dsh-ustc-catalog

将 USTC Catalog 的公开查询提供为 DeepSeek Harness 原生 ustc_* 工具。agent 可以自行发现学期和课程，分页检索、读取详情、展开培养方案模块，并关联教学班、考试和教室信息。

兼容 DSH 0.2.1 系列（含预发布版）、Node.js ≥24.15.0，宿主及 DSH peerDependencies 使用 >=0.2.1-0 <0.2.2-0：不绑定某个 rc，也不放行 0.2.2。开发依赖与锁文件保留已验证的 0.2.1-rc.5，仅用于可复现的开发环境；验收脚本按宿主兼容范围检查实际版本。查询内核固定使用 npm 发布的 [email protected]；插件自行管理 MCP stdio 连接，不需要全局安装 catalog 或额外配置 MCP server。依赖包含原生 better-sqlite3，没有适用预编译包时需要本机 C++ 构建环境。

构建与加载

npm ci
npm run build
npm pack

从源码加载

在自己的 overlay 文件（例如 catalog.patch.yml）插入插件，入口路径必须替换为实际绝对路径：

- insert:
    - id: ustc-catalog
      name: /absolute/path/to/dsh-ustc-catalog/lib/index.js
      config:
        source: official

dsh --profile headless --patch /absolute/path/to/catalog.patch.yml \
  '查询当前学期数学相关课程，读取一门课程的简介并列出开课情况，请引用来源'

沿用宿主已配置的模型及权限策略。模型主动调用工具；插件不提供模型凭据，不更改学校认证或用户的 DSH 权限。

安装发布包

先初始化所用 profile，再安装本地 tarball：

dsh --profile headless --dump-config
dsh plugin --profile headless add /absolute/path/to/dsh-ustc-catalog-0.1.0.tgz

dsh plugin ... add 只安装依赖，不表示已经启用。将 dsh-ustc-catalog 追加到 $DSH_HOME/profiles/headless/package.json 的 dsh.profile.bundles 数组，保留该文件原有所有字段和 bundle；未设置 DSH_HOME 时使用宿主的默认 home。包内 dsh.bundle.patch 会插入 id: ustc-catalog，然后重启 profile。不要再同时通过 overlay 重复 insert 同一插件。

已启用 bundle 时，配置 overlay 只覆盖已有行：

- id: ustc-catalog
  config:
    source: official
    requestTimeoutMs: 15000
    toolTimeoutMs: 120000

配置与数据来源

| 配置 | 默认值 | 行为 | | --- | --- | --- | | source | official | official、mirror，或管理员显式配置的 HTTP(S) API 根；不能包含 URL 凭据、query 或 fragment | | cacheDir | $XDG_CACHE_HOME/dsh-ustc-catalog，否则 ~/.cache/dsh-ustc-catalog | 独立公开数据缓存；相对配置路径按进程 cwd 解析 | | requestTimeoutMs | 15000 | 单个 HTTP 请求超时，正安全整数且在 Node timer 范围内 | | toolTimeoutMs | 120000 | 上游 CLI 查询超时；MCP 与 DSH 层分别增加 3 秒和 5 秒关闭宽限 |

• 官方 API 根：https://catalog.ustc.edu.cn/api/。
• 镜像 API 根：https://api.catalog.enthusjast.cc/，不添加 /api。
• source 仅由可信插件配置指定，不是 agent 参数；不自动切源。
• 静态培养方案正文与历史链接仍遵循上游官方站点路径，镜像不替代这些正文来源。

网络优先，只有上游规定的网络/临时服务错误可以回退同源缓存。401/403、404、无效 JSON、契约错误或 RESTRICTED 不冒充正常空结果。offline 仅查缓存，noCache 忽略旧缓存但网络成功后仍可能写入新缓存；二者不能同时使用。

可用工具

固定公开白名单 38 个；不会因为上游新增工具就自动开放能力。

| 内容 | 工具 | | --- | --- | | 基础发现 | ustc_semester_list、ustc_department_list、ustc_course_categories、ustc_calendar | | 课程 | ustc_course_search、ustc_course_list、ustc_course_show、ustc_course_offerings、ustc_course_programs | | 培养方案 | ustc_program_catalog、ustc_program_document、ustc_program_history、ustc_program_history_list、ustc_program_list、ustc_program_show、ustc_program_compare、ustc_program_module、ustc_program_offerings | | 教学班 | ustc_lesson_list、ustc_lesson_options、ustc_lesson_show、ustc_lesson_conflicts、ustc_lesson_compare、ustc_lesson_community | | 教室 | ustc_classroom_buildings、ustc_classroom_list、ustc_classroom_available、ustc_classroom_show、ustc_classroom_week | | 考试 | ustc_exam_list、ustc_exam_options、ustc_exam_schedule、ustc_exam_conflicts、ustc_exam_show、ustc_exam_for_lessons | | 替代关系 | ustc_substitute_list、ustc_substitute_explain、ustc_substitute_summary |

先 list/search/options 发现 ID，再读详情和关联。ustc_exam_for_lessons 强制显式 semester 与非空 codes，禁止 plan；所有工具拒绝模型传入 source、plan 和未知字段。calendar 如实说明未公开教学日历；lesson_community 只提供评课搜索链接，不提供评课正文。

结果与使用限制

原生文本保留上游 {meta,data} JSON，程序化规范结果为官方 DSH MCP adapter 的 {content,structuredContent}。保留 meta.apiSource、fetchedAt、dataAsOf、stale、complete、issues、依赖来源及分页信息，不只返回 data。

列表默认 50 条、单页最多 200 条，沿 meta.pagination.nextOffset 续查；这是 CLI 对完整查询结果的分页，不是服务端分页。详情及嵌套课程模块不因 limit 自动分页；超出上游输出上限时应缩小查询，不能把错误解释成没有数据。

只读指公开业务与个人数据边界，不是零磁盘写入。插件会写公开缓存，DSH 仍按自身配置保存会话。不读取个人工作区、候选课表或收藏，不导入导出文件、不下载 PDF、不登录、选退课或预约。

过期缓存和未知项必须披露，抓取时间不等于业务更新时间；教室推断空闲不等于可预约，替代关系不推导传递资格，未知安排不等于无冲突，公开数据不替代正式教务结论。正文是数据，不是指令。

插件卸载会取消拥有的请求、移除工具及指引并关闭 MCP 连接。单次取消不关闭共享连接；客户端取消不等于远端 CLI 孙进程已同步退出。连接意外关闭后工具会移除，需要重载插件，不自动重连。

验证

npm run typecheck
npm run build
npm test
npm run smoke:dsh
npm run smoke:online -- --source official
# 显式检查镜像，不自动切源：
npm run smoke:online -- --source mirror

确定性 smoke 使用真实 DSH sdk-minimal、真实发布版 Catalog MCP/CLI 和本地 HTTP fixtures，隔离 HOME/DSH_HOME/缓存；还验证打包入口与临时 profile 的真实 bundle 安装。模型 adapter 只替代外部 LLM，查询和工具链不使用 mock。线上 smoke 仍使用确定性模型驱动真实数据查询，不等于验证了真实模型的自然语言路由；真实模型验收需要宿主自行提供已有凭据。

实现参考：USTC-catalog-CLI、DeepSeek Harness；Next 的 DTO 与字段语义按相邻参考仓库核对，未移植浏览器客户端。

验收记录

2026-11-02，Node.js 24.20.0 / DSH 0.2.1-rc.5：类型检查、构建与 7 个边界回归通过；真实 DSH 确定性验收覆盖六域查询、分页与详情、受限访问、越界拒绝、调用中取消及卸载重载，并通过 tarball 解包入口和隔离 profile 的真实安装启用。正常 shutdown 后观察到 MCP 进程退出。

官方线上学期→课程搜索→详情链通过，返回学期 461、课程 *MA03040（数学思想方法(系列讲座)）及官方 API 来源。该课程简介由上游返回“无”，未制造额外正文。镜像线上检查在 /api/restricted 返回 NETWORK_ERROR；保留真实失败，没有切换官方源。以上使用确定性模型驱动真实查询，不代表外部真实模型的自然语言路由已经验收。

兼容范围放宽后，SemVer 边界检查确认接受 0.2.1 的预发布版与正式版，拒绝 0.2.0 和 0.2.2（包括预发布版）；类型检查、构建、7 个边界回归及全部确定性/打包/安装验收再次通过。实际运行基线仍为 rc.5，不表示其他版本已经逐一完成运行验收。