# PRD: OPC 跨 Agent 记忆共享系统（SharedContext）

> Version: 1.0  
> Date: 2026-04-24  
> Author: 小研（xiaoyan）  
> Status: READY FOR BUILD

---

## 1. Problem & User

**用户：** OPC 团队（Bo Huang + 8个专职 AI Agent）

**核心问题：** 8 个 Agent 各自孤立运行，无共享记忆机制。每次跨 Agent 协作，必须人工在 `sessions_send` 消息里重复传递项目背景、PRD路径、技术决策。小策→小码→小质→小维的完整交付链中，每个交接点都会丢失上下文，产生重复沟通成本。

**量化影响：**
- 每次跨 Agent 任务交接：额外 2-5 分钟背景传递
- Agent 重启后失忆：每次都需要人工重新 brief
- 同一技术问题被多 Agent 重复调研：浪费 $5-20 LLM 成本/次

**根本原因：** OpenClaw 的 `memory_get`/`memory_search` 是 per-Agent 的 SQLite，不跨 Agent 共享；`sessions_send` 是消息通道，不是知识存储。但所有 Agent 运行在同一服务器，`/home/ubuntu/OPC/` 是天然共享文件系统，目前未被利用。

---

## 2. Target Outcome & KPIs

**目标：** 建立一套零依赖的跨 Agent 共享记忆协议，基于现有共享文件系统。

**KPIs（6周后验收）：**
- ✅ 任意 Agent 可在 30 秒内找到另一 Agent 最近完成的项目上下文
- ✅ 项目交接消息长度减少 70%（不需要在消息里粘贴完整背景）
- ✅ 跨 Agent 决策记录覆盖率 ≥ 80%（每个 BUILD 决策有记录）
- ✅ 零额外成本（无需部署新服务、无 API 费用）

---

## 3. MVP Scope（In）

1. **SharedContext 目录结构** — `/home/ubuntu/OPC/context/` 标准化组织
2. **项目上下文文件格式** — `{slug}__context.md` 标准模板（关键路径 + 决策 + 状态）
3. **各 Agent SOUL.md/TOOLS.md 写入协议** — 规定"完成任务后必须写 context 文件"
4. **全局索引文件** — `/home/ubuntu/OPC/context/INDEX.md` 自动维护的项目列表
5. **Agent 读取约定** — 接收任务时先 `cat /home/ubuntu/OPC/context/{slug}__context.md`

---

## 4. Out of Scope

- 向量数据库 / 语义检索（当前项目数量 <20，关键词检索足够）
- mem0 / Letta / ChromaDB 等第三方记忆服务
- 自动记忆提取（LLM 自主决定存什么）
- Agent 间实时同步通知（仍用 sessions_send 通知，context 文件是持久化层）
- MEMORY.md 的跨 Agent 访问（私有信息，不开放）

---

## 5. User Flow（Happy Path）

```
小策 收到新任务（如：legalflow-v2 部署）
  └→ 读取 /home/ubuntu/OPC/context/legalflow-v2__context.md
  └→ 获得：PRD路径、技术栈、部署端口、上次决策
  └→ sessions_send("xiaowei", "请部署 legalflow-v2，上下文见 context 文件")
  
小维 收到任务
  └→ 读取 legalflow-v2__context.md（PRD路径/端口/nginx配置/注意事项 全在）
  └→ 完成部署后，更新 context 文件（状态: deployed, url: xxx）
  └→ sessions_send("xiaoce", "部署完成，context 已更新")

下次任意 Agent 接手 legalflow 相关任务
  └→ cat context/legalflow-v2__context.md → 立即获得完整项目状态
```

---

## 6. Functional Requirements（P0）

### F1 — Context 目录结构

```
/home/ubuntu/OPC/context/
├── INDEX.md                          ← 全局项目索引（自动维护）
├── legalflow-v2__context.md          ← 项目上下文（按 slug 命名）
├── restaurant-food-safety__context.md
└── ...
```

### F2 — Context 文件标准模板

每个 `{slug}__context.md` 必须包含以下字段：

```markdown
# Context: {项目名称}

> 最后更新：YYYY-MM-DD HH:MM | 更新者：{Agent}

## 关键路径
- PRD: /home/ubuntu/OPC/PRD/{slug}__prd__{ts}.md
- 代码: /home/ubuntu/OPC/src/{project}/
- 部署: {port} / {url}

## 技术决策
- 框架: {stack}（原因: {why}）
- 数据库: {db}（原因: {why}）
- 认证: {auth}

## 当前状态
- 阶段: [PRD完成 | 开发中 | 测试中 | 已部署]
- 最近完成: {描述}
- 待处理: {描述}
- 已知问题: {描述}

## Agent 职责记录
- 小研: PRD 完成于 {date}
- 小码: M1/M2/M3 完成于 {date}
- 小维: 部署于 {date}，端口 {port}
```

### F3 — 写入协议（各 Agent 必须遵守）

触发写入的时机：
- 小研：每次 PRD 生成后 → 创建/更新 context 文件
- 小码：每个 Milestone 完成后 → 更新状态
- 小质：测试完成后 → 更新已知问题
- 小维：部署完成后 → 更新部署信息
- 小策：任务分配前 → 读取 context；任务完成后 → 更新状态

### F4 — 全局索引维护

`INDEX.md` 格式：

```markdown
# OPC 项目上下文索引

| 项目 | Slug | 阶段 | 最后更新 | 负责 Agent |
|------|------|------|---------|-----------|
| LegalFlow V2 | legalflow-v2 | 已部署 | 2026-04-24 | 小维 |
| 餐饮食安 SafeChain | restaurant-food-safety-compliance | PRD完成 | 2026-04-22 | 小研 |
```

### F5 — 读取约定

Agent 接收任务时，SOUL.md 中应包含：

```
接收跨 Agent 任务时，先执行：
cat /home/ubuntu/OPC/context/{slug}__context.md 2>/dev/null || echo "无上下文，请从 PRD 目录查找"
```

---

## 7. Minimal Data Model

```
/home/ubuntu/OPC/context/
├── INDEX.md              (纯文本，手动/自动维护)
└── {slug}__context.md    (结构化 Markdown，每项目一文件)
```

**无数据库需赖。** 文件即数据，版本控制通过 git 或时间戳备份。

可选：
```bash
# 备份机制（小策在每天凌晨通过 cron 触发）
cp -r /home/ubuntu/OPC/context/ /home/ubuntu/OPC/context-backup-$(date +%Y%m%d)/
```

---

## 8. API / Integration Notes

### 8.1 现有 OpenClaw 工具整合

| 场景 | 使用工具 | 说明 |
|------|---------|------|
| 检查项目上下文是否存在 | `exec: ls /home/ubuntu/OPC/context/` | 直接文件操作 |
| 读取上下文 | `exec: cat context/{slug}__context.md` | 无需新工具 |
| 写入/更新上下文 | `exec: cat > context/{slug}__context.md` | 标准 bash |
| 通知上下文已更新 | `sessions_send(agentId, "context 已更新")` | 现有工具 |
| 快速搜索跨项目 | `exec: grep -r "keyword" /home/ubuntu/OPC/context/` | 关键词检索 |

### 8.2 与 sessions_history 配合

对于需要查阅"Agent 最近做了什么"的场景：

```python
# 当 context 文件不存在时的 fallback
sessions_history("xiaoma", limit=20)  # 读小码最近20条记录找线索
```

### 8.3 SOUL.md 集成（各 Agent 需添加）

在各 Agent SOUL.md 的"协作规则"章节添加：

```markdown
## 共享记忆协议
- 完成每个重要任务后，写入/更新 /home/ubuntu/OPC/context/{slug}__context.md
- 接收跨 Agent 任务时，先读取对应的 context 文件
- 若 context 不存在，先查 /home/ubuntu/OPC/context/INDEX.md 定位
```

---

## 9. Acceptance Criteria

- [ ] `/home/ubuntu/OPC/context/` 目录存在
- [ ] `INDEX.md` 包含所有现有项目（≥5个）的索引条目
- [ ] `legalflow-v2__context.md` 包含：PRD路径、代码路径、部署端口、技术栈选型原因
- [ ] 任意 Agent 执行 `cat /home/ubuntu/OPC/context/legalflow-v2__context.md` 可在 2 秒内获取完整上下文
- [ ] 小研的 SOUL.md 包含"完成 PRD 后写入 context"的协议
- [ ] 小码的 SOUL.md 包含"Milestone 完成后更新 context"的协议
- [ ] 小维的 SOUL.md 包含"部署完成后更新 context"的协议
- [ ] `grep` 可检索关键词（如"Next.js"）并找到相关项目上下文

---

## 10. Delivery Plan

### Milestone 1 — 基础设施建立（预估 1 小时，执行者：小策）

**目标：** 创建目录、迁移现有项目上下文

```
创建文件：
  /home/ubuntu/OPC/context/INDEX.md
  /home/ubuntu/OPC/context/legalflow-v2__context.md
  /home/ubuntu/OPC/context/restaurant-food-safety-compliance__context.md
  /home/ubuntu/OPC/context/medical-device-distributor__context.md
  /home/ubuntu/OPC/context/staffing-contract-expiry__context.md
  /home/ubuntu/OPC/context/law-firm-evidence-deadline__context.md
```

**实施顺序：**
1. `mkdir -p /home/ubuntu/OPC/context/`
2. 读取各项目 PRD，提取关键信息，写入 context 文件
3. 写入 INDEX.md 汇总表

**Exit Criteria：**
- `ls /home/ubuntu/OPC/context/*.md | wc -l` ≥ 6
- `cat /home/ubuntu/OPC/context/legalflow-v2__context.md` 包含完整的12个必要字段
- INDEX.md 列出所有项目

---

### Milestone 2 — Agent 协议更新（预估 2 小时，执行者：小策协调各 Agent）

**目标：** 更新各 Agent 的 SOUL.md，写入共享记忆协议

```
修改文件：
  /root/.openclaw/workspace-xiaoyan/SOUL.md  ← 小研：PRD完成后写context
  /root/.openclaw/workspace-xiaoma/SOUL.md   ← 小码：Milestone完成后更新context
  /root/.openclaw/workspace-xiaozhi/SOUL.md  ← 小质：测试后更新known issues
  /root/.openclaw/workspace-xiaowei/SOUL.md  ← 小维：部署后更新部署信息
  /root/.openclaw/workspace-xiaoce/SOUL.md   ← 小策：任务分配前读context
```

**Exit Criteria：**
- 各 SOUL.md 包含"共享记忆协议"章节
- 小研完成下一个 PRD 任务后，自动生成对应的 context 文件（验收测试）

---

### Milestone 3 — 运营验证（预估 1 周观察，执行者：Bo 观察）

**目标：** 验证协议在真实任务中被执行

```
监控文件：
  /home/ubuntu/OPC/context/INDEX.md    ← 新项目是否被自动添加
  /home/ubuntu/OPC/context/*.md       ← 文件是否被更新
```

**观察指标：**
- 下一个跨 Agent 任务（小策→小码）：context 文件是否被使用
- 小策发给小码的任务消息：是否不再包含大段背景复述
- 2 周内 context 目录下是否自然增长到 ≥ 8 个项目

**Exit Criteria：**
- 2 周内，context 目录有 ≥ 3 次新增或更新
- Bo 主观感受：跨 Agent 任务交接时，消息明显更简短

---

## 11. Risks & Mitigations

| 风险 | 概率 | 影响 | 缓解策略 |
|------|------|------|---------|
| Agent 忘记写 context（习惯未建立） | 高 | 中 | 小策在任务完成确认时，主动检查 context 是否更新 |
| context 文件冲突（同时写入） | 低 | 低 | 最后写入者覆盖，加时间戳；文件级别无锁竞争风险 |
| 文件格式不统一 | 中 | 低 | SOUL.md 中提供标准模板，context 写法高度一致 |
| 历史项目 context 信息不完整 | 中 | 低 | M1 手动补充现有项目；未来项目从 PRD 阶段起就建立 |
| Agent 读到过期 context | 低 | 低 | context 文件头部有"最后更新"时间戳，Agent 可判断时效 |

---

## 12. Chargeability Rationale

本系统直接降低 OPC 8 个 Agent 跨 Agent 协作的信息传递摩擦，每个项目交付周期预计节省 30-60 分钟的重复 brief 时间，同时消除 Agent 重复调研导致的 LLM API 浪费（每月可节省 $20-100）——以零成本实现，ROI 极高。

---

## 附录：立即可执行的第一步

```bash
# 小策可以在接收此 PRD 后立即执行 M1：
mkdir -p /home/ubuntu/OPC/context/

cat > /home/ubuntu/OPC/context/INDEX.md << 'EOF'
# OPC 项目上下文索引

> 最后更新：2026-04-24

| 项目 | Slug | 阶段 | 最后更新 | 主要文件 |
|------|------|------|---------|---------|
| LegalFlow V2 | legalflow-v2 | 已部署 | 2026-04-24 | PRD/legalflow-v2__prd__*.md |
| 餐饮食安 SafeChain | restaurant-food-safety-compliance | PRD完成 | 2026-04-22 | PRD/restaurant-food-safety-compliance__prd__*.md |
| 医疗器械许可证追踪 | medical-device-distributor | PRD完成 | 2026-04-21 | PRD/medical-device-distributor*.md |
| 用工合同到期管理 | staffing-contract-expiry | PRD完成 | 2026-04-22 | PRD/staffing-contract-expiry*.md |
| 律所证据截止管理 | law-firm-evidence-deadline | PRD完成 | 2026-04-22 | PRD/law-firm-evidence-deadline*.md |
EOF

echo "✅ INDEX.md 已创建"
```