---
title: Weixin 群聊渠道接入设计
created: 2026-05-08
updated: 2026-05-12
status: **方案 5 (WCDB DB 读+SendInput) 已被选为最终方案**(2026-05-12 更新);原 ClawBot/WCF/WeCom 讨论保留作为决策记录
---

> **📌 2026-05-12 最终结论**:  
> 1. **原 2026-05-08 Phase 1-6 实施的所有与传输层无关的代码(chat_scope / errors / group entity / agent_channel_group service+controller / agent_executor chatScope / 前端 UI)全部保留**,复用率 ~90%。  
> 2. **传输层从 "iLink ClawBot HTTP" 切换到 "WCDB SQLCipher DB 读取 + Win32 SendInput 回复"**(新渠道类型 `weixin-db`)。  
> 3. 2026-05-09 的 UIA 方案(spec `2026-05-09-wechat-uia-channel-design.md`)因 Weixin 4.x 用 Qt 自绘 UI(UIA 树空)**作废**。  
> 4. **已验证**:Weixin 4.1.8.107 的 `message_0.db` 可完整解密(见 `docs/superpowers/specs/2026-05-11-weixin-4x-db-decrypt-progress.md`)。  
>   
> 本文档的**历史方案分析(方案 1-4)保留**作为决策证据;**方案 5 的实施规范写在本文档末尾**。请优先阅读文档末尾 "方案 5 · 落地规范" 章节。  
  
# Weixin 群聊渠道接入设计

## Context

> ⚠️ **下文 "Context" 到 "方案 4 分析" 为 2026-05-08 原始设计讨论 + 2026-05-08 "后记"的历史记录**。  
> 请优先阅读文档顶部的 2026-05-12 更新摘要 + 文档末尾的 "方案 5 · 落地规范"。  
> 原文保留为决策证据;下文任何与方案 5 冲突的细节以方案 5 为准。

当前 Neta 的微信渠道(`packages/backend/src/modules/netaclaw/service/agent_channel.ts`)在 `routeInboundMessage` 里遇到带 `room_id` 的消息直接 `return`,彻底屏蔽了群聊。业务场景需要把同一个绑定 bot 的 agent 同时服务于私聊与群聊，典型场景例如客服群、项目研发群、家人群。

参考实现：hermes-agent 的 weixin 适配器已经支持群聊，核心是"三档策略 + chat_type 区分 + sessionId 多维隔离"，但 hermes 的群准入靠人类去另一个地方粘贴 room_id 白名单，UX 较差。本设计采用"被动发现 + 默认禁用 + 前端 toggle 启用"的方式，兼顾安全与便利。

接入群之后必须解决：

1. **如何加入群**：没有 iLink 侧的 join API，全靠人类在手机微信里把 bot 拉进群；代码侧做"被动发现 + 可见清单"。
2. **何时回话**：群里每条消息都回答会造成风控+噪音，必须支持 "@机器人 / 前缀 / 所有消息" 三档策略，按群独立配置。
3. **日志在哪看**：复用现有 agent 对话页的会话列表 + session tree，不新建页面。

## 总体架构

```
微信群消息
  └─ weixin.ts.getUpdates
       └─ agent_channel.ts.routeInboundMessage（同步、零 DB I/O）
             ├─ decideChatScope(message, accountId) → dm / group
             ├─ dm 路径：先查 pendingClarify[dm key]，命中则同步 resolve；否则入 DM senderQueue
             └─ group 路径：
                  ① 同步：先查 pendingClarify[group key=(cid,roomId,senderId)]，命中则 consumePendingClarifyReply 同步 resolve，不入队
                  ② 否则构造 chatScope，按 chat scope 选 senderQueue key
                       · DM key  = channel:<cid>:weixin:<senderId>
                       · 群 key  = channel:<cid>:weixin:group:<roomId>   ← 群级共享，所有人串行
                  ③ fire-and-forget 入 senderQueue
             └─ senderQueue 异步链（首位是群路径专属预处理）：
                   ① ChannelGroupService.upsertOnInbound（被动发现，默认 disabled）
                   ② 读 group entity → decideGroupAcceptance（status + triggerMode 判定）
                   ③ 拒绝 → 丢弃并日志（reject 走 debug 级别，避免群活跃刷屏）
                   ④ 通过 → stripLeadingMention/stripLeadingPrefix 清洗文本
                   ⑤ handleInboundMessage(channel, state, scope, cleanedText)
                         ├─ agentExecutor.execute({ chatScope, message, onClarifyRequest, ... })
                         │     ├─ beforeToolCall：chatScope==='group' && detectToolRisk 命中 → throw GroupInteractionDeclineError
                         │     ├─ onClarifyRequest：群路径发文本选项到群 + pendingClarify[group key] + 300s timeout
                         │     ├─ runner 主体 catch (isInteractionDecline) → finalContent=declineMessage short-circuit
                         │     └─ 写入 assistant entry + metadata
                         ├─ ChannelGroupService.touchActive（仅群路径）
                         └─ weixinService.sendText(to=replyTarget, result.content)
                                · DM replyTarget = senderId
                                · 群 replyTarget = roomId（拒绝文字 / clarify 选项 / 正常回复走同一路径）
```

- **关键不变量**：`routeInboundMessage` 严格同步、零 DB I/O，与上一轮死锁修复保持一致。所有 DB 写（`upsertOnInbound` / `touchActive`）都发生在 senderQueue 异步链路里。
- **群级串行（P0-1 决策）**：群 sessionId 全 sender 共享同一个 senderQueue，保证 session tree 写入有序，**LLM 看到的群对话是连贯的多人线程**而非 fork 出的孤岛分支。代价是 A 在等 agent 跑期间 B 的群消息要排队，群机器人可接受。
- **群内风险确定性拒绝**：命中 `detectToolRisk` 的工具在群里**不走确认流程**，直接抛 `GroupInteractionDeclineError`，runner short-circuit 把拒绝文字当作 `finalContent` 返回，`agent_channel` 把它发到群里。不依赖 LLM 自由发挥。
- **群内 Clarify 受约束地支持**：Clarify 无害，群里允许；pendingClarify key 含 senderId 确保只收发起者回复，Promise 加 300 秒超时避免 senderQueue 被卡住；超时用同一个 `GroupInteractionDeclineError` short-circuit。
- sessionId 规则：
  - DM：`channel:<cid>:weixin:<senderId>`（保持兼容）
  - 群：`channel:<cid>:weixin:group:<roomId>` —— **一群一会话**（真共享）
- 前端不新增对话页面；`channel-management.vue` 加 `群聊管理` 抽屉；agent 对话页列表自动显示群会话。

## 数据模型

### 新增表 `netaclaw_agent_channel_group`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint PK auto | 自增主键 |
| `channelId` | bigint, FK logical | 指向 `netaclaw_agent_channel.id`（项目规范不用 FK 约束，service 层显式级联） |
| `roomId` | varchar(255) | iLink room_id，如 `12345@chatroom`；255 兜底未知上限 |
| `roomName` | varchar(256) nullable | 群名，首次可空，可刷新 |
| `status` | tinyint default 0 | `0 = disabled（默认）` / `1 = enabled` |
| `triggerMode` | varchar(32) default `at_mention` | `at_mention` / `prefix` / `all` |
| `triggerPrefix` | varchar(64) nullable | triggerMode=prefix 时必填 |
| `firstSeenAt` | datetime | 首次发现时间 |
| `lastSeenAt` | datetime | 最近一次群消息触达 |
| `lastActiveAt` | datetime nullable | 最近一次 bot 真正回复的时间 |
| `createTime / updateTime` | datetime | 标准字段 |

索引：`UNIQUE(channelId, roomId)`。

**级联清理（P1-4）**：channel 删除路径必须显式 `groupRepo.delete({ channelId })`；不依赖 FK ON DELETE。

**并发 upsert（P1-3）**：`upsertOnInbound` 用 `findOne` + `update`（已存在）/ `repo.upsert`（不存在 + race 时 catch + 重查 + update lastSeenAt）的组合实现，既保留 `firstSeenAt` 不被覆盖（TypeORM `upsert` 不支持条件更新），又规避并发竞态。返回 `{ created: boolean }` 让上层决定是否打"群被发现"日志。

### `netaclaw_agent_channel.config` 扩展（Json）

```ts
interface NetaClawAgentChannelConfig {
  // …existing…
  group?: {
    /** bot 在群里显示的昵称，用于 @ 匹配的文本回落（P1-1 强校验项） */
    botAlias?: string;
  };
}
```

**不加全局 groupPolicy 白名单字段**——准入已经落到 `netaclaw_agent_channel_group.status` 表里，实现等价 allowlist 语义但列表由后端被动发现填充，无需人工粘贴 roomId。

### 会话 / dispatch key 规则

```ts
export function buildDmSessionId(channelId: number, senderId: string): string {
  return `channel:${channelId}:weixin:${senderId}`;
}
export function buildGroupSessionId(channelId: number, roomId: string): string {
  return `channel:${channelId}:weixin:group:${roomId}`;
}
export function buildDmDispatchKey(channelId: number, senderId: string): string {
  return `channel:${channelId}:weixin:${senderId}`;
}
export function buildGroupDispatchKey(channelId: number, roomId: string): string {
  return `channel:${channelId}:weixin:group:${roomId}`;  // 群级共享，不含 senderId
}
export function buildDmClarifyKey(channelId: number, senderId: string): string {
  return `channel:${channelId}:weixin:${senderId}`;
}
export function buildGroupClarifyKey(channelId: number, roomId: string, senderId: string): string {
  return `channel:${channelId}:weixin:group:${roomId}:${senderId}`;  // 群里 clarify 仍按发起者收答
}
```

`senderQueues` 使用 dispatch key 作为队列 key：

| 场景 | dispatch key | 并发行为 |
|---|---|---|
| 私聊 A | `channel:1:weixin:A` | A 自己消息按到达顺序串行；与 B 并发 |
| 私聊 B | `channel:1:weixin:B` | 与 A 并发 |
| 群 R 内 A | `channel:1:weixin:group:R` | A、B、C 在群 R 的消息**全部串行**，按到达顺序排队 |
| 群 R 内 B | `channel:1:weixin:group:R` | 同上（共享队列） |
| 群 R2 内任何人 | `channel:1:weixin:group:R2` | 与群 R 并发 |
| 私聊 A | `channel:1:weixin:A` | 与群路径并发，私聊不被群里堵塞 |

**pendingClarify 在群里仍然支持**（详见"风险拒绝与 Clarify"节）。两套 key 系统并存：
- `senderQueues` 用 dispatch key（群级共享）：保证群内多人消息严格按到达顺序串行进 agent。
- `pendingClarify` 用 clarify key（含 senderId）：保证 clarify 只接受**发起者**本人的回复，群里其他人乱回的"1"会被忽略走 trigger 判定。

`routeInboundMessage` 在群路径里**先做 pending reply 短路**：
```
if pendingClarify.has(buildGroupClarifyKey(cid, roomId, senderId)):
    consumePendingClarifyReply(...)  # 同步 resolve，不入 senderQueue
    return
```
这样发起者的回复永远走"答复" 路径，不会被解析为新消息再次触发 trigger 判定。

## 触发策略与风险处理

### 准入判定

```ts
function decideGroupAcceptance(
  group: NetaClawAgentChannelGroupEntity,
  message: WeixinInboundMessage,
  text: string,                   // routeInboundMessage 已用 weixinService.extractText 提取过的文本
  channelConfig: NetaClawAgentChannelConfig,
  credential: WeixinCredential,
): { accept: boolean; cleanedText?: string; reason?: string }
```

**关键：text 由调用方一次性提取并传入**，避免 chat_scope.ts 的纯函数版与 weixinService.extractText 的业务版双源不一致（P0-1 修订）。`detectAtMention` 同样接收 `text` 入参。

流程：

1. `group.status !== 1` → reject `group_disabled`
2. 按 `triggerMode` 分流（text 由调用方提供）：
   - `all`：无条件 accept，cleanedText = text
   - `prefix`：text 起始匹配 `group.triggerPrefix` → accept 并 `stripLeadingPrefix`；否则 reject
   - `at_mention`（默认）：协议字段优先 → 文本回落 → accept 并 `stripLeadingMention`；否则 reject

### `detectAtMention` 双层检测

签名：`detectAtMention(message, text, aliases, accountIds): boolean`。`text` 由调用方提供，与 `decideGroupAcceptance` 同步。

1. **协议层**：先对 `message` / `item_list[*]` 扫描常见字段名 `at_user_list` / `mention_list` / `at_info`（开发首日先打 raw payload 日志，确认 iLink 真实字段名后再固化代码——见 P1-7）。命中条件：list 中含 `credential.accountId` 或 `credential.userId`。
2. **文本回落**：构造别名集合 `aliases = [config.group.botAlias, credential.nickname].filter(Boolean)`。如果两者都为空，文本回落直接判 false（前端在保存触发策略时会强校验，避免出现这种状态——见 P1-1）。

   匹配正则要求 alias 是**完整 token**，且 `@` 前必须是空白或字符串开头（防止 `email@小神.com` 这类邮箱地址误命中——P2-6 修订）：

   ```ts
   // @ 前必须是 字符串开头 / 空白 / 中文标点 / U+2005 / U+3000
   // alias 后必须紧跟 空白 / U+2005 / U+3000 / 标点 / 字符串结束
   const trailing = `(?=$|[\\s\\u2005\\u3000\\p{P}])`;
   const leading = `(?<=^|[\\s\\u2005\\u3000])`;
   const atRegex = new RegExp(`${leading}@(?:${aliases.map(escape).join('|')})${trailing}`, 'u');
   ```

   `\p{P}` 覆盖中英标点（需 ES2018+ Unicode property escapes）。

误伤测试用例（见测试节）：
- `@小神 你好` → 命中（alias=小神）
- `@小神同学 你好` → 不命中（alias 后紧跟汉字）
- `今天 @小神 帮看下` → 命中（中段也算 @ 命中——agent 拿完整文本，trigger 只是开关）
- `@小神聊天群 大家好` → 不命中（"群"字接在 alias 后无分隔符）
- `我的邮箱 email@小神.com` → 不命中（@ 前是字母，不是空白——新增 leading 约束）
- `foo@小神 帮我查` → 不命中（同上）
- `@小神，你好` → 命中（alias 后紧跟中文逗号，\p{P} 覆盖）

### 清洗文本

- `stripLeadingMention(text, aliases)`：**仅移除文本起首处**的 `@<alias>` 与随后空白；中段的 `@` 保留（可能是 @ 群里其他人）。

  ```ts
  const leading = new RegExp(`^@(?:${aliases.map(escape).join('|')})[\\s\\u2005\\u3000]*`, 'u');
  return text.replace(leading, '');
  ```

- `stripLeadingPrefix(text, prefix)`：去除起首处前缀与随后空白。

清洗后的文本作为 `agentExecutor.execute({ message })`，避免污染 agent context。

### 风险工具：群内必须显式回复"已拒绝"

群里风险工具不能"静默 block"——必须确定性把拒绝消息发到群里，告知用户为什么没动作。**不能依赖 LLM 自由发挥是否说明**。

实现机制：自定义错误 + runner short-circuit。

```ts
// runtime/errors.ts（新增）
export class GroupInteractionDeclineError extends Error {
  readonly isInteractionDecline = true;
  constructor(public readonly declineMessage: string) {
    super(declineMessage);
    this.name = 'GroupInteractionDeclineError';
  }
}
```

`agent_executor` runner 的 `beforeToolCall`：

```ts
const risk = detectToolRisk(name, runtimeArgs);
if (risk) {
  if (params.chatScope === 'group') {
    throw new GroupInteractionDeclineError(
      `⚠️ 群内禁止高风险操作：${toolLabel || name}\n原因：${risk}\n👉 请点我头像私聊 bot 继续`
    );
  }
  // dm 路径继续走 onRiskConfirmRequest
}
```

runner 主体外层 try/catch 识别此错误并 short-circuit：

```ts
try {
  runResult = await this.agentRunner({ ... });
} catch (err: any) {
  if (err?.isInteractionDecline) {
    return {
      finalContent: err.declineMessage,
      thinking: thinkingText || undefined,
      usage: undefined,
      toolCallCount: toolExecutions.length,
      metadata: buildToolExecutionMetadata(toolExecutions),
    };
  }
  // 原有错误处理（标记 running tool 为 error、加 runtimeMetadata 等）
  throw err;
}
```

效果：
- `chat_orchestrator.finalizeAssistantEntry` 拿到 `finalContent` 写入 session。
- `agent_channel.handleInboundMessage` 现有路径 `weixinService.sendText(replyTarget, result.content)` **直接把这条拒绝文字发到群里**，无需额外分支。
- assistant entry 的 metadata.skillExecutions 仍包含被 block 的 tool 条目（带 status='error'、reason），前端对话页能看到完整决策轨迹。

### Clarify 在群内允许，但有三条约束

Clarify（agent 主动问选择题）本身不危险，群里允许使用，但要解决"谁来回答"和"会不会卡住"。

**约束 1 · 答复者必须是发起者**：pendingClarify key 含 senderId（见 key 规则节）。其他人发的"1/2"不会被识别为答复，继续走 trigger 判定。

**约束 2 · routeInboundMessage 先做 pending 短路**：群消息先查 `pendingClarify[group clarify key]`，命中即 `consumePendingClarifyReply` 同步 resolve，不入 senderQueue、不再走 trigger 判定。避免发起者的"1"被当成新消息触发新对话。

**约束 3 · 强制超时**：发起者长期不回复会让群 senderQueue 被该 await 占住，后续群消息全部排队。群路径的 clarify Promise 加默认 300 秒超时：

```ts
function withClarifyTimeout<T>(promise: Promise<T>, timeoutMs = 300_000): Promise<T> {
  return Promise.race([
    promise,
    new Promise<T>((_, reject) =>
      setTimeout(
        () => reject(new GroupInteractionDeclineError('⏱️ 等待 5 分钟未收到回复，已自动取消本次询问')),
        timeoutMs,
      ),
    ),
  ]);
}
```

超时复用同一个 `GroupInteractionDeclineError`：runner short-circuit 后 finalContent 自动发到群，pendingClarify 在 finally 里清理，senderQueue 释放。

`agent_channel.ts` 群路径下 `onClarifyRequest` 实现：

```ts
onClarifyRequest: async (question, choices) => {
  let msg = `❓ ${question}`;
  if (choices?.length) {
    msg += '\n' + choices.map((c, i) => `${i + 1}. ${c}`).join('\n');
    msg += `\n\n（仅 @${botAlias || '机器人'} 的发起者本人可回复，5 分钟超时）`;
  }
  await this.weixinService.sendText(credential, roomId, msg, contextToken);
  const clarifyKey = buildGroupClarifyKey(channelId, roomId, senderId);
  const promise = new Promise<string>(resolve => {
    this.pendingClarify.set(clarifyKey, { resolve, choices });
  });
  return withClarifyTimeout(promise, 300_000)
    .finally(() => this.pendingClarify.delete(clarifyKey));
}
```

DM 路径 onClarifyRequest 不加超时（私聊场景没有"卡住整个群"的问题），保持现状。

### 风险确认仅在 DM 提供

群路径**不传** `onRiskConfirmRequest`。即使误传，前置 `chatScope==='group'` 分支已 throw `GroupInteractionDeclineError`，不会走到回调。

### 持久化钩子

- `upsertOnInbound(channelId, roomId, roomName?) -> { created: boolean }`：先 `findOne` 查询；命中只 update `lastSeenAt`（与可选 `roomName`），返回 `{ created: false }`；未命中走 `repo.upsert` 落 `firstSeenAt + lastSeenAt + status=0 + triggerMode=at_mention`，返回 `{ created: true }`。upsert 抛 race 异常时 catch + 重查 + update lastSeenAt 兜底，仍返回 `{ created: false }`。**`created: true` 触发上层打 `group discovered` info 日志。**
- `touchActive(channelId, roomId)`：在 `handleInboundMessage` 的 `sendText` 成功后调用，更新 `lastActiveAt`。

## 前端 UX

### 频道卡片（`channel-management.vue`）

- 元数据行加 `群聊 X/Y` 徽标（`X=enabled`, `Y=discovered`）。已连接的微信频道才显示。
- 操作栏加按钮：`群聊管理`。
- 频道编辑 drawer 增加字段：`微信机器人昵称`（绑到 `config.group.botAlias`）。

### 群聊管理抽屉（新组件 `channel-group-panel.vue`）

```
┌─ 群聊管理 · 老板微信 ─────────────────────[x]─┐
│                                              │
│ 共发现 5 个群 · 已启用 2 个     [刷新]         │
│                                              │
│ 💡 在手机微信把本账号拉进群即可自动发现。     │
│    新群默认禁用，请在下方逐个启用。            │
│                                              │
│ ┌──────────────────────────────────────┐     │
│ │ 产品研发群           [●启用]           │     │
│ │ roomId: 12345@chatroom              │     │
│ │ 首次发现 4 天前 · 最近消息 12 分钟前 │     │
│ │                                      │     │
│ │ 触发策略  (●) @机器人                 │     │
│ │           ( ) 前缀                    │     │
│ │           ( ) 所有消息                │     │
│ │ 前缀     [___________]  (仅前缀模式) │     │
│ │                                      │     │
│ │         [查看对话记录]  [保存]        │     │
│ └──────────────────────────────────────┘     │
│                                              │
│ ┌──────────────────────────────────────┐     │
│ │ 家人群  [○禁用]  ...                 │     │
│ └──────────────────────────────────────┘     │
│                                              │
│ 📌 禁用后 bot 不再回复该群消息，但仍留在群内。│
│    如需让 bot 离开群，请在手机微信中移除。     │
└──────────────────────────────────────────────┘
```

- 状态 switch：即点即切（toggle API）。
- 触发策略 / 前缀：必须点 `保存` 才提交，避免误触。
- **前端强校验（P1-1）**：保存触发策略时，若选 `at_mention` 但 channel.config.group.botAlias 为空，弹警告"请先回到频道编辑页填写 bot 昵称，否则群里永远不会被识别为 @机器人"。
- `查看对话记录` 按钮 → 跳 `/agent?sessionId=channel:<cid>:weixin:group:<roomId>&agentId=<bound>`。

### agent 对话页群会话识别

- `store/chat.ts` 的 `buildFallbackTitle` 扩展：
  - sessionId 以 `channel:<cid>:weixin:group:` 起头 → 前缀 `微信群 · `（取 roomName 或 roomId 后 8 位）
  - sessionId 以 `channel:<cid>:weixin:` 起头但非 group → 前缀 `微信 · `
- **依赖 sessionId 字符串模式判别 chat kind**，不写专门的 `metadata.chat` 字段——sessionId 模板已经携带足够信息（channelId / kind / roomId-or-senderId），增加一份冗余 metadata 没有额外收益。前端渲染 icon 时用同一份正则判定。
- `chat.vue` mounted 检测 `route.query.sessionId / agentId`，自动切到对应 session。**鲁棒性（P2-f）**：agentId 必须是数字字符串，否则忽略 query 走默认逻辑。

## 代码模块与接口

### 后端新增

| 文件 | 职责 |
|---|---|
| `entity/agent_channel_group.ts` | TypeORM Entity |
| `service/agent_channel_group.ts` | upsertOnInbound / toggle / updatePolicy / rename / touchActive / list / cascadeDeleteByChannel |
| `controller/admin/agent_channel_group.ts` | `@CoolController` + 自定义 list/toggle/updatePolicy/rename/delete |
| `runtime/chat_scope.ts` | 全部纯函数：decideChatScope / buildXxxSessionId / buildXxxDispatchKey / detectAtMention / stripLeadingMention / stripLeadingPrefix / decideGroupAcceptance |

### 后端修改

| 文件 | 改动 |
|---|---|
| `service/agent_channel.ts` | routeInboundMessage 按 chat_scope 分流；群路径先查 pendingClarify 短路；senderQueues key 改为 dispatch key（群级共享）；upsert/decideGroupAcceptance 移到 senderQueue 异步链；群路径 onClarifyRequest 发群消息 + 300s 超时 |
| `service/agent_executor.ts` | execute() 入参加 chatScope；beforeToolCall 命中风险时群路径抛 `GroupInteractionDeclineError`；runner 外层识别该错误 short-circuit 为 finalContent |
| `runtime/errors.ts`（新增） | `GroupInteractionDeclineError` 自定义错误 + `withClarifyTimeout` helper |
| `service/agent_channel.ts` 的 `delete()` 路径 | 调 `agentChannelGroupService.cascadeDeleteByChannel(id)` |
| `configuration.ts` / 入口 | 注册 NetaClawAgentChannelGroupEntity |
| （可选）`service/weixin.ts` | 增加 `sendGroupText` 语义别名，实质复用 sendText |

### 后端 REST 新增

```
POST /admin/netaclaw/channel/group/list          { channelId } → list
POST /admin/netaclaw/channel/group/toggle        { id, status }
POST /admin/netaclaw/channel/group/updatePolicy  { id, triggerMode, triggerPrefix? }
POST /admin/netaclaw/channel/group/rename        { id, roomName }
POST /admin/netaclaw/channel/group/delete        { ids }
```

服务端校验：
- `updatePolicy` 在 `triggerMode='prefix'` 时必须携带非空 `triggerPrefix`。
- `updatePolicy` 在 `triggerMode='at_mention'` 时校验所属 channel.config.group.botAlias 非空，否则返回 4xx 提示前端补 botAlias。

### 前端新增

| 文件 | 职责 |
|---|---|
| `components/channel-group-panel.vue` | 群列表抽屉 |
| `api/channel_group.ts` | list/toggle/updatePolicy/rename/delete 封装 |

### 前端修改

| 文件 | 改动 |
|---|---|
| `views/channel-management.vue` | 卡片徽标 + "群聊管理" 按钮 + botAlias 表单字段 |
| `store/chat.ts` | buildFallbackTitle 扩展；route.query 自动切 session（鲁棒性） |
| `views/chat.vue` | 渲染群/DM icon；mounted 里处理 `?sessionId=` |

## 测试与验证

### 单元测试

| 文件 | 覆盖 |
|---|---|
| `test/modules/netaclaw/runtime/chat_scope.test.ts` | decideChatScope 四形态；sessionId/dispatchKey 构造；detectAtMention 协议命中 / 文本命中 / 误伤（"@小神同学"、"@小神聊天群"）；stripLeadingMention 处理 U+2005、U+3000；stripLeadingPrefix；中段 @ 不被剥除 |
| `test/modules/netaclaw/service/agent_channel_group.test.ts` | upsertOnInbound 首次 insert 默认 disabled；existing 仅更新 lastSeenAt；并发 upsert 不抛 duplicate key；toggle/updatePolicy 非法入参（prefix 模式缺 prefix、at_mention 模式缺 botAlias）拒绝；cascadeDeleteByChannel；touchActive |
| `test/modules/netaclaw/service/agent_channel.group.test.ts` | routeInboundMessage 端到端：群被动发现默认不 dispatch；enable+at_mention 下 @bot 通过、普通消息拒；triggerMode=all 全部通过；**同群多人消息按到达顺序串行**（A 发起后 B 紧跟也排队，不并发开 session）；不同群间并发；**群路径 pendingClarify 命中短路**（发起者回"1"直接 resolve 不入 senderQueue）；**非发起者回"1"不被当作答复**，走常规 trigger 判定 |
| `test/modules/netaclaw/service/agent_executor.test.ts`（扩展） | chatScope='group' + 风险命中 → runner 抛 `GroupInteractionDeclineError`，外层 short-circuit 为 finalContent；onRiskConfirmRequest 未被调用；finalContent 含拒绝说明文字且 metadata.skillExecutions 含被 block 的条目；**chatScope='group' + Clarify 正常**：onClarifyRequest 调用后 resolve 正常返回；**Clarify 超时 path**：pendingClarify 长期不 resolve → withClarifyTimeout 抛 `GroupInteractionDeclineError` → runner short-circuit 为超时文案；dm 保持现状 |

### 手工验证

1. 后端 `pnpm --filter @neta/backend dev`、前端 `pnpm --filter @neta/frontend dev`
2. 在频道编辑页填写 bot 昵称（botAlias）
3. 手机微信把 bot 拉进测试群
4. 群里发一条普通消息 → 后端日志 `group discovered`，bot 不回，前端卡片徽标 `群聊 0/1`
5. 点 `群聊管理` → 看到该群，禁用状态
6. 启用 + 选 `@机器人`
7. 群里发 `你好` → bot 不回；发 `@<alias> 你好` → bot 回复
8. 测误伤：群里发 `@<alias>同学 在吗` → bot 不回（保护 token 不被前缀匹配误触）
9. 点 `查看对话记录` → 跳 agent 对话页，session 标题 `微信群 · ...`，assistant 气泡含完整工具卡片/thinking
10. 群里发 `@<alias> rm -rf /tmp/foo` → bot 在群里**明确回复** `⚠️ 群内禁止高风险操作：bash\n原因：包含文件删除命令\n👉 请点我头像私聊 bot 继续`；**不弹确认**
11. 私聊 bot 发同样指令 → bot 发 `1. 确认执行 / 2. 不执行`；回 `2` → 拒绝
12. 群切 `所有消息` → 群里任意消息 bot 都回
13. 群 `禁用` → bot 不回；卡片徽标计数更新
14. 并发回归：两个群同时 @bot + 一个 DM 并发 → 三条任务并行进 agent，群内消息顺序串行不乱
15. 删除 channel → DB 检查 group 记录已被级联清除
16. **群内 Clarify 正常流**：拉 bot 进群，配置一个会触发 clarify 的 skill（或 agent 自然需要澄清问题的对话）。A @bot 问句 → bot 群里发"❓ 问题\n1. ...\n2. ...\n（仅 @<alias> 的发起者本人可回复，5 分钟超时）"。
    - A 回 `1` → agent 继续执行
    - 同时 B 回 `1` → 被忽略，B 的消息走 trigger 判定（若未 @bot 就丢弃）
17. **群内 Clarify 超时**：发起 clarify 后不回复等 5 分钟 → bot 在群里发 `⏱️ 等待 5 分钟未收到回复，已自动取消本次询问`，pendingClarify 被清理，群 senderQueue 恢复接受新消息

### 可观测性

本次新增日志：

- `[AgentChannel] group discovered channelId=%s roomId=%s`（info 级，仅首次发现）
- `[AgentChannel] group dispatch channelId=%s roomId=%s sender=%s trigger=%s accept=%s reason=%s`（accept=true 走 info，accept=false 走 debug，避免群活跃时刷屏）
- `[AgentChannel] group risk declined channelId=%s roomId=%s tool=%s reason=%s`（warn 级，表示群里因 detectToolRisk 命中而回复拒绝消息）
- `[AgentChannel] group clarify timeout channelId=%s roomId=%s senderId=%s`（info 级，Clarify 300s 超时）

## 迁移路径

- DB schema：本地 dev 走 TypeORM `synchronize: true` 自动建表。**测试 / 生产环境的 DDL 通过 MCP MySQL 工具直接执行**（`mcp__mysql__execute` / `mcp__mysql__describe_table` / `mcp__mysql__list_tables`），不再产出 `.sql` 文件随 release 包发布——按 CLAUDE.md 项目规约统一处理。具体执行步骤见 plan Task 20。
- 老 channel 升级：现存 channel 的 `config.group` 为 undefined → 任何群消息都会进入 disabled 状态，bot 不会乱回，平滑过渡。
- 老 sessionId 兼容：DM sessionId 模板未变，已有私聊会话不受影响。

## 非目标 / 不在本 spec 范围

- **主动加入/退出群的 API**：iLink 未提供，且违反微信平台条款，永远不做。
- **群内风险确认降级**：安全考虑，命中 `detectToolRisk` 的工具在群里一律拒绝（带回执文字），不做"仅发起者能确认"的复杂流程。Clarify 不属于此范畴——无害，群里允许使用。
- **每群 botAlias override**：当前 botAlias 落在 channel 级别，假定一个 bot 在所有群里同名。如果未来需要群级覆盖，加 `netaclaw_agent_channel_group.botAliasOverride` 字段即可，不破坏现有结构。
- **企业微信 / 飞书群**：hermes 的 wecom/feishu 适配器是另一体系；本 spec 仅覆盖个人微信（iLink Bot API）。sessionId 模板里 `weixin` 段绑 channel.type，未来加新平台用各自段名（`channel:<cid>:wecom:group:...`）不冲突。
- **agent 切换语义**：channel.agentId 改后已存在 group session 的历史保留，新消息按当前 channel.agentId 处理（沿用 DM 行为）。
- **跨群 / 跨 channel 的会话合并**：每群一会话，不做跨群的全局人物志合并。
- **独立的 `metadata.chat` 字段**：session 实体**刻意不**写 `{ kind, channelId, roomId?, senderId? }` 这类冗余 metadata。sessionId 模板 `channel:<cid>:weixin:[group:]<chatId>` 已经携带所有分类信息，前端做一次 regex 判别即可渲染 icon / fallback title。多一份 metadata 增加双源一致性负担，无显著收益。（P1-5 修订决策）
- **群内消息主动推送**：只实现被触发后的回复，不做 bot 主动在群内发起话题。

---

## 后记 · iLink ClawBot 群消息接入的事实更正（2026-05-08）

> 本节是在前述设计与代码（20 个 task / 117 单测）实施完成后追加的现状报告。
> **结论先行：当前实现的群聊路径在生产环境无法被触发，因为 iLink ClawBot 协议本身不允许 bot 接收群消息**。下文记录事实、当前代码的处置建议、以及两条候选迁移路径（WeChatFerry 逆向 / 企业微信 WeCom）的改造难度。

### 1. 事实勘误：iLink ClawBot 不是用户的个人微信号

之前的设计基于"hermes weixin 适配器能收到群消息"这个假设，由此推导出"被动发现群 + 三档触发策略"的整套架构。这个假设错了。

通过查阅 iLink Bot 协议拆解资料（[openclaw-weixin/weixin-bot-api.md](https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md)、[x1ah/wechat-ilink-demo](https://github.com/x1ah/wechat-ilink-demo)、[微信开放社区 Q&A](https://developers.weixin.qq.com/community/develop/doc/000e0aeba90160ea81f45a2046b400)）确认的事实：

- **iLink ClawBot 是腾讯官方"机器人账号"**：扫码后通过 `bot_type=3` 在 iLink 平台生成一个独立 Bot ID（每次扫码 Bot ID 都会变化）。它**不是**用户自己的微信号，只是与之"关联"。
- **ClawBot 不能被人拉进任何微信群**：因为它不是普通微信号，不在好友/群成员选择列表里。
- **群消息推送当前未开放**：协议层面 `room_id` / `group_id` 字段存在，但官方明确"群聊可能需要额外权限"，目前默认状态下 iLink **不会**向 ClawBot 推送群消息。
- **腾讯官方对"个人微信号 + 群聊多人共享 Bot"的定位**：建议改用微信对话开放平台（chatbot.weixin.qq.com）或企业微信，而非 iLink Bot API。

hermes 文档里那句 "personal WeChat accounts may be in many groups" 是基于错误前提的描述，他们的群代码在 iLink 路径下也不会被触发。

### 2. 企业微信 (WeCom) 也无法接入"已有的个人微信群"

有人会自然想到"那转 WeCom 总行了吧"——也不行。腾讯封死了这条路：

- **个人微信群（已存在的）→ 企业微信账号**：❌ 协议禁止加入。
  > "原有微信群，不支持邀请企业微信联系人加入。如果要让企业微信账号进入个人微信群，**通常需要在创建群聊时就同时拉入企业微信账号**。"——[企客宝 SCRM](https://www.qikebao.com/article/qywx-qywxjzsyhtgn.html)
- **企业微信新建群 → 同时拉入个人微信用户**：✅ 但是这是企业侧主动建群（"客户群"/"互通群"），不是接入用户**已有**的个人微信群。
- 企业微信的 SCRM/客户群路径适合"客服/销售"等场景，不能解决"机器人加入老板已有的家人群、运营群、技术群"这类需求。

### 3. 三条路径的可行性矩阵

| 路径 | 加入"已有个人微信群" | 加入"新建群（同账号建）" | 协议风险 | 已有代码复用度 |
|---|---|---|---|---|
| **iLink ClawBot**（当前） | ❌ Bot 是独立账号 | ❌ 同上 | 合规 | 100%（DM 私聊有效） |
| **企业微信 WeCom** | ❌ 协议禁止 | ⚠️ 仅"企业建群拉个人微信好友"的客户群 | 合规 | 60%（架构复用，渠道层重写） |
| **WeChatFerry / wxhelper（PC Hook）** | ✅ 代理用户**真实**个人微信号 | ✅ | ❌ **违反《微信个人账号使用规范》、有封号风险** | 70%（架构复用，传输层重写） |

### 4. 当前代码的处置建议

实施完成的 20 个 task / 117 单测在以下层面**仍然有价值**：

- `chat_scope.ts`（decideChatScope / 三档准入 / detectAtMention / strippers / decideGroupAcceptance）—— 与传输层无关的纯函数，**任何"个人微信群消息接入"方案都能直接复用**。
- `runtime/errors.ts`（GroupInteractionDeclineError + withClarifyTimeout）—— 通用错误模型，无需修改。
- `agent_channel_group.{entity,service,controller}.ts` —— 群发现、状态、策略、级联删除都是渠道无关的元数据层。
- `agent_executor.ts` 的 `chatScope` 参数 + 群内风险 short-circuit —— 这是 agent 层语义，与微信底层协议无关，可直接保留。
- `routeInboundMessage` 群分流 + senderQueue 群级共享 + clarify 短路 —— 入站消息处理的通用模式。
- 前端"群聊管理"抽屉、卡片徽标、深链接跳转、`buildFallbackTitle` —— UX 层完全可复用。

**仅在以下层面是空跑**：

- `service/weixin.ts`（iLink getUpdates / sendText）当前**永远收不到 `room_id` 不为空的消息**。所以 routeInboundMessage 的 group 分支理论上不会被触发；只有 DM 路径在生产中工作。
- 群消息回复 `weixinService.sendText(credential, roomId, ...)` 同样发不出去——iLink 服务端不接受 `to_user_id = @chatroom`。

### 5. 处置建议（按时间维度）

**短期建议（本次 PR）**：

- ✅ **保留** Phase 1（纯函数 chat_scope + errors）+ Phase 2（数据层）+ Phase 3（agent_executor chatScope）+ Phase 4 的 routeInboundMessage 分流框架——这些是平台无关的能力，未来重构成本低且对当前 DM 路径有保护性（明确隔离 DM 与 group 处理路径）。
- ⚠️ **暂时禁用** Phase 5/6 的群聊管理 UI（频道页"群聊管理"按钮、`群聊 X/Y` 徽标、群聊面板）——避免误导用户以为已经能用。可以保留组件代码，但前端入口加 `v-if="false"` 或 `feature flag` 隐藏。
- ✅ **保留**前端的 ClawBot 文案修订（"扫码登录" → "ClawBot 扫码登录（个人微信助手）"，弹窗里明确"无法被拉进微信群，仅支持私聊"）。
- ❌ **不要**部署 Task 20 的 `netaclaw_agent_channel_group` 表到生产环境。测试库里已建可保留供后续路径复用。

**中长期方向**：见下两节"方案 3：WeChatFerry 路径"和"方案 4：企业微信路径"的迁移成本评估。

---

## 方案 3 分析 · 改造为 WeChatFerry / wxhelper 逆向方案

### 协议特征

- WeChatFerry 是 Windows PC Hook 协议（DLL 注入到微信客户端进程），代理**用户真实个人微信号**（[wcferry 官网](https://wcferry.netlify.app/)、[GitHub lich0821/WeChatFerry](https://github.com/lich0821/WeChatFerry)）。
- 群消息识别：`msg.roomid` 包含 `@chatroom` 即为群消息。
- bot 入群方式：用户**手动**在手机/PC 微信里把自己的微信号拉进群（=就是把自己加进去），bot 通过 hook 自动收到群消息。
- 提供完整 API：发消息 / 收消息 / 群成员管理 / 数据库直读 / 文件解密。

### 风险

- **违反《微信个人账号使用规范》**，封号风险无法消除——只能通过控制使用方式延缓。
- 作者本人 lich0821 已**停止维护**项目（2024 年起），但社区仍在用。
- 实测：约 2-3 天后可能掉线警告；高频消息 + @ 操作 + 大群行为容易触发风控。
- 必须严格匹配微信客户端版本（wcf 与微信版本绑定）。

### 改造工作量评估

| 子项 | 现有代码可复用度 | 工作量 | 说明 |
|---|---|---|---|
| `service/weixin.ts`（iLink HTTP/JSON） | ❌ 0% | **大** | 完全重写：从 long-poll HTTP 改为 wcf 的 gRPC/Socket 客户端协议 |
| `getUpdates` 长轮询 | ❌ 0% | 大 | 改为 wcf 的事件订阅/回调 |
| `sendText(credential, chatId, ...)` | ⚠️ 30% | 中 | API shape 类似（to / text），但传输层换成 wcf SDK |
| 凭证模型 (`WeixinCredential` token / accountId / baseUrl) | ⚠️ 50% | 中 | 改为 wcf 的连接信息（gRPC 端点、wxid） |
| QR 登录流程 | ❌ 0% | 中 | wcf 不需要 QR；改为"启动 wcf 服务、用户在 PC 微信内手动登录" 的引导 |
| `routeInboundMessage` 分流 | ✅ 100% | 几乎为零 | `decideChatScope(message, accountId)` 协议字段 `room_id` 与 wcf 的 `roomid` 形态一致，最多加个字段适配层 |
| `decideGroupAcceptance` / `detectAtMention` / strippers | ✅ 100% | 0 | 纯函数完全无关 |
| Group entity + service + controller | ✅ 100% | 0 | DB 层完全复用 |
| `agent_executor.chatScope` + Decline short-circuit | ✅ 100% | 0 | agent 层无关 |
| 前端 UI（群聊管理 / 徽标 / 跳转） | ✅ 95% | 小 | 仅"扫码登录"按钮替换为"启动 wcf 服务"引导 |
| 测试单测 | ✅ 100% | 0 | 都是 mock 入站 message 的，protocol-agnostic |
| 部署 / 运维 | ❌ N/A | **大** | 必须有 Windows 节点 + PC 微信客户端长期登录；Linux/Mac 服务器跑不了 |

**整体难度评估：中等**（如果只算代码改造）。**实际难度：高**（因为部署环境从 Linux 服务器变成 Windows + PC 微信客户端，运维模型完全变了）。

合规风险**高**——任何用户主号绑定 wcf 都可能封号。建议只用**小号**或**专用号**。

### 落地步骤建议（粗略）

1. 新增渠道类型 `netaclaw_agent_channel.type = 'weixin-pchook'`（与现有 `weixin` 并行）。
2. 实现 `service/weixin_pchook.ts`：封装 wcf gRPC 客户端，提供与 `weixin.ts` 同 shape 的 `getUpdates` / `sendText` 接口。
3. `agent_channel.ts.routeInboundMessage` 按 `channel.type` 分流到不同 weixin service；下游处理完全不变。
4. 前端频道编辑页加 type 选项：`微信 ClawBot（私聊）` / `微信 PC Hook（含群聊，封号风险）`。后者明确警告标语。
5. 部署文档新增 Windows 节点搭建指南。

---

## 方案 4 分析 · 改造为企业微信 (WeCom) 客户群方案

### 协议特征

- 企业微信开放平台提供官方 API（`qyapi.weixin.qq.com`）：[企微 API 文档](https://developer.work.weixin.qq.com/document/path/91039)。
- 群类型：
  - **内部群**：仅企业内成员，bot 可在企业内主动建群、加入。
  - **客户群（外部群）**：企业建群后拉个人微信好友进群，**bot 在企业侧、客户在个人微信侧**。
- 消息接收：企业微信使用回调 webhook（你提供 URL，企微 push 消息），不是 long-poll。
- bot 入群：企业建群时把"应用机器人"加为成员；客户群同理。
- **不能加入"已有的个人微信群"**——协议禁止。

### 改造工作量评估

| 子项 | 现有代码可复用度 | 工作量 | 说明 |
|---|---|---|---|
| `service/weixin.ts` 整体 | ❌ 0% | **大** | 完全重写：HTTP+签名认证、回调 webhook 接收消息、access_token 续期、不同消息类型解码（企微的消息体 schema 与 iLink 完全不同） |
| QR 登录 | ❌ 0% | 大 | 改为"安装企微应用 + OAuth 授权"，部署一次后长期有效 |
| 凭证模型 | ❌ 0% | 中 | 从 `token + accountId` 改为 `corp_id + corp_secret + agent_id` |
| 入站消息接入 | ❌ 30% | 大 | 从主动 long-poll 改为被动 webhook，需要在 Neta 后端开 HTTP endpoint，做企微签名校验 |
| `decideChatScope` | ⚠️ 60% | 小 | 企微消息里 `chat_id` / `from_user_id` 字段名不同，加适配层 |
| 三档触发策略 + at_mention 检测 | ✅ 90% | 极小 | 企微消息也有 `at_user_list`，文本里 `@xxx` 格式与微信稍有不同 |
| 群发现机制 | ⚠️ 50% | 中 | 企微提供"获取群列表"主动 API（与 iLink 的"被动发现"不同），需要重写 `upsertOnInbound` 时机——可改为"管理员触发刷新群列表"按钮 |
| Group entity + service | ✅ 100% | 0 | 完全复用 |
| `agent_executor.chatScope` + Decline | ✅ 100% | 0 | 完全复用 |
| 前端 UI | ✅ 80% | 中 | 频道管理改为"企业微信应用配置"，群聊管理抽屉小改（移除"被动发现"提示，加"刷新群列表"按钮） |
| Risk Confirm / Clarify | ✅ 100% | 0 | DM 路径完全可用 |
| 部署 | ✅ 90% | 小 | 现有后端服务多开一个 webhook endpoint 即可，不需要新机器 |

**整体难度评估：中等偏高**（代码改造）。**实际难度：中**（部署模型友好，但要求企业资质）。

合规风险**低**——这是腾讯官方推荐的合规路径。

### 业务可行性评估

- 必须有**企业微信注册资质**（公司主体 + 营业执照），不能用个人身份。
- 适合"客服群 / 销售对接群 / 售后群"等需要企业身份背书的场景。
- **不适合**"接入老板已有的家人群、技术研讨群"这种纯私域社群。
- 客户群人数上限 500，比个人微信群（200）更宽松。

### 落地步骤建议（粗略）

1. 新增渠道类型 `netaclaw_agent_channel.type = 'wecom'`。
2. 实现 `service/wecom.ts`：封装企微 access_token 管理 + 主动 API（消息发送、群列表获取） + 被动回调入口。
3. 新增 controller `controller/admin/wecom_callback.ts` 处理企微 webhook 推送，做签名校验后转化为统一的 `WeixinInboundMessageLike` shape，喂给 `routeInboundMessage`。
4. 频道编辑页加 type 选项 `企业微信（客户群）`，配置项变为 `corp_id` / `corp_secret` / `agent_id` / 回调 URL。
5. 群聊管理抽屉改为"主动拉取"模式，加"刷新群列表"按钮。

---

## 决策对比一句话总结

| 需求 | 推荐方案 |
|---|---|
| 只要私聊(一对一 AI 助手) | **保持 iLink ClawBot**(当前实现已可用) |
| 加入用户已有的个人微信群 | **方案 5 · WCDB DB 读+SendInput**(2026-05-12 新增,已验证可行) |
| 客户运营 / 企业 SCRM 场景 | **企业微信 WeCom**(合规、稳定、有企业资质前提) |
| 多场景兼顾 | 加渠道类型字段,多种 type 并存(架构已为此预留) |

---

# 方案 5 · WCDB DB 读 + Win32 SendInput(2026-05-12 追加)

> **状态**: ✅ 技术可行性已验证(见 `2026-05-11-weixin-4x-db-decrypt-progress.md`)。
> **架构 C 修订**(2026-05-12 架构师交叉评审):**不再使用独立 .NET bridge 进程**,改为 backend 内集成 + PowerShell 小脚本处理 Win32 调用。
> **前置**: 用户本机装 Weixin 4.1.x 并已登录;backend 进程以同用户身份运行(不需要管理员)。
> **合规定位**: 读用户本机 SQLite 文件,不触碰 Weixin 服务器,不做协议模拟、不做 DLL 注入。等同于用户自行备份/查看本机聊天记录。封号风险接近 0;唯一的合规议题是在产品侧给用户明示授权。

## 5.0 · 架构演进(决策记录)

| 版本 | 架构 | 状态 | 理由 |
|---|---|---|---|
| v1 (2026-05-09) | 独立 .NET UIA bridge | ❌ 死 | Weixin 4.x Qt 自绘,UIA 树空 |
| v2 (2026-05-12 早) | 独立 .NET bridge + WCDB | ❌ superseded | 33 Task 大头是 Node PoC 翻 C#;没有进程隔离收益 |
| v3 (2026-05-12 晚) | **backend 集成 + PS 脚本** | ✅ 选定 | 复用 better-sqlite3 已有依赖;PoC 直接搬;调试一体 |

**决定性证据**:
- backend 已依赖 `better-sqlite3@^12.8.0` 并被 `pkg` 打包成 `backend.exe` 跑在 Windows 上
- WCDB 解密 PoC `poc-7f-reserve80.mjs` 用纯 Node `crypto` 完成,0.2 秒解 41MB DB
- Win32 调用(OpenProcess / SendInput)用 PowerShell 一次性脚本即可,实测无需管理员
- Tray 是 .NET 是因为 WinForms NotifyIcon 必需;**bridge 没有非 .NET 不可的理由**

## 5.1 · 为什么选方案 5 而不是之前的四条路

| 路径 | 作废/保留 | 原因 |
|---|---|---|
| 方案 1 · iLink ClawBot | **保留用于 DM** | ClawBot 是独立账号,永远收不到群消息 |
| 方案 2 · 企业微信 WeCom | 保留作为 v2 备选 | 只能入"新建客户群",**不能入用户已有个人群** |
| 方案 3 · WeChatFerry PC Hook | ❌ 放弃 | DLL 注入,封号风险高;且作者 2024 停更,对 Weixin 4.x 无官方支持 |
| 方案 4 · UIA(2026-05-09 spec) | ❌ 作废 | Weixin 4.x 用 Qt 5.15 自绘,UIA 树只有 3 个空壳节点 |
| **方案 5 · DB 读 + SendInput** | ✅ **选定** | 无注入无协议模拟;本地文件读;HMAC 验证能捕捉任何非正常页;已实测可解密并读到最新群消息 |

## 5.2 · 总体架构(架构 C · 2026-05-12 修订)

```
Windows 用户桌面
├─ Weixin.exe (4.1.x, 已登录用户真实个人微信号)
│    └─ 写 message_0.db / session.db / contact.db (WCDB 加密)
│    └─ 写 message_0.db-wal (WAL, 实时增量)
│    └─ 主窗口 (Qt 自绘, 仅 Ctrl+F 搜索 + 剪贴板 Ctrl+V 可控)
│
├─ backend.exe (Neta backend, Node 22)
│    └─ modules/netaclaw/runtime/weixin_db/
│        ├─ wcdb_codec.ts          WCDB 解密 (纯 crypto, 直接搬 PoC)
│        ├─ db_paths.ts            xwechat_files 目录结构
│        ├─ key_extractor.ts       spawn ps1 → JSON 输出 → 缓存
│        ├─ message_repo.ts        better-sqlite3 readonly 查询
│        ├─ wal_watcher.ts         setInterval 轮询 .db-wal mtime
│        ├─ incremental_reader.ts  解密 + 查 + 解 zstd
│        └─ message_sender.ts      spawn ps1 → 切群 + 发文本
│    └─ modules/netaclaw/service/weixin_db.ts   ← 主服务,装配上述子模块
│    └─ modules/netaclaw/service/agent_channel.ts
│         routeInboundMessage 按 channel.type 分流
│           ├─ type='weixin'    → iLink 路径 (DM)
│           └─ type='weixin-db' → ★直接调 weixinDbService.ingestRow(...)
│              (无 HTTP IPC, 内部函数调用)
│    └─ tools/win32/             PowerShell 脚本 (装包时拷到 installDir/tools/)
│        ├─ extract-weixin-key.ps1   一次性: dump key map JSON
│        └─ send-weixin-text.ps1     每次回复: Ctrl+F 切群 + Ctrl+V 发
│
└─ Neta.Tray.exe (.NET, 仅 NotifyIcon, 无变化)
       拉起 backend.exe;不再拉 bridge.exe (已删除)
```

**关键差别 vs v2 .NET bridge**:
- ❌ 删除 `Neta.WeChatBridge` / `Neta.WeChatBridge.Tests` 整个 .NET 项目
- ❌ 删除 `/open/netaclaw/channel/weixin-db/handshake|inbound` HTTP 入口(无 bridge 进程要推)
- ❌ 删除 `service/weixin_db.ts` 中的 axios 客户端(无 HTTP 出站)
- ✅ `weixin_db.ts` 改为完整服务: 启动时抽 key + 持有 wal watcher;入站直接调 `agent_channel.routeInboundMessage`
- ✅ 安装时只多 2 个 .ps1 脚本(无编译产物);bridge 文件夹里没有 .exe 要打入

## 5.3 · 最关键的技术细节(不能再猜)

已通过 `poc-7f-reserve80.mjs` + `poc-10-decrypt-and-read.mjs` 完整验证:

```
WCDB cipher_compatibility = 4 (SQLCipher 4 标准)
  page_size     = 4096
  kdf_algorithm = PBKDF2-HMAC-SHA512
  hmac_algorithm = HMAC-SHA512
  iv_sz         = 16
  hmac_sz       = 64   ← 关键!HMAC-SHA512 是 64B(我之前按 SQLCipher 3 的 SHA1=20B 算成 48,全部失败)
  reserve_sz    = iv_sz + hmac_sz = 80

Raw key 模式(WCDB 内存中以 x'<64hex raw><32hex salt>' 形式,99 字符串):
  encKey  = 内存中提取的 32 字节 raw key (不派生)
  salt    = DB 文件 page 1 前 16 字节(每个 DB 不同,是随机的)
  hmacKey = PBKDF2-HMAC-SHA512(encKey, salt XOR 0x3a, 2 rounds, 32B)

每 page(4096B)解密:
  encStart   = 16 if pageNum == 1 else 0          # page 1 前 16B 是 salt, 不加密
  ciphertext = page[encStart : 4016]
  iv         = page[4016 : 4032]                   # 16B
  storedHmac = page[4032 : 4096]                   # 64B HMAC-SHA512

  # HMAC 验证(LE page number)
  computed = HMAC-SHA512(hmacKey, ciphertext || iv || pageNum_LE_u32)
  assert computed[0..64] == storedHmac

  # AES 解密
  plaintext = AES-256-CBC(encKey, iv).decrypt(ciphertext)

输出明文 SQLite:
  out[0..16] = "SQLite format 3\0"                  # 替换 salt 位
  out[16..encEnd] = plaintext
  out[encEnd..4096] = 原 reserve 区(含 IV + HMAC,不影响 SQLite 解析)
```

## 5.4 · 群消息数据模型(WCDB 实际结构)

```
message_0.db (主消息库)
├─ DeleteInfo / DeleteResInfo / HistoryAddMsgInfo / HistorySysMsgInfo
└─ Msg_<sha256_of_room_or_wxid> × N     ← 每个会话一张表(DM + 群都在这)
     ├─ local_id            INTEGER PK
     ├─ server_id           INTEGER     — 服务端消息 id
     ├─ local_type          INTEGER     — 1=文本, 3=图片, 其他高位值看 bit flag(81604378673 等)
     ├─ sort_seq            INTEGER
     ├─ real_sender_id      INTEGER     — 指向 contact.db 的 sender 映射
     ├─ create_time         INTEGER     — Unix 秒
     ├─ status              INTEGER
     ├─ upload_status / download_status INTEGER
     ├─ server_seq          INTEGER
     ├─ source              TEXT        — 来源元数据(可能含 wxid)
     ├─ message_content     TEXT/BLOB   — 明文或 zstd 压缩(前 4B=28 b5 2f fd)
     ├─ compress_content    TEXT
     ├─ packed_info_data    BLOB
     └─ WCDB_CT_message_content/source  — WCDB 自带的加密类型列,可忽略

contact.db + session.db  — 通过 real_sender_id 反查 wxid / 昵称 / 群名

room 判断:message_content 里若出现 "wxid_xxx:\n..." 形式的前缀 → 群消息(发送者 wxid 自带)
          反之是 DM(发送者就是这张表对应的联系人)
```

## 5.5 · Bridge 项目结构(替换老 Neta.WeChatBridge)

**老 bridge 作废**(UIA 实现),**新 bridge 在同目录重建**。目录名复用。

```
packages/windows-tray/Neta.WeChatBridge/
├── Neta.WeChatBridge.csproj      (net8.0-windows, AssemblyName=bridge)
├── Program.cs                    启动 + 版本白名单 + handshake + 启 watcher
├── Config/
│   ├── WeixinProfile.cs          Weixin 4.x 版本 profile
│   └── WeixinProfiles.yaml       版本白名单 (4.1.x, 4.2.x ...)
├── Crypto/
│   ├── WeixinProcessLocator.cs   定位 Weixin.exe(不是 WeChat.exe)
│   ├── MemoryKeyExtractor.cs     OpenProcess + VirtualQueryEx + 找 x'...' 96-char literal + 按 salt 反向匹配各 DB
│   ├── WcdbCodec.cs              解密一个 page(HMAC 验证 + AES 解密) - 见 5.3
│   ├── ZstdDecompressor.cs       解 message_content 的 zstd
│   └── DbDecryptor.cs            全量解密 DB 到临时文件
├── Db/
│   ├── DbPaths.cs                定位 ~/Documents/xwechat_files/<seed>/db_storage/
│   ├── MessageRepo.cs            node:sqlite 风格 API,解密后用 Microsoft.Data.Sqlite 读
│   ├── ContactRepo.cs            查 real_sender_id → wxid 映射
│   └── RoomRepo.cs               查群名/成员
├── Watcher/
│   ├── WalWatcher.cs             轮询 .db-wal mtime(500ms)
│   ├── IncrementalReader.cs      只查 create_time > lastKnownSeq 的行
│   └── MessageDispatcher.cs      去重 + 推 backend
├── Input/
│   ├── WeixinWindowLocator.cs    FindWindowEx 找指定群/联系人的聊天子窗口
│   └── SendInputSender.cs        Win32 SendInput UTF-16 字符模拟输入 + Enter
├── Http/
│   ├── BridgeHttpServer.cs       Kestrel 托管
│   ├── Endpoints/                /health /send /enable-room /disable-room /rooms /diag
│   └── TraySecretAuth.cs
├── Backend/
│   └── BackendClient.cs          POST /handshake /inbound
└── Runtime/
    ├── BridgeRuntimeInfo.cs
    └── GracefulShutdown.cs
```

**作废的老 UIA 代码**: `Uia/WeChatWindow.cs`、`SessionListWatcher.cs`、`ChatBoxReader.cs`、`UiaRoomMessageReader.cs`、`MessageSender.cs`(UIA 版)、`AttachmentExtractor.cs`。**全部删除**,不保留占位。

## 5.6 · 入站事件流(架构 C 修订版)

```
backend.exe 启动时 weixin-db channel 初始化:
 1. WeixinProcessLocator: 找 Weixin.exe 4.x 主进程 + 版本号
 2. 定位 seedDir = ~/Documents/xwechat_files/<wxid>_<suffix>/
 3. 抽 key: spawn `extract-weixin-key.ps1` (一次性, 输出 JSON):
      - PowerShell 用 OpenProcess(VM_READ | QUERY_INFO, pid)  ← 同用户, 无需管理员
      - 枚举 private RW 区域 + ReadProcessMemory
      - 正则找 x'<96hex>' literal
      - 根据各 DB 的前 16B salt 一一匹配 → 输出 {dbFile: rawKey32B} JSON
      - backend 读 stdout, 缓存到内存 (channel 单例 service)
 4. ★ 从 DB 读取 channel 的"用户已添加群名"白名单 (netaclaw_agent_channel_group WHERE channelId=X AND status=1)
 5. 初次全量解密 message_0.db → 临时文件 (dataDir/<cid>/decrypted/message_0.db)
 6. ★ 枚举 Msg_<sha> 表, 用 contact.db / session.db 反查每张表对应的群名
      → 构造 { tableName → roomName } 映射
      → ★ 只保留 roomName 在白名单内的表; 其他表整体跳过 (隐私 + 性能)
 7. 记录每张"白名单表"的 MAX(create_time) 为 lastKnownTs
 8. 启 WalWatcher (setInterval 500ms 防抖, 轮询 message_0.db-wal mtime):
     mtime 变 → 把 DB 主文件 + WAL + -shm 拷到 work 目录 → 全量解密
              → 对每个"白名单表" SELECT * WHERE create_time > lastKnownTs ORDER BY create_time ASC
              → 每条新行: 解 zstd → 构造 WeixinDbInboundPayload
              → ★ 直接调用 agentChannelService.routeInboundMessage(channel, state, pseudo)
                 (无 HTTP IPC, 同进程内函数调用)
              → 更新 lastKnownTs
```

**白名单语义**:
- 用户在前端"群聊管理"里**手动输入群名**才会建条 `netaclaw_agent_channel_group` 记录,默认 status=1 启用
- DB 解密阶段 ★ 第 6 步就过滤掉非白名单的表 → **bot 永远不读未授权群的消息**(无论加密 DB 里是什么)
- 这是隐私保护 + 性能优化双重收益:用户家庭群、好友群不会被 agent "顺便看到"

**运行时目录约定**:
- 解密临时文件路径: `<pDataPath()>/weixin-db-work/cid-<channelId>/{src,decrypted}/<dbname>`
- backend 进程退出时不清理(下次启动覆盖即可,且方便排错)
- DEV 时 `pDataPath()` 解析为 `packages/backend/dist/`,与现有 uploads/workspace 同一根

**关键优化**:
- 全量解密 10644 pages 仅 0.2s (Node),性能不是问题
- 解密后的临时文件只在 work 目录存在,backend 停止时清理
- 白名单过滤在 SQL 层 (`SELECT FROM "Msg_<sha>"`),只读用户授权的表

## 5.7 · 回复路径(TODO · 占位)

> **状态**: 占位,后续单独 spec 描述。
>
> **目标**: 当 agent 决定回复某个白名单群时,把回复文本投递到 Weixin UI 让微信真实发出去。
>
> **已知约束**(用于后续设计):
> - Weixin 4.x 主窗口是 Qt 自绘,EnumChildWindows 只能看到 2 个 top-level 子窗口(整个聊天 UI 在 `MMUIRenderSubWindowHW` 一块画布里,Qt widget 对 Win32 完全不可见)
> - UIA 树空,不能通过控件自动化切群/定位输入框
> - 候选路径(待评估,**本 spec 不下定论**):
>   - 路径 A: 剪贴板 + Ctrl+V + Enter,假设用户当前已聚焦目标群
>   - 路径 B: Ctrl+F 搜索群名 → Enter 切群 → Ctrl+V + Enter
>   - 路径 C: WeChatFerry 4.x 注入 hook(灰色,封号风险)
> - 任一路径都要解决"用户在用微信时怎么避免打断"问题
>
> **接口设计(占位)**: `weixin_db_service.ts` 暴露:
> ```ts
> /** 向白名单群发送一条文本回复。v1 占位,先抛 NotImplementedError。 */
> async replyToGroup(channelId: number, roomName: string, text: string): Promise<void>;
> ```
> 在 `routeInboundMessage` 决策完 finalContent 后调,失败时 agent 视为发送失败(不重试)。
>
> **未决问题**(下一次 spec 解决):
> 1. 如何在用户操作微信时安全发送 / 何时拒发
> 2. 切群后如何验证焦点在目标群的输入框(避免发错群)
> 3. 同名群处理策略
> 4. 长文本 / 多行 / emoji 的 SendInput 编码细节


## 5.8 · 数据模型变更(架构 C · 群白名单语义)

**保留不变**:
- `netaclaw_agent_channel_group` 表(Phase 2 已上线,schema 主体不动)
- `agent_channel.config.group.botAlias`
- 所有 sessionId / dispatch key / clarify key 规则

**语义变更**(2026-05-12 关键):

| 字段 | 原 ClawBot/UIA 语义 | weixin-db 新语义 |
|---|---|---|
| `roomId` | iLink 平台 ID 或 sha1(roomName) | **就是用户输入的群名(string)**,作为白名单 key |
| `roomName` | 显示名 | 同 roomId(冗余,前端可编辑) |
| `status` | `0=disabled (待审批)` / `1=enabled` / `-1=ignored` | 简化为 `0=disabled` / `1=enabled`,**默认 1**(用户手动添加即启用) |
| `firstSeenAt` | bridge 被动发现时间 | 用户添加时间 |
| `lastSeenAt` | bridge 看到该群消息时间 | DB 解密时确认群存在的时间 |
| 创建路径 | bridge 被动发现 → `upsertOnInbound` | **前端用户主动 POST /list/add { channelId, roomName }** |

**作废**:
- `upsertOnInbound`(被动发现写库)→ 删除
- `status=-1 (ignored)` 状态 → 删除(没有"忽略"概念,用户没添加就不监管)
- 前端"待审批横幅" + "新发现 N 个群" → 删除

**新增**:

```sql
ALTER TABLE netaclaw_agent_channel
  -- type 字段新增合法值 'weixin-db'(原 'weixin' 仍用于 iLink DM)
;

-- credential JSON 对 weixin-db 的含义:
-- {
--   "wxid":          "wxid_xxx",       -- 必填(用户从 PC 微信"设置→关于"抄;backend 启动时校验进程匹配)
--   "nickname":      "张三",            -- 启动后自动回填
--   "wechatVersion": "4.1.8.107",      -- 同上
-- }
```

**作废**:
- 2026-05-09 spec 中的 `netaclaw_wechat_archive` SQLite 归档表 → 不再需要(用户白名单内的群消息直接落 session_entry,非白名单的根本不读)

## 5.9 · routeInboundMessage 的最终分流逻辑

```ts
async routeInboundMessage(channel, state, message) {
  // 按 channel.type 分流
  switch (channel.type) {
    case 'weixin':         // iLink ClawBot(DM only)
      if (message.room_id) return;     // 丢弃任何群消息(ClawBot 实际也收不到,双保险)
      return this.handleIlinkInbound(channel, state, message);

    case 'weixin-db':      // ★新增:本地 DB 读
      if (!message.room_id) {
        // DM 走 ClawBot,丢弃 DB 读出的 DM 避免双渠道重复响应(见 2026-05-09 spec 决策)
        this.logger.debug('[weixin-db] drop DM, use ClawBot for DM');
        return;
      }
      return this.handleDbInbound(channel, state, message);

    default:
      return;
  }
}
```

`handleDbInbound` 的代码 **99% 复用** `handleIlinkInbound`:
- pendingClarify 短路 → 同
- decideChatScope → 同
- decideGroupAcceptance → 同(trigger 策略 at_mention/all 仍生效;白名单已经过滤掉非授权群,本层只判 @ 命中等)
- senderQueue 按 group dispatch key 串行 → 同
- agentExecutor.execute({ chatScope: 'group', ... }) → 同
- finalContent → **唯一差别在 sendText**:调 `weixinDbService.replyToGroup(channelId, roomName, text)`(占位,见 5.7)

## 5.9.5 · 前端"用户主动添加群"UX(替换被动发现)

**原 channel-group-panel(被动发现版)作废**,改为简单的"白名单管理"形态:

```
┌─ 群聊白名单 · 老板微信 ──────────────────────[x]─┐
│                                                  │
│ 已添加监管 3 个群           [+ 添加群]             │
│                                                  │
│ ┌──────────────────────────────────────┐         │
│ │ 产品研发群           [启用 ●]  [删除]  │         │
│ │ 添加于 2026-05-12 · 最近消息 12 分钟前 │         │
│ │ 触发策略  (●) @机器人  ( ) 所有消息     │         │
│ │              [保存策略]                 │         │
│ └──────────────────────────────────────┘         │
│                                                  │
│ 💡 群名必须与 PC 微信里完全一致(包括空格、表情)│
│ 💡 未添加的群,bot 不会读取消息内容(隐私保护)   │
└──────────────────────────────────────────────────┘

[+ 添加群] 弹窗:
┌─ 添加群聊 ─┐
│ 群名:    [_________________________]  │
│ 触发策略: (●) @机器人  ( ) 所有消息     │
│              [取消]  [添加]              │
└─────────┘
```

**前端约束**:
- 群名作为白名单 key,**用户必须输入与 Weixin UI 完全一致的群名**(后端校验 trim 但不做 fuzzy)
- 同一 channel 下同名群只能加一次(UNIQUE(channelId, roomName) 校验)
- 删除群 = 立即停止监管(不影响 Weixin 自身,只是 backend 不再读)
- 不再有"待审批"状态;不再有"忽略"按钮

**REST 接口**:

```
POST /admin/netaclaw/channel/group/add        { channelId, roomName, triggerMode } → { id, status: 1 }
POST /admin/netaclaw/channel/group/list        { channelId } → list
POST /admin/netaclaw/channel/group/toggle      { id, status }
POST /admin/netaclaw/channel/group/updatePolicy { id, triggerMode }
POST /admin/netaclaw/channel/group/delete      { ids }
```

**作废接口**: 旧 `/upsertOnInbound`(已被 add 替代)

## 5.10 · 现有代码需要修改的地方(架构 C 修订)

### 后端 modifications

| 文件 | 改动 |
|---|---|
| `packages/backend/src/modules/netaclaw/entity/agent_channel.ts` | type 字段 enum 加 `weixin-db` |
| `packages/backend/src/modules/netaclaw/service/agent_channel.ts` | `routeInboundMessage` 加 `case 'weixin-db'` 分支;`handleDbInbound` 新增(99% 复用 handleIlinkInbound,仅 sendText 改调 weixinDbService.replyToGroup) |
| `packages/backend/src/modules/netaclaw/service/weixin_db.ts` (新增) | **完整服务**(架构 C):启动时抽 key、维持 wal watcher、解密 + 增量读 + 投递 routeInboundMessage、replyToGroup 占位接口 |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/wcdb_codec.ts` (新增) | WCDB 解密(直接搬 PoC `poc-7f-reserve80.mjs` + `poc-10`) |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/db_paths.ts` (新增) | xwechat_files 目录解析 |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/key_extractor.ts` (新增) | spawn ps1 抽 key + 缓存 |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/message_repo.ts` (新增) | better-sqlite3 readonly 查询 + zstd 解压 |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/wal_watcher.ts` (新增) | setInterval 500ms 轮询 wal mtime |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/incremental_reader.ts` (新增) | 解密 → 白名单过滤 → 增量读 → 解 zstd |
| `packages/backend/src/modules/netaclaw/runtime/weixin_db/room_resolver.ts` (新增) | 解析 Msg_<sha> 表名 → 群名 → 白名单匹配 |
| `packages/backend/src/modules/netaclaw/service/agent_channel_group.ts` | 删除 `upsertOnInbound`(被动发现);新增 `addByName(channelId, roomName, triggerMode)` 显式添加 |
| `packages/backend/src/modules/netaclaw/controller/admin/agent_channel_group.ts` | endpoint `/upsertOnInbound` 改 `/add`;入参变 `{ channelId, roomName, triggerMode }` |
| `packages/backend/tools/win32/extract-weixin-key.ps1` (新增) | OpenProcess + 抽 key,JSON stdout 输出 |
| `packages/backend/tools/win32/send-weixin-text.ps1` (新增,占位) | 5.7 实现时再写;v1 先写 stub 抛 NotImplemented |

### 后端 删除(作废)

| 文件 | 理由 |
|---|---|
| `packages/backend/src/modules/netaclaw/service/weixin_uia.ts` | UIA 路径作废 |
| `packages/backend/src/modules/netaclaw/controller/open/weixin_uia.ts` | UIA bridge HTTP 入口作废(架构 C 不需要) |
| `packages/backend/src/modules/netaclaw/runtime/wechat_uia_routing.ts` | 同上 |
| `packages/backend/src/modules/netaclaw/service/wechat_archive.ts` | 不再需要 SQLite 归档 |
| `packages/backend/src/modules/netaclaw/runtime/wechat_archive_schema.ts` | 同上 |
| `packages/backend/src/modules/netaclaw/controller/admin/wechat_archive.ts` | 同上 |
| `packages/backend/src/config/config.default.ts` 的 `staticFile.wechatUploads` | 不再需要图片挂载 |
| `packages/backend/src/comm/path.ts` 的 `pWechatUploadsPath` | 同上 |

### 前端 modifications

| 文件 | 改动 |
|---|---|
| `packages/frontend/src/modules/agent/types/index.d.ts` | `AgentChannelInfo.type` 改为 `'weixin' \| 'weixin-db'`;`AgentGroupItem.status` 仅 `0/1`,删 `-1` |
| `packages/frontend/src/modules/agent/views/channel-management.vue` | drawer type 下拉:"微信本地代理(群聊 · 需 Windows + PC 微信)";所有 "UIA" 文案改 "本地代理" |
| `packages/frontend/src/modules/agent/components/channel-group-panel.vue` | **重写 UX**:删除"待审批横幅"、"忽略"按钮、被动发现提示;改为"+ 添加群"按钮 + 群卡片(启用 toggle / 触发策略 / 删除) |
| `packages/frontend/src/modules/agent/composables/useUiaChannelValidation.ts` → `useDbChannelValidation.ts` | 改名;wxid 唯一性校验逻辑保留 |

### 前端 删除

| 文件 | 理由 |
|---|---|
| `packages/frontend/src/modules/agent/components/wechat-archive-panel.vue` | 归档面板作废 |

### .NET Bridge — **整个项目删除**

| 文件 | 理由 |
|---|---|
| `packages/windows-tray/Neta.WeChatBridge/` 整个项目 | 架构 C 不需要独立 bridge;backend 直接处理 |
| `packages/windows-tray/Neta.WeChatBridge.Tests/` | 同上 |
| `packages/windows-tray/Neta.Tray/BridgeProcessManager.cs` | 不再拉 bridge.exe |
| `packages/windows-tray/Neta.Tray/BridgeHealthPoller.cs` | 同上 |
| `packages/windows-tray/Neta.Tray/TrayApplicationContext.cs` 中的 bridge 拉起逻辑 | 删除相关代码段;Tray 只负责 backend.exe |

### 安装包脚本

| 文件 | 改动 |
|---|---|
| `packages/backend/scripts/build-windows-installer.js` | 删除 `dotnet publish bridge` 步骤;新增"拷贝 backend/tools/win32/*.ps1 到 installDir/tools/" 步骤 |
| `packages/backend/installer/setup.iss` | 删除 bridge.exe 文件项;新增 ps1 文件项 |

## 5.11 · 实施优先级(架构 C · 简化版)

| Phase | 内容 | 估时 | 前置 |
|---|---|---|---|
| **P1** | 清理 UIA + bridge .NET 项目 + archive 后端代码 | 0.5d | 本 PR |
| **P2** | Backend runtime/weixin_db/ 各子模块(wcdb_codec / db_paths / message_repo / room_resolver) | 2d | P1 |
| **P3** | Backend `weixin_db.ts` service 装配 + 启动钩子 + key extractor (含 ps1) | 1.5d | P2 |
| **P4** | Backend `agent_channel.ts` 加 weixin-db 分支 + `handleDbInbound` | 0.5d | P3 |
| **P5** | Backend group service `addByName` + controller `/add` 端点 | 0.5d | P1 |
| **P6** | 前端 channel-management 改文案 + `channel-group-panel` 重写 UX(添加群表单) | 1d | P5 |
| **P7** | 安装包脚本去 .NET bridge + 加 ps1 拷贝 | 0.5d | P3 |
| **P8** | Tray 删除 bridge 拉起逻辑 | 0.25d | P7 |
| **P9** | 端到端手工验证 | 0.5d | 全部 |
| **P10**(占位) | 5.7 自动回复实现 | TBD | P9 |

**合计 ~7 工作日(不含 P10)**。对比架构 A 的 10 天 + .NET 维护负担,显著简化。

## 5.12 · 风险与兜底

| 风险 | 可能性 | 兜底 |
|---|---|---|
| Weixin 升级后 raw key 在内存中的位置/格式变 | 中 | KeyExtractor 在 ps1 里做版本兜底,失败提示用户重启 backend |
| Weixin 改 cipher_compatibility 或换 KDF | 低(WCDB 标准) | 真改了升级 wcdb_codec.ts 即可,无需重打包 |
| DB 解密频率过高被 antivirus 检测 | 低 | 解密在内存做,只读 DB 文件不写;500ms-1s 防抖 |
| PC 微信未登录 / 未启动 | 必然 | weixinDbService 启动时探测,未就绪 channel.loginStatus='disconnected',前端卡片显示离线;**60s 健康探针自动重连** |
| Weixin 进程重启(PID 变) | 中 | 健康探针检测到 PID 变化或解密失败 → `unbindChannel` + `bindChannel` 重跑抽 key 流程 |
| 同时登录多个微信号 | 不存在 | PC 微信本身限制一机一号 |
| 用户输入群名与 Weixin 不一致 | 中 | 前端校验:群名长度 1-128;后端启动后 RoomResolver 扫描所有 session,若白名单某项匹配不上 → 前端卡片提示"未找到群: <name>" |
| **backend 在非 Windows 平台运行**(Linux/Mac dev 机) | 必然 | `weixinDbService.bindChannel` 检测 `process.platform !== 'win32'` 直接 return + 标 `loginStatus='unsupported_platform'`;不 spawn powershell,不让 backend crash |
| PowerShell 脚本路径解析错误 | 中 | `key_extractor.ts` 按 `NETA_WEIXIN_KEY_SCRIPT` env → `<installDir>/tools/win32/*.ps1` → `<cwd>/tools/win32/*.ps1` → `<module>/../../tools/win32/*.ps1` 顺序 fallback |
| **5.7 回复部分(未实现)** | 必然 | v1 暴露 `replyToGroup` 接口但抛 `NotImplementedError`;`handleDbInbound` 捕获后写入 sessionEntry "[占位:回复未实现]";不阻塞读链路 |


## 5.13 · 与 2026-05-08 原 Phase 成果的关系

| 原 spec 产出 | 方案 5 状态 |
|---|---|
| Phase 1 · `runtime/chat_scope.ts` + `runtime/errors.ts` | ✅ 完全保留 |
| Phase 2 · `entity/agent_channel_group.ts` + service + controller | ✅ 完全保留 |
| Phase 3 · `agent_executor.chatScope` + GroupInteractionDeclineError short-circuit | ✅ 完全保留 |
| Phase 4 · `routeInboundMessage` 分流 + senderQueue 群级共享 + clarify 短路 | ✅ 保留,只是按 channel.type 加一个 case |
| Phase 5 · 前端 channel-management / channel-group-panel | ✅ 保留,仅改文案 + group panel 重构为"用户主动添加" |
| Phase 6 · "UIA 采集" 相关代码(2026-05-09 的 A/B/C/D) | ❌ 作废,全删 |
| Phase 7 · iLink ClawBot DM 路径 | ✅ 保留(作为 DM 渠道) |

**结论:原 2026-05-08 的 20 个 task / 117 单测,95% 资产有效**。只替换传输层。

---

## 5.14 · 开发与部署形态(架构 C 关键澄清)

### DEV 模式工作流

backend 在 DEV 是普通 Node 进程,**无需打包成 backend.exe** 即可完整开发与调试 weixin-db 渠道:

```
开发者机器 (Windows + 已登录 Weixin 4.x):
  ├─ packages/backend/  → pnpm dev (Midway tsx HMR)
  │   └─ 改 wcdb_codec.ts / message_repo.ts / weixin_db.ts → 热更新, 无需重启
  ├─ packages/backend/tools/win32/extract-weixin-key.ps1
  │   └─ 改 ps1 → 下次 spawn 直接读最新版, 无需重启 backend
  ├─ packages/frontend/  → pnpm dev (Vite HMR)
  └─ Weixin.exe         → 用户保持登录
```

**只在以下三个时机需要打包成 exe**:

1. 端到端验证 installer 把 ps1 拷到正确路径
2. 给非开发者(测试用户)分发安装包
3. CI 烟囱测试

**绝大多数日常开发改动(代码、UI、PoC、测试)都用 `pnpm dev` 完成**。

### PowerShell 脚本路径解析(robust 兜底)

PS 脚本是纯文本资源,需在 DEV / pkg 打包 / installer 安装三种环境定位到。`key_extractor.ts` 按以下顺序 fallback:

```ts
function resolveExtractorScript(): string {
  // 1. 环境变量(覆盖一切)
  if (process.env.NETA_WEIXIN_KEY_SCRIPT) return process.env.NETA_WEIXIN_KEY_SCRIPT;

  // 2. 模块自身相对路径(DEV / pkg 都行)
  //    runtime/weixin_db/key_extractor.ts → ../../../../tools/win32/extract-weixin-key.ps1
  const moduleRel = path.resolve(__dirname, '..', '..', '..', '..', 'tools', 'win32', 'extract-weixin-key.ps1');
  if (fs.existsSync(moduleRel)) return moduleRel;

  // 3. installer 部署路径: <installDir>/tools/win32/*.ps1
  const installDir = process.env.NETA_INSTALL_DIR || path.dirname(process.execPath);
  const installRel = path.join(installDir, 'tools', 'win32', 'extract-weixin-key.ps1');
  if (fs.existsSync(installRel)) return installRel;

  // 4. 当前工作目录 fallback
  const cwdRel = path.join(process.cwd(), 'tools', 'win32', 'extract-weixin-key.ps1');
  if (fs.existsSync(cwdRel)) return cwdRel;

  throw new Error('extract-weixin-key.ps1 not found in any candidate path');
}
```

### 跨平台兜底

backend 跨平台编译(Linux/Mac/Windows),但 weixin-db **只在 Windows 有意义**:

```ts
// service/weixin_db.ts
async bindChannel(channel, onInbound) {
  if (process.platform !== 'win32') {
    this.logger.warn('[weixin-db] non-Windows platform (%s), channel %s skipped', process.platform, channel.id);
    // 标记 channel.loginStatus = 'unsupported_platform' (前端卡片显示)
    await this.channelRepo.update({ id: channel.id }, { loginStatus: 'unsupported_platform' });
    return;
  }
  // ...正常流程
}
```

效果:
- **Linux/Mac dev 机能完整跑 backend / 前端 / 单测**(只是 weixin-db channel 不工作,其他功能正常)
- 单测里所有 weixin_db service 测试用 jest mock,不依赖真实 powershell.exe → 跨平台跑通

### 健康探针 / 自动重连

```ts
// service/weixin_db.ts 新增
@Init()
async onInit() {
  setInterval(() => this.healthCheck().catch(() => void 0), 60_000);
}

private async healthCheck() {
  for (const [cid, runtime] of this.runtimes) {
    try {
      // 探测 Weixin 进程仍在 + DB 文件可读
      const ok = await this.probeAlive(runtime);
      if (!ok) {
        this.logger.warn('[weixin-db] cid=%s lost connection, rebinding', cid);
        this.unbindChannel(cid);
        const channel = await this.channelRepo.findOne({ where: { id: cid } });
        if (channel) await this.bindChannel(channel, this.cachedOnInbound);
      }
    } catch (err: any) {
      this.logger.error('[weixin-db] healthCheck cid=%s: %s', cid, err.message);
    }
  }
}
```

### 实施里程碑(明确优先级)

| 里程碑 | 范围 | 价值 |
|---|---|---|
| **M1 · 读 + 展现** | Phase C-0 / C-1 / C-2 / C-3 / C-4 + Phase C-5 的 addByName | 用户能添加群名,backend 实时读到群消息,落 sessionEntry,前端 chat 页能看到对话流 |
| **M2 · 完整 UX** | Phase C-6 / C-7 / C-8 | 前端"+ 添加群"完整体验,安装包能装,E2E 跑通 |
| **M3 · 自动回复(留 v2)** | Phase C-9(独立 spec) | replyToGroup 真实实现 |

**M1 是最小可演示版本**:加群 → 看到群消息流到 chat 页面。回复占位即可。


---