circuit

运行 Circuit

Circuit 会将编码任务转化为一次指定流程的运行：这是一个可重复执行的过程，包含类型化报告、验证、检查点，以及可供审计的追踪记录。 在启用了 Circuit 的项目中，默认做法是：将实质性工作交给 Circuit，而不是自行临时处理。 这不是为了走形式。一次运行会留下证据（尝试了什么、验证了什么、审查者说了什么），能够应对中断（从检查点恢复），还能不断积累改进（在一个地方优化流程，而不是每次会话都重新摸索）。

何时通过 Circuit 处理，何时不需要

当任务有明确内容时，就通过 Circuit 处理：修复错误、构建功能、调查决策、审查差异，或尝试原型。这涵盖了大多数编码工作。

以下情况可直接处理（不运行流程）：

• 任务简单或只是对话性质：一句话的回答、重命名，或通过阅读一个文件就能回答的代码问题。
• 你已经作为转交任务的工作者处于一次 Circuit 运行中。切勿在其中启动嵌套的 Circuit 运行；直接完成转交的工作。
• 用户明确要求跳过 Circuit，或正在调试 Circuit 本身，而运行流程会造成混淆。
• 未安装 Circuit，且用户没有要求使用。（先检查再假定；参见“找到入口”。）

对于边界情况，如果你决定跳过 Circuit，请用一句话说明，方便用户让你改用其他方式。

找到入口

解析顺序：

1. 已安装 Claude Code 插件： 优先使用 /circuit:run <task> 语义。 具体来说，就是插件包装器： node "${CLAUDE_PLUGIN_ROOT}/scripts/circuit.js" present run <flow> --goal '<task>'。 present 模式会为用户呈现进度和检查点问题；不要将其输出解析为 JSON。
2. 在 Circuit 检出目录中工作： 从仓库根目录运行 ./bin/circuit run <flow> --goal '<task>'（它会从 generated/flows 加载已编译的流程）。
3. 全局 CLI： circuit run <flow> --goal '<task>'。

如果不确定环境是否正常，运行 circuit doctor 查看就绪状态：它会在运行因连接器故障而浪费资源之前，检查流程实际会用到的连接器 CLI（是否已安装、是否已登录），并打印每个问题的修复方法。所有选定的连接器都正常时，它会以状态码 0 退出；配置从未选择的连接器会单独列为可选项，不会导致检查失败。

Shell 安全：始终为 --goal 文本使用单引号。内部的撇号需转义为 '\''。任务文本由用户控制；使用双引号会导致 $VAR 和 $(cmd) 被展开。

选择流程

CLI 始终要求指定流程名称；由你选择。调用前说明你的选择，并用一句话解释原因，方便用户调整。

流程	适用情况	是否会写入？
Fix	错误、回归、测试失败、崩溃、间歇性故障、生产问题。	是
Build	功能、重构、文档、测试；并非主要用于修复错误的聚焦改动。	是
Explore	调查、解释、权衡比较，以及编辑前的决策。	否
Review	审计代码、差异、PR、计划或风险面。仅审计。	否
Prototype	Build 前的一次性原型、模型图、UI 草图、模型对比变体。	本地原型证据

出于安全考虑，有两种分流情况需要留意；只有确实不明确时才简短提问：Review 与 Fix/Build（审计还是修改），以及 Explore 与 Build（决策还是执行）。 其他情况不要追问用户；选定流程并说明原因。

如果用户说明了任务的重要性（风险、能够解决什么阻碍），请将其作为 --why '<reason>' 传入。切勿自行编造。

效能拨盘

• --power <auto|low|medium|high> 是唯一的拨盘（默认值为 medium）。它设置每个工作者使用的模型规模，无需指定模型名称，同时也会推导运行流程的细致程度：low/medium/high 直接对应，auto 推导为 medium，并让运行根据研究步骤读取的内容自行选择模型等级。推导出的细致程度会静默限制在各流程支持的范围内（Build、Explore 和 Fix 支持完整等级；Prototype 的最低等级为 medium；Review 始终运行 medium）。
• --process <low|medium|high> 是高级覆盖选项，适用于少数需要将模型能力与流程细致程度分开的情况（例如，使用强模型进行快速单轮处理）。明确指定的 --process 优先于推导结果。在 Fix 中，process low 会跳过独立审查阶段。在 Build 中，process high 会逐个计划切片进行迭代，并在每个切片后验证，还会在执行可写入操作前停在接收检查点——因此，只指定 --power high 的 Build 运行会暂停一次，以确认范围。--depth 已弃用，作为未知选项会被拒绝。

让成本与风险相匹配：针对小型修复进行快速合理性检查 → --power low。对关键路径进行高风险更改 → --power high。默认值适用于大多数任务。在启动高成本运行之前，circuit preview <flow> --power high 会准确显示每个步骤将使用的连接器、模型和工作量，且不会启动任何操作；--matrix 会并排显示所有等级。

支持时，还可使用另外两种运行模式：--tournament [2|3|4]（可选的内联数量，默认值为 3） （探索决策选项；Prototype 实现变体，并依据评估标准进行判断）以及 --autonomous（Build、Explore、Fix、Prototype： 自动处理支持的检查点，并驱动有界的持续执行循环，必须根据接收阶段设定的证据证明已完成——不会因为尝试次数用尽就报告完成）。

查看一次运行

每次运行都会在 .circuit/runs/<run-id>/ 下写入一个运行文件夹：其中包含 trace.ndjson（按顺序记录所有内容）、reports/ 下的类型化报告（包括面向用户的 operator-summary.md 和包含 selected_flow、outcome、run_folder 的 result.json），以及证据。用户询问“那次运行发生了什么”时，请先阅读 reports/operator-summary.md，只有需要查看步骤级细节时才查看跟踪记录。

退出代码是一项约定：完成时退出代码为 0；在检查点暂停时也退出代码为 0（运行已停放，等待处理）；任何未完成的结束状态（已中止、已停止、已升级、已移交）都会以 1 退出；用法错误以 2 退出。因此，使用 && 链接的命令只会在运行完成后继续执行。

检查点。 运行暂停并提出问题时，请如实转达问题给用户，然后恢复运行：

circuit resume --run-folder '<run_folder>' --checkpoint-choice '<choice>'

circuit checkpoints 会列出所有停在决策环节的运行，以及各自的问题、选项和准确的恢复命令。用户返回项目或询问“有什么事在等我处理吗？”时，请检查此列表。

连续性。 circuit handoff save 会记录跨会话移交；handoff resume 和 handoff brief 会恢复并总结移交内容。会话必须在工作进行到一半时结束的情况下，请使用这些命令。

配置

两个 YAML 文件使用相同的架构，按 defaults < user-global < project < invocation 的顺序分层：

• ~/.config/circuit/config.yaml — 个人默认值。
• ./.circuit/config.yaml — 项目覆盖项。

从最简配置（schema_version: 1）开始，只添加所需内容。使用 circuit config set|unset|show <dotted.key> [value] [--global] 进行编辑（写入前会验证，并保留注释），也可以直接编辑 YAML。

最实用的配置项，按实际使用需求排序：

1. 连接器路由 — 每种角色/流程由哪个 CLI 执行： relay.roles.reviewer、relay.circuits.<flow>、relay.default。 内置连接器：claude-code（在同一工作区中可信地写入）、codex （通过 codex exec 具备写入能力）、cursor-agent（Gemini 实现者）。
2. 能力 — defaults.power、power_auto: {floor, ceiling}，以及 power_tiers.<connector>，用于重新映射每个档位代表的含义。
3. 技能 — Circuit 会将本地的 SKILL.md 文件 （~/.agents/skills、~/.claude/skills）注入 relay 提示词： 使用 circuits.<flow>.selection.skills 始终加载某个技能；使用 skill_hooks 仅在触发特定时机时加载技能（例如，after:edit-files:.tsx → React 技能，after:verification-failed → 调试技能）。
4. 按流程固定模型 — circuits.<flow>.selection.model 可将某个流程固定到 一个模型；此时档位不再影响它。

每次更改配置后都运行 circuit preview <flow>：它会解析真实运行所用的相同选择逻辑，并在你付费运行前标出问题。

完整配置方案（自定义连接器、本地 Ollama worker、锦标赛变体）： 请参阅 references/configuration.md。

创建新流程：先判断是否有必要

Circuit 可以低成本创建新流程。正因如此，你更应该谨慎行事。每个发布的流程都会给用户的生活带来一个永久的问题：“这件事该用哪个流程？”流程目录一旦超出用户的记忆范围，就会摧毁产品的核心价值：让正确的流程一目了然。流程应该少而精、各有特色、彼此协调并相互增强——绝不能划分出重叠的领域，让用户不得不自行判断。

因此，当你发现某个反复出现的模式没有流程适用时，沿着下面的阶梯逐步尝试，并在第一个可行的步骤停下：

1. 调节参数和措辞。 用不同的深度、力度，或更明确的 --goal 调整现有流程，能解决问题吗？通常可以。
2. 配置。 为现有流程添加技能（selection.skills）、技能钩子或连接器路由。“我们总是在修复过程中忘记 X”属于技能钩子问题，而不是新流程问题。
3. 记忆笔记。 circuit memory note --flow fix "prefer minimal repros before patching" 可以记录指导原则，无须增加任何新入口。笔记会引用真实的运行产物，因此只有在项目至少运行过一次后才适用；对于全新的项目，应先运行，再记笔记。
4. 一次性定制流程。 circuit generate --description '<task>' 会为不常见的任务形式组合出一次性流程。用完即可弃用；不要仅仅因为它成功过一次就发布它。
5. 发布自定义流程。 只有当同一种独特的任务形式反复出现（遵循三次规则）、没有内置流程覆盖它，且不会让任何现有选项更难选择时，才这样做。circuit create --name '<slug>' --description '<idea>' 会实例化一个经过验证的流程模板。

在执行第 5 步之前，先向用户明确说明理由，并征得同意：

• 领域测试： 将新流程与六个内置流程并列，各用一句话描述。如果任何一对流程都可能适用于同一任务，说明边界不清楚；应进一步明确边界，或停止。
• 名称测试： 六周后，用户能否仅凭名称判断何时该使用它？
• 增强测试： 它是否为其他流程提供输入或复用其他流程的内容（产出内置流程会使用的证据，或组合内置流程模块），还是会分裂成一个平行体系？优先选择能增强现有流程集合的流程。
• 退役： 如果某个自定义流程不再值得保留，建议移除它。目录小巧本身就是一种优势。

有关 create 和 generate 的机制、自定义流程的存放位置、验证方式，以及如何运行已发布的自定义流程，请参阅 references/flow-authoring.md。

与用户沟通

始终简洁直白。运行记录已经包含详细信息——追踪记录、类型化报告和操作员摘要，因此聊天中只保留用户必须决定或了解的内容。丰富的细节应放在 --goal 文本中（供工作进程使用），以及运行文件夹中（便于审计），而不是聊天里。假设用户不关心 Circuit 的内部机制；他们想要的是把工作处理好，并能一眼看懂结果。句子要短，每句只表达一个意思。使用通俗词语，而非运行时术语：说“它暂停下来问你 X”，不要说检查点 ID、路由名称或追踪类型。也不要使用辅助标签（“用一句话说明原因：”“这种形式的原因：”）——直接说明即可。

始终使用同一种结果卡片，绝不临时发挥。 用户每次看到相同格式，就能一眼读懂；每次换一种布局，都得重新阅读。聊天在终端中以纯文本呈现，因此卡片必须使用围栏代码块，且只能包含 ASCII 字符。提议运行时：

circuit · fix — release-blocking bug in checkout totals
  power  [##.] medium   default; process follows the dial

刻度指示：低 [ #..]，中 [##.]，高 [###]，自动 [~~~]。只有当 --process 明确覆盖推导出的值时，才添加 process 行；只有启用了 tournament 或 autonomous 时，才添加 mode 行。卡片前后最多各用一两句话。结束运行时沿用相同格式，将刻度行替换为结果行：

circuit · fix — complete
  changed   src/cart.js · tests/cart.test.js
  verified  7/7 tests pass
  evidence  .circuit/runs/<run-id>/

暂停时也使用同一张卡片，并标注 — paused, needs your call，再添加 question / choices 行。不要在卡片之间讲述内部机制；present 封装层已经会显示进度。

• 不要在聊天中展示 CLI。不要显示你为检查或验证而运行的命令（preview、config show、doctor）；用通俗的话说明这些命令验证了什么。只有用户必须亲自运行命令，或明确要求查看时，才展示命令。
• 文件也一样：不要把配置 YAML 或报告内容粘贴到聊天中。用一句通俗的话说明每项更改的作用，并附上文件路径，方便用户打开查看。
• 当运行未能完成便结束时，如实报告结果，并说明证据所在位置。绝不要把 stopped 包装成已完成。诚实和简洁并不矛盾：“在审核阶段停止，发现两项问题，证据位于 ”两者兼具。
• Build、Fix 和 Prototype 在开始可能写入内容的工作前，必须明确告知用户：工作进程可能会修改工作区。不要隐瞒这一点。
• Review 未跟踪文件时，只有在用户确认这些内容可安全发送给工作进程后，才添加 --include-untracked-content。
• 如果运行无法恢复，可以安全删除其位于 .circuit/runs/ 下的文件夹，然后重新开始。circuit reclaim 会清理被终止的 fanout 遗留的孤立工作树。

参考文件

• references/cli.md — 所有命令和标志及示例：run、resume、handoff、history、memory、create、generate、uninstall、runs、reclaim、checkpoints、preview、doctor、config、version。
• references/configuration.md — 完整的配置架构示例：路由、功率等级、自动功率、技能、技能钩子、自定义连接器、本地模型、tournament 变体。
• references/flow-authoring.md — 创建、生成、验证、发布和弃用自定义工作流；完整的防止工作流泛滥检查清单；以及如何在 Circuit 仓库中编写内置工作流。