zl-q
80ad5141a6
Visibility mask refactoring: - Replace dead UI_REALTIME bit with CONTEXT_ASSEMBLY (bit 1) - Remove visibility_consumer_bit from SystemAgentLLMConfig and system_agents.yaml - Simplify _resolve_user_message_visibility_mask: chat->UI_HISTORY|CONTEXT_ASSEMBLY, automation->0 - Simplify _resolve_stage_visibility_mask: memory->UI_HISTORY, router/worker->UI_HISTORY|CONTEXT_ASSEMBLY - Remove stage_visibility_bit_map from store.py Task queue renaming: - Replace default_broker/bulk_broker/critical_broker with worker_agent_broker/worker_automation_broker - Queue names: 'default'/'bulk'/'critical' -> 'agent'/'automation' - Rename run_command_task -> run_command_task_agent/run_command_task_automation - AgentService derives queue from runtime_mode: chat->agent, automation->automation Architecture cleanup: - Move context_service.py from runtime/ to agentscope/services/ - Add MemoryService in v1/memory/ following repository/service pattern - Move consumer_registry.py and pipeline_spec.py from schemas/agent to agentscope/schemas/ - Delete dead code: registry_builder.py, VisibilityBitRef - Delete superseded plan docs
152 lines
4.5 KiB
Markdown
152 lines
4.5 KiB
Markdown
# 可见性掩码重构方案
|
||
|
||
> 日期：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
|