ai-battle 0.2.0 → 0.2.2

package/README.md

@@ -10,17 +10,41 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/ai-battle"><img src="https://img.shields.io/npm/v/ai-battle?style=flat-square&logo=npm&logoColor=white&color=CB3837" alt="npm version" /></a>
+  <a href="https://github.com/Alfonsxh/ai-battle/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/Alfonsxh/ai-battle/publish.yml?style=flat-square&logo=githubactions&logoColor=white" alt="publish" /></a>
   <img src="https://img.shields.io/badge/Bash-4%2B-4EAA25?style=flat-square&logo=gnubash&logoColor=white" alt="Bash 4+" />
   <img src="https://img.shields.io/badge/Dep-jq-blue?style=flat-square" alt="jq" />
   <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>
+  <a href="README_CN.md">中文</a> ·
+  <a href="https://www.npmjs.com/package/ai-battle">NPM</a> ·
+  <a href="https://github.com/Alfonsxh/ai-battle/issues">Issues</a> ·
+  <a href="https://github.com/Alfonsxh/ai-battle/pulls">PRs</a> ·
+  <a href="LICENSE">License</a>
 </p>
 
 ---
 
+<details>
+<summary><b>Table of Contents</b></summary>
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+- [Examples](#examples)
+- [How It Works](#how-it-works)
+- [Built-in Agents](#built-in-agents)
+- [Output Structure](#output-structure)
+- [Extend Agent](#extend-agent)
+- [Environment Variables](#environment-variables)
+- [Contributing](#contributing)
+- [License](#license)
+
+</details>
+
 ## ✨ Features
 
 | Feature | Description |
@@ -70,7 +94,7 @@ npm install -g ai-battle
 
 ## 📖 Usage
 
-```
+```text
 ai-battle [options]
 ai-battle help
 ```
@@ -245,141 +269,3 @@ register_agent "myagent"
 ## 📄 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

@@ -23,12 +23,31 @@ if [ -f ".env" ]; then
 fi
 
 # ======================== 版本（从 package.json 读取） ========================
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# 解析脚本真实路径（支持全局安装后经由软链接启动）
+resolve_script_dir() {
+  local src="${BASH_SOURCE[0]}"
+
+  while [ -L "$src" ]; do
+    local dir target
+    dir="$(cd -P "$(dirname "$src")" && pwd)"
+    target="$(readlink "$src")"
+    if [[ "$target" != /* ]]; then
+      src="${dir}/${target}"
+    else
+      src="$target"
+    fi
+  done
+
+  cd -P "$(dirname "$src")" && pwd
+}
+
+SCRIPT_DIR="$(resolve_script_dir)"
+
 # 优先使用 npm/npx 注入的环境变量，fallback 到 node 读取，最后 grep 提取
 if [ -n "${npm_package_version:-}" ]; then
   VERSION="$npm_package_version"
 else
-  VERSION=$(node -p "require('${SCRIPT_DIR}/package.json').version" 2>/dev/null \
+  VERSION=$(node -p "require(process.argv[1]).version" "${SCRIPT_DIR}/package.json" 2>/dev/null \
     || grep -o '"version": *"[^"]*"' "${SCRIPT_DIR}/package.json" 2>/dev/null | head -1 | grep -o '[0-9][^"]*' \
     || echo "0.0.0")
 fi
@@ -50,6 +69,8 @@ DEFAULT_MAX_ROUNDS=10
 WORK_DIR=".ai-battle"
 PROBLEM_FILE="problem.md"
 ROUNDS_DIR="${WORK_DIR}/rounds"
+ORDERS_DIR="${WORK_DIR}/orders"
+ORDER_HISTORY_FILE="${WORK_DIR}/order_history.jsonl"
 CONSENSUS_FILE="${WORK_DIR}/consensus.md"
 LOG_FILE="${WORK_DIR}/battle.log"
 CONFIG_FILE="${WORK_DIR}/config.json"
@@ -566,6 +587,138 @@ agent_md_file() {
   echo "${AGENTS_DIR}/${filename}"
 }
 
+# 查找 agent 在数组中的索引
+# 参数: $1=目标 agent  $2...=agent 列表
+# 输出: 索引（找不到返回 -1）
+find_agent_index() {
+  local target="$1"
+  shift
+  local agents=("$@")
+
+  for ((idx=0; idx<${#agents[@]}; idx++)); do
+    if [ "${agents[$idx]}" = "$target" ]; then
+      echo "$idx"
+      return 0
+    fi
+  done
+
+  echo "-1"
+  return 0
+}
+
+# 校验轮次顺序 CSV 是否与当前 agent 列表一一对应
+# 参数: $1=order_csv  $2...=agent 列表
+# 返回: 0=有效, 1=无效
+validate_round_order_csv() {
+  local order_csv="$1"
+  shift
+  local agents=("$@")
+  local order=()
+
+  [ -n "$order_csv" ] || return 1
+  IFS=',' read -ra order <<< "$order_csv"
+
+  if [ "${#order[@]}" -ne "${#agents[@]}" ]; then
+    return 1
+  fi
+
+  for ((idx=0; idx<${#order[@]}; idx++)); do
+    order[$idx]=$(echo "${order[$idx]}" | xargs)
+  done
+
+  # 每个 agent 必须且仅出现一次，避免顺序文件损坏导致错位
+  for expected in "${agents[@]}"; do
+    local count=0
+    for got in "${order[@]}"; do
+      if [ "$got" = "$expected" ]; then
+        count=$((count + 1))
+      fi
+    done
+    if [ "$count" -ne 1 ]; then
+      return 1
+    fi
+  done
+
+  return 0
+}
+
+# Fisher-Yates 洗牌，生成当前轮次的随机顺序
+# 参数: $@=agent 列表
+# 输出: csv 字符串（如 a,b,c）
+shuffle_round_order_csv() {
+  local shuffled=("$@")
+  local n=${#shuffled[@]}
+
+  if [ "$n" -eq 0 ]; then
+    echo ""
+    return 0
+  fi
+
+  for ((i=n-1; i>0; i--)); do
+    local j=$((RANDOM % (i + 1)))
+    local tmp="${shuffled[$i]}"
+    shuffled[$i]="${shuffled[$j]}"
+    shuffled[$j]="$tmp"
+  done
+
+  local csv="${shuffled[0]}"
+  for ((i=1; i<n; i++)); do
+    csv+=",${shuffled[$i]}"
+  done
+  echo "$csv"
+}
+
+# 记录轮次顺序历史（jsonl），用于兜底追踪和恢复审计
+# 参数: $1=round  $2=order_csv  $3=source(random|recovered)
+record_round_order() {
+  local round="$1"
+  local order_csv="$2"
+  local source="${3:-random}"
+  local ts
+  ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  local order_json
+  order_json=$(printf '%s' "$order_csv" | jq -R 'split(",")')
+
+  jq -cn \
+    --arg ts "$ts" \
+    --arg source "$source" \
+    --argjson round "$round" \
+    --argjson order "$order_json" \
+    '{ts: $ts, round: $round, source: $source, order: $order}' \
+    >> "$ORDER_HISTORY_FILE"
+}
+
+# 读取或生成某一轮的顺序：
+# 1) 若顺序文件存在且有效，复用；2) 否则随机生成并落盘
+# 参数: $1=round  $2...=agent 列表
+# 输出: order_csv
+resolve_round_order_csv() {
+  local round="$1"
+  shift
+  local agents=("$@")
+  local order_file="${ORDERS_DIR}/round_${round}.order"
+  local order_csv=""
+  local source="recovered"
+
+  if [ -f "$order_file" ] && [ -s "$order_file" ]; then
+    order_csv=$(tr -d '\r\n' < "$order_file")
+    if ! validate_round_order_csv "$order_csv" "${agents[@]}"; then
+      log_and_print "${YELLOW}⚠️ Round ${round} 顺序文件无效，已重新随机${NC}"
+      order_csv=""
+    fi
+  fi
+
+  if [ -z "$order_csv" ]; then
+    order_csv=$(shuffle_round_order_csv "${agents[@]}")
+    echo "$order_csv" > "$order_file"
+    source="random"
+  fi
+
+  record_round_order "$round" "$order_csv" "$source"
+  echo "$order_csv"
+}
+
 # 上帝视角: 等待用户输入补充信息
 # 参数: $1=当前轮次
 # 输出: stdout 用户输入的补充信息（可为空）
@@ -1069,8 +1222,8 @@ cmd_run() {
     exit 1
   fi
 
-  # 创建 rounds 目录
-  mkdir -p "$ROUNDS_DIR" "$SESSIONS_DIR" "$AGENTS_DIR"
+  # 创建运行目录（包含顺序记录目录）
+  mkdir -p "$ROUNDS_DIR" "$SESSIONS_DIR" "$AGENTS_DIR" "$ORDERS_DIR"
 
   # 动态生成各 Agent 的指令文件（新建和恢复模式都需要更新）
   for agent in "${available_agents[@]}"; do
@@ -1117,6 +1270,7 @@ cmd_run() {
   log_and_print "  📝 问题: $(head -1 "$PROBLEM_FILE")"
   log_and_print "  🤖 Agent: ${available_agents[*]}"
   log_and_print "  🔄 最大轮次: $max_rounds"
+  log_and_print "  🔀 发言顺序: 每轮随机（自动记录并可恢复）"
   if $god_mode; then
     log_and_print "${CYAN}  👁️  上帝视角: 开启${NC}"
   fi
@@ -1160,7 +1314,7 @@ cmd_run() {
     round=$((prev_round + 1))
 
     # 更新配置: 状态为 running，max_rounds 使用命令行参数
-    jq --argjson m "$max_rounds" '.status = "running" | .max_rounds = $m' \
+    jq --argjson m "$max_rounds" '.status = "running" | .max_rounds = $m | .order_mode = "round_random"' \
       "$CONFIG_FILE" > "${CONFIG_FILE}.tmp" \
       && mv "${CONFIG_FILE}.tmp" "$CONFIG_FILE"
 
@@ -1197,7 +1351,7 @@ cmd_run() {
       --argjson max_rounds "$max_rounds" \
       --arg problem "$problem" \
       '{agents: $agents, max_rounds: $max_rounds, problem: $problem,
-        status: "running", current_round: 0}' \
+        status: "running", current_round: 0, order_mode: "round_random", last_round_order: ""}' \
       > "$CONFIG_FILE"
 
     # 清空日志
@@ -1353,10 +1507,21 @@ ${all_responses_r1}请进行裁判总结。" "referee_round_1")
   # 提取为函数逻辑，供主循环和追加轮次复用
   while [ "$round" -le "$max_rounds" ]; do
     local remaining=$((max_rounds - round))
-
-    # 每个 agent 依次发言，看到所有其他 agent 的上一轮回复
-    for ((i=0; i<agent_count; i++)); do
-      local agent="${available_agents[$i]}"
+    local round_order_csv
+    round_order_csv=$(resolve_round_order_csv "$round" "${available_agents[@]}")
+    local round_order=()
+    IFS=',' read -ra round_order <<< "$round_order_csv"
+
+    log_and_print "${CYAN}🔀 Round $round 顺序: ${round_order[*]}${NC}"
+
+    # 每轮默认随机顺序发言，优先复用已落盘顺序（便于恢复）
+    for agent in "${round_order[@]}"; do
+      local i
+      i=$(find_agent_index "$agent" "${available_agents[@]}")
+      if [ "$i" -lt 0 ]; then
+        log_and_print "${YELLOW}⚠️ 跳过未知 agent: ${agent}${NC}"
+        continue
+      fi
       local base
       base=$(agent_base "$agent")
       local color
@@ -1368,8 +1533,8 @@ ${all_responses_r1}请进行裁判总结。" "referee_round_1")
       # 构建其他 agent 回复的 XML 块
       local others_responses=""
       for ((j=0; j<agent_count; j++)); do
-        if [ "$j" != "$i" ]; then
-          local other="${available_agents[$j]}"
+        local other="${available_agents[$j]}"
+        if [ "$other" != "$agent" ]; then
           others_responses+="<${other}_response>
 ${responses[$j]}
 </${other}_response>
@@ -1502,7 +1667,8 @@ ${all_responses}请进行裁判总结。" "referee_round_${round}")
     fi
 
     # 更新配置
-    jq --argjson r "$round" '.current_round = $r | .status = "running"' \
+    jq --argjson r "$round" --arg o "$round_order_csv" \
+      '.current_round = $r | .status = "running" | .last_round_order = $o' \
       "$CONFIG_FILE" > "${CONFIG_FILE}.tmp" && mv "${CONFIG_FILE}.tmp" "$CONFIG_FILE"
 
     # 上帝视角: 每轮结束后注入（裁判总结后再让 god 输入）
@@ -1554,9 +1720,20 @@ ${all_responses}请进行裁判总结。" "referee_round_${round}")
     # 继续讨论循环（逻辑与上方 Round 2+ 完全相同）
     while [ "$round" -le "$max_rounds" ]; do
       local remaining=$((max_rounds - round))
-
-      for ((i=0; i<agent_count; i++)); do
-        local agent="${available_agents[$i]}"
+      local round_order_csv
+      round_order_csv=$(resolve_round_order_csv "$round" "${available_agents[@]}")
+      local round_order=()
+      IFS=',' read -ra round_order <<< "$round_order_csv"
+
+      log_and_print "${CYAN}🔀 Round $round 顺序: ${round_order[*]}${NC}"
+
+      for agent in "${round_order[@]}"; do
+        local i
+        i=$(find_agent_index "$agent" "${available_agents[@]}")
+        if [ "$i" -lt 0 ]; then
+          log_and_print "${YELLOW}⚠️ 跳过未知 agent: ${agent}${NC}"
+          continue
+        fi
         local base
         base=$(agent_base "$agent")
         local color
@@ -1568,8 +1745,8 @@ ${all_responses}请进行裁判总结。" "referee_round_${round}")
         # 构建其他 agent 回复的 XML 块
         local others_responses=""
         for ((j=0; j<agent_count; j++)); do
-          if [ "$j" != "$i" ]; then
-            local other="${available_agents[$j]}"
+          local other="${available_agents[$j]}"
+          if [ "$other" != "$agent" ]; then
             others_responses+="<${other}_response>
 ${responses[$j]}
 </${other}_response>
@@ -1697,7 +1874,8 @@ ${all_responses}请进行裁判总结。" "referee_round_${round}")
       fi
 
       # 更新配置
-      jq --argjson r "$round" '.current_round = $r | .status = "running"' \
+      jq --argjson r "$round" --arg o "$round_order_csv" \
+        '.current_round = $r | .status = "running" | .last_round_order = $o' \
         "$CONFIG_FILE" > "${CONFIG_FILE}.tmp" && mv "${CONFIG_FILE}.tmp" "$CONFIG_FILE"
 
       # 上帝视角: 每轮结束后注入（裁判总结后再让 god 输入）
@@ -1751,6 +1929,7 @@ cmd_help() {
     --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)
+                           Speaking order is randomized every round by default
     --god, -g              Enable god mode (inject instructions after each round)
     --referee [agent]      Enable referee mode (summarize each round, detect
                            consensus, generate final summary)
@@ -1788,6 +1967,8 @@ cmd_help() {
     .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/orders/round_*.order Per-round speaking order (fallback/recovery)
+    .ai-battle/order_history.jsonl  Full order history (audit trail)
     .ai-battle/sessions/            Raw Agent CLI output
     .ai-battle/consensus.md         Consensus conclusion (if reached)
     .ai-battle/battle.log           Full log

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "ai-battle",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "description": "让多个 AI Agent 对同一问题进行结构化圆桌讨论",
     "bin": {
-        "ai-battle": "./ai-battle.sh"
+        "ai-battle": "ai-battle.sh"
     },
     "files": [
         "ai-battle.sh",
@@ -22,8 +22,8 @@
     ],
     "repository": {
         "type": "git",
-        "url": "https://github.com/Alfonsxh/ai-battle.git"
+        "url": "git+https://github.com/Alfonsxh/ai-battle.git"
     },
     "author": "Alfons",
     "license": "MIT"
-}
+}