向 Kiro Crew 贡献代码：从 Makefile 构建到 pytest 质量门禁的开发者完整指南

向 Kiro Crew 贡献代码：从 Makefile 构建到 pytest 质量门禁的开发者完整指南

【免费下载链接】KiroCrewA persistent workspace for development work that self-improves and continues beyond one session.项目地址: https://gitcode.com/gh_mirrors/ki/KiroCrew

Kiro Crew 是一个开源的本地持久化 AI 开发工作区（Agent 持续跨会话自我改进、持续工作）。想在其中贡献代码？本文带你走通整条开发者链路：用根目录 Makefile 一键完成前端 + 后端构建，再用 scripts/local-gate.py 等 pytest 质量门禁保证提交前代码达标，最终顺利通过 CI 审查。全程按文档来，新手也能少走弯路。

一、动手前：认识仓库结构

Kiro Crew 是「Python 后端 + React 前端」的双面（surface）架构，理解目录分工是写好第一个 PR 的前提：

前置环境要求（来自 CONTRIBUTING.md）：

• Python ≥ 3.12（Makefile 会强制校验版本，低于 3.12 会直接报错终止）
• Node.js ≥ 22（推荐 24 LTS）+ npm
• macOS / Linux / Windows 均可从源码构建

二、一键构建：Makefile 目标详解 🏗️

根 Makefile 的设计哲学是「一条命令，全部就绪」：make build会依次执行frontend和backend两个目标——前端用npm ci安装依赖并npm run build，把产物拷入src/kiro_crew/static/dist；后端则自动创建.venv虚拟环境、校验解释器版本、以pip install -e ".[dev]"安装开发依赖（含锁定的 pytest 工具链，见 pyproject.toml 的 dev 依赖组）。

核心 make 目标一览

首次构建完整步骤

git clone https://gitcode.com/gh_mirrors/ki/KiroCrew cd KiroCrew make build source .venv/bin/activate kirocrew setup # 配置数据目录与默认 agent kirocrew doctor # 验证安装与后端 kirocrew gateway # 启动 dashboard 与消息网关

启动后访问http://localhost:5476即可看到 dashboard。

💡开发模式技巧：修改 Python 源码后需重启后端；修改.tsx前端文件则可跑 Vite 热更新，无需重新构建。官方还推荐用隔离数据目录并行跑开发实例，避免污染生产配置：

KIROCREW_HOME=.kirocrew-dev KIROCREW_PORT=6777 kirocrew gateway

三、pytest 质量门禁：提交前必须过的三道关卡 🚦

第一关：格式与静态检查

AGENTS.md 定义了「提交前的门」，在 macOS / Linux 上的标准命令序列：

python3 scripts/check_black_formatting.py && python3 scripts/check_subprocess_encoding.py && isort src/kiro_crew test flake8 src/kiro_crew test && mypy src/kiro_crew python3 scripts/local-gate.py

两个高频坑点值得划重点：

• 绝不裸跑black src/kiro_crew test——它会重排所有基线文件，把你的 diff 淹没。只格式化你改过的文件；
• macOS 上跑 mypy 需加--platform linux，否则会漏掉 CI 会拦截的 Linux 专属错误。

第二关：local-gate.py 按 diff 范围跑 pytest

这是本仓库最有特色的门禁。全量后端测试超过 6 万个用例、本地跑要一小时，而 scripts/local-gate.py 只运行与你改动相关的测试：它分析你的 diff（提交 + 暂存 + 未跟踪文件），把改动分类到frontend（website/**）、meta（.github/**、scripts/**）和backend三个桶，再在对应表面上选取相关测试文件、相邻测试、文本引用了改动文件的测试来执行，并带上受控的 xdist 并行度。

• --dry-run：只打印执行计划，不实际跑；
• --full：人工显式请求时才跑全量（全量本来就是 CI 的职责）。

pytest 的根配置在 setup.cfg 的[tool:pytest]段：testpaths锁定为test src/kiro_crew/apps/builtins，单测超时--timeout=120秒。一个游离在testpaths之外的test_*.py文件永远不会被收集到——这正是 Fast Gate 中testpaths-coverage检查要拦截的「绿色遗漏」。

上图的Dev Fleet页面就是配合贡献流程的工具：项目规定每个改动都在独立的 git worktree 中进行（官方开发技能 kirocrew-worktree-dev 将此列为硬性规则），你可以在这里统一 sync、rebase、起 Pod 做 QA，互不干扰。

第三关：CI 流水线门禁

推送 PR 后，CI 按 docs/ci/ci-and-reviews.md 描述的结构运行：

1. Fast Gate：约 44 秒跑完的廉价阻塞门禁（vendor 清单校验、品牌名 lint、注释历史 lint、changelog 历史检查、docs-lint 等十几个 job），每个检查都先跑自测试再跑正式检查；
2. CI：Fast Gate 通过后才释放重型任务——backend-lint（isort / flake8 / mypy / black）、backend-test（按文件哈希分成 8 个 shard 并行跑 pytest，见 scripts/ci_file_shards.py）、覆盖率门槛、前端 lint 与 vitest 测试、E2E 等；
3. PR Readiness：唯一值得盯的聚合状态，它把所有独立 workflow 折叠成一个结论，真正的合并门是「人工审批 + 自动合并」。

四、从提交到 PR 落地：完整流程清单

1. 从main拉特性分支：git checkout -b feat/my-feature origin/main；
2. 做改动并补测试（新函数/组件必须有测试）；
3. 提交前跑第三节的「提交前的门」，测试步骤即python3 scripts/local-gate.py；
4. 遵循 Conventional Commits 提交（feat:/fix:/docs:等，祈使句、摘要不超 72 字符）；
5. 对main发起 PR，维护者审查后按反馈追加提交；
6. ⚠️ 若 PR 打开期间落后于 base 分支，用 rebase 而不是 merge更新分支（git rebase origin/main+--force-with-lease），否则合并提交会触犯「一个 PR 最多一两个提交」的 PR Hygiene 规则。

三条让 PR 顺利落地的经验（来自官方贡献指南）：改动小而聚焦；较大的设计先开 issue 对齐方案；发送前逐行读一遍自己的 diff。架构级改动需先写 RFC 放进 docs/request-for-change/；任何改变已记录行为的改动，必须在同一提交里更新对应文档，并运行./scripts/docs-lint.sh验证。

五、进阶阅读地图 📚

• 官方 CI 门禁全解：docs/ci/ci-and-reviews.md
• 测试约定（隔离、worker 限制、平台陷阱）：docs/system-specs/common/testing-conventions.md
• 前端测试指南：website/docs/testing.md
• 安装与构建目标详解：docs/guides/install.md
• 代码风格规范：docs/system-specs/common/code-style.md
• 项目治理与维护者：GOVERNANCE.md、MAINTAINERS.md

总结：向 Kiro Crew 贡献代码的路径非常清晰——make build完成环境搭建，local-gate.py让你在本地几分钟内拿到与 CI 同构的反馈信号，Fast Gate + 分片 pytest + PR Readiness 三层门禁保证合入质量。按 CONTRIBUTING.md 的清单执行，你的第一个 PR 就能稳稳通过所有关卡。

【免费下载链接】KiroCrewA persistent workspace for development work that self-improves and continues beyond one session.项目地址: https://gitcode.com/gh_mirrors/ki/KiroCrew