dsh-quickref
开发者速查工具箱：面向 DeepSeek Harness（DSH）的插件。设置页「开发者速查」分区提供按主题分类、可搜索的速查表（12 类 195 条），以及 6 个零依赖开发工具（正则实时测试 / JSON 格式化 / 时间戳转换 / Base64\/URL 编解码 / Cron 生成 / 文本 Diff）。
目录结构
dsh-quickref/
├── package.json # dsh.bundle / dsh.client 声明、peerDependencies、发布配置
├── cordis.patch.yml # ★ 主机端 loader 条目（上架硬性要求，缺它无法安装）
├── tsconfig.json # 类型检查（noEmit）
├── tsconfig.build.json # 声明文件输出（lib/types）
├── scripts/
│ ├── build.mjs # esbuild：src → lib（主机 ESM + 浏览器 CJS bundle）
│ └── check-market.mjs # 发布前的市场就绪检查
├── src/
│ ├── index.ts # 主机端 cordis 插件（apply(ctx)）
│ └── client.ts # 浏览器半部（window.__ModuleLoader__.load）
├── README.md
└── LICENSE快速开始
npm install # 或 pnpm install
npm run build # → lib/index.js + lib/client.js
npm run typecheck # tsc --noEmit
npm run dts # → lib/types/*.d.ts
npm run check:market # 发布前的市场就绪检查装进本机 profile 试运行
# 在插件仓库根目录执行（相对路径会被锚定到你的调用目录）
dsh plugin --profile web add .- 等价于
pnpm add <绝对路径>（symlink 形式），改完代码重新npm run build即生效； - 验证：
dsh plugin --profile web install通过，--dump-config输出里能看到dsh-quickref条目，然后重启桌面客户端； - 卸载：
dsh plugin --profile web remove dsh-quickref。
> ⚠️ 不要用 /tmp 下的路径做 link 安装——macOS 清空 /tmp 后客户端会因解析不到 bundle 而崩溃（血的教训）。务必用持久目录。
开发：往哪里加代码
骨架刻意保持「惰性」（零副作用），扩展点在源码里都有注释标记：
| 你想做 | 写在哪 | 参考模式 |
|---|---|---|
| 主机端服务 / 事件 / 副作用 | src/index.ts 的 apply(ctx) | ctx.get() 判空；ctx.on()；ctx.effect()；硬依赖用 inject |
| 注册一个动态模型工具 | 主机端 apply | harness builtin（先查 Builtin.listBuiltins），参数/返回值须 JSON 安全 |
| 浏览器 UI（设置页/侧栏/回合尾部等） | src/client.ts 的 apply(ctx) | 先 cordis_inspect_query 查真实 Slot 再 slots.register，用 React.createElement |
| 客户端调主机（RPC） | 两端 | 主机 harness.handle('name', fn)；客户端 host.call('name', args) |
| 主题 / 样式 | 客户端 | 查 Theme.listTokens 覆盖 token；局部样式用 styles.insert(css) |
> 任何时候不要凭名字猜接口：先 cordis_inspect_list / cordis_inspect_query 查真实的 Service、Event、Slot、Builtin 签名。
发布到 npm（推荐）
# 1. 先重命名（见下），并在 package.json 里设置 repository 指向你的 GitHub 仓库
# "repository": { "type": "git", "url": "git+https://github.com/worksAssistant/dsh-quickref.git" }
# 2. 登录并发布
npm login
npm publish- 市场装包优先走 npm tarball（秒级、免构建授权），且会校验
repository与仓库一致（防冒名）； - 不发 npm 时，可把预构建 tarball 挂到 GitHub Release，并在目录条目里用
tarball:字段指向它。
上架 Harness 市场
市场（dsh-market）的插件列表来自精选目录 awesome-dsh-plugin（站点 https://awesome-dsh-plugin.com/plugins.json）。上架 = 向该仓库提 PR，合并后站点自动重建，市场约 1 天收录。
1. 仓库要求（CI 自动检查）： - package.json 声明了 dsh.bundle（本骨架已声明）；只声明 dsh.client 会被直接拒绝； - 仓库创建满 1 天、提交数 ≥ 10； - 有真实可用代码（占位/纯 README 不收）； - 打上 dsh-plugin topic； - 描述只写功能、不夸大（会对照源码核验）。 2. 新增 data/plugins/worksAssistant__dsh-quickref.yml：
``yaml url: https://github.com/worksAssistant/dsh-quickref name: worksAssistant/dsh-quickref category: ui # ui usage theme model session memory tools vision skill workflow notify dev market fun description: en: One-line description ending with a period. zh: 一句话描述，以句号结尾。 # 可选，维护者会补 ``
3. 重新生成两个 README 一起提交（README 是脚本生成的，不要手改）：
``sh npm ci node scripts/generate-readme.mjs ``
4. 可选：在 data/screenshots.json 里以仓库 URL 为 key 加 1~8 张 GitHub 图床截图，市场详情页会像 App Store 一样展示。
发布前清单（rename checklist）
- [ ] 全局替换包名：
dsh-quickref→ 你的包名（package.json、cordis.patch.yml、src/client.ts 里的 id、README） - [ ]
package.json的repository设置为你的 GitHub 仓库 - [ ]
description改为一句准确的功能描述 - [ ]
dsh.client.inject按实际用到的官方 client 包增删（例如用到多语言就加@deepseek-ai/dsh-client-locale） - [ ]
npm run typecheck && npm run build && npm run dts && npm run check:market全部通过 - [ ] 本地
dsh plugin --profile web add .实测可加载，--dump-config无报错 - [ ] 按「上架 Harness 市场」提 PR
常见坑
| 坑 | 解法 |
|---|---|
只声明 dsh.client、缺 dsh.bundle | 市场 CI 直接拒绝；cordis.patch.yml 必须存在并在 files 白名单里 |
@deepseek-ai/* 放进 dependencies | 一律 peerDependencies；peer 范围带预发布分支（^0.1.0-rc.6 这种写法是对的） |
用 /tmp 路径 link 安装 | 客户端会崩；用持久目录 |
| 描述夸大（数字/API 名对不上） | 会被打回；描述与代码严格一致 |
参考
- 市场应用：https://github.com/dsh-market/dsh-market
- 插件目录 / 上架 PR：https://github.com/awesome-dsh-plugin/awesome-dsh-plugin
- 官方插件开发 skill（动态插件）：DSH 内置
cordis-plugin-development - 完整上架教程：仓库外的
dsh-plugin-publish-guide.md（同工作区）