refactor(agent): restructure visibility masks, task queues, and memory service
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
This commit is contained in:
zl-q
@@ -0,0 +1,151 @@
|
||||
# 可见性掩码重构方案
|
||||
|
||||
> 日期：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
|
||||
Reference in New Issue
Block a user