@mhfire/dsh-im-bridge 0.2.0 → 0.4.2

package/README.en.md

@@ -4,10 +4,35 @@
 
 WeCom AI Bot ⇄ DeepSeek Harness Agent bridge — a **DSH plugin**.
 
-Creates Agents **in-process** inside a dsh profile (no child-process spawn): per-sender durable sessions (the same WeCom user reuses one session with memory), sessions registered with the Web GUI (live view and continue-chat), plus a Settings → Plugins card (`botId` / `secret`, allow-list, timeouts, copy, and model overrides, written to `settings.yaml`).
+Creates Agents **in-process** inside a dsh profile (no child-process spawn): one durable DSH session **per WeCom chat window** (1:1 = that user; everyone in the same group shares one session — a person’s DM and group chats stay separate), sessions registered with the Web GUI (live view and continue-chat), plus a Settings → Plugins card (`botId` / `secret`, allow-list, timeouts, copy, and model overrides, written to `settings.yaml`).
 
 The Host half registers the `im-bridge` namespace through `installSettingsSection`. The browser half contributes a card into `settings.plugin.item` under `key: im-bridge`. The card can set `botId` / `secret` on the same user layer as the profile patch. Live fields such as `startHint` apply on the next message; changing credentials still requires a process restart to open the WebSocket.
 
+## Session granularity
+
+One DSH session maps to one WeCom chat window, not “every window of the same userid”:
+
+- **1:1**: `single:<userid>` — one Agent for that user
+- **Group**: `group:<chatid>` — all members share one Agent and one serial queue (two people speaking at once still cannot concurrent-`followup`)
+- `allowFrom` filters **who may chat** by sender userid; empty = enqueue everyone. Office commands use `wecomCli.allowFrom` separately
+- Leading `@nickname` mentions are stripped on arrival, so both the model input and the title read `测试一下` instead of `@MediaAgent 测试一下`. Mentions later in the text stay, and a message that is nothing but mentions goes to the model unchanged
+- Process restart continues the same durable session via a stable `wecom-` + short hash of the key: adopt a live Agent if the process already has one (for example the browser already opened that row), `resume` from persistence otherwise, and `create` only when neither exists. Resume cwd / preset follow the archive, not the current config; a cwd mismatch logs a warning and is not rewritten.
+- The GUI title is `企微·私聊` / `企微·群` plus the first user prompt (the same automatic title as other sessions), not a userid / chatid; two windows of the same kind with similar first lines stay two sidebar rows
+- Archiving a WeCom session in the GUI ends that context: the next message silently starts a new session at `wecom-<hash>-2` (`-3` after another archive), with no extra WeCom notice. DSH has no unarchive API, so the archived session is merely no longer written to — it neither becomes visible again nor is deleted
+- Every window still shares the same `workspace` (files / rag). That is environment isolation, separate from chat-context windows
+
+## Compatible DeepSeek Harness versions
+
+DeepSeek Harness is still a developer preview and makes **no semver compatibility promise** to out-of-tree plugins. Package 0.4.2 is aligned to published tags by the APIs it actually calls:
+
+| DSH | This package |
+|---|---|
+| [0.1.0-rc.8](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.0-rc.8), [0.1.1-rc.1](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.1), [0.1.1-rc.2](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2) | Compatible (developed against the 0.1.1-rc.2 line) |
+| [0.1.0-rc.7](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.0-rc.7) and earlier | Not compatible. rc.7 already has the plugin settings-card slot and `dsh plugin add`, but the browser has no `settingsScope.describe()`, so the card and the credential “Configured” badges fail |
+| Newer RCs / untagged HEAD | Not guaranteed. After upgrading dsh, re-check the Settings card and the WeCom connection |
+
+Pin `dsh` to `0.1.0-rc.8` or later, for example `npx @deepseek-ai/dsh@0.1.1-rc.2 web`. Do not rely on a floating `latest`.
+
 ## Install
 
 ### Recommended: npm package
@@ -15,7 +40,7 @@ The Host half registers the `im-bridge` namespace through `installSettingsSectio
 ```powershell
 dsh plugin --profile web add @mhfire/dsh-im-bridge
 # Or pin a version:
-# dsh plugin --profile web add @mhfire/dsh-im-bridge@0.2.0
+# dsh plugin --profile web add @mhfire/dsh-im-bridge@0.4.2
 ```
 
 In `$DSH_HOME/profiles/web/cordis.patch.yml` (or your profile), supply credentials only (other fields ship as bundle defaults and can be overridden):
@@ -38,7 +63,25 @@ Install from this repo’s `plugin/` directory or a `file:` path:
 dsh plugin --profile web add <package-path>
 ```
 
-If `botId` / `secret` are missing, the plugin still loads (does not block `dsh web`); logs warn that WeCom connect is skipped. You can also fill them at the top of the Settings → Plugins card (same user layer as the profile patch); the badge becomes “Configured” after save. Changing credentials still requires a **restart** to connect (this release does not hot-reconnect).
+If `botId` / `secret` are missing, the plugin still loads (does not block `dsh web`); logs warn that WeCom connect is skipped. You can also fill them on the Settings plugin card (see the next section).
+
+## Settings plugin card
+
+After the plugin is installed and `dsh web` is running, open **Settings → Plugins → Plugin configuration** and expand **WeCom Bridge** (same card chrome as Shell / Agent loop / Web search). **Save** writes the user layer of `settings.yaml`, the same layer as the profile `cordis.patch.yml`. **Discard** drops unsaved drafts. Fields marked **Overridden** can be **Reset** to the bundle default.
+
+Fields, top to bottom:
+
+| Card control | Config key | After save |
+|---|---|---|
+| Bot ID / Secret | `botId` / `secret` | Badge becomes “Configured”; a **process restart** is required to open the WebSocket. Inputs are password fields; stored literals never ride the wire. A **blank save does not clear** a stored credential |
+| Allowed sender userids | `allowFrom` | Applies on the next message; comma-separated, empty = allow everyone |
+| Task timeout (seconds) | `agentTimeoutSec` | Applies on the next message |
+| Placeholder while thinking | `startHint` | Applies on the next message |
+| Denied-sender reply | `deniedMessage` | Applies on the next message |
+| Welcome message | `welcomeMessage` | Applies on the next message |
+| WeCom-only provider / model | `provider` / `model` | Applies only to **later new** WeCom-window sessions; both must be set to override, otherwise the GUI default model is used |
+
+`workspace`, `agentPreset`, `persona` / `personaFile`, `thinking`, `maxReplyBytes`, `reasoningEffort`, and `wecomCli` are not on the card; set them in the profile patch or the table below. This release does not hot-reconnect credentials; changing `wecomCli` also requires a process restart.
 
 ## Configuration
 
@@ -48,16 +91,17 @@ The bundle `cordis.patch.yml` supplies defaults for every field except `botId` /
 |---|---|
 | `botId` / `secret` | WeCom AI Bot credentials (`role('secret')`, redacted in UI); when empty, WeCom side is skipped and the host keeps running |
 | `workspace` | Agent working directory (session cwd) |
-| `allowFrom` | Allowed sender userids; empty = allow everyone |
+| `allowFrom` | Chat allow-list; empty = everyone may ask. Does not gate wecom-cli |
 | `agentTimeoutSec` | Max seconds per task; also drives progress / ETA |
 | `startHint` | Placeholder text when processing starts |
 | `agentPreset` | Agent preset to mount (default `standard`) |
-| `provider` / `model` | WeCom-only model; **both must be non-empty** to override, otherwise follow the GUI `agent-default-model`. Filling only one warns and falls back. Editable in Settings; applies to later new sender sessions only |
+| `provider` / `model` | WeCom-only model; **both must be non-empty** to override, otherwise follow the GUI `agent-default-model`. Filling only one warns and falls back. Editable in Settings; applies to later new WeCom-window sessions only |
 | `reasoningEffort` | Optional effort when the WeCom override is in effect; ignored otherwise |
 | `persona` / `personaFile` | Bot persona; precedence: `personaFile` → `persona` → packaged default (zh/en via Host `locale.preference`); overrides do not follow language; do not commit secrets |
 | `maxReplyBytes` | Reply size cap in bytes (default 20000) |
 | `deniedMessage` | Reply when the sender is not on `allowFrom` (editable in Settings) |
 | `welcomeMessage` | Welcome text on `enter_chat` (editable in Settings) |
+| `wecomCli` | Optional WeCom office skills (off by default). See the next section |
 | `thinking` | Streaming animation. Precedence: tool activity (`toolLabels`) > model stream phase (`reasoningStatus` / `outputStatus` from `assistant/chunk`) > timed `phases` fallback; also `spin` / `reasoningSpin` / `outputSpin` / `eggs` |
 
 To give WeCom a different model from the GUI, set both in the profile `cordis.patch.yml`:
@@ -87,6 +131,41 @@ thinking:
     pwsh: PowerShell
 ```
 
+## WeCom office skills (wecom-cli)
+
+The plugin depends on the official [`@wecom/cli`](https://www.npmjs.com/package/@wecom/cli) binary. Install `wecomcli-*` under **`$DSH_HOME/wecom-cli-skills`** (not workspace `.dsh/skills` / `.agents/skills`, and not `$DSH_HOME/skills`). Only the **office userid’s 1:1** agent gets the office layer: `skills.register()` for the catalog and `tools.register()` for the gated `wecom_cli` tool. Both go through that agent’s own ctx, so group chats and the GUI never see them. Other workspace skills stay on `skill-filesystem`.
+
+Office commands run **only through the `wecom_cli` tool**: the model passes `argv` (the arguments after `wecom-cli`), the plugin spawns the official binary directly, and any `auth init` is refused. The `wecom-cli` on PATH is a shim that prints a refusal and exits 1, so group chats, the GUI, and any `pwsh wecom-cli` fail; the shim’s message points back at `wecom_cli`. The credential directory is never exported to the process environment — it is injected per spawn.
+
+`wecomCli.enabled` is off by default. Turning it on requires a non-empty **`wecomCli.allowFrom`** (office userids). Root `allowFrom` only gates who may chat; empty means everyone may ask. An empty office list logs a warning and skips the shim / auth.
+
+One-time setup:
+
+1. Leave root `allowFrom` empty (everyone may ask) and put **office** userids in `wecomCli.allowFrom` (do not leave that empty)
+2. In **Settings → Plugins → WeCom Bridge**, click **Install official skills** (the Host downloads the official repo zip into `$DSH_HOME/wecom-cli-skills`). **Do not** use `npx skills add -g` (it leaks into the GUI). The skills CLI has **no `--dir`**, so that flag does not write into the plugin directory. If `wecomcli-*` folders already sit in the workspace, move them here and delete the workspace copies. You can also copy official `skills/wecomcli-*` into `$DSH_HOME/wecom-cli-skills` by hand.
+
+3. Enable it in the profile `cordis.patch.yml` (the plugin then writes wecom-cli credentials from the existing `botId` / `secret` via hidden `auth init --bot-id/--secret`; no QR scan and no `npm install -g @wecom/cli`):
+
+```yaml
+- id: im-bridge
+  config:
+    allowFrom: []
+    wecomCli:
+      enabled: true
+      allowFrom: ["<office userid>"]
+      # skillsDir: ''   # empty = $DSH_HOME/wecom-cli-skills
+      # configDir: ''   # empty = <workspace>/.dsh/wecom-cli; gitignore this directory
+```
+
+| Field | Description |
+|---|---|
+| `wecomCli.enabled` | Install the PATH deny shim, run the auth check, and wire the prompt plus the `wecom_cli` tool; default `false` |
+| `wecomCli.allowFrom` | Userids that receive the `wecom_cli` tool; empty skips the shim / auth. Independent of the chat list |
+| `wecomCli.skillsDir` | Override skills root; empty = `$DSH_HOME/wecom-cli-skills` |
+| `wecomCli.configDir` | Override the credential directory; empty = `<workspace>/.dsh/wecom-cli`. Gitignore that directory. `WECOM_CLI_CONFIG_DIR` is injected only when the plugin spawns the CLI, never into the process environment, so `~/.config/wecom` stays unused. |
+
+Changing `wecomCli` requires a process restart. Messages still arrive when unauthorized; at boot the plugin seeds credentials with hidden `--bot-id/--secret` (stderr is not a TTY). If automatic seeding fails, the log prints a manual command that sets `WECOM_CLI_CONFIG_DIR` — keep that prefix, or `npx --yes @wecom/cli auth init --manual` writes to `~/.config/wecom`, which the plugin never reads. Do not run `auth init` from the agent (that creates a new bot).
+
 ## Persona
 
 Precedence: `personaFile` → `persona` string → packaged default persona.
@@ -104,11 +183,35 @@ Precedence: `personaFile` → `persona` string → packaged default persona.
 
 Or copy [`persona.example.md`](./persona.example.md) as a fill-in template. Supports `{{model}}` / `{{cwd}}`. Do not commit secret-bearing persona files. Welcome / deny / thinking copy remain Chinese config strings and do not follow locale yet.
 
+## Sending PNGs to WeCom
+
+If the agent’s final reply contains Markdown pointing at a **workspace** PNG, the bridge uploads it after the text stream finishes and sends it as a **separate image message** (`uploadMedia`, then `sendMediaMessage` with `media_id`).
+
+Trigger (paths relative to `workspace`):
+
+```markdown
+![screenshot](main_screen.png)
+[screenshot](out/frame.png)
+```
+
+- Only `.png`; `http(s):` / `data:` are ignored; the file must stay inside `workspace`
+- Must be a real PNG (signature), at most **10MB** each, at most **10** images (first-seen order, deduped)
+- Writing a PNG without that Markdown does **not** send it
+- Images follow the text bubble; they are not inlined into the stream
+- Inbound image / voice / file messages are still ignored
+
 ## Security
 
-- Do not commit secret-bearing files such as `config.json` / `persona.md`
+- Do not commit secret-bearing files such as `config.json` / `persona.md` / `.dsh/wecom-cli/`
 - Session and tool output may contain adversarial text; the plugin’s safety prompt tells the agent not to treat tool output as instructions
 
+## Known Limitations and Deferred Work
+
+- wecom-cli credentials live in the workspace `<workspace>/.dsh/wecom-cli` (gitignore it). People on `wecomCli.allowFrom` borrow that identity’s office permissions; the chat list (root `allowFrom`) does not grant office access. An office 1:1 may still send to any `--chat-id`; the plugin does not pin recipients.
+- Gating is not a sandbox. The `wecom_cli` tool and `wecomcli-*` register only on the office 1:1 agent, PATH resolves `wecom-cli` to a refusal, and the credential directory reaches only the plugin's own spawns — but a shell in the same process can still bypass all of it: run `node <absolute path to @wecom/cli's wecom.js>`, or `npx --yes @wecom/cli` with a self-set `WECOM_CLI_CONFIG_DIR`. Without that variable such a bypass lands on the unauthorized `~/.config/wecom`. Real isolation needs a process sandbox.
+- The WeCom channel has no GUI confirmation dialog. Irreversible actions (send mail, cancel a meeting, delete a todo, overwrite a document) are constrained only by the prompt (run `--dry-run` first, wait for the next user message). Every WeCom session forbids `ask_user_question` (it hangs until the task times out).
+- Leftover `wecomcli-*` folders in workspace `.dsh/skills` / `.agents/skills` remain visible to every agent with that cwd, including GUI. Other skills are unchanged. `enabled: false` only turns off the deny shim, the auth check, `wecom_cli`, and wecomcli-* registration; the channel ban on `ask_user_question` is still injected.
+
 ## License
 
 MIT

package/README.md

@@ -4,10 +4,35 @@
 
 企业微信智能机器人 ⇄ DeepSeek Harness Agent 桥接 **DSH 插件**。
 
-在 dsh profile 内**进程内**创建 Agent（不再 spawn 子进程）：per-sender 持久会话（同一企业微信用户复用同一会话，有上下文记忆），会话与 Web GUI 同进程注册（实时可见、可续聊），并在 Settings → 插件配置页提供配置卡片（`botId` / `secret`、白名单、超时、提示语、模型覆盖，写入 `settings.yaml`）。
+在 dsh profile 内**进程内**创建 Agent（不再 spawn 子进程）：按**企微窗口**拆分持久会话（单聊 = 该用户一条；同一群里所有人共用一条；同一个人的私聊和群聊互不串上下文），会话与 Web GUI 同进程注册（实时可见、可续聊），并在 Settings → 插件配置页提供配置卡片（`botId` / `secret`、白名单、超时、提示语、模型覆盖，写入 `settings.yaml`）。
 
 Host 通过 `installSettingsSection` 注册 `im-bridge` 命名空间；浏览器半包以 `key: im-bridge` 挂进 `settings.plugin.item`。卡片可填 `botId` / `secret`，与 profile patch 写入同一用户层；改 `startHint` 等热字段后下一轮消息即生效，改凭证仍需重启进程才会连 WebSocket。
 
+## 会话粒度
+
+一条 DSH 会话对应一个企微聊天窗口，而不是「同一个 userid 的所有窗口」：
+
+- **单聊**：`single:<userid>`，该用户一条 Agent
+- **群聊**：`group:<chatid>`，群内所有人共用一条 Agent 和同一条串行队列（两人同时发也不会并发 `followup`）
+- `allowFrom` 按**发送者** userid 拦截谁能聊天；空 = 所有人可进队。办公命令另用 `wecomCli.allowFrom`
+- 群里 @机器人 的消息，开头的 `@昵称` 在入站就去掉：模型看到的和标题用的都是「测试一下」而不是「@MediaAgent 测试一下」；正文中间的 @某人 保留，整条只有 @ 时按原文交给模型
+- 进程重启后用稳定 id `wecom-` + key 的短 hash 续上同一条会话：进程里已有活 Agent 就直接采用（例如浏览器已打开该行），存档里有就 `resume`，都没有才 `create`。resume 的 cwd / preset 跟存档，不跟当前配置；cwd 不一致时打警告，不改写。
+- GUI 标题为「企微·私聊/群」+ 第一句用户话（与其它会话一样由 DSH 生成），不再露出 userid / chatid；同类型窗口若第一句话相近，侧栏仍是两行
+- 在 GUI 里归档某条企微会话 = 结束那段上下文：下一条消息用 `wecom-<hash>-2`（再归档就 `-3`）静默开一条新会话，企微侧不额外提示。DSH 没有取消归档的接口，所以旧会话只是不再被本插件写入，既不会恢复可见也不会被删除
+- 所有窗口仍共用同一个 `workspace`（文件 / rag 环境），与聊天上下文分窗是两件事
+
+## 兼容的 DeepSeek Harness 版本
+
+DeepSeek Harness 仍是 developer preview，对外置插件**没有 semver 兼容承诺**。本包 0.4.2 按实际调用的 API 对齐已发布 tag：
+
+| DSH | 本包 |
+|---|---|
+| [0.1.0-rc.8](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.0-rc.8)、[0.1.1-rc.1](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.1)、[0.1.1-rc.2](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2) | 可适配（对照开发的是 0.1.1-rc.2 一线） |
+| [0.1.0-rc.7](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.0-rc.7) 及更早 | 不可适配。rc.7 已有插件配置卡槽位和 `dsh plugin add`，但浏览器没有 `settingsScope.describe()`，配置卡加载和凭证「已配置」徽章会失败 |
+| 更新的 RC / 未打 tag 的 HEAD | 未保证。升级 dsh 后请再验 Settings 卡和企微连线 |
+
+建议把 `dsh` 钉在 `0.1.0-rc.8` 及以上，例如 `npx @deepseek-ai/dsh@0.1.1-rc.2 web`，不要只跑浮动的 `latest`。
+
 ## 安装
 
 ### 推荐：从 npm 安装
@@ -15,7 +40,7 @@ Host 通过 `installSettingsSection` 注册 `im-bridge` 命名空间；浏览器
 ```powershell
 dsh plugin --profile web add @mhfire/dsh-im-bridge
 # 或钉版本：
-# dsh plugin --profile web add @mhfire/dsh-im-bridge@0.2.0
+# dsh plugin --profile web add @mhfire/dsh-im-bridge@0.4.2
 ```
 
 在 `$DSH_HOME/profiles/web/cordis.patch.yml`（或对应 profile）中补密钥即可（其余项已有 bundle 默认，可按需覆盖）：
@@ -38,7 +63,25 @@ dsh plugin --profile web add @mhfire/dsh-im-bridge
 dsh plugin --profile web add <本包路径>
 ```
 
-未配置 `botId` / `secret` 时插件仍会加载（不阻塞 `dsh web`），日志会提示跳过企微连线；也可在 Settings → 插件配置卡片顶部填写，保存后徽章变为「已配置」，与 profile patch 同一用户层。改凭证仍要**重启**进程才会连接（本版本不做热重连）。
+未配置 `botId` / `secret` 时插件仍会加载（不阻塞 `dsh web`），日志会提示跳过企微连线；也可在 Settings 插件配置卡填写（见下节）。
+
+## Settings 插件配置卡
+
+安装插件并启动 `dsh web` 后，打开 **设置 → 插件 → 插件配置**，展开 **企业微信桥接**（与「终端 / Agent 循环 / 网页搜索」同一组卡片）。改完点右下角 **保存** 写入 `settings.yaml` 用户层，与 profile `cordis.patch.yml` 同一层；**放弃** 丢掉未保存草稿。带「已覆盖」的字段可 **重置** 回 bundle 默认。
+
+卡片字段自上而下：
+
+| 卡片项 | 对应配置 | 保存后 |
+|---|---|---|
+| Bot ID / Secret | `botId` / `secret` | 徽章变为「已配置」；**须重启进程** 才会连 WebSocket。输入框为密码框，线上看不到已存字面值；**留空再保存不会清空**已存凭证 |
+| 允许的发送者 userid | `allowFrom` | 下一轮消息生效；逗号分隔，空 = 允许所有人 |
+| 单任务超时（秒） | `agentTimeoutSec` | 下一轮消息生效 |
+| 开始处理时的占位提示 | `startHint` | 下一轮消息生效 |
+| 非白名单拒绝文案 | `deniedMessage` | 下一轮消息生效 |
+| 进入会话欢迎语 | `welcomeMessage` | 下一轮消息生效 |
+| 企微专用 provider / model | `provider` / `model` | 只影响之后**新建**的企微窗口会话；须两项都填才覆盖，否则跟随 GUI 默认模型 |
+
+`workspace`、`agentPreset`、`persona` / `personaFile`、`thinking`、`maxReplyBytes`、`reasoningEffort`、`wecomCli` 不在卡片上，仍在 profile patch 或下表中配置。本版本不做凭证热重连；改 `wecomCli` 也须重启进程。
 
 ## 配置项
 
@@ -48,16 +91,17 @@ bundle 的 `cordis.patch.yml` 已为除 `botId` / `secret` 外的字段提供默
 |---|---|
 | `botId` / `secret` | 企业微信智能机器人凭证（`role('secret')`，UI 自动脱敏）；缺省时跳过企微侧，不阻塞主进程 |
 | `workspace` | Agent 工作目录（会话 cwd） |
-| `allowFrom` | 允许的发送者 userid 白名单；空 = 允许所有人 |
+| `allowFrom` | 聊天白名单；空 = 允许所有人问诊断。不控制 wecom-cli |
 | `agentTimeoutSec` | 单任务最长执行时间（秒），动画进度条/剩余估算的基准 |
 | `startHint` | 开始处理时的占位提示语 |
 | `agentPreset` | Agent 加入的 preset（默认 `standard`） |
-| `provider` / `model` | 企微专用模型；**两者都非空**才覆盖，否则跟随 GUI 的 `agent-default-model`；只填一项会告警并回退。Settings 可编，只影响之后新建的发送者会话 |
+| `provider` / `model` | 企微专用模型；**两者都非空**才覆盖，否则跟随 GUI 的 `agent-default-model`；只填一项会告警并回退。Settings 可编，只影响之后新建的企微窗口会话 |
 | `reasoningEffort` | 覆盖生效时可选的推理强度；未覆盖模型时忽略 |
 | `persona` / `personaFile` | 机器人「人设」；优先级：`personaFile` → `persona` → 包内默认（按 Host `locale.preference` 选中/英）；覆盖不跟语言切换；含敏感信息请勿入库 |
 | `maxReplyBytes` | 回复上限（字节，默认 20000） |
 | `deniedMessage` | 非白名单用户的拒绝文案（Settings 可编） |
 | `welcomeMessage` | 进入会话欢迎语（Settings 可编） |
+| `wecomCli` | 可选的企业微信办公能力（默认关闭）。见下一节 |
 | `thinking` | 流式动画。优先级：工具活动（`toolLabels`）> 模型流式阶段（`reasoningStatus` / `outputStatus`，来自 `assistant/chunk`）> 时间轴 `phases` 兜底；另有 `spin` / `reasoningSpin` / `outputSpin` / `eggs` 等 |
 
 企微与 GUI 使用不同模型时，在 profile `cordis.patch.yml` 同时填写：
@@ -87,6 +131,41 @@ thinking:
     pwsh: PowerShell
 ```
 
+## 企业微信办公能力（wecom-cli）
+
+插件依赖官方 [`@wecom/cli`](https://www.npmjs.com/package/@wecom/cli) 二进制。`wecomcli-*` 装在 **`$DSH_HOME/wecom-cli-skills`**（不要装进工作区 `.dsh/skills` / `.agents/skills`，也不要装进 `$DSH_HOME/skills`）。插件只在**办公 userid 的单聊** Agent 上注入：`skills.register()` 装 catalog，`tools.register()` 装门控工具 `wecom_cli`。两者都走该 Agent 自己的 ctx，群聊与 GUI 看不到。工作区里其它 skill 仍由 `skill-filesystem` 发现，不受影响。
+
+办公命令**只经 `wecom_cli` 工具执行**：模型传 `argv`（`wecom-cli` 之后的参数数组），插件直接 spawn 官方二进制，并拒绝任何 `auth init`。PATH 上的 `wecom-cli` 是一个只打印拒绝信息并 `exit 1` 的 shim，所以群聊、GUI 以及任何 `pwsh wecom-cli` 都跑不通；shim 的文案会指回 `wecom_cli`。凭证目录不进程级导出，只在插件自己 spawn 时注入。
+
+`wecomCli.enabled` 默认关闭。开启须同时配置非空 **`wecomCli.allowFrom`**（办公 userid）；根级 `allowFrom` 只管谁能聊天，空名单表示所有人可问诊断。办公名单为空时插件会告警并跳过 shim / 授权 / `wecom_cli`。
+
+一次性准备：
+
+1. 根级 `allowFrom` 留空（所有人可问诊断），把 **办公** userid 写进 `wecomCli.allowFrom`（不要留空）
+2. 在 **Settings → 插件配置 → 企业微信桥接** 点「安装官方 skills」（Host 下载官方仓库 zip，解到 `$DSH_HOME/wecom-cli-skills`）。**不要用** `npx skills add -g`（会泄漏给 GUI）；skills CLI **没有 `--dir`**，加了也不会写到程序目录。若工作区里已有 `wecomcli-*`，先挪到该目录再删工作区副本。也可手动把官方仓库 `skills/wecomcli-*` 拷进 `$DSH_HOME/wecom-cli-skills`。
+
+3. 在 profile `cordis.patch.yml` 打开（启用后插件会用已有 `botId` / `secret` 走 `auth init --bot-id/--secret` 写入 wecom-cli 凭据，不必扫码、不必 `npm install -g @wecom/cli`）：
+
+```yaml
+- id: im-bridge
+  config:
+    allowFrom: []
+    wecomCli:
+      enabled: true
+      allowFrom: ["<办公 userid>"]
+      # skillsDir: ''   # 空 = $DSH_HOME/wecom-cli-skills
+      # configDir: ''   # 空 = <workspace>/.dsh/wecom-cli；请 gitignore
+```
+
+| 字段 | 说明 |
+|---|---|
+| `wecomCli.enabled` | 装 PATH 拒绝 shim、跑授权检查、给企微 Agent 接上 prompt 与 `wecom_cli` 工具；默认 `false` |
+| `wecomCli.allowFrom` | 能拿到 `wecom_cli` 工具的 userid；空则跳过 shim / 授权。与根级聊天名单独立 |
+| `wecomCli.skillsDir` | 覆盖 skills 根目录；空 = `$DSH_HOME/wecom-cli-skills` |
+| `wecomCli.configDir` | 覆盖凭证目录；空 = `<workspace>/.dsh/wecom-cli`。请把该目录加入 gitignore。`WECOM_CLI_CONFIG_DIR` 只在插件 spawn CLI 时注入，不写进程环境，因此不会使用 `~/.config/wecom`。 |
+
+改 `wecomCli` 后须重启进程。未授权时插件仍收消息；启动时用隐藏的 `--bot-id/--secret`（stderr 非 TTY）写入凭据。若自动写入失败，日志会打印一条带 `WECOM_CLI_CONFIG_DIR` 的手动命令——必须带上它，否则 `npx --yes @wecom/cli auth init --manual` 会把凭证写到 `~/.config/wecom`，插件读不到。禁止在 Agent 里扫码 `auth init`（会新建机器人）。
+
 ## 人设（persona）
 
 优先级：`personaFile` → `persona` 字符串 → 包内默认人设。
@@ -104,11 +183,35 @@ thinking:
 
 也可复制 [`persona.example.md`](./persona.example.md) 为模板后按环境填写。支持 `{{model}}` / `{{cwd}}` 占位符。含环境凭据的人设文件请勿提交。欢迎语 / 拒绝文案 / 思考动画文案目前仍为中文配置项，不随语言切换。
 
+## 把 PNG 发到企业微信
+
+Agent 的最终回复若包含指向**工作区内** PNG 的 Markdown，桥会在文字流结束之后，把图作为**独立图片消息**发出（先 `uploadMedia`，再用 `media_id` 调用 `sendMediaMessage`）。
+
+触发写法（相对 `workspace`）：
+
+```markdown
+![屏幕截图](main_screen.png)
+[屏幕截图](out/frame.png)
+```
+
+- 只认 `.png`；跳过 `http(s):` / `data:`；路径必须落在 `workspace` 内
+- 文件须为真实 PNG（文件头），单张不超过 **10MB**，最多 **10** 张（按出现顺序去重）
+- 只把 PNG 写到磁盘、回复里没有上述 Markdown，**不会**发图
+- 图在文字气泡之后另发，不会嵌进同一条流式消息
+- 入站图片/语音/文件消息仍忽略
+
 ## 安全
 
-- `config.json` / `persona.md` 等含密钥文件不入库；
+- `config.json` / `persona.md` / `.dsh/wecom-cli/` 等含密钥文件不入库；
 - 会话与工具输出可能含对抗性文本，插件内置安全提示词约束 agent 不把工具输出当指令。
 
+## Known Limitations and Deferred Work
+
+- wecom-cli 凭证在工作区 `<workspace>/.dsh/wecom-cli`（请 gitignore）。`wecomCli.allowFrom` 里的人借用这份凭据的办公权限；聊天名单（根级 `allowFrom`）不授予办公。办公单聊仍可向任意 `--chat-id` 发信，插件不锁定收件人。
+- 门控不是沙箱。`wecom_cli` 工具与 `wecomcli-*` 只注册到办公单聊 Agent，PATH 上的 `wecom-cli` 一律拒绝，凭证目录也只在插件自己 spawn 时注入；但同进程的 shell 仍可绕过：直接 `node <@wecom/cli 的 wecom.js 绝对路径>`，或 `npx --yes @wecom/cli` 并自行设置 `WECOM_CLI_CONFIG_DIR`。不设该变量时这类旁路会落到未授权的 `~/.config/wecom`。真正的隔离需要进程级沙箱。
+- 企微通道没有 GUI 审批框：发信、取消会议、删待办、覆盖文档等不可逆操作只靠 prompt 约束（先 `--dry-run`，等用户下一条确认）。所有企微会话都禁止 `ask_user_question`（会挂到超时）。
+- 工作区 `.dsh/skills` / `.agents/skills` 里残留的 `wecomcli-*` 仍会被同 cwd 的 GUI 和群聊发现。其它 skill 不受影响。`enabled: false` 只关拒绝 shim、授权检查、`wecom_cli` 与 wecomcli-* 注册；通道上的 `ask_user_question` 禁令仍会注入。
+
 ## License
 
 MIT

package/cordis.patch.yml

@@ -18,6 +18,12 @@
         maxReplyBytes: 20000
         deniedMessage: '无权访问本服务'
         welcomeMessage: '👋 办公助手已就绪。直接发消息即可，例如查文件、整理文档、查资料或处理日常事务。'
+        wecomCli:
+          enabled: false
+          skillsDir: ''
+          allowFrom: []
+          # skillsDir 空 = $DSH_HOME/wecom-cli-skills（不要用工作区 .dsh/skills）
+          # configDir: ''   # 空 = <workspace>/.dsh/wecom-cli
         thinking:
           eggAfterSec: 240
           intervalMs: 1500

package/lib/client.js

@@ -115,7 +115,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:C:\Users\user\Desktop\dsh-im-bridge\plugin\src\client\fields.module.css.mjs
-		const css = ".OMD7cq_field{flex-direction:column;gap:6px;padding:12px 0;display:flex}.OMD7cq_field+.OMD7cq_field{border-top:1px solid var(--dsw-alias-border-l2)}.OMD7cq_head{align-items:center;gap:8px;display:flex}.OMD7cq_label{min-width:0;color:var(--dsw-alias-label-primary);flex:1;font-size:13px;font-weight:500;line-height:1.5}.OMD7cq_badges{align-items:center;gap:8px;display:inline-flex}.OMD7cq_badge{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}.OMD7cq_badgeMuted{white-space:nowrap;color:var(--dsw-alias-label-tertiary);border-radius:999px;padding:1px 8px;font-size:11px;line-height:17px}.OMD7cq_reset{font:inherit;color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:none;padding:0;font-size:12px;line-height:1.5}.OMD7cq_reset:hover:not(:disabled){color:var(--dsw-alias-label-primary)}.OMD7cq_reset:disabled{cursor:default}.OMD7cq_input{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;line-height:1.5}.OMD7cq_input:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}.OMD7cq_input:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}.OMD7cq_inputInvalid{border:1px solid var(--dsw-alias-label-error);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;line-height:1.5}.OMD7cq_inputInvalid:focus-visible{outline:none}.OMD7cq_invalid{color:var(--dsw-alias-label-error);margin:0;font-size:12px;line-height:1.5}.OMD7cq_hint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:1.5}";
+		const css = ".OMD7cq_field{flex-direction:column;gap:6px;padding:12px 0;display:flex}.OMD7cq_field+.OMD7cq_field{border-top:1px solid var(--dsw-alias-border-l2)}.OMD7cq_head{align-items:center;gap:8px;display:flex}.OMD7cq_label{min-width:0;color:var(--dsw-alias-label-primary);flex:1;font-size:13px;font-weight:500;line-height:1.5}.OMD7cq_badges{align-items:center;gap:8px;display:inline-flex}.OMD7cq_badge{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}.OMD7cq_badgeMuted{white-space:nowrap;color:var(--dsw-alias-label-tertiary);border-radius:999px;padding:1px 8px;font-size:11px;line-height:17px}.OMD7cq_reset{font:inherit;color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:none;padding:0;font-size:12px;line-height:1.5}.OMD7cq_reset:hover:not(:disabled){color:var(--dsw-alias-label-primary)}.OMD7cq_reset:disabled{cursor:default}.OMD7cq_input{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;line-height:1.5}.OMD7cq_input:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}.OMD7cq_input:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}.OMD7cq_input::placeholder{color:var(--dsw-alias-label-tertiary)}.OMD7cq_inputInvalid{border:1px solid var(--dsw-alias-label-error);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;line-height:1.5}.OMD7cq_inputInvalid:focus-visible{outline:none}.OMD7cq_invalid{color:var(--dsw-alias-label-error);margin:0;font-size:12px;line-height:1.5}.OMD7cq_hint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:1.5}.OMD7cq_install{appearance:none;font:inherit;cursor:pointer;background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3);border:1px solid #0000;border-radius:8px;align-self:flex-start;padding:5px 14px;font-size:13px;line-height:1.5}.OMD7cq_install:hover:not(:disabled){opacity:.92}.OMD7cq_install:disabled{opacity:.4;cursor:default}.OMD7cq_install:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:1px}";
 		const tagId = "@mhfire/dsh-im-bridge/fields.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -133,6 +133,7 @@ window.__ModuleLoader__.load({
 			"hint": "OMD7cq_hint",
 			"input": "OMD7cq_input",
 			"inputInvalid": "OMD7cq_inputInvalid",
+			"install": "OMD7cq_install",
 			"invalid": "OMD7cq_invalid",
 			"label": "OMD7cq_label",
 			"reset": "OMD7cq_reset"
@@ -189,7 +190,8 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* Write-only credential control. The literal never rides a response, so the
-		* control starts blank and reports only whether one is configured.
+		* control starts blank and reports only whether one is configured. A configured
+		* empty draft shows a dots placeholder so the box does not look unset.
 		* @param props - the field's copy, staged text, and configured state.
 		* @returns the labelled control.
 		*/
@@ -217,6 +219,7 @@ window.__ModuleLoader__.load({
 						type: "password",
 						autoComplete: "off",
 						value: props.text,
+						placeholder: props.configured && props.text === "" ? "••••••••" : void 0,
 						disabled: props.disabled,
 						onChange: (event) => {
 							props.onEdit(event.target.value);
@@ -278,6 +281,16 @@ window.__ModuleLoader__.load({
 							props.edit("secret", text);
 						}
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SkillsInstall, {
+						t,
+						disabled,
+						available: state.skillsInstallAvailable,
+						status: state.skillsInstallStatus,
+						dest: state.skillsDest,
+						count: state.skillsCount,
+						error: state.skillsError,
+						onInstall: props.installSkills
+					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(ValueField, {
 						id: "im-bridge-allowFrom",
 						label: t("allowFrom"),
@@ -373,6 +386,44 @@ window.__ModuleLoader__.load({
 				]
 			});
 		}
+		function skillsStatusText(t, status, dest, count, error, available) {
+			if (!available) return t("skillsUnavailable");
+			if (status === "ok") return t("skillsInstalled").replace("{count}", String(count)).replace("{dest}", dest);
+			if (status === "error") return error === "" ? t("skillsFailed") : `${t("skillsFailed")} ${error}`;
+			return t("skillsHint");
+		}
+		/**
+		* Host-side install of official wecomcli-* (browser never chooses the path).
+		* @param props - copy, status, and the install action.
+		* @returns the labelled control.
+		*/
+		function SkillsInstall(props) {
+			const installing = props.status === "installing";
+			const status = skillsStatusText(props.t, props.status, props.dest, props.count, props.error, props.available);
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: fields_module_css_default.field,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: fields_module_css_default.head,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: fields_module_css_default.label,
+							children: props.t("skillsTitle")
+						})
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: fields_module_css_default.install,
+						disabled: props.disabled || !props.available || installing,
+						onClick: props.onInstall,
+						children: props.t(installing ? "skillsInstalling" : "skillsInstall")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: props.status === "error" || !props.available ? fields_module_css_default.invalid : fields_module_css_default.hint,
+						children: status
+					})
+				]
+			});
+		}
 		//#endregion
 		//#region src/client/card-form.ts
 		/**
@@ -577,6 +628,10 @@ window.__ModuleLoader__.load({
 				this.failed = false;
 				this.publish();
 			}
+			/** Rebuild bound projections for card-owned state outside the settings draft. */
+			notify() {
+				this.publish();
+			}
 			spec(field) {
 				const spec = this.specs.get(field);
 				if (spec === void 0) throw new Error(`im-bridge card has no field ${field}`);
@@ -610,15 +665,22 @@ window.__ModuleLoader__.load({
 		var WecomCardController = class {
 			scope;
 			describe;
+			rpc;
 			form;
 			store;
+			skillsInstallStatus = "idle";
+			skillsDest = "";
+			skillsCount = 0;
+			skillsError = "";
 			/**
 			* @param scope - bound settings scope for the `im-bridge` namespace.
 			* @param describe - Host describe face; secret literals never ride it.
+			* @param rpc - optional Connection RPC for the skills install button.
 			*/
-			constructor(scope, describe) {
+			constructor(scope, describe, rpc) {
 				this.scope = scope;
 				this.describe = describe;
+				this.rpc = rpc;
 				this.form = new CardForm(scope, [
 					csvField("allowFrom"),
 					numberField("agentTimeoutSec"),
@@ -649,7 +711,12 @@ window.__ModuleLoader__.load({
 					deniedMessage: this.form.field("deniedMessage"),
 					welcomeMessage: this.form.field("welcomeMessage"),
 					provider: this.form.field("provider"),
-					model: this.form.field("model")
+					model: this.form.field("model"),
+					skillsInstallAvailable: this.rpc !== void 0,
+					skillsInstallStatus: this.skillsInstallStatus,
+					skillsDest: this.skillsDest,
+					skillsCount: this.skillsCount,
+					skillsError: this.skillsError
 				};
 			}
 			/**
@@ -670,11 +737,45 @@ window.__ModuleLoader__.load({
 				await this.scope.set(field, text);
 				return this.secretConfigured(field);
 			}
+			/**
+			* Download official wecomcli-* into the Host-resolved directory.
+			* The browser does not choose the path.
+			*/
+			installSkills() {
+				this.runInstall();
+			}
+			async runInstall() {
+				if (this.rpc === void 0 || this.skillsInstallStatus === "installing") return;
+				this.skillsInstallStatus = "installing";
+				this.skillsError = "";
+				this.form.notify();
+				try {
+					const result = await this.rpc.call("/im-bridge", "wecomcli.installSkills", {});
+					if (!result.ok) {
+						this.skillsInstallStatus = "error";
+						this.skillsError = result.error.message;
+						this.form.notify();
+						return;
+					}
+					const value = result.value;
+					this.skillsInstallStatus = "ok";
+					this.skillsDest = typeof value.dest === "string" ? value.dest : "";
+					this.skillsCount = typeof value.count === "number" ? value.count : 0;
+					this.skillsError = "";
+				} catch (error) {
+					this.skillsInstallStatus = "error";
+					this.skillsError = error instanceof Error ? error.message : String(error);
+				}
+				this.form.notify();
+			}
 			/** Face the slot registration injects. */
 			inject() {
 				return {
 					hooks: { wecomCard: this.store },
-					...this.form.actions()
+					...this.form.actions(),
+					installSkills: () => {
+						this.installSkills();
+					}
 				};
 			}
 		};
@@ -697,7 +798,7 @@ window.__ModuleLoader__.load({
 			invalidNumber: "Enter a finite number.",
 			botId: "Bot ID",
 			secret: "Secret",
-			secretHint: "Leave blank to keep the stored value. Save, then restart the process to open the WebSocket.",
+			secretHint: "The box stays empty on purpose (the stored value never rides the wire). A Configured badge means it is saved; type a new value to replace it. Save, then restart the process to open the WebSocket.",
 			secretConfigured: "Configured",
 			secretUnset: "Not configured",
 			allowFrom: "Allowed sender userids",
@@ -713,7 +814,14 @@ window.__ModuleLoader__.load({
 			provider: "WeCom-only provider",
 			providerHint: "Empty follows the GUI default model. Both provider and model must be set to override.",
 			model: "WeCom-only model",
-			modelHint: "Takes effect only together with provider."
+			modelHint: "Takes effect only together with provider.",
+			skillsTitle: "WeCom office skills",
+			skillsHint: "Installs wecomcli-* into the plugin directory ($DSH_HOME/wecom-cli-skills). Do not use npx skills add -g; that CLI has no --dir. An empty Bot ID / Secret box is normal.",
+			skillsInstall: "Install official skills",
+			skillsInstalling: "Installing…",
+			skillsInstalled: "Installed {count} skills into {dest}",
+			skillsFailed: "Install failed.",
+			skillsUnavailable: "Install needs the Web host Connection."
 		};
 		/** Chinese copy for the im-bridge card. */
 		const zh = {
@@ -732,7 +840,7 @@ window.__ModuleLoader__.load({
 			invalidNumber: "请输入有效数字。",
 			botId: "Bot ID",
 			secret: "Secret",
-			secretHint: "留空保留已存值。保存后需重启进程才会连 WebSocket。",
+			secretHint: "框空是正常的（已存值不会传到浏览器）。徽章「已配置」即已保存；重新输入可覆盖。保存后需重启进程才会连 WebSocket。",
 			secretConfigured: "已配置",
 			secretUnset: "未配置",
 			allowFrom: "允许的发送者 userid",
@@ -748,7 +856,14 @@ window.__ModuleLoader__.load({
 			provider: "企微专用 provider",
 			providerHint: "空 = 跟随 GUI 默认模型。须与 model 同时填写才覆盖。",
 			model: "企微专用 model",
-			modelHint: "仅在同时填写 provider 时生效。"
+			modelHint: "仅在同时填写 provider 时生效。",
+			skillsTitle: "企微办公 skills",
+			skillsHint: "装到程序目录 $DSH_HOME/wecom-cli-skills。不要用 npx skills add -g；CLI 没有 --dir。Bot ID / Secret 框空是正常的。",
+			skillsInstall: "安装官方 skills",
+			skillsInstalling: "正在安装…",
+			skillsInstalled: "已装 {count} 个到 {dest}",
+			skillsFailed: "安装失败。",
+			skillsUnavailable: "安装需要 Web Host 的 Connection。"
 		};
 		//#endregion
 		//#region src/client/index.ts
@@ -767,7 +882,8 @@ window.__ModuleLoader__.load({
 		* @param ctx - browser plugin context.
 		*/
 		function apply(ctx) {
-			const card = new WecomCardController(ctx.settingsScope.bind({ namespace: NS }), ctx.settingsScope.describe());
+			const connection = ctx.get("connection");
+			const card = new WecomCardController(ctx.settingsScope.bind({ namespace: NS }), ctx.settingsScope.describe(), connection?.rpc);
 			ctx.effect(() => ctx.locale.register(NS, {
 				zh,
 				en