fire-safety-ymd 项目协作与开发规范

1. 必读入口

开始任务前按顺序阅读：

AGENTS.md
CONTEXT.md
PROJECT_STATE.md
docs/project/README.md
与任务相关的项目文档、Spec、ADR 或 Workflow

通用标准位于：

docs/import/reusable/ai-native-software-engineering-standard.md
docs/import/reusable/general-development-guidelines.md

项目规则与通用标准冲突时，以用户当前明确要求和 docs/project/ai-nses-project-overlay.md 中更具体的项目约束为准。

2. 项目定位

本仓库建设一个 Go 后端，负责连接用户侧应用与既有 SuperAgent 平台，并通过受控 MCP 工具向 Agent 提供森林防火业务数据。PostgreSQL/PostGIS 是空间业务事实的预期权威来源，SuperAgent 负责理解问题、选择工具和组织回答。

当前已完成项目骨架、GET /health、默认关闭的原生用户对话 API、可选 DashScope 风格兼容对话入口、SuperAgent Open API 出站适配器，以及默认关闭的空间只读 MCP/PostGIS 基线。对话入口只有独立静态联调凭证和单进程内存会话，不是最终用户认证；兼容 SSE 只在严格成功后返回正文。仓库已有多阶段 Docker/Compose 测试部署基线和把 agent.nianxx.com 精确反代到本 Go 服务的 Nginx 示例；容器端口只发布到宿主机回环地址，目标服务器和公网链路尚未验证。MCP 具备 7 个固定工具（含地名候选搜索）、独立 Bearer、显式服务端数据范围（数据库全范围或镇街白名单）、readiness 校验和只读参数化查询。数据提供方确认源数据为 EPSG:4326 且无偏移；2026-09-05 已通过受控事务为 4,048 条非空几何补齐 SRID 4326 元数据，严格 readiness 和 7 个工具的本地真实数据库冒烟测试均已通过，但真实消防 Profile 对话、公网部署与 SuperAgent 回调联调尚未完成。地名候选必须由用户确认，不要把查询成功当成资源可用性、路线、实时队伍位置或生产鉴权已经验证。

3. 默认工作方式

先确认 checkpoint 的目标、边界、验收标准和允许的写操作。
修改前检查 Git 状态，保留用户已有变更，不回滚、不覆盖、不顺手整理无关文件。
一次只完成一个明确 checkpoint；新需求进入 Spec、Change Request 或下一个 checkpoint。
先读现有接口和项目文档，再新增抽象或依赖。
对未确认的外部接口、数据结构、坐标系、权限规则和部署条件明确标记 待确认，不得猜测为事实。
完成后报告变更、验证命令、验证结果、未确认项和建议下一步。
除非用户明确要求，不自动创建提交、推送、迁移生产数据或调用外部系统写接口。

4. Go 工程规则

使用 gofmt 作为唯一基础格式化标准，变更后至少执行 go test ./...。
cmd/server 只负责进程启动、信号和依赖装配，不放业务规则。
internal/handler 负责 HTTP/MCP 入站契约、输入校验和响应映射。
internal/service 编排用例；internal/domain 保存稳定领域概念与规则。
internal/repository 保存持久化适配器和确实稳定的仓储契约，不允许 Handler 直连数据库。
internal/config 集中读取、默认值处理和配置校验；业务代码不散落读取环境变量。
pkg 只放确实需要被其他 Go module 导入的稳定 API；没有明确复用方时优先放入 internal。
接口应小且由使用方定义；依赖通过构造函数显式注入，避免全局可变状态和隐藏初始化。
错误必须携带上下文并使用 %w 保留错误链；正常业务失败不使用 panic。
先使用标准库；引入框架或第三方依赖前记录用途、维护状态和替代方案。

完整后端规则见 docs/project/backend-development-guidelines.md。

5. 数据、AI 与安全边界

不允许 Agent 执行任意 SQL；MCP 只暴露固定、参数化、可授权和可审计的领域工具。
用户身份、租户/区域范围和角色来自可信服务端上下文，不接受模型自由填写这些授权参数。
未确认 SRID 前不得上线空间距离或包含关系计算；不得把 WKB 坐标数值猜测直接升级为数据库事实。
**原始几何维度不得被静默降维：**用户现场导入已确认 st_2_xianyoufanghuotongdao.geom 同时存在二维和带 Z 维度的几何；原导出声明 geometry(GEOMETRY) 会以二维 typmod 拒绝 Z 记录（PostgreSQL 错误 22023）。该表的原始导入列必须保持为不限定 typmod 的 geometry，除非另有经过审查的数据迁移决定。
未经用户或数据所有者明确授权，不得对原始表执行 ST_Force2D、重写 WKB 或以其他方式丢弃 Z。若 MCP 算法只接受二维数据，应在只读查询/派生层显式投影并记录语义，不得修改原始事实。几何维度与 SRID 是两件事；成功容纳 Z 不代表坐标系已确认为 EPSG:4326。
实库已发现 35 条无效面几何。当前决策是不自动修复或覆盖原始几何：readiness 明确告警，所有 MCP 查询使用 ST_IsValid 排除，工具响应提示结果可能不完整。SRID、坐标范围和几何类型仍是启用 MCP 的硬门禁。
不把资源记录存在等同于设备当前可用；返回值需要能表达来源、更新时间、不确定性和现场确认要求。
联系人、电话、精确位置、访问令牌和数据库凭证按敏感信息处理，不进入普通日志或模型无权限上下文。
AI 生成内容是辅助信息，不能虚构现场状态，也不能替代报警、人员撤离和现场指挥。

完整边界见 docs/project/security-access-control-boundary.md。

6. 常用命令

gofmt -w ./cmd ./internal
go test ./...
go vet ./...
go run ./cmd/server
curl -i http://localhost:8080/health
# 仅在只读 PostGIS 配置已显式加载时：
go run ./cmd/postgis-probe
# 仅使用临时表所有者/迁移凭证，详见项目 operations 文档：
go run ./cmd/postgis-srid-migrate
# 仅在项目专属测试凭证已配置时：
go run ./cmd/superagent-probe

默认监听地址为 :8080，可通过 FIRE_SAFETY_HTTP_ADDR 覆盖。Secret 只允许放在环境变量或未提交的 .env 文件中。

docs/import/db-samples/*.sql 含受限联系人和破坏性导出 DDL，已被 Git 忽略；只能只读分析，不得执行、提交或复制到测试输出。

7. 文档完成条件

每个 Feature 或 checkpoint 完成前检查：

PROJECT_STATE.md 是否反映真实状态。
Domain、Architecture、Workflow、ADR、Spec 是否需要新增或更新。
接口、安全、权限、审计、外部系统和数据契约是否同步。
验证命令和已知限制是否有可追踪记录。

没有文档变化时，交付说明中明确写 No documentation changes required.。

8. 多 Agent 协作

使用多 Agent 工作流时：

主线程拆分任务、分配互不重叠的文件所有权并负责最终整合。
边界明确、可独立完成的任务优先交给 luna_worker；需要修改代码且判断要求较高的任务交给 sol_worker。
同一个文件同一时间只能由一个写入 Agent 负责，所有 Agent 必须保留他人的现有修改。
实现结束后由 sol_reviewer 只读验证，并明确返回 PASS 或 FAIL。
最多并行启动 6 个子 Agent；运行时上限更低时按实际上限执行。
主线程等待所有子 Agent 返回后再统一总结。

7.4 KiB Raw Permalink Blame History Unescape Escape