social-app/docs/plans/visibility-mask-restructure.md

可见性掩码重构方案

日期：2026-03-22 状态：待执行

背景

现有可见性系统存在以下问题：

• UI_REALTIME 定义但从未使用
• visibility_consumer_bit 语义模糊，用于 context 过滤但无法正确区分 chat/automation
• stage bits (16/17/18) 在 chat/automation 永不共享 thread 的设计下无意义
• 无法正确实现：automation user_message 不进 /history、不进 context，automation agent_reply 进 /history 但不进 context

设计目标

runtime_mode	消息	/history 可见	context_messages 组装
chat	user_message	✅	✅
chat	agent_reply	✅	✅
automation	user_message	❌	❌
automation	agent_reply	✅	❌

前提条件

• chat 和 automation 永不共享 thread_id（已确认的设计约束）
• memory == automation，无需单独处理

---

Bit 定义

BIT 0  → UI_HISTORY       → /history API 可见
BIT 1  → CONTEXT_ASSEMBLY → 组装进 context_messages

UI_REALTIME 废弃，删除。 visibility_consumer_bit 废弃，删除。 Stage bits (16/17/18) 废弃，删除。

---

消息 Mask 矩阵

消息	runtime_mode	UI_HISTORY	CONTEXT_ASSEMBLY	Mask
user_message	chat	1	1	3
user_message	automation	0	0	0
agent_reply	chat	1	1	3
agent_reply	automation	1	0	1

---

查询设计

查询	Mask	匹配规则
/history	UI_HISTORY = 1	(message_mask & 1) != 0
context_messages	CONTEXT_ASSEMBLY = 2	(message_mask & 2) != 0

---

查询结果验证

消息	Mask	/history & 1	/history	context & 2	context
chat user_message	3	1 ✅	✅	1 ✅	✅
chat agent_reply	3	1 ✅	✅	1 ✅	✅
automation user_message	0	0 ❌	❌	0 ❌	❌
automation agent_reply	1	1 ✅	✅	0 ❌	❌

---

变更清单

1. schemas/agent/visibility.py

• 删除 UI_REALTIME = 1 从 SystemVisibilityBit
• 删除 VisibilityBitRef 类
• 保留 bit_mask() 函数
• 保留 VisibilityMask 类（其他模块可能使用）

2. schemas/agent/system_agent.py

• 删除 SystemAgentLLMConfig.visibility_consumer_bit 字段

3. core/config/static/database/system_agents.yaml

• 删除 router.visibility_consumer_bit
• 删除 worker.visibility_consumer_bit

4. v1/agent/service.py

• 重写 _resolve_user_message_visibility_mask：

  async def _resolve_user_message_visibility_mask(
      self, *, runtime_mode: RuntimeMode
  ) -> int:
      if runtime_mode == RuntimeMode.CHAT:
          return UI_HISTORY | CONTEXT_ASSEMBLY  # = 3
      return 0  # automation user_message
  

5. core/agentscope/events/store.py

• 重写 _resolve_stage_visibility_mask：
  • chat stage (router/worker) → UI_HISTORY | CONTEXT_ASSEMBLY = 3
  • automation stage (memory) → UI_HISTORY = 1
• 删除 _load_stage_visibility_bit_map 中对 visibility_consumer_bit 的依赖
• 删除 system_agents.yaml 配置加载逻辑

6. core/agentscope/runtime/context_service.py

• load_context_messages 查询 mask 改为 CONTEXT_ASSEMBLY = 2

  visibility_mask = bit_mask(bit=int(SystemVisibilityBit.CONTEXT_ASSEMBLY))
  

7. core/agentscope/runtime/tasks.py

• 删除 _build_recent_context_messages 中 memory job 的特殊处理
• memory mode 改用 runtime_mode=automation 语义

8. core/agentscope/runtime/runner.py

• 删除硬编码 visibility_consumer_bit=18 的 SystemAgentLLMConfig
• memory agent 配置改用 automation 语义

9. 清理迁移

• 更新 schemas/agent/__init__.py 导出（删除 visibility_consumer_bit 相关）
• 更新所有引用 visibility_consumer_bit 的文件
• 运行测试验证 /history 和 context 组装行为

---

实施顺序

1. 新增 CONTEXT_ASSEMBLY = 1 bit，更新 service.py
2. 更新 events/store.py 可见性逻辑
3. 更新 context_service.py 查询 mask
4. 清理废弃配置和字段
5. 运行测试验证

---

风险

• VisibilityBitRef 可能在其他未知位置使用（需全面搜索）
• visibility_consumer_bit 被 runner.py 硬编码，修改可能影响 memory pipeline
• 测试覆盖不足可能导致 regression