sanguo_moziplus_v2/docs/design/08-classify-outcome-optimization.md

#08 Classify Outcome 优化 + Registry 清理

版本：v2.0 | 日期：2026-06-02 | 作者：庞统 | 状态：✅ 已实施，司马懿评审通过

v2.0 最终状态：

• Phase -1 TCP probe → 废弃，替代为独立 Gateway Watchdog v2（已部署）
• Classify Outcome v3.1 → 全部实施（v1.0: A3/A3b/api_error/cooldown; v1.1: A14-A17/A8/A10/cooldown统一60s）
• Registry 清理 → 不做物理删除，逻辑删除+归档，后续单独实施
• 并发控制一致性 → TODO，留 #02 Main Session 统一处理
• stderr_preview / exit_signal → 暂缓
• A7 compact_failed retry → 暂缓

1. 背景与动机

1.1 classify outcome 问题

_classify_outcome 的 A0 行（status=None, stdout 空, exit≠0 → crashed）把所有「进程没输出 JSON 就退了」的情况一视同仁，无法区分：

实际场景	exit_code	当前判定	理想判定
openclaw CLI 连不上 Gateway	1	crashed	可恢复
进程被 SIGINT/SIGTERM 杀（compact 期间等）	130/143	crashed	可恢复
Agent 代码 bug 崩溃	1	crashed	不可恢复（但要等 ticker 兜底）

此外：

• fallback_used 直接判死刑，不允许 retry
• compact_failed 不可恢复——但 compact 结束后应该可以续杯
• network/rate_limit/lock 推回 pending 而非 retry——counter 在手里，retry 更快
• stderr 没记录到 task_attempts，排查靠猜

1.2 Registry 孤儿问题

测试产生的 e2e-* 项目 data 目录被删，但 registry.db 记录还在（128 条）。每次 tick 遍历 100+ 个 no_db 项目，浪费 I/O。

1.3 并发控制一致性

architecture-v3.0.md §8.2 描述三层并发控制，代码已实现但存在一处偏差：

• AgentProfile.max_concurrent（config 中每个 agent 的 max_concurrent）定义了但没被使用
• 实际 per-agent 限制统一用 counter.max_concurrent_sessions（全局值 3）
• 不影响功能（因为当前 max_concurrent_sessions=3 已是宽松上限），但是设计↔代码不一致

2. 设计目标

1. classify outcome：区分可恢复 vs 不可恢复，可恢复走 retry（续杯），不可恢复标 failed + 原因写黑板
2. Registry 清理：删除项目时同步清理 registry，discover 时同步清理孤儿
3. 并发控制对齐：标记 AgentProfile.max_concurrent 为 TODO 或接入 counter

2.1 Phase -1: Gateway 存活检查 — ❌ 已废弃

原方案（TCP probe）

spawner spawn 前 TCP + WebSocket Upgrade 握手探测 Gateway。实测 406 次全部 ok，但线上仍频繁发生 stalled session、lane task error、FailoverError。

失败原因

TCP 握手只能检测进程端口是否监听，无法检测 Gateway 业务可用性（lane task 卡死、provider 全挂等）。结论：TCP probe 方案无效。

替代方案

独立 Gateway Watchdog v2（已部署）：bash 脚本每分钟扫描 Gateway 进程日志，3 条规则检测 FailoverError/stalled/rate_limit，自动重启 + 5 分钟冷却。设计文档：docs/design/gateway-watchdog.md。

3. Classify Outcome 判定树 v2.0

3.1 核心分类原则

分类	处理	说明
可恢复 → retry	_do_retry（续杯）	counter 已在手里，重新 spawn 比推回 pending 更快
不确定 → crashed（等 ticker 兜底）	cooldown + 保持 working	ticker 超时回收 or crash_limit 标 failed
Agent 自己判的	尊重，不干预	A4: task_status=failed
完成	结束	正常完成
不可恢复 → failed	标 failed + 原因写黑板	确定性错误，重试不会改变结果

3.2 输入因素

因素	来源	说明
exit_code	进程退出码	0=正常, 1=通用错误, 128+N=信号
json_result.status	openclaw stdout JSON	ok / timeout / error / None
json_result.summary	同上	completed 等
json_result.fallback_used	同上	Gateway 降级标志
stderr_text	进程 stderr	关键字匹配辅助分类
stdout_text	进程 stdout	是否有输出
task_status	黑板 DB 任务实际状态	done / failed / working 等
exit_code 信号类型 (新增)	exit_code ≥ 128	SIGINT(130) / SIGTERM(143) = 外部中断
stderr 关键字（无 JSON 时） (新增)	stderr_text	无 JSON 输出时也检查 network/compact 等

3.3 判定表

第一层：有 JSON 输出（status ≠ None）

编号	条件	outcome	可恢复？	处理
A1	status=ok, summary=completed	completed	—	结束
A2	status=timeout	gateway_timeout	✅	retry（续杯）
A3	status=ok, fallback_used, fallback_count ≥ 2	fallback_exhausted	❌	标 failed + 原因写黑板
A3b	status=ok, fallback_used, fallback_count < 2	fallback_retry	✅	retry + cooldown 60s
A4	task_status=failed	agent_failed	—	尊重，不干预
A5	status=ok（其他组合）	completed	—	结束
A6	status=error + stderr 含 auth 关键字	auth_failed	❌	标 failed + 原因写黑板
A7	status=error + stderr 含 compact 关键字	compact_interrupted	✅	retry + cooldown 60s（等 compact 完成）
A8	status=error + stderr 含 network 关键字	gateway_unreachable	✅	retry + cooldown 60s
A9	status=error + stderr 含 rate_limit 关键字	api_error	✅*	release counter + 推回 pending + api_retry_count 上限

*A9 是特殊路径：不走统一 _do_retry 续杯，而是 release counter + 推回 pending + 独立 api_retry_count 计数器（达 max_retries 标 failed）。保留此路径是因为 api_error 有独立的计数器逻辑，与 retry_count 互不干扰。 | A10 | status=error + stderr 含 lock 关键字 | lock_conflict | ✅ | retry + cooldown 60s | | A11 | status=error（其他） | agent_error | ❌ | 标 failed + 原因写黑板 |

第二层：无 JSON 输出（status = None, stdout 空）

编号	条件	outcome	可恢复？	处理
A12	已合并到 A13 revised	—	—	见下方 A13 revised
A13 revised	exit=0（无 JSON 输出）	completed	—	信任进程退出码，exit=0 即正常完成。旧逻辑按 task_status 区分，非终态判 agent_error → 导致 inform Mail 永不标 done，与 dispatcher inform auto-done 形成死循环
A14	exit=130 (SIGINT) 或 exit=143 (SIGTERM)	interrupted	✅	retry
A15	exit≠0 + stderr 含 network 关键字	gateway_unreachable	✅	retry + cooldown 30s
A16	exit≠0 + stderr 含 compact 关键字	compact_interrupted	✅	retry + cooldown 60s
A17	exit≠0（其他，排除 A14-A16）	crashed	不确定	cooldown 300s + 保持 working → ticker 兜底

3.4 各编号详细说明

A2: gateway_timeout（续杯）

• 唯一由 Gateway 官方信号触发的续杯
• 走 _do_retry，用同一 session-id 续杯
• retry_count 上限 3 次

A3/A3b: fallback 分级处理（新）

• A3b（fallback_count < 2）：fallback 说明任务本身没问题，是模型/网络抖了，retry
• A3（fallback_count ≥ 2）：连续两次 fallback，说明模型质量不可靠，标 failed
• fallback_count 存储位置：task_attempts.metadata 中的 fallback_count 字段
• 每次检测到 fallback_used=true 时递增，retry 成功（非 fallback 结束）时重置

A4: Agent 自己标 failed

• Agent 通过 API POST /tasks/{id}/status 主动标 failed
• 含义：Agent 有意识地判断任务无法完成（需求矛盾、资源不足等）
• 处理：尊重 Agent 的判断，记录 outcome=agent_failed，不干预

A6: auth_failed（不可恢复）

• 401/403/unauthorized → 认证/授权失败
• 重试不会改变结果，需要人工介入
• 标 failed + {"reason": "auth_failed", "stderr_preview": "..."}

A7: compact_interrupted（暂缓未实施）

• compact 是 Gateway 的上下文压缩过程
• compact 结束后 session 状态恢复，理论上可以续杯
• 当前代码 A7 compact_failed 仍为不可恢复（should_retry=False），暂不改动
• 等 A7 实施时一并处理

A9: api_error（特殊路径，release counter + push pending）

• 原逻辑和新逻辑一致：release counter + 推回 pending + cooldown
• 有独立的 api_retry_count 计数器，达 max_retries(3) 标 failed
• 不走统一 _do_retry 续杯，因为 api_error 需要独立的计数器逻辑
• cooldown 由 counter 默认 cooldown 控制（与 crashed 相同）

A11: agent_error（不可恢复）

• status=error 但 stderr 不匹配任何已知关键字
• 标 failed + {"reason": "agent_error", "stderr_preview": "前500字"}

A14: interrupted（可恢复，新增）

• exit=130 (SIGINT) 或 exit=143 (SIGTERM)
• 原因：进程被外部中断（PM2 restart、compact 期间被杀、手动 Ctrl+C）
• 不是代码 bug，retry 很可能成功
• retry + cooldown 60s

A15/A16: 无 JSON 输出 + stderr 关键字（可恢复，新增）

• 原逻辑 A0 把这些统判 crashed
• 新逻辑：stderr 含 network/compact 关键字 → 对应的可恢复分类
• A15: network → retry + cooldown 60s
• A16: compact → retry + cooldown 60s

A17: crashed（不确定，等 ticker 兜底）

• 排除所有可恢复场景后，真正的"不知道什么原因崩了"
• 不立刻标 failed（保持现有逻辑）
• 设 cooldown 300s，任务保持 working
• ticker _check_timeouts 检测超时 → 标 failed
• 或 _check_crash_limit 连续 3 次 → 标 failed
• 两种兜底机制都写原因到黑板

3.5 cooldown 参数汇总

⚠️ v1.1 统一简化：A14/A15/A8/A10 cooldown 统一 60s，减少认知负担和参数维护。

场景	cooldown	理由
A3b fallback	60s	统一简化
A7/A16 compact	60s	等 compact 完成
A8/A15 network	60s	网络暂时性问题
A9 rate_limit	60s	API 限流需要等待
A10 lock	60s	统一简化
A14 interrupted	60s	统一简化
A17 crashed	300s	给 session 恢复时间

3.6 retry 时 cooldown 的实现

retry 走 _do_retry → spawn_full_agent(skip_counter=True)。 cooldown 在 retry 前设：

if cls.get("cooldown_seconds"):
    self.counter.set_cooldown(agent_id, seconds=cls["cooldown_seconds"])
    await asyncio.sleep(cls["cooldown_seconds"])

或者更优雅：cooldown 由 can_acquire 检查，retry 时 spawn_full_agent 内部 Phase 1 会调 can_acquire，cooldown 期间自动等待。但当前 _do_retry 用 skip_counter=True 跳过了 counter 检查。

方案：在 _do_retry 开始时设 cooldown，cooldown 期间 asyncio.sleep，然后继续 spawn。这样不需要改 counter 逻辑。

3.7 stderr 记录增强 — 暂缓

stderr_preview 和 exit_signal 写 metadata 的方案暂缓，本轮不实施。 已有 metadata 记录 fallback_count、api_retry_count、retry_count 等计数器。

4. Registry 清理 — 最终决策：逻辑删除 + 归档，不做物理删除

决策记录

• delete_project 保持逻辑删除（status→deleted，data 目录和 blackboard.db 保留）
• 不做物理删除：项目数据有长期价值，保留可恢复
• 归档方案（TODO）：定期将 deleted 项目的 data 移至 NAS 归档目录，从活跃存储清理
• 批量管理 API：暂不实施，当前项目数量少（15 个 active），手动管理可接受
• discover_projects 孤儿清理：暂不实施，当前无孤儿问题

性能评估

逻辑删除不物理删对性能无影响：

• registry.db 多几十条 deleted 记录，SQLite 微秒级
• ticker 只处理 active 项目，deleted 的不被遍历
• API 查询已过滤 deleted 状态

5. 并发控制一致性检查

5.1 现状

设计层	配置/代码	实际生效
per session key	max_per_session=1	✅ 生效
per agent	max_concurrent_sessions=3	✅ 生效
global	max_global_agents=5	✅ 生效
per tick	max_dispatch_per_tick=3	✅ 生效
per agent profile	AgentProfile.max_concurrent	❌ 定义了未使用

5.2 问题

config/default.yaml 中每个 agent 有 max_concurrent（张飞=1, 司马懿=2, 庞统=3），但 Router 加载 profile 后 max_concurrent 从未被引用。实际 per-agent 限制统一用 counter.max_concurrent_sessions=3。

5.3 方案（标记为 TODO，不在本次实施）

两种对齐方向：

• 方向 A：删掉 AgentProfile.max_concurrent，统一用 max_concurrent_sessions
• 方向 B：counter.can_acquire() 读取 agent profile 的 max_concurrent 替代全局值

当前所有 agent 的 max_concurrent 都 ≤ 3，且 max_concurrent_sessions=3 已是宽松上限，不影响运行。标记为 TODO，在 #02 Main Session 实施时统一处理。

6. 影响范围

已实施

文件	改动	风险
src/daemon/spawner.py	_classify_outcome A0→A14-A17 拆分 + A8/A10 改可恢复	中 — 核心逻辑
src/daemon/spawner.py	_handle_exit should_retry 分支加 cooldown + A3b cooldown 30→60 + else 分支加 compact_interrupted	中
scripts/gateway-watchdog.sh	独立 Gateway Watchdog v2（替代 Phase -1 TCP probe）	低 — 新文件

未实施（暂缓）

文件	原计划改动	状态
src/daemon/spawner.py	A7 compact_failed 改可恢复	暂缓
src/daemon/spawner.py	stderr_preview / exit_signal 写 metadata	暂缓
src/blackboard/registry.py	delete_project 增强 + discover 孤儿清理	不做（逻辑删除+归档）
src/api/admin_routes.py	批量清理 API	不做
tests/test_spawner.py	单元测试	暂缓

7. 测试计划

7.1 单元测试（mock）

测试	覆盖
test_A14_interrupted_sigint	exit=130 → retry
test_A14_interrupted_sigterm	exit=143 → retry
test_A15_no_json_network	exit=1 + stderr network → retry
test_A16_no_json_compact	exit=1 + stderr compact → retry
test_A17_crashed	exit=1 + 空 stderr → crashed + cooldown
test_A3b_fallback_retry	fallback_count=0 → retry
test_A3_fallback_exhausted	fallback_count=2 → failed
test_A7_compact_retry	status=error + compact → retry + 60s cooldown
test_A8_network_retry	status=error + network → retry + 60s cooldown
test_A9_api_error_push_pending	status=error + rate_limit → push pending + api_retry_count
test_A10_lock_retry	status=error + lock → retry + 60s cooldown
test_A11_agent_error_reason	status=error + 未知 stderr → failed + reason
test_A6_auth_failed_reason	status=error + auth → failed + reason
test_stderr_recorded	metadata 包含 stderr_preview
test_fallback_count_tracking	fallback_count 跨 retry 累计

7.2 E2E 测试（需 RUN_INTEGRATION=1）

• 模拟 compact 场景：spawn → compact → retry → 成功
• 模拟 network 中断：spawn → network error → retry → 成功

8. 与现有设计的关系

本文档是 spawner-monitor-design.md 的增量更新，不替代原文档。改动点：

• §5 A0 章节更新为 A14-A17 四种细分
• §5 A5/A6 (fallback) 改为 A3/A3b 分级处理
• §5 A7-A12 中 compact/network/rate_limit/lock 改为 retry
• 新增 §3.6 cooldown 参数汇总
• 新增 §4 Registry 清理
• 新增 §5 并发控制一致性检查（TODO 标记）

9. v2.1 修订：失败处理一致性修复（2026-06-06）

审计发现设计文档描述的 failed 处理在代码中有 3 处 gap，已修复并通过司马懿评审。

9.1 发现的问题

BUG	设计要求	代码实际	影响
BUG-1	A6 auth_failed / A11 agent_error → 标 failed + 原因写黑板	只设 cooldown 300s，任务留 working 等 ticker 30 分钟	不可恢复错误白等 30 分钟
BUG-2	Mail 幻觉门控无回复 → 标 failed(no_reply_found)	留 working 等 ticker recheck	Agent 未回复 Mail 卡 30 分钟
BUG-3	所有设计只描述到标 failed 为止	标完 failed 无任何通知	failed 任务无人关注

9.2 修复内容

F1: auth_failed + agent_error → 立刻标 failed（spawner.py:855-860）

在 _handle_exit() "其他"分支中，cooldown 之后、_do_on_complete_async 之前，新增不可恢复 outcome 立刻标 failed 逻辑。

F2: 所有 failed → comment @pangtong-fujunshi（spawner.py:1456-1470）

在 _mark_task() 中 conn.close() 之后，检查 status == "failed" 时通过 Blackboard comment + mention_queue 通知庞统。不走 Mail，走黑板 comment + mention 标准流程。

F3: Mail 幻觉门控失败 → 立刻标 failed（dispatcher.py:679-707）

在 _mail_auto_complete() 中，无回复时用与标 done 同样的重试模式（3 次尝试）标 failed。不 retry（Agent turn 已结束，同样 prompt 大概率同样结果）。

9.3 不改的

• compact 检测：Fix-1 session jsonl 扫描是主要防线，Phase 2 无上限 skip + Monitor B2 最多 31.5 分钟，合理
• compact_failed (有JSON+stderr)：暂缓（08 §1.1 已标注）
• agent_error 不改为 retry：未知错误 retry 无意义
• api_error：当前推回 pending + cooldown 是对的