ai-battle 0.1.8 → 0.2.0

package/README.md

@@ -1,11 +1,11 @@
 <h1 align="center">⚔️ ai-battle</h1>
 
 <p align="center">
-  <strong>让多个 AI Agent 对同一问题进行结构化圆桌讨论</strong>
+  <strong>Structured roundtable discussions among multiple AI Agents</strong>
 </p>
 
 <p align="center">
-  自动管理轮次 · 检测共识 · 保存全部记录
+  Auto-managed rounds · Consensus detection · Full session recording
 </p>
 
 <p align="center">
@@ -15,54 +15,58 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="MIT License" /></a>
 </p>
 
+<p align="center">
+  <a href="#-中文文档">📖 中文文档</a>
+</p>
+
 ---
 
 ## ✨ Features
 
 | Feature | Description |
 | :--- | :--- |
-| 🤖 **多 Agent 圆桌** | 支持 Claude / Codex / Gemini 自由组合 |
-| 🔁 **同类自辩** | 同一 Agent 可参加多席位（如 `gemini,gemini`） |
-| 🔨 **裁判模式** | 独立裁判每轮总结差异、自动检测共识、生成最终报告 |
-| 👁️ **上帝视角** | 每轮结束后人工注入补充信息引导讨论方向 |
-| 💾 **Session 录制** | 保存 Agent CLI 原始输出（stream-json / json / raw） |
-| 🔄 **断点续讨** | 中断后自动恢复到上次轮次继续讨论 |
-| 🔌 **可扩展** | 实现 3 个函数 + 注册即可接入新 Agent |
+| 🤖 **Multi-Agent Roundtable** | Mix and match Claude / Codex / Gemini freely |
+| 🔁 **Self-Debate** | Same agent can take multiple seats (e.g. `gemini,gemini`) |
+| 🔨 **Referee Mode** | Independent referee summarizes each round, detects consensus, generates final report |
+| 👁️ **God Mode** | Inject supplementary instructions after each round to steer the discussion |
+| 💾 **Session Recording** | Saves raw Agent CLI output (stream-json / json / raw) |
+| 🔄 **Resume Support** | Automatically resumes from the last round after interruption |
+| 🔌 **Extensible** | Implement 3 functions + register to add a new agent |
 
 ## 🚀 Quick Start
 
 ```bash
-# 创建讨论目录
+# Create a discussion directory
 mkdir my-topic && cd my-topic
 
-# 写入问题
-echo "微服务 vs 单体架构的优缺点？" > problem.md
+# Define the topic
+echo "Microservices vs Monolith: pros and cons?" > problem.md
 
-# 启动讨论（自动拉取最新版）
+# Start the discussion (auto-fetches latest version)
 npx ai-battle --agents claude,gemini --rounds 8
 ```
 
 ## 📦 Installation
 
-**推荐：无需安装，直接使用 npx**
+**Recommended: No install needed, use npx directly**
 
 ```bash
 npx ai-battle --agents claude,gemini --rounds 5
 ```
 
-> npx 每次执行自动拉取最新版本，无需手动更新。
+> npx fetches the latest version automatically — no manual updates required.
 
-**全局安装：**
+**Global install:**
 
 ```bash
 npm install -g ai-battle
 ```
 
-### 前置依赖
+### Prerequisites
 
 - `bash` 4+
 - [`jq`](https://jqlang.github.io/jq/)
-- Agent CLI 工具（至少安装 2 个）：`claude` / `codex` / `gemini`
+- At least 2 Agent CLI tools: `claude` / `codex` / `gemini`
 
 ## 📖 Usage
 
@@ -71,29 +75,29 @@ ai-battle [options]
 ai-battle help
 ```
 
-| 参数 | 说明 | 默认值 |
+| Option | Description | Default |
 | :--- | :--- | :--- |
-| `--agents, -a <a1,a2>` | 选择参与的 Agent，支持同类 | `claude,codex` |
-| `--rounds, -r <N>` | 最大讨论轮次 | `10` |
-| `--god, -g` | 开启上帝视角（每轮可注入补充信息） | — |
-| `--referee [agent]` | 开启裁判模式（每轮总结 + 生成 SUMMARY.md） | — |
+| `--agents, -a <a1,a2>` | Select participating agents (supports same-type) | `claude,codex` |
+| `--rounds, -r <N>` | Max discussion rounds | `10` |
+| `--god, -g` | Enable god mode (inject info after each round) | — |
+| `--referee [agent]` | Enable referee mode (per-round summary + SUMMARY.md) | — |
 
 ### 💡 Examples
 
 ```bash
-# 同类 Agent 自我辩论
+# Same-type agent self-debate
 ai-battle --agents gemini,gemini
 
-# 三方圆桌讨论
+# Three-way roundtable
 ai-battle --agents claude,codex,gemini --rounds 5
 
-# 裁判模式
+# Referee mode
 ai-battle --agents claude,codex,gemini --referee --rounds 5
 
-# 指定 claude 做裁判
+# Specify claude as referee
 ai-battle --agents codex,gemini --referee claude --rounds 5
 
-# 上帝视角 + 裁判
+# God mode + Referee
 ai-battle --agents claude,codex --referee --god
 ```
 
@@ -110,52 +114,52 @@ sequenceDiagram
     U->>S: ai-battle --agents A,B --referee
 
     rect rgb(40, 40, 60)
-        Note over S: 阶段 1: 初始化
-        S->>S: 加载 .env / 检查 problem.md
-        S->>A: check_A() 可用性检查
-        S->>B: check_B() 可用性检查
+        Note over S: Phase 1: Initialize
+        S->>S: Load .env / Check problem.md
+        S->>A: check_A() availability
+        S->>B: check_B() availability
     end
 
     rect rgb(30, 50, 40)
-        Note over S: Round 1: 并发独立思考
+        Note over S: Round 1: Concurrent independent thinking
         par
             S->>A: call_A(problem)
-            A-->>S: 回复 A
+            A-->>S: Response A
         and
             S->>B: call_B(problem)
-            B-->>S: 回复 B
+            B-->>S: Response B
         end
     end
 
     rect rgb(40, 40, 60)
-        Note over S: Round 2+: 顺序交互
-        loop 每个 Agent 依次发言
-            S->>A: call_A(B 的上轮回复)
-            A-->>S: 回复 A
-            S->>B: call_B(A 的最新回复)
-            B-->>S: 回复 B
+        Note over S: Round 2+: Sequential interaction
+        loop Each agent takes turn
+            S->>A: call_A(B's last response)
+            A-->>S: Response A
+            S->>B: call_B(A's latest response)
+            B-->>S: Response B
         end
 
-        opt --referee 模式
-            S->>R: call_referee(所有回复)
-            R-->>S: 裁判总结 / CONSENSUS 判定
+        opt --referee mode
+            S->>R: call_referee(all responses)
+            R-->>S: Summary / CONSENSUS verdict
         end
 
-        opt --god 模式
-            S->>U: 请输入补充信息
-            U-->>S: 上帝视角注入
+        opt --god mode
+            S->>U: Enter supplementary info
+            U-->>S: God mode injection
         end
     end
 
-    alt 达成共识
-        S->>S: 保存 consensus.md
-        opt 裁判模式
+    alt Consensus reached
+        S->>S: Save consensus.md
+        opt Referee mode
             S->>R: generate_final_summary()
             R-->>S: SUMMARY.md
         end
-        S->>U: 🎉 达成共识！
-    else 未达成
-        S->>U: 是否追加轮次？
+        S->>U: 🎉 Consensus reached!
+    else No consensus
+        S->>U: Add more rounds?
     end
 ```
 
@@ -171,31 +175,34 @@ sequenceDiagram
 
 ```text
 my-topic/
-├── problem.md              # 讨论问题（用户创建）
-├── referee.md              # 裁判自定义提示词（可选）
-├── rounds/                 # 讨论轮次记录
-│   ├── round_1_claude.md
-│   ├── round_1_gemini.md
-│   ├── referee_round_2.md  # 裁判总结（--referee）
-│   └── god_round_1.md      # 上帝注入（--god）
-├── .sessions/              # Agent CLI 原始输出
-├── consensus.md            # 共识结论（如达成）
-├── SUMMARY.md              # 最终总结（裁判自动生成）
-├── .debate.json            # 状态配置
-└── .debate.log             # 运行日志（tail -f 实时查看）
+├── problem.md                    # Discussion topic (user-created)
+├── referee.md                    # Custom referee prompt (optional)
+├── SUMMARY.md                    # Final summary (generated by referee)
+├── .env                          # Environment variables (auto-loaded)
+└── .ai-battle/                   # All runtime artifacts
+    ├── rounds/                   # Per-round discussion records
+    │   ├── round_1_claude.md
+    │   ├── round_1_gemini.md
+    │   ├── referee_round_2.md    # Referee summary (--referee)
+    │   └── god_round_1.md        # God mode injection (--god)
+    ├── sessions/                 # Raw Agent CLI output
+    ├── agents/                   # Agent instruction files
+    ├── consensus.md              # Consensus conclusion (if reached)
+    ├── config.json               # Session config
+    └── battle.log                # Full log (tail -f to watch live)
 ```
 
 ## 🔌 Extend Agent
 
-只需实现 3 个函数并注册：
+Implement 3 functions and register:
 
 ```bash
-# 1. 实现函数
-check_myagent()          { ... }  # 可用性检查，返回 0/1
-call_myagent()           { ... }  # 调用 Agent: $1=system_prompt $2=user_msg $3=session_tag
-generate_myagent_md()    { ... }  # 生成指令文件: $1=max_rounds $2=problem
+# 1. Implement functions
+check_myagent()          { ... }  # Availability check, return 0/1
+call_myagent()           { ... }  # Call agent: $1=system_prompt $2=user_msg $3=session_tag
+generate_myagent_md()    { ... }  # Generate instruction file: $1=max_rounds $2=problem
 
-# 2. 注册
+# 2. Register
 register_agent "myagent"
 ```
 
@@ -206,10 +213,10 @@ register_agent "myagent"
 
 | Variable | Description |
 | :--- | :--- |
-| `ANTHROPIC_BASE_URL` | API 地址 |
-| `ANTHROPIC_AUTH_TOKEN` | 认证 Token |
-| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 模型名称 |
-| `API_TIMEOUT_MS` | 超时时间（毫秒） |
+| `ANTHROPIC_BASE_URL` | API endpoint |
+| `ANTHROPIC_AUTH_TOKEN` | Auth token |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model name |
+| `API_TIMEOUT_MS` | Timeout (ms) |
 
 </details>
 
@@ -218,7 +225,7 @@ register_agent "myagent"
 
 | Variable | Description | Default |
 | :--- | :--- | :--- |
-| `CODEX_MODEL` | Codex 模型 | `gpt-5.3-codex` |
+| `CODEX_MODEL` | Model name | `gpt-5.3-codex` |
 
 </details>
 
@@ -227,14 +234,152 @@ register_agent "myagent"
 
 | Variable | Description |
 | :--- | :--- |
-| `GEMINI_API_KEY` | API Key（如需自定义） |
+| `GEMINI_API_KEY` | API key |
 
 </details>
 
 ## 🤝 Contributing
 
-欢迎提交 [Issue](https://github.com/Alfonsxh/ai-battle/issues) 和 [Pull Request](https://github.com/Alfonsxh/ai-battle/pulls)！
+[Issues](https://github.com/Alfonsxh/ai-battle/issues) and [Pull Requests](https://github.com/Alfonsxh/ai-battle/pulls) are welcome!
 
 ## 📄 License
 
 [MIT](LICENSE) © [Alfons](https://github.com/Alfonsxh)
+
+---
+
+# 📖 中文文档
+
+## ✨ 特性
+
+| 特性 | 说明 |
+| :--- | :--- |
+| 🤖 **多 Agent 圆桌** | 支持 Claude / Codex / Gemini 自由组合 |
+| 🔁 **同类自辩** | 同一 Agent 可参加多席位（如 `gemini,gemini`） |
+| 🔨 **裁判模式** | 独立裁判每轮总结差异、自动检测共识、生成最终报告 |
+| 👁️ **上帝视角** | 每轮结束后人工注入补充信息引导讨论方向 |
+| 💾 **Session 录制** | 保存 Agent CLI 原始输出（stream-json / json / raw） |
+| 🔄 **断点续讨** | 中断后自动恢复到上次轮次继续讨论 |
+| 🔌 **可扩展** | 实现 3 个函数 + 注册即可接入新 Agent |
+
+## 🚀 快速开始
+
+```bash
+# 创建讨论目录
+mkdir my-topic && cd my-topic
+
+# 写入问题
+echo "微服务 vs 单体架构的优缺点？" > problem.md
+
+# 启动讨论（自动拉取最新版）
+npx ai-battle --agents claude,gemini --rounds 8
+```
+
+## 📦 安装
+
+**推荐：无需安装，直接使用 npx**
+
+```bash
+npx ai-battle --agents claude,gemini --rounds 5
+```
+
+> npx 每次执行自动拉取最新版本，无需手动更新。
+
+**全局安装：**
+
+```bash
+npm install -g ai-battle
+```
+
+### 前置依赖
+
+- `bash` 4+
+- [`jq`](https://jqlang.github.io/jq/)
+- Agent CLI 工具（至少安装 2 个）：`claude` / `codex` / `gemini`
+
+## 📖 用法
+
+```
+ai-battle [options]
+ai-battle help
+```
+
+| 参数 | 说明 | 默认值 |
+| :--- | :--- | :--- |
+| `--agents, -a <a1,a2>` | 选择参与的 Agent，支持同类 | `claude,codex` |
+| `--rounds, -r <N>` | 最大讨论轮次 | `10` |
+| `--god, -g` | 开启上帝视角（每轮可注入补充信息） | — |
+| `--referee [agent]` | 开启裁判模式（每轮总结 + 生成 SUMMARY.md） | — |
+
+### 💡 示例
+
+```bash
+# 同类 Agent 自我辩论
+ai-battle --agents gemini,gemini
+
+# 三方圆桌讨论
+ai-battle --agents claude,codex,gemini --rounds 5
+
+# 裁判模式
+ai-battle --agents claude,codex,gemini --referee --rounds 5
+
+# 指定 claude 做裁判
+ai-battle --agents codex,gemini --referee claude --rounds 5
+
+# 上帝视角 + 裁判
+ai-battle --agents claude,codex --referee --god
+```
+
+## 📁 产出结构
+
+```text
+my-topic/
+├── problem.md                    # 讨论问题（用户创建）
+├── referee.md                    # 裁判自定义提示词（可选）
+├── SUMMARY.md                    # 最终总结（裁判自动生成）
+├── .env                          # 环境变量（启动时自动加载）
+└── .ai-battle/                   # 所有运行时产物
+    ├── rounds/                   # 讨论轮次记录
+    │   ├── round_1_claude.md
+    │   ├── round_1_gemini.md
+    │   ├── referee_round_2.md    # 裁判总结（--referee）
+    │   └── god_round_1.md        # 上帝注入（--god）
+    ├── sessions/                 # Agent CLI 原始输出
+    ├── agents/                   # Agent 指令文件
+    ├── consensus.md              # 共识结论（如达成）
+    ├── config.json               # 会话配置
+    └── battle.log                # 运行日志（tail -f 实时查看）
+```
+
+## 🔌 扩展 Agent
+
+只需实现 3 个函数并注册：
+
+```bash
+# 1. 实现函数
+check_myagent()          { ... }  # 可用性检查，返回 0/1
+call_myagent()           { ... }  # 调用 Agent: $1=system_prompt $2=user_msg $3=session_tag
+generate_myagent_md()    { ... }  # 生成指令文件: $1=max_rounds $2=problem
+
+# 2. 注册
+register_agent "myagent"
+```
+
+## 🔑 环境变量
+
+| 变量 | 说明 | 默认值 |
+| :--- | :--- | :--- |
+| `ANTHROPIC_BASE_URL` | Claude API 地址 | — |
+| `ANTHROPIC_AUTH_TOKEN` | Claude 认证 Token | — |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Claude 模型名称 | — |
+| `API_TIMEOUT_MS` | Claude 超时时间（毫秒） | — |
+| `CODEX_MODEL` | Codex 模型名称 | `gpt-5.3-codex` |
+| `GEMINI_API_KEY` | Gemini API Key | — |
+
+## 🤝 参与贡献
+
+欢迎提交 [Issue](https://github.com/Alfonsxh/ai-battle/issues) 和 [Pull Request](https://github.com/Alfonsxh/ai-battle/pulls)！
+
+## 📄 许可
+
+[MIT](LICENSE) © [Alfons](https://github.com/Alfonsxh)

package/ai-battle.sh

@@ -1731,93 +1731,95 @@ finish_consensus() {
 cmd_help() {
   cat << HELP
 
-  ai-battle — AI 圆桌讨论工具 (v${VERSION})
+  ai-battle — AI Roundtable Discussion Tool (v${VERSION})
 
-  让多个 AI Agent 对同一问题进行结构化讨论，自动管理轮次、
-  检测共识、保存全部讨论记录。
+  Facilitate structured discussions among multiple AI Agents on a given
+  topic. Automatically manages rounds, detects consensus, and saves all
+  discussion records.
 
-  前置条件:
-    1. 确保参与讨论的 Agent CLI 工具已安装并可用
-    2. 首次运行会自动弹出编辑器创建讨论问题
+  Prerequisites:
+    1. Ensure the Agent CLI tools you want to use are installed and available
+    2. On first run, an editor will open to define the discussion topic
 
-  依赖: jq, bash 4+, (可选) claude, codex, gemini
+  Dependencies: jq, bash 4+, (optional) claude, codex, gemini
 
-  用法:
+  Usage:
     ai-battle [options]
     ai-battle help
 
-  参数:
-    --agents, -a <a1,a2>   选择参与的 Agent（默认: claude,codex）
-                           支持同类 Agent: --agents gemini,gemini
-    --rounds, -r <N>       最大讨论轮次（默认: 10）
-    --god, -g              开启上帝视角（每轮结束后可注入补充信息）
-    --referee [agent]      开启裁判模式（每轮总结差异/检测共识，结束时生成最终总结）
-                           可选指定裁判使用的 Agent（默认: 第一个参与者）
-
-  已注册 Agent:
-    claude    通过 Claude CLI 调用 (需 claude 命令)
-    codex     通过 codex exec 调用 (需 codex 命令)
-    gemini    通过 Gemini CLI 调用 (需 gemini 命令)
-
-  使用示例:
-    # 快速开始（首次运行会自动弹出编辑器输入问题）
+  Options:
+    --agents, -a <a1,a2>   Select participating agents (default: claude,codex)
+                           Supports same-type agents: --agents gemini,gemini
+    --rounds, -r <N>       Max discussion rounds (default: 10)
+    --god, -g              Enable god mode (inject instructions after each round)
+    --referee [agent]      Enable referee mode (summarize each round, detect
+                           consensus, generate final summary)
+                           Optionally specify the referee agent (default: first agent)
+
+  Registered Agents:
+    claude    Via Claude CLI (requires 'claude' command)
+    codex     Via codex exec (requires 'codex' command)
+    gemini    Via Gemini CLI (requires 'gemini' command)
+
+  Examples:
+    # Quick start (editor opens to define the topic on first run)
     mkdir my-topic && cd my-topic
     ai-battle --agents claude,gemini --rounds 8
 
-    # 同类 Agent 自我辩论
+    # Same-type agent self-debate
     ai-battle --agents gemini,gemini
 
-    # 三方圆桌讨论
+    # Three-way roundtable
     ai-battle --agents claude,codex,gemini --rounds 5
 
-    # 裁判模式（每轮总结 + 结束时生成 SUMMARY.md）
+    # Referee mode (per-round summary + SUMMARY.md on completion)
     ai-battle --agents claude,codex,gemini --referee --rounds 5
 
-    # 指定 claude 做裁判
+    # Specify claude as referee
     ai-battle --agents codex,gemini --referee claude --rounds 5
 
-    # 上帝视角（每轮可人工补充信息）
+    # God mode (inject human input after each round)
     ai-battle --agents claude,codex --god
 
-    # 裁判 + 上帝视角
+    # Referee + God mode
     ai-battle --agents claude,codex --referee --god
 
-  产出文件:
-    .ai-battle/rounds/       每轮讨论记录 (round_N_<agent>.md)
-    .ai-battle/rounds/referee_*.md  裁判总结记录 (--referee)
-    .ai-battle/rounds/god_*.md      上帝视角注入记录 (--god)
-    .ai-battle/sessions/     Agent CLI 原始输出记录
-    .ai-battle/consensus.md  共识结论（如达成）
-    .ai-battle/battle.log    完整日志
-    SUMMARY.md               最终总结 (裁判自动生成，输出到运行目录)
-
-  用户文件 (运行目录):
-    problem.md               讨论问题定义 (首次运行自动创建)
-    referee.md               裁判自定义提示词 (--referee 时可选)
-    .env                     环境变量 (启动时自动加载)
-
-  扩展 Agent:
-    在脚本中实现 check_<name>()、call_<name>()、generate_<name>_md()
-    然后调用 register_agent "<name>"
-
-  环境变量:
+  Output Files:
+    .ai-battle/rounds/              Per-round records (round_N_<agent>.md)
+    .ai-battle/rounds/referee_*.md  Referee summaries (--referee)
+    .ai-battle/rounds/god_*.md      God mode injections (--god)
+    .ai-battle/sessions/            Raw Agent CLI output
+    .ai-battle/consensus.md         Consensus conclusion (if reached)
+    .ai-battle/battle.log           Full log
+    SUMMARY.md                      Final summary (generated by referee)
+
+  User Files (working directory):
+    problem.md               Discussion topic definition (auto-created on first run)
+    referee.md               Custom referee prompt (optional, for --referee)
+    .env                     Environment variables (auto-loaded on startup)
+
+  Extending Agents:
+    Implement check_<name>(), call_<name>(), generate_<name>_md()
+    then call register_agent "<name>"
+
+  Environment Variables:
     Claude:
-      ANTHROPIC_BASE_URL              API 地址
-      ANTHROPIC_AUTH_TOKEN             认证 Token
-      ANTHROPIC_DEFAULT_SONNET_MODEL   模型名称
-      API_TIMEOUT_MS                  超时时间 (毫秒)
+      ANTHROPIC_BASE_URL              API endpoint
+      ANTHROPIC_AUTH_TOKEN             Auth token
+      ANTHROPIC_DEFAULT_SONNET_MODEL   Model name
+      API_TIMEOUT_MS                  Timeout in milliseconds
 
     Codex:
-      CODEX_MODEL       模型名称 (默认: gpt-5.3-codex)
+      CODEX_MODEL       Model name (default: gpt-5.3-codex)
 
     Gemini:
-      GEMINI_API_KEY    API Key (如需自定义)
+      GEMINI_API_KEY    API key (if custom endpoint needed)
 
-  项目:
+  Project:
     GitHub: https://github.com/Alfonsxh/ai-battle
     npm:    https://www.npmjs.com/package/ai-battle
-    作者:   Alfons <alfonsxh@gmail.com>
-    许可:   MIT
+    Author: Alfons <alfonsxh@gmail.com>
+    License: MIT
 
 HELP
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ai-battle",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "description": "让多个 AI Agent 对同一问题进行结构化圆桌讨论",
     "bin": {
         "ai-battle": "./ai-battle.sh"