微信智能桥接 LouisHaoL/dsh-wechat-plus

dsh-wechat-plus · DSH 微信桥接插件（项目/会话管理 + 智能路由版）

⚠️ 项目状态：已封存（2026-08-21）。本插件功能未完善，存在已知缺陷（会话恢复竞态、启动多实例锁竞争等），仅作为实现思路与方案参考保留，不建议直接在生产环境安装使用。欢迎按本 README 记录的方案自行取用与续作。

把手机微信接到 DeepSeek Harness (DSH)：你在微信里给机器人发消息，DSH 的 AI 助手处理后把回复流式发回微信。本插件是 dsh-wechat-bridge 的升级重命名版，在原有消息桥接之上新增多项目/会话管理与 embedding 智能路由：在微信里即可切换项目、翻找历史会话、并让「日常闲聊」与「项目工作」自动分流。功能定位与 CC-Connect 的「微信消息中转」类似，但本插件为完全独立的原创实现，与 CC-Connect 无任何代码、配置或商标关联（详见下方合规说明）。

手机微信 ──▶ 腾讯 iLink Bot API（ilinkai.weixin.qq.com，官方开放协议） │ 长轮询收消息 / sendmessage 回传 ▼ dsh-wechat-plus（本插件，DSH 内运行） │ 命令拦截 → 智能路由 → ctx.agents.create/followup/resume ▼ DeepSeek Harness AI Agent（DSH 官方 Agent 接口）

一、合规与「不侵权」说明

1. 全部代码原创：本仓库代码为独立编写，未复制、未翻译、未借鉴 CC-Connect 的任何源码或配置文件；插件名、配置结构、命令集均为原创。
2. 微信通道合法：走腾讯官方开放的「微信 ClawBot 插件功能」——iLink Bot 协议（域名 ilinkai.weixin.qq.com），受腾讯《微信 ClawBot 功能使用条款》约束，不是逆向 iPad 协议，也不是 PC 客户端 Hook。
3. 底层依赖宽松许可：协议客户端使用独立开源项目 wechat-ilink-client（MIT 许可，零运行时依赖），其实现参考腾讯官方开源包 @tencent-weixin/openclaw-weixin。MIT 归属声明见 THIRD_PARTY_NOTICES.md。
4. 商标与命名：不使用 "cc-connect" 名称、图标、文档文本或品牌元素。
5. 参考对象：CC-Connect 本身为 MIT 许可项目；即使按其许可证也允许合法复用（保留声明），本项目选择了更保守的路线——完全不使用其代码，只实现「消息中转」这一通用功能概念（功能概念本身不受著作权保护）。

二、iLink 协议

腾讯为「微信 ClawBot 插件功能」开放的官方 Bot 协议，服务地址 https://ilinkai.weixin.qq.com。核心交互：长轮询（long-polling）收取消息、sendmessage 回传文本、getUploadUrl + CDN 回传图片/文件、「正在输入」状态上报。凭证为 Token + 账号 ID（扫码登录后自动获取并持久化）。本插件通过 MIT 许可的独立客户端 wechat-ilink-client 使用该协议。

三、功能

- ✅ 手机微信私聊 → DSH AI 对话，回复流式分段发回（打字机效果，按句读边界切割不切词）
- ✅ 多项目/会话管理：/projects /project /sessions /home /new /stay /status /history /models /model 全套命令，微信端直接切换项目与历史会话、切换模型（详见下节）
- ✅ embedding 智能路由：日常闲聊自动分流，项目相关消息自动切入对应项目（详见「智能路由」）
- ✅ 内置扫码登录：自动弹出二维码页面，微信扫码即完成绑定（也可直接配置已有 token）
- ✅ 每个联系人独立绑定状态（当前项目 + 会话指针），持久化、重启恢复
- ✅ 语音消息（转写文字后交给 AI）、文字消息
- ✅ 图片接收：微信发图自动下载到工作目录，AI 用工具（OCR/看图）分析后回复
- ✅ 文件接收与回传：入站文件自动下载供 AI 读取；AI 把生成的文件保存到 wechat-outbox/<联系人>/ 自动发回微信；更有专属工具 wechat_send_file 与 wechat_send_local_file
- ✅ 微信排版：回复里的 Markdown（加粗/表格/引用/列表/链接）自动转成微信可读的纯文本；非流式长回复自动加 (1/n) 分段编号
- ✅ 群聊（代码就绪，待平台开放）：⚠️ 实测确认当前微信 ClawBot 机器人无法被拉入群聊（平台未开放），此功能暂不可用；平台开放后开箱即用
- ✅ 网页抓取（可选）：配套极简 MCP fetch 服务器（mcp/fetch-server/），仅用户明确要求时抓取公开网页
- ✅ 定时任务：cron 定时给指定联系人派活，配置热加载、无需重启
- ✅ 「正在输入…」提示、用量尾注（每轮回复附模型与 token 统计）
- ✅ 白名单分级：allowFrom 控制谁能聊；admins 控制谁能执行控制命令；支持 override.json 热调整
- ✅ 纯链接消息拦截（安全铁律）、断线/凭证过期自动重试、长轮询假死看门狗、空闲自动回收、单实例互斥
- ⏳ 暂不支持：入站视频消息（忽略并记日志）

四、会话与项目管理

每个联系人的消息都有明确的归属指针：当前项目（日常 或某个具体项目）+ 该项目下的当前会话。指针持久化在 ~/.dsh/wechat-plus/bindings.json，重启自动恢复。

命令表

| 命令 | 行为 |
| /projects | 列出所有项目（日常 置顶），编号菜单 |
| /project <n> | 切到第 n 个项目，自动落在该项目最近活跃的会话（无会话则下一条消息自动新建） |
| /sessions [页码或关键词] | 列出当前项目下的会话（标题+时间，每页 ≤8 条，n=下一页；带关键词按标题过滤） |
| 回复数字 | 选中 /sessions 菜单中的会话，回显 已切换：《标题》，后续消息恢复该会话 |
| /home | 回到日常模式 |
| /new | 当前项目另开新会话（旧会话保留，可从 /sessions 找回） |
| /stay [小时] | 钉住当前上下文（默认 2 小时），期间智能路由静默；无参数 = 查询剩余时间 |
| /status | 显示当前项目 / 会话 / stay 状态 / 当前模型 |
| /history [n] | 把当前会话最近 n 轮对话（默认 5）发到微信（自动脱敏，超长按 20 段截断） |
| /models | 列出可用模型（按 provider 分组，当前模型 ★ 标记），编号菜单 |
| /model <n或名称> | 切换当前联系人的模型：数字选菜单 / 模型 id（支持唯一子串匹配，多匹配会列出候选）/ 无参数显示当前模型。按联系人持久化（重启保留）；空闲时立即生效且保留会话上下文，任务运行中则本轮完成后生效 |
| /help | 帮助文本 |
| /stop | 中断当前正在处理的任务 |

所有斜杠命令在消息投递给 AI 之前拦截处理，零 LLM 调用、即时响应。命令需完全匹配（trim 后以 / 开头且首 token 在命令表中）。

日常模式

- 新联系人默认落在伪项目 日常（__daily__，工作目录 ~/.dsh/daily/），拥有一个长生命周期会话：上下文连续，agent 上下文窗口天然只装最近若干轮，更早轮次由会话持久化滚出窗口。
- 日常会话中的 agent 照常可用 OpenViking 记忆工具（viking_remember / viking_search），即自带长期记忆。

阶层约束（铁律）

1. /sessions 只列当前项目下的会话（按会话工作目录过滤），不会跨项目串列。
2. /project <n> 切换后自动落在该项目的最近活跃会话；每个项目各自记住自己的会话指针（切走再切回，还在原会话）。
3. 会话恢复时强制使用该会话自己的工作目录，不做跨项目 resume。

编号菜单机制

- 单活跃菜单：同一联系人同一时刻只有一个活跃菜单，新菜单出现即作废旧菜单。
- 短 TTL：菜单 5 分钟未回复自动失效；失效后回复数字会提示 菜单已失效，请重新 /sessions。

五、智能路由

路由发生在消息投递给 AI 之前（斜杠命令拦截之后）。判定为跑题的消息直接改投目标会话——被打断的会话从未见过该消息，不存在"撤回"问题。

决策表

消息到达 ├─ 斜杠命令 → 命令层（最高优先级） ├─ /stay 未过期 → 原样投递当前指针 ├─ 当前在【项目A】 │ ├─ 与 A 高度相似 → 投 A │ ├─ 与 B 高度相似 且 出现工作意图 → 投 A + 一行切换建议（"这像【B】的活？1.切过去 2.就在这聊"） │ └─ 都低（纯闲聊）→ 投 A（项目里允许闲聊，不切出） └─ 当前在【日常】 ├─ top1 且 top1−top2 > margin → 自动切项目 + 回复标头 + 可撤销提示 ├─ top1/top2 歧义（差 ≤ margin）→ 三选一菜单 "1.【A】 2.【B】 3.留日常" └─ 都低于切入阈值 → 留日常

自动切入项目后，该轮回复带标头 [已进入【项目A】·《会话标题》]，尾部一行 ↩ /home 回日常。

routeMode 三档

| 档位 | 行为 |
| auto（默认） | 高置信度时自动切入项目（带标头、可撤销） |
| ask | 切入前先发三选一菜单确认 |
| off | 纯手动，不做任何自动切换 |

相似度服务（可插拔）

- insert:
- id: wechat-plus
name: 'dsh-wechat-plus'
config:
routerEnabled: true # 总开关（关闭后消息一律按当前指针直通） routerProvider: openviking # 'openviking' | 'deepseek' | 'off' routerOpenvikingBaseUrl: 'http://127.0.0.1:1933' routeMode: auto # 'auto' | 'ask' | 'off'

- openviking（推荐）：用本机 OpenViking 语义搜索做相似度，免费、无需 API key（dev 模式免鉴权）。
- deepseek：OpenAI 兼容 /embeddings 接口，需配置 routerDeepseekApiKey（可选 routerDeepseekBaseUrl、routerDeepseekModel），本地余弦相似度。
- off：不路由。

降级安全网：provider 不可达或调用失败时，路由一律降级为直通（按当前指针投递，限频记日志），永不阻塞消息。

阈值与校准（为什么默认 enter=0.75）

实测本机 OpenViking（0.4.15）相似度分布整体偏高：无关消息也能拿到 ~0.70，相关消息 ~0.876。规格初值 0.62 在这种分布下会过于激进（闲聊频繁误切项目），因此默认切入阈值提升到 routerEnter = 0.75，可按自己的服务实测调回。配套参数：

- routerMargin = 0.08：top1 与 top2 差值 ≤ 该值视为歧义，发三选一菜单。
- 迟滞：项目 A 内要切到项目 B 需 sim(B) > enter + 0.05；本项目内不切出。
- 手动切换后 60 秒路由静默窗口：不对抗用户的手动操作。
- 工作意图启发式：祈使开头（来/继续/开始/修/写/跑/部署…）或含文件/命令操作词，仅用于触发"项目间切换建议"，不影响投递。

锚点与成本

- 每个项目维护一个锚点：该项目 AGENTS.md/README.md 前 2000 字 + 最近 6 轮对话摘要，缓存于 ~/.dsh/wechat-plus/anchors.json（TTL 1 小时）。日常模式无锚点（只判项目相似度）。
- embedding 调用成本：每条入站消息仅做一次相似度查询（openviking provider 为一次 search 调用；deepseek provider 为消息一次 embedding + 与缓存的锚点向量本地余弦比较）。锚点向量有 1 小时缓存，不会每条消息重算。

六、安装

DSH 插件装在 profile 里（默认 ~/.dsh/profiles/web/）。

⚠️ 代码更新提示（重要）：DSH 的插件加载器会缓存已导入的模块，修改插件源码后必须重启 DSH 才会加载新代码（配置项改动则热加载，无需重启）。首次安装也建议装完即重启一次。开发迭代建议用 link: 方式安装（见方式 B）。

📦 从 dsh-wechat-bridge 升级：本插件状态目录为 ~/.dsh/wechat-plus/。首次启动时若检测到旧目录 ~/.dsh/wechat-bridge/ 且新目录尚无数据，会自动整体迁移（token、会话索引、绑定状态全部保留），无需手动操作。

方式 A：官方命令（如本机已安装 dsh CLI）

在 DSH 之外打开 PowerShell，执行：
dsh plugin --profile web add "<插件仓库路径>"

dsh plugin 是 DSH 自带的插件管理命令（本质是把参数转发给 pnpm 并同步 bundle 列表）。
装完后重启 DSH 使 bundle 生效。

方式 B：手动安装（link: 链接，推荐开发迭代用）

cd "$env:USERPROFILE\.dsh\profiles\web"
pnpm add "link:<插件仓库路径>"

用 link:（而不是 file:）安装：node_modules 里是符号链接，改完源码重启 DSH 即生效，无需重装。

⚠️ 运行时 peer 依赖解析：插件目录在 DSH 应用安装树之外，Node ESM 解析够不到主机自带的 @deepseek-ai/ 包（会报 ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/schemastery'）。
因此本仓库通过 postinstall（scripts/ensure-host-junction.mjs）自动把 peer 包以 junction 链接到主机安装目录的 node_modules——在插件仓库里跑过 npm install 即自动建立。
若曾用 --legacy-peer-deps 跳过，可手动执行 node scripts/ensure-host-junction.mjs 补链。

- insert:
- id: wechat-plus
name: 'dsh-wechat-plus'

首次启用（扫码）

1. 插件默认 enabled: true，装好后没有凭证会自动进入扫码流程：自动弹出浏览器页面（~/.dsh/wechat-plus/login.html）显示二维码。
2. 手机微信扫码确认。成功后插件保存凭证（~/.dsh/wechat-plus/state.json），开始收发。
3. 想先不激活，可在 patch 配置里加 config: { enabled: false }。

可选：网页抓取（MCP fetch 服务器）

让微信里的 AI 真正能读网页内容。自研约 150 行极简实现，只依赖官方 @modelcontextprotocol/sdk（MIT）与 zod（MIT）：

cd mcp/fetch-server
npm install

然后在 profile 的 cordis.patch.yml 里挂载：

- insert:
- id: mcp-fetch
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: fetch
transport: stdio
command: 'C:\Program Files\nodejs\node.exe' # 换成你机器上 node.exe 的绝对路径 args:
- '<仓库路径>\mcp\fetch-server\server.mjs' cwd: '<仓库路径>\mcp\fetch-server' toolCallTimeoutMs: 60000 failOnStartupError: true

安全设计：仅 GET 公开 http/https 地址；拒绝 localhost/私网/环回地址（SSRF 防护）；20 秒超时、3 MB 下载上限、单次最多返回 10 万字符并支持分页续读；不执行任何抓取到的脚本。只有用户明确要求抓取时 AI 才会调用。

七、配置项

可在 DSH 设置界面（插件配置）或 cordis.patch.yml 的 config 中调整：

| 配置 | 默认 | 说明 |
| enabled | true | 是否启用桥接 |
| token / accountId | 空 | 已有 iLink 凭证（留空走扫码登录，推荐） |
| baseUrl | https://ilinkai.weixin.qq.com | iLink 服务地址 |
| allowFrom | [""] | 白名单（iLink 用户 ID）；建议收紧成你自己的 ID |
| admins | [] | 管理员列表：可执行控制命令；为空则所有人可执行 |
| workDir | 空 | AI 工作目录；留空用 DSH 当前工作区 |
| blockLinks | true | 拦截纯链接消息（安全铁律） |
| streaming | true | 流式分段发送 |
| idleTimeoutMins | 60 | 空闲多久自动结束会话（0=永不） |
| maxReplyChars | 1500 | 单条回复最大字符数（自动分段） |
| loginCooldownSecs | 30 | 登录失败重试间隔 |
| wechatMarkdown | true | 回复里的 Markdown 转微信友好纯文本 |
| groups / groupRequireMention | true | 群聊处理与 @ 触发（平台未开放，代码就绪） |
| pollWatchdogSecs | 90 | 长轮询假死看门狗（0=关闭） |
| usageFooter | true | 回复末尾附模型与用量统计 |
| routerEnabled | true | 启用 embedding 智能路由（关闭后按当前指针直通） |
| routerProvider | openviking | 相似度服务：openviking / deepseek / off |
| routerOpenvikingBaseUrl | http://127.0.0.1:1933 | OpenViking 服务地址 |
| routerDeepseekBaseUrl | https://api.deepseek.com | deepseek provider 的 embeddings API 地址 |
| routerDeepseekApiKey | 空 | deepseek provider 的 API key |
| routerDeepseekModel | 空 | deepseek provider 的 embedding 模型名（留空用服务端默认） |
| routerMargin | 0.08 | 歧义判定边际（top1−top2 ≤ 该值发三选一菜单） |
| routerEnter | 0.75 | 日常→项目切入阈值（实测校准值，见上文） |
| routeMode | auto | 路由模式：auto / ask / off |

运行时覆盖配置：~/.dsh/wechat-plus/override.json（可选，约 5 秒热加载、删除自动回退），可运行时调整 allowFrom、admins 与 cron jobs。

八、安全注意事项

- /history 脱敏：回发到微信的对话历史经过正则脱敏——API key、Bearer token、密码赋值、长随机串、手机号一律替换为 ；长历史分段复用安全发送，单次上限 20 段，超出提示。
- 白名单：allowFrom 建议只保留你自己的微信 ID（登录日志会打印）；陌生消息一律不进 AI。admins 控制命令权限。
- 隐私告知（embedding 锚点）：启用 openviking provider 的智能路由时，插件会把各项目的锚点文本（项目 AGENTS.md/README.md 前 2000 字 + 最近 6 轮对话摘要）作为资源写入本机 OpenViking 实例（wechat-plus-route/ 前缀），用于计算相似度。该数据只写入你本机的 OpenViking，不会发送到任何第三方；如介意，可将 routerProvider 设为 off 或改用 deepseek provider（消息 embedding 只经 API 计算、不落库）。
- 插件只做消息中转：不执行任何来自微信的命令行指令，纯链接默认拦截；高危操作由 DSH 本身的权限确认机制把关。

九、自动化测试

cd <插件仓库路径>
npm install # 首次
node --test # 单元测试（路由决策表全分支、阈值/迟滞/静默窗口、菜单 TTL、脱敏、绑定持久化）
npm run test # 全量集成测试（真实 DSH 服务树 + 真实模型 + 模拟微信客户端）
node test/unit.mjs # 纯单元测试（CI 亦运行此套）

测试环境自动隔离在 test/.home（复制你的凭证与模型配置），不污染真实 DSH 数据。

十、故障排查

- 日志：~/.dsh/wechat-plus/bridge.log（登录、扫码、路由决策、每条消息处理都记录）
- 重新扫码：删除 ~/.dsh/wechat-plus/state.json 后重启 DSH
- 凭证过期：插件自动重新进入扫码流程
- 收不到消息：确认插件已启用，看日志里 开始接收微信消息… 是否出现
- 路由不生效：/status 查看当前绑定；确认 routerEnabled: true 且 routerProvider 对应服务可达（provider 失败会降级直通并限频记日志）
- 杀毒软件误报：Windows Defender 可能误判 lib/index.js（实测 Trojan:Script/Obfuscript.A!ml）。处理：对 lib 目录添加排除、从隔离区还原后重启 DSH、可对照 git status 核实文件未被篡改。

十一、已知限制

- 单联系人同一时间只处理一个任务，连续发消息会排队依次处理
- 入站视频消息暂不支持；纯链接消息默认拦截
- 运行中任务：切换项目/会话时若当前会话 busy，仅提示 当前会话有任务运行中（未中断），任务不杀
- 会话标题超长截断（≤24 字符 + …）
- 旧版 DSH 缺少 sessionQuery/workspaceRegistry 服务时，会话/项目命令降级提示 当前 DSH 版本不支持

十二、免责声明

- 微信侧能力受腾讯《微信 ClawBot 功能使用条款》约束，请勿用于骚扰、营销、违反微信规则等用途。
- 本项目作者不对因违反腾讯条款、误配置白名单、AI 输出内容造成的任何损失负责。

dsh-wechat-plus · DSH WeChat Bridge Plugin (Project/Session Management + Smart Routing)

⚠️ 项目状态：已归档（2026-08-21）。 这个插件尚未完成，存在已知缺陷（会话恢复竞态、启动时多实例锁争用等），仅作为设计参考 / 概念验证保留——不建议用于生产环境。欢迎基于这里记录的思路继续开发。

把手机微信接到 DeepSeek Harness（DSH）：在微信里给机器人发消息，DSH 智能体处理，回复再流式推回微信。这个插件是 dsh-wechat-bridge 的升级改名版，在原桥接的基础上加了多项目 / 会话管理和基于嵌入的智能路由：切换项目、翻看历史会话，让「日常闲聊」和「项目工作」自己分流——全都在微信里完成。功能上对标 CC-Connect 的「微信消息中继」概念，但这是完全独立的原创实现，与 CC-Connect 没有任何代码、配置或商标关系（见下方合规说明）。

Phone WeChat ──▶ Tencent iLink Bot API (ilinkai.weixin.qq.com, official open protocol)
│ long-polling for messages / sendmessage for replies
▼
dsh-wechat-plus (this plugin, runs inside DSH)
│ command interception → smart routing → ctx.agents.create/followup/resume
▼
DeepSeek Harness AI Agent (official DSH Agent interface)

1. 合规与不侵权

1. 代码完全原创：独立编写；没有复制、翻译或派生 CC-Connect 的任何源码或配置。插件名、配置 schema、命令集均为原创。
2. 合法微信通道：使用腾讯官方开放的「微信 ClawBot 插件能力」——iLink Bot 协议（域名 ilinkai.weixin.qq.com），受腾讯 ClawBot 条款约束。不是逆向 iPad 协议，也不是 PC 客户端钩子。
3. 宽松许可依赖：协议访问通过独立开源项目 wechat-ilink-client（MIT，零运行时依赖），它参考了腾讯官方开源的 @tencent-weixin/openclaw-weixin。MIT 署名见 THIRD_PARTY_NOTICES.md。
4. 商标与命名：不含任何「cc-connect」名称、图标、文档文字或品牌元素。
5. 参考对象：CC-Connect 本身是 MIT 许可，合法复用只需署名即可；本项目选择更保守的路线——零使用其代码，只实现「消息中继」这一通用概念（功能概念不受版权保护）。

2. iLink 协议

腾讯官方 Bot 协议，用于「微信 ClawBot 插件能力」，服务地址为 https://ilinkai.weixin.qq.com。核心交互包括：长轮询接收消息、sendmessage 发送文本回复、getUploadUrl + CDN 收发图片和文件，以及上报输入状态。凭证为 Token + 账号 ID（扫码登录后自动获取并持久化）。本插件通过 MIT 协议的 wechat-ilink-client 调用该协议。

3. 功能

- ✅ 微信私聊 → DSH AI 对话，回复分段流式输出（打字机效果，在句子边界切分——绝不从词中间断开）
- ✅ 多项目/会话管理：/projects /project /sessions /home /new /stay /status /history（见下一节）
- ✅ 嵌入智能路由：日常聊天留在原地；与项目相关的消息自动切到对应项目（见「智能路由」）
- ✅ 内置扫码登录（自动弹出登录页；也可配置已有 token）
- ✅ 按联系人保存绑定状态（当前项目 + 会话指针），持久化，重启后恢复
- ✅ 语音消息（先转写再交给 AI）、文本消息
- ✅ 接收图片：图片自动下载到工作目录；AI 用工具分析（OCR/视觉）
- ✅ 接收与发送文件：收到的文件自动下载供 AI 读取；AI 生成的文件保存到 wechat-outbox/<contact>/ 后自动发回微信；专用工具 wechat_send_file 和 wechat_send_local_file
- ✅ 微信排版：Markdown（加粗/表格/引用/列表/链接）自动转成微信友好的纯文本；非流式的长回复带 (1/n) 分段编号
- ✅ 群聊（代码就绪，等待平台开放）：⚠️ 经测试确认，ClawBot 机器人目前无法加入群聊（平台未开放）；一旦开放即可开箱即用
- ✅ 网页抓取（可选）：极简 MCP fetch 服务器（mcp/fetch-server/）；仅在明确请求时抓取公开页面
- ✅ 定时任务：按计划向联系人发送提示词；配置热重载
- ✅ 输入状态提示、用量页脚（每条回复的模型与 token 统计）
- ✅ 分级白名单：allowFrom 控制谁能聊天；admins 控制管理命令；可通过 override.json 热重载
- ✅ 纯链接拦截（安全规则）、过期自动重连、轮询看门狗、空闲回收、单实例互斥
- ⏳ 不支持：接收视频消息（忽略并记录日志）

4. 会话与项目管理

每个联系人的消息都有明确的归属指针：当前项目（Daily 或某个具体项目）+ 该项目内的当前会话。指针持久化在 ~/.dsh/wechat-plus/bindings.json，重启后依然有效。

命令表

| 命令 | 行为 |
| /projects | 列出所有项目（Daily 置顶），带编号菜单 |
| /project <n> | 切换到第 n 个项目；落在该项目最近活跃的会话（或下一条消息开启新会话） |
| /sessions [页码或关键词] | 列出当前项目的会话（标题+时间，每页 ≤8 条，n=下一页；关键词按标题过滤） |
| 回复数字 | 从 /sessions 菜单里选一个会话，回显 已切换：《title》，之后的消息会接着它继续 |
| /home | 回到日常模式 |
| /new | 在当前项目里开新会话（旧会话保留，可用 /sessions 找到） |
| /stay [小时] | 钉住当前上下文（默认 2h）；智能路由保持静默；不带参数 = 查询剩余时间 |
| /status | 显示当前项目 / 会话 / stay 状态 / 当前模型 |
| /history [n] | 把当前会话最近 n 轮（默认 5）发到微信（自动脱敏；最多 20 段） |
| /models | 按服务商分组列出可用模型（当前模型 ★），带编号菜单 |
| /model <编号或名称> | 为当前联系人切换模型：编号从菜单里选 / 模型 id（唯一子串匹配；匹配到多个会列出候选）/ 不带参数显示当前模型。按联系人持久化（重启后仍在）；空闲时立即生效（会话上下文保留），忙碌时等当前轮跑完再生效 |
| /help | 帮助文本 |
| /stop | 打断正在跑的任务 |

所有斜杠命令都在送达 AI 之前被拦截——零 LLM 调用，即时响应。命令必须完全匹配（去除首尾空白、以 / 开头、第一个 token 在命令表里）。

日常模式

- 新联系人默认落在伪项目 Daily（__daily__，工作目录 ~/.dsh/daily/），只有一个长期存活的会话：上下文保持连续；更早的轮次靠会话持久化滚出模型窗口。
- 日常会话里的智能体照样能用 OpenViking 记忆工具（viking_remember / viking_search）——长期记忆就此建立。

层级约束（铁律）

1. /sessions 只列当前项目下的会话（按会话工作目录过滤）——不跨项目混在一起。
2. /project <n> 落到该项目最近活跃的会话；每个项目各自记住自己的会话指针（切走再切回来，还在同一个会话里）。
3. 恢复会话始终用该会话自己的工作目录——不跨项目恢复。

编号菜单机制

- 同一时刻只有一个活跃菜单：一个联系人最多一个活跃菜单；新菜单会让旧菜单失效。
- TTL 很短：菜单 5 分钟后过期；之后再回复数字会收到 菜单已失效，请重新 /sessions。

5. 智能路由

路由发生在把消息送达 AI 之前（斜杠命令拦截之后）。判定为跑题的消息直接送到目标会话——被打断的会话根本看不到它，所以不存在「撤回」问题。

决策表

消息到达 ├─ 斜杠命令 → 命令层（最高优先级） ├─ /stay 未过期 → 原样送到当前指针 ├─ 当前在 [项目 A] │ ├─ 与 A 相似 → 送到 A │ ├─ 与 B 相似 + 工作意图 → 投递到 A + 一行切换建议（「看起来是 [B] 的活？1. 切换 2. 留在这里」） │ └─ 两者都低（纯聊天）→ 投递到 A（在项目里聊天没问题，绝不切出去） └─ 当前在 [Daily] ├─ top1 与 top1−top2 > margin → 自动切换项目 + 头部提示 + 撤销提示 ├─ top1/top2 模糊（差距 ≤ margin）→ 三选一菜单「1.[A] 2.[B] 3.留在 Daily」 └─ 全部低于阈值 → 留在 Daily

自动切换后，回复会带上头部 [已进入【ProjectA】·《session title》]，末尾一行 ↩ /home 回日常。

routeMode 级别

| 级别 | 行为 |
| auto（默认） | 高置信度时自动切换（带头部提示，可撤销） |
| ask | 切换前先发三选一确认菜单 |
| off | 全手动，不自动切换 |

相似度服务商（可插拔）

- insert:
- id: wechat-plus
name: 'dsh-wechat-plus'
config:
routerEnabled: true # master switch (off = deliver to current pointer)
routerProvider: openviking # 'openviking' | 'deepseek' | 'off'
routerOpenvikingBaseUrl: 'http://127.0.0.1:1933'
routeMode: auto # 'auto' | 'ask' | 'off'

- openviking（推荐）：用你本地的 OpenViking 语义搜索算相似度——免费，不需要 API key（开发模式下免鉴权）。
- deepseek：OpenAI 兼容的 /embeddings 端点；需要 routerDeepseekApiKey（可选 routerDeepseekBaseUrl、routerDeepseekModel）；余弦相似度在本地计算。
- off：不做路由。

兜底安全网：服务商不可达或失败时，路由降级为直通（按当前指针投递，日志限流）——消息永远不会被阻塞。

阈值与校准（为什么默认 enter=0.75）

在本地 OpenViking（0.4.15）上实测，相似度分数整体偏高：无关消息约 0.70，相关消息约 0.876。原始规格里的 0.62 在这个分布下会过于激进（闲聊时频繁误切），所以默认进入阈值提高到 routerEnter = 0.75；请按你自己服务的实测值调整。相关参数：

- routerMargin = 0.08：top1−top2 ≤ 这个值就算模糊 → 三选一菜单。
- 迟滞：从项目 A 切到项目 B 需要 sim(B) > enter + 0.05；在当前项目内绝不切出去。
- 手动切换后 60 秒路由静默：绝不跟用户对着干。
- 工作意图启发式：祈使句开头（continue/fix/write/run/deploy…）或文件/命令操作词——只触发跨项目建议，绝不改变投递。

锚点与成本

- 每个项目维护一个 anchor：AGENTS.md/README.md 的前 2000 个字符，加上最近 6 轮对话的摘要，缓存在 ~/.dsh/wechat-plus/anchors.json（TTL 1 小时）。每日模式没有 anchor（只判断项目相似度）。
- Embedding 开销：每条入站消息只触发 一次 相似度查询（openviking：一次 search 调用；deepseek：一次消息 embedding + 对缓存 anchor 向量做本地余弦计算）。anchor 向量缓存 1 小时，不会每条消息都重算。

6. 安装

DSH 插件安装到配置档（默认 ~/.dsh/profiles/web/）。

⚠️ 代码更新提醒（重要）：DSH 的插件加载器会缓存已导入的模块 —— 改完插件源码后要重启 DSH（改配置会热重载，不用重启）。首次安装后也要重启一次。开发时用 link: 方式（方式 B）。

📦 从 dsh-wechat-bridge 升级：状态目录现在是 ~/.dsh/wechat-plus/。首次启动时，如果旧的 ~/.dsh/wechat-bridge/ 还在、新目录又没数据，会 自动整体迁移（token、会话索引、绑定全部保留）—— 不用手动操作。

方式 A：官方命令（装了 dsh 命令行的话）

Open PowerShell outside DSH and run:
dsh plugin --profile web add "<path to this repo>"

dsh plugin 是 DSH 内置的插件管理器（转发给 pnpm，并同步 bundle 列表）。
安装后 重启 DSH，bundle 才会生效。

方式 B：手动安装（link:，开发推荐）

cd "$env:USERPROFILE\.dsh\profiles\web"
pnpm add "link:<path to this repo>"

用 link:（不要用 file:）：node_modules 里会生成软链接 —— 改源码，重启 DSH，搞定。

⚠️ 运行时 peer-dep 解析：仓库在 DSH 安装树之外，Node ESM 够不到宿主机的 @deepseek-ai/ 包（ERR_MODULE_NOT_FOUND: @deepseek-ai/schemastery）。postinstall 脚本（scripts/ensure-host-junction.mjs）会从宿主机 node_modules 把 peer 包 junction 链接过来 —— 在仓库里跑 npm install 就会自动配好。如果你用 --legacy-peer-deps 跳过了，跑一下 node scripts/ensure-host-junction.mjs。

- insert:
- id: wechat-plus
name: 'dsh-wechat-plus'

首次运行（二维码）

1. 默认 enabled: true 且没有凭据时，插件自动启动二维码登录：弹出浏览器页面（~/.dsh/wechat-plus/login.html），显示二维码。
2. 用手机微信扫码。凭据存到 ~/.dsh/wechat-plus/state.json，随即开始收发消息。
3. 想让它保持不启用，在 patch 里加 config: { enabled: false }。

可选：网页抓取（MCP fetch 服务器）

让微信侧的 AI 真正能读网页。约 150 行的原创实现，只依赖官方 @modelcontextprotocol/sdk（MIT）和 zod（MIT）：

cd mcp/fetch-server
npm install
在配置档的 cordis.patch.yml 里挂载：

- insert:
- id: mcp-fetch
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: fetch
transport: stdio
command: 'C:\Program Files\nodejs\node.exe' # absolute path to node.exe on your machine
args:
- '<repo path>\mcp\fetch-server\server.mjs'
cwd: '<repo path>\mcp\fetch-server'
toolCallTimeoutMs: 60000
failOnStartupError: true

安全设计：GET 只允许公开的 http/https；拒绝 localhost/私有/回环地址（防 SSRF）；20s 超时，上限 3 MB，每个响应 ≤100k 字符并支持分页；绝不执行抓取到的脚本。只有用户明确要求时，AI 才会调用它。

7. 配置

可在 DSH 设置界面或 cordis.patch.yml 的 config 里调整：

| 选项 | 默认值 | 说明 |
| enabled | true | 启用桥接 |
| token / accountId | 空 | 已有的 iLink 凭据（留空 = 扫码登录，推荐） |
| baseUrl | https://ilinkai.weixin.qq.com | iLink 服务 URL |
| allowFrom | [""] | 允许列表（iLink 用户 ID）；收紧为你自己的 ID |
| admins | [] | 可执行控制命令的管理员；留空 = 所有人 |
| workDir | 空 | AI 工作目录；留空 = 当前 DSH 工作区 |
| blockLinks | true | 拦截纯链接消息（安全规则） |
| streaming | true | 分段流式回复 |
| idleTimeoutMins | 60 | 空闲多少分钟后自动结束会话（0 = 从不） |
| maxReplyChars | 1500 | 每条微信回复的最大字符数（自动分段） |
| loginCooldownSecs | 30 | 登录失败后的重试间隔 |
| wechatMarkdown | true | 把 Markdown 转成微信友好的纯文本 |
| groups / groupRequireMention | true | 群聊处理与 @ 触发（平台未开放；代码已就绪） |
| pollWatchdogSecs | 90 | 轮询看门狗（0 = 关闭） |
| usageFooter | true | 在回复末尾追加模型与用量统计 |
| routerEnabled | true | 启用 embedding 智能路由（关闭 = 直通） |
| routerProvider | openviking | 相似度服务：openviking / deepseek / off |
| routerOpenvikingBaseUrl | http://127.0.0.1:1933 | OpenViking 服务 URL |
| routerDeepseekBaseUrl | https://api.deepseek.com | deepseek 服务商的 Embeddings API URL |
| routerDeepseekApiKey | 空 | deepseek 服务商的 API key |
| routerDeepseekModel | 空 | Embedding 模型名（留空 = 服务端默认） |
| routerMargin | 0.08 | 歧义阈值（top1−top2 ≤ 该值 → 三选一菜单） |
| routerEnter | 0.75 | 每日→项目入口阈值（已校准的默认值，见上文） |
| routeMode | auto | 路由模式：auto / ask / off |

运行时覆盖：~/.dsh/wechat-plus/override.json（可选，约 5s 内热重载，删除后自动还原），用于 allowFrom、admins 和 cron jobs。

8. 安全说明

- /history 脱敏：发给微信的会话历史会经过正则脱敏——API key、bearer token、密码赋值、长随机字符串、手机号全部替换为 ；长输出会安全分段，每次调用最多 20 段。
- 允许列表：allowFrom 里只保留你自己的微信 ID（登录日志里会打印）；陌生人永远到不了 AI。admins 控制哪些命令可用。
- 隐私说明（嵌入锚点）：启用 openviking 服务商后，插件会把每个项目的锚点文本（项目 AGENTS.md/README.md 的前 2000 字符，加上最近 6 轮的摘要）作为资源写入你本地的 OpenViking 实例（前缀 wechat-plus-route/），用于相似度计算。这些数据留在你机器上，绝不发给第三方；如果你介意，把 routerProvider 设为 off，或改用 deepseek 服务商（消息嵌入只通过 API 计算，不存储任何内容）。
- 插件只转发消息：不会执行来自微信内容的任何 shell 命令，默认拦截纯链接；危险操作仍由 DSH 自身的权限确认把关。

9. 自动化测试

cd <repo path>
npm install # first time
node --test # unit tests (routing decision table branches, thresholds/hysteresis/silence window, menu TTL, redaction, binding persistence)
npm run test # full integration tests (real DSH service tree + real model + mocked WeChat client)
node test/unit.mjs # pure unit tests (also run in CI)

Tests auto-isolate in test/.home (copies your credentials & model config) — no pollution of real DSH data.

10. Troubleshooting

- Logs: ~/.dsh/wechat-plus/bridge.log (login, QR, routing decisions, every message)
- Re-scan QR: delete ~/.dsh/wechat-plus/state.json and restart DSH
- Expired credentials: the plugin auto-restarts the QR flow
- No messages arriving: check the plugin is enabled and 开始接收微信消息… appears in the log
- Routing not working: /status to inspect bindings; ensure routerEnabled: true and the provider service is reachable (provider failure degrades to pass-through with rate-limited logs)
- Antivirus false positives: Windows Defender may flag lib/index.js (observed Trojan:Script/Obfuscript.A!ml). Fix: exclude the lib directory, restore from quarantine, restart DSH; verify integrity with git status.

11. Known Limitations

- One task per contact at a time; consecutive messages queue in order
- Inbound video not supported; pure links intercepted by default
- Running tasks: switching project/session while busy only warns 当前会话有任务运行中（未中断） — the task is not killed
- Session titles truncated (≤24 chars + …)
- On older DSH lacking sessionQuery/workspaceRegistry, session/project commands degrade with a 当前 DSH 版本不支持 notice

12. Disclaimer

- WeChat-side capabilities are governed by Tencent's WeChat ClawBot terms of use; do not use for spam, marketing, or anything violating WeChat rules.
- The author is not liable for losses caused by violating Tencent's terms, misconfigured allowlists, or AI output.