# 多智能体文档存储、命名与索引规范 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（陆怀瑾）。