knowledge-integration-and-workflow-tool-adapters

name

knowledge-integration-and-workflow-tool-adapters

description

Covers 领域能力如何包装成内置工具、getBuiltinTools 的 Session 依赖注入、ToolSearch 延迟激活，以及 Goal/Task/Team/Plan/Skill/LSP/MCP/Web/Config/Worktree 适配边界。 Navigate when: 新增或移除内置工具、改变工具集合条件、调整领域工厂依赖、排查 deferred schema、MCP helper 或工作流工具权限分类。 Excludes: 各领域内部状态机（见对应顶层域）、通用 Tool 契约（见 ../tool-contracts-and-registry/）、执行顺序（见 ../tool-execution-pipeline/）。 Keywords: getBuiltinTools, ToolSearch, createGoalTools, createTaskTools, createTeamTools, createMcpContentTools, createMcpTaskTools, createLspTool, createBrowserTools.

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 调 时看到的目录必然更小 (, )

Architecture

• 内置目录先由 getBuiltinTools 组装，SessionRuntime 再过滤非 mcp__ 内置项、接入 MCP catalog 与 helper，最后为每个 Agent 创建独立过滤 registry (packages/cli/src/tools/builtin/index.ts, packages/cli/src/agent/runtime/SessionRuntime.ts)
• 工厂注入将状态所有权留在领域服务：GoalStore、TaskListManager、LspSessionManager、SessionBrowserRuntime、SkillRegistry 等不会被通用 Tool 接口重新实现 (packages/cli/src/tools/builtin/goal/goalTools.ts, packages/cli/src/tools/builtin/lsp/lsp.ts, packages/cli/src/tools/builtin/browser/browserTools.ts)
• deferred 工具仍已注册并可被 ToolSearch 搜索，只是 full schema 不进入 Provider 请求；核心工具集合由 DeferredToolManager 的固定 allowlist 立即暴露 (packages/cli/src/tools/registry/DeferredToolManager.ts, packages/cli/src/tools/builtin/system/ToolSearchTool.ts)
• 动态 MCP catalog 变化会同步到所有已创建 executor registry，并按各自 allow/deny 集重新过滤，避免旧 Agent 看到已删除或越权工具 (packages/cli/src/agent/runtime/SessionRuntime.ts, packages/cli/src/tools/registry/ToolRegistry.ts)

Decisions

• Browser 只有在 SessionRuntime 创建并注入 runtime 后加入目录，保持 import/启动无 Chromium 副作用且确保 Session dispose 能回收 Context (packages/cli/src/tools/builtin/index.ts, packages/cli/src/agent/runtime/SessionRuntime.ts)
• LSP 只有 Session manager 报告 available 时才注册，且 ACP-owned remote files 不走本地 LSP，避免暴露一个必然失败的 schema (packages/cli/src/tools/builtin/lsp/lsp.ts, packages/cli/src/tools/builtin/index.ts)
• deferred catalog 用 ToolSearch 实现渐进披露，核心编辑/搜索/任务工具常驻，Browser 与多数集成能力仅以名称进入系统提示，降低每轮 schema token 成本 (packages/cli/src/tools/registry/DeferredToolManager.ts, git:25d5a7d3)

Patterns

• 单例无状态工具直接导入，依赖 Session 状态的工具统一使用 createXTools(options)；新增适配器应先判断它属于哪一类 (packages/cli/src/tools/builtin/index.ts)
• 适配器失败应返回统一 ToolResult 和稳定 error type/code，把领域对象限制在 metadata，而不是把原始异常或内部路径直接泄露给模型 (packages/cli/src/tools/builtin/browser/browserTools.ts, packages/cli/src/mcp/createMcpTool.ts)
• 读取类领域工具只有经过幂等审计后才添加 isRetrySafe: true；“查询”名称、ReadOnly kind 或 isConcurrencySafe 都不足以作为 opt-in 理由 (packages/cli/src/tools/builtin/lsp/lsp.ts, packages/cli/src/tools/builtin/system/readPromptArtifact.ts)

Consumer Analysis

• packages/cli/src/agent/runtime/SessionRuntime.ts 是完整消费者：它注入 Session 资源、注册 MCP helper、传播 catalog 变化，并为前台 Agent、子代理和旁路对话创建过滤 executor (packages/cli/src/agent/runtime/SessionRuntime.ts)
• packages/cli/src/agent/Agent.ts 是兼容/独立消费者：缺少完整 Session runtime 时用默认资源构建较小目录，并单独连接 MCP 内容工具 (packages/cli/src/agent/Agent.ts)
• packages/cli/src/agent/loop/executeLoopGenerator.ts 消费模式过滤后的 declarations 与 deferred listing，并把 registry/manager 回注到调用上下文以支持 ToolSearch (packages/cli/src/agent/loop/executeLoopGenerator.ts)
• packages/cli/src/mcp/ 同时生产动态外部 Tool 和供 builtin 工厂使用的 Registry；外部调用、内容目录和异步 task 的所有权不能在适配层混为一类 (packages/cli/src/mcp/createMcpTool.ts, packages/cli/src/mcp/McpRegistry.ts)
• packages/cli/src/ui/、packages/cli/src/commands/headless.ts、packages/cli/src/server/ 和 packages/cli/src/acp/ 不直接实现领域工具，而是消费统一 ToolResult、确认请求和展示投影 (packages/cli/src/tools/display/ToolResultProjector.ts, packages/cli/src/ui/utils/toolFormatters.ts)