陆怀瑾 (COO)
38b21d7adb
- BIZ-11: 组织架构与岗位职责体系建设方案 - BIZ-12: 文档存储、命名与索引规范方案 - BIZ-13: 运行稳定性保障方案（任务停滞与429速率限制） - BIZ-14: 知识库体系建设方案 - BIZ-15: 配置文件持续优化机制方案 所有方案均为初稿，待刘总审阅。
270 lines
6.7 KiB
Markdown
270 lines
6.7 KiB
Markdown
# 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 配置文件。 |