# @tsxapp/dsh-plugin **简体中文** | [English](README.md) DeepSeek Harness（DSH）插件：把 tsxapp 接进 DSH 的三处 —— **一个 skill**，**一个侧边栏标签页**， **一个工具**。 - **skill 注入**：宿主半边注册一个 `tsxapp` 技能，agent 于是知道 `.app.tsx` 的契约： 默认导出一个不接收参数的组件、能力从 `@tsxapp/runtime` 导入、权限模型、Tailwind。 装插件即得技能，卸载即失效 —— 不往 `~/.dsh/skills/` 里写文件。 - **侧边栏**：浏览器半边注册一个标签类型，`patterns: ['*.app.tsx']`。在右侧文件树里 点开任何 `*.app.tsx`，出来的不是纯文本，而是这个应用的标签页：**页面直接画在标签里** （内嵌 iframe，不弹系统浏览器）、启动动画、运行状态、实时日志、带行号的源码。 顶栏右侧两颗工具：「重启并刷新」（停掉服务再起来，并把 iframe 整个换新 —— 改完源码不想等 HMR、或页面状态已经跑飞时用）和「在浏览器打开」。关掉标签，服务跟着停。 起不来时那颗「**帮我修复**」会在**当前工作区**里开一个新会话，让 agent 带着整个工程的上下文 去修（不是只看 `foo.app.tsx` 那一层子目录）；应用**运行时**报错会报一条**不挡路的横幅** （宿主自带的 `Toast`），要看堆栈才展开详情。 - **文案跟随宿主的语言设置**：字典注册在 DSH 的 locale 服务上（命名空间 `tsxapp`，中英两份）， 界面按宿主当前语言显示，切语言即时生效 —— 不看浏览器语言。 - **工具**：`tsxapp_preview` —— agent 改完代码调一次：**类型检查 → 起服务 → 截图**。 截图**作为图片直接回在工具结果里**（模型自己看得见页面），报告里给服务地址与尺寸；同时把标签 在侧边栏打开，人和模型看的是同一个页面。类型检查没过就直接回报告（不起服务、不截图）。 （上一版那个独立的 `tsxapp_check` 已经并进这里：对 agent 来说，动作永远只有「改完 → 看一眼」。） ## 源码与构建 源码在 `src/`：宿主半边是几个 `.ts`，浏览器半边是 `src/client/` 目录下的 tsx 组件。 两边**各有自己的 tsconfig**，因为它们活在两个世界里（Node vs DOM + JSX）： | 入口 | 产物 | 跑在哪 | tsconfig | | --- | --- | --- | --- | | `src/index.ts` | `dist/index.js` | Node（DSH 宿主进程） | `tsconfig.host.json` | | `src/client/index.tsx` | `dist/client.js` | 浏览器（DSH 客户端模块表） | `tsconfig.client.json` | `tsconfig.json` 现在只是两者共用的 base（`files: []`，不自己编译任何东西）。 ```bash pnpm dsh:build # tsdown -c packages/dsh/tsdown.config.ts（两份配置，先 host 后 client） pnpm dsh:typecheck # tsc -p tsconfig.host.json && tsc -p tsconfig.client.json pnpm dsh:test # 跑单元测试（vitest，会先 build） ``` 四件值得知道的事： - **skill 正文是静态导入的**。`src/skill.ts` 直接 `import '../skill/SKILL.md'`，由 `tsdown.config.ts` 里的 `markdownText` 插件在构建时变成字符串常量 —— 运行期不读磁盘， 少一个「文件不在原位」的失败点。`skill/` 目录仍然随包发布，因为 `resourceBase` 指向它，模型按需读 `references/*.md` 时走的还是真实文件。 - **`client.js` 必须是经典脚本**。源码是普通 ESM（`import { useState } from 'react'`）， 构建用 cjs 格式让 rolldown 把 import 落成 `require(...)`，再由 `loaderEntry` 插件 套上 `window.__ModuleLoader__.load({ id, factory })`。React 走 `deps.neverBundle` 保持外置 —— 它只存在于宿主的模块表里，包里那点 `@types/react` 只为类型。 JSX 用**生产态**运行时（`react/jsx-runtime`）：`react/jsx-dev-runtime` 不在模块表里， 切过去就是白屏，自测里的 `require` 桩会把这条路堵住。 - **浏览器半边的类型也来自官方包**。`slot` 名、`useTabInfo`、标签定义的形状都是从 `@deepseek-ai/dsh-client-ui-{sidebar-right,renderer,slots}` 合并来的： `PropsRuntime<'sidebar.right.pane.tab'>` 就是正文的 props，`priority` 只能是 `'extension' | 'builtin' | 'fallback'` —— 手抄一份的话这几个字面量早写错了。 - **宿主半边的类型同理**。`src/types.ts` 里没有一行手写的 service 声明：`import type` 官方包触发 cordis 的声明合并（`declare module '@deepseek-ai/cordis'`），再从 `Context` 上切出插件用到的那几个方法。官方改了签名，`dsh:typecheck` 立刻报错。这些包在 `devDependencies` 里，且全是 `import type` —— 宿主产物里一行 `@deepseek-ai` 都不会出现。 浏览器那半边有一个**例外**：`@deepseek-ai/dsh-client-ui-primitives` 是真的要 `require` 的 —— 报错横幅用的 `Toast` / `Modal` / `Button` 必须是宿主的**同一份实例**（它们在 DSH 的 冻结模块表里，见 `client/web/src/seed.ts` 的 `PLATFORM_MODULES`）。自己再打一份，等于在 DSH 的设计语言旁边另立一套，还要多背一份 `react-dom` 和一套焦点管理。 ## 装 ```bash # 先构建（DSH 加载的是 dist/） pnpm dsh:build # 在 DSH 里（profile web 才有浏览器界面） dsh plugin --profile web add /abs/path/to/tsxapp/packages/dsh # 重启 dsh web，刷新页面 ``` 确认挂上了： ```bash dsh --profile web --dump-config | grep -A2 tsxapp-dsh ``` 开发时改完代码 `pnpm dsh:build` 再重启 DSH —— DSH 在启动时锁定插件集合， 热改插件本身不会生效。 ## 怎么起服务：直接调内核，不开子进程 插件**不 spawn `tsxapp` 命令**，而是在 DSH 宿主进程里直接调内核 —— `src/runs.ts` 顶部 就是一句静态导入： ```ts import { chooseLocale, startApp } from '@tsxapp/core' const handle = await startApp({ file, cwd, version, options, logger, banner: false }) handle.url // 带一次性令牌的宿主页地址 await handle.close() ``` 当初把 CLI 和 core 拆开就是为了这个：命令行那层壳（解析参数、打横幅、装 SIGINT 钩子） 对嵌入方全是负担 —— 横幅会刷乱宿主终端，`process.exit(0)` 更会把 DSH 一起关掉。 插件只拿内核交回的 `AppHandle`，没有 pid、没有 exit code。 `startApp` 就住在 `packages/core/src/run.ts`；命令行走的 `runApp` 只是它 + 信号钩子。 ### 谁负责收尾：一条 effect 管一个应用 启动是异步的（要编译），而「停止」随时可能先到。这套时序没有手写状态机 —— 每个文件 对应**一条 cordis effect**： ```ts run.release = ctx.effect(() => () => { ac.abort('stopped') // 让还在飞的启动立刻放弃 return slot.close() // 关句柄；收摊之后才到的句柄，进门那一刻关掉 }, `tsxapp-dsh: ${basename(absolute)}`) ``` 于是「用户点停止」（手动调 `release()`）和「插件被卸载」（fiber 逆序调它）是同一段代码。 插件里因此没有「卸载时遍历在跑的服务」这种循环，也不需要代号去判断一个刚回来的句柄是不是 已经过气 —— 那件事由句柄槽的 `retired` 一次说清（`src/runs.ts`）。 `ctx.getEffects()` 里，每个在跑的应用都是一条带文件名的 effect。 ### 内核在哪儿 内核是本包的**普通依赖** —— `package.json` 里写着 `"@tsxapp/core": "workspace:*"`， pnpm 把它链接到 `packages/core`。代码里就是一句静态 `import … from '@tsxapp/core'`： 仓库内开发、装进 DSH profile、别人机器上 `npm install`，走的都是同一条 Node 解析规则。 **没有** `config.core`、**没有**候选路径列表、**没有**「找不到就试下一个」的兜底 —— 所以也不会出现「内核太旧 / 位置猜错了」这类只在运行期才炸的分支。 代价是失败形态变了：core 装不上时 `dist/index.js` 自己就 import 失败，插件整条不激活 （DSH 会报 `1 entry did not activate`），而不是起来一半再回一句「找不到内核」。 这比静默退化好定位 —— 一眼看出是依赖没装。 记得先 `pnpm build`：内核的入口是 `dist/index.js`，也是类型声明的来源。 ## 配置 `cordis.patch.yml` 里那一行就是配置，`config` 是**整行替换**语义（不是深合并）。 键名与 `tsxapp` 的命令行参数一一对应： ```yaml - insert: - id: tsxapp-dsh name: '@tsxapp/dsh-plugin' config: port: 5173 # 起始端口，被占用时内核会顺延 allow: [] # 启动即放行的规则，写法同 --allow deny: [] startTimeoutMs: 20000 # 等内核起好的上限 ``` 可用的键：`port` `host` `hmr` `accessControl` `typecheck` `persistPermissions` `allow` `deny` `title` `verbose` `locale` `startTimeoutMs`。 没有 `core`（内核是静态依赖，位置不开放配置），也没有 `open`（打开浏览器是顶栏那颗链接 的事，内核自己不管）。 `typecheck`（默认 `true`）就是启动前那次类型 / 语法检查：有错时启动会失败，侧边栏的 日志里是那份报告（和命令行同一份文案），改好再点一次就行；要绕过就写 `typecheck: false` （等价于命令行的 `--no-typecheck`）。 `allow` 适合「打开就该能用」的能力，例如： ```yaml config: allow: ['fs.list:.', 'fs.read:./data/**'] ``` 没写进 `allow` 的能力，仍然是运行时弹窗授权（宿主页 Monitor 面板里可以点「始终允许」/ 「始终拒绝」把这一次的选择沉淀成规则）。 ## 侧边栏里是什么 点开任意 `.app.tsx`，标签会**自动启动**它，然后把页面直接画在标签里 —— 不再弹系统浏览器。 **启动中整块标签只有一个加载动画**：一圈渐隐尾巴的环在转，没有文案、没有按钮、没有顶栏和 面板 —— 编译这几秒里没什么值得占位置的信息。跑起来之后才是下面这套外壳： | 区域 | 内容 | | --- | --- | | 顶栏 | 左边一行文件路径（`…/sales/demo.app.tsx`，超长省略、悬停看全路径），右边「重启并刷新」/「截图」/「在浏览器打开」三颗图标（`space-between`） | | 舞台 | 应用页面（`