archon

Archon CLI 技能

Archon 是一个远程 Agentic 编码平台，可在隔离的 git 工作树中运行 AI 工作流。本技能将教你如何运行工作流、创建新工作流和命令，以及管理 Archon 配置。

可用工作流（实时）

!archon workflow list 2>&1 || echo "Archon CLI not installed. Read guides/setup.md to set it up."

路由

确定用户的意图，并分派到相应指南：

意图	操作
设置 / 安装 /“如何使用”	阅读 guides/setup.md — 交互式设置向导
配置 / 设置	阅读 guides/config.md — 交互式配置编辑器
在仓库中初始化 .archon/	阅读 references/repo-init.md
创建工作流	阅读 references/workflow-dag.md — 完整的工作流编写指南
快速查找参数 — 哪个字段适用于哪种节点类型	阅读 references/parameter-matrix.md — 主矩阵、基于意图的查找、静默失败目录
高级功能（钩子/MCP/技能）	阅读 references/dag-advanced.md
创建命令文件	阅读 references/authoring-commands.md
变量替换参考	阅读 references/variables.md
CLI 命令参考	阅读 references/cli-commands.md
运行交互式工作流	阅读 references/interactive-workflows.md — 透明中继协议
工作流最佳实践 / 反模式	阅读 references/good-practices.md — 设计复杂工作流前请先阅读
排查失败 / 卡住的工作流	阅读 references/troubleshooting.md — 日志位置、常见故障模式
运行工作流（默认）	继续阅读下方的“运行工作流”部分

如果意图不明确，请让用户进一步说明。

---

更多背景信息：archon.diy

本技能中的参考资料是经过提炼的子集。完整的权威文档位于 archon.diy（packages/docs-web/ 中的 Starlight 网站）。如果本技能的参考页面没有涵盖你需要的内容——例如边缘情况、完整示例、图表或某项功能的深入介绍——请从 archon.diy 获取相应页面。

何时查阅在线文档

• 你需要端到端示例，且内容比本技能展示的更完整（例如钩子、MCP 配置、沙箱架构、审批流程的完整模式）
• 你要向用户解释某个概念，并希望采用最易读的表述方式（book/ 系列是教程，而非参考文档）
• 你遇到本技能只简单提及的功能（例如 agents: 内联子 Agent、高级 Codex 选项、完整的 SyncHookJSONOutput 架构）
• 用户询问“在哪里有相关文档？”——请提供 archon.diy URL，而非技能文件路径

URL 映射

主题	URL
首页 + 安装	archon.diy
入门（安装、快速开始、概念）	archon.diy/getting-started/
本书（教程式指南）	archon.diy/book/
工作流编写指南	archon.diy/guides/authoring-workflows/
命令编写指南	archon.diy/guides/authoring-commands/
节点类型指南	archon.diy/guides/loop-nodes/, /approval-nodes/, /script-nodes/
单节点功能（仅限 Claude）	/hooks/, /mcp-servers/, /skills/
全局工作流/命令/脚本	archon.diy/guides/global-workflows/
变量参考	archon.diy/reference/variables/
CLI 参考	archon.diy/reference/cli/
安全模型（环境变量、沙箱、剥离目标仓库的 .env）	archon.diy/reference/security/
架构	archon.diy/reference/architecture/
配置（.archon/config.yaml 完整架构）	archon.diy/reference/configuration/
故障排查	archon.diy/reference/troubleshooting/
适配器设置（Slack/Telegram/GitHub/Web/Discord/Gitea/GitLab）	archon.diy/adapters/
部署（Docker、云、Windows）	archon.diy/deployment/

URL 格式为 archon.diy/<section>/<page>/ — 路径与 packages/docs-web/src/content/docs/ 下的文件名对应。

优先级

本技能的参考页面是常规工作流编写、CLI 使用和设置的主要信息来源。如果本技能未涵盖你的情况，请查阅 archon.diy — 默认情况下不要先访问在线文档（技能参考内容加载到上下文中的速度更快，也针对 Agent 做了优化）。

---

运行工作流

核心命令

archon workflow run <workflow-name> --branch <branch-name> "<message>"

重要规则：

1. 始终在后台运行 — Archon 工作流运行时间较长。始终使用 run_in_background: true 调用 Bash 工具。使用 /tasks 或 TaskOutput 工具查看进度。

2. 始终使用 worktree 隔离 — 除非用户明确要求其他方式，否则使用 --branch 标志。这会创建一个隔离环境，让 Archon 在不影响主分支的情况下运行。

3. 每个 shell 运行一个工作流 — 每个工作流都会占用其 shell。将多个工作流作为独立的后台任务运行。

隔离模式

模式	标志	使用场景
Worktree（默认）	--branch <name>	除非另有要求，否则始终使用此模式
自定义起点	--branch <name> --from <base>	从指定分支开始
直接检出	--no-worktree	仅在用户明确要求不隔离时使用
恢复失败的运行	--resume	从上次失败的位置恢复

工作流选择

将用户意图与上方实时列表中的工作流相匹配。常见模式：

用户意图	典型工作流	分支模式
“修复问题 #X” / “解决 Bug”	archon-fix-github-issue	fix/issue-{N}
“审查 PR #X” / “全面审查”	archon-comprehensive-pr-review	review/pr-{N}
“快速审查 PR #X”	archon-smart-pr-review	review/pr-{N}
“验证 PR #X” / “检查 PR”	archon-validate-pr	review/pr-{N}
“根据计划实现”	archon-feature-development	feat/{name}
“规划并实现功能”	archon-idea-to-pr	feat/{name}
“执行计划文件”	archon-plan-to-pr	feat/{name}
“运行 ralph” / “实现 PRD”	archon-ralph-dag	feat/{name}
“解决冲突”	archon-resolve-conflicts	resolve/pr-{N}
“创建问题” / “提交 Bug”	archon-create-issue	issue/{name}
“全面审查问题 #X”	archon-issue-review-full	review/issue-{N}
“安全重构”	archon-refactor-safely	refactor/{name}
“架构审查”	archon-architect	review/{name}
“PIV 循环” / “引导式开发”	archon-piv-loop ⚡	piv/{name}
“创建 PRD” / “交互式 PRD”	archon-interactive-prd ⚡	prd/{name}
通用 / 调试	archon-assist	assist/{description}

⚡ = 交互式工作流 — 需要透明中继协议。运行前请阅读 references/interactive-workflows.md。

如果没有匹配的特定工作流，请使用 archon-assist 作为后备方案。上方的实时工作流列表始终具有权威性 — 其中可能包含本表未列出的工作流。

多问题调用

当用户提及多个问题、PR 或任务时 — 分别将每项作为独立的后台任务运行：

# Each gets its own worktree — they won't conflict
archon workflow run archon-fix-github-issue --branch fix/issue-10 "Fix issue #10"
archon workflow run archon-fix-github-issue --branch fix/issue-11 "Fix issue #11"
archon workflow run archon-fix-github-issue --branch fix/issue-12 "Fix issue #12"

切勿将多个问题合并到同一条命令中。

---

其他 CLI 命令

archon workflow list              # List all available workflows
archon workflow list --json       # Machine-readable JSON
archon isolation list             # Show active worktree environments
archon isolation cleanup          # Remove stale worktrees (default: 7 days)
archon isolation cleanup --merged # Remove branches merged into main
archon complete <branch>          # Complete branch lifecycle (remove worktree + branches)
archon version                    # Show version info

如需查看包含所有标志的完整 CLI 参考：请阅读 references/cli-commands.md

---

快速入门：编写工作流

Archon 使用一种工作流格式：节点（DAG）。工作流是 .archon/workflows/ 中的 YAML 文件。

重要：以下示例仅供入门参考。务必根据用户的实际需求设计工作流 — 节点的数量、类型、依赖关系和配置都应符合用户要求，而不是照搬这些模板。

工作流结构

name: my-workflow
description: What this workflow does
provider: claude          # Optional: 'claude', 'codex', 'pi', ... (default: from config)
model: medium             # Optional: tier keyword (small|medium|large), @alias, or literal model
nodes:
  - id: first-node
    command: my-command    # Loads .archon/commands/my-command.md
  - id: second-node
    prompt: "Use the output: $first-node.output"
    depends_on: [first-node]

节点类型

每个节点必须且只能有以下字段之一：command、prompt、bash、script、loop、loop_group、approval 或 cancel。

Command 节点 — 运行 .archon/commands/*.md 文件：

- id: investigate
  command: investigate-issue

Prompt 节点 — 内联 AI 提示词：

- id: classify
  prompt: "Classify this issue: $ARGUMENTS"
  model: haiku
  allowed_tools: []

Bash 节点 — Shell 脚本，不使用 AI，stdout 会被捕获为输出：

- id: fetch-data
  bash: "gh issue view 42 --json title,body"
  timeout: 15000

Script 节点 — TypeScript/JavaScript（通过 bun）或 Python（通过 uv），不使用 AI，stdout 会被捕获为输出：

- id: transform
  script: |
    const raw = process.argv.slice(2).join(' ') || '{}';
    console.log(JSON.stringify({ parsed: JSON.parse(raw) }));
  runtime: bun           # 'bun' (.ts/.js) or 'uv' (.py) — REQUIRED
  timeout: 30000         # Optional, ms, default 120000

# Or reference a named script from .archon/scripts/ or ~/.archon/scripts/
- id: analyze
  script: analyze-metrics   # loads .archon/scripts/analyze-metrics.py
  runtime: uv
  deps: ["pandas>=2.0"]     # Optional, uv only — 'uv run --with <dep>'

Loop 节点 — 反复执行 AI 提示词，直至完成。至少声明 until / until_bash 之一；当条件可确定时，省略 until，这样就无需匹配任何散文文本：

- id: implement
  loop:
    prompt: "Implement next story. When done: <promise>COMPLETE</promise>"
    until: COMPLETE               # Prose signal
    max_iterations: 10
    fresh_context: true
    until_bash: "bun run test"    # Exit 0 = done
    # until_field: done           # Or: a declared boolean in this node's output_format
    # At least ONE of until / until_bash / until_field

Loop group 节点 — 每次迭代都重复执行由多个节点组成的子 DAG 主体（将实现 → 测试 → 审查作为一个重复周期）：

- id: fix-cycle
  loop_group:
    nodes:
      - id: implement
        prompt: "Implement the next fix. Last review: $LOOP_PREV.review.output"
      - id: test
        bash: "bun run test 2>&1 || true"
        depends_on: [implement]
      - id: review
        prompt: "Review diff + tests: $test.output. All good? <promise>SHIP</promise>"
        depends_on: [test]
    until: SHIP
    max_iterations: 6

Approval 节点 — 暂停工作流以供人工审查。若要通过 Web UI 交付，工作流级别必须设置 interactive: true：

interactive: true   # workflow level — required for web UI

nodes:
  - id: review-gate
    approval:
      message: "Review the plan above before proceeding."
      capture_response: true      # Optional: user's comment → $review-gate.output
      on_reject:                  # Optional: AI rework on rejection instead of cancel
        prompt: "Revise based on feedback: $REJECTION_REASON"
        max_attempts: 3           # Range 1-10, default 3
    depends_on: [plan]

Cancel 节点 — 以指定原因终止工作流。通常由 when: 控制是否执行：

- id: stop-if-unsafe
  cancel: "Refusing to proceed: input flagged UNSAFE."
  depends_on: [classify]
  when: "$classify.output != 'SAFE'"

如需包含所有字段、条件、触发规则和模式的完整编写指南：请阅读 references/workflow-dag.md

创建命令文件

命令是 .archon/commands/ 中包含 AI 提示词模板的 .md 文件：

---
description: What this command does
argument-hint: <expected arguments>
---

# My Command

User request: $ARGUMENTS
Workflow artifacts: $ARTIFACTS_DIR

[Instructions for the AI agent]

如需完整的命令编写指南：请阅读 references/authoring-commands.md

关键变量

变量	描述
$ARGUMENTS	用户的输入消息
$ARTIFACTS_DIR	为工作流制预先创建的目录
$BASE_BRANCH	基础分支（从 git 自动检测）
$WORKFLOW_ID	唯一的工作流运行 ID
$nodeId.output	上游节点的输出（.field 访问是严格的——参见变量参考）
$LOOP_PREV_OUTPUT / $LOOP_PREV.<id>.output	上一次循环 / loop_group 迭代的输出
$LOOP_USER_INPUT / $REJECTION_REASON	循环关卡中的人工反馈 / 审批拒绝原因

完整变量参考：读取 references/variables.md

高级功能（命令/提示词节点）

output_format（结构化 JSON 输出——所有提供方均支持，并进行架构验证；不匹配时节点失败）、hooks（工具拦截——仅 Claude 支持）、mcp（外部工具服务——除 Pi 外的所有提供方均支持）、skills（在每个节点注入，适用于 Claude/Pi/OpenCode/Copilot；Codex 通过文件系统实现）、allowed_tools/denied_tools（工具限制——除 Codex 外均支持）、agents（子 Agent——Claude 支持内联定义；OpenCode/Copilot 按名称选择已配置的 Agent，不支持内联定义）、persist_session（跨运行 AI 记忆）、output_type（带类型的工件附属文件）。

详情：读取 references/dag-advanced.md

示例文件

• examples/dag-workflow.yaml — 包含条件、bash + script + loop 节点和结构化输出的工作流
• examples/command-template.md — 包含所有变量的命令文件框架

---

交互示例

用户：“使用 Archon 修复问题 #42”

archon workflow run archon-fix-github-issue --branch fix/issue-42 "Fix issue #42"

用户：“让 Archon 审查 PR #15”

archon workflow run archon-comprehensive-pr-review --branch review/pr-15 "Review PR #15"

用户：“创建一个审查代码并运行测试的工作流” → 读取 references/workflow-dag.md 并创建一个包含并行审查节点的工作流。

用户：“创建一个带条件路由的工作流” → 读取 references/workflow-dag.md 并创建带有 when: 条件和 output_format 的节点。

用户：“编写一个用于调查 Bug 的命令文件” → 读取 references/authoring-commands.md 并在 .archon/commands/ 中创建一个 .md 文件。

用户：“在此仓库中设置 Archon” → 读取 references/repo-init.md 以创建 .archon/ 目录结构。

用户：“初始化 .archon 并创建自定义工作流” → 首先读取 references/repo-init.md，然后读取相应的工作流参考。