# 文档

- [简介](/docs): PKU harness 是一个开源的北大校园生活 App，核心是一个 AI 助手。这份文档写给为它开发插件的同学和 AI 助手。
- 使用手册
  - [使用手册](/docs/manual): PKU harness Android App 的使用说明：安装、首次设置、四个标签页、插件与权限、校园账号和各项设置。
  - [安装与更新](/docs/manual/install): 下载并安装 Android 版 PKU harness，核对安装包，以及新版本怎样送到你的手机上。
  - [首次设置](/docs/manual/first-run): 第一次打开 App 时的介绍页和六个设置步骤：AI 服务、北大账号、手机令牌、插件、提醒权限和 Copilot，以及「稍后设置」的作用。
  - [对话](/docs/manual/chat): 在「对话」页和助手交谈：打字或用语音输入消息，附上照片和文档，使用 / 命令，管理对话列表，确认助手的操作，编辑和复制消息，停止回复。
  - [看板](/docs/manual/dashboard): 「看板」页由一组小组件组成。本页说明怎样添加组件、组件的三种尺寸，以及怎样调整顺序、尺寸和删除组件。
  - [日程与提醒](/docs/manual/schedule): 「日程」页的课表、待办、提醒和定时任务：怎样添加和修改，提醒的重复规则，以及让通知准时送达的设置。
  - [插件与权限](/docs/manual/plugins): 在「设置 → 插件」里开启和关闭插件、为每类操作设置权限、通过链接安装插件、更新和移除插件。
  - [校园账号与手机令牌](/docs/manual/campus-account): 登录和退出北大校园账号，填写登录时的验证码，把 App 绑定为手机令牌，以及只能在校园网内使用的服务。
  - [AI 服务](/docs/manual/ai-model): 先设置好 AI 模型：在中国大陆选择哪家服务商（DeepSeek、阿里云百炼、百度千帆），怎样一步一步申请 API Key、在哪里填写，以及账户余额、上下文预算和费用。
  - [语音输入](/docs/manual/voice-input): 在对话框里说话代替打字。用你自己的 Key 设置语音识别服务：阿里云百炼（默认，说话时文字同步出现）、DeepSeek（直接用 AI 服务的 Key）或硅基流动，也可以转写音频文件。
  - [校园卡与付款码共享](/docs/manual/campus-card): 「校园钱包」插件里的校园卡余额、付款码、充值、网费和浴卡，以及用「付款码共享」把付款码临时借给朋友。
  - [Copilot 手机助手](/docs/manual/copilot): Copilot 让助手在一块独立的屏幕上替你操作手机里的其他 App。本页面向不熟悉手机设置的同学，一步一步说明开发者选项、无线调试和配对码、无障碍、允许的 App 和截图怎样设置，列出各品牌手机的注意事项，并说明怎样暂停、停止以及彻底关闭。
  - [设置与数据](/docs/manual/settings): 「设置」页的各项内容：账号、AI 服务、语音输入、云服务、用量、插件、提醒与通知、外观、语言、时区、触感反馈、导出和清除数据、更新和「关于」页面，以及助手怎样在对话中替你修改设置。
  - [常见问题](/docs/manual/troubleshooting): PKU harness 的常见问题和解决方法：校园网、登录时的验证码、AI 服务和语音输入报错、附件文件、提醒延迟、App 更新、付款码，以及 Copilot 的设置。
- 核心概念
  - [架构](/docs/concepts/architecture): PKU harness 的框架层由 Agent 循环、设计系统和宿主服务组成，具体功能都由插件通过同一套接口提供。
  - [插件](/docs/concepts/plugins): 插件有三种形式。插件文档（PLUGIN.md）由 App 解释执行，通过链接安装；内置 TypeScript 插件随 App 发布；远程插件是通过 URL 添加的 MCP 服务器。三者共用同一个注册表、同一套权限系统和同一个 Agent 循环。
  - [工具与效果](/docs/concepts/tools-and-effects): 工具是插件对外提供功能的唯一方式。每个工具有 id、标题、写给模型的说明、zod 输入 schema，以及唯一一个效果（read、write、money 或 public）。
  - [权限与授权](/docs/concepts/permissions): 你可以针对每个插件的每种效果，决定助手可以直接执行、需要先询问，还是不能执行。定时任务只能读取。
  - [能力需求](/docs/concepts/capabilities): 插件在 `requires` 里声明它需要手机提供哪些能力。手机满足不了时，框架会隐藏这个插件，并告诉用户原因。
  - [宿主服务](/docs/concepts/host-services): 内置插件需要做自身以外的事情时，都要通过 `HostServices`。框架在工具里以 `ctx.services`、在页面和小组件里以 `props.services` 的形式把它传给插件。
  - [生成式界面](/docs/concepts/generative-ui): 助手用 JSON 描述一段界面，App 用原生组件把它显示出来，可以显示在对话里（`ui.render`），也可以显示在看板上。表单提交的内容会作为你的下一条消息发回给助手。
  - [看板小组件与数据](/docs/concepts/dashboard): 看板上的小组件有两类：助手搭建的小组件（一份生成式界面 spec，加上对读取类工具的绑定），以及插件提供的原生组件。刷新由宿主统一负责，所有组件共用一份缓存。
  - [定时任务与通知](/docs/concepts/scheduler): 提醒、待办、上课提醒和定时检查都由同一个定时任务引擎驱动。每个任务由一个触发器（单次，或有限次的重复）和一个动作（通知、检查或助手）组成，准时到分钟触发。
  - [校园会话与 IAAA](/docs/concepts/campus-sessions): 校园账号由框架保管。框架自己登录各个北大服务，再通过 `services.campus.request` 把响应交给插件。插件永远拿不到密码或会话令牌。
  - [安全模型](/docs/concepts/security): 账号凭据只留在手机上。工具结果只是数据，不是指令；第三方内容会「污染」助手的当前回合。任何要离开手机的数据都会先声明，并征得用户同意。
- 开发插件
  - [开发插件](/docs/build): 怎样在 PLUGIN.md 插件文档、远程插件和内置 TypeScript 插件之间做选择，需要克隆哪些仓库，以及从写第一个工具到上架插件市场的工作顺序。
  - [编写第一个插件](/docs/build/quickstart): 写一个只有一个工具的 PLUGIN.md 插件，用录制的响应测试它，再以链接的形式分享。示例是空闲教室插件的简化版。
  - [声明式插件（PLUGIN.md）](/docs/build/declarative-plugins): 插件语言的说明。插件是一个文件夹，包含 PLUGIN.md 清单、给助手的说明、用 YAML 步骤写的工具和生成式界面小组件。App 解释执行它，通过链接安装，不需要构建代码，也不需要 App 发版。
  - [让 AI 帮你写插件](/docs/build/ai-authoring): 在 App 里让助手和你一起写 PLUGIN.md 插件。它会查阅语言参考、校验草稿、对真实服务试运行只读工具，最后打开审核页，由你决定是否安装。
  - [快速上手：远程插件](/docs/build/remote-plugin): 基于 templates/remote-plugin 编写远程插件，也就是一个使用 Streamable HTTP 的 MCP 服务器。在本地运行它，添加到 App，再部署上线并登记到插件市场。
  - [内置插件](/docs/build/bundled-plugin): 用 definePlugin 编写随 App 一起发布的插件。本页通过一个完整示例，依次介绍工具、数据源、页面、设置项、小组件、快捷指令、英文文字和测试。
  - [工具与 schema](/docs/build/tools): 怎样设计模型好用的工具。内容包括命名、描述、用 zod（内置插件）或 JSON Schema（MCP）定义输入、如实声明效果、只返回数据，以及处理用户可以补救的状态。
  - [界面扩展](/docs/build/ui): 内置插件怎样通过 `contributes` 添加页面、设置项、标签页内容、看板小组件和快捷指令，并用 App 传入的 HostUI 组件搭建界面。
  - [多语言（i18n）](/docs/build/i18n): 内置插件怎样同时提供中文和英文。清单里的文字在 `i18n.en` 里写英文版，页面和小组件的文字放进 `defineStrings` 表，日期交给 SDK 的格式化函数，给模型看的文字不翻译。
  - [测试](/docs/build/testing): 怎样测试各种插件。插件文档回放录制的响应，解析器和纯逻辑用 bun test 写单元测试，用按脚本应答的模拟模型完整跑通助手的流程，远程插件用 demo-canteen 示例来试。
  - [从 pkucli 移植](/docs/build/porting-from-pkucli): pkucli 是北大各项服务的协议参考。本页介绍怎样把它 Rust crate 里的接口、登录步骤和各种特殊情况移植到插件里，把登录交给 App，并注明出处文件。
  - [发布](/docs/build/publishing): 远程插件和内置插件怎样送到用户手上。远程插件登记到插件市场的注册表；内置插件合并进 pku-harness-plugins，通过签名的 OTA 更新或下一个 App 版本到达用户手机。
- 插件市场
  - [概览](/docs/marketplace): 插件市场如何发现、检查和上架插件，各个徽章的含义，以及 App 如何安装插件。
  - [清单参考](/docs/marketplace/manifest): 插件市场如何读取 PLUGIN.md（插件语言 v1）、扫描器在哪里查找插件、检查哪些内容，以及远程 MCP 服务器使用的 pku-harness.plugin.json 格式。
  - [发布](/docs/marketplace/publishing): 提交仓库、在一个仓库里发布多个插件、推送代码来更新，以及下架插件。
  - [审核规则与安全](/docs/marketplace/review): 每个上架插件都要遵守的规则、维护者把插件标为「已审核」前检查什么，以及如何举报插件。
- SDK 参考
  - [SDK 参考](/docs/sdk): `@pku-harness/sdk` 的获取方式和各模块的导出。SDK 包含插件的类型定义（definePlugin、工具、模型服务商、HostServices、HostUI、能力需求）、插件语言的解释器，以及重复规则、定时、课表、格式化等纯函数。
  - [plugin](/docs/sdk/plugin): 定义插件时用到的全部类型：definePlugin、defineTool、definePreference、PluginDef、ToolDef、ToolContext、效果、调用方、能力需求、KV、轮次信息、数据源、设置项、模型、语音和 OCR 服务商、翻译和旧 id。
  - [HostServices](/docs/sdk/host-services): 内置插件通过 ctx.services 或 props.services 拿到的全部宿主服务的签名和行为，包括设置注册表和附件，以及任务、小组件目录和常驻通知相关的类型。
  - [ui](/docs/sdk/ui): 插件界面用到的类型：页面和小组件收到的 props，HostUI（组件、主题、导航、触感反馈、实时数据 hook），以及全部扩展类型（页面、设置项、标签页、小组件、命令）。
  - [genui](/docs/sdk/genui): 描述生成式界面 spec 的 specSchema 和 UISpec 类型，以及 services.genui.checkSpec 返回的 SpecCheck 结果。
  - [dashboard](/docs/sdk/dashboard): 看板小组件的数据类型：Widget 类型，Binding 和 WidgetSource 的 schema，以及 WidgetSize。services.widgets 也使用这些类型。
  - [scheduler](/docs/sdk/scheduler): 调度器的类型和工具函数：Trigger、Action、Condition、Job 及其 zod schema，计算重复规则的纯函数，便于模型使用的 ScheduleInput 格式，条件判断，以及无人值守运行的限制常量。
  - [notify](/docs/sdk/notify): NotifyReadiness 类型和 deliveryBlocker 函数，用于在界面上检查提醒和定时检查能否准时送达。
  - [campus](/docs/sdk/campus): 通过宿主访问已登录校园服务所用的类型（CampusService、CampusRequest、CampusResponse、multipart 上传、用户选取的文件），以及登录状态和手机令牌验证码。
  - [cloud](/docs/sdk/cloud): 插件使用 PKU harness Cloud 时的接口：CloudManifest、PluginCloud（store、channels、push、functions）、Channel 及其事件、SecretLink、CloudStatus、CloudError 和 defineCloudFunction。
  - [timetable](/docs/sdk/timetable): 课表的数据类型 Course 和 Semester，以及处理课表的纯函数：解析周次、计算教学周、列出某天的课、判断上课状态和生成课前提醒的触发器。
  - [todo](/docs/sdk/todo): 待办事项的数据类型 Todo 和 TodoInput，供 services.todos 使用。
  - [format](/docs/sdk/format): 按界面语言格式化日期和时间的函数，以及用来定义多语言字符串表的 defineStrings。
  - [pointer](/docs/sdk/pointer): setPointer：按 JSON Pointer 路径往对象里写入一个值，用来把绑定的结果放进小组件的状态。
- 云服务
  - [PKU harness Cloud](/docs/cloud): PKU harness Cloud 是一套可选的插件后端标准，包含存储、中继通道、推送、文件和服务端函数。官方实例、自建服务器或任何符合标准的服务器都可以提供这些服务。数据默认端到端加密，云端不保存校园身份。
  - [插件指南](/docs/cloud/plugin-guide): 在内置插件里使用 PKU harness Cloud：声明云服务清单和数据说明，处理授权与可用性，使用存储和中继通道，并安全地展示分享链接。
  - [安全](/docs/cloud/security): PKU harness Cloud 怎样让服务器读不到用户数据：设备密钥对、带工作量证明的注册、短时效的签名插件 token、XChaCha20-Poly1305 信封、放在 URL 片段里的分享链接密钥、只能认领一次的通道，以及分享链接脱敏。
  - [服务商与自建](/docs/cloud/providers): 如何选择官方实例、自建参考服务器或任何符合标准的 URL，服务商需要实现哪些接口，以及如何运行和配置参考服务器。
  - [cloud-protocol 包](/docs/cloud/protocol-package): @pku-harness/cloud-protocol：App、服务商和查看页共用的 zod 线上 schema、路径构造函数、信封加密、分享链接工具、工作量证明和 token 挑战。
  - API 参考
    - [元数据](/docs/cloud/api/meta): 服务商发现。用户连接服务商时，宿主会读取它并检查 `protocol`、`services` 和 `limits`。
    - [设备与鉴权](/docs/cloud/api/devices): 设备的云端身份只有一把 Ed25519 签名密钥和一把 X25519 加密密钥，没有学号，也没有姓名。注册需要完成一次工作量证明；插件 token 由签名质询换取，有效期 10 分钟。
    - [存储](/docs/cloud/api/store): 键值存储，命名空间 `(deviceId, plugin)` 取自 token，而不是路径。插件声明了 `e2e` 时，值都是信封。
    - [通道（所有者）](/docs/cloud/api/channels): 设备开启的端到端加密中继通道，用来和打开分享链接的人实时共享。所有者通过 WebSocket 与对端通信，服务器只转发信封。
    - [通道（对端）](/docs/cloud/api/peers): 查看方（网页或另一个 App）打开分享链接 `https://<provider>/s/<id>#k=<secret>` 后调用的接口。片段 `k` 不会发到服务器，查看方用它推导出 `authKey` 来加入通道。
    - [分享链接与页面](/docs/cloud/api/pages): 给没装 App 的人用的公开跳转和静态查看页。
    - [服务端函数](/docs/cloud/api/functions): 插件声明的服务端函数。参考服务器已经实现，但生产配置默认关闭（`CLOUD_FN_POLICY=allowlist`，列表为空），官方服务器也不会开放；自建服务器可以自行开启。
    - [推送（规划中）](/docs/cloud/api/push): 推送 token 和定时推送，载荷端到端加密。尚未实现，参考服务器对这些接口返回 `501 unsupported`。
- 生态
  - [仓库](/docs/ecosystem/repositories): pkuinfo 组织下的各个仓库（应用、插件仓库、pkucli、pkubdcard 和本网站），每个仓库包含什么，以及它们之间的依赖关系。
  - [路线图](/docs/ecosystem/roadmap): PKU harness 已完成、进行中、计划中和暂缓的工作，整理自应用仓库的开发计划和设计文档。
  - [参与贡献](/docs/ecosystem/contributing): 如何为 PKU harness 贡献插件、应用改动、协议说明和文档，以及需要遵守的约定、安全规则和许可证。
- [写给 AI 助手](/docs/for-agents): 写给编程 Agent（Claude Code、Codex、App 内置助手）的说明，帮助它从头到尾做出一个 PKU harness 插件。内容包括如何选择插件类型、具体步骤、必须遵守的规则、要运行的检查，以及应当加载哪些页面。

# Docs

- [Introduction](/en/docs): PKU harness is an open-source app for campus life at Peking University, built around an AI assistant. These docs are for the people and AI agents who build plugins for it.
- User manual
  - [User manual](/en/docs/manual): How to use the PKU harness Android app — installing it, first-run setup, the four tabs, plugins and permissions, your campus account and the settings.
  - [Install and update](/en/docs/manual/install): Download and install PKU harness for Android, check the APK, and how new versions reach your phone.
  - [First-run setup](/en/docs/manual/first-run): The intro pages and the six setup steps the first time you open the app — AI provider, PKU sign-in, authenticator, plugins, reminder permissions and Copilot — and what "Set up later" does.
  - [Chat](/en/docs/manual/chat): Talk to the assistant in the Chat tab — type or speak messages, attach photos and documents, use / commands, manage your chats, confirm the assistant's actions, edit and copy messages, and stop a reply.
  - [Dashboard](/en/docs/manual/dashboard): The Dashboard tab is a set of widgets. This page covers adding widgets, the three widget sizes, and reordering, resizing and removing them.
  - [Schedule and reminders](/en/docs/manual/schedule): The timetable, to-dos, reminders and scheduled tasks on the Schedule tab — adding and changing them, the repeat options for reminders, and the settings that make notifications arrive on time.
  - [Plugins and permissions](/en/docs/manual/plugins): Turn plugins on and off in Settings → Plugins, set a permission for each kind of action, install plugins from a link, and update or remove them.
  - [Campus account and authenticator](/en/docs/manual/campus-account): Sign in to and out of your PKU account, enter verification codes, make the app your mobile authenticator, and the services that only work on the campus network.
  - [AI provider](/en/docs/manual/ai-model): Set up the AI model first — which provider to choose in mainland China (DeepSeek, Alibaba Cloud Bailian, Baidu Qianfan), how to get an API key step by step, where to enter it, the account balance, the context budget and costs.
  - [Voice input](/en/docs/manual/voice-input): Speak instead of typing in the chat box. Set up a speech-to-text service with your own key (Alibaba Cloud Bailian, the default, where text appears while you talk; DeepSeek, with the key you already use for the AI; or SiliconFlow) and transcribe audio files.
  - [Campus Card and payment-code sharing](/en/docs/manual/campus-card): Your Campus Card balance, payment code, top-ups, network fee and bath card in the Campus wallet plugin, and lending your payment code to a friend with Share payment code.
  - [Copilot](/en/docs/manual/copilot): Copilot lets the assistant operate other apps on your phone on a separate screen. A step-by-step setup guide for non-technical users — Developer options, Wireless debugging and the pairing code, accessibility, allowed apps and screenshots — with notes for each phone brand, and how to pause, stop and turn it all off again.
  - [Settings and your data](/en/docs/manual/settings): Everything on the Settings tab — account, AI provider, voice input, cloud, usage, plugins, reminders and alerts, appearance, language, time zone, haptics, exporting and erasing data, updates and the About page — and how the assistant changes settings for you in chat.
  - [Troubleshooting](/en/docs/manual/troubleshooting): Common problems with PKU harness and how to solve them — the campus network, verification codes at sign-in, AI provider and voice input errors, attached files, late reminders, app updates, the payment code and Copilot setup.
- Concepts
  - [Architecture](/en/docs/concepts/architecture): The PKU harness core is an agent loop, a design system and a set of host services. Every feature comes from a plugin, and all plugins use the same interface.
  - [Plugins](/en/docs/concepts/plugins): Plugins come in three kinds. Plugin documents (PLUGIN.md) are interpreted by the app and installed by link. Bundled TypeScript plugins ship inside the app. Remote plugins are MCP servers added by URL. All three share one registry, one permission system and one agent loop.
  - [Tools and effects](/en/docs/concepts/tools-and-effects): Tools are the only way a plugin offers features. Each tool has an id, a title, a description for the model, a zod input schema and exactly one effect (read, write, money or public).
  - [Permissions and consent](/en/docs/concepts/permissions): For each effect of each plugin, you decide whether the agent may act directly, must ask first, or may not act at all. Scheduled runs only read.
  - [Capabilities](/en/docs/concepts/capabilities): Plugins declare in `requires` what they need from the phone. If the phone can't provide it, the harness hides the plugin and tells the user why.
  - [Host services](/en/docs/concepts/host-services): Whenever a bundled plugin needs to do something outside itself, it goes through `HostServices`. The harness passes it in as `ctx.services` in tools and as `props.services` in screens and widgets.
  - [Generative UI](/en/docs/concepts/generative-ui): The agent describes a piece of UI in JSON, and the app shows it with native components, either in the chat (`ui.render`) or on the dashboard. A submitted form comes back to the agent as your next message.
  - [Dashboard widgets and data](/en/docs/concepts/dashboard): There are two kinds of dashboard widget. The agent builds some from a generative-UI spec plus bindings to read tools, and plugins provide others as native components. The host handles refreshing, with one cache shared by all of them.
  - [Scheduler and notifications](/en/docs/concepts/scheduler): One scheduler runs reminders, to-dos, class reminders and scheduled checks. Each job pairs a trigger (once, or a series with an end) with an action (notify, check or agent), and fires on the minute.
  - [Campus sessions and IAAA](/en/docs/concepts/campus-sessions): The harness keeps the campus credentials, signs in to each PKU service itself, and gives plugins the responses through `services.campus.request`. Plugins never see passwords or session tokens.
  - [Security model](/en/docs/concepts/security): Credentials stay on the phone. Tool results are data, never instructions, and third-party content taints the agent's turn. Anything that leaves the phone is declared and agreed to first.
- Build a plugin
  - [Build a plugin](/en/docs/build): How to choose between a PLUGIN.md document, a remote plugin and a bundled TypeScript plugin, which repositories to clone, and the order of work from your first tool to a marketplace listing.
  - [Your first plugin](/en/docs/build/quickstart): Write a PLUGIN.md plugin with one tool, test it against a recorded response, and share it as a link. The example is a cut-down version of the free-classrooms plugin.
  - [Declarative plugins (PLUGIN.md)](/en/docs/build/declarative-plugins): The plugin language. A plugin is a folder with a PLUGIN.md manifest, instructions for the assistant, tools written as YAML steps, and generative-UI widgets. The app interprets it and installs it from a link, with no code to build and no app release.
  - [Write a plugin with the AI](/en/docs/build/ai-authoring): Ask the assistant in the app to write a PLUGIN.md plugin with you. It reads the language reference, validates the draft, tries read-only tools against the live service, and opens the usual review sheet, where you decide whether to install.
  - [Quickstart: remote plugin](/en/docs/build/remote-plugin): Build a remote plugin, an MCP server that uses Streamable HTTP, from templates/remote-plugin. Run it locally, add it to the app, deploy it and register it in the marketplace.
  - [Bundled plugin](/en/docs/build/bundled-plugin): Write a plugin that ships inside the app with definePlugin. A complete example walks through tools, a data source, a screen, a Settings row, a widget, a command, English text and tests.
  - [Tools and schemas](/en/docs/build/tools): How to design tools the model uses well. Covers naming, descriptions, inputs in zod (bundled plugins) or JSON Schema (MCP), honest effects, results that are data, and states the user can recover from.
  - [UI contributions](/en/docs/build/ui): How a bundled plugin adds screens, Settings rows, tab content, dashboard widgets and slash commands through `contributes`, using the components the app passes in as HostUI.
  - [Languages (i18n)](/en/docs/build/i18n): How a bundled plugin provides Chinese and English. Manifest strings get English versions in `i18n.en`, screen and widget text goes in a `defineStrings` table, dates go through the SDK formatters, and text for the model stays untranslated.
  - [Testing](/en/docs/build/testing): How to test each kind of plugin. Replay recorded responses for plugin documents, unit-test parsers and pure logic with bun test, run the assistant end to end with the scripted mock model, and try remote plugins with the demo-canteen example.
  - [Porting from pkucli](/en/docs/build/porting-from-pkucli): pkucli is the protocol reference for PKU services. How to port endpoints, login steps and quirks from its Rust crates into a plugin, leave sign-in to the app, and credit the source file.
  - [Publishing](/en/docs/build/publishing): How a remote or bundled plugin reaches users. Remote plugins are listed in the marketplace registry. Bundled plugins are merged into pku-harness-plugins and reach phones as a signed over-the-air update or with the next app release.
- Marketplace
  - [Overview](/en/docs/marketplace): How the plugin marketplace finds, checks and lists plugins, what the badges mean, and how the app installs a plugin.
  - [Manifest reference](/en/docs/marketplace/manifest): How the marketplace reads PLUGIN.md (plugin language v1), where the scanner looks and what it checks, and the pku-harness.plugin.json format for remote MCP servers.
  - [Publishing](/en/docs/marketplace/publishing): Submit a repository, publish many plugins from one repository, update a listing by pushing, and remove a listing.
  - [Review policy & safety](/en/docs/marketplace/review): The rules every listed plugin follows, what maintainers check before marking a plugin verified, and how to report a plugin.
- SDK reference
  - [SDK reference](/en/docs/sdk): Where to get `@pku-harness/sdk` and what each module exports. The SDK holds the plugin types (definePlugin, tools, providers, HostServices, HostUI, capabilities), the plugin language interpreter and pure helpers for recurrence, schedules, timetables and formatting.
  - [plugin](/en/docs/sdk/plugin): Every type you use to define a plugin: definePlugin, defineTool, definePreference, PluginDef, ToolDef, ToolContext, effects, actors, capabilities, KV, turn info, data sources, preferences, model, speech and OCR providers, translations and legacy ids.
  - [HostServices](/en/docs/sdk/host-services): Signatures and behaviour of every host service a bundled plugin gets as ctx.services or props.services, including the settings registry and attached files, plus the job, widget catalog and ongoing-notification types.
  - [ui](/en/docs/sdk/ui): Types for plugin UI: the props that screens and widgets receive, HostUI (components, theme, navigation, haptics, live data hooks) and every contribution type (screens, Settings rows, tabs, widgets, commands).
  - [genui](/en/docs/sdk/genui): specSchema and the UISpec type, which describe generative UI specs, plus the SpecCheck result that services.genui.checkSpec returns.
  - [dashboard](/en/docs/sdk/dashboard): Data types for dashboard widgets. The Widget type, the Binding and WidgetSource schemas, and WidgetSize, also used by services.widgets.
  - [scheduler](/en/docs/sdk/scheduler): Types and helpers for the scheduler. Trigger, Action, Condition and Job with their zod schemas, the pure recurrence engine, the model-friendly ScheduleInput format, condition evaluation and the limits for unattended runs.
  - [notify](/en/docs/sdk/notify): The NotifyReadiness type and the deliveryBlocker function, for screens that check whether reminders and scheduled checks can arrive on time.
  - [campus](/en/docs/sdk/campus): Types for signed-in campus requests through the host (CampusService, CampusRequest, CampusResponse, multipart uploads, picked files), the sign-in status and the 手机令牌 (IAAA authenticator) code.
  - [cloud](/en/docs/sdk/cloud): The plugin side of PKU harness Cloud. CloudManifest, PluginCloud (store, channels, push, functions), Channel and its events, SecretLink, CloudStatus, CloudError and defineCloudFunction.
  - [timetable](/en/docs/sdk/timetable): The Course and Semester types for timetable data, and pure helpers that parse weeks expressions, find the teaching week, list the classes on a date, report class status and build class reminder triggers.
  - [todo](/en/docs/sdk/todo): The Todo and TodoInput types for to-do items, used by services.todos.
  - [format](/en/docs/sdk/format): Functions that format dates and times for the app's language, plus defineStrings for defining per-language string tables.
  - [pointer](/en/docs/sdk/pointer): setPointer writes a value into an object at a JSON Pointer path. The dashboard uses it to put binding results into widget state.
- Cloud
  - [PKU harness Cloud](/en/docs/cloud): PKU harness Cloud is an optional backend standard for plugins, covering storage, relay channels, push, files and server functions. The official instance, a self-hosted server or any conforming server can provide it. Data is end-to-end encrypted by default, and the cloud holds no campus identity.
  - [Plugin guide](/en/docs/cloud/plugin-guide): Use PKU harness Cloud from a bundled plugin. Declare the cloud manifest and disclosure, handle consent and availability, use the store and relay channels, and show share links safely.
  - [Security](/en/docs/cloud/security): How PKU harness Cloud keeps user data unreadable to the server. Device keypairs, proof-of-work registration, short-lived signed plugin tokens, XChaCha20-Poly1305 envelopes, share-link secrets in the URL fragment, claim-once channels and share-link redaction.
  - [Providers and self-hosting](/en/docs/cloud/providers): How to pick the official instance, a self-hosted reference server or any conforming URL, what a provider must implement, and how to run and configure the reference server.
  - [cloud-protocol package](/en/docs/cloud/protocol-package): @pku-harness/cloud-protocol: the zod wire schemas, path builders, envelope crypto, share-link helpers, proof of work and token challenge that the app, providers and viewer pages share.
  - API reference
    - [Meta](/en/docs/cloud/api/meta): Provider discovery. The host reads it when the user connects a provider and checks `protocol`, `services` and `limits`.
    - [Devices and auth](/en/docs/cloud/api/devices): A device's cloud identity is an Ed25519 signing key plus an X25519 box key, nothing else: no student ID, no name. Registration costs a proof of work; plugin tokens are minted from a signed challenge and live 10 minutes.
    - [Store](/en/docs/cloud/api/store): Key-value store namespaced by `(deviceId, plugin)` taken from the token, never from the path. Values are envelopes when the plugin declares `e2e`.
    - [Channels (owner)](/en/docs/cloud/api/channels): End-to-end encrypted relay channels opened by a device, used for live sharing with people who open a share link. The owner talks to its peers over a WebSocket; the server only forwards envelopes.
    - [Channels (peer)](/en/docs/cloud/api/peers): What a viewer (a web page or another app) calls after opening a share link `https://<provider>/s/<id>#k=<secret>`. The fragment `k` never reaches the server; the viewer derives `authKey` from it to join.
    - [Share links and pages](/en/docs/cloud/api/pages): Public redirects and static viewer pages for people without the app.
    - [Functions (planned)](/en/docs/cloud/api/functions): Server functions declared in a plugin's `CloudManifest.functions`. Planned for stage 6.
    - [Push (planned)](/en/docs/cloud/api/push): Push tokens and scheduled pushes with end-to-end encrypted payloads. Planned for stage 6.
- Ecosystem
  - [Repositories](/en/docs/ecosystem/repositories): 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.
  - [Roadmap](/en/docs/ecosystem/roadmap): The work on PKU harness that is done, in progress, planned or on hold, summarised from the app's plan and design documents.
  - [Contributing](/en/docs/ecosystem/contributing): How to contribute plugins, app changes, protocol notes and documentation to PKU harness, and the conventions, security rules and license that apply.
- [For AI agents](/en/docs/for-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.