# BIZ-12 文档存储、命名与索引规范方案

> 版本：v1.0  
> 编制：陆怀瑾（COO）  
> 日期：2026-06-22  
> 状态：待审阅

---

## 一、目标

建立统一的文档存储规范，确保所有智能体能够规范地存储、命名、检索文档，避免信息孤岛和文档混乱。

---

## 二、核心原则

1. **分层存储**：按文档类型和用途分层存放
2. **统一命名**：所有文档遵循一致的命名规则
3. **索引可查**：建立文档索引，支持快速检索
4. **版本可控**：重要文档保留版本历史

---

## 三、目录结构设计

### 3.1 根目录结构

```
workspace/
├── AGENTS.md              # Agent 协作协议（核心配置）
├── MEMORY.md              # 长期记忆（核心配置）
├── SOUL.md                # 角色定义（核心配置）
├── IDENTITY.md            # 身份信息（核心配置）
├── USER.md                # 用户画像（核心配置）
├── TOOLS.md               # 工具清单（核心配置）
├── HEARTBEAT.md           # 心跳配置（核心配置）
│
├── memory/                # 记忆归档目录
│   └── YYYY-MM-DD.md      # 按日期归档的记忆文件
│
├── docs/                  # 项目文档目录
│   └── {project-name}/    # 按项目分目录
│       ├── README.md
│       ├── requirements.md
│       └── design.md
│
├── plans/                 # 方案文档目录
│   └── YYYY-MM-DD_{topic}.md
│
├── reports/               # 运营报告目录
│   └── YYYY-QN_{type}.md  # 按季度/类型归档
│
├── knowledge/             # 知识库目录
│   └── {domain}/          # 按领域分目录
│       └── {topic}.md
│
└── assets/                # 资源文件目录
    ├── images/
    ├── attachments/
    └── templates/
```

### 3.2 各目录用途说明

| 目录 | 用途 | 维护者 | 更新频率 |
|------|------|--------|----------|
| 根目录配置文件 | Agent 核心配置 | 各 Agent | 按需 |
| memory/ | 短期记忆归档 | 各 Agent | 每日 |
| docs/ | 项目文档 | projectmanager | 按项目 |
| plans/ | 方案文档 | COO | 按需 |
| reports/ | 运营报告 | COO | 每周/每月 |
| knowledge/ | 知识库 | 各 Agent | 持续 |
| assets/ | 资源文件 | 各 Agent | 按需 |

---

## 四、命名规则

### 4.1 通用命名格式

```
{日期}_{主题}_{版本}.{扩展名}
```

### 4.2 日期格式

- 统一使用 `YYYY-MM-DD` 格式
- 示例：`2026-06-22`

### 4.3 主题命名

- 使用下划线分隔中文主题
- 避免特殊字符（`/ \ : * ? " < > |`）
- 示例：`多智能体协作体系`

### 4.4 版本标识

- 初稿：`v1.0`
- 修订：`v1.1`, `v1.2`
- 重大变更：`v2.0`

### 4.5 命名示例

| 类型 | 示例 |
|------|------|
| 记忆归档 | `memory/2026-06-22.md` |
| 方案文档 | `plans/2026-06-22_多智能体协作体系总方案_v1.0.md` |
| 运营报告 | `reports/2026-Q2_运营效率报告_v1.0.md` |
| 知识库 | `knowledge/电商/淘宝运营 SOP_v1.0.md` |
| 项目文档 | `docs/自动化运营系统/requirements_v1.0.md` |

---

## 五、索引机制

### 5.1 索引层级

```
Level 1: MEMORY.md（总索引）
         ↓
Level 2: 各目录 README.md（分类索引）
         ↓
Level 3: 具体文档（内容）
```

### 5.2 MEMORY.md 索引表格式

```markdown
## 文档索引

### 方案文档
| 日期 | 主题 | 路径 | 状态 |
|------|------|------|------|
| 2026-06-22 | 多智能体协作体系 | plans/2026-06-22_多智能体协作体系总方案.md | 待审阅 |

### 运营报告
| 周期 | 类型 | 路径 | 状态 |
|------|------|------|------|
| 2026-Q2 | 效率报告 | reports/2026-Q2_运营效率报告.md | 已完成 |

### 知识库
| 领域 | 主题 | 路径 | 更新时间 |
|------|------|------|----------|
| 电商 | 淘宝 SOP | knowledge/电商/淘宝运营 SOP.md | 2026-06-22 |
```

### 5.3 检索工具

- **memory_search**: 跨文档语义检索
- **wiki_search**: 知识库检索
- **memory_get**: 精确读取特定文档
- **web_fetch**: 外部文档获取

---

## 六、Agent 文档操作规范

### 6.1 写入规范

```python
# 伪代码示例
def write_document(path, content, agent_id):
    # 1. 检查文件是否存在
    if exists(path):
        # 2. 如存在，增加版本号
        version = get_next_version(path)
        path = add_version(path, version)
    
    # 3. 写入文件
    write(path, content)
    
    # 4. 更新索引
    update_index(path, agent_id, timestamp())
```

### 6.2 读取规范

```python
# 伪代码示例
def read_document(query, agent_id):
    # 1. 先查索引
    results = search_index(query)
    
    # 2. 如未找到，用语义检索
    if not results:
        results = memory_search(query)
    
    # 3. 记录读取日志
    log_access(query, agent_id, timestamp())
    
    return results
```

### 6.3 更新规范

- 小改动：直接覆盖原文件
- 大改动：创建新版本，保留旧版本
- 删除：移动到 `archive/` 目录，不直接删除

---

## 七、版本管理策略

### 7.1 版本类型

| 类型 | 标识 | 说明 |
|------|------|------|
| 初稿 | v1.0 | 首次创建 |
| 小修订 | v1.1, v1.2 | 内容微调，不改变结构 |
| 大修订 | v2.0, v3.0 | 结构性变更 |
| 归档 | archive/v1.0 | 已废弃的旧版本 |

### 7.2 版本保留策略

- 当前版本：始终保留
- 上一版本：保留最近 1 个
- 历史版本：归档到 `archive/` 子目录

### 7.3 版本命名示例

```
plans/
├── 2026-06-22_多智能体协作体系总方案.md       # 当前版本
├── archive/
│   └── 2026-06-22_多智能体协作体系总方案_v1.0.md  # 历史版本
```

---

## 八、实施步骤

### 阶段 1：规范化（本周）
- [ ] 制定完整的命名规则文档
- [ ] 创建各目录 README.md
- [ ] 更新 MEMORY.md 索引表

### 阶段 2：迁移（下周）
- [ ] 整理现有文档，按新规范重命名
- [ ] 移动到正确目录
- [ ] 建立归档目录

### 阶段 3：工具化（持续）
- [ ] 开发文档索引自动更新脚本
- [ ] 建立文档健康检查机制
- [ ] 定期清理过期文档

---

## 九、风险与对策

| 风险 | 影响 | 对策 |
|------|------|------|
| Agent 不按规范命名 | 文档混乱 | 增加命名检查工具 |
| 索引更新不及时 | 检索失败 | 自动更新索引 |
| 版本过多占用空间 | 存储压力 | 定期清理归档 |

---

## 十、交付物清单

- [ ] 文档存储规范文档（本文档）
- [ ] 各目录 README.md 模板
- [ ] MEMORY.md 索引表模板
- [ ] 文档命名检查工具
- [ ] 文档迁移脚本

---

> ⚠️ 本方案需 Vincent 审阅后方可实施。审阅前不修改任何 Agent 配置文件。