@fanchao8609/agent_brain_sync 1.3.1 → 1.4.0

package/README.md

@@ -72,6 +72,7 @@ abs log "完成 X"                          # 记一行流水；abs log 无参 =
 abs query <词>                            # 检索图谱（多词 OR）
 abs status                                # 当前项目 + 图谱概要
 abs lint                                  # 体检：死链/孤岛/超尺寸/堆积
+abs todo archive                          # 归档 Done 区旧日期组（默认留近 3 天）
 ```
 
 > `abs todo start` 与 `abs todo add` 等价（都登记任务）。

package/bin/abs.js

@@ -2,7 +2,7 @@
 // bin/abs.js — abs CLI 入口。
 // abs <cmd> [args]
 // 命令: init / board / status / load / task / install / uninstall / help
-import { cmdInit, cmdBoard, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdShow, cmdRepair, cmdWrapup, cmdTeardownCheck } from '../src/store.js';
+import { cmdInit, cmdBoard, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdShow, cmdRepair, cmdWrapup, cmdTeardownCheck, cmdTodoArchive } from '../src/store.js';
 import { runInstall, runUninstall, installSummary } from '../src/install.js';
 import { readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
@@ -70,6 +70,8 @@ function parseArgv(args) {
     else if (a === '--section') { o.section = args[++i]; }
     else if (a === '--note') { o.note = args[++i]; }
     else if (a === '--payload') { o.payload = args[++i]; }
+    else if (a === '--keep-days') { o.keepDays = args[++i]; }
+    else if (a === '--dry-run') { o.dryRun = true; }
     else if (a === '--yes') { o.yes = true; }
     else if (a === '--repair') { o.repair = true; }
     else if (a === '--no-mcp') { o.mcp = false; }
@@ -99,6 +101,9 @@ const usage = `abs — agent-brain-sync 记忆工具
 
 维护:
   abs query <词1> [词2 …]    检索 .brain/ 知识页 (多词 OR)
+  abs todo archive [--keep-days N] [--dry-run]
+                            归档 Done 区旧日期组 → sessions/<日期>-todo归档.md
+                            (默认保留近 3 天; 任一天有未完成则整天不归档)
   abs lint                   图谱体检 (死链/孤岛/超尺寸/堆积)
   abs init [--repair]        建 .brain/ 图谱; 结构不完整时报明细, --repair 只补缺不覆盖
   abs install [--agent <宿主>]   安装 MCP+hook+skill (宿主: claude-code/codex/opencode/pi)
@@ -181,10 +186,17 @@ async function main() {
           break;
         }
         const action = TODO_ACTIONS[sub];
+        // 归档：Done 区迁出旧日期组（非任务子命令，单独处理）
+        if (sub === 'archive') {
+          rejectExtra(rest2, 'abs todo archive [--keep-days N] [--dry-run]');
+          const a = { dir: opts.dir, keepDays: opts.keepDays, dryRun: opts.dryRun };
+          console.log(await cmdTodoArchive(a));
+          break;
+        }
         if (!action) {
           throw new Error(
             `✗ 未知子命令 "${sub}"\n` +
-            `  可用: add / start / note / blocked / done\n` +
+            `  可用: add / start / note / blocked / done / archive\n` +
             `  看板: abs todo（不带参数）\n` +
             `  登记任务: abs todo add <id> --note "做什么"`,
           );

package/package.json

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

package/skill/SKILL.md

@@ -115,6 +115,12 @@ monorepo 若多个子包各自独立交付，可各建一份 `.brain/`；横向
 | 碰壁/阻塞 | `abs todo blocked <id> --note "卡点原因"`（移 Blocked） |
 | 被打断/改向/干到一半停 | `abs todo note <id> --note "改到哪个文件/到哪步"`（补 ↳ 断点 行） |
 
+**Done 区会自动收口**：会话结束时 hook 调 `abs wrapup`，顺手把「超过 3 天 且 整天都已完成」
+的日期组迁到 `.brain/sessions/<日期>-todo归档.md`，并在 Done 区尾部留一行
+`### 归档` → `- [[<日期>-todo归档]] 完成任务 N 条`。
+**任一天只要还有未完成任务（`- [ ]`），整天都不归档** —— 不会把半成品扫走。
+手动跑：`abs todo archive [--keep-days N] [--dry-run]`。
+
 > `abs todo start` 与 `abs todo add` 等价（老写法仍可用）。
 > 旧版 `abs task ...` / `abs board` 已改名，会报错并提示新写法。
 > 只读命令（`todo`/`status`/`lint`/`load`/`index`）遇多余参数会报错 —— 不再静默吞掉。

package/src/install.js

@@ -6,6 +6,7 @@
 //   - OpenCode / Pi: 官方只吃 TS plugin/extension(无 shell-hook 配置) → 初版给出手工指引。
 // 纪律: 幂等(重复安装=更新)、原子写(tmp+rename)、卸载只删自己装的、写入前备份。
 import { promises as fs } from 'node:fs';
+import * as fsSync from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,6 +16,31 @@ const ABS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const HOOK_TEMPLATE = join(ABS_DIR, 'hooks', 'event.sh');
 const SKILL_SOURCE = join(ABS_DIR, 'skill', 'SKILL.md');
 
+/**
+ * 写进宿主 MCP 配置的 mcp.js 路径。
+ * 坑: 直接用 ABS_DIR 是不稳定的 —— ABS_DIR = "install.js 自己住哪", 从仓库跑
+ * `abs install` 就把仓库路径写进宿主配置。之后若卸载/移动全局包, 该路径直接失效;
+ * 而 Co​dex 分支又"已存在即跳过", 一旦写错永不修正。
+ * 现在优先解析本包的稳定安装位置（全局 node_modules），解析不到才回退 ABS_DIR。
+ */
+function mcpEntryPath() {
+  // 本包名（package.json），用于反查全局安装位置
+  let pkgName = '@fanchao8609/agent_brain_sync';
+  try {
+    pkgName = JSON.parse(fsSync.readFileSync(join(ABS_DIR, 'package.json'), 'utf8')).name || pkgName;
+  } catch { /* 保持默认 */ }
+  const candidates = [
+    // npm 全局根（最常见）
+    join(dirname(process.execPath), '..', 'lib', 'node_modules', pkgName, 'bin', 'mcp.js'),
+    join(process.env.npm_config_prefix || '', 'lib', 'node_modules', pkgName, 'bin', 'mcp.js'),
+  ];
+  for (const c of candidates) {
+    try { if (fsSync.existsSync(c)) return c; } catch { /* 试下一个 */ }
+  }
+  // 回退：仓库/本地安装形态
+  return join(ABS_DIR, 'bin', 'mcp.js');
+}
+
 const MARK = '// abs-managed (agent-brain-sync)'; // TS plugin 标记
 const JSON_MARK_KEY = 'abs-managed';             // JSON 内我们的命名空间
 
@@ -103,7 +129,7 @@ async function installClaudeCode({ withMcp, withSkill, log }) {
     settings.mcpServers = settings.mcpServers || {};
     settings.mcpServers['abs'] = {
       command: process.execPath,
-      args: [join(ABS_DIR, 'bin', 'mcp.js')],
+      args: [mcpEntryPath()],
     };
     await atomicWrite(settingsP, JSON.stringify(settings, null, 2));
     steps.push(`✓ MCP    → settings.json mcpServers.abs (stdio)`);
@@ -183,12 +209,21 @@ async function installCodex({ withMcp, withSkill, log }) {
     let text = '';
     try { text = await fs.readFile(mcpP, 'utf8'); } catch {}
     if (!text.includes('[mcp_servers.abs]')) {
-      const block = `\n[mcp_servers.abs]\ncommand = "${process.execPath}"\nargs = ["${join(ABS_DIR, 'bin', 'mcp.js')}"]\n`;
+      const block = `\n[mcp_servers.abs]\ncommand = "${process.execPath}"\nargs = ["${mcpEntryPath()}"]\n`;
       await backup(mcpP);
       await atomicWrite(mcpP, text.replace(/\s*$/, '') + '\n' + block);
       steps.push(`✓ MCP    → ${mcpP} [mcp_servers.abs]`);
     } else {
-      steps.push(`• MCP    → ${mcpP} 已存在, 跳过`);
+      // 已存在也要校对路径: 旧版可能写入了仓库路径(不稳定) 或全局包已迁移。
+      const want = mcpEntryPath();
+      const re = /(\[mcp_servers\.abs\][^\[]*?args\s*=\s*\[)"[^"]*"(\])/s;
+      if (re.test(text) && !text.includes(`"${want}"`)) {
+        await backup(mcpP);
+        await atomicWrite(mcpP, text.replace(re, `$1"${want}"$2`));
+        steps.push(`✓ MCP    → ${mcpP} 路径已校正 → ${want}`);
+      } else {
+        steps.push(`• MCP    → ${mcpP} 已存在且路径正确, 跳过`);
+      }
     }
   }
   if (withSkill) {
@@ -526,7 +561,7 @@ async function installOpenCode({ withMcp, withSkill, log }) {
     cfg.mcp = cfg.mcp || {};
     cfg.mcp['abs'] = {
       type: 'local',
-      command: [process.execPath, join(ABS_DIR, 'bin', 'mcp.js')],
+      command: [process.execPath, mcpEntryPath()],
     };
     await backup(mcpP);
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));

package/src/store.js

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { requireBrain, findBrainRoot, brainPath } from './index.js';
-import { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped, idOfTaskLine } from './todo.js';
+import { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped, idOfTaskLine, archiveDoneInText, renderArchivePage, renderArchiveBody } from './todo.js';
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor, wrapupLogPath } from './wrapup.js';
 
@@ -190,7 +190,82 @@ export async function cmdLoad({ dir }) {
 // ---------- wrapup: 滞留快照（B）/ load 内展示由 cmdLoad 完成（A） ----------
 export async function cmdWrapup({ dir }) {
   const root = await requireBrain(dir || process.cwd());
-  return appendWrapup(root);
+  const snap = await appendWrapup(root);
+  // 顺手做 Done 归档。**不引入 cron/定时器**：Stop hook 已经会在会话结束时调
+  // `abs wrapup`，直接复用这个触发点（零新基础设施、零新失败面）。
+  // 只对「超过保留天数 且 整天都已完成」的日期组动手，平时无动作。
+  // 本函数 stdout 会被 hook 追写到 ~/.abs/log/hooks.log → 归档动作自动留痕。
+  let arch = '';
+  try {
+    const a = await cmdTodoArchive({ dir: root, keepDays: 3 });
+    if (a.startsWith('✓')) arch = '\n' + a;
+  } catch { /* 归档失败不影响快照本身 */ }
+  return snap + arch;
+}
+
+/**
+ * `abs todo archive` —— 把 Done 区里「超过保留天数 且 整天都已完成」的日期组迁到归档页。
+ * 规则见 `archiveDoneInText`（① 只留近 N 天 ② 任一天有未完成则整天不归档 ③ 归档成一个文件
+ * 并在 Done 区尾部 `### 归档` 记 `- [[slug]] 完成任务 N 条`）。
+ * 幂等：同日重跑 = 追写到同一归档页 + 就地更新标记行。
+ */
+export async function cmdTodoArchive({ dir, keepDays = 3, dryRun = false } = {}) {
+  let root;
+  try { root = await requireBrain(dir || process.cwd()); } catch { return '未找到 .brain/ 图谱。先在项目根运行: abs init'; }
+  const days = Math.max(1, Number(keepDays) || 3);
+  const todoP = brainPath(root, 'todo.md');
+  const raw = await fs.readFile(todoP, 'utf8').catch(() => '');
+  if (!raw.trim()) return '（todo.md 为空）';
+
+  const plan = archiveDoneInText(raw, { keepDays: days, from: today() });
+  const why = plan.skipped.length
+    ? `\n  跳过: ${plan.skipped.map((s) => `${s.date}（${s.reason}）`).join('；')}`
+    : '';
+  if (!plan.archived.length) return `（无可归档：保留近 ${days} 天）${why}`;
+  const brief = plan.archived.map((g) => `${g.date}(${g.count})`).join(' ');
+  if (dryRun) {
+    return `[dry-run] 将归档 ${plan.archived.length} 天 / ${plan.count} 条（每天一个文件）\n  ${brief}${why}`;
+  }
+
+  // 1) 归档页：**每天一个文件**，文件名用被归档那天的日期（便于按天回溯）。
+  //    同一天再次归档（罕见：该日组已被移走，除非有人重新补当天任务）则追写正文。
+  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 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);
+  }
+
+  // 2) todo.md：锁内重算（拿最新内容，避免与并发 done 互相覆盖）
+  await editFile(todoP, (cur) => {
+    const p2 = archiveDoneInText(cur ?? '', { keepDays: days, from: today() });
+    return p2.archived.length ? { text: p2.text } : SKIP;
+  });
+
+  // 3) index 登记（每个日期页一行，幂等）
+  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');
+    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 next = after === -1
+      ? `${index.replace(/\s*$/, '')}\n${add}\n`
+      : index.slice(0, after) + `\n${add}` + index.slice(after);
+    return { text: next };
+  });
+
+  const files = plan.archived.map((g) => `sessions/${g.slug}.md`).join('\n  ');
+  return `✓ 已归档 ${plan.archived.length} 天 / ${plan.count} 条\n  ${brief}\n  → ${files}${why}`;
 }
 
 /**
@@ -502,8 +577,10 @@ export async function cmdLint({ dir }) {
       if (/slug|Name|name|Date|页面名$/.test(ln)) issues.push(`TEMPLATE-LINK: ${pg.rel} -> [[${ln}]]`);
       if (!names.has(ln)) issues.push(`DEAD-LINK: ${pg.rel} -> [[${ln}]]`);
     }
-    // ORPHAN: sources/ 暂存页豁免（暂存线索天然孤立，提炼成 concept 前不强制挂链）
-    if (pg.dir !== 'sources' && !pg.links.length && !linkedNames.has(pg.slug)) {
+    // ORPHAN: sources/ 暂存页与 todo 归档页豁免。前者是暂存线索（提炼成 concept 前天然孤立），
+    // 后者是历史数据倾倒（已登记在 index.md，就是图谱入口，无需再制造双链）。
+    const isTerminal = pg.dir === 'sources' || /todo归档$/.test(pg.slug);
+    if (!isTerminal && !pg.links.length && !linkedNames.has(pg.slug)) {
       issues.push(`ORPHAN-PAGE: ${pg.rel} (no links out, no links in)`);
     }
     if (/知识冲突/.test(pg.body) && /status: draft/.test(pg.frontmatter)) {
@@ -529,6 +606,22 @@ export async function cmdLint({ dir }) {
   const nsrc = pages.filter((p) => p.dir === 'sources').length;
   if (nsrc > 10) issues.push(`SOURCES-PILED-UP: sources/ has ${nsrc} files > 10; 提炼归档旧 source`);
 
+  // Done 区堆积：它无上限增长，且 `abs todo`/`abs load` 每次全量打印 → 越积越难用。
+  // （与 hooks.log/wrapup.log 同类问题；那两处有轮转，这里靠 `abs todo archive`。）
+  // 坑: 曾经写成 brainPath(vault, 'todo.md')，而 vault 已经是 .brain 目录
+  // → 拼出 .brain/.brain/todo.md（ENOENT），又被外层 try/catch 吞掉
+  // → 检查静默失效（lint 永远 0 problem）。故这里不用 try/catch 吞错，
+  // 只对 ENOENT 做缺省，写错路径这类编程错会直接暴露。
+  const todoTxt = await fs.readFile(join(vault, 'todo.md'), 'utf8').catch(() => '');
+  const di = todoTxt.split('\n').findIndex((l) => l.startsWith('## Done'));
+  if (di !== -1) {
+    const doneLines = todoTxt.split('\n').slice(di + 1).filter((l) => l.trim()).length;
+    const DONE_MAX = 60;
+    if (doneLines > DONE_MAX) {
+      issues.push(`DONE-PILED-UP: Done 区 ${doneLines} 行 > ${DONE_MAX}; 跑 \`abs todo archive\` 迁出旧日期组`);
+    }
+  }
+
   const n = issues.length;
   return [
     ...(issues.length ? issues : []),

package/src/todo.js

@@ -138,6 +138,153 @@ function renderDoneGroups(units) {
   return out;
 }
 
+/** 归档标记区标题。它在 Done 区内部、日期分组之后，形如：
+ *   ### 归档
+ *   - [[2026-09-10-todo归档]] 完成任务 10 条
+ * 这区不是任务行，不能被 parseDoneUnits 吃挂，否则 markDone 重建 Done 时会把它丢掉。
+ * 故先切出去当"不透明区域"原样保留。 */
+const ARCHIVE_HEADING = '### 归档';
+
+/** 把 Done 主体行切成 { groupLines, archiveLines }：把 `### 归档` 区当"不透明块"原样保留。
+ * 注意不能简单"从标题切到文件尾" —— 否则一旦有日期组落在归档区之后（手改/旧数据），
+ * 它会被当不透明内容除在分组之外，永远不参与归档。故只取到下一个 ###/## 标题为止。 */
+function splitDoneBody(bodyLines) {
+  const ai = bodyLines.findIndex((l) => l.trim() === ARCHIVE_HEADING);
+  if (ai === -1) return { groupLines: bodyLines, archiveLines: [] };
+  let end = ai + 1;
+  while (end < bodyLines.length && !/^#{2,3} \S/.test(bodyLines[end].trim())) end++;
+  return {
+    groupLines: [...bodyLines.slice(0, ai), ...bodyLines.slice(end)],
+    archiveLines: bodyLines.slice(ai, end),
+  };
+}
+
+/** 合并归档标记行：**每天一行** `- [[<日期>-todo归档]] 完成任务 N 条`。
+ * 计数按 slug **累计**（同一天分两批归档时叠加，否则标记行与归档页实际内容不符）；
+ * 已存在的其他天的标记行原样保留。返回含标题的行数组。 */
+function mergeArchiveLines(existing, entries) {
+  const out = existing.length ? [...existing] : [ARCHIVE_HEADING];
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  for (const { slug, count } of entries) {
+    const i = out.findIndex((l) => l.includes(`[[${slug}]]`));
+    const prev = i !== -1 ? Number((out[i].match(/完成任务 (\d+) 条/) || [])[1] || 0) : 0;
+    const line = `- [[${slug}]] 完成任务 ${prev + count} 条`;
+    if (i !== -1) out[i] = line;
+    else out.push(line);
+  }
+  out.push('');
+  // 标记行按日期倒序（与 Done 日期组同风格：新的在上）。
+  // 否则顺序 = 归档先后，多次归档后读起来是乱的（如 08/09/07）。
+  const dateOf = (l) => (String(l).match(/(\d{4}-\d{2}-\d{2})/) || [''])[0];
+  const body = out.slice(1).filter((l) => l.trim());
+  body.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
+  return [out[0], ...body, ''];
+}
+
+/** 本地日期减 n 天（YYYY-MM-DD）。纯字符串入出，避免时区漂移。 */
+function daysAgo(n, from) {
+  const [y, m, d] = String(from).split('-').map(Number);
+  const t = new Date(y, m - 1, d);
+  t.setDate(t.getDate() - n);
+  const pad = (x) => String(x).padStart(2, '0');
+  return `${t.getFullYear()}-${pad(t.getMonth() + 1)}-${pad(t.getDate())}`;
+}
+
+/** 一行是否为未完成任务行（- [ ]）。 */
+function isUndoneLine(l) {
+  return /^\s*- \[ \]/.test(l);
+}
+
+/**
+ * 把 Done 区里"可归档"的日期组摘出来，并追回归档标记行。**纯函数**（不碰磁盘）。
+ * 规则（用户定）：
+ *   ① 只保留近 keepDays 天（含今天）；更早的才归档。
+ *   ② 某一天只要还有未完成（- [ ]）任务，**整天都不归档**（不拆半天）。
+ *   ③ 每**天**归一个文件，slug 为 `<日期>-todo归档`（由 slugFor 给），本函数只负责
+ *      从 todo 文本里移除 + 在 Done 区尾部的 `### 归档` 区**每天记一行**
+ *      `- [[<日期>-todo归档]] 完成任务 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归档` } = {}) {
+  const lines = String(text || '').split('\n');
+  const di = lines.findIndex((l) => l.startsWith('## Done'));
+  if (di === -1) return { text, archived: [], skipped: [], count: 0 };
+  const head = lines.slice(0, di + 1);
+  const { groupLines, archiveLines } = splitDoneBody(lines.slice(di + 1));
+  const units = parseDoneUnits(groupLines);
+  if (!units.length) return { text, archived: [], skipped: [], count: 0 };
+
+  const keep = Math.max(1, Number(keepDays) || 3);
+  // 保留 cutoff..from 这 keep 天；比 cutoff 更早的才归档
+  const cutoff = daysAgo(keep - 1, from);
+
+  const byDate = new Map();
+  const undated = [];
+  for (const u of units) {
+    if (!u.date) { undated.push(u); continue; }
+    if (!byDate.has(u.date)) byDate.set(u.date, []);
+    byDate.get(u.date).push(u);
+  }
+
+  const archived = [];
+  const skipped = [];
+  const keepUnits = [...undated];
+  if (undated.length) skipped.push({ date: '(未标日期)', reason: '无完成日期，无法判断天数（保守不归档）' });
+
+  for (const date of [...byDate.keys()].sort()) {
+    const us = byDate.get(date);
+    if (date >= cutoff) { keepUnits.push(...us); continue; }        // ① 近 N 天：保留
+    const undone = us.filter((u) => isUndoneLine(u.lines[0]));
+    if (undone.length) {                                            // ② 有未完成：整天不归档
+      skipped.push({ date, reason: `有 ${undone.length} 条未完成，整天不归档` });
+      keepUnits.push(...us);
+      continue;
+    }
+    const gLines = us.flatMap((u) => u.lines);                       // ③ 可归档
+    archived.push({
+      date,
+      lines: gLines,
+      slug: slugFor(date),
+      count: gLines.filter((l) => /^\s*- \[x\]/.test(l)).length,
+    });
+  }
+
+  if (!archived.length) return { text, archived: [], skipped, count: 0 };
+
+  const count = archived.reduce((n, g) => n + g.count, 0);
+  const entries = archived.map((g) => ({ slug: g.slug, count: g.count }));
+  const rebuilt = [...head, ...renderDoneGroups(keepUnits), ...mergeArchiveLines(archiveLines, entries)];
+  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';
+}
+
 /** 幂等：把 todo 全文里平铺的旧 Done 区按日期分组（新日期在前，未标日期归尾）。
  * 已是分组态(### date)则原样返回——惰性迁移用，避免每次读都动文件。 */
 export function groupDoneSection(text) {
@@ -147,9 +294,11 @@ export function groupDoneSection(text) {
   const body = lines.slice(di + 1);
   const first = body.find((l) => l.trim());
   if (first && /^### /.test(first.trim())) return text; // 已分组，幂等不动
-  const units = parseDoneUnits(body);
+  const { groupLines, archiveLines } = splitDoneBody(body); // 归档标记区原样保留
+  const units = parseDoneUnits(groupLines);
   if (!units.length) return text;
-  return [...lines.slice(0, di + 1), ...renderDoneGroups(units)].join('\n').replace(/\n+$/, '\n');
+  return [...lines.slice(0, di + 1), ...renderDoneGroups(units), ...archiveLines]
+    .join('\n').replace(/\n+$/, '\n');
 }
 
 /** 把 moved 单元（已完成任务行+附属行）放入 Done 区并整体按日期分组重建。
@@ -165,9 +314,10 @@ export function insertDoneGrouped(text, movedLines) {
   }
   const head = lines.slice(0, di + 1);
   const body = lines.slice(di + 1);
+  const { groupLines, archiveLines } = splitDoneBody(body); // 归档标记区原样保留
   // 新完成单元置前：同日期组内新在最上（renderDoneGroups 按 encounter 顺序保持，日期再倒序排）
-  const units = [newUnit, ...parseDoneUnits(body)];
-  return [...head, ...renderDoneGroups(units)].join('\n').replace(/\n+$/, '\n');
+  const units = [newUnit, ...parseDoneUnits(groupLines)];
+  return [...head, ...renderDoneGroups(units), ...archiveLines].join('\n').replace(/\n+$/, '\n');
 }
 
 // 占位/空任务行（老模板的 "（无）"/"无"/纯 - [ ]）不迁移