chore: track claude skills, tools, templates, reference code and research-wiki

- Add all claude skills (brainstorming, commit, debugging, TDD, etc.) - Add claude hooks (pre-commit-guard, post-edit-quality) - Add research templates (experiment plan, research brief, etc.) - Add claude tools (arxiv/semantic_scholar/openalex fetch, wiki, exa) - Add TRM4 reference implementation as algorithm fidelity baseline - Add research-wiki content (plans, index, graph, query_pack) - Update .gitignore to exclude .graphify_version runtime state
2026-07-06 20:59:03 -04:00
parent 0616d16956
commit 6bdb802f01
98 changed files with 19321 additions and 0 deletions
@@ -0,0 +1,102 @@
+---
+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 | 具体文件和函数的埋点要求 |