EayonLee/dsh-tuitui-bot

---

这是什么

把推推机器人做成 dsh 的一个渠道前端：推推消息 → 归一化 → 中间件链 → dsh Agent； dsh 的文本/工具/审批/问答/交付物 → 推推消息、原生交互卡片、原地编辑流式输出。

传输层用推推官方 SDK（@qihoo/tuitui-bot-sdk）， 上层是自带的洋葱中间件链：访问控制 → 历史缓冲 → 触发门控 → 清洗 → 限流 → 命令 → 并发串行 → 打字状态 → 引用解析 → 附件处理 → 上下文组包，顺序即行为契约。

功能一览

能力	说明
💬 三种会话形态	单聊、群聊、团队频道帖子（含回帖串），各自独立的会话上下文
⚡ 流式输出	首条消息拿到 msgid 后用 modifyText 原地刷新，不刷屏；降级时自动切成追加片段
🃏 原生交互卡片	审批 / 提问用推推交互卡片，点击后 modifyInteractive 原地更新为最终状态
🖼️ 富媒体理解	图片/文件/语音/视频落地到本地媒体目录，交给 agent 读取（视觉工具可选）
📎 文件回传	tuitui_send_file 工具 + present 交付物自动投递到当前会话
🧭 上下文感知	群历史缓冲、引用消息解析、发送者部门路径、@ 标记清洗
🧩 斜杠命令	/new /compact /model /preset /status /stop 等，同步为推推快捷指令
🧠 原生步骤上报	通过 client.agent 上报模型/工具调用，推推客户端原生展示执行过程
🔐 四档访问控制	open / allowlist / blocklist / disabled，单聊 / 群聊 / 帖子分别配置，黑白名单以标签录入
🗣️ 智能插话	smart 模式下由模型读群聊上下文自行判断要不要开口，判定提示词可在设置页整段改写
🛠️ 端内设置页	凭据绑定 + 全部常用配置可视化编辑，保存即写 profile 并自动重载；名单是标签，工作区是下拉

快速开始

1. 准备机器人凭据

在推推机器人后台创建机器人，拿到 AppID 与 AppSecret。

2. 安装插件

# 一键安装脚本（自动建 profile、装包、提示配置；npm 装不上会自动回落 GitHub）
sh install.sh

# 从 npm 安装（推荐）
dsh plugin --profile tuitui add @eayonlee/dsh-tuitui-bot

# 从 GitHub 安装（等价；npm 不可达时用，仓库已提交构建产物 lib/，无需本地构建）
dsh plugin --profile tuitui add github:EayonLee/dsh-tuitui-bot

# 或从本地源码 / tarball 安装
dsh plugin --profile tuitui add /path/to/dsh-tuitui-bot
npm pack && dsh plugin --profile tuitui add ./eayonlee-dsh-tuitui-bot-0.1.0.tgz

3. 配置凭据并启动

export TUITUI_BOT_APPID="你的AppID"
export TUITUI_BOT_SECRET="你的AppSecret"
export DEEPSEEK_API_KEY="你的 DeepSeek Key"

dsh --profile tuitui            # 启动 agent + 推推长连接

也可以不配环境变量：直接启动后在 设置 → 推推机器人 里填写 appId/appSecret， 插件会调用 property.info() 校验并把凭据写进 profile 的 cordis.patch.yml。

4. 在推推里聊

• 私聊机器人：直接发消息
• 群聊：把机器人拉进群。默认是智能模式——它按自己的性格和上下文判断要不要说话；三档触发方式（mentionPolicy）：
  • require（默认）：只有 @ 才算叫它。
  • smart：模型读最近对话自己判断要不要插嘴——别人互相聊天不接话，轮到自己或被问到才开口；判定提示词可在设置页改写。
  • always：群里每条消息都回（只建议专用小群）。
• 团队频道：在频道里发帖并 @机器人（或回复机器人的帖子）

配置

配置项定义在 src/config.ts，可在 profile 的 cordis.patch.yml 中覆盖 （patch 是整体替换 config，需写全你要保留的键）。

设置页（推荐）

dsh 设置 → 推推机器人，所有常用配置都在这里，保存后写回 profile 并自动重载：

• 服务范围：单聊 / 群聊 / 团队帖子各选四档模式；白名单、黑名单都是标签输入—— 回车或逗号成标签，Backspace 删最后一个，点 × 删单个，不用记格式。
• 什么时候回话：触发方式三档；选「智能」时展开追问延续窗口，以及 判定提示词编辑器（多行、等宽字体、可一键恢复出厂默认）。
• 上下文与会话：群聊上下文条数、闲置回收分钟数，带单位后缀与用途说明。
• 工作区：下拉直接选目录（默认工作区 / ~/workspace 下的项目 / 当前值），不用手打绝对路径。
• 推推原生能力：交互卡片、中间步骤上报、调试日志三个开关。

名单、提示词这类长文本提交前都在服务端重新校验（长度、控制字符、类型）， 客户端校验只负责体验，安全边界在宿主。

基础

配置	类型	默认值	说明
appId	string	''	推推机器人 AppID（可用 TUITUI_BOT_APPID）
appSecret	string	''	推推机器人 AppSecret（可用 TUITUI_BOT_SECRET）
provider / model	string	-	覆盖 LLM 路由；留空继承宿主默认，可 /model 切换
preset	string	-	Agent preset id（新会话生效）
cwd	string	~/.dsh-tuitui/workspace	Agent 工作目录
requireMention	boolean	true	群聊是否必须 @bot（mentionPolicy 未设置时用它推导）
requireMentionInPost	boolean	true	团队帖子是否必须 @bot
mentionPolicy	'smart'	smart / require / always：按人格与上下文自主判断（默认）/ 仅 @ / 全部
smartFollowUpMs	120000	机器人回复后，同一个人接着说话算「同一轮对话」的窗口（ms）
smartJudge.enabled	true	智能模式用模型判断；关掉退回确定性规则
smartJudge.prompt	内置文案	判定提示词，可整段改写（设置页可视化编辑，留空恢复默认）
smartJudge.maxHistory	50	判定时交给模型的历史消息条数
smartJudge.cooldownMs	20000	同一会话两次判定的最小间隔，防止每条消息都调模型
smartJudge.timeoutMs	8000	判定超时（超时视为不插嘴）
groupPrompt / directPrompt / postPrompt	string	-	按作用域追加的 system prompt
textChunkLimit	number	4000	单条消息最大字符数
debug	boolean	false	调试日志（含原始事件体）

会话与并发

配置	默认值	说明
streaming	true	流式输出（原地编辑）
streamIntervalMs	600	流式刷新节流
sessionIdleTimeout	1800000	会话闲置回收（ms）
maxQueue	20	同 peer 消息队列上限
processingTimeoutMs	1800000	单轮处理超时（ms）
askTimeoutMs	300000	待答问题超时（ms）
historyLimit	50	群/帖子历史缓冲条数
showToolResults	false	是否展示工具成功结果（错误始终展示）

访问控制

配置	默认值	说明
access.c2cMode	open	open / allowlist / blocklist / disabled
access.c2cAllow / c2cBlock	[]	单聊白名单 / 黑名单（域账号或 UID，黑名单优先）
access.groupMode	open	群聊模式（同上四档）
access.groupAllow / groupBlock	[]	群白名单 / 黑名单（group_id）
access.postMode	disabled	团队帖子模式（同上四档；默认禁用，要用再开）
access.postAllow / postBlock	[]	帖子白名单 / 黑名单（channel_id 或 team_id）

allowlist 模式下名单为空 = 拒绝所有人（fail-closed）。

富媒体 / 视觉 / 附件

配置	默认值	说明
media.enabled	true	是否下载并理解富媒体
media.maxMB	200	单文件上限（MB）
media.ttlHours	24	媒体保留时长，0 = 永久
vision.enabled	false	启用 tuitui_describe_image 工具
vision.provider / vision.model	-	视觉模型路由
sendFile.restrictPaths	false	是否限制可发送的文件路径；默认放开，打开后只允许 media + cwd + extraRoots
sendFile.extraRoots	[]	额外允许发送的目录
sendFile.sendPresentedFiles	true	轮末投递 present 声明的文件

推推原生能力开关

配置	默认值	说明
interactive.enabled	true	用交互卡片做审批/提问（关闭后走编号文本应答）
interactive.headBgColor / headTextColor	#1F6FEB / #FFFFFF	卡片头部配色
agentSteps.enabled	false	上报模型/工具步骤给推推客户端原生展示（默认关）
agentSteps.includeToolPayload	false	是否上报工具参数/结果原文
agentSteps.maxResultChars	800	工具结果截断长度
apiBaseUrl / websocketBaseUrl	-	私有化部署端点覆盖（亦可用 TUITUI_BOT_API_BASE / TUITUI_BOT_WS_BASE）

内置命令

命令	说明
/new（别名 /reset /clear）	开始新会话（清空上下文）
/compact	压缩会话历史（摘要替换旧记录）
/model	查看或切换模型
/preset	查看或切换 agent preset（新会话生效）
/status	当前会话状态（会话 id、模型、preset、消息数）
/stop	中止当前生成
/bot-ping	延迟检测（传输 + 处理耗时）
/bot-version	版本信息
/bot-help	全部命令
/auth	访问控制自检（当前 peer 是否被允许）

常用命令会同步到推推的快捷指令面板，用户无需记忆。

工具

工具	说明
tuitui_send_file	把本地文件/URL/内存内容发到当前会话；默认不限制路径，想发什么发什么
tuitui_describe_image	视觉理解（需 vision.enabled，复用 dsh llm + attachments）

智能插话是怎么工作的

mentionPolicy: 'smart' 时，群里每条消息（未 @ 也算）会走一次判定：

1. 冷却：同一会话 smartJudge.cooldownMs 内只判一次，超出的消息直接按「不插嘴」处理，不烧 token。
2. 取上下文：从历史缓冲拿最近 smartJudge.maxHistory 条（带说话人，机器人自己标 [你]）。
3. 问模型：用该会话当前生效的模型，把 smartJudge.prompt + 历史 + 新消息发过去， 要求只回一行 JSON：{"join":true,"why":"十个字以内"}。
4. 失败即闭嘴：超时（timeoutMs）、输出解析不了、模型报错、服务缺失——一律 join:false。 宁可漏答一句，也不在群里刷屏。
5. 关掉开关（smartJudge.enabled=false）退回确定性兜底：只保留「机器人刚回过的人接着说话」这一条，没有「出现某个词就回」的规则——那跟人格设定冲突。

提示词里没有判断清单——写成清单，它就变成按表格打勾的机器人。出厂文案给的是处境和动机 （感兴趣、不同意、觉得好笑、无聊、手上有信息、被叫到、该有人拍板），让它自己拿主意。 提示词是一等配置：不同群需要不同的「人设」，在设置页整段改，改完保存即生效； 清空输入框恢复出厂默认（见 src/shared/smart-prompt.ts）。

会话与上下文

行为	说明
会话隔离	会话键是 tuitui:<scope>:<peerId>：单聊按对方账号、群聊按 group_id、帖子按 channel_id，各自独立上下文
群上下文	未 @ 的群消息也会进历史缓冲（受 historyLimit 约束），被叫到时随消息一起交给 agent
闲置回收	超过 sessionIdleTimeout 没消息就回收内存里的 agent；下次说话自动恢复原会话，上下文不丢
长任务保护	agent 正在跑（非 idle）的会话不会被回收，避免长任务被中途清掉
并发串行	同一 peer 的消息排队串行处理（maxQueue），不同 peer 互不阻塞
引用解析	被回复的那条消息会作为引用一起交给 agent，群里「它刚才说」这类指代不会丢

安装后刷新 / 卸载

改完配置或想升级时，重装同一路径即可（profile 会原地替换），然后重启对应 profile：

dsh plugin --profile <name> add @eayonlee/dsh-tuitui-bot   # 或本地 tarball / 源码目录
dsh --profile <name>                                      # 重启让新版本加载

dsh --profile <name> --dump-config | grep -A3 im-tuitui 可以确认插件行已进入组合树。

卸载：

dsh plugin --profile <name> remove @eayonlee/dsh-tuitui-bot
# 凭据写在 profile 的 cordis.patch.yml 里，需要的话一并手动删除

常见问题

群里不回应？ 先看 /auth 自检，再确认触发方式：require 只认 @；smart 要看模型判定； always 才全回。帖子还要确认 requireMentionInPost。

智能模式太安静 / 太吵？ 安静就调小 smartJudge.cooldownMs、把提示词写得更积极； 太吵就反过来，或者直接把 mentionPolicy 调回 require。

设置页说「凭据来自环境变量」不能解绑？ 环境变量优先于 profile，端内解绑删不掉它。 去部署环境删掉 TUITUI_BOT_APPID / TUITUI_BOT_SECRET 再重启。

改了配置没生效？ 设置页保存会写 profile 并触发重载；手改 cordis.patch.yml 需要重启。

为什么有时回复变成好几条？ 单条超过 textChunkLimit 会被切成多段；流式降级时也会追加片段。

架构

推推事件 (WebSocket)
   │  src/tuitui/inbound.ts      归一化：single_chat / group_chat / teams_post_create / interactive_action
   ▼
中间件洋葱 (src/gateway/middleware/)
   errorHandler → messageFilter → accessPolicy → historyBuffer → mentionGate →
   contentSanitizer → rateLimiter → slashCommand → questionAnswer →
   concurrencyGuard → typingIndicator → quoteRef → attachmentProcessor → envelopeFormatter
   ▼
src/transport/inbound.ts   5 层组装（用户内容/引用/发送者标签/媒体元数据/历史 envelope）→ agent.followup
   ▼
dsh Agent（session/**、host/**、model/**）
   ▼
dsh 事件 (session/event, agent/assistant-stream)
   │  src/transport/{outbound,streaming-writer,outbound-buffer,tool-presenter,deliverables}.ts
   ▼
src/tuitui/sender.ts   im.sendText / modifyText / sendInteractive / modifyInteractive / sendFile / recall / emojiReaction
                       teams.sendPost / editPost / sendFile / emojiReaction

关键设计：全插件只有 src/tuitui/ 直接 import 推推 SDK，其余模块只依赖 src/types.ts 里的 TuituiSender 抽象，便于替换与测试。

开发

npm install
npm run typecheck        # tsc --noEmit
npm test                 # vitest（纯逻辑模块单测）
npm run build            # tsc → lib/ + tsdown → lib/client.js（浏览器端面板）

# 真实环境冒烟（真实凭据验证：事件归一化 / 凭据 / 长连接 / 发送 / 编辑 / 撤回）
TUITUI_BOT_APPID=xxx TUITUI_BOT_SECRET=yyy node scripts/smoke-live.mjs
node scripts/smoke-live.mjs --send group:<groupId>      # 额外做真实收发 + 编辑 + 撤回

# 启动接线自检（不需要 dsh CLI / LLM Key：验证客户端、发送器、中间件链、工具注册、
# WS 订阅、property.info 自检、快捷指令同步、生命周期清理整条接线）
TUITUI_BOT_APPID=xxx TUITUI_BOT_SECRET=yyy node scripts/verify-bootstrap.mjs

本地调试（不装包，直接用源码，dsh ≥ 0.2.1 用 --patch 叠加层）：

dsh web --patch /path/to/dsh-tuitui-bot/cordis.dev.yml

本插件的 bundle 层会随 dsh plugin --profile <name> add 自动生效； 用 dsh --profile <name> --dump-config 可以确认 im-tuitui 行已进入组合树。

贡献

欢迎提 issue / PR，动手前请先读 贡献指南：

• Bug 请用 Bug 报告 模板，附上 dsh 版本、插件版本与脱敏日志；
• 功能建议请用 功能建议 模板，说明推推侧可复用的原生能力；
• 提交前请跑通 npm run typecheck、npm test、npm run build；
• 参与即表示遵守 行为准则；安全漏洞请按 SECURITY.md 私下报告，不要开公开 issue。

变更记录见 CHANGELOG.md（英文：CHANGELOG_EN.md）。

致谢

• 宿主框架 DeepSeek Harness；
• 推推开放平台 @qihoo/tuitui-bot-sdk。

许可

MIT © 2026 EayonLee and dsh-tuitui-bot contributors