Add "04-部署指南"

figmar committed 2026-10-04 01:19:04 +08:00
1 parent 75bc10f880
commit cecb01ef40
1 file changed
+163
+163
@@ -0,0 +1,163 @@
# 04 · 部署指南
> 目标:在一台机器上把本插件挂进 DSH,并确认它**真的在跑**。
> 关键前提:**先确认宿主版本,再选版本线**——选错线的唯一症状是「静默失效」。
## 一、前置条件
| 项 | 要求 |
| --- | --- |
| Node | ≥ 20(`engines.node`);本机验证用 22.x |
| pnpm | 11.x(`pnpm install` 会自动触发 `prepare: tsdown` 构建) |
| DSH | 见下面的版本矩阵 |
| 终端可用性 | 仅 v0.19.1 线需要额外放行 `node-pty` 原生构建(见 §五) |
### 1.1 宿主版本矩阵(先读这张表)
| 版本线 | 分支 | 插件版本 | peer 声明 | 适用宿主 |
| --- | --- | --- | --- | --- |
| 旧宿主线 | `main` | 1.2.0 | `^0.1.5-rc.1` | DSH `0.1.5-rc.1+`(含 `0.1.5-rc.2`,即 **DSH Desktop 2.0.10** 内置版本) |
| 新宿主线 | `sync/v0.24.1` | 1.3.0 | `^0.2.0-rc.1` | DSH `0.2.0-rc.1+` |
**怎么查宿主版本**(扩展模式桌面版):
```bash
# 内置的 dsh 版本
grep -m1 '"version"' "/Applications/DSH Desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh/package.json"
# 或看 profile 里装的宿主包
grep -m1 -A2 '"@deepseek-ai/dsh"' ~/.dsh/profiles/desktop/package.json
```
**选线决策**
```
宿主 ≥ 0.2.0-rc.1 ? ── 是 ──▶ sync/v0.24.1(1.3.0)
└─ 否 ──▶ main(1.2.0)
```
> ⚠️ **peer 不匹配不会报错。** 宿主以 `semver.satisfies(host, peerRange, { includePrerelease: true })` 预检,
> caret 跨 minor 判 false 后**整行静默禁用**:不加载、无日志、界面上「像没装」。
> 因此「装完没反应」的第一件事永远是核对宿主版本 ↔ peer 范围。
## 二、安装方式(本 fork 未发布 npm 包)
`npm view dsh-apes-sidebar` 返回 404 —— **本 fork 不在 npm 上**(README 里的 npm 徽章/命令是沿用上游文档)。
实际部署使用「本地源码 + `file:` 链接依赖」:
### 步骤 1:构建
```bash
cd <插件仓库绝对路径>
git checkout main # 或 sync/v0.24.1(按宿主版本选)
pnpm install # 会顺带跑 prepare: tsdown
pnpm typecheck && pnpm build && pnpm test # 门禁三连
```
产物(`lib/`):`index.js` / `invariant.js`(host)+ `client.js` + 懒加载 chunk
(`client-registry` / `client-editor` / `client-locale` / `client-mermaid` / `client-terminal`)+ `types/`。
### 步骤 2:接进 profile
编辑 `~/.dsh/profiles/<profile>/package.json`(桌面版为 `desktop`,网页版通常为 `web`):
```jsonc
{
"dependencies": {
"dsh-apes-sidebar": "file:/绝对路径/dsh-apes-sidebar" // ← 必须是绝对路径
},
"dsh": {
"profile": {
"bundles": [
"…",
"dsh-apes-sidebar" // ← 加入 bundle 栈
]
}
}
}
```
> 也可以在 profile 自己的 `cordis.patch.yml` 里手写挂载行(老方式)。**两种方式不要同时用**:
> 会双挂载成两个 Node 半、两个侧边栏。包内自带的 `cordis.patch.yml` 是 `dsh.bundle.patch` 层,
> 由官方 CLI 安装时自动追加 bundle,并带「聚合包双挂载退让」守卫。
### 步骤 3:让 profile 重新安装依赖
```bash
cd ~/.dsh/profiles/<profile> && pnpm install
```
**为什么必须重装**:pnpm 对 `file:` 依赖是**复制**语义(不是软链)。源码 `pnpm build` 之后,
profile 的 `node_modules/dsh-apes-sidebar/lib` **仍是旧副本**——这就是「改了代码但界面没变」的头号原因。
DSH 启动时也会 reconcile profile 的 pnpm workspace,但不要假定它一定帮你刷新。
### 步骤 4:完整重启
**⌘Q 完全退出 DSH,再重新启动**(不是关窗口)。client 半有热加载,但 host 半与依赖变更必须走完整重启。
## 三、验收清单
重启后逐条核对(每条都对应一个可观察事实):
- [ ] **右列只有一套侧边栏**、一个开合控件(不再出现自绘的第二套开关)
- [ ] 原生 guide 里能看到本插件的 tab 芯片,且**带图标**
- [ ] 三个信息层 tab 存在:**智能体 / 应用 / 画像**(order 在原生面板之后)
- [ ] `apes:agents` 打开后:有主代理卡片;有子代理时列出直系子代理(标签 + 模式 + 运行态)
- [ ] 打开一个 HTML 文件:**沙箱态下自包含 HTML 能正常渲染**(不再是 `forbidden`)
- [ ] 打开「社区插件市场」:弹窗**完整盖在**本插件面板之上(面板不切弹窗角)
- [ ] 页面左下角**没有**红色诊断条(有的话说明 client 生命周期某处抛错)
- [ ] 开发者控制台**没有** `[dsh-apes-sidebar] … error` 前缀的错误
## 四、网页 profile 与桌面 profile 的差异
| 项 | 桌面版(DSH Desktop) | 网页版 |
| --- | --- | --- |
| profile 目录 | `~/.dsh/profiles/desktop` | 通常 `~/.dsh/profiles/web` |
| 外壳 | Electron 壳,有「扩展模式/兼容模式」与请求围栏 | 浏览器直连宿主端口 |
| 预览 iframe | 受渲染器围栏约束(因此必须走 `srcDoc` 交付) | 无该围栏,但仍受路由 CSP/沙箱约束 |
| 面板宿主层级 | 壳层会给 `#root` 打 content-viewport 标记 → 宿主挂进 `#root` | 无标记 → 宿主挂 `document.body` |
| 刷新方式 | ⌘Q 完整退出再启动 | 硬刷新(Cmd/Ctrl+Shift+R) |
## 五、v0.19.1 线特有:放行 node-pty 原生构建
`main`(上游 v0.19.1 基线)在 `package.json` 中仍有 `node-pty` 依赖;pnpm 11 默认**拦截依赖的构建脚本**,
于是首次安装会失败或终端不可用:
```bash
cd ~/.dsh/profiles/<profile>
pnpm approve-builds # 选中 node-pty,回车确认
pnpm rebuild node-pty # 必要时
```
`sync/v0.24.1`(1.3.0)**不含** `node-pty`(终端交由宿主内置承担),无需此步。
(`main` 与 `sync/v0.24.1` 的 `node-pty` 引用数:1 / 0。)
## 六、切换与卸载
同一条线只能装一个(两条线都注册 `ctx.betterSidebar`,entry id 冲突,第二个被丢弃)。
仓库自带切换脚本:
```bash
bash scripts/switch.sh --status # 只看当前是哪条线
bash scripts/switch.sh aps # 切到本 fork 线(本地 file: 安装)
bash scripts/switch.sh upstream # 切回上游 dsh-better-sidebar
bash scripts/switch.sh upstream 0.18.0 # 指定上游版本
bash scripts/switch.sh aps --profile web # 指定 profile
```
**完全卸载**:从 profile 的 `dependencies` 与 `dsh.profile.bundles` 中移除 `dsh-apes-sidebar`,
`pnpm install`,⌘Q 完整重启。若曾手写过 `cordis.patch.yml` 挂载行,一并删除(否则会留下悬空 entry)。
> 若同时装了聚合包(如 `@linxin666/dsh-web-ui-all`)且它内部也挂载了本包,
> 包内 bundle patch 的守卫会让**本行退让**;此时请确认聚合包在 bundle 栈中位于本行之前。
## 七、变更后的重新部署
```bash
# 插件仓库
pnpm typecheck && pnpm build && pnpm test
# profile
cd ~/.dsh/profiles/<profile> && pnpm install
# ⌘Q 退出 DSH 再启动
```
改完代码**必须**走完这三步:产物构建非字节确定性,profile 的 `file:` 副本也不会自动跟随。