fire-safety-ymd 项目上下文

1. 项目目标

fire-safety-ymd 是一个面向森林防火场景的 Go 后端项目。目标调用链是：用户在业务应用中提问，后端维护会话并调用既有 SuperAgent 平台；SuperAgent 在需要业务事实时调用本项目提供的 MCP 工具；本项目从受控的 PostgreSQL/PostGIS 数据源查询消防资源和风险区域，再将结构化结果返回给 Agent 组织回答或辅助方案。

项目不自行训练或实现通用 Agent，也不允许大模型直接访问数据库。

用户对话的 Chat 凭证默认要求至少 32 个可打印 ASCII 字符。若已经交付的旧客户端只能继续发送短凭证，必须在受控测试/迁移窗口显式开启 FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN；该开关默认关闭，新环境不得开启，轮换后恢复关闭。无论开关如何，Chat 凭证仍须非空、不超过 4096 字节且仅含 ASCII 0x21-0x7e（无空格、控制字符或 Unicode）；该兼容范围只适用于 Chat 原生 Bearer 与兼容入口 xtoken，MCP Token 仍要求至少 32 个字符，三种凭证必须不同。

2. 当前系统组成

路径或系统	当前职责	当前状态
`cmd/server`	Go 服务进程入口	已建立
`internal/app`	应用装配、readiness 和 HTTP 生命周期	已建立；按开关装配原生/兼容 Chat、可选 `/chat` 测试页面、SuperAgent 和 MCP/PostGIS
`internal/config`	环境配置入口	已包含 HTTP、SuperAgent、Chat 兼容 App ID/页面开关/legacy 短凭证开关、MCP 与 PostGIS 配置校验和凭证分离门禁
`internal/handler`	HTTP/MCP 入站协议层	`GET /health` 已启用；默认关闭的原生 `/api/chat`、可选 DashScope 风格 `completion`、可选 `/chat` 页面/资源和 `/mcp` 已实现
`internal/service`	业务用例编排	已实现单进程聊天会话/并发 Run 控制，以及地名候选、有界空间查询、可信数据库全范围/镇街白名单和结果语义
`internal/domain`	森林防火领域模型与规则	已包含点位、水源、候选设施、通道、队伍和风险区模型
`internal/repository`	PostgreSQL/PostGIS 持久化适配	已实现 pgxpool、只读固定 SQL 与 schema/SRID readiness；实库 SRID 元数据、严格 readiness 和 7 个工具真实查询已验证
`cmd/postgis-srid-migrate`	显式 SRID 元数据迁移	已执行；默认只读预检，写入需独立迁移凭证和明确 CRS 确认
`internal/integration/superagent`	SuperAgent Open API 出站适配	已实现并通过模拟 Provider 测试，默认关闭
`cmd/superagent-probe`	无业务数据的显式连通性探针	已实现；需要项目专属测试配置
`cmd/postgis-probe`	不读取业务行的 PostGIS readiness 探针	已实现；需要只读数据库配置
`Dockerfile` / `compose.yaml`	测试环境容器构建与单实例进程托管	已建立；容器内监听 8080，只发布宿主机回环端口 16587；页面开关默认关闭；目标机镜像已构建，容器启动和 health 待重建后验证
`pkg`	可被外部 module 复用的稳定 Go API	当前为空
`docs/import`	字段/表映射、通用模板和本地数据库样例	样例 SQL 含受限数据并被 Git 忽略，不会执行
SuperAgent	对话理解、工具选择和答案组织	对话客户端按仓库内 2026-07-12 协议基线实现；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定启用/调用，证明其兼容档案不依赖版本配置；公网消防 `/mcp` 已收到一次请求并到达 Go，但旧版本门禁返回错误，消防兼容档案待部署验证，公网消防链路尚未调用数据库工具
PostgreSQL/PostGIS	消防空间业务事实的预期权威来源	8 表共 4,055 条记录；4,048 条非空几何已标记 EPSG:4326，严格 readiness 与本地真实工具冒烟均通过；35 条无效几何按当前策略排除并告警

3. 技术栈

已采用

Go module：fire-safety-ymd（临时 module 名）。
本地工具链：Go 1.26.6。
HTTP：Go 标准库 net/http。
测试：Go 标准库 testing、httptest。
配置：环境变量；支持 HTTP、SuperAgent、Chat、MCP 与 PostGIS 配置，并默认关闭 Chat 及两个外部方向。
Chat API：标准库 HTTP/SSE；原生 /api/chat 使用静态联调 Bearer，可选 completion 兼容入口使用同一信任方向的 xtoken；默认要求 Chat 凭证至少 32 个可打印 ASCII 字符，受控迁移时可通过默认关闭的 FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN 兼容已交付短凭证；两者共享精确 Origin、严格 JSON、总超时、有界单进程会话和同会话并发冲突。兼容入口只在严格成功后发送正文。可选测试页面由 FIRE_SAFETY_CHAT_PAGE_ENABLED 控制，提供 /chat（开启时 308 到 /chat/）、/chat/、/chat/app.css 和 /chat/app.js；页面只在内存中使用用户手动输入的 xtoken，复用兼容 SSE 的 session_id，不嵌入或持久化 Token。
SuperAgent：标准库 HTTP/SSE 客户端，分离 Session 创建和消息发送，支持严格完成判定与既有 Run 断流恢复。
MCP：标准库 HTTP/JSON-RPC，服务端固定返回版本标识 2025-06-18，同步 JSON 响应，独立 Bearer 和 7 个只读工具；按已稳定接通的 th-hotel-simple-superagent 兼容档案处理，initialize 中的 protocolVersion 和后续 MCP-Protocol-Version Header 都不作为版本拒绝门禁，SuperAgent 无需也不能配置版本。固定返回该版本不表示支持任意其他版本，也不是追求最新协议。地名工具只搜索现有业务记录并要求用户确认候选。
PostgreSQL：github.com/jackc/pgx/v5 v5.10.0 原生连接池；连接默认只读并设置 statement timeout。
PostGIS：ST_Covers、ST_DWithin、ST_Distance 和 ST_ClosestPoint；只在实库确认 EPSG:4326 后启用。
部署：多阶段 Docker 镜像与单实例 Compose；Secret 通过未提交的 .env 在运行时注入，容器内 8080 只发布到宿主机 127.0.0.1:16587，由宿主机 Nginx 终止 TLS。Docker build 的 Go module proxy 可按环境覆盖，但默认使用官方代理、保留 checksum 校验，且所选构建代理在运行容器内强制清空。Nginx 示例精确反代 /chat、/chat/、页面 CSS/JavaScript、兼容 completion 和 /mcp；页面仍由 Go 开关控制。

计划但尚未接入或确认

PostgreSQL/PostGIS 的适用索引和生产查询计划验证。
SuperAgent 到 /mcp 的 proven-profile 兼容实现部署后重测，以及 TLS、网络白名单、Token 和完整工具调用链联调；版本 Header 不需要配置，也不是验收门禁。
任意地址/山名的外部地理编码、别名词典和大数据量地名索引。
用户聊天的真实身份认证、动态授权、共享/持久会话、主动取消和限流策略；首版默认关闭的静态 Bearer + 内存会话 API 以及默认关闭的静态测试页面已实现。legacy 短凭证仅限受控测试/迁移窗口，轮换后须关闭兼容开关。
最终用户鉴权、动态角色/区域或租户隔离、持久审计与完整可观测性方案。
正式前端身份接入；当前 /chat 页面仅用于受控测试，现有第三方客户端仅通过受限 DashScope 风格协议适配。

4. 已知业务数据范围

当前资料描述 8 类森林防火空间资源：

资源	预期 PostgreSQL 表	预期几何形态
蓄水池	`st_2_xianyouxushuichiguan`	点
防火通道	`st_2_xianyoufanghuotongdao`	线；样例为 MultiLineString，原始数据混合二维与 Z 维度
水源地	`st_2_mpslfh_t_slfh_syd`	点
林区工矿企业	`st_2_linqugongkuangqiye`	面
防火网格	`st_2_fanghuowangge`	面
防火瞭望哨	`st_2_fanghuoliaowangshao`	点
防火检查站	`st_2_fanghuojianchazhan`	点
墓地坟区	`st_2_mudifenqu_mian`	面

仓库中的两份 Excel 是字段与数据表映射资料，不是可查询的业务数据库。docs/import/db-samples/*.sql 是含敏感字段的本地参考输入，已被 Git 忽略且不得由开发 Agent 执行。用户在 2026-09-04 的现场导入中确认，防火通道原始数据同时包含二维和带 Z 维度的几何：geometry(GEOMETRY) 导入到第 256 条附近时报 Geometry has Z dimension but column does not，将该原始列改为不限定 typmod 的 geometry 后重导成功。2026-09-05 的初始只读 audit 覆盖 8 表共 4,055 条记录：4,048 条非空几何均标记 SRID 0，7 条为空，35 条面几何无效，仅防火网格表存在 GiST 几何索引；类型和经纬度数值范围符合预期。数据提供方随后确认 8 表源数据均为 EPSG:4326、无坐标偏移，并允许 MCP 二维计算忽略 Z，但原始 Z 仍须保留。项目使用独立 admin 迁移凭证在单个事务中补齐了 4,048 条几何的 SRID 4326 元数据：7 张二维表改为 geometry(Geometry,4326)，防火通道保持裸 geometry 且 2 条 Z 几何未变；迁移前后无 SRID WKB 指纹、行数、类型、有效性和维度一致，随后只读严格 readiness 通过。无效几何仍不自动修复，查询排除并明确告警。

5. 目标职责边界

用户侧应用：采集用户输入并展示结果；仓库提供默认关闭的 /chat 受控测试页面，正式用户端形态仍待确认。
本 Go 服务：鉴权上下文、会话转发、MCP 工具、数据查询、权限、安全和审计。
SuperAgent：理解自然语言、决定是否调用工具、组织自然语言结果；页面和第三方客户端都通过同一兼容 completion SSE 入口发起对话。
MCP 工具：提供固定的森林防火领域查询，不开放任意 SQL 或跨权限访问。
PostgreSQL/PostGIS：保存和计算可信空间事实；资源是否可用仍取决于明确状态和数据时效。

6. 当前开发方向与非目标

当前阶段已有可运行、可测试、文档自解释的 Go 基线、SuperAgent Open API Adapter、默认关闭的原生用户对话 API、可选 DashScope 风格兼容入口、默认关闭的 /chat 测试页面，以及空间只读 MCP/PostGIS 实现。对话入口使用独立静态联调凭证和单进程内存会话；页面不嵌入或持久化 Token，使用者手动输入 xtoken 并复用同页面内存中的 session_id。仓库已有多阶段 Docker/Compose 基线以及精确路径、无 Secret 的 Nginx HTTPS 反向代理示例，模板公开反代 /chat、/chat/、/chat/app.css、/chat/app.js、兼容 completion 和 /mcp，页面是否可用由 Go 开关控制。目标机镜像构建和 Nginx 语法检查已由现场截图证明通过，容器稳定运行、页面公网响应和 TLS 实际状态仍待验证。2026-09-05 22:35 的现场日志已证明公网 MCP 完成 fire_safety_search_place_candidates 一次成功调用（此前的 initialize/notifications/tools/list 也有日志），但其余消防工具和完整多工具链仍待验收。同一 SuperAgent 中 th-hotel-simple-superagent 已稳定启用/调用，为本项目提供了 proven-profile 兼容参照，但不能替代消防 endpoint 的完整验收。部署后通过 direct_success 或 compatibility_success 日志分类确认实际请求，不记录客户端原始版本值。MCP 默认关闭，实库严格 readiness 和全部 7 个工具的本地真实查询已通过。下一阶段先在测试服务器验证页面开关、静态资源、兼容 Chat 首轮/多轮和公网 TLS，再完成真实消防 Profile 的完整 MCP 工具链联调。

本阶段不实现：

面向真实用户的认证、动态权限、持久会话和已验证生产能力；当前对话 API 与 /chat 页面只用于受控联调。
PostgreSQL/PostGIS 数据导入或索引 DDL；SRID 元数据迁移是已经显式执行的一次受控运维操作，不是应用运行时行为。
用户登录、权限模型、审计存储和生产部署。
面向真实火情的自动决策或路径规划。
队伍实时定位、集结点管理和资源调度。

7. 新 Agent 阅读顺序

AGENTS.md
CONTEXT.md
PROJECT_STATE.md
docs/project/README.md
docs/project/ai-nses-project-overlay.md
与任务相关的后端或安全规范

12 KiB Raw Blame History Unescape Escape