lansi-ai/dsh-plugin-starter

dsh-plugin-starter

目录结构

dsh-plugin-starter/
├── SKILL.md                    # DSH 技能文件：完整开发流程 + 工具/路由/UI 开发 + 模式 + 踩坑清单 + 命令速查
├── templates/                  # 可直接复制使用的模板（替换包名后即可构建）
│   ├── host.ts                 #   Host 端模板（webServer.register 路由型）
│   ├── host-tool.ts            #   Host 端模板（ctx.tools.register(defineTool) 工具型）
│   ├── client.ts               #   Client 端模板（settings.section 设置页）
│   ├── tsdown.config.ts        #   双端构建配置（__ModuleLoader__ 包装）
│   ├── package.json            #   dsh.client + dsh.bundle 声明
│   ├── tsconfig.json
│   └── cordis.patch.yml        #   DSH 安装配置
└── README.md

一、把本仓库安装为 DSH 技能

把本仓库（或只复制 SKILL.md）放到任意一个技能根目录下即可，DSH 会自动发现：

| 技能根目录 | 路径 | 作用域 |
|---|---|---|
| 用户级 | /skills/dsh-plugin-starter/ | 所有工作区 |
| 项目级 | /.dsh/skills/dsh-plugin-starter/ | 当前项目 |
| 自定义 | 在 settings 里配置 customSkillDirs 指向本仓库路径 | 按配置 |

以用户级为例（$DSH_HOME 未设置时默认为 ~/.dsh）
git clone https://github.com/lnyanhongyan/dsh-plugin-starter "$DSH_HOME/skills/dsh-plugin-starter"

安装后，AI 在开发 DSH 插件时会自动加载 SKILL.md 中的流程与要点。

二、用模板新建一个插件

1. 新建插件目录，复制模板
mkdir my-plugin && cd my-plugin
cp -r ../dsh-plugin-starter/templates/* .
mkdir -p src/client

2. 把 src/index.ts 放到 src/，src/client/index.ts 放到 src/client/
mv host.ts   src/index.ts
mv client.ts src/client/index.ts

纯工具型插件：只要 Host 端，不要 Client 半区
mv host-tool.ts src/index.ts   # （与 host.ts 二选一，工具型选这个）

3. 改名清单：把下面所有 @lnyanhongyan/dsh-plugin-name 替换成你的包名

改名清单（3 个配置文件 + 3 个源码文件）

| 位置 | 替换内容 |
|---|---|
| package.json | name 字段 → 你的包名（如 @你的命名空间/dsh-my-plugin） |
| tsdown.config.ts | PLUGIN_ID 常量 → 与包名一致 |
| cordis.patch.yml | name 字段 → 与包名一致 |
| tsconfig.json | paths 里的键 → 与包名一致 |
| src/index.ts（host.ts） | 路由前缀 /plugin-path → 你的路由路径；plugin-name → 你的插件 id |
| src/index.ts（host-tool.ts） | 工具名 my_tool → 你的工具名；description 改写为模型视角 |
| src/client/index.ts | plugin-name → 你的插件 id（slot id / locale namespace / 日志标签） |

命名规范：包名用你自己的 npm/GitHub 命名空间（如 @lnyanhongyan/dsh-xxx），不要占用 @deepseek-ai 官方命名空间。

构建与安装

pnpm install          # 安装依赖
pnpm typecheck        # 类型检查
pnpm build            # tsdown 双端构建 → lib/index.mjs + lib/client.js
pnpm pack             # 产出 .tgz

dsh plugin --profile web add ./my-plugin   # 安装到 DSH
dsh web --port 3081                        # 重启后在设置页验证

三、参考实现

dsh-rule-manager 是本模板的完整参考实现：

- Host 端注册 /rules/ 路由（overview / read / write / delete / projects），用 ctx.get('fs') 管理规则文件、sandboxPolicy 申请完整权限、fs.unlink 删除文件（Windows 兼容）。
- Client 端是「规则管理」设置页：ctx.slots.inject('settings.section', ...) 注册、fetch() 调路由、--dsw-alias- token 适配主题。

工具型插件的参考实现见 dsh-fetch-url（本地 plugins 目录）：ctx.tools.register(defineTool({name:'fetch_url', ...}))，含 output.schema 强制校验、presentCall UI 展示、协作取消（exec.signal）。

四、发布到 GitHub

git init && git add . && git commit -m "feat: initial release"
先在 GitHub 上创建仓库（你的账号），再推送
git remote add origin git@github.com:你的账号/仓库名.git
git push -u origin master

GitHub 权限提示：fine-grained token 需要给仓库单独配置 Contents: Read and write 权限，或用 classic token（ghp_ 开头，勾选 repo）。

License

MIT