track-session

会话进度

概述

在项目根目录的 SESSION_PROGRESS.md 中跟踪多会话工作，以便暂停后无需重建上下文即可继续。只有文件内容与实际情况相符时，它才有价值，因此应在工作过程中及时记录检查点——完成任务、计划变更、遇到失败或准备向用户提问后，而不是等别人提醒保存。

cc-dash 仪表板会读取此文件，因此下面的 frontmatter 架构和 HTML id 标记至关重要，并非装饰。

文件格式

---
schema: cc-dash/session@1
project: project-name
session_id: s_YYYY-MM-DD_topic-slug
roadmap_ref: r_XXXXX          # optional — links a roadmap feature
started: YYYY-MM-DDTHH:MM:SS-TZ
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
status: in-progress           # in-progress | paused | completed | blocked
---

# Session Progress

## Bench note

- **Did:** <what got finished, in plain words>
- **Next:** <what happens next, in plain words>
- **Needs you:** <a question or decision waiting on the user; drop the line if none>
- **Acted on:** n_ab12c, <a few words on what was done; only when a note id was given>

## Plan

- [ ]  Task: description
- [x]  Task: description

## Current Status

Working on: <current task>
Next: <specific next action — name files and functions, not "fix the bug">

## Decisions

-  Durable choice + why, so it isn't relitigated on resume

## Failed Attempts

-  Tried X: failed because Y, trying Z instead

## Completed Work

-  What was done

## Plan 和 ## Current Status 至关重要；预期应有 ## Bench note，而 ## Decisions、## Failed Attempts 和 ## Completed Work 则是可选的——有实际内容要记录时再添加。

Bench note

Bench note 是给运行 Agent 的人看的简短状态说明，写法应像向同事介绍当前进展。不要写任务 id、文件路径，也不要使用读者需要查证的术语；这些细节应放在面向下一个 Agent 的 ## Current Status 中。cc-dash 会根据标题读取此内容，无论它在文件中的哪个位置。

• Did 和 Next：各用一句话。
• Needs you：记录等待用户回复的问题或决定。没有待办事项时，省略这一行。
• Acted on：如果用户的提示或备注中带有类似 n_ab12c 的 id，在你采取行动后记录一次：写上 id、一个逗号，再简要说明你做了什么。每条备注占一行。只记录用户提供且你已处理的 id，因为 cc-dash 会将此行视为凭据，不会自行推断。

每次到达检查点、保存文件、结束会话或暂停以向用户提问之前，都应重写本节，而不是追加内容。在本次会话中保留之前的 Acted on 行。控制在四行左右，每行一句；如果备注长到需要滚动查看，就应另设一个 Current Status。

**长度：**每个任务一行；Decisions 和 Failed Attempts 各用 1–2 句话。此文件是状态记录，不是叙述文档——不要添加填充性章节、重复摘要，也不要复述 Completed Work 中已经列出的工作。

上下文重置后必须保留的内容，按优先级排序：遇到的问题及其解决方式（Failed Attempts）；提出、尝试或搁置的选项及原因（Decisions）；用户要求、排除或设定的约束，尽量沿用用户原话；准确的当前进展（Current Status）；尚未完成或已承诺的事项（Plan）；以及难以重建的细节——名称、数字、准确措辞、链接——均须原样保留。这些内容务必完整，必要时可以增加篇幅。将自己的推理压缩为结论。

**ID：**使用 t_（任务）或 f_（失败尝试）加 1–20 个 [a-z0-9_-] 字符——默认使用五个随机字符，也可以用便于记忆的标识（t_redis-mw、t_authfix）。task: 和 ref: 也采用相同格式，且各自只能包含一个 id。roadmap_ref 只能包含一个路线图 id；当一个会话推进多项功能时，在 ## Current Status 中列出其他功能。写入后保持 id 不变，因为 dep: 引用会指向它。每个计划事项都必须包含 id 和 dep（dep:none 或 dep:t_XXXXX）。

记录每种失败尝试及其原因，避免盲目重试。如果失败与环境有关——例如 MCP 服务未连接、缺少凭据或服务宕机——请在条目中注明；后续会话的环境可能不同，因此重新检查是正确的做法，不算重复尝试。

工作流

路由无参数调用

执行不带参数的 /track-session 时，按顺序选择第一个匹配的分支，然后停止：

1. 项目根目录下没有 SESSION_PROGRESS.md → Start。不要根据路线图或 git 历史重建文件；那属于 recover，且仅在用户提出要求时执行。
2. 文件存在，且本次对话中产生了文件尚未记录的工作（自其 last_updated 以来的编辑、测试运行或决策）→ checkpoint，然后继续工作。
3. 文件的 status: completed → 说明上一个会话已结束及其完成的工作，然后交接给 /track-roadmap resume 以选择下一个功能；如果用户已经指定了新工作，则交接给 Start。
4. 其他情况——全新的上下文，文件是唯一记录 → Resume。

判别依据是本次对话中尚未记录的工作，而不是文件看起来完成了多少。如果分支 2 和 4 似乎都符合，就用这一点作为裁决标准：执行 checkpoint。写入几乎为空的增量只会多花一轮，而在尚有未记录工作时恢复，会导致这些工作没有写入文件，并把下一会话交接到过时的计划。

Start 模式

根据仓库确定 project:（文件夹名称、package.json、pyproject.toml），不要沿用即将覆盖的文件中的值。使用时钟记录 started 和 last_updated（见 Checkpoint），设置 status: in-progress，并至少写入 ## Plan、## Current Status 和 ## Bench note。

如果 SESSION_PROGRESS.md 已存在，先阅读，然后检查 git 是否在跟踪它——这决定了替换操作是否可撤销：

git ls-files --error-unmatch SESSION_PROGRESS.md   # exit 0 = tracked; non-zero = untracked or ignored

• 同一项未完成的工作 → 这不是 Start，而是 Resume。到此为止。
• 已跟踪，且上一个会话已 completed/paused，内容无关 → 先向用户确认，然后替换文件；git 中保留着旧版本。
• 未跟踪或被 git 忽略 → 先归档到 SESSION_ARCHIVE_<topic>.md，然后再写入干净的文件。替换未跟踪文件会永久销毁其内容；公共仓库通常会有意将 SESSION_PROGRESS.md 加入 git 忽略规则。如果是这种情况，也应提出将 SESSION_ARCHIVE_*.md 加入 .gitignore，以免归档文件反而泄露。

Checkpoint（无参数调用）和 Save

两者都会将当前状态写入文件：勾选已完成的任务，更新 ## Current Status，重写 ## Bench note，追加决策和失败的尝试，并重新记录 last_updated。唯一的区别是接下来做什么——无参数的 /track-session 执行 checkpoint 后会继续工作，而 /track-session save 执行 checkpoint 后会停止。

所有时间戳都必须取自时钟，不要估算；猜测的时间戳会产生数小时的偏差，而仪表板的过时状态视图会以它为准：

date +%Y-%m-%dT%H:%M:%S%z | sed -E 's/([0-9]{2})$/:\1/'   # 2026-09-22T11:19:48-06:00

勾选最后一个计划任务时，应在同一次写入中设置 status: completed，并告知用户会话已结束。已完成的文件若仍标记为 in-progress，就会在仪表板上无限期显示为进行中的工作。

Resume 模式

阅读文件后，先在回复开头说明实际进度——status、已完成任务数/总任务数、工作树状态、最近一次提交以及下一步操作，再进行任何新的分析。以叙述开场的交接（“我现在会读取会话文件，然后查看测试”）会掩盖用户回来想了解的状态，最后用户还得自行重新推导。

Resume 也是顺手核对信息的自然时机：如果 project: 或 status: 与实际情况不符，就在此处直接修正。

验证与恢复 — 按需加载

• /track-session verify 确认 [x] 任务确实符合要求——读取文件、运行测试、将每项声明与本次运行中的证据关联起来，并追加一个 ## Verification Results 部分，cc-dash 会在会话页面上呈现该部分。当用户要求验证，或勾选框是工作已完成的唯一证据时，加载 reference/VERIFICATION.md。
• /track-session recover 根据 Claude Code 转录记录重建已删除的 SESSION_PROGRESS.md。当文件缺失且用户想要恢复时，加载 reference/RECOVERY.md——其中包含转录记录 slug 的推导方法和经过测试的 Python 重建脚本；该参考文档说明了为何需要它，因为 jq 会错误解析这些转录记录。

示例

✅ 具体且便于续接：

## Plan
- [x]  Phase 1: choose session store (picked Redis)
- [ ]  Phase 2: add session middleware

## Current Status
Working on: Phase 2
Next: add Redis client in src/auth/session.ts, then wire middleware in app.ts

❌ 太过含糊，无法续接：

## Plan
- [ ] Do auth stuff
- [ ] Fix sessions
Working on auth. Tried some things that didn't work.

✅ 以当前状态开头的续接回复：

Paused, 4 of 7 plan tasks done, working tree clean, last commit 3cf23e0 "add session middleware".
Next: add the Redis client in src/auth/session.ts, then wire it in app.ts.

❌ 以叙述开头的续接回复：

Let me start by reading your SESSION_PROGRESS.md to understand the context.
Then I'll check the git log and look through the auth directory...

✅ 不会被盲目重试的失败尝试：

## Failed Attempts
-  Tried `ioredis` autoReconnect for the session store: reconnect storms under the test harness's socket limit. Switched to a single shared client in src/auth/redisClient.ts.
-  Ran the e2e suite against staging: env-scoped — STAGING_URL unset in this shell. Re-check before treating this as a real failure.

❌ 会被重试的失败尝试：

## Failed Attempts
- Redis didn't work, trying something else

✅ 用户十秒内就能读完的 Bench 备注：

## Bench note

- **Did:** Landed the forest and sand vistas.
- **Next:** Town vistas, then stop for review.
- **Needs you:** Dusk or noon light for the town?
- **Acted on:** n_ab12c, stopped after sand as asked.

❌ 写给 Agent 的 Bench 备注，或无法匹配到上下文的备注：

## Bench note

- **Did:** t_a1b2c done, patched src/scene/vista.ts L40-88, tests green
- **Acted on:** stopped after sand as asked

✅ 每个好的版本都会写明文件、ID 和原因；每个欠佳的版本都会让读者从头重建上下文。

注意事项

• 只会解析顶部的 frontmatter 块。 第二个 --- 之后的所有内容对 cc-dash 都不可见，因此包含多个连续会话的文件只会静默报告最新的一个。
• **许多公开仓库会将 SESSION_PROGRESS.md 加入 gitignore，**因此“直接替换它，git 有历史记录”在这些仓库中并不成立。替换前先检查 git ls-files --error-unmatch；如果返回非零值，先归档。
• cc-dash 会丢弃 id 不匹配的条目并发出警告，其余内容仍会保留。 ref: 或 roadmap_ref 中的逗号分隔列表，以及包含空格或大写字母的 id，都会导致对应条目或链接从仪表板中消失。修正格式错误的值，但不要把有效的助记 id 改成随机令牌——重命名 id 会使所有指向它的 dep: 变成孤立引用。
• 每次写入时都要重新设置 last_updated。 仪表板的过时状态视图以此为依据，因此检查点若漏掉这个时间戳，会让进行中的工作看起来像是已被搁置。
• save 会停止工作。 用户可能在流程中途输入它，以为这是创建检查点，随后却纳闷你为什么停了；只有单独的 /track-session 会创建检查点并继续。
• 有子 Agent 仍在运行时，save 不会停止它们。 你说已停止后，它们的结果仍会到达。在 ## Current Status 下列出每个正在运行的 Agent 及其任务，并告知用户结果仍会送达，这样下一次会话就知道要留意。
• cc-dash 无法读取的 Bench note 行会被丢弃并发出警告；其余内容仍会计入。 标签必须完全准确（Did、Next、Needs you、Acted on），并且每个 Acted on 都必须以五个字符的 n_ 小写 id 开头。出现两个 Bench note 章节时只会读取第一个，因此请在原处改写。
• 其他标题会保留，但不会显示。 cc-dash 会读取 Plan、Current Status、Bench note、Decisions、Failed Attempts 和 Completed Work，并显示 Verification Results；## Notes 章节会保留在磁盘上，但不会出现在仪表板中。应将需要留存到会话之后的发现作为引述备注写入关联的路线图条目（参见 track-roadmap），而不是放进自行创建的章节。
• 每个仓库只在根目录放一个文件。 即使在子目录（如 godot/ 或 web/ 文件夹）中工作，检查点也会写入根目录的文件；如果在更深的目录中再放一个 SESSION_PROGRESS.md，记录就会分散，而仪表板只会读取其中一个。
• 使用 Edit 或 Write 写入文件，不要使用 Bash heredoc 或 sed -i。 recover 会通过重放对话记录中的 Edit 和 Write 调用来重建文件，因此通过 Bash 进行的更新对它不可见。
• 恢复时很少能找到完整的内容块。 由于更新是通过增量 Edit 完成的，对话记录中通常没有完整的 Write——应准备将编辑重放到最新快照上，而不是直接提取其中一份副本。

集成

• track-roadmap — 从路线图中选择一项功能，然后通过 roadmap_ref: r_XXXXX 将其实现关联到此处。会话结束前，应将会话结束后仍有价值的研究内容、待解决问题和已否决的替代方案作为引述备注写回该路线图条目。
• 在提交和测试阶段之间创建检查点，让文件状态与提交边界保持一致，以便后续会话通过 git show 查看。

如需了解恢复失败、会话文件过大和验证边缘情况，请参阅 reference/TROUBLESHOOTING.md。