PKU harnessSDK 参考
`@pku-harness/sdk` 的获取方式和各模块的导出。SDK 包含插件的类型定义（definePlugin、工具、模型服务商、HostServices、HostUI、能力需求）、插件语言的解释器，以及重复规则、定时、课表、格式化等纯函数。
@pku-harness/sdk 是编写内置插件时用到的开发包。它定义了插件要导出的对象和宿主提供给插件的接口，还附带一些常用的纯函数。本节逐个模块列出它的类型和函数，写插件时可以随时查阅。
内置插件从我们这里只依赖 @pku-harness/sdk，此外只引入 zod、react 和 react-native。SDK 以
TypeScript 源码的形式放在插件仓库里，由 App 的打包器 Metro 和 App 代码一起编译。它的对等依赖（peer dependency）是
zod ^4 和 react >=19。
安装
SDK 没有发布到 npm。它在
pku-harness-plugins 仓库的 packages/sdk
目录下。开发时，你直接在这个仓库的本地副本里工作，仓库的 bun workspace 和 tsconfig.json 会把
@pku-harness/sdk 解析到 packages/sdk/src。
git clone https://github.com/pkuinfo/pku-harness-plugins.git
cd pku-harness-plugins
bun installApp 把同一个仓库作为 git 子模块挂在 plugins/，所以你在这里写的插件也能直接在 App 里运行（见
内置插件 → 在 App 中运行）。
import { definePlugin, defineTool, type PluginScreenProps } from '@pku-harness/sdk';所有内容都可以从包的根入口引入。插件语言的各个模块也可以通过 @pku-harness/sdk/lang/<module> 单独引入。
模块
下表列出 SDK 的源码文件、对应的参考页面和主要导出。
| 模块 | 页面 | 主要导出 |
|---|---|---|
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 | 宿主服务 | HostServices、JobInput、JobPatch、CheckResult、PluginInfo、ToolInfo、WidgetCatalogEntry、OngoingOptions、OngoingHandle |
settings.ts | plugin、宿主服务 | definePreference、PluginPreferenceDef、SettingContext、SettingsService、SettingInfo、SettingChange、SettingValue |
files.ts | 宿主服务 | 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、各类 schema、重复规则引擎、ScheduleInput 及 toTrigger/summarize、evaluate、策略常量 |
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/* | 声明式插件 | PLUGIN.md 解释器：loadDocument、compilePlugin、runTool、manifestSchema、toolSchema、ABILITIES、LIMITS、LANGUAGE_REFERENCE、memoryKV 等 |
约定
SDK 的各个模块遵循下面几条共同的约定。
- 时间一律用 epoch 毫秒（自 1970 年 1 月 1 日 UTC 起的毫秒数）表示。需要当作钟点理解时，按设备的本地时区解释。给模型或表单看的字符串使用本地时间格式
"YYYY-MM-DD HH:mm"。 - 课表的星期沿用 JavaScript 的编号（0 = 周日 … 6 = 周六），但
weekdayName接收的是 1 = 周一 … 7 = 周日。 - Schema 都是 zod 4 对象，对应的 TypeScript 类型用
z.infer从 schema 推出。 - 纯函数不引入任何 React Native 模块，因此可以直接用
bun test做单元测试。