yuqei/ai-exchange

Fork 0

Files

T

Codex 78ee9b3e54 Productize decision assistant archive and context cockpit batch

2026-05-14 23:21:21 +08:00

9.8 KiB

Raw Blame History

AI ICT 外部 repair agent 接入说明 v1

1. 文档目标

本文档用于说明：

如果你想编写一个外部 repair agent，并通过 scripts/run_monitoring_alert_rollout.py 的 repair-bridge 模式接入当前自动化流程，应该如何实现。

本文档面向：

你自己写的 Python 修复脚本
其他 AI 代理包装器
Codex / Claude / 其他模型的桥接程序
后续可能扩展出来的自动修复子进程

2. repair agent 的职责

外部 repair agent 的职责不是管理整个流程，而是专注完成这一步：

接收失败阶段上下文
-> 分析应该修什么
-> 修改代码
-> 可选地执行少量 focused tests
-> 返回结构化 JSON 结果

也就是说：

主 orchestrator 负责：阶段推进、状态管理、复验、phase advance
外部 repair agent 负责：拿到上下文之后，尽量完成本轮修复

3. 调用方式

当前主脚本通过环境变量指定外部 repair agent 命令，例如：

MONITORING_ALERT_AUTO_REPAIR_ENABLED=1 \
MONITORING_ALERT_REPAIR_BRIDGE_COMMAND="python your_repair_agent.py" \
MONITORING_ALERT_ROLLOUT_MODE=repair-bridge \
.venv/bin/python scripts/run_monitoring_alert_rollout.py

主脚本会：

生成 bridge input JSON
通过 stdin 传给 your_repair_agent.py
从 stdout 读取 repair result JSON
解析结果并决定是否自动复验

4. stdin 输入协议

repair agent 必须从 stdin 读取 JSON。

当前协议版本：

repair-bridge/v1

必填字段

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": ["..."]
  }
}

5. 你应该如何使用输入字段

5.1 `phase`

表示当前处在哪个开发阶段。

比如：

N1
N2
N3
N4

你可以用它决定修复策略范围。

5.2 `failure_class`

这是 orchestrator 归纳后的失败类型。

常见值：

missing_dependency_or_import
missing_file_or_artifact
validation_failure
missing_implementation
readiness_gap
alert_dispatch_gap
runtime_gap
decision_packet_gap
blocker:<something>

用途：

帮你先快速判断本轮修复重点
降低 repair agent 自己重新归类的成本

5.3 `recommended_focus`

这是主脚本给 repair agent 的聚焦建议。

例如：

readiness_and_boundary_hardening
alert_delivery_and_dispatch
runtime_scheduler_and_status
decision_packet_and_operator_view

建议：

优先服从这个 focus
避免本轮修到无关模块

5.4 `phase_patch_targets`

这是当前最值得优先看的文件列表。

建议：

先读这些文件
只在必要时扩展到其它文件

这有助于控制修复范围。

5.5 `validation_entrypoint`

这是本轮首个失败命令或者最重要的验证入口。

例如：

.venv/bin/python scripts/run_alert_dispatcher.py

建议：

修完后优先自己尝试跑这个命令
如果你已经跑了，把命令写到 tests_run

5.6 `repair_prompt_context`

这里面通常包含最完整的上下文：

prompt_text
phase_tasks
phase_files
suggested_files
suggested_commands
reasoning

如果你只想用一段“人类可读修复提示”，优先用：

repair_prompt_context.prompt_text

6. stdout 输出协议

repair agent 必须向 stdout 输出 一段合法 JSON。

当前必填字段

status
summary
changed_files

可选字段

protocol_version
notes
success_guess
tests_run

7. 每个输出字段该怎么写

7.1 `status`

建议值：

applied
success
fixed
failed
blocked
noop

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

applied
success
fixed

如果你根本没改代码，不要写 applied。

7.2 `summary`

一句简短总结。

好的写法：

Implemented missing alert dispatcher module and updated runtime hook.
Fixed readiness panel payload mismatch and aligned API fields.

不好的写法：

done
fixed stuff

7.3 `changed_files`

必须是数组，列出本轮真正改动的文件路径。

例如：

"changed_files": [
  "src/services/alerts/alert_dispatcher_service.py",
  "src/services/runtime/trading_runtime_service.py"
]

非常重要：

如果你没改任何文件，不要伪造
如果只改 docs，也应如实返回 docs 文件
这个字段会影响 orchestrator 后续智能复验选择

7.4 `success_guess`

布尔值。

建议：

true：你认为这轮修复值得复验
false：你知道还没修完，不建议进入自动复验

如果你不确定，可以不写；但如果明确没修好，最好写 false。

7.5 `tests_run`

建议写上本轮 repair agent 自己已经执行过的 focused commands。

例如：

"tests_run": [
  ".venv/bin/python scripts/run_alert_dispatcher.py"
]

好处：

orchestrator 会优先用这些命令做 focused rerun
复验逻辑更精准

如果你没跑任何命令，可以不写。

7.6 `notes`

可选。可以写本轮修复的一些额外说明。

例如：

"notes": [
  "Focused on N2 alert delivery gap",
  "Did not touch visual-watch code"
]

8. 一个最小合法输出示例

{
  "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"
  ],
  "success_guess": true,
  "tests_run": [
    ".venv/bin/python scripts/run_alert_dispatcher.py"
  ]
}

9. stdout 和 stderr 的规则

这是最重要的实践规则之一：

stdout

只能输出最终 JSON。

不要把这些内容输出到 stdout：

调试日志
print 进度
traceback
人类说明文字

否则 orchestrator 会解析失败。

stderr

所有日志都应写到 stderr。

包括：

调试日志
运行步骤
中间状态
额外说明

10. 最小 Python repair agent 示例

下面给一个最小骨架：

import json
import sys
from pathlib import Path


def main():
    raw = sys.stdin.read()
    request = json.loads(raw)

    phase = request.get("phase")
    patch_targets = request.get("phase_patch_targets") or []
    context = request.get("repair_prompt_context") or {}

    print(f"[repair-agent] phase={phase}", file=sys.stderr)
    print(f"[repair-agent] patch_targets={patch_targets}", file=sys.stderr)

    changed_files = []
    tests_run = []

    # 这里写你自己的修复逻辑
    # 例如：读取 patch_targets，修改文件，运行一个 focused command

    response = {
        "protocol_version": "repair-bridge/v1",
        "status": "applied",
        "summary": "Applied a placeholder repair.",
        "changed_files": changed_files,
        "success_guess": True,
        "tests_run": tests_run,
    }

    sys.stdout.write(json.dumps(response, ensure_ascii=False))


if __name__ == "__main__":
    main()

11. 推荐实现步骤

如果你要做一个真正可用的 repair agent，建议按这个顺序：

Step 1

先实现：

stdin 读 JSON
stdout 写 JSON
stderr 写日志

Step 2

只消费：

phase
failure_class
phase_patch_targets
repair_prompt_context.prompt_text

Step 3

修完后正确写：

changed_files
success_guess
tests_run

Step 4

再逐步加高级能力：

patch target 优先级
局部测试
风险边界保护
多轮修复策略

12. 与 orchestrator 的交互建议

repair agent 最好遵守这些原则：

范围尽量小 优先修当前 phase patch targets，不要顺手大改无关模块。
日志进 stderr 保持 stdout 纯 JSON。
changed_files 要真实 后续智能复验靠它决定。
tests_run 要真实 不要写没执行过的命令。
success_guess 要诚实 没修好就写 false，比误导自动复验更好。

13. 当前脚本会如何使用你的返回值

当前 orchestrator 会消费：

status
summary
changed_files
success_guess
tests_run

用于决定：

是否自动复验
跑哪些 focused rerun commands
是否推进 phase
patch round 历史记录内容

14. 常见错误

错误 1：stdout 混入日志

后果：JSON 解析失败。

错误 2：`changed_files` 不是数组

后果：bridge output schema invalid。

错误 3：没改文件却返回 `applied`

后果：会触发不必要复验，污染历史。

错误 4：已经知道没修好还写 `success_guess: true`

后果：会误导自动复验逻辑。

错误 5：运行了 focused tests 却不写 `tests_run`

后果：orchestrator 无法利用你的执行信息做更精准复验。

15. 总结

如果你要做兼容当前自动化流程的外部 repair agent，最重要的就是三句话：

stdin 读 JSON
stdout 只输出 JSON
真实返回 changed_files / success_guess / tests_run

做到这一点，就已经可以稳定接入当前的 repair-bridge 自动化链路。

9.8 KiB Raw Blame History Unescape Escape