diff --git a/00_Management/01_Project_Progress.md b/00_Management/01_Project_Progress.md index dbc8581..fb031bb 100644 --- a/00_Management/01_Project_Progress.md +++ b/00_Management/01_Project_Progress.md @@ -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 职责边界，并避免图片相对路径失效与旧引用残留 | 正面影响，历史资料结构更清晰，检索效率提升，引用路径与目录职责统一，降低后续维护成本 | diff --git a/00_Management/03_Task_Checklist.md b/00_Management/03_Task_Checklist.md index 6e70721..a526521 100644 --- a/00_Management/03_Task_Checklist.md +++ b/00_Management/03_Task_Checklist.md @@ -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) ### 📋 新增引言文档 diff --git a/00_Management/08_AI_Agent_Maintenance_SOP.md b/00_Management/08_AI_Agent_Maintenance_SOP.md new file mode 100644 index 0000000..348cb5c --- /dev/null +++ b/00_Management/08_AI_Agent_Maintenance_SOP.md @@ -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. 剩余风险与下一步建议 + diff --git a/00_Management/09_AI_Document_Optimization_Plan.md b/00_Management/09_AI_Document_Optimization_Plan.md new file mode 100644 index 0000000..b4d03cb --- /dev/null +++ b/00_Management/09_AI_Document_Optimization_Plan.md @@ -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% +