Amicus

---

目录

• Amicus 是什么
• Council
• 运行 council 的方式
• 快速开始
  • 1. 安装
  • 2. 配置——请勿跳过
  • 3. 你的首次 council
  • 4. 你的首个 sidecar
• 要求与依赖
• 并行窗口
• 命令
• 模型
• MCP 集成
• 配置
• JSON 输出
• Windows
• 故障排除
• 文档
• 贡献
• 基于 OpenCode 构建
• 致谢与许可证

---

什么是 Amicus

一次安装即可获得六项协同工作的功能：

• second-opinion LLM Council 技能。 结构化多模型评审：独立评审 → 匿名交叉评审 → 非 Claude 主席裁决 → 分级接受／拒绝决策。这是核心功能。
• sidecar 聊天技能。 随时分叉／协作／合并——在真实窗口（或无头模式）中启动另一个模型，与它协同工作，再将摘要合并回来。
• amicus CLI（带有 am 别名）和 MCP 服务。 两项技能背后的引擎：启动会话、共享上下文、运行并行轮次，并通过 MCP 工具向 Claude 提供相同的功能。
• 自动更新的模型目录。 别名和验证会根据从提供商 API 获取的实时目录（缓存在本地）进行解析，因此无需硬编码表格，模型名称也能保持最新。
• 可观测性。 amicus watch <id> 可在任意终端中呈现任意正在运行或已完成的运行（扇出或 Council）；--follow 会实时推送进度节点；--on-complete 会在运行结束时触发钩子；--retry-failed 加上可选的低成本模型回退方案，可在无需重新启动整个轮次的情况下恢复失败环节；amicus spend 可按运行归因，回答“这花了多少钱，花在了哪里”。
• Council Workspace。 amicus watch <runId> --ui：一个展示 Council 思考过程的窗口——包括实时席位、匿名评审包、裁决矩阵、异议深入分析、主席裁决和按席位统计的成本，适用于正在运行和历史运行。它还会在 Claude Code 调用 MCP 运行 Council 时（本地）自动打开，因此你无需再记住这个标志（参见 docs/council.md）。

Claude 是编排者。Council 和聊天技能运行于引擎之上；你与 Claude 对话，由 Claude 驱动 Amicus。

---

Council

对 Claude 说 “council review this” 即可触发；在插件渠道中，也可以直接运行 /amicus:council。

为什么要用多模型。 任何单个模型——包括运行你当前会话的模型——都有稳定的盲点。将相同材料交给来自不同系列的模型处理，就能暴露它们之间的分歧：遗漏的问题、夸大的信心，以及单个模型可能会轻易放过的论断。Council 是这种思路的结构化实现。

流程分五步：

1. 独立评审。 每个 Council 模型独立评审材料（一个并行轮次），生成结构化问题清单——论断、严重程度（blocker | major | minor | nit）、位置和理由。
2. 匿名交叉评审。 Claude 会为每份评审重新标记（评审 A、B、C……），并向每个模型发送完全相同的材料包。每个模型都会为各份评审排序，并裁定每项发现（agree | dispute | neutral）——它们会在不知情的情况下评判自己的评审，从而消除自我偏见。由此产生 street-cred 排名，并将发现归入 Disputed / Confirmed / Contested / Singleton 等级。自我偏见按席位消除：如果你有意让同一模型占据两个席位，那么每个席位对另一个席位发现的投票都将作为真实的同伴投票计入；如果某项发现唯一的佐证来自它自己的孪生席位，系统就会将其标记出来。
3. 主席裁决。 指定的非 Claude主席会收到去匿名化后的全貌——包括所有评审、排名和裁定——并综合得出独立裁决。Claude 会逐字呈现该裁决；Claude 不负责综合裁决。
4. 分级决策。 对 Confirmed 发现进行一次批量接受／拒绝；对 Contested 和 Singleton 发现逐项决策（接受／拒绝／修改）。
5. 应用结果。 已接受的发现会写入经过评审的源文件副本；完整运行记录会保存到运行文件夹中。

flowchart LR
    A["Artifact"] --> B["Independent<br/>reviews"]
    B --> C["Anonymized<br/>cross-review"]
    C --> D["Chair verdict<br/>(non-Claude)"]
    D --> E["Tiered<br/>accept / deny"]
    E --> F["Reviewed copy<br/>+ run folder"]

一次运行会生成（位于 output/<stem>-council/）：

• review-<model>.md × N — 每个模型各自独立的评审意见。
• crossreview-matrix.md — 裁定矩阵，以及去匿名化后的信誉表。
• verdict.md — 主席的综合结论。
• report.md — 综合结论、完整决策日志，以及逐次调用的运行统计表。
• report.html — 确定性渲染器的输出（裁定矩阵、信誉表、按层级划分的发现、费用——不含主席的文字）。这是默认交付给用户的产物。
• 对于可编辑的源文件，已接受的编辑会写入原文件旁的 <stem>-reviewed.<ext>。

可选的评审团要素（v2.2.0，默认全部关闭）：四种可选行为，启动时只提供一次菜单——除非你明确指定，否则不会启用任何行为；确认信息会明确列出已启用的项目。主席结论等级（自 v2.2.0 后续版本起为标准功能，不再是可选项）：主席始终会以 3–5 个尖锐问题和一行可解析的 VERDICT: Ship it | Fix these first | Fundamental rethink 作结。

• 批评者席位 — 一名评审者改用四轮对抗式简报（对抗式审查、边缘案例搜寻、一致性检查、可执行性测试）。其发现会与其他人的发现一起进入同一匿名评审包，因此评审团也会约束批评者：凭空捏造的负面意见会被标为“有争议”，并在统计中剔除。
• 专家视角 — 每名评审者采取不同的专家视角；由你选择评审团领域（业务、技术、客户、财务或自定义）。采用专家视角的运行不会计入可靠性记录，报告也会披露交叉评审匿名性有所减弱。
• 辩论模式 — 交叉评审后，每项有争议或存在异议的发现都会交回提出者，由其辩护、修订或撤回；提出异议的评审者随后重新投票。仅进行一轮答辩，然后得出最终统计结果。
• 评审团中的 Claude — Claude 会将自己的全新评审意见加入评审包，供评审团排序和裁定。Claude 会接受评判，但绝不投票或担任主席，因此结论仍然独立。

批评者和专家视角的方法改编自 John Renaldi 的 product-kit 中的 /critic 和 /debate Agent（MIT）；简报模板位于 skills/second-opinion/SEAT-BRIEFS.md。

费用会提前披露。 在启动任何模型之前，你会看到运行方案——包括已启用的可选要素——例如：

本次运行将使用 3 个评审团模型，分 2 轮并行调用，另加 1 次主席调用；批评者席位和辩论模式已开启（约 7 次基础运行，最多另加 6 次答辩调用）。

然后评审团会等待你的确认。

该技能位于 skills/second-opinion/SKILL.md；其背后的设计规范是 skills/second-opinion/COUNCIL-DESIGN.md。若要了解 amicus council tally|verdict|report|stats 实际接受哪些输入、生成哪些输出——包括逐字段架构、verdict.json 的溯源信息，以及使用真实 CLI 的完整运行示例——请参阅 docs/council.md。

---

运行评议团的方式

评议团是主角——从日常用法开始，需要时再选择更强大的方式：

• 直接在 Claude Code 中提问。 把计划、差异、设计或手稿交给 Claude，然后说 "council review this." second-opinion 技能会在你的会话中执行上述完整流程，除了 API 密钥外无需任何设置。大多数人都是这样使用的。→ 快速开始
• 在 CI 中无头运行，无需 Claude 运行时。 amicus council run --prompt-file plan.md --council free 只需一条命令即可运行同一流程——评审 → 交叉评审 → 汇总 → 主席裁决——并写入 verdict.json 和 report.html。它不需要 Claude 会话，因此可以直接接入 CI。→ 无头评议团（CI）
• 加入辩论环节。 添加 --debate 后，每项有争议或存疑的发现都会退回给提出者，让其辩护、修订或撤回，同时提出异议的评审重新投票——只有一轮答辩，然后进行最终汇总。→ 评议团
• 使用免费的本地私有模型，费用为 $0。 使用 amicus provider add，将评议团（及辅助程序）指向已在你的机器上运行的 OpenAI 兼容服务，例如 Ollama、LM Studio 或 vLLM。无需 API 密钥，无需按 token 付费，任何内容都不会离开你的机器，而且支持离线运行。→ amicus provider
• 直接针对任务本身，而不是评审任务。 添加 --intent task，同一评审组就会产出交付成果，而不是批评已有成果。→ 任务模式（v4.9）

### 无头评议会（CI）

同一条流水线无需运行 Claude 即可执行：amicus council run --prompt-file briefing.md --models gemini,glm --chair deepseek --json 会通过一条命令执行评审轮次、匿名交叉评审、计票和主席裁决，并写入完整的运行目录（包含带有主席解析出的 overallVerdict 的 verdict.json、report.html，以及每份评审和评审者输出）。这正是该代码库自用的 Council Review GitHub Action v2 的运行方式——对于标记为 council-review 的 PR，它会将裁定后的结论作为检查运行和置顶评论发布，上传运行目录作为证据制品，并默认通过其 fail_on 输入阻止合并（仅在结论为 Fundamental rethink 时失败；传入 fail_on: fix 可要求结论为 Ship it，传入 fail_on: none 则仅生成报告）。参考：docs/council.md。

该 Action 可以为评议席位固定 OpenRouter 上游，而且默认不固定任何上游（#202）。 OpenRouter 会通过多个上游提供商提供同一个模型，而运行记录中没有任何信息表明某个环节由哪个上游提供服务，因此上游响应慢与模型响应慢无法区分。将工作流的 COUNCIL_PROVIDER_ROUTING 设置为路由文档后，它会在付费步骤前将 opencode.json 写入运行目录，为一个基准模型固定上游 （provider.openrouter.models.<id>.options.provider）；使用单一 slug 的 only 时，该模型的各个环节便能明确归因。该功能默认未启用。#202 Lever 2 实验进行了两轮实际测试，将 qwen 固定到一个上游，但首个 token 的耗时尾部并未改善：两轮中，固定的评议席位都在无输出保护机制处首次尝试失败；第 1 轮的重试也失败了（912 s），导致该席位退出；只有第 2 轮的重试及其评审环节通过同一上游完成。因此，两轮中固定上游的 5 个环节有 3 个失败。所以，固定上游并非解决方案；在没有实测收益的情况下，也不应让用于合并门禁的评议席位依赖单一上游。相关机制仍会保留，并通过门控和测试，为下一个问题做好准备。设置固定上游时：文档会在写入前经过验证；无密钥预运行检查会在指定上游未列出或无法提供服务时，为该次运行跳过固定上游；无密钥 canary 会确认引擎仍将该文件传入请求体；运行后的步骤会在固定模型的环节失败时发出警告。若要查看这类运行，请打开其 council-run 证据制品——其中的 opencode.json 记录了当时生效的路由。

免费评议会（零成本）

想要交叉质询，又不想花费模型费用？amicus setup 提供 Free OpenRouter council 模式——可通过 readline 向导的选项 2 或 Electron 的 Models 步骤选择。它会从目录中实时检测免费的 :free 模型，支持多选（按 Enter 可采用供应商多样化的默认选择），并将它们保存为 councils.free——这是一个一等 councils 配置原语，采用可避免冲突的 free-* 别名进行初始化。你的 config.default 不会受到影响，只需一个 OPENROUTER_API_KEY 即可。

可在任何能够运行评议会的地方使用：

amicus fanout --council free --prompt "Review this design"

amicus_fanout MCP 工具使用相同的 council 参数，而 second-opinion 技能会自动读取 councils.free。如果某个成员被移出目录，系统会发出警告并将其剔除——只要仍有至少 2 个成员，评议会就会继续运行。免费模型受到速率限制，质量也不稳定；有些模型除非你在 openrouter.ai/settings/privacy 启用数据共享，否则会返回 404。

Council 预设

使用 amicus council save <name> --models a,b,c 保存自定义的命名成员列表（至少 2 个可解析的别名或 provider/model ID），然后在任何支持运行 Council 的地方通过 --council <name> 运行。amicus council list 会显示已保存的预设，以及 3 个无需任何设置即可使用的内置阵容：free（即上文所述的同一动态零成本选择；如果你尚未设置 councils.free，就会使用它）、budget（经济实用型成员，每个厂商系列各 1 个）和 frontier（高端旗舰成员，每个厂商系列各 1 个）。amicus council show <name> 会解析这些预设（已保存或内置），并报告当前可用的成员。已保存的 Council 始终优先于同名内置预设——这与向导设置 councils.free 的方式完全相同。

策略包（v4.5）

Council 预设只保存阵容。策略包会将整次运行的配置——阵容、主持人、批评者/视角、成本/超时选项和简报模板——保存为一个可分享的命名 JSON 文件：

amicus pack save review-bench --kind council --bench gemini,deepseek,gpt --chair opus --timeout 20 --max-cost 2
amicus council run --pack review-bench --prompt-file plan.md --json

你在第二行同时输入的任何标志，只会覆盖对应的值——策略包只会填入你未明确指定的内容，无论如何，这些内容都会记录在本次运行中。fanout/start 和 amicus_fanout/amicus_start/amicus_council_run MCP 工具都可以使用策略包。使用 amicus pack list/show/rm 管理策略包；使用 --from-run <id> 可根据你已经满意的一次运行创建策略包，无需手动输入任何标志。完整参考：docs/usage.md § 策略包。

任务模式（v4.9）

Council 默认执行审查。amicus council run --intent task --prompt-file brief.md——或在 amicus_council_run MCP 工具中设置 intent: 'task'——会将同一条流水线用于开放式工作：每个席位都会生成简报要求的分析、答案或产物；评审者会对哪份回复完成了这项工作进行排名，并裁定每份回复所声明的主张；主持人则会综合得出一个答案——Converged | Split | Insufficient，而不是审查结论。这两种量表没有共同值，因此任务运行绝不会报告 Ship it，审查运行也绝不会报告 Converged。任务运行不会向可靠性账本写入任何内容（其中的排名衡量的是观点一致，而非缺陷确认），并会在原本可能显得空白的界面上说明这一点；审查运行与之前逐字节完全相同。完整参考：docs/council.md § 任务模式。

简报模板（v4.5）

--template <name> --artifact <file>（以及可重复使用的 --var k=v）会在发送前渲染 {{prompt}}/{{artifact}} 风格的 Markdown 模板；start/fanout/council run 均可使用。模板存放在 ~/.config/amicus/templates/ 中，而策略包的 briefing.template 是将模板用于 MCP 调用的运行的方式（MCP 没有自己的模板参数）。使用 amicus template list|show 管理模板；v4.5 内置了一个模板：review。完整参考：docs/usage.md § 简报模板。

---

快速开始

两种安装渠道——请先阅读。 Amicus 提供两种安装方式，两者的 CLI 命令有所不同：

• npm 全局安装（npm install -g amicus 或安装脚本）——推荐方式。 将 amicus/am 添加到你的 PATH，因此本 README 中的每个 amicus <command> 示例都可以按原样使用，并会配置并行窗口运行所需的 Electron GUI。
• Claude Code 插件（/plugin install amicus@bourbondog-amicus）不会将 CLI 添加到你的 PATH。CLI 调用需改用 npx -y amicus@latest <command>——例如，将 amicus doctor 改为 npx -y amicus@latest doctor。作为交换，插件渠道会提供 npm 不提供的两项功能：斜杠命令 /amicus:council 和 /amicus:sidecar。这两项功能仅限插件渠道——npm 用户无法使用，不过可以通过说“council review this”或直接与 Claude 对话来使用相同的技能。

完整的取舍对比请参见下方的对比表——简而言之，交互式窗口需要 npm 安装，而且两种方式可以并行安装。

本 README 通用约定： 插件渠道用户请在 CLI 示例前加上 npx -y amicus@latest（不要直接使用 amicus/am）。此处不会为每种渠道分别重复代码块——记住这条说明即可。

1. 安装

每种安装方式都会提供 MCP 服务和两项技能，其他功能则有所不同：

	npm / 安装脚本	Claude Code 插件
amicus / am 位于你的 PATH 中	✅	❌ — 每次调用都需使用 npx -y amicus@latest <command>
交互式 Electron 窗口（amicus start、watch --ui）	✅ 安装时配置	⚠️ 尽力提供 — 详见下文
GUI 出现故障时自动修复（amicus doctor --fix）	✅	❌ 没有可用于运行该命令的 CLI
MCP 服务 + 两项技能	✅	✅
斜杠命令 /amicus:council、/amicus:sidecar	❌	✅

---

使用 npm 安装——推荐

标准安装方式，可获得完整的交互体验（需要 Node.js ≥ 22.12）：

npm install -g amicus

除非你特别需要插件的斜杠命令，否则请选用此方式。它会将 amicus/am 添加到你的 PATH——并行窗口正是由此驱动；安装后脚本还会配置 Electron GUI。如果之后出现问题，可使用 amicus doctor --fix 就地修复。

使用安装脚本

效果与 npm 相同，一条命令即可完成——适用于 macOS、Linux 或 Windows（需要 Node.js ≥ 22.12）：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/BourbonDog/amicus/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/BourbonDog/amicus/main/install.ps1 | iex

作为 Claude Code 插件

如果你使用 Claude Code，这是最原生的注册方式，也是唯一支持斜杠命令的方式：

/plugin marketplace add BourbonDog/amicus
/plugin install amicus@bourbondog-amicus
/reload-plugins

Claude Code 会为你注册 MCP 服务和两个技能，无需任何配置。你还可以使用 /amicus:council（运行完整的评审）和 /amicus:sidecar（将对话分叉到另一个模型），而 npm 安装方式不支持这两个命令。

选择此方式前，请了解其中的取舍。 插件不会将 amicus 添加到 PATH，因此每次 CLI 调用都要通过 npx -y amicus@latest <command> 执行，包括打开交互式窗口的命令。插件也会跳过 amicus 的 postinstall，而 postinstall 负责安装并自动修复 Electron GUI。如果 Electron 下载到了 npx 缓存中，窗口仍可正常使用，Claude Code 运行评审时也仍会自动打开 Council Workspace；但如果 Electron 没有下载到缓存中，就不会有任何机制修复它，而且每次发布新版本都会解析到新的缓存目录。如果你想把并行窗口作为日常工具，请通过 npm 安装。

（另外，首次调用 council/sidecar 时会下载 OpenCode 引擎。）

可以同时使用这两种方式——如果你既喜欢斜杠命令，又需要窗口，这正是你想要的组合。通过 npm 安装 CLI 和 GUI，然后添加插件以使用 /amicus:council。你的配置、API 密钥和会话历史记录都保存在两种安装方式之外，并会自动共享。

需要注意的是：MCP 服务只会注册一次，名称为 amicus，因此它只会指向一个安装副本——即最近注册的那个，通常是插件的 npx -y amicus@latest mcp。这不会造成问题（两者提供相同的工具），但 CLI 运行的副本和 Claude 的 MCP 工具运行的副本可能不同。amicus doctor 会明确报告 MCP 的启动路径，--fix 会就地修复该副本。因此，如果 GUI 或引擎问题只在 Claude 中出现、而终端中没有出现，首先应检查这一点。

对于 npm 和 安装脚本安装方式，postinstall 会自动配置所有内容，无需手动注册：

• 在 Claude Code 和 Claude Desktop / Cowork 中注册 MCP 服务，以便原生使用 Amicus 工具。
• 将两个技能安装到 ~/.claude/skills/——second-opinion（评审）和 sidecar（聊天技能）。

跳过了 postinstall？ 使用 --ignore-scripts 进行的 npm 安装不会运行它，而插件渠道会按设计跳过它（Claude Code 会自行注册插件的 MCP 服务和技能）。无论哪种情况，你都可以随时运行 amicus init（插件渠道：npx -y amicus@latest init）按需（重新）注册；例如，也可以配置 Claude Desktop，而插件安装方式不会处理它。请参阅 amicus init。

---

2. 配置——不要跳过这一步

⚠️ 仅完成安装还不够。运行此命令，否则一切都无法正常工作。

Amicus 没有自己的 API 密钥——它会调用你在 OpenRouter、Google、 OpenAI、Anthropic 或 DeepSeek 的账户。在添加至少一个密钥之前，每个 council 和每个 侧车都会在首次模型调用时失败。很多人会跳过这一步。

amicus setup
# plugin-only install (no CLI on PATH):
npx -y amicus@latest setup

一个密钥就足以开始使用。 OpenRouter 通常是首选—— 一个密钥即可访问目录中的所有模型，因此无需注册四个不同的账户，就能组建混合供应商的 council。

这会打开一个图形化向导：

步骤	功能
1. API 密钥	输入 OpenRouter、Google、OpenAI、Anthropic 和/或 DeepSeek 的密钥。系统会实时通过供应商的 API 验证每个密钥。密钥将以 0600 权限写入 ~/.config/amicus/.env。
2. 默认模型	从可搜索的实时选择器（由模型目录提供支持）中选择常用模型——每个供应商卡片还允许你深入选择具体模型，而不只是选择默认模型系列。在省略 --model 时使用此模型。
3. 模型路由	选择各个模型由哪个供应商提供服务——例如，让 Gemini 通过 Google 的直接密钥路由，其他所有模型则通过 OpenRouter 路由。
4. 检查	确认配置后再保存。

**无头环境：**如果 Electron 无法打开窗口，向导会改为在终端中运行基于 readline 的设置流程。

确认设置已生效——这是最快的确认方式：

amicus doctor

所有项目都显示绿色（0 error(s)），表示密钥、目录、引擎、技能和 MCP 注册都已就绪。如果有任何项目显示红色，运行 amicus doctor，它会准确告知你接下来要做什么。

---

3. 你的第一个 council

无需学习任何标志。在 Claude Code 或 Cowork 中，给 Claude 一份文档并说：

请对这份文档进行 council 审查

使用插件频道的用户也可以直接输入 /amicus:council，而不必把它说成请求——调用的是同一项技能，只是显式触发。

Claude 会准备材料、推荐模型阵容、说明运行方式和费用，并协调后续流程。最后由你决定接受还是拒绝。（second-opinion 技能会教 Claude 识别这一请求——如果没有任何反应，请运行 amicus doctor（或 npx -y amicus@latest doctor）。通过 npm/安装脚本安装时，技能位于 ~/.claude/skills/second-opinion/；通过插件安装时，技能保留在插件内部——在 Claude Code 中检查 /plugin，确认 amicus 已启用。）

4. 你的第一个侧车

侧车提供更底层的使用方式——你也可以通过 Claude 说出短语来调用它，但 CLI 会直接提供这些标志：

amicus start --model gemini --prompt "Fact-check the auth approach Claude just proposed"

编辑器旁边会打开一个窗口，其中已准备好 Gemini，并预先载入你的对话。与它协作，然后将摘要折叠回来。

更新

Amicus 每 24 小时最多检查一次 npm 注册表（后台缓存检查）。有可用更新时，CLI 会打印通知，Electron 工具栏也会显示一个可一键点击的更新横幅。你也可以自行运行：

amicus update

从 GitHub 安装

npm 包是主要安装方式。如果要直接从仓库安装——postinstall 的运行方式完全相同（注册相同的 MCP 和两项技能）——只需确保 git 位于你的 PATH 中：

npm install -g github:BourbonDog/amicus

完整的前置要求列表请参阅要求与依赖项。

贡献者设置

要克隆 Amicus 并参与开发？请参阅 CONTRIBUTING.md，了解开发环境设置、Git 钩子配置和测试命令。

---

要求与依赖项

首次运行前需要准备的内容，以及可选项。

运行环境

• Node.js ≥ 22.12 — 运行 node --version 检查。这是唯一硬性运行环境要求。
• 正在运行的 Claude Code 或 Cowork 会话 — Amicus 由 Claude 编排，并非独立聊天机器人。

安装方式与 git 工具链

• 从 npm 注册表安装（推荐）： npm install -g amicus。无需构建工具链 — 软件包已附带预构建内容。
• 从 GitHub 安装： npm install -g github:BourbonDog/amicus 的运行方式完全相同 — MCP 注册、两个技能和 postinstall 都相同。唯一额外要求是 PATH 中有可用的 git，因为 npm 会克隆仓库来安装（运行 git --version 检查）。

模型 API 密钥 — 至少需要一个

• OpenRouter 用一个密钥即可支持最多模型，也可以使用 Google / OpenAI / Anthropic / DeepSeek 的直接密钥。使用 amicus setup 或 amicus key <provider> <key> 添加；密钥存放在 ~/.config/amicus/.env。支持的环境变量包括 OPENROUTER_API_KEY、GOOGLE_GENERATIVE_AI_API_KEY（仍接受旧版 GEMINI_API_KEY）、OPENAI_API_KEY、ANTHROPIC_API_KEY 和 DEEPSEEK_API_KEY。
• 或者完全跳过云端密钥，以 $0 的成本在本地运行。 将 Amicus 指向已在本机运行的 OpenAI 兼容服务 — LM Studio、Ollama 或 vLLM — 即可无需 API 密钥，也无需按 token 付费：amicus provider add lmstudio --preset lmstudio（LM Studio）、--preset ollama（Ollama）或 --preset vllm（vLLM）。请参阅 amicus provider。
• ⚠️ OpenRouter 密钥需要购买额度。 全新且额度为零的密钥可以通过 setup 的实时验证，但首次实际调用时会在运行期间因 402 错误而失败。运行 council 前，请先购买少量额度。

Electron — 可选（仅 GUI）

• Electron 是可选依赖项，用于图形化设置向导和并行 sidecar 窗口。无头运行和完整 council 均无需 Electron — 如果未安装 Electron 或无法打开窗口，amicus setup 会改用 readline 向导，sidecar 则以无头模式运行。amicus doctor 会准确报告 Electron 是否存在，绝不会将其缺失视为致命问题。

OpenCode 引擎

• 捆绑的 opencode-ai 引擎（对话运行时）会作为普通依赖项自动安装 — 无需单独安装。它自己的 postinstall 会部署约 11 个适用于不同平台的二进制文件；如果这一步发生暂时性故障（spawn ENOENT 或防病毒软件锁定文件），原子安装可能会回滚。如果安装中途失败，或 amicus doctor 报告找不到 OpenCode 二进制文件，只需重新运行 npm install -g amicus（如果问题持续，先清除缓存：npm cache clean --force）。

操作系统支持

• Windows 11、macOS 和 Linux 均受支持；Amicus 对 Windows 提供一等支持（在 Windows 上开发和测试，无需 WSL）。平台相关信息请参阅 Windows 一节。

运行成本。 一个 sidecar 只会调用一次模型。一次完整 council 通常会进行 约 5–8 次付费模型调用（例如，2 轮扇出中有 3 位评审，再加 1 位主席）。每次 council 运行前，Amicus 都会显示费用估算，并通过内置预算门槛拒绝使用超昂贵模型（o3-pro 级别），除非你使用 --no-cost-gate 选择加入。你直接向服务提供商支付 token 费用；Amicus 本身免费且开源。

并行窗口

当你不需要完整的议事团，只想听听另一个模型的看法时，可以分叉一段对话。Amicus 会提取你当前的 Claude Code 上下文，打开一个预先加载该上下文的会话，你可以与它并肩工作，完成后再将结构化摘要折回 Claude 的上下文中。

交互模式（默认）： 编辑器旁边会打开一个真实窗口。使用模型切换器在对话中途切换模型，然后点击 FOLD 按钮（或按 Cmd+Shift+F）生成摘要。使用 --fold-shortcut 自定义快捷键。

无头模式（--no-ui）： Agent 会自主工作，并在完成后输出折回摘要，非常适合测试生成或文档编写等批量工作。搭配 --json 可生成机器可读的运行文档。

折回交接的实际工作方式。 折回是摘要交接，不是实时交还——折回后，侧边栏模型的上下文就会消失。具体来说：点击 FOLD 会要求模型生成结构化摘要，然后将摘要作为带有 [SIDECAR_FOLD] 标记的区块写入 Electron 进程的标准输出；启动 Electron 的 amicus 运行器会捕获该标准输出，并将其保存为会话的 summary.md（位于会话目录中，与 metadata.json 和 conversation.jsonl 并列）。结果不会自动推送给你——你的编排 Agent 会在收到请求后，通过 amicus read <taskId>（CLI）或 amicus_read MCP 工具获取摘要。两种方式返回的摘要都会用 <untrusted_sidecar_output> 围栏包裹，因为它是来自另一个模型的文本，会进入你的上下文，因此应将其视为数据，而非指令。

上下文共享。 对话历史会自动传入。可通过以下选项调整：

• --context-turns <N> — 要包含的对话轮数上限（默认值为 50）。
• --context-since <duration> — 时间范围（例如 2h）；优先于轮数设置。
• --context-max-tokens <N> — 上下文大小上限（默认值为 80000）。
• --no-context — 完全跳过父级历史记录。

MCP 继承。 Amicus 会发现你的 Claude Code 会话使用的 MCP 服务，并将它们传递过去，因此分叉出的模型也能使用与你相同的工具。可通过以下选项控制：

• --no-mcp — 不继承任何父级 MCP 服务。
• --exclude-mcp <name> — 移除指定服务（可重复使用）。
• --mcp <name=url|name=command> — 添加一个服务。

安全性。 Amicus 会针对文件冲突（会话运行期间文件被外部修改）和上下文偏移（共享上下文可能与当前会话相比已过时）发出警告，因此折回操作绝不会悄悄覆盖较新的工作。

---

命令

命令	功能
amicus start	启动新会话（交互式或使用 --no-ui）。
amicus fanout	并行运行 N 个模型处理同一提示词（无头模式）。
amicus list	显示之前的会话 — 显示启动时设置的 --tag <t>，--search <q> 用于筛选，--limit <n> 限制行数，--all 则涵盖所有已知项目（Council 运行仅限当前项目 — CLI 会在表格中说明）。
amicus resume	重新打开之前的会话并保留完整历史记录。
amicus continue	基于之前的会话开启新会话。
amicus read	输出会话摘要 / 对话 / 元数据。
amicus status <id>	一次性查看会话或扇出波次的状态（人类可读格式或 --json；也可使用替代写法 --wave <id>）。
amicus watch <id>	从任意终端实时渲染扇出波次、Council 运行或会话，直至结束 — 在 TTY 上显示原地更新的表格，使用 --plain 输出里程碑行，或使用 --json 输出 NDJSON；退出代码对应终止状态。使用 --ui 则会打开 Council Workspace 窗口（仅限交互式，不支持 --json）。
amicus models	列出、搜索、刷新目录或审查别名。
amicus aliases	管理你的模型别名 — 关注 / 固定；--review 用于查看更新提议，--ui 可在设置窗口中执行相同操作，--unpin <name> 可取消固定，--json 供脚本使用；--review --owner（维护者）用于审查随附的固定项；执行任何命令后，如果有待处理的更新，每天会通知一次；此外还会每周在后台刷新目录（aliasReview.autoRefresh: false 可同时关闭这两项功能）。
amicus doctor	诊断你的设置 — 密钥、默认模型、目录、别名、随附的固定项、OpenCode 二进制文件、Electron、技能、MCP 注册、OpenRouter 额度（支持 --json；--fix 会自动修复可处理的问题）。
amicus spend	汇总支出账本中的跨运行费用，并按运行归属 — 总支出及各模型支出、Token 数和来源分布，按费用从高到低排列（--wave/--council/--project/--model/--op/--failed 用于筛选，--group-by 用于分组，--since 7d 用于设置时间范围；--json 输出带版本信息的文档；配置密钥后会显示剩余的 OpenRouter 额度）。
amicus key	以非交互方式管理 API 密钥：amicus key <provider> <key> 会在实时验证后保存；--remove 用于移除；直接运行 amicus key 可列出提供商。
amicus provider	添加 / 列出 / 测试 / 移除本地 OpenAI 兼容提供商（LM Studio、Ollama、vLLM）— 使用 --preset 或 --url 进行配置，边际费用为 $0（每个子命令都支持 --json）。
amicus council	Council 运算：tally <input.json>（确定性分级 + 追加账本），stats（审查者可靠性），report <verdict.json> [--md|--html]，validate <file>（检查 findings 区块，退出码为 0/2/1），verdict <tally.json> [--decisions <d.json>] [-o <out.json>]（生成并写入 verdict.json）。预设：save <name> --models a,b,c、list [--json]、show <name> [--json] — 内置的 free/budget/frontier 测试组请参阅 Council 预设。
amicus council run	无头 Council 引擎：在一条命令中执行 Stage-1 审查 → 匿名交叉审查 → 确定性计票 → 非 Claude 主席裁决，无需 Claude 运行时。添加 --debate 可进行 Stage-2.5 反驳轮次（提出异议者进行辩护 / 修订 / 撤回，有争议的裁决者重新投票）；添加 --claude-review <file> 可将 Claude 自己的审查作为编号为 N+1 的评审纳入裁决。会写入一个运行目录，其中包含 verdict.json（包括 overallVerdict）和 report.html — 详见 docs/council.md。
amicus pack	保存完整的运行配置 — 测试组、主席 / 批评者 / 视角、选项、简报模板 — 并按名称调用：save <name> --kind council|fanout|solo [flags]（或 --from-run <id>）、list、show <name>、rm <name>。在 start/fanout/council run 中使用 --pack <name> 加载配置；显式标志始终优先。详见 docs/usage.md § Policy packs。
amicus template	使用 list/show <name> 列出 / 查看简报模板。在 start/fanout/council run 中使用 --template <name> [--artifact <file>] [--var k=v]，可在发送简报前渲染模板。详见 docs/usage.md § Briefing templates。
amicus abort	中止正在运行的会话（或使用 --all 中止全部会话）。
amicus setup	配置默认模型、API 密钥和别名。
amicus update	更新到最新版本。
amicus mcp	启动 MCP 服务（stdio 传输）。
amicus init	按需重新运行技能安装和 MCP 注册 — 使用 --claude/--desktop 指定范围，使用 --json 查看各步骤状态。适用于插件渠道 / --ignore-scripts 安装（此类安装会跳过 npm postinstall）、postinstall 失败，或修复已删除的 ~/.claude 状态。
am 别名在所有地方都可与 amicus 互换。

所有标志、所有子命令、所有示例——包括完整的 amicus start 选项表、amicus fanout（支持 --session-id、--council <name> 作为 --models 的替代选项）、council 预设和所有其他命令——都位于权威 CLI 参考文档 docs/usage.md 中。以下内容仅用于让你了解一次运行的大致情况。

amicus status <id> 的输出。人类可读格式：

$ amicus status demo123
Task:     demo123
Status:   complete (terminal)
Elapsed:  5m 0s
Model:    google/gemini-2.5-flash

--json：

$ amicus status demo123 --json
{
  "taskId": "demo123",
  "status": "complete",
  "elapsed": "5m 0s",
  "version": "4.14.3",
  "model": "google/gemini-2.5-flash",
  "phase": "terminal"
}

amicus list --status 支持 running、complete、error、timed-out、aborted、crashed、idle-timeout。行中包含 TAG 列（通过启动时的 --tag <t> 设置）；--search <q> 按 id/tag/briefing 子字符串筛选，--limit <n> 限制行数（0 = 不限），--all 则列出所有已知项目中的运行记录（council 运行仍限定在当前项目中——目前没有跨项目索引，列表会对此予以说明）。逐字段的完整文档（包括运行中会话的 messages/STALLED 报告、wave-ID 状态格式等）请参阅 docs/usage.md。

---

模型

Amicus 不会附带固定的模型名称表。别名解析和验证依赖从提供商 API 获取并缓存在 ~/.config/amicus/model-catalog.json 中的实时目录（TTL 为 24 小时；无需 API 密钥即可获取）。运行 amicus models，即可查看在你的机器上实际解析出的内容——这才是权威信息，而不是本 README。

amicus models                 # list the catalog
amicus models --search gemini # filter by substring

start/fanout 会在启动前根据目录验证模型（使用 --no-validate-model 可跳过）。你也可以随时绕过别名，直接传入完整模型 ID——裸 provider/model（规范格式）或 openrouter/provider/model（显式覆盖）；请参阅下文的路由部分。目录内部机制、别名管理和完整 ID 直通表见 docs/usage.md § Models。

路由

• 裸 provider/model（例如 openai/gpt-5.5、anthropic/claude-opus-4-8、google/gemini-3.6-flash）是规范的策略路由格式——Amicus 会优先采用直接路由：配置了直接提供商密钥时使用该密钥；只有 OpenRouter 密钥时则自动回退到 OpenRouter。
• openrouter/provider/model 是显式覆盖格式，即使存在直接密钥也始终强制使用 OpenRouter——请有意选择此格式，或用于没有直接集成的仅网关供应商（Qwen、Grok、Mistral、GLM 等）。
• --gateway auto|direct|openrouter（CLI 和 MCP 工具均支持）可覆盖单次调用的路由；auto 是优先直接路由的默认值。config.json 中的 routing.prefer（默认值为 "direct"，也可设为 "openrouter"）用于设置全局默认值。
• 一次性迁移提示：如果你同时持有 OpenRouter 密钥和某个供应商的直接密钥，那么在auto 路由（默认值）下，首次解析到该供应商的启动操作会显示一次性提示，告知路由已切换为直接 API；设置 routing.prefer: "openrouter" 可恢复此前全部使用 OpenRouter 的行为。显式传入 --gateway direct 时不会触发该提示——这是你的主动选择，而非迁移。

完整详情、API 密钥/前缀表和迁移提示请参阅 docs/configuration.md。

---

MCP 集成

安装后会自动注册 MCP 服务（Claude Code 和 Claude Desktop / Cowork）。它提供以下工具：

工具	功能
amicus_start	启动会话；立即返回任务 ID。
amicus_status	轮询任务（或一波扇出任务）是否完成。
amicus_wait	在一次工具调用中阻塞，直到会话/任务波次完成或等待窗口关闭。
amicus_read	读取结果：摘要、对话、元数据或 JSON。
amicus_list	列出过往会话（tag 字段；search 按 ID/tag/简报子字符串筛选）。
amicus_resume	重新打开会话。
amicus_continue	在先前会话的基础上启动新会话。
amicus_abort	停止正在运行的会话。
amicus_setup	打开设置向导。
amicus_guide	返回使用指南（模型选择、简报、轮询）。
amicus_fanout	启动一波使用相同提示词的任务；返回 { waveId, taskIds[] }。
amicus_council_tally	汇总评审团任务波次的评审结果，并生成评分。
amicus_council_stats	根据以往评审团运行结果统计评审者的可靠性。
amicus_verdict	根据评分和决策生成最终评审团裁决；当提供 render:true 和 outDir 时，会写入 <outDir>/report.html。
amicus_council_run	运行完整的无头评审团引擎（第一阶段评审 → 匿名交叉评审 → 评分 → 主席裁决）；异步返回 { runId, runDir }。
amicus_spend	只读地汇总跨次运行的费用，数据来自支出账本（与 CLI amicus spend 的标志参数一致）。

异步模式为 启动 → 状态 → 读取：amicus_start/amicus_fanout 会立即返回，随后轮询 amicus_status 并调用 amicus_read；amicus_wait 则将轮询循环合并为一次阻塞调用。

旧版 sidecar_* 工具名称已在 v2.0.0 中彻底移除——现在仅存在 amicus_* 工具。AMICUS_LEGACY_ALIASES=1 是从 v1.8.0 选择启用开关遗留下来的空操作。请参阅 docs/SHIMS.md。

手动注册方式和各工具详情请参阅 docs/usage.md § MCP Server。

---

配置

推荐使用 amicus setup 配置 Amicus——它会将 API 密钥写入 ~/.config/amicus/.env（0600），并保存默认模型及其别名。所有环境变量（API 密钥、行为调优、无头轮询器、GUI/调试、进程生命周期）均记录在 docs/configuration.md 中。v2.0.0 已彻底移除旧版 SIDECAR_* → AMICUS_* 环境变量映射；移除记录和重命名表请参阅 docs/SHIMS.md。

想了解磁盘占用情况？ 配置目录树中每个文件的内容、会话存储布局、日志的写入位置（以及是否写入）、config.json 的确切结构，以及完整的卸载说明，均可在 docs/configuration.md § Where things live 中找到。

---

JSON 输出

使用 --json 时，Amicus 会在标准输出中生成稳定且带版本的运行/任务波次文档，供脚本和 Agent 使用：

{
  "taskId": "...", "model": "...", "modelInput": "...", "agent": "...",
  "status": "complete", "summary": "...", "error": null,
  "createdAt": "...", "completedAt": "...", "durationMs": 0
}

fanout 的任务波次文档结构、字段含义和完整的退出代码表请参阅 docs/usage.md § JSON Output。每份 --json 文档也都配有已发布的 JSON Schema——请参阅 docs/schemas.md（随 npm tarball 一同发布，位于 schemas/ 下）。

---

Windows

Amicus 在 Windows 上具备一等支持——在 Windows 11 上开发和测试，无需 WSL。

大多数与 Claude 相关的工具都假定运行于 macOS/Linux；Amicus 则不然。

• 完整的单元测试套件在 Windows 11 上通过。
• 原生二进制文件的 PATH 处理可在 Windows 下正确解析 OpenCode 二进制文件。
• 会话路径编码由原生方式处理（已考虑到会导致简单 ~/.claude/projects 查找出错的 Claude 项目路径编码）。
• 对于较长的简报，--prompt-file 可绕过 Windows 命令行参数约 32 KB 的长度上限。

---

故障排除

先运行 amicus doctor——它会一次性检查密钥、目录、OpenCode 二进制文件、Electron、技能和 MCP 注册情况，并针对任何失败项打印相应的修复方法。对于下文未涵盖的问题，或需要对这些项目进行更深入的诊断，请参阅 docs/troubleshooting.md。

症状	可能原因	修复方法
执行 "council review this" 没有任何反应	未安装 second-opinion 技能	检查 ~/.claude/skills/second-opinion/SKILL.md 是否存在；重新运行 npm install -g amicus（postinstall 会安装这两个技能）
npm install -g amicus 因 EEXIST: … claude-sidecar 失败	旧的上游 claude-sidecar 包仍全局安装；npm 不会覆盖其他包的 bin 启动脚本	执行 npm uninstall -g claude-sidecar，然后执行 npm install -g amicus。你的密钥和过往会话不会丢失，但 v2.0.0 不再自动读取旧路径——一次性迁移步骤请参见 docs/SHIMS.md（重命名 ~/.config/sidecar/ 和任何 .claude/sidecar_sessions/ 目录）。
安装中途失败，或 amicus doctor 报告找不到 OpenCode 二进制文件	OpenCode 引擎自身的 postinstall 过程中出现暂时性错误（spawn ENOENT，或安装其 11 个各平台二进制文件时被杀毒软件锁定文件）可能导致整个原子安装回滚——通常重试即可成功	重新运行 npm install -g amicus 即可。如果仍然失败，请先清理缓存：npm cache clean --force && npm install -g amicus。
401 / 身份验证错误	模型供应商没有可用密钥——裸 provider/model ID 会自动回退到 OPENROUTER_API_KEY，因此这表示直连密钥和 OpenRouter 密钥都未配置（或 --gateway direct/openrouter 强制使用的网关缺少密钥）	运行 amicus setup，或运行 amicus key <provider> <key> 添加缺失的密钥；参见路由。
首次调用 council review / start / fanout 时出现 402 / "Payment Required"	你的 OpenRouter 密钥有效，但没有额度。保存密钥（amicus key openrouter <key> 或设置向导中的密钥步骤）只会检查密钥是否通过身份验证——不会检查余额，因此零额度密钥也能顺利保存，只会在之后首次实际调用模型时失败。（amicus council 子命令本身执行的是确定性数学运算，从不调用模型。）	在 openrouter.ai/credits 充值，或切换到零成本 council：运行 amicus setup → 选择选项 2（Free OpenRouter council），即可用实时的 :free 后缀模型创建并保存为 councils.free——然后运行 amicus fanout --council free …。参见上文的免费 council（零成本）。
所有直连的 anthropic/… 模型（haiku、sonnet、opus、claude）在约 2 秒内、消耗 0 个 token 时均报错 Not Found，但同一模型通过 openrouter/anthropic/… 可以正常使用	继承自主机的 host 格式 ANTHROPIC_BASE_URL（缺少 /v1）——这是 Anthropic-SDK 的约定，而非 OpenCode 的约定；由 Claude Code 启动的 shell 会替你设置该变量。从 v4.6.2 起，amicus 会自动将其规范化为 <value>/v1（provider 配置覆盖，且只会在 stderr 上提示一次）——模型 ID、别名和密钥一直都不是问题，现在 URL 也不是，除非设置了 AMICUS_BASE_URL_NORMALIZE=0 或路径不标准。	现在应该会自动修复——通过 amicus doctor 的 anthropic-base-url 行确认（该行会显示检测到的值及其处理方式）。仍然失败：如果设置过 AMICUS_BASE_URL_NORMALIZE，请取消设置；或运行 export ANTHROPIC_BASE_URL=https://api.anthropic.com/v1 / 取消设置该变量 / 传入 --gateway openrouter。在 council 中，失效的席位会导致运行降级，而不是使其失败——付费运行 council 前，先用一次临时的 amicus start 对每个席位进行冒烟测试。参见 docs/troubleshooting.md。
对一个显然存在的模型显示 Model 'X' is unverified against the direct catalog; attempting anyway	这并不是说模型有问题——而是 amicus 无法验证。该供应商的直连目录获取失败（通常是存储的密钥过期或被截断），导致其命名空间为空；而空命名空间不会阻止启动。引擎仍可能从自己的凭据存储中运行该模型，因此可用的模型会一直显示警告。	运行 amicus models --refresh，并留意是否有供应商的目录一直为空；使用 amicus key <provider> <apikey> 重新保存有效密钥。参见 docs/troubleshooting.md。
找不到会话	没有与给定 ID 匹配的会话	运行 amicus list，或省略 --session-id 以使用最近的会话。
找不到对话历史记录	项目路径编码问题	检查 ~/.claude/projects/；项目路径中的 / 和 _ 在目录名中会编码为 -。
无头运行始终无法结束	任务超出了默认超时时间	调高超时时间：--timeout 30。
选取了错误的会话	多个活动会话导致解析结果不明确	显式传入 --session-id。
折叠摘要看起来已损坏	调试输出泄漏到 stdout	使用 LOG_LEVEL=debug 重新运行，查看正在打印什么。
模型未通过目录验证	缓存目录中没有该模型（模型已更名或缓存过期）	运行 amicus models --refresh，或使用 --no-validate-model 跳过验证。
fanout 以 2 退出	部分波次——至少有一个分支失败	阅读波次文档的 legs[]，检查每个失败分支的 status / error。
调试日志：

LOG_LEVEL=debug amicus start --model gemini --prompt "test" --no-ui

---

文档

文档	描述
docs/usage.md	完整的命令行和 MCP 参考：每个标志、每个子命令和每个示例。
docs/council.md	Council 工作流参考：tally/verdict/report 架构、来源信息和一个完整示例。
docs/schemas.md	所有 --json 文档（结果和 council 系列）的已发布 JSON Schema。
docs/configuration.md	完整的配置和环境参考。
docs/architecture.md	引擎、Electron 外壳和上下文共享如何协同工作。
docs/opencode-integration.md	Amicus 如何驱动 OpenCode 运行时。
docs/troubleshooting.md	详细的故障排除指南。
docs/electron-testing.md	用于 UI 测试的 Chrome DevTools Protocol 模式。
docs/testing.md	测试套件布局及运行方法。
docs/CITATIONS.md	如何引用另一个文件中的内容，以确保引用不会失效，以及引用检查机制会强制执行哪些要求。
docs/publishing.md	发布流程。
docs/SHIMS.md	v2.0.0 移除记录：关于品牌重塑前的 sidecar* 兼容性垫片——移除了什么，以及如何迁移。
skills/second-opinion/SKILL.md	LLM Council 技能。
skills/sidecar/SKILL.md	sidecar 聊天技能。
evals/README.md	用于 LLM 交互的端到端评测框架。

---

贡献

欢迎贡献。开发环境设置、Git 钩子配置和测试命令请参见 CONTRIBUTING.md。

自主 Electron UI 测试方法（通过 Chrome DevTools Protocol 驱动真实窗口）记录在 docs/electron-testing.md 中。

---

基于 OpenCode 构建

Amicus 是一个基于 OpenCode 构建的测试框架；OpenCode 是一款开源 AI 编码引擎。OpenCode 提供对话运行时、工具执行框架、Agent 系统和 Web UI。Amicus 增加了来自 Claude Code 的上下文共享、Electron 外壳、折叠/摘要工作流、会话持久化、并行扇出波次、多模型 council，以及多客户端支持（命令行、MCP、Cowork）。OpenCode 负责处理 LLM 交互中的复杂部分，让 Amicus 专注于 council 和并行窗口工作流。

---

署名与许可

Amicus 的灵感来自 John Renaldi 的 Claude Sidecar，并依据 MIT 许可证使用。原始版权声明（© 2025 John Renaldi）已完整保留在 LICENSE 中。引擎修改、多模型 council 和技能打包 © 2026 Christian Wagner，同样依据 MIT 许可证。完整署名信息请参见 LICENSE 和 NOTICE。

MIT。