Knowledge Tool Contracts And Registry

Module Structure

该组件是所有内置工具、MCP 工具和 Agent 表面的共享契约层。工具定义在这里被校验并 投影为 Provider function schema，注册表再决定哪些声明进入当前模型上下文。

Directory Layout

• packages/cli/src/tools/core/ — createTool 与 UnifiedToolInvocation
• packages/cli/src/tools/types/ — 工具、结果、metadata、权限和执行上下文类型
• packages/cli/src/tools/validation/ — TypeBox 校验、JSON Schema 投影和敏感文件识别
• packages/cli/src/tools/registry/ — 内置/MCP 注册、索引、事件和延迟加载状态
• packages/cli/src/tools/artifacts/ — 有界、私有、内容寻址的 Session 制品存储

Key Entry Points

• createTool() in packages/cli/src/tools/core/createTool.ts — 从 ToolConfig 构造完整工具对象
• ToolRegistry in packages/cli/src/tools/registry/ToolRegistry.ts — 注册、筛选、克隆和投影工具目录
• DeferredToolManager.filterDeclarations() in packages/cli/src/tools/registry/DeferredToolManager.ts — 只向模型暴露已加载 schema
• parseToolSchema() in packages/cli/src/tools/validation/schemaErrorFormatter.ts — 构建 invocation 前执行 TypeBox 运行时校验
• SessionArtifactStore in packages/cli/src/tools/artifacts/SessionArtifactStore.ts — MCP 与 Browser 共用的私有制品原语

API Surface

createTool

• createTool(config) — 绑定 TypeBox schema、描述、权限签名、并发/重试能力和执行函数，并返回 Tool
• Tool.build(params) — 先解析默认值并拒绝无效输入，再创建不可变参数的 ToolInvocation
• Tool.getFunctionDeclaration() — 将内部 schema 和多段描述转换为 Provider function declaration
• Tool.getMetadata() — 暴露工具目录元数据，包括显式归一化后的 isRetrySafe 与 parallelism

ToolRegistry

• register() / registerAll() — 注册内置工具并同步分类、标签和 deferred 状态
• replaceMcpTools() — 原子替换动态 MCP 目录并保留内置名称冲突保护
• getFunctionDeclarationsByMode() — 组合 Plan 模式过滤与 deferred schema 过滤
• clone() — 共享工具对象但重新建立注册表、索引与 deferred 状态
• drainMcp*() — 以有界队列向 Agent loop 交付 MCP 目录、内容、连接、日志和任务变化

DeferredToolManager

• register() / syncDynamicTools() — 维护立即加载与延迟加载集合
• markLoaded() — 在 ToolSearch 成功后把完整 schema 纳入后续 Provider 请求
• getDeferredToolsListing() — 生成按名称排序的 <available-deferred-tools> 提示片段

SessionArtifactStore

• write() — 校验单件/Session 配额，以 SHA-256 为 ID 写入 0600 文件并去重
• removeAll() — 删除一个 Session namespace 并重置内存计数

Usage Examples

定义一个可安全重放的查询工具

const tool = createTool({
  name: 'Read',
  kind: ToolKind.ReadOnly,
  isConcurrencySafe: true,
  isRetrySafe: true,
  schema: Type.Object({ file_path: ToolSchemas.filePath() }),
  execute: async (params, context) => read(params, context),
});

注册 Session 工具并投影动态 MCP 目录

this.baseRegistry.registerAll(builtin);
this.baseRegistry.replaceMcpTools(registry.getCatalogSnapshot().tools);
this.baseRegistry.registerAll(createMcpContentTools(registry));
this.baseRegistry.registerAll(createMcpTaskTools(registry));

Gotchas

• ToolKind.ReadOnly 不表示语义幂等；CreateGoal、TaskCreate 等会改变持久状态但仍为 Plan 可用的 ReadOnly，重试资格必须单独显式声明 (packages/cli/src/tools/types/ToolTypes.ts, packages/cli/src/tools/builtin/goal/goalTools.ts, packages/cli/src/tools/builtin/task/taskListTools.ts)
• isConcurrencySafe 默认 false，parallelism 默认随它选择 shared/exclusive；显式 parallelism: 'shared' 可允许不同调用进入批内共享门，但 isConcurrencySafe: false 仍会启用同路径文件锁和禁止流式预启动 (packages/cli/src/tools/core/createTool.ts, packages/cli/src/tools/execution/ToolExecutor.ts, packages/cli/src/agent/loop/StreamingToolExecutor.ts)
• isRetrySafe 在 config、tool、metadata 和 invocation 四处传播且默认 false；新增工具若漏写不会自动重放，这是有意的 fail-closed 契约 (packages/cli/src/tools/core/createTool.ts, packages/cli/src/tools/core/ToolInvocation.ts, packages/cli/src/tools/types/ToolTypes.ts)
• Tool.build() 已经执行 TypeBox 校验与默认值注入，Hook 修改参数后必须重新 build，不能继续执行旧 invocation (packages/cli/src/tools/core/createTool.ts, packages/cli/src/tools/execution/ToolExecutionHooks.ts)
• ToolRegistry.registerAll() 逐个注册后才聚合错误，不提供批次回滚；调用方不应把失败批量注册视为零副作用 (packages/cli/src/tools/registry/ToolRegistry.ts)
• 内置工具名优先于 MCP 工具名；动态 MCP 替换遇到内置冲突或批内重名会直接失败，而同名已有 MCP 工具可被新目录覆盖 (packages/cli/src/tools/registry/ToolRegistry.ts)
• clone() 共享 Tool 实例，但 deferred 加载集合和待排出的 MCP 事件不是原对象的副本；每个执行器目录需独立经历 ToolSearch 与变化投影 (packages/cli/src/tools/registry/ToolRegistry.ts)
• TypeBox 转 Provider JSON Schema 时会递归移除 ~ 运行时注解，并为对象补 required: [] 与 additionalProperties: false；直接序列化 TypeBox schema 会产生不同契约 (packages/cli/src/tools/validation/schemaToJson.ts)
• SessionArtifactStore 发现已有同 hash 文件时会重新校验 owner、0600、大小和内容哈希，权限漂移不会被当作正常去重命中 (packages/cli/src/tools/artifacts/SessionArtifactStore.ts)