USTC Catalog CLI

将中国科学技术大学 Catalog 的公开查询带到终端。使用 TypeScript、Node.js 和 SQLite，默认中文表格，支持 JSON、CSV 和适用场景的 ICS。

本文对应 0.4.0，包含候选方案、工作区和 JSON v2。该版本发布到 npm 前，请使用下方源码构建方式体验新功能。

安装与第一次查询

需要 Node.js 22 或更新版本，以及可运行 better-sqlite3 的环境。

npm install --global ustc-catalog-cli
catalog --version
catalog --help
catalog course search 数学
catalog lesson list --course 数学
catalog classroom list --available
catalog exam options

程序命令名是 catalog，MCP 入口是 catalog-mcp。catalog --version 输出类似 USTC-catalog-CLI 0.4.0。

从源码构建并运行：

git clone https://github.com/Enthusjast/USTC-catalog-CLI.git
cd USTC-catalog-CLI
npm ci
npm run build
node dist/main.js --help
# 可选：将当前源码链接为 catalog/catalog-mcp 命令
npm link

以下命令中的学期、培养方案 ID 和课堂号仅作示例，需以实际列表结果为准。日期统一使用上海时区；自然周为星期一至星期日。

公开查询

| 命令 | 功能 | | --- | --- | | semester list、department list | 发现学期、院系 | | course search <关键词> [--department …] | 院系筛选，按精确编号、精确名称、前缀和关键词排序 | | course categories/list/show | 课程分类目录、课程详情 | | course offerings <课程号> --years 2 | 当前学期以前的开课记录，最多回溯 5 年；失败不算未开课 | | course programs <课程号> --grade 2026 | 扫描指定年级培养方案，保留模块路径和要求 | | program catalog/document/history | 静态方案正文、关键词搜索、历史归档及显式 PDF 下载 | | program list/show/module/compare | 官方培养方案、公共模块展开和方案比较 | | program offerings <计划ID> --semester … | 方案课程与目标学期全部教学班关联 | | lesson list/options/show | 全校开课、动态筛选选项、列表与补充详情关联 | | lesson compare <课堂号...> --semester … | 比较同课教学班的教师、时间、容量、教材及考核 | | lesson conflicts <课堂号...> --semester … | 分别报告已确认冲突和无法检查项 | | lesson community <课堂号...> --semester … | 评课搜索链接；可显式提供自己的本地索引 | | lesson diff --baseline <JSON> | 同学期快照差异；部分基线不推断全部新增项 | | classroom buildings/list/show/week/available | 教室目录、使用记录、周汇总、时段/日期/教学周空闲查询 | | exam list/options/show/schedule/conflicts | 考试查询、日程与同考场冲突 | | exam for-lessons <课堂号...> --semester … | 教学班个人考试与时间冲突；也可使用 --plan | | substitute list/explain/summary | 直接替代关系、原始关系依据、官方汇总表 | | calendar | 网站教学日历占位说明，不推断学校放假或调课安排 |

高级教学班筛选包括 --campus、--language、--exam-mode、--course-category、--discipline 和 --grading。后两项筛选及 lesson options 的相应维度仅在字段缺失时批量加载详情，每批最多 100 条、并发最多 3。课程类别与课程范畴分类 --course-classify 分开保留。

catalog lesson list --semester 461 --campus 东校区 --language 中文
catalog lesson options --semester 461 --grading 百分制
catalog program document 001001 --keyword 数学
catalog classroom available --date 2026-10-19 --from 14:00 --to 16:00 --min-seats 30
catalog classroom available --semester 461 --weekday 1,3 --week 1-8单周 \
  --first-monday 2026-08-31 --from 14:00 --to 16:00

周期空闲需要明确第一教学周周一；与单日、日期范围模式互斥，单次最多 62 个目标日期，所有目标日期都满足才返回。连续日期范围模式仍最多 31 天。教室只分为“已占用”“按公开记录推断空闲”“无法判断”，不代表可预约；无法定位或时间异常的记录会降低可信度。

某个目标日期请求失败时，多日空闲结果不会宣称任何教室“每天空闲”；周摘要仍保留成功日期，并显示无法判断的日期及数量。

关联查询保留成功部分并列出缺失原因，要求完整结果时加 --strict。考试、替代课程等公开数据可能次日更新，抓取时间不等于业务数据更新时间。

本地候选方案与日程

program 始终表示官方培养方案；plan 是用户自建的候选教学班组合，不是实际选课记录或毕业审核。

catalog plan create 秋季候选 --semester 461
catalog plan list
# 使用 create/list 返回的 ID
catalog plan add MATH1001.01 PHYS1001.01 --plan <ID>
catalog plan show --plan <ID>
catalog plan calendar --plan <ID> --first-monday 2026-08-31 --layout 1
catalog agenda --plan <ID> --week-of 2026-10-19
catalog exam for-lessons --plan <ID>
catalog plan refresh --plan <ID>          # 仅预览
catalog plan refresh --plan <ID> --apply  # 明确应用唯一匹配；不自动删除缺失记录

也可用 --semester 选择该学期活动方案。方案支持 use/rename/delete/remove/compare，显示去重学分、未知学分、重复课程、已知冲突及无法检查项。

自动排课默认仅预览，每门课程恰好选择一个教学班：

catalog plan generate MATH1001 PHYS1001 --semester 461 \
  --fixed MATH1001.01 --exclude "1(3,4)@1-16" --max-results 20
# 明确保存第 1 个结果；MCP 不开放保存
catalog plan generate MATH1001 PHYS1001 --semester 461 --save 备选 --select 1

最多 20 门课程，默认 20 个结果、最多 100 个结果，搜索节点上限 100000。按课程号和课堂号稳定枚举，无偏好评分。未知安排不会进入可行结果；达到上限不表示无解，也不保证名额或考试安排完整。

课程收藏支持分组和备注，教室收藏使用目录 ID：

catalog favorite group create 专业课
catalog favorite course add MATH1001 --note 下学期考虑
catalog favorite course list
catalog favorite room add <目录ID>
catalog favorite room list

工作区与备份

工作区独立于可清理缓存。Linux 默认 ~/.local/share/catalog-cli/workspace.sqlite，遵循 XDG_DATA_HOME；macOS 在 ~/Library/Application Support/catalog-cli/，Windows 在 %APPDATA%/catalog-cli/。可用 --workspace <文件> 或 CATALOG_WORKSPACE_PATH 覆盖。

catalog workspace inspect
catalog workspace inspect backup.json
catalog workspace import backup.json --dry-run
catalog workspace import backup.json
catalog workspace export --output backup.json
catalog workspace export --plan <ID> --output one-plan.json
# 整体替换必须明确确认
catalog workspace import backup.json --replace --yes

支持 Next v1 升级与 v2 双向交换。默认合并：导入方案获得新 ID、重名加后缀，按名称合并分组，保留已有备注和活动方案。完整验证后事务提交，并检查 revision。文件最大 5 MiB；每学期 20 个方案、每方案 100 个教学班、1000 门课程收藏、20 个分组、100 个教室收藏。

导出不覆盖现有文件。单方案导出不附带其他方案、课程收藏、分组、备注和教室收藏。备份包含个人数据，请自行保管。

应用更新时，缺失或歧义记录的旧快照及检查标记会保留。CLI 扩展字段可在 CLI 内往返，其他 v2 客户端可能忽略这些扩展。修改/文件写出命令不支持 --columns 或非零 --offset，以免操作完成后才因输出参数报错；可随后用只读命令筛选结果。

输出和日历

catalog --columns 课堂号,课程名,授课教师 lesson list --semester 461
catalog --json lesson list --semester 461 --limit 50 --offset 0
catalog --csv lesson list --semester 461 > lessons.csv
catalog --ics lesson list --semester 461 --course 数学 \
  --first-monday 2026-08-31 --layout 1 > lessons.ics
catalog --ics plan show --plan <ID> > plan.ics

表格默认分页，--all 查看全部，--wide 保留长文本。--columns 接受对应输出的中文列名。CSV 使用中文列名和 UTF-8 BOM；stdout 仅包含 CSV，警告到 stderr。ICS 同样不混入普通提示。

教学班日历必须明确第一周周一，绝不直接采用学期开始日期。未选择课节表时生成标注性质的全天提醒；--layout 1|2 表示用户确认相应课节表，不能替代学校正式时间通知。非连续节次拆分，未知周次不扩展，缺少课节时间不猜测，跳过原因写入 stderr。

JSON 保持 meta/data，契约升级为 meta.schemaVersion: 2：增加完整性、问题列表、依赖来源、最早/最晚抓取时间和列表分页统计。考试 courseCode 现在是真实课程号，lessonCode 才是课堂号；详情以学期列表为准。旧脚本迁移说明见 使用指南。

来源、缓存与离线

catalog --source official semester list
catalog --source mirror semester list
catalog --source https://example.org/api/ semester list
catalog --offline lesson list --semester 461
catalog --no-cache lesson list --semester 461
catalog cache prefetch --semester 461 --date 2026-10-19
catalog cache inspect
catalog cache inspect --all-sources
catalog cache prune --older-than 30d --yes
catalog cache compact
catalog cache clear --yes
catalog cache clear --all-sources --yes

默认请求官方最新数据；--source 优先于保留的 CATALOG_BASE_URL（后者仍表示站点根地址）。镜像为显式选择，不自动跨来源切换。缓存按 API 根地址、资源、范围和契约版本隔离。

连接失败、超时、429 和暂时性 5xx 有上限重试并可回退缓存；认证失败、404、无效 JSON、契约错误不回退。--offline 只读缓存；--no-cache 不读取或回退旧缓存，但新数据仍尝试写入。两者互斥。缓存写入失败不影响成功的网络结果，但会提示未持久化；工作区写入失败则报错。

缓存数据库默认位于用户缓存目录的 catalog-cli/catalog.sqlite，可用 --cache-dir 或 CATALOG_CACHE_DIR 覆盖。默认上限 128 MiB 压缩快照、1000 条，按最近使用淘汰；CATALOG_CACHE_MAX_BYTES、CATALOG_CACHE_MAX_ENTRIES 可调整。清理默认仅当前来源；跨来源必须 --all-sources。

升级时旧缓存事务迁移为来源不明的 legacy，不猜测归属或混用。请重新预取需要的数据，cache inspect --all-sources 可查看保留的旧快照。清缓存不清工作区。

MCP、补全和预设

{
  "mcpServers": {
    "ustc-catalog": {
      "command": "catalog-mcp",
      "env": {
        "CATALOG_WORKSPACE_PATH": "/path/to/workspace.sqlite"
      }
    }
  }
}

当前源码提供 50 个只读工具，包含公开查询、方案查看/比较/更新预览、日程、排课预览及收藏列表。不暴露导入、导出到文件、收藏修改、方案保存、应用更新、删除或教务操作。返回统一 JSON，不输出表格。默认 50 条，单页最多 200 条。

固定 CLI 子进程使用 shell:false；最多并发 3 个、排队 32 个，stdout 限制 8 MiB、stderr 256 KiB、完整 MCP 回复 2 MiB。超时或取消先终止进程，2 秒后强制结束，退出前保留并发名额。不要向不信任的 MCP 客户端开放本地私人工作区。

catalog completion show zsh
catalog completion show bash
catalog preset save 数学课 -- lesson list --course 数学
catalog --source mirror --json preset run 数学课
catalog doctor --offline

动态补全只读取现有本地缓存与目录，不联网。预设只允许登记的只读命令，拒绝下载、文件导出和工作区修改；来源、工作区路径与输出方式由运行预设时决定。

开发与验收

npm run check
npm run test:coverage
npm run mcp:smoke
npm run package:smoke
npm pack --dry-run
# 独立线上检查，可分别指定 official / mirror
npm run api:check -- --source official

教室目录维护使用 npm run directory:check -- --capture capture.json，默认校验和输出差异，不写入；同步须显式加 --write，删除还需 --allow-remove。快照格式及安全边界见使用指南。在线接口检查独立于本地测试，不依赖生产站点可达性。

线上检查默认每次请求超时 4 秒，可通过 CATALOG_TIMEOUT_MS 调整；不写缓存，也不自动切换来源。2026-10-19 的分来源检查记录见使用指南第 28 节。

本项目不实现登录、认证绕过、选课、退课或预约，不修改教务数据。公开查询与本地候选方案不构成正式教务结论。

完整参数、输出契约、错误码和互通细节见 使用指南。本项目采用 MIT License。