@dsh-workbench/core 0.2.10 → 0.2.12

package/dist/types/modules/panels/model/diy-context.d.ts

@@ -0,0 +1,102 @@
+import type { DshHostContext, DshToolRunContext } from '@dsh-workbench/shared';
+import { type BrowserFindResult, type BrowserReadResult } from '@dsh-workbench/shared/host';
+import type { BundleChange } from '../../../shared/api/bundle-install';
+import type { PanelsService } from './service';
+export declare const OUTPUT_SCHEMA: {
+    type: string;
+    properties: {
+        text: {
+            type: string;
+        };
+        workshop: {
+            type: string;
+        };
+        modules: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+            };
+        };
+        unit: {
+            type: string;
+        };
+        path: {
+            type: string;
+        };
+        install: {
+            type: string;
+            additionalProperties: boolean;
+        };
+        alreadyInstalled: {
+            type: string;
+        };
+        panel: {
+            type: string;
+            additionalProperties: boolean;
+        };
+    };
+    additionalProperties: boolean;
+};
+export declare const OUTPUT: {
+    schema: {
+        type: string;
+        properties: {
+            text: {
+                type: string;
+            };
+            workshop: {
+                type: string;
+            };
+            modules: {
+                type: string;
+                items: {
+                    type: string;
+                    additionalProperties: boolean;
+                };
+            };
+            unit: {
+                type: string;
+            };
+            path: {
+                type: string;
+            };
+            install: {
+                type: string;
+                additionalProperties: boolean;
+            };
+            alreadyInstalled: {
+                type: string;
+            };
+            panel: {
+                type: string;
+                additionalProperties: boolean;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    render: (_args: unknown, value: unknown) => {
+        type: string;
+        text: string;
+    }[];
+};
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function asNumber(value: unknown): number | undefined;
+export declare function asText(value: unknown): string;
+export declare function plainJson<T>(value: T): T;
+export declare function verdictOf(change: BundleChange): string;
+export declare function renderProbe(out: BrowserReadResult): string;
+export declare function renderFind(out: BrowserFindResult): string;
+export declare function showOrReason(panels: PanelsService, unit: string, workspace: string | null): {
+    readonly ok: boolean;
+    readonly reason?: string;
+};
+export declare function workshopOf(ctx: DshHostContext, exec: DshToolRunContext): {
+    readonly packagesDir: string;
+    readonly workspace: string | null;
+};
+export declare function modulesOf(ctx: DshHostContext, packagesDir: string): {
+    installed: string[];
+    modules: readonly import("@/shared/api/host/diy-workshop").WorkshopModule[];
+};
+export declare function panelEntriesOf(panels: PanelsService, workspace: string | null): import("./config").PanelEntry[];

package/dist/types/modules/panels/model/diy-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/model/diy-logs.d.ts

@@ -0,0 +1,18 @@
+import type { DshHostContext, DshToolRegistry } from '@dsh-workbench/shared';
+export declare const LOGS_ARM_SCRIPT: string;
+export declare const LOGS_READ_SCRIPT: string;
+export declare const LOGS_STOP_SCRIPT: string;
+export interface LogLine {
+    readonly level: string;
+    readonly text: string;
+    readonly at: number;
+}
+export interface LogsRead {
+    readonly ok: boolean;
+    readonly code: string;
+    readonly seen: number;
+    readonly lines: readonly LogLine[];
+}
+export declare function logsReadOf(payload: Record<string, unknown> | undefined): LogsRead;
+export declare function renderLogs(read: LogsRead): string;
+export declare function registerLogTools(ctx: DshHostContext, tools: DshToolRegistry): readonly (() => void)[];

package/dist/types/modules/panels/model/diy-logs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/model/diy-look.d.ts

@@ -0,0 +1,14 @@
+import type { DshHostContext, DshToolRegistry } from '@dsh-workbench/shared';
+import { type Shot } from './diy-browser';
+import { type CardView, type PickRequest, type SlotFacts } from './diy-scripts';
+export declare function registerLookTools(ctx: DshHostContext, tools: DshToolRegistry): readonly (() => void)[];
+export declare function rgbOf(value: string): readonly [number, number, number] | undefined;
+export declare function contrastOf(foreground: string, background: string): number | undefined;
+export declare function styleLineOf(view: CardView, pick: PickRequest): string;
+export declare function partsLineOf(view: CardView, pick: PickRequest): string;
+export declare function slotText(slot: SlotFacts, width: number): string;
+export declare function slotLineOf(view: CardView): string;
+export declare function outlineText(view: CardView): string;
+export declare function contrastLineOf(view: CardView): string;
+export declare function renderLook(unit: string, view: CardView, shot: Shot, pick: PickRequest): string;
+export declare function renderMissingCard(unit: string, cards: number, anchored: boolean): string;

package/dist/types/modules/panels/model/diy-look.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/model/diy-net.d.ts

@@ -0,0 +1,3 @@
+import type { DshHostContext, DshToolRegistry } from '@dsh-workbench/shared';
+export declare function nearestKeyOf(payload: Record<string, unknown> | undefined, key: string): string;
+export declare function registerNetTools(ctx: DshHostContext, tools: DshToolRegistry): readonly (() => void)[];

package/dist/types/modules/panels/model/diy-net.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/model/diy-page.d.ts

@@ -0,0 +1,15 @@
+import type { DshHostContext, DshShell, DshToolRunContext } from '@dsh-workbench/shared';
+export interface PageHandle {
+    readonly packagesDir: string;
+    readonly unit: string;
+    readonly args: Record<string, unknown>;
+    readonly shell: DshShell;
+    readonly command: string;
+    readonly session: string;
+    readonly bound: boolean;
+}
+export interface PageOptions {
+    readonly requireWorkbench?: boolean | undefined;
+    readonly requireUnit?: boolean | undefined;
+}
+export declare function pageAt(ctx: DshHostContext, exec: DshToolRunContext, raw: unknown, options?: PageOptions): Promise<PageHandle>;

package/dist/types/modules/panels/model/diy-page.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/model/diy-schema.d.ts

@@ -0,0 +1,9 @@
+export declare const UNIT_PROP: {
+    type: string;
+    description: string;
+};
+export declare const SESSION_PROP: {
+    type: string;
+    description: string;
+};
+export declare function pageSchema(extra?: Record<string, unknown>, required?: readonly string[]): Record<string, unknown>;

package/dist/types/modules/panels/model/diy-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/model/diy-scripts.d.ts

@@ -0,0 +1,64 @@
+export declare const PAGE_PROBE = "(async () => {\n  const answer = await fetch('/workbench/api/health').then((one) => one.json()).catch(() => null);\n  return JSON.stringify({\n    plugin: answer === null ? null : answer.plugin,\n    pid: answer === null ? null : answer.pid,\n    url: location.href,\n    title: document.title,\n  });\n})()";
+export declare function cardSelectorOf(unit: string): string;
+export type DomMode = 'none' | 'outline' | 'html';
+export interface PickRequest {
+    readonly props: readonly string[];
+    readonly parts: readonly string[];
+    readonly dom: DomMode;
+}
+export declare const DOM_MODES: readonly DomMode[];
+export interface PickFacts {
+    readonly card: Readonly<Record<string, string>>;
+    readonly parts: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+export declare const DEFAULT_PROPS: readonly ["display", "flexDirection", "gap", "padding", "width", "height", "overflow", "backgroundColor", "color", "borderRadius", "fontSize", "lineHeight", "fontFamily", "boxSizing", "--dsw-radius-xl", "--dsw-alias-bg-layer-1", "--dsw-alias-label-primary"];
+export declare const DEFAULT_PARTS: readonly [".wb-cardHead", ".wb-cardBody"];
+export declare function cleanNames(value: unknown, cap: number): readonly string[];
+export declare function pickOf(raw: Record<string, unknown>): PickRequest;
+export interface CardView {
+    readonly ok: boolean;
+    readonly anchored: boolean;
+    readonly width: number;
+    readonly height: number;
+    readonly head: string;
+    readonly text: string;
+    readonly clipped: boolean;
+    readonly cards: number;
+    readonly rect: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly dpr: number;
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly pick: PickFacts;
+    readonly slot: SlotFacts;
+    readonly outline: readonly CardNode[];
+    readonly html: string;
+}
+export interface SlotFacts {
+    readonly parentWidth: number;
+    readonly parentDisplay: string;
+    readonly columns: string;
+    readonly index: number;
+    readonly cards: number;
+    readonly viewportHeight: number;
+    readonly scrollHeight: number;
+}
+export interface CardNode {
+    readonly depth: number;
+    readonly tag: string;
+    readonly cls: string;
+    readonly role: string;
+    readonly name: string;
+    readonly text: string;
+}
+export declare const EMPTY_CARD: CardView;
+export declare function measureScriptOf(unit: string, pick: PickRequest): string;
+export declare function nodesOf(value: unknown): readonly CardNode[];
+export declare function slotOf(value: unknown): SlotFacts;
+export declare function pickFactsOf(value: unknown): PickFacts;

package/dist/types/modules/panels/unit.d.ts

@@ -1,5 +1,45 @@
 import type { UnitManifest } from '@dsh-workbench/shared';
-export declare const PANELS_TOOL = "workbench_panels";
-export declare const MODULES_TOOL = "workbench_modules";
-export declare const DIY_TOOL = "workbench_diy";
+export declare const PANELS_LIST_TOOL = "workbench_panels_list";
+export declare const PANELS_SHOW_TOOL = "workbench_panels_show";
+export declare const PANELS_HIDE_TOOL = "workbench_panels_hide";
+export declare const PANELS_MOVE_TOOL = "workbench_panels_move";
+export declare const PANELS_RESET_TOOL = "workbench_panels_reset";
+export declare const PANELS_FOLLOW_TOOL = "workbench_panels_follow";
+export declare const MODULES_LIST_TOOL = "workbench_modules_list";
+export declare const MODULES_INSTALL_TOOL = "workbench_modules_install";
+export declare const MODULES_UPDATE_TOOL = "workbench_modules_update";
+export declare const MODULES_UNINSTALL_TOOL = "workbench_modules_uninstall";
+export declare const MODULES_INSTALL_BUNDLE_TOOL = "workbench_modules_install_bundle";
+export declare const MODULES_UPDATE_DEPENDENCY_TOOL = "workbench_modules_update_dependency";
+export declare const MODULES_UPDATE_PLUGIN_TOOL = "workbench_modules_update_plugin";
+export declare const MODULES_UNINSTALL_PLUGIN_TOOL = "workbench_modules_uninstall_plugin";
+export declare const MODULES_UPDATE_WORKBENCH_TOOL = "workbench_modules_update_workbench";
+export declare const DIY_LIST_TOOL = "workbench_diy_list";
+export declare const DIY_STATUS_TOOL = "workbench_diy_status";
+export declare const DIY_PANEL_TOOL = "workbench_diy_panel";
+export declare const DIY_RECON_TOOL = "workbench_diy_recon";
+export declare const DIY_PROBE_TOOL = "workbench_diy_probe";
+export declare const DIY_LOOK_TOOL = "workbench_diy_look";
+export declare const DIY_INSTALL_TOOL = "workbench_diy_install";
+export declare const DIY_SHOW_TOOL = "workbench_diy_show";
+export declare const DIY_CLICK_TOOL = "workbench_diy_click";
+export declare const DIY_TYPE_TOOL = "workbench_diy_type";
+export declare const DIY_FILL_TOOL = "workbench_diy_fill";
+export declare const DIY_KEYS_TOOL = "workbench_diy_keys";
+export declare const DIY_HOVER_TOOL = "workbench_diy_hover";
+export declare const DIY_SELECT_TOOL = "workbench_diy_select";
+export declare const DIY_SCROLL_TOOL = "workbench_diy_scroll";
+export declare const DIY_RELOAD_TOOL = "workbench_diy_reload";
+export declare const DIY_VIEWPORT_TOOL = "workbench_diy_viewport";
+export declare const DIY_NET_WATCH_TOOL = "workbench_diy_net_watch";
+export declare const DIY_NET_READ_TOOL = "workbench_diy_net_read";
+export declare const DIY_NET_STOP_TOOL = "workbench_diy_net_stop";
+export declare const DIY_LOGS_WATCH_TOOL = "workbench_diy_logs_watch";
+export declare const DIY_LOGS_READ_TOOL = "workbench_diy_logs_read";
+export declare const DIY_LOGS_STOP_TOOL = "workbench_diy_logs_stop";
+export declare const ALL_TOOLS: readonly ["workbench_panels_list", "workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_list", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_recon", "workbench_diy_probe", "workbench_diy_look", "workbench_diy_install", "workbench_diy_show", "workbench_diy_click", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_hover", "workbench_diy_select", "workbench_diy_scroll", "workbench_diy_reload", "workbench_diy_viewport", "workbench_diy_net_watch", "workbench_diy_net_read", "workbench_diy_net_stop", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
+export type PanelsToolName = (typeof ALL_TOOLS)[number];
+export declare const READ_TOOLS: readonly ["workbench_panels_list", "workbench_modules_list", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_recon", "workbench_diy_probe", "workbench_diy_look", "workbench_diy_click", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_hover", "workbench_diy_select", "workbench_diy_scroll", "workbench_diy_reload", "workbench_diy_viewport", "workbench_diy_net_watch", "workbench_diy_net_read", "workbench_diy_net_stop", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
+export declare const WRITE_TOOLS: readonly ["workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_install", "workbench_diy_show"];
+export declare const DIY_TOOLS: readonly ["workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_recon", "workbench_diy_probe", "workbench_diy_look", "workbench_diy_install", "workbench_diy_show", "workbench_diy_click", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_hover", "workbench_diy_select", "workbench_diy_scroll", "workbench_diy_reload", "workbench_diy_viewport", "workbench_diy_net_watch", "workbench_diy_net_read", "workbench_diy_net_stop", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
 export declare const panelsUnit: UnitManifest;

package/dist/types/shared/api/diy.d.ts

@@ -3,3 +3,7 @@ export declare const WORKSHOP_RELATIVE = "workbench/diy";
 export declare const WORKSHOP_TITLE = "\u5DE5\u4F5C\u53F0DIY";
 export declare const WORKSHOP_PAST_TITLES: readonly string[];
 export declare function isWorkshopPath(path: string): boolean;
+export interface DiyStartOptions {
+    readonly agentPreset: string;
+}
+export declare function diyStartOptions(workspaceId: string, workshopId: string | undefined): DiyStartOptions | undefined;

package/dist/types/shared/api/host/__tests__/png-fixtures.d.ts

@@ -0,0 +1,17 @@
+export declare const PNG_SIGNATURE: Buffer<ArrayBuffer>;
+export declare function fixtureOf(options: {
+    width: number;
+    height: number;
+    color?: number;
+    depth?: number;
+    interlace?: number;
+    filter?: number;
+}): Buffer;
+export interface Pixels {
+    readonly width: number;
+    readonly height: number;
+    readonly color: number;
+    readonly pixels: Buffer;
+}
+export declare function pixelsOf(bytes: Buffer): Pixels;
+export declare function blockOf(x: number, y: number, width: number, height: number, color: number): Buffer;

package/dist/types/shared/api/host/mount-units.d.ts

@@ -12,6 +12,7 @@ export interface MountedUnit {
     readonly host: HostUnit;
     readonly result: UnitMountResult;
     readonly readiness: UnitReadiness;
+    readonly rollbackTools: () => void;
 }
 export interface UnitsPlan {
     readonly mounted: readonly MountedUnit[];
@@ -41,6 +42,11 @@ interface NamedEntry {
     handle(payload: unknown): unknown;
 }
 export declare function failureReasonOf(error: unknown): string;
+export interface PlanFailureSinks {
+    readonly note: (unit: string, reason: string) => void;
+    readonly warn: (message: string) => void;
+}
+export declare function applyPlanFailures(failures: readonly UnitFailure[], sinks: PlanFailureSinks): void;
 export declare function mountUnits(units: readonly HostUnit[], deps: {
     ctx: DshHostContext;
     logger?: {

package/dist/types/shared/api/host/png-crop.d.ts

@@ -0,0 +1,21 @@
+export interface PngRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface PngCrop {
+    readonly ok: boolean;
+    readonly bytes: Buffer;
+    readonly width: number;
+    readonly height: number;
+    readonly clamped: boolean;
+    readonly reason: string;
+}
+export interface PngCropFile {
+    readonly ok: boolean;
+    readonly clamped: boolean;
+    readonly reason: string;
+}
+export declare function cropPng(bytes: Buffer, rect: PngRect): PngCrop;
+export declare function cropPngFile(input: string, output: string, rect: PngRect): PngCropFile;

package/dist/types/shared/api/host/png-crop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/core",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "个人工作台：Agent 工作台外壳（左栏 + 常驻对话 + 自研右侧数据面板）。",
   "type": "module",
   "icon": "./icon.svg",
@@ -87,7 +87,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dsh-workbench/shared": "0.2.10"
+    "@dsh-workbench/shared": "0.2.12"
   },
   "scripts": {
     "build": "node scripts/build.mjs && node scripts/build-types.mjs",

package/skills/workbench-module-diy/BUILD.md

@@ -53,7 +53,7 @@ pnpm exec dsh-wb-module init <unit> --dir <工坊>/packages/module-<unit> --temp
 | 模板 | 是什么 | 什么时候用 |
 |---|---|---|
 | `minimal`（不写就是它） | 空壳：卡壳、文案、测试都接好了，但**没有数据源** | 你已经清楚要读什么、想从零写 |
-| `diy` | 一张**读当前项目的样板卡**：宿主侧一条真读目录的只读路由、卡片三态、`?wbMock=1` 三档夹具 | 你要照着改出一个"真能出数据"的最小版本 —— **建议先用它** |
+| `diy` | 一张**读当前项目的样板卡**：宿主侧一条真读目录的只读路由、卡片五态（待机 / 加载 / 就绪 / 就绪但空 / 出错） | 你要照着改出一个"真能出数据"的最小版本 —— **建议先用它** |
 
 ⚠️ `diy` 那份是**给别人照抄的**，所以它自己也必须开箱全绿 —— 门禁会**两个模板各 init 一遍、各跑一遍全套**。
 
@@ -112,8 +112,9 @@ pnpm selfcheck   # 构建 + 把 client.js 当加载器跑一遍（`diy` 骨架
 这次没查的那几条逐条列出来；**要验它们，回工作台仓库根跑一次 `dsh-wb-module check`**。
 所以「8 通过 · 2 不适用」不等于十一条全绿 —— 别把这句话念给用户听。
 
-装上板那一步不是命令，是一把 agent 工具：`workbench_diy`（`action=list` 看工坊里有什么、`action=status, unit=<单元 id>`
-看它现在走到哪一步、`action=install` 装上并上板、`action=open` 只上板）—— 见 §7。
+装上板那一步不是命令，是一套 agent 工具（一个动词一把）：`workbench_diy_list` 看工坊里有什么、
+`workbench_diy_status`（`unit=<单元 id>`）看它现在走到哪一步、`workbench_diy_install` 装上并上板、
+`workbench_diy_show` 只上板 —— 见 §7。**上完板看一眼**：`workbench_diy_look`（只截那张卡 + 按你点的项读样式）—— 用户那一页不会被改动，但他得把工作台切到前台。卡片有没有报错先看 `workbench_diy_panel` 的「崩过 / 读到了」；真要这一页的控制台，用 `workbench_diy_logs_watch` → 做那件事 → `workbench_diy_logs_read`（钩子有上限，见 [REVIEW.md](REVIEW.md) 四步取证的 4）。
 
 ## 4 两个面的形状
 

package/skills/workbench-module-diy/DATASOURCE.md

@@ -20,7 +20,7 @@
 2. **数据从哪来 —— 四层，从上往下试**（**用户不知道 opencli 是什么，这一整步是你的活**：
    别问他"你用哪个插件 / 有没有 API"，他说的是"我想看 X"，把 X 翻成关键词是你的活）。
 
-   ① **先看 opencli 自带的**：`workbench_diy`（`action=recon, keyword=<站点名 / 系统名 / 域名>`，
+   ① **先看 opencli 自带的**：`workbench_diy_recon`（`keyword=<站点名 / 系统名 / 域名>`，
       也可以直接给 `url` 让它取域名）。它回这台机器上**已经能用**的能力：站点、命令、`strategy`
       （PUBLIC / COOKIE / INTERCEPT / UI）以及**要不要用户的 Chrome 登录**，还有能直接照抄的那一行。
       **有就直接复用：不用装、不用点头。** 官方那份发现指引：`opencli skills read opencli-usage`。
@@ -41,7 +41,7 @@
       - 想长期用 → 给这个站点写 adapter：`opencli skills read opencli-adapter-author`（侦察 → 字段解码 →
         写 → verify）；以后 adapter 失效：`opencli skills read opencli-autofix`。
 
-   **④ 才轮到探** —— 用工具：`workbench_diy`（`action=probe, url=<那套系统的地址>, script=<一段回 JSON 的脚本>`；
+   **④ 才轮到探** —— 用工具：`workbench_diy_probe`（`url=<那套系统的地址>, script=<一段回 JSON 的脚本>`；
    页面里没有接口就给 `css=<选择器>`，走的是同一条固定 DOM 读，`{entries:[{text}]}` 直接回给你）。
    它用**用户浏览器里现有的登录**去读，并把"读不到"归一成阻断屏认的那几个码 —— 两拍（不在站点上就自己
    打开 `url` 再读一遍）、刚重启时的重试、平台码到阻断码的映射**都在工具里**，不用你记。
@@ -67,7 +67,7 @@
      [ADR-0036](../../../../docs/adr/0036-opencli-always-background.md)）。
    - **页面里没有接口时（DOM 读）不要用 `eval` 去 `document.querySelectorAll`**：产物边界判据会拦
      （宿主产物里不许出现 `document.` / `window.` 字样），而且那样解析只能窝在字符串里、测不了。
-     探的时候 `workbench_diy`（`action=probe, url=…, css=<选择器>`）就是这个口子；
+     探的时候 `workbench_diy_probe`（`url=…, css=<选择器>`）就是这个口子；
      固化时走 `browserFind`，它内部用的就是 `opencli browser <session> find --css '<选择器>' --limit N --text-max M`，
      回 `{ entries: [{ text, tag, nth }] }` —— **一行的单元格按换行拼在 `text` 里**（`美元\n668.3\n…`），
      所以"切格 + 按列序取值"是两个纯函数，能单测。很多公开站点一条 XHR 都不发，就该走这条。
@@ -119,4 +119,4 @@
 
 - 数据源写在**宿主半侧**，卡片只消费它的返回；
 - 只读路由出错时回 `{ ok: false, error: { code, message, hint? } }`（HTTP 仍是 200，外壳原样转发）；
-- `?wbMock=1` 下三档夹具都要能出（正常 / 空 / 出错）—— 这是你自己验收"三态"的快捷方式。
+- 验收时把「正常 / 空 / 出错」三条路都走一遍 —— 真机上造不出来的那几条，写清**怎么才能真看到**（换个空目录、换个不存在的路径那种），别为它写夹具（**2026-10-16 起模板与指引都不带评审夹具**）。

package/skills/workbench-module-diy/DESIGN.md

@@ -101,7 +101,7 @@ key 固定 `idle|loading|ready|empty|unreadable`）+ `config[]` + `capabilities[
 `link` 这类**可选格**留空渲染成 `—`，不算空格。
 
 `design.json` 是**设计底稿**：只装人话。"这条能力在哪些工作区出现"**哪里都别写** ——
-它既不在底稿、也不在清单：那是**用户**的事（他在 `workbench_panels` 里决定，见 [TOOLS.md](TOOLS.md) §12）。
+它既不在底稿、也不在清单：那是**用户**的事（他在 `workbench_panels_show` / `workbench_panels_hide` 里决定，见 [TOOLS.md](TOOLS.md) §12）。
 协议里那个 `scope`（`tools[].scope` / `card.scope`）**已经删掉**：用户口径是「模块开发者不能定义 scope，
 scope 永远是用户来决定的」（见 [ADR-0038 §2.4 / §6.16](../../../../docs/adr/0038-module-declaration-protocol.md)）。
 `contracts` 只拿名字把底稿与清单对起来（键集合对账）。

package/skills/workbench-module-diy/KIT.md

@@ -0,0 +1,121 @@
+# kit 速查：要做什么 → 用哪一件 → 最小写法
+
+`dsh-wb-module check --only kit` 列的是**名字**，这一份给的是**用法**。两处都别看漏：
+名字那份是这台机器上**真有的**（别照抄别的模块），这一份是**怎么拼**。
+
+**能拿 kit 的就别自己画。** 理由只有一条：主题、语言、悬停、禁用、焦点环、空态、被裁的处理
+都只维护一份。自己画的不会跟着换主题，也不会跟着我们改口径 —— 这就是"同一个东西长得不一样"的来源。
+
+> 全部从 `const { … } = kit.components`（`@dsh-workbench/core/client`）拿。
+> 例子里的 `h` = `createElement`（`import { createElement as h } from 'react'`）。
+
+## 1 卡片外壳
+
+**`Card`** —— 一张卡的壳：标题 + 刷新钮 + 卡片体。面板上每一格都是它。
+
+```tsx
+h(Card, {
+  t: props.t,
+  title: t('myunit.cardTitle'),
+  refreshing: resource.phase === 'loading',
+  onRefresh: props.onRefresh,
+}, body)
+```
+
+**`CardHead`** —— 你自己拼卡头时用它（`Card` 内部就是它）：`t` / `title` / `meta` / `refreshing` /
+`onRefresh` / `gear` / `onToggleGear`（右上那颗齿轮展开设置面）/ **`platformHref`**（跳整张卡对应的
+那个系统：只给这一颗就够，那颗 ↗ 立刻画出来）。
+
+**`CardAnchor`** —— 外壳自己盖的锚点（`#wb-card-<unit>`）。**别自己写**，也别删。
+
+**`CardBoundary`** —— 卡片级错误边界。一张卡炸了不许把整块面板带走；**别自己 try/catch 包渲染**。
+
+## 2 状态：这是下限最集中的地方
+
+先想清五态（`design.json` 的状态矩阵就是这五格）：**待机 / 在读 / 就绪 / 就绪但空 / 读不到**。
+每一态都要有东西画，一个不落。
+
+| 什么时候 | 用 |
+|---|---|
+| 有内容了 | `StateBlock`（标题 + `hint` 一行 + 正文） |
+| 要他先选一个 / 正在读 / 读不到 | `CenteredState`（居中一屏） |
+| 就绪但空 | `EmptyState`（它只是 `CenteredState` 的简写） |
+| 在读、且你已经有大概形状 | `SkeletonRows`（骨架） |
+| 一句说明 / 一句报错 | `Note`（`tone: 'problem'` 是报错） |
+
+```tsx
+h(CenteredState, { icon: null, title: t('myunit.loading'), hint: t('myunit.loadingHint'), compact: true })
+h(CenteredState, { icon: null, title: t('myunit.errorTitle'), detail: `${code}: ${message}`, hint: t('myunit.errorHint'), compact: true })
+h(EmptyState, { text: t('myunit.empty'), icon: h(IconPanelScreen, { size: 20 }), compact: true })
+h(StateBlock, { title: rows.title, hint: `3 条 · ${when}`, resolving: t('myunit.rows') }, table)
+h(Note, { children: t('myunit.hint') })
+```
+
+**读不到就说读不到**：`detail` 里放原始错误码与那句话，**绝不显示 0**（0 是"真的是 0"，不是"没读到"）。
+
+## 3 一行一行
+
+**`Rows` + `Row`** —— 键值行（左边名字、右边值）。**别自己写 `ul`/`li` 或 div 行**：
+分隔线、行距、对齐、两端溢出都在这两件里。
+
+```tsx
+h(Rows, null,
+  ...items.map((one) => h(Row, { key: one.name, label: one.name, value: `${size} · ${when}` })))
+```
+
+**`ActivityBlock` / `ActivityLine` / `ActivityAction`** —— "它做过什么"那一块：
+`ActivityLine` 有 `dot` / `text` / `at`（时间）/ `actions`；`ActivityAction` 是行尾那个动作
+（`label` / `icon` / `href` 或 `onClick` / `failed`）。时间一律用它，别自己拼。
+
+**`LongTaskRow`** —— 长任务那一行：`status`（四态）+ `headline` + `problem` + `links` + `steps` +
+`raw`。跑得久的事（发布、扫描、迁移）都用它，别自己画进度。
+
+**`ApprovalDetail` / `ApprovalPlan`** —— 审批屏上那两格（要用户点头的写操作）。
+
+## 4 表单
+
+**`Field`** —— 标签 + 输入的排布（`label` / `hint`），输入框放里面。
+
+```tsx
+h(Field, { label: t('myunit.mode'), hint: t('myunit.modeHint') },
+  h(TextField, { value, onChange: (event) => setMode(event.target.value) }))
+```
+
+**`TextField`** —— 单行输入（`invalid` 标红；其余是原生 input 的 props）。
+**`ChoiceGroup`** —— 单选 / 多选（`multi` 区分；`value` 或 `values` + `onChange`；选项 `{ value, label, hint?, disabled? }`）。
+**`SelectField`** —— 下拉：默认是**常规下拉框**（跟 `TextField` 一套），无边框那种给 `variant: 'ghost'`；
+搜索、分组、禁用项、加载态、空态、页脚都是它的 prop。
+**`SaveBar`** —— 设置面底下那条"取消 / 保存"（`busy` / `disabled` / `labels` / `onCancel` / `onSave`）。
+
+**别手写 `<button>` / `<input>` / `<select>`**：dsh 有 `Button`（`variant` / `size`），
+kit 有上面这几件；手写的会拿到浏览器默认样式，而且**判据会红**（`check:style`）。
+`<textarea>` 例外（dsh 与 kit 都没有多行输入）——真要用就直接写，其余形态别开这个口子。
+
+## 5 别的
+
+- **`Link`** —— **唯一**的外链写法：`h(Link, { href, children })`。自带新窗口 + `rel="noopener noreferrer"`
+  + 正文色 + hover 下划线 + 那颗小箭头。**别去掉箭头、别在文案里自带 `→`、别手写 `<a>`**（判据红）。
+- **`SettingsSection`** —— 一屏设置里的一节（`label` / `title` / `action`）。
+- **`Stack`** —— 竖排 + 统一间距（懒得分组时的默认容器）。
+- **`BlockerState`** —— 阻断屏：要登录 / 没权限 / 能力没装好那一类（`blocker` / `t` / `onRetry` / `onOpenMarket`）。
+- **`Tip`** —— Tooltip：图标钮与只有图的地方**必须**有它（或 `aria-label`）。
+- **别给模块带夹具**：2026-10-16 起模板 / `init` 文案 / 这份指引都不带评审夹具了（`?wbMock=1` 那套、`useFixturePick` / `MockStrip` / `mockNote` 都从模板里删了）。夹具是模块作者负担里最不值的那一份 —— 而**你自己那份 `plugin.test.ts` 就能把五态各喂一遍**，门禁从来只问"空数据画不画得出"（`check:cards`）。外壳自己那套 `?wbMock=1` 夹具是给**外壳的卡片**用的，模块不必跟（机制仍在，谁想要仍然可以用，但**不是你要做的事**）。
+- **图标** —— `IconPanelScreen`（面板/卡片那类）、`IconModuleMark`（我们的模块类型标）、
+  `IconNpm` / `IconOpencli`（包类型）；其余图形一律从 dsh 的 `Icon*Regular` 拿，**别自己画图标**。
+
+## 6 三条纪律
+
+1. **调用点只给数据与语义**：`h(Card, { title, refreshing, onRefresh }, …)`。别从外面塞外观类名
+   —— 只有布局槽例外（通栏、外边距、网格位置）。
+2. **字号与颜色走 kit 与令牌**（`--dsw-*` / `--wb-*`），不写字面值。**重点可以大**：
+   一个"余额 / 总数"那种要突出的数字，用刻度里最大那档 `--dsw-font-xl-24`（24/32、600），
+   数字加 `font-variant-numeric: tabular-nums`（见 [PANEL.md](PANEL.md) §6）。
+   刻度外非要一个字面值（比如更大的标题数）时，在模块 `README.md` 里写一句为什么。
+3. **自己写 CSS 只写布局**（flex / grid / gap / 对齐）。要一个新的"长得像控件"的东西时，
+   先问一句：kit 里是不是已经有了？
+
+## 7 kit 里没有、但你确定要标准控件
+
+见 [PANEL.md](PANEL.md) §9：可以引 dsh 的客户端原语，但**只在浏览器侧**、并在
+`package.json` 的 `dsh.client.external` 里声明 `@deepseek-ai/dsh-client-ui-primitives`
+（宿主侧一个字都不许碰 —— `check` 的源码边界判据会红）。能拿 kit 的时候仍然别自己画。

package/skills/workbench-module-diy/PANEL.md

@@ -133,6 +133,16 @@ agent 那一侧也要能通过模块自己的能力读到同一份偏好。
   dsh 的 `Button`，或阻断屏里的 `action`。区别在"跳去哪"和"它是不是一个动作"，不在好看不好看。
 - **标签 + 输入框的排布用 `Field`**，输入框用 `TextField` —— 内边距与排版是外壳给的默认，
   别为"能看"写模块自己的 CSS（见 §5.1）。
+- **要做什么用哪件，照 [KIT.md](KIT.md) 抄**（"要做什么 → 用哪件 → 最小写法"的表）。
+  下面几条是口径，KIT.md 是写法。
+- **字号与重点**：走那把刻度（`--dsw-font-*`：11 / 12 / 13 / 14 / 16 / 20 / 24），
+  **但不许"整张卡一样大"** —— 要有重点。最该大的那个数字（余额、总数、还剩多少）
+  就用刻度里最大那档 `--dsw-font-xl-24`（24/32、600 重），它旁边的说明 12。
+  这一档是**给重点留的、鼓励用**：卡里最大的字比正文大一倍，比全卡 12 号好读得多。
+  刻度外非要一个字面值（28/32 那种）时，在模块 `README.md` 里写一句为什么，别静悄悄写。
+  成列的数字加 `font-variant-numeric: tabular-nums`。
+  **别为了"统一"把重点压回正文大小**——那才是不合口径。
+- **颜色与间距也走令牌**（`--dsw-*` / `--wb-*`）；自己写 CSS 只写布局（flex / grid / gap / 对齐）。
 
 ## 7 状态矩阵怎么写
 
@@ -154,7 +164,7 @@ agent 那一侧也要能通过模块自己的能力读到同一份偏好。
 - **平台没给的那一格就不占位**（不留孤零零的字段名、不留空的一行）。
 - **读不到就说读不到**，并说清为什么（例：手上这份能力太旧）；**绝不显示 0**。
 - 有确定答案就不打扰他（能按默认读出来就别弹设置面）。
-- 真机上造不出来的状态也要写 —— 造出来是评审夹具的事。
+- 真机上造不出来的状态也要**在设计上**画出来（照这一格写清）—— 但**不必为它写夹具**：2026-10-16 起模板与指引都不带评审夹具，模块自己的 `plugin.test.ts` 把五态各喂一遍就够（门禁只问"空数据画不画得出"）。
 
 ### 7.1 图例就是把屏幕画成 ASCII
 
@@ -177,7 +187,7 @@ agent 那一侧也要能通过模块自己的能力读到同一份偏好。
 - **用真字**：图里的文案用界面上真实那句（例「没有指派给你的缺陷。」），别写"一句空态文案"。
 - **别拿图标代替画面**：给状态起个名字、配个 `⛔` 这类符号，用户还是分不清；一眼能认的是**形状**（整卡换掉 vs 多一行）与**位置**（行首的点、行尾的两颗）。
 - **画不成的才写词**：动作、agent 的下一步、时间性的"不变 / 自己变"，写成词并说清意思。
-- **真机上造不出来的状态**：沟通时照样画（画的是设计意图）；实现时用评审夹具把它造出来给人切。
+- **真机上造不出来的状态**：沟通时照样画（画的是设计意图）；实现时**要让它能用真实输入走到**（换个空目录、换个坏路径、先不选），而不是给它写夹具 —— 2026-10-16 起模板与指引都不带评审夹具，模块自己的 `plugin.test.ts` 把五态各喂一遍就够。
 
 ## 8 范例（真实产出的形状）