86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# AI-NSES 采用说明
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 项目 | `fire-safety-ymd` |
|
||
| 采用日期 | 2026-09-04 |
|
||
| 通用标准版本 | AI-NSES 0.2 |
|
||
| 当前采用阶段 | Active development |
|
||
|
||
## 1. 目标
|
||
|
||
本项目采用 AI-NSES，将长期项目知识保存在仓库中，使人类开发者和新的 Agent 不依赖历史会话也能理解当前目标、代码边界、风险和下一步。
|
||
|
||
通用标准保持原样，项目差异放在根入口和 `docs/project/ai-nses-project-overlay.md`，避免 fire-safety-ymd 的规则反向污染可复用模板。
|
||
|
||
## 2. 本次接入的通用文件
|
||
|
||
模板来源快照：`/Users/andy/IdeaProjects/th-hotel-simple/docs/import/reusable`。
|
||
|
||
仅接入以下白名单内容：
|
||
|
||
- `docs/import/reusable/ai-native-software-engineering-standard.md`
|
||
- `docs/import/reusable/general-development-guidelines.md`
|
||
- `docs/import/reusable/ai-native-templates/` 全目录
|
||
|
||
它们作为通用参考和新文档模板保存，不直接承担本项目当前状态说明。
|
||
|
||
## 3. 明确排除的来源内容
|
||
|
||
没有复制以下内容：
|
||
|
||
- TH Hotel 的 `docs/project/`。
|
||
- TH Hotel 的根 `AGENTS.md`、`CONTEXT.md`、`PROJECT_STATE.md`。
|
||
- reusable 目录中的 Java、Spring、MyBatis、前端、分页基础结构和特定集成指南。
|
||
- reusable 根 `README.md`，因为本 checkpoint 的复制白名单未包含它。
|
||
|
||
本仓库的项目级文档均按森林防火、Go、SuperAgent、MCP 和 PostGIS 的实际已知边界重新编写。
|
||
|
||
## 4. AI-NSES 目录映射
|
||
|
||
| AI-NSES 职责 | fire-safety-ymd 位置 | 采用状态 |
|
||
| --- | --- | --- |
|
||
| Agent 工作入口 | `AGENTS.md` | 已采用 |
|
||
| 长期项目背景 | `CONTEXT.md` | 已采用 |
|
||
| 动态项目状态 | `PROJECT_STATE.md` | 已采用 |
|
||
| 项目文档索引 | `docs/project/README.md` | 已采用 |
|
||
| 项目覆盖规则 | `docs/project/ai-nses-project-overlay.md` | 已采用 |
|
||
| 长期工程规范 | `docs/project/backend-development-guidelines.md` | 已采用 |
|
||
| 安全与权限边界 | `docs/project/security-access-control-boundary.md` | 已采用；Chat 静态联调门禁与 MCP 服务账号边界已实现，最终用户机制待设计 |
|
||
| Domain 文档 | `docs/domain/` | 按需创建 |
|
||
| Architecture 文档 | `docs/architecture/` | 已采用；已有原生/兼容用户对话入口和空间只读 MCP v1 |
|
||
| Workflow 文档 | `docs/workflows/` | 已采用；已有用户对话和演练方案证据查询流程 |
|
||
| ADR | `docs/adr/` | 首个架构决策时创建 |
|
||
| Spec | `docs/specs/` | 已采用；已有原生/兼容用户对话 API、SuperAgent Open API 与空间只读 MCP Spec |
|
||
|
||
Go 源码使用 `cmd/`、`internal/` 和 `pkg/`，这是通用标准中 `src/` 的项目级映射。
|
||
|
||
## 5. 项目 Definition of Ready
|
||
|
||
跨模块、数据、权限、安全或外部平台的 Feature 进入实现前必须明确：
|
||
|
||
- 目标、非目标、调用方和可测试验收标准。
|
||
- SuperAgent 或 MCP 的真实契约来源，不依据记忆猜测字段。
|
||
- 身份、区域或租户范围如何进入可信服务端上下文。
|
||
- PostgreSQL 表、字段、几何类型、SRID、数据时效和权限是否已经核验。
|
||
- 错误、超时、重试、幂等、审计和敏感信息处理方式。
|
||
- 所需测试层级和可用测试环境。
|
||
|
||
## 6. 项目 Definition of Done
|
||
|
||
Feature 完成时至少满足：
|
||
|
||
- 代码已 `gofmt`，相关测试和 `go test ./...` 已运行，或明确记录阻塞原因。
|
||
- 接口只返回被授权、可追踪且不泄露敏感信息的数据。
|
||
- 数据和空间计算结论有实际验证依据，没有把待确认项写成事实。
|
||
- 相关 Spec、ADR、Workflow、安全文档和 `PROJECT_STATE.md` 已同步。
|
||
- 没有引入 Secret、真实敏感样本、构建产物或无关用户改动。
|
||
- 交付说明包含变更清单、验证结果、剩余风险和下一 checkpoint。
|
||
|
||
## 7. 维护方式
|
||
|
||
- 通用 AI-NSES 升级时先比较上游快照，再单独做文档升级 checkpoint。
|
||
- 项目规则只修改项目入口或 Overlay，不直接编辑通用快照。
|
||
- `PROJECT_STATE.md` 每个 checkpoint 更新；稳定背景变化时才更新 `CONTEXT.md`。
|
||
- 采用状态或目录映射变化时更新本文。
|