القائمة
Bug 修复或对接问题排查确认有效后，将经验记录到知识库。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | archive-bug |
| description | Bug 修复或对接问题排查确认有效后，将经验记录到知识库。 |
仅在以下条件全部满足时触发：
绝不触发的情况：
在写入知识库前，必须确认以下所有项：
## 修复确认清单
- [ ] Bug 描述清晰（现象可复现）
- [ ] 根因已定位（不是猜测）
- [ ] 修复代码已提交（有 commit hash）
- [ ] 相关测试已通过（列出测试命令和结果）
- [ ] 无回归问题（未引入新 bug）
- [ ] 用户确认可以归档
如果有任何一项未满足，停止并告知用户原因。
根据问题类型，严格归档到对应目录：
归档路径： H:/wiki/bugs/
文件命名： {模块}-{简要描述}.md
示例：
frame-parsing-error.md — 帧解析错误handshake-timeout.md — 握手超时memory-pool-leak.md — 内存池泄漏触发场景：
归档路径： H:/wiki/client/
文件命名： {客户端}-{问题类型}.md
示例：
client-compatibility.md — 客户端与服务端兼容性client-version-negotiation.md — 客户端版本协商问题clash-config-template.md — Clash 配置模板触发场景：
归档路径： H:/{模块名}/
文件命名： {子模块}-{问题类型}.md
示例：
stealth/key-rotation.md — 密钥轮换问题multiplex/flow-control.md — 流控问题crypto/aead-nonce-reuse.md — AEAD nonce 重用问题触发场景：
归档路径： H:/wiki/protocol/ 或 H:/wiki/stealth/
文件命名： {协议}-{问题类型}.md
示例：
auth-mismatch.md — 认证不匹配session-reuse.md — 会话复用问题decryption-failure.md — 解密失败触发场景：
---
title: {Bug 标题}
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
type: bug
severity: critical | major | minor
modules: [{affected modules}]
status: fixed
fix_commit: {commit hash}
fix_date: {YYYY-MM-DD}
related: [{related pages}]
---
## 现象
**用户可见症状：**
- 具体描述用户看到的错误现象
- 错误信息/日志片段
- 复现步骤（如果有）
**影响范围：**
- 影响哪些功能
- 影响哪些客户端/平台
- 严重程度评估
## 排查过程
**第一步：初步分析**
- 收集的信息
- 初步判断
**第二步：深入排查**
- 使用的工具/方法
- 关键发现
**第三步：根因定位**
- 最终定位的代码位置
- 根本原因分析
## 根因
**技术原因：**
- 详细的技术原因分析
- 相关代码片段（如有）
**设计原因（如有）：**
- 为什么会出现这个问题
- 设计上的缺陷
## 修复
**修复方案：**
- 修改了哪些文件
- 修改内容摘要
- 关键代码变更
**修复验证：**
- 测试命令
- 测试结果
- 回归测试结果
## 预防措施
**如何避免类似问题：**
- 代码审查要点
- 测试覆盖建议
- 文档更新建议
## 相关模块
- [[module1]]
- [[module2]]
- [[related-page]]
## 参考资料
- 相关 issue/PR 链接
- 外部文档链接
---
title: {对接问题标题}
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
type: client
client: {client name}
client_version: {version}
prism_version: {version}
status: resolved
related: [{related pages}]
---
## 问题描述
**现象：**
- 客户端连接 Prism 时的具体表现
- 错误信息/日志
**环境：**
- 客户端版本
- Prism 版本
- 操作系统/网络环境
## 排查过程
**第一步：配置检查**
- 检查的配置项
- 发现的差异
**第二步：协议分析**
- 抓包分析（如有）
- 协议版本对比
**第三步：兼容性测试**
- 测试的客户端版本
- 测试的 Prism 版本
## 根因
**兼容性原因：**
- 客户端与 Prism 的差异
- 协议版本/实现差异
## 解决方案
**配置调整：**
- 需要修改的配置项
- 配置模板
**代码修改（如有）：**
- Prism 侧的修改
- 客户端侧的建议
## 配置模板
```yaml
# 客户端配置示例
{配置内容}
```
## 兼容性矩阵
| 客户端版本 | Prism 版本 | 状态 | 备注 |
|-----------|-----------|------|------|
| {version} | {version} | ✅/❌ | {notes} |
## 相关页面
- [[client/{client-name}]]
- [[protocol/{protocol-name}]]
- [[stealth/{scheme-name}]]
## 归档确认
1. 问题是否已解决？ {是/否}
2. 是否已测试验证？ {是/否}
3. 用户是否确认归档？ {是/否}
4. 问题类型是什么？ {bug/client/module/protocol}
如果任何一项为"否"，停止并告知用户。
根据问题类型，选择归档目录：
问题类型 → 归档目录 → 文件名
─────────────────────────────────────
bug → H:/wiki/bugs/ → {module}-{description}.md
client → H:/wiki/client/ → {client}-{issue}.md
module → H:/{module}/ → {submodule}-{issue}.md
protocol → H:/wiki/protocol/ → {protocol}-{issue}.md
stealth → H:/wiki/stealth/ → {scheme}-{issue}.md
[[wikilinks]]）更新 H:/wiki/index.md：
更新 H:/wiki/log.md：
## [{YYYY-MM-DD}] {action} | {description}
- {action}: {file path}
- 原因: {brief reason}
- 相关: {related pages}
## 验证清单
- [ ] 文件已创建在正确路径
- [ ] frontmatter 格式正确
- [ ] 正文包含所有必要部分
- [ ] 至少 3 个 wikilinks
- [ ] index.md 已更新
- [ ] log.md 已更新
文件夹归档规则、特殊场景处理、完整示例流程、常见错误等详见 examples-and-edge-cases.md。
写入新模块文档、重构模块、或用户要求分析模块时触发。
修改 PMR 分配器、内存池配置、热路径容器、对象生命周期管理代码后触发。
编写或修改性能基准测试、分析 benchmark 结果、优化热路径性能时触发。
新增或修改 enable_shared_from_this 类、co_spawn 调用、shared_ptr 捕获的 lambda、co_await 后的成员访问时触发。
新增或修改原子操作、异步定时器、无锁通道、跨线程状态同步、CAS 竞争相关代码时触发。
修改协程（co_await/co_return/co_spawn）、异步 I/O、定时器、多线程相关 C++ 代码时触发。