Every campus service in PKU harness, as a plugin you can read, share and write yourself.
Website · Download the app · Marketplace · Docs · Write a plugin · Language reference
PKU harness is an open-source, AI-native app for Peking University students. The app itself is only a harness: an agent, a design system and host services. Everything it can do comes from plugins, and this repository holds all of them: the official ones that ship with the app, the SDK, the plugin language, and the marketplace registry.
- Plugins are documents, not code. A plugin is a folder with a
PLUGIN.md, like an agent skill, written in a small declarative language the app interprets. No build, no package, no app release. - Shared by link. Push the folder to GitHub and send the link (or a QR code). The app shows exactly what the plugin can reach before installing it, and keeps it updated from the link.
- Safe by construction. A plugin can only call the campus services, websites and app features it declares. Campus passwords never leave the phone, and every tool goes through the user's per-effect permissions (read / write / money / public).
- Human and AI are equal operators. Every tool works from a tap and from the agent. The AI can even write a plugin with you, test it live, and hand you the review sheet.
- Tested like software. Every official plugin ships recorded tests that CI replays.
| Plugin | What it does | Kind |
|---|---|---|
classrooms |
Free classrooms per building and period | Document |
canteen |
Live canteen crowding, opening hours, notices | Document |
shuttle |
Next campus shuttle between Yanyuan and the new campus | Document |
notices |
Official notices from six university sites and WeChat | Document |
campus-events |
Academic talks and campus activities | Document |
grades |
Grades and GPA (with the treehole second factor handled) | Document |
library |
Catalogue search, loans and renewals, holds, study rooms and seats | Document |
treehole |
Browse, search, follow and post on the campus forum | Document |
elective |
Course selection results and open seats (read-only) | Document |
course-catalog |
Search every course offered this term | Document |
course-sync |
Sync this term's timetable into the schedule | Document |
room-booking |
Book seminar rooms in the teaching buildings | Document |
finance |
Stipends and income, tuition and housing fees, payment orders (read-only) | Document |
courses |
Blackboard: announcements, assignments and deadlines (synced to to-dos), submitting, grades, materials, lecture recordings | Document |
wallet |
Campus Card balance, payment code and top-ups, transactions and monthly stats, network fee, bath card, payment platform | Document |
calendar, card-share, authenticator |
Academic calendar, payment-code sharing, OTP | TypeScript (need host abilities; being ported) |
dashboard, schedule, scheduler, todo, timetable, ledger, memory, plugins, ui, deepseek, openai-compatible |
The harness's own features and model providers | TypeScript |
The full list, including community plugins, is in registry/registry.json
and on the marketplace.
A plugin is a folder:
my-plugin/
├── PLUGIN.md # manifest (YAML frontmatter) + instructions for the AI (Markdown)
├── tools/free.yaml # one file per tool, in the plugin language
├── widgets/*.json # optional dashboard widgets (generative UI)
└── tests/*.yaml # optional recorded tests
PLUGIN.md:
---
spec: 1
id: my-plugin
name: 空闲教室
description: Free classrooms in a teaching building.
version: 1.0.0
author: your-github-name
network: [portal.pku.edu.cn]
tools:
free: tools/free.yaml
---
Use `free` when the user asks where to study.tools/free.yaml:
title: 空闲教室
description: Free rooms in one teaching building today.
effect: read
input:
building: { type: string, default: 二教 }
steps:
- let: r
request:
url: https://portal.pku.edu.cn/publicQuery/classroomQuery/retrClassRoomFree.do
query: { buildingName: '${input.building}', time: 今天 }
headers: { referer: 'https://portal.pku.edu.cn/publicQuery/' }
as: json
- check: r.success
error: The portal did not answer
return: "r.rows.map(x => ({ room: x.room, seats: num(x.cap, 0) }))"Plugin names and tool titles are shown to students, so they are usually Chinese; descriptions and instructions are for the AI and can be English. Check and run the plugin on your computer, no phone needed:
bun install
bun run plugin validate path/to/my-plugin # schema, expressions, declared hosts: precise errors
bun run plugin run path/to/my-plugin free # call the real site
bun run plugin test path/to/my-plugin # replay tests/*.yamlThen push the folder to GitHub and install it in the app with its link, or with
pkuharness://plugin?src=<link>. The language reference
covers every step, the expression standard library, host abilities, widgets and limits, and
plugins/classrooms is a complete, tested example.
The marketplace indexes GitHub repositories
the way skills.sh indexes skills: one repository can hold many plugins, each
found by its PLUGIN.md.
- Push your plugin folder (or a repository of several) to a public GitHub repository.
- Open pkuharness.com/marketplace/submit, paste the repository and fix anything the scanner reports.
- Submit. A bot rescans the repository, comments its report on the submission issue and opens a pull request that lists it. Once merged, your plugin gets a page with its access review, install link, deep link and QR code.
You don't need a pull request here. The curated registry/registry.json
holds official and reviewed plugins; see CONTRIBUTING.md
to add a remote (MCP) plugin to it, and the publishing guide
for details.
| Topic | Where |
|---|---|
| Quick start: your first plugin | Build → Quick start |
| Tools, effects and permissions | Build → Tools · Concepts → Permissions |
| Recorded tests | Build → Testing |
| Porting a service from pkucli | Build → Porting from pkucli |
| Remote (MCP) plugins | Build → Remote plugin |
| SDK and host services | SDK reference |
| Language specification | PLUGIN-LANGUAGE.md |
| For AI coding agents | /llms.txt · /llms-full.txt |
| Kind | Where it runs | Use it for |
|---|---|---|
Document (PLUGIN.md) |
Interpreted by the app, sandboxed to what it declares | Campus integrations: the default |
| Remote (MCP over HTTPS) | Your server | Heavy work, third-party APIs, your own backend |
| TypeScript (bundled) | Inside the app binary | The harness's own features and host abilities |
All three compile to the same plugin contract (@pku-harness/sdk), so tools, permissions,
approvals, widgets and the agent work the same way for each.
| Path | Contents |
|---|---|
plugins/<id>/PLUGIN.md |
Plugin documents (official) |
plugins/<id>/src |
TypeScript plugins (builtinPlugins in plugins/index.ts) |
plugins/shared |
Code shared by TypeScript plugins |
packages/sdk |
The plugin contract, pure helpers, and the plugin language in src/lang (schemas, interpreter, abilities, loader) |
packages/cloud-protocol |
Wire protocol of PKU harness Cloud (schemas, envelope crypto, share links) |
packages/cloud-server |
Reference Cloud server (Bun + Hono + SQLite) |
registry |
Marketplace schema and registry.json |
templates/remote-plugin |
Starting point for a remote (MCP) plugin |
examples |
A demo remote plugin and a scripted model server for testing the agent without a key |
scripts |
plugin.ts (author CLI), bundle-docs.ts, validate-registry.ts |
Requires Bun 1.3 or newer.
git clone https://github.com/pkuinfo/pku-harness-plugins.git
cd pku-harness-plugins
bun install
bun run verify # typecheck, registry, bundled documents, all tests (exactly what CI runs)The app consumes this repository as a git submodule. After changing an official plugin document,
run bun run bundle so the app ships the new version; CI fails if you forget.
Contributions are welcome, from fixing a parser after a university site changes to writing a new plugin. Read CONTRIBUTING.md for the plugin rules and the review process, and please follow the Code of Conduct.
- Questions and ideas: Discussions in the app repository
- A campus service broke, or you want a new one: issues
- Good places to start:
good first issueandhelp wanted - Where to ask what: SUPPORT.md
PKU harness handles campus credentials. Please report vulnerabilities privately as described in SECURITY.md, never in a public issue.
| Repository | Role |
|---|---|
| pkuinfo/pku-harness | The app (Expo / React Native) |
| pkuinfo/pkuharness-website | Website, developer docs and marketplace |
| pkuinfo/pkucli | Command-line tools for PKU services: the protocol reference for plugins |
MIT © pkuinfo contributors