Archon 入门：AI 造 Agent，多 Agent 协作跑复杂工作流

入门级 | 约 20 分钟 | 你将掌握 Archon 的核心概念（Worktree 隔离、DAG 节点类型、YAML 工作流语法）、安装配置、以及 3 个典型工作流实操

---

项目简介

我们先来承认一个事实：你让 AI 修一个 bug，它可能顺便改了你没想改的地方；你让它加个功能，这次跑通了下次同样的话又说又跑偏了；你让它写 PR，每次描述风格都不一样。

这些问题不是 AI 故意捣乱，而是整个过程没有「结构」。AI 收到的是一句模糊指令，输出完全取决于模型当时的心情和上下文。

Archon 做的事情，就是给 AI 编程加上结构。它用 YAML 定义开发流程——规划、验证、代码审查、PR 创建，每一步是什么、依赖什么、什么时候算完成，全部写清楚。然后把 AI 塞进这个框架里，让它在这个结构里自由发挥，而不是漫天乱跑。

它的另一个核心能力是 Git Worktree 隔离：每个工作流跑在独立的 git 分支和工作目录上，5 个任务并行跑也不会互相踩踏。任务完了，合并回主分支；任务废了，直接删掉 Worktree，干净利落。

---

目标读者画像

• 使用 Claude Code 或 Codex 的开发者
• 对 AI 编程工作流标准化有需求的团队
• 想让 AI 产出可重复、可审查的用户

核心依赖与环境

• Bun
• Git
• Claude Code（CLI）
• GitHub CLI（完整安装时需要）

完整项目结构树

.archon/                     # 项目级（setup wizard 生成）
├── commands/                # 自定义命令（Markdown 文件）
├── workflows/               # 自定义工作流（YAML）
│   └── defaults/            # 内置工作流模板
└── config.yaml              # 项目配置（assistant 模型等）

~/.archon/                   # 用户级全局配置
├── workspaces/owner/repo/  # 按 GitHub 用户/仓库组织的隔离环境
│   ├── source/             # 仓库克隆或本地路径
│   ├── worktrees/          # Git Worktree 隔离目录
│   └── artifacts/          # 工作流产出物（不进入 git）
└── config.yaml             # 全局配置

---

手把手步骤

第 1 步：安装 Archon

有两种安装方式，根据你的情况选一个。

方式一：完整安装（推荐，5 分钟）

git clone https://github.com/coleam00/Archon
cd Archon
bun install
claude

然后对 Claude Code 说："Set up Archon"。它会启动交互式引导向导，帮你配置 GitHub 凭据、选择平台集成、测试连接、最后把 Archon 技能文件复制到你的目标项目。

方式二：快速安装（30 秒，已有 Claude Code）

# macOS / Linux
curl -fsSL https://archon.diy/install | bash

# Windows (PowerShell)
irm https://archon.diy/install.ps1 | iex

# 或用 Homebrew
brew install coleam00/archon/archon

快速安装只装 CLI，不会自动配置凭据和工作流到项目里，需要手动完成初始化。

第 2 步：运行 Setup Wizard（完整安装用户）

如果用了完整安装，setup wizard 会引导你完成以下步骤：

1. CLI 安装 — 安装 archon 二进制到 PATH
2. GitHub 认证 — gh auth login，让 Archon 有权限操作你的仓库
3. 平台选择 — 是否接入 Telegram / Slack / Discord（可选）
4. 目标项目 — 选择要注册的项目目录，wizard 把 .archon/ 技能文件复制进去

完成后，你的目标项目里多了这些东西：

.archon/
├── commands/       # AI 可调用的命令文件
└── workflows/      # 工作流定义

第 3 步：初始化目标项目

如果快速安装，需要手动初始化：

cd your-project
archon init
# 或在 Claude Code 里说: "Use archon to set up"

初始化后验证一下：

archon workflow list
# 应该列出 17 个内置工作流

第 4 步：理解 YAML 工作流结构

Archon 的工作流是一个 DAG（有向无环图），每个节点是一个执行步骤。节点之间通过 depends_on 声明依赖关系，Archon 按拓扑顺序执行，没有依赖的节点可以并行跑。

一个完整的工作流长这样：

# .archon/workflows/my-feature.yaml
nodes:
  # 节点 1：规划（无依赖，直接执行）
  - id: plan
    prompt: "探索代码库，制定实现计划"

  # 节点 2：实现（依赖 plan）
  - id: implement
    depends_on: [plan]
    loop:                                    # AI 循环节点
      prompt: "阅读计划，实现下一个任务，运行验证"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # 每次循环用新的 AI 会话

  # 节点 3：运行测试（依赖 implement，bash 节点，纯确定性执行）
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # 节点 4：代码审查（依赖测试通过）
  - id: review
    depends_on: [run-tests]
    prompt: "审查所有变更，对照计划修复任何问题"

  # 节点 5：人工审批（交互式 gate）
  - id: approve
    depends_on: [review]
    loop:
      prompt: "展示变更内容，响应任何反馈"
      until: APPROVED
    interactive: true                        # 暂停等待人工输入

  # 节点 6：创建 PR
  - id: create-pr
    depends_on: [approve]
    prompt: "推送代码，创建 Pull Request"

节点类型一览：

第 5 步：实操——从 GitHub Issue 到 PR

这是最常用的工作流之一：输入一个 GitHub Issue，输出一个 PR。

在 Claude Code 里直接说：

Use archon to fix issue #42

Archon 会自动：

1. 创建隔离的 Worktree 分支（archon/fix-42-xxx）
2. 按 archon-fix-github-issue 工作流执行：分类问题 → 调研 → 规划 → 实现 → 验证 → 创建 PR
3. 如果测试失败，自动进入 self-fix 循环
4. 完成后在 Worktree 里操作，不会影响你本地的主分支

你看到的大致过程：

→ Creating isolated worktree on branch archon/fix-42-abc...
→ Planning...
→ Investigating issue #42...
→ Implementing (task 1/3)...
→ Implementing (task 2/3)...
→ Tests failing - iterating...
→ Tests passing after 2 iterations
→ Code review complete - 0 issues
→ PR ready: https://github.com/you/project/pull/47

第 6 步：实操——从想法到 PR

如果你没有现成的 Issue，只有一个想法：

Use archon to add dark mode to the settings page

Archon 用 archon-idea-to-pr 工作流：

→ Feature idea → plan → implement → validate → PR → 5 parallel reviews → self-fix

过程中 AI 会：

1. 先探索代码库，理解当前架构
2. 制定实现计划（你可以中途介入修改）
3. 用 loop 节点反复实现直到所有任务完成
4. 运行验证（bun run validate）
5. 并行跑 5 个代码审查 Agent（风格、安全、性能、可维护性、文档）
6. 根据审查反馈 self-fix
7. 创建 PR 并附上完整的审查总结

第 7 步：自定义工作流编写

内置工作流是很好的起点，直接复制一份改：

cp .archon/workflows/defaults/archon-feature-development.yaml \
   .archon/workflows/my-feature.yaml

然后编辑 YAML 文件。比如你想去掉人工审批环节，直接合并：

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "分析需求，制定实现计划"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "读取计划，实现下一个任务，标记完成"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

  - id: run-tests
    depends_on: [implement]
    bash: "bun test"

  - id: create-pr
    depends_on: [run-tests]
    prompt: "推送代码，创建 Pull Request，使用以下模板：..."

变量替换：工作流里可以用这些内置变量：

- id: log-context
  bash: "echo $WORKFLOW_ID $ARTIFACTS_DIR $BASE_BRANCH"

• $1, $2, $3 — 位置参数
• $ARGUMENTS — 所有参数
• $ARTIFACTS_DIR — 当前工作流 run 的产出物目录
• $WORKFLOW_ID — 工作流 run ID
• $BASE_BRANCH — 主分支名
• $LOOP_USER_INPUT — 人工在 approval gate 输入的反馈

第 8 步：Web UI + 多平台接入

Archon 不只是 CLI，它有完整的 Web Dashboard。快速启动：

archon serve
# 下载 Web UI（首次），然后在 http://localhost:4000 启动

Web UI 提供：

• Chat 页面 — 和 AI 实时对话，看流式输出和工具调用
• Dashboard — 监控所有工作流运行状态（来自所有平台：CLI、Slack、Telegram 等）
• Workflow Builder — 可视化 DAG 编辑器，拖拽创建工作流
• Workflow Execution — 逐步查看任意工作流的执行过程

接入聊天平台（可选）：

接入后，你可以在 Slack 或 Telegram 里直接触发工作流，结果实时推送到同一个对话里。

---

常见问题排查

1. Claude Code 找不到 Archon 命令

这通常发生在快速安装后没有运行 setup wizard：

# 重新运行 setup
cd your-project
claude
# 说 "Set up Archon" 或 "Use archon to set up"

# 或手动更新技能文件
archon update

2. Worktree 创建失败

最常见原因是磁盘空间不足或权限问题：

# 检查磁盘空间
df -h

# 检查 git 版本（需要 2.23+ 才支持 Worktree）
git --version

# 手动清理旧 Worktree
archon isolation cleanup

3. 工作流列表为空

# 确认 .archon/workflows/ 目录存在
ls .archon/workflows/

# 手动触发工作流发现
archon workflow list --verbose

如果内置工作流也不见，检查 Archon 版本：

archon --version

4. YAML 节点依赖循环

如果 depends_on 形成了环，Archon 会报错：

Error: Circular dependency detected in workflow

解决方法：检查 YAML 文件，确保没有节点互相依赖对方（一个节点的 depends_on 指向了它自己或它的下游节点）。

5. 交互式 Approval Gate 在 CLI 下不响应

Approval Gate 需要人工介入。在 CLI 下，工作流会暂停等待输入：

Workflow paused: awaiting approval
Type /workflow approve <run-id> [comment] to approve
Type /workflow reject <run-id> <reason> to reject

如果是在 Web UI 里运行，带 interactive: true 的节点会自动显示审批按钮。

6. PostgreSQL vs SQLite 切换

Archon 默认用 SQLite（零配置），数据存在 ~/.archon/archon.db。如果你想切换到 PostgreSQL：

# 启动 PostgreSQL（Docker）
docker-compose --profile with-db up -d postgres

# 在 .env 中设置连接字符串
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# 重启 Archon
archon serve

---

扩展阅读 / 进阶方向

17 个内置工作流详解：Archon 提供了从日常辅助（archon-assist）到复杂审查（archon-comprehensive-pr-review）的完整工具链。其中 archon-refactor-safely 带 type-check hooks，archon-architect 做架构健康度扫描，archon-ralph-dag 支持 PRD 迭代实现。

自定义 Node 类型：除了内置节点，还可以写 command: 调用自定义命令文件（Markdown）、script: 运行 TypeScript/Python 脚本（支持 deps: 安装依赖和 timeout: 超时控制）、approval: 自定义人工审批流程。

平台适配器开发：Archon 的适配器层（IPlatformAdapter）支持接入任何聊天平台。参考 packages/adapters/src/ 下的 Slack、Telegram、Discord 实现，可以接入企业微信、飞书等国内平台。

Archon 架构深度解析：核心是 @archon/workflows 包里的 DAG 执行引擎（dag-executor.ts）+ @archon/core 的 Orchestrator（消息路由和会话管理）。工作流 YAML 通过 loader.ts 解析和验证，节点通过 depends_on 构建拓扑图，然后按拓扑顺序执行。

团队工作流规范化：把 .archon/workflows/ 提交到 Git，团队成员每次 clone 后都自动获得同一套工作流定义。结合 .archon/config.yaml 注入团队编码规范，AI 生成的所有内容都会遵循团队约定。