@lingda-ai/dsh-plugin-ledger 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/technical.md CHANGED
@@ -246,7 +246,8 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
246
246
 
247
247
  | 手段 | 覆盖 | 产出 |
248
248
  |---|---|---|
249
- | `node --test test/*.test.mjs` | 158 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR |
249
+ | `node --test test/*.test.mjs` | 191 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR、客户端产物形态 |
250
+ | `node scripts/build-client.mjs` | 产物形态 | 从源码重建 `lib/client.js`(零 import/export 的 loader 包) |
250
251
  | `scripts/bench.mjs --gate` | 热路径 + 内存 | 上表数字 |
251
252
  | `scripts/smoke-registry.mjs` | 插件装配契约 | 假 ctx 下工具注册/提供不抛 |
252
253
  | `scripts/smoke-dsh.mjs` | 宿主契约 | 右栏 tab、seat、事件形状 |
@@ -295,14 +296,15 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
295
296
  3. **内置价表带固定基准日** `2026-11-19`:厂商调价可写 `~/.dsh/ledger/pricing.json` 覆盖,
296
297
  无需改代码;写坏了会在面板顶部警示而不是静默回退。仍是"人工提供价格",不假装实时。
297
298
  4. **`private: true` 未改**:npm registry 未定。代码仓已在 Gitee。
298
- 5. **未真机验证五项**(`ctx.tools.register` 真注册、真进程全量派发、`ctx.provide` 冲突、
299
- 宿主是否真给 `ctx.slots`、插件侧 `workspaceFiles` 权限)——都需能 boot DSH 且带凭据的进程。
299
+ 5. **真机验证的现状**:`ctx.tools.register` 真注册、真进程全量派发、`ctx.provide` 无冲突、
300
+ `ctx.slots` 存在、`workspaceFiles` 可读,这五项在 0.1.4 装机后已全部被真实运行证伪/证实
301
+ (工具可用、右栏可挂、面板通道可读);而客户端入口形态**被证伪过一次**,见 12.5。
300
302
  6. **团队版零代码**:身份、上报、聚合、对账均未开工(有意为之,见商业计划书)。
301
303
 
302
304
  ---
303
305
 
304
306
 
305
- ## 12. 真机作为最终裁判:四处被单测掩盖的偏差
307
+ ## 12. 真机作为最终裁判:五处被单测掩盖的偏差
306
308
 
307
309
  第一次把插件装进真实宿主跑通之后,暴露了四个单测没有任何办法发现的问题。
308
310
  本节留档不是为了追责,而是因为**同一个错误模式还会再犯**:用自己假设的契约写测试,
@@ -329,6 +331,41 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
329
331
  页脚用 UTC 的 ISO(`07:35`),明细行用本地时间戳(`15:35`)。差 8 小时,用户只会以为数据错。
330
332
  新增 `formatLocalTime()`,一律本地时区——**同一个面板里只能有一套时间口径**。
331
333
 
334
+ **12.5 客户端入口不能是 ESM 源码。** 0.1.4 把 `lib/client.js` 作为未打包的 ESM 发布(`import` / `export` 俱在)。
335
+ 宿主把每个包的 client 入口**原样拼接**进一个 classic script,浏览器在第一句 `import` 处抛
336
+ `SyntaxError: Cannot use import statement outside a module`;`dsh-client-modules` 把它升级为致命错误,
337
+ Desktop 宿主启动阶段直接停住(用户看到"以安全模式重启")。
338
+
339
+ 这个错误单测完全看不出来:`test/client.test.mjs` 用 `import` 直接加载源码,全绿;而宿主从不 `import` 它,
340
+ 只是把文本拼进 `<script>`。**测试加载方式与实际加载方式不同,等于没测。**
341
+
342
+ 修法是把发布物变成宿主契约要求的 loader 形态,并让构建成为发布前不可跳过的一步:
343
+
344
+ - `lib/client.src.js`(源码,单测/脚本用)→ `scripts/build-client.mjs` → `lib/client.js`(产物,零 import/export);
345
+ - `id` 取安装后的包名(转发包要按自己的包名重建,见 `scripts/build-bundle.mjs`);
346
+ - React 只经 factory 的 `require("react")`;
347
+ - `test/client-bundle.test.mjs` 在 `node:vm` 里用假 `window.__ModuleLoader__` 加载产物,断言形态;
348
+ - `scripts/ci.sh` 校验产物与源同步(重建后 `git diff` 必须为空)。
349
+
350
+ **12.6 客户端插件必须导出 `inject`,而且它和 `dsh.client.inject` 不是一回事。**
351
+ 修完 12.5 之后再重启,宿主换了个死法:`cannot get property "sidebarRightTabs" without inject`。
352
+
353
+ 原因:cordis 的 `ctx` 是代理,**访问未声明依赖的服务属性会当场抛错**(不是返回 undefined),
354
+ 而这个抛错发生在 `apply()` 里,等于让宿主启动失败。`package.json` 的 `dsh.client.inject` 说的是
355
+ "先加载哪几个客户端包",`exports.inject` 说的是"这个插件依赖哪些服务"——前者写对了并不能免掉后者。
356
+
357
+ 正确写法(对齐 `dsh-bloub-mood` / `dsh-client-ui-skill-explorer` 的产物):
358
+
359
+ ```js
360
+ exports.inject = ['sidebarRightTabs'] // 硬依赖,缺了就别 apply
361
+ ctx.get('slots') // 可选服务:不受 inject 约束的通道
362
+ ```
363
+
364
+ 教训与 12.5 同源:**客户端半边的契约没有一条经过真机验证,而每一条的失败方式都是"宿主起不来"。**
365
+ 所以本轮把 apply 里所有未证实契约(tab 登记、close handler、seat 挂载、卸载)都包了 try/catch,
366
+ 默认姿态是"退化成一个没有面板的插件",而不是"把宿主带走";同时新增反证测试:
367
+ 把 `inject` 去掉,`apply` 必须抛 `without inject`——这条测试的存在意义就是让这个错在单测里炸。
368
+
332
369
  ### 工程侧的一条硬约束
333
370
 
334
371
  `dsh plugin --profile <p> add file:<path>` 是 pnpm 的 `file:` 依赖:**文件硬链接、目录复制**。