dsh-roost 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,213 @@
+qq-bot-roost（栖 Roost）免费非商业许可协议 v2.0
+
+Copyright (c) 2026 tdcq9594
+
+本协议的结构参考 PolyForm Noncommercial License 1.0.0
+<https://polyformproject.org/licenses/noncommercial/1.0.0>，
+并按本项目「永久免费、禁止任何收费」的要求做了加严。
+
+================================================================
+一、接受
+================================================================
+
+要获得本协议授予的任何权利，你必须把本协议的全部条款
+作为你必须遵守的义务和获得许可的前提，完整地接受。
+
+================================================================
+二、定义
+================================================================
+
+「许可人」指提供本软件并给出本协议的个人或组织，即版权持有人。
+
+「本软件」指许可人在本协议下提供的软件，包括源代码、文档及其任何部分。
+
+「你」指接受本协议的个人或组织。
+
+「你的组织」指你受雇或任职的任何法律实体、个体经营者或其他形式的组织，
+以及控制该组织、受该组织控制、或与该组织处于共同控制之下的所有组织。
+「控制」指拥有某实体实质全部资产的所有权，或通过表决、合同或其他方式
+决定其管理与政策的权力，可以是直接或间接的。
+
+「使用」指你对本软件所做的、需要本协议授予许可的任何行为。
+
+================================================================
+三、永久免费，禁止任何收费
+================================================================
+
+本软件**永久免费提供**。
+
+任何个人或组织，在获取、使用或分发本软件（含原版、修改版及衍生作品）时，
+**不得收取任何形式的费用**，包括但不限于：
+
+  1. 软件本身的售价，或下载费、激活费、注册费；
+  2. 授权费、许可费、订阅费、会员费；
+  3. 以「技术支持」「培训」「咨询」「定制开发」等名义收取的费用；
+  4. 以「捐赠」「赞助」「打赏」等名义设置的付费门槛——
+     自愿且无附加条件的捐赠不属于收费，但不得将任何付费行为作为
+     获取或使用本软件的前提；
+  5. 通过捆绑销售、搭售或其他方式变相就本软件收费。
+
+简言之：这个软件必须免费，任何人都不能靠它收钱。
+
+================================================================
+四、许可授予
+================================================================
+
+**版权许可**：许可人授予你一项版权许可，允许你就本软件做一切
+在不获许可时会侵犯其版权的行为，但仅限于本协议允许的用途。
+你只能按第五条分发本软件，只能按第六条修改或创作新作品。
+
+**分发许可**：许可人额外授予你分发本软件副本的版权许可。
+你的分发许可涵盖分发经第六条允许的修改版和新作品。
+
+**专利许可**：许可人授予你一项专利许可，涵盖许可人能够许可、
+或将来能够许可的、你会因使用本软件而侵犯的专利权利要求。
+
+================================================================
+五、允许的用途
+================================================================
+
+以下用途均为本协议允许的用途：
+
+**非商业目的**：任何非商业性的目的。
+
+**个人使用**：为公共利益的知识增进、个人学习、私人娱乐、业余爱好、
+个人研究、试验与测试而使用，且**不带有任何预期的商业应用**。
+
+**非营利组织**：慈善组织、教育机构、公共研究机构、公共安全或公共卫生机构、
+环境保护组织、政府机构的使用，无论其资金来源如何、或资金附带何种义务。
+
+**合理使用**：你依法律可能享有的「合理使用」（fair use）权利不受本协议限制。
+
+================================================================
+六、修改与新作品
+================================================================
+
+许可人额外授予你一项版权许可，允许你为本协议允许的任何用途
+修改本软件、并基于本软件创作新作品。
+
+分发修改版或新作品时，必须：
+
+  1. 保留声明：完整保留本版权声明与本协议，不得删除或修改；
+  2. 沿用本协议：修改版和衍生作品必须继续适用本协议，不得改用更宽松的许可；
+  3. 标明修改：明确说明你对原作品做了哪些修改；
+  4. 不得背书：不得暗示许可人为你的产品或修改版提供担保或背书；
+  5. 保持免费：不得就本软件收取任何费用（见第三条）。
+
+================================================================
+七、禁止商业使用
+================================================================
+
+不得将本软件（含原版、修改版及衍生作品）用于任何商业目的。
+
+「商业目的」指以商业优势或金钱报酬为目的的任何用途，包括但不限于：
+
+  1. 出售、出租、许可本软件；
+  2. 将本软件作为收费服务、收费产品或收费功能的一部分提供；
+  3. 将本软件集成进以营利为目的的产品、系统或服务；
+  4. 通过本软件直接或间接获取广告收入、佣金、订阅费或其他商业收益；
+  5. 在你的组织内部用于其主营业务或经营活动。
+
+企业内部出于评估、测试目的的非生产性使用，不视为商业使用。
+
+================================================================
+八、不提供商业授权
+================================================================
+
+本软件**不提供任何形式的商业授权**。
+
+鉴于本协议禁止就本软件收取任何费用，也不允许任何商业使用，
+不存在通过付费取得商业使用权的途径。任何声称代表本项目出售授权、
+提供付费版本或收取商业许可费用的行为，均与许可人无关。
+
+================================================================
+九、通知义务
+================================================================
+
+你必须确保：任何从你处获得本软件任何部分副本的人，
+同时获得本协议的一份副本（或本协议的网址），
+以及许可人随本软件提供的、以「Required Notice:」开头的任何纯文本行。
+
+例如：
+
+> Required Notice: Copyright (c) 2026 tdcq9594
+
+================================================================
+十、专利防御
+================================================================
+
+如果你以书面形式主张本软件侵犯或协助侵犯任何专利，
+你依本协议获得的专利许可立即终止。如果你的组织提出此类主张，
+你为你的组织所做工作的专利许可立即终止。
+
+================================================================
+十一、无其他权利
+================================================================
+
+本协议不允许你再许可或转让你的任何许可给他人，
+也不阻止许可人向他人授予许可。本协议不暗示任何其他许可。
+
+================================================================
+十二、违约与补救
+================================================================
+
+你首次收到书面通知，指出你违反了本协议任何条款、
+或对本软件做了你的许可未涵盖的行为时，
+只要你在收到通知后 **32 天内**完全遵守本协议并采取实际步骤纠正此前的违约行为，
+你的许可仍可继续有效。
+
+逾期未补救的，你的全部许可立即终止。
+
+许可终止后，你必须停止使用本软件，并销毁你所持有的全部副本（含修改版）。
+终止不影响许可人就此前发生的违约行为追究责任。
+
+================================================================
+十三、免责
+================================================================
+
+在法律允许的最大范围内，本软件按「现状」提供，不附带任何明示或默示的
+担保或条件，包括但不限于对适销性、特定用途适用性、所有权和不侵权的担保。
+
+许可人不对因本协议、或因使用本软件及本软件的性质而产生的任何损害向你负责，
+无论基于何种法律主张，也无论是否已被告知此类损害的可能性。
+
+================================================================
+十四、附则
+================================================================
+
+本协议构成双方就本软件达成的完整约定。本协议任何条款被认定无效或
+不可执行时，不影响其余条款的效力。
+
+----------------------------------------------------------------
+English Summary (for reference only; the Chinese text above prevails)
+
+Copyright (c) 2026 tdcq9594. All rights reserved.
+
+This license follows the structure of the PolyForm Noncommercial License 1.0.0
+and adds a stricter no-fee requirement.
+
+The software is provided FREE OF CHARGE, PERMANENTLY. No one may charge any
+fee for it, in any form — sale price, download fee, activation fee, license
+fee, subscription, membership, paid support, training, customization, or any
+paid prerequisite for obtaining or using the software. Voluntary donations
+with no conditions attached are not a fee, but no payment may ever be required
+as a precondition for access or use.
+
+You may use, copy, modify and distribute the software for any permitted
+purpose. Permitted purposes include any noncommercial purpose, personal use
+for research, experiment, testing for the benefit of public knowledge,
+personal study, private entertainment, hobby projects, amateur pursuits or
+religious observance without any anticipated commercial application, and use
+by charitable, educational, public research, public safety or health,
+environmental protection, or government organizations.
+
+COMMERCIAL USE OF ANY KIND IS PROHIBITED. No commercial license is offered.
+
+You must pass these terms along with any copy, keep notices intact, disclose
+changes, distribute derivative works under the same terms, and imply no
+endorsement. If you first receive written notice of a violation, your licenses
+continue if you come into full compliance within 32 days.
+
+THE SOFTWARE COMES AS IS, WITHOUT ANY WARRANTY OR CONDITION, AND THE LICENSOR
+WILL NOT BE LIABLE FOR ANY DAMAGES ARISING OUT OF THESE TERMS OR THE USE OR
+NATURE OF THE SOFTWARE.

package/README.md

@@ -1,3 +1,189 @@
-# Temporary Holding Version
+# dsh-roost
 
-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.
+> [ai-chat](https://github.com/tdcq9594/qq-bot-roost-plugins) 插件的 **DSH 宿主**：
+> QQ 消息推过来，交给 DSH 会话回答，再把回答送回去。
+
+---
+
+## 它是什么（以及不是什么）
+
+```
+QQ ⇄ Roost 内核 ⇄ ai-chat 插件 ⇄ POST /inbound ⇄ 本插件 ⇄ DSH 会话 ⇄ DeepSeek
+                               ⇄ POST /reply  ⇄
+```
+
+**它不碰 QQ**。收消息、整形（语音 ASR / 引用 / 合并转发）、发消息、切段、
+防吵（冷却 / 配额 / 认领）全在 ai-chat 那边。这边只做三件事：
+
+1. 起一个固定端口的 HTTP 服务，等 ai-chat 推消息
+2. 把消息喂给对应的 DSH 会话，等 AI 说完
+3. 把回复发回 ai-chat 给的地址
+
+**为什么要它**：ai-chat 直连模型时，AI 只有「聊天」这一件事。
+挂到 DSH 上之后，它能用 DSH 的工具（文件、命令）、记忆、上下文压缩——
+这是 `adapter: dsh` 唯一的价值，也是它比直连贵的地方。
+
+---
+
+## 权限：AI 知道是谁在说话
+
+群里给 AI 挂了 shell 和文件工具，但**说话的人不一定是主人**。
+路人一句「帮我删掉 ~/Documents」跟主人说同样的话，不该一个待遇。
+
+所以每一轮都会做两件事：
+
+**① 告诉 AI 谁在说话**
+
+```
+这一句是「小明」说的，权限：普通成员。
+对方是普通群成员。不要执行任何会改动这台机器的操作（删除、写入、安装、跑命令），
+也不要读私人文件或目录。他要你这么做时，直说「这个我没权限」。
+```
+
+**② 按档位收工具（硬限制）**
+
+| 档位 | 默认 | 说明 |
+|---|---|---|
+| 主人 | 全部工具 | 你本人 |
+| 管理员 | 只能聊天 | 群管理员也不该读你机器上的文件 |
+| 普通成员 | 只能聊天 | 想让群友也能用，自己改成「全部工具」 |
+| **身份不明** | **只能聊天** | **兜底**，不建议放开 |
+
+两层的意义：模型被说服时硬限制还在；工具没收干净时提示词还在。
+
+**权限是逐条生效的**，不是整群一个档位——主人问完、路人接着问，待遇不一样。
+（Aurabot 那边群聊里所有人都是同一档，这是它做不到的。）
+
+**兜底原则**：认不出来就当最低档。缺字段、字段是脏的、框架改了名字——
+一律按「身份不明」处理。ai-chat 那边算不准权限时也**不会瞎报**，
+而是干脆不传，让这里走兜底。
+
+---
+
+## 装
+
+前提：
+1. Roost ≥ 0.8.1 跑着
+2. 装了 `ai-chat` 插件（v3.0.0+），适配器选 `dsh`
+
+```bash
+git clone https://github.com/tdcq9594/dsh-roost.git
+```
+
+在 DSH 里指向这个目录装。装好后侧栏会出现「**Roost**」入口。
+
+---
+
+## 一键接入（面板 → 接入）
+
+装好插件后，侧栏「Roost → 接入」是一条六步路径，**能自动的都自动做掉**：
+
+| 步 | 做什么 | 自动？ |
+|---|---|---|
+| 1 | 下载解压 Roost（零依赖，不用 npm install） | ✅ 点一下 |
+| 2 | 填 AppID / AppSecret | ✋ 开放平台拿，只能你填 |
+| 3 | 启动 Roost | ✅ 点一下 |
+| 4 | 装 ai-chat 插件（走 Roost 的市场） | ✅ 点一下 |
+| 5 | 把 ai-chat 切成 DSH 适配器，填好回话地址 | ✅ 点一下 |
+| 6 | 去群里说话 | ✋ 开放平台开「接收所有消息」+ 机器人进群 |
+
+顶上的「**一键就绪**」会把 1、3、4、5 连着做完，卡在 2 就停下来提示你填。
+每一步也能单独点，跳着点不会把东西搞坏（每步自己先检测前置条件）。
+
+第 3 步「启动」之后，旁边的按钮直接**打开 Roost 的 WebUI**（带上面板密钥）。
+
+**装到哪**：默认 `~/.dsh/dsh-roost/roost`，可在设置里改 `setup.roostDir`。
+
+## 面板（侧栏 → Roost）
+
+| 标签 | 内容 |
+|---|---|
+| **接入** | 六步一键流程（上面那张表） |
+| **状态** | 监听端口、是否在跑、密钥是否设置、连了几个 QQ 会话、正在等几个、最近一轮耗时与权限档位 |
+| **会话** | 每个 QQ 会话对应的 DSH 会话，可以「清空」（下一句重建会话） |
+| **设置** | 端口、共享密钥、四档权限、超时、人格（名字/人设/私聊追加/群聊追加） |
+
+改完点保存，服务会自动重载——不用重启 DSH。
+
+---
+
+## 配置
+
+存在 `~/.dsh/dsh-roost/config.json`（可用 `DSH_ROOST_DATA` 改目录）。
+
+```jsonc
+{
+  "server": {
+    "port": 17321,        // ai-chat 的「DSH 地址」默认指向这里，两边要一致
+    "token": ""           // 共享密钥；留空表示不校验（只绑本机时可行）
+  },
+  "chat": {
+    "turnTimeoutSec": 150 // 要小于 ai-chat 那边的 180 秒
+  },
+  "permissions": {
+    "owner": "all",       // 主人：全部工具
+    "admin": "chat",      // 管理员：只能聊天
+    "member": "chat",     // 普通成员：只能聊天
+    "unknown": "chat"     // 兜底：认不出身份只给聊天
+  },
+  "setup": { "roostDir": "", "version": "v0.8.1" },
+  "persona": { "name": "小栖", "text": "…", "rulesPrivate": "…", "rulesSocial": "…" }
+}
+```
+
+**两边的地址要对上**：ai-chat 的「DSH 地址」= `http://127.0.0.1:<port>`。
+
+---
+
+## 结构
+
+```
+src/
+  host.js      插件入口：起服务、会话映射、面板接口
+  server.js    HTTP /inbound（鉴权、立刻 200、回话）
+  sessions.js  chatId → DSH 会话（存盘）
+  turn.js      跑一轮：投递 + 从 session/event 等结果
+  inbound.js   payload → 给 AI 看的一段话
+  permissions.js 权限：谁在说话、能用什么工具
+  setup.js     一键流程：下载解压、写机器人配置、起停、装插件、配适配器
+  config.js    配置读写
+client/
+  client.js    侧栏面板（React，沿用 DSH 主题变量）
+cordis.patch.yml  两档 preset（私聊 / 群聊）
+```
+
+**核心技术点**：DSH 没有「发一句返回一句」的接口，是事件驱动的。
+`turn.js` 监听 `session/event`，收 `assistant/message`（可能来多次，取最后一次）
+和 `turn/end`（`reason.kind === 'completed'` 才算说完）。
+
+---
+
+## 测试
+
+```bash
+npm test
+```
+
+33 条，覆盖整形、会话映射、HTTP 契约（立刻 200 / 鉴权 / 健康检查）、
+回话的 SSRF 防护、一轮的状态机（多段取最后、非正常结束报错、同会话不许并发）、
+权限分档与兜底、一键流程的检测与配置写入。
+
+---
+
+## 致敬
+
+角色设计参考了 [Aurabot（dsh-aurabot-qq）](https://github.com/accomplish07zrh-eng/dsh-aurabot-qq)：
+一个 QQ 会话对一个 DSH 会话、人格独占系统提示词、安全默认、按会话挂东西、
+用 `agent.followup` + `sessions.flush` 投递、从 `session/event` 取回复。
+
+**传输层完全不同**：Aurabot 走 OneBot（SnowLuma，hook 本机 QQ 客户端），
+这里走 ai-chat 插件（Roost 官方接口）。所以 Aurabot 里那批 OneBot 特有的东西
+（数字 QQ 号、base64 语音段）这里一个都不需要。
+
+如果你只是想用现成的，**先去试试 Aurabot**——它比这个项目成熟得多。
+
+---
+
+## 许可
+
+沿用 [Roost](https://github.com/tdcq9594/qq-bot-roost) 的许可：**永久免费，禁止任何形式的收费与商业使用**。