安装

前置:dsh 宿主(各包的版本要求见能力地图各表的「宿主要求」列与包 README 的 Compatibility 节;共存设计与 ankh-guard 的重复行例外见运维守护与 ankh-guard 的说明)。推荐路径是整合包(见上文整合包);单包安装是高级用户按需裁剪或调试的路径。

宿主 ≥ 0.1.7-rc.2 时,单包安装不用碰命令行:设置 → 插件 → 添加插件,填 npm 包名(如 @khorsheed/dsh-whalesong),按提示启用/重启即可。注意这个入口只认单个插件包——本仓是 monorepo、整合包仓是 profile 模板,把它们的 GitHub 地址贴进去会被拒绝并回滚(官方安装器只装仓库根的插件包,不支持子目录);整合包请走各自仓库的安装脚本。

# 按 npm 名装单个(自挂载包自动挂载自身 loader 行,无需手改 cordis.yml)
dsh plugin --profile web add @khorsheed/dsh-whalesong

# 家族一键装(元包)
dsh plugin --profile web add @khorsheed/dsh-bundle-conversation-toolbox
dsh plugin --profile web add @khorsheed/dsh-bundle-local-agent

# local-agent 家族单装时注意:核心与 harness 要显式一起装
dsh plugin --profile web add @khorsheed/dsh-local-agent
dsh plugin --profile web add @khorsheed/dsh-local-agent-kimi   # 或 -codex / -claude-code / -dsh

装完重启对应 web 实例生效。组合组件包(*-tool、local-agent-dsh-headless、ui-content-preview)不由 dsh plugin add 挂载——它们由 profile 的 preset 行或 provider patch 落位,完整关系见权威包地图。

卸载

dsh plugin --profile web remove @khorsheed/dsh-<name>

通用规则:

• 卸载即精确还原。 没有任何插件修改/替换官方文件,移除后组合精确回到之前的状态。
• 用户数据刻意保留。 local-agent 家族保留每个 harness 的作用域目录($DSH_HOME/local-agent/<name>),重装无需重新登录;ankh-guard 保留 stateDir 下的状态(凭证、重启记录、中断会话快照);ui-shortcuts 的键位保留在 $DSH_HOME/settings.yaml。任何卸载都不碰会话日志——编辑/撤回的审计轨迹留在日志里是有意为之。
• 家族行随行。 先卸 local-agent 核心而 harness 还在时,harness 行保持 pending,不会崩溃——重装核心即恢复。
• enabled: false 可以禁用某行而不卸载——这是部署层操作,不是代码改动。

开发

独立 pnpm monorepo;每个包以 @khorsheed/dsh-* 发布。

packages/   一个目录一个可发布插件
profiles/   整合包(basic / dev / web-eval 与生产 web)
build/      共享构建/测试预设(tsdown client bundle、vitest 源码面配置)
scripts/    仓库工具(pack-dist、gen-typert、镜像同步、门禁检查器)

pnpm install
pnpm run build      # pnpm -r --if-present run build
pnpm run test       # pnpm -r --if-present run test
pnpm run typecheck  # pnpm -r --if-present run typecheck

测试必须走根 pnpm test 或 pnpm --filter <pkg> test——裸跑 vitest run packages/xxx 会绕过每包的 vitest 配置(源码面别名预设),报误导性的解析错误。

开发期对 harness checkout 的依赖。 两条机制解析到本地 deepseek-harness clone(env DSH_HARNESS,默认 ~/code/deepseek-harness),发布的 npm 产物单独无法满足:

• scripts/gen-typert.mts 对 harness checkout 重新生成 lib/typert.* 产物(带 ./typert/./remote 导出的包);全量构建有保鲜缓存,输入或产物有变才会真生成(GEN_TYPERT_FORCE=1 强制)。
• build/vitest.ts(共享 vitest 预设)把平台 import 映射到 harness 的 tsconfig.base.json 路径——发布的包不携带 src/,其 /client 入口是 loader 包裹的浏览器 bundle,裸 import 会炸。

CI 注意:先在本仓库旁 clone deepseek-harness 并设 DSH_HARNESS 再 pnpm test;harness checkout 过期意味着被测 API 面可能落后于生产宿主。发布走 scripts/pack-dist.ts(--family 重写 peer 依赖的 scope),npm publish 前先验证 tarball。完整仓库纪律见 AGENTS.md。