admin
5ad755116e
1) dsh-server-docs/ 从工作区（原 E:\...\aliyun-dsh-server\dsh-server-docs）**整体并入本仓**，
保留目录名 ⇒ 仓库内 dsh-server-docs/... 的相对引用天然继续有效；旧目录（含其 .git）已归档到
工作区 _中间产物_待清理/，未随本提交带入。
2) .gitattributes：新增 `dsh-server-docs/** -text` —— 原文档库是 `* -text` + autocrlf=false，
必须保持纯 LF，否则会被本仓的 CRLF 规则翻掉。
3) 活引用里的绝对路径已全部改到新位置（docs 的 INDEX / README / scripts / skills + 用户级 skills
+ ~/.workbuddy/settings.json 的 hooks）；历史档案（04-调整方案/、archive/）按「只增不改」未动。
⚠️ hooks 路径改动需「完全重启会话」才生效（配置是会话启动快照）。
4) 交接单/T08：新增 §16「生产整体切换执行记录」（形态 / 落地动作 / **4 个只有真上线才暴露的真 bug** /
验收证据 / 回滚命令 / 残留项）；台账 T08 行 → 已完成并归档；03-路线图 §二 登记 T08 收尾项。
5) 统一称谓：**「本机」只指跑 WorkBuddy 的开发机**，47 / 106 一律写「远程服务器」。
134 lines
8.1 KiB
Markdown
134 lines
8.1 KiB
Markdown
---
|
||
name: dsh-knowledge-upkeep
|
||
description: dsh 平台文档库 / 项目知识的**维护与纠偏方法**。当发现「文档与现状不符」「同一事实多处打架」「知识越积越碎」「AI 忘了某条规则」「要收敛或重构知识库结构」时使用；也用于定期体检。核心 = 六层知识结构（L0-L5）+ **分层判据（实体 vs 指针）** + Lint 四件套 + **漂移处理 SOP** + **自动化的边界（检测可自动，改写不可自动）** + 今天踩过的 5 个反例。**配套：`dsh-feature-first`（谁定什么）· `dsh-decision-method`（怎么定得对）· `dsh-change-workflow`（怎么落地）。**
|
||
version: 1.0.0
|
||
updated_at: 2026-09-12
|
||
agent_created: true
|
||
---
|
||
|
||
# dsh-knowledge-upkeep — 知识库维护方法
|
||
|
||
> **一句话**：知识库不会自己变好，**只会慢慢变错**。本技能把"纠错"从临时动作变成**可复跑的方法**。
|
||
> 素材来源：2026-09-12 全库校验实证（20 项违背 → 0）。
|
||
|
||
---
|
||
|
||
## 0. 为什么需要它（实证，不是理论）
|
||
|
||
| 现象 | 实测 |
|
||
|---|---|
|
||
| **同一事实被抄很多份** | 现行域名出现在 **21 个文件 / 123 处**；档案"下一号"写在 4 处且**互相打架**（72 / 69 / 53 / 20） |
|
||
| **过时值长期存活** | 旧配额活在 15 个文件；实例 MemoryMax 曾同时存在两个"现役值" |
|
||
| **权威源头本身是错的** | `BRIEF.md`（首读现状卡）自己带着旧值 → AI 老老实实读了它，读到就是错的 |
|
||
| **校验工具查不到** | 原 `docs-audit.py` 只查**结构**（编号/悬空/重复），**不查事实** → 漂移不可见 |
|
||
| **规模已超"全量塞入"上限** | 库 = 93 md / 555,533 字符 ≈ **388,873 tokens**；Karpathy 模式实证 **~100 篇就崩**（模型开始略读并给出自信的错误答案）|
|
||
|
||
---
|
||
|
||
## 1. 知识结构：六层 + 单一来源
|
||
|
||
| 层 | 内容 | 唯一权威 | 变更频率 | 送达方式 |
|
||
|---|---|---|---|---|
|
||
| **L0 不变量** | 架构与机制（为什么这样设计） | `01-规划与架构` + 早期档案 | 年 | 按需 |
|
||
| **L1 现行值** | 现在到底是什么（域名/配额/端口/路径/阈值） | **`BRIEF.md`** | 周 | 首读 |
|
||
| **L2 规则** | 必须遵守（提问判据/红线/提交边界） | **`CODEBUDDY.md`** | 很少 | **自动注入** |
|
||
| **L3 方法** | 怎么想、怎么做 | 3 个 dsh 技能 | 月 | 按需触发 |
|
||
| **L4 状态** | 现在在哪（待办、落差） | `交接单/` + `.workbuddy/memory/MEMORY.md` | 天 | **自动注入** |
|
||
| **L5 历史** | 怎么变成现在这样 | `04-调整方案/` + `archive/` | **只增不改** | 按需 |
|
||
|
||
**三条铁律**
|
||
1. **每个事实只有一个权威** —— 其余文件**只许写指针，不许复制数字**。
|
||
2. **L5 冻结** —— 历史档案里的旧值**不回改**（写的时候是对的，回改破坏历史）；需要修正时**在文末追加「修正（YYYY-MM-DD）」小节**，并改 L1 的现值。
|
||
3. **校验必须能查"事实一致性"** —— 否则前两条必然失守。
|
||
|
||
---
|
||
|
||
## 2. 分层判据：**什么必须实体，什么可以只给指针**
|
||
|
||
> **"不做会违规、会出事"的 → 实体保留；"看了更准但不看也不违规"的 → 才给指针。**
|
||
|
||
| 处理 | 内容 |
|
||
|---|---|
|
||
| **实体保留**（压缩不许删语义） | 提问判据 · 红线 R1–R8 · 提交边界 · 规划/执行分离 · 并发纪律 · **会导致事故的实测事实** · 环境要点 |
|
||
| **只给指针** | 平台现状与历史细节 · UI 规范全文 · 档案模板细则 · 某功能的实现内幕 |
|
||
|
||
⚠️ **指针必须绑定可识别的动作**，否则"去查"不会发生：
|
||
`当你要写前端页面 → 先读 06-UI规范`，而不是 `详见 06-UI规范`。
|
||
|
||
---
|
||
|
||
## 3. Lint 四件套（可复跑，退出码可接 CI）
|
||
|
||
```bash
|
||
python3 scripts/docs-audit.py # 结构：编号冲突 / 标题号不符 / 悬空引用
|
||
python3 scripts/docs-manifest.py # 刷新机读清单 docs-manifest.json（含被引次数/tier）
|
||
bash scripts/docs-sync-check.sh # 双端对账（本机 ↔ /opt/dsh/docs）
|
||
python3 scripts/docs-consistency.py # 事实：写死取值 + 跨页取值冲突
|
||
```
|
||
|
||
**`docs-consistency.py` 的设计要点**（写它时踩过的坑，别重踩）：
|
||
- 只查**高置信**模式。首版把「旧域名」「旧配额」当违规 → **几乎全是误报**（库里都是"旧域已 301" / "512M→384M" 的合法表述）。
|
||
- **引号感知**：引号内的匹配 = **引用历史**，不是断言，不算违规。
|
||
- 判据 = 「**承诺现行**的文件不许含已废止/写死/矛盾的取值」；
|
||
**历史豁免**：`04-调整方案/**`、`archive/**`、`01-规划与架构`、`02-运维手册`。
|
||
|
||
---
|
||
|
||
## 4. 漂移处理 SOP（发现 → 收敛，五步）
|
||
|
||
```
|
||
① 发现 → 四件套任一项退出码非 0
|
||
② 定性 → 真漂移 / 合法历史表述 / 校验器误报 ← **这一步不能跳**
|
||
③ 定权威 → 这个事实的**唯一权威**是哪一层哪个文件（见 §1）
|
||
④ 收敛 → 改权威文件；其余副本改为指针或删除；写死值改为"复跑取号"
|
||
⑤ 复跑+同步 → 四件套全绿 → scp → 复跑 docs-sync-check.sh
|
||
```
|
||
|
||
**② 定性是分水岭**——2026-09-12 首跑报 20 项，逐条看上下文后：
|
||
- 真漂移 **≈6 项**（下一号三处矛盾、MemoryMax 两处取值不一致、`maidou`、旧路径、SSH 端口）
|
||
- **合法历史 14 项**（"旧域已 301" / "512M→384M" 的迁移表述）
|
||
⇒ 若不做定性就批量改，会**破坏历史档案**并制造新错误。
|
||
|
||
---
|
||
|
||
## 5. 自动化的边界（**重要**）
|
||
|
||
| 动作 | 可否自动 | 理由 |
|
||
|---|---|---|
|
||
| **检测**（跑四件套、出报告） | ✅ **可以，且应该** | 只读、零风险、退出码可判定 |
|
||
| **刷新派生件**（`docs-manifest.json`） | ✅ 可以 | 纯派生，无人工语义 |
|
||
| **改写正文 / 批量替换** | ❌ **不可以** | ① 触 **R7**（批量写入须确认）② **认识论漂移**：LLM 改知识库后，错误会成为后续输入并**复利放大**（LLM Wiki 社区已实证）③ 研究员明确指出：**git diff + 人工审阅才是真正的安全网** |
|
||
| **删历史档案里的旧值** | ❌ 不可以 | 违反铁律 2（L5 冻结） |
|
||
|
||
⇒ **推荐形态**：自动任务**只做"体检 + 出报告"**，**发现违背时通知人**，由人或新会话按 §4 SOP 收敛。
|
||
|
||
---
|
||
|
||
## 6. 反例（今天真实踩过，别重犯）
|
||
|
||
| # | 反例 | 后果 | 规避 |
|
||
|---|---|---|---|
|
||
| 1 | 校验规则太宽（拿"旧域名"当违规） | 20 项里 14 项误报 → 校验器被忽视 | 只留高置信模式；拿不准就不查，改人工 |
|
||
| 2 | 改了**技能工作副本**却忘了**归档副本** | 校验器扫的是归档副本 → 改了等于没改 | 技能两处位置必须同步（md5 一致） |
|
||
| 3 | 备份文件 `*.bak-*` 留在**文档库内** | 污染 `docs-sync-check`（算成"仅本地"） | 备份放库外，或收尾删掉 |
|
||
| 4 | scp 时把 `scripts/x.py` 也推到**根目录** | 服务器多一份同内容副本 → 对账报"仅服务器" | scp 目标路径逐个核对 |
|
||
| 5 | 把"下一号"写死在入口文档 | 并行改动 3 次打穿（83→85→87） | 一律"复跑取号" |
|
||
| 6 | **只看根目录就说"本机没有这个文件"** | 实际在 `scripts/` 下 → 结论完全相反（今天两次） | 报"不存在/缺失"前先 `find` 全库 |
|
||
| 7 | **把问题抛给用户前没确认它还在** | 服务器多余文件已被并行会话清掉 → 问了个**已消失**的问题 | 抛出前重新查一次；状态会被别人改变 |
|
||
| 8 | 没顺着 grep 找权威档案就猜文件用途 | 直接读关联档案的 TL;DR 一句话就清楚，比猜快得多 | `grep -rn <文件名> --include="*.md"` → 读那条档案的头部 |
|
||
|
||
---
|
||
|
||
## 7. 自检清单（每次动知识库前后）
|
||
|
||
**动手前**
|
||
1. 这个事实的**唯一权威**在哪一层？我是不是正准备在别处复制它？
|
||
2. 我要改的是**承诺现行**还是**历史**文件？历史的 → 不回改，追加"修正"小节。
|
||
3. 涉及 >10 文件？→ 先出清单（R7）。
|
||
|
||
**收尾**
|
||
4. 四件套**全绿**了吗？
|
||
5. 两处技能副本 md5 一致吗？推服务器了吗？
|
||
6. 临时/备份产物清了吗？
|
||
7. 复数入口都改成"复跑取号"了吗？
|