向SWE-AF贡献代码：从开发、测试到发布的完整路径

SWE-AF 是一个基于 AgentField 的自主 AI 软件工程舰队（autonomous engineering fleet）：一次 API 调用即可拉起一支 AI 智能体团队，自动完成软件的规划、编码、测试与交付，产出生产级 PR。本文带你走通向 SWE-AF 贡献代码的完整路径：搭建本地开发环境、理解多智能体架构、跑通测试与 CI、规范提交 PR，直到参与版本发布。

🧭 项目速览：SWE-AF 是什么

SWE-AF 不是单智能体包装器，而是一套协同的「工程工厂」：

• 规划层：Product Manager、Architect、Tech Lead、Sprint Planner 协作产出 PRD 与 Issue 分解
• 执行层：Coder、QA、Reviewer 在相互隔离的 git worktree 中并行工作
• 治理层：Issue Advisor 与 Replanner 在失败时重试、拆分或重构剩余任务

理解这套分层控制架构，是你开始贡献代码前最重要的背景知识。

📋 开发前准备：环境要求清单

根据 docs/CONTRIBUTING.md，开发 SWE-AF 需要三项前置条件：

💡 如果你只是跑测试、改纯逻辑代码，没有 AI 密钥也能进行大部分本地开发；只有触发完整 build 时才需要配置 LLM provider key。

🚀 克隆仓库并搭建本地开发环境（5 分钟上手）

按官方推荐流程，4 步完成环境搭建：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/sw/SWE-AF cd SWE-AF # 2. 创建并激活虚拟环境 python3 -m venv .venv source .venv/bin/activate # 3. 安装项目 + 开发依赖（pytest、pytest-asyncio、ruff） python -m pip install --upgrade pip python -m pip install -e ".[dev]"

pip install -e ".[dev]"以可编辑模式安装项目，并额外装上开发依赖。依赖声明集中在 pyproject.toml，其中agentfield>=0.1.113、pydantic、claude-agent-sdk等核心依赖的版本约束值得先读一遍——很多「跑不起来」的问题都源于版本不匹配。

🧩 代码结构导览：先读哪些模块

SWE-AF 同时包含 Python 主实现与 Go 移植版，首次贡献建议按此顺序阅读：

下图展示了 SWE-AF 多智能体管线的完整架构，贡献代码前强烈建议对照理解各角色职责：

▶️ 运行项目：双终端开发工作流

本地运行 SWE-AF 需要两个终端配合（详见 docs/SKILL.md）：

# 终端 1：启动 AgentField 控制平面（:8080） af # 终端 2：注册 swe-planner 节点 python3 -m swe_af

然后就能触发一次构建来验证你的改动：

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \ -H "Content-Type: application/json" \ -d '{"input": {"goal": "Add JWT auth", "repo_path": "/path/to/your/repo"}}'

下图是一条真实构建的时间线，展示了各阶段（planning → coder → reviewer → qa → merger → verify）如何交错并行执行——改动手上逻辑时，先弄清自己处于流水线的哪一段：

✅ 测试规范：如何跑通 SWE-AF 的 CI

提交前，本地必须先跑通 Makefile 中的两个目标：

make test # 运行 pytest tests/ -x -q make check # 测试 + 全量编译检查（compileall）

等价的手动命令：

python3 -m pytest tests/ -x -q python3 -m unittest discover -s tests -v

CI 定义在 .github/workflows/ci.yml，包含两个独立 Job，本地需分别对应：

1. test（Python Job）：Python 3.12 环境下安装-e ".[dev]"依赖后执行make check，与本地命令完全一致
2. go（Go Job）：如果你改动了 go/ 目录，需额外跑通格式、构建与竞态测试：

cd go gofmt -l . # 必须无输出 go build ./... go vet ./... go test -race -count=1 ./...

新增测试的建议：参考 tests/ 中现有用例的命名与 conftest 组织方式，纯逻辑改动优先补单元测试，涉及管线编排再补集成测试——PR 中会要求附上测试证据。

📝 提交 PR：仓库卫生与必备信息

PR 描述需遵循 pull_request_template.md 的四个板块：

• Summary：改了什么、为什么改
• Validation：make check结果 + 手动验证记录
• Behavior Impact：无行为变更 / 向后兼容 / 破坏性变更（三选一）
• Notes：上线注意事项或后续跟进项

根据 docs/CONTRIBUTING.md 的仓库卫生要求，请特别注意：

💡 明确说明「是否改变了智能体编排行为」是本项目 PR 的硬性要求，因为编排逻辑（如重试、门控）直接影响生产构建结果。

📦 发布路径：版本号、CHANGELOG 与镜像

SWE-AF 遵循语义化版本（Semantic Versioning），发布涉及三个环节：

1. 版本号：更新 pyproject.toml 中的version字段（当前为0.1.0）
2. 变更记录：在 CHANGELOG.md 的[Unreleased]区段按 Keep a Changelog 格式登记 Added / Changed / Removed，版本发布时再落到具体版本号下
3. Docker 镜像：容器化构建基于 Dockerfile 与 docker-compose.yml，修改入口点、依赖或环境变量后需重新构建验证：

docker compose up -d curl http://localhost:8003/health # swe-planner 节点健康检查

部署与镜像的详细验证步骤（含环境变量、已知问题与扩容方法）见 docs/deployment.md。

💡 新手常见坑速查

🎯 小结：你的第一份贡献路线图

1. 环境：Python 3.12+ → 克隆仓库 →pip install -e ".[dev]"
2. 理解：读 docs/ARCHITECTURE.md，对照架构图认清你要改的模块
3. 开发：双终端跑通本地节点，用真实 build 验证行为
4. 测试：make check全绿；改 Go 代码则加跑go test -race
5. PR：按模板写清变更原因与测试证据，遵守仓库卫生规则
6. 发布：版本 bump + CHANGELOG 记录 + 镜像重建验证

按这条路径走完，你就完成了从开发到发布的全流程——欢迎加入 SWE-AF 的构建。