Knowledge Integration And Workflow Tool Adapters

Module Structure

该组件不实现领域核心状态，而是把 Session 拥有的服务、注册表和资源快照适配为统一 Tool[]。静态单例工具与依赖注入工厂在 getBuiltinTools 汇合，再由 SessionRuntime 加入动态 MCP 工具和按 Agent 的 allow/deny 过滤。

Directory Layout

• packages/cli/src/tools/builtin/index.ts — 内置工具组合根与条件注入
• packages/cli/src/tools/builtin/system/ — ToolSearch、Skill、SlashCommand、AskUserQuestion 与 prompt artifact
• packages/cli/src/tools/builtin/task/ / team/ / goal/ — Agent 工作流适配器
• packages/cli/src/tools/builtin/mcp/ / lsp/ — MCP 内容/任务与 Session LSP 查询适配器
• packages/cli/src/tools/builtin/web/ — WebFetch/WebSearch、缓存和 Provider fallback
• packages/cli/src/tools/builtin/config/ / memory/ / plan/ / worktree/ — 配置、记忆、模式和工作区适配器

Key Entry Points

• getBuiltinTools() in packages/cli/src/tools/builtin/index.ts — 依据 Session 能力构造完整内置目录
• toolSearchTool in packages/cli/src/tools/builtin/system/ToolSearchTool.ts — 搜索并激活 deferred schema
• createMcpTool() in packages/cli/src/mcp/createMcpTool.ts — 将外部 MCP tool definition 转换为 Blade Tool
• SessionRuntime.registerBuiltinTools() in packages/cli/src/agent/runtime/SessionRuntime.ts — 注入 Session-owned Browser/LSP/资源

API Surface

getBuiltinTools

• getBuiltinTools(options?) — 返回当前 Session 的工具数组，并为需要状态的领域调用工厂
• browserRuntime — 提供时加入六个 Browser 工具，否则不暴露 Browser 能力
• lspManager / lspResources — 仅 manager available 时加入 LSP，并传给子代理
• agentTeamsEnabled — 唯一控制 Team 工具是否进入目录的显式能力门
• agentResources / modelResources — 固定当前 Session 的 Agent、Skill、命令与模型资源
• userPromptArtifactStore — 提供时加入 ReadPromptArtifact

Domain Adapter Factories

• createGoalTools() / createTaskListTools() / createTeamTools() — 把持久状态和协调服务包装为工具
• createSkillTool() / createSlashCommandTool() — 加载 Markdown 扩展并把约束返回给主对话
• createLspTool() / createBrowserTools() — 绑定 Session-owned runtime，避免模块级跨会话状态
• createMcpContentTools() / createMcpTaskTools() — 暴露当前 MCP catalog 与异步任务，而外部 MCP 方法由 createMcpTool() 动态生成

ToolSearch

• select:<name,...> — 按精确名称返回 function declarations 并标记已加载
• 普通 query — 搜索名称、显示名、描述、分类和标签，并受 max_results 限制

Usage Examples

Session 注入可用能力

const builtinTools = await getBuiltinTools({
  sessionId: this.sessionId,
  workspaceRoot: this.workspaceRoot,
  agentResources: this.agentResources,
  lspManager: this.lspManager,
  browserRuntime: this.browserRuntime,
});

在基础目录上叠加 MCP 能力

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

Gotchas

• getBuiltinTools() 混合模块级单例和 Session 工厂；任何持有 Session 状态的新工具必须通过 options 注入，不能在模块加载时捕获当前 cwd、Session 或 runtime (packages/cli/src/tools/builtin/index.ts, packages/cli/src/agent/runtime/SessionRuntime.ts)
• 当前 fail-closed 重试清单只有 GetGoal、Glob、Grep、LSP、MemoryRead、Read、ReadPromptArtifact、TaskGet、TaskList、TeamStatus、ToolSearch；未列出的工具即使是 ReadOnly 也不会自动重放 (packages/cli/tests/unit/tooling/tools/builtin/tool-retry-safety.test.ts, packages/cli/src/tools/core/createTool.ts)
• ToolKind.ReadOnly 是权限标签而非“没有状态变化”：CreateGoal、UpdateGoal、TaskCreate/Update 和多项 Team 工具会写持久状态但为 Plan 流程保留 ReadOnly 分类，因此仍显式关闭并发和重试 (packages/cli/src/tools/builtin/goal/goalTools.ts, packages/cli/src/tools/builtin/task/taskListTools.ts, packages/cli/src/tools/builtin/team/teamTools.ts)
• WebFetch 被声明为 ReadOnly，但 schema 允许 POST/PUT/DELETE 和 body；它没有 isRetrySafe，修改权限或重试策略时不能只依据 kind 把任意请求视为无副作用 (packages/cli/src/tools/builtin/web/webFetch.ts)
• WebSearch 没有工具级 isRetrySafe，但其内部 HTTP provider 会做最多 3 次指数退避并在多个 Provider 间 failover；不要再叠加 invocation 重放造成成倍请求 (packages/cli/src/tools/builtin/web/webSearch.ts)
• MCP catalog 中的外部工具统一包装为 ToolKind.Execute 且默认不可重放，即使远端 schema/描述声称只读也不会改变本地权限基线 (packages/cli/src/mcp/createMcpTool.ts)
• MCP 内容和任务 helper 是内置工具，不属于动态 mcp__* Map；替换 MCP catalog 时不能删除这些 helper，SessionRuntime 会分别注册两类工具 (packages/cli/src/agent/runtime/SessionRuntime.ts, packages/cli/src/tools/builtin/mcp/mcpContentTools.ts)
• ToolSearch 只在 ExecutionContext 同时拿到 registry 和 deferred manager 时永久激活当前目录中的 schema；返回 <functions> 文本本身不会修改其他 executor 的加载状态 (packages/cli/src/tools/builtin/system/ToolSearchTool.ts, packages/cli/src/agent/loop/executeLoopGenerator.ts)
• Browser、LSP、Teams 和 prompt artifact 都是条件工具；测试或备用 Agent 用缺省 options 调 getBuiltinTools() 时看到的目录必然更小 (packages/cli/src/tools/builtin/index.ts, packages/cli/src/agent/Agent.ts)
• Skill 和 SlashCommand 返回的是供后续模型执行的指令及 allowedTools/model 元数据，不会在工具函数内部直接完成整个 Skill 或命令请求 (packages/cli/src/tools/builtin/system/skill.ts, packages/cli/src/tools/builtin/system/slashCommand.ts)
• TaskOutput 聚合子代理、MCP task 和 Background Shell 三类 ID；新增后台任务类型时必须同步路由和结果形状，不能只在 producer 侧注册 (packages/cli/src/tools/builtin/task/taskOutput.ts)