DSH 插件发布全链路：npm 打包、bundle 与 profile 机制、商店元信息、用户安装一条龙

CFzjyAI Engineer▍深耕领域AI Agent 架构设计Harness 插件开发Context Engineering多智能体协同 RAG▍技术底座PythonTypeScript·Cordis 插件MCP Skills·FastAPIDocker▍工程能力专注 Agent 运行时与 Harness 插件开发、长上下文与流式交互优化、LLM 全链路工程化落地「 让 AI 交互更智能让技术落地更高效 」欢迎技术探讨 / 项目合作关注解锁大模型与智能交互的无限可能DSH 插件发布全链路npm 打包、bundle 与 profile 机制、商店元信息、用户安装一条龙《DeepSeek Harness 插件架构》连载专栏 · 第 13 篇前面十二篇把 DSH 插件从原理写到实战、从官方解剖写到迁移。这一篇解决最后一公里你写好的插件怎么变成别人一行命令就能装上的成品很多插件死在本地能跑、一发布就坏——不是代码不行是打包、元信息、分发方式没对齐。DSH 的发布有一套清晰的契约先分清组合包bundle和profile两个概念再搞定 npm 打包不变式然后补商店元信息最后验证用户安装。这一篇把整条链路串起来。痛点一插件本地跑得好npm publish 一装就坏。因为files白名单漏了产物线上包缺文件。痛点二分不清 bundle 和 profile。把两者混为一谈结果装不进、启不来。痛点三插件在商店里丑得没眼看。没有 locale 标题、没有 icon、没有实机截图商店卡片一片空白。痛点四从 GitHub 直装总失败。不知道 git 安装拉的是源码不是产物需要prepare脚本和allowBuilds授权。网上讲 DSH 的教程大多停在写个插件本篇把发布讲透。读完你会拿到bundle/profile 的概念区分、package.json 的发布级不变式、三种分发方式的取舍表、商店元信息的完整清单、以及一张发布避坑速查表。想追完结篇下一篇插件化是 Agent 应用层的未来吗可以先关注我的 CSDN 主页。文章目录DSH 插件发布全链路npm 打包、bundle 与 profile 机制、商店元信息、用户安装一条龙一、发布全链路概览两个概念两种 manifest二、npm 打包package.json 的不变式三、三种分发方式npm / tarball / git 的取舍四、商店元信息locale、icon、screenshots 与市场五、用户安装验证 发布避坑速查表结语一、发布全链路概览两个概念两种 manifestDSH 的安装机制建立在两个概念之上二者都由package.json描述但回答的问题不同官方原话概念manifest 键回答的问题谁写、谁用组合包bundledsh.bundle“这个包贡献什么”你编写、你分发profiledsh.profile“这套配置由哪些组合包按什么顺序组成”用户用dsh --profile启动组合包是附带一个配置层的 npm 包——它的dsh.bundle.patch指向一个 patch 文件声明我往插件树里插/覆盖哪些行。profile是$DSH_HOME/profiles/name下的目录用dsh.profile.bundles列表声明我按什么顺序组合哪些 bundle。官方强调了一句容易踩的边界“没有东西同时是两者”——组合包是你发的东西profile 是用户启的东西。源码src/index.ts构建lib/index.jsnpm 打包files 白名单三种分发用户 dsh plugin add写入 profile.bundles--dump-config 验证二、npm 打包package.json 的不变式第 07 篇你搭过骨架这里给发布级的硬约束——官方通过 CIpnpm run constraints强制执行这些不变式新包不满足就过不了门禁字段硬约束不满足的后果privatetruemonorepo 内意外发版version与根 package.json 一致版本漂移type/main/typesmodule/lib/index.js/lib/types/index.d.tsimport/export 报错peer 依赖deepseek-ai/cordis同时进 peerDependencies devDependencies同范围类型检查/测试孤岛deepseek-ai/schemastery放dependencies运行时校验器运行时缺依赖files精确列出lib/index.js、lib/types/**/*.d.ts等线上包缺文件其中files是最高的坑官方特别强调“不要发布 src、声明映射、JS map 或陈旧的根声明文件”。它的逻辑是只发产物不发源码——TypeScript 源码留在仓库消费者只拿编译好的lib/。发布前用pnpm pack --dry-run核对打包清单能提前发现漏了cordis.patch.yml或screenshots.json这类线上坏包。三、三种分发方式npm / tarball / git 的取舍官方给了三种交付方式各有适用场景也各有坑方式命令优点代价npm 发布dsh plugin add your-package预构建、零授权、体验最好要发版到 registrytarballdsh plugin add ./your-package-0.1.0.tgz离线交付、不需 registry要自己pnpm packgit 直装dsh plugin add github:you/pkg不用发 registry拉的是源码需要构建授权git 直装是坑最多的一种官方专门提醒git 安装拉取的是源码不是构建产物——没有任何环节运行你的build脚本TypeScript 包到手时没有lib/输出加载就失败。解法两边各做一件事作者提供自包含的prepare脚本pnpm 在 git 安装后运行它从源码构建出发布入口用户为构建授权——pnpm ≥10 在显式允许前拒绝运行 git 依赖的prepare脚本所以第一次add会失败dsh会提示把确切的包键写进 profile 的pnpm-workspace.yamlallowBuilds:dsh-hello-plugin:true官方给了一句分量很重的话这项授权意味着允许该包的代码在安装时于你的机器上执行且不在 agent 运行的任何沙箱之内——所以只对源码可信的包授权并锁定 commitgithub:you/pkg#sha让后续推送无法悄悄改变实际运行的内容。如果不想让用户做授权就改用前两种npm / tarball它们都是预构建产物、零构建权限。四、商店元信息locale、icon、screenshots 与市场插件进了商店长什么样取决于三样元信息——这是能被搜到、点进、装走的关键元信息位置作用locale 标题/描述locale/en.jsonlocale/zh.json商店卡片的名称和简介中英双语iconpackage.jsonicon: ./icon.svg商店卡片图标screenshotsscreenshots.jsonassets/*.png实机运行截图严禁伪造locale 的字段很简洁{meta:{title:Workspace Tools,description:Tools for your workspace.}}官方给了一条回退链值得记标题回退顺序是locale meta.title→package.json.name→ 完整 Cordis 插件名描述是meta.description→package.json.description→ 不显示。所以即使你不写 locale插件也不会在商店消失只是显示技术名。但想要商店卡片专业就得补双语 locale iconSVG/PNG/JPEG/WebP≤256 KiB自包含 实机截图。第 07 篇提过screenshots.json必须是合法字符串数组、图片在仓库里真实存在——商店 CI 会校验伪造截图过不了。五、用户安装验证 发布避坑速查表用户侧一行命令安装dsh会转发给 pnpm 并维护 profile 的 bundle 列表dsh plugin--profiledemoadd./hello-plugin# 首次会初始化 profile(deepseek-ai/dsh-base 作为第一个 bundle)# 因为包声明了 dsh.bundle会被追加进 dsh.profile.bundles装完先别急着启动用--dump-config验证你的层真的被应用了第 05/09 篇的验层法dsh--profiledemo --dump-config# 输出里应出现 # dsh-hello-plugin 这一层dsh--profiledemo生效配置按四层层序组合第 05 篇profile 的 bundles 列表 → profile 自己的 patch → home 级$DSH_HOME/cordis.patch.yml→ 每个--patchoverlay后层按行胜出且整行替换不深度合并。序号遇到的报错或现象背后的真正原因一句话解决办法1npm 装完插件不生效包没声明 dsh.bundle.patchpackage.json 加 dsh 键2线上包行为与本地不一致files 白名单漏了 patch 或 assets发布前 pnpm pack --dry-run 核对3git 直装 TS 包加载失败拉的是源码,无 lib/ 产物作者加 prepare 脚本,用户配 allowBuilds4git 安装被 pnpm 拒绝pnpm≥10 默认拒绝运行 prepareprofile 的 pnpm-workspace.yaml 加 allowBuilds5商店卡片显示技术名没写 locale 元信息locale/en.json zh.json 补 meta.title6商店 CI 校验 screenshots 失败不是合法字符串数组或图片缺失格式 [“./assets/screenshot-1.png”] 且文件真实存在7装了但 --dump-config 看不到层层序或整行替换语义没吃透回到第 05 篇核对四层层序与覆盖语义这张表的心法回到本篇主题发布不是npm publish 一下就完而是把 bundle 概念、打包不变式、分发方式、商店元信息、安装验证五件事全部对齐。任何一环漏了都会在别人装你的插件那一刻爆雷而不是在你本地跑的时候爆雷。结语这一篇把 DSH 插件发布串成了完整链路两个概念bundle 贡献什么 vs profile 由什么组成、打包不变式package.json 的 files/peer/exports 硬约束、三种分发npm 预构建 / tarball 离线 / git 直装需授权、商店元信息locale icon screenshots、用户安装验证dsh plugin add --dump-config。核心一句话发布质量 对齐契约而不是代码能跑——你的插件在别人机器上装不装得上取决于你有没有把每一层的契约做对。知识要点文字回顾① bundle(贡献什么) vs profile(由什么组成) 是两个概念没有东西同时是两者② package.json 不变式files 只发 lib 不发 src、cordis 同时进 peerdev、schemastery 进 dependencies③ 三种分发npm 预构建零授权、tarball 离线、git 直装需 prepareallowBuilds④ 商店元信息 locale(meta.title/description) icon screenshots.json⑤ 安装后用 --dump-config 验证层被应用。完结篇预告《插件化是 Agent 应用层的未来吗DeepSeek Harness 架构趋势前瞻》——回到本系列开头的判断做一个收束和展望关注 CSDN 主页 不错过更新。你发布过 DSH 插件或 npm 包吗卡在 files 白名单、git 授权还是商店元信息评论区聊聊我挨个回。本文事实基于 DeepSeek Harness 官方文档打包与安装插件、添加 workspace 包手册2026-10 版本API 迭代快有出入评论区提醒我。参考资料正文数据来源DeepSeek Harness 官方文档《打包与安装插件》《实操手册添加 workspace 包》《插件配置》。