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

快速上手

在 GitHub 查看源文件

本指南带你从全新安装 AWR 走到一次经过验证的会话交接：安装 CLI、 初始化项目、启动工作会话，并证明一个后继会话能够从前一个会话停下的 地方接手。所有命令都可以直接复制粘贴运行；AWR 自带 SQLite。

1. 安装 AWR

AWR 以原生包的形式发布在 npm 和 PyPI 上。两个渠道安装的是同一个 Rust CLI（awr）和 MCP 服务器（awr-mcp）；没有独立的 JavaScript 或 Python SDK。

使用 npm（需要 Node 22.14 或更新版本）：

npm install -g @originoneai/agent-work-runtime@0.5.1

或使用 pip，在虚拟环境中（需要 Python 3.9 或更新版本）：

python -m pip install agent-work-runtime==0.5.1

验证两个可执行文件：

awr --version
awr-mcp --version

支持的平台包括 macOS 15+（arm64 和 Intel x64）、glibc 2.39 或更新版本 的 Linux x64 与 arm64（以 Ubuntu 24.04 为基线），以及 Windows x64。 在 Linux 上，先检查你的 glibc：

ldd --version | head -n 1

对于 npm 安装，请保持可选依赖（optional dependencies）启用——启动器 会解析对应平台的原生包。没有安装脚本，也没有网络下载器；pip wheel 包内嵌了二进制文件。此外还有面向应用作者的第三个渠道：一个锁定版本的 原生负载，宿主应用可以内嵌这两个二进制文件，使其用户在运行时无需 Node、Python 或 Rust。

2. 初始化你的项目

初始化分两步：先预览，再显式确认。在你传入 --accept 之前，不会写入 任何内容。

AWR_PROJECT=/absolute/path/to/your/project
awr --project "$AWR_PROJECT" init

仔细阅读预览：它展示了 AWR 发现的清单——已有的 Markdown 任务台账、 YAML 来源文件、目标——以及它建议的来源映射。已有文件绝不会被覆盖； 你的原始文档始终是权威。如果预览符合预期，就确认它：

awr --project "$AWR_PROJECT" init --accept

对于一个空白项目，在一开始就说明它的用途：

awr --project "$AWR_PROJECT" init --goal "Deliver a document portal" --accept

如果你的 Markdown 台账使用了非标准的状态词，可以在初始化时做映射：

awr --project "$AWR_PROJECT" init \
  --status-map pending=planned --status-map complete=completed --accept

然后查看组织状况报告：

awr --project "$AWR_PROJECT" intake inspect --json

报告中的 organization.state 告诉你当前所处的状态：ready 表示至少 有一个任务具备来源声明的目标、验收标准、下一步行动，且前置条件均已 满足。needs_organization 表示有缺失——报告中有序的 actions 会告诉 你需要往来源文件里补充什么。

3. 启动工作会话

会话（session）是 AWR 中工作归属的基本单位。下面的命令使用一个小的 shell 辅助函数，让每次调用都带上项目路径和 JSON 输出：

AWR_BIN=$(command -v awr)
AWR_WORK=INTAKE-001          # a task key from your intake report
AWR_AGENT=agent-primary      # a label for who is working
AWR_MODEL=your-current-model # a recorded label; AWR does not invoke the model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

检查哪些工作可以执行，然后启动一个会话，同时带上认领（claim，即对该 工作项的运行时所有权）和当前项目修订版本：

awrj ready
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

编译工作上下文——把目标、验收标准、已记录的事实和历史组装成一个有 边界的数据包：

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

要阅读这个数据包本身，而不只是看布尔结果。遇到 BudgetExceeded 时， 调大 --budget；遇到 SourceStale 时，运行 awrj source reindex 后 重新编译。

4. 用检查点记录进展

在你离开之前——或在宿主的长对话被压缩之前——保存一个检查点，带上你 实际使用的上下文哈希、一份诚实的摘要、确切的下一步行动，以及每一个 未闭合的环节：

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

检查点可以记录未完成的工作；它不是测试通过或验收标准达成的证明。

5. 在新会话中继续工作

为了证明续接确实有效，结束第一个会话并从中恢复——这正是新 agent、 新机器或新宿主对话会使用的接手路径。结束会话会释放认领；它不会把 来源中的工作标记为完成：

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

现在恢复。任何 agent——可以是另一个，也可以是同一个 agent 稍后—— 都从前驱会话创建一个后继会话：

AWR_PREDECESSOR="$AWR_SESSION"
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent successor --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

两项检查可以确认交接成功：

  • jq -e '.context_ready' 退出码为 0：后继会话收到了前驱会话记录的 上下文，包括最后一次成功的检查点。
  • 恢复后的会话有一个新的 ID——resume 会创建一个新的 AWR 会话，而不是 修改旧会话。

你也可以随时以只读方式检查恢复状态：

awrj recovery inspect --session "$AWR_SESSION"

在编码 agent 的聊天窗口里工作？把宿主对话绑定到 AWR 会话上，让检查点 在宿主压缩后依然存活：

awrj client bind --client generic --external-session "myhost:$HOST_CONVERSATION_ID" \
  --work "$AWR_WORK" --session "$AWR_SESSION"

AWR 不会转移宿主的进程内存，也不会接管任意的已有进程——连续性来自 被显式记录的内容。

接下来去哪里