PKU harnessContributing
How to contribute plugins, app changes, protocol notes and documentation to PKU harness, and the conventions, security rules and license that apply.
PKU harness is developed in public for the PKU community. Every repository accepts issues and pull requests. This page explains which repository to use for each kind of change and what we expect from a contribution.
Where to contribute
The right repository depends on what you want to change.
- Connecting a campus service or adding a capability. This is usually done with a plugin
document. If your plugin needs its own server, write a remote plugin in your own repository.
Official plugins live in
pku-harness-plugins; please open an issue there before you start. See Build a plugin. - Listing a plugin. See Marketplace.
- Fixing or improving the app. Use
pku-harness. ReadAGENTS.md,docs/ARCHITECTURE.mdanddocs/DESIGN.mdfirst. - Documenting or fixing a campus protocol. Use
pkucli. - Improving these docs. Use
pkuharness-website. The pages are incontent/docs/, and every page has an edit link.
Conventions
- Use bun for all JavaScript and TypeScript (
bun install,bun run,bun test,bunx). - Keep commits small and follow Conventional Commits, for example
feat(wallet): …,fix(treehole): …ordocs: …. - Before you open a pull request in the plugins repository or the app, run
bun run verifyand make sure it passes. It runs the same checks as continuous integration (CI). In the plugins repository these are the typecheck, registry validation, the bundled-documents check and every test. In the app they are the typecheck, lint and tests. - If you change the UI, check it on a device or emulator in both the dark and the light theme.
- Plugin changes are merged into
pku-harness-pluginsfirst. The app then commits an update of itsplugins/submodule. - Campus protocols are ported from pkucli. Cite the source file in a comment.
- Docs and code comments are written in English. Text shown to users is written in Chinese first, and every such string also needs an English translation.
Using AI agents
The repositories are designed to be worked on by people and coding agents together. Each one has
an AGENTS.md (or CLAUDE.md) file with its rules. If you write a plugin with an agent, point
it at For AI agents and at the Markdown version of these docs
(/llms.txt).
You are responsible for what you submit. Review the generated code, run the checks yourself, and never let an agent handle real credentials.
Community
- Discuss ideas and report bugs in the GitHub issues of the relevant repository.
- Be kind to others. The app, plugins and website repositories each have a code of conduct
(
CODE_OF_CONDUCT.md).
Security
Report vulnerabilities privately, following the SECURITY.md of the affected repository. Don't
report them in public issues. Also keep real credentials, tokens and personal data out of issues,
test fixtures and logs.
License
All repositories use the MIT license. By contributing, you agree that your contribution is released under the same license.
Roadmap
The work on PKU harness that is done, in progress, planned or on hold, summarised from the app's plan and design documents.
For AI agents
Instructions for coding agents (Claude Code, Codex, the in-app agent) that build a PKU harness plugin from start to finish. They cover which kind of plugin to build, the steps, the rules you must follow, the checks to run and the pages to load.