archon-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Archon CLI

Archon runs multi-step AI workflows through the

archon

CLI. Git projects run in isolated worktrees by default; registered folder projects run in place. You sit on top of the runs: you write the brief, launch, watch one stream, answer the decisions that reach you, and read what each run left behind.

Route by intent:

The user wants to...	Read
Run a workflow on real work	`operate/running.md`
Inspect, answer, cancel or resume runs	`operate/managing-runs.md`
Drive the SDLC pack's queues	`operate/queues.md`
Find out why a run failed or hangs	`operate/troubleshooting.md`
Set up Archon or change config	`setup/setup-and-config.md`
Author or change a workflow	`authoring/authoring-workflows.md` (then `node-reference.md` and `variables.md` in the same folder)
Improve a node prompt or a run message	`authoring/prompting-mistakes.md`

When the intent is clear ("build me a workflow for X", "run archon-ship on issue #42"), go straight to the reference. Do not ask.
When it is ambiguous, ask which of these the user wants.
On a machine where
```
archon doctor
```
fails, start with
```
setup/setup-and-config.md
```
.

Archon 通过

archon

CLI 运行多步骤 AI 工作流。Git 项目默认在隔离的 worktree 中运行；已注册的文件夹项目则在原地运行。你负责统筹这些运行：编写任务简报、启动运行、监视一个流、响应需要你决策的事项，并读取每次运行留下的内容。

按意图分流：

用户想要……	读取
对实际任务运行工作流	`operate/running.md`
检查、响应、取消或恢复运行	`operate/managing-runs.md`
驱动 SDLC 套件的队列	`operate/queues.md`
查明运行失败或卡住的原因	`operate/troubleshooting.md`
设置 Archon 或修改配置	`setup/setup-and-config.md`
编写或修改工作流	`authoring/authoring-workflows.md` （然后阅读同一目录中的 `node-reference.md` 和 `variables.md` ）
改进节点 prompt 或运行消息	`authoring/prompting-mistakes.md`

当意图明确时（“build me a workflow for X”“run archon-ship on issue #42”），直接查阅相关参考文档。不要询问。
当意图不明确时，询问用户具体需要哪一种。
在
```
archon doctor
```
执行失败的机器上，先阅读
```
setup/setup-and-config.md
```
。

The operating loop

操作循环

Discover.
```
archon workflow list --json
```
gives compact descriptions. For each plausible candidate, read the full description with
```
archon workflow list <name> --full
```
. Choose from full descriptions, never from names you remember.
Check the brief. The message, issue body or document the run reads is the contract the run is measured against. It must state the problem, why it is worth solving, why now, the desired outcome, the invariants and the acceptance. If any is missing, say which, propose wording, and get the user's agreement before launching.
```
operate/running.md
```
has the full check.

Launch detached. Pass the work as a message, the workflow's declared inputs with

--input

, or both:

bash

archon workflow run <workflow> --branch <branch-name> "<the work>" --detach
archon workflow run <workflow> --input <name>=<value> --input <name>=<value> --detach

Watch once. Run one stream as a background task of your harness, however many runs you launched:
bash
```
archon workflow attention --watch --json        # this project; add --all for the install
```
Each line is JSON.
```
attention
```
means a run needs a decision,
```
resolved
```
means it no longer does, and
```
terminal
```
means a run ended. Act on the line, then keep reading.
Answer deliberately. Read the item's question, its recommendation and the evidence it links. Answer with a reason, detached:
```
archon workflow respond <run-id> <decision> "<reason>" --detach
```
.
```
operate/managing-runs.md
```
covers every form.
Read the result. A completed run is not a verdict.
```
archon workflow get <run-id> --json
```
gives the normalized
```
outcome
```
and
```
leave_behind.artifactFiles
```
. Read the report before telling the user what the run concluded.

发现。
```
archon workflow list --json
```
会给出精简的说明。对于每个可能匹配的候选项，使用
```
archon workflow list <name> --full
```
阅读完整说明。根据完整说明进行选择，绝不要凭记忆中的名称选择。
检查简报。 运行所读取的消息、issue 正文或文档，就是评估该运行是否达标的契约。它必须说明问题、为何值得解决、为何现在解决、期望结果、不变量和验收标准。如果缺少任何内容，指出缺失项、拟定措辞，并在启动前获得用户同意。
```
operate/running.md
```
包含完整的检查项。

分离启动。 通过消息、工作流声明的 inputs（使用

--input

），或两者同时传入来提交工作：

bash

archon workflow run <workflow> --branch <branch-name> "<the work>" --detach
archon workflow run <workflow> --input <name>=<value> --input <name>=<value> --detach

只监视一次。 无论启动了多少个运行，都在你的 harness 中将一个流作为后台任务运行：
bash
```
archon workflow attention --watch --json        # this project; add --all for the install
```
每一行都是 JSON。
```
attention
```
表示某个运行需要决策，
```
resolved
```
表示该运行不再需要决策，
```
terminal
```
表示运行已结束。根据该行采取行动，然后继续读取。
审慎作答。 读取事项的问题、建议及其链接的证据。附带理由作答，并使用分离模式：
```
archon workflow respond <run-id> <decision> "<reason>" --detach
```
。
```
operate/managing-runs.md
```
涵盖了所有形式。
读取结果。 已完成的运行并不等同于最终结论。
```
archon workflow get <run-id> --json
```
会给出标准化的
```
outcome
```
和
```
leave_behind.artifactFiles
```
。在告诉用户该运行得出了什么结论之前，先阅读报告。

Hard rules

硬性规则

Never launch on a thin brief. A weak input does not produce a weak result. It produces a confident, well-formed answer to the wrong question, at full price.
Launch and answer with
--detach
. A detached run starts its own session and survives your shell. A foreground
```
respond
```
or
```
resume
```
continues the run inside your shell, and closing the shell stops it.
One watcher, not one per run. One
```
workflow attention --watch
```
stream covers every run in scope, including runs that triggers or other sessions start. A
```
workflow wait <run-id>
```
per run is fine for one or two runs; with dozens it contends for the database.
Stop work only when you mean to end it.
```
archon workflow cancel
```
stops the run mid-node, and that node's provider session and unsaved work are lost. Let a run reach its next pause or end when you only want to stop launching more. When one turn is stuck on a tool or background command that never finishes,
```
archon workflow end-turn <run-id>
```
ends that turn and keeps the run (
```
operate/managing-runs.md
```
, "A stalled turn").
Merge only what was reviewed. When you merge a pull request by hand, pin the merge to the reviewed head (
```
gh pr merge <n> --match-head-commit <sha>
```
), read the open review threads first, and sync your checkout afterwards.
Author agent-first. In a workflow you write, an agent node with typed output judges, scripts read facts and act at boundaries, and YAML only wires them.
```
authoring/authoring-workflows.md
```
("Agent-first") has the rule and an example.

绝不要基于单薄的任务简报启动。 薄弱的输入不会产生薄弱的结果；它会付出全部代价，给出一个自信、格式完善却回答了错误问题的答案。
启动和响应均使用
--detach
。分离运行会启动自己的会话，并在 shell 关闭后继续存在。前台执行
```
respond
```
或
```
resume
```
则会在你的 shell 中继续运行，关闭 shell 也会将其停止。
使用一个 watcher，而不是每个运行一个。 一个
```
workflow attention --watch
```
流可覆盖范围内的每个运行，包括由触发器或其他会话启动的运行。对于一两个运行，可以为每个运行使用
```
workflow wait <run-id>
```
；运行达到数十个时，它们会争用数据库。
只有确实要结束运行时才停止它。
```
archon workflow cancel
```
会在节点执行中途停止运行，该节点的 provider 会话和未保存的工作都会丢失。如果你只是不想再启动更多运行，应让运行自行到达下一个暂停点或结束。当某一轮卡在某个始终无法完成的工具或后台命令上时，
```
archon workflow end-turn <run-id>
```
会结束该轮，同时保留运行（
```
operate/managing-runs.md
```
中的“A stalled turn”）。
只合并经过审查的内容。 手动合并 pull request 时，将合并操作锁定到已审查的 head commit（
```
gh pr merge <n> --match-head-commit <sha>
```
），先阅读尚未关闭的 review threads，随后同步 checkout。
编写工作流时以 Agent 优先。 在你编写的工作流中，由带类型化输出的 Agent 节点负责判断，脚本负责读取事实并在边界采取行动，而 YAML 只负责将它们连接起来。
```
authoring/authoring-workflows.md
```
（“Agent-first”）包含相关规则和示例。

Gotchas

容易踩的坑

The current directory selects the project for discovery, launches and project listings.
```
workflow status
```
,
```
workflow runs
```
and
```
workflow attention
```
default to that project; add
```
--all
```
for the whole install. For a git project, run from the repo root. Register a non-git folder with
```
workflow run --folder
```
. A full run ID works from any directory.
Attention items are paused runs. A running run stuck on a stalled tool call is not an item:
```
workflow wait <run-id>
```
and
```
workflow status
```
show it.
```
workflow status
```
and
```
workflow runs
```
set
```
scopeFallback: true
```
in JSON when an unregistered project produced an install-wide result.
Prefer
```
--json
```
whenever you will parse output.
```
archon --help
```
is authoritative. If a flag this skill names is rejected, trust the CLI's help and tell the user about the drift.

当前目录决定了发现工作流、启动运行和列出项目时所用的项目。
```
workflow status
```
、
```
workflow runs
```
和
```
workflow attention
```
默认使用该项目；添加
```
--all
```
可作用于整个安装范围。对于 Git 项目，请从仓库根目录运行。使用
```
workflow run --folder
```
注册非 Git 文件夹。完整 run ID 可用于任意目录。
Attention 项是处于暂停状态的运行。因工具调用停滞而卡住的运行中任务不属于 Attention 项：使用
```
workflow wait <run-id>
```
和
```
workflow status
```
查看它。
当未注册的项目产生整个安装范围的结果时，
```
workflow status
```
和
```
workflow runs
```
会在 JSON 中设置
```
scopeFallback: true
```
。
只要需要解析输出，就优先使用
```
--json
```
。
```
archon --help
```
是权威依据。如果此 skill 提到的某个 flag 被拒绝，请信任 CLI 的帮助信息，并告知用户存在版本漂移。