企业官网建设流程全解析

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/kilocode

Kilo 的 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：以基本相同的语义移植到 V2
• remove：不再向前携带
• 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）：

1. 全局 Kilo 配置目录；
2. 祖先项目目录；
3. .kilo或遗留.kilocode配置目录。

值得注意的是：Kilo 刻意忽略.opencode目录。这意味着迁移到 Kilo 的项目不会意外读取 opencode 的配置目录，两者配置空间被显式隔离。

Group 1：文件元数据

$schema是唯一存活在 Group 1 的字段。设计约束很明确：加载器只消费它，绝不回写。

Group 2：进程与服务设置

这组决策体现了两条重要原则：没有运行时消费者的配置不移植（logLevel），加载时序上无法生效的配置不移植（server，因为配置加载晚于服务启动）。autoupdate的三态设计（true/false/"notify"）则把"自动更新"与"仅通知"区分开。

Group 3：命令与项目资源

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：插件

插件加载具有路径源与作用域敏感行为，因此单独评审。插件顺序是 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：文件系统与工具运行时

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是唯一的会话分享设置："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 7：Provider 与模型选择

这是新 core 已开始动工的分组，也是 V2 配置重构幅度最大的区域。

策略化 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 option）；catalog 状态提供空默认值并按配置顺序合并补丁。

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/body，ConfigV2.Model.Cost支持tier（type: "context"+size）、input、output、可选cache（read/write），ConfigV2.Model.Limit含context/input/output三个可选整数，Model 本体还带variants数组与disabled开关——这正是文档所述"补丁合并、catalog 提供默认值"的落点。

Group 8：Agent 与权限

顶层选择器与别名的清理

default_agent不在 v2 agent 设计之前移植——遗留运行时用它选择可见的非子 agent 回退（替代build），但以孤立顶层字段暴露该选择会在 agent 与策略面尚未共同定义前，过早锁定遗留 agent 模型。

mode不移植：遗留加载器已把该废弃别名合并进agent，V2 只应暴露一个 agent 定义编写面。

agents 复数化与字段重塑

agent改复数agents，因为它是按 agent 名键控的集合。继续支持覆盖内置 agent（build、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 条目别名）：遗留加载器已把工具布尔值转换为权限规则（包括把写相关工具名折叠进edit），V2 应避免携带这个有损兼容输入。

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）

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显式禁用 OAuth；callback_port被 Schema 约束在 1–65535 区间。

Group 10：会话生命周期（compaction）

压缩能力保留，但含义不清的限额被重新设计。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是死选项（stretch 已固定）、batch_tool是已下线的功能、openTelemetry与粘贴摘要属于进程/UI 层职责、工具门控统一收敛到 permissions、mcp_timeout则被 Group 9 的新超时模型吸收。

评审执行顺序

除非决策间出现明显的依赖关系，按以下顺序逐组推进：

1. File Metadata
2. Process And Server Settings
3. Providers And Model Selection
4. Commands And Project Resources
5. Plugins
6. Filesystem And Tool Runtime
7. Sharing And Identity
8. Agents And Permissions
9. Integrations
10. Conversation Lifecycle
11. Deprecated And Experimental Settings

Provider 分组（第 3 位）提前到项目资源之前，因为新 core 已在此处开工；Deprecated 分组殿后，避免未讨论的新决策被惯性带偏。

总结：V2 配置设计的四条主线

回看整个评审，可以提炼出 Kilo V2 配置面的四条设计主线：

1. 按运行时消费者裁决：logLevel、server因无消费者或加载时序问题被删除；model、shell因有明确消费路径被保留。
2. 能力迁移而非删除：command→ skills、disabled_providers/enabled_providers→experimental.policies、tools→permissions、experimental.mcp_timeout→mcp.timeout。
3. 复数化与职责澄清：provider→providers、reference→references、plugin→plugins、attachment→attachments、agent→agents、permission→permissions，同时以disabled统一"保留但停用"语义。
4. 补丁式覆盖 + 目录发现：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