PKU harnessRepositories
The repositories of the pkuinfo organisation (the app, the plugins repository, pkucli, pkubdcard and this website), what each one contains and how they depend on each other.
All of the project's code is open source and lives in the pkuinfo
GitHub organisation. The project is split into five repositories.
| Repository | Stack |
|---|---|
pku-harness | Expo SDK 58, React Native 0.88, TypeScript, bun |
pku-harness-plugins | TypeScript, zod, bun workspace |
pkucli | Rust workspace (reqwest, tokio, clap) |
pkubdcard | Go (Gin) + Preact |
pkuharness-website | Next.js 16 + Fumadocs 16, bun |
What each repository is for
pku-harness is the app itself. It contains the harness, which is the core that runs the AI
agent loop and hosts the plugins, together with the design system, the host services, the campus
sessions and the scheduler. The app targets Android first.
pku-harness-plugins holds everything a plugin author needs. It contains the SDK
(@pku-harness/sdk), every bundled plugin (@pku-harness/plugins), the marketplace registry
(@pku-harness/registry), the cloud protocol (@pku-harness/cloud-protocol), the remote plugin
template and some examples. If you want to build a plugin, start here.
pkucli is a set of command-line tools for PKU web services. It is also the protocol
reference for every campus service the app talks to: when the app needs a login flow or an
endpoint, it is ported from here. The repository also ships agent skills.
pkubdcard is a web app for sharing a campus-card payment code. It was an earlier port of
pkucli's campus-card flow, and its UI and rate limits shaped the design of the cloud card-share
plugin.
pkuharness-website is this website. It serves the landing page, the downloads, these docs
and the marketplace.
How they fit together
All campus logins go through IAAA (iaaa.pku.edu.cn), PKU's unified login service. pkucli
documents the campus protocols, and the app follows them. The app includes
pku-harness-plugins as a git submodule. Remote plugins connect to the app through the Model
Context Protocol (MCP), and the PKU harness Cloud provider is built on the cloud protocol and the
reference cloud server from the plugins repository.
| Repository | Uses | How |
|---|---|---|
pku-harness (the app) | PKU IAAA (iaaa.pku.edu.cn) | Every campus login goes through it |
pku-harness (the app) | pkucli | Implements campus services from the protocols pkucli records |
pku-harness (the app) | pku-harness-plugins | Includes the SDK and plugins as a git submodule |
| Remote plugins (anyone can write one) | templates/remote-plugin in pku-harness-plugins | Start from the template; connect to the app over MCP |
| PKU harness Cloud providers | cloud-protocol and cloud-server in pku-harness-plugins | Implement the cloud protocol; cloud-server is the reference |
pkuharness-website | registry.json, indexed plugin repositories, GitHub releases | Builds the docs, the marketplace and the download page |
The website stands beside the others. Its marketplace reads registry.json and the plugin
repositories it has indexed, and its download page lists the app's GitHub releases.
Inside pku-harness-plugins
| Folder | Contents |
|---|---|
packages/sdk | @pku-harness/sdk: the plugin contract, pure helpers and the plugin language (src/lang: schemas, interpreter, abilities, loader) |
packages/cloud-protocol | @pku-harness/cloud-protocol: Cloud wire schemas, envelope crypto, share links |
packages/cloud-server | The reference PKU harness Cloud server (Bun + Hono + SQLite) |
plugins/<id>/PLUGIN.md | Official plugin documents. They ship with the app (bun run bundle) and update from their link |
plugins/<id>/src | Bundled TypeScript plugins (builtinPlugins in plugins/index.ts) |
plugins/shared | Code shared by bundled plugins |
scripts | plugin.ts (author CLI: bun run plugin validate|test|run), bundle-docs.ts, validate-registry.ts |
registry | Marketplace schema and registry.json |
templates/remote-plugin, examples/* | The remote plugin template, plus demo-canteen and mock-llm |
These packages are private to the workspace, and none of them is published to npm. The app pulls
the whole repository in as its git submodule plugins/.
Plugin documents are shared the same way as agent skills: as a folder or a link, which the app reads and interprets. See Declarative plugins.
Bundled plugins today
The app currently bundles the following plugin documents: classrooms, campus-events,
grades, canteen, shuttle and notices.
It also bundles these TypeScript plugins: ui (generative UI), dashboard, scheduler,
todo, schedule, timetable, course-sync, authenticator (手机令牌, the IAAA mobile
token), calendar (校历, the academic calendar), wallet (campus card, network fee,
utilities), card-share (share a payment code through the Cloud), courses (Blackboard),
course-catalog, treehole, elective, finance, library, room-booking, memory,
plugins (plugin management and AI authoring), deepseek and openai-compatible.
The marketplace has a description of each one.