figmar
63bcb47ed0
Gitea 的 wiki 此前是空的。本次把百科的**源文件版本化进仓库**（docs/wiki/）， 再用脚本发布到 wiki——文档因此与代码同源、可 review、可回溯，而不是只存在于网页上。 八页（Home 作为导航与项目速览）： Home 项目速览 / 两条版本线的宿主兼容性差异 / 文档地图 / 谱系说明 01-需求分析 五条核心需求（现象·根因·验收标准·状态）+ 非目标与约束 + 需求→实现→锚点 02-系统架构 host/client 分层与产物、三层接口面、面板宿主层叠契约与 isolate 陷阱、关键不变量 03-功能说明 面板/预览器总表、信息层三 tab 数据来源、HTML 预览交付方式、i18n 与令牌、配置面 04-部署指南 宿主版本矩阵与选线决策、profile 接线（file: + bundles）、构建、验收清单、卸载与切换 05-运维手册 分支/tag 策略与回滚剧本、发布纪律（版本三元组/非确定性产物）、巡检、备份铁律、诊断 06-故障排查 8 类症状 → 根因 → 处置（含本会话实机定位过的全部案例）+ 定位手法 07-开发与测试 工程约定、目录、门禁基线、测试分层与契约 spec、扩展点、测量式 re-base 方法 脚本 scripts/push-wiki.sh：幂等发布（POST 新建 / PATCH 覆盖），凭据走 git credential helper （临时 netrc，600，退出即删），不落盘、不进 argv。已实测：8 页全部发布成功，复推为更新。 内容纪律：只写**本次会话实证过**的事实（提交号、行数、层级取值、产物大小、宿主版本矩阵、 静默禁用机制、re-base 步骤），未验证的部分明确标注为待验证或已知限制；并如实说明本仓库 历代承载过 v1 / v2 / 当前 fork 三代实现，本百科描述的是 main 上的 fork 线。
7.1 KiB
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+ |
怎么查宿主版本（扩展模式桌面版）：
# 内置的 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：构建
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）：
{
"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 重新安装依赖
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 默认拦截依赖的构建脚本，
于是首次安装会失败或终端不可用：
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 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 栈中位于本行之前。
七、变更后的重新部署
# 插件仓库
pnpm typecheck && pnpm build && pnpm test
# profile
cd ~/.dsh/profiles/<profile> && pnpm install
# ⌘Q 退出 DSH 再启动
改完代码必须走完这三步：产物构建非字节确定性，profile 的 file: 副本也不会自动跟随。