iomgaa
6bdb802f01
- 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
103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
---
|
|
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 | 具体文件和函数的埋点要求 |
|