mcp接口增加分页

docs/project/integrations/superagent-mcp-spatial.md

@@ -46,9 +46,42 @@ SuperAgent 当前不能在 MCP 服务配置中填写或固定 `protocolVersion`
 
 工具不会返回负责人、书记、队长、值班人员、电话或图片字段。
 
+## 统一分页契约
+
+七个工具都支持可选的 `limit` 和 `offset`，由 MCP 服务端统一校验和分页：
+
+| 工具类别 | 默认 `limit` | `offset` 默认值 |
+| --- | ---: | ---: |
+| 地名候选、水源、指挥部候选、防火通道、风险区域 | 10 | 0 |
+| 防火网格、责任中队 | 20 | 0 |
+
+`limit` 只能是 `1..20`，`offset` 只能是 `0..10000`；`offset` 是稳定排序结果中的零基偏移量，不是页码。服务端先完成授权范围、空间条件、有效几何排除和其他业务过滤，再计算总量并执行分页。所有工具保持稳定排序：业务主排序相同的记录使用资源类型、源记录 ID 等确定性字段决胜。
+
+每个成功工具结果的 `data` 都是数组，`metadata` 至少包含：
+
+```json
+{
+  "result_count": 10,
+  "total_count": 27,
+  "limit": 10,
+  "offset": 0,
+  "has_more": true,
+  "next_offset": 10
+}
+```
+
+其中 `result_count` 是当前页数量，`total_count` 是全部有效过滤结果的数量；`has_more` 等价于 `offset + result_count < total_count`，有下一页时 `next_offset` 为 `offset + result_count`，末页为 `null`。只有 `total_count=0` 时 `status` 才是 `no_results`；当请求超出末页但总量大于零时，仍返回 `status=ok` 和空数组，不能误报为无结果。
+
+SuperAgent Profile 应遵循以下分页规则：
+
+1. 首次查询不传分页参数时使用工具默认值；需要更多结果时使用上一次响应的 `next_offset`，不要自行计算或把它当页码。
+2. `has_more=true` 时，回答中说明“当前展示 N 条，共 M 条”，并在用户明确要求继续或结果确实影响当前问题时继续查询。
+3. 综合演练方案默认使用当前页的主要候选，不自动循环拉取全部数据；需要完整清单时先告知用户总量，再按 `next_offset` 分页展示。
+4. `data=[]` 且 `total_count>0` 表示请求偏移已超过末页，不得说“数据库没有记录”；只有 `status=no_results` 才表示有效过滤范围内总量为零。
+
 ## 地名输入的最小流程
 
-`fire_safety_search_place_candidates` 接受 `place_name` 和可选 `limit`，名称长度为 2 至 100 字符，默认返回 10 条、最多 20 条。它对现有业务记录的名称、镇街和村庄字段做不区分大小写的包含匹配，不是完整地名库，也不调用外部地图服务。
+`fire_safety_search_place_candidates` 接受 `place_name` 和可选的 `limit`/`offset`，名称长度为 2 至 100 字符，默认 `limit=10`、`offset=0`、最多 20 条。它对现有业务记录的名称、镇街和村庄字段做不区分大小写的包含匹配，不是完整地名库，也不调用外部地图服务。
 
 返回值包含：
 
@@ -66,15 +99,7 @@ SuperAgent Profile 应遵循：
 5. `representative_point` 不能描述为地点中心、入口或真实演练点。
 6. 工具返回 `source_records_with_invalid_geometries_are_excluded` 时，必须说明结果可能不完整；无结果只能表示在有效记录中没有找到。
 
-可加入 SuperAgent 系统提示词的最小片段：
-
-```text
-当用户没有经纬度但提供了地名时，先调用 fire_safety_search_place_candidates。
-搜索结果只是地点候选：无结果时请用户补充地名或地图选点；多结果时列出候选并请用户选择；不得静默选择第一条。
-任何候选都要先回显名称、类型、镇街、村庄和坐标供用户确认。location_kind=representative_point 时必须说明它只是线面记录的代表点，不能当作真实演练点。
-只有用户确认坐标后，才调用网格、水源、指挥部候选、防火通道、责任中队和风险区域工具。
-所有空间工具都会排除无效几何。看到 source_records_with_invalid_geometries_are_excluded 时，要说明结果可能不完整；不得把无结果解释为原始数据库确认不存在。
-```
+消防专属 Profile 不应只包含地名搜索的最小片段。完整、可直接粘贴的系统提示词见 [`superagent-fire-safety-profile-prompt.md`](superagent-fire-safety-profile-prompt.md)。该提示词将对外身份统一为“山东省烟台市牟平区森林防火平台 AI 助手小牟”，并同时承担日常咨询、授权数据查询和演练方案辅助：本地事实必须来自用户确认或 MCP，方案组织可以使用通用专业知识；所有相关 `location`/`nearest_point` 默认显示 WGS84 经度、纬度；没有坐标、路线或实时队伍位置时不得补造。
 
 ## 配置顺序
 
@@ -168,7 +193,7 @@ SuperAgent 侧配置模板见 [`superagent-mcp-client.example.json`](superagent-
 ## 当前联调门禁
 
 - 样例 SQL 不可执行，也不可提交；其中包含破坏性 DDL 和受限联系人数据。
-- 2026-09-05 已完成受控 SRID 元数据迁移和严格 audit：8 表共 4,055 条记录，4,048 条非空几何均为 SRID 4326，SRID/类型/范围硬门禁通过。7 条空几何、35 条无效面几何以及 7 张缺 GiST 索引表仍按预期告警；本地实库 7 个 `tools/call` 已执行并通过，但公网 SuperAgent `tools/call` 尚未执行，因此当前仍不能宣称公网 MCP 业务联调完成。
+- 2026-09-05 已完成受控 SRID 元数据迁移和严格 audit：8 表共 4,055 条记录，4,048 条非空几何均为 SRID 4326，SRID/类型/范围硬门禁通过。7 条空几何、35 条无效面几何以及 7 张缺 GiST 索引表仍按预期告警；分页改造前的本地实库 7 个 `tools/call` 已执行并通过，分页版真实 PostGIS 查询与公网 SuperAgent 调用尚未复验，因此当前仍不能宣称分页或公网 MCP 业务联调完成。
 - 用户提供的 SuperAgent 现场截图证明公网 `/mcp` 请求已经到达 Go 服务，Bearer、`Content-Type` 和 JSON-RPC 前置校验通过；随后旧版本门禁返回错误。该历史截图没有捕获客户端版本字段是否存在、类型和值。同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定调用是兼容档案的参照，但不是消防 MCP 的成功证据；部署后仍需观察 `direct_success` 或 `compatibility_success`，并完成 initialize → initialized → tools/list → 至少一个 tools/call。
 - 缺少适用于距离表达式的 GiST 索引时可做小数据开发联调，但生产前必须补齐并验证查询计划。
 - 地名包含匹配当前没有专用名称索引；真实数据量下先验证查询耗时，后续再决定标准地名表、别名词典或 `pg_trgm` 索引。