### 功能描述 大量避免误判的领域知识目前只存在于技能文档(SKILL.md)中,例如: - trace 结束时仍存活 ≠ 已确认泄漏(候选证据); - 不同事件发生的峰值不能直接相减; - event ID 距离是排序标记,不是耗时; - 地址复用 ≠ 同一 allocation; - `percent_of_active_blocks` 实为字节占比而非块数占比(`skills/pt-snap-memory-leak/SKILL.md` Step 3 有专门警示)。 未加载技能的 Agent 只凭字段名很容易误读这些结果。 ### 使用场景 任何 Agent(包括未加载技能的)读取查询结果时,都应能获取字段的单位与统计口径;技能文档保留决策流程,字段语义下沉到模板元数据,避免两处漂移。 ### 期望的实现方式 - 模板 YAML 的 `output_schema` 扩展语义元数据:`units`(bytes / percent / event_id)、`metric_semantics`(瞬时占用 / 累计分配)、`scope`(dynamic / static / preexisting)、`interpretation_limits` - `query --template-info`(含 #138 的 `--json` 形态)暴露同一份元数据 - 结果行不重复长说明,通过模板名 / 契约版本引用 - 优先覆盖易误读字段:`percent_of_active_blocks`、各 peak 值、`allocEventId`/`freeEventId` 语义 - 与 #120 的参数约束工作共用元数据机制,不引入两套 schema ### 验收标准 - [ ] `leak_detection` / `memory_peak` / `allocator_gap` / `active_memory_callstack_at_event` 的关键字段带语义元数据 - [ ] `--template-info` 输出机器可读的语义元数据 - [ ] 诊断技能文档引用元数据而非重复定义 - [ ] `tests/query` 覆盖元数据加载与展示
Activity
codeasier commentedon Sep 17, 2026
归入 #136 Agent 友好化路线图 P1;参数约束部分与 #120 关联,避免两套 schema。
codeasier commentedon Sep 18, 2026
需求真实,支持将字段语义下沉到模板元数据。建议补充以下边界:
1. 修正现状描述
这些知识并非全部仅存在于技能中:
docs/en/database.md已解释allocEventId/freeEventId,docs/en/querying.md已说明存活条件与 static/preexisting 分类。当前缺口是统一、机器可读、跨接口一致的语义契约。2. 元数据必须描述准确的统计口径
percent_of_active_blocks是 0–100 的字节百分比,分母受min_size、include_static和top_n影响。SQL 先截断动态调用栈组,再计算占比;不能描述成“全部 active memory 的占比”。该行为已有tests/query/test_peak_memory_templates.py覆盖。memory_peak的各指标独立取指定事件范围内的最大值,同值取最早事件;不同事件的峰值不能直接相减。allocator_gap在同一事件计算差值,但 reserved-active gap 本身不能直接等同于碎片。freeEventId指向释放完成事件,需声明未捕获事件的哨兵值、NULL 处理与存活边界;事件 ID 及其距离不是耗时。leak_detection返回捕获范围内有分配记录、无释放完成记录的候选,不能据此确认泄漏。现有 “Detect memory leaks” 等描述也应同步校准。3. 区分字段级语义和模板级解释限制
“候选不等于泄漏”“跨事件峰值不可相减”等适合模板级
interpretation_limits;单位、分母、事件含义适合字段级定义。scope需要支持按行分类或混合范围:active_memory_callstack_at_event同时返回 dynamic/static/preexisting 行,不能给整列固定标注为 dynamic。单位也需覆盖实际输出中的 GiB、计数等。4. 复用共享链路,明确版本与兼容性
#120 已在当前 main 落地,建议扩展既有 YAML → config → registry → core → API/MCP/CLI 链路。当前
output_schema直接透传,但类型声明为list[dict[str, str]];引入数组或结构化语义时,应同步调整类型和加载校验,并兼容未声明新增字段的旧模板。与 #138 对齐结果信封中的模板名及契约版本引用,明确其与 YAML 格式版本、SnapshotDB schema 版本的区别。v1/v2 SQL 变体应共享同一份语义契约。
5. 扩展验收范围
除
tests/query外,应覆盖 CLI、Python API、MCP 及tests/test_contract_cli_mcp.py,验证元数据完整透传、JSON 可解析及旧模板兼容。统计口径应有 SQL 行为测试支撑,避免只测试“字段存在”。技能保留决策流程与关键提醒,详细定义引用元数据;同步中英文文档、打包技能副本及现有技能契约测试。