多agent协同执行

七阶段（含阶段0任务澄清）多角色工作坊；角色种类与人数均由任务决定。触发词："多角色研讨"、"需求工作坊"、"需求评审"、"圆桌"、"定方案再执行"。

# Multi-Agent Workshop

在**单会话**内由**主 Agent 担任导演**，按 **7 个阶段（含阶段 0）**推进；每阶段产物写入 `workshops/<session_id>/`，角色发言建议用 **subagent**（一次一个角色、只注入该角色立场），避免上下文混乱。

> **所有阶段跳转必须经 `orchestrator.py`（Plan B）**：门禁以代码强制，不依赖 Markdown 约定。导演每次推进阶段时执行 `orchestrator.py advance <sid>`；跳转前检查 `orchestrator.py gate <sid>`。

## 何时启用

用户要：**多人视角讨论同一需求、互评、输出可执行方案、确认后再执行**。

## 核心原则：角色由任务决定，不是固定班子

- **禁止**不经 **阶段 0** 就默认把「如何产出高质量 X」当成 **必须交完整成稿**（或相反）；须先锁定 **交付物类型**（方案/SOP、成稿、大纲+样例、混合等）。
- **禁止**不经阶段 2 就默认使用「运营 / 产品 / 技术」；三者仅是**通用软件需求**的**参考模板**，不是每题的答案。
- **阶段 2 必须先回答**：「要完成这个任务，最少需要哪几种**相互制约的专业视角**？」再列角色。
- **角色人数没有固定值**（不是必须 2 个、3 个或 5 个）：**完全由任务决定**——有几个**不可缺少且彼此能形成张力的视角**，就设几个角色；宁可少也不要凑数。多一个角色就多一轮 token 与协调成本。
- 下文的「2～5」「调用量级表」仅是**常见规模参考**，不是规范；**唯一标准**是阶段 2 的选角理由是否成立。
- 在 `state.md` 必须写清：**任务类型标签** + **为何选这些角色（及为何是这个人数量）**（各一行），便于复盘。

### 任务类型 → 角色组合（示例，可增删）

| 任务类型 | 常见角色视角（示例） | 说明 |
|----------|----------------------|------|
| 通用产品需求 / 功能评审 | 运营、产品、技术 | 参考 `references/sample-roles/` |
| 短视频 / 直播 / 投放素材 | 编导或内容、法务或合规、剪辑或制作 | 重传播与合规，未必需要「技术」 |
| 公关 / 舆情 / 对外声明 | 公关、法务、业务事实负责人 | 避免只有运营 |
| 数据 / 指标 / 实验 | 数据/分析、产品、工程 | 「运营」可换成增长但职责要写清 |
| 纯技术债 / 架构改造 | 技术、SRE/运维、产品（仅定范围） | 可不要运营 |
| 采购 / 商务 / 合同 | 商务、法务、财务或使用方 | 与产研三角无关 |
| 法律合规审查 | 法务、业务、执行对接人 | 不要假装「技术」能替代法务立场 |
| 市场研报 / 行业研究 | 市场情报、分析或产品视角、事实/合规把关 | 需可引用事实时优先安排**一次集中检索**；检索失败须在 `state` 与正文披露 |

**导演动作**：从上表**得到启发即可**，不要机械套用；若用户任务跨界，可**合并角色**（一人兼两视角但分两轮说）或**拆两次工作坊**。

## 目录与产物（相对 workspace 根）

| 产物 | 路径 |
|------|------|
| 工作坊根目录 | `workshops/<session_id>/` |
| 状态 + 阶段 + 摘要 | `workshops/<session_id>/state.md` |
| 完整发言（可选） | `workshops/<session_id>/transcript.md` |
| 可执行方案 | `workshops/<session_id>/plan.md` |
| **交付正文（推荐）** | `workshops/<session_id>/deliverables/*`（报告、脚本包、设计稿等） |

**`deliverables/`**：阶段 6 或同步写入的**对用户可见成果**默认放此目录，避免与 `state.md` 混写；路径写进 `plan.md` 执行清单或验收表。

**敏感信息**：`workshops/` 可能含未公开需求；对外 git 请忽略或脱敏，见 `workshops/README.md`。

**`session_id` 建议**：`YYYY-MM-DD_主题简写`。用户未命名时由导演生成。

在 `state.md` 的「当前阶段」中统一使用下列 **phase key**（便于检索）：

| 阶段 | phase key |
|------|-----------|
| 0 任务澄清 | `phase_0_intake` |
| 1 任务理解 | `phase_1_understanding` |
| 2 角色拆解 | `phase_2_roles` |
| 3 角色创建 | `phase_3_role_cards` |
| 4 任务讨论 | `phase_4_discussion` |
| 5 plan 起草 | `phase_5_plan` |
| 5 末尾待批 | `awaiting_approval`（`plan.md` 已落盘、**用户未确认**前） |
| 6 plan 执行 | `phase_6_execution` |

**说明**：`awaiting_approval` 仍属**阶段 5 的末尾**，不是第 7 阶段；用户确认后进入 `phase_6_execution`。

## 模板与骨架（复制起盘）

| 用途 | 路径 |
|------|------|
| `state.md` 结构 | `templates/state.example.md` |
| `transcript.md` 结构 | `templates/transcript.example.md` |
| 自建角色卡 | `references/role-card-skeleton.md` |
| 从 JD 构建角色卡 | `references/role-card-from-jd.md` |
| 阶段 1 导演迫问（可选） | `references/director-forcing-questions.md` |
| `plan.md`（全量） | `templates/plan-output.md` |
| `plan.md`（轻量） | `templates/plan-lite.md`（见下文「plan 模板选择」） |
| **Orchestrator（唯一阶段管理入口）** | `scripts/orchestrator.py`（阶段机 + 门禁 + SQLite；**硬性阻塞不满足前置条件的跳转**） |
| **阶段 6 执行脚本生成（可选）** | `workshops/scripts/generate_execution.py`（`--preset` 或 **`--from-plan`** 读 `plan.md` 的 `execution_*`）；说明见 `workshops/scripts/README.md` |
| JD→角色卡草稿生成 | `scripts/jd_to_role_card.py`（`--role <名> --industry <行业> [--task <任务>]`） |
| 各阶段检查清单（给人/LLM 看） | `scripts/phases/00-…06-*.md` |
| **关闭 subagent 并行**（改 `openclaw.json`） | `scripts/openclaw-subagents-parallel.sh`（`off` = `maxConcurrent`→1；需 `python3`；改前自动备份） |

### Orchestrator CLI（唯一阶段管理入口）

`scripts/orchestrator.py`：Python 3.8+，无第三方依赖，状态存 SQLite（`data/orchestrator.db`）。**所有阶段跳转必须经此工具，门禁以代码强制**。

| 子命令 | 说明 |
|--------|------|
| `orchestrator.py init <sid> [-d TYPE]` | 创建 session + workshops 目录（可选指定 deliverable_type） |
| `orchestrator.py status <sid>` | 当前状态 + 下一门禁是否通过 |
| `orchestrator.py advance <sid>` | 推进到下一阶段（**检查门禁**） |
| `orchestrator.py set-phase <sid> <phase> [--force]` | 跳转阶段（检查门禁；`--force` 可强行跳过） |
| `orchestrator.py gate <sid> [phase]` | 查看门禁状态 |
| `orchestrator.py set <sid> <field> <value>` | 设置字段（deliverable_type、raw_requirement、approved_at 等） |
| `orchestrator.py set-role <sid> <name> [-r ...] [-t ...] [--card-path ...]` | 添加/更新角色 |
| `orchestrator.py add-message <sid> --phase ... --role ...` | 记录讨论消息 |
| `orchestrator.py validate <sid>` | 全量校验 |
| `orchestrator.py history <sid>` | 阶段变更历史 |
| `orchestrator.py import <sid>` | 从现有 `workshops/<sid>/state.md` 导入 |
| `orchestrator.py sync <sid>` | DB 状态回写 `state.md`（phase key + Session 状态） |
| `orchestrator.py cleanup` | 清理 OpenClaw 残留 subagent |
| `orchestrator.py list` | 列出所有 session |

**门禁规则**（代码强制，非建议）：

| 目标阶段 | 前置条件 |
|----------|----------|
| → 阶段 1 | 阶段 0 填了 deliverable_type + success_criteria |
| → 阶段 2 | 阶段 1 填了 raw_requirement |
| → 阶段 3 | 阶段 2 填了 task_type_tag + role_rationale + ≥1 角色 |
| → 阶段 4 | 阶段 3 每个角色有 card_path 或 card_inline |
| → 阶段 5 | 阶段 4 有 ≥1 条讨论消息 |
| → awaiting | plan.md 存在或 plan_version 已设 |
| → 阶段 6 | 当前为 awaiting_approval 且 approved_at 已设 |

示例（完整起盘到推进流程）：

```bash
cd /path/to/workspace
SID="2026-03-22_my-topic"
ORC="python3 skills/multi-agent-workshop/scripts/orchestrator.py"

# 1. 起盘（创建 session + workshops 目录 + 模板文件）
$ORC init $SID -d methodology

# 2. 阶段 0：填交付物类型、成功标准
$ORC set $SID success_criteria "产出可复用的写作方法论 SOP"
$ORC advance $SID                    # → phase_1_understanding（门禁检查）

# 3. 阶段 1：填原始需求
$ORC set $SID raw_requirement "如何产出高质量 AI 观点文章"
$ORC advance $SID                    # → phase_2_roles

# 4. 阶段 2：填任务类型、选角理由、添加角色
$ORC set $SID task_type_tag "内容创作"
$ORC set $SID role_rationale "需要信息捕捉、观点提炼两种张力"
$ORC set-role $SID 趋势猎手 -r "扫描热点" -t "热点vs深度"
$ORC set-role $SID 观点锻造师 -r "提炼角度" -t "差异化vs可论证"
$ORC advance $SID                    # → phase_3_role_cards

# 5. 随时检查状态 / 门禁 / 历史
$ORC status $SID
$ORC gate $SID
$ORC history $SID
```

## 防走样（导演必读）

- 不标 `director_monologue` / 压缩就**禁止**单口吻写多角色全文。
- 省略 subagent 或迫问须在 `state.md` + `plan.md` 风险同时披露。
- 跳过迫问清单须写具体原因（**禁止**仅用「已内化」「略」）。

> 完整规则（独白/压缩叠加、何时不可压缩、迫问跳过格式）→ **`references/anti-drift.md`**

## 导演补充规则

> 以下为**低频参考**，完整内容 → **`references/director-supplementary.md`**

| 主题 | 要点 | 详见 |
|------|------|------|
| 用户确认 | plan 勾选、自然语言「确认执行」、或子集确认均可；模糊表述不算 | `director-supplementary.md` §用户确认 |
| 轮次成本 | 2 角色≈4 调用，3≈6；用户要快可压缩但须标注 | 同上 §轮次与成本 |
| 事实检索 | 阶段 4 前至多 1-2 次集中检索；失败须声明，禁止捏造 | 同上 §事实检索 |
| 会话续跑 | 同 SID 续写须先读 state/plan；默认新 SID | 同上 §会话续跑 |
| subagent 收口 | 每跳有结束说明或导演补录；session 结束写 state.md | `references/subagent-closure.md` |
| OpenClaw 集成 | 阶段 6 遵循 `AGENTS.md` 路由 + `TOOLS.md` | `director-supplementary.md` §OpenClaw |
| gstack 参考 | 只读克隆 `workspace/reference/gstack/` | `docs/gstack-learning-notes.md` |
| 辩论协议 | 提前收束、冲突处理、语言约定 | `references/debate-protocol.md` |

---

## 全局约束（全程有效）

- **阶段 0～5**：以分析、文档、讨论为主；**不**擅自执行对外发送、改生产、支付等离开本机的操作。
- **阶段 6**：仅当用户在对话中**明确确认** `plan.md`（或确认修改后的版本）后启动；高风险步骤先复述再执行。

---

## 阶段 0：任务澄清（phase_0_intake）

**目的**：在选角与多轮讨论前，锁定 **交付物类型** 与 **非目标**，避免典型走样：用户要「**可复用的写作方法论**」，系统却直接交付「**一篇完整文章**」（或相反）。

**何时必须做**：用户表述模糊（如「如何产出高质量文章」「帮我做好内容」）且未明确 **交付形态** 时；**默认新 session 从本阶段开始**（`state.md` 模板默认 `phase_0_intake`）。

**动作**：

- 在 `state.md`「阶段 0」勾选或填写 **期望交付物类型**（见 `templates/state.example.md`）：`methodology` / `artifact` / `outline_sample` / `review` / `mixed`（混合须写清边界与顺序）。
- 写 **非目标**（例：本 session **不**默认交付 3000 字成稿；或 **不**只给空洞框架而不给可执行步骤）。
- 写 **成功标准** + **用户原话摘要** + **导演对齐说明**（有歧义须追问，**禁止**单方面猜交付物）。
- 若用户改口改变交付物类型：回到本阶段更新 `state.md`，或进入阶段 5+ 时 **递增 `plan_version`** 并在风险中披露。

**完成条件**：阶段 0 字段齐全 → 执行 `orchestrator.py set <sid> deliverable_type <type>` + `set <sid> success_criteria "..."` → `orchestrator.py advance <sid>`（门禁检查 deliverable_type + success_criteria）。

---

## 阶段 1：任务理解（phase_1_understanding）

**目的**：在 **交付物类型已锁定** 的前提下，把「用户到底要什么细节」说清楚，避免后面角色空转。

**动作**：

- 从用户输入提取：**业务目标、用户/客户、时间约束、成功标准**；缺失则写**假设**并标「待用户确认」。**不得**在本阶段悄悄改阶段 0 的交付物类型；若需改则回到阶段 0 或走 plan 变更流程。
- **推荐**：按 `references/director-forcing-questions.md` **择问**（不必六问全问），把答案并入上文假设或「待澄清」；未使用清单时须满足 `references/anti-drift.md`「迫问清单跳过格式」。用户要求快进时可同步启用 **压缩模式**。
- 在 `state.md` 写入 **原始需求**（可含原文摘要 + 导演理解的一段话）。

**完成条件**：`state.md` 中「原始需求 + 约束与假设」齐全 → 执行 `orchestrator.py set <sid> raw_