工具与能力¶

手册 · 架构 · 模块 · 插件

两种契约¶

BaseTool, ToolDefinition, and ToolResult 描述由模型选择的一个操作。工具会验证参数、执行操作，并返回内容以及结构化元数据/错误状态。可用性并不等同于拥有访问所有资源的权限。

TurnCapability and CapabilityManifest 描述一个拥有某一轮对话的流水线。能力消费 UnifiedContext 并发出流事件。所有能力都应汇聚到 emit_capability_result() 以生成响应负载和 cost_summary；不要发明另一种完成封装。

内置目录由 modules/manifests/ 下内容经由 builtin_capabilities.py 推导生成。请使用 deeptutor module list、deeptutor plugin list 和 deeptutor plugin info 检查当前安装，而不是假设每个源特性在仅核心的 wheel 环境中都可用。

挂载规则¶

八个用户可切换工具是 brainstorm、web_search、paper_search、 zotero_search、reason、geogebra_analysis、imagegen 和 videogen。 tools/builtin/__init__.py 中的 USER_TOGGLEABLE_TOOL_NAMES 是权威列表；CLI --tool 从中选择。

CONFIGURABLE_BUILTIN_TOOL_NAMES 声明按上下文门控的工具，包括 研究、检索、记忆、笔记本、执行和延迟工具发现。 tool_composition.py 负责 挂载标志和始终可用的工作区工具。由能力拥有的 solve、mastery 及其他专用工具遵循各自的激活契约。 Partner 的 allow/deny 配置面可进一步收窄访问范围。

账户授权、工作区资源策略、模块选择和能力激活在发现与调度时必须始终生效。 UI 或清单中的工具名称不得绕过这些检查。MCP/CLI 延迟发现必须使用现有加载器，而不是另建并行的注册表。

添加或更改内置工具¶

1. 在其所属模块中实现类型化操作或能力。将可选库保持在仅元数据的导入之外。
2. 更新工具规范或能力声明、别名以及所属模块清单。延迟工具描述符位于 builtin_specs.py。
3. 将挂载逻辑放入现有组合/激活所有者中。明确决定工具是用户可切换、上下文门控还是 能力所属。
4. 在需要时更新请求验证和翻译后的提示词。能力提示位于 capabilities/prompts/ 下； 有些 agent 实现还在自己的目录中维护额外提示。
5. 测试元数据/实现一致性、缺失模块行为、已授权资源范围、失败与取消，以及公共结果封装。 按照测试进行 schema 重新生成和更全面的检查。

对于独立分发的包，请使用插件契约和 Learning Echo 示例， 而不要修改内置注册。阅读工具栏操作有独立的阅读扩展协议。

诊断意外的工具调用¶

将活动模块状态、能力、所选资源、用户工具选择和工作区策略，与实际被允许进入模型请求的 schema 进行对比。 然后检查调度和返回的证据。选中的 KB 并不证明检索已运行；检索到的 URL 并不证明像素已到达模型。 参见源可视化和答案质量诊断。