Circuit 是一款专为 Claude Code 和 Codex 设计的工作流编排插件，通过结构化的多步骤工作流，帮助 AI 代理自动完成复杂任务，减少人工干预和重复性提示工程。

Circuit：为 Claude Code 和 Codex 打造的工作流编排插件\n\n## 引言：从繁琐提示到一键工作流\n\n在使用 Claude Code 或 Codex 进行开发时，许多开发者都经历过这样的场景：需要反复提示 AI 代理执行一系列步骤——先让它理解技能，再让它制定计划，接着让它审查计划并更新，然后执行，再审查结果，最后可能还需要切换到另一个技能处理代码的不同部分。整个过程充满了不确定性和焦虑感，担心 AI 会遗漏关键细节或偏离正确方向。\n\nCircuit 的出现正是为了解决这一痛点。这款开源插件为 Claude Code 和 Codex 提供了强大的工作流编排能力，让复杂的开发任务可以通过简单的一条命令完成。\n\n## 什么是 Circuit？\n\nCircuit 是一款工作流编排插件，专为 Claude Code 和 Codex 等 AI 编程代理设计。它的核心目标是将原本需要多轮人工提示和" babysitting（看护）"的复杂任务，转化为可重复、自动化的多步骤工作流。\n\nCircuit 的设计理念非常直观：开发者只需要输入类似 /circuit:run build the thing 这样的简单命令，系统就会自动选择合适的工作流，依次执行各个步骤，并在每一步进行检查和验证，最终输出完整的结果报告。\n\n## 核心功能与优势\n\n### 1. 智能工作流选择\n\nCircuit 能够根据用户的自然语言描述，自动选择最合适的内置工作流。目前支持的主要工作流包括：\n\n- Build（构建）：用于代码生成和项目构建\n- Fix（修复）：用于 bug 诊断和修复\n- Review（审查）：用于代码审查和质量检查\n- Explore（探索）：用于代码库分析和理解\n- Pursue（追踪）：用于持续跟进复杂任务\n\n### 2. 并行化与序列化执行\n\nCircuit 不仅能按顺序执行依赖步骤，还能自动识别并并行化那些相互独立的子任务。这种智能调度大大提高了复杂任务的执行效率。\n\n### 3. 技能集成与模型选择\n\nCircuit 允许开发者在特定步骤应用偏好的技能（skills），并为不同步骤配置不同的 AI 模型和思考强度。例如，代码生成步骤可以使用更强的模型，而简单的格式化步骤可以使用轻量级模型。\n\n### 4. 完整的可追溯性\n\n每个工作流执行后，Circuit 都会提供详细的追踪记录、报告和证据，证明工作已按预期完成。这种透明度对于团队协作和代码审查尤为重要。\n\n## 安装与使用\n\n### Claude Code 用户\n\n对于 Claude Code 用户，安装过程非常简单：\n\n\n/plugin marketplace add petekp/circuit\n/plugin install circuit@circuit\n/reload-plugins\n\n\n安装完成后，只需输入：\n\n\n/circuit:run the checkout total is wrong when discounts and tax both apply\n\n\n值得注意的是，安装后的插件是完全自包含的，无需克隆仓库、运行 npm install 或创建符号链接。\n\n### Codex 用户\n\nCodex 用户需要先从仓库刷新本地插件缓存：\n\nbash\nnpm run sync:codex-plugin-cache\n\n\n然后使用 @Circuit 前缀调用：\n\n\n@Circuit the checkout total is wrong when discounts and tax both apply\n\n\n### 本地 CLI 使用\n\n对于希望直接使用命令行的用户：\n\nbash\nnpm install\nnpm run build\n./bin/circuit run --goal '<your task>'\n\n\nCircuit 需要 Node.js 22.18.0 或更高版本。\n\n## 安全机制与透明度\n\nCircuit 在设计时充分考虑了安全性。当某些工作流（如 Build、Fix 和 Pursue）需要调用具有写权限的 worker 时，Circuit 会明确告知用户：\n\n> "This flow may invoke a write-capable Claude Code worker. Circuit will verify and review the result, but the worker can edit files in this checkout."\n\n此外，Review 工作流默认只收集未跟踪文件的路径和大小，而不会读取文件内容，除非用户显式添加 --include-untracked-content 标志并确认这些文件可以安全传输。\n\n## 配置与定制化\n\nCircuit 支持多层配置系统：\n\n1. 用户级配置：~/.config/circuit/config.yaml —— 适用于所有项目的个人默认设置\n2. 项目级配置：./.circuit/config.yaml —— 针对特定项目的覆盖设置\n\n配置内容可以包括：\n- 偏好的 AI 模型和推理强度\n- 本地技能定义\n- 连接器路由规则\n- 特定工作流的覆盖设置\n\n这种分层配置机制让开发者既能保持个人偏好，又能为特定项目定制行为。\n\n## 实际应用场景\n\nCircuit 特别适合以下场景：\n\n### 代码审查自动化\n通过 /circuit:review 命令，可以自动对代码库进行全面的质量检查，包括代码风格、潜在 bug、性能问题等。\n\n### Bug 修复工作流\n当发现 bug 时，/circuit:fix 可以自动诊断问题、制定修复方案、执行修复并验证结果。\n\n### 复杂功能开发\n对于需要多步骤协调的复杂功能开发，/circuit:build 可以管理从需求分析到代码实现再到测试验证的完整流程。\n\n### 代码库探索\n新加入项目时，/circuit:explore 可以帮助快速理解代码库结构、关键模块和依赖关系。\n\n## 技术架构与扩展性\n\nCircuit 采用模块化设计，内置了 claude-code 和 codex 两种 worker 连接器。开发者也可以创建自定义连接器，使用 prompt-file/output-file 协议与 Circuit 集成。\n\n值得注意的是，Codex 在 Circuit 中扮演两种角色：\n- Host/Orchestrator：作为工作流的编排者，选择并调用 Circuit 工作流\n- Worker Connector：作为只读 worker，通过 CLI 接收 Circuit 分派的任务\n\n这种设计让 Circuit 能够灵活适应不同的使用场景和团队工作流。\n\n## 总结与展望\n\nCircuit 代表了 AI 辅助开发工具向更结构化、更自动化方向演进的重要一步。它不仅仅是另一个 CLI 工具，而是一种新的开发范式——让 AI 代理能够按照预定义的高质量流程自主完成复杂任务，同时保持人类开发者的监督和控制。\n\n随着 AI 编程助手的普及，类似 Circuit 这样的工作流编排工具将成为开发工具链中不可或缺的一环。它既保留了 AI 的灵活性和创造力，又通过结构化工作流确保了结果的一致性和可靠性。\n\n对于经常使用 Claude Code 或 Codex 的开发者来说，Circuit 值得一试。它可能会彻底改变你与 AI 编程助手协作的方式，让开发工作变得更加高效和愉快。

Circuit：为 Claude Code 和 Codex 打造的工作流编排插件\n\n引言：从繁琐提示到一键工作流\n\n在使用 Claude Code 或 Codex 进行开发时，许多开发者都经历过这样的场景：需要反复提示 AI 代理执行一系列步骤——先让它理解技能，再让它制定计划，接着让它审查计划并更新，然后执行，再审查结果，最后可能还需要切换到另一个技能处理代码的不同部分。整个过程充满了不确定性和焦虑感，担心 AI 会遗漏关键细节或偏离正确方向。\n\nCircuit 的出现正是为了解决这一痛点。这款开源插件为 Claude Code 和 Codex 提供了强大的工作流编排能力，让复杂的开发任务可以通过简单的一条命令完成。\n\n什么是 Circuit？\n\nCircuit 是一款工作流编排插件，专为 Claude Code 和 Codex 等 AI 编程代理设计。它的核心目标是将原本需要多轮人工提示和" babysitting（看护）"的复杂任务，转化为可重复、自动化的多步骤工作流。\n\nCircuit 的设计理念非常直观：开发者只需要输入类似 /circuit:run build the thing 这样的简单命令，系统就会自动选择合适的工作流，依次执行各个步骤，并在每一步进行检查和验证，最终输出完整的结果报告。\n\n核心功能与优势\n\n1. 智能工作流选择\n\nCircuit 能够根据用户的自然语言描述，自动选择最合适的内置工作流。目前支持的主要工作流包括：\n\n- Build（构建）：用于代码生成和项目构建\n- Fix（修复）：用于 bug 诊断和修复\n- Review（审查）：用于代码审查和质量检查\n- Explore（探索）：用于代码库分析和理解\n- Pursue（追踪）：用于持续跟进复杂任务\n\n2. 并行化与序列化执行\n\nCircuit 不仅能按顺序执行依赖步骤，还能自动识别并并行化那些相互独立的子任务。这种智能调度大大提高了复杂任务的执行效率。\n\n3. 技能集成与模型选择\n\nCircuit 允许开发者在特定步骤应用偏好的技能（skills），并为不同步骤配置不同的 AI 模型和思考强度。例如，代码生成步骤可以使用更强的模型，而简单的格式化步骤可以使用轻量级模型。\n\n4. 完整的可追溯性\n\n每个工作流执行后，Circuit 都会提供详细的追踪记录、报告和证据，证明工作已按预期完成。这种透明度对于团队协作和代码审查尤为重要。\n\n安装与使用\n\nClaude Code 用户\n\n对于 Claude Code 用户，安装过程非常简单：\n\n\n/plugin marketplace add petekp/circuit\n/plugin install circuit@circuit\n/reload-plugins\n\n\n安装完成后，只需输入：\n\n\n/circuit:run the checkout total is wrong when discounts and tax both apply\n\n\n值得注意的是，安装后的插件是完全自包含的，无需克隆仓库、运行 npm install 或创建符号链接。\n\nCodex 用户\n\nCodex 用户需要先从仓库刷新本地插件缓存：\n\nbash\nnpm run sync:codex-plugin-cache\n\n\n然后使用 @Circuit 前缀调用：\n\n\n@Circuit the checkout total is wrong when discounts and tax both apply\n\n\n本地 CLI 使用\n\n对于希望直接使用命令行的用户：\n\nbash\nnpm install\nnpm run build\n./bin/circuit run --goal '<your task>'\n\n\nCircuit 需要 Node.js 22.18.0 或更高版本。\n\n安全机制与透明度\n\nCircuit 在设计时充分考虑了安全性。当某些工作流（如 Build、Fix 和 Pursue）需要调用具有写权限的 worker 时，Circuit 会明确告知用户：\n\n> "This flow may invoke a write-capable Claude Code worker. Circuit will verify and review the result, but the worker can edit files in this checkout."\n\n此外，Review 工作流默认只收集未跟踪文件的路径和大小，而不会读取文件内容，除非用户显式添加 --include-untracked-content 标志并确认这些文件可以安全传输。\n\n配置与定制化\n\nCircuit 支持多层配置系统：\n\n1. 用户级配置：~/.config/circuit/config.yaml —— 适用于所有项目的个人默认设置\n2. 项目级配置：./.circuit/config.yaml —— 针对特定项目的覆盖设置\n\n配置内容可以包括：\n- 偏好的 AI 模型和推理强度\n- 本地技能定义\n- 连接器路由规则\n- 特定工作流的覆盖设置\n\n这种分层配置机制让开发者既能保持个人偏好，又能为特定项目定制行为。\n\n实际应用场景\n\nCircuit 特别适合以下场景：\n\n代码审查自动化\n通过 /circuit:review 命令，可以自动对代码库进行全面的质量检查，包括代码风格、潜在 bug、性能问题等。\n\nBug 修复工作流\n当发现 bug 时，/circuit:fix 可以自动诊断问题、制定修复方案、执行修复并验证结果。\n\n复杂功能开发\n对于需要多步骤协调的复杂功能开发，/circuit:build 可以管理从需求分析到代码实现再到测试验证的完整流程。\n\n代码库探索\n新加入项目时，/circuit:explore 可以帮助快速理解代码库结构、关键模块和依赖关系。\n\n技术架构与扩展性\n\nCircuit 采用模块化设计，内置了 claude-code 和 codex 两种 worker 连接器。开发者也可以创建自定义连接器，使用 prompt-file/output-file 协议与 Circuit 集成。\n\n值得注意的是，Codex 在 Circuit 中扮演两种角色：\n- Host/Orchestrator：作为工作流的编排者，选择并调用 Circuit 工作流\n- Worker Connector：作为只读 worker，通过 CLI 接收 Circuit 分派的任务\n\n这种设计让 Circuit 能够灵活适应不同的使用场景和团队工作流。\n\n总结与展望\n\nCircuit 代表了 AI 辅助开发工具向更结构化、更自动化方向演进的重要一步。它不仅仅是另一个 CLI 工具，而是一种新的开发范式——让 AI 代理能够按照预定义的高质量流程自主完成复杂任务，同时保持人类开发者的监督和控制。\n\n随着 AI 编程助手的普及，类似 Circuit 这样的工作流编排工具将成为开发工具链中不可或缺的一环。它既保留了 AI 的灵活性和创造力，又通过结构化工作流确保了结果的一致性和可靠性。\n\n对于经常使用 Claude Code 或 Codex 的开发者来说，Circuit 值得一试。它可能会彻底改变你与 AI 编程助手协作的方式，让开发工作变得更加高效和愉快。