Archon Quick Start：5 分钟跑通你的第一个 AI 编码工作流-开发者社区

Archon Quick Start：5 分钟跑通你的第一个 AI 编码工作流

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

本指南带你从零开始运行 Archon 的第一次 AI 编码工作流：先完成前置安装与认证，再通过archon workflow list / run等命令在任意 git 仓库上启动assist、smart-pr-review等内置工作流。读完你将掌握"输入即契约"的 Brief 编写方法论，学会用一条结构化指令把模糊需求变成可验收、可审计的确定性编码任务，并理解工作流隔离、脱离后台运行（--detach）等底层机制。

前置条件：安装 Archon 与 Claude Code

在运行第一个工作流之前，需要先满足以下几项：

安装 Archon——完整安装步骤见 installation.md。macOS/Linux 一行安装：
```
curl -fsSL https://archon.diy/install | bash
```
Windows（PowerShell）：
```
irm https://archon.diy/install.ps1 | iex
```

安装 Claude Code——Archon 负责编排 Claude Code，但不捆绑它，必须单独安装：

# macOS / Linux / WSL（Anthropic 官方推荐安装器） curl -fsSL https://claude.ai/install.sh | bash

认证 Claude：运行claude /login，直接复用你已有的 Claude Pro/Max 订阅，无需额外 API Key。如果想走 OAuth Token 或按量计费的 API Key，参考 ai-assistants.md 的认证章节。
编译版二进制需设置CLAUDE_BIN_PATH：源码安装（bun run）会通过node_modules自动发现可执行文件，但快速安装 / Homebrew 安装的原生编译二进制必须显式指向 Claude Code 可执行文件：
```
# 原生安装器之后： export CLAUDE_BIN_PATH="$HOME/.local/bin/claude" # npm 全局安装之后： export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"
```
也可以持久化写入~/.archon/config.yaml：
```
assistants: claude: claudeBinaryPath: /absolute/path/to/claude
```
二进制模式下 Archon 的解析优先级为：环境变量CLAUDE_BIN_PATH（最高）→ 配置文件claudeBinaryPath→ 自动探测原生安装布局（POSIX 的~/.local/bin/claude与 Windows 的%USERPROFILE%\.local\bin\claude.exe）。三条路都解析不到时，首次 Claude 查询会直接抛出带安装指引的错误。Docker 镜像则已内置 Claude Code 并预置CLAUDE_BIN_PATH，无需任何配置。
进入任意 git 仓库目录：工作流默认基于 git worktree 做隔离（详见下文"隔离机制"），运行前请cd到目标仓库；非 git 目录也可以用--folder注册为 folder project 原地运行。

私有仓库需要设置平台 Token：Archon 克隆私有仓库时按平台读取对应环境变量——GitHub 用GH_TOKEN、GitLab 用GITLAB_TOKEN、Gitea/Forgejo 用GITEA_TOKEN。这些变量的行为可对照 configuration.md 的环境变量表：

变量	用途
`GH_TOKEN`	克隆私有 GitHub 仓库时的认证
`GITLAB_TOKEN`	克隆私有 GitLab 仓库（同时供 GitLab adapter 使用）
`GITEA_TOKEN`	克隆私有 Gitea/Forgejo 仓库（同时供 Gitea adapter 使用）

运行你的第一个工作流

完成前置后，即可在仓库目录下执行：

# 1. 列出可用工作流 archon workflow list # 2. 让 Archon 协助理解代码库 archon workflow run assist "What does this codebase do?" # 3. 运行一次代码评审 archon workflow run smart-pr-review

三个命令分别做了什么

archon workflow list：枚举当前可用的工作流。Archon 自带一批内置默认工作流（archon-assist、archon-smart-pr-review、archon-fix-github-issue、archon-idea-to-pr等），完整清单见 overview.md 的可用工作流表；仓库级工作流放在.archon/workflows/下，同名文件覆盖内置默认。你并不需要记住工作流名——路由会读取所有工作流的 description 自动匹配，例如"fix issue #42"会路由到archon-fix-github-issue，"review this PR"路由到archon-smart-pr-review，匹配不上则回退到archon-assist。
archon workflow run assist "..."：把引号内的消息作为本次运行的输入规格（input），派发给编排器。默认行为是自动创建隔离的 git worktree 运行；也可显式控制：--branch <name>指定 worktree 分支名、--no-worktree关闭隔离直接在现有 checkout 运行、--cwd /path/to/repo指定目标目录、--folder注册非 git 目录为 folder project。这些标志在 workflow.ts 的选项注释中有清晰定义，其中--branch与--no-worktree、--resume与--branch、--base与--no-worktree互斥。
archon workflow run smart-pr-review：执行复杂度自适应的 PR 评审工作流。它是内置默认之一，可在 bundled-defaults.generated.ts 中看到实际声明。

验证安装

运行archon version确认 CLI 可用；想全面体检环境（Claude/Codex 二进制、gh认证、数据库、adapter token 等）可执行archon doctor（--full还会探测 OpenCode 运行时 SDK）。

输入即契约：把"需求"写成"规格"

That quoted message is not a prompt — it is the specification the whole run is measured against, and it is yours to write.

工作流运行时传入的那段引号文本，不是一句提示词，而是整次运行被衡量的规格（specification），而且它由你来写。Archon 负责治理"怎么做"：隔离、门禁、重试、审计轨迹。但它无法替你决定"你到底想要什么"。一个含糊的简报不会产生含糊的结果——它会产生一个自信、结构良好、却回答了你根本没问的问题的答案，而你为它支付了全额代价。

这条原则同样适用于运行读取输入的任何位置——GitHub issue 正文、消息、文档。无论哪种载体，都请让它说清楚六件事：

要素	要回答的问题
Problem to solve（要解决的问题）	今天具体哪里出了问题。
Why it is worth solving（为什么值得解决）	放任不管的代价是什么。
Why now（为什么是现在）	是什么让此刻成为合适的时机。
Desired outcome（期望的结果）	之后可观察到的差异是什么。
Invariants（不变量）	任何可接受的实现都必须保持成立的东西。
Acceptance（验收标准）	你如何知道它完成了。

方案引导是可选的——但沉默也是一种选择

是否在输入里写"怎么做"（solution steering）由你决定。省略它，运行会自己选方案——这常常是正确的选择：它读过了代码，而你可能没有。但如果你确实对"如何做"有意见——复用某个 helper、不要引入新依赖、遵循某个模块的模式、这必须是迁移而不是重写——请写进输入里。一个没说出口的偏好，运行无法遵从，你只能在读 diff 时才意识到。

把引导放在最后，在问题陈述完之后。一上来就写实现方案会把运行限制在你的第一个猜测上，掩盖更好的答案；放在末尾则只约束"怎么做"，而不替换"是什么"。

一份值得运行的 Brief 长什么样

archon workflow run archon-ship --branch fix/upload-timeout "$(cat <<'BRIEF' Problem: uploads over ~8 MB fail with a 504 after 30s. The proxy read timeout is 30s and the upload handler streams to disk before responding, so any file large enough to take longer than that is rejected after the bytes were already sent. Why it matters: this is the top support complaint this month, and every failure wastes the user's full upload time before telling them. Why now: the new export feature ships next week and its files are 20-50 MB, so this moves from an edge case to the default path. Outcome: a 50 MB upload completes, and a genuinely stuck upload still fails rather than hanging forever. Invariants: no change to the storage layout or the public upload API; memory use must not scale with file size. Acceptance: a 50 MB upload succeeds end to end; a test covers the timeout path; the 30s proxy timeout is either raised deliberately or no longer on the path. Steering (optional): prefer streaming straight to storage over raising the timeout, if that holds the memory invariant. Do not add a queue for this. BRIEF )" --detach

对比一下"fix the upload bug"。两者都会启动一次运行，但只有前者可以被检查、被验收。后者只能靠运行"猜"。

在 Brief 里写错是可以接受的、也是正常的——沉默才是代价。把你不确定的那条假设写出来，运行才有东西可以反驳，你也能从 diff 里看到它是否反驳了。

`--detach`意味着什么

示例末尾的--detach让运行在后台脱离终端执行，父进程立即返回。从 workflow.ts 的实现看，脱离运行时父进程会把稳定的分支名与 conversation id 钉在子进程的 argv 上，确保只创建一个worktree/conversation，子进程随后完成全部工作；日志写入detached-run-<conversationId>.log。之后可以用archon workflow status查看活跃运行、archon workflow get <id>查看单次运行详情、archon workflow resume <id>恢复失败或暂停的运行。想实时看流式输出就不加--detach，前台运行。

输入背后：Workflow 一次运行发生了什么

理解"输入即契约"后，值得看一眼这条输入驱动了哪些机制（详见 concepts.md）：

Workflow 是 DAG：一个 YAML 文件描述多步骤 AI 编码任务的有向无环图，节点间通过depends_on连接，无依赖的节点立即执行、同层节点并行扇出。
节点是原子单元：六种节点类型——command:（加载提示模板发给 AI）、prompt:（内联提示）、bash:（纯脚本，stdout 捕获为$nodeId.output）、loop:（反复执行直到完成信号）、approval:（暂停等人工审批）、cancel:（带原因提前终止）。
隔离是默认：每次运行默认获得独立 git worktree，你的工作分支保持干净、多工作流可并行、失败不留残局；用archon isolation cleanup清理，用archon complete <branch>完结分支生命周期。
命令支持变量替换：最常用的$ARGUMENTS（用户输入）、$ARTIFACTS_DIR（预创建的工作产物目录）、$BASE_BRANCH（基础分支）、$WORKFLOW_ID（本次运行唯一 ID），完整列表见 variables.md。

接下来看什么

至此你已跑通第一个工作流并掌握规格化输入的方法。继续深入：

Overview —— 完整入门指南：安装、认证、Web UI 与 CLI 设置、故障排查
Core Concepts —— 理解 workflows、nodes、commands 与隔离机制
Configuration —— 按项目定制 Archon（环境变量、.archon/config.yaml）
Authoring Workflows —— 编写你自己的多步骤工作流
AI Assistants —— Claude Code、Codex、OpenCode、Pi、GitHub Copilot 五种助手与认证方式

【免费下载链接】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 Quick Start：5 分钟跑通你的第一个 AI 编码工作流