Archon 提示词防错指南为工作流节点与运行调用编写可执行、可验证的 Prompt【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本指南围绕 Archon 开源仓库中随附的「提示词常见错误」技能文档.claude/skills/archon-cli/prompting-mistakes/prompting-mistakes.md展开系统讲解在为 Archon 工作流编写 Prompt 时应避开的 10 类典型错误。文章同时结合仓库中的工作流编排文档、节点参考、变量替换参考与执行器测试源码说明每一类错误背后的运行机制与正确做法。读完你将掌握两套能力一是为archon workflow run的调用消息即整次运行的$ARGUMENTS写出高质量的工作订单二是为工作流中的command:/prompt:节点编写能产生可消费产物artifact、可被门禁gate判定、可重复执行的节点 Prompt。提示词在 Archon 中的两个落点在动手写任何 Prompt 之前必须先明确它会被用在哪个位置。Archon 的提示词只出现在两处且语义完全不同见 prompting-mistakes.md调用工作流时传入的消息——即archon workflow run workflow --branch branch message中的message。它会在整次运行期间作为$ARGUMENTS变量存在是整条流水线测量的契约。运行参考文档running-workflows.md将其称为The input is the contractArchon 只能治理工作如何进行无法替你补足用户真正想要什么这是整个流程中杠杆率最高、且发生在任何成本支出之前的环节。工作流内部command:/prompt:节点中的提示词——这是你编写 YAML 时直接写在节点里的内容。command:从工作流目录下的commands/*.md文件加载提示词prompt:则是内联提示词见 node-reference.md。两条底层事实决定了两处提示词的写法文档 Prompting Basics 部分Agent 很聪明善加利用。每个command:节点底层运行的都是一套真实的编码 Agent 工具链具备其全部能力——节点内可以调用工具、读写文件、运行命令。Archon 内部的 Agent 并不必然知道 Archon 本身、本次运行或过去的失败。不要引用 Agent 没有感知能力的上下文例如像上次那样、按我们之前的约定这些上下文只在你的脑子里不在它的上下文窗口里。十大常见错误与修正以下内容完整继承自技能文档的主体章节并结合 authoring-workflows.md、node-reference.md 与执行器测试源码逐一展开。1. 结果模糊、方法暗示Vague outcome, implied method错误示例Look into the auth thing.查一下 auth 那件事。这句话没有任何可验收的终点。Agent 不知道查到何种程度算完成也不知道上下文放在哪里。正确做法明确完成的样子和上下文的存放位置。例如Fix issue #42. Use the issue, comments, and current source as evidence. Preserve the documented login behavior.修复 issue #42。以 issue 正文、评论和当前源码为证据。保留文档记载的登录行为。这与工作流设计方法一脉相承authoring 文档的设计序列第一步就是Desired outcome——当这件事成功时存在什么样的产物或世界状态一句话说清。如果无法陈述为一个结果它就不适合被构建。2. 偷渡你的诊断Smuggling your diagnosis如果你希望运行过程独立调查问题就用日常语言请求修复——不要把你怀疑的根因当作既成事实塞给 Agent除非你已经证明了它。原因是诊断一旦作为事实被接受Agent 的调查就会围绕它打转永远不会去验证它本身是否正确——它会自信地修复一个可能根本不存在的 bug。把疑似根因作为证据传递等于预先关上了调查的路径。3. 对着空气叙述Narrating to nobody无人值守的节点产出的是产物artifacts、提交commits和声明字段declared fields——不是聊天。写下 report to me below在下面向我汇报这类提示词的节点产出的是永远不会被任何人阅读的输出。修正把每一条指令都指向它所服务的产物。例如要求节点把调查结果写入$ARTIFACTS_DIR/report.md该目录是每次运行预先创建的产物目录见 variables.md或者把结论放进output_format声明的字段中供下游门禁消费。4. 没有证据门槛No evidence bar一个评判型judging提示词如果不说清引用因果链 / 剔除所有建立在might之上的内容就会收集一堆看似合理的填充物plausible filler。修正明确说明什么算作证据并要求其余内容保持沉默。这与 authoring 文档中Prompt command gates的设计完全一致独立验证者verifier要read the diff/artifact/entry, check claims and criteria——即把检查声明与标准写进提示词让验证者以证据为基准判定。5. 把退出码当结论Trusting exit codes as verdicts被拒绝的任务也会以 exit 0 结束例如bash:节点内exit 0无条件成功或 Agent 判断任务不适用后正常返回。门禁应读取产物和声明字段而不是成功位success bits。仓库测试对此有直接佐证condition-evaluator.test.ts展示了$nodeId.exit_code 0这类条件求值的全部行为但 authoring 文档明确警告A declined task exits 0; gate on artifacts existing and validating, and on declared outcome fields.被拒绝的任务以 0 退出门禁应基于产物是否存在且通过校验、以及声明的结果字段。工作流层的outcome_field如green正是为此设计的——把作者化的布尔判定与运行状态并列持久化。6. 用散文做线格式Prose wire formats让一个节点以魔法标记magic token结尾、再由下一个节点 grep 这个标记是一种脆弱且不可靠的节点间通信方式。修正改用结构化输出字段output_format声明的 JSON schema $nodeId.output.field严格字段访问或脚本退出码。执行器对结构化输出有严格契约声明了output_format的bash:/script:节点必须向 stdout 打印一个符合该 schema 的 JSON 文档诊断信息走 stderr违反契约会直接失败该节点且不重试见 node-reference.md 的 Result contracts。authoring 文档的 Common mistakes 也把 Prose between nodes as a wire format 列为首要错误Emitting a token so the next node can grep it. Fix: structured output typed reads, or a script exit code.7. 什么都塞进一个节点Everything-but-the-kitchen-sink scope一个节点只做一件事并且要声明非目标non-goals。Also update docs and tests and the changelog顺便把文档、测试和变更日志都更新了会同时稀释三件事。负面范围negative scope与正面范围同等承重——例如 do not touch the lockfile不要动 lockfile就是一条必须显式写出的约束。authoring 文档的 primitives 方法论与此呼应把结果分解为小型可组合工作investigate、decide、implement、verify、publish……每个可复用的 primitive 打包为一个工作流目录用include:/with:组合进父工作流——而不是让一个节点承担五个职责。8. 假设模型有记忆Assuming memory每个节点都可能是一个全新的会话没有任何先验上下文。必须在每个提示词内部重申输入路径、产物路径和约束条件。节点级会话语义在 node-reference.md 中有精确说明省略context时顺序层继承前一个兼容 provider 的会话、并行层全新开始context: fresh始终干净启动独立验证的推荐做法context: { resume: plan }从指定上游节点分叉会话。但你永远不能依赖这些继承——冷恢复cold resume不会重建环境会话游标见 running-workflows.md 的 Resuming after failure因此跨节点传递的关键信息必须写进提示词或落在产物/字段上。9. 不写停止规则Stop rules left unstated告诉 Agent 何时停止、何时上报遇到歧义→ 给出选项让用户选上下文缺失→ 明确指出缺失什么。绝不把有真实成本的决策交给use judgment自行判断。这条原则在调用侧同样成立运行参考文档要求输入消息完整覆盖六个要素问题、为何值得做、为何现在、期望结果、不变量、验收标准缺哪一项都要明确说出并提议措辞而不是静默放行。10. 软失败措辞Soft failure languageTry to...试着……邀请的是表演式努力theater而不是可检查的结果。修正把可检查的失败放进bash:/script:节点让它的退出码决定运行是否失败或者让评判节点返回结构化布尔值并由下游门禁以确定性方式when:条件、loop 的until_field消费它。这正对应 authoring 文档的节点选择规则模型判断若要门控下游开销 → AI 节点 output_format布尔 读取该字段的下游门禁或循环通道。门禁与循环正确提示词的落地载体上述第 4、5、6、10 条错误的修正方案几乎都要落在 Archon 的门禁gate与循环loop机制上理解它们才能写出真正可判定的提示词。三类门禁详见 authoring-workflows.md确定性门禁bash:/script:节点拥有退出码或when:条件作用于声明字段。凡是可检查的事实测试通过、文件存在、总额对平、每行都有属主都归它——最便宜、最无争议。提示词命令门禁独立验证者以证据门槛评判另一个 Agent 的输出。验证者应以context: fresh启动读取 diff/产物/条目核对声明与标准返回驱动循环或分支的结构化布尔值。设计未知时从这里开始——Agent 检查 Agent 是最强大的通用门禁能抓住任何固定检查都没预料到的问题。人工approval:门禁只有两种场景值得使用——交互式工作流中有人在控制台逐轮阅读或超承重动作不可逆、面向公众、难以回滚部署、公开发帖、删除数据、发送面向客户的沟通。其余一律交给代码或另一个 Agent。注意任何approval:门禁都会强制工作流级别interactive: true。循环完成通道按层级选择见 node-reference.md完成可从外部检查 →until_bash: exit-0 check完成由模型判断 →output_formatuntil_field: bool-field散文哨兵until: TOKEN→ 只用于人类阅读的交互式门禁其余场景已废弃每个循环至少声明一条完成通道。执行器测试dag-executor.test.ts为此提供了大量行为证据until_bash以真实 bash 子进程执行检查测试中有用计数器文件实现迭代 N 次后完成的惯用法until_field在验证过的负载中done true的那一轮完成交互式循环门禁会明确报告本次迭代由哪条通道促成完成✅ Completion condition met viauntil_bash / until_field若三条通道都未满足则给出警告提示。这正是第 10 条软失败语言的机械解完成与否由机器可读的通道决定而不是由散文的运气决定。节点上下文与数据流提示词要明确的四件事结合 variables.md 的变量表每个节点提示词内部应显式声明对应第 8 条假设记忆的修正输入路径调用消息通过$ARGUMENTS或别名$USER_MESSAGE全文进入工作流声明输入通过$INPUTS.name在 bash/script 中对应环境变量INPUTS_UPPER_SNAKE。产物路径需要写入文件时使用$ARTIFACTS_DIR——预创建的本次运行产物目录。若要让下游以文件指针消费返回{type:archon_artifact,run_id:实际 WORKFLOW_ID,path:review/report.md}形状的 JSON生产节点必须先在自己$ARTIFACTS_DIR下写入该文件引擎会在持久化前校验指针。约束条件不变量与负面范围要写进提示词例如 do not touch the lockfile。判定的落点结论放在output_format声明字段机器消费when:、until_field、脚本还是放在产物正文人类阅读作者必须事先想清——只有机器要消费字段时才声明output_format否则让输出保持整串散文schema 是对不强制执行的 provider 的一种可靠性税。一个容易踩的坑输入默认值不会自动回退到调用消息。当两者都是合法来源时把两个值都给模型并说明优先级- id: implement prompt: | Optional work override: $INPUTS.work Original invocation: $ARGUMENTS Use the work override when it is non-empty; otherwise use the original invocation.仓库自带的示例工作流 archon-test-pi.yaml 是观察上述原则的现成样本hello/hello-ollama两个 AI 节点各自只做一件可验收的小事verify节点通过$hello.output与$hello-ollama.output严格引用上游输出并对四种情形逐一给出明确判定措辞最后以 Say nothing else 声明停止规则——正是第 1、3、9 条修正的缩影。单行测试发送前的最后一道检查无论调用消息还是节点提示词发出前都要问一句文档 The one-line test 部分Could a competent engineer who has never seen this conversation act on exactly this text?一位从未见过本次对话的称职工程师能否仅凭这段文字就行动如果答案需要的上下文只存在于你脑中这个提示词还没写完。这条测试把前面十条错误收敛为一个可操作的自检不依赖记忆第 8 条、不依赖默契第 1 条、不依赖对话历史第 2、3 条、不依赖无法验证的措辞第 4、10 条。作者化工作流的完整纪律还有另一半每个作者化工作流都要随附fixtures/*.stubs.yaml干跑夹具用archon workflow test在零 AI 开销下证明布线见 node-reference.md 的 Fixtures 一节。预期失败expected-red的路径尤其要证明真的会红——从未被证明会失败的守卫毫无证明力。提示词写得再漂亮也只有被夹具与真实运行验证过才算真正完成。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考