dev-playbooks-cn 1.0.0

package/skills/devbooks-design-doc/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: devbooks-design-doc
+description: devbooks-design-doc：产出变更包的设计文档（design.md），只写 What/Constraints 与 AC-xxx，不写实现步骤。用户说"写设计文档/Design Doc/架构设计/约束/验收标准/AC/C4 Delta"等时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+---
+
+# DevBooks：设计文档（Design Doc）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 产物落点
+
+- 设计文档：`<change-root>/<change-id>/design.md`
+
+## 文档影响声明（必填）
+
+设计文档中**必须**包含「文档影响」章节，声明本次变更对用户文档的影响。这是确保文档与代码同步的关键机制。
+
+### 模板
+
+```markdown
+## Documentation Impact（文档影响）
+
+### 需要更新的文档
+
+| 文档 | 更新原因 | 优先级 |
+|------|----------|--------|
+| README.md | 新增功能 X 需要说明使用方法 | P0 |
+| docs/使用说明书.md | 新增脚本 Y 需要补充用法 | P0 |
+| CHANGELOG.md | 记录本次变更 | P1 |
+
+### 无需更新的文档
+
+- [ ] 本次变更为内部重构，不影响用户可见功能
+- [ ] 本次变更仅修复 bug，不引入新功能或改变使用方式
+
+### 文档更新检查清单
+
+- [ ] 新增脚本/命令已在使用文档中说明
+- [ ] 新增配置项已在配置文档中说明
+- [ ] 新增工作流/流程已在指南中说明
+- [ ] API/接口变更已在相关文档中更新
+```
+
+### 触发规则
+
+以下变更类型**强制要求**更新对应文档：
+
+| 变更类型 | 需更新文档 |
+|----------|------------|
+| 新增脚本（*.sh） | 使用说明、README |
+| 新增 Skill | README、Skills 列表 |
+| 修改工作流程 | 相关指南文档 |
+| 新增配置项 | 配置文档 |
+| 新增命令/CLI 参数 | 使用说明 |
+| 对外 API 变更 | API 文档 |
+
+## 执行方式
+
+1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+2) 严格按完整提示词输出：`references/设计文档提示词.md`。
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的运行模式。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测 `proposal.md` 是否存在（设计文档的输入）
+2. 检测 `design.md` 是否已存在
+3. 若存在，检测完整性（是否有 AC-xxx、是否有 `[TODO]`）
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **新建设计** | `design.md` 不存在 | 创建完整设计文档 |
+| **补充设计** | `design.md` 存在但有 `[TODO]` | 补充缺失章节 |
+| **添加 AC** | 设计存在但 AC 不完整 | 补充验收标准 |
+
+### 检测输出示例
+
+```
+检测结果：
+- proposal.md：存在
+- design.md：存在，有 5 个 [TODO]
+- AC 数量：8 个
+- 运行模式：补充设计
+```
+
+---
+
+## MCP 增强
+
+本 Skill 不依赖 MCP 服务，无需运行时检测。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+

package/skills/devbooks-design-doc/references//345/276/256/346/234/215/345/212/241/350/256/276/350/256/241/346/270/205/345/215/225.md

@@ -0,0 +1,149 @@
+# 微服务设计清单
+
+> 适用场景：设计涉及微服务/分布式架构时，使用本清单检查设计完整性。
+>
+> 本文档为**可选参考**，仅当项目涉及微服务/分布式系统时使用。
+
+---
+
+## 1) RPC 位置透明性陷阱（必须检查）
+
+**核心原则**：远程调用不等于本地函数调用，不要隐藏复杂度。
+
+### 1.1 设计文档必须声明
+
+- [ ] **超时策略**：每个 RPC 调用的超时时间（建议 1-5 秒）
+- [ ] **重试策略**：最大重试次数、重试间隔、指数退避
+- [ ] **降级方案**：依赖服务不可用时的行为（返回默认值/缓存/错误码）
+- [ ] **熔断阈值**：失败率达到多少时触发熔断（建议 50%）
+
+### 1.2 反模式检查
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|----------|
+| 无超时 RPC | 一个慢服务拖垮整条链路 | 显式设置超时，建议 1-5 秒 |
+| 无限重试 | 重试风暴压垮下游 | 最多 3 次，使用指数退避 |
+| 同步链式调用 | A→B→C→D 延迟叠加 | 异步化或并行调用 |
+| 隐藏远程调用 | 调用方不知道这是网络 IO | 接口名/返回类型体现"可失败" |
+
+### 1.3 Test Owner 检查项
+
+- [ ] 测试覆盖"依赖服务超时"场景（mock 超时）
+- [ ] 测试覆盖"依赖服务返回错误"场景
+- [ ] 测试覆盖"熔断后的降级行为"
+- [ ] 测试覆盖"重试逻辑"（验证最大重试次数）
+
+---
+
+## 2) 分布式故障影响评估
+
+### 2.1 故障模式清单
+
+| 故障类型 | 影响范围 | 检测方式 | 恢复策略 |
+|----------|----------|----------|----------|
+| 网络分区 | 服务 A 无法访问服务 B | 健康检查超时 | 熔断 + 降级 |
+| 节点宕机 | 单节点服务中断 | 心跳检测失败 | 负载均衡切换 |
+| 响应变慢 | 链路延迟增加 | p99 延迟告警 | 限流 + 排队 |
+| 数据不一致 | 多副本数据不同步 | 对账任务 | 重试 + 补偿 |
+
+### 2.2 设计文档必须声明
+
+- [ ] 本次变更涉及哪些服务间依赖？
+- [ ] 每个依赖的故障影响范围是什么？
+- [ ] 故障时的用户可见行为是什么？
+- [ ] 是否需要补充故障演练（Chaos Engineering）？
+
+---
+
+## 3) 链路追踪（Distributed Tracing）
+
+### 3.1 设计要求
+
+- [ ] 所有 RPC 调用必须传递 `trace_id`
+- [ ] 日志必须包含 `trace_id` 字段
+- [ ] 事件/消息必须包含 `trace_id` 字段
+
+### 3.2 实现检查
+
+```
+请求头传递: X-Trace-Id / X-Request-Id
+日志格式: {"trace_id": "xxx", "message": "...", "timestamp": "..."}
+消息包含: {"trace_id": "xxx", "event_type": "...", "payload": {...}}
+```
+
+### 3.3 Test Owner 检查项
+
+- [ ] 测试验证"跨服务调用时 trace_id 被正确传递"
+- [ ] 测试验证"日志包含 trace_id 字段"
+- [ ] 测试验证"异常日志可通过 trace_id 追溯到原始请求"
+
+---
+
+## 4) 服务间契约管理
+
+### 4.1 契约定义要求
+
+- [ ] 使用 OpenAPI/Proto/AsyncAPI 定义服务契约
+- [ ] 契约文件纳入版本控制
+- [ ] 契约变更需要走兼容性检查
+
+### 4.2 契约测试要求
+
+- [ ] Provider 侧有契约测试（验证实现符合契约）
+- [ ] Consumer 侧有契约测试（验证消费者假设正确）
+- [ ] 契约变更时双方测试都运行
+
+### 4.3 破坏性变更处理
+
+- [ ] 禁止直接删除已发布 API
+- [ ] 新版本与旧版本并行至少 2 个发布周期
+- [ ] 提供迁移指南和弃用时间表
+
+---
+
+## 5) exactly-once 与幂等性
+
+### 5.1 消息处理语义选择
+
+| 语义 | 适用场景 | 实现复杂度 |
+|------|----------|------------|
+| at-most-once | 日志、监控（允许丢失） | 低 |
+| at-least-once | 通知、统计（允许重复） | 中 |
+| exactly-once | 支付、订单（不允许丢失或重复） | 高 |
+
+### 5.2 exactly-once 实现清单
+
+- [ ] 消息包含唯一 `message_id`
+- [ ] 消费者记录已处理的 `message_id`（数据库/Redis）
+- [ ] 重复消息直接返回成功（幂等处理）
+- [ ] 测试覆盖"同一消息消费 3 次，只执行 1 次"
+
+### 5.3 Test Owner 检查项
+
+- [ ] 测试验证"消息重复时不产生重复副作用"
+- [ ] 测试验证"消息丢失时能重试成功"
+- [ ] 测试验证"部分失败时能正确补偿"
+
+---
+
+## 6) 设计文档模板补充
+
+在 `design.md` 的目标架构章节，增加以下小节：
+
+```markdown
+### 微服务设计约束（如适用）
+
+#### 服务依赖图
+- 本服务 → 依赖服务 A（超时 3s，重试 2 次，降级返回空列表）
+- 本服务 → 依赖服务 B（超时 5s，重试 0 次，降级返回缓存）
+
+#### 故障模式与降级
+| 故障场景 | 用户可见行为 | 恢复策略 |
+|----------|--------------|----------|
+| 服务 A 不可用 | 显示"暂无数据" | 熔断 60 秒后重试 |
+| 服务 B 响应慢 | 使用缓存数据 | p99 > 1s 时触发限流 |
+
+#### 链路追踪要求
+- 所有 API 必须传递 `X-Trace-Id`
+- 日志格式：JSON，必须包含 `trace_id`
+```

package/skills/devbooks-design-doc/references//350/256/276/350/256/241/346/226/207/346/241/243/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,189 @@
+# 设计文档提示词
+
+> **角色设定**：你是软件架构领域的**最强大脑**——融合了 Eric Evans（领域驱动设计）、Martin Fowler（企业架构模式）、Gregor Hohpe（企业集成模式）的智慧。你的设计必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"架构设计负责人（Design Owner）"。你的目标是产出一份可验收、可追溯、可演进的《设计文档（Design Doc）》，作为后续编码计划与验收测试的黄金真理（Golden Truth）。
+
+产物落点（目录约定，协议无关）：
+- 该设计文档通常作为单次变更包的一部分，推荐保存为：`<change-root>/<change-id>/design.md`
+- “当前系统真理（Current Truth）”由 `<truth-root>/` 维护；本设计文档描述的是“本次变更应达成什么”（并在归档后合并进真理源）
+- 规格条目（Requirements/Scenarios）不在本文件中展开，交由“规格变更提示词”产出 spec delta（避免 What 与 Requirements 互相污染）
+
+输入材料（由我提供）：
+- 业务/问题背景
+- 现状与约束（如有）
+- 聊天记录
+- 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
+
+任务：
+1) 输出设计文档（不是编码计划、不是代码实现）。
+2) 文档必须达到“可驱动验收、可驱动计划拆解”的颗粒度：清晰边界、契约、红线、验收。
+3) 为避免同源谬误：文档只定义 What/Constraints，不写 How/实现步骤。
+
+输出格式（建议严格遵循）：
+
+> **Lost-in-Middle 优化**：关键信息放开头和结尾，AI 对首尾的召回率（~90%）远高于中间（~50-60%）。
+
+### 第一部分：关键信息前置（High Attention Zone）
+
+1) 标题 + 元信息（版本/状态/更新时间/适用范围/owner/last_verified/freshness_check）
+
+2) **⚡ Acceptance Criteria（验收标准，前置！）**：
+   - 每条以 "AC-xxx" 编号
+   - 每条都要可观察、可验收：明确 Pass/Fail 判据
+   - 必须标注验收方式：A（机器裁判）/ B（工具+人签核）/ C（纯人工）
+   - **这是本文档最重要的部分，必须放在最前面**
+
+3) **⚡ Goals / Non-goals + Red Lines（核心约束，前置！）**：
+   - Goals：本次变更要达成什么
+   - Non-goals：明确不做什么（Out of Scope）
+   - Red Lines：不可破的约束（如：不能破坏向后兼容）
+
+4) 执行摘要（目标与核心矛盾，2-3 句话）
+
+### 第二部分：背景与设计细节（Lower Attention Zone）
+
+5) **Problem Context（问题背景）**：
+   - 为什么要解决这个问题？（业务驱动/技术债/用户痛点）
+   - 当前系统在哪里产生了摩擦或瓶颈？
+   - 若不解决会有什么后果？
+
+6) 价值链映射（Goal → 阻碍/杠杆 → 最小方案；若目标不清晰先追问）
+
+7) 背景与现状评估（现有资产/主要风险）
+
+8) 设计原则（含变化点识别）
+   - **必须识别变化点（Variation Points）**：哪些部分最可能变化？如何封装？
+
+9) 目标架构（Bounded Context、依赖方向、关键扩展点）
+   - **Testability & Seams（可测试性与接缝）**（可选，建议填写）：
+     - **测试接缝（Seams）**：列出设计中预留的测试切入点
+       - 依赖注入点（如：构造器参数、工厂方法）
+       - 可替换组件（如：实现了接口的外部服务适配器）
+       - 可观察点（如：事件发布、日志钩子）
+     - **Pinch Points（汇点）**：预期的高价值测试点
+       - 哪些模块/类是多条调用路径的汇聚点？
+       - 在这些点写测试可覆盖哪些下游路径？
+     - **依赖隔离策略**：
+       - 外部依赖（DB/API/第三方）如何隔离？
+       - 是否需要 Anti-Corruption Layer？
+     - **示例格式**：
+       ```
+       Seams:
+       - OrderService 构造器接受 PaymentGatewayInterface（可注入 Mock）
+       - EventBus.publish() 可被测试订阅者监听
+
+       Pinch Points:
+       - OrderService.processOrder() - 3 条路径汇聚
+       - PaymentGateway.execute() - 2 条路径汇聚
+
+       依赖隔离:
+       - PaymentGateway → 通过接口隔离，测试时用 MockGateway
+       - InventoryDB → 通过 Repository 接口隔离
+       ```
+
+10) **领域模型（Domain Model）**：
+   - **Data Model**：列出核心数据对象，并明确标注类型：
+     - `@Entity`：有唯一标识、可变状态、需要跟踪生命周期的对象（如 Order、Customer）
+     - `@ValueObject`：无标识、不可变、描述性的对象（如 Address、Money、DateRange）
+   - **Business Rules**：独立列出业务规则（不要混在 AC 或代码注释中）
+     - 每条规则有唯一 ID（如 BR-001）
+     - 说明触发条件、约束内容、违反时的行为
+   - **Invariants（固定规则）**：标注 `[Invariant]`，说明必须始终成立的约束
+     - 例如：`[Invariant] 订单总额 = SUM(订单项.金额)`
+     - 例如：`[Invariant] 库存数量 >= 0`
+   - **Integrations（集成边界）**：若涉及外部系统/API，定义 ACL（Anti-Corruption Layer）
+     - 说明外部模型与内部模型的转换点
+     - 标注哪些外部变更会被 ACL 隔离
+
+11) 核心数据与事件契约（Artifacts、Event Envelope、schema_version、idempotency_key、兼容策略）
+
+12) 关键机制（质量闸门/预算化/隔离/回放/审计等）
+
+13) 可观测性与验收（Metrics/KPI/SLO）
+
+14) 安全、合规与多租户隔离
+
+15) 里程碑（设计层面的分阶段交付）
+
+16) Deprecation Plan（如有替换/弃用，必须写清标记/警告/移除窗口）
+
+17) **Design Rationale（设计决策理由）**（可选，大型重构或架构变更时建议填写）：
+   - 为什么选择这个方案而非其他备选方案？
+   - 主要备选方案及其被否决的原因
+   - 关键技术决策及其依据（如：为什么用 Redis 而非 PostgreSQL LISTEN/NOTIFY？）
+
+18) **Trade-offs（权衡取舍）**：
+   - 本设计放弃了什么？（如：放弃强一致性换取高可用）
+   - 接受了哪些已知的不完美？
+   - 哪些场景下本设计可能不适用？
+
+19) **Technical Debt（技术债务，可选）**：
+   - **已知技术债务**：本设计引入或未解决的技术债务
+     - 每条债务有唯一 ID（如 TD-001）
+     - 说明债务类型（架构债务/代码债务/测试债务/文档债务）
+     - 说明产生原因（时间压力/技术限制/权宜之计）
+     - 评估影响范围和严重程度（High/Medium/Low）
+   - **偿还计划**：何时、如何偿还这些债务
+     - 短期可接受的阈值
+     - 触发偿还的条件（如：用户量超过 X、性能低于 Y）
+   - **示例格式**：
+     ```
+     Technical Debt:
+     - TD-001 [Code] 订单服务硬编码了支付超时为30秒
+       - 原因：第一阶段快速验证，未抽取配置
+       - 影响：Medium - 需要改代码才能调整超时
+       - 偿还计划：Phase 2 前移入配置中心
+     - TD-002 [Test] 支付回调缺少集成测试
+       - 原因：Mock 第三方支付网关复杂度高
+       - 影响：High - 回调逻辑变更风险
+       - 偿还计划：搭建沙箱环境后补充
+     ```
+
+20) 风险与降级策略（Failure Modes + Degrade Paths）
+
+### 第三部分：尾部强化（High Attention Zone）
+
+21) **⚡ DoD 完成定义（Definition of Done，尾部强化！）**：
+   - 本设计何时算"完成"？
+   - 必须通过的闸门清单（tests / lint / build / review）
+   - 必须产出的证据（evidence/ 目录内容）
+   - 与开头 AC 的交叉引用
+
+22) Open Questions（<=3）
+
+Acceptance Criteria 写法要求：
+- 每条以 "AC-xxx" 编号
+- 每条都要可观察、可验收：明确 Pass/Fail 判据
+- **非功能需求（NFR）强约束**：
+  - **禁止使用模糊形容词**（如"高性能"、"高可用"、"用户友好"、"很快"）。
+  - **必须转化为可测阈值**（允许使用区间，如 `p99 < 200ms`）或**明确的参照锚点**（如"错误提示组件复用 auth 模块的样式与交互"）。
+  - **百分位数（Percentile）说明**：
+    - `p50`（中位数）：50% 的请求在此时间内完成；反映"典型用户"体验
+    - `p95`：95% 的请求在此时间内完成；反映"大多数用户"体验
+    - `p99`：99% 的请求在此时间内完成；反映"几乎所有用户"体验，暴露长尾延迟
+    - `p999`：99.9% 的请求在此时间内完成；用于高 SLA 场景
+    - **为什么用百分位数而非平均值**：平均值会被极端值拉偏，掩盖真实用户体验。例如：平均 100ms 可能意味着 99% 用户 50ms，1% 用户 5000ms。
+    - **选择建议**：
+      - 用户体验类指标：建议用 p95 或 p99
+      - SLA/合同约束：建议用 p99 或 p999
+      - 内部监控/告警：建议同时监控 p50、p95、p99
+- 必须标注验收方式：
+  - A：机器裁判（tests/静态检查/build/smoke）
+  - B：工具证据+人签核（看板/报表/日志证据）
+  - C：纯人工验收（UX/产品走查）
+- 若不能自动化：写明原因，并给出需要留存的证据类型
+
+限制：
+- 不输出实现步骤、PR 切分建议、生产代码具体文件路径与函数体代码
+- 不输出可运行伪代码；如必须描述算法，只写 Inputs/Outputs/Invariants/复杂度上限/降级策略
+
+补充要求（用于大型项目的“可追溯性”）：
+- 在文档中显式列出本次变更影响的“能力/模块/对外契约”（仅列名称与边界，不写实现）
+- 若涉及对外接口/API/事件/数据结构：必须在“核心数据与事件契约”章节写清楚版本化策略（schema_version、兼容窗口、迁移/回放原则）
+- 若涉及架构边界变化：在“目标架构”章节增加一个 **C4 Delta（可选）** 小节：说明 C1/C2/C3 哪些元素被新增/修改/移除（不要求画完整图；完整图由架构地图维护）
+
+现在开始输出该《设计文档》Markdown，不要输出额外解释。

package/skills/devbooks-design-doc/references//351/232/220/347/247/201/345/220/210/350/247/204/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,240 @@
+# Telemetry 隐私合规检查项
+
+借鉴 VS Code 的 `telemetry.instructions.md`，本文档定义了埋点/遥测数据的隐私合规要求。
+
+---
+
+## 1) GDPR 分类要求
+
+当 design.md 或 spec-delta 涉及埋点时，**必须**填写以下字段：
+
+```markdown
+## Telemetry / 埋点设计
+
+### GDPR Classification
+
+| 字段 | 值 | 说明 |
+|------|-----|------|
+| **owner** | @username | 数据所有者（必须是团队成员） |
+| **isMeasurement** | true/false | 是否为度量数据（非 PII） |
+| **purpose** | PerformanceAndHealth / BusinessInsight / FeatureInsight | 收集目的 |
+| **classification** | SystemMetaData / CallstackOrException / EndUserPseudonymizedInformation | 数据类型 |
+| **retention** | 90d / 1y / permanent | 数据保留期限 |
+| **gdprRequired** | true/false | 是否需要用户同意 |
+
+### 埋点事件定义
+
+| 事件名 | 触发时机 | 数据字段 | 分类 |
+|--------|----------|----------|------|
+| feature.used | 用户使用功能 X 时 | `{ featureId, duration }` | SystemMetaData |
+| error.occurred | 发生异常时 | `{ errorCode, stack }` | CallstackOrException |
+```
+
+---
+
+## 2) 数据分类说明
+
+### SystemMetaData（系统元数据）
+
+**定义**：不涉及用户身份的系统信息
+
+**允许收集**：
+- 操作系统版本
+- 应用版本
+- 功能开关状态
+- 性能指标（延迟、内存）
+- 匿名的使用频率
+
+**示例**：
+```typescript
+// 合规：系统元数据
+telemetry.log('app.startup', {
+  version: '1.0.0',
+  os: 'darwin',
+  memoryUsage: process.memoryUsage().heapUsed,
+});
+```
+
+### CallstackOrException（调用栈或异常）
+
+**定义**：错误信息和调用栈
+
+**允许收集**：
+- 错误代码
+- 错误消息（需脱敏）
+- 调用栈（需脱敏文件路径）
+
+**脱敏要求**：
+- 移除用户名：`/Users/john/` → `/Users/<username>/`
+- 移除项目路径：`/project/secret/` → `<project>/`
+- 移除敏感文件名：`credentials.json` → `<sensitive>`
+
+**示例**：
+```typescript
+// 合规：脱敏后的异常
+telemetry.logError('app.error', {
+  errorCode: 'E001',
+  message: sanitizeMessage(error.message),
+  stack: sanitizeStack(error.stack),
+});
+```
+
+### EndUserPseudonymizedInformation（终端用户假名化信息）
+
+**定义**：经过假名化处理的用户信息
+
+**要求**：
+- 必须使用单向哈希
+- 不可逆向还原
+- 需要用户同意
+
+**示例**：
+```typescript
+// 合规：假名化用户 ID
+telemetry.log('user.action', {
+  hashedUserId: sha256(userId + salt), // 单向哈希
+  action: 'click',
+});
+```
+
+### PublicNonPersonalData（公开非个人数据）
+
+**定义**：完全公开、不涉及任何个人信息的数据
+
+**允许收集**：
+- 公开的配置选项
+- 公开的 API 版本
+- 公开的功能列表
+
+---
+
+## 3) 禁止收集的数据
+
+| 类型 | 示例 | 原因 |
+|------|------|------|
+| 明文 PII | 姓名、邮箱、电话 | 直接识别用户 |
+| 位置信息 | GPS、IP 地址 | 间接识别用户 |
+| 文件内容 | 用户文档、代码 | 敏感数据 |
+| 密码/令牌 | API keys、密码 | 安全风险 |
+| 健康信息 | 医疗数据 | 敏感数据 |
+| 财务信息 | 银行卡号 | 敏感数据 |
+
+**检测规则**：
+```bash
+# 检测可能的 PII 收集
+rg "email|phone|name|address|ip" --type ts -g "*telemetry*"
+rg "password|token|secret|key" --type ts -g "*telemetry*"
+```
+
+---
+
+## 4) 事件命名规范
+
+### 常规事件（publicLog2）
+
+用于正常的功能使用和性能度量：
+
+```typescript
+// 命名格式：<domain>.<action>
+publicLog2<{ duration: number }>('editor.opened', { duration: 123 });
+publicLog2<{ count: number }>('search.performed', { count: 10 });
+```
+
+### 异常事件（publicLogError2）
+
+用于错误和异常情况：
+
+```typescript
+// 命名格式：<domain>.error 或 <domain>.failed
+publicLogError2<{ code: string }>('editor.error', { code: 'E001' });
+publicLogError2<{ reason: string }>('save.failed', { reason: 'disk_full' });
+```
+
+---
+
+## 5) Code Review 检查清单
+
+当审查涉及埋点的代码时：
+
+### 必须检查
+
+- [ ] **GDPR 分类是否完整？**
+  - owner 是否指定？
+  - classification 是否正确？
+  - purpose 是否明确？
+
+- [ ] **数据是否脱敏？**
+  - 文件路径是否移除用户名？
+  - 错误消息是否过滤敏感信息？
+  - 是否存在明文 PII？
+
+- [ ] **命名是否规范？**
+  - 事件名是否符合 `<domain>.<action>` 格式？
+  - 错误事件是否使用 `publicLogError2`？
+
+- [ ] **用户同意是否处理？**
+  - 需要同意的数据是否检查了 `telemetryLevel`？
+  - 是否尊重用户的隐私设置？
+
+### 自动化检查
+
+```bash
+# 检查是否有未分类的埋点
+rg "publicLog2|telemetry\.log" --type ts | xargs -I {} grep -L "classification" {}
+
+# 检查是否收集敏感数据
+rg "(email|phone|password|token)" --type ts -g "*telemetry*"
+```
+
+---
+
+## 6) design.md 模板
+
+当 design.md 涉及埋点时，添加以下章节：
+
+```markdown
+## Telemetry Impact
+
+### 新增埋点事件
+
+| 事件 | owner | classification | purpose | isMeasurement |
+|------|-------|----------------|---------|---------------|
+| feature.x.used | @alice | SystemMetaData | FeatureInsight | true |
+| feature.x.error | @alice | CallstackOrException | PerformanceAndHealth | false |
+
+### 数据字段定义
+
+```typescript
+interface FeatureXUsedEvent {
+  duration: number;        // 使用时长（ms）
+  success: boolean;        // 是否成功
+  // 禁止添加: userId, filePath, etc.
+}
+```
+
+### 隐私影响评估
+
+- [ ] 不收集 PII
+- [ ] 已脱敏敏感路径
+- [ ] 已检查 telemetryLevel 设置
+- [ ] 已获得 Privacy Review（如需要）
+```
+
+---
+
+## 7) 合规审批流程
+
+| 数据类型 | 审批要求 |
+|----------|----------|
+| SystemMetaData | 无需审批 |
+| CallstackOrException | 无需审批（需脱敏） |
+| EndUserPseudonymizedInformation | 需要 Privacy Review |
+| 任何新的 PII | 需要 Legal Review |
+
+---
+
+## 参考资料
+
+- [GDPR 数据分类指南](https://gdpr.eu/data-protection/)
+- [VS Code Telemetry 文档](https://code.visualstudio.com/docs/getstarted/telemetry)
+- [Microsoft Privacy Statement](https://privacy.microsoft.com/)