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外部依赖
| 类型 | 依赖 |
|---|---|
| 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风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- 文档出域不可控（主要在功能固有） — 每次 critique 都会把 spec 全文送给所选模型；--context 还会读取并外发任意本地文件（schema.sql、合规文档等）。产品规格常含未公开信息，使用前必须确认文档可否发给对应供应商；企业场景应切 Bedrock 或仅用自托管模型。
- 外部模型输出即第二指令源 — 脚本按字面标记解析 [AGREE]/[SPEC]，模型返回文本既进入下一轮输入也进入 Claude 的综合素材；若某模型（或其被注入的上下文，如 --context 里的恶意文档）输出指令性内容，可能影响最终文档与『是否收敛』的判定。
- 凭证面宽 — 读取多达 9 个 API key 环境变量 + AWS 凭证 + Telegram token；list_providers 会暴露『哪些钥匙存在』这一信息；telegram 通道把文档摘要外发到第三方平台（Telegram）。
- 子进程与 --full-auto — codex exec --full-auto 授权该 CLI 自行执行动作（在其自身沙箱内），gemini -y 亦为自动批准模式；两个 CLI 均为远程安装的第三方包，行为受其自身版本与账号策略影响，本 skill 不做审计。
- 无强制轮数护栏 + 成本不可预知 — 'Maximum 10 rounds' 仅是提示词纪律（代码无上限），多模型多轮会产生真实费用；难度高的 spec 可能长时间迭代并把成本推到用户预期之外（虽有成本摘要，但是事后可见）。
- 文档质量依赖模型与提示词，无客观验证 — 所谓『收敛』等于所选模型都输出了 [AGREE]，不构成对规格正确性的验证；SKILL.md 也自述要按 document 类型清单人工核对（Step 5 的 completeness/consistency/clarity/actionability 四项自检）。
风险提醒：橙色，评估后使用。按统一分档：本 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 的环境（子进程面与订阅账号绑定）；以及只想快速起草文档、不需要对抗评审的场景（辩论流程会显著延长交付时间）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 adversarial-spec.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent89a0a6e57cca0f6a…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库zscole / zscole/adversarial-spec
原始 GitHubzscole/adversarial-spec ↗
Stars556
最近推送2026-01-22
本 skill commit
f90cf0c36c许可MIT（仓库根 LICENSE；GitHub API spdx=MIT；pyproject license = {text = "MIT"}）
本站信息
收录日期2026-09-06
分类基础工具与工作流
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。