docs(wiki): 建立项目百科（需求分析 → 架构 → 功能 → 部署 → 运维 → 排障 → 开发与测试）

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 线。

README.md

@@ -11,6 +11,9 @@
 >   `apes:profile` 画像），按 DSH 标准 `TabDescriptor` 接口注册——因此它们会自动获得上游原生适配层
 >   的全部待遇（进原生 guide、tab 芯片图标、开合与分栏）。
 > - 版本线独立于上游：`1.2.0`（fork）。上游历史版本见其 CHANGELOG。
+> - **📚 项目百科**（需求分析 → 系统架构 → 功能说明 → 部署指南 → 运维手册 → 故障排查 → 开发与测试）：
+>   <https://gitea.apescale.com/figmar/apes-sidebar/wiki>　源文件在仓库 `docs/wiki/`，
+>   改完用 `bash scripts/push-wiki.sh` 一条命令发布。
 
 > [!IMPORTANT]
 > **已适配 DSH 原生侧边栏 API**（v0.19.0 起，DSH `0.1.5-rc.1+`）：右列就是 DSH 自己的右侧栏——插件的每个 tab 类型与 tab 体通过 `ctx.sidebarRightTabs` / `ctx.sidebarRight` 注册与打开，聊天里的文件打开统一走 `ctx.sidebarRight.openResource('dsh-resource://file/…')`，插件**不再自绘右侧面板**（旧的浮窗能力同步移除）。自绘的底部工作台与开放给其他插件的 `ctx.betterSidebar` 服务保持不变，接入方式见[插件接入指南](docs/external-plugin-guide.md)。

docs/wiki/01-需求分析.md

@@ -0,0 +1,97 @@
+# 01 · 需求分析
+
+> 本篇回答三个问题：**为什么要做这个 fork、要解决什么、做到什么程度算完成**。
+> 每条需求都给出「现象 / 根因（含证据）/ 需求 / 验收标准 / 状态」，便于回溯与验收。
+> 证据中的提交号均在本仓库 `main` 或 `sync/v0.24.1` 上。
+
+## 一、背景
+
+DSH（DeepSeek Harness）宿主自身提供会话、任务、模型与一个**原生右侧栏**（`ctx.sidebarRight` /
+`sidebarRightTabs`）。上游 `dsh-better-sidebar` 在此基础上提供了一套「侧边栏工作台」：
+文件树与编辑器、文件变动、任务、侧边对话、终端、浏览器，并把
+`ctx.betterSidebar` 服务开放给其他插件注册标签页与文件预览器。
+
+**本 fork 的定位**：不重复造工作台，而是在其之上补齐宿主与上游都没有的那一层——
+**「信息层」**：这个会话的智能体拓扑、所属应用、以及会话画像。同时，在 fork 过程中暴露出
+若干与 DSH 桌面壳（Electron 壳）交互的**边界缺陷**，一并作为需求纳入。
+
+## 二、核心需求
+
+### R1 — 侧边栏只应存在一套
+
+| 项 | 内容 |
+| --- | --- |
+| 现象 | 窗口里同时出现**两套右侧边栏**与**两套开合按钮**（一套自绘浮窗控件、一套 DSH 原生） |
+| 根因 | fork 基线 v0.18.0 时，插件**自绘**右侧面板与开关（`toggleCluster`）；DSH 0.1.5 起宿主自己也提供原生右侧栏，二者并存 |
+| 需求 | 右侧内容全部改为**注册进 DSH 原生右侧栏**；插件不再自绘右侧面板 |
+| 验收标准 | ① 产物中 `toggleCluster` 引用数为 **0**；② 右列只有宿主那一个展开控件；③ 每个 tab 类型与 tab 体都经由原生注册路径（`src/client/native/`）出现 |
+| 状态 | ✅ 已完成（基线升级到上游 v0.19.1：`5a7e213` → 合并 `e5d34ac`；产物核对 `toggleCluster` = 0） |
+
+### R2 — 补齐「信息层」标签页
+
+| 项 | 内容 |
+| --- | --- |
+| 现象 | 宿主有会话树、上游有工作台，但**没有**「这个会话的智能体拓扑 / 应用 / 画像」这一层信息 |
+| 根因 | 上游聚焦文件工作台，信息层属于使用方（本 fork）的业务诉求 |
+| 需求 | 提供三个信息层标签页：`apes:agents`（智能体）、`apes:apps`（应用）、`apes:profile`（画像），按 DSH 标准 `TabDescriptor` 注册 |
+| 验收标准 | ① 三个 tab 进入原生 guide（带图标、可开合分栏）；② `order` 取 60/65/70，与原生 10–50 不冲突；③ 单实例（single）；④ 文案走 i18n（zh/en 双语齐全）|
+| 状态 | ✅ 已完成（`src/client/apes/`，随基线同步进 v0.19.1 与 v0.24.1 两条线） |
+
+**R2.1（收敛）** — 最初的 `apes:tasks` 已移除：它与原生会话树信息重叠，属重复建设。当前信息层为三 tab。
+
+### R3 — HTML 预览必须能在桌面壳里显示（且不牺牲沙箱）
+
+| 项 | 内容 |
+| --- | --- |
+| 现象 | 预览 HTML 文件时 iframe 只显示一行 `forbidden`（DSH Desktop 扩展模式） |
+| 根因 | 三层因果：① 桌面壳给**所有**路由套一层围栏，扩展模式下 `ordinaryBrowserEnabled` 恒为 false，不带 Electron 注入的 `x-dsh-desktop-renderer` 头一律 403；② 该头只发给 **mainFrame** 与**同源**子框架；③ 预览 iframe 的 sandbox 令牌不含 `allow-same-origin`，请求时源为 `null` → 拿不到头 → 403。**与本次基线升级无关**（v0.18.0 起行为一致） |
+| 需求 | 在**保持不透明源沙箱边界**的前提下让预览可用 |
+| 验收标准 | ① 沙箱态下自包含 HTML（含内联脚本/样式）完整可见；② `sandbox` 令牌一个字符不变（不加 `allow-same-origin`）；③ 解锁态下多文件 HTML 的相对资源也能加载；④ 取文档失败时仍能把路由的错误答复透出，而不是白屏 |
+| 状态 | ✅ 已完成（`4c242ac`：主框架 `fetch` 取文档 → `srcDoc` 交付，见 [03-功能说明](03-功能说明)） |
+
+### R4 — 插件面板不得盖住宿主与其他插件的弹窗
+
+| 项 | 内容 |
+| --- | --- |
+| 现象 | 打开「社区插件市场」（宿主自带的 `dsh-community-market`）时，弹窗左下角被本插件的文件面板**切掉** |
+| 根因 | 桌面壳给上游 `#root` 打标 `data-dsh-desktop-content-viewport` 并施加 `isolation: isolate`——`#root` 成为层叠上下文，宿主的 overlay 层（`.dshDesktopOverlay`，`z-index: 1000`）就在其中；而插件的面板宿主挂在 `document.body`（在该上下文**之外**）且是带 `z-index: 25` 的定位元素，于是整块画在其上，宿主 overlay 的 1000 根本没参与竞争 |
+| 需求 | 遵守宿主的层叠契约：**在 app 内容之上、在宿主 overlay 层之下** |
+| 验收标准 | ① 插件市场弹窗完整盖住本插件面板；② 本插件面板仍在对话内容之上；③ 非桌面壳部署（纯网页）行为不变 |
+| 状态 | ✅ 已完成（`4422001`：宿主挂载点改为 `#root[data-dsh-desktop-content-viewport]`，无标记时回退 `document.body`） |
+
+### R5 — 可运维：版本线可预期、升级可回滚
+
+| 项 | 内容 |
+| --- | --- |
+| 现象 | 跟随上游新版本时，插件可能**静默失效**（不报错、不加载、无日志），排查成本高 |
+| 根因 | 宿主启动时的兼容性预检 `semver.satisfies(host, peerRange, { includePrerelease: true })`：caret 范围跨 minor 必为 false → 整行禁用 |
+| 需求 | ① 同时维护两条互相独立的版本线（旧宿主线 / 新宿主线），各自钉住可用的上游基线与 peer 范围；② 每次升级都有可回滚锚点（分支 + tag）；③ 文档写清「哪条线配哪个宿主」 |
+| 验收标准 | ① `main`（1.2.0 / 上游 v0.19.1 / peer `^0.1.5-rc.1`）与 `sync/v0.24.1`（1.3.0 / 上游 v0.24.1 / peer `^0.2.0-rc.1`）均可独立构建并通过门禁；② 远端有 `backup/*` 分支与 `apes-v*` tag 作为锚点；③ 部署指南给出选线决策 |
+| 状态 | ✅ 已完成（见 [05-运维手册](05-运维手册)） |
+
+## 三、非目标（scope lock）
+
+| 不做 | 原因 |
+| --- | --- |
+| 新增上游之外的工作台面板（文件 / 终端 / 浏览器） | 属上游与宿主职责；本 fork 只用它们，不重造 |
+| 团队 / 房间 / 多智能体协作面板 | 属宿主 `dsh-background-agents` 一类能力的职责 |
+| 为「能用」而放宽沙箱（例如给预览 iframe 加 `allow-same-origin`） | **安全底线**：不拿安全边界换便利（R3 明确要求保住不透明源） |
+| 直接 merge 上游提交 | 冲突面大、易引入无关变更；改用测量式 re-base（见 [07-开发与测试](07-开发与测试)） |
+
+## 四、约束条件
+
+1. **安全边界不可降级**：HTML 预览与浏览器类内容一律在不透明源沙箱中渲染；新增能力不得要求放宽它。
+2. **KISS / DRY**：一处逻辑只写一遍（例如两处 HTML 预览共用 `HtmlPreviewFrame`）。
+3. **双语**：所有面向用户的文案必须同时有 `zh` 与 `en`（本次会话新增文案遵循此约定）。
+4. **可回滚**：任何升级前先留分支/tag 锚点，改动都能一条命令回退。
+5. **不污染运行环境**：不把未验证的新线同步进正在使用的 DSH profile。
+
+## 五、需求 → 实现 → 锚点
+
+| 需求 | 主要实现位置 | 关键提交 |
+| --- | --- | --- |
+| R1 单一侧边栏 | `src/client/native/`（原生侧边栏适配层） | `5a7e213` / `e5d34ac` |
+| R2 信息层三 tab | `src/client/apes/`（`tabs.tsx` / `icons.tsx` / `locales.ts`） | 随 `5a7e213`、`e5bbef1` 同步 |
+| R3 HTML 预览 | `src/client/HtmlPreviewFrame.tsx` + `src/client/html-preview.ts` | `4c242ac` |
+| R4 层叠契约 | `src/client/desktop-env.ts`（`panelHostParent`）+ `src/client/index.tsx` | `4422001` |
+| R5 版本线可运维 | 分支 `main` / `sync/v0.24.1`、tag `apes-v1.1.0-pre-sync`、`apes-v1.2.0` | `4422001` / `e5bbef1` |

docs/wiki/02-系统架构.md

@@ -0,0 +1,154 @@
+# 02 · 系统架构
+
+> 本篇说明插件的**分层、接口面、层叠契约与关键不变量**。
+> 与源码一一对应，可直接当作改动前的「雷区地图」使用。
+
+## 一、总体分层
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ DSH 宿主（Desktop Electron 壳 / Web profile）                              │
+│  ├─ 原生右侧栏   ctx.sidebarRight / sidebarRightTabs（tab 类型注册表）       │
+│  ├─ 会话与任务   ctx.sessions.list（会话摘要、子代理、投影）、ctx.tools       │
+│  ├─ webServer    路由挂载点（插件用 /sidebar/* 前缀注册）                    │
+│  └─ 桌面壳层     webserver 外层的请求围栏 + #root 的 content-viewport 标记   │
+└───────────────┬──────────────────────────────────────────────────────────┘
+                │ ① 宿主 → 插件：cordis 服务注入（inject）
+                │ ② 插件 → 宿主：原生 tab / 资源打开 / 路由
+┌───────────────┴──────────────────────────────────────────────────────────┐
+│ 插件 HOST 半（Node，lib/index.js）                                         │
+│  · src/index.ts      路由注册（/sidebar/*）、信任围栏、会话/文件数据、HTML 交付 │
+│  · src/trust-fence.ts 请求信任围栏（Host 头 / 令牌）                         │
+│  · src/invariant.ts  依赖零的断言与 semver 工具（host/client 共用）           │
+└───────────────┬──────────────────────────────────────────────────────────┘
+                │ 浏览器侧模块（__ModuleLoader__ bundle，非 CJS）
+┌───────────────┴──────────────────────────────────────────────────────────┐
+│ 插件 CLIENT 半（浏览器，lib/client.js + 懒加载 chunk）                      │
+│  · src/client/index.tsx    应用入口：装配 store/service/原生适配/信息层       │
+│  · src/client/native/      原生右侧栏适配（tab 记录、tab 体、tab 芯片标题）    │
+│  · src/client/builtins/    内置面板：文件 / 文件变动 / 子代理 / 侧边对话 /     │
+│                            终端 / 浏览器 + 文件预览器                        │
+│  · src/client/sidebar/     自绘底部工作台与开合控件（原生侧边栏之外的部分）     │
+│  · src/client/apes/        信息层三 tab（本 fork 的增量）                     │
+│  · src/client/service.ts   ctx.betterSidebar 服务（供其他插件注册）            │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## 二、构建产物
+
+| 产物 | 角色 | 备注 |
+| --- | --- | --- |
+| `lib/index.js` | host 半（ESM，Node） | 路由、围栏、数据面 |
+| `lib/invariant.js` | 不变量面（零依赖） | host/client 都要 import，**不得**引入 Node 内置或宿主包 |
+| `lib/client.js` | client 主 bundle | 浏览器 `window.__ModuleLoader__.load({...})` 形态，**不是** CJS/ESM，Node 里 `require` 会因 `window is not defined` 抛错 |
+| `lib/client-registry.js` | 懒加载 chunk | 高开销能力（图标/预览库）按需加载 |
+| `lib/client-editor.js` | 懒加载 chunk | 编辑器（CodeMirror 系） |
+| `lib/client-locale.js` | 懒加载 chunk | 语言包 |
+| `lib/client-mermaid.js` | 懒加载 chunk | Mermaid 渲染 |
+| `lib/client-terminal.js` | 懒加载 chunk | 终端 |
+| `lib/types/**/*.d.ts` | 类型声明 | 供消费方类型检查 |
+
+> 懒加载动机：主 bundle 不应静态 import 重型预览库；chunk 通过宿主 `ctx.modules` 解析外部依赖
+> （入口在 `src/client/index.tsx` 里先 `setChunkModuleSystem(ctx.modules)`）。
+
+## 三、三层接口面
+
+### 3.1 宿主 → 插件（cordis 注入）
+
+```ts
+// src/index.ts
+export const name = 'dsh-apes-sidebar'
+export const inject = ['webServer', 'sessions', 'webRuntime', 'tools']
+export function apply(ctx: Context, config?: SidebarConfig): void
+```
+
+客户端侧读取的宿主面（结构化镜像，运行时由宿主提供）：
+`ctx.sessions.list`（`getSnapshot/subscribe`）、`ctx.sidebarRight`（原生右列与 `openResource`）、
+`ctx.slots`、`ctx.settings`（挂载行 `config`）、`ctx.modules`（懒加载 chunk 的模块系统）。
+
+### 3.2 插件 → 宿主
+
+| 方向 | 手段 |
+| --- | --- |
+| 注册 tab 类型与 tab 体 | `src/client/native/registerNativeSurface()` → 原生右侧栏注册表 |
+| 打开会话内文件 | `ctx.sidebarRight.openResource('dsh-resource://file/…')` |
+| 暴露 HTTP 能力 | `/sidebar/` 前缀路由：`api` · `file` · `html` · `upload` · `ws/terminal` · `ws/agent-opens` · `ws/agent-terminals` |
+
+### 3.3 插件 → 其他插件（对外服务）
+
+`ctx.betterSidebar`（`src/client/service.ts`）对外开放 `registerTab` / `registerFileViewer` 等，
+并按「能力清单」做前向兼容门控（能力只增不减）。对外契约见仓库内
+[docs/external-plugin-guide.md](../blob/main/docs/external-plugin-guide.md)。
+服务版本常量 `SIDEBAR_SERVICE_VERSION` 必须与 `package.json` / `dsh.plugin.json` 的版本三方一致
+（有单元测试断言这一对）。
+
+## 四、面板宿主与层叠契约（重点雷区）
+
+插件的所有面板渲染在一个 **body 级（或壳层 viewport 级）的宿主层**里：
+
+```css
+[data-dsh-panel-host] { position: fixed; inset: 0; z-index: 25; pointer-events: none }
+```
+
+`z-index: 25` 不是随手取的，它要同时满足：**在 app 内容与壳层 overlay 之上、在宿主交给插件用的
+overlay 槽之下**。完整取义：
+
+| 层级 | 对象 |
+| --- | --- |
+| `z-index: auto` | app 的流内内容、`.dshDesktopFrame` |
+| **25** | **本插件的面板宿主** |
+| 30 | 宿主的动态插件面板（ui-cordis） |
+| 100+ | app 的 overlay 栈（Toast / onBoarding 等） |
+| 1000 | `.dshDesktopOverlay[data-shell-overlay]`（宿主给 `shell.overlay` 槽的容器，第三方弹窗在此） |
+
+**陷阱（已修，`4422001`）**：DSH 桌面壳的有框模式会给上游 `#root` 打标
+`data-dsh-desktop-content-viewport` 并施加 `isolation: isolate`，使 `#root` 成为一个**层叠上下文**。
+宿主自己的 overlay 层就在这个上下文内；若插件宿主挂在 `document.body`（上下文之外），
+它是「带正 z-index 的定位元素」，会画在整个上下文**之上**——把宿主 overlay 里的弹窗（如社区插件市场）盖住。
+
+```ts
+// src/client/desktop-env.ts —— 修法：挂进壳层的 content viewport
+export function panelHostParent(doc: Document = document): HTMLElement {
+  return doc.querySelector<HTMLElement>('#root[data-dsh-desktop-content-viewport]') ?? doc.body
+}
+```
+
+进入该上下文后，25 恢复原意（在 app frame 之上、在 overlay 层 1000 之下）；无该标记的部署
+（纯网页 / 未打标的壳）仍挂 `document.body`，行为不变。重新锚定守卫同时监听
+`document.body` 的 `data-dsh-desktop-mode`（壳层打标与它是同一个 effect），因此壳层在插件挂载**之后**
+才框住 `#root` 的情况也能被搬到正确位置。
+
+## 五、数据流示例
+
+**会话 → 信息层**
+
+```
+ctx.sessions.list.getSnapshot()      →  { byId, projectionsBySession? }
+  useSyncExternalStore(subscribe)        （uSES 安全订阅）
+  ├─ apes:agents  → rootAncestor(byId, scope.sessionId) 找主代理
+  │                 → projectionsBySession[rootId].values.subagentCatalog 取直系子代理
+  │                   （无投影时回退 byId 里的 durable 子会话）
+  └─ apes:profile / apes:apps → byId[scope.sessionId]（标题 / cwd / running）
+```
+
+**文件 → 预览**（HTML 为例）
+
+```
+编辑器/diff 面板 → /sidebar/html/<session>/<path>    （路由负责路径围栏与体积上限）
+  主框架 fetch 取回文档文本 → 注入 <base href="<该文件的路由目录>">
+  → iframe srcDoc + sandbox（不透明源）
+  取失败时回退为 iframe src=路由 URL，把路由的答复原样透出
+```
+
+## 六、关键不变量（改动前必读）
+
+1. **host / client 拆分是结构性的**：client bundle 在浏览器运行，不得 import Node 内置；
+   `src/invariant.ts` 两侧共用，必须保持零依赖。
+2. **`dsh-better-sidebar` 是 peer，永不打包**：一旦被内联，client 会带上第二份侧边栏注册表，
+   tab 注册进死实例，界面上永不出现。
+3. **tab id 前缀归本 fork**：信息层用 `apes:*`；不得占用上游/宿主内部 id。
+4. **HTML 预览的沙箱令牌不得放宽**（不加 `allow-same-origin` 等）；交付方式只能是「主框架取文档 + `srcDoc`」。
+5. **颜色只用宿主设计令牌**（`--dsw-alias-*`），不写硬编码色值；几何量（字号/间距/圆角）无公开令牌，内联即可。
+6. **所有面向用户的字符串走 i18n**，`zh` / `en` 必须同时存在。
+7. **变更后必须重新同步到 profile**：构建产物非字节确定性，且 profile 的 `file:` 依赖是复制语义，
+   不能假定旧副本可用（见 [04-部署指南](04-部署指南)）。

docs/wiki/03-功能说明.md

@@ -0,0 +1,109 @@
+# 03 · 功能说明
+
+> 本篇是**功能清单与行为契约**：有哪些面板、数据从哪来、文案与配色怎么走、安全边界在哪、能配什么。
+
+## 一、面板与标签页总表
+
+「来源」列：**上游** = 来自 `dsh-better-sidebar`；**宿主** = DSH 自身提供并占用该槽位；**本 fork** = 本项目的增量。
+
+| id | 名称 | order | 来源 | 数据 / 行为 |
+| --- | --- | --- | --- | --- |
+| `editor` | 文件 | 10 | 上游 | 文件树 + 编辑器（CodeMirror 系，懒加载 `client-editor`） |
+| `git` | 文件变动 | 20 | 上游 | 工作区变更、单个 diff 视图 |
+| `subagent` | 子代理 | 30 | 上游 | 会话的子代理视图 |
+| `sidechat` | 侧边对话 | 35 | 上游 | 会话内旁路对话 |
+| `terminal` | 终端 | 40 | 上游 | PTY 终端（懒加载 `client-terminal`；v0.24.1 线起由宿主内置终端承担） |
+| `browser` | 浏览器 | 50 | 上游 | 内嵌浏览器/HTML 预览宿主 |
+| `diff` | （内部） | -1 | 上游 | 非用户可见，供内部打开 diff |
+| **`apes:agents`** | **智能体** | **60** | **本 fork** | 主代理 + 直系子代理拓扑 |
+| **`apes:apps`** | **应用** | **65** | **本 fork** | 当前会话所属工作区（宿主暂无「应用」feed） |
+| **`apes:profile`** | **画像** | **70** | **本 fork** | 当前会话摘要（标题 / cwd / 运行态） |
+
+> order 10–50 是上游/宿主既定带宽，apos 信息层取 60/65/70 留出余量，避免与原生面板抢占位置。
+
+## 二、信息层三 tab（本 fork 的增量）
+
+三个 tab 全部是**单实例**（`single: true`），且都按 DSH 标准 `TabDescriptor` 注册，
+因此自动获得原生侧边栏的全部待遇：进入原生 guide、tab 芯片带图标、可开合与分栏。
+
+| tab | 展示内容 | 数据来源 | 空态 |
+| --- | --- | --- | --- |
+| `apes:agents` | 根（主代理）卡片 + 其直系子代理卡片；每行显示标签、`one-shot`/`continuable`、运行态圆点 | ① `ctx.sessions.list` 的 `byId`（durable 会话摘要）；② 宿主的会话投影 `projectionsBySession[sessionId].values.subagentCatalog`（直系子代理清单） | 「当前会话没有子代理」提示 |
+| `apes:apps` | 当前会话的工作区（cwd） | `byId[scope.sessionId].cwd`，回退 `scope.cwd` | 明确写出「宿主今日无应用 feed」 |
+| `apes:profile` | 会话标题、运行/空闲、cwd | `byId[scope.sessionId]` | 「无 cwd」提示 |
+
+**实现要点**：两个来源被归一化成同一种行形状 `{ id, label, mode }`，**活动态统一从 `byId` 读**，
+于是「投影已就绪」与「仅有 durable 摘要」两种情况下渲染一致；这也是上游 0.1.6→0.1.7 会话 feed
+迁移（`subagentsByParent` → `projectionsBySession`、`list.current` 删除）后的落地方式。
+
+## 三、文件预览器
+
+| id | 适用 | 说明 |
+| --- | --- | --- |
+| `image` | 图片 | 走媒体路由，受 `mediaLimit` 限制 |
+| `pdf` | PDF | 内嵌查看 |
+| `markdown` | Markdown | 渲染（Mermaid 走懒加载 chunk，可手动刷新） |
+| `html` | HTML | **不透明源沙箱 iframe**，见下节 |
+| `code` | 代码 | 高亮查看（编辑器懒加载） |
+| `binary-download` | 二进制 | 只提供下载 |
+
+### 3.1 HTML 预览的交付方式（重要）
+
+```
+路由 /sidebar/html/<session>/<path>    ← 路径围栏 + 体积上限（readLimit）
+        │
+        ├─ 主框架 fetch（唯一同时被宿主围栏信任、又能带上 Electron 头的角色）
+        │
+        ├─ 注入 <base href="<该文件的路由目录>">   ← 让 ./style.css 等相对引用解析回本文件所在目录
+        │
+        └─ iframe srcDoc=<文档> + sandbox=HTML_IFRAME_SANDBOX
+```
+
+| 状态 | 自包含 HTML | 多文件 HTML（外链 CSS/JS/图片） |
+| --- | --- | --- |
+| 沙箱态（默认） | ✅ 完整可用 | 正文可用，**相对资源不可用**（iframe 源为 `null`，子请求同样被宿主围栏拒绝） |
+| 临时解锁（无 sandbox 属性） | ✅ | ✅ **相对资源可用**（iframe 继承 GUI 源，成为普通同源请求） |
+
+设计取舍：**沙箱令牌一个字符都不放宽**。多文件 HTML 想要完整效果需用户显式点「临时解锁」——
+这是把「放宽边界」的决定权留给用户的显式动作，而不是插件默认降级。
+
+## 四、安全边界（三层）
+
+| 层 | 机制 | 说明 |
+| --- | --- | --- |
+| 预览内容 | `sandbox="allow-scripts allow-popups allow-downloads allow-modals"` | **不含 `allow-same-origin`**：预览文档运行在不透明源里。宿主路由另有 CSP `sandbox` 兜底 |
+| 插件路由 | 请求信任围栏（`src/trust-fence.ts`） | 校验 Host 头/令牌，拒绝跨站或非授权来源对 `/sidebar/*` 的访问 |
+| 桌面壳 | Electron 注入的 `x-dsh-desktop-renderer` 头 | 扩展模式下所有路由的前置围栏；只发给主框架与同源子框架。这正是「沙箱 iframe 发不出请求」的根源 |
+
+## 五、i18n 与主题
+
+- **语言包**：`src/client/locales.ts` + 19 个 `src/client/locales-*.ts` 覆盖文件；默认 `zh`，缺省回退 `en`。
+- **本 fork 文案**：集中在 `src/client/apes/locales.ts`，每个 key 同时提供 `zh` / `en`。
+- **硬性约定**：界面里**不得出现裸字符串**，一律 `t('key')`。
+- **配色**：只用宿主设计令牌 `--dsw-alias-*`（bg / border / label / state / interactive 系列），
+  写法为 `var(--dsw-alias-xxx, <字面回退>)`，保证在非 DSH 环境（单元测试）也能渲染。
+  **无公开的 `--ds-*` 几何令牌**，字号/间距/圆角内联即可。
+
+## 六、配置面（挂载行 `config`）
+
+配置写在插件挂载行上（profile 的 `cordis.patch.yml` 或 bundle patch 的 insert 行），设置页写的也是它：
+
+| 字段 | 默认 | 含义 |
+| --- | --- | --- |
+| `readLimit` | `512 KiB` | 单文件读取上限（超出截断并标记 `truncated`） |
+| `mediaLimit` | `20 MiB` | 媒体（图片等）读取上限 |
+| `uploadLimit` | `128 MiB` | 上传上限 |
+| `listLimit` | `1000` | 目录列举条目上限 |
+| `terminalsPerSession` | `3` | 每会话终端数上限 |
+| `shell` / `shellArgs` | 自动解析 | 终端 shell 与其启动参数（`shellArgs` 非空时替换默认 `-l`） |
+
+例：在挂载行里指定 shell
+
+```yaml
+- insert:
+    - id: better-sidebar
+      name: 'dsh-apes-sidebar'
+      config:
+        shell: /bin/zsh
+        shellArgs: ['--noprofile', '--no-rc']
+```

docs/wiki/04-部署指南.md

@@ -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:` 副本也不会自动跟随。

docs/wiki/05-运维手册.md

@@ -0,0 +1,133 @@
+# 05 · 运维手册
+
+> 本篇是**日常运维、升级与回滚**的操作手册。所有命令都以「先留锚点、再动手、改完回读验证」为原则。
+
+## 一、版本线与分支策略（当前远端实况）
+
+| ref | 指向 | 含义 / 用途 |
+| --- | --- | --- |
+| `main` | `4422001` | **旧宿主线**：插件 1.2.0，上游基线 v0.19.1，peer `^0.1.5-rc.1`。本机 DSH Desktop 2.0.10 正在跑这条 |
+| `sync/v0.24.1` | `e5bbef1` | **新宿主线**：插件 1.3.0，上游基线 v0.24.1，peer `^0.2.0-rc.1`。待 ≥0.2.0 宿主实机验证 |
+| `backup/pre-sync-v0.19.1` | `96cc334` | v0.19.1 re-base **之前**的状态（旧 fork 三角色 tab 版） |
+| `backup/pre-sync-v0.24.1` | `4422001` | v0.24.1 re-base 之前的 `main`（等价于当前 main，作为下次升级的锚点） |
+| `tags/apes-v1.1.0-pre-sync` | `96cc334` | 与上面第一支 backup 同一提交，tag 形式的锚点 |
+| `tags/apes-v1.2.0` | `4422001` | 当前已验收的 1.2.0 线 |
+
+**纪律**：任何 re-base / 大改之前，先建 `backup/pre-sync-<新基线>` 分支 + `apes-v<版本>` tag，
+并**推送**到远端（本地锚点在多人/多机场景等于不存在）。
+
+## 二、回滚剧本
+
+### 场景 A：某次提交引入回归（单点回退）
+
+```bash
+cd <插件仓库>
+git log --oneline -5                 # 定位可疑提交
+git revert <sha>                     # 保留历史的回退（推荐）
+# 或整体丢弃：git reset --hard <上一提交>
+pnpm typecheck && pnpm build && pnpm test
+cd ~/.dsh/profiles/<profile> && pnpm install   # file: 是复制语义，必须重装
+# ⌘Q 完全退出 DSH → 重启
+```
+
+### 场景 B：整条线回退（例如新线在真机上不可用）
+
+```bash
+git checkout main                    # 或 backup/pre-sync-v0.24.1
+pnpm install && pnpm build
+cd ~/.dsh/profiles/<profile> && pnpm install
+# ⌘Q 重启
+```
+
+### 场景 C：profile 依赖/config 被改坏
+
+```bash
+cd ~/.dsh/profiles/<profile>
+cp package.json package.json.bak.$(date +%s)     # 先备份
+bash <插件仓库>/scripts/switch.sh aps            # 或 upstream，脚本会重写依赖与 bundle 行
+pnpm install
+# ⌘Q 重启
+```
+
+**回滚验收**：重启后按 [04-部署指南](04-部署指南) §三 的验收清单逐条核对（至少「右列一套侧边栏」
+与「三个信息层 tab 存在」两条）。
+
+## 三、发布 / 变更纪律
+
+1. **版本三元组必须一致**：
+   - `package.json` 的 `version`
+   - `dsh.plugin.json` 的 `version`
+   - `src/client/service.ts` 的 `SIDEBAR_SERVICE_VERSION`
+   三者不一致会被单元测试（`tests/service.spec.ts`）直接拦下——**不要改其中一个而忘了另一个**。
+2. **门禁三连必过**：`pnpm typecheck && pnpm build && pnpm test`。当前基线：`main` 131 个测试文件 /
+   1367 通过；`sync/v0.24.1` 141 个文件 / 1515 通过（另有 9 个 skip）。
+3. **产物非字节确定性**：两次构建的字节数可能相同但 **sha 不同**。因此「改完代码 → 让 profile 用旧副本」
+   永远不成立；必须重新 `pnpm build` + 让 profile 重新安装。
+4. **发布方式**：本 fork 未发布 npm 包，发布 = 推分支/tag + 目标机器 `git fetch && checkout && pnpm build`
+   + profile 重装。发布前把 `README.md` 与 `docs/wiki/` 一并更新（wiki 见 §六）。
+5. **不要顺手改无关文件**：re-base 时保持「只带自己的增量」，避免下次升级冲突面扩大。
+
+## 四、日常巡检清单
+
+| 频率 | 检查项 | 命令 / 判据 |
+| --- | --- | --- |
+| 每次部署后 | 版本三元组一致 | 见 §三.1 |
+| 每次部署后 | 产物标记齐全 | `grep -c 'apes:agents' lib/client.js`（>0）、`grep -c 'dsh-desktop-content-viewport' lib/client.js`（>0） |
+| 每次部署后 | profile 副本已刷新 | 比对 `lib/client.js` 与 `~/.dsh/profiles/<p>/node_modules/dsh-apes-sidebar/lib/client.js` 的 sha256 |
+| 每次升级宿主/插件 | 宿主版本 ↔ peer 范围 | 见 [04-部署指南](04-部署指南) §1.1（不匹配 = 静默禁用） |
+| 每月/大改前 | 锚点是否已推远端 | `git ls-remote <remote> \| grep -E 'heads/(main\|sync)\|tags/apes'` |
+| 异常时 | 诊断条与控制台 | 页面左下角红条；控制台 `[dsh-apes-sidebar]` 前缀 |
+
+## 五、备份与配置铁律
+
+- **改任何 profile 配置前先备份**，改完**回读验证**（不要假定写入即生效）：
+
+  ```bash
+  cp ~/.dsh/profiles/<profile>/package.json{,.bak.$(date +%s)}
+  # 改完：
+  python3 -c "import json;json.load(open('$HOME/.dsh/profiles/<profile>/package.json'));print('JSON OK')"
+  ```
+
+- **DSH 应用配置的类型陷阱**：部分字段（如材质/透明度类的 `macosMaterial`）必须是**字符串**
+  （`"off"` / `"transparent"`）。若被写成 YAML 布尔（`false`），DSH 会启动进**恢复模式**。
+  改完务必回读校验类型：
+
+  ```bash
+  python3 -c "import yaml;d=yaml.safe_load(open('$HOME/.dsh/settings.yaml'));v=d.get('macosMaterial');print(v, type(v).__name__)"
+  ```
+
+- **不要回滚/手工编辑** profile 的 `pnpm-lock.yaml`：由 pnpm 重建；手工改会导致解析错乱。
+- **凭据不进仓库**：远端推送用系统凭据助手（`git credential fill`），仓库内不写 token。
+
+## 六、百科（wiki）本身的维护
+
+百科源文件版本化在仓库 `docs/wiki/`，通过脚本推送到 Gitea wiki：
+
+```bash
+bash scripts/push-wiki.sh            # 推送/更新全部页面（幂等：有则 PATCH，无则 POST）
+bash scripts/push-wiki.sh 05-运维手册 # 只推一页
+```
+
+凭据来自 `git credential fill`（与推送代码同一套，不落盘）。修改文档的推荐流程：
+**改 `docs/wiki/*.md` → 提交到仓库 → 跑脚本推送**，这样 wiki 与代码同源可回溯。
+
+## 七、诊断与日志
+
+| 信号 | 含义 | 位置 |
+| --- | --- | --- |
+| 左下角红色诊断条 `[dsh-apes-sidebar] <phase> error: …` | client 生命周期某阶段抛错（mount / native / 懒加载等） | 页面左下角（`z-index: 2147483000`），同时 `console.error` 打前缀 |
+| 控制台 `[dsh-apes-sidebar] …` | 同上，且带上具体阶段名 | 开发者工具 Console |
+| 「插件像没装」且**无任何日志** | 宿主兼容性预检失败（peer 不匹配）→ **静默禁用** | 只能靠版本矩阵排查，见 [06-故障排查](06-故障排查) §1 |
+| 界面正常但面板层级错乱 | 面板宿主挂载点/层叠上下文问题 | 见 [02-系统架构](02-系统架构) §四 |
+
+## 八、性能与容量
+
+| 项 | 观察值 | 说明 |
+| --- | --- | --- |
+| `lib/client.js` | ≈ 0.9 MB | 主 bundle，始终加载 |
+| `lib/client-mermaid.js` | ≈ 7 MB（+12 MB map） | 懒加载，仅在需要渲染 Mermaid 时拉取 |
+| `lib/client-editor.js` | ≈ 2 MB | 懒加载，仅打开编辑器时 |
+| `lib/client-terminal.js` | ≈ 0.5 MB | 懒加载，仅打开终端时 |
+| 全量测试 | 约 3–4 分钟 | 变更后按需跑全量，日常可只跑相关 spec |
+
+主 bundle 不应静态引入上述重型库；新增重型依赖一律走 `src/client/chunks/`（懒加载 chunk）。

docs/wiki/06-故障排查.md

@@ -0,0 +1,208 @@
+# 06 · 故障排查
+
+> 每条都给出**症状 → 根因（机制）→ 处置 → 验证**。标注 ✅ 的条目是在真机上定位并验证过的案例。
+
+## 速查表
+
+| 症状 | 最可能根因 | 跳到 |
+| --- | --- | --- |
+| 装完「像没装」，界面无变化且**无任何日志** | peer 范围与宿主版本不匹配 → 静默禁用 | §1 |
+| 页面出现**两个侧边栏** / 两套开合按钮 | 双挂载（两条线同装，或残留挂载行） | §2 |
+| HTML 预览只显示 `forbidden` | 桌面壳渲染器围栏 + 不透明源 iframe | §3 |
+| 插件面板盖住宿主/第三方弹窗（如插件市场） | 面板宿主挂在层叠上下文之外 | §4 |
+| 终端打不开 / `node-pty` 加载失败 | pnpm 拦截原生构建（仅 v0.19.1 线） | §5 |
+| 改了代码，界面没变 | 产物未重建 / profile 副本未刷新 / 浏览器缓存 | §6 |
+| DSH 拒绝加载插件、entry pending | 插件声明（`dsh.plugin.json` / bundle patch）不合法 | §7 |
+| DSH 启动进**恢复模式** | profile 配置被写成错误类型（如 YAML 布尔） | §8 |
+
+---
+
+## §1 装完「像没装」：静默禁用 ✅
+
+**症状**：profile 里依赖装了、文件也在，但界面没有任何变化；日志里也没有插件相关报错。
+
+**根因**：宿主启动时做兼容性预检，判定 `peerDependencies` 与自身版本是否满足：
+
+```
+semver.satisfies(hostVersion, peerRange, { includePrerelease: true })
+```
+
+caret 范围**跨 minor 必然为 false**（例如 `^0.1.5-rc.1` 对 `0.2.0`）。判定失败后宿主的处理是
+**跳过这一行**——不抛错、不打日志、不加载。
+
+**处置**：核对宿主版本，改用匹配的版本线（见 [04-部署指南](04-部署指南) §1.1）。
+
+```bash
+grep -m1 '"version"' "/Applications/DSH Desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh/package.json"
+grep -n 'dsh-client-ui-sidebar-right' <插件仓库>/package.json     # 看 peer 范围
+```
+
+**验证**：重启后右列出现插件 tab；`lib/client.js` 里能 grep 到 `apes:agents`。
+
+**教训**：这一条没有日志可查，因此**部署前先看版本矩阵**是唯一可靠的预防手段。
+
+## §2 两个侧边栏 / 两套开合按钮 ✅
+
+**症状**：窗口里出现两套右侧面板与两组开合控件。
+
+**根因**：两个方向都可能：
+1. **旧版遗留**：v0.18.0 基线时插件自绘右侧面板与开关（`toggleCluster`）。升级后自绘部分应已移除。
+2. **双挂载**：同一条线被挂两次（profile 自己的 `cordis.patch.yml` 里还留着旧挂载行，
+   与 bundle patch 同时生效），或者本 fork 线与上游线同时安装（两者都注册 `ctx.betterSidebar`，
+   entry id 冲突，第二个被丢弃）。
+
+**处置**：
+
+```bash
+# 确认产物里已经没有自绘开关
+grep -c toggleCluster <插件仓库>/lib/client.js        # 期望 0
+
+# 检查是否双挂载：profile 里是否同时存在 bundle 行 与 手写挂载行
+grep -n "dsh-apes-sidebar\|dsh-better-sidebar" ~/.dsh/profiles/<profile>/cordis.patch.yml ~/.dsh/profiles/<profile>/package.json
+```
+
+- 有残留手写挂载行 → 删除它，只保留一条通道。
+- 两条线同装 → `bash scripts/switch.sh aps`（或 `upstream`）二选一。
+- 装了聚合包（如 `@linxin666/dsh-web-ui-all`）→ 确认聚合包在本包之前，让包内守卫生效。
+
+**验证**：右列只剩一套面板与一个开合控件。
+
+## §3 HTML 预览显示 `forbidden` ✅
+
+**症状**：预览 HTML 文件时 iframe 里只有一行裸文本 `forbidden`；而「临时解锁」后又能看。
+
+**根因（三层）**：
+
+1. DSH Desktop 在**扩展模式**下给所有路由套了一层请求围栏：`ordinaryBrowserEnabled` 恒为 false，
+   不带 Electron 注入的 `x-dsh-desktop-renderer` 头的请求一律 `403 + "forbidden"`；
+2. 该头只注入给 **mainFrame** 与**同源**子框架；
+3. 预览 iframe 的 sandbox 令牌不含 `allow-same-origin`，请求时其源为 `null` → 拿不到头 → 403。
+
+与「是否升级了插件基线」无关（v0.18.0 起行为一致）。
+
+**处置**：插件已在 1.2.0+ 用 **`srcDoc` 交付**修复（主框架取文档 → 注入 `<base>` → 注入 iframe），
+`main` 上对应提交 `4c242ac`。**不要**通过给 iframe 加 `allow-same-origin` 来"修"——那是安全降级。
+
+**验证**：
+- 沙箱态下自包含 HTML（含内联脚本）能正常渲染；
+- 有外链资源的 HTML 在沙箱态下缺资源属**已知限制**，点「临时解锁」后应完整显示。
+
+**排查命令**（确认宿主围栏在起作用）：
+
+```bash
+lsof -nP -iTCP -sTCP:LISTEN | grep -i dsh          # 找宿主端口（每次启动可能不同）
+curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:<端口>/"   # 无渲染器头 → 403
+```
+
+## §4 插件面板盖住宿主/第三方弹窗 ✅
+
+**症状**：打开「社区插件市场」（宿主自带 `dsh-community-market`）时，弹窗左下角被本插件的
+文件面板整齐切掉一块。
+
+**根因**：桌面壳的有框模式会给上游 `#root` 打标 `data-dsh-desktop-content-viewport` 并施加
+`isolation: isolate`，使 `#root` 成为**层叠上下文**；宿主的 overlay 层（`.dshDesktopOverlay`，
+`z-index: 1000`）位于其中。插件面板宿主若挂在 `document.body`（该上下文之外）且是定位元素，
+就会画在整个上下文之上，把 overlay 里的弹窗盖住。
+
+**处置**：已修（`4422001`）——面板宿主改为挂进 `#root[data-dsh-desktop-content-viewport]`，
+无标记时回退 `document.body`。**不要**通过调大 `z-index` 解决（25 的取义见
+[02-系统架构](02-系统架构) §四；乱调会破坏与宿主其他层级的关系）。
+
+**验证**：插件市场弹窗完整盖住本插件面板，同时本插件面板仍在对话内容之上。
+
+## §5 终端不可用 / `node-pty` 加载失败（仅 v0.19.1 线）✅
+
+**症状**：终端面板报 shell 启动失败或提示 `node-pty` 加载失败；`pnpm install` 阶段报
+"ignored build scripts"。
+
+**根因**：pnpm 11 默认**拦截依赖的构建脚本**，`node-pty` 的原生二进制没被编译。
+（`main` 依赖 `node-pty`；`sync/v0.24.1` 已移除该依赖，终端由宿主内置承担。）
+
+**处置**：
+
+```bash
+cd ~/.dsh/profiles/<profile>
+pnpm approve-builds            # 选中 node-pty
+pnpm rebuild node-pty          # 必要时
+# ⌘Q 完整退出 DSH 再启动
+```
+
+**验证**：终端能开出 shell；`node_modules/node-pty/build/Release/*.node` 存在。
+
+## §6 改了代码，界面没变 ✅
+
+**症状**：源码已改、`pnpm build` 也跑了，但界面行为仍是旧的。
+
+**根因（三个叠加因素）**：
+
+1. 产物**非字节确定性**，且 profile 的 `file:` 依赖是**复制**语义 → profile 里仍是旧副本；
+2. `lib/client.js` 是浏览器的 `window.__ModuleLoader__.load({...})` bundle，**不是 CJS/ESM**，
+   在 Node 里 `require` 会因 `window is not defined` 报错——因此不能用「在 Node 里试跑」来验证前端改动；
+3. host 半的改动必须重启进程（client 半有热加载，host 半没有）。
+
+**处置**：
+
+```bash
+cd <插件仓库> && pnpm build
+cd ~/.dsh/profiles/<profile> && pnpm install      # 刷新 file: 副本
+# ⌘Q 完整退出 DSH → 重启
+```
+
+**验证**：比对两边产物 sha：
+
+```bash
+shasum -a 256 <插件仓库>/lib/client.js \
+  ~/.dsh/profiles/<profile>/node_modules/dsh-apes-sidebar/lib/client.js
+```
+
+## §7 DSH 拒绝加载插件 / entry pending
+
+**症状**：插件目录存在，但宿主不加载，或 loader 报 entry pending / 恢复模式。
+
+**根因**：插件的声明面不合法或不被接受，常见于：
+- `dsh.plugin.json` 的 `engines.dsh` 与宿主不符；
+- bundle patch / 挂载行的 `insert` 结构不合法（例如把声明写成宿主无法解析的形态）；
+- 同 id 重复挂载（`duplicate loader entry id` / `duplicate prefix route`）。
+
+**处置**：
+
+```bash
+cat <插件仓库>/dsh.plugin.json                      # 检查 id / engines / main
+cat <插件仓库>/cordis.patch.yml                     # 检查 insert 结构与守卫表达式
+grep -n "cordis.patch\|dsh-apes-sidebar" ~/.dsh/profiles/<profile>/package.json
+```
+
+确保只有一条挂载通道、`name` 与实际包名一致（本 fork 为 `dsh-apes-sidebar`），
+`engines.dsh` 与宿主版本相容。改完 `pnpm install` + **完整重启**。
+
+**验证**：启动日志无 loader 报错；右列出现插件 tab。
+
+## §8 DSH 启动进「恢复模式」
+
+**症状**：DSH 启动后进入恢复/安全模式，插件与侧边栏都不正常。
+
+**根因**：profile 或应用配置被写成**错误类型**。典型是材质/透明度字段要求**字符串**
+（`"off"` / `"transparent"`），但被 YAML 序列化成了布尔 `false` —— 宿主按类型校验失败即进恢复模式。
+
+**处置与验证**：
+
+```bash
+python3 -c "import yaml;d=yaml.safe_load(open('$HOME/.dsh/settings.yaml'));v=d.get('macosMaterial');print(repr(v), type(v).__name__)"
+# 期望：'off' str（或 'transparent' str）；若为 False bool → 改回字符串
+```
+
+改配置前**先备份**，改完**回读校验类型**（见 [05-运维手册](05-运维手册) §五）。
+
+---
+
+## 附：定位手法（本次会话验证有效）
+
+1. **先按用户可见文案 grep 找归属**：`grep -rl "<界面上的中文短语>" <app>/lib <profile>/node_modules`。
+   若两边都搜不到，说明它来自**运行时下载/缓存**（例如市场插件），再按 `NSUserData` 缓存或
+   `desktop-market/state.json` 之类线索去找提供方。
+2. **再读提供方自己的 CSS/DOM 结构**：拿到它声明的 z-index、定位方式与所在槽位
+   （如 `renderSlot("shell.overlay")`），据此判断是「它太高」还是「我们太高」。
+3. **层叠问题先找 `isolation` / `transform` / `filter` / `contain`**：这些才是层叠上下文与包含块的真正来源，
+   比 z-index 数值更关键。
+4. **像素证据要用原图量**：交给视觉模型的截图会被缩放（1920→1280），裁剪坐标 ≠ 屏幕坐标；
+   用 PIL 在原图上量边界、比对 RGB 剖面，再下结论。

docs/wiki/07-开发与测试.md

@@ -0,0 +1,164 @@
+# 07 · 开发与测试
+
+> 面向改代码的人（与 agent）。**先读 [02-系统架构](02-系统架构) §六「关键不变量」**，
+> 再动手改，能省掉大部分回退。
+
+## 一、工程约定
+
+| 项 | 约定 |
+| --- | --- |
+| 语言 | TypeScript **strict**（含 `noUncheckedIndexedAccess`）、ESM、导入写 `.ts` 扩展名 |
+| 构建 | `tsdown`（rolldown），host/client 双产物；懒加载 chunk 走 `src/client/chunks/` |
+| 包管理 | `pnpm`（11.x）；`pnpm install` 会触发 `prepare` 构建 |
+| 测试 | `vitest`；默认 node 环境，需要 DOM 的 spec 用 `// @vitest-environment jsdom` |
+| 宿主 peer | `dsh-better-sidebar`（本仓库已改名）**永不打包**，必须留在 peer/neverBundle 一侧 |
+| 命名 | 信息层 tab id 前缀 `apes:`；插件名 `dsh-apes-sidebar` |
+| 颜色 | 只用 `--dsw-alias-*` 设计令牌（`var(--token, <回退>)`），不写死色值 |
+
+## 二、目录结构（`main` 实况）
+
+```
+src/
+  index.ts              HOST 入口：name / inject / apply(ctx, config)，路由与围栏装配
+  invariant.ts          零依赖不变量面（host/client 共用）
+  context-types.ts      cordis 服务面契约（ctx.sessions / sidebarRight / …）
+  trust-fence.ts        请求信任围栏（Host 头 / 令牌）
+  html-route.ts         /sidebar/html 路由（路径围栏 + 体积上限）
+  config.ts             挂载行配置 schema 与默认值（readLimit / mediaLimit / …）
+  fs-*.ts git.ts …      文件系统、Git、会话、任务、终端等 host 能力
+  client/
+    index.tsx           CLIENT 入口（apply）：装配 store/service/native/apes
+    service.ts          ctx.betterSidebar 服务实现（对外 API + 能力清单）
+    state.ts            侧边栏状态存储（store）
+    native/             原生右侧栏适配（tab 记录、tab 体、tab 芯片标题）
+    builtins/           内置面板：editor / git / subagent / sidechat / terminal / browser + 预览器
+    sidebar/            自绘底部工作台与开合控件
+    apes/               信息层三 tab（本 fork 增量：tabs.tsx / icons.tsx / locales.ts）
+    changes/ diff/      文件变动与 diff 视图
+    chunks/             懒加载 chunk：editor / locale / mermaid / terminal
+    locales*.ts         i18n（`locales.ts` + 19 个语言覆盖文件）
+    *.module.css        组件样式（含 sidebar.module.css：面板宿主层契约）
+tests/                  vitest specs（131 个文件，含 e2e/ 的挂载脚本型用例）
+scripts/                install / switch / e2e 挂载 / 发布辅助
+docs/                   external-plugin-guide.md（对外契约）+ plans/（上游历史设计）+ wiki/（本百科源文件）
+```
+
+## 三、门禁（提交前必跑）
+
+```bash
+pnpm typecheck     # tsc --noEmit（strict）
+pnpm build         # rm -rf lib && tsc(d.ts) && tsdown
+pnpm test          # vitest run
+```
+
+当前基线（本次会话实测）：`main` = 131 文件 / **1367 通过** + 9 skip；
+`sync/v0.24.1` = 141 文件 / **1515 通过** + 9 skip。全量 test 约 3–4 分钟。
+**任何一条不过就不要提交**；三条全绿才算完成。
+
+## 四、测试体系（按层次）
+
+| 层次 | 环境 | 手法 | 代表 spec |
+| --- | --- | --- | --- |
+| 宿主插件形状 / 对外契约 | node | 断言导出面与语义（含与 `package.json` 的版本一致性） | `smoke.spec.ts` · `plugin-shape.spec.ts` · `service.spec.ts` · `consumer-types.ts` |
+| 原生侧边栏适配 | node | 用「类型为真、运行时为假」的 mock 注册表 | `native-surface.spec.ts` |
+| 面板宿主与层叠契约 | node + jsdom | CSS 断言 + DOM 挂载点解析 | `panel-host-css.spec.ts` · `panel-host-parent.spec.ts` |
+| 预览交付 | node + jsdom | 纯逻辑（`<base>` 注入）+ 客户端挂载（stub `fetch`，`createRoot` + `act`） | `html-preview.spec.ts` · `html-preview-frame.spec.tsx` |
+| 沙箱契约 | node | 对渲染结果做**字符串断言**（服务端渲染把 `srcDoc` 输出为 camelCase `srcDoc=""`，与客户端设置的真实属性 `srcdoc` 不同 —— 断言方式随之不同） | `sandbox-views.spec.tsx` |
+| 信息层 tab | node | mock `ctx.sessions.list` 与投影 | `apes-tabs.spec.ts` |
+| 桌面环境探测 | node | stub 全局（URL stamp / preload 标记） | `desktop-env.spec.ts` |
+
+约定：
+- **不引入 jsdom 到默认环境**：需要 DOM 的 spec 在文件头写 `// @vitest-environment jsdom`。
+- **不依赖真实 DSH 宿主**：需要真宿主的用例归到 `tests/e2e/`（脚本型挂载），不进单元门禁。
+- 新增「契约」必须**同时新增 pin 它的 spec**（例如本文档提到的 25 层级、沙箱令牌、`srcDoc` 交付方式，
+  都有对应断言）。改契约 = 改代码 + 改 spec，两者必须一起提交。
+
+## 五、扩展点（对外服务）
+
+其他插件通过 `ctx.betterSidebar` 接入：
+
+```ts
+// 注册一个 tab 类型
+await ctx.betterSidebar.registerTab(descriptor)
+// 注册一个文件预览器
+await ctx.betterSidebar.registerFileViewer(viewer)
+```
+
+- 服务按**能力清单**做前向兼容门控（能力只增不减），消费方应据此判断可用性而非版本号比较。
+- 完整契约、字段表与示例见仓库内 [docs/external-plugin-guide.md](../blob/main/docs/external-plugin-guide.md)。
+- 改服务面时：**只能新增**；删除或改语义需同步更新能力清单、指南与本百科。
+
+## 六、上游同步：测量式 re-base（本项目的方法论）
+
+**不 merge 上游**。上游每个版本差距可达数百文件，直接合并会引入无关变更并放大冲突面；
+本项目改用「先测量、再重建、后补增量」：
+
+### 步骤
+
+**① 测出自己的增量（把改名归一化掉）**
+
+```python
+# 对每个变更文件：取出两边 blob，把改名归一化后比较
+old = git('show', f'{base}:{path}'); new = git('show', f'HEAD:{path}')
+rename_only = old.replace('dsh-better-sidebar', 'dsh-apes-sidebar') == new
+```
+→ 得到三张清单：**仅改名**（自动处理）/ **真改动** / **新增**。数量级参考：v0.19.1→v0.24.1 为
+78 / 11 / 10。
+
+**② 确定改名的精确范围（不要重新推断）**
+
+```bash
+# 仍保留上游名字的文件 = 有意保留（本仓库为 README.md、package.json、docs/plans/*）
+comm -12 <(git grep -l 'dsh-better-sidebar' <旧基线> | cut -d: -f2 | sort) \
+         <(git grep -l 'dsh-better-sidebar' HEAD | cut -d: -f2 | sort)
+```
+其余文件只做子串替换 `dsh-better-sidebar` → `dsh-apes-sidebar`；**camelCase 服务名 `betterSidebar` 必须保留**。
+
+**③ 造一个"改名归一化基座"，让增量与改名解耦**
+
+```bash
+git checkout -B tmp/norm-<旧基线> <旧基线 tag>
+#   → 套同一口径改名 → commit
+git diff tmp/norm-<旧基线> HEAD -- . ':(exclude)pnpm-lock.yaml' > /tmp/apes-delta.patch
+# 校验：这条 diff 的文件清单必须恰好等于 ① 的「真改动 + 新增」
+```
+
+**④ 在新基线上重建 + 三点合并**
+
+```bash
+git checkout -B sync/<新基线 tag> <新基线 tag>
+#   → 套同一口径改名 → commit（"rename only"）
+git apply -3 /tmp/apes-delta.patch        # 冲突会以 <<<<<<< ours / >>>>>>> theirs 留存（命令本身不失败）
+```
+
+**⑤ 逐条判读冲突（只有五种形态）**
+
+| 形态 | 判定 |
+| --- | --- |
+| 版本/身份 JSON | 取**新基线**侧，再改成本 fork 的版本；两侧各自新增的元数据取**并集**（依赖、files 条目、`forkedFrom` 块） |
+| 上游搬走了某个 import | 取上游的新路径，保留本 fork 的新 import |
+| 上游新环境里的注册块 | 保留本 fork 的块，放进上游的新上下文 |
+| 同一函数两边都定义（上游上移/下移了它） | 删除本 fork 那份；用 `grep -c 'const <name>'` 断言只剩 1 处 |
+| 长文档（README） | 整体取上游原文，再机械套上本 fork 的两处增量：顶部 fork notice + 包名替换（**跳过** `github.com/<上游 org>` 与徽章域名行） |
+
+**⑥ 迁移检查（API 漂移）+ 门禁**
+
+- 先**解完所有冲突标记再** `pnpm install`（`prepare: tsdown` 会因为语法错误直接失败），
+  并**删掉 lockfile 重新生成**（不要把旧 lockfile 带过来）。
+- 逐条跑 `pnpm typecheck` 修类型漂移。经验：漂移通常集中在**本 fork 自己新增的模块**里。
+  上游会在 `context-types.ts` 的注释里写清迁移路径（例：0.1.6 的 `subagentsByParent`
+  → 0.1.7 的 `projectionsBySession[id].values.subagentCatalog`，`list.current` 被删除），照注释做即可。
+- 最后跑门禁三连，并且**用 `grep` 核对关键标记**（tab id、`srcDoc`、`dsh-desktop-content-viewport` 等）。
+
+**⑦ 收尾（纪律）**
+
+- 安全锚点：`backup/pre-sync-<新基线>` 分支 + `apes-v<版本>` tag，**推送远端**。
+- **不要把新线同步进正在使用的 profile**：peer 范围可能已跨 minor，同步过去只会「静默失效」，
+  同时把本机环境弄脏。保持 profile 在已验证的线上。
+
+## 七、提交与分支纪律
+
+- 提交信息用 `type(scope): 摘要`（`feat` / `fix` / `chore` / `docs` / `refactor`），正文说明**为什么**与验证方式。
+- 一个提交一件事；re-base 类改动拆成「rename only」+「增量移植」两个提交，便于回溯与回滚。
+- 分支命名：`sync/<上游 tag>`（跟随上游）、`backup/pre-sync-<基线>`（锚点）、其余按需。
+- 提交前：门禁三连 + 关键标记 grep + （若涉及部署）提醒 profile 重装与完整重启。

docs/wiki/Home.md

@@ -0,0 +1,82 @@
+# apes-sidebar 项目百科
+
+> DeepSeek Harness（DSH）的**服务化右侧边栏工作台** + **apes 信息层**。
+> 本项目是 [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar)（MIT）的 fork，
+> 在其「文件 / 文件变动 / 任务 / 侧边对话 / 终端 / 浏览器」工作台之上，追加三个信息层标签页：
+> **智能体（agents）/ 应用（apps）/ 画像（profile）**。
+
+## 一、项目速览
+
+| 项 | 值 |
+| --- | --- |
+| 仓库 | `figmar/apes-sidebar`（公开） |
+| 默认分支 | `main` |
+| 许可证 | MIT（fork 自 `omdsh-dev/DSH-better-sidebar`） |
+| 语言 / 构建 | TypeScript（strict）· `tsdown`（rolldown）· `pnpm` |
+| 宿主 | DSH Desktop（Electron 壳）或 DSH Web profile |
+| 上游跟随方式 | 不合并上游提交，而是**测量式 re-base**（见 [07-开发与测试](07-开发与测试)） |
+
+## 二、两条版本线（重要）
+
+本仓库同时维护两条互相独立、**不能同时挂载**的版本线（两条线都注册 `ctx.betterSidebar`，
+cordis entry id 冲突，第二个会被丢弃）：
+
+| 分支 | 版本 | 上游基线 | peer / 宿主要求 | 状态 |
+| --- | --- | --- | --- | --- |
+| **`main`** | 1.2.0 | `dsh-better-sidebar` **v0.19.1**（`8753096`） | `^0.1.5-rc.1`（DSH **0.1.5-rc.1+**） | 已在本机 DSH Desktop 2.0.10（`dsh 0.1.5-rc.2`）实机运行 |
+| **`sync/v0.24.1`** | 1.3.0 | `dsh-better-sidebar` **v0.24.1**（`a2751cf`） | `^0.2.0-rc.1`（DSH **0.2.0-rc.1+**） | 构建与测试全绿，**待具备 0.2.0 宿主实机验证** |
+
+> ⚠️ **宿主的兼容性预检是「静默禁用」，不报错、不加载、无日志。**
+> 宿主用 `semver.satisfies(host, peerRange, { includePrerelease: true })` 判定；caret 范围跨 minor
+> 不成立（`^0.1.5-rc.1` 在 `0.2.0` 宿主上为 false），于是整行被跳过。
+> **现象 = 插件"好像没装"**。选线请先看宿主版本，见 [04-部署指南](04-部署指南)。
+
+## 三、文档地图
+
+| 页面 | 内容 |
+| --- | --- |
+| [01-需求分析](01-需求分析) | 背景、五条核心需求（含验收标准与状态）、非目标与约束 |
+| [02-系统架构](02-系统架构) | host/client 拆分、三层接口面、面板宿主层级契约、关键不变量 |
+| [03-功能说明](03-功能说明) | 全部标签页与预览器、信息层数据来源、i18n、主题令牌、安全边界 |
+| [04-部署指南](04-部署指南) | 环境矩阵、选线、profile 接线、构建、验收清单、卸载 |
+| [05-运维手册](05-运维手册) | 版本线与分支策略、回滚剧本、发布纪律、巡检、备份铁律 |
+| [06-故障排查](06-故障排查) | 症状 → 根因 → 处置（含全部实机验证过的案例） |
+| [07-开发与测试](07-开发与测试) | 工程约定、目录、门禁、测试体系、扩展点、上游 re-base 方法 |
+
+## 四、快速开始（TL;DR）
+
+```bash
+# 1) 构建（Node ≥ 20，pnpm）
+pnpm install && pnpm typecheck && pnpm build && pnpm test
+
+# 2) 接到 DSH profile（以桌面 profile 为例，使用 file: 链接依赖）
+#    在 ~/.dsh/profiles/desktop/package.json 中：
+#      "dsh-apes-sidebar": "file:/绝对路径/dsh-apes-sidebar"
+#    并在 dsh.profile.bundles 列表里加入 "dsh-apes-sidebar"
+
+# 3) 让 profile 重新安装依赖，然后 ⌘Q 完整退出 DSH 再启动
+```
+
+完整步骤与坑见 [04-部署指南](04-部署指南)。
+
+## 五、仓库内的事实源
+
+| 位置 | 说明 |
+| --- | --- |
+| `README.md` | 面向用户的功能与安装说明（主体沿用上游文档，顶部有 fork notice） |
+| `AGENTS.md` | 面向 agent/协作者的工程约定（构建、布局、硬性规则、测试约定）⚠️ 注意：本文件当前描述的是**另一套 from-scratch 实现**，与 `main` 的 fork 树不一致，以源码为准 |
+| `docs/external-plugin-guide.md` | 插件接入指南：`ctx.betterSidebar.registerTab / registerFileViewer` 的对外契约 |
+| `docs/plans/` | 上游历史设计文档（保持上游原样，未随 fork 改名） |
+| `docs/wiki/` | **本百科的源文件**（Gitea wiki 页面的可版本化副本，由 `scripts/push-wiki.sh` 推送） |
+| `scripts/switch.sh` | 两线切换脚本（`aps` ↔ `upstream`），含 `--status` |
+
+## 六、谱系说明（如实交代）
+
+`figmar/apes-sidebar` 这个仓库先后承载过同一产品族的三代实现：
+
+1. **v1**：早期 JS bundle 版侧边栏插件（仓库描述里提到的「可配置显示名 / 预设 feyOS」即出自那一代）；
+2. **v2**：from-scratch 重写（`src/index.ts` + `src/client/index.tsx` 结构，五个 `apes:*` tab），
+   即 `AGENTS.md` 所描述的那一套，其产物不在当前 `main` 上；
+3. **当前线（v0.19.1 / v0.24.1 fork）**：即 `main` 与 `sync/v0.24.1` 上的代码——本百科描述的对象。
+
+若需要把本百科改写成描述 v2 重写版，请告知，源文件在 `docs/wiki/` 可直接替换。

scripts/push-wiki.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# =============================================================================
+# push-wiki.sh — 把 docs/wiki/*.md 推送/更新到本仓库的 Gitea wiki
+#
+# 为什么需要它：本项目的百科源文件**版本化在仓库里**（docs/wiki/），
+# Gitea wiki 只是它的发布面。改文档 = 改仓库文件 + 跑本脚本，日志与回溯都在 git 里。
+#
+# 行为：
+#   · 幂等：页面不存在则 POST 新建，已存在则 PATCH 覆盖（标题 = 文件名去掉 .md）
+#   · 凭据来自 `git credential fill`（与推代码同一套），脚本自身不存任何 token
+#   · 凭据经临时 netrc 文件传给 curl（600 权限，退出即删），不进入 argv
+#
+# 用法：
+#   bash scripts/push-wiki.sh                 # 推送全部页面
+#   bash scripts/push-wiki.sh 05-运维手册      # 只推指定页面（按文件名/片段匹配）
+#   WIKI_REMOTE=origin bash scripts/push-wiki.sh   # 指定 remote（默认 gitea，缺失则 origin）
+# =============================================================================
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+WIKI_DIR="$ROOT/docs/wiki"
+FILTER="${1:-}"
+
+# ---- 解析 remote / owner / repo -------------------------------------------
+pick_remote() {
+  for r in "${WIKI_REMOTE:-}" gitea origin; do
+    [ -z "$r" ] && continue
+    if git remote get-url "$r" >/dev/null 2>&1; then echo "$r"; return 0; fi
+  done
+  echo "无法找到可用的 git remote（试过: ${WIKI_REMOTE:-<空>} gitea origin）" >&2
+  return 1
+}
+REMOTE="$(pick_remote)"
+URL="$(git remote get-url "$REMOTE")"
+case "$URL" in
+  https://*) ;;
+  *) echo "本脚本只支持 https remote（当前: $URL）" >&2; exit 1 ;;
+esac
+HOST="$(printf '%s' "$URL" | sed -E 's#^https://([^/]+)/.*#\1#')"
+SLUG="$(printf '%s' "$URL" | sed -E 's#^https://[^/]+/##; s#\.git$##')"
+OWNER="${SLUG%%/*}"
+REPO="${SLUG#*/}"
+API="https://$HOST/api/v1/repos/$OWNER/$REPO/wiki"
+
+echo "wiki 目标 : $OWNER/$REPO @ $HOST (remote: $REMOTE)"
+echo "源目录    : docs/wiki"
+echo
+
+# ---- 凭据 -----------------------------------------------------------------
+CRED="$(printf 'protocol=https\nhost=%s\n\n' "$HOST" | git credential fill 2>/dev/null || true)"
+USER="$(printf '%s\n' "$CRED" | sed -n 's/^username=//p')"
+PASS="$(printf '%s\n' "$CRED" | sed -n 's/^password=//p')"
+if [ -z "$PASS" ]; then
+  echo "未从 git credential helper 取到 $HOST 的凭据（先确保 git push 能成功）" >&2
+  exit 1
+fi
+NETRC="$(mktemp)"
+chmod 600 "$NETRC"
+trap 'rm -f "$NETRC"' EXIT
+printf 'machine %s\nlogin %s\npassword %s\n' "$HOST" "$USER" "$PASS" > "$NETRC"
+
+json_body() { # $1 = file
+  python3 - "$1" <<'PY'
+import base64, json, sys, pathlib
+p = pathlib.Path(sys.argv[1])
+print(json.dumps({
+    "title": p.stem,
+    "content_base64": base64.b64encode(p.read_text(encoding="utf-8").encode("utf-8")).decode("ascii"),
+}, ensure_ascii=False))
+PY
+}
+
+api() { # $1 = method, $2 = path, $3 = body(optional) -> 输出 HTTP 码
+  local method="$1" path="$2" body="${3:-}"
+  if [ -n "$body" ]; then
+    curl -s --netrc-file "$NETRC" -o /tmp/push-wiki-resp.json -w '%{http_code}' \
+      -X "$method" -H 'Content-Type: application/json' --data-binary "$body" "$API$path"
+  else
+    curl -s --netrc-file "$NETRC" -o /tmp/push-wiki-resp.json -w '%{http_code}' -X "$method" "$API$path"
+  fi
+}
+
+# ---- 逐页推送 -------------------------------------------------------------
+shopt -s nullglob
+files=("$WIKI_DIR"/*.md)
+[ ${#files[@]} -gt 0 ] || { echo "docs/wiki 下没有 .md 文件" >&2; exit 1; }
+
+ok=0; fail=0
+for f in "${files[@]}"; do
+  title="$(basename "$f" .md)"
+  if [ -n "$FILTER" ] && [[ "$title" != *"$FILTER"* ]]; then continue; fi
+  body="$(json_body "$f")"
+
+  code="$(api POST /new "$body")"
+  if [ "$code" = "201" ]; then
+    echo "  + $title  (新建)"; ok=$((ok+1)); continue
+  fi
+  enc="$(python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1], safe=""))' "$title")"
+  code="$(api PATCH "/page/$enc" "$body")"
+  if [ "$code" = "200" ]; then
+    echo "  ~ $title  (更新)"; ok=$((ok+1))
+  else
+    echo "  ! $title 失败（HTTP $code）: $(head -c 200 /tmp/push-wiki-resp.json 2>/dev/null)" >&2
+    fail=$((fail+1))
+  fi
+done
+
+echo
+echo "完成：成功 $ok 页，失败 $fail 页"
+[ "$fail" -eq 0 ] || exit 1
+echo "查看： https://$HOST/$OWNER/$REPO/wiki"