Introduction¶

When developing DSH plugins or agents, a common requirement arises: getting the model to read a document stored in the WeCom Micro-disk. The common approach is to first download the file and then manually paste the path—this is cumbersome and prone to disconnecting from the authorization state. The plugin introduced below consolidates this into the conversation input bar: click a button to select a file, and the selected item becomes an official mechanism-recognizable @ reference chip, which is subsequently routed to the corresponding skill by wecom-cli based on the ID prefix. It solves not “whether it can read the micro-disk,” but rather strings together the micro-disk selection, reference generation, and skill routing into a path completed within the input bar.

The plugin is named cillivian/wecom-file-dsh. The repository name/product name is wecom-file-dsh, the package name is wecom-dsh-plugins, and the plugin ID is wecom-picker (the three identifiers are different, so don’t mix them up during installation and configuration). The maintainer is Cillivian, classified as a client plugin. GitHub repository: https://github.com/Cillivian/wecom-file-dsh, directory page: https://www.skillhub.cn/plugins/Cillivian/wecom-file-dsh.

The core design is CLI-first with iframe fallback: it defaults to the local wecom-cli, requiring no browser login, and behaves consistently between the desktop version and dsh web. When the CLI is not available on the machine, it automatically switches to the official selector on doc.weixin.qq.com.

Feature Overview¶

• Added an “Enterprise WeChat · Micro-disk” button to the toolbar on the left side of the input bar
• The layer is a macOS 26 Finder style frosted glass floating window: unified toolbar + segmented view + sort menu + search box + status bar
• Three view modes (list / grid / gallery), five sort fields (ascending/descending), real-time search, scroll to load more, multi-select (max 10 items)
• When the authorization expires, the QR code of wecom-cli is displayed directly in the layer; after login fails or the QR code expires, “Re-authorize” / “Re-fetch QR Code” in the same place can restart the login
• Runtime skills wecom-wedrive-ref (chip to wecomcli-* routing) and wecom-wedrive-picker-setup (install / config / troubleshoot)
• Installable in both the desktop and dsh web profiles

Chip text rules: Files/Documents are written as @<id>/<filename>, and when the name contains spaces, as @"<id>/<filename>". Folders are written as @<id>/<foldername>/.

Installation and Enablement¶

The installation command comes directly from the Quick Start in the README, with the prerequisite being wecom-cli ≥ 1.2.0 and authorized:

# 1. Prerequisite: wecom-cli ≥ 1.2.0 and authorized
wecom-cli --version
wecom-cli auth show --status        # Expect authorized; otherwise wecom-cli auth init --noninteractive

# 2. Install into target profile (desktop or web, replace as needed)
cd "${DSH_HOME:-$HOME/.dsh}/profiles/desktop"
pnpm add wecom-dsh-plugins@github:Cillivian/wecom-file-dsh
# Then add "wecom-dsh-plugins" to dsh.profile.bundles in package.json

# 3. Restart application / reopen dsh web

When editing code locally, use a symlink: pnpm add wecom-dsh-plugins@link:/abs/path/to/wecom-file-dsh. The artifacts in lib/ (like lib/host/*.js, lib/shared/*.js, lib/client.js) are already committed to the repo, so no build steps are needed when installing from GitHub.

Configuration is written in the profile’s patch layer because it is applied after all bundle layers:

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

- id: wecom-picker
  name: wecom-dsh-plugins
  config:
    placement: plusMenu     # standalone (default) | plusMenu | both

Restart the application after changing. The id must match the line inserted in the bundle layer, and it is fixed as wecom-picker.

If the old host does not support this configuration or the configuration cannot be read, it falls back to standalone.

Typical Usage¶

After installation and configuration are complete, click the “Enterprise WeChat · Micro-disk” button in the conversation input bar. Search or switch folders in the layer. After selecting the file, document, or folder to reference, press Enter to insert. The selected item becomes a chip in the form @<id>/<name>, and the model routes based on this:

The source of the ID is from the fields of wecom-cli disk files list/search: docid is used for online documents, and the entry id is used for regular files and folders; if docid is not present in the results, the entry id is used by default.

The layer itself supports keyboard operations: Esc to close, Enter to insert, ⌘/Ctrl+F to focus search, ↑/↓/Home/End to move between lines, Space to toggle selection. The window position is stored in localStorage (wecom-picker/window/v1), and sort/view mode is stored in wecom-picker/preferences/v1, so it opens in the same place next time.

Why the Official Iframe Selector is Not the Default¶

The official selector cannot log in in the DSH desktop version; this is a inherent limitation of third-party iframes. The README lists three reasons for this: the desktop origin is dsh-app://app, the WeCom session cookie defaults to SameSite=Lax, so neither can be set nor sent in a cross-site iframe; the official login panel only agrees to run inside an iframe, but after successful scanning, it uses window.top.location to navigate the top-level window; the desktop version has a fence for top-level navigation leaving dsh-app://app (pointing to apps/desktop/src/main.ts:226), manifesting as the ability to only jump to an external browser, and the session in the external browser cannot return to DSH.

Therefore, the official selector is kept as a fallback and can only log in for real when running in a browser + same-site proxy.

Host Routing¶

The plugin registers four routes on the DSH host’s loopback HTTP service (the browser side calls using the document relative path wecom-picker/…, the host registers using absolute paths, reusing the connection Host/Origin fence):

Failures uniformly return { ok: false, state: 'missing' | 'unauthorized' | 'error', message }, using 503 for missing and 200 for the rest.

Use Cases and Precautions¶

Suitable for developers who are already using wecom-cli in the desktop version or dsh web and want to bring micro-disk file references into the conversation flow. The plugin itself runs with the permissions of the current DSH process; before installing, you should first check the source code and license.

Regarding security, the README has clear instructions: all four routes go through the Host/Origin fence to prevent DNS rebinding and cross-site web page driving of the local CLI; wecom-cli executes via ctx.subprocess with a fixed argv array, not through a shell, and user input is only used as the value of the --json parameter; single call has timeout (20s / probe 15s / login 10min) and output limit (stdout 2 MiB, stderr 64 KiB); the only thing written to disk is the login QR code $DSH_HOME/storages/wecom-picker/qr.png; the plugin does not collect or upload any data.

Regarding the license: the source code in this repository is released under the MIT license, but the built-in Tencent Docs file type icons and launch button icons are taken from a Tencent internal package. The upstream has not declared a license, so they are not within the scope of the MIT license. You need confirmation from the resource owner before redistributing. Additionally, wecom-cli and @deepseek-ai/* are internal resources, provided by peerDependencies.

Conclusion¶

The value of this plugin lies in making the micro-disk selection a step operation within the input bar, and fixing the routing from chip to skill, rather than making the user switch back and forth between CLI and the browser. Directory page: https://www.skillhub.cn/plugins/Cillivian/wecom-file-dsh, Repository: https://github.com/Cillivian/wecom-file-dsh. For installation and configuration details, see the repo’s docs/SETUP.md; for architecture explanation, see docs/ARCHITECTURE.md.