docs: 新增 checker-observation 变更提案，归档历史 openspec 变更记录

openspec/changes/checker-observation/tasks.md

@@ -0,0 +1,56 @@
+## 1. 共享类型与接口变更
+
+- [ ] 1.1 修改 `src/shared/api.ts` 中 CheckResult 类型：移除 statusDetail，新增 detail 和 observation 字段
+- [ ] 1.2 修改 `src/server/checker/types.ts` 中 StoredCheckResult 类型：status_detail 替换为 observation
+- [ ] 1.3 修改 `src/server/checker/runner/types.ts` 中 CheckerDefinition 接口：新增 buildDetail 方法
+
+## 2. 存储层适配
+
+- [ ] 2.1 修改 `src/server/checker/store.ts` 中 check_results 表 DDL：status_detail 列替换为 observation TEXT 列
+- [ ] 2.2 修改 `src/server/checker/store.ts` 中 insertCheckResult 方法：写入 observation（JSON.stringify）替代 statusDetail
+- [ ] 2.3 修改 `src/server/checker/store.ts` 中 getHistory、getLatestCheck、getLatestChecksMap 读取类型：返回 observation 字段替代 status_detail
+- [ ] 2.4 修改 `src/server/checker/engine.ts` 中 writeResult 方法：传递 observation 替代 statusDetail，异常兜底结果 observation 为 null
+
+## 3. Checker execute 改造（返回 observation 替代 statusDetail）
+
+- [ ] 3.1 改造 HTTP checker execute.ts：组装 observation 对象（statusCode/headers/bodyPreview/contentType/contentLength），拿到响应后始终采集 bodyPreview，移除 statusDetail 赋值
+- [ ] 3.2 改造 TCP checker execute.ts：组装 observation 对象（connected/connectTimeMs/banner/error），移除 statusDetail 赋值和 buildStatusDetail 函数
+- [ ] 3.3 改造 UDP checker execute.ts：组装 observation 对象（responded/responseSize/responsePreview/sourceAddress/sourcePort/error），移除 statusDetail 赋值和 build*Detail 函数
+- [ ] 3.4 改造 ICMP checker execute.ts：组装 observation 对象（复用 PingStats 字段 + error），移除 statusDetail 赋值和 buildStatusDetail 函数
+- [ ] 3.5 改造 DB checker execute.ts：组装 observation 对象（connected/rowCount/rowsPreview/error），移除 statusDetail 赋值
+- [ ] 3.6 改造 CMD checker execute.ts：组装 observation 对象（exitCode/stdoutPreview/stderrPreview/error），移除 statusDetail 赋值
+- [ ] 3.7 改造 LLM checker types.ts 和 observation.ts：保留执行期完整 outputText，新增持久化 observation 派生结构（outputPreview/outputLength/截断 headers）
+- [ ] 3.8 改造 LLM checker execute.ts：返回持久化 observation，继续用执行期 LlmCheckObservation 执行 expect，移除 buildStatusDetail 函数
+
+## 4. Checker buildDetail 实现
+
+- [ ] 4.1 为 HTTP checker 实现 buildDetail 方法：返回 `"HTTP {statusCode}"` 格式
+- [ ] 4.2 为 TCP checker 实现 buildDetail 方法：返回连接状态和 banner 摘要
+- [ ] 4.3 为 UDP checker 实现 buildDetail 方法：返回响应状态和大小摘要
+- [ ] 4.4 为 ICMP checker 实现 buildDetail 方法：返回存活状态、平均延迟和丢包率摘要
+- [ ] 4.5 为 DB checker 实现 buildDetail 方法：返回连接状态或行数摘要
+- [ ] 4.6 为 CMD checker 实现 buildDetail 方法：返回 `"exitCode={N}"` 格式
+- [ ] 4.7 为 LLM checker 实现 buildDetail 方法：返回 provider/mode/status/finish/output/usage 摘要
+
+## 5. API 序列化层适配
+
+- [ ] 5.1 修改 `src/server/helpers.ts` 中 mapCheckResult：接收 type 参数，反序列化 observation，observation 为 null 时 detail 为 null，否则调用 buildDetail 动态构造 detail
+- [ ] 5.2 修改 `src/server/routes/dashboard.ts`：传递 target.type 给 mapCheckResult
+- [ ] 5.3 修改 `src/server/routes/history.ts`：传递 target.type 给 mapCheckResult
+
+## 6. 前端适配
+
+- [ ] 6.1 修改 `src/web/constants/history-table-columns.tsx`：statusDetail 引用改为 detail
+- [ ] 6.2 修改 `src/web/components/OverviewTab.tsx`：statusDetail 引用改为 detail
+
+## 7. 测试与质量保障
+
+- [ ] 7.1 更新所有涉及 CheckResult 的现有测试，适配 statusDetail → detail + observation 字段变更
+- [ ] 7.2 为各 checker 的 buildDetail 方法编写单元测试
+- [ ] 7.3 更新 CheckerDefinition mock、store、engine、dashboard/history API、前端组件与 constants 的测试 fixture
+- [ ] 7.4 为 mapCheckResult 编写 observation JSON parse、null observation、unknown type 或 malformed observation 的覆盖测试
+- [ ] 7.5 执行完整测试套件、代码检查和格式检查，确保无回归
+
+## 8. 文档更新
+
+- [ ] 8.1 更新 README.md 和/或 DEVELOPMENT.md，反映 CheckResult 类型变更和 observation 机制