Kilo Code Agent 机制详解内置 Agent 切换方式、工具权限模型与源码实现【免费下载链接】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本文以 Kilo Code 官方文档《Using Agents》为主线系统讲解 Agent智能体的概念与价值、VSCode 与 CLI 两种环境下的切换方式、内置 Agentcode / ask / plan / debug / orchestrator各自的工具权限边界并结合当前仓库源码agent/index.ts、agent.ts还原每个 Agent 权限配置的真实实现帮助读者既会用、又知其然亦知其所以然。1. Agent 是什么任务特化的行为人格Kilo Code 中的 Agent 是一种特化人格specialized persona用于把助手的整体行为适配到当前任务。每个 Agent 拥有不同的能力范围、专业定位和访问权限级别帮助你完成具体目标。相比一个全能助手应对所有场景Agent 机制带来四点实际收益任务特化Task specialization针对当前任务获得恰到好处的协助类型而不是泛泛的通用回答安全控制Safety controls在专注规划或学习时防止助手无意间修改文件——例如 ask 模式下所有写操作在权限层被直接拒绝聚焦交互Focused interactions回复内容针对当前活动优化调试模式用系统化排查方法规划模式用架构师视角工作流优化Workflow optimization在规划、实现、调试、学习之间无缝流转而不必重新解释约束。从源码结构看Agent 的核心定义位于 agent.ts 中的Info数据结构每个 Agent 由name、modeprimary/subagent/all、permission权限规则集、可选的prompt系统提示词、model、temperature等字段构成。Kilo 特有的扩展则集中在 kilocode/agent/index.ts 的patchAgents函数中——它在上游 Agent 映射之上重命名、打补丁并追加 Kilo 专属 Agent这正是下文所有内置 Agent 行为差异的根源。2. 切换 Agent 的操作方式2.1 VSCode 扩展下拉菜单点击侧边栏的 Agent 选择器在下拉列表中直接切换斜杠命令在聊天输入框输入/agents打开 Agent 选择器键盘快捷键按Cmd.macOS或Ctrl.Windows/Linux在可用 Agent 间正向循环切换加上Shift则反向循环。快捷键背后是扩展注册的两条命令kilo-code.new.cycleAgentMode与kilo-code.new.cyclePreviousAgentMode定义于 package.json在 extension.ts 中注册并向 webview 发送cycleAgentMode/cyclePreviousAgentMode动作消息cycleAgent的纯函数逻辑有专门测试覆盖见 session-agent.test.ts。2.2 CLITUI循环切换按Tab正向切换 AgentShiftTab反向切换Agent 选择器按CtrlX aleader 键 a打开完整 Agent 列表斜杠命令在聊天输入框输入/agents打开 Agent 选择器配置文件在配置文件中设置default_agent键改变启动时的默认 Agent。default_agent的解析逻辑在 agent.ts 的defaultInfo中配置了default_agent时先经KiloAgent.resolveKey做向后兼容映射build→code随后做三项校验——Agent 不存在、是subagent模式、或hidden为 true 都会直接抛错未配置时优先回退到code。因此子 Agent如 explore不能被设为默认 Agent这是配置时需要了解的硬性约束。3. 内置 Agent 全解析VSCode 扩展与 CLI 提供的内置 Agent 基本一致下面按官方文档的维度描述 / 工具访问 / 适用场景 / 特性逐一展开并在源码佐证部分给出权限配置的真实位置。3.1 code默认 Agent维度说明描述精通编程语言、设计模式与最佳实践的资深软件工程师工具访问全部工具read、edit、glob、grep、bash、task、webfetch外加 MCP 服务器提供的工具适用场景写代码、实现功能、调试、日常开发特性无工具限制全编码任务均可自由使用源码佐证code由上游的buildAgent 重命名而来。patchAgentsagent/index.ts把agents.build复制为agents.code、合并semantic_search: allow后删除原键配置中的agent.build键也会经preprocessConfig映射为code保证旧配置继续可用。默认权限基线在 agent.ts 的baseDefaults中全局*放行、.env系列文件读取需询问、question/plan_enter默认拒绝但 code 模式放开为允许。3.2 ask只读问答维度说明描述专注回答问题、不改动代码库的有学识技术助手工具访问只读工具read、glob、grep、list、只读 bash 命令cat、grep、git log、git diff、jq等、MCP 工具每次调用需用户批准所有写操作被阻止适用场景代码讲解、概念探索、技术学习、项目调研特性可运行只读命令、检查项目而不做任何修改MCP 工具每次调用都要批准源码佐证ask 的权限守卫askGuardagent/index.ts先整体*拒绝再逐项放开read/grep/glob/list/webfetch/websearch等只读能力edit由askEditGuard单独封死。只读 bash 清单readOnlyBash是白名单 黑名单双层设计白名单cat、head、ls、rg、jq、sort、git log/show/diff/status/blame等纯查看命令放行黑名单纵深防御源码注释明确写了这不是沙箱*|*、*;*、**、**、*$(*、反引号、rg --pre、sort -o等规则专门堵死白名单命令通过管道、重定向、子 shell 偷偷写文件或执行任意程序的绕过路径。MCP 工具每次批准来自getMcpRules它遍历cfg.mcp中的每个服务器生成sanitized_server_*: ask的通配规则agent/index.ts即 MCP 工具默认不拒绝但每次都要询问。另外有一个有意思的实现细节ask 的系统提示词会根据客户端调整——VSCode 与 JetBrains 客户端mermaidClients允许使用 Mermaid 图CLI 则把提示词中的该条替换为CLI 无法渲染 Mermaid请改用纯文本/ASCII 图agent/index.ts。3.3 plan规划维度说明描述帮助设计系统、制定实施计划的资深技术负责人与规划者工具访问只读工具外加受限制的文件编辑只能写.kilo/plans/下的计划文件适用场景系统设计、高层规划、架构讨论特性类似旧扩展的 Architect 模式规划导向源码佐证plan 的编辑边界由planEditRulesagent/index.ts精确限定——全局edit: *: deny然后仅放行.kilo/plans/*.md、plans/*.md、.plans/*.md、.opencode/plans/*.md以及全局数据目录下相对 worktree 的plans/*.md。planGuard还允许task除general外即 plan 可以委派子任务但不能委派给通用 Agent、plan_exit/open_plan用于退出规划模式以及全部只读工具。值得注意的是hardenPlanagent/index.ts这些编辑限制只对内置的plannative: true生效是权限的天花板——用户自定义的agent.plan配置会复用内置对象、天花板依然生效而自定义的architectAgent 则完全由自己的 permission 配置管辖。3.4 debug调试维度说明描述专攻系统化排障与诊断的专家型问题解决者工具访问全部工具的完整访问权限适用场景追踪 Bug、诊断错误、解决复杂问题特性采用分析 → 缩小可能性范围 → 修复的方法论流程源码佐证debug Agent 在 agent/index.ts 中注入权限为默认基线合并question、suggest、plan_enter、semantic_search全放行——也就是说它与 code 一样拥有完整工具能力差异主要体现在PROMPT_DEBUG系统提示词带来的调试方法论上。3.5 orchestrator已弃用维度说明描述战略性工作流编排者通过把复杂任务委派给合适的特化 Agent 来协调执行工具访问仅限创建新任务、协调工作流的受限访问适用场景把复杂项目拆解为可管理的子任务并分配给特化 Agent特性把工作委派给其他 Agent还拥有explore子 Agent 用于代码库探索警告Orchestrator 已弃用将在未来版本移除。拥有完整工具访问的 AgentCode、Plan、Debug现在原生支持子 Agentsubagents不再需要专职的编排者。迁移细节见 Orchestrator Mode (Deprecated)。源码佐证与文档一致orchestrator 在patchAgents中被标记deprecated: trueagent/index.ts。其权限模型可精确概括为*拒绝、只读工具与task: allow、todoread/todowrite放行最后在用户配置之后强制bash: deny注释明确写着防止用户配置重新开启 shell。说明VSCode 扩展与 CLI 均不提供内置的 Review Agent。代码评审工作流可由codeAgent 承担或通过自定义 Agent 配置实现。3.6 隐藏的内置系统 Agent源码中还存在若干文档未列出、但会出现在 Agent 列表内部的隐藏hidden: trueAgent如compaction上下文压缩、title会话标题、summary摘要。hardenSystemAgentsagent/index.ts会在所有配置合并完成后把它们的权限重置为全局拒绝*: deny确保用户配置无法意外给系统工具 Agent 开洞——这解释了为什么它们不可作为默认 Agent、也不应被自定义。4. 安全边界的统一设计guarded 与 sealed阅读 kilocode/agent/index.ts 可以发现一套贯穿所有只读 Agent 的通用防护设计guarded列表定义了会变更工作区或执行代码的工具集合bash、task、notebook_edit、notebook_execute、write、agent_manager、repo_clone无论配置文件写了什么always allow包括代码模式的通配放行ask / plan 等只读模式都不会因此获得这些工具的执行权源码注释指出这是针对某次代码模式的通配 allow 意外把执行权交给 ask 和 plan问题的修复issue #12053并提供了官方逃生口通过agent.name.permission单独为某个模式解禁该规则在patchAgents之后合并因此优先级最高。从baseline函数的实现还能推断出权限合并的完整次序内置守卫规则 → 用户规则按安全工具名精确展开→ bash / MCP / guarded 天花板 → 用户 deny 规则最后落地。理解这个次序就能解释为什么我的 permission 配置在 ask 模式下不生效这类问题。5. 自定义 Agent从内置到自建官方文档指出通过定义工具访问、文件权限与行为指令你可以创建自己的特化助手。自定义 Agent 适合两类场景——强制团队标准例如统一禁止某类操作和构建目的特化的助手例如专门的评审、迁移、文档 Agent。结合源码自定义 Agent 的配置入口是agent.name配置块与独立的 markdown 源文件Agent 的移除逻辑会扫描{agent,agents}/**/*.md与{mode,modes}/*.md等路径见 agent/index.ts。配置项可覆盖model、variant、prompt、description、temperature、top_p、mode、color、hidden、name、steps、options与permission逐项见 agent.ts 的合并逻辑设置disable: true可整体禁用某个 Agent包括内置 Agent。完整搭建步骤请参见 Custom Modes 文档相关配套文档包括 Agent 权限、自定义子 Agent 与 AGENTS.md。此外default_agent等配置项的完整说明可参考 kilo-config 技能文档 中的配置表其记载default_agent为默认主 Agent回退值为code。6. 延伸阅读Session Goals若希望一个 Agent 在多轮对话中持续朝着单一目标推进见 Session Goals 文档Orchestrator 迁移正在使用 orchestrator 工作流的用户见 Orchestrator Mode (Deprecated) 获取迁移指引源码入口权限模型与内置 Agent 定义集中在 packages/opencode/src/kilocode/agent/index.tsAgent 服务与默认选择逻辑在 packages/opencode/src/agent/agent.tsVSCode 侧切换命令在 packages/kilo-vscode/src/extension.ts。小结Kilo Code 的 Agent 机制本质上是人格prompt× 权限permission× 模型参数的可组合单元code 提供全工具默认能力ask 用白名单 纵深防御黑名单保证只读问答plan 把写权限收窄到.kilo/plans/目录debug 以方法论提示词驱动系统化排障而 orchestrator 作为过渡形态已被原生子 Agent 能力取代并标记弃用。掌握这些 Agent 的权限边界与切换方式Cmd./Ctrl.、Tab/ShiftTab、CtrlX a、/agents、default_agent并理解guarded/harden系列防护的实现意图就能把选对 Agent变成 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），仅供参考 
长河君 · 2026/9/13 11:07:24 · 阅读 1.2k Kilo Code Agent 机制详解：内置 Agent 切换方式、工具权限模型与源码实现
Kilo Code Agent 机制详解内置 Agent 切换方式、工具权限模型与源码实现【免费下载链接】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本文以 Kilo Code 官方文档《Using Agents》为主线系统讲解 Agent智能体的概念与价值、VSCode 与 CLI 两种环境下的切换方式、内置 Agentcode / ask / plan / debug / orchestrator各自的工具权限边界并结合当前仓库源码agent/index.ts、agent.ts还原每个 Agent 权限配置的真实实现帮助读者既会用、又知其然亦知其所以然。1. Agent 是什么任务特化的行为人格Kilo Code 中的 Agent 是一种特化人格specialized persona用于把助手的整体行为适配到当前任务。每个 Agent 拥有不同的能力范围、专业定位和访问权限级别帮助你完成具体目标。相比一个全能助手应对所有场景Agent 机制带来四点实际收益任务特化Task specialization针对当前任务获得恰到好处的协助类型而不是泛泛的通用回答安全控制Safety controls在专注规划或学习时防止助手无意间修改文件——例如 ask 模式下所有写操作在权限层被直接拒绝聚焦交互Focused interactions回复内容针对当前活动优化调试模式用系统化排查方法规划模式用架构师视角工作流优化Workflow optimization在规划、实现、调试、学习之间无缝流转而不必重新解释约束。从源码结构看Agent 的核心定义位于 agent.ts 中的Info数据结构每个 Agent 由name、modeprimary/subagent/all、permission权限规则集、可选的prompt系统提示词、model、temperature等字段构成。Kilo 特有的扩展则集中在 kilocode/agent/index.ts 的patchAgents函数中——它在上游 Agent 映射之上重命名、打补丁并追加 Kilo 专属 Agent这正是下文所有内置 Agent 行为差异的根源。2. 切换 Agent 的操作方式2.1 VSCode 扩展下拉菜单点击侧边栏的 Agent 选择器在下拉列表中直接切换斜杠命令在聊天输入框输入/agents打开 Agent 选择器键盘快捷键按Cmd.macOS或Ctrl.Windows/Linux在可用 Agent 间正向循环切换加上Shift则反向循环。快捷键背后是扩展注册的两条命令kilo-code.new.cycleAgentMode与kilo-code.new.cyclePreviousAgentMode定义于 package.json在 extension.ts 中注册并向 webview 发送cycleAgentMode/cyclePreviousAgentMode动作消息cycleAgent的纯函数逻辑有专门测试覆盖见 session-agent.test.ts。2.2 CLITUI循环切换按Tab正向切换 AgentShiftTab反向切换Agent 选择器按CtrlX aleader 键 a打开完整 Agent 列表斜杠命令在聊天输入框输入/agents打开 Agent 选择器配置文件在配置文件中设置default_agent键改变启动时的默认 Agent。default_agent的解析逻辑在 agent.ts 的defaultInfo中配置了default_agent时先经KiloAgent.resolveKey做向后兼容映射build→code随后做三项校验——Agent 不存在、是subagent模式、或hidden为 true 都会直接抛错未配置时优先回退到code。因此子 Agent如 explore不能被设为默认 Agent这是配置时需要了解的硬性约束。3. 内置 Agent 全解析VSCode 扩展与 CLI 提供的内置 Agent 基本一致下面按官方文档的维度描述 / 工具访问 / 适用场景 / 特性逐一展开并在源码佐证部分给出权限配置的真实位置。3.1 code默认 Agent维度说明描述精通编程语言、设计模式与最佳实践的资深软件工程师工具访问全部工具read、edit、glob、grep、bash、task、webfetch外加 MCP 服务器提供的工具适用场景写代码、实现功能、调试、日常开发特性无工具限制全编码任务均可自由使用源码佐证code由上游的buildAgent 重命名而来。patchAgentsagent/index.ts把agents.build复制为agents.code、合并semantic_search: allow后删除原键配置中的agent.build键也会经preprocessConfig映射为code保证旧配置继续可用。默认权限基线在 agent.ts 的baseDefaults中全局*放行、.env系列文件读取需询问、question/plan_enter默认拒绝但 code 模式放开为允许。3.2 ask只读问答维度说明描述专注回答问题、不改动代码库的有学识技术助手工具访问只读工具read、glob、grep、list、只读 bash 命令cat、grep、git log、git diff、jq等、MCP 工具每次调用需用户批准所有写操作被阻止适用场景代码讲解、概念探索、技术学习、项目调研特性可运行只读命令、检查项目而不做任何修改MCP 工具每次调用都要批准源码佐证ask 的权限守卫askGuardagent/index.ts先整体*拒绝再逐项放开read/grep/glob/list/webfetch/websearch等只读能力edit由askEditGuard单独封死。只读 bash 清单readOnlyBash是白名单 黑名单双层设计白名单cat、head、ls、rg、jq、sort、git log/show/diff/status/blame等纯查看命令放行黑名单纵深防御源码注释明确写了这不是沙箱*|*、*;*、**、**、*$(*、反引号、rg --pre、sort -o等规则专门堵死白名单命令通过管道、重定向、子 shell 偷偷写文件或执行任意程序的绕过路径。MCP 工具每次批准来自getMcpRules它遍历cfg.mcp中的每个服务器生成sanitized_server_*: ask的通配规则agent/index.ts即 MCP 工具默认不拒绝但每次都要询问。另外有一个有意思的实现细节ask 的系统提示词会根据客户端调整——VSCode 与 JetBrains 客户端mermaidClients允许使用 Mermaid 图CLI 则把提示词中的该条替换为CLI 无法渲染 Mermaid请改用纯文本/ASCII 图agent/index.ts。3.3 plan规划维度说明描述帮助设计系统、制定实施计划的资深技术负责人与规划者工具访问只读工具外加受限制的文件编辑只能写.kilo/plans/下的计划文件适用场景系统设计、高层规划、架构讨论特性类似旧扩展的 Architect 模式规划导向源码佐证plan 的编辑边界由planEditRulesagent/index.ts精确限定——全局edit: *: deny然后仅放行.kilo/plans/*.md、plans/*.md、.plans/*.md、.opencode/plans/*.md以及全局数据目录下相对 worktree 的plans/*.md。planGuard还允许task除general外即 plan 可以委派子任务但不能委派给通用 Agent、plan_exit/open_plan用于退出规划模式以及全部只读工具。值得注意的是hardenPlanagent/index.ts这些编辑限制只对内置的plannative: true生效是权限的天花板——用户自定义的agent.plan配置会复用内置对象、天花板依然生效而自定义的architectAgent 则完全由自己的 permission 配置管辖。3.4 debug调试维度说明描述专攻系统化排障与诊断的专家型问题解决者工具访问全部工具的完整访问权限适用场景追踪 Bug、诊断错误、解决复杂问题特性采用分析 → 缩小可能性范围 → 修复的方法论流程源码佐证debug Agent 在 agent/index.ts 中注入权限为默认基线合并question、suggest、plan_enter、semantic_search全放行——也就是说它与 code 一样拥有完整工具能力差异主要体现在PROMPT_DEBUG系统提示词带来的调试方法论上。3.5 orchestrator已弃用维度说明描述战略性工作流编排者通过把复杂任务委派给合适的特化 Agent 来协调执行工具访问仅限创建新任务、协调工作流的受限访问适用场景把复杂项目拆解为可管理的子任务并分配给特化 Agent特性把工作委派给其他 Agent还拥有explore子 Agent 用于代码库探索警告Orchestrator 已弃用将在未来版本移除。拥有完整工具访问的 AgentCode、Plan、Debug现在原生支持子 Agentsubagents不再需要专职的编排者。迁移细节见 Orchestrator Mode (Deprecated)。源码佐证与文档一致orchestrator 在patchAgents中被标记deprecated: trueagent/index.ts。其权限模型可精确概括为*拒绝、只读工具与task: allow、todoread/todowrite放行最后在用户配置之后强制bash: deny注释明确写着防止用户配置重新开启 shell。说明VSCode 扩展与 CLI 均不提供内置的 Review Agent。代码评审工作流可由codeAgent 承担或通过自定义 Agent 配置实现。3.6 隐藏的内置系统 Agent源码中还存在若干文档未列出、但会出现在 Agent 列表内部的隐藏hidden: trueAgent如compaction上下文压缩、title会话标题、summary摘要。hardenSystemAgentsagent/index.ts会在所有配置合并完成后把它们的权限重置为全局拒绝*: deny确保用户配置无法意外给系统工具 Agent 开洞——这解释了为什么它们不可作为默认 Agent、也不应被自定义。4. 安全边界的统一设计guarded 与 sealed阅读 kilocode/agent/index.ts 可以发现一套贯穿所有只读 Agent 的通用防护设计guarded列表定义了会变更工作区或执行代码的工具集合bash、task、notebook_edit、notebook_execute、write、agent_manager、repo_clone无论配置文件写了什么always allow包括代码模式的通配放行ask / plan 等只读模式都不会因此获得这些工具的执行权源码注释指出这是针对某次代码模式的通配 allow 意外把执行权交给 ask 和 plan问题的修复issue #12053并提供了官方逃生口通过agent.name.permission单独为某个模式解禁该规则在patchAgents之后合并因此优先级最高。从baseline函数的实现还能推断出权限合并的完整次序内置守卫规则 → 用户规则按安全工具名精确展开→ bash / MCP / guarded 天花板 → 用户 deny 规则最后落地。理解这个次序就能解释为什么我的 permission 配置在 ask 模式下不生效这类问题。5. 自定义 Agent从内置到自建官方文档指出通过定义工具访问、文件权限与行为指令你可以创建自己的特化助手。自定义 Agent 适合两类场景——强制团队标准例如统一禁止某类操作和构建目的特化的助手例如专门的评审、迁移、文档 Agent。结合源码自定义 Agent 的配置入口是agent.name配置块与独立的 markdown 源文件Agent 的移除逻辑会扫描{agent,agents}/**/*.md与{mode,modes}/*.md等路径见 agent/index.ts。配置项可覆盖model、variant、prompt、description、temperature、top_p、mode、color、hidden、name、steps、options与permission逐项见 agent.ts 的合并逻辑设置disable: true可整体禁用某个 Agent包括内置 Agent。完整搭建步骤请参见 Custom Modes 文档相关配套文档包括 Agent 权限、自定义子 Agent 与 AGENTS.md。此外default_agent等配置项的完整说明可参考 kilo-config 技能文档 中的配置表其记载default_agent为默认主 Agent回退值为code。6. 延伸阅读Session Goals若希望一个 Agent 在多轮对话中持续朝着单一目标推进见 Session Goals 文档Orchestrator 迁移正在使用 orchestrator 工作流的用户见 Orchestrator Mode (Deprecated) 获取迁移指引源码入口权限模型与内置 Agent 定义集中在 packages/opencode/src/kilocode/agent/index.tsAgent 服务与默认选择逻辑在 packages/opencode/src/agent/agent.tsVSCode 侧切换命令在 packages/kilo-vscode/src/extension.ts。小结Kilo Code 的 Agent 机制本质上是人格prompt× 权限permission× 模型参数的可组合单元code 提供全工具默认能力ask 用白名单 纵深防御黑名单保证只读问答plan 把写权限收窄到.kilo/plans/目录debug 以方法论提示词驱动系统化排障而 orchestrator 作为过渡形态已被原生子 Agent 能力取代并标记弃用。掌握这些 Agent 的权限边界与切换方式Cmd./Ctrl.、Tab/ShiftTab、CtrlX a、/agents、default_agent并理解guarded/harden系列防护的实现意图就能把选对 Agent变成 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），仅供参考