skill-memo-ilife 0.2.0 → 0.2.1

package/SKILL.md

@@ -35,11 +35,12 @@ memo-cmd-read memo.help.lookup                      # 说「备忘录 HELP」（
 | 看备忘 | memo.detail | detail | `memo-cmd-read memo.detail --params '{"id":"<id>"}'` |
 | 看提醒 | memo.remind | list | `memo-cmd-read memo.remind` |
 | 查提醒 | memo.remind | list | `memo-cmd-read memo.remind` |
-| 设提醒 | memo.create | receipt | `memo-cmd-read memo.create --params '{"remindAt":"2026-10-01"}'` |
-| 记提醒 | memo.create | receipt | `memo-cmd-read memo.create --params '{"remindAt":"2026-10-01"}'` |
+| 设提醒 | memo.create | receipt | `memo-cmd-read memo.create --params '{"remindAt":"2026-10-01 09:00"}'` |
+| 记提醒 | memo.create | receipt | `memo-cmd-read memo.create --params '{"remindAt":"2026-10-01 09:00"}'` |
 | 废弃提醒 | memo.remove | receipt | `memo-cmd-read memo.remove --params '{"mode":"abandon"}'` |
 | 完成心愿 | memo.update | receipt | `memo-cmd-read memo.update --params '{"done":true}'` |
 | 心愿排期 | memo.wish | list | `memo-cmd-read memo.wish` |
+| 飞书授权 | memo.auth | receipt | `memo-cmd-read memo.auth` |
 | 记一条 | memo.create | receipt | `memo-cmd-read memo.create` |
 | 添加笔记 | memo.create | receipt | `memo-cmd-read memo.create` |
 | 记心愿 | memo.create | receipt | `memo-cmd-read memo.create --params '{"category":"心愿"}'` |
@@ -55,21 +56,22 @@ memo-cmd-read memo.help.lookup                      # 说「备忘录 HELP」（
 | 删打卡 | memo.update | receipt | `memo-cmd-read memo.update --params '{"category":"打卡","id":"<id>"}'` |
 | 删情绪日记 | memo.update | receipt | `memo-cmd-read memo.update --params '{"category":"情绪日记","id":"<id>"}'` |
 
-相关场景：memo.batch、memo.create、memo.detail、memo.help.lookup、memo.remind、memo.remove、memo.search、memo.stats、memo.sync、memo.update、memo.wish（11 联动，key 字符串 P8 落表时冻结）。
+相关场景：memo.auth、memo.batch、memo.create、memo.detail、memo.help.lookup、memo.remind、memo.remove、memo.search、memo.stats、memo.sync、memo.update、memo.wish（12 联动，key 字符串 P8 落表时冻结）。
 <!-- HELP-AUTO-END -->
 
 ## HELP 交付（说「备忘录 HELP」走这里，不分大小写）
 
-- **缺省就是交付物**：`memo-cmd-read memo.help.lookup` **原样调用**即落一份能打开的 HELP 文件——`<SKILLS_DB_PATH>/memo_html/备忘录_HELP_<YYYYMMDD_HHMMSS>.html`（扁平落 `memo_html/`，不加 `help/` 一层；8 域／13 二级组／30 场景，走仓内通用 help 模板）。stdout 的 `delivery.path` 是**绝对路径**、`delivery.bytes` 是文件字节数；回话就把这个路径给用户（回执即真相）。同一秒撞名自动递补 `_2`（再撞给 `_3`）。
+- **缺省就是交付物**：`memo-cmd-read memo.help.lookup` **原样调用**即落一份能打开的 HELP 文件——`<库目录>/<产物目录>/备忘录_HELP_<YYYYMMDD_HHMMSS>.html`（`<库目录>`＝配置文件 `~/.ilife/memo.yaml` 的 `db.dir`，空串＝数据目录 `~/.ilife/data/`；`<产物目录>`＝同文件的 `html.dir`，默认 `memo_html`，**扁平一段、不加 `help/` 一层**；8 域／13 二级组／30 场景，走仓内通用 help 模板）。stdout 的 `delivery.path` 是**绝对路径**、`delivery.bytes` 是文件字节数；回话就把这个路径给用户（回执即真相）。
   **完成标准**：`delivery.path` 指的那个文件真的存在、大小＝`delivery.bytes`、退出码 0——三条都核过才算交付，核不过就照实说失败。
-- **要速查表才加参数**：`--params '{"mode":"lookup"}'` 落同目录 `备忘录_速查表_<YYYYMMDD_HHMMSS>.html`（28 条唤醒词一行一条：唤醒词／命令／形状／调用形／一句话）。与 HELP 文件**分名**，两份产物不撞车。
+- **反复读不再涨目录（#245）**：同一主体**一天内只留一份**——24 小时内再读就**复用已有那份**（不新建、不改写；回执给的就是它）。要别的窗口给 `--params '{"reuseHours":3}'`（小时）；要**每次都要一份最新的**给 `{"reuseHours":0}`。窗口内若已有一份、而你刚改过 HELP 内容，那份旧产物**不会被自动刷新**（窗口语义如此）——真要新的就带 `reuseHours:0`。
+- **要速查表才加参数**：`--params '{"mode":"lookup"}'` 落同目录 `备忘录_速查表_<YYYYMMDD_HHMMSS>.html`（28 条唤醒词一行一条：唤醒词／命令／形状／调用形／一句话）。与 HELP 文件**分名**，两份产物不撞车；这一支同样吃上面的复用窗口。
 - **要现找才加参数**：`--params '{"q":"帮我搜备忘"}'` 只回命中条目（JSON），**不落盘**；要落盘再给 `--html`。`q` 与 `mode` 互斥，`mode` 只认 `lookup`，违反即退出码 2。
 - **`--html <路径>`＝显式落点**：逐字用你给的路径、缺父目录自动建、**覆盖写**（不参与同一秒 `_N` 递补）。给 `--html` 时缺省那支落整页 HELP，`q`／`mode:"lookup"` 那两支落该次的分节页。
-- **边界**：看 HELP **不开库、不建库**——跑完 `<SKILLS_DB_PATH>/memo` 仍不存在；这条命令只交页面与索引，不读也不写笔记内容。
+- **边界**：看 HELP **不开库、不建库**——跑完数据目录里仍没有 `memo.db`；这条命令只交页面与索引，不读也不写笔记内容。
 - **与上一节的关系**：正文「联动速查」块是**构建期注入的索引**（`scripts/build-help.mjs` 从唤醒词表注入 SKILL.md，勿手改），给 AI 按唤醒词找命令；**HELP 文件是缺省交付物**，给用户打开看。两者同源（同一张唤醒词表）、不是一份东西；显式 `mode:"lookup"` 落的那份是索引的页面版（`备忘录_速查表`），也不是 HELP 文件。
 - **入口只认一条**：「备忘录 HELP」（不分大小写，用户 2026-09-12 裁定）；其余唤醒词是场景别名，住上一节索引块，不另立 HELP 入口。
 
 ## 环境与出 scope
 
-- SKILLS_DB_PATH（必设）+ lark-cli（同步须四门全绿），见 docs/env.md。
+- 路径类取值一律读配置文件 `~/.ilife/memo.yaml`（**配置文件是唯一真相，环境变量不参与配置**）：库目录＝`db.dir`（空串＝数据目录 `~/.ilife/data/`，首次读时自动建）、库文件名＝`db.name`（默认 `memo.db`）、产物目录＝`html.dir`（默认 `memo_html`）、附件目录＝`media.dir`（默认 `media`）、飞书 CLI 路径＝`lark.cliPath`（**空串＝没有显式值，走本机自动探测**）、飞书扫码目录＝`lark.qrDir`（空串＝系统临时目录下的 `memo_feishu_qr`）、HELP 与速查表的主体名＝`files.help`／`files.lookup`；`ILIFE_CONFIG_DIR` 设定且非空即整体接管配置目录。飞书同步另须 lark-cli 四门全绿。取值面与环境项见 docs/env.md。
 - 出 scope：定时任务、面板、本技能外联动；Python 老家只读对照。

package/dist/cli/cmd_read.js

@@ -3,14 +3,22 @@
 // 退出码对齐 skilllink 冻结：0 ok；1 预检；2 用法/参数；3 key；4 取数/超时；5 envelope/渲染/落盘。
 // stdout 纯净：成功只打 envelope JSON 一行。
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { openMemoDb, listNotes, getNote, searchNotes, addNote, updateNote, removeNote, larkReady, MemoFetchError } from '../fetch/index.js';
-import { normalizeTop, normalizeSub, normalizeRemindAt, crudCreate, crudUpdate, crudRemove } from '../policy/index.js';
-import { memoShapeFor, buildMemoEnvelope, renderEnvelopeHtml, assertHtmlSize, MemoRenderError } from '../render/index.js';
+import { basename, dirname, join, resolve } from 'node:path';
+import { saveHtmlFile, helpReuseWindowOf } from 'base-paint/save-html';
+import { openMemoDb, closeMemoDb, listNotes, getNote, searchNotes, abandonReminder, checkDueReminders, listCompletedReminders, listReminderRows, countReminderRowsOfNote, collectBatchItems, countNotesByCategory, applyBatchCategory, authInit, authQr, authPoll, authStatus, runSentinel, MemoFetchError, } from '../fetch/index.js';
+import { normalizeTop, normalizeSub, needId, normalizeMediaPath, crudCreate, crudUpdate, crudRemove } from '../policy/index.js';
+// #661：心愿类的对外面——记／改／删／批量排期四条写命令与反向对账都经这一个门（`src/wish/index.ts`）。
+// #665：完成心愿走原子转换（`completeWish`，老 `complete-wish`）；排期／完成向导收集走 `wizards`。
+import { dueForCategory, dueMatches, ensureWish, updateWish, removeWish, setWishDue, reconcileWishes, completeWish, planWizard, completeWizard } from '../wish/index.js';
+import { memoShapeFor, buildMemoEnvelope, renderEnvelopeHtml, assertHtmlSize, fillMemoPage, pageEnvelope, wishPlanSnapshot, wishCompleteSnapshot, changeCategorySnapshot, syncSnapshot, MemoRenderError } from '../render/index.js';
 import { buildMemoHelpFileData, renderMemoHelpHtml } from '../help/helpFile.js';
 import { buildHelpSceneIndex } from '../help/sceneData.js';
 import { buildHelpLookup } from '../help/index.js';
-import { HELP_FILE_STEM, LOOKUP_FILE_STEM, resolveStemTarget, deliverMemoHtml } from '../help/memoOutput.js';
+import { helpHtmlDirName, helpFileStem, lookupFileStem } from '../help/manifest.js';
+import { resolveDbDir, dbFilename } from '../fetch/paths.js';
+import { isConfigKey, runConfigKey } from './config.js';
+// #706 · 配置体检：设置页专用的一条只读命令，同走「进分派层之前拦下」这条口（判据住 src/health.ts）。
+import { isHealthCheckKey, runHealthCheckKey } from './health.js';
 import { MemoPolicyError } from '../fetch/errors.js';
 const DEFAULT_TIMEOUT_MS = 30000;
 function fail(code, msg) { console.error('ERR ' + code + ': ' + msg); process.exit(code); }
@@ -19,10 +27,6 @@ function preflight() {
     const v = process.versions.node.split('.').map(Number);
     if (!(v[0] > 22 || (v[0] === 22 && v[1] >= 13)))
         fail(1, 'node 低于 22.13：' + process.versions.node);
-    const p = process.env.SKILLS_DB_PATH;
-    if (!p)
-        fail(1, 'SKILLS_DB_PATH 未设置（无默认值，必设）');
-    return p;
 }
 function needStr(params, name) {
     const v = params[name];
@@ -36,15 +40,59 @@ function needStr(params, name) {
 // （扁平、不加 `help/` 层：裁决 1），独占落盘 ＋ **绝对路径**回执（`delivery` 顶层追加，序在既有五字段之后）。
 // 显式 `mode:"lookup"` ＝ 速查表分名文件（主体 `备忘录_速查表`，裁决 2：一个键两种产物就分两个名字）。
 // 显式 `q` ＝ 现找：只回命中（stdout），给 `--html <路径>` 才落盘（检索式问答不刷目录）。
+// 显式 `reuseHours`（小时）＝ 复用窗口：`0`＝每次都落新的；不给＝**一天**（#245）——24 小时内反复读
+// 同一份 HELP 产物只留一份、不再新建（判据＝落盘名里的时间戳，不看 mtime）。两种 HELP 产物都吃窗口。
 // 全程**不开库**：初始化判据＝「**memo 库目录存在**」（票 6 V4：新库是目录 `<SKILLS_DB_PATH>/memo`，
 // 不是老家的 `memo.db` 文件——本机实测 0 字节空壳 `memo.db` 在、真目录不在，老家口径当场判错），
 // 且**只 stat、绝不建库**：免得「看帮助」把库目录 `mkdir` 出来。
+//
+// #240（欠债清偿）：命名与落盘**不再自持**——时间戳、同秒 `_N` 递补、独占创建、写后回读字节数全在
+// 共用件 `saveHtmlFile`（`base-paint/save-html`，唯一定义地 `packages/base-render/src/output/saveHtml.ts`）。
+// 本文件只出**落点意图**（`{dir, stem}`，主体与目录名取自 `../help/manifest.js` 的三个值），
+// 原先包内那份第 4 份同逻辑实现 `src/help/memoOutput.ts` 已删（裁决 3 挂的债，见 `#240`）。
 const HELP_MODE_FILE = 'file';
-/** 初始化状态：memo 库**目录**存在＝已初始化（票 6 V4）。只 `stat`、不建目录；
- *  判定本身异常 ⇒ `false`＝横幅照显（fail-open：误显只多一条提示，误藏会让新用户找不到入口）。 */
+/** HELP 支的复用窗口（毫秒）。#245：缺省**一天**（共用件 `HELP_REUSE_DEFAULT_HOURS`）——24 小时内反复读
+ *  同一份 HELP 产物只留一份、不再新建；`--params` 的 `reuseHours` 可改（`0`＝每次都落新的）。
+ *  换算与校验都在共用件，坏参抛 `RangeError` ⇒ 用 `helpReuseWindowOf` 翻成出口的「参数错」那一档
+ *  （exit 2），与其余四家同档：坏参绝不静默当 0。 */
+const helpReuseWindow = helpReuseWindowOf((m) => fail(2, m));
+/** 缺省交付的落点意图：`<库目录>/<memo_html>/〈主体〉`（目录名与主体是备忘录自己的三个值，
+ *  #695 起从配置文件取：`html.dir`／`files.help`／`files.lookup`，默认逐字等于老常量）。 */
+function landingOf(dbPath, stem) {
+    return { dir: join(resolve(dbPath), helpHtmlDirName()), stem };
+}
+/** 交付一次 HELP 产物（本包**唯一落盘点**）：
+ *  - `explicit`（`--html <路径>`，用户逐字指定）→ **覆盖写**（共用件 `file` ＋ `onExists:'overwrite'`：逐字落点、
+ *    不带时间戳、不递补），与该参数的既有口径一致；**不吃复用窗口**（逐字落点＝说哪落哪）；
+ *  - `landing`（本次产物按通式算出的落点意图）→ **独占创建 ＋ 同秒递补**（共用件缺省 `succession` ＋ `stem`）；
+ *    带 `window`（#245）时改为**窗口内复用**（共用件 `{reuse:{byAge}}`）：已有那份不超龄就返回它、不新建；
+ *  - 两者都给时 `explicit` 优先（用户指定胜过默认落点）。
+ *  命名、独占、回执全在共用件里；本函数只表态「这次落哪个」。写不进去**不静默降级**：共用件的
+ *  `code`（`EEXIST`／`EINVAL`／`EIO`／`ENOTDIR`…）原样穿过，由 main 归到 exit 5（目的地是「明确拿到文件」）。
+ *
+ *  ⚠️ **缺省支那句不许传 `onExists`**：共用件的缺省是 `'succession'`（通式名 ＋ 同秒 `_N` 递补）。
+ *  一旦显式传成 `'overwrite'`，产物就退化成固定名 `备忘录_HELP.html`、同秒连跑互相覆盖——
+ *  `#230` 的 ①③④ 会当场红（本票已用这一步做过变异自证）。 */
+function deliverMemoHtml(input) {
+    if (input.explicit !== undefined && input.explicit.length > 0) {
+        const abs = resolve(input.explicit);
+        return saveHtmlFile({ dir: dirname(abs), file: basename(abs), html: input.html, onExists: 'overwrite' });
+    }
+    if (input.landing === undefined) {
+        throw new Error('[skill-memo-ilife] deliverMemoHtml 缺落点（`explicit` 与 `landing` 至少给一个）');
+    }
+    return saveHtmlFile({
+        dir: input.landing.dir,
+        stem: input.landing.stem,
+        html: input.html,
+        ...(input.window === undefined ? {} : { onExists: { reuse: { byAge: input.window } } }),
+    });
+}
+/** 初始化状态：memo 老库文件存在＝已初始化（老 `_help_initialized`，新仓直连老库）。只 `stat`、
+ *  不建文件；判定本身异常 ⇒ `false`＝横幅照显（fail-open：误显只多一条提示，误藏会让新用户找不到入口）。 */
 function helpInitialized(dbPath) {
     try {
-        return existsSync(join(dbPath, 'memo'));
+        return existsSync(join(dbPath, dbFilename()));
     }
     catch {
         return false;
@@ -69,6 +117,9 @@ function dispatchHelp(params, dbPath) {
         fail(2, '参数 q 与 mode 互斥：q＝现找，mode＝速查表产物');
     if (mode !== undefined && mode !== 'lookup')
         fail(2, 'mode 非法（' + mode + '）：本键只认 lookup');
+    // #245：两种 HELP 产物（缺省 HELP 文件／`mode:"lookup"` 速查表）都吃复用窗口——缺省一天内只留一份。
+    // `q`（现找）那支不落盘，自然不吃；`--html` 逐字落点那支由 `deliverMemoHtml` 另走覆盖写。
+    const window = helpReuseWindow(params);
     if (q !== undefined) {
         const items = buildLookupItems().filter((it) => q.includes(String(it.id)));
         return { data: { items, total: items.length, mode: 'lookup', query: q } };
@@ -77,7 +128,7 @@ function dispatchHelp(params, dbPath) {
         const items = buildLookupItems();
         return {
             data: { items, total: items.length, mode: 'lookup' },
-            deliver: { target: resolveStemTarget(dbPath, LOOKUP_FILE_STEM, now) },
+            deliver: { landing: landingOf(dbPath, lookupFileStem()), window },
         };
     }
     const data = buildMemoHelpFileData(now, { initialized });
@@ -89,87 +140,284 @@ function dispatchHelp(params, dbPath) {
     // 索引载荷（`list` 形）：一行一域，计数全派生；`memo.help.lookup`＝HELP 文件的交付索引。
     return {
         data: { ...buildHelpSceneIndex(), mode: HELP_MODE_FILE },
-        deliver: { html, target: resolveStemTarget(dbPath, HELP_FILE_STEM, now) },
+        deliver: { html, landing: landingOf(dbPath, helpFileStem()), window },
     };
 }
-// 十一键分发：读走 fetch 读，写走 fetch 写+policy 校验，sync 走 lark 四门；未知键 upstream 已拦，此处再拦一道。
+function ok(data) { return { data, exit: 0 }; }
+function asIds(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        fail(2, 'ids 须为非空数组');
+    return value.map((v) => needId(v, 'ids'));
+}
+const toRows = (xs) => xs.map((x) => ({ ...x }));
 function dispatch(key, params, db) {
     switch (key) {
         case 'memo.search': {
             const items = params.q !== undefined
                 ? searchNotes(db, String(params.q), { category: params.category, sub: params.sub })
                 : listNotes(db).filter((n) => (params.category === undefined || n.category === params.category));
-            return { items, total: items.length };
+            const hit = items.filter((n) => dueMatches(n, params));
+            return ok({ items: hit, total: hit.length });
         }
-        case 'memo.detail': return { item: getNote(db, needStr(params, 'id')) };
+        case 'memo.detail': return ok({ item: getNote(db, needId(params.id, '详情')) });
         case 'memo.create': {
             const c = crudCreate(params);
             const top = normalizeTop(params.category);
             const sub = normalizeSub(params.sub);
-            const remindAt = params.remindAt !== undefined ? normalizeRemindAt(params.remindAt) : null;
-            const n = addNote(db, { title: c.title, body: c.body, category: top, sub, remindAt });
-            return { ok: true, message: '已记一条：' + n.id };
+            const media = params.media !== undefined ? normalizeMediaPath(params.media) : null;
+            const r = ensureWish(db, {
+                title: c.title,
+                body: c.body,
+                category: top,
+                sub,
+                media,
+                remindAt: params.remindAt,
+                repeatType: params.repeatType,
+                repeatRule: params.repeatRule,
+                due: params.due,
+            });
+            return { data: r.receipt, exit: r.exit };
         }
         case 'memo.update': {
+            // 批量排期（老 `set-due`）：一批 id ＋ 一个排期日期（空值＝清期），走心愿那条合成写。
+            if (params.ids !== undefined) {
+                const r = setWishDue(db, { ids: asIds(params.ids), due: params.due });
+                return { data: r.receipt, exit: r.exit };
+            }
             const id = crudUpdate(params).id;
+            // 完成心愿走原子转换（老 `complete-wish`：删心愿 ＋ 生成打卡；`content` 即打卡内容，缺省拷贝心愿原文）。
+            if (params.done === true) {
+                const r = completeWish(db, { id, content: params.content });
+                return { data: r.receipt, exit: r.exit };
+            }
+            if (params.done !== undefined)
+                fail(2, 'done 只认 true（完成心愿）；改字段另给参数');
             const patch = {};
             if (params.title !== undefined || params.body !== undefined) {
-                const c = crudCreate({ title: params.title || getNote(db, id).title, body: params.body || '' });
-                patch.title = c.title;
-                if (params.body !== undefined)
-                    patch.body = c.body;
+                const t = typeof params.title === 'string' ? params.title.trim() : '';
+                const b = typeof params.body === 'string' ? params.body.trim() : '';
+                if (!t && !b)
+                    fail(2, '正文不可改成空');
+                patch.content = b !== '' ? b : t !== '' ? t : getNote(db, id).content;
             }
             if (params.category !== undefined)
                 patch.category = normalizeTop(params.category);
             if (params.sub !== undefined)
-                patch.sub = normalizeSub(params.sub);
+                patch.sub_category = normalizeSub(params.sub);
+            if (params.media !== undefined)
+                patch.media_path = normalizeMediaPath(params.media);
+            if (params.reminderId !== undefined)
+                patch.reminder_id = needId(params.reminderId, '关联提醒');
+            // 老实现没有「改提醒时间」这一路：提醒时间定盘即不可改，错了废弃重建，大声失败不静默。
             if (params.remindAt !== undefined)
-                patch.remindAt = normalizeRemindAt(params.remindAt);
-            if (params.done !== undefined)
-                patch.done = params.done === true;
-            const n = updateNote(db, id, patch);
-            return { ok: true, message: '已更新：' + n.id };
+                fail(2, '提醒时间不可改（废弃旧提醒、重建一条）');
+            if (params.due !== undefined)
+                patch.due = dueForCategory(patch.category ?? getNote(db, id).category, params.due);
+            if (Object.keys(patch).length === 0)
+                fail(2, '至少需要提供一个更新字段：content/category/sub/media/reminderId/due');
+            const r = updateWish(db, { id, patch });
+            return { data: r.receipt, exit: r.exit };
         }
         case 'memo.remove': {
+            // 废弃提醒（老 `dismiss`）：按提醒 id 标 dismissed，笔记保留。
             if (params.mode === 'abandon') {
-                const id = needStr(params, 'id');
-                updateNote(db, id, { remindAt: null });
-                return { ok: true, message: '已废弃提醒（笔记保留）：' + id };
+                const rid = needId(params.id, '废弃提醒');
+                abandonReminder(db, rid);
+                return ok({ ok: true, message: '提醒已废弃（笔记保留）：' + rid });
             }
             const r = crudRemove(params);
-            removeNote(db, r.id, true);
-            return { ok: true, message: '已删除：' + r.id };
+            // 老 `delete`：有关联提醒必须显式级联（`--with-reminders`），否则大声失败；
+            // 有未触发提醒时的二次确认是交互动作，出口非交互，改显式参数一次讲清。
+            const related = countReminderRowsOfNote(db, r.id);
+            if (related > 0 && params.withReminders !== true) {
+                fail(2, '笔记 ' + r.id + ' 关联 ' + related + ' 个提醒，请加 withReminders:true 级联删除（提醒不会被自动删除）');
+            }
+            // #661 · C 口径：默认照老「远端标完成」，显式 `purge:true` 才连飞书任务一起删（两种语义用参数讲清）。
+            const w = removeWish(db, r.id, params.purge === true);
+            return { data: w.receipt, exit: w.exit };
         }
         case 'memo.remind': {
-            const items = listNotes(db).filter((n) => n.remindAt);
-            const done = params.done === true;
-            const out = items.filter((n) => (n.done === true) === done);
-            return { items: out, total: out.length };
+            // 到期判定（老 `due`）：读＋写 notified，定时壳不搬。
+            if (params.mode === 'due' || params.due === true) {
+                const items = checkDueReminders(db);
+                return ok({ items, total: items.length });
+            }
+            // 已完成视图（老 `completed`）；`done:true` 是它的兼容写法。
+            if (params.mode === 'done' || params.done === true) {
+                const items = listCompletedReminders(db);
+                return ok({ items, total: items.length });
+            }
+            const status = params.status === undefined ? 'active' : String(params.status);
+            if (status !== 'active' && status !== 'dismissed')
+                fail(2, 'status 只认 active/dismissed');
+            const items = listReminderRows(db, status);
+            return ok({ items, total: items.length });
         }
         case 'memo.wish': {
-            const items = listNotes(db).filter((n) => n.category === '心愿');
-            return { items, total: items.length };
+            // #665 向导：`wizard: plan` 出排期向导页（默认全勾选），`wizard: complete` 出完成向导页（默认不勾选）；
+            // 不带即老形状（只回列表，#661 行为）。
+            if (params.wizard === 'plan' || params.wizard === 'complete') {
+                if (params.wizard === 'plan') {
+                    const w = planWizard(db, { ids: params.ids, all: params.all, suggestDue: params.suggestDue });
+                    const snap = wishPlanSnapshot(toRows(w.items), w.suggestDue, w.includeAll);
+                    const message = '找到 ' + w.items.length + ' 个心愿' + (w.includeAll ? '（含已排期）' : '（仅未排期）');
+                    const payload = pageEnvelope({
+                        commandCn: '心愿排期', wakeWord: '心愿排期', sceneId: 'wish-batch-plan',
+                        title: snap.title, summary: snap.summary, sections: snap.sections,
+                        copyLog: {
+                            thinking: '过程型向导 · 只读收集心愿列表，勾选＋填排期后复制指令回 AI（HTML 不写库）',
+                            data_structure: "notes 表（category='心愿'）· id/content/category/sub_category/due/feishu_task_guid",
+                            call_chain: 'memo.wish wizard:plan → render_wish_plan → 共享 filler',
+                            exception: '无',
+                        },
+                        extra: { items: w.items, suggest_due: w.suggestDue, all: w.includeAll },
+                        message,
+                    });
+                    return {
+                        data: { items: w.items, total: w.items.length, suggestDue: w.suggestDue, all: w.includeAll },
+                        exit: 0,
+                        deliver: { html: fillMemoPage('wish_plan', payload), stem: '心愿排期向导' },
+                    };
+                }
+                const w = completeWizard(db, { ids: params.ids, onlyOverdue: params.onlyOverdue, all: params.all, content: params.content });
+                const snap = wishCompleteSnapshot(toRows(w.items));
+                const message = '找到 ' + w.items.length + ' 个心愿' + (w.onlyOverdue ? '（仅未排期＋已过期）' : '');
+                const payload = pageEnvelope({
+                    commandCn: '心愿完成', wakeWord: '完成心愿', sceneId: 'wish-complete',
+                    title: snap.title, summary: snap.summary, sections: snap.sections,
+                    copyLog: {
+                        thinking: '过程型向导 · 勾选＋填打卡内容后复制指令回 AI（completeWish 原子转换）',
+                        data_structure: "notes 表（category='心愿'）· id/content/due/feishu_task_guid",
+                        call_chain: 'memo.wish wizard:complete → render_wish_complete → 共享 filler',
+                        exception: '无',
+                    },
+                    extra: { items: w.items, default_content: w.defaultContent, only_overdue: w.onlyOverdue },
+                    message,
+                });
+                return {
+                    data: { items: w.items, total: w.items.length, defaultContent: w.defaultContent, onlyOverdue: w.onlyOverdue },
+                    exit: 0,
+                    deliver: { html: fillMemoPage('wish_complete', payload), stem: '心愿完成向导' },
+                };
+            }
+            const items = listNotes(db).filter((n) => n.category === '心愿').filter((n) => dueMatches(n, params));
+            return ok({ items, total: items.length });
         }
         case 'memo.sync': {
-            const gate = larkReady();
-            return { ok: true, message: '飞书就绪：' + gate.openId + '（同步执行归 M7 端到端）' };
+            // #661：反向对账三步（本地缺标识补建／远端完成→本地／远端改期→本地），回执带 11 项统计。
+            // #665：同步报告页随行（#661 遗留 HELP 承诺，出页归这一支）。
+            const r = reconcileWishes(db);
+            const snap = syncSnapshot(r.receipt);
+            const payload = pageEnvelope({
+                commandCn: '备忘录同步', wakeWord: '备忘录同步', sceneId: 'sync-from-feishu',
+                title: snap.title, summary: snap.summary, sections: snap.sections,
+                copyLog: {
+                    thinking: '双向对账 · 飞书 done/due 反向同步到本机（只读扫描 ＋ 有变更才写）',
+                    data_structure: 'reconcile 11 项统计（backfilled/synced/due_*/skipped_*/errors）',
+                    call_chain: 'memo.sync → reconcileWishes → render_sync_report → 共享 filler',
+                    exception: r.receipt.errors.length ? r.receipt.errors.join('; ') : '无',
+                },
+                extra: { ...r.receipt },
+                message: r.receipt.message,
+            });
+            return { data: r.receipt, exit: r.exit, deliver: { html: fillMemoPage('sync_report', payload), stem: '同步报告' } };
+        }
+        case 'memo.batch': {
+            // #665 批量改分类：不带目标分类即收集（出向导页）；带目标分类＋ids 即执行。
+            const from = params.fromCategory !== undefined ? normalizeTop(params.fromCategory) : null;
+            const to = params.toCategory !== undefined ? normalizeTop(params.toCategory) : null;
+            if (from !== null && to !== null && from === to)
+                fail(2, '原分类与目标分类相同：' + from);
+            // 执行（老 `update-category` 逐条）：目标分类＋一批 id；只给目标分类不给 id 即收集预览。
+            if (params.ids !== undefined) {
+                if (to === null)
+                    fail(2, '执行改分类须给 toCategory（只收集不执行时别给 ids）');
+                const r = applyBatchCategory(db, asIds(params.ids), to);
+                const doneAll = r.errors.length === 0;
+                return {
+                    data: {
+                        ok: doneAll,
+                        message: '改分类完成：更新=' + r.updated + '，跳过=' + r.skipped,
+                        updated: r.updated,
+                        skipped: r.skipped,
+                        errors: r.errors,
+                    },
+                    exit: doneAll ? 0 : 4,
+                };
+            }
+            const items = collectBatchItems(db, from);
+            const snap = changeCategorySnapshot(toRows(items), from, to);
+            const message = "原分类 '" + (from ?? '<全部>') + "' 下 " + items.length + ' 条笔记';
+            const payload = pageEnvelope({
+                commandCn: '批量改分类', wakeWord: '备忘改分类', sceneId: 'batch-update-category',
+                title: snap.title, summary: snap.summary, sections: snap.sections,
+                copyLog: {
+                    thinking: '过程型向导 · 勾选后复制改分类指令回 AI（只改顶层分类，sub_category 不动）',
+                    data_structure: 'notes 表 · id/content/category/sub_category/media_path/due',
+                    call_chain: 'memo.batch → render_change_category → 共享 filler',
+                    exception: '无',
+                },
+                extra: { items, from_category: from, to_category: to, target_conflict_count: to ? countNotesByCategory(db, to) : 0 },
+                message,
+            });
+            return {
+                data: { ok: true, message, items, total: items.length, fromCategory: from, toCategory: to },
+                exit: 0,
+                deliver: { html: fillMemoPage('change_category', payload), stem: '批量改分类' },
+            };
+        }
+        case 'memo.auth': {
+            // #665 飞书授权引导（三步非阻塞，Q4 批新增 key）：init／qr／poll＋status 诊断。
+            // #666 自检 sentinel：step:'diag'（显式诊断，D-03 任务半场）。
+            const step = params.step === undefined ? 'status' : String(params.step);
+            if (step === 'init') {
+                const brand = params.brand === undefined ? 'feishu' : String(params.brand);
+                return ok({
+                    ok: true,
+                    message: '授权已发起：在浏览器打开链接或扫码，完成后调 step poll 续轮询',
+                    step: 'init',
+                    ...authInit(brand),
+                });
+            }
+            if (step === 'qr') {
+                if (typeof params.url !== 'string' || params.url.length === 0)
+                    fail(2, 'qr 须给 url（init 回的 verification_url）');
+                const qrPath = authQr(params.url, params.outDir === undefined ? undefined : String(params.outDir));
+                return ok({ ok: true, message: '二维码已生成', step: 'qr', qrPath });
+            }
+            if (step === 'poll') {
+                if (typeof params.deviceCode !== 'string' || params.deviceCode.length === 0) {
+                    fail(2, 'poll 须给 deviceCode（init 回的 device_code，过期请重走 init）');
+                }
+                const domain = params.domain === undefined ? 'task' : String(params.domain);
+                return ok({ ok: true, message: '授权续轮询完成', step: 'poll', ...authPoll(params.deviceCode, domain) });
+            }
+            if (step === 'status') {
+                return ok({ ok: true, message: '授权状态', step: 'status', ...authStatus() });
+            }
+            if (step === 'diag') {
+                // #666 自检 sentinel（D-03 任务半场）：显式才跑；默认四步不碰它，零写。
+                const r = runSentinel(params.dryRun === true ? { dryRun: true } : undefined);
+                return { data: r.receipt, exit: r.exit };
+            }
+            fail(2, 'step 只认 init/qr/poll/status/diag');
+            return ok(null);
         }
-        case 'memo.batch': return { ok: true, message: '批量改分类向导须交互确认（M5 只登记意图）' };
         case 'memo.stats': {
             const all = listNotes(db);
             const metrics = { count: all.length };
             for (const n of all)
                 metrics['cat.' + n.category] = (metrics['cat.' + n.category] || 0) + 1;
-            return { metrics };
+            return ok({ metrics });
         }
         // #229：本键由 `dispatchHelp` 在**开库之前**处理（只读页不建库）；走到这里说明 main 的路由被改坏了。
         // 照 skill-bill/src/cli/cmd_read.ts:449-451 的同一道内部断言——防的是「改回无条件开库」这个静默回退。
         case 'memo.help.lookup':
             fail(1, '内部错误：memo.help.lookup 须走 dispatchHelp（开库之前）');
-            return null;
+            return ok(null);
         default:
             fail(3, '未知 memo key：' + key);
-            return null;
+            return ok(null);
     }
 }
 function parseArgs(a) {
@@ -193,7 +441,6 @@ async function main() {
     const o = parseArgs(process.argv.slice(2));
     if (!o.key)
         fail(2, '用法：memo-cmd-read <memo.key> [--params JSON对象] [--html 输出路径] [--timeout 毫秒]');
-    const dbPath = preflight();
     let params = {};
     if (o.params !== undefined) {
         try {
@@ -205,6 +452,28 @@ async function main() {
         if (typeof params !== 'object' || params === null || Array.isArray(params))
             fail(2, '--params 须为 JSON 对象');
     }
+    // #695：三个配置 key（`memo.config.read/write/reset`）在库目录预检与形状表之前拦下——
+    // 读写配置不该要求库已配，它们也不进 `MEMO_KEY_SHAPES`（不是唤醒词命令，见 `src/cli/config.ts`）。
+    if (isConfigKey(o.key)) {
+        process.stdout.write(runConfigKey(o.key, params) + '\n');
+        return;
+    }
+    // #706 · 配置体检（`memo.config.check`）：同样是设置页专用的只读命令，同样在预检之前拦下——
+    // 它要报的正是「库在哪、通不通」，不能先要求库目录已配。只读：不建目录、不写文件、不落默认配置。
+    if (isHealthCheckKey(o.key)) {
+        process.stdout.write(runHealthCheckKey(o.key) + '\n');
+        return;
+    }
+    preflight();
+    // 读配置算库目录：配置件的报错本身就是人话（带行号与文件名），归「预检」那一档原样交回
+    // （不能让它裸抛——那会吐一整段 node 崩溃栈，用户看不到「该在哪配」）。
+    let dbPath = '';
+    try {
+        dbPath = resolveDbDir();
+    }
+    catch (e) {
+        fail(1, e instanceof Error ? e.message : String(e));
+    }
     let shape = null;
     try {
         shape = memoShapeFor(o.key);
@@ -217,10 +486,35 @@ async function main() {
     timer.unref();
     let env = null;
     let delivery;
+    // #661：合成写「最终没达成」时回执照打、退出码在写完回执之后落实（分字段是回执的本分，不能因为非 0 就吞掉）。
+    let writeExit = 0;
     try {
-        // #229：`memo.help.lookup` 在**开库之前**分派（只读页不建库）；其余 10 键照旧走 dispatch（内部开库）。
+        // #229：`memo.help.lookup` 在**开库之前**分派（只读页不建库）；其余键照旧走 dispatch。
+        // #665：开的是老库文件（直连，不建库）；用完即关，失败也关。
         const help = o.key === 'memo.help.lookup' ? dispatchHelp(params, dbPath) : null;
-        env = buildMemoEnvelope(o.key, help ? help.data : dispatch(o.key, params, openMemoDb(join(dbPath, 'memo'))));
+        let db = null;
+        let out;
+        try {
+            if (help === null) {
+                db = openMemoDb(dbPath);
+                out = dispatch(o.key, params, db);
+            }
+            else {
+                out = { data: help.data, exit: 0 };
+            }
+        }
+        finally {
+            if (db) {
+                try {
+                    closeMemoDb(db);
+                }
+                catch {
+                    // 关库失败不掩盖主流程结果。
+                }
+            }
+        }
+        writeExit = out.exit;
+        env = buildMemoEnvelope(o.key, out.data);
         const built = env;
         // B4 既有语义：`--html <路径>` 逐字写用户给的路径，内容仍是本包的 envelope 片段（`renderEnvelopeHtml`）。
         const sectionHtml = () => {
@@ -233,7 +527,11 @@ async function main() {
             const html = help.deliver.html ?? sectionHtml();
             if (help.deliver.html !== undefined)
                 assertHtmlSize(html);
-            delivery = deliverMemoHtml({ explicit: o.html, target: help.deliver.target, html });
+            delivery = deliverMemoHtml({ explicit: o.html, landing: help.deliver.landing, html, window: help.deliver.window });
+        }
+        else if (out.deliver !== undefined) {
+            // #665 整页交付：缺省落 `memo_html/<页名>.html`（独占递补），显式 `--html` 逐字覆盖写。
+            delivery = deliverMemoHtml({ explicit: o.html, landing: landingOf(dbPath, out.deliver.stem), html: out.deliver.html });
         }
         else if (o.html) {
             delivery = deliverMemoHtml({ explicit: o.html, html: sectionHtml() });
@@ -250,7 +548,8 @@ async function main() {
         if (e?.code && /^E[A-Z]+$/.test(String(e.code))) {
             fail(5, '落盘失败：' + (e.message || String(e)));
         }
-        if (e.message?.includes('SKILLS_DB_PATH'))
+        // 配置件（`base-link-core`）的报错本身就是人话（带行号与文件名）：归「预检」那一档原样交回。
+        if (/(配置文件|配置项|测试缺隔离)/.test(e.message ?? ''))
             fail(1, e.message);
         fail(4, '未知失败：' + (e.message || String(e)));
     }
@@ -259,6 +558,11 @@ async function main() {
     }
     // #83／#144 口径的顶层追加：`delivery{mode,path,bytes}` 只追加，envelope 既有五字段一字不改、序不变。
     process.stdout.write(JSON.stringify(delivery ? { ...env, delivery } : env) + '\n');
+    // #661：本地那一侧成了、远端那一侧没成 ⇒ 回执已分字段写明，退出码仍要如实反映「这一趟没达成」（契约 A3／A6）。
+    if (writeExit !== 0) {
+        console.error('ERR ' + writeExit + ': 合成写没达成（本地侧已落，远端侧见回执 remote 那一格）');
+        process.exit(writeExit);
+    }
 }
 await main();
 //# sourceMappingURL=cmd_read.js.map