astrbotplugindsh

August 14, 2026 · View on GitHub

AstrBot 插件：把白名单内的聊天消息接入 DeepSeek Harness（DSH）Agent Runtime，由 DeepSeek 模型回复，并带有一整套面向公网聊天入口的安全控制。

聊天平台 ──▶ AstrBot ──▶ 本插件 ──ACP─▶ DSH Agent Runtime ──▶ DeepSeek 模型
                ▲                                  │
                └──────────── 回复 ─────────────────┘

接口：DSH 官方面向自动化的 ACP（Agent Client Protocol），通过子进程 stdin/stdout 的 JSON-RPC 通信，支持按会话取消与超时终止。
开发环境 Windows、部署环境 Linux 都支持（source_checkout 模式从固定版本的 DSH 源码检出启动；acp_binary 模式直接运行已构建的 dsh-acp-demo）。
纯标准库实现，无第三方 Python 依赖。

安装

在服务器上准备一个固定版本的 DeepSeek Harness 检出（git clone 后 pnpm install），例如 /opt/deepseek-harness。Windows 开发机同理（本仓库默认配置指向 D:\Applications\ds-harness\deepseek-harness）。
把本仓库放进 AstrBot 插件目录（data/plugins/astrbot_plugin_dsh），或在 AstrBot 面板中安装。
在 AstrBot 面板打开插件配置页，至少填写：
- dsh.dsh_root：DSH 检出根目录（source_checkout 模式必填）；
- 白名单：access.group_whitelist / access.private_whitelist；
- 模型：dsh.model。
在 服务器环境 中设置 DeepSeek API Key（推荐，不要写进配置面板）：
```
export DEEPSEEK_API_KEY=sk-...
```
插件会用 dsh.api_key_env 指定的变量名读取它；只有该变量名列在白名单里，其他服务器环境变量不会传给 DSH。

快速验证（Linux 服务器）

export DEEPSEEK_API_KEY=sk-...
python scripts/smoke_acp.py --dsh-root /opt/deepseek-harness              # 只验证启动+会话创建
python scripts/smoke_acp.py --dsh-root /opt/deepseek-harness --real-turn   # 再跑一次真实模型对话

Windows 开发机把 --dsh-root 换成 DSH 检出路径即可。随后在 AstrBot 中确认白名单会话能收到 DSH 回复，/dsh status 显示正常。

插件指令

指令	作用
`/dsh help`	显示帮助
`/dsh status`	查看模型、活跃会话数、限额与白名单数量
`/dsh reset`（或 `/dsh_reset`）	清空当前会话的 DSH 上下文

安全设计

面向公网聊天入口，安全按“能力不挂载 + 进程隔离 + 数据边界 + 输出脱敏”四层实现，而不是只靠提示词：

模型零工具：插件随附的 runtime/cordis.yml 不挂载 Bash、文件读写、Web、MCP、子代理、工作流、hook、skill、后台任务和人工审批工具；workspaceContext: false 阻止读取工作区里的 AGENTS.md 等指令文件；includeRuntimeContext: false 阻止把 DSH 运行时信息（含文件沙箱策略）注入上下文。模型可见输入只有系统人格 + 用户消息，聊天内容无法借此操作服务器。
独立子进程与最小环境：每个聊天会话一个 DSH 子进程，工作目录、HOME、TMP、DSH_HOME 全部重定向到插件数据目录下的隔离目录；子进程环境只包含 PATH、系统基础变量和插件显式注入的模型参数，不继承服务器上的其他密钥/凭据。
权限请求一律拒绝：DSH 发起 session/request_permission 时插件只回答 cancelled（fail-closed），不向聊天用户开放任何授权通道。
输入策略：长度上限；剥离 ANSI/零宽字符/Bidi 控制符；明显要求“忽略系统提示、泄露密钥、读服务器文件、执行命令”的消息直接拒绝；用户文本统一包装成 JSON 标记为不可信数据。
输出脱敏：API Key/Bearer、私钥块、/etc|/proc|... 路径、C:\... 路径、内网/回环 IP 在回复中自动打码；配置中的关键路径也按字面量替换。输出超长截断。
超时与限流：单请求超时后先发 ACP session/cancel 再终止整个子进程，避免后台任务残留；每会话限每分钟请求数与最小间隔；活跃子进程数有上限并按 LRU 淘汰；空闲会话到时回收（上下文随之清除）。
白名单：群聊按 group_id、私聊按 sender_id 匹配，可用 平台ID:ID 或 平台类型:ID 精确限定平台实例；空列表 = 不响应。未命中白名单的消息完全不进入 DSH。群内上下文可配置为全群共享或按成员隔离。

边界说明

本插件的“零工具”配置使模型在 DSH 进程内没有宿主机操作能力；DSH 进程运行在什么账户下，仍取决于你如何启动 AstrBot。生产环境建议进一步用独立低权限系统账户（或容器）运行 AstrBot，这是纵深防御的最后一层。
dsh.cordis_config 允许管理员换用自己的 Cordis 组合；一旦在其中挂载 Bash/文件工具，以上第 1 条的保证即失效，请自行评估。
插件不会把聊天用户的任何内容写入自己日志；DSH 侧默认不落会话日志（内置组合未挂载持久化），但自定义 Cordis 可能改变这一点。

配置说明（AstrBot 面板）

access.group_whitelist / access.private_whitelist：留空表示不响应。ID 获取：群内发送 /sid 或从 AstrBot 日志查看。
access.group_scope：group（全群共享上下文）/ group_sender（群内每人独立上下文）。
access.require_wake：默认关闭——白名单内的每条消息都会进入 DSH；开启后只处理 @机器人/@全体/引用机器人/唤醒前缀消息。/dsh 指令用正则过滤器注册，不受唤醒前缀配置影响，任何时候都能直接触发。
dsh.launch_mode：source_checkout（推荐，DSH 源码检出 + node + tsx，Windows/Linux 通用）；acp_binary（已构建的 dsh-acp-demo 可执行文件）。
dsh.command：source_checkout 填 node（PATH 查找）；acp_binary 填可执行文件绝对路径。
dsh.dsh_root：DSH 检出根目录（source_checkout 必填）。
dsh.cordis_config：留空使用内置安全配置；自定义必须绝对路径且后果自负。
dsh.api_key / dsh.api_key_env：优先用环境变量；直接填 Key 会明文存进插件配置文件。
其余项为模型参数（provider/model/base_url/thinking/effort/token/上下文窗口）与资源限额（超时、长度、并发、限流、会话 TTL）。

开发与测试

python -m pytest tests

tests/test_security.py：输入清洗、注入拦截、输出脱敏；
tests/test_access.py：白名单匹配与会话键隔离；
tests/test_config.py：配置解析、默认值、夹紧与安全校验；
tests/test_pool.py：会话池复用/串行/淘汰/限流/重置；
tests/test_acp.py：子进程最小环境与随附配置的安全断言；
tests/test_plugin_surface.py：按 AstrBot 插件规范校验类结构、元数据与配置 schema。

ACP 传输与超时/取消逻辑依赖进程管道，请在你的 Linux 机器上用 scripts/smoke_acp.py（--real-turn）做端到端验证；在 AstrBot 中安装后可用 /dsh status 和真实群聊确认。