核心概念 — AWR

AWR 把项目的工作事实保存在任何单一 agent 对话之外，使工作能够在上下文丢失、更换 agent 和重启之后依然存活。本文解释这个模型背后的五个概念；读完之后，快速上手中的命令和日常工作流中的例行步骤就会顺理成章。

核心原则：你的来源文件（台账、计划）是权威，运行时存储的一切——会话、认领、证据——都是这些事实的可核对投影。AWR 绝不凭空捏造缺失的意图，也绝不允许对话记录替代已记录的事实。

项目事实：来源台账

AWR 的来源台账（source ledger）是一份保存在普通项目文件中的小型工作契约：一个 YAML 台账，如 work-ledger.yaml；或一个已有的 Markdown 台账（*-ledger.md），它在 AWR 中保持只读，仍在原文件中编辑。台账记录两类事实：

目标（Goals）——项目试图达成的东西，附带成功标准。目标在不确定时可以是 draft、candidate 或 needs_confirmation，在有来源材料或用户指示支撑时可以是 active 或 confirmed。AWR 检查的是声明本身；它不保证目标与人的本意一致。
工作项（Work items）——即任务，详见下文。

一个最小台账长这样：

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

通过 init 把这些文件纳入 AWR 的管理。在你确认预览之前，不会写入任何内容：

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

Init 绝不会覆盖已有文件，而检查（inspect）只刷新可重建的投影缓存—— 绝不触碰你的目标、任务文件或执行状态。

任务：工作项

一个工作项就是台账中的一个任务。它的关键字段都是 AWR 能够真正检查的字段：

acceptance——完成标准：任务完成时必须可观测地为真的内容。之后的完成报告会逐条对照这些标准进行核验。
next_action——持久化的下一步，也是对恢复最有价值的字段：它让一个全新的会话无需重读历史就能继续。
辅助字段：summary、goal、kind、paths、tags、priority、 depends_on、owner 和 milestone。

你从一份只陈述明确已知事实的 JSON 草稿创建任务：

awr work create --input draft.json

创建总是产生一个草稿。缺失的目标或必需事实会保持可见，草稿不授予任何执行或完成的权限；应用草稿是一个单独的、显式的步骤。

AWR 还会报告项目级的组织状态，如 not_initialized、needs_organization、 ready、blocked、awaiting_verification、completed 和 closed_without_completion。日常最重要的是两个：ready 表示至少有一个任务具备来源声明的目标、验收标准、下一步行动，且前置条件均已满足； awaiting_verification 表示台账称任务已完成，但它们的验收报告尚未全部通过验证。

检查点与会话

一个会话是某个 agent 与一个工作项之间的工作附着关系。一个检查点 是该会话所处位置的持久记录：持久化的下一步行动、未闭合环节，以及实际的 AWR 事件与来源差异——而不是对话的副本。

当客户端会话启动或在压缩后恢复时，AWR 返回基于检查点构建的恢复上下文。当一轮工作暂停或结束时，变更后的下一步行动和未闭合环节会在丢失之前被保存：

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

工作未变化的重复事件会复用其检查点；进展有变化的延续轮次会创建新的检查点。有一条诚实的边界：自动化这一流程的原生钩子适配器目前仅为 Codex 安装。其他宿主使用 L0 绑定器（--client generic），它把宿主对话附着到一个活跃的 AWR 会话上，但不安装钩子。适配器绝不读取对话正文——它只记录你告诉它的内容，而不是模型说过的话。

认领与交接

认领（claim）是会话在执行任务之前持有的显式锁。AWR 要求你在执行前获取会话认领，完成时还会重新检查它——这就是两个 agent 避免悄悄做同一个任务的机制。

交接（handoff）把工作从一个会话或客户端移交给后继者。你显式地恢复一个会话，带有修订版本检查和后继转换：

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

或者把一个新的客户端对话绑定到它的前驱：

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

交接传递的是已记录的事实——台账状态、检查点、执行历史——而不是进程内存。关闭钩子是建议性的：它们绝不释放认领或终止会话，在交接时释放和终止仍然是你显式的责任。

交付与验收

验收（acceptance）是 AWR 刻意严格的地方。任务不会因为有人在台账里写了 status: completed 就算完成。只有当一份注册的完成报告对照台账当前的验收标准验证通过时，任务才算完成。

完成报告记录实际执行的命令、实际验证的范围、时间，以及具名检查—— 每一项都映射到一条确切的验收标准，并描述观测到的结果，而不是预期的结果：

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

在完成之前，先对报告做预检（preflight）：

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

预检不执行任何命令、不注册任何证据、不完成任何任务——它读取报告字节，返回证据参数和验收映射。完成本身是一次单独的写入，会重新检查认领、依赖、来源新鲜度和报告字节；在预检之后修改报告会使其摘要失效。仅有来源声明的完成绝不会提供经过验证的回执，在状态报告中 source_completed 和 verified_completed 始终是两个独立的计数。

一个任务的端到端之旅

用上面台账中的 search 任务把各环节串起来：

事实。 你运行 awr --project /absolute/project init --accept；带有 search 目标和 search-api 工作项的台账成为权威。
任务。 工作项携带验收标准和下一步行动，因此项目报告为 ready。
会话与认领。 你从一个快照准备工作，然后在动代码之前获取会话认领：

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

检查点。 工作过程中，你用 awr client progress 保存进展，使下一步行动和未闭合环节在崩溃或压缩后依然存活。
交接（如需要）。 后继者用 awr session resume --from-session … 恢复，得到同样的事实，不重放任何聊天记录。
交付。 你写一份检查项逐条映射到确切验收标准的报告，用 awr work prepare-completion 预检，然后才记录完成。此时状态显示该任务是针对来源 SHA 已验证的，而不仅仅是被标记为完成。

接下来去哪里

快速上手——第一次运行这些概念。
日常工作流——准备、认领、检查点与完成的例行循环。