Skip to content

[FEATURE] 查询模板语义元数据:字段单位、统计口径与解释限制 #141

Closed

Description

@codeasier

功能描述

大量避免误判的领域知识目前只存在于技能文档(SKILL.md)中,例如:

  • trace 结束时仍存活 ≠ 已确认泄漏(候选证据);
  • 不同事件发生的峰值不能直接相减;
  • event ID 距离是排序标记,不是耗时;
  • 地址复用 ≠ 同一 allocation;
  • percent_of_active_blocks 实为字节占比而非块数占比(skills/pt-snap-memory-leak/SKILL.md Step 3 有专门警示)。

未加载技能的 Agent 只凭字段名很容易误读这些结果。

使用场景

任何 Agent(包括未加载技能的)读取查询结果时,都应能获取字段的单位与统计口径;技能文档保留决策流程,字段语义下沉到模板元数据,避免两处漂移。

期望的实现方式

验收标准

  • leak_detection / memory_peak / allocator_gap / active_memory_callstack_at_event 的关键字段带语义元数据
  • --template-info 输出机器可读的语义元数据
  • 诊断技能文档引用元数据而非重复定义
  • tests/query 覆盖元数据加载与展示

Activity

  1. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    归入 #136 Agent 友好化路线图 P1;参数约束部分与 #120 关联,避免两套 schema。

  2. codeasier commented on Sep 18, 2026

    @codeasier
    OwnerAuthor

    需求真实,支持将字段语义下沉到模板元数据。建议补充以下边界:

    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 行为测试支撑,避免只测试“字段存在”。

    技能保留决策流程与关键提醒,详细定义引用元数据;同步中英文文档、打包技能副本及现有技能契约测试。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions