mcp接口增加分页

PROJECT_STATE.md

@@ -4,18 +4,20 @@
 | --- | --- |
 | 最近更新 | 2026-09-06 |
 | 当前分支 | `main` |
-| 当前阶段 | 对话、SuperAgent、空间 MCP、默认关闭的测试页面、无 Trace 兼容模式与测试环境容器部署基线已完成；公网地点候选 MCP 已现场成功一次，页面公网验收和完整 MCP 多工具链仍待验证 |
-| 当前重点 | 使用 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false` 绕过当前 Trace 策略限制，重建目标机并验证兼容 Chat 与完整公网 MCP 工具链路 |
+| 当前阶段 | 对话、SuperAgent、空间 MCP、默认关闭的测试页面、无 Trace 兼容模式与测试环境容器部署基线已完成；7 个 MCP 工具的统一分页代码和自动化验证已完成，真实 PostGIS 与公网分页验收待完成 |
+| 当前重点 | 部署并验证 MCP 分页契约，再发布“小牟”消防 Profile 提示词，核对具体方案的多工具调用、分页提示和 WGS84 坐标输出 |
 
 ## 1. 当前 Checkpoint
 
-- 名称：`fire-safety-ymd-superagent-no-trace-mode-v1`
-- 状态：Ready for Review（无 Trace 自动化、真实 SuperAgent 探针和本地兼容 Chat 冒烟均已通过；测试服务器重建和公网完整 MCP 对话待用户执行）
-- 目标：增加 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 配置，默认使用 `include_trace=false`，在不开放 SuperAgent Trace 策略时仍严格验证最终 AI 消息 `finish_reason=stop`、非空顶层 `message.final` 与顶层 `end`；开启 Trace 时继续要求 `run.completed(status=success)`，并保持既有 Chat/MCP 安全边界。
-- 非目标：替用户提交或推送 Git、直接修改远程服务器、创建数据库容器、迁移生产数据、签发证书、改变 DNS/安全组、实现真实用户认证、动态授权、会话持久化或生产审计；无 Trace 也不承诺已完成公网 MCP 多工具对话验证。
+- 名称：`fire-safety-ymd-mcp-pagination-v1`
+- 状态：Ready for Review（7 个工具的分页代码、自动化测试和文档已完成；分页版真实 PostGIS 查询、测试服务器部署和公网 SuperAgent 验收待执行）
+- 目标：为 7 个固定只读 MCP 工具提供兼容现有调用的有界 `limit/offset` 分页，返回过滤后 `total_count`、当前页 `result_count`、`has_more` 和 `next_offset`，确保 Agent 不再把默认前 10/20 条误报为全部结果。
+- 非目标：替用户提交或推送 Git、直接修改远程服务器、创建数据库容器、修改或迁移生产数据、实现任意 SQL/游标快照分页、改写 Chat 最终回答协议、实现真实用户认证、动态授权、会话持久化或生产审计。
 
 当前进展：
 
+- 7 个 MCP 工具均已增加 `limit/offset` schema、服务端校验和稳定 SQL 分页；响应 `data` 仍为数组，metadata 已区分当前页数量与过滤后总量。自动化、竞态、vet 和 Linux 构建通过；开发机当前无法连接 `.env` 中的 PostGIS，分页版真实 SQL 尚未实库复验。
+- 用户报告测试页面已经能够正常输出内容，并确认对外身份应为“山东省烟台市牟平区森林防火平台 AI 助手小牟”。现有 Profile 更像泛化模板生成器，没有主动形成数据支撑的演练方案，也没有稳定展示工具坐标。仓库已新增可直接粘贴的消防 Profile 提示词 v2，明确“小牟”身份、“数据库事实 + 通用专业规划”的能力定位、坐标输出硬规则、纯文本结果格式、综合方案结构和能力边界；真实 Profile 尚未由用户发布和验收。
 - `Dockerfile` 使用显式 Go/Alpine 版本的多阶段构建，在构建阶段执行全部 Go 测试，最终镜像只包含静态服务二进制、CA 和时区数据，并以非 root 用户运行。
 - Docker build 支持通过 `FIRE_SAFETY_BUILD_GOPROXY` 选择目标机可达的可信 Go module proxy；默认仍为官方代理并保留 checksum database，`git` 只存在于 builder，构建代理配置在运行容器中强制清空。
 - `compose.yaml` 只运行一个 API 实例，从未提交的 `.env` 注入配置，强制清空一次性迁移 DSN，把容器内 8080 发布到宿主机 `127.0.0.1:16587`，并设置健康检查、只读文件系统、权限收紧和日志轮转。
@@ -38,13 +40,14 @@
 
 1. 由用户审查本 checkpoint 变更后提交并推送 `origin/main`；服务器只部署明确提交的 revision。
 2. 在 `/home/firee-safety-ymd` 重建 Compose，确认宿主机 16587 只绑定回环地址、容器内 8080 健康可达且数据库连接正常。
-3. 页面测试保持 `FIRE_SAFETY_CHAT_PAGE_ENABLED=false` 默认边界；需要开启时配置 `https://agent.nianxx.com` 精确 Origin，重建容器并验证 `/chat` 308、`/chat/` 及 CSS/JavaScript 资源 200，以及关闭后的直接 404。
-4. reload 已通过语法检查的 Nginx 配置，只公开 HTTPS 页面/资源、兼容路径、`/mcp` 和可选 `/health`。
-5. 使用项目专属测试 Key 和已发布消防 Profile 做兼容 `completion` 首轮/多轮真实冒烟，核对最终回答、用量和会话复用；页面必须证明使用同一请求契约。
-6. 先以 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false` 重建并运行探针/Chat，确认无 Trace 的 `finish_reason=stop` + 非空顶层 `message.final` + 顶层 `end` 严格成功；仅在外部应用策略允许时再测试 true 模式。
-7. 使用 SuperAgent 无版本配置的实际握手重测：通过 `direct_success` 或 `compatibility_success` 日志确认请求已按 proven profile 处理，并验证 `initialize` → `notifications/initialized` → `tools/list` → 7 个工具的 `tools/call`；当前公网地点搜索的一次成功不替代完整链路，版本字段/Header 不需要配置，也不作为拒绝门禁。
-8. 为所有查询表补齐适用 GiST 索引并验证查询计划；当前小数据可做联调，但生产前必须完成索引与并发验证。
-9. 设计真实用户身份、动态角色/区域授权、共享会话、限流、Secret 轮换、指标和持久审计。
+3. 按部署手册对同一地名执行 `offset=0/1` 相邻页真实冒烟，核对 `total_count` 一致、`next_offset` 可继续且记录不重复；再验证 7 个工具的分页版 `tools/call` 和 warning。
+4. 分页契约部署通过后，将 `docs/project/integrations/superagent-fire-safety-profile-prompt.md` 的“可直接粘贴版本”发布为消防测试 Profile 新版本。
+5. 用全新会话验证地名候选、继续展示和综合演练问题；同时核对自然语言结果与 MCP 日志，坐标只来自 `location`/`nearest_point`，责任队伍、集结点和路线能力不得被补造。
+6. 页面测试保持 `FIRE_SAFETY_CHAT_PAGE_ENABLED=false` 默认边界；需要开启时配置精确 Origin，验证页面入口和静态资源；Nginx 只公开约定路径。
+7. 使用项目专属测试 Key 验证兼容 `completion` 首轮/多轮、会话复用和无 Trace 严格完成；仅在外部应用策略允许时测试 Trace 模式。
+8. 使用 SuperAgent 实际握手验证 `initialize` → `notifications/initialized` → `tools/list` → 7 个工具的 `tools/call`；版本字段/Header 不作为配置或拒绝门禁。
+9. 为所有查询表补齐适用 GiST 索引并验证查询计划；当前小数据可做联调，但生产前必须完成索引与并发验证。
+10. 设计真实用户身份、动态角色/区域授权、共享会话、限流、Secret 轮换、指标和持久审计。
 
 ## 3. 已确认事实
 
@@ -68,6 +71,7 @@
 - `deploy/nginx/fire-safety-ymd.conf.example` 已将公网页面/资源、兼容对话和 MCP 调用指向宿主机 `127.0.0.1:16587`，再由 Docker 映射到容器 8080；配置不保存或注入任何 Provider/Chat/MCP Secret。目标机仅 `nginx -t` 语法检查已通过，reload、页面资源和 HTTPS 实际响应尚未验证。
 - 用户确认真实数据包含大量镇街，环境变量不适合枚举全量值；MCP 现支持显式数据库全范围 `all` 和默认镇街白名单 `town_allowlist` 两种服务端范围。
 - 用户选择先实现简单地名能力、后续再优化；当前只查询既有森林防火记录，不调用外部地图服务，也不把候选代表点自动认定为演练点。
+- 消防 Profile 的对外身份已确认为“山东省烟台市牟平区森林防火平台 AI 助手小牟”，能力不限于复述系统字段，可用通用专业知识补全演练方案；本地地点和资源事实仍必须来自用户确认或 MCP，相关工具返回坐标时默认展示 WGS84 经度、纬度。当前实现是授权 MCP 查询，不得表述为业务数据已经训练进模型或 Agent 会在对话中自行学习。
 - 本地真实 MCP 冒烟已完成：7 个工具均成功访问实库，响应和错误边界符合契约；该结果不等于公网、SuperAgent 或生产并发已验证。
 - SuperAgent 无法配置 MCP 协议版本；已稳定接通的 `th-hotel-simple-superagent` 作为 proven profile 参照，不读取/校验 initialize 版本字段或 `MCP-Protocol-Version` Header，并固定返回 `2025-06-18`。消防服务按该 profile 处理，版本字段/Header 不作为拒绝门禁；固定返回不等于支持任意其他版本，也不是追求最新协议。
 - 防火通道现有字段不能支持可靠路线规划；防火网格现有字段不能支持实时队伍位置或正式集结点。
@@ -92,6 +96,7 @@
 - 路线规划缺少路网拓扑、坡度、路面、宽度、车辆限制、封路、实时火场和天气数据。
 - 队伍集结缺少正式集结点、实时定位、战备状态、人员/车辆/装备和容量数据。
 - `fire-safety-ymd` 正式 module path 与 CI/部署 Go 版本仍待确认。
+- 新提示词尚未发布到真实消防 Profile；坐标展示、地名确认、多点不串线、综合问题多工具调用以及建议/事实分层均待全新会话验收。
 
 ## 5. Next Checkpoint
 
@@ -110,6 +115,7 @@
 
 ## 6. 验证记录
 
+- MCP 分页：`gofmt`、`GOCACHE=/private/tmp/fire-safety-ymd-pagination-go-cache go test -count=1 ./...`、`go vet ./...`、`go test -race -count=1 ./...` 和 Linux 静态服务构建通过；覆盖 7 个工具的 schema、默认值、边界校验、透传、当前页/总量元数据、末页、超尾页、稳定排序与只读 SQL 参数化。开发机使用现有 `.env` 尝试真实分页冒烟时无法连接已配置 PostGIS，因此分页版真实 SQL 和公网链路仍待测试服务器验证。
 - `gofmt -w ./cmd ./internal`：通过。
 - `GOCACHE=/private/tmp/fire-safety-ymd-go-cache go test -count=1 ./...`：通过；新增覆盖页面开关依赖、开启/关闭路由、HTML/静态资源、安全响应头和应用装配；原有 Chat、SuperAgent、MCP/PostGIS 覆盖继续通过。
 - `GOCACHE=/private/tmp/fire-safety-ymd-go-cache go vet ./...`：通过。
@@ -138,3 +144,13 @@
 - 真实 SuperAgent 对话与 MCP 联调：对话 API 仅完成模拟 Provider 端到端测试，真实消防 Profile 尚未完成 Chat 页面/多轮验收；MCP readiness 和本地真实工具冒烟已通过。公网 `/mcp` 已完成一次 `fire_safety_search_place_candidates`，但其余 6 个工具和完整多工具链尚待验证，不能宣称公网工具联调或部署完成。th-hotel 成功只证明同一 SuperAgent 的兼容档案可行，不替代消防 endpoint 的完整链路验收。
 - 样例 SQL：未执行；含受限数据的 `*.sql` 已被 Git 忽略。
 - Git：`801c0af`（Chat 门禁兼容修复）已由用户提交并推送到 `origin/main`；本次 MCP 协商变更尚未提交，未执行自动 commit/push。
+
+## 7. 2026-09-06 MCP 分页契约 checkpoint
+
+- 名称：`fire-safety-ymd-mcp-pagination-v1`
+- 状态：代码、自动化测试和文档契约已完成；分页版真实 PostGIS 查询与公网 SuperAgent 验收待完成。
+- 统一契约：7 个只读工具均接受可选 `limit`/`offset`；`limit` 范围为 `1..20`，`offset` 范围为 `0..10000`。地名候选、水源、指挥部候选、防火通道和风险区域默认 `limit=10`；防火网格和责任中队默认 `limit=20`；`offset` 默认 `0`。
+- 结果契约：`data` 始终为数组；`metadata.result_count` 为当前页数量，新增 `total_count`、`limit`、`offset`、`has_more`、`next_offset`。总量必须在授权范围、有效几何排除和全部业务过滤完成后、分页前计算，并使用稳定排序；末页 `next_offset=null`。
+- 状态语义：仅 `total_count=0` 使用 `status=no_results`；总量大于零但请求超出末页时仍为 `status=ok`，返回空数组和 `has_more=false`。
+- Agent 规则：`has_more=true` 时说明当前展示数/总数；用户要求继续时使用上一页 `next_offset`；综合方案默认不自动拉取全部页。
+- 实现范围：Domain/Service/Handler/Repository 已统一分页；Repository 使用过滤后的窗口总量、稳定排序和参数化 `LIMIT/OFFSET`，超尾空页通过相同条件的只读首页探测恢复准确 `total_count`。同步更新了项目上下文、架构、空间 MCP Spec、SuperAgent 接入指南、演练证据流程、消防 Profile 提示词和本状态记录。