故障牵引 + 流水线飞轮
目标：故障发生时自动牵引到修复方案，任意流水线可低成本接入飞轮。
核心组件
| 脚本 | 职责 |
|---|---|
fault_traction.py |
从错误文本提取特征，匹配教训库给出修复建议 |
pipeline_flywheel.py |
注册流水线、记录运行/学习/审计/修复/追踪事件、抽象错误 Pattern、五维健康评估 |
fact_flywheel.py |
三环飞轮：内环正向反馈、中环 trust 校准、外环质量校准 |
sync_rules.py |
启动时自动驱动飞轮 |
一、故障牵引修复流程
故障发生
↓
fault_traction.py 提取错误特征
↓
匹配教训库中的活跃教训
↓
输出：top_fix + 置信度 + 历史使用次数
↓
自动修复 / 人工确认修复
↓
记录修复结果到 pipeline_flywheel
↓
若成功 → 更新教训 use_count
↓
若失败 → 标记为待人工，写入持久存储
二、流水线飞轮接入标准
任意流水线只需 2 步即可接入飞轮：
2.1 注册流水线
python3 pipeline_flywheel.py register <name> <process_fn>
2.2 运行飞轮
python3 pipeline_flywheel.py run <name> <input>
飞轮自动记录：
- 运行次数
- 修复次数
- 错误特征
- 匹配的教训
2.3 满意度评估 + 自动重试
内置 evaluate_and_retry()：
- 阈值：satisfaction_threshold=0.7
- 最多重试：max_retries=2
- 成功条件：satisfaction >= 0.7
- 失败处理：记录到飞轮，标记待人工
2.4 结构化 Trace + Pattern 自动抽象
CLI 命令
# 记录单步 trace
python3 pipeline_flywheel.py trace <pipeline_name> <run_id> <status> [--error "错误信息"] [--latency_ms <毫秒>]
# 列出所有错误模式
python3 pipeline_flywheel.py pattern list
# 按流水线过滤
python3 pipeline_flywheel.py pattern list <pipeline_name>
# 手动抽象 Pattern
python3 pipeline_flywheel.py pattern mine <pipeline_name> <run_id> '["特征1","特征2"]' "<修复动作>"
cron prompt 接入模板
在现有故障牵引块后追加：
## 飞轮事件记录
执行结果必须记录到飞轮：
- 成功时追加：python3 pipeline_flywheel.py trace <pipeline_name> <run_id> success
- 失败时追加：
1) python3 pipeline_flywheel.py trace <pipeline_name> <run_id> failure --error "<错误特征>" --latency_ms <耗时毫秒>
2) python3 pipeline_flywheel.py pattern mine <pipeline_name> <run_id> '["<特征1>","<特征2>"]' "<采取的修复动作>"
- run_id 格式：<pipeline_name>_<YYYYmmdd_HHMMSS>
三、知识体系闭环
故障发生
↓
fault_traction.py 匹配教训 → 自动修复
↓
pipeline_flywheel.py 记录事件
↓
fact_flywheel.py 三环运转
↓
若修复成功 → 教训 use_count +1
↓
若修复失败 → 生成新教训 → 写入教训库
↓
sync_rules.py 同步到持久存储
↓
下次故障自动召回更高优先级
四、健康度评估
4.1 CLI
# 五维健康分（0-100）
python3 pipeline_flywheel.py health [pipeline_name]
# Markdown 审计报告
python3 pipeline_flywheel.py audit [pipeline_name]
# 按错误文本搜相似 pattern
python3 pipeline_flywheel.py error-search '<error_text>'
# 生成/应用修复记录
python3 pipeline_flywheel.py fix-apply <pattern_id> <fix_patch>
4.2 五维健康分
| 维度 | 权重 | 说明 |
|---|---|---|
| 成功率 | 40% | success / total |
| 延迟 | 20% | <1s 满分，>5s 零分，线性插值 |
| Token 用量 | 10% | <1000 满分，>5000 零分，线性插值 |
| 错误分布 | 15% | vendor/harness 占比越低分越高 |
| Pattern 覆盖率 | 15% | 有 pattern 的失败数 / 总失败数 |
4.3 Pattern 自动分类
vendor_error：401/403/404/rate limit/timeout/connectionuser_error：user/input/参数/格式harness_defect：其他未匹配错误
4.4 时间窗口
建议使用滚动窗口（默认 1 天），避免历史批量故障永久压低健康分。
五、关键设计决策
5.1 Trace 表独立于主库
高写入的 trace 表应当独立数据库文件，避免与主事实库争抢写锁导致 database is locked。
5.2 飞轮写入失败降级
- 飞轮写入失败 ≠ 主任务失败
- trace 失败时只降级提示，不回滚主任务结果
- 可保留 JSONL 文件作为二次 fallback
5.3 自动修复安全白名单
自动 apply 只对命中以下关键词的补丁生效：model.default / provider / config.yaml / prompt / cron / retry / timeout / fallback。未命中白名单的仅生成 diff，不自动 apply。
5.4 延迟统计过滤
统计延迟时必须过滤 latency_ms=0 和数量级异常值（>24h），否则均分会完全失真。
六、使用示例
故障牵引
# 已知错误
python3 fault_traction.py "API 404 模型不存在"
# 从日志文件提取
python3 fault_traction.py /tmp/agent_error.log
飞轮运行
# 查看已注册流水线
python3 pipeline_flywheel.py list
# 手动运行飞轮
python3 fact_flywheel.py all
注册新流水线
python3 pipeline_flywheel.py register research "research-pipeline"
七、注意事项
- 不改用户配置：飞轮只记录事件，不修改现有流水线配置
- 最小侵入：接入只需在 cron prompt 里加 1-2 行调用
- 可观测：所有事件写入持久存储，可查询审计
- 自愈优先：故障优先自动修复，失败才上报
- 口径不一致：飞轮报告的运行次数是 trace 记录数，不是 cron 调度次数，两者不一定一致
八、与 self-fix-loop 的关系
self-fix-loop：聚焦单个脚本/任务的 8 阶段自愈闭环pipeline-flywheel：聚焦跨流水线知识沉淀 + 第二大脑飞轮 + 故障牵引
两者互补：
- 脚本级故障 → self-fix-loop
- 流水线级故障 + 知识沉淀 → pipeline-flywheel
九、Web 管理面板
提供零外部依赖的本地面板，支持：
- 五维健康分仪表盘
- 最近 trace 记录浏览
- Pattern 库管理
- 修复记录生成与安全 apply
# 启动面板
python3 pipeline_flywheel_dashboard.py [port]
