원클릭으로 Manus에서 모든 스킬 실행

prism-wiki-depth

스타0

포크0

업데이트2026년 5월 28일 01:29

Use when writing or auditing core/ layer documentation to ensure knowledge depth. Covers design motivation extraction, constraint documentation, failure mode analysis, cross-module contracts, and change sensitivity. Complements prism-wiki-standard.

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

Hatedatastructures

Hatedatastructures/PrismWiki

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

深度知识提取规范

本 skill 是 prism-wiki-standard 的互补层。standard 负责骨架（格式、类型、链接），本 skill 负责血肉（设计意图、约束、故障模式、跨模块协议）。

适用范围：仅 core/ 层 API 文档（type: api）和 dev/ 层编码指南。ref/、docs/、client/ 不适用。

前置条件：必须先按 prism-wiki-standard 完成骨架（frontmatter、段落结构、函数签名表）。本 skill 不替代 standard，而是在已有骨架上注入深度。

核心理念

代码文档的深度不是行数，而是回答了几个读者无法从源码直接得到答案的问题。

好的深度文档回答五类问题：

#	问题	源码能回答吗	文档必须回答
1	为什么这么设计？	不能	设计动机
2	有什么隐藏约束？	部分（散在注释里）	显式列出
3	出错了会怎样？	部分（散在 trace 里）	故障模式
4	和其他模块有什么隐式协议？	不能	跨模块契约
5	改了这个会影响谁？	不能	变更敏感度

一、设计动机提取

什么是设计动机

设计动机解释为什么选择这个实现方式，而不是其他可行方案。它回答"作者面对什么问题时做了这个选择"。

提取方法

读头文件的 @details 和 @note：这是作者自己写的意图
读实现文件中的 WHY 注释：搜索关键词 防止、避免、确保、否则、必须、限制、复用、解耦
问自己：如果删掉这段代码，什么会坏？怎么坏？

写入位置

在 API 文档的「概述」段落末尾，加一个 ## 设计决策 子段落（S 档必写，A 档可选，B 档不要写）。

格式

## 设计决策

### 为什么 X 使用 Y 模式？

[一句话描述问题]

[两到三句话解释选择原因和替代方案的取舍]

**后果**: [这个选择带来的限制或好处]

示例模式

以下是三类常见的设计决策模式，提取时对号入座：

模式 1：性能关键路径上的非显而易见选择

当一个看似多余的类型包装或间接层出现在热路径上时，通常是零分配或避免悬挂指针。

### 为什么会话计数器用 shared_ptr<atomic<T>> 包装？

会话关闭回调在对象析构后才执行。如果回调捕获裸指针，
所属模块部分析构后回调访问的是悬挂指针。

通过 shared_ptr 包装计数器，回调只捕获计数器本身，
独立于所属模块生命周期。

**后果**: 控制块生命周期可能长于所属模块，但开销可忽略
（每个模块仅一个计数器）。

模式 2：看似多余但实际有保护作用的代码

当出现 std::move 后对空容器操作、冗余的状态检查、双重锁等，通常是防范重入或迭代器失效。

### 为什么 close() 用 std::move(map) 而不是直接迭代？

子对象的 close() 会回调本对象的 remove 方法，后者执行
map.erase()。如果迭代的是 map 本身，erase 导致迭代器失效。

先 std::move 把 map 移到局部变量，原 map 变空。
后续 remove 方法对空 map 的 erase 是空操作。

**后果**: close() 只能调用一次。由原子标志的幂等性保证。

模式 3：类型选择中的权衡

当选择了看起来"不对"的类型（如 string_view 而非 string、span 而非 vector），通常是零拷贝或避免分配。

### 为什么路由查找使用透明哈希？

每次请求的路由查找需要用 `string_view`（来自协议解析的零拷贝视图）
查 `unordered_map<string, endpoint>`。普通查找会构造临时 string，
触发堆分配。

使用 `is_transparent` 透明查找，`string_view` 直接查表，热路径零分配。

**后果**: 哈希函数和相等比较必须保证跨类型一致性
（统一用 `hash<string_view>` 计算哈希值）。

提取清单

在写「设计决策」时，逐条检查：

有没有 @note、@warning、@details 标注了设计理由？
实现文件中有没有带"防止"、"避免"、"解耦"的注释？
是否存在非显而易见的类型选择（如 shared_ptr<atomic> 而非 atomic 成员）？
是否存在看似多余但实际有保护作用的代码（如 std::move 后对空容器操作）？
是否有性能关键路径上的特殊处理（如栈缓冲区代替堆分配）？

二、约束文档化

什么是约束

约束是使用此代码时必须遵守的规则。违反约束不会产生编译错误，但会在运行时导致未定义行为、数据竞争、资源泄漏或安全漏洞。

约束分类

类型	说明	严重度
生命周期约束	A 必须比 B 活得长	违反→悬挂指针/崩溃
调用顺序约束	必须先调 X 再调 Y	违反→未初始化/数据丢失
线程安全约束	必须在特定上下文调用	违反→数据竞争
状态前置条件	调用时对象必须处于某状态	违反→逻辑错误
资源上限约束	数据大小/数量有硬上限	违反→溢出/OOM

写入位置

在 API 文档中加 ## 约束 段落（S 档必写，A 档必写，B 档写重要的）。放在「依赖关系」之后、「函数签名表」之前。

格式

## 约束

### [约束名称]

**类型**: 生命周期 / 调用顺序 / 线程安全 / 状态前置 / 资源上限

**规则**: [一句话描述约束]

**违反后果**: [具体会出什么问题]

**源码依据**: [文件:行号]

示例模式

模式 1：状态前置 — 某方法仅在特定状态下安全

### rewind 只能在纯读取阶段使用

**类型**: 状态前置

**规则**: rewind() 仅在未发生写入时有效。
认证阶段是纯读取，安全 rewind。一旦开始写入，状态不可恢复。

**违反后果**: rewind 后读取到不一致的状态，
可能导致协议解析错误或安全漏洞。

**源码依据**: snapshot.hpp 布尔标志字段

模式 2：调用顺序 — 初始化依赖

### start() 必须在事件循环运行前调用

**类型**: 调用顺序

**规则**: start() 必须在事件循环 run() 之前调用，
否则内部清理协程不会启动。

**违反后果**: 过期资源永远不会被清理，容器无限增长。

**源码依据**: pool.hpp start() 方法注释

模式 3：线程安全 — 非线程安全但有例外

### 工作线程不可跨线程共享

**类型**: 线程安全

**规则**: 所有成员访问必须在所属线程内进行。
只有 dispatch() 和 snapshot() 是线程安全的
（内部使用 post 跨线程分发）。

**违反后果**: 数据竞争，未定义行为。

模式 4：资源管理 — RAII 依赖

### 连接包装器必须显式析构或 reset

**类型**: 资源管理

**规则**: 包装器必须在底层资源不再需要前析构或
显式 reset()/release()。否则资源不会被归还池中。

**违反后果**: 资源泄漏。池中可用资源逐渐耗尽。

提取清单

头文件中有没有 @warning 标注？（最常见的约束信号）
有没有裸指针/引用成员？（生命周期依赖）
有没有 noexcept 方法但内部依赖有效状态？（状态前置）
有没有 atomic 成员但文档说"不是线程安全的"？（局部线程安全）
有没有固定大小的缓冲区/计数器？（资源上限）

三、故障模式分析

什么是故障模式

故障模式描述代码在异常条件下怎么失败、失败时什么表现、如何恢复。它不是"函数返回错误码"的罗列，而是端到端的故障场景。

故障场景 vs 错误码

错误码（bad）：函数返回 timeout
故障场景（good）：上游服务器无响应时，连接池等待超时后返回 timeout。
连接未归还池中。调用方会尝试下一个端点或返回错误。
最终会话关闭，客户端收到连接重置。

写入位置

S 档文档加 ## 故障场景 段落，放在「调用链」之后。 A 档文档只在关键路径（网络 I/O、加密、状态机）写故障场景。 B 档不写。

格式

## 故障场景

### [场景名称]

**触发条件**: [什么情况会导致这个故障]

**传播路径**: [错误从哪里产生，经过哪些层，最终到哪]

**外部表现**: [客户端/运维看到什么现象]

**恢复机制**: [系统如何自动恢复，或需要人工干预]

**日志关键字**: [grep 什么字符串可以在日志中定位此故障]

示例模式

模式 1：级联失败 — 从底层到顶层的完整传播

### 所有候选地址连接失败

**触发条件**: 目标域名的所有解析结果都无法建立连接。
常见原因：目标宕机、防火墙阻断、本地网络中断。

**传播路径**: racer 每个候选连接超时或拒绝 →
所有 pending 递减到 0 且无 winner → 返回错误码 →
上层重试（默认 N 次）→ 全部失败 → 转发层返回错误 →
会话关闭 → 客户端收到 RST。

**外部表现**: 客户端连接超时。

**恢复机制**: 自动。下次请求重新触发解析和竞速。
如果是临时网络故障，新请求可能成功。

**日志关键字**: 模块名 + 错误码

模式 2：资源耗尽 — 自限流与自动恢复

### accept() 因文件描述符耗尽而失败

**触发条件**: 系统文件描述符达到上限。

**传播路径**: accept() 返回错误 →
指数退避（10ms → 20ms → 40ms → ... → 上限 1s） →
持续重试直到有 fd 释放 → 恢复 accept。

**外部表现**: 新连接间歇性无法建立。已建立的连接不受影响。

**恢复机制**: 自动。指数退避避免 CPU 空转。
当旧连接关闭释放 fd 后，accept 自动恢复。

**日志关键字**: accept + error

模式 3：安全检测 — 主动防御

### 密钥交换输出全零（低阶点攻击）

**触发条件**: 攻击者构造特殊的公钥，使得密钥交换输出全零。

**传播路径**: 密钥交换成功返回 → 全零检查捕获 →
日志警告 → 返回错误码 → 握手失败 →
回退到伪装目标或关闭连接。

**外部表现**: 连接被拒绝，日志出现警告信息。

**恢复机制**: 自动。该连接被拒绝，不影响其他连接。
攻击者无法获得任何有用的认证信息。

提取清单

函数有没有返回错误码枚举？每种错误码对应什么故障？
有没有 error/warn 级别的日志？它们在什么条件下触发？
有没有 try/catch 或 co_await 错误处理？捕获了什么异常？
有没有超时机制？超时后怎么处理？
有没有资源上限检查？超出后怎么处理？

四、跨模块契约

什么是跨模块契约

两个模块之间的隐式协议 — 不在类型系统或接口签名中体现，但违反了就会出问题的约定。

常见契约类型

契约类型	说明
初始化顺序	A 必须在 B 之前初始化
生命周期绑定	A 持有 B 的引用，B 必须比 A 活得长
回调重入	A 调用 B，B 的回调又会调用 A（需要防范重入）
数据格式约定	A 产生的数据 B 消费，格式必须匹配
线程归属	A 的实例只被特定线程使用，B 必须遵守

写入位置

在「依赖关系」表格中增加一行契约说明。S 档必写，A 档重要契约必写。

格式

在依赖关系表格后加：

### 跨模块契约

| 模块 A | 模块 B | 契约内容 |
|--------|--------|---------|
| 上层 | 下层 | 上层负责 X；下层假设 Y；违反后 Z |

示例模式

模式 1：回调重入契约

### 跨模块契约

| 模块 A | 模块 B | 契约内容 |
|--------|--------|---------|
| 子对象 | 容器 | 子对象::close() 内部调用容器::remove()。这是重入调用：容器::close() → 子对象::close() → 容器::remove()。容器用 std::move(map) 在迭代前清空，确保 remove() 的 erase 操作安全（对空 map 的 erase 是空操作） |

模式 2：初始化顺序契约

### 跨模块契约

| 模块 A | 模块 B | 契约内容 |
|--------|--------|---------|
| 注册模块 | 使用模块 | register() 必须在使用模块首次使用前调用（启动流程保证）。注册顺序决定默认优先级 |

模式 3：副作用契约

### 跨模块契约

| 模块 A | 模块 B | 契约内容 |
|--------|--------|---------|
| 健康检查 | 连接池 | check() 临时设置 socket 为非阻塞模式，检查后恢复原始状态。如果恢复失败，后续 async 操作可能阻塞在非预期模式 |

提取清单

模块持有其他模块的引用/裸指针？（生命周期契约）
模块注册回调给其他模块？（重入契约）
模块依赖启动阶段的初始化顺序？（初始化契约）
模块产生的数据被其他模块消费？（格式契约）
模块有 friend 声明？（特权访问契约）

五、变更敏感度

什么是变更敏感度

描述修改此模块时，哪些改动会影响其他模块，以及其他模块的哪些改动会破坏此模块。

写入位置

S 档文档末尾加 ## 变更敏感度 段落。A 档不写。

格式

## 变更敏感度

### 对外影响（改这里会影响谁）

| 变更 | 影响范围 | 影响 |
|------|---------|------|
| 修改 close() 的幂等性假设 | 所有子对象 | 它们的 close() 依赖 remove() 对空容器安全 |
| 修改内部数据结构 | 所有子类 | 子类直接操作该 buffer |

### 对内影响（改别人会影响这里）

| 上游变更 | 本模块受影响 | 需要检查 |
|---------|------------|---------|
| 子对象增加新的关闭路径 | remove() 被新路径调用 | 确认容器状态一致 |
| 依赖层新增装饰器 | cancel()/close() 穿透 | 确认新装饰器正确转发 |

提取方法

找 friend 和继承关系：基类改了，所有子类都受影响
找回调/观察者模式：回调签名改了，所有注册者都受影响
找协议常量：magic number、版本号改了，所有对端都受影响
找 shared_ptr 共享状态：共享对象的结构改了，所有持有者都受影响

六、代码片段使用规则

prism-wiki-standard 的 Pitfall #15 说"不要贴源码片段"。这个规则过于绝对。以下定义什么时候该贴、什么时候不该贴。

应该贴代码（知识提炼后的片段）

展示调用模式：读者无法仅从函数签名理解的组合使用方式

// 好：展示了 shared_ptr<atomic> 的使用模式
auto counter = metrics.session_counter();  // shared_ptr 拷贝
auto on_closed = [counter]() noexcept {
    counter->fetch_sub(1U, std::memory_order_relaxed);  // 安全
};

展示关键算法：不可从函数名直接推断的逻辑

// 好：EMA 平滑算法的具体参数
smoothed = (smoothed * 7 + effective) / 8;

展示错误处理路径：多步恢复逻辑

// 好：fd 转移后的错误恢复
auto native_handle = sock.release();
migrated.assign(protocol, native_handle, ec);
if (ec || !migrated.is_open())
{
    closesocket(native_handle);
}

不应该贴代码（直接搬运）

Doxygen 已有的内容：函数签名、参数列表、返回值类型 — 这些已经在 wiki 的函数签名表里了
getter/setter 实现：显而易见的代码
整个类定义：用成员变量表代替
重载的每个版本：选一个有代表性的，其余用文字说明差异

判断标准

问自己：如果删掉这段代码，只保留文字描述，读者能否理解？

能 → 不要贴代码，用文字
不能 → 贴代码，因为代码本身就是知识的载体

七、深度审计检查

在完成 prism-wiki-standard 的骨架审计后，运行以下深度审计。以下脚本需替换路径为实际的知识库目录和源码目录。

设计动机审计

# 检查 S 档文档是否有「设计决策」段落
# WIKI_DIR = 知识库 core 层目录
for f in $(find $WIKI_DIR -name '*.md' -not -path '*/.git/*' -not -path '*/.obsidian/*'); do
  lines=$(wc -l < "$f")
  [ "$lines" -gt 150 ] && ! grep -q '设计决策\|为什么' "$f" && echo "MISSING_MOTIVE($lines): $f"
done

约束审计

# 检查 S/A 档文档是否有「约束」段落
# 对比：源码中有 @warning 但 wiki 没有「约束」
for f in $(find $WIKI_DIR -name '*.md' -not -path '*/.git/*' -not -path '*/.obsidian/*'); do
  lines=$(wc -l < "$f")
  [ "$lines" -gt 80 ] || continue
  src=$(head -15 "$f" | grep -m1 '^source:' | sed 's/^source: *"*//;s/"*$//')
  [ -z "$src" ] && continue
  hpp="${SRC_DIR}/${src}"
  [ ! -f "$hpp" ] && continue
  warnings=$(grep -c '@warning' "$hpp" 2>/dev/null || echo 0)
  has_constraints=$(grep -c '约束' "$f" 2>/dev/null || echo 0)
  [ "$warnings" -gt 0 ] && [ "$has_constraints" -eq 0 ] && echo "MISSING_CONSTRAINT(warnings=$warnings): $f"
done

故障模式审计

# 检查涉及网络 I/O 或加密的 S 档文档是否有「故障场景」
for f in $(find $WIKI_DIR -name '*.md' -not -path '*/.git/*' -not -path '*/.obsidian/*'); do
  lines=$(wc -l < "$f")
  [ "$lines" -gt 150 ] || continue
  has_io=$(grep -cl 'async_read\|async_write\|co_await\|socket\|tls\|ssl\|encrypt\|decrypt' "$f" 2>/dev/null)
  [ -n "$has_io" ] && ! grep -q '故障场景\|故障模式' "$f" && echo "MISSING_FAILURE($lines): $f"
done

代码搬运检测

# 检查文档中代码块占比（超过 40% 可能是代码搬运）
for f in $(find $WIKI_DIR -name '*.md' -not -path '*/.git/*' -not -path '*/.obsidian/*'); do
  total=$(wc -l < "$f")
  [ "$total" -lt 30 ] && continue
  code_lines=$(awk '/^```/{flag=1-flag;next} flag{count++}END{print count+0}' "$f")
  ratio=$((code_lines * 100 / total))
  [ "$ratio" -gt 40 ] && echo "CODE_HEAVY(${ratio}%): $f"
done

八、写入流程（与 prism-wiki-standard 协作）

新建 S 档文档

按 prism-wiki-standard 完成骨架（frontmatter → 概述 → 命名空间 → 依赖关系 → 函数签名表 → 函数分节）
本 skill 接管：在概述中提取设计动机，加「设计决策」
本 skill 接管：在依赖关系后加「约束」
本 skill 接管：在调用链后加「故障场景」
本 skill 接管：在依赖关系表格后加「跨模块契约」
本 skill 接管：在文档末尾加「变更敏感度」
回到 prism-wiki-standard：更新 index.md，记 log.md

刷新已有文档

必须重读头文件和实现文件：不是在旧文档上修补
对比旧文档与新源码，标记哪些「设计决策」和「约束」仍然有效
删除过时的深度内容，补充新增的
运行深度审计检查

优先级排序

按以下顺序注入深度，而非一次全写：

约束 — 最实用，读者最需要，违反后果最严重
设计决策 — 理解系统的关键，但阅读频率较低
跨模块契约 — 修改代码时必须知道
故障场景 — 排障时需要
变更敏感度 — 重构时需要

九、质量指标

深度文档的质量不用行数衡量，用信息密度衡量：

指标	计算方法	目标
约束覆盖率	有约束段落的 S/A 档文档数 / 总 S/A 档文档数	≥ 80%
设计动机覆盖率	有「设计决策」的 S 档文档数 / 总 S 档文档数	≥ 60%
故障场景覆盖率	有「故障场景」的网络/加密相关 S 档文档数 / 总相关文档数	≥ 50%
代码搬运率	代码行 / 总行数	≤ 30%
重复信息率	与 Doxygen 注释重复的描述 / 总描述	≤ 20%

重复信息率是关键指标。如果 wiki 的某段话和头文件 Doxygen 注释说的是同一件事，至少有一方是多余的。要么 wiki 说得比 Doxygen 更深（补充 Why、后果、场景），要么删掉 wiki 搬运的那段。

十、源码沉默时的处理策略

问题

上文的提取方法依赖源码中有 WHY 注释（@note、@warning、"防止"、"避免"等关键词）。但大量设计决策没有任何注释：

hardcoded 常量的具体数值（为什么是 6 而不是 8？）
阈值参数的选取依据（为什么是 90%/80%？）
数据结构大小限制（为什么帧头是 N 字节？）
缓冲区大小的选取（为什么是 65536？）

三级处理策略

对每个设计决策，按以下顺序判断：

级别 1：源码有 WHY 注释 → 提取并扩展

这是最简单的情况。直接提取，按「设计决策」格式写。

验证：标注 **源码依据**: file:line，读者可以跳过去确认。

级别 2：源码有 WHAT 但没有 WHY → 从上下文推断，标注置信度

从代码的上下文推断设计意图。但必须标注推断的置信度，让读者知道这不是源码明确说的。

推断方法：

看调用方：谁调用这个函数？调用方的注释是否暗示了设计意图？
看边界条件：hardcoded 常量通常与某个协议规范或系统限制相关 — 去找原始规范
看替代方案：如果不用这个值/方法，最自然的替代是什么？为什么替代方案不可行？
看历史：git log -p -- file 看这个值是何时引入的，commit message 可能解释原因

格式：

### 为什么 max_racing 是 N？

[从上下文推断的原因]

**置信度**: 推断（源码只写了 WHAT，未说明 WHY 的具体依据）
**替代方案**: [其他可行值及为什么不选]
**源码依据**: file:line

关键要素：

置信度标注：推断 或 高确信 或 推测
替代方案：说明为什么不用其他值
源码依据：指向原始 WHAT 注释

级别 3：既没有 WHY 也没有 WHAT → 不写设计决策，标注"未记录"

不要编造动机。如果无法从上下文合理推断，写：

## 设计决策

> 此模块的设计决策未在源码注释中记录。以下列出已知的非显而易见的实现选择，
> 等待作者确认或补充。

### [某某设计选择]？

[已知事实]

**状态**: 未确认
**源码依据**: file:line

绝对禁止

禁止编造理由：如果不知道为什么，写"未记录"比编造一个看似合理的理由好 100 倍
禁止把 WHAT 当 WHY："max_hdr_size = 65536 限制了大小" — 这是 WHAT，不是 WHY。WHY 是"为什么选 65536 而不是其他值"
禁止猜测作者意图：如果注释没说，你不知道作者当时在想什么。只能从代码事实和外部规范推断

十一、伪深度防御

什么是伪深度

伪深度是看似有设计洞察，实际上要么是编造的，要么是错误归因，要么是显而易见的废话。这是 AI 写文档时最容易犯的错误。

伪深度模式识别

伪深度模式	示例	问题
显而易见包装	"为什么用 `unordered_map`？因为 O(1) 查找比 O(log n) 快"	废话，任何 C++ 开发者都知道
编造理由	"为什么用 HMAC-SHA1？因为 SHA-256 在当时还没有广泛部署"	事实错误（SHA-256 早已普及）
错误归因	"为什么用 write_channel？为了避免单个慢速消费者阻塞整个会话"	过度泛化。实际只阻塞帧循环，其他流不受影响
替代方案稻草人	"为什么不使用互斥锁？因为互斥锁会阻塞事件循环线程"	正确但无信息量 — 协程项目里禁止 mutex 是基本原则，不是设计决策
空泛后果	"后果: 需要注意内存管理"	没有具体说明什么后果

验证流程

写完每条设计决策后，执行以下验证：

第一步：删除测试

删掉你写的"为什么"解释，只保留事实描述。问自己：读者能否从事实描述中推出你的解释？

能推出 → 你的解释是显而易见的废话，重写或删除
推不出 → 你的解释有价值，保留

第二步：源码确认

你写的每条断言，能否在头文件或实现文件中找到对应的注释/代码支撑？

能找到 → 标注 **源码依据**: file:line
找不到 → 回到「十、源码沉默时的处理策略」，标注置信度或标为"未记录"

第三步：精确性检查

你写的描述是否比源码注释更精确？检查有没有过度泛化：

源码注释: "write_channel 解耦帧循环与 target 写入，避免慢速 target 阻塞帧循环"
伪深度:   "避免单个慢速 target 阻塞整个会话"
正确深度:  "避免慢速 target 阻塞帧循环（frame loop）。其他已建立的流
          不受影响，因为它们的数据在各自的缓冲区中排队"

差异：伪深度用"整个会话"泛化了"帧循环"，导致读者对影响范围产生错误理解。

质量自检清单

每条设计决策写完后，逐条打分：

删除测试通过？（不是显而易见的废话）
有源码依据？（每条断言都有注释/代码支撑）
精确性检查通过？（没有过度泛化或错误归因）
有后果描述？（具体说了这个选择带来什么限制/好处）
不是编码原则的重述？（不是"用 RAII 因为安全"这种）

5 项全部通过才能保留。任何一项不通过，重写或删除。

十二、完整 S 档深度文档结构模板

以下是 S 档深度文档的完整结构模板，展示所有深度段落如何在一个文档中衔接。

---
layer: core
source: [源文件路径]
title: [模块标题]
created: [日期]
updated: [日期]
tags: [标签列表]
---

# [模块标题]

> 源码: [头文件] | 实现: [实现文件]
> 模块: [[父模块链接]]

## 概述

[2-3 句功能描述。不是搬运 Doxygen，而是解释这个模块在整个系统中
扮演什么角色、解决什么问题。]

## 命名空间

[命名空间声明]

## 依赖关系

| 依赖方向 | 模块 | 说明 |
|----------|------|------|
| 依赖 | [[模块A]] | 原因 |
| 被调用 | [[模块B]] | 谁在什么场景调用 |

## 设计决策

### 为什么 [非显而易见的设计选择]？

[问题描述]

[选择原因和替代方案取舍]

**后果**: [具体限制或好处]
**置信度**: [有源码依据则省略，推断则标注]
**源码依据**: [file:line]

[重复此模式，每条设计决策独立成段]

## 约束

### [约束名称]

**类型**: 生命周期 / 调用顺序 / 线程安全 / 状态前置 / 资源上限

**规则**: [一句话描述]

**违反后果**: [具体会出什么问题]

**源码依据**: [file:line]

[重复此模式]

## 函数签名表

| 函数 | 签名 | 说明 |
|------|------|------|
| ... | ... | ... |

## 函数: [函数名]

> 源码: [头文件] | 实现: [实现文件:行号]

[函数详细文档，包括参数、返回值、流程]

## 故障场景

### [场景名称]

**触发条件**: [什么情况导致]
**传播路径**: [错误从哪产生，经过哪些层，到哪]
**外部表现**: [客户端/运维看到什么]
**恢复机制**: [自动/人工，怎么恢复]
**日志关键字**: [grep 什么字符串定位]

[重复此模式]

## 跨模块契约

| 模块 A | 模块 B | 契约内容 |
|--------|--------|---------|
| ... | ... | ... |

## 变更敏感度

### 对外影响（改这里会影响谁）

| 变更 | 影响范围 | 影响 |
|------|---------|------|
| ... | ... | ... |

### 对内影响（改别人会影响这里）

| 上游变更 | 本模块受影响 | 需要检查 |
|---------|------------|---------|
| ... | ... | ... |

## 相关文档

- [[相关模块A]]
- [[相关模块B]]

结构要点

概述不重复 Doxygen：概述回答"这个模块在系统中的角色"，Doxygen 回答"这个函数做什么"
设计决策在约束之前：先理解为什么这么设计，再理解使用限制
故障场景在函数文档之后：需要先理解正常流程，再看异常流程
跨模块契约和变更敏感度在最后：这是维护者视角的内容
信息不重复：概述中提到的东西，设计决策不重写；约束中提到的限制，故障场景只引用不重述

十三、模块深度优先级排序

知识库的深度注入应按模块重要性排序，而非按文件名字母序。

排序维度

每个模块按三个维度打分，计算优先级：

维度	评分标准
使用频率	核心路径上的模块 = 3，多数请求经过 = 2，少数场景使用 = 1
安全/正确性敏感度	涉及密码学/协议解析/资源管理 = 3，业务逻辑 = 2，辅助工具 = 1
修改频率	经常修改 = 3，偶尔修改 = 2，几乎不改 = 1

优先级 = 使用频率 × 安全敏感度 × 修改频率（范围 1-27）

分级标准

优先级分数	等级	深度要求
18-27	P0 必须有深度	全部 5 个深度段落
10-17	P1 应该有深度	约束 + 设计决策 + 故障场景
5-9	P2 可以有深度	约束 + 设计决策
1-4	P3 不需要深度	只需骨架，强行加深度反而制造噪音

执行建议

按 P0 → P1 → P2 → P3 顺序注入深度。每个优先级内，按以下顺序：

约束（最实用）
设计决策（理解关键）
故障场景（排障用）
跨模块契约（重构用）
变更敏感度（维护用）

每批 3-5 个文件，写完后运行深度审计确认质量。

name	prism-wiki-depth
description	Use when writing or auditing core/ layer documentation to ensure knowledge depth. Covers design motivation extraction, constraint documentation, failure mode analysis, cross-module contracts, and change sensitivity. Complements prism-wiki-standard.
version	3.0.0
author	Wang
license	MIT
platforms	["windows"]
metadata	{"hermes":{"tags":["wiki","knowledge-base","depth","design-intent","constraints","failure-modes"]}}
layer	skills

name	prism-wiki-depth
description	Use when writing or auditing core/ layer documentation to ensure knowledge depth. Covers design motivation extraction, constraint documentation, failure mode analysis, cross-module contracts, and change sensitivity. Complements prism-wiki-standard.
version	3.0.0
author	Wang
license	MIT
platforms	["windows"]
metadata	{"hermes":{"tags":["wiki","knowledge-base","depth","design-intent","constraints","failure-modes"]}}
layer	skills

prism-wiki-depth

이 저장소의 다른 Skills

이 저장소의 다른 Skills

深度知识提取规范

核心理念

一、设计动机提取

什么是设计动机

提取方法

写入位置

格式

示例模式

提取清单

二、约束文档化

什么是约束

约束分类

写入位置

格式

示例模式

提取清单

三、故障模式分析

什么是故障模式

故障场景 vs 错误码

写入位置

格式

示例模式

提取清单

四、跨模块契约

什么是跨模块契约

常见契约类型

写入位置

格式

示例模式

提取清单

五、变更敏感度

什么是变更敏感度

写入位置

格式

提取方法

六、代码片段使用规则

应该贴代码（知识提炼后的片段）

不应该贴代码（直接搬运）

判断标准

七、深度审计检查

设计动机审计

约束审计

故障模式审计

代码搬运检测

八、写入流程（与 prism-wiki-standard 协作）

新建 S 档文档

刷新已有文档

优先级排序

九、质量指标

十、源码沉默时的处理策略

问题

三级处理策略

级别 1：源码有 WHY 注释 → 提取并扩展

级别 2：源码有 WHAT 但没有 WHY → 从上下文推断，标注置信度

级别 3：既没有 WHY 也没有 WHAT → 不写设计决策，标注"未记录"

绝对禁止

十一、伪深度防御

什么是伪深度

伪深度模式识别

验证流程

质量自检清单

十二、完整 S 档深度文档结构模板

结构要点

十三、模块深度优先级排序

排序维度

分级标准

执行建议

深度知识提取规范

核心理念

一、设计动机提取

什么是设计动机

提取方法

写入位置

格式

示例模式

提取清单

二、约束文档化