# 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）。