llm-to-agent/docs/features/tools-execution.md

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 关联。