# dsh-ui-web

> 为 DSH 设置页提供 Web UI 全家桶的聚合卡片、可编辑的常驻人格（猫娘小咪预设）以及关于版权页；保存人格后 DSH 技能系统自动热加载。

## Metadata

- Author: [@CAPTAIN1275](https://github.com/CAPTAIN1275)
- Repo: <https://github.com/CAPTAIN1275/dsh-ui-web.git>
- GitHub: [CAPTAIN1275/dsh-ui-web](https://github.com/CAPTAIN1275/dsh-ui-web)
- Stars: 34
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Topics: `dsh-plugin`, `dsh-plugin-market`, `dsh-plugins`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-16T18:08:27.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-web-ui-settings
```

## Wiki

## 一句话定位
DSH 设置页的「Web UI 全家桶」容器插件：把整个 dsh-web-ui 家族的功能插件折叠成设置页里的一张聚合卡片，并自带一个可编辑的「常驻人格」编辑器（默认提供猫娘小咪）和一个版权说明页。

## 核心能力
- 在设置页「插件配置」区插入一张「Web UI 插件」组卡，所有家族功能插件的启用开关与配置表单都收纳在这张卡里
- 提供设置页「人格设定」分区：开关、名称、描述、Markdown 正文四件套，一键填充「小咪」猫娘预设，保存即生效
- 提供设置页「关于」分区：展示当前插件版本、基于的上游项目、第三方资源版权与商标声明
- 后台 HTTP 路由：读取/写入人格配置、列出内置人格预设、查询聚合包版本（用于「检查更新」）
- 启用人格时自动在用户级技能目录生成对应的 SKILL.md，DSH 技能系统热加载，无需重启

## 技术实现
- **语言**: TypeScript（ESM，target web）
- **关键依赖**: @deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver、@deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-settings
- **架构模式**: 双端插件——host 端（Node）注册 `/api/persona/*` 与 `/api/web-ui/version` 路由，client 端（浏览器 React）注册 `settings.plugin.item` 组卡与 `settings.section` 中的两个分区
- **入口文件**: `src/index.ts`（host apply）+ `src/client/index.ts`（client apply）

## 适用场景
用 dsh-web-ui 全家桶（含看板、皮肤、SSH、看板娘等）但希望设置页不要被十几张独立卡片刷屏的用户。它把家族插件收纳为一张可折叠的「Web UI 插件」卡，并提供一个常驻人格编辑器（猫娘、虚拟伴侣、助手语气定制都能写）。

## 前置依赖与兼容性

| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH（host + client）| 0.1.0-rc.6+ | peerDependencies 锁定的官方包均为 ^0.1.0-rc.6 |
| Node.js | 未声明 | 源码未在 engines 中声明，遵循宿主要求 |
| 平台 | 仅 Web | package.json#dsh.client.platform = web |
| 原生模块 | 无 | 不引入 node-gyp 模块 |

## 安装方式

```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-web-ui-settings
```

## 配置项
本插件无需额外配置。它是设置页的容器，本身不暴露 `ctx.config.*` 字段。用户可编辑的内容是「人格设定」分区的表单（开关、技能名、描述、正文），保存后写到 `~/.dsh/persona.json` 与 `~/.dsh/skills/catgirl-rp/SKILL.md`，与插件配置无关。

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 启用人格 | 开关 | 是否常驻生效（关闭时 SKILL.md 被改名暂存） | 开 |
| 技能名 | 文本 | 必须是「小写字母/数字/短横线」，会作为 SKILL.md 所在目录名 | catgirl-rp |
| 描述 | 多行文本 | 写入 SKILL.md 的 frontmatter `description`，建议包含「Use when」 | 内置猫娘描述 |
| 人格设定正文 | Markdown | 写入 SKILL.md 主体，每次对话的回复依据 | 内置猫娘正文 |

## 常见问题

**Q: 装上后没有可见效果，是不是没生效？**

A: 这个插件是「设置页容器」型插件：装上后本身不会改变对话体验。它只会在 DSH 设置页多出「Web UI 插件」「人格设定」「关于」三个分区。要看到它承载的其他插件（如看板、皮肤）需要同时安装 `dsh-web-ui-all` 聚合包或其它家族包。

**Q: 装上后人设就启用了吗？怎么关掉或改写？**

A: 默认会启用「小咪」猫娘人格（每次对话都以小咪身份回应）。打开 DSH 设置页「人格设定」分区，关掉顶部开关即可停用，或编辑正文后点「保存」立即覆盖，无需重启。

**Q: 人格保存后写到哪里？为什么对话立即生效？**

A: 保存时写入 `~/.dsh/persona.json`，同时在 `~/.dsh/skills/catgirl-rp/SKILL.md` 生成一份技能文件，DSH 技能系统（dsh-skill-filesystem）热加载该技能，所有新对话自动套用。禁用时 SKILL.md 会被改名成 SKILL.md.disabled 而不是删除，再启用就恢复。

**Q: 「关于」里显示的版本号是怎么来的？为什么有时显示「未知」？**

A: 插件启动时读自身 package.json 拿到 current 版本，并在每次请求时去 npm registry 拉 `@captain1275/dsh-web-ui-all` 的最新版本做对比，8 秒内没拿到就当作查不到（latest 为 null），前端就会显示「未知」。这不影响使用，只影响更新提示。

**Q: 这个插件能在桌面版/CLI 版用吗？**

A: 不能。它在 package.json#dsh.client.platform 里声明 platform: web，只注入到 Web 设置页。DSH 桌面客户端走的是另一套 UI，需要装对应分支的 dsh-web-ui-settings 包。

**Q: 我想完全卸载，连同猫娘人格一起清除，该怎么操作？**

A: 先在设置页「人格设定」分区关掉开关（或点保存覆盖为空内容），让 `~/.dsh/skills/catgirl-rp/` 被改名暂存；然后用 `dsh plugin --profile web remove` 卸载插件包；最后手动删除 `~/.dsh/persona.json` 与 `~/.dsh/skills/catgirl-rp/` 残留目录即可彻底清除。

## 上手难度
入门 — 装上即生效；不需要写代码，普通用户在设置页点几下就能编辑人格、查看版本、收拢家族插件卡片。

## 已知问题与限制
- 「检查更新」功能强依赖 npm registry 可达性；离线或网络受限时永远显示「未知」，没有重试也没有降级提示
- 默认行为激进：装上后人格就处于「常驻启用」状态且内容是一只猫娘人格，不熟悉的用户第一次进对话可能会被猫娘语气吓到，需要到设置页主动关掉
- 默认写入 `~/.dsh/skills/catgirl-rp/SKILL.md` 的目录名是硬编码的「catgirl-rp」，跟「小咪」人格内容强绑定；改成严肃人格后目录名还叫 catgirl-rp，需要一并改技能名
- 插件本身没有 `engines.node` 声明，Node 版本兼容性完全由宿主 DSH 决定

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-ui-web](https://deepseek-plugin.org/plugins/CAPTAIN1275/dsh-ui-web/packages/dsh-web-ui-settings)
Wiki generated by AI (model: `MiniMax-M3`)