拆解 Agent 内置工具链：Denova filesystem、shell 与 task 工具设计指南

Denova 是一个面向小说写作与 AI 角色扮演游戏的 AI 创作平台，它的 Agent 能直接读取项目文件、执行 shell 命令、委派子任务。这篇文章带你完整拆解 Denova 内置工具链中 filesystem、shell 与 task 三大工具组的设计与实现：每个工具的输入边界、结果如何压缩回模型上下文、以及权限与恢复机制如何兜底，帮助你理解一个生产级 Agent 工具链是怎么搭出来的。

一、先看全景：内置工具从哪里来

所有模型可见的工具都集中在 agent/tool/builtin/ 包中。包注释（doc.go）用文件命名把职责划分得很清楚：

📌 工具不是零散注册的，而是通过 toolset_builders.go 中的Workspace、Shell、Tasks等构建函数按“能力组”打包。例如Workspace会根据访问模式装配read、glob、grep，读写模式下再追加write、edit；Shell则按平台自动选择 bash 或 pwsh。每个工具都携带一个由配置摘要计算的稳定Identity，用于缓存与能力校验——这是整个工具链可测试、可换实现的基础。

二、filesystem 工具：read、glob、grep、write、edit 五件套

read：一个工具，多种适配器

read的设计很巧妙：模型只看到一个工具，背后是一组ReadAdapter（read_tool.go）。本地文本文件、目录结构、甚至图片都通过各自的适配器路由，每个适配器自带精确的参数 schema 并在选中后二次校验。结果统一为带行号、分页游标（offset/limit/total）的有界内容，避免大文件撑爆上下文。

glob 与 grep：发现文件、搜索内容

两者定义在 filesystem_search_tools.go：

• glob：回答“哪些路径匹配这个模式”，一次可传多个文件/目录/glob 模式，结果去重并有数量上限，支持cursor翻页；
• grep：直接使用 ripgrep 语法（如rg -n 'TODO|FIXME' agent internal），但从不经过 shell——只解析 Denova 支持的rg字面语法，杜绝了命令注入风险。

两者共享SearchResult结构：条目列表 + 截断标记 + 下一页游标 + 警告，把本地进程细节挡在模型可见接口之外。

write 与 edit：可审阅的原子修改

写操作通过MutationAdapter注入（workspace_mutation_tools.go），产品层负责审阅历史、并发控制与结构化回执：

• write：整体替换一个文件，内容上限 16 MiB；
• edit：基于同一份原始快照做多条精确替换（old_string/new_string），任一匹配失败则整个文件不动，保证原子性；也支持operation=delete删文件。

这就是为什么 Denova 的 Agent 改稿后，你能在工作台里逐文件“撤销整组 / 审阅”——变更都是可回放、可审计的结构化操作。

三、shell 工具：bash 与 pwsh 的受控执行

shell 工具定义在 shell_tools.go，核心是一个CommandRunner接口，本地实现见 shell_local_runner.go。值得学习的设计点：

1. 结构化状态而非裸错误：结果分为success/failed/cancelled/timed_out四类。命令退出码非零是“预期的结构化结果”，模型能据此自我修正，而不是一次不透明的报错；
2. 明确的恢复建议：失败会附带recovery提示，比如超时时建议“缩小命令或显式调大timeout_seconds”；
3. 输出必有界：结果先序列化一个 JSON 信封（状态、退出码、工作目录、截断标记），剩余预算才给 stdout/stderr；超长输出会截断并落为 artifact（完整产物文件），模型只拿到可读路径和大小；
4. 安全上限：命令正文最大 1 MiB、环境变量 128 项 / 64 KiB，可选 PTY 与超时；PowerShell 引擎会显式报告是 pwsh 还是 Windows PowerShell 兜底。

四、task 工具：send、await 与 list_agents

task 工具组定义在 agent_send.go，一次send最多携带 32 条操作，每条独立成败：

几个关键约束体现得淋漓尽致：

• 回执 ≠ 完成：delegate返回 receipt 只表示命令被持久化受理，结果通过完成邮箱（mailbox）自动送达，父 Agent 应“继续做独立工作”而不是忙等；
• await 只用于真实依赖：task_wait_tool.go 的await等待 1~32 个目标，timeout_ms=0表示只读一次有界状态，就绪指“完成、暂停或交互边界”，而非成功；
• 冷重启可恢复：本地执行器 task_local_executor.go 不维护权威任务表，TaskRef（agent/session/run）足以在进程重启后重新打开子会话并挂回 Run。

五、三条贯穿始终的设计哲学

1. 边界先行：命令 1 MiB、文件 16 MiB、工具结果统一MaxResultBytes有界投影——模型上下文永远不会被单次输出打爆；
2. 接口即契约：ReadAdapter、CommandRunner、MutationAdapter、TaskExecutor都是宿主可替换的接缝，工具层只管模型可见语义，宿主注入本地或远程实现；
3. 失败可恢复：结构化状态 +recovery建议 + 幂等键（idempotency_key），让模型和用户都有明确的下一步。

想动手体验，可以直接阅读 agent/README.md 中“完整组合”示例：tools.Workspace+tools.Shell+tools.Tasks三行代码即可装配出本文拆解的完整工具链。理解这些内置工具的设计，也帮你为自己的 Agent 产品设计出同样稳健的工具边界。