dsh-ts-example 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0] - 2026-08-28
+
+### Added
+
+- TypeScript 插件开发示例：server 端 TS 源码 + tsc 编译（`lib/index.js` 产物）、client 端 TS 源码 + 构建时编译（`__ModuleLoader__` bundle）
+- 演示内容：`GET /ts-example/api/greeting?name=xxx` 问候语路由、`GET /ts-example/api/stats` 会话计数、侧边栏「TS 示例」页签

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bsfeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# dsh-ts-example
+
+[![插件生态](https://img.shields.io/badge/插件生态-topic%20dsh-4d6bfe)](https://github.com/topics/dsh)
+
+<div align="center">
+  <img alt="侧边栏「TS 示例」页签：显示当前会话问候语" src="./assets/screenshot.png" width="420" />
+</div>
+
+**DSH 插件 TypeScript 开发示例插件**：演示新插件用 TypeScript 开发的全流程——server 端 TS 源码 + `tsc` 编译，client 端 TS 源码 + 构建时编译；编译期即可发现模块不存在、类型不匹配、未定义变量等错误。
+
+## 功能
+
+- **问候语路由**：`GET /ts-example/api/greeting?name=xxx` → `{ "greeting": "Hello, xxx!" }`（支持 `zh` / `en` 语言配置）；
+- **会话计数**：`GET /ts-example/api/stats` → `{ "sessions": N }`（监听 `session/start` 事件计数）；
+- **侧边栏页签「TS 示例」**：显示当前会话的问候语（client 端 TS → server 端 TS 全链路），经宿主原生侧边栏扩展点注册，零第三方依赖——同时作为「原生扩展点 + TS 构建」的活样例。
+
+## 配置
+
+| 配置项     | 类型           | 默认值 | 说明       |
+| ---------- | -------------- | ------ | ---------- |
+| `language` | `'zh' \| 'en'` | `'en'` | 问候语语言 |
+
+## 安装
+
+```bash
+# npm 安装（该包尚未发布到 npm，发版后可用）
+dsh plugin --profile web add dsh-ts-example --trust-lockfile
+
+# 本地 link（当前可用方式）
+git clone https://github.com/baosfeng/my-dsh-plugins.git
+dsh plugin --profile web add link:<仓库路径>/plugins/dsh-ts-example
+```
+
+## 相关文档
+
+→ [TS 示例概述](../../docs/TS示例/概述.md) · [CHANGELOG](CHANGELOG.md)

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-ts-example bundle patch: inserts the plugin row into the profile roster.
+# The row mounts the host half (greeting + stats API) and the client half
+# (sidebar "TS 示例" tab). Install with:
+#
+#   git clone https://github.com/baosfeng/my-dsh-plugins.git
+#   dsh plugin --profile web add link:<仓库路径>/plugins/dsh-ts-example
+- insert:
+    - id: ts-example
+      name: 'dsh-ts-example'

package/lib/client.js

@@ -0,0 +1,125 @@
+/**
+ * dsh-ts-example — client half (browser). SOURCE TEMPLATE.
+ *
+ * BUILD NOTE: 本文件是模板源码，不是 DSH 实际服务的文件。scripts/build.mjs
+ * 先运行 `tsc -p tsconfig.client.json` 把 src/client/index.ts 编译成
+ * CommonJS 单文件（lib/.client-build/index.js），再注入下方
+ * /*__CLIENT_BUNDLE__* / 占位符（函数式 replaceAll，避免 $&/$1 特殊解释），
+ * 写出 lib/client.js —— 即 DSH 实际服务的产物（单一 __ModuleLoader__ bundle）。
+ * 产物必须提交；CI 只对产物执行 node --check（见 .github/workflows/ci.yml）。
+ *
+ * 编译产物为 CommonJS 格式：require / exports / module 均为本 factory 作用域
+ * 变量（require 由 __ModuleLoader__ 注入，exports/module 为上方局部变量），
+ * 因此产物可直接内联。client 端 TS 源码为单文件（无运行时相对 import），
+ * 需要多文件/复杂打包时可用 esbuild/tsdown（官方 tsdown.client.ts 协议）。
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-ts-example',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    // ── TS 编译产物（scripts/build.mjs 注入）────────────────────────
+    "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inject = void 0;
+exports.apply = apply;
+/**
+ * dsh-ts-example — client 端入口（TypeScript 源码，单文件）。
+ *
+ * 构建流程：`tsc -p tsconfig.client.json` 把本文件编译为 CommonJS 单文件
+ * （lib/.client-build/index.js），scripts/build.mjs 再注入
+ * lib/client.src.js 模板的 __CLIENT_BUNDLE__ 占位符，写出
+ * lib/client.js（DSH 实际服务的 __ModuleLoader__ bundle）。
+ *
+ * 约束：client 端 TS 源码为单文件（无运行时相对 import——编译产物内联进
+ * factory 作用域后，require 只认识 DSH 运行时注入的模块，如 react）。
+ * 类型声明可拆文件（import type 编译期擦除）；需要多文件/复杂打包时可用
+ * esbuild/tsdown（官方 tsdown.client.ts 协议）。
+ *
+ * 演示内容：侧边栏页签「TS 示例」——调 server 端 /ts-example/api/greeting
+ * 显示问候语（client TS → server TS 全链路）。
+ *
+ * 侧边栏走**宿主原生扩展点**（issue #187 批 1），不再消费第三方
+ * dsh-better-sidebar 服务：
+ *   1. `ctx.sidebarRightTabs.register(...)` 注册页面类型（含 guide 胶囊，
+ *      用户从右栏指南页点开）；
+ *   2. keyed 席位 `sidebar.right.pane.tab` 注册面板本体（key = 类型 id）；
+ *   3. keyed 席位 `sidebar.right.pane.tab.title` 注册页签标题。
+ * 原生能力通过 Cordis 服务名 inject 获取（`slots` / `sidebarRightTabs`），
+ * 无需 require 任何 `@deepseek-ai/dsh-client-ui-*` 包 —— 官方生产范本见
+ * dsh-client-ui-sidebar-files/lib/client.js:681-711。
+ */
+const react_1 = require("react");
+// ── 插件体 ─────────────────────────────────────────────────────────────
+/** 页签实现身份（官方惯例：包名；全局唯一）。 */
+const TAB_ID = 'dsh-ts-example';
+/** 页面类型判别符（沿用迁移前 better-sidebar 的 tab id）。 */
+const TAB_KIND = 'dsh-ts-example:greeting';
+/** 指南页相对顺序（沿用迁移前 better-sidebar 的 order）。 */
+const TAB_ORDER = 90;
+exports.inject = ['slots', 'sidebarRightTabs'];
+function apply(ctx) {
+    // 服务缺失（旧宿主）时静默跳过：判空必须同时覆盖 null 与 undefined
+    // （typeof null 是 object，会骗过 === undefined 的写法）。
+    const tabs = ctx.sidebarRightTabs;
+    const slots = ctx.slots;
+    if (tabs == null || slots == null)
+        return;
+    ctx.effect(() => tabs.register({
+        id: TAB_ID,
+        kind: TAB_KIND,
+        title: () => 'TS 示例',
+        guide: [{ order: TAB_ORDER, title: () => 'TS 示例' }],
+    }), 'dsh-ts-example: tab');
+    ctx.effect(() => slots.inject('sidebar.right.pane.tab', () => slots.register({ name: 'sidebar.right.pane.tab', key: TAB_ID }, GreetingTabBody)), 'dsh-ts-example: greeting tab body');
+    ctx.effect(() => slots.inject('sidebar.right.pane.tab.title', () => slots.register({ name: 'sidebar.right.pane.tab.title', key: TAB_ID }, GreetingTabTitle)), 'dsh-ts-example: greeting tab title');
+}
+// ── 原生席位 → 面板适配 ────────────────────────────────────────────────
+/**
+ * 原生 tab body 席位：把原生 props（`sessionId` + `useTabInfo` hook）
+ * 适配成面板契约（`scope.sessionId` + `visible`），面板本体零改动。
+ * `useTabInfo` 缺失（契约不匹配）时保守取 visible=true，只影响轮询。
+ */
+function GreetingTabBody(props) {
+    const visible = props.useTabInfo?.()?.tab?.visible ?? true;
+    return (0, react_1.createElement)(GreetingPanel, { scope: { sessionId: props.sessionId }, visible });
+}
+/** 原生 tab title 席位：优先用宿主给定的标题（i18n 由文档标题决定）。 */
+function GreetingTabTitle(props) {
+    return (0, react_1.createElement)('span', null, props.useTabInfo?.()?.tab?.title ?? 'TS 示例');
+}
+// ── 页面组件 ───────────────────────────────────────────────────────────
+function GreetingPanel(props) {
+    const [greeting, setGreeting] = (0, react_1.useState)('');
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    (0, react_1.useEffect)(() => {
+        if (!props.visible)
+            return;
+        let cancelled = false;
+        fetch(`/ts-example/api/greeting?name=${encodeURIComponent(props.scope?.sessionId ?? '')}`)
+            .then((response) => response.json())
+            .then((body) => {
+            if (!cancelled) {
+                setGreeting(body.greeting ?? '');
+                setLoading(false);
+            }
+        })
+            .catch(() => {
+            if (!cancelled) {
+                setGreeting('(请求失败)');
+                setLoading(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [props.visible, props.scope?.sessionId]);
+    return (0, react_1.createElement)('div', { style: { padding: '12px', fontFamily: 'var(--dsw-font-sans)' } }, (0, react_1.createElement)('h3', null, 'TS 示例插件'), (0, react_1.createElement)('p', null, loading ? '加载中…' : greeting), (0, react_1.createElement)('p', { style: { color: 'var(--dsw-alias-text-tertiary)', fontSize: '12px' } }, 'server 端由 TypeScript 编写（tsc 编译），client 端由 TypeScript 编写（构建时编译）。'));
+}
+
+
+    return module.exports
+  },
+})

package/lib/client.src.js

@@ -0,0 +1,28 @@
+/**
+ * dsh-ts-example — client half (browser). SOURCE TEMPLATE.
+ *
+ * BUILD NOTE: 本文件是模板源码，不是 DSH 实际服务的文件。scripts/build.mjs
+ * 先运行 `tsc -p tsconfig.client.json` 把 src/client/index.ts 编译成
+ * CommonJS 单文件（lib/.client-build/index.js），再注入下方
+ * /*__CLIENT_BUNDLE__* / 占位符（函数式 replaceAll，避免 $&/$1 特殊解释），
+ * 写出 lib/client.js —— 即 DSH 实际服务的产物（单一 __ModuleLoader__ bundle）。
+ * 产物必须提交；CI 只对产物执行 node --check（见 .github/workflows/ci.yml）。
+ *
+ * 编译产物为 CommonJS 格式：require / exports / module 均为本 factory 作用域
+ * 变量（require 由 __ModuleLoader__ 注入，exports/module 为上方局部变量），
+ * 因此产物可直接内联。client 端 TS 源码为单文件（无运行时相对 import），
+ * 需要多文件/复杂打包时可用 esbuild/tsdown（官方 tsdown.client.ts 协议）。
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-ts-example',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    // ── TS 编译产物（scripts/build.mjs 注入）────────────────────────
+    /*__CLIENT_BUNDLE__*/
+
+    return module.exports
+  },
+})

package/lib/greeting.js

@@ -0,0 +1,14 @@
+/**
+ * dsh-ts-example — greeting 纯函数（server 端逻辑）。
+ *
+ * 独立成模块以演示：TS 模块拆分 + 类型检查（interface / 联合类型 /
+ * 可选参数）+ 单元测试直接 import 编译产物。
+ */
+/** 生成问候语：空名回退默认问候，非空名去除首尾空白后拼接。 */
+export function buildGreeting(options) {
+    const name = options.name.trim();
+    if (name === '') {
+        return options.language === 'zh' ? '你好，DSH！' : 'Hello, DSH!';
+    }
+    return options.language === 'zh' ? `你好，${name}！` : `Hello, ${name}!`;
+}

package/lib/index.js

@@ -0,0 +1,92 @@
+/**
+ * dsh-ts-example — server 端入口（TypeScript 源码）。
+ *
+ * 本文件是 TS 插件 server 端的示例：`tsc -p tsconfig.json` 编译为
+ * lib/index.js（产物必须提交，CI 只跑 node --check + 测试，不跑构建）。
+ *
+ * 演示内容：
+ *  - 类型检查：import 不存在的模块 → TS2307 编译期报错（#39 的
+ *    require('dsh-md-render') 类错误在 TS 下不可能发版出去）；
+ *  - 路由：GET /ts-example/api/greeting?name=xxx → { greeting }；
+ *  - 事件：session/start 计数，GET /ts-example/api/stats → { sessions }；
+ *  - 信任围栏：非 loopback 来源 403（与 /api 网关一致的契约）。
+ */
+import { buildGreeting } from './greeting.js';
+export const name = 'dsh-ts-example';
+export const inject = ['webServer'];
+// config 可能缺省：DSH 对未声明 config schema 的插件调用 apply(ctx) 时
+// 第二个参数为 undefined（cordis 契约），必须用可选链兜底，否则 TypeError。
+/**
+ * root 上的注册表（以 root ctx 为键）。
+ *
+ * ⚠️ 教学要点（issue #242 实测，DSH 0.1.5-rc.1）：profile 插件的 fiber 会被 loader
+ * 在 apply 结束后回收，**注册在插件自身 ctx 上的监听器与路由会随之静默消失**——
+ * 事件 0 触发、路由返回 404，且**没有任何报错**。所以本样例的所有注册都挂到
+ * **常驻 ctx.root**，并以 root 为键去重（loader 会多次 apply 同一插件，重复注册会
+ * 让同一事件被处理多次）。照抄本样例时，**不要把 root 改回 ctx**。
+ */
+const rootRegistrations = new WeakMap();
+export function apply(ctx, config) {
+    const language = config?.language ?? 'en';
+    let sessionCount = 0;
+    const listenCtx = ctx.root ?? ctx;
+    for (const dispose of rootRegistrations.get(listenCtx) ?? [])
+        dispose();
+    const disposers = [];
+    // ── 事件监听：会话开始计数（演示 ctx.on；注册在常驻 root）──────────
+    disposers.push(listenCtx.on('session/start', () => {
+        sessionCount += 1;
+    }, { global: true }));
+    // ── 路由：greeting + stats（注册在常驻 root，自持 disposer）────────
+    const webServer = ctx.webServer ?? listenCtx.webServer;
+    if (webServer !== undefined) {
+        disposers.push(webServer.register({
+            kind: 'prefix',
+            path: '/ts-example/api',
+            handler: (request, response) => {
+                if (!isTrustedRequest(request)) {
+                    writeJson(response, 403, { ok: false, error: 'forbidden' });
+                    return;
+                }
+                const path = request.url?.split('?')[0] ?? '';
+                if (path === '/ts-example/api/greeting') {
+                    const name = readQueryParam(request, 'name');
+                    writeJson(response, 200, { greeting: buildGreeting({ name, language }) });
+                    return;
+                }
+                if (path === '/ts-example/api/stats') {
+                    writeJson(response, 200, { sessions: sessionCount });
+                    return;
+                }
+                writeJson(response, 404, { ok: false, error: 'not found' });
+            },
+        }));
+    }
+    rootRegistrations.set(listenCtx, disposers);
+}
+/** 请求是否来自本机（loopback 信任围栏）。 */
+function isTrustedRequest(request) {
+    const host = request.headers.host;
+    if (typeof host !== 'string')
+        return false;
+    try {
+        const hostname = new URL(`http://${host}`).hostname;
+        return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/** 读取查询参数（request.url 的 query 部分）。 */
+function readQueryParam(request, key) {
+    const url = request.url ?? '';
+    const queryIndex = url.indexOf('?');
+    if (queryIndex < 0)
+        return '';
+    return new URLSearchParams(url.slice(queryIndex + 1)).get(key) ?? '';
+}
+/** 写 JSON 响应。 */
+function writeJson(response, status, body) {
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(body));
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dsh-ts-example",
+  "version": "0.1.0",
+  "description": "DSH 插件 TypeScript 开发示例：server 端 tsc 编译（lib/index.js 产物）、client 端构建时编译（__ModuleLoader__ bundle），演示编译期类型检查（TS2307 模块不存在、类型不匹配等）。DSH web plugin: TypeScript development example — tsc-compiled server half + build-time-compiled client half.",
+  "type": "module",
+  "main": "lib/index.js",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "npx tsc -p tsconfig.json && node scripts/build.mjs",
+    "typecheck": "npx tsc --noEmit -p tsconfig.json && npx tsc --noEmit -p tsconfig.client.json",
+    "test": "npx vitest run --coverage"
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "assets"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.10",
+    "react": "^18.2.0 || ^19.3.0"
+  },
+  "peerDependenciesMeta": {
+    "cordis": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}