From 56229869bf03301a70ed703462f4e06f4f585aca Mon Sep 17 00:00:00 2001 From: xmanrui <841206367@qq.com> Date: Thu, 20 Aug 2026 01:59:56 +0800 Subject: [PATCH] docs: document bot interactions and features --- README.en.md | 21 ++++++++++++++++++++- README.md | 21 ++++++++++++++++++++- 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/README.en.md b/README.en.md index 73b119c..442c116 100644 --- a/README.en.md +++ b/README.en.md @@ -98,6 +98,9 @@ When a channel does not explicitly configure `agentPreset`, each new IM session | Command | Description | | --- | --- | +| `/help` | Show the commands and usage supported by the bot. | +| `/new` | Unbind the current chat so its next ordinary message starts a new Harness Session. | +| `/status` | Check the connection between the current bot and DeepSeek Harness. | | `/models` | List every currently configured model, grouped by provider. | | `/model` | Show the model used by the Session bound to this chat. | | `/model ` | Switch the model for the Session bound to this chat. | @@ -108,9 +111,16 @@ When a channel does not explicitly configure `agentPreset`, each new IM session | `/workspacelist` | List workspace absolute paths that still exist on the current Harness Host. | | `/sessionlist [workspace number or absolute path]` | List every registered session ID and title in the selected workspace; omit the argument to use the current workspace. | | `/session ` | Bind the current chat to an existing Harness session. | +| Interactive question | Reply with an option number, option label, or custom text; separate multiple choices with commas. | +| Remote approval | Reply with `批准` / `拒绝` / `同意` / `不同意` / `yes` / `no`. | -Examples: `/models`, `/model deepseek-official/deepseek-v4-pro`, `/steer inspect only the configuration file`, `/stop`, `/compact`, `/workspace /Users/alice/projects/my-app`, `/sessionlist 2`, `/sessionlist /Users/alice/projects/my-app`, or `/session session-id` +Examples: `/help`, `/new`, `/status`, `/models`, `/model deepseek-official/deepseek-v4-pro`, `/steer inspect only the configuration file`, `/stop`, `/compact`, `/workspace /Users/alice/projects/my-app`, `/sessionlist 2`, `/sessionlist /Users/alice/projects/my-app`, or `/session session-id` +### Command details + +- `/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. +- `/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 lists every currently configured Harness model using stable, copyable `provider/model-id` values. If one provider fails, models from the remaining providers are still shown. - Bare `/model` only displays the current Session model. `/model ` accepts an exact value returned by `/models`. When the chat has no Session yet, a valid switch creates and binds a blank Session without prompting the model. The switch affects only that Session; Harness also attempts to save it as the default for future Sessions, while other existing Sessions remain unchanged. - A model cannot be switched while a task is running or waiting for an approval or question answer. Wait for it to finish or use `/stop` first. A Session containing images cannot switch to a model that does not accept image input. @@ -131,6 +141,15 @@ Examples: `/models`, `/model deepseek-official/deepseek-v4-pro`, `/steer inspect - 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. +## Other features + +- **Image understanding**: all nine built-in channels can send JPEG, PNG, WebP, and GIF files sent as images to Harness, with an optional text description. Each image is limited to 5 MB, and all images in one message are limited to 20 MB in total. +- **Switch workspaces from a bot card**: every bot card on the settings page shows its current Harness workspace. Enter an existing absolute directory path directly or open the directory picker. Switching clears only that bot's old chat mappings; it never deletes, empties, or archives old Sessions. Replies already in progress may finish, while later messages use the new workspace. +- **Check the connection and send a test message**: when a bot is online, clicking **Check connection** verifies the platform connection and sends a “DeepSeek Harness connection test succeeded” message to the bot's most recently remembered direct conversation; WhatsApp uses the account's self-chat. The test neither creates a Harness Session nor invokes the model. The bot must have received at least one direct message before it has a remembered test target; otherwise the page reports that no test conversation is available yet. +- **Retry a connection or remove an integration**: when a bot is offline, its card action changes to **Retry connection**. Use **Remove integration** when the bot is no longer needed. Each action affects only the selected bot and leaves other bots and channels unchanged. +- **Manage multiple bots independently**: a channel can have multiple connected bots. Credentials, connection state, workspace, and chat-to-Session mappings are kept separately for every bot, so card actions do not affect sibling bots. +- **Streaming replies and progress**: the plugin uses each platform's available capabilities to show thinking state, tool progress, and incremental answers. Platforms without a native streaming API complete replies through message edits, card updates, or a final message. + ## Design - Registers a single **IM Bot** settings page in Harness. diff --git a/README.md b/README.md index c1fd734..a525b1f 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,9 @@ QQ 扫码接入使用腾讯 QQBot v2 官方流程。默认腾讯授权页会把 | 命令 | 作用 | | --- | --- | +| `/help` | 显示机器人支持的命令和用法。 | +| `/new` | 解除当前聊天的会话绑定，让下一条普通消息开启全新 Harness 会话。 | +| `/status` | 检查当前机器人与 DeepSeek Harness 的连接状态。 | | `/models` | 按 Provider 列出当前配置的全部可用模型。 | | `/model` | 查看当前聊天绑定会话正在使用的模型。 | | `/model ` | 切换当前聊天绑定会话的模型。 | @@ -111,9 +114,16 @@ QQ 扫码接入使用腾讯 QQBot v2 官方流程。默认腾讯授权页会把 | `/workspacelist` | 列出当前 Harness Host 上仍然存在的工作区绝对路径。 | | `/sessionlist [工作区序号或绝对路径]` | 列出指定工作区登记的所有会话 ID 和标题；省略参数时使用当前工作区。 | | `/session ` | 将当前聊天绑定到指定的已有 Harness 会话。 | +| 交互式提问 | 回复选项序号、选项文字或自定义文字；多选时用逗号分隔。 | +| 远程审批 | 回复 `批准` / `拒绝` / `同意` / `不同意` / `yes` / `no`。 | -示例：`/models`、`/model deepseek-official/deepseek-v4-pro`、`/steer 只检查配置文件`、`/stop`、`/compact`、`/workspace /Users/alice/projects/my-app`、`/sessionlist 2`、`/sessionlist /Users/alice/projects/my-app` 或 `/session session-id` +示例：`/help`、`/new`、`/status`、`/models`、`/model deepseek-official/deepseek-v4-pro`、`/steer 只检查配置文件`、`/stop`、`/compact`、`/workspace /Users/alice/projects/my-app`、`/sessionlist 2`、`/sessionlist /Users/alice/projects/my-app` 或 `/session session-id` +### 命令说明 + +- `/help` 不需要参数，也不会创建会话；它会返回当前机器人支持的完整命令列表。 +- `/status` 不需要参数，也不会向模型发送消息或改变会话绑定；它用于确认当前机器人能够连接 DeepSeek Harness。 +- `/new` 只解除当前聊天在 dsh-im 中保存的会话绑定，不会删除、清空或归档旧 Session。下一条普通消息会在当前工作区创建并绑定一个新 Session。任务正在运行或等待问题、审批时，应先完成交互或使用 `/stop`，再使用 `/new`。 - `/models` 不需要参数，也不会创建会话。它列出 Harness 当前配置的全部可用模型，使用可稳定复制的 `Provider/模型ID`；某个 Provider 查询失败时，其他 Provider 的结果仍会显示。 - `/model` 不带参数时只查看当前会话模型；带完整模型 ID 时只接受 `/models` 列出的精确值。聊天尚无会话时，有效的切换命令会创建并绑定一个空白会话，但不会触发模型回复。切换只影响当前会话；Harness 还会尝试把它保存为以后新会话的默认模型，已有其他会话不受影响。 - 正在运行任务或等待审批、问题回答时不能切换模型；请等待完成，或先使用 `/stop`。含图片的会话无法切换到不支持图片输入的模型。 @@ -134,6 +144,15 @@ QQ 扫码接入使用腾讯 QQBot v2 官方流程。默认腾讯授权页会把 - 切换成功后只清除当前机器人的旧 Harness 会话映射，不影响其他机器人。 - 新工作区对后续消息生效；已经开始生成的回复会继续完成。 +## 其它功能 + +- **图片识别**：九个内置渠道都可以把 JPEG、PNG、WebP，以及以图片文件方式发送的 GIF 交给 Harness；图片可以附带文字说明。单张图片上限为 5 MB，单条消息中的图片总大小上限为 20 MB。 +- **在机器人卡片切换工作区**：设置页中的每张机器人卡片都会显示当前 Harness 工作区。可以直接填写已有目录的绝对路径，也可以打开目录选择器。切换只清除该机器人的旧聊天映射，不会删除、清空或归档旧 Session；已经开始的回复可以继续完成，后续消息使用新工作区。 +- **检查连接并发送测试消息**：机器人在线时，点击卡片上的「检查连接」会检查平台连接，并向该机器人最近记录的私聊发送一条“DeepSeek Harness 连接测试成功”消息；WhatsApp 会发送到账号自聊。测试消息不会创建 Harness Session，也不会调用模型。机器人必须至少收到过一条私聊才能记住测试目标，否则页面会提示尚无可用的测试会话。 +- **重试连接和移除接入**：机器人离线时，卡片上的操作会变为「重试连接」；不再使用时可以点击「移除接入」。这些操作都只作用于所选机器人，不影响其他机器人或渠道。 +- **多机器人独立管理**：同一渠道可以接入多个机器人。每个机器人分别保存凭据、连接状态、工作区和聊天会话映射，卡片上的工作区、连接检查、重试和移除操作互不影响。 +- **流式回复和进度提示**：插件会按各平台能力显示正在思考、工具执行和逐步生成的回答；不支持原生流式接口的平台会通过编辑消息、卡片更新或最终消息完成回复。 + ## 设计 - Harness 中只注册一个「IM机器人」设置页；