English | 简体中文

westlake_survival

把西湖大学散落在数十个系统里的校园服务，收拢成一条命令、一次调用、一个页面。

Python 库 · CLI · MCP 服务器 · 本地 WebUI —— 一套能力，四个入口，人与 AI 代理皆宜。

西湖大学的校园服务散落在 SIS、教学系统 AMS、Canvas、预约中心、门户、图书馆、体育场馆……各自为政的几十个系统里。westlake_survival 在 API 层面把它们逐一接通，收敛为一个工具包：

• CLI：westlake 一条命令覆盖查询与少量写操作；不确定归哪条，westlake find <口语关键词> 直接问（「论文」「借书」「放假」都能命中）。
• 本地 WebUI：裸跑 westlake（或双击启动脚本）自动打开浏览器进仪表盘——30+ 页面，含账号配置；/capabilities 一页列出全部能力。
• MCP 服务器：westlake-mcp 一个进程，接给任何支持 MCP 的 AI 客户端。
• Python 库：import westlake_survival 拿结构化数据，examples/ 有可直接跑的样例。

三条底线，先说清楚：

1. 默认只读。写操作仅五条——交作业、讨论回帖、回私信、预约场地、取消预约——且都必须凭使用者当轮明确指令执行；不做选课、抢课，不绕过权限。
2. 凭据只存本机。钥匙串优先、只存一份、不打印不提交、不跨机器同步；账号由本人在网页「设置」页填写，终端不问密码。见凭据与隐私。
3. 无官方背书。社区工具，结构参考 sustech_survival，与西湖大学官方无关。

功能总览

体育场馆与图书馆座位是独立系统，与预约中心的对照见 docs/module_audit_2026-10-27.md；办事门户 affairs portal 服务端接口近期疑似变化、暂报错。个人档案类（学籍/住宿/荣誉/志愿/资助/社团）还有 20+ 条只读命令，westlake find 一查便知。

快速开始

最省事：双击仓库根目录的 start.bat（Windows）/ start.command（macOS），或终端 ./start.sh（Linux）。首次运行自动装依赖，随后浏览器自动打开——没配过账号直达「设置」页，本人填一次学号与统一密码，验证通过自动进仪表盘；之后每次启动直达仪表盘。同一端口已有服务在跑时不重复启动，直接把浏览器指过去。

终端（已发布 PyPI，无需 clone 仓库）：

pip install westlake-survival   # PyPI 直装；开发装法：clone 后 pip install -e .，锁验证过的版本用 requirements.txt
westlake                      # 起网页并开浏览器；脚本/自动化设 WESTLAKE_NO_WEBUI=1 关闭弹出
westlake calendar today       # 校历等公开功能无需账号
westlake --help

启动行为与首次配置的完整契约见 docs/first_run.md。环境不对（装了却用不了、缺依赖、命令和解释器不同环境）先跑 westlake doctor：逐项体检解释器/依赖/账号/网络，缺什么给一条能直接抄的修复命令（docs/doctor.md）。

配合 AI 代理使用（任何代理通用）

本仓库为代理而设计。三种接法按需选、可叠加：

1. 读 AGENTS.md 的代理（ZCode、DSH、Codex、Claude Code、Cursor……）：clone 即用——根目录 AGENTS.md 已写明纪律、入口与验证方式，代理开会话自动读到；配好账号后直接差遣 westlake CLI。
2. 带技能（Skill）机制的代理：技能文档在 skills/westlake-survival/SKILL.md，拷进你的代理的技能根即可被发现：

   git clone https://github.com/yizhang-dream/westlake_survival.git
   cp -r westlake_survival/skills/westlake-survival ~/.zcode/skills/    # ZCode；其他代理用 ~/.agents/skills/、~/.claude/skills/ 等
   

3. MCP 客户端：装包后注册 westlake-mcp 进程；配置片段与全套 MCP 工具清单见 docs/skill_reference.md。

代理接手第一步永远是 westlake doctor（--json 便于程序判断）：全绿再干活；账号不由代理填，请使用者在网页「设置」页本人填写。

凭据与隐私

• 一个统一密码通吃：SIS、Canvas、AMS、预约、体育、打印、门户都走西湖统一身份认证；Canvas 另兼容个人令牌，网页可存可清。
• 只存一份、只存本机：钥匙串（Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service）优先；写文件即自动清钥匙串，反之亦然（docs/credential_single_store.md）。不跨机器、不跨系统用户同步。
• 密码只在网页表单里敲：终端默认不问密码（SSH 等无图形环境才 westlake setup --terminal）；做隔离测试设 WESTLAKE_HOME 或 WESTLAKE_NO_KEYRING，任一成立即沙箱。
• 默认直连：全部会话 trust_env=False，无视 HTTP_PROXY/HTTPS_PROXY——校园站点经系统代理常 502/超时；外部脚本复用请走 westlake_survival.discovery.direct_session()。
• 校外访问教务/Canvas 需校园网或 VPN：westlake vpn status 查状态。

验证（端到端）

本仓库不维护单元测试，功能验证一律端到端真跑：

python tools/module_smoke.py   # 全部只读 CLI 逐条真跑，出 OK/EMPTY/AUTH/FAIL 体检表
python tools/webui_smoke.py    # 进程内起真实 Flask 服务，逐页 GET 断言 200
python tools/pii_scan.py       # 提交前扫真实学号等个人信息

文档

许可与致谢

• 许可：PolyForm Noncommercial 1.0.0，仅限非商业用途并保留署名。
• 致谢：结构参考 sustech_survival；社团简介改写自学生自建百科 WikiLake 并逐条附原文链接（docs/clubwiki.md）。
• 本项目为社区工具，无西湖大学官方背书；仅访问使用者本人有权的数据。