Archon 工作流编写实战以结果为导向设计可治理、可验证的 AI 流程【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/ArchonArchon 是面向 AI 编程的可复现流程编排框架其核心单元是工作流workflow——用 YAML 描述的一组节点AI 判断、确定性命令、人工审批与门控gate的编排。本文以仓库技能文档 authoring-workflows.md 为骨架系统讲解工作流的完整编写方法从结果优先的设计序列、三类 gate 的设计取舍到 11 种节点类型的 YAML 接线、循环完成通道、结构化输出、fixtures 测试并配合仓库源码与内置 sdlc 示例包给出可落地的实战细节。读完你应能独立设计并编写一个属于自己项目的工作流并学会用 dry-run fixtures 在零 AI 开销下证明其接线正确。工作流并不只服务于代码任务。整理工单收件箱、对账、筛选申请人、维护 CRM 记录——同样的节点类型、gate 与纪律都适用每个领域真正变化的是 gate 的来源见下文 Gate 设计一节。机械层面的完整细节每种节点类型与字段、when:/trigger_rule接线、fixtures见同目录下的 node-reference.md完整的变量替换语义见 variables.md编写 YAML 前建议两者都读。设计序列先回答九个问题再写 YAML编写工作流的方法论是结果优先outcome-first——机制从结果推导而来。按顺序过完以下九个问题标注与用户一起的步骤必须与用户确认后再设计期望结果Desired outcome。成功时存在什么工件或世界状态用一句话表述。如果无法表述为一个结果说明它还不具备构建条件。特异性与用户一起Specificity。这个工作流是针对某一个项目或结果还是打算通用复用这决定了后续一切项目专属工作流可以硬编码该仓库真实的 gate、真实命令、真实规则使用它自己的词汇——这会比任何通用等价物强大得多。设计前必须询问。复用检查Reuse check。用户自己已有的工作流中哪些已经覆盖了部分工作archon workflow list然后读它们的 YAML。通过include:组合复用。重要边界内置的 sdlc 包不是组件库。它的工作流存在的意义是教学——作为 gate 摆放、prompt 契约、fixture 纪律的范例默认不要把它们include:进用户工作流。它们的 prompt 和 gate 刻意写得通用以适配任意项目用户工作流若由它们拼装就会继承这种通用性失去让自己有价值的具体性。如果用户想要类似 archon-ship 但针对我的仓库应当用他们项目的术语新写一个工作流sdlc 包只作技艺参考。原语Primitives。用原语思维是对的命名那些组合成结果的小作业——调查、决策、实现、验证、发布运营队列则是 intake、enrich、judge、route、notify。把每个内聚、可复用的原语打包成带声明inputs:和returns:的工作流文件夹它既可以单独运行也可以通过include:with:组合进父工作流。节点实现原语的内部父工作流里放小的胶水代码用 AI 节点做判断用代码做可核查的事实。原语集合来自这个结果本身而不是复制别的工作流的节点清单。Gate 摆放与用户一起Gate placement。运行在继续之前必须在哪里停下来由什么决定三类 gate 都是头等公民见下一节专述。数据流Data flow。每个节点把什么交给下一个声明值$node.output、output_format字段、工作流inputs:/returns:承载 JSON 值工件$ARTIFACTS_DIR承载文件。产出节点拥有 schema包括脚本结果和组合工作流。声明结果前读 node-reference.md 的Result contracts返回文件引用时读 variables.md 的Artifact pointers。Prompt 编写。每个节点的提示词动笔前先看技能包中的 prompting-mistakes.md。接线Wiring与 fixtures。接入 YAML见下文然后每个编写的工作流都要在pack/workflow/fixtures/*.stubs.yaml下附带一个声明期望结果的 dry-run fixture。在信任之前先证明红色路径确实是红的。Fixtures 能证明 dry-run 可执行的路径可达的workflow:或include:fan_out:节点按设计会导致 dry-run 失败所以用一次小规模真实验收运行证明那条路径同时把 fixtures 留给周边接线。验证Validate。加载期错误会在archon workflow list中暴露然后archon workflow test workflow在不消耗 AI 的情况下运行受支持的 fixture 路径。Gate 设计三种头等公民按成本与可信度排序在项目专属工作流上用户往往已经知道部分 gate——push 之前必须先让我看 diff迁移若触碰 billing 就停下来没有两份评分一致任何申请人都不得晋级——逐字收集它们它们会成为 approval gate、cancel 节点或when:条件。其余部分在真实运行证明哪一步可以确定性化之前一律默认用 prompt command gate。确定性 gateDeterministic gates——由bash:/script:节点拥有退出码或对声明字段施加when:。凡是一个可核查的事实就能定论的地方就用它代码任务中测试通过、文件存在运营任务中对账平衡、每行都有负责人、导出数量与源匹配。最廉价、最无可争辩。Prompt command gate提示命令门——一个独立验证者以证据标准评判另一个 agent 的输出。验证者用context: fresh启动读 diff/工件/条目核对声明与标准返回驱动循环或分支的结构化布尔值。当 gate 设计未知时从这里开始agent 检查 agent 是最强大的通用 gate能抓住任何固定检查都预料不到的问题。把裁决保持结构化output_format布尔机器才能消费判断性的论述放在 prompt 里。如果以仓库中一个作者署名的 sidecar版本化的评分标准/指示文件为锚agent 判断 gate 可以顶替典型的人工评审者同样的标准、同样的问题、每次运行都有记录的答案。人工approval:gate——只有两种情况值得使用交互式工作流人类在控制台前阅读每次迭代或**超承重super load-bearing**动作——不可逆、面向公众、或超出轻松回滚范围的昂贵操作部署、公开发帖、删除数据、向客户发送沟通。其余都应能由代码或另一个 agent 决策。记住任何approval:gate 都强制工作流级interactive: true全新启动不能脱离detach但已暂停运行的续接动作可以。每个领域都潜藏着 gate。任何由人治理的流程早已发明了自己的控制手段复式记账、对账、双人复核four-eyes review、检查清单、回读。引出elicitation才是编写工作——让强模型基于领域知识提出候选 gate再由用户领域专家验证哪些真正有效。一个候选 gate 只有在可证明地拒绝过一个植入的坏结果之后才赢得信任——证明 gate 是红的和证明 fixture 是红的是同一件事。先简单起步再由运行经验驱动演进第一个版本刻意欠设计under-engineered用少量节点、短提示、关键 gate。不要在没有证据的情况下增加确定性真实运行之前对哪里会失败只能算猜测。立即在真实的东西上 dogfood——仓库里真实的任务而不是 demo。运行本身就是测试。基于证据适应而不是预期一次失败揭示缺了哪个 gate一次被浪费的评审揭示哪个检查赢得了自己的位置。只在有记录的发生要求的地方增加机制。原地迭代编辑文件夹重跑同类任务对比工件。工作流向项目收敛而不是预先设计完成。文件布局一个工作流一个文件夹保持每个工作流在自己独立的文件夹中。如果它的脚本使用了 pack 级共享模块把它移动到其他仓库时请连同 pack 一起复制。新建工作流的命令mkdir -p .archon/workflows/my-pack/my-workflow/{commands,scripts,fixtures}目录结构约定.archon/workflows/pack/workflow/ ├── workflow.yaml # name, description, inputs:, returns:, nodes: ├── commands/*.md # prompt 文件被 command: 节点引用 ├── scripts/*.py|.ts # 确定性逻辑Python/uv 优先TS/bun 亦可 └── fixtures/*.stubs.yaml实质性 prompt 放在 command 文件中不要内联。内联bash:只用于一两行的胶水任何有分支的逻辑都要落到脚本文件。绝不把 shell 当作脚本语言写逻辑。询问用户希望用哪种脚本语言维护。Python 依赖内联声明deps:用于uvnode_modules和虚拟环境不得进入打包的脚本树。共享的.ts、.js或.py模块放在pack/.shared/支持子文件夹。这个保留目录只提供模块绝不提供工作流定义或script:目标——缺失的打包脚本目标会在加载期失败。从workflow/scripts/publish.ts出发Bun 可以import ../../.shared/result.tsPython 文件可用pathlib.Path把str(Path(__file__).resolve().parents[2] / .shared)加入sys.path再正常导入Archon 不注入PYTHONPATH分组脚本需要按实际相对深度调整。同一路径在项目/全局源码、打包二进制与冻结快照中都可用。导入保持在 pack 内部不要求 npm 包或目标项目配置。使用常规模块文件二进制生成器会拒绝.shared下的 symlink。输出写到ARTIFACTS_DIR或STATE_DIR绝不写到脚本旁边Python 字节码缓存__pycache__在运行与可执行 fixture 中会被禁用。节点类型一个节点只做一件事共 11 种节点类型每个节点恰好出现一种commandprompt 文件·prompt内联·bashshell无 AI·scriptpy/ts无 AI·loop迭代单个 AI 节点·loop_group重复一个子 DAG·approval人工 gate·cancel带原因终止通常挂在when:后·wait持久化挂起·workflow受治理的子运行·include加载期普通组合或fan_out:的运行期按宽度组合。选择规则速记机器可验证的检查 →bash:/script:节点绝不让 AI 去检查。需要模型判断来门控下游开销 → AI 节点加output_format布尔 下游 gate 或循环通道读取该字段。重复的行动→验证周期 →loop_group由验证节点输出的结构化布尔驱动完成。command / prompt — AI 节点- id: plan command: plan # 加载 workflow-folder/commands/plan.md —— 文件优先于内联文字 depends_on: [investigate]- id: classify prompt: Classify $ARGUMENTS. Set type to BUG or FEATURE. allowed_tools: [] # 纯判断不需要任何工具 output_format: # 仅当机器要消费某字段gate/until_field/script时才声明 type: object properties: type: { type: string, enum: [BUG, FEATURE] } required: [type]AI 节点的关键字段model/provider层级 tier、output_format 类型化工件 sidecar 的output_type、allowed_tools/denied_tools、effort/thinking、retry瞬态默认重试 2 次、persist_session、idle_timeout。会话上下文在重要时显式指定省略时顺序层继承先前兼容 provider 的会话、并行层全新开始context: fresh总是干净起步独立验证用它context: shared显式继承顺序层的环境会话并行结构中祖先不明确时非法context: { resume: plan }分叉命名完成的上游节点的会话当恰好一个精确祖先重要时使用provider 须支持会话分叉。bash — 确定性 shell无 AI- id: test-gate bash: bun run test timeout: 300000 # msstdout 捕获为 $test-gate.output退出码决定成败。同一节点形状可验证非代码工作bash: python3 scripts/reconcile.py --period 2026-08总额必须平衡或检查每行导入记录都有负责人的脚本。只做一两行胶水有分支就用 script 节点。script — TypeScriptbun或 Pythonuv无 AI- id: verify-report script: verify-report # 加载 workflow-folder/scripts/verify-report.py runtime: uv depends_on: [implement, review] with: # 类型化值传输进入 INPUTS_UPPER_SNAKE 环境变量 green: $implement.output.green prior: {from: $review.output, if_skipped: none}优先具名脚本文件而非内联 body。Pythonruntime: uv优先TypeScriptruntime: bun亦可。deps:追加 uv 依赖。结果契约产出者拥有 schema用产出节点的output_format承载 JSON 结果。returns:只是选中那个节点并不声明另一套 schema。任何值形状声明都不属于inputs:或returns:。name: certified-result description: Certify a deterministic result and bind its field downstream returns: build nodes: - id: build bash: printf %s {ready:true} output_format: type: object properties: ready: {type: boolean} required: [ready] - id: consume depends_on: [build] with: ready: $build.output.ready runtime: uv script: | import os print(os.environ[INPUTS_READY])带output_format的bash:/script:节点必须打印一个满足该 schema 的严格 JSON 文档诊断信息发到 stderr。没有 JSON 修复或重问契约违反直接失败该节点且不重试即使有retry:。无法编译的 schema 是加载错误。没有output_format时exec stdout 保持纯文本。include:别名通过展平暴露被选中产出者的契约workflow:调用者收到子工作流选中的结果与声明的字段名并在冷恢复cold resume时持久化。不要在调用者侧重复 schemaworkflow:节点上的output_format是加载错误include:上的则被忽略并告警。无 schema 的子工作流保持无 schema。fan-out 返回按序的条目值数组消费整个聚合而不是数组上的某个字段。loop — 迭代一个 AI 作业- id: implement loop: command: implement until_field: done # 该节点 output_format 中的布尔值 max_iterations: 5 depends_on: [record-start] output_format: type: object properties: done: {type: boolean} required: [done]完成通道至少声明一个按层级选择详见下一节循环完成通道。另有fresh_context: true每轮迭代干净起步与$LOOP_PREV_OUTPUT上一轮状态。迭代失败在max_iterations处如实失败——耗尽边界如实失败而不是给糟糕的最后一次尝试背书。loop_group — 重复一个子 DAG- id: fix-cycle depends_on: [review-findings] loop_group: nodes: - id: fix prompt: Address findings: $review-findings.output - id: recheck prompt: Verify each finding is fixed with evidence. depends_on: [fix] context: fresh output_format: {type: object, properties: {ready: {type: boolean}}, required: [ready]} until_bash: test $recheck.output.ready true max_iterations: 5Body 是密封的无外部depends_on外层输出通过$nodeId.output进入 body。在loop_groupbody 中$LOOP_PREV.body-id.output读取上一轮迭代prompt 中做文本替换而when:条件中按类型化条件引用解析。body 节点失败立即失败整个组。approval — 人工 gate- id: review-gate approval: message: Review before proceeding decisions: - {id: approve, label: Approve} - {id: needs-revision, label: Needs revision} depends_on: [plan] - id: revise prompt: Revise using this feedback: $review-gate.output.text depends_on: [review-gate] when: $review-gate.output.decision needs-revision要求工作流级interactive: true。全新启动不能脱离已暂停运行的续接动作可以。仅用于交互会话或超承重动作。作者声明的decisions:总是产出结构化{decision, text}。capture_response与on_reject仅为兼容保留改用上面的when:显式接回改rework或当评审与修订需要重复时把 gate 放在loop_group末尾。cancel — 刻意终止- id: refuse cancel: This workflow handles bugs only. when: $classify.output.type ! BUGworkflow / include — 复用另一个工作流用workflow:启动一个受治理的子运行它有自己的工件、gate、成本与审计轨迹用include:在加载期把可复用工作流块展平进当前运行。- id: review-child workflow: archon-review with: scope: $INPUTS.branch isolation: worktree - id: review-inline include: archon-review with: scope: $INPUTS.branchworkflow:的目标名在 YAML 中是静态的但在节点执行时才解析所以前置节点可以动态创作子工作流。workflow:也接受input:替代with:并可声明fan_out:。普通include:在加载期完全解析并展开该指令只携带结构图字段加with:自身没有执行面。当运行期数据决定静态块应运行多少份时把fan_out:放在include:上- id: list-scopes bash: printf [packages/cli,packages/workflows] - id: review-each include: archon-review depends_on: [list-scopes] fan_out: items: $list-scopes.output as: scope # 必需每个实例收到 $INPUTS.scope max_parallel: 1 # 被包含块可能写入时串行逃生 join: all_done此形式不创建子运行返回$review-each.output下的按条目排序 JSON 数组。join: all_done时失败实例贡献archon_failed标记all_success则失败该节点。要并发运行实例被包含的完整块必须声明mutates_checkout: false。approval gate、持久 wait 等挂起路径在组合 fan-out 内部不受支持放在 fan-out 之前或之后。wait — 持久挂起- id: pause-for-ci wait: duration_ms: 300000wait 恰好声明一个有界条件duration_ms、until下的 ISO 时间戳或eventdeadline_ms。Archon 持久化挂起并释放 worker 槽位。其固定结构化输出含statussatisfied或expired与waited_ms事件等待还可能返回event与payload。循环完成通道按层级挑选完成可由外部检查 →until_bash: exit-0 check确定性。完成由模型判断 →output_formatuntil_field: bool-field。散文哨兵until: TOKEN只用于人类阅读的交互 gate其他场合已弃用。每个循环至少声明一个通道。结构化输出只在机器做决策处声明当when:、until_field或脚本消费某字段时才声明output_format否则让输出保持整串散文——schema 是对不强制执行的 provider 收的可靠性税。始终写 provider 无关的 YAML层级small|medium|large绝不写字面模型 id打包的工作流中不要provider:键。这一点在源码层面同样被约束packages/workflows/src/schemas/workflow.ts中模型绑定走 tier 名称与别名预设tierNameSchema、modelAliasPresetSchemapackages/workflows/src/model-validation.ts负责校验。隔离与交互性工作流级worktree.enabled: true固定 worktree 隔离省略则由调用者决定。在workflow:子节点上isolation: worktree显式给子工作流自己的 worktree。worktree 只圈定 git 文件不隔离~/.archon、环境变量、数据库或会话。任何approval:gate 都要求工作流级interactive: true。全新交互式启动不能脱离已暂停运行的续接动作可以。组合include:在父工作流的单一运行/隔离/审计轨迹内运行。只有当独立受治理的启动确实是需求时才使用workflow:子运行。数据流与变量替换packages/workflows/src/schemas/index.ts中的 schema 模块dag-node.ts、workflow.ts、workflow-run.ts等定义了节点与运行的全部合法形状加载期错误在archon workflow list时暴露。运行时接线语义如下$nodeId.output— 上游节点全文未知/跳过的产出者 →。$nodeId.output.field—严格 JSON 访问缺失键失败消费节点绝不静默为空声明为可选字段解析为。已声明 schema 之外的字段拼写保护、无 schema 的非 JSON 输出、跳过/待定的产出者都会失败消费者——用when:或宽松trigger_rule守护引用。with:绑定 — prompt/command 文件把绑定值读作$INPUTS.namebash/script 进程收到INPUTS_UPPER_SNAKE环境变量。{from, if_skipped}区分跳过与运行的产出者失败的产出者使绑定失败。$INPUTS.name— 声明的工作流输入同样以INPUTS_UPPER_SNAKE交付给 bash/script。$ARTIFACTS_DIR— 预创建的目录写给人类看的报告/证据。注入防护bash/script 源码中用户可控值一律以环境变量到达ARGUMENTS、INPUTS_*、LOOP_USER_INPUT、LOOP_PREV_OUTPUT、REJECTION_REASON、CONTEXT等绝不做文本替换$nodeId.output引用则会被替换自动 shell 引用32KB 溢出到文件并替换为$(cat path)。给散文产出者先加output_format再把输出直接赋给脚本。完整替换顺序与转义规则见 variables.md\$产出字面$$1…$9位置参数不被替换请用$ARGUMENTS或 bash/script 节点解析。Artifact 指针机器消费者需要文件结果时返回一个含指针的小 JSON 值{type:archon_artifact,run_id:producing run id,path:review/report.md}。run_id用实际的WORKFLOW_ID值。产出者须先把文件写到自己的$ARTIFACTS_DIR下引擎在持久化结果前校验指针自身 run id、无..段或 NUL 的非空相对路径、词法包含、存在的常规文件。指针不被展开为绝对路径也不会读进 prompt运行内的 prompt 交接仍用$ARTIFACTS_DIR/path。接线depends_on / when / trigger_ruledepends_on产生边同一拓扑层的独立节点并发运行。when:条件为假时跳过节点跳过会传播给依赖者when: $classify.output.type BUG when: $score.output.confidence 0.9 $gate.output.proceed true操作符、!、、,、数字自动解析非数字 fail-closed复合用/||绑定更紧无括号。表达式畸形 → 节点跳过 告警点访问契约违反 → 节点响亮失败。trigger_rule提供依赖的联接语义ValueBehaviorall_success所有依赖成功默认one_success至少一个依赖成功none_failed_min_one_success无失败且 ≥1 成功跳过 OKall_done所有依赖终态完成、失败或跳过Fixtures零 AI 开销地证明接线每个编写的工作流都要在workflow-folder/fixtures/name.stubs.yaml附带 dry-run fixtures# 声明期望 节点 stubs。每个非保留键都是一个节点输出。 fixture: expect: completed # 或 failed / paused / cancelled fail-node: assert-changed # expect: failed 时必需 —— 必须精确匹配 inputs: branch: task-42 implement: done: true green: true summary: stub summary exec-code: false # true 时真实执行 bash/script 节点需要 git checkout运行archon workflow test # 全部已发现的工作流 archon workflow test my-workflow # 单个工作流的 fixtures期望为红的 fixtures 才是重要的一个从未被看见失败的守卫证明不了任何东西。先证明红的确实是红的再信任它。workflow test镜像真实运行的目录行为具名脚本与 command 文件来自每次调用时对工作树的一次冻结快照未提交的编辑也包含在内所以编写工作正常进行而 exec-code 节点针对 HEAD 的一个 scratch worktree 执行。因此一个以__file__相对路径触达.archon/之外的脚本会在 fixture 中与真实运行一样失败节点执行的一切都无法触碰你的 checkout。Exec-code fixtures 需要 git checkout在 git 外显式失败。加载期错误用archon workflow list校验。常见错误清单写 YAML 前先读节点间用散文作线路格式。发一个 token 让下一个节点 grep 它。修复结构化输出 类型化读取或脚本退出码。AI 做本该代码做的事。把检查测试是否通过写成 prompt。修复bash/script 节点拥有退出码。解析模型散文来做决策。对$node.output做正则。同样的修复。在默认工作流 gate 中硬编码项目工具链tsc、pytest。确定性检查只验证 Archon 拥有的东西git 状态、工件、agent 发现命令的退出码。静默回退。可选输入悄悄降级而不失败。要响亮失败并点名缺失之物。把退出码/运行状态当作裁决。拒绝的任务也以 0 退出gate 在工件存在且通过验证、以及声明的结果字段上。跳过 fixtures。未被证伪的接线是未知接线。期望红的路径尤其如此见过红否则证明不了什么。什么都内联。YAML 里内联长 prompt、bash 里内联逻辑。文件老化得更好、diff 得更好且可跨节点复用。仓库实战样板sdlc 包的 implement 工作流.archon/workflows/sdlc/implement/archon-implement.yaml是上述全部原则的浓缩示范sdlc 包完整分布在 .archon/workflows/sdlc/ 下含 investigate、plan、implement、review、validate、deliver、ship、triage、pr、upkeep 等原语每个都带一整套红/绿 fixtures工作流级声明model: largetier 关键字、inputs.work空默认 空时用触发消息当工作、returns: implement、outcome_field: green——运行状态之外再持久化一个作者命名的布尔green/ready/rooted。record-startbash把git rev-parse HEAD写入$ARTIFACTS_DIR/.start-sha用串联使写入失败即节点失败它构成assert-changed的锚独立于运行开始时分支已领先多少。implementloopuntil_field: donemax_iterations: 5output_format中required: [done, green, red_cause, summary]全量声明注释解释了为何可选性必须活在类型里而不能靠省略required——OpenAI strict 模式会拒绝 required 遗漏声明属性的 schemared_cause用enum: [introduced, inherited, environment, ]区分红的原因。assert-changedscript,runtime: uv运行成功 ≠ 绿——loop 在done上完成而done有意包含一次确凿的受阻拒绝green: false。消费方读$implement.output.green组合在上游花费或发布前确定性 gate 它。守卫收到三个绑定输入green、red_cause、summary证据随值走不走工件桥。配套 fixture.archon/workflows/sdlc/implement/fixtures/decline.stubs.yaml就是红色证明的教科书implement被 stub 成一次拒绝done: true, green: false, red_cause: record-start与assert-changed真实执行exec-code: truefixture.expect: failedfail-node: assert-changed精确断言——一个什么都没做、又对为什么说不出话的运行必须失败而不是报告成功。这是把退出码不可信这一教训固化成可回归测试的写法。小结编写 Archon 工作流的完整循环是以一句话结果定义起点 → 与用户确认特异性并引出领域已有 gate → 拆原语 → 用三选一 gate确定性 提示命令 人工审批摆放检查点 → 声明数据流与结果契约 → 用 11 种节点接线 → 用 fixtures 证明红红绿绿 → 在真实任务上 dogfood 并基于日志证据原地迭代。机制细节始终以 node-reference.md 与 variables.md 为准示例参考内置 sdlc 包实现层面对照 packages/workflows/src/schemas/index.ts 与 packages/workflows/src/ 下的 loader、dag-executor、fixture-runner、condition-evaluator 等源码即可获得最权威的行为定义。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考