ai-exchange/docs/AI_ICT_repair_bridge_protocol_v1.md

AI ICT repair bridge protocol v1

1. 目标

本文档定义 scripts/run_monitoring_alert_rollout.py 中 repair-bridge 模式与外部修复代理之间的 JSON 输入输出协议。

目标：

• 让自动化 orchestrator 能把当前失败阶段的上下文结构化发送给外部修复代理
• 让外部修复代理用稳定 JSON 返回修复结果
• 让 orchestrator 根据返回值决定是否自动复验、是否允许阶段推进

---

2. 协议版本

当前协议版本：

repair-bridge/v1

---

3. stdin JSON 输入协议

外部修复代理从 stdin 读取 JSON。

必填字段

• protocol_version
• mode
• phase
• phase_title
• failure_class
• recommended_focus
• phase_patch_targets
• validation_entrypoint
• repair_prompt_context

示例

{
  "protocol_version": "repair-bridge/v1",
  "mode": "repair_loop",
  "phase": "N2",
  "phase_title": "最小主动消息告警闭环",
  "failure_class": "alert_dispatch_gap",
  "recommended_focus": "alert_delivery_and_dispatch",
  "phase_patch_targets": [
    "src/services/alerts/alert_dispatcher_service.py",
    "src/services/runtime/trading_runtime_service.py"
  ],
  "validation_entrypoint": ".venv/bin/python scripts/run_alert_dispatcher.py",
  "repair_prompt_context": {
    "prompt_text": "...",
    "phase_tasks": ["..."],
    "phase_files": ["..."],
    "suggested_files": ["..."],
    "suggested_commands": ["..."]
  }
}

---

4. stdout JSON 输出协议

外部修复代理必须向 stdout 输出一段 JSON。

必填字段

• status
• summary
• changed_files

可选字段

• protocol_version
• notes
• success_guess
• tests_run

字段说明

status

建议值：

• applied
• success
• fixed
• blocked
• noop
• failed

当前 orchestrator 认为下面这些值可以进入自动复验候选：

• applied
• success
• fixed

summary

一句简短摘要，说明修复做了什么。

changed_files

数组，列出本轮修复实际修改的文件路径。

success_guess

布尔值。

• true 表示修复代理认为可以尝试复验
• false 表示修复代理认为还不适合复验

tests_run

数组，列出修复代理已经主动执行过的 focused tests / scripts。

orchestrator 会把它作为智能复验调度输入。

示例

{
  "protocol_version": "repair-bridge/v1",
  "status": "applied",
  "summary": "Implemented missing alert dispatcher module and updated runtime hook.",
  "changed_files": [
    "src/services/alerts/alert_dispatcher_service.py",
    "src/services/runtime/trading_runtime_service.py"
  ],
  "notes": [
    "Focused on N2 alert delivery gap"
  ],
  "success_guess": true,
  "tests_run": [
    ".venv/bin/python scripts/run_alert_dispatcher.py"
  ]
}

---

5. orchestrator 当前决策逻辑

5.1 自动复验条件

只有满足以下条件，脚本才会自动复验：

1. MONITORING_ALERT_AUTO_RERUN_ENABLED=1
2. bridge output JSON 可解析
3. bridge output schema 合法
4. status in {applied, success, fixed}
5. success_guess != false
6. changed_files 非空

---

5.2 智能复验调度

当前策略：

优先级 1：如果有 tests_run

直接优先执行 tests_run 中列出的命令，作为 focused rerun。

优先级 2：如果没有 tests_run

根据 changed_files 做命令映射：

• 改动 src/services/alerts/ 或 src/api/alerts.py
  • 运行 scripts/run_alert_dispatcher.py
• 改动 src/services/runtime/ 或 src/api/trading_runtime.py
  • 运行 scripts/run_trading_runtime.py
• 改动 src/services/readiness/ / src/web/ / src/config/settings.py
  • 运行 scripts/run_launch_readiness.py
• 改动 src/services/decision/ / src/services/operator/
  • 运行 scripts/run_review_packet.py
• 如果全部改动只在 docs/
  • 跳过 focused rerun，直接进入全阶段判断

之后仍会回到 run-until-blocked 做阶段级判断。

---

5.3 自动推进条件

修复后复验完成后，如果 rerun 结果状态为：

• running
• completed

则当前阶段可视为已推进成功。

否则进入：

inspect_rerun_result

---

6. 推荐外部修复代理实现要求

建议外部 repair agent 至少做到：

1. 从 stdin 读取完整 JSON
2. 解析 phase_patch_targets 和 repair_prompt_context
3. 明确输出 changed_files
4. 给出 success_guess
5. 若已主动运行 focused checks，则把命令写入 tests_run
6. 始终输出合法 JSON 到 stdout，不要混入额外日志

如果需要日志，建议输出到 stderr。

---

7. 当前脚本内相关模式

• run-until-blocked
• repair-loop
• repair-bridge

推荐顺序：

run-until-blocked
  -> repair-loop
  -> repair-bridge
  -> auto rerun
  -> phase advance / inspect_rerun_result

---

8. 后续可扩展项

后续协议可以考虑补充：

• applied_patches
• skipped_files
• risk_notes
• confidence_score
• requires_human_review
• suggested_next_tests

这些字段当前不是必需，但适合 repair-bridge/v2。