工具与工具集
Tools 是 Anyy 在某一轮里可以暴露给模型调用的函数。Toolsets 是这些工具的命名分组，
用于让工具列表保持聚焦，例如 web、memory、terminal、messaging、subagents、
mcp-docs。
Toolsets 控制可见性，不是权限边界。工具可见后，它自己的 risk class、approval policy、 execution policy、output budget、timeout 和 audit category 仍然生效。文件写入、shell 命令、connector mutation、桌面控制和配置变更仍然会走对应审批或 ChangePlan 路径。
可用工具
需要查看当前 runtime 的精确列表时，请使用本地 catalog：
| 位置 | 显示内容 |
|---|---|
/tools | 按 source、descriptor、risk、policy 展示模型可见工具。 |
/toolsets | Runtime toolsets、各自的工具，以及哪些 toolsets 默认可见。 |
Dashboard /dashboard/tools | 工具详情，以及 timeout、output budget 等资源限制。 |
底层 RPC method 是 tools.list，结果包含 tools、toolsets 和 default_toolsets。
Dashboard 有意不编辑 risk、approval_policy、execution_policy 或 enabled
等安全策略字段；这些字段需要通过经过 review 的配置变更修改。
高层分类：
| 类别 | Toolsets | 示例 |
|---|---|---|
| Web 与召回 | web、sessions | web_search、web_fetch、web_extract、session_search。 |
| Memory 与任务 | memory、tasks、automation | memory、task_create、automation_create、automation_history。 |
| 消息 | messaging | messaging_status、message_receipt、notify_user、send_message。 |
| 文件与主机操作 | file、terminal | read_file、patch、bash、process。 |
| Skills 与委托 | skills、subagents、clarify | skills_list、skill_view、skill_manage、delegate_task、background_job、clarify。 |
| 媒体与 artifacts | tts、media_generation、artifact | text_to_speech、image_generate、artifact_list、artifact_inspect。 |
| 可选 connectors | email、calendar、computer_use、mcp-<server> | Email/calendar connector 工具、桌面控制和 MCP 工具。 |
权威分组列表见工具参考。
内置工具集
新的 profile 会使用以下内置默认可见列表，除非配置了 toolsets.default：
toolsets:
default:
- web
- sessions
- memory
- tasks
- automation
- clarify
- file
- messaging
- skills
- subagents
- terminal
- tts
| Toolset | 作用 |
|---|---|
web | 搜索和读取公共 web 内容。 |
sessions | 搜索历史 session 内容。 |
memory | add、replace 或 remove 结构化长期记忆。 |
tasks | 管理持久个人任务。 |
automation | 管理模型可见的 automations 和 reminders。 |
clarify | 缺少信息时向用户提问。 |
file | 读取、写入、搜索和 patch workspace/local 文件。 |
messaging | 报告渠道状态并发送用户可见消息。 |
skills | 当 skill management 可用时，列出、查看、reload 和管理 skills。 |
subagents | 委托有边界的 child work，并管理 child/background agent runs。 |
terminal | 执行 shell 命令并管理 Anyy process jobs。 |
tts | 配置 TTS 后生成 speech artifacts。 |
email、calendar、media_generation、computer_use、artifact、browser、mcp-browser
和 mcp-<server> 等可选工具集，只会在对应 connector、service、setup command 或 turn metadata
激活时出现。
使用工具集
本构建没有单独的 anyy tools 或 anyy toolsets enable CLI。Toolsets 由配置、
session metadata、turn metadata、setup flows 和 runtime 条件选择。
常见路径：
| 需求 | 路径 |
|---|---|
| 修改新 session 的默认 toolsets | 编辑 config.yaml 中的 toolsets.default。 |
| 查看当前 runtime catalog | 使用 /tools、/toolsets 或 /dashboard/tools。 |
| 添加 MCP server 的已选工具 | 使用 anyy mcp add ... --activate-toolset 或 anyy mcp configure ... --activate-toolset。 |
| 启用本地 Mac 桌面控制 | 使用 anyy computer-use enable。 |
| 限制定时 automation run 的工具 | 创建 cron job 时使用 --toolsets 选项。 |
提交配置时推荐 YAML list：
toolsets:
default:
- web
- sessions
- memory
- messaging
新 session 会把配置的 profile toolsets 复制到 session metadata。已有 session 保留自己已经存储的列表；
修改 toolsets.default 不会改写它们。
工具治理
每个 tool descriptor 包含：
| 字段 | 含义 |
|---|---|
toolset | 工具出现前必须被选中的可见性分组。 |
risk | read、runtime-low、runtime-high、config-low、config-high、credential-high、dangerous 或 force-required。 |
approval_policy | none、hook 或 always。 |
execution_policy | direct、audit、confirm、change_plan 或 force_change_plan。 |
output_budget | Visible 和 stored 结果字符上限。 |
timeout_ms | 工具执行 timeout。 |
audit_category | 需要记录时写入的 audit stream。 |
tool_governance.overrides 可以调整 built-in 或 MCP 工具，而不改变它所属的 toolset：
tool_governance:
overrides:
- source: builtin
name: bash
timeout_ms: 60000
output_budget:
visible_chars: 8000
stored_chars: 200000
- source: mcp:docs
name: mcp_docs_search
approval_policy: always
execution_policy: confirm
支持的 source 是 builtin 和 mcp:<serverID>。重复的 source/name 会被拒绝。Output budgets
必须非负、不超过 1000000。对于 MCP tools，name 是 Anyy 生成的 visible descriptor
name，例如 mcp_docs_search，不是 server 的原始工具名。并且当 visible_chars 和
stored_chars 都设置时，stored_chars 必须大于等于 visible_chars。
审批策略
审批由 effective descriptor 和工具自身行为共同决定：
| 场景 | 行为 |
|---|---|
web_search、task_list、calendar_list 等 read tools | 直接运行，除非 governance override 改变 policy。 |
task_create、memory、notify_user 等被审计的低风险写入 | 默认不向用户弹审批，但在 audit category 要求时记录 audit。 |
email_send、calendar_create、calendar_update、calendar_cancel 等 connector mutations | 返回 needs_approval；审批 replay 后执行 mutation。 |
bash、write_file、patch 等 host/config mutations | 在改变状态前走 ChangePlan 和 policy-hook approval。 |
computer_use | 桌面 capture grant 和会修改桌面的动作需要审批。 |
Approval metadata 会从普通执行路径移除，只在已批准的 replay 路径中被信任。
工具结果存储
工具结果有 visible 和 stored 两套 budget。Visible content 会立刻进入模型和 surface；stored content 可为 history 和 audit 保留更多细节。
如果成功的 visible result 超过 descriptor 的 visible budget，Anyy 可以把完整输出持久化到磁盘，
并用预览替换 visible result。目录优先使用 ANYY_TOOL_RESULTS_DIR，否则使用
/tmp/anyy-results。结果 metadata 会包含 persisted_output_path 和
persisted_output_bytes。
工具进度
Surfaces 会收到 agent loop 的工具生命周期事件：tool_execution_start、
tool_execution_update 和 tool_execution_end。工具结果状态包括 success、error、
needs_approval、change_plan_created、timeout、cancelled，以及 invalid、unavailable、
unauthorized 等 blocked statuses。
长时间 shell 工作应通过 bash 的 background=true 创建托管 process job，再用 process 管理。
独立模型工作应使用 delegate_task 做同步 fork/join，或使用 background_job 做异步 child agent 工作。
可选 Connector 工具
可选 connector 不会因为配置存在就自动进入内置默认可见列表。只有 runtime 接入 service 且对应 toolset 被选中时，才会对模型可见。
| Connector | Toolset | 说明 |
|---|---|---|
| MCP | mcp-<server> | Server 必须启用。每一轮只加载被选中的 MCP toolsets。 |
| Browser | browser | 由 browser setup 启用，暴露 Anyy 管理的 browser tools。 |
| Browser raw MCP | mcp-browser | 仅用于显式 MCP 诊断；browser setup 默认不激活。 |
email | Read/status tools 是 direct reads；email_send 需要 approval。 | |
| Calendar | calendar | Read/draft tools 不直接 mutation；create/update/cancel 需要 approval。 |
| Image generation | media_generation | 配置 image generation service/model 后暴露。 |
| Computer use | computer_use | 不在 defaults 中，也不会被 skill metadata 激活。 |
| Artifacts | artifact | 有 attachment/artifact 的 turn 会加入，除非该 turn 显式提供了 toolset list。 |
MCP setup 见 MCP 集成。Connector-backed email/calendar 和本地 computer-use toolsets 在这里作为 runtime tool contracts 列出，不代表默认启用。