Imported from xhh678876/openclaw-sjtu (SKILL.md). Install upstream with npx skills add xhh678876/openclaw-sjtu. Copyright stays with the author (MIT).

上海交通大学全能校园助手 (sjtu)

平台无关。 本 skill 是 scripts/ 下的一组独立 CLI 脚本（Python3 / Node.js）。任何能运行 shell 命令、读文件的 agent 都能调用——不依赖任何特定网关、浏览器代理或私有运行时。 凭证集中在仓库根 config.json（已被 .gitignore 忽略，不会进版本库）。

一、给 Agent 的调用约定（必读）

1. 执行前先 cd ~/openclaw-sjtu。脚本按仓库根定位 config.json / templates/ / fonts/， 不在此目录会找不到配置或资源。
2. 调用形式：Python 脚本用 python3 scripts/<名>.py <子命令> [参数]； .mjs 脚本用 node scripts/<名>.mjs <子命令>（水源用 node，不是 python3）。 不带参数一般打印用法。
3. 凭证：统一放仓库根 config.json（从 config.example.json 复制）。按需填——只填要用的 功能对应字段即可。部分脚本也支持等价环境变量（见 §2）。
4. 写操作必须先确认：会改服务器/外部状态的命令（发邮件、传承下载消耗积分等），执行前必须向 用户复述对象并取得确认。本文档用 ⚠️ 标出。注：Canvas 提交作业当前未暴露为 CLI 子命令 （仅库函数 submit_assignment），不会被误触发。
5. 缺凭证 = 明确报错：脚本不会假装成功。缺 key/token 会打印「缺什么、怎么配」，多数带 selftest。
6. 状态语义：✅实时=真实抓线上数据；📌静态=内置离线数据（稳定但非实时，跨学期可能过期）； 🔑需登录=缺凭证会明确报错；⚙️本地=纯本地生成；⚠️注意=有依赖缺失或接口变更，见说明。
7. 环境提示：macOS 无 timeout 命令，文档示例都不用 timeout，脚本自带超时，直接运行即可。

二、配置 (config.json)

从 config.example.json 复制为 config.json，按需填写：

等价环境变量（优先级高于 config.json）：JCOURSE_API_KEY、DYWEB_TOKEN、OPENCLAW_SJTU_CANVAS_PROFILE。

🔒 config.json 已在 .gitignore，含真实凭证，切勿 git add。只提交 config.example.json（占位符）。

三、功能 × 入口 × 认证 × 状态 总表

四、功能详解

每条都标注了真实子命令（已逐行核对源码 + 实跑）。脚本帮助里写 python3 sjtu_xxx.py，从仓库根 调用时实际路径是 scripts/sjtu_xxx.py。

4.1 Canvas 课程 / DDL / 成绩 ✅ — canvas_api.py

需 canvas_token。CLI 仅 5 个只读子命令，全局 --profile <name> 可放命令前后任意位置切换 学生/教师身份（缺省用 canvas_default_profile）。无参数时默认执行 courses。

python3 scripts/canvas_api.py me                       # 验证 token + 显示当前身份(学生/教师)
python3 scripts/canvas_api.py courses                  # 列出所有课程: [课程ID] 课程名 [角色]
python3 scripts/canvas_api.py ddls                     # 未来未提交作业, 按截止排序(🔴<24h/🟡<72h/🟢)
python3 scripts/canvas_api.py ddls-all                 # 本学期DDL全景: 统计+待交+老师反馈
python3 scripts/canvas_api.py grades                   # 各课已评分作业的得分
python3 scripts/canvas_api.py --profile teacher courses # 教师端: 管理课程/全班提交/成绩册

• 课程 ID 从 courses 输出取，用于其它需要 course_id 的脚本。
• DDL 走 Canvas Planner API 一次性拉取（含 submitted/graded/late/missing/feedback）；时区固定 UTC+8。
• ⚠️ 课件下载、作业提交、讨论区、日历事件等是库函数，未做成 CLI 子命令；提交作业需另调 canvas_api.submit_assignment(...) 并确认，普通调用不会触发写操作。
• ddls-all 的学期起始日在源码里硬编码（2026-02-17），跨学期需改源码。
• 依赖 requests；需能访问 oc.sjtu.edu.cn（校园网或可达网络）。

4.2 自动作业流水线 ✅ — auto_homework.py

需 canvas_token。5 个子命令（无参默认 scan）：

python3 scripts/auto_homework.py scan                  # 扫所有未提交作业, 按剩余时间升序(只读)
python3 scripts/auto_homework.py urgent 24             # 只看 N 小时内截止(默认48)(只读)
python3 scripts/auto_homework.py context <course_id> <assignment_id>  # 拉题面+下载图片/课件, 生成 ai_prompt.md
python3 scripts/auto_homework.py full <course_id> <assignment_id>     # 同 context + 提示后续提交步骤
python3 scripts/auto_homework.py watch                 # 对比上次状态, 报新增作业(写 .homework_state.json, 适配 cron)

• context/full 会向 ~/Downloads/Canvas作业上下文/ 与 ~/Downloads/Canvas课件/ 下载文件； 生成的 ai_prompt.md 可喂 LLM 辅助作答。本身不提交作业。
• context/full 提取课件正文需 python-pptx / pdfplumber / python-docx（缺失则该文件标注「需安装」，不崩）。

4.3 DDL → 日历 ✅ / ⚙️ — sjtu_timetable_ics.py + calendar_sync.py

需 canvas_token。sjtu_timetable_ics.py 3 个子命令，可选第二参为输出路径：

python3 scripts/sjtu_timetable_ics.py ddls [输出.ics]     # 未来DDL→ICS, 每个含截止前1h/24h两个提醒(默认 ~/Downloads/sjtu_ddls.ics)
python3 scripts/sjtu_timetable_ics.py calendar [输出.ics] # 课程日历事件→ICS(默认 ~/Downloads/sjtu_calendar.ics)
python3 scripts/sjtu_timetable_ics.py all [输出.ics]      # DDL+日历合并(默认 ~/Downloads/sjtu_timetable.ics)
python3 scripts/calendar_sync.py                         # ⚙️ 仅macOS: 直接同步未来DDL进"日历"app的"Canvas作业"日历

• ICS 双击即可导入 Apple/Google 日历。calendar / all 的学期区间硬编码 2026-02-17→2026-07-15。
• calendar_sync.py 无参数、无 flag，运行即写本机日历（按事件标题去重）；首次需在 macOS 「系统设置→隐私与安全性→自动化」授予终端/Python 控制「日历」权限。

4.4 课程评价 / 老师对比（选课社区 jCourse）✅ — sjtu_course_review.py

走 jCourse 开放 API（Bearer key），无需 cookie / 浏览器。需 jcourse_api_key。

python3 scripts/sjtu_course_review.py search 传热学      # 搜课(名称/课号/老师)
python3 scripts/sjtu_course_review.py detail 6807       # 课程详情 + 同课号其他老师评分对比
python3 scripts/sjtu_course_review.py reviews 6807 5    # 看某门课的评价(前5条)
python3 scripts/sjtu_course_review.py compare 传热学     # 同名课不同老师评分横向对比
python3 scripts/sjtu_course_review.py selftest         # 自检 API Key 与连通性

搜索结果与详情里的 #数字 是课程 ID，传给 detail / reviews。

4.5 传承交大 往年资料 / 试卷 🔑 — sjtu_legacy.py

传承新站（beta.share.dyweb.sjtu.cn）强制 jAccount 登录，无免登录接口。先拿 token：

# 方式A(推荐): 浏览器登一次自动抓 token
python3 scripts/save_sjtu_cookies.py legacy
# 方式B: config.json 填 dyweb_token (F12 → Application → Local Storage 的 token)
# 方式C: export DYWEB_TOKEN=...

拿到 token 后：

python3 scripts/sjtu_legacy.py search 传热学      # 搜课程
python3 scripts/sjtu_legacy.py course <课程ID>    # 课程详情
python3 scripts/sjtu_legacy.py materials <课程ID> # 某课程的资料列表
python3 scripts/sjtu_legacy.py selftest          # 检查 token 与连通性

⚠️ 下载资料会消耗站内积分，本工具只列清单不自动下载。

4.6 交大邮箱 🔑 — sjtu_mail.py

需 sjtu_username / sjtu_password（IMAP 993 / SMTP 465，走 mail.sjtu.edu.cn，需校园网/VPN）。 凭证也可用 -u/-p 临时传（优先于 config.json）。

python3 scripts/sjtu_mail.py unread --limit 10            # 未读邮件(不标记已读)
python3 scripts/sjtu_mail.py search --keyword 作业        # 按主题+发件人搜(可缩写 -k)
python3 scripts/sjtu_mail.py summary                      # 邮箱概况(总数/未读/最近5封)
python3 scripts/sjtu_mail.py send --to x@sjtu.edu.cn --subject "标题" --body "正文" [--html]  # ⚠️ 发信

⚠️ send 会真发邮件（From=登录账号），执行前必须向用户确认收件人/主题/正文。

4.7 水源社区（只读）✅ — shuiyuan_discourse.mjs（用 node）

需 shuiyuan_user_api_key（首次走链接授权）。Node.js ≥18，严格只读（代码层只允许 GET + 路径白名单， 不能发帖/回复/点赞）。访问 shuiyuan.sjtu.edu.cn 通常需校园网/VPN。

# 首次授权(链接授权)
node scripts/shuiyuan_discourse.mjs auth init                       # 生成授权链接
node scripts/shuiyuan_discourse.mjs auth finish --payload "<payload>"  # 浏览器授权后粘回 payload
node scripts/shuiyuan_discourse.mjs auth status                     # 查看凭证状态
# 日常只读
node scripts/shuiyuan_discourse.mjs search "选课" --max-results 10  # 全文搜索(支持 #分类 @用户 order:likes topic:<id> 等算子)
node scripts/shuiyuan_discourse.mjs latest --max-results 30        # 最新话题
node scripts/shuiyuan_discourse.mjs categories                     # 全部版块(id/名称/帖数)
node scripts/shuiyuan_discourse.mjs topic <topic_id> --post-limit 5  # 看某话题及楼层正文
node scripts/shuiyuan_discourse.mjs post <post_id>                # 看单楼正文
node scripts/shuiyuan_discourse.mjs filter "category:xx tags:yy"  # Discourse 过滤式
node scripts/shuiyuan_discourse.mjs image <图片URL> --output meta # 安全取帖内图片(meta/data-url/media-path)
node scripts/shuiyuan_discourse.mjs vision-check                  # 检查模型是否支持图片输入

• 凭证存 ~/.openclaw/skills-data/shuiyuan-discourse/auth.json（0600）。
• 限流（429）会被规整为 rate_limited:true 并给重试间隔，等几十秒重试同一命令即可。
• 全局选项：--site / --runtime auto|node|curl / --timeout / --auth-file 等。

五、信息查询与校园生活

教务通知 / 交大新闻 ✅（实时）— sjtu_news.py

python3 scripts/sjtu_news.py jwc 10              # 教务处通知(标题/日期/摘要/链接)
python3 scripts/sjtu_news.py news 10            # 交大要闻
python3 scripts/sjtu_news.py news 5 --column mtjj # 媒体聚焦(jdyw=要闻 / mtjj=媒体聚焦)
python3 scripts/sjtu_news.py news 5 --json      # 结构化 JSON, 便于 agent 解析
python3 scripts/sjtu_news.py all 10             # 新闻+教务一起抓

正版软件 ✅（实时）— sjtu_software.py

python3 scripts/sjtu_software.py list                 # 列校内正版软件(系统/办公/科学计算/网络安全)
python3 scripts/sjtu_software.py list --category 办公  # 按类别筛选(仅 list)
python3 scripts/sjtu_software.py list --json          # JSON 输出
python3 scripts/sjtu_software.py search MATLAB        # 关键词搜

抓 software.sjtu.edu.cn；断网/解析失败会静默回退到内置 13 条数据（可能过时）。

生存手册 ✅（实时，GitBook）— sjtu_survive.py

python3 scripts/sjtu_survive.py toc              # 全书目录(来自 sitemap, 约110页)
python3 scripts/sjtu_survive.py toc gpa          # 目录按关键词过滤
python3 scripts/sjtu_survive.py search bao-yan   # 搜章节
python3 scripts/sjtu_survive.py read bao-yan     # 读章节正文

GitBook 章节 slug 为拼音，搜索用拼音片段（gpa / bao-yan / zhuan-zhuan-ye）比中文更准。

视觉交大 官方图库 ✅（实时）— sjtu_visual.py

python3 scripts/sjtu_visual.py themes            # 主题相册(南洋筑韵/SJTU SCENE/航拍/运动交大…)
python3 scripts/sjtu_visual.py images 42 6       # 某主题前6张(含原图直链/尺寸/下载数)
python3 scripts/sjtu_visual.py search 图书馆      # 全站搜图
python3 scripts/sjtu_visual.py download <图片直链> [输出路径]  # 下载高清原图(常数MB)

课件文本提取 ✅（本地）— file_extractor.py

python3 scripts/file_extractor.py <文件>          # 单文件提取文本到 stdout(前2000字, 支持 pptx/ppt/pdf/docx/txt/md)
python3 scripts/file_extractor.py <目录>          # 批量提取目录内 pptx/pdf/docx, 打印字符数
python3 scripts/file_extractor.py <目录> <输出目录> # 批量转 Markdown 落盘(每文件一个 .md)

位置参数 CLI，无子命令。PPTX/PDF 提取需 pip install python-pptx pdfplumber。配合 Canvas 课件做 AI 总结。

教学周 / 校历 / 巴士 / 食堂 / 图书馆 / 空教室 / 在线工具 📌（静态）

python3 scripts/sjtu_info.py week                # 今天第几教学周 + 近期事件
python3 scripts/sjtu_info.py calendar            # 学期校历
python3 scripts/sjtu_info.py bus                 # 校园巴士时刻(按工作日/周末自动切换)
python3 scripts/sjtu_canteen.py list             # 列闵行 7 个食堂
python3 scripts/sjtu_canteen.py menu 二餐         # 某食堂菜单(简称: 一餐/二餐/三餐/四餐/五餐/哈乐/玉兰苑)
python3 scripts/sjtu_canteen.py recommend        # 按当前时段推荐
python3 scripts/sjtu_library.py info             # 5 个馆开放时间/位置/座位数
python3 scripts/sjtu_library.py seats            # 座位预约系统指引(非实时余量)
python3 scripts/sjtu_classroom.py empty          # 全部教学楼教室清单(77间)
python3 scripts/sjtu_classroom.py empty --building 东上院  # 按楼筛选
python3 scripts/sjtu_classroom.py info           # 教学楼概览; info --building 东上院 看单楼详情+课程时间表
python3 scripts/sjtu_tools.py list               # 12 项校内在线工具目录
python3 scripts/sjtu_tools.py latex              # 某工具详情+可达性(latex/notes/ocr/tts/ai/feedback)

📌 这几项为内置离线数据（学校无公开实时 API），每学期手工维护，跨学期可能过期。座位实时余量 / 真实空闲教室需 jAccount 登录教务系统，当前未实现。sjtu_tools 的详情命令会对 URL 做可达性探测 （校外多显示「无法连接」属正常）。

六、生成工具 ⚙️

交大 PPT — generate_ppt.py（需 pip install python-pptx）

python3 scripts/generate_ppt.py --list-templates                  # 列 templates/ 下 9 个交大官方模板
python3 scripts/generate_ppt.py --title "标题" --markdown notes.md \
  --template "百廿红" --output out.pptx                            # 从 Markdown 生成多页 PPT
python3 scripts/generate_ppt.py --title "标题" --no-polish         # 关闭默认文字美化

• 单命令多 flag（无子命令）。--markdown 可传文件路径或内联文本；##→内容页、#→章节过渡页。
• --template 传模板名子串即可（如「百廿红」匹配 1.百廿红-李一.pptx）；缺省用交大通用模板。
• ⚠️ 未装 python-pptx 时脚本在导入阶段就退出（连 --list-templates 也跑不了），先装依赖。

手写 PDF — handwrite_pdf.py ⚠️（需 pip install handright）

python3 scripts/handwrite_pdf.py input.txt output.pdf --style casual   # 文件→手写PDF
python3 scripts/handwrite_pdf.py --text "要写的内容" out.pdf --ruled    # 直传文本, 带信纸横线
# 风格: neat(工整) / casual(随意,默认) / messy(潦草)

⚠️ 当前 handright 依赖未安装，运行会 ModuleNotFoundError；先 pip install handright （Pillow 已装）。字体已就绪（仓库 fonts/ 及 workspace 下均有手写体）。

镜像换源指引 — sjtu_mirror.py

python3 scripts/sjtu_mirror.py pip               # pip 换源命令(临时/永久/配置文件)
python3 scripts/sjtu_mirror.py conda             # conda ~/.condarc
python3 scripts/sjtu_mirror.py brew              # Homebrew 环境变量
python3 scripts/sjtu_mirror.py docker            # Docker daemon.json
python3 scripts/sjtu_mirror.py npm               # npm registry
python3 scripts/sjtu_mirror.py list              # ⚠️ 列镜像(后端接口已变, 可能回退内置静态列表)

pip/conda/brew/docker/npm 只打印换源指引文本，不修改任何配置文件，需用户自己执行。 ⚠️ 仅 list 联网，其后端 API 已变更，结果可能不准。

七、子 Skill（独立模块，各有 SKILL.md）

主 /sjtu 覆盖日常功能；下列是独立成 skill 的进阶模块，多需 jAccount 登录或较重，按需委派：

委派对照（用户提到这些词时优先用对应子 skill）：

• “我有什么 DDL / 作业 / 实验”（跨平台聚合）→ sjtu-deadlines
• “登录所有 SJTU 平台 / 刷新所有 cookies” → sjtu-oneshot
• “爬交大网站 / 抓教务通知 / 蒸馏公告” → sjtu-crawler
• “刷新传承 / 第三方站 cookie / token” → sjtu-cookie-saver
• “填 SJTU Date 问卷 / 查匹配 / 脱单” → sjtu-date

其他辅助脚本（不单独成 skill）：

• grading_assistant.py — 助教批改助手（批量拉学生提交 + 生成评分上下文，需 Canvas 教师端 token）
• sjtu_distill.py — 用 Claude 把 crawler 爬下的文档蒸馏成结构化摘要

共享工具层：scripts/auth/（jAccount SSO + cookie store）、scripts/platforms/（各平台适配器）、 scripts/scheduler/（macOS launchd 服务）。

八、依赖安装

# 主功能
pip3 install requests beautifulsoup4 python-pptx pdfplumber python-docx handright Pillow reportlab
# 子 skill 额外
pip3 install -r scripts/requirements-platforms.txt    # sjtu-deadlines / sjtu-oneshot
playwright install chromium                            # sjtu-oneshot / cookie-saver(浏览器登录)
pip3 install fastapi uvicorn                           # shuiyuan-rag-service

• 水源、SJTU Date 等 .mjs 脚本需 Node.js ≥18（用内置 fetch，无需 npm 包）。
• 仓库自带 .venv，建议用它的 python 运行需第三方库的脚本（PPT/手写PDF/课件提取）。

九、故障排查

十、注意事项

1. 写操作（发邮件 / 传承下载消耗积分）执行前必须向用户确认。Canvas 提交作业未做成 CLI，需显式调库函数。
2. 凭证失效：Canvas token、jCourse key、传承 token 失效时按 §9 重新生成。
3. 📌 静态数据项（食堂 / 校历 / 巴士 / 教室 / 教学周 / 在线工具）为内置离线数据，跨学期可能过期。
4. 校园网：邮箱、水源、部分子 skill（phycai/lcme）需校园网或 VPN。
5. config.json 含真实凭证，已被 git 忽略，切勿提交；只提交 config.example.json（占位符）。
6. ⚠️ 已知待修：sjtu_mirror.py list 后端接口已变更；handwrite_pdf.py 需先装 handright。