# 🏛️ Multi-Agent Meeting 使用说明

> 一个轻量级、Unix 哲学的多 Agent 会议系统。PM Agent 自动调度专家 Agent 轮流发言，最终输出结构化会议报告。

---

## 目录

- [快速开始](#快速开始)
- [核心概念](#核心概念)
- [所有预置 Agent 一览](#所有预置-agent-一览)
- [开会指南：如何串联 Agent](#开会指南如何串联-agent)
- [预设场景](#预设场景)
- [深度讨论：背景输入](#深度讨论背景输入)
- [Human-in-the-Loop 交互模式](#human-in-the-loop-交互模式)
- [创建自定义 Agent](#创建自定义-agent)
- [高级配置](#高级配置)
- [常见问题](#常见问题)

---

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置 API Key

```bash
# 方式一：导出环境变量
export ANTHROPIC_API_KEY="sk-ant-..."

# 方式二：使用 .env 文件（推荐）
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
```

### 3. 开一场会

```bash
# 方式一：手动指定 Agent
python run_meeting.py \
  --topic "是否应该将单体架构重构为微服务" \
  --agents architect,business_analyst,devops

# 方式二：使用预设场景（推荐）
python run_meeting.py \
  --topic "是否应该将单体架构重构为微服务" \
  --scenario tech_design

# 方式三：让 PM 自动选人
python run_meeting.py \
  --topic "是否应该将单体架构重构为微服务" \
  --auto-select
```

会议结束后，报告和讨论记录自动保存到 `reports/` 目录：
```
reports/
  20260330-155618-是否应该将单体架构重构为微服务.md              # 最终报告
  20260330-155618-是否应该将单体架构重构为微服务.transcript.md   # 完整讨论记录
```

---

## 核心概念

### 会议是怎么运作的？

```
┌─────────────────────────────────────────────────────┐
│                    Meeting Loop                      │
│                                                     │
│  ┌──────────┐    "叫架构师来说说"    ┌───────────┐  │
│  │          │ ──────────────────────▶ │           │  │
│  │ PM Agent │                        │ Agent 池  │  │
│  │ (调度者)  │ ◀────────────────────── │ (专家们)   │  │
│  │          │    "架构师的观点..."    │           │  │
│  └──────────┘                        └───────────┘  │
│       │                                             │
│       │  所有对话写入 ▼                               │
│  ┌──────────────────┐                               │
│  │  共享白板          │                               │
│  │  (Scratchpad)     │                               │
│  │  - 架构师: ...     │                               │
│  │  - 商业分析: ...   │                               │
│  │  - DevOps: ...    │                               │
│  └──────────────────┘                               │
│       │                                             │
│       ▼  PM 决定结束                                  │
│  ┌──────────────────┐                               │
│  │  📄 会议报告       │                               │
│  │  (Markdown)       │                               │
│  └──────────────────┘                               │
└─────────────────────────────────────────────────────┘
```

1. **PM Agent（项目经理）** 阅读当前白板，决定下一步：叫谁发言？问什么问题？
2. **被叫到的 Agent** 看到白板摘要 + PM 的具体提问，给出专业回复
3. 回复写入共享白板，PM 再次审视全局
4. 重复直到 PM 认为讨论充分，输出 **最终报告**
5. 硬性上限：`max_rounds` 轮后强制结束（默认 10 轮）

### 关键设计

| 设计 | 说明 |
|------|------|
| **Agent 无状态** | 每个 Agent 只看到当前白板 + PM 的提问，没有私有记忆 |
| **PM 是唯一的路由器** | Agent 之间不直接对话，所有调度经过 PM |
| **JSON 驱动** | PM 的决策是结构化 JSON，不是自由文本，防止跑偏 |
| **防无限循环** | `max_rounds` 硬限制 + 最后一轮系统强制结束 |

---

## 所有预置 Agent 一览

系统自带 **27 个** Agent 配置，分为四个类别。

### 📦 项目原有 Agent（5 个）

基础角色，适合通用技术/商业讨论。

| 名称 | 角色 | 适用场景 |
|------|------|----------|
| `architect` | 资深软件架构师 | 系统设计、可扩展性、技术债务 |
| `business_analyst` | 商业分析师 | ROI 分析、市场可行性、成本收益 |
| `devops` | DevOps 工程师 | CI/CD、部署、监控、基础设施 |
| `steve_jobs` | 产品经理（乔布斯风格） | 产品简洁性、用户体验极致追求 |
| `example_architect` | 示例架构师 | 快速上手参考 |

### 🎭 gstack 角色 Agent（3 个）

来自 gstack 生态的「拷问者」角色，适合产品评审、方案论证。三个角色搭配使用可以从商业、技术、体验三个维度全面拷问方案。

| 名称 | 角色 | 核心能力 |
|------|------|----------|
| `gstack_commercial` | 💰 商业拷问者 | 付费验证、ROI 冷算、竞争护城河、定价权、退出成本 |
| `gstack_technical` | 🔩 技术悲观者 | 边界条件猎杀、依赖链审计、规模爆炸预警、运维地狱检测 |
| `gstack_ux` | 🎨 用户体验原教旨主义者 | 摩擦力扫描、认知负担测试、首次使用体验、错误恢复 |

### 🧠 gstack 名人认知模型（11 个）

以真实商业/技术/设计领袖的思维框架建模，适合战略讨论、方案论证、设计评审。

#### CEO / 战略视角（6 个）

| 名称 | 人物 | 认知模型 |
|------|------|----------|
| `gstack_bezos` | Jeff Bezos | 单向门 vs 双向门决策、Day 1 思维、客户痴迷、70% 信息就决策 |
| `gstack_grove` | Andy Grove | 偏执狂生存法则、10x force 扫描、战略转折点、穿越死亡之谷 |
| `gstack_munger` | Charlie Munger | 逆向思考(Inversion)、多元思维模型、能力圈、激励机制分析 |
| `gstack_horowitz` | Ben Horowitz | 和平/战争时期切换、没有好选择时做选择、文化即行动 |
| `gstack_altman` | Sam Altman | 杠杆执念、复合增长、偏向行动、技术拐点赌注 |
| `gstack_pg` | Paul Graham | Do Things That Don't Scale、创始人模式、拉面盈利 |

#### 工程视角（2 个）

| 名称 | 人物 | 认知模型 |
|------|------|----------|
| `gstack_brooks` | Fred Brooks | 本质 vs 偶然复杂度、没有银弹、概念完整性、人月神话 |
| `gstack_beck` | Kent Beck | 先让改变变简单再做简单的改变、TDD 循环、简单设计四原则 |

#### 设计视角（3 个）

| 名称 | 人物 | 认知模型 |
|------|------|----------|
| `gstack_rams` | Dieter Rams | Less but better、好设计十原则、诚实设计、持久性优先 |
| `gstack_norman` | Don Norman | 可供性(Affordance)、反馈与映射、错误设计、心智模型 |
| `gstack_ive` | Jonathan Ive | 关怀即品质、材料的诚实、不可避免感、消除设计的痕迹 |

### 🔧 ecc 技术审查 Agent（8 个）

来自 everything-claude-code 的技术专家，适合代码审查、架构评审、技术选型。

| 名称 | 角色 | 核心能力 |
|------|------|----------|
| `ecc_security_reviewer` | 安全审查专家 | OWASP Top 10、攻击面分析、STRIDE 威胁建模、供应链安全 |
| `ecc_performance_optimizer` | 性能优化专家 | 瓶颈识别、P50/P95/P99 指标、缓存策略、数据库性能 |
| `ecc_database_reviewer` | 数据库专家 | Schema 设计、查询优化、索引策略、迁移安全 |
| `ecc_python_reviewer` | Python 审查专家 | PEP 8、类型提示、Pythonic 惯用法、依赖管理 |
| `ecc_go_reviewer` | Go 审查专家 | 惯用 Go、并发模式、错误处理、接口设计 |
| `ecc_rust_reviewer` | Rust 审查专家 | 所有权与借用、生命周期、零成本抽象、unsafe 纪律 |
| `ecc_architect` | 系统架构师 | 架构权衡、可扩展性、系统边界、故障设计、演进式架构 |
| `ecc_tdd_guide` | TDD 专家 | Red-Green-Refactor、测试金字塔、FIRST 原则 |

---

## 开会指南：如何串联 Agent

### 基本命令

```bash
python run_meeting.py \
  --topic "你的议题" \
  --agents agent1,agent2,agent3 \
  [--context "背景信息"] \
  [--context-file path/to/brief.md] \
  [--max-rounds 10] \
  [--interactive] \
  [--agents-dir agents/] \
  [--output-dir reports/]
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--topic` | 会议议题（必填，除 `--list-scenarios`） | — |
| `--agents` | 参会 Agent 名称，逗号分隔 | — |
| `--scenario` | 使用预设场景（与 `--agents` 互斥） | — |
| `--auto-select` | PM 自动选择参会 Agent（与 `--agents` 互斥） | — |
| `--list-scenarios` | 列出所有预设场景并退出 | — |
| `--context` | 内联背景信息字符串 | `""` |
| `--context-file` | 从文件读取背景信息 | — |
| `--max-rounds` | 最大讨论轮数 | 10 |
| `--interactive` | 启用 Human-in-the-Loop 交互模式 | `false` |
| `--agents-dir` | Agent 配置文件目录 | `agents/` |
| `--output-dir` | 报告输出目录 | `reports/` |

> **注意**：`--agents`、`--scenario`、`--auto-select` 三者互斥，必须提供其一（除非使用 `--list-scenarios`）。

### 推荐组合方案

#### 🔥 产品方案评审（最经典的三角拷问）

```bash
python run_meeting.py \
  --topic "评估是否上线 AI 智能客服功能" \
  --agents gstack_commercial,gstack_technical,gstack_ux
```

商业拷问者追问 ROI，技术悲观者找隐患，UX 原教旨审体验。三个维度互相挑战。

#### 🏛️ 名人董事会（战略决策）

```bash
python run_meeting.py \
  --topic "公司是否应该 all-in AI 赛道" \
  --agents gstack_bezos,gstack_munger,gstack_grove,gstack_altman \
  --max-rounds 8
```

Bezos 追问客户价值，Munger 逆向找死法，Grove 扫描 10x force，Altman 找杠杆。

#### 🔍 技术架构评审

```bash
python run_meeting.py \
  --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" \
  --agents architect,ecc_database_reviewer,ecc_architect,ecc_performance_optimizer
```

#### 🛡️ 安全与性能审查

```bash
python run_meeting.py \
  --topic "审查支付系统 v2 的技术方案" \
  --agents ecc_security_reviewer,ecc_performance_optimizer,ecc_architect,devops
```

#### 🐍 Python 项目代码评审

```bash
python run_meeting.py \
  --topic "审查用户认证模块的代码设计" \
  --agents ecc_python_reviewer,ecc_tdd_guide,ecc_security_reviewer
```

#### 🎨 产品设计评审（设计大师组）

```bash
python run_meeting.py \
  --topic "评审新版首页的交互设计方案" \
  --agents gstack_rams,gstack_norman,gstack_ive,gstack_ux
```

Rams 做减法，Norman 审心智模型，Ive 追求不可避免感，UX 原教旨扫摩擦力。

#### 🚀 创业方向论证

```bash
python run_meeting.py \
  --topic "评估做 B2B SaaS 数据分析工具的可行性" \
  --agents gstack_pg,gstack_horowitz,gstack_commercial,business_analyst \
  --max-rounds 8
```

#### 🏗️ 全栈混合会议

```bash
python run_meeting.py \
  --topic "设计一个高并发实时消息系统" \
  --agents ecc_architect,ecc_security_reviewer,gstack_technical,gstack_brooks,ecc_performance_optimizer \
  --max-rounds 10
```

### 关于轮数的建议

| Agent 数量 | 建议 `max-rounds` | 说明 |
|:---:|:---:|------|
| 2-3 | 10（默认） | 每人至少发言一次 + PM 追问 + 总结 |
| 4-5 | 10-12 | 给 PM 足够空间做交叉提问 |
| 6+ | 12-15 | 确保关键 Agent 有机会回应彼此 |

---

## 预设场景

不想每次手动挑选 Agent？使用预设场景一键开会。

### 查看所有可用场景

```bash
python run_meeting.py --list-scenarios
```

### 内置场景一览

| 场景名 | 说明 | 参会 Agent | 建议轮数 |
|--------|------|-----------|:---:|
| `product_review` | 全面产品评审：商业 + 技术 + UX 三维拷问 | gstack_commercial, gstack_technical, gstack_ux | 10 |
| `startup_pitch` | 创业方向论证：多位大佬视角 | gstack_pg, gstack_bezos, gstack_munger, gstack_altman, gstack_horowitz | 12 |
| `tech_design` | 技术架构评审 | ecc_architect, ecc_security_reviewer, ecc_performance_optimizer, gstack_technical | 10 |
| `code_review_python` | Python 代码审查 | ecc_python_reviewer, ecc_security_reviewer, ecc_tdd_guide | 10 |
| `design_review` | 设计评审：大师组 | gstack_rams, gstack_norman, gstack_ive, gstack_ux | 10 |
| `strategic_decision` | 战略决策评估 | gstack_bezos, gstack_grove, gstack_munger, business_analyst | 10 |

### 使用场景

```bash
# 产品评审
python run_meeting.py \
  --topic "评估是否上线 AI 智能客服功能" \
  --scenario product_review

# 创业方向论证
python run_meeting.py \
  --topic "B2B SaaS 数据分析工具的可行性" \
  --scenario startup_pitch \
  --context "目标客户是中小企业，团队3人，有6个月runway"
```

### PM 自动选人

如果没有合适的预设场景，可以让 PM 根据议题自动从所有可用 Agent 中选择最合适的参会者：

```bash
python run_meeting.py \
  --topic "评估从 PostgreSQL 迁移到 MongoDB 的方案" \
  --auto-select
```

PM 会分析议题和背景，从 27 个可用 Agent 中选出最相关的 5 个。

---

## 深度讨论：背景输入

### 为什么需要背景？

没有背景的议题容易导致泛泛而谈。通过 `--context` 或 `--context-file` 提供背景信息，Agent 可以围绕具体情况展开讨论。

### 使用方式

```bash
# 方式一：内联背景
python run_meeting.py \
  --topic "是否应该重构认证系统" \
  --scenario tech_design \
  --context "当前系统使用 session-based auth，日活 10 万，计划明年支持 SSO 和 OAuth2"

# 方式二：从文件读取（适合长背景）
python run_meeting.py \
  --topic "Q2 产品路线图评审" \
  --scenario product_review \
  --context-file docs/q2-roadmap-brief.md

# 方式三：两者同时使用（会拼接）
python run_meeting.py \
  --topic "是否上线 AI 功能" \
  --agents gstack_commercial,gstack_technical,gstack_ux \
  --context "预算 50 万" \
  --context-file docs/ai-feature-spec.md
```

### 背景信息最佳实践

一份好的背景应该包含：
- **现状**：当前系统/产品/团队的状态
- **约束**：时间、预算、技术限制
- **目标**：希望通过这次讨论达成什么
- **数据**：相关指标、用户反馈、市场数据

---

## Human-in-the-Loop 交互模式

### 为什么需要交互？

自动模式下，PM 和 Agent 的讨论完全自主进行。但有时你希望：
- 在讨论中途补充新信息
- 引导讨论方向
- 对某个观点追加提问
- 分阶段审阅和补充

### 使用方式

```bash
python run_meeting.py \
  --topic "新产品定价策略" \
  --scenario product_review \
  --context "目标市场：中国中小企业" \
  --interactive
```

### 交互流程

```
1. PM + Agent 自动讨论 → 输出初版报告
2. 系统提示：💬 有补充内容吗？(直接回车结束)
3. 你输入反馈 → 追加到共享白板，PM 继续调度讨论
4. 新一轮讨论 → 输出更新版报告
5. 重复 2-4，直到你满意按回车结束
6. 保存最终报告 + 包含你反馈的完整讨论记录
```

### 交互示例

```
[PM] Meeting concluded.
========================================
# 产品定价策略报告
（初版报告内容...）
========================================

💬 有补充内容吗？(直接回车结束): 竞品 A 的定价是每月 99 元，我们需要考虑差异化定价

[HUMAN] 竞品 A 的定价是每月 99 元，我们需要考虑差异化定价

[SYSTEM] --- Round 1/10 ---
[PM] Analysis: 人类反馈提到了竞品定价...
[PM] Calling gstack_commercial: 针对竞品 A 的 99 元/月定价...
...
```

你的反馈会以 `[HUMAN]` 标签出现在白板上，PM 会将其视为高优先级的利益相关者反馈，调度相关 Agent 回应。

---

## 创建自定义 Agent

### 方式一：AI 生成（推荐入门）

用 `agent_builder.py` 从自然语言描述生成配置：

```bash
python agent_builder.py \
  --description "一位有20年经验的数据科学家，专注于机器学习模型的可解释性和公平性审查" \
  --name data_scientist \
  --output-dir agents/ \
  --format json
```

生成的文件会自动包含 `name`、`role` 和 `system_prompt` 字段。

### 方式二：手写 JSON（推荐精细控制）

在 `agents/` 目录下创建 JSON 文件：

```json
{
  "name": "cto",
  "role": "首席技术官",
  "system_prompt": "你是一位经验丰富的CTO……（详细人设描述）"
}
```

#### 配置字段说明

| 字段 | 必填 | 说明 |
|------|:---:|------|
| `name` | ✅ | Agent 唯一标识，需与文件名一致（不含 `.json`） |
| `role` | ✅ | 角色名称，会在会议中显示 |
| `system_prompt` | ✅ | 核心人设指令，定义 Agent 的专业能力和说话风格 |
| `input_schema` | ❌ | 输入格式描述（预留字段，当前未强制使用） |
| `output_schema` | ❌ | 输出格式描述（预留字段，当前未强制使用） |

支持 `.json`、`.yaml`、`.yml` 三种格式。

### 方式三：YAML 格式

```yaml
# agents/cto.yaml
name: cto
role: 首席技术官
system_prompt: |
  你是一位经验丰富的CTO，在技术战略和团队管理方面有深厚积累。
  你关注：技术路线图、团队建设、技术债务管理、创新与稳定的平衡。
  说话风格：全局视角，兼顾短期交付和长期技术健康。
```

### 写好 system_prompt 的技巧

一个优秀的 `system_prompt` 通常包含以下要素：

```
1. 身份定义    → 你是谁？什么背景？
2. 核心框架    → 你用什么方法论/思维模型分析问题？（3-5 条）
3. 说话风格    → 直接？温和？学术？尖锐？
4. 特征行为    → 你每次发言一定会做什么？（如「至少指出一个风险」）
5. 禁忌/偏好   → 你最讨厌什么观点？（如「我们之后再想盈利模式」）
```

**参考模板**（以 `gstack_technical.json` 为例）：

```
你是一位[身份]，绰号[昵称]。你的职责是[核心职责]。

你的核心审查框架：
1. **[框架名]**：[具体描述]
2. **[框架名]**：[具体描述]
3. ...

你的说话风格：[风格描述]。每次发言[特征行为]。
```

### 命名规范

| 前缀 | 含义 | 示例 |
|------|------|------|
| `gstack_` | 来自 gstack 生态 | `gstack_bezos.json` |
| `ecc_` | 来自 everything-claude-code | `ecc_security_reviewer.json` |
| 无前缀 | 项目原有 / 自定义 | `architect.json`, `cto.json` |

建议自定义 Agent 使用有意义的英文名，避免中文文件名。

### 验证新 Agent

创建后运行验证：

```bash
# 验证单个
python3 -c "
from src.config_loader import load_agent_config
from pathlib import Path
config = load_agent_config(Path('agents/your_agent.json'))
print(f'✅ {config.name} | {config.role}')
"

# 验证全部
python3 -c "
from src.config_loader import load_agents
from pathlib import Path
agents = [p.stem for p in Path('agents').glob('*.json')]
results = load_agents(agents, agents_dir=Path('agents'))
for name, c in sorted(results.items()):
    print(f'✅ {name:30s} | {c.role}')
print(f'\nTotal: {len(results)} agents')
"
```

---

## 高级配置

### 切换 LLM 提供商

```bash
# Anthropic（默认）
export LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export LLM_MODEL=claude-sonnet-4-20250514   # 可选，覆盖默认模型

# OpenAI
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-proj-...
export LLM_MODEL=gpt-4o                      # 可选

# OpenAI 兼容代理（如本地 Ollama、DeepSeek 等）
export LLM_PROVIDER=openai
export OPENAI_API_KEY=any-value
export OPENAI_BASE_URL=http://localhost:11434/v1
export LLM_MODEL=llama3
```

所有环境变量也可写入项目根目录的 `.env` 文件。

### 会议报告与讨论记录

每次会议自动生成两个文件：

```
reports/
├── 20260330-155618-评估从-postgresql-迁移到-mongodb-的方案.md              # 最终报告
├── 20260330-155618-评估从-postgresql-迁移到-mongodb-的方案.transcript.md   # 完整讨论记录
├── 20260330-162000-是否应该上线-ai-客服.md
├── 20260330-162000-是否应该上线-ai-客服.transcript.md
└── ...
```

| 文件 | 说明 |
|------|------|
| `{timestamp}-{slug}.md` | PM 的最终报告，结构化的结论和建议 |
| `{timestamp}-{slug}.transcript.md` | 完整讨论过程：每轮 PM 分析 + Agent 发言 + 人类反馈（如有） |

文件名格式：`{YYYYMMDD-HHMMSS}-{议题slug}`

### 运行测试

```bash
# 全部测试
python3 -m pytest tests/ -v

# 单个模块
python3 -m pytest tests/test_config_loader.py -v
python3 -m pytest tests/test_meeting.py -v
```

---

## 常见问题

### Q: PM Agent 是什么？我需要配置它吗？

PM Agent 是内置的调度者，**不需要**手动配置。它的行为由 `src/pm.py` 定义，会自动：
- 决定叫谁发言
- 为每个 Agent 定制提问
- 在讨论充分后生成最终报告

### Q: Agent 之间能直接对话吗？

不能。所有 Agent 只能看到共享白板（Scratchpad）上的内容。如果 Agent A 想回应 Agent B 的观点，需要 PM 明确引导。这是有意的设计——避免 Agent 之间无限循环对话。

### Q: 怎么让某个 Agent 多说几次？

增大 `--max-rounds`（默认 10 轮）。PM 会根据讨论进展自行判断是否需要叫某个 Agent 再次发言。新的 PM 提示词会鼓励深入追问和交叉质询。也可以使用 `--interactive` 模式，在中途手动引导方向。

### Q: 会议卡住了怎么办？

系统有三重保护：
1. PM 决策有 3 次 JSON 重试机制
2. `max_rounds` 到达后系统强制注入 FINISH 指令
3. 即使 PM 最终没有生成报告，也会返回一个 fallback 报告

### Q: 可以用中文议题吗？

完全可以。议题、Agent 的 system_prompt、会议报告都支持中文。大部分预置 Agent 的 system_prompt 就是中文的。

### Q: 一场会议消耗多少 Token？

粗略估算（以 3 个 Agent、10 轮为例）：
- 每轮 PM 调用：~2000-4000 tokens
- 每轮 Agent 调用：~1000-3000 tokens
- 总计：约 30000-70000 tokens

增加 Agent 数量或轮数会线性增加消耗。使用 `--interactive` 模式会因多轮讨论进一步增加消耗。

### Q: 讨论过程丢失了怎么办？

不会丢失！系统现在自动保存完整讨论记录到 `.transcript.md` 文件。每个 Agent 的每次发言、PM 的分析、以及你在交互模式下的反馈都会被完整记录。

### Q: 不知道该选哪些 Agent 怎么办？

三种方式：
1. **用预设场景**：`--scenario product_review` — 最简单，一键开会
2. **PM 自动选人**：`--auto-select` — PM 分析议题后自动挑选
3. **查看场景列表**：`--list-scenarios` — 看看有哪些现成方案