企业官网建设流程全解析

Kilo Code 功能提案模板实战指南：用 Status 生命周期标签编写规范化的 Feature Proposal

【免费下载链接】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 文档仓库中的 功能提案模板 为主体，结合仓库内 4 个真实功能提案页面（Benchmarking、Agent Observability、Enterprise MCP Controls、Onboarding Improvements）的实践，系统讲解 Kilo Code 社区撰写功能设计提案（Feature Proposal）的章节结构与状态标注规范。读完本文，你将掌握 Proposal / Partial / Historical / Superseded 四种生命周期标签的选用规则，能够按模板的八段式结构撰写一份可评审、可追踪、可演进为 GitHub Issue 的功能设计文档。

模板在 Kilo Code 文档体系中的定位

Kilo Code 是一个开源的 agentic 工程平台（当前仓库包含 VS Code 扩展、CLI、Gateway、文档站点等大量包）。对于较大的功能，项目要求先编写工程规格说明（engineering spec）对齐需求，再进入实现。功能提案正是承载这类规格说明的文档形式。

在文档导航中，贡献指南首页 的 "Engineering Specs" 一节明确指出：For larger features, we write engineering specs to align on requirements before implementation. Check the Feature Proposals section to see planned features and learn how to contribute specs.

功能提案索引页 则给出了该板块的定位：

These pages contain design proposals and roadmaps for features under consideration or implementation. They are planning documents, not current-state architecture references. Each page records its implementation status near the top.

这句话点明了模板的两条核心设计原则：

1. 它们是规划文档，不是当前架构参考：提案页描述的是"计划中的形态"，读者不应将其当作已上线能力的权威文档；
2. 每个页面必须在顶部记录实现状态：这正是模板中 Status callout 存在的意义。

索引页末尾明确指引新功能设计使用模板：Use the proposal template for new feature designs.

Status callout：提案的生命周期标签

模板的第一个强制要求是：每个提案页面必须在标题附近放置一个可见的 Status callout（状态提示块），且只能选用一个生命周期标签。生命周期标签表格如下：

Status callout 在文档站中由 Markdoc 标签渲染。仓库中 callout 标签定义 显示它支持generic、note、tip、info、warning、danger六种类型，并支持title（自定义标题）与collapsed（默认折叠）属性。模板中使用的正是type="info" title="Status"形态，例如：

{% callout type="info" title="Status" %} Proposal - replace this sentence with concise status detail. Use Partial only when page clearly separates shipped behavior from roadmap. {% /callout %}

一个容易被忽略的细节：模板要求状态行内附一段"简洁的状态详情"（concise status detail），而不是只写一个标签。例如真实页面 Enterprise MCP Controls 的写法是：

{% callout type="info" title="Status" %} Proposal - no matching organization MCP allowlist implementation exists yet. Schema, endpoints, dashboard flows, and client enforcement described here are tentative. {% /callout %}

而 Benchmarking 的 Partial 写法是：

{% callout type="info" title="Status" %} Partial - inspected repositories show a Harbor-facing smoke-eval workflow and cloud `model-eval-ingest` promotion sync. Broader Harbor adapters, ATIF traces, Opik workflows, and commands remain unverified roadmap items. {% /callout %}

对比可见：Proposal 页面强调"尚无实现、以下内容均为 tentative"；Partial 页面则精确列出"已验证的证据"与"仍属路线图的内容"两类清单。

模板还对 Partial 页面提出了专门要求：必须分开维护"当前实现"与"路线图"两张表格，严禁把已上线行为与 tentative 的 schema、端点、命令或上线宣称混在一起写。这一要求直接保证了文档的可信度——读者可以一眼分辨"现在能用什么"与"未来打算做什么"。

模板的八段式章节结构

模板在 Status callout 之后规定了完整的章节骨架。下面逐节解析其写作意图，并结合真实页面的做法说明每个章节如何落地。

Overview：问题与方案概述

模板要求：描述问题与拟议方案，说明预期结果（intended outcome）与边界（boundaries），并保持范围小到"可交付、可评估"（Keep scope small enough to ship and evaluate）。

真实范例可参考 Agent Observability 的开篇：

Agentic coding systems combine model requests, tool execution, file changes, and external API calls. Traditional request metrics catch hard failures. Agent behavior signals are also needed to investigate loops, degraded sessions, and poor outcomes.

该页面用两句话完成了"问题陈述（传统指标抓不住行为问题）+ 方案动机（需要 agent 行为信号）"，随后立即引用云平台可观测性文档建立上下文，是 Overview 的典型写法。

Requirements：最小需求清单

模板要求列出拟议方案所需的最小需求（minimum requirements），并以无序列表呈现：

## Requirements List minimum requirements needed for proposed solution. -

真实页面 Enterprise MCP Controls 将 Requirements 进一步细分为 "Dashboard app" 与 "Client behavior" 两组，逐条列出管理员界面能力（展示 marketplace MCP 服务器、选择批准项、默认禁用策略、审计日志记录）与客户端行为（策略启用时以 dashboard 配置替换本地配置、不激活不合规本地条目等），并明确了两个易混淆场景的边界：local entries rejected by policy need not be activated（被策略拒绝的本地条目无需被激活）与dashboard-managed configuration replacement is proposed behavior only when policy is enabled（dashboard 托管配置替换仅在策略启用时才属于拟议行为）。

Non-requirements：明确排除的范围

模板要求列出刻意排除在本提案之外的工作：

### Non-requirements List work intentionally excluded from this proposal. -

这一节与 Requirements 同等重要：通过声明"本次不做 X"，提案作者可以防止评审过程中范围蔓延（scope creep），也让评审者清楚知道哪些相邻问题是被有意搁置的。

Current implementation：当前实现（Partial 专用）

模板规定：仅 Partial 提案需要此节，用于列出已上线能力并提供证据范围（evidence scope）；纯设计提案应删除本节。其表格结构为：

Agent Observability 的当前实现表列出 7 项能力（API metrics ingestion、Session metrics ingestion、Burn-rate alert evaluation、Alert config storage、Analytics Engine storage、Export pipelines、Per-message feedback），全部标注为 Current 或 Current infrastructure，并在 Notes 列给出可验证说明——例如 "Explicit user feedback signal exists"。

Benchmarking 则示范了更严格的证据边界：其对"已检查仓库证据"与"未经证实的内部细节"做了显式区分。表中既有标注 Current workflow 的能力（Harbor-facing smoke eval、CLI release smoke coverage、Smoke result artifacts），也有标注 "Not verified here" 的条目（Private kilo-bench internals、Live production enablement），并注明"Static source does not prove deployment, rollout, retention, or vendor configuration"。这种"未验证即不声称"的态度正是模板要求 Evidence scope 的用意。

Roadmap：路线图

模板要求将 tentative 行为与当前实现分开列出：

Benchmarking 的路线图表包含 Contributor-facing Harbor adapter、ATIF trajectory adapter、Opik integration（均标注 Unverified roadmap），以及 Standard model comparison workflow、Standard agent comparison workflow、Custom task-set template、CI regression suite beyond smoke eval（标注 Planned）。Onboarding Improvements 的路线图表则覆盖 Starter prompt cards、Interactive tutorial、Tutorial completion state、In-product changelog、Kilo provider settings layout、Onboarding analytics 六项。

System design：系统设计

模板要求记录拟议架构与实现决策，并强调：tentative 的 schema、端点、命令与厂商集成，在验证之前必须标注为 proposed（拟议）。

Enterprise MCP Controls 是本节的最佳范本。它用{% callout type="warning" title="Tentative design" %}声明：

Following schema has not shipped. Names, storage layout, encryption approach, and API shape may change during implementation review.

然后给出三段拟议代码：组织级 MCP 控制的 Zod schema（OrganizationSettings_MCPControls）、加密成员配置的 SQL 建表语句（organization_member_mcp_configs）、以及成员配置载荷的 Zod schema（OrganizationMemberMCPConfig），并在随后的 API 表面表格中明确所有路由与端点"are placeholders for implementation design. They are not documented as available APIs."

这一段特别值得学习：拟议设计越具体越好（schema、SQL、API 占位符都要给出），但每个具体元素都必须配上"未上线、会变更"的警示。

Scope and implementation：范围与实现

模板要求列出可转化为 GitHub Issue 的工作项：

## Scope and implementation List work items that can become GitHub issues. -

真实页面的做法是把工作按区域分组。例如 Enterprise MCP Controls 的 Scope 表格将工作拆为 Backend（策略 schema、加密成员配置存储、审计日志、组织/成员 API）、Dashboard（管理员白名单 UI、成员配置 UI）、Client（拉取策略配置、忽略不合规本地条目、链接到 dashboard 配置）三个区域，每一项都能直接拆成可追踪的 Issue。

Compliance considerations：合规考虑

模板要求描述相关的安全、隐私、数据处理与 SOC 2 考量：

## Compliance considerations Describe relevant security, privacy,>bun run --filter @kilocode/kilo-docs test bun run --filter @kilocode/kilo-docs build

手动预览受影响页面，检查链接与渲染内容；

按照这套流程产出的提案，既能直接进入 Kilo Code 功能提案索引 被社区评审，其 Scope 章节的工作项又可平滑转化为 GitHub Issue，形成"设计文档 → 评审 → 拆 Issue → 实现 → 状态升级（Proposal → Partial）"的完整闭环。

【免费下载链接】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