BIZ-12: 文档存储、命名与索引规范 v1.0（实施版）

关键变更： - 纳入刘总反馈：索引分离原则 - 纳入 QMD 作为知识库检索补充路径 - 新增 Token 预算控制章节 - 新增检索体系分层路径 - 新增文档生命周期管理流程 - 产出 specs/BIZ-12_文档存储规范_v1.0.md
2026-06-22 21:44:18 +08:00
parent dc00661a34
commit 74cfb3e0f6
1 changed files with 279 additions and 0 deletions
@@ -0,0 +1,279 @@
+# 多智能体文档存储、命名与索引规范 v1.0
+
+> 版本：v1.0（实施版）
+> 编制：陆怀瑾（COO）
+> 日期：2026-06-22
+> 状态：已批准，执行中
+> 适用范围：所有 Agent 的 workspace 目录
+
+---
+
+## 一、统一目录结构
+
+每个 Agent 的 workspace 必须采用以下标准目录结构：
+
+```
+workspace/
+├── AGENTS.md              # Agent 协作协议
+├── MEMORY.md              # 长期记忆 → 含文档索引表（核心）
+├── SOUL.md                # 角色定义 → 引用外部内容，不填塞
+├── IDENTITY.md            # 身份信息
+├── USER.md                # 用户画像
+├── TOOLS.md               # 工具清单 → 仅保留索引，详情外挂
+├── HEARTBEAT.md           # 心跳配置
+│
+├── memory/                # 记忆归档目录（按日期）
+│   └── YYYY-MM-DD.md
+│
+├── docs/                  # 项目文档目录（按项目分）
+│   └── {project}/
+│       ├── README.md
+│       └── ...
+│
+├── plans/                 # 方案文档目录
+│   └── YYYY-MM-DD_{topic}.md
+│
+├── specs/                 # 规范/标准文档目录
+│   └── BIZ-XX_{name}_v{M}.{N}.md
+│
+├── reports/               # 运营报告目录
+│   └── YYYY-Q{N}_{type}_v{M}.{N}.md
+│
+├── knowledge/             # 知识库目录（按领域分）
+│   └── {domain}/
+│       └── {topic}.md
+│
+├── tasks/                 # 任务文件目录（可选）
+│   └── ...
+│
+└── assets/                # 资源文件目录
+    ├── images/
+    ├── files/
+    └── templates/
+```
+
+### 目录用途速查
+
+| 目录 | 用途 | Token 影响 |
+|------|------|-----------|
+| 根目录 .md | Agent 核心配置 | **直接影响 Token**，必须精简 |
+| memory/ | 按日归档记忆 | 通过 memory_search 检索，不占用上下文 |
+| docs/ | 项目文档 | 按需加载 |
+| plans/ | 方案文档 | 仅 COO 维护 |
+| specs/ | 规范标准 | 按需加载 |
+| reports/ | 运营报告 | 仅 COO 维护 |
+| knowledge/ | 知识库 | 知识库检索，不占用上下文 |
+| assets/ | 二进制资源 | 不占用上下文 |
+
+---
+
+## 二、文件命名规则
+
+### 2.1 强制命名格式
+
+```
+{日期/编号}_{中文主题}_{版本}.md
+```
+
+### 2.2 各目录命名约定
+
+| 目录 | 命名模式 | 示例 |
+|------|----------|------|
+| memory/ | `YYYY-MM-DD.md` | `2026-06-22.md` |
+| plans/ | `YYYY-MM-DD_{主题}.md` | `2026-06-22_多智能体协作体系总体方案.md` |
+| specs/ | `BIZ-{编号}_{主题}_v{M}.{N}.md` | `BIZ-12_文档存储规范_v1.0.md` |
+| reports/ | `YYYY-Q{N}_{类型}_v{M}.{N}.md` | `2026-Q2_运营效率报告_v1.0.md` |
+| knowledge/ | `{主题}_v{M}.{N}.md` | `淘宝运营_SOP_v1.0.md` |
+| docs/{project}/ | `{功能}_{版本}.md` | `requirements_v1.0.md` |
+| memory/ day file | `YYYY-MM-DD.md` | `2026-06-22.md` |
+
+### 2.3 禁止事项
+
+- ❌ 使用特殊字符：`/ \ : * ? " < > |` 空格
+- ❌ 超过 80 字符的文件名
+- ❌ 不含日期/编号的裸文件名
+- ❌ 中文和英文混排无分隔符
+- ✅ 统一使用下划线 `_` 作为分隔符
+
+---
+
+## 三、索引机制（核心）
+
+### 3.1 索引分离原则（刘总反馈已纳入）
+
+> **配置文件只保留索引指针，详细内容外挂存储。**
+
+此原则适用场景：
+- **TOOLS.md**：只列工具名称 + 引用路径，不列完整参数
+- **待办列表**：只记录 ID + 主题 + 状态，详情在独立文件中
+- **Agent 协作表**：只列 Agent 名 + 职能 + Session Key，详情在各自文件
+- **知识索引**：MEMORY.md 只保留索引表，知识条目在 knowledge/ 中
+
+### 3.2 MEMORY.md 索引表模板
+
+```markdown
+# MEMORY.md - {Agent Name} 长期记忆
+
+## 📑 文档索引
+
+### 方案文档
+| 日期 | 主题 | 路径 | 状态 |
+|------|------|------|------|
+| 2026-06-22 | 多智能体协作体系 | plans/2026-06-22_多智能体协作体系总体方案.md | 已批准 |
+
+### 规范标准
+| 编号 | 主题 | 路径 | 版本 |
+|------|------|------|------|
+| BIZ-12 | 文档存储规范 | specs/BIZ-12_文档存储规范_v1.0.md | v1.0 |
+
+### 项目文档
+| 项目 | 文档 | 路径 | 状态 |
+|------|------|------|------|
+
+### 运营报告
+| 周期 | 类型 | 路径 | 状态 |
+|------|------|------|------|
+
+### 知识库条目
+| 领域 | 主题 | 路径 | 更新时间 |
+|------|------|------|----------|
+
+---
+（以下是实际记忆内容...）
+```
+
+### 3.3 各目录 README.md 模板
+
+每个目录应有一个 `README.md`：
+
+```markdown
+# {目录名称}
+
+> 最后更新：{YYYY-MM-DD}
+> 维护者：{Agent Name}
+
+## 目录说明
+{简短描述本目录的用途和使用规范}
+
+## 文件列表
+| 文件名 | 描述 | 最后更新 |
+|--------|------|----------|
+| ... | ... | ... |
+```
+
+---
+
+## 四、检索体系
+
+### 4.1 分层检索路径
+
+```
+第一层：memory_search（语义检索，跨 memory/*.md + MEMORY.md）
+    ↓ 未命中
+第二层：wiki_search / wiki_get（编译型知识库检索）
+    ↓ 未命中  
+第三层：qmd（QMD 全文检索，已安装 —— 刘总反馈已纳入）
+    ↓ 未命中
+第四层：web_fetch / web_search（外部知识）
+```
+
+### 4.2 检索优先级
+
+1. **memory_search**（corpus=all）：首选，零 token 消耗
+2. **qmd**：本地全文检索，补充 memory_search 未覆盖的长文档
+3. **wiki_search/wiki_get**：编译型结构化知识库
+4. **web_search/web_fetch**：外部补充，仅在以上均未命中时使用
+
+---
+
+## 五、Token 预算控制
+
+### 5.1 配置文件大小限制
+
+| 文件 | 最大行数 | 说明 |
+|------|----------|------|
+| AGENTS.md | 200 行 | Agent 协议 + 协作表（精简） |
+| MEMORY.md | 150 行 | 长期记忆 + 索引表 |
+| SOUL.md | 80 行 | 角色定义 |
+| IDENTITY.md | 30 行 | 身份信息 |
+| USER.md | 30 行 | 用户画像 |
+| TOOLS.md | 100 行 | 工具索引（不填塞完整参数） |
+| HEARTBEAT.md | 60 行 | 心跳配置 |
+
+### 5.2 引用代替填塞
+
+**反例（填塞模式）**：
+```markdown
+# TOOLS.md - 全部填入
+- memory_search: 参数 query, maxResults, minScore, corpus=[memory|wiki|all|sessions]...
+  （占用大量 token）
+```
+
+**正例（引用模式）**：
+```markdown
+# TOOLS.md - 索引模式
+## 已安装 Skills
+- plantuml-skill → 详见 skills/plantuml-skill/SKILL.md
+- qmd → 详见 skills/qmd/SKILL.md
+- ...
+## 核心工具（已内置于运行时，无需列出参数）
+- memory_search / wiki_search / web_fetch
+```
+
+---
+
+## 六、文档生命周期管理
+
+### 6.1 状态流转
+
+```
+创建 → 草稿(draft) → 审阅中(in_review) → 已批准(approved) → 归档(archived)
+                                           ↓
+                                        废弃(deprecated)
+```
+
+### 6.2 操作规范
+
+| 操作 | 规则 |
+|------|------|
+| 创建 | 在正确目录，按命名规则创建 |
+| 更新 | 小改动直接覆盖；大改动新建版本 |
+| 审阅 | 状态标记 `in_review`，通知审阅人 |
+| 归档 | 移动到 `archive/` 子目录 |
+| 删除 | 不直接删除，先归档 30 天后清理 |
+
+### 6.3 版本标记
+
+- v1.0：首版
+- v1.1-v1.9：小修
+- v2.0+：大修 / 重构
+
+---
+
+## 七、Agent 端执行规范
+
+### 7.1 每次任务后
+1. 更新 `memory/YYYY-MM-DD.md`（日记）
+2. 如产出文档，更新 MEMORY.md 索引表
+3. 检查文件名是否符合规范
+
+### 7.2 每周
+1. 检查并清理过期文档（移动到 archive/）
+2. 验证索引表与实际文件一致性
+3. 检查配置文件大小是否超限
+
+---
+
+## 八、实施检查清单
+
+- [x] 规范文档编制（本文档）
+- [ ] 各 Agent workspace 目录结构初始化
+- [ ] MEMORY.md 索引表模板部署到所有 Agent
+- [ ] TOOLS.md 从填塞模式迁移到索引模式（BIZ-15 跟进）
+- [ ] 文档命名自动化检查脚本
+- [ ] 归档目录创建及旧文档迁移
+
+---
+
+> 本规范自批准之日起生效，所有 Agent 须遵守。
+> 审阅/修订请联系 COO（陆怀瑾）。