贡献指南

动手改这个仓库之前，先读 AGENTS.md。本地环境搭建、代码归属、依赖边界，以及常见改动要跑哪些检查，都在开发者指南里。

一句话流程

从 dev 拉分支，命名为 <user>/<scope>/<name>。一次改动只做一件事：一个功能、一个修复，或一次文档更新。
跑覆盖你所改行为的测试，缺的就补上。测试不能放水：出了回归就修代码，不要为了让测试通过而放宽断言。
受影响的契约、迁移和当前在用的文档，要一并更新。
跑 make check，以及这次改动需要的其他检查。它会自动做格式化和 lint 修复，提交前看一遍改了什么。
向 dev 发起 pull request。写清楚改完之后的行为，并列出你实际跑过的检查和结果。

commit 标题和 PR 标题都用 conventional commit 格式：type(scope): summary。Pull request 用 squash 方式合并，所以 PR 标题就是 dev 上那条 commit 的标题。main 通过手动触发的 fast-forward 工作流往前推进。

每个 commit 都要当成公开内容对待，绝不能提交 secret、令牌或密钥。提交前，对照 PR 检查清单把 diff 过一遍。MIGRATION.md 记录的是已经完成的仓库拆分；里面"只搬不改"的限制已成历史，但 AGENTS.md 里的服务边界和安全边界依然有效。

提交评审前的检查

在仓库根目录运行这些后端命令：

make setup-dev
make check

第一次搭环境用 make setup-dev。make check 会对三个 Python 包做格式化、lint 和类型检查，并跑测试（不含 external 和 dbtest 两个层级）。

改了前端，还要跑：

cd apps/frontend
npm ci
npm run lint
npm run format:check
npm run type-check
npm run test

CI 还会跑 server-only 和运行时站点配置的构建守卫。如果你动了这两处边界，请按开发者指南在本地跑对应的守卫。

需要跑哪些数据库测试和外部测试，参考开发者指南来选。改了数据库，就要用专门的 PostgreSQL 测试库跑 dbtest 层级。改 schema 要写增量的 Alembic 迁移，服务启动时不能建表或改表。

如果改了环境变量、Compose 文件、Docker 打包或工作流，要跑验证这些配置是否接对的测试。新增的变量写进 ENVIRONMENT.md。命令或行为变了，在同一次改动里更新文档。

持续集成

CI 会根据改动了哪些路径，决定要跑哪些后端、前端和镜像任务。pull request 和它的 base 比较，push 则和最新的 agent-* 发布比较，所以一个 commit 发布时，上次发布以来的所有改动都已经检查过。CI 用的是 Python 3.12 和 Node.js 22。CI Gate 要求路径分类这一步必须成功，其他任务要么成功，要么是按规则跳过的。

secret 扫描和默认测试层级每次都会跑，这一层的测试还会读取文档、ENVIRONMENT.md 和 Web 应用的源码。其余任务视改动的路径而定，涵盖后端格式化、lint、mypy、PostgreSQL 测试层级、前端检查、Compose 渲染、镜像构建和镜像冒烟测试。CI 还会实际跑一部分真实的 CLI、会话和 MCP 流程。评审通过后，相关的 dev commit 会再跑一次真实 Kata 的候选检查。pull request 里的镜像任务只构建和冒烟测试，不发布。

每个 pull request，不管来自 fork 还是本仓库的分支，都在用完即弃的 GitHub 托管 runner 上运行；推送到 dev 和 main 则在自托管的 runner 池上运行。仓库里写的 runner 路由不算安全边界，因为 fork 可以随便改。真正起作用的是 runner 组的限制，这项工作记录在 issue #464，具体说明见开发者指南。发布有自己的工作流和指南。

契约

gateway_contracts/*.openapi.yaml 记录本服务调用的网关 HTTP API，改动时要对照网关的源代码核实。如果改了某个客户端用到的端点或字段，就在同一个 PR 里更新对应的契约，并注明它对应网关的哪次改动。测试只能锁定本服务这一侧的契约，没法验证另一个仓库里当前的实现。

gateway_contracts/agent-control-plane.openapi.json 记录本服务自己的 API。有意改 API 时，用开发者指南里的命令重新生成，看一遍 diff，并在 PR 里说明对兼容性的影响。

apps/backend/cloud_agent_shared/ 里共用的 Python 协议，是控制平面和主机之间的另一份契约。动这条边界时，协议版本、能力声明和运行时版本固定要放在一起审视。