日常工作流

本指南走一遍可重复的 AWR 日常例行流程：查看项目状态、认领或恢复任务、 记录进展、保存检查点，并完成交接，让你——或某个 agent——能恰好从 停下的地方接手。

开始之前，确保你的项目已初始化，并且了解基本概念（工作项、会话、认领、 检查点）——见快速上手和核心概念。同样的 例行流程也可以通过 MCP 进行；见 MCP。

关于版本的说明：下面提到的部分能力（action 视图和 work edit）反映的是 当前源码树，可能未在发布的包中启用。运行 awr --help 查看你的安装支持 什么。

1. 开始一天：找到下一步行动

在做任何其他事情之前，先运行一次状态检查：

awr status

awr status 和 MCP 工具 awr_project_status 默认使用 action 视图 （view="action"）。它把你未闭合的工作分成四个队列，每个队列最多 显示五个条目，并给出精确的总数和被省略的数量：

用可重复的选择器收窄范围——它们之间取交集：

awr status --work GUIDE-1 --goal GOAL-1 --milestone M1

队列是导航，不是授权：认领和完成检查仍由各自的动作强制执行。 awr ready 保持它更窄的含义——适合新认领——并省略进行中的工作。

2. 认领或恢复任务

每个 shell 设置一次，让每条命令都绑定项目并以 JSON 输出：

AWR_BIN=/absolute/path/to/awr
AWR_PROJECT=/absolute/path/to/initialized/project
AWR_WORK=EXAMPLE-001
AWR_AGENT=agent-primary
AWR_MODEL=your-current-model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

新工作，在新会话下认领：

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")

认领是运行时所有权；它不会改写来源中的工作状态。如果该工作已有会话， 用 session show 检查并确认归属——不同的 agent 或模型应通过 session resume 在它自己的会话中继续。

3. 编译你的上下文

动手编辑之前，为会话构建上下文数据包：

awrj context bootstrap --session "$AWR_SESSION" --budget 1000 \
  > "$AWR_NOTES/bootstrap.json"
jq -e '.context.complete' "$AWR_NOTES/bootstrap.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 时，调大 预算或收窄范围；遇到 SourceStale 时，先运行 awr 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"

关于检查点，有几件事要理解：

• --agent 是调用方的声明。与会话不匹配的声明会被拒绝并给出恢复指引； 匹配的声明也保持未验证状态——CLI 无法认证标签背后真实的模型。 省略它时，来源会被记录为 undeclared。
• 摘要和上下文哈希是你的断言。请使用实际最后使用的哈希；已保存的检查点 不证明上下文已验证、测试已通过或工作已完成。
• 修订版本防护要使用 session show 顶层的 project_revision，而不是 session.revision。发生冲突时，先检查中间的变更再重试。
• 检查点绝不改写来源中的下一步行动。要修改契约，请编辑权威来源文件。

5. 不用手改 YAML 的小字段修正

当来源计划需要小修正时——比如来源写的是"Draft the guide"，但真正的 下一步是"Review the conclusion"——先预览这次编辑：

awr --json work edit GUIDE-1 --request-key guide-next-1 --actor writer \
  --reason 'Clarify the review step' --next-action 'Review the conclusion'

响应会显示来源位置、新旧值，以及用于确认的指纹。核对之后，重复该命令 并加上：

--accept --source-fingerprint SOURCE_FINGERPRINT \
--expected-preview PREVIEW_FINGERPRINT --expected-revision REVISION

支持的字段有 --title、--summary、--priority 和 --next-action。 收到不确定的响应后，检查 host status --key guide-next-1；字段编辑 绝不改变所有权、生命周期或验证状态。

6. 结束会话——或交接出去

当你结束一天的工作时：

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

结束会释放认领；它不会完成来源中的工作。第 4 步保存的检查点才是让 工作能干净恢复的东西。

7. 从你（或某个 agent）停下的地方继续

稍后——或从另一个 agent——从前驱会话恢复：

AWR_PREDECESSOR=the-recorded-awr-session-id
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent "$AWR_AGENT" --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")

Resume 会创建一个新的 AWR 会话；它不会切换你宿主的原生聊天。然后重新 编译上下文（第 3 步）并继续。宿主压缩之后，如果同一个 AWR 会话仍然 活跃，重新编译即可——session resume 要留给真正的交接。

要对比计划与最近记录的内容，查看 status --view action 和 work show KEY 暴露的 progress 对象：

• source_next_action——来源计划中的权威文本，附带其定位符、来源修订 版本和新鲜度。
• latest_checkpoint_next_action——针对这个确切的工作、分支和所有权的 最近一次检查点，没有则为 null。
• differs_from_source——当检查点文本与来源出现分歧时为 true。这是一 个观测结果，不是问题：保存进展绝不会修改原始契约，也不构成完成。

进展文本截断至 240 个字符（标记为 truncated）；完整文本请用 work show KEY 和 session show SESSION。

出问题时

• 保存响应不确定 → 检查 host status --key REQUEST_KEY；host recover 只用于检查过的待决操作。
• 修订版本冲突 → 用 status 读取当前的 project_revision 并带它重试。
• 可疑的检查点 → 用 session show SESSION 读取完整记录；没有完成回执的 中断保存不是可恢复的检查点。

更多故障模式见故障排查。本流程中涉及的词汇见 核心概念。