From 612cccecb7828000f2852625d005a35a4a84c03c Mon Sep 17 00:00:00 2001 From: chenchen Date: Wed, 10 Jun 2026 13:38:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(telemetry):=20production=20enablement=20ch?= =?UTF-8?q?ecklist=20=E5=AE=9A=E7=A8=BF=20(#44)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #44 的「生产开启 telemetry 前置 checklist 定稿」工程交付: docs/integration/telemetry-production-enablement-checklist.md。 涵盖:① 代码侧控制核验(默认 off/410、白名单 #42、8KiB 上限、保留期 #43、服务端脱敏、 不计费)② 生产配置确认(HEICODE_TELEMETRY_ENABLED/RETENTION_DAYS 等)③ 隐私/法务 签字硬前置(设备 ID 可关联账号披露 + 法务签字,owner=文档/合规,口径 @Fasthei;跟踪 #34) ④ 上线/回滚验证(410 基线→开启→抽查脱敏→回滚演练)⑤ 结论门。docs README 已索引。 完成 #44 的 checklist 定稿 DoD;隐私披露(#34)与法务签字仍是开启的人工前置。Docs only。 Co-Authored-By: Claude Opus 4.8 --- docs/README.md | 1 + ...lemetry-production-enablement-checklist.md | 53 +++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/integration/telemetry-production-enablement-checklist.md diff --git a/docs/README.md b/docs/README.md index bb2a31f6..60ac4fc8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ | [`integration/heicode-desktop-client-api.md`](./integration/heicode-desktop-client-api.md) | 桌面客户端对接 HM（模板 Agent 模型），已生产验证 | | [`integration/heicode-am-contract.md`](./integration/heicode-am-contract.md) | HM ↔ AM（agent_management）接口契约 | | [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md) | **蜂群（Swarm）现状裁定与后续跟踪入口**：HM 当前不实现 swarm runtime，旧 sub/蜂群文档作废后的上下文迁移映射与归属（AM/Swarm 侧） | +| [`integration/telemetry-production-enablement-checklist.md`](./integration/telemetry-production-enablement-checklist.md) | **客户端错误遥测生产开启前置 Checklist（#44 定稿）**：代码侧控制核验、生产配置、隐私/法务签字硬前置、上线/回滚验证；开启 `HEICODE_TELEMETRY_ENABLED` 前必过 | | [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agent / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 | 旧 Agent API 草案、旧 sub / 蜂群任务编排、旧里程碑、旧架构说明和旧上手材料不再作为实施依据（相关文档已删除）。**蜂群相关文档的作废/迁移映射与「HM 不实现 swarm runtime、新能力归 AM/Swarm 侧跟踪」的结论见 [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md)（删除≠丢上下文，迁移到此追踪入口）。** 当前实施模型以 `heicode.md`、`plan.md` 与 `integration/heicode-hm-template-agent-model.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。 diff --git a/docs/integration/telemetry-production-enablement-checklist.md b/docs/integration/telemetry-production-enablement-checklist.md new file mode 100644 index 00000000..edfb374d --- /dev/null +++ b/docs/integration/telemetry-production-enablement-checklist.md @@ -0,0 +1,53 @@ +# 客户端错误遥测 — 生产开启前置 Checklist（定稿） + +> 工单：#44（拆分自 #32 EPIC）· 状态：**工程项已就绪;开启仍需法务/产品签字** +> 适用：把 `HEICODE_TELEMETRY_ENABLED` 从默认 `false` 翻到 `true` 之前的强制检查清单。 + +## 0. 一句话 + +遥测**默认关闭**(摄入端点回 410 kill switch)。在本清单**全部勾选**前,生产 **不得** 开启;尤其是 §3 的法务/产品签字是硬前置——工程已把代码侧防线做齐,但「设备 ID 可关联账号」属隐私敏感,必须先如实披露。 + +## 1. 代码侧控制（已实现，可现场核验） + +| 控制 | 实现 | 核验方式 | +|---|---|---| +| 默认关闭 + kill switch | `HEICODE_TELEMETRY_ENABLED` 默认 `false`,关时摄入端点返回 **410** | `GET /api/heicode/config` → `telemetry.enabled=false`;`POST /api/heicode/telemetry/events` → 410 | +| 不计费、不进 consume log | 独立 `telemetry_events` 表,摄入不写消费日志/不动 quota | 代码 `controller/heicode_telemetry.go`;开启后抽查无 consume log | +| 仅设备配对可上送 | 需 V2 设备签名 + `X-Heicode-Device-Id`;会话-only 拒绝(403) | 无设备头请求 → 403 | +| 批量/尺寸限制 | 顶层数组 1–20 条、≤256KB | 超限 → 413 | +| context 字段白名单（#42） | 仅 `route/retryable/phase/exit_code/duration_ms/attempt`,其余键丢弃 | `TestFilterTelemetryContext_Whitelist` | +| 单字段尺寸上限 | `stack_top`/`context` 脱敏后截断 8KiB | `TestCapTelemetryField` | +| 服务端二次脱敏 | `stack_top`/`context` 剥离 sk-/Bearer/URL token/JSON 密钥字段 | `TestTelemetryToModel_RedactsSecrets` | +| 数据保留期（#43） | `HEICODE_TELEMETRY_RETENTION_DAYS`(默认 30)+ master-only 每日清理 | `GET /api/heicode/config` → `retention_days`;`TestDeleteTelemetryEventsBefore` | + +**禁止采集(白名单已强制)**:prompt、代码正文、token、邮箱、完整文件路径、用户名路径、IP 原文等可识别信息——非白名单 `context` 键一律丢弃 + 服务端脱敏兜底。 + +## 2. 生产配置确认（开启时设置 + 复核） + +- [ ] `HEICODE_TELEMETRY_ENABLED=true`（仅在 §3 全部完成后） +- [ ] `HEICODE_TELEMETRY_RETENTION_DAYS` 已确认(建议 ≤90;默认 30) +- [ ] `HEICODE_TELEMETRY_RETENTION_INTERVAL_HOURS` 已确认(默认 24) +- [ ] 仅 master 节点跑清理任务(`IsMasterNode`,已在 `main.go` 内置) +- [ ] `GET /api/heicode/config` 返回的 `telemetry` 块与上述配置一致 + +## 3. 隐私 / 法务前置（硬性，开启的真正闸门） + +> 这一节不是工程能独立完成的;**owner = 文档 owner + 合规/法务**,口径 @Fasthei。 + +- [ ] **heicodeDocs 隐私文档如实披露**「客户端错误遥测;**设备 ID 可关联账号、非匿名**;采集范围(崩溃类别/错误码哈希/脱敏调用栈/运行环境);保留期;不采集 prompt/代码/token/邮箱/完整路径/IP 原文」(跟踪：#34，草案已在 #34 给出) +- [ ] **法务 / 产品确认并签字**(在 #44 或 #34 留确认记录 + 责任人 + 链接) +- [ ] 隐私文档**已发布上线**(用户可见),且与实际采集行为一致(`法律声明.md`「隐私披露必须与真实采集行为一致」) + +## 4. 上线 / 回滚验证（开启当次执行） + +- [ ] 开启前:`POST /api/heicode/telemetry/events` 返回 **410**(确认 kill switch 基线) +- [ ] 开启后:客户端真实上送一批 → `200 {accepted:n}`,落 `telemetry_events` 表 +- [ ] 抽查入库行:`stack_top`/`context` 已脱敏;`context` 仅白名单键;无 prompt/邮箱/路径/IP +- [ ] 确认**无** consume log / quota 变化(遥测不计费) +- [ ] **回滚演练**:把 `HEICODE_TELEMETRY_ENABLED` 改回 `false` → 端点回 410、客户端停送(kill switch 可用) +- [ ] 保留期清理任务在日志中可见(`secret/telemetry retention task started`) + +## 5. 结论门 + +**只有 §1 已核验 + §2 已确认 + §3 全部签字 + §4 验证通过,才允许在生产保持 `HEICODE_TELEMETRY_ENABLED=true`。** +任一项不满足 → 维持默认关闭(410)。本清单作为 #44 的「checklist 定稿」交付;§3 的法务签字仍是开启的人工前置。