---
name: structured-logging
description: "设计结构化日志方案。在功能会产生运行时数据时，brainstorming 之后、writing-plans 之前必须调用。设计表结构、定义基线指标、注册到 Wiki。"
argument-hint: "[功能描述]"
---

# Structured Logging

## Overview

为即将开发的功能设计结构化日志方案。确定需要记录什么数据、如何记录、如何评估。

**核心原则：** 没有日志方案就不能开始编码。所有会产生运行时数据的功能，必须先设计日志再写实现。

## 触发时机

SOP Phase 1 中，brainstorming 产出 design 之后、writing-plans 之前。

## 前置条件

- `research-wiki/` 目录存在
- `core/eval/` 存在（SqliteRunStore 库）
- brainstorming 已产出 design 实体

## 执行流程

### Phase 1: 读取现有 Schema

1. 列出 `research-wiki/schemas/` 下所有已有 schema 实体
2. 如果 `results/harness.db` 存在，查询 `SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '_%'` 获取实际表列表
3. 对比 Wiki 记录与实际表结构，标记不一致之处

### Phase 2: 设计日志方案

基于 brainstorming 产出的 design，回答以下问题：

1. **这个功能会产生什么运行时数据？**
   - OCR 置信度（每张影像/字段的识别置信度）
   - 提取信度一致率（多次提取/多专家的一致性）
   - 阶段事件（开始/结束/错误/警告）
   - 门控结果（期望张数、完整性校验）
   - token 用量与时延（LLM 调用成本与延迟）

2. **需要新建表还是复用现有表？**
   - 如果现有表能覆盖 → 复用，不新建
   - 如果需要新维度 → 新建表

3. **每张表的 schema 是什么？**
   - 列名、类型、说明
   - 主键（如果有）
   - 哪些列用于 agent 查询诊断

4. **在代码哪些位置埋点？**
   - 具体函数名、具体代码节点
   - 用 `log.insert()` 还是 `log.log_event()`

### Phase 3: 定义评估基线

1. **硬性指标**：列出每个可量化的指标、阈值、判定方式
2. **语义指标**：列出需要 LlmJudge 评估的维度
3. **基线来源**：指明对比哪个历史 run_id（如果是首次，标记为"待首次运行后建立"）

### Phase 4: 注册到 Wiki

1. 对每张新表，执行：
   ```bash
   python3 .claude/tools/research_wiki.py add_entity research-wiki/ --type schema --id <table-name> --title "表结构: <table-name>"
   ```
   然后在生成的 md 文件中填入完整的列定义和埋点位置。

2. 对每组基线指标，执行：
   ```bash
   python3 .claude/tools/research_wiki.py add_entity research-wiki/ --type metric --id <metric-name> --title "<指标描述>"
   ```
   然后在生成的 md 文件中填入基线值、阈值、判定方式。

3. 建立关联：
   ```bash
   python3 .claude/tools/research_wiki.py add_edge research-wiki/ --from "metric:<id>" --to "schema:<id>" --type measures --evidence "..."
   python3 .claude/tools/research_wiki.py add_edge research-wiki/ --from "schema:<id>" --to "design:<id>" --type implements --evidence "..."
   ```

4. 重建索引：
   ```bash
   python3 .claude/tools/research_wiki.py rebuild_index research-wiki/
   ```

### Phase 5: 产出

交给 writing-plans 的输入：
- 哪些文件需要 `from core.eval.run_store import SqliteRunStore`
- 哪些函数需要在什么位置调用 `log.insert()` / `log.log_event()`
- 这些埋点必须作为 writing-plans 中的显式步骤，不得遗漏

## 产出物清单

| 产出 | 位置 | 说明 |
|------|------|------|
| schema 实体 | `research-wiki/schemas/<name>.md` | 表结构 + 列说明 + 埋点位置 |
| metric 实体 | `research-wiki/metrics/<name>.md` | 基线值 + 阈值 + 判定方式 |
| edge 关系 | `research-wiki/graph/edges.json` | schema↔metric↔design 关联 |
| 日志埋点清单 | 传递给 writing-plans | 具体文件和函数的埋点要求 |