PKU harnessSDK reference
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.
@pku-harness/sdk is the package you use to write a bundled plugin. It defines the object a plugin
exports and the interfaces the host gives to plugins, and it includes a set of pure helper
functions. This section lists its types and functions module by module, for you to look up while
you write a plugin.
A bundled plugin depends on @pku-harness/sdk and nothing else from us. Its only other imports are
zod, react and react-native. The SDK ships as TypeScript source in the plugins repository, and
the app's bundler, Metro, compiles it together with the app code. Its peer dependencies are
zod ^4 and react >=19.
Install
There is no npm package. The SDK lives in
pku-harness-plugins under packages/sdk, and
you work inside a checkout of that repository. Its bun workspace and tsconfig.json resolve
@pku-harness/sdk to packages/sdk/src.
git clone https://github.com/pkuinfo/pku-harness-plugins.git
cd pku-harness-plugins
bun installThe app pulls in the same repository as its git submodule plugins/, so a plugin you build there
also runs in the app (see Bundled plugin → Run it in the app).
import { definePlugin, defineTool, type PluginScreenProps } from '@pku-harness/sdk';Everything can be imported from the package root. You can also import the plugin language modules
one at a time as @pku-harness/sdk/lang/<module>.
Modules
The table lists each source file of the SDK, its reference page and its main exports.
| Module | Page | Main exports |
|---|---|---|
plugin.ts | plugin | definePlugin, defineTool, PluginDef, ToolDef, ToolContext, ToolEffect, Actor, Capability, KV, TurnInfo, DataSourceDef, ProviderDef, SpeechProviderDef, ToolAssessment, PluginTranslation, PluginLegacy, ContextInput, CONTEXT_MARK, Dynamic, resolveDynamic |
plugin.ts | host services | HostServices, JobInput, JobPatch, CheckResult, PluginInfo, ToolInfo, WidgetCatalogEntry, OngoingOptions, OngoingHandle |
settings.ts | plugin, host services | definePreference, PluginPreferenceDef, SettingContext, SettingsService, SettingInfo, SettingChange, SettingValue |
files.ts | host services | FilesService, FileInfo, FileReadResult, FileSearchResult |
speech.ts | plugin | openAITranscribe, cleanTranscript, speechErrorMessage |
ui.ts | ui | HostUI, HostComponents, HostTheme, LiveData, PluginScreenProps, PluginWidgetProps, Contributions, ScreenContribution, SettingsContribution, TabContribution, WidgetContribution, CommandContribution, AppLocale |
genui.ts | genui | specSchema, UISpec, SpecCheck |
dashboard.ts | dashboard | Widget, Binding, bindingSchema, WidgetSize, widgetSizeSchema, WidgetSource, widgetSourceSchema |
scheduler/* | scheduler | Trigger, Action, Condition, Job, JobRun, schemas, recurrence engine, ScheduleInput + toTrigger/summarize, evaluate, policy constants |
notify.ts | notify | NotifyReadiness, NotifyFixKind, deliveryBlocker |
campus.ts | campus | CampusService, CampusRequest, CampusResponse, CampusMultipart, PickedFile, CampusStatus, OtpCode, OtpStatus |
cloud.ts | cloud | CloudManifest, PluginCloud, Channel, SecretLink, CloudError, isCloudError, defineCloudFunction |
timetable.ts | timetable | Course, Semester, parseWeeks, formatWeeks, weekOf, classesOn, classStatus, courseReminderTrigger |
todo.ts | todo | Todo, TodoInput |
format.ts | format | defineStrings, Localized, formatClock, formatLocalDate, formatRelative, formatDay, formatCountdown, plural, … |
pointer.ts | pointer | setPointer |
lang/* | Declarative plugins | The PLUGIN.md interpreter: loadDocument, compilePlugin, runTool, manifestSchema, toolSchema, ABILITIES, LIMITS, LANGUAGE_REFERENCE, memoryKV, … |
Conventions
All SDK modules follow these conventions.
- Times are epoch milliseconds (milliseconds since 1 January 1970 UTC). Where a time is read as
a clock time, it is read in the device's local time zone. Strings that the model or a form sees
use the local format
"YYYY-MM-DD HH:mm". - Timetable weekdays use JavaScript numbering (0 = Sunday … 6 = Saturday), but
weekdayNametakes 1 = Monday … 7 = Sunday. - Schemas are zod 4 objects. The matching TypeScript types are derived from them with
z.infer. - Pure helpers import nothing from React Native, so they can be unit-tested directly with
bun test.
Review policy & safety
The rules every listed plugin follows, what maintainers check before marking a plugin verified, and how to report a plugin.
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.