knowledge-tool-and-automation-platform

name

knowledge-tool-and-automation-platform

description

Covers Blade 工具契约、注册与执行，以及文件、搜索、Shell、worktree、Browser 和领域适配工具的协作边界。 Navigate when: 新增工具、调整工具注册或执行顺序、排查工具副作用、并发、重试、输出投影或自动化资源生命周期。 Excludes: 全局权限与 Workspace Trust 策略（见 ../workspace-policy-and-shared-foundations/）、MCP 协议内部生命周期（见 ../extension-ecosystem/mcp-protocol-runtime/）、Agent 轮次决策（见 ../agent-execution-and-orchestration/decision-loop-and-completion/）。 Keywords: tools, Tool, ToolRegistry, ToolExecutor, createTool, isRetrySafe, ApplyPatch, Bash, WorktreeManager, SessionBrowserRuntime.

Module Structure

该域把模型可见的工具声明、运行时准入与具体副作用适配器连接起来；SessionRuntime 负责组装 Session 私有依赖，Agent loop 负责提交并持久化调用，具体工具只返回统一 ToolResult。

Directory Layout

• packages/cli/src/tools/core/ — TypeBox 工具工厂与统一调用对象
• packages/cli/src/tools/types/ — 工具、调用、结果与执行上下文契约
• packages/cli/src/tools/registry/ — 内置、延迟加载与动态 MCP 工具目录
• packages/cli/src/tools/execution/ — 权限、Hook、准入、锁、调用与验证管线
• packages/cli/src/tools/builtin/ — 文件、Shell、Browser 与工作流工具适配器
• packages/cli/src/browser/ — Session 隔离的 Playwright 自动化运行时
• packages/cli/src/worktree/ — 托管 Git worktree 的创建、交付和清理
• packages/cli/src/services/FileSystemService.ts — 本地与 ACP 文件系统抽象

Key Entry Points

• getBuiltinTools() in packages/cli/src/tools/builtin/index.ts — 按 Session 能力组装内置工具
• ToolRegistry in packages/cli/src/tools/registry/ToolRegistry.ts — 维护可发现工具及动态 MCP 投影
• ToolExecutor.execute() in packages/cli/src/tools/execution/ToolExecutor.ts — 执行单次工具调用的统一入口
• StreamingToolExecutor in packages/cli/src/agent/loop/StreamingToolExecutor.ts — 将 Provider 流式 tool call 接入持久化与执行

Gotchas

• ToolKind 只参与权限和容量分类，isConcurrencySafe、parallelism 与 isRetrySafe 是三个独立维度；不能因工具是 ReadOnly 就推断它可并发、可流式预启动或可重放 (packages/cli/src/tools/types/ToolTypes.ts, packages/cli/src/tools/core/createTool.ts)
• 工具瞬态异常重试默认 fail-closed；未显式声明 isRetrySafe: true 的调用只执行一次，避免在完成状态不确定时重复外部副作用 (packages/cli/src/tools/execution/ToolInvocationRunner.ts, packages/cli/tests/unit/tooling/tools/builtin/tool-retry-safety.test.ts)
• Browser 自动化与 Web UI 的 iframe Preview 是两个独立运行时；前者由 Session 持有 Playwright Context，后者不能被 Agent 工具直接操纵 (packages/cli/src/browser/SessionBrowserRuntime.ts, packages/cli/web/src/components/preview/BrowserPreview.tsx)
• Session 关闭必须同时回收执行器队列、后台进程、Browser Context、文件访问记录和 worktree 内存绑定；只释放其中一个会留下跨轮次资源或容量占用 (packages/cli/src/agent/runtime/SessionRuntime.ts)
• ExecutionPipeline 只是 ToolExecutor 的兼容别名，新代码若沿用旧“固定阶段类”心智模型会误判当前真实调用顺序 (packages/cli/src/tools/execution/ExecutionPipeline.ts, git:e6a1bef4)

Architecture

• 主链路是 getBuiltinTools/MCP 工具投影 → ToolRegistry → Agent loop → ToolExecutor → invocation；Schema、权限签名、并发、重试和展示数据都沿这一条统一契约传播 (packages/cli/src/tools/builtin/index.ts, packages/cli/src/tools/registry/ToolRegistry.ts, packages/cli/src/tools/execution/ToolExecutor.ts)
• SessionRuntime 先构造带 Browser、LSP、Skill、Task 等 Session 私有依赖的基础注册表，再为不同 Agent 按 allow/deny 过滤克隆目录，避免共享动态加载和审批状态 (packages/cli/src/agent/runtime/SessionRuntime.ts, packages/cli/src/tools/registry/ToolRegistry.ts)
• 文件、Shell 与 Browser 各自拥有额外的状态一致性边界：文件依赖读取记录和事务，Shell 依赖进程租约，Browser 依赖 Context/页面/快照代际；通用执行器不替代这些领域内保护 (packages/cli/src/tools/builtin/file/FileAccessTracker.ts, packages/cli/src/context/storage/DurableProcessLeaseStore.ts, packages/cli/src/browser/BrowserSnapshotAuthority.ts)
• ToolResult 同时承载给模型的 llmContent、稳定错误类型和跨表面的 metadata；TUI、Headless、Server 与 ACP 再通过统一 projector 做各自长度裁剪 (packages/cli/src/tools/types/ToolTypes.ts, packages/cli/src/tools/display/ToolResultProjector.ts)

Decisions

• 工具系统已从 11 阶段对象管线迁移为平铺执行器，以显式函数组合表达顺序；保留旧导出仅用于兼容现有 import (packages/cli/src/tools/execution/ExecutionPipeline.ts, packages/cli/src/tools/execution/ToolExecutor.ts, git:e6a1bef4)
• 工具 schema 统一迁移到 TypeBox，并在发送给 Provider 前去除运行时注解和关闭未知对象字段，避免手写 JSON Schema 与运行时校验漂移 (packages/cli/src/tools/validation/schemaToJson.ts, packages/cli/src/tools/validation/schemaErrorFormatter.ts, git:311ba368)
• Browser 选择原生工具而非 MCP 或 iframe 控制，是为了复用 Blade 的权限、Hook、Session、取消和持久化语义，同时保持一个进程、多 Session Context 的资源模型 (docs/superpowers/specs/2026-08-25-native-browser-tool-design.md, git:90fad7fe)

Patterns

• 能力适配器通过 createTool 返回声明与执行一体的对象，Session 依赖通过工厂参数注入；模块级单例仅用于真正的进程级资源 (packages/cli/src/tools/core/createTool.ts, packages/cli/src/tools/builtin/index.ts)
• 任何可能产生副作用的长生命周期资源都使用显式 owner/session identity 和幂等 dispose/release，恢复路径先验证身份再清理 (packages/cli/src/context/storage/DurableProcessLeaseStore.ts, packages/cli/src/browser/BrowserProcessPool.ts)
• 大输出先在生产端有界保留，再在表面投影层二次裁剪；持久记录保留计数和截断事实，避免 UI 限制反向改变执行语义 (packages/cli/src/tools/builtin/shell/ShellOutputCapture.ts, packages/cli/src/tools/display/ToolResultProjector.ts)

Child Knowledge Nodes

• ./tool-contracts-and-registry/SKILL.md — Navigate when: 定义工具、调整 TypeBox schema、注册表、延迟发现、MCP 工具目录或通用制品存储
• ./tool-execution-pipeline/SKILL.md — Navigate when: 调整执行顺序、权限/Hook、并发准入、文件锁、重试、取消、自动验证或结果投影
• ./filesystem-search-and-atomic-patching/SKILL.md — Navigate when: 修改 Read/Write/Edit/ApplyPatch、快照回退、Glob/Grep 或 ACP 文件语义
• ./shell-process-and-worktree/SKILL.md — Navigate when: 修改 Bash、后台输入输出、进程租约/回收、写沙箱或托管 worktree
• ./browser-automation/SKILL.md — Navigate when: 修改 Chromium 池、Session Browser、ARIA ref、同源边界、诊断、截图或 Web Browser 面板
• ./integration-and-workflow-tool-adapters/SKILL.md — Navigate when: 修改领域能力的工具适配、Session 条件注入、ToolSearch 或 MCP/Goal/Task/LSP/Web 工具集合