e3d-pilot

e3d-pilot

多模型 AI 问题求解：独立回答 → 批判 → 收敛 → 人类决策 → 执行 → 评审 → 溯源。

e3d-pilot 是一个开源系统，可让多个 AI 模型共同解决同一个问题，而不是依赖单个模型的回答——从一次性提问，到经过人工把关并完整执行的软件变更。

上手很简单。让多个已配置的模型（Claude、Codex、Grok、Devin，或你接入的其他模型）回答同一个问题。让它们独立作答、查看并批判彼此的观点、修订答案、揭示真实分歧，并收敛到最有力的答案。这就是 bin/e3d-debate——一个独立工具，无需仓库或流水线。它也可作为 MCP 服务在编辑器中使用：通过 GitHub Copilot、Claude Code 或 Cursor 使用，只需一行 npx 命令。

接着，e3d-pilot 将这一理念延伸到实际的软件工作中：discover → ideate → approve → draft → negotiate → execute → review → publish → outcome。每一步都会记录在只追加的账本中，因此系统（或人类，或新的 AI 会话）之后可以还原某个想法的来源、影响过它的模型或人员、它产出了什么，以及之后发生了什么。

60 秒体验 e3d-debate

git clone https://github.com/spacepacket1/e3d-pilot.git
cd e3d-pilot

bin/e3d-debate \
  "Should e3d-pilot's provenance data be a graph, or is that over-engineering?" \
  --providers claude,codex --rounds 3

（任何 lib/providers/<name> 适配器都可以参与——如果你已配置 devin/grok-build/其他适配器，也可以将它们添加进来；大多数尝试此工具的人都已经配置了 claude/codex。）

第一轮：每个提供方独立作答。第二轮及之后：每个提供方都会看到其他提供方在上一轮的观点，并必须为其辩护、修订、反驳或让步。如果各方确实达成共识，辩论会提前结束；随后，综合器会读取完整记录并给出最终答案、共识以及任何仍然存在的分歧。

这个问题并非假设——我们确实以这种方式进行了一场辩论，以下内容摘自完整记录：

QUESTION
Should the E3D 3D graph generalize into a standalone product, or should
e3d-pilot instrument its own provenance instead?

CLAUDE (round 3, the only one to formally reach "approved")
Don't create e3d-graph yet — build a confidence-annotated, domain-neutral
provenance emitter inside e3d-pilot, prove attribution questions are
answerable from the data alone, add a 2D lens only if they are, and extract
a public repo only on external pull or paid demand.

CODEX (round 3)
Build outcome-linked Pilot provenance first, then open-source a narrow
standalone viewer only if measured workflow value and external pull
justify extraction.

DEVIN (round 3)
Instrument Pilot with a domain-neutral provenance schema from day one; gate
public extraction on the internal experiment succeeding, not on indefinite
deferral.

GROK-BUILD (round 3)
Do not ship standalone e3d-graph; instrument Pilot provenance first and
treat visualization as a 2D lens inside E3D.

SYNTHESIS
Do not ship a standalone e3d-graph product. Instrument e3d-pilot now with
an append-only, domain-neutral, confidence-annotated provenance schema —
the ledger stays canonical, the graph is an index, not memory. Validate by
answering real attribution questions from the data alone before any UI.

DISSENT (reported, not hidden)
Devin and partly Codex would gate public extraction on the internal
experiment succeeding; Claude and Grok-build require external pull or paid
demand instead — a real, named disagreement the tool didn't paper over.

**接下来发生了什么：**我们正是按此思路构建了工具，并用它验证了本仓库历史中的三个真实想法。三次结果都表明，“比手动阅读原始账本更有用”——其中一次还发现了提出该方案的规范中存在一个真实错误。之后，我们也以同样严谨的方式评估了图智能查询：一个明确胜出，两个因真实数据仍然过于稀疏而明确判定为“没有信号”——结果如实报告，没有夸大。完整过程（规范、真实项目中的验证结果，以及未奏效之处）见 docs/provenance-graph-experiment.md 和 docs/graph-intelligence-experiment.md。

**实验性功能：溯源图。**e3d-pilot 现在会从自身不可变的事件账本中推导结构化关系——包括想法、参与者、模型、决策、仓库、提交、证据和结果。我们正在测试这张图能否揭示仅凭原始账本难以发现的模式，并不声称它已经做到了这一点。

你无需使用 e3d-pilot 的其他部分，也可以单独使用 e3d-debate——完整的标志参考见下文的 e3d-debate。继续阅读，了解如何将辩论得出的答案转化为已交付、经过评审且有溯源记录的变更。

在 GitHub Copilot、Claude Code 和 Cursor 中使用 e3d-pilot（MCP）

e3d-mcp 是一个零依赖的 Model Context Protocol 服务。它让 AI 编码助手可以在任务进行中征求多个模型的第二意见，而不是直接采用某个模型给出的第一个答案。它以 e3d-pilot 的名称发布在 npm 上，并列入官方 MCP 注册表，条目为 io.github.spacepacket1/e3d-pilot。

工具	功能
e3d_debate	多个独立模型分别作答，由一个综合器给出明确答案、共识级别（full / majority / split）、任何具名异议，以及每个模型的最终立场，同时提供易读文本和结构化数据（dissent.present、dissent.summary、positions）。mode: "quick"（默认）只进行一轮，用时数秒；mode: "thorough" 会增加一轮评议，让模型相互反驳。完整对话记录需通过 include_transcript 选择启用。
e3d_list_providers	显示此机器上可用的模型提供商。辩论至少需要两个提供商。
e3d_provenance_trace	只读：追溯某项变更存在的原因，从其起源到辩论、批准、执行、审查和结果。
e3d_ideas_list	只读：列出 e3d-pilot 在仓库中追踪的想法，以便找到用于追溯的 ID。

以下是 quick 模式下的一次实际结果（耗时 11 秒，使用两个模型）。问题是：一个小型 CLI 默认应该使用扁平 JSON 文件还是 SQLite？

FINAL ANSWER: Default to a flat JSON file for a small CLI. It has no dependencies, is
human-readable and diffable, and is easy to hand-edit and debug. Write it atomically
(temp file, then rename). Move to SQLite once you need indexed queries, concurrent
writers, or data beyond a few MB.
CONSENSUS: split
DISSENT: Codex prefers SQLite as the default for any persistent mutable state because
it gives transactions, concurrency safety, and schema evolution at low cost.

出现分歧正是关键：你得到答案的同时，也能看到最有力的反方观点，而不是某个模型自信满满的猜测。

安装

VS Code（GitHub Copilot Agent 模式）：一键安装，或将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "e3d-pilot": { "type": "stdio", "command": "npx", "args": ["-y", "--no-update-notifier", "-p", "e3d-pilot", "e3d-mcp"] }
  }
}

Claude Code：

claude mcp add e3d-pilot -- npx -y --no-update-notifier -p e3d-pilot e3d-mcp

Cursor（~/.cursor/mcp.json）以及其他使用 mcpServers 格式的客户端：

{ "mcpServers": { "e3d-pilot": { "command": "npx", "args": ["-y", "--no-update-notifier", "-p", "e3d-pilot", "e3d-mcp"] } } }

任何能够启动 stdio 服务的 MCP 客户端都应该可以使用；以上分别是各客户端的标准格式。

**前提条件：**Node 18+、jq、bash 4+（macOS 自带 3.2：brew install bash jq），以及至少两个已登录的模型 CLI（例如 claude 和 codex）。一次性检查全部条件：

npx -y -p e3d-pilot e3d-mcp --doctor

--doctor 会报告缺少的内容以及修复方法。它不需要完整流水线中的 e3d-code 执行器（只会说明是否已安装）。从克隆的仓库中运行 bin/e3d-mcp --print-config --local，会打印指向当前检出目录的配置。

使用方法

在 Copilot Agent 模式（或任何客户端）中提问：*“在选择存储层之前，请针对这个 CLI 的 SQLite 与扁平 JSON 运行 e3d_debate。”*若要让助手在有争议的设计选择上主动执行此操作，请将 examples/copilot-instructions.md 复制到 .github/copilot-instructions.md 或 AGENTS.md。不要用它查询信息或回答显而易见的问题；它速度较慢，而且会产生费用。

费用与限制

• quick 辩论耗时数秒到一分钟，thorough 辩论耗时数分钟；两者都会消耗你自己的模型额度。服务通过 E3D_MCP_MAX_ROUNDS（3）、E3D_MCP_MAX_PROVIDERS（4）、E3D_MCP_MAX_CONCURRENT（2）和 E3D_MCP_TIMEOUT_SEC（900）限制 e3d_debate。
• 它会使用服务环境中已有的提供商 CLI 和密钥（参见 e3d-pilot providers list）。
• Copilot 的编码 Agent运行在 GitHub 托管的运行器上，这些运行器没有安装上述提供商 CLI。目前请使用上文介绍的本地（stdio）配置。

辩论中的网络搜索

每个辩论提示词都会注明今天的 UTC 日期。API 提供商（anthropic-api、openai-api、gemini-api、xai-api）也可以在辩论轮次中使用各自厂商的网络搜索工具。默认开启，此时问题文本可能会发送给搜索提供商。CLI 发言方、MCP 采样发言方和综合器都不会搜索；系统会告知它们无法访问网络。向 e3d_debate 或 e3d_debate_start 传入 web_search: false，或向 e3d-debate 传入 --web-search off，即可在单场辩论中关闭搜索。搜索结果会被视为不可信数据：有关各厂商允许的操作和剩余风险，请参阅 docs/web-search-providers.md；有关结果结构，请参阅 docs/web-search-interface.md。

变量	默认值	作用
E3D_DEBATE_WEB_SEARCH	on	off 是紧急关闭开关：无需修改代码即可彻底关闭所有搜索。任何其他值也会关闭搜索。
E3D_DEBATE_WEB_SEARCH_PROVIDERS	anthropic-api,openai-api,gemini-api,xai-api	允许执行搜索的提供商。除此四个以外的名称都会被忽略。
E3D_DEBATE_SEARCH_MAX_PER_CALL	3（1-10）	每次模型调用的搜索上限。Anthropic 和 OpenAI 原生支持此限制；这是 xAI 最接近的可用控制方式。所有厂商的搜索次数都会在事后检查，超限时会触发 ALARM。
E3D_DEBATE_SEARCH_MAX_CITATIONS	8（1-20）	每次调用保留的引用数。超出的引用会被丢弃并计数。
E3D_DEBATE_SEARCH_EXCERPT_CHARS	150（0-300）	每条引用保留的摘录字符数上限。0 表示不保留摘录。
E3D_DEBATE_SEARCH_ALLOW_DOMAINS	空	以逗号分隔的纯域名列表（example.com）。在厂商支持的情况下原生应用，并在所有场景下进行后置过滤。如果厂商只接受一个列表，则优先采用此列表。
E3D_DEBATE_SEARCH_DENY_DOMAINS	空	以逗号分隔的纯域名列表。尽可能原生应用，并在所有场景下进行后置过滤。
E3D_DEBATE_SEARCH_TIMEOUT_SEC	派生值	单次搜索调用的墙钟时间限制。默认值为辩论超时时间除以（2 x 轮数 + 1），且至少为 10 s；如果未设置辩论超时时间，则为 120 s。
E3D_MCP_DAILY_SEARCHES	0（不限制）	每个主体每日的网络搜索上限。运行辩论前会预留最坏情况下的搜索次数（上限 x 搜索调用次数）。
GEMINI_API_NATIVE_BASE_URL	https://generativelanguage.googleapis.com/v1beta	Gemini Interactions API 的端点，仅在 Gemini 执行搜索时使用。
OPENAI_API_SEARCH_CONTEXT_SIZE	low	OpenAI 搜索工具的 search_context_size。
ANTHROPIC_API_MAX_PAUSE_CONTINUATIONS	2（0-5）	搜索调用可以进行的 pause_turn 续接次数。超过此次数后会安全失败。

如果搜索调用失败、超时、使用了搜索以外的工具，或厂商禁用了搜索，系统会要求该模型在不使用搜索的情况下重新作答，并在答案中说明这一情况（“网络搜索不可用……”）。答案还会报告可执行搜索的模型数量（“M 个模型中 N 个已开启”）。

• e3d_debate 和只读工具绝不会写入代码仓库。下方的流水线工具会写入，但只会通过与用户手动操作时相同的受控 CLI 路径写入；e3d_pilot_propose 会写入代码仓库的 .e3d-pilot/ 账本。

在编辑器中运行流水线

状态（0.2.0）： 流水线工具和默认采样功能都是新增的。它们已通过脚本化 MCP 客户端和模拟提供商进行测试，但尚未在真实的 VS Code Copilot 会话中验证。除非设置 E3D_MCP_ALLOW_APPROVAL=1，否则无法在编辑器中批准操作；流水线工具也只会接触你允许的代码仓库。

除了辩论之外，e3d-mcp 还可以驱动由人工把关的流水线，让助手无需离开编辑器，就能从决策推进到 PR 草稿。这些工具调用的代码路径与用户手动操作时相同；它们不会重新实现任何阶段，也不会放宽任何关卡。

工具	费用	功能
e3d_pilot_config_check	免费	验证 .e3d-pilot/config.json，并报告是否已安装 e3d-code（编写代码的执行器）。
e3d_pilot_propose	免费	在仓库的记录簿中记录一个想法，并可附上 e3d_debate 结果作为来源证据。
e3d_pilot_start	消耗额度	以后台任务的方式启动 discover 或 ideate。（不提供 all：它会超出计划预览的范围。）
e3d_pilot_job_status	免费	查看任务状态、已达到的阶段、产物和日志末尾。任务保存在磁盘的 .e3d-pilot/mcp-jobs/ 下，服务器重启后仍会保留。wait_seconds 会等待任务完成。
e3d_pilot_approve	门禁	人工门禁 1。 默认只读：返回 waiting_for_human 和需要运行的确切命令（参见信任模型）。
e3d_pilot_reject	门禁	拒绝提议的想法。可在编辑器中确认，也可使用确切的 confirm_phrase 确认。
e3d_pilot_implement	消耗额度	对于已批准的想法：起草规格并由审阅者协商，然后在编写任何代码之前暂停。
e3d_pilot_code_plan	免费	显示 execute 将执行的操作：各个阶段、执行器和模型、涉及的文件、验证命令、预检结果。返回一个 plan_token。
e3d_pilot_execute	消耗额度并编写代码	需要针对该规格的有效 plan_token。在独立分支的隔离工作树中编写代码，执行验证和审阅，并创建一个草稿 PR。
e3d_pilot_cancel_paused	免费	放弃已暂停的实现（记录一次失败尝试及你的原因）。
e3d_pilot_request_changes	门禁	草稿 PR 创建后，将该想法退回修改。
e3d_pilot_artifact	免费	从固定列表中读取一次运行的一个产物（规格、协商日志、审阅结果、e3d-code 清单中的各阶段结果），并限制大小及对敏感信息进行脱敏。

Copilot Agent 模式下的完整流程

1. “我们需要本地持久化。运行 e3d_debate，比较 JSON 和 SQLite。” 随后会返回结论及异议。
2. “将它作为一个想法提出，并附上辩论结果作为证据。” e3d_pilot_propose 会将其记录为 proposed。
3. *（可选）*使用 e3d_pilot_start 依次运行 discover 和 ideate，让流水线为仓库本身寻找想法。
4. 由你批准（见下文）。在此之前，不会起草或编写任何内容。
5. “实现它。” e3d_pilot_implement 会起草并协商分阶段规格，然后暂停。轮询 e3d_pilot_job_status。
6. “向我展示计划。” e3d_pilot_code_plan 会列出各个阶段、所用模型、涉及的文件和验证命令。
7. 如果计划看起来合适：运行 e3d_pilot_execute。否则：运行 e3d_pilot_cancel_paused。执行结束后会创建一个草稿 PR，供他人审阅。
8. 无法通过 MCP 合并。 approve-merge 和 merge 刻意仅限命令行使用，因此最后一道门禁始终由使用终端（或 Web UI）的人把关。

信任模型

• Gate 1 由用户决定。 e3d_pilot_approve 不会默认批准。如果服务的操作员设置了 E3D_MCP_ALLOW_APPROVAL=1，并且编辑器支持 MCP elicitation，它会在编辑器自己的提示中询问用户；Agent 无法代替用户回答该提示。如果不满足这两个条件，它会返回需要运行的命令（e3d-pilot ideas approve ...），或者你也可以使用 Web 控制面板。
• 单独使用 confirm_phrase 只能防止意外（Agent 可以从错误消息中读到它），因此它并不是批准机制。reject 和 request_changes 接受它，因为这两项操作只会停止工作。
• CLI 会自行强制执行批准。 每个会修改内容的阶段都会在阶段内部检查与摘要绑定的批准，因此这里没有任何工具可以跳过批准。
• 仓库允许列表。 流水线工具只会操作 E3D_MCP_REPOS（以 : 分隔的列表）、客户端的工作区文件夹，或者在两者都不存在时，服务启动时所在的 Git 仓库。路径会经过符号链接解析，必须是 Git 仓库的顶层目录；任何超出范围的路径都会被拒绝。（最初的四个工具早于此机制，且不受影响。）
• 代码会写入单独的工作树，并使用每次运行各自的分支；同时遵守现有的 protected_paths、max_diff_files/max_diff_lines 上限及发布前验证规则。你的工作树不会受到影响。
• 日志、构件和错误都会经过密钥脱敏处理。

成本模型

• 工具描述会注明其属于 FREE 还是 SPEND MODEL CREDITS。code_plan 仅使用 e3d-code --list 和 --preflight，不会写入任何内容（特意避免使用 --dry-run，因为它会在清单中记录一个“已完成”的阶段）。
• 上限：每个仓库同时只能运行一个任务；所有仓库共用的 E3D_MCP_MAX_JOBS（2）；E3D_MCP_JOB_TIMEOUT_SEC（3600）；E3D_MCP_MAX_PHASES（8）；计划令牌会在 E3D_MCP_PLAN_TTL_SEC（1800）后过期，若规范或仓库的 HEAD 发生变化，也会失效。
• 目前仍没有每日或每会话支出上限，也没有成本报告。请将上述上限视为护栏，而非预算。

默认使用 Copilot 自带的模型

当客户端支持 MCP sampling（根据 VS Code 文档，VS Code 支持）时，e3d_debate 会将客户端自带的模型（Copilot）作为一个或两个辩论方，并加入它检测到的任何本机模型 CLI（claude、codex、gemini 等），而不再要求必须有两个 CLI。首次请求时，它会提示你授权服务使用你的模型；你可以在 MCP: List Servers > Configure Model Access 中限制可用模型。结果会报告实际作答的模型，并在所有辩论方最终使用同一个模型时发出警告（这相当于一个模型与自己辩论，而非真正的辩论）。不支持 sampling 时，默认使用原来的 claude + codex。使用 E3D_MCP_PROVIDERS=claude,codex 固定模型，或使用 E3D_MCP_AUTO_VOICES 限制模型数量。Sampling 会消耗你的 Copilot 用量。

Sampling 只能回答输入和输出均为文本的提示，因此适用于辩论，以及在仓库的 providers 中指定 mcp-sampling 时的 negotiate 和 review 阶段。discover、ideate、draft 和 execute 必须读取或编辑仓库，因此仍需要模型 CLI。e3d_pilot_config_check 会对此发出警告。如果编辑器或服务在运行中停止，使用 sampling 提供方的任务就会失败。

如果在 VS Code 中遇到问题（在 VS Code 1.142 和内置 Copilot Chat 的实际运行中观察到）：

• “Start” 代码透镜可能只显示 “e3d-pilot Error”。原因可在 VS Code 的 Agent 主机日志中找到：较新的版本会等到聊天会话存在后才启动 MCP 服务（“Cannot start an MCP server before the session runtime has been created. Send a message first.”）。打开聊天并发送任意消息，然后启动或重启服务。
• VS Code 可能会显示一次性“迁移”消息，清空 .vscode/mcp.json，并以另一种格式（mcpServers、type: local、tools: ["*"]）写入 .mcp.json。如果你的服务消失了，请检查 VS Code 正在读取哪个文件，或者通过 e3d-mcp --print-config 恢复 .vscode/mcp.json。本地 stdio 服务也可能要求聊天会话类型为“Local”。
• 允许服务使用你的模型的权限提示会在第一次辩论时出现，而不会在 e3d_list_providers 时出现（该工具不会调用模型）。
• e3d-mcp --doctor 可能会提示没有单独列出 Copilot 扩展。较新的 VS Code 版本内置了 Copilot Chat，这是正常的。
• 每日预算在 00:00 UTC 重置（太平洋夏令时为下午 5 点），因此预算中的“天”可能与你本地日期不同。e3d_usage 会显示确切的 resets_at。
• 暂停某个实现时，该想法的账本状态仍为 implementing；作业会以 paused_before 报告 waiting_for_human。调用 e3d_pilot_cancel_paused 或 e3d_pilot_execute 后，该作业会标记为 cancelled 或 resumed。
• 通过 MCP 记入账本的条目（包括首个 idea_proposed 事件）会归属到 mcp:<client>（或 E3D_MCP_ACTOR），而不会归属到检出目录所有者的 git 身份。<client> 是编辑器声明的名称：VS Code 会声明自己为 Visual Studio Code，但 Copilot 的 Agent 主机会声明为 copilot-cli，因此这里的参与者会显示为 mcp:copilot-cli。如果你想使用固定名称，请设置 E3D_MCP_ACTOR。被拒绝的审批会作为备注记录在该想法上。
• 在 VS Code 自身的工具调用确认提示中拒绝，不会到达服务端，因此无法记录任何内容。只有服务端显示的“Approve this idea?”表单会被记录（作为备注）。即使你在该表单中拒绝，VS Code 也可能记录 response=accept，因此查看想法的账本备注才能可靠地分辨结果。
• 辩论会在运行前按最坏情况预留额度，并在结束后按实际使用量结算，且该过程是原子的（锁文件会串行处理多个共享同一计数器的服务进程），因此并发请求不会全部通过同一限额。
• 流水线作业也会计入花费。 e3d_pilot_start、e3d_pilot_implement 和 e3d_pilot_execute 会在启动前，根据估算的模型调用次数和 token 数量预留每日预算（discover/ideate 启动时，每个已配置提供方约调用 2 次；implement 时，每个起草者调用 1 次，每个协商审查者调用 2 次；execute 时，每个阶段调用 3 次，约使用 200,000 个 token；可通过 E3D_MCP_EST_TOKENS_PER_PHASE 调整）。若预留额度会突破限额，作业会被拒绝且不会记录任何内容；无法启动的作业会退还预留额度。这些是估算值，并非实测值。
• 使用量计数器按整台机器统计，而非按代码库统计：每个主体在 ~/.e3d-pilot/usage/ 下都有一个文件（stdio 模式下为 local），所有该服务访问过的代码库共享此文件。e3d_usage 会显示文件路径。删除该文件即可重置当天的计数。
• 当编辑器自身的模型提供回答时（MCP sampling），辩论会在 150 秒后停止（E3D_MCP_SAMPLING_TIMEOUT_SEC），确保服务能在编辑器约 3 分钟后放弃之前报告超时。只统计实际得到回答的调用；如果辩论在给出结论前停止，则不会为从未执行的综合调用计费。
• 实现失败时，作业的 failure_detail 会指出实际原因（例如 draft-rejected.md: status: too-large ...），存储的作业记录还会带有 warnings 列表。取消后，状态会说明日志仅供追溯。
• e3d-mcp 还提供 MCP 提示词（在支持显示这些提示词的编辑器中为 /e3d-debate、/e3d-propose、/e3d-budget），并且服务会报告 package.json 中的版本（开发版本会报告 0.2.0-dev.N）。
• 如果代码库告知 Agent 何时使用这些工具，Agent 就能更可靠地调用它们。将 docs/mcp-agent-instructions.md 复制到 .github/copilot-instructions.md 或 AGENTS.md。
• 辩论结果现在会报告供应商系列：Copilot 的 Claude 和 claude CLI 计为同一系列，重叠情况会在 warnings 中说明。 | 变量 | 默认值 | 含义 | | --- | --- | --- | | E3D_MCP_REPOS | 工作区根目录 | 流水线工具可使用的仓库，以 : 分隔。 | | E3D_MCP_ALLOW_APPROVAL | off | 设为 1 后，用户可通过征询在编辑器中批准。 | | E3D_MCP_ACTOR | mcp:<client> | MCP 操作记录在账本中的 Actor 名称。 | | E3D_MCP_MAX_JOBS / E3D_MCP_JOB_TIMEOUT_SEC | 2 / 3600 | 并发任务数、每个任务的超时时间。 | | E3D_MCP_MAX_PHASES / E3D_MCP_PLAN_TTL_SEC | 8 / 1800 | 执行阶段上限、计划有效期。 | | E3D_MCP_MAX_ARTIFACT_BYTES | 100000 | 可读取的最大制品大小。 | | E3D_MCP_SAMPLING_TIMEOUT_SEC | 150 | 使用编辑器模型的辩论达到此时长后停止。 | | E3D_MCP_EST_TOKENS_PER_PHASE | 200000 | 启动 e3d_pilot_execute 时，为每个代码编写阶段预留的令牌数。 | | E3D_MCP_PROVIDERS / E3D_MCP_AUTO_VOICES | auto / 3（未使用采样时为 2） | 固定或限制默认辩论发言方。 | | E3D_MCP_SAMPLING_HINTS | claude,gpt | 两个采样发言方的模型名称提示。 |

将它们添加到 mcp.json 中服务的 env，例如 "env": { "E3D_MCP_REPOS": "/Users/me/work/app" }。

托管 / 远程使用

e3d-mcp --http [--host H] [--port N] 通过 MCP 的可流式 HTTP 传输提供同一服务，而 deploy/Dockerfile 会将其打包为容器，因此无法运行本地工具的客户端（例如 Copilot 编码 Agent）仍可请求辩论。目前没有任何内容已部署： 未使用任何云账户，deploy/README.md 中关于 AWS 和 Azure 的说明也未经测试。

• 由谁付费： 由运营方的模型凭据（通过 azure-openai、bedrock、anthropic-api 和 openai-api 提供商使用 Azure OpenAI、Bedrock 或本地端点）支付，而非调用方。每个 bearer token（E3D_MCP_AUTH_TOKENS="name:token"）都是一个预算主体，设有每日调用次数和预估令牌数上限，并会在辩论开始前检查。这些上限按令牌分别计算，并非全局上限，数据存储在单个实例的文件中。
• HTTP 模式下关闭了什么，以及原因： 默认隐藏 e3d_pilot_* 流水线工具、来源信息和创意列表（这些功能会操作服务所在磁盘上的仓库）；禁用采样、征询和根目录（它们需要向服务端发送客户端请求），因此审批保持只读。绑定到非回环地址时，如果没有令牌，服务将拒绝启动；TLS 应由反向代理提供。
• 用量报告在本地也可用： e3d_debate 结果现在包含 usage（模型调用次数和预估令牌数）与 budget，e3d_usage 会显示今日总量；E3D_MCP_DAILY_CALLS / E3D_MCP_DAILY_EST_TOKENS 也可在标准输入输出模式下设置可选上限（默认不限制）。

使用外部身份验证与计量服务进行托管

当你为付费客户托管 e3d-mcp --http，且由计费服务（你自己的服务）管理密钥和余额时，请使用此方案。此时，服务会向该计费服务查询调用方身份（introspect）、在辩论开始前冻结额度（reserve），并报告实际发生的情况（settle；若未运行任何操作，则使用 release）。如果不使用此方案，静态 E3D_MCP_AUTH_TOKENS 和本地每日上限仍与之前完全相同。线缆协议、架构、状态机及实现者检查清单见 docs/external-auth.md；参考存根（examples/external-auth-stub.js，非生产代码）和一致性测试运行器（examples/external-auth-conformance.js）展示并测试了兼容服务：

STUB_SERVICE_TOKEN=<24+ chars> STUB_RESERVATION_TTL_SEC=2 node examples/external-auth-stub.js   # prints its loopback URL; the runner's expiry vector needs a short hold lifetime
node examples/external-auth-conformance.js <that URL> <token>          # run against any implementation

此钩子会检查身份和支出，但不会让面向客户开放的代码编写工具变得安全；请勿向客户开放 e3d_pilot_* 流水线工具。

变量	默认值	含义
E3D_MCP_AUTH_URL	未设置	服务的基础 URL（https，或环回地址上的 http）。设置后启用此钩子；仅限 --http。
E3D_MCP_AUTH_SERVICE_TOKEN	无	服务自身用于访问服务的凭据（24 个或更多可打印字符）。
E3D_MCP_AUTH_SERVICE_TOKEN_FILE	无	同上，从文件读取（模式 0600）。两者只能设置一个，不能同时设置。
E3D_MCP_AUTH_CACHE_SEC	30	缓存有效 introspect 答复的时长（1 到 300）。这是撤销生效延迟的上限。
E3D_MCP_AUTH_MAX_INFLIGHT	32	同时进行中的不同 introspect 调用数（1 到 1024）。
E3D_MCP_AUTH_IP_PER_MIN	30	每个 IP 每分钟可提交的被拒绝（未知或格式错误）密钥数，超出后，后续未知密钥将不再向服务查询并直接拒绝。成功的密钥不计入。
E3D_MCP_AUTH_HEALTH_SEC	15	/readyz 背景 health 探测的间隔。
E3D_MCP_OUTBOX_MAX	5000	未送达的结算记录数量上限；达到上限后将拒绝新的计费工作。
E3D_MCP_OUTBOX_MAX_BYTES	67108864 (64 MB)	未送达记录的总大小上限（最终结算记录包含辩论结果）；达到上限后将拒绝新的计费工作。
E3D_MCP_ORPHAN_MAX_AGE_SEC	21600（正整数秒；其他值将导致启动被拒绝）	未完成辩论的计量意图在超过此时长后将被协调，即使其进程 ID 看起来仍然存活（崩溃后 PID 可能会被重复使用）。
E3D_MCP_TRUST_PROXY_HOPS	0	服务前方受信任的反向代理数量。设为 N 时，失败密钥限流器会将 X-Forwarded-For 中从右往左数第 N 个条目用作客户端地址，而不是代理地址；设为 0 时忽略此标头。
E3D_MCP_AUTH_KNOWN_ACTIVE_MAX	10000	失败密钥限流器记住的近期活跃密钥数量（先淘汰最旧的）。
E3D_MCP_OUTBOX_MAX_DEAD	1	在拒绝新的计费工作之前允许进入死信的结算记录数量；可使用 --outbox-status 和 --outbox-retry-dead 重试或解决这些记录。
E3D_MCP_OUTBOX_CLAIM_SEC	300	超过此时长的投递声明视为来自已崩溃的进程，并会重试。
E3D_MCP_ORPHAN_POLICY	charge	服务崩溃时正在运行的辩论在重启后如何计费：charge（预留的单位数，结果为 orphaned）或 release。如果辩论尚未开始就发生崩溃（已预留，但尚未调用模型），则始终只释放预留。

• 默认拒绝。 如果无法连接服务或服务答复异常，则拒绝请求（HTTP 503 retry-after: 5，或对非活跃密钥返回 401），且不会运行模型。无法送达的结算记录会写入状态目录中的持久化发件箱并重试；不会丢弃任何记录。
• 本地上限仍是第二道限额。 E3D_MCP_DAILY_CALLS、E3D_MCP_DAILY_EST_TOKENS 和速率限制仍按主体生效，因此计费故障不会导致支出失控。
• 运维命令（仅打印记录 ID、调用名称、时长和数量）：e3d-mcp --outbox-status；e3d-mcp --outbox-export <file>（新建文件，模式 0600，导出包含载荷的待处理和死信记录，不含令牌，用于协调）；e3d-mcp --outbox-retry-dead <record_id>（仅将一条死信记录移回待处理状态；必须使用完全匹配的 ID；这是唯一会更改任何内容的命令）。e3d-mcp --doctor 和 e3d_usage 会报告钩子、健康状态和发件箱数量。服务或发件箱运行状况异常时，/readyz 会返回 503。
• 死信和服务中断处理流程：docs/external-auth.md 中的运维手册。

异步辩论（立即启动，稍后获取结果）

一场辩论可能需要几分钟，而许多客户端会在此之前停止等待工具调用（Claude Code 大约一分钟后就会停止）。当服务在 introspect 的答复中同时公布 finalize 和 fetch（辩论协议 v1，docs/external-auth.md）时，客户还会获得三个工具：

• e3d_debate_start 启动辩论并立即返回 debate_id。它接受与 e3d_debate 相同的参数，但轮数和每个答案的字数会降低至客户上限（E3D_MCP_CUSTOMER_LIMITS），而不是拒绝请求。更长的提供商列表会被拒绝（不会预留任何资源），而不会截断：删除调用者指定的供应商会改变回答者。
• e3d_debate_status 报告辩论处于排队中、运行中、已完成还是失败状态，以及何时再次检查。
• e3d_debate_result 返回答案、共识级别、异议以及每个模型的立场。只有在设置 include_transcript: true 时才会包含对话记录。

无论是否有人检查，辩论都会在服务端运行。辩论结束后，服务端会完成处理：服务一步完成收费并存储结果，绝不会对无法存储的答案收费。已完成的运行会在本地保留 E3D_MCP_RUNS_TTL_SEC 指定的时长。之后，状态和结果请求会从服务存储的副本（fetch）中获取答复。调用者只能读取自己的辩论：属于其他账户的 ID 与不存在的 ID 一样，都会返回 not_found。服务返回的 not_found 会缓存 60 秒。

如果只公布了这两项功能中的一项，就不会列出异步工具，调用这些工具也会因工具未知而失败。e3d_debate、stdio 模式和静态令牌模式仍按原方式工作。

每项限制都会在预留任何资源之前拒绝新的启动：准入名额（排队中的运行也计入）、每个账户保留的运行数量、运行存储的字节上限，以及发件箱自身的限制。如果服务重启时某次运行的模型已经启动，则该运行会以错误状态完成，且不产生结果。仍在排队的运行会恢复，或者如果其等待时间超过 E3D_MCP_RUN_TIMEOUT_SEC，则会以零收费完成。运行存储在 <state dir>/runs/<hash of the account>/<debate_id>/ 中（目录权限为 0700，文件权限为 0600）。问题和答案绝不会出现在日志中。e3d-mcp --doctor 会检查这些设置并显示运行存储的大小。

变量	默认值	含义
E3D_MCP_RUNS_PER_PRINCIPAL	3	每个账户可同时排队或运行的异步辩论数量。超过此数量时，启动请求会因繁忙而被拒绝，且不会预留任何资源。
E3D_MCP_RUNS_GLOBAL	8	此服务上所有账户合计可同时排队或运行的异步辩论数量。辩论还会与 e3d_debate 共用 E3D_MCP_MAX_CONCURRENT 个执行名额。
E3D_MCP_RUNS_KEEP_PER_PRINCIPAL	50	每个账户保留的运行数量。最旧的已完成运行会优先删除；尚未发送完成通知的运行绝不会被删除。
E3D_MCP_RUNS_TTL_SEC	86400（24 小时）	已完成的运行在本地保留的时长。服务会保留持久化副本。
E3D_MCP_RUNS_MAX_BYTES	67108864（64 MB）	本地运行存储的总大小上限。达到此上限时，会拒绝新的启动请求。
E3D_MCP_RUNS_POLL_PER_MIN	60	每个账户每分钟可发送的状态和结果请求数。
E3D_MCP_RUN_TIMEOUT_SEC	1800	超过此时长的排队运行会以零收费结束，而不会启动。重启后也适用此规则。
E3D_MCP_CUSTOMER_LIMITS	rounds=2,max_words=300,providers=3	客户的异步辩论可使用的最高限值。调用者指定的更大轮数和字数会降低至这些限值；更长的提供商列表会被拒绝。

辩论面板（哪些供应商会作答）

在托管模式下，运营方决定辩论可以使用哪些供应商，每个账户（在 pilot.e3d.ai 上）从中选择自己的面板。问题只会发送给有效面板中的供应商，最终摘要也包括在内。

• E3D_MCP_ALLOWED_PROVIDERS 是托管模式的允许列表。只要设置了此变量，每场辩论（默认配置、账户面板、网页运行的列表或客户端自己的 providers）都只能使用这些供应商，因此托管模式下会拒绝 MCP 采样语音。E3D_MCP_PROVIDERS 必须包含在此列表中，且每个条目都必须对应已知的供应商系列，否则服务会拒绝启动。
• 最终摘要始终由辩论中的第一个供应商撰写，并显式传递给 e3d-debate。（此前，只要安装了 claude CLI，即使辩论中没有 Anthropic，也会由它撰写摘要。）在本地运行时，如果客户端自己的模型或参与辩论的 claude 可用，则由其撰写；否则由第一个供应商撰写。
• E3D_MCP_PANEL=1（托管模式，且使用外部钩子）会在每场辩论开始前、预留任何资源之前，向计费服务的 POST /panel/v1/resolve 请求调用方的面板。此路径不使用缓存，任何失败（HTTP 错误、超时、格式错误的响应）都会导致辩论被拒绝；不会回退到默认配置。账户面板中不可用的供应商会按顺序移除（结果中的 panel.dropped 和工具文本会说明这一点）；如果剩余供应商少于两个，或来自的供应商系列少于两个，辩论就会被拒绝。客户端的 providers 必须是账户面板的子集，因此工具参数可以缩小面板，但不能添加供应商。计费服务中的供应商系列必须与此服务一致；否则会拒绝辩论（panel_config_mismatch）并记录警报。结果中包含 panel（source、requested、used、dropped、families、synthesizer，以及设置时的 required）。
• E3D_MCP_REQUIRED_PROVIDERS（仅限托管模式；stdio 模式下忽略）指定每场托管辩论都必须参与的供应商，并按列出的顺序置于最前；第一个供应商始终负责撰写摘要。客户端的 providers 只能缩小其他供应商的范围（必需供应商会重新添加到最前面，客户端对其余供应商的排序则保持不变）；默认配置、账户面板和网页运行的列表也会将它们置于最前面。如果某个必需供应商不可用，辩论会在预留或运行任何资源之前被拒绝（required_provider_unavailable），因此不会产生费用；不会由其他供应商代为撰写摘要，而是在辩论中途撰写摘要失败时，整场辩论也会失败，绝不会改用其他供应商重试。每个必需供应商都必须位于 E3D_MCP_ALLOWED_PROVIDERS 中，且列表必须符合 E3D_MCP_MAX_PROVIDERS 的限制（使用外部钩子时还必须符合 E3D_MCP_CUSTOMER_LIMITS 中 providers 的上限），否则服务会拒绝启动。在 pilot.e3d.ai 上，必需供应商必须与计费端的 PILOT_PANEL_REQUIRED 一致（例如 anthropic-api）。

变量	默认值	含义
E3D_MCP_ALLOWED_PROVIDERS	未设置（任何可用供应商）	以逗号分隔的供应商列表，每场辩论仅限使用其中的供应商。
E3D_MCP_PANEL	未设置	1：在每场托管辩论开始前，通过计费服务解析每个账户的面板。只有在服务提供此端点后才设置。
E3D_MCP_REQUIRED_PROVIDERS	未设置（没有必需供应商）	仅限托管模式：以逗号分隔的供应商列表，它们必须参与每场辩论并置于最前；第一个供应商负责撰写摘要。不可用时会拒绝辩论（required_provider_unavailable）。必须包含在 E3D_MCP_ALLOWED_PROVIDERS 中。

Web 运行（内部运行监听器）

计费服务的 Web“提问”页面可以让此服务器运行服务已预留的辩论。设置 E3D_MCP_RUN_PORT 和 E3D_MCP_RUN_TOKEN，即可为此启动第二个监听器。此功能需要外部钩子，仅绑定到 127.0.0.1，其路径绝不会通过公共监听器提供服务。如果令牌少于 32 个字符，服务器将拒绝启动。

• 使用 {reservation_id, debate_id, question, providers?, rounds?, max_words?} 调用 POST /internal/runs。服务器首先调用服务的 authorize-run。账户信息只取自该调用的响应，绝不取自请求；除非服务授权，否则不会运行任何内容。运行费用从服务的预留额度中扣除（不会新建预留），并且只会执行一次结算，且 source: "web"。已接受的运行会返回 202 和一个随机的 run_token。重复发送相同请求会返回 200，并附带相同的运行和令牌。字段发生变化，或任一 ID 与不同的另一个 ID 搭配使用时，将返回 409 conflict。明确拒绝时，返回 400 invalid、403 not_authorized、409 conflict 或 429 busy。503（unavailable 或 not_ready）表示请求未被接受，可以稍后重试。
• GET /internal/runs/{debate_id} 会返回状态、进度，以及（运行完成后）结果。DELETE /internal/runs/{debate_id} 会取消运行：结算结果为 outcome: "error"，且不返回结果。两者都需要服务令牌和运行自身的令牌，并通过 X-E3D-Run-Token 标头发送。

每个请求都必须携带 Authorization: Bearer <E3D_MCP_RUN_TOKEN>。令牌会以恒定时间进行比较。每分钟认证失败达到 E3D_MCP_RUN_AUTH_FAILS_PER_MIN 次后，接下来最多一分钟内的所有请求都会被拒绝，并返回 429。Web 运行与异步辩论共用相同的运行槽位、限制、客户上限、运行存储和重启恢复机制。只有当服务声明支持 finalize、fetch 和 authorize-run 时，才会接受新运行。服务器从 introspect 响应中获取这些信息，因此启动后，在检查过客户请求之前，监听器会返回 503 not_ready。请求正文、问题和令牌绝不会出现在日志中。运行令牌仅存储在运行状态文件中（模式为 0600）。e3d-mcp --doctor 会检查这些设置。

变量	默认值	含义
E3D_MCP_RUN_PORT	未设置（关闭）	内部运行监听器在 127.0.0.1 上使用的端口。
E3D_MCP_RUN_TOKEN	未设置	监听器的服务令牌，至少 32 个字符。辩论进程不会继承此令牌。
E3D_MCP_RUN_AUTH_FAILS_PER_MIN	20	监听器拒绝所有请求（最长一分钟）前，每分钟允许的认证失败次数。

Token 计价（per_token_v1）

设置 E3D_MCP_PRICING=per_token 后，服务会按 Token 为计费服务（其 PILOT_PRICING_MODE=per_token）中的辩论计价：运行监听器的健康检查响应（空运行请求收到的 400 invalid）会添加 "capabilities": ["per_token_v1"]；托管连接器辩论会在预留前向服务请求报价；每场辩论都会在报价给出的各供应商限额内运行；每次调用由供应商报告的 Token 数都会在 finalize 前发送给服务。若未设置，则行为不变；不含新字段的运行请求正文也会按原样处理，因此旧版计费服务仍可正常工作。完整行为、相关文件以及应填入费率表的字节数，请参阅 docs/token-pricing.md。

变量	默认值	含义
E3D_MCP_PRICING	未设置	per_token 会启用 Token 计价并公布 per_token_v1。仅限使用外部钩子的托管模式；需要设置 E3D_MCP_CUSTOMER_LIMITS（rounds 和 max_words 分别等于计费服务的 PILOT_TOKEN_MAX_ROUNDS 和 PILOT_TOKEN_MAX_WORDS）。
E3D_MCP_PER_TOKEN_ALLOW_XAI	未设置	1 会按 Token 提供 xai-api（所有者允许使用；保留此开关，以便随时关闭）。xAI 推理 Token 会计费，但不受 max_tokens 限制。
E3D_MCP_PER_TOKEN_SEARCH	未设置	1 会公布 per_token_search_v1：在 Token 计价中计费的网页搜索（运行字段 max_searches 和 cite_bytes、报价版本 2、用量报告版本 2）。需要设置 E3D_MCP_PRICING=per_token，并在此处启用网页搜索。会将 E3D_MCP_DAILY_SEARCHES 的默认值设为 160。请参阅 docs/token-pricing.md。
E3D_DEBATE_MAX_SEARCHES / E3D_DEBATE_CITE_BYTES_MAX	未设置	仅限 e3d-debate；须同时设置或都不设置，并与 E3D_DEBATE_MAX_TOKENS 配合使用：{"<provider>": k} 表示可执行搜索的供应商及其每次调用的报价上限；另一个参数表示插入后续提示词的引用列表最大字节数。e3d-mcp 会根据报价设置这些变量。
E3D_DEBATE_MAX_TOKENS	未设置	仅限 e3d-debate：{"<provider>": n}，表示每次调用的供应商输出上限。会将辩论切换到按 Token 计价模式（仅限 API 供应商、不重试，除非 E3D_DEBATE_MAX_SEARCHES 指定，否则不进行网页搜索，并写入 usage.json）。e3d-mcp 会根据报价设置此变量。
E3D_DEBATE_ANSWER_BYTES_MAX	未设置	仅限 e3d-debate：{"<provider>": n}，表示插入后续提示词的供应商回答最多包含多少 UTF-8 字节。可单独使用。
E3D_DEBATE_PROMPT_OVERHEAD	未设置	1 会让 e3d-debate 输出每种提示词固定文本的字节数，然后停止。

我们为何构建它

自主编码 Agent 解决了问题的执行部分：给一个优秀模型一份优秀的规范，它就会忠实地实现。仍然缺失的是此前的一切——发现哪些东西值得构建，确认它不是对已关闭 PR 或上周已放弃分支的重炒，以及在任何内容触及工作树之前，让不止一个模型真正认同计划安全可靠。跳过这部分，就会得到这样的 Agent：它们欣然重新实现已有功能，在没人要求的 PR 中自我争论，或者悄无声息地突破代码仓库实际的差异预算。

e3d-pilot 的存在，就是为了补上这一缺失环节：它是一个小巧、可审计的层，位于 e3d-code（原名 spec2code）之上，而不是重复实现它。e3d-code 仍然是那个简单可靠的阶段执行器——“运行这份规范”。e3d-pilot 的职责是决定规范究竟该写什么、证明它值得去做，并拒绝让它在无人监督的情况下运行到需要人类审查的阶段之后。

另一个原因是：好点子很少来自对着同一份待办清单反复琢磨。e3d-pilot 的发现阶段会明确借鉴代码仓库所属类别之外的领域——游戏的进度循环、交易市场的流动性技巧、社交信息流的通知机制；其构思阶段则会根据吸引力和留存率为每个候选方案评分（能否吸引用户，能否让他们回来），并将收入视为次要的平局判定因素，而绝非决定因素。我们的目标是打造人们真正想要的功能，而不是只做内部 TODO 列表上的下一个条目。

第三个原因，不那么关乎某一次运行，而更关乎多次运行后积累的成果：一个决定一旦做出，就不该要求接手工作的下一个会话从头重新解释。每个已跟踪想法的台账记录，都是一个持久的跨会话目标——ideas context/ideas handoff 让全新的 Claude Code、ChatGPT 或 Codex 会话准确了解关于某个想法的已知信息（其决策、发现和当前状态），而不必重放之前的整段对话；ideas note 则让该会话写回刚刚了解到的内容。同样的理念——对于真正存在争议的问题，不要只相信一次推理结果——也是 e3d-debate 作为独立工具存在的原因：让多个模型分轮讨论任何问题，直到它们达成一致，或留下有明确名称且具体的异议。这与 e3d-pilot 自身协商阶段内部依赖的机制相同，可用于任何决策，而不只是代码更改。

它的不同之处

• 绝不重复劳动。 在允许任何想法进入后续流程前，都会检查目标仓库的开放分支、PR 历史记录（开放和已关闭），以及此前每次 e3d-pilot 运行的记录。
• 绝不只凭一个模型的意见行事。 协商阶段要求所有已配置的审查者——目前有两个，之后可通过配置增加——独立批准同一份未改动的草稿。意见不一致时，会进行次数有限的重试，随后明确停止并标记为“需要人工处理”，而不是强行合并。
• 绝不把未批准视为已批准。 发现和构思可以无人值守地运行，但会修改源代码的阶段必须先执行 ideas approve，合并到基准分支则必须针对确切的 PR head SHA 执行 approve-merge。
• 绝不在首个关卡前触碰源代码。 只有在实现获批后，才会在独立分支上的隔离 worktree 中执行操作。任何内容进入审查或发布环节前，都会执行路径拒绝列表检查，并核实实际执行后的差异是否超出限制。
• 绝不合并不同的修订版本。 合并批准独立于 GitHub 审查批准，并绑定到已确认的 PR URL、基准分支和 head SHA。提交推送后，批准即失效，直到人工审查并批准新的 head。
• 绝不假定它操作的是 spacepacket1 的仓库。 与目标仓库的全部约定都由一个 JSON 配置文件定义。流水线中没有固定的组织或远程主机，也不内置任何 e3d-* 命名假设。
• 绝不让想法的上下文在会话之间消失。 ideas note/ideas context/ideas handoff 为任何 AI 会话——不仅限于 e3d-pilot 自身流水线的运行——提供持久空间，用来读取和记录关于已跟踪想法的经验或决定，且不受其生命周期状态影响。

它如何帮助他人

如果你维护一个仓库，并希望持续获得关于“接下来应该构建什么”的第二意见——它会先做好功课再提出建议，在采取行动前取得独立模型共识，并提供带有完整审计记录的 PR 草稿，而不是造成既成事实——那么，采用 e3d-pilot 的设计目标是只需做出一个文件层面的决定：编写 .e3d-pilot/config.json，运行一次进行验证，然后按你选择的频率（例如 cron 条目或计划任务）让它处理你的仓库（或整批仓库）；e3d-pilot 不会另行发明自己的调度器。它在 GitHub、本地无远程仓库的仓库上，以及——从架构上说，即使尚未为其提供 forge 适配器——任何其他 git 主机上，运行方式都完全相同，因为只有最后的发布步骤才需要知道自己连接的是哪个 forge。

Pipeline

flowchart LR
    A[discover] --> B[ideate]
    B -->|optional candidate_scoring| S[read-only ensemble]
    S --> I[[proposed idea ledger]]
    B -->|selected: none| STOP1((nothing to do))
    I -->|ideas approve| C[draft]
    I -->|ideas reject| STOPR((rejected))
    C --> D[negotiate]
    D -->|needs human| STOP2((stop for review))
    D --> E[execute]
    E -->|over ceiling| STOP2
    E --> F[review]
    F -->|verify failed| STOP3((blocked))
    F --> G[publish]
    G --> H[[implemented: draft PR / local branch]]
    H -->|approve-merge for exact head SHA| M[merge]
    M --> Z[[merged / partially_merged / merge_failed]]

1. discover — 写入 findings.md：Git 历史记录、分支、议题/PR、现有文档和 TODO，以及由模型调研的“外部背景”部分，其中包含明确的跨领域“类似模式”子部分（参见下文的构思信息来源）。
2. ideate — 写入经过排序、去重的 candidates.md，并将每个非重复候选项转为 proposed 状态的构想。如果所有已提议的内容都已涵盖，selected: none 是有效且干净的停止状态。如果配置了 candidate_scoring，一组只读工作器会在写入前重新评定非重复候选项；模型最初选中的内容会存储为 model_selected。
3. approval gate 1 — 由人工批准或拒绝确切的构想。proposed 绝不表示已拒绝；没有当前的实现批准，任何会修改源代码的阶段都无法运行。
4. draft — 将已批准的候选项转为符合 e3d-code 格式的 spec-draft.md，并为每个阶段添加机器可读的 pilot:touches 注释，以便后续防护措施检查实际路径，而不是猜测说明文字的含义。
5. negotiate — 所有已配置的审阅者都必须在一轮中批准同一份未更改的草案；意见分歧会触发有次数限制的修订轮次，最终以成功生成 spec-final.md 或干净停止并标记为“需要人工处理”告终。
6. execute — 在独立分支的隔离工作树中，将 spec-final.md 交给已配置的执行后端，然后强制执行 protected_paths 和实际执行后的 max_diff_files/max_diff_lines 上限。默认后端为 e3d-code（原名 spec2code）。providers.execute: "grok-build" 是一个实验性替代方案，仍使用相同的工作树、上限、审查和草稿 PR 流程。
7. review — 运行（或自动检测）验证命令，并让独立审查提供方检查实际 diff。
8. publish — 仅在验证通过后：将本次运行的审计产物提交到分支，并交由发布后端（github 或 local）创建草稿 PR，或保留本地审查分支。
9. approval gate 2 — 人工审阅草稿 PR/本地分支后运行 approve-merge。对于 GitHub 目标，e3d-pilot 会记录当前 PR 头部 SHA；若之后的头部发生变化，则拒绝合并，除非获得新的批准。

生成的运行产物位于目标仓库中的 .e3d-pilot/runs/<run-id>/。构想账本状态位于 .e3d-pilot/ideas/<idea-id>/idea.json，追加式事件则存储在 .e3d-pilot/events.jsonl 中。idea.json 根据事件生成，可以重建；events.jsonl 是不可变的审计来源。未指定 --run-id 的 discover 和 all 会启动一个新的、防冲突的 run-id，并更新 .e3d-pilot/latest-run；其他所有阶段都会恢复使用最新的 run-id，除非你明确传入 --run-id <id>。在目标仓库中创建 .e3d-pilot/paused，即可在任何外部操作发生前停止各阶段。

构思选题与评分

Discover 的模型调用不只是总结“最先进的技术”，还会被要求从可配置的 analogy_domains 列表（或涵盖游戏、社交平台、市场、开发工具和金融科技的合理内置默认列表）中选出最具迁移价值的 2–3 个条目，并具体说明每种机制如何应用于此仓库。

Ideate 随后会对每个非重复候选项的 Attraction 和 Retention 分别评分（各为 1–5），标注 Category（data、workflow、social、gamification、testing、marketing、selling 或 other），引用所借鉴的 Analogy，并估算 Effort。排名主要由 Attraction + Retention 决定；可选的 Revenue 评分只能用于区分其他条件相同的候选项，绝不能让一个候选项排在吸引或留住用户效果更好的候选项之前。这样的优先顺序是经过刻意设计的：增长并留住用户才是目标，收入只是做好这件事后的次要结果。

语义重复检测（Jev，可选）

在实例化之前，系统已通过对提案进行哈希（ideas_find_duplicate_by_digest）来捕获完全重复的候选项。另外，如果设置了 TYPESAFE_API_KEY，每个新实例化的想法都会通过 Jev（TypeSafe 的 System One Choice API）与同一账本中的其他有效想法进行比对，以检测哈希无法捕获的语义重复——即底层问题相同，但措辞不同。这会在每次 ideas ingest/propose 调用时自动运行；除了提供凭据外，没有其他配置标志可以启用它。如果未提供凭据，则会静默跳过，不会报错。

此功能处于影子模式，仅提供建议：匹配结果不会阻止导入，也不会更改候选项，只会附加一条发现备注（“possible semantic duplicate of <idea-id>, confidence <level> — does not block this idea”），供人工审核时查看。在真实校准样本验证 Jev 针对这一特定判断的误报率之前，此功能始终仅提供建议（参见 idea-980bf5b4df6b / idea-82a5c2225266）。参见 lib/ideas/jev_dedup.sh。

可选的集成评分

ideate 提供方写入候选项后，可选的 candidate_scoring 块可以在想法实例化之前，通过 3–5 个独立的只读工作进程重新为候选项排序。原始模型选择结果会存储为 model_selected；selected 则变为非重复候选项中的集成胜出者。评分不会执行、发布或批准任何内容——两个人工审核关卡仍然适用。

任何 lib/providers 适配器都可以用作评分提供方。grok-build 是一种选择，旨在作为更经济的扇出层，位于 frontier negotiate 和 e3d-code execute 之前：

"candidate_scoring": {
  "provider": "grok-build",
  "workers": 3
}

workers 必须是 3 到 5 之间的整数（默认值为 3）。产物会写入运行目录，包括 ideate-scoring.json、ideate-response.model.md，以及 ideate-scoring.artifacts/ 下每个工作进程的提示词/标准输出。Fleet discover 在 .e3d-pilot-fleet/config.json 中使用相同的配置块，并写入 fleet-ideate-scoring.json。运行评分后，每条想法记录都会将集成平均值存储为 scores.ensemble；此字段不属于批准摘要。

以收入为重点的运行

在 e3d-pilot run（任意阶段）中传入 --focus revenue，即可在专门运行中切换优先级：discover 会添加 ### Monetization Signals 小节（仓库中现有的变现机制，以及 2-3 种可用于扩展这些机制的相邻行业模式），而 ideate 会优先按 Revenue 对候选项排序——只有在平局时才以 Attraction/Retention 作为判断依据，并将 Revenue 从可选的平局判断字段改为必填数值字段。候选项可以是全新的变现方式，不必只是现有功能的扩展；无论哪种情况，重复项检查都同样适用。

每次运行只解析一次重点，并持久化到 .e3d-pilot/runs/<run-id>/focus，因此，同一次运行的后续阶段（例如，在 discover 已运行后单独调用 --stage ideate）会自动继承该重点，除非再次显式传入 --focus，此时会覆盖原值。默认行为（--focus default，即优先考虑吸引力/留存率）保持不变。

Fleet 实时运营

Fleet 发现可从可选的 .e3d-pilot-fleet/config.json 字段中提取两个只读运营信号：

• live_instances：由对象组成的数组，每个对象必须且只能包含 name 和 url。name 必须是非空的显示名称。url 必须是非空的 http:// 或 https:// URL，包含非空的 authority，且不包含用户信息。采集器对每个实例恰好发出一次 GET 请求，最多跟随一次重定向，每个请求的超时时间上限为 10 秒，仅允许初始请求和重定向请求使用 HTTP/HTTPS，且绝不重试。
• 实时状态分类采用确定性规则：HTTP 200 且耗时不超过 1500 毫秒时为 healthy；HTTP 200 且耗时超过 1500 毫秒，或任何其他 2xx/3xx 响应时为 degraded；发生 curl 错误、耗时/状态输出无效，或状态码不在 200-399 范围内（包括 000、1xx、4xx、5xx 和 6xx-9xx）时为 down。
• social_accounts：由对象组成的数组，每个对象必须且只能包含 platform、name、channel_id 和 bot_user_id。platform 必须是字符串 discord。bot_user_id 是用于精确验证作者身份的公开标识符，不是凭据。Discord 采集从环境中读取 DISCORD_BOT_TOKEN，对每个配置了凭据的账户恰好发出一次消息请求；如果令牌缺失或为空，则不发出任何请求。
• Discord 采集为只读操作，使用 GET https://discord.com/api/v10/channels/{channel_id}/messages?limit=50，且不重试。它会区分 no recent messages found、零互动消息和采集失败。仅对 author.id 与 bot_user_id 完全匹配的消息汇总反应数。
• 只有当上述任一数组非空时，才会追加 ## Live Operations。只要该小节存在，### Live Instance Status 就会首先出现；如果没有实时实例但已配置 Discord，该小节会显示 No live instances configured.。仅当 social_accounts 非空时，才会显示 ### Social Engagement。
• 只有在实时实例状态为 degraded/down，或 Discord 出现零互动或采集失败的情况下，才会按配置顺序包含 ### Operational Recommendations 中的条目。该小节会重复观察到的确切状态，不会猜测原因。健康实例、非零 Discord 互动以及 no recent messages found 均不会生成建议。
• 计划在后续的同级分支中支持 Moltbook。
• 请勿将凭据放入 fleet 配置；只有 DISCORD_BOT_TOKEN 应放在运行时环境中。

如果需要现成的 fleet 配置，其中包含虚构的 .example.com 实时实例和虚构的 Discord 账户，请从 examples/sample-fleet-config-with-ops.json 开始。

要求与安装

安装 Bash、Git、jq 和 curl；完整流水线的执行阶段还需要 e3d-code，这是一个按阶段根据规格编写代码的工具（原名为 spec2code；可通过 npm install -g e3d-code 安装，也会随 npm install -g e3d-pilot 一同自动安装）。辩论和只读 MCP 工具不需要它。安装并验证配置中使用的模型 CLI 和代码托管 CLI（claude、codex、devin、本地兼容 OpenAI 的端点，以及／或者用于 grok-build 的 grok）。将此仓库的 bin 目录添加到 PATH：

# From npm (also installs e3d-code, the execute-stage dependency, when it can):
npm install -g e3d-pilot
e3d-pilot --help

# Or from a clone:
git clone https://github.com/spacepacket1/e3d-pilot.git
export PATH="$PWD/e3d-pilot/bin:$PATH"
e3d-pilot --help

npm 包提供三个命令：e3d-pilot、e3d-debate 和 e3d-mcp。

Node.js 仅用于可选的 e3d-pilot web 仪表板（见下文的 Web UI）；所有其他命令只需要 Bash、Git、jq 和 curl。

配置仓库

在目标仓库中创建 .e3d-pilot/config.json。请从 examples/sample-config.json 开始。字段如下：

• verify：在执行工作树中、发布前运行的命令。若为空列表，则会从 package.json、requirements.txt 或 Makefile 自动检测。
• protected_paths：生成的规格和执行时保护措施会拒绝处理的 glob 模式。
• research_topics：用于探索性研究的提示。
• analogy_domains：可选的跨领域种子列表，供探索阶段的类比分析使用（见上文）；省略时会使用内置默认值。
• providers：为 discover、ideate、draft、按顺序排列的 negotiate 审阅者、独立的 review，以及可选的 execute 指定提供方（默认为 e3d-code，也可使用实验性的 grok-build）。discover、ideate、negotiate 和 review 可以是提供方名称字符串，也可以是名称数组；设置为数组时，列表中的每个模型都会运行（discover／review 会拼接输出；ideate 会合并候选方案；negotiate 仍要求通过一次不修改草稿的共识审查）。draft 仍只能使用单个提供方。grok-build 是普通适配器：可像使用 claude、codex、devin 或 local 一样，将它填入相同字段。
• candidate_scoring：可选的 { "provider": "grok-build", "workers": 3 }。ideate 提出候选方案后，3–5 个独立的只读工作进程会对其重新排序。provider 可以是任意 lib/providers 适配器；grok-build 是其中一个选项。评分不会执行、发布或批准任何内容。省略时不进行评分。
• max_diff_files 和 max_diff_lines：实际执行后的上限。
• docs：可选的指导文档路径；否则会检测常见文件名。
• live_verify：可选的 { "command": "..." } 钩子。只有在仓库文档指出存在受支持的 E3D 付费 API 接口，且 e3d-agent 可用时才会运行；否则会跳过。
• pr：base_branch、草稿标志、标签和后端（auto、github 或 local）。
• notify：可选的 { "email": { "to": "...", "command": "..." } }。见通知。
• approval：可选的 { "implementation_required": bool, "merge_required": bool }。两者默认均为 true；见审批门控的操作员工作流。
• tracking：可选的 { "project_url": "..." }。为此仓库覆盖 E3D_PILOT_TRACKING_PROJECT_URL；见项目看板跟踪。

验证并运行：

e3d-pilot config validate /path/to/repository
e3d-pilot run --repo /path/to/repository --stage all

需审批的操作员工作流

默认的 run --stage all 会自主发现并构思创意，将创意具体化，然后在 draft 之前停止，除非所选创意已获得当前有效的实施审批。这是成功的等待状态，不是崩溃。

列出并检查提议的创意：

e3d-pilot ideas list --repo /path/to/repository --status proposed
e3d-pilot ideas show --repo /path/to/repository idea-abc123def456

批准或拒绝实施：

e3d-pilot ideas approve --repo /path/to/repository idea-abc123def456 --actor [email protected] --note "Build this next"
e3d-pilot ideas reject  --repo /path/to/repository idea-abc123def456 --reason "Not aligned this cycle" --actor [email protected]

ideas approve 是第一道关卡。它授权针对确切的创意内容和已批准的目标计划进行起草、协商、执行、审查和发布。它不是 GitHub PR 审查，也不授权合并。

在创意上记录发现和决策，并将其提取为简洁的上下文，不受创意生命周期状态影响：

e3d-pilot ideas note     --repo /path/to/repository idea-abc123def456 "Discovered the API rate-limits at 50 req/min" --actor [email protected]
e3d-pilot ideas note     --repo /path/to/repository idea-abc123def456 --decision "Ship the read-only slice first" --actor [email protected]
e3d-pilot ideas context  --repo /path/to/repository idea-abc123def456 [--json]
e3d-pilot ideas handoff  --repo /path/to/repository idea-abc123def456

这些功能旨在弥补一个特定的缺口：除了 e3d-pilot 自己的流水线调用之外，没有任何东西会写入 .e3d-pilot/，因此，在临时的 Claude Code、ChatGPT 或 Codex 会话中发现的有关已跟踪创意的上下文无处持久保存。ideas note 会通过纯自循环事件（note_appended），将自由格式的发现（或使用 --decision 时的决策）追加到创意现有的台账记录中；此事件永远不会触发关卡，也不会受生命周期状态的关卡限制——无论创意处于何种状态，包括 proposed、implemented 或 merged，都可以使用。ideas context 会以简短摘要的形式读回该创意，并将累积的决策和发现分开呈现。ideas handoff 会将相同信息整理为简洁的信息包（GOAL / STATUS / RELEVANT DECISIONS / RELATED CONTEXT / RECENT FINDINGS），方便交给新的模型会话，而不必从头重新解释所有内容。这些功能不会引入新架构或新创意类型——它们只是基于现有的逐创意台账提供了三个轻量动词。

来源追溯导出与追踪实验

来源追溯命令直接从同一事件台账中生成一次性图谱，或单个创意的追踪记录：

e3d-pilot provenance export --repo /path/to/repository [--out /path/to/provenance.jsonl]
e3d-pilot provenance trace  --repo /path/to/repository idea-abc123def456 [--json]
e3d-pilot fleet provenance export /path/to/fleet.json [--out /path/to/provenance.jsonl]
e3d-pilot fleet provenance trace  /path/to/fleet.json idea-abc123def456 [--json]

provenance export 会重新生成规范节点和边，其中包括 fleet 创意提议的仓库；provenance trace 会直接读取 events.jsonl，并区分决策、发现、Pilot 产出的工作、仅由 Pilot 观察到的外部提交、结果和失败。在 ideas note 中添加 --evidence <path-or-url>，即可在仓库模式的追踪记录和导出中保留支持材料的指针，而无需将材料复制到台账中。这是 e3d-graph 讨论中商定的刻意不带 UI 的实验：在开展任何可视化工作之前，先验证追踪记录能否比手动阅读台账更快、更准确地回答实际归属问题。

每次 provenance export 还会写入一个同目录的 <name>.manifest.json（按类型统计节点/边数量、孤立节点、度数最高的节点，以及表示派生图谱大小与源台账大小之比的 graph_events_ratio）——这是用于发现图谱是否在悄然膨胀或丢失结构的工程遥测数据，不是产品分析数据。

固定的 provenance query 子命令会汇总创意到结果的 lineage、重复的审查 reversals、实施 failures，以及仅限 fleet 的 cross-repo 传播；每个子命令都支持 --json，fleet 模式使用 e3d-pilot fleet provenance query <name> /path/to/fleet.json，仓库模式使用 e3d-pilot provenance query <name> --repo /path/to/repository（其中 cross-repo 会按预期返回空结果）。 一个独立的脚本——bin/e3d-provenance-agreement --repo /path/to/repository（采用与 e3d-debate 相同的模式，不接入子命令树）——会汇总该仓库 .e3d-pilot/runs/ 下历史协商轮次和评审轮次中的提供方一致性，并通过子进程复用现有的 lib/negotiate/parse-status 和 lib/review/parse-verdict 解析器，而不是重新推导其约定。它会在标准输出中打印 JSON：每个提供方的协商批准率、每对提供方的一致率，以及具体的分歧（运行 ID、轮次、双方提供方的状态和所述原因）。早于当前格式或解析失败的响应文件会跳过并单独计数，绝不会计为一致或分歧。

评审异议、逃过评审的缺陷以及历史记录回填，详见 docs/objection-capture.md。

实现已批准的想法：

e3d-pilot ideas implement --repo /path/to/repository idea-abc123def456
e3d-pilot ideas implement-approved --repo /path/to/repository

成功的实现会记录运行 ID、分支/工作树、变更文件和行、验证结果、评审结果、发布后端、PR URL/编号以及最终 PR head SHA。GitHub 发布会创建草稿 PR；本地发布会保留本地评审分支和摘要。

ideas implement 每次都会启动全新运行，并在重试时从头重新执行 draft、negotiate 和 execute——即使失败的只是最后一个阶段（通常是 publish，例如 forge 标签尚不存在），而此前的尝试已完成验证和评审。如果某个特定运行已经推进到该阶段，请在原运行中恢复，而不是再重复 draft/negotiate/execute 周期：

e3d-pilot ideas repair-run --repo /path/to/repository --run-id <run-id> [--from-stage <stage>] idea-abc123def456

--from-stage 默认为 publish。恢复点之前的每个阶段都必须已在磁盘上留下实际成功产物——这只能跳过有证据证明已完成的工作，不能跳过从未发生的工作。

写入任何代码前先暂停，查看计划，然后继续或放弃：

e3d-pilot ideas implement --repo /path/to/repository --stop-before execute idea-abc123def456   # draft + negotiate, then stop
e3d-pilot ideas resume    --repo /path/to/repository idea-abc123def456                          # execute -> review -> publish
e3d-pilot ideas cancel-paused --repo /path/to/repository --reason "plan too broad" idea-abc123def456

--stop-before 接受 negotiate、execute、review 或 publish。暂停的想法会保持 implementing 状态（不会新增 ledger 状态），并在其运行目录中写入 paused-before.txt 标记。resume 会重新检查批准摘要、每个先前阶段的产物是否存在，以及基础 SHA 是否已变动，然后以通常的 implemented/failed 结果结束。cancel-paused 会记录带有你所提供原因的 implementation_failed 结果，以便正常的 ideas implement 可以重试。

审阅草稿 PR 后，通过第二道关卡批准并执行合并：

e3d-pilot ideas approve-merge --repo /path/to/repository idea-abc123def456 --actor [email protected] --note "Reviewed head"
e3d-pilot ideas merge         --repo /path/to/repository idea-abc123def456

approve-merge 会记录确切的 PR URL、基础分支和 head SHA。ideas merge 会在合并前立即刷新 forge 状态，并拒绝过期的 head、已变更的基础分支、草稿 PR、已关闭的 PR 或缺少批准的情况。GitHub 评审批准是有用的协作凭据，但不等同于 e3d-pilot 的合并批准。

请求更改、同步 forge 状态并记录结果：

e3d-pilot ideas request-changes --repo /path/to/repository idea-abc123def456 --reason "Tighten scope"
e3d-pilot ideas sync            --repo /path/to/repository
e3d-pilot ideas outcome         --repo /path/to/repository idea-abc123def456 --window 7d --metric retained=true --metric revenue=42
e3d-pilot ideas rebuild         --repo /path/to/repository

sync 会观察 PR head 变更、草稿/就绪状态变更、检查结果、关闭以及外部合并，但不会批准任何内容。新的 PR head 会使合并批准失效。outcome 会追加类型化指标，绝不覆盖历史记录。rebuild 会从 events.jsonl 重新生成派生的 idea.json 快照。

迁移

现有 .e3d-pilot/runs/<run-id>/ 产物仍可读取。重新运行该运行的 ideation，即可将旧版选定候选项物化为 proposed 想法：

e3d-pilot run --repo /path/to/repository --stage ideate --run-id <legacy-run-id>

该命令可以创建 proposed 想法记录，但绝不会创建实现批准。仍须由人工运行 ideas approve。

现有的未关闭 e3d-pilot PR，只能通过已安装版本提供的明确采用命令进行接管。采用操作必须记录 PR/运行的来源，将想法设为 implemented，并且在合并到任何基础分支之前仍须执行 approve-merge。不要将未关闭的 PR、GitHub 评审批准或分支名称视为 ledger 批准。

提供方与协商

内置适配器包括 claude、codex、local、devin、grok-build、需主动选择的 gemini 试用适配器、两个云适配器 bedrock 和 azure-openai，以及四个直接 API 适配器 anthropic-api、openai-api、gemini-api 和 xai-api（无需 CLI，适用于服务和容器）；使用 e3d-pilot providers list 查看这些适配器。 grok-build 的选择方式与其他适配器相同：在 providers.* 中指定它。 当 grok 二进制文件位于 PATH 中时即可使用（通过 GROK_BUILD_BIN 覆盖）。

discover、ideate、negotiate 和 review 都可以列出多个模型，让每个已配置的适配器都有机会运行。字符串仍然有效，表示“仅使用此模型”。negotiate 原本就支持这种方式；现在 discover、ideate 和 review 也支持了。如果某个 discover、ideate 或 review 适配器缺失或运行失败，其他适配器仍会运行，阶段也会继续；只有所有列出的适配器都失败时，阶段才会失败。negotiate 在审查者不可用时仍会立即失败，因为达成共识正是该阶段的目标。

grok-build — 以无头模式调用 Grok Build CLI。推理阶段使用只读沙箱。使用 curl -fsSL https://x.ai/cli/install.sh | bash 安装，然后运行 grok login --device-auth 或设置 XAI_API_KEY。通过 GROK_BUILD_BIN、GROK_BUILD_TIMEOUT（秒，默认值为 900）和 GROK_BUILD_MODEL 覆盖二进制文件、超时或模型。无需额外的启用标志：在配置中指定 grok-build 即表示主动选择，与其他适配器相同。

gemini — 需主动选择的试用适配器，适用于明确选择了 e3d-debate --providers ...gemini... 的运行。它不在 e3d-debate 的默认配置中，也不在任何默认或推荐的 providers.* 配置中；与这里的所有其他适配器一样，除明确指定外，无需单独的启用标志。因此，代码不会阻止你在流水线阶段自己的 providers.* 配置中指定它，但它与其他用户共用且配额有限的免费层级（见下文），不适合任何必须始终成功的阶段。 安装 Gemini CLI，并按照其个人 Google OAuth 说明操作。为避免产生付费调用，该适配器会拒绝 API 密钥、Vertex AI、Google Cloud、凭据覆盖、缺失、含糊不清以及可能产生超额费用的身份验证方式——settings.json 中的 billing.overageStrategy 必须严格设为 "never"（其默认值为 "ask"，而非 "never"）。它以无头模式运行，并根据策略拒绝所有内置工具、扩展工具和 MCP 工具；如果用户设置、系统设置或系统默认设置文件中配置了任何 Gemini CLI 钩子、mcpServers 条目、admin.mcp.config、admin.mcp.requiredConfig 或 adminPolicyPaths 条目，它也会拒绝运行（钩子会在生命周期事件中执行可访问提示词的任意命令；MCP 服务——包括 Gemini CLI 文档所述“无论用户偏好如何”都会注入的企业管理员必需服务——会在发现阶段于 CLI 启动时运行命令；管理员策略路径指向此适配器无法审计的其他策略文件——这些都独立于策略所禁止的工具调用路径）。设置 GEMINI_BIN（默认值为 gemini）、GEMINI_MODEL（默认未设置）、GEMINI_TIMEOUT（秒，默认值为 120）或 GEMINI_TOKEN_LIMIT（默认值为 200000）以覆盖其限制。Gemini 提供确切的响应模型和令牌数时，成功调用会报告这些信息；否则遥测数据会标记为未测量。超时或令牌上限会导致调用失败，而不会返回部分输出。请参阅促成该适配器的 Gemini/Qwen 提供方辩论。

如果只想把 Grok 用作低成本候选项排名器，请保留现有的 ideate/negotiate 提供方，并添加 candidate_scoring（参见可选的集成评分）。该扇出不会执行。人工审批、negotiate 和 e3d-code 执行仍会保留。 devin — 通过非交互式打印模式调用 Devin CLI。默认使用 claude-sonnet-4-6-thinking-1m；可通过环境变量覆盖：

export DEVIN_BIN=devin                          # binary path (default: devin)
export DEVIN_MODEL=claude-sonnet-4-6-thinking-1m  # model override
export DEVIN_PERMISSION_MODE=auto               # permission mode (default: auto)

bedrock — 通过 AWS CLI 的 Converse API 使用 Amazon Bedrock（不使用 SDK）。需要 aws 位于 PATH 中，并提供模型 ID 和区域；凭证取自常规 AWS 凭证链（环境变量、配置文件、SSO、实例角色或任务角色）：

export BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0   # or an inference-profile id
export AWS_REGION=us-east-1

providers list 只会检查 CLI、模型 ID 和区域是否已设置；如果缺少权限，首次实际调用时会显示清晰的错误。请求通过负载文件发送，因此可以处理较大的提示词，且不会出现在 ps 中。可选项：BEDROCK_MAX_TOKENS（4096）、AWS_BIN。

azure-openai — 通过 HTTPS 使用 Azure OpenAI 部署（curl + jq）：

export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
export AZURE_OPENAI_DEPLOYMENT=my-deployment          # the deployment name, not the model name
export AZURE_OPENAI_API_KEY=...                       # or AZURE_OPENAI_API_KEY_FILE=/path/to/file-with-only-the-key

密钥通过权限模式为 0600 的标头文件发送，不会出现在命令行中，也不会被打印或由 providers list 探测。可选项：AZURE_OPENAI_API_VERSION（2024-10-21）、AZURE_OPENAI_MAX_TOKENS、AZURE_OPENAI_TIMEOUT（120 秒）。两个适配器都会报告令牌用量，并遵循 E3D_PILOT_PROVIDER_TOKEN_LIMIT。本仓库的测试均未针对真实服务运行这两个适配器（测试使用伪造的 aws 和本地伪造 HTTP 服务）。

anthropic-api 和 openai-api — 通过 HTTPS 使用 Anthropic Messages API 和 OpenAI 聊天补全接口（curl + jq），无需 claude 或 codex CLI。服务器或容器可使用它们搭配你自己的 API 密钥；两个不同的提供商即可进行辩论（--providers anthropic-api,openai-api）。

export ANTHROPIC_API_KEY=...        # or ANTHROPIC_API_KEY_FILE=/path/to/file (the key alone, or an `export ANTHROPIC_API_KEY=...` line)
export ANTHROPIC_API_MODEL=claude-sonnet-5-5    # optional; this is the default
export OPENAI_API_KEY=...           # or OPENAI_API_KEY_FILE=...
export OPENAI_API_MODEL=...         # required: there is deliberately no default, because model names change
export GEMINI_API_KEY=...           # or GEMINI_API_KEY_FILE=...   (gemini-api: Google Gemini)
export GEMINI_API_MODEL=...         # required, no default
export XAI_API_KEY=...              # or XAI_API_KEY_FILE=...      (xai-api: xAI Grok)
export XAI_API_MODEL=...            # required, no default

gemini-api 和 xai-api 使用各自厂商兼容 OpenAI 的聊天补全端点（GEMINI_API_BASE_URL 默认值为 https://generativelanguage.googleapis.com/v1beta/openai，XAI_API_BASE_URL 默认值为 https://api.x.ai/v1），并使用 Bearer 密钥。gemini-api 与 gemini CLI 试用适配器相互独立。使用全部四个提供商进行辩论时，会计为四个厂商系列（Anthropic、OpenAI、Google、xAI）。

密钥通过权限模式为 0600 的标头文件发送，不会出现在命令行中，也不会由 providers list 打印或发送（它只会检查密钥是否已设置以及 API 是否可访问）。可选项：ANTHROPIC_API_MAX_TOKENS（4096）、OPENAI_API_MAX_TOKENS、GEMINI_API_MAX_TOKENS、XAI_API_MAX_TOKENS（后三者会作为 max_tokens 发送）、ANTHROPIC_API_BASE_URL / OPENAI_API_BASE_URL / GEMINI_API_BASE_URL / XAI_API_BASE_URL（任意兼容端点），以及常用的 E3D_PILOT_PROVIDER_TOKEN_LIMIT 上限。调用费用由密钥所有者承担。

local — 调用兼容 OpenAI 的端点。适合将可自托管的模型（例如通过 Ollama 使用 Qwen）作为第三位协商评审者：

export LOCAL_MODEL_ENDPOINT=http://localhost:11434/v1
export LOCAL_MODEL_NAME=my-model

然后在 providers.negotiate 的任意位置添加 "local"；评审者数量没有硬编码。已配置但不可用的评审者会立即导致失败，不会被静默跳过。

每次通过本地适配器进行的实际调用都会通过整台机器范围内的锁进行串行处理（基于 mkdir 的互斥锁，路径为 ${TMPDIR:-/tmp}/e3d-pilot-qwen.lock，可通过 LOCAL_MODEL_LOCK_DIR 覆盖），因此两个 e3d-pilot 运行（即使针对不同的目标仓库，或由 cron、fleet 模式启动）也绝不会同时访问共享的本地模型端点。这一点很重要，因为本地端点通常由一个驻留内存的模型进程提供服务，供多个仓库的 Agent 使用；并发请求可能导致内存不足，而不仅仅是资源争用。运行会等待锁，最长等待 LOCAL_MODEL_LOCK_TIMEOUT 秒（默认值为 900），超时后失败；被终止进程遗留的过期锁会被自动检测并回收。

如果协商评审者省略了可选的 reason: 字段，系统会合成 "(no reason provided by reviewer)"，而不会解析失败——对于能生成有效 status: 行、但漏掉 reason 字段的小模型，会予以容忍。 execute 阶段默认使用 e3d-code，目前会分派 Codex 和 Claude。实验性的 providers.execute: "grok-build" 路径会在同一经过审批的隔离工作树中直接运行 Grok。e3d-code 仍是推荐的执行器。请参阅 Grok Build 集成与基准测试。

发布

auto 会在远程地址为 github.com 时选择 github，否则选择 local。GitHub 模式只推送运行分支，并调用 gh pr create --draft；绝不会合并或推送基础分支。Local 模式会在不访问网络的情况下提交工作树分支，并写入 publish-summary.md。lib/publish/ 中的脚本共享扩展接口，以便未来添加 GitLab 后端。

只有在验证通过后，发布流程才会将 findings、candidates、negotiation log、final spec 和 e3d-code manifest 强制添加到运行的审计路径下，以便摘要链接在分支上正常解析。创建 GitHub PR 时，会应用 pr.labels 中配置的标签。

通知

运行发布后——此时新分支（以及 GitHub 模式下的草稿 PR）已经存在，随时可供人工查看——e3d-pilot 可以发送一封尽力而为的邮件，这样你就不必亲自去检查。此功能默认关闭：在目标仓库的配置中添加 notify.email 即可，不会影响其他行为。

"notify": {
  "email": {
    "to": "[email protected]"
  }
}

邮件主题会注明分支名称（如果结果为 needs-attention，也会特别说明，例如 GitHub 仓库无法使用 gh）；正文则包含 PR URL 或本地分支/路径，后接与 PR 正文相同的摘要——findings 摘录、选中的 candidate 及其并非重复项的原因、协商结果，以及所有审计文件的链接。

默认情况下，系统会将正文通过标准输入传给 mail -s "$E3D_PILOT_EMAIL_SUBJECT" "$E3D_PILOT_EMAIL_TO"。可以覆盖 notify.email.command，改用 sendmail、msmtp 或调用 SES/SendGrid 等服务的脚本——环境变量相同，传输方式不限：

"notify": {
  "email": {
    "to": "[email protected]",
    "command": "msmtp \"$E3D_PILOT_EMAIL_TO\""
  }
}

如果未配置 notify，或者未配置邮件命令或在 PATH 中找不到该命令，发布仍会成功——通知步骤会降级为空操作（或输出一行警告），而不会导致运行失败。

项目看板跟踪

在 idea 进入 PR 阶段之前，它通常只存在于本地台账（ideas list/show）中——除非有人主动查询，否则无法了解有哪些提议或已获批准的 idea。将 e3d-pilot 指向 GitHub Projects（v2）看板后，它会为每个 idea 创建并同步一张卡片，使其状态与实际生命周期保持一致，从提出到合并全程跟踪：

Idea 状态	看板列
proposed	Backlog
approved_for_implementation、changes_requested、implementation_failed	Ready
implementing	In progress
implemented、approved_for_merge、partially_merged、merge_failed	In review
merged	Done
rejected、closed、reverted	archived（不删除）

此功能默认关闭，需选择启用。通过环境变量为每个仓库统一设置一次（格式与 LOCAL_MODEL_ENDPOINT 相同——一处设置，到处生效）：

export E3D_PILOT_TRACKING_PROJECT_URL="https://github.com/users/<owner>/projects/<n>"

也可以在每个仓库的 .e3d-pilot/config.json 中单独设置（该仓库的配置会覆盖环境变量）：

"tracking": {
  "project_url": "https://github.com/orgs/<org>/projects/<n>"
}

新提议的 idea 会创建一张草稿卡片。idea 进入正式 PR 后，如果看板上已经有该 PR 对应的条目，e3d-pilot 会复用它——包括由项目自身的“auto-add”工作流创建的条目——而不是在旁边留下一张过时的草稿。每次同步都尽力而为：URL 配置错误、缺少 project/read:project gh 身份验证范围，或遇到临时 API 错误时，都会降级为 stderr 警告，绝不会导致命令失败。跟踪状态会与其他所有内容一起记录在只追加的台账中，因此 ideas rebuild 不会丢失 idea 关联的看板条目。

Fleet 模式

提供一个包含仓库路径的 JSON 数组：

e3d-pilot fleet examples/sample-fleet.json

每个仓库都会独立运行。Fleet 会在出现失败后继续执行，输出每个仓库的结果和最终汇总；只要有任一仓库失败，退出状态就为非零。

跨仓库构思

e3d-pilot fleet <repos.json> 有意不考虑跨仓库的机会——每个仓库都会单独运行各自的隔离流水线。e3d-pilot fleet discover 则与之互补：一次性对 fleet 文件中的所有仓库执行组合层面的发现与构思，专门寻找只有在其中 2 个或更多仓库同时存在时才有意义的创意（例如，将一个仓库的数据源与另一个仓库的支付渠道结合起来）。它绝不会提出任何单个仓库独立就能实现的创意——这正是常规 fleet/run 的用途。

e3d-pilot fleet discover examples/sample-fleet.json
e3d-pilot fleet discover examples/sample-fleet.json --focus revenue

它需要单独的小型配置——providers.discover 和 providers.ideate，以及可选的 candidate_scoring（参见 examples/sample-fleet-config.json）——配置文件放在 fleet 文件旁的 .e3d-pilot-fleet/config.json 中，或者传入 --config <path> 指定其他位置。输出会写入 .e3d-pilot-fleet/runs/<run-id>/findings.md 和 candidates.md，其布局与单仓库运行相同：findings.md 包含按仓库整理的 ## Portfolio 摘要（README/AGENTS/CLAUDE 内容、head sha），以及由模型调研生成的 ## Cross-Repo Context 部分；candidates.md 按照单仓库 ideate 的方式对候选项排序，不同之处在于，每个候选项都必须在 Repos: 字段中列出 2 个或更多仓库，并且去重只会检查同一工作区中此前的 fleet discover 运行记录，不会检查各个仓库自身的分支或 PR——这是一个需要了解的实际范围限制。

此阶段会在 .e3d-pilot-fleet/ideas/ 中生成 fleet 创意，并将事件记录在 .e3d-pilot-fleet/events.jsonl 中，然后结束。跨仓库实现仍需明确批准：

e3d-pilot fleet ideas examples/sample-fleet.json list --status proposed
e3d-pilot fleet ideas examples/sample-fleet.json show idea-abc123def456
e3d-pilot fleet ideas examples/sample-fleet.json approve idea-abc123def456 --actor [email protected]
e3d-pilot fleet ideas examples/sample-fleet.json implement idea-abc123def456
e3d-pilot fleet ideas examples/sample-fleet.json implement-approved

fleet 创意会在批准时记录按顺序排列的各仓库目标。目标会按顺序逐一实现。如果部分目标已合并，而之后的目标失败或发生变化，该 fleet 创意会变为 partially_merged；e3d-pilot 会记录哪些仓库已合并，哪些没有。它绝不会声称跨仓库操作具有原子性。

审查 fleet 改进

fleet 运行结束后，fleet prs 会在终端中显示各仓库中未关闭的 e3d-pilot 草稿 PR。使用它来查看状态，而不是作为审批流程：

e3d-pilot fleet prs ~/e3d-fleet.json

repo                    PR     state  idea                                          A   R   effort
────────────────────────────────────────────────────────────────────────────────────────────────
e3d-docs                #1     DRAFT  In-docs "Ask the Docs" AI assistant           5   5   high
e3d-sdk                 #1     DRAFT  MCP-native tool bindings for AI agents        5   4   high
e3d-trade               #1     DRAFT  Trade Decision Receipts                       4   5   medium
  └─ https://github.com/spacepacket1/e3d-sdk/pull/1

如果存在 ~/e3d-fleet.json，默认会使用该文件；否则请传入明确的路径。

建议通过创意账本进行 fleet 审批：

e3d-pilot fleet ideas ~/e3d-fleet.json approve-merge idea-abc123def456 --actor [email protected]
e3d-pilot fleet ideas ~/e3d-fleet.json merge idea-abc123def456
e3d-pilot fleet ideas ~/e3d-fleet.json merge-approved

fleet ideas approve 表示批准实现。fleet ideas approve-merge 表示批准合并经过审核的确切 head SHA。GitHub 审查批准或 fleet prs --approve 操作都不能视为上述任一账本审批。

Web UI（可选）

fleet prs 和 ideas list 可在终端中使用；e3d-pilot web 则是可选的仪表板，供愿意为此安装 Node.js 的用户在浏览器中查看并处理一个或多个仓库中的创意。它并非必需——其他所有 e3d-pilot 命令只需要 Bash、Git、jq 和 curl；如果 Node 不在 PATH 中，e3d-pilot web 会拒绝启动并显示清晰的错误信息。

export E3D_PILOT_WEB_AUTH_USER=you
export E3D_PILOT_WEB_AUTH_PASS='a real secret, not this'
e3d-pilot web --repo /path/to/repo-a --repo /path/to/repo-b --port 4173

打开 http://127.0.0.1:4173（使用上文的基本身份验证凭据），即可查看所有已配置仓库各自的创意台账合并而成的可筛选列表，以及每个创意的详情页，其中包含摘要、评分、去重理由、批准/合并状态、事件历史记录、关联的运行产物和操作按钮（批准、拒绝、请求修改、批准合并、同步、实施）。每项操作都会同步调用完全相同的 e3d-pilot ideas ... 子命令，就像你亲自在命令行中输入一样——Web UI 不会重新实现台账或批准逻辑，因此始终遵循 CLI 的保证。

点击 Implement 会将 e3d-pilot ideas implement 作为分离的后台进程启动（draft → negotiate → execute → review → publish 可能需要 30 分钟以上），运行期间，创意页面会实时显示其 implementation-stage-log.md 日志。

E3D_PILOT_WEB_AUTH_USER 和 E3D_PILOT_WEB_AUTH_PASS 都是必需的；不支持未验证身份的模式。此功能旨在可信任的计算机上运行，或部署在你自己的反向代理/隧道之后——它不内置 TLS、速率限制或多用户账户。

e3d-debate（实验性）

想在编辑器中使用它？e3d-debate 也作为 MCP 工具 提供给 Copilot、Claude Code 和 Cursor 使用。

bin/e3d-debate 是一个独立的独立脚本——没有接入 bin/e3d-pilot 的子命令树或 config.schema.json，与 bin/e3d-backend-benchmark 和 bin/e3d-grok-workers 一样——用于执行“向多个模型提问，看看它们是否真的达成一致”的循环，可应用于任何问题，而不只是仓库工作。它复用了 lib/providers/<name> 适配器和 lib/negotiate/convergence 原语；discover/ideate/negotiate/review 已经依赖这些组件。这里的“实验性”指它仍是独立工具，尚未接入正式流水线——并非无人使用或未经测试：tests/phase34.sh 覆盖了下方的来源关联标志；它也已成为本项目数项实际架构和产品方向决策的决定性机制，而不只是演示。

bin/e3d-debate "Should this service store timestamps as UTC or local time+offset?" \
  --providers claude,codex,devin,grok-build --rounds 3

第 1 轮：每个列出的提供方独立作答。第 2 轮及之后：每个提供方都会看到其他所有提供方上一轮的回答，并被要求重申立场、反驳或让步，最后以 POSITION: <one-line answer> 和 status: approved|revise 作结——“approved”表示：采取该回答的人与采取其他每位参与者当前回答的人会做出相同决定；增加细节或补充注意事项不算意见分歧。一旦所有提供方都报告 approved，lib/negotiate/convergence 就会提前结束辩论，不再耗费剩余轮次。最后一轮结束后（无论是否提前结束），指定的一位 --synthesizer（默认为 claude）会阅读完整记录，并生成 FINAL ANSWER / CONSENSUS / DISSENT 摘要。

任何 lib/providers 适配器都可以参与，包括 devin——如果 Devin/Windsurf 订阅原本会闲置，这就很有用。完整记录（提示词、每一轮的原始回答以及综合结果）默认写入临时目录；也可以通过 --out-dir <path> 指定目录。

默认情况下，辩论结论只会输出到 stdout／记录文件，不会接入任何仓库的来源关系图。传入 --repo <path> --idea <idea-id>（两者必须同时指定，并将 --out-dir 指向 --repo 内的某个位置，例如 docs/debates/<slug>），即可在综合结果生成成功后，自动将结论记录到该仓库账本中已存在的 idea 上；效果等同于手动运行 e3d-pilot ideas note --decision --evidence <transcript-path> <idea-id> "<verdict>"：

bin/e3d-debate "Should we ship it?" --providers claude,codex --repo /path/to/repo --idea idea-abc123 --out-dir /path/to/repo/docs/debates/ship-it

这会关联证据，不会创建 idea——请先通过其他方式单独提出它（例如使用 ideas ingest）。要让证据链接持续有效，记录本身仍需提交，与现有的 docs/debates/ 记录一样。

按计划运行

e3d-pilot 有意不作为守护进程运行——每次调用都是一次短暂的 CLI 调用，运行（或恢复）某个阶段后即退出。它没有内置调度器，因此“持续运行”取决于调用它的方式：cron、systemd 计时器、计划 CI 工作流或你自己的编排器都同样适用。

将自主构思与已批准的实现、同步和数据集导出分开。例如：

# Autonomous single-repo ideation; stops before implementation approval.
0 */6 * * * /path/to/e3d-pilot/bin/e3d-pilot run --repo /path/to/repo --stage all --focus revenue >> /var/log/e3d-pilot-ideate.log 2>&1

# Implement only ideas that humans already approved.
15 * * * * PATH="/usr/local/bin:$PATH" /path/to/e3d-pilot/bin/e3d-pilot ideas implement-approved --repo /path/to/repo >> /var/log/e3d-pilot-implement.log 2>&1

# Observe forge state and invalidate stale merge approvals.
*/30 * * * * PATH="/usr/local/bin:$PATH" /path/to/e3d-pilot/bin/e3d-pilot ideas sync --repo /path/to/repo >> /var/log/e3d-pilot-sync.log 2>&1

# Weekly labeled dataset export for local Qwen evaluation/training.
0 3 * * 1 /path/to/e3d-pilot/bin/e3d-pilot fleet train export /path/to/fleet.json >> /var/log/e3d-pilot-export.log 2>&1

Fleet 中的对应配置：

0 2 * * * PATH="/usr/local/bin:$PATH" LOCAL_MODEL_ENDPOINT="http://127.0.0.1:5050/v1" /path/to/e3d-pilot/bin/e3d-pilot fleet discover /path/to/fleet.json --focus revenue >> /var/log/e3d-pilot-fleet-ideate.log 2>&1
20 * * * * PATH="/usr/local/bin:$PATH" /path/to/e3d-pilot/bin/e3d-pilot fleet ideas /path/to/fleet.json implement-approved >> /var/log/e3d-pilot-fleet-implement.log 2>&1
*/30 * * * * PATH="/usr/local/bin:$PATH" /path/to/e3d-pilot/bin/e3d-pilot fleet ideas /path/to/fleet.json sync >> /var/log/e3d-pilot-fleet-sync.log 2>&1

非零退出码可能表示真正的故障，也可能是合理的停止（ideate 的“无事可做”、需要人工输入的 negotiate 僵局、失败的 verify）——在将其视为崩溃之前，请检查目标仓库中的 .e3d-pilot/runs/<run-id>/。在目标仓库中放置 .e3d-pilot/paused 文件，即可让计划任务不执行任何操作，而无需修改 crontab。

每周导出

使用 fleet 训练命令，汇总 fleet 台账以及 fleet 文件中列出的每个仓库台账：

e3d-pilot fleet train readiness /path/to/fleet.json --since 2026-08-01T00:00:00Z
e3d-pilot fleet train export    /path/to/fleet.json --week 2026-W32

默认情况下，导出文件会写入 .e3d-pilot-fleet/datasets/<YYYY-Www>/ 下的 ideation.jsonl、preferences.jsonl、implementation.jsonl 和 manifest.json。待处理的想法可以作为未标注的构思记录导出，但绝不会作为拒绝示例。明确的批准、拒绝、要求修改、失败、合并、部分合并、关闭、还原和类型化结果会提供标签。

安全模型

发现、构思和可选的 candidate_scoring 不会修改源代码。评分为只读操作，无法执行候选项。起草、协商、执行、审查和发布都需要当前的实现批准。执行使用独立的工作树和每次运行专用的分支。起草时和执行后端运行前，都会检查受保护路径。达到实际文件数／行数上限时，会在审查前停止。验证失败会阻止发布。发布会创建草稿 PR 或本地审查分支。e3d-code 是默认的执行后端；即使 providers.execute 选择了 Grok Build，它也不能绕过这些外层关卡。

合并是单独的操作。approve-merge 会将批准绑定到已观察到的目标集和确切的 PR 头部 SHA。若头部已过期、基础分支已更改、PR 仍是草稿、PR 已关闭、缺少批准或本地合并后端不受支持，合并操作都会拒绝执行。e3d-pilot 绝不会强制推送，也不会直接推送到受保护的基础分支。

项目看板跟踪（见上文）尽力而为，且不属于安全流程：除非明确配置，否则默认关闭；URL 配置错误、缺少 gh 身份验证范围或 API 临时故障只会导致向 stderr 输出警告，不会阻止构思、批准、实现或合并。

可选的 Web UI（见上文）不会赋予自身任何新权限：它公开的每项操作都会直接调用相同的 e3d-pilot ideas ... 子命令，因此无论决策来自终端还是浏览器，都会以相同方式应用批准关卡、状态转换保护和合并 SHA 绑定。

使用以下命令运行仓库测试套件：

set -e
for test_file in tests/*.sh; do bash "$test_file"; done

许可证

MIT © 2026 FutCo LLC。属于 FutCo 开源生态系统的一部分。