内置工具

工具能力全部来自 @ai-zen/agents-sdk（BUILTIN_TOOL_CLASSES，共 20 种）与 SDK 的动态加载机制。CLI 本身不新增工具类，只负责组装路径、构建 Scope 单例，并把工具目录与 MCP/Skill 相关路径传给 SDK。

20 种内置工具

这些工具由 SDK 静态注册表 discoverBuiltinTools 实例化，装配时不做任何过滤（发现阶段无条件注册全部），其可用性由各工具自行声明（isAvailable）。

工具	说明
`cwd`	获取当前工作目录
`read`	读取文件内容（支持 `range` 分批读取）
`inspect_file`	勘察文件结构概况（行数、字符数、列宽分布、行尾风格），不读取内容
`write`	写入文件内容
`edit`	在文件中替换文本（单次替换）
`batch_edit`	批量替换文件中的文本
`exec`	执行 Shell 命令
`spawn`	异步执行 Shell 命令（立即返回）
`mkdir`	创建目录
`rm`	删除文件或目录
`glob`	用 glob 模式扫描文件
`ls`	列出目录内容
`exist`	检查路径是否存在
`find_text`	在文件中检索文本
`download_file`	从 URL 下载文件
`rename`	重命名或移动文件/目录
`copy`	复制文件或目录
`sleep`	等待指定毫秒数
`view_image`	查看/分析图片（仅视觉模型可用）
`generate_image`	根据文字描述生成图片

视觉与图片工具的可用性

view_image：仅对视觉模型启用。isAvailable(config, definition) 从 definition.modelId 解析当前模型并检查 Model.vision，因此非视觉模型不会拿到该工具（无需运行时重复校验）。
- 输入 path_or_url：http(s) URL 直接以 image_url 内容块返回；本地路径自动通过 Files API（DeepSeek）上传，以 file 内容块（file_id）返回。不使用 base64 内联。
generate_image：依赖配置中的 imageModels 与 defaultImageModel，未配置时由 isAvailable 过滤掉。统一返回字符串（JSON，含图片 URL 列表 + view_image/download_file 提示），而不是强制返回图片内容块。

具体字段名、声明与返回类型均以 SDK 的 .d.ts 为准（如 ViewImageTool / GenerateImageTool）。

输出保护（`maxToolOutput`）

工具返回给模型的内容超过 maxToolOutput（AppConfig 配置项，缺省 32768 字符）时，SDK 不再原样回传，而是给出警告与预览，以免单次工具结果撑爆上下文：

落盘并警告：exec（stdout / stderr 分文件落盘）、find_text、glob、ls 超限时写入 <系统临时目录>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/（每次调用独立目录），返回警告 + 头部预览（exec 为各流头尾各 1000 字符）与统计信息，并提示缩小范围的方式；
仅警告不落盘：read 超限时提示改用 range 分批读取；inspect_file 的明细超限时仅返回概况与提示。

maxToolOutput 为 CONFIG 层配置项，不暴露为工具参数，亦不支持按 Agent 覆盖。

5 种动态加载工具

除内置工具外，SDK 还提供动态加载工具，依据可用资源与权限按需注册：

工具	用途
`load_skill`	加载 Skill 文档到上下文（幂等，重复调用跳过重复注入）
`call_skill_sub_agent`	将任务委托给 Skill 子 Agent（仅对 frontmatter 含 `sub-agent: true` 的 Skill 生效）
`load_mcp`	连接 MCP 服务器并列出其工具（幂等，重复调用跳过重复连接）
`call_mcp_tool`	在已连接的 MCP 服务器上调用某个工具
`read_mcp_resource`	读取已连接 MCP 服务器的资源

这些工具分别由 SDK 的 createLoadSkillTool / createCallSkillSubAgentTool、createLoadMcpTool / createCallMcpTool / createReadMcpResourceTool 创建。

子 Agent 工具

SDK 的 createSubAgentTool 会把带 function 字段的 Agent 注册为可被其他 Agent 调用的工具（SubAgent）。它使用延迟构建（AgentToolLazy）以避免工具列表构建阶段的递归创建问题。子 Agent 拥有独立的权限，不与父 Agent 继承权限。

工具装配流水线

工具通过 SDK Scope 的能力流水线分三个阶段装配：

发现（Discovery）：扫描文件系统，发现内置工具、用户工具、SubAgent、Skill 与 MCP 服务器。20 种内置工具无条件注册（本阶段不过滤）。
过滤（Filtering）：应用权限（allow/deny）、安全排除（递归保护）以及每个工具自行声明的 isAvailable(config, definition)。可用性在模型已知的构建期决定，例如 view_image 仅视觉模型可用、generate_image 需配置 defaultImageModel。
实例化（Instantiation）：将过滤后的名称映射到 Tool 实例，并注册动态加载器。

权限模型

AgentPermissions 定义了四个维度的权限（来自 SDK 类型）：

typescript

interface AgentPermissions {
  tools?: { allow: string[] } | { deny: string[] };
  skills?: { allow: string[] } | { deny: string[] };
  mcps?: { allow: string[] } | { deny: string[] };
  subagents?: { allow: string[] } | { deny: string[] };
}

规则要点：

缺失 permissions 字段 = 所有维度全部拒绝（deny: ["*"]）。
每个维度要么用 allow（白名单），要么用 deny（黑名单），二者互斥。
"*" 通配符匹配任意名称。
被拒绝的资源对 LLM 完全不可见（不仅是调用被阻断）。
每个 Agent 拥有独立的权限，父子 Agent 之间不继承。
唯一例外：call_skill_sub_agent 创建的临时 Skill 子 Agent，作为一次性的对话代理沿用调用者的工具能力（不再走第二遍权限过滤），而不是独立实体。

内置工具 ​

20 种内置工具 ​

视觉与图片工具的可用性 ​

输出保护（maxToolOutput） ​

5 种动态加载工具 ​

子 Agent 工具 ​

工具装配流水线 ​

权限模型 ​