@daoxiang0520

dsh-plugin-whu

Name: dsh-plugin-whu
Availability: InStock
Author: daoxiang0520

No description

Stars: 0
Language: Python
Created: Aug 17, 2026
Updated: Aug 17, 2026

Web UI

GitHub repo

Introduction

dsh-plugin-whu · 武汉大学校园服务 DSH 插件

把武汉大学校园服务（图书馆座位、课表、成绩、考试、天气）以DSH 工具 + Skill + 同页悬浮卡片 + 独立 Web UI 的形式安装进 DeepSeek Harness（DSH）。

项目概要

一句话

学生用自然语言与 DSH Agent 对话（"帮我查课表""预约明天下午的座位"），Agent 调用 whu_* 工具操作武大各业务系统；插件同时提供每页可见的悬浮卡片与 /whu 独立控制台，浏览器里可以直接登录、点选座位。

能力清单

能力	形态	说明
15 个 Agent 工具	`whu_login_password` / `whu_login_qr` / `whu_login_qr_poll` / `whu_get_seats` / `whu_get_seat_map` / `whu_reserve_seat` / `whu_get_current_usage` / `whu_get_reservations` / `whu_cancel_reservation` / `whu_stop_usage` / `whu_query_schedule` / `whu_query_exam_schedule` / `whu_query_grades` / `whu_get_weather`	模型可规划、可调用；`session_id` 被插件内部隐藏（固定 `local` 会话），模型无需理解 MCP 会话概念
`whu_login_qr_image`（UI 专用）	PNG data URL 二维码	仅供 Web UI / 悬浮卡片以 `<img>` 显示；`agentVisible: false`，不进 Agent 工具目录，避免 base64 污染模型上下文
Skill `whu-lib`	随包注册（`source: 'runtime'`）	安装即生效：武大领域知识（登录流程、venueId 映射、查座展示规范、扫码流程），模型按需加载
同页悬浮卡片	注入 DSH 每个页面右下角	免跳转登录与快捷查询；设置页「whu」namespace 可开关、可换左下角（live 生效，前端 5 秒轮询配置）
独立 Web UI	`http://127.0.0.1:<端口>/whu`	完整控制台：图片二维码登录、工具调用、后端状态
DSH 设置卡片	设置 → 插件配置 → whu	`floatingCardEnabled` / `floatingCardPosition`

架构

DeepSeek Harness (dsh)
  ├── ctx.tools    ── 15 个 whu_* 工具（Agent 可调用）
  ├── ctx.skills   ── whu-lib skill（领域知识，按需注入）
  ├── ctx.settings ── whu namespace（悬浮卡片开关/位置）
  └── ctx.webServer ─ /whu 独立页 + tapIndex 悬浮卡片注入
             │
             │ 自研最小 MCP stdio JSON-RPC 客户端（仅 Node 内置模块）
             ▼
     python/server.py --transport stdio（随包分发）
             │
     python/lib/（CAS 登录 / 图书馆 HMAC / 教务 / 天气 / 验证码破解）

技术要点

零编译：插件入口纯 ESM JavaScript，无需构建步骤；
按需拉起：首次工具调用才 spawn Python 进程；进程崩溃自动重启（ensureStarted）；
登录态共享：凭证写入 $DSH_HOME/whu/session.json（经 WHU_SESSION_FILE 注入 Python），同一用户所有工具共享一份登录态，token 过期自动用 CASTGC 刷新；
会话隐藏：登录后无需 session_id，DSH 侧自动补 local；
超时与取消：每个 MCP 请求独立超时 + AbortSignal 支持；
卸载干净：backend dispose、UI route/tapIndex disposer 全部挂 fiber，插件卸载即回收。

目录结构

package/
├── index.js / cordis.patch.yml   # bundle 入口与挂载层
├── src/
│   ├── index.js                  # 插件入口（apply）
│   ├── core.js                   # 核心装载逻辑（可测试）
│   ├── backend.js                # MCP stdio 客户端（Node 内置模块）
│   ├── tools.js                  # 15 个工具定义与注册
│   ├── skill.js                  # runtime skill 注册
│   └── ui.js                     # /whu 路由 + tapIndex 悬浮卡片
├── assets/
│   ├── SKILL.md                  # whu-lib 领域知识
│   └── ui/                       # 控制台 HTML + 悬浮卡片 css/js
├── python/
│   ├── server.py                 # MCP server（stdio）
│   ├── requirements.txt
│   └── lib/                      # CAS/图书馆/教务/天气/验证码
└── test/                         # 测试（含 fake-whu-mcp.py 假服务器）

部署方法

前置要求

依赖	版本/说明
Node.js	`^22.19
dsh	`npx @deepseek-ai/dsh` 或源码构建的 dsh CLI
Python	≥ 3.10，且安装了下述依赖
网络	CAS、图书馆、教务系统可达；`get_weather` 走 Open-Meteo

第 1 步：安装 Python 依赖（一次性）

cd package/python
python -m pip install -r requirements.txt
python -m playwright install chromium
# Linux/WSL 服务器还需系统依赖：
python -m playwright install-deps chromium

依赖清单：mcp、requests、opencv-python、qrcode、playwright、beautifulsoup4、pycryptodomex 等（以 requirements.txt 为准）。

第 2 步：安装插件到 DSH profile

方式 A：从 tarball 安装（推荐）

dsh plugin --profile web add /path/to/dsh-plugin-whu-0.1.0.tgz

方式 B：从本地目录安装（改代码调试）

dsh plugin --profile web add /path/to/dsh-plugin-whu-0.1.0/package

方式 C：从 GitHub 安装（发布后）

dsh plugin --profile web add github:<you>/dsh-plugin-whu

本插件入口是纯 ESM JS、不需要编译；若 pnpm 提示 allowBuilds，按提示在 profile 的 pnpm-workspace.yaml 中放行即可（tarball/目录安装不需要）。

第 3 步：Windows 用户补一行配置（关键）

bundle 默认 pythonCommand: python3；Windows 需在 profile 的 cordis.patch.yml 覆盖（注意是裸行语法）：

- id: whu
  config:
    pythonCommand: python
    toolPrefix: whu_
    uiPath: /whu
    uiEnabled: true
    registerSkill: true
    skillName: whu-lib
    defaultTimeoutMs: 120000

第 4 步：验证

# 组合验证：应看到 "# == dsh-plugin-whu" 层
dsh --profile web --dump-config

# 启动
dsh web

# 浏览器验证：
#   http://127.0.0.1:3080/whu            独立控制台
#   http://127.0.0.1:3080/whu/api/health 后端状态（JSON）
#   http://127.0.0.1:3080/whu/api/tools  15 个工具清单

配置项

字段	默认	说明
`pythonCommand`	`python3`	启动 `python/server.py` 的解释器（Windows 改 `python`）
`toolPrefix`	`whu_`	Agent 工具名前缀；SKILL.md 内容自动同步替换
`uiPath`	`/whu`	独立 UI 路由前缀
`uiEnabled`	`true`	是否注册 Web UI
`registerSkill`	`true`	是否注册 runtime skill
`skillName`	`whu-lib`	skill 注册名（与本地 skill 冲突时可改）
`defaultTimeoutMs`	`120000`	MCP 调用默认超时
`debug`	`false`	转发 Python stderr 日志

设置页 namespace whu：floatingCardEnabled（悬浮卡片开关）、floatingCardPosition（bottom-right / bottom-left）。

登录与使用

对话中说"帮我登录武大"→ Agent 调 whu_login_qr 输出 ASCII 二维码 → 手机「智慧珞珈」扫码 → 说"扫好了" → Agent 调 whu_login_qr_poll 完成登录；
或打开 /whu 控制台 / 悬浮卡片，用图片二维码登录（UI 专用，不进对话）；
登录态约 4 小时有效（CASTGC 会话级），token 过期（约 30 分钟）自动刷新；
之后直接说"总馆明天有座位吗""帮我预约 305 区下午 2 点""查一下 GPA"。

卸载

dsh plugin --profile web remove dsh-plugin-whu

已知限制

只捆绑 stdio 后端；未实现 DSH 直连远程 SSE（https://whu-mcp.daoxiang.xyz）transport，需要时扩展 src/backend.js；
密码登录的参数会进入 DSH 会话日志；对日志保密要求高时优先 whu_login_qr 扫码或在 /whu 控制台登录；
独立 UI 仅在 Web profile（存在 ctx.webServer）下出现；headless/CLI 中 Agent 工具与 Skill 仍可用；
凭证文件含 CASTGC 与图书馆 token（不含明文密码），权限取决于 $DSH_HOME/whu/ 目录权限。

License

MIT