Runlane CLI

Runlane 是一个面向 agent 的 Git 仓库 SDLC 工具：它把普通仓库组织成文件协议、worktree、分支、测试和交付报告协作流，规划 agent、任务 agent 和人工协作者都可以直接检查这些协作状态。

Runlane MVP 是本地 CLI 和 Markdown/Git 协议。它不提供托管服务、仪表盘、账号系统、远程 Git 平台集成、自动合并、自动推送或 Codex UI 自动化。

安装与运行

依赖：Node.js 20+、npm、Git。

查看公开 npmjs 上的最新版本：

npm view runlane-cli version

然后在业务项目里把 Runlane 固定为 devDependency，让团队成员、CI 和 agent 使用同一版本：

cd <your-project>
npm install -D --save-exact runlane-cli@latest
npx runlane --help
npx runlane doctor

--save-exact 会把解析到的实际版本写入 package.json 和 package-lock.json，避免团队成员、CI 和 agent 使用不同 CLI 版本。

runlane doctor 用来在进入 Runlane workflow 前确认当前运行版本、安装来源、版本一致性、Git root、Runlane project state 和 validation command availability。它默认离线、只读、不运行 validation commands，也不要求 Git 工作区干净；如果要真实运行配置里的 test/typecheck/build，仍然使用 npx runlane check。

如果你准备执行具体 workflow，可以先运行对应 preflight profile：

npx runlane doctor --preflight init
npx runlane doctor --preflight prompt
npx runlane doctor --preflight worktree
npx runlane doctor --preflight upgrade

这些 profile 只会调整诊断 severity、priority 和 next steps，帮助你优先看到当前 workflow 的风险；它们不会执行 init、sync、worktree create、prompt、Git cleanup 或 validation commands，也不会修改文件。

团队 onboarding 或 CI 准入可以使用机器可读的严格模式：

npx runlane doctor --strict --json
npx runlane doctor --ci --json

--ci 用于非交互 onboarding 或 automation readiness。它会使用 CI-oriented profile 和严格失败策略，但不替代 runlane check。

只有需要显式访问 npm registry 做联网检查时，才使用：

npx runlane doctor --online

升级旧版 Runlane 项目

已接入项目会有 .runlane/config.yaml。升级时：

git status
npm uninstall @runlane/cli
npm install -D --save-exact runlane-cli@latest
npx runlane doctor --preflight upgrade --json
npx --no-install runlane --version
npx runlane sync --dry-run
npx runlane sync --apply
git diff
npx runlane check --skip-tests --json

如果旧项目曾安装 legacy scoped package @runlane/cli，升级时必须先移除它，再安装 canonical runlane-cli。doctor --preflight upgrade --json 会检查 package.json、package-lock.json 和可检测的 node_modules/.bin/runlane shadowing；release dogfood 中安装 candidate tarball 前也要先完成这一步，随后用 npx --no-install runlane --version 确认本地入口来自 canonical package。

sync --dry-run 会列出配置和托管协议文件迁移，例如 legacy commands.* 到 validation.commands[]，或修复 docs/for_agent/roles/*.protocol.md 漂移/缺失。确认后再 sync --apply，review diff，并提交依赖、配置和协议文件变更。

没有 .runlane/config.yaml 的项目先用 npx runlane init --project-name <project-name> --yes 接入。

文档中的 runlane ... 默认指项目内版本，例如 npx runlane ... 或 npm exec runlane -- ...。

从当前源码仓库开发 Runlane CLI：

npm install
npm run build
node dist/index.js --help

本地开发时，通过构建后的入口执行命令：

node dist/index.js init --help
node dist/index.js doctor --help
node dist/index.js task --help
node dist/index.js work --help
node dist/index.js prompt planner --help
node dist/index.js protocol sync --help

CLI help 信息架构

runlane --help 默认使用中文优先文案，但命令名、flag、placeholder、stable ref、JSON 字段、错误码、package name 和 npm script 保持原文，确保可以直接复制，例如 task next、--work <work-ref>、runlane://task/<id>、ok、data、error、RUNLANE_LEGACY_SCOPED_PACKAGE_INSTALLED、runlane-cli 和 npm run build。

顶层 help 优先展示主流程命令：

init
doctor
sync
prompt
work
task
worktree
check
validate

protocol、project、run、event、evidence 和 trace 仍然公开，但在 help 和文档中作为高级、审计或 runtime surfaces 描述，不作为新用户的 primary happy path。产品模型仍是 Work-first progress semantics；CLI 行动入口则把 Task 作为一等顶层视图。

发布入口

Runlane 的 canonical package 发布到公开 npmjs。GitLab 只作为源码 remote，不再作为 npm package registry。

npm run check:fast
npm run release:version-check
npm run release:check
npm run release:rehearsal
export NPM_TOKEN='<token>'
npm run release:publish -- --dry-run
npm run release:publish

check:fast 是日常本地自检，覆盖 build、unit tests 和 typecheck。release:check 是发布候选 gate，覆盖 build、scenario、unit tests 和 typecheck。release:rehearsal 是发布前 rehearsal，覆盖 build、真实 packed tarball install smoke、project upgrade fixture matrix、unit tests 和 typecheck。

release:publish -- --dry-run 会先完成 rehearsal，并报告将要 tag、push、publish 和验证公开 registry smoke 的计划；dry-run 不会创建 tag、push、执行 npm publish 或访问公开 npm registry 做发布后 smoke。

发布后必须基于 no-prefix tag 创建代码托管平台 Release，并粘贴对应版本的 release notes。完整发布流程见 Runlane CLI 公开 npm 发布，历史 release notes 见 docs/releases。

MVP 命令示例

为 Git 仓库初始化 Runlane agent 文档协议文件：

npx runlane init --project-name my-project --yes

如果项目已有产品说明或架构决策，建议初始化前先放到这些位置：

• product_design/*.md：产品说明、需求、用户流程等项目事实。
• docs/adr/*.md：架构决策记录。

npx runlane init 会自动发现这两个目录下的直接 Markdown 文件，并写入 .runlane/config.yaml 的 project.source_documents。文件名没有特殊限制；如果来源文档放在其他路径，初始化后手动加入 project.source_documents。

接入一个已经包含 docs/for_agent/* 文件的仓库：

npx runlane init --project-name my-project --yes

已有的 agent 文档会被跳过，不会被覆盖。只有在明确希望替换 Runlane 管理文件时，才使用 --force。

生成规划 agent 提示词：

npx runlane prompt planner
npx runlane prompt planner --json

从任务卡生成任务 agent 提示词：

npx runlane prompt task docs/for_agent/tasks/task-01-demo.md
npx runlane prompt task docs/for_agent/task-01-demo.md --json

规划或创建任务 worktree：

npx runlane worktree create docs/for_agent/tasks/task-01-demo.md --dry-run
npx runlane worktree create docs/for_agent/tasks/task-01-demo.md
npx runlane worktree cleanup --merged --dry-run
npx runlane worktree cleanup --merged
npx runlane worktree cleanup --merged --delete-branch --dry-run
npx runlane worktree cleanup --merged --delete-branch

worktree cleanup 是 planner 接受并合并 task branch 之后的显式收尾命令，不会在 planner merge、doctor 或其它命令中自动运行。第一版只清理当前 Git repository 注册、位于 .runlane/config.yaml 配置的 worktree parent 内、clean、且本地 task branch 已 merge 到 default branch 的 worktree；dirty、detached、非 task branch、未 merge 或 parent 外的 worktree 会被跳过并说明原因。--delete-branch 只会用 git branch -d 删除已 merge 的本地 task branch，不会删除 remote branch。

查看 .runlane/state/*.json 中的 Work-first cockpit 状态：

npx runlane work list
npx runlane work next
npx runlane work show runlane://work/work-runtime-foundation
npx runlane project status

机器消费时使用 JSON 输出：

npx runlane work list --json
npx runlane work next --json
npx runlane work show runlane://work/work-runtime-foundation --json
npx runlane project status --json

work list 会按 Work status 分组，并从关联 Task 推导完成进度。work next 只给出确定性推荐和原因，不会创建 run、派发 task 或修改 state。work show 展示 Work 的 intent、status、progress、tasks、runs、decision refs、evidence refs 和 artifacts。JSON 是 Work Cockpit 的 canonical machine-readable view model，包含 stable refs、ids、status、numeric progress、recommendation reasons、source attribution 和 optional trace warnings；默认 human-readable 文本由同一 view model 渲染，适合人类快速阅读。

把 Task 作为顶层行动视图查看；Work 仍是顶层进度聚合单位：

npx runlane task list
npx runlane task next
npx runlane task list --work runlane://work/work-runtime-foundation
npx runlane task next --work runlane://work/work-runtime-foundation
npx runlane task show runlane://task/task-work-cockpit

npx runlane task list --json
npx runlane task next --json
npx runlane task list --work runlane://work/work-runtime-foundation --json
npx runlane task next --work runlane://work/work-runtime-foundation --json
npx runlane task show runlane://task/task-work-cockpit --json

task list 和 task next 不传 --work 时在项目范围内列出或推荐 Task，并为每个 Task 输出 parent Work context；--work <work-ref> 是可选过滤器，用于保留 Work-scoped drill-down。task show 会通过 Task 的 work_ref 解析所属 Work。Task commands 都是只读 view / recommendation commands，不会创建 branch、worktree、task card、report、run、event、evidence 或 trace record。Markdown task cards、reports、ADRs 和 planner docs 应只保存叙事、stable refs、paths 和 compact JSON 摘要；不要复制完整 Work / Task / Run state tree 或完整 event / evidence / trace records 作为第二套机器事实。

读取 runtime records 时也应优先使用 JSON 作为 canonical machine output：

npx runlane event list --json
npx runlane event show runlane://event/event-runtime-001 --json
npx runlane evidence list --json
npx runlane evidence show runlane://evidence/evidence-runtime-001 --json
npx runlane trace list --json
npx runlane trace show runlane://trace/trc-runtime-001 --json

event list/show、evidence list/show 和 trace list/show 默认仍输出 human-readable 文本；文本和 JSON 都由同一结构化 view model 渲染。JSON 输出包含 storage path、source status、missing、count、authority label 和排序后的 record summaries；show 命令会返回单条 canonical record。Authority label 固定为 events 的 lifecycle_control_facts、evidence 的 structured_evidence_summaries、trace 的 optional_non_authoritative。Markdown 文档和报告只应引用 JSON refs、paths 和 compact summaries，不要复制完整 Domain Event、Evidence 或 Executor Trace records 作为第二套事实源。Executor Trace JSON 只是 optional input context，不代表 gate、acceptance、closure、dispatch 或 Core state。

写入 runtime records 或 ManualRuntime state 时，--json 是 canonical machine-readable command result；默认输出仍是 human-readable 文本：

npx runlane trace capture command --command "npm test" --summary "tests passed" --json
npx runlane trace capture diff --summary "updated runtime JSON contract" --file src/commands/run.ts --json
npx runlane trace capture file --path src/commands/trace.ts --summary "added capture JSON output" --json
npx runlane trace capture completion --summary "task completed" --report-path docs/for_agent/tasks/task-81-runtime-mutating-json-output-contract/report.md --json
npx runlane trace capture decision --outcome accept --reason "Reviewed JSON output." --json

trace capture ... --json 返回 created trace ref/id、source adapter kind、action/observation type、target/evidence refs 或 hints、raw source pointer、storage path 和 records_created；它只写 .runlane/traces/records.jsonl，不代表 gate、acceptance、closure、dispatch 或 Core state mutation。

准备和记录 ManualRuntime run：

npx runlane run prepare runlane://task/task-62-manual-runtime-foundation
npx runlane run attach runlane://run/run-62-manual-runtime-foundation-001 --report docs/for_agent/tasks/task-62-manual-runtime-foundation/report.md --branch codex/task-62-manual-runtime-foundation --commit abc1234
npx runlane run validate runlane://run/run-62-manual-runtime-foundation-001
npx runlane run decide runlane://run/run-62-manual-runtime-foundation-001 accept --reason "User accepted the attached evidence."

npx runlane run prepare runlane://task/task-62-manual-runtime-foundation --json
npx runlane run attach runlane://run/run-62-manual-runtime-foundation-001 --report docs/for_agent/tasks/task-62-manual-runtime-foundation/report.md --branch codex/task-62-manual-runtime-foundation --commit abc1234 --json
npx runlane run validate runlane://run/run-62-manual-runtime-foundation-001 --json
npx runlane run decide runlane://run/run-62-manual-runtime-foundation-001 accept --reason "User accepted the attached evidence." --json

ManualRuntime 是手动控制的 runtime。run prepare --json 返回 run ref/id/status/runtime、work/task refs、prompt snapshot path、event refs 和 mutation storage boundaries；run attach --json 返回 attached report、branch、commit、diff、command log 和 evidence refs；run validate --json 返回 valid、missing 和 evidence_refs，证据不完整时保持非零退出并输出 { "ok": false, ... }；run decide --json 返回 decision ref、outcome、reason、actor、event/evidence refs，并显式报告 automatic_merge: false 和 automatic_dispatch: false。run prepare 只解析 Work/Task、创建 run state 并写 prompt snapshot，不执行 Codex、Claude、Cursor 或其他 agent；run attach 只绑定用户提供的 report、branch、commit、diff 或 command log；run validate 检查最小证据；run decide 记录用户输入的 accept / revise / reject / split / defer / stop 决策和 reason，不自动 merge、不自动 dispatch follow-up。Markdown task cards、reports 和 planner docs 应引用 JSON refs、paths、storage boundaries 和 compact command summaries，不要复制完整 trace/state/event/evidence records 作为第二套机器事实。

检查当前仓库或 worktree：

npx runlane doctor
npx runlane doctor --json
npx runlane doctor --strict --json
npx runlane doctor --ci --json
npx runlane doctor --preflight init
npx runlane doctor --preflight prompt
npx runlane doctor --preflight worktree
npx runlane doctor --preflight upgrade
npx runlane doctor --online
npx runlane check
npx runlane check --json
npx runlane check --skip-tests

运行使用前诊断：

npx runlane doctor
npx runlane doctor --json
npx runlane doctor --strict

doctor 是离线、只读的 preflight diagnostics。它检查当前 Runlane CLI 来源、运行版本、Node.js/npm/Git 可用性、项目内 runlane-cli 版本声明、legacy scoped package @runlane/cli 移除状态、package-lock.json 解析版本、Runlane config、核心 agent 文档、role protocol drift、Git 风险和 validation command 静态可用性。默认只有 error 会让命令失败；--strict 会把 warning 也作为失败。doctor 不访问网络、不写文件，也不执行 validation.commands。

check 面向已接入 Runlane 的仓库或 worktree，会检查协议文件并运行配置的本地 validation commands；需要真实执行 test/typecheck/build/lint gate 时使用 check。

验证已交付的任务分支或提交：

npx runlane validate task wangjc/my-project-task-01-demo
npx runlane validate task 0123456789abcdef --json

为旧版 Runlane 仓库规划或应用安全的 agent 文档协议同步：

npx runlane protocol sync --dry-run
npx runlane protocol sync --dry-run --json
npx runlane protocol sync --apply

protocol sync --apply 要求 Git 工作区干净，并且会拒绝存在未解决文件冲突的同步。

Agent 工作流

Runlane 会把协作状态显式写入仓库：

• .runlane/config.yaml 存储项目、Git、命令和协议路径配置。
• .runlane/config.yaml 的 project.source_documents 定义 planner 必须读取的项目事实源；npx runlane init 会自动填入 product_design/*.md 和 docs/adr/*.md 下的直接 Markdown 文件。
• .runlane/prompts/ 和 .runlane/templates/ 存储生成的提示词与文档模板。
• docs/for_agent/README.md 是稳定的 agent 入口。
• docs/for_agent/roles/planner.md 定义规划 agent 职责。
• docs/for_agent/roles/task-agent.md 定义任务 agent 职责。
• docs/for_agent/planning/ 保存路线图、计划、进度快照和归档。
• docs/for_agent/tasks/task-*.md 保存 v2 任务卡。
• docs/for_agent/tasks/<task_slug>/report.md 保存 v2 完成报告。

旧路径仍然可读，以兼容旧项目和旧任务卡，例如 docs/for_agent/task-*.md、docs/for_agent/<task_slug>/report.md、docs/for_agent/planner.md、docs/for_agent/plan.md 和 docs/for_agent/progress-YYYY-MM-DD.md。

典型循环：

1. 人工协作者用 Runlane 初始化或同步仓库。
2. 规划 agent 读取 Runlane 入口文档、产品来源、路线图、计划和最新进度快照。
3. 规划 agent 创建边界清晰的任务卡，写明归属文件、共享文件风险、必跑命令和报告路径。
4. 任务 agent 运行 npx runlane prompt task <task-card>，创建或进入独立 worktree，只实现归属范围内的内容，运行必跑命令，写完成报告并提交。
5. 规划 agent 用 npx runlane validate task <branch-or-commit> 验证分支或提交，审查 diff 和报告，然后接受任务或退回重做。

Runlane 把 Git 状态、命令结果和完成报告作为交付完成证据。

当前限制

• Runlane 优先面向本地和文件协议。
• 它不存储 token、cookie、私钥、模型提示词或模型响应。
• 它不调用 GitHub、GitLab、Codex、Cursor、Claude Code 或任何远程服务。
• 它不会替你合并、推送、创建 Pull Request，也不会在 planner merge 后自动删除 worktree；已合并任务现场需要显式运行 worktree cleanup。
• doctor 默认离线且只读，只做 preflight diagnostics；它不执行配置的 validation commands。
• check 和 validate task 会运行配置的本地命令；目标仓库依赖缺失时仍需自行安装。
• worktree create 创建任务 worktree 前要求 Git 状态干净。
• 关键命令已经支持 JSON 输出，但失败契约仍是 MVP 表面，后续任务可能会收紧。
• 当前发布候选不包含 Web 仪表盘、数据库、账号系统、托管 runner 或审计服务器。

Dogfood 状态

Runlane 已用 QuotaPilot 仓库完成 MVP 循环 dogfood：

• init 引导生成 .runlane/* 和 docs/for_agent/*。
• prompt planner 与 prompt task <task-card> 生成了可用的交接提示词。
• worktree create --dry-run 推导出任务 slug、分支、worktree 路径、基础分支和 Git 命令。
• check --json 报告了 Git 清洁状态、必需文件和配置命令结果。
• validate task <branch> 解析目标分支，展示 diff 统计，并重新运行目标检查。

这个仓库已经处理了 dogfood 后续事项，包括更安全的接入初始化、npm 包模板资源、Agent Docs Protocol v2 脚手架，以及用于升级旧协议布局的 protocol sync。

开发检查

在交付本仓库变更前，运行：

npm run check:fast
npm test
npm run typecheck
npm run build

发布相关检查分为三层：

npm run check:fast
npm run release:check
npm run release:rehearsal

check:fast 用于日常本地自检，执行 build、unit tests 和 typecheck。release:check 用于发布候选检查，执行 build、scenario、unit tests 和 typecheck。release:rehearsal 用于发布前 rehearsal，执行 build、真实 packed tarball install smoke、project upgrade fixture matrix、unit tests 和 typecheck。

真实安装入口由 scenario 中的 packed tarball smoke 覆盖：先生成 runlane-cli-<version>.tgz，再确认临时业务项目没有 legacy @runlane/cli shadowing，然后通过 npm install -D --save-exact <tarball> 安装，并用 npx --no-install runlane --version 验证 CLI 入口。