内置工具

AweeClaw 内置工具是平台自带、无需额外开发的工具。声明式场景通过 capabilities.builtinTools 声明可用工具，运行时由 BuiltinToolRegistry 校验白名单。

白名单来源：src/scenario-system/core/BuiltinToolRegistry.ts → AVAILABLE_BUILTIN_TOOLS（共 29 个）
白名单语义是「允许声明式场景引用的内置工具集合」，其中 5 项数据类工具为预留能力 （有工具描述、无执行器），由 isAvailable() 通过 toolRegistry.has() 二次校验兜底拒绝。
工具定义：src/shared/configuration/toolDefinitions.ts
构建器可选值：SCENARIO_ICON_OPTIONS 同级的 BUILTIN_TOOL_OPTIONS（scenarioOptionCatalog.ts）
权限校验：见权限声明

可用性的三层过滤

场景声明的内置工具最终是否真的暴露给模型，需按顺序通过三层过滤，任一层未通过即不可用：

顺序	过滤层	来源	未配置时的行为
1	场景白名单	`capabilities.builtinTools`	非声明式场景不适用
2	自定义智能体白名单	智能体配置的 `builtinTools`	未配置 → 放行
3	套餐能力组白名单	后端套餐 `features.allowedToolGroups`	未配置 → 全放行

套餐能力组把工具按功能划分为 8 组：文件读写 / 代码智能 / 终端命令 / 网络检索 / 多模态与图表 / 记忆与知识 / 任务与自动化 / 伴侣与交互。

组定义与工具归属的唯一真相：aweeclaw-backend/src/modules/payment/tool-catalog.ts
客户端镜像：src/shared/configuration/toolCategoryDefs.ts 的 CAPABILITY_GROUPS （两侧必须逐项对齐，否则会出现「后台勾了却用不了」的错位）
系统必需工具（extract_document / ask_user / todo_write / send_file_to_channel）任何套餐均放行
目录未登记的工具（MCP / 场景自定义工具 / 插件 / 外部智能体）不受此层限制

场景工具本身不受套餐能力组限制：capabilities.customTools 与场景运行时注册的 scene_tools_* 不属于内置工具，场景即购买凭证，不会被套餐二次限制。但 capabilities.builtinTools 中声明的内置工具仍受第 3 层约束 —— 低套餐用户激活场景后可能拿不到声明的工具，场景开发时不要假设「声明即一定可用」，需对工具缺失做降级处理。

可用工具列表

「权限要求」一列来自 PermissionGuard 的工具映射表；标注 — 表示无需声明权限（默认放行的安全工具）。

文件操作

工具名	说明	权限要求
`read_file`	读取一个或多个文件	`filesystem:read`
`write_file`	创建新文件或整文件重写	`filesystem:write`
`edit_file`	局部修改已有文件（字符串/行/批量模式）	—
`list_directory`	列出目录内容	`filesystem:read`
`search_files`	按文本/正则搜索文件内容	`filesystem:read`
`create_file_or_folder`	创建文件或目录	`filesystem:write`
`delete_file_or_folder`	删除文件或目录（需审批）	`filesystem:write`

write_file 只能用于新建文件或整文件替换；对已有文件做局部修改必须用 edit_file，否则会被文件写入策略层拒绝。

代码分析

工具名	说明	权限要求
`codebase_search`	语义检索代码库	`filesystem:read`
`get_lint_errors`	获取 TypeScript / ESLint 诊断	—
`find_references`	查找符号引用	—
`go_to_definition`	跳转到符号定义	—
`get_hover_info`	获取类型信息与文档	—
`get_document_symbols`	列出文件内的符号结构	—

终端执行

工具名	说明	权限要求
`run_command`	执行 Shell 命令（需审批）	`terminal:execute`
`read_terminal_output`	读取后台终端输出	`terminal:execute`
`send_terminal_input`	向运行中的终端发送输入	`terminal:execute`
`stop_terminal`	终止终端进程	`terminal:execute`

Git 版本控制

要求工作区本身是 Git 仓库：非仓库时工具会返回明确提示（引导初始化），不会误报为命令执行失败。只读工具在 chat / agent / plan 模式均可用；git_commit、git_branch、git_sync、 git_worktree、git_audit 仅在 agent / plan 模式暴露，并受「设置 → Git → AI 版本控制能力」各开关约束（提交与分支 / 远程同步 / 隔离工作区 / 审计封存，共四项）。

工具名	说明	权限要求
`git_status`	仓库状态：分支、领先/落后、暂存/未暂存/未跟踪、冲突、进行中的操作	`filesystem:read`
`git_diff`	差异查看：工作区 / 暂存区 / 指定提交 / 分支对比（可只取统计）	`filesystem:read`
`git_log`	提交历史（支持按文件、分支、关键字过滤）	`filesystem:read`
`git_commit`	暂存并提交（需审批，自动应用场景提交前缀；合规场景自动补审计封存）	`terminal:execute`
`git_branch`	分支列表 / 创建 / 切换 / 重命名 / 合并 / 删除（需审批）	`terminal:execute`
`git_sync`	远程同步 `pull` / `push` / `fetch` / `clone`（需审批）	`terminal:execute`
`git_worktree`	链接工作树管理：`list` / `add` / `remove` / `prune`，用于并行任务隔离（需审批）	`terminal:execute`
`git_audit`	审计轨迹封存：提交待提交变更并打带注记的审计 tag；`seal` / `list` / `verify`（需审批）	`terminal:execute`

并行隔离（git_worktree）：工作树目录只允许建在工作区的同级目录下（传相对名即可，如 path="myrepo-spike"），避免写进仓库内部污染 git status。同一分支不能被两个工作树同时检出，需并行时用 create_branch=true 新建分支。默认关闭，需在「设置 → Git」中显式开启。

审计封存（git_audit）：seal 会先把待提交变更按场景提交约定提交，再对 HEAD 打带注记 tag（默认 audit-<时间戳>）。注记内容参与 tag 对象自身哈希，因此事后移动 tag 或改写注记都会导致 verify 失败 —— 这是「不可篡改轨迹」的最小充分条件。封存后不应再做 amend / rebase。此外，legal / medical 场景（SCENARIO_COMMIT_CONFIGS.auditTrail === true）下 git_commit 成功后会自动补一次封存，避免「合规场景提交了却没留痕」。

凭证处理：远程要求认证而凭证缺失或已过期时，客户端弹出账号密码 / Token 输入框，用户填写后自动重试；勾选「记住凭证」则由主进程用系统级加密（safeStorage）保存到本机。凭证明文只在主进程内存与 git 子进程环境中短暂存在，不会进入模型上下文。用户取消或 120 秒无响应时，git_sync 返回「已取消」，AI 不应重复尝试。

网络

工具名	说明	权限要求
`web_search`	联网搜索	`network:request`
`read_url`	读取网页内容	`network:request`

数据处理（预留）

以下 5 个工具的说明已在 toolDefinitions.ts 中定义，但 toolExecutors.ts 尚未实现执行器，toolRegistry.has() 返回 false —— isAvailable() 会拒绝，声明后也拿不到工具。它们同时登记在 toolPacks.ts 的 ToolPack.reservedTools 与构建器选项表的 reserved: true 标记中，见下文「预留工具」。

工具名	说明	状态
`sql_query`	执行 SQL 查询	预留（无执行器）
`data_transform`	数据转换与清洗	预留（无执行器）
`csv_analyze`	CSV 数据分析	预留（无执行器）
`chart_generate`	生成图表	预留（无执行器）
`statistical_test`	统计检验	预留（无执行器）

知识检索

工具名	说明	权限要求
`knowledge_search`	检索项目知识库	—

交互与记忆

工具名	说明	权限要求
`ask_user`	向用户提问（结构化选项）	—
`todo_write`	维护任务清单	—
`remember`	持久化项目事实与偏好	—
`companion_control`	控制桌面伴侣（动作/表情/说话）	—

预留工具（尚未接入执行器）

预留工具分三处登记，都不会进入 LLM 工具列表与系统提示词：

所在路径	涵盖工具	兜底机制
`ToolPack.reservedTools`（工具包，共 17 项）	`data`：`sql_query`、`data_transform`、`csv_analyze`、`chart_generate`、`statistical_test`、`rest_api`；`media`：`image_generate`、`image_edit`、`audio_transcribe`、`video_analyze`；`office`：`doc_write`、`spreadsheet`、`presentation`、`email_send`；`web`：`web_scrape`、`api_call`、`browser_automate`	不参与 `resolveTools()` 解析，直接不进工具列表
`AVAILABLE_BUILTIN_TOOLS` 白名单内（上述 `data` 的 5 项，不含 `rest_api`）	`sql_query`、`data_transform`、`csv_analyze`、`chart_generate`、`statistical_test`	`isAvailable()` 二次校验 `toolRegistry.has()` → `false`
`BUILTIN_TOOL_OPTIONS` 的 `reserved: true`（构建器 UI 选项，共 5 项）	上述 `data` 的 5 项	UI 显示「未实现」徽标并禁止勾选，从入口杜绝静默失效

其中 rest_api、web_scrape、api_call、browser_automate 连工具描述都尚未补齐。

构建器侧行为：ScenarioConfigEditor 的 MultiSelectPicker 会将 reserved: true 的选项置灰并禁止勾选（悬停显示「该工具尚未实现执行器，暂不可用」）；历史配置中已勾选的预留项以警示色展示、可手动移除 —— 因此不会再出现「勾选了却拿不到工具」的静默失效。

执行器补齐后，需同时完成四件事才会生效：
在 toolExecutors.ts 实现执行器；
把工具名从 ToolPack.reservedTools 移入所属工具包的 tools；
确认其在 AVAILABLE_BUILTIN_TOOLS 白名单内；
移除 BUILTIN_TOOL_OPTIONS 中该项的 reserved: true 标记。
tests/unit/shared/toolPacks.integrity.test.ts 会校验上述状态一致性：
tools 与 reservedTools 不得重叠，已有执行器的工具不得继续留在 reservedTools；
构建器 UI 中可勾选（未标 reserved）的工具必须同时具备工具定义与执行器；
已标 reserved 的工具不得已有执行器（实现后须移除标记）。

使用方式

声明式场景

在 scenario.json 的 capabilities.builtinTools 中声明：

json

{
  "capabilities": {
    "builtinTools": [
      "read_file",
      "write_file",
      "search_files",
      "web_search",
      "ask_user",
      "remember"
    ]
  }
}

编程式场景

编程式场景按工具包批量启用（见下节）：

typescript

getPlugin() {
  return {
    capabilities: {
      toolPacks: ['code', 'data'],
    }
  }
}

工具包（Tool Packs）

工具包是工具的逻辑分组，由 toolPackRegistry 注册，场景通过 capabilities.toolPacks 引用；依赖包会自动解析。

工具包 id	名称	依赖	说明
`code`	代码工具	—	文件操作、终端、代码分析、网络、记忆与交互工具（已接入执行器）
`data`	数据工具	`code`	数据库查询、数据转换、统计分析（全部预留，见下文「预留工具」）
`web`	网页工具	`code`	网页抓取、API 调用、浏览器自动化（全部预留）
`media`	媒体工具	`code`	图像生成/编辑、音频转录、视频分析（全部预留）
`office`	办公工具	`code`	文档、表格、演示文稿、邮件（全部预留）
`education`	教育工具	`code`	学科、知识点、测验、学习计划、错题本等（执行器由场景项目注册）
`store-diagnosis`	门店诊断工具	`code`	门店管理、诊断分析、报告与优化规划（执行器由场景项目注册）

toolPacks 中声明的 id 必须是已注册的工具包。未注册的 id 会被 resolveDependencies() 跳过并输出告警；可用 toolPackRegistry.findUnknownPacks(packIds) 在加载 / 构建期提前拿到完整非法列表。

完整工具清单与可用性说明见 ScenarioCapabilities。

权限要求

工具包只负责「启用哪些工具」，是否能执行仍取决于场景是否声明了对应权限：

json

{
  "permissions": ["filesystem:read", "filesystem:write", "network:request"]
}

未声明对应权限时，工具调用会被 PermissionGuard 拒绝并返回明确原因。详见权限声明。

详见权限声明。

内置工具 ​

可用性的三层过滤 ​

可用工具列表 ​

文件操作 ​

代码分析 ​

终端执行 ​

Git 版本控制 ​

网络 ​

数据处理（预留） ​

知识检索 ​

交互与记忆 ​

预留工具（尚未接入执行器） ​

使用方式 ​

声明式场景 ​

编程式场景 ​

工具包（Tool Packs） ​

权限要求 ​