@lingda-ai/dsh-plugin-ledger 0.1.5 → 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,7 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
246
246
 
247
247
  | 手段 | 覆盖 | 产出 |
248
248
  |---|---|---|
249
- | `node --test test/*.test.mjs` | 188 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR、客户端产物形态 |
249
+ | `node --test test/*.test.mjs` | 191 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR、客户端产物形态 |
250
250
  | `node scripts/build-client.mjs` | 产物形态 | 从源码重建 `lib/client.js`(零 import/export 的 loader 包) |
251
251
  | `scripts/bench.mjs --gate` | 热路径 + 内存 | 上表数字 |
252
252
  | `scripts/smoke-registry.mjs` | 插件装配契约 | 假 ctx 下工具注册/提供不抛 |
@@ -347,6 +347,25 @@ Desktop 宿主启动阶段直接停住(用户看到"以安全模式重启")
347
347
  - `test/client-bundle.test.mjs` 在 `node:vm` 里用假 `window.__ModuleLoader__` 加载产物,断言形态;
348
348
  - `scripts/ci.sh` 校验产物与源同步(重建后 `git diff` 必须为空)。
349
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
+
350
369
  ### 工程侧的一条硬约束
351
370
 
352
371
  `dsh plugin --profile <p> add file:<path>` 是 pnpm 的 `file:` 依赖:**文件硬链接、目录复制**。
package/lib/client.js CHANGED
@@ -844,6 +844,38 @@ window.__ModuleLoader__.load({
844
844
  /** tab 类型判别串,`openTab('ledger.cost', …)` 用的就是它。 */
845
845
  const LEDGER_KIND = 'ledger.cost'
846
846
 
847
+ /**
848
+ * 硬依赖:没有右栏 tab 服务,这个插件什么都不用做。
849
+ *
850
+ * 这条**必须声明**。cordis 的 ctx 是代理:访问未声明的服务属性会直接抛
851
+ * `cannot get property "sidebarRightTabs" without inject`,而且是在 apply 里抛,
852
+ * 等同于让宿主启动失败(0.1.5 重启即崩就是这么来的——之前只写了 package.json 的
853
+ * dsh.client.inject,那是"先加载哪个包",不是"这个插件依赖哪个服务",两回事)。
854
+ */
855
+ const inject = ['sidebarRightTabs']
856
+
857
+ /**
858
+ * 取可选服务。不能写成 `ctx.xxx`——没在 inject 里声明的服务,属性访问会抛。
859
+ * 宿主提供了 `ctx.get(name)` 这条不受 inject 约束的通道;Node 侧单测的假 ctx
860
+ * 没有 get,退回普通属性读。
861
+ * @param {any} ctx
862
+ * @param {string} name
863
+ */
864
+ function optionalService(ctx, name) {
865
+ if (typeof ctx?.get === 'function') {
866
+ try {
867
+ return ctx.get(name) ?? null
868
+ } catch {
869
+ return null
870
+ }
871
+ }
872
+ try {
873
+ return ctx?.[name] ?? null
874
+ } catch {
875
+ return null
876
+ }
877
+ }
878
+
847
879
  /** 面板用到的 seat 名,抽出来避免字符串散落。 */
848
880
  const SEAT_BODY = 'sidebar.right.pane.tab'
849
881
  const SEAT_TITLE = 'sidebar.right.pane.tab.title'
@@ -889,7 +921,7 @@ window.__ModuleLoader__.load({
889
921
  function createFetchView(ctx) {
890
922
  return async function fetchView(sessionId, opts = {}) {
891
923
  if (typeof sessionId !== 'string' || sessionId.length === 0) return null
892
- const files = ctx?.remote?.workspaceFiles
924
+ const files = optionalService(ctx, 'remote')?.workspaceFiles
893
925
  if (!files || typeof files.stat !== 'function' || typeof files.read !== 'function') {
894
926
  return { error: '宿主未提供 workspaceFiles 通道' }
895
927
  }
@@ -980,16 +1012,30 @@ window.__ModuleLoader__.load({
980
1012
  keepMounted: true,
981
1013
  }
982
1014
 
983
- const disposeTab = tabs.register(definition)
984
- const disposeClose =
985
- typeof ctx.sidebarRight?.registerCloseHandler === 'function'
986
- ? ctx.sidebarRight.registerCloseHandler(LEDGER_KIND, () => {})
987
- : null
1015
+ // 客户端契约里除 sidebarRightTabs 之外的部分都没被真机证实过。
1016
+ // 这是一个 UI 插件:任何一处契约偏差都应该退化成"没有面板",而不是让宿主起不来。
1017
+ let disposeTab = null
1018
+ try {
1019
+ disposeTab = tabs.register(definition)
1020
+ } catch (error) {
1021
+ console.warn('[ledger] 右栏 tab 登记失败,面板不出现(宿主其它功能不受影响):', error)
1022
+ return
1023
+ }
1024
+
1025
+ const sidebarRight = optionalService(ctx, 'sidebarRight')
1026
+ let disposeClose = null
1027
+ if (typeof sidebarRight?.registerCloseHandler === 'function') {
1028
+ try {
1029
+ disposeClose = sidebarRight.registerCloseHandler(LEDGER_KIND, () => {})
1030
+ } catch (error) {
1031
+ console.warn('[ledger] registerCloseHandler 失败:', error)
1032
+ }
1033
+ }
988
1034
 
989
1035
  // 正文与标题:宿主把 seat 声明在 sidebar-right 里,先 inject 再 register
990
1036
  let disposeBody = null
991
1037
  let disposeTitle = null
992
- const slots = ctx.slots
1038
+ const slots = optionalService(ctx, 'slots')
993
1039
  if (typeof slots?.inject === 'function' && typeof slots.register === 'function') {
994
1040
  let React = null
995
1041
  try {
@@ -998,21 +1044,29 @@ window.__ModuleLoader__.load({
998
1044
  React = null // 宿主没给 React:保持无正文的降级态
999
1045
  }
1000
1046
  if (React !== null) {
1001
- const fetchView = createFetchView(ctx)
1002
- disposeBody = slots.inject(SEAT_BODY, () =>
1003
- slots.register({ name: SEAT_BODY, key: LEDGER_ID }, makeLedgerBody(React, fetchView)),
1004
- )
1005
- disposeTitle = slots.inject(SEAT_TITLE, () =>
1006
- slots.register({ name: SEAT_TITLE, key: LEDGER_ID }, makeLedgerTitle(React)),
1007
- )
1047
+ try {
1048
+ const fetchView = createFetchView(ctx)
1049
+ disposeBody = slots.inject(SEAT_BODY, () =>
1050
+ slots.register({ name: SEAT_BODY, key: LEDGER_ID }, makeLedgerBody(React, fetchView)),
1051
+ )
1052
+ disposeTitle = slots.inject(SEAT_TITLE, () =>
1053
+ slots.register({ name: SEAT_TITLE, key: LEDGER_ID }, makeLedgerTitle(React)),
1054
+ )
1055
+ } catch (error) {
1056
+ // seat 名对不上、权限不足、host 版本差异:只丢面板正文,tab 仍在
1057
+ console.warn('[ledger] 面板正文挂载失败(只剩 tab 标题):', error)
1058
+ }
1008
1059
  }
1009
1060
  }
1010
1061
 
1011
1062
  const cleanup = () => {
1012
- disposeTitle?.()
1013
- disposeBody?.()
1014
- disposeClose?.()
1015
- disposeTab()
1063
+ for (const dispose of [disposeTitle, disposeBody, disposeClose, disposeTab]) {
1064
+ try {
1065
+ dispose?.()
1066
+ } catch {
1067
+ // 卸载阶段的异常同样不能冒泡
1068
+ }
1069
+ }
1016
1070
  }
1017
1071
  if (typeof ctx.effect === 'function') ctx.effect(() => cleanup)
1018
1072
  else ctx.on('dispose', cleanup)
@@ -1039,6 +1093,9 @@ window.__ModuleLoader__.load({
1039
1093
  __setReactLoader(() => require("react"));
1040
1094
 
1041
1095
  exports.apply = apply;
1096
+ // 硬依赖必须跟着产物一起导出:cordis 靠它判断"什么时候允许 apply",
1097
+ // 漏了就会在 apply 里抛 cannot get property "..." without inject,把宿主启动带崩。
1098
+ exports.inject = inject;
1042
1099
  return module.exports;
1043
1100
  },
1044
1101
  });
package/lib/client.src.js CHANGED
@@ -43,6 +43,38 @@ const LEDGER_ID = '@lingda-ai/ledger'
43
43
  /** tab 类型判别串,`openTab('ledger.cost', …)` 用的就是它。 */
44
44
  const LEDGER_KIND = 'ledger.cost'
45
45
 
46
+ /**
47
+ * 硬依赖:没有右栏 tab 服务,这个插件什么都不用做。
48
+ *
49
+ * 这条**必须声明**。cordis 的 ctx 是代理:访问未声明的服务属性会直接抛
50
+ * `cannot get property "sidebarRightTabs" without inject`,而且是在 apply 里抛,
51
+ * 等同于让宿主启动失败(0.1.5 重启即崩就是这么来的——之前只写了 package.json 的
52
+ * dsh.client.inject,那是"先加载哪个包",不是"这个插件依赖哪个服务",两回事)。
53
+ */
54
+ export const inject = ['sidebarRightTabs']
55
+
56
+ /**
57
+ * 取可选服务。不能写成 `ctx.xxx`——没在 inject 里声明的服务,属性访问会抛。
58
+ * 宿主提供了 `ctx.get(name)` 这条不受 inject 约束的通道;Node 侧单测的假 ctx
59
+ * 没有 get,退回普通属性读。
60
+ * @param {any} ctx
61
+ * @param {string} name
62
+ */
63
+ function optionalService(ctx, name) {
64
+ if (typeof ctx?.get === 'function') {
65
+ try {
66
+ return ctx.get(name) ?? null
67
+ } catch {
68
+ return null
69
+ }
70
+ }
71
+ try {
72
+ return ctx?.[name] ?? null
73
+ } catch {
74
+ return null
75
+ }
76
+ }
77
+
46
78
  /** 面板用到的 seat 名,抽出来避免字符串散落。 */
47
79
  const SEAT_BODY = 'sidebar.right.pane.tab'
48
80
  const SEAT_TITLE = 'sidebar.right.pane.tab.title'
@@ -102,7 +134,7 @@ import {
102
134
  export function createFetchView(ctx) {
103
135
  return async function fetchView(sessionId, opts = {}) {
104
136
  if (typeof sessionId !== 'string' || sessionId.length === 0) return null
105
- const files = ctx?.remote?.workspaceFiles
137
+ const files = optionalService(ctx, 'remote')?.workspaceFiles
106
138
  if (!files || typeof files.stat !== 'function' || typeof files.read !== 'function') {
107
139
  return { error: '宿主未提供 workspaceFiles 通道' }
108
140
  }
@@ -193,16 +225,30 @@ export async function apply(ctx) {
193
225
  keepMounted: true,
194
226
  }
195
227
 
196
- const disposeTab = tabs.register(definition)
197
- const disposeClose =
198
- typeof ctx.sidebarRight?.registerCloseHandler === 'function'
199
- ? ctx.sidebarRight.registerCloseHandler(LEDGER_KIND, () => {})
200
- : null
228
+ // 客户端契约里除 sidebarRightTabs 之外的部分都没被真机证实过。
229
+ // 这是一个 UI 插件:任何一处契约偏差都应该退化成"没有面板",而不是让宿主起不来。
230
+ let disposeTab = null
231
+ try {
232
+ disposeTab = tabs.register(definition)
233
+ } catch (error) {
234
+ console.warn('[ledger] 右栏 tab 登记失败,面板不出现(宿主其它功能不受影响):', error)
235
+ return
236
+ }
237
+
238
+ const sidebarRight = optionalService(ctx, 'sidebarRight')
239
+ let disposeClose = null
240
+ if (typeof sidebarRight?.registerCloseHandler === 'function') {
241
+ try {
242
+ disposeClose = sidebarRight.registerCloseHandler(LEDGER_KIND, () => {})
243
+ } catch (error) {
244
+ console.warn('[ledger] registerCloseHandler 失败:', error)
245
+ }
246
+ }
201
247
 
202
248
  // 正文与标题:宿主把 seat 声明在 sidebar-right 里,先 inject 再 register
203
249
  let disposeBody = null
204
250
  let disposeTitle = null
205
- const slots = ctx.slots
251
+ const slots = optionalService(ctx, 'slots')
206
252
  if (typeof slots?.inject === 'function' && typeof slots.register === 'function') {
207
253
  let React = null
208
254
  try {
@@ -211,21 +257,29 @@ export async function apply(ctx) {
211
257
  React = null // 宿主没给 React:保持无正文的降级态
212
258
  }
213
259
  if (React !== null) {
214
- const fetchView = createFetchView(ctx)
215
- disposeBody = slots.inject(SEAT_BODY, () =>
216
- slots.register({ name: SEAT_BODY, key: LEDGER_ID }, makeLedgerBody(React, fetchView)),
217
- )
218
- disposeTitle = slots.inject(SEAT_TITLE, () =>
219
- slots.register({ name: SEAT_TITLE, key: LEDGER_ID }, makeLedgerTitle(React)),
220
- )
260
+ try {
261
+ const fetchView = createFetchView(ctx)
262
+ disposeBody = slots.inject(SEAT_BODY, () =>
263
+ slots.register({ name: SEAT_BODY, key: LEDGER_ID }, makeLedgerBody(React, fetchView)),
264
+ )
265
+ disposeTitle = slots.inject(SEAT_TITLE, () =>
266
+ slots.register({ name: SEAT_TITLE, key: LEDGER_ID }, makeLedgerTitle(React)),
267
+ )
268
+ } catch (error) {
269
+ // seat 名对不上、权限不足、host 版本差异:只丢面板正文,tab 仍在
270
+ console.warn('[ledger] 面板正文挂载失败(只剩 tab 标题):', error)
271
+ }
221
272
  }
222
273
  }
223
274
 
224
275
  const cleanup = () => {
225
- disposeTitle?.()
226
- disposeBody?.()
227
- disposeClose?.()
228
- disposeTab()
276
+ for (const dispose of [disposeTitle, disposeBody, disposeClose, disposeTab]) {
277
+ try {
278
+ dispose?.()
279
+ } catch {
280
+ // 卸载阶段的异常同样不能冒泡
281
+ }
282
+ }
229
283
  }
230
284
  if (typeof ctx.effect === 'function') ctx.effect(() => cleanup)
231
285
  else ctx.on('dispose', cleanup)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lingda-ai/dsh-plugin-ledger",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "description": "DSH 插件搜索入口:运行时账本(成本/用量观测)。自包含单包,不依赖其他 npm 包,便于从镜像源安装。",
5
5
  "license": "Apache-2.0",
6
6
  "keywords": [