admin
e03465c398
用户令逐字：「E:/ProgramData/.workbuddy/skills 提交仓库是指的这里」—— 即本目录就是仓库（2026-10-07 已在本目录建仓，见当日日志 §22），本轮把余下未纳管的 9 个技能一并提交。 本次入库（9 个技能，46 个文件）： 1、`AI HOT` 2、`draw-ui` 3、`dsh-diagnose` 4、`dsh-knowledge` 5、`dsh-local-env` 6、`dsh-opensource-release` 7、`dsh-workflow` 8、`oil-motion` 9、`skills-security-check` 提交前核对： · **凭据类扫描**（`*.env` / `*token*` / `*.key` / `*secret*` / `*.pem`）⇒ **零命中** ✓； · 体积合计约 20 MB（`draw-ui` 12M ＋ `oil-motion` 6.5M 是大头，形态为配图/素材 —— 仓库 `.gitignore` 里明写「`assets/*.png` 是内容不是产物」⇒ 属刻意入库）； · 运行产物仍按既定规则排除（`__pycache__` / `logs/` / `tmp/` / `.venv/` / `*.egg-info` / `uv.lock` / `.workbuddy/`）。
261 lines
14 KiB
Markdown
261 lines
14 KiB
Markdown
# 过程文档与架构定稿的分层机制
|
||
|
||
> **归属**：技能 `dsh-knowledge` · 详情档（主干 `../SKILL.md`）
|
||
> **本档覆盖**：原技能 `dsh-architecture-lifecycle` **全文**（正文 164 行 ＋ frontmatter 变更历史）
|
||
> **provenance**：本机版（WorkBuddy 实况）
|
||
> **搬运方式**：**逐行未改**；内部附件链接已改写为 `dsh-architecture-lifecycle/<附件名>`（附件在本目录下）
|
||
> ⚠️ 原技能 `dsh-architecture-lifecycle` **已合并退役** ⇒ 见到该名按本档读。
|
||
|
||
---
|
||
|
||
|
||
# dsh-architecture-lifecycle — 过程 / 定稿分层机制
|
||
|
||
> **一句话**：**过程文档记录「当时怎么想的」，架构定稿声明「现在该做成什么样」**。两者混放 ⇒ 后续会话读到的是**过时结论**，而且**读全的概率趋近于零**。
|
||
> 素材来源：2026-09-21 用户三次纠正（「现在调整方案都是过程信息，后续 AI 会话找的时候可能看不全」→「过程和定稿要分开放」→「所有架构放一个文件夹，具体什么架构体现在文件名上」）。
|
||
|
||
---
|
||
|
||
## 0. 为什么需要它（用户原话 + 实测）
|
||
|
||
| 现象 | 实测 |
|
||
|---|---|
|
||
| **架构结论散落在过程档案里** | 覆盖网络顶层架构的结论分散在 **103–117 / 118–120 / 133 / 136 / 145–147 / 148 / 149 / 序③交接单**，共 **20+ 份**档案 |
|
||
| **后续会话「看不全」** | 用户原话：**「现在调整方案都是过程信息，后续 AI 会话找的时候可能看不全」** |
|
||
| **同一架构有多版口径** | 148 提出的形态被 149 **修正两处过强表述** ⇒ 只读 148 会得到**错的架构** |
|
||
| **过程档案会自然变长** | 入口文档实测 `§0 = 32%` 是累积「🆕刷新」块、`§2 = 60%` 是累积「上一轮已完成」块 ⇒ **真信号被埋** |
|
||
| **入口曾指向不存在的文件** | 某入口 `§1` 列着 **10 个文件名**，都已随「加编号前缀」改动而**改名** ⇒ 照它去找 = 找不到 |
|
||
|
||
**根因**：没有区分「**过程**」与「**成品**」。两者默认同目录、同命名、同生命周期 ⇒
|
||
**过程档案每更新一次，架构的权威表述就多一份副本**，且没有一份声明「以我为准」。
|
||
|
||
> ⚠️ 用户第一次纠正时的措辞值得记住：**「网络架构的信息应该有一份总的最终的不断迭代」**。
|
||
> 关键词是 **「一份」「总的」「最终的」「不断迭代」** ——
|
||
> **一份**（不是散在多处）· **总的**（覆盖全貌，不是单点结论）· **最终的**（成品，不是过程）· **不断迭代**（定稿本身会演进，不是冻结）。
|
||
|
||
---
|
||
|
||
## 1. 两个目录，一个判据（🔴 本技能的核心）
|
||
|
||
| | **过程目录**（本项目 = `04-调整方案/`） | **定稿目录**（本项目 = `02-架构设计/`） |
|
||
|---|---|---|
|
||
| **装什么** | 调研、推演、取证、权衡、待拍板 | 收敛后的架构设计 |
|
||
| **形态** | **逐个问题一档**，编号递增（100–150…） | **按架构成篇**，文件名＝架构名 |
|
||
| **命名** | `<NN>-<主题>.md`（编号是**过程**的标识） | `<对象>-<架构名>.md`（**⛔ 不用编号前缀**） |
|
||
| **会不会过时** | **会** —— 需求变则结论变 | **不轻易变** —— 只有架构本身变了才改 |
|
||
| **读它的目的** | 追根因、查证据、看权衡 | **照此施工 / 对外介绍 / 新人理解全局** |
|
||
| **可否删** | ⛔ 不可（是历史与判据来源） | ⛔ 不可（是当前唯一权威） |
|
||
|
||
### 1.1 唯一判据（落到每一份文件上）
|
||
|
||
> **「这份文档是在记录『我们怎么想到的』，还是在声明『现在该做成什么样』？」**
|
||
>
|
||
> 前者 ⇒ **过程目录**；后者 ⇒ **定稿目录**。
|
||
|
||
**反向判据（防误放）**：
|
||
- 含**多个候选方案 / 优缺点对比 / 未拍板项** ⇒ **过程**（还没收敛）
|
||
- 含**「倾向」「建议」「拟」** ⇒ **过程**（还没定）
|
||
- 含**`file:line` 取证** ⇒ **过程**（证据属推演过程；定稿只引结论）🔴 **例外：定稿要保留「该结论的依据在哪份档案」的回溯指针**
|
||
- 一份文档只讲**一个架构的全貌**、可直接照着施工 ⇒ **定稿**
|
||
|
||
### 1.2 冲突仲裁（🔴 必须写进两边）
|
||
|
||
> **定稿目录与过程档案冲突时，一律以定稿目录为准。**
|
||
|
||
**仲裁后要做的**：在**过程档案头部加状态块**指向定稿，⛔ **不要改过程档案正文**。
|
||
理由见 §4。
|
||
|
||
---
|
||
|
||
## 2. 定稿目录的命名约定（用户第二次纠正的落点）
|
||
|
||
> 用户原话：**「所有的架构放在一个文件夹中 方便管理，具体什么架构体现在文件名称上」**
|
||
|
||
### 2.1 铁律三条
|
||
|
||
1. 🔴 **一个目录装全部架构** —— ⛔ **不再按架构分子目录**（用户第一次我做成 `<对象>-顶层架构/` 子目录，被纠正）。
|
||
2. 🔴 **文件名 = 架构名** —— 命名 `<对象>-<架构名>.md`，**看文件名就知道该不该打开**。
|
||
3. 🔴 **⛔ 不用编号前缀** —— 编号是**过程**的标识；定稿目录内**按文件名排序**即可。
|
||
|
||
### 2.2 `<对象>` 与 `<架构名>` 各自是什么
|
||
|
||
- **对象** = 被设计的那个系统部分：`覆盖网络` / `平台` / `插件体系` / `客户端` …
|
||
- **架构名** = 这份文档讲的那个架构：`顶层架构全貌` / `多区域联邦` / `密钥与信任` …
|
||
|
||
**示例**：`覆盖网络-顶层架构全貌.md` = 讲**覆盖网络的顶层架构全貌**。
|
||
|
||
### 2.3 反例（别这样命名）
|
||
|
||
| ❌ 错 | 为什么 |
|
||
|---|---|
|
||
| `01-顶层架构全貌.md` | 编号前缀 ⇒ 与过程档案混同，且排序变成"谁先写"而非"谁是什么" |
|
||
| `覆盖网络/顶层架构全貌.md` | 按对象分子目录 ⇒ 违反「一个目录装全部」 |
|
||
| `架构.md` | 文件名没说是什么架构 ⇒ 看名字无法判断该不该打开 |
|
||
| `149-顶层架构全貌定稿.md` | 带过程档案号 ⇒ 两套编号体系打架 |
|
||
|
||
---
|
||
|
||
## 3. 收敛（过程 → 定稿）五步
|
||
|
||
> **定稿不是新写的，是从过程档案收敛而来。** 收敛 ≠ 复制粘贴，而是**判定 + 合并 + 消解冲突**。
|
||
|
||
```
|
||
① 定位 → 列出与该架构有关的所有过程档案（grep 文件名 / 关键词 / 目录）
|
||
② 判新旧 → 逐份看「谁修正了谁」；🔴 后出的档案若显式修正了先出的，以新为准
|
||
③ 合并 → 按「架构自己的结构」重组（不是按档案顺序堆叠）
|
||
④ 标回溯 → 每条结论标注来源档案号（便于日后追根因）
|
||
⑤ 标未决 → 尚未拍板的一律**显式列为待决项**，⛔ 不要悄悄写成已定
|
||
```
|
||
|
||
### 3.1 ② 判新旧是**分水岭**（实测踩过）
|
||
|
||
覆盖网络线实测：**148** 首次提出「多 Manager 多区域联邦」，**149** 又**修正了 148 的两处过强表述**。
|
||
⇒ 若只读 148 就写定稿，会把**已被推翻的表述**当成结论**固化进定稿**（更糟：定稿的权威性会让人不再回查）。
|
||
|
||
**判据**：档案头部/正文里搜 **「修正」「订正」「本节更正」「此前表述过强」** 等措辞；
|
||
有 ⇒ 它是**后出且覆盖前者**的。
|
||
|
||
### 3.2 ③ 按「架构自己的结构」重组
|
||
|
||
⛔ **不要按档案顺序堆叠**（那只是把过程搬到另一个目录）。
|
||
✅ **按架构的内在结构分节**，例如顶层架构全貌 = ①是什么 ②两张图分离 ③三层权威 ④多根与角色升格 ⑤接入路径 ⑥缺口 ⑦推进序 ⑧待决项。
|
||
|
||
### 3.3 ⑤ 未决项必须显式（🔴 红线）
|
||
|
||
**未拍板的事，在定稿里必须是「待决项」小节，⛔ 不得写成已完成的口径。**
|
||
否则后续会话会把「AI 的倾向」当成「用户已批准的决定」去施工 —— 这是**最贵的一类错误**。
|
||
|
||
**格式**：逐条编号 + 每个候选写**优点/缺点** + 写明**必须在哪个节点前拍板**（若有依赖）。
|
||
|
||
---
|
||
|
||
## 4. 过时档案的处理：只加「状态块」，⛔ 不改正文
|
||
|
||
**触发**：某份过程档案的结论**已被定稿取代**。
|
||
|
||
**做法**：在**该档案头部**插入状态块：
|
||
|
||
```markdown
|
||
> **⚠️ 本文结论已被取代** → 见 `02-架构设计/<对象>-<架构名>.md`（定稿，YYYY-MM-DD）。
|
||
> 本文保留为**过程记录**，正文不改（档案 = 当时的事实）。
|
||
```
|
||
|
||
### 4.1 为什么⛔ 不改正文
|
||
|
||
| 理由 | 说明 |
|
||
|---|---|
|
||
| **正文 = 当时的事实** | 改了就不再是「当时怎么想的」，回溯链断裂 |
|
||
| **改动会造新错误** | 事后改正文要重新推理，等于**用今天的认知重写昨天的证据** |
|
||
| **省事但危险** | 只加 3 行状态块 vs 重写全篇；后者还可能引入事实错误 |
|
||
|
||
> 与 `dsh-knowledge-upkeep` §1 铁律 2（**L5 冻结**）同源：**历史档案不回改**。
|
||
> 补充判据：**「修正」写在定稿里，「指向」写在过程档案头部** —— 两边各司其职。
|
||
|
||
### 4.2 ⛔ 不要在两处同时改
|
||
|
||
**入口文档 / 台账只允许一份**，⛔ 禁止「两处同改」的双份维护（双份必然漂移）。
|
||
发现双份 ⇒ **先合并成一份**，另一处改为**指针**。
|
||
|
||
---
|
||
|
||
## 5. 定稿的三道验收（贴出去之前过一遍）
|
||
|
||
| # | 验收项 | 判据 |
|
||
|---|---|---|
|
||
| **A** | **可独立读懂** | 只读定稿、⛔ 不点开任何过程档案，能否答出「这是什么、现在该做成什么样」 |
|
||
| **B** | **可照此施工** | 结论是否**收敛到可执行**（有对象、有动作、有边界）；仍有「倾向/建议/待定」的 ⇒ 移入待决项 |
|
||
| **C** | **可回溯** | 关键结论能否指回过程档案号；待决项是否标明**必须在哪个节点前拍板** |
|
||
|
||
⚠️ **A 不过 = 定稿变成了「过程索引」**（最常见失败模式：把所有过程摘要拼一起，读它还得读别的）。
|
||
|
||
---
|
||
|
||
## 6. 定稿目录自身的 README 必须写什么
|
||
|
||
每个定稿目录**必须有 `README.md`**，且至少含：
|
||
|
||
1. **一句话定位** —— 这个目录装什么（成品，非过程）
|
||
2. **与过程目录的分工表** —— 见 §1 那张表（可直接复制）
|
||
3. **唯一判据** —— 见 §1.1
|
||
4. **命名约定** —— 见 §2
|
||
5. **当前内容清单** —— 「文档 / 讲什么 / 定稿日期」三列
|
||
6. **来源（过程依据）** —— 列出收敛自哪些档案；🔴 写明**冲突以本目录为准**
|
||
7. **过时档案处理规则** —— 见 §4
|
||
|
||
---
|
||
|
||
## 7. 与既有技能的分工（别抢活）
|
||
|
||
| 技能 | 管什么 | 与本技能的关系 |
|
||
|---|---|---|
|
||
| **`dsh-knowledge-upkeep`** | 知识库**怎么不变错**（六层结构 / 漂移 SOP / Lint 四件套） | 本技能是它的**架构级特化**：它在 L5 只写「`04-调整方案/` 只增不改」，**未定义「定稿层」** ⇒ 本技能补上 L0.5「定稿」层与收敛流程 |
|
||
| **`session-mechanism`** | 单个决策**怎么定得对** | 本技能处理**决策沉淀为定稿**的那一段（§3） |
|
||
| **`dsh-change-workflow`** | 改造**怎么落地** | 定稿是「落地前的目标形态」；施工按 `dsh-change-workflow` |
|
||
|
||
### 7.1 给 `dsh-knowledge-upkeep` 的层表补充（建议）
|
||
|
||
原六层（L0 不变量 / L1 现行值 / L2 规则 / L3 方法 / L4 状态 / L5 历史）中，
|
||
**架构定稿**介于 L0 与 L1 之间：
|
||
|
||
| 层 | 内容 | 唯一权威 | 变更频率 |
|
||
|---|---|---|---|
|
||
| **L0.5 架构定稿** | 架构级的「现在该做成什么样」 | **`02-架构设计/`** | **中**（架构变才改） |
|
||
|
||
⇒ L0（不变量：为什么这样设计）与 L0.5（该做成什么样）的差别：
|
||
**L0 是「为什么」，L0.5 是「是什么/做什么」**；L0.5 比 L0 变得勤，比 L1（现值）稳。
|
||
|
||
---
|
||
|
||
## 8. 自检（动手前 / 收尾）
|
||
|
||
**动手前**
|
||
1. 我要写的是**过程**还是**定稿**？（§1.1 判据）
|
||
2. 若是定稿：**收敛自哪些过程档案？谁修正了谁？**（§3.1）
|
||
3. 里面有没有**未拍板**的事被我写成了已定？（§3.3 红线）
|
||
|
||
**收尾**
|
||
4. 定稿是否**只靠它自己就能读懂**？（验收 A）
|
||
5. 文件名是否符合 `<对象>-<架构名>.md`、⛔ 无编号前缀？（§2）
|
||
6. 被取代的过程档案是否加了**状态块**（而非改正文）？（§4）
|
||
7. 定稿目录 README 的**内容清单**是否登记了新文档？（§6）
|
||
8. **同一事实是否仍有第二处副本**？（§4.2）
|
||
|
||
---
|
||
|
||
## 9. 反例（2026-09-21 真实踩过）
|
||
|
||
| # | 反例 | 后果 | 规避 |
|
||
|---|---|---|---|
|
||
| 1 | 先按对象做成 `<对象>-顶层架构/` **子目录** | 被用户纠正 ⇒ 返工重排 | §2.1 铁律 1：**一个目录装全部** |
|
||
| 2 | 定稿文件叫 `01-顶层架构全貌.md` | 被用户纠正 ⇒ 编号属过程，定稿不用 | §2.1 铁律 3 |
|
||
| 3 | 差点只读 148 就写定稿 | 148 有两处已被 149 修正 ⇒ 会固化错结论 | §3.1 判新旧 |
|
||
| 4 | 过程档案里曾出现「两处同改」的双份入口 | 双份必然漂移，别的工作区会误判归属 | §4.2 入口只一份 |
|
||
| 5 | 入口文档累积历史，`§0+§2` 占 92% | 真信号被埋 ⇒ 「后续会话看不全」的直接成因 | 过程目录**也要控制累积**；历史压到归档 |
|
||
| 6 | 入口 `§1` 列了 10 个**已改名**的文件名 | 照它去找 = 找不到 | 列文件时用**可复跑**的引用（`INDEX.md` / `ls`），⛔ 不写死名单 |
|
||
|
||
---
|
||
|
||
## 10. 判据速查（一屏）
|
||
|
||
```
|
||
① 这份文档是「怎么想的」还是「该做成什么样」？ → 过程 / 定稿
|
||
② 定稿命名：<对象>-<架构名>.md，⛔ 无编号前缀，一个目录
|
||
③ 收敛五步：定位 → 判新旧 → 按架构重组 → 标回溯 → 标未决
|
||
④ 冲突：以定稿为准；过程档案只加状态块，⛔ 不改正文
|
||
⑤ 未拍板的事 ⛔ 不得写成已定 —— 必须单列待决项
|
||
⑥ 定稿验收：可独立读懂 / 可照此施工 / 可回溯
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## 变更历史（原 frontmatter · 逐字保留）
|
||
|
||
```text
|
||
name: dsh-architecture-lifecycle
|
||
description: DSH 平台「**过程文档与架构定稿的分层机制**」—— 治「架构结论散落在几十份过程档案里、后续会话找不到、同一事实多处打架」。当要**写架构级设计**、要**把推演结论定稿**、要**判断某份文档该放过程还是定稿**、要**查「现在的架构到底是什么样」**、或发现**同一架构有多处互相矛盾的表述**时使用。核心 = 两个目录的**唯一分工判据** + 定稿命名约定 + **收敛（过程→定稿）五步** + 冲突仲裁 + 过时档案的**状态块**纪律 + 定稿的三道验收。**配套：`dsh-knowledge-upkeep`（知识库怎么不变错）· `session-mechanism`（怎么定得对）· `dsh-change-workflow`（怎么落地）。**
|
||
version: 1.0.0
|
||
updated_at: 2026-09-21
|
||
agent_created: true
|
||
```
|