前言¶

做 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。