@restregular/dsh-skill-center 0.2.0 → 0.2.2

package/README.md

@@ -1,4 +1,4 @@
-# dsh-skill-center · 技能中心
+# dsh-skill-center · 技能中心
 
 [![npm](https://img.shields.io/npm/v/@restregular/dsh-skill-center?color=cb3837&logo=npm)](https://www.npmjs.com/package/@restregular/dsh-skill-center)
 [![license](https://img.shields.io/npm/l/@restregular/dsh-skill-center?color=blue)](./LICENSE)
@@ -67,7 +67,7 @@ Then add the package to the profile's bundle list and restart:
 // <profile>/package.json
 {
   "dsh": { "profile": { "bundles": [/* … */ "@restregular/dsh-skill-center"] } },
-  "dependencies": { "@restregular/dsh-skill-center": "^0.1.4" }
+  "dependencies": { "@restregular/dsh-skill-center": "^0.2.2" }
 }
 ```
 
@@ -75,8 +75,51 @@ The package ships its own `cordis.patch.yml`, so no manual loader edit is requir
 host plugin (`id: skill-center`) and the client half. The sidebar row appears **below Plugins**,
 because the client registers `sidebar.panellist` with `order: 1`.
 
+> [!IMPORTANT]
+> The loader row's `name` **must equal the package name verbatim**
+> (`@restregular/dsh-skill-center`). `@deepseek-ai/dsh-client-modules` locates a row's
+> `package.json` by that name and compares it strictly (`nearestPackage`). With a bare
+> `dsh-skill-center` the host half still mounts, but the client half is dropped **silently**:
+> no sidebar row, `/plugins/@restregular/dsh-skill-center/client.js` returns `404`, and nothing is
+> logged. 0.2.1 fixed exactly this; 0.2.0 shipped the bare name.
+
+> [!IMPORTANT]
+> The client bundle must also call `__ModuleLoader__.load({ id: '@restregular/dsh-skill-center' })` —
+> **the package name, not the plugin id**. The browser module graph numbers rows by package name, and
+> `ClientModuleSystem.invalidate(id, rev)` (what the HMR `rebuilt` frame and `entries.reload` use)
+> deletes factory entries **by row id only**. A registration id that differs from the row id leaves
+> the stale factory in place, so the next bundle revision throws
+> `client-modules: duplicate factory registration … (bundle executed twice without invalidate?)`
+> and the whole web boot reports `1 entry did not activate`. 0.2.2 fixed this; 0.2.0/0.2.1 used the
+> bare plugin id. The bundle additionally skips registration when that id is already present, so a
+> double execution can no longer take the boot down.
+
 To uninstall: remove the bundle entry and the dependency, then restart.
 
+> [!WARNING]
+> Do not leave a bare-name junction/link for this package in the profile's `node_modules`
+> (e.g. `node_modules\dsh-skill-center` → the repo). Both the link and the scoped package register
+> the same plugin, which is exactly the two-sources situation behind the duplicate-registration
+> crash. Install the scoped package and nothing else.
+
+## Troubleshooting
+
+Nothing appears in the sidebar after install + restart? Check in this order:
+
+1. **Is the host half alive?** `http://127.0.0.1:19387/dsh-skill-center/api?op=ping` should answer
+   `{"ok":true,…}`. A `404` means the loader row never mounted — the package is not in the profile's
+   `dsh.profile.bundles`, or is not installed under the profile's `node_modules`.
+2. **Did the client half reach the browser module graph?**
+   `http://127.0.0.1:19387/dsh-skill-center/api?op=diagnose` — `client.inGraph` must be `true`.
+   `false` while `host.mounted` is `true` is the loader-row-name / package-name mismatch above.
+3. **Is the bundle served?** `http://127.0.0.1:19387/plugins/@restregular/dsh-skill-center/client.js`
+   should return JavaScript, not `404`.
+4. **Re-run the offline composition check** (no host restart needed):
+   `node verify-compose.mjs <profileDir>` — it now fails loudly on a loader row name that cannot be
+   resolved back to the package.
+5. `pnpm add` inside the profile is what makes the package resolvable; installing it elsewhere
+   (a global `npm i -g`, an unrelated directory) installs nothing the profile can compose.
+
 ## Usage
 
 1. Open a session (or stay on the home screen — see *Known limits*).
@@ -243,15 +286,51 @@ pnpm add @restregular/dsh-skill-center
 // <profile>/package.json
 {
   "dsh": { "profile": { "bundles": [/* … */ "@restregular/dsh-skill-center"] } },
-  "dependencies": { "@restregular/dsh-skill-center": "^0.1.4" }
+  "dependencies": { "@restregular/dsh-skill-center": "^0.2.2" }
 }
 ```
 
 包自带 `cordis.patch.yml`，**不需要**手改 loader：它会插入宿主半边（`id: skill-center`）与浏览器半边。
 侧栏那一行排在「插件」下方，因为客户端以 `order: 1` 注册 `sidebar.panellist`。
 
+> [!IMPORTANT]
+> patch 里那条 loader 行的 `name` **必须逐字等于包名**（`@restregular/dsh-skill-center`）。
+> 宿主 `@deepseek-ai/dsh-client-modules` 是按这个行名去定位该行的 `package.json` 并**严格比对**
+> `name` 的（`nearestPackage`）。写成裸名 `dsh-skill-center` 时：宿主半边照样挂得上，
+> 但浏览器半边会被**静默丢弃** —— 侧栏没有「技能中心」、`/plugins/@restregular/dsh-skill-center/client.js`
+> 返回 `404`，而且日志里一个字都没有。0.2.1 修的就是这个；0.2.0 发出去的是裸名。
+
+> [!IMPORTANT]
+> 客户端 bundle 还必须用**包名**注册：`__ModuleLoader__.load({ id: '@restregular/dsh-skill-center' })`，
+> 不能用插件 id `dsh-skill-center`。浏览器模块图是按包名给行编号的，而
+> `ClientModuleSystem.invalidate(id, rev)`（HMR 的 `rebuilt` 帧 → `entries.reload` 走的正是它）
+> **只按行 id** 删工厂表里的条目：注册 id 与行 id 不一致 → 旧工厂删不掉 → 下一版 bundle 一执行就
+> `client-modules: duplicate factory registration … (bundle executed twice without invalidate?)`，
+> 整条 web boot 变成「1 entry did not activate」并弹「应用无法启动或已意外停止」。
+> 0.2.2 修的就是这个。bundle 另外加了一道幂等保护：该 id 已在工厂表里就跳过注册，
+> 重复执行最多是空转，不会再打挂启动。
+
 卸载：删掉上面两处清单项，重启即可。
 
+> [!WARNING]
+> 不要在 profile 的 `node_modules` 里给这个包留裸名链接/junction
+> （例如 `node_modules\dsh-skill-center` → 本仓库）。链接和真正的 scoped 包会各自注册同一个插件，
+> 正好构成「同一插件两个来源」——也就是上面那个 duplicate registration 崩溃的现场。
+> 只装 scoped 包，别的都清掉。
+
+### 装完侧栏没出现？按顺序查这五步
+
+1. **宿主半边活着吗**：`http://127.0.0.1:19387/dsh-skill-center/api?op=ping` 应回 `{"ok":true,…}`。
+   回 `404` 说明 loader 行压根没挂上 —— 包不在 profile 的 `dsh.profile.bundles` 里，或者没装进
+   profile 的 `node_modules`。
+2. **浏览器半边进模块图了吗**：`…/api?op=diagnose` 里的 `client.inGraph` 必须是 `true`。
+   若 `host.mounted` 为 `true` 而它是 `false`，就是上面那个「行名 ≠ 包名」。
+3. **bundle 有没有被服务**：`http://127.0.0.1:19387/plugins/@restregular/dsh-skill-center/client.js`
+   应返回 JavaScript 而不是 `404`。
+4. **跑离线合成自检**（不用重启宿主）：`node verify-compose.mjs <profileDir>`，
+   现在它会因为「行名解析不回本包」直接 FAIL。
+5. `pnpm add` 必须**在 profile 目录里**执行；装到别处（全局 `npm i -g`、别的目录）profile 合成不到。
+
 ### 它怎么接进 Harness
 
 **宿主半边**（`lib/index.js`）挂载一条**仅回环**的 HTTP 路由 `/dsh-skill-center/api`：

package/client/client.js

@@ -6,11 +6,27 @@
  *      `order: 1` 使其排在 `plugins`(order 0)下方;
  *   2. `main`(keyed, root, key = "skill-center")— 中央区域的面板本体。
  *
+ * 注册 id **必须逐字等于包名**(`@restregular/dsh-skill-center`)。浏览器模块图是按
+ * 包名给行编号的,`ClientModuleSystem.invalidate`/`reload`(HMR 的 `rebuilt` 帧走的
+ * 就是它)只按**行 id** 清理工厂表:注册 id 与行 id 不一致时,旧工厂不会被删掉,
+ * 新版 bundle 一到就撞成
+ * `client-modules: duplicate factory registration ... (bundle executed twice without invalidate?)`,
+ * 于是整条 web boot 变成 "1 entry did not activate"。
+ *
  * 数据与写操作全部走宿主同源回环路由 `/dsh-skill-center/api`(见 ../lib/index.js)。
  * 样式只用宿主主题令牌 `--dsw-*`,不 import 任何 Harness Client 包。
  */
+const MODULE_ID = '@restregular/dsh-skill-center';
+
+/** 该 id 是否已经注册过工厂(宿主 facade 暴露 factories 表;取不到就当作没注册)。 */
+function alreadyRegistered() {
+  const factories = window.__ModuleLoader__?.factories;
+  return factories !== undefined && typeof factories.has === 'function' && factories.has(MODULE_ID);
+}
+
+if (!alreadyRegistered()) {
 window.__ModuleLoader__.load({
-  id: 'dsh-skill-center',
+  id: MODULE_ID,
   factory: (require) => {
     const React = require('react');
     const h = React.createElement;
@@ -765,3 +781,4 @@ window.__ModuleLoader__.load({
     return { apply, inject };
   },
 });
+}

package/cordis.patch.yml

@@ -1,7 +1,11 @@
 # dsh-skill-center bundle patch: inserts the host plugin (skill catalog API over
 # the loopback Web route /dsh-skill-center) and the client plugin (a 「技能中心」
 # row in the sidebar's global panel list plus its central page).
-# 纯 insert(id/name)可热挂载,免重启。
+#
+# `name` 必须逐字等于本包 package.json 的 name。宿主 @deepseek-ai/dsh-client-modules
+# 是按 **loader 行名 = 包名** 去定位 package.json 的(nearestPackage 严格比对 name):
+# 写成裸名 'dsh-skill-center' 时宿主半边照样挂得上,但客户端半边会被静默丢弃 ——
+# `/plugins/<包名>/client.js` 404、侧栏不出「技能中心」,而且没有任何报错。
 - insert:
     - id: skill-center
-      name: 'dsh-skill-center'
+      name: '@restregular/dsh-skill-center'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@restregular/dsh-skill-center",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "技能中心 — DeepSeek Harness 技能管理面板：浏览当前会话可见的所有技能、查看正文、开关模型/用户调用、新建与删除。 · Skill Center for DeepSeek Harness: browse and manage the skills visible to the current session.",
   "type": "module",
   "main": "lib/index.js",