skill-bill 0.1.0 → 0.2.1

package/dist/cli/cmd_read.js

@@ -2,347 +2,132 @@
 // 饼干记账唯一出口 cmd_read：argv+JSON(stdout)+exit；非 0 走 stderr；超时 terminate+TOAST 降级标记。
 // 退出码对齐 skilllink 冻结：0 ok；1 预检；2 用法/参数；3 key；4 取数/超时；5 envelope/渲染/落盘。
 // stdout 纯净：成功只打 envelope JSON 一行。写走 receipt（直通即真相）。
-import { writeFileSync, readFileSync, copyFileSync, readdirSync, existsSync, mkdirSync } from 'node:fs';
-import { join, basename } from 'node:path';
-import { BillFetchError, BillPolicyError, resolveDbPath, resolveGoalsPath, assertWritablePath, openBillDb, closeBillDb, fetchAll, listToday, listRange, getById, searchKeyword, listByTag, addBill, updateBill, undoBill, restoreBill, loadGoals, saveGoals, } from '../fetch/index.js';
-import { validateAddInput, validateUpdateInput, needId, parseRecordOp, resolveQueryDate, resolveRange, parseOverviewKind, parseCompareKind, parseTrendKind, parseGoalOp, validateSetBudget, validateSetSaving, parseAccountOp, needName, validateTransfer, TRANSFER_OUT_CATEGORY, TRANSFER_IN_CATEGORY, TRANSFER_LEDGER, validateCategory, } from '../policy/index.js';
-import { billShapeFor, buildBillEnvelope, renderEnvelopeHtml, assertHtmlSize, templateFor, loadTemplate, fillTemplate, toBillItem, buildRecordToday, buildRecordRange, buildRecordSearch, buildRecordDetail, buildRecordReceipt, buildOverview, buildCompare, buildTrend, buildGoalQuery, buildAccountQuery, buildHelpItems, BillRenderError, } from '../render/index.js';
-import { buildHelpLookup } from '../help/index.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { BillFetchError, BillPolicyError, resolveDbPath, resolveDbDir, resolveGoalsPath, openBillDb, closeBillDb, } from '../fetch/index.js';
+import { billShapeFor, buildBillEnvelope, renderEnvelopeHtml, assertHtmlSize, templateFor, loadTemplate, fillTemplate, buildHelpIndex, buildHelpFileData, renderHelpFileHtml, BillRenderError, } from '../render/index.js';
+// #726：产物目录名与两个文件名主体改成「现读配置」的三个函数（那几个常量仍住同一处定义地，是默认值）。
+import { htmlDirName, lookupFileStem } from '../help/helpPaths.js';
+import { helpFileStem } from '../help/helpFile.js';
+import { deliverHtml } from '../output.js';
+import { helpReuseWindowOf } from 'base-paint/save-html';
+import { buildHelpLookup, buildHelpItems } from '../help/index.js';
+import { REGISTRY } from './registry.js';
+// #677 · 设置页的三个配置 key 由本文件在**预检与分派层之前**拦下（见下行 main 里那一处拦截与 cli/config.ts 的件头）。
+import { isConfigKey, runConfigKey } from './config.js';
+// #706 · 配置体检：设置页专用的一条只读命令，同走「进分派层之前拦下」这条口（判据住 src/health.ts）。
+import { isHealthCheckKey, runHealthCheckKey } from './health.js';
+import { buildRecordReceipt } from '../write/index.js';
 const DEFAULT_TIMEOUT_MS = 30000;
 function fail(code, msg) { console.error('ERR ' + code + ': ' + msg); process.exit(code); }
 function toast(msg) { console.error('TOAST: ' + msg); }
 function note(msg) { console.error('NOTE: ' + msg); }
+/** 预检只留 node 版本这一道门（#726）：库目录不再要求环境变量——落点由配置文件唯一决定，
+ *  缺项一律按默认落点走，故「没配」不再是阻断项。测试隔离那道响亮失败住 `base-link-core`
+ *  （跑在 `node --test` 里却没设 `ILIFE_CONFIG_DIR` 即抛 `CONFIG_TEST_ISOLATION_MISSING`）。 */
 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 monthRange(month) {
-    const [y, m] = month.split('-').map(Number);
-    const last = new Date(y, m, 0).getDate();
-    const dd = String(last).padStart(2, '0');
-    return { start: month + '-01', end: month + '-' + dd };
+/** 吃复用窗口的 HELP 产物名（本技能自己的两个主体）。#245：判据**按落点名**而不是按 key——
+ *  `bill.help.lookup` 这条命令下挂着两种产物（HELP 文件与速查表），两种都算「反复读的 HELP 产物」；
+ *  而 `--html` 那支是用户逐字指定的落点（共用件的 `file` 口子），本来不吃复用。
+ *  #726 起改成函数：两个主体随配置变（`html.helpStem`／`html.quickRefStem`），常量会在配置改动后陈旧。 */
+function helpReuseStems() {
+    return [helpFileStem(), lookupFileStem()];
 }
-function yesterdayStr() {
-    const d = new Date();
-    d.setDate(d.getDate() - 1);
-    return d.toISOString().slice(0, 10);
+/** 本次交付吃不吃复用窗口 ⇒ 给出窗口毫秒数（不吃 = `undefined`，交付退回「独占创建 ＋ 递补」老口径）。
+ *
+ *  窗口来自 `--params` 的 `reuseHours`（小时）：不给＝缺省一天（`HELP_REUSE_DEFAULT_HOURS`）、
+ *  `0`＝每次都落新的、正数＝该窗口。换算与校验都在共用件，坏参抛 `RangeError` ⇒ 用共用件的
+ *  `helpReuseWindowOf` 把它翻成出口的「参数错」那一档（exit 2）——五家技能同一档，坏参绝不静默当 0。 */
+const windowOf = helpReuseWindowOf((m) => fail(2, m));
+function windowForHelpDelivery(stem, params) {
+    if (!helpReuseStems().includes(stem))
+        return undefined;
+    return windowOf(params);
 }
-function weekRange() {
+/** 初始化状态：DB **文件存在**＝已初始化（照老 `render_help._is_initialized`）；
+ *  判定本身异常 ⇒ `false`＝横幅照显（fail-open，理由见 render/helpFile.ts 头注释）。 */
+function helpInitialized() {
+    try {
+        return existsSync(resolveDbPath());
+    }
+    catch {
+        return false;
+    }
+}
+function dispatchHelp(params) {
     const now = new Date();
-    const day = (now.getDay() + 6) % 7;
-    const mon = new Date(now);
-    mon.setDate(now.getDate() - day);
-    const sun = new Date(mon);
-    sun.setDate(mon.getDate() + 6);
-    return { start: mon.toISOString().slice(0, 10), end: sun.toISOString().slice(0, 10) };
+    const mode = params.mode === undefined ? undefined : String(params.mode);
+    const q = params.q === undefined ? undefined : String(params.q);
+    if (mode !== undefined && q !== undefined)
+        fail(2, '参数 q 与 mode 互斥：q＝现找，mode＝速查表产物');
+    if (mode !== undefined && mode !== 'lookup')
+        fail(2, 'mode 非法（' + String(mode) + '）：本命令只认 lookup');
+    if (q !== undefined) {
+        const hits = buildHelpItems(buildHelpLookup(), q);
+        return { data: { ...hits, mode: 'lookup', query: q } };
+    }
+    if (mode === 'lookup') {
+        const hits = buildHelpItems(buildHelpLookup(), undefined);
+        const stem = lookupFileStem();
+        return {
+            data: { ...hits, mode: 'lookup' },
+            deliver: {
+                target: { dir: join(resolveDbDir(), htmlDirName()), stem },
+                reuseMs: windowForHelpDelivery(stem, params),
+            },
+        };
+    }
+    const html = renderHelpFileHtml(buildHelpFileData(now, { initialized: helpInitialized() }));
+    const stem = helpFileStem();
+    return {
+        data: { ...buildHelpIndex(), mode: 'file', bytes: Buffer.byteLength(html, 'utf8') },
+        deliver: {
+            html,
+            target: { dir: join(resolveDbDir(), htmlDirName()), stem },
+            reuseMs: windowForHelpDelivery(stem, params),
+        },
+    };
+}
+/** 迁移过的命令入口（写入域两条 ＋ 查询域四条 ＋ 账户域两条）：查注册表命中即走**命令声明里的 `run`**。
+ *  开库／关库与老路同一套；**写库开关已退役（#726）**：`BILL_FORCE_PROD` 那个 opt-in 随 #675 删除，
+ *  落点改由配置文件唯一决定（口径「照写」，替代护栏＝测试基座的 `ILIFE_CONFIG_DIR`）。
+ *  这些命令的整页（采集页／回执页／查询列表页／账户表单与汇总页）住各自能力目录，
+ *  故 `dispatch` 的 switch 里**不再有**它们的 case（一个命令恰住一处）。
+ *  #691 起**不再按域写死入口**（改前是 `spec.kind === 'write' ? runRecordWrite : runQueryRead` 两条）：
+ *  声明里本来就带着 `run`，第三个域进来时这一支一行不动——入口跟着声明走，域不需要在外壳上挂号。 */
+function runRegistered(key, params) {
+    const spec = REGISTRY[key];
+    if (spec === undefined)
+        fail(3, '未知 bill 命令：' + key);
+    const dbPath = resolveDbPath();
+    const handle = openBillDb(dbPath);
+    try {
+        if (handle.initialized)
+            note('记账 DB 已初始化：' + dbPath);
+        return spec.run(params, handle);
+    }
+    finally {
+        try {
+            closeBillDb(handle);
+        }
+        catch { /* ignore */ }
+    }
 }
-// 十六键分发：读走 fetch 读，写走 fetch 写+policy 校验；未知键上游已拦，此处再拦一道。
+// 十六条命令分发：读走 fetch 读，写走 fetch 写+各域门的校验；未知命令名上游已拦，此处再拦一道。
 function dispatch(key, params) {
     const dbPath = resolveDbPath();
     const goalsPath = resolveGoalsPath();
-    // 写键前置守卫（B6）：非 tmp 写库须 BILL_FORCE_PROD=1；读键不受影响。
-    if (key === 'bill.record.add' || key === 'bill.record.update')
-        assertWritablePath(dbPath);
-    if (key === 'bill.goal.write')
-        assertWritablePath(goalsPath);
-    if (key === 'bill.account.write') {
-        assertWritablePath(dbPath);
-        assertWritablePath(goalsPath);
-    }
     const handle = openBillDb(dbPath);
     try {
         if (handle.initialized)
             note('记账 DB 已初始化：' + dbPath);
         switch (key) {
-            case 'bill.record.add': {
-                const input = validateAddInput(params);
-                const r = addBill(handle, input);
-                const kind = typeof params.kind === 'string' ? params.kind : '';
-                const extra = kind === 'photo' ? '（拍账单图片识别以外置为准）' : kind === 'batch' ? '（批量逐笔校验其一）' : kind ? `（${kind}）` : '';
-                return buildRecordReceipt(`已记录：${r.category} ${r.amount.toFixed(2)}${extra}（id=${r.id}，账单回执可复制 prompt）`);
-            }
-            case 'bill.record.update': {
-                const op = parseRecordOp(params);
-                if (op === 'undo') {
-                    const id = needId(params);
-                    const r = undoBill(handle, id);
-                    return buildRecordReceipt(`已撤销：${r.id}（软删，恢复走 restore）`);
-                }
-                if (op === 'restore') {
-                    const id = needId(params);
-                    const r = restoreBill(handle, id);
-                    return buildRecordReceipt(`已恢复：${r.id}`);
-                }
-                const { id, patch } = validateUpdateInput(params);
-                const r = updateBill(handle, id, patch);
-                return buildRecordReceipt(`已修改：${r.id}（${Object.keys(patch).join('/')}）`);
-            }
-            case 'bill.record.today': {
-                if (params.recent === true) {
-                    const limit = params.limit === undefined ? 10 : params.limit;
-                    if (!Number.isInteger(limit) || limit < 1 || limit > 200)
-                        fail(2, 'recent limit 须为 1~200 的整数');
-                    const rows = fetchAll(handle).sort((a, b) => b.time.localeCompare(a.time) || b.id - a.id).slice(0, limit);
-                    return buildRecordToday('recent', rows);
-                }
-                const date = params.date === 'yesterday' ? yesterdayStr() : resolveQueryDate(params);
-                const rows = listToday(handle, date);
-                if (!rows.length)
-                    note('当日无记录：' + date + '（真实无，非故障）');
-                return buildRecordToday(date, rows);
-            }
-            case 'bill.record.range': {
-                let start;
-                let end;
-                if (typeof params.range === 'string' && params.range === 'week')
-                    ({ start, end } = weekRange());
-                else if (typeof params.range === 'string' && params.range === 'month')
-                    ({ start, end } = monthRange(new Date().toISOString().slice(0, 7)));
-                else if (params.start !== undefined || params.end !== undefined)
-                    ({ start, end } = resolveRange(params));
-                else if (params.category !== undefined || params.account !== undefined || params.ledger !== undefined) {
-                    const rows = fetchAll(handle, {
-                        category: params.category,
-                        account: params.account,
-                        ledger: params.ledger,
-                    });
-                    if (!rows.length)
-                        throw new BillFetchError('BILL_EMPTY_RANGE', '条件无记录（缺失阻断，不返空统计）');
-                    return buildRecordRange('', '', rows);
-                }
-                else
-                    fail(2, '缺槽位 start/end（或 range=week/month，或 category/account/ledger 条件）');
-                const rows = fetchAll(handle, {
-                    fromTime: start + ' 00:00:00', toTime: end + ' 23:59:59',
-                    category: params.category,
-                    account: params.account,
-                    ledger: params.ledger,
-                });
-                if (!rows.length)
-                    throw new BillFetchError('BILL_EMPTY_RANGE', `区间无记录：${start}~${end}（缺失阻断，不返空统计）`);
-                return buildRecordRange(start, end, rows);
-            }
-            case 'bill.record.search': {
-                const kind = params.kind === undefined ? '' : String(params.kind);
-                if (kind === 'tag') {
-                    const tag = params.tag;
-                    if (typeof tag !== 'string' || !tag.trim())
-                        fail(2, '查标签须给 tag');
-                    return buildRecordSearch('tag:' + tag, listByTag(handle, tag));
-                }
-                if (kind === 'debt') {
-                    const rows = fetchAll(handle).filter((r) => r.category.startsWith('借贷/') || r.note.includes('#未还'));
-                    return buildRecordSearch('debt', rows);
-                }
-                if (kind === 'reimburse') {
-                    const rows = fetchAll(handle).filter((r) => r.note.includes('#待报销'));
-                    return buildRecordSearch('reimburse', rows);
-                }
-                if (kind === 'installment') {
-                    const rows = fetchAll(handle).filter((r) => r.category.startsWith('分期/') || r.note.includes('#分期'));
-                    return buildRecordSearch('installment', rows);
-                }
-                const q = params.q;
-                if (typeof q !== 'string' || !q.trim())
-                    fail(2, '搜备注须给 q');
-                return buildRecordSearch('search:' + q, searchKeyword(handle, q));
-            }
-            case 'bill.record.detail': {
-                return buildRecordDetail(getById(handle, needId(params)));
-            }
-            case 'bill.analysis.overview': {
-                const kind = parseOverviewKind(params);
-                let rows;
-                let label = kind;
-                if (params.month !== undefined) {
-                    const m = String(params.month);
-                    const { start, end } = monthRange(m);
-                    rows = listRange(handle, start, end);
-                    label = m;
-                }
-                else if (params.start !== undefined || params.end !== undefined) {
-                    const { start, end } = resolveRange(params);
-                    rows = listRange(handle, start, end);
-                    label = start + '~' + end;
-                }
-                else if (kind === 'monthly') {
-                    const { start, end } = monthRange(new Date().toISOString().slice(0, 7));
-                    rows = listRange(handle, start, end);
-                    label = start.slice(0, 7);
-                }
-                else {
-                    rows = fetchAll(handle);
-                }
-                if (!rows.length)
-                    throw new BillFetchError('BILL_EMPTY_RANGE', '总览区间无记录：' + label + '（缺失阻断）');
-                return buildOverview(label, rows);
-            }
-            case 'bill.analysis.compare': {
-                const kind = parseCompareKind(params);
-                if (kind === 'period' || kind === 'yoy') {
-                    const a = params.monthA;
-                    const b = params.monthB;
-                    if (typeof a !== 'string' || typeof b !== 'string')
-                        fail(2, '对比须给 monthA/monthB（YYYY-MM）');
-                    const ra = monthRange(a);
-                    const rb = monthRange(b);
-                    const rowsA = listRange(handle, ra.start, ra.end);
-                    const rowsB = listRange(handle, rb.start, rb.end);
-                    if (!rowsA.length || !rowsB.length)
-                        throw new BillFetchError('BILL_EMPTY_RANGE', '对比区间有空（缺失阻断）');
-                    return buildCompare({ labelA: a, labelB: b, a: rowsA, b: rowsB });
-                }
-                if (kind === 'range') {
-                    for (const k of ['startA', 'endA', 'startB', 'endB'])
-                        if (typeof params[k] !== 'string')
-                            fail(2, '双区间对比须给 startA/endA/startB/endB');
-                    const rowsA = listRange(handle, params.startA, params.endA);
-                    const rowsB = listRange(handle, params.startB, params.endB);
-                    if (!rowsA.length || !rowsB.length)
-                        throw new BillFetchError('BILL_EMPTY_RANGE', '对比区间有空（缺失阻断）');
-                    return buildCompare({ labelA: `${params.startA}~${params.endA}`, labelB: `${params.startB}~${params.endB}`, a: rowsA, b: rowsB });
-                }
-                const { start, end } = resolveRange(params);
-                const rows = listRange(handle, start, end);
-                if (!rows.length)
-                    throw new BillFetchError('BILL_EMPTY_RANGE', '分类对比区间无记录（缺失阻断）');
-                const mid = start.slice(0, 7);
-                const ra = monthRange(mid);
-                const rowsA = rows.filter((r) => r.time <= ra.end + ' 23:59:59');
-                return buildCompare({ labelA: start + '~' + ra.end, labelB: ra.end + '~' + end, a: rowsA.length ? rowsA : rows, b: rows });
-            }
-            case 'bill.analysis.trend': {
-                const kind = parseTrendKind(params);
-                let rows;
-                if (params.month !== undefined) {
-                    const { start, end } = monthRange(String(params.month));
-                    rows = listRange(handle, start, end);
-                }
-                else if (params.start !== undefined || params.end !== undefined) {
-                    const { start, end } = resolveRange(params);
-                    rows = listRange(handle, start, end);
-                }
-                else {
-                    rows = fetchAll(handle);
-                }
-                if (!rows.length)
-                    throw new BillFetchError('BILL_EMPTY_RANGE', '趋势区间无记录（缺失阻断）');
-                const limit = params.limit === undefined ? 5 : params.limit;
-                if (params.limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 50))
-                    fail(2, 'limit 须为 1~50 的整数');
-                return buildTrend(kind, rows, { limit: limit });
-            }
-            case 'bill.goal.write': {
-                const op = parseGoalOp(params);
-                const goals = loadGoals(goalsPath);
-                if (op === 'set-budget') {
-                    const { month, category, amount, force } = validateSetBudget(params);
-                    const hit = goals.budgets.find((b) => b.month === month && (b.category || '') === category);
-                    if (hit && !force) {
-                        throw new BillPolicyError('POLICY_CONFLICT', `同月同分类预算已存在（${month} ${category || '全分类'} ${JSON.stringify(hit.amount)}），确认后加 --force 重跑`);
-                    }
-                    const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
-                    if (hit && force) {
-                        hit.amount = amount;
-                        hit.created_at = now;
-                    }
-                    else {
-                        const id = Math.max(0, ...goals.budgets.map((b) => Number(b.id) || 0)) + 1;
-                        goals.budgets.push({ id, month, category, amount, created_at: now });
-                    }
-                    saveGoals(goalsPath, goals);
-                    return buildRecordReceipt(`已设定预算：${month} ${category || '全分类'} ${amount.toFixed(2)}`);
-                }
-                if (op === 'set-saving') {
-                    const { name, amount, deadline } = validateSetSaving(params);
-                    const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
-                    const id = Math.max(0, ...goals.savings.map((b) => Number(b.id) || 0)) + 1;
-                    goals.savings.push({ id, name, amount, deadline, created_at: now });
-                    saveGoals(goalsPath, goals);
-                    return buildRecordReceipt(`已设定目标：${name} ${amount.toFixed(2)}${deadline ? '（' + deadline + ' 前）' : ''}`);
-                }
-                fail(2, 'goal.write 只接受 op=set-budget/set-saving');
-                return null;
-            }
-            case 'bill.goal.query': {
-                const op = parseGoalOp(params);
-                const goals = loadGoals(goalsPath);
-                if (op === 'budget' || params.op === undefined) {
-                    const month = typeof params.month === 'string' ? params.month : new Date().toISOString().slice(0, 7);
-                    const { start, end } = monthRange(month);
-                    const rows = listRange(handle, start, end);
-                    const items = goals.budgets.filter((b) => b.month === month).map((b) => {
-                        const bb = b;
-                        const cat = String(bb.category || '');
-                        const spent = rows.filter((r) => r.amount < 0 && (cat === '' || r.category === cat || r.category.startsWith(cat + '/'))).reduce((a, r) => a + Math.abs(r.amount), 0);
-                        const amount = Number(bb.amount);
-                        return { ...bb, spent: Math.round(spent * 100) / 100, remaining: Math.round((amount - spent) * 100) / 100, rate: amount > 0 ? Math.round((spent / amount) * 1000) / 10 : 0 };
-                    });
-                    return buildGoalQuery('budget:' + month, items);
-                }
-                const items = goals.savings.map((s) => {
-                    const ss = s;
-                    const rows = fetchAll(handle);
-                    const net = rows.filter((r) => r.ledger !== '转账' && !r.category.startsWith('转账/')).reduce((a, r) => a + r.amount, 0);
-                    const amount = Number(ss.amount);
-                    return { ...ss, saved: Math.round(net * 100) / 100, pct: amount > 0 ? Math.round((net / amount) * 1000) / 10 : 0 };
-                });
-                return buildGoalQuery('saving', items);
-            }
-            case 'bill.account.write': {
-                const op = parseAccountOp(params);
-                const goals = loadGoals(goalsPath);
-                if (op === 'add') {
-                    const name = needName(params);
-                    const type = typeof params.type === 'string' ? params.type : '';
-                    if (goals.accounts.some((a) => a.name === name)) {
-                        throw new BillPolicyError('POLICY_CONFLICT', '账户已存在：' + name);
-                    }
-                    goals.accounts.push({ name, type, disabled: false, created_at: new Date().toISOString().slice(0, 19).replace('T', ' ') });
-                    saveGoals(goalsPath, goals);
-                    return buildRecordReceipt(`已新增账户：${name}`);
-                }
-                if (op === 'update') {
-                    const name = needName(params);
-                    const acc = goals.accounts.find((a) => a.name === name);
-                    if (!acc)
-                        throw new BillFetchError('BILL_ACCOUNT_CORRUPT', '无此账户：' + name);
-                    if (typeof params['new-name'] === 'string' && params['new-name'].trim())
-                        acc.name = params['new-name'].trim();
-                    if (params.disable === true)
-                        acc.disabled = true;
-                    if (params.enable === true)
-                        acc.disabled = false;
-                    saveGoals(goalsPath, goals);
-                    return buildRecordReceipt(`已修改账户：${String(acc.name)}`);
-                }
-                if (op === 'transfer') {
-                    const { amount, from, to, time } = validateTransfer(params);
-                    const t = time || new Date().toISOString().slice(0, 19).replace('T', ' ');
-                    addBill(handle, { category: TRANSFER_OUT_CATEGORY, amount: -amount, time: t, account: from, ledger: TRANSFER_LEDGER, currency: '人民币', note: '#转账（转出）' });
-                    addBill(handle, { category: TRANSFER_IN_CATEGORY, amount, time: t, account: to, ledger: TRANSFER_LEDGER, currency: '人民币', note: '#转账（转入）' });
-                    return buildRecordReceipt(`已转账：${from}→${to} ${amount.toFixed(2)}（双笔 #转账，不入收支）`);
-                }
-                fail(2, 'account.write 只接受 op=add/update/transfer');
-                return null;
-            }
-            case 'bill.account.query': {
-                const goals = loadGoals(goalsPath);
-                const rows = fetchAll(handle);
-                const items = goals.accounts.map((a) => {
-                    const aa = a;
-                    const name = String(aa.name);
-                    const bal = rows.filter((r) => r.account === name).reduce((s, r) => s + r.amount, 0);
-                    const recent = rows.filter((r) => r.account === name).sort((x, y) => y.time.localeCompare(x.time) || y.id - x.id).slice(0, 3).map(toBillItem);
-                    return { name, type: aa.type || '', disabled: !!aa.disabled, balance: Math.round(bal * 100) / 100, recent };
-                });
-                return buildAccountQuery(items);
-            }
+            // #729：分析域三条读命令（`bill.analysis.overview`／`compare`／`trend`）已搬进 `src/analysis/`，
+            // 出口只查注册表（`runRegistered`）再调命令声明里的 `run`——本分派层不再认这三条 key。
             case 'bill.link.submit': {
                 const scene = params.scene === undefined ? 'purchase' : params.scene;
                 if (scene !== 'purchase' && scene !== 'meal')
@@ -360,83 +145,12 @@ function dispatch(key, params) {
                 const ate = typeof params.ate === 'string' ? params.ate : '';
                 return buildRecordReceipt(`已采单吃饭${ate ? '：' + ate : ''}（主操作请先走 bill.record.add 记支出；同时记卡路里请复制 prompt：请加载「卡路里」技能，帮我记一餐${ate ? '：' + ate : ''}）`);
             }
-            case 'bill.setup.run': {
-                const op = typeof params.op === 'string' ? params.op : 'init-status';
-                if (op === 'init') {
-                    return buildRecordReceipt(`已初始化：${dbPath}（幂等自愈，bills 10 列 + 索引 + deleted_at 补列）`);
-                }
-                if (op === 'init-status') {
-                    return buildRecordReceipt(`就绪：bills 表 10 列（v2.0 特征 deleted_at），库 ${dbPath}`);
-                }
-                if (op === 'backup-create' || op === 'backup-list') {
-                    const dir = join(dbPath, '..', 'backups');
-                    mkdirSync(dir, { recursive: true });
-                    if (op === 'backup-list') {
-                        const names = readdirSync(dir).filter((f) => f.endsWith('.db')).sort();
-                        return buildRecordReceipt(`备份${names.length}个${names.length ? '：' + names.slice(-5).join('、') : ''}`);
-                    }
-                    assertWritablePath(dbPath);
-                    closeBillDb(handle);
-                    const stamp = new Date().toISOString().slice(0, 19).replace(/[-:T]/g, '').replace(/(\d{8})(\d{6})/, '$1_$2');
-                    const name = `biscuit_${stamp}.db`;
-                    copyFileSync(dbPath, join(dir, name));
-                    try {
-                        copyFileSync(goalsPath, join(dir, name.replace('.db', '.goals.json')));
-                    }
-                    catch { /* goals 可空 */ }
-                    return buildRecordReceipt(`已备份：${name}`);
-                }
-                if (op === 'restore') {
-                    const name = params.name;
-                    const dir = join(dbPath, '..', 'backups');
-                    const target = typeof name === 'string' && name ? join(dir, basename(name)) : readdirSync(dir).filter((f) => f.endsWith('.db')).sort().map((f) => join(dir, f)).pop();
-                    if (!target || !existsSync(target))
-                        throw new BillFetchError('BILL_DB_MISSING', '无可用备份（先 backup-create）');
-                    assertWritablePath(dbPath);
-                    closeBillDb(handle);
-                    copyFileSync(target, dbPath);
-                    return buildRecordReceipt(`已恢复：${basename(target)}`);
-                }
-                if (op === 'import') {
-                    const file = params.file;
-                    if (typeof file !== 'string' || !file)
-                        fail(2, '导入须给 file（CSV 路径）');
-                    if (!existsSync(file))
-                        throw new BillFetchError('BILL_DB_MISSING', '导入文件不存在：' + file);
-                    const text = readFileSync(file, 'utf8');
-                    const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
-                    if (lines.length < 2)
-                        throw new BillFetchError('BILL_BAD_QUERY', '导入 CSV 无数据行');
-                    if (params['dry-run'] === true || params.dryRun === true) {
-                        return buildRecordReceipt(`导入预览：${lines.length - 1} 行（dry-run，未写入）`);
-                    }
-                    assertWritablePath(dbPath);
-                    let n = 0;
-                    for (const line of lines.slice(1)) {
-                        const cells = line.split(',').map((c) => c.trim());
-                        if (cells.length < 3)
-                            continue;
-                        try {
-                            const rec = { category: validateCategory(cells[2]), amount: Number(cells[1]), time: cells[0], account: cells[3] || '', ledger: cells[4] || '生活', currency: '人民币', note: cells[5] || '' };
-                            if (!Number.isFinite(rec.amount))
-                                continue;
-                            addBill(handle, { ...rec, amount: rec.amount });
-                            n++;
-                        }
-                        catch { /* 单行坏数据跳过，计数不含 */ }
-                    }
-                    return buildRecordReceipt(`已导入：${n} 笔（${basename(file)}）`);
-                }
-                fail(2, 'setup op 非法（期望 init/init-status/backup-create/backup-list/restore/import）');
+            case 'bill.help.lookup':
+                // #144：本命令由 `dispatchHelp` 在**开库之前**处理（只读页不建库）；走到这里说明 main 的路由被改坏了。
+                fail(1, '内部错误：bill.help.lookup 须走 dispatchHelp（开库之前）');
                 return null;
-            }
-            case 'bill.help.lookup': {
-                const all = buildHelpLookup();
-                const q = params.q === undefined ? undefined : String(params.q);
-                return buildHelpItems(all, q);
-            }
             default:
-                fail(3, '未知 bill key：' + key);
+                fail(3, '未知 bill 命令：' + key);
                 return null;
         }
     }
@@ -468,8 +182,7 @@ async function main() {
     const o = parseArgs(process.argv.slice(2));
     if (!o.key)
         fail(2, '用法：bill-cmd-read <bill.key> [--params JSON对象] [--html 输出路径] [--timeout 毫秒]');
-    const dbPath = preflight();
-    void dbPath;
+    const key = o.key;
     let params = {};
     if (o.params !== undefined) {
         try {
@@ -481,9 +194,22 @@ async function main() {
         if (typeof params !== 'object' || params === null || Array.isArray(params))
             fail(2, '--params 须为 JSON 对象');
     }
+    // #677：设置页的三个配置 key 在**预检与分派层之前**拦下——读写配置不该要求库目录已配，
+    // 也不进形状表、不进 HELP 与唤醒词计数。用上唯一出口那条规矩：stdout 一行 envelope。
+    if (isConfigKey(key)) {
+        process.stdout.write(runConfigKey(key, params) + '\n');
+        return;
+    }
+    // #706 · 配置体检（`bill.config.check`）：同样是设置页专用的只读命令，同样在预检之前拦下——
+    // 它要报的正是「库在哪、通不通」，不能先要求库目录已配。只读：不建目录、不写文件、不落默认配置。
+    if (isHealthCheckKey(key)) {
+        process.stdout.write(runHealthCheckKey(key) + '\n');
+        return;
+    }
+    preflight();
     let shape = null;
     try {
-        shape = billShapeFor(o.key);
+        shape = billShapeFor(key);
     }
     catch (e) {
         fail(3, e.message);
@@ -492,20 +218,33 @@ async function main() {
     const timer = setTimeout(() => { toast('cmd_read 超时 terminate（' + o.timeout + 'ms），已终止取数'); process.exit(4); }, o.timeout);
     timer.unref();
     let env = null;
+    let delivery;
     try {
-        const data = dispatch(o.key, params);
-        env = buildBillEnvelope(o.key, data);
-        if (o.html) {
-            // B4：--html 套模板输出完整收据页（section 片段经 CONTENT 注入模板，非片段直写）。
-            const section = renderEnvelopeHtml(env);
-            const full = fillTemplate(loadTemplate(templateFor(o.key)), section);
-            assertHtmlSize(full);
-            try {
-                writeFileSync(o.html, full, 'utf8');
-            }
-            catch (e) {
-                fail(5, 'HTML 写盘失败：' + o.html);
-            }
+        // #144：HELP 在开库之前分派（只读页不建库）；迁移过的命令（写入域两条＋查询域四条）先查注册表走能力目录；
+        // 其余照旧走 dispatch。
+        const help = key === 'bill.help.lookup' ? dispatchHelp(params) : null;
+        const abilityOut = help === null && REGISTRY[key] !== undefined ? runRegistered(key, params) : null;
+        const built = buildBillEnvelope(key, abilityOut ? abilityOut.data : (help ? help.data : dispatch(key, params)));
+        env = built;
+        // B4 既有语义：`--html` 套模板输出完整收据页（section 片段经 CONTENT 注入模板，非片段直写）。
+        // 迁移过的命令另有整页（采集页／回执页住 `src/write/`、查询列表页住 `src/query/`），不再套老模板。
+        const sectionHtml = () => {
+            if (abilityOut)
+                return abilityOut.html;
+            return fillTemplate(loadTemplate(templateFor(key)), renderEnvelopeHtml(built));
+        };
+        // B1 复核整改：体积门对准**实际交付的那串**——交给 `deliverHtml` 的字符串先过 `gatedHtml()`，
+        // 判的就是写下去的那一串（`delivery.bytes` 也照它算）。四条交付路都从这里过：迁移过的命令
+        // （回执页／采集页／查询列表页整页，由能力目录出）、未迁移的命令（section 片段经 CONTENT 注入模板）、
+        // HELP 缺省整页、HELP 速查表分节页。
+        const gatedHtml = (html) => { assertHtmlSize(html); return html; };
+        if (help?.deliver !== undefined) {
+            // 本命令的产物：缺省＝HELP 整页（共享 help 模板自带 html）；`mode:"lookup"`＝速查表分节页（由 envelope 渲染）。
+            const html = gatedHtml(help.deliver.html ?? sectionHtml());
+            delivery = deliverHtml({ explicit: o.html, target: help.deliver.target, html, reuseMs: help.deliver.reuseMs });
+        }
+        else if (o.html) {
+            delivery = deliverHtml({ explicit: o.html, html: gatedHtml(sectionHtml()) });
         }
     }
     catch (e) {
@@ -515,16 +254,20 @@ async function main() {
             fail(2, '口径失败：' + e.message);
         if (e instanceof BillRenderError)
             fail(5, '渲染失败：' + e.message);
-        if (e.message?.includes('SKILLS_DB_PATH'))
-            fail(1, e.message);
-        if (e.message?.includes('BILL_FORCE_PROD'))
+        if (e?.code && /^E[A-Z]+$/.test(String(e.code))) {
+            fail(5, '落盘失败：' + (e.message || String(e)));
+        }
+        // #726：配置面报错（测试缺隔离基座、配置文件读不出来）走「预检」那一档，与老线缺库目录同一档；
+        // 按 `base-link-core` 的 `ConfigError.code`（`CONFIG_*`）认，不拿报文文本去猜。
+        if (String(e.code ?? '').startsWith('CONFIG_'))
             fail(1, e.message);
         fail(4, '未知失败：' + (e.message || String(e)));
     }
     finally {
         clearTimeout(timer);
     }
-    process.stdout.write(JSON.stringify(env) + '\n');
+    // #83 口径的顶层追加：`delivery{mode,path,bytes}` 只追加，既有五字段一字不改、序不变。
+    process.stdout.write(JSON.stringify(delivery ? { ...env, delivery } : env) + '\n');
 }
 await main();
 //# sourceMappingURL=cmd_read.js.map