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

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.这句话点明了模板的两条核心设计原则它们是规划文档不是当前架构参考提案页描述的是计划中的形态读者不应将其当作已上线能力的权威文档每个页面必须在顶部记录实现状态这正是模板中 Status callout 存在的意义。索引页末尾明确指引新功能设计使用模板Use the proposal template for new feature designs.Status callout提案的生命周期标签模板的第一个强制要求是每个提案页面必须在标题附近放置一个可见的 Status callout状态提示块且只能选用一个生命周期标签。生命周期标签表格如下StatusUse whenProposalDesign only; no matching implementation exists仅有设计尚无对应实现PartialSome pieces shipped; page separates current behavior from roadmap部分已上线页面须区分当前行为与路线图HistoricalPage remains for design history; implementation shipped elsewhere or changed materially页面仅为设计历史保留实现已迁移他处或发生重大变化SupersededAnother proposal or implementation reference replaced page已被其他提案或实现引用取代Status callout 在文档站中由 Markdoc 标签渲染。仓库中 callout 标签定义 显示它支持generic、note、tip、info、warning、danger六种类型并支持title自定义标题与collapsed默认折叠属性。模板中使用的正是typeinfo titleStatus形态例如{% callout typeinfo titleStatus %} 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 typeinfo titleStatus %} Proposal - no matching organization MCP allowlist implementation exists yet. Schema, endpoints, dashboard flows, and client enforcement described here are tentative. {% /callout %}而 Benchmarking 的 Partial 写法是{% callout typeinfo titleStatus %} 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 页面强调尚无实现、以下内容均为 tentativePartial 页面则精确列出已验证的证据与仍属路线图的内容两类清单。模板还对 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 enableddashboard 托管配置替换仅在策略启用时才属于拟议行为。Non-requirements明确排除的范围模板要求列出刻意排除在本提案之外的工作### Non-requirements List work intentionally excluded from this proposal. -这一节与 Requirements 同等重要通过声明本次不做 X提案作者可以防止评审过程中范围蔓延scope creep也让评审者清楚知道哪些相邻问题是被有意搁置的。Current implementation当前实现Partial 专用模板规定仅 Partial 提案需要此节用于列出已上线能力并提供证据范围evidence scope纯设计提案应删除本节。其表格结构为CapabilityStatusNotesExample capabilityCurrentDescribe verified current behaviorAgent 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 行为与当前实现分开列出CapabilityStatusProposed behaviorExample capabilityPlannedDescribe intended changeBenchmarking 的路线图表包含 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 typewarning titleTentative design %}声明Following schema has not shipped. Names, storage layout, encryption approach, and API shape may change during implementation review.然后给出三段拟议代码组织级 MCP 控制的 Zod schemaOrganizationSettings_MCPControls、加密成员配置的 SQL 建表语句organization_member_mcp_configs、以及成员配置载荷的 Zod schemaOrganizationMemberMCPConfig并在随后的 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手动预览受影响页面检查链接与渲染内容提交 PR 时遵循贡献指南的 issue-first 策略在 PR 描述中附上测试证据与手动验证结果。按照这套流程产出的提案既能直接进入 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考