更新日志

本文件记录 HealthGuard 的所有重要变更。

格式基于 Keep a Changelog， 版本号遵循 语义化版本。

[Unreleased]

2026-10-27：Android / Flutter 稳定设备标识（SDK 源码 0.3.0）

Flutter 源码 0.3.0 从原生 Android ID 生成应用/项目作用域的 SHA-256 脱敏标识，独立于安装与会话标识；异常与失败请求统一携带状态、来源、作用域、设备/系统和 App/SDK 版本。缺失时标为“未获取”，不以随机值或型号冒充稳定标识。Dashboard 分别统计稳定标识、安装标识和无法识别记录，支持短码/型号搜索、分页及跨版本异常历史；邮件显示触发事件短码和版本，App 可嵌入设备诊断页。历史不回填或按型号合并。Android 5–7、恢复出厂、用户/签名/应用作用域变化和旧系统升级限制明确记录；不能宣称永久唯一。Collector/Dashboard 和接入 App 已完成发布验证；SDK 仍以固定 Git 源码接入，未发布 pub.dev。每个自托管环境仍需自行升级；目标平板重装/清数据与真实邮件对照另验。

2026-10-26：区分事件接收与邮件时间（待部署）

客户端发生、服务器接收、邮件生成、发送处理开始和邮件服务器接受时间独立展示。事件详情与 AI 报告显示发生/接收之差，并提示补报、传输延迟或设备时钟偏差的可能性，不能据此认定当前版本刚出故障。新增接收时间由服务器记录，客户端不可覆盖；重复上报保留首次接收。旧记录缺失值不推算，测试邮件的事件时间不适用。需更新 Collector 与 Dashboard，无需升级 SDK/App；真实收件另验。

2026-10-26：邮件标题显示错误 ID（待部署）

• 自动告警标题改为 [HealthGuard][完整 Issue ID] 提醒类型 · 项目名，在邮件列表前部即可区分错误。
• 同一问题的新异常、复发和次数阈值提醒使用相同 ID；保留完整编号，避免与单次事件 ID 混淆。
• 仅需更新 Collector，业务 App 与 SDK 无需升级。已排队、历史邮件和测试邮件保持原标题；真实收件与服务端上线另行验收。

手动确认归档与备注

兼容保留的修复、验证及 PR 写接口也会校验项目所有权，避免通过旧接口绕过归档权限。

点击「归档」会弹出确认框，可填写归档备注（选填，最多 4000 字），确认后直接归档，不再要求修复或验证版本。取消或按 Escape 不会提交，失败会保留备注供重试。在「已归档」中可查看备注和归档时间，也可手动恢复到当前列表；恢复后保留上次备注。归档不表示已修复，后续上报继续计数并保持手动归档。修复由外部 AI/开发工具在业务仓库完成，页面保留「复制给 AI」，不再展示开始修复、版本验证、PR 表单或修复状态标签。列表和详情隐藏内部编号与指纹。

筛选与搜索控件细节

下拉箭头统一向内留出 12px，文字预留 36px，选择器与日期控件等高并保留清晰的键盘焦点。搜索框移至 Issues 标题右侧，同一行展示，去掉与状态标签数字重复的分组总数；搜索与筛选规则不变。

项目详情更紧凑

移除内容区重复的项目标题和说明，操作与筛选共用一排工具栏；统计名称和数字用小字号同行展示。状态筛选使用紧贴 Issue 列表上沿的下划线标签页，减少顶部空白。窄屏工具栏可换行，统计保持单排并可横向滚动，错误内容继续完整显示。 HTTP 事件卡片也会在窄详情栏中换行，避免撑宽页面。

Issue 元信息靠右

Issue 列表的状态、平台和时间整体靠右排列，类型和事件次数保留左侧；错误标题仍完整换行。窄列表及手机宽度下，右侧信息组会自动换行。

2026-10-15：Cloudflare 发布配置读取修复

• 发布脚本跳过凭据说明中的示例变量，只读取实际 Account ID、API Token 和 DNS Token，兼容 Markdown 格式。
• 增加配置解析回归用例；不改变现有显式环境变量的优先级。

HTTP 标题显示完整地址

打开历史 HTTP 错误详情后，标题会从对应事件中补全真实请求域名、路径及非敏感查询参数，并保留完整错误内容；选中的列表项和 AI 报告同步。长地址自动换行。缺少绝对地址或方法、路径不匹配时保留历史摘要，不猜测域名。仅更新展示，不改变分组、修复和归档状态。

2026-10-15：归档反馈与可读性

• 保留验证后归档的门槛，未满足时点击会明确提示原因；归档/恢复成功及请求失败均有可见反馈。
• 操作按钮统一高度；列表和详情隐藏错误指纹与内部 Issue 编号，内部归组和 AI 报告仍保留必要标识。

2026-10-15：HTTP 故障分组与 Flutter 原请求证据（未发布）

• 新 HTTP Issue 按目标服务、环境和实际故障阶段分组；连接、发送、接收超时及明确 DNS 错误不再混合。请求编号、查询参数与耗时不参与分组。
• 邮件以触发事件为主，历史摘要单独标注；页面和 AI 报告同步展示原始 Dio 类型、请求编号、探测采样时间和缓存标记。
• 旧事件晚到及启动回填不会把最新摘要和版本退回旧值。保留历史 Issue ID 与修复关联；历史混合问题不自动拆分，新上报进入 v2 分组。
• Flutter SDK 源码 0.2.1 新增可选 IO adapter，记录原请求连接取得与响应头等待，冻结超时证据并中止迟到连接；沿用原连接池、代理及证书校验。
• 原请求 DNS/TCP/TLS 子阶段仍明确不可用，独立探测不能补作原请求耗时。未发布 pub.dev；Collector/Dashboard、官网部署、业务 App 打包和真机验收分别执行。

2026-10-15：先浏览列表，再展开详情

• 未选择 Issue 时隐藏详情区，列表占满宽度，每条问题独占一行，错误信息完整换行显示，类型、次数、状态、平台和时间等信息单独放在下一排。
• 点击问题后展开详情，「收起详情」恢复完整列表；筛选和切换项目清除选择，关闭后的旧请求不会重新打开详情。
• 手机端单列浏览，选中后滚动至详情，收起后恢复卡片焦点。无 API、存储或 SDK 变化。

2026-10-15：Flutter SDK 0.2.0 统一详细网络诊断（未发布源码）

• 请求编号、快照、网络切换事件、并发计数及受控分阶段探测统一到 SDK，业务 App 可删除重复实现。
• Android 基础与详细采集共用一个监听器；主动探测默认关闭，需显式 HTTPS/443 域名白名单及安全健康检查路径。
• 主动取消不告警；原始错误、故障时间、采样时间和补传身份继续保留。
• SDK 30 项测试与静态分析通过。源码提交 b9ad8bea6afcee848c99e67a8f141faa17a52fd3，未发布 pub.dev，未因此部署 Collector/Dashboard 或重新发布业务 App；真机验收另行执行。

2026-10-15：品牌区返回首页

• 左上角 Logo、HealthGuard 标题和账号区域共用首页链接；从详情页点击即可返回项目列表。
• 支持键盘 Tab/Enter 与可见焦点，适配子目录部署；未登录时保持登录入口，无需 SDK 或业务 App 更新。

2026-10-15：Dashboard 品牌 Logo

• 登录页、项目列表和详情页的品牌标题新增与官网一致的 HealthGuard Logo，并补齐浏览器标签页图标。
• 资源路径适配子目录部署；桌面与手机宽度的加载和对齐已验证。本次仅调整品牌显示，无需 SDK 或业务 App 更新。

2026-10-15：项目重命名

• 项目列表与详情页侧栏新增「改名」，位于标题右侧；长标题单行省略并可悬停查看全文，支持中文名称、取消和失败重试。
• 仅项目所有者可修改名称；1–100 字符，去除首尾空白。项目标识、SDK 配置、历史事件/Issue 与通知规则保持不变。
• 新增 PATCH /api/apps/:appKey，无需数据库迁移或客户端 SDK 升级。源码与目标环境部署分别验收。

2026-10-14：Flutter SDK 0.1.1 集成兼容（源码更新）

• 支持原故障时间、环境、设备信息和稳定指纹，保留请求编号及受限诊断证据。
• 显式允许的业务标量字段可保留，凭据和嵌套业务载荷仍被过滤；补充旧队列与安装身份迁移说明。
• 7 项 Flutter 测试通过，SDK 行覆盖率 83.3%；Dart 静态检查通过。固定 Git 提交 1e95665f978f4347120c969a9771bbc64531cdca 接入，尚未发布 pub.dev，也未因此部署 Collector/Dashboard。
• SDK 接入与迭代记录已同步源码；官网线上状态另行验收。

2026-10-14：网络诊断 SDK 复用（源码已完成，未发布）

• Web、小程序和 uni-app SDK 准备版本 0.4.0：统一失败分类、字段白名单、每域限频、离线补传，以及上传确认应答检查。
• 新增独立 Flutter/Dio SDK 源码 0.1.0 与 Android 网络状态插件；保留 native 异常上报，提供有上限的持久化队列。
• Collector 按事件 ID 去重，避免补传重复计数或主键冲突；Dashboard、AI 报告和告警邮件统一展示本次事件的诊断证据。
• 浏览器或平台取不到的网络状态、DNS/连接/TTFB 耗时标为不可用；普通 Failed to fetch 保留原因未知，不据此判定 DNS/TLS/CORS 故障。
• 验证：183 项 TypeScript 和 4 项 Flutter 测试通过，构建与检查通过；另有 2 项数据库服务集成测试未配置环境而跳过。

发布状态： 此记录对应主项目提交 38cc9e2。npm/pub.dev 发布、服务器部署、业务 App 迁移及真机切网尚未完成，不能仅升级包版本就视为已上线。Flutter 当前可通过 Git/path 引入源码；新增 JS 选项需使用包含本次实现的 SDK，而非默认安装旧 registry 版本。

接入与限制见 网络诊断 和 Flutter SDK。

[0.3.0] - 2026-06-18

新增

• 新增 @health-guard/repair-agent 包：扫描项目 SDK 配置，登录 HealthGuard 并拉取 issue 列表/详情，支持本地源码关键词匹配。

修复

• SDK transport 失败后增加退避重试（transportFailureRetryDelayMs，默认 30s），失败事件回队并支持手动 flush() 强制上报。
• sdk-uniapp 与 sdk-miniprogram 对齐 sdk-web 的退避重试行为。

变更

• 公共 npm 包版本统一提升至 0.3.0。

[0.2.0] - 2026-06-09

新增

• 手动修复任务功能（Repair Task Phase 1）
  • 支持从 Issue 创建修复任务，选择 Agent（Hermes / Codex / Claude Code / 手动）
  • 任务状态流转：pending → claimed → running → pr_created → closed
  • Dashboard 修复任务列表、详情页、取消操作
  • PostgreSQL 持久化修复任务数据和进度笔记
  • 认证 API 和 Agent API 分离设计
• Issue 管理和筛选功能
• Issue ID 缩短显示 + 复制给 AI 按钮
• Dashboard 侧边栏显示版本号
• 支付宝小程序监控上下文补全
• Issue 详情页缺失的 CSS 样式和国际化文案

修复

• 防止 SDK transport 失败时的无限递归错误循环
• 移除未使用的 reactive import

文档

• 修复任务工作流设计文档（中英文）
• 修复任务 Phase 1 实施计划

[0.1.0] - 2026-05-01

新增

• H5/Web SDK（@health-guard/sdk-web）
  • JavaScript 错误自动捕获
  • HTTP 请求失败监控（fetch + XHR）
  • Promise rejection 捕获
  • 性能指标采集
• 微信小程序 SDK（@health-guard/sdk-miniprogram）
  • 运行时错误捕获
  • Promise rejection 捕获
  • wx.request 请求监控
  • 页面生命周期面包屑
• uni-app 多端 SDK（@health-guard/sdk-uniapp）
  • 支持 H5、微信、支付宝、抖音、App 等平台
  • 自动检测运行环境并适配
  • 设备信息和页面 URL 检测
• Dashboard 前端（Vue 3 + Vite）
  • 项目管理（创建、查看、SDK 接入指南）
  • 总览页面（事件统计、错误率、失败请求）
  • Issue 列表（聚合去重、平台筛选、时间筛选）
  • Issue 详情（堆栈跟踪、面包屑、事件时间线）
  • 中英文自动检测 + 手动切换
• Server 后端（Node.js + Fastify）
  • 事件批量采集 API
  • Issue 聚合和分页查询
  • 本地认证（注册/登录，会话 Token）
  • 用户级项目隔离
• PostgreSQL 持久化
  • 连接池（pg.Pool）
  • 批量 INSERT 优化
  • 时间戳索引
  • 自动数据清理
• Docker 一键部署
  • docker-compose.yml（PostgreSQL + Server + Dashboard）
  • 健康检查端点
  • 部署文档
• 安全加固
  • 所有查询端点认证保护
  • nanoid ID 生成
  • 优雅关闭（SIGTERM/SIGINT）
  • 速率限制和 CORS

文档

• README（中英文）
• 运维指南
• AI CLI 操作手册
• 运营商指南