Archon 核心概念详解：Workflow、Node、Command 与隔离机制

Archon 核心概念详解：Workflow、Node、Command 与隔离机制

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

Archon 是一个面向 AI 编码的编排器（harness），它通过四个核心概念来"编排" AI 编码 Agent：Workflow（工作流）、Node（节点）、Command（命令）与 Isolation（隔离）。本文以 getting-started/concepts.md 为主线，结合 packages/workflows/src/schemas/workflow.ts、dag-node.ts 等源码实现，系统讲解这套概念体系，帮助读者快速建立心智模型，并能在真实仓库中编写、运行、排查自己的工作流。

Workflows：以 YAML 定义的 DAG 任务

Workflow是一个 YAML 文件，把一个多步骤的 AI 编码任务描述为有向无环图（DAG）。每个 workflow 存放在.archon/workflows/目录下，包含名称（name）、描述（description）以及一组声明了依赖关系的节点（nodes）。

name: fix-issue description: Investigate and fix a GitHub issue nodes: - id: investigate command: investigate-issue - id: implement command: implement-issue depends_on: [investigate] context: fresh

执行语义：并行扇出与汇合

• 没有依赖的节点立即执行；
• 同一依赖层的节点并行运行——例如三个互不依赖的 review 节点会同时扇出（fan out）并发执行；
• 下游节点在它所依赖的所有节点完成后汇合（converge）。

从源码看，这一规划被物化为GraphPlan（见 workflow.ts）：包含nodes、layers（按依赖层级分组的节点序列）与sinks（汇合节点），由执行器按层推进。

内置默认工作流

Archon 自带一批打包好的默认工作流，例如：

• archon-assist：通用助手模式，处理问题排查、调试、探索等无法匹配具体工作流的请求；
• archon-smart-pr-review：先评估 PR 复杂度再只路由相关审查 Agent 的智能 PR 审查；
• archon-validate-pr：同时在 main 分支（复现 bug）与 feature 分支（验证修复）上做端到端校验并给出结论。

这些默认定义内嵌在 packages/workflows/src/defaults/bundled-defaults.generated.ts 中，通过archon workflow list可以查看当前可用列表，也可以在.archon/workflows/defaults/下浏览真实示例。CLI 子命令支持按名称过滤与--full/--json输出（用法为archon workflow list [name] [--full] [--json]，见 packages/cli/src/cli.ts）。

工作流的来源有三种：bundled（内嵌于二进制）、global（~/.archon/workflows/，对所有仓库生效）、project（<repoRoot>/.archon/workflows/，仓库级）。同名文件按bundled < global < project的优先级覆盖，这一来源模型定义在 workflow.ts。

Nodes：六种基础构件

Node是工作流的基本构件。每个节点只做一件事，且必须从以下六种类型中精确选择一种：

在源码的DagNode判别联合（discriminated union）中，这六种 YAML 形态会被归并为agent（command/prompt）、exec（bash/script）、gate（approval）、halt（cancel）、wait、loop/loop_group等运行形态（见 dag-node.ts）。

连接、分支与汇合控制

节点通过depends_on连接成 DAG，此外还支持：

• when:条件分支：用表达式控制是否执行；
• trigger_rule:汇合规则：控制多依赖节点的触发时机。源码中的四种取值见 dag-node.ts：all_success（全部成功）、one_success（任一成功）、none_failed_min_one_success（无失败且至少一个成功）、all_done（全部结束，不论成败）；
• 按节点覆盖 AI Provider / Model。

下面是一个典型的分支示例：先分类，再按分类结果走不同的下游节点。

nodes: - id: classify command: classify-issue output_format: type: object properties: type: { type: string, enum: [BUG, FEATURE] } required: [type] - id: fix-bug command: fix-bug depends_on: [classify] when: "$classify.output.type == 'BUG'" - id: build-feature command: build-feature depends_on: [classify] when: "$classify.output.type == 'FEATURE'"

output_format为节点输出声明 JSON Schema，从而让$classify.output.type这类字段引用拥有严格的类型校验。除上述基础字段外，节点还支持context（fresh/shared/resume）、retry、idle_timeout、allowed_tools/denied_tools、effort、model/provider覆盖等众多配置，完整字段集可参阅 dag-node.ts 的dagNodeBaseSchema。

Commands：Markdown 提示词模板

Command是一个 Markdown 提示词模板。打包工作流（packaged workflow）只从自己所属的commands/目录加载命令；传统工作流（legacy workflow）则按"仓库 → 用户主目录 → 内置默认"的顺序搜索共享命令。Archon 会完成变量替换后把结果发送给 AI。

常用变量

完整的变量清单（含$USER_MESSAGE别名、$STATE_DIR跨运行持久状态目录、$CONTEXT/$ISSUE_CONTEXT上下文别名、循环相关$LOOP_USER_INPUT/$LOOP_PREV_OUTPUT以及节点输出引用$nodeId.output/$nodeId.output.field）见 Variable Reference，其中还明确了替换顺序（先工作流变量 → 上下文变量 → 节点输出引用）与各变量在不同上下文中的可用性矩阵。

注意：Archon不支持位置参数（$1、$2……$9），用户的完整触发消息只通过$ARGUMENTS/$USER_MESSAGE传递；需要结构化输入时应在命令体内自行解析。

默认命令与覆盖

Archon 内置了 investigation、implementation、code review 等常见操作的默认命令。仓库级的.archon/commands/下同名命令会覆盖内置默认——这一"就近覆盖"机制让你可以为每个项目定制行为，同时不必复制整套默认文件。

Isolation（Worktrees）：每次运行的隔离工作区

默认情况下，每次工作流运行都会获得一个独立的 git worktree——仓库的一个隔离副本。这带来三个好处：

1. 工作分支保持干净：工作流的所有改动都发生在独立目录中；
2. 多个工作流可并行运行：互不冲突；
3. 失败的运行不留垃圾：通过archon isolation cleanup清理。

存储位置与生命周期

worktree 位于~/.archon/workspaces/<owner>/<repo>/worktrees/，每个 worktree 拥有自己的分支，你可以检查其产出、从它创建 PR，或直接丢弃。对应的底层实现是WorktreeProvider（packages/isolation/src/providers/worktree.ts），它按workflowType + identifier生成分支名（例如 issue"42"→issue-42，task"my-feature"→task-my-feature），并在创建前优先收养（adopt）已存在的 worktree。

退出隔离

如果希望直接在检出目录中运行（不隔离），传入--no-worktree：

archon workflow run quick-fix --no-worktree "Fix the typo in README"

也可以在工作流 YAML 顶层通过worktree.enabled显式钉住隔离策略（true强制隔离、false强制不隔离、缺省由调用方决定），该策略字段定义在 workflow.ts。注意内置的archon-assist就声明了worktree.enabled: false，因为自动路由的通用助手需要直接在调用会话所在的 working tree 中落盘改动，否则编辑结果无法回传。

分支收尾

当某个 worktree 分支的工作完成时，用一条命令清理全部内容（worktree + 本地分支 + 远端分支）：

archon complete <branch-name>

该命令实现在 packages/cli/src/commands/isolation.ts，内部会先做若干安全检查（未推送提交、PR 状态、唯一提交等），再执行清理，并汇总输出Complete: N completed, M failed, K not found之类的报告；失败时可通过--force跳过校验强制完成。

Folder Projects：非 Git 工作区

Project并不必须是 git 仓库。Folder Project指任何目录——无论是包含多个服务仓库的multi-repo 根目录，还是完全没有 git 的纯业务运维目录——都可以注册为 Archon 的一等公民项目，获得与 repo 项目相同的身份、项目级环境变量、运行历史，以及按名称归档的产物/日志存储。

注册与运行

使用--folder注册并运行：

# 从一个 multi-repo 根目录（它本身不是 git 仓库） cd ~/platform # 包含 auth-service/、billing-service/、…… archon workflow run assist --folder "List every service and its current branch"

Folder 项目与 Repo 项目的诚实差异

• 默认就地运行，无 worktree 隔离：Agent 的工作目录就是 folder 根目录，因此能看到所有子文件夹与子仓库；每个服务的 git 操作（分支、提交、PR）由 Agent 通过bash/gh自行负责，而不是 Archon 的职责。若希望写入不污染运行中的实时根目录，可传--container（或在配置中设置container.enabled）改用 overlay 隔离的 Docker 容器运行，详见 Configuration → Container isolation (folder projects)。
• --branch/--from会被拒绝（没有 worktree 可创建），/worktree报告 "not applicable"。
• 产物与日志存放在~/.archon/workspaces/_folder/<slug>/，而不是<owner>/<repo>/。
• 注册是显式的：通过 CLI 的--folder、Web 控制台添加项目时的path字段，或聊天中的/register-project（非 git 路径会被自动识别为 folder）。

注册之后，从该 folder 根目录下的任何位置运行工作流或聊天都无需再传--folder。

小结：四概念如何协同

把这四个概念串起来，就得到了 Archon 的运行模型：

1. 你用一个Command（Markdown 模板）或内联prompt表达"让 AI 做什么"；
2. Workflow把多个这样的步骤编排成 DAG，通过depends_on、when、trigger_rule控制分支与汇合；
3. 每次运行默认落在独立的worktree中，保证并行安全与工作区干净；
4. 当目录不是 git 仓库时，Folder Project提供了同等的一等公民体验（身份、环境变量、历史、产物），代价是默认就地运行、无隔离。

进一步学习路径：

• Quick Start —— 运行你的第一个工作流；
• Authoring Workflows —— 编写自己的多步工作流；
• Authoring Commands —— 编写高效的提示词模板；
• Variable Reference —— 全部受支持的变量。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon