diff --git a/specs/BIZ-12_文档存储规范_v1.0.md b/specs/BIZ-12_文档存储规范_v1.0.md new file mode 100644 index 0000000..6b7125b --- /dev/null +++ b/specs/BIZ-12_文档存储规范_v1.0.md @@ -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（陆怀瑾）。 \ No newline at end of file