代码结构与扩展点¶
这一页写给准备动手改代码的贡献者。它先给出 src/growbridge/ 的地图,再说明让各个服务保持独立的那条依赖规则,最后针对几类常见的扩展,逐一指出要改的文件、要满足的协议和要补的测试。
两层结构¶
整个包分两层。桥接层(GrowBridge)是最初的守护进程,由顶层的几个模块组成,负责 BLE 连接、样本历史、本机回环 HTTP API、控制台和 MCP 工具。DiAGRI 的其余部分是一组子包,一个服务一个包,在 auto_research 打开时由 runtime.py 装配起来。不打开的话,growbridge serve 只运行桥接层。各个服务在运行时分别负责什么,见架构总览;这一页只讲代码在哪里。
桥接层:顶层模块¶
| 模块 | 负责什么 |
|---|---|
cli.py |
growbridge 命令和它的子命令。serve 要么只启动桥接层,要么启动 DiAGRI 的运行时。 |
config.py |
Settings 和 RoleModel,也就是私有配置文件。load 读取它,initialize 创建它。 |
protocol.py |
GGS v1 的分帧:encode、Decoder、crc16。 |
transport.py |
BLE 连接:macOS 上是 NativeTransport,Linux 上是 BleakTransport,由 make_transport 选择。 |
native/BLEHelper.swift |
macOS 上由 NativeTransport 启动、真正操作蓝牙的辅助进程。 |
service.py |
Bridge:BLE 连接的唯一持有者。遥测、请求与应答、最初的控制命令和水泵计时都在这里。 |
store.py |
Store:最初的 SQLite 历史库,存样本和操作记录。 |
api.py |
create_app:本机回环 HTTP API 和控制台。DiAGRI 模式下,工作台的路由也挂在这里。 |
dashboard.py、web/ |
控制台的浏览器会话,以及它的页面、脚本和样式表。web/tokens.css 是两个页面共用的设计变量。 |
web/workbench.html、web/workbench/ |
DiAGRI 模式下 /workbench 提供的操作员控制台:纯 ES 模块,没有构建步骤,也没有 npm 包。main.js 负责启动,router.js 把 URL 的 hash 对应到页面,api.js 调用 /wb,pages/ 里每个页面一个模块,ui/ 是共用的控件,i18n/ 放中英文文案,denials.js 给每个拒绝码配提示。脚本只从同源加载,写入文字只用 textContent。 |
mcp_server.py、client.py |
走标准输入输出的 MCP 服务器,以及它访问守护进程所用的 HTTP 客户端。 |
DiAGRI 的其余部分:一个服务一个包¶
| 包 | 负责什么 |
|---|---|
archive/ |
项目档案(store.py 里的 Archive):只追加的记录、数据快照、导出、备份、存储空间不足时的降级。readings.py 按时间桶读取一个阶段的样本,供控制台画曲线。所有服务共用的东西也放在这里:models.py、db.py(Database)、clock.py(Clock)和 ids.py。 |
workflow/ |
WorkflowService:研究轮次和阶段的状态、审批和历史。tasks.py 里的 TaskBoard:研究任务。states.py:各个状态枚举。listing.py:给控制台用的只读查询,比如项目摘要和等待选择的轮次。 |
control/ |
ControlService:所有 BLE 写入的唯一关口。写入权在 rights.py,动作账本和写入主机登记在 ledger.py,通道映射和回读在 device.py。 |
executor/ |
ExecutorEngine:按已批准的运行单逐拍执行的确定性程序。规则求值在 rules.py,时钟是否可信和连接中断的处理在 outage.py。 |
observer/ |
Observer:告警规则和告警簿、通知发件箱和通知渠道、每日指标和日报、运行健康检查与心跳。 |
planning/ |
纯函数:design.py 做实验设计检查,validate.py 做运行单校验。 |
research/ |
分析库:统计方法、确认性分析的关口、HoldoutRegistry、报告发布和代码沙箱。 |
agents/ |
四个模型角色:提示词在 roles.py,工具注册表在 tools.py,工具处理函数在 handlers*.py,此外还有 Agent 循环、Dispatcher、CallBudget,以及 llm.py 里的模型客户端。 |
compute/ |
ComputeService:额度检查和作业跟踪。ComputeBackend 协议。FirecrestBackend,没有对 CSC 验证过。 |
workbench/ |
操作员使用的 HTTP 路由,都在 /wb 下:会话、阶段控制、人工写入和读取在 api.py,发起和掌控一轮研究在 rounds.py;控制台的读取路由(待办、项目、读数、测量、历史、安全配置)在 reads.py。auth.py 里是操作员凭据、会话和入口的判定。 |
sim/ |
模拟器和测试数据,测试和 growbridge simulate 都用它。 |
另有四个顶层模块把这些服务连在一起:
| 模块 | 负责什么 |
|---|---|
ports.py |
服务之间的契约:ControlPort、StagePort、WriteTransport、SampleSource、RecordSink 这几个协议,以及在它们之间传递的值,例如 Actor、Denied、ActionRequest、StageEvent。 |
runtime.py |
build_runtime 为每个所有者建一个 SQLite 文件,并把各个服务装配起来。Runtime.tick 是每秒一次的主循环。simulate_stage 是模拟运行。 |
runtime_agents.py |
在运行时的服务之上构造各角色的工具和 Dispatcher。这里的代码不会被 Runtime.tick 调到。 |
runtime_backup.py |
Backups:按计划对各个数据库做在线备份。 |
依赖规则¶
一个服务只导入 ports.py 里的协议和 archive/models.py 里的模型,不导入另一个服务的类。具体的类只在 runtime.py(连同 runtime_agents.py 和 runtime_backup.py)里出现,由它把协作对象交给每个服务。正因为这样,测试才能给工作流服务一个 FakeControl,或者给执行 Agent 一个 FakeClock,而不用启动其他任何东西。为什么要这样拆分,见设计决策记录。
flowchart TD
cli["cli.py<br/>growbridge 命令"]
runtime["runtime.py<br/>装配与每秒循环"]
subgraph services["DiAGRI 的各个服务"]
workflow["workflow/"]
control["control/"]
executor["executor/"]
observer["observer/"]
agents["agents/"]
workbench["workbench/"]
archive["archive/"]
compute["compute/"]
end
libs["planning/ 与 research/<br/>纯函数检查与分析"]
contracts["ports.py 与 archive/models.py<br/>协议与共享模型"]
bridge["service.py 与 store.py<br/>桥接层"]
cli --> runtime
runtime --> services
runtime --> libs
services --> contracts
libs --> contracts
workbench -.-> workflow
agents -.-> workflow
agents -.-> libs
control -.-> bridge
archive -.-> bridge
实线是规则允许的导入,虚线是下面列出的例外。
除了这两个契约模块,每个包还可以导入公共的基础设施:archive/clock.py、archive/db.py、archive/ids.py、workflow/states.py(它不导入包里的任何其他模块)和 config.py。
用 grep 在当前工作区核对的结果是:executor/、observer/、compute/、planning/、research/ 和 workflow/ 完全符合规则。其余的包在下面这些地方有例外:
| 位置 | 导入了什么 | 为什么 |
|---|---|---|
workbench/api.py、workbench/rounds.py、workbench/reads.py |
WorkflowService、TaskBoard、Archive、AlertBook、ComputeService(在 reads.py 里),以及 workflow/permissions.py 里的 require_operator |
工作台拿到的是真实的服务对象,类型标注里直接写了它们的类。rounds.py 用自己定义的协议给调用预算标类型,所以 workbench/ 不从 agents/ 导入任何东西。 |
agents/dispatch.py |
TaskBoard |
调度器的任务看板参数用这个类做类型标注。 |
control/service.py、control/device.py |
service.py 里的 Bridge、BridgeError |
控制服务包在桥接层外面。DiAGRI 的其他包都不导入它。 |
archive/source.py |
store.py 里的 Store |
这是把桥接层的样本历史读进项目档案的适配器。 |
agents/handlers_*.py |
planning/ 和 research/ 里的函数与结果类型,以及 archive/snapshot.py 模块 |
工具处理函数直接调用这些纯函数检查和分析库。 |
另外,工具处理函数是通过 agents/handlers_common.py 里的 Deps 拿到真实服务的,而 Deps 的字段类型都是 Any。所以只看导入语句,看不全它们用到了什么。想自己核对某个包,可以这样查:
扩展点¶
每一项都给出要改的文件、要满足的契约和要补的测试。测试要遵守开发环境、测试与 CI里“不联网”的规则。
新增通知渠道¶
- 文件。
observer/channels.py。 - 契约。
NotifyChannel协议:async def send(self, text: str) -> Outcome。返回值是accepted、unknown(请求可能已经送达)或failed(肯定没有送达)。密钥和服务地址只能来自环境变量。 - 装配。
runtime.py里的default_channels按名称返回可用的渠道。发件箱把这个名称和每条通知存在一起,没有被接受的通知会重试。 - 测试。 照
tests/observer/test_observer_channels.py的写法:用httpx.MockTransport模拟每一种响应和网络错误,并断言各自对应的结果。
目前没有任何渠道对接过真实服务,见状态与已知限制。
新增计算后端¶
- 文件。 契约在
compute/backend.py。新的适配器放在compute/firecrest.py旁边。 - 契约。
ComputeBackend协议:submit、find_by_name、status、fetch、cleanup、cancel和balance。submit收到的作业名是gb-<attempt_id>,find_by_name必须能凭这个名字把作业找回来。这样回执丢失时可以对账,而不是重新提交。作业肯定没被接受时抛SubmitRejected,结果不确定时抛BackendError。 - 装配。
build_runtime有compute_backend、compute_templates和compute_members三个参数。只有计算服务配置齐全时,serve才通过runtime_compute.py里的compute_options传入它们,并装上输入检查,对模型指定的每个输入做范围检查。新增后端就在那里选择。 - 测试。
tests/compute/用FakeBackend驱动ComputeService。适配器自身的拒绝逻辑,照tests/compute/test_compute_firecrest.py的方式测。
FirecrestBackend 接受可注入的客户端,所以所有测试都不需要 pyfirecrest。它不报告用量和余额(接口没有):服务按预留全额给作业计账,余额由操作员录入。
给模型角色新增工具¶
- 文件。 把工具名加进
agents/tools.py的ROLE_TOOLS,再到该角色的处理函数模块里构造Tool,例如agents/handlers_researcher.py。两边的清单不一致时,build_role_tools会报错。 - 契约。 输入模型继承
ToolInput。它不接受未知字段,所以role、approved这类字段过不了校验。处理函数以actor_for(role)的身份行事,绝不从输入里取身份。writes、sandbox、reads_web要如实填写:Agent 循环在读过网页之后,会把写入类工具和沙箱工具藏起来。 - 规则一:不给控制权。 工具不能审批、启动、暂停、恢复或停止阶段,也不能写设备。
CONTROL_TOOLS里的名字永远到不了模型角色手里,新工具也不能换个名字提供同样的能力。 - 规则二:每个 ID 都要限定范围。 模型给出的 ID 只是它的说法,不是事实。先取调用方的
task_id并解析出任务,再确认快照、轮次或阶段属于这个任务所在的项目,然后才能读取或创建任何东西。own_task、scoped_snapshot和require_round就是做这件事的,不符合时以Denied("scope")拒绝。 - 测试。
tests/agents/test_agents_tools.py和tests/dispatch/test_dispatch_toolsets.py里的注册表测试;该角色的tests/dispatch/test_dispatch_*.py里补一个行为测试;再照tests/dispatch/test_dispatch_snapshot_scope.py补范围测试:别的项目的 ID、不存在的 ID、别的角色的任务。
新的反馈规则或保护规则形式¶
- 文件。 模型
FeedbackRule、ProtectionRule、Condition、RuleAction在archive/models.py。求值在executor/rules.py。送审前的检查在planning/validate.py。 - 契约。
evaluate_feedback和evaluate_protection是纯函数:输入规则、一条读数、上一次的RuleState和now_mono,输出一个Decision。持续时间只按单调时间戳计算。读数只有通过valid_reading才能驱动规则;否则规则不产生动作,计时重新开始,而on_missing为pause的反馈规则会要求暂停。validate_run_sheet返回若干Finding,其中只要有阻断项,运行单就不能送审。 - 还要检查。 保护规则的写入权里列的是已批准规则的确切档位,
control/rights.py的check_scope会拒绝其他任何取值。如果safety_conflicts发现某条保护规则作用的通道在运行单里不是主机控制,工作流服务会以safety_conflict拒绝启动阶段。新的动作形式要同时过这两关。 - 测试。 求值放在
tests/rules/,校验放在tests/planning/test_planning_validate.py,每一拍的行为放在tests/executor/。如果新的形式需要样例,扩充sim/fixtures.py里的humidity_rule和make_safety。
其他平台的沙箱¶
- 文件。
research/sandbox.py。 - 契约。
Sandbox协议:run(script, snapshot_dir, out_dir, timeout) -> SandboxResult。子进程不能联网,对快照只读,只能写out_dir,环境变量是空的。 - 装配。 选择后端的函数有两个:同一文件里的
make_sandbox,和runtime.py里的make_runtime_sandbox。两者在没有可用后端时都退回RefusingSandbox,也就是什么都不运行。这个兜底要保留。 - 测试。
tests/research/test_research_sandbox.py里仅在 macOS 上运行的那些测试,就是新后端必须复现的行为,只是跳过条件要换成它自己的:不能联网、不能写到out_dir之外、拿不到父进程的凭据、超时后脚本被终止。
目前只有 macOS 有可用的后端(SeatbeltSandbox)。在 Linux 上,包括树莓派,分析脚本会被拒绝执行。
新增控制台页面¶
- 文件。 在
web/workbench/下加pages/<name>.js,并在router.js的FLAT或WITH_ID里加一条路由;main.js在页面第一次被访问时才加载它。页面用ui/dom.js里的函数建元素,文字只用textContent写入。不要用innerHTML:tests/web/里的测试发现控制台脚本用了它就会失败。 - 文案。 每条文案都要同时加进
i18n/zh.js和i18n/en.js,有测试要求两边的键完全一致。新的拒绝码要在denials.js里写上中英两条提示。 - 写入。 会写入的页面都走
api.js:它带上服务器要求的请求头,并在收到reauth_required时只请求一次重新输入密码。控制类操作成功后重新读取对象,不要凭猜测更新屏幕。 - 测试。 能脱离浏览器测试的逻辑单独放进一个模块,在
tests/web/里用node --test测。
新的 BLE 传输¶
- 文件。
transport.py。 - 契约。
ports.py里的WriteTransport协议:属性connected,方法connect(callback)、send(command)、close()和halt()。只有确认旧的写入通路再也写不了,halt才返回True。超时或出错都返回False。halt之后,send必须拒绝。 - 装配。
make_transport按平台选择具体的类。Bridge和build_runtime接受任意的transport_factory,测试就是这样把SimulatedTransport传进去的。 - 测试。 照
tests/transport/test_transport_bleak_halt.py来写:halt无法确认的每一种情况各一个测试,再加一个halt之后调用send的测试。
写入权交接时,控制服务依赖 halt 的结果。为什么超时不能算确认,见控制与安全模型。
运行中的守护进程还没有接上的部分¶
下面几块都有代码和测试,但 growbridge serve 没有把它们接起来。每一块都是贡献者可以着手的地方。
- 研究目标的网页或命令。 入口已经有了,是
workbench/rounds.py里的工作台路由。它们调用WorkflowService的create_project、save_protocol、create_round,调用CallBudget.set,并用TaskBoard.create建立第一个编排任务。这些路由和只读路由之上是/workbench的操作员控制台,没有 CLI 命令;还有少数几类读取没有路由,运行一轮研究里列了出来。新路由加在rounds.py或api.py里,挂在工作台的operator或fresh依赖后面。它在tests/workbench/里的测试要证明:角色令牌、没有会话、别处来的 Origin、另一个入口的会话,都会被拒绝。 - 计算后端。 见上文:
serve没有传compute_backend。 - 心跳端点。
build_runtime的heartbeats参数接受一对Heartbeat对象。serve在runtime_heartbeat.py里根据GROWBRIDGE_HEARTBEAT_HOST_URL和GROWBRIDGE_HEARTBEAT_RUN_URL构造它们:两个都设或者都不设。想换一个监控服务,就在那里构造一对新的Heartbeat。 - 搜索后端。
runtime_agents.py的role_tools传的是search=None,所以计划 Agent 的两个联网工具lookup_crop_conditions和search_and_verify_sources会被拒绝。
完整的清单在状态与已知限制。
另见¶
页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。