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`：
  ```python
  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`
  ```python
  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