@deepseek-ai/dsh-wecom 0.0.0-stage → 0.2.3-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.i18n.yaml +88 -0
  3. package/README.md +177 -2
  4. package/README.zh.md +178 -0
  5. package/cordis.patch.yml +3 -0
  6. package/docs/DETAIL.md +1 -0
  7. package/docs/DETAIL.zh.md +1 -0
  8. package/docs/preview.svg +1 -0
  9. package/docs/preview.zh.svg +1 -0
  10. package/icon.svg +1 -0
  11. package/lib/index.js +590 -0
  12. package/lib/types/account.d.ts +19 -0
  13. package/lib/types/account.d.ts.map +1 -0
  14. package/lib/types/account.js.map +1 -0
  15. package/lib/types/directory.d.ts +17 -0
  16. package/lib/types/directory.d.ts.map +1 -0
  17. package/lib/types/directory.js.map +1 -0
  18. package/lib/types/index.d.ts +30 -0
  19. package/lib/types/index.d.ts.map +1 -0
  20. package/lib/types/index.js.map +1 -0
  21. package/lib/types/locales.d.ts +93 -0
  22. package/lib/types/locales.d.ts.map +1 -0
  23. package/lib/types/locales.js.map +1 -0
  24. package/lib/types/presentation.d.ts +29 -0
  25. package/lib/types/presentation.d.ts.map +1 -0
  26. package/lib/types/presentation.js.map +1 -0
  27. package/lib/types/skills.d.ts +7 -0
  28. package/lib/types/skills.d.ts.map +1 -0
  29. package/lib/types/skills.js.map +1 -0
  30. package/lib/types/types.d.ts +20 -0
  31. package/lib/types/types.d.ts.map +1 -0
  32. package/lib/types/types.js.map +1 -0
  33. package/locale/de.json +7 -0
  34. package/locale/en.json +7 -0
  35. package/locale/es.json +7 -0
  36. package/locale/fr.json +7 -0
  37. package/locale/ja.json +7 -0
  38. package/locale/pt.json +7 -0
  39. package/locale/ru.json +7 -0
  40. package/locale/zh.json +7 -0
  41. package/package.json +62 -3
  42. package/skills/wecom/SKILL.md +40 -0
  43. package/src/account.ts +69 -0
  44. package/src/directory.ts +43 -0
  45. package/src/index.ts +66 -0
  46. package/src/locales.ts +279 -0
  47. package/src/presentation.ts +116 -0
  48. package/src/skills.ts +18 -0
  49. package/src/types.ts +25 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DeepSeek
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,88 @@
1
+ # Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
2
+ # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
3
+ # After editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/connector/wecom/README.md
5
+ /:
6
+ en: 61517a3b25e2a2c5
7
+ zh: 55ef5e89541516e0
8
+ /deepseek-ai-dsh-wecom:
9
+ en: 97ebb140059d2cd9
10
+ zh: b9753254b9a084f3
11
+ /deepseek-ai-dsh-wecom/summary:
12
+ en: 06358926dfdfecee
13
+ zh: 5ae37704e7983a03
14
+ /deepseek-ai-dsh-wecom/table-of-contents:
15
+ en: d152484eb41ac6b4
16
+ zh: 09388d293f9be9cb
17
+ /deepseek-ai-dsh-wecom/use-this-package:
18
+ en: bbff250eba0f1b89
19
+ zh: 0a618f05cc88ee2b
20
+ /deepseek-ai-dsh-wecom/use-this-package/install-into-a-profile:
21
+ en: 6227d6e43ec8c108
22
+ zh: 48e0f252de253d14
23
+ /deepseek-ai-dsh-wecom/use-this-package/what-you-get:
24
+ en: 7581623b2b257fe0
25
+ zh: cdd670dfd6d0183d
26
+ /deepseek-ai-dsh-wecom/use-this-package/authorization-operations:
27
+ en: a5d3467ec57a5657
28
+ zh: ea5a0e1c3c539046
29
+ /deepseek-ai-dsh-wecom/use-this-package/configure:
30
+ en: dfbcda32182eb7eb
31
+ zh: 554086e7081a313a
32
+ /deepseek-ai-dsh-wecom/understand-the-implementation:
33
+ en: 2b6b63d9e4e2e41c
34
+ zh: 6268453811f2efcb
35
+ /deepseek-ai-dsh-wecom/further-exploration:
36
+ en: 7a8fda721faaf5ef
37
+ zh: b4233b8a77994ae6
38
+ /deepseek-ai-dsh-wecom/model-experience:
39
+ en: 215e7ba838619b7b
40
+ zh: a311da3843709f90
41
+ /deepseek-ai-dsh-wecom/model-experience/skill-catalog-entries:
42
+ en: 7265024b55daf9ef
43
+ zh: 3447e587c56a25d6
44
+ /deepseek-ai-dsh-wecom/model-experience/skill-catalog-entries/what-the-model-sees:
45
+ en: 92eb47194f3c8cc3
46
+ zh: b9cfda74948e4b1a
47
+ /deepseek-ai-dsh-wecom/model-experience/skill-catalog-entries/token-effect:
48
+ en: 5c0018a8ae3cd3d3
49
+ zh: 341e13c2f26125be
50
+ /deepseek-ai-dsh-wecom/model-experience/skill-catalog-entries/kv-cache-effect:
51
+ en: ce9139edf3309f2b
52
+ zh: bca06594b3e557e5
53
+ /deepseek-ai-dsh-wecom/model-experience/loaded-skill-body:
54
+ en: 8955ac196848e69f
55
+ zh: 54aa7db097eafd3c
56
+ /deepseek-ai-dsh-wecom/model-experience/loaded-skill-body/what-the-model-sees:
57
+ en: ff5d75fb84ce8130
58
+ zh: 0f236bf0534755a9
59
+ /deepseek-ai-dsh-wecom/model-experience/loaded-skill-body/token-effect:
60
+ en: 1ed287a86abbc585
61
+ zh: 5d55a6fd61786866
62
+ /deepseek-ai-dsh-wecom/model-experience/loaded-skill-body/kv-cache-effect:
63
+ en: 1f6b842a95e14ce4
64
+ zh: 0d57cdec5e828828
65
+ /deepseek-ai-dsh-wecom/model-experience/cli-path:
66
+ en: b5fed52af6c0d771
67
+ zh: 25b7aa5297583030
68
+ /deepseek-ai-dsh-wecom/model-experience/cli-path/what-the-model-sees:
69
+ en: 44f38c8383be971a
70
+ zh: 5975e1948617e18b
71
+ /deepseek-ai-dsh-wecom/model-experience/cli-path/what-the-model-sees/runtime-context-entry:
72
+ en: c91314832f78f460
73
+ zh: aac156ea0b5b816a
74
+ /deepseek-ai-dsh-wecom/model-experience/cli-path/what-the-model-sees/runtime-context-entry-on-windows:
75
+ en: 54f899bbaf7ed198
76
+ zh: 31256473a192427b
77
+ /deepseek-ai-dsh-wecom/model-experience/cli-path/token-effect:
78
+ en: 2caf581d193f3dba
79
+ zh: 3b5e94d4cc69ca3b
80
+ /deepseek-ai-dsh-wecom/model-experience/cli-path/kv-cache-effect:
81
+ en: 67398dd4e4b02db9
82
+ zh: a873eacd006fa656
83
+ /deepseek-ai-dsh-wecom/known-limitations-and-deferred-work:
84
+ en: 7a9e3ee8135294ee
85
+ zh: a016e5b728757c1f
86
+ /deepseek-ai-dsh-wecom/known-limitations-and-deferred-work/dev-note:
87
+ en: 71cc23fc507e649e
88
+ zh: 3dbd0498845467cc
package/README.md CHANGED
@@ -1,3 +1,178 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: "Add the WeCom plugin to a profile: the official wecom-cli with its skills, and WeCom authorization on the Plugins page."
3
+ kind: "package-bundle"
4
+ ---
2
5
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
6
+ # @deepseek-ai/dsh-wecom
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ The WeCom plugin lets conversations use WeCom through the official `wecom-cli`. It installs a pinned `@wecom/cli`, gives the model the absolute path of its `wecom-cli` executable in runtime context, and registers one `wecom` skill whose guides are the official WeCom skills, downloaded from the CLI's GitHub repository. It registers the authorization with the [connector account registry](../../client/ui-connector-account/README.md), so the Plugins page shows it and can check it, bind a bot through the CLI's QR-code page, or cancel. The CLI keeps the bot credentials in its default configuration, which the user's own terminal shares. Only macOS and Windows x64 are supported.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ ### Install into a profile
29
+
30
+ Install the plugin from the Web sidebar's **Plugins** page or with the CLI:
31
+
32
+ ```sh
33
+ dsh plugin --profile web add @deepseek-ai/dsh-wecom
34
+ dsh plugin --profile web remove @deepseek-ai/dsh-wecom
35
+ ```
36
+
37
+ `@wecom/cli` ships its native binary in a platform package such as `@wecom/cli-darwin-arm64`, which installs without a build script. When no platform package matches the computer, or the executable is missing, the `wecom` row fails to load with an error that names the missing package or path.
38
+
39
+ ### What you get
40
+
41
+ After the plugin loads, one `wecom` skill joins the skill catalog. The agent loads it with the `skill` tool, opens the guide it needs, such as `wecomcli-doc` or `wecomcli-message`, with the file tools, and runs `wecom-cli` by that path through the ordinary Shell tools under the current sandbox and approval policy. When `wecom-cli auth show --status` reports no authorization, the agent asks the user to connect WeCom on the plugin page; it runs the CLI's own `auth init` only when the user asks to finish it in the conversation, and requests `sandbox_permissions` with a `justification` on the first attempt because the command writes outside the workspace. When a command returns `errcode` 853004 (`cli token expired`), the agent does not ask for a new authorization or pass on the server's upgrade advice: it reruns the command with `sandbox_permissions` and a `justification`, because in the file sandbox the CLI cannot save the token it just refreshed.
42
+
43
+ The guides come from `skills/` of `WecomTeam/wecom-cli` at commit `4c74ff2`. The row downloads that commit's archive when it loads and keeps the verified files in `$DSH_HOME/cache/wecom/`; until they are in place, the catalog has no `wecom` skill and the plugin page reports the download. A failed download is retried by the page's check.
44
+
45
+ Turning the plugin off in Plugin Manager withdraws the skills, the path from runtime context, and the authorization section. The CLI authorization and the downloaded guides stay in place.
46
+
47
+ <a id="account-operations"></a>
48
+ ### Authorization operations
49
+
50
+ The Plugins page drives these operations through the connector account registry, which the Web app loads; a headless profile loads the plugin without it. The Host runs at most one operation at a time and owns it, so leaving the page does not cancel it.
51
+
52
+ | Operation | Effect |
53
+ |---|---|
54
+ | `check` | Checks the authorization again; each browser that opens the Web app starts one when no operation runs |
55
+ | `connect` | Runs `auth init --noninteractive --no-browser`, waits for the user to scan the QR code, then checks that the CLI reports the bot authorized. The authorized section offers it again as changing the bot, after a confirmation, because the new binding replaces the one the terminal shares |
56
+ | Cancel | Cancels the connection while it waits for the scan and waits for its command to exit; other steps are ignored |
57
+
58
+ A check runs `auth show`. The authorization reads `authorized` or `unauthorized` from the CLI's `Status` line, and the bound bot's id from its `Bot ID` line, which the section shows when the CLI prints one; any other output or a nonzero exit fails the check and keeps the previous state. Each link that `auth init` prints alone on a stdout line is offered only when it is an HTTPS address on `work.weixin.qq.com`. Results report succeeded, cancelled, or failed. Failures show the command and the observed exit code on the page and in the Host log; the CLI's output, which can carry the QR-code session, is omitted. `wecom-cli` has no command that revokes the authorization, so the plugin offers no disconnect. The process running DSH needs access to the CLI configuration; `DSH_HOME` does not relocate it.
59
+
60
+ ### Configure
61
+
62
+ | Field | Default | Meaning |
63
+ |---|---|---|
64
+ | `binDir` | the installed `@wecom/cli-<platform>-<arch>` package's `bin` | Absolute directory containing an executable `wecom-cli`, `wecom-cli.exe` on Windows |
65
+ | `skillsDir` | none | Directory holding the files of `skills/` at their repository paths; when set, the guides are not downloaded |
66
+
67
+ An authorization check gets the `commandTimeoutMs` of the [`cli-account` row](../cli-account/README.md#use-this-package), 30 seconds by default. QR-code authorization waits up to 10 minutes for the user, and each command keeps at most 1 MiB of stdout; the CLI account Service fixes both limits. The guides are downloaded from the `skillsUrls` of the [`upstream-skills` row](../upstream-skills/README.md#use-this-package), each within its `skillsTimeoutMs`.
68
+
69
+ The generated [config catalog](../../../docs/config-catalog.md#deepseek-aidsh-wecom) is the exhaustive source of supported fields.
70
+
71
+ -----
72
+
73
+ <a id="understand-the-implementation"></a>
74
+ ## Understand the implementation
75
+
76
+ <details>
77
+ <summary>Implementation internals — click to expand</summary>
78
+
79
+ [`cordis.patch.yml`](cordis.patch.yml) inserts this package as the `wecom` row after the profile's other layers, and the Plugins page keys the authorization section by this package name. [`src/index.ts`](src/index.ts) is a function plugin. It checks that `binDir/wecom-cli` (`wecom-cli.exe` on Windows) is executable, registers the `wecom` skill with `ctx.upstreamSkills` under the pin in [`src/skills.ts`](src/skills.ts), and registers that path and the authorization with `ctx.cliAccounts`. The account view carries the download state, and each check restarts a failed download without waiting for it. [`src/directory.ts`](src/directory.ts) resolves the platform package that `@wecom/cli` installs as an optional dependency. The [CLI account Service](../cli-account/README.md) gives the model that path in runtime context, runs each command by the same path, runs one operation at a time, and reports a failed command by its exit code. [`src/account.ts`](src/account.ts) carries out each operation with the WeCom commands and reads the QR-code link from the output lines of `auth init`. [`src/presentation.ts`](src/presentation.ts) maps each view to the section the registry serves, in the text of [`src/locales.ts`](src/locales.ts). Disposal cancels the active operation, aborts running commands, and settles after their processes exit.
80
+
81
+ [`skills/wecom/SKILL.md`](skills/wecom/SKILL.md) is the only skill this package carries: the DSH guidance, an index of the guides, and how to open them. Upstream publishes the guides only in its repository and not in the npm package, so the [upstream skills Service](../upstream-skills/README.md) downloads them; they are files under the skill's base directory, not separate skills. Where the DSH guidance and `wecomcli-shared` disagree, the entry tells the agent to follow the DSH guidance: it uses the plugin's `wecom-cli` instead of installing one, and sends authorization to the plugin page. References are ordinary files in each guide's directory.
82
+
83
+ </details>
84
+
85
+ -----
86
+
87
+ <a id="further-exploration"></a>
88
+ ## Further Exploration
89
+
90
+ - [Connector packages](../README.md) — the group this application plugin belongs to.
91
+ - [CLI account Service](../cli-account/README.md) — command execution, the CLI path context, and account operations shared by CLI app plugins.
92
+ - [Upstream skills Service](../upstream-skills/README.md) — download, verification, and publication of the guides.
93
+ - [Skills](../../../docs/subsystems/skills.md) — catalog publication, loading, and precedence.
94
+ - [Connector account surfaces](../../client/ui-connector-account/README.md) — the registry and the Plugins page section that drive the authorization operations.
95
+
96
+ -----
97
+
98
+ <a id="model-experience"></a>
99
+ ## Model Experience
100
+
101
+ ### Skill catalog entries
102
+
103
+ #### What the model sees
104
+
105
+ The skill catalog lists one `wecom` skill. Its Chinese description names the WeCom features it covers and tells the agent to load it, then read the matching guide, whenever the user mentions WeCom or those features or gives a `doc.weixin.qq.com` or `drive.weixin.qq.com` link.
106
+
107
+ #### Token effect
108
+
109
+ The entry stays in context while the plugin is loaded. Its name and description total about 160 characters.
110
+
111
+ #### KV Cache effect
112
+
113
+ The catalog is fixed for one plugin version. Loading or unloading the plugin changes the catalog, which is republished as a new message and leaves earlier context in place.
114
+
115
+ ### Loaded skill body
116
+
117
+ #### What the model sees
118
+
119
+ A `skill` tool result for `wecom` contains about 2,300 characters: the DSH guidance, an index that gives each of the 15 guides one sentence with the upstream routing rules, and how to open a guide. The DSH guidance tells the agent to run the plugin's `wecom-cli` by the absolute path from the current runtime context, to ask the user to connect on the plugin page before running `auth init --noninteractive` itself, to request `sandbox_permissions` for that command from its first attempt, and to rerun a command that returned `errcode` 853004 with `sandbox_permissions` instead of asking for a new authorization or passing on the server's upgrade advice, asking for a new authorization only when the rerun returns 853004 again; it takes precedence over `wecomcli-shared` where they disagree. Its resource base is the downloaded directory, `skillsDir` or `$DSH_HOME/cache/wecom/skills-<digest>`, so the agent opens `skills/<name>/SKILL.md` with the file tools rather than the `skill` tool, treats a skill the guides name as that guide, and resolves a guide's relative paths against the guide's own directory.
120
+
121
+ #### Token effect
122
+
123
+ Each load adds the entry body to the retained tool history. Guides and their reference files arrive as ordinary file-read output.
124
+
125
+ #### KV Cache effect
126
+
127
+ Loading appends a tool result and does not rewrite earlier context.
128
+
129
+ ### CLI path
130
+
131
+ #### What the model sees
132
+
133
+ While the row is loaded, the [CLI account Service](../cli-account/README.md#model-experience) adds one required runtime-context entry with the path of `wecom-cli` in `binDir`, which defaults to the `bin` directory of the platform package that `@wecom/cli` installs. The second line covers the guide scripts that call `wecom-cli` by name, such as `build_page.py`.
134
+
135
+ ##### Runtime-context entry
136
+
137
+ ```markdown
138
+ WeCom CLI: run `wecom-cli` by its absolute path "<binDir>/wecom-cli"; the bare name may resolve to another installation or to none.
139
+ Scripts in the WeCom skill call `wecom-cli` by name; prefix only the commands that run them with PATH="<binDir>:$PATH", and never export PATH or run `wecom-cli` by name yourself.
140
+ ```
141
+
142
+ ##### Runtime-context entry on Windows
143
+
144
+ ```markdown
145
+ WeCom CLI: run `wecom-cli` by its absolute path with the call operator, & '<binDir>\wecom-cli.exe'; the bare name may resolve to another installation or to none.
146
+ Scripts in the WeCom skill call `wecom-cli` by name; start only the commands that run them with $env:PATH = '<binDir>;' + $env:PATH, and never run `wecom-cli` by name yourself.
147
+ ```
148
+
149
+ #### Token effect
150
+
151
+ Two lines of about 280 characters plus the path and its directory in each runtime-context snapshot.
152
+
153
+ #### KV Cache effect
154
+
155
+ The system prompt does not change; loading or unloading the row, or a changed path, appends one runtime-context snapshot.
156
+
157
+ ## Known Limitations and Deferred Work
158
+
159
+ <a id="known-limitations-and-deferred-work"></a>
160
+
161
+ - Only macOS and Windows x64 are supported; other platforms are unverified. `@wecom/cli` publishes no Windows arm64 package.
162
+ - Commands must run on this Host. When a composition runs them elsewhere, such as over SSH, the plugin still loads, and each command that runs `wecom-cli` fails because the path does not exist there.
163
+ - The plugin uses the CLI's default configuration. Authorizing from DSH affects the user's own terminal, and there is no DSH-private bot or bot picker. `wecom-cli` cannot revoke the authorization, so neither the page nor turning the plugin off removes it; the page can only replace the bound bot with another one.
164
+ - Connection reads the QR-code link from the plain-text output of `auth init --noninteractive --no-browser`; a CLI version that changes that output fails the connection with a retryable result.
165
+ - The guides follow upstream commit `4c74ff2`; updating them means a new pin from `scripts/upstream-skills-digest.ts`, after which the entry's index and DSH guidance must be checked against the new guides.
166
+ - The first load after a new pin needs access to GitHub or a configured mirror; until a download succeeds, the agent has no `wecom` skill.
167
+ - The downloaded guides stay in `$DSH_HOME/cache/wecom/` after the plugin is removed or pins another commit.
168
+ - In the file sandbox, `wecom-cli` reads the saved authorization without writing, so commands run there until the saved token expires. It then cannot save the refreshed token in its configuration directory outside the workspace, and the command returns `errcode` 853004 with the server's upgrade advice. Rerunning that command needs one single-command approval, after which commands run in the sandbox again until the next expiry. The page's check reads only local state and does not refresh the token.
169
+
170
+ <a id="dev-note"></a>
171
+ ### Dev Note
172
+
173
+ <details>
174
+ <summary>Working context for maintainers — click to expand</summary>
175
+
176
+ The guides keep upstream whitespace, including trailing spaces that mark Markdown line breaks, and no whitespace exemption covers them: a commit that adds upstream lines with trailing whitespace fails the pre-commit `git diff --cached --check`. Specs and the `wecom-skills` session snapshot use stand-in executables through `binDir`.
177
+
178
+ </details>
package/README.zh.md ADDED
@@ -0,0 +1,178 @@
1
+ ---
2
+ description: "把企业微信插件加入 profile:官方 wecom-cli 及其技能,以及插件页上的企业微信授权。"
3
+ kind: "package-bundle"
4
+ ---
5
+
6
+ # @deepseek-ai/dsh-wecom
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ 企业微信插件让对话通过官方 `wecom-cli` 使用企业微信。它安装固定版本的 `@wecom/cli`,在运行时上下文中把其 `wecom-cli` 可执行文件的绝对路径告诉模型,并注册一个 `wecom` skill,其子指南是官方企业微信技能,从该 CLI 的 GitHub 仓库下载。它把授权注册到 [连接器账号注册表](../../client/ui-connector-account/README.zh.md),插件页因此能显示授权,并检查授权、通过 CLI 的扫码页面绑定机器人,或取消操作。CLI 把机器人凭据保存在默认配置中,与用户自己的终端共用。仅支持 macOS 和 Windows x64。
13
+
14
+ ## 目录
15
+
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
27
+
28
+ ### 安装到 profile
29
+
30
+ 在 Web 侧栏的**插件**页面安装,或使用 CLI:
31
+
32
+ ```sh
33
+ dsh plugin --profile web add @deepseek-ai/dsh-wecom
34
+ dsh plugin --profile web remove @deepseek-ai/dsh-wecom
35
+ ```
36
+
37
+ `@wecom/cli` 把原生程序放在 `@wecom/cli-darwin-arm64` 等平台包中,这些包安装时不运行构建脚本。没有与本机匹配的平台包或可执行文件缺失时,`wecom` 行会加载失败,并给出缺失的包名或路径。
38
+
39
+ ### 获得的能力
40
+
41
+ 插件加载后,一个 `wecom` skill 进入 skill 目录。agent 用 `skill` 工具加载它,用文件工具打开所需的子指南(例如 `wecomcli-doc` 或 `wecomcli-message`),并在当前沙箱与审批策略下通过普通 Shell 工具按这个路径运行 `wecom-cli`。`wecom-cli auth show --status` 报告未授权时,agent 会请用户到插件页连接企业微信;只有用户要求在对话中完成时,才运行 CLI 自带的 `auth init`,并且因为该命令会写入工作区之外,第一次尝试就带 `justification` 申请 `sandbox_permissions`。命令返回 `errcode` 853004(`cli token expired`)时,agent 不会请用户重新授权,也不会转述服务端的升级建议,而是带 `sandbox_permissions` 和 `justification` 重跑同一条命令,因为在文件沙箱下 CLI 保存不了刚换到的 token。
42
+
43
+ 子指南来自 `WecomTeam/wecom-cli` 在提交 `4c74ff2` 时的 `skills/`。该行加载时下载这个提交的归档,并把校验后的文件保存在 `$DSH_HOME/cache/wecom/`;文件就位之前,skill 目录中没有 `wecom` skill,插件页会报告下载状态。下载失败时,由插件页的检查重试。
44
+
45
+ 在 Plugin Manager 中关闭插件会撤下 skill、运行时上下文中的路径和授权区块,CLI 的授权和已下载的子指南保持不变。
46
+
47
+ <a id="account-operations"></a>
48
+ ### 授权操作
49
+
50
+ 插件页通过 连接器账号注册表发起这些操作,注册表由 Web 应用加载;headless profile 加载插件时没有它。Host 同一时间最多运行一个操作并持有它,因此离开页面不会取消操作。
51
+
52
+ | 操作 | 作用 |
53
+ |---|---|
54
+ | `check` | 重新检查授权;没有操作运行时,每个打开 Web 应用的浏览器会触发一次 |
55
+ | `connect` | 运行 `auth init --noninteractive --no-browser`,等待用户扫码,然后确认 CLI 报告机器人已授权。已授权的区块以“更换机器人”再次提供它,需先确认,因为新绑定会替换终端共用的那一个 |
56
+ | 取消 | 在等待扫码期间取消连接并等待其命令退出;其他步骤会被忽略 |
57
+
58
+ 检查运行 `auth show`。授权状态从 CLI 输出的 `Status` 行读作 `authorized` 或 `unauthorized`,CLI 打印 `Bot ID` 行时,从中读取已绑定机器人的 id 并显示在区块中;其他输出或非零退出码会使检查失败,并保留之前的状态。`auth init` 在 stdout 中单独一行打印的链接,只有是 `work.weixin.qq.com` 上的 HTTPS 地址时才会提供。结果分为成功、已取消和失败。失败时,页面和 Host 日志显示命令和观察到的退出码;CLI 的输出可能带有扫码会话,因此不保留。`wecom-cli` 没有撤销授权的命令,因此插件不提供断开连接。运行 DSH 的进程需要能访问 CLI 配置;`DSH_HOME` 不会迁移它。
59
+
60
+ ### 配置
61
+
62
+ | 字段 | 默认值 | 含义 |
63
+ |---|---|---|
64
+ | `binDir` | 已安装 `@wecom/cli-<platform>-<arch>` 包的 `bin` | 包含可执行 `wecom-cli`(Windows 上为 `wecom-cli.exe`)的绝对目录 |
65
+ | `skillsDir` | 无 | 按仓库路径存放 `skills/` 文件的目录;设置后不下载子指南 |
66
+
67
+ 授权检查使用 [`cli-account` 行](../cli-account/README.zh.md#use-this-package)的 `commandTimeoutMs`,默认 30 秒。扫码授权最多等待用户 10 分钟,每条命令最多保留 1 MiB 的 stdout;这两个上限由 CLI 账号 Service 固定。子指南从 [`upstream-skills` 行](../upstream-skills/README.zh.md#use-this-package)的 `skillsUrls` 下载,每个前缀的时限是该行的 `skillsTimeoutMs`。
68
+
69
+ 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-wecom)是受支持字段的完整来源。
70
+
71
+ -----
72
+
73
+ <a id="understand-the-implementation"></a>
74
+ ## 理解实现
75
+
76
+ <details>
77
+ <summary>实现内部机制——点击展开</summary>
78
+
79
+ [`cordis.patch.yml`](cordis.patch.yml) 在 profile 其他层之后把本包作为 `wecom` 行插入,插件页以本包名作为授权区块的 key。[`src/index.ts`](src/index.ts) 是一个函数插件。它检查 `binDir/wecom-cli`(Windows 上为 `wecom-cli.exe`)是否可执行,按 [`src/skills.ts`](src/skills.ts) 中的固定信息把 `wecom` skill 注册到 `ctx.upstreamSkills`,并把这个路径和授权注册到 `ctx.cliAccounts`。账号视图携带下载状态,每次检查都会在不等待的情况下重新开始失败的下载。[`src/directory.ts`](src/directory.ts) 定位 `@wecom/cli` 作为可选依赖安装的平台包。[CLI 账号 Service](../cli-account/README.zh.md) 在运行时上下文中把这个路径告诉模型,按同一路径运行每条命令,一次执行一个操作,并以退出码报告失败的命令。[`src/account.ts`](src/account.ts) 用企业微信的命令完成每个操作,并从 `auth init` 的输出行中读取扫码链接。[`src/presentation.ts`](src/presentation.ts) 用 [`src/locales.ts`](src/locales.ts) 中的文案,把每个视图映射为注册表提供的区块。释放时取消进行中的操作,中止正在运行的命令,并在这些进程退出后完成。
80
+
81
+ [`skills/wecom/SKILL.md`](skills/wecom/SKILL.md) 是本包携带的唯一 skill:DSH 指引、子指南索引和打开方式。上游只在其仓库发布这些子指南,没有放进 npm 包,因此由[上游技能 Service](../upstream-skills/README.zh.md) 下载;它们是 skill 基础目录下的文件,不是独立的 skill。DSH 指引与 `wecomcli-shared` 不一致时,总入口要求 agent 以 DSH 指引为准:使用插件提供的 `wecom-cli`,不再自行安装,并把授权引导到插件页。引用文件是每个子指南目录中的普通文件。
82
+
83
+ </details>
84
+
85
+ -----
86
+
87
+ <a id="further-exploration"></a>
88
+ ## 进一步探索
89
+
90
+ - [Connector 包](../README.zh.md)——这个应用插件所属的分组。
91
+ - [CLI 账号 Service](../cli-account/README.zh.md)——CLI 应用插件共用的命令执行、CLI 路径上下文与账号操作。
92
+ - [上游技能 Service](../upstream-skills/README.zh.md)——子指南的下载、校验与发布。
93
+ - [Skill](../../../docs/subsystems/skills.zh.md)——目录发布、加载与优先级。
94
+ - [连接器账号界面](../../client/ui-connector-account/README.zh.md)——发起授权操作的注册表和插件页区块。
95
+
96
+ -----
97
+
98
+ <a id="model-experience"></a>
99
+ ## 模型体验
100
+
101
+ ### Skill 目录条目
102
+
103
+ #### 模型看到什么
104
+
105
+ skill 目录只列出一个 `wecom` skill。其中文描述列出它覆盖的企业微信功能,并要求 agent 在用户提到企业微信或这些功能、或给出 `doc.weixin.qq.com`、`drive.weixin.qq.com` 链接时加载它,再读取对应的子指南。
106
+
107
+ #### Token 影响
108
+
109
+ 插件加载期间这一条目一直留在上下文中。其名称与描述合计约 160 个字符。
110
+
111
+ #### KV Cache 影响
112
+
113
+ 同一插件版本的目录固定不变。加载或卸载插件会改变目录,目录作为新消息重新发布,不改动更早的上下文。
114
+
115
+ ### 已加载的 skill 正文
116
+
117
+ #### 模型看到什么
118
+
119
+ `wecom` 的 `skill` 工具结果约 2,300 个字符:DSH 指引、为 15 个子指南各写一句话并保留上游分流规则的索引,以及打开子指南的方式。DSH 指引要求 agent 按当前运行时上下文给出的绝对路径运行插件提供的 `wecom-cli`,先请用户到插件页连接,再考虑自行运行 `auth init --noninteractive`,第一次运行该命令就申请 `sandbox_permissions`,命令返回 `errcode` 853004 时带 `sandbox_permissions` 重跑同一条命令,而不是请用户重新授权或转述服务端的升级建议,重跑后仍返回 853004 才请用户重新授权;与 `wecomcli-shared` 不一致时以它为准。其资源根目录是下载目录,即 `skillsDir` 或 `$DSH_HOME/cache/wecom/skills-<摘要>`,因此 agent 用文件工具而不是 `skill` 工具打开 `skills/<name>/SKILL.md`,把子指南按名字提到的技能当作对应子指南,并按子指南自己的目录解析其中的相对路径。
120
+
121
+ #### Token 影响
122
+
123
+ 每次加载把总入口正文加入保留的工具历史。子指南及其引用文件作为普通的文件读取输出返回。
124
+
125
+ #### KV Cache 影响
126
+
127
+ 加载会追加一条工具结果,不改写更早的上下文。
128
+
129
+ ### CLI 路径
130
+
131
+ #### 模型看到什么
132
+
133
+ 该行加载期间,[CLI 账号 Service](../cli-account/README.zh.md#model-experience) 添加一条必需的运行时上下文,给出 `binDir` 中 `wecom-cli` 的路径;`binDir` 默认是 `@wecom/cli` 安装的平台包的 `bin` 目录。第二行针对按名称调用 `wecom-cli` 的子指南脚本,例如 `build_page.py`。
134
+
135
+ ##### 运行时上下文条目
136
+
137
+ ```markdown
138
+ WeCom CLI: run `wecom-cli` by its absolute path "<binDir>/wecom-cli"; the bare name may resolve to another installation or to none.
139
+ Scripts in the WeCom skill call `wecom-cli` by name; prefix only the commands that run them with PATH="<binDir>:$PATH", and never export PATH or run `wecom-cli` by name yourself.
140
+ ```
141
+
142
+ ##### Windows 上的运行时上下文条目
143
+
144
+ ```markdown
145
+ WeCom CLI: run `wecom-cli` by its absolute path with the call operator, & '<binDir>\wecom-cli.exe'; the bare name may resolve to another installation or to none.
146
+ Scripts in the WeCom skill call `wecom-cli` by name; start only the commands that run them with $env:PATH = '<binDir>;' + $env:PATH, and never run `wecom-cli` by name yourself.
147
+ ```
148
+
149
+ #### Token 影响
150
+
151
+ 每份运行时上下文快照中两行,约 280 个字符加上路径及其目录。
152
+
153
+ #### KV Cache 影响
154
+
155
+ 系统提示词不变;加载或卸载该行、或路径变化时,追加一份运行时上下文快照。
156
+
157
+ ## 已知限制与延期工作
158
+
159
+ <a id="known-limitations-and-deferred-work"></a>
160
+
161
+ - 仅支持 macOS 和 Windows x64;其他平台未经验证。`@wecom/cli` 没有发布 Windows arm64 平台包。
162
+ - 命令必须在本 Host 上运行。组合把命令放到别处运行(例如通过 SSH)时,插件仍会加载,但每条运行 `wecom-cli` 的命令都会因为那里没有这个路径而失败。
163
+ - 插件使用 CLI 的默认配置。在 DSH 中授权会影响用户自己的终端,没有 DSH 私有机器人或机器人选择器。`wecom-cli` 无法撤销授权,因此页面和关闭插件都不会移除它;页面只能把已绑定的机器人换成另一个。
164
+ - 连接从 `auth init --noninteractive --no-browser` 的纯文本输出中读取扫码链接;CLI 版本改变该输出时,连接以可重试的结果失败。
165
+ - 子指南跟随上游提交 `4c74ff2`;更新时要用 `scripts/upstream-skills-digest.ts` 生成新的固定信息,之后按新的子指南核对总入口的索引和 DSH 指引。
166
+ - 换用新的固定提交后,首次加载需要能访问 GitHub 或配置的镜像;下载成功之前,agent 没有 `wecom` skill。
167
+ - 插件卸载或改为固定其他提交后,已下载的子指南仍留在 `$DSH_HOME/cache/wecom/`。
168
+ - 在文件沙箱下,`wecom-cli` 读取已保存的授权时不需要写入,所以在已保存的 token 过期之前命令可以直接运行。token 过期后,CLI 无法把刚换到的 token 保存到工作区之外的配置目录,命令会返回 `errcode` 853004 和服务端的升级建议。重跑这条命令需要一次单条命令审批,之后命令又可以在沙箱中运行,直到下一次过期。页面的检查只读取本地状态,不会刷新 token。
169
+
170
+ <a id="dev-note"></a>
171
+ ### 开发备注
172
+
173
+ <details>
174
+ <summary>维护者工作上下文——点击展开</summary>
175
+
176
+ 子指南保留上游的空白,包括表示 Markdown 换行的行尾空格,且没有任何空白豁免:新增带行尾空白的上游行的提交,会被 pre-commit 的 `git diff --cached --check` 拒绝。单测与 `wecom-skills` 会话快照通过 `binDir` 使用替身可执行文件。
177
+
178
+ </details>
@@ -0,0 +1,3 @@
1
+ - insert:
2
+ - id: wecom
3
+ name: '@deepseek-ai/dsh-wecom'
package/docs/DETAIL.md ADDED
@@ -0,0 +1 @@
1
+ ![The authorized WeCom section on the plugin page and a conversation that adds a WeCom to-do](preview.svg)
@@ -0,0 +1 @@
1
+ ![插件页上已授权的企业微信,以及在对话中添加企业微信待办](preview.zh.svg)