Files

T

iomgaa 3058f4c744 chore: bootstrap project scaffolding

Add architecture doc (research-wiki/ARCHITECTURE.md), CLAUDE.md with
tiered SOP for Fable 5, adapted .claude skills/hooks/settings, package
skeleton (src/polygateway), pyproject with import-linter contracts,
Makefile, .env.example and smoke test.

2026-07-20 00:49:10 -04:00

3.0 KiB

Raw Blame History

name, description, argument-hint

name	description	argument-hint
structured-logging	设计结构化日志/遥测方案。当功能会产生运行时数据时,在 brainstorming 产出 design 之后、writing-plans 之前调用:确定记录什么、记到哪、如何评估,并注册到 Wiki。纯内部重构、不产生运行时数据的改动不需要。	[功能描述]

Structured Logging

Overview

为即将开发的功能设计结构化日志/遥测方案:记录什么数据、落到哪张表、如何评估。

边界: 会产生运行时数据的功能,编码前必须有日志方案——埋点是"当前需要"(CLAUDE.md P1),事后补埋点意味着丢失基线数据。不产生运行时数据的改动直接跳过本 skill。

本项目背景:PolyGateway 自带遥测子系统(telemetry/,SQLite 后端,每次调用必录,见 CLAUDE.md 库铁律"遥测必录")。本 skill 设计的是具体功能的埋点方案,必须与遥测子系统对齐,不另起炉灶。

设计要回答的问题

这个功能产生什么运行时数据? 网关领域的典型维度:
- 每次调用的时延 / TTFT / token 用量与成本
- 错误分类计数(Transient/SourceDead/RequestRejected/ResultInvalid)与重试次数
- 熔断状态迁移、限流等待/拒绝、缓存命中率
- 阶段事件(开始/结束/错误/降级)
新建表还是复用现有表? 现有表能覆盖就复用;需要新维度才新建。先对照 research-wiki/schemas/ 已登记的 schema 与实际库中的表,标记不一致。
每张表的 schema: 列名、类型、说明、主键、哪些列服务于诊断查询。
埋点位置: 具体模块与函数;必须走库的 TelemetryRecorder 端口/统一 helper,禁止散落的 ad-hoc 写库(三项目遥测调用被复制 4 次的教训)。
评估基线: 可量化指标 + 阈值 + 判定方式;基线来源(对比哪次历史运行;首次则标"待首次运行后建立")。

注册到 Wiki(留痕,不可省略)

.claude/tools/research_wiki.py add_entity research-wiki/ --type schema --id <table-name> --title "表结构: <table-name>"
.claude/tools/research_wiki.py add_entity research-wiki/ --type metric --id <metric-name> --title "<指标描述>"
.claude/tools/research_wiki.py add_edge research-wiki/ --from "metric:<id>" --to "schema:<id>" --type measures --evidence "..."
.claude/tools/research_wiki.py add_edge research-wiki/ --from "schema:<id>" --to "design:<id>" --type implements --evidence "..."
.claude/tools/research_wiki.py rebuild_index research-wiki/

在生成的 md 中填入完整列定义、埋点位置、基线值与阈值。

产出(交给 writing-plans)

埋点清单:哪些文件、哪些函数、在什么位置记什么。这些埋点必须成为 plan 中的显式步骤,不得遗漏。

产出	位置
schema 实体	`research-wiki/schemas/<name>.md`
metric 实体	`research-wiki/metrics/<name>.md`
edge 关系	`research-wiki/graph/edges.json`
埋点清单	传递给 writing-plans

3.0 KiB Raw Blame History