huangting/fire-safety-ymd
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8a6c31c14d233ef8d269bcc8c4f5f7129a8d53d6
fire-safety-ymd/CONTEXT.md
T
andy 8a6c31c14d 初始化第一版
2026-09-05 15:46:37 +08:00

8.6 KiB
Raw Blame History

fire-safety-ymd 项目上下文

1. 项目目标

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

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

2. 当前系统组成

路径或系统 当前职责 当前状态
cmd/server Go 服务进程入口 已建立
internal/app 应用装配、readiness 和 HTTP 生命周期 已建立；按开关装配原生/兼容 Chat、SuperAgent 和 MCP/PostGIS
internal/config 环境配置入口 已包含 HTTP、SuperAgent、Chat 兼容 App ID、MCP 与 PostGIS 配置校验和凭证分离门禁
internal/handler HTTP/MCP 入站协议层 GET /health 已启用；默认关闭的原生 /api/chat、可选 DashScope 风格 completion 和 /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 测试环境容器构建与单实例进程托管 已建立；只发布宿主机回环端口，目标服务器尚未验证
pkg 可被外部 module 复用的稳定 Go API 当前为空
docs/import 字段/表映射、通用模板和本地数据库样例 样例 SQL 含受限数据并被 Git 忽略，不会执行
SuperAgent 对话理解、工具选择和答案组织 已按仓库内 2026-07-12 协议基线实现客户端；当前环境待联调
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；两者共享精确 Origin、严格 JSON、总超时、有界单进程会话和同会话并发冲突。兼容入口只在严格成功后发送正文。
  • SuperAgent：标准库 HTTP/SSE 客户端，分离 Session 创建和消息发送，支持严格完成判定与既有 Run 断流恢复。
  • MCP：标准库 HTTP/JSON-RPC，协议基线 2025-06-18，同步 JSON 响应，独立 Bearer 和 7 个只读工具；地名工具只搜索现有业务记录并要求用户确认候选。
  • 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 在运行时注入，应用端口只发布到宿主机 127.0.0.1:8080，由宿主机 Nginx 终止 TLS。

计划但尚未接入或确认

  • PostgreSQL/PostGIS 的适用索引和生产查询计划验证。
  • SuperAgent 到 /mcp 的真实网络、TLS、Header 与 Token 联调。
  • 任意地址/山名的外部地理编码、别名词典和大数据量地名索引。
  • 用户聊天的真实身份认证、动态授权、共享/持久会话、主动取消和限流策略；首版默认关闭的静态 Bearer + 内存会话 API 已实现。
  • 最终用户鉴权、动态角色/区域或租户隔离、持久审计与完整可观测性方案。
  • 正式前端身份接入；现有客户端仅通过受限 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. 目标职责边界

  • 用户侧应用：采集用户输入并展示结果；具体形态待确认。
  • 本 Go 服务：鉴权上下文、会话转发、MCP 工具、数据查询、权限、安全和审计。
  • SuperAgent：理解自然语言、决定是否调用工具、组织自然语言结果。
  • MCP 工具：提供固定的森林防火领域查询，不开放任意 SQL 或跨权限访问。
  • PostgreSQL/PostGIS：保存和计算可信空间事实；资源是否可用仍取决于明确状态和数据时效。

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

当前阶段已有可运行、可测试、文档自解释的 Go 基线、SuperAgent Open API Adapter、默认关闭的原生用户对话 API、可选 DashScope 风格兼容入口，以及空间只读 MCP/PostGIS 实现。对话入口使用独立静态联调凭证和单进程内存会话；仓库已有多阶段 Docker/Compose 基线以及精确路径、无 Secret 的 Nginx HTTPS 反向代理示例，但尚未在目标机验证。MCP 默认关闭，实库严格 readiness 和全部 7 个工具的本地真实查询已通过。下一阶段在测试服务器应用这些部署资产，并使用真实消防 Profile 联调公网对话与 MCP。

本阶段不实现：

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

7. 新 Agent 阅读顺序

  1. AGENTS.md
  2. CONTEXT.md
  3. PROJECT_STATE.md
  4. docs/project/README.md
  5. docs/project/ai-nses-project-overlay.md
  6. 与任务相关的后端或安全规范
Reference in new issue View Git Blame Copy Permalink