# Tools、Workspace 与产物

## Tool 契约与统一 Gateway

**实现阶段：P2**

- 定义 Tool 名称、说明、参数 Schema、结构化结果和错误协议。
- 支持注册、列出、调用和取消 Tool，并将所有调用纳入 Run Context。
- 在统一 Gateway 中触发基础 Hook、日志和输出事件。

## Workspace 作用域与路径解析

**实现阶段：P2**

- 为 Task 和 Project 解析工作区根目录与当前工作目录。
- 统一处理相对路径、绝对路径、符号链接和工作区外路径。
- 将 Tool 产生的实际文件与 `.agent/` 元数据明确区分。

## 文件操作 Toolset

**实现阶段：P2**

- 支持目录浏览、文件读取、文本搜索、写入、补丁、移动、复制和创建目录。
- 处理编码、大文件、二进制文件和修改冲突。
- 返回适合模型继续工作的结构化摘要，同时保留完整结果入口。

## Shell 与进程 Toolset

**实现阶段：P2**

- 执行 Shell 命令，流式返回 stdout/stderr、退出码和耗时。
- 支持超时、取消、工作目录、环境变量和基础后台进程处理。
- 将模型临时生成的命令或脚本文本记录进 Run，不额外建立脚本库。

## Tool 进度与产物收集

**实现阶段：P2**

- 统一表达 Tool 开始、进度、完成、失败和取消。
- 自动识别测试报告、截图、下载文件和其他可预览产物并关联到 Run。
- 支持产物查看、固定、导出和后续 Tool 引用。

## 交互式终端会话

**实现阶段：P4**

- 使用 PTY 运行需要持续输入、终端控制序列或长时间驻留的命令。
- 允许 Agent 与用户查看会话、发送输入、转入后台、重新连接和终止进程。
- 将交互式会话与普通 Shell Tool、Run 日志和资源回收统一管理。

## Tool 能力范围与分组

**实现阶段：P4**

- 按 Profile、Space 和 Behavior 选择向模型暴露的 Tool 集合。
- 支持 Tool 别名、分组、描述优化和能力发现，避免一次向模型暴露过多接口。
- 为权限策略和不同平台能力降级提供统一元数据。

## 外部 Tool 协议接入

**实现阶段：P4**

- 通过 Adapter 接入 MCP 等外部 Tool 服务，将其映射到统一 Tool 契约。
- 管理服务连接、能力同步、错误转换和生命周期。
- 外部 Tool 与内置 Tool 使用一致的日志、确认和 Run 关联。