# 运行时操作协议 v2026-04-20 (v8.1 更新)

主代理执行多代理任务时的**强制执行规范**。

⚠️ **本文件中的规则不可违反。主代理不得跳过、省略或修改任何流程阶段。**

---

## 🆕 v8.1 新增：子代理轮询监控协议（2026-04-20）

### 背景问题

在 OpenClaw vs Hermes 对比研究（2026-04-19）中发现：
- **40% 子代理"完成"但未及时被主代理感知**
- **Technical_Specialist 发送询问消息但主代理未收到**
- **主代理误判子代理"丢失"，导致重复执行浪费 350k tokens**

**根因**：
1. `sessions_spawn` 完成通知是 push-based，但子代理的 `sessions_send` 询问消息不保证主代理能收到
2. 主代理被动等待完成通知，没有主动轮询子代理状态
3. 缺少超时处理机制，无法区分"延迟"和"丢失"

### v8.1 解决方案

#### 1. 主动轮询机制（必须执行）

```javascript
// Phase 3: collect 阶段必须使用主动轮询
const { collectResults, PollMonitor } = await import('./lib/executor_v8.1.js');

const monitor = new PollMonitor({
  pollIntervalMs: 30000,  // 每 30 秒检查一次
  timeoutMs: 3600000,     // 1 小时超时
  logFile: './poll_log.jsonl'  // 可选：记录完整轮询历史
});

// 对每个子代理进行轮询
for (const agentName of agentNames) {
  const result = await monitor.pollUntilReady(
    agentName,
    `${outputDir}/${agentName}_report.md`
  );
  
  if (!result.success) {
    // 触发降级协议
    console.warn(`${agentName} 超时：${result.reason}`);
  }
}
```

#### 2. 轮询状态定义

| 状态 | 触发条件 | 处理动作 |
|------|---------|---------|
| `POLL_START` | 开始轮询 | 记录开始时间、输出文件路径 |
| `POLL_CHECK` | 每次检查文件 | 记录文件状态（不存在/大小不足/内容无效） |
| `FILE_READY` | 文件有效产出 | 记录文件大小、行数，进入验证阶段 |
| `POSSIBLY_LOST` | 轮询≥10 次且>5 分钟 | 建议检查子代理会话状态或触发降级 |
| `TIMEOUT` | 超过 1 小时 | 触发降级协议（Level 2 或 3） |
| `ERROR` | 异常 | 记录错误详情，标记为缺失 |

#### 3. 超时降级策略

| 超时时间 | 降级级别 | 处理动作 |
|---------|---------|---------|
| < 5 分钟 | 正常等待 | 继续轮询 |
| 5-10 分钟 | Level 1（轻度） | 记录 POSSIBLY_LOST，准备补做 |
| 10-30 分钟 | Level 2（中度） | 重试缺失代理（换模型/加时限） |
| > 30 分钟 | Level 3（重度） | 主代理全面接管 |
| > 1 小时 | Level 3（重度） | 强制触发降级，记录审计日志 |

#### 4. 消息路由验证

**问题**：子代理通过 `sessions_send` 发送询问消息，但主代理可能收不到。

**v8.1 要求**：
1. 子代理在发送询问消息后，**必须同时写入进度文件**
2. 主代理轮询时**检查进度文件**，而不仅依赖消息推送
3. 进度文件格式：`{outputDir}/progress/{agentName}_status.json`

```json
{
  "agent": "Technical_Specialist",
  "status": "completed",
  "timestamp": "2026-04-20T09:38:00Z",
  "outputFile": "Technical_Specialist_report.md",
  "message": "已完成量化对比分析，请确认是否需要补充 03_metrics_comparison_v2.md",
  "awaitingResponse": true
}
```

#### 5. 审计日志要求

**必须记录**（用于事后调试和根因分析）：
- 每个子代理的 spawn 时间、预期完成时间、实际完成时间
- 每次轮询的时间戳、文件状态
- 超时事件的详细信息（elapsedMs, pollCount, reason）
- 降级决策的依据（成功率、缺失代理列表）

**日志格式**（JSONL，便于机器解析）：
```json
{"timestamp":"2026-04-20T09:38:00Z","agent":"Technical_Specialist","event":"FILE_READY","elapsedMs":132000,"pollCount":5,"fileSize":20036}
```

---

## 0. 质量优先原则（最高约束，用户指定）

**质量 > 速度。质量 > 一切。**

- 深度研究任务始终以**质量优先**为第一原则
- **未经用户明确确认，不得以任何理由降低质量标准、裁剪流程环节、省略审核步骤**
- 当质量与交付速度发生冲突时，**主代理必须选择质量**，并向用户说明原因
- 如需调整质量策略（如时间紧迫需快速交付），**必须向用户提出请求并获得明确确认**后才能修改
- 即使子代理全部超时、全部失败，也**不允许跳过 Critic 审核直接进入聚合**——Critic 可以审核「主代理补做的内容」
- 此原则优先级高于所有其他规则，包括流程不可跳跃原则

## 1. 流程不可跳跃原则（最高优先级）

**任何已触发的流程阶段都不可省略、跳过或合并。**

**违反后果**：任务看板缺失、用户无法追踪进度、Critic 反馈未处理、交付质量不可控。

完整流程骨架（6个Phase，必须按顺序执行）：
```
Phase 0: 提纲确认 → 生成提纲 → 展示给用户 → 等待确认
Phase 1: plan → 生成执行计划 + 创建看板（createPlanBoard）→ 展示计划看板
Phase 2: spawn → 创建执行看板（createExecBoard）→ 启动子代理 → yield等待 → 更新看板
Phase 3: collect → 检查文件 → 评估成功率 → 决定降级/继续 → 更新看板
Phase 4: critic → spawn Critic → yield等待 → 审核通过 → 更新看板
       ├── 通过 → 进入 Phase 5
       └── 不通过 → Phase 4b（返工循环）→ spawn 修正任务 → yield → 再审 → 通过 → Phase 5
Phase 5: aggregate → 读取所有报告 + Critic 意见 → 融合为 FINAL_REPORT → 更新看板
Phase 6: finalize → 输出执行摘要 + 展示最终执行看板
```

**Phase 间的自动触发**：每个 Phase 完成后，主代理**必须自动进入下一个 Phase**，无需用户催促。

| 流程 | 可跳过条件 | 不可跳过 |
|------|-----------|---------|
| 复杂度评估 → 路由 | 无（必须执行） | — |
| direct 路由 → 主代理自检验证 | 无 | 即使简单任务也必须经过验证 |
| hybrid 路由 → Critic 审核 | 无 | — |
| full 路由 → 并行执行 → 结果收集 → Critic审核 → 聚合 | 无 | 即使3/3全部完成也必须执行聚合 |
| 结果收集 → 降级 | 无缺失时跳过降级 | — |

```
完整流程骨架（不可删减）：
  提纲确认 → decompose → evaluate_complexity → route
    → [parallel/spawn] → collect_results → validate
    → [critic_review] → aggregate → finalize
```

每个阶段完成后必须输出**阶段报告**，写入对应看板后进入下一阶段。

---

## 1. 任务看板体系（新增）

### 1.1 看板结构

系统维护两份看板：

**A. 计划看板（Plan Board）**—— 在 `plan` 阶段生成
```json
{
  "workflow_id": "wf_xxx",
  "goal": "...",
  "complexity": "complex",
  "route": "full",
  "phases": [
    {
      "id": "parallel",
      "name": "并行执行",
      "type": "parallel",
      "status": "pending",
      "tasks": [
        {
          "agent": "Research_Analyst",
          "model": "openrouter/xxx",
          "timeout": 300,
          "output_file": "shared/final/Research_Analyst_report.md",
          "status": "pending"
        }
      ]
    }
  ],
  "created_at": "ISO时间",
  "updated_at": "ISO时间"
}
```

**B. 执行看板（Execution Board）**—— 每阶段完成后更新
```json
{
  "workflow_id": "wf_xxx",
  "current_phase": "parallel",
  "elapsed_total": "2m30s",
  "phases": [
    {
      "id": "parallel",
      "status": "completed",
      "started_at": "ISO时间",
      "completed_at": "ISO时间",
      "elapsed": "2m30s",
      "tasks": [
        {
          "agent": "Research_Analyst",
          "status": "success",
          "model": "openrouter/xxx",
          "model_tier": "free",
          "thinking": "low",
          "timeout": 300,
          "actual_time": "1m27s",
          "tokens": { "in": 412200, "out": 5900 },
          "output_file": "shared/final/Research_Analyst_report.md",
          "file_size": "17KB",
          "file_validated": true
        }
      ]
    }
  ]
}
```

### 1.2 看板存储

- 计划看板：`shared/boards/{workflow_id}_plan.json`
- 执行看板：`shared/boards/{workflow_id}_exec.json`

### 1.3 看板展示格式（主代理输出到用户）

```
╔═══════════════════════════════════════════════════════╗
║  📋 计划看板 | wf_xxx                                   ║
║  目标：中国新能源汽车出海策略研究                       ║
║  路由：full (复杂) | 阶段数：4                          ║
╠═══════════╤═══════════════╤════════╤════════╤═════════╣
║ 阶段      │ 代理          │ 模型   │ 超时   │ 输出文件║
╠═══════════╪═══════════════╪════════╪════════╪═════════╣
║ ⚡并行    │ Research_     │ qwen   │ 300s   │ R_...md ║
║           │ Analyst       │ :free  │        │         ║
║           │ Technical_    │ glm-5  │ 300s   │ T_...md ║
║           │ Specialist    │        │        │         ║
║           │ Strategy_     │ nemot  │ 300s   │ S_...md ║
║           │ Analyst       │ :free  │        │         ║
║ 🔍审核    │ Critic        │ glm-5  │ 180s   │ C_...md ║
║ 🧠聚合    │ 主代理        │ —      │ 120s   │ AGR.md  ║
║ 📝终稿    │ 主代理        │ —      │ 180s   │ FIN.md  ║
╚═══════════╧═══════════════╧════════╧════════╧═════════╝
```

### 1.4 执行看板格式

```
╔═════════════════════════════════════════════════════════════╗
║  📊 执行看板 | wf_xxx | 总耗时：8m42s                        ║
╠═══════════╤═══════════════╤════════╤════════╤═══════════════╣
║ 阶段      │ 代理          │ 状态   │ 耗时   │ 模型/Tokens   ║
╠═══════════╪═══════════════╪════════╪════════╪═══════════════╣
║ ⚡并行    │ Research_     │ ✅成功 │ 1m27s  │ qwen/free     ║
║ (3/3)     │ Analyst       │        │        │ 412k in/6k    ║
║           │               │        │        │ 文件17KB      ║
║           │ Technical_    │ ✅成功 │ 1m42s  │ glm-5         ║
║           │ Specialist    │        │        │ 396k in/6k    ║
║           │               │        │        │ 文件18KB      ║
║           │ Strategy_     │ ✅成功 │ 1m56s  │ nemotron/free ║
║           │ Analyst       │        │        │ 320k in/7k    ║
║           │               │        │        │ 文件19KB      ║
║ 🔍审核    │ Critic        │ ✅成功 │ 1m44s  │ glm-5         ║
║           │               │        │        │ (重试1次)     ║
║           │               │        │        │ 文件11KB      ║
║ 🧠聚合    │ 主代理        │ ✅成功 │ 50s    │ —             ║
║           │               │        │        │ 文件53KB      ║
╠═══════════╧═══════════════╧════════╧════════╧═══════════════╣
║ 总计：4代理 + 主代理 | 5/5阶段完成 | 降级1次(Critic重试)     ║
╚═════════════════════════════════════════════════════════════╝
```

---

## 2. 复杂度评估与路由决策

执行任何多代理任务前，主代理必须先做复杂度评估：

| 复杂度 | 判定条件 | 路由 | 说明 |
|--------|---------|------|------|
| **简单** | 单一维度、无需交叉验证、2分钟内完成 | `direct` | 主代理直接完成，**但必须自检验证** |
| **中等** | 需要外部数据验证、或产出需要独立审核 | `hybrid` | 主代理 + 1个 Critic |
| **复杂** | 多维度并行研究、需要交叉验证 | `full` | 完整多代理 + Critic |

**⚠️ 无论选择哪条路由，最终产出都必须经过验证（主代理自检或 Critic 审核）。**

---

## 4. 超时预设（固化配置）

按任务类型预设超时值，禁止随意设定：

| 任务类型 | 超时值 | 适用场景 |
|---------|--------|---------|
| `research_web` | **480s** | 需要 web 搜索的研究任务（⚠️ 从 300s 提升至 480s，解决长报告超时问题） |
| `research_analysis` | **480s** | 纯分析型研究（⚠️ 从 300s 提升至 480s） |
| `review_validate` | **180s** | Critic 审核、交叉验证 |
| `quick_task` | **120s** | 简单的数据整理、格式转换 |
| `code_develop` | **600s** | 代码编写、调试任务 |

---

## 4. 子代理 Task 提示词模板（强制格式）

每个子代理的 task 必须包含 4 个部分，缺一不可。详见前版协议，此处不再重复。

---

## 5. Spawn 参数标准（固化配置）

```json
{
  "runtime": "subagent",
  "mode": "run",
  "thread": false,
  "timeoutSeconds": "按任务类型查超时预设表",
  "cleanup": "keep"
}
```

---

## 6. 结果收集与降级协议

### 6.1 文件检查
并行阶段完成后，主代理必须检查每个子代理的 `output_file`：
- 文件存在 + 内容非空 → ✅ 成功
- 文件不存在 → ❌ 缺失

### 6.2 成功率评估
```
success_rate = 成功数 / 总数
100%  → 进入 Critic 审核阶段
>=60% → 策略A：主代理补做缺失报告
>=30% → 策略B：重试缺失代理（超时×1.5）
<30%  → 策略C：主代理全部自行完成
```

### 6.3 ⚠️ 不可跳过聚合阶段
即使 100% 成功，也必须执行聚合阶段。不允许直接将分支报告交付给用户。

---

## 7. Phase 0 — 提纲生成与审核（最高优先级门禁）

> 本节定义了流程的「0 阶段」。提纲未经用户确认，**不得执行 Phase 1-6 的任何步骤**。用户修改次数不限，直到满意为止。**提纲确认通过后，主代理根据已确认的提纲拆分子代理任务，再进入 Phase 1。**

### 7.1 提纲生成原则

主代理在收到研究目标后，**首先亲自（不拆分子任务）生成完整的研究提纲（或模板）**，遵循以下标准：

**A. 参考方法论**
- **麦肯锡金字塔原理**：自上而下构建研究框架，结论先行，每个章节有核心判断，子章节支撑主章节论点
- **券商深度研报结构**：开篇即核心观点 → 行业全景 → 竞争格局 → 产业链分析 → 财务/投资逻辑 → 风险提示
- **避免**：纯科普式罗列、百科式条目、无主线的章节堆砌

**B. 提纲格式要求**

提纲要以 Markdown 格式呈现，**最少包含二级目录**（根据内容可增减层级），每级目录下必须明确内容要求。格式规范：

```
📋 研究报告提纲（待审核）
════════════════════ ═══════════

研究目标：{用户提交的原始目标}
报告定位：{行业深度报告 / 产业全景报告 / 技术评估报告 / 战略研判报告}

---
# {报告标题}
> **核心观点/主旨**：一句话概括本报告要传递的核心判断

## 一、{一级章节标题}
> **本章核心判断**：一句话说明本章的论点

### 1.1 {二级章节标题}
**内容要求**：明确写明该节需要覆盖什么、回答什么问题
**数据/证据**：需要哪些数据支撑（公开数据/子代理调研/案例分析等）
**输出标准**：预期交付物（数据表/对比矩阵/判断结论等）

### 1.2 {二级章节标题}
**内容要求**：...
**数据/证据**：...
**输出标准**：...

## 二、{一级章节标题}
> **本章核心判断**：...
### 2.1 {二级章节标题}
**内容要求**：...
...

## N、结论与投资建议
> **本章核心判断**：给出具体的、可操作的结论
### N.1 关键判断
### N.2 投资策略/行动建议

════════════════════════════════════
📌 说明：
• 以上为报告结构提纲，不含内部流程痕迹
• 每节的「内容要求」明确了该节必须交付的分析深度
• 确认通过后，主代理将根据提纲拆分子代理任务

⏱️ 预计执行规模：{代理数} 个子代理 + Critic审核

请确认：
  - 回复"确认"或"OK" → 提纲确认通过，主代理开始拆分任务
  - 提出修改意见（如"增加XX章节"、"XX太浅"、"合并A和B"）→ 我将调整后再次展示
  - 回复"取消" → 终止任务
════════════════════════════════════
```

**C. 内容要求规范**
- **一级章节**：必须有核心判断（不是"介绍了XXX概况"，而是"我们认为XXX"）
- **二级章节**：必须有明确的「内容要求」「数据/证据」「输出标准」三项
- **禁止科普式章节**：不得从"什么是XX"等基础定义开头，必须直接从判断/分析开始
- **必须有结论章节**：最后一章必须是"结论与投资建议/行动建议"，给出具体、可操作的建议

### 7.2 交互流程

```
用户提交目标
  ↓
主代理亲自生成提纲（不拆分任务）→ 展示给用户
  ↓
用户审核
  ├── "确认" / "OK" / "开始" → ✅ 提纲确认通过
  │   → 主代理根据确认的提纲拆分子代理任务
  │   → 进入 Phase 1
  ├── 修改意见 → 主代理调整提纲 → 再次展示 → 等待用户（循环）
  └── "取消" → ❌ 终止任务
```

### 7.3 强制约束

- **未经用户确认研究提纲，禁止启动任何子代理**
- **提纲确认通过前，禁止进行任务拆分、Phase 1-6 的任何步骤**
- 用户修改次数不限，直到满意为止
- 提纲确认通过后，主代理**必须根据已确认的提纲**拆分子代理任务，每个子代理的任务提示词中引用提纲对应的章节

---

## 8. 主代理执行流程

```
Phase 0: 提纲确认
  → 主代理亲自生成提纲（含一/二级目录+内容要求）→ 展示给用户 → 用户审核/修改（多轮）
  → 用户确认 → 主代理根据提纲拆分子代理任务 → 进入 Phase 1

Phase 1: plan
  → 生成执行计划 + 更新计划看板

Phase 2: spawn（并行阶段）
  → 对所有子代理调用 sessions_spawn
  → **yield 等待 completion event**（不轮询，不主动检查）
  → 收到 completion event 后更新执行看板

Phase 3: collect
  → 检查 output_file 存在性
  → 评估成功率 → 决定降级/继续

Phase 4: critic
  → spawn Critic 子代理
  → yield 等待 completion event
  → 检查审核报告

Phase 5: aggregate
  → 读取所有分支报告
  → 融合为完整的 FINAL_REPORT.md
  → 更新执行看板

Phase 6: finalize
  → 输出执行摘要
  → 等待用户确认归档
```

**关键规则**：
- Phase 0 是用户审批门，**提纲未确认前不得进行任何任务拆分或启动子代理**
- 提纲确认后，主代理**必须按确认的提纲**拆分子代理任务，每个子代理的任务必须映射到提纲的具体章节
- 子代理全部完成后（Phase 2），主代理收到 completion event 后**自动进入 Phase 3**，无需用户催促
- 每个阶段完成后**必须更新执行看板**并保存到 `shared/boards/`
- 聚合阶段不可跳过
- Critic 审核不通过时**必须进入返工循环**，不允许直接进入聚合

## 1.5 看板展示规范（强制）

主代理在每个阶段完成后**必须执行以下输出**：

### Phase 1 完成后：展示计划看板
调用 `createPlanBoard()` → 生成 JSON → **将格式化后的看板文本展示给用户`

### Phase 2-5 每个阶段完成后：更新并展示执行看板
调用 `createExecBoard()` 初始化 → `updateExecBoard()` 更新状态 → **将格式化后的看板文本展示给用户`

### 最终看板展示（Phase 6）
展示完整的执行看板，包含：
- 每个阶段的状态（成功/失败/重试）
- 每个代理的实际用时、模型名称、tokens 消耗、文件大小
- 总的阶段进度和耗时

**不展示看板 = 流程未完成。** 这是判断主代理是否遵循协议的核心指标。

---

## 9. Critic 审核与返工流程（强制闭环）

### 9.1 Critic 审核结论分类

| 结论 | 处理方式 |
|------|----------|
| **通过** | 直接进入 Phase 5 聚合 |
| **需修正后通过** | 进入 Phase 4b 返工循环 |
| **拒绝** | 废弃当前轮次，从 Phase 2 重新启动 |

### 9.2 返工循环（Phase 4b）

**触发条件**：Critic 审核结论不是"通过"。

**步骤**：
1. 主代理读取 `Critic_report.md`，提取每个代理需要修正的问题列表
2. 对出问题的代理调用 `buildRework SpawnParams()` 生成修正任务的 spawn 参数
3. 使用 `sessions_spawn` 并行下发修正任务
4. yield 等 completion event
5. 修正完成后，再次 spawn Critic 审核修正版本
6. 重复直到 Critic 审核**通过**

**约束**：
- 最多返回 **2 轮** ，第 2 轮后强制通过（避免无限循环）
- 每轮返工必须在执行看板上记录
- 返工轮次的版本号递增（v2, v3...）

---

## 10. 输出文件分层管理

### 10.1 设计原则

**不同研究任务必须完全隔离，不可混同。** 同一研究任务的不同迭代版本按版本号分层。

### 10.2 三级目录结构

```
shared/
├── boards/                              # 任务看板（JSON，全局共享）
│   ├── wf_xxx_plan.json
│   └── wf_xxx_exec.json
│
├── researches/                          # 按研究任务隔离（第一级）
│   │
│   ├── ev-overseas-strategy_20260403/  # ← 研究任务A（slug+日期）
│   │   ├── v1/                          #   第1轮原始产出（第二级）
│   │   │   ├── Research_Analyst_report.md
│   │   │   ├── Technical_Specialist_report.md
│   │   │   ├── Strategy_Analyst_report.md
│   │   │   └── Critic_report.md
│   │   ├── v2/                          #   返工轮产出（第二级）
│   │   │   ├── Research_Analyst_report_v2.md
│   │   │   ├── Technical_Specialist_report_v2.md
│   │   │   └── Strategy_Analyst_report_v2.md
│   │   └── final/                       #   最终交付物
│   │       ├── AGGREGATED_REPORT.md
│   │       └── FINAL_REPORT.md
│   │
│   ├── ai-healthcare_20260405/         # ← 研究任务B（完全不同的任务）
│   │   ├── v1/
│   │   │   ├── Research_Analyst_report.md
│   │   │   ├── ...
│   │   └── final/
│   │
│   └── smart-grid_20260410/            # ← 研究任务C
│       ├── v1/
│       └── final/
│
└── archive/                              # 归档（用户确认后移动）
    └── {research-slug}_{date}_wf_xxx/
```

### 10.3 层级说明

| 层级 | 标识 | 说明 |
|------|------|------|
| **L1 研究任务** | `{research-slug}_{YYYYMMDD}/` | 从研究目标提取slug（≤50字符，仅小写字母/数字/-），加日期后缀确保唯一 |
| **L2 迭代版本** | `v{n}/` | 同一研究任务的第N轮执行（含返工） |
| **L3 交付物** | `final/` | 该研究任务的最终产物，聚合所有迭代后的完整报告 |

### 10.4 隔离规则

1. **不同研究任务绝对不可共用目录**——即使目标相似也必须创建独立目录
2. **同一研究任务的返工轮在 v{n} 下新增目录**，不覆盖旧版本
3. **看板文件独立管理**——放在 `boards/` 下，以 workflow_id 命名
4. **归档按研究任务移动**——整个 researches/{slug}/ 目录移入 archive/
5. **旧 `shared/final/` 中的文件在用户确认归档时移入 `archive/legacy/`**

---

## 11. 完成清理协议

略（与前版相同）。