sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily eccb4d2723

CI / lint (pull_request) Successful in 7s

Details

CI / test (pull_request) Successful in 9s

Details

CI / notify-on-failure (pull_request) Successful in 0s

Details

docs: 设计文档编号重排(20→14, 24→15) + 已完成文档状态标注更新

2026-06-13 10:12:39 +08:00

23 KiB

Raw Blame History

02-main-session-delegation.md — Main Session + Delegation 架构

日期: 2026-05-30 作者: 庞统状态: ✅ 已完成（spawner/ticker/dispatcher 全部 use_main_session=True）前置: 01-four-phase-loop.md（四相循环 E2E 验证暴露 session 爆炸问题）

一、问题：现行 spawn 方案的 session 爆炸

现状

spawner 通过 openclaw agent --session-id UUID --message "..." --json spawn Agent：

spawner → 新 UUID session → Agent 执行 → 进程退出 → session 残留

问题

问题	证据	影响
Session 爆炸	今天 E2E 测试 6 个 Agent 产生 68 个 session（16~484 每个），其中 56 个 `gateway-fallback-*`	文件系统堆积、磁盘浪费
空 payloads	绝大部分 spawn 返回 `status: None, payloads: []`	Daemon 以为任务完成了但实际没有产出
上下文丢失	每次 spawn 新 session，Agent 无历史、无 workspace bootstrap	Agent 不知道自己是谁、不知道之前的决策
续杯浪费	续杯时 `reuse_session_id` 复用 UUID，但 Gateway 可能又创建 fallback	round_count 空转、Agent busy 但不产出

根因

openclaw agent --session-id UUID 的语义是"在指定 session 里执行 turn"，但 Gateway 的实际行为是 find-or-create：

session 不存在 → 创建 gateway-fallback-<UUID> session
每次都是全新上下文
Agent 没有历史，没有 SOUL.md 等身份注入

这是结构性问题，不是 bug。 在这个方案上继续修 bug 没有意义。

二、方案：Main Session + Delegation

核心思路

现行：Daemon 硬编码步骤 → spawner 直接 spawn 新 session → Agent 被动执行

改为：Daemon 投递任务 → Agent main session 收到 → Agent 自主分析 → sessions_spawn(subagent) 执行 → sub 完成 → Agent review → 写回黑板

架构对比

┌─ 现行 ──────────────────────────────────────────┐
│                                                  │
│  Daemon/Ticker                                   │
│  ├── broadcast → spawn_full_agent(UUID session)  │
│  │   → Agent 执行固定步骤 prompt                  │
│  │   → 空 payloads / session 残留                 │
│  ├── mention  → spawn_full_agent(UUID session)   │
│  └── review   → spawn_full_agent(UUID session)   │
│                                                  │
└──────────────────────────────────────────────────┘

┌─ 改为 ───────────────────────────────────────────┐
│                                                   │
│  Daemon/Ticker                                    │
│  ├── broadcast → 投递到 Agent main session        │
│  ├── mention  → 投递到 Agent main session         │
│  └── review   → 投递到庞统 main session           │
│                                                   │
│  Agent Main Session（有完整身份+上下文）            │
│  ├── 收到任务消息                                  │
│  ├── 分析黑板（API 读任务详情/上下文/依赖）          │
│  ├── sessions_spawn(subagent, cleanup: "delete")  │
│  │   └── sub 执行具体工作 → 完成后自动清理          │
│  ├── sessions_yield → 等待 sub 完成               │
│  ├── review sub 结果                               │
│  └── 写回黑板（产出/状态/评论）                      │
│                                                   │
└───────────────────────────────────────────────────┘

三条路径的变化

路径	现行	改为
Broadcast dispatch	`spawn_full_agent(session_id=UUID)` 新 session	`spawn_full_agent(use_main_session=True)` main session
Mention	`spawn_full_agent(session_id=UUID)` 新 session	`spawn_full_agent(use_main_session=True)` main session
Review（庞统）	`spawn_full_agent(session_id=UUID)` 新 session	`spawn_full_agent(use_main_session=True)` main session

三、关键机制

3.1 投递到 Main Session

方式：spawn_full_agent(use_main_session=True)（不传 --session-id）

底层命令行：openclaw agent --agent <id> --message "..." --json --timeout N

Gateway 行为（已确认）：

不传 --session-id → 投递到 Agent 的 main session（agent:<id>:main）
main session 正忙 → 消息排队，Agent 当前 turn 完成后处理
Agent 有完整上下文（SOUL.md / MEMORY.md / workspace bootstrap）

调用链路：

spawner.spawn_full_agent(use_main_session=True)
  → session_id = None（不传 --session-id）
  → counter.acquire(agent_id, "main")
  → asyncio.create_subprocess_exec("openclaw", "agent", "--agent", "xxx", ...)
  → asyncio.create_task(_monitor_process(...))  # 异步不阻塞
  → 返回 "main"

_monitor_process()
  → await proc.wait() + 读 stdout  # 异步等子进程退出
  → 子进程退出 → _handle_exit()
    → 解析 --json 输出
    → on_complete 回调（幻觉门控、标状态等）
    → counter.release(agent_id, "main")

关键：openclaw agent 子进程内部是同步阻塞的——它会同步等 Gateway 投递消息到 main session → Agent 执行 turn → 回复 → 子进程退出。所以 on_complete 只在 Agent 真正完成 turn 后才触发。

3.2 Delegation（subagent-delegation skill）

Agent 收到任务后，用 sessions_spawn 创建 subagent 执行具体工作：

sessions_spawn({
  task: "任务目标\n\n上下文信息",
  cleanup: "delete",    // 完成后自动清理 session
  model: "zhipu/glm-5.1",
  label: "T1-01"
})

关键特性：

cleanup: "delete" → sub 执行完 session 立即删除（transcript 保留可查）
main session 通过 sessions_yield 等待 sub 完成（非阻塞，可被新消息打断，Gateway 还能投递新消息）
sub 的结果通过完成事件回传给 main session
subagent 是 Agent 自己 spawn 的，不经过 Daemon counter

3.3 续杯机制

改用 main session 后，续杯逻辑简化：

维度	现行	改为
续杯 session	`reuse_session_id=UUID` 复用原 session	`use_main_session=True` 重新投递到 main session
上下文	新 session 无历史	main session 有完整历史
counter	acquire 新 session key	acquire 同一个 "main" key
失败处理	重试时可能创建新的 fallback session	直接重投 main session，无 fallback 问题

改动：_do_retry 中把 reuse_session_id 改为 use_main_session=True，移除 reuse_session_id 参数。

3.4 Counter（无需改动）

改用 main session 后 counter 逻辑不变：

所有 spawn 走同一个 session key（"main"）
max_per_session=1 保证同一时间只有一个 active turn
max_concurrent_sessions=3 限制同一 Agent 最多 3 个不同 session（main + 可能的 sub）
max_global=5 限制全局并发

注意：subagent 是 Agent 自己 spawn 的，不经过 Daemon counter。Daemon 只控制 main session 的投递。

四、Prompt 设计

4.1 投递消息格式

Daemon 投递到 main session 的消息包含足够的上下文，让 Agent 自主决策：

📋 新任务到达

**任务**: {title}
**描述**: {description}
**Project**: {project_id}
**Task ID**: {task_id}
**类型**: {task_type} | **风险**: {risk_level}
**验收标准**: {must_haves}
**依赖产出**: {depends_on_outputs_summary}

**黑板 API**: http://localhost:8083/api/projects/{project_id}
- 读任务详情: GET /api/projects/{project_id}/tasks/{task_id}?expand=all
- 写产出: POST /api/projects/{project_id}/tasks/{task_id}/outputs
- 写评论: POST /api/projects/{project_id}/tasks/{task_id}/comments
- 更新状态: POST /api/projects/{project_id}/tasks/{task_id}/status

**约束**:
- 完成后必须写产出 + 标 review
- 失败了标 failed 并写明原因
- 优先使用 subagent-delegation skill 进行具体执行
- 禁止使用 sessions_send 直接发消息

4.2 Agent 自主决策

Agent 收到消息后的自主行为（不是硬编码步骤）：

分析上下文：读黑板 API 获取任务详情、依赖、历史讨论
决定执行策略：
- 简单任务 → 自己直接做
- 复杂任务 → sessions_spawn 拆分 sub task
- 需要协作 → @mention 其他 Agent
执行：通过 subagent 或直接执行
Review：检查 sub 结果质量
写回：产出 + 状态 + handoff comment（handoff comment 必须 ≥ 50 字符，用于幻觉门控第三信号检测）

4.3 消息优先级与中断策略

Agent main session 可能同时收到多种消息（新 task / mention / review），按以下优先级处理：

优先级顺序（Prompt 中明确告知 Agent）：

🔍 Review 消息（庞统的打回重做 / GOAL_ACHIEVED）— 最高优先级，先处理再继续当前工作
💬 Mention 消息（其他 Agent 的协作请求）— 高优先级，完成当前 sub task 后立即处理
📋 新任务消息（ticker 投递的广播任务）— 普通优先级，排队处理

中断策略（Prompt 中明确告知 Agent）：

收到 review 消息时 → 暂停当前 sub task，先完成 review，再决定是否继续
收到 mention 消息时 → 完成当前 sub task（如果 sub 正在执行），然后处理 mention
收到新任务消息时 → 排队等待，当前任务完成后再处理
任何时候一个任务完成后，检查是否有更高优先级消息排队

队列管理：

Agent 自己维护任务队列（在对话中记忆），不需要 Daemon 管理
每一步开始前先检查新消息，如果有高优先级消息就调整顺序
完成当前任务后，从队列取下一个

4.4 Subagent 背压控制

Agent 同时 spawn 的 subagent 数量有硬性上限：

参数	值
单轮同时 sub 上限	3
单任务累计 sub 上限	8

超限时 subagent-delegation skill 自动拒绝，并在 prompt 中提醒 Agent："已超出 subagent 数量限制，请等待现有 sub 完成后再创建新 sub。"

在 subagent-delegation skill 中通过计数器维护（Daemon 不参与 subagent 计数）。

4.5 庞统 Review 消息格式

🔍 一轮结束，需要你的 review

**Parent Task**: {title}（ID: {task_id}）
**Project**: {project_id}
**Round**: {round_num}/{max_rounds}

**本轮状态**:
- 完成: {done} | 失败: {failed} | 取消: {cancelled}
- 总计: {total}

**三问**:
1. Goal 还清晰吗？（是否有 goal drift）
2. 成果物覆盖 goal 了吗？（逐条检查验收标准）
3. 下一轮需要做什么？（创建新 sub tasks / 标记完成 / 调整方向）

**你可以**:
- 创建新 sub task: curl -X POST http://localhost:8083/api/projects/{project_id}/tasks ...
- 调整 goal
- 标记 GOAL_ACHIEVED

回复 GOAL_ACHIEVED 表示完成，否则系统会等待你创建新 sub tasks。

五、Daemon 侧改动

5.1 改动范围

不需要新增方法。直接复用 spawn_full_agent(use_main_session=True)，Mail 路径已验证此模式。

改动集中在调用侧（把参数改对）和回调侧（把完成检测从邮件改为黑板）：

文件	改动点	改动量
`ticker.py`	3 处 `spawn_full_agent` 调用加 `use_main_session=True`；移除 `new_session=True`	~15 行
`dispatcher.py`	确定性路由改 `use_main_session=True`；新增 `_task_auto_complete`	~40 行
`spawner.py`	`_do_retry` 续杯改 `use_main_session=True`；标注 `new_session`/`reuse_session_id` 废弃	~10 行
`ticker.py`	新增 `_task_verify_completion`（第一层幻觉门控）；review 前跑 `_verify_output_files`（第二层）	~50 行

总改动量：~115 行，涉及 3 个文件。不涉及 DB schema 变更、不涉及前端。

5.2 Ticker 改动

方法	改动
`_broadcast_and_dispatch`	`spawn_full_agent(..., use_main_session=True)` 替代当前的默认参数
`_process_mentions`	同上
`_spawn_pangtong_review`	同上
`_check_round_complete`	保留 `reviewing` 中间态逻辑（SYS-BUG-01 修复）
`_handle_review_conclusion`	保留，从 `on_complete` 回调中的黑板状态变化触发
新增 `_task_verify_completion`	第一层幻觉门控（三信号检查）
新增 `_verify_output_files`	第二层幻觉门控（文件存在性检查）

5.3 Dispatcher 改动

确定性路由改 use_main_session=True
新增 _task_auto_complete（复用 Mail 的 _mail_auto_complete 模式）
new_session 参数标注废弃

5.4 废弃代码

spawn_full_agent 的 new_session 参数 → 标注废弃（保留接口兼容，变更前 grep -rn 'new_session' 确认零调用方后标废弃）
reuse_session_id 参数 → 标注废弃（续杯改用 use_main_session=True；变更前 grep -rn 'reuse_session_id' 确认零调用方）
gateway-fallback-* session 的产生路径 → 自然消失（不再传 --session-id UUID）

5.5 `on_complete` 回调路由

on_complete 回调中，根据 task_type 分支选择检测逻辑：

def _handle_completion(self, task, db_path):
    if task["type"] == "mail":
        return self._mail_auto_complete(task, db_path)
    else:
        return self._task_auto_complete(task, db_path)

_task_auto_complete 检查黑板三信号（status/outputs/comments），_mail_auto_complete 检查是否有回复邮件。两者共享超时兜底逻辑（ticker 轮询 working 状态）。

六、Session 生命周期对比

现行

每次 spawn → 创建新 session → 执行 → 残留 → 手动清理
                                          ↓
                              gateway-fallback-* 堆积

改为

main session（常驻，有完整上下文）
  ├── 收到任务 A → spawn sub(A1, cleanup: delete) → yield → review → 写回
  ├── 收到任务 B → spawn sub(B1, cleanup: delete) → yield → review → 写回
  └── 收到 mention → 自主处理 → 写回

sub session（临时，完成即删）
  ├── sub(A1) → 执行 → 完成 → session 删除（transcript 保留）
  └── sub(B1) → 执行 → 完成 → session 删除（transcript 保留）

Session 数量：6 个 main session（常驻）+ 临时 sub session（用完即删） 对比现行：6 个 main + N 个 gateway-fallback-*（无限增长）

七、收益与风险

收益

维度	改善
Session 数量	从无限增长 → 6 个 main + 临时 sub
Agent 上下文	从无历史 → 完整身份 + 记忆 + workspace
代码简化	`new_session` / `reuse_session_id` 不再有调用方
Prompt 灵活度	从硬编码步骤 → Agent 自主决策
空 payloads	消除（main session 有完整生命周期管理）
续杯可靠性	不再创建 fallback session，直接重投 main session

风险与缓解

风险	缓解
main session 上下文膨胀	OpenClaw 自带的 compact 机制处理；sub session 不膨胀（用完删）
main session 被阻塞	`sessions_yield` 非阻塞，可被新消息打断；Gateway 排队机制保证不丢消息
sub 质量不可控	main session review sub 结果；reviewing 中间态保证 round 不重复触发
Prompt 依赖	投递消息中明确告诉 Agent "优先使用 subagent-delegation skill"；skill 已调优
main session 排队延迟	Daemon 投递后 `on_complete` 异步等结果；ticker 轮询黑板状态兜底
main session prompt 污染	每次投递消息中明确标注当前任务 ID；Agent 每步开始前确认当前处理的任务；compact 机制清除旧消息
sub 失败传导	投递 prompt 中明确告诉 Agent：sub 失败时不要标 done，先分析失败原因；可重试 ≤ 2 次，然后标 failed 并写原因到 comment
openclaw agent 子进程超时	`--timeout` 超时后子进程退出，但 main session 中的 Agent turn 可能还在进行。Daemon 遇到超时：不立即标 failed，留 working 等 ticker 下一次轮询检查

八、Mail 路径已验证的完整模式（可直接复用）

Mail 路径（dispatcher.py _mail_on_checks_passed + _mail_auto_complete）已经完整实现了 main session + 完成检测的全链路：

openclaw agent --agent xxx（不传 --session-id）→ Gateway 投递到 main session
  → Agent 处理 → 子进程退出
  → _monitor_process → _handle_exit
    → on_complete 回调 → _mail_auto_complete
      → 幻觉门控：检查黑板是否有回复
        → 有回复 → 标 done
        → 无回复 → 留 working，等 ticker 超时兜底再查
    → counter.release(agent_id, "main")

已验证的机制

机制	Mail 实现	普通 Task 复用
Main session 投递	`use_main_session=True`	✅ 直接复用
`on_complete` 回调	`_mail_on_complete` → `_mail_auto_complete`	✅ 改为 `_task_auto_complete`（检查产出/状态而非邮件回复）
幻觉门控	`_mail_check_reply` 检查回复邮件	⚠️ 改为三信号检查（status + outputs + comments）
超时兜底	ticker 轮询 working 状态 + 再次检查	✅ 直接复用
auto-working	`on_checks_passed` 回调中标 working	✅ 直接复用
Counter acquire/release	`"main"` session key	✅ 直接复用

普通 Task 的完成检测

Mail 的 _mail_auto_complete 检查"是否有回复邮件"。普通 Task 改为 _task_auto_complete，检查黑板三信号（详见第九节幻觉门控方案）。

九、幻觉门控方案（三层）

第一层：Daemon 确定性检查（on_complete 触发）

触发时机：on_complete 回调（openclaw agent 子进程退出时）。 Agent 在 main session 里执行时子进程还活着，不会触发。不存在长任务误判。

三信号检查：status / outputs / comments 任一存在即视为有效完成。

def _task_verify_completion(self, task_id, db_path) -> bool:
    """普通 Task 完成验证（泛化 Mail 幻觉门控）"""
    conn = get_connection(db_path)
    try:
        # 信号 1：Agent 已自行更新状态（review/done/failed）
        row = conn.execute(
            "SELECT status FROM tasks WHERE id=?", (task_id,)
        ).fetchone()
        TERMINAL_STATES = {"review", "done", "failed", "cancelled"}
        if not row or row["status"] in TERMINAL_STATES:
            return True  # Agent 自己标了终态

        # 信号 2：outputs 表有产出
        output_count = conn.execute(
            "SELECT COUNT(*) FROM outputs WHERE task_id=?", (task_id,)
        ).fetchone()[0]
        if output_count > 0:
            return True

        # 信号 3：有评论/handoff（Agent 至少写了交接文档，且 ≥ 50 字符）
        comment_count = conn.execute(
            "SELECT COUNT(*) FROM comments WHERE task_id=? AND author != 'system' AND LENGTH(content) >= 50",
            (task_id,)
        ).fetchone()[0]
        if comment_count > 0:
            return True

        # 三无 → 可能是幻觉
        return False
    finally:
        conn.close()

行为：

通过 → 标 review（等待司马懿 review，详见 #01 §4.6）
不通过 → 留 working，ticker 重查（最多 3 次，然后标 failed）

重试计数器存储：在 tasks 表中复用 retry_count 字段（现有字段，用于续杯计数）。Daemon 在 _task_verify_completion 返回 False 后递增该字段，达到 3 次后标 failed。不走内存维护（重启丢失）。

第二层：Daemon 产出物文件验证（review 阶段触发）

对 outputs 表中有 content_path 的产出，验证文件是否真实存在。放在 Daemon（确定性代码，成本低、不依赖 AI）：

def _verify_output_files(self, task_id, db_path) -> list[str]:
    """验证产出物文件是否真实存在"""
    conn = get_connection(db_path)
    outputs = conn.execute(
        "SELECT content_path FROM outputs WHERE task_id=? AND content_path IS NOT NULL",
        (task_id,)
    ).fetchall()
    missing = []
    for o in outputs:
        if not Path(o["content_path"]).exists():
            missing.append(o["content_path"])
    return missing

触发时机：review 阶段（庞统 review 前），Daemon 先跑一次文件验证。行为：missing 非空 → 在黑板 comment 中标注缺失文件，供庞统 review 时参考。

第三层：AI 验证（review prompt 中要求）

庞统/司马懿 review 时，在 prompt 中要求：

检查产出是否覆盖 must_haves 中的验收标准
如果产出不可验证，在评论中标注

这一层由 AI 做，成本高但准确度高，只在 review 时触发。

三层关系

openclaw agent 子进程退出
  → on_complete 回调
    → 第一层（三信号：status / outputs / comments）
      → 有信号 → 标 review
      → 三无 → 留 working（ticker 重查，最多 3 次 → failed）

司马懿 review（_dispatch_reviews 确定性路由）
  → review 通过 → 标 done
  → review 不通过 → 打回 working

庞统 review（_check_round_complete → _spawn_pangtong_review）
  → 第二层（文件存在性：content_path 验证）
  → 第三层（AI 验证：产出是否覆盖 must_haves）
  → GOAL_ACHIEVED → parent done
  → 创建新 sub task → 新一轮执行
  → 不通过 → 打回重做

十、实施计划

Phase 1：统一投递到 main session + 幻觉门控

所有 spawn_full_agent 调用改为 use_main_session=True（3 处）
续杯 _do_retry 改为 use_main_session=True
新增 _task_verify_completion（第一层幻觉门控）
新增 _verify_output_files（第二层幻觉门控）
单元测试覆盖

Phase 2：E2E 测试适配 + 验证

适配新的投递机制（不再依赖 --session-id UUID）
验证 session 不爆炸
验证 Agent 自主决策行为
重跑 01-four-phase-loop 的 E2E 测试

Phase 3：已完成

用户确认一步到位直接使用 use_main_session=True，不需要 feature flag 灰度切换。所有 spawn_full_agent 调用均已硬编码 use_main_session=True。

Agent main session 频繁超时（>5 次/小时openclaw agent 子进程超时）

十一、参考文件

文件	说明
`01-four-phase-loop.md`	四相循环设计（现行方案）
`v2.8-direction-notes.md`	v2.8/v2.9 方向（Prompt 进化 + Daemon 退化）
`subagent-delegation/SKILL.md`	Delegation skill（Agent 侧执行指南）
`counter.py`	并发控制（per session 粒度）
`spawner.py` `_do_retry`	续杯机制
`dispatcher.py` `_mail_auto_complete`	Mail 幻觉门控（已验证，可复用）

23 KiB Raw Blame History Unescape Escape

02-main-session-delegation.md — Main Session + Delegation 架构

一、问题：现行 spawn 方案的 session 爆炸

现状

问题

根因

二、方案：Main Session + Delegation

核心思路

架构对比

三条路径的变化

三、关键机制

3.1 投递到 Main Session

3.2 Delegation（subagent-delegation skill）

3.3 续杯机制

3.4 Counter（无需改动）

四、Prompt 设计

4.1 投递消息格式

4.2 Agent 自主决策

4.3 消息优先级与中断策略

4.4 Subagent 背压控制

4.5 庞统 Review 消息格式

五、Daemon 侧改动

5.1 改动范围

5.2 Ticker 改动

5.3 Dispatcher 改动

5.4 废弃代码

5.5 on_complete 回调路由

六、Session 生命周期对比

现行

改为

七、收益与风险

收益

风险与缓解

八、Mail 路径已验证的完整模式（可直接复用）

已验证的机制

普通 Task 的完成检测

九、幻觉门控方案（三层）

第一层：Daemon 确定性检查（on_complete 触发）

第二层：Daemon 产出物文件验证（review 阶段触发）

第三层：AI 验证（review prompt 中要求）

三层关系

十、实施计划

Phase 1：统一投递到 main session + 幻觉门控

Phase 2：E2E 测试适配 + 验证

Phase 3：已完成

十一、参考文件

23 KiB

Raw Blame History

5.5 `on_complete` 回调路由