alethe

编排 CLI 工作进程

以尽可能少的引导上下文和成本最低且胜任的工作进程完成任务，或按用户要求采用最强组合。制定计划、委派范围明确的工作单元，并整合有证据支持的结果。

• 运行手册 = 各阶段和角色。
• 配置档 = 各层级使用哪些模型（base、savings、aggressive）。
• 目标 = 启用某模式时委派的积极程度（save、balanced、max）。
• 运行器策略 = 单个波次的运行方式（economy、balanced、quality、research、parallel、rescue）。

选择后端

如果用户明确要求使用本地技能或不使用 MCP，必须遵从。除此之外，运行 scripts/orchestrate.py policy show，并使用其 backend：skill 选择此运行器，mcp 在可用时选择 alethe_* 工具，auto 则优先选择这些可用工具。

Python 是可选的。如果 python --version、python3 --version 和 py --version 全部失败或报告的版本低于 3.9，或者用户提出要求，请按照 references/manual.md 进行检测、配置选项、后台工作进程和结果报告。其他所有章节仍适用，可通过手动方式实现。

技能路径无需 MCP。它会运行有界并发工作进程，支持可选的工作树隔离和可恢复会话。CLI 工作进程不会显示在 Alethe 的看板上。

首次运行和配置

如果环境可能尚未准备就绪，或用户询问已配置的内容，请运行 scripts/orchestrate.py doctor。它会检查 Python、提供商、已保存的策略和用户的运行手册副本，并汇总配额读数及可执行的提示。

当 doctor 报告尚未配置策略，或用户要求设置编排时，请按照 references/onboarding.md 操作：盘点 CLI、模型和路由，建立 base、savings 和 aggressive 配置档，并在将其保存到运行手册副本前征得批准。只保存已确认的偏好。像 9router 这样的代理负责传输模型流量；它不是工作进程。

设置不应阻碍工作。如果任务进行到一半时仍未配置任何内容，请运行 doctor，使用其中已登录的 CLI 和内置运行手册，用一行说明这一情况，然后继续。当前步骤完成后再提供入门设置；用户同意前不要保存任何内容。

将笼统的配置请求转化为相应操作：

用户说	操作
将“保存提供商 X”作为长期偏好	确认后运行 policy set --conserve-providers X
“小任务用便宜的模型”	确认提供商和模型，然后编辑运行手册副本中的 tiers
将“最多 N 个工作进程 / T 分钟 / C 美元”作为长期偏好	确认后运行 policy set --max-calls N --max-wall-seconds T --max-reported-cost-usd C
以上任一要求“仅用于本次运行”	将其写入计划的 budget，或使用 --strategy；绝不要修改策略
“整个任务最多 N 次调用 / C 美元 / T 个令牌”	在第一个波次开始前，用 budget 设定这些限额
“我们进行到哪了”，或对话上下文被压缩后	先运行 status，再进行其他操作
“恢复默认设置”	确认后运行 policy reset
“更改运行手册”或调整各阶段的角色	运行 playbook --init，然后编辑它输出的副本；UI 导出的是同一文件
将“使用 savings”或“启用 aggressive”作为长期偏好	确认后在运行手册副本中设置 profile
“它做了什么”“花了多少钱”	运行 report；无需确认

简短命令

在 Claude Code 中使用 /alethe <args>，或在其他任何地方将相同的词语放在「alethe」之后，都对应一个操作。未指定文件夹的运行专用命令会使用当前编排：由 new 启动、由 use 选定，或由上次 run 写入的那个。

词语	操作
用日常语言描述一项任务	按照本技能其余部分的说明编排任务
什么也没说	执行 status；若没有当前编排，则用几行列出这些命令
on，或一条长期指令（「从现在开始……」）	按下文所述保持开启
always，或「始终开启」「在每个项目中」	mode on --everywhere
off	mode off；如果默认开启，则仅在此项目中关闭
off everywhere	mode off --everywhere
save、balanced、max	mode on --goal <it>
careful	mode on --care careful
report [folder]	执行 report，并原样显示其输出，不要自行总结
report html，或「显示报告」	执行 report --format html，在文件夹中写入 report.html 并打开；若没有 Python，则按照 references/manual.md 填写 assets/report.html
status	执行 status，并原样显示其输出
usage	执行 usage；若 Claude 的读取记录缺失或过时，则执行 usage --refresh-claude；显示时间窗口、重置时间和数据时效性
models	执行 models；显示模型价格、排名和价格数据时效性
editor，或「显示操作手册」	执行 editor，将操作手册写成流程页面并打开；若没有 Python，则按照 references/manual.md 填写 assets/editor.html
list	执行 list；use <folder> 可再次将其中一个设为当前项
stop	执行 stop，然后在各波次结束后执行一次 status
budget <limit>	执行 budget --max-calls N、--max-reported-cost-usd C 或 --max-reported-tokens T
skip <phase>、switch <playbook>、freeform、add <phase>	按下文所述调整计划
note <text>	执行 note "<text>"
mark <worker> used|partial|discarded	执行 mark <worker> <mark>
setup	执行 doctor；若未保存策略，则开始引导设置
help	用几行列出这些命令

保持开启

1. 只要请求可拆分为范围明确、彼此独立的单元，就主动使用它，即使没有人提到编排也是如此，正如说明所述。小型或紧密耦合的工作由你自行处理。
2. mode on --everywhere 会在每个项目中将其设为默认模式，且永不过期。在项目中执行 mode off 只会在该项目中关闭它；执行 mode off --everywhere 则会移除默认设置。
3. mode on 会在当前项目（仓库根目录或文件夹）中保持开启，直至执行 mode off，或 12 小时内没有收到提示词。项目模式优先于默认模式。

两种模式接受相同的选项：

• --goal save 会尽可能少地消耗资源；max 会最大限度地利用可用 Agent；balanced（默认值）仅在操作手册认为划算时委派任务。
• --care careful 会先读取再写入，隔离每个写入者，在集成前审查每个差异，并在执行任何难以撤销的操作前征求同意。
• --rule "<the user's words>" 会保留长期指令，最多 8 条；--clear-rules 会清除这些指令。

当用户说 /alethe on、给出长期指令，或要求「从现在开始」进行编排时，开启此模式。如果指令适合映射为目标或谨慎级别，就进行映射，并将用户原话保留为规则。用一行确认当前已开启的设置，然后继续处理用户原本的事项。

开启模式时，Claude Code 钩子会提醒你；如果没有该钩子，则在会话开始和压缩后运行 mode show。只有在目标设定下委派任务的收益大于开销时才委派；小型工作由你自行完成。

在任务中途加入

可以在任何时候加入，包括加入另一个技能的工作流。不要从头开始：

1. 将现有内容作为计划：对话、规范、任务列表、设计文档、当前差异。让工作者参考这些文件，而不是复制内容。
2. 保留另一工作流的步骤和关卡：将待处理任务作为工作单元，将其检查作为关卡。只有当某个步骤要求时，才重写其文件。
3. 仅将 new 用于委派工作。将规模较小、相互关联或有歧义的工作留给负责人；用一行说明原因。

选择并调整操作手册

开始规划前，运行 scripts/orchestrate.py playbook --pick，查看当前配置、提供方顺序、选择条件和操作手册摘要。然后对选定的操作手册运行 playbook <id>，查看解析后的层级、配额和预算规则。两者均接受 --json；不带参数的 playbook 仅用于编辑或引导时输出完整文件。请参阅 references/playbooks.md。

1. 使用 pickOrder 选择操作手册。用户指定的操作手册优先；运行器策略名称也优先，并会保留下文所述的单轮行为。如果其他选项都不适用，则按单元调整 complete。
2. 按顺序运行各阶段。who: lead 指你，即当前会话中的你。其他每个阶段都是一轮工作者：其 runner 是计划的 strategy，workers 是单元数量，readOnly 表示 mode: read-only，而 isolate 会为每位写入者创建独立工作树。
3. 如果某阶段的 if 条件不成立，则跳过该阶段；对于通过 with 连接的路径，运行第一个条件为真的路径。自行检查阶段的 gate；若未通过，则针对每个单元运行一次其 after 链，然后再次检查。
4. 根据操作手册文件和当前配置解析每位工作者的层级，然后应用第一条匹配的规则。如果已设置，已弃用的 policy.modelTiers 覆盖项仍优先；新层级仅保存在操作手册中。明确传递模型和推理力度；只读工作应使用能力足够的提供方。
5. 在第一轮开始前，用一行说明你选择了哪个操作手册以及原因。

关注配额

无论目标、配置和运行器策略如何，也无论是否有人要求，都绝不能让任何提供方的配额耗尽。每轮开始前：

1. 运行 scripts/orchestrate.py usage。Codex 的读数来自其会话文件，Claude 的读数来自每个 Claude 工作线程的 rate_limit_event。如果计划中要使用 Claude，或你要使用 Claude，而读数缺失或已过时（>30 分钟），请运行 usage --refresh-claude，这会发起一次单行 Haiku 调用。

2. 查看 dry-run 中的 quotaForecast：根据以往的轮次估算本轮可能消耗的各个窗口配额。样本太少时，预测结果为未知；请如实说明，不要猜测。

3. 如果某个提供方的配额偏低（达到或超过 quota.criticalThreshold），且顺序中的下一个提供方使用相同层级，就转移工作，并用一行文字告知用户读数和重置时间：“将侦察任务转给 Codex：你的 Claude 5 小时窗口已用 86%（14:30 重置），Codex 已用 33%。”按照 quota.whenSpare 的规定，使用即将作废的配额。

4. 如果规避低配额提供方的唯一办法会降低工作所需的层级、所有提供方的配额都偏低，或者预测值超过 quota.stopAt，则在启动前停下并询问。说明工作需要什么、还剩多少配额以及何时重置，然后提供 2 到 4 个选项并给出建议；如果 Agent 有提问工具，请使用该工具：

   • 等待配额重置；
   • 改用其他提供方运行，并说明会有哪些变化；
   • 仅对允许降级的单元使用更便宜的层级，并说明风险；
   • 现在只运行配额足够的单元；
   • 连接其他 CLI 或账户（setup）；
   • 仅在用户明确要求的情况下，继续运行并使用 run --allow-low-quota。

   “这次迁移需要强力层级（Opus）。你的 Claude 5 小时窗口已用 91%，2 小时 10 分后（14:30）重置；本轮预计会消耗约 15%。1）等到 14:30（推荐）；2）现在使用 Codex high，当前配额为 40%；3）仅对两个机械性单元使用 Sonnet；4）连接其他 CLI。”

5. 如果某个提供方的配额达到或超过 quota.stopAt，run 会拒绝执行该轮，并跳过排队中的工作线程（failureKind: quota_low）。触及限额的工作线程会以 rate_limited 失败。遇到这两种情况，都按第 4 步处理。

用户固定指定的提供方和用户的答复优先于这些规则。你自己使用低配额提供方运行时，请告知用户，缩短你自己的轮次，并将工作交给配额充足的提供方。如果读数已过时，请如实说明，不要断言具体数值。使用 note "<reason and readings>" --kind switch 记录每次变更。读数未知时，请参阅参考文档。

调整方案

在各轮之间，根据结果或用户请求调整计划：跳过、重复或新增阶段，亲自执行某个步骤，更改提供方、模型或预算，切换操作手册，或制定自由形式的轮次。用户请求优先于操作手册。

每次调整都要在下一轮开始前用一行记录，以便报告说明原因：

变更	命令
跳过一个阶段	note "<phase>: <why>" --kind skip
添加一个阶段或工作线程	note "<what>: <why>" --kind add
切换操作手册，或改为自由形式	note "to <playbook or freeform>: <why>" --kind switch
亲自执行某个步骤	note "<what you did>" --kind lead
其他变更	note "<what changed and why>"

自由形式轮次也是普通计划：省略 playbook，并根据轮次要执行的工作为 phase 命名。使用 stop 停止已无用的轮次；已经运行的工作线程仍会保留其结果。

编排

1. 只有在委派带来的收益足以抵消开销时才委派；运行器策略 economy 和 rescue 允许只使用一名工作者。
2. 阅读 references/routing.md，了解每个波次可使用的运行器策略： auto、economy、balanced、quality、research、parallel 或 rescue。当前请求中明确指定的 运行器策略优先于已保存的偏好。如果明确调用了某个技能，且其后紧接的词与名称匹配，则将该词视为操作手册或运行器策略。
3. 运行 scripts/orchestrate.py probe，并且只使用可用的提供方。使用 Agy、Kimi、恢复工作者或 添加自定义 CLI 时，请阅读 references/providers.md。
4. 为写作者分配互不重叠的职责。并发写作时使用隔离的工作树；如果保留现有用户更改，单个写作者可以使用主检出。
5. 在仓库外创建版本 1 计划 JSON。运行 scripts/orchestrate.py scaffold <strategy> --workers N 可打印出有效的骨架，供你填写。使用 strategy；只有在已保存的提供方切换偏好可能决定提供方时，才使用 provider: auto。如果某个波次需要硬性限制，请设置计划的 budget；如果限制适用于整个编排中的每个波次，请运行 budget。 为计划填写 title、要运行的 playbook 和 phase，以及一行说明 why；为每位工作者填写简短的 why，说明其角色以及选择其模型的原因。报告会显示这些内容。 按照 references/briefs.md 中的说明编写每项任务。Codex 和 Claude 工作者启动时不会连接 MCP 服务；只有任务说明需要 MCP 服务时，才设置 mcp: true。根据 schemas/plan.schema.json 或使用 scripts/orchestrate.py validate 验证计划。
6. 运行 models。如果需要的价格缺失或已过期（超过 60 天），只能在供应商的官方定价页面查询，告知用户，并在策略文件旁的 alethe-prices.json 中保存包含 source 和 asOf 的条目；切勿猜测。参见 references/operations.md。 使用 dry-run 预览：查看运行器策略、提供方、并发数、提示词令牌数、预算、listPriceEstimateUsd（估算值）和 quotaForecast。修复警告，包括默认模型、提供方数量不足和停止阈值方面的警告，或说明这些警告为何不适用。 如果用户想查看架构，使用 dry-run --write 保存预览，然后按照 references/diagram.md 中的说明用 scripts/diagram.py 渲染。运行工作者之前先展示 SVG，并且只使用已确认的代理路由。
7. 使用 scripts/orchestrate.py new "<title>" --playbook <name> --why "<one line>" --lead <your CLI>:<your model> 启动一次编排，例如 --lead claude:opus；该命令会创建 文件夹、将其设为当前文件夹，并在报告中将你列为负责人。每个波次都使用 run <plan> --in current --detach 启动，然后调用 wait [--timeout N]（最多 540 秒），直到 done 为 true；该命令也会返回状态。Claude Code 也可以改用 shell 工具的后台模式。切勿在 shell 工具的前台运行波次并设置较短的超时时间。系统会检测到被中断的运行器；stop 也会终止遗留的工作者。运行器会限制并发数和预算，并保留工作树供审核。它使用参数数组；无法读取的 .cmd 垫片只有在遵守 references/providers.md 中的参数限制时才会通过 cmd.exe 运行。
8. 阅读 state.json、每个 outcome.json（先查看其中的 workerStatus、failureKind 和 readOnlyViolation）、简明的 result.md，以及写作者的 diff.patch 文件。除非正在诊断故障，否则不要加载原始日志。
9. 整合经审核的更改，在合并后的检出目录中运行验证；将每位工作者的结果标记为 used、partial 或 discarded，然后只移除已处理有用更改的临时数据和工作树。mark <worker> used 会在当前编排中查找该工作者。
10. 最后运行 scripts/orchestrate.py report 并展示其输出：工作内容、原因、更改、报告的支出以及剩余事项。回答用户的费用问题时使用该报告；未指定文件夹时使用当前编排。 有关计划示例、结果语义、选择性脏状态初始化和清理，请参阅 references/operations.md。

Worker 约定

每份任务说明都必须写明任务目标、完成定义、负责的路径、相关仓库规则、检查项、 禁止的更改以及期望的交接内容。运行器会自动追加以下不变量：

• 不要委派任务、启动子 Agent 或运行其他 Agent CLI
• 不要提交、推送、打标签、发布或发起拉取请求
• 返回简洁的结果、依据、变更文件、检查项、失败情况和风险
• 以 STATUS: 行（DONE、DONE_WITH_CONCERNS、BLOCKED 或 NEEDS_CONTEXT）和 SUMMARY: 行结尾

Codex 和 Claude worker 无法启动子 Agent：运行器会在 CLI 中禁用此功能。每个 worker 都以 ALETHE_ORCHESTRATE_WORKER=1 运行，因此无法自行启动编排。Worker 的 状态和摘要只是其自述；请检查其差异。对于评审、验证、裁决和评审小组任务说明，请遵循 references/briefs.md。

不要在计划、任务、参数或日志中放入机密信息。除非用户明确要求放弃这种隔离，否则不要使用绕过标志；自定义 worker 使用已知的不安全标志时，必须设置 allowUnsafe: true。

Token 使用规范

• 将“token 不多了”“节省配额”或“节约用量”等表述视为当前运行的运行器策略 economy。只有用户要求将其设为长期默认值时，才通过 policy set economy 持久化。
• 计划中的 budget 会将节省用量转为硬性限制：限制 worker 调用次数、运行时间、预估提示词 token 数、报告的 token 数和报告的费用。运行前使用 dry-run 查看估算值。只有 Claude 会报告费用，因此 maxReportedTokens 会限制其他 worker。缓存读取量会单独报告，不计入 maxReportedTokens，也不计入报告中的 Value token 拆分。
• 增加 worker 会提高提供商的总用量。若直接完成任务更省，auto 必须选择不进行编排；如果用户明确要求编排，则选择满足条件的最小运行器策略。
• 引用文件而不是复制文件；阅读简洁结果和差异，不要阅读完整对话记录。
• 仅在针对性后续任务中复用 sessionId。使用低成本 worker 处理范围明确的探索和机械性工作；将存在歧义的工作和集成工作交由主负责人或能力较强的评审者处理。
• 只有在错误有明确且可修正的原因时，失败的 worker 才能重试一次。

除非用户明确要求，否则不要提交、推送、打标签、发布或发起拉取请求。