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. 协议版本

当前协议版本：

```text
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`

### 示例

```json
{
  "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 会把它作为智能复验调度输入。

### 示例

```json
{
  "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`

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

否则进入：

```text
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`

推荐顺序：

```text
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`。