基于 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 仓库在真实开发中必须遵守的工程约束。文档由六个部分构成章节作用对应的仓库事实Goal用一句话定义可追踪的目标明确“可追踪”traceable是核心Todo、验证、完成标准都服务于它Scope划定改动边界禁止无关修改与script/upstream/README.md中“不要修改无关文件”的合并规则一致Todos可勾选的执行清单从检视文件到总结结果形成线性执行链Implementation Notes代码归属与风格约束直接对应kilocode_change标记与script/upstream/的目录豁免规则Verification最小化验证命令对应根目录package.json的typecheck/lint与包内bun testCompletion Criteria完成判定条件强调“相关检查通过或无法运行的原因被记录”该文件位于 .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检视相关文件与既有模式确认改动属于 Kilo 自有代码还是共享上游代码。阶段二实现Todos 3–43. 实施最小代码变更 4. 行为变化时补充或更新针对性测试。阶段三验证与收尾Todos 5–85. 在被触碰的包要求时运行格式化或 lint 6. 运行最小相关的 typecheck 或测试命令 7. 修复改动引入的任何失败 8. 总结变更文件与验证结果。这套“先侦查、后实现、再验证、最后汇报”的顺序与仓库中 .kilo/agent/upstream-merge.md 描述的合并工作流高度同构该 Agent 文件同样要求“先端到端读完全部冲突文件再做计划”“在展示 diff 前先说明推理”“每次解析后运行最小相关检查”。可以说Todo 清单是这个 Agent 工作流在单功能开发场景下的简化映射。四、Implementation Noteskilocode_change 标记与代码归属规则这是整个计划中技术含量最高的部分它要求开发者理解并遵守 Kilo 与上游 opencode 之间的“代码边界协议”Kilo 专属行为优先放在 Kilo 自有目录必须修改共享上游文件时保持改动窄小并在需要处添加kilocode_change标记避免不必要的宽泛重构保留既有的风格、命名与包约定。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 typecheck5.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/ 目录守卫脚本职责bun run script/check-opencode-annotations.ts校验共享上游文件中的 Kilo 改动都有kilocode_change标记覆盖bun run script/check-architecture.ts架构边界检查对应根check:architecturebun run script/check-kilocode-duplication.tsKilo 代码重复检查对应根check:duplicationbun run script/check-forbidden-strings.ts禁止字符串扫描如不应出现在 Kilo 中的上游 URL、品牌串bun run script/check-workflows.ts/check-test-ci.ts等CI 工作流与测试配置一致性检查合并场景还会涉及script/extract-source-links.tssource-links 校验与 knip针对kilo-vscode/。计划文档建议按“触碰了哪些文件”决定运行哪些守卫而非全量盲跑——这正对应“运行被触碰文件隐含的最小相关检查”的原则。六、Completion Criteria完成的客观判定计划文档用四条标准定义“完成”请求的行为已实现与改动相关的测试或检查通过或无法运行它们的原因已被记录没有修改无关文件最终回复包含简明的变更总结与验证状态。第 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”等约束。可见示例计划中的六个章节在真实计划中一一对应且每部分都被填充了可执行细节。八、落地建议与常见误区结合模板与仓库工具链实践中值得注意几点先侦查再写 TodoTodo 清单应在读完受影响文件、确认代码归属之后填写避免“边做边猜”导致 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考