@fanchao8609/agent_brain_sync 1.8.5 → 1.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.8.5",
+  "version": "1.8.7",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",

package/skill/abs-agent-brain-sync/SKILL.md

@@ -30,6 +30,7 @@ abs todo state <id> --note "进行中|讨论中|滞留中"  # 改状态标记（
 abs todo done <id> [--as 落地|否决|仅方案]      # 完成（默认 落地）
 abs log "完成 X：…"                            # 记一行工作成果（无参=查看）
 abs note "经验一句话" [--tags 坑,docker]        # 经验实时暂存 → sources/
+abs concept <slug> --title "标题" [--tags a,b]  # 建概念页骨架（头/中/尾，只给结构不给内容）
 abs rule [add "一句话"]                        # 读写 index.md 的 ## Rules 硬规则
 
 # 维护
@@ -127,7 +128,8 @@ load 只展示最新 5 条、每条按语义边界收口。
 行形态：`- [ ] [进行中] <id> [[name]] — 说明 (认领 YYYY-MM-DD)`
 
 `abs todo done <id>` 会勾选并归位到 Done 的日期组顶部，断点（`↳` 行）随迁；
-Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已完成」的组迁到 `sessions/<日期>-todo归档.md`
+Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已完成」的组迁进
+**当天会话快照的 `## 📦 任务归档` 段**（`sessions/log-<日期>.md`）—— 归档不另建文件
 （任一天有未完成则整天不迁）。**什么时候动它见「进行中」一节。**
 
 ### `entities/` `concepts/` `sources/` `syntheses/` `sessions/`
@@ -138,10 +140,50 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 | `concepts/` | 可复用的**规律/坑**（能说"这么做就避坑"） | `docker-prisma-429.md` |
 | `sources/` | 实时经验**暂存**（`abs note` 自动落） | `YYYY-MM-DD-slug.md` |
 | `syntheses/` | **横向**选型/架构取舍（跨多个 entity/concept 的判断） | `synthesis-slug.md` |
-| `sessions/` | 会话快照 + `## 🪝 Next Session Hook`、todo 归档页 | `log-YYYY-MM-DD.md` |
+| `sessions/` | 会话快照（含 `## 🪝 Next Session Hook`）+ 当日任务归档段 | **`log-YYYY-MM-DD.md`** |
 
 归类拿不准时**默认 `concepts/`**。
 
+### `sessions/` 命名契约：一天一个文件（硬规则）
+
+**一天只允许一个文件，且只能叫 `log-<日期>.md`。** 该日的一切都放进它：
+
+```
+log-2026-09-08.md
+  ├─ 会话快照正文（AI 手写：做了什么/怎么定位/结论）
+  ├─ ## 关联连接
+  ├─ ## 🪝 Next Session Hook（强制）
+  └─ ## 📦 任务归档（`abs todo archive` 自动写，机器生成勿手改）
+```
+
+**为什么定死**（实测 codebuddy 项目乱成这样，2026-09-15）：同一天曾出现 **5 个文件**：
+`2026-09-07-init-brain.md` / `-todo-md-archive.md` / `-todo归档.md` / `-ui-fixes.md` / `log-2026-09-07.md`，
+且五份的 `tags` 各不相同（`source` / `source,archive` / `todo-archive` / `source,session-log` / `session-log`）。
+同一天的记录散在多处，查一次要开五个文件。
+
+**✅ 归档的正规做法**（用户 2026-09-15 定为标准，以后都这么干）：
+
+```bash
+abs todo archive            # 一条命令搞定，无需手工搬
+```
+
+它自动把过期日期组写进 `sessions/log-<那天>.md` 的 `## 📦 任务归档` 段：
+- 该日**已有快照** → 只替换归档段，**段外的手写内容逐字保留**（不覆盖人工内容）
+- 该日**没有快照** → 建一个只有归档段的 `log-<日期>.md`（那天本来就只有任务记录）
+- 同日二次归档 → 段内追加，不重复建段
+
+**结论：归档这件事不需要「方法」，只需要跑那条命令。**下面的禁令是给**手写**用的
+（手写时才可能犯错）。
+
+**四条禁令**（每条都有实测反例）：
+1. **不要**再把归档单独建文件（`<日期>-todo归档.md`）——归档已有专门的坑位段，`abs todo archive` 会写进去。
+   存量旧页不必手改（lint 不报），但新归档不再产生它。
+2. **不要**在 `sessions/` 放 `tags: [source]` 的页——暂存页属 `sources/`。
+   当天做的一组工作不是「暂存线索」，而是**当天的快照正文**：直接写进 `log-<日期>.md`。
+3. **不要**一天拆多个快照（`log-<日期>-<主题>.md`）——多主题就多写几个 `##` 段。
+4. **不要**手工搬大文件进来当归档（如把仓库根 `todo.md` 全文倒进 `sessions/`）——
+   那要么进 `sources/`，要么摘出规律进 `concepts/`；全文属外部产物，用指针就行。
+
 ### 容量纪律（写任何页之前过四关）
 
 图谱贵在**精**不在全，不过关就不写或压缩：
@@ -150,7 +192,7 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 3. **sources 是暂存**：提炼成规律后删/归档，并清掉指向它的引用（防死链）。
 4. **能不能用一行链接代替新增整页**？
 
-`abs lint` 兜底：死链/孤岛/**悬挂页(NO-INBOUND)**/缺 frontmatter/超限/sources 堆积/**超龄未提炼(SOURCE-UNDISTILLED)**/index 漏列/Rules 超限。
+`abs lint` 兜底：死链/孤岛/**悬挂页(NO-INBOUND)**/缺 frontmatter/超限/sources 堆积/**超龄未提炼(SOURCE-UNDISTILLED)**/index 漏列/Rules 超限/**缺尾(NO-TAIL，concept 页没有「做完怎么确认」)**。
 ## 开场：Init Sync（开工 / 默认续 todo）
 
 图谱已存在；收到第一个核心开发指令**之前**走这条链载入上下文：
@@ -166,7 +208,7 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
    >
    > **`## Rules` 区原样保留** —— 那是 load 要传达的状态本身（代码里明确不折）。
    > 要全量明细：`abs todo --full` / `abs index`，或直接读 `.brain/` 文件、
-   > `.brain/sessions/<日期>-todo归档.md`。
+   > `.brain/sessions/log-<日期>.md`（含 `## 📦 任务归档` 段）。
 2. **对账滞留（强制，别跳过）**：若 `abs load` 顶部出现 `⏳ 上会话滞留`，说明上会话有任务做完/做到一半就断了。**先收尾再开工**：
    - 快照里的任务现在真做完了 → `abs todo done <id>`（done 后下次 load 滞留自动消失）；
    - 还没做完 → `abs todo note <id> --note "接到哪/改到哪个文件"` 补断点（别空手续接）。
@@ -253,7 +295,10 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 任务告一段落/结束前，把**真实发生**写回图谱。只写做过/跑过/测过的事实，禁止脑补。按序：
 
 1. **暂存线索**：`abs note`（或建 `sources/YYYY-MM-DD-slug.md`）记做了什么、改哪些文件、验证命令。
-2. **抽规律**：值得留的 → `concepts/<kebab-slug>.md`：触发场景/❌表现/🛠根因+解法+验证。挂双链。
+2. **抽规律**：值得留的 → **用 `abs concept <slug> --title "…"` 建页**（自动带好四段骨架
+   并登记 index），再填内容。手写也行，但**四段位置别缺** —— 尤其末尾的「验证」段：
+   **没尾巴的经验只能被「相信」，不能被「验证」**（`abs lint` 会报 NO-TAIL）。
+   **判断仍归你**：这条值不值得留、该新建还是并入已有页 —— `abs concept` 只给结构，不替判断。
    **同时检查：旧页里有没有被本次推翻的说法？** 有 → `abs supersede <旧页> --by <新页>`
    （别删页；删了会让下个会话重踩同一个坑、重新记一遍）。核实过的新页把 `status` 改成 `active`
    （`abs note` 落的页默认是 `draft`）。

package/src/store.js

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { requireBrain, brainPath, absLogDir, BRAIN_DIR } from './index.js';
 import { requireUser, atTag, getUser } from './userconfig.js';
-import { stripStateMark, ensureStateMark, normalizeTodo, addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, setStateMark, TASK_STATES, insertDoneGrouped, idOfTaskLine, archiveDoneInText, renderArchivePage, renderArchiveBody, DONE_KINDS, withDoneKind, doneKindOf, doneDateOf, collapseDone, SEC, rebuildStructure } from './todo.js';
+import { stripStateMark, ensureStateMark, normalizeTodo, addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, setStateMark, TASK_STATES, insertDoneGrouped, idOfTaskLine, archiveDoneInText, upsertArchiveSection, DONE_KINDS, withDoneKind, doneKindOf, doneDateOf, collapseDone, SEC, rebuildStructure } from './todo.js';
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor } from './wrapup.js';
 
@@ -685,16 +685,17 @@ export async function cmdTodoArchive({ dir, keepDays = 3, dryRun = false } = {})
     return `[dry-run] 将归档 ${plan.archived.length} 天 / ${plan.count} 条（每天一个文件）\n  ${brief}${why}`;
   }
 
-  // 1) 归档页：**每天一个文件**，文件名用被归档那天的日期（便于按天回溯）。
-  //    同一天再次归档（罕见：该日组已被移走，除非有人重新补当天任务）则追写正文。
+  // 1) 归档目标 = 当天的会话快照文件（log-<日期>.md），写进其「任务归档」段。
+  //    为何合一（2026-09-15 用户定）: 归档与会话快照是**同一天的记录**，分两个文件查着要开两处。
+  //    边界: ① 文件不存在→建只有归档段的页（那天可能没写快照）
+  //          ② 文件已存在（含 AI 手写快照）→ 只替换归档段，段外逐字保留
+  //    （硬规则「已存在的人工内容一律不覆盖」由 upsertArchiveSection 保证）。
   const sessDir = brainPath(root, 'sessions');
   for (const g of plan.archived) {
     const pageP = join(sessDir, `${g.slug}.md`);
     let page = null;
     try { page = await fs.readFile(pageP, 'utf8'); } catch { /* 首次 */ }
-    const nextPage = page == null
-      ? renderArchivePage({ group: g })
-      : page.replace(/\s*$/, '') + '\n\n' + renderArchiveBody([g]) + '\n';
+    const nextPage = upsertArchiveSection(page, g);
     const tmp = join(sessDir, `.${g.slug}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`);
     await fs.writeFile(tmp, nextPage, 'utf8');
     await fs.rename(tmp, pageP);
@@ -707,15 +708,17 @@ export async function cmdTodoArchive({ dir, keepDays = 3, dryRun = false } = {})
   });
 
   // 3) index 登记（每个日期页一行，幂等）
+  // 坑（2026-09-15 修）: 原先把归档页登记到 `## Sources` 区 —— 但它们在 sessions/ 里，
+  // 旧数据实测就是错位的（09-10/09-12 两条曾键在 Sources 段，人工才发现）。现改登 `## Sessions`。
   const iP = brainPath(root, 'index.md');
   await editFile(iP, (index) => {
     if (!index) return SKIP;
     const missing = plan.archived.filter((g) => !index.includes(`[[${g.slug}]]`));
     if (!missing.length) return SKIP;
-    const sIdx = index.indexOf('## Sources');
+    const sIdx = index.indexOf('## Sessions');
     if (sIdx === -1) return SKIP;
     const after = index.indexOf('\n## ', sIdx + 1);
-    const add = missing.map((g) => `- [[${g.slug}]] — Todo 归档：${g.date}，共 ${g.count} 条已完成任务`).join('\n');
+    const add = missing.map((g) => `- [[${g.slug}]] — ${g.date}（会话快照 + 任务归档）`).join('\n');
     const next = after === -1
       ? `${index.replace(/\s*$/, '')}\n${add}\n`
       : index.slice(0, after) + `\n${add}` + index.slice(after);
@@ -1355,9 +1358,13 @@ export async function cmdLint({ dir }) {
         issues.push(`DEAD-LINK: ${pg.rel} -> [[${ln}]]`);
       }
     }
-    // ORPHAN: sources/ 暂存页与 todo 归档页豁免。前者是暂存线索（提炼成 concept 前天然孤立），
-    // 后者是历史数据倾倒（已登记在 index.md，就是图谱入口，无需再制造双链）。
-    const isTerminal = pg.dir === 'sources' || /todo归档$/.test(pg.slug);
+    // ORPHAN: sources/ 暂存页与会话/归档页豁免。前者是暂存线索（提炼成 concept 前天然孤立），
+    // 后者是历史记录（已登记在 index.md，就是图谱入口，无需再制造双链）。
+    // 豁免名单含两种归档命名：旧 `*-todo归档`（存量页仍在）+ 新 `log-*`
+    //（2026-09-15 起归档并入当天快照，见 todo.js 的 upsertArchiveSection）。
+    const isTerminal = pg.dir === 'sources'
+      || /todo归档$/.test(pg.slug)
+      || (pg.dir === 'sessions' && /^log-/.test(pg.slug));
     if (!isTerminal && !pg.links.length && !linkedNames.has(pg.slug)) {
       issues.push(`ORPHAN-PAGE: ${pg.rel} (no links out, no links in)`);
     }
@@ -1367,7 +1374,12 @@ export async function cmdLint({ dir }) {
     if (['concepts', 'entities', 'syntheses'].includes(pg.dir) && !(inbound.get(pg.slug) || 0)) {
       issues.push(`NO-INBOUND: ${pg.rel} (无人链接到本页；在相关页的 ## 关联连接 挂一条 [[${pg.slug}]]）`);
     }
-    if (/知识冲突/.test(pg.body) && /status: draft/.test(pg.frontmatter)) {
+    // UNRESOLVED-CONFLICT: 有「## 知识冲突」段但还是 draft = 冲突标了没裁决。
+    // 判据必须认【段标题】而非页内出现「知识冲突」字样。
+    // 坑（2026-09-15 实测）: 原用裸子串 → codebuddy 的会话快照因任务描述里写了
+    // 「更新 session-key-fingerprint-flaw（知识冲突裁决）」而误报（它并无该段）。
+    // 同 NO-TAIL 的教训: 判据看结构，不看关键词。
+    if (/^#{2,6}[^\n]*知识冲突/m.test(pg.body) && /status: draft/.test(pg.frontmatter)) {
       issues.push(`UNRESOLVED-CONFLICT: ${pg.rel}`);
     }
     if (['concepts', 'entities', 'syntheses'].includes(pg.dir)) {
@@ -1419,6 +1431,54 @@ export async function cmdLint({ dir }) {
     }
   }
 
+  // SESSIONS-NAMING: sessions/ 的一天一文件契约（见 skill 的「sessions/ 命名契约」）。
+  // 实测 codebuddy 乱局（2026-09-15）：一天最多出现 5 个文件、5 种 tags、同天两个快照。
+  // 判据纯机械：按“日期前缀”归组——同天 >1 个文件报 SPLIT；单个但非规范名报 NAMING。
+  // 只看文件名，不猜内容。
+  const sessByDate = new Map();
+  for (const pg of pages) {
+    if (pg.dir !== 'sessions') continue;
+    // 同时认两种写法：规范名 `log-<日期>` 与旧/杂命名 `<日期>-…`。
+    // 坑（写测试时抓到的）: 首版只写 `^(\d{4}-…)` → **匹配不上规范名 `log-2026-09-07`**，
+    // 于是「一个 log- + 一个旧杂文件」被数成 1 个而非 2 个，漏报。
+    const m = pg.slug.match(/^(?:log-)?(\d{4}-\d{2}-\d{2})/);
+    if (!m) continue;
+    // 长期存续的归档页豁免：**只认独立的 `archive` 标签**（如 `tags: [session-log, archive]`），
+    // 不认 `todo-archive`（那是旧归档页的标签，它正是要迁移的对象）。
+    // 坑（2026-09-15 在 ~/Docker 实测抓到）: 首版用 `\barchive\b` —— 而 `todo-archive`
+    // 里 `-` 与 `a` 之间也是词边界 → **老式归档页全被豁免**，一个都不报（漏报四天）。
+    // 豁免是为「外部产物全文归档」（如仓库 todo.md 全文）设的，不是为旧命名归档页。
+    const tags = String(pg.frontmatter).match(/^tags:\s*(.+)$/m)?.[1] || '';
+    const tagList = tags.replace(/^\[|\]$/g, '').split(',').map((t) => t.trim());
+    if (tagList.includes('archive')) continue;
+    if (!sessByDate.has(m[1])) sessByDate.set(m[1], []);
+    sessByDate.get(m[1]).push(pg.slug);
+  }
+  for (const [date, slugs] of sessByDate) {
+    if (slugs.length > 1) {
+      issues.push(`SESSIONS-SPLIT: ${date} 在 sessions/ 有 ${slugs.length} 个文件（${slugs.join('、')}）；` +
+        `一天只应有一个 \`log-${date}.md\`：归档写进其「## 📦 任务归档」段，多主题写成多个 ## 子段`);
+    } else if (!slugs[0].startsWith('log-')) {
+      // 单个文件但**不是规范名** —— 旧命名（`<日期>-todo归档.md` 等）单独存留。
+      // 坑（2026-09-15 在 ~/Docker 实测抓到）: 首版只看“同天 >1 个” → 4 个日期
+      // 各只有一份 `<日期>-todo归档.md` → 一个都不报（漏报）。
+      // 旧命名的页无论是否孤单都该改：跑 `abs todo archive` 后并入 `log-<日期>.md`。
+      issues.push(`SESSIONS-NAMING: ${date} 的文件 \`${slugs[0]}.md\` 不是规范名；` +
+        `应为 \`log-${date}.md\`（跑 abs todo archive 会并入；旧归档页可删）`);
+    }
+  }
+  // SESSIONS-MISPLACED: sessions/ 里放了 tags 既非 session-log / todo-archive / archive 的页。
+  // 实例：codebuddy 的 `2026-09-07-ui-fixes.md`（tags: [source,session-log]）等 5 页 ——
+  // 当时做的一组工作不是「暂存线索」，而就是当天的快照正文。
+  for (const pg of pages) {
+    if (pg.dir !== 'sessions') continue;
+    const tags = String(pg.frontmatter).match(/^tags:\s*(.+)$/m)?.[1] || '';
+    if (!/session-log|todo-archive|archive/.test(tags)) {
+      issues.push(`SESSIONS-MISPLACED: ${pg.rel}（tags: ${tags.trim()} 不属 sessions/；` +
+        `当天工作写进 \`log-<日期>.md\` 正文，暂存线索用 \`abs note\` 落 sources/）`);
+    }
+  }
+
   // SUPERSEDED-DANGLING: superseded 页声明的取代者也必须存在。
   // 它跟 DEAD-LINK 同性质（指向不存在的页），但后果更重：
   // 读者被引导去找一个不存在的"新版本"，比单纯断链更容易让人以为"没新页就是没替代"。

package/src/todo.js

@@ -426,13 +426,13 @@ function isUndoneLine(l) {
  * 规则（用户定）：
  *   ① 只保留近 keepDays 天（含今天）；更早的才归档。
  *   ② 某一天只要还有未完成（- [ ]）任务，**整天都不归档**（不拆半天）。
- *   ③ 每**天**归一个文件，slug 为 `<日期>-todo归档`（由 slugFor 给），本函数只负责
- *      从 todo 文本里移除 + 在 Done 区尾部的 `### 归档` 区**每天记一行**
- *      `- [[<日期>-todo归档]] 完成任务 N 条`。
+ *   ③ 每**天**一个文件，slug 为 `log-<日期>`（由 slugFor 给）—— 即**归进那天的会话快照**
+ *      （同一天的东西放一处，别为归档另建文件）。本函数只负责从 todo 文本里移除
+ *      + 在 Done 区尾部的 `### 归档` 区**每天记一行** `- [[log-<日期>]] 完成任务 N 条`。
  * 无日期组（### （未标日期））无法判天数，**保守不归档**。
  * @returns {{text:string, archived:{date:string,lines:string[],slug:string,count:number}[], skipped:{date:string,reason:string}[], count:number}}
  */
-export function archiveDoneInText(text, { keepDays = 3, from = today(), slugFor = (d) => `${d}-todo归档` } = {}) {
+export function archiveDoneInText(text, { keepDays = 3, from = today(), slugFor = (d) => `log-${d}` } = {}) {
   const lines = String(text || '').split('\n');
   const di = lines.findIndex((l) => l.startsWith('## Done'));
   if (di === -1) return { text, archived: [], skipped: [], count: 0 };
@@ -484,31 +484,69 @@ export function archiveDoneInText(text, { keepDays = 3, from = today(), slugFor
   return { text: rebuilt.join('\n').replace(/\n+$/, '\n'), archived, skipped, count };
 }
 
-/** 归档页正文（按日期分组，原文保留）。供首次建页与同日追写复用。 */
+/** 归档页正文（按日期分组，原文保留）。供同日追写复用。 */
 export function renderArchiveBody(groups) {
   const out = [];
   for (const g of groups) out.push(`### ${g.date}`, '', ...g.lines, '');
   return out.join('\n').replace(/\n+$/, '\n');
 }
 
-/** 归档页全文（带 frontmatter）。**每天一个文件**，故只收一组。 */
-export function renderArchivePage({ group }) {
-  const { date, lines } = group;
-  const n = lines.filter((l) => /^\s*- \[x\]/.test(l)).length;
-  const head = [
-    '---',
-    'tags: [todo-archive, 历史]',
-    `updated: ${date}`,
-    'status: reviewed',
-    '---',
-    '',
-    `# Todo 归档 — ${date}`,
-    '',
-    `> 从 \`.brain/todo.md\` 的 Done 区迁出（该区只保留近期）。本页含 ${date} 的 ${n} 条已完成任务。`,
-    '> 原文完整保留（含 `↳ 断点/卡点`），查"某任务当时做到哪"看这里。',
-    '',
-  ];
-  return head.join('\n') + '\n' + renderArchiveBody([group]) + '\n';
+/** 归档区标题。归档内容全部落在这个二级标题下，**与 AI 手写的会话快照共存**：
+ *  同一天的记录（快照 + 任务明细）放一个文件里，而不是分两个文件。
+ *  写入侧只动这一段：标题之前的内容原样保留（已存在的人工内容一律不覆盖）。 */
+export const ARCHIVE_SECTION = '## 📦 任务归档';
+
+/** 把「任务归档」段合并进已有正文。**纯函数**（不碰磁盘）。
+ *
+ * 为何不再「每天一个文件」（2026-09-15 用户定）：
+ *   归档页与 `log-<日期>.md` 会话快照是**同一天的记录**，分两处查着要开两个文件。
+ *   改为：归档写进当天快照的 `ARCHIVE_SECTION` 段。
+ *
+ * 两个边界（都有测试钉住）：
+ *   ① 文件不存在 → 建一个**只有归档段**的页（那天可能没写快照，仍只落这一个文件）。
+ *   ② 文件已存在（含 AI 手写的快照）→ **只替换归档段**，段外内容逐字保留。
+ *      同日重复归档（罕见）则把新日期组接在段内已有内容之后，不重复建段。
+ *
+ * @param body   现有全文（null = 文件不存在）
+ * @param group  { date, lines, count }
+ */
+export function upsertArchiveSection(body, group) {
+  const chunk = renderArchiveBody([group]);
+  if (body == null) {
+    // ① 新文件：只有归档段（无手写快照也合法 —— 那天本来就只有任务记录）
+    const fm = [
+      '---',
+      'tags: [session-log, todo-archive, 历史]',
+      `updated: ${group.date}`,
+      'status: reviewed',
+      '---',
+      '',
+      `# ${group.date} 记录`,
+      '',
+      '> 本页 = 该日的会话快照（若有）+ 从 `todo.md` Done 区迁出的任务明细。',
+      '',
+      ARCHIVE_SECTION,
+      '',
+      chunk.trimEnd(),
+      '',
+    ];
+    return fm.join('\n');
+  }
+  // ② 已存在：只动归档段，段外原样
+  const lines = body.split('\n');
+  const i = lines.findIndex((l) => l.trim() === ARCHIVE_SECTION);
+  if (i === -1) {
+    // 有文件但还没归档段 → 追加到末尾（不搅动已有内容）
+    return `${body.replace(/\s*$/, '')}\n\n${ARCHIVE_SECTION}\n\n${chunk.trimEnd()}\n`;
+  }
+  // 找到本段结束（下一个同级或更高级标题）
+  let j = i + 1;
+  while (j < lines.length && !/^#{1,2} \S/.test(lines[j].trim())) j++;
+  const head = lines.slice(0, i + 1);
+  const tailPart = lines.slice(j);
+  const existingInner = lines.slice(i + 1, j).join('\n').trim();
+  const merged = existingInner ? `${existingInner}\n\n${chunk.trimEnd()}` : chunk.trimEnd();
+  return [...head, '', merged, '', ...tailPart].join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
 /** 幂等：把 todo 全文里平铺的旧 Done 区按日期分组（新日期在前，未标日期归尾）。