back
loading skill details...
Implementation guide for RoundTable v3.0 - a universal multi-agent discussion engine with heterogeneous model routing, MMR intent parsing, and convergence co...
---
name: roundtable-v3
description: "Implementation guide for RoundTable v3.0 - a universal multi-agent discussion engine with heterogeneous model routing, MMR intent parsing, and convergence control."
---
# RoundTable v3.0 — Universal Multi-Agent Discussion Engine
## Overview
RoundTable simulates a real roundtable meeting: multiple AI Agents assume distinct expert personas and produce high-feasibility proposals through 5 rounds of progressive, structured discussion. Its core design goal is **to break single-Agent perspective blind spots** — one mind inevitably circles within its own cognitive frame; cross-validating ideas under pressure from multiple expert viewpoints is far more reliable than solitary reasoning.
> **概览**: RoundTable 模拟真实圆桌会议：多个 AI Agent 扮演不同专家角色，通过 5 轮渐进式讨论产出高可行性方案。核心目标是**打破单一 Agent 视角盲区**——一个大脑容易在自己的框架内打转；多视角交叉验证远比单一视角更可靠。
## Design Philosophy
### Why RoundTable
Single Agents have inherent limitations:
- **Narrow perspective** — No matter how deep one thinks, it cannot escape its own cognitive frame. A backend engineer will always reason like a backend engineer.
- **No adversarial check** — Without challenge, proposals become echo-chamber self-validation. The agent confirms its own assumptions and calls it "analysis."
- **Pseudo-depth** — Looks like thorough reasoning, but it is the same angle repeated with different wording. Real depth requires friction between opposing viewpoints.
RoundTable's structured adversarial design breaks this cycle through 5 mandatory rounds:
```
R1 Independent → R2 Cross-Reference → R3 Forced Critique → R4 Debate & Revise → R5 Arbitrate
```
After 5 rounds, the system surfaces **15+ risks, 9+ defects**, and produces a plan that has been thoroughly stress-tested against diverse expert scrutiny.
> **为什么需要 RoundTable**: 单一 Agent 存在天然局限——视角单一（无法跳出自身认知框架）、缺乏对抗检验（没有挑战的方案容易沦为回声室自证）、伪深度（看似全面实则同一角度反复展开）。RoundTable 通过结构化对抗设计打破这一循环：R1 独立提出 → R2 交叉引用 → R3 强制质疑 → R4 辩论修订 → R5 仲裁总结。5 轮后系统可暴露 15+ 风险、9+ 缺陷，产出经过充分压力测试的方案。
### Core Design Principles
1. **Real sub-Agent isolation** — Every utterance in every round is an independent `sessions_spawn`. Models and thought-chains are fully isolated; no shared context leaks between experts.
2. **Forced critique depth** — No vague hand-waving allowed. The critique round (R3) must produce exactly **5 risks + 3 defects**, each backed by concrete reasoning.
3. **Dynamic proposal evolution** — R4 is not a repeat of R1. Experts must show an explicit "Original → Revised + Reason" comparison table, proving their thinking evolved under challenge.
4. **Explicit disagreement arbitration** — The R5 Host cannot dodge conflicts. Every disputed point must receive a ruling with rationale, even when experts fundamentally disagree.
5. **Directly executable output** — Not "recommendations." The final deliverable is an 8-week task table with named owners, deliverables, and risk contingencies.
> **核心设计原则**:
> 1. **真实子 Agent 调用** — 每轮每句都是独立 `sessions_spawn`，模型与思维链完全隔离
> 2. **强制质疑深度** — 不允许模糊敷衍；硬性要求 5 风险 + 3 缺陷
> 3. **方案动态演进** — R4 必须展示「原版→修订+理由」对比表
> 4. **明确分歧仲裁** — R5 主持人不可回避冲突，须逐条裁决
> 5. **直接可执行输出** — 不是"建议"，而是带责任人和交付物的周任务表
---
## 5-Round Discussion Flow
```
R1 Independent → R2 Cross-Reference → R3 Deep Critique → R4 Debate & Revise → R5 Final Summary
↓ ↓ ↓ ↓ ↓
3 experts Reference each 5 risks + Respond to all Arbitrate
800-1200 words 800-1200 words 3 defects 质疑 (1000-1500w) 1500-2000 words
```
| Round | Theme | Core Task | Hard Requirements |
| --- | --- | --- | --- |
| **R1** | Independent Proposal | Each expert gives a plan from their perspective | At least 1 comparison table + 5 quantitative metrics |
| **R2** | Cross-Reference | Cite others' points + fill blind spots | At least 3 citation markers + explicit stance (agree/disagree) |
| **R3** | Deep Critique | Find flaws — risks and defects | **5 risks** + **3 defects**, each backed by data |
| **R4** | Debate & Revise | Respond to challenges + revise plan | Revision comparison table (original vs. revised + reason) |
| **R5** | Host Summary | Arbitrate disagreements + produce plan | **8-week task table** + risk contingency + Top 3 risks |
### Context Propagation Mechanism
The fatal flaw of v2.0 was that R2-R5 had no awareness of prior rounds — each round was essentially starting from scratch. v3.0 enforces full discussion history injection:
- **R2**: Injects all R1 expert statements (you need to read them to cite them)
- **R3**: Injects R1 + R2 history (critique must target real content)
- **R4**: Injects R1-R3 history (responses must address actual arguments)
- **R5 Host**: Injects R1-R4 full history (otherwise arbitration is impossible)
---
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ RoundTable Engine │
├─────────────────────────────────────────────────────────┤
│ Intent Parser │ Model Router │ Convergence │
│ (MMR Intent) │ (Heterogeneous) │ (Loop Guard) │
├────────────────────┼──────────────────┼──────────────────┤
│ Agent Selector │ Prompt Builder │ Notifier │
│ (170+ Experts) │ (Templates) │ (Feishu/Lark) │
└─────────────────────────────────────────────────────────┘
```
### 1. Intent Parser — MMR Algorithm for Expert Selection
Not simple keyword matching — uses **Maximal Marginal Relevance (MMR)**:
```
score = λ × relevance − (1−λ) × max_similarity_to_selected
```
- λ controls diversity (default 0.7, biased toward covering different perspectives)
- Prevents "echo chambers" — 3 experts cannot all be from the same domain
- 170+ expert library covers: Engineering, Design, Product, Security, Performance, Growth, DevOps, Data…
### 2. Model Router — Heterogeneous Model Assignment
Different expert roles get different models, leveraging each model's strengths:
| Expert Role | Capability Need | Recommended Model Tags |
| --- | --- | --- |
| Engineering / Architecture | Code, logic | `code`, `technical`, `engineering` |
| Design / Creative | Long context, creativity | `creative`, `long-context`, `design` |
| QA / Testing | Balanced, fast | `balanced`, `fast`, `general` |
| Product / Business | Chinese, domain knowledge | `chinese`, `knowledge`, `product` |
| Host Summary | Logic, decision-making | `logic`, `summary`, `decision`, `max` |
**Three-tier routing strategy:**
1. **User explicit config** (highest priority): Custom `local_models.json`
2. **OpenClaw official API** (recommended): Auto-discover available models
3. **Single-model fallback** (safety net): One model plays all roles
ClawHub compliant: no `os.environ` scanning, no `apiKey`/`baseUrl` access. All model info comes from public config files only.
### 3. Convergence Engine — Anti-Infinite-Loop
```
R1 → R2 → R3 → R4 → R5
↑
Semantic divergence < threshold → early stop
max_rounds reached → FORCE_ARBITRATE
```
- **Semantic similarity detection**: 2 consecutive rounds with >80% content overlap → auto-stop
- **Consensus detection**: 3+ consensus points confirmed after R4 → accelerate to R5
- **Hard cap**: Max 5 rounds, prevents token explosion
### 4. Agent Selector — 170+ Expert Library
Domain coverage:
- **Technical**: Backend / Frontend / Full-stack / Architecture / DevOps / Security / DBA / Algorithm / Data Engineering
- **Product**: Product Manager / Growth / Data Analysis / UX / Customer Success
- **Business**: Marketing Strategy / Branding / Sales / PR / Business Analysis
- **Design**: Interaction / Visual / Service Design / Design System
- **Management**: Project Manager / Tech Lead / Agile Coach
Selection strategy: MMR algorithm + domain weighting + user force-override
### 5. Prompt Builder — Structured Templates
Each round has a dedicated Prompt framework (`prompts/framework.md`), not free-form:
- **Hard constraints**: Word count minimums, table requirements, citation counts
- **Role-specific content**: Different expert roles get industry-specific templates
- **History injection**: Full prior-round content appended to Prompt
---
## Execution Engine
### Core Flow
```python
engine = RoundTableEngine(
topic="Smart Customer Service Technical Proposal",
agents=["Engineering Expert", "Product Expert", "Architecture Expert"],
mode="pre-ac" # pre-ac: local pre-analysis | full: complete mode
)
success = await engine.run()
```
### Fault Tolerance
| Scenario | Strategy |
| --- | --- |
| Sub-Agent timeout | Max 2 retries, 5s interval |
| `sessions_spawn` unavailable | Hard fail (no mock fallback) |
| R5 Host failure | Auto-extract summary from existing rounds |
| Model unavailable | Auto-fallback to `FALLBACK_MODEL` |
### Output
1. **JSON report** (`data/roundtable/{topic}.json`): Structured data, machine-readable
2. **Markdown report**: Human-readable, includes all 5 rounds
3. **Feishu/Lark notification** (optional): Real-time progress push per round
4. **Chat room mode** (optional): Broadcast discussion to a designated session
---
## v3.0 vs v2.0
| Dimension | v2.0 | v3.0 |
| --- | --- | --- |
| **Context Propagation** | R2-R5 have no prior context ❌ | **Forced full history injection** ✅ |
| **Critique Depth** | Vague (~3 risks) | **Hard 5 risks + 3 defects** |
| **Proposal Evolution** | R1-R4 content repeats | **R4 revision comparison table** |
| **Disagreement Handling** | No arbitration | **R5 Host rules on each point** |
| **Output Quality** | 400-600 words, no tables | **800-2000 words + mandatory tables** |
| **Actionability** | ~50% | **90%+** |
### Benchmark Data (Tested 2026-03-19)
```
Topic: Smart Customer Service Technical Proposal
Participating Experts: Engineering / Product / Design (3)
Sub-Agent Calls: 15
Risks Identified: 15
Defects Found: 9
Modification Suggestions: 13
8-Week Plan: W1-W8, daily effort estimates
Disagreement Rulings: 4 items + rationale
Total Output: ~8,500 words
```
---
## Use Cases
| ✅ Recommended | ❌ Not Recommended |
| --- | --- |
| Technical proposal review (architecture, tech selection) | Simple Q&A (ask your main Agent directly) |
| Product kickoff (feature planning, MVP scoping) | Urgent decisions (needs 15-20 min runtime) |
| Complex decisions (multi-factor tradeoffs) | Code generation (use Auto-Coding instead) |
| Cross-team alignment (aligning multiple perspectives) | Quick fact lookups |
---
## Usage Strategy
### Local Development
Use `local_models.json` to define your custom model lineup:
```json
{
"engineering": "deepseek/deepseek-v4-flash",
"design": "minimax/minimax-latest",
"host": "deepseek/deepseek-v4-pro"
}
```
### ClawHub Public Mode
Use `roundtable_config.yaml` to declare model capability tags. Read model metadata from config files only, without accessing API keys or sensitive fields.
---
## File Paths
- `core/model_router.py`
- `core/intent_parser.py`
- `core/prompt_builder.py`
- `core/convergence.py`
- `prompts/framework.md`
---
## 🔒 Data Handling Transparency
This skill processes the following data during execution:
| Behavior | Description | User Control |
| --- | --- | --- |
| **Model Config Reading** | Reads model IDs, tags, priorities for heterogeneous routing | ✅ Override via parameters |
| **Discussion History Injection** | R2-R5 injects prior round summaries (truncated to ~200 chars per round) into agent context | ✅ Truncation limits exposure; users control topic selection |
| **Report Persistence** | Saves discussion results as JSON + Markdown files | ✅ Configurable output directory |
| **Chat Room Broadcasting** | Optional: broadcasts truncated agent outputs (≤1000 chars) to a separate session | ✅ Default off (`enable_chat_room=False`); intermediate outputs visible to session observers |
> ⚠️ **Privacy note**: If discussions contain sensitive information, be aware that report files, chat room sessions, and round progress notifications may expose topic names, agent roles, and partial discussion content to channel observers. Disable chat room and notification channels when handling confidential topics.
**Version**: 3.0.9
**Last Updated**: 2026-05-26
don't have the plugin yet? install it then click "run inline in claude" again.