AWR
GitHub
中文
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

使用 CLI

在 GitHub 查看源文件

awr 命令行工具是 AWR 项目的完整管理入口：agent 能通过 MCP 做的一切， 你都可以在终端里完成——此外还有 MCP 不暴露的项目管理功能。

安装

两个包渠道安装的是同一个 Rust CLI 和 MCP 服务器；没有独立的 JavaScript 或 Python SDK：

npm install -g @originoneai/agent-work-runtime@0.5.1
# or, in a Python virtual environment
python -m pip install agent-work-runtime==0.5.1

用 awr --version 和 awr-mcp --version 验证。

支持的目标平台为 macOS 15+（arm64 和 Intel）、glibc 2.39+ 的 Linux （以 Ubuntu 24.04 为基线，x64 和 arm64），以及 Windows x64。npm 启动器 需要 Node 22.14+，并依赖可选的原生包，因此请保持可选依赖启用；PyPI 启动器需要 Python 3.9+。在 Linux 上用 ldd --version | head -n 1 检查 glibc。仅 Git 绑定操作需要 Git；SQLite 已内置。第一个项目的完整演练见 快速上手。

每条命令的统一形态

文档中的 CLI 示例共用一个统一前缀：

awr --project /absolute/project --json <command>

--project 指向项目根目录；--json 把 stdout 切换为单个机器可读的 JSON 对象（详见下文）。自己阅读输出时可以去掉 --json——默认的人类 可读输出是刻意控制篇幅的：status 最多显示一条当前建议，ready 最多 列出 10 个条目。

查看项目当前状态

status 是你的第一站。它默认的 action 视图显示当前的续接事项、可 认领的工作、等待项、真实的阻塞，以及历史摘要：

awr --project /absolute/project status --view full --branch main
  • --view action/full/summary——默认是 action；full 给出旧版的完整 结构。
  • --branch NAME_OR_ID——按名称、内部 ID 或 main 读取某个分支，而不是 默认分支。为读取而选择分支绝不会改变默认分支、会话、认领或你的 Git 检出状态。

ready 列出可以接手的工作项，附带诊断信息、认领信息和截断提示。 --limit 默认为 10，接受 1 到 100；--branch 在这里同样可用：

awr --project /absolute/project ready --limit 25

读取工作项

work show 完整展示一个条目——任务、验收标准、依赖、决策、证据和来源 出处。--source-sha SHA 按特定来源修订版本读取；--branch 在另一个 分支上读取：

awr --project /absolute/project work show W-123 --source-sha abc123

search 在整个项目中查找条目。查询文本是位置参数；--type、--status、 --work 和 --limit 用于收窄结果：

awr --project /absolute/project search "payment retry" --type work --limit 20

为任务编译上下文

context compile 组装 L1 执行上下文——一个任务的预算化工作集——并给出 完整性、缺口、来源出处和上下文哈希：

awr --project /absolute/project context compile --work W-123

以下参数都是可选的：--session 和 --detached 控制会话绑定；--agent、 --intent 和 --budget 引导编译过程；--goal、--path 和 --tag 可重复使用；--source-sha 针对特定来源版本编译；--checkpoint 和 --after-revision 设定自定义基线，二者互斥。--branch ID 在另一个分支 上使用常规的上下文基线——这与 branch context 含义不同，后者编译的是 某个具名分支自分叉以来的增量，且不切换你的默认分支：

awr --project /absolute/project branch context feature-x --work W-123

默认的文本输出是受预算约束的执行上下文，完整的验收标准和硬性规则会被 保留。如果存在必需的缺口，JSON 结果会是 ok=false 且 error.code=ContextIncomplete；如果硬性事实超出预算，你会得到 BudgetExceeded——事实绝不会被悄悄截断。

推进工作

工作项通过 work 子命令改变状态：

awr --project /absolute/project work progress W-123 \
  --session S-1 --reason "starting implementation" --expected-revision 10

同样的形态适用于 block、unblock、cancel 和 reopen，由 --next-action、--summary 和 --blocker 携带相应的细节。完成操作 从 JSON 文件绑定验收标准和证据，并在成功后释放本会话的认领：

awr --project /absolute/project work complete W-123 \
  --session S-1 --reason "all checks green" \
  --input /absolute/completion.json --expected-revision 10

记录事件与证据

event append 写入项目日志：

awr --project /absolute/project event append \
  --type note --summary "reviewer asked for retry tests" \
  --expected-revision 11

可选参数：--work、--session、--branch、--importance（默认 normal），以及 --payload FILE（一个 JSON 值文件，省略时为 {}）。 默认输出显示 ID、类型、简短摘要和版本——它不会回显 payload；要展开 某个事件，请显式使用 event show --full。你无法伪造保留的域事件，如 work.completed；它们只能来自状态变更命令。

evidence add 从 JSON 输入文件记录证据：

awr --project /absolute/project evidence add \
  --input /absolute/evidence.json --expected-revision 11

输入字段包括 work_item_key、branch_id、external_key、 evidence_type、level、summary、locator、sha256、source_sha、 command、scope 和 verified_at。写入成功会返回保存的记录和一个 event_id，但记录不等于执行：validation_basis=caller_supplied_bindings 表示 AWR 存储的是你提交的绑定——而不是它运行了你的命令，也不代表业务 验收已通过。evidence show 提供记录的摘要读取视图；它不是写入回执。

路径与大小规则：证据输入和事件 payload 中的相对路径相对 --project 根目录解析；完成输入中的相对路径相对进程的当前目录解析，因此在自动化 中请使用绝对路径。证据输入和事件 payload 文件上限为 1 MiB，完成输入 上限为 64 KiB。

修订版本与乐观并发

写入操作接受 --expected-revision R，其中 R 是你最近观测到的 project_revision。如果项目已经向前推进，写入会以 RevisionConflict 失败，而不是悄悄覆盖别人的工作——用 status 重新读取，然后针对新的 修订版本重试。输出中会出现三个不可互换的版本号：revision 是对象的 版本，source_revision 是来源的版本，project_revision 是项目状态的 版本。

如果一次写入被中断或只部分应用，在决定下一步之前先检查提案、事件、 会话和当前修订版本——进程失败后不要盲目重试。有两个工作区错误值得 一提：WorkspaceConflict（来自 awr workspace）表示双方编辑了同一个 被跟踪的文件，不做任何自动合并；WorkspaceContended 表示一次 publish 或 drop 连续三个提交被抢占，解决办法就是再运行一次同样的命令。

JSON 输出、错误与退出码

带 --json 时，成功的命令在 stdout 上恰好打印一个 JSON 对象。错误是 stderr 上的带类型 JSON：

{
  "code": "RevisionConflict",
  "message": "revision conflict: expected 10, actual 11",
  "details": {"expected": 10, "actual": 11}
}

两个流要分开解析——绝不要用 2>&1 合并后再解析合并文本。code 和 details 是机器可读的决策依据；message 是给人看的。--json 可以放在 已知子命令之前或之后；把它放在命令之前，可以让未知的顶层命令也返回 JSON 错误。退出码：

  • 0——成功（也包括 --help 和 --version）。
  • 1——域错误（stderr 上有带类型错误），stdout 上可能附有可检查的 部分结果体；未实现的顶层命令返回 Unsupported，也是此码。
  • 2——参数缺失或无效，或未知的嵌套子命令；--json 模式下为 InvalidInput。

CLI 与 MCP 的分界

CLI 和 MCP 服务器暴露的是同一份域状态：对于共享的工作和上下文工具， 在相同的项目、分支选择、索引来源和参数下，两者返回相同的标识符、版本、 验收标准、依赖、诊断和缺口。区别在于姿态：

  • CLI 是完整的项目管理入口，它的读取可以刷新可重建的数据库投影 （source_refresh）。
  • MCP 读取工具严格只读（read_only=true）。如果来源已变化，MCP 读取 会以 SourceStale 拒绝过期快照，而不是自动刷新；运行 awr source reindex 后再读。
  • MCP stdio 为 agent 客户端暴露固定的工具目录（共享 HTTP 服务额外 增加项目目录工具）；超出该目录的管理功能留在 CLI 中。

实践中，你在终端里做安装、管理、重建索引和临时排查，而你的 agent 客户端在会话中调用 MCP 工具。agent 侧的内容见 MCP 工具； 出问题时见故障排查。