| 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)。- CLAUDE.md「Safety Guardian 规则分类」表:total N+1 + 该文件行;ARCHITECTURE.md「N 条规则」。
- 测试到
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 登记:
EXPECTED["specialists_count"] +1 + ARCHITECTURE.md「13 个 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
python ../scripts/check_doc_drift.py
规则需要的新数据要先进 Twin:加 Twin 分区字段 → 在 builder.py 填(注意 Phase A 同步用传入 db / Phase B 并行自开 SessionLocal,见 [[project_build_twin_sessionlocal_ignores_db]])→ 该改动可能动 twin_partitions 计数(走 doc-drift-fix)。
