企业官网建设流程全解析

基于 Kilo 仓库的 Todo 驱动开发流程：从计划到验证的完整实践指南

【免费下载链接】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 这一基于 opencode 持续演进的开源编码代理工程平台时，每一次功能改动都必须在“最小正确变更”“Kilo 自有代码与上游共享代码的边界管理”“可复现的验证闭环”三者之间取得平衡。本文以仓库内.kilo/plans/1779980012659-happy-circuit.md这份 Todo 工作流计划为骨架，结合kilocode_change标记机制、script/upstream/上游合并自动化以及仓库根部的校验脚本，为你呈现一套可直接复用的“计划—实现—验证—完成”开发方法论。读完本文，你将掌握：如何用 Todo 清单约束改动范围、如何在共享上游文件中安全保留 Kilo 专属逻辑、以及如何用最小粒度的检查命令在提交前完成自证。

一、计划模板的核心结构

1779980012659-happy-circuit.md是一份“示例计划”（Sample Plan），但它并非抽象模板——它精确映射了 Kilo 仓库在真实开发中必须遵守的工程约束。文档由六个部分构成：

该文件位于 .kilo/plans/1779980012659-happy-circuit.md，同目录下的其余计划（如 .kilo/plans/1782926865817-jetbrains-model-picker-details-plan.md、.kilo/plans/1779990397226-quiet-canyon.md）都是这一结构的实际落地：它们同样包含 Goal、Affected Areas、Implementation Steps、Verification、Expected Outcome。因此，这份示例计划本质上描述了 Kilo 贡献者（尤其是 Agent）在仓库内开展工作的“标准动作序列”。

二、Scope：识别改动归属，划定最小边界

计划的 Scope 部分给出了四条硬约束：

• 确定受影响的包或功能区域；
• 做出最小且正确的代码变更；
• 仅在能验证行为时才新增或更新测试；
• 完成前运行最小相关的检查。

这四条约束在仓库中有着对应的执行依据。Kilo 是一个 monorepo（根 package.json 通过workspaces管理packages/*及packages/sdk/js），改动可能落在packages/opencode、packages/core、packages/llm、packages/kilo-jetbrains等不同工作区。在动手前，必须回答“这个改动属于 Kilo 自有代码还是共享上游代码”：

• Kilo 自有代码：packages/opencode/src/kilocode/、packages/kilo-*等目录，无需额外标记；
• 共享上游代码：其余从 opencode 继承来的文件，一旦修改就必须用kilocode_change标记。

这一判断直接影响后续是否触发 script/check-opencode-annotations.ts 这一仓库守卫。该脚本将packages/opencode、packages/core、packages/llm等 14 个作用域纳入检查范围，同时把packages/opencode/src/kilocode/**、任何含kilocode的路径、以kilo-开头的目录、script/upstream/**等列为豁免路径——因为它们在 Kilo 中完全自有，无需标记。

三、Todos：把功能落地拆成可验证的步骤

计划文档给出的 Todo 清单是一份通用的执行序列，可归纳为三个阶段：

阶段一：侦查（Todos 1–2）

1. 检视相关文件与既有模式；
2. 确认改动属于 Kilo 自有代码还是共享上游代码。

阶段二：实现（Todos 3–4）3. 实施最小代码变更； 4. 行为变化时补充或更新针对性测试。

阶段三：验证与收尾（Todos 5–8）5. 在被触碰的包要求时运行格式化或 lint； 6. 运行最小相关的 typecheck 或测试命令； 7. 修复改动引入的任何失败； 8. 总结变更文件与验证结果。

这套“先侦查、后实现、再验证、最后汇报”的顺序，与仓库中 .kilo/agent/upstream-merge.md 描述的合并工作流高度同构：该 Agent 文件同样要求“先端到端读完全部冲突文件再做计划”“在展示 diff 前先说明推理”“每次解析后运行最小相关检查”。可以说，Todo 清单是这个 Agent 工作流在单功能开发场景下的简化映射。

四、Implementation Notes：kilocode_change 标记与代码归属规则

这是整个计划中技术含量最高的部分，它要求开发者理解并遵守 Kilo 与上游 opencode 之间的“代码边界协议”：

1. Kilo 专属行为优先放在 Kilo 自有目录；
2. 必须修改共享上游文件时，保持改动窄小，并在需要处添加kilocode_change标记；
3. 避免不必要的宽泛重构；
4. 保留既有的风格、命名与包约定。

4.1 标记的三种形态

在 script/upstream/utils/markers.ts 中，kilocode_change标记被系统化地定义为三类：

• 独立标记行（standalone）：形如// kilocode_change、# kilocode_change、/* kilocode_change */，用于标注单行改动；
• 区块标记（block）：// kilocode_change start与// kilocode_change end配对，包裹一段 Kilo 专属代码；
• 整文件标记（fresh）：// kilocode_change - new file，插入在文件首行（若为 shebang 脚本则插在第二行），声明整个文件为 Kilo 新增。

标记的注释风格随文件类型自动适配，markers.ts中的styles映射表规定：.ts/.tsx/.js/.jsx用//，.css用/* */，.yml/.yaml/.toml/.sh/.bash/.zsh用#；扩展名为.json/.jsonc/.lock以及各类图片格式被列入unsupported集合，不允许标记。这套自动适配逻辑由 script/upstream/fix-kilocode-markers.ts 驱动：它对比当前文件与最近一次合并的上游版本，剥离旧标记后，在仍有差异的行周围重新生成新鲜标记。

4.2 标记背后的工程意图

标记不是装饰，而是三类工程目标的载体：

• 可审计：script/check-opencode-annotations.ts 会校验共享上游源码中的每一处 Kilo 改动都已被标记覆盖——行内含标记注释（inline）、落在 start/end 区块内（block）、或文件首行有- new file声明（whole-file），空行与标记行本身自动豁免；
• 可合并：script/upstream/README.md 明确指出，预合并变换消除了品牌差异后，“剩下的冲突只有含kilocode_change标记、包含 Kilo 专属逻辑的真实代码差异”；
• 可追踪：.kilo/agent/upstream-merge.md 要求合并时逐条核查标记编码的究竟是 bug 修复、功能增量还是防御性检查——例如 v1.14.30 中Workspace.isSyncing缺少await的修复，在上游 Effect 重构时被重新引入，因此需要把该修复移植进新的Effect.gen块。

计划文档中“如果必须编辑共享上游文件，保持改动窄小”的要求，在合并场景中还有一条实践补充：当需要移除冲突一侧的代码而周边结构（如if、循环）仍然成立时，优先用kilocode_change标记将其注释掉而不是直接删除，例如：

} else if (input?.scope !== "project" && !Flag.KILO_EXPERIMENTAL_WORKSPACES) { // kilocode_change start - directory filtering handled by KiloSession.filters above // if (input?.directory) { // conditions.push(eq(SessionTable.directory, input.directory)) // } // kilocode_change end }

这让下一次合并者仍能看到意图，而不是面对一段凭空消失的逻辑。

五、Verification：最小相关的检查命令

计划文档要求“为被改行为运行针对性测试”“TypeScript 代码变更时运行包级 typecheck”“运行触碰文件所需的仓库级守卫”。在 Kilo 仓库中，这些要求对应如下命令体系。

5.1 包内针对性测试

Kilo 的根 package.json 刻意将根级test设置为echo 'do not run tests from root' && exit 1，强制开发者进入具体包执行测试。典型做法是：

cd packages/core bun test --timeout 30000 # 运行该包测试 bun test path/to/xxx.test.ts # 只跑单个针对性测试文件

JetBrains 插件的测试则走 Gradle，例如 .kilo/plans/1779990397226-quiet-canyon.md 中的验证命令：

cd packages/kilo-jetbrains ./gradlew test --tests "ai.kilocode.client.session.SessionScrollTest" ./gradlew typecheck

5.2 类型检查与 Lint

根目录提供全局入口：

bun run typecheck # 等价于 bun turbo typecheck，覆盖全部工作区 bun run lint # oxlint

其中bun turbo typecheck是全仓兜底检查——.kilo/agent/upstream-merge.md 将其称为“非冲突调用点损坏的最终捕获器”（full-repo typecheck is the catch-all），因为自动合并可能悄悄引入重复声明、孤立导入或失效引用，这些在单个文件内无法察觉，只有全仓类型检查才能暴露。

5.3 仓库级守卫脚本

计划中的“repo-specific guard”在 Kilo 中主要指以下脚本（均位于 script/ 目录）：

合并场景还会涉及script/extract-source-links.ts（source-links 校验）与 knip（针对kilo-vscode/）。计划文档建议按“触碰了哪些文件”决定运行哪些守卫，而非全量盲跑——这正对应“运行被触碰文件隐含的最小相关检查”的原则。

六、Completion Criteria：完成的客观判定

计划文档用四条标准定义“完成”：

1. 请求的行为已实现；
2. 与改动相关的测试或检查通过，或无法运行它们的原因已被记录；
3. 没有修改无关文件；
4. 最终回复包含简明的变更总结与验证状态。

第 2 条是工程诚实性的体现：允许“无法运行”但禁止“未运行且不说明”。第 3 条直接约束改动边界，与 Scope 部分呼应——上游合并规则同样强调“do not modify unrelated files”。第 4 条则与 .kilo/agent/upstream-merge.md 中“总结精确的解析、取舍与验证结果”的要求一致：验证状态必须可被审查者复现。

在真实计划中，完成标准还会带上可测量的行为断言。例如 .kilo/plans/1779990397226-quiet-canyon.md 的 Expected Outcome 列出了五条可观察行为（转录区远离底部时新提示卡不移动滚动位置、位于底部时跟随到底部、点击按钮仍跳转到底部等），每条都能被SessionScrollTest中的断言直接检验。这说明：完成标准写得越“可断言”，验证环节就越轻松。

七、把模板套用到真实场景：JetBrains 计划实例

为展示该工作流的实际威力，可对照 .kilo/plans/1782926865817-jetbrains-model-picker-details-plan.md 观察模板如何被实例化：

• Goal：为 JetBrains 模型选择器增加最大化/最小化交互，扩展弹出宽度并展示与 VS CodeModelPreview对等的模型详情；
• Scope/Affected Areas：精确列出ProviderDto.kt、KiloWorkspaceState.kt、SessionUi.kt、ModelPicker*.kt等 9 处文件；
• Todos/Implementation Steps：拆成 DTO 扩展、后端解析、前端数据流、Swing 详情面板、布局重构、交互对齐、本地化、测试 8 步；
• Implementation Notes：明确“仅用 Swing/IntelliJ 平台组件，不引入 Compose/JCEF/UI DSL”“新增字段保持 nullable/带默认值以兼容 RPC 反序列化”；
• Verification：后端 parser 测试、Mapper 序列化测试、ModelPickerTest的 Swing EDT 测试；
• Completion/Risks：列出“元数据缺失时隐藏行而非占位”“所有 Swing 变更保持在 EDT”等约束。

可见，示例计划中的六个章节在真实计划中一一对应，且每部分都被填充了可执行细节。

八、落地建议与常见误区

结合模板与仓库工具链，实践中值得注意几点：

• 先侦查再写 Todo：Todo 清单应在读完受影响文件、确认代码归属之后填写，避免“边做边猜”导致 Scope 失控；
• 共享文件改动必须自带标记：凡是触碰packages/opencode等共享上游代码且行为有差异的改动，都要在提交前运行bun run script/check-opencode-annotations.ts自检，否则 CI 守卫会拦截；
• 验证命令要写在计划里：把将要运行的命令写进 Verification 章节（如bun run typecheck、bun test --timeout 30000、./gradlew test --tests "..."），既能约束自己，也让审查者可以复现；
• “无法运行”也要记录：环境不允许跑某条检查时，把它与原因一起写进最终总结，而不是默默跳过；
• 警惕宽泛重构：模板反复强调最小改动。在需要保留被移除代码意图时，用kilocode_change标记注释掉，而非删除。

结语

.kilo/plans/1779980012659-happy-circuit.md表面上是一份 37 行的示例计划，但它实则是 Kilo 仓库工程纪律的浓缩：以 Todo 清单锚定执行顺序，以kilocode_change标记维护与上游 opencode 的长期可合并性，以最小检查命令保证每次改动都可自证。当你在这类开源工程平台上贡献代码时，把 Goal、Scope、Todos、Implementation Notes、Verification、Completion Criteria 六个章节当作固定仪式，就能把“改一处功能”从直觉行为升级为可审查、可复现、可合并的工程产物。

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