LLM Agent 查询基础设施：从“能接”到“可推理、可追问、可演进”

• 最小交付集合：实体定义、读模型、字段字典、查询能力边界、样例查询、稳定详情能力。
• 字段字典至少覆盖：字段名、类型、中文语义、可筛选/排序/聚合、可空、枚举范围。
• 若无稳定主键与 detail by id，follow-up 会在“这条/第2条/这些结果的 id”场景失稳。
• 若只有单 query 字符串，无法稳定表达范围过滤、排序、聚合，属于兼容层而非主查询底座。

推荐查询样例:
- 给我湖南 2020 年后的资料
- 把刚才结果的 id 列出来
- 只要链接
- 第 2 条展开详情

推荐统一字段：id/title/type/category/region/year/status/summary/content/source/created_at/updated_at；URL 类字段统一为 url/pdf_url/h5_url/download_url/preview_url。

{
  "name": "search_kaoqing_documents",
  "kind": "query",
  "input_schema": {
    "region": {"type": "string"},
    "year_gte": {"type": "integer"},
    "limit": {"type": "integer", "default": 20}
  },
  "result_schema": {
    "entity": "document",
    "list_fields": ["id", "title", "year", "region", "pdf_url", "h5_url"]
  }
}

反模式：只有字符串 query、零散接口爆炸、页面导向返回、没有 detail by id。

核心要求：每一阶段都应有可验证的“退出标准”，而不是凭主观感受推进。

• 数据与实体：核心实体定义完整，主键跨轮稳定，不依赖标题做伪主键。
• 查询面：支持精确/范围/枚举过滤，支持 limit 与稳定排序，查询语义文档化。
• 适配层：capability、输入输出 schema、字段映射、working set 规则齐备。
• 可观测性：能追踪用户问题、planner 路径、adapter 参数、上游摘要、最终回复。
• 安全与性能：只读、限流、超时、最大返回条数、慢查询风险说明。

验收口令:
1) 这些结果的 id 给我
2) 第 2 条展开
3) 把链接发我
4) 刚才那批里湖南的有哪些

兼容态请求:
POST /sac/kq/pdf
{
  "query": "福建"
}

目标态（结构化）:
{
  "entity": "kaoqing_document",
  "filters": {"region": "浙江", "year >= 2021": true, "confirmed": true},
  "sort": ["year:desc", "updated_at:desc"],
  "limit": 20,
  "fields": ["id", "title", "year", "region", "pdf_url"]
}

目标 SQL:
SELECT id, title, year, region, pdf_url
FROM kaoqing_document_read_model
WHERE region = '浙江'
  AND year >= 2021
ORDER BY year DESC, updated_at DESC
LIMIT 20;

• 业务域说明：业务目标、典型问题、结果主实体与不支持范围。
• 底层能力：数据来源、字段字典、查询边界、错误语义、性能边界。
• Agent 设计：路径选择、delivery role、working set 字段、follow-up 策略。
• 联调与验收：基础用例、追问用例、边界用例、灰度样本、复盘结论。