Kilo 核心工具架构解析Tool 表示、Location 注册与结算机制深度指南【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode导读本文以 packages/core/src/tool/AGENTS.md 为核心脉络系统讲解 Kilo开源编码 Agent 平台Core 包中工具子系统的整体架构一种不透明的规范 Tool 表示、进程级与 Location 级两层注册、生效查找effective lookup与结算settlement机制。读完本文你将理解内置工具与应用工具如何共用同一类型、Location 注册如何覆盖应用注册、权限过滤与执行授权如何分离以及工具输出的通用模型侧收口bounding与受管存储managed output边界落在哪里。一、总体架构一个本地工具表示 进程/Location 双层注册packages/core/src/tool/目录拥有 Core 中唯一的本地工具表示以及完整的注册、生效与结算链路。该目录下的核心文件构成四个层次文件职责tool.ts定义不透明的规范Tool.make(...)值description / input / output / execute / toModelOutputapplication-tools.ts存储进程作用域process-scoped的应用注册tools.ts暴露仅含注册能力的Tools.Service视图供 Location 生产者使用registry.ts只存放规范工具叠加 Location 注册、派生定义、调用工具并施加通用输出收口从源码结构看这套设计最重要的约束是单一执行入口类型文档明确要求不要新增第二种可执行条目类型、registry 自有执行器、授权回调、输出路径回调或遗留归一化路径legacy normalization path。也就是说所有可执行工具——无论应用工具还是内置工具——都必须以同一种Tool.make值存在。对应到具体内置实现builtins.ts 只组合随发布提供的 Location 作用域内置工具变换其deps列出的正是bash、edit、apply_patch、write、glob、grep、question、read、skill、todowrite、webfetch、websearch等工具节点。文件头部注释同时指出动态 MCP 与插件工具后续走独立的 scoped 规范注册而不是进入这份静态内置列表。二、构造Construction不透明 Tool 值与其运行时细节2.1Tool.make的配置面Tool.make接收一个Config其核心字段在 tool.ts 中定义description模型可见的工具描述input/output均基于 Effect Schema 的编解码器构成工具输入/输出的唯一事实来源structured/toStructuredOutput可选用于派生结构化输出execute真正的执行函数签名是(input, context) EffectOutput, ToolFailuretoModelOutput可选把已验证的输出投影成模型可读的Content数组文本或内联文件。而工具值是不透明的调用方拿到的只是一个Object.freeze({})的Definition对象其 codec、执行器、定义派生逻辑与目录权限声明全部被隐藏在WeakMapAnyTool, Runtime中tool.ts外部无法直接触碰。Tool.definition(name, tool)、Tool.settle(tool, call, context)、Tool.permission(tool, name)、Tool.withPermission(tool, permission)是仅有的几个公开操作入口。2.2 名字校验与权限装饰Tool.validateName用正则/^[A-Za-z][A-Za-z0-9_-]{0,63}$/校验工具名失败时抛出Tool.RegistrationError。Tool.withPermission通过复制 runtime 并覆写permission字段来装饰工具tool.ts装饰后的值依然是同一个不透明类型。2.3 规范调用上下文的权限源Location 作用域的内置工具层在构造期间获取PermissionV2.Service及其所需的其他 Location 服务执行器捕获这些服务。权限源permission source总是从规范的调用上下文构造const source { type: tool as const, messageID: context.assistantMessageID, callID: context.toolCallID, }这一代码模式在 bash.ts、edit.ts、write.ts、apply-patch.ts 中完全一致——Context结构sessionID、agent、assistantMessageID、toolCallID在 tool.ts 中统一定义。2.4 错误翻译纪律文档强调叶子工具自行负责解析、权限与副作用顺序并且只把预期的类型化错误翻译成ToolFailure不要使用catchCause——因为中断interruption和缺陷defect必须原样存活。这正是 Effect 生态中错误是值、缺陷是缺陷的边界体现工具内部可以用Effect.mapError把业务错误包装成ToolFailure如 bash.ts 的Unable to execute command但绝不能把中断/缺陷误吞为普通工具失败。三、注册Registration两层作用域与覆盖规则3.1 两条注册通路内置工具通过Tools.Service.register({ [name]: tool })注册例如 bash.ts、edit.ts应用工具通过ApplicationTools.Service.register(...)注册对外公开为opencode.tools.register(...)。ApplicationTools.Service是**进程级process-scoped**的由所有 Location 共享而ToolRegistry.Service是 **Location 级Location-scoped**的。文档明确禁止把 registry 做成进程全局也禁止为每个 Location 单独构造应用工具服务——保证应用工具注册一次、处处可见而 Location 内注册天然隔离。3.2 覆盖shadowing语义两层注册的生效规则来自 registry.ts 的实现最新活跃的同层注册胜出Location 本地注册以Mapstring, ArrayRegistration栈式存储查找时取entries.at(-1)关闭任一注册只移除该注册并暴露下一个活跃注册注册通过Effect.addFinalizer登记清理逻辑registry.tsScope 关闭时只移除当前 token 对应的条目Location 注册优先于应用注册settleWith中先查local栈查不到才回落到applications.entries()调用在结算开始时捕获生效工具materialize把应用注册与当前 Location 注册合并成一张不可变快照后续settle都基于这张快照避免注册中途变更导致执行不一致。此外还有一个陈旧调用保护settleWith支持传入advertised广告过的注册身份如果实际生效的注册身份与广告不一致直接返回Stale tool call: name错误registry.ts防止模型基于旧定义发起调用。3.3 注册期的并发与原子性ToolRegistry.register内部包裹在Effect.uninterruptible中registry.ts确保一批工具的注册/清理是原子的。注册前还会用Effect.forEach批量执行validateName任一名字非法则整批失败。四、权限Permissions定义过滤 ≠ 执行授权这是本架构最容易误解的一点值得单独展开registry 不依赖PermissionV2.Service也不做执行授权。从 registry.ts 的Service声明可见ToolRegistry的依赖只有ApplicationTools与ToolOutputStore有一个仅供内置工具使用的内部操作会给工具附加一个 permission action目的纯粹是为了保留整工具定义过滤whole-tool definition filtering能力它不是公开Tool.make的一部分大多数工具默认以其注册名为 action而edit、write、apply_patch三个工具统一声明共享的editaction——在 edit.ts、write.ts、apply-patch.ts 中均可看到Tool.withPermission(tool, edit)的用法。定义过滤是目录可见性catalog visibility不是执行授权。调用如果走到了结算仍会执行捕获到的叶子策略leaf policy。在实现上materialize用whollyDisabled(action, permissions)判断只有命中resource * effect deny的通配规则时才把工具从definitions中剔除registry.ts而真正的授权发生在叶子工具执行时的permission.assert(...)调用——例如 bash.ts 对命令本身、edit.ts 对编辑资源。此外叶子工具的解析顺序统一为先用LocationMutation.resolve解析路径 → 若目标在外部目录则先断言external_directory权限 → 再断言自身 action如edit。bash.ts、edit.ts、write.ts、apply-patch.ts 都是这一模式。五、输出Outputsettle是唯一的执行与收口边界5.1 结算settlement流程文档明确指出ToolRegistry.Materialization.settle是唯一的执行与通用模型输出收口generic model-output bounding边界并且拥有受管保留路径managed retention paths。结合 registry.ts 与 tool.ts 的实现settle的完整链路是按调用名查找注册Location 栈优先回落应用注册Tool.settle用Schema.decodeUnknownEffect(config.input)解码调用输入失败映射为Invalid tool input: ...的ToolFailure执行config.execute(input, context)用Schema.encodeEffect(config.output)编码输出失败映射为Tool returned an invalid value for its output schema: ...若配置了structuredtoStructuredOutput再编码结构化输出调用toModelOutput生成Content数组——文本部分直接透传file类型部分编码为data:mime;base64,data的 data URItool.tsregistry 捕获LLM.ToolFailure并转成错误结果然后把输出交给ToolOutputStore.bound做通用收口registry.ts。5.2 输出收口与受管存储ToolOutputStoretool-output-store.ts定义了三个关键常量MAX_LINES 2_000MAX_BYTES 50 * 1024RETENTION Duration.days(7)bound会对超限输出做首尾采样式截断preview保留头部一半、尾部一半行数超过阈值的部分落盘到MANAGED_DIRECTORY tool-output目录返回的outputPaths指向受管文件。结算结果Settlement因此包含result、可选output与可选outputPaths三部分。值得注意的是edit与apply_patch两个工具还做了工具侧的自压缩当序列化输出超过ToolOutputStore.MAX_BYTES时compact会把files数组裁剪为仅保留additions/deletions/file/status字段、丢弃巨大的 diff 文本edit.ts、apply-patch.ts从而在不隐藏正常大小 diff 预览的前提下保持持久化/SSE 工具记录的体积有界。5.3 生产者捕获限制是另一回事文档特别澄清生产者producer的捕获限制与模型输出收口是分离的。以 Bash 为例它自己维护AppProcess.maxOutputBytes在 bash.ts 中即MAX_CAPTURE_BYTES 1024 * 1024它会在输出里如实报告 stdout/stderr 捕获丢失输出被截断时追加[output capture truncated at the in-memory safety limit]说明但它不做模型输出截断也不返回受管outputPath——那是settle边界的事。也就是说Bash 的超时默认DEFAULT_TIMEOUT_MS 2 * 60 * 1_000上限MAX_TIMEOUT_MS 10 * 60 * 1_000与内存捕获上限属于进程层约束而模型看到的最终输出形状由 registry 的settleToolOutputStore.bound统一决定。edit/apply_patch的compact与ToolOutputStore的preview分别位于工具内与结算边界两层共同保证输出记录可控。六、当前缺口Current Gaps已知的演进方向文档如实记录了三个尚未完成的设计点对于理解代码现状至关重要插件启动plugin boot尚未重构为通过Tools.Service注册规范工具——文档明确要求不要作为叶子迁移的一部分顺带重设计它MCP 与未来的 Session 级注册仍缺少显式的规范注册设计——builtins.ts的注释也印证了动态 MCP 与插件工具稍后使用独立 scoped 规范注册的规划公开 Session 结果形状目前暴露了受管的outputPaths——完整的存储封装需要未来的不透明受管输出引用设计opaque managed-output reference才能实现。这三个缺口都指向同一个方向当前进程级应用注册 Location 级内置注册 registry 结算的骨架已经稳定而插件、MCP 与 Session 级扩展点正在向同一套规范工具模型收敛。七、小结架构设计的关键约束一览关注点结论源码位置工具表示唯一不透明的Tool.make值应用/内置共用tool.ts注册层级应用进程级、Location 级Location 优先、最新胜出、可关闭回退application-tools.ts、registry.ts公开注册 API内置走Tools.Service.register应用走opencode.tools.registertools.ts、application-tools.ts权限registry 不授权定义过滤只影响目录可见性edit/write/apply_patch共享editactionregistry.ts、edit.ts输出边界settle是唯一执行与模型输出收口点ToolOutputStore管理受管输出路径registry.ts、tool-output-store.ts生产者限制如 Bash 的捕获上限仅报告丢失不截断模型输出、不返回 outputPathbash.ts已知缺口插件 boot、MCP/Session 级注册、Session 结果形状封装AGENTS.md这套架构的核心价值在于用一个规范工具类型 两层作用域注册 唯一结算边界把工具系统的可扩展性与可治理性统一起来——应用开发者只需opencode.tools.register即可接入内置叶子共享同一执行与权限纪律而输出形状则由settle统一收口为插件、MCP 等后续扩展点保留了清晰的挂载位置。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考