EnterpriseArchitect/specs/BIZ-12_文档存储规范_v1.0.md

多智能体文档存储、命名与索引规范 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 索引表模板

# 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：

# {目录名称}

> 最后更新：{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 引用代替填塞

反例（填塞模式）：

# TOOLS.md - 全部填入
- memory_search: 参数 query, maxResults, minScore, corpus=[memory|wiki|all|sessions]...
  （占用大量 token）

正例（引用模式）：

# 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. 检查配置文件大小是否超限

---

八、实施检查清单

• 规范文档编制（本文档）
• 各 Agent workspace 目录结构初始化
• MEMORY.md 索引表模板部署到所有 Agent
• TOOLS.md 从填塞模式迁移到索引模式（BIZ-15 跟进）
• 文档命名自动化检查脚本
• 归档目录创建及旧文档迁移

---

本规范自批准之日起生效，所有 Agent 须遵守。 审阅/修订请联系 COO（陆怀瑾）。