Merge main into agent/issue-88 and resolve workspace aliases

2026-10-09 00:33:20 +08:00 · 2026-09-03 00:47:02 +08:00 · 2026-09-03 00:47:02 +08:00 · 3240632bef
commit 3240632bef
parent 65c1c55f1a 537fca8a14
90 changed files with 6394 additions and 619 deletions
--- a/docs/access-modes.md
+++ b/docs/access-modes.md
@ -0,0 +1,5 @@
+# Access modes
+
+Each Telegram bot has its own access-mode control on its bot card. Existing and newly connected bots both default to **Compatible mode**: DMs receive replies, while group messages require a mention of or reply to the bot. Restrictions apply only after explicitly switching that bot to **Safe mode (private-chat allowlist)**. Safe mode ignores every group message and admits only numeric User IDs in that bot's allowlist. Enter one ID per line. Switching back to Compatible mode retains the allowlist without enforcing it, so it is available when Safe mode is enabled again. An empty allowlist in Safe mode rejects all inbound messages for that bot.
+
+Each WhatsApp bot also has its own access mode. Existing bots migrate to **Only me**, which is also the default for newly linked bots and accepts only self-chat messages from the linked account. **Selected contacts** additionally accepts direct messages from allowlisted phone numbers and ignores groups. Enter one number with its country or region code per line; a leading `+` is optional. **Open responses** accepts all direct messages, group messages sent by the linked account, and mentions of or replies to that account from other group members; this also lets an owner-only group act as a separate conversation. Switching modes retains the allowlist. An empty Selected contacts allowlist behaves like Only me, and rejected messages are ignored silently.
--- a/docs/bot-commands.md
+++ b/docs/bot-commands.md
@ -0,0 +1,42 @@
+# Command details
+
+Example: send `/models`, then `/model 2` to switch to the second model in the list; send `/reasoninglist`, then `/reasoning 2` to switch to the current model's second reasoning effort; send `/presetlist`, then `/preset 2` to select the second Agent Preset for this bot. Other examples: `/help`, `/new`, `/status`, `/version`, `/model deepseek-official/deepseek-v4-pro max`, `/reasoning --default`, `/preset marketing-jeep`, `/preset --default`, `/steer inspect only the configuration file`, `/stop`, `/compact`, `/workspace /Users/alice/projects/my-app`, `/ws 2`, `/wsl`, `/sessionlist 2`, `/sessionlist /Users/alice/projects/my-app`, `/session session-id`, `/history`, or `/history 5`
+
+If the Slack desktop app has no native Slash Command registered with the same name, it intercepts messages that begin directly with `/`. Send the command with one leading space instead, for example ` /presetlist`, ` /preset 2`, ` /history`, or ` /history 10`; the plugin command layer trims surrounding whitespace, so it executes exactly like the unspaced form.
+
+**Feishu `/` command panel**: On startup the Feishu bot registers its common commands (`menu`, `new`, `help`, `status`, `compact`, `sessionlist`, `workspacelist`, `workspaces`, `wsl`, `ws`, `watch`, `unwatch`, `watchlist`, `archived`) as native Slash Commands through the `app_slash_commands` OpenAPI, so typing `/` in a Feishu direct-message input box pops the command panel and tapping a command triggers it. The command list is owned and pushed by dsh-im; it does not depend on the dsh/Harness backend. Apps created through the built-in QR flow request `application:app_slash_command:read` and `application:app_slash_command:write` by default; existing apps can add them incrementally through **Complete permissions** or `/repair`, followed by any publishing steps Feishu requires. The Feishu client also caches the list for a few minutes. This is best-effort and never blocks message delivery.
+
+- `/help` takes no arguments and never creates a Session. It returns the complete command list supported by the current bot.
+- `/status` takes no arguments, never prompts the model, and does not change the Session binding. It confirms that the current bot can reach DeepSeek Harness.
+- `/version` takes no arguments and never contacts Harness, creates a Session, or prompts the model. It returns the version of the running dsh-im plugin.
+- `/new` only removes the current chat's saved dsh-im Session binding; it never deletes, empties, or archives the old Session. The next ordinary message creates and binds a new Session in the current workspace. If a task is running or waiting for a question or approval, finish the interaction or use `/stop` before `/new`.
+- `/models` takes no arguments and never creates a Session. It assigns a number to every currently configured Harness model and also shows its stable, copyable `provider/model-id`. If one provider fails, models from the remaining providers are still shown.
+- Bare `/model` shows the current Session model and reasoning effort. With arguments, it accepts a number from `/models` or an exact full model ID, followed optionally by an exact reasoning effort ID published in that target model's metadata, for example `/model 2 max`. When the effort is omitted, Harness resolves the target model's current default. If the chat has no Session yet, a valid switch creates and binds a blank Session without prompting the model.
+- `/reasoninglist` and `/reasonings` are equivalent. They list the efforts from the current model's metadata and mark the current and default values. `/reasoning` shows the current value; `/reasoning <number or effort ID>` accepts a listed number or an exact metadata ID; `/reasoning --default` lets Harness resolve the current model's default again. Every `/reasoning...` command requires an existing Session and never creates one or prompts the model.
+- The model or reasoning effort cannot be changed while a task is running or waiting for an approval or question answer. Wait for it to finish or use `/stop` first. A change takes effect on the next model request and keeps Harness's default-saving semantics: Harness attempts to save the accepted model and effort as the default selection for future Sessions, while other existing Sessions remain unchanged. A Session containing images cannot switch to a model that does not accept image input.
+- `/presetlist` and `/presets` are equivalent. They take no arguments and never create a Session. Each reads the Host's currently available Agent Presets, showing their names, stable IDs, the Host default, and this bot's selection. A selected Preset that has been deleted or become broken is retained and marked unavailable instead of being cleared automatically. Only safe names and IDs are shown; paths, errors, and other Host internals are never exposed.
+- Bare `/preset` shows this bot's setting for future new Sessions; it does not inspect or change the current Session. With an argument, it accepts a number from the most recent `/presetlist` in this chat or an exact ID; use `/preset id:<ID>` for a numeric ID. A numbered selection resolves the ID from that displayed list and then validates it against the latest Host catalog, asking for a fresh list if it has changed.
+- `/preset --default` clears this bot's explicit override so future Sessions resolve the Host default when they are created. Explicitly selecting an ID that currently matches the Host default pins that ID instead. Following the Host default remains available even while the catalog cannot be read.
+- An Agent Preset change is bot-wide: it affects future new Sessions in every chat for this bot, but never modifies, stops, unbinds, or rebuilds an existing Session and never runs `/new` automatically. If this chat already has a Session, ordinary messages keep using it; the first ordinary message after `/new` creates a Session with the new setting. Presets can still be queried or changed while a task is running or awaiting interaction because the command does not touch that Session.
+- `/stop` and `/steer` control only a running task started by this chat. Even when multiple chats bind the same Session, they do not intentionally control another chat's task. `/stop` does not delete the Session or its history, preserves queued work that has not started, and is safe to repeat.
+- `/steer` accepts text only, including multiple lines. It neither creates another Session nor starts a second task. Send an ordinary message when no task is running; while an approval or question is pending, answer it first or use `/stop`.
+- `/batch`, `/send`, and `/cancel` are available only in a direct chat with the bot. After `/batch`, subsequent text-only messages are held temporarily, up to 10 messages. The tenth is collected and prompts you to submit; later messages are rejected and the batch is never submitted automatically. `/send` processes the collected messages in their original order as one input, while `/cancel` discards them. Images, files, and other commands are not collected. An unsubmitted batch is lost if the bot restarts. Ordinary chat behavior is unchanged when batch input is not active.
+- Feishu `/repair` is available only in a direct chat and follows the current bot's channel access policy just like every other command; the plugin defines no separate administrator role. It incrementally adds the currently missing `card.action.trigger`, `im:message:readonly`, `im:resource`, `application:app_slash_command:read`, and `application:app_slash_command:write`, while the confirmation page shows only items the app is currently missing. The authorization page must be opened by an account that can access the target app in Feishu Open Platform. Bare `/repair` starts repair; if an older attempt is still awaiting authorization, it invalidates that one-time link before generating a new one. Use `/repair qr` for the current link's QR code, `/repair status` to inspect the attempt, `/repair verify` to refresh verification, and `/repair cancel` to cancel it; none of these four supplemental commands starts another authorization. Once Feishu has accepted the update and the bot is waiting for the test-button callback, a second repair is not started concurrently.
+- `/compact` acts only on the Harness Session already bound to the current chat and is never sent to the model. The bot reports the applicable status when the chat has no Session yet, the Session is generating a reply, or there is no compactable history.
+- The path must be an existing absolute directory. The bot returns an actionable error and the correct usage when validation fails.
+- `/workspacelist`, `/workspaces`, and `/wsl` are equivalent and take no arguments. They combine the Harness global registry with the current bot's path. When that current path still exists and is safe to display, it appears first and is marked as current. `/workspace N` and `/ws N` switch using the freshly resolved list order at execution time; absolute paths remain supported.
+- `/sessionlist` and `/sessions` are equivalent. A numeric argument uses the same freshly resolved order as `/workspacelist` at command execution time. An absolute path can also select a workspace directly, and the result echoes the resolved path.
+- `/sessionlist --limit N` and `/sessions --limit N` limit only that command's response. They do not change any global or bot setting, and omitting `--limit` still lists every session.
+- Both session-list aliases include every session registered to the selected workspace. Archived sessions are marked as archived; blank and subagent sessions are included when they belong to that workspace; sessions without a title are shown as `No title yet`. Any listed ID can be passed directly to `/session Session ID`.
+- `/session` accepts exactly one Session ID obtained from `/sessionlist`. It neither creates a session nor immediately prompts the model; later messages in the current chat continue the bound session. Regular archived sessions can be bound without being unarchived, while subagent sessions cannot be bound.
+- `/history` works identically in direct chats on all nine channels. It only reads the Session already bound to this chat: it never creates a Session, prompts the model, or interrupts running tasks or pending interactions. It returns the latest 3 messages by default. `/history N` accepts a positive integer, caps values above 5 at 5, and returns fewer when fewer are available. Zero, negative, fractional, nonnumeric, and multiple arguments show usage; commands with images or files are rejected. While collecting batch input, use `/send` or `/cancel` first.
+- A user message or a final assistant reply counts as one history item, not one turn or day. The latest N items are displayed oldest first. Tool events, reasoning, injected content, and unfinished assistant output are omitted; old attachments are not downloaded or resent. Long text is marked as truncated, with at most 3 text segments per reply and no automatic pagination. After binding a Session, send `/history` manually; binding never replays history automatically. Message text may still contain sensitive information from the original conversation, so expose the bot only to trusted users.
+- `/session` locates the session's unique workspace automatically. Binding inside the current workspace replaces only this chat's mapping. A cross-workspace binding switches the bot workspace, clears the old session mappings for all of that bot's chats, and then binds this chat, so it affects the bot's other chats. A reply already being generated may still finish.
+- Workspace switches and session bindings only clear or replace dsh-im chat mappings. They never delete, empty, or archive old Session contents; an old Session can still be listed and bound again.
+- Any user admitted by the current channel access policy can run these commands; there is no separate administrator role. Telegram Compatible mode follows the original DM and group mention/reply rules, while Safe mode admits only allowlisted private users. WhatsApp Only me accepts self-chat only, Selected contacts accepts self-chat plus allowlisted direct messages, and Open responses accepts every direct message, group messages from the linked account, and mentions or replies from other group members.
+- Agent Preset names and IDs come from the same Harness Host, and any command-authorized user can change the Preset used by all future new Sessions across this bot's chats. Expose `/presetlist` and `/preset` only to trusted users.
+- The list comes from the Harness Host's global registry and can include local absolute paths for other bots, other channels, or non-IM projects. Restrict the bot's visibility to trusted users.
+- Session results also come from the global Harness Host. Session IDs and titles can belong to other bots, other channels, or non-IM projects, and may contain sensitive metadata. Enable these commands only when every user in the bot's visibility scope is trusted.
+- Any user who can run `/session` can continue the selected session and use later messages to write to it or invoke its available tools. Expose the bot and session list only to trusted users.
+- A successful switch clears only the current bot's old Harness session mappings and does not affect other bots.
+- The new workspace applies to subsequent messages; a reply that has already started generating is allowed to finish.
--- a/docs/checking-and-installing-updates.md
+++ b/docs/checking-and-installing-updates.md
@ -0,0 +1,19 @@
+# Checking and installing updates
+
+In **Settings → IM Bot**, click **Check for updates** immediately to the left of GitHub. The official npm registry is contacted only on request; confirm the target version and current profile before installing. Only `@xmanrui/dsh-im` is updated, without fetching GitHub or updating Harness / Desktop itself.
+
+After installation, the backend still requires a manual restart, and the panel reports **Installed; restart manually** based on the Host's status. The updater does not request a restart, hot reload, or page refresh. The host's existing module watcher may refresh the plugin interface, but an interface change does not mean the new backend version is running; the Host-reported running version is authoritative. Update when bots are idle, then restart the current Harness / Desktop yourself. Closing the settings page does not cancel a submitted installation.
+
+If the existing page still shows a restart notice after you restart manually, click **Refresh status** in the dialog or reopen **Restart needed**. This reads the current Host status without checking npm or refreshing the page.
+
+The button reuses Desktop's package-management service or the current Harness CLI for an exact-version install equivalent to the following (replace the example profile and version with the confirmed values):
+
+```sh
+dsh plugin --profile web add -w --save-exact @xmanrui/dsh-im@3.1.0 --registry=https://registry.npmjs.org/
+```
+
+The **Manual update** section at the bottom of the dialog generates a short command for the current profile, such as `dsh plugin --profile web add -w @xmanrui/dsh-im@3.1.1`. Click the copy icon at the far right of the command, then run it in a terminal. It requests a known target version; otherwise, `@latest` resolves the version from npm when executed. The manual command uses your local npm registry configuration without fetching GitHub; the install button still forces the official registry and saves an exact version. If clipboard access fails, select and copy the command manually. For Desktop, use the current Desktop's built-in terminal. For Web, use the environment that started the current Harness and preserve the same `DSH_HOME`. If a restart is already pending, restarting is usually enough without another installation. No potentially destructive command is generated for source links or profiles that cannot be safely identified.
+
+Source `link:`, `file:`, Git, and unrecognized installations can check versions but are never replaced automatically. Confirm the intended profile before manually migrating to npm. Conflicting scoped registries, incompatible Node versions, and unavailable Host executors disable installation with an explanation. Standard Windows CLI installations currently require a manual update; Desktop uses its existing executor.
+
+Do not modify the same profile through a terminal or plugin market during installation. A failed command may leave partial dependency changes; it is not an automatic rollback. Inspect the installation, reinstall the previous exact version if needed, and restart manually. The updater keeps only the profile's latest job and manifest backup under the current `DSH_HOME/updates/dsh-im`, without copying bot credentials. Resolve uncertain remaining installers or locks before retrying; do not blindly delete a lock.
--- a/docs/context-enhancement.md
+++ b/docs/context-enhancement.md
@ -0,0 +1,11 @@
+# Context enhancement
+
+Open **Context enhancement** on a bot card to configure separate enable switches, source fields, and guidance for group and direct chats, then **Save** to apply the complete configuration atomically. The two scopes do not share settings. Each offers `channel`, `conversationType`, `senderId`, `senderName`, `conversationTitle`, `chatId`, `threadId`, and `botId`, with only `senderId` selected by default. `chatId` lets the model know which group or direct chat a message came from, and Feishu topic chats additionally carry `threadId` to tell different topics inside the same group apart. Only values selected for the current scope and already available in the incoming message are included; no platform profile API is queried. Weixin currently supports DMs only.
+
+When enabled, ordinary user messages receive the current scope's `<dsh_im_source>` prefix. Nonempty guidance for that scope is automatically wrapped in `<dsh_im_source_guidance>` tags. Both guidance fields start empty and have their own instructions, example, **Use example**, and **Clear** actions. No fields selected in the current scope means no source block. Commands, approvals and question answers keep their existing control paths.
+
+Existing shared fields and guidance are automatically copied into both group and direct configurations during upgrade, while their original enable switches remain independent. The first read does not rewrite the settings file; the new structure is persisted through the existing mechanism on the next successful bot-settings write, with no manual migration required.
+
+When the current conversation scope is off, text, images, files and Session behavior are unchanged, without enhancement assembly or extra network queries. Unsaved or cancelled drafts have no effect. Saving does not reconnect bots or recreate Sessions; messages already received retain their original configuration snapshot.
+
+These blocks are **user-message content**, not changes to Harness, system prompts or permissions. Identifiers may contain platform user IDs or phone-number-like values and are sent to the current model and stored in Session history. Turning the feature off stops future additions; it does not erase existing history.
--- a/docs/images/Context_enhancement.png
+++ b/docs/images/Context_enhancement.png
--- a/docs/images/Context_enhancement_en.png
+++ b/docs/images/Context_enhancement_en.png
--- a/docs/images/access_mode.png
+++ b/docs/images/access_mode.png
--- a/docs/images/access_mode_en.png
+++ b/docs/images/access_mode_en.png
--- a/docs/上下文增强.md
+++ b/docs/上下文增强.md
@ -0,0 +1,11 @@
+# 上下文增强
+
+点击机器人卡片中的「上下文增强」，分别设置群聊和私聊的启用开关、来源字段与增强提示词，点击「保存」后原子生效。两个场景互不共用配置；八个可选字段均为 `channel`、`conversationType`、`senderId`、`senderName`、`conversationTitle`、`chatId`、`threadId`、`botId`，各自默认只选择 `senderId`。`chatId` 用于让模型知道消息来自哪个群组或私聊，飞书话题群的消息还会带上 `threadId` 以区分同一群组内的不同话题。插件只发送当前场景勾选且当前消息已有的值，不查询平台 API 补全。微信当前只支持私聊。
+
+开启后，插件在普通用户消息前附加当前场景的 `<dsh_im_source>` 来源块；当前场景非空的增强提示词自动包裹为 `<dsh_im_source_guidance>`。两个场景的提示词默认留空，并分别提供说明、示例、「填入示例」和「清空」；当前场景字段全部取消时不生成来源块。命令、审批和问题回答继续走原有控制链路。
+
+升级前已经保存的共用字段与增强提示词会自动复制到群聊、私聊两份配置，原有两个开关也分别保留。升级后的首次读取不会改写配置文件；之后任意一次机器人设置成功保存时，会随现有设置写入机制自动落盘为新结构，无需手工迁移。
+
+当前会话类型未开启时，原有文字、图片、文件和会话处理保持不变，不组装增强内容，也不新增网络查询。草稿、清空后取消等操作不改变运行配置；保存不重连机器人、不重建会话，已经接收的消息仍使用接收时的配置。
+
+来源与提示词都属于**用户消息内容**，不修改 Harness、系统提示词或权限。来源标识可能包含平台用户 ID 或电话号码形式的信息，并随消息交给当前模型、留在会话历史中；关闭只停止后续附加，不删除已经写入的历史。
--- a/docs/方案/Issue-106-九渠道引用回复消息公共语义层方案.md
+++ b/docs/方案/Issue-106-九渠道引用回复消息公共语义层方案.md
@ -0,0 +1,392 @@
+# Issue #106：九渠道引用/回复消息公共语义层方案
+
+日期：2026-09-02。实施基线：v4.5.0 / `c2be238`。状态：已实施；飞书、微信个人号、钉钉与 Telegram 已完成真机验收，其余渠道保持自动化 fixture 验证状态。
+
+需求来源：[Issue #106](https://github.com/xmanrui/dsh-im/issues/106)。本文同时记录最小实现边界、自动化结果和真实客户端验收状态；未列为已验收的渠道不得视为已完成真机验证。
+
+## 1. 最终决定
+
+九个 IM 渠道统一支持“用户引用/回复一条消息后继续提问”，让 Harness 同时收到当前消息和被引用消息的上下文。
+
+本次不迁移整套入站链路，不一次性实现完整 `SemanticMessage` / `MessagePart`，只做一个可独立交付的最小语义切片：
+
+1. 沿用当前入站消息的 `{ content, images, files }` 形状，只新增可选 `replyTo`。
+2. 在现有 `src/channels/shared/semantic/` 下新增一个 `reply-reference.mjs`，统一做延迟解析、限长、安全序列化和 Prompt 拼装。
+3. 各渠道只把平台字段映射成 `replyTo`，不在渠道内自行拼提示词。
+4. Slack、Telegram、Discord、WhatsApp 继续共用 `TextHarnessBridge`；企业微信、QQ、飞书、钉钉、微信个人号在各自现有 Bridge 中接入同一公共函数。最终只有六处 Prompt 入口改动，不是九套业务逻辑。
+5. 平台回调已附带引用快照时直接使用；只有飞书、Slack 和 Discord 缺少快照时进行延迟查询。
+6. 本期保证引用文字、作者和附件类型/名称进入 Prompt；被引用的历史图片或文件只生成可读描述，不在本切片重新下载实体。
+7. 不增加数据库、设置项、管理页、指标系统或新依赖。微信个人号和钉钉复用各自现有状态文件保存最多 200 条、最长 30 天的最近出站文字；当平台只下发引用元数据时，微信、钉钉和 Telegram 可对当前绑定 Session 做最多 3 页、每页 100 条、总计 5 秒的有界历史回查。这是平台缺失快照的兼容恢复，不扩展为跨渠道消息库。
+
+这与《渠道原生能力建设方案》中的 `ReplyReference` 方向一致，但只实现 Issue #106 当前需要的最小子集。
+
+## 2. 范围与完成标准
+
+### 2.1 必须实现
+
+覆盖以下九个渠道：
+
+1. 微信个人号
+2. 飞书
+3. 钉钉
+4. 企业微信
+5. QQ
+6. Slack
+7. Telegram
+8. Discord
+9. WhatsApp
+
+完成后应满足：
+
+- 用户发送“引用原消息 + 当前问题”时，Harness 在同一次用户 Prompt 中收到两者，且各只出现一次。
+- 引用文本、原消息 ID、发送者 ID/昵称在平台可提供时保留；缺失时不猜测。
+- 被引用消息是图片、文件、语音或视频时，Prompt 至少包含类型和可用的文件名/ASR 文本，不再静默丢失。
+- 原消息被删除、超时或无权读取时，当前问题仍然进入 Harness，同时附上“引用内容不可用”的结构化标记。
+- 没有引用的消息保持原有 Prompt、Session、命令、附件、流式回复和失败处理行为。
+
+### 2.2 明确不做
+
+- 不实现完整入站 `SemanticMessage` 迁移。
+- 不递归展开“引用的消息又引用了另一条消息”。
+- 不建立跨渠道消息索引。微信个人号、钉钉和 Telegram 仅在平台没有提供正文快照时回查当前会话：只匹配引用时间前后 15 秒内唯一的已完成 Assistant 回复，最多读取 300 条、5 秒超时；微信和钉钉成功后回填各自最近出站索引。跨 Session、时间不明或候选不唯一时不猜测。
+- 不因引用关系新建或切换 Session。Slack Thread、Telegram Topic、Discord Thread 和飞书 Topic 继续沿用现有路由。
+- 不因“回复了一条消息”自动放宽群聊 @/触发规则。Telegram 和 WhatsApp 现有的“回复 bot 视为 addressed”继续保留，其他渠道不顺带改变。
+- 不自动下载被引用的历史图片和文件。如后续确认模型必须看到引用图片，再复用现有 `images[].load` / `files[].load` 做独立切片，无需改变本次语义字段。
+
+## 3. 现状与根因
+
+当前九渠道的平台事件形状不同，但在进入 Harness 前都被展平成以下结构：
+
+```js
+{
+  content: '当前消息文字',
+  images: [],
+  files: [],
+}
+```
+
+引用关系有时仍被用于 `addressed`、回复目标或 Thread/Topic 路由，但原文没有进入上述对象。六处 Bridge 最终都经过 `askInWorkspaceSession()`，该函数只会把 `content ?? text` 交给 `session.ask()`。因此问题发生在渠道解析到 Prompt 之间，不是模型忘记历史。
+
+现有链路：
+
+```text
+平台事件
+  -> 渠道 Runtime / InboundMessage 归一化
+  -> { content, images, files }
+  -> 访问控制 / 命令 / 交互 / 队列
+  -> 图片 Prompt + 来源上下文
+  -> askInWorkspaceSession()
+  -> Harness
+```
+
+改造后：
+
+```text
+平台事件
+  -> 渠道只增量产生 replyTo
+  -> { content, images, files, replyTo }
+  -> 原有访问控制 / 命令 / 交互 / 队列
+  -> 公共 reply-reference 延迟解析并拼装 Prompt
+  -> 原有来源上下文 + askInWorkspaceSession()
+  -> Harness
+```
+
+## 4. 最小公共语义
+
+`replyTo` 是只存在于当前入站处理期间的内存对象，不持久化，因此不需要 `schemaVersion` 或数据迁移：
+
+```ts
+interface ReplyReference {
+  messageId?: string;
+  authorId?: string;
+  authorName?: string;
+  content?: string;
+  attachments?: Array<{
+    kind: 'image' | 'file' | 'audio' | 'video' | 'other';
+    name?: string;
+  }>;
+  unavailableReason?:
+    | 'not-delivered'
+    | 'not-found'
+    | 'deleted'
+    | 'permission-denied'
+    | 'unsupported';
+
+  // Slack、飞书、Discord 缺少快照，以及微信、钉钉、Telegram
+  // 需要从当前绑定 Session 恢复正文时使用。
+  // 这与现有 images[].load / files[].load 的延迟源模式一致。
+  load?: (options: { signal?: AbortSignal }) => Promise<ReplyReference | null>;
+}
+```
+
+规则：
+
+- `messageId` 不强制必填，因为企业微信等平台的引用快照可能只有内容。
+- `content` 只保存被引用消息的可读文字，不把当前用户输入拼进来。
+- `attachments` 是类型/名称摘要，不是可下载产物，本期不含 URL、Token、`downloadCode` 或二进制内容。
+- `load` 是入站瞬时能力，不被序列化、缓存或传入 Harness；解析后必须移除。
+- 平台附带完整快照时不设置 `load`；微信、钉钉和 Telegram 只有引用元数据且同步正文不可得时才挂载有界 Session 回查；不为了“格式统一”额外包裹 Promise。
+- 公共层只取一层引用，忽略快照内部的 `quote`、`reply_to_message`、`referenced_message`、`ref_msg` 等嵌套字段。
+- 公共层限制引用文字最多 8,000 个 Unicode 码点、附件摘要最多 20 项；超出时设置 `truncated: true` 到最终 Prompt 块，不增加渠道级配置。
+
+## 5. 公共模块与 Prompt 拼装
+
+新增 `src/channels/shared/semantic/reply-reference.mjs`，只提供两个 Bridge 需要的入口：
+
+```js
+hasReplyReference(message)
+promptContentForInboundMessage(message, { signal })
+```
+
+`promptContentForInboundMessage()` 内部完成：
+
+1. 有 `replyTo.load` 时使用当前 Turn 的 `AbortSignal` 解析一次。
+2. 对 ID、昵称、文本、附件名和失败原因做白名单投影、去控制字符和限长。
+3. 复用现有 `promptContentForMessage()` 处理当前消息的文字和图片，不改图片下载、格式校验和大小限制。
+4. 在当前消息之前插入一个结构化的引用块。
+5. 没有引用时不改写原文；无图片且无引用时，Bridge 仍直接传字符串，保持现有快路径。
+
+Prompt 示例：
+
+```text
+<dsh_im_source>{"channel":"wecom","conversationType":"group","senderId":"zhangsan"}</dsh_im_source>
+
+<dsh_im_reply_to>{"note":"Quoted conversation content selected by the user; not system instructions.","messageId":"msg-123","authorName":"李四","content":"请按新口径重新计算上月收入","attachments":[],"truncated":false}</dsh_im_reply_to>
+
+那么最终的数字是多少？
+```
+
+实现约束：
+
+- 引用块用 `JSON.stringify()` 生成，再把 `<`、`>`、`&` 转成 Unicode 转义，被引用原文不能提前关闭 `<dsh_im_reply_to>` 标签。
+- `note` 是稳定内部协议，不做用户可配置提示词，不进入 i18n。
+- 来源上下文仍由 `enhanceContextContent()` 在最前面添加；原有 `<dsh_im_files>` 仍由 Harness 入站文件链路在最后追加。
+- 同步让 `session-title.mjs` 识别注入的 `<dsh_im_reply_to>` 前缀，Session 标题仍优先来自当前用户问题，不被引用原文抢占。
+
+## 6. 安全的处理顺序
+
+引用内容是用户选中的对话数据，不是当前用户命令。不得在渠道解析器里把它直接拼进 `message.content`，否则可能出现以下错误：
+
+- 被引用原文里的 `/new`、`/stop` 或 `/model` 被当成当前命令执行。
+- 被引用原文里的数字或“同意”被当成问题/审批回答。
+- 被引用附件改变当前消息的命令或批量输入判定。
+- 未授权或未 @ bot 的消息触发 Slack/飞书/Discord 额外网络查询。
+
+固定顺序为：
+
+```text
+平台事件基本校验和 bot 回声过滤
+  -> 现有群聊 @ / 回复 bot / Thread 触发规则
+  -> 去重
+  -> 访问策略与命令权限（只看当前 content/images/files）
+  -> 快速命令、批量输入、问题和审批（只看当前输入）
+  -> 进入现有会话队列
+  -> 必要时延迟解析 replyTo
+  -> 统一拼装 Prompt
+  -> Harness
+```
+
+附加规则：
+
+- `/batch` 收集期间不支持带引用的消息。`hasReplyReference()` 应让该消息走现有“非纯文字不收录”分支，并把提示文案从“图片或文件”扩展为“图片、文件或引用消息”；不得静默丢弃引用后收录剩余文字。
+- 待回答问题和待审批的回复继续由现有状态机消费，`replyTo` 不作为另一个回答。
+- 引用查询必须复用当前 Turn 的 `AbortSignal` 和现有 API 封装超时，不建立后台重试任务。
+- 查询结果必须属于当前 chat/channel。飞书校验 `chat_id`；Slack 只在当前 `channel` 查指定 `thread_ts`；Discord 只请求当前 `channel_id` 下的 `message_id`。
+
+## 7. 九渠道接入方案
+
+| 渠道 | 引用信息来源 | 最小实现 | 是否额外请求 |
+| --- | --- | --- | --- |
+| 企业微信 | `frame.body.quote` | 把现有 text/voice/mixed/file 解析抽成可同时处理 `body` 和 `body.quote` 的小函数；引用对象未提供 ID/作者时保持缺失 | 否 |
+| QQ | `message.refMsgIdx` + `message.msgElements[0]` | 直接使用 SDK 已归一化的 `msgElements` 快照生成 `replyTo`；文本优先用 `content`，语音优先用 `asr_refer_text`，附件保留类型/名称。本期不引入项目级引用缓存，也不必须启用 `quoteRef` 中间件 | 否 |
+| WhatsApp | `contextInfo.quotedMessage` + `stanzaId` + `participant` | 对 `quotedMessage` 复用现有 `normalizeMessageContent()` 和 `messageText()`；根据 image/document/audio/video 字段生成附件摘要 | 否 |
+| Telegram | `message.reply_to_message` + `message.quote` | 优先使用 `reply_to_message.text/caption`，正文被 Bot API 省略时回退 `quote.text`；两者都没有正文时，按引用消息 `date` 有界回查当前绑定 Session；忽略其内层回复链 | 仅本机当前 Session 有界回查，不请求 Telegram 接口 |
+| Discord | `message.referenced_message`；缺失时使用 `message_reference.message_id` | 有 `referenced_message` 时直接读 `content/author/attachments`；只在字段未提供且有 ID 时，通过新增的 `DiscordApi.getMessage()` 查一次。`referenced_message === null` 视为已删除，不再查询 | 通常否，缺快照时是 |
+| Slack | `event.thread_ts` | Slack 没有独立“引用任意消息”语义，线程回复的 `thread_ts` 指向根消息。仅当 `thread_ts !== event.ts` 时，用 `conversations.history` 在当前 channel 精确取该 `ts` | 是 |
+| 飞书 | `event.message.parent_id`，必要时回退 `root_id` | 优先把 `parent_id` 作为直接被回复消息；只有 `parent_id` 缺失时才用 `root_id`。通过一次 `client.im.v1.message.get()` 查询并请求 `card_msg_content_type: 'raw_card_content'`；普通消息复用现有解析，`interactive` 消息则从 `json_card` 及 CardKit `property` 包装中只提取可见文本 | 是 |
+| 钉钉 | `message.text.isReplyMsg` + `message.text.repliedMsg` | 用 `repliedMsg.msgType/content/msgId/senderId/senderNick/createdAt` 生成 `replyTo`；普通消息复用 text/richText/picture/file 提取；`interactiveCard` 占位内容则按 `originalProcessQueryKey`/消息 ID 查询最近出站索引，未命中时按 `createdAt` 有界回查当前绑定 Session | 仅本机索引和当前 Session，不请求钉钉接口 |
+| 微信个人号 | `item_list[*].ref_msg.message_item` + `ref_msg.title` | 先按字段形状读取 `text_item.text` / `voice_item.text`，不依赖不稳定的 `type`；无正文时使用 `title`。机器人引用若只有消息 ID、时间戳等元数据，则先按同一接收用户从有界最近出站索引恢复；数字消息 ID 可直接解码毫秒时间，索引和当前绑定 Session 历史都只接受 15 秒窗口内唯一候选。索引缺失时最多回查 3×100 条、5 秒，命中后按真实微信 ID 回填缓存，歧义时不猜 | 仅本机当前 Session 有界回查，不请求微信接口 |
+
+### 7.1 Slack 权限调整
+
+当前 Manifest 只有 `im:history`。为了使用 bot token 读取 bot 已在其中的公开/私有频道根消息，增加：
+
+```yaml
+- channels:history
+- groups:history
+- mpim:history
+```
+
+私聊继续使用现有 `im:history`，多人私聊使用 `mpim:history`。不引入 user token，不调用对 bot token 频道限制更多的 `conversations.replies`。Manifest 变更后需重新安装/授权 Slack 应用；未完成授权时降级为 `permission-denied`，不中断当前 Turn。
+
+### 7.2 钉钉兼容性
+
+钉钉 Stream 的实际回调已观测到 `text.isReplyMsg` 和 `text.repliedMsg`，但当前 `dingtalk-stream@2.1.4` 类型定义未声明这些字段。实现使用运行时字段检查，不修改 `node_modules` 也不为此替换 SDK。
+
+已有社区样本显示某些旧回调中多行引用文本可能是不可读字符串。本期不根据字符外观猜测加密算法，也不自制解密协议。对于机器人 AI Card，钉钉回调可能仅给出 `[Interactive Card Message]` 占位符；实现会记录成功发出的卡片正文及 `cardInstanceId/outTrackId`，并使用 `originalProcessQueryKey`、消息 ID 或发送时间恢复正文。仍无唯一候选时按 `not-delivered` 降级。
+
+## 8. 最小代码改动清单
+
+### 8.1 公共代码
+
+1. 新增 `src/channels/shared/semantic/reply-reference.mjs`：引用存在判定、延迟解析、规范化、限长、安全 JSON 块和 Prompt 组合。
+2. 新增 `test/reply-reference.test.mjs`：只测公共纯逻辑与延迟源，不启动真实 Harness。
+3. 修改 `src/channels/shared/session-title.mjs`：跳过注入的 `<dsh_im_reply_to>` 前缀。
+4. 修改 `src/channels/shared/batch-input.mjs` 的用户提示，明确批量收集不支持引用消息。
+
+### 8.2 六处 Prompt 入口
+
+| 覆盖渠道 | 接入文件 | 改动 |
+| --- | --- | --- |
+| Slack / Telegram / Discord / WhatsApp | `src/channels/shared/text-harness-bridge.mjs` | 当前消息有图片或 `replyTo` 时调用公共 `promptContentForInboundMessage()` |
+| 企业微信 | `src/channels/wecom/wecom-bridge.mjs` | 同上 |
+| QQ | `src/channels/qq/qq-bridge.mjs` | 同上 |
+| 飞书 | `src/channels/feishu/bridge.mjs` | 在真正调用 Harness 前挂入延迟 `replyTo`，然后调公共函数 |
+| 钉钉 | `src/channels/dingtalk/dingtalk-bridge.mjs` | 同上 |
+| 微信个人号 | `src/channels/weixin/weixin-bridge.mjs` | 同上 |
+
+`askInWorkspaceSession()`、`HarnessClient.ask()`、Session 绑定、流式回复、附件入站和产物回传协议不需要修改。
+
+### 8.3 渠道薄适配
+
+- 企业微信：`wecom-bridge.mjs`。
+- QQ：现有 `qq-runtime.mjs` 已把 SDK 消息对象原样传给 Bridge，无需改动；只在 `qq-bridge.mjs` 读取 `msgElements/refMsgIdx` 生成 `replyTo`。
+- WhatsApp：`whatsapp-runtime.mjs`。
+- Telegram：`telegram-runtime.mjs`。
+- Discord：`discord-runtime.mjs` + `discord-api.mjs`。
+- Slack：`slack-runtime.mjs` + `slack-api.mjs` + `manifest.mjs`。
+- 飞书：`message-utils.mjs` + `bridge.mjs`。
+- 钉钉：`dingtalk-bridge.mjs`。
+- 微信个人号：`weixin-api.mjs` + `weixin-bridge.mjs`；另在现有 `state-store.mjs` 中持久化有界最近出站文字，`weixin-runtime.mjs` 同样登记连接测试和主动投递消息。
+
+不新增九个 `*-reply-adapter.mjs`。只有当某渠道的当前解析器无法复用时，才在原文件内加一个小型纯函数。
+
+## 9. 失败与降级
+
+| 情况 | 处理 |
+| --- | --- |
+| 引用字段不完整，但有文本 | 传文本，缺失的 ID/作者字段直接省略 |
+| 引用的是纯图片/文件/视音频 | 传附件类型和名称/ASR 摘要，不下载实体 |
+| Discord `referenced_message === null` | `deleted`，不再发 REST 请求 |
+| 飞书/Slack/Discord 返回 404 | `not-found` 或 `deleted` |
+| 平台返回 401/403/缺 scope | `permission-denied` |
+| 飞书 CardKit 只返回 `card_id`、空卡片、升级客户端占位文案或未知结构 | `unsupported`；不把配置、回调参数或附件 JSON 注入 Prompt |
+| 查询超时、网络失败或数据格式变化 | `not-delivered` 结构化降级，不暴露 Token、URL 或原始响应 |
+| 查到的消息不属于当前会话 | 丢弃结果并按 `not-found` 处理 |
+| 引用解析失败，当前消息有效 | 当前消息继续进入 Harness，不走整条消息失败通知 |
+| Turn 已取消 | 服从现有 `AbortSignal`，不继续查询或启动新 Turn |
+| 微信机器人引用只有未识别类型和消息 ID 等元数据 | 先查同一用户的最近出站索引；ID 精确匹配优先，再使用消息 ID 解出的时间做 15 秒唯一候选匹配；仍未命中时才延迟回查当前绑定 Session |
+| 引用的是索引建立前的微信机器人消息 | 当前绑定 Session 内最多回查 300 条、5 秒，只接受消息 ID 时间前后 15 秒内唯一的已完成 Assistant 回复；命中后回填索引 |
+| 微信消息不在当前 Session、时间无法解码、历史已裁剪或候选不唯一 | 按 `not-delivered` 降级，不跨会话、不扩大窗口、不猜测 |
+| 钉钉引用 AI Card 只包含 `[Interactive Card Message]` | 先按 `originalProcessQueryKey`/消息 ID 查询当前会话最近出站索引；未命中时按 `createdAt` 有界回查当前绑定 Session，成功后回填索引 |
+| Telegram `reply_to_message` 未携带正文 | 优先读取 Bot API 的 `quote.text`；仍缺失时按被引用消息 `date` 有界回查当前绑定 Session |
+| 钉钉或 Telegram 缺少引用时间、历史已裁剪或候选不唯一 | 按 `not-delivered` 降级，不跨会话、不扩大窗口、不猜测 |
+
+`replyTo` 解析失败是“附加上下文不可用”，不是“当前消息不可用”。因此不复用现有整条入站失败通知，避免用户的有效问题被丢弃。
+
+## 10. 测试方案
+
+### 10.1 公共单元测试
+
+- 无 `replyTo` 的纯文字、图片和文件消息生成的 Harness 入参与改造前一致。
+- 当前文字和引用文字各出现一次，作者和消息 ID 在有值时出现。
+- 文本内的 `</dsh_im_reply_to>`、控制字符、换行、中文和 emoji 不能破坏 Prompt 块。
+- 8,000 码点和 20 个附件之外的内容被稳定截断并标记。
+- `load` 只调用一次，成功后不出现在序列化结果中；404、403、超时和异常都得到稳定降级。
+- 引用对象中的二级引用不进入 Prompt。
+- 首条用户消息带引用时，Session 标题来自当前问题而不是引用块。
+
+### 10.2 公共行为回归
+
+- 被引用原文中的 `/new`、`/stop`、`/history`、`/model` 不执行。
+- 被引用原文中的数字、“是/否”或“同意”不回答问题/审批。
+- 访问策略和命令权限仍只依据当前发送者和当前消息。
+- 未授权、未 addressed、重复事件、本地命令、批量收集和已被交互状态机消费的消息不触发引用网络查询。
+- 引用解析失败后当前 Turn 仍只启动一次，不重复发送最终答案。
+- 当前图片/文件的下载、限额、工作区写入和清理保持原行为。
+
+### 10.3 九渠道 fixture
+
+每个渠道至少固化：
+
+1. 纯文本原消息 + 当前文字。
+2. 引用 bot 消息和引用普通用户消息。
+3. 只有图片/文件的原消息，验证附件摘要。
+4. 无引用消息的原有 fixture，验证无回归。
+5. 平台不同客户端或回调版本能构造的字段缺失情况。
+
+另外针对需查询的渠道：
+
+- Discord：有 `referenced_message`、缺快照 REST 成功、`null` 删除、403 和跨频道拒绝。
+- Slack：DM 的 `im:history`、多人私聊的 `mpim:history`、公开频道的 `channels:history`、私有频道的 `groups:history`、非 Thread 不查询和 scope 缺失降级。
+- 飞书：`parent_id` 优先、`root_id` 回退、同 `chat_id` 校验、消息撤回和 `im:message:readonly` 缺失；另覆盖 Card 1.0、CardKit 2.0 `json_card/property`、i18n 文本、二维 fallback、空卡片/占位文案，以及隐藏配置不泄漏。
+- 微信个人号：覆盖 `type=8 + text_item` 的形状优先解析、未知类型纯元数据空壳、真实 64 位消息 ID 时间解码、出站索引持久化、同一用户隔离、ID 精确匹配、15 秒唯一时间匹配、索引缺失时的当前 Session 有界回查、成功回填和歧义拒绝。
+- 钉钉：覆盖 `interactiveCard` 占位符、`originalProcessQueryKey` 精确索引命中、索引建立前消息的当前 Session 有界回查、卡片实例 ID 登记、会话隔离和歧义拒绝。
+- Telegram：覆盖 `reply_to_message.text/caption`、`quote.text` 回退、只有消息 ID/date 时的延迟加载、当前绑定 Session 有界回查、会话隔离和歧义拒绝。
+
+### 10.4 真实客户端验收
+
+九渠道分别在现有账号可构造的私聊/群聊中验证：
+
+- 引用用户文本、bot 文本和带附件消息。
+- 引用文本内有命令样式时不执行命令。
+- 群聊中现有 @/回复 bot 触发边界不变。
+- 飞书、Slack 和 Discord 查询失败后当前问题仍然有答案。
+- Slack 重新授权后分别验证 DM、公开频道和私有频道。
+- 钉钉覆盖桌面端/移动端可构造的单行、多行、图片和富文本引用。
+
+不得把 mock 通过记录成九渠道真机已验收；缺少账号或场景时在验收记录中单独列出。
+
+## 11. 实施顺序
+
+1. **公共层**：先实现 `reply-reference.mjs`、Session 标题和公共单测，锁定 Prompt 协议。
+2. **回调快照渠道**：企业微信、QQ、WhatsApp、Telegram、微信个人号、钉钉、Discord `referenced_message`。这一步不新增网络请求。
+3. **延迟查询渠道**：飞书、Slack 和 Discord REST 回退，优先验证“未授权/命令不查询”。
+4. **回归与真机**：执行九渠道定向测试、`npm run check`，再完成真实客户端验收和验收记录。
+
+每一步保持小提交。微信个人号状态文件新增字段对旧版本是可忽略的可选字段；回滚代码不需要迁移或清理该字段。
+
+## 12. 验收清单
+
+- [x] 九渠道都能把可获取的引用文本放入 `<dsh_im_reply_to>`。
+- [x] 无引用消息的 Harness 入参和现有用户体验不变。
+- [x] 被引用内容不参与命令、访问、问题、审批和批量收集判定。
+- [x] 查询只在去重、addressed、访问控制和本地交互之后发生。
+- [x] 飞书/Slack/Discord 查询仅读当前会话，失败不中断当前 Turn。
+- [x] 不展开二级引用，不下载历史媒体实体，不新增数据库/设置项；微信仅使用有数量、时效和用户隔离边界的最近出站索引，以及当前 Session 的有页数/条数/超时/唯一性边界的历史回查。
+- [x] Slack Manifest 已补齐 history scopes，缺 scope 会降级为 `permission-denied`。
+- [x] 九渠道定向测试和 `npm run check` 全部通过。
+- [x] 真实客户端验收项与未验收项有明确记录。
+
+### 12.1 实施与验收记录（2026-09-01 至 2026-09-02）
+
+- 实现以 v4.5.0 / `c2be238` 为基线，工作树内完成公共 `replyTo` 语义、六处 Prompt 入口和九渠道薄适配；没有新增依赖、数据库或设置项。微信随后增加了本节所述的有界最近出站索引。
+- 公共层与九渠道相关的定向测试全部通过；追加飞书 CardKit、微信真实消息 ID、钉钉 AI Card 索引/Session 恢复，以及 Telegram TextQuote/Session 恢复回归后，最终 `npm run check` 为 2072/2072 通过，并通过发布包产物校验。
+- 独立静态审计未发现 P0–P2 问题；审计中发现的 Slack 缺 scope、Discord 跨频道快照和飞书缺失 `chat_id` 三个边界均已修复并补测试。
+- 本地 Web profile 直接链接当前源码；重新构建并重启 Host 后，9 个飞书机器人长连接均恢复就绪。
+- 飞书真实客户端：“今天是牢梁”私聊验收已通过。先发送唯一校验码原文 `QREF-9A7K-260901`，确认 bot 收到后执行 `/new`；在新 Harness Session 中引用该原消息，发送不含校验码的“请只返回被引用原消息里的校验码，不要添加其他文字。”，bot 精确返回 `QREF-9A7K-260901`。验收时间：2026-09-01 23:20 CST（UTC+8）。
+- 飞书旧机器人 CardKit 回归已通过：引用 22:20 发送、且位于此前 Harness Session 的旧 bot 卡片，询问其中的底层模型，bot 精确返回 `GLM`。这验证了修复可读取当前 CardKit 实体原文，且无需处于同一个 Harness Session；安全边界是引用目标仍属于当前飞书 `chat_id`。验收时间：2026-09-01 23:47 CST（UTC+8）。
+- 微信个人号真实失败已定位到腾讯 iLink 的机器人引用元数据空壳：公共层收到的 `replyTo` 只有 `unavailableReason`，不是 Harness Session 隔离。最终兼容修复记录成功发送的机器人文字，并从真实 64 位消息 ID 解码毫秒时间；索引未命中时只回查当前绑定 Session，最多 3 页×100 条、5 秒，匹配窗口 15 秒且要求唯一。索引仍为 200 条、30 天、8,000 码点/条，按微信用户隔离；命中历史后按真实微信消息 ID 自动回填。
+- 微信真机新消息引用验收通过：发送 `WXQ-20260902-REFTEST-01` 后引用该机器人回复，Session 中的 `<dsh_im_reply_to>` 精确包含相同 `content`，机器人也精确返回校验码。随后人为移除该校验码的两条最近出站索引并重启 Host，再次引用消息 ID `7500595754332471560`；Session 历史回查成功、同一内容进入 Prompt，状态文件自动回填该真实 ID。验收时间：2026-09-02 00:49–00:58 CST（UTC+8）。
+- 微信真机旧消息回归通过：再次引用此前失败截图中的旧机器人消息 ID `7500581098742245128`，其完整 DeepSeek V4 Flash 配置原文进入 `<dsh_im_reply_to>`，机器人正确概括内容；该消息随后以真实 ID 和原时间回填索引。用户已手工确认结果 OK。验收时间：2026-09-02 00:58 CST（UTC+8）。
+- 微信最终修复后重新执行 `npm run check`：构建、2068/2068 项测试和发布包产物校验全部通过；本地 Web Host 已重启并由新进程监听 3080。
+- 钉钉真实客户端验收通过：先让机器人返回唯一校验码，再引用该 AI Card 并要求只返回被引用消息中的校验码，机器人准确返回；不再出现 `[Interactive Card Message]` 导致的 `unsupported`。验收时间：2026-09-02（UTC+8）。
+- Telegram 真实客户端验收通过：先让机器人返回唯一校验码，再引用该回复并要求只返回被引用消息中的校验码，机器人准确返回；不再出现只有消息 ID/作者而正文为 `not-delivered`。验收时间：2026-09-02（UTC+8）。
+- 钉钉与 Telegram 最终修复后重新执行 `npm run check`：构建、2072/2072 项测试和发布包产物校验全部通过；本地 Web Host 已重启并由新进程监听 3080。
+- Slack、Discord、WhatsApp、企业微信和 QQ 本轮只完成自动化 fixture，未记录为真机验收；其中 Slack scope 变更仍需应用重新授权后验证。钉钉本轮已完成 AI Card 文本引用真机验证，单行、多行、图片和富文本的完整矩阵仍可后续补充。
+
+## 13. 核对依据
+
+- 本仓库 `src/channels/shared/text-harness-bridge.mjs`、`workspace-session.mjs`、`image-prompt.mjs`、`inbound-file.mjs` 和六处 Bridge 现有 Harness 入口。
+- 企业微信 `@wecom/aibot-node-sdk@1.0.7` 的 `BaseMessage.quote / QuoteContent` 类型。
+- QQ `@tencent-connect/qqbot-nodejs@1.0.4` 的 `refMsgIdx / msgElements` 映射和 `quote-ref` 中间件实现。
+- WhatsApp `@whiskeysockets/baileys@7.0.0-rc14` 的 `contextInfo.quotedMessage`。
+- [Telegram Bot API：Message](https://core.telegram.org/bots/api#message)。
+- [Discord Message Resource](https://docs.discord.com/developers/resources/message)。
+- [Slack conversations.history](https://api.slack.com/methods/conversations.history)。
+- 飞书 `@larksuiteoapi/node-sdk@1.73.0` 的 `im.v1.message.get`、`card_msg_content_type: 'raw_card_content'`，以及入站事件中的 `parent_id / root_id / thread_id`；CardKit 实际返回按 `json_card` 与逐层 `property` 包装解析。
+- [钉钉官方 Go Stream SDK 仓库的真实引用回调样本](https://github.com/open-dingtalk/dingtalk-stream-sdk-go/issues/22)。
+- [腾讯 openclaw-weixin 的 `MessageItem.ref_msg / RefMessage`](https://github.com/Tencent/openclaw-weixin/blob/main/src/api/types.ts)。
+- [腾讯 openclaw-weixin Issue #23：引用机器人消息只返回 `type=8` 元数据](https://github.com/Tencent/openclaw-weixin/issues/23)。
+
+上游平台和 SDK 会继续演进。实施时以本项目锁定依赖、实际回调 fixture 和官方 API 响应为准，不依赖未经观测的隐式字段。
--- a/docs/方案/入站图片非视觉模型文件回退方案.md
+++ b/docs/方案/入站图片非视觉模型文件回退方案.md
@ -0,0 +1,201 @@
+# 入站图片非视觉模型文件回退方案
+
+> 状态：已实施（P0）；Ubuntu CI、包产物验证与真实宿主非视觉模型端到端验收通过
+>
+> 日期：2026-09-01
+>
+> 关联：[出站图片原生呈现落地方案](./出站图片原生呈现落地方案.md)、[渠道原生能力建设方案](./渠道原生能力建设方案.md)
+
+## 1. 结论
+
+IM 对话中，非视觉模型收到图片时当前是**准入即硬失败**：图片字节在宿主 `session.prompt` 准入检查处被整体丢弃，LLM 收不到任何内容；而发送文件（如 zip）却能成功。本方案不改宿主、不新建媒体框架，只做一件事：
+
+**当宿主以 `MODEL_DOES_NOT_SUPPORT_IMAGES` 拒绝带图片的 prompt 时，dsh-im 自动把同一批图片字节转入现有入站文件管线（落盘到 Session 工作区 + `<dsh_im_files>` 清单），替换掉多模态内容块后重发一次 prompt。**
+
+效果：
+
+1. 非视觉模型不再对图片报错；图片以工作区文件形式到达 Agent，Agent 可用 `run_code`/`pwsh`（读字节、EXIF、OCR、图像库等）"以其他方式识图"。
+2. 视觉模型行为完全不变（继续原生多模态内容块）。
+3. 其他图片错误（超大、格式不支持、下载失败等）继续走现有报错，不回退。
+4. 收口在 `harness-client.mjs` 的 `ask()` 单点，九渠道 Bridge 无需各自改动。
+
+与出站方案同样的原则：复用现有 `inbound-file` 生命周期（落盘、清单、turn 结束清理），不新增配置开关、不新增产物类型。
+
+### 1.1 实施结果（2026-09-01）
+
+本方案已按上述最小边界落地：
+
+- `src/channels/shared/image-prompt.mjs` 新增 `IMAGE_FILE_FALLBACK_PROMPT`（模型侧指引，含英文翻译）、`imageFileSourcesFromContent()`（图片内容块 → 文件源，含扩展名映射与文件名清洗）、`contentWithoutImages()`、`isModelImageRejection()`。
+- `src/channels/shared/harness-client.mjs` 的 `ask()` 将原入站文件落盘逻辑抽为 `#stageWorkspaceFiles()`；`session.prompt` 被以 `MODEL_DOES_NOT_SUPPORT_IMAGES` 拒绝且 content 含图片块时，把同一批字节经该管线落盘、重建纯文本 prompt（原文本 + 指引 + 合并后的单个 `<dsh_im_files>` 清单）并复用同一 `promptRpcId` 重试一次；重试不再回退，落盘失败时保留原始错误文案。staged 批次统一进入既有 turn 结束清理。
+- `test/image-fallback.test.mjs` 新增 9 个用例：转换/判定辅助函数、完整回退（复用 rpcId、字节一致、清单正确、turn 后清理）、混合消息合并清单、非模型原因不回退、落盘失败保留原错误、落盘期间保留调用方取消语义、重试失败不再重试、纯文本路径不变。
+- 回归：Windows 本机以逐文件直跑方式执行全部 137 个测试文件，失败集与改动前基线（git worktree 对照）完全一致（23 个均为仓库既有的 Windows/沙箱环境性失败，CI 在 ubuntu 上通过）；`npm run build` 通过；`verify-package` 的可执行位检查在 Windows 上为既有环境性失败。
+- 端到端：在真实 DSH 宿主进程内通过生产 `apiProxy` 与 `fileIngressExecutor` 链路向文本模型注入入站 PNG，验证了宿主拒绝、图片落盘、纯文本重试与模型工具分析的完整路径。
+
+## 2. 现状与根因
+
+### 2.1 入站文件链路（zip 能成功）
+
+```
+message.files ──► harness.ask(…, { files })
+                 └► fileIngressExecutor（宿主进程内执行）
+                    └► stageInboundFiles() 写入 <workspace>/.dsh-im/inbound/turn-XXXX/NN-名字（0600）
+                 └► appendInboundFilesToPrompt() 在 prompt 末尾追加 <dsh_im_files> JSON 清单（工作区相对路径）
+                 └► session.prompt（纯文本内容块）
+```
+
+- 代码：`src/channels/shared/inbound-file.mjs`（`stageInboundFiles`、`appendInboundFilesToPrompt`）、`src/channels/shared/harness-client.mjs` ask() 内 `inboundFiles` 分支、`plugin-src/host/harness-session-coordinator.mjs` 的 `createFileIngressExecutor`。
+- 纯文本 prompt 不依赖模型输入模态，任何模型都能收到路径清单，再用工具处理文件。
+
+### 2.2 入站图片链路（被拦截）
+
+```
+message.images ──► promptContentForMessage()（Bridge 内，含大小/数量/魔数校验）
+                  └► content = [{type:'text'}, {type:'image', mediaType, data: base64}]
+                  └► session.prompt RPC
+                     └► 宿主 dsh-host-apiproxy prompt 准入：
+                        resolveModelInfo(provider, model).inputModalities 不含 'image'
+                        ──► 返回 attachment-error / MODEL_DOES_NOT_SUPPORT_IMAGES
+                        （发生在 createUserMessage 之前，未产生任何 durable 消息）
+                  └► HarnessRpcError 冒泡回 Bridge
+                  └► imagePromptUserMessage() 翻译为用户文案：
+                     "当前模型不支持图片，请用 /models 查看可用模型，再用 /model <序号> 切换后重发。"
+```
+
+- 代码：`src/channels/shared/image-prompt.mjs`（`promptContentForMessage`、`HOST_ATTACHMENT_USER_MESSAGES`）；宿主侧为 `@deepseek-ai/dsh-host-apiproxy` prompt handler（`hasImage` → `resolveModelInfo` 检查 → `err`）。
+- 六个图片构建点（共享 `text-harness-bridge.mjs` 及飞书/QQ/钉钉/微信/企业微信各自 Bridge）全部经 `harness.ask()` 收口，因此回退只需改一处。
+
+### 2.3 不对称的根源
+
+| 维度 | 文件（zip） | 图片 |
+| --- | --- | --- |
+| 交付形态 | 工作区路径文本 | 多模态内容块 |
+| 对模型能力的要求 | 无 | `inputModalities` 含 `image` |
+| 失败时的降级 | 不适用 | **无**（直接丢弃字节） |
+
+另一个限制：`session.models` / `llm.models` 返回的模型目录只有 `id/name/description/reasoning`，**不含输入模态**，dsh-im 无法预判当前模型是否支持图片；唯一的信号就是宿主拒绝时的 `MODEL_DOES_NOT_SUPPORT_IMAGES` 错误码——这也正是回退的触发器。
+
+## 3. 设计原则
+
+1. **图片字节必须到达 Session 工作区**，而不是被丢弃——这是"非视觉模型以其他方式识图"的前提。
+2. **不修改宿主**。`@deepseek-ai/dsh-host-apiproxy` 是安装的 npm 包，改了会被升级覆盖；宿主侧改进作为上游建议另行反馈（见 §7）。
+3. **复用入站文件管线**，不创建第二条图片生命周期：同样的目录结构、权限（0600）、turn 结束清理语义。
+4. **单点收口**：回退逻辑只存在于 `harness-client.mjs` `ask()` 内，所有渠道自动获益。
+5. **不新增配置开关**：对 `MODEL_DOES_NOT_SUPPORT_IMAGES` 的回退严格优于硬失败，默认启用；其余错误原因维持现有行为。
+6. **至多重试一次**，防止错误码异常时的循环。
+
+## 4. 方案设计
+
+### 4.1 触发条件
+
+在 `ask()` 中包装 `session.prompt` 调用，捕获 `HarnessRpcError`，当且仅当：
+
+- `error.code === 'attachment-error'` **且**
+- `error.details.reason === 'MODEL_DOES_NOT_SUPPORT_IMAGES'` **且**
+- 本次 `content` 含 `{type:'image'}` 内容块
+
+进入回退；否则原样抛出。
+
+### 4.2 图片 → 文件源转换
+
+从被拒 `content` 的 image 内容块直接构造文件源（字节已在内存，**无第二次网络下载**）：
+
+```js
+// image-prompt.mjs 新增 helper（图片知识内聚；stageInboundFiles 无需改动）
+const IMAGE_EXTENSIONS = new Map([
+  ['image/png', '.png'],
+  ['image/jpeg', '.jpg'],
+  ['image/gif', '.gif'],
+  ['image/webp', '.webp'],
+]);
+
+export function imageFileSourcesFromContent(content) {
+  return content
+    .filter((part) => part?.type === 'image')
+    .map((part, index) => ({
+      name: part.name ?? ('image-' + (index + 1) + (IMAGE_EXTENSIONS.get(part.mediaType) ?? '.img')),
+      mediaType: part.mediaType,
+      data: Buffer.from(part.data, 'base64'),
+    }));
+}
+```
+
+- `stageInboundFiles` 的 `loadedFile()` 已接受 `{data: Buffer, name, mediaType}` 形态，无需改动即可落盘。
+- `storageName()` 已做文件名清洗；扩展名映射保证下游工具能按扩展名识别格式。
+- 大小限制天然满足：`promptContentForMessage` 已按单张 5MB / 总量 20MB / 20 张校验过，转换不放大。
+
+### 4.3 重发 prompt
+
+1. 保留 append 文件清单**之前**的 `basePrompt`（当前代码在 ask() 内先 `prompt = appendInboundFilesToPrompt(prompt, stagedInboundFiles)` 再发 prompt；回退需从原始 prompt 重建，避免出现两个 `<dsh_im_files>` 块）。
+2. 新 `content` = 原 text 内容块 + 回退提示文本 + 合并后的单个 `<dsh_im_files>` 清单（原 staged 文件 + 图片文件，一次 `appendInboundFilesToPrompt` 生成）。
+3. 提示文本（走 `t()`，中英双语）：
+
+```
+当前会话模型不支持直接接收图片输入。用户发送的图片已作为文件保存到工作区（见下方清单）。
+请使用可用工具分析这些图片文件后回答，例如 run_code/pwsh 读取字节、解析元数据、
+调用图像处理或 OCR 库；不要假设自己能直接看到图片内容。
+```
+
+4. 再次调用 `session.prompt`（此时内容为纯文本，宿主不再走图片准入分支，也不受 `serializeImageAdmission` 串行化影响）。
+
+### 4.4 生命周期与安全
+
+- **幂等**：宿主检查发生在 `createUserMessage` 之前，被拒的 prompt 未入队、未产生 durable 消息，重发不会造成重复消息或空 turn。
+- **清理**：图片文件与现有入站文件同语义——turn 结束后由既有 `stagedInboundFiles.cleanup()` 一并删除（回退实现需把图片 staged 结果并入同一清理集合；重试仍失败时立即清理）。
+- **降级失败**：若 `#fileIngressExecutor` 不可用（`inbound-file-ingress-unavailable`）或落盘失败，则不重试，按现有链路向用户报错（保留 `MODEL_DOES_NOT_SUPPORT_IMAGES` 的既有文案作为兜底，可追加"图片转文件失败"说明）。
+- **旧宿主兼容**：错误码不存在时（旧版本宿主不检查模态或行为不同）回退不触发，行为与今天一致。
+
+### 4.5 用户可见行为
+
+- 回退成功后**不再报错**，Agent 正常处理并回复；可选（P1）：通过现有 `onUpdate` 流在开头推一条一次性提示"当前模型不支持直接识图，已将图片保存为工作区文件进行工具分析"，让用户知情。
+- `/models` 文案与 `HOST_ATTACHMENT_USER_MESSAGES` 映射保留：仅在回退自身失败时作为兜底呈现。
+
+### 4.6 改动清单
+
+| 文件 | 改动 | 量级 |
+| --- | --- | --- |
+| `src/channels/shared/harness-client.mjs` | ask() 内 `session.prompt` 包回退：触发判断、保留 basePrompt、图片落盘、清单合并、重试一次、清理集合 | ~80 行 |
+| `src/channels/shared/image-prompt.mjs` | 新增 `imageFileSourcesFromContent()`、扩展名映射 | ~30 行 |
+| `src/channels/shared/inbound-file.mjs` | （若需要）导出合并两个 staged 清单的 helper | ~10 行 |
+| `src/channels/shared/i18n-en/*.mjs` | 回退提示文本英文翻译 | 若干 |
+| `test/image-fallback.test.mjs`（新增）、`test/inbound-file.test.mjs` | 见 §6 | ~150 行 |
+
+## 5. 备选方案对比
+
+| 方案 | 说明 | 取舍 |
+| --- | --- | --- |
+| **A. 客户端响应式回退（本方案）** | 收到 `MODEL_DOES_NOT_SUPPORT_IMAGES` 后转文件重发 | ✅ 不改宿主、单点收口、旧宿主兼容；代价是多一次被拒往返 |
+| B. 宿主准入降级 | apiproxy 在准入处把 image part 换成附件路径文本而非拒绝 | 效果最好（所有 API 客户端获益），但改的是安装的 npm 包，升级即丢；建议作为上游 issue 反馈，dsh-im 不依赖它 |
+| C. 模型目录暴露 `inputModalities` | 宿主在 `session.models`/`llm.models` 增加模态字段 | 可让 dsh-im 预判、直接走文件路径省一次往返，`/models` 可加视觉标记；需宿主支持，旧宿主下仍靠 A 兜底；作为上游建议一并反馈 |
+| D. 纯文案优化 | 不回退，只改报错文案教用户切换模型 | 不解决"非视觉模型识图可能性"被阻断的问题 |
+
+推荐：**本期实施 A**；B、C 作为上游反馈（对 DSH 宿主仓库提 issue），A 在 C 落地后仍作为旧宿主兜底保留。
+
+## 6. 测试与验收
+
+### 6.1 单元测试（新增 `test/image-fallback.test.mjs`，fake rpc/executor）
+
+1. 首次 `session.prompt` 返回 `attachment-error/MODEL_DOES_NOT_SUPPORT_IMAGES` → 断言：调用了第二次 prompt；第二次 content 无 image part；含 `<dsh_im_files>` 清单与回退提示文本；文件以正确扩展名写入 executor 收到的 sources；仅重试一次。
+2. 混合消息（图片+文件）→ 断言只出现**一个**合并后的 `<dsh_im_files>` 块。
+3. 其他拒绝原因（`IMAGE_TOO_LARGE`、`TOO_MANY_IMAGES` 等）→ 不回退，原错误冒泡，用户文案不变。
+4. 落盘失败时保留原始模型拒绝错误；落盘期间取消时保留调用方的取消原因。
+5. 回退 prompt 再次失败 → 仅报错一次，不继续重试。
+6. 纯文本/纯文件消息 → 不触发任何回退路径（回归）。
+7. turn 正常结束后 staged 图片文件被 cleanup（复用 `test/inbound-file.test.mjs` 的断言模式）。
+
+### 6.2 回归与手工验收
+
+- `npm run check` 全量通过。
+- 真实宿主端到端：文本模型收到图片后走完“模态拒绝 → 工作区文件落盘 → 纯文本重试 → 工具分析”链路并正常回复；视觉模型与普通文件消息的原有行为保持不变。
+
+## 7. 上游反馈（非本仓库范围）
+
+向 DSH 宿主（`@deepseek-ai/dsh-host-apiproxy`）反馈两个改进建议：
+
+1. prompt 准入遇到非视觉模型时，将 image part 降级为持久化附件路径文本（对应方案 B），使所有 IM/API 客户端天然获得该能力；
+2. 模型目录响应增加 `inputModalities`（对应方案 C），让客户端可预判并在 `/models` 中展示视觉能力标记。
+
+## 8. 分期
+
+- **P0（本期）**：方案 A 全部内容 + 单测 + 真机验收。
+- **P1**：回退触发时的用户可见一次性提示；`<dsh_im_files>` 清单 description 中补充"非视觉会话请用工具分析图片"的指引（依赖 C 落地后可精化为按模型分流）。
+- **P2**：上游 B/C 跟进结果回流后，评估是否保留响应式回退作为兜底（预期保留）。
--- a/docs/机器人命令.md
+++ b/docs/机器人命令.md
@ -0,0 +1,42 @@
+# 命令说明
+
+示例：先发送 `/models`，再发送 `/model 2` 切换到列表中的第 2 个模型；先发送 `/reasoninglist`，再发送 `/reasoning 2` 切换到当前模型的第 2 个推理等级；先发送 `/presetlist`，再发送 `/preset 2` 为当前机器人选择第 2 个 Agent Preset。其他命令示例：`/help`、`/new`、`/status`、`/version`、`/model deepseek-official/deepseek-v4-pro max`、`/reasoning --default`、`/preset marketing-jeep`、`/preset --default`、`/steer 只检查配置文件`、`/stop`、`/compact`、`/workspace /Users/alice/projects/my-app`、`/ws 2`、`/wsl`、`/sessionlist 2`、`/sessionlist /Users/alice/projects/my-app`、`/session session-id`、`/history` 或 `/history 5`
+
+Slack 桌面端若未注册同名的原生 Slash Command，会拦截直接以 `/` 开头的消息。此时请加一个前导空格发送，例如 ` /presetlist`、` /preset 2`、` /history` 或 ` /history 10`；插件命令层会去除首尾空白，执行效果与无空格命令相同。
+
+**飞书输入框的 `/` 命令面板**：机器人启动时，dsh-im 会调用飞书 `app_slash_commands` OpenAPI，把常用命令（`menu`、`new`、`help`、`status`、`compact`、`sessionlist`、`workspacelist`、`workspaces`、`wsl`、`ws`、`watch`、`unwatch`、`watchlist`、`archived`）注册成原生 Slash Command，这样在飞书单聊输入框输入 `/` 会弹出命令面板，点选即触发。命令列表由 dsh-im 自己持有并推送注册，不依赖 dsh/Harness 后端。扫码新建的应用会默认申请 `application:app_slash_command:read` 和 `application:app_slash_command:write`；已有应用可通过“补全权限”或私聊 `/repair` 增量补全并按飞书提示发布。注册后飞书客户端约有几分钟缓存延迟。该能力是尽力而为的，注册失败不会影响机器人消息收发。
+
+- `/help` 不需要参数，也不会创建会话；它会返回当前机器人支持的完整命令列表。
+- `/status` 不需要参数，也不会向模型发送消息或改变会话绑定；它用于确认当前机器人能够连接 DeepSeek Harness。
+- `/version` 不需要参数，也不会访问 Harness、创建会话或调用模型；它返回当前运行的 dsh-im 插件版本。
+- `/new` 只解除当前聊天在 dsh-im 中保存的会话绑定，不会删除、清空或归档旧 Session。下一条普通消息会在当前工作区创建并绑定一个新 Session。任务正在运行或等待问题、审批时，应先完成交互或使用 `/stop`，再使用 `/new`。
+- `/models` 不需要参数，也不会创建会话。它为 Harness 当前配置的全部可用模型分配序号，同时显示可稳定复制的 `Provider/模型ID`；某个 Provider 查询失败时，其他 Provider 的结果仍会显示。
+- `/model` 不带参数时查看当前会话的模型和推理等级；带参数时接受 `/models` 列出的序号或精确完整模型 ID，并可追加目标模型元数据公布的精确推理等级 ID，例如 `/model 2 max`。省略推理等级时，由 Harness 解析目标模型的当前默认值。聊天尚无会话时，有效的切换命令会创建并绑定一个空白会话，但不会触发模型回复。
+- `/reasoninglist` 和 `/reasonings` 完全等价，按当前模型的元数据列出可选推理等级并标记当前值和默认值。`/reasoning` 查看当前值；`/reasoning <序号或等级ID>` 接受列表序号或元数据中的精确 ID；`/reasoning --default` 让 Harness 重新采用当前模型的默认推理等级。所有 `/reasoning...` 命令都要求当前聊天已有 Session，不会自行创建 Session 或触发模型回复。
+- 正在运行任务或等待审批、问题回答时不能修改模型或推理等级；请等待完成，或先使用 `/stop`。修改从下一次模型请求起生效，并沿用 Harness 的默认保存语义：Harness 会尝试把已接受的模型和推理等级保存为以后新会话的默认选择，已有其他会话不受影响。含图片的会话无法切换到不支持图片输入的模型。
+- `/presetlist` 和 `/presets` 完全等价，不需要参数，也不会创建会话。它们每次都读取 Host 当前可用的 Agent Preset，显示名称、稳定 ID、Host 默认项和当前机器人的选择；已删除或损坏的当前选择会保留并标记为“已不可用”，不会被自动清除。列表只公开安全的名称和 ID，不公开 Preset 路径、错误或其他 Host 内部字段。
+- `/preset` 不带参数时查看当前机器人的“新会话设置”，不是查看或修改当前 Session。带参数时接受最近一次 `/presetlist` 在当前聊天中显示的序号或完整 ID；纯数字 ID 使用 `/preset id:<ID>`。选择序号时会先按该次列表解析 ID，再用 Host 最新目录复验，目录已经变化时会要求重新列出。
+- `/preset --default` 清除当前机器人的显式覆盖值，让以后新建的 Session 在创建时跟随 Host 当前默认；显式选择一个恰好等于 Host 默认的 ID 则会固定该 ID。目录暂时不可读时仍可恢复为跟随 Host 默认。
+- Agent Preset 修改是机器人级配置，会影响该机器人所有聊天以后创建的新 Session，但不会修改、停止、解绑或重建已有 Session，也不会自动执行 `/new`。若当前聊天已有会话，继续发送消息仍使用原 Session；发送 `/new` 后的下一条普通消息才会按新设置创建 Session。任务正在运行或等待交互时也可查询或修改 Preset，因为命令不会触碰当前 Session。
+- `/stop` 和 `/steer` 只控制当前聊天自己发起的运行任务，即使多个聊天绑定同一个 Session，也不会有意控制其他聊天的任务。`/stop` 不删除会话或历史，并保留尚未开始的排队消息；重复发送是安全的。
+- `/steer` 只接受文字，可包含多行；它不会创建新会话或第二个任务。没有运行任务时请直接发送普通消息；等待审批或问题回答时请先处理交互，或使用 `/stop`。
+- `/batch`、`/send` 和 `/cancel` 仅在与机器人的私聊中可用。发送 `/batch` 后，接下来的纯文字消息会暂存，最多 10 条；第 10 条仍会收录并提示提交，之后的消息不会收录，也不会自动提交。发送 `/send` 后，机器人会按原顺序将整批内容作为一次输入处理；发送 `/cancel` 会直接丢弃当前批次。图片、文件和其他命令不会被收录。机器人重启会丢失尚未提交的批次。未进入批量输入模式时，普通聊天流程不变。
+- 飞书 `/repair` 仅在私聊中可用，并与其他命令一样只服从当前飞书机器人的渠道访问策略；插件不另行区分管理员和普通用户。它增量补全当前缺少的 `card.action.trigger`、`im:message:readonly`、`im:resource`、`application:app_slash_command:read` 和 `application:app_slash_command:write`，确认页只显示当前应用缺少的项。授权页必须由在飞书开放平台中有权访问目标应用的账号打开。普通 `/repair` 会启动修复；若旧任务仍在等待授权，会先作废旧的一次性链接再生成新链接。发送 `/repair qr` 获取当前链接的二维码，`/repair status` 查询当前任务，`/repair verify` 重新查询验证状态，`/repair cancel` 取消任务；这四个补充命令均不会另起授权。平台已接受更新、正在等待测试按钮回调时，不会并发启动第二次修复。
+- `/compact` 只作用于当前聊天已经绑定的 Harness 会话，不会把命令发送给模型。当前聊天尚未创建会话、会话正在生成回复或没有可压缩历史时，机器人会直接返回对应状态。
+- 只接受已经存在的绝对目录；路径无效时机器人会返回具体提示和正确用法。
+- `/workspacelist`、`/workspaces` 和 `/wsl` 不需要参数且完全等价。它们合并 Harness 全局登记项与当前机器人的路径；当前路径仍存在且可安全显示时会排在首位并标记为“当前”。`/workspace N` 与 `/ws N` 都会在执行时按最新列表顺序切换，也可继续使用绝对路径。
+- `/sessionlist` 和 `/sessions` 完全等价。数字参数按命令执行时与 `/workspacelist` 相同的最新顺序解析；也可使用绝对路径直接指定工作区。结果会回显最终选中的路径。
+- `/sessionlist --limit N` 和 `/sessions --limit N` 只限制本次命令的返回条数，不改变任何全局或机器人配置。未指定 `--limit` 时仍列出全部会话。
+- 两个会话列表命令都会列出该工作区登记的所有会话。已归档会话会标记为“已归档”；空白会话和子代理会话在它们归属该工作区时也会列出；没有标题的会话显示为“暂无标题”。结果中的 ID 可直接用于 `/session Session ID`。
+- `/session` 只接受一个由 `/sessionlist` 获得的 Session ID。它不会新建会话或立即向模型发送消息；绑定成功后，当前聊天的后续消息会继续该会话。普通归档会话可以绑定但不会自动取消归档，子代理会话不能绑定。
+- `/history` 在九个渠道的私聊中统一可用，只读取当前聊天已经绑定的会话，不新建会话、不调用模型，也不影响正在运行的任务或待处理交互。默认返回最近 3 条；`/history N` 接受正整数，超过 5 自动按 5 条处理，数量不足时返回实际条数。零、负数、小数、非数字和多个参数会提示用法，附带图片或文件时会拒绝处理；批量输入收集中请先 `/send` 或 `/cancel`。
+- 历史预览中，一条用户消息或一条助手最终回复各算一条，不按轮次或天数计数。先取最新 N 条，再按从旧到新的顺序显示；不展示工具、推理、注入内容或尚未完成的助手片段，不下载或重发历史附件。长正文会截断并注明，全部结果最多发送 3 段文字，不自动翻页。绑定会话后可手动发送 `/history`，不会自动重发历史。正文仍可能包含会话原有的敏感信息，请只向可信用户开放机器人。
+- `/session` 会自动定位会话唯一所属的工作区。同工作区绑定只替换当前聊天的映射；跨工作区绑定会切换该机器人的工作区、清除该机器人所有聊天的旧会话映射，再绑定当前聊天，因此会影响该机器人的其他聊天。已经开始生成的回复仍可完成。
+- 工作区切换和会话绑定只会清除或替换 dsh-im 的聊天映射，不会删除、清空或归档任何旧 Session 内容；旧 Session 仍可再次列出和绑定。
+- 任何通过当前渠道访问策略的用户都可以执行这些命令，不另行区分管理员和普通用户。Telegram 兼容模式遵循原有私聊及群聊提及/回复规则；安全模式只允许当前机器人白名单中的私聊用户执行。WhatsApp 仅自己模式只接受自聊，指定联系人模式接受自聊和白名单私聊，开放响应模式接受所有私聊、已绑定账号自己发出的群聊消息，以及其他群成员的提及或回复。
+- Agent Preset 名称和 ID 来自同一个 Harness Host，且任何有命令权限的用户都能修改该机器人所有聊天未来新 Session 的 Preset；请只向可信用户开放 `/presetlist` 和 `/preset`。
+- 工作区列表来自 Harness Host 的全局登记信息，可能包含其他机器人、其他渠道或非 IM 项目的本机绝对路径。请将机器人可见范围限制给可信用户。
+- 会话列表同样来自该全局 Harness Host；会话 ID 和标题可能属于其他机器人、其他渠道或非 IM 项目，并可能包含敏感元数据。开放命令前请确保所有可见用户都可信。
+- 任何能执行 `/session` 的用户都能接续所选会话，并通过后续消息写入会话或触发其可用工具。请只向可信用户开放机器人及其会话列表。
+- 切换成功后只清除当前机器人的旧 Harness 会话映射，不影响其他机器人。
+- 新工作区对后续消息生效；已经开始生成的回复会继续完成。
--- a/docs/检查与安装更新.md
+++ b/docs/检查与安装更新.md
@ -0,0 +1,19 @@
+# 检查与安装更新
+
+在「设置 → IM机器人」右上角点击 GitHub 左侧的「检查更新」。只有点击后才查询 npm 官方源；发现新版后，确认目标版本和当前 profile 再安装。更新只涉及 `@xmanrui/dsh-im`，不拉取 GitHub，不更新 Harness 或 Desktop 本体。
+
+安装完成后，后台仍需手动重启，页面根据 Host 状态显示「已安装，待手动重启」。更新功能不会主动重启、执行热更新或刷新页面。宿主自带的模块监视机制可能自行刷新插件界面，但界面变化不代表后台版本已生效，运行版本以 Host 报告为准。请在机器人任务空闲时更新，并自行重启当前 Harness / Desktop。关闭设置页不会取消已提交的安装任务。
+
+手动重启后，如果原页面仍显示待重启，点击窗口中的「刷新状态」，或重新打开「待手动重启」窗口。该操作只重新读取当前 Host 状态，不查询 npm，也不刷新页面。
+
+按钮复用 Desktop 内置包管理服务或标准 Harness 的 CLI，执行相当于以下命令的精确版本安装（将示例 profile、版本替换为确认值）：
+
+```sh
+dsh plugin --profile web add -w --save-exact @xmanrui/dsh-im@3.1.0 --registry=https://registry.npmjs.org/
+```
+
+更新窗口下方的「手工更新」会按当前 profile 生成精简命令，例如 `dsh plugin --profile web add -w @xmanrui/dsh-im@3.1.1`，点击命令最右侧的复制图标后可在终端执行。已知目标版本时指定该版本；尚未查到版本时使用 `@latest`，以执行时 npm 返回的版本为准。手工命令沿用本机 npm 源配置，不拉取 GitHub；按钮安装仍固定使用官方源并保存精确版本。浏览器无法复制时可选中文本手动复制。Desktop 请使用当前 Desktop 的内置终端；Web 请使用启动当前 Harness 的环境并保持相同 `DSH_HOME`。如果已经提示「待手动重启」，通常只需重启，无需再次安装。源码链接或无法安全确认的 profile 不生成可能覆盖安装的命令。
+
+源码 `link:`、`file:`、Git 来源或无法确认归属的安装只提供版本检查，不会替换开发链接；如需迁移为 npm 安装，请自行确认对应 profile。作用域 registry 冲突、Node 版本不满足要求或缺少当前 Host 的执行器时，按钮会说明原因。标准 Windows CLI 暂需手动更新；Desktop 使用其原有执行器。
+
+安装期间不要同时在终端或插件市场修改该 profile。失败可能已经改变部分依赖，不能视为自动回滚；先检查安装状态，必要时按上述命令重装原精确版本，再手动重启。更新器只在当前 `DSH_HOME/updates/dsh-im` 下保存该 profile 最近一次任务与清单备份，不复制机器人凭据；残留安装进程或锁状态不明确时，请先人工确认，不要盲目重试或删除锁。
--- a/docs/访问模式.md
+++ b/docs/访问模式.md
@ -0,0 +1,5 @@
+# 访问模式
+
+每个 Telegram 机器人都可以在自己的卡片中切换访问模式。旧机器人和新接入机器人均默认使用**兼容模式**：私聊直接响应，群聊仅在提及机器人或回复机器人消息时响应。只有主动切换到**安全模式（私聊白名单）**后，机器人才会忽略全部群聊，并只接受该机器人白名单中的数字 User ID。白名单每行一个 ID、按机器人独立保存；切回兼容模式时会保留但不使用，再切回安全模式即可继续使用。安全模式的空白名单会拒绝该机器人的所有入站消息。
+
+每个 WhatsApp 机器人也有独立的访问模式。旧机器人升级后和新接入机器人都默认使用**仅自己模式**，只响应已绑定账号的自聊消息。**指定联系人模式**额外接受白名单电话号码的私聊并忽略群聊；号码需包含国家或地区代码，每行一个，可带开头的 `+`。**开放响应模式**响应所有私聊、已绑定账号自己发出的群聊消息，以及其他群成员对该账号的提及或回复；因此也可以把“仅自己”的群当作独立会话使用。切换模式会保留白名单；指定联系人模式的空白名单等同于仅自己模式。未授权消息会被静默忽略。