252 lines
8.9 KiB
Markdown
252 lines
8.9 KiB
Markdown
# 📋 MD 文档维护优化 - AI Agent 分工方案
|
||
|
||
> **文档定位**：本文档定义多 AI Agent 协同维护优化项目 MD 文档的分工矩阵、协作流程与验收标准。
|
||
> **适用范围**：docs/ 目录下所有 .md 文档的维护、更新与优化工作。
|
||
|
||
---
|
||
|
||
## 1. 文档分类与工作量评估
|
||
|
||
### 1.1 文档分类矩阵
|
||
|
||
| 分类 | 文档数量 | 维护频率 | 复杂度 |
|
||
|-----|---------|---------|-------|
|
||
| **benchmarks/** | 1 (综合文档) | 低 | 中 |
|
||
| **blueprints/** | 6 | 中 | 高 |
|
||
| **blueprints/frontend-integration/** | 60+ | 高 | 中 |
|
||
| **design/** | 4 | 中 | 中 |
|
||
| **governance/** | 4 | 高 | 高 |
|
||
| **guides/** | 3 | 中 | 低 |
|
||
| **quality/** | 3 | 低 | 低 |
|
||
|
||
### 1.2 优化工作类型
|
||
|
||
| 工作类型 | 描述 | 预估工作量 |
|
||
|---------|-----|----------|
|
||
| **内容校准** | 修正过时信息、补充缺失内容 | 40% |
|
||
| **格式规范** | 统一文档格式、命名规范 | 20% |
|
||
| **关联更新** | 同步关联文档、交叉引用 | 15% |
|
||
| **质量提升** | 补充示例、完善细节 | 15% |
|
||
| **架构演进** | 适配新功能、新需求 | 10% |
|
||
|
||
---
|
||
|
||
## 2. AI Agent 分工矩阵
|
||
|
||
> 基于项目现有的 **三 AI 协作模式**，将文档维护任务按职责域进行分配。
|
||
|
||
### 2.1 分工概览
|
||
|
||
| Agent | 职责域 | 文档范围 | 核心能力 |
|
||
|-------|-------|---------|---------|
|
||
| **AI-1 (Kernel)** | 基础设施与内核文档 | blueprints/, design/ | 架构设计、技术规范 |
|
||
| **AI-2 (Internal)** | 内部支撑与集成文档 | governance/, benchmarks/ | 分析能力、关联梳理 |
|
||
| **AI-3 (Biz)** | 业务与前端集成文档 | frontend-integration/, guides/, quality/ | 业务理解、用户体验 |
|
||
|
||
### 2.2 详细分工
|
||
|
||
#### 🔧 AI-1 (Kernel) - 基础设施与架构文档
|
||
|
||
| 任务分类 | 具体文档 | 工作内容 |
|
||
|---------|---------|---------|
|
||
| **架构蓝图** | arch-overview-v30.md, arch-freeze-v30.md, v30-arch-optimization-plan.md | 校准技术架构描述、同步最新变更 |
|
||
| **前端架构** | frontend-architecture.md | 更新技术栈、补充新特性 |
|
||
| **全局蓝图** | global-business-blueprint.md | 业务架构演进同步 |
|
||
| **设计文档** | server-initiation.md, extension-initiation.md, console-pipeline-log-design.md | 技术规范更新 |
|
||
| **新增文档** | industry-benchmarks-comprehensive.md | 行业标杆综合文档落地 |
|
||
|
||
**交接给 AI-2**：
|
||
- 架构变更需同步至 governance/collaboration-board.md
|
||
- 前端架构变更需通知 AI-3 更新 frontend-integration/
|
||
|
||
#### 🔍 AI-2 (Internal) - 协作与分析文档
|
||
|
||
| 任务分类 | 具体文档 | 工作内容 |
|
||
|---------|---------|---------|
|
||
| **协作看板** | collaboration-board.md, console-collaboration-board.md | 更新任务状态、批次信息 |
|
||
| **任务规格** | task-specifications.md | 补充任务描述、完善验收标准 |
|
||
| **历史归档** | archive/collaboration-history-v31.md | 归档变更记录 |
|
||
| **标杆分析** | benchmarks/industry-benchmarks-comprehensive.md | 15+标杆产品综合拆解 |
|
||
|
||
**交接给 AI-1**：
|
||
- 新任务 ID 需在 task-specifications.md 定义
|
||
- 架构变更需通知 AI-1 更新 blueprints/
|
||
|
||
**交接给 AI-3**：
|
||
- 业务需求变更需通知 AI-3 更新 frontend-integration/
|
||
- 标杆功能新增需同步至前端集成方案
|
||
|
||
#### 🏢 AI-3 (Biz) - 业务与前端集成文档
|
||
|
||
| 任务分类 | 具体文档 | 工作内容 |
|
||
|---------|---------|---------|
|
||
| **前端集成** | frontend-integration/*.md (48个) | 完善 UI 描述、补充 API 映射 |
|
||
| **实施指南** | server-readme.md, toc-early-stage-spec.md, non-saas-multi-tenant-checklist.md | 更新实施步骤、补充注意事项 |
|
||
| **质量标准** | frontend-delivery-standard.md, golive-redline-checklist.md, ux-field-acceptance-checklist.md | 完善交付标准、补充验收清单 |
|
||
| **开发计划** | frontend-dev-plan.md | 更新前端路线图 |
|
||
|
||
**交接给 AI-1**：
|
||
- 前端架构变更需通知 AI-1 更新 frontend-architecture.md
|
||
|
||
---
|
||
|
||
## 3. 协作流程
|
||
|
||
### 3.1 任务分发机制
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 任务池 (Task Pool) │
|
||
│ - 文档优化需求 │
|
||
│ - 变更同步请求 │
|
||
│ - 质量审计反馈 │
|
||
└───────────────────────┬─────────────────────────────────┘
|
||
│
|
||
┌───────────────┼───────────────┐
|
||
▼ ▼ ▼
|
||
[AI-1 Kernel] [AI-2 Internal] [AI-3 Biz]
|
||
│ │ │
|
||
└───────────────┼───────────────┘
|
||
│
|
||
▼
|
||
[验收 & 归档]
|
||
```
|
||
|
||
### 3.2 跨 Agent 协作规则
|
||
|
||
| 场景 | 发起方 | 接收方 | 协作方式 |
|
||
|-----|-------|-------|---------|
|
||
| 架构变更 | AI-1 | AI-2/AI-3 | 变更通知 + 文档同步 |
|
||
| 任务新增 | AI-2 | AI-1 | 规格定义 + 架构确认 |
|
||
| 业务需求 | AI-3 | AI-2 | 需求描述 + 规格确认 |
|
||
| 依赖阻塞 | 任意 | 上游 | 阻塞上报 + 等待确认 |
|
||
|
||
### 3.3 变更同步协议
|
||
|
||
```
|
||
[变更类型] → [文档路径] → [影响范围] → [协作要求]
|
||
```
|
||
|
||
**示例**：
|
||
```
|
||
[架构变更] → [arch-overview-v30.md] → [AI-2:更新协作看板] → [24小时内同步]
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 验收标准
|
||
|
||
### 4.1 单文档验收
|
||
|
||
| 检查项 | 标准 | 权重 |
|
||
|-------|-----|-----|
|
||
| **内容准确性** | 无过时信息、与代码实现一致 | 40% |
|
||
| **格式规范性** | 符合命名规范、目录结构规范 | 20% |
|
||
| **关联完整性** | 交叉引用有效、版本同步 | 20% |
|
||
| **可读性** | 逻辑清晰、示例充足 | 20% |
|
||
|
||
### 4.2 协作验收
|
||
|
||
| 检查项 | 标准 |
|
||
|-------|-----|
|
||
| **交接完整性** | 跨 Agent 文档均已同步 |
|
||
| **状态可追溯** | 变更记录完整、可回溯 |
|
||
| **无静默失败** | 阻塞问题已上报 |
|
||
|
||
---
|
||
|
||
## 5. 执行计划
|
||
|
||
### 5.1 第一轮：基础规范（1-2 周）
|
||
|
||
| Agent | 任务 | 交付物 |
|
||
|-------|-----|-------|
|
||
| AI-1 | 统一 blueprints/ 格式规范 | 格式检查清单 |
|
||
| AI-2 | 审计 governance/ 文档完整性 | 缺失清单 |
|
||
| AI-3 | 完善 frontend-integration/ 模板 | 补充示例 |
|
||
|
||
### 5.2 第二轮：内容优化（2-3 周）
|
||
|
||
| Agent | 任务 | 交付物 |
|
||
|-------|-----|-------|
|
||
| AI-1 | 校准架构文档与技术实现一致 | 更新的架构蓝图 |
|
||
| AI-2 | 同步任务规格与看板状态 | 最新协作看板 |
|
||
| AI-3 | 补充前端集成方案的 API 映射 | 完整的前端集成文档 |
|
||
|
||
### 5.3 第三轮：质量提升（1-2 周）
|
||
|
||
| Agent | 任务 | 交付物 |
|
||
|-------|-----|-------|
|
||
| AI-1 | 补充架构决策记录 (ADR) | 决策日志 |
|
||
| AI-2 | 完善标杆分析报告 | 行业对比报告 |
|
||
| AI-3 | 补充 UX 验收标准 | 完善的质量清单 |
|
||
|
||
---
|
||
|
||
## 6. 当前任务分配
|
||
|
||
### 6.1 优先级 P0（立即执行）
|
||
|
||
| 文档 | 当前状态 | 负责 Agent | 截止时间 |
|
||
|-----|---------|------------|---------|
|
||
| industry-benchmarks-comprehensive.md | ✅ 已完成 | AI-2 | 已完成 |
|
||
| collaboration-board.md | ✅ 已同步 | AI-2 | 已完成 |
|
||
| frontend-architecture.md | ✅ 已更新 | AI-1 | 已完成 |
|
||
|
||
### 6.2 优先级 P1（本周内）
|
||
|
||
| 文档 | 当前状态 | 负责 Agent |
|
||
|-----|---------|------------|
|
||
| arch-overview-v30.md | 待校准 | AI-1 |
|
||
| task-specifications.md | 待同步 | AI-2 |
|
||
| frontend-architecture.md | 待更新 | AI-3 |
|
||
|
||
---
|
||
|
||
## 7. 沟通机制
|
||
|
||
### 7.1 例行同步
|
||
|
||
| 周期 | 内容 | 参与方 |
|
||
|-----|-----|-------|
|
||
| **每日站会** | 进度同步、阻塞上报 | 全员 |
|
||
| **周度复盘** | 质量评估、流程优化 | 全员 |
|
||
| **版本发布** | 文档版本同步 | 全员 |
|
||
|
||
### 7.2 紧急响应
|
||
|
||
- **阻塞升级**：超过 4 小时未解决的跨域问题，升级至负责人
|
||
- **变更广播**：重大变更需在 1 小时内通知所有相关方
|
||
|
||
---
|
||
|
||
## 8. 附录
|
||
|
||
### 8.1 文档命名规范
|
||
|
||
- 使用 **小写短横线** (kebab-case)
|
||
- 示例：`frontend-architecture.md`, `arch-overview-v30.md`
|
||
|
||
### 8.2 目录结构规范
|
||
|
||
```
|
||
docs/
|
||
├── benchmarks/ # 行业标杆分析
|
||
├── blueprints/ # 架构蓝图
|
||
│ └── frontend-integration/ # 前端集成方案
|
||
├── design/ # 技术设计
|
||
├── governance/ # 协作与任务
|
||
├── guides/ # 实施指南
|
||
└── quality/ # 质量标准
|
||
```
|
||
|
||
---
|
||
|
||
**维护者**：AI-1 (Kernel)
|
||
**版本**：V2.0
|
||
**状态**：已更新
|
||
**更新内容** (2026-03-15):
|
||
- benchmarks/ 目录已整合为 1 个综合文档
|
||
- frontend-integration/ 更新为 60+ 个文档
|
||
- P0 任务已完成状态同步
|