echovic 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()inpackages/cli/src/tools/builtin/index.ts— 按 Session 能力组装内置工具ToolRegistryinpackages/cli/src/tools/registry/ToolRegistry.ts— 维护可发现工具及动态 MCP 投影ToolExecutor.execute()inpackages/cli/src/tools/execution/ToolExecutor.ts— 执行单次工具调用的统一入口StreamingToolExecutorinpackages/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 工具集合