[Feature] 双向关系自动同步 - 当 A 添加 B 到关系列表时自动在 B 的列表中添加 A

[Clawiee]

🎯 需求背景

当前 Clawith 的关系系统是单向配置的：

• 当用户 A 把数字员工 B 加入关系列表时，只在 B 的 relationships.md 中记录 A
• A 的关系列表不会自动包含 B
• 用户需要在两边都手动配置才能建立双向关系

这导致：

1. 配置繁琐：每次建立关系都需要操作两次
2. 容易遗漏：忘记配置反向关系导致协作不畅
3. 体验不一致：与社交网络中"好友关系"的直觉不符

✨ 功能建议

增加双向关系自动同步功能：

方案 A：完全双向同步（推荐）

当 A 把 B 加入关系列表时：

1. 自动在 B 的关系列表中也加入 A
2. 关系类型可以相同或可配置
3. 删除时同样同步删除反向关系

优点：

• 用户体验最佳，一次操作完成双向配置
• 符合"关系是双向的"直觉认知
• 减少配置错误和遗漏

实现要点：

# 伪代码示例
async def save_relationships(agent_id, data, current_user, db):
    for r in data.relationships:
        # 创建正向关系 A → B
        db.add(AgentRelationship(agent_id=agent_id, member_id=r.member_id, ...))
        
        # 自动创建反向关系 B → A
        reverse_rel = AgentRelationship(
            agent_id=r.member_id,  # B 的 agent_id
            member_id=agent_id,     # A 的 member_id
            relation=r.relation,    # 相同或映射的关系类型
            description=r.description,
            created_by_user_id=current_user.id,
            updated_by_user_id=current_user.id,
        )
        db.add(reverse_rel)

方案 B：可选双向同步

在 UI 上增加"同步建立反向关系"复选框：

• 默认勾选
• 用户可取消以保留单向关系

方案 C：关系类型映射

支持关系类型的智能映射：

• A 设置 B 为"下属" → B 自动设置 A 为"上级"
• A 设置 B 为"协作伙伴" → B 自动设置 A 为"协作伙伴"（对称）

📋 技术实现建议

1. 数据库层面

• 保持现有表结构不变（AgentRelationship, AgentAgentRelationship）
• 在保存/删除时增加反向关系的自动处理逻辑

2. API 层面

在 backend/app/api/relationships.py 的 save_relationships 和 save_agent_relationships 端点中：

• 创建正向关系后，检查反向关系是否存在
• 不存在则自动创建
• 存在则更新（如果关系类型变化）

3. 删除同步

在 delete_relationship 和 delete_agent_relationship 端点中：

• 删除时同时查找并删除反向关系

4. 权限控制

• 确保当前用户对两个 agent 都有管理权限
• 如果用户只能管理 A 不能管理 B，则只创建单向关系并给出提示

5. 循环关系防护

• 检测并防止 A→B→A 的循环配置
• 或者允许循环但需要特殊处理

🎨 UI/UX 建议

关系配置页面

┌─────────────────────────────────────┐
│ 添加关系：姚劲                       │
│ 关系类型：[协作伙伴 ▼]               │
│ □ 同步建立反向关系（推荐）           │
│   （在姚劲的关系列表中也添加此数字员工）│
│                                     │
│ 描述：[________________]            │
│                                     │
│          [取消]  [保存]             │
└─────────────────────────────────────┘

关系列表展示

在关系列表中增加标识：

姚劲 - 协作伙伴  ↺ 双向
湛雨桐 - 协作伙伴  → 单向

⚠️ 注意事项

1. 向后兼容：

   • 已有单向关系保持不变
   • 新增关系默认启用双向同步

2. 权限边界：

   • 如果用户只能管理 agent A，不能管理 agent B
   • 则只能创建 A→B 的单向关系
   • UI 上显示提示"需要 B 的管理员配置反向关系"

3. 批量操作：

   • 批量保存/删除时同样需要处理反向关系
   • 注意事务一致性

4. 通知机制：

   • 当自动创建反向关系时，可选通知对方管理员
   • "您的数字员工 X 已被添加到 Y 的关系网络中"

📊 优先级评估

维度	评分	说明
用户价值	⭐⭐⭐⭐⭐	显著降低配置成本
实现难度	⭐⭐⭐	中等，需要处理边界情况
影响范围	⭐⭐⭐	影响关系管理核心流程
紧急程度	⭐⭐⭐	非紧急但重要

综合建议：纳入下个 Sprint 的产品优化项

🙋 相关方

• @姚劲 (后端开发)
• @湛雨桐 (产品负责人)
• @覃睿 (Clawith 负责人)

---

提交者：Clawiee（代 xiaoan 提交）
提交时间：2026-05-14