工具系统

Coding Code 的工具系统是 Agent 与外部世界交互的核心机制。本文档介绍内置工具、加载机制、自定义工具开发和沙箱隔离。

内置工具

文件操作 (fs)

工具	功能	关键参数
`read_file`	读取文件内容	`path: string`（文件路径），`offset: number`（起始行，默认 1），`limit: number`（行数，默认 200，最大 500）
`write_file`	写入/创建文件	`path: string`，`content: string`
`edit_file`	编辑文件中的特定代码段	`path: string`，`old_string: string`（被替换的文本，至少 1 字符），`new_string: string`（替换后的文本）
`search_code`	正则搜索项目代码	`pattern: string`（正则表达式），`glob: string`（文件匹配模式，默认 `*/`），`max_results: number`（默认 30，最大 100）
`search_files`	模式匹配查找文件	`pattern: string`（glob 模式），`path: string`（搜索目录，默认 `.`），`max_results: number`（默认 50，最大 500）

命令执行

工具	功能	关键参数
`execute_command`	执行 shell 命令	`command: string`，`cwd: string`（可选，工作目录），`timeout_ms: number`（超时毫秒，默认 30000）

网络

工具	功能	关键参数
`fetch_url`	HTTP GET 请求	`url: string`（合法 URL），`max_length: number`（最大响应长度，默认 100000，最大 500000）
`web_search`	Web 搜索	`query: string`，`max_results: number`（默认 8，最大 20）

代理状态

工具	功能	关键参数
`todo_write`	修改代理的任务列表	`plan: Array<{ step: string, status: 'pending' \| 'in_progress' \| 'completed' }>`（最大条目数有限制）

子智能体

工具	功能	关键参数
`dispatch_agent`	将任务委派给运行时注册的子智能体	`agent: string`, `prompt: string`

工具加载机制

工具按加载时机分为两类：

Core 工具：始终可用，在启动时注册。包括上述所有内置工具。
MCP 工具：从 MCP 服务自动导入和注册。名称空间化为 serverName:toolName 格式，避免不同服务间的工具名冲突。

Agent 在一次运行开始时注册内置工具、项目 MCP 工具和 dispatch_agent。plan 模式通过独立的 PLAN_MODE_ALLOWED_TOOLS 策略过滤工具。

自定义工具

工具通过 ToolService 注册，每个工具实现 ToolDefinition 接口：

interface ToolDefinition {
  name: string;
  description: string;
  parameters: z.ZodTypeAny;         // Zod schema 定义参数
  execute: (args: unknown, ctx?: ToolExecCtx) => Effect.Effect<string, AgentError, never>;
}

interface ToolExecCtx {
  signal?: AbortSignal;    // 取消信号
  sessionId?: string;      // 当前会话 ID
  turnId?: number;         // 当前轮次
  projectPath?: string;    // 项目路径
}

execute 保留在 ToolDefinition 中，因为执行器需要通过同一个定义完成参数校验、审批、取消和 hook，再调用工具的实际实现。ToolExecCtx 中，signal 用于取消；sessionId 用于会话级工具状态和子智能体关联，projectPath 用于限定工作目录，turnId 只用于执行 hook 的轮次追踪。

在 cli.ts 中向 ToolService 注册新工具，Agent 会自动将其暴露给 LLM。

工具可见性策略

通过 ToolVisibilityPolicy 控制工具的可见性：

interface ToolVisibilityPolicy {
  allowedTools?: Set<string>;        // 允许的工具白名单
  allowedMcpServers?: Set<string>;   // 允许的 MCP 服务白名单
}

沙箱隔离

所有工具执行经过两层安全保护：

审批流水线（始终生效）

六层决策链，按顺序执行，任一层返回 deny/allow 即终止：

层级	名称	逻辑
1	RuleEngine	规则引擎匹配，支持 glob 模式匹配工具名和参数，按优先级排序
2	ReadonlyWhitelist	只读工具自动放行（read_file, search_code, search_files, fetch_url, web_search, dispatch_agent, todo_write）
3	PermissionMode	权限模式判断：`bypass`（全部放行）、`acceptEdits`（非破坏性工具放行）、`default`（继续下一层）。`plan` 模式由独立的 `agent/mode.ts` 中的 `planModeGateHook` 在 Layer 4 强制，不在此层处理
4	HookPreToolUse	钩子决策，可返回 allow/deny/ask/continue，支持 `modifiedInput` 修改参数
5	UserConfirmation	异步用户确认，支持 allow/deny/always/never 四种响应，always/never 会持久化为规则
6	AuditLog	每一层决策后记录审计日志，通过 `tool.approval.post` 钩子发出

预设安全规则

系统内置 9 条默认规则（不可删除）：

规则	动作	说明
`rm -rf /`	deny	禁止递归删除根目录
`sudo`	deny	禁止提权执行
`curl \| sh`	deny	禁止管道执行远程脚本
`chmod u+s`	deny	禁止设置 SUID 位
`shutdown`	deny	禁止系统关机
`/etc/shadow`	deny	禁止读取影子密码文件
`/etc/passwd`	deny	禁止读取系统密码文件
`.ssh`	ask	访问 SSH 目录需确认
`.env`	ask	访问环境变量文件需确认

权限模式

type PermissionMode = 'default' | 'acceptEdits' | 'bypass';

default：逐层审批，危险操作需用户确认
acceptEdits：非破坏性工具自动放行，减少确认弹窗
bypass：全部放行，跳过所有审批（慎用）

plan 不再是 PermissionMode 的成员。plan 模式通过 AgentProfile.name === 'plan' 结构化识别，由 agent/mode.ts 的 planModeGateHook 和 PLAN_MODE_ALLOWED_TOOLS 共同限制工具。

OS 级沙箱（预留）

packages/codingcode/src/sandbox/ 目前是 stub 实现（SandboxService 为空类），尚未集成实际的沙箱运行时。审批流水线已提供基本安全保障，OS 级沙箱将在未来版本中实现。

FilesExpand file tree

tools.md

Latest commit

History