Files

T

iomgaa 6bdb802f01 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

3.8 KiB

Raw Blame History

name, description, argument-hint

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

Structured Logging

Overview

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

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

触发时机

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

前置条件

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

执行流程

Phase 1: 读取现有 Schema

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

Phase 2: 设计日志方案

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

这个功能会产生什么运行时数据？
- OCR 置信度（每张影像/字段的识别置信度）
- 提取信度一致率（多次提取/多专家的一致性）
- 阶段事件（开始/结束/错误/警告）
- 门控结果（期望张数、完整性校验）
- token 用量与时延（LLM 调用成本与延迟）
需要新建表还是复用现有表？
- 如果现有表能覆盖 → 复用，不新建
- 如果需要新维度 → 新建表
每张表的 schema 是什么？
- 列名、类型、说明
- 主键（如果有）
- 哪些列用于 agent 查询诊断
在代码哪些位置埋点？
- 具体函数名、具体代码节点
- 用 log.insert() 还是 log.log_event()

Phase 3: 定义评估基线

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

Phase 4: 注册到 Wiki

对每张新表，执行：

python3 .claude/tools/research_wiki.py add_entity research-wiki/ --type schema --id <table-name> --title "表结构: <table-name>"

然后在生成的 md 文件中填入完整的列定义和埋点位置。

对每组基线指标，执行：

python3 .claude/tools/research_wiki.py add_entity research-wiki/ --type metric --id <metric-name> --title "<指标描述>"

然后在生成的 md 文件中填入基线值、阈值、判定方式。

建立关联：

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 "..."

重建索引：

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	具体文件和函数的埋点要求

3.8 KiB Raw Blame History