# 技术文档：dsh插件名称修改

## 1. 项目概述

**dsh插件名称修改** 是一个 DeepSeek Harness (dsh) 插件，功能是在原生插件设置列表里，把英文包名替换成用户自定义的中文备注名。

### 核心需求
- 用户安装了很多插件，英文包名不好记
- 希望在原生插件列表里直接看到中文备注名
- 不需要打开独立的管理页面，直接在原生设置页就能看到和修改

### 解决方案
- Host 端：极简 Cordis 插件，只负责注册
- Client 端：纯 DOM 操作脚本，通过 `window.__ModuleLoader__.load()` 注入到浏览器页面
- 用 MutationObserver 监听页面变化，动态替换插件列表里的文字

---

## 2. 技术架构

### 2.1 整体结构
```
┌─────────────────────────────────┐
│           dsh 主应用             │
├─────────────────────────────────┤
│  ┌───────────┐  ┌─────────────┐ │
│  │ Host 端   │  │  Client 端   │ │
│  │ (Node.js) │  │ (Browser JS)│ │
│  │           │  │             │ │
│  │ 注册插件   │  │ DOM 替换    │ │
│  │ 无业务逻辑 │  │ 编辑面板    │ │
│  └───────────┘  └─────────────┘ │
└─────────────────────────────────┘
```

### 2.2 Host 端（lib/index.js）
- 极简 Cordis 插件，只导出 `name`、`inject`、`apply`
- 不做任何业务逻辑，只是占位
- 作用：让 dsh 识别这是一个有效插件

### 2.3 Client 端（lib/client.js）
- 通过 `window.__ModuleLoader__.load()` 格式加载
- 功能模块：
  1. **备注存储**：用 localStorage 保存用户自定义的备注映射
  2. **文字替换**：扫描页面上的插件列表，把英文包名替换成中文备注
  3. **编辑面板**：可视化编辑界面，点击按钮弹出
  4. **快捷键**：Ctrl+Shift+N 打开/关闭面板
  5. **MutationObserver**：监听页面变化，React 重新渲染后自动重新替换

---

## 3. 核心实现原理

### 3.1 客户端加载机制
dsh 的客户端插件不是直接打包成 React 组件的，而是通过 `window.__ModuleLoader__.load()` 格式注入：

```js
window.__ModuleLoader__.load({
  id: 'dsh-plugin-nickname',
  factory: () => {
    return {
      name: 'plugin-nickname-client',
      inject: [],
      apply(ctx) {
        // 客户端逻辑
      }
    };
  }
});
```

### 3.2 文字替换原理
1. 遍历页面上所有的 `div`、`span`、`h2`、`h3` 元素
2. 检查元素的文本内容是不是匹配已知的插件包名
3. 如果匹配，就把文本替换成中文备注
4. 给元素打上标记 `data-nickname-processed`，避免重复处理

### 3.3 持久化存储
- 用户修改的备注保存在 `localStorage` 的 `dsh_plugin_nicknames` 字段
- 格式是 JSON 对象：`{ "包名": "中文备注" }`
- 刷新页面后自动读取，继续生效

### 3.4 编辑面板
- 左下角浮动按钮，点击弹出编辑面板
- 面板里列出所有已安装的插件（自动扫描页面）
- 每个插件后面有输入框，直接修改中文备注
- 修改后自动保存，实时生效

---

## 4. 配置文件说明

### 4.1 package.json
```json
{
  "name": "dsh-plugin-nickname",
  "type": "module",
  "exports": {
    ".": "./lib/index.js",
    "./client": "./lib/client.js"
  },
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    },
    "client": {
      "platform": "web",
      "inject": [
        "@deepseek-ai/dsh-client-locale",
        "@deepseek-ai/dsh-client-ui-slots"
      ]
    }
  }
}
```

### 4.2 cordis.patch.yml
```yaml
- insert:
  - id: plugin-nickname
    name: 'dsh-plugin-nickname'
```

作用：告诉 dsh 要加载这个插件。

---

## 5. 已知问题与限制

1. **按钮可能被 React 重新渲染冲掉**：已经用 MutationObserver 持续监听，按钮不见了就自动重新加上
2. **文字替换是基于文本匹配的**：如果 dsh 的插件列表 DOM 结构变了，可能匹配不到
3. **只支持中文备注**：目前只做了中文，其他语言也能用，但默认是中文
4. **桌面版和 Web 版都能用**：因为都是 Web UI，只是外壳不一样

---

## 6. 开发与发布

### 本地开发
1. 修改代码后，重新打包 zip
2. 在 dsh 里卸载旧插件，重新安装本地目录
3. 刷新页面测试

### 发布到 npm
1. 登录 npm
2. `npm publish`
3. 用户就可以通过 `dsh plugin add dsh-plugin-nickname` 安装了

---

## 7. 许可

MIT License