workbuddy_skills/dsh-knowledge/references/01-过程与定稿分层.md

过程文档与架构定稿的分层机制

归属：技能 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. 过时档案的处理：只加「状态块」，⛔ 不改正文

触发：某份过程档案的结论已被定稿取代。

做法：在该档案头部插入状态块：

> **⚠️ 本文结论已被取代** → 见 `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 · 逐字保留）

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