Build a plugin

A plugin connects PKU harness to one campus service, or adds one feature to the app. Each plugin offers a set of tools: small, typed operations such as "list free classrooms" or "show my card balance". The AI assistant and the user's own taps both call the same tools.

Writing a plugin therefore comes down to three jobs. You find out how the service answers requests, you wrap those requests in tools, and, where it helps, you add a widget or a screen.

This section assumes you can read YAML or TypeScript and use a terminal. You don't need to know the app's internals.

Choose the kindCopy Anchor Link

There are three kinds of plugin. Most people should write the first one.

A plugin document is a folder with a PLUGIN.md file. Its tools are written as YAML steps with small, safe expressions, and the app interprets them on the phone. You publish it with git push, and students install and update it from a link. Use it for most campus integrations: requests to campus or public websites, extraction of the data you need, and the user's campus session when a service requires sign-in. Start with the quickstart, then read Declarative plugins. You can also write it with the AI inside the app.

A remote plugin is a server you run yourself. It speaks the Model Context Protocol (MCP), a standard way for AI apps to call tools over HTTP, using the Streamable HTTP transport. You can write it in any language. Updates go out when you deploy the server; no app release is involved. Use it for your own service, for heavy work, or for anything that needs general-purpose code. Start from templates/remote-plugin.

A bundled plugin is a TypeScript module, written with zod and React Native, that ships inside the app. It reaches users only with app releases, so open an issue before you start. Use it for the app's own features (dashboard, schedule, scheduler, memory, model providers and so on) and for integrations the plugin language can't express yet. Start with definePlugin.

The official campus integrations classrooms, campus-events, grades, canteen, shuttle and notices are already plugin documents. The other official integrations are still TypeScript, and we are porting them one at a time.

The order of workCopy Anchor Link

Repositories you needCopy Anchor Link

Start with pkuinfo/pku-harness-plugins. It holds the SDK and the plugin language, the author command-line tool (bun run plugin), the official plugin documents and bundled plugins, the marketplace registry, and the remote-plugin template and examples.

You need pkuinfo/pku-harness, the app itself, only to run a bundled plugin on a phone or emulator. A plugin document doesn't need it until you want to try campus requests for real.

pkuinfo/pkucli is a set of Rust command-line tools for PKU services. Use it as a reference for how each service's protocol works.

mkdir pku-info && cd pku-info
git clone https://github.com/pkuinfo/pku-harness-plugins.git     # SDK, plugins, registry, template
git clone --recurse-submodules https://github.com/pkuinfo/pku-harness.git   # only to run bundled plugins in the app
cd pku-harness-plugins && bun install && bun test

Ground rules (from CONTRIBUTING.md)Copy Anchor Link

1. Tools are the API. Give each tool a clear Chinese title, which users see, and a description written for the model that says when and how to use it. Validate every input: with input fields in a plugin document, with zod in a bundled plugin, and with JSON Schema in a remote plugin.
2. Declare effects honestly. A read-only tool sets effect: read (plugin documents and bundled plugins) or readOnlyHint: true (MCP). A tool that changes state, spends money or posts publicly must say so.
3. Never ask for campus passwords. Credentials stay on the user's phone.
4. Return data, not instructions. The model treats tool results as data.
5. Declare what you reach. In a plugin document, list campus, network and abilities; requires is derived from them. In code, list requires. Don't depend on a shell or a file system on the phone.
6. Port campus protocols from pkucli when it already implements them, and credit the source.
7. Write both languages. A plugin document has an i18n.en section. A bundled plugin needs an English overlay for every user-facing manifest string, and a src/strings.ts table for the text in its screens and widgets.