控制面与数据面分离——Artifact Descriptor 模式

学习目标

• 理解控制面与数据面分离的设计动机
• 掌握 Artifact Descriptor 模式的结构与使用场景
• 设计自己的有界交接（Bounded Handoff）策略
• 识别描述符与实际产物不一致的陷阱

前置知识

记忆系统的短期/长期分层与抗压缩持久化已在通用知识中介绍：

• 记忆系统设计

下文假设你已理解记忆分层和 Notepad/Project Memory 的基础概念，直接聚焦 OMC 的 控制面与数据面分离设计。

项目实践

控制面 vs 数据面

OMC 将编排元数据与大持久化产物严格分离：

维度	控制面	数据面
路径	.omc/state/**	.omc/plans/、.omc/notepads/、.omc/prompts/
内容	队列状态、Worker 分配、会话状态	计划、规范、提示词、研究结果
大小	小（KB 级）	大（MB 级）
访问频率	高（频繁读写）	低（按需读取）
消费者	调度器、状态检查脚本	Agent、人类审计者

分离的动机

当编排元数据（如任务队列、Worker 状态）与大产物（如完整计划文档）混合存储时：

1. 调度器膨胀：每次读取状态都需要加载大产物
2. 状态检查变慢：omc team status 需要解析大量无关内容
3. 上下文浪费：控制面信息注入上下文窗口时携带不必要的大产物

Artifact Descriptor 模式

当控制面需要引用大产物时，OMC 使用 Descriptor 而非直接内联：

字段	类型	用途
kind	string	产物类别（plan、prompt、result、trace 等）
path	string	持久化路径
contentHash?	string	完整性校验（可选）
createdAt	timestamp	创建时间
producer	string	生产者（工具、技能、Worker）
sizeBytes?	number	负载大小（用于阈值决策）
retention	string	生命周期提示（cleanup/ownership）
expiresAt?	timestamp	过期时间（短期产物）

有界交接规则（Bounded Handoff Rule）

OMC 定义了明确的交接阈值策略：

1. 小负载内联：当调用方阈值允许时，直接传递内容
2. 大负载 Descriptor：超出阈值时，使用 Descriptor + 人类可读摘要
3. 保留清理元数据：Descriptor 包含 retention 和 ownership 信息，确保后续清理可审计

具体交接示例

共享互操作状态（interop state）：

• 任务/消息元数据内联存储在控制面
• 超大任务描述、任务结果、消息体存储在 .omc/state/interop/artifacts/**
• 控制面通过 Descriptor 引用这些大产物

提示词持久化：

• 提示词/响应文件存储在 .omc/prompts/**
• 描述符元数据与作业状态一起存储在控制面

状态集中化（可选）

默认情况下，OMC 状态存储在项目的 .omc/ 目录中，工作树删除时状态也会删除。

通过 OMC_STATE_DIR 环境变量，可以将状态集中存储：

export OMC_STATE_DIR="$HOME/.claude/omc"
# 状态存储在 ~/.claude/omc/{project-identifier}/

项目标识符是 Git remote URL 的哈希，因此同一仓库在不同工作树间共享状态。

问题与规避

问题 1：描述符与实际产物不一致

Descriptor 引用的文件可能被删除或修改，导致引用失效。

规避策略：Descriptor 包含 retention 生命周期提示。清理脚本检查引用关系——只有当没有 Descriptor 引用时，才删除产物文件。

问题 2：描述符过大失去分离意义

如果 Descriptor 本身携带大量元数据，控制面仍然膨胀。

规避策略：Descriptor 保持精简——只保留路径、哈希、时间戳和生命周期提示。详细信息存储在产物文件本身中。

问题 3：阈值决策不一致

不同模块对”大/小”的判断阈值不同，导致一些模块内联而其他模块使用 Descriptor。

规避策略：OMC 定义了统一的阈值常量，所有模块引用同一标准。

设计取舍

为什么不直接用数据库？

维度	文件系统 + Descriptor	数据库
可读性	高——人类可直接查看和编辑	低——需要工具查询
版本控制	高——Git 可追踪变更	低——数据库变更不在 Git 中
查询能力	低——需要遍历文件	高——SQL 查询
原子性	低——需要文件锁	高——事务保证

OMC 的选择：文件系统 + Descriptor——对于 Agent 编排场景，人类可审计性和 Git 版本控制比查询能力更重要。

参考来源

• OMC Architecture - State Management — 状态系统的官方文档
• OMC REFERENCE.md — 完整功能文档