tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity

docs: 新增 AI Agent 维护SOP与AI优化规划

Browse Source
This commit is contained in:
tangweijie 2026-03-11 11:50:01 +08:00
parent df537a6831
commit 1868456215
4 changed files with 291 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
00_Management/01_Project_Progress.md
View File

@ -111,6 +111,8 @@
| 变更时间 | 变更类型 | 变更内容 | 变更原因 | 影响评估 |
| ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 2026-03-11 | AI 文档优化专项规划 | 新增 `00_Management/09_AI_Document_Optimization_Plan.md`，形成 4 周可执行优化方案（2026-03-12 至 2026-04-08），明确现状基线、阶段目标、交付物、验收指标与风险应对；重点覆盖目录索引补齐、主文档 Front Matter 标准化、超长文档可检索化与 AI 抽检门禁固化 | 用户要求“规划文档是否对 AI 优化”，需要将现状评估转化为可执行的阶段计划与量化验收标准 | 正面影响，AI 文档治理从“规则存在”升级为“按周推进 + 指标验收”的专项机制，可提升 AI 检索命中率、降低历史文档干扰并增强跨代理一致性 |
| 2026-03-11 | AI Agent 维护SOP落地 | 新增 `00_Management/08_AI_Agent_Maintenance_SOP.md`，定义 AI Agent 在本仓库的目标范围、执行前检查、普通任务与结构任务流程、冲突优先级、质量门禁与提交规范；与现有目录治理基线、迁移模板和 pre-commit 校验形成闭环 | 用户要求提供“一份适用于 AI Agent 的项目维护方式”，需要形成可直接执行的标准操作流程 | 正面影响，AI Agent 执行路径从“经验驱动”升级为“规则驱动 + 流程驱动”，可降低误改风险、提升跨代理一致性与维护可追溯性 |
| 2026-03-11 | 目录治理工程化基线落地 | 新增 `00_Management/06_Directory_Governance_Baseline.md`（目录治理基线清单）与 `00_Management/07_Migration_Mapping_Template.md`（迁移映射模板），明确主文档单一真源、Archive 边界、目录命名规则、迁移流程、门禁指标及角色责任；新增 `.pre-commit-config.yaml` 与 `scripts/precommit-validate-markdown.sh`，将 `make validate-file`、`make check-links`、`make validate-mermaid` 纳入提交前/推送前校验草案 | 用户要求提供“可执行的目录治理方案”，并确认需要直接落地模板与自动化校验入口 | 正面影响，目录治理从“规则说明”升级为“可执行流程 + 模板 + 工具门禁”；可显著降低平行版本扩散、链接失效和图文不一致风险，提升后续文档维护效率与交付稳定性 |
| 2026-03-10 | 统一主详设整编 | 将 `02_Detailed/01_Detailed_Design.md` 重构为统一《福建水务营收系统详细设计说明书》，整合模块设计、CA电子签章、数据库、接口、安全、部署等分散文档内容；统一系统名称、章节体系、模块/接口编号及数据库口径为达梦数据库 8.0+，并清理部署章节残留脚本碎片 | 用户要求以唯一主详设文件完成整编交付，避免多份详设并存、章节口径不一致及旧数据库表述残留 | 正面影响，主详设结构更完整统一，可直接交付实施，数据库与章节口径一致，后续维护与评审成本显著降低 |
| 2026-03-10 | Archive归档整理 | 重组 `04_Appendix/Archive/` 历史资料目录，按需求、操作手册、历史设计、原始附件、数据字典、整合资料分层归档；迁移 Markdown 与配套 `_images` 目录；同步修正 `00_Management/04_Writing_Guide.md` 中数据字典旧路径引用 | 用户要求提升历史资料可检索性，明确 Archive 职责边界，并避免图片相对路径失效与旧引用残留 | 正面影响，历史资料结构更清晰，检索效率提升，引用路径与目录职责统一，降低后续维护成本 |

34
00_Management/03_Task_Checklist.md
View File

@ -174,6 +174,40 @@
- [x] 新增 `scripts/precommit-validate-markdown.sh`，支持按本次变更文件逐一执行 `make validate-file` ✅
- [x] 更新项目进度文件记录本次目录治理工程化动作 ✅
## ✅ 最新完成任务 (AI Agent 维护SOP)
### 📋 AI Agent 标准维护方式落地
- [x] **新增 AI Agent 维护SOP 文档** ✅ (2026-03-11)
- [x] 新增 `00_Management/08_AI_Agent_Maintenance_SOP.md`，定义 AI Agent 目标范围、角色边界、执行前检查、任务流程与决策规则 ✅
- [x] 明确普通维护任务与结构治理任务的可执行步骤与校验命令 ✅
- [x] 固化 AI Agent 质量门禁（断链、Mermaid、平行稿、口径冲突、台账同步） ✅
- [x] 补充提交规范与周期化巡检节奏，便于团队长期执行 ✅
- [x] 更新项目进度文件记录本次 SOP 落地动作 ✅
## ✅ 最新完成任务 (AI 文档优化规划)
### 📋 AI 文档优化专项计划建立
- [x] **新增 AI 文档优化规划文档** ✅ (2026-03-11)
- [x] 新增 `00_Management/09_AI_Document_Optimization_Plan.md`，明确当前 AI 友好性短板与基线指标 ✅
- [x] 输出 4 周执行计划（2026-03-12 至 2026-04-08），覆盖目录索引、Front Matter、长文档可检索化与门禁固化 ✅
- [x] 定义量化验收指标（README 覆盖率、Front Matter 覆盖率、一致性抽检、断链与 Mermaid 指标） ✅
- [x] 明确专项 Backlog 优先级（P0/P1/P2）与风险应对策略 ✅
- [x] 更新项目进度文件记录本次专项规划动作 ✅
## 🚧 当前推进任务 (AI 文档优化专项)
- [ ] **第 1 周：检索入口标准化**（截至 2026-03-18）
- [ ] 补齐一级目录 `README.md` 索引（7/7）
- [ ] 形成 AI 检索优先白名单清单
- [ ] **第 2 周：主文档元数据统一**（截至 2026-03-25）
- [ ] 六个主文档补齐 Front Matter 标准字段
- [ ] **第 3 周：长文档可检索化**（截至 2026-04-01）
- [ ] 建立超长主文档章节锚点导航与定位表
- [ ] **第 4 周：门禁与抽检固化**（截至 2026-04-08）
- [ ] 建立每周 AI 抽检记录模板并首次执行
## ✅ 最新完成任务 (2024-12-19)
### 📋 新增引言文档

92
00_Management/08_AI_Agent_Maintenance_SOP.md Normal file
View File

@ -0,0 +1,92 @@
# 福建水务营收系统 AI Agent 维护SOP
## 1. 目标与适用范围
- 目标：让 AI Agent 在本仓库内稳定执行“文档维护、口径对齐、引用修复、台账同步”。
- 适用范围：仓库内全部 Markdown 正式文档及管理文档。
- 维护原则：主文档优先、Archive 归档隔离、可追溯、可校验。
## 2. AI Agent 角色定义
- 角色定位：文档架构师 + 一致性审校者 + 保守补完编辑者。
- 非目标行为：擅自发明业务规则、无依据扩展技术细节、批量制造新版本文件。
## 3. 执行前检查（必须）
每次任务开始前，AI Agent 必须先读取：
1. `00_Management/01_Project_Progress.md`
2. `00_Management/02_Delivery_Standards.md`
3. `00_Management/03_Task_Checklist.md`
4. 与任务直接相关的目标文档
结构性调整任务需额外读取：
- `00_Management/04_Writing_Guide.md`
- `docs/guides/BACKEND_CURRENT_STATUS.md`
- `docs/guides/BACKEND_TABLE_MAPPING.md`
## 4. 标准执行流程
### 4.1 普通维护任务（术语、编号、链接、图文一致）
1. 识别修改范围（文档路径、章节、受影响引用）。
2. 优先修改主文档，不新建平行版本。
3. 同步修复文内目录、交叉引用、图表描述一致性。
4. 执行最小校验：
- `make validate-file FILE=<目标文件>`
5. 如涉及跨文档引用或图表，追加：
- `make check-links`
- `make validate-mermaid`
6. 更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`（适用时）。
### 4.2 结构性治理任务（迁移、重命名、归档整理）
1. 先创建迁移批次，使用 `00_Management/07_Migration_Mapping_Template.md`。
2. Markdown 与同名 `_images/` 目录成组处理。
3. 修复全部受影响相对路径。
4. 完整执行校验：
- `make validate-file FILE=<目标文件>`
- `make check-links`
- `make validate-mermaid`
5. 在 `01_Project_Progress.md` 登记“变更内容/原因/影响评估”。
## 5. AI Agent 决策规则
- 信息冲突时优先级：
1. 用户当次明确要求
2. 主文档既有统一口径
3. `docs/guides/` 最新映射文档
4. `04_Appendix/Archive/` 历史资料
- 无依据时默认“保守不扩写”，先做结构与一致性修复。
- 涉及高风险调整（编号体系、数据库口径、模块拆分）时，先给出影响面再执行。
## 6. 质量门禁（AI Agent 必须满足）
- 断链数量 = 0
- Mermaid 语法错误 = 0
- 平行正式稿新增数量 = 0
- 关键口径冲突数量 = 0（系统名称、数据库口径、编号规则）
- 结构变更台账同步率 = 100%
## 7. 提交规范
- 建议提交信息格式：`docs: <动作> + <对象>`
- 单次提交聚焦单一主题（如“目录治理基线”“接口编号统一”）。
- 提交前应通过本次改动对应的 `pre-commit` 校验。
## 8. 周期化维护节奏（建议）
- 每周：口径巡检（系统名称/数据库口径/IF 编号）。
- 每双周：结构巡检（目录职责/冗余文件/引用有效性）。
- 每月：Archive 清理与来源追溯补全。
## 9. 交付输出模板（AI Agent 回答格式）
AI Agent 输出建议最少包含：
1. 本次修改文件清单
2. 修改摘要（做了什么）
3. 校验结果（执行了哪些命令）
4. 剩余风险与下一步建议

163
00_Management/09_AI_Document_Optimization_Plan.md Normal file
View File

@ -0,0 +1,163 @@
# 福建水务营收系统文档 AI 优化规划
## 1. 文档信息
| 项目 | 内容 |
| --- | --- |
| 项目名称 | 福建水务营收系统 |
| 文档类型 | AI 优化规划 |
| 版本 | v1.0 |
| 状态 | 规划中（可执行） |
| 编制日期 | 2026-03-11 |
## 2. 现状评估（截至 2026-03-11）
### 2.1 已具备能力
- 已建立仓库级代理约束：`AGENTS.md`
- 已建立 AI Agent 执行流程：`00_Management/08_AI_Agent_Maintenance_SOP.md`
- 已建立目录治理基线与迁移模板：`00_Management/06_Directory_Governance_Baseline.md`、`00_Management/07_Migration_Mapping_Template.md`
- 已接入提交前/推送前校验：`.pre-commit-config.yaml`
### 2.2 主要短板
- Markdown 总量较大，历史与正式文档混杂，AI 检索优先级不够明确。
- 一级目录缺少目录级 `README.md` 索引入口。
- 主文档尚未统一机器可读元数据（Front Matter）。
- 超长主文档存在上下文过长问题，影响 AI 精准检索与引用定位。
### 2.3 基线指标（脚本盘点）
- Markdown 文件总数：120
- 一级目录 README 覆盖率：0/7
- 主文档 Front Matter 覆盖率：0/6
- 超长文档（>1500 行）示例：
- `01_High_Level/03_Summary_Design.md`
- `03_Technical/01_Database_Design.md`
- `04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
## 3. 优化目标（2026-03-12 至 2026-04-08）
- 目标 1：建立 AI 优先检索路径，减少历史资料干扰。
- 目标 2：建立统一文档元数据，提升机器可读性与可路由性。
- 目标 3：降低超长文档理解成本，提升跨文档定位效率。
- 目标 4：将 AI 质量门禁纳入常态化维护流程。
## 4. 分阶段执行计划（4 周）
### 第 1 周（2026-03-12 ~ 2026-03-18）：检索入口标准化
交付物：
- 一级目录 `README.md` 索引模板与落地：
- `00_Management/README.md`
- `01_High_Level/README.md`
- `02_Detailed/README.md`
- `03_Technical/README.md`
- `04_Appendix/README.md`
- `docs/README.md`
- `scripts/README.md`
- AI 检索优先白名单（主文档 + 管理基线）清单文档。
验收指标：
- 一级目录 README 覆盖率达到 100%。
### 第 2 周（2026-03-19 ~ 2026-03-25）：主文档元数据统一
交付物：
- 为六个主文档增加统一 Front Matter 字段：
- `doc_id`
- `doc_role`
- `authority`
- `scope`
- `source_of_truth`
- `last_reviewed`
- 形成《Front Matter 字段规范》并纳入管理文档。
验收指标：
- 主文档 Front Matter 覆盖率达到 100%。
### 第 3 周（2026-03-26 ~ 2026-04-01）：长文档可检索化改造
交付物：
- 为超长主文档建立“主索引 + 章节锚点”导航层（不破坏主文档唯一真源）。
- 输出关键章节定位表（章节编号、标题、路径、锚点）。
验收指标：
- 超长主文档关键章节可在 3 次跳转内定位。
### 第 4 周（2026-04-02 ~ 2026-04-08）：门禁与抽检固化
交付物：
- 将 AI 专项检查加入日常巡检清单（术语、编号、口径、链接、图表）。
- 建立每周 AI 抽检记录模板（问题、修复、复盘）。
验收指标：
- 抽检一致性 ≥ 95%（系统名称、数据库口径、接口编号）。
- 断链 = 0、Mermaid 错误 = 0。
## 5. 任务优先级（Backlog）
### P0（必须优先）
- 一级目录 `README.md` 索引补齐。
- 主文档 Front Matter 标准化。
- AI 检索优先白名单建立。
### P1（应在本轮完成）
- 超长文档章节锚点与导航增强。
- 跨文档术语映射与统一入口完善。
### P2（可持续优化）
- 归档文档标签化（来源、用途、可信级别）。
- AI 抽检自动化脚本（输出差异清单）。
## 6. 验收与校验命令
每次改动至少执行：
- `make validate-file FILE=<目标文件>`
跨文档改动必须追加：
- `make check-links`
- `make validate-mermaid`
发布前建议执行：
- `pre-commit run --files <变更文件列表>`
- `pre-commit run --hook-stage pre-push --all-files`
## 7. 风险与应对
| 风险 | 触发场景 | 应对策略 |
| --- | --- | --- |
| 历史资料干扰 AI 检索 | 归档文档与主文档命名相似 | 白名单优先检索 + 目录索引声明权威来源 |
| 文档拆分导致引用失效 | 章节重构或命名调整 | 先建映射表，再执行迁移并跑全量链接校验 |
| 规则过严影响效率 | 校验覆盖范围过大 | 分层校验：提交前最小校验、推送前全量校验 |
## 8. 组织与责任
- 文档负责人：确认优化范围、审批口径变更。
- AI 执行人：按本规划实施与自检。
- 复核人：按门禁指标验收并记录问题闭环。
## 9. 完成标准（Definition of Done）
同时满足以下条件视为本轮 AI 文档优化完成：
- 一级目录 README 覆盖率 = 100%
- 主文档 Front Matter 覆盖率 = 100%
- 断链 = 0
- Mermaid 错误 = 0
- 口径一致性抽检通过率 ≥ 95%