worksAssistant/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：

   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 是脚本生成的，不要手改）：

   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（同工作区）