向 Kiro Crew 贡献代码从 Makefile 构建到 pytest 质量门禁的开发者完整指南【免费下载链接】KiroCrewA persistent workspace for development work that self-improves and continues beyond one session.项目地址: https://gitcode.com/gh_mirrors/ki/KiroCrewKiro Crew 是一个开源的本地持久化 AI 开发工作区Agent 持续跨会话自我改进、持续工作。想在其中贡献代码本文带你走通整条开发者链路用根目录 Makefile 一键完成前端 后端构建再用 scripts/local-gate.py 等 pytest 质量门禁保证提交前代码达标最终顺利通过 CI 审查。全程按文档来新手也能少走弯路。一、动手前认识仓库结构Kiro Crew 是「Python 后端 React 前端」的双面surface架构理解目录分工是写好第一个 PR 的前提目录 / 文件作用src/kiro_crew/后端主包CLI、会话管理、ACP 客户端、Dashboard、MCP 工具website/React Vite 前端单页应用dashboard 界面test/后端 pytest 测试套件数万用例CI 按文件分片并行scripts/门禁与工具脚本local-gate.py、ci_file_shards.py、各类 lint 检查docs/官方文档架构、CI 说明、系统规格Makefile公开构建目标总入口CONTRIBUTING.md贡献指南本文的权威依据前置环境要求来自 CONTRIBUTING.mdPython ≥ 3.12Makefile 会强制校验版本低于 3.12 会直接报错终止Node.js ≥ 22推荐 24 LTS npmmacOS / 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 目标一览目标效果make build构建前端 安装后端到本地 venv最常用make test先 build再运行.venv/bin/pytest -q全量测试make等价于make testmake wheel产出自包含 pip wheel内嵌 dashboardmake desktop双击即可运行的桌面应用macOS 通用 DMG / Linux AppImagemake clean清理 build、dist、dist 缓存与.pytest_cache首次构建完整步骤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_PORT6777 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提交 暂存 未跟踪文件把改动分类到frontendwebsite/**、meta.github/**、scripts/**和backend三个桶再在对应表面上选取相关测试文件、相邻测试、文本引用了改动文件的测试来执行并带上受控的 xdist 并行度。--dry-run只打印执行计划不实际跑--full人工显式请求时才跑全量全量本来就是 CI 的职责。pytest 的根配置在 setup.cfg 的[tool:pytest]段testpaths锁定为test src/kiro_crew/apps/builtins单测超时--timeout120秒。一个游离在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 描述的结构运行Fast Gate约 44 秒跑完的廉价阻塞门禁vendor 清单校验、品牌名 lint、注释历史 lint、changelog 历史检查、docs-lint 等十几个 job每个检查都先跑自测试再跑正式检查CIFast Gate 通过后才释放重型任务——backend-lintisort / flake8 / mypy / black、backend-test按文件哈希分成 8 个 shard 并行跑 pytest见 scripts/ci_file_shards.py、覆盖率门槛、前端 lint 与 vitest 测试、E2E 等PR Readiness唯一值得盯的聚合状态它把所有独立 workflow 折叠成一个结论真正的合并门是「人工审批 自动合并」。四、从提交到 PR 落地完整流程清单从main拉特性分支git checkout -b feat/my-feature origin/main做改动并补测试新函数/组件必须有测试提交前跑第三节的「提交前的门」测试步骤即python3 scripts/local-gate.py遵循 Conventional Commits 提交feat:/fix:/docs:等祈使句、摘要不超 72 字符对main发起 PR维护者审查后按反馈追加提交⚠️ 若 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考