How sshwy/pku3b works
1. What this repo is
- pku3b is a single Rust CLI binary for PKU’s teaching platform (course.pku.edu.cn).
- The runtime is centered on authenticated HTTP scraping/API calls plus local file handling for downloads, uploads, and video processing.
2. Top-level control flow
- src/main.rs is the entrypoint.
- src/cli/ defines the command-line surface and dispatches to feature-specific subcommands such as assignment, course table, announcement, video, syllabus/selection, Bark, and TT识图.
- Each subcommand is a boundary between user interaction and the domain API layer.
3. Domain API layer
- src/api/ is the main integration layer.
- It is split into high-level modules like blackboard, portal, syllabus, thesis_lib, and drm_lib, which represent different teaching-site subsystems.
- These modules provide task-oriented operations used by the CLI: list/query items, download attachments, submit work, inspect schedules, list announcements, fetch video metadata, and perform course-selection actions.
4. Low-level protocol boundary
- src/api/low_level/ contains the request/response plumbing for each backend area.
- This layer likely owns endpoint paths, cookies/session handling, parsing, and any PKU-specific quirks.
- The higher-level API modules wrap this low-level layer so the CLI can work with domain concepts instead of raw HTTP payloads.
5. Authentication and configuration
- src/config.rs and the init/config CLI commands manage persisted credentials and settings.
- The tool expects a one-time login initialization, then reuses stored config for later commands.
- This is the main state boundary between “local machine” and “remote PKU service”.
6. Course selection workflow
- src/api/syllabus.rs and the syllabus CLI subcommand implement the “quick course selection” loop.
- This flow can repeatedly poll/select courses and report success/failure.
- It optionally triggers Bark notifications, so selection is the most stateful and time-sensitive subsystem in the repo.
7. Assignment workflow
- src/api/blackboard.rs plus src/cli/cmd_assignment.rs cover assignment listing, attachment download, and submission.
- File uploads likely use src/multipart.rs, which is the local abstraction for constructing multipart form bodies.
- This subsystem is where local files cross the network boundary into the teaching platform.
8. Video workflow
- src/cli/cmd_video.rs and the portal/video API modules handle course replay listings and downloads.
- The README states that playback download depends on external ffmpeg, so the tool downloads source media and then converts/remuxes it into MP4 locally.
- This creates a two-step flow: remote media retrieval, then local media processing.
9. Announcements, timetable, and other read-only queries
- src/api/portal.rs, src/cli/cmd_announcement.rs, and src/cli/cmd_course_table.rs expose read-only views such as announcements, detail pages, and personal schedules.
- These paths are primarily fetch-and-render flows with minimal local state.
10. Captcha / external helper service
- src/ttshitu.rs and src/cli/cmd_ttshitu.rs integrate a TT识图 account for image-captcha solving.
- This is an optional external dependency used to unblock login/selection-related flows when captcha is required.
11. Notification integration
- src/cli/cmd_bark.rs integrates with Bark for push notifications to iPhone/iPad.
- Bark is not part of the core teaching-site flow; it is an optional side channel used mainly for course-selection status events.
12. Utility and support modules
- src/qs.rs, src/pdf.rs, src/utils.rs, src/walkdir.rs, and src/multipart.rs provide shared helpers for query-string handling, PDF/file processing, filesystem traversal, and request bodies.
- These are cross-cutting utilities consumed by multiple subcommands and API modules.
13. Operational/runtime dependencies
- The binary is Rust-based and managed with Cargo; .github/workflows/ covers formatting and release automation.
- build.rs and assets/ support packaging and distribution, including a Windows install script and demo artifacts, but they are not part of the core runtime architecture.
14. Key architectural boundary to draw
- On one side: the local CLI, config store, file system, and optional external tools/services (ffmpeg, Bark, TT识图).
- On the other side: PKU teaching platform subsystems accessed through a layered API (low_level transport/parsing, then domain modules, then CLI commands).
- Most features are thin orchestrations around that boundary rather than independent services.
Main entry points: cli/mod.rs CLI · portal.rs Portal · api/mod.rs API · low_level.rs Low level
Components 22
Local runtime
CLI entrypoint, config, file handling, and helper modules on the machine.
- Main · CLI process startup and top-level wiring.
src/main.rs - CLI · Command-line surface and subcommand routing.
src/cli/mod.rs - Assignment · Assignment listing, download, and submission flows.
src/cli/cmd_assignment.rs - Course table · Personal timetable and schedule views.
src/cli/cmd_course_table.rs - Announcement · Read-only announcement and detail queries.
src/cli/cmd_announcement.rs - Selection · Quick course selection workflow and polling loop.
src/cli/cmd_syllabus.rs - Video · Replay listing and download workflow.
src/cli/cmd_video.rs - Thesis lib · Library/thesis-related queries and actions.
src/cli/cmd_thesis_lib.rs - Bark · Push notification integration for selection status.
src/cli/cmd_bark.rs - TT识图 · Captcha-solving integration for login and selection flows.
src/cli/cmd_ttshitu.rs - Config · Stored credentials and runtime settings.
src/config.rs - Multipart · Local multipart request-body construction.
src/multipart.rs - PDF · PDF and document handling helpers.
src/pdf.rs - Utils · Shared utility functions used across features.
src/utils.rs
PKU platform
Layered API integration for the teaching platform backends.
- API · High-level domain API facade over the PKU platform.
src/api/mod.rs - Low level · Backend request/response plumbing and site-specific quirks.
src/api/low_level.rs - Blackboard · Assignments, attachments, and submissions.
src/api/blackboard.rs - Portal · Announcements, schedules, and replay/course pages.
src/api/portal.rs - Syllabus · Course-selection polling and selection actions.
src/api/syllabus.rs - Thesis lib · Thesis/library-specific backend operations.
src/api/thesis_lib.rs - DRM lib · DRM-protected library or media backend operations.
src/api/drm_lib.rs
External services
Optional third-party helpers used by some workflows.
- TT识图 · External captcha-solving account/service integration.
src/ttshitu.rs
Connections 35
- Main → CLI: starts · Entrypoint hands off to CLI dispatch.
- Main → Config: loads · Initializes persisted settings and credentials.
- CLI → Assignment: routes · Dispatches assignment commands.
- CLI → Course table: routes · Dispatches timetable commands.
- CLI → Announcement: routes · Dispatches announcement commands.
- CLI → Selection: routes · Dispatches course-selection commands.
- CLI → Video: routes · Dispatches video commands.
- CLI → Thesis lib: routes · Dispatches thesis/library commands.
- CLI → Bark: routes · Dispatches Bark notification setup/usage.
- CLI → TT识图: routes · Dispatches TT识图 integration commands.
- Assignment → Blackboard: uses · Assignment workflow is driven by the Blackboard API.
- Assignment → Multipart: uploads · Builds multipart bodies for file submission.
- Course table → Portal: queries · Fetches schedule and timetable data.
- Announcement → Portal: queries · Fetches announcements and detail pages.
- Video → Portal: queries · Uses portal/video endpoints for replay listings and downloads.
- Selection → Syllabus: drives · Runs the selection loop against syllabus APIs.
- Selection → TT识图: optional captcha · Can invoke captcha solving when needed.
- Selection → Config: reads state · Uses stored credentials and selection settings.
- Thesis lib → Thesis lib: uses · Delegates library/thesis operations to API.
- Bark → Config: stores token · Persists Bark endpoint or token settings.
- TT识图 → TT识图: uses · Wraps the external captcha service.
- API → Low level: wraps · High-level APIs are built on the low-level transport layer.
- API → Blackboard: exposes · Re-exports or organizes Blackboard capabilities.
- API → Portal: exposes · Re-exports or organizes portal capabilities.
- API → Syllabus: exposes · Re-exports or organizes selection capabilities.
- API → Thesis lib: exposes · Re-exports or organizes thesis/library capabilities.
- API → DRM lib: exposes · Re-exports or organizes DRM/library capabilities.
- Blackboard → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Portal → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Syllabus → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Thesis lib → Low level: delegates · Uses shared request/session plumbing for backend calls.
- DRM lib → Low level: delegates · Uses shared request/session plumbing for backend calls.
- Portal → PDF: processes · Video/document workflows may produce or transform local files.
- Blackboard → Utils: shares helpers · Common parsing and filesystem helpers are reused here.
- Portal → Utils: shares helpers · Common parsing and filesystem helpers are reused here.