65 lines
5.0 KiB
Markdown
65 lines
5.0 KiB
Markdown
|
# dsh-server-docs 归类现状与方案（2026-09-23）
|
|||
|
|
|
|||
|
|
> **工作区**：`E:\ProgramData\AI技能\aliyun-dsh-server`（插件投放与分库线）
|
|||
|
|
> **性质**：**现状台账 ＋ 归类方案**。本轮已执行「零风险归置」3 件；结构性大搬动**留待拍板**（原因见 §三）。
|
|||
|
|
> **取证**：全量结构见 `tmp/_docs_inventory.txt`（本工作区）；引用面 = 整仓对 `dsh-server-docs/<顶层项>` 的路径引用计数。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §一 结论先说
|
|||
|
|
|
|||
|
|
**文档库其实已经是「按用途分类」的结构** —— 10 个目录各司其职（见下表），根级只留「编号规范件 ＋ 入口/索引件 ＋ 生成物」。
|
|||
|
|
⇒ 真正的"未归类项"只有 **1 个单文件目录** ＋ **1 个临时残渣**，本轮已清；剩下的一件事属**别人的线**，已报告未动。
|
|||
|
|
|
|||
|
|
## §二 现状（现读）
|
|||
|
|
|
|||
|
|
| 目录 | 用途 | 文件数 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `04-调整方案/` | **过程档案**（每项改造一份，编号） | 156 |
|
|||
|
|
| `交接单/` | 执行台账（已规划待执行 ＋ 各线单） | 38 |
|
|||
|
|
| `skills/` | 平台技能包（含 `references/`） | 38 |
|
|||
|
|
| `scripts/` | 文档库工具脚本（探针 / 对账 / 分析） | 27 |
|
|||
|
|
| `archive/` | 存档区（已完成单 / 旧方案 / 简报） | 13 |
|
|||
|
|
| `ops/` | 运维物料（nginx / scripts / 域名迁移 / 覆盖网络接续件） | 6 |
|
|||
|
|
| `数据库/` | 数据面规范 `DB-00`–`DB-03` | 4 |
|
|||
|
|
| `架构设计/` | **定稿**架构（分库 / 覆盖网络全貌） | 3 |
|
|||
|
|
| `tmp/` | 临时区（当前为空） | 0 |
|
|||
|
|
| ~~`docs/`~~ | 原单文件目录 ⇒ **本轮已归并撤销** | 0 |
|
|||
|
|
| **根级编号规范件** | `01-规划与架构` `02-运维手册` `03-路线图与待办` `06-工作台UI规范` `07-实例UI分区登记表` `08-插件开发与对接规范` `09-IM插件SDK与扩展点契约` | 7 |
|
|||
|
|
| **根级入口/索引件** | `README`（总入口）`INDEX`（场景索引）`BRIEF`（现行事实）`CODEBUDDY`（项目指令）`DEPLOY-本部署` | 5 |
|
|||
|
|
| **根级生成物 / 配置** | `docs-manifest.json` `archive-summaries.json` ＋ `.gitignore` `.gitattributes` | 4 |
|
|||
|
|
|
|||
|
|
## §三 本轮已执行（3 件 · 均先备份、可回滚）
|
|||
|
|
|
|||
|
|
| # | 动作 | 风险 | 依据 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 1 | **删** `.domains.tmp.1639`（29 B，锁机制中断残渣） | 0（备份在 `归档/dsh-server-docs-整理-20260923/`） | 内容 = 临时域列表，无引用方 |
|
|||
|
|
| 2 | **`docs/IM插件SDK与扩展点契约.md` → 根级 `09-IM插件SDK与扩展点契约.md`**（与 06/07/08 同族），并删空的 `docs/` | 低 | 单文件目录 = 未归类；提为编号件后与其他规范件同层 |
|
|||
|
|
| 3 | **同步改指针 2 处**（`交接单/IM群组-D-插件SDK与扩展点契约.md` 第 221 / 309 行）＋ `INDEX.md` 加一行 09 的索引 | 低 | 移动必然断引用 ⇒ 跟随动作的必要修正（该文件只被这一处引用） |
|
|||
|
|
|
|||
|
|
**回滚**：`归档/dsh-server-docs-整理-20260923/` 内有原文件与残渣副本；路径改动为 1 个文件，反向 `mv` ＋ 撤销上面 2 处指针即可。
|
|||
|
|
|
|||
|
|
## §四 ⏸ 报告未动（1 件 · 属别的线）
|
|||
|
|
|
|||
|
|
`ops/接续入口_覆盖网络线_20260916.md` ＋ `ops/接续包_覆盖网络线_20260916.md` —— 与**工作区根**的权威入口**同名**。按「入口只允许一份」的归属律，`ops/` 里这两份属**外来副本**（会误导读者以为入口在这）。
|
|||
|
|
**未动的原因**：它们是**覆盖网络线**的资产 ⇒ 归置（移 `archive/` 或删）应由该线决定；本线只登记。
|
|||
|
|
|
|||
|
|
## §五 待拍板：根级那 12 个文件要不要收进子目录（真取舍）
|
|||
|
|
|
|||
|
|
**A 维持现状（本轮做法 · 倾向）**
|
|||
|
|
优点：零引用断裂 —— `CODEBUDDY.md`（每会话自动加载的项目指令）里写的是 `dsh-server-docs/06-工作台UI规范.md` 这类绝对路径，`INDEX` / 各档案 / 技能 / 脚本另有 26+10+8 处路径引用；根级"编号件 ＋ 入口件"本身就是文档库的既有约定（`01/02/03` 从第一天就在根）。
|
|||
|
|
缺点：物理上根目录仍有一排 `.md`，"看起来"不够分层。
|
|||
|
|
|
|||
|
|
**B 全量分层（新建 `规范/`、`入口/`、`生成物/` 再搬）**
|
|||
|
|
优点：根目录只剩目录，视觉最整齐。
|
|||
|
|
缺点：**必须同步改 `CODEBUDDY.md` 并重启会话才生效**（改错会污染此后所有会话的规则加载）＋ `INDEX` ＋ 26/10/8 处路径引用逐一核对 ＋ 服务器端 `skills/` 副本要重推 ⇒ 回归面远大于收益，且"编号件在根"是既有约定、并非缺陷。
|
|||
|
|
|
|||
|
|
**C 只加导航层（可选增量）**
|
|||
|
|
优点：零移动、当场见效 —— 在 `README` 顶部补一张「用途 → 目录」总表（`INDEX` 已有场景表，可再抽象一层）。
|
|||
|
|
缺点：不改物理布局，解决不了"想看到文件夹"的观感。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §六 附：若要继续清理文档库
|
|||
|
|
|
|||
|
|
`dsh-server-docs/tmp/` 当前为空（无需处理）；`04-调整方案/` 里 09 月中旬以前的过程档案若要归档，须走「过程 ≠ 成品」的既有机制（`架构设计/` 为准，过程档案**不改正文**、只加头部状态块）——属专项，不属本次归类。
|