social-app/docs/plans/2026-03-25-protocols-doc-fix.md

Protocols 文档修复计划

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 修复 protocols 文档中与后端实现不一致的错误

Architecture: 直接修改 docs/protocols/ 下的 markdown 文件，确保文档与 backend/src/models/ 中的实际模型定义保持一致

Tech Stack: Markdown 编辑

---

修复任务清单

Task 1: 修复 Memories Protocol - 移除不存在的 agent_id 字段

文件:

• 修改: docs/protocols/models/memory.md

修改内容:

• 从 "数据库存储" 章节的表格中移除 agent_id 字段
• 该字段在实现中不存在

---

Task 2: 修复 InboxMessages Protocol - 添加缺失的 group_id 字段

文件:

• 修改: docs/protocols/models/inbox-messages.md

修改内容:

• 在 InboxMessageResponse 数据结构中添加 group_id: uuid | null 字段

---

Task 3: 修复 ScheduleItems Protocol - 补充 permission 位掩码说明

文件:

• 修改: docs/protocols/calendar/schedule-items.md

修改内容:

• 在 ScheduleItemResponse 的说明中，添加 permission 字段的位掩码语义：
  • 1 = view
  • 2 = invite
  • 4 = edit
• 在 ScheduleItemShareRequest 中补充说明

---

Task 4: 修复 Friendships Protocol - 补充内部状态说明

文件:

• 修改: docs/protocols/models/friendships.md

修改内容:

• 在 FriendRequestResponse 的 status 字段说明中，添加注释：
  • blocked 和 declined 为内部实现状态
  • 对外返回时映射为 rejected
• 说明这是实现细节，客户端应处理所有枚举值

---

Task 5: 修复 Memories Protocol - 改进 source 列移除说明

文件:

• 修改: docs/protocols/models/memory.md

修改内容:

• 在 "数据库存储" 章节的表格中，明确标注 source 列已移除
• 或者在表格下方添加更醒目的 "已移除字段" 说明

---

Task 6: 修复 Automation Jobs Protocol - 添加 bootstrap_key 字段

文件:

• 修改: docs/protocols/models/automation-jobs.md

修改内容:

• 在 "Canonical Fields" 表格中添加 bootstrap_key: string | null 字段说明
• 简短说明其用途（引导配置键）

---

执行顺序

1. Task 1 - Memories: 移除 agent_id
2. Task 2 - InboxMessages: 添加 group_id
3. Task 3 - ScheduleItems: 补充 permission 说明
4. Task 4 - Friendships: 补充状态说明
5. Task 5 - Memories: 改进 source 说明
6. Task 6 - AutomationJobs: 添加 bootstrap_key

---

验证方式

• 人工检查：对比修改后的文档与 backend/src/models/ 中的实际模型定义
• 确保文档中描述的每个字段都能在对应 model 文件中找到