Kilo Code 工具系统全解析工作流、权限审批与核心工具源码级指南【免费下载链接】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/kilocodeKilo Code 通过一组专用工具Tools与你的代码和环境交互以自动化的方式完成读文件、改代码、跑命令、搜代码库等常见开发任务。本文以官方文档《How Tools Work》为骨架结合本仓库packages/core/src/tool/下的真实源码实现系统讲解工具的工作流程、分类体系、权限安全模型以及每个核心工具的输入参数与底层行为帮助你理解并安全、高效地使用 Kilo Code 的自动化能力。工具工作流从自然语言到执行结果Kilo Code 使用工具Tools作为与代码和环境交互的桥梁。这些专门的辅助工具执行特定动作——读取文件、进行编辑、运行命令、搜索代码库——让常见开发任务无需手工操作即可自动化完成。用自然语言描述你希望完成的目标Kilo Code 会遵循一个四步循环选择工具根据你的请求选择最合适的工具展示参数将工具及其参数呈现给你审查执行并反馈执行经你批准的工具调用并展示结果循环直至完成重复以上过程直到任务全部完成。从源码结构看这个循环的核心建立在 工具定义模块 之上每个工具通过Tool.make声明description描述、input输入 Schema、output输出 Schema与execute执行函数并在settle阶段完成输入解码 → 校验 → 执行 → 输出编码的完整闭环tool.ts。工具的输入输出均以 Effect Schema 强类型约束非法输入会以ToolFailure的形式返回明确的错误信息。工具分类五大职责域文档将工具划分为五大类别每一类解决一类开发自动化问题分类用途工具名Read读取访问文件内容与代码结构read、glob、grepEdit编辑创建或修改文件与代码edit、write、apply_patchExecute执行运行命令与执行系统操作bashWeb网络抓取与搜索网页内容webfetch、websearchWorkflow工作流管理任务流与子代理question、task、todowrite、todoread、plan、skill核心工具参考参数与底层行为以下逐一深入每个工具结合源码说明其输入参数、默认值与实现细节。读取类read、glob、grepread读取文件内容并显示行号。从 read.ts 的实现看它远比读文件更强大支持分页读取大文件输入参数offset从 1 开始的行/目录项偏移与limit最大读取行数支持目录列表分页输出目录页支持读取图片jpeg、png、gif、webp读取后会自动归一化read.ts相对路径从当前 Location活动工作区解析活动 Location 内的绝对路径可直接读取Location 外的绝对路径需要额外的external_directory审批遇到非支持格式的二进制文件会返回BinaryFileError提示使用其他方式处理。glob按 glob 模式查找文件。从 glob.ts 的实现看它底层基于 ripgrep 的文件枚举能力输入参数pattern必填的 glob 模式、path相对搜索目录默认活动 Location、limit最大返回条数结果携带truncated结果被截断与partial部分文件不可读状态并会明确告知模型结果已截断仅显示前 N 个文件glob.ts每次搜索都会先做路径逃逸校验请求的路径必须位于活动 Location或命名的项目引用之内否则直接报错拒绝。grep用正则表达式搜索文件内容。从 grep.ts 的实现看输入参数pattern正则、path相对搜索目录默认活动 Location、include按 glob 过滤文件如*.js或*.{ts,tsx}、limit最大匹配数输出为文件资源、行号与有界的行预览同样携带truncated/partial状态支持搜索托管工具输出文件managed tool-output file等受管理路径。编辑类edit、write、apply_patchedit在文件中做精确文本替换。从 edit.ts 的实现看这是文档中提到的最精细的编辑工具输入参数path文件路径、oldString要替换的精确文本、newString替换文本必须与oldString不同、replaceAll可选是否替换所有精确匹配默认false精确匹配约束oldString必须与文件内容逐字符精确匹配包括空白与缩进找不到时返回Could not find oldString in the file若存在多个匹配且未开启replaceAll会提示提供更多上下文或设置replaceAll: trueedit.ts自动处理换行符与 BOM先检测文件是\n还是\r\n行尾将替换文本转换后匹配并在写入时保留 BOM 标记edit.ts写前一致性防护写入采用若未变更则写入writeIfUnchanged机制如果文件在权限批准后被外部修改会抛出StaleContentError并提示文件在批准后已变更请先重新读取再编辑edit.ts输出包含files含 diff 补丁、增删行数、状态与replacements替换次数并会向模型返回带/-前缀的 diff 预览。write创建新文件或覆盖已有文件。从 write.ts 的实现看输入参数path与content写入时保留文件 BOMwriteTextPreservingBom输出标记operation、target、resource以及existed文件原本是否存在模型侧据此反馈是Wrote写入还是Created创建成功。apply_patch应用 unified diff统一差异补丁主要配合特定模型使用。同样属于 Edit 类别用于一次性的多处修改场景。执行类bashbash运行 Shell 命令。从 bash.ts 的实现看这是权限面最大的工具输入参数command要执行的 Shell 命令字符串、workdir工作目录默认活动 Location相对路径从该 Location 解析、timeout超时毫秒数超时默认 120,000ms2 分钟最大不超过 600,000ms10 分钟bash.ts超时后返回明确提示并建议调大超时重试输出捕获上限 1MBMAX_CAPTURE_BYTES超出时输出会附带[output capture truncated at the in-memory safety limit]提示Shell 选择优先使用配置的 shell否则 POSIX 用/bin/shWindows 用COMSPEC或cmd.exebash.ts具备外部目录咨询扫描对命令中的绝对路径参数做 best-effort 检测若引用活动 Location 之外的目录会附加 advisory 警告注意这是提示性扫描并非硬性拦截返回exit退出码、output合并后的标准输出/错误、truncated、timeout与可选的warnings。网络类webfetch、websearchwebfetch抓取指定 URL 的内容。实现上设有MAX_RESPONSE_BYTES5MB响应上限与DEFAULT_TIMEOUT_SECONDS30 秒默认超时。websearch联网搜索面向 Kilo/OpenRouter 用户。实现通过 Exa 的 MCP 端点提供搜索能力无结果时返回No search results found. Please try a different query.。工作流类question、task、todowrite、todoread、plan、skillquestion在执行过程中向你提出带选项的澄清问题帮助你决定后续方向task派生一个子代理sub-agent会话用于并行或分工处理子任务todowrite创建并更新当前会话的 TODO 列表跟踪多步任务进度todoread读取当前会话的 TODO 列表plan进入结构化规划模式先规划再执行skill调用可复用的技能Markdown 指令模块。从 skill.ts 的实现看单次调用有文件数量限制FILE_LIMIT 10。实战示例一次典型的工具交互下面是文档给出的典型交互场景用户创建一个名为greeting.js、能打印问候消息的文件。Kilo Code提议使用write工具扩展插件会展示文件路径与拟写入的内容供你审查。点击Approve批准执行或点击Deny拒绝取消。注意——工具批准 UI当工具被提议时聊天面板底部的Permission Dock权限停靠栏会出现审批提示。你可以选择批准一次、总是批准会保存到配置或拒绝。以write工具为例它在源码中实际上注册为edit权限动作Tool.withPermission(..., edit)并会在写文件前依次检查external_directory若路径在活动 Location 之外与edit两类权限write.ts。这也解释了为什么在配置中放行edit会同时影响write工具。工具安全与审批默认全部询问每一次工具调用都会经过权限检查。默认行为是ask——如果配置中没有针对该工具的匹配规则Kilo Code 会在执行前暂停并询问你。各工具默认权限工具默认权限read、glob、grepaskedit、write、apply_patchaskbashask按命令逐条询问external_directoryask访问项目外路径时触发taskaskwebfetch、websearchasktodowrite、todoread、question、skillask开箱即用没有任何工具被自动批准auto-approved。你必须在配置中显式授予allow或在运行时逐个批准。运行时审批聊天面板中的Permission Dock浮动 UI 会显示每个待批准的调用对每次工具调用你可选择Approve once批准一次仅执行这一次调用Approve always总是批准将一条allow规则保存到配置中使后续匹配的调用自动放行Deny拒绝取消该工具调用。预先在配置文件中授权{ permission: { read: allow, glob: allow, grep: allow, edit: ask, bash: ask } }这一安全机制确保你对哪些文件被修改、哪些命令被执行、代码库如何被变更始终保有控制权。权限系统的源码落地从源码看权限检查由PermissionV2.Service统一承担每个工具的execute内都会调用permission.assert(...)传入action动作名如read、edit、bash、resources资源如文件路径、命令字符串或 glob 模式、save决定总是批准时保存哪条规则如[*]表示保存通配规则以及会话与代理上下文。总是批准保存的规则最终持久化到 SQLite 的permission表中该表以project_id action resource作为唯一索引sql.ts这意味着授权规则按项目 × 动作 × 资源粒度生效——你批准的是某个项目里某个动作对某个资源的放行而不是全局无差别放行。双重审批外部目录与工具动作从read、edit、write、bash的实现可以归纳出一个共同的审批模式先做外部目录检查再做工具动作检查。当路径解析LocationMutation.resolve发现目标位于活动 Location 之外时会先触发external_directory权限检查通过后才进入工具自身动作read/edit/bash等的权限检查。这意味着访问项目外的文件需要两道独立的审批为跨目录操作提供了更细粒度的安全边界。从源码理解工具是如何被定义与注册的如果你希望从底层理解 Kilo Code 的工具体系可以顺着这条调用链阅读源码定义每个工具调用Tool.make({ description, input, output, execute })声明契约input/output使用 Effect Schema 描述并自动转换为 JSON Schema 供模型调用tool.ts注册工具通过Tools.Service.register({ name: tool })注册到全局工具注册表名称需匹配^[A-Za-z][A-Za-z0-9_-]{0,63}$的校验规则tool.ts权限装饰需要绑定特定权限动作的工具使用Tool.withPermission(tool, edit)装饰如edit与write都绑定到edit动作write.ts执行闭环模型发起调用后settle负责输入解码 → 权限检查 → 执行 → 输出编码 → 生成模型可读内容文本或文件内容的完整流程tool.ts。所有工具的实现文件统一位于 packages/core/src/tool 目录对应的测试覆盖在 packages/core/test/tool-*.test.ts 系列测试文件中例如tool-bash.test.ts、tool-edit.test.ts、tool-read.test.ts、tool-read-filesystem.test.ts、tool-question.test.ts、tool-todowrite.test.ts、tool-webfetch.test.ts、tool-websearch.test.ts、tool-write.test.ts可供进一步验证各工具的边界行为。小结Kilo Code 的工具体系围绕选择 → 审查 → 执行 → 循环的工作流展开通过五大类别Read、Edit、Execute、Web、Workflow覆盖开发自动化的主要场景。其安全模型以默认全部ask为底线辅以外部目录 工具动作的双重审批与按项目粒度的持久化授权规则确保任何文件修改、命令执行和代码变更都在你的掌控之中。理解每个工具的参数与默认行为是安全、高效驾驭 Kilo Code 自动化能力的前提。【免费下载链接】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），仅供参考