@jiang_li/dsh-im-companion 0.0.0-stage → 1.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-im-companion contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# dsh-im-companion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@jiang_li/dsh-im-companion` · [GitHub](https://github.com/zingreqe/dsh-im-companion) · MIT
+
+因为 `@xmanrui/dsh-im` 插件和 `dsh-onebot-qq` 插件均没有提供分段发送和自动发送的功能，为了使得使用这两个插件的dsh更加拟人，所以该插件给 `@xmanrui/dsh-im` 和 `dsh-onebot-qq` 补三块能力：
+
+1. **分段发送**：可以让大模型自行进行消息分段——它写的空行就是气泡边界。插件按段落逐条发出，前几段由本插件发送，最后一段仍交给 dsh-im 原链路，不会重复发送。不额外加提示词，因此不会覆盖或绕开系统提示词、其他插件的上下文注入。
+2. **自动发送**：按机器人配置时间窗、间隔、随机性和每日上限，可实现像真人那般主动给你发送消息，到点时插件在那个真实会话里发起一轮 Agent 轮次，会话自己的系统提示词、记忆和其他插件注入全部生效，回复也落回该会话，随后按段落逐条发到 IM。默认接着该机器人最新未归档的会话，也可以在面板里手动指定。
+3. **话题库**：提供一个 `topic_library` 工具，让模型把聊天里的话题、兴趣与偏好按「一级分类 / 二级分类 / 描述」收进来；支持入库敏感度、遗忘时间、固定话题，以及手动增删改。在主动给你发消息时可以选择注入已有话题，让大模型自动发的消息不会那么生硬。
+
+### 关于即时通讯（@xmanrui/dsh-im）
+该插件是一个聚合机器人服务插件，该插件支持微信、QQ、飞书、企业微信等等众多软件的机器人连接，优点是不会风控，缺点是因为是机器人而不是真实的账号，真实账号的功能机器人无法使用。本项目对该插件的功能提供了扩展，使其可以像真人一样发送消息。并且支持精确的机器人和会话设置。可以结合记忆插件和人格插件来打造你的小鲸鱼。（这里推荐一下我的另一个插件dsh-tools-manager，提供系统提示词覆写功能，可以在系统提示词注入你的小鲸鱼人格哦）
+
+### 关于QQ（dsh-onebot-qq）
+`dsh-onebot-qq` 是一个通过napcat连接真实qq号的插件，可以为大模型提供通过qq聊天的能力，但是不提供自动发送的功能，本插件统一了该插件的分段发送规则和添加了自动发送的功能，并可按照私聊账号进行管理。注意，使用该插件直接控制的真实QQ号容易被风控和封号，请不要使用大号连接。
+`dsh-onebot-qq` 不向宿主暴露服务，所以这里用两个缝：包装它的 `OutboundPipeline.prototype.sendToChat`，出站文本按空行拆成多条气泡（仍然走它自己的 Markdown 清理、转发块、t2i、队列与重连补发）；自动发送则在 `onebot-private-<QQ>` / `onebot-group-<群>` 这条真实会话里发一轮 Agent，面板中每个 QQ 私聊/群聊都是一张独立的卡片（`onebot:private:<QQ>` / `onebot:group:<群>`），可以同时给多个私聊开启自动发送，时间窗、间隔、随机性、每日上限、回复后静默和话题提示都各配各的；旧的单个「QQ（dsh-onebot-qq）」配置会自动迁移到它绑定的那条聊天上。活跃 QQ 会话的最终回复由 bridge 自己投递；冷会话（重启后还没收到过消息）bridge 不会投递，这时插件会在 6 秒后接管：先通过 `ChatBridge.prototype.onSessionEvent` 捕获到的 bridge 实例走它自己的出站闸门分段发送，bridge 还没出现时再退回 `qq_send_segments` 工具（每段切到 500 字以内、每批 9 段）。
+
+需要该 QQ 机器人之前至少和用户聊过一次（这样才存在绑定会话）；冷会话会在 30 秒内被索引出来。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @jiang_li/dsh-im-companion
+```
+
+装好后重启或重载 DSH。插件依赖 `@xmanrui/dsh-im` 和/或 `dsh-onebot-qq`：两者都没装时仍能加载，面板里只会显示空列表。本地开发时也可以把 `plugin_manager install_bundle` 指向源码目录（profile 里是软链接，方便热改）。
+
+## 使用
+
+装好后刷新 DSH Web 页面，点侧边栏的「主动消息」。面板分成两个页签：「发送设置」把每个机器人排成宫格里的一格，分段、提示词与运行记录各占整行；「话题库」只在切过去时加载和显示话题数据。
+
+- 分段发送：总开关、段间延迟范围、模拟打字速度（字数上限仅保留给旧的分段函数，IM 分组以模型段落为准）。
+- 自动发送：总开关，每个机器人一张卡片；发送会话（留空为「自动：最新未归档会话」）、时间窗（可跨夜）、间隔分钟、随机性 0–10、每日上限、回复后静默时长、时区、话题提示。
+- 消息提示词：一段自定义模板，作为用户消息追加进目标会话。支持 `{{time}}`、`{{weekday}}`、`{{date}}`、`{{topic}}`、`{{topics}}`、`{{topicHints}}`、`{{lastTexts}}`；面板上有占位符按钮，点一下插到光标处。「恢复默认」可回到内置模板。
+- 话题库：入库敏感度 0–10（0 时工具不会出现在模型上下文里）、遗忘天数（0 为不自动遗忘）、话题列表与手动编辑。
+- 「立即发一条」用当前草稿立即试发，不需要先保存，也不会重置表单里的其他改动。
+
+随机性映射：`0` 时实际间隔在 `[0, 2×间隔]` 内均匀随机，`10` 时严格固定间隔，中间线性过渡。
+
+发送会话留空时，每次发送前都会重新选「该机器人绑定的、最新活跃的未归档会话」，并在该会话里生成；手动选中某个会话后固定用它。会话里的触发消息使用 `im-proactive` 来源，dsh-im 的会话同步不会把触发词或回复再回显一遍。
+
+## 存储
+
+设置、话题库与运行状态在 `~/.dsh/dsh-im-companion.json`，原子写入。自动发送总开关、每个机器人的开关和发送会话改动会立即保存；其余字段在点「保存」时落盘。
+
+## 消息提示词
+
+模板会作为一条 `im-proactive` 用户消息追加进目标会话，不会替换系统提示词、记忆或其他插件的上下文注入；空行决定回复会被拆成几条气泡。各占位符的含义：
+
+| 占位符 | 内容 |
+| --- | --- |
+| `{{time}}` | 发送时刻（本地时间，如 `2026-11-02 18:27`） |
+| `{{weekday}}` / `{{date}}` | 星期几 / 日期 |
+| `{{topic}}` | 该机器人卡片里的「话题提示」 |
+| `{{topics}}` | 话题库里的分类与摘要（最多 40 条，固定项标 ★） |
+| `{{topicHints}}` | 最近关注的话题提示 |
+| `{{lastTexts}}` | 最近主动发过的内容，避免重复 |
+
+未填值的占位符会留空，多余空行会自动合并。
+
+## 实现方式
+
+Host 侧包装 `typertGateway.invoke`，只处理 dsh-im 的 owner peer（`interactions: 'none'`）发起的 `session.page` 请求：在包含 `turn/end` 的响应里注入合成 `assistant/message` 事件，把已发出的前缀段从 dsh-im 的最终答案里抹掉，只留下末段。Web UI 的会话传输不受影响。
+
+话题库用 `ctx.tools.register` 注册工具、`ctx.systemPrompt.section` 注入提示段；敏感度为 0 时注销工具，模型就看不到它了。
+
+自动发送走 `sessionController.commands.prompt(request, { kind: 'im-proactive' })`：这是真实的 Agent 轮次，不是另起一次模型调用，所以记忆、系统提示词和其他插件的上下文注入都按该会话的规则生效；dsh-im 的会话同步只镜像 `user` 来源，因此不会重复发送。
+
+读取回复用 `gateway.stream('session', 'follow')` 的 opening snapshot（`assistantStream` 字段只能缺省或为 `true`，传 `false` 会被 wire 边界校验拒绝）。注意 `session.page` 的 `throughSeq: -1` 不是“取最新一页”，而是 `min(-1+1, ...) = 0`，会返回空页；要用 `session.page` 时得先拿到 follow snapshot 的 `cursor` 再以它为 `throughSeq`。
+
+## 限制
+
+- 分段只对能解析出投递目标的 IM 会话生效；解析不到时本轮按原样整段发送。
+- QQ 的分段依赖包装 `lib/outbound.js`，兜底依赖捕获 bridge 实例或 `qq_send_segments` 工具；该包升级后如果改了类名或方法名，包装会失败并自动退回整段发送，不影响 bridge 本身。
+- 自动发送需要该机器人至少有一个已绑定的会话；一个都没有时只会在面板运行记录里提示，不会凭空新建会话。
+- 主动发送依赖渠道的主动投递能力与 `contextToken` 新鲜度；掉线或令牌失效会记录在面板的运行记录里。
+- 修改 Host 侧文件后要用 `set_bundle` 重挂一次（见下「改动与重载」），不需要重启整个 DSH。
+
+## 改动与重载
+
+- 改了 Host 侧（`index.js`、`src/*.mjs`）：用 `plugin_manager set_bundle` 禁用再启用会把插件重新 import（实测 Host 模块会重新执行），不必重启整个 DSH；不放心就重启。
+- 改了客户端半（`client.js`）：`dsh-client-modules` 只在包来源变化时重读文件。没有 `pnpm run dev:web` 看护时，刷新页面拿到的仍是旧 bundle；用 `plugin_manager set_bundle` 先把 `dsh-im-companion` 设为 `enabled:false` 再设回 `true`，让 Loader 条目重挂即可，随后刷新页面。
+- `plugin_manager install_bundle` 对已安装的包会返回 `already-installed`，升级版本号也不会覆盖安装；要么先 `remove_bundle` 再装，要么直接改源码（profile 里是软链接）。