docs(feat): merge NEW_FEAT into FEAT and remove NEW_FEAT.md
This commit is contained in:
35
FEAT.md
35
FEAT.md
@@ -121,3 +121,38 @@ Turn management is handled entirely by the plugin. Manual control via slash comm
|
||||
- Member list with pagination + field projection
|
||||
- Guardrails: action validation, id-list limits, response-size limit
|
||||
- (Migrated) Discord control now runs in-plugin via direct Discord REST (no companion service)
|
||||
|
||||
---
|
||||
|
||||
## NEW_FEAT 合并记录（原 NEW_FEAT.md）
|
||||
|
||||
### 背景与目标
|
||||
- 解决 turn 初始化依赖被动观察（`recordChannelAccount`）导致 `currentSpeaker` 空值的问题。
|
||||
- 将 Discord control 从 sidecar 迁移到插件内模块。
|
||||
- 采用 channel 成员缓存（内存 + 本地持久化），避免轮询。
|
||||
|
||||
### 关键实现方向
|
||||
- 统一 channelId 解析链路，避免 `channel=discord` 错位。
|
||||
- `before_model_resolve / before_prompt_build` 与消息 hook 使用一致解析策略。
|
||||
- 清理未使用函数，降低排障噪音。
|
||||
- 模块化重构：`index.ts` 作为 wiring，逻辑拆入 `hooks/core/tools/policy/commands`。
|
||||
|
||||
### Channel 成员缓存
|
||||
- 缓存文件：`~/.openclaw/dirigent-channel-members.json`
|
||||
- 启动加载、运行时原子写盘。
|
||||
- 记录字段包含 `botAccountIds/updatedAt/source/guildId`。
|
||||
- 首次无缓存时允许 bootstrap 拉取，随后走本地缓存。
|
||||
|
||||
### Turn 初始化改造
|
||||
- `ensureTurnOrder(channelId)` 基于缓存中的 botAccountIds 初始化。
|
||||
- 不再仅依赖“已见账号”被动记录。
|
||||
- 提升新频道首条消息场景的稳定性。
|
||||
|
||||
### 权限计算（频道可见成员）
|
||||
- 通过 guild 成员 + roles + channel overwrites 计算 `VIEW_CHANNEL` 可见性。
|
||||
- 用于内部 turn bootstrap，不对外暴露为公共工具。
|
||||
|
||||
### 风险与注意
|
||||
- 权限位计算必须严格按 Discord 规则。
|
||||
- 缓存读写需原子化，防并发损坏。
|
||||
- 通过 `updatedAt/source/guildId` 提高可观测性与排障效率。
|
||||
|
||||
185
NEW_FEAT.md
185
NEW_FEAT.md
@@ -1,185 +0,0 @@
|
||||
# NEW_FEAT — Dirigent 设计草案（channel 成员缓存驱动 turn 初始化）
|
||||
|
||||
## 背景
|
||||
|
||||
当前 turn manager 初始化依赖 `recordChannelAccount`（被动观察频道里出现过哪些 bot account）。
|
||||
在新频道/低活跃频道中，可能出现 turn state 未及时建立，导致 `currentSpeaker` 为空（`undefined/null`）并引发调度异常。
|
||||
|
||||
（已完成迁移）原 `discord-control-api` sidecar 带来部署与运维复杂度，现已改为插件内直连 Discord REST。
|
||||
|
||||
---
|
||||
|
||||
## 目标
|
||||
|
||||
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. 增加调试日志与回归测试（新频道首条消息场景）
|
||||
Reference in New Issue
Block a user