# Agent 原生项目工作区 (/docs/architecture/agent-workspace)

## 一个 Agent 进入项目后，需要知道什么 [#一个-agent-进入项目后需要知道什么]

目标是什么、当前方案是哪一版、已有证据在哪里、哪些任务可以执行、哪些事情需要人参与，以及上次工作停在哪里。

这些信息来自业务记录和工作区清单。聊天历史只是交互记录之一。

## 候选文件结构 [#候选文件结构]

下面是便于人和 Agent 阅读、交换的工作区示意。它尚未固定为正式文件协议。

```text
project/
  project.yaml          项目身份、工作区版本、当前基准
  briefs/               需求与设计基础的可读快照
  research/             问题、假设、下一步计划
  experiments/          实验清单与原始文件引用
  models/               工艺与仿真模型文件
  analyses/             数据处理脚本、笔记、图表
  skills/               当前项目启用的工作方法及版本
  assets.lock.yaml      本项目引用的资产版本
  proposals/            待审阅变更
  runs/                 Agent 与工具的执行记录
  deliveries/           发布包清单与导出文件
```

数据库负责结构化记录和协作状态，文件存储负责原始资料及产物，工作区提供可读写入口。一个文件夹不承担所有并发协作和权限判断。

## Agent 可以怎样修改 [#agent-可以怎样修改]

- 新建分析脚本、研究笔记和工作文件。
- 通过工具接口创建实验计划、工况或变更提案。
- 编辑受支持的交换文件，再由导入接口校验并生成业务变更。
- 查看差异、修正错误、提交可被工程师审阅的结果。

直接改动文件不会自动覆盖数据库里的正式实验事实。导入需要识别对象、基准版本、单位和来源，并给出明确结果。

## MCP 提供什么 [#mcp-提供什么]

MCP 是 Agent 调用能力的一种标准接入方式。模块先提供稳定业务接口，再暴露为查询和动作工具。

示例工具语义：查询证据、读取工况、创建实验计划、运行仿真、提交变更、获取任务状态。这里没有确定正式 API 路径或参数协议。

长任务返回任务编号。工具超时后先查询执行状态，再决定是否重试；同一个提交标识重复请求不会生成两次实验或重复发布。

## Skills 提供什么 [#skills-提供什么]

Skills 保存有版本的工作方法：适用问题、所需输入、步骤、调用工具、检查点和输出要求。工程模板与计算模型保存在资产库，由 Skill 引用。

例如“拟合分离效率”这个 Skill，需要说明哪些实验条件可比较、使用哪个分析程序、怎样检查拟合质量，以及结果适用范围如何表达。

业务规则和权限由系统执行，不能只写在提示词中。

## 人如何介入 [#人如何介入]

人可以暂停任务、补充输入、锁定参数、修改计划或局部接受提案。恢复时校验此前引用版本是否变化，必要时重新计算。

资料、文献和客户附件被当作证据读取。它们不能改变 Agent 的授权范围，也不能替代工程师的明确决策。

完整执行机制见 [Agent 与工具运行时](/docs/subsystems/agent)，持续改进机制见[研究规划与迭代](/docs/subsystems/research)。