1实现原理 · 为什么它能做到
机制核心不是『调用多个模型』而是『Claude 亲自下场』：SKILL.md 要求 Claude 在给出对手模型结论的同时给出自己的独立 critique 与综合裁决，并明确让用户知道这一点。
skills/adversarial-spec/SKILL.md
**Important: Claude is an active participant in this debate, not just an orchestrator.** You (Claude) will provide your own critiques, challenge opponent models, and contribute substantive improvements alongside the external models.
Step 4 给出固定输出模板（--- Round N --- / Opponent Models / Claude's Critique / Synthesis），把『哪条批评来自谁、Claude 自己补了什么、拒了什么』逐项摆出来，避免多模型评审退化成黑箱。
真实执行层是一个自带 Python CLI（debate.py + 5 个模块），skill 通过固定命令行把文档经 stdin 喂给脚本；脚本用 litellm 并行调用各家 provider 并解析 `[AGREE]` / `[SPEC]` 标记。
skills/adversarial-spec/SKILL.md
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" critique --models MODEL_LIST --doc-type TYPE <<'SPEC_EOF'
脚本路径用 find 在 ~/.claude 下动态定位，说明该 skill 以插件形式安装到用户家目录；调用方式为 heredoc 传 stdin（debate.py 内 'spec = sys.stdin.read().strip()'）。
调用通道分两类：API key 走的模型经 litellm 统一出口；订阅制模型（ChatGPT/Google 账号）走本机 CLI 子进程，把文档拼进 argv/stdin 交给 codex / gemini。
skills/adversarial-spec/scripts/models.py
cmd = [ "codex", "exec", "--json", "--full-auto", "--skip-git-repo-check", "--model", actual_model, "-c", f'model_reasoning_effort="{reasoning_effort}"', ]
Gemini 侧为 'gemini', '-m', actual_model, '-y' 且 prompt 经 stdin 传入（models.py call_gemini_cli_model）。可用性探测在 providers.py：CODEX_AVAILABLE = shutil.which("codex") is not None / GEMINI_CLI_AVAILABLE = shutil.which("gemini") is not None。
收敛判定靠模型输出里的字面标记，而非语义判断：任何模型没出现 [AGREE] 就继续下一轮；对『前两轮就同意』强制加一轮 --press 反懒惰盘问。
skills/adversarial-spec/SKILL.md
**Handling Early Agreement (Anti-Laziness Check):** If any model says `[AGREE]` within the first 2 rounds, be skeptical.
PRESS_PROMPT_TEMPLATE（prompts.py）要求模型确认读完整篇、列出至少 3 个复核过的章节、说明为何同意、并给出残余顾虑。脚本侧对应 '--press' 选项；轮数上限只写在 SKILL.md（'Maximum 10 rounds per cycle'），代码里没有强制。
长辩论可中断可回滚：会话状态、每轮 checkpoint、常用配置各自落盘，session 与 profile 分离存放。
skills/adversarial-spec/scripts/session.py
SESSIONS_DIR = Path.home() / ".config" / "adversarial-spec" / "sessions" CHECKPOINTS_DIR = Path.cwd() / ".adversarial-spec-checkpoints"
providers.py 另有 PROFILES_DIR = Path.home() / ".config" / "adversarial-spec" / "profiles" 与 GLOBAL_CONFIG_PATH = Path.home() / ".claude" / "adversarial-spec" / "config.json"（Bedrock 开关存这里）。SKILL.md 对应描述 'Sessions are stored in `~/.config/adversarial-spec/sessions/`' 与 'each round's spec is saved to `.adversarial-spec-checkpoints/`'。
可选的人工在环通道是 Telegram 机器人：每轮把摘要推给用户，轮询 60 秒内回复并把答复并入下一轮；无需回复则自动继续。
skills/adversarial-spec/scripts/telegram_bot.py
TELEGRAM_API: str = "https://api.telegram.org/bot{token}/{method}"
token != '' 时生效（'token = os.environ.get("TELEGRAM_BOT_TOKEN", "")'），SKILL.md 说明 'After each round: Bot sends summary to Telegram / 60 seconds to reply with feedback (configurable via --poll-timeout) / Reply incorporated into next round / No reply = auto-continue'。
企业级替代通道：可切到 AWS Bedrock 让所有模型调用统一走 Bedrock 前缀（用于合规/网关场景），配置写回家目录的 config.json。
skills/adversarial-spec/SKILL.md
**When Bedrock mode is enabled, ALL model calls route through Bedrock** - no direct API calls are made.
代码侧：models.py 'os.environ["AWS_REGION"] = bedrock_region' 与 'if not model.startswith("bedrock/"): actual_model = f"bedrock/{model}"'；providers.py handle_bedrock_command 负责 status/enable/disable/add-model/remove-model/alias，配置落在 GLOBAL_CONFIG_PATH。
成品交付由 Claude（宿主）完成而非脚本：skill 要求把最终文档打印并写入当前目录的 spec-output.md（PRD 续做则为 tech-spec-output.md），脚本本身不产出该文件。
skills/adversarial-spec/SKILL.md
1. Print the complete, polished document to terminal 2. Write it to `spec-output.md` in current directory
全 scripts/ 目录 grep 'spec-output' 无命中，佐证写文件是宿主 Write 工具动作（SKILL.md allowed-tools 声明 'Bash, Read, Write, AskUserQuestion'），脚本只负责评审/差异/导出。
2核心能力
01多模型并行对抗评审（一次 critique 调用并发打多家 provider，逐模型返回批评或 [AGREE]）
02两类文档模板 + 对应批评标准（PRD 与 Technical Specification 各自的结构清单与 7-8 条评审准则）
03Interview mode：先做覆盖 8 大主题的深度需求访谈（AskUserQuestion）再进入辩论
04聚焦模式 --focus：把评审火力定向到 security / scalability / performance / ux / reliability / cost
05专家人格 --persona：security-engineer / oncall-engineer / junior-developer / qa-engineer / site-reliability / product-manager / data-engineer / mobile-developer / accessibility-specialist / legal-compliance，并支持自定义字符串
06上下文注入 --context：把既有 API 文档/DB schema/合规要求作为附件一并交给评审模型
07会话持久化与断点续跑（--session / --resume / sessions 列表 + 每轮 checkpoint 可回滚）
08轮次差异对比与任务导出（diff --previous/--current；export-tasks 可 --json 输出可直接进 issue tracker 的任务项）
09成本可观测：按模型价目表统计 token 与估算费用，并写进终端摘要/JSON/Telegram 通知
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| package | litellm |
| api | 多家 LLM 供应商 API（经 litellm 统一出口） |
| cli | codex（OpenAI Codex CLI，走 ChatGPT 订阅） |
| cli | gemini（Google Gemini CLI，走 Google 账号） |
| api | AWS Bedrock（可选企业通道，全部调用可改走 bedrock/ 前缀） |
| network | Telegram Bot API（可选人工在环） |
| package | 开发依赖（pytest/pytest-cov/ruff/mypy/pre-commit） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 <…>/debate.py critique|diff|export-tasks|send-final|providers|focus
- 网络端点: 声明外部网络访问: litellm → 各供应商官方 API（OpenAI / Anthropic / Google / xAI / Mistral / Groq / O
- 本地工作目录: 文件读写与工件输出: ~/.claude/adversarial-spec/config.json（bedrock enable/disable/add-model/ali
审计说明： 。按统一分档：本 skill 明确读取多项环境变量凭证（各家 LLM API key、AWS 凭证、Telegram token）并把用户文档全文外发到第三方模型，**属『涉及凭证/环境变量读取 + 第三方插件/远程包依赖』**；同时存在子进程执行面（codex exec --full-auto、gemini -y、自带的 debate.py/telegram_bot.py）。外发对象可预期（官方 API/官方 CLI/Bedrock/Telegram Bot API），无 TLS 降级、无绕过、无混淆代码，故不升红；但涉及凭证与在环人工通道，使用前应确认哪些密钥可见、文档可否出域（企业场景建议直接启用 Bedrock 通道或禁用 Telegram 路径）。
5第二遍独立确认
- [ok] 多模型调用确实存在（非纯提示词） — models.py import litellm + from litellm import completion，标准路径 'response = completion(**completion_kwargs)'；providers.py CODEX_AVAILABLE/GEMINI_CLI_AVAILABLE 用 shutil.which 探测。
- [ok] 订阅制模型走 CLI 子进程 — call_codex_model 构造 ['codex','exec','--json','--full-auto','--skip-git-repo-check','--model',…] 并 subprocess.run；call_gemini_cli_model 构造 ['gemini','-m',model,'-y'] 并把 prompt 经 input= 传入。
- [ok] Telegram 端点与轮询 — telegram_bot.py 'TELEGRAM_API: str = "https://api.telegram.org/bot{token}/{method}"' + 'with urlopen(req, timeout=30)'（urllib，非 requests）；poll_for_reply(timeout=60 默认) 与 cmd_notify 均存在。
- [ok] Bedrock 模式确实可全量接管调用 — is_bedrock_enabled()/get_bedrock_config() 读 GLOBAL_CONFIG_PATH；models.py 在 bedrock 分支设置 AWS_REGION 并给 model 加 'bedrock/' 前缀；handle_bedrock_command 支持 status/enable/disable/add-model/remove-model/alias。
- [discrepancy] 『Maximum 10 rounds』是否由代码强制 — SKILL.md 写 'Maximum 10 rounds per cycle (ask user to continue if reached)'，但对 debate.py 全文检索无任何轮数上限常量/参数（--round 只是当前轮号，--rounds 只用于 send-final 汇报）。结论：轮数上限是提示词纪律，代码不设护栏，已在 how_it_works 第 4 条与 risks 中如实标注。
- [discrepancy] 『Write it to spec-output.md』的归属 — 第一遍曾按『脚本写文件』记录；第二遍在 scripts/ 全目录检索 'spec-output' 零命中，确认该写入由宿主 Write 工具完成（SKILL.md allowed-tools: Bash, Read, Write, AskUserQuestion）。已改写为『成品交付由 Claude 完成』并据此调整 file_writes。
- [discrepancy] Python 版本要求一致性 — SKILL.md Requirements 写 'Python 3.10+ with `litellm` package installed'，而 pyproject.toml 写 requires-python = ">=3.9" 且 ruff target-version = "py39"、mypy python_version = "3.10"。属文档与打包元数据的轻微不一致（不影响功能判定）。
- [ok] 成本追踪是否真有实现（非仅文档） — providers.py MODEL_COSTS 价目表 + DEFAULT_COST；debate.py 'Cost: ${cost_tracker.total_cost:.4f}' 与 JSON 输出 'cost': {total, input_tokens, output_tokens, by_model}。
6结论
适合： 适合：需要产出 PRD 或技术规格、且希望被多个不同厂商模型交叉挑刺的工程/产品团队；已有 API key 或 codex/gemini 订阅、愿意把文档发给相应供应商的个人开发者；需要把『规格评审』流程化并留痕（每轮 checkpoint、diff、成本摘要）的团队；企业合规场景可走 Bedrock 通道。
不适合： 不适合：文档含不可外发机密且无法使用自托管/Bedrock 通道的场景；期望 skill 自动判定规格『正确』的用户（它只汇总批评，不验证事实）；不想付多模型调用费或不想管理多把钥匙的用户；不希望 agent 调用本机 codex/gemini CLI 的环境（子进程面与订阅账号绑定）；以及只想快速起草文档、不需要对抗评审的场景（辩论流程会显著延长交付时间）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload adversarial-spec.tar.gz
sha256:
Option B · Copy Guide for Agent89a0a6e57cca0f6a…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit f90cf0c36c.