186 lines
6.1 KiB
Markdown
186 lines
6.1 KiB
Markdown
# NEW_FEAT — Dirigent 设计草案（channel 成员缓存驱动 turn 初始化）
|
||
|
||
## 背景
|
||
|
||
当前 turn manager 初始化依赖 `recordChannelAccount`（被动观察频道里出现过哪些 bot account）。
|
||
在新频道/低活跃频道中，可能出现 turn state 未及时建立，导致 `currentSpeaker` 为空（`undefined/null`）并引发调度异常。
|
||
|
||
同时，`discord-control-api` 以独立 sidecar 运行增加了部署与运维复杂度。
|
||
|
||
---
|
||
|
||
## 目标
|
||
|
||
1. 将 Discord control 能力从独立 API server 收敛为插件内模块（类似 turn-manager.ts 的内部模块化）。
|
||
2. 引入 **channel 成员列表缓存（内存 + 本地文件持久化）**，作为 turn 初始化的权威输入。
|
||
3. 成员列表采用 **事件/工具触发更新**，不轮询。
|
||
|
||
---
|
||
|
||
## 方案总览
|
||
|
||
### A. 架构调整
|
||
|
||
- 新增模块：`plugin/discord-control.ts`
|
||
- 迁移当前 `discord-control-api/server.mjs` 的核心能力为模块函数：
|
||
- `channelPrivateCreate`
|
||
- `channelPrivateUpdate`
|
||
- `guildMemberList`
|
||
- `channelMemberList`（新增）
|
||
|
||
> 说明：`channelMemberList` 通过 Discord 权限计算（guild 成员 + channel overwrite）得到可见成员。
|
||
|
||
---
|
||
|
||
### B. channel 成员缓存（内存 + 本地持久化）
|
||
|
||
建议新增缓存文件（示例）：
|
||
- `~/.openclaw/dirigent-channel-members.json`
|
||
|
||
结构示例：
|
||
|
||
```json
|
||
{
|
||
"1479928646830391346": {
|
||
"guildId": "1368531017534537779",
|
||
"memberUserIds": ["..."],
|
||
"botAccountIds": ["neon", "nav", "lyn"],
|
||
"updatedAt": "2026-03-07T21:40:00Z",
|
||
"source": "tool|bootstrap|channel-private-update"
|
||
}
|
||
}
|
||
```
|
||
|
||
插件启动时加载到内存；更新时先改内存再原子写盘。
|
||
|
||
---
|
||
|
||
### C. 更新策略（不轮询）
|
||
|
||
只在以下时机刷新某 channel 成员：
|
||
|
||
1. 通过指定工具显式更新（手动触发）
|
||
2. `channel-private-create` 成功后刷新该 channel
|
||
3. `channel-private-update` 成功后刷新该 channel
|
||
4. （建议兜底）首次遇到无缓存 channel 时允许一次 bootstrap 拉取并落盘
|
||
|
||
> 除上述触发外，不做轮询保活。
|
||
|
||
---
|
||
|
||
### D. turn manager 初始化改造
|
||
|
||
当前：
|
||
- `ensureTurnOrder()` 依赖 `recordChannelAccount` 的被动观察结果
|
||
|
||
改造后：
|
||
- `ensureTurnOrder(channelId)` 直接读取 channel 成员缓存中的 `botAccountIds`
|
||
- 有可用 bot 列表即 `initTurnOrder(channelId, botAccountIds)`
|
||
- 不再把 `recordChannelAccount` 作为主初始化来源（可保留为辅助观测）
|
||
|
||
预期效果：
|
||
- 新频道首次消息即可建立 turn state
|
||
- 避免 `currentSpeaker` 长时间空值导致的并发生成异常
|
||
|
||
---
|
||
|
||
### E. 统一 channelId 解析（`deriveDecisionInputFromPrompt` 对齐 `extractDiscordChannelId`）
|
||
|
||
问题点：
|
||
- `deriveDecisionInputFromPrompt(prompt, messageProvider, ctx.channelId)` 目前可能优先使用 `ctx.channelId`。
|
||
- 在 OpenClaw 的 Discord 场景中，`ctx.channelId` 常是平台名（`"discord"`），不是 snowflake。
|
||
|
||
改造建议：
|
||
- 在 `before_model_resolve / before_prompt_build` 路径中，先走与消息钩子一致的解析逻辑：
|
||
1. `extractDiscordChannelId(ctx, event)`（优先）
|
||
2. `sessionKey` 正则兜底（`discord:(channel|group):<id>` 或 `:channel:<id>`）
|
||
3. prompt 中 untrusted metadata（`chat_id` / `conversation_label` / `channel_id`）作为最后兜底
|
||
- `ctx.channelId` 仅作为末级 fallback，不再作为高优先级输入。
|
||
|
||
目标：
|
||
- 让 `message_received / message_sent / before_model_resolve / before_prompt_build` 使用一致的 channelId 来源，避免出现 `channel=discord` 导致 turn/policy 失配。
|
||
|
||
---
|
||
|
||
### F. 清理未使用函数（减小维护噪音）
|
||
|
||
当前检查到 `plugin/index.ts` 中存在未被引用的函数：
|
||
- `normalizeSender(...)`
|
||
- `normalizeChannel(...)`
|
||
|
||
计划：
|
||
- 在完成 channelId 解析统一改造后，移除上述未使用函数与相关无效注释。
|
||
- 如后续确实需要其语义，改为在统一解析模块内落地实际调用，不保留“仅定义不使用”的中间状态。
|
||
|
||
目标：
|
||
- 降低代码噪音，避免误导排障（看起来像在用，实际没走到）。
|
||
- 保持关键路径（sender/channel 解析）只有一套可追踪实现。
|
||
|
||
---
|
||
|
||
## Discord 权限计算要点（channelMemberList）
|
||
|
||
按 Discord 规则计算 `VIEW_CHANNEL` 可见性：
|
||
|
||
1. 基于 guild 基础权限（@everyone + 角色）
|
||
2. 叠加 channel `permission_overwrites`：
|
||
- @everyone overwrite
|
||
- role overwrites（合并）
|
||
- member overwrite（最终）
|
||
3. 最终判定是否可见频道
|
||
|
||
> 私密线程与普通私密文本频道语义不同，需分路径处理。
|
||
|
||
---
|
||
|
||
## 风险与注意
|
||
|
||
- 权限位计算需严格按 Discord bitfield 规则实现，否则成员集会偏差。
|
||
- 缓存文件读写要原子化，防止并发写损坏。
|
||
- 建议记录 `updatedAt/source` 便于排查“成员集为何变化”。
|
||
|
||
---
|
||
|
||
### G. 模块化重构（拆分 `plugin/index.ts`）
|
||
|
||
现状：
|
||
- `plugin/index.ts` 体积过大，hook、工具、状态、解析逻辑耦合在一起，排障成本高。
|
||
|
||
重构方向：
|
||
- `plugin/hooks/`
|
||
- `message-received.ts`
|
||
- `before-model-resolve.ts`
|
||
- `before-prompt-build.ts`
|
||
- `before-message-write.ts`
|
||
- `message-sent.ts`
|
||
- `plugin/core/`
|
||
- `decision-input.ts`
|
||
- `channel-resolver.ts`
|
||
- `session-state.ts`
|
||
- `plugin/policy/`
|
||
- `policy-store.ts`
|
||
- `policy-resolver.ts`
|
||
- `plugin/tools/`
|
||
- `discord-control-tools.ts`
|
||
- `policy-tools.ts`
|
||
- `plugin/index.ts`
|
||
- 仅保留 wiring（注册工具 + 注册 hooks + 生命周期管理）
|
||
|
||
目标：
|
||
- 单文件职责清晰，便于定位问题与编写回归测试。
|
||
- 关键路径（channel/sender/session/turn）统一入口，避免同逻辑多处实现漂移。
|
||
|
||
---
|
||
|
||
## 里程碑建议
|
||
|
||
1. 抽离 `discord-control.ts`（功能等价迁移）
|
||
2. 增加成员缓存存储与读写
|
||
3. 实现 `channelMemberList` 权限计算
|
||
4. 打通 create/update 工具触发刷新
|
||
5. 改造 turn 初始化读取缓存
|
||
6. 统一 channelId 解析到 `extractDiscordChannelId` 路径
|
||
7. 清理未使用函数（`normalizeSender` / `normalizeChannel`）
|
||
8. 模块化拆分 `plugin/index.ts`（最少先拆 core 解析层）
|
||
9. 增加调试日志与回归测试（新频道首条消息场景）
|