claude-code-debate

AI 驱动的多智能体结构化辩论 CLI 工具

三个 Claude Agent 在终端里唇枪舌战，裁判实时亮分，最终裁决一锤定音。

What is this?

claude-code-debate 编排三个独立的 AI Agent 围绕一个主题进行正反方对抗式辩论：

        ┌──────────┐
        │  你的主题  │
        └────┬─────┘
             │
    ┌────────▼────────┐
    │   Round 1 .. N   │
    │                  │
    │  🟢 正方 → 陈词  │
    │  🔴 反方 → 反驳  │
    │  ⚖️  裁判 → 评分  │
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │    最终裁决       │
    │  胜者 · 总结 ·    │
    │  关键时刻         │
    └─────────────────┘

每轮辩论严格按照 正方陈词 → 反方反驳 → 裁判评分 的流程推进，辩手能感知历史轮次上下文，逐轮深化观点。所有输出均为中文。

Features

• 三角色多智能体架构 — 正方、反方、裁判各自拥有独立的 System Prompt 和行为约束
• 四维评分体系 — 逻辑性 / 证据 / 说服力 / 反驳质量，每项 0-10 分
• 实时流式输出 — 辩手发言逐字流式渲染到终端，配合彩色高亮和 Spinner 动画
• Markdown 报告导出 — 生成包含完整论点、评分表格和统计数据的结构化报告
• 事件驱动 API — 通过 AsyncGenerator<DebateEvent> 暴露 9 种事件类型，可作为库集成
• 费用追踪 — 精确统计每个 Agent、每轮、整场辩论的 API 费用（USD）
• 健壮的 JSON 解析 — 三层容错（原始解析 → 控制字符修复 → 正则回退），从容处理模型输出
• Ctrl+C 优雅退出 — SIGINT 信号处理，不留悬挂进程

Quick Start

前置条件

• Node.js >= 18
• pnpm

安装 & 运行

# 克隆仓库
git clone https://github.com/zwkang/claude-code-debate.git
cd claude-code-debate

# 安装依赖
pnpm install

# 设置 API Key（二选一）
export ANTHROPIC_API_KEY="sk-ant-..."
# 或在项目根目录创建 .env 文件:
# ANTHROPIC_API_KEY=sk-ant-...

# 直接运行
pnpm start "人工智能是否会取代人类程序员"

# 或构建后以 CLI 运行
pnpm build
claude-code-debate "开源软件是否比闭源软件更安全"

Usage

claude-code-debate <topic> [options]

Arguments:
  topic                    辩论主题（必填）

Options:
  -r, --rounds <n>         辩论轮数（默认: 3）
  -o, --output <path>      输出 Markdown 报告到指定文件
  -m, --model <model>      Claude 模型标识（默认: sonnet）
  --base-url <url>         自定义 API Base URL
  -v, --verbose            启用详细日志
  -h, --help               显示帮助
  --version                显示版本号

示例

# 5 轮辩论 + 导出报告
claude-code-debate "996工作制是否应该被禁止" -r 5 -o report.md

# 使用 Opus 模型
claude-code-debate "人类是否应该殖民火星" -m opus

# 自定义 API 地址
claude-code-debate "加密货币是否有长期价值" --base-url https://your-proxy.com/v1

Architecture

src/
├── cli.ts              # CLI 入口：参数解析、环境校验、流程串联
├── debate.ts           # 辩论编排引擎：轮次调度、重试、事件流
├── types.ts            # 全量 TypeScript 类型定义
├── index.ts            # 公共 API 导出
├── agents/
│   ├── pro.ts          # 正方 Agent 配置
│   ├── con.ts          # 反方 Agent 配置
│   ├── judge.ts        # 裁判 Agent 配置
│   └── prompts.ts      # Prompt 模板 & JSON 解析器
├── output/
│   ├── terminal.ts     # 终端彩色渲染（chalk + ora）
│   └── markdown.ts     # Markdown 报告生成
└── utils/
    ├── errors.ts       # 自定义错误类层级
    ├── env.ts          # .env 文件加载器
    └── stream.ts       # 流消费工具

事件流模型

辩论引擎以 AsyncGenerator 产出一系列有类型的事件，消费端可自由选择渲染方式：

| 事件类型 | 触发时机 | 关键字段 | |:---------|:---------|:---------| | debate_start | 辩论开始 | config | | round_start | 每轮开始 | round, totalRounds | | agent_start | Agent 开始思考 | role, round | | agent_text | Agent 流式文本块 | role, text | | agent_end | Agent 完成发言 | role, costUsd, durationMs | | round_end | 每轮结束 | debateRound (含评分) | | verdict | 最终裁决产出 | verdict, costUsd | | debate_end | 辩论结束 | result (全量数据) | | error | 出错 | message, role?, round? |

作为库使用

import { runDebate } from 'claude-code-debate'

const events = runDebate({
  topic: '远程办公是否提高了生产力',
  rounds: 3,
  model: 'sonnet',
  verbose: false,
})

for await (const event of events) {
  if (event.type === 'agent_text') {
    process.stdout.write(event.text)
  }
  if (event.type === 'debate_end') {
    console.log('Winner:', event.result.verdict.winner)
  }
}

Scoring System

裁判从四个维度对每位辩手独立评分：

| 维度 | 评估内容 | 分值 | |:-----|:---------|:-----| | 逻辑性 (Logic) | 推理链条的连贯性与严密性 | 0 - 10 | | 证据 (Evidence) | 引用实例和数据的质量与相关性 | 0 - 10 | | 说服力 (Persuasion) | 整体论证力度和修辞技巧 | 0 - 10 | | 反驳质量 (Rebuttal) | 回应对方论点的针对性和有效程度 | 0 - 10 |

每轮总分 = 四个维度的平均值（保留一位小数）。最终裁决基于所有轮次的累计得分，并附带综合总结、双方核心优势与关键时刻分析。

Tech Stack

| 类别 | 工具 | |:-----|:-----| | 语言 | TypeScript 5.8 (ES2022, strict) | | 运行时 | Node.js | | AI SDK | @anthropic-ai/claude-agent-sdk | | CLI 解析 | cac | | 终端样式 | chalk + ora | | 构建 | tsdown (ESM + CJS 双格式) | | 测试 | vitest | | 代码规范 | eslint + @antfu/eslint-config | | 包管理 | pnpm |

Development

# 监听模式开发
pnpm dev

# 运行测试
pnpm test

# 类型检查
pnpm typecheck

# 代码规范检查 & 自动修复
pnpm lint
pnpm lint:fix

# 构建
pnpm build

Built by AI

本项目从架构设计、代码实现、测试用例到文档撰写，100% 由 AI 完成。

人类仅提供需求意图与最终审阅，所有源代码、Prompt 工程、CI/CD 配置和本 README 均由 Claude Code 生成。

这本身就是多智能体协作能力的一次自证 — 一个由 AI 构建的工具，用于让 AI 互相辩论。

License

MIT License © 2022 zwkang