coleam00/Archon · 上手攻略

  • 仓库：coleam00/Archon
  • 链接：https://github.com/coleam00/Archon
  • 分类：skill
  • 作者：Tom
  • 更新：2026-07-08

是什么

Archon 是一个面向 AI 编程智能体的工作流引擎——用 YAML 定义开发流程（计划→实现→验证→审查→PR），让 AI 编程行为从"随机发挥"变成可复现的确定性过程。

它的类比是：Dockerfile 解决了基础设施的可复现，GitHub Actions 解决了 CI/CD 的可复现，而 Archon 解决的是 AI 编程工作流的可复现。

核心思想：把开发过程结构化、阶段化，在每个阶段设置验证门控，AI 只负责每个阶段内的"智能填充"，整体流程由你定义。

解决什么问题

当前 AI 编程工具的核心问题：同一次"修 bug"请求，AI 这次可能跳过测试，下次可能忘记写 PR，下次可能 PR description 格式全错。结果不可预测，依赖模型当前"状态"。

Archon 的解法： - YAML 驱动的确定性流程：你定义阶段和验证门，AI 按顺序执行，每次都一样 - 隔离的 Git Worktree：5 个修复并行跑不会相互冲突 - 人机协作门控：某些阶段可设"需人工审批"再继续 - AI + 确定性节点混合：YAML 中可混排 AI 步骤（prompt:）和确定性步骤（bash:），AI 只在真正需要的地方消耗 token

快速安装

前置依赖

  • Bun：https://bun.sh bash # macOS/Linux curl -fsSL https://bun.sh/install | bash # Windows irm bun.sh/install.ps1 | iex
  • GitHub CLI：https://cli.github.com bash # macOS brew install gh # Windows winget install GitHub.cli # Debian/Ubuntu sudo apt install gh
  • Claude Code：https://claude.ai/code bash # macOS/Linux/WSL curl -fsSL https://claude.ai/install.sh | bash # Windows irm https://claude.ai/install.ps1 | iex

完整安装（5 分钟，引导式）

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

在 Claude Code 中说：Set up Archon

引导向导会：安装 CLI → 配置认证 → 选择平台集成 → 复制 Archon skill 到目标项目。

快速安装（30 秒，已有 Claude Code）

如果已装好 Claude Code，只需安装 Archon CLI：

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

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

# Homebrew
brew install coleam00/archon/archon

编译好的二进制包不含 Claude Code，需要单独安装后配置路径：

# macOS/Linux/WSL
export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"

# 或在 ~/.archon/config.yaml 设置
# assistants:
#   claude:
#     claudeBinaryPath: "$HOME/.local/bin/claude"

Web Dashboard（可选）

Archon 带 Web UI，支持可视化工作流构建、实时监控和跨平台消息聚合：

# 二进制安装后
archon serve

# 从源码
cd Archon && bun run dev

核心用法

YAML 工作流定义

工作流文件放在项目 .archon/workflows/ 目录下（可兼容 .claude/workflows/）：

# .archon/workflows/build-feature.yaml
nodes:
  - id: plan
    prompt: "探索代码库并制定实现计划"

  - id: implement
    depends_on: [plan]
    loop:  # AI 循环——迭代直到完成
      prompt: "阅读计划。实现下一个任务。运行验证。"
      until: ALL_TASKS_COMPLETE
      fresh_context: true  # 每次迭代全新的 session

  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"  # 确定性节点——无 AI

  - id: review
    depends_on: [run-tests]
    prompt: "审查所有变更是否符合计划，修复任何问题"

  - id: approve
    depends_on: [review]
    loop:  # 人工审批门控
      prompt: "展示变更供审查。处理所有反馈。"
      until: APPROVED
      interactive: true  # 暂停等待人类输入

  - id: create-pr
    depends_on: [approve]
    prompt: "推送变更并创建 Pull Request"

运行工作流

在 Claude Code 中直接自然语言调用：

/path/to/project
claude

Use archon to fix issue #42

Archon 自动处理：选择合适工作流 → 创建隔离 worktree → 执行各阶段 → 完成后汇报 PR 链接。

查看可用工作流

claude

What archon workflows do I have?

节点类型速查

节点类型 写法 说明
AI 步骤 prompt: "..." AI 填充内容
AI 循环 loop: { prompt: ..., until: ALL_TASKS_COMPLETE } 重复直到满足条件
人工门控 loop: { until: APPROVED, interactive: true } 暂停等人确认
Bash 步骤 bash: "bun run validate" 确定性命令
依赖声明 depends_on: [node_id, ...] 必须在这些节点之后执行

工作流构建器（Web UI）

Dashboard 中的 Workflow Builder 提供可视化拖拽 DAG 编辑，包括循环节点（loop）的支持。适合非 YAML 偏好者。

典型适用场景

场景 Archon 如何帮忙
规范开发流程 强制 plan → implement → test → review → PR 的完整链路，防止遗漏
并行多任务 同时跑 5 个 bug fix，互不干扰（隔离 worktree）
人机协作审批 关键变更需人工 review 后再合并
Specs-driven 开发 compose 模式从规格文档出发，保证交付对齐原始需求
CI/CD 化 AI 任务 工作流 YAML 化后，可提交到 repo，所有成员复用同一流程
自动化研究 自定义 workflow 调用 deep-research 工作流，自动生成带引用的报告

坑与注意

  1. 必须从目标项目目录运行 Claude Code，而非 Archon 仓库目录：Archon skill 是通过引导安装复制到你的项目的，在 Archon 仓库里运行没有意义。

  2. Claude Code 认证要先完成：如果 Claude Code 未登录，Set up Archon 向导会在认证步骤卡住。先手动完成 Claude Code 初始配置。

  3. fresh_context: true 的代价：AI 循环中每次迭代都是新 session，避免了上下文累积导致的降智，但也意味着没有上一次迭代的记忆。适合短周期任务；长周期任务请慎用。

  4. 工作流选择由 AI 自行决定：Archon 没有强制的工作流选择机制——AI 根据你的自然语言描述自行判断用哪个工作流。在团队中建议通过项目内的 .archon/ 目录固化流程定义（提交到 git），成员克隆后自动获得一致流程。

  5. Web Dashboard 仅监控：Dashboard 显示实时进度和历史记录，但工作流执行仍然在 Claude Code 端运行，关闭 Dashboard 不影响执行。

  6. Archon ≠ 纯 Agent 框架：Archon 是工作流编排工具，不是 Agent 底层框架。它依赖 Claude Code 作为底层 AI 引擎，自己做的是流程编排和确定性保障。

  7. v1 分支仍有参考价值：早期基于 Python 的任务管理 + RAG 版本在 archive/v1-task-management-rag 分支完整保留，如有相关需求可参考。

与同类对比

特性 Archon Claude Code GitHub Copilot Workspace Goose
工作流引擎 ✅ YAML DAG ❌ 部分 ❌
确定性流程 ✅ ❌ 部分 ❌
Git Worktree 隔离 ✅ ❌ ❌ ❌
人工审批门控 ✅ ❌ 部分 ❌
Web UI ✅ ❌ ✅ ❌
多平台集成 Slack/Telegram/... ❌ ❌ ❌
内置 skills Archon skill（可迁移） 内置 有限 ❌
开源 ✅ ❌ ❌ ✅
底层 Agent Claude Code（你配置） Claude 未知 可配置

Archon 本质上是 Claude Code 的工作流增强层，而非独立的编程 Agent。如果你满意 Claude Code 的能力但希望它的行为更可预测，Archon 是最轻量的加法。

一句话推荐结论

Archon 是目前将 Claude Code 从"不可预测的智能体"变成"可复用开发流程"的最直接工具——如果你已经在用 Claude Code，想把 AI 编程规范化、团队化，Archon 值得一试。

适合：已用 Claude Code、希望 AI 编程流程标准化、可复现的团队
不适合：还没用 Claude Code（需要先安装）、想要完全自主的 Agent 框架（Archon 依赖 Claude Code）