贡献流程¶
这一页写给准备提交改动的人。它按步骤说明这个仓库目前是怎么做改动的,最后给出评审时用的检查清单。
下面写的是目前的做法,不是正式的制度。仓库根目录的 CONTRIBUTING.md 是本页的简短入口;仓库没有 Pull Request 模板,也没有自带的 Git 钩子。提交历史里还看不出来的习惯,本页会直接说明。
开始之前¶
- 搭好环境,先让测试全部通过:开发环境、测试与 CI。
- 找到要改的代码,弄清它必须遵守的契约:代码结构与扩展点。
做一次改动¶
1. 在分支上工作¶
改动在分支上做,不直接在 main 上做。到目前为止唯一的功能分支是 feat/auto-research-agents,Agent 系统就是在它上面加进来的。除了这个例子,分支怎么命名没有别的规定。
2. 会让硬件动起来的地方,先写测试¶
凡是改 control/、executor/ 或 workflow/,都先写一个会失败的测试,再写代码。这三个包决定了往真实设备上写什么、什么时候写,这里出错,灯、风扇或水泵就会跟着动。
- 修 bug 时,先写一个因为这个 bug 而失败的测试。
- 使用模拟器,测试不需要 AC5。规则见开发环境、测试与 CI。
- 测试放在对应领域的目录里,例如
tests/control/,文件名以领域开头。
其他的包,目前的做法没有规定先后顺序。
3. 跑一遍 CI 的检查¶
.venv/bin/ruff check src tests scripts
.venv/bin/ruff format --check src tests scripts
.venv/bin/pytest -q
完整的清单和 CI 的执行顺序见开发环境、测试与 CI。
4. 提交¶
提交信息的标题行写成 <type>: <description>。
| 类型 | 用于 |
|---|---|
feat |
新的行为 |
fix |
修复 bug |
refactor |
调整结构,行为不变 |
docs |
只改文档 |
test |
只改测试 |
chore |
归不到其他类型的维护工作 |
perf |
性能方面的改动 |
ci |
CI 工作流 |
main 的提交历史里,最早的七个提交是以动词开头的普通句子,例如“Add local dashboard with live controls, history charts and CSV export”。之后的提交都采用这个格式,只有两个用了表里没有的 style:。
5. 推送,等 CI 通过¶
每次推送和每个 Pull Request 都会触发 CI。四个作业全部通过,改动才算可以送审:Linux 和 macOS,各配 Python 3.11 和 3.13。只在一个操作系统上通过是不够的,因为两边的 BLE 传输不同、沙箱不同,还有 14 个测试只在其中一边运行。
目前一直遵守的规则¶
仓库里不放密钥¶
凭据只有两个来源,都不是受版本管理的文件。
| 来源 | 内容 | 由谁读取 |
|---|---|---|
| 环境变量 | 模型的 API 密钥、GROWBRIDGE_TELEGRAM_TOKEN、GROWBRIDGE_ROLE_TOKEN_<ROLE>、FIRECREST_* 这一组变量 |
agents/llm.py、observer/channels.py、cli.py、compute/firecrest.py |
| 私有配置文件 | 安装令牌 | config.py。growbridge init 默认把它建在仓库之外,只有文件所有者可读。 |
.gitignore 已经把常见的载体排除在外:.env、config.toml、*.sqlite*、*.backup、*.jsonl 和 .local/。测试里的凭据一律是占位值。真实的设备地址、账号名和原始协议抓包同样不应进入仓库。
文件不超过 800 行¶
src/、tests/ 和 scripts/ 下的每个 Python 文件目前都在 800 行以内。文件快到上限时,按职责拆分:工具处理函数拆成了 agents/handlers_*.py;工作流服务超过 800 行时,它的恢复核对逻辑移到了 workflow/recovery.py。控制台的 web/app.js 和 web/style.css 比这长,它们属于桥接部分,比 DiAGRI 的其余部分更早。
Wiki 页面两种语言一起改,放在同一次提交里¶
每个页面在 en/ 和 zh-CN/ 下各有一份,文件名相同。两份要在同一次提交里修改,并遵守 Wiki 的 README 里的十条编写约定。tests/docs/test_docs_wiki.py 这个测试负责检查程序能检查的部分:
- 每个页面两种语言都有;
- Wiki 的 README 里的页面表,和实际存在的页面完全一致;
- 每个相对链接指向的文件都存在;
- 每个页面都链接到另一种语言的版本。
另外两个测试用代码核对参考页面,两种语言都查。test_docs_reference.py 核对拒绝码、CLI 命令和选项、Settings 与 RoleModel 的字段、MCP 工具(README 里的也查)和模型角色的工具,以及页面上写的数量,并检查 CITATION.cff 写的是软件包的当前版本。test_docs_routes.py 核对桥接和工作台的路由。测试失败时会列出页面漏了什么、写了哪些代码里没有的东西:两种语言的页面都要改。
除了这些表格,没有测试检查两个版本说的是不是同一件事,这要靠评审的人来看。
不要绕过 Git 钩子¶
提交和推送时不要加 --no-verify。仓库本身不带钩子,所以这里指的是你本机或你所在组织安装的钩子。钩子拦下提交时,把它指出的问题修好。
评审检查清单¶
清单里的每一项,都是这份代码在评审中真实出现过的一类缺陷。送审之前,先对照它检查自己的改动。
| 要找的问题 | 该问什么 | 代码里正确的做法在哪里 |
|---|---|---|
| 读取失败时,检查反而放行 | 读取抛出异常或什么都没返回时,这个分支会怎么做?“读不出来”绝不能当成“一致”“安全”或“没有差异”。 | 执行 Agent 把读不出来的设备状态当作有差异处理:tests/executor/test_executor_unreadable.py。 |
| 模型给出的 ID 没有限定在它的任务范围内 | 在读取或创建任何东西之前,每个快照、轮次或阶段的 ID 是否都对照过调用方任务所属的项目? | agents/handlers_common.py 里的 scoped_snapshot 和 require_round,以及 tests/dispatch/test_dispatch_snapshot_scope.py。 |
| 写入没有经过控制服务 | 每一次写设备,是否都走 ControlPort 的 submit、irrigate 或 pump_off? |
在 DiAGRI 的各个包里,只有 control/ 导入 Bridge。契约在 ports.py。 |
| 该用单调时钟的地方比较了墙上时钟 | 这是一段时长、一个超时还是一个最小间隔?是的话就用 Clock.monotonic()。Clock.now() 用于按日历触发的动作和记录上的时间戳。 |
executor/rules.py 和 archive/clock.py。测试里可以用 FakeClock.jump 拨动墙上时钟,而不让时间流逝。 |
| 测试访问了网络 | 测试有没有建立真实连接、解析真实主机名,或读取真实密钥? | tests/observer/test_observer_channels.py 里的 httpx.MockTransport,以及 sim/ 里的模拟器。 |
还有两个问题,每次改动都要问:
- 新增的工具、路由或命令,会不会让模型角色得到控制阶段或设备的能力?不允许这样。见控制与安全模型。
- 改动是否描述了真机、树莓派、真实通知服务或 CSC 上的行为?如果是,要写明哪些测过、哪些没有,并链接到状态与已知限制。这是 Wiki 的 README 里第 6 条约定的要求。
另见¶
页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。