DSH-bot

dsh-botplugin

把 Telegram / 微信变成 DSH 的聊天入口的插件。三大功能：Telegram 入口、微信入口、handoff 记忆接续，外加语音转文字。

🔰 第一次接触、想知道"这东西到底能干什么" → 先看 功能说明.txt（大白话版，不用懂技术）。

装的时候怎么填、怎么启动 → 看 使用说明.txt。下面这份是给要自己动手的人的完整文档。

环境要求

• Node ≥ 18
• 机器上装好 DSH（有 dsh 命令；没装的话先跑下面第 0 步）
• 一个 Telegram bot token（在 Telegram 里找 @BotFather 发送 /newbot 新建，不要和其他 bot 共用）

安装分成两件事，一个脚本管一头，互不越界：

setupdsh = 升级（Git、Node、DSH 本体，外加已经装过机器人的工作区里的插件：装 + 升级）；

setupbot = 建/选工作区、首次装插件、绑 TG / 微信、生成工作区里那 5 个文件（英文名，双击或终端里跑都行）。

机器上没有 dsh 时 setupbot 会自己把 setupdsh 跑一遍，所以顺序不用记。

安装方式一：在线安装（两条命令，推荐）

1. 先装/升级本体（Git、Node、DSH 一起办，可重复跑）：

curl -fsSL https://raw.githubusercontent.com/aitcmhk-web/DSH-bot/main/setupdsh.sh | sh

1. 再装机器人 —— 把下面这条整段贴进终端，回车：

curl -fsSL https://raw.githubusercontent.com/aitcmhk-web/DSH-bot/main/setupbot.sh | sh

它自己列出/新建工作区、自己把插件装好，然后只问你三件事： 工作区叫什么（直接回车就叫 mybot）、Telegram token（@BotFather 那串）、微信怎么绑（可选）。 每样都是「输个编号」或「粘一下回车」，不用你编辑任何文件。

1. 跑完它会把两个词装进 PATH —— **以后升级（本体 + 插件）敲 setupdsh；

重新绑 TG、重新绑微信敲 setupbot**：

setupdsh
   setupbot

1. 启动：照着它最后打出来的那行，或者跑 ~/DSH//start.command

（同目录里另有 stop.command、restart.command、install-autostart.command、uninstall-autostart.command）。

那五个文件名字一律英文：有桌面双击，没桌面（云主机 / 只有终端）就

cd ~/DSH/ && ./start.command。中文文件名在纯终端里得切输入法，太别扭。

开发者：本地安装（用你手上这份源码）

已经有一份源码（比如你自己 clone 下来的、或者要改着调试的），就用 file: 指向那个目录：

dsh plugin --profile mybot add file:/绝对路径/dsh-botplugin

例如源码在 ~/DSH/BOT/botplugin：

dsh plugin --profile mybot add file:$HOME/DSH/BOT/botplugin

⚠️ file: 后面不能写 `~` —— 它不会展开波浪号，会当成字面路径找不到。用 $HOME/ 或完整绝对路径。

用 file: 装出来的是软链 —— 改完源码不用重装，重启 profile 就生效。

调试的时候用这个；平时用上面的 git 方式。两种选一种，别都装

（会装出两份同名插件，加载哪份不好说）。

⚠️ 路径必须是绝对路径，且指向含 `package.json` 的那一层（也就是仓库根），

不要指到 src/ 或上一层。

安装方式二：下载安装包（不想敲命令的）

1. 下载安装包：dsh-mybot-安装包.zip（在本页文件列表里，点它再点 Download / Download raw）。
2. 解压，双击里面的 安装-mybot.command。
3. 接下来和在线方式完全一样：问你工作区名字（直接回车就叫 mybot）→ 粘 token → 微信要不要绑。

窗口最后会停住等你按回车，结果不会一闪而过。

1. 以后每次使用：跑 ~/DSH//start.command（stop.command / restart.command / install-autostart.command / uninstall-autostart.command 是同一个目录里的另外四个文件）。

想重新绑 TG / 微信：把 安装-mybot.command 再双击一次（或在终端敲 setupbot）。 想升级（Git / Node / DSH 本体 / 已经装过机器人的工作区里的插件）：在终端敲 setupdsh（安装包里也带了这个脚本）。

两种方式装出来的是同一个插件，跑的是同一个 setupbot.sh，选一种就行。

安装包方式适合完全不想碰命令行的人；在线方式第一次要粘两条命令，之后也只剩 setupdsh / setupbot 两个词。

怎么确认装对了

脚本跑到最后会打「✅ 复核通过：配置已经生效」—— 看到这句就是装对了，它紧接着会给你启动命令。

没看到这句、或者它报「插件没装上」= 没装成，插件不会生效（而且不报错，只会静默什么都没发生）。

配置项速查

配置 · 说明 telegramToken / telegramApiRoot · TG 必填；apiRoot 指向代理时改 telegramAllowedUsers · 允许的 TG 用户 ID；空 = 首个发消息者认领为主人 weixinToken / weixinApiRoot / weixinAccountFile · 微信入口（通常用扫码登录，不用填 token） routes + defaultRouteKey · 手工指定模型档位；留空 = 自动跟随 web 端「设置 → 模型」 cwd · 模型的工作目录 memoryDir / memoryScript · handoff 记忆接续：默认开启（/memory + 插件自带的记账程序），不用配；要关闭把 memoryDir 设成空串 restartCommand · 重启用的启动器 .command 路径；不填默认找工作目录里的 start.command（兼容老的 启动-.command / 启动-mybot.command） turnTimeoutMs · 单轮超时，默认 90 分钟（2026-10-20 由 30 抬上来：满 30 分钟就判超时并把这一轮答案丢掉） asrBackend / asrWhisperBin / asrPythonBin · 语音转文字。默认 sensevoice（阿里 FunASR，中文准），不填路径就自动找 /opt/homebrew/bin/python3.11；本机没装时，安装收尾和发语音都会回一条可粘贴的安装命令（⛔ 不自动装）。whisper 中文差，只有显式填 asrBackend: whisper 才用 llmBudget · 模型流量闸：滚动 60 秒内请求数与 token 数封顶（默认 50 次 / 90 万 token），超了排队等，别撞供应商的 TPM 限额。字段：enabled（默认 true，关掉=不限流）/ tpm / rpm / 输出预留（每次先占多少输出 token，默认 8000）/ 最长等待毫秒（默认 10 分钟，等满就放行并打告警）

模型流量闸（每分钟限额，2026-10-19 加）

一回合里跑工具、开子代理都会反复发模型请求，一分钟里的累计很容易顶到供应商的 TPM/RPM 限额（撞上就是 429）。插件在宿主 llm 的 llm/stream 上挂了一道闸 （src/llm-budget.js）：滚动 60 秒窗口内 请求数 ≤ `rpm`、token 合计 ≤ `tpm`， 快满时让下一次调用排队等到窗口腾位，⛔ 不丢请求、⛔ 不改流里的内容。

• 记账口径：调前按请求体的可读字符量预估（中文 1 token/字、其余 1/4，另加输出预留），

流里收到宿主 usage 块后换成实际用量（替换，不叠加）；失败/中断的那次仍按预估留在账上（保守）。

• fail-open：单次最多等 最长等待毫秒（默认 10 分钟），等满仍无额度就放行一次并打告警——

宁可偶尔超一次，也不让整台 bot 卡死。

• 子代理与工具循环一样算：它们都走同一条 waterfall，所以一处就管住全机流量。
• 默认口径：rpm 50 次 / tpm 90 万 token（2026-10-19 定的最终值）。供应商（百度千帆）的

TPM 限额是 100 万，90 万是留一成余量。一条请求就带十几万 token（整段历史重发），所以一分钟 大约放六七发 —— 这是硬约束，要更快只能少发请求，⛔ 不能靠抬闸。 ⛔ 历史上曾抬到 300 万（当时误判「供应商限的是请求密度、不是 token 量」），拿到实数后已收回。

• 关掉：配置里 llmBudget.enabled: false（出问题时可一键停，不影响启动）。

会话压缩口径（随版本下发，2026-10-19 加）

插件作为 profile 层装上时，会顺手把会话压缩的口径打进 profile：本包的 cordis.patch.yml（package.json 的 dsh.bundle.patch）多打一行 compaction-basic。 宿主代码默认 thresholdRatio 0.8 —— 在百万窗口上等于 80 万 token 才压缩， 正常对话根本触发不到，历史只能近乎全量重发，越聊越慢。

本包一律下发比例制（两个数都随窗口缩放，任何窗口都自洽）：

键 · 值 · 作用 thresholdRatio · 0.15 · 窗口的 15% 触发压缩（百万窗口 = 15 万 token） retainRatio · 0.08 · 压缩后按窗口留约 8%（百万窗口 ≈ 5 万 token） headroomTokens · 8192 · 预留空间。出厂默认 65536 比小窗口本身还大，会把压力预算算成负数

⛔ 不要再用 `retainTokens`（绝对保留量）：它是绝对值、不随窗口缩放，宿主会校验 「保留量必须小于触发线」，小窗口模型（如 6.5 万窗口）配上几万的绝对值会被判非法并抛 TargetPressureConfigError —— 压缩整个失效、历史无限增长，直到上下文溢出。

补丁顺序是「出厂 → 本插件 → 用户 profile 的 cordis.patch.yml」，最后一个写的人赢， 所以用户 profile 想改仍盖得住本包，这里只是把合理默认变成可分发的东西。

远程审批（手机点按钮，不用守着电脑）

DSH 的审批服务用 waterfall 广播 approval/request，插件把它桥接到 Telegram—— 推一张和 web 端审批面板同口径的卡片（等待审批 / 已允许 / 已拒绝 / 已取消 / 已超时

• 命令、工作目录、原因），下面挂两个内联按钮【✅ 允许一次】【❌ 拒绝】。

点完卡片收成终态并去掉按钮。

桥是只读旁路：卡片渲染失败、编辑失败、按钮超时，统统只记日志，

绝不影响审批本身的结果（该通过的照常通过）。

行动端入口在 src/approval-bridge.js，默认超时 10 分钟。

多端互通（TG ⇄ 微信，同一个大脑）

src/hub.js 是所有端点的唯一交汇点，纯逻辑、零依赖。两条规则，都是「同步到所有」：

方向 · 行为 端点到 hub · 同步给 ① DSH ② 其他所有端点 DSH 到 hub · 同步发到所有端点

新增端点 = 加一个数组项（O(n)），不是两两镜像（O(n²)）。 微信消息并入主人的 TG 会话，所以两边聊的是同一段上下文， 在微信里 /new、/model 操作的是同一个会话。

⛔ 这里刻意不做去重/合并：TG 和微信各进来一条就是两次真实输入，进来几条算几条。

指令

/whoami /status /model /new（新会话） /restart（重启进程，先留档） /help

/restart 与老 bot 同路：先把进展写进 handoff，再由进程外的接力脚本延迟几秒杀掉宿主并重新拉起（有 start.command（兼容老的 启动-.command / 启动-mybot.command）就重开终端窗口；没有就按原始命令行后台拉起）。两者都没有时退化为只重开会话。重启完成后发条消息，新会话自动带上刚才的记忆。

记忆（流水账 + handoff）

默认开启，什么都不用配：

• 流水账：每轮对话原文追加到 /memory/conversation-cache/raw/ledger/，按月一个文件，只增不删。
• handoff：/new、切换模型（本次会话满 20 条才写，调试期反复切不会覆盖）、/restart（无条件）和启动补写时，把最近 20 条进展落盘到 /memory/handoff/handoff.md。
• 冷启动注入：新会话的第一条消息会自动带上最近一次 handoff，模型直接接着上段干，不用你复述上文。
• 记账程序随插件自带（vendor/conversation-cache/），不依赖机器上是否装过 DSH 的其它项目。
• 想换位置或关闭：配置里写 memoryDir（自定路径；空串 = 关闭）、memoryScript（自定程序路径）。

微信入口（扫码绑定）