Kilo V2 配置架构重构指南从遗留 Schema 到 11 组配置评审全景【免费下载链接】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 的 V2 配置评审文档specs/v2/config.md将遗留配置 schema 拆分为 11 个独立评审分组逐字段裁定原样保留keep删除remove重新设计redesign。本文以该文档为主线结合仓库内packages/core/src/config/下的 V2 Schema 实现agent、mcp、provider、compaction、permission 等进行源码级印证帮助你理解 Kilo V2 配置面的设计取向哪些遗留字段被继承、哪些被废弃、哪些被重塑以及每一项决策背后的运行时理由。评审方法论四类状态标签文档将每个遗留字段的状态标记为四种之一这是整个评审的组织骨架pending尚未讨论keep以基本相同的语义移植到 V2remove不再向前携带redesign保留能力但改变形态、作用域或归属模块阅读表格时请注意remove不等于功能消失很多被删除的字段其能力被迁移到了更合理的归属模块例如command移入 skills、disabled_providers移入experimental.policies。Schema 范围与配置文档发现机制V2 现阶段只维护一个统一的配置 schema。部分字段如autoupdate本质上属于全局/用户级配置但在没有足够收益之前暂不强行拆分 global 与 location 两套 schema——只有当评审存活下来的字段中出现更多作用域敏感项时才会重新考虑拆分。V2 core 会按以下顺序发现配置文档命名为config.json、kilo.json、kilo.jsonc、opencode.json或opencode.jsonc全局 Kilo 配置目录祖先项目目录.kilo或遗留.kilocode配置目录。值得注意的是Kilo 刻意忽略.opencode目录。这意味着迁移到 Kilo 的项目不会意外读取 opencode 的配置目录两者配置空间被显式隔离。Group 1文件元数据字段现状用途状态备注$schema供编辑器校验与补全的 JSON schema 引用keep只读元数据加载配置时不得为它插入或创建文件$schema是唯一存活在 Group 1 的字段。设计约束很明确加载器只消费它绝不回写。Group 2进程与服务设置字段现状用途状态备注shell终端与 shell 工具执行的默认 shellkeep作为有效配置移植共享的 shell 选择贯穿 opencodelogLevel日志级别配置remove无配置消费者日志由 CLI 输入初始化server主机名、端口、mDNS 与 CORSremovelocation 配置在 server 启动之后才加载autoupdate自动更新或通知行为keep仅限全局用户偏好保留true、false、notify三态这组决策体现了两条重要原则没有运行时消费者的配置不移植logLevel加载时序上无法生效的配置不移植server因为配置加载晚于服务启动。autoupdate的三态设计true/false/notify则把自动更新与仅通知区分开。Group 3命令与项目资源字段现状用途状态备注command用户自定义命令remove不再作为 v2 配置具名可复用工作流归属 skillsskills附加 skill 位置redesign将{ paths?, urls? }替换为本地路径或远程 URL 发现源的单数组reference具名 git 或本地目录引用redesign改复数references保留本地路径与 Git 仓库外部上下文条目instructions附加环境指令源keep保留为本地路径、glob 或远程 URL 的单一数组自动包含为上下文command明确不移植V2不暴露独立的用户命令配置。具名可复用提示词工作流由 skills 承担无论用户直接调用还是由 agent 加载。内部命令路由与内置命令仍可作为运行时关注点存在但不会创造command或commands配置字段。这意味着遗留 command-only 行为全部不移植包括per-command 的model、agent、subtask、提示词 shell 展开、位置/模板替换。如果 V2 需要类似能力应在所属领域内设计而不是通过第二套工作流定义系统保留。skills发现源而非内联定义skills保持为发现源配置skill 内容仍归属SKILL.md。每个条目要么是本地搜索根要么是远程发现 URL直接调用行为可另行设计不扩大配置形态{ skills: [./team-skills, ~/shared-skills, https://example.com/.well-known/skills/], }instructions与 skills 分离环境指令与 skills 分离是刻意为之instructions 自动包含进模型上下文skills 则是按需加载或调用。每个源无歧义地是本地路径/glob 或 URL因此 V2 保留简单数组形态{ instructions: [ CONTRIBUTING.md, docs/guidelines.md, .cursor/rules/*.md, https://example.com/shared-rules.md, ], }注意这里的 glob.cursor/rules/*.md是受支持的混合同一数组内的多个本地路径与远程 URL 也是合法的。references复数化 紧凑字符串形式具名外部上下文引用保留为 V2 配置能力改为复数references因为它是按别名键控的集合。引用声明本地目录或 Git 仓库供 v2 runtime 将来以alias或alias/path寻址{ references: { design-system: { path: ../ui-library }, sdk: { repository: github.com/example/sdk, branch: main }, }, }同时保留紧凑字符串条目形式以.、/、~开头的值视为本地路径其他字符串视为 Git 仓库。Group 4插件字段现状用途状态备注plugin用户指定插件模块redesign改复数plugins保留有序加载支持包字符串或{ package, options? }条目插件加载具有路径源与作用域敏感行为因此单独评审。插件顺序是 V2 配置契约的一部分——hook 注册与执行可能依赖加载顺序。遗留的 option 元组被可读对象条目取代{ plugins: [ opencode-helicone-session, { package: my-org/audit-plugin, options: { endpoint: https://audit.example.com, }, }, ], }边界清晰plugins列表只表示包加载插件。本地插件代码仍从插件目录如.kilo/plugins/与遗留.kilocode/plugins/发现V2 不把任意的已配置本地路径或文件 URL 移植进该字段。Group 5文件系统与工具运行时字段现状用途状态备注watcher文件监听忽略模式keep保留{ ignore?: string[] }配置文件系统监听子系统snapshot文件系统快照追踪开关redesign改复数snapshots控制用于 undo/revert 的快照创建formatter格式化器配置keep保留单数boolean \| Recordstring, entry形态lsp语言服务器配置keep保留单数boolean \| Recordstring, entry形态自定义 server 需 command 与 extensionsattachment附件/图片处理配置redesign改复数attachments保留{ image?: { auto_resize?, max_width?, max_height?, max_base64_bytes? } }输入归一化限制tool_output工具输出截断限制keep保留{ max_lines?, max_bytes? }两个正阈值都作用于保存预览截断formatter与lsp各配置一个项目工具子系统单数命名仍然贴切。true启用内置注册、false禁用、键控对象则在启用内置的同时应用具名覆盖或自定义注册。自定义语言服务器必须声明extensions以保证运行时文件附件行为确定内置 server ID 的校验属于未来 v2 LSP 集成的职责而非聚合核心配置 schema。attachment改复数attachments的理由很关键该设置控制附件领域的处理未来可能扩展出图片之外的形态而单数attachment已被占用为模型能力标志表示某模型是否接受附件。{ formatter: { prettier: { disabled: true }, project: { command: [./scripts/format, $FILE], extensions: [.foo] }, }, lsp: { typescript: { disabled: true }, project: { command: [project-language-server, --stdio], extensions: [.foo] }, }, attachments: { image: { auto_resize: true, max_width: 2000, max_height: 2000 }, }, tool_output: { max_lines: 2000, max_bytes: 51200 }, }从 config/formatter.ts 与 config/lsp.ts 等 V2 Schema 实现可以看到这类子系统配置均以独立的 Schema.Class 承载disabled是统一的保留配置但停用开关。Group 6分享与身份字段现状用途状态备注share会话分享行为keep保留manual \| auto \| disabled控制手动分享权限与新会话自动分享autoshare遗留自动分享标志remove不移植废弃别名用share: autoenterprise企业 URL 配置keep保留{ url?: string }无组织账号时选择遗留分享服务端点username会话与遥测中的显示用户名keep保留字符串身份覆盖运行时默认解析操作系统用户名share是唯一的会话分享设置manual允许显式分享auto自动分享新建的顶层会话disabled禁止分享。遗留autoshare: true只是share: auto的别名V2 不再暴露。enterprise.url与username均与服务器认证凭据分离——username标识会话与遥测中的用户而不是 HTTP basic-auth 配置。{ share: disabled, enterprise: { url: https://share.example.com }, username: developer, }Group 7Provider 与模型选择这是新 core 已开始动工的分组也是 V2 配置重构幅度最大的区域。字段现状用途状态备注provider自定义 provider 与模型覆盖redesignV2 改复数providers不保留遗留单数键disabled_providers禁用自动加载的 providerredesign用experimental.policies: [{ effect: deny, action: provider.use, resource: ... }]取代enabled_providers将启用 provider 限制为白名单redesign用有序provider.useallow/deny 语句与通配 resource 取代model默认模型选择keep作为活动会话或 agent 未指定模型时的回退模型small_model小模型/工具模型选择remove唯一运行时消费者是标题生成可改用显式titleagent 模型覆盖策略化 provider 选择provider 选择规则归属experimental.policies而非 provider 条目或反复出现的顶层 provider 字段。初始提议形态{ experimental: { policies: [ { effect: deny, action: provider.use, resource: *, }, { effect: allow, action: provider.use, resource: anthropic, }, ], }, }策略语义与优先级规则详见 specs/v2/provider-policy.md。策略求值将按逆序消费已编写的配置文档同时保持文档内语句顺序.kilo与遗留.kilocode策略源的优先级待 Kilo 配置评审后确定。providers 复数化与 model 回退V2 使用复数providers键与遗留单数provider刻意不同且在配置面尚未定型前不添加兼容别名。model保留为默认模型回退它是应用级行为用于活动会话或 agent 无显式模型选择时因此不属于任何单个 provider 配置。small_model不移植。当前运行时仅在生成会话标题时读取它优先级为titleagent 模型 →small_model→ 自动/当前模型回退。V2 中需要特定标题模型的用户应直接配置titleagent而不是使用独立顶层模型设置。补丁式覆盖与模型嵌套字段provider、model、variant 及临时的 agentoptions都以**部分补丁partial patch**形式编写而非完整物化的运行时 option 记录。用户只需设置所需覆盖项如一个 header 或一个 AI SDK request optioncatalog 状态提供空默认值并按配置顺序合并补丁。provider 的env保留为已识别凭据环境变量名的编写列表。内置 catalog provider 已携带该元数据用于自动环境支持的可用性判断配置 provider 可能声明相同来源对配置 provider 而言这是附加元数据不要求变量实际存在——provider 可能通过配置 options、已存账号或无需凭据的端点使用。配置模型内部遗留上游模型标识符id嵌套到api.id与其余模型 API 覆盖项并列。limit是编写补丁覆盖项可只改context、input或output之一。cost接受单个简单定价对象或分层定价数组省略的缓存价格默认零。明确不移植遗留 provider model 的reasoning、temperature、interleaved标志属结构化options或模型 variants、release_date、status、experimental、whitelist、blacklist。{ providers: { internal: { env: [INTERNAL_LLM_API_KEY], options: { headers: { Authorization: Bearer {env:API_KEY} } }, models: { chat: { api: { id: upstream-chat-model }, limit: { output: 32768 }, cost: { input: 1.25, output: 10 }, variants: [{ id: high, aisdk: { request: { reasoningEffort: high } } }], }, }, }, }, }仓库中的 config/provider.ts 与文档提议的形态高度吻合ConfigProvider.Request定义headers/bodyConfigV2.Model.Cost支持tiertype: contextsize、input、output、可选cacheread/writeConfigV2.Model.Limit含context/input/output三个可选整数Model 本体还带variants数组与disabled开关——这正是文档所述补丁合并、catalog 提供默认值的落点。Group 8Agent 与权限字段现状用途状态备注default_agent选择默认主 agentremove不保留独立顶层选择器默认选择应随 v2 agent 配置模型一并设计mode遗留 agent 配置别名remove不移植废弃别名仅通过 v2 agent 面配置agent主 agent、子 agent 与专用 agent 配置redesign改复数agents保留内置覆盖与自定义 agent 定义的具名映射permission工具权限规则redesign改复数permissions以有序{ action, resource, effect }规则数组取代遗留 map 简写tools遗留工具开关 mapremove不移植布尔开关别名工具访问通过 permissions 表达顶层选择器与别名的清理default_agent不在 v2 agent 设计之前移植——遗留运行时用它选择可见的非子 agent 回退替代build但以孤立顶层字段暴露该选择会在 agent 与策略面尚未共同定义前过早锁定遗留 agent 模型。mode不移植遗留加载器已把该废弃别名合并进agentV2 只应暴露一个 agent 定义编写面。agents 复数化与字段重塑agent改复数agents因为它是按 agent 名键控的集合。继续支持覆盖内置 agentbuild、plan、title与声明具名自定义 agent。agents.name.mode保留取值为primary、subagent或all标识 agent 的运行时角色它与被删除的顶层遗留mode别名agent 定义的另一个容器无关。跨 V2 命名条目统一使用disabled?: boolean表示保留配置但停用——因此 agent 定义将遗留disable重塑为disabled这与 formatter、语言服务器、未来 MCP server 定义及配置模型覆盖一致。运行时 catalog 状态仍可能以enabled追踪活跃可用性但那是内部状态而非用户编写配置。model与variant分离模型引用形如provider/model-id但模型 ID 本身可能含斜杠分段如openrouter/openai/gpt-5把 variant 追加进字符串会产生歧义。color保留agent 是用户可见的可选实体用户编写的显示色是合适的元数据保留 hex 颜色与现有配置支持的主题色。仓库实现 config/agent.ts 中的ColorSchema 正是#RRGGBB十六进制正则与primary/secondary/accent/success/warning/error/info字面量的联合。options临时保留复用配置 provider/model 上可用的结构化形态headers、body、AI SDK provider/request 覆盖长期归属待团队评审因为可复用的 provider 专用预设可用 variants 建模。不保留专门的 agenttemperature或top_p字段。description、hidden、steps保留——它们定义 agent 的可发现性、可见性与迭代预算。遗留prompt改名system明确表示提供持久系统级 agent 内容避免与顶层环境instructions冲突。废弃的maxSteps由steps取代。{ agents: { reviewer: { model: openrouter/openai/gpt-5, variant: high, options: { headers: { x-agent: reviewer }, body: {}, aisdk: { provider: {}, request: { reasoningEffort: high } }, }, description: Review changes for correctness, system: Find regressions and missing tests., mode: subagent, color: warning, steps: 12, disabled: false, permissions: [{ action: edit, resource: *, effect: deny }], }, }, }注意 config/agent.ts 的InfoSchema 字段model、variant、request、system、description、mode、hidden、color、steps、disabled、permissions与上例逐项对应——文档中的options对象对应 Schema 中的request字段含headers/body/aisdk覆盖。permissions 规则集与 ask 效应tools不移植无论顶层还是 agent 条目别名遗留加载器已把工具布尔值转换为权限规则包括把写相关工具名折叠进editV2 应避免携带这个有损兼容输入。permission改复数permissions暴露PermissionV2.Ruleset已建模的归一化有序规则集。规则除allow、deny外保留交互式ask效应——这与experimental.policies不同provider 强制目前只需要 allow/deny 决策。同一permissions规则集形态也用于未来agents条目内部。{ permissions: [ { action: bash, resource: *, effect: ask }, { action: bash, resource: git status, effect: allow }, ], }从 permission.ts 的实现可以看到evaluate函数如何消费该规则集按规则列表倒序findLast找到首个 action 与 resource 同时通配匹配的规则若没有任何规则命中默认回退为{ action, resource: *, effect: ask }——这正是未授权即询问用户这一安全默认的源码依据。Group 9集成MCP字段现状用途状态备注mcpMCP server 定义与启用redesign保留 opencode 显式本地/远程 server 条目格式嵌套于mcp.servers不活跃条目用disabled超时默认值移入此处V2保留 opencode 的 MCP server 条目格式不采纳常见的mcpServers复制粘贴形态。本地 server 仍是显式type: local条目command 数组 environment远程 server 仍是显式type: remote条目url、headers、可选oauth。server 映射嵌套在mcp.servers下使超时默认值等协议级设置可共存于同一子系统。MCP 超时分为独立的启动与请求预算以毫秒计startup覆盖建立传输与完成 MCP 初始化request独立应用于初始化后的每个 MCP 请求。server 可只覆盖其一而不必重复另一个——config/mcp.ts 中ConfigV2.MCP.Timeout的startup/request均为可选PositiveInt正是该语义的 Schema 落点。{ mcp: { timeout: { startup: 30000, request: 300000 }, servers: { github: { type: local, command: [npx, -y, github/github-mcp-server], environment: { GITHUB_TOKEN: {env:GITHUB_TOKEN} }, disabled: false, timeout: { startup: 60000 }, }, docs: { type: remote, url: https://docs.example.com/mcp, headers: { Authorization: Bearer {env:DOCS_TOKEN} }, oauth: { client_id: {env:MCP_CLIENT_ID}, client_secret: {env:MCP_CLIENT_SECRET}, scope: read write, callback_port: 19876, redirect_uri: http://127.0.0.1:19876/mcp/oauth/callback, }, disabled: false, timeout: { request: 600000 }, }, }, }, }config/mcp.ts 进一步印证了文档之外的细节Local支持可选cwd相对路径从工作区目录解析Remote.oauth除对象外还允许字面量false显式禁用 OAuthcallback_port被 Schema 约束在 1–65535 区间。Group 10会话生命周期compaction字段现状用途状态备注compaction自动压缩、剪枝与上下文预留redesign保留的逐字历史归入keep上下文余量改名buffer压缩能力保留但含义不清的限额被重新设计。keep.tokens是序列化进文本压缩检查点的近期历史 token 预算buffer是预留的 token 余量使自动压缩在输入窗口耗尽前触发。{ compaction: { auto: true, prune: true, keep: { tokens: 2000, }, buffer: 10000, }, }config/compaction.ts 中的ConfigV2.CompactionSchema 与之一致auto、prune为布尔keep.tokens与buffer均为非负整数NonNegativeInt。Group 11废弃与实验性设置以下字段不因惯性移植每个都需要明确理由字段现状用途状态备注layout遗留布局选择remove不移植废弃选项始终使用 stretch 布局experimental.disable_paste_summary禁用粘贴内容摘要remove粘贴输入呈现行为归属 client/UI 面experimental.batch_tool启用批处理工具remove批处理工具已不是受支持功能experimental.openTelemetry启用 AI SDK 遥测 spanremove可观测性是进程级行为应使用标准 OpenTelemetry 环境或声明式配置experimental.primary_tools将工具限制到主 agentremove过时的门控agent 工具访问由 permissions 配置experimental.continue_loop_on_deny拒绝后继续循环remove不移植遗留拒绝工具循环行为experimental.mcp_timeoutMCP 请求超时redesign移入mcp.timeout.request默认与mcp.servers.name.timeout.requestper-server 覆盖这组决策的共性逻辑layout是死选项stretch 已固定、batch_tool是已下线的功能、openTelemetry与粘贴摘要属于进程/UI 层职责、工具门控统一收敛到 permissions、mcp_timeout则被 Group 9 的新超时模型吸收。评审执行顺序除非决策间出现明显的依赖关系按以下顺序逐组推进File MetadataProcess And Server SettingsProviders And Model SelectionCommands And Project ResourcesPluginsFilesystem And Tool RuntimeSharing And IdentityAgents And PermissionsIntegrationsConversation LifecycleDeprecated And Experimental SettingsProvider 分组第 3 位提前到项目资源之前因为新 core 已在此处开工Deprecated 分组殿后避免未讨论的新决策被惯性带偏。总结V2 配置设计的四条主线回看整个评审可以提炼出 Kilo V2 配置面的四条设计主线按运行时消费者裁决logLevel、server因无消费者或加载时序问题被删除model、shell因有明确消费路径被保留。能力迁移而非删除command→ skills、disabled_providers/enabled_providers→experimental.policies、tools→permissions、experimental.mcp_timeout→mcp.timeout。复数化与职责澄清provider→providers、reference→references、plugin→plugins、attachment→attachments、agent→agents、permission→permissions同时以disabled统一保留但停用语义。补丁式覆盖 目录发现provider/model/variant/agent options 以部分补丁编写并由 catalog 合并默认值配置文档在多级目录全局、祖先项目、.kilo/.kilocode中发现且刻意忽略.opencode。若需继续深入可对比 V1 侧的实现packages/core/src/v1/config/config.ts 及v1/config/目录下的子模块provider、permission、mcp、skills 等或阅读 provider 策略语义的配套文档 specs/v2/provider-policy.md。【免费下载链接】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），仅供参考
