skill-bill 0.1.0 → 0.2.0

package/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: skill-bill
+description: "「饼干记账HELP」→bill.help.lookup 缺省落一份老技能同款 HELP 文件（7 域／74 场景，与卡路里同一套共享 help 模板）；唯一出口 bill-cmd-read。触发词：饼干记账 HELP、饼干记账帮助、查帮助、能做什么、记支出、记收入、拍账单、批量录入、记退款、记报销、报销到账、记借出、记借入、记收回、记偿还、记分期、记一笔、改记录、撤销、恢复、查今天、查昨天、查某天、查最近、查账单、查周、查月、查区间、查分类、查账户、查账本、搜备注、查标签、查欠款、查待报销、查分期、查账单详情、看月度、看年度、看总览、看周报、看分类、看账户、看账本、看结构、做统计、看对比、看双区间、看同比、看分类对比、看趋势、看分类趋势、看大额、看高频、看分布、看活跃、看洞察、看异常、看借贷、看报销、看分期、看退款、设定预算、设定目标、看预算、看目标、新增账户、改账户、账户转账、看账户汇总、买东西、吃饭、初始化、初始化状态、备份、恢复备份、导入"
+---
+
+# 饼干记账（bill）SKILL
+
+本地记账：记支出/收入、查今天/区间/分类/标签、看月度/对比/趋势、预算目标、账户转账、买东西/吃饭联动、初始化备份导入。唯一出口 `bill-cmd-read <bill.key>`，argv+JSON(stdout)+exit，非 0 走 stderr。写走 receipt（直通即真相）。
+
+## 快速开始
+
+```sh
+bill-cmd-read bill.help.lookup                      # 说「饼干记账help」就这一条：落一份 HELP 文件
+bill-cmd-read bill.record.today --params '{"date":"2026-09-06"}'
+bill-cmd-read bill.record.add --params '{"category":"餐饮/外卖/午餐","amount":-35,"note":"午饭"}'
+```
+
+## 口径
+
+- 分类：支出 L1 10 个 + 收入 L1 6 个（餐饮/居家/穿着/出行/玩乐/学习/健康/社交/宠物/其他）+ 借贷/分期/转账隔离；amount 符号即分类依据（支出负/收入正），不单设 type 列；至多 L1/L2/L3 三级，旧数据无 / 视为 L1。
+- 时间：YYYY-MM-DD HH:mm:ss（日期缺时分补 12:00:00）；查区间须 start/end 同给；搜备注空查询不返全量；#tag 精确匹配（#旅行计划不命中 #旅行）。
+- 软删：撤销=deleted_at 置 now，恢复=置 NULL（G7 契约）；转账=双笔 #转账（转出支出 + 转入收入，账本 转账，不入收支统计，余额含转账）。
+- 预算覆盖：同月同分类已存在默认拒绝（conflict），确认后加 --force 重跑；导入列映射 dry-run 先行；拍账单图片识别以外置为准。
+- 坏输入与缺失一律阻断（exit 2/4），不返空数组冒充正常；账单为 record.add 子功能（receipt 回执带复制 prompt）。
+
+## 联动速查（构建期注入，勿手改）
+
+<!-- HELP-AUTO-START -->
+| 唤醒词 | key | shape | 例 |
+|---|---|---|---|
+| 饼干记账 HELP | bill.help.lookup | list | `bill-cmd-read bill.help.lookup` |
+| 饼干记账帮助 | bill.help.lookup | list | `bill-cmd-read bill.help.lookup` |
+| 查帮助 | bill.help.lookup | list | `bill-cmd-read bill.help.lookup` |
+| 能做什么 | bill.help.lookup | list | `bill-cmd-read bill.help.lookup` |
+| 记支出 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"expense","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记收入 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"income","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 拍账单 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"photo","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 批量录入 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"batch","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记退款 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"refund","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记报销 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"reimburse","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 报销到账 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"reimburse-done","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记借出 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"lend","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记借入 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"borrow","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记收回 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"collect","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记偿还 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"repay","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记分期 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"kind":"installment","category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 记一笔 | bill.record.add | receipt | `bill-cmd-read bill.record.add --params '{"category":"餐饮","amount":-35,"note":"午饭"}'` |
+| 改记录 | bill.record.update | receipt | `bill-cmd-read bill.record.update --params '{"id":1}'` |
+| 撤销 | bill.record.update | receipt | `bill-cmd-read bill.record.update --params '{"op":"undo","id":1}'` |
+| 恢复 | bill.record.update | receipt | `bill-cmd-read bill.record.update --params '{"op":"restore","id":1}'` |
+| 查今天 | bill.record.today | list | `bill-cmd-read bill.record.today` |
+| 查昨天 | bill.record.today | list | `bill-cmd-read bill.record.today --params '{"date":"yesterday"}'` |
+| 查某天 | bill.record.today | list | `bill-cmd-read bill.record.today --params '{"date":"2026-09-06"}'` |
+| 查最近 | bill.record.today | list | `bill-cmd-read bill.record.today --params '{"recent":true}'` |
+| 查账单 | bill.record.today | list | `bill-cmd-read bill.record.today` |
+| 查周 | bill.record.range | list | `bill-cmd-read bill.record.range --params '{"range":"week"}'` |
+| 查月 | bill.record.range | list | `bill-cmd-read bill.record.range --params '{"range":"month"}'` |
+| 查区间 | bill.record.range | list | `bill-cmd-read bill.record.range --params '{"start":"2026-09-01","end":"2026-09-01"}'` |
+| 查分类 | bill.record.range | list | `bill-cmd-read bill.record.range --params '{"category":"餐饮"}'` |
+| 查账户 | bill.record.range | list | `bill-cmd-read bill.record.range --params '{"account":"支付宝"}'` |
+| 查账本 | bill.record.range | list | `bill-cmd-read bill.record.range --params '{"ledger":"生活"}'` |
+| 搜备注 | bill.record.search | list | `bill-cmd-read bill.record.search --params '{"q":"午饭"}'` |
+| 查标签 | bill.record.search | list | `bill-cmd-read bill.record.search --params '{"kind":"tag","tag":"旅行"}'` |
+| 查欠款 | bill.record.search | list | `bill-cmd-read bill.record.search --params '{"kind":"debt"}'` |
+| 查待报销 | bill.record.search | list | `bill-cmd-read bill.record.search --params '{"kind":"reimburse"}'` |
+| 查分期 | bill.record.search | list | `bill-cmd-read bill.record.search --params '{"kind":"installment"}'` |
+| 查账单详情 | bill.record.detail | detail | `bill-cmd-read bill.record.detail --params '{"id":1}'` |
+| 看月度 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"monthly"}'` |
+| 看年度 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"yearly"}'` |
+| 看总览 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"overview"}'` |
+| 看周报 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"week"}'` |
+| 看分类 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"category"}'` |
+| 看账户 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"account"}'` |
+| 看账本 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"ledger"}'` |
+| 看结构 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"structure"}'` |
+| 做统计 | bill.analysis.overview | stat | `bill-cmd-read bill.analysis.overview --params '{"kind":"stats"}'` |
+| 看对比 | bill.analysis.compare | analysis | `bill-cmd-read bill.analysis.compare --params '{"kind":"period"}'` |
+| 看双区间 | bill.analysis.compare | analysis | `bill-cmd-read bill.analysis.compare --params '{"kind":"range"}'` |
+| 看同比 | bill.analysis.compare | analysis | `bill-cmd-read bill.analysis.compare --params '{"kind":"yoy"}'` |
+| 看分类对比 | bill.analysis.compare | analysis | `bill-cmd-read bill.analysis.compare --params '{"kind":"category"}'` |
+| 看趋势 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"trend"}'` |
+| 看分类趋势 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"category"}'` |
+| 看大额 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"top"}'` |
+| 看高频 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"frequent"}'` |
+| 看分布 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"distribution"}'` |
+| 看活跃 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"activity"}'` |
+| 看洞察 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"insight"}'` |
+| 看异常 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"anomaly"}'` |
+| 看借贷 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"debt"}'` |
+| 看报销 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"reimburse"}'` |
+| 看分期 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"installment"}'` |
+| 看退款 | bill.analysis.trend | analysis | `bill-cmd-read bill.analysis.trend --params '{"kind":"refund"}'` |
+| 设定预算 | bill.goal.write | receipt | `bill-cmd-read bill.goal.write --params '{"op":"set-budget","amount":35}'` |
+| 设定目标 | bill.goal.write | receipt | `bill-cmd-read bill.goal.write --params '{"op":"set-saving","name":"招行卡","amount":35}'` |
+| 看预算 | bill.goal.query | list | `bill-cmd-read bill.goal.query --params '{"op":"budget"}'` |
+| 看目标 | bill.goal.query | list | `bill-cmd-read bill.goal.query --params '{"op":"saving"}'` |
+| 新增账户 | bill.account.write | receipt | `bill-cmd-read bill.account.write --params '{"op":"add","name":"招行卡"}'` |
+| 改账户 | bill.account.write | receipt | `bill-cmd-read bill.account.write --params '{"op":"update","name":"招行卡"}'` |
+| 账户转账 | bill.account.write | receipt | `bill-cmd-read bill.account.write --params '{"op":"transfer","amount":35,"from":"支付宝","to":"招行卡"}'` |
+| 看账户汇总 | bill.account.query | list | `bill-cmd-read bill.account.query` |
+| 买东西 | bill.link.submit | receipt | `bill-cmd-read bill.link.submit --params '{"scene":"purchase"}'` |
+| 吃饭 | bill.link.submit | receipt | `bill-cmd-read bill.link.submit --params '{"scene":"meal"}'` |
+| 初始化 | bill.setup.run | receipt | `bill-cmd-read bill.setup.run --params '{"op":"init"}'` |
+| 初始化状态 | bill.setup.run | receipt | `bill-cmd-read bill.setup.run --params '{"op":"init-status"}'` |
+| 备份 | bill.setup.run | receipt | `bill-cmd-read bill.setup.run --params '{"op":"backup-create"}'` |
+| 恢复备份 | bill.setup.run | receipt | `bill-cmd-read bill.setup.run --params '{"op":"restore"}'` |
+| 导入 | bill.setup.run | receipt | `bill-cmd-read bill.setup.run --params '{"op":"import","file":"bills.csv"}'` |
+
+相关场景：bill.account.query、bill.account.write、bill.analysis.compare、bill.analysis.overview、bill.analysis.trend、bill.goal.query、bill.goal.write、bill.help.lookup、bill.link.submit、bill.record.add、bill.record.detail、bill.record.range、bill.record.search、bill.record.today、bill.record.update、bill.setup.run（16 联动，key 字符串后续票落表时冻结）。
+<!-- HELP-AUTO-END -->
+
+## HELP 交付（说「饼干记账help」或「查帮助」走这里）
+
+- **缺省就是交付物**：`bill-cmd-read bill.help.lookup` **原样调用**即落一份能打开的 HELP 文件——`<SKILLS_DB_PATH>/biscuit_accountant_html/饼干记账_HELP_<YYYYMMDD_HHMMSS>.html`（7 域／74 场景，与卡路里同一套共享 help 模板）。stdout 的 `delivery.path` 是**绝对路径**，`delivery.bytes` 是文件字节数；回话就把这个路径给用户（回执即真相）。
+  **完成标准**：`delivery.path` 指向的文件真的存在，且大小＝`delivery.bytes`。
+- **要全量速查表才加参数**：`--params '{"mode":"lookup"}'` 出 77 条唤醒词速查表，落同目录 `饼干记账_速查表_<时间戳>.html`（与 HELP 文件分名，两份产物不撞车）；这一支同样吃下面的复用窗口。
+- **反复读不再涨目录（#245）**：同一主体**一天内只留一份**——24 小时内再读就**复用已有那份**（不新建、不改写；回执给的就是它）。要别的窗口给 `--params '{"reuseHours":3}'`（小时）；要**每次都要一份最新的**给 `{"reuseHours":0}`。窗口内若已有一份、而你刚改过 HELP 内容，那份旧产物**不会被自动刷新**（窗口语义如此）——真要新的就带 `reuseHours:0`。
+- **要现找才加参数**：`--params '{"q":"查今天"}'` 回命中条目（只出 JSON，不落盘；要落盘就给 `--html`）。`q` 与 `mode` 互斥、`mode` 只认 `lookup`，违反即 exit 2。
+- **`--html <路径>`＝显式落点**：逐字使用、覆盖写、缺父目录自动建（不参与同秒 `_N` 递补）；其它 15 条命令的 `--html` 语义不变（仍写收据页）。
+- **边界**：面板／侧栏的 HELP 入口不在本技能范围（属插件的桥／面板那条线）；不写固定名镜像（用户 Q10=A）。
+- 触发词总表见上「联动速查」构建期注入块（`<!-- HELP-AUTO-START/END -->`，由 `scripts/build-help.mjs` 重写，勿手改）。
+
+## 环境与出 scope
+
+- SKILLS_DB_PATH（必设，无默认值）+ BILL_FORCE_PROD 哨兵（非 tmp 写库须 opt-in），见 docs/env.md。
+- --html 套模板输出完整收据页（section 片段经 CONTENT 注入对应模板，非片段直写；超体积阻断）；`bill.help.lookup` 的 `--html` 改写到该键的产物（HELP 全页／速查页），语义见上「HELP 交付」节。
+- 出 scope：定时任务（老家零定时代码）、面板（二期单 MAP）、本技能外联动登记（combos.yaml 一律不碰，走后续票；link 跨技能仅复制 prompt）；真实数据禁迁，测试 tmp 隔离；Python 老家只读对照。

package/dist/.gen-inputs.json

@@ -0,0 +1,14 @@
+{
+  "version": 2,
+  "note": "饼干记账生成器输入的内容印记：每条记 {src, dist} 配对，由 `pnpm build` 调 `--stamp` 写入；`pnpm gen`／`gen:check` 按它判陈旧、按现场配对门判脱钩。",
+  "files": {
+    "query/commands.ts": {
+      "src": "3b0adbca90a6b756ae797ec9ff1c9fbd0972614b94708550acdb5ae156262011",
+      "dist": "9a8e4bd18e192f67b053b9328e3cf14b9442dae4a936c14f5d49db97e7e10889"
+    },
+    "record/commands.ts": {
+      "src": "e10e943942ea01803f0aa6b0f21b34bc2967a94a6e5c935b92d97838a506608b",
+      "dist": "c31d83861dc651df3ec6ee685b2c5b3640347b0adcc4f9c52b8e846056b492d8"
+    }
+  }
+}

package/dist/cli/cmd_read.js

@@ -2,12 +2,17 @@
 // 饼干记账唯一出口 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 { readFileSync, copyFileSync, readdirSync, existsSync, mkdirSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { BillFetchError, BillPolicyError, resolveDbPath, resolveDbDir, resolveGoalsPath, assertWritablePath, openBillDb, closeBillDb, fetchAll, listRange, addBill, loadGoals, saveGoals, } from '../fetch/index.js';
+import { resolveRange, parseOverviewKind, parseCompareKind, parseTrendKind, monthRange, 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, buildRecordReceipt, buildOverview, buildCompare, buildTrend, buildGoalQuery, buildAccountQuery, buildHelpItems, buildHelpIndex, buildHelpFileData, renderHelpFileHtml, HELP_FILE_STEM, LOOKUP_FILE_STEM, HELP_HTML_DIR_NAME, BillRenderError, } from '../render/index.js';
+import { deliverHtml } from '../output.js';
+import { helpReuseWindowOf } from 'base-paint/save-html';
 import { buildHelpLookup } from '../help/index.js';
+import { REGISTRY } from './registry.js';
+import { runRecordWrite } from '../record/index.js';
+import { runQueryRead } from '../query/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); }
@@ -21,33 +26,98 @@ function preflight() {
         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` 口子），本来不吃复用。 */
+const HELP_REUSE_STEMS = [HELP_FILE_STEM, LOOKUP_FILE_STEM];
+/** 本次交付吃不吃复用窗口 ⇒ 给出窗口毫秒数（不吃 = `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 (!HELP_REUSE_STEMS.includes(stem))
+        return undefined;
+    return windowOf(params);
 }
-function yesterdayStr() {
-    const d = new Date();
-    d.setDate(d.getDate() - 1);
-    return d.toISOString().slice(0, 10);
+/** 初始化状态：DB **文件存在**＝已初始化（照老 `render_help._is_initialized`）；
+ *  判定本身异常 ⇒ `false`＝横幅照显（fail-open，理由见 render/helpFile.ts 头注释）。 */
+function helpInitialized() {
+    try {
+        return existsSync(resolveDbPath());
+    }
+    catch {
+        return false;
+    }
 }
-function weekRange() {
+function dispatchHelp(params) {
+    const dbDir = resolveDbDir();
     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 = LOOKUP_FILE_STEM;
+        return {
+            data: { ...hits, mode: 'lookup' },
+            deliver: {
+                target: { dir: join(resolve(dbDir), HELP_HTML_DIR_NAME), stem },
+                reuseMs: windowForHelpDelivery(stem, params),
+            },
+        };
+    }
+    const html = renderHelpFileHtml(buildHelpFileData(now, { initialized: helpInitialized() }));
+    const stem = HELP_FILE_STEM;
+    return {
+        data: { ...buildHelpIndex(), mode: 'file', bytes: Buffer.byteLength(html, 'utf8') },
+        deliver: {
+            html,
+            target: { dir: join(resolve(dbDir), HELP_HTML_DIR_NAME), stem },
+            reuseMs: windowForHelpDelivery(stem, params),
+        },
+    };
 }
-// 十六键分发：读走 fetch 读，写走 fetch 写+policy 校验；未知键上游已拦，此处再拦一道。
+/** 迁移过的命令入口（写入域两条 ＋ 查询域四条）：查注册表命中即走能力目录，按 `kind` 静态分两支。
+ *  开库／关库与写前置守卫与老路同一套；读命令不碰写库守卫（照旧只读）。
+ *  这些命令的整页（采集页／回执页／查询列表页）住各自能力目录，
+ *  故 `dispatch` 的 switch 里**不再有**它们的 case（一个命令恰住一处）。 */
+function runRegistered(key, params) {
+    const spec = REGISTRY[key];
+    if (spec === undefined)
+        fail(3, '未知 bill 命令：' + key);
+    const dbPath = resolveDbPath();
+    if (spec.kind === 'write')
+        assertWritablePath(dbPath);
+    const handle = openBillDb(dbPath);
+    try {
+        if (handle.initialized)
+            note('记账 DB 已初始化：' + dbPath);
+        return spec.kind === 'write'
+            ? runRecordWrite(key, params, handle)
+            : runQueryRead(key, params, handle);
+    }
+    finally {
+        try {
+            closeBillDb(handle);
+        }
+        catch { /* ignore */ }
+    }
+}
+// 十六条命令分发：读走 fetch 读，写走 fetch 写+policy 校验；未知命令名上游已拦，此处再拦一道。
 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);
+    // 会改数据库的命令前置守卫（B6）：非 tmp 写库须 BILL_FORCE_PROD=1；查询命令不受影响。
+    // 记一笔／改记录已迁进能力目录（走上面的 `runRegistered`），守卫也跟着搬过去了。
     if (key === 'bill.goal.write')
         assertWritablePath(goalsPath);
     if (key === 'bill.account.write') {
@@ -59,102 +129,6 @@ function dispatch(key, params) {
         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;
@@ -430,13 +404,12 @@ function dispatch(key, params) {
                 fail(2, 'setup op 非法（期望 init/init-status/backup-create/backup-list/restore/import）');
                 return null;
             }
-            case 'bill.help.lookup': {
-                const all = buildHelpLookup();
-                const q = params.q === undefined ? undefined : String(params.q);
-                return buildHelpItems(all, q);
-            }
+            case 'bill.help.lookup':
+                // #144：本命令由 `dispatchHelp` 在**开库之前**处理（只读页不建库）；走到这里说明 main 的路由被改坏了。
+                fail(1, '内部错误：bill.help.lookup 须走 dispatchHelp（开库之前）');
+                return null;
             default:
-                fail(3, '未知 bill key：' + key);
+                fail(3, '未知 bill 命令：' + key);
                 return null;
         }
     }
@@ -468,6 +441,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 key = o.key;
     const dbPath = preflight();
     void dbPath;
     let params = {};
@@ -483,7 +457,7 @@ async function main() {
     }
     let shape = null;
     try {
-        shape = billShapeFor(o.key);
+        shape = billShapeFor(key);
     }
     catch (e) {
         fail(3, e.message);
@@ -492,20 +466,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/record/`、查询列表页住 `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,6 +502,9 @@ async function main() {
             fail(2, '口径失败：' + e.message);
         if (e instanceof BillRenderError)
             fail(5, '渲染失败：' + e.message);
+        if (e?.code && /^E[A-Z]+$/.test(String(e.code))) {
+            fail(5, '落盘失败：' + (e.message || String(e)));
+        }
         if (e.message?.includes('SKILLS_DB_PATH'))
             fail(1, e.message);
         if (e.message?.includes('BILL_FORCE_PROD'))
@@ -524,7 +514,8 @@ async function main() {
     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