Archon 工作流运行原理剖析DAG 节点、产物交接与隔离工作树【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本篇技术指南以 Archon 内置工作流archon-fix-github-issue为线索完整拆解一条多步骤 AI 工作流从 YAML 定义到实际执行的底层机制命令如何以 DAG 节点编排、产物artifacts如何在节点间传递上下文、context: fresh为何是防上下文污染的关键以及隔离工作树如何保证主仓库不被触碰。读完你将理解 Archon 确定性、可重复 的设计内核并能据此编写自己的可复现工作流。从一条命令说起archon-fix-github-issue到底是什么当你执行下面的命令时看到的是一次运行实际发生的却是多个 AI 节点在一个 DAG有向无环图中协作、共享一个工作区、并通过一连串文件把上下文从一个阶段传递到下一个阶段archon workflow run archon-fix-github-issue --branch fix/login-crash #142这条命令背后对应的是 Archon 内置默认工作流bundled defaults中的 YAML 定义。在 packages/workflows/src/defaults/bundled-defaults.generated.ts 中可以找到它的完整定义该文件为自动生成产物真正的源文件位于.archon/workflows/defaults/等目录通过bun run generate:bundled重新生成。官方书籍章节 how-it-works.md 用一个简化版的 YAML 展示了它的骨架每个nodes:条目引用一个 markdown 文件——即一个命令command——告诉 AI 该步骤做什么节点通过depends_on声明执行顺序相互独立的节点可以并发运行。name: archon-fix-github-issue nodes: # PHASE 1: CLASSIFY - id: classify command: archon-investigate-issue # Classifies issue type (bug/feature/etc), produces classification artifact # PHASE 2: INVESTIGATE or PLAN - id: investigate command: archon-investigate-issue depends_on: [classify] context: fresh # For bugs: analyzes root cause, creates investigation.md artifact # PHASE 3: IMPLEMENT - id: implement command: archon-fix-issue depends_on: [investigate] context: fresh # Implements fix from investigation, commits (no PR) # PHASE 4: CREATE PR - id: create-pr command: archon-create-pr depends_on: [implement] context: fresh # Pushes branch, creates draft PR linked to issue # PHASE 5: REVIEW - id: code-review command: archon-code-review-agent depends_on: [create-pr] context: fresh # PHASE 6: SELF-FIX - id: self-fix command: archon-self-fix-all depends_on: [code-review] context: fresh # Reads all review artifacts, fixes findings, pushes fix report每个步骤实际做了什么下表摘自 how-it-works 章节并补充完整展示了archon-fix-github-issue这条链路中各阶段、命令、AI 行为与产物的对应关系PhaseCommandWhat the AI DidArtifact ProducedInvestigatearchon-investigate-issueRead the GitHub issue, explored relevant code files, documented root cause and a fix planinvestigation.mdFixarchon-fix-issueReadinvestigation.md, made code changes, ran tests, committed the changesimplementation.mdCreate PRarchon-create-prPushed the branch, created a pull request linked to the issue with a full descriptionPR on GitHubReview scopearchon-pr-review-scopeGathered PR metadata and changed files.pr-number,scope.mdCode reviewarchon-code-review-agentRead the diff with full codebase context, produced structured findingsreview-findings.mdPost reviewarchon-post-review-to-prReadreview-findings.md, posted it as a comment on the PRGitHub PR commentAuto-fixarchon-auto-fix-reviewRead all review artifacts, fixed the surfaced issues, pushed to the PR branch, posted a fix reportGitHub PR comment每个步骤独立而聚焦调研节点不知道 PR 的存在它只负责写文件修复节点不知道代码评审的存在它只读investigation.md并做出修改。是工作流把这一切缝合起来。真实定义比简化版更完整在仓库中的真实定义比章节里的骨架复杂得多。从 bundled-defaults.generated.ts 可以看到完整流水线包含约 20 个节点划分为十个阶段FETCH CLASSIFYparse-request用output_format强制结构化输出user_request、issue_number、repo、repo_url四个字段→fetch-issuebash 节点通过gh issue view拉取 issue→classifyAI 分类节点输出issue_type枚举为 bug/feature/enhancement/refactor/chore/documentation。RESEARCHweb-research与 PR 模板拉取并行。INVESTIGATE / PLAN 路由when: $classify.output.issue_type bug走investigate否则走plan随后bridge-artifacts用trigger_rule: one_success确保investigation.md或plan.md至少存在一个否则显式失败避免把空规格交给 implement 浪费模型调用。IMPLEMENTimplement使用model: large读取investigation.md实施修复。VALIDATEvalidate运行项目自身检查。CREATE DRAFT PRcreate-pr用gh pr create --draft创建草稿 PR并把 PR 号写入$ARTIFACTS_DIR/.pr-number。REVIEWreview-scope→review-classify小模型判定 5 个评审 agent 各自是否启用其中 code-review 必跑→ 5 个评审 agent 按when:条件并行运行。SYNTHESIZE SELF-FIXsynthesize以trigger_rule: one_success汇总self-fix修复全部发现。SIMPLIFYsimplify精简改动。REPORTreport把完成报告回写到 GitHub issue。这就是章节骨架背后真实的生产级形态条件路由、结构化输出、并行评审、失败护栏一应俱全。关键洞察原子、分子与连接器archon-fix-github-issue的运行机制可以用三个概念概括how-it-works 章节的核心结论命令Commands是原子atoms每个命令都是单一的、聚焦的任务用纯 markdown 编写不感知前后节点。在仓库中这些命令同样以字符串形式内置于 bundled-defaults.generated.ts 的BUNDLED_COMMANDS共 54 条内置命令例如archon-fix-issue、archon-pr-review-scope、archon-auto-fix-review等都有完整定义。工作流Workflows是分子moleculesYAML 文件把命令编排成一张有明确目的的图。产物Artifacts是连接器产物是写入共享目录$ARTIFACTS_DIR的文件每个节点都可以读取。调研结束时写investigation.mdimplement 节点启动时读它评审节点运行时读implementation.md——信息就这样在 fresh 上下文的节点之间传递。你也可以手动逐个运行这些命令而工作流只是把这张图自动化了。产物目录的真实环境变量$ARTIFACTS_DIR不是魔法变量它在每个节点执行前由引擎注入。见 packages/workflows/src/exec-environment.tsbuildExecNodeEnvironment会构造完整的环境变量集合环境变量含义ARTIFACTS_DIR本次运行的产物目录节点间共享STATE_DIR状态目录LOG_DIR日志目录WORKFLOW_ID当前工作流 IDBASE_BRANCH目标基础分支USER_MESSAGE/ARGUMENTS用户触发消息LOOP_USER_INPUT/LOOP_PREV_OUTPUT循环节点输入与上一次输出CONTEXT/EXTERNAL_CONTEXT/ISSUE_CONTEXT上下文字段命令如archon-create-pr、archon-pr-review-scope通过$ARTIFACTS_DIR/.pr-number、$ARTIFACTS_DIR/.pr-url这类注册文件在节点间传递 PR 标识这是产物交接的典型用法。产物指针让结果可以指向文件从源码看产物机制还有一层指针设计见 packages/workflows/src/artifact-pointer.ts当一个节点产生大体积结果计划、报告、diff时它可以把结构化摘要与文件位置解耦通过一个保留判别符指向自己运行目录下的文件{ type: archon_artifact, run_id: 01J…, path: plan.md }validateArtifactPointers在生产端校验每个指针路径必须是相对路径、不能包含..、必须指向本运行且存在于产物目录内的常规文件。这保证了结果引用文件的可靠性而不只是命名约定。文件都存放在哪里Archon 使用两套目录树摘自 how-it-works 章节~/.archon/ - User-level data ├── workspaces/ │ └── owner/repo/ │ ├── source/ - Your cloned repo (or symlink) │ ├── worktrees/ - Isolated workspaces per run │ └── artifacts/ - Workflow outputs (never in git) ├── archon.db - SQLite database (conversations, runs) └── config.yaml - Your global settingsyour-repo/.archon/ - Repo-level config (checked into git) ├── commands/ - Your custom commands ├── workflows/ - Your custom workflows └── config.yaml - Repo-specific settings当你执行archon-fix-github-issue --branch fix/my-first-run时Archon 依次做了三件事在~/.archon/workspaces/owner/repo/worktrees/fix/my-first-run创建一个worktree在~/.archon/workspaces/owner/repo/artifacts/下为本次运行创建artifacts 目录在 worktree 内运行所有节点$ARTIFACTS_DIR指向该 artifacts 目录。你的主仓库从头到尾没有被触碰。隔离后端的产物挂载源码佐证隔离机制在 packages/isolation 中实现。以容器后端为例packages/isolation/src/backends/container.ts运行时的 artifacts 目录会被以读写方式绑定挂载到容器内的同一绝对路径——artifactsMount与 source 挂载并列保证容器内写出的产物回到宿主机挂载路径必须位于ARCHON_HOME之内assertMountableHostPath会校验。对应测试见 packages/isolation/src/backends/container.test.ts其中明确覆盖了artifacts 以读写方式绑定在 source 旁的同一绝对路径、恢复容器时缺失 artifacts 挂载会报错等边界情况。上下文与记忆context: fresh为何如此重要注意大多数节点都标记了context: fresh这是刻意设计。每个 AI 节点都在一个 Claude Code 会话中运行。会话会累积上下文——读过的文件、做过的工具调用、对话历史。在调研完一个复杂的代码库问题之后这份上下文可能有数千 token其中大量细节与下一阶段无关。context: fresh为该节点开启一个全新的会话AI 只带着任务指令和它显式读取的产物进场不再背负前序节点的包袱。这就是产物如此重要的原因。它回答了第 5 个节点如何知道第 1 个节点发现了什么——答案是它读了一个文件。全新上下文显式文件交接。The pattern: 把重要发现写进产物。让下一个节点以context: fresh启动。让该节点读取产物。这样每个节点保持聚焦防止上下文跨阶段累积噪声。并发执行中的安全为什么隔离让并行成为可能DAG 编排的另一个价值是并发。在 dag-workflows.md 中可以看到完整说明没有共享依赖的节点会被 Archon 按拓扑分层同层节点并行执行如code-review与security-review同时依赖scope但互不依赖。而并行之所以安全正是因为它发生在彼此隔离的 worktree/容器中——这是 Archon 隔离系统的职责详见 isolation.md 章节。延伸DAG 机制与你如何利用它理解了 how-it-works 之后你可以在 dag-workflows.md 中掌握更进阶的编排能力这些能力正是上述真实工作流在用的底层机制when:条件执行when: $classify.output.issue_type bug这类表达式决定节点是否跳过。注意两点表达式语法错误会 fail-closed节点被跳过而引用无法解析的字段会失败节点而非静默置空。对 AI 生产节点不要拿整个输出与字面量比较模型自由文本不可能与BUG逐字节相同必须用output_format声明字段再比较。output_format结构化输出给 AI 节点一个 JSON Schema引擎会保证节点返回该形状的数据字段可通过$nodeId.output.field点号访问。trigger_rule汇合规则all_success默认、one_success、none_failed_min_one_success、all_done。真实工作流中bridge-artifacts与synthesize都用了one_success因为它们的上游必然有一个节点被when:跳过。节点类型command:、prompt:、bash:、script:runtime: bun|uv、loop:、loop_group:、approval:、cancel:共八种每种节点恰好需要一个模式字段。失败恢复长工作流中途失败时可用archon workflow run name --resume或archon workflow resume id跳过已完成节点继续执行普通archon workflow run总是全新开始。小结archon-fix-github-issue看似一条命令实则是原子命令 分子工作流 产物连接器的完整体系YAML 描述节点图depends_on/when:/output_format/trigger_rule编排路由与并行$ARTIFACTS_DIR让 fresh 上下文的节点之间靠文件交接信息隔离 worktree/容器保证主仓库与并行安全。理解了这套模型你就能从运行内置工作流进阶到编排自己的确定性流水线。Archon 的全部内置工作流清单与选用指南见 essential-workflows.md动手构建第一个自定义工作流的教程在 first-workflow.md。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Archon 工作流运行原理剖析：DAG 节点、产物交接与隔离工作树
Archon 工作流运行原理剖析DAG 节点、产物交接与隔离工作树【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本篇技术指南以 Archon 内置工作流archon-fix-github-issue为线索完整拆解一条多步骤 AI 工作流从 YAML 定义到实际执行的底层机制命令如何以 DAG 节点编排、产物artifacts如何在节点间传递上下文、context: fresh为何是防上下文污染的关键以及隔离工作树如何保证主仓库不被触碰。读完你将理解 Archon 确定性、可重复 的设计内核并能据此编写自己的可复现工作流。从一条命令说起archon-fix-github-issue到底是什么当你执行下面的命令时看到的是一次运行实际发生的却是多个 AI 节点在一个 DAG有向无环图中协作、共享一个工作区、并通过一连串文件把上下文从一个阶段传递到下一个阶段archon workflow run archon-fix-github-issue --branch fix/login-crash #142这条命令背后对应的是 Archon 内置默认工作流bundled defaults中的 YAML 定义。在 packages/workflows/src/defaults/bundled-defaults.generated.ts 中可以找到它的完整定义该文件为自动生成产物真正的源文件位于.archon/workflows/defaults/等目录通过bun run generate:bundled重新生成。官方书籍章节 how-it-works.md 用一个简化版的 YAML 展示了它的骨架每个nodes:条目引用一个 markdown 文件——即一个命令command——告诉 AI 该步骤做什么节点通过depends_on声明执行顺序相互独立的节点可以并发运行。name: archon-fix-github-issue nodes: # PHASE 1: CLASSIFY - id: classify command: archon-investigate-issue # Classifies issue type (bug/feature/etc), produces classification artifact # PHASE 2: INVESTIGATE or PLAN - id: investigate command: archon-investigate-issue depends_on: [classify] context: fresh # For bugs: analyzes root cause, creates investigation.md artifact # PHASE 3: IMPLEMENT - id: implement command: archon-fix-issue depends_on: [investigate] context: fresh # Implements fix from investigation, commits (no PR) # PHASE 4: CREATE PR - id: create-pr command: archon-create-pr depends_on: [implement] context: fresh # Pushes branch, creates draft PR linked to issue # PHASE 5: REVIEW - id: code-review command: archon-code-review-agent depends_on: [create-pr] context: fresh # PHASE 6: SELF-FIX - id: self-fix command: archon-self-fix-all depends_on: [code-review] context: fresh # Reads all review artifacts, fixes findings, pushes fix report每个步骤实际做了什么下表摘自 how-it-works 章节并补充完整展示了archon-fix-github-issue这条链路中各阶段、命令、AI 行为与产物的对应关系PhaseCommandWhat the AI DidArtifact ProducedInvestigatearchon-investigate-issueRead the GitHub issue, explored relevant code files, documented root cause and a fix planinvestigation.mdFixarchon-fix-issueReadinvestigation.md, made code changes, ran tests, committed the changesimplementation.mdCreate PRarchon-create-prPushed the branch, created a pull request linked to the issue with a full descriptionPR on GitHubReview scopearchon-pr-review-scopeGathered PR metadata and changed files.pr-number,scope.mdCode reviewarchon-code-review-agentRead the diff with full codebase context, produced structured findingsreview-findings.mdPost reviewarchon-post-review-to-prReadreview-findings.md, posted it as a comment on the PRGitHub PR commentAuto-fixarchon-auto-fix-reviewRead all review artifacts, fixed the surfaced issues, pushed to the PR branch, posted a fix reportGitHub PR comment每个步骤独立而聚焦调研节点不知道 PR 的存在它只负责写文件修复节点不知道代码评审的存在它只读investigation.md并做出修改。是工作流把这一切缝合起来。真实定义比简化版更完整在仓库中的真实定义比章节里的骨架复杂得多。从 bundled-defaults.generated.ts 可以看到完整流水线包含约 20 个节点划分为十个阶段FETCH CLASSIFYparse-request用output_format强制结构化输出user_request、issue_number、repo、repo_url四个字段→fetch-issuebash 节点通过gh issue view拉取 issue→classifyAI 分类节点输出issue_type枚举为 bug/feature/enhancement/refactor/chore/documentation。RESEARCHweb-research与 PR 模板拉取并行。INVESTIGATE / PLAN 路由when: $classify.output.issue_type bug走investigate否则走plan随后bridge-artifacts用trigger_rule: one_success确保investigation.md或plan.md至少存在一个否则显式失败避免把空规格交给 implement 浪费模型调用。IMPLEMENTimplement使用model: large读取investigation.md实施修复。VALIDATEvalidate运行项目自身检查。CREATE DRAFT PRcreate-pr用gh pr create --draft创建草稿 PR并把 PR 号写入$ARTIFACTS_DIR/.pr-number。REVIEWreview-scope→review-classify小模型判定 5 个评审 agent 各自是否启用其中 code-review 必跑→ 5 个评审 agent 按when:条件并行运行。SYNTHESIZE SELF-FIXsynthesize以trigger_rule: one_success汇总self-fix修复全部发现。SIMPLIFYsimplify精简改动。REPORTreport把完成报告回写到 GitHub issue。这就是章节骨架背后真实的生产级形态条件路由、结构化输出、并行评审、失败护栏一应俱全。关键洞察原子、分子与连接器archon-fix-github-issue的运行机制可以用三个概念概括how-it-works 章节的核心结论命令Commands是原子atoms每个命令都是单一的、聚焦的任务用纯 markdown 编写不感知前后节点。在仓库中这些命令同样以字符串形式内置于 bundled-defaults.generated.ts 的BUNDLED_COMMANDS共 54 条内置命令例如archon-fix-issue、archon-pr-review-scope、archon-auto-fix-review等都有完整定义。工作流Workflows是分子moleculesYAML 文件把命令编排成一张有明确目的的图。产物Artifacts是连接器产物是写入共享目录$ARTIFACTS_DIR的文件每个节点都可以读取。调研结束时写investigation.mdimplement 节点启动时读它评审节点运行时读implementation.md——信息就这样在 fresh 上下文的节点之间传递。你也可以手动逐个运行这些命令而工作流只是把这张图自动化了。产物目录的真实环境变量$ARTIFACTS_DIR不是魔法变量它在每个节点执行前由引擎注入。见 packages/workflows/src/exec-environment.tsbuildExecNodeEnvironment会构造完整的环境变量集合环境变量含义ARTIFACTS_DIR本次运行的产物目录节点间共享STATE_DIR状态目录LOG_DIR日志目录WORKFLOW_ID当前工作流 IDBASE_BRANCH目标基础分支USER_MESSAGE/ARGUMENTS用户触发消息LOOP_USER_INPUT/LOOP_PREV_OUTPUT循环节点输入与上一次输出CONTEXT/EXTERNAL_CONTEXT/ISSUE_CONTEXT上下文字段命令如archon-create-pr、archon-pr-review-scope通过$ARTIFACTS_DIR/.pr-number、$ARTIFACTS_DIR/.pr-url这类注册文件在节点间传递 PR 标识这是产物交接的典型用法。产物指针让结果可以指向文件从源码看产物机制还有一层指针设计见 packages/workflows/src/artifact-pointer.ts当一个节点产生大体积结果计划、报告、diff时它可以把结构化摘要与文件位置解耦通过一个保留判别符指向自己运行目录下的文件{ type: archon_artifact, run_id: 01J…, path: plan.md }validateArtifactPointers在生产端校验每个指针路径必须是相对路径、不能包含..、必须指向本运行且存在于产物目录内的常规文件。这保证了结果引用文件的可靠性而不只是命名约定。文件都存放在哪里Archon 使用两套目录树摘自 how-it-works 章节~/.archon/ - User-level data ├── workspaces/ │ └── owner/repo/ │ ├── source/ - Your cloned repo (or symlink) │ ├── worktrees/ - Isolated workspaces per run │ └── artifacts/ - Workflow outputs (never in git) ├── archon.db - SQLite database (conversations, runs) └── config.yaml - Your global settingsyour-repo/.archon/ - Repo-level config (checked into git) ├── commands/ - Your custom commands ├── workflows/ - Your custom workflows └── config.yaml - Repo-specific settings当你执行archon-fix-github-issue --branch fix/my-first-run时Archon 依次做了三件事在~/.archon/workspaces/owner/repo/worktrees/fix/my-first-run创建一个worktree在~/.archon/workspaces/owner/repo/artifacts/下为本次运行创建artifacts 目录在 worktree 内运行所有节点$ARTIFACTS_DIR指向该 artifacts 目录。你的主仓库从头到尾没有被触碰。隔离后端的产物挂载源码佐证隔离机制在 packages/isolation 中实现。以容器后端为例packages/isolation/src/backends/container.ts运行时的 artifacts 目录会被以读写方式绑定挂载到容器内的同一绝对路径——artifactsMount与 source 挂载并列保证容器内写出的产物回到宿主机挂载路径必须位于ARCHON_HOME之内assertMountableHostPath会校验。对应测试见 packages/isolation/src/backends/container.test.ts其中明确覆盖了artifacts 以读写方式绑定在 source 旁的同一绝对路径、恢复容器时缺失 artifacts 挂载会报错等边界情况。上下文与记忆context: fresh为何如此重要注意大多数节点都标记了context: fresh这是刻意设计。每个 AI 节点都在一个 Claude Code 会话中运行。会话会累积上下文——读过的文件、做过的工具调用、对话历史。在调研完一个复杂的代码库问题之后这份上下文可能有数千 token其中大量细节与下一阶段无关。context: fresh为该节点开启一个全新的会话AI 只带着任务指令和它显式读取的产物进场不再背负前序节点的包袱。这就是产物如此重要的原因。它回答了第 5 个节点如何知道第 1 个节点发现了什么——答案是它读了一个文件。全新上下文显式文件交接。The pattern: 把重要发现写进产物。让下一个节点以context: fresh启动。让该节点读取产物。这样每个节点保持聚焦防止上下文跨阶段累积噪声。并发执行中的安全为什么隔离让并行成为可能DAG 编排的另一个价值是并发。在 dag-workflows.md 中可以看到完整说明没有共享依赖的节点会被 Archon 按拓扑分层同层节点并行执行如code-review与security-review同时依赖scope但互不依赖。而并行之所以安全正是因为它发生在彼此隔离的 worktree/容器中——这是 Archon 隔离系统的职责详见 isolation.md 章节。延伸DAG 机制与你如何利用它理解了 how-it-works 之后你可以在 dag-workflows.md 中掌握更进阶的编排能力这些能力正是上述真实工作流在用的底层机制when:条件执行when: $classify.output.issue_type bug这类表达式决定节点是否跳过。注意两点表达式语法错误会 fail-closed节点被跳过而引用无法解析的字段会失败节点而非静默置空。对 AI 生产节点不要拿整个输出与字面量比较模型自由文本不可能与BUG逐字节相同必须用output_format声明字段再比较。output_format结构化输出给 AI 节点一个 JSON Schema引擎会保证节点返回该形状的数据字段可通过$nodeId.output.field点号访问。trigger_rule汇合规则all_success默认、one_success、none_failed_min_one_success、all_done。真实工作流中bridge-artifacts与synthesize都用了one_success因为它们的上游必然有一个节点被when:跳过。节点类型command:、prompt:、bash:、script:runtime: bun|uv、loop:、loop_group:、approval:、cancel:共八种每种节点恰好需要一个模式字段。失败恢复长工作流中途失败时可用archon workflow run name --resume或archon workflow resume id跳过已完成节点继续执行普通archon workflow run总是全新开始。小结archon-fix-github-issue看似一条命令实则是原子命令 分子工作流 产物连接器的完整体系YAML 描述节点图depends_on/when:/output_format/trigger_rule编排路由与并行$ARTIFACTS_DIR让 fresh 上下文的节点之间靠文件交接信息隔离 worktree/容器保证主仓库与并行安全。理解了这套模型你就能从运行内置工作流进阶到编排自己的确定性流水线。Archon 的全部内置工作流清单与选用指南见 essential-workflows.md动手构建第一个自定义工作流的教程在 first-workflow.md。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考