modelstudioai__cli/docs/agents/dsh-plugin.md

dsh 插件维护（packages/bailian-kb-dsh）

触发条件

• 改 packages/bailian-kb-dsh 的工具（kb_search / kb_chat）、服务缓存、settings / 凭据解析
• 改 web 半（Settings 配置页 React 组件、CSS Modules）
• 升级 @deepseek-ai/dsh-* peer 依赖
• 改插件包名、bundle 声明或产物布局
• 发布插件到 npm

这个包和其他 packages 不一样的地方

它是下游宿主适配层：依赖方向朝外（消费 bl CLI 与百炼 API，装进 DeepSeek Harness 运行），不是 core → runtime → commands → 产品入口 这条链上的一环。由此带来四条与 packages/* 通行约定的故意偏离：

项	本包	其他包	原因
版本	独立 0.1.x	core/runtime/commands/cli/kscli 锁步	跟随 dsh 的 rc 节奏，与 bl 发版无关；不在 tools/release/lib/packages.mjs 白名单里
构建	tsc + tsdown	vp pack	浏览器半需要 __ModuleLoader__ banner/footer 与 lightningcss CSS Modules 内联，vp pack 产不出
发布	publish.yml 里 package=bailian-kb-dsh job，走 publish-kb-dsh.mjs	publish.yml 里 publish-stable/channel.mjs	不在 bailian-cli 依赖闭包内，版本与构建都不同，不能与 bl 共用同一条 script
tsconfig	三个	一个	见下

tsconfig 三件套（改动前先读）

文件	谁在用	作用
tsconfig.json	oxlint / vp check 自动发现	纯类型检查，覆盖 src + tests 两半：noEmit + jsx: react-jsx + DOM lib + allowImportingTsExtensions
tsconfig.build.json	build script（tsc -b）	产出 node 半到 dist/，exclude: src/web
tsconfig.web.json	build / typecheck script	web 半的隔离检查：types: []，确保浏览器代码不误用 node 全局

• 不要把 tsconfig.json 改成产出配置：allowImportingTsExtensions 与 emit 互斥，一改 oxlint 就再也检查不了 .tsx（报 TS17004 --jsx not set）。
• web 半的隔离检查挂在 build script 里，因为 CI 只跑 build / 根 check / 根 test，typecheck script 没有调用点。

必查清单

A. 包身份（改包名时三处必须一起改）

• package.json 的 name
• cordis.patch.yml 的 insert[].name（profile 层栈按这个名字解析插件）
• tsdown.config.ts 的 PLUGIN_ID（进 window.__ModuleLoader__.load({ id }) 与 <style data-plugin>）

漏任何一处都不会在构建期报错，只会在 dsh 里运行时崩。验证：grep -rn "<新包名>" package.json cordis.patch.yml tsdown.config.ts 三处齐全，且 dist/web/client.js 首行的 id 是新名。

B. 产物布局

• 产物落 dist/（node 半）与 dist/web/client.js（浏览器半）；根 .gitignore 忽略 dist 与 *.tsbuildinfo，不要改回 lib/（那会把产物提交进库）
• package.json 的 main / types / exports["."] / exports["./client"] / files 与实际产物一致
• tsdown 的 clean 保持 false：默认 clean 会清掉 tsc 刚产出的 node 半

C. web 半的模块边界

• 只 import tsdown CLIENT_EXTERNALS 名单里的 @deepseek-ai/*（宿主 frozen module table 只能应答这些）——构建期由 dsh-client-bundle-purity 插件把关
• 不 import node:* 与本仓 CLI 包（bailian-cli-core 等）——根 vite.config.ts 的 no-restricted-imports override 在 lint 期把关
• 跨插件协作走 cordis service，不做 value import（type-only import 会被擦除，不受限制）

D. skill 资产

• skills/bailian-kb/ 留在包内，不要挪到仓库顶层 skills/：.github/workflows/publish-skills.yml 把 skills/** 全量对账到 OSS registry，bl skill init 会装给所有 bl 用户，而这个 skill 讲的 kb_search / kb_chat 原生工具只在 dsh 里存在
• skill 只有一个手写 SKILL.md，不带 reference/：它不是 CLI，没有义务维护一份 bl 参数手册。bl 命令的 flag 详情交给 bl <命令> --help（权威的 bl reference 由 tools/generate-reference.ts 写到 skills/bailian-cli/reference/，与本包无关）。SKILL.md 里写到的 bl 命令/flag 修改时手动核对 packages/commands/src/commands/，不要锚版本号

E. 文档（README 是 npm 主页，双语）

• 用户可见行为变了（工具参数、配置字段、环境变量、设置页、安装/卸载命令）→ README.md 与 README.zh.md 一起改；两份互为镜像，头部互链
• README 只写用户要知道的事；"为什么这么设计"（上下文注入载体、缓存布局、刷新触发点、桥接路由）写进 ../kb-dsh/runtime-behavior.md，不要回流 README
• 包根保留 LICENSE（npm 无条件打包），与 package.json 的 license 一致

F. 依赖与测试约定

• @deepseek-ai/dsh-* 同时列在 peerDependencies（运行时由 dsh 安装闭包提供）和 devDependencies（本地类型检查）——升级时两处同步
• 测试从 vite-plus/test 导入（仓库统一约定），不要用 vitest
• 忽略的 catch 绑定与 mock 签名参数用 _ 前缀（根 vite.config.ts 已为本包放开 no-unused-vars 的对应 pattern）

G. 改完跑

pnpm --filter bailian-kb-dsh run build   # tsc 出 dist/ + web 半隔离检查 + tsdown 出 client.js
pnpm run check                           # 根 lint + 格式 + 类型
npx vp test packages/bailian-kb-dsh

手动集成（改了 bundle 声明 / web 半 / 工具 schema 时必做）：

dsh plugin --profile dev add <本仓库>/packages/bailian-kb-dsh
dsh --profile dev --dump-config          # 应能看到 tool-bailian-kb row

发布

入口与 bl 共用：Actions → Publish → package=bailian-kb-dsh + mode=stable|channel。共享的只有 workflow 入口与 checkout/pnpm/node/gitleaks/install 几步 setup；它走自己的 tools/release/publish-kb-dsh.mjs，不复用 publish-stable.mjs / publish-channel.mjs。

	stable	channel
版本	package.json 当前值（先手动 bump 并提交）	临时 0.0.0-beta-<sha>-<stamp>，finally 还原，不提交
npm tag	latest	你传的 channel（dist-tag）
preflight	工作区干净 + 必须在 main	无
git tag	bailian-kb-dsh-v<version>（与 bl 的 v<version> 错开命名空间）	不打 tag
审批	environment: production（Required Reviewers）	无
产物	npm only	npm only

两种模式都跑：build（tsc + web 隔离检查 + tsdown）→ 幂等性查重 → pnpm pack → publint + gitleaks → pnpm publish --provenance。

本地验证（不真发，需本地装 gitleaks）：

node tools/release/publish-kb-dsh.mjs --dry-run
node tools/release/publish-kb-dsh.mjs --dry-run --channel dsh-beta

首发前的 npm 侧前置（仓外操作，一次性）

1. 占住包名 bailian-kb-dsh（OIDC Trusted Publishing 无法给不存在的包首发）
2. 在 npm 包设置里绑 Trusted Publisher：仓库 modelstudioai/cli、workflow publish.yml；stable 走 environment production，channel 无 environment

未完成这两步前触发 workflow 会在 pnpm publish --provenance 这一步失败（前面的 build / scan 仍会正常跑完）。

已知待办

• publint 会报一条 warning：exports["./client"] 是 CJS 但包为 type: module，建议改 .cjs 扩展名。这是迁移前就存在的状态，warning 不阻断发布；真要改得同时动宿主按 exports["./client"] 解析 /plugins/<id>/client.js 的 URL 契约，需 dsh 侧一起验证，不要单方面改

相关文档

• 设计与实现计划归档：docs/kb-dsh/
• 运行时行为与设计取舍（内部）：docs/kb-dsh/runtime-behavior.md
• 用户面说明：packages/bailian-kb-dsh/README.md / README.zh.md
• skill 文案与路由约定：skill-change.md