| name | extend-safety-or-specialist |
| description | 在 backend 加一条 Safety Guardian 规则 或 一个 Orchestrator Specialist。当要新增安全规则/专科 agent 时使用。含 @register、engine 注册、防循环导入、doc-drift 登记、测试接线等易漏步骤。 |
扩展 Safety 规则 / Specialist
两个扩展点共享同一个坑:doc-drift 登记 + 测试接线容易漏。改完都要跑 doc-drift-fix + 测试。
安全规则属敏感面 → 上线前走 safety-gate。
加一条 Safety Rule
- 在
backend/app/agents/safety_guardian/rules/<file>.py 写函数,加 @register 装饰器(自动注册,不用改 engine)。
- 签名:
(twin: HealthTwin) -> Optional[Alert] | List[Alert]。
- 只读 Twin,不开 db(规则是纯 twin→alerts 函数;要的数据先在 builder 填进 Twin 分区)。
- 新文件才需在
engine.py 的 _load_rule_modules() 里 import 该模块(已有文件加函数不用)。
- doc-drift 登记(必做,否则 CI 红):
scripts/check_doc_drift.py 的 EXPECTED["safety_rules"] 加该文件 @register 数(纯数据文件无 @register 也要登记为 0,防 unknown rule file)。- 运行 generator 更新
docs/_generated/system-map.json；叙事文档只链接生成真源，禁止手写总数。
- 测试到
tests/test_safety_guardian.py:正例(命中→Alert,severity/requires_medical_attention 对)+ 反例(不命中→静默)。
- 跑
doc-drift-fix + pytest tests/test_safety_guardian.py。上线走 safety-gate。
加一个 Specialist
- 建
backend/app/agents/<name>/ 目录,实现 Specialist Protocol:applies_to(intent, twin) -> bool + run(twin, context) -> SpecialistFinding。
- 在
backend/app/orchestrator/specialists.py 的 _build_registry() 注册(按依赖顺序)。
- 防循环导入:
<name>/__init__.py 不要 import specialist 类(由 specialists.py 直接 import)。
- doc-drift 登记:让扫描器识别新 Specialist，运行 generator 更新
docs/_generated/system-map.json；叙事文档不手写 Specialist 总数。
- 测试到
tests/test_specialists.py(applies_to 正反 + run 产出 shape)。
- 跑
doc-drift-fix + pytest tests/test_specialists.py tests/test_orchestrator.py。
共同验证
cd backend && source venv/bin/activate
export SECRET_KEY=test-secret-key-32-chars-minimum!! GARMIN_ENCRYPTION_KEY=mI4nYXirjGlbHD7sFogYlqPQJzirU04mUsS5LyDS0SU=
pytest tests/test_safety_guardian.py tests/test_specialists.py tests/test_orchestrator.py -q --no-cov
../scripts/system-map-check.sh
规则需要的新数据要先进 Twin:加 Twin 分区字段 → 在 builder.py 填；必须验证 Phase A 传入 session 与 Phase B 并行 session 的一致性边界。结构变化统一走 doc-drift-fix，不在叙事里手写分区计数。
