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/ArchonArchon 是一个面向 AI 编码的编排器harness它通过四个核心概念来编排 AI 编码 AgentWorkflow工作流、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/对所有仓库生效、projectrepoRoot/.archon/workflows/仓库级。同名文件按bundled global project的优先级覆盖这一来源模型定义在 workflow.ts。Nodes六种基础构件Node是工作流的基本构件。每个节点只做一件事且必须从以下六种类型中精确选择一种Type作用command:加载一个命令文件打包工作流使用包内命令传统工作流使用共享命令并发送给 AI Agentprompt:将一段内联提示词字符串发送给 AI Agentbash:运行一段 shell 脚本不经过 AI。stdout 会被捕获为$nodeId.outputloop:反复运行一段 AI 提示词直到检测到完成信号approval:暂停工作流等待人工审查批准或拒绝cancel:携带一个原因字符串提前终止工作流在源码的DagNode判别联合discriminated union中这六种 YAML 形态会被归并为agentcommand/prompt、execbash/script、gateapproval、haltcancel、wait、loop/loop_group等运行形态见 dag-node.ts。连接、分支与汇合控制节点通过depends_on连接成 DAG此外还支持when:条件分支用表达式控制是否执行trigger_rule:汇合规则控制多依赖节点的触发时机。源码中的四种取值见 dag-node.tsall_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 FEATUREoutput_format为节点输出声明 JSON Schema从而让$classify.output.type这类字段引用拥有严格的类型校验。除上述基础字段外节点还支持contextfresh/shared/resume、retry、idle_timeout、allowed_tools/denied_tools、effort、model/provider覆盖等众多配置完整字段集可参阅 dag-node.ts 的dagNodeBaseSchema。CommandsMarkdown 提示词模板Command是一个 Markdown 提示词模板。打包工作流packaged workflow只从自己所属的commands/目录加载命令传统工作流legacy workflow则按仓库 → 用户主目录 → 内置默认的顺序搜索共享命令。Archon 会完成变量替换后把结果发送给 AI。常用变量变量解析为$ARGUMENTS用户的输入消息$ARTIFACTS_DIR为工作流产物预创建的目录$BASE_BRANCH基础分支自动检测或配置$DOCS_DIR文档目录路径默认docs/$WORKFLOW_ID当前工作流运行的唯一 ID完整的变量清单含$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/下同名命令会覆盖内置默认——这一就近覆盖机制让你可以为每个项目定制行为同时不必复制整套默认文件。IsolationWorktrees每次运行的隔离工作区默认情况下每次工作流运行都会获得一个独立的 git worktree——仓库的一个隔离副本。这带来三个好处工作分支保持干净工作流的所有改动都发生在独立目录中多个工作流可并行运行互不冲突失败的运行不留垃圾通过archon isolation cleanup清理。存储位置与生命周期worktree 位于~/.archon/workspaces/owner/repo/worktrees/每个 worktree 拥有自己的分支你可以检查其产出、从它创建 PR或直接丢弃。对应的底层实现是WorktreeProviderpackages/isolation/src/providers/worktree.ts它按workflowType identifier生成分支名例如 issue42→issue-42taskmy-feature→task-my-feature并在创建前优先收养adopt已存在的 worktree。退出隔离如果希望直接在检出目录中运行不隔离传入--no-worktreearchon 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 branchFolder 项目与 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 的运行模型你用一个CommandMarkdown 模板或内联prompt表达让 AI 做什么Workflow把多个这样的步骤编排成 DAG通过depends_on、when、trigger_rule控制分支与汇合每次运行默认落在独立的worktree中保证并行安全与工作区干净当目录不是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考