# dsh-beginner-hub —— DSH 插件注册机制调研笔记

> 调研时间：2026-09-08
> 调研对象：本机 DSH 0.1.2-rc.1（`D:\deepseek_harness_qwen\dsh_data`）随附的官方包源码，
> 即 npx 缓存与 `profiles\node_modules\@deepseek-ai\*`。
> 结论全部来自源码研读，不是猜测；本插件按第 3 节「最简可靠路径」实现。

---

## 1. 结论先行

1. **第三方插件 = npm 包 + 两样东西**：
   `cordis.patch.yml`（挂载声明）+ ESM 入口（导出 `{ name, inject, apply }`）。
2. **第三方插件要往 Web 页面加 UI，当前唯一简单可靠的路是「注入脚本」**：
   用 `ctx.webServer.tapIndex()` 改写返回的 `index.html`，插入自己的 `<script>`；
   前端脚本自绘悬浮面板，数据走插件自己注册的 HTTP 端点。
   官方更完整的「客户端双面插件」体系依赖 monorepo 构建链，第三方目前接不上（见 §4）。
3. **第三方插件必须零运行时依赖**：`dsh plugin add link:<目录>` 是目录链接安装，
   插件文件仍留在源码目录，Node 按真实路径向上解析 import，
   够不到 profile 的 node_modules 依赖树（dsh-whale-widget 只用 Node 内建模块，同因）。

## 2. Profile / Bundle / 行（row）三层结构

- profile 根（`cordis.yml`）是一个**空配置树**：`[]`；
- `package.json` 的 `dsh.profile.bundles` 按顺序列出 bundle 包；
  每个 bundle 可用 `dsh.bundle.patch` 字段指向自己的 `cordis.patch.yml`；
- Loader 把各 bundle 的 patch **按层叠加**成最终配置树，最后再叠用户
  `cordis.patch.yml` 与 `--patch` 覆盖；
- 每个 patch 是一个**行（row）操作**列表：按 `id` 覆盖某行整个 config、
  `disabled` 某行、或 `insert` 新行。新行形如：

  ```yaml
  - insert:
      - id: <行id>
        name: <模块名>        # 可被 require/import 的插件模块
        config: {...}         # 可选
        inject: [服务名]       # 可选
        disabled: true        # 可选
  ```

- 行名解析：官方行用 `name: '@deepseek-ai/dsh-xxx'`（含子路径形式
  `'@deepseek-ai/dsh-web-app/startup'`）；第三方行 `name` 与包同名
  （whale 即 `dsh-whale-widget`），从 profile 的 node_modules 解析。

**证据**：`@deepseek-ai/dsh-web-app/cordis.patch.yml`（web-server 行、client 名录、
agent preset 名录、按 id disable 的行群）；`dsh-whale-widget/cordis.patch.yml`。

## 3. 运行时插件入口的形态（whale 与官方一致）

- `package.json`：`"type": "module"`、`"main": "lib/index.js"`；
- `lib/index.js` 导出：
  ```js
  export const name = '...'          // 插件注册名（与行 id 不必相同：whale 行 id
                                     // dsh-whale-widget、模块 name whale-balance-widget）
  export const inject = ['webServer', 'credentials']   // 声明所需前置服务
  export function apply(ctx) { ... }  // 插件主体，ctx 为 Cordis 上下文
  ```
- `apply(ctx)` 里可用（whale 实证）：
  - `ctx.webServer.register({ kind:'exact', path, handler })`——handler 是 Node
    http 风格 `(req, res)`，用 `res.writeHead(200, headers); res.end(body)`；
  - `ctx.webServer.tapIndex(fn)`——fn 收到将返回给浏览器的 `index.html` 字符串，
    返回改写后的 HTML（在 `</body>` 前插标签即可）；
  - `ctx.credentials.resolve('ENV_NAME')`——返回 Promise，未配置时为 null；
    只可探测存在性，值不可外泄；
  - `ctx.on(...)` 会话事件、`ctx.effect(() => cleanup)` 注册清理。
- `cordis.patch.yml`：`insert` 一行 `{ id, name }` 即可挂载。

**证据**：`dsh-whale-widget/lib/index.js`（register 5 个 `/dsh-whale/*` 端点 +
tapIndex 注入 widget.js）、`@deepseek-ai/dsh-web-app/lib/index.js`
（`const inject = ["webServer"]` + Config schema + `export { Config, apply, inject, name }`）。

## 4. 官方「客户端双面插件」体系（第三方暂不可用的那套）

- 每个 client UI 包是**双面**包：
  - 宿主面 `lib/index.js`：空 `apply()`，只为了让该行出现在 Loader；
  - 浏览器面 `exports["./client"]`：被 `package.json` 顶层 `dsh.client` 字段声明
    （`{ inject: [...], platform: 'web' }`），在浏览器 Cordis kernel 里作为插件加载，
    通过 `declare module '@deepseek-ai/cordis' { interface Context { ... } }` 提供服务
    （`ctx.layout`、`ctx.session` 等），并往**槽位（slot）**注册 UI 组件：
    根槽 `root`、侧栏 `sidebar`、会话 `conversation`、右栏 `details`，
    以及**追加式列表槽 `shell.overlay`**（官方注释：加浮层入口就加这个槽的条目）。
- 浏览器端加载链路：`dsh-client-modules` 宿主面把 client 名录编成
  `window.__DSH_BOOT__` 图（内容寻址 combo bundle + rev），模块系统
  （`__ModuleLoader__`）在 cordis 存在前构造模块表，HMR 通过 `loadBundle` 缝隙换包。
- **为什么第三方接不上**：这些 combo bundle 由官方 monorepo 的构建链
  （tsdown/Vite）产出并内嵌在前端 dist 里；`dsh-client-hmr` 只在官方
  `pnpm run dev:web` watcher 跑着时才换包。第三方包没有这条发布通道，
  也没有从 dist 外动态注入 client 模块的公开入口。

**证据**：
`dsh-client-ui-commands/package.json`（exports["./client"] + dsh.client 声明）、
`dsh-client-ui-layout/lib/types/client/index.d.ts`（SlotMap：sidebar/conversation/details/
shell.overlay 语义）、`dsh-client-modules/lib/types/client/manifest.d.ts`
（WebBootGraph/WebBootEntry：组合条目图）、`dsh-web-frontend/dist/index.html` +
`index-*.js` 里的 `__ModuleLoader__`/`__DSH_BOOT__` boot 代码。

## 5. 对 dsh-beginner-hub 的落地

- 采用 §3 形态：零依赖包 + `{name,inject,apply}` + tapIndex 注入
  `<link hub.css>` 与 `<script defer hub.js>`；
- 面板数据全部走插件自注册端点（`/dsh-beginner-hub/{hub.js,hub.css,data.json,status.json}`），
  不依赖任何 DSH 内部 API / 页面结构；
- 环境自检读 `$DSH_HOME/settings.yaml`（工具生成的稳定 YAML，见
  `lib/settings-lite.js` 的取舍说明）与 `ctx.credentials`、Ollama 本地接口；
- 「填入新会话 / 打开设置」属于跨应用 DOM 桥接，做成尽力而为 + 降级提示
  （§4 说明为什么拿不到官方句柄），面板观感需人工在浏览器确认。

## 7. 补充：v0.1.1 对 composer 的实锤（2026-09-08，headless DOM 侦察）

真实页面 DOM 显示 DSH 0.1.2-rc.1 的输入框**不是 textarea**：

```html
<div contenteditable="true" role="textbox" aria-multiline="true"
     data-composer-input="true" data-lexical-editor="true"
     data-phase="plain" class="uV2eYG_input" ...></div>
```

- `data-composer-input="true"` 是应用自己的输入框钩子；`data-lexical-editor`
  表明底层是 Meta Lexical 富文本编辑器 —— DOM 只是 EditorState 的渲染结果；
- 因此 v0.1.0 直接写 `textContent` 必然失效（文字不进 EditorState，发送读空）；
- 正确写入 = 聚焦 + 光标置尾 + `document.execCommand('insertText')`，走浏览器
  原生 beforeinput/input 管线，Lexical/React 都会据此更新内部状态（等价真实打字）；
- 「新建会话」按钮在左侧栏，aria/文本含「新建会话」（类名 hHd-Xa_newSession 不入代码，
  只用文本/aria 探测）。

E2E 证据：见 docs/verification-log.md「第二轮」。

## 8. 补充：v0.2.0 Skills/插件机制调研（2026-09-08，决定第④页文案）

来源：本机 DSH 0.1.2-rc.1 安装内的官方包 README（zh）与 dump-config 实锤：
`@deepseek-ai/dsh-skill-filesystem/README.zh.md`、`@deepseek-ai/dsh-skill/README.zh.md`、
`@deepseek-ai/dsh-client-ui-skill/README.zh.md`、`dsh-client-ui-settings-plugin-inventory`
与 `dsh-host-plugin-inventory` README；`dsh --profile web --dump-config` 组成树。

### Skill 的存储与发现（filesystem 提供方）
- Skill = 扫描根目录下的一级子目录 bundle（内含 `SKILL.md`）或平铺 `<name>.md`；
  YAML frontmatter 必填 `name` + `description`；不支持嵌套 `**/SKILL.md`；
- 默认扫描根（rank 序）：`<projectRoot>/.dsh/skills` → `<projectRoot>/.agents/skills`
  → customSkillDirs → `<dshHome>/skills` → `<~/.agents>/skills`（dshHome = $DSH_HOME）；
- 实时监视：新增/改名/删除无需重启，下一个模型步骤即可见；编辑正文无需缓存失效。

### Skill 的调用（web UI）
- 聊天输入框键入 `/技能名`：建议菜单（skills/list Remote）列出“用户可调用”的 skill，
  选中落下字面 `/name`；发送后宿主（dsh-tool-skill）把该 skill 作为说明书注入，
  对话里渲染可展开的 Instructions 卡片；
- 面向模型自动调用由 description 触发（模型目录 + loader），无需用户手动操作。

### 现状结论（第④页文案的事实边界）
- **没有**“技能商店 / 一键安装按钮 / 图形化管理页”（v0.1.2-rc.1）；
- 最友好的安装路径 = 把文件夹放进扫描根（推荐 `<DSH_HOME>/skills`，即本机
  `D:\deepseek_harness_qwen\dsh_data\skills`），或直接让 DSH 帮你写好并放入；
- 设置 →「插件」分区 = 只读插件列表（官方 README 原文：“它不能启用、停用、添加或移除插件”）；
  装/卸插件只能命令行 `dsh plugin --profile web add/remove`；
- 故第④页：B 节列“几种装法”并如实说明无图形入口；C 节给挑选标准而非编造技能名；
  D 节的管理=改/删文件夹 + 常见不生效原因（目录/缺 frontmatter/需新会话）。

## 9. 补充：v0.3.0 生态调研与技能扫描（2026-09-08）

### 值得装清单的事实来源
[awesome-dsh-plugin/awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
README（2026-09-08 实抓）：收录规则 = 能用 `dsh plugin add` 安装 + 声明 `dsh.bundle` +
描述经人工核实，插件页还带讨论区；官方仓库 deepseek-ai/deepseek-harness（GitHub API 实证存在）。
从中选了 7 个对“AI 应用岗求职学生”真正有用且可核实源的项目（见 lib/content/skills-catalog.js
与 README），每个都带 GitHub 链接、如实标注 kind（plugin/skill）与安装命令。
生态事实：DSH 社区把“技能”大多打包成**插件 bundle** 分发（装后技能经 ctx.skills 注册，
用法仍是输入框打 /技能名），与手写进扫描目录的本地技能并存；装第三方插件=运行第三方代码，
列表本身也带安全警告（已如实转述进 UI）。

### 技能扫描端点（skills.json，服务端）
复刻官方 dsh-skill-filesystem 的默认扫描根：项目 `.dsh/skills`(rank100) → 项目
`.agents/skills`(200) → `<DSH_HOME>/skills`(400) → `~/.agents/skills`(500)，可选
$DSH_BUNDLED_SKILL_DIR(600)；只读解析各 SKILL.md/平铺 .md 的 frontmatter（name/description），
同名取 rank 胜出，全程容错不抛错。实测：临时实例真实列出 `~/.agents/skills` 下两个已装技能
（coze-agent-collaboration / using-coze-cli，含描述）。
注意：项目根取自进程 cwd 向上找 .git——从不同目录启动 dsh web，扫到的“项目书架”不同；
用户级书架（DSH_HOME/skills 等）与 cwd 无关。

### v0.3 本地分类器的设计约束
意图→方案全部做成数据表（lib/content/router-data.js：7 类意图 × keywords + ask 变体 +
advanced 玩法；兜底=万能提问公式），识别算法 classify() 为纯前端关键词打分，零网络；
“换模型理解”只需替换 classify() 一个函数，数据结构不变——这就是预留的 API 开关位
（UI 层面暂无开关，v1 不接）。

## 10. 补充：技能模块扩展——发现/一键装/已装管理（2026-09-09）

### 安装路线的机制核实（GitHub API 实测仓库结构）
- mattpocock-skills-dsh-zh / dsh-skill-7d-code-reviewer / dsh-starter-zh 等“技能仓库”根目录
  均为插件 bundle（cordis.patch.yml + package.json，dsh.bundle 形态），技能本体在仓库内
  skills/（mattpocock 有 25 个一等技能目录）或 src 等子目录 → 整仓默认按插件处理：
  一键装 = 自动调 dsh plugin CLI（本进程从 argv[1] 反推定位 dsh.cmd，cmd /d /c 无引号拼接）；
- 指名子目录（subPath，如 skills/code-review）→ 无论整仓形态，都按技能文件夹直装：
  复制进 <DSH_HOME>/skills（rank 400 用户书架，新会话即被发现）；
- 停用/启用机制：官方 filesystem 提供方不支持嵌套 SKILL.md → 移入 <root>/disabled/ 即停用、
  移回即启用；卸载 = 移入 <root>/.trash/（可恢复），全程只动技能目录内部；
- 下载用 codeload tarball（HEAD/master 回退）+ 系统自带 tar 解压（Windows System32\tar.exe）；
  附 DSHB_ARCHIVE_URL 环境注入点（仅测试用，对用户透明）——本环境 codeload 从 dsh 进程
  下载超时，故用本地归档完成“下载→解压→分类→入书架→启停→卸载→日志”8/8 全链验证；
- GitHub 搜索由前端直调 api.github.com/search/repositories（CORS 可用），403/429 优雅降级
  提示；结果与清单一键装共用安装管线（二次确认）。

## 11. 补充：规格调整——撤销自研管理后端（2026-09-09，§10 的后续决策）

用户查过 GitHub 后拍板：技能管理交给成熟生态插件，不自研（避免重复造轮子）。
因此 §10 描述的“GitHub 搜技能 / 自研一键装 / 启停卸载 / .trash 回收站”方案被**撤销**：
删除 lib/skill-ops.js 与 POST /skills/action、/install、/ops 端点，前端技能页改为只读
“已装一览 + 引导装管理器”；路由方案B 对未装技能只给链接 + “用 dsh-skill-manager 装”提示。

管理器候选经 GitHub API 逐仓库核实（2026-09-09）：
sulfide2085/dsh-skill-manager（★11）、MichengAI/dsh-skills-manager（★38）、
zhengjy01/dsh-skill-studio（★3）。检测端点 GET /managers.json 只读判断它们是否已装
（看 web profile package.json 里包名是否出现），未装则在技能页给出与描述一致的一键装命令。

定位差异（写入 README）：本插件 = “需求路由 + 新手引导”；技能/插件的安装、搜索、启停管理
属于生态成熟插件（dsh-skill-manager 等）的职责，不再重复实现。
保留的只读扫描模块 skill-scan.js 服务于“已装一览”（帮助小白认识自己已有什么）。

## 6. 附：本机验证环境（2026-09-08）

- DSH CLI 0.1.2-rc.1：`C:\Users\10464\AppData\Local\npm-cache\_npx\1e7f6d9597241db0\node_modules\.bin\dsh.cmd`
- DSH_HOME：`D:\deepseek_harness_qwen\dsh_data`（**不是** `D:\deepseek_harness_qwen`）
- web profile：`D:\deepseek_harness_qwen\dsh_data\profiles\web`
- 默认端口 3080（`dsh web --help`：`--host/--port/--trusted-host/--no-open`）