feihu1991/dsh-kefu

dsh-kefu — DSH 多租户客服平台

给 DeepSeek Harness 套一层多租户客服平台壳：
一台服务器集中管理多个商家，每个商家用独立账号登录，创建自己的「店员 Agent」
（可选模型服务档位，档位细节由平台屏蔽），通过控制台或网页问答组件接待顾客。

典型场景：淘宝智能客服 SaaS。平台方开账号 → 商家登录创建客服 Agent → 顾客在店铺网页上咨询。

┌──────────────────────────────────────────────────────────────┐
│  商家电脑：KefuClient（Tauri 桌面壳）→ 打开 {服务器}/kefu/       │
│  顾客浏览器：店铺网页 iframe 引入 {服务器}/kefu/widget/   │
└──────────────────────────┬───────────────────────────────────┘
│ HTTP / SSE
┌──────────────────────────▼───────────────────────────────────┐
│  服务器：dsh web（DeepSeek Harness Web 实例）                   │
│    └── 插件 dsh-kefu（本仓库 server/）                          │
│         ├── SQLite：商家 / 账号 / 档位 / Agent / 会话 / 消息      │
│         ├── 账号体系：scrypt 密码 + 会话 Cookie，登录锁定          │
│         ├── RBAC：平台超管 / 商家管理员 / 店员                    │
│         ├── 限流：每账号 / 每 IP 滑动窗口                         │
│         ├── 店员 Agent：复用 DSH 的 ctx.agents 会话引擎           │
│         │     （模型档位 → provider/model，人设注入 system prompt，│
│         │      多轮会话持久化，SSE 流式回复）                      │
│         └── 商家控制台前端（React SPA，由插件静态托管）             │
└──────────────────────────────────────────────────────────────┘

目录

| 目录 | 说明 |
|---|---|
| server/ | DSH 插件 dsh-kefu（核心交付，挂到 web profile） |
| console/ | 商家控制台前端源码（React + Vite，构建产物进 server/public/） |
| client/ | 桌面客户端（Tauri 2 壳子，连接服务器地址） |
| docs/ | 详细文档（API 一览、部署、二次开发） |

快速部署（服务器）

前置：Node 22.5+ / pnpm（数据层使用 node:sqlite，Node 18/20 不可用）、DeepSeek Harness（npm i -g @deepseek-ai/dsh）、一个模型 API Key。

1. 构建控制台前端（产物写入 server/public/）
cd console && npm install && npm run build && cd ..

2. 安装插件到 web profile（两种方式任选）
dsh plugin --profile web add /path/to/kefu/server          # 本地目录
dsh plugin --profile web add dsh-kefu                      # 发布到 npm 后

3. 编辑 profile 的 package.json，把 dsh-kefu 加进 bundles 列表
"dsh": { "profile": { "bundles": [..., "dsh-kefu"] } }

4. 启动（对局域网开放用 0.0.0.0）
DEEPSEEK_API_KEY=sk-xxx dsh web --host 0.0.0.0 --port 3080

启动后：

- 客服平台：http://:3080/kefu/（首次注册商家账号）
- 平台超管：默认账号 admin，密码在启动日志里打印（[kefu] 已创建平台超管），首次登录后请修改
- 服务档位：默认创建「高级客服 / 中级客服 / 基础客服」三档（映射到 DeepSeek 模型），
超管可在「平台管理 → 服务档位」调整或新增（provider/model 对商家不可见）

对外暴露端口时建议在前面加一层反向代理（HTTPS），并把
dsh web --trusted-host 加上你的域名（远程浏览器设置功能需要）。

推荐的插件配置：
- HTTPS 部署时设置 secureCookie: true，为会话 Cookie 增加 Secure 标志；
- 只有请求确实经过可信反向代理时才设置 trustProxy: true，此时按 X-Forwarded-For 最右侧地址做 IP 限流；
- 默认 exposeSessionToken: false，登录只下发 HttpOnly Cookie；仅当外部客户端必须使用 Bearer 时才显式开启；
- 每个商家每天的 widget 消息额度由 widgetDailyMessageLimit 控制（默认 2000，0 = 不限制），超管可在平台设置中调整。

核心能力

多租户与数据隔离
- 商家（merchant）是隔离单元；账号、Agent、会话、消息全部按 merchant_id 隔离
- 每个商家有独立工作区目录 dataDir/merchants//，Agent 的 DSH 会话 cwd 指向它
- 越权访问（跨商家读会话 / 改 Agent）一律 404

账号与权限
| 角色 | 能力 |
|---|---|
| superadmin | 平台管理：商家 / 账号 / 档位 / 平台设置 / 审计 |
| merchant_admin | 商家管理员：建店员账号、建/改/停 Agent、网页客服凭据、接待 |
| merchant_staff | 店员：仅接待会话 |
- 密码 scrypt 存储；登录连续失败 5 次锁定 15 分钟；锁定期内使用正确密码仍可登录并立即解锁（避免攻击者用错误密码把真实用户持续锁死）；会话 12 小时（默认仅 HttpOnly Cookie，exposeSessionToken: true 时额外支持 Bearer）

店员 Agent
- 商家创建 Agent：名称、人设话术、服务档位（商家只看到档位名，如「高级客服」，看不到 provider/model）
- 每轮对话由插件通过 ctx.agents.create/resume 驱动 DSH 会话：
- 档位 → {provider, model, maxTokens} 注入 AgentOptions
- 人设注入 system prompt（并遮蔽 Harness 的通用身份/运行时上下文，禁用全部工具，保持纯客服行为）
- 多轮上下文由 DSH 会话持久化自动续接
- 回复通过 SSE 流式返回（delta 事件含文本与思考过程；done 含最终文本与 token 用量）

知识库（RAG v1）
- 商家在「知识库」录入商品资料 / 售后政策 / 常见问答（可指定某 Agent 专用或全店共享）
- 顾客提问时自动检索（FTS5 trigram 整句匹配 + 2 字关键词 LIKE 回退，中文口语友好），
把命中的资料作为权威依据注入客服 system prompt，回答优先照实引用资料、不编造

客服网页问答（v1 可用 + v2 悬浮球 SDK）
- 商家在「店员管理 → 网页客服」生成凭据 token，拿到三种接入方式：
1. 独立问答页 {base}/widget/：可发链接，可 iframe 嵌入店铺网页
2. 悬浮球 SDK（推荐）：店铺页面加一行
，
右下角气泡聊天面板，自动续接会话（演示页 {base}/sdk-demo.html?token=…）
3. 公开接口（免登录、按 IP + token 双限流）：
- GET  {base}/widget//config — 商家名 / 客服名 / 欢迎语
- GET  {base}/widget//visitor — 获取服务端 HMAC 签名的 visitorId
- POST {base}/widget//messages — 聊天（请求携带签名的 visitorId 续接同一会话）
- 凭据可配置店铺 Origin 白名单（如 https://shop.example.com）：带 Origin 的浏览器请求必须匹配，否则 403
- 每个商家有每日 widget 消息额度（widgetDailyMessageLimit，默认 2000，0 = 不限制），防止公开 token 被滥用刷模型费用
- 规划：知识库向量化（语义检索）、转人工、订单查询工具

限流与额度
- 登录：10 次/分钟/IP；注册：按 IP；聊天：30 次/分钟/账号 + 60 次/分钟/IP；网页客服：10 次/分钟/凭据
- 每个商家每天另有 widget 消息总额度（默认 2000，0 = 不限制）
- 超管可在「平台设置」改数值，即时生效（内存滑动窗口与 SQLite 跨进程回合锁配合）

API 一览（前缀 {base}/api，默认 /kefu/api）

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /auth/register | 注册商家（可后台关闭） |
| POST | /auth/login / /auth/logout | 登录 / 退出 |
| GET | /auth/me | 当前用户 + 商家 + 档位 |
| GET | /tiers | 服务档位（仅公开字段） |
| GET/POST | /agents | 店员 Agent 列表 / 新建 |
| PATCH/DELETE | /agents/:id | 改 / 删 Agent |
| GET/POST | /agents/:id/widget-tokens | 网页客服凭据（可含店铺 Origin 白名单） |
| GET/POST | /conversations | 会话列表 / 新建 |
| GET/POST | /conversations/:id/messages | 历史 / 发消息（SSE 流式） |
| PATCH | /conversations/:id | 关闭 / 重开 / 改标题 |
| GET/POST | /users | 商家账号（merchant_admin） |
| GET/POST | /kb /kb/:id | 知识库（商家管理员） |
| GET | /stats | 商家统计 |
| GET/POST | /admin/merchants /admin/users /admin/tiers | 平台管理 |
| GET/PATCH | /admin/settings | 平台设置（注册开关 / 限流 / widget 每日额度） |
| GET | /admin/stats | 平台统计 + 审计 |
| GET/POST | /widget/:token/config /widget/:token/visitor /widget/:token/messages | 网页问答公开接口（Origin 白名单 + 签名 visitorId + 每日额度） |

错误统一 {error: {code, message}}；429 限流、401 未登录、403 无权限、404 不存在/越权。

开发与测试

控制台开发（vite 代理到 3080 的 dsh web）
cd console && npm run dev

插件 API + Agent 工具隔离测试（不需要模型 API Key）
cd server && pnpm install && pnpm test

用独立 DSH_HOME 起一个测试实例（不动正式实例）
DSH_HOME=~/.dsh-kefu dsh --profile web --host 127.0.0.1 --port 3100

数据目录
$DSH_HOME/kefu/kefu.sqlite          # 全部业务数据
$DSH_HOME/kefu/merchants//      # 商家工作区

安全注意
- 上线必须 HTTPS（反向代理），并设置 secureCookie: true，否则密码/会话 Cookie 会被嗅探
- 只有经过可信反向代理时才设置 trustProxy: true；否则保留默认值，直接按 TCP 对端地址限流
- 建议关闭自助注册（平台设置），由超管统一开账号
- 登录锁定不影响正确密码登录：攻击者无法通过持续输错密码把账号永久锁死
- 网页客服凭据建议配置店铺 Origin 白名单；visitorId 由服务端 HMAC 签名，无法伪造/枚举
- 设置 widgetDailyMessageLimit 防止公开 token 被滥用消耗模型费用
- 客服 Agent 通过 tools.restrict({ allow: [] }) 白名单禁用全部工具；若目标 DSH 不支持该能力，接待会 fail-closed（直接失败），不会带着工具继续运行。升级 DSH 后请跑工具可见性冒烟测试
- kefu-state.json 含 widget 签名密钥，文件权限为 0600；备份时请按敏感配置处理
- 定期备份 kefu.sqlite 与 merchants/ 目录

License
MIT