@dsh-workbench/module-tools 0.1.14 → 0.1.16

package/template/scripts/smoke.mjs.tpl

@@ -1,9 +1,12 @@
-// 模块包的接线自检：把 client.js 当成浏览器里的加载器那样跑一遍。
+// 模块包的接线自检：把 client.js 当成浏览器里的加载器那样跑一遍，再把宿主产物当 ESM 跑一遍。
 //
 // 为什么值得有：宿主侧挂没挂上，curl /panels 就能看见；浏览器侧挂没挂上，过去只能靠"刷个页面看看"。
 // 这个脚本复刻 dsh 加载器的**契约**（`window.__ModuleLoader__.load({ id, factory })` + `factory(require)`），
 // 于是"模块注册的卡片到底进没进外壳"变成一条机器判据，而不再是人的眼睛。
 //
+// ★ 这份脚本只验**形状**：它认不出成员名、也不认识你的数据源，所以换数据源、换卡片内容都不用改它。
+//   你自己的那条读该不该跑通，属于 `?wbMock=1` 三档夹具与你自己 vitest 的事。
+//
 // 负例在最后一段：服务不在的时候必须**报出来**，不许静默通过 —— 静默的模块是最难查的那种坏。
 
 const PLUGIN_ID = '__NAME__';
@@ -19,9 +22,45 @@ function check(name, ok, detail) {
   console.log(`❌ ${name}${detail === undefined ? '' : ` —— ${detail}`}`);
 }
 
+/**
+ * 什么属性都拿得到、什么调用都返回自己的替身 —— 这样"模块用了 kit 的哪个成员"就不再是
+ * 这份脚本要知道的事（`check:cards` 用的是同一招）。真红只留给模块自己的代码。
+ */
+function anyStub(path = 'stub') {
+  const target = function () {
+    return anyStub(`${path}()`);
+  };
+  return new Proxy(target, {
+    get(_target, key) {
+      if (key === Symbol.toPrimitive) return () => 0;
+      if (key === Symbol.iterator) return function* () {};
+      if (key === 'then') return undefined;
+      if (key === 'length') return 0;
+      if (key === 'toString') return () => path;
+      return anyStub(`${path}.${String(key)}`);
+    },
+    apply() {
+      return anyStub(`${path}()`);
+    },
+  });
+}
+
+/** 外壳 kit 的替身：**三个桶都必须在** —— 卡片是在模块顶层解构 kit 的，少一个桶是 import 那一刻就抛。 */
+function fakeKit() {
+  return {
+    hooks: new Proxy({}, { get: () => () => anyStub('hook') }),
+    components: new Proxy({}, { get: () => () => null }),
+    api: new Proxy({}, { get: () => () => anyStub('api') }),
+    lib: anyStub('lib'),
+  };
+}
+
 function moduleRequire(name) {
-  if (name === 'react') return { createElement: () => null };
-  if (name === '@dsh-workbench/core/client') return { kit: { components: { Card: () => null } } };
+  if (name === 'react') {
+    // 必须是**真的元素对象**：返回 null 的话，"卡片画得出来"这类断言会永远假红。
+    return { createElement: (type, props, ...children) => ({ type, props: props ?? {}, children }) };
+  }
+  if (name === '@dsh-workbench/core/client') return { kit: fakeKit() };
   throw new Error(`模块包不该 require ${JSON.stringify(name)}：模块表里只有外壳的 seed 词与外部声明`);
 }
 
@@ -71,7 +110,25 @@ pluginExports.apply(ctx);
 check('卡片真的注册进了外壳', faces.length === 1, `注册了 ${faces.length} 个`);
 check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.manifest.id === UNIT_ID, faces[0]?.manifest.id);
 check('卡片是个能画的组件', typeof faces[0]?.card === 'function');
-check('卡片自己带标题与顺序（外壳的看板据此排）', faces[0]?.manifest.card?.order === 90);
+check(
+  '卡片自己带标题与顺序（外壳的看板据此排）',
+  typeof faces[0]?.manifest.card?.titleKey === 'string' &&
+    faces[0].manifest.card.titleKey !== '' &&
+    typeof faces[0]?.manifest.card?.order === 'number',
+  JSON.stringify(faces[0]?.manifest.card),
+);
+check(
+  '卡片在空数据下也画得出来（不许抛）',
+  (() => {
+    try {
+      return (
+        faces[0].card({ world: { current: {} }, refreshToken: 0, onRefresh: () => {}, t: (key) => key }) != null
+      );
+    } catch {
+      return false;
+    }
+  })(),
+);
 
 const warnings = [];
 const realWarn = console.warn;
@@ -90,5 +147,48 @@ check(
   warnings.join(' | '),
 );
 
+// ── 宿主产物：面注册得对不对 ──────────────────────────────────────────────
+const hostExports = await import(new URL('../dist/host.js', import.meta.url).href);
+check('宿主产物导出了 apply', typeof hostExports.apply === 'function');
+check(
+  '宿主产物也注入 workbenchUnits',
+  Array.isArray(hostExports.inject) && hostExports.inject.includes('workbenchUnits'),
+);
+
+const hostFaces = [];
+hostExports.apply({
+  get: (name) =>
+    name === 'workbenchUnits'
+      ? {
+          register(face) {
+            hostFaces.push(face);
+            return () => {};
+          },
+        }
+      : undefined,
+  effect: (fn) => {
+    fn();
+  },
+  logger: { warn: () => {} },
+});
+
+check('宿主面注册进了外壳', hostFaces.length === 1, `注册了 ${hostFaces.length} 个`);
+// 给一份最小 deps：宿主面的 `mount(deps)` 通常要 `deps.ctx.get('shell')` 之类，
+// 不给 deps 的话**任何真的用了 `mount(deps)` 的模块**都会在这里崩 —— 而那不是模块的错。
+let mounted = {};
+try {
+  mounted = hostFaces[0]?.mount({ ctx: { get: () => undefined }, logger: { warn: () => {} } }) ?? {};
+} catch (error) {
+  failures.push(`宿主面的 mount(deps) 抛了：${error.message}`);
+}
+
+const routes = mounted.routes ?? {};
+const strays = Object.keys(routes).filter((key) => key !== UNIT_ID && !key.startsWith(`${UNIT_ID}/`));
+check(`每条路由都住在自己那一格（${UNIT_ID} 或 ${UNIT_ID}/…）`, strays.length === 0, strays.join(', '));
+check(
+  'registerTools() 交得出一份清单（这份模块没有工具时是空数组）',
+  Array.isArray(mounted.registerTools?.()),
+);
+
 console.log(`\n${failures.length === 0 ? '模块自检通过' : `${failures.length} 条没过`}`);
 if (failures.length > 0) process.exit(1);

package/template-diy/README.md.tpl

@@ -0,0 +1,282 @@
+# __NAME__
+
+`__UNIT__` 模块：一个独立的 dsh 插件包，只认外壳的服务名，不认识外壳源码。
+
+这份是 **DIY 模板**（`--template diy`）生成的骨架：一张**读当前项目目录的只读卡**，
+数据从宿主侧**真读**一个目录算出来（`node:fs`），不是一个写死的样板。
+
+```bash
+dsh-wb-module init <unit> --dir <目录> --template diy   # 生成这份骨架（默认模板是没有数据源的空壳）
+dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
+dsh-wb-module check     # 十条判据：契约 / 产物边界 / 源码边界 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳
+dsh-wb-module check --only cards   # 十条可以单跑
+```
+
+包自带的四个脚本（`check` 的契约判据要求它们都在）：
+
+```bash
+pnpm build        # 构建产物
+pnpm typecheck    # tsc --noEmit
+pnpm test         # vitest：路由真读数 + 卡片五态 + 三种夹具
+pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 调一次 <unit>/overview 看它真读盘
+```
+
+## 需求底稿（做之前填，做完对着它验收）
+
+三张表既是**要问清的需求**，也是**最后的验收单** —— 表里每一格都要能在界面上见过或点过。
+**空着的格就是还没定的事**，别带着空格往下做：落点是同目录的 `design.json`
+（`dsh-wb-module design check` 会把空格一格一格列出来），**下面标了 start/end 的那一段就是由它生成的**
+—— 要改三张表就改 `design.json`，再 `dsh-wb-module design render`；手改那一段会被 next 一次 check 判红。
+所以下次他说"改一下"不用从头问。
+
+怎么问、怎么填：指引 `SKILL.md` 的七步 · `DESIGN.md`（判域 / 两条分工 / 三张表）·
+`STEPS.md`（每步问什么、什么时候算做完）· `PANEL.md` · `TOOLS.md` · `LINKAGE.md`。
+
+<!-- dsh-wb:design:start -->
+### 表 1 面板：他看什么、他能自己配什么
+
+| 这一格 | 一眼能得出什么结论 | 点一下可以去哪 |
+|---|---|---|
+| 这个目录占了多少空间 | 该不该清、谁在占 | （本骨架没有外链；要加就把目标写这儿） |
+
+| 能自己配的 | 管什么 | 默认是什么 | 可选值从哪来 | 选错了会怎样 |
+|---|---|---|---|---|
+| 列几个最大的文件 | 明细长度 | `5` | `1..50` | 夹回范围内，不报错 |
+
+状态矩阵（每种状态：他看到什么 / 他能做什么 / agent 能接着做什么）——
+图号对着下面「卡片画哪五态」那一节：
+
+| # | 状态 | 他看到什么 | 他能做什么 | agent 能接着做什么 |
+|---|---|---|---|---|
+| A | 待机（没选项目） | 「先打开一个项目」，不发请求 | 去左栏开一个项目 | 说清"要先有项目" |
+| B | 加载 | 「正在读目录」 | 等 | —— |
+| C | 就绪 | 路径 + N 文件 / M 目录 / 总字节 + 最大的几个 | 刷新 | 读一次这一格（联动见表 3） |
+| D | 就绪但空 | 「这个目录是空的」 | 换一个目录 | 同上 |
+| E | 读不到 | 读不到这个目录 + 宿主的原话 | 重试 / 改路径 | 同上 |
+
+### 表 2 agent：他能替用户做什么、哪几件要点头
+
+| 能力 | 一句话 | 传什么 / 拿回什么（贴真实调用与返回） | 要点头吗 | 点头时他看到的"会发生什么" |
+|---|---|---|---|---|
+| （这份骨架故意没有能力：`manifest.tools` 是空的。要加就照这张表填，只读的不点头、动东西的要点头） | | | | |
+
+### 表 3 联动：agent 动完，这个模块哪一格变
+
+| 谁在动 | 面板什么时候变 | 哪一格变（投影 + 最窄那个参数） | 用户看到什么 |
+|---|---|---|---|
+| agent 读一次这一格 | 读完立刻 | 本单元那条只读投影（`__UNIT__/overview`），只带这个目录 | 那一格变成 agent 看到的那份数 |
+| agent 只预览 / 只说了句话 | 不动 | —— | 面板没变 |
+| 用户自己按刷新 | 立刻 | 同上 | 转一下，然后是新值 |
+
+### 数据源探明记录
+
+`opencli` 只是**侦察兵**：探明之后固化成**一条**读，日常只走这一条
+（这条就是 `src/host.ts` 里那个数据源）。改数据源时先改这张表，再改代码。
+
+| 项 | 值（照抄，别转述） |
+|---|---|
+| 哪条读（命令 / URL） | 本机目录本身：`readdirSync(path)` + `statSync`（不走网络、不要凭据） |
+| 参数（缺省 / 范围 / 上限） | `path` 必填（卡片给当前项目）；`limit` 默认 `5`，夹在 `1..50` |
+| 凭据从哪来 | 不需要 |
+| 没登录 / 凭据过期时是什么样 | 不适用（本机读盘，没有登录这回事） |
+| 超时 / 连不上时是什么样 | 路径不存在 / 没权限 / 不是目录 → HTTP 200 + `ok:false`，码 `overview-unreadable` |
+| 当初探明用的那次调用（原文） | `node -e "require('node:fs').readdirSync(process.cwd())"` |
+
+<!-- dsh-wb:design:end -->
+
+## 生成出来的形状
+
+| 文件 | 是什么 |
+|---|---|
+| `package.json` | 自述清单：`dsh.workbench.unit` = `__UNIT__`、两个面（`src/host.ts` / `src/client.tsx`）、四个脚本、peer 下限 |
+| `cordis.patch.yml` | 插进 dsh 组合的补丁 |
+| `src/host.ts` | 宿主面：`readOverview()`（真读目录）+ 一条只读路由 `<unit>/overview` |
+| `src/client.tsx` | 卡片：`Card` 壳 + 五态（待机 / 加载 / 就绪 / 出错，其中"就绪但空"单列一态）+ `?wbMock=1` 夹具 |
+| `src/messages.ts` | 卡片那几句文案（zh / en） |
+| `src/plugin.test.ts` | 面注册 + 路由真读 + 五态 + 三种夹具的断言 |
+| `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、路由真读没真读 |
+| `tsconfig.json` / `vitest.config.ts` / `types/globals.d.ts` | 经典 JSX 运行时（`jsxFactory: h`）、vitest 的别名、浏览器半侧的运行时垫片 |
+| `README.md` | 就是本文 |
+
+## 数据是在哪算出来的
+
+宿主侧，`src/host.ts` 的 `readOverview(path, limit)`：
+
+* `readdirSync(path, { withFileTypes: true })` 数出**目录数**；
+* 每个普通文件 `statSync` 一次，累加**总字节**、记下 `name / bytes / mtime`（mtime 是 ISO 串）；
+* 按字节降序（同字节按名字）排，取前 `limit` 个当**最大的几个文件**。
+
+已知的取舍（不是 bug，是这份骨架刻意保持简单的地方）：
+
+* **符号链接不计数**：既不算文件也不算目录（想要跟随就自己换成 `statSync` + `lstatSync` 判断）；
+* **同步读**：模板优先让代码一眼看得懂；真接大目录时改成 `node:fs/promises` 版本更合适；
+* 只读**直接子项**，不递归。
+
+## 那条只读路由
+
+键是 `<unit>/overview`（`__UNIT__` 就是本模块的单元 id）——**必须住在自己那一格的命名空间里**，
+外壳装 / 升 / 卸时要能点名到它；写成别的名字注册当场就被判红。
+
+```
+GET /api/__UNIT__/overview?path=<绝对路径>&limit=<1..50>
+```
+
+查询参数：
+
+| 参数 | 缺省 | 说明 |
+|---|---|---|
+| `path` | 无（必填） | 要读的目录。卡片把 `props.world.current.workspace.path` 塞进来；缺了不回数据，直接回 `no-path` |
+| `limit` | `5` | 返回几个"最大的文件"，夹在 `1..50` 之间 |
+
+成功：
+
+```json
+{ "ok": true, "path": "/…", "files": 128, "dirs": 12, "bytes": 3145728,
+  "largest": [{ "name": "client.js", "bytes": 182400, "mtime": "2026-01-05T09:12:44.000Z" }] }
+```
+
+读不到（路径不存在 / 没权限 / 不是目录）：**HTTP 200 + `ok:false`**，错误码 `overview-unreadable`。
+压根没给 `path`：同样 `ok:false`，错误码 `no-path` —— 别拿宿主进程的工作目录当默认值：
+那会让"我没说要看哪儿"变成"屏幕上是 dsh 服务启动目录"，两个都不像用户想要的东西。
+之所以不让它抛：抛出去会被外壳的传输层转成 HTTP 500，卡片只剩一句"宿主返回 HTTP 500"，
+用户看不到是哪条路径出了什么事。
+
+```json
+{ "ok": false, "error": { "code": "overview-unreadable", "message": "ENOENT: no such file or directory, scandir '/…'" } }
+```
+
+卡片侧读数的 hook 是 `kit.hooks.useApiResource`（`route` 就是 `__UNIT__/overview`）。
+注意它的 `value` 是**整个响应对象**（成功时形如 `{ ok: true, ...payload }`），不是 `payload` 本身。
+
+## 这个模块会不会写东西、要不要跑一会儿、靠什么跑起来
+
+**这张卡只读** —— 上面那条 `/overview` 就是全部。要动手（提交、发布、批量改）就得再加两样，
+下面三段是**最小可抄的写法**；不需要的整段删掉，别留半截。
+
+### 会写：清单里标出来 + 认领审批
+
+```ts
+tools: [{ name: 'workbench___UNIT___rebuild', writes: true }],
+
+needsApproval: (call) => ({
+  kind: 'ask',
+  reason: '会覆盖产物',
+  question: { zh: '要重建这 3 个模块吗？', en: 'Rebuild these 3 modules?' },
+  fallback: { zh: '会覆盖它们的 dist 与 client.js', en: 'Overwrites their dist and client.js' },
+}),
+
+approvalDetail: async (call) => ({ zh: '会覆盖 3 个模块的产物，不碰源码', en: '…' }),
+```
+
+清单写着 `writes: true` 而不认领，外壳**当场 deny**（用户看到的是一次莫名其妙的拒绝）——
+`dsh-wb-module check --only contracts` 会替你先把这条看一遍。用户侧看到的问话就是
+`question` + `approvalDetail` 合起来的那几行：**一行一个事实，别写"这个操作会写数据"这种空话。**
+
+### 跑一会儿：长任务
+
+```ts
+mount({ longTasks, ... }) {
+  const runs = longTasks?.create({
+    key: 'rebuild',
+    run: async ({ payload, onStep }) => { onStep({ kind: 'start', text: '开始…' }); /* … */ return {}; },
+    outcome: (result) => ({ why: '…' }),
+    view: (snapshot) => ({ steps: String(snapshot.steps.length) }),
+  });
+  return { routes: {}, registerTools: () => [], ...(runs === undefined ? {} : { longTasks: runs }) };
+}
+```
+
+浏览器侧用 kit 那套画（`kit.hooks.useLongTask` + `<LongTaskRow …/>`）：状态只有
+`running` 进行中 / `needs-login` 要登录 / `ok` 完成 / `failed` 出错 —— **契约里没有"停止"**，
+别在界面上摆一个不存在的按钮。
+
+### 存起来：他能自己配什么（`prefs`）
+
+选一次就想让它一直算数（钉哪个环境、忽略哪些、超时多久）→ 走 `prefs` 通道：**按项目记、刷新还在**。
+只是"这次看哪一种"→ 当 route 参数传，别落盘。两种都写进 `design.json` 的 `config[].persistence`
+（`prefs` / `view`）—— 表里写了 `prefs`，产物里就必须真的接上（`check --only contracts` 会拦）。
+
+宿主半侧在 `mount` 里返回（最好单独一个纯文件，像 `src/prefs.ts` 那样能单测）：
+
+```ts
+prefs: {
+  resource: 'your-module',
+  handle: (payload) => applyPref(deps.store.for(UNIT_ID, workspace), payload),
+}
+```
+
+浏览器半侧：`useHostWrite({ channel: 'prefs', resource: 'your-module' })` + `Field` / `TextField`，外面套
+`SettingsSection`，保存用 `SaveBar`；存失败留在原地。（输入框内边距与"标签 + 提示"排布是外壳给的默认，
+不用为这个写 CSS。）语义：没写过 ≠ 选空、清空要把文件收掉、不认识的值报错并列出还认的候选。
+
+### 靠什么跑起来：`env`
+
+```ts
+env: {
+  command: 'opencli',
+  libs: [{ name: 'x-lib', registryEnv: 'DSH_WORKBENCH_X_REGISTRY', registryDefault: 'https://…/', purpose: '装它干嘛' }],
+  plugins: [{ name: 'x', commands: ['a', 'b'], installSource: { kind: 'npm', package: 'opencli-plugin-x', registryEnv: '…' } }],
+}
+```
+
+外壳的隔离运行时按它装、按它探（`workbench_modules list` 里逐条看得到）。**没装好时用户看到的那句话
+由你写**：`libInstallCommand({ need })` 会连源和缓存目录一起拼好，原样给他，别自己拼 npm 命令。
+
+## 卡片画哪五态
+
+`src/client.tsx` 的 `overviewStateOf({ fixture, phase, value, error })` 是一条纯函数，
+每个分支各对应一屏（`src/plugin.test.ts` 一屏一屏断言）：
+
+| 态 | 什么时候 | 画什么 |
+|---|---|---|
+| 待机 | 没有选中工作区（`path === ''`），请求压根不发（`useApiResource(…, { enabled: false })`，`phase` 停在 `idle`） | `CenteredState`：先打开一个项目 |
+| 加载 | 还没有值（首读），或 `phase === 'error'` 之外什么都没来 | `CenteredState`：正在读目录 |
+| 就绪 | 有值，且文件数 + 目录数 > 0 | `StateBlock`：路径 + 「N 个文件 · M 个目录 · 总字节」+ 最大的几个文件列表 |
+| 就绪但空 | 有值，但文件数 = 目录数 = 0 | `EmptyState`：这个目录是空的 |
+| 出错 | `phase === 'error'`（或夹具给的是错误） | `CenteredState`：读不到这个目录 + 宿主的原话 |
+
+待机那一屏要排在夹具**之后**：`?wbMock=1` 且没开项目时，夹具仍然要演得出来（否则
+"读不到"这种状态在没有项目时就永远看不到，而那正是干净 profile 下的评审场景）。
+
+刷新时 `useApiResource` 会把 `phase` 打成 `loading` **同时保留上一次的 `value`** ——
+这时刻意继续画旧数据（右上角的转圈由 `Card` 的 `refreshing` 表示），不退回骨架：
+一次刷新不该让整张卡闪一下。
+
+## `?wbMock=1` 夹具
+
+打开 `?wbMock=1`（搜索串里含 `wbMock=1`）时卡片顶上多一条 `MockStrip`，
+`kit.hooks.useFixturePick` 提供三个夹具，**只切状态、不发请求**：
+
+| id | 标签 | 演的是 |
+|---|---|---|
+| `ready` | 有数据 | 128 个文件 / 12 个目录 / 3 MB，带三个最大的文件 |
+| `empty` | 空目录 | 就绪但那一路"空"态 |
+| `error` | 读不到 | `EACCES: permission denied, scandir /mock/secret` |
+
+夹具优先于真请求：只要 mock 开着，画的就是夹具那一屏。
+改夹具时顺手改一眼 `src/plugin.test.ts` 的「夹具」那一组断言 —— 那组就是守它的。
+
+## 装进本地工作台
+
+```bash
+dsh plugin --profile workbench add <本目录>
+```
+
+## 改的时候这些是硬约束
+
+* **只用 kit 里真有的成员**：`check:kit` 拿产物实际取的成员去对 peer 下限那份外壳的 kit，
+  取了旧外壳没有的成员会在用户机器上首帧渲染就炸（peer 下限因此不许比 devDependency 旧）。
+* **两个运行时不许互引**：宿主侧不许碰 DOM / react，浏览器侧不许碰 `node:` / `process.env` / `Buffer`
+  （`check:bundles` 对着产物查）。所以目录读在 `src/host.ts`，卡片只管画。
+* `@/` 只许指自己（`@/modules/__UNIT__/*`）；共享代码走包名；`@deepseek-ai/dsh-*` 只在客户端侧用，
+  且必须同时写进 `package.json` 的 `dsh.client.external`。
+* **自己的样式走 CSS Modules**（`src/x.module.css` + `import styles from './x.module.css'`）：
+  类名照常写就行 —— 构建会**按文件路径哈希**（跨模块不会撞），但**别带 `wb-` 前缀**：
+  `wb-*` 是外壳的全局类名，模块定义它、或借契约里没有的那一个，`check:style` 都会判红。
+  要借外壳契约里的类，写 `:global(.wb-…)`，而且那个类必须在契约里。
+  这份骨架没带样式文件：五态全用 kit 的组件，够看。
+* **源码零注释**（`src/**`）：要说的都写在这里。
+
+要发布：把 `package.json` 里的 `private` 去掉，并显式写上发布目标
+（`publishConfig.access: "public"` 或指向内网源的 `publishConfig.registry`）——
+`private: true` 的包不许发到任何源，这是刻意的默认。

package/template-diy/cordis.patch.yml.tpl

@@ -0,0 +1,3 @@
+- insert:
+    - id: workbench-module-__UNIT__
+      name: '__NAME__'

package/template-diy/design.json.tpl

@@ -0,0 +1,38 @@
+{
+  "unit": "__UNIT__",
+  "name": "__NAME__",
+  "oneLine": "__DESC__",
+  "panel": [
+    { "cell": "这个目录占了多少空间", "conclusion": "该不该清、谁在占", "link": "" }
+  ],
+  "states": [
+    { "key": "idle", "sees": "「先打开一个项目」，不发请求", "canDo": "去左栏开一个项目", "agentCan": "说清「要先有项目」" },
+    { "key": "loading", "sees": "「正在读目录」", "canDo": "等", "agentCan": "——" },
+    { "key": "ready", "sees": "路径 + N 文件 / M 目录 / 总字节 + 最大的几个", "canDo": "刷新", "agentCan": "读一次这一格（联动见表 3）" },
+    { "key": "empty", "sees": "「这个目录是空的」", "canDo": "换一个目录", "agentCan": "同上" },
+    { "key": "unreadable", "sees": "「读不到这个目录」+ 宿主的原话", "canDo": "重试 / 改路径", "agentCan": "同上" }
+  ],
+  "config": [
+    { "persistence": "view", "key": "列几个最大的文件", "watches": "明细长度", "default": "5", "valuesFrom": "1..50", "wrongChoice": "夹回范围内，不报错" }
+  ],
+  "capabilities": [],
+  "linkage": [
+    { "who": "agent 读一次这一格", "when": "读完立刻", "whatChanges": "本单元那条只读投影（__UNIT__/overview），只带这个目录", "userSees": "那一格变成 agent 看到的那份数" },
+    { "who": "agent 只预览 / 只说了句话", "when": "不动", "whatChanges": "——", "userSees": "面板没变" },
+    { "who": "用户自己按刷新", "when": "立刻", "whatChanges": "同上", "userSees": "转一下，然后是新值" }
+  ],
+  "datasource": {
+    "read": "本机目录本身：readdirSync(path) + statSync（不走网络、不要凭据）",
+    "params": "path 必填（卡片给当前项目）；limit 默认 5，夹在 1..50",
+    "credentials": "不需要",
+    "notLoggedIn": "不适用（本机读盘，没有登录这回事）",
+    "timeout": "路径不存在 / 没权限 / 不是目录 → HTTP 200 + ok:false，码 overview-unreadable",
+    "probeCommand": "node -e \"require('node:fs').readdirSync(process.cwd())\""
+  },
+  "acceptance": [
+    { "step": "打开面板 → 看到这张卡 → 路径 + N 文件 / M 目录 / 总字节", "checked": false },
+    { "step": "换一个空目录 → 看到「这个目录是空的」（不是空白、也不是 0）", "checked": false },
+    { "step": "把 limit 调成 50 → 明细变长；调成 0 → 夹回 1，不报错", "checked": false },
+    { "step": "让 agent 读一次这一格 → 面板那一格变成同一份数", "checked": false }
+  ]
+}

package/template-diy/package.json.tpl

@@ -0,0 +1,43 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "__DESC__",
+  "type": "module",
+  "exports": {
+    ".": "./dist/host.js",
+    "./client": "./client.js"
+  },
+  "files": ["dist", "client.js", "cordis.patch.yml"],
+  "scripts": {
+    "build": "dsh-wb-module build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "selfcheck": "dsh-wb-module build && dsh-wb-module design check && node scripts/smoke.mjs",
+    "design": "dsh-wb-module design check",
+    "prepack": "dsh-wb-module build"
+  },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": ["@dsh-workbench/core"],
+      "external": ["@dsh-workbench/core/client"]
+    },
+    "workbench": {
+      "unit": "__UNIT__",
+      "faces": { "host": "src/host.ts", "client": "src/client.tsx" }
+    }
+  },
+  "peerDependencies": { "@dsh-workbench/core": "^0.1.0", "react": "*" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "devDependencies": {
+    "@dsh-workbench/core": "^0.1.0",
+    "@dsh-workbench/module-tools": "^0.1.0",
+    "@types/node": "^24.19.0",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "typescript": "5.9",
+    "vitest": "^5.0.2"
+  }
+}