Metadata-Version: 2.5
Name: westlake_survival
Version: 2026.10.29
Summary: API-level access to Westlake University services — 在 API 层面调用西湖大学各服务系统
Project-URL: Homepage, https://github.com/yizhang-dream/westlake_survival
Project-URL: Reference, https://github.com/dumixthestpd/sustech_survival
Author: westlake_survival contributors
License: PolyForm Noncommercial License 1.0.0
        
        https://polyformproject.org/licenses/noncommercial/1.0.0
        
        Required Notice: westlake_survival contributors (community project, not affiliated with Westlake University)
        
        Acceptance
        In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
        Copyright License
        The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to
        Distribution License
        and make changes or new works based on the software according to
        Changes and New Works License
        .
        Distribution License
        The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by
        Changes and New Works License
        .
        Notices
        You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with
        Required Notice:
        that the licensor provided with the software. For example:
        Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
        Changes and New Works License
        The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
        Patent License
        The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
        Noncommercial Purposes
        Any noncommercial purpose is a permitted purpose.
        Personal Uses
        Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
        Noncommercial Organizations
        Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
        Fair Use
        You may have "fair use" rights for the software under the law. These terms do not limit them.
        No Other Rights
        These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
        Patent Defense
        If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
        Violations
        The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
        No Liability
        As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
        Definitions
        The
        licensor
        is the individual or entity offering these terms, and the
        software
        is the software the licensor makes available under these terms.
        You
        refers to the individual or entity agreeing to these terms.
        Your company
        is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.
        Control
        means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
        Your licenses
        are all the licenses granted to you for the software under these terms.
        Use
        means anything you do with the software requiring one of your licenses.
        © PolyForm Project Inc.
License-File: LICENSE
Keywords: canvas,library,sis,university,westlake,westlake-survival
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=42
Requires-Dist: flask>=3.0
Requires-Dist: keyring>=25
Requires-Dist: python-dateutil>=2.8
Requires-Dist: requests>=2.28
Requires-Dist: tzdata>=2024.1
Requires-Dist: urllib3>=1.26
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: crypto
Requires-Dist: cryptography>=42; extra == 'crypto'
Provides-Extra: secure
Requires-Dist: keyring>=25; extra == 'secure'
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == 'test'
Provides-Extra: webui
Requires-Dist: flask>=3.0; extra == 'webui'
Description-Content-Type: text/markdown

[English](README_en.md) | 简体中文

# westlake_survival

> 把西湖大学散落在数十个系统里的校园服务，收拢成**一条命令、一次调用、一个页面**。
>
> Python 库 · CLI · MCP 服务器 · 本地 WebUI —— 一套能力，四个入口，人与 AI 代理皆宜。

![PyPI](https://img.shields.io/pypi/v/westlake-survival)
![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-58839b)
![MCP](https://img.shields.io/badge/MCP-server-8957e5)
![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-dd4a4a)

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

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

三条底线，先说清楚：

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

## 功能总览

| 领域 | 覆盖 | 需账号 |
| --- | --- | --- |
| 学业（SIS） | 课表、成绩、考试安排、选课车、评教、第二课堂成绩单、学籍异动、学业导师、课表 ICS | 统一密码 |
| 教学（AMS） | 另一套课表、教学周次、学籍与选课入口 | 统一密码 |
| Canvas | 课程、截止与测验、待办、模块、课程文件下载、讨论区、公告、收件箱、作业详情（题目附件＋评分细则）；交作业、回帖、回私信 | 令牌或统一密码 |
| 场地预约 | 17 类场地（自习室/研讨室/琴房/活动用房…）：分类、逐日可约、逐格空闲、我的预约、预约与取消 | 统一密码 |
| 体育场馆 | 场景、场地、逐日可约、我的预约（只读） | 统一密码 |
| 任务与门户 | 办事大厅目录、我的待办/进行中/抄送、门户个人卡片（未读邮件/在借/待办计数） | 统一密码 |
| 学术科研 | 订阅数据库注册表、CARSI 校外 SSO（`scholar ensure` 一条命令）、DOI→PDF 全文下载、科研进展、导师名录、HPC 集群、报销与经费制度 | 部分免账号 |
| 就业 | 招聘岗位、招聘会、宣讲会：最新＋深列表＋详情 | 免账号 |
| 培养方案 | 专业学分要求与课程表、课程体系、通识课目录、课程搜索 | 免账号 |
| 校园生活 | 校历周次与假期、班车时刻与 ICS、每日晨报快照（`context`/`digest`）、食堂咖啡、公寓、校区地图与 720° 全景、打印网点 | 免账号 |
| 讲义下载 | OneDrive/SharePoint 分享讲义免账号直读与下载（需 `[browser]` 可选增强） | 免账号 |
| 信息检索 | 官网全站搜索、新闻、讲座活动、学院动态、学生百科 WikiLake | 免账号 |
| 系统盘点 | 90+ 项服务注册表、子站在线普查、站点栏目、服务可达性、VPN 状态与隧道路由 | 免账号 |
| 图书馆 | 系统于 2026-10-28 迁移至「阿法迪云 eLibrary」，借阅查询暂不可用（[迁移说明](docs/library_migration_2026-10-28.md)） | — |

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

## 快速开始

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

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

```bash
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](docs/first_run.md)。环境不对（装了却用不了、缺依赖、命令和解释器不同环境）先跑 `westlake doctor`：逐项体检解释器/依赖/账号/网络，缺什么给一条能直接抄的修复命令（[docs/doctor.md](docs/doctor.md)）。

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

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

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

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

## 凭据与隐私

- **一个统一密码通吃**：SIS、Canvas、AMS、预约、体育、打印、门户都走西湖统一身份认证；Canvas 另兼容个人令牌，网页可存可清。
- **只存一份、只存本机**：钥匙串（Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service）优先；写文件即自动清钥匙串，反之亦然（[docs/credential_single_store.md](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` 查状态。

## 验证（端到端）

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

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

## 文档

| 文档 | 内容 |
| --- | --- |
| [docs/first_run.md](docs/first_run.md) | 启动行为与首次配置契约 |
| [docs/doctor.md](docs/doctor.md) | 环境自检逐项说明 |
| [docs/skill_reference.md](docs/skill_reference.md) | 命令示例、Python API 方法表、MCP 注册 |
| [docs/credential_single_store.md](docs/credential_single_store.md) | 「凭据只存一份」的设计与实现 |
| [docs/ams.md](docs/ams.md) / [docs/sportvenue_notes.md](docs/sportvenue_notes.md) / [docs/wikilake.md](docs/wikilake.md) / [docs/clubwiki.md](docs/clubwiki.md) | 各系统深挖注记 |
| [docs/library_migration_2026-10-28.md](docs/library_migration_2026-10-28.md) | 图书馆系统迁移说明 |
| [docs/module_audit_2026-10-27.md](docs/module_audit_2026-10-27.md) | 各模块「做不了」归因审计 |

## 许可与致谢

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