前言¶

做 DSH 插件或智能体开发时，经常遇到一个需求：让模型读一份放在企业微信微盘里的文档。常见做法是先把文件下载下来、再手动贴路径，步骤多且容易和授权状态脱节。下面介绍的这个插件把这件事收进了对话输入条：点按钮选文件，选中项会变成官方机制可认的 @ 引用 chip，后续由 wecom-cli 按 id 前缀路由到对应技能去读。它解决的不是”能不能读微盘”，而是把微盘选择、引用生成、技能路由串成一条在输入条里完成的路径。

该插件名为 cillivian/wecom-file-dsh，仓库名/产品名即 wecom-file-dsh，包名是 wecom-dsh-plugins，插件 id 是 wecom-picker（三个标识各不相同，安装和配置时别混）。维护者为 Cillivian，分类属于客户端插件，GitHub 仓库：https://github.com/Cillivian/wecom-file-dsh，目录页：https://www.skillhub.cn/plugins/Cillivian/wecom-file-dsh。

核心设计是 CLI 优先、iframe 回退：默认走本机 wecom-cli，不需要浏览器登录，桌面版与 dsh web 表现一致；机器上没有 CLI 时自动切到 doc.weixin.qq.com 的官方选择器。

功能概览¶

• 输入条左侧工具栏增加「企业微信·微盘」按钮
• 弹层是 macOS 26 Finder 风格的毛玻璃浮动窗口：统一工具栏 + 分段查看方式 + 排序菜单 + 搜索框 + 状态栏
• 三种查看方式（列表 / 分栏 / 画廊）、五个排序字段（升降序）、实时搜索、滚动加载更多、多选（最多 10 项）
• 授权失效时弹层内直接展示 wecom-cli 的扫码二维码；登录失败或二维码过期后，同一处的「重新授权」/「重新获取二维码」可重开一次登录
• 运行时技能 wecom-wedrive-ref（chip 到 wecomcli-* 路由）与 wecom-wedrive-picker-setup（安装 / 配置 / 排查）
• 桌面版与 dsh web 两个 profile 都能装

chip 文本规则：文件 / 文档写成 @<id>/<文件名>，名称含空格时为 @"<id>/<文件名>"；文件夹写成 @<id>/<文件夹名>/。

安装与启用¶

安装命令直接来自 README 的快速开始，前置是 wecom-cli ≥ 1.2.0 且已授权：

# 1. 前置：wecom-cli ≥ 1.2.0 且已授权
wecom-cli --version
wecom-cli auth show --status        # 期望 authorized；否则 wecom-cli auth init --noninteractive

# 2. 装进目标 profile（desktop 或 web，按需替换）
cd "${DSH_HOME:-$HOME/.dsh}/profiles/desktop"
pnpm add wecom-dsh-plugins@github:Cillivian/wecom-file-dsh
# 再把 "wecom-dsh-plugins" 加进 package.json 的 dsh.profile.bundles

# 3. 重启应用 / 重开 dsh web

本机改代码时改用软链：pnpm add wecom-dsh-plugins@link:/abs/path/to/wecom-file-dsh。lib/ 里的产物（lib/host/*.js、lib/shared/*.js、lib/client.js）都已入库，从 GitHub 装不需要任何构建步骤。

配置写在 profile 的 patch 层，因为它在所有 bundle 层之后应用：

# ${DSH_HOME:-$HOME/.dsh}/profiles/<desktop|web>/cordis.patch.yml

- id: wecom-picker
  name: wecom-dsh-plugins
  config:
    placement: plusMenu     # standalone（默认）| plusMenu | both

改完重启应用。id 必须和 bundle 层插入的行一致，固定是 wecom-picker。

不支持该配置的旧宿主或读不到配置时，回落到 standalone。

典型用法¶

安装配置完成后，在对话输入条点击「企业微信·微盘」按钮，在弹层里搜索或切换文件夹，选中要引用的文件、文档或文件夹后回车插入。选中项会变成 @<id>/<名称> 形式的 chip，模型侧据此路由：

id 来源是 wecom-cli disk files list/search 的字段：在线文档用 docid，普通文件和文件夹用条目 id；结果里没有 docid 时一律用条目 id。

弹层自身支持键盘操作：Esc 关闭、Enter 插入、⌘/Ctrl+F 聚焦搜索、↑/↓/Home/End 行间移动、Space 切换选中。窗口位置存 localStorage（wecom-picker/window/v1），排序与查看方式存 wecom-picker/preferences/v1，下次打开仍在原处。

为什么默认不是官方 iframe 选择器¶

官方选择器在 DSH 桌面版里无法登录，这是第三方 iframe 的固有限制。README 里列了三步原因：桌面版 origin 是 dsh-app://app，WeCom 会话 cookie 默认 SameSite=Lax，跨站 iframe 里既种不下也不会发送；官方登录面板只肯在 iframe 内运行，扫码成功后却用 window.top.location 导航最顶层窗口；桌面版对离开 dsh-app://app 的顶层跳转有围栏（apps/desktop/src/main.ts:226），表现为只能跳外部浏览器，而外部浏览器里的会话回不到 DSH。

所以官方选择器只作为回退保留，并且只在浏览器 + 同站代理下能真正登录。

宿主路由¶

插件在 DSH 宿主的 loopback HTTP 服务上注册四条路由（浏览器侧用文档相对路径 wecom-picker/… 调用，宿主按绝对路径注册，复用 connection 的 Host/Origin 围栏）：

失败统一返回 { ok: false, state: 'missing' | 'unauthorized' | 'error', message }，missing 用 503，其余 200。

适用场景与注意事项¶

适合已经在桌面版或 dsh web 里使用 wecom-cli、希望把微盘文件引用放进对话流程的开发者。插件本身以当前 dsh 进程的权限运行，安装前应先检查源码与许可证。

安全方面，README 已有明确说明：四个路由都过 Host/Origin 围栏，防止 DNS rebinding 与跨站网页驱动本地 CLI；wecom-cli 通过 ctx.subprocess 以固定 argv 数组执行，不经过 shell，用户输入只作为 --json 参数值；单次调用有超时（20s / 探测 15s / 登录 10min）与输出上限（stdout 2 MiB、stderr 64 KiB）；唯一落盘的是登录二维码 $DSH_HOME/storages/wecom-picker/qr.png；插件不收集、不上传任何数据。

许可需要注意：本仓库源代码以 MIT 许可发布，但内置的腾讯文档文件类型图标与启动按钮图标取自腾讯内部包，上游未声明许可证，不在 MIT 许可范围内，对外分发前需资源所有者确认。另外 wecom-cli 与 @deepseek-ai/* 均为内部资源，peerDependencies 由运行中的 DeepSeek Harness 提供。

结尾¶

这个插件的价值在于把微盘选择做成了输入条里的一步操作，并把 chip 到技能的路由固定下来，而不是让使用者在 CLI 和浏览器之间来回切。目录页：https://www.skillhub.cn/plugins/Cillivian/wecom-file-dsh，仓库：https://github.com/Cillivian/wecom-file-dsh，安装配置细节见仓库 docs/SETUP.md，架构说明见 docs/ARCHITECTURE.md。