dsh_shenxian/dsh-server-docs/README.md

# dsh 多租户平台 — 改造方案文档库

> 服务器：47.77.182.89（Alibaba Cloud Linux al8）｜ 平台：dshs + dsh 0.1.2-rc.1（account 硬隔离）
> 域名：**`ai1net.com`**（门户）／**`<用户名>.ai1net.com`**（用户实例）｜ 旧域 `alotbuy.com` 自 2026-09-19 仅作 **301** 过渡装置（档案 22 / `域名迁移_ai1net_20260919`）
> 服务：systemd `dshs`（127.0.0.1:3080）｜ 现行状态与部署细节见 **`DEPLOY-本部署.md`**

> ⚠️ **两处 `docs/` 勿混**（档案 19 §C10）：
> - **本仓库**（`dsh-server-docs`）＝ **本项目改造文档**（档案 01-53、`06-ops/`、`07-scripts/`、`09-archive/`、`08-skills/`）；
> - **代码仓库**（`/opt/dshs/docs/`）＝ **上游 dshs 自带 7 篇**（blueprint / deployment / k8s-deploy …），**不要往里写我们的改造记录**。
> 构建/部署/回滚与依赖清单一律看根目录 **`DEPLOY-本部署.md`**。

## 阅读约定（先读这 7 条，避免歧义）

0. **首读 `BRIEF.md`**（现状卡）：30 秒拿到"现在是什么样、该读哪篇"；需要筛档时用 `python3 07-scripts/docs-manifest.py`（产出机读 `docs-manifest.json`）。

1. **两套编号互不相同**：根级 `01/02/03/06` 是**长期文档**（架构、运维、路线图、UI 规范）；`04-调整方案/NN-` 是**一次性改造成档案**。说"档案 NN"时**默认指后者**。
2. **单一来源**：**清单与状态 = `INDEX.md` §二**；**待办与优先级 = `01-规范/03-路线图与待办.md`**；**部署/构建/回滚 = `DEPLOY-本部署.md`**。其余文件提到这些内容时**只做指针，不复制**（历史上 README/INDEX 各存一份清单，已漂移 —— 见档案 53）。
3. **术语以档案 38b 为准**：统一称「**功能插件**」（早期档案写"业务插件"= 同一事物；历史档案保留原文，不回改）。
4. **域名以 `ai1net.com` 为准**：**2026-09-19** 由 `alotbuy.com` 迁入（档案 22 / `09-archive/域名迁移_ai1net_20260919/`）。早期档案里的 `dsh.alotbuy.com`、`alotbuy.com` 属当时事实，**保留原文**；现行入口一律 `ai1net.com`。
5. **AI 默认不读**：`09-archive/`（历史全文）、`07-scripts/` `06-ops/`（工具与配置）、`*.bak*`、`04-调整方案/poc/`（源码）—— 需要时再按需打开。
6. **档案头部格式**：`- 日期：` ＋ `- 状态：`（✅已完成 / 🔄进行中 / ⏸暂缓 / ❌关闭）＋ `- 触发：`；正文用「需求 → 改动点 → 验证」三段。

## 模块一览

| 文件 | 内容 | 用途 |
|------|------|------|
| **`BRIEF.md`** | **现状卡（AI / 人首读）**：现行事实（入口/服务/运行时/隔离/可见面/清理阈值/定时/证书/红线）+ 当前待办 top5 + 高频问题→档案映射 + **4 步读取顺序** | **先看这份**：30 秒对齐现状，再决定读哪篇 |
| `01-规范/01-规划与架构.md` | 背景/现状盘点、总体架构、目录布局、dsh 分层机制、归属矩阵、安全边界（一~五、九章）、架构切换实施记录（十三章） | 理解平台怎么搭的、为什么这样隔离 |
| `DEPLOY-本部署.md` | 本部署说明：拓扑/目录/env 键/依赖版本/脚本族/构建部署回滚三步/红线 | **重建或交接先看这份** |
| `01-规范/02-运维手册.md` | 迁移执行步骤、备份/恢复语义、多用户过渡方案、域名接入、面板反代站点、uid 排障、命令速查（六~八、十二、十四、十五章 + 附录） | **日常操作对照查**：重启/备份/看 token/改 key 流程 |
| `01-规范/03-路线图与待办.md` | 待验证项结论（Open Questions 已实测）、路线图（已完成/待办）、历史决策记录 | 追踪未完成事项与优先级 |
| **`01-规范/06-工作台UI规范.md`** | **前端 UI 强制基线**：设计 Token（色/字/圆角/阴影/间距）、布局框架与滚动规则、页面路由、组件规范（按钮/输入/表格/Tab/卡片/徽章/弹窗/Toast/空状态/分页/评分/图标）、关键交互约定、9 条已知坑与规避 | **开发/改任何前端页面前必读并遵循**（门户页 desktop/admin/08-skills/plugins + 工作台页）；权威源 `mcn-work-shop/docs/工作台UI规范.md` |
| `08-skills/dsh-workflow/` | **作业流程总入口** skill（**v1.0.0**）：**由 `dsh-change-workflow` ＋ `dsh-auto-handoff-chain` 合并**（两个原名退役）。两半：① **平台改造六阶段**（需求识别→调研→规划→开发→验证→归档）＋ **红线 R1–R11 原文速查** ＋ 并行调度协议（三把锁）② **多棒自动接力**（规划棒 ↔ 执行棒 · 六件套 prompt 骨架 · 登记门禁 · 收尾四件套 · 排期两条铁律）。**详情已拆到 `references/`（2 档 ＋ 11 个附属档）**。 | 执行平台改造 / 跑跨会话长任务时对照。⚠️ **红线以本档为准（R1–R11）** —— 只到 R8 的是 2026-09-21 之前的旧版。**同步方向：工作副本在本机 `.workbuddy/skills/`，本目录为服务器归档副本 —— 改动后单向推进来（本机 → 此处），勿反向覆盖** |
| `08-skills/dsh-decision/` | **决策总入口** skill（**v1.0.0**）：**由 `dsh-decision-method` ＋ `dsh-feature-first` 合并**（两个原名退役）。两半：① **决策方法论**（判定矩阵 · 「确认最优解」十问 · **验收口径分级 L1–L5** · 技术选型先立判据轴）② **功能优先协作协议**（功能卡 4 问 · **9 类自决白名单`永不问`** · **只准上抛的 3 类** · 上抛语言转换表）。**详情已拆到 `references/`（2 档 ＋ 3 个素材库）**。 | ⛔ **用户点名「决策方法 / 按你的规划 / 别问我 / 自行决策」时必须加载**；管「怎么想、怎么定」，落地 ⇒ `dsh-workflow`。**同步方向：工作副本在本机 `.workbuddy/skills/`，本目录为服务器归档副本（本机 → 此处，勿反向覆盖）** |
| `08-skills/dsh-knowledge/` | **项目知识与架构资产维护** skill（**v1.0.0**）：**由 `dsh-knowledge-upkeep` ＋ `dsh-architecture-lifecycle` 合并**（两个原名退役）。两半：① **知识库维护与纠偏**（六层结构 L0–L5 ＋ **分层判据「实体 vs 指针」** ＋ Lint 四件套 ＋ 漂移 SOP ＋ **§9 技能集体检 10 层** ＋ **§10 技能重组：主干 + `references/`**）② **过程/定稿分层机制**（两个目录的唯一分工判据 ＋ 定稿命名 ＋ 收敛五步 ＋ 冲突仲裁「以定稿为准」＋ 过时档案只加状态块）。**详情已拆到 `references/`（2 档 ＋ 2 个附属档）**。 | 文档与现状不符 / 事实打架 / 定期体检 / 要定稿架构级结论时用。**同步方向：工作副本在本机 `.workbuddy/skills/`，本目录为服务器归档副本（本机 → 此处，勿反向覆盖）** |
| `08-skills/agent-operating-rules/` | **AI 会话作业总规矩** skill（**v1.0.0**）：跨工作区通用的会话级规则集 —— 上抛唯一判据（边界内自决 / 边界外八类）、**回复排版契约**（结论先行 · 层级 ≤3 · 每节 ≤7 行 · 待拍板项落最后一节且候选竖排成段）、**§2.5 去 AI 味**（说话要像人，含语言组织与排版）、工作区归属三律、一把锁纪律、落位·提交·批量红线、交付门禁、多棒自动接力、环境陷阱速查、**§10.1 技能要不要合并的判据**、**§10.2 机制扩面后必须清退绕行方案**；重内容已拆到 `references/`（01 协作与上抛判据 / 02 工作区纪律 / 03 多棒接力编排 / 04 去AI味与说话方式） | **任何工作区开工前加载**：管「怎么想、怎么说、怎么不越界」，与 `dsh-change-workflow`（怎么落地）、`dsh-decision-method`（怎么定案）分工互补。**⛔ 本技能零硬编码路径，加载后不读取任何具体工作区文档 ⇒ 不影响其他工作区**。**同步方向同上（本机 → 此处，勿反向覆盖）** |
| `08-skills/dsh-local-env/` | **本机 dsh 环境总入口** skill（**v1.0.0**）：**由 `dsh-desktop-dev-shell` ＋ `dsh-env-bootstrap` 合并**（两个原名退役）。两半：① **在 Windows 本机跑起官方 dsh 并取证**（web 实例 / 桌面壳两形态 · Node 22 · **「监听 ≠ 就绪」** · **判据写窄＝假红** · CDP 真跑 · 离线可用验证）② **环境引导 / 搬迁 / 改名后的路径残留清理**（换环境先保「规则齐备」· **分类要细到「行」**· 权威单向）。**详情已拆到 `references/`（2 档 ＋ 2 个附属档）**。 | ⚠️ **边界**：本技能管**本机**；服务器上的实例与插件 ⇒ `dsh-diagnose`。**同步方向：工作副本在本机 `.workbuddy/skills/`，本目录为服务器归档副本（本机 → 此处，勿反向覆盖）** |
| `08-skills/dsh-diagnose/` | **平台故障诊断总入口** skill（**v1.0.0**）：**由三者合并**（`dsh-instance-diagnose` ＋ `dsh-plugin-diagnose` ＋ `dsh-distributed-state-readback`，三个原名**已退役**）。按症状分三层：① **服务器实例**（打不开 / 起不来 / 挂了 / 一直重启 / 503·502 / 内存不够）② **业务插件**（没 UI / 装了界面没变化 / GLIBC / 改了还是老行为）③ **跨机状态回流**（某字段跨机恒为 false / 状态回不来）。各层第一原则：实例＝**先读 journal 再分服务/实例/会话三级**；插件＝**静默失败当默认假设**；跨机＝**先判「缺失能力 vs 代码缺陷」**。判据实体留在主干，**全文已下沉 `references/`**（00 服务器实例故障 / 01 业务插件故障 / 02 跨机状态回流，共 3 档）。 | ⚠️ **与 `dsh-desktop-dev-shell` 的边界**：本技能管**服务器上的实例与插件**；「**本机** Windows 上把官方 dsh 跑起来」属对方。**同步方向同上（本机 → 此处，勿反向覆盖）** |
| `08-skills/dsh-opensource-release/` | **开源导出与版本迭代** skill（**v1.0.0**）：把私有代码仓导出成可公开的开源副本 —— **脱敏**（含"曾用名必须在 `LEAK_PROBES` 里"的教训：探针只探最老名字会漏中间名）+ **去插件 / 分层授权**（`LICENSE` 原样 ＋ `COMMERCIAL-LICENSE.{md,zh-CN.md}` 两条平行许可各自成文件，⛔ 不给 AGPL/MIT 附加限制）+ **重写说明文档** + 按 commit 取树避免混入并行会话未提交的改动 + 发布前阻断性探针 + **重内容已拆到 `references/`**（01 保留移除与脱敏口径 / 02 多远端推送 / 03 实测坑 / 04 交互式图示-archify / 05 已知待办与漂移，共 5 档）。 | **说「开源一份」「导出到 GitHub / CNB」「发新版本」「开源那份同步一下」时用**。⚠️ 唯一例外：`dsh-univer-office` 经特许保留原名。**同步方向同上（本机 → 此处，勿反向覆盖）** |
| `交接单/` | **规划会话 → 执行会话的任务单**（目标 / 只读前置 / 范围 / 决策点 / 步骤 / 验收 / 回滚 / 回报格式）+ 交接约定 | **要执行某个任务时才读**；单子完成后移入 `交接单/` |
| `04-调整方案/` | 每个功能改造一份档案：需求 → 改动文件 → commit → 验证结果 | **核对用**：某功能当时怎么改的 |
| `02-架构设计/` | **已定稿的架构设计**（一个目录装全部架构，文件名＝架构名）：当前 = `覆盖网络-顶层架构全貌.md`（两图分离 · 三层权威 · 多根与角色升格 · 缺口与推进序）。**与 `04-调整方案/` 的分工 = 过程 vs 成品**：那目录答「为什么这么做」（调研/推演/取证/权衡，会过时），本目录答「现在该做成什么样」（收敛后可施工，不轻易变）；**两者冲突以本目录为准** | **想施工 / 想理解全局时读这份**；`04-调整方案/` 只用来追根因与看证据 |
| `09-archive/` | `dsh-improvement-plan-20260909-full.md`：拆分前的 19 章完整时间线归档 | 保留历史全文，防拆分遗漏 |

`04-调整方案/` 档案清单：

| 档案 | 对应章节 | commit |
|------|---------|--------|
| `01-launch-token自动携带.md` | 十六 | 29c8907 |
| `02-安全加固-权限边界与DB.md` | 十七 | —（chmod 操作） |
| `03-统一KEY管理员管控.md` | 十八 | df5cc84 |
| `04-删除用户功能.md` | 十九 | 4943c8c |
| `06-登录直达会话窗口.md` | —（方案 A 第一步落地，v1+v2） | 6f63108 + e39628a |
| `07-红线-禁止dsh自动获取最新版本.md` | —（红线+升级流程） | 生效 |
| `08-实例常驻上限与单活跃会话.md` | —（回收+last-wins 落地） | 928dde1 + 6336c53 |
| `09-普通用户隐藏模型设置-角色化profile-patch.md` | —（cordis patch disable 裁剪 client 插件，`ensure-role-profile-patch.cjs`） | —（工具脚本，2026-09-09 落地） |
| `10-共享技能只读部署-bundledSkillDir.md` | —（调研分析 + 实施：编排器 env 注入 + 共享只读目录，dsh 全员可见只读技能层） | —（已实施 2026-09-09；管理面见 11） |
| `11-技能管理面-shared+mine-API与页面.md` | —（管理面：编排器新增 `/api/08-skills/{shared,mine}` + `/skills.html`；**v2 = zip-only 两阶段替换**：上传检测→同名提示确认→apply 全量替换） | —（已实施 2026-09-09，v2 同日） |
| `12-VoxEMW全云API化接入dsh-调研与M1落地.md` | —（外部产品插件化调研 + 云 API 方案：VoxEMW 魔镜 → dsh-plugin-voxemw-cloud） | —（本地插件 v0.1.0 已实现，2026-09-10；云端链路待接线验证） |
| `13-登录直达冷启动竞态404修复.md` | —（登录直达冷启动竞态：enter 等 launch token 到位再返回 URL） | fa718d2 |
| `14-实例会话敏感信息暴露面审计与加固.md` | —（读取→留存→外传链路审计；uid 段收敛 [100000,199999] + nftables 出网护栏封元数据端点/观测外联） | —（已上线 2026-09-10，`dsh-egress.service` enabled+active） |
| `15-会话失效401未跳登录页修复与guest可见面复核.md` | —（三页注入 401 守卫跳 `/login.html`；核心插件开关收归 admin；guest 可见面复核） | —（已上线 2026-09-10） |
| `16-页面导航定稿-技能插件管理面三决策落地.md` | —（已封板：skills.html 两 tab 管公共面 + 插件三层归属模型 + folder_plugins 已废弃；分阶段实施） | 🔄 实施中 |
| `17-工作区选择器暴露面核查.md` | —（会话内「添加工作区」为何能看到 `/`：bwrap 合成根还原 + 实测可读/可写/跨租户边界；判定 P1 写边界随会话 cwd、P2 picker 无根白名单与 /etc/passwd 泄露；收敛项 H1-H4） | 核查完成，收敛待确认 |
| `18-目录选择器收敛为仅见自有目录.md` | —（**已定稿**：自建 host 插件子类化 `DirectoryPicker` seam，根固定 `<userRoot>/ws`，含 admin；改走 **bundle 路由**不动用户 patch；**PoC 26/26 通过**；P0-1/P0-3 待装包重启） | 已定稿，待装包重启 |
| `19-方案与代码全面审查.md` | —（代码 10 项 + 文档 8 项体检：patch 多 owner 冲突 / 含 admin 注入缺口 / 测试缺口 / 01-02-03 滞后 / 2 组重复文件；含优先级批次与决策点） | 审查完成，整改待启动 |
| `20-崩溃自愈现状核实与加固方案.md` | —（订正档案19 §C4：自愈**已在**（`scheduleRestart` 1s 退避）；真缺口=重试无上限/无观测/handoff 悬空；方案 A 加固+观测+handoff 决策，**不建议**启用 enablePatch） | 方案A（熔断+观测）+ handoff 停写 **已实施**；待 live 实测 |
| `21-guest会话卡顿排查.md` | —（服务端全链路取证：TTFT 1.0–3.5s、实例 TTFB 2ms、nginx 全 <5s、0 崩溃；体感来自客户端侧 + 两个干扰项：生产启用 HMR 每 65s 连 /plugins/events、无关域名流量误入编排器） | 排查完成，待拍板 A1/A2 |
| `22-服务域名迁移到alotbuy.com.md` | —（走 CF 代理切换服务域名：门户 alotbuy.com + 用户 `<用户名>.alotbuy.com`；签通配证书、CF 真实 IP 还原、旧域名 301 含用户名映射；含 4 个踩坑与回滚） | ✅ 已上线 |
| `23-实例内AI能力与权限限制核查.md` | —（guest 报的 9 条环境限制逐条判定：**1 条 P1 真 bug**——合成根缺 /bin /sbin /lib 致 dsh 沙箱探针失败 → bash 工具被整体拒绝，已修复待重启；3 条可优化（ffmpeg/python/rg/jq/浏览器）；4 条设计使然；1 条与平台无关） | 修复已编译，待重启生效 |
| `24-实例侧401自动恢复.md` | —（实例重启后旧标签页 token 失效 → dsh 报 `dsh web authentication required` 死端页；代理补上「实例侧 401 + 浏览器导航 → 302 带最新 token 原地恢复」；与档案 23 沙箱修复同批重启上线） | ✅ 已上线 |
| `25-实例崩溃循环修复与not_running兜底.md` | —（**自造事故修复**：插件包内 patch 与 profile 层重复 insert 同一 loader id → `duplicate loader entry id` → 实例崩溃循环（被档案 20 熔断拦住）→ 用户看到裸 `{"error":"not_running"}`。修：包内改空补丁单点插入 + 浏览器导航永不吐 JSON + 并发进场等待在飞实例 token） | ✅ 已修复上线 |
| `26-dsh升级耦合点与回归清单.md` | —（回答"是否影响官方包/升级会不会覆盖"：**官方包零改动**（实测无痕迹/无新 mtime）；升级不覆盖我们的改动，但有 **6 类契约耦合点**需回归：profile 引用的官方 client 行 id、自建插件继承的 seam 基类、client bundle 契约、bwrap 合成根、proxy 401/not_running 假设等） | 清单建立 |
| `27-MCN工作台插件平台化评估.md` | —（MCN 工作台插件能否作为功能插件投放/多用户/存储/自带 DB 风险/技能整合 vs 外置：**可行但 3 处 P0 必改**（DSH_HOME 路径、技能路径硬编码 13 处、agent preset 随包投放）；技能结论=**外置**） | 评估完成，改造待启动 |
| `28-用户数据清理策略.md` | —（ws 三档清理（T1 平台产物 / T2 超 90 天顶层脚本 / T3 永不删）+ 会话阈值回收 + 回收站 30 天 + cron；含平台自身污染 bug 的发现与修复） | ✅ 已上线 |

- **单一来源约定（2026-09-11 订正，档案 53）**：档案**清单与状态**的单一来源是 **`INDEX.md` §二**；本文件的档案表**仅作拆分前（01–26）的历史对照，不再新增行**。`04-调整方案/README.md` 为指针式说明。（此前本文件与 INDEX 各维护一份全量清单 → 已实际漂移，故订正。）

## 红线（硬性，全部档案同遵守）

1. **禁止启动 dsh 时自动获取最新版本**；dsh 版本升级必须先走独立"升级测试→评估→修复"流程再整体更新（详见档案 07）。
2. **不改官方 dsh 主程序与缓存**（/usr/local/lib/node_modules/@deepseek-ai/dsh 及依赖）；扩展只走 profile 层官方插件机制（档案 05）。
3. 服务器 docs 只读归档（root 600）；技能同步类红线见各技能 MEMORY 约定。
4. **禁止未经确认的批量 / 全仓写入**（2026-09-12 新增，见 R7）：不得对仓库或生产目录做**全库遍历改写、通配符重写、批量 `chmod`/`chown`、批量换行符转换、`cp -r` 整目录覆盖**；**任何可能影响 >10 个文件的操作用前必须先出受影响清单并取得确认**。执行过程中发现的**额外问题一律"先报告、后动手"**，不得顺手改 —— **本机镜像不是沙箱**，本机批量改动会经 scp 传导到生产。
5. **中断在线用户的生产变更须先确认**（2026-09-12 新增，见 R8）：重启 `dshs`、drain 实例 scope、批量铺插件、改 `MemoryMax`/实例 env 等，都会让在线用户掉线；执行前必须先说明「**影响谁、断多久**」并取得确认，能避开用户活跃时段就避开。

`04-调整方案/poc/`：PoC 插件源码档案（`portal-entry/` = `@dsh-local/portal-entry` v0.4.3，含 package.json / cordis.patch.yml / lib/{index,client}.js；版本演进：v0.1.0→v0.1.1 行级 `inject:[tools]`（host 面）、v0.2.0 client 面 `exports["./client"]` + `dsh.client.platform=web`、v0.3.0 bundle 内 `exports.inject=["slots"]`、v0.3.1 package.json `dsh.client.inject=["@deepseek-ai/dsh-client-ui-sidebar"]`、v0.3.2 list-slot register `id`+callback 形式、v0.4.0 footer.action 废弃改 `settings.section`（id:"platform"，与通用设置/模型/插件/Agent预设 同槽）、v0.4.1 删 `exports.default`（loader ESM interop 取函数 → 无 inject → settings.section 注册失败，浏览器实测根因，**红线 3**）+ `label` 函数形式、**v0.4.2 尝试 var() fallback 失败**（深色主题下 `--dsw-alias-label-primary`/`--dsw-alias-button-elevated-fill` 都已定义 `#f9fafb`，fallback 永不生效，文字/背景同浅色不可见）、**v0.4.3 hardcode 修复**（文本 `#f9fafb`、按钮边框 `#43464d`、打开管理台 `#4f6ef7` 蓝底白字、退出登录 `#ff4d4f` 红字透明底；浏览器验收白字蓝底清晰可见——但**部署后首次仍见旧 bundle**，根因=实例 pid 147068 16:32 启动 vs tgz 16:40 部署**未重启**，dsh client bundle 在实例启动时打包缓存；重启走编排器 `POST /api/dsh/restart`（主域 Host+admin sid），新实例 port 37817→45543，bundle rev `259e7a43027c→936d9012841a`）；服务器同步副本在 `/opt/dsh/docs/04-调整方案/poc/`）。

## 使用约定

- **新增改造**：按主题写进对应文件；功能类改造在 `04-调整方案/` 新建档案（编号递增，**复跑取号勿写死**：`ls 04-调整方案/ | sort -n | tail -1`；**63 为空号，勿补占**），模板 = 需求 → 改动点表 → 验证结果。
- **01-规范/基线类**（跨页面长期生效）→ 根级编号文档（`01-规范/06-工作台UI规范.md`），**不入 `04-调整方案/`**。
- **工作区根批量入仓（2026-09-17）**：工作区根尚未入仓的项目文档已一次性归位 —— 16 份方案 / 评估 / 复盘 / 规范类 → `04-调整方案/113–128`；13 份交接单 → `交接单/T09–T21`；运行态指针（`接续入口_*` / `接续包_*`）→ 当时入 `06-ops/`（**2026-09-23 再归置**：两份覆盖网络接续件 ＋ 域名迁移目录 → `09-archive/`）；临时与内部简报 → `09-archive/`。**档案清单仍以 `INDEX.md` §二 为单一来源**（本文件的 01–26 表按上条约定不新增行）。
- **前端页面改动**：先读 `01-规范/06-工作台UI规范.md` 再动手；视觉判断辅以 `.workbuddy/08-skills/impeccable`（Operate 模式）与 `taste-skill`（反 AI 味），**冲突时以 `06` 的实测 Token 为准**。
- **排障**：追加进 `01-规范/02-运维手册.md` 排障小节。
- **自查**：归档/改动文档后跑一次 `python3 07-scripts/docs-audit.py`（歧义/悬空引用）与 `07-scripts/docs-manifest.py`（刷新机读清单）（编号冲突 / 标题号不符 / 悬空引用 / 重复 / 体量）——**编号冲突与悬空引用会让它退出码非 0**。
- **保留原章节编号**（如"十六、"）：方便与 archive 完整版对查。
- **同步**：本机 `D:\github\dsh_shenxian\dsh-server-docs\` ↔ 服务器 `/opt/dsh/docs/` 整目录镜像，改完即 scp（服务器侧档案 `chmod 600` 保持 root-only，README 保持 644）。
- **对账**：`bash 07-scripts/docs-sync-check.sh`（工作区 `07-scripts/`，2026-09-10 落地）一条命令输出「一致 / 内容不一致 / 仅本地待推送 / 仅服务器待拉取」，退出码 0=全绿；加 `--push` 一键推送本机变更（档案 600 / README 644 自动设权）。
- **定位**：先查 `INDEX.md` 的场景速查表（编号规则见「阅读约定」第 1 条）。

## 目录内其他文件（服务器侧）

- `nginx-dsh.alotbuy.com.conf.bak-20260908` / `.manual-20260908`：面板注册前的手写反代配置备份。
- `dshs.db.bak-20260908-uidfix`：uid 错配修复前的数据库备份（正式备份见 `/opt/dsh/backups/`）。