weekly-digests

每周摘要

根据项目的完整 claude-mem 历史，生成一组连续的多章节叙事摘要。与 timeline-report（一篇长报告）不同，此工具每个 ISO 周生成一篇摘要，每个子 Agent 都会阅读前一周的延续块，以保持故事连贯。

章节数等于时间线涵盖的 ISO 周数。 有 2 周数据的项目会生成 2 章；有 30 周数据的项目会生成 30 章。长度不固定——先统计周数，再根据该数量运行流水线。

适用场景

当用户提出以下要求时触发：

• “每周摘要”
• “逐周讲述”
• “连续时间线”
• “[项目] 的故事章节”
• “每周生成一篇摘要”
• “逐周继续讲述故事”

如果用户想要一篇全面的报告，请改用 timeline-report。此技能用于连续章节格式。

前提条件

• claude-mem worker 正在运行
• 项目至少有一个 ISO 周的观察记录（流水线可优雅处理退化情况——即使 N=1 也能正常运行）
• 一个用户愿意写入内容的干净输出目录

解析 worker 端口（只需执行一次，后续复用 $WORKER_PORT）：

WORKER_PORT="${CLAUDE_MEM_WORKER_PORT:-$(node -e "const fs=require('fs'),p=require('path'),os=require('os');const uid=(typeof process.getuid==='function'?process.getuid():77);const fallback=String(37700+(uid%100));try{const s=JSON.parse(fs.readFileSync(p.join(os.homedir(),'.claude-mem','settings.json'),'utf-8'));process.stdout.write(String(s.CLAUDE_MEM_WORKER_PORT||fallback));}catch{process.stdout.write(fallback);}" 2>/dev/null)}"

工作流

步骤 1：确定项目名称

使用与 timeline-report 相同的 worktree 检测模式。在 worktree 中，数据源是父项目：

git_dir=$(git rev-parse --git-dir 2>/dev/null)
git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
if [ "$git_dir" != "$git_common_dir" ]; then
  parent_project=$(basename "$(dirname "$git_common_dir")")
else
  parent_project=$(basename "$PWD")
fi
echo "$parent_project"

步骤 2：获取完整时间线并保存

mkdir -p .scratch
curl -s "http://localhost:${WORKER_PORT}/api/context/inject?project=PROJECT_NAME&full=true" \
  > .scratch/cm-timeline.md
wc -l .scratch/cm-timeline.md

合理性检查：确认文件非空且结构符合预期（前言，随后是日期标题，如 ### Mon DD, YYYY，然后是数字观察记录行 <id> <time> <emoji> <title> 和会话边界行 S<n> <prompt> (Mon DD at HH:MMpm)）。

步骤 3：将时间线拆分为每个 ISO 周的文件

编写 Python 脚本 .scratch/split-timeline.py，该脚本需：

1. 解析日期标题（### Mon DD, YYYY）。
2. 使用 date.isocalendar() 将日期归入 ISO 周（周一开始）。
3. 为每周生成一个文件，路径为 docs/timeline-weeks/<YYYY>-W<NN>-<MonDD>-to-<MonDD>.md，并逐字保留每天的章节。
4. 执行双重检查：拆分后分布的观察记录总数必须与源文件中的数量一致。

输出结构（文件名仅供示例）：

docs/timeline-weeks/
  README.md                       # weekly index table
  YYYY-W<NN>-MonDD-to-MonDD.md    # one per ISO week the timeline covers
  ...

每个周文件都应逐字保留原始的每日章节。此阶段不要改写——摘要 Agent 需要原始内容的准确性。

在启动流水线之前，统计生成的文件数。 该数量就是 TOTAL，后续每个步骤都以此为准。应跳过空周（活跃周之间没有观察记录的周）——流水线仅处理有内容的周。

步骤 4：创建每周索引 README

在 docs/timeline-weeks/README.md 中创建一个 Markdown 表格：Week | Dates | Observations | Sessions | File。这是操作者的路线图，也有助于 Agent 了解各周的节奏（高峰周与低谷周）。

步骤 5：运行连续子 Agent 流水线

重要：子 Agent 必须按顺序运行，而不是并行运行。 每个 Agent 都会收到前一个 Agent 的延续块。这正是此技能的核心——没有它，你会得到 N 份互不关联的摘要；有了它，你会得到一篇由 N 章组成的连续叙事。

创建输出目录：

mkdir -p docs/timeline-weeks/digests

按时间顺序逐周派发通用型 Task 子 Agent，并使用以下提示词模板。启动下一个 Agent 前，必须等待当前 Agent 完成。 从结果中提取延续块，并将其作为 STORY_SO_FAR 注入下一个提示词。

子 Agent 提示词模板

You are writing chapter {N} of {TOTAL} in a serial week-by-week digest of the {PROJECT} project's development history. Chapters 1 through {N-1} are written. {SPECIAL_NOTE: e.g. "This is the LARGEST week", "This is the TROUGH", "This is the FINAL chapter", "This is the ONLY chapter — both first AND final week"}.

**Source file (read in full):**
{ABSOLUTE_PATH_TO_WEEK_FILE}

**Output digest file (write):**
{ABSOLUTE_PATH_TO_DIGEST_FILE}

**Format key for the source file:**
- Numeric lines like `1 7:59p 🔵 Save hook file is empty` are observations (ID, time, type-emoji, title)
- `S##` lines are session boundaries (the user prompt that started the session)
- Emoji legend: 🎯session 🔴bugfix 🟣feature 🔄refactor ✅change 🔵discovery ⚖️decision 🚨security_alert 🔐security_note 🤫sensitive

**Story so far (carry-forward from Week {N-1}):**

{STORY_SO_FAR_BLOCK_OR_EMPTY_FOR_WEEK_1}

**Your digest must include:**
1. **Title line** — `# Week {N} ({WEEK_LABEL}): {DATE_RANGE} — [your chosen subtitle]`
2. **One-line tagline** — what this week is about, in plain English
3. **Narrative section** ({BUDGET}) — tell the story. Resolve threads from prior weeks where the data shows resolution. Introduce new arcs. Use specific observation details.
4. **Threads continued / opened / resolved** sections
5. **Cliffhanger / What's next**
6. **Carry-forward block** at the very bottom, fenced as ```carry-forward ... ``` — structured handoff for the next week's agent.

**CARRY-FORWARD DISCIPLINE:**
- Cap at ~350 words.
- AGGRESSIVELY PRUNE: drop arcs that didn't surface this week unless they're actively unresolved cliffhangers.
- Drop cast members absent 2+ weeks unless load-bearing for the long arc.
- Quality over completeness. The next agent inherits what you mention; mention judiciously.

Required carry-forward sub-sections:
- **Active arcs** — ongoing themes/projects the next agent should watch for
- **Cast** — notable named systems/people/tools (continuing + new)
- **Unresolved** — open questions or unfinished work
- **Tone notes** — how the story is being told (voice, perspective, register evolution)

**Tone rules:**
- Third-person narrator, sharp, observational. Not twee.
- AI is "Claude"; human is "{USER_FIRST_NAME}".
- Treat codebase components as characters — whatever the project's recurring named systems are (e.g. a worker, a queue, a process manager, a recurring bug, a flaky migration). Don't import names from another project; use what shows up in this project's observations.
- Don't manufacture drama. Name what's there.
- Track the user's prompt-register evolution week by week (frustration markers, escalation language, shifts in tone).
- Note meta-recursion if the project is reflexive about its own behavior (e.g. a tool that documents its own work, an AI agent debugging itself, a system that catches its own regressions).
- Watch for new villains or co-stars and name them.
- For trough/silent weeks: silence IS the story. Don't pad. Name what didn't happen.
- For surge weeks (>2,000 obs): pick 4-7 spine arcs and tell them well. Don't catalog.

**Important:** Do NOT speculate beyond what's in the source file.

After writing the file, return:
1. Path of the file you wrote
2. The carry-forward block verbatim
3. One-sentence summary of the week

按观察记录数量设定叙事篇幅

根据每周的内容量按比例调整叙事长度：

Obs count	Narrative section budget
< 100	200–400 字
100–500	300–600 字
500–1,500	500–900 字
1,500–3,000	700–1,100 字
3,000+	800–1,300 字

将这些篇幅范围填入每周提示词中的 {BUDGET} 位置。

第一周

对于第 1 周，传入空的 STORY_SO_FAR_BLOCK，并注明这是起源章节——Agent 应为后续所有章节中的人物确立初始阵容、基调和故事线。

最后一周

最后一周采用不同的结尾：不提供延续区块。改为指示 Agent 撰写一个 ## Where We Are 部分（约 250 词），说明写作当下仍有哪些事项尚未解决。告诉 Agent 项目仍在进行——摘要会停止，故事不会。不要给故事一个虚假的结局。

当 N = 1（单周项目）

对同一章节同时采用两种处理方式：使用空的 STORY_SO_FAR_BLOCK，并以 ## Where We Are 代替延续区块。Agent 要在一次写作中同时完成起源和收尾。不要提及不存在的前后章节。

步骤 6：重命名文件，使顺序可排序

Agent 写出的摘要文件名类似 YYYY-W<NN>-digest.md。这些文件已按 ISO 周次按时间顺序排列（除非某个项目跨越了年份边界），但请添加带前导零的数字前缀，让用户浏览目录或编写脚本处理目录时都能明确判断顺序：

cd docs/timeline-weeks/digests
total=$(ls *.md | wc -l | tr -d ' ')
width=${#total}                  # 1 for N<10, 2 for N<100, 3 for N<1000
[ "$width" -lt 2 ] && width=2    # always pad to at least 2 for readability
i=0
for f in *.md; do
  printf -v prefix "%0${width}d" $i
  mv "$f" "${prefix}-$f"
  i=$((i+1))
done

N=30 时，结果为 00-...md 至 29-...md。N=4 时，为 00-...md 至 03-...md。N=120 时，为 000-...md 至 119-...md。始终补齐前导零——否则 1-...md 和 10-...md 的排序会出错。

不要同时在每个文件内的摘要标题行前添加顺序编号。文件名前缀用于排序；标题应保持简洁：# Week N (W##): Date — Subtitle。

步骤 7：报告完成情况

告知用户：

• 摘要覆盖的总周数（N）
• 输出目录路径
• 覆盖的日期范围
• 值得标记的静默周／低谷周
• 用一句话概述故事线的收束语——由最后一章的 Agent 撰写，或由操作人员根据最后一个 Agent 的 ## Where We Are 部分撰写。

流程规范

这些规则是在端到端运行流程时总结出来的。每次都要贯彻执行：

1. 按顺序处理，不要并行处理。 延续链条是整个流程的核心。并行会破坏链条。
2. 限制延续内容的长度。 不主动精简，内容就会膨胀。告诉每个 Agent：控制在约 350 词，删去休眠故事线和未出现的人物。
3. 明确追踪语气的演变。 用户每周的提示词风格变化本身就是一条故事线。挫败感的标记会随时间变化（具体标记取决于这个项目的数据）。指出这些变化。
4. 把组件视为角色。 观察中反复出现的具名系统，都是这个项目中的反派和重要配角。每周保持稳定的人物阵容，能建立叙事连贯性。
5. 尊重沉默。 低谷周（10–100 条观察）也是实实在在的章节。指出没有发生什么。不要凑内容。
6. 不要凭空制造戏剧性。 只观察数据。如果项目具有反身性，递归本身就是戏剧性；无需再添枝加叶。
7. 最后一周：不要给出虚假的结局。 摘要会停止，项目不会。撰写 ## Where We Are，而不是“故事结束”。

错误处理

• 时间线为空：项目名称错误，或工作进程未运行。运行 curl -s "http://localhost:${WORKER_PORT}/api/search?query=*&limit=1" 进行验证。
• 工作进程未运行：使用常用方法启动，或检查 ps aux | grep worker-service。
• 子 Agent 返回格式错误的延续内容：通过正则表达式提取延续区块（```carry-forward ... ```），并原样传递。如果缺失，请要求 Agent 重试，并明确指示：“你的回复必须在末尾包含用 carry-forward ... 围住的延续区块。”
• 某个 Agent 在流程中途失败：使用相同的延续内容重试该周。不要跳过，否则链条会断裂。
• 延续内容超过约 500 词：在后续提示词中加强精简要求，并明确要求删减。

示例

长期项目（约 30 周）

用户：“从头到尾为 [project] 制作每周简报”

1. 解析工作器端口，检测项目名称。
2. 获取完整时间线 → .scratch/cm-timeline.md。
3. 运行 .scratch/split-timeline.py → 在 docs/timeline-weeks/ 中生成 N 个每周文件（例如 30 个）。
4. 生成 docs/timeline-weeks/README.md 索引。
5. 依次启动 N 个子 Agent，每周一个。每个子 Agent 都会收到上一周的延续内容。第一章的延续内容为空；最后一章写入 ## Where We Are，而不是延续内容区块。
6. 为简报文件名添加带前导零的顺序前缀（从 00-...md 到 29-...md）。
7. 报告章节总数、日期范围、任何低谷／高峰，以及最终 Agent 生成的一句话总结。

短期项目（约 3 周）

流程相同，只是规模较小。N=3，因此：

• 第 1 章：延续内容为空，确立人物、基调和故事线。
• 第 2 章：接收第 1 章的延续内容，并在此基础上展开。
• 第 3 章：接收第 2 章的延续内容，但按最终章节处理（写入 ## Where We Are，而不是延续内容区块）。
• 文件名：00-...md、01-...md、02-...md。

单周项目（N=1）

对唯一章节同时采用首章和最终章节的处理方式：延续内容为空，以 ## Where We Are 收尾，不引用其他章节。文件名：00-...md。