橘波特 std-microblock/orange-bot

orange-bot（橘波特）

Orange (橘波特)：一个 QQ 群聊机器人，跑在 DeepSeek Harness 上。它盯着同一个 QQ 群的两个视图——官方 bot（koishi）和 userbot（crossgram）——自己判断什么时候该开口，把真正的活儿交给后台任务智能体，再用一个 Web 面板把看到和做过的一切都管起来。

橘波特不是一个只会复读的命令行机器人。它在群里像个人：有人 @ 它、有人接它的话、或者群里在聊它主人维护的项目的 bug 时，它自己判断要不要插一句；需要查证的事情它不瞎猜，而是派给后台任务智能体去翻源码、跑命令、提 PR。它同时接两个平台（QQ 官方 bot，以及和主人共号的 userbot），把同一个物理群的两行视图配对成一行，再在这上面做触发判定、会话、任务和面板。

这个仓库是它的全部代码：一个 dsh 插件 + 两个挂在 Satori 服务上的同伴插件。

三个包

| 包 | 跑在哪 | 提供什么 |
| packages/dsh-plugin-orange | DeepSeek Harness（dsh web profile） | 机器人本体：双平台接入、消息库、触发合并与分类器、chat 智能体、后台任务 worker、智能体工具、Web 面板 |
| packages/koishi-plugin-orange-bridge | koishi（官方 bot 侧） | 官方 bot 那几个 Satori 表达不了的 HTTP 面：C2C 私聊发送、被动回复、群名、成员角色、撤回、指令表 |
| packages/orange-ext | crossgram（userbot 侧） | 全量消息 WS、历史、合并转发展开、reaction、撤回、成员角色、消息查询、表情（收藏夹） |

orange-ext 是 crossgram monorepo（@mtproto-relay/）里的插件，依赖那边的 @mtproto-relay/bridge 类型，所以它不在本仓库的 pnpm workspace 里：源码放在这儿，装法见它自己的 README。

拓扑

QQ 群 │ ├─ 官方 bot ─ koishi ────────────┐ /satori/v1/ 事件流（Satori op:3 identify） │ + orange-bridge ───┤ /satori/orange/* send / guild / member / recall / commands │ │ └─ userbot ─ crossgram ──────────┤ /satori/v1/message.create 出站发送
+ orange-ext ───────┤ /satori/orange/events (WS) 全量消息流（含自己发的） │ /satori/orange/* history / forward / reaction / sticker / member.roles / …
▼
反向代理（例如 Caddy，两条 HTTPS 入口） │ ▼ dsh（web profile）+ dsh-plugin-orange ├─ SQLite：消息 / 响应 / 分类 / 任务 / 记忆 / 用量 / 表情 / 群角色 ├─ chat 智能体：每个会话一个 session ├─ 后台 task worker：带完整 shell，会开子智能体、会提 PR └─ Web 面板：/orange-api/（会话、响应记录、任务、表情、用量、设置）

截图

面板（dsh web 侧栏「🍊 Orange Bot」里的会话页：左侧是见过的所有群，右侧是两侧合一的消息流 + 触发原因）：

会话

| 响应记录：每条回复的触发方式、dry run、这次抽到的子风格 | 后台任务：worker 实时状态与 PR/issue |
| 响应记录 | 后台任务 |

| 记忆与用户：长期记忆、用户标签（谁是开发者） | 用量：按类别与模型计的 token 与花销 |
| 记忆与用户 | 用量 |

| 设置：说话风格、表情、主人项目、旁听主题 | 表情库：类型筛选 / 搜索 / 权重 |
| 设置 | 表情库 |

表情库的导入（从 QQ 收藏夹导入，视觉模型逐张自动分类并写一句话描述）：

| 导入进度 | 批量操作 | 表情设置 |
| 导入 | 批量 | 表情设置 |

消息渲染：存下来的文本是给模型看的（<quote>…</quote>、<forward …>、[图片 #12]），面板负责把它摊平成给人看的样子——下面这组是修这个 bug 前后面板画面的对比：

| 修之前：引用里的合并转发直接把 XML 画出来 | 修之后：引用块 + 转发卡片 |
| before | after |

| 引用里的图真的出图 | 我们自己写的那行 > 名字：… 也画成引用块 |
| 引用里的图 | 自渲染引用行 |

装起来

0. 需要什么

- 一台能跑 dsh 的机器（Node ≥ 22）；
- 一个 koishi（官方 bot 侧，装 @satorijs/adapter-qq）+ 本仓库的 koishi-plugin-orange-bridge；
- 一个 crossgram（userbot 侧）+ 本仓库的 orange-ext；
- 一个 OpenAI 兼容的模型端点（分类器、聊天、任务、表情分类、风格润色都走它）；
- 两条能到上面两个 Satori 服务的 HTTPS 入口（同一域名不同端口也行），因为两边都靠 Bearer token 认证。

1. 把同伴插件装到两侧

koishi 侧：

在 koishi 的 app 目录里
npm install /path/to/orange-bot/packages/koishi-plugin-orange-bridge

koishi.yml
plugins:
orange-bridge:
path: /satori/orange
token: <和 dsh 侧 ORANGE_KOISHI_TOKEN 相同>

crossgram 侧：把那 packages/orange-ext 放进 crossgram monorepo 的 packages 下并加进它的 workspace 依赖，配置 path: /satori/orange、token: <和 ORANGE_CROSSGRAM_TOKEN 相同>、platformId: qqnt；细节见 packages/orange-ext/README.md。

2. 反向代理

/etc/caddy/Caddyfile
https://bot.example.com:41008 { # koishi
@satori path /satori/v1/ /satori/orange/*
handle @satori { reverse_proxy 127.0.0.1:5140 }
respond 404
}

https://bot.example.com:41009 { # crossgram
@satori path /satori/v1/* /satori/orange/*
handle @satori { reverse_proxy 127.0.0.1:3140 }
respond 404
}

3. 挂到 dsh

git clone https://github.com/std-microblock/orange-bot.git
cd orange-bot/packages/dsh-plugin-orange && npm install # prepare 会顺手 build 一次

然后让 dsh web profile 依赖它并把包名加进 bundle 列表（完整步骤与配置表见 packages/dsh-plugin-orange/README.md）：

{
"name": "dsh-profile-web",
"private": true,
"dependencies": { "dsh-plugin-orange": "link:/path/to/orange-bot/packages/dsh-plugin-orange" },
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-plugin-orange"],
"patchReload": "live"
}
}
}

4. 首次运行

新装的插件谁都不回答、什么群都不存：admins、白名单、errorGroup 默认都是空的。按顺序：

1. 起 dsh web，在启动日志里拿到带 token 的面板地址，侧栏会出现「🍊 Orange Bot」；
2. 把主人写进 admins（qq:<user_openid> / cg:<uid>），否则群里没人有管理权限；
3. 面板「会话」页把要聊的群加白名单（或管理员在群里 /ai.white add <群号>）；
4. 新群先开 dry run：照常思考、照常出响应记录，但不真的发出去。

端点契约

要做别的客户端、或者只想接一侧的话，这张表是全部要求（ 是配置里的 endpoint，例如 https://bot.example.com:41008/satori）：

| 端点 | 谁提供 | 说明 |
| /v1/ | koishi 自带的 Satori 服务 | 官方 bot 的事件流（op:3 identify）与其余 Satori API |
| /orange/send | orange-bridge | 复用 koishi 的消息编码器发消息：C2C 私聊、被动回复（同一个 msg_id 的 msg_seq 递增）|
| /orange/guild | orange-bridge | 群名/群标签（官方群事件里只有不透明的 group_openid）|
| /orange/member | orange-bridge | 单个群成员的角色（事件没带 member_role 时的兜底）|
| /orange/recall | orange-bridge | 撤回自己发的消息 |
| /orange/commands | orange-bridge | koishi 已注册的指令别名，用来对 koishi 自己的指令保持沉默 |
| /v1/message.create | crossgram 的 satori-exporter | userbot 侧的出站发送 |
| /orange/events（WS） | orange-ext | 全量消息流，含账号自己发出的；连上后第一帧发 {"token":…} 认证，回 {"type":"ready","selfId","loginId"} |
| /orange/message.get message.recall history.list forward.get forward.send reaction.set reaction.catalog member.roles conversation.get sticker.packs sticker.list sticker.asset debug | orange-ext | 见 packages/orange-ext/README.md 的路由表 |

自查（两个 token 分别填）：

curl -sS -X POST -H "Authorization: Bearer $ORANGE_CROSSGRAM_TOKEN" \
-H 'Content-Type: application/json' -d '{}' \
https://bot.example.com:41009/satori/orange/debug

开发

pnpm install
pnpm build # 只 build dsh 插件（node 半 + 面板 bundle）
pnpm typecheck # tsc --noEmit

- packages/dsh-plugin-orange：TypeScript + esbuild；改 src/client/ 之后要重新 build 才会生效（面板 bundle 由 dsh 的模块加载器接管，react 与 @deepseek-ai/dsh-client-ui- 由宿主提供）。
- packages/koishi-plugin-orange-bridge：一个 CommonJS 文件，没有构建步骤；改完重启 koishi。
- packages/orange-ext：TypeScript，由 crossgram 自己加载（main 指向 src/index.ts）；它依赖 crossgram 的工作区，单独装不起来，改完重启 crossgram。
- 源码注释里出现的 vm/debug/*-test.ts（润色、@ 解析、面板分词、表情…）是作者部署仓库里的离线纯逻辑断言脚本，没有随本仓库发布，因此在本仓库里跑不了。

隐私与安全

- 只存该存的：白名单群（及其配对的对端行）才落消息；非白名单群只留群号/群名；除主人↔机器人的私聊，别人的私聊连会话行都不建。
- 工具按会话收敛：历史、搜索、转发、图片、记忆只覆盖本会话服务的群和它的对端行；跨群要管理员触发，后台任务继承发起者的权限。
- 工具守卫：任何 orange 会话都不许读机器人自己的数据库、凭据与会话记录（~/.orange/、orange.db、/etc/orange、~/.dsh/sessions、进程环境变量里的 token），命中直接拒绝并写日志。
- 入站审查：非管理员触发的消息先过一遍（关键词 + 一次小模型调用，带缓存）：套别群/私聊内容、要机器人骂人或网暴、辱骂挑衅、涉政 → 完全不回应，也不进 agent 的上下文，只在响应记录里留一条审计。

许可

MIT © 2026 MicroBlock