Skip to content

[FEATURE] 查询结果完整性与分页协议:has_more/total 语义/超时保护 #140

Closed

Description

@codeasier

功能描述

query -n 默认不限制行数(cli.py query 选项),执行器以 fetchall() 物化全部结果(query/executor.py),当返回行数达到 max_rows 时会额外执行 count 查询取精确总数(core/query_service.py)。对 Agent 存在三个问题:

  1. 无界输出可能耗尽 Agent 上下文;
  2. total 语义不明确:达到上限时是精确总数,未达到时等于已返回行数,Agent 无法区分「完整集合」与「截断集合」;
  3. 输出限制与执行成本未分离:LIMIT 行数不限制执行成本,且没有查询超时保护。

使用场景

Agent 需要判断证据是否完整:把「前 100 条」当成全部会得出错误结论;确认截断后需要稳定的分页方式继续取证。

期望的实现方式

  • 结果显式携带 returned / has_more / truncated 及生效的限制条件(与 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 的结果信封对齐)
  • 精确 total 变为可选能力(opt-in 或按需触发),必要时以「多取一行」判断是否还有更多
  • 为支持分页的模板定义稳定排序与 offset 参数(event / block 模板已有 limit/offset 基础)
  • 增加查询超时保护(如 SQLite progress handler),输出限制与执行超时分别处理
  • 诊断技能默认使用有界查询(现有 skill 文档已要求 -n 100 起步,见 skills/pt-snap-memory-leak/SKILL.md Step 5)

验收标准

  • JSON 结果能明确区分完整 / 截断(has_more/truncated)
  • total 语义文档化并有测试覆盖(精确 vs 已返回行数)
  • 至少 event / block 类模板支持稳定排序分页
  • 查询超时可配置并有测试
  • 诊断技能默认有界查询,相关技能文档同步更新

Activity

  1. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    归入 #136 Agent 友好化路线图 P1;与 #138 结果信封、#141 语义元数据衔接。

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