# 让 AI 帮你写插件 (/docs/build/ai-authoring)

> 在 App 里让助手和你一起写 PLUGIN.md 插件。它会查阅语言参考、校验草稿、对真实服务试运行只读工具，最后打开审核页，由你决定是否安装。

插件文档是纯文本，所以 App 里的 AI 助手可以和你一起写。比如你可以说「给体育馆预约网站做个插件」，最后会得到一个 `PLUGIN.md` 文件夹。你审核之后，可以安装它，也可以放弃。

你只需要 App 和一个配置好的 AI 模型，不需要电脑。不过，如果之后要发布插件，你还是会用到电脑。

助手通过一个名为 **Plugins**（id 为 `plugins`）的内置插件提供的工具（tool）完成这项工作。这些工具都不能在你确认之前安装任何东西。

## 相关工具

助手会用到五个工具。前四个只读取，最后一个负责为你打开审核页。

**`plugins.reference`**（read）用一页的篇幅返回完整的插件语言：清单、步骤、表达式、标准库、宿主能力、限制和一个示例。助手在准备编写或修改插件时才读取它。它不在每一轮的提示词里，所以不会占用其他对话的空间。

**`plugins.validate`**（read）用和 App 相同的加载器检查一个草稿文件夹。草稿以 `{ files: { "PLUGIN.md": "…", "tools/x.yaml": "…" } }` 的形式传入。草稿有效时，工具返回 `{ ok: true, id, version, tools, widgets, campus, network, abilities }`；否则返回 `{ ok: false, issues }`，每个问题都会标出所在的文件和步骤。

**`plugins.tryTool`**（read）在不安装草稿的前提下，真实运行草稿里的一个**只读**工具。它会发出真实请求，对草稿声明的服务使用你的校园登录状态，并给工具一个用完即弃的存储。`write`、`money` 和 `public` 效果的工具不能这样试运行。运行结果会被当作不可信数据。

**`plugins.source`**（read）返回已安装插件文档的文件，供助手解释、修复或复制。内置的 TypeScript 插件没有插件文档，所以这个工具对它们无效。

**`plugins.install`**（write）为一个链接（GitHub 文件夹或 `PLUGIN.md` 的 URL）或一份草稿（`{ files }`）打开 App 的审核页。它只负责打开审核页，装不装由你在审核页上决定。

Plugins 插件默认在运行 `write` 工具之前询问你。所以只要你没有改过这项授权方式，助手在打开审核页之前也会先征得你的同意。

## 编写插件的流程

<Steps>
<Step>

### 说出你的需求

说清楚插件要做什么。如果你知道它该用哪个页面或接口，也一起告诉助手。如果涉及校园服务，请明确指出：插件会用你的登录状态调用这个服务，永远看不到你的密码。

</Step>
<Step>

### 助手起草并校验

这些工具不在对话开始时提供：助手先用 `plugins.use` 加载 `plugins` 插件的编写工具。然后它读取 `plugins.reference`，再编写 `PLUGIN.md` 和各个工具文件。每次修改后，它都会调用 `plugins.validate`，并持续修正草稿，直到没有问题为止。

</Step>
<Step>

### 试运行只读工具

`plugins.tryTool` 会对真实服务运行只读工具。安装之前你就能看到实际结果，从而判断插件是否真的能用。

</Step>
<Step>

### 审核并安装

`plugins.install` 打开的审核页，和你通过安装链接看到的是同一个。它会显示插件是官方的还是社区的，能访问哪些校园服务、网站和 App 功能，以及每个工具和它的效果。在对话中写出的草稿算作社区插件。你点「安装」之前，什么都不会装上。

</Step>
</Steps>

## 修改已安装的插件

想修改已安装的插件文档，直接请助手修复或扩展它。助手会用 `plugins.source` 读取文件，修改后进行校验，再用新版本重新打开审核页。

如果你在对话里贴了一个插件链接，助手会用 `plugins.install { link }` 为它打开审核页。

## 分享你的作品

助手写出的草稿就是一个普通的插件文件夹。想分享它，或者让它能通过链接更新，就把文件夹放进一个公开的 GitHub 仓库，文件夹的 URL 就是它的安装链接（见[编写第一个插件](/docs/build/quickstart#share-it)）。发布之前，请在电脑上运行一遍[作者 CLI](/docs/build/declarative-plugins#test)，并补上录制好的测试。

## 安全

- 助手从不自行安装任何东西。`plugins.install` 只会打开审核页。
- `plugins.tryTool` 只运行只读工具，只能访问草稿声明的范围，也不会保留任何数据。
- 装好的草稿和其他社区插件遵守同样的规则：`write`、`money` 和 `public` 工具会先询问，结果作为数据交给 AI，不会被当作指令。

插件语言本身见[声明式插件](/docs/build/declarative-plugins)，各种授权方式怎样运作见[权限](/docs/concepts/permissions)。


# 内置插件 (/docs/build/bundled-plugin)

> 用 definePlugin 编写随 App 一起发布的插件。本页通过一个完整示例，依次介绍工具、数据源、页面、设置项、小组件、快捷指令、英文文字和测试。

内置插件（bundled plugin）是 `pku-harness-plugins/plugins/<id>` 下的一个 TypeScript 模块，只依赖 `@pku-harness/sdk`。它在手机上的 App 内部运行，只能通过「宿主服务」（host services）访问 App 的其他部分。宿主服务是 App 传给每个插件的一组对象，用于发起校园请求、发送通知、管理待办和定时任务等。和插件文档不同，内置插件可以添加原生界面。

内置插件只能随 App 版本发布，所以**请先开一个 issue**，说明插件做什么，以及为什么不能写成插件文档或远程插件。

<Callout title="大多数校园服务已经改用插件文档">
  TypeScript 用于 App 自身的功能：界面、看板、定时任务、待办、日程、课表、记忆、插件管理、模型服务商、身份验证器和付款码页面。插件语言暂时表达不了的接入也用 TypeScript。官方的校园接入 classrooms、campus-events、grades、canteen、shuttle 和 notices 都是随 App 内置的[插件文档](/docs/build/declarative-plugins)，其余的正在迁移。如果你的插件只是向校内或公开接口发请求、再提取数据，请改写 `PLUGIN.md`。如果它需要插件语言还没有的功能，请提议新增一项宿主能力（ability）。
</Callout>

本页从头编写一个完整的插件 `focus`。它记录专注时段（比如做一小时作业），并显示你今天一共专注了多少分钟。这个插件不调用任何外部服务，可以直接运行。如果要对接校园服务，就把其中的存储调用换成 `ctx.services.campus.request(...)`（见[校园会话](/docs/concepts/campus-sessions)）。

你需要 bun，并了解 TypeScript 和一些 React Native。第 1 到第 6 步都在你电脑上的插件仓库里完成，最后一节会在模拟器或手机上的 App 里运行这个插件。

## 目录结构

插件放在 `plugins/` 下自己的文件夹里。除此之外，你还要修改两个共用文件：内置插件列表 `plugins/index.ts`，以及 `registry/registry.json`。

<Files>
  <Folder name="pku-harness-plugins" defaultOpen>
    <Folder name="plugins" defaultOpen>
      <Folder name="focus" defaultOpen>
        <File name="package.json" />
        <Folder name="src" defaultOpen>
          <File name="index.ts" />
          <File name="store.ts" />
          <File name="store.test.ts" />
          <File name="strings.ts" />
          <File name="screen.tsx" />
          <File name="widget.tsx" />
        </Folder>
      </Folder>
      <File name="index.ts" />
    </Folder>
    <Folder name="registry">
      <File name="registry.json" />
    </Folder>
  </Folder>
</Files>

## 1. package.json

```json title="plugins/focus/package.json"
{
  "name": "@pku-harness/plugin-focus",
  "private": true,
  "version": "0.1.0",
  "description": "Focus sessions and today's total, on the device",
  "type": "module",
  "main": "src/index.ts",
  "license": "MIT",
  "pkuHarness": { "builtin": true },
  "peerDependencies": {
    "@pku-harness/sdk": "*",
    "zod": "^4.0.0",
    "react": "*",
    "react-native": "*"
  }
}
```

每个插件都是插件工作区里的一个包，工作区会把 `@pku-harness/sdk` 解析到 `packages/sdk/src`。所有包都是私有的，不会发布到 npm。依赖写成 peer dependencies，因为它们由 App 提供。添加其他运行时依赖之前，请先和我们商量，因为所有代码都会打进 App 的安装包，让它变大。

## 2. 先写纯逻辑

先写不依赖 React Native 的逻辑，放在普通模块里。导入了 `react-native` 的模块，不做 mock 的话 `bun test` 无法加载，所以把逻辑分开写，测试起来就很方便。

这里的 `store.ts` 把专注时段保存在插件的键值（KV）存储里，并计算今天的分钟数。`minutesOn` 是一个纯函数：它把时间 `now` 当作参数传入，而不是自己读取时钟，所以测试可以传入任意时间。

```ts title="plugins/focus/src/store.ts"
import type { KV } from '@pku-harness/sdk';

export type Session = { id: string; label: string; startedAt: number; endedAt: number | null };

const KEY = 'sessions';

export async function loadSessions(kv: KV): Promise<Session[]> {
  return (await kv.get<Session[]>(KEY)) ?? [];
}

export async function saveSessions(kv: KV, list: Session[]): Promise<void> {
  await kv.set(KEY, list.slice(-500));
}

/** `now` 所在本地日期的专注分钟数，进行中的专注算到 `now` 为止。纯函数。 */
export function minutesOn(list: Session[], now: number): number {
  const d = new Date(now);
  const start = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
  const end = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
  let ms = 0;
  for (const s of list) {
    const a = Math.max(s.startedAt, start);
    const b = Math.min(s.endedAt ?? now, end);
    if (b > a) ms += b - a;
  }
  return Math.round(ms / 60_000);
}

export const running = (list: Session[]) => list.find((s) => s.endedAt == null) ?? null;
```

## 3. 插件本体

`src/index.ts` 把各部分组合起来。它定义了三个工具（`start`、`stop` 和 `today`）、一个供小组件使用的数据源，以及插件添加到 App 里的页面、设置项、小组件和快捷指令。

```ts title="plugins/focus/src/index.ts"
import { definePlugin, defineTool } from '@pku-harness/sdk';
import { z } from 'zod';

import { FocusScreen } from './screen';
import { loadSessions, minutesOn, running, saveSessions } from './store';
import { FocusWidget } from './widget';

/** 专注：开始、结束专注时段，查看今天的总时长。所有数据都留在设备上。 */
export const focusPlugin = definePlugin({
  id: 'focus',
  name: '专注',
  description: '记录专注时段，查看今天专注了多久。',
  version: '0.1.0',
  icon: 'clock',
  requires: [],
  scopes: [],
  i18n: {
    en: {
      name: 'Focus',
      description: 'Track focus sessions and see how long you focused today.',
      tools: { start: { title: 'Start focusing' }, stop: { title: 'Stop focusing' }, today: { title: 'Focus today' } },
      widgets: { today: { title: 'Focus today', description: 'Minutes focused today and the running session, if any.' } },
      screens: { main: { title: 'Focus' } },
      settings: { main: { title: 'Focus', subtitle: 'Focus sessions' } },
      commands: { focus: { description: 'Open focus sessions', aliases: ['pomodoro'] } },
      dataSources: { today: { title: 'Focus today' } },
    },
  },
  instructions: `专注记录：用户说"开始学习/专注""我学完了"时用 focus__start / focus__stop；问"今天学了多久"时用 focus__today。`,
  dataSources: {
    today: { title: '今日专注', tool: 'today', ttlMs: 60_000 },
  },
  contributes: {
    screens: { main: { title: '专注', component: FocusScreen } },
    settings: [{ screen: 'main', title: '专注', subtitle: '专注时段', icon: 'clock' }],
    widgets: {
      today: {
        title: '今日专注',
        description: '今天专注的分钟数，以及正在进行的专注。',
        sizes: ['sm', 'md', 'lg'],
        defaultSize: 'sm',
        component: FocusWidget,
      },
    },
    commands: {
      focus: { description: '打开专注', aliases: ['专注', '番茄钟'], run: (_input, { navigate }) => navigate('/p/focus/main') },
    },
  },
  tools: {
    start: defineTool({
      title: '开始专注',
      description: 'Start a focus session now. Fails if one is already running (stop it first).',
      input: z.object({ label: z.string().trim().max(40).optional().describe('what the user focuses on, e.g. "高数作业"') }),
      effect: 'write',
      execute: async ({ label }, ctx) => {
        const list = await loadSessions(ctx.kv);
        if (running(list)) throw new Error('已经有一个正在进行的专注，请先结束它');
        const session = { id: Date.now().toString(36), label: label ?? '', startedAt: Date.now(), endedAt: null };
        await saveSessions(ctx.kv, [...list, session]);
        return { started: true, label: session.label };
      },
    }),
    stop: defineTool({
      title: '结束专注',
      description: 'Stop the running focus session. Returns its length in minutes.',
      input: z.object({}),
      effect: 'write',
      execute: async (_input, ctx) => {
        const list = await loadSessions(ctx.kv);
        const current = running(list);
        if (!current) return { stopped: false, reason: 'nothing running' };
        const now = Date.now();
        await saveSessions(ctx.kv, list.map((s) => (s.id === current.id ? { ...s, endedAt: now } : s)));
        return { stopped: true, minutes: Math.round((now - current.startedAt) / 60_000) };
      },
    }),
    today: defineTool({
      title: '今日专注',
      description: 'Minutes focused today (device-local day), including the running session, and the running session if any.',
      input: z.object({}),
      effect: 'read',
      execute: async (_input, ctx) => {
        const list = await loadSessions(ctx.kv);
        const current = running(list);
        return { minutes: minutesOn(list, Date.now()), running: current ? { label: current.label, startedAt: current.startedAt } : null };
      },
    }),
  },
});
```

`definePlugin` 接收一个描述整个插件的对象，其中各部分的作用如下：

| 字段 | 作用 |
| --- | --- |
| `id` | 注册表 id，格式为 `^[a-z0-9][a-z0-9-]{1,40}$`。工具 id 会是 `focus.start`，模型看到的名字是 `focus__start`。 |
| `name`、`description`、工具的 `title` | 中文，展示给用户。英文写在 `i18n.en` 里。 |
| `instructions` | 加在助手的系统提示词（system prompt）里，每次请求都会发送，所以要写得短。提到工具时用模型名。 |
| `dataSources` | 适合给小组件和定时检查用的读取工具，带缓存时长。 |
| `contributes.screens` | 挂载在 `/p/focus/main`（`presentation: 'modal'` 时为 `/m/focus/<screen>`）。 |
| `contributes.settings` | 设置页里的一行，点开进入某个页面。 |
| `contributes.widgets` | 一个原生的看板小组件（widget），助手会读取它的 `description`。 |
| `contributes.commands` | 聊天输入框里的 `/focus` 快捷指令（这里是一个本地操作）。 |
| `tools` | 插件的 API：每个工具一种效果（effect），用 zod 定义输入，返回数据。 |

## 4. 界面

页面和小组件通过 `host` 属性拿到 App 的组件，从不直接从 App 导入。这样插件就不依赖 App 的代码，App 改版后插件照样能用。页面、小组件和字符串表的写法如下：

```tsx title="plugins/focus/src/screen.tsx"
import type { PluginScreenProps } from '@pku-harness/sdk';

import { strings } from './strings';

type Today = { minutes: number; running: { label: string; startedAt: number } | null };

/** 开始和结束专注。以用户身份调用插件自己的工具。 */
export function FocusScreen({ host, invoke }: PluginScreenProps) {
  const { Screen, Stat, Button, Column, Text } = host.components;
  const s = strings[host.useLocale()];
  const data = host.useToolData<Today>('focus.today', {}, { ttlMinutes: 1 });
  const active = data.value?.running ?? null;

  const toggle = async () => {
    host.haptics.tap();
    await invoke(active ? 'focus.stop' : 'focus.start', {});
    await data.refresh();
  };

  return (
    <Screen title={s.today}>
      <Column gap="lg">
        <Stat label={s.today} value={data.value?.minutes ?? null} suffix={host.useLocale() === 'en' ? ' min' : ' 分钟'} icon="clock" />
        <Text tone="muted">{active ? s.running(active.label) : s.idle}</Text>
        <Button title={active ? s.stop : s.start} variant={active ? 'secondary' : 'primary'} loading={data.fetching} onPress={() => void toggle()} />
      </Column>
    </Screen>
  );
}
```

```tsx title="plugins/focus/src/widget.tsx"
import type { PluginWidgetProps } from '@pku-harness/sdk';
import { View } from 'react-native';

import { strings } from './strings';

type Today = { minutes: number; running: { label: string; startedAt: number } | null };

/** 今天的专注分钟数；由宿主负责刷新（小组件里不要轮询）。 */
export function FocusWidget({ host, size }: PluginWidgetProps) {
  const { Text, Skeleton } = host.components;
  const t = host.useTheme();
  const s = strings[host.useLocale()];
  const data = host.useToolData<Today>('focus.today', {}, { ttlMinutes: 1 });
  if (data.status === 'loading') return <Skeleton width="50%" height={28} />;
  if (!data.value) return <Text tone="muted">{data.error ?? ''}</Text>;
  return (
    <View style={{ gap: t.spacing.xs }}>
      {size === 'sm' ? (
        <Text variant="micro" tone="faint">
          {s.today}
        </Text>
      ) : null}
      <Text variant={size === 'lg' ? 'numberXL' : 'numberL'}>{s.minutes(data.value.minutes)}</Text>
      <Text variant="caption" tone={data.value.running ? 'accent' : 'muted'} numberOfLines={1}>
        {data.value.running ? s.running(data.value.running.label) : s.idle}
      </Text>
    </View>
  );
}
```

```ts title="plugins/focus/src/strings.ts"
import { defineStrings } from '@pku-harness/sdk';

type Strings = {
  today: string;
  minutes: (n: number) => string;
  start: string;
  stop: string;
  running: (label: string) => string;
  idle: string;
};

export const strings = defineStrings<Strings>({
  'zh-Hans': {
    today: '今日专注',
    minutes: (n) => `${n} 分钟`,
    start: '开始专注',
    stop: '结束',
    running: (label) => (label ? `正在专注：${label}` : '正在专注'),
    idle: '还没有开始',
  },
  en: {
    today: 'Focus today',
    minutes: (n) => (n === 1 ? '1 min' : `${n} min`),
    start: 'Start focusing',
    stop: 'Stop',
    running: (label) => (label ? `Focusing on ${label}` : 'Focusing'),
    idle: 'Not started yet',
  },
});
```

页面用 `invoke` 调用插件自己的工具。`invoke` 以**用户身份**（`actor: 'user'`）运行工具：输入照常校验，权限照常生效，但不会弹出授权确认，因为用户刚刚亲手点了按钮。执行修改操作之后，要刷新页面上正在显示的实时查询，就像 `toggle` 里调用 `data.refresh()` 那样。

## 5. 测试

测试覆盖第 2 步的纯函数 `minutesOn`。由于它把 `now` 当作参数，每个测试都可以固定时间。

```ts title="plugins/focus/src/store.test.ts"
import { describe, expect, test } from 'bun:test';

import { minutesOn, type Session } from './store';

const at = (h: number, m = 0) => new Date(2026, 9, 21, h, m).getTime();

describe('minutesOn', () => {
  test('sums finished and running sessions of the day', () => {
    const list: Session[] = [
      { id: 'a', label: '高数', startedAt: at(8), endedAt: at(8, 50) },
      { id: 'b', label: '英语', startedAt: at(10), endedAt: null },
    ];
    expect(minutesOn(list, at(10, 30))).toBe(80);
  });

  test('cuts a session that started yesterday at midnight', () => {
    const list: Session[] = [{ id: 'c', label: '', startedAt: at(0) - 30 * 60_000, endedAt: at(0, 20) }];
    expect(minutesOn(list, at(12))).toBe(20);
  });
});
```

## 6. 注册插件

App 只加载 `plugins/index.ts` 里列出的插件，所以要把你的插件加进这个列表。列表的顺序也就是插件在设置页和系统提示词里的顺序：

```ts title="plugins/index.ts"
import { focusPlugin } from './focus/src';

export const builtinPlugins: PluginDef[] = [
  // …
  focusPlugin,
];
```

然后在 `registry/registry.json` 里加一条记录，插件市场展示的就是这份列表。图标不能和其他条目重复：

```json
{
  "id": "focus",
  "name": "专注",
  "description": "记录专注时段，查看今天专注了多久。",
  "author": "your-github-name",
  "source": "https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/focus",
  "kind": "builtin",
  "icon": "clock",
  "requires": [],
  "scopes": [],
  "tags": []
}
```

最后，运行和持续集成（CI）相同的检查：

```bash
bun test                          # 你的测试，以及多语言覆盖测试（plugins/i18n.test.ts）
bunx tsc --noEmit -p .            # 对 SDK 和插件做类型检查
bun scripts/validate-registry.ts  # 检查 schema、id 和图标是否唯一、内置插件是否存在
```

## 在 App 里运行

App 以 git 子模块 `plugins/` 的形式引入 `pku-harness-plugins`，并从这里加载 `@pku-harness/sdk` 和内置插件。所以要在 App 里看到你的插件，就要在这个子模块里开发。

<Steps>
<Step>

### 连同子模块克隆 App

```bash
git clone --recurse-submodules https://github.com/pkuinfo/pku-harness.git
cd pku-harness
bun install
```

</Step>
<Step>

### 在 `plugins/` 里开发

创建 `plugins/plugins/focus/`，也就是子模块里的 `plugins/` 目录。在 `plugins/plugins/index.ts` 里注册插件，然后运行 App：

```bash
bun run android           # 在模拟器或设备上运行开发版
# 或者，已经装好开发版时：
bunx expo start --dev-client
```

Metro 是 React Native 的 JavaScript 打包工具，你保存文件后它会自动重新加载 App。要推送分支，就把子模块的远程仓库指向你的 fork（`git -C plugins remote add …`）。pull request 提交到 `pku-harness-plugins`，之后再由 App 仓库更新子模块指向的提交。

</Step>
<Step>

### 试一试

有四种方式可以试用：打开「设置 → 专注」；在看板的小组件库里添加小组件；在对话里输入 `/focus`；或者对助手说「开始专注高数作业」。

</Step>
</Steps>

如果你没有模型的 API key，可以用[模拟模型](/docs/build/testing#mock-model)。在设备上，有一种只在开发版里可用的深链接，可以直接运行某个工具：`pkuharness://dev?tool=focus.today&input={}`。

## 规则

- **必须**只从 `@pku-harness/sdk`、`zod`、`react` 和 `react-native` 导入，外加你自己的文件和 `plugins/shared/`（内置插件之间共享的代码，比如 `campus-card.ts`）。不能导入 App 的代码，也不能导入其他插件目录里的文件。
- **必须**遵守[工具规则](/docs/build/tools)、[多语言规则](/docs/build/i18n)和[能力需求规则](/docs/concepts/capabilities)。
- **必须**用 `host.useToolData` 加载小组件和页面的数据，不要轮询。
- **应当**让 `instructions` 和 `context` 尽量短，因为每次请求都要为它们消耗 token。


# 声明式插件（PLUGIN.md） (/docs/build/declarative-plugins)

> 插件语言的说明。插件是一个文件夹，包含 PLUGIN.md 清单、给助手的说明、用 YAML 步骤写的工具和生成式界面小组件。App 解释执行它，通过链接安装，不需要构建代码，也不需要 App 发版。

本页介绍插件语言：插件文件夹怎样组织，清单里写什么，工具怎样用步骤和表达式写成，以及插件怎样安装和更新。如果你还没写过插件，请先完成[快速上手](/docs/build/quickstart)。

<Callout title="规范 v1">
  语言规范见 [`docs/PLUGIN-LANGUAGE.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/PLUGIN-LANGUAGE.md)（规范版本 1），实现位于 `@pku-harness/sdk` 的 `lang/` 目录，其中有 schema、解释器、宿主能力和加载器。本页是规范的摘要。两者不一致时，App 以 SDK 里的 [`schema.ts`](https://github.com/pkuinfo/pku-harness-plugins/blob/main/packages/sdk/src/lang/schema.ts) 和 [`abilities.ts`](https://github.com/pkuinfo/pku-harness-plugins/blob/main/packages/sdk/src/lang/abilities.ts) 为准。
</Callout>

声明式插件是一个由文本文件组成的文件夹，可以作为链接分享。它在 PKU harness 里的作用，和 `SKILL.md` 文件夹在 AI Agent 里的作用相同。App 读取这个文件夹，用一个小而安全的解释器执行其中声明的步骤。App 从不下载或运行插件代码，因此发布新插件或更新插件既不需要 App 发版，也不需要服务器。

如果一项任务只是向校园网站或公开网站发几个请求，再提取一些数据，就适合写成声明式插件。例如空闲教室、食堂人流和营业时间、班车时刻表、成绩、校园活动和通知。

有些事情无法用插件语言安全地表达，比如读取短信验证码、添加待办。App 把这类功能做成「宿主能力」（host ability）：它们内置在 App 里，任何插件声明之后都可以调用。如果你有自己的服务器，请改写[远程插件](/docs/build/remote-plugin)。你也可以在 App 里[让 AI 帮你写插件](/docs/build/ai-authoring)。

## 官方插件文档

[`pku-harness-plugins/plugins`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins) 里的官方校园接入都是插件文档，每个都附有录制好的测试，很适合当作范例来读。它们分别演示了插件语言的不同部分：

- [`classrooms`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/classrooms) 用 `each` 并行发出公开请求，在 `constants` 里定义别名，并提供一个看板小组件。
- [`campus-events`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/campus-events) 通过 `verify.treehole` 读取树洞日历。
- [`grades`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/grades) 用 `verify.treehole` 和 `verify.treeholeSendCode` 处理二次验证，验证方式可以是短信，也可以是手机令牌（北大统一身份认证 IAAA 的身份验证器）。
- [`canteen`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/canteen) 使用 `shared:` 文件，把结果缓存在键值（KV）存储里、请求失败时退回旧数据，并读取含合并单元格的 HTML 表格。
- [`shuttle`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/shuttle) 完全不联网：时刻表直接作为数据写在插件里，小组件每分钟刷新一次。
- [`notices`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/notices) 访问通配域名（`*.pku.edu.cn`）和微信公众号文章。它在 `shared:` 里维护一张来源表，按页面缓存到 KV 并在失败时退回旧数据，用 `untrusted: true` 标记返回第三方文本的工具，还提供一条快捷指令。

App 内置了这些插件文档，并像其他插件一样从各自的 GitHub 链接更新。所以修复其中某个解析器，不需要 App 发版。

## 目录结构

```
classrooms/
  PLUGIN.md              # 清单（YAML frontmatter）+ 给助手的说明（Markdown）
  tools/free.yaml        # 每个文件一个工具（也可以直接写在 frontmatter 里）
  shared.yaml            # 可选：所有工具共用的 constants 和 functions
  widgets/overview.json  # 看板小组件：生成式界面 spec + 数据绑定
  screens/…json          # 整页的生成式界面
  tests/free.yaml        # 供 CLI 和 CI 使用的录制响应；App 从不拉取
  README.md, assets/     # 给人和插件市场看；App 会忽略
```

- 一个文件夹放一个插件，一个仓库可以放很多个。在插件市场里，插件用 `owner/repo/path` 标识。
- App 只加载 **frontmatter 里写明的文件**。路径必须是相对路径，不能包含 `..`。由于 App 从不列出文件夹内容，插件放在任何静态托管上都可以：GitHub、gist 或你自己的服务器。
- 文件必须是 UTF-8 文本。App 加载的文件加起来不能超过 **512 KB**。

## 清单

清单就是 `PLUGIN.md` 顶部的 YAML frontmatter。下面是一个简化版 `classrooms` 插件的清单：

```md title="classrooms/PLUGIN.md"
---
spec: 1
id: classrooms
name: 空闲教室
description: 查询各教学楼今天、明天、后天的空闲教室。
version: 1.2.0
author: pkuinfo
icon: location
network: [portal.pku.edu.cn]
tools:
  free: tools/free.yaml
widgets:
  overview: widgets/overview.json
dataSources:
  overview: { tool: free, args: { day: today }, ttl: 30m }
i18n:
  en:
    name: Free classrooms
    description: Free classrooms in each teaching building.
    tools: { free: { title: Free classrooms, summary: Find free classrooms in a building } }
---

Use `free` when the user asks where to study or which rooms are free. Periods are 1–12
(1 = 08:00). Answer with the building and room, and the free period ranges.
```

必填字段有六个：`spec: 1`、`id`、`name`、`description`（4 到 200 个字符）、`version`（语义化版本号，如 `1.2.0`）和 `author`。

### 插件声明的范围

有四个字段最重要，因为同学们在安装前会在审核页上看到它们。

`campus` 列出插件可以**带着用户的登录状态**调用的校园服务，名称有 `card`、`its`、`treehole`、`blackboard`、`elective`、`cwfw`、`cwpay`、`bdkj`、`library`、`library-space` 等。这些请求由 App 自己签发，所以插件永远看不到密码、cookie 或 token。

`network` 列出插件可以访问的公开域名，写成 `example.com` 或 `*.example.com` 的形式，只允许 HTTPS。

`abilities` 列出插件用到的[宿主能力](#host-abilities)：`verify`、`otp`、`todos`、`timetable`、`scheduler`、`browser`、`campusPage`、`sms`、`files`、`crypto` 和 `cloud`。

`tools` 写明每个工具所在的文件，每个工具再各自声明 `effect`：`read`、`write`、`money` 或 `public`。

### 可选字段

- `shared` 指向一个 YAML 文件，其中的 `constants` 和 `functions` 所有工具都能使用。如果工具自己定义了同名项，以工具自己的为准。
- `dataSources`、`widgets` 和 `screens` 用来添加实时数据和生成式界面。
- `settings` 和 `commands` 用来添加设置项和快捷指令。
- `defaultModes` 设置每种效果的初始授权方式。
- `i18n` 放英文文字，可以翻译名称、简介、说明，以及每个工具的 `title` 和 `summary`（`i18n.en.tools.<name>`）。
- `remote: { mcp, auth }` 用 `PLUGIN.md` 描述一个远程 MCP 服务器。
- `cloud` 声明插件对 PKU harness Cloud 的使用，包括 `cloud.disclosure`；`server` 声明服务端函数（[见下文](#server-functions)）。

`requires` 不用写，它由 `campus`、`network`、`cloud` 和 `server` 自动推导。每个字段的详细说明，以及插件市场会检查什么，见[清单参考](/docs/marketplace/manifest)。

### 给助手的说明

**Markdown 正文**会作为插件说明发给模型。请写得简短：什么问题用哪个工具，返回的数字分别表示什么。在正文里，工具要写成 `<id>__<tool>` 的形式，例如 `classrooms__free`，因为模型看到的就是这个名字。

## 工具

工具（tool）是一份数据，由以下几部分组成：

- `title`：工具的名字，显示给用户，不超过 60 个字符。
- `summary`（可选）：给人看的一行说明，不超过 80 个字符，显示在安装审核页和插件市场插件页的工具名下方。英文版写在 `i18n.en.tools.<name>.summary`；不写的话，App 不会给使用英文界面的用户显示这一行。
- `description`：只给模型看，从不显示给用户。
- `effect`：`read`、`write`、`money` 或 `public`，必须如实声明。
- `input`：带类型的输入字段。
- `constants` 和 `functions`（可选）：这个工具自己用的常量和辅助表达式。
- `steps`：按顺序执行的请求和数据转换。
- `return`：组装结果的表达式。

还有两个标记会改变 App 对待工具的方式。`untrusted: true` 表示工具的结果里含有第三方文本，比如帖子或文章。`userOnly: true` 表示只有用户亲手点击才能运行这个工具，助手不能调用。

```yaml title="tools/free.yaml（节选）"
title: 空闲教室
summary: 查某栋楼哪些教室空着
description: Free rooms in one building (or all) for today, tomorrow or the day after.
effect: read
input:
  building: { type: string, optional: true, trim: true, description: 'e.g. 二教, 理教' }
  day: { enum: [today, tomorrow, dayAfter], default: today }
constants:
  DAY_QUERY: { today: 今天, tomorrow: 明天, dayAfter: 后天 }
steps:
  - let: page
    request:
      url: https://portal.pku.edu.cn/publicQuery/classroomQuery/retrClassRoomFree.do
      query: { buildingName: '${input.building ?? "二教"}', time: '${DAY_QUERY[input.day]}' }
      headers: { referer: 'https://portal.pku.edu.cn/publicQuery/' }
    as: json
  - check: page.success
    error: 空闲教室查询未成功
return: "page.rows.map(r => ({ room: r.room, seats: num(r.cap, 0) }))"
```

每个**输入字段**的格式是 `{ type, enum?, default?, optional?, description?, min?, max?, pattern?, trim?, items? }`。`type` 取 `string`、`number`、`integer`、`boolean`、`array`、`object` 之一。`trim: true` 会在校验前去掉字符串首尾的空白。App 在任何步骤运行之前就会校验全部输入，所以步骤里可以放心使用它们。

### 步骤

每个步骤只做一件事，可以用 `let: name` 把结果绑定到一个名字上。后面的步骤和 `return` 能使用所有已绑定的名字，以及 `input`、`constants`、`functions` 和 `now`。

| 步骤 | 作用 |
| --- | --- |
| `{ let, value: expr }` | 绑定一个表达式的值。 |
| `{ let, request, as? }` | 发出一个 HTTP 请求。 |
| `{ let, each, concurrency?, request \| steps \| value }` | 对列表中的每一项执行一次。 |
| `{ let, paginate: { request, next, items, max } }` | 逐页重复同一个请求。 |
| `{ let, extract: { from, each, fields }, limit? }` | 从 HTML 中提取条目。 |
| `{ if, then, else? }` | 条件分支。 |
| `{ check, error }` | 条件不成立时带着信息失败。 |
| `{ try, catch }` | 捕获错误；`catch` 里可以使用 `error`。 |
| `{ let?, kv: get \| set \| delete, key, value?, ttl? }` | 读写插件自己的存储。 |
| `{ let, cache: { key, ttl, staleOnError? }, steps }` | 把内部步骤的结果缓存到 KV。 |
| `{ let?, call: <tool>, input }` | 调用同一插件的另一个工具。 |
| `{ let?, ability: <group>.<op>, args }` | 调用一项[宿主能力](#host-abilities)。 |

其中几种步骤需要多说几句。

**请求**有两种写法：用 `campus: <service>` 指定校园服务，再写该服务上的路径；或者写一个属于 `network` 域名的公开 `https` URL。`as` 决定怎样读取回复，可以是 `json`、`text`、`html` 或 `response`。用 `response` 时，无论状态码是多少，都会得到 `{ status, url, headers, text }`；其他几种写法在状态码不是 2xx 时会失败。

**`each`** 遍历的列表最多 50 项，同时运行 1 到 4 个，其中可以使用 `item` 和 `index`。**`paginate`** 在 `next` 不为 null 时重复请求，最多 30 页。

**`extract`** 用 CSS 选择器从 HTML 中选出元素。每个字段的值可以经过管道处理，例如 `text`、`attr href`、`url`、`num`、`date` 和 `match <regex>`。

每次运行都有固定的上限：200 个步骤，60 个请求（同时最多 4 个），60 秒，单个响应 2 MB，结果 1 MB，100,000 次表达式运算，每个插件 256 KB 的 KV 存储。插件语言里没有无界循环，没有 `eval`，也没有 JavaScript。

### 表达式

有些字段写的是「表达式」：`value`、`each`、`if`、`check`、`return`、`next`、`items`、`from`，以及 `call` 的 input、`ability` 的 args 和 `functions` 的函数体。表达式只能有一个，语法是 JavaScript 的一个安全子集。可以使用字面量、`.` `?.` `[]`、算术运算、严格的 `==` 和 `!=`、`&& || ?? !`、`a ? b : c`，以及作为参数的箭头函数。不能赋值，不能用 `new`，也访问不到任何全局变量。使用未绑定的名字会报错。

其余的字符串都是「模板」。模板里的 `${expr}` 会被替换成表达式的值。如果整个模板正好就是一个 `${expr}`，值会保留原来的类型，不会变成字符串。

标准库包括列表（`map`、`filter`、`sortBy`、`groupBy`、`sum`、`reduce` 等）、对象、字符串、数字、北京时间的日期、URL、JSON 和 HTML（`html`、`select`、`first`、`tableRows`、`htmlText` 等）。完整列表见规范 §6.2，在 App 里可以查看 `plugins.reference`。

下面几点经常让人出错：

- **正则表达式写成字符串。** 每个正则只编译一次，长度有上限。需要忽略大小写之类的匹配时，在模式开头写内联标志，例如 `'(?i)^yanyuan'`。支持的标志有 `i`、`m`、`s` 和 `u`。
- **字符串转义。** `\\`、`\'`、`\"`、`\n`、`\t` 和 `\r` 的含义和 JavaScript 相同。其他转义**会保留反斜杠**，所以 `'\d+'` 就是正则 `\d+`。这里有意与 JavaScript 不同，目的是让模式经过 YAML 之后保持原样。不过，正则仍然建议写在单引号 YAML 字符串或 `|` 块里。
- **注释。** 表达式里可以使用 `// …` 和 `/* … */`。
- **合并单元格。** `tableRows(node, { header: true })` 为每一行返回一个对象，键是表头文字，rowspan 和 colspan 都已展开。`tableRows(node, { cells: true })` 返回由 `{ text, row, col, rowspan, colspan, id }` 组成的网格行，同一个合并单元格覆盖的所有格子 `id` 相同。

<Callout type="warn" title="YAML 里表达式的引号">
  如果表达式含有 `: `，或者以 `{`、`[`、`'`、`"` 开头，就要加引号，或者写成块标量（`return: |`）。不加引号时，YAML 会把它当成映射或列表。遇到这种情况，校验器会指出出错的行。
</Callout>

### 返回结果

返回普通的 JSON，不要返回指令。App 能识别几种结果格式：

- `{ status: 'verification_required', kind, methods, message }` 表示需要用户提供验证码。
- `{ status: 'needs_input', fields, message }` 表示工具还需要用户补充输入。
- `{ items, hasMore, truncated }` 是列表的格式。

## 宿主能力

宿主能力是 App 提供的功能。插件在 `abilities` 里列出对应的分组后，就可以使用它。每个操作的效果是固定的，调用它的工具声明的效果**至少**要达到这一级。例如，`read` 工具不能调用 `todos.add`，因为它是 `write` 操作。不在下表里的名字一律拒绝。

插件不能自己添加宿主能力。新的宿主能力只能加进 App 本身，在那里统一审核一次，之后所有插件都能使用。

| 宿主能力 | 操作（效果） |
| --- | --- |
| `verify` | `treehole { request, code?, via?: sms \| otp, kind?: login \| course }`（read），`treeholeSendCode { kind? }`（write） |
| `otp` | `code`（read）：手机令牌当前的验证码，没有则为 null |
| `todos` | `list`（read）；`add`、`update`、`setDone`、`remove`（write） |
| `timetable` | `get`（read）；`upsert`、`remove`（write） |
| `scheduler` | `list`（read）；`create`、`update`、`remove`（write） |
| `browser` | `open { url }`（read）：在 App 外打开一个 https URL |
| `campusPage` | `open { service }`（read）：以已登录状态打开校园网站 |
| `sms` | `awaitCode`（read）：用户允许读取一条短信后，一键填入短信验证码 |
| `files` | `pick { types?, multiple? }`（read）：让用户选择文件 |
| `crypto` | `sha256 { text }`（read） |
| `cloud` | `call { fn, input }`（read）：调用本插件的某个[服务端函数](#server-functions) |

调用宿主能力的步骤写法如下：

```yaml title="调用宿主能力的步骤"
- let: data
  ability: verify.treehole
  args: "{ request: { url: '/chapi/api/course/score_v2' }, code: input.code, via: input.method ?? 'sms' }"
```

### 二次验证（`verify`）

树洞有时会先要求额外验证才肯回答：登录时要短信验证码，读取课程数据前要一个令牌。处理这些需要按正确的顺序发好几个请求。`verify.treehole` 把一次树洞请求包装起来，替你完成这些工作，插件就不用自己实现。它的行为如下：

- 如果传了 `code`，它会先提交验证码，再发出请求。`via` 说明验证码是通过 `sms` 收到的，还是来自手机令牌（`otp`）。如果当前没有待处理的验证，`kind` 指明验证码用于哪种验证：`login` 或 `course`。
- 如果需要课程令牌而你没有传验证码，它会自动尝试用已绑定的手机令牌生成验证码。
- 其他情况下，它返回 `{ status: 'verification_required', kind, methods, message, next }`，由助手向用户索要验证码。
- 树洞的回复里没有 `success: true` 就算失败，工具会带着树洞返回的信息报错。

`verify.treeholeSendCode { kind? }` 为当前待处理的验证发送短信。没有待处理的验证时，用 `kind` 指定一种。如果树洞提示上一条验证码还没过期，也算发送成功。

## 服务端函数

<Callout type="warn" title="官方服务器暂未开放">
  SDK 里已经有 `server:` 字段、`{ fn }` 绑定和 `cloud.call` 宿主能力，但插件的服务端函数**目前在官方服务器上没有开放**。请让插件在手机上运行，或者把你自己的后端做成[远程插件](/docs/build/remote-plugin)。
</Callout>

`server:` 部分用同样的步骤和表达式声明函数，由 PKU harness Cloud 服务器运行。服务器有一套自己的能力：服务端 KV 存储，`crypto.sha256`、`hmacSha256` 和 `randomId`，以及使用服务器运营方设置的密钥（secrets）向 `server.network` 里的域名发 HTTPS 请求。服务端函数永远拿不到校园访问权限。

带有 `server:` 的插件必须在 `cloud.disclosure` 里写明哪些数据会离开设备。设计和进展见 [`docs/CLOUD-FUNCTIONS.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/CLOUD-FUNCTIONS.md)（目前暂缓）；另见[云服务 → 插件作者指南](/docs/cloud/plugin-guide#server-functions)。

## 安装链接

同学们有四种方式安装插件：在 App 里粘贴链接（设置 → 插件 → 添加）、扫描二维码、在[插件市场](/marketplace)点「在 App 中打开」，或者让助手安装（它会调用 `plugins.install`）。App 接受以下几种链接：

| 形式 | 示例 |
|---|---|
| GitHub 文件夹 | `https://github.com/<owner>/<repo>/tree/<ref>/<path>` |
| GitHub 仓库根目录 | `https://github.com/<owner>/<repo>`（PLUGIN.md 位于根目录） |
| GitHub 文件 | `https://github.com/<owner>/<repo>/blob/<ref>/<path>/PLUGIN.md` |
| 任意指向 `PLUGIN.md` 的 HTTPS URL | gist 的 raw 链接、你自己的服务器 |
| 深链接 | `pkuharness://plugin?src=<上面任意一种链接，经过 URL 编码>` |

安装之前，App 会拉取并校验所有文件，然后显示**审核页**。审核页告诉同学三件事：

- 这是**官方**插件还是**社区**插件。官方插件指 App 内置的插件，或者链接指向 `github.com/pkuinfo/pku-harness-plugins` 的插件，其余都是社区插件。
- 插件能访问什么：**校园服务**（使用用户的登录状态调用，插件看不到密码）、**网站**（`network` 里的域名）和 **App 功能**（宿主能力）。
- 插件能做什么：列出每个工具，以及它的说明和效果。

社区插件的 `write`、`money` 和 `public` 工具，初始设置都是「先询问」。它们的结果作为不可信数据交给 AI，不会被当作指令执行。用户点「安装」之前，什么都不会装上。

## 更新

App 会在启动时（每天最多一次）和用户打开插件页面时，重新检查已安装插件的链接。接下来怎么处理，取决于哪些内容有变化：

- 内容哈希没变：什么都不做。
- 内容变了，但声明没变：直接应用更新，并显示「已更新到 1.3.0」之类的提示。
- 声明范围变大了，比如新增了校园服务、域名或宿主能力，或者效果变强：更新会先暂停，等用户审核同意后再应用。

用户可以关闭自动更新，也可以回滚到上一个版本。对作者来说，发布更新只需要一次 `git push`。

## 测试

```bash
bun run plugin validate path/to/my-plugin   # App 会做的全部检查，精确到文件和步骤
bun run plugin test path/to/my-plugin       # 回放 tests/*.yaml（录制的响应）
bun run plugin run path/to/my-plugin <tool> '{"k":"v"}'   # 真实请求，仅限公开域名
```

请在 `pku-harness-plugins` 的本地副本里运行这些命令。校园请求只能在 App 里发出，所以要把它们的响应录进 `tests/*.yaml`（见[快速上手](/docs/build/quickstart#record-a-test)）。在插件仓库里，持续集成（CI）会通过 `plugins/documents.test.ts` 回放所有插件文档的测试。

## 发布

把文件夹推送到公开的 GitHub 仓库，然后在[插件市场](/marketplace/submit)提交这个仓库。插件市场会找出所有 `PLUGIN.md`，检查路径和声明，并如实展示同学们将会看到的内容。见[发布](/docs/marketplace/publishing)和[审核规则](/docs/marketplace/review)。

想让插件成为官方插件，就向 `pku-harness-plugins` 提交一个 pull request，把插件文件夹加到 `plugins/` 下，并附上录制好的测试。


# 多语言（i18n） (/docs/build/i18n)

> 内置插件怎样同时提供中文和英文。清单里的文字在 `i18n.en` 里写英文版，页面和小组件的文字放进 `defineStrings` 表，日期交给 SDK 的格式化函数，给模型看的文字不翻译。

App 支持简体中文（`zh-Hans`）和英文（`en`）。中文是源语言：每个字符串先用中文写，再补上英文版。用户在设置里选择「跟随系统」「简体中文」或「English」。

每个内置插件（bundled plugin）都**必须**把两种语言写全。插件仓库里的测试 `plugins/i18n.test.ts` 会逐个检查插件，缺少英文字符串就会失败。本页讲的是内置插件。插件文档的英文文字全部写在清单的 `i18n.en` 部分（见[声明式插件](/docs/build/declarative-plugins#the-manifest)）。

## 哪些要翻译

给人看的文字要翻译。只给模型看的文字，比如工具描述和插件说明，只写一份，不翻译。

| 文字 | 位置 | 是否翻译 |
| --- | --- | --- |
| 插件 `name`、`description` | `definePlugin`（中文）+ `i18n.en` | 是 |
| 工具 `title` | `tools.<name>.title` + `i18n.en.tools.<name>.title` | 是 |
| 工具 `summary`（仅插件文档） | 工具文件里的 `summary` + `i18n.en.tools.<name>.summary` | 是 |
| 小组件标题和描述 | `contributes.widgets` + `i18n.en.widgets` | 是 |
| 页面标题 | `contributes.screens` + `i18n.en.screens` | 是 |
| 设置项 | `contributes.settings` + `i18n.en.settings.<screen>` | 是 |
| 快捷指令 | `contributes.commands` + `i18n.en.commands.<name>`（`description`、`argHint`、`aliases`、`prompt`） | 是 |
| 数据源标题 | `dataSources` + `i18n.en.dataSources` | 是 |
| 模型服务商名称、提示、模型名 | `providers` + `i18n.en.providers` | 是 |
| 页面和小组件里的文字 | `src/strings.ts`（`defineStrings`） | 是 |
| 工具 `description`、`instructions`、`context`、工具结果 | 给模型看 | **否** |

## 清单的英文版本

中文字符串照常写在 `definePlugin` 里，英文版写在 `i18n.en` 里。下面的例子来自 `shuttle` 插件：

```ts
definePlugin({
  id: 'shuttle',
  name: '校车',
  description: '燕园—新燕园（昌平）通勤班车和新燕园—地铁北安河快速公交时刻表，算出下一班车。',
  i18n: {
    en: {
      name: 'Shuttle bus',
      description: 'Timetables for the Yanyuan–Xinyanyuan (Changping) commuter shuttle and the Xinyanyuan–Bei’anhe metro express bus, with the next departure worked out for you.',
      tools: { next: { title: 'Next shuttle' }, timetable: { title: 'Shuttle timetable' } },
      widgets: { next: { title: 'Next shuttle', description: '…' } },
      commands: { shuttle: { description: 'Next shuttle (works offline)', argHint: 'e.g. Yanyuan to Xinyanyuan', aliases: ['bus'] } },
      dataSources: { next: { title: 'Next shuttle' } },
    },
  },
  // …
});
```

运行时，`en` 里缺少的字段会回退到中文。但覆盖测试仍会失败，所以请全部填上。

## 字符串表

页面和小组件里的文字放在字符串表里，每个插件一张，位于 `src/strings.ts`。先用类型定义一次所有的键，再为每种语言分别给出值：

```ts title="src/strings.ts"
import { defineStrings } from '@pku-harness/sdk';

type Strings = {
  none: string;
  later: (list: string) => string;
};

export const strings = defineStrings<Strings>({
  'zh-Hans': { none: '今明两天没有班次', later: (list) => `之后 ${list}` },
  en: { none: 'No buses today or tomorrow', later: (list) => `Then ${list}` },
});
```

```tsx
const s = strings[host.useLocale()];
<Text>{s.none}</Text>
```

在组件里，用 `host.useLocale()` 选出用户所用语言的那张表。

`defineStrings` 会拿 `en` 和 `zh-Hans` 做类型检查：两者的键必须相同，值的类型也必须相同。带参数的字符串写成函数。不要把翻译好的片段拼接成句子，因为两种语言的语序不同。

## 日期和数字

App 运行在 JavaScript 引擎 Hermes 上，而 Hermes 会忽略 `Intl` 的语言设置，`toLocaleDateString` 之类的函数因此会给出错误的格式。请改用 SDK 提供的格式化函数，其中大多数接收来自 `host.useLocale()` 的语言参数 `l`：

| 函数 | zh-Hans | en |
| --- | --- | --- |
| `formatClock(d)` | `21:04` | `21:04` |
| `formatWeekday(d, l)` | `周一` | `Mon` |
| `formatLocalDate(d, l)` | `10月18日` | `Oct 18` |
| `formatLocalDateTime(d, l)` | `10月18日 21:04` | `Oct 18, 21:04` |
| `formatRelative(ms, l)` | `刚刚`, `3 分钟前`, `昨天 21:04` | `Just now`, `3 min ago`, `Yesterday 21:04` |
| `formatDay(d, l)` | `今天`, `明天`, `周三` | `Today`, `Tomorrow`, `Wed` |
| `formatCountdown(ms, l)` | `2小时10分` | `2h 10m` |
| `plural(n, one)` | — | `1 book`, `3 books` |

详见 [SDK → format](/docs/sdk/format)。

## 英文文案规范

覆盖测试还会检查英文字符串的写法：

- 除了括号里的注释和引号内的内容，不能出现中文。`Treehole (树洞)` 是可以的。
- 用弯撇号（`’`），不用直撇号（`'`）。
- 不用感叹号。
- 简短，并使用句首大写（sentence case），即只有第一个单词和专有名词首字母大写。校园专有名词用官方英文名或拼音：Peking University、Treehole (树洞)、Course (教学网 / Blackboard)、Campus Card。

中文文字也一样：写得简短，不用感叹号。


# 开发插件 (/docs/build)

> 怎样在 PLUGIN.md 插件文档、远程插件和内置 TypeScript 插件之间做选择，需要克隆哪些仓库，以及从写第一个工具到上架插件市场的工作顺序。

插件（plugin）负责把 PKU harness 接到某一个校园服务上，或者给 App 增加一项功能。每个插件提供一组「工具」（tool），也就是带类型的小操作，比如「列出空闲教室」「查询校园卡余额」。AI 助手和用户在界面上的点击，调用的都是同一套工具。

所以写插件主要是三件事：弄清楚服务怎样响应请求，把这些请求包装成工具，再在合适的地方加一个小组件或页面。

阅读本章需要你能看懂 YAML 或 TypeScript，并会使用终端。你不需要了解 App 的内部实现。

## 选择插件类型

插件有三种。大多数情况下，你应该写第一种。

**插件文档**是一个包含 `PLUGIN.md` 文件的文件夹。它的工具用 YAML 步骤和安全的小型表达式写成，由 App 在手机上解释执行。你用 `git push` 发布，同学们通过链接安装和更新。大多数校园接入都适合写成插件文档：向校园网站或公开网站发请求，提取需要的数据，必要时带上用户的校园登录状态。建议先看[快速上手](/docs/build/quickstart)，再读[声明式插件](/docs/build/declarative-plugins)。你也可以在 App 里[让 AI 帮你写](/docs/build/ai-authoring)。

**远程插件**是你自己运行的服务器。它使用 MCP（Model Context Protocol，模型上下文协议）。MCP 是 AI 应用通过 HTTP 调用工具的一种标准协议，这里使用它的 Streamable HTTP 传输方式。远程插件可以用任何语言编写，部署服务器就等于发布更新，不需要 App 发版。它适合你自己的服务、计算量大的任务，或者需要通用代码的场景。从 [`templates/remote-plugin`](/docs/build/remote-plugin) 开始。

**内置插件**是用 TypeScript、zod 和 React Native 编写的模块，打包在 App 里。它只能随 App 版本发布，所以动手之前请先开一个 issue。内置插件用于 App 自身的功能（看板、日程、定时任务、记忆、模型服务商等），以及插件语言暂时表达不了的接入。从 [`definePlugin`](/docs/build/bundled-plugin) 开始。

| | 插件文档 | 远程插件 | 内置插件 |
| --- | --- | --- | --- |
| 编写方式 | YAML 步骤和表达式 | 任意语言（MCP） | TypeScript |
| 运行位置 | 手机上，由 App 解释执行 | 你的服务器 | 手机上，App 内部 |
| 更新方式 | `git push` | 重新部署服务器 | 随 App 发版 |

官方的校园接入中，classrooms、campus-events、grades、canteen、shuttle 和 notices 已经是插件文档。其余官方接入目前仍是 TypeScript，我们正在逐个迁移。

## 开发流程

<Steps>
<Step>

### 阅读概念

[插件](/docs/concepts/plugins)、[工具与效果](/docs/concepts/tools-and-effects)、[权限](/docs/concepts/permissions)和[安全](/docs/concepts/security)这四页规定了每个插件都要遵守的规则。审核会按照这些规则检查你的插件，所以请先读它们。

</Step>
<Step>

### 弄清协议

你需要知道服务用哪些地址、返回什么内容。如果 [`pkucli`](https://github.com/pkuinfo/pkucli) 已经对接过这个服务，就移植它的代码，并注明参考的文件。具体做法见[从 pkucli 移植](/docs/build/porting-from-pkucli)。

</Step>
<Step>

### 编写工具

一个操作写成一个工具。如实声明它的效果，给每个输入加上限制，描述要写给模型看。插件文档的写法见[声明式插件](/docs/build/declarative-plugins)，代码插件的写法见[工具与 schema](/docs/build/tools)。

</Step>
<Step>

### 添加界面

插件文档可以添加生成式界面的小组件和页面（用 JSON 描述，由 App 绘制），还可以添加设置项和快捷指令。内置插件还能添加原生页面。见[界面扩展](/docs/build/ui)和[多语言](/docs/build/i18n)。

</Step>
<Step>

### 测试

每种插件有各自的测试方法。插件文档用 `bun run plugin validate|test` 检查文件、回放录制好的响应；TypeScript 逻辑用 `bun test`；想在没有 API key 的情况下跑通助手的调用流程，可以用模拟模型；远程插件可以拿演示用的远程插件来对照。四种方法都在[测试](/docs/build/testing)里介绍。

</Step>
<Step>

### 发布

先分享安装链接，再把插件登记到插件市场。见[发布](/docs/build/publishing)，以及插件市场部分的[清单参考](/docs/marketplace/manifest)和[提交流程](/docs/marketplace/publishing)。

</Step>
</Steps>

## 需要的仓库

从 [`pkuinfo/pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 开始。这个仓库包含 SDK 和插件语言、作者命令行工具（`bun run plugin`）、官方插件文档和内置插件、插件市场的注册表，以及远程插件的模板和示例。

[`pkuinfo/pku-harness`](https://github.com/pkuinfo/pku-harness) 是 App 本体，只有在手机或模拟器上运行内置插件时才需要。写插件文档时，在你想实际发出校园请求之前都用不到它。

[`pkuinfo/pkucli`](https://github.com/pkuinfo/pkucli) 是一组访问北大各项服务的 Rust 命令行工具，可以用来查阅各个服务的协议细节。

```bash
mkdir pku-info && cd pku-info
git clone https://github.com/pkuinfo/pku-harness-plugins.git     # SDK、插件、注册表、模板
git clone --recurse-submodules https://github.com/pkuinfo/pku-harness.git   # 只在 App 里运行内置插件时需要
cd pku-harness-plugins && bun install && bun test
```

<Callout title="没有 npm 包">
  SDK 和插件都不发布到 npm，而是直接从 GitHub 仓库使用。请在 `pku-harness-plugins` 的本地副本里开发：它的 bun workspace 和 `tsconfig.json` 会把 `@pku-harness/sdk` 解析到 `packages/sdk/src`。App 也以 git 子模块 `plugins/` 的形式引入同一个仓库。远程插件完全不需要 SDK。
</Callout>

## 基本规则（摘自 CONTRIBUTING.md）

1. **工具就是 API。** 每个工具要有清楚的中文 `title`，给用户看；还要有写给模型的 `description`，说明什么时候用、怎么用。每个输入都要校验：插件文档用 `input` 字段，内置插件用 zod，远程插件用 JSON Schema。
2. **如实声明效果。** 只读工具设置 `effect: read`（插件文档和内置插件）或 `readOnlyHint: true`（MCP）。会修改状态、花钱或公开发布内容的工具，必须声明出来。
3. **绝不索要校园密码。** 账号凭据只保存在用户的手机上。
4. **返回数据，不要返回指令。** 模型会把工具结果当作数据看待。
5. **声明要访问的范围。** 插件文档写 `campus`、`network` 和 `abilities`，`requires` 由它们自动推导；代码插件写 `requires`。不要依赖手机上的 shell 或文件系统。
6. **校园协议从 pkucli 移植**（如果它已经实现），并注明来源。
7. **中英文都要写。** 插件文档要有 `i18n.en` 部分。内置插件要给清单里每个面向用户的字符串提供英文版本，页面和小组件里的文字放在 `src/strings.ts` 表里。


# 从 pkucli 移植 (/docs/build/porting-from-pkucli)

> pkucli 是北大各项服务的协议参考。本页介绍怎样把它 Rust crate 里的接口、登录步骤和各种特殊情况移植到插件里，把登录交给 App，并注明出处文件。

[`pkuinfo/pkucli`](https://github.com/pkuinfo/pkucli) 是一组访问北大网络服务的命令行工具，用 Rust 编写。每个服务最难弄清的部分，它的作者都已经摸索过了：有哪些接口，登录要经过哪几步，哪些请求头和参数必不可少，以及 HTML 的结构。

如果你要写插件的服务 pkucli 已经支持，请直接移植 pkucli 的做法，不必重新摸索，并在注释里注明出处文件。本页介绍在 pkucli 里去哪里找代码，哪些部分放进插件、哪些留在 App 里，并给出一个示例。

大多数服务都通过北大统一身份认证 IAAA（iaaa.pku.edu.cn）登录。通过 IAAA 之后，每个服务通常还要经过一次或几次自己的单点登录（SSO）跳转，我们把每一次这样的跳转称为「登录跳转」。

## 对应关系

| pkucli crate | 服务 | 在 PKU harness 中 |
| --- | --- | --- |
| `common` | IAAA 登录（密码、扫码）、TOTP 验证码、图形验证码、会话、凭据 | App 本身（`src/core/campus`）；**不**放在插件里 |
| `campuscard` | 校园卡（bdcard） | `wallet` 插件，`card` 校园服务 |
| `treehole` | 树洞 | `treehole` 插件，`treehole` 服务 |
| `course` | 教学网（Blackboard） | `courses` 插件，`blackboard` 服务 |
| `elective` | 选课 | `elective` 插件，`elective` 服务 |
| `cwfw`、`cwpay` | 财务、财务缴费 | `finance` 插件，`cwfw` / `cwpay` 服务 |
| `bdkj` | 场地预约 | `room-booking` 插件，`bdkj` 服务 |
| `portal` | 门户 | App 内部的门户 SSO 跳转 |
| `claspider` | 课程回放（智云课堂） | 计划中 |
| `info-spider`、`info-auth` | 微信公众号文章 | `notices` 插件可读取单篇文章（正文清洗移植自 `info-spider`） |

TOTP（基于时间的一次性密码）就是身份验证器 App 上显示的六位数字。在一个 crate 里，`api.rs`（或 `client.rs`）存放接口和响应类型，`login.rs` 存放该服务自己的登录跳转，`commands.rs` 存放用户可以执行的操作。

## 代码搬到哪里

pkucli crate 里的每个文件，在 PKU harness 里都有对应的位置。登录部分搬进 App，其余部分搬进插件：

```
pkucli crate                     PKU harness
─────────────────────────────    ──────────────────────────────────────────────
login.rs（IAAA → 服务的 SSO）    App：一个校园服务适配器（由 App 维护）
client.rs（请求头、基础 URL）    插件：services.campus.request 的 `url` / `headers`
api.rs（接口、类型）             插件：src/api.ts 加 zod / TS 类型
commands.rs / display.rs         插件：工具（返回数据，而不是排好版的文本）
```

- **登录留在 App 里。** 插件（plugin）从不自己实现 IAAA 或某个服务的 SSO 跳转，所以永远接触不到密码。App 目前能登录的服务有 `card`、`its`、`treehole`、`blackboard`、`bdkj`、`cwfw`、`cwpay`、`elective`、`library` 和 `library-space`。如果你需要的服务不在其中，请去 `pku-harness` 开 issue。新服务需要在 `src/core/campus/adapters/` 里新增一个适配器。
- **请求通过 `services.campus.request(service, req)` 发出。** 路径写成相对于服务域名的路径，cookie 或 token 由 App 加上。
- **公开页面**（不需要登录）可以直接用 `fetch`，并声明 `requires: ['network']`。请把 pkucli 的请求头一起照搬过来，比如桌面浏览器的 User-Agent 和 `accept-language: zh-CN`，因为有些校园服务器会拒绝不带这些请求头的请求。
- **解析成数据。** pkucli 的 `display.rs` 是为终端排版输出的。工具（tool）则返回结构化的 JSON，因为读取它的是模型或页面。

## 示例

下面是 pkucli 里查询校园卡的代码，用 Rust 编写：

```rust title="crates/campuscard/src/api.rs"
/// 查询校园卡信息
pub async fn query_card(&self) -> Result<CardQueryData> {
    let url = format!("{CARD_BASE}/berserker-app/ykt/tsm/queryCard?synAccessSource=h5");
    let resp = self.http.get(&url).send().await.context("查询校园卡失败")?;
    let api_resp: ApiResp<CardQueryData> = parse_response(resp).await?;
    check_resp(api_resp)
}
```

同一个请求在插件里的写法，用 TypeScript 编写：

```ts title="plugins/shared/campus-card.ts (abridged)"
/**
 * 校园卡（bdcard.pku.edu.cn）响应处理，移植自 pkucli
 * crates/campuscard/src/api.rs。金额单位是分；每次请求都带 synAccessSource=h5。
 */
import type { HostServices } from '@pku-harness/sdk';

type Services = Pick<HostServices, 'campus'>;
const get = (services: Services, url: string) => services.campus.request('card', { url });

export async function cardAccount(services: Services) {
  const data = unwrap<{ card: CardInfo[] }>(await get(services, '/berserker-app/ykt/tsm/queryCard?synAccessSource=h5'));
  const account = data.card[0]?.account;
  if (!account) throw new Error('校园卡缺少账户信息');
  return account;
}
```

顶部的注释写明了出处文件，还记下了两个特殊之处：金额单位是分（0.01 元），每次请求都要带上 `synAccessSource=h5`。

## 二次验证

有些服务会要求额外验证，比如短信验证码。pkucli 在终端里请用户输入验证码，插件做不到这一点。在插件里，服务层面的验证要变成一个工具结果，例如 `{ status: 'verification_required', methods: ['sms'], message }`，再配一个发送或提交验证码的工具。树洞的短信验证（错误码 `40002`）和课程令牌（错误码 `40077`）都是这样处理的。插件的页面还可以调用 `services.sms.awaitCode()`，从短信里读取验证码。

IAAA 层面的二次验证由 App 处理，不归插件管。

## 规则

- **必须**在模块顶部的注释里写明移植自 pkucli 的哪个文件。
- **必须**把登录留在 App 里，插件只发请求。
- **应当**在移植解析器时，一起移植测试，以及用真实响应（已脱敏）做成的 fixture。
- **应当**两边一起修 bug。如果发现了 pkucli 没处理的特殊情况，也去 pkucli 开 issue 或提 pull request。


# 发布 (/docs/build/publishing)

> 远程插件和内置插件怎样送到用户手上。远程插件登记到插件市场的注册表；内置插件合并进 pku-harness-plugins，通过签名的 OTA 更新或下一个 App 版本到达用户手机。

本页介绍写好的插件怎样送到用户手上。远程插件和内置插件的步骤不同。插件文档只需把文件夹推送到 GitHub，见[声明式插件](/docs/build/declarative-plugins#publish)和插件市场的[提交流程](/docs/marketplace/publishing)。

## 远程插件

1. 用 HTTPS 部署你的 MCP 服务器（见[快速上手](/docs/build/remote-plugin#4-deploy)）。
2. 确认 MCP 服务器的 `name` 和你要使用的注册表 `id` 一致。
3. 把插件登记到插件市场。一种方式是在仓库里加一份清单，然后在本网站提交（见[清单参考](/docs/marketplace/manifest)和[提交流程](/docs/marketplace/publishing)）。另一种方式是向 [`pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 提交 pull request，在 `registry/registry.json` 里加一条记录。条目怎样审核、`verified` 标记怎样授予，见[审核规则](/docs/marketplace/review)。
4. 用户在「设置 → 插件 → 插件市场」里安装，也可以手动填写你的地址来添加。

你一部署，更新就生效了。App 下次刷新这个插件时，就会拿到新的工具列表。

工具名要保持稳定。用户的小组件和定时检查按名字引用工具，改名会让它们失效。

## 内置插件

1. 先在 `pku-harness-plugins` 开一个 issue，说明插件做什么，以及为什么必须内置。
2. 提交一个 pull request，包含三部分：`plugins/<id>/` 文件夹，`plugins/index.ts` 里 `builtinPlugins` 的条目，以及一条 `"kind": "builtin"` 的注册表记录。
3. 持续集成（CI）和审核者会运行以下检查：

   ```bash
   bun test
   bunx tsc --noEmit -p .
   bun scripts/validate-registry.ts
   ```

4. 合并之后，App 会把 `plugins/` 子模块更新到新的提交。改动怎样到达手机，取决于它涉及哪些部分。只改了 JavaScript 的改动，通过签名的空中更新（OTA，over-the-air）推送，App 下载后在下次启动时生效。涉及原生代码的改动，要等下一个 App 版本，也就是新的 APK。

我们不往 npm 发布任何东西。App 和其他开发者都直接从 GitHub 仓库使用 SDK 和插件。

## 改名或合并

用户可能已经在小组件、定时检查或设置里保存了插件 id、工具 id 或小组件的 key。这些 id 不要复用，也不要悄悄改名。请用 `PluginDef.legacy` 把旧的插件 id、工具 id 和小组件 key 映射到新的上面（见 [SDK → plugin](/docs/sdk/plugin#pluginlegacy)）。

## 使用 PKU harness Cloud

PKU harness Cloud 是我们为需要服务器的功能提供的托管服务。如果插件声明了 `PluginDef.cloud`，请把其中的 `cloud` 声明原样复制到注册表记录里。这份声明包含 `uses`、`e2e`（存储的数据是否必须端到端加密）、`disclosure`，以及可选的 `backend`。

插件市场会在安装前展示这份声明。`disclosure.zh` 必须用平实的话写清楚哪些数据会离开手机。详见 [Cloud → 插件指南](/docs/cloud/plugin-guide#6-registry-entry)。


# 编写第一个插件 (/docs/build/quickstart)

> 写一个只有一个工具的 PLUGIN.md 插件，用录制的响应测试它，再以链接的形式分享。示例是空闲教室插件的简化版。

本页带你写一个只有一个工具的小型插件文档。这个工具回答一个问题：**现在各教学楼分别有多少间空闲教室**。写好之后，你会离线测试它，并把它作为链接分享出去。

示例是插件仓库里真实插件 [`plugins/classrooms`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/classrooms) 的简化版。它只调用一个公开的校园接口，所以不需要登录。

开始之前，请装好 [bun](https://bun.sh) 和 git。在最后一步之前，你都不需要 App 或手机。

完整的语言说明见[声明式插件](/docs/build/declarative-plugins)，规范原文见 [`PLUGIN-LANGUAGE.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/PLUGIN-LANGUAGE.md)。

<Steps>

<Step>

### 获取作者 CLI

插件仓库里有一个给插件作者用的命令行工具（CLI）。它做的检查和 App 完全一样，所以你在自己电脑上就能发现错误，不必等到有人安装时才出问题。

```bash
git clone https://github.com/pkuinfo/pku-harness-plugins
cd pku-harness-plugins
bun install
```

命令的格式是：`bun run plugin validate|test|run <plugin-dir> [tool] [json-input]`。

</Step>

<Step>

### 编写 `PLUGIN.md`

一个插件就是一个文件夹，`PLUGIN.md` 是其中的主文件。这个文件分为两部分。

顶部两行 `---` 之间的 YAML frontmatter 是插件的「清单」（manifest）。它写明插件的名字、包含哪些工具、可以访问哪些网站。下面的 Markdown 正文是写给 AI 助手看的，告诉它什么时候、怎样使用你的工具。

```md title="my-classrooms/PLUGIN.md"
---
spec: 1
id: my-classrooms
name: 教室概况
description: 各教学楼现在有多少空闲教室。
version: 0.1.0
author: your-github-name
network: [portal.pku.edu.cn]
tools:
  overview: tools/overview.yaml
i18n:
  en:
    name: Classroom overview
    description: How many classrooms are free in each teaching building right now.
    tools: { overview: { title: Free rooms by building, summary: Free classrooms in each building } }
---

my-classrooms__overview：各楼现在空闲教室数量。用户想找自习的地方时先用它挑楼。
```

`network` 列出插件可以访问的全部公开域名。访问其他域名的请求都会失败，而同学们在安装前看到的也正是这份列表。`i18n.en` 里放英文文字，使用英文界面的用户会看到它们，而不是中文。

App 只加载 frontmatter 里写明的文件，比如这里的 `tools/overview.yaml`。它从不列出文件夹的内容，所以插件放在任何静态文件服务器上都能用。

</Step>

<Step>

### 编写工具

一个工具文件描述一个操作。它包含给人看的字段、给模型看的字段、声明的效果，以及按顺序执行的一组步骤。

```yaml title="my-classrooms/tools/overview.yaml"
title: 各楼空闲教室数
summary: 各教学楼现在的空闲教室数量
description: 'How many classrooms are free right now in each teaching building: building, free, total.'
effect: read
steps:
  - let: r
    request:
      url: https://portal.pku.edu.cn/publicQuery/classroomQuery/retrClassRoomInfos.do
      headers: { referer: 'https://portal.pku.edu.cn/publicQuery/', accept: 'application/json' }
    as: json
  - check: "r.success && isList(r.rows)"
    error: 教室概况查询未成功
return: |
  {
    buildings: r.rows.map(b => ({ building: b.buildingName, free: b.classroomFree, total: b.classroomSum })),
  }
```

各字段的作用如下：

- `title` 是工具在 App 里显示的名字，用中文写；英文版写在 `i18n.en.tools.overview.title`。
- `summary` 可以不写。它是一行不超过 80 个字符的说明，告诉用户这个工具做什么，App 会把它显示在安装审核页的工具名下方。英文版写在 `i18n.en.tools.overview.summary`；如果不写英文版，App 就不会给使用英文界面的用户显示这一行说明。
- `description` 只给模型看，从不显示给用户。写清楚工具返回什么、什么时候该用。
- `effect`（效果）取 `read`、`write`、`money` 或 `public`。用户会按效果分别决定助手能否不经询问直接运行工具，所以必须如实声明。
- 第一个步骤发出请求，把解析后的 JSON 绑定到名字 `r` 上。如果响应和预期不符，`check` 步骤会带着错误信息停止。`return` 负责组装结果。

返回数据，不要返回指令。模型会把结果当作数据来读。

<Callout type="warn" title="YAML 里表达式的引号">
  如果表达式或 `${…}` 模板里含有 `: `，或者以 `{`、`[` 开头，就要给它加引号。不加引号时，YAML 会把它当成映射或列表，而不是字符串。遇到这种情况，`validate` 会给出提示。
</Callout>

</Step>

<Step>

### 录制测试

测试回放事先录好的响应，而不去访问真实网站。所以它可以离线运行，每次结果都一样，校园网页改版后也不受影响。把一段真实响应裁剪到需要的部分，贴进 `body`。如果响应很长，可以存成测试旁边的文件，再用 `file:` 引用。

```yaml title="my-classrooms/tests/overview.yaml"
tool: overview
responses:
  - match: retrClassRoomInfos.do
    headers: { content-type: application/json }
    body: '{"success":true,"rows":[{"buildingName":"一教","classroomFree":16,"classroomSum":32}]}'
expect: { buildings: [{ building: 一教, free: 16, total: 32 }] }
```

测试用 `tool` 指明要运行的工具，还可以给出 `input` 和一个固定的时间 `now`。`responses` 里的每一项，会回应 URL 中包含 `match` 文字的请求，内容来自 `body` 或 `file`。如果是校园请求，还要加上 `campus`，写明服务名。

测试的最后写下面两个字段之一。`expect` 会和工具的结果做**严格**比较；`expectError` 是一个模式，错误信息必须与它匹配。

</Step>

<Step>

### 校验、测试、运行

```bash
bun run plugin validate path/to/my-classrooms
bun run plugin test path/to/my-classrooms
bun run plugin run path/to/my-classrooms overview '{}'
```

`validate` 检查清单、工具的 schema、每个表达式和每个文件路径，和 App 以及插件市场做的检查完全一样。`test` 回放 `tests/` 里的文件。`run` 会真实调用工具，但只限公开域名。校园请求必须在 App 里发出，因为只有 App 掌握用户的登录状态，所以要用录制的测试覆盖它们。

</Step>

<Step>

### 分享

把文件夹推送到一个公开的 GitHub 仓库。文件夹的 URL 就是安装链接：

```
https://github.com/<you>/<repo>/tree/main/my-classrooms
```

其他同学可以在 App 里粘贴这个链接、扫描它的二维码，或者打开 `pkuharness://plugin?src=<url-encoded link>`。安装之前，App 会先显示审核页：标明这是社区插件还是官方插件，列出它能访问的网站（这里是 `portal.pku.edu.cn`），并列出每个工具及其说明和效果。

此后每一次 `git push` 都是一次更新。想把插件登记到插件市场，就去[提交仓库](/marketplace/submit)。一个仓库里可以放任意多个插件。见[发布](/docs/marketplace/publishing)。

</Step>

</Steps>

## 下一步

- 输入、步骤、表达式、宿主能力和错误处理：[声明式插件](/docs/build/declarative-plugins)
- 在 App 里和助手一起起草、校验、试运行插件：[让 AI 帮你写插件](/docs/build/ai-authoring)
- 需要用到同学校园登录状态的请求：声明 `campus`（见规范 §4 和 §9）
- 审核会检查什么：[审核与安全](/docs/marketplace/review)


# 快速上手：远程插件 (/docs/build/remote-plugin)

> 基于 templates/remote-plugin 编写远程插件，也就是一个使用 Streamable HTTP 的 MCP 服务器。在本地运行它，添加到 App，再部署上线并登记到插件市场。

远程插件（remote plugin）是你自己运行的服务器，App 通过网络连接它、调用它的工具。本页带你复制模板、编写一个工具、在电脑上运行服务器、把它添加到 App，最后部署上线并登记到插件市场。

服务器使用 [MCP](https://modelcontextprotocol.io)（Model Context Protocol，模型上下文协议）。MCP 是一项开放标准，让 AI 应用能够发现并调用服务器上的工具。PKU harness 使用 MCP 的 Streamable HTTP 传输方式，每次调用都是一个 HTTP `POST` 请求。

用户可以通过 URL 或插件市场添加远程插件。添加之后，它的工具和内置插件的工具进入同一个注册表，遵守同一套权限，由同一个助手调用。你的代码不会在手机上运行，远程插件也永远拿不到校园账号密码。

你需要 bun 和一些 TypeScript 基础。模板使用 TypeScript 和官方 MCP SDK，不过任何有 MCP 服务端库的语言，做法都一样。

## 1. 从模板开始

```bash
cd pku-harness-plugins
cp -r templates/remote-plugin ../my-plugin
cd ../my-plugin
bun install
```

模板只有一个文件 `server.ts`，外加一个 `package.json`，依赖 `@modelcontextprotocol/sdk`、`express` 和 `zod`：

```ts title="server.ts"
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express from 'express';
import { z } from 'zod';

function build() {
  // name 就是你在注册表里的 id：App 会以 `mcp-<name>` 的名字安装这个插件。
  const server = new McpServer(
    { name: 'my-plugin', version: '0.1.0', title: '我的插件' },
    { instructions: 'What this plugin is for, in one sentence.' },
  );
  server.registerTool(
    'hello',
    {
      title: '打个招呼',
      description: 'Return a greeting. Replace with a real capability.',
      inputSchema: { name: z.string().describe('who to greet') },
      annotations: { readOnlyHint: true },
    },
    async ({ name }) => ({
      content: [{ type: 'text', text: `你好，${name}` }],
      structuredContent: { greeting: `你好，${name}` },
    }),
  );
  return server;
}

const app = express();
app.use(express.json());
app.post('/mcp', async (req, res) => {
  // 可选的 bearer 认证：用户在 App 里粘贴 token，它保存在用户设备的钥匙串里。
  if (process.env.PLUGIN_TOKEN && req.headers.authorization !== `Bearer ${process.env.PLUGIN_TOKEN}`) {
    res.status(401).json({ jsonrpc: '2.0', error: { code: -32001, message: 'unauthorized' }, id: null });
    return;
  }
  const server = build();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); // 无状态
  res.on('close', () => {
    transport.close();
    server.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
app.listen(Number(process.env.PORT ?? 8787), () => console.log('MCP plugin ready on /mcp'));
```

`build()` 函数创建服务器并注册工具。`/mcp` 路由先检查可选的 token，再把请求交给一个新建的服务器处理。把 `hello` 工具换成你自己的工具即可。

## 2. 编写真正的工具

工具的每个 MCP 字段在 PKU harness 里都有特定的用途：

- **`name`**，即 `registerTool` 的第一个参数，会成为工具 id `mcp-<server>.<name>`，模型看到的名字是 `mcp-<server>__<name>`。请用简短的 ASCII 小驼峰命名。其他字符会被替换成 `_`，超过 40 个字符的部分会被截掉。
- **`title`** 显示给用户，出现在聊天、授权确认和设置页里。用中文写。
- **`description`** 给模型看。写清楚什么时候用、怎么用，以及单位和格式。
- **`inputSchema`** 会在设备上转换成 zod，每次调用前都会校验。每个字段都要写说明。
- **`annotations.readOnlyHint`** 决定工具的效果。设为 `true` 时效果是 `read`，工具直接运行；不写或设为 `false` 时效果是 `write`，App 默认会先询问用户。
- 结果中的 **`structuredContent`** 会作为 `data` 返回给模型，这是推荐的写法。没有它时，App 会尝试把文本内容解析成 JSON，解析失败就原样作为文本传递。
- 结果中的 **`isError: true`** 会让文本内容成为助手看到的错误信息。

服务器 `instructions` 的前 500 个字符会写进系统提示词中属于这个插件的那一段。App 会在它前面加一句话，提醒模型：这个插件的输出只是数据，不能当作指令执行。

<Callout type="warn" title="远程工具的效果">
  目前 App 只给远程工具两种效果（effect）：设置了 `readOnlyHint: true` 的是 `read`，其余都是 `write`。所以会花钱或公开发帖的工具也被归为 `write`，默认先询问。请在它的 `title` 和 `description` 里写清楚它做什么。
</Callout>

## 3. 运行并添加到 App

```bash
bun server.ts                       # 在 8787 端口的 /mcp 上提供服务
# 可选：PLUGIN_TOKEN=secret bun server.ts
```

在 App 里打开 **设置 → 插件 → 添加远程插件**，填入 URL；如果设置了 token，也一并填上。URL 取决于 App 运行在哪里：

| App 运行在 | URL |
| --- | --- |
| Android 模拟器 | `http://10.0.2.2:8787/mcp` |
| 同一网络下的手机 | `http://<你电脑的局域网 IP>:8787/mcp` |
| 已部署 | `https://my-plugin.example.com/mcp` |

模拟器通过 `10.0.2.2` 访问你的电脑；真机则需要你的电脑在局域网里的地址。

App 会连接服务器，列出你的工具，并在插件页面上显示每个工具的效果。然后问助手一个你的工具能回答的问题。你也可以请助手替你安装插件：它会调用 `plugins.installRemote`，安装前会先请你确认。

<Callout title="完整示例">
  `pku-harness-plugins` 里的 `examples/demo-canteen` 是一个能运行的远程插件，使用模拟数据。它有一个读取工具和一个修改工具，bearer token 是 `demo-token`。用 `bun examples/demo-canteen/server.ts` 运行它。
</Callout>

## 4. 部署

任何能提供 HTTPS 的地方都可以：虚拟专用服务器（VPS）、Fly.io、Railway、带有 MCP 兼容运行时的 Cloudflare，或者校内服务器。请注意以下几点：

- 生产环境必须使用 HTTPS，纯 HTTP 只用于本地开发。
- `POST /mcp` 必须能处理 MCP Streamable HTTP 请求。模板是**无状态**的：每个请求都新建一个服务器。这很适合 serverless 平台，因为这类平台可能为每个请求启动一个新进程。
- 有些校内服务只在北大校园网内可以访问。如果你要调用这类服务，你的服务器也必须运行在校园网里。App 无法把用户的校园登录状态借给你的服务器。
- 你自己的密钥（比如 API key）留在服务器上。如果要保护接口，请使用 bearer token，并在注册表条目里写上 `"auth": "bearer"`。

## 5. 登记到插件市场

登记之后，插件会出现在插件市场里，同学们就能找到它。登记有两种方式。一种是在你的仓库里加一份清单，再通过本站的插件市场提交（见[清单参考](/docs/marketplace/manifest)和[提交插件](/docs/marketplace/publishing)）。另一种是在 `pku-harness-plugins` 的 `registry/registry.json` 里加一条记录。无论哪种方式，`id` 都必须和 MCP 服务器的 `name` 一致：

```json
{
  "id": "my-plugin",
  "name": "我的插件",
  "description": "一句话说明它做什么。",
  "author": "your-github-name",
  "source": "https://github.com/you/my-plugin",
  "kind": "remote",
  "endpoint": "https://my-plugin.example.com/mcp",
  "auth": "none",
  "requires": ["network"],
  "scopes": ["example.com"],
  "tags": ["canteen"]
}
```

向注册表提交 pull request 之前，请先运行 `bun scripts/validate-registry.ts`。另见[发布](/docs/build/publishing)和[审核规则](/docs/marketplace/review)。

## 检查清单

- [ ] MCP 服务器的 `name` 和注册表 `id` 相同（`^[a-z0-9][a-z0-9-]{1,40}$`）。
- [ ] 每个工具都有中文 `title`、写给模型的 `description`，每个输入字段都有说明。
- [ ] 只读工具设置了 `annotations.readOnlyHint: true`，其他工具都没有设置。
- [ ] 返回的是数据（`structuredContent`），不含指令，体积适中。
- [ ] 插件从不索要校园账号密码。
- [ ] 接口使用 HTTPS；如果用了 bearer 认证，已在注册表中声明。


# 测试 (/docs/build/testing)

> 怎样测试各种插件。插件文档回放录制的响应，解析器和纯逻辑用 bun test 写单元测试，用按脚本应答的模拟模型完整跑通助手的流程，远程插件用 demo-canteen 示例来试。

大多数校园插件分三层：一次 HTTP 请求、一个读取响应的解析器，以及一个整理结果的工具（tool）。请求依赖真实的校园服务器，所以测试时用录制好的响应代替它。解析和整理都是普通代码，可以在你的电脑上测试。之后，再在 App 里把整个插件跑一遍。

本页先介绍插件文档，然后依次介绍 TypeScript 插件、模拟模型、演示用的远程插件和真机测试。除非另有说明，所有命令都在插件仓库里运行。

## 插件文档（PLUGIN.md）

`PLUGIN.md` 插件用插件仓库里的作者命令行工具（CLI）测试。它会回放插件 `tests/*.yaml` 里录制的响应：

```bash
bun run plugin validate plugins/classrooms   # App 会做的检查
bun run plugin test plugins/classrooms       # 回放 tests/*.yaml
bun run plugin run plugins/classrooms overview '{}'   # 真实请求，仅限公开域名
```

`validate` 执行的就是 App 安装插件时做的那套检查。`test` 回放 `tests/*.yaml`。`run` 会发出真实请求，而且只能访问公开域名。

`bun test` 包含 `plugins/documents.test.ts`。它加载每个 `plugins/<id>/PLUGIN.md`，回放其中所有录制好的测试。持续集成（CI）会在每次推送到 `main` 和每个 pull request 上运行 `bun test`，所以只要某个插件文档或它录制的响应（fixture）出了问题，CI 就会失败。测试文件的格式见[快速上手](/docs/build/quickstart#record-a-test)。本页其余部分讲的是 TypeScript 插件。

## 单元测试（bun test）

在插件仓库里运行：

```bash
bun test                      # 工作区里所有的 *.test.ts
bun test plugins/focus        # 只测一个插件
bunx tsc --noEmit -p .        # 对 SDK 和插件做类型检查
```

`focus` 是[内置插件](/docs/build/bundled-plugin)一页里的示例插件，请换成你自己插件的目录。

下面几个习惯能让测试真正有用：

- 测试和代码放在一起：`src/parse.test.ts` 紧挨着 `src/parse.ts`。
- **解析器。** 把真实响应存成 fixture（`src/fixtures/*.html|json`），替换掉其中的个人信息，然后断言解析结果。校园网页时常改版，改版之后，fixture 能准确地告诉你哪里出了问题。
- **时间。** 把 `now` 作为参数传进去，不要在逻辑里直接读取 `Date.now()`，这样测试就能固定时间。SDK 的重复规则、课表和格式化函数都接受 `now` 参数。
- **React Native。** 导入了 `react-native` 的模块，不做 mock 的话 bun 无法加载。要么把逻辑放在普通模块里，要么像 `plugins/i18n.test.ts` 那样 mock 掉 `react-native`：

```ts
import { mock } from 'bun:test';

mock.module('react-native', () => ({
  StyleSheet: { create: (s: unknown) => s },
  Platform: { OS: 'android', select: (o: Record<string, unknown>) => o.android ?? o.default },
  View: () => null,
}));
```

### 用假的上下文测试工具

工具的 `execute` 函数接收输入和一个上下文对象 `ctx`。测试时，你可以自己构造一个简单的假上下文。下面的假上下文带有一个内存里的 KV 存储，测试可以先开始一次专注，再把它读出来：

```ts title="plugins/focus/src/index.test.ts"
import { expect, mock, test } from 'bun:test';
import type { KV, ToolContext } from '@pku-harness/sdk';

// index.ts 引入了小组件，小组件又引入了 react-native：加载插件之前先 mock 它。
mock.module('react-native', () => ({ View: () => null }));
const { focusPlugin } = await import('./index');

function memoryKV(): KV {
  const m = new Map<string, unknown>();
  return {
    get: async <T,>(k: string) => m.get(k) as T | undefined,
    set: async (k, v) => void m.set(k, v),
    delete: async (k) => void m.delete(k),
  };
}

test('start, then today shows the running session', async () => {
  const ctx = { pluginId: 'focus', actor: 'user', kv: memoryKV(), services: {} } as unknown as ToolContext;
  await focusPlugin.tools.start.execute({ label: '高数' }, ctx);
  const today = (await focusPlugin.tools.today.execute({}, ctx)) as { running: { label: string } | null };
  expect(today.running?.label).toBe('高数');
});
```

由于 `index.ts` 引入了小组件，小组件又引入了 `react-native`，所以测试要先 mock 它，再加载插件。

`execute` 本身不校验输入，App 会在调用它之前完成校验。如果校验逻辑很重要，请用 `tool.input.safeParse(...)` 单独测试。

## 模拟模型

助手按循环工作：把对话发给模型，运行模型要求调用的工具，再把结果发回给模型。想在没有 API key、也没有真实模型的情况下测试这个循环，可以用 `examples/mock-llm`。它是一个小服务器，接口和 OpenAI 的 Chat Completions API 相同，按固定的脚本应答：

```bash
bun examples/mock-llm/server.ts     # 地址 http://localhost:8788/v1，模型名 "mock-agent"
```

在 App 里打开「设置 → AI 服务 → OpenAI 兼容」。Base URL 填 `http://10.0.2.2:8788/v1`，模拟器通过这个地址访问你的电脑；模型填 `mock-agent`。模拟模型会根据你消息里的关键词挑选一个工具来调用，再总结工具的结果：

| 消息里包含 | 调用 |
| --- | --- |
| `提醒` / `remind` | `scheduler__create`（每 3 天 09:00，共 16 次） |
| `马上` / `soon` | `scheduler__create`（一次性，2 分钟后） |
| `看板` / `dash` | `dashboard__upsertWidget`（一个绑定 `timetable.today` 的小组件） |
| `表单` / `form` | `ui__render`（一个充值表单） |
| `remember` | `memory__remember` |
| `食堂` / `canteen` | `mcp-demo-canteen__reserveSeat`（需要先装好演示插件） |
| `who` | 原样回显注入的 `<context>` 块 |

想让它调用你自己的工具，就在本地扩展它的 `plan()` 函数，写上这些工具的模型名。

## 演示用远程插件

```bash
bun examples/demo-canteen/server.ts   # 地址 :8787/mcp，bearer token 为 demo-token
```

`examples/demo-canteen` 是一个使用模拟数据的远程插件，在 8787 端口的 `/mcp` 上提供服务，bearer token 是 `demo-token`。在「设置 → 插件 → 添加远程插件」里填入 `http://10.0.2.2:8787/mcp` 和 token `demo-token`。它有一个读取工具（`menu`）和一个修改工具（`reserveSeat`），你可以借此看到远程修改类工具弹出的确认提示。

## 在真机上

- 开发版能识别几个特殊的深链接（deep link），可以直接运行一个工具或发起一轮对话：`pkuharness://dev?tool=<plugin>.<tool>&input=<json>` 和 `pkuharness://dev?chat=<text>`。加上 `&actor=agent` 就以助手的身份运行工具，从而看到「先询问」的确认提示。
- 页面和小组件要在深色、浅色两种主题下，以及中英两种语言下各检查一遍。
- 真实的校园数据需要真实账号。读取类工具先在自己的账号上测试，再请别人帮忙；含有个人信息的响应绝不要提交。


# 工具与 schema (/docs/build/tools)

> 怎样设计模型好用的工具。内容包括命名、描述、用 zod（内置插件）或 JSON Schema（MCP）定义输入、如实声明效果、只返回数据，以及处理用户可以补救的状态。

工具（tool）是插件的 API。模型调用它，你自己的页面也调用它。好的工具很小，只做一件事；它的描述写清楚什么时候该用，返回的数据模型拿来就能用。

本页介绍怎样用代码编写工具，包括内置插件（zod）和远程插件（JSON Schema）。插件文档里的工具写法见[声明式插件](/docs/build/declarative-plugins#tools)，本页关于描述、效果和返回结果的建议同样适用。工具背后的概念见[工具与效果](/docs/concepts/tools-and-effects)。

## 命名

一个工具有几个名字，分别给不同的读者看：

| 名字 | 规则 | 示例 |
| --- | --- | --- |
| 工具名 | ASCII 小驼峰的动词或名词，插件内唯一 | `cardBalance`、`search`、`reserveSeat` |
| 工具 id | `<plugin>.<name>`（自动生成） | `wallet.cardBalance` |
| 模型名 | `<plugin>__<name>`（自动生成） | `wallet__cardBalance` |
| `title` | 给用户看的简短中文名称 | `校园卡余额` |

App 每次请求都会把所有启用的工具发给模型，所以相似的工具越多，每次请求消耗的 token 就越多。相关的读取操作应该合并成一个带筛选参数的工具，不要写十个几乎一样的工具。

## 给用户看的文字

用户会在聊天、授权确认和设置页里看到工具的 `title`。`title` 用中文写，英文版写在 `i18n.en.tools.<name>.title`。

插件文档还可以给工具写一个 `summary`：一行不超过 80 个字符的说明，用平实的话讲清楚工具做什么。安装审核页和插件市场的插件页会把它显示在工具名下方。英文版写在 `i18n.en.tools.<name>.summary`；缺少英文版时，App 不会给使用英文界面的用户显示这一行。内置插件没有 `summary` 字段。

下一节介绍的 `description` 从不显示给用户。

## 描述

`description` 是写给模型看的，中文或英文都可以。它应该写清楚三件事：

- **什么时候**用这个工具，用同学们自己会说的话来写。例如：「Use when the user asks which canteen is least crowded」。
- **返回什么**：有哪些字段，单位是什么（元、分钟、北京时间），数据有多新。
- **限制**和**后续步骤**：分页大小、必须遵守的调用顺序（「call `treehole__sendCode` first」），以及遇到 `verification_required` 时该怎么办。

不要在描述里重复输入 schema。每个字段的说明请用 `.describe()` 写，因为模型会在字段旁边看到这些说明。

如果描述文字取决于设备，`description` 可以写成一个接收宿主服务的函数：

```ts
description: (services) => `Show a native UI in the chat… Components:\n${services.genui.describeCatalog()}`,
```

## 输入

内置插件使用 zod 4。模型看到的是由 zod schema 生成的 JSON Schema。无论调用来自助手、页面还是定时任务，App 都会在 `execute` 运行之前校验输入，所以 `execute` 可以放心使用它。

```ts
input: z.object({
  from: z.string().trim().max(20).optional().describe('boarding place, e.g. 燕园 / 新燕园'),
  at: z.string().optional().describe('Beijing time "YYYY-MM-DD HH:mm", default now'),
  count: z.number().int().min(1).max(10).optional().describe('departures per direction, default 3'),
}),
```

- 每个数字和字符串都要设上下限（`.min`、`.max`），默认值写在描述里。
- 取值范围固定的集合用枚举，例如 `z.enum(['weekday', 'holiday'])`。
- 需要模型填写时间时，让它写本地时间字符串 `"YYYY-MM-DD HH:mm"`。SDK 的 `scheduleInputSchema` 和 `parseLocal` 在处理日程时已经采用这种格式。
- 远程插件：设备会用 `z.fromJSONSchema` 把 MCP 的 `inputSchema`（即 JSON Schema）转换成 zod。请只用 JSON Schema 的基础特性，以保证转换能成功。

## 效果

每个工具只能有一种效果（effect）。效果告诉 App 这个工具做的是哪一类事情，用户会按效果分别决定助手能否不经询问直接执行（见[权限](/docs/concepts/permissions)）。

```ts
effect: 'read',      // 读取：余额、列表、搜索
effect: 'write',     // 修改：添加待办、关注帖子、预约房间
effect: 'money',     // 花钱：创建支付订单、充值、把校园卡切换为电子卡
effect: 'public',    // 公开：在树洞发帖或回复
```

有些工具还要加上另外两个标记。返回第三方文本（比如帖子或通知）的工具要设置 `untrusted: true`。调用这样的工具后，助手这一轮剩下的操作都会被标记为「受污染」（tainted），这一轮里会长期保存的写入要等用户确认（见[安全](/docs/concepts/security)）。只能由用户发起的操作，比如批准或解锁某样东西，要设置 `userOnly: true`。这样工具对模型不可见，来自助手或定时任务的调用都会被拒绝。很少用到的工具可以设置 `onDemand: true`：对话开始时不提供给模型，助手用 `plugins.use` 加载插件后才提供，这样每次请求都更小。

## 返回结果

```ts
execute: async ({ name, sort = 'least' }, ctx) => {
  const { time, canteens } = await fetchCrowd(ctx.signal);
  return { time, canteens: canteens.filter((c) => !name || c.name.includes(name)), source: CROWD_SOURCE };
},
```

结果会交回给模型，所以要按模型方便阅读的方式组织：

- 返回 JSON 对象，字段名和单位要一看就懂。
- 需要时注明数据来源和时效（`source`、`time`）。
- 返回模型可以传给下一个工具的 id。
- 把中止信号 `ctx.signal` 传给网络请求，这样调用被取消时请求能尽快停止。
- 失败时抛出 `Error`，附上用户能看懂的简短中文信息，例如 `throw new Error('校园卡登录已失效')`。助手会把它转告给用户。

有些情况是预料之中的，需要用户介入，比如短信验证。这时请返回一个状态对象，而不是抛出异常。助手就能向用户索要所需的信息，再重新调用工具：

```ts
export type VerificationRequired = { status: 'verification_required'; kind: 'login'; methods: ['sms']; message: string };

// 在 execute 里：
if (needsSms) {
  return {
    status: 'verification_required',
    kind: 'login',
    methods: ['sms'],
    message: '树洞需要短信验证。先调用 treehole__sendCode 发送验证码，再带上 code 重试。',
  } satisfies VerificationRequired;
}
```

## 上下文与说明

插件可以给模型提供两种额外的文字。

`instructions` 写在系统提示词里，每次请求都会发送。它适合写简短的规则：什么问题用哪个工具，以及「以预约系统为准」之类的注意事项。

`context({ query, kv, services })` 在每轮对话之前运行，返回和当前消息相关的事实，比如用户记忆的快照。它的结果会被标记为数据，函数必须在 800 ms 内返回。没有相关内容时返回 `undefined`。

两者每次请求都会消耗 token，也都会改变提示词的开头部分，降低模型服务商复用缓存的机会。所以要写得短，而且内容要稳定。不要写入日期和时间，App 每轮都会自动加上。

## 在界面里调用工具

页面和小组件也会调用工具。`invoke` 以用户身份运行工具，`host.useToolData` 通过 App 的共享缓存读取工具结果：

```ts
// 在页面或小组件里（actor: 'user'，不弹授权确认）
await invoke('focus.start', { label: '高数' });

// 通过宿主的共享缓存实时读取
const data = host.useToolData<{ minutes: number }>('focus.today', {}, { ttlMinutes: 1 });
```

## 检查清单

- [ ] 每个工具只负责一件事，读取和修改分成不同的工具。
- [ ] 每个工具都有中文 `title`、`i18n.en.tools` 里的英文标题，以及写给模型的 `description`。
- [ ] 每个输入字段都有范围限制和说明。
- [ ] `effect` 如实声明；需要 `untrusted` 或 `userOnly` 的地方都设置了。
- [ ] 返回的是数据：体积小，带单位，不含密钥，也不含指令。
- [ ] 错误信息简短、用户能看懂；可以补救的状态用状态对象表示。


# 界面扩展 (/docs/build/ui)

> 内置插件怎样通过 `contributes` 添加页面、设置项、标签页内容、看板小组件和快捷指令，并用 App 传入的 HostUI 组件搭建界面。

本页介绍内置插件怎样给 App 添加自己的界面。阅读前请先看[内置插件](/docs/build/bundled-plugin)。插件文档的小组件和页面用生成式界面的 JSON 描述，写法见[声明式插件](/docs/build/declarative-plugins)。

内置插件添加原生界面时，不需要导入任何 App 代码。每个页面和小组件都会通过 props 收到一个名为 `HostUI` 的对象，里面有 App 的组件、主题 token、触感反馈、导航和数据 hook。插件的界面全部用这些东西绘制，所以看起来和 App 的其他部分一致，App 改版后也照样能用。

插件添加的所有界面，都列在 `definePlugin` 的 `contributes` 里：

```ts
contributes: {
  screens:  { main: { title: '专注', component: FocusScreen } },
  settings: [{ screen: 'main', title: '专注', subtitle: '专注时段', icon: 'clock' }],
  widgets:  { today: { title: '今日专注', description: '…', sizes: ['sm', 'md'], component: FocusWidget } },
  commands: { focus: { description: '打开专注', aliases: ['专注'], run: (_i, { navigate }) => navigate('/p/focus/main') } },
  tabs:     [{ slot: 'schedule', screen: 'main' }],   // 只有负责某个标签页的插件才需要
},
```

## 页面

```ts
interface ScreenContribution {
  title: string;
  component: ComponentType<PluginScreenProps>;
  presentation?: 'push' | 'modal';   // modal → /m/<plugin>/<screen>（表单）；默认 push → /p/<plugin>/<screen>
}
```

页面是一个 React 组件。默认以普通页面（`push`）的方式打开，表单请设置 `presentation: 'modal'`。组件会收到 `PluginScreenProps`，其中有 `host`、`services`、`kv`、`invoke(toolId, input?)`、`params`（路由的查询参数）和 `cloud?`。

```tsx
import type { PluginScreenProps } from '@pku-harness/sdk';
import { useState } from 'react';

export function EditScreen({ host, params, invoke }: PluginScreenProps) {
  const { SheetScreen, Field } = host.components;
  const [text, setText] = useState(params.text ?? '');
  return (
    <SheetScreen title="编辑" primary="保存" onPrimary={async () => { await invoke('memory.update', { id: params.id, text }); host.dismiss(); }}>
      <Field label="内容" value={text} onChangeText={setText} multiline />
    </SheetScreen>
  );
}
```

打开页面用 `host.navigate('/p/<plugin>/<screen>')`，打开弹出页用 `host.navigate('/m/<plugin>/<screen>?id=…')`，关闭弹出页用 `host.dismiss()`。普通页面以 `host.components.Screen` 为根组件，弹出的表单页以 `SheetScreen` 为根组件。

## 设置项

```ts
interface SettingsContribution { screen: string; title: string; subtitle?: string; icon?: string }
```

设置项是通往你某个页面的入口，点开后进入它指定的页面。除了这些设置项，「设置 → 插件」里的插件详情页还会列出插件的页面、小组件、工具和权限。

## 小组件

```ts
interface WidgetContribution {
  title: string;
  description: string;                 // 写给助手看：显示什么内容，config 起什么作用
  sizes?: ('sm' | 'md' | 'lg')[];
  defaultSize?: 'sm' | 'md' | 'lg';
  configSchema?: z.ZodType<Record<string, unknown>>;
  component: ComponentType<PluginWidgetProps>;  // host, services, kv, invoke, size, config, cloud?
}
```

小组件是看板上的一张卡片。编写时请注意以下几点：

- 卡片的外框由看板绘制，包括标题、背景、数据更新时间和长按菜单。你只需要绘制内容，并根据 `size` 调整布局：`sm` 是半宽的小卡片，`md` 占满一行，`lg` 是大号主卡片。
- 用 `host.useToolData(tool, args, { ttlMinutes })` 加载数据（见[看板](/docs/concepts/dashboard#refresh-owned-by-the-host)）。刷新时机由 App 决定，所以不要轮询。
- 处理好三种状态。`status` 为 `'loading'` 时显示骨架屏；没有数据时显示错误文字，并让用户可以通过 `data.refresh()` 重试；还要处理未登录的情况。
- 小组件的 `config` 由助手或用户选择，并用 `configSchema` 校验。每个字段用 `.describe()` 写说明，并在 `description` 里提到这些字段（「config.names limits it to certain canteens」），这样助手才知道有哪些配置。
- 每个小组件都放在一个错误边界（error boundary）里。即使它崩溃，看板也只在它的位置显示一条提示，其他小组件照常工作。

## 快捷指令

```ts
type CommandContribution = {
  description: string;       // 在 / 菜单里显示的一行说明
  aliases?: string[];        // 别名，例如中文名：['余额']
  argHint?: string;          // 输入框占位提示；写了它，表示指令接受输入
} & (
  | { prompt: string }       // 作为用户消息发送；{{input}} 会被替换
  | { run: (input: string, ctx: { services: HostServices; navigate: (href: string) => void; locale: AppLocale }) => Promise<string | void> | string | void }
);
```

快捷指令是聊天输入框 `/` 菜单里的一项。指令名只能用小写字母、数字和连字符（`^[a-z][a-z0-9-]*$`）。如果两个插件用了同一个名字，App 会给它们加上插件 id 作为前缀，变成 `/plugin:name`。

指令有两种。`prompt` 指令把一段文字发给助手，就像用户自己输入的一样。`run` 指令在设备上运行，它返回的字符串作为提示显示在聊天里，不会发给模型。

```ts
commands: {
  canteen: { description: '现在去哪个食堂', aliases: ['食堂', '吃饭'], argHint: '想吃什么 / 在哪（可空）', prompt: '现在哪些食堂还开着、人少？帮我挑一个{{input}}' },
  shuttle: { description: '下一班校车（本地计算）', aliases: ['校车'], argHint: '如 燕园到新燕园', run: (input, { locale }) => quickAnswer(input, Date.now(), locale) },
},
```

## 标签页

App 有两个标签页位置：`dashboard` 和 `schedule`，分别由提供它们的已启用插件填充，目前是 `dashboard` 插件和 `schedule` 插件。对话和设置两个标签页属于 App 本身。只有在你要替换这两个插件之一时，才需要提供标签页。

## HostUI 要点

下面是 `host` 里最常用的成员：

| 成员 | 用途 |
| --- | --- |
| `host.components` | `Screen`、`SheetScreen`、`Text`、`Button`、`IconButton`、`ListGroup`、`ListRow`、`Chip`、`Surface`、`Glass`、`Stat`、`Ring`、`Sparkline`、`Field`、`DateTimeField`、`Switch`、`Checkbox`、`Segmented`、`Stepper`、`WeekdayPicker`、`SortableList`、`EmptyState`、`Skeleton`、`FadeIn`、`Icon`、`QRCode`、`GenUI`、`PluginWidget`、`Row`、`Column`、`Pressable`、`Hourglass` |
| `host.useTheme()` | 主题 token：`colors`、`spacing`、`radius`、`typography`、`glass`、`courseColor(i)`、`contentWidth` |
| `host.useToolData`、`useWidgetData`、`useBindings`、`refreshAll` | 使用共享缓存的实时数据 |
| `host.useLocale()` | `'zh-Hans'` 或 `'en'` |
| `host.navigate`、`back`、`dismiss`、`ask(text)` | 导航；`ask` 会切换到对话并发送一条消息 |
| `host.haptics` | `tap`、`select`、`success`、`warning`（遵循用户设置） |
| `host.useNow(ms)`、`formatAgo(ms)` | 每隔 `ms` 更新一次的当前时间；相对时间 |
| `host.useSecureDisplay({ brightness })` | 挂载期间禁止截屏（用于付款码） |
| `host.useStoreVersion()` | 定时任务、待办、小组件或课表变化时重新渲染 |
| `host.clipboard?`、`host.shareLink?` | 可选，使用前先判断是否存在 |

完整签名见 [SDK → ui](/docs/sdk/ui)。

## 设计规则

- **必须**使用 `host.components` 和主题 token，不要写死颜色、字号或间距。
- **必须**把所有面向用户的文字放进 `strings.ts`，用 `host.useLocale()` 选择语言。
- **必须**使用宿主图标集里的图标名：`card`、`wifi`、`book`、`bell`、`clock`、`location`、`sparkles`、`key`、`person`、`qr`、`warning`、`check`、`calendar`、`bus`、`food`、`wallet`、`library`、`room`、`school`、`ticket`、`medal`、`chart`、`search`、`globe`、`lock` 等（完整列表见 App 的 `src/components/icon.tsx`）。
- **应当**给可点击的自定义内容加上 `accessibilityLabel`。
- 文案：中文要简短，不用感叹号；英文只有句首字母大写（sentence case），撇号用弯撇号（’）。


# 通道（所有者） (/docs/cloud/api/channels)

> 设备开启的端到端加密中继通道，用来和打开分享链接的人实时共享。所有者通过 WebSocket 与对端通信，服务器只转发信封。

Base URL: `https://{provider}` or `http://localhost:8787`

## POST /v1/channels

**Open a channel** (`createChannel`)

Opens a relay channel owned by the calling device and plugin. The client generates the share
secret `k`, derives `authKey = HKDF(k, "pku-harness-cloud/v1/join")` and
`encKey = HKDF(k, "pku-harness-cloud/v1/enc")`, and sends only `joinHash = base64url(sha256(authKey))`,
the channel's X25519 public key and `meta` sealed with `encKey`. The server can gate joins
but can't read anything. Limits: 5 open channels per device, TTL 60 s – 24 h (default 15 min).

Auth: `pluginToken`

Request body (`application/json`): `CreateChannelRequest`

- **200**: The channel id and expiry. → `application/json` `CreateChannelResponse`
- **default**: see [Error](#response-error) below

## PATCH /v1/channels/{id}

**Extend a channel** (`extendChannel`)

Sets the expiry to now + `ttlS`, capped at `limits.channels.maxTtlS`. Owner only.

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

Request body (`application/json`): `PatchChannelRequest`

- **200**: The new expiry. → `application/json` `PatchChannelResponse`
- **default**: see [Error](#response-error) below

## DELETE /v1/channels/{id}

**Close a channel** (`closeChannel`)

Closes the channel; connected peers receive `{ t: "closed", reason: "owner" }`. Owner only.

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

- **200**: Closed. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## GET /v1/channels/{id}/ws

**Owner WebSocket** (`ownerSocket`)

Upgrades to a WebSocket for the channel owner. Every frame is one JSON object.

- Server → owner: `OwnerInFrame` (`hello`, `join`, `leave`, `peer` presence, `msg`, `closed`, `error`, `pong`).
- Owner → server: `OwnerOutFrame` (`msg` to one peer, `kick` a peer and free its seat, `ping`).

Frames carry envelopes sealed with the per-peer key
`HKDF(X25519(chanPriv, peerPub) ‖ encKey, salt = chanPub ‖ peerPub, info = "pku-harness-cloud/v1/peer")`.
Limits: frames ≤ 4 KB of ciphertext, ≤ 60 frames per minute per party (the owner gets
60 × maxPeers); a violating frame is dropped with an `error` frame. A frame to an offline
party is dropped with `error: conflict` (use the mailbox for offline delivery).

The token may also be passed as `?t=` (WebSocket clients can't always set headers). Close
codes: `4003` kicked, `4009` replaced by a newer connection of the same party, `4010` channel
closed or expired (a `closed` frame comes first), `1001` server shutdown (reconnect).

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

- **101**: Switching to the WebSocket protocol. Frames are described by the `OwnerInFrame` and `OwnerOutFrame` schemas.
- **default**: see [Error](#response-error) below

## DELETE /v1/channels/{id}/mailbox

**Clear the mailbox** (`clearMailbox`)

Removes every mailbox slot of the channel (`Channel.mailbox.clear()` in the SDK). Owner only.

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

- **200**: Cleared. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## DELETE /v1/channels/{id}/mailbox/{slot}

**Delete a mailbox slot** (`deleteMailboxSlot`)

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |
| `slot` | path | `MailboxSlot` | yes |  |

- **200**: Deleted. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## PUT /v1/channels/{id}/mailbox/{slot}

**Put a sealed blob in a mailbox slot** (`putMailboxSlot`)

Batch mode. Sealed blobs that peers can read while the owner is offline (at most `limits.channels.mailboxSlots` slots). Owner only.

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |
| `slot` | path | `MailboxSlot` | yes |  |

Request body (`application/json`): `MailboxPutRequest`

- **200**: Stored. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### ChannelId

Server-generated, base64url (16 random bytes → 22 characters). pattern `^[A-Za-z0-9_-]{8,64}$`

```ts
type ChannelId = string;
```

### CloseReason

```ts
type CloseReason = "owner" | "expired" | "revoked" | "locked" | "server";
```

### CreateChannelRequest

```ts
type CreateChannelRequest = {
  ttlS: number; // minimum 1
  maxPeers?: number; // minimum 1, default 1
  joinHash: Key32;
  meta: Envelope;
  chanPub: Key32;
  page?: PageName;
};
```

### CreateChannelResponse

```ts
type CreateChannelResponse = {
  id: ChannelId;
  expiresAt: Ms;
};
```

### Envelope

XChaCha20-Poly1305 sealed JSON. `n` = 24-byte random nonce, `c` = ciphertext ‖ 16-byte tag. Open it with `open()` from `@pku-harness/cloud-protocol` and validate the result.

```ts
type Envelope = {
  v: 1;
  n: Nonce24;
  c: string; // pattern `^[A-Za-z0-9_-]*$`, minLength 22
};
```

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### Key32

32 bytes, base64url (Ed25519 or X25519 public key, hash). pattern `^[A-Za-z0-9_-]{43}$`

```ts
type Key32 = string;
```

### MailboxPutRequest

```ts
type MailboxPutRequest = {
  env: Envelope;
  ttlS: number; // minimum 1
};
```

### MailboxSlot

pattern `^[A-Za-z0-9._:-]{1,64}$`

```ts
type MailboxSlot = string;
```

### Ms

Unix time in milliseconds. minimum 0

```ts
type Ms = number;
```

### Nonce24

24 bytes, base64url. pattern `^[A-Za-z0-9_-]{32}$`

```ts
type Nonce24 = string;
```

### Ok

```ts
type Ok = {
  ok: true;
};
```

### OwnerInFrame

Server → owner WebSocket frame.

```ts
type OwnerInFrame = {
  t: "hello";
  id: ChannelId;
  expiresAt: Ms;
  peers: {
    peerId: PeerId;
    peerPub: Key32;
    joinedAt: Ms;
    online: boolean;
  }[];
} | {
  t: "join";
  peerId: PeerId;
  peerPub: Key32;
  at: Ms;
} | {
  t: "leave";
  peerId: PeerId;
  at: Ms;
} | {
  t: "peer";
  peerId: PeerId;
  online: boolean;
  at: Ms;
} | {
  t: "msg";
  peerId: PeerId;
  env: Envelope;
} | {
  t: "closed";
  reason: CloseReason;
} | {
  t: "error";
  code: WireErrorCode;
  message: string;
} | {
  t: "pong";
  at: Ms;
};
```

### OwnerOutFrame

Owner → server WebSocket frame. `kick` drops a peer and frees its seat (重置查看者).

```ts
type OwnerOutFrame = {
  t: "msg";
  to: PeerId;
  env: Envelope;
} | {
  t: "kick";
  peerId: PeerId;
} | {
  t: "ping";
};
```

### PageName

pattern `^[a-z0-9][a-z0-9-]{0,40}$`

```ts
type PageName = string;
```

### PatchChannelRequest

```ts
type PatchChannelRequest = {
  ttlS: number; // minimum 1
};
```

### PatchChannelResponse

```ts
type PatchChannelResponse = {
  expiresAt: Ms;
};
```

### PeerId

pattern `^[A-Za-z0-9_-]{4,64}$`

```ts
type PeerId = string;
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 设备与鉴权 (/docs/cloud/api/devices)

> 设备的云端身份只有一把 Ed25519 签名密钥和一把 X25519 加密密钥，没有学号，也没有姓名。注册需要完成一次工作量证明；插件 token 由签名质询换取，有效期 10 分钟。

Base URL: `https://{provider}` or `http://localhost:8787`

## POST /v1/devices

**Register a device** (`registerDevice`)

Registers a device identity. Authenticated by proof of work instead of a token: find a
decimal `nonce` such that `SHA-256(prefix ‖ UTF-8(nonce))` starts with at least
`pow.difficulty` zero bits (from `GET /v1/meta`), where

```
prefix = UTF-8("pku-harness-cloud/v1/pow\n" + salt + "\n" + signPub + "\n" + boxPub + "\n")
```

The server accepts its current salt and the previous one. Binding the keys into the prefix
means one solution registers exactly one identity. Clients refuse a difficulty above 28
(`MAX_POW_DIFFICULTY`); the default is 16 (about one second on a phone). Use `solvePow` from
`@pku-harness/cloud-protocol`.

Auth: none

Request body (`application/json`): `RegisterDeviceRequest`

- **200**: The server-generated device id. → `application/json` `RegisterDeviceResponse`
- **default**: see [Error](#response-error) below

## POST /v1/auth/token

**Mint a plugin token** (`createToken`)

Exchanges an Ed25519-signed challenge for a 10-minute bearer token bound to one device, one
plugin and a set of services (claims `sub = deviceId`, `plg = plugin`, `svc = services`).
The signed bytes are these lines joined by `\n` (no trailing newline):

```
pku-harness-cloud/v1/auth
<aud>        provider origin, lowercase scheme://host[:port], no path
<deviceId>
<plugin>
<services>   deduplicated, sorted, joined by ","
<ts>         Unix ms, decimal
<nonce>      16 random bytes, base64url
```

The server compares `aud` with its own origin, accepts `|now − ts| ≤ 5 min` and rejects a
reused nonce within that window. Use `signAuthChallenge` from
`@pku-harness/cloud-protocol`.

Auth: none

Request body (`application/json`): `AuthTokenRequest`

- **200**: A bearer token for this plugin's requests. → `application/json` `AuthTokenResponse`
- **default**: see [Error](#response-error) below

## DELETE /v1/devices/me

**Delete this device and all its data** (`deleteDevice`)

Wipes every record of the device (store, channels, push schedules). Any plugin token of the device works. The app calls it from Settings → 删除云端数据 and before a full reset.

Auth: `pluginToken`

- **200**: Deleted. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### AuthTokenRequest

```ts
type AuthTokenRequest = {
  aud: string; // pattern `^https?:\/\/[a-z0-9.\-:[\]]+$`
  deviceId: DeviceId;
  plugin: PluginId;
  services: CloudService[]; // minItems 1
  ts: Ms;
  nonce: Nonce16;
  sig: Sig64;
};
```

### AuthTokenResponse

```ts
type AuthTokenResponse = {
  token: string; // minLength 16
  expiresAt: Ms;
};
```

### CloudService

```ts
type CloudService = "store" | "channels" | "push" | "files" | "functions";
```

### DeviceId

Server-generated, base64url. pattern `^[A-Za-z0-9_-]{8,64}$`

```ts
type DeviceId = string;
```

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### Key32

32 bytes, base64url (Ed25519 or X25519 public key, hash). pattern `^[A-Za-z0-9_-]{43}$`

```ts
type Key32 = string;
```

### Ms

Unix time in milliseconds. minimum 0

```ts
type Ms = number;
```

### Nonce16

16 bytes, base64url. pattern `^[A-Za-z0-9_-]{22}$`

```ts
type Nonce16 = string;
```

### Ok

```ts
type Ok = {
  ok: true;
};
```

### PluginId

Registry id rule, plus `mcp-…` host ids for remote plugins. pattern `^[a-z0-9][a-z0-9-]{1,63}$`

```ts
type PluginId = string;
```

### RegisterDeviceRequest

```ts
type RegisterDeviceRequest = {
  signPub: Key32;
  boxPub: Key32;
  pow: {
    salt: string; // pattern `^[A-Za-z0-9_-]{1,64}$`
    nonce: string; // pattern `^(0|[1-9][0-9]{0,14})$`
  };
};
```

### RegisterDeviceResponse

```ts
type RegisterDeviceResponse = {
  deviceId: DeviceId;
};
```

### Sig64

64-byte Ed25519 signature, base64url. pattern `^[A-Za-z0-9_-]{86}$`

```ts
type Sig64 = string;
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 服务端函数 (/docs/cloud/api/functions)

> 插件声明的服务端函数。参考服务器已经实现，但生产配置默认关闭（`CLOUD_FN_POLICY=allowlist`，列表为空），官方服务器也不会开放；自建服务器可以自行开启。

Base URL: `https://{provider}` or `http://localhost:8787`

## POST /v1/fn/{plugin}/{name}

**Invoke a server function (planned)** (`invokeFunction`)

**Planned (stage 6).** The reference server answers `501 unsupported` until then. Runs a function the plugin declared in `CloudManifest.functions`, on
the user's provider. A function is `name@version`; the server keeps the previous major for
90 days. Default limit: 60 calls per minute.

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `plugin` | path | `PluginId` | yes |  |
| `name` | path | `FunctionName` | yes |  |

Request body (`application/json`): `FunctionRequest`

- **200**: The function output. → `application/json` `FunctionResponse`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### FunctionName

pattern `^[a-zA-Z][a-zA-Z0-9_]{0,63}$`

```ts
type FunctionName = string;
```

### FunctionRequest

```ts
type FunctionRequest = {
  input?: unknown;
  version?: number; // minimum 1
};
```

### FunctionResponse

```ts
type FunctionResponse = {
  output?: unknown;
};
```

### PluginId

Registry id rule, plus `mcp-…` host ids for remote plugins. pattern `^[a-z0-9][a-z0-9-]{1,63}$`

```ts
type PluginId = string;
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 元数据 (/docs/cloud/api/meta)

> 服务商发现。用户连接服务商时，宿主会读取它并检查 `protocol`、`services` 和 `limits`。

Base URL: `https://{provider}` or `http://localhost:8787`

## GET /v1/meta

**Provider metadata** (`getMeta`)

Protocol version, offered services, limits, proof-of-work parameters, viewer pages, server functions and the operator. No authentication.

Auth: none

- **200**: Provider metadata. → `application/json` `MetaResponse`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### CloudService

```ts
type CloudService = "store" | "channels" | "push" | "files" | "functions";
```

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### FunctionName

pattern `^[a-zA-Z][a-zA-Z0-9_]{0,63}$`

```ts
type FunctionName = string;
```

### Limits

Defaults (`DEFAULT_LIMITS`): store 1,000,000 bytes / 1,000 keys / 64,000 bytes per value; channels 5 open, TTL 60–86,400 s (default 900), 5 peers, 4,096-byte frames, 60 frames/min, 64 mailbox slots; push 100 pending; functions 60 calls/min; 20 joins per IP per minute.

```ts
type Limits = {
  store: {
    maxBytes: number;
    maxKeys: number;
    maxValueBytes: number;
  };
  channels: {
    maxOpen: number;
    minTtlS: number;
    maxTtlS: number;
    defaultTtlS: number;
    maxPeers: number;
    frameBytes: number;
    framesPerMin: number;
    mailboxSlots: number;
  };
  push?: {
    maxPending: number;
  };
  functions?: {
    callsPerMin: number;
  };
  joinsPerIpPerMin: number;
};
```

### MetaResponse

```ts
type MetaResponse = {
  protocol: 1;
  services: CloudService[];
  limits: Limits;
  pow: {
    difficulty: number; // minimum 0, maximum 64
    salt: string; // pattern `^[A-Za-z0-9_-]{1,64}$`
  };
  pages: {
    plugin: PluginId;
    page: PageName;
  }[];
  functions: {
    plugin: PluginId;
    name: FunctionName;
    version: number; // minimum 1
  }[];
  operator: {
    name: string; // minLength 1
    contact: string;
    privacyURL?: string;
  };
};
```

### PageName

pattern `^[a-z0-9][a-z0-9-]{0,40}$`

```ts
type PageName = string;
```

### PluginId

Registry id rule, plus `mcp-…` host ids for remote plugins. pattern `^[a-z0-9][a-z0-9-]{1,63}$`

```ts
type PluginId = string;
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 分享链接与页面 (/docs/cloud/api/pages)

> 给没装 App 的人用的公开跳转和静态查看页。

Base URL: `https://{provider}` or `http://localhost:8787`

## GET /s/{id}

**Open a share link** (`shareRedirect`)

Redirects to the viewer page the channel was opened with, `/w/<plugin>/<page>?c=<id>`. The browser keeps the `#k=` fragment across the redirect; the server never sees it.

Auth: none

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

- **302**: Redirect to the plugin's viewer page.
- **default**: see [Error](#response-error) below

## GET /w/{plugin}/{page}

**Static viewer page** (`viewerPage`)

A static page built from `plugins/<id>/web` and listed in `CloudManifest.pages`, served with a strict CSP (`connect-src 'self'`). It reads `#k` from `location.hash`, decrypts locally with `@pku-harness/cloud-protocol` and talks to `/v1/c/{id}/…`.

Auth: none

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `plugin` | path | `PluginId` | yes |  |
| `page` | path | `PageName` | yes |  |

- **200**: The page. → `text/html` `string`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### ChannelId

Server-generated, base64url (16 random bytes → 22 characters). pattern `^[A-Za-z0-9_-]{8,64}$`

```ts
type ChannelId = string;
```

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### PageName

pattern `^[a-z0-9][a-z0-9-]{0,40}$`

```ts
type PageName = string;
```

### PluginId

Registry id rule, plus `mcp-…` host ids for remote plugins. pattern `^[a-z0-9][a-z0-9-]{1,63}$`

```ts
type PluginId = string;
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 通道（对端） (/docs/cloud/api/peers)

> 查看方（网页或另一个 App）打开分享链接 `https://<provider>/s/<id>#k=<secret>` 后调用的接口。片段 `k` 不会发到服务器，查看方用它推导出 `authKey` 来加入通道。

Base URL: `https://{provider}` or `http://localhost:8787`

## GET /v1/c/{id}

**Public channel info** (`getChannelInfo`)

What a viewer reads before joining. `meta` is sealed with `encKey`, so only someone holding the link can read it. Public and rate-limited (20 requests per IP per minute by default).

Auth: none

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

- **200**: Channel status, sealed meta and the channel public key. → `application/json` `ChannelInfoResponse`
- **default**: see [Error](#response-error) below

## POST /v1/c/{id}/join

**Join a channel** (`joinChannel`)

Claims a seat. The server checks `sha256(authKey)` against the channel's `joinHash` and
enforces `maxPeers`: when the channel is full the answer is `409 conflict`, so a forwarded
link is useless once the first viewer claimed it. `peerPub` is the viewer's ephemeral X25519
key.

Auth: none

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

Request body (`application/json`): `JoinRequest`

- **200**: The peer id and a peer token for the socket, SSE stream, send and mailbox endpoints. → `application/json` `JoinResponse`
- **default**: see [Error](#response-error) below

## GET /v1/c/{id}/ws

**Peer WebSocket** (`peerSocket`)

Upgrades to a WebSocket for a joined peer.

- Server → peer: `PeerInFrame` (`hello`, `owner` online state, `extended`, `msg`, `closed`, `error`, `pong`).
- Peer → server: `PeerOutFrame` (`msg`, `ping`).

Auth: none

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |
| `t` | query | `string` | yes | The `peerToken` from `POST /v1/c/{id}/join`. minLength 16 |

- **101**: Switching to the WebSocket protocol. Frames are described by the `PeerInFrame` and `PeerOutFrame` schemas.
- **default**: see [Error](#response-error) below

## GET /v1/c/{id}/events

**Peer event stream (SSE)** (`peerEvents`)

Fallback for webviews without WebSocket (WeChat). Each `data:` line is one `PeerInFrame` as JSON. Send with `POST /v1/c/{id}/send`.

Auth: none

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |
| `t` | query | `string` | yes | The `peerToken` from `POST /v1/c/{id}/join`. minLength 16 |

- **200**: Server-sent events. → `text/event-stream` `PeerInFrame`
- **default**: see [Error](#response-error) below

## POST /v1/c/{id}/send

**Send a frame (SSE clients)** (`peerSend`)

The body is one `PeerOutFrame`, as it would be sent on the WebSocket.

Auth: `peerToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

Request body (`application/json`): `PeerOutFrame`

- **200**: Accepted. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## GET /v1/c/{id}/mailbox

**Read the mailbox** (`peerMailbox`)

Batch mode. The sealed blobs the owner left in the channel's mailbox.

Auth: `peerToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | `ChannelId` | yes |  |

- **200**: Mailbox slots. → `application/json` `MailboxListResponse`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### ChannelId

Server-generated, base64url (16 random bytes → 22 characters). pattern `^[A-Za-z0-9_-]{8,64}$`

```ts
type ChannelId = string;
```

### ChannelInfoResponse

```ts
type ChannelInfoResponse = {
  status: ChannelStatus;
  meta: Envelope;
  chanPub: Key32;
  expiresAt: Ms;
  ownerOnline: boolean;
};
```

### ChannelStatus

```ts
type ChannelStatus = "open" | "closed" | "expired";
```

### CloseReason

```ts
type CloseReason = "owner" | "expired" | "revoked" | "locked" | "server";
```

### Envelope

XChaCha20-Poly1305 sealed JSON. `n` = 24-byte random nonce, `c` = ciphertext ‖ 16-byte tag. Open it with `open()` from `@pku-harness/cloud-protocol` and validate the result.

```ts
type Envelope = {
  v: 1;
  n: Nonce24;
  c: string; // pattern `^[A-Za-z0-9_-]*$`, minLength 22
};
```

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### JoinRequest

```ts
type JoinRequest = {
  authKey: Key32;
  peerPub: Key32;
};
```

### JoinResponse

```ts
type JoinResponse = {
  peerId: PeerId;
  peerToken: string; // minLength 16
  expiresAt: Ms;
};
```

### Key32

32 bytes, base64url (Ed25519 or X25519 public key, hash). pattern `^[A-Za-z0-9_-]{43}$`

```ts
type Key32 = string;
```

### MailboxListResponse

```ts
type MailboxListResponse = {
  items: {
    slot: MailboxSlot;
    env: Envelope;
    expiresAt: Ms;
  }[];
};
```

### MailboxSlot

pattern `^[A-Za-z0-9._:-]{1,64}$`

```ts
type MailboxSlot = string;
```

### Ms

Unix time in milliseconds. minimum 0

```ts
type Ms = number;
```

### Nonce24

24 bytes, base64url. pattern `^[A-Za-z0-9_-]{32}$`

```ts
type Nonce24 = string;
```

### Ok

```ts
type Ok = {
  ok: true;
};
```

### PeerId

pattern `^[A-Za-z0-9_-]{4,64}$`

```ts
type PeerId = string;
```

### PeerInFrame

Server → peer frame (WebSocket message or SSE `data:` line).

```ts
type PeerInFrame = {
  t: "hello";
  peerId: PeerId;
  ownerOnline: boolean;
  expiresAt: Ms;
} | {
  t: "owner";
  online: boolean;
} | {
  t: "extended";
  expiresAt: Ms;
} | {
  t: "msg";
  env: Envelope;
} | {
  t: "closed";
  reason: CloseReason | "kicked";
} | {
  t: "error";
  code: WireErrorCode;
  message: string;
} | {
  t: "pong";
  at: Ms;
};
```

### PeerOutFrame

Peer → server frame (WebSocket message, or the body of `POST /v1/c/{id}/send`).

```ts
type PeerOutFrame = {
  t: "msg";
  env: Envelope;
} | {
  t: "ping";
};
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 推送（规划中） (/docs/cloud/api/push)

> 推送 token 和定时推送，载荷端到端加密。尚未实现，参考服务器对这些接口返回 `501 unsupported`。

Base URL: `https://{provider}` or `http://localhost:8787`

## POST /v1/push/tokens

**Register a push token (planned)** (`registerPushToken`)

**Planned (stage 6);** `501 unsupported` until then. UnifiedPush (ntfy) on Android, APNs on iOS, FCM optional.

Auth: `pluginToken`

Request body (`application/json`): `PushTokenRequest`

- **200**: Registered. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## POST /v1/push/schedule

**Schedule a push (planned)** (`schedulePush`)

**Planned (stage 6);** `501 unsupported` until then. The payload is an envelope: the server learns the time only. At most 100 pending schedules.

Auth: `pluginToken`

Request body (`application/json`): `PushScheduleRequest`

- **200**: The schedule id. → `application/json` `PushScheduleResponse`
- **default**: see [Error](#response-error) below

## DELETE /v1/push/schedule

**Cancel a scheduled push (planned)** (`cancelPush`)

**Planned (stage 6);** `501 unsupported` until then.

Auth: `pluginToken`

Request body (`application/json`): `PushCancelRequest`

- **200**: Cancelled. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### Envelope

XChaCha20-Poly1305 sealed JSON. `n` = 24-byte random nonce, `c` = ciphertext ‖ 16-byte tag. Open it with `open()` from `@pku-harness/cloud-protocol` and validate the result.

```ts
type Envelope = {
  v: 1;
  n: Nonce24;
  c: string; // pattern `^[A-Za-z0-9_-]*$`, minLength 22
};
```

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### Ms

Unix time in milliseconds. minimum 0

```ts
type Ms = number;
```

### Nonce24

24 bytes, base64url. pattern `^[A-Za-z0-9_-]{32}$`

```ts
type Nonce24 = string;
```

### Ok

```ts
type Ok = {
  ok: true;
};
```

### PushCancelRequest

```ts
type PushCancelRequest = {
  id: string; // minLength 1
};
```

### PushScheduleRequest

```ts
type PushScheduleRequest = {
  at: Ms;
  payload: Envelope;
};
```

### PushScheduleResponse

```ts
type PushScheduleResponse = {
  id: string; // minLength 1
};
```

### PushTokenRequest

```ts
type PushTokenRequest = {
  kind: "unifiedpush" | "apns" | "fcm";
  token: string; // minLength 1, maxLength 2048
};
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# 存储 (/docs/cloud/api/store)

> 键值存储，命名空间 `(deviceId, plugin)` 取自 token，而不是路径。插件声明了 `e2e` 时，值都是信封。

Base URL: `https://{provider}` or `http://localhost:8787`

## GET /v1/store

**List keys** (`listStore`)

Keys of the calling `(device, plugin)` namespace, optionally filtered by prefix. Values are not included.

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `prefix` | query | `string` | no | Only keys starting with this string. |

- **200**: Matching keys. → `application/json` `StoreListResponse`
- **default**: see [Error](#response-error) below

## GET /v1/store/{key}

**Read a value** (`getStoreValue`)

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `key` | path | `StoreKey` | yes | Path-like key (`/` allowed, each segment URL-encoded), no `.` or `..` segments. |

- **200**: The value with its version. → `application/json` `StoreGetResponse`
- **default**: see [Error](#response-error) below

## DELETE /v1/store/{key}

**Delete a value** (`deleteStoreValue`)

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `key` | path | `StoreKey` | yes | Path-like key (`/` allowed, each segment URL-encoded), no `.` or `..` segments. |

- **200**: Deleted. → `application/json` `Ok`
- **default**: see [Error](#response-error) below

## PUT /v1/store/{key}

**Write a value** (`putStoreValue`)

Creates or replaces a value. Optimistic concurrency with `If-Match: <version>`: the write
fails with `409 conflict` unless the stored version matches; `If-Match: 0` means the key must
not exist yet. Default quotas: 1 MB and 1,000 keys per plugin per device, 64 KB per value
(`limits.store` in `GET /v1/meta`).

Auth: `pluginToken`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `key` | path | `StoreKey` | yes | Path-like key (`/` allowed, each segment URL-encoded), no `.` or `..` segments. |
| `If-Match` | header | `string` | no | Expected current version; `0` = the key must not exist. pattern `^[0-9]+$` |

Request body (`application/json`): `StorePutRequest`

- **200**: The new version (also sent as the `ETag` header). → `application/json` `StorePutResponse`
- **default**: see [Error](#response-error) below

## Response: Error

Any error. `error.code` maps to HTTP statuses as usual (`bad_request` 400, `unauthorized`
401, `forbidden` 403, `not_found` 404, `conflict` 409, `gone` 410, `payload_too_large` 413,
`rate_limited` 429). A 429 carries `Retry-After` and `RateLimit-*` headers; the SDK turns it
into `CloudError('rate_limited', retryAfterS)`.

Body: `application/json` `ErrorBody`

## Schemas

### ErrorBody

```ts
type ErrorBody = {
  error: {
    code: WireErrorCode;
    message: string;
    retryAfterS?: number; // minimum 0
  };
};
```

### Ms

Unix time in milliseconds. minimum 0

```ts
type Ms = number;
```

### Ok

```ts
type Ok = {
  ok: true;
};
```

### StoreGetResponse

```ts
type StoreGetResponse = {
  key: StoreKey;
  value?: unknown;
  version: number; // minimum 1
  updatedAt: Ms;
  expiresAt?: Ms;
};
```

### StoreKey

Path-like key; no `.` or `..` segments. pattern `^[A-Za-z0-9._:/-]{1,256}$`

```ts
type StoreKey = string;
```

### StoreListResponse

```ts
type StoreListResponse = {
  items: {
    key: StoreKey;
    version: number; // minimum 1
    updatedAt: Ms;
  }[];
  cursor?: string;
};
```

### StorePutRequest

```ts
type StorePutRequest = {
  value?: unknown;
  ttlS?: number; // minimum 1
};
```

### StorePutResponse

```ts
type StorePutResponse = {
  version: number; // minimum 1
};
```

### WireErrorCode

`unauthorized`: missing or expired token, bad signature. `forbidden`: the token lacks the
service, not the owner, wrong `authKey`. `gone`: channel closed or expired. `conflict`:
`If-Match` mismatch, or the channel is full (`maxPeers`). `unsupported`: service not
offered by this provider.

```ts
type WireErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "conflict" | "payload_too_large" | "rate_limited" | "quota" | "pow_invalid" | "unsupported" | "server";
```

# PKU harness Cloud (/docs/cloud)

> PKU harness Cloud 是一套可选的插件后端标准，包含存储、中继通道、推送、文件和服务端函数。官方实例、自建服务器或任何符合标准的服务器都可以提供这些服务。数据默认端到端加密，云端不保存校园身份。

大多数插件只在手机上运行，但有些功能需要服务器。例如，把校园卡付款码实时分享给一位没有安装 App 的朋友，或者在几台设备之间同步一小份数据。PKU harness Cloud（下文简称「云服务」）是为这类功能制定的一套后端标准。它规定了服务器要提供哪些接口，以及 App 和插件如何使用这些接口。

设计云服务时，我们的目标是让你在使用服务器的同时不必信任它。下面几段说明这一点是怎样做到的。

## 设计原则

数据在离开手机之前就已经加密。这种方式叫作端到端加密（end-to-end encryption，E2E）：只有发送方和接收方持有密钥，服务器只负责转发和保存密文，自己无法解密。

云端不保存你的校园身份。服务器只通过设备生成的一对密钥来识别设备，不知道你的学号和姓名，也收不到你的校园账号密码或登录会话。

同一份协议可以由多家服务商提供。你可以使用官方实例、自己部署的参考服务器，或者任何实现了这份协议的服务器地址。插件调用的接口完全相同，也无法分辨当前连接的是哪一家。

App 会把各个插件隔离开。App 是运行插件的一方，我们称它为「宿主」。宿主给每个插件一个只属于它自己的云服务客户端，每个插件有独立的 token、独立的存储空间，并且要单独获得你的授权。

AI 助手只能通过插件提供的工具使用云服务。它看不到云服务的凭据和 token，也看不到分享链接。

<Callout title="当前进度（2026-10-24）">
  官方云服务实例还没有部署。在它上线之前，如果要使用云服务，请在「设置 → 云服务」里填写自建服务器的 URL。

  已经完成的部分有：协议 v1（`@pku-harness/cloud-protocol`）、SDK 类型、参考服务器（`packages/cloud-server`），以及 App 内的云服务客户端。客户端支持设备身份、按插件绑定和授权、端到端加密的存储与通道，并在「设置 → 云服务」里提供连接测试。第一个使用云服务的插件是 `card-share`，它实时分享校园卡付款码，全程端到端加密。推送服务（`push`）还没有完成，参考服务器目前对它返回 `501 unsupported`。

  官方实例上线后会刻意保持精简，只提供三样东西：实时分享用的中继（通道和信箱，服务器只转发看不懂的密文），小容量的端到端加密存储，以及静态查看页。插件的[服务端函数](#server-functions)已经在参考服务器里实现，但官方服务器不开启这项功能。
</Callout>

## 三个组成部分

云服务由三部分组成。第一部分是服务定义，也就是 SDK 里的类型和一份带版本号的 HTTP 协议。第二部分是服务商，即真正运行服务器的一方。第三部分是使用方，也就是调用云服务的插件。

| 部分 | 内容 | 位置 |
| --- | --- | --- |
| 服务定义 | SDK 类型（`CloudManifest`、`PluginCloud`）和 HTTP 协议（`/v1`） | `@pku-harness/sdk`（`cloud.ts`）、`@pku-harness/cloud-protocol`、[API 参考](/docs/cloud/api/meta) |
| 服务商 | 官方实例、开源参考服务器（自建）、任何符合标准的 URL | [服务商与自建](/docs/cloud/providers) |
| 使用方 | 插件，通过 `ctx.cloud` 或 `props.cloud` 访问 | [插件指南](/docs/cloud/plugin-guide) |

## 云服务提供的服务

协议定义了五种服务。服务商可以只提供其中一部分。

`store` 是键值存储。每台设备上的每个插件各有一块独立的空间，按 `(device, plugin)` 划分。它支持版本号（`If-Match`）和过期时间（time to live，TTL）。如果插件声明了 `e2e`，值会先在手机上加密再上传。

`channels` 是实时分享用的中继通道。设备开一个通道，查看者用分享链接加入，服务器在两者之间转发数据帧。通道始终端到端加密，每个查看者的密钥都由分享链接里的密钥派生。

`push` 用于推送 token 和定时推送。这项服务还在计划中，官方实例不会提供。推送内容会加密，服务器只知道发送时间。

`files` 是文件存储，目前也在计划中。

`functions` 是插件在 `PLUGIN.md` 的 `server:` 段里声明的服务端函数，[下文](#server-functions)有详细说明。官方服务器不开启这项功能。服务端函数必须事先声明并经你同意，它也是整个云服务里唯一可能处理明文的地方。

App 通过 `GET /v1/meta` 查询服务商提供哪些服务。如果插件在 `uses` 里列出的某项服务对方不提供，App 会把这个插件标为不可用，并说明原因。

## 一次请求的流程

下面以插件写入一条存储为例。插件调用 `ctx.cloud.store.put`，宿主先检查授权、插件清单里的 `uses` 和 `e2e`。如果插件声明了 `e2e`，宿主用 XChaCha20-Poly1305 算法加密这个值。然后宿主用设备的 Ed25519 密钥签名一段挑战，换取一个有效期 10 分钟的 token，附在请求上发给服务商。服务商从 token 里读出设备和插件，确定存储空间，最后把密文保存下来。

```
plugin ──ctx.cloud.store.put(key, value)──► host（为这个插件绑定的客户端）
          │ 检查授权、清单里的 `uses` 和 `e2e`
          │ 声明了 e2e 时加密值（XChaCha20-Poly1305）
          │ 签发或刷新 10 分钟有效的 token（Ed25519 签名挑战）
          ▼
        provider  PUT /v1/store/<key>   Authorization: Bearer <token>
          │ 存储空间 = token 里的 (deviceId, plugin)
          ▼
        保存密文
```

## 服务端代码在哪里运行

插件需要服务器参与时，有三种做法。我们建议按下面的顺序考虑。

1. 标准服务，包括 store、channels、mailbox、push 和 files。每个符合标准的服务器都会实现它们，服务器上不运行任何插件代码。能用这一层解决问题时，请优先使用它。
2. 插件服务端函数，写在 `PLUGIN.md` 的 `server:` 段里。服务器用和 App 相同的解释器执行它们。官方服务器不开启这项功能。
3. 外部后端，即任何实现了这份协议的 URL。插件要在清单里声明它（`backend: { kind: 'external', url }`），并经你同意后才能使用。

## 服务端函数

<Callout type="warn" title="官方服务器不开启">
  请让插件在手机端完成工作，或者使用你自己的后端。设计文档 [`docs/CLOUD-FUNCTIONS.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/CLOUD-FUNCTIONS.md) 已暂停推进：已有的功能保留，但集合、定时任务、推送、群组和 webhook 都不再开发。
</Callout>

插件文档可以声明服务端函数。服务端函数使用的步骤和表达式与插件工具相同，只是在服务器上执行。下面是一个例子：

```yaml title="PLUGIN.md（frontmatter 节选）"
cloud:
  disclosure: { zh: ['你输入的名字会发到云端服务器。'], en: ['The name you enter is sent to the cloud server.'] }
server:
  network: [api.example.org]        # 服务端步骤可以访问的主机（HTTPS）
  secrets: [API_KEY]                # 由运营者保管，只能在请求模板里使用
  functions:
    stats:
      effect: read
      access: public                # 目前支持 user（默认）和 public；peer、group、webhook 尚不支持
      cache: 30s
      steps:
        - let: c
          request: { url: 'https://api.example.org/v1/count', headers: { authorization: 'Bearer ${secrets.API_KEY}' } }
          as: json
      return: "{ count: c.count }"
```

使用服务端函数时要注意以下几点：

- 写了 `server:` 段，就等于声明了 `cloud.uses: [functions]`，并且必须同时写 `cloud.disclosure`。
- 服务端步骤有自己的一组宿主能力：按用户隔离的服务端键值存储（`kv.get/set/delete`），以及 `crypto.sha256`、`crypto.hmacSha256`（按名字引用密钥）和 `crypto.randomId`。服务端步骤访问不了校园服务。`caller.id` 是设备在这个插件下的假名。
- 手机端通过 `cloud.call { fn, input }` 能力调用函数。小组件也可以绑定 `{ fn }`，而不只是 `{ tool }`。
- token 里记录了你同意时的插件文档版本（链接加内容哈希），服务器只运行这个版本。是否运行还取决于运营者的策略 `CLOUD_FN_POLICY`，可选值为 `verified`、`allowlist` 和 `open`。相关环境变量见参考服务器的 README。

## 继续阅读

- [插件指南](/docs/cloud/plugin-guide)：声明 `cloud`、获取授权、使用 `store` 和 `channels`。
- [安全](/docs/cloud/security)：设备密钥、工作量证明、token、信封和分享链接。
- [服务商与自建](/docs/cloud/providers)：选择服务商，以及运行参考服务器。
- [`@pku-harness/cloud-protocol`](/docs/cloud/protocol-package)：服务器和查看页共用的 schema 与加密实现。
- [API 参考](/docs/cloud/api/meta)：全部接口，由 OpenAPI 3.1 规范生成。


# 插件指南 (/docs/cloud/plugin-guide)

> 在内置插件里使用 PKU harness Cloud：声明云服务清单和数据说明，处理授权与可用性，使用存储和中继通道，并安全地展示分享链接。

本页说明内置插件（用 TypeScript 编写、随 App 打包的插件）怎样使用云服务。我们以 `card-share` 插件为例，它把校园卡付款码实时分享给朋友。下面的步骤按开发顺序排列：先在清单里声明，再处理授权和可用性，然后使用存储或通道。

## 1. 在清单里声明云服务

插件要在 `definePlugin` 的 `cloud` 字段里说明自己用到哪些云服务、数据是否端到端加密，以及哪些数据会离开设备。宿主（运行插件的 App）会按这份声明限制插件的调用，并把其中的说明展示给你。

```ts
import { definePlugin } from '@pku-harness/sdk';

export const cardSharePlugin = definePlugin({
  id: 'card-share',
  name: '付款码共享',
  description: '把校园卡付款码实时分享给朋友，端到端加密。',
  version: '0.1.0',
  requires: ['campus-session', 'network', 'cloud'],
  cloud: {
    protocol: 1,
    uses: ['channels'],
    e2e: true,
    pages: ['view'],
    disclosure: {
      zh: ['分享期间，加密后的付款码经云服务转发给你分享的人；服务器无法解密', '服务器能看到：分享的开始/结束时间、查看者的 IP'],
      en: ['While sharing, encrypted payment codes are relayed to the person you shared with; the server can’t decrypt them', 'The server sees when a share starts and ends, and the viewer’s IP address'],
    },
  },
  defaultModes: { read: 'auto', write: 'auto', money: 'ask' },
  scopes: ['bdcard.pku.edu.cn'],
  tools: { /* … */ },
});
```

各字段的规则如下：

| 字段 | 规则 |
| --- | --- |
| `protocol` | 固定为 `1` |
| `uses` | 只列出你实际调用的服务。调用未列出的服务会被宿主拒绝。 |
| `disclosure.zh` | `uses` 不为空时必填，说明见下文。 |
| `e2e` | 设为 `true` 后，宿主会拒绝明文写入存储。只要可行，就应该开启。 |
| `optional` | 插件不依赖云服务也能工作时设为 `true`。 |
| `pages` | 给没装 App 的人使用的静态查看页，源码在 `plugins/<id>/web`，部署在 `/w/<plugin>/<page>`。 |
| `functions`、`backend` | 服务端函数，或外部后端 URL。外部后端会在你授权前展示出来。 |

`disclosure` 是写给用户看的数据说明。请用通俗的话写清楚哪些数据会离开设备、服务器能看到什么，每行只写一件事。如果同时写了 `en`，英文必须与中文逐行对应。

如果设置了 `optional: true`，就不要在 `requires` 里写 `'cloud'`，并在使用前检查 `ctx.cloud?.available`。服务端函数在官方服务器上不开启，见[下文](#server-functions)。

## 2. 获取用户授权

每个插件都要单独获得用户授权。在设置里打开插件的详情页，可以看到一个**云服务**区块。它显示服务商的主机名、你写的数据说明、端到端加密标识、用到的服务和配额用量，并提供**允许使用云服务**开关和**清除此插件云端数据**按钮。

用户允许之前，插件的所有云服务调用都会抛出 `CloudError('consent_required')`。在页面里，你可以先调用 `cloud.requestConsent()` 询问用户。它会弹出宿主的授权面板，用户同意时返回 `true`，拒绝时返回 `false`。如果用户之前已经同意过，它会立即返回 `true`。

```tsx
const start = async () => {
  if (!(await props.cloud?.requestConsent())) return; // 用户拒绝，或者当前宿主没有云服务
  const channel = await props.cloud!.channels.open({ ttlS: 30 * 60, maxPeers: 1, page: 'view' });
  // …
};
```

AI 助手调用插件工具时，宿主不会弹出授权面板。工具里不需要特别处理，让错误直接抛出即可，助手会告诉用户去哪里开启授权。如果你想返回更明确的结果，也可以像下面这样捕获错误：

```ts
import { isCloudError } from '@pku-harness/sdk';

try {
  await ctx.cloud?.store.put('prefs', prefs);
} catch (e) {
  if (isCloudError(e, 'consent_required')) return { status: 'cloud_consent_required' };
  if (isCloudError(e, 'offline')) throw new Error('网络不可用，稍后再试');
  throw e;
}
```

## 3. 检查云服务是否可用

用户可能没有配置服务商、没有授权，或者服务商暂时连不上。这些情况下 `ctx.cloud?.available` 都是 `false`，插件应该直接返回明确的结果，不再发起调用。

```ts
const cloud = ctx.cloud;
if (!cloud?.available) {
  // 没有配置服务商、没有授权，或者连不上
  return { status: 'cloud_unavailable', provider: cloud?.status().provider ?? 'off' };
}
```

`status()` 返回 `{ provider: 'official' | 'custom' | 'off', baseURL?, consented, online }`。

手机离线时，各项操作的表现不同。存储的读操作会改为读取本地镜像。写操作和函数调用会立即以 `offline` 失败，宿主不会把它们放进待发队列，事后悄悄补发。通道会按退避策略自动重连。

## 4. 使用存储

存储是一个键值存储，适合保存小份的设置或状态。下面的例子读出一个计数器，加一后写回：

```ts
const cur = await ctx.cloud!.store.get<{ count: number }>('counter');
await ctx.cloud!.store.put('counter', { count: (cur?.value.count ?? 0) + 1 }, { ifVersion: cur?.version ?? 0 });
const keys = await ctx.cloud!.store.list('history/');
```

- 服务商按 `(device, plugin)` 划分命名空间，其他插件读不到你的数据。
- `ifVersion` 用来做乐观并发控制：只有当前版本与给出的版本一致时，写入才会成功。`0` 表示这个键必须还不存在。版本不一致时服务器返回 `409 conflict`，宿主会把它抛成 `CloudError('protocol')`。
- `ttlS` 设置值的有效期（秒），到期后自动删除。
- 默认配额是每台设备每个插件 1 MB、1,000 个键，单个值最大 64 KB。

## 5. 使用中继通道

通道在机主的手机和打开分享链接的人之间转发端到端加密的数据帧。服务商只负责转发密文，并控制谁能加入通道。只有持有分享链接的人才能解密。

```ts
const channel = await cloud.channels.open({
  ttlS: 30 * 60,          // 必填，60 秒到 24 小时
  maxPeers: 1,            // 第一个加入的人占住名额，转发出去的链接没有用
  page: 'view',           // 给没装 App 的人看的查看页
  meta: { nameHint: '王_明', pinRequired: true },  // 已加密；查看者加入前就能读到
});

const off = channel.on('message', (e) => {
  if (e.type !== 'message') return;
  const msg = frameSchema.safeParse(e.msg);  // 对端发来的帧一律先校验
  if (!msg.success) return;
  // …
});
channel.on('join', (e) => e.type === 'join' && void channel.send(e.peerId, { t: 'hello' }));

// 之后
await channel.extend(15 * 60);
await channel.close();
off();
```

通道还提供以下方法：

- `send(peerId | '*', msg)` 为每个对端分别加密并发送。每帧最大 4 KB，每分钟最多 60 帧。
- `mailbox.put(slot, msg, ttlS)` 留下一个加密数据块。你离线时，对端也能读到它。
- `kick(peerId)` 踢掉一个查看者并释放名额，之后同一个链接可以给新的查看者使用。
- `channels.get(id)` 和 `list()` 在 App 重启后依然有效，因为通道密钥保存在系统密钥库里。
- 在 Android 上做长时间分享时，用 `services.ongoing.start({ title, until, onStop })` 让 App 保持运行。`services.ongoing` 只在 Android 上存在。

### 展示分享链接

`channel.link` 是一个 `SecretLink` 对象。插件代码读不到其中的 URL，把它序列化也只会得到 `"[secret link]"`。要把链接交给用户，请使用宿主提供的组件：

```tsx
const { QRCode, Button } = host.components;
<QRCode link={channel.link} size={220} />
<Button title="分享给朋友" onPress={() => void host.shareLink?.(channel.link, { message: '我的付款码' })} />
```

不要从工具里返回链接，也不要把链接写进日志。工具应该返回 `{ status: 'awaiting_user' }`，然后打开一个页面，由用户在页面上完成分享。

## 6. 在注册表里登记

插件市场在安装前就会显示插件是否使用云服务。为此，请把云服务声明复制到你在 `registry.json` 里的条目中：

```json
{
  "id": "card-share",
  "cloud": {
    "uses": ["channels"],
    "e2e": true,
    "disclosure": { "zh": ["分享期间，加密后的付款码经云服务转发给你分享的人；服务器无法解密", "服务器能看到：分享的开始/结束时间、查看者的 IP"] }
  }
}
```

注册表校验器会检查三件事：`uses` 不为空时必须有 `disclosure.zh`；如果写了 `en`，必须与中文逐行对应；外部 `backend.url` 必须使用 HTTPS。

## 服务端函数

<Callout type="warn" title="官方服务器不开启">
  请让插件在手机端完成工作，或者使用你自己的后端。
</Callout>

`PLUGIN.md` 插件可以在 `server:` 段里声明服务端函数，使用的步骤和表达式与工具相同，再通过 `cloud.call { fn, input }` 能力调用。小组件也可以绑定 `{ fn }`。写了这一段就等于声明了 `uses: [functions]`，并且必须写 `disclosure`。

参考服务器在 `POST /v1/fn/<plugin>/<name>` 运行 `access: user` 的函数，在 `/v1/p/<plugin>/<name>` 运行 `access: public` 的函数。它为函数提供服务端键值存储、加密工具，以及访问已声明主机的 HTTPS 请求。详见[云服务 → 服务端函数](/docs/cloud#server-functions)和 [`docs/CLOUD-FUNCTIONS.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/CLOUD-FUNCTIONS.md)（已暂停推进）。

## 查看页

查看页是给没装 App 的人使用的网页。对方打开 `https://<provider>/s/<id>#k=…` 后，会被重定向到 `/w/<plugin>/<page>?c=<id>#k=…`。`#` 之后的部分叫作 URL 片段，它在重定向后依然保留，并且浏览器不会把它发给服务器。

请在 `plugins/<id>/web` 里把查看页做成静态站点，例如用 Vite + Preact。页面从 `location.hash` 读出 `k`，再用 [`@pku-harness/cloud-protocol`](/docs/cloud/protocol-package) 派生密钥、加入通道并解密。

查看页必须能在微信内置浏览器里运行，因此要注意两点。第一，不要依赖 WebCrypto，这个包使用的是纯 JavaScript 实现的 noble 加密库。第二，WebSocket 不可用时，要退回服务器推送事件（Server-Sent Events，SSE）。完整的查看页可以参考 `plugins/card-share/web`。


# cloud-protocol 包 (/docs/cloud/protocol-package)

> @pku-harness/cloud-protocol：App、服务商和查看页共用的 zod 线上 schema、路径构造函数、信封加密、分享链接工具、工作量证明和 token 挑战。

`@pku-harness/cloud-protocol` 是云服务协议的公共实现，包含线上数据的 schema、接口路径、加密、分享链接、工作量证明和 token 挑战。如果你在编写云服务的服务器，或者为插件编写查看页，就会用到它。

这个包用纯 TypeScript 编写，可以在 Hermes（React Native 的 JavaScript 引擎）、Bun 和浏览器里运行。App、参考服务器和查看页引用的是同一份代码，所以三者的线上格式和加密方式始终一致。它依赖 `@noble/ciphers`、`@noble/curves` 和 `@noble/hashes`（锁定版本），并把 `zod ^4` 作为 peer 依赖。插件一般不需要引用它，因为宿主会替插件完成云服务相关的工作。

它位于 [`pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 仓库的 `packages/cloud-protocol` 目录，没有发布到 npm。你可以在仓库检出里直接使用它（workspace 包名为 `@pku-harness/cloud-protocol`），也可以把 `src/` 目录复制到你的服务器或页面项目中。

## 模块

下表列出各模块的导出：

| 模块 | 导出 |
| --- | --- |
| `schemas.ts` | `PROTOCOL_VERSION`，所有请求、响应和帧的 schema（`metaResponse`、`registerDeviceRequest`、`authTokenRequest`、`storePutRequest`、`createChannelRequest`、`ownerInFrame`、`peerInFrame`……），各类 id 的 schema，`envelopeSchema`、`errorBody`、`wireErrorCode`、`DEFAULT_LIMITS`、`paths` |
| `crypto.ts` | `generateDeviceIdentity`、`generateSignKeyPair`、`generateBoxKeyPair`、`signPublicKey`、`boxPublicKey`、`sign`、`verify`、`seal` / `open`、`sealBytes` / `openBytes`、`EnvelopeError`、`hkdfSha256`、`sha256`、`generateShareSecret`、`deriveShareKeys`、`joinHash`、`ownerPeerKey`、`viewerPeerKey`、`derivePeerKey`、`KDF_INFO`、`KEY_BYTES`、`NONCE_BYTES`、`SIG_BYTES` |
| `link.ts` | `buildShareLink`、`buildAppShareLink`、`parseShareLink`、`parseKeyFragment`、`scrubShareLinks`、`SHARE_LINK_SCRUB_RE`、`CHANNEL_ID_RE`、`APP_SCHEME` |
| `pow.ts` | `solvePow`、`verifyPow`、`powHash`、`powPrefix`、`leadingZeroBits`、`DEFAULT_POW_DIFFICULTY`（16）、`MAX_POW_DIFFICULTY`（28）、`POW_CONTEXT` |
| `auth.ts` | `signAuthChallenge`、`verifyAuthChallenge`、`authChallengeBytes`、`normaliseAudience`、`AUTH_CONTEXT`、`AUTH_MAX_SKEW_MS`（5 分钟）、`AUTH_NONCE_BYTES`（16）、`TOKEN_TTL_S`（600） |
| `bytes.ts` | `toB64url`、`fromB64url`、`isB64url`、`utf8`、`fromUtf8`、`concatBytes`、`equalBytes`、`toHex` |

线上数据遵循以下约定：二进制数据使用不带填充的 base64url 编码；时间默认是 Unix 毫秒，字段名以 `S` 结尾的则是秒；解析时会丢弃未知的键。

## 示例：查看页加入通道并解密

下面的代码运行在查看页里。它从 URL 读出通道 id 和密钥，加入通道，然后解密收到的每一帧。

```ts
import {
  deriveShareKeys,
  envelopeSchema,
  fromB64url,
  generateBoxKeyPair,
  joinResponse,
  open,
  parseKeyFragment,
  paths,
  peerInFrame,
  channelInfoResponse,
  toB64url,
  viewerPeerKey,
} from '@pku-harness/cloud-protocol';

// 访问 GET /s/<id> 之后，页面位于 /w/<plugin>/<page>?c=<id>#k=<secret>
const channelId = new URLSearchParams(location.search).get('c')!;
const k = parseKeyFragment(location.hash);
if (!k) throw new Error('link has no key');
const { authKey, encKey } = deriveShareKeys(k);

const info = channelInfoResponse.parse(await (await fetch(paths.publicChannel(channelId))).json());
const meta = open(encKey, info.meta);          // 机主加密过的 meta（使用前务必校验）

const me = generateBoxKeyPair();
const joined = joinResponse.parse(
  await (
    await fetch(paths.join(channelId), {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ authKey: toB64url(authKey), peerPub: toB64url(me.publicKey) }),
    })
  ).json(),
);

const key = viewerPeerKey(me.secretKey, me.publicKey, fromB64url(info.chanPub), encKey);
const ws = new WebSocket(new URL(paths.peerWs(channelId, joined.peerToken), location.href).href.replace(/^http/, 'ws'));
ws.onmessage = (ev) => {
  const frame = peerInFrame.parse(JSON.parse(ev.data));
  if (frame.t === 'msg') console.log(open(key, envelopeSchema.parse(frame.env)));
};
```

参考服务器会把 `/s/<id>` 重定向到 `/w/<plugin>/<page>?c=<id>`。浏览器在重定向后会自动保留 `#k=` 这段 URL 片段，而片段不会发给服务器，所以服务器始终看不到密钥。

有些应用内置的浏览器不支持 WebSocket。这时改用 `GET /v1/c/{id}/events?t=`（服务器推送事件，Server-Sent Events，SSE）接收数据，用 `POST /v1/c/{id}/send` 发送数据。完整的查看页可以参考 `plugins/card-share/web`，它的界面移植自 pkubdcard。

## 示例：服务器校验 token 请求

下面的代码运行在服务器上。设备用签名挑战换取 token 时，服务器先校验签名和时间，再检查 nonce 是否被用过，最后签发 token。

```ts
import { authTokenRequest, fromB64url, verifyAuthChallenge } from '@pku-harness/cloud-protocol';

const body = authTokenRequest.parse(await req.json());
const device = await db.device(body.deviceId);           // 注册时保存的 signPub
const check = verifyAuthChallenge(body, fromB64url(device.signPub), { aud: 'https://cloud.example.org' });
if (!check.ok) return error(401, 'unauthorized', check.reason);
if (await nonces.seen(body.nonce)) return error(401, 'unauthorized', 'replay');
// 签发 token，声明为 { sub: deviceId, plg: plugin, svc: services, iat, exp: iat + 600_000 }
```

全部接口见 [API 参考](/docs/cloud/api/meta)。


# 服务商与自建 (/docs/cloud/providers)

> 如何选择官方实例、自建参考服务器或任何符合标准的 URL，服务商需要实现哪些接口，以及如何运行和配置参考服务器。

提供云服务的服务器叫作服务商。PKU harness 不绑定某一家服务商：只要服务器实现了云服务协议，App 就能使用它。本页前半部分面向用户，说明如何选择服务商；后半部分面向运营者，说明服务商要实现什么，以及如何运行开源的参考服务器。

## 选择服务商（用户）

在「设置 → 云服务」里有三个选项。

**官方**是由 pkuinfo 运营的实例，目前还没有部署。它上线后会保持精简，只提供实时分享用的中继、小容量的端到端加密存储和查看页。在你主动开启之前，它默认处于关闭状态。

**自建**需要你填写一个基础 URL。点**测试连接**后，App 会显示这个服务商在 `/v1/meta` 里返回的运营者、服务和限额。

**关闭**表示不使用云服务。必须依赖云服务的插件会变为不可用；云服务对其可选的插件照常在本地工作。

URL 必须使用 HTTPS。开发版额外允许 `http://10.0.2.2:*`、`http://localhost:*` 和 `http://127.0.0.1:*`。切换服务商不会迁移数据，因为每家服务商上的设备身份和存储都是独立的。

## 服务商需要实现什么

服务商需要实现 [API 参考](/docs/cloud/api/meta)里的全部接口，并用 [`@pku-harness/cloud-protocol`](/docs/cloud/protocol-package) 的 schema 校验数据。具体包括：

- `GET /v1/meta`。它返回 `protocol: 1`、提供的服务、限额、工作量证明参数、查看页、函数，以及运营者信息（`name`、`contact`，可选 `privacyURL`）。
- 设备注册和 token 签发。注册时设备要先完成工作量证明。设备用签名换取 token 时，`aud` 必须是你自己的源，允许 5 分钟的时钟偏差，并防止 nonce 重放。token 的有效期为 10 分钟。
- 你在 `services` 里列出的服务。服务商可以只提供其中一部分，`uses` 没有被完全覆盖的插件会被标为不可用。
- 统一的错误响应体 `{ error: { code, message, retryAfterS? } }`，以及 `Retry-After` 和 `RateLimit-*` 响应头。
- `/w/<plugin>/<page>` 下的静态查看页，并带有严格的内容安全策略（Content Security Policy，CSP）；以及 `GET /s/:id` 重定向。

## 参考服务器

开源的参考服务器位于 [`pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/packages/cloud-server) 仓库的 `packages/cloud-server` 目录。它基于 Bun、Hono 和 `bun:sqlite`（WAL 模式），并用 `@pku-harness/cloud-protocol` 的 schema 校验每个请求和响应。

参考服务器声明提供 `store`、`channels` 和 `functions` 三项服务，`push` 目前返回 `501 unsupported`。插件服务端函数（`/v1/fn`、`/v1/p`）受 `CLOUD_FN_POLICY` 控制。在生产环境（`NODE_ENV=production`）中，它的默认值是名单为空的 `allowlist`。官方服务器不开启服务端函数。

在本地运行参考服务器：

```bash
cd pku-harness-plugins/packages/cloud-server
bun run dev        # http://localhost:8787，改动后自动重载，数据保存在 ./data/cloud.db
bun test           # 路由测试，以及真实的 WebSocket/SSE 测试
# 也可以在仓库根目录运行：bun run --filter @pku-harness/cloud-server dev
```

在 Android 模拟器里，把「设置 → 云服务 → 自建」指向 `http://10.0.2.2:8787`。

参考服务器通过环境变量配置：

| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `PORT` / `HOST` | `8787` / `0.0.0.0` | 监听地址 |
| `CLOUD_PUBLIC_URL` | `http://localhost:$PORT` | 客户端访问用的源，也是 token 挑战里的 `aud` |
| `CLOUD_DB` | `./data/cloud.db` | SQLite 文件（临时运行可以用 `:memory:`） |
| `CLOUD_TOKEN_SECRET` | 自动生成并存进数据库 | bearer token 的 HMAC 密钥（至少 32 个字符） |
| `CLOUD_POW_DIFFICULTY` | `16` | 工作量证明难度 |
| `CLOUD_POW_ROTATE_S` | `21600` | salt 轮换周期；上一个 salt 会再多有效一个周期 |
| `CLOUD_OPERATOR_NAME` / `CLOUD_OPERATOR_CONTACT` / `CLOUD_PRIVACY_URL` | `PKU harness Cloud (self-hosted)` / 空 | 由 `GET /v1/meta` 返回 |
| `CLOUD_PAGES_DIR` | `<plugins repo>/plugins` | 存放 `<plugin>/web/dist` 查看页的目录 |
| `CLOUD_TRUST_PROXY` | 关闭 | 设为 `1` 时，客户端 IP 取 `X-Forwarded-For` 的最后一跳（部署在 Caddy 后面时使用） |

`deploy/` 目录里有 Dockerfile、Caddyfile 和 Litestream 配置，用法见其中的 `README.md`。服务端函数相关的变量（`CLOUD_FN_POLICY`、`CLOUD_FN_ALLOW`、`CLOUD_FN_VERIFIED`、`CLOUD_FN_LOCAL`、`CLOUD_SECRET_<PLUGIN>__<NAME>`）写在服务器自己的 `README.md` 里。

## 运营一个实例

如果你打算为别人运营一个实例，请注意以下几点：

- 公开你的身份（`operator.name`、`contact`），并发布隐私声明（`privacyURL`）。
- 不要在日志里记录数据内容和 token。数据虽然是密文，但 IP 地址和请求时间同样属于个人信息。
- 在中国大陆托管服务需要 ICP 备案。官方实例计划部署在大陆以外，并为分享链接准备一个专用的短域名。微信可能会对陌生域名显示拦截提示，所以 App 总是同时提供二维码和复制链接两种方式。


# 安全 (/docs/cloud/security)

> PKU harness Cloud 怎样让服务器读不到用户数据：设备密钥对、带工作量证明的注册、短时效的签名插件 token、XChaCha20-Poly1305 信封、放在 URL 片段里的分享链接密钥、只能认领一次的通道，以及分享链接脱敏。

云服务的目标是让服务器只能转发和保存它读不懂的密文，并且不知道用户是谁。本页依次说明实现这一目标的各个机制：设备怎样获得身份，怎样换取 token，数据怎样加密，分享链接怎样保护密钥，以及还存在哪些无法完全消除的风险。

## 设备身份

每台设备在第一次使用云服务时生成两对密钥。私钥保存在系统密钥库里，只能在本机使用，并且要在设备首次解锁后才能读取。

| 密钥 | 算法 | 用途 |
| --- | --- | --- |
| 签名密钥 | Ed25519 | 签名 token 挑战 |
| 加密密钥 | X25519 | 密钥协商 |

服务器只通过这两把公钥认识设备，不知道学号、姓名或手机号。「设置 → 云服务」会显示签名密钥的指纹，并提供**重置身份**和**删除云端数据**两个操作。删除云端数据会调用 `DELETE /v1/devices/me`，App 在完全重置之前也会调用这个接口。

## 注册时的工作量证明

注册设备（`POST /v1/devices`）不需要账号，但设备要先完成一次工作量证明（proof of work）。工作量证明是一道需要一定计算量才能解出的题，验证答案却很快。这样，一次注册的代价很小，批量伪造大量身份的代价就很高。

另一种做法是让服务器验证请求确实来自官方 App，但这会让自己编译的 APK 无法使用，所以我们没有采用。

题目的定义如下：

```
prefix = UTF-8("pku-harness-cloud/v1/pow\n" + salt + "\n" + signPub + "\n" + boxPub + "\n")
hash   = SHA-256(prefix ‖ UTF-8(nonce))         # nonce：十进制，无前导零，最多 15 位
valid  = hash has ≥ difficulty leading zero bits  # 哈希值的前导零位数不少于 difficulty
```

`salt` 和 `difficulty` 来自 `GET /v1/meta`，服务器同时接受当前和上一个 salt。默认难度为 16，在手机上大约要算一秒。客户端会拒绝高于 28 的难度，因此恶意服务商无法让手机无休止地计算。两把公钥都写进了前缀，所以一个解只能注册一个身份。

## 插件 token

插件发出的每个请求都带一个 bearer token。一个 token 只对应一台设备、一个插件和一组服务，有效期为 10 分钟。设备用 Ed25519 签名密钥签名下面这段挑战，以此换取 token：

```
pku-harness-cloud/v1/auth
<aud>        服务商的源，小写的 scheme://host[:port]
<deviceId>
<plugin>
<services>   去重、排序后用 "," 连接
<ts>         Unix 毫秒
<nonce>      16 个随机字节，base64url 编码
```

调用服务端函数用的 token 还会多一行 `doc <hash> <link>`，记录用户同意过的插件文档版本。

这段挑战的各部分分别防范不同的攻击：

- `aud` 防止某个服务商把签名拿到另一家服务商那里重放。
- 服务器只接受满足 `|now − ts| ≤ 5 min` 的请求，并拒绝在这个时间窗口内重复出现的 nonce。
- 存储的命名空间和通道的归属都取自 token 里的 `sub` 和 `plg`，从不取自请求路径，因此一个插件碰不到另一个插件的数据。
- 插件永远看不到 token。token 由宿主签发，并由宿主附加到请求上。

## 信封

所有加密数据，无论是在传输中还是保存在服务器上，都使用同一种格式，我们称之为「信封」：

```json
{ "v": 1, "n": "<24-byte nonce, base64url>", "c": "<ciphertext ‖ 16-byte tag, base64url>" }
```

信封使用 XChaCha20-Poly1305 算法和随机生成的 24 字节 nonce。加密时可以附带关联数据，例如通道 id 或帧类型，解密方必须提供相同的关联数据才能解开。

这套加密只实现了一份，位于 `@pku-harness/cloud-protocol`，基于经过审计的 [noble](https://paulmillr.com/noble/) 库（纯 JavaScript）。App（运行在 Hermes 上）、参考服务器（运行在 Bun 上）和查看页（运行在没有 WebCrypto 的微信内置浏览器里）用的都是这一份实现。

## 分享链接与通道

分享链接的格式如下：

```
https://<provider>/s/<channelId>#k=<base64url 32 bytes>
```

链接里的密钥 `k` 放在 URL 片段（`#` 之后的部分）里。浏览器从不把片段发给服务器，所以服务器拿不到 `k`。设备和查看者从 `k` 派生出两把密钥：

- `authKey = HKDF-SHA256(k, "pku-harness-cloud/v1/join")`，用来加入通道。服务器只保存 `joinHash = base64url(sha256(authKey))`，因此它能校验加入请求，自己却无法加入。
- `encKey = HKDF-SHA256(k, "pku-harness-cloud/v1/enc")`，永远不离开设备。它用来加密通道的 `meta`，并参与派生每个对端的密钥。

查看者加入时，发送 `authKey` 和一把临时生成的 X25519 公钥。此后，机主和这个对端之间的数据帧使用下面的密钥加密：

```
HKDF-SHA256(ikm = X25519(own, other) ‖ encKey, salt = chanPub ‖ peerPub, info = "pku-harness-cloud/v1/peer")
```

通道还有以下保护：

- 认领：`maxPeers` 默认为 1。第一个加入的人认领通道，之后再来的人会收到 `409 conflict`，所以转发出去的链接没有用。机主可以踢掉对端来释放名额。
- 服务器无法验证的检查，例如打码的姓名提示和口令，都在机主的设备上完成。服务器只限制加入频率（每个 IP 每分钟 20 次），并在 `authKey` 错误 5 次后锁定通道。

### 不让 AI 模型接触分享链接

分享链接里含有解密密钥，所以 App 不让它进入 AI 模型的上下文：

- SDK 中的 `SecretLink` 是不透明对象，`JSON.stringify(link)` 只会得到 `"[secret link]"`。
- 宿主会从工具输出和日志里抹掉符合分享链接格式的字符串（`/s/<id>#k=…`、`pkuharness://share/<id>#k=…`），具体实现见 `scrubShareLinks`。
- 工具从不返回链接。页面通过 `host.shareLink` 或 `<QRCode link>` 把链接展示给用户。

## 限额

限流按 `(deviceId, plugin, service)` 和按 IP 分别使用令牌桶算法，当前状态写在 `RateLimit-*` 响应头里。服务器返回 429 时，宿主会抛出 `CloudError('rate_limited', retryAfterS)`。默认值如下：

| 资源 | 默认值 |
| --- | --- |
| 存储 | 每台设备每个插件 1 MB、1,000 个键，单个值 64 KB |
| 通道 | 每台设备同时开 5 个，有效期 60 秒到 24 小时（默认 15 分钟），最多 5 个对端，每帧 4 KB，每分钟 60 帧，64 个信箱槽位 |
| 加入通道 | 每个 IP 每分钟 20 次 |
| 推送（计划中） | 100 个待发的定时推送 |
| 服务端函数（官方服务器不开启） | 每分钟 60 次调用 |

## 剩余风险

上面的机制不能消除所有风险。下面三类风险仍然存在。

元数据。服务商能看到请求时间、数据大小和 IP 地址。插件的数据说明里必须写明这一点。

查看页运行的是服务商提供的 JavaScript。恶意运营者可以提供一个泄露 `k` 的页面，从而看到那一次分享期间通道里传输的内容，但拿不到校园凭据。我们用三种方式降低这一风险：查看页是静态页面，由插件仓库可复现地构建；页面带有严格的内容安全策略（Content Security Policy，CSP），即 `connect-src 'self'`；装了 App 的查看者通过深链接在 App 内解密，完全不运行服务商的 JavaScript。

服务端函数按设计会处理明文。它们必须在 `PLUGIN.md` 里声明并写明数据说明，经用户同意后才能使用，服务器也只运行用户同意过的那个文档版本。官方服务器不开启这项功能。


# 架构 (/docs/concepts/architecture)

> PKU harness 的框架层由 Agent 循环、设计系统和宿主服务组成，具体功能都由插件通过同一套接口提供。

PKU harness 的设计借鉴了 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的两个思路。第一，App 的功能都由插件提供。第二，App 以 AI 助手为核心，但你和助手能做的事情完全相同。

为了做到第二点，每项功能只实现一次，形式是一个有类型的工具（tool）。你在界面上点按钮时，界面调用这个工具；你在对话里提出需求时，助手调用同一个工具。

## 分层结构

App 的代码分为四层，从上到下依次是界面、核心运行时、插件和原生模块。

```
界面          路由 · 页面 · 设计系统（设计令牌、组件、动效）· 生成式界面组件目录
                   │
核心运行时    插件注册表与权限 · Agent 循环 · 看板 · 定时任务 · 存储
              校园会话管理（IAAA、各服务的会话）
                   │
插件          PLUGIN.md 插件文档（解释执行）· 内置 TypeScript 插件 · 远程 MCP 插件 · 模型服务商
                   │
原生模块      campus-http 模块（控制重定向、每个会话独立的 cookie、HTTP/1.1、不走代理）
```

依赖关系只能向下。插件从不导入 App 的代码。插件需要做自身以外的事情时，要通过**宿主服务**（`ctx.services`）；需要显示界面时，要通过 **`HostUI`**。

## 框架层的组成

我们把插件以下的这一层叫作框架（harness）。它由四个部分组成。

| 部分 | 插件使用的接口 |
| --- | --- |
| Agent 循环 | `tools`、`instructions`、`context`、`contributes.commands` |
| 设计系统 | `HostUI`（`host.components`、`host.useTheme()` 等） |
| 宿主服务 | `HostServices`（`ctx.services`、`props.services`） |
| 生成式界面 | `ui.render` 工具、`HostUI.components.GenUI` |

**Agent 循环**负责和模型对话。它基于 AI SDK，模型由任意一个模型服务商插件提供。每次请求时，它把所有已启用的工具交给模型，并以流式方式接收回答。模型可以按任务需要连续调用工具，单次回复没有步骤上限，直到模型给出回答或你按停止才结束。回复进行中，如果历史记录超过上下文预算，Agent 循环会把较早的步骤压缩成摘要，然后继续。它还为每个会话保存模型可见的历史记录，并记录 token 用量。无人值守的定时 Agent 任务仍有一个较小的步骤上限。

**设计系统**包括设计令牌、原生控件和动效。插件的页面用它搭建，所以看起来和 App 的原生页面一致。App 更新后，这些页面也能继续正常工作。

**宿主服务**是 App 提供给插件的一组服务，包括校园 HTTP 请求、定时任务、小组件、待办、课表、通知权限状态、文件、浏览器、加密、插件注册表和设置注册表。

**生成式界面**是一个组件目录。助手写出一段 JSON 描述，App 就按描述在对话或看板里显示对应的组件。

## 助手能操作一切

你在 App 里能做的每一件事，助手都能通过一个工具来做。各个页面只是进入同一份数据的另一条途径，而不是另一套逻辑。整个 App 分为三个部分。

| 部分 | 操作的对象 | 通过什么 |
| --- | --- | --- |
| 校园服务和数据 | 校园服务、校园卡、日程、待办、看板、记忆、附件 | 各个插件的工具 |
| App 本身 | 所有设置：外观、语言、时区、触感反馈、AI 服务和语音服务、每个插件的开关和权限、每个插件自己的设置项 | 设置注册表和核心插件 `settings` |
| 手机 | 手机上的其他 App | Copilot（`copilot.*` 工具） |

**设置注册表**是一份由带类型的条目组成的列表。每个条目有键名、分组、标题、类型（`choice`、`boolean`、`text` 或 `list`）、可选值和当前值。它包括：

- 宿主自己的设置：`app.theme`、`app.language`、`app.timezone`、`app.haptics`、`ai.provider`、`ai.model` 和 `voice.provider`；
- 每个插件的 `plugin.<id>.enabled`（核心插件没有这一项）和 `plugin.<id>.permission.<effect>`，取值为 `auto`、`ask` 或 `off`；
- 每个插件自己的设置项，在清单的 `PluginDef.preferences` 中声明，键名为 `<plugin>.<name>`，例如 `copilot.enabled`、`copilot.apps` 和 `copilot.screenshots`。

插件只要声明设置项，就能加入注册表，宿主不需要任何改动。标记为 `uiOnly` 的条目（例如 API Key、校园账号和系统通知权限）会和它所在的页面一起列出。助手不能修改它们，只能为用户打开那个页面。

核心插件 `settings` 给助手提供三个工具：`list`（读取）、`change`（修改）和 `open`（打开页面）。修改遵循通常的[权限模式](/docs/concepts/permissions)：在改动任何内容之前拒绝未知的键和 `uiOnly` 的键，按条目校验每个值，并返回每个键修改前后的值。插件通过 [`HostServices.settings`](/docs/sdk/host-services#settings) 使用同一个注册表。

## 四个标签页由谁提供

| 标签页 | 提供者 |
| --- | --- |
| 对话 | 框架 |
| 看板 | `dashboard` 插件 |
| 日程 | `schedule` 插件 |
| 设置 | 框架，其中部分设置项由插件提供 |

看板和日程这两个标签页在框架里只是两个空的位置，我们叫它**插槽**。插件通过 `contributes.tabs` 填充插槽。

## 插件

插件有三种形式：

- **插件文档**：一个 `PLUGIN.md` 文档，由 App 解释执行；
- **内置插件**：用 `definePlugin` 写成的 TypeScript 对象，随 App 发布；
- **远程插件**：一个 MCP 服务器。MCP 是 Model Context Protocol（模型上下文协议）的缩写。

无论哪种形式，框架都会把它转换成同样的结构：一组工具，加上可选的界面。每个工具的 id 形如 `<plugin>.<tool>`，并带有效果（effect）和输入 schema。

下面是一个最简单的内置插件。它只有一个工具 `greet`，用来打招呼。

```ts
import { definePlugin, defineTool } from '@pku-harness/sdk';
import { z } from 'zod';

export const helloPlugin = definePlugin({
  id: 'hello',
  name: '你好',
  description: '演示插件。',
  version: '0.1.0',
  scopes: [],
  tools: {
    greet: defineTool({
      title: '打招呼',
      description: 'Greet someone by name.',
      input: z.object({ name: z.string() }),
      effect: 'read',
      execute: async ({ name }) => ({ greeting: `你好，${name}` }),
    }),
  },
});
```

同一个插件也可以写成插件文档：一个带有 `tools: { greet: … }` 的 `PLUGIN.md`，工具的逻辑用 YAML 步骤来写，见[声明式插件](/docs/build/declarative-plugins)。三种插件的对比见[插件](/docs/concepts/plugins)。

## 数据存在哪里

| 数据 | 位置 |
| --- | --- |
| 校园账号密码、模型和语音输入的 API 密钥、远程插件的令牌 | 手机的密钥库（SecureStore） |
| 聊天会话、用量、小组件、定时任务、待办、课表、插件的键值存储 | 手机上的 SQLite 数据库 |
| 你主动开启的插件云端数据 | [PKU harness Cloud](/docs/cloud) 服务，端到端加密 |

默认情况下，数据不经过本项目的任何服务器。你配置的模型服务商会收到对话内容。校园服务收到的请求和浏览器发出的请求相同。

## 更新如何送达用户

不同的代码有不同的更新方式。

| 改动的内容 | 送达方式 |
| --- | --- |
| 插件文档（`PLUGIN.md`），包括随 App 内置的官方插件 | App 重新拉取它的链接 |
| 远程插件 | 服务器自己更新，App 每次实时调用 |
| 插件市场的条目（`registry.json`） | App 实时拉取 |
| App 的 JavaScript 代码、SDK、内置 TypeScript 插件 | 签名的空中更新（OTA），或者发布新版 App |
| 原生代码（原生模块、系统权限） | 发布新版 App |

**插件文档**的链接每天最多重新拉取一次。如果新版本的声明没有变化，它会直接生效。如果新版本要求更宽的权限，要等你确认后才生效。插件文档的更新完全不经过 OTA。

**空中更新**（over-the-air update，简称 OTA）从我们自己的更新服务器下发，下次启动 App 时生效。它基于 expo-updates，服务端是一个静态的、经过代码签名的服务器（`https://pkuharness.com/updates/`）。每次更新都由持续集成（CI）用只有维护者持有的密钥签名。App 内置了对应的证书，会拒绝其他来源的更新。

`runtimeVersion` 采用 fingerprint 策略。也就是说，只要原生代码有改动，运行时版本就会变化，旧的 APK 不会接收新的 OTA 更新，用户需要安装新的 APK。

## 继续阅读

- [插件](/docs/concepts/plugins)：插件文档、内置插件和远程插件的区别，以及如何选择。
- [工具与效果](/docs/concepts/tools-and-effects)：插件对外提供功能的唯一方式。
- [安全模型](/docs/concepts/security)：账号凭据、提示词注入和用户授权。


# 校园会话与 IAAA (/docs/concepts/campus-sessions)

> 校园账号由框架保管。框架自己登录各个北大服务，再通过 `services.campus.request` 把响应交给插件。插件永远拿不到密码或会话令牌。

北大的各项服务都通过学校的统一身份认证系统 IAAA 登录。登录之后，每个服务保存会话的方式又各不相同：有的用 cookie，有的要经过门户的单点登录（SSO）跳转，有的用 JWT 令牌。

这些登录逻辑由框架在 App 里统一实现，协议细节参考 [`pkucli`](https://github.com/pkuinfo/pkucli)。内置插件不需要关心登录。它只要按**服务名**发起一个请求，框架就会带上登录状态发出请求，并把响应交给插件。例如，查询校园卡余额：

```ts
const res = await ctx.services.campus.request('card', {
  url: '/berserker-app/ykt/tsm/queryCard?synAccessSource=h5',
});
// res: { status, url, headers, body }
```

## 框架负责登录的服务

下表列出四个主要服务，以及框架为它们建立会话的过程。

| 服务 | 域名 | 框架建立的会话 |
| --- | --- | --- |
| `card` | bdcard.pku.edu.cn | IAAA → 门户 ssoLogin → redirectToCard → synjones JWT |
| `its` | its.pku.edu.cn | ITS 网页登录（网络账号） |
| `treehole` | treehole.pku.edu.cn `/chapi/…` | IAAA「PKU Helper」→ JWT + 设备 uuid |
| `blackboard` | course.pku.edu.cn（教学网） | IAAA → campusLogin cookie 会话 |

会话失效时，框架会自动处理。`card` 遇到 401 时刷新 JWT；`treehole` 遇到 401 时重新登录；`blackboard` 会自动跟随重定向。

除此之外，App 里的适配器（`src/core/campus/adapters/`）还注册了以下服务：`bdkj`（空间预约）、`cwfw`（财务）、`cwpay`（财务缴费）、`elective`（选课）、`library`（图书馆）和 `library-space`（图书馆空间预约，包括研讨室和研修专座）。

`CampusService` 的类型是 `'card' | 'its' | 'treehole' | 'blackboard' | (string & {})`。请求一个没有注册的服务，会直接被拒绝。请在插件的 `scopes` 里声明你用到的服务，这样用户可以在插件页面上看到。

## 请求的格式

`request` 的第二个参数是一个 `CampusRequest` 对象。

```ts
type CampusRequest = {
  url: string;                       // 绝对地址，或服务域名下的路径
  method?: 'GET' | 'POST';
  headers?: Record<string, string>;
  body?: string;
  contentType?: string;
  responseType?: 'text' | 'base64';
  form?: Record<string, string>;     // url-encoded 表单，代替 body
  authIn?: 'headers' | 'form';       // 把会话凭据也放进表单（校园卡下单接口）
  sign?: (fields) => fields | Promise<fields>;  // 对最终的表单字段追加签名
  followRedirects?: boolean;         // false = 自己读取 `location`
  multipart?: CampusMultipart;       // 文件上传；文件字节不经过插件
  timeoutMs?: number;                // 默认 20 秒，multipart 为 120 秒
};
```

请求由 App 原生的校园 HTTP 模块发出。这个模块有以下特点。

- 为每个会话维护独立的 cookie 存储。
- 允许手动控制重定向。
- 使用 HTTP/1.1。
- 内置部分校园网站需要的额外根证书。
- **不经过代理**。只能在校内访问的网站会被直接请求。

完整的类型定义见 [SDK → campus](/docs/sdk/campus)。

## 二次验证

二次验证分两种，分别由框架和插件处理。

**IAAA 的二次验证**由框架处理，包括短信、邮箱和手机令牌三种方式。任何一次登录都可能弹出验证提示，后台刷新会话时也一样。这时请求会暂停，等用户完成验证后再继续。

**服务自己的验证**交给插件处理，因为只有插件了解这个服务的接口。以树洞为例，它会返回两种需要验证的状态码：

- `40002` 表示需要短信验证，相关接口是 `/chapi/api/jwt_send_msg` 和 `/chapi/api/jwt_msg_verify`；
- `40077` 表示需要课程数据令牌。

插件把这些状态码转换成类似 `{ status: 'verification_required', methods: ['sms'], message }` 的结果。之后，用户可以自己完成验证，也可以把验证码交给助手，由助手完成。在 Android 上，`services.sms.awaitCode()` 支持一键读取短信验证码。

如果用户在 App 里绑定了身份验证器，`services.campus.otp()` 会返回当前的手机令牌验证码，但不会返回令牌的密钥。树洞课程令牌这类二次验证可以用它完成。

## 把用户带到校园网页

有时插件需要让用户在浏览器里完成操作，最常见的是为插件创建的订单付款。

`services.campus.openSignedIn(service)` 会在系统浏览器里打开一个已经登录的服务页面。它用的是这个服务自己的跳转机制。URL 由框架生成，所以插件看不到其中的令牌。

`services.browser.open(url)` 可以打开任意 URL，例如支付收银台。如果 URL 是 `weixin://` 或 `alipays://` 这类链接，系统会打开对应的 App。

## 规则

- **必须**声明 `requires: ['campus-session']`。如果访问只能在校内访问的网站，还要加上 `'campus-network'`。
- **不得**向用户索要校园账号密码，无论是在页面里、工具输入里还是远程插件里。远程插件目前没有校园会话。按范围授予会话的功能已经列入路线图。
- `pkucli` 已经实现的接口和特殊处理，**必须**照着移植，并在注释里注明来源文件。详见[从 pkucli 移植](/docs/build/porting-from-pkucli)。
- **应当**先检查 `services.campus.status().signedIn`。如果用户还没有登录，请返回一条清楚的提示，例如「请先在设置里登录校园账号」，不要直接返回原始错误。


# 能力需求 (/docs/concepts/capabilities)

> 插件在 `requires` 里声明它需要手机提供哪些能力。手机满足不了时，框架会隐藏这个插件，并告诉用户原因。

手机和电脑不同。插件在手机上没有 shell，也没有用户可见的文件系统，后台运行的时间也有限。另外，有些校园网站只能在校园网内访问。

所以，每个插件都要说明自己需要手机提供哪些能力。插件在 `PluginDef.requires` 里列出这些能力，注册表条目里的 `requires` 也一样。框架会把这份列表和手机实际提供的能力做比较。只要有一项不满足，插件就会对助手隐藏，它的工具调用会被拒绝，设置页会显示原因。

例如，财务插件需要已登录的校园会话，还需要校园网：

```ts
definePlugin({
  id: 'finance',
  // …
  requires: ['campus-session', 'campus-network'],
});
```

## 能力列表

| 能力 | 含义 | 目前是否提供 |
| --- | --- | --- |
| `network` | 普通的互联网访问 | 是 |
| `campus-network` | 只能在北大校园网内访问的网站 | 是（见下文） |
| `campus-session` | 通过宿主发出的、已登录的校园请求 | 仅 Android |
| `notifications` | 本地通知 | 是 |
| `background` | 定期在后台运行 | 是 |
| `cloud` | 已配置 [PKU harness Cloud](/docs/cloud) 服务 | 配置了服务时提供 |
| `ongoing` | 常驻通知或前台服务 | 仅 Android |
| `phone-control` | 操作手机上的其他 App（Copilot，通过 `services.phone`） | Android 12 及以上 |
| `shell` | 命令行 shell | 手机上永远没有 |
| `filesystem` | 文件系统 | 不向插件开放 |

下面是几项需要补充说明的能力。

- **`network`** 指直接用 `fetch` 访问互联网。
- **`campus-network`** 在 App 里始终声明为可用。但如果手机不在校园网内，请求会失败。
- **`campus-session`** 指通过宿主的 `services.campus` 发出已登录的校园请求，账号密码不会暴露给插件。它依赖原生的 campus-http 模块，所以目前只在 Android 上提供。iOS 要等这个模块移植到 Swift 之后才能提供。
- **`cloud`** 会随你的配置实时变化。你配置了 Cloud 服务，它就可用；你移除配置，它就不可用。
- **`ongoing`** 对应 `services.ongoing`，用来显示常驻通知或运行前台服务。
- **`shell`** 在手机上永远不会提供。需要 shell 的插件只能做成远程插件。
- **`filesystem`** 不向插件开放。如果需要用户选择的文件，请使用 `services.files.pick`。

## 规则

- **必须**列出插件的工具依赖的每一项能力。调用 `services.campus.request` 的插件需要 `campus-session`。如果它还访问只在校园网内可用的网站，还需要 `campus-network`。
- 内置插件**不得**要求 `shell` 或 `filesystem`。繁重的工作，例如抓取大量页面、文字识别（OCR）或长时间运行的任务，应该放到远程插件里。
- 远程插件运行在服务器上，所以 `shell` 对它们来说不是手机需要提供的能力。注册表的校验工具会拒绝远程插件条目里的 `requires: ['shell']`。
- **应当**在使用可选服务之前先检查它是否存在。没有 `ongoing` 能力时，`services.ongoing` 为 `undefined`。宿主不支持云服务时，`ctx.cloud` 为 `undefined`。
- 如果插件不依赖云服务也能工作，应当声明 `cloud.optional: true`，而不是要求 `cloud`。使用前请检查 `ctx.cloud?.available`。


# 看板小组件与数据 (/docs/concepts/dashboard)

> 看板上的小组件有两类：助手搭建的小组件（一份生成式界面 spec，加上对读取类工具的绑定），以及插件提供的原生组件。刷新由宿主统一负责，所有组件共用一份缓存。

「看板」标签页由 `dashboard` 插件提供。它是一个有序的小组件（widget）列表，例如校园卡余额、下一节课和下一班校车。

你可以在对话里告诉助手想看哪些数字，例如「显示我的校园卡余额和下一班校车」，助手就会搭建或修改看板。你也可以长按一个小组件，调整它的顺序、大小或者删除它，还可以从小组件库里添加插件提供的小组件。

## 两类小组件

看板上的小组件分为两类，它们可以混排在一起。

**助手搭建的小组件**由 `{ spec, bindings }` 描述。助手通过 `dashboard.upsertWidget` 写出一份[生成式界面](/docs/concepts/generative-ui) spec 来决定它的样子。数据来自 `bindings`：每一项绑定把状态中的一个路径对应到一个读取类工具。

**插件提供的小组件**由 `{ source: { plugin, widget, config? } }` 描述。它是插件自己的原生组件，在 `contributes.widgets` 里声明。看板会用一层错误边界把它包起来，这样一个小组件出错不会影响其他小组件。组件在内部调用 `host.useToolData(...)` 获取数据。

搭建看板时，助手会先查看 `dashboard.catalog`。如果有合适的插件小组件，它就直接把这个小组件放上看板（`dashboard.addPluginWidget`）。只有找不到合适的，它才自己搭建一个。

无论哪一类，小组件的外框都由看板来画。外框包括标题、数据的更新时间和长按菜单。

## 小组件模型

```ts
type Widget = {
  id: string;
  title: string;
  size: 'sm' | 'md' | 'lg';           // sm = 半宽小块，md = 全宽，lg = 全宽大卡片
  spec: Record<string, unknown>;      // json-render spec（插件小组件为空）
  bindings: Record<string, Binding>;  // 状态中的 JSON pointer → 数据源
  source?: { plugin: string; widget: string; config?: Record<string, unknown> };
  position: number;
  createdAt: number;
  updatedAt: number;
};

type Binding = {
  tool: string;            // 只读工具 id，例如 "calendar.today"
  args?: Record<string, unknown>;
  path?: string;           // 结果中的点路径；为空表示整个结果
  ttlMinutes?: number;     // 0 – 1440，默认 5
};
```

`size` 有三种：`sm` 是半宽的小块，`md` 占满一行，`lg` 是占满一行的大卡片。

下面是一个由助手搭建的小组件，它显示今天的课程。`bindings` 把状态中的 `/today` 绑定到 `timetable.today` 工具，缓存 1 分钟。

```json
{
  "title": "下一节课",
  "size": "md",
  "spec": {
    "root": "col",
    "elements": {
      "col": { "type": "Column", "props": { "gap": "sm" }, "children": ["h", "t"] },
      "h": { "type": "Heading", "props": { "text": { "$template": "今天共 ${/today/count} 节课" }, "size": "md" } },
      "t": { "type": "Text", "props": { "text": { "$template": "下一节：${/today/next/name} ${/today/next/time}" }, "tone": "muted", "size": null } }
    }
  },
  "bindings": { "/today": { "tool": "timetable.today", "ttlMinutes": 1 } }
}
```

## 小组件如何刷新

小组件的刷新由宿主统一负责，插件不需要自己处理。

所有读取类工具的结果都存在**同一个存储**里，以「工具 + 参数」作为键。助手搭建的小组件、插件小组件、插件页面和定时检查都共用这个存储。如果你用过 TanStack Query，会发现这是同一种模型，叫作 stale-while-revalidate：先显示缓存里的旧值，同时在后台获取新值。具体规则如下。

- **上一次的值会保存下来。** App 冷启动后，数字会立刻显示出来，并标明是多久以前的数据，例如「3 分钟前」。只有从来没有获取过数据时，才会显示骨架屏。
- **数据超过缓存有效期（TTL）后就算过期。** 默认的 TTL 是 5 分钟。过期的查询只有在**当前聚焦的页面上**才会重新获取，时机是页面获得焦点时、App 回到前台时，以及页面可见期间的定时刷新。隐藏的标签页和在后台运行的 App 从不轮询。
- **下拉刷新会强制刷新当前页面上的所有查询。** 同时发出的相同请求会共用同一个 promise，不会重复发送。
- **刷新失败时保留上一次的值，** 并加上一个标记，例如「刷新失败 · 10 分钟前」。
- **定时检查也会写入这个存储。** 所以后台的余额检查会顺便更新看板上的余额小组件。

因此，插件小组件**不得**自己设定时器轮询。请用 `host.useToolData` 加载数据，并按数据变化的快慢选择 TTL。余额这类数据适合 5–15 分钟，变化慢的数据适合 60 分钟以上。

## 编写插件小组件

下面是一个显示食堂就餐人数的插件小组件。它用 `host.useToolData` 读取 `canteen.crowd` 工具的结果，TTL 设为 2 分钟。小尺寸时显示 3 个食堂，其他尺寸显示 6 个。

```tsx
import type { PluginWidgetProps } from '@pku-harness/sdk';
import { View } from 'react-native';

type Crowd = { name: string; percent: number }[];

export function CrowdWidget({ host, size }: PluginWidgetProps) {
  const { Text, Skeleton } = host.components;
  const t = host.useTheme();
  const data = host.useToolData<{ canteens: Crowd }>('canteen.crowd', {}, { ttlMinutes: 2 });
  if (data.status === 'loading') return <Skeleton width="60%" height={20} />;
  if (!data.value) return <Text tone="muted">{data.error ?? '暂无数据'}</Text>;
  const list = data.value.canteens.slice(0, size === 'sm' ? 3 : 6);
  return (
    <View style={{ gap: t.spacing.xs }}>
      {list.map((c) => (
        <Text key={c.name} variant="callout">{`${c.name} ${c.percent}%`}</Text>
      ))}
    </View>
  );
}
```

写好之后，在 `contributes.widgets` 下注册这个组件，并为它写一段给助手看的 `description`。助手挑选小组件时，读的就是这段描述。详见 [UI 扩展](/docs/build/ui#widgets)。


# 生成式界面 (/docs/concepts/generative-ui)

> 助手用 JSON 描述一段界面，App 用原生组件把它显示出来，可以显示在对话里（`ui.render`），也可以显示在看板上。表单提交的内容会作为你的下一条消息发回给助手。

有些回答用文字表达并不方便。例如，助手需要你填写一个金额，或者需要你从列表里选一项，或者手上的数据更适合用卡片展示。这时，助手可以直接回复一段界面。

具体做法是：助手写出一份 JSON 格式的界面描述，我们叫它 **spec**。App 从一套固定的**组件目录**（catalog）里取出对应的原生组件，把这段界面显示出来。这套机制基于 [json-render](https://github.com/vercel-labs/json-render)。

组件的属性都是语义化的，例如色调（tone）和尺寸（size），不能直接写颜色值。因此，助手搭出来的界面和 App 其他部分的风格一致。助手搭建看板小组件时用的也是这套组件目录，所以它只需要学会一种界面描述方式。

## spec 的结构

```ts
// specSchema in @pku-harness/sdk (genui.ts)
type UISpec = {
  root: string;                                  // 根元素的 id
  elements: Record<string, {
    type: string;                                // 目录中的组件名
    props: Record<string, unknown>;              // 列出的属性都要给出，不用时为 null
    children?: string[];                         // 子元素 id
    on?: Record<string, unknown>;                // 事件，例如 { press: { action, params } }
    visible?: unknown;
  }>;
  state?: Record<string, unknown>;               // 初始状态，例如 { form: { amount: "50" } }
};
```

spec 里可以保存一份状态（`state`）。组件的属性可以绑定到状态上，有三种绑定方式。

| 绑定 | 含义 |
| --- | --- |
| `{ "$state": "/card/balance" }` | 从状态中读取一个值（JSON pointer） |
| `{ "$bindState": "/form/amount" }` | 把输入控件和状态双向绑定 |
| `{ "$template": "今天共 ${/today/count} 节课" }` | 插入状态值的字符串 |

## 组件目录

目录里共有 17 个组件。表中「可以有子元素」的组件用 `children` 包含其他组件；「绑定 `value`」表示这个输入控件的值应当用 `$bindState` 绑定到状态。

| 组件 | 属性 | 说明 |
| --- | --- | --- |
| `Column` | `gap` | 纵向排列，可以有子元素 |
| `Row` | `gap`, `align`, `wrap` | 横向排列，可以有子元素 |
| `Card` | `title`, `subtitle` | 分组面板，可以有子元素。不要嵌套卡片。 |
| `Heading` | `text`, `size` | |
| `Text` | `text`, `tone`, `size` | |
| `Stat` | `label`, `value`, `prefix`, `suffix`, `decimals`, `delta`, `deltaTone`, `caption`, `icon`, `size` | 关键数字，数值变化时有动画 |
| `Badge` | `label`, `tone` | |
| `ListItem` | `title`, `subtitle`, `value`, `icon` | 事件 `press` |
| `Divider` | — | |
| `Progress` | `label`, `value`（0–1）, `tone` | |
| `TextField` | `label`, `placeholder`, `value`, `keyboard` | 绑定 `value` |
| `Toggle` | `label`, `value` | 绑定 `value` |
| `Choice` | `label`, `options`, `value` | 最多 12 个选项；绑定 `value` |
| `Sparkline` | `values`, `tone` | |
| `Ring` | `value`（0–1）, `label`, `caption`, `tone`, `size` | |
| `DateTime` | `label`, `value`, `mode` | 原生选择器；值为本地时间 `"YYYY-MM-DD HH:mm"` |
| `Button` | `label`, `variant` | 事件 `press` |

组件被点击时，会触发 `on.press` 里定义的动作。动作有两种。

| 动作 | 参数 | 效果 |
| --- | --- | --- |
| `submit` | `{ label }` | 把 `/form` 下的全部内容作为用户的下一条消息发回给助手 |
| `callTool` | `{ tool, input }` | 直接调用某个插件工具 |

`callTool` 调用工具时，权限检查和助手调用时相同。

这一页的内容可能落后于实际代码，但运行时的组件目录始终是最新的。`ui.render` 工具的描述里包含了 `services.genui.describeCatalog()` 的输出，所以助手看到的永远是当前的目录。`services.genui.checkSpec(spec)` 可以用来校验一份 spec。

## 示例：充值表单

下面的 spec 显示一张「充值校园卡」卡片，里面有一个金额选择和一个确认按钮。你点「确认」后，所选金额会作为你的下一条消息发回给助手。

```json
{
  "root": "card",
  "elements": {
    "card": { "type": "Card", "props": { "title": "充值校园卡", "subtitle": "选择金额" }, "children": ["amount", "ok"] },
    "amount": {
      "type": "Choice",
      "props": {
        "label": null,
        "options": [{ "label": "¥50", "value": "50", "hint": null }, { "label": "¥100", "value": "100", "hint": "常用" }],
        "value": { "$bindState": "/form/amount" }
      }
    },
    "ok": { "type": "Button", "props": { "label": "确认", "variant": "primary" }, "on": { "press": { "action": "submit", "params": { "label": "充值" } } } }
  },
  "state": { "form": { "amount": "100" } }
}
```

## 写给插件作者

远程插件不能自己显示界面。它们只返回数据，由助手来生成界面。

内置插件的页面可以用 `host.components.GenUI` 显示一份 spec：`<GenUI spec={spec} onSubmit={(form, label) => …} />`。

生成式界面适合对话中一次性的场景。如果用户会经常打开某个界面，请把它做成原生页面或小组件（`contributes.screens` / `widgets`）。


# 宿主服务 (/docs/concepts/host-services)

> 内置插件需要做自身以外的事情时，都要通过 `HostServices`。框架在工具里以 `ctx.services`、在页面和小组件里以 `props.services` 的形式把它传给插件。

内置插件从不导入 App 的代码。插件需要的系统功能，例如发送校园请求或创建定时任务，由 App 提供。我们把 App 提供的这些功能叫作**宿主服务**。

框架把宿主服务放在一个 `HostServices` 对象里交给插件。在工具里，它是 `ctx.services`；在页面和小组件里，它是 `props.services`。

此外，每个插件还有自己的键值存储（`ctx.kv` / `props.kv`）。如果插件声明了云服务，它还会拿到一个云客户端（`ctx.cloud`）。

## 服务一览

| 服务 | 提供什么 |
| --- | --- |
| `campus` | 已登录的校园 HTTP 请求和登录状态 |
| `scheduler` | 定时任务的创建、更新、删除和列出 |
| `widgets` | 看板小组件的管理 |
| `todos` | 待办，可以附带提醒 |
| `timetable` | 课程、学期和上课提醒设置 |
| `notify` | 提醒能否准时触发，以及修复入口 |
| `sms` | 一键读取短信验证码 |
| `files` | 系统的文件选择器，以及对话中附件的文字（列出、读取、搜索） |
| `settings` | App 和插件的全部设置：列出、修改、打开对应页面 |
| `phone` | Copilot 的手机会话（供内置的 Copilot 插件使用） |
| `browser` | 在系统浏览器中打开网址 |
| `crypto` | `sha256(text)` |
| `registry` | 已安装的插件和工具（只读） |
| `remote` | 远程 MCP 插件的安装、卸载和检查 |
| `genui` | 生成式界面的组件目录和描述校验 |
| `ongoing?` | Android 前台服务和常驻通知 |

每个服务的完整签名见 [SDK → HostServices](/docs/sdk/host-services)。下面补充一些使用时要注意的地方。

- **`campus`** 的主要方法是 `request(service, req)`。它还能返回当前的手机令牌验证码，并能在保持登录状态的情况下跳转到浏览器。使用它需要 `campus-session` 能力，详见[校园会话](/docs/concepts/campus-sessions)。
- **`scheduler`** 用于精确的通知和定时检查，也可以立即运行一次检查，详见[定时任务](/docs/concepts/scheduler)。
- **`widgets`** 可以列出、放置、移除、排序、预览和解析小组件，并提供组件目录，详见[看板](/docs/concepts/dashboard)。
- **`notify`** 的 `fix` 方法只能在用户点击时调用。
- **`sms`** 的 `awaitCode()` 使用 Android 的 SMS User Consent 接口，不需要短信权限。
- **`files`** 的 `pick` 只能由用户发起，绝不能在助手调用的工具里使用。`list`、`read` 和 `search` 读取用户在当前对话里附上的文档（PDF、Word、Excel、PowerPoint、录音转写等），内容是手机上提取出的文字。这些文字属于第三方内容，返回它们的工具要标记为 `untrusted`。
- **`settings`** 和设置页面读写同一份设置。`change` 会拒绝未知的键和 `uiOnly` 的键；插件自己的设置项要在 `PluginDef.preferences` 中声明，见[架构 → 助手能操作一切](/docs/concepts/architecture#agent-operates-everything)。
- **`phone`** 驱动 Copilot 的独立屏幕。它只供内置的 Copilot 插件使用，需要 `phone-control` 能力。
- **`browser`** 用于打开收银台和文档，以及框架无法代为完成的登录。
- **`crypto`** 存在的原因是插件自己没有加密库。
- **`remote`** 供 `plugins` 插件使用。
- **`ongoing`** 只在手机具备 `ongoing` 能力时存在，所以它的类型带有问号。

## 私有存储：`kv`

```ts
interface KV {
  get<T>(key: string): Promise<T | undefined>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
}
```

每个插件的 `kv` 都有独立的命名空间。数据以 JSON 的形式存在手机上的 SQLite 数据库里。

`kv` 不是密钥库。请不要在里面存放用户输入的机密信息，也不要存放大块数据。

## 示例：一个用到三项服务的工具

下面这个工具会创建一个定时检查：每天早上 8 点查一次校园卡余额，余额低于指定金额时提醒你。它用到了 `campus`、`scheduler` 和 `kv`。

```ts
import { defineTool } from '@pku-harness/sdk';
import { z } from 'zod';

export const remindLowBalance = defineTool({
  title: '余额提醒',
  description: 'Every morning at 08:00, notify when the campus card balance is below `below` yuan.',
  input: z.object({ below: z.number().positive() }),
  effect: 'write',
  execute: async ({ below }, ctx) => {
    if (!ctx.services.campus.status().signedIn) throw new Error('请先在设置里登录校园账号');
    const job = await ctx.services.scheduler.create({
      title: '校园卡余额提醒',
      source: ctx.actor === 'agent' ? 'agent' : 'user',
      trigger: { type: 'every', unit: 'day', interval: 1, times: ['08:00'], startAt: Date.now() },
      action: {
        type: 'check',
        tool: 'wallet.cardBalance',
        condition: { path: 'balance', op: '<', value: below },
        title: '校园卡余额只剩 ¥{value}',
      },
    });
    await ctx.kv.set('lowBalanceJob', job.id);
    return { jobId: job.id, nextRunAt: job.nextRunAt };
  },
});
```

## 规则

- **必须**只通过 `services`、`kv`、`cloud`，以及界面中的 `host` 访问 App。不能导入 App 的代码，也不能在插件之间共享全局单例。
- **不得**导入其他插件的代码。很小的工具函数可以直接复制一份，内置插件的 HTTP 辅助函数就是这样做的。多个内置插件都需要的代码放在 `plugins/shared/`，例如 `wallet` 和 `card-share` 共用的 `campus-card.ts`。
- **必须**只在响应用户点击时调用 `files.pick` 和 `notify.fix`。`files.pick` 绝不能在助手调用的工具里使用。
- **应当**只对公开的、不需要登录的页面使用普通的 `fetch`，并声明 `requires: ['network']`。凡是需要用户会话的请求，都要通过 `services.campus.request` 发出。


# 权限与授权 (/docs/concepts/permissions)

> 你可以针对每个插件的每种效果，决定助手可以直接执行、需要先询问，还是不能执行。定时任务只能读取。

在首次启动的引导中同意用户协议之后，助手就可以代表你操作已启用的插件。

不过，你可以细致地控制助手能做什么。每个插件对每种[效果](/docs/concepts/tools-and-effects#effects)（effect）都有一个单独的授权方式。例如，你可以让助手直接查询校园卡余额，但在充值之前先问你。授权方式在「设置 → 插件 → 某个插件 → AI 权限」里修改。

## 三种授权方式

授权方式决定助手调用某类效果的工具时会发生什么。

| 授权方式 | 结果 |
| --- | --- |
| `auto` | 直接执行 |
| `ask` | 先弹出审批提示 |
| `off` | 拒绝执行 |

审批提示会显示插件、工具、效果和输入参数，并提供三个选项：**允许**、**拒绝**和**始终允许**。

授权方式为 `off` 时，调用会被拒绝，助手会被告知这个工具已被禁用。

## 默认的授权方式

不同类型的插件有不同的默认值。

| 插件类型 | `read` | `write` | `money` | `public` |
| --- | --- | --- | --- | --- |
| 内置插件 | auto | auto | auto | auto |
| 官方插件文档 | auto | auto | auto | auto |
| 社区插件文档 | auto | ask | ask | ask |
| 远程插件 | auto | ask | ask | ask |

插件可以用 `defaultModes` 修改自己的默认值。

- 内置插件和官方插件文档如果设置了 `defaultModes`，就按它的声明执行，例如 `{ money: 'ask' }`。没有声明的效果仍然是 `auto`。
- 社区插件文档也可以设置 `defaultModes`，但只有比上表更严格的设置才会生效。

如果某个操作是用户可能想先确认的，请为它声明更严格的默认值：

```ts
definePlugin({
  // …
  defaultModes: { money: 'ask', public: 'ask' },
});
```

## 何时询问，询问谁

是否执行一次调用，只在宿主的 invoke 路径这一处决定。宿主按下面的顺序检查。

1. 工具必须存在，它所属的插件必须**可用**（能力需求已满足）并且**已启用**。
2. 如果工具标记了 `userOnly`，只有 `actor === 'user'` 时才放行，否则拒绝。
3. 用工具的 zod schema 校验输入。
4. 授权方式为 `off` 时，拒绝。
5. 如果 `actor === 'scheduler'`，而效果不是 `read`，拒绝。无人值守的运行只能读取。
6. 如果授权方式为 `ask`，而 `actor === 'scheduler'`，视为拒绝，因为这时没有人可以询问。
7. 如果授权方式为 `ask`，而 `actor === 'agent'`，弹出审批提示。你选择拒绝时，助手会收到一个「declined」错误。
8. 如果 `actor === 'user'`，从不弹出提示，因为点按钮本身就表达了你的意图。

## 总是询问的工具

有两类工具，助手每次调用都会询问，不受授权方式影响：`auto` 也不会跳过提示，`off` 照样拒绝调用，定时任务的调用一律拒绝。

- **`grant`** 工具给助手它原本没有的访问权限，例如 `copilot.requestApp` 会把一个 App 加入 Copilot 的使用范围。它的提示提供「仅本次允许」「始终允许」和「不允许」。用户的回答以 `ctx.grant`（`'once'` 或 `'always'`）传给工具，不会改变插件的授权方式。
- **`alwaysAsk`** 工具用于宿主无法根据观察到的目标来判断的操作。它的提示没有「以后不再询问」选项。

如果工具的 `resolveEffect` 给出了操作对象（例如 Copilot 将要点按的按钮），提示会把它作为标题显示，同样不提供「以后不再询问」选项。

## 工具之外的授权

除了工具调用，还有几类操作需要你单独授权。

**校园服务。** 你登录校园账号，就授权了 App 访问校园服务。插件要声明它访问的站点和服务（`scopes`），以及 `requires: ['campus-session']`。这些信息会显示在插件页面上。

**PKU harness Cloud。** 每个插件都有一个单独的**允许云端**开关。开关旁边会列出插件的 `disclosure` 说明，用通俗的话讲清它会在云端存什么。没有得到授权就调用云服务时，会抛出 `CloudError('consent_required')`，详见[云服务](/docs/cloud/plugin-guide#2-consent)。

**文件。** 只有你本人能选择文件。插件只能在页面里调用 `services.files.pick`，绝不能在助手调用的工具里使用它。你在对话里附上的文档会在手机上读成文字，助手通过核心插件 `files` 的工具翻页和搜索；这些工具返回第三方内容，调用后助手的这个回合会被标记为「已污染」。

**通知和精确闹钟。** 这两项由系统的授权弹窗决定。插件在你点击时调用 `services.notify.fix(kind)` 来弹出它。

**记忆。** 助手读到不可信的内容之后写入的记忆，会先保存为「待确认」状态。你在记忆页面批准后，它才会生效。

**设置，包括授权方式本身。** 助手可以通过核心插件 `settings` 修改设置：App 的外观、语言和时区，模型，每个插件的开关、授权方式和它自己的设置项。`change` 工具的效果是 `write`，所以它遵循 `settings` 插件自己的授权方式；和其他内置插件一样，默认是 `auto`。希望每次修改设置都确认的用户，可以把这一项设为 `ask`。密钥和需要用户亲手完成的步骤（API Key、校园账号、系统权限）标记为 `uiOnly`，助手只能打开它们所在的页面。详见[架构 → 助手能操作一切](/docs/concepts/architecture#agent-operates-everything)。

## 插件作者须知

- **必须**如实声明每个工具的效果。`money` 和 `public` 这两种效果存在的意义，就是让你能把这类操作放在确认之后。
- **不得**在 `read` 工具里偷偷修改数据，例如「读取并标记为已读」。
- **应当**把 `money` 和 `public` 的 `defaultModes` 设为 `ask`，除非这个操作很容易撤销。
- **应当**把既读又写的工具拆成两个工具。
- **必须**用 `userOnly` 标记那些助手不能自己打开的操作，例如批准助手自己写入的记忆。


# 插件 (/docs/concepts/plugins)

> 插件有三种形式。插件文档（PLUGIN.md）由 App 解释执行，通过链接安装；内置 TypeScript 插件随 App 发布；远程插件是通过 URL 添加的 MCP 服务器。三者共用同一个注册表、同一套权限系统和同一个 Agent 循环。

在 PKU harness 里，每一项连接校园服务的功能都由一个插件（plugin）提供。插件有三种形式。最常见的是**插件文档**：一个包含 `PLUGIN.md` 文件的文件夹，App 读取并按照其中的说明执行。另外两种分别是内置在 App 中的 **TypeScript 插件**，以及运行在服务器上、通过 MCP（Model Context Protocol，模型上下文协议）连接的**远程插件**。

助手、权限系统和插件市场用同样的方式对待这三种插件。内置插件和社区插件使用同一套权限系统。

## 插件的三种形式

### 插件文档

插件文档是一个文件夹。文件夹里有一份 YAML 清单、一段写给助手的说明，以及用 YAML 步骤写成的工具。如果插件有小组件，小组件用生成式界面的 JSON 来描述。

插件文档在手机上运行，由 App 解释执行。整个过程中不会运行任何插件代码。

它通过一个链接发布，可以是 GitHub 文件夹，也可以是任意一个 `PLUGIN.md` 的 URL。要更新插件，只需要 `git push`。官方的插件文档也随 App 内置，同样从各自的链接更新。

插件文档可以访问它声明过的校园服务（使用用户的会话）和公开网站，也可以使用[宿主能力](/docs/build/declarative-plugins#host-abilities)。它能提供小组件、页面、设置项和快捷指令。

### 内置 TypeScript 插件

内置插件是一个基于 `@pku-harness/sdk` 的 TypeScript 模块，用 `definePlugin` 定义。它运行在手机上的 App 内部，随 App 的新版本或签名的空中更新（OTA）一起发布。

内置插件可以使用宿主服务、原生界面和 PKU harness Cloud。原生界面包括页面、小组件、设置项、快捷指令和标签页。

### 远程插件

远程插件是一个通过 Streamable HTTP 通信的 MCP 服务器，可以用任何语言编写。它运行在你自己控制的 HTTPS 服务器上。

发布远程插件时，你部署自己的服务器。用户可以添加它的 URL，也可以从插件市场安装。远程插件只能提供工具，它的结果会作为数据交给模型。

### 三种形式的对比

| | 插件文档 | 内置插件 | 远程插件 |
| --- | --- | --- | --- |
| 运行位置 | 手机，由 App 解释执行 | 手机，App 内部 | 你的 HTTPS 服务器 |
| 发布方式 | 一个链接 | 随 App 发布 | 部署服务器 |
| 能否看到校园账号密码 | 不能 | 不能 | 不能 |
| 工具 id | `<plugin id>.<tool>` | `<plugin id>.<tool>` | `mcp-<server name>.<tool>` |
| 工具 id 示例 | `classrooms.free` | `wallet.cardBalance` | `mcp-demo-canteen.menu` |

三种插件都看不到校园账号密码。插件文档的校园请求由框架代为签发；内置插件只能通过 `services.campus.request` 拿到响应；远程插件根本没有校园会话。

### 信任级别

插件文档分为官方和社区两类。官方插件文档随 App 内置，或者来自 `pkuinfo/pku-harness-plugins` 仓库。社区插件的工具在执行 `write`、`money` 或 `public` 效果之前会先询问你，它们返回的结果也被视为不可信的内容。

内置插件都在插件仓库中经过审核。

远程插件属于第三方。默认情况下，会修改数据的工具都要先询问你。远程插件返回的任何结果都会「污染」（taint）当前这一轮对话。这意味着什么，请看[安全模型](/docs/concepts/security)。

### 为什么大多数插件是文档

应用商店禁止 App 下载可执行代码。插件文档是数据，不是代码，所以社区插件可以以文档的形式在手机上运行，也可以通过 MCP 在远程运行。

官方的校园服务插件 classrooms、campus-events、grades、canteen、shuttle 和 notices 都是插件文档。TypeScript 只用于框架自己的功能，例如界面、看板、定时任务、日程、待办、记忆和模型服务商，以及插件语言暂时还无法表达的服务。

## 如何选择插件的形式

```
插件只需要请求校园网站或公开网站，再从响应里提取数据吗？（需要时可以带上用户的校园会话）
├─ 是 → 插件文档（PLUGIN.md）。从快速上手开始，或者让 App 里的 AI 帮你写。
└─ 否 → 需要通用代码，或者需要你自己的服务器吗？
         ├─ 是 → 远程插件。从 templates/remote-plugin 开始。
         └─ 否，需要设备能力，或插件语言做不到的原生界面
              → 内置 TypeScript 插件（请先开一个 issue），或者提议新增一项宿主能力。
```

大多数校园服务只需要发请求、再从响应里提取数据，这类插件写成插件文档就够了。你可以从[快速上手](/docs/build/quickstart)开始，也可以直接让 App 里的 AI 帮你写。

如果需要通用代码或自己的服务器，就写远程插件，从 `templates/remote-plugin` 模板开始。只有需要插件语言还不支持的设备能力或原生界面时，才写内置 TypeScript 插件。这种情况请先开一个 issue。你也可以提议新增一项宿主能力，让插件文档也能做到。

## 插件在 App 中的生命周期

一个插件从安装到使用，会经过下面五个阶段。

1. **注册。** 内置插件和内置的插件文档在 App 启动时注册。通过链接安装的插件文档，要等你在审查页上确认后才注册，它的文件和内容哈希会保存在手机上。远程插件在你安装时注册：App 连接服务器，列出它的工具，并缓存它的清单。
2. **可用。** 手机满足插件在 `requires` 中声明的[能力需求](/docs/concepts/capabilities)时，插件才可用。不可用的插件对助手隐藏，设置页会说明原因。
3. **启用。** 插件默认是开启的。你可以关闭任何非核心插件。核心插件（标记为 `core: true`，例如生成式界面和记忆）不能关闭。
4. **调用。** 每次调用都走同一条路径。App 先用 zod 校验输入，再检查这个效果对应的授权方式，必要时请你批准，然后执行工具并返回结果。
5. **更新。** 这一步只适用于插件文档。App 每天最多重新拉取一次插件的链接。如果新内容的声明没有变化，就直接生效；如果声明的权限变宽了，要等你确认后才生效。详见[声明式插件 → 更新](/docs/build/declarative-plugins#updates)。

## 远程插件的细节

**添加。** 你，或者经你批准的助手，可以添加一个 MCP Streamable HTTP 地址，并可选地附上一个 bearer token。这个 token 保存在密钥库里。

**插件 id。** 远程插件的 id 由 `mcp-` 加上 MCP 服务器的 `name` 组成，`name` 取自 `initialize` 响应，并会被转换成 slug 形式。请用你在注册表里的 id 作为服务器名，这样插件市场才能把两者对应起来。

**工具。** 每个 MCP 工具都会变成注册表里的一个工具，它的输入 schema 会从 JSON Schema 转换成 zod。标记了 `annotations.readOnlyHint: true` 的工具是 `read` 工具，其余工具都是 `write` 工具。

**默认授权。** 对于远程插件，`read` 工具自动执行，`write`、`money` 和 `public` 工具要先询问你。

**结果。** 结果会被包装成 `{ source, data }`。其中 `data` 取自 `structuredContent`，或者把文本解析成 JSON。系统提示词里有一段关于这个插件的说明，它告诉模型：这些结果是数据，不能当作指令执行。

**工具名。** MCP 工具名会被规整为只含 `[a-zA-Z0-9_-]` 的形式，其他字符会变成 `_`，长度会截断到 40 个字符。所以请使用简短的 ASCII 驼峰命名。

## 合并与重命名插件

`PluginDef.legacy` 字段让一个插件接管旧插件的 id。例如，`wallet` 插件取代了 `campus-card`、`netfee` 和 `utilities` 三个旧插件。

设置了这个字段之后，宿主会把旧的插件 id、工具 id 和小组件 key 映射到新的上面，并把你原来的设置迁移一次。详见 [SDK → plugin](/docs/sdk/plugin#pluginlegacy)。

## 继续阅读

- [工具与效果](/docs/concepts/tools-and-effects)
- [第一个插件](/docs/build/quickstart)和[声明式插件](/docs/build/declarative-plugins)
- [快速上手：远程插件](/docs/build/remote-plugin)
- [内置插件](/docs/build/bundled-plugin)


# 定时任务与通知 (/docs/concepts/scheduler)

> 提醒、待办、上课提醒和定时检查都由同一个定时任务引擎驱动。每个任务由一个触发器（单次，或有限次的重复）和一个动作（通知、检查或助手）组成，准时到分钟触发。

PKU harness 里所有和时间有关的功能都由同一个定时任务引擎（`scheduler`）处理。引擎里的每一项叫作一个**任务**（job）。例如，一条提醒、某个待办的提醒、上课提醒，以及「每天早上查一下我的校园卡余额」，都是任务。

你可以在「日程」标签页里创建任务，也可以直接让助手创建。插件通过 `services.scheduler` 创建任务。

每个任务由两部分组成：**触发器**（trigger）决定它什么时候运行，**动作**（action）决定它运行时做什么。

## 任务的结构

```ts
type Job = {
  id: string;
  title: string;
  trigger: Trigger;          // 何时触发
  action: Action;            // 做什么
  enabled: boolean;
  source: 'user' | 'agent' | 'plugin';
  runs: number;              // 已触发（或已错过）的次数
  lastRunAt: number | null;
  nextRunAt: number | null;  // 系列结束后为 null
  // check / agent 任务还会记录 lastValue、lastError、history（最近 20 次）、failures …
  meta?: Record<string, unknown>;  // 指回所属对象，例如 { todoId }
  createdAt: number;
  updatedAt: number;
};
```

## 触发器

触发器有两种，所有时间都按**手机的本地时间**计算。

**单次触发器** `{ type: 'at' }` 只有一个字段 `at`，是一个毫秒时间戳。它适用于「两天后」「明天 8:00」这样的提醒。

**重复触发器** `{ type: 'every' }` 适用于「每天早上 8 点」「每 3 天一次，共 16 次后停止」「每周一、三、五 07:30，直到学期结束」这样的提醒。它有以下字段。

| 字段 | 含义 |
| --- | --- |
| `unit` | 重复的单位：`minute`、`hour`、`day` 或 `week` |
| `interval` | 每隔几个单位重复一次，取值 1–1000 |
| `times?` | 一天中的时刻，格式为 `"HH:MM"`，用于 `day` 和 `week` |
| `weekdays?` | 星期几，0 表示周日，6 表示周六，用于 `week` |
| `startAt` | 开始时间 |
| `count?` | 最多触发几次 |
| `until?` | 截止日期（含当天） |

重复触发器的计算方法如下。一个重复系列由若干个周期组成，每个周期是一个分钟或小时步长、一天，或者从周一开始的一周。每个周期里有若干个时间点，由时刻和星期组合而成。早于 `startAt` 的时间点会被跳过，剩下的依次编号为 0、1、2……，最后由 `count`、`until` 或两者共同截断。

助手和表单使用一种更容易书写的输入格式 `ScheduleInput`，时间写成本地时间字符串 `"YYYY-MM-DD HH:mm"`。例如，「每 3 天一次，09:00，共 16 次」写作：

```json
{ "type": "repeat", "unit": "day", "interval": 3, "times": ["09:00"], "count": 16 }
```

`toTrigger(input)` 把它转换成触发器。`summarize(trigger)` 返回 `{ schedule, next, total, finished }`，例如 `"每 3 天 09:00 · 共 16 次"` 以及接下来的三个触发时间。助手可以在保存之前把这些时间告诉你，请你确认。

## 动作

动作有三种。

| 动作 | 字段 |
| --- | --- |
| `notify` | `title`、`body?`、`url?` |
| `check` | `tool`、`args?`、`condition`、`title`、`body?`、`url?` |
| `agent` | `prompt`（4–1000 个字符） |

**`notify`** 发送一条通知。它会提前注册为精确通知，触发时不运行任何代码。`url` 是点击通知后打开的 App 内路由。

**`check`** 是定时检查。它调用一个只读工具（形如 `<plugin>.<tool>`），读取结果中 `condition.path` 处的值，只有条件成立时才发送通知。通知文案里的 `{value}` 会被替换成读到的值。

**`agent`** 让助手定时运行一次。每次运行都新开一个只读的助手会话，不带任何聊天记录。如果助手回复 `NO_REPLY`，就表示这次不需要打扰你；否则，它的简短回答就是通知的内容。

`check` 的条件写作 `{ path, op, value? }`。`op` 取以下值之一：`<`、`<=`、`>`、`>=`、`==`、`!=`、`changed`、`always`。

下面的检查在校园卡余额低于 100 元时提醒你充值：

```json
{
  "type": "check",
  "tool": "wallet.cardBalance",
  "condition": { "path": "balance", "op": "<", "value": 100 },
  "title": "校园卡余额只剩 ¥{value}，记得充值"
}
```

## 在 Android 上准时送达

**`notify` 任务**会提前注册为精确闹钟。注册的范围是未来 14 天，每个任务最多 64 个，总共最多 400 个。App 启动时、任务每次变更时、App 回到前台时，以及后台任务运行时，都会重新注册。

**`check` 和 `agent` 任务**在 JavaScript 里运行。App 在前台时，由计时器准时到分钟触发它们。App 在后台或已被系统关闭时，由精确闹钟唤醒一个后台任务（headless task）。这个后台任务会执行所有到期的任务，注册下一个闹钟，并移除占位通知。

准时送达需要两项权限：通知权限，以及「闹钟和提醒」这项特殊权限。Android 14 及以上版本默认不授予后者。关闭电池优化只是建议，不是必需的。

插件可以用以下函数检查和修复这些设置。

- `services.notify.readiness()` 报告这三项的状态。
- `deliveryBlocker(readiness)` 指出第一个阻碍准时送达的项目。
- `services.notify.fix(kind)` 打开对应的系统弹窗或设置页。`fix` 必须在用户点击时调用。

## 无人值守时的限制

定时检查运行时，没有人在旁边看着。所以它的权限受到限制，每次运行都有记录，失败时会明确提醒你。

| 规则 | 取值 |
| --- | --- |
| 可调用的工具 | 只能是 `read` 工具 |
| 启用中的任务 | 最多 50 个（`MAX_ACTIVE_JOBS`） |
| 检查频率 | 最多每 15 分钟一次（`MIN_CHECK_GAP_MS`） |
| 助手任务的数量 | 最多 10 个（`MAX_AGENT_JOBS`） |
| 助手任务的频率 | 最多每小时一次（`MIN_AGENT_GAP_MS`） |
| 助手任务每次的步数 | 最多 8 步（`AGENT_MAX_STEPS`） |
| 迟到的运行 | 迟到超过 2 小时（`MAX_LATE_MS`）记为错过 |
| 运行日志 | 保留最近 20 次（`HISTORY_LIMIT`） |
| 连续失败后提醒 | 2 次（`FAIL_ALERT_AFTER`） |
| 连续失败后停用 | 10 次（`DISABLE_AFTER`） |

对这些规则的补充说明如下。

- 工具的效果在运行时会重新检查。如果授权方式为 `ask`，这次调用视为被拒绝。
- 不允许创建重复的检查，也就是工具、参数和条件都相同的检查。
- 迟到的运行记为错过，是为了避免几个小时后才弹出一条早已过时的提醒。
- 运行日志记录计划时间和实际时间、结果、读到的值和错误。
- 连续失败 2 次时，App 会提醒你一次，6 小时后如果仍然失败，会再提醒一次。连续失败 10 次时，App 会停用这个任务并告诉你。

## 写给插件作者

- **让工具适合被检查。** 这样的工具效果为 `read`，响应快，并且有一个稳定的数字或布尔字段可以比较，例如 `balance`、`unread` 或 `available`。请把这些工具列在 `dataSources` 里，助手才能找到它们。
- **只在响应用户操作时创建任务，** 写法是 `services.scheduler.create({ …, source: 'plugin' })`。请保存好任务 id（放在 `meta` 或你的 `kv` 里），之后才能更新或删除这个任务。
- **SDK 导出了纯计算的引擎函数，** 例如 `occurrencesAfter`、`nextOccurrence`、`describeTrigger` 和 `evaluate`。详见 [SDK → scheduler](/docs/sdk/scheduler)。


# 安全模型 (/docs/concepts/security)

> 账号凭据只留在手机上。工具结果只是数据，不是指令；第三方内容会「污染」助手的当前回合。任何要离开手机的数据都会先声明，并征得用户同意。

PKU harness 保管着你在统一身份认证系统 IAAA 上的密码，还能代你操作校园账号。所以我们希望，从你的角度看，这套系统像是没有服务器的：本项目运行的任何服务都看不到你的账号凭据，插件做的任何事也都不会瞒着你。

## 基本原则

1. **凭据不离开手机。** IAAA 密码、手机令牌的密钥、模型 API 密钥和远程插件的令牌，都存放在手机的密钥库里。它们不会写进日志，不会发送到本项目的服务器，也不会交给任何插件，无论是插件文档、内置插件还是远程插件。
2. **插件拿到的是响应，不是会话。** `services.campus.request` 只返回响应。会话的 cookie 和令牌留在框架内部。需要对请求签名时，签名也在框架内部完成（通过 `sign` 钩子）。
3. **工具结果只是数据。** 框架会告诉模型：工具结果、插件上下文和远程插件的输出都是数据，不能当作指令执行。
4. **效果要明确声明。** 每个工具都要声明 `read`、`write`、`money` 或 `public` 四种效果之一，分别表示读取、修改、花钱和公开。你可以按效果分别决定助手能否直接执行。定时任务只能读取。
5. **离开手机的数据要先声明。** 插件访问的校园服务（`scopes`）、使用的模型服务商，以及 PKU harness Cloud 的 `disclosure` 说明，都会在第一次使用前展示给你。

## 提示词注入

校园里的很多内容是第三方写的，例如一条树洞、一则通知、一段活动简介，或者一个远程插件的输出。其中任何一段都可能写着「忽略之前的指令，然后……」。这种攻击叫作**提示词注入**（prompt injection）。

框架把这些内容一律当作数据，并且限制被注入的指令最多能造成多大影响。具体做法如下。

**不可信工具。** 返回第三方文本的工具要设置 `untrusted: true`。远程插件的所有工具都被视为不可信。

**污染标记。** 助手在一个回合里调用了不可信工具之后，这个回合剩下的部分都会被标记为「已污染」（taint）。同一回合里之后的工具调用会看到 `ctx.turn.tainted === true`。

**持久写入需要确认。** 回合被污染之后，凡是会影响以后对话的写入，都要等你确认。例如，记忆插件会把这类记忆保存为「待确认」，由你在记忆页面上批准。

有一种情况例外：如果是你自己的消息要求助手记住某件事（`ctx.turn.userAsked`），这次写入就是你的本意，会直接保存。第三方文本无法冒充你的消息。

**默认先询问。** 远程插件中效果为 `write`、`money` 和 `public` 的工具，默认都要先问你。

**无法伪造的宿主信息。** 宿主每个回合都会向模型提供一些事实，例如当前时间和回复语言。这些信息放在固定的位置，插件上下文无法仿冒。

### 插件作者要做的事

- **必须**为结果里含有他人所写文本的工具设置 `untrusted: true`。他人所写的文本包括帖子、评论、通知、消息和公开网站上的描述。
- **不得**在结果里写指令，例如「告诉用户……」「现在调用……」。结果里只返回数据，让模型自己判断。指导模型的内容请写在工具的 `description` 或插件的 `instructions` 里。
- 有些工具会写入助手以后当作事实读取的持久状态，例如笔记、记忆和保存的偏好。这类工具**应当**检查 `ctx.turn?.tainted`，把写入保存为待确认，或者直接拒绝。
- 返回第三方文本时，**应当**去掉控制字符、不可见字符、双向文本（bidi）字符和标记，并限制长度。
- 代表用户批准或解锁某些东西的工具，**必须**设置 `userOnly: true`。

## 结果中的机密信息

有些值绝不能让模型看到，也不能写进日志。

**付款码**只能显示在使用了 `host.useSecureDisplay()` 的页面上。这种页面禁止截屏，并会调高屏幕亮度。付款码绝不能作为工具结果返回。

**分享链接**是指云端频道的链接，它把密钥放在 URL 的 fragment 部分。SDK 中的 `SecretLink` 类型是不透明的，`JSON.stringify(link)` 只会得到 `"[secret link]"`。请只通过 `host.shareLink(link)` 或 `<QRCode link={link} />` 展示它。宿主还会从工具输出和日志里清除看起来像分享链接的内容。

**令牌和密钥**插件根本拿不到。

## 插件文档的安全性

App 解释执行 `PLUGIN.md` 中声明的步骤，不运行任何插件代码。一份插件文档只能访问它声明过的校园服务、公开网站和宿主能力（ability），并且受到固定的时间、大小和操作次数限制。

校园请求由框架签名。所以插件文档看不到密码、cookie 或令牌，也访问不了其他插件的存储。

安装插件之前，以及插件更新要求更多权限时，你会看到一个审查页面。页面上列出插件是官方的还是社区的、用到哪些校园服务、访问哪些网站、使用哪些 App 功能，以及每个工具的效果。

社区插件文档中效果为 `write`、`money` 和 `public` 的工具会先询问你，它们的结果也按不可信数据处理。助手可以起草插件，但不能安装插件：`plugins.install` 只会打开审查页面，由你决定是否安装。

## 远程插件的安全性

远程插件运行在别人的服务器上。它收不到校园凭据、会话或你的其他数据，只能拿到助手发给它的工具输入。

它的工具都是不可信的，修改类效果默认先询问你。系统提示词里关于它的那一段也会说明，它的输出只是数据。只有在维护者审查过源码之后，注册表才会把它的条目标记为 `verified`。

## PKU harness Cloud

可选的云服务默认使用端到端加密。它只通过一对密钥识别设备，不涉及学号或姓名。每个插件使用云服务之前，都要单独征得你的同意，并附上通俗易懂的说明。详见 [Cloud → 安全](/docs/cloud/security)。

## 报告漏洞

请按照 [`pkuinfo/pku-harness`](https://github.com/pkuinfo/pku-harness) 或 [`pkuinfo/pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 仓库中 `SECURITY.md` 的说明，私下报告漏洞。请不要公开提 issue。


# 工具与效果 (/docs/concepts/tools-and-effects)

> 工具是插件对外提供功能的唯一方式。每个工具有 id、标题、写给模型的说明、zod 输入 schema，以及唯一一个效果（read、write、money 或 public）。

**工具**（tool）是插件提供的一个有类型的操作，例如「查询校园卡余额」或「创建一条提醒」。

同一个工具可以被四种方式调用：助手在对话中调用它；页面在用户点击时通过 `invoke` 调用它；小组件通过 `host.useToolData` 读取它；定时检查也会运行它。除了工具，没有其他途径能用到插件的功能。所以，插件定义了哪些工具，就决定了它对外提供哪些功能。

## 工具的结构

下面是校园卡余额工具的定义。

```ts
import { defineTool } from '@pku-harness/sdk';
import { z } from 'zod';

const cardBalance = defineTool({
  title: '校园卡余额',                       // 展示给用户（对话中的标签、审批弹窗、设置页）
  description: 'Campus card balance in CNY, today\'s spending and the daily limit. Use when the user asks how much money is left on the card.',
  input: z.object({}),                      // 在 execute 运行前校验
  effect: 'read',                           // 它会改变什么：read | write | money | public
  execute: async (_input, ctx) => {
    const res = await ctx.services.campus.request('card', { url: '/berserker-app/ykt/tsm/queryCard?synAccessSource=h5' });
    return parseBalance(res.body);          // 只返回 JSON 数据，绝不包含指令
  },
});
```

每个字段的规则如下。

- **`title`**：简短的中文标题，展示给用户看。英文标题写在 `i18n.en.tools.<name>.title`。
- **`description`**：写给模型看的说明。它要告诉模型**什么时候**用这个工具、**怎么**用，以及单位、格式和限制。可以用中文或英文写，不需要翻译。它也可以是一个依赖宿主服务的函数（`Dynamic<string>`）。
- **`input`**：一个 zod schema。请给每个字段加上 `.describe()`，因为模型看到的是由它生成的 JSON Schema。
- **`effect`**：工具的效果，从下一节的四种效果中选一个，并且要如实填写。
- **`untrusted`**：如果结果里有第三方写的文字，例如论坛帖子、通知或活动简介，设为 `true`。
- **`userOnly`**：有些操作只能由用户亲自触发，助手不能自己打开。这时设为 `true`。工具会对模型隐藏，来自助手和定时任务的调用都会被拒绝。
- **`execute`**：形式为 `(input, ctx) => Promise<output>`。失败时抛出一个 `Error`，错误信息要清楚，让用户能看懂。

## 工具的 id 与名称

工具有两种写法，分别给代码和模型使用。

**工具 id** 的形式是 `<plugin id>.<tool name>`，例如 `wallet.cardBalance` 和 `scheduler.create`。代码里都使用 id，例如 `invoke('memory.list')`、`host.useToolData('wallet.cardBalance')`，以及检查任务和小组件绑定。

**模型看到的名称**是把 id 中第一个 `.` 换成 `__`，例如 `wallet__cardBalance`。这是因为模型 API 不允许工具名里出现点号。在 `instructions` 或说明里提到某个工具时，请使用这种写法，例如 `"use canteen__openNow for …"`。

**远程插件**的工具 id 是 `mcp-<server>.<tool>`，模型看到的名称是 `mcp-<server>__<tool>`。

## 四种效果

效果（effect）描述一个工具会改变什么。每个工具只能有一种效果。

| 效果 | 含义 | 例子 |
| --- | --- | --- |
| `read`（读取） | 只读取数据，不改变任何东西 | 查余额、查课表、搜索、列出 |
| `write`（修改） | 改变手机上或服务端的状态 | 添加待办、创建提醒、关注帖子、预约房间 |
| `money`（花钱） | 花钱、转钱，或者让付款成为可能 | 校园卡充值、创建支付订单、切换到电子校园卡付款 |
| `public`（公开） | 发布别人能看到的内容 | 在树洞发帖或回复 |

如果一个工具同时符合几种效果，请选**最强**的那个。例如，一个工具既公开发帖，又修改本地状态，它的效果就是 `public`。

效果决定了[权限](/docs/concepts/permissions)。你可以针对每个插件的每种效果，选择助手可以直接执行、需要先询问，还是完全不能执行。

<Callout title="定时任务只能读取">
  定时任务运行时没有人在旁边看着。所以无论你怎么设置授权方式，定时任务都会拒绝所有效果不是 `read` 的工具。只有确实不改变任何东西的工具，才能标成 `read`。否则，基于它的定时检查会误导用户。
</Callout>

## 谁在调用工具

`ctx.actor` 告诉工具是谁发起了这次调用。调用者有三种。

| 调用者 | 何时出现 | 是否需要批准 |
| --- | --- | --- |
| `user` | 页面或小组件响应用户点击，调用了 `invoke(...)` | 从不询问 |
| `agent` | 模型在对话中调用了工具 | 该效果的授权方式为 `ask` 时询问 |
| `scheduler` | 定时检查或定时 Agent 任务 | 只能使用 `read` 工具 |

用户的调用从不询问，因为点击本身就表达了用户的意图。定时任务遇到授权方式为 `ask` 的工具时，会把它当作被拒绝。

助手在对话中调用工具时，`ctx.turn` 会被设置为 `{ sessionId, tainted, userAsked }`。其中 `tainted` 的含义见[安全模型](/docs/concepts/security#prompt-injection)。

## 如何返回结果

- **返回能直接回答问题的 JSON。** 字段名里带上单位，例如 `balanceYuan` 和 `minutesUntil`。时间用 ISO 格式或本地时间 `"YYYY-MM-DD HH:mm"`。如果模型可能要把某个 id 传给下一个工具，就把它也放进结果。
- **不要返回指令**，例如「现在告诉用户……」。模型会把结果当作数据。
- **结果要小。** 在模型的历史记录里，框架会把单个结果截断到 12,000 个字符，界面上仍然保留完整输出。所以请分页或过滤，不要把所有数据一次返回。
- **预期内的、可以恢复的状态，返回状态对象，不要抛出异常。** 例如树洞需要短信验证时，返回 `{ status: 'verification_required', methods: ['sms'], message: '…' }`。
- **绝不返回机密信息**，例如付款码、令牌和分享链接。校园卡付款码只会显示在页面上，不会出现在工具结果里。

## 数据源

有些读取工具很适合给小组件和定时检查使用。插件可以在 `PluginDef.dataSources` 里列出这些工具，并为每个工具指定缓存时长。助手通过 `dashboard.sources` 找到它们。

```ts
dataSources: {
  crowd: { title: '食堂就餐人数', tool: 'crowd', ttlMs: 2 * 60_000 },
},
```

`tool` 是本插件内部的工具名。如果需要固定的参数，写在 `args` 里。


# 参与贡献 (/docs/ecosystem/contributing)

> 如何为 PKU harness 贡献插件、应用改动、协议说明和文档，以及需要遵守的约定、安全规则和许可证。

PKU harness 面向北大社区公开开发，每个仓库都欢迎 issue 和 pull request。本页说明不同的改动应该提交到哪个仓库，以及我们对贡献的要求。

## 从哪里入手

该去哪个仓库，取决于你想改什么。

- **接入一个校园服务或增加一项功能**：一般写成插件文档。如果插件需要自己的服务器，就在你自己的仓库里写一个远程插件。官方插件放在 [`pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 仓库，动手之前请先在那里开一个 issue。参见[编写插件](/docs/build)。
- **把插件上架**：参见[插件市场](/docs/marketplace)。
- **修复或改进应用**：提交到 [`pku-harness`](https://github.com/pkuinfo/pku-harness)。开始之前请先读 `AGENTS.md`、`docs/ARCHITECTURE.md` 和 `docs/DESIGN.md`。
- **记录或修复校园服务协议**：提交到 [`pkucli`](https://github.com/pkuinfo/pkucli)。
- **改进这份文档**：提交到 [`pkuharness-website`](https://github.com/pkuinfo/pkuharness-website)。页面在 `content/docs/` 目录下，每一页都有编辑链接。

## 约定

- JavaScript 和 TypeScript 一律使用 **bun**（`bun install`、`bun run`、`bun test`、`bunx`）。
- 每次提交只做一件小事，提交信息遵循 Conventional Commits，例如 `feat(wallet): …`、`fix(treehole): …` 或 `docs: …`。
- 在插件仓库或应用仓库提 pull request 之前，先运行 `bun run verify`，确认它通过。这个命令执行的检查和持续集成（CI）完全相同：插件仓库会做类型检查、插件清单校验、内置文档检查，并运行全部测试；应用仓库会做类型检查、lint，并运行测试。
- 改了界面的话，要在真机或模拟器上分别用深色和浅色主题检查一遍。
- 插件的改动先合入 `pku-harness-plugins`，再由应用仓库提交 `plugins/` 子模块的版本更新。
- 校园服务协议从 pkucli 移植，并在注释里注明来源文件。
- 文档和代码注释用英文书写。展示给用户的文字以中文为主，每一条都要配上英文翻译。

## 借助 AI 编程助手

这些仓库在设计上就是供人和编程助手一起开发的，每个仓库都有一份 `AGENTS.md`（或 `CLAUDE.md`），写明了各自的规则。如果你让助手帮忙写插件，可以把它指向[给 AI 助手](/docs/for-agents)这一页，以及这份文档的 Markdown 版本（`/llms.txt`）。

提交的内容由你本人负责。请审阅生成的代码，亲自跑通检查，并且不要让助手接触真实的账号密码。

## 社区

- 想法和 bug 请在对应仓库的 GitHub issue 里讨论和报告。
- 请友善待人。应用、插件和网站这三个仓库都有行为准则（`CODE_OF_CONDUCT.md`）。

## 安全

发现漏洞时，请按照受影响仓库的 `SECURITY.md` 私下报告，不要发公开的 issue。另外，不要在 issue、测试数据或日志里放入真实的账号密码、token 或个人信息。

## 许可证

所有仓库都采用 MIT 许可证。提交贡献即表示你同意以同一许可证发布你的贡献。


# 仓库 (/docs/ecosystem/repositories)

> pkuinfo 组织下的各个仓库（应用、插件仓库、pkucli、pkubdcard 和本网站），每个仓库包含什么，以及它们之间的依赖关系。

项目的全部代码都开源在 GitHub 组织 [`pkuinfo`](https://github.com/pkuinfo) 下，分成五个仓库。

| 仓库 | 技术栈 |
| --- | --- |
| [`pku-harness`](https://github.com/pkuinfo/pku-harness) | Expo SDK 58、React Native 0.88、TypeScript、bun |
| [`pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) | TypeScript、zod、bun workspace |
| [`pkucli`](https://github.com/pkuinfo/pkucli) | Rust workspace（reqwest、tokio、clap） |
| [`pkubdcard`](https://github.com/pkuinfo/pkubdcard) | Go（Gin）+ Preact |
| [`pkuharness-website`](https://github.com/pkuinfo/pkuharness-website) | Next.js 16 + Fumadocs 16、bun |

## 各仓库的用途

**`pku-harness`** 是应用本身。它包含运行 AI 助手循环、承载各个插件的核心（我们称为 harness），以及设计系统、宿主服务、校园会话和调度器。应用优先支持 Android。

**`pku-harness-plugins`** 包含编写插件所需的一切：SDK（`@pku-harness/sdk`）、所有内置插件（`@pku-harness/plugins`）、插件市场清单（`@pku-harness/registry`）、云服务协议（`@pku-harness/cloud-protocol`）、远程插件模板和一些示例。想写插件的话，从这个仓库开始。

**`pkucli`** 是一组访问北大各类网站的命令行工具。应用对接的每个校园服务都以它为协议参考：应用需要某个登录流程或接口时，就从这里移植。这个仓库还提供了一些 Agent 技能（skills）。

**`pkubdcard`** 是一个分享校园卡付款码的网页应用，也是 pkucli 校园卡流程更早的一个移植版本。云服务插件 `card-share` 的界面和限流设计都参考了它。

**`pkuharness-website`** 就是本网站，提供首页、下载、这份文档和插件市场。

## 仓库之间的关系

所有校园登录都要经过 IAAA（`iaaa.pku.edu.cn`），也就是北大的统一身份认证服务。pkucli 记录了各个校园服务的协议，应用按照这些协议实现。应用把 `pku-harness-plugins` 作为 git 子模块引入。远程插件通过 MCP（Model Context Protocol，模型上下文协议）连接到应用；PKU harness Cloud（云服务）则基于插件仓库里的云服务协议和参考服务器实现。

| 仓库 | 用到什么 | 方式 |
| --- | --- | --- |
| `pku-harness`（应用） | 北大 IAAA（`iaaa.pku.edu.cn`） | 所有校园登录都经过它 |
| `pku-harness`（应用） | `pkucli` | 按 pkucli 记录的协议实现校园服务 |
| `pku-harness`（应用） | `pku-harness-plugins` | 作为 git 子模块引入 SDK 和插件 |
| 远程插件（任何人都可以写） | `pku-harness-plugins` 的 `templates/remote-plugin` | 从模板开始，通过 MCP 连接到应用 |
| PKU harness Cloud 服务 | `pku-harness-plugins` 的 `cloud-protocol` 和 `cloud-server` | 实现云服务协议，`cloud-server` 是参考实现 |
| `pkuharness-website` | `registry.json`、已收录的插件仓库、GitHub Releases | 生成文档、插件市场和下载页 |

网站独立于其他仓库。它的插件市场读取 `registry.json` 和已收录的插件仓库，下载页列出应用在 GitHub 上发布的版本。

## pku-harness-plugins 的目录结构

| 目录 | 内容 |
| --- | --- |
| `packages/sdk` | `@pku-harness/sdk`：插件接口约定、纯函数工具和插件语言（`src/lang`：schema、解释器、宿主能力、加载器） |
| `packages/cloud-protocol` | `@pku-harness/cloud-protocol`：云服务通信协议的 schema、信封加密、分享链接 |
| `packages/cloud-server` | PKU harness Cloud（云服务）的参考服务器实现（Bun + Hono + SQLite） |
| `plugins/<id>/PLUGIN.md` | 官方插件文档。随应用一起打包（`bun run bundle`），之后从各自的链接更新 |
| `plugins/<id>/src` | 用 TypeScript 写的内置插件（见 `plugins/index.ts` 里的 `builtinPlugins`） |
| `plugins/shared` | 内置插件之间共用的代码 |
| `scripts` | `plugin.ts`（作者命令行：`bun run plugin validate\|test\|run`）、`bundle-docs.ts`、`validate-registry.ts` |
| `registry` | 插件市场的 schema 和 `registry.json` |
| `templates/remote-plugin`、`examples/*` | 远程插件模板，以及 `demo-canteen` 和 `mock-llm` 两个示例 |

这些包只在 workspace 内部使用，都不会发布到 npm。应用把整个仓库作为 git 子模块 `plugins/` 引入。

插件文档的分享方式和 Agent 技能一样，是一个文件夹或一个链接，由应用读取并解释执行。详见[声明式插件](/docs/build/declarative-plugins)。

## 目前的内置插件

应用目前内置了以下插件文档：`classrooms`、`campus-events`、`grades`、`canteen`、`shuttle` 和 `notices`。

另外还内置了这些 TypeScript 插件：`ui`（生成式界面）、`dashboard`、`scheduler`、`todo`、`schedule`、`timetable`、`course-sync`、`authenticator`（手机令牌）、`calendar`（校历）、`wallet`（校园卡、网费、宿舍水电）、`card-share`（通过云服务分享付款码）、`courses`（教学网）、`course-catalog`、`treehole`、`elective`、`finance`、`library`、`room-booking`、`memory`、`plugins`（插件管理和 AI 编写插件）、`deepseek` 和 `openai-compatible`。

每个插件的介绍见[插件市场](/marketplace)。


# 路线图 (/docs/ecosystem/roadmap)

> PKU harness 已完成、进行中、计划中和暂缓的工作，整理自应用仓库的开发计划和设计文档。

本页整理自 [`pku-harness`](https://github.com/pkuinfo/pku-harness) 仓库里的开发计划和设计文档：`docs/PLAN.md`、`docs/CLOUD.md`、`docs/PLUGIN-LANGUAGE.md`、`docs/CLOUD-FUNCTIONS.md` 和 `docs/OTA.md`，内容截至 2026-10-24。各项工作以 PLAN.md 为准，它会随开发进度更新；需要最新细节时请直接查看它。

## 当前状态

- Android 应用的 1.0.0 版本已经发布。
- OTA（over-the-air，空中下载）更新已经上线。App 的 JavaScript 代码（包括内置在 App 里的插件）有改动时，可以通过 OTA 直接更新到已安装的应用上，不需要重新安装 APK。插件文档不走 OTA，而是从各自的链接更新。
- PKU harness Cloud（云服务）的官方实例还没有部署。
- 官方服务器上的插件服务端函数处于关闭状态。

## 已完成

**基础与设计系统**：Expo + bun 项目脚手架、设计 token、玻璃质感的设计语言、动效基础组件、四个标签页的框架，以及首次启动引导。

**核心运行时**：数据存放在 SQLite 和系统密钥库中。插件运行时负责处理效果、授权和审批。模型服务以插件形式提供，默认使用 DeepSeek，也可以接入兼容 OpenAI 接口的服务。Agent 循环支持流式的工具调用。

**Agent 框架**：这是应用中负责和 AI 助手对话的部分，目前支持：
- 多个会话，自动生成标题，回复可以在后台继续；
- 斜杠命令；
- 输入框支持附件、消息排队和模型选择；
- 上下文管理与压缩；
- 提示词的排列方式便于模型服务复用前缀缓存；
- 显示 token 用量和费用的看板；
- 带审批的记忆功能：从不可信内容里得到的信息会先被「污染闸门」拦下，等你同意后才写入记忆。

**生成式界面**：json-render 组件目录、`ui.render` 工具，以及能把填写结果回传给助手的表单。

**校园服务接入**：原生的校园 HTTP 模块。通过 IAAA（北大统一身份认证）登录，只在服务要求时才需要二次验证。手机令牌。短信验证码一键读取。带文件选择器的 multipart 上传。在浏览器中以已登录状态打开校园网站。校园卡、ITS、树洞、教学网、bdkj、cwfw、cwpay、选课和图书馆的适配器。

**校园插件**：校园钱包（校园卡、网费、宿舍水电）、课表同步、教学网课程、成绩、树洞、校园活动、选课（只读）、财务、空间预约、课程查询、校历、食堂、班车、通知公告等。

**看板**：小组件模型，小组件可以由 AI 生成，也可以由插件提供。每个小组件在后台刷新时先显示上一次的数值（stale-while-revalidate）。看板还有编辑模式和小组件库。

**调度器**：重复规则引擎和准点通知。在 Android 上，检查任务在后台、甚至应用被杀掉之后都能准时运行。还包括由助手执行的定时任务、无人值守运行的策略，以及引导你授予准点送达所需权限的步骤。

**日程标签页**：支持单双周和课前提醒的课表、待办事项，以及可以自由设置重复规则的提醒。

**插件生态**：插件仓库，包括 SDK、插件清单及其校验器。通过 MCP（Model Context Protocol，模型上下文协议）连接的远程插件，调用时需要审批。应用内的插件市场。插件可以向应用添加页面、设置项、标签页、小组件和命令。

**插件语言（规范 1）**：插件可以是一个可分享的文件夹，里面有一个 `PLUGIN.md` 文件，由应用解释执行。这部分工作包括：
- SDK 中的解释器和宿主能力，包括 `verify.treehole`；
- 作者命令行（`bun run plugin validate|test|run`），每份文档录制好的测试都在持续集成（CI）中运行；
- 通过链接或 `pkuharness://plugin` 安装，安装前会显示审核页；
- 每天检查更新，如果新版本申请了更多权限，要等你同意后才会更新；支持回滚；
- 官方文档随应用打包，并从各自的链接更新；
- [AI 编写插件](/docs/build/ai-authoring)用到的工具（`plugins.reference / validate / tryTool / source / install`）。

**官方插件文档**：classrooms、campus-events、grades、canteen、shuttle 和 notices 已经从 TypeScript 移植成插件文档。每个移植版本都通过了对拍测试，原来的 TypeScript 版本已经删除。

**PKU harness Cloud（云服务）**：通信协议 v1 和信封加密、SDK 中的云服务类型，以及插件清单的 `cloud` 字段。用 Bun、Hono 和 SQLite 实现的参考服务器。宿主客户端，包括设备身份、授权、端到端加密的存储和通道，以及「设置 → 云服务」页面。Android 前台服务（`services.ongoing`）。`card-share` 插件，带网页查看页和 `pkuharness://share` 链接。

**发布与更新**：1.0.0 版本已经发布。推送版本 tag 后，CI 会构建签名的 APK，并发布到 GitHub Releases。自建、经过代码签名的 OTA 更新已经上线：它使用 expo-updates，在 CI 中基于公开的提交签名，由我们的服务器以静态文件的形式提供。

## 进行中

- **把集成移植成插件文档**：接下来是课程查询、选课、图书馆的只读功能和树洞工具，之后是需要新宿主能力的那一批。详见[声明式插件](/docs/build/declarative-plugins)。
- **iOS**：应用已经能在 iOS 上安全启动，钥匙串和通知相关的工作也已完成。校园 HTTP 模块的 Swift 移植还没有做。
- **第二批插件**：更完整的水电和财务功能，教学网作业提交和智云课堂，图书馆的借阅、续借和座位预约，以及门户应用等校园生活功能。
- **实地验证**：有些服务只能在特定时间测试。例如选课系统，不在补退选期间就无法测试。

## 计划中

- **PKU harness Cloud**：部署官方实例，并保持最小规模，只提供实时分享用的中继、小型的端到端加密存储和查看页。支持多台设备配对。
- **插件需要的宿主能力**：为插件提供限定范围的公网 HTTP 访问。
- **限定范围的会话授权**：让远程插件不接触你的账号密码，也能操作校园服务。
- **官方托管的模型服务选项。**

## 暂缓

**插件服务端函数**目前暂缓开发。这类函数在 `PLUGIN.md` 里用 `server:` 声明（见 `docs/CLOUD-FUNCTIONS.md`）。已有的实现保留在参考服务器中，但在官方服务器上是关闭的；集合、定时任务、推送、群组和 webhook 都暂不开发。现阶段请让插件在手机上完成工作，或者使用你自己的后端。

## 暂不考虑

暂不考虑开发应用的网页版，也不考虑在应用内支付：需要付款时，应用会跳转到官方收银台。


# 写给 AI 助手 (/docs/for-agents)

> 写给编程 Agent（Claude Code、Codex、App 内置助手）的说明，帮助它从头到尾做出一个 PKU harness 插件。内容包括如何选择插件类型、具体步骤、必须遵守的规则、要运行的检查，以及应当加载哪些页面。

这一页写给 AI 编程助手。如果你是一个 AI Agent，正准备为 PKU harness 写插件，请按顺序读完本页。

本页链接的页面都有 Markdown 版本。你可以在任意文档 URL 后面加上 `.md` 来加载单个页面，也可以先读 `/llms.txt` 里的索引。如果需要一次拿到全部内容，中文版在 `/llms-full.zh.txt`，英文版在 `/llms-full.txt`。

请不要编造 API。你需要的每个类型都写在 [SDK 参考](/docs/sdk)里。SDK 参考里没有的东西，就是不存在。

## 0. 加载上下文

下表列出不同任务需要加载的页面。

| 场景 | 加载 |
| --- | --- |
| 所有任务 | `/docs/concepts/plugins.md`、`/docs/concepts/tools-and-effects.md`、`/docs/concepts/permissions.md`、`/docs/concepts/security.md` |
| 插件文档（`PLUGIN.md`） | `/docs/build/declarative-plugins.md`、`/docs/build/quickstart.md`、`/docs/marketplace/manifest.md`，以及下文列出的规范文件 |
| 远程插件 | `/docs/build/remote-plugin.md`、`/docs/marketplace/manifest.md` |
| 内置插件 | `/docs/build/tools.md`、`/docs/build/bundled-plugin.md`、`/docs/sdk/plugin.md`、`/docs/sdk/host-services.md`、`/docs/build/ui.md`、`/docs/build/i18n.md`、`/docs/build/testing.md` |
| 接入校园服务 | `/docs/concepts/campus-sessions.md`、`/docs/build/porting-from-pkucli.md`、`/docs/sdk/campus.md` |
| 用到云服务 | `/docs/cloud/plugin-guide.md`、`/docs/sdk/cloud.md` |

写插件文档时，还要读插件语言的规范 [`PLUGIN-LANGUAGE.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/PLUGIN-LANGUAGE.md)，以及 SDK 中的 `packages/sdk/src/lang/schema.ts` 和 `abilities.ts`。

动手修改之前，先读仓库自己的规则。在 `pku-harness-plugins` 里，规则写在 `AGENTS.md` / `CLAUDE.md` 和 `CONTRIBUTING.md` 中。如果要改 App 本身，也要读 `pku-harness` 里的同名文件。

## 1. 选择插件类型

插件有三种：插件文档、远程插件和内置插件。按下面的顺序判断。

```
插件只需要请求校园网站或公开网站，再从响应里提取数据吗？（需要时可以带上用户的校园会话）
├─ 是 → 插件文档：一个包含 PLUGIN.md 和 tools/*.yaml 的文件夹，由 App 解释执行。
│        通过链接分享和安装，不需要发布新版 App。校园服务默认用这种方式
│        （classrooms、campus-events、grades、canteen、shuttle 和 notices 都是插件文档）。
└─ 否 → 需要通用代码，或者需要你自己的服务器吗？
         ├─ 是 → 远程插件：一个基于 Streamable HTTP 的 MCP 服务器（模板在 templates/remote-plugin）。
         └─ 否，需要设备能力，或插件语言做不到的原生界面
              → 在 pku-harness-plugins 里写内置 TypeScript 插件（请告诉用户先开一个 issue，
                因为内置插件随 App 及其签名的 OTA 更新一起发布），
                或者提议新增一项宿主能力，让插件文档也能做到。
```

下面逐一说明这三种类型。

**插件文档**适合大多数校园服务。它只做两件事：向校园网站或公开网站发请求，再从响应里提取数据。需要登录的网站，可以带上用户的校园会话。插件文档是一个包含 `PLUGIN.md` 和 `tools/*.yaml` 的文件夹，由 App 解释执行。它通过链接分享和安装，不需要发布新版 App。

**远程插件**适合需要通用代码或自己服务器的情况。它是一个 MCP 服务器。MCP 是 Model Context Protocol（模型上下文协议）的缩写，远程插件通过 Streamable HTTP 和 App 通信。模板在 `templates/remote-plugin`。

**内置插件**只在需要设备能力，或者需要插件语言做不到的原生界面时才写。它是 `pku-harness-plugins` 里的一个 TypeScript 模块，随 App 一起发布，修复则通过签名的空中更新（OTA）推送。所以写内置插件之前，请告诉用户先开一个 issue。另一种做法是提议新增一项宿主能力（ability），让插件文档也能完成这件事。

在 App 里，助手先用 `plugins.use` 加载 `plugins` 插件的编写工具，再用它们来写插件文档：`plugins.reference`、`validate`、`tryTool`、`source` 和 `install`。详见[让 AI 写插件](/docs/build/ai-authoring)。

## 2. 插件文档检查清单

1. 选一个工作目录。插件文件夹是自包含的，放在任何仓库里都可以。如果想用插件命令行工具，就在 `pku-harness-plugins` 的本地副本里工作。可以从 `plugins/classrooms` 或[快速上手](/docs/build/quickstart)开始。
2. 编写 `PLUGIN.md`，填写以下字段：
   - `spec: 1`；
   - `id`，需匹配 `^[a-z0-9][a-z0-9-]{1,40}$`；
   - 中文的 `name`；
   - `description`，长度 4–200 个字符；
   - 语义化版本号 `version`；
   - `author`；
   - `campus`、`network` 和 `abilities`，只列出步骤里实际用到的，不多也不少。

   App 加载的每个文件都要在 frontmatter 里列出。
3. 每个操作对应一个工具，写在 `tools/<name>.yaml` 里。每个工具需要：
   - 中文的 `title`；
   - 写给模型看的 `description`；
   - 如实的 `effect`，至少要覆盖它调用的每项宿主能力的效果；
   - 有取值范围的 `input` 字段；
   - 来自第三方的文本标上 `untrusted: true`；
   - 执行步骤，以及一个只返回数据的 `return`。
4. 只使用规范里列出的步骤、标准库函数和宿主能力，其他的都不存在。YAML 有几处容易写错：表达式里含有 `: `，或者以 `{ [ ' "` 开头时，要加引号；正则表达式要写在单引号字符串或 `|` 块里。
5. 不要使用 `server:`、`{ fn }` 绑定或 `cloud` 宿主能力。官方服务器目前关闭了服务端函数，所以插件要么完全在手机上运行，要么使用你自己的后端。
6. 为每个工具在 `tests/<name>.yaml` 里录制响应，并去掉其中的个人数据。失败的情况也要录制，用 `expectError` 表示。
7. 运行下面的命令，直到全部通过。

```bash
bun run plugin validate path/to/plugin
bun run plugin test path/to/plugin
```

8. 校园请求无法在 App 之外运行，所以请说明哪些工具只用录制的响应测试过。最后把 GitHub 文件夹的 URL 作为安装链接分享出去，用户会在 App 里审阅插件后再安装。

## 3. 远程插件检查清单

1. 从 `pku-harness-plugins` 复制 `templates/remote-plugin`，然后运行 `bun install`。
2. 创建服务器：`new McpServer({ name: '<registry id>', version, title: '<Chinese name>' }, { instructions })`。其中 `name` 是注册表 id，需匹配 `^[a-z0-9][a-z0-9-]{1,40}$`；`title` 填插件的中文名。
3. 每个操作调用一次 `registerTool`。工具名用简短的 ASCII 驼峰形式，`title` 用中文，`description` 写给模型看。`inputSchema` 的每个字段都要有说明和取值范围。
4. 不改变任何数据的工具加上 `annotations: { readOnlyHint: true }`。其他工具一律不加。
5. 成功时在 `structuredContent` 里返回数据。失败时返回 `isError: true` 和一句简短的说明。
6. 运行 `bun server.ts`，然后用 App 或任意 MCP 客户端验证。在 Android 模拟器里，地址是 `http://10.0.2.2:8787/mcp`。
7. 通过 HTTPS 部署。然后添加一份清单（manifest）并提交，或者在 `registry.json` 里添加一条记录，见[发布](/docs/build/publishing)。

## 4. 内置插件检查清单

1. 在 `pku-harness-plugins` 的本地副本里工作。App 仓库以子模块 `plugins/` 的形式引入它。SDK 没有 npm 包，`@pku-harness/sdk` 在工作区里解析到 `packages/sdk/src`。
2. 创建两个文件：
   - `plugins/<id>/package.json`：设为 private，`"main": "src/index.ts"`，peer 依赖为 `@pku-harness/sdk`、`zod`、`react` 和 `react-native`；
   - `plugins/<id>/src/index.ts`：导出 `<camelId>Plugin = definePlugin({...})`。
3. 填写这些字段：`id`、中文的 `name` 和 `description`、`version`、`icon`、`requires`、`scopes`，以及用 `defineTool` 定义的 `tools`。`icon` 从宿主图标集中选，且不能和注册表里其他插件重复。可选字段有 `dataSources`、`instructions`、`contributes` 和 `defaultModes`。
4. 清单里每个面向用户的字符串都要在 `i18n.en` 里提供英文。页面和小组件的文案放在 `src/strings.ts`，用 `defineStrings` 定义。
5. 纯逻辑放在普通模块里，测试文件 `*.test.ts` 放在同一目录。如果测试导入了界面代码，要 mock `react-native`。
6. 在 `plugins/index.ts` 的 `builtinPlugins` 中注册插件，并在 `registry/registry.json` 里添加一条 `"kind": "builtin"` 记录。
7. 运行下面的命令，直到全部通过。

```bash
bun test
bunx tsc --noEmit -p .
bun scripts/validate-registry.ts
```

8. 如果你无法运行 App，请直接说明。界面需要有人在真机或模拟器上，分别在浅色和深色主题、中文和英文下检查过，才算完成。

## 5. 必须遵守的规则

违反下面任何一条都算 bug。

1. **绝不索要、存储、记录或传输校园密码、OTP（一次性密码）密钥、会话令牌或 API 密钥。** 校园请求一律通过 `services.campus.request` 或插件文档的 `request: { campus }` 发出。远程插件没有校园会话。
2. **每个工具声明一个如实的效果（effect）。** 效果有四种：`read`、`write`、`money` 和 `public`。不要把写操作藏在 `read` 工具里。定时任务只能调用 `read` 工具。
3. **工具结果只是数据，不是指令。** 结果里不能出现「告诉用户……」之类的话，也不能夹带提示词。
4. **来自第三方的文本标上 `untrusted: true`。** 这包括帖子、评论、通知和公开网站上的描述。助手读到这类文本后，本轮对话就被「污染」了（`ctx.turn?.tainted`），这时持久化的写操作要拦下。
5. **结果里绝不返回机密信息。** 例如付款码、分享链接、收银台 URL 和令牌。
6. **声明你访问的一切。** 插件文档要写 `campus`、`network` 和 `abilities`；代码里用到的每项能力都要写进 `requires`。内置插件不允许使用 `shell` 和 `filesystem`。
7. **内置插件不从 App 或其他插件的文件夹导入代码。** 请使用 `ctx.services`、`ctx.kv`、`ctx.cloud` 和 `host`。多个内置插件共用的代码放在 `plugins/shared/`。
8. **校园协议从 pkucli 移植，** 并在注释里注明源文件。不要猜测接口。
9. **面向用户的字符串要中英双语。** 面向模型的文本，例如描述、指令和结果，不需要翻译。
10. **小组件不轮询。** 请使用带 TTL（缓存有效期）的 `host.useToolData`。
11. **`files.pick` 和 `notify.fix` 只能由用户点击触发，** 不能在助手调用的工具里使用。
12. **使用 bun**（`bun install`、`bun test`、`bunx`），不要使用 npm、npx、yarn 或 pnpm。

## 6. 名称和格式

下面这些名称和格式必须写对。

| 对象 | 形式 | 示例 |
| --- | --- | --- |
| 工具 id（用于代码、小组件、定时检查和 `invoke`） | `<plugin>.<tool>` | `wallet.cardBalance` |
| 模型看到的工具名（写在 `instructions` 里） | `<plugin>__<tool>` | `wallet__cardBalance` |
| 远程插件在 App 中的 id | `mcp-<server name>` | `mcp-demo-canteen` |
| 插件文档的安装链接 | GitHub 文件夹 URL，或 `pkuharness://plugin?src=<url-encoded link>` | `https://github.com/pkuinfo/pku-harness-plugins/tree/main/plugins/classrooms` |
| 页面路由 | `/p/<plugin>/<screen>`，弹窗为 `/m/<plugin>/<screen>` | `/p/focus/main` |
| 模型写出的时间 | 本地时间 `"YYYY-MM-DD HH:mm"` | `"2026-10-30 08:00"` |

## 7. 报告完成之前

- [ ] 选定了插件类型（插件文档、远程插件或内置插件），并说明了理由。
- [ ] 每个工具都有标题、描述、有取值范围的输入和如实的效果，结果只含数据。
- [ ] 插件文档：`bun run plugin validate` 和 `test` 都通过；声明与步骤实际做的事一致。
- [ ] 代码插件：`requires` 和 `scopes` 完整；`defaultModes` 对 `money` 和 `public` 设为先询问用户。
- [ ] 结果和日志里没有凭据、机密信息或链接。
- [ ] 上面的测试和检查都通过了，或者你准确说明了哪些没能运行，以及原因。
- [ ] 添加了注册表记录或清单。如果插件用到云服务，复制了 `cloud` 声明。
- [ ] 给用户写了总结：插件做什么、改了哪些文件、怎么试用，以及还有哪些事需要人来做（例如真机测试、用真实校园账号测试、为内置插件开 issue）。

## 把文档当作上下文

| URL | 用途 |
| --- | --- |
| `/llms.txt` | 所有页面的索引，每页一句简介，用来挑选要加载的页面 |
| `/llms-full.zh.txt` | 所有中文页面合成的一个文件（很大） |
| `/llms-full.txt` | 所有英文页面合成的一个文件（很大） |
| `/docs/<page>.md` | 单个页面的 Markdown |
| `/docs/cloud/api/<tag>.md` | 以纯文本列出的 Cloud API 接口和数据结构 |


# 简介 (/docs)

> PKU harness 是一个开源的北大校园生活 App，核心是一个 AI 助手。这份文档写给为它开发插件的同学和 AI 助手。

PKU harness 是一个帮北大同学处理校园事务的 Android 应用。你用校园账号登录一次，就能在 App 里使用课表、校园卡、网费、树洞、教学网、财务、场地预约等校园系统。登录走的是学校的统一身份认证系统 IAAA。插件还可以接入更多服务。

App 的核心是一个 AI 助手。你在对话里提出需求，助手会替你操作这些系统。助手能用的每一项功能，在 App 的原生界面里也有对应的按钮，你可以自己点。

## App 与插件的关系

App 本身只提供三样基础设施：一个 Agent 循环（让 AI 助手反复思考、调用工具、再回答的那段程序），一套界面设计系统，以及一组宿主服务（例如校园登录、定时任务、小组件和待办）。我们把这一层叫作 harness（框架）。

除此之外的功能都由**插件**（plugin）提供。每个校园服务、看板、提醒，甚至 AI 模型的服务商，都是一个插件。随 App 一起发布的插件和同学自己在服务器上运行的插件遵循同一套接口，显示在同一个插件列表里，也受同一套权限系统管理。

<LayerDiagram
  title="PKU harness App（框架层）"
  parts={[
    { name: 'Agent 循环', note: '调用工具' },
    { name: '设计系统（HostUI）', note: '显示页面' },
    { name: '宿主服务', note: '校园登录、定时任务、小组件、待办等' },
  ]}
  below={[
    { name: '内置插件', note: 'TypeScript、SDK' },
    { name: '远程插件', note: '基于 HTTPS 的 MCP' },
    { name: 'PKU harness Cloud', note: '可选的后端' },
  ]}
/>

这种结构带来两条规则，后面的文档会经常提到。

- **你和助手能做的事情完全相同。** 每项功能都是一个有类型的工具（tool）。你在界面上点按钮时，界面调用这个工具；你在对话里提出需求时，助手调用同一个工具。
- **凭据不离开手机。** 校园服务由框架自己登录。插件只拿到服务返回的结果，看不到你的密码和会话令牌。

## 这份文档写给谁

<Cards>
  <Card title="学生开发者" href="/docs/build">
    把 App 还没覆盖的校园服务接进来。你可以写一份插件文档，用任意语言搭一个远程 MCP 服务器，或者写一个内置的 TypeScript 插件。
  </Card>
  <Card title="AI 助手" href="/docs/for-agents">
    正在写插件的 Claude Code、Codex 或 App 内置助手。请先看检查清单，再按需阅读其中链接的页面。
  </Card>
  <Card title="普通用户" href="/docs/manual">
    使用手册：安装 App、完成首次设置，以及各个标签页和设置项的用法。
  </Card>
  <Card title="服务器运维" href="/docs/cloud">
    运行一个 PKU harness Cloud 服务。它是一个可选的后端，为插件提供端到端加密的存储和同步。
  </Card>
</Cards>

## 接下来读什么

| 你想要 | 阅读 |
| --- | --- |
| 了解 App 的整体结构 | 先读[架构](/docs/concepts/architecture)，再读[核心概念](/docs/concepts/plugins)里的其他页面 |
| 不改动 App，今天就发布一个插件 | [快速上手：远程插件](/docs/build/remote-plugin) |
| 写一个随 App 发布的插件 | [内置插件](/docs/build/bundled-plugin)和 [SDK 参考](/docs/sdk) |
| 把插件上架到插件市场 | [插件市场](/docs/marketplace) |
| 在服务器上存数据或实时共享 | [PKU harness Cloud](/docs/cloud) 及其 [API 参考](/docs/cloud/api/meta) |
| 查看所有仓库和路线图 | [生态](/docs/ecosystem/repositories) |

## 把文档交给 AI 助手

每个页面都有 Markdown 版本。这样你可以只把需要的内容交给 AI 助手，不必让它读整个网站。文档有简体中文和英文两种语言。中文是默认语言，路径以 `/docs` 开头；英文路径以 `/en/docs` 开头。

| URL | 内容 |
| --- | --- |
| [`/llms.txt`](/llms.txt) | 两种语言所有页面的索引，每页附一句简介 |
| [`/llms-full.txt`](/llms-full.txt) | 所有英文页面合成的一个文件 |
| [`/llms-full.zh.txt`](/llms-full.zh.txt) | 所有中文页面合成的一个文件 |
| `/docs/<page>.md` | 单个中文页面，例如 [`/docs/sdk/plugin.md`](/docs/sdk/plugin.md) |
| `/en/docs/<page>.md` | 同一页面的英文版 |
| `/docs/<page>`，请求头带 `Accept: text/markdown` | 与 `.md` 相同 |

最后一行利用的是 HTTP 的内容协商：服务器根据请求头决定返回 HTML 还是 Markdown。

每页标题下方有 **Copy Markdown** 和 **Open in…** 两个按钮。Cloud API 参考页的 Markdown 版本会把接口和数据结构以纯文本列出。

```bash
# 把插件检查清单和 SDK 约定交给 Claude Code
curl -s https://<this-site>/docs/for-agents.md https://<this-site>/docs/sdk/plugin.md > plugin-context.md
```

<Callout title="当前状态">
  PKU harness 1.0.0 已发布 Android 版，iOS 版正在准备中。

  JavaScript 代码的修复通过签名的空中更新（over-the-air update，简称 OTA）推送到已安装的 App。原生代码的改动则需要发布新的 APK。

  这里描述的 SDK 和通信协议与 [`pkuinfo/pku-harness`](https://github.com/pkuinfo/pku-harness) 和 [`pkuinfo/pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 两个仓库的默认分支一致。插件和 SDK 直接从 GitHub 仓库获取，不通过 npm 发布。大多数校园服务以[插件文档](/docs/build/declarative-plugins)（`PLUGIN.md`）的形式提供，通过链接安装。
</Callout>


# AI 服务 (/docs/manual/ai-model)

> 先设置好 AI 模型：在中国大陆选择哪家服务商（DeepSeek、阿里云百炼、百度千帆），怎样一步一步申请 API Key、在哪里填写，以及账户余额、上下文预算和费用。

PKU harness 的助手需要一个大模型来理解你的话并替你操作。App 不附带模型，我们也不运营模型服务。你需要在模型服务商那里开一个账户，创建一个 **API Key**，再把它填进 App。API Key 是一串很长的字符，通常以 `sk-` 开头，作用相当于服务商那边的密码。

密钥保存在手机的安全存储中，只会发送给你选择的服务商。你的对话内容从手机直接发给这家服务商。服务商按用量收费：你先给账户充值，每次回复花掉一小笔钱。

## 推荐的服务商

任何提供 OpenAI 兼容接口的服务都可以使用。对中国大陆的同学来说，下面三家付款方便，不需要代理也能访问。

| 服务商 | 在 App 中怎样接入 | 接口地址（Base URL） | 模型示例 |
| --- | --- | --- | --- |
| **DeepSeek** | 「DeepSeek」（内置，默认） | `https://api.deepseek.com`，固定 | DeepSeek-V4.1-Flash、DeepSeek-V4-Pro |
| **阿里云百炼**（千问模型） | 「OpenAI 兼容」 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3.7-plus`、`qwen3.8-flash` |
| **百度千帆**（文心模型） | 「OpenAI 兼容」 | `https://qianfan.baidubce.com/v2` | `ernie-5.1`、`ernie-4.5-turbo-128k` |

模型名称经常更新，请以服务商的模型列表为准：[百炼模型列表](https://help.aliyun.com/zh/model-studio/models)、[千帆模型列表](https://cloud.baidu.com/doc/qianfan/s/rmh4stp0j)。

### 怎样选择

**DeepSeek** 最简单，也是我们首先推荐的。App 认识它的模型，所以：

- 不需要填写接口地址和模型名称。
- App 知道每个模型的上下文长度（100 万 token），也知道它能不能看图片。DeepSeek-V4.1-Flash 支持图片，可以发送照片，Copilot 也能使用截图；DeepSeek-V4-Pro 不支持。
- 「设置 → 用量」按 DeepSeek 公开的价格估算花费，「设置 → AI 服务」可以显示账户余额。

**阿里云百炼**和**百度千帆**通过「OpenAI 兼容」接入。如果你已经有这两家的账户，或者更喜欢它们的模型，可以选择它们。百炼还有一个好处：同一个账户也能申请[语音输入](/docs/manual/voice-input)用的 Key。用这种方式接入的模型，App 了解得少一些：

- App 按 128k token 估计上下文长度，并据此压缩对话。
- App 不为这些模型提供图片附件，所以不能发送照片，Copilot 也不能用截图。
- 「设置 → 用量」会统计它们的 token，但无法估算花费，App 也不能显示余额。这两项请在服务商的控制台查看。

## 申请 DeepSeek API Key

<Steps>

<Step>

### 注册账户

用浏览器打开 [platform.deepseek.com](https://platform.deepseek.com)，例如用手机号注册。充值前，平台可能要求你完成实名认证。

</Step>

<Step>

### 充值

打开「充值」页面，用微信或支付宝充一小笔钱，例如 10 元。余额为零时，调用会失败，并提示「账户余额不足」。

</Step>

<Step>

### 创建 Key

点左侧菜单的「API keys」，再点「创建 API key」。起一个容易认出的名字，例如 `PKU harness`，然后创建。立刻复制这个 Key：完整的 Key 只显示一次。

</Step>

<Step>

### 填进 App

打开「设置 → AI 服务」，点「DeepSeek」，把 Key 粘贴到「API Key」，点「保存并测试连接」。详见[在 App 中填写](#enter-the-key-in-the-app)。

</Step>

</Steps>

## 申请阿里云百炼 API Key

<Steps>

<Step>

### 注册账户

在 [aliyun.com](https://www.aliyun.com) 注册阿里云账号。使用付费服务前，阿里云通常要求完成实名认证，按控制台的提示操作即可。

</Step>

<Step>

### 打开北京地域的百炼

打开[百炼控制台](https://bailian.console.aliyun.com)。如果提示开通服务，同意开通。确认右上角的地域是「华北2（北京）」。Key 只能在创建它的地域使用。

</Step>

<Step>

### 创建 Key

打开 [API Key 页面](https://bailian.console.aliyun.com/cn-beijing/model/settings/api-key)，点「创建 API Key」，保持默认设置并确定。立刻复制这个 Key：完整的 Key 只显示一次。

</Step>

<Step>

### 填进 App

打开「设置 → AI 服务」，点「OpenAI 兼容」。把「Base URL」设为 `https://dashscope.aliyuncs.com/compatible-mode/v1`，把 Key 粘贴到「API Key」，在「模型 ID」里填写模型名称，例如 `qwen3.7-plus`。点「保存并测试连接」。

</Step>

</Steps>

百炼的每次调用都计入你的阿里云账户。新账户有时会获得部分模型的免费额度，具体以控制台显示为准。

上面的接口地址是百炼 [API Key 文档](https://help.aliyun.com/zh/model-studio/get-api-key)中北京地域的地址。百炼的 [OpenAI 兼容说明](https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope)还列出了一个业务空间地址 `https://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`，并建议使用它以获得更好的稳定性。两个地址都可以使用。

## 申请百度千帆 API Key

<Steps>

<Step>

### 注册账户

在 [cloud.baidu.com](https://cloud.baidu.com) 注册百度智能云账号。如果控制台要求实名认证，请先完成。

</Step>

<Step>

### 创建 Key

在控制台打开[「安全认证 → API Key」](https://console.bce.baidu.com/iam/#/iam/apikey/list)，点「创建 API Key」。Key 的样子类似 `bce-v3/ALTAK-…/…`，复制时要包括开头的 `bce-v3/`。

</Step>

<Step>

### 填进 App

打开「设置 → AI 服务」，点「OpenAI 兼容」。把「Base URL」设为 `https://qianfan.baidubce.com/v2`，把 Key 粘贴到「API Key」，在「模型 ID」里填写模型名称，例如 `ernie-5.1`。点「保存并测试连接」。

</Step>

</Steps>

接口地址和 Key 的格式来自千帆的[快速开始](https://cloud.baidu.com/doc/qianfan-docs/s/qm8qxemze)。调用费用计入你的百度智能云账户。

## 在 App 中填写

可以在[首次设置](/docs/manual/first-run#step-1-connect-an-ai-provider)中连接，也可以之后在设置里修改。设置页的选项最完整。

1. 打开「设置 → AI 服务」。
2. 点一个服务商：「DeepSeek」或「OpenAI 兼容」。
3. 在「模型」下点选一个模型，或在「模型 ID」里填写模型名称。「OpenAI 兼容」需要手动填写；测试成功后，App 也会列出服务商返回的模型。
4. 选择「OpenAI 兼容」时，填写「Base URL」。DeepSeek 的地址是固定的，页面上显示为「接口地址：https://api.deepseek.com」。
5. 在「API Key」里粘贴密钥。已保存的密钥会标注「已保存在本机安全存储」。
6. 点「保存并测试连接」。App 会发送一条很短的测试消息，成功后显示「连接成功：」和模型的回复。只想保存、不测试，点「仅保存」。

测试失败时，提示会说明原因，见[常见问题 → AI 服务](/docs/manual/troubleshooting#ai-provider)。

助手不能读取或填写 API Key。如果你在对话里让它改 Key，它会打开这个页面，由你自己填写。

## 账户余额

选择 DeepSeek 并保存 Key 后，「AI 服务」页面会出现「账户余额」，显示余额以及其中赠送和充值的部分（「赠送 … · 充值 …」）。点按可以刷新。如果服务商提示余额不足以发起请求，页面会说明；到服务商网站充值后即可继续使用。

其他服务商的余额请在它们的控制台查看。

## 切换模型

在对话页点输入框下方的模型标签，或输入 `/model`，可以选择其他模型。新模型从下一条消息起用于这个对话，也会成为新对话的默认模型。详见[对话 → 模型和上下文](/docs/manual/chat#model-and-context)。

也可以直接告诉助手，例如「切换到 DeepSeek-V4-Pro」。它会修改设置，并告诉你改了什么，见[设置 → 在对话中修改设置](/docs/manual/settings#changing-settings-in-chat)。

## 上下文预算

模型看到的对话内容叫作「上下文」。「设置 → AI 服务」底部的「上下文预算」限制 App 每次发送多少上下文，可选「32k」「64k」「128k」「256k」和「模型上限」，默认是「模型上限」。

选择「模型上限」时，App 使用模型的完整上下文，对话用到 90% 时把较早的内容压缩成摘要。DeepSeek 的上下文是 100 万 token，也就是大约 90 万时压缩。预算越小，回复越快、越省钱，但助手直接看到的对话也越少。长任务进行到一半时也会压缩，任务会接着做下去。

## 用量和费用

服务商按 token（文本片段）数量收费，发送和接收的内容都计入。对话越长、附件越多、Copilot 任务越长，用的 token 就越多。

「设置 → 用量」显示 token 用量、活跃时段与常用工具，可以选择「7 天」「30 天」或「全部」。对于公布了价格的模型（例如 DeepSeek），页面会估算花费。估算仅供参考，以服务商的账单为准。详见[设置与数据 → 用量](/docs/manual/settings#usage)。


# 校园账号与手机令牌 (/docs/manual/campus-account)

> 登录和退出北大校园账号，填写登录时的验证码，把 App 绑定为手机令牌，以及只能在校园网内使用的服务。

App 用你的北大校园账号（IAAA 统一身份认证）登录各个校园服务。本页说明登录、验证码、手机令牌和退出登录。

## 登录

你可以在[首次设置](/docs/manual/first-run#step-2-sign-in-to-pku)中登录，也可以之后在设置里登录。

1. 打开「设置 → 校园账号」。
2. 在「学号 / 职工号」和「密码」里填写登录门户用的账号和密码。
3. 点「登录」。
4. 如果学校要求验证码，按下一节的说明填写。

登录成功后，「设置」页的「校园账号」一行显示你的姓名、学号和「已登录」。

## 密码保存在哪里

学号和密码保存在手机的系统安全存储中，只会发给学校的登录服务。它们不会发送到本项目运行的任何服务器，也不会交给任何插件。

App 先登录 IAAA，再在需要时登录各个服务，例如校园卡、树洞、教学网和图书馆。插件只能使用这些服务的登录状态，拿不到你的密码。

## 登录时的验证码

IAAA 通常只需要密码，但有时会要求额外验证。App 在后台刷新登录状态时也可能遇到这种情况。这时 App 会弹出一个输入框，标题是下面三种之一。

| 标题 | 怎样填写 |
| --- | --- |
| 需要短信验证码 | 填写发到账号绑定手机的验证码。短信到达后，点系统弹窗里的「允许」，验证码会自动填好。App 只能读取这一条短信 |
| 需要邮件验证码 | 填写发到你邮箱的验证码 |
| 需要手机令牌验证码 | 填写手机令牌 App 当前显示的 6 位数字。如果已把本 App 绑定为手机令牌，会自动填写 |

填写后点「验证」。没有收到短信时，等倒计时结束后点「重新发送验证码」。

有些服务在 IAAA 之外还有自己的验证。例如树洞会不定期要求短信验证，查看课表和成绩需要手机令牌或短信验证码。这些验证在对应插件的页面上完成，也可以在对话里把验证码告诉助手。

## 测试连接

在「设置 → 校园账号」里点「测试连接」。连接正常时，页面显示「连接正常，校园卡余额 ¥…」。

## 手机令牌

「手机令牌」插件可以把本 App 绑定为 IAAA 的手机令牌（一种每 30 秒变化一次的 6 位动态验证码）。绑定后：

- App 自己登录学校系统时，需要的手机令牌验证码会自动填写。
- 在别的设备上登录时，打开 App 的「手机令牌」页面，就能看到当前的验证码。
- 看板上可以放一个「手机令牌」组件。它平时背面朝上，验证码是隐藏的。轻点后卡片翻过来，显示当前验证码，再点验证码即可复制。一分钟后，或者你离开 App 时，卡片会重新翻回背面。

<Callout type="warn" title="绑定会替换原来的手机令牌">
  绑定时，IAAA 会生成新的令牌密钥并交给本 App。之前在其他 App（如 FreeOTP、Google Authenticator 或学校推荐的令牌 App）中绑定的手机令牌将不再有效。之后凡是要求手机令牌的登录，包括网页登录 iaaa.pku.edu.cn，都要使用本 App 显示的验证码。
</Callout>

绑定步骤如下。需要先登录校园账号。

1. 打开「设置 → 插件 → 手机令牌」，在「打开」一栏中点「手机令牌」。
2. 阅读「绑定前请了解」中的说明，勾选「我已了解，之前绑定的手机令牌会失效」。
3. 点「发送绑定验证码」。App 会用你保存的账号向 IAAA 验证身份，并给账号绑定的手机发送短信。
4. 在「短信验证码」里填写 6 位数字，点「完成绑定」。

绑定成功后，这个页面显示当前验证码和刷新倒计时。点按验证码即可复制。

令牌密钥只保存在本机的系统安全存储中，不会上传，也不会交给 AI。卸载 App、清除数据或换手机都会丢失密钥，届时可以用短信重新绑定。

要在本机删除令牌，点「从本机移除」。学校那边的绑定不会解除，之后要求手机令牌的登录需要另一个令牌，或在这里重新绑定。

## 需要校园网的服务

有些服务只能在北大校园网内访问，例如「财务」插件使用的财务门户（cwfw.pku.edu.cn）。这类插件在插件列表中显示「仅限校园网」。

使用这类服务时，请连接校园网（PKU 或 PKU Secure）。App 访问校园服务时直接连接，不使用系统代理。

## 退出登录

1. 打开「设置 → 校园账号」。
2. 点「退出登录」，在确认对话框中再点「退出登录」。

App 会删除本机保存的密码和所有校园服务的登录状态。重新登录之前，需要校园账号的插件都无法使用。

要删除 App 的全部数据，见[设置与数据 → 清除所有数据](/docs/manual/settings#erase-all-data)。


# 校园卡与付款码共享 (/docs/manual/campus-card)

> 「校园钱包」插件里的校园卡余额、付款码、充值、网费和浴卡，以及用「付款码共享」把付款码临时借给朋友。

「校园钱包」插件提供校园卡、网费、浴卡和宿舍电费的相关功能。「付款码共享」插件可以把你的校园卡付款码临时分享给朋友。两个插件都需要先登录校园账号。

## 打开校园钱包

以下任一方式都可以：

- 打开「设置 → 插件 → 校园钱包」，在「打开」一栏中点「校园钱包」或「校园卡付款码」。
- 把「校园卡余额」组件放到看板上，点组件上的「充值」或「付款码」。
- 在对话里问助手，例如「校园卡还剩多少钱？」，或输入 `/balance`。

「校园钱包」页面显示：

- **校园卡**：余额、今日消费和日限额。卡片已挂失或冻结时会标明。
- **网费**：网络账号余额和本月用量。点「缴网费」会打开学校的收费平台，用微信或支付宝缴费。
- **浴卡**：最近几次线上充值的记录。浴卡余额存在卡片芯片里，线上查不到。
- **宿舍电费**：查看和缴费的方法。宿舍电费目前只能在微信公众号「动力中心收费服务号」里缴纳，App 查不到电量，也不能代缴。

## 付款码

付款码用于在食堂和超市扫码付款。

1. 打开「校园卡付款码」页面，或点「校园卡余额」组件上的「付款码」。
2. 把付款码出示给收银员。

付款码每 30 秒自动刷新。页面打开时，屏幕会调到最亮，并禁止截屏。

付款码只能在「数字卡」用卡方式下使用。如果你当前用的是其他方式，页面会显示「需要切换到「数字卡」」，点「切换到数字卡」即可。切换后，实体卡或手机 NFC 刷卡可能无法使用。要改回来，点付款码页面上的「用卡方式」，选择其他方式。

付款码只在你打开的页面上显示，不会交给助手。助手不能替你出示付款码。

## 充值

1. 在「校园钱包」页面或「校园卡余额」组件上点「充值」。
2. 选择一个金额，或在「其他金额（元）」里填写 1–1000 的整数。
3. App 会在学校的收银台创建充值订单，并在浏览器中打开。在收银台里选择微信或支付宝付款。
4. 付款后，在食堂的 POS 机上刷一次卡，余额才会更新。

本 App 不经手钱款，所有付款都在微信或支付宝里由你完成。你也可以让助手充值，它会创建订单并打开收银台，付款仍由你完成。充值属于「资金」类操作，可以在插件权限中设置为「每次询问」，见[插件与权限](/docs/manual/plugins#permissions)。

浴卡充值的金额为 10–100 元，在学校收费平台的「我的订单」里付款。付款后，要拿浴卡到浴卡转存机上贴卡，钱才会写进卡里。

## 付款码共享

「付款码共享」把你的付款码临时借给朋友使用：朋友扫码付款，钱从你的校园卡扣。付款码在你的手机上生成，加密后经云服务转发给朋友，服务器无法解密。服务器能看到分享的开始和结束时间，以及查看者的 IP 地址。

请遵守《北京大学一卡通管理办法》及相关规定，只分享给你信任的人。

### 开始之前

1. 登录校园账号。
2. 在「设置 → 云服务」中选择一个服务器，见[设置与数据 → 云服务](/docs/manual/settings#cloud)。
3. 允许「付款码共享」使用云服务。第一次使用时 App 会弹出「「付款码共享」想使用云服务」，点「允许」。也可以在「设置 → 插件 → 付款码共享」的「云端」一栏中打开「允许使用云服务」。
4. 把用卡方式切换为「数字卡」。

### 创建分享

1. 在付款码页面点「分享给朋友」，或输入 `/share`。
2. 阅读「分享前请知悉」。
3. 选择「有效期」：「10 分钟」「30 分钟」「2 小时」或「今天」。
4. 选择「消费上限」：¥20、¥50、¥100、¥200 或「未设上限」。
5. 可选：在「查看者验证」里设置「姓名验证」（点按姓名中的字把它藏起来，对方要补全这些字）或「口令」（4–8 位数字）。口令请当面或另行告诉对方，不要和链接一起发送。
6. 点「生成分享链接」。
7. 点「发送给朋友」把链接发出去，或让对方扫描页面上的二维码。

朋友用浏览器打开链接即可，不需要安装 App。链接只能被第一个打开的人使用。验证输错 5 次，分享会自动关闭。

### 分享期间

分享期间请保持手机联网。手机上会一直显示一条「正在共享付款码」的通知。在「设置 → 插件 → 付款码共享 → 付款码共享」页面可以看到对方是否在查看、已出示几次付款码和已消费金额，并可以：

- 「停止分享」：立即结束。
- 「延长 30 分钟」。
- 「重置查看者」：下一个打开这个链接的人可以查看。
- 「再次发送链接」。

到期、达到消费上限或验证失败次数过多时，分享会自动结束。消费上限在每笔消费后核对，最后一笔可能略超上限。分享期间你自己的消费也计入上限，校园卡自己的日限额照常生效。


# 对话 (/docs/manual/chat)

> 在「对话」页和助手交谈：打字或用语音输入消息，附上照片和文档，使用 / 命令，管理对话列表，确认助手的操作，编辑和复制消息，停止回复。

「对话」页是你和助手交谈的地方。助手会调用已开启插件的工具来查询信息或替你操作，也可以在对话里显示表单、选择器和数据卡片。本页说明这个页面上的各项操作。

使用对话页之前，需要先连接一个 AI 服务。没有连接时，页面会显示「连接 AI 服务」按钮，点按后进入「设置 → AI 服务」。

## 发送消息

1. 在底部的输入框里输入内容。内容较长时，点输入框右上角的展开按钮可以打开全屏编辑器。想用说的，点麦克风，见[语音输入](/docs/manual/voice-input)。
2. 点发送按钮。

你用什么语言提问，助手就用什么语言回答。

新对话的空白页上列出了几个示例问题，例如「今天有什么课？」。点按一个就会直接发送。

助手回复时，会显示它正在做什么，例如「思考中」或「正在调用」某个工具。回复结束后：

- 如果模型输出了思考过程，回复上方会出现「思考了 N 秒」，点按可以展开或收起。
- 如果助手用了工具，会显示「用了 N 个工具」和工具名称。回答正文出现后，这部分会自动折叠，点按可以重新展开。
- 回复下方有复制按钮。最后一条回复还有重新生成按钮。点左侧的小图标可以显示本次回复的统计：模型、用时和 token 数。

如果你在回复进行中切到别的 App，回复完成后 App 会发一条「回复好了」的通知。

## 停止回复和排队发送

助手回复时，发送按钮的位置会出现停止按钮。点按它会停止当前回复，回复下方显示「已停止」。

回复进行中，你仍然可以输入下一条消息并点「排队发送」。排队的消息会在当前回复结束后依次发送。如果当前回复被停止或出错，排队的消息会暂停，输入框上方显示「回复中断，排队的消息已暂停」，点「继续发送」即可恢复。点按一条排队的消息可以把它放回输入框。

单次回复的步骤数没有上限。助手会一直做到任务完成或你按停止。在长任务中（例如用 Copilot 点单），上下文快满时较早的步骤会被压缩成摘要，然后任务继续。

## 附件

点输入框左下角的「+」，打开「添加到消息」面板。

| 选项 | 说明 |
| --- | --- |
| 拍照 | 用相机拍一张照片 |
| 相册 | 从相册选择图片 |
| 文件 | PDF、Word、Excel、PowerPoint、音频和文本文件 |
| 输入命令 | 在输入框中输入 `/`，打开命令菜单 |

每条消息最多带 8 个附件。文本文件最大 200 KB，文档最大 30 MB，音频最大 50 MB。只有支持图片的模型才能接收图片。当前模型不支持图片时，面板会提示，并在有可用模型时提供「切换」按钮。例如 DeepSeek-V4.1-Flash 支持图片，DeepSeek-V4-Pro 不支持。

### 文档和音频

PDF、Word、Excel 和 PowerPoint 文件会在你的手机上读成文字。文件本身不会上传，助手拿到的是文字。长文档只有开头部分随消息发送，助手需要时会翻到后面或在文档里搜索。引用数字、日期和金额时，它会照原文写。点按附件可以预览助手看到的文字。

扫描版 PDF 里只有页面的图片，没有可以读取的文字。如果你在「设置 → AI 服务」中保存了 DeepSeek API Key，App 会把这类 PDF 发送给 DeepSeek OCR 识别，再附上识别出的文字。费用从你的 DeepSeek 账户扣除，每 1,000 页 $0.225；文件最大 100 MiB、1,000 页。没有 DeepSeek Key 时，App 会提示你填写一个，或者改为拍下页面。

另外有些文件读不出来，App 会说明原因：有密码保护的文件，以及损坏的文件。

音频文件由你的[语音输入](/docs/manual/voice-input#transcribe-an-audio-file)服务转成文字，助手读取转写结果。「阿里云百炼（实时）」只能处理实时语音，转写音频文件请选择硅基流动。

文档里的文字被当作数据。如果文件里写着要助手做什么，助手不会照做。

### 很长的粘贴文本

粘贴很长的文本时，输入框下方会提示内容太长，点「转为附件」可以把它作为附件发送。

## 命令

在输入框开头输入 `/`，会弹出命令菜单。继续输入可以筛选，点按一项即可执行。命令也可以用中文别名，例如 `/新对话`。

| 命令 | 作用 |
| --- | --- |
| `/new` | 开始新对话 |
| `/sessions` | 查看全部对话 |
| `/rename 新标题` | 重命名当前对话 |
| `/retry` | 重新生成上一条回复 |
| `/copy` | 复制上一条回复 |
| `/export` | 把对话导出为 Markdown 分享 |
| `/compact` | 压缩较早的对话，腾出上下文 |
| `/context` | 查看上下文占用 |
| `/model` | 切换模型 |
| `/memory` | 查看 AI 记住了什么 |
| `/usage` | 查看 token 用量 |
| `/tasks` | 查看定时任务和提醒 |
| `/plugins` | 管理插件 |
| `/help` | 列出所有命令 |

插件也会添加自己的命令，例如 `/balance`（查校园卡余额）、`/canteen`（现在去哪个食堂）、`/homework`（查看教学网上还没交的作业）和 `/share`（分享付款码给朋友）。输入 `/help` 可以看到当前可用的全部命令。

## 模型和上下文

输入框下方的模型标签显示当前使用的模型。点按它可以选择其他模型。新选择的模型从下一条消息起用于这个对话，也会成为新对话的默认模型。

模型支持时，选择面板顶部还有「思考强度」：「自动」（默认）在规划任务时认真思考，在用 Copilot 操作手机时每一步快速思考；也可以固定为「低」「高」或「最高」。助手用你消息的语言回复：用中文问就用中文答，即使 App 界面是英文。

模型标签旁边的圆环显示当前对话占用了多少上下文预算。点按它可以看到各部分的占用和压缩次数。对话超过预算时，较早的内容会被自动压缩成摘要，长任务进行到一半时也会这样做。对话里会显示「已压缩 N 条消息」，点按可以查看摘要。预算在「设置 → AI 服务 → 上下文预算」里设置，默认使用模型的完整上下文，见 [AI 服务 → 上下文预算](/docs/manual/ai-model#context-budget)。

## 编辑和复制消息

- **编辑你发出的消息**：长按这条消息，点「编辑」。内容会回到输入框，上方显示「编辑消息 · 发送后将替换这条及之后的内容」。修改后发送，这条消息之后的对话会被替换。点输入框上方的关闭按钮可以取消编辑。
- **复制你发出的消息**：长按这条消息，点「复制」。
- **复制助手的回复**：点回复下方的复制按钮，或输入 `/copy` 复制最后一条回复。

## 对话列表

点对话页左上角的菜单按钮，打开对话列表。对话按「置顶」「今天」「昨天」「7 天内」「更早」分组，顶部可以搜索。

- 点按一个对话即可打开。
- 长按一个对话，可以「重命名」「置顶」或删除。
- 向左滑动一个对话可以删除。删除后 5 秒内可以点「撤销」恢复。

新对话的标题由 App 根据内容自动生成。点对话页顶部的标题可以直接修改。对话页右上角的「+」用于开始新对话。

## 助手能做什么

助手能做的事情取决于你开启了哪些插件。例如：

- 查询校园卡余额、网费、成绩、空闲教室、食堂人流和校园通知。
- 从学校同步课表，创建待办、提醒和定时检查。
- 把数字放到看板上。
- 阅读和搜索你附上的文档。
- 用你的 DeepSeek API Key 搜索网页、阅读网页内容，见下面的[联网搜索](#web-search)。
- 修改 App 的设置，例如主题、语言、时区、模型，以及插件的开关和权限，见[设置 → 在对话中修改设置](/docs/manual/settings#changing-settings-in-chat)。
- 设置好 [Copilot](/docs/manual/copilot) 后，操作手机上的其他 App。
- 在对话里显示表单或选择器，让你填写或选择后点「提交」。

有些操作只能由你本人在 App 界面上完成，助手不能代劳。例如出示校园卡付款码，在教学网交作业时选择文件并提交，以及填写密码和 API Key。

插件的完整列表见「设置 → 插件」，详见[插件与权限](/docs/manual/plugins)。

### 联网搜索

在「设置 → AI 服务」中保存了 DeepSeek API Key 后，助手可以上网查资料。用哪个对话模型都可以：需要搜索时，助手会自动加载 DeepSeek 插件。这个插件有两个工具：

- 「搜索网页」（`deepseek__web_search`）使用 DeepSeek 搜索，最多返回 20 条结果，每条有标题、链接、网站、日期和摘要。
- 「读取网页」（`deepseek__web_read`）把网页读成文字，每次 12,000 个字符。

搜索和读取网页各按每 1,000 次 $0.75 从你的 DeepSeek 账户扣费。搜索结果和网页内容来自第三方，助手只把它们当作数据，不会照其中的指示去做。校园相关的信息，助手仍然通过校园插件查询。

## 确认助手的操作

每个插件的每一类操作都有一个权限设置：「直接执行」「每次询问」或「禁止」。设置为「每次询问」的操作，助手执行前会弹出确认面板，标题是「AI 请求执行」，并说明来自哪个插件。

- 点「允许」执行这一次。
- 点「拒绝」不执行，助手会收到被拒绝的结果。
- 点「允许，以后同类操作不再询问」会执行，并把这个插件这一类操作改为「直接执行」。Copilot 操作手机应用时的确认面板没有这个选项。

权限的设置方法见[插件与权限](/docs/manual/plugins#permissions)。


# Copilot 手机助手 (/docs/manual/copilot)

> Copilot 让助手在一块独立的屏幕上替你操作手机里的其他 App。本页面向不熟悉手机设置的同学，一步一步说明开发者选项、无线调试和配对码、无障碍、允许的 App 和截图怎样设置，列出各品牌手机的注意事项，并说明怎样暂停、停止以及彻底关闭。

「Copilot 手机助手」让助手替你使用手机上的其他 App。例如你可以说「用 Copilot 设一个 7:30 的闹钟」或「帮我点一杯常喝的咖啡」。助手会在一块看不见的独立屏幕上打开这个 App，在那里点按和输入，你可以照常使用手机。一个小悬浮窗显示每一步，你可以随时暂停或停止。

Copilot 需要 Android 12 或更高版本。它只能使用你允许的 App；要用其他 App 时，会先问你。

## 为什么需要这些权限

Android 平时不允许一个 App 操作另一个 App。Copilot 借助 Android 为开发者和读屏软件提供的功能来做到这一点。每一项都有明确的用途。

| 项目 | 用途 |
| --- | --- |
| **手机助手**（通过无线调试） | PKU harness 在你手机上启动的一个小助手程序。它创建 Copilot 的独立屏幕，在上面打开 App，并完成每一次点按、滑动和输入。它只连接你自己的手机，不连接电脑，也不连接任何服务器 |
| **无障碍** | 让 Copilot 读取被操作 App 的屏幕内容（按钮、文字、列表），并显示悬浮窗。从 1.0.20 版开始，无障碍只用来读取，不再用来点按或输入 |
| **允许的 App** | Copilot 可以打开的 App 列表，最多 20 个 |
| **通知**（可选） | 设置时，在通知里输入配对码；任务进行时，可以在通知里停止任务 |
| **截图**（默认开启） | 用于淘宝、微信等不向无障碍显示内容的 App |

每一项都可以随时在 Android 的设置中撤销，见[关闭 Copilot](#turn-copilot-off)。

## 开始之前

- 连接 **Wi-Fi**。无线调试只能在 Wi-Fi 下使用，校园网（PKU、PKU Secure）也可以。
- 准备好**锁屏密码**。开启开发者选项时，Android 会要求输入。
- 留出大约五分钟。这些设置只需要做一次。
- Copilot 是一个插件。如果你在首次设置时关闭了它，请先在「设置 → 插件」中开启。

## 打开 Copilot 页面

在对话中输入 `/copilot`，或打开「设置 → 插件 → Copilot 手机助手」，在「打开」下点「Copilot」。[首次设置](/docs/manual/first-run#step-6-copilot)中的「设置 Copilot」也会打开这个页面。

在全部就绪之前，页面顶部显示「开始前的准备」：一个有五步的编号列表，每一步标着「待完成」「建议开启」「自动」或已完成的状态。第一个未完成的步骤会自动展开。从上到下依次完成即可。

## 一步一步设置 Copilot

<Steps>

<Step>

### 允许通知

这一步标着「可选」，但它能让配对简单很多。

点「允许通知」，在系统弹窗中点「允许」。如果你之前关闭过通知，按钮会显示「打开通知设置」，在那里为 PKU harness 打开通知后再回来。

</Step>

<Step>

### 开启开发者选项

「开发者选项」是 Android 设置里一个隐藏的页面，给开发 App 的人使用。开启它本身不会改变手机的任何行为，只是让这个页面显示出来。Copilot 需要用到其中的一个开关：「无线调试」。

如果开发者选项还没有开启，「连接手机助手」这一步会显示「打开「关于手机」」按钮。点按后：

1. 在「关于手机」页面找到「版本号」，连续点按七次。有些手机上这一项叫别的名字，例如「OS 版本」或「软件版本号」，见[下面的表格](#where-the-switches-are-on-your-phone)。
2. Android 要求输入锁屏密码，输入即可。
3. 屏幕提示「您已处于开发者模式」或类似的话。
4. 返回设置首页，打开「开发者选项」。大多数手机把它放在「系统」或「更多设置」里。

如果开发者选项已经开启，按钮会显示「开启无线调试」，并直接打开开发者选项中对应的位置。

</Step>

<Step>

### 开启无线调试

1. 在 PKU harness 中点「开启无线调试」。App 会打开 Android 的开发者选项，并在那里等你。
2. 找到「无线调试」，打开它的开关。如果系统问「要允许在此网络上使用无线调试吗？」，点「允许」。勾选「始终允许使用此网络」，以后就不会再问。
3. 点「无线调试」这几个字（不是开关），进入它的页面。
4. 点「使用配对码配对设备」。弹窗里会显示一个六位数的「WLAN 配对码」。保持这个弹窗打开。

无线调试原本用于让电脑连接手机。Copilot 用它在手机自己身上启动手机助手，不涉及电脑；没有配对码，手机以外的设备无法借此连接。

</Step>

<Step>

### 输入配对码

1. 保持配对弹窗打开，下拉通知栏。
2. 在「Copilot 配对」通知（「输入配对码」）中点「输入配对码」。
3. 输入弹窗里的六位数字并发送。

通知会先显示「正在配对并启动手机助手…」，然后显示「手机助手已连接」。不需要输入端口号，也不需要分屏。

如果通知提示配对码错误或弹窗已关闭，再点一次「使用配对码配对设备」，在同一条通知里输入新的配对码。

如果你没有允许通知，或者通知没有出现，回到 PKU harness 点「手动输入配对码」，在「配对码」里填写数字，点「配对手机」。「IP 地址和端口」可以留空，App 会自动查找。

配对只需要做一次。配对过的手机会显示「重新连接」标签页；平时它会自己重新连接，重启手机后也一样。

</Step>

<Step>

### 无障碍

手机助手连接后，这一步会自动完成。这一行先显示「正在开启…」，然后显示「已开启」。手机助手还会替你做三件事：

- 为 PKU harness 允许 Android 13 的「受限制的设置」（见下文）；
- 把 PKU harness 加入电池优化白名单，让 Copilot 能在后台持续运行；
- 允许 PKU harness 自己重新打开它的无障碍服务。

如果这一行仍显示「待完成」，点「一键开启」。例如你之前在系统设置中关闭过这个服务时，就会出现这种情况。

**手动开启。** 如果手机助手连不上，点「改为在系统设置中开启」，再点「打开无障碍设置」，在列表中找到「Copilot」（通常在「已下载的应用」或「已安装的服务」下）并打开。系统可能提示这是「受限制的设置」：从安装包安装的 App 需要你先允许，才能开启无障碍。点「打开应用信息」，点右上角的「⋮」，选择「允许受限制的设置」，用锁屏密码确认，然后回去打开「Copilot」。

</Step>

<Step>

### 选择允许的 App

1. 点「选择应用」。「应用权限」下的「全部应用」列出手机上的 App。可以用「搜索应用」或右侧的 A–Z 字母索引查找；中文名称按拼音首字母排列。
2. 打开你允许 Copilot 使用的每个 App 右侧的开关，最多 20 个。
3. 选择会自动保存。「已允许」标签页列出你选中的 App。

标有「系统界面 · 由其他应用打开」的条目是系统界面，例如其他 App 打开的设置页。只有 Copilot 需要在这些界面里操作时才允许它们。

如果某个允许的 App 已被卸载，它会出现在「已不可用的应用」下。点「移除不可用的应用」即可。

</Step>

<Step>

### 开启 Copilot

点「开启 Copilot」。页面显示「Copilot 已就绪」，点「去对话」开始使用。

之后，页面顶部会显示「启用 Copilot」开关、「权限」一行（没有缺少的权限时显示「必需权限均已就绪」）和「允许 AI 查看截图」开关。

</Step>

</Steps>

## 各品牌手机上的开关位置

每家手机厂商都会改动这些菜单的名称和位置。最快的方法是使用系统设置顶部的搜索框：先搜「版本号」，再搜「无线调试」。下表列出常见的位置，可能因机型和系统版本而不同。

| 品牌（系统） | 连续点按七次以开启开发者选项 | 开发者选项在哪里 |
| --- | --- | --- |
| Google Pixel 及其他多数手机（Android） | 设置 → 关于手机 → 「版本号」 | 设置 → 系统 → 开发者选项 |
| 三星（One UI） | 设置 → 关于手机 → 软件信息 → 「编译编号」 | 设置 → 开发者选项（列表最底部） |
| 小米、Redmi、POCO（澎湃 OS、MIUI） | 设置 → 我的设备 → 全部参数与信息 → 「OS 版本」（HyperOS 版本 / MIUI 版本） | 设置 → 更多设置 → 开发者选项 |
| 华为（HarmonyOS 4 及更早） | 设置 → 关于手机 → 「版本号」 | 设置 → 系统和更新 → 开发者选项 |
| 荣耀（MagicOS） | 设置 → 关于手机 → 「版本号」 | 设置 → 系统和更新 → 开发者选项 |
| OPPO（ColorOS）、一加（ColorOS、OxygenOS） | 设置 → 关于本机 → 版本信息 → 「版本号」 | 设置 → 其他设置 → 开发者选项 |
| vivo、iQOO（OriginOS） | 设置 → 系统管理 → 关于手机 → 「软件版本号」 | 设置 → 系统管理 → 开发者选项 |

Google 的通用说明见[配置设备端开发者选项](https://developer.android.com/studio/debug/dev-options?hl=zh-cn)。

### 各品牌的常见问题

- **小米、Redmi、POCO。** 如果 Copilot 能读取 App 的内容，但点按或输入没有反应，请在开发者选项中打开「USB 调试（安全设置）」。它和「USB 调试」是两个不同的开关。小米要求登录小米账号才能打开它，可能还需要插着 SIM 卡。打开后重启手机。另外请允许 PKU harness「自启动」，并把它的省电策略设为「无限制」，否则系统可能在后台停掉手机助手。
- **OPPO、一加。** 如果设置时无法开启无障碍，或点按没有反应，请在开发者选项中打开「禁止权限监控」，然后重试。
- **三星。** Copilot 可以正常设置。如果键盘每个键要点两次，见[键盘每个键要点两次](#the-keyboard-needs-two-taps-per-key)。如果开启了「自动拦截器」（设置 → 安全和隐私），它可能拦截从安装包安装的 App；设置失败时请先关闭它。
- **华为。** HarmonyOS NEXT（HarmonyOS 5 及以后）的手机不能安装 Android 应用，所以无法运行 PKU harness。较早的 HarmonyOS 可能没有「无线调试」，或报告的 Android 版本低于 12，这时 Copilot 会提示「Copilot 需要 Android 12 或更高版本。」
- **所有品牌。** 省电功能可能停掉手机助手。如果 Copilot 经常断开，请在系统的应用设置中把 PKU harness 的电池使用设为不受限制。

## 截图

有些 App，例如淘宝和微信，不向无障碍显示内容，Copilot 看到的几乎是一个空白屏幕。对这些 App，助手会改为截一张图、看图，再按图上的位置点按。Copilot 页面上的「允许 AI 查看截图」控制这项功能。它**默认开启**，你可以随时关闭。

- 只截取 Copilot 正在操作的 App，也就是独立屏幕上的画面，不会截取你自己的屏幕。
- 不会截取密码、支付等受保护的画面。
- 截图只在这一次回复中发送给你的 AI 服务商，不会保存在对话里。
- 模型需要能看图片。DeepSeek-V4.1-Flash 可以；DeepSeek-V4-Pro 和通过「OpenAI 兼容」接入的模型不行。当前模型看不了图片时，助手会告诉你。

## 使用 Copilot

在对话中描述任务即可，例如「在浏览器里搜索北大图书馆」。不需要每次手动开始任务。助手会在独立屏幕上打开允许的 App，一直做到任务完成或你按停止，步骤数没有上限。

如果任务需要一个你还没有允许的 App，助手会先问你：「「Copilot」想使用」加上这个 App 的名字。可以选「仅本次允许」（只用于这次任务）、「始终允许」（加入允许列表）或「不允许」（助手会停下并告诉你）。只有你的点按才能授权。你不在 PKU harness 里时，请求会以通知或悬浮窗的形式出现。

定时任务不能使用 Copilot。

## 确认、暂停和接管

Copilot 读取屏幕时不会询问。默认情况下，它每次点按、输入或提交之前都会请你确认，因为 Copilot 的「修改」「资金」「公开」权限初始为「每次询问」。如果想让它不经询问直接操作，在「设置 → 插件 → Copilot 手机助手 → AI 可以做什么」中把「修改」改为「直接执行」。

- PKU harness 在前台时，确认请求出现在 App 里。
- 你在其他 App 里时，请求出现在悬浮窗中。点「允许一次」或「拒绝」。

悬浮窗显示当前步骤和实时预览，上面有「暂停」/「继续」和「停止」按钮，「更多选项」菜单里有「接管操作」和「打开 Harness」。

- 点「最小化」可以把悬浮窗缩成一个小圆形图标。红点表示 Copilot 正在操作，橙点表示需要你处理，灰点表示已暂停或由你控制。拖动图标可以移动位置，点按图标重新打开悬浮窗。缩小后，下拉通知栏或打开最近任务都不会让它展开；只有需要你确认或交给你操作时，悬浮窗才会自己展开。在 PKU harness 里不显示悬浮窗，对话里已经能看到任务进度。
- 拖动预览的一角可以调整大小。

**你只需要付款。** 选商品、地址、选项和优惠券，再到点「提交订单」或「立即支付」，都由 Copilot 完成（点之前它会说明金额和商家）。弹出付款界面（选择支付宝或微信支付、收银台、密码或指纹）时，Copilot 不能在上面点按，它会把 App 交到你的主屏幕上，并附一句说明，例如「支付 ¥23.5，然后点完成」。你用指纹、面容或密码付款后，在悬浮窗中点「完成 · 继续」，Copilot 会检查结果并把任务做完。遇到密码和登录验证时也是这样。你也可以随时在 Copilot 页面点「我来接管」，完成后点「交还给 Copilot」。如果开启了免密支付，订单可能不弹付款界面就直接扣款，这时 Copilot 会检查结果并告诉你。

## 离开 App 和锁屏

交给 Copilot 的任务不需要你一直看着：

- **切到其他 App 或锁屏都没关系。** Copilot 在自己的独立屏幕上操作，这块屏幕不受锁屏影响，任务会继续。
- **任务进行时屏幕保持点亮（变暗）。** Android 会让 Copilot 的屏幕和手机屏幕一起熄灭，所以任务进行中屏幕不会自动熄屏。
- **按电源键关掉屏幕后，Copilot 会暂停。** 锁屏上会显示一条安静的通知「Copilot 已暂停：屏幕已关闭」。点亮屏幕即可继续，不需要解锁。
- **需要你时会点亮屏幕。** 需要你确认操作，或需要你接手（例如付款、登录）时，手机会点亮屏幕，并在锁屏上显示通知。确认请求要打开 PKU harness 处理；接手时解锁后 App 已经在你的屏幕上，完成后在悬浮窗中点「完成 · 继续」。助手最多等你 30 分钟，之后会结束这次回复，你回来后发一条消息即可继续。

## 微信

微信有自己的防自动化检测，由腾讯的服务器控制。检测到 Copilot 时，微信会隐藏界面内容、禁止截图并忽略输入。Copilot 会直接告诉你：微信现在正在阻止自动操作，需要你自己完成这一步，然后停下。请你自己在微信里完成这一步。Copilot 不会尝试绕过这种拦截。

微信的服务条款禁止自动化操作，腾讯可能限制使用自动化工具的账号。助手在一个对话中第一次使用微信时会提到这一点。是否让 Copilot 使用微信，请你自己判断。

## 键盘每个键要点两次

为了能在微信等 App 里读取界面，Copilot 的无障碍服务使用了一个读屏软件的服务名。有些输入法（例如三星键盘）在这类服务开启时会切换到读屏输入方式，每个键都要点两次。

为了避免这个问题，Copilot 在两次任务之间会关闭自己的无障碍服务，下次任务开始时再打开。任务进行中，你在 PKU harness 里打字（键盘打开）时，服务也会在两次操作之间关闭，下一步操作前再打开。它也会在每次操作前检查这个服务，如果被系统或你关掉了，就重新打开。这需要手机助手处于连接状态；没有连接时，服务会一直开着，键盘问题可能再次出现。如果任务结束后键盘仍要点两次，打开 Copilot 页面让手机助手重新连接，服务会在大约 20 秒内关闭。

如果 Copilot 无法重新打开无障碍服务，助手会请你到「系统设置 → 无障碍」中打开，然后停下。

## 停止任务

下面任意一种方式都会立即结束当前的手机任务：

- 点悬浮窗或 Copilot 通知中的「停止」。
- 在 Copilot 页面的「当前任务」下点「停止 Copilot」。
- 关闭「启用 Copilot」。

停止后，当前这次回复不能再自行开始任务。要开始新任务，请发送一条新消息。

## 关闭 Copilot

**不再使用 Copilot**：在 Copilot 页面关闭「启用 Copilot」。允许的 App 列表会保留，新的任务不会再开始。也可以直接告诉助手，例如「关闭 Copilot」。

**同时撤销系统权限**：在 Android 的设置中完成下面几步。

1. 打开「开发者选项 → 无线调试」，在「已配对的设备」下点 PKU harness 配对的设备，再点「取消保存」（或「忘记」）。之后手机助手要重新配对才能连接。
2. 关闭「无线调试」，或者用开发者选项页面顶部的开关关闭整个开发者选项。
3. 在「设置 → 无障碍」中关闭「Copilot」。

Copilot 开启并且已配对时，PKU harness 会在需要时自己重新打开无线调试和无障碍服务，所以第 1 步很重要。手机助手授予 PKU harness 的「修改系统安全设置」权限会一直保留，直到你卸载 App；它只用于 Copilot 自己的无障碍服务和无线调试。

## 哪些内容留在手机上

- 手机助手只连接你自己的手机，不连接电脑或服务器。
- 助手读取被操作 App 屏幕上的文字和控件。这些内容，以及使用截图时的截图，会作为对话的一部分发送给你的 AI 服务商，和其他消息一样。
- 悬浮窗和 Copilot 页面上的预览画面只在你的手机上显示。
- Copilot 看不到你在密码框里输入的内容，也不会替你付款。


# 看板 (/docs/manual/dashboard)

> 「看板」页由一组小组件组成。本页说明怎样添加组件、组件的三种尺寸，以及怎样调整顺序、尺寸和删除组件。

「看板」页显示一组小组件，例如校园卡余额、网费和教学周。你可以让助手搭建和修改这些组件，也可以直接添加插件自带的组件。本页说明这些操作。

## 页面上有什么

页面顶部是问候语。登录校园账号并有课表后，这里还会显示当前教学周、正在上或下一节课的名称，以及今天还剩几节课。

问候语下面是组件。第一次打开 App 时，看板上有三个组件：「今天」（日期和教学周）、「提醒」（待触发的提醒数量）和「教学周」。你可以随时删除或替换它们。

组件中的数据会自动刷新：打开看板、回到 App 时，过期的数据会重新获取；看板显示期间也会按各自的间隔刷新。在页面上向下拉可以立即刷新全部组件。

## 添加组件

有两种方法。

**在对话里让助手添加。** 告诉助手你想在看板上看到什么，例如「把校园卡余额放到看板最上面」或「加一个显示本学期第几周的卡片」。如果某个插件已经提供了合适的组件，助手会直接使用它。否则，助手会用插件的只读工具搭建一个新组件。修改组件的内容也是这样，直接在对话里告诉助手。

**从组件库添加插件组件。**

1. 点看板右上角的「+」（「添加组件」）。看板为空时，点「从插件添加组件」。
2. 组件库列出已开启插件自带的组件。点某个组件旁边的「添加」。

插件自带的组件包括「校园卡余额」「网费」「食堂人流」「空闲教室」「最新通知」「手机令牌」等。某个插件提供哪些组件，可以在「设置 → 插件 → 插件名」页面的「看板组件」一栏查看。

看板为空时，页面下方列出几条示例，例如「显示我接下来的三个提醒」。点按一条，App 会切换到对话页，把它发给助手。看板底部的「＋ 在对话里让 AI 添加或修改组件」会切换到对话页。

## 组件的尺寸

每个组件有三种尺寸之一。

| 尺寸 | 外观 |
| --- | --- |
| 小 | 半个屏幕宽，适合显示一个数字 |
| 宽 | 整个屏幕宽，高度随内容变化 |
| 大 | 整个屏幕宽，更高，用于重点信息 |

## 调整顺序、尺寸和删除

1. 长按任意一个组件，或点右上角的编辑按钮（「编辑看板」），进入编辑状态。
2. 按住一行左侧的把手上下拖动，调整顺序。
3. 点按一行右侧的尺寸标签，在「小」「宽」「大」之间切换。
4. 点按垃圾桶按钮删除这个组件。删除不会再次确认。
5. 点「完成」退出编辑状态。

你也可以在对话里让助手调整顺序、尺寸或删除组件。

如果组件显示「刷新失败」，点「重试」可以重新获取数据。如果组件所属的插件被关闭，组件会显示它已关闭或在此设备不可用。


# 首次设置 (/docs/manual/first-run)

> 第一次打开 App 时的介绍页和六个设置步骤：AI 服务、北大账号、手机令牌、插件、提醒权限和 Copilot，以及「稍后设置」的作用。

第一次打开 PKU harness 时，App 会先显示几页介绍，请你同意用户协议，然后带你完成六个设置步骤。本页按顺序说明每一步。

每完成一步，进度都会保存。如果中途退出 App，下次打开时会回到同一步。要返回上一步，点左上角的返回箭头，或按 Android 的返回键。页面顶部的进度条显示当前在第几步。

<Callout title="先准备好 AI 服务">
  对话页的所有功能都需要一个 AI 模型服务，App 本身不附带。如果你还没有 API Key，请先阅读 [AI 服务](/docs/manual/ai-model)，那里一步一步说明了怎样在 DeepSeek、阿里云百炼或百度千帆申请 Key。整个过程大约十分钟，用手机浏览器就能完成。
</Callout>

## 介绍页和用户协议

介绍页共五页。左右滑动或点「继续」翻页，点「跳过介绍」直接到最后一页。

最后一页有一个复选框：「我已阅读并同意《用户协议》和《隐私政策》……」。点下方的「用户协议」或「隐私政策」可以阅读全文。勾选后，「同意并继续」才能点按。

同意后，AI 可以在你授予的权限内代你操作校园服务。每个插件的权限之后都可以修改，见[插件与权限](/docs/manual/plugins#permissions)。

## 第 1 步：连接 AI 服务

助手需要一个大模型才能工作。这一步需要一个模型服务商提供的 API Key。API Key 是一串类似密码的长字符，通常以 `sk-` 开头。

1. 如果有多个 AI 服务插件，在顶部选择一个：「DeepSeek」或「OpenAI 兼容」。默认是 DeepSeek。使用阿里云百炼、百度千帆等服务时，选「OpenAI 兼容」。
2. 选择「OpenAI 兼容」时，需要填写「接口地址（Base URL）」。各服务商的地址见 [AI 服务](/docs/manual/ai-model#recommended-providers)。
3. 在「API Key」里粘贴密钥。右侧的按钮可以从剪贴板粘贴，以及显示或隐藏密钥。
4. 点「验证并连接」。App 会用这个密钥向服务商发送一次请求。成功时显示「已连接，可用 N 个模型」；失败时会说明原因，例如密钥无效或账户余额不足。
5. 在「模型」下选择一个模型。如果服务商没有返回模型列表，在「模型 ID」里填写模型名称。
6. 点「继续」。

密钥只保存在这台手机上，只会发送给你选择的服务商。

## 第 2 步：登录北大账号

1. 在「学号 / 职工号」和「密码」里填写门户使用的 IAAA 账号。
2. 点「登录」。
3. 如果学校要求短信验证码或手机令牌验证码，App 会弹出输入框。填写后点「验证」。
4. 登录成功后，页面显示「你好，」加上你的姓名。点「继续」。

如果显示网络错误，可能是需要连接校园网的服务暂时访问不到。详见[常见问题](/docs/manual/troubleshooting)。

## 第 3 步：设置手机令牌

这一步把 App 设为你的 IAAA 手机令牌。之后学校登录要求手机令牌验证码时，App 会自动填写，看板上也会出现一个「手机令牌」组件。这个组件平时隐藏验证码，点按后才显示，见[校园账号与手机令牌](/docs/manual/campus-account#authenticator)。

这一步需要先登录北大账号。如果第 2 步没有登录，这里只显示说明和「继续」按钮。

1. 阅读页面上的说明。绑定后，你之前在其他 App（如 FreeOTP、Google Authenticator）里设置的手机令牌会失效。
2. 勾选「我已了解，之前绑定的手机令牌会失效」。
3. 点「发送短信验证码」。验证码会发到账号绑定的手机号。
4. 在「短信验证码」里填写收到的验证码，点「完成绑定」。

暂时不想设置的话，点「暂不设置」。之后可以在「设置 → 插件 → 手机令牌」中完成。

## 第 4 步：选择插件

页面把内置插件分为「校园服务」「效率」「系统」三组。每一行右侧的开关用于开启或关闭插件，改动立即生效。

- 有些插件带有标签。「需登录」表示需要先登录北大账号，「仅校园网」表示只能在校园网内使用，「通知」和「后台」表示它会发送通知或在后台运行。
- 「系统」组里的插件是 App 本身的一部分，始终开启。

选好后点「继续」。之后随时可以在「设置 → 插件」中修改。

## 第 5 步：让提醒准时送达

提醒和定时检查在你的手机上运行，到点由系统闹钟唤起。这一步有三项。

| 项目 | 标签 | 怎么做 |
| --- | --- | --- |
| 「通知」 | 必需 | 点「允许」，在系统弹窗中允许通知。如果通知之前被关闭，按钮会显示「去设置」 |
| 「准时提醒」 | 必需 | 点「开启」，在系统的「闹钟和提醒」设置中允许 PKU harness |
| 「不限制后台」 | 推荐 | 点「允许」，在弹出的系统对话框中点「允许」 |

不开启通知，提醒和预警都不会弹出。不开启准时提醒，系统可能把提醒推迟几分钟甚至更久。不限制后台，早上查余额这类定时检查才能在后台准时运行。

这些权限之后可以在「设置 → 提醒与通知」中修改。

## 第 6 步：让助手替你操作其他 App

这一步介绍「Copilot」。它让助手打开并操作你手机上的其他 App，例如浏览器或外卖 App。这一步只在 Android 上出现。

页面列出 Copilot 需要的几项，并标明「已完成」或「待设置」：

- 「手机助手（无线调试配对）」
- 「无障碍权限」
- 「允许使用的 App」

点「设置 Copilot」会打开 Copilot 页面，在那里完成设置。回到这一步时，如果都已完成，页面显示「Copilot 已就绪」，点「继续」即可。如果手机助手已经连接、但无障碍没有开启，可以直接点这里的「开启无障碍」。

设置大约需要几分钟，会用到 Android 的「开发者选项」。如果你对这些不熟悉，可以先点「稍后设置」，有空时再按照 [Copilot 手机助手](/docs/manual/copilot)一步一步完成。之后也可以在对话中输入 `/copilot` 开始设置。

## 完成

最后一页汇总设置结果：「AI 服务」是否已连接，「北大账号」是否已登录，开启了多少「校园服务」，「提醒」能否准时送达，以及「Copilot」是否已就绪。

如果已经连接 AI 服务，「可以这样开始」下面会列出几个问题，例如「校园卡还剩多少钱？」。点按一个问题，它会被填进对话页的输入框，由你决定是否发送。点「开始使用」进入对话页。

## 「稍后设置」的作用

第 1、2、4、5、6 步底部有「稍后设置」按钮，第 3 步是「暂不设置」。点按后直接进入下一步，这一步填写的内容不会保存。跳过的项目之后都可以补上。

| 步骤 | 之后在哪里设置 |
| --- | --- |
| 连接 AI 服务 | 设置 → AI 服务 |
| 登录北大账号 | 设置 → 校园账号 |
| 设置手机令牌 | 设置 → 插件 → 手机令牌 |
| 选择插件 | 设置 → 插件 |
| 提醒权限 | 设置 → 提醒与通知 |
| Copilot | 在对话中输入 `/copilot`，或设置 → 插件 → Copilot 手机助手 |

没有连接 AI 服务也可以进入 App，但无法对话，对话页会显示「连接 AI 服务」按钮。


# 使用手册 (/docs/manual)

> PKU harness Android App 的使用说明：安装、首次设置、四个标签页、插件与权限、校园账号和各项设置。

本手册说明 PKU harness Android App 1.0.20 版的用法。每一页讲一个部分，步骤中引用的按钮和菜单名称与 App 里显示的一致。

PKU harness 是一个帮你处理校园事务的 Android 应用。你用北大的学号和密码登录一次，再接入一个 AI 模型服务，就可以在对话里让助手查询校园卡余额、同步课表、设置提醒等。每一项连接校园服务的功能都由一个插件提供。

如果你是第一次使用，请先阅读 [AI 服务](/docs/manual/ai-model)：接入模型服务之前，助手什么也做不了。那一页一步一步说明了怎样申请 Key。

## App 的四个标签页

App 底部有四个标签页。

| 标签页 | 内容 |
| --- | --- |
| **对话** | 和助手对话，让它查询信息或替你操作 |
| **看板** | 一组小组件，显示余额、教学周等数字 |
| **日程** | 课表、待办、提醒和定时任务 |
| **设置** | 账号、AI 服务、插件、通知和数据 |

## 本手册的内容

1. [安装与更新](/docs/manual/install)
2. [首次设置](/docs/manual/first-run)
3. [对话](/docs/manual/chat)
4. [看板](/docs/manual/dashboard)
5. [日程与提醒](/docs/manual/schedule)
6. [插件与权限](/docs/manual/plugins)
7. [校园账号与手机令牌](/docs/manual/campus-account)
8. [AI 服务](/docs/manual/ai-model)
9. [语音输入](/docs/manual/voice-input)
10. [校园卡与付款码共享](/docs/manual/campus-card)
11. [Copilot 手机助手](/docs/manual/copilot)
12. [设置与数据](/docs/manual/settings)
13. [常见问题](/docs/manual/troubleshooting)

App 的《用户协议》和《隐私政策》见 [/terms](/terms) 和 [/privacy](/privacy)。


# 安装与更新 (/docs/manual/install)

> 下载并安装 Android 版 PKU harness，核对安装包，以及新版本怎样送到你的手机上。

本页说明怎样安装 PKU harness，以及 App 更新的两种方式。App 目前只有 Android 版。

## 系统要求

- Android 7.0 或更高版本（API 24 及以上）。
- 一个北大校园账号，也就是登录门户用的学号（或职工号）和密码。
- 一个 AI 模型服务的 API Key。默认使用 DeepSeek，详见 [AI 服务](/docs/manual/ai-model)。

## 下载

安装包在[下载页](/download)上，来自 GitHub 仓库 [`pkuinfo/pku-harness`](https://github.com/pkuinfo/pku-harness/releases) 的最新 Release。每个版本有三个 APK，按手机的处理器架构区分。

| 文件 | 适用于 |
| --- | --- |
| `arm64-v8a` | 大多数手机 |
| `armeabi-v7a` | 较旧的 32 位手机 |
| `x86_64` | 电脑上的 Android 模拟器 |

## 安装

1. 在手机上下载 APK。
2. 打开下载好的文件。
3. 如果 Android 提示不允许安装未知来源的应用，按提示允许浏览器（或文件管理器）安装应用，再返回继续。
4. 点「安装」。安装完成后打开 App，按[首次设置](/docs/manual/first-run)的步骤操作。

## 核对安装包

每个正式版 APK 都由 GitHub Actions 从打了标签的提交自动构建，并用同一把发布密钥签名。Release 说明里列出了每个 APK 的 SHA-256、签名证书的 SHA-256 和对应的提交。你可以用这些值核对下载的文件。

<Callout type="warn" title="只安装官方构建">
  App 会在手机里保存你的校园账号密码。请只安装官方 Release 中的 APK，或者自己从源码构建。
</Callout>

## 更新

App 有两种更新方式。

**空中更新（over-the-air update，简称 OTA）** 用于只改动 App 内部代码的小修复。App 每次打开时自动检查。有更新时，App 在后台下载，下次打开 App 时生效。每个空中更新都带有维护者的签名，App 拒绝没有有效签名的更新。这个过程不需要你做任何操作。

**新的 APK** 用于涉及原生代码的版本。App 打开时会检查 GitHub 上的最新 Release，最多每 12 小时检查一次。

- **连接 Wi-Fi 时自动下载**（「设置 → 关于 → 连接 Wi-Fi 时自动下载更新」，默认开启）：发现新版本后，App 在后台用 Wi-Fi 下载，不打扰你。下载完成后会收到「PKU harness X.Y.Z 已下载」通知，点按即可安装。
- 关闭这个开关后，App 会弹出新版本的说明。点「立即更新」后提示会关闭，下载在后台进行，进度显示在通知栏里，你可以照常使用 App。下载完成后同样会收到「点按安装」的通知。

无论哪种方式，安装都要你点按确认：App 打开系统安装器。第一次通过 App 更新时，Android 会请你允许 PKU harness 安装应用，打开这个开关后返回，再在系统安装器里确认安装。

新版本会直接覆盖安装。登录状态、对话、设置和其他数据都会保留。

如果点了「稍后」，App 在 3 天内不会再为这个版本弹出提示。App 检查到新版本后，「设置」页最上方会显示一行「新版本 X.Y.Z 可用」（下载中显示进度，下载完成后显示「已下载」），点按它可以更新或安装。你也可以在「设置 → 关于 → 检查更新」里手动检查。

<Callout title="1.0.6 版本的更新提示">
  在 1.0.6 中，提示里的按钮是「下载」，点它会在浏览器里打开下载链接，不会在 App 内下载。请下载 APK 后按上面的「安装」步骤覆盖安装，数据同样会保留。从 1.0.7 起，App 会自己下载 APK 并打开系统安装器。
</Callout>

## 从源码构建

如果你想自己构建 App，请看 App 仓库的 `README.md`，以及[内置插件 → 在 App 里运行](/docs/build/bundled-plugin#run-it-in-the-app)。


# 插件与权限 (/docs/manual/plugins)

> 在「设置 → 插件」里开启和关闭插件、为每类操作设置权限、通过链接安装插件、更新和移除插件。

App 中每一项连接校园服务的功能都由一个插件提供，例如「校园钱包」「教学网」「树洞」。本页说明怎样管理插件，以及怎样控制助手可以替你做哪些操作。

## 插件列表

打开「设置 → 插件」。页面顶部可以搜索，下面按四组列出所有插件。

| 分组 | 内容 |
| --- | --- |
| 校园服务 | 连接校园服务和其他功能的插件，可以单独开关 |
| 手机操作 | Copilot，在这台手机上替你操作其他 App，见 [Copilot](/docs/manual/copilot) |
| 系统能力 | App 本身的一部分，例如看板、日程、提醒，始终开启 |
| AI 服务 | 模型服务商，例如 DeepSeek，在「设置 → AI 服务」里切换 |
| 远程插件 | 通过 MCP 连接的第三方服务 |

每个插件旁边显示它的状态：「已开启」「已关闭」「需登录」（要先登录校园账号）、「仅限校园网」或「暂不可用」（这台设备不支持它需要的功能）。

插件分为两类来源。**内置插件**随 App 发布，可以关闭，但不能删除。**社区插件**是你通过链接自己安装的插件，可以删除。

## 插件页面

在列表中点按一个插件，打开它的页面。页面上依次有以下内容（有些插件没有其中某几项）。

- **启用插件**：开关。关闭后，助手和看板都无法使用这个插件。
- **打开**：插件自己的页面，例如「校园钱包」插件的「校园卡付款码」，「手机令牌」插件的「手机令牌」。
- **AI 可以做什么**：四类操作的权限，见下一节。
- **云端**：插件是否可以使用云服务，见[设置与数据](/docs/manual/settings#cloud)。
- **看板组件**：这个插件提供的看板组件。
- **能力**：插件提供的全部工具，以及每个工具属于哪类操作。
- **访问范围**：插件可以访问的校园服务和网站。
- **来源**：通过链接安装的插件和内置的插件文档会显示版本、更新和移除选项。

## 权限

插件的每个工具都属于以下四类操作之一。

| 操作 | 例子 |
| --- | --- |
| 读取 | 查询余额、课表、公告等 |
| 修改 | 创建提醒、改设置、提交表单 |
| 资金 | 充值、缴费、付款码 |
| 公开 | 发帖、评论等他人可见的操作 |

在插件页面的「AI 可以做什么」里，你可以为每类操作选择一种权限。

| 权限 | 含义 |
| --- | --- |
| 直接执行 | 助手直接完成，不打扰你 |
| 每次询问 | 助手执行前先请你确认，见[对话 → 确认助手的操作](/docs/manual/chat#confirm-the-assistants-actions) |
| 禁止 | 助手不能这样做 |

这些权限只限制助手。你在界面上亲手点击的操作不受限制。

默认权限如下。

- 内置插件和来自官方仓库 `pkuinfo/pku-harness-plugins` 的插件，默认全部为「直接执行」。少数插件有自己的默认值，例如「Copilot 手机助手」的修改、资金、公开操作默认「每次询问」，「付款码共享」的资金操作默认「每次询问」。
- 社区插件和远程插件的修改、资金、公开操作，默认至少为「每次询问」。

定时任务只能使用读取类工具，也不能使用设置为「每次询问」的工具。

也可以让助手开关插件或修改权限，例如「Copilot 修改东西前先问我」，见[设置 → 在对话中修改设置](/docs/manual/settings#changing-settings-in-chat)。

## 通过链接安装插件

社区插件是一个包含 `PLUGIN.md` 文件的 GitHub 文件夹。安装方法有两种。

**点按安装链接。** 网站[插件市场](/marketplace)上的安装链接以 `pkuharness://plugin?src=` 开头。在手机上点按它，App 会打开「添加插件」页面并填好链接。

**粘贴链接。**

1. 打开「设置 → 插件」，在「远程插件」一组中点「添加远程插件」。
2. 在「链接」里粘贴插件的 GitHub 文件夹链接，例如 `github.com/owner/repo/tree/main/my-plugin`。这里也可以填 MCP 服务地址。
3. 点「检查」。App 会读取插件，但还不会安装。
4. 查看它的信息：作者和版本，标签「官方」或「社区」，「它能访问的」校园服务、网站和 App 功能，以及「它能做的」全部工具。
5. 确认无误后，点「安装」。

社区插件的工具返回的内容只作为数据交给助手，不会被当作指令。

## 更新插件

通过链接安装的插件默认自动更新。在插件页面的「来源」一栏中：

- 「检查更新」会立即检查一次。
- 「自动更新」开关可以关闭自动更新。
- 如果新版本需要更多权限，它不会自动安装，而是显示「版本 X 需要更多权限」。点「查看并更新」查看新版本，再决定是否安装。
- 「退回到版本 X」可以回到上一个版本。

内置插件随 App 提供，从官方链接自动更新。

## 移除插件

在插件页面底部点「移除插件」。只有你通过链接安装的插件和远程插件可以移除。内置插件只能关闭。

## 插件市场

在「设置 → 插件」的「远程插件」一组中点「插件市场」，可以浏览插件，并按「全部」「内置」「远程」筛选。已经内置的插件显示「已内置」，点按会打开它的插件页面。完整的插件市场也可以在网站上浏览：[插件市场](/marketplace)。


# 日程与提醒 (/docs/manual/schedule)

> 「日程」页的课表、待办、提醒和定时任务：怎样添加和修改，提醒的重复规则，以及让通知准时送达的设置。

「日程」页集中显示课表、待办、提醒和定时任务。本页说明怎样添加和修改它们，以及怎样确保提醒准时送达。这些内容也都可以在对话里让助手创建，例如「明天早上 8 点提醒我交作业」。

页面顶部有两个视图：「日程」和「课表」。设置了学期后，标题旁会显示当前是第几周。

## 「日程」视图

「日程」视图显示一天的安排。

1. 在顶部的一周日期条里点选一天。有课的日子带有标记。
2. 下面的三个按钮「待办」「提醒」「课程」分别用于新建一项。
3. 页面依次列出这一天的课（当天显示为「今天的课」）、「待办」，以及「提醒与定时任务」。

点按任意一项可以打开它的编辑页。编辑页底部有「删除」按钮。

## 课表

切换到「课表」视图，可以看到一整周的课程表。用左右箭头切换上一周和下一周。

### 设置学期

教学周、单双周课程和上课提醒都依赖学期设置。登录校园账号后，App 会自动同步校历。你也可以手动设置。

1. 在「课表」视图下方的「课表设置」里点「学期」。
2. 填写「名称」「第 1 周的第一天」和「教学周数」。
3. 点「保存」。

### 从学校同步课表

这个功能由「教务课表」插件提供，需要先登录校园账号。

1. 在「课表设置」里点「从学校同步课表」。
2. 点「同步课表」。
3. 如果页面显示「需要验证」，选择「手机令牌」或「短信」。用短信时先点「发送短信验证码」。填写验证码后点「验证并同步」。如果已经把 App 绑定为手机令牌，验证码会自动填写。

同步会替换上一次同步的课程。你手动添加的课程不受影响。之后可以点「重新同步」更新。

### 手动添加课程

1. 点「课表设置」里的「添加课程」，或「日程」视图上方的「课程」。
2. 填写「课程名称」「星期」「上课」「下课」，以及可选的「地点」「教师」。
3. 在「周次」里填写上课的周，例如 `1-16`、`1-15单`、`2-16双` 或 `1,3,5`。留空表示每周都上。
4. 点「保存」。

### 上课提醒

在「课表」视图底部的「上课提醒（提前）」里，选择「关」「5 分」「10 分」「15 分」或「30 分」。选择后，课表中的每门课都会在上课前这么久提醒你。

## 待办

在「待办」列表底部的输入框里输入内容，按回车即可添加一项。要设置更多内容，点输入框旁边的「更多选项」，或点上方的「待办」按钮。

待办编辑页包括以下几项。

- **内容**和**备注**。
- **截止时间**。
- **提醒**：「不提醒」「到期时」「提前15分」或「提前1时」。设置提醒前需要先设置截止时间。助手创建的待办可能带有其他提醒时间，显示为「自定义」。
- **重要**：打开后，这一项带有旗标；即使没有截止时间，也会出现在「今天」里。
- **重复**：「不重复」「按天」或「按周」。完成一项重复待办后，App 会自动生成下一次，提醒也随之顺延。

待办按「已逾期」「今天」「之后」「无日期」分组。勾选左侧的复选框即可标记完成。已完成的待办收在列表底部，点「展开已完成」可以查看。

## 提醒

点「日程」视图上方的「提醒」新建一条提醒。

1. 填写「标题」，以及可选的「内容」。内容会显示在通知里。
2. 选择「一次」或「重复」。
3. 选「一次」时，设置提醒的日期和时间。
4. 选「重复」时，设置重复规则（见下一节）。
5. 点「保存」。

列表中每条提醒右侧有一个开关，关闭后提醒暂停，但不会被删除。列表会显示下一次提醒的时间；已经结束的提醒显示「已结束」和总次数。

### 重复规则

重复提醒有四种单位：「按天」「按周」「按小时」「按分钟」。

- **间隔**：「每」后面的数字，例如每 3 天、每 2 周。
- **按周**时，选择一周中的哪几天。
- **按天**和**按周**时，可以设置一天中的多个时间，点「添加时间」增加。
- **按小时**和**按分钟**时，设置从哪个时间点开始。

「结束」有三种选择。

| 选项 | 含义 |
| --- | --- |
| 一直重复 | 不会自动停止 |
| 重复次数 | 提醒指定次数后停止，例如「共 16 次后停止」 |
| 截止日期 | 到这一天（含当天）为止 |

例如，「每 3 天提醒一次，共 16 次」是：选「按天」，间隔 3，结束选「重复次数」并填 16。

## 定时任务

除了提醒，助手还可以在对话里创建两种定时任务。它们也显示在「提醒与定时任务」列表中。

**定时检查**按时查询某项数据，满足条件时通知你。例如「每天早上 8 点检查校园卡余额，低于 100 元提醒我」。

- 定时检查最频繁每 15 分钟一次。
- 它只能使用只读的工具，不会修改任何东西。
- 编辑页显示检查条件、「最近运行」的记录，以及「立即检查」按钮。检查条件由助手创建，要修改条件，请在对话里告诉助手。
- 如果连续失败 10 次，检查会自动暂停，并发通知告诉你。排除原因后，可以在列表里重新打开它的开关。

**AI 定时任务**到点时让助手在一个全新的会话里执行一项任务，例如每天整理一次通知。

- 助手执行时只能使用只读工具。没有值得告诉你的内容时，它不会发通知。
- 最频繁每小时一次，同时最多启用 10 个。
- 设置为「每次询问」的工具，定时任务无法使用。
- 编辑页有「立即运行」按钮。

所有提醒和定时任务加起来，同时最多启用 50 个。

## 让提醒准时送达

提醒和定时检查都在手机上运行，到点由系统闹钟唤起，不经过任何服务器。要让它们准时，需要以下权限。

1. 打开「设置 → 提醒与通知」。
2. 「通知」：点「允许」。如果显示已被拒绝，点「去设置」在系统设置中打开。
3. 「精确闹钟」：点「开启」，在系统的「闹钟和提醒」设置中允许 PKU harness。不开启时，提醒可能延后几分钟送达。
4. 「不限制后台」：点「开启」，在系统对话框中点「允许」。这让定时检查能在后台按时运行。

同一页还会显示「后台检查」是否可用、「已排定的通知」数量，以及「发送测试提醒」按钮。测试提醒会在 10 秒后送达，你可以退到桌面或锁屏观察。

如果缺少通知或精确闹钟权限，「日程」页顶部会显示提示，点「开启」或「去设置」即可处理。

在 Android 的系统通知设置里，PKU harness 有三个通知类别：「提醒」（日程、待办与定时提醒）、「检查结果」（后台检查触发的通知）和「后台检查」（检查运行时短暂出现，结束后自动消失）。

如果手机关机或 App 被系统阻止，导致一次定时检查或 AI 定时任务比预定时间晚了 2 小时以上，这次检查会被记为「错过（太晚了）」，不会再发通知。


# 设置与数据 (/docs/manual/settings)

> 「设置」页的各项内容：账号、AI 服务、语音输入、云服务、用量、插件、提醒与通知、外观、语言、时区、触感反馈、导出和清除数据、更新和「关于」页面，以及助手怎样在对话中替你修改设置。

本页按「设置」页从上到下的顺序，说明每一项的作用。大部分设置也可以让助手替你修改，见[在对话中修改设置](#changing-settings-in-chat)。

## 设置页的结构

| 分组 | 项目 | 说明 |
| --- | --- | --- |
| （有新版本时） | 新版本 X.Y.Z 可用 | 点按下载并安装新版本，见[安装与更新](/docs/manual/install#updates) |
| 账号 | 校园账号 | 登录或退出北大账号，见[校园账号与手机令牌](/docs/manual/campus-account) |
| | AI 服务 | 选择模型服务商、填写 API Key，见 [AI 服务](/docs/manual/ai-model) |
| | 语音输入 | 选择语音识别服务、填写 Key，见[语音输入](/docs/manual/voice-input) |
| | 云服务 | 选择云服务器，见下文 |
| | 用量 | Token 用量、活跃时段与常用工具，见下文 |
| 插件 | 插件 | 服务、权限与各插件自己的设置，见[插件与权限](/docs/manual/plugins) |
| 通知 | 提醒与通知 | 通知、精确闹钟和后台权限，见[日程与提醒](/docs/manual/schedule#on-time-delivery) |
| 外观 | 跟随系统 / 深色 / 浅色 | App 的配色 |
| 语言 | 跟随系统 / 简体中文 / English | App 的界面语言 |
| | 时区 | 见下文 |
| | 触感反馈 | 点按、开关和确认时轻微振动 |
| 数据 | 导出数据、清除所有数据 | 见下文 |
| 关于 | 连接 Wi-Fi 时自动下载更新、检查更新、关于 PKU harness | 见下文 |

## 在对话中修改设置

这些页面上能改的设置，助手都能改。在对话中直接说，例如「换成深色模式」「界面改成英文」「时区设为 Asia/Shanghai」「关掉触感反馈」「切换到 DeepSeek-V4-Pro」「关闭树洞插件」「Copilot 修改东西前先问我」或「允许 Copilot 使用浏览器」。助手改完后会告诉你这一项原来是什么、现在是什么。设置页面和助手修改的是同一份设置，所以在任一处修改，另一处都会同步显示。

可以修改的包括：

- App 的外观、语言、时区和触感反馈；
- AI 服务、模型和语音输入服务；
- 每个插件的开关和权限；
- 每个插件自己的设置，例如 Copilot 的开关、允许使用的 App 和「允许 AI 查看截图」。

有些事情只能由你自己完成。助手不能读取或填写 API Key，不能替你登录校园账号，也不能授予通知等系统权限。你提出这类要求时，它会打开对应的页面，由你操作。

这些修改由核心插件「设置」完成，它的权限和其他插件一样。默认情况下，助手修改设置时不会询问。如果想每次确认，在「设置 → 插件 → 设置 → AI 可以做什么」中把「修改」设为「每次询问」。

## 云服务

云服务是一个可选的服务器，只为插件转发和保存加密后的数据。目前用到它的功能是[付款码共享](/docs/manual/campus-card#share-your-payment-code)。校园账号和密码不会离开手机，服务器只认识这台设备的一个匿名密钥。

默认不使用云服务。要开启：

1. 打开「设置 → 云服务」。
2. 选择一个服务器：
   - 「关闭」：不连接任何服务器，依赖云服务的功能不可用。
   - 「官方」：PKU harness 社区运营的实例。
   - 「自建」：你自己或你信任的人部署的开源服务器。在「服务器地址」里填写 `https://` 开头的地址。
3. 点「保存并测试」。连接成功后，页面会显示运营方、支持的服务和限额。

插件要使用云服务，还需要你单独允许。插件第一次需要云服务时，App 会弹出「「插件名」想使用云服务」，列出会离开手机的内容，点「允许」或「暂不」。之后可以在「设置 → 插件 → 插件名」的「云端」一栏中更改，或点「清除此插件的云端数据」。

「本机身份」一栏显示设备指纹，它是这台手机上生成的一对密钥，与校园账号无关。

- 「重置身份」：先删除这台设备在服务器上的数据，再生成新的密钥。进行中的分享会结束。
- 「删除云端数据」：删除这台设备在当前服务器上保存的所有数据。进行中的分享会结束，无法恢复。

## 用量

「设置 → 用量」显示你使用 AI 服务的统计，可以选择「7 天」「30 天」或「全部」。页面包括：

- 今日和本月的 token 用量，以及本月的预估花费。
- 提示缓存的命中率。命中缓存的输入按较低的价格计费。
- 每天的 token 用量、活跃时段和最近 20 周的对话活跃度。
- 用到的插件与工具，以及调用次数和成功率。
- 用到的模型。

花费按服务商公开的价格估算，以服务商的账单为准。

## 时区

提醒、日程、记账和助手都按这个时区计时。这一行的副标题显示当前使用的时区和它此刻与 UTC 的时差。

默认是「跟随系统」：时区随手机的系统设置变化，例如出国时会自动切换。要固定使用某个时区，打开「设置 → 时区」，搜索城市、国家或时区名称，然后点选。

## 导出数据

点「设置 → 导出数据」，App 会生成一个 JSON 文件，并打开系统的分享面板，你可以把它保存或发送到别处。文件包括提醒、待办、课表、看板与设置，不包括密码和 API Key。

## 清除所有数据

1. 点「设置 → 清除所有数据」。
2. 在确认对话框中点「清除」。

提醒、待办、课表、看板、对话和已保存的密钥（包括校园账号密码和 API Key）都会从手机上删除，无法恢复。之后 App 会回到首次设置的介绍页。

## 关于

- 「连接 Wi-Fi 时自动下载更新」：默认开启。新版本在后台用 Wi-Fi 下载，下载完成后由你点按安装。助手也可以替你修改这个设置。
- 「检查更新」：下方显示当前版本号。点按会检查 GitHub 上是否有新的 APK，见[安装与更新](/docs/manual/install#updates)。
- 「关于 PKU harness」：App 版本和正在使用的在线更新，官方网站和源代码的链接，作者和贡献者，我们永久开源、永久免费的承诺，以及「用户协议」和「隐私政策」。网站上的版本见[用户协议](/terms)和[隐私政策](/privacy)。隐私政策说明了哪些数据会发给 AI 服务商、语音输入服务、学校系统和云服务。


# 常见问题 (/docs/manual/troubleshooting)

> PKU harness 的常见问题和解决方法：校园网、登录时的验证码、AI 服务和语音输入报错、附件文件、提醒延迟、App 更新、付款码，以及 Copilot 的设置。

本页列出使用中常见的问题，以及每个问题的原因和处理方法。

## 校园服务和登录

### 提示「财务门户只能在校园网内访问」

财务门户（cwfw.pku.edu.cn）只能在北大校园网内访问。请连接校园网（PKU 或 PKU Secure）后再试。App 访问校园服务时直接连接，不使用系统代理。在插件列表中显示「仅限校园网」的插件都有这个限制。

### 提示「无法连接」某个网站

提示的格式是「无法连接 网站地址（原因）」。可能是这个网站在维护或暂未开放，也可能是它只能在校园网内访问。请检查网络，稍后再试。

### 登录时要求输入验证码

学校的统一身份认证有时会要求短信验证码、邮件验证码或手机令牌验证码，这是正常的。App 在后台刷新登录状态时也可能遇到这种情况。按提示填写即可，见[校园账号与手机令牌 → 登录时的验证码](/docs/manual/campus-account#verification-codes)。

如果后台刷新时需要验证码，App 会提示「校园登录需要验证码，请打开 App 完成验证」。打开 App 填写即可。

树洞会不定期要求单独的短信验证。查看课表和成绩时，也可能需要手机令牌或短信验证码。

### 提示「账号要求手机令牌，但还没有绑定」

你的账号开启了手机令牌，但本 App 还没有绑定为手机令牌。你可以在验证框中填写你正在使用的令牌 App 显示的验证码，或者把本 App 绑定为手机令牌，见[手机令牌](/docs/manual/campus-account#authenticator)。注意，绑定后原来的令牌会失效。

### 插件显示「需登录」

这个插件需要校园账号。在「设置 → 校园账号」中登录即可。

## AI 服务

### 对话页显示「连接 AI 服务」

还没有设置 AI 服务。点这个按钮，或打开「设置 → AI 服务」，见 [AI 服务](/docs/manual/ai-model)。

### 测试连接时报错

| 提示 | 处理方法 |
| --- | --- |
| API Key 无效或已停用 | 检查密钥是否完整、是否已在服务商网站上停用 |
| 账户余额不足 | 先在服务商网站充值 |
| 接口地址不对 | 检查 Base URL，通常以 `/v1` 结尾 |
| 请求太频繁 | 稍等片刻再试 |
| 连接超时 / 连不上服务 | 检查网络和 Base URL |

使用**阿里云百炼**时，Key 只能在创建它的地域使用；[AI 服务](/docs/manual/ai-model#recommended-providers)里给出的接口地址属于北京地域。使用**百度千帆**时，要复制完整的 Key，包括开头的 `bce-v3/`。如果测试提示模型不存在，请对照服务商的模型列表检查「模型 ID」的拼写。

### 无法发送图片

当前模型不接收图片。例如 DeepSeek-V4-Pro 不接收图片，DeepSeek-V4.1-Flash 可以。附件面板中会提示，并在有可用模型时提供「切换」按钮。通过「OpenAI 兼容」接入的模型，App 不提供图片附件。

## 语音输入和文件

### 语音输入无法开始

提示会说明缺少什么：语音识别服务、API Key 或麦克风权限。见[语音输入 → 语音输入用不了时](/docs/manual/voice-input#when-voice-input-doesnt-work)。

### 文件无法读取

| 提示 | 原因 |
| --- | --- |
| 这个 PDF 是扫描的图片，没有文字…… | PDF 里只有页面的图片，而且没有保存 DeepSeek API Key。在「设置 → AI 服务」中填写后即可自动识别，或者拍下页面，作为图片发送 |
| DeepSeek OCR 未能识别这个扫描版 PDF：…… | 原因来自 DeepSeek。检查 DeepSeek 账户是否有余额、文件是否不超过 100 MiB 和 1,000 页，或者改为拍下页面 |
| 这个文件有密码保护…… | 去掉密码后重新添加 |
| 这个文件已损坏，或者实际格式与扩展名不符。 | 在电脑上打开后重新保存 |
| 文件太大…… | 文本文件最大 200 KB，文档最大 30 MB，音频最大 50 MB |
| ……只能转写实时语音…… | 「阿里云百炼（实时）」不能转写音频文件。请在「设置 → 语音输入」中选择硅基流动 |

## 提醒和定时任务

### 提醒推迟送达或没有弹出

1. 打开「设置 → 提醒与通知」。
2. 确认「通知」显示「已允许」，「精确闹钟」显示「提醒会准时送达」。
3. 对「不限制后台」点「开启」，在系统对话框中点「允许」。
4. 点「发送测试提醒」，退到桌面等待 10 秒，确认能收到。

### 定时检查显示「已暂停」

定时检查连续失败 10 次后会自动暂停。常见原因是需要重新登录、需要校园网或网站在维护。排除原因后，在「日程」页的「提醒与定时任务」中打开它的开关。

## 更新

### 点「更新」后无法安装

第一次通过 App 更新时，Android 会请你允许 PKU harness 安装应用。打开这个开关后返回 App，系统安装器会继续。如果没有看到这个请求，可以在系统设置的应用信息中找到 PKU harness，在「安装未知应用」里允许它。

### 提示下载失败

检查网络后，在「设置」页顶部点「新版本 X.Y.Z 可用」重试，或在「设置 → 关于 → 检查更新」中重新检查。也可以在[下载页](/download)手动下载 APK 覆盖安装，数据会保留。

## 校园卡

### 付款码页面要求切换到「数字卡」

付款码只能在「数字卡」用卡方式下使用。点「切换到数字卡」即可。切换后实体卡或手机 NFC 可能无法刷卡，可以在「用卡方式」里改回来。

### 充值后余额没有变化

在收银台付款后，需要在食堂的 POS 机上刷一次卡，余额才会更新。浴卡充值后，需要拿浴卡到浴卡转存机上贴卡。

## Copilot

完整的设置步骤见 [Copilot 手机助手](/docs/manual/copilot)。

### 提示「Copilot 需要 Android 12 或更高版本」

Copilot 用到了 Android 12 才加入的功能。在更早的手机上，App 的其他功能都能用，只有 Copilot 不能用。

### 找不到开发者选项或无线调试

使用系统设置顶部的搜索框：先搜「版本号」，连续点按七次；再搜「无线调试」。各品牌把它们放在不同的位置，见[各品牌手机上的开关位置](/docs/manual/copilot#where-the-switches-are-on-your-phone)。

### 配对码不起作用

每次打开配对弹窗，配对码都会变；弹窗关闭后，配对码就失效了。请保持弹窗打开，下拉通知栏，输入弹窗上当前显示的配对码。如果通知提示配对码错误或已过期，再点一次「使用配对码配对设备」，输入新的配对码。

### 手机助手连不上

- 连接 Wi-Fi，系统询问时允许在此网络上使用无线调试。
- 如果 Copilot 页面提示「系统配对授权已失效，请重新配对」，重新配对一次。
- 如果 Copilot 经常断开，把 PKU harness 的电池使用设为不受限制；小米手机还要允许「自启动」。

### 无法开启 Copilot 无障碍服务

对于通过 APK 安装的应用，Android 会把开启无障碍服务列为「受限制的设置」。有两种处理方法：

- 先连接「手机助手」。它会自动开启无障碍；如果没有，在无障碍这一步点「一键开启」。
- 在 Copilot 页面点「改为在系统设置中开启」，再点「打开应用信息」，点右上角的 ⋮，选择「允许受限制的设置」，然后到系统的无障碍设置中开启「Copilot」。

OPPO 和一加手机还需要在开发者选项中打开「禁止权限监控」。详见 [Copilot 手机助手 → 无障碍](/docs/manual/copilot#enable-accessibility)。

### 助手请你到「系统设置 → 无障碍」中开启

Copilot 每次操作前都会检查自己的无障碍服务，能重新打开时会自动打开。如果打不开（例如手机助手没有连接），助手会请你自己开启，然后停下。打开「系统设置 → 无障碍」，开启「Copilot」，再发送一次请求。

### Copilot 能读到 App 内容，但点按和输入没有反应

小米、Redmi、POCO 手机：在开发者选项中打开「USB 调试（安全设置）」，然后重启手机。OPPO、一加手机：打开「禁止权限监控」。见[各品牌的常见问题](/docs/manual/copilot#known-blockers-by-brand)。

### 微信阻止了自动操作

微信自己的防自动化检测拦截了 Copilot。Copilot 会说明情况并停下，请你自己在微信里完成这一步。这是腾讯服务器端的决定，Copilot 不会尝试绕过。见 [Copilot 手机助手 → 微信](/docs/manual/copilot#wechat)。

### 键盘每个键要点两次

Copilot 的无障碍服务会让部分输入法（例如三星键盘）切换到读屏输入方式。Copilot 会在两次任务之间关闭这个服务，这需要手机助手处于连接状态。打开 Copilot 页面让手机助手重新连接即可。见[键盘每个键要点两次](/docs/manual/copilot#the-keyboard-needs-two-taps-per-key)。

### 「启用 Copilot」开关无法打开

需要同时满足：手机助手已连接、无障碍服务已开启、至少允许了一个应用，并且已移除「已不可用的应用」。


# 语音输入 (/docs/manual/voice-input)

> 在对话框里说话代替打字。用你自己的 Key 设置语音识别服务：阿里云百炼（默认，说话时文字同步出现）、DeepSeek（直接用 AI 服务的 Key）或硅基流动，也可以转写音频文件。

开启语音输入后，点对话框里的麦克风说话，说的内容会变成文字出现在输入框里，发送前可以修改。和 AI 模型一样，语音识别也由你选择的服务商提供，使用你自己的 API Key。

录音从手机直接发送给这家服务商，转成文字后即从手机上删除。PKU harness 不会收到录音。

## 可选的服务

打开「设置 → 语音输入」，页面列出插件提供的语音识别服务，默认服务排在最前。

| 服务 | 文字怎样出现 | 模型 | 在哪里申请 Key |
| --- | --- | --- | --- |
| **阿里云百炼（实时）**（默认） | 边说边出现 | 「Fun-ASR」（默认，每秒 ¥0.00033）、「Paraformer v2」（每秒 ¥0.00024） | [百炼控制台](https://bailian.console.aliyun.com/?tab=model#/api-key)，华北2（北京）地域 |
| **DeepSeek** | 每次停顿后按句子出现 | 「DeepSeek 语音识别」（自动识别语言：普通话、粤语、英语等），每小时音频 $0.116，目前五折为 $0.058，按秒计费 | 不用另外申请，直接使用「设置 → AI 服务」中的 DeepSeek Key |
| **硅基流动** | 每次停顿后按句子出现 | 「SenseVoice」（普通话、英语、粤语、日语、韩语）、「TeleSpeech」（方言识别更好） | [cloud.siliconflow.cn](https://cloud.siliconflow.cn/account/ak) |
| **OpenAI 兼容** | 按句子出现 | 自己填写模型 ID | 任何提供 `/audio/transcriptions` 接口的服务 |

价格是 App 在每个模型旁边显示的数字，实际以服务商的价目表为准。

我们推荐「阿里云百炼」加「Fun-ASR」：说话时文字同步出现，在我们的测试中，它对校园地名识别得最准。如果你已经用百炼作为 [AI 模型](/docs/manual/ai-model#get-an-alibaba-cloud-bailian-api-key)，这里可以用同一个 Key。

如果你的 AI 模型用的是 DeepSeek，又不想再注册一个账号，可以选「DeepSeek」，不需要额外的 Key。DeepSeek 没有实时识别，App 会在你每次停顿时把录音切成一段发送，所以文字是一句一句出现的，而不是逐字出现。价格来自 [DeepSeek 的价目表](https://api-docs.deepseek.com/quick_start/pricing)。

## 设置阿里云百炼

1. 在「华北2（北京）」地域创建一个百炼 API Key，步骤和 [AI 服务 → 申请阿里云百炼 API Key](/docs/manual/ai-model#get-an-alibaba-cloud-bailian-api-key) 相同。其他地域的 Key 不能用。
2. 在 App 中打开「设置 → 语音输入」，点「阿里云百炼（实时）」。
3. 在「模型」下点「Fun-ASR」。
4. 把 Key 粘贴到「API Key」。「获取 API Key」按钮会打开百炼的 Key 页面。
5. 点「保存」。

接口地址是固定的（`wss://dashscope.aliyuncs.com/api-ws/v1/inference`），显示在模型列表下方。

## 设置 DeepSeek

1. 确认「设置 → AI 服务」中已经保存了 DeepSeek API Key。还没有的话，按 [AI 服务 → 申请 DeepSeek API Key](/docs/manual/ai-model#get-a-deepseek-api-key) 操作。
2. 在 App 中打开「设置 → 语音输入」，点「DeepSeek」。
3. 页面显示「使用你在 AI 服务设置中填写的 DeepSeek API Key，无需另外申请。」，不需要粘贴任何内容。如果显示的是「请先在 AI 服务设置中填写 DeepSeek API Key。」，点「打开 AI 服务设置」，在那里保存 Key。
4. 点「保存」。

## 设置硅基流动

1. 在 [cloud.siliconflow.cn](https://cloud.siliconflow.cn) 注册账号，如果要求实名认证，请先完成。
2. 打开[「API 密钥」](https://cloud.siliconflow.cn/account/ak)，新建一个 Key 并复制。
3. 在 App 中打开「设置 → 语音输入」，点「硅基流动」。
4. 在「模型」下点「SenseVoice」；如果你说方言，可以选「TeleSpeech」。
5. 把 Key 粘贴到「API Key」，点「保存」。

## 用语音输入一条消息

1. 在对话页点输入框里的麦克风。第一次使用时，Android 会询问麦克风权限，请允许。
2. 开始说话。输入框显示「正在听…」和你说的内容。
3. 说完后点对勾按钮（「完成并转成文字」），文字会留在输入框里。
4. 需要的话修改一下，然后发送。

不想要这段录音，点关闭按钮（「放弃录音」）。

## 转写音频文件

在对话中也可以附上音频文件：点「+」，再点「文件」，选择一段录音（最大 50 MB）。语音输入服务会把它转成文字，助手读取转写结果。

「阿里云百炼（实时）」只能转写实时语音。要转写音频文件，请在「设置 → 语音输入」中选择「硅基流动」或「OpenAI 兼容」服务。

DeepSeek 也能转写音频文件，但只接受 WAV 或 Ogg Opus 格式、不超过 120 秒和 8 MiB 的录音。更长的录音以及 MP3、M4A 文件可能会失败，所以转写音频文件推荐用硅基流动。

## 语音输入用不了时

| 提示 | 怎么办 |
| --- | --- |
| 请先设置语音输入（设置 → 语音输入）。 | 选择一个服务并保存 |
| 请先为语音输入填写 API Key（设置 → 语音输入）。 | 粘贴 Key 后点「保存」 |
| 麦克风权限已关闭…… | 在 Android 的应用设置中允许 PKU harness 使用麦克风 |
| 没有听到内容…… | 靠近手机再说一次 |
| 语音输入失败：…… | 原因来自服务商。使用百炼时，检查 Key 是否来自北京地域、账户是否有余额 |

也可以让助手切换语音识别服务，例如「语音输入改用硅基流动」。它不能填写 Key，会打开这个页面由你填写。


# 概览 (/docs/marketplace)

> 插件市场如何发现、检查和上架插件，各个徽章的含义，以及 App 如何安装插件。

[插件市场](/marketplace)列出了所有可以在 PKU harness 里安装的插件，包括官方插件和社区开发者写的插件。社区插件有两种：一种是带 `PLUGIN.md` 文件的文件夹，App 读取这个文件并按其中的说明执行；另一种是远程服务器，App 通过 MCP（Model Context Protocol，模型上下文协议）连接它。

插件市场不需要你上传任何东西。你只要告诉它一个公开的 GitHub 仓库，它就会自己找出仓库里的所有插件。这和 [skills.sh](https://skills.sh) 从 GitHub 收录 Agent 技能的做法相同。

## 插件如何上架

<Steps>
<Step>

**为每个插件写一个 `PLUGIN.md`。** 每个插件放在单独的文件夹里，文件夹在仓库的哪一层都可以。`PLUGIN.md` 开头的 YAML frontmatter 说明插件是什么、可以访问哪些东西；后面的 Markdown 正文告诉助手怎样使用它。工具一般单独放在 `tools/*.yaml` 文件里。一个仓库可以只放一个插件，也可以放上百个。所有字段见[清单参考](/docs/marketplace/manifest)。

远程 MCP 服务器也可以改用 `pku-harness.plugin.json` 文件来描述。在 `PLUGIN.md` 的 `remote.mcp` 取代它之前，这种旧格式会一直保留。

</Step>
<Step>

**检查并提交仓库。** 把仓库粘贴到 [/marketplace/submit](/marketplace/submit)。网站会立即扫描，列出找到的每个插件，以及它们的错误、警告和卡片预览。

全部通过后，点击**提交上架**，网站会打开一个预先填好内容的 GitHub issue。机器人会再扫描一次仓库，然后开一个 pull request，把仓库加进 `data/sources.json`。最后由维护者合并这个 pull request。

</Step>
<Step>

**推送代码即可更新。** 插件市场大约每小时重新扫描一次所有已上架的仓库。你修改清单、新增或删除插件文件夹后，列表会随之更新，不需要重新提交。

</Step>
</Steps>

## 插件的标识和 id

每个插件有两个名字。**标识**（handle）是 `owner/repo/path`，也就是存放 `PLUGIN.md` 的文件夹，例如 `alice/campus-tools/canteen`。**id** 是清单里的 `id` 字段，例如 `canteen-menu`。插件在本站的页面地址用的是 id：`/marketplace/alice/campus-tools/canteen-menu`。

`id` 在整个插件市场里必须唯一。App 会把每个工具注册为 `<id>.<tool>`，把每个远程插件注册为 MCP 服务器 `mcp-<id>`。如果两个插件的 id 相同，它们的工具就会在手机上冲突。两个仓库使用同一个 id 时，先上架的仓库保留它。官方插件的 id 不能被占用。

## 官方插件、已审核插件和社区插件

每个插件页都会显示下面三种徽章之一。徽章表示插件经过了多仔细的审查，不影响插件的功能。

| 徽章 | 含义 |
|---|---|
| **官方 Official** | 由 pkuinfo 在 [`pku-harness-plugins`](https://github.com/pkuinfo/pku-harness-plugins) 里维护，从其中的 `registry/registry.json` 上架。 |
| **已审核 Verified** | 维护者读过源码的社区插件，按插件 id 记录在 `data/sources.json` 里。 |
| **社区 Community** | 通过扫描器的检查后自动上架，还没有人读过源码。 |

维护者把插件标为「已审核」之前要检查什么，以及插件在什么情况下会被下架，见[审核规则](/docs/marketplace/review)。

## 插件市场的英文名称

大多数插件的名称以中文为主。如果插件提供了英文名称和简介，英文版插件市场就会显示它们：

- `PLUGIN.md` 插件写在 `i18n.en.name` 和 `i18n.en.description` 里，还可以在 `i18n.en.tools.<name>` 里为每个工具提供英文标题和简介。
- 官方插件写在注册表条目里，即 `registry/registry.json` 中的 `i18n.en: { name, description }`。

如果插件没有英文名称，英文页面会根据 id 生成一个名称，并在下方显示原来的中文名称。

## App 如何安装插件

不同种类的插件，安装方式也不同。

**插件文档**（`PLUGIN.md`）通过链接安装。插件页提供三种方式：*在 App 中打开*按钮（`pkuharness://plugin?src=…`）、二维码，以及安装链接本身，也就是 GitHub 文件夹的 URL。你可以把链接粘贴到「设置 → 插件」里。App 随后下载文件并弹出审查面板。面板上会写明插件是官方还是社区插件、用到哪些校园服务和网站、需要哪些 App 功能，以及每个工具的效果。你确认后，App 把插件保存在手机上。

之后，App 会重新下载这个链接来检查更新。如果更新没有申请新的权限，App 会直接应用；如果申请了更多权限，就要等你确认后才生效。

**内置插件**随 App 一起安装，你可以在「设置 → 插件」里开启。部分官方内置插件本身就是插件文档，它们和其他插件文档一样，从各自的 GitHub 链接更新。

**远程插件**是使用 Streamable HTTP 传输的 MCP 服务器。你可以在「设置 → 插件 → 插件市场」里添加，也可以直接粘贴它的端点 URL。App 连接这个端点，并把它的工具注册为 `mcp-<id>`。如果插件使用 `"auth": "bearer"`，你需要粘贴一个 token，App 会把它保存在手机的钥匙串里。

**自建插件**是没有公开 `endpoint` 的远程插件。插件市场会列出它们的源码链接，你需要自己部署一份服务器，再把它的 URL 粘贴到 App 里。

无论哪种插件，手机上都不会运行第三方代码。App 只执行 `PLUGIN.md` 里声明的步骤，远程插件则运行在作者自己的服务器上。访问校园服务的请求由 App 带着你的会话发出，所以插件永远看不到你的密码、cookie 或 token。

## 供程序读取的接口

App 和 AI Agent 通过下面这些 URL 读取插件市场：

| URL | 内容 |
|---|---|
| [`/marketplace.json`](/marketplace.json) | 完整索引（`MarketplaceIndex`：`plugins[]` + `sources[]`），支持 CORS，每小时刷新。 |
| [`/marketplace/llms.txt`](/marketplace/llms.txt) | 同一份列表的 Markdown 版本，供语言模型阅读。 |
| [`/schema/plugin-manifest.v1.json`](/schema/plugin-manifest.v1.json) | `pku-harness.plugin.json` 的 JSON Schema。这是描述远程 MCP 服务器的旧格式。 |
| `POST /api/marketplace/scan` | 接收 `{ "repo": "owner/repo" }`，返回扫描报告。有频率限制，提交页用的就是它。 |


# 清单参考 (/docs/marketplace/manifest)

> 插件市场如何读取 PLUGIN.md（插件语言 v1）、扫描器在哪里查找插件、检查哪些内容，以及远程 MCP 服务器使用的 pku-harness.plugin.json 格式。

本页列出插件市场会读取和检查的插件内容。准备上架仓库时，或者扫描器报出一个你看不懂的问题时，可以来这里查。

一个插件就是一个带 `PLUGIN.md` 文件的文件夹。文件开头的 YAML frontmatter 是插件的「清单」（manifest），说明插件是什么、可以访问哪些东西；下面的 Markdown 正文是交给助手的使用说明。完整的插件语言（工具、步骤、表达式和界面）见 [`docs/PLUGIN-LANGUAGE.md`](https://github.com/pkuinfo/pku-harness/blob/master/docs/PLUGIN-LANGUAGE.md)。如果你刚开始写插件，请先读[声明式插件](/docs/build/declarative-plugins)。

```md title="campus-tools/canteen/PLUGIN.md"
---
spec: 1
id: canteen-menu
name: 食堂菜单
description: 今天各食堂的菜单和营业时间。
version: 1.0.0
author: alice
icon: food
network: [dining.pku.edu.cn]
tools:
  menu: tools/menu.yaml
widgets:
  today: widgets/today.json
dataSources:
  today: { tool: menu, args: { day: today }, ttl: 30m }
i18n:
  en: { name: Canteen menu, description: "Today's menus and opening hours." }
---

Use `menu` when the user asks what to eat or which canteen is open. Prices are in yuan.
```

## 扫描器在哪里查找插件

扫描器通过 GitHub API 读取仓库的默认分支，并用下面两种方式之一查找插件。

1. 如果仓库根目录有 **`pku-harness.json`** 文件，扫描器只检查其中列出的文件夹（最多 200 个），并按列出的顺序检查。大型 monorepo 适合这样做：

   ```json title="pku-harness.json"
   { "plugins": ["plugins/canteen", "plugins/library-seat"] }
   ```

   `"."` 表示仓库根目录。如果列出的文件夹里没有清单，扫描器会报错。

2. 否则，仓库里任意层级的每个 **`PLUGIN.md`** 都算一个插件。扫描器会跳过存放依赖、测试和测试数据的文件夹，所以其中的示例清单不会被上架。跳过的文件夹有：

   - `node_modules`，以及名称以 `.` 开头的文件夹；
   - `test`、`tests` 和 `__tests__`；
   - `fixtures`、`__fixtures__` 和 `testdata`；
   - `e2e`（端到端测试）。

   只要路径中有一层文件夹叫这些名字，就会被跳过。例如 `plugins/canteen/tests/PLUGIN.md` 不会上架。`pku-harness.json` 里列出的文件夹则一定会被检查，不论它叫什么名字。

一个文件夹最多对应一个插件。如果一个文件夹里有多种清单，扫描器**优先使用 `PLUGIN.md`**，其次是 `pku-harness.plugin.json`，最后是带 `"pkuHarness"` 对象的 `package.json`（见[远程 MCP 插件](#remote-mcp-plugins)）。

提交时也可以填一个子文件夹的 URL，例如 `https://github.com/owner/repo/tree/main/plugins`。这样扫描器只查找这个文件夹。

## Frontmatter 字段

下表列出所有顶层字段。「必填」一栏为空的字段都是可选的。

| 字段 | 必填 | 说明 |
|---|---|---|
| `spec` | 是 | `1`。App 会拒绝它不认识的版本。 |
| `id` | 是 | `^[a-z0-9][a-z0-9-]{1,40}$`。在整个插件市场里唯一，因为工具会注册为 `<id>.<tool>`。 |
| `name` | 是 | 显示名称，以中文为主。 |
| `description` | 是 | 一句话，4–200 个字符。 |
| `version` | 是 | 语义化版本号（semver）。如果 YAML 会把它读成数字，请加引号（`"1.0"` 本来也不是合法的 semver）。 |
| `author` | 是 | GitHub 用户名或名字。 |
| `icon`、`homepage` | | App 图标集里的图标名；一个 URL。 |
| `minApp` | | 插件需要的最低 App 版本（`x.y.z`）。 |
| `campus` | | App **带着用户会话**调用的校园服务（取值见下文）。 |
| `network` | | 插件访问的公开主机（`dining.pku.edu.cn`、`*.example.com`），只允许 HTTPS。 |
| `abilities` | | 插件用到的宿主能力（取值见下文）。 |
| `shared` | | 一个 YAML 文件（`shared.yaml`），其中的 `constants` 和 `functions` 所有工具都能使用。 |
| `tools` | | 工具名到文件（`tools/menu.yaml`）或内联工具的映射，见[工具](#tools)。 |
| `dataSources` | | 供小组件和定时检查轮询的读取工具：`{ tool, args?, ttl }`。 |
| `widgets`、`screens` | | 名称到 JSON 文件的映射（生成式界面 spec 加数据绑定）。 |
| `settings`、`commands`、`defaultModes` | | 设置项、斜杠命令，以及按效果建议的授权方式。 |
| `requires` | | 可以不写，因为插件市场会根据其他字段[推导](#derived-capabilities)出来。 |
| `cloud` | | 使用 PKU harness Cloud，并附上通俗易懂的数据说明（[见下文](#cloud-disclosure)）。 |
| `server` | | 服务端函数。官方服务器暂不开启（见下文）。 |
| `i18n.en` | | 英文字符串：`name`、`description`，以及 `tools.<name>.{title,summary}` 等覆盖项。 |
| `remote` | | `{ mcp: https URL, auth?: none \| bearer }`，把这个文件夹变成[远程 MCP 插件](#remote-mcp-plugins)。 |

**`campus`** 可以填这些服务名：`card`、`its`、`treehole`、`blackboard`、`elective`、`cwfw`、`cwpay`、`bdkj`、`library`、`library-space`、`portal`，以及 App 认识的其他服务。写了未知的服务名会得到警告。

**`abilities`** 可以填 `verify`、`otp`、`todos`、`timetable`、`scheduler`、`browser`、`campusPage`、`sms`、`files`、`crypto` 和 `cloud`。每种能力提供哪些操作、对应什么效果，见[声明式插件指南](/docs/build/declarative-plugins#host-abilities)。写别的名字会报错，因为 App 会拒绝它。

**`server`** 声明服务端函数，这些函数运行在 PKU harness Cloud 上（[CLOUD-FUNCTIONS.md](https://github.com/pkuinfo/pku-harness/blob/master/docs/CLOUD-FUNCTIONS.md)）。带 `server` 的插件必须写 `cloud.disclosure`，并且隐含 `cloud.uses: [functions]`。官方服务器**暂不开启**服务端函数，使用官方实例的用户无法运行它们。请让插件在手机上完成工作，或者使用你自己的后端。

### 使用说明

`PLUGIN.md` 的 Markdown 正文会成为插件给模型的使用说明。App 每次对话都会带上它，所以请写得简短，讲清楚什么时候用哪个工具、数字代表什么即可。插件市场会在插件页上展示正文，超过 20,000 个字符的部分会被截掉；正文超过 8,000 个字符时会给出警告。

### 工具

`tools` 里的每一项都是助手可以调用的一个工具。它可以是一个 YAML 文件的路径（例如 `tools/menu.yaml`），也可以直接内联写在清单里。每个工具都必须有 `title`、`description` 和如实填写的 `effect`：`read`、`write`、`money` 或 `public`。

工具还可以有一个 `summary`：一行简短的说明，最多 80 个字符，告诉用户这个工具做什么。`description` 是写给模型看的，往往很长；`summary` 是写给用户看的。插件页会把它显示在工具标题下方，插件市场的搜索也会匹配它。

```yaml title="tools/talks.yaml"
title: 学术日历
summary: 近期的学术讲座
description: >-
  Academic talks between two dates, sorted by start time. Default: today to 30 days ahead.
effect: read
untrusted: true
```

如果想让英文版插件市场显示英文的标题和简介，请在 `PLUGIN.md` 的 `i18n.en.tools.<name>` 下添加。没有英文简介的工具会显示中文简介。

```yaml
i18n:
  en:
    name: Campus events
    description: Calendars of academic talks and campus activities.
    tools: { talks: { title: Academic talks, summary: Upcoming academic talks } }
```

### 文件

App 只加载 frontmatter 在 `tools`、`shared`、`widgets` 和 `screens` 里点名的文件，从不遍历文件夹去找别的文件。对每个点名的路径，扫描器会检查它：

- 相对于 `PLUGIN.md`，不含 `..`，不以 `/` 开头，也没有 URL 协议；
- 在仓库里确实存在（文件缺失是**错误**）；
- 连同 `PLUGIN.md` 总共不超过 **512 KB**（按 GitHub 文件树里的 blob 大小计算）。

扫描器还会下载每个点名的工具文件，读出它的 `title`、`summary` 和 `effect`，插件页会把这些作为权限面板的一部分展示出来。frontmatter 没有点名的文件，例如 `tests/`、`README.md` 和 `assets/`，都会被忽略。

### 推导出的能力需求

插件页和插件市场的筛选器会显示一份 `requires` 列表。它包括你在 `requires` 里写的内容，以及其他声明隐含的内容：

| 声明 | 隐含 |
|---|---|
| 任何 `campus` 服务 | `campus-session`、`network` |
| `campus: [cwfw]` | 另加 `campus-network`（cwfw 只在校园网内响应） |
| `network` 主机，或 `remote` | `network` |
| `abilities: [scheduler]` | `background` |
| `cloud.uses` 非空，或有 `server` | `cloud` |

### 安装链接

每个 `PLUGIN.md` 插件的页面都会给出安装方式：

- 安装链接，即默认分支上的 GitHub 文件夹 URL，例如 `https://github.com/alice/campus-tools/tree/main/canteen`；
- *在 App 中打开*按钮，深链接为 `pkuharness://plugin?src=<url-encoded install link>`；
- 这个深链接的二维码。

页面上显示的标识是 `owner/repo/path`。

## 远程 MCP 插件

远程插件运行在你自己的服务器上，通过 Streamable HTTP 提供 MCP（Model Context Protocol，模型上下文协议）服务。App 把它当作名为 `mcp-<id>` 的 MCP 服务器来连接，所以请把服务器的 `name` 设成插件的 `id`。

描述远程插件时，`PLUGIN.md` 只需要 `remote` 字段，不写工具。工具由服务器提供，所以文件里声明的工具会被忽略，并给出警告。

```md title="PLUGIN.md"
---
spec: 1
id: canteen-live
name: 食堂实时人数
description: 各食堂当前排队人数。
version: 1.0.0
author: alice
remote: { mcp: "https://canteen.example.com/mcp", auth: none }
---

Use the tools when the user asks how crowded a canteen is.
```

远程服务器永远拿不到用户的校园会话，因此远程插件写了 `campus` 会得到警告。

### 旧格式：`pku-harness.plugin.json`

在 `PLUGIN.md` 的 `remote.mcp` 取代它之前，插件市场仍然会为远程 MCP 服务器读取 `pku-harness.plugin.json`，以及 `package.json` 里的 `"pkuHarness"` 对象。把 `$schema` 指向 [`/schema/plugin-manifest.v1.json`](/schema/plugin-manifest.v1.json)，编辑器就能在你输入时检查这个文件。

```json title="pku-harness.plugin.json"
{
  "$schema": "https://<this site>/schema/plugin-manifest.v1.json",
  "id": "canteen-live",
  "name": "食堂实时人数",
  "description": "各食堂当前排队人数。",
  "endpoint": "https://canteen.example.com/mcp",
  "requires": ["network"],
  "scopes": ["dining.pku.edu.cn"]
}
```

### `pku-harness.plugin.json` 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 | `^[a-z0-9][a-z0-9-]{1,40}$`，在整个插件市场里唯一。请把它用作 MCP 服务器的 `name`（见下文）。 |
| `name` | string | 是 | 显示名称，以中文为主（不超过 40 个字符）。 |
| `description` | string | 是 | 一句话，4–200 个字符，说明它能帮同学做什么。 |
| `author` | string | | 默认是仓库的 GitHub 所有者。 |
| `kind` | `"remote"` \| `"builtin"` | | 默认 `"remote"`。`"builtin"` 保留给随 App 内置的插件。 |
| `endpoint` | https URL \| null | | 公开的 MCP 端点（Streamable HTTP）。**自建**插件不写，或填 `null`。 |
| `auth` | `"none"` \| `"bearer"` | | 默认 `"none"`。填 `"bearer"` 时，用户要在 App 里粘贴一个 token。 |
| `icon` | string | | App 图标集里的图标名（`wallet`、`food`、`library`、`bus`……），或者指向方形图片的 `https://` URL。 |
| `requires` | capability[] | | 插件需要什么，见[能力需求](#capabilities-requires)。 |
| `scopes` | string[] | | 插件访问的主机名（`"dining.pku.edu.cn"`、`"*.example.com"`），会展示给用户。 |
| `tags` | string[] | | 小写的搜索标签。 |
| `cloud` | object | | PKU harness Cloud 的使用声明，从 `PluginDef.cloud` 复制过来，见[下文](#cloud-disclosure)。 |
| `version` | string | | 显示在插件页上。 |
| `license` | string | | SPDX 许可证标识，例如 `"MIT"`。 |
| `homepage` | https URL | | 文档或项目主页。 |
| `i18n.en` | `{ name?, description? }` | | 英文字符串。 |
| `$schema` | string | | 扫描器会忽略它。 |

`id` 的作用不只在插件市场。App 会把插件安装为名为 `mcp-<id>` 的 MCP 服务器，并靠这个名字判断插件是否已安装。如果服务器的 `name` 与 `id` 不同，App 就无法把两者对应起来。

`endpoint` 必须使用 `https://` 和公网主机，不能包含凭据或查询字符串。

未知字段会被忽略，同时给出警告。这样拼错字段名时，你会知道有数据没有生效。

#### 写在 package.json 里

```json title="package.json"
{
  "name": "@campus-tools/library-seat",
  "version": "0.3.0",
  "description": "图书馆座位查询与预约提醒。",
  "license": "MIT",
  "pkuHarness": {
    "id": "library-seat",
    "name": "图书馆座位",
    "endpoint": "https://seat.example.com/mcp",
    "requires": ["network"],
    "scopes": ["seat.lib.pku.edu.cn"]
  }
}
```

`description`、`version`、`license` 和 `homepage` 默认取 package 自身的字段，`pkuHarness` 里写的值会覆盖它们。**没有 `id`** 的 `pkuHarness` 对象被视为 SDK 元数据，不会上架。内置插件用的就是这种写法：`{ "builtin": true }`。

## 能力需求（`requires`）

下表中的每个值都会显示在插件页上，右栏是展示给用户的含义。

| 值 | 展示给用户的含义 |
|---|---|
| `network` | 会访问互联网上的服务器。 |
| `campus-network` | 部分主机只在北大校园网内响应。 |
| `campus-session` | 使用用户已登录的校园会话办事。 |
| `notifications` | 发送本地通知。 |
| `background` | App 关闭时也会运行定时检查。 |
| `shell`、`filesystem` | 手机上两者都没有。App 会隐藏需要它们的插件，扫描器也会给出警告。 |
| `cloud` | 使用 PKU harness Cloud，必须有 `cloud` 块。 |
| `ongoing` | 显示一个实时的持续活动。 |

`PLUGIN.md` 插件通过声明 `campus` 获得 `campus-session`，请求由 App 自己签发。远程 MCP 服务器永远拿不到校园会话，所以它申请 `campus-session` 时扫描器会警告。

远程插件运行在你的服务器上，所以只需声明要由**手机**提供的东西。

## 云服务数据说明

如果插件使用 PKU harness Cloud，它的 `cloud` 块必须用通俗的话写清楚哪些数据会离开设备。插件市场和 App 都会在插件页上显示这些说明。

```json
"cloud": {
  "uses": ["store"],
  "e2e": true,
  "disclosure": { "zh": ["你的收藏列表会加密存到云端，用于多设备同步。"], "en": ["Your favourites are stored encrypted in the cloud to sync devices."] }
}
```

扫描器采用与注册表中 `cloudIssues()` 相同的规则：

- `uses` 不能有重复项；
- `uses` 非空时，至少要有一行 `disclosure.zh`，用通俗的话说明哪些数据会离开设备；
- 不能有空行；
- 如果写了 `disclosure.en`，它必须逐行翻译 `zh`；
- 外部 `backend.url` 必须使用 `https`。

## 扫描器检查什么

有错误的插件不会上架。警告不影响上架，会显示在插件页的**检查结果**里。提示只是建议。

| 检查项 | 级别 |
|---|---|
| 没有 frontmatter、YAML 或 JSON 不合法，或违反 schema（`spec`、semver 格式的 `version` 等） | 错误 |
| 仓库内 `id` 重复、占用官方 id，或 id 已被另一个已上架仓库使用 | 错误 |
| 点名的文件是绝对路径、含 `..` 或不存在；总大小超过 512 KB | 错误 |
| 工具文件缺少 `title`、`description` 或合法的 `effect`，或 `summary` 超过 80 个字符 | 错误 |
| `dataSources` 指向未声明的工具，或 `settings` 指向未声明的页面 | 错误 |
| `network` 里有不是主机名的条目 | 错误 |
| 端点（`remote.mcp`、`endpoint`）不是 https，是私有或本地主机、IP，或带凭据、查询字符串 | 错误 |
| 违反上面的 `cloud` 数据说明规则；有 `server` 但没有 `cloud.disclosure.zh` | 错误 |
| 未知的 `abilities` | 错误 |
| `PLUGIN.md` 里有未知的顶层字段（App 严格解析） | 错误 |
| 在 `pkuinfo/pku-harness-plugins` 之外使用 `kind: "builtin"`（JSON） | 错误 |
| 未知的 `campus` 服务 | 警告 |
| 有 `server`（官方服务器暂不开启）；写了 `abilities: [cloud]` 却没有 `cloud` 或 `server` 块 | 警告 |
| 远程插件写了 `campus`（JSON 清单写了 `campus-session`） | 警告 |
| `requires` 里有 `shell` 或 `filesystem` | 警告 |
| `requires: cloud` 但没有 `cloud` 块 | 警告 |
| Markdown 正文为空或太长；没有任何工具、命令或小组件 | 警告 |
| 远程插件声明了 `tools`（会被忽略） | 警告 |
| JSON 清单里有未知字段 | 警告 |
| 没有 `i18n.en`；JSON 清单没有 `endpoint`（自建）或没有 `license` | 提示 |

扫描器还有以下大小限制：

- 每个仓库最多 100 个插件、300 个 `package.json`；
- 每个插件最多 40 个工具文件，每个仓库最多 400 个；
- 每个下载的文件最大 256 KB；
- 每次 GitHub 请求最长 10 秒。

如果仓库太大，GitHub 一次请求列不完文件树，扫描器会给出警告。在仓库里加一个列出插件文件夹的 `pku-harness.json` 就能解决。


# 发布 (/docs/marketplace/publishing)

> 提交仓库、在一个仓库里发布多个插件、推送代码来更新，以及下架插件。

本页介绍如何把插件上架到插件市场、如何更新，以及如何下架。插件市场直接从公开的 GitHub 仓库读取插件，所以大部分工作都在你自己的仓库里完成。

## 提交之前

请先确认以下几点：

- 每个插件是一个带 `PLUGIN.md` 的文件夹。frontmatter 点名的每个文件（位于 `tools/`、`widgets/` 或 `screens/`）都已提交。见[清单参考](/docs/marketplace/manifest)和[声明式插件](/docs/build/declarative-plugins)。
- 如果是远程插件，也就是 MCP（Model Context Protocol，模型上下文协议）服务器，服务器已经通过 HTTPS 部署好，或者你写清楚了如何自行部署。服务器的 `name` 与插件的 `id` 相同。可以从 [`templates/remote-plugin`](https://github.com/pkuinfo/pku-harness-plugins/tree/main/templates/remote-plugin) 模板开始。
- 仓库在 github.com 上是**公开**的。
- 插件遵守[审核规则](/docs/marketplace/review)。简单地说：绝不索要校园密码，如实声明效果，工具只返回数据、不返回指令，使用云服务时写明数据说明。

## 提交仓库

1. 打开 [/marketplace/submit](/marketplace/submit)，粘贴 `owner/repo`、仓库 URL 或文件夹 URL，例如 `https://github.com/owner/repo/tree/main/plugins`。
2. 修好预览里显示的所有错误。每次 push 之后重新检查一遍。检查结果会缓存大约一分钟。
3. 点击**提交上架**。网站会在 [`pkuinfo/pkuharness-website`](https://github.com/pkuinfo/pkuharness-website/issues) 打开一个预先填好内容的 issue，并带上 `plugin-submission` 标签。
4. GitHub Action 会再扫描一次仓库，把报告作为评论发到 issue 上。扫描通过后，它会开一个 pull request，把仓库加进 `data/sources.json`。你编辑 issue 后，Action 会重新运行。
5. 维护者合并 pull request 后，插件会在网站下次部署时出现在插件市场里。

你也可以在自己的电脑上扫描并添加仓库，然后自己开 pull request：

```bash
bun scripts/marketplace.ts scan owner/repo   # 打印报告（有错误时退出码为 1）
bun scripts/marketplace.ts add owner/repo    # 扫描，然后加进 data/sources.json
```

不带 token 时，GitHub API 每小时只允许 60 次请求。设置 `GITHUB_TOKEN`（例如 `GITHUB_TOKEN=$(gh auth token)`）后，额度会提高到每小时 5000 次。

## 一个仓库放多个插件

一个仓库可以放任意多个插件，不需要额外设置。扫描器会找出仓库里的每个 `PLUGIN.md`，每个插件都有自己的标识 `owner/repo/<folder>` 和自己的安装链接。

扫描器会跳过存放依赖、测试和测试数据的文件夹，例如 `node_modules`、`tests`、`fixtures` 和 `e2e`。所以你放在这些文件夹里做测试用的 `PLUGIN.md` 不会被上架。完整列表见[清单参考](/docs/marketplace/manifest#where-the-scanner-looks)。

大型 monorepo 还可以在根目录加一个 `pku-harness.json`，列出插件所在的文件夹。这样扫描器只按顺序检查这些文件夹，扫描更快，其他清单也不会混进来：

```json title="pku-harness.json"
{ "plugins": ["services/canteen", "services/library-seat", "services/bus"] }
```

## 更新插件

更新插件只需要推送到默认分支。插件市场大约每小时重新扫描一次已上架的仓库。新增插件文件夹会让新插件上架，删除文件夹则会让插件下架。

已经安装了 `PLUGIN.md` 插件的手机，会从插件的链接重新下载它。如果声明没有变化，App 会直接应用更新；如果插件申请了更多权限，更新要等用户同意后才生效。「更多权限」指新增的校园服务、主机或宿主能力，或者某个工具的效果比以前更强。

请让每个插件的 `id` 在各个版本之间保持不变。用户的安装记录、小组件和定时检查都靠 id 来找到插件。

如果某次 push 引入了错误，只有出错的那个插件会从插件市场撤下。仓库页面会显示扫描器发现的问题，方便你修复。

## 下架插件

**下架自己的插件。** 删除 `PLUGIN.md` 文件、删除仓库，或者把仓库设为私有。下次扫描时插件就会从列表中消失。如果想把仓库条目也删掉，请开一个 pull request，从 `data/sources.json` 里移除它。

**维护者下架。** 如果插件违反了[审核规则](/docs/marketplace/review)，维护者会从 `data/sources.json` 里删除这个仓库，还可能禁止作者再次提交。


# 审核规则与安全 (/docs/marketplace/review)

> 每个上架插件都要遵守的规则、维护者把插件标为「已审核」前检查什么，以及如何举报插件。

在 PKU harness 里，助手以同学本人的校园身份替他办事。插件会扩展助手能做的事，所以无论官方插件还是社区插件，都要遵守同样的规则。本页列出这些规则，解释「已审核」徽章的含义，并说明如何举报插件。规则来自插件仓库的 [CONTRIBUTING.md](https://github.com/pkuinfo/pku-harness-plugins/blob/main/CONTRIBUTING.md)。

## 规则

<Callout type="error" title="绝不索要校园密码">
  凭据只保存在同学自己的手机上。插件不得索要、收集或转交同学的密码、动态口令（OTP）或会话 cookie，无论是在工具、界面还是文档里。需要校园服务的 `PLUGIN.md` 只要在 `campus` 里声明即可，App 会带着用户的会话发出这些请求，插件永远看不到凭据。远程 MCP（Model Context Protocol，模型上下文协议）服务器则完全拿不到校园会话。
</Callout>

1. **把每个工具写清楚。** 用户和助手都通过工具来使用插件。每个工具都要有清晰的中文 `title`，也可以加一行简短的 `summary`（最多 80 个字符），告诉用户它做什么。`description` 要告诉模型何时、如何使用它。输入要经过校验，MCP 服务器用 JSON Schema 校验。
2. **如实声明每个工具的效果。** `read` 工具不能改动任何东西。改变状态的工具是 `write`，花钱的是 `money`，公开发布内容的是 `public`。在 MCP 服务器上，只有只读工具才能设置 `readOnlyHint: true`，其余工具 App 一律按 `write` 处理。同学会按效果分别决定助手可以直接执行，还是必须先询问。效果写错，助手就可能跳过本该有的确认，所以我们把它当作安全漏洞处理。
3. **只返回数据，不返回指令。** 工具结果是作为数据交给模型的。不要在结果里放提示词、隐藏指令，或者「忽略之前的指令」这类文字。如果工具返回的是别人写的文字，例如论坛帖子、通知或邮件，请标上 `untrusted: true`，也绝不能把这类内容当作指令转给模型。
4. **声明插件访问的所有东西。** 在 `PLUGIN.md` 里列出插件需要的每个校园服务（`campus`）、公开主机（`network`）和宿主能力（`abilities`），并给每个工具写上真实的 `effect`。这份清单就是同学同意的权限面板，没有声明的东西 App 一律拒绝。
5. **说明云服务的用途。** 如果插件使用 PKU harness Cloud，清单的 `cloud` 块必须用通俗的话写清楚哪些数据会离开设备。不加说明就收集数据的插件会被下架。
6. **如实说明插件的访问范围。** `scopes` 列出你的服务器会访问的主机，`requires` 列出需要手机提供的东西。不要依赖手机上的命令行或文件系统。
7. **注明协议出处。** 如果你从 [pkucli](https://github.com/pkuinfo/pkucli) 移植了某个校园协议，请注明来源文件。

## 自动检查与人工审核

每个上架的插件都通过了扫描器的检查（[检查内容](/docs/marketplace/manifest#what-the-scanner-checks)）。通过检查只能说明清单格式正确，不能说明插件是安全的。

**已审核**徽章表示维护者还做了下面这些事：

- 读过 `PLUGIN.md`、它的工具文件和 Markdown 说明，确认声明与步骤的实际行为一致，包括校园服务、主机、宿主能力、效果和云服务数据说明。维护者还确认了说明和结果里没有类似提示词的文字；
- 确认公开端点运行的就是这份源码，或者插件是自建的；
- 对照上面的规则检查过，特别是关于凭据和提示词注入的规则。

### 把插件标为已审核（给维护者）

审核状态按仓库记录在 `data/sources.json` 里：

```json title="data/sources.json"
{
  "sources": [
    { "repo": "alice/campus-tools", "addedAt": "2026-11-02", "verified": ["canteen-menu"] }
  ]
}
```

要审核通过一个插件，就在 pull request 里把它的 `id` 加进 `verified`。如果某个已审核的 id 在仓库里已经不存在，`bun scripts/marketplace.ts check` 会失败。持续集成（CI）会在 `data/` 每次变更时运行这项检查，每周也会运行一次。

已审核的插件之后如果有较大改动，应该重新审核；拿不准时就把它的 id 移除。官方插件则通过 `pku-harness-plugins` 里的 `registry.json` 审核。

可选的 `sources[].path` 字段把一个仓库条目限定在某个子文件夹。有人提交文件夹 URL 时，提交流程会自动设置它。

## 举报插件

在 [`pkuinfo/pkuharness-website`](https://github.com/pkuinfo/pkuharness-website/issues) 开一个 issue，写上插件的标识（`owner/repo/id`）和你看到的问题。如果是 App 或官方插件的安全漏洞，请按照[安全策略](https://github.com/pkuinfo/pku-harness-plugins/blob/main/SECURITY.md)报告。


# campus (/docs/sdk/campus)

> 通过宿主访问已登录校园服务所用的类型（CampusService、CampusRequest、CampusResponse、multipart 上传、用户选取的文件），以及登录状态和手机令牌验证码。

插件需要以用户身份访问校园网站时，例如查询校园卡余额或在树洞发帖，就通过 `services.campus.request` 让宿主代为发送请求。这个模块定义了请求、响应和相关状态的类型。使用这些接口的插件需要声明 `campus-session` 能力。

源码：`packages/sdk/src/campus.ts`。概念介绍见[校园会话](/docs/concepts/campus-sessions)。

## 插件能看到什么

校园账号和密码由宿主保存在设备的密钥库里。宿主自己登录各个服务，包括 IAAA（北大统一身份认证）、门户的单点登录（SSO）和 ITS（校园网账号系统），然后把服务的响应交给插件。插件既拿不到密码，也拿不到原始的会话 token。

上传文件（multipart 请求）时，宿主直接从本地 URI 读取文件并发送，文件内容同样不经过插件。

## 类型

```ts
/**
 * - `card`：bdcard.pku.edu.cn（宿主自动加上 synjones JWT）
 * - `its`：its.pku.edu.cn（网络账号会话）
 * - `treehole`：treehole.pku.edu.cn `/chapi/…`（宿主自动加上 Bearer JWT 和设备 uuid）。树洞自己的
 *   二次验证仍会返回给插件：40002 = 短信验证，40077 = 课程数据令牌。
 * - `blackboard`：course.pku.edu.cn（教学网，HTML 页面；SSO 会话，自动跟随重定向）
 * - 其余服务由宿主的适配器注册（bdkj、cwfw、cwpay、elective、library、library-space）
 */
type CampusService = 'card' | 'its' | 'treehole' | 'blackboard' | (string & {});

type CampusRequest = {
  /** 绝对 URL，或该服务主机上的路径（例如 "/berserker-app/…"）。 */
  url: string;
  method?: 'GET' | 'POST';
  headers?: Record<string, string>;
  body?: string;
  contentType?: string;
  responseType?: 'text' | 'base64';
  /** 表单字段，以 url-encoded 格式发送（代替 `body`）。 */
  form?: Record<string, string>;
  /**
   * 会话凭据放在哪里，默认放在请求头。'form' 表示同时放进 `form`，用于从请求体读取 token 并对其签名的
   * 接口（校园卡的下单接口）。
   */
  authIn?: 'headers' | 'form';
  /** 发送 `form` 前的最后一步：加上签名。在宿主内运行；仅限内置插件。 */
  sign?: (fields: Record<string, string>) => Record<string, string> | Promise<Record<string, string>>;
  /** 是否跟随 3xx 重定向（默认由服务决定）。false 表示自己读取 `location`。 */
  followRedirects?: boolean;
  /** multipart/form-data 请求体（上传文件），代替 `body` / `form`。方法默认为 POST。 */
  multipart?: CampusMultipart;
  /** 请求超时，单位为毫秒（默认 20 秒；multipart 为 120 秒）。 */
  timeoutMs?: number;
};

type CampusMultipart = {
  /** 文本字段：用 [name, value] 数组可以保持顺序并允许重名。文本字段写在文件之前。 */
  fields: Record<string, string> | [string, string][];
  files: CampusFilePart[];
};

type CampusFilePart = {
  /** 这一部分的表单字段名，例如 "newFile_LocalFile0"。 */
  field: string;
  /** 发送给服务器的文件名。 */
  name: string;
  /** MIME 类型，例如 "application/pdf"。 */
  mime: string;
  /** 来自 `services.files.pick` 的本地 URI。 */
  uri: string;
};

type PickedFile = {
  name: string;
  mime: string;
  /** 字节数，系统提供时才有。 */
  size: number | null;
  /** 本地 URI，在本次应用会话内有效。 */
  uri: string;
};

type CampusResponse = { status: number; url: string; headers: Record<string, string>; body: string };

type CampusStatus = {
  signedIn: boolean;
  username: string | null;
  /** 持卡人姓名，已知时才有（来自校园卡）。 */
  name: string | null;
};

/** 当前的手机令牌（IAAA TOTP）验证码；密钥始终留在宿主内。 */
type OtpCode = { code: string; /** 距离验证码更新还有几秒（1–30）。 */ remainingSeconds: number };

/** 宿主的手机令牌绑定状态（不含密钥）。`pending` 表示已发送绑定短信，正在等待验证码。 */
type OtpStatus = { bound: boolean; userId: string | null; userName: string | null; boundAt: number | null; pending: boolean };
```

## 示例

```ts
// 用校园卡会话调用 JSON 接口
const res = await ctx.services.campus.request('card', { url: '/berserker-app/ykt/tsm/queryCard?synAccessSource=h5' });
if (res.status !== 200) throw new Error(`校园卡服务返回 HTTP ${res.status}`);
const json = JSON.parse(res.body);

// 向树洞发送 JSON POST 请求
await ctx.services.campus.request('treehole', {
  url: '/chapi/api/jwt_send_msg',
  method: 'POST',
  body: JSON.stringify({}),
  contentType: 'application/json',
});

// 会话 token 放在表单里并签名，自己读取重定向
// （节选自 plugins/wallet/src/card/recharge.ts，移植自 pkucli campuscard api.rs）
const order = await ctx.services.campus.request('card', {
  url: '/charge/order/thirdOrder',
  method: 'POST',
  followRedirects: false,
  authIn: 'form', // 宿主在签名前把校园卡会话加进表单
  form: { feeitemid: '401', tranamt: '50', synAccessSource: 'h5' /* … */ },
  sign: (fields) => signFields(fields, ctx.services.crypto.sha256), // 对最终字段签名
});
const cashier = order.headers.location; // 用 services.browser.open 打开，不要返回给模型
```


# cloud (/docs/sdk/cloud)

> 插件使用 PKU harness Cloud 时的接口：CloudManifest、PluginCloud（store、channels、push、functions）、Channel 及其事件、SecretLink、CloudStatus、CloudError 和 defineCloudFunction。

PKU harness Cloud 是一组可选的云服务，插件可以用它在服务器上保存少量数据，或者通过中继与打开分享链接的人实时共享内容。这个模块定义了插件这一侧的接口。插件先在清单里声明要用哪些服务，再通过宿主提供的客户端调用它们。

源码：`packages/sdk/src/cloud.ts`。使用指南见[云服务 → 插件指南](/docs/cloud/plugin-guide)。线上协议见
[`@pku-harness/cloud-protocol`](/docs/cloud/protocol-package) 和 [API 参考](/docs/cloud/api/meta)。

## 宿主替插件保管什么

插件在 `PluginDef.cloud` 里声明要用的服务，然后拿到一个只属于自己的客户端（`ctx.cloud`、`props.cloud`）。设备身份、token 和密钥都由宿主保管。宿主负责检查用户是否已经授权、调用是否符合插件清单，并和用户选定的服务商通信。服务商可以是官方服务器、自建服务器或任意 URL。

插件看不到 token、密钥和服务商凭据，助手也看不到分享链接。

<Callout title="宿主支持情况">
  应用已经实现了这个客户端。为了兼容不支持云服务的宿主，`ctx.cloud` 的类型仍是可选的（`PluginCloud | undefined`），使用前先检查 `ctx.cloud?.available`。

  `push` 暂未提供，调用会以 `not_configured` 失败。官方云服务实例目前还没有部署。它上线后只运行中继和一个小型加密存储，不开启服务端函数。另外，服务端函数要以明文读取输入，所以声明了端到端加密（`e2e`）的插件调用 `functions.invoke` 时，宿主会拒绝。能在手机上完成的工作就放在手机上；确实需要服务器时，请使用你自己的后端。
</Callout>

## CloudManifest

`CloudManifest` 是插件在 `PluginDef.cloud` 中声明的清单，写明插件要用哪些服务、哪些数据会离开设备，以及数据是否端到端加密。

```ts
type CloudService = 'store' | 'channels' | 'push' | 'files' | 'functions';

interface CloudManifest {
  protocol: 1;
  uses: CloudService[];
  /** 授权弹窗中显示的说明，用平实的语言逐条写明哪些数据会离开设备。 */
  disclosure: { zh: string[]; en?: string[] };
  /** 所有 store 和 channel 数据都在客户端加密；为 true 时，宿主拒绝明文写入。 */
  e2e: boolean;
  /** 没有云服务时插件仍可使用，相关功能先检查 ctx.cloud.available。否则插件依赖 'cloud'。 */
  optional?: boolean;
  /** 服务端函数：运行在用户的服务商上（代码位于 plugins/<id>/server），或运行在外部 URL。 */
  functions?: Record<string, CloudFunctionDecl>;
  backend?: { kind: 'provider' } | { kind: 'external'; url: string };
  /** plugins/<id>/web 中的静态页面，发布在 /w/<plugin>/<page>（供没有安装应用的人查看）。 */
  pages?: string[];
}

interface CloudFunctionDecl<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
  title: string;
  input: I;
  output: O;
  version: number;
  timeoutMs?: number;
}

function defineCloudFunction<I extends z.ZodType, O extends z.ZodType>(d: CloudFunctionDecl<I, O>): CloudFunctionDecl<I, O>;
```

## PluginCloud

`PluginCloud` 是插件拿到的客户端，`CloudStatus` 描述它当前的状态。

```ts
interface PluginCloud {
  /** 已配置服务商、用户已授权，并且服务商可以连通（允许离线的读取除外）。 */
  readonly available: boolean;
  status(): CloudStatus;
  /**
   * 请用户允许这个插件使用云服务（弹出宿主的授权弹窗；已经允许时立即返回）。用户拒绝时返回 false。
   * 界面在打开通道前调用它；助手调用工具时从不弹窗，直接得到 `CloudError('consent_required')`。
   */
  requestConsent(): Promise<boolean>;
  /** 键值存储，服务商按（设备，插件）划分命名空间。启用 `e2e` 时值会加密。 */
  store: {
    get<T>(key: string): Promise<{ value: T; version: number } | undefined>;
    put<T>(key: string, value: T, opts?: { ifVersion?: number; ttlS?: number }): Promise<{ version: number }>;
    delete(key: string): Promise<void>;
    list(prefix?: string): Promise<{ key: string; version: number; updatedAt: number }[]>;
  };
  /** 端到端加密的中继通道（与打开链接的人实时共享）。 */
  channels: {
    /** `meta` 用链接密钥加密；查看者在加入前读取它。 */
    open(opts: { ttlS: number; maxPeers?: number; page?: string; meta?: unknown }): Promise<Channel>;
    /** 应用重启后仍然可用（密钥保存在安全存储中）。 */
    get(id: string): Channel | undefined;
    list(): Channel[];
  };
  /** 第 6 阶段。 */
  push: {
    schedule(at: number, payload: unknown): Promise<string>;
    cancel(id: string): Promise<void>;
  };
  /** `CloudManifest.functions` 中声明的服务端函数（第 6 阶段）。 */
  functions: {
    invoke<N extends string>(name: N, input: unknown, opts?: { signal?: AbortSignal }): Promise<unknown>;
  };
}

interface CloudStatus {
  provider: 'official' | 'custom' | 'off';
  baseURL?: string;
  /** 用户已允许这个插件使用云服务。 */
  consented: boolean;
  online: boolean;
}
```

## Channel

通道（channel）用于实时共享：插件打开一个通道，把分享链接交给别人，打开链接的人就成为通道的对端（peer）。

```ts
interface Channel {
  id: string;
  expiresAt: number;
  link: SecretLink;
  peers(): { id: string; joinedAt: number }[];
  /** 订阅事件；返回取消订阅的函数。 */
  on(ev: ChannelEventType, fn: (e: ChannelEvent) => void): () => void;
  /** 按每个对端分别加密；'*' 表示所有已连接的对端。 */
  send(peerId: string | '*', msg: unknown): Promise<void>;
  /** 加密的数据块，所有者离线时对端也能读取（批量模式）。 */
  mailbox: {
    put(slot: string, msg: unknown, ttlS: number): Promise<void>;
    clear(): Promise<void>;
  };
  /** 移除一个对端并空出它的位置（新的查看者可以用同一个链接加入）。 */
  kick(peerId: string): Promise<void>;
  extend(ttlS: number): Promise<void>;
  close(): Promise<void>;
}

type ChannelEventType = 'join' | 'leave' | 'message' | 'closed';
type ChannelCloseReason = 'owner' | 'expired' | 'revoked' | 'locked' | 'server';

type ChannelEvent =
  | { type: 'join'; peerId: string; at: number }
  | { type: 'leave'; peerId: string; at: number }
  /** 对端发来的消息，已经解密（使用前请用 zod 校验）。 */
  | { type: 'message'; peerId: string; msg: unknown }
  | { type: 'closed'; reason: ChannelCloseReason };
```

## SecretLink

```ts
/**
 * 不透明的分享链接（`https://<provider>/s/<id>#k=…`）。插件读不到其中的 URL，只能用
 * `host.shareLink(link)` 或 `<QRCode link={link} />` 显示它。`JSON.stringify(link)` 得到 "[secret link]"。
 */
interface SecretLink {
  readonly kind: 'secret-link';
  readonly channelId: string;
  toJSON(): string;
}
```

宿主实现的 `toString` 同样输出 `"[secret link]"`，所以链接不会混进工具结果或日志。

## 错误

```ts
type CloudErrorCode = 'not_configured' | 'consent_required' | 'offline' | 'rate_limited' | 'quota' | 'gone' | 'protocol' | 'server';
const CLOUD_ERROR_CODES: readonly CloudErrorCode[];

class CloudError extends Error {
  readonly code: CloudErrorCode;
  /** 错误码为 'rate_limited' 时才有（取自 Retry-After）。 */
  readonly retryAfterS?: number;
  constructor(code: CloudErrorCode, message: string, retryAfterS?: number);
}

function isCloudError(e: unknown, code?: CloudErrorCode): e is CloudError;
```

各错误码的含义如下：

| 错误码 | 含义 |
| --- | --- |
| `not_configured` | 没有配置服务商，或该服务不可用（比如 `push`） |
| `consent_required` | 用户还没允许这个插件使用云服务 |
| `offline` | 没有网络。写入和函数调用会立即失败，不会悄悄排队重发 |
| `rate_limited` | 服务商返回 429，`retryAfterS` 有值 |
| `quota` | 超出存储或通道配额 |
| `gone` | 通道已关闭或已过期 |
| `protocol` | 服务商的响应不符合协议 v1，或调用违反了清单（使用未声明的服务、`e2e` 插件发送明文） |
| `server` | 服务商的其他错误 |


# dashboard (/docs/sdk/dashboard)

> 看板小组件的数据类型：Widget 类型，Binding 和 WidgetSource 的 schema，以及 WidgetSize。services.widgets 也使用这些类型。

这个模块定义看板上小组件的数据结构。看板上的小组件有两种：一种由助手生成，用一份界面描述（spec）加上数据绑定（bindings）来显示；另一种由插件提供，插件自己用原生组件绘制。插件通过 `services.widgets` 读写小组件时，用的就是这里的类型。

源码：`packages/sdk/src/dashboard.ts`。概念介绍见[看板](/docs/concepts/dashboard)。

## 类型与 schema

```ts
import { z } from 'zod';

export const bindingSchema = z.object({
  tool: z.string().describe('read-only tool id, e.g. "calendar.today"'),
  args: z.record(z.string(), z.unknown()).optional(),
  /** 工具结果中的点分路径；为空表示整个结果。 */
  path: z.string().optional(),
  /** 缓存有效期，单位为分钟（默认 5）。 */
  ttlMinutes: z.number().min(0).max(24 * 60).optional(),
});
export type Binding = z.infer<typeof bindingSchema>;

export const widgetSizeSchema = z
  .enum(['sm', 'md', 'lg'])
  .describe('sm = half width tile, md = full width, lg = full width hero');
export type WidgetSize = z.infer<typeof widgetSizeSchema>;

/** 插件提供的小组件（`contributes.widgets`），按键名放到看板上。 */
export const widgetSourceSchema = z.object({
  plugin: z.string(),
  widget: z.string().describe("key in the plugin's contributes.widgets"),
  config: z.record(z.string(), z.unknown()).optional(),
});
export type WidgetSource = z.infer<typeof widgetSourceSchema>;

/**
 * 两种小组件并排显示：助手生成的（`spec` + `bindings`），以及插件提供的
 * （`source`，由插件原生绘制；`spec`/`bindings` 留空）。
 */
export type Widget = {
  id: string;
  title: string;
  size: WidgetSize;
  /** json-render 界面描述（{ root, elements, state? }）。 */
  spec: Record<string, unknown>;
  /** state 路径（JSON pointer，例如 "/card"）→ 数据来源。 */
  bindings: Record<string, Binding>;
  source?: WidgetSource;
  position: number;
  createdAt: number;
  updatedAt: number;
};
```

`sm` 是半宽的小方块，`md` 占满整行，`lg` 是占满整行的大尺寸卡片。

## 绑定如何填充数据

每个绑定会调用一个只读工具，再用 [`setPointer`](/docs/sdk/pointer) 把结果写进 spec 的 state。例如，一个挂在 `/card`、`path` 为 `"balance"` 的绑定，会让 spec 里的 `{ "$state": "/card" }` 取到余额。

## 在工具里放置插件小组件

要在工具里放置插件提供的小组件，先构造一个带 `source` 的 `Widget`，再调用 `put`：

```ts
const w: Widget = {
  id: ctx.services.widgets.newId(),
  title: '校园卡余额',
  size: 'md',
  spec: {},
  bindings: {},
  source: { plugin: 'wallet', widget: 'card', config: { warnBelow: 30 } },
  position: ctx.services.widgets.list().length,
  createdAt: Date.now(),
  updatedAt: Date.now(),
};
await ctx.services.widgets.put(w);
```

大多数插件不需要这样做，因为助手会自己调用 `dashboard.addPluginWidget` 放置小组件。


# format (/docs/sdk/format)

> 按界面语言格式化日期和时间的函数，以及用来定义多语言字符串表的 defineStrings。

这个模块帮你按 App 当前的语言显示文字。它提供两类工具：一是定义插件的中英文字符串表，二是把日期、时间和倒计时格式化成符合该语言习惯的字符串。

源码：`packages/sdk/src/format.ts`。指南：[多语言](/docs/build/i18n)。下文中的 `locale` 参数类型是 `AppLocale`，取值为
`'zh-Hans' | 'en'`。

App 运行在 React Native 的 JavaScript 引擎 Hermes 上。Hermes 的 `Intl` 会忽略 locale 参数，所以这些函数不使用 `Intl`，自己拼出字符串。它们的输出和 App 自身的日期格式一致，插件界面因此和 App 其他地方保持统一。这些函数都是纯函数，测试时传入 `now` 参数即可得到固定结果。

## 字符串表

字符串表把同一组文案的中文版和英文版放在一起。`defineStrings` 以中文版为准做类型检查：英文版少了或多了某个键，或者值的类型不同，编译时就会报错。

```ts
/** 按语言划分的字符串表；`en` 的键（以及值的类型）必须与 `zh-Hans` 完全一致。 */
type Localized<T> = { 'zh-Hans': T; en: T };

/** 定义插件的字符串表，`en` 按 `zh-Hans` 做类型检查。 */
const defineStrings: <T>(table: { 'zh-Hans': T; en: NoInfer<T> }) => Localized<T>;
```

## 日期和时间

下表列出各个格式化函数的签名，以及它们在两种语言下的输出示例。

| 函数 | 签名 | zh-Hans | en |
| --- | --- | --- | --- |
| `formatClock` | `(d: Date \| number, seconds?: boolean) => string` | `21:04` / `21:04:37` | 同左 |
| `formatWeekday` | `(d: Date \| number, locale) => string` | `周一` | `Mon` |
| `weekdayName` | `(weekday: number, locale) => string`（1 = 周一 … 7 = 周日，0 也表示周日） | `周一` | `Mon` |
| `formatLocalDate` | `(d, locale, now?) => string`（不是今年时带上年份） | `10月18日`、`2025年10月18日` | `Oct 18`、`Oct 18, 2025` |
| `formatLocalDateTime` | `(d, locale, now?) => string` | `10月18日 21:04` | `Oct 18, 21:04` |
| `formatRelative` | `(ms: number, locale, now?) => string`（过去的时间戳） | `刚刚`、`3 分钟前`、`21:04`、`昨天 21:04`，再往前是日期加时间 | `Just now`、`3 min ago`、`21:04`、`Yesterday 21:04` …… |
| `formatDay` | `(d, locale, now?) => string` | `今天`、`明天`、`昨天`、`周三`（未来一周内）、日期 | `Today`、`Tomorrow`、`Yesterday`、`Wed`、日期 |
| `formatCountdown` | `(ms: number, locale) => string`（剩余时间） | `3天5小时`、`2小时10分`、`8分钟`、`不到1分钟`、`已到` | `3d 5h`、`2h 10m`、`8 min`、`<1 min`、`Now` |
| `dayDiff` | `(d, now?) => number` | 距今天的自然日数（0 今天，1 明天，−1 昨天），不受夏令时影响 | |
| `plural` | `(n: number, one: string, many?: string) => string` | — | `plural(3, 'book')` → `3 books` |

```ts
import { formatCountdown, formatRelative } from '@pku-harness/sdk';

const locale = host.useLocale();
formatRelative(data.updatedAt ?? Date.now(), locale);      // "3 分钟前" / "3 min ago"
formatCountdown(deadline - Date.now(), locale);            // "2小时10分" / "2h 10m"
```

这些函数用于给用户看的界面。给模型看的时间戳另有处理：宿主会在每一轮对话中附上当前时间，定时相关的工具则使用
[scheduler](/docs/sdk/scheduler) 里的 `formatLocal`，输出形如 `"2026-10-20 08:00 周二"`。


# genui (/docs/sdk/genui)

> 描述生成式界面 spec 的 specSchema 和 UISpec 类型，以及 services.genui.checkSpec 返回的 SpecCheck 结果。

助手可以在对话里临时生成一块界面，比如一张表单或一个选择列表。它用一份 JSON 描述这块界面，我们称之为「spec」。这个模块定义了 spec 的结构；如果你的工具要接收助手写的 spec，或者你要在页面里显示一份 spec，就会用到它。

源码：`packages/sdk/src/genui.ts`。概念介绍：[生成式界面](/docs/concepts/generative-ui)。

```ts
import { z } from 'zod';

/** 助手写出的 json-render spec（组件来自宿主的组件目录）。 */
export const specSchema = z.object({
  root: z.string().describe('id of the root element'),
  elements: z.record(
    z.string(),
    z.object({
      type: z.string(),
      props: z.record(z.string(), z.unknown()),
      children: z.array(z.string()).optional(),
      on: z.record(z.string(), z.unknown()).optional(),
      visible: z.unknown().optional(),
    }),
  ),
  state: z.record(z.string(), z.unknown()).optional().describe('initial state, e.g. { "form": { "amount": "50" } }'),
});

export type UISpec = z.infer<typeof specSchema>;

export type SpecCheck = { ok: true; spec: UISpec } | { ok: false; issues: string[] };
```

一份 spec 由若干元素组成，`elements` 以 id 为键，`root` 指明根元素的 id。每个元素用 `type` 指定组件，用 `children` 列出子元素的 id。`state` 是界面的初始状态。

`specSchema` 只检查结构。每个 `type` 是否在组件目录里、props 是否合法，由宿主通过 `services.genui.checkSpec(spec)` 检查：

```ts
const r = ctx.services.genui.checkSpec(spec);
if (!r.ok) return { shown: false, issues: r.issues }; // 让模型自己修正 spec
```

接收 spec 的工具可以直接把 `specSchema` 用作输入 schema，`ui.render` 和 `dashboard.upsertWidget` 都是这样做的。要在页面里渲染 spec，请使用 `host.components.GenUI`。


# HostServices (/docs/sdk/host-services)

> 内置插件通过 ctx.services 或 props.services 拿到的全部宿主服务的签名和行为，包括设置注册表和附件，以及任务、小组件目录和常驻通知相关的类型。

插件不能直接调用 App 的内部代码。需要打开浏览器、选择文件、发校园网请求、创建提醒时，插件调用宿主提供的服务。工具在 `ctx.services` 中拿到这些服务，页面和小组件在 `props.services` 中拿到。这一页列出每项服务的签名和行为。

源码：`packages/sdk/src/plugin.ts`。概念介绍：[宿主服务](/docs/concepts/host-services)。

```ts
interface HostServices {
  phone: PhoneService;
  settings: SettingsService;
  browser: {
    open(url: string): Promise<{ opened: true }>;
  };
  files: FilesService & {
    pick(opts?: { types?: string[]; multiple?: boolean }): Promise<PickedFile[]>;
  };
  crypto: {
    sha256(text: string): Promise<string>;
  };
  registry: {
    plugins(): PluginInfo[];
    tool(id: string): ToolInfo | undefined;
  };
  docs?: {
    review(input: { link?: string; files?: Record<string, string> }): Promise<{ opened: true }>;
    source(id: string): { link: string | null; version: string; files: Record<string, string> } | null;
  };
  remote: {
    install(input: { url: string; name?: string; token?: string }): Promise<{ id: string; name: string; tools: { name: string; effect: ToolEffect }[] }>;
    uninstall(id: string): Promise<void>;
    has(id: string): boolean;
  };
  genui: {
    describeCatalog(): string;
    checkSpec(spec: unknown): SpecCheck;
  };
  notify: {
    readiness(): Promise<NotifyReadiness>;
    fix(kind: NotifyFixKind): Promise<NotifyReadiness>;
  };
  sms: {
    awaitCode(): Promise<string | null>;
  };
  scheduler: {
    create(input: JobInput): Promise<Job>;
    update(id: string, patch: JobPatch): Promise<Job>;
    remove(id: string): Promise<void>;
    get(id: string): Job | undefined;
    list(): Job[];
    runCheck(id: string): Promise<CheckResult>;
  };
  widgets: {
    list(): Widget[];
    get(id: string): Widget | undefined;
    newId(): string;
    put(widget: Widget): Promise<void>;
    remove(id: string): Promise<void>;
    reorder(ids: string[]): Promise<void>;
    preview(widget: Widget): Promise<Record<string, unknown>>;
    resolve(widget: Widget, force?: boolean): Promise<Record<string, unknown>>;
    catalog(): WidgetCatalogEntry[];
  };
  todos: {
    list(): Todo[];
    get(id: string): Todo | undefined;
    add(input: TodoInput, source: JobSource): Promise<Todo>;
    update(id: string, patch: Partial<TodoInput>, source: JobSource): Promise<Todo>;
    setDone(id: string, done: boolean): Promise<Todo>;
    remove(id: string): Promise<void>;
  };
  campus: {
    status(): CampusStatus;
    request(service: CampusService, req: CampusRequest): Promise<CampusResponse>;
    otp(): Promise<OtpCode | null>;
    otpStatus(): Promise<OtpStatus>;
    otpBindStart(): Promise<{ sentTo: string | null }>;
    otpBindFinish(smsCode: string): Promise<OtpStatus>;
    otpUnbindLocal(): Promise<void>;
    openSignedIn(service: CampusService): Promise<{ opened: true }>;
  };
  ongoing?: {
    start(opts: OngoingOptions): OngoingHandle;
  };
  timetable: {
    get(): { courses: Course[]; semester: Semester | null; reminderMinutes: number | null };
    newId(): string;
    upsert(course: Course): Promise<void>;
    remove(id: string): Promise<void>;
    setReminderMinutes(minutes: number | null): Promise<void>;
    reloadSemester(): Promise<void>;
  };
}
```

## 行为说明

下面按成员说明调用时需要注意的行为。

- **`phone`**：驱动 Copilot 的独立屏幕（`packages/sdk/src/phone.ts` 中的 `PhoneService`）。它供内置的 Copilot 插件使用，需要 `phone-control` 能力，本参考不展开说明。
- **`settings`**：列出和修改 App 与插件的全部设置，见[设置](#settings)。
- **`files.list` / `read` / `search`**：读取当前对话中附上的文档，见[附件](#files)。

- **`browser.open`**：在系统浏览器标签页（Android 上是 Custom Tabs，iOS 上是 SFSafariViewController）里打开页面。页面上的 App 链接（`weixin://`、`alipays://`）会唤起对应的 App，所以收银台页面可以一路跳转到微信支付或支付宝。这个方法在页面打开后就 resolve，无法得知支付是否成功。等用户回到 App 后，请重新读取一次结果，比如余额。
- **`files.pick`**：只有用户能选择文件。请在页面里响应用户点击时调用它，不要在 Agent 工具里调用。`types` 是 MIME 类型，支持通配符，例如 `['application/pdf', 'image/*']`。用户取消时 resolve 为 `[]`。选中的文件会复制到 App 缓存，你拿到的是文件引用（在本次 App 会话内有效的 URI），拿不到文件内容。
- **`crypto.sha256`**：对 UTF-8 文本计算 SHA-256，返回小写十六进制字符串。插件自己没有加密库，这个方法用来给请求签名。
- **`registry`**：只读地查看已安装的插件和工具。`tool(id)` 也能解析旧 id。
- **`docs`**：管理文档插件（`PLUGIN.md`），供 `plugins` 插件使用。`review` 为一个链接或一组文件打开 App 的授权面板，面板弹出后即 resolve，之后由用户在面板里决定。`source(id)` 返回已安装文档插件的文件，用来阅读或 fork；对其他插件返回 `null`。这一项是可选的，使用前请先判断它是否存在。
- **`remote`**：安装和移除远程插件，即通过 Model Context Protocol（MCP）连接的插件。供 `plugins` 插件使用。
- **`genui`**：`describeCatalog()` 以文本形式返回组件目录，可以直接放进工具描述。`checkSpec(spec)` 按组件目录校验一份 spec。
- **`notify.readiness` / `fix`**：`readiness` 告诉你提醒能否准时触发，涉及通知权限、精确闹钟和电池优化三项设置。`fix` 只能在用户点击时调用。系统设置页可能在用户还没改动时就返回，所以 App 回到前台时要再读一次 readiness。
- **`sms.awaitCode`**：用户允许读取下一条短信后，resolve 为短信里的验证码（基于 Android 的 SMS User Consent）。功能不可用、用户拒绝、识别不出验证码或等待超过 5 分钟时，返回 `null`。请在让服务发送短信之后立刻调用。
- **`scheduler`**：`Trigger`、`Action`、`Job` 的定义见 [scheduler](/docs/sdk/scheduler)。`runCheck` 立即执行一次检查任务。
- **`widgets.preview` / `resolve`**：填充小组件的绑定，返回它的 spec 将会看到的 state。`preview` 每次都重新获取数据；`resolve` 使用按缓存有效期（TTL，time to live）保存的缓存，传入 `force` 时强制刷新。
- **`widgets.catalog`**：列出已启用插件提供的原生小组件。
- **`todos`**：`source` 参数记录这次修改是谁做的。
- **`campus.request`**：需要 `campus-session` 能力，详见 [campus](/docs/sdk/campus)。
- **`campus.otp`**：如果用户绑定了 App 内置的令牌，返回当前的手机令牌验证码，否则返回 `null`。插件永远拿不到令牌的密钥本身。
- **`campus.otpStatus`、`otpBindStart`、`otpBindFinish`、`otpUnbindLocal`**：用于管理令牌，只应由内置令牌插件的页面调用。
- **`campus.openSignedIn`**：借助服务自己的登录跳转，在系统浏览器里以已登录状态打开该服务。URL 由宿主生成，插件看不到会话 token。服务不支持这种跳转时会 reject。
- **`ongoing`**：只有设备具备 `ongoing` 能力（Android）时才存在。请在用户操作时启动，用完后停掉。
- **`timetable.reloadSemester`**：日历插件保存学期信息后，调用它让宿主重新读取。

## 设置

`settings` 是宿主的设置注册表：用户在 App 中能修改的每一项设置，都在这一个列表里。设置页面和核心插件 `settings`（助手的入口）都使用它，所以在任一处修改，另一处都会同步显示。源码：`packages/sdk/src/settings.ts`。

```ts
type SettingValue = string | number | boolean | string[];

interface SettingInfo {
  /** `app.theme`、`plugin.copilot.enabled`、`copilot.apps` 等 */
  key: string;
  /** 所属的分组，用于列出（`app`、`ai`、插件名称等）。 */
  group: string;
  title: string;
  description?: string;
  /** `choice` 取 `options` 中的一个值；`list` 是字符串列表。 */
  kind: 'choice' | 'boolean' | 'text' | 'list';
  options?: { value: string; label: string }[];
  value: SettingValue | null;
  /** 机密或需要用户亲手完成的步骤：助手不能设置；`screen` 是它所在的页面。 */
  uiOnly?: boolean;
  /** 显示这项设置的页面路由。 */
  screen?: string;
}

interface SettingChange {
  key: string;
  before: SettingValue | null;
  after: SettingValue | null;
}

interface SettingsService {
  /** 所有设置及其当前值。 */
  list(): Promise<SettingInfo[]>;
  /** 按顺序应用修改。 */
  change(changes: { key: string; value: SettingValue }[]): Promise<SettingChange[]>;
  /** 打开某项设置所在的页面。 */
  open(key: string): void;
}
```

目前 App 列出的键：

| 键 | 类型 | 取值 |
| --- | --- | --- |
| `app.theme` | `choice` | `system`、`light`、`dark` |
| `app.language` | `choice` | `system`、`zh-Hans`、`en` |
| `app.timezone` | `text` | `auto`（跟随手机）或 IANA 时区，例如 `Asia/Shanghai` |
| `app.haptics` | `boolean` | |
| `ai.provider` | `choice` | 服务商 id，例如 `deepseek.api` |
| `ai.model` | `text` | 模型 id；服务商有固定模型列表时，只能取其中之一 |
| `voice.provider` | `choice` | 语音服务商 id，例如 `aliyun-bailian.realtime` |
| `plugin.<id>.enabled` | `boolean` | 核心插件没有这一项 |
| `plugin.<id>.permission.<effect>` | `choice` | `auto`、`ask`、`off`；只有带工具的插件才有 |
| `<plugin>.<name>` | 由插件决定 | `PluginDef.preferences` 中的每一项，例如 `copilot.enabled`、`copilot.apps`、`copilot.screenshots` |
| `ai.apiKey`、`voice.apiKey`、`campus.account`、`app.notifications` | `text`，`uiOnly` | 只有用户能设置；`open` 打开它们所在的页面 |

`change` 的行为：

- 先检查所有的键。只要有一个未知的键或 `uiOnly` 的键，整个调用就会失败，什么都不改。
- 然后按顺序应用修改。每个值都按它的条目校验（`choice` 必须是可选值之一，`boolean` 必须是 `true` 或 `false`，设置项按它的 `input` schema 校验）。值不合法时抛出一个带可读消息的 `Error`。
- 返回每个键修改前后的值（`before` 和 `after`）。

`open(key)` 跳转到这项设置的 `screen`，键不存在时抛出错误。请在响应用户时调用它，例如用户要求修改一项 `uiOnly` 设置时。

插件通过 [`PluginDef.preferences`](/docs/sdk/plugin#preferences) 添加自己的条目，而不是通过这个服务。

## 附件

除了 `pick`，`files` 还能读取用户在当前对话中附上的文档：PDF、Word、Excel、PowerPoint、录音转写和文本文件。宿主在手机上提取它们的文字。用户的消息以 `<attachment name=… kind=… id=… chars=…>` 的形式携带每个文档，文档较长时只内联开头部分；下面这些调用用来翻阅其余部分或在其中搜索。偏移量和长度都按提取出的文字的字符数计算。源码：`packages/sdk/src/files.ts`。

```ts
interface FileInfo {
  id: string;
  name: string;
  /** 'pdf' | 'docx' | 'xlsx' | 'pptx' | 'audio' | 'text' | …（由宿主定义） */
  kind: string;
  /** 提取出的文字的长度。 */
  chars: number;
  /** 页数、工作表数、幻灯片数或秒数（对应类型有这一项时）。 */
  units?: number;
}

interface FileReadResult extends FileInfo {
  /** 这一段的起始位置。 */
  offset: number;
  text: string;
  /** 继续读取的位置，读到末尾时为 null。 */
  next: number | null;
}

interface FileSearchResult {
  id: string;
  name: string;
  matches: { offset: number; snippet: string }[];
}

interface FilesService {
  /** 当前对话中附上的文档（最新的在前）。 */
  list(): Promise<FileInfo[]>;
  read(id: string, offset?: number, length?: number): Promise<FileReadResult>;
  search(id: string, query: string, max?: number): Promise<FileSearchResult>;
}
```

文档的文字属于第三方内容。返回这些文字的工具必须设置 `untrusted: true`，核心插件 `files` 的 `read` 和 `search` 就是这样做的。

## 上文用到的类型

下面是上文签名中出现、但在其他页面没有定义的类型。

```ts
type JobInput = { title: string; trigger: Trigger; action: Action; source: JobSource; enabled?: boolean; meta?: Record<string, unknown> };
type JobPatch = Partial<Pick<Job, 'title' | 'trigger' | 'action' | 'enabled' | 'meta'>>;
type CheckResult = { notified: boolean; value?: unknown; error?: string };

type ToolInfo = { id: string; pluginId: string; title: string; effect: ToolEffect };

type PluginInfo = {
  id: string;
  name: string;
  kind: 'system' | 'builtin' | 'remote';
  enabled: boolean;
  modes: Record<ToolEffect, 'auto' | 'ask' | 'off'>;
  tools: { id: string; title: string; effect: ToolEffect }[];
};

interface WidgetCatalogEntry {
  plugin: string;
  pluginName: string;
  widget: string;
  title: string;
  description: string;
  sizes: WidgetSize[];
  defaultSize: WidgetSize;
  /** 小组件配置的 JSON Schema（如果它接受配置）。 */
  config?: Record<string, unknown>;
}

interface OngoingOptions {
  title: string;
  body?: string;
  /** 活动结束的时间（epoch 毫秒）：显示为倒计时，到点后宿主自动停止。 */
  until?: number;
  /** 通知上停止按钮的文字（默认为「停止」）。 */
  stopLabel?: string;
  /** 用户点击停止（或系统结束服务）时调用。 */
  onStop?: () => void;
}

interface OngoingHandle {
  update(p: { title?: string; body?: string }): void;
  stop(): void;
}
```

## 示例：选择文件并上传

```ts
import type { HostServices } from '@pku-harness/sdk';

/** 在页面的按钮回调里调用：只有用户能选文件。 */
export async function pickAndSubmit(services: HostServices, hiddenFields: [string, string][]) {
  const [file] = await services.files.pick({ types: ['application/pdf'] });
  if (!file) return null; // 用户取消
  return services.campus.request('blackboard', {
    url: '/webapps/assignment/uploadAssignment?action=submit',
    method: 'POST',
    multipart: {
      fields: hiddenFields, // 提交表单里的隐藏字段（nonce、course_id、content_id…）
      files: [{ field: 'newFile_LocalFile0', name: file.name, mime: file.mime, uri: file.uri }],
    },
  });
}
```

这段代码是 `courses` 插件中提交作业流程的简化版。实际的流程是 `plugins/courses/src/api.ts` 里的 `submitAssignment`，移植自
pkucli 的 `crates/course`。它会先读取提交表单，拿到隐藏字段和新的 nonce，然后提交，最后重新读取作业页面，确认出现了这次提交记录。文件内容从不经过插件，宿主直接从选中文件的 URI 流式上传。


# SDK 参考 (/docs/sdk)

> `@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`](https://github.com/pkuinfo/pku-harness-plugins) 仓库的 `packages/sdk`
目录下。开发时，你直接在这个仓库的本地副本里工作，仓库的 bun workspace 和 `tsconfig.json` 会把
`@pku-harness/sdk` 解析到 `packages/sdk/src`。

```bash
git clone https://github.com/pkuinfo/pku-harness-plugins.git
cd pku-harness-plugins
bun install
```

App 把同一个仓库作为 git 子模块挂在 `plugins/`，所以你在这里写的插件也能直接在 App 里运行（见
[内置插件 → 在 App 中运行](/docs/build/bundled-plugin#run-it-in-the-app)）。

```ts
import { definePlugin, defineTool, type PluginScreenProps } from '@pku-harness/sdk';
```

所有内容都可以从包的根入口引入。插件语言的各个模块也可以通过 `@pku-harness/sdk/lang/<module>` 单独引入。

## 模块

下表列出 SDK 的源码文件、对应的参考页面和主要导出。

| 模块 | 页面 | 主要导出 |
| --- | --- | --- |
| `plugin.ts` | [plugin](/docs/sdk/plugin) | `definePlugin`、`defineTool`、`PluginDef`、`ToolDef`、`ToolContext`、`ToolEffect`、`Actor`、`Capability`、`KV`、`TurnInfo`、`DataSourceDef`、`ProviderDef`、`SpeechProviderDef`、`ToolAssessment`、`PluginTranslation`、`PluginLegacy`、`ContextInput`、`CONTEXT_MARK`、`Dynamic`、`resolveDynamic` |
| `plugin.ts` | [宿主服务](/docs/sdk/host-services) | `HostServices`、`JobInput`、`JobPatch`、`CheckResult`、`PluginInfo`、`ToolInfo`、`WidgetCatalogEntry`、`OngoingOptions`、`OngoingHandle` |
| `settings.ts` | [plugin](/docs/sdk/plugin#preferences)、[宿主服务](/docs/sdk/host-services#settings) | `definePreference`、`PluginPreferenceDef`、`SettingContext`、`SettingsService`、`SettingInfo`、`SettingChange`、`SettingValue` |
| `files.ts` | [宿主服务](/docs/sdk/host-services#files) | `FilesService`、`FileInfo`、`FileReadResult`、`FileSearchResult` |
| `speech.ts` | [plugin](/docs/sdk/plugin#speech-providers) | `openAITranscribe`、`cleanTranscript`、`speechErrorMessage` |
| `ui.ts` | [ui](/docs/sdk/ui) | `HostUI`、`HostComponents`、`HostTheme`、`LiveData`、`PluginScreenProps`、`PluginWidgetProps`、`Contributions`、`ScreenContribution`、`SettingsContribution`、`TabContribution`、`WidgetContribution`、`CommandContribution`、`AppLocale` |
| `genui.ts` | [genui](/docs/sdk/genui) | `specSchema`、`UISpec`、`SpecCheck` |
| `dashboard.ts` | [dashboard](/docs/sdk/dashboard) | `Widget`、`Binding`、`bindingSchema`、`WidgetSize`、`widgetSizeSchema`、`WidgetSource`、`widgetSourceSchema` |
| `scheduler/*` | [scheduler](/docs/sdk/scheduler) | `Trigger`、`Action`、`Condition`、`Job`、`JobRun`、各类 schema、重复规则引擎、`ScheduleInput` 及 `toTrigger`/`summarize`、`evaluate`、策略常量 |
| `notify.ts` | [notify](/docs/sdk/notify) | `NotifyReadiness`、`NotifyFixKind`、`deliveryBlocker` |
| `campus.ts` | [campus](/docs/sdk/campus) | `CampusService`、`CampusRequest`、`CampusResponse`、`CampusMultipart`、`PickedFile`、`CampusStatus`、`OtpCode`、`OtpStatus` |
| `cloud.ts` | [cloud](/docs/sdk/cloud) | `CloudManifest`、`PluginCloud`、`Channel`、`SecretLink`、`CloudError`、`isCloudError`、`defineCloudFunction` |
| `timetable.ts` | [timetable](/docs/sdk/timetable) | `Course`、`Semester`、`parseWeeks`、`formatWeeks`、`weekOf`、`classesOn`、`classStatus`、`courseReminderTrigger` |
| `todo.ts` | [todo](/docs/sdk/todo) | `Todo`、`TodoInput` |
| `format.ts` | [format](/docs/sdk/format) | `defineStrings`、`Localized`、`formatClock`、`formatLocalDate`、`formatRelative`、`formatDay`、`formatCountdown`、`plural` 等 |
| `pointer.ts` | [pointer](/docs/sdk/pointer) | `setPointer` |
| `lang/*` | [声明式插件](/docs/build/declarative-plugins) | `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` 做单元测试。


# notify (/docs/sdk/notify)

> NotifyReadiness 类型和 deliveryBlocker 函数，用于在界面上检查提醒和定时检查能否准时送达。

提醒和定时检查要准时送达，需要用户在系统里打开几项权限。这个模块提供的类型和函数可以帮插件界面查明缺了哪一项，并引导用户去打开。它们配合 `services.notify.readiness()`（读取当前状态）和 `services.notify.fix(kind)`（弹出系统请求或打开对应的系统设置页）使用。

源码：`packages/sdk/src/notify.ts`。

## 准时送达需要的条件

目前优先支持 Android。在 Android 上，准时送达需要满足以下条件：

- 通知权限。
- 「闹钟和提醒」特殊权限，也就是精确闹钟。Android 14 起这项权限默认是拒绝的。
- 关闭系统对本应用的电池优化。这一项只是建议，不打开也不会阻止提醒按时触发。

## 类型与函数

```ts
type NotifyPermission = 'granted' | 'undetermined' | 'denied';

interface NotifyReadiness {
  /** 'denied' 表示系统不会再弹出请求，只能到系统设置里打开。 */
  notifications: NotifyPermission;
  /** 是否允许精确闹钟（系统没有这项权限时恒为 true）。 */
  exactAlarms: boolean;
  /** 系统可能推迟本应用的后台任务（电池优化已开启）。 */
  batteryOptimized: boolean;
}

/** 用户可以修复的项目：弹出系统请求，或打开对应的系统设置页。 */
type NotifyFixKind = 'notifications' | 'exactAlarms' | 'battery';

/**
 * 返回第一个导致提醒无法准时送达的原因；没有阻碍时返回 null。
 * 电池优化只是建议（精确闹钟照样会触发），所以它永远不会被当作阻碍。
 */
function deliveryBlocker(r: NotifyReadiness): 'notifications' | 'exactAlarms' | null;
```

## 示例：显示修复按钮

只有确实有东西阻碍送达时，界面才需要显示修复按钮。`fix` 只能在用户点击时调用：

```tsx
import { deliveryBlocker, type NotifyReadiness, type PluginScreenProps } from '@pku-harness/sdk';
import { useEffect, useState } from 'react';

export function ReminderBanner({ host, services }: PluginScreenProps) {
  const { Button } = host.components;
  const [r, setR] = useState<NotifyReadiness | null>(null);
  useEffect(() => void services.notify.readiness().then(setR), [services]);
  const blocker = r && deliveryBlocker(r);
  if (!blocker) return null;
  return (
    <Button
      title={blocker === 'notifications' ? '允许通知' : '允许准时提醒'}
      variant="secondary"
      onPress={() => void services.notify.fix(blocker).then(setR)}
    />
  );
}
```

用户可能还没改任何设置就从系统设置页返回了，所以应用回到前台时，也要重新读取一次 readiness。


# plugin (/docs/sdk/plugin)

> 定义插件时用到的全部类型：definePlugin、defineTool、definePreference、PluginDef、ToolDef、ToolContext、效果、调用方、能力需求、KV、轮次信息、数据源、设置项、模型、语音和 OCR 服务商、翻译和旧 id。

每个内置插件都导出一个用 `definePlugin` 定义的对象，里面写明插件的名称、需要的能力、提供的工具和界面等。这一页列出这个对象和工具的全部字段，以及工具运行时收到的上下文。

源码：`packages/sdk/src/plugin.ts`。

## definePlugin

```ts
function definePlugin(def: PluginDef): PluginDef;
function defineTool<I extends z.ZodType, O>(def: ToolDef<I, O>): ToolDef;
function definePreference<T extends SettingValue>(def: PluginPreferenceDef<T>): PluginPreferenceDef<T>;
```

三个函数都原样返回参数，用途只是类型检查。`defineTool` 会根据 zod 的 `input` schema 推断出 `execute` 的入参类型；`definePreference` 让设置项的值类型和它的 `input` schema 保持一致。

## PluginDef

`PluginDef` 是插件对象本身。下面先给出完整的类型，再逐个说明字段。

```ts
interface PluginDef {
  id: string;
  name: string;
  description: string;
  version: string;
  maxAgentSteps?: number;
  icon?: string;
  core?: boolean;
  requires?: Capability[];
  cloud?: CloudManifest;
  preferences?: Record<string, PluginPreferenceDef<any>>;
  remote?: { url: string; server: string };
  defaultModes?: Partial<Record<ToolEffect, 'auto' | 'ask' | 'off'>>;
  scopes: string[];
  tools: Record<string, ToolDef>;
  dataSources?: Record<string, DataSourceDef>;
  providers?: Record<string, ProviderDef>;
  speech?: Record<string, SpeechProviderDef>;
  ocr?: Record<string, OcrProviderDef>;
  instructions?: Dynamic<string>;
  context?: (input: ContextInput) => Promise<string | undefined>;
  contributes?: Contributions;
  i18n?: { en?: PluginTranslation };
  legacy?: PluginLegacy;
}
```

<TypeTable
  type={{
    id: { type: 'string', required: true, description: '注册 id：小写字母、数字和连字符（`PLUGIN.md` 插件必须匹配 `^[a-z0-9][a-z0-9-]{1,40}$`）。所有工具 id 都以它为前缀。' },
    name: { type: 'string', required: true, description: '显示名称，用中文（英文写在 `i18n.en.name`）。' },
    description: { type: 'string', required: true, description: '一句话，中文。' },
    version: { type: 'string', required: true, description: '插件版本号，遵循 semver。' },
    maxAgentSteps: { type: 'number', description: '仍可填写但会被忽略：从 App 1.0.16 起，单次回复没有步骤上限（改为在回复进行中压缩上下文）。' },
    icon: { type: 'string', description: "宿主图标集里的图标名，如 'card'、'book'、'alarm'。" },
    core: { type: 'boolean', description: '属于 Harness 核心体验：始终启用，不能关闭。' },
    requires: { type: 'Capability[]', description: '插件需要设备提供什么；有不满足的需求时插件会被隐藏。' },
    cloud: { type: 'CloudManifest', description: "如何使用 PKU harness Cloud（云服务）。没有写 `optional: true` 时，还要在 `requires` 里列出 'cloud'。" },
    preferences: { type: 'Record<string, PluginPreferenceDef>', description: '插件自己的设置项，以 `<plugin id>.<name>` 列入宿主的设置注册表，用户和助手在同一处读取和修改。见[设置项](#preferences)。注意它和 `contributes.settings`（设置页上的入口行）不同。' },
    remote: { type: '{ url: string; server: string }', description: '宿主为已安装的远程插件（通过 Model Context Protocol，即 MCP 连接）填写，不要自己设置。' },
    defaultModes: { type: "Partial<Record<ToolEffect, 'auto' | 'ask' | 'off'>>", description: '每种效果的默认授权方式，用户可以修改。', default: '全部 auto' },
    scopes: { type: 'string[]', required: true, description: '插件会访问的校园服务或主机，展示给用户看。' },
    tools: { type: 'Record<string, ToolDef>', required: true, description: '插件的 API，键是工具名。' },
    dataSources: { type: 'Record<string, DataSourceDef>', description: '适合给小组件和定时检查用的读取工具。' },
    providers: { type: 'Record<string, ProviderDef>', description: '模型服务商（服务商插件用）。' },
    speech: { type: 'Record<string, SpeechProviderDef>', description: '语音输入使用的语音识别服务，以本地 id 为键（宿主中的 id 为 `<plugin>.<key>`）。见[语音服务商](#speech-providers)。' },
    ocr: { type: 'Record<string, OcrProviderDef>', description: '识别手机自己读不出文字的文档（没有文字层的扫描版 PDF），以本地 id 为键。只有用户附上这类文件、并且 `credentialFrom` 指定的服务商已有 Key 时才会调用。见 [OCR 服务商](#ocr-providers)。' },
    instructions: { type: 'Dynamic<string>', description: "追加到助手的系统提示词末尾。写短一些；提到工具时用模型侧名称（`plugin__tool`）。" },
    context: { type: '(input: ContextInput) => Promise<string | undefined>', description: '每轮 Agent 对话前调用，返回的文本会标记为数据，在这一轮展示给模型。每次请求都要消耗 token。' },
    contributes: { type: 'Contributions', description: '页面、设置项、标签页、小组件、命令。' },
    i18n: { type: '{ en?: PluginTranslation }', description: "清单中给用户看的字符串的英文版本。给模型看的文本不翻译。" },
    legacy: { type: 'PluginLegacy', description: '这个插件取代的旧 id，用来让已保存的数据继续可用。' },
  }}
/>

## ToolDef

工具是插件提供给助手、用户和调度器调用的函数。`tools` 里的每一项都是一个 `ToolDef`。

```ts
interface ToolDef<I extends z.ZodType = z.ZodType, O = unknown> {
  title: string;
  description: Dynamic<string>;
  input: I;
  effect: ToolEffect;
  resolveEffect?: (input: z.infer<I>, services: HostServices) => Promise<ToolEffect | ToolAssessment>;
  untrusted?: boolean;
  userOnly?: boolean;
  onDemand?: boolean;
  grant?: boolean;
  alwaysAsk?: boolean;
  serial?: boolean;
  dayScoped?: boolean;
  execute: (input: z.infer<I>, ctx: ToolContext) => Promise<O>;
}

/** 宿主观察到的操作对象，和模型给出的工具参数分开显示。 */
type ToolAssessment = {
  effect: ToolEffect;
  target?: { label: string; context?: string };
};
```

<TypeTable
  type={{
    title: { type: 'string', required: true, description: '展示给用户（聊天中的工具标签、审批、设置），用中文。' },
    description: { type: 'Dynamic<string>', required: true, description: '写给模型看：什么时候用、怎么用这个工具。写成函数时可以读取宿主信息。' },
    input: { type: 'z.ZodType', required: true, description: '宿主在运行 `execute` 之前校验。' },
    effect: { type: 'ToolEffect', required: true, description: "'read' | 'write' | 'money' | 'public'." },
    untrusted: { type: 'boolean', description: "工具会返回第三方写的文本。调用后，这一轮 Agent 对话会被标记为受污染（tainted）。远程插件的工具一律算作此类。" },
    userOnly: { type: 'boolean', description: '只能由用户在页面里运行：不提供给模型，助手和调度器的调用都会被拒绝。' },
    onDemand: { type: 'boolean', description: '很少用到的工具（例如写插件用的工具）：即使属于核心插件，也不在对话开始时提供给模型，等助手用 `plugins.use` 加载这个插件后才提供。这样每次请求都更小。' },
    resolveEffect: { type: '(input, services) => Promise<ToolEffect | ToolAssessment>', description: '根据当前的外部状态判断出的额外效果（例如 Copilot 的一次点按会点到什么），和 `effect` 一起检查。返回的 `target` 会作为审批提示的标题。' },
    grant: { type: 'boolean', description: '这个工具会给助手它原本没有的访问权限。助手的每次调用都要等用户点按，不受授权方式影响（`auto` 不会跳过，`off` 照样拒绝）；定时任务的调用会被拒绝。提示提供「仅本次允许」和「始终允许」，用户的回答以 `ctx.grant` 传入。' },
    alwaysAsk: { type: 'boolean', description: '助手的每次调用都要经过审批，不受授权方式影响；定时任务的调用会被拒绝。用于宿主无法根据观察到的目标来判断的操作。`resolveEffect` 应说明将要发生什么。' },
    serial: { type: 'boolean', description: '这个插件中标记为 serial 的工具一次只运行一个（包括审批），按模型发出的顺序执行。用于作用在同一份共享状态上的工具。' },
    dayScoped: { type: 'boolean', description: '结果描述的是当天（按 App 的时区）。小组件不能显示更早某天取得的缓存结果，离线时的兜底除外。' },
    execute: { type: '(input: z.infer<I>, ctx: ToolContext) => Promise<O>', required: true, description: '执行实际工作。失败时抛出一个 Error，消息要写得让用户能看懂。' },
  }}
/>

## ToolContext

宿主调用 `execute` 时会传入第二个参数 `ctx`。它说明这次是谁在调用（`actor`），并提供插件私有的键值存储 `kv` 和宿主服务 `services`。

```ts
interface ToolContext {
  /** 本次调用经过（可选的）原生分类后被批准的效果。 */
  effect?: ToolEffect;
  pluginId: string;
  actor: Actor;
  /** 助手在一轮对话中调用时才有值。 */
  turn?: TurnInfo;
  /** 本插件的私有存储。 */
  kv: KV;
  services: HostServices;
  /** 绑定到本插件的 PKU harness Cloud；在所有宿主版本都接入之前是可选的。 */
  cloud?: PluginCloud;
  /** 用户对 `grant` 工具提示的回答。用户直接调用时不设置。 */
  grant?: 'once' | 'always';
  /**
   * 本插件自己的某个模型服务商（`PluginDef.providers` 的键）的地址和 Key，不能取其他插件的。
   * 在所有宿主版本都接入之前是可选的。
   */
  provider?: (key: string) => Promise<{ baseURL: string; credential?: string }>;
  signal?: AbortSignal;
}

type Actor = 'user' | 'agent' | 'scheduler';

interface TurnInfo {
  sessionId?: string;
  /** 本轮中助手此前调用过不受信任的工具（或任何远程插件）。 */
  tainted: boolean;
  /** 用户在本轮自己发的消息中要求记住某件事。 */
  userAsked?: boolean;
  /** 本轮使用的模型能看图片（模型目录的 `inputModalities` 中有 'image'）。 */
  acceptsImages?: boolean;
}

interface KV {
  get<T>(key: string): Promise<T | undefined>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
}
```

`ctx.provider(key)` 返回插件自己的某个模型服务商的地址和 Key，也就是用户在「设置 → AI 服务」中填写的内容。调用同一个服务、用同一个 Key 的工具可以用它，例如 DeepSeek 插件的 `web_search` 用的就是 DeepSeek 对话的 Key。用户还没保存 Key 时 `credential` 为空，这时抛出一个 Error，告诉用户去哪里填写。插件读不到其他插件的服务商。

## 效果与能力需求

效果（`ToolEffect`）说明一个工具会产生什么后果，宿主据此决定调用前是否要征求用户同意。能力需求（`Capability`）说明插件需要设备具备什么条件。

```ts
type ToolEffect = 'read' | 'write' | 'money' | 'public';

type Capability =
  | 'network'          // 普通的互联网访问
  | 'campus-network'   // 只能从北大校园网访问的主机
  | 'campus-session'   // 经宿主发出的已登录校园 HTTP 请求（不会暴露凭据）
  | 'notifications'
  | 'background'       // 定期在后台运行
  | 'shell'            // 手机上永远不可用；需要它的插件必须远程运行
  | 'filesystem'
  | 'cloud'            // 已配置 PKU harness Cloud 服务；见 PluginDef.cloud
  | 'phone-control'    // 操作手机上的其他 App（Copilot）
  | 'ongoing';         // 常驻通知 / 前台服务（仅 Android）
```

另见[工具与效果](/docs/concepts/tools-and-effects)和[能力需求](/docs/concepts/capabilities)。

## 动态值

有些字段（如 `instructions` 和工具的 `description`）既可以写成固定的值，也可以写成函数。写成函数时，宿主在构建提示词时调用它并传入 `HostServices`，你可以据此按当前状态生成内容。`resolveDynamic` 对这两种写法统一求值。

```ts
type Dynamic<T> = T | ((services: HostServices) => T);
function resolveDynamic<T>(value: Dynamic<T>, services: HostServices): T;
```

## DataSourceDef

数据源指向插件里一个适合给小组件和定时检查使用的读取工具，并给出调用参数 `args` 和缓存时长 `ttlMs`。

```ts
interface DataSourceDef {
  title: string;
  /** 本插件内的工具名。 */
  tool: string;
  args?: Record<string, unknown>;
  ttlMs: number;
}
```

## 请求上下文

`PluginDef.context` 函数在每轮对话前被调用，收到的参数是 `ContextInput`。

```ts
interface ContextInput {
  /** 用户最新的一条消息。 */
  query: string;
  kv: KV;
  services: HostServices;
}

/** 用来撤回先前展示过的事实的上下文行标记。 */
const CONTEXT_MARK = { deleted: '[已删除]', corrected: '[更正]', arrow: ' → ' } as const;
```

当一条事实被删除或更正时，宿主会追加 `- [已删除] old` 或 `- [更正] old → new` 这样的行。它只在历史里仍然显示 `old` 的对话中追加，而且只追加一次。因此，事实文本本身不能含有这个箭头。

## PluginTranslation

插件清单中的名称、描述、标题等默认用中文写。`i18n.en` 用这个类型提供英文版本，没有写出的字段沿用中文。

```ts
type PluginTranslation = {
  name?: string;
  description?: string;
  /** 工具标题，以工具名为键。 */
  tools?: Record<string, { title?: string }>;
  widgets?: Record<string, { title?: string; description?: string }>;
  screens?: Record<string, { title?: string }>;
  /** 设置项，以它打开的页面为键。 */
  settings?: Record<string, { title?: string; subtitle?: string }>;
  /** 设置项（PluginDef.preferences）的标题和说明，以名称为键。 */
  preferences?: Record<string, { title?: string; description?: string; options?: Record<string, string> }>;
  /** `prompt`：提示词类命令的英文模板。 */
  commands?: Record<string, { description?: string; argHint?: string; aliases?: string[]; prompt?: string }>;
  providers?: Record<string, { name?: string; description?: string; credentialHint?: string; models?: Record<string, { name?: string; description?: string }> }>;
  speech?: Record<string, { name?: string; description?: string; credentialHint?: string; models?: Record<string, { name?: string; description?: string }> }>;
  dataSources?: Record<string, { title?: string }>;
  /** 用文字描述（而非主机名）的访问范围，以 `scopes` 中的原文为键。 */
  scopes?: Record<string, string>;
};
```

## 设置项

设置项是属于某个插件的设置，例如 Copilot 允许使用的 App。你在 `PluginDef.preferences` 中声明它，宿主就会把它列入设置注册表，键名为 `<plugin id>.<name>`，和 App 自己的设置放在一起。用户在插件的页面里修改它，助手通过核心插件 `settings` 修改它，两者都经过 `get` 和 `set`。宿主不需要任何改动。详见[架构 → 助手能操作一切](/docs/concepts/architecture#agent-operates-everything)。

源码：`packages/sdk/src/settings.ts`。

```ts
type SettingValue = string | number | boolean | string[];

interface PluginPreferenceDef<T extends SettingValue = SettingValue> {
  title: string;
  description?: string;
  kind: 'choice' | 'boolean' | 'text' | 'list';
  options?: { value: string; label: string }[];
  /** 校验新的值（来自助手或页面）。 */
  input: z.ZodType<T>;
  get(ctx: SettingContext): Promise<T>;
  set(ctx: SettingContext, value: T): Promise<void>;
  /** 显示这个设置项的页面路由（默认是插件的第一个页面）。 */
  screen?: string;
}

/** 设置项读写自己的值时能用的东西。 */
interface SettingContext {
  kv: KV;
  services: HostServices;
}
```

<TypeTable
  type={{
    title: { type: 'string', required: true, description: '显示在设置列表里，用中文；英文写在 `i18n.en.preferences.<name>.title`。' },
    description: { type: 'string', description: '一句话说明它改变什么。' },
    kind: { type: "'choice' | 'boolean' | 'text' | 'list'", required: true, description: '`choice` 取 `options` 中的一个值；`list` 是字符串列表。' },
    options: { type: '{ value: string; label: string }[]', description: '`choice` 类型的可选值。标签可以在 `i18n.en.preferences.<name>.options` 中翻译。' },
    input: { type: 'z.ZodType<T>', required: true, description: '在 `set` 运行前校验每个新值，校验失败时这次修改失败。' },
    get: { type: '(ctx: SettingContext) => Promise<T>', required: true, description: '读取当前值，通常来自 `ctx.kv`。' },
    set: { type: '(ctx: SettingContext, value: T) => Promise<void>', required: true, description: '写入校验过的值。也可以调用宿主服务，例如结束正在运行的会话。' },
    screen: { type: 'string', description: '显示这个设置项的 App 路由，供 `settings.open` 使用。默认是插件的第一个页面。' },
  }}
/>

设置项不是机密。不要把 API Key 或密码声明为设置项：助手能读取和修改每一个设置项。宿主自己的机密是标记为 `uiOnly` 的条目，只有用户能设置。

Copilot 插件这样声明它的截图开关：

```ts
import { definePlugin, definePreference } from '@pku-harness/sdk';
import { z } from 'zod';

import { loadCopilotVision, saveCopilotVision } from './preferences';

export const copilotPlugin = definePlugin({
  id: 'copilot',
  // …
  i18n: {
    en: {
      preferences: {
        screenshots: { title: 'Let the AI see screenshots', description: 'For apps that hide their contents from Copilot (Taobao, WeChat).' },
      },
    },
  },
  preferences: {
    screenshots: definePreference({
      title: '允许 AI 查看截图',
      description: '用于不向 Copilot 显示内容的 App（淘宝、微信）。',
      kind: 'boolean',
      input: z.boolean(),
      get: async (c) => (await loadCopilotVision(c.kv)).screenshots,
      set: async (c, screenshots) => { await saveCopilotVision(c.kv, { screenshots }); },
    }),
  },
});
```

这样，助手就能用 `settings__change` 和键名 `copilot.screenshots` 修改它。

## PluginLegacy

```ts
interface PluginLegacy {
  /** 现在由本插件承接的旧插件 id，例如 ['campus-card', 'netfee']。 */
  pluginIds?: string[];
  /** 旧的完整工具 id → 本插件中的工具名，例如 { 'campus-card.getBalance': 'cardBalance' }。 */
  tools?: Record<string, string>;
  /** 旧的 `<plugin>.<widget>` → 本插件 `contributes.widgets` 中的小组件键。 */
  widgets?: Record<string, string>;
}
```

合并或重命名插件之后，用它保留旧 id。宿主会把旧插件 id（设置、`/p/<old>/…` 页面、小组件）和旧工具 id 映射到新插件，一次性改写已保存的小组件和检查任务，并沿用原有设置，每种效果取最严格的授权方式。如果某个旧 id 对应的插件实际仍然安装着，宿主使用那个插件，不会用旧 id 映射遮盖它。

## 模型服务商

模型服务商为助手提供语言模型，例如 DeepSeek 或任何兼容 OpenAI 接口的服务。插件在 `providers` 中用 `ProviderDef` 描述一个服务商。

```ts
type ProviderAuth = 'apiKey' | 'account' | 'none';

interface ProviderDef {
  name: string;
  description: string;
  auth: ProviderAuth;
  defaultBaseURL: string;
  editableBaseURL?: boolean;
  models: ProviderModel[];
  defaultModel: string;
  /** API 支持的思考强度，从低到高，例如 DeepSeek 的 ['low', 'high', 'max']。用户在模型选择里选「自动」或其中一档。 */
  efforts?: readonly ('minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max')[];
  credentialHint?: string;
  listModels?: (config: ProviderConfig) => Promise<ProviderModel[]>;
  signIn?: () => Promise<string>;
  /** 用用户自己的凭据读取账户余额。 */
  balance?: (config: ProviderConfig) => Promise<ProviderAccount>;
  /** 返回一个 AI SDK 的 `LanguageModel`（类型写得比较宽松）。 */
  createModel: (config: ProviderConfig) => unknown;
}

interface ProviderConfig {
  baseURL: string;
  model: string;
  /** 来自宿主安全存储的 API key 或账户 token。 */
  credential?: string;
  /** 宿主提供的支持流式响应的 fetch（例如 expo/fetch）。 */
  fetch: typeof fetch;
}

interface ProviderModel {
  id: string;
  name?: string;
  description?: string;
  /** 上下文窗口大小，单位为 token。未知时按 128k 处理。 */
  contextWindow?: number;
  /** 只有列出 'image' 时才允许添加图片附件。 */
  inputModalities?: ('text' | 'image')[];
  pricing?: ModelPricing;
}

interface ModelPricing {
  currency: 'CNY' | 'USD';
  /** 每 100 万 token 的价格。 */
  inputCacheHit: number;
  inputCacheMiss: number;
  output: number;
  /** 服务商时区内的高峰时段：星期几（0 = 周日）和 [startHour, endHour)。 */
  peak?: { multiplier: number; utcOffsetMinutes: number; weekdays: number[]; hours: [number, number][] };
  /** 价格的出处（URL 和核对日期）。 */
  source?: string;
}

interface ProviderBalance { currency: string; total: number; granted?: number; toppedUp?: number }
interface ProviderAccount { available: boolean; balances: ProviderBalance[] }
```

服务商插件就是设置了 `providers` 的普通插件，通常不提供工具。下面是一个最小的例子。实际使用中的服务商插件可以参考插件仓库里的
`plugins/deepseek/src/index.ts` 和 `plugins/openai-compatible/src/index.ts`。

```ts
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { definePlugin } from '@pku-harness/sdk';

export const myProviderPlugin = definePlugin({
  id: 'my-provider',
  name: '我的模型',
  description: '接入 example.com 的模型。',
  version: '0.1.0',
  scopes: ['api.example.com'],
  tools: {},
  providers: {
    example: {
      name: 'Example',
      description: 'OpenAI-compatible models from example.com',
      auth: 'apiKey',
      defaultBaseURL: 'https://api.example.com/v1',
      models: [{ id: 'example-large', name: 'Example Large', contextWindow: 128_000 }],
      defaultModel: 'example-large',
      createModel: ({ baseURL, model, credential, fetch }) =>
        createOpenAICompatible({ name: 'example', baseURL, apiKey: credential, fetch })(model),
    },
  },
});
```

## 语音服务商

语音服务商把用户说的话转成文字，供对话框的[语音输入](/docs/manual/voice-input)使用。它和模型服务商类似：用户使用自己的 Key，录音从手机直接发送到 `baseURL`。插件在 `speech` 中用 `SpeechProviderDef` 描述每个服务，宿主中的 id 为 `<plugin>.<key>`。

实时服务实现 `stream`，用户说话时文字同步出现；只接受完整录音的服务实现 `transcribe`。使用 `transcribe` 时，宿主会在用户停顿处把录音切成小段陆续发送，所以用户说完时大部分已经转好。只有 `transcribe` 能处理作为附件的音频文件。

```ts
interface SpeechProviderDef {
  name: string;
  description: string;
  defaultBaseURL: string;
  editableBaseURL?: boolean;
  models: { id: string; name: string; description?: string }[];
  defaultModel: string;
  credentialHint?: string;
  /** 申请 Key 的网址，显示在输入框下方。 */
  keyURL?: string;
  /** 改用本插件中这个 id 的模型服务商的 Key，不需要单独的 Key。 */
  credentialFrom?: string;
  transcribe?: (config: SpeechConfig, audio: SpeechAudio, signal?: AbortSignal) => Promise<string>;
  stream?: (config: SpeechConfig, handlers: SpeechStreamHandlers) => Promise<SpeechStream>;
}

interface SpeechConfig {
  baseURL: string;
  model: string;
  /** 来自宿主安全存储的 API Key。 */
  credential?: string;
  /** 宿主提供的 fetch（在 FormData 中上传 `SpeechAudio.file`）。 */
  fetch: typeof fetch;
  /** 打开一个带请求头的 WebSocket（供在握手时鉴权的实时服务使用）。 */
  webSocket: (url: string, headers: Record<string, string>) => WebSocket;
}

/** 要转写的录音（除非 `mimeType` 另有说明，否则为 16 kHz 单声道 WAV）。 */
interface SpeechAudio {
  file: Blob;
  uri: string;
  name: string;
  mimeType: string;
  durationMs?: number;
}

interface SpeechStreamHandlers {
  /** 到目前为止的完整转写（已确认的文字加上尚未确定的结尾），替换上一次的结果。 */
  onText: (text: string) => void;
}

interface SpeechStream {
  /** 100 毫秒的 16 kHz 单声道 16 位小端 PCM，base64 编码。 */
  send: (pcmBase64: string) => void;
  /** 音频已结束：返回最终的转写结果。 */
  finish: () => Promise<string>;
  /** 放弃这次会话，不要结果。 */
  cancel: () => void;
}
```

`packages/sdk/src/speech.ts` 提供三个辅助函数：

- `openAITranscribe(config, audio, signal?)` 发送 `POST {baseURL}/audio/transcriptions`（multipart 中带 `file` 和 `model`），返回清理后的 `text`。硅基流动、OpenAI 和大多数兼容服务都使用这种格式，所以插件可以直接把它作为 `transcribe`。
- `cleanTranscript(text)` 去掉 `<|zh|>` 这类控制标记，并去除多余空白。
- `speechErrorMessage(status, body)` 把错误响应整理成 `"<status>: <message>"`。

下面是精简后的硅基流动插件：

```ts
import { definePlugin, openAITranscribe } from '@pku-harness/sdk';

export const siliconflowPlugin = definePlugin({
  id: 'siliconflow',
  name: '硅基流动',
  description: '用硅基流动的语音识别把语音输入转成文字（你自己的 API Key）。',
  version: '0.1.0',
  requires: ['network'],
  icon: 'mic',
  scopes: ['api.siliconflow.cn'],
  tools: {},
  speech: {
    asr: {
      name: '硅基流动',
      description: 'SenseVoice 与 TeleSpeech，国内可直接访问；文字按句子出现',
      defaultBaseURL: 'https://api.siliconflow.cn/v1',
      models: [
        { id: 'FunAudioLLM/SenseVoiceSmall', name: 'SenseVoice', description: '普通话、英语、粤语、日语、韩语' },
        { id: 'TeleAI/TeleSpeechASR', name: 'TeleSpeech', description: '方言识别更好' },
      ],
      defaultModel: 'FunAudioLLM/SenseVoiceSmall',
      credentialHint: '在 cloud.siliconflow.cn 创建的 API Key',
      keyURL: 'https://cloud.siliconflow.cn/account/ak',
      transcribe: openAITranscribe,
    },
  },
});
```

实时服务的写法见插件仓库中的 `plugins/aliyun-bailian/src/realtime.ts`。

如果语音服务和模型用的是同一个 Key（例如 DeepSeek），把 `credentialFrom` 设为插件自己 `providers` 中的某个键。宿主就不再显示 Key 输入框，而是把这个服务商的 Key 放进 `SpeechConfig.credential`；Key 还没填写时，语音输入页面会提示用户先到 AI 服务设置中填写。示例见 `plugins/deepseek/src/index.ts`。

## OCR 服务商

OCR 服务商负责识别手机自己读不出文字的文档，目前就是没有文字层的扫描版 PDF。插件在 `ocr` 中用 `OcrProviderDef` 描述每个服务。它总是使用插件自己某个模型服务商（`credentialFrom`）的地址和 Key，用户不需要额外设置。只有当用户附上这类文件、插件已开启、并且这个服务商已有 Key 时，宿主才会调用 `recognize`；否则文件仍像以前一样被拒绝。

```ts
interface OcrProviderDef {
  name: string;
  /** 使用哪个本插件模型服务商（`PluginDef.providers` 的键）的地址和 Key。 */
  credentialFrom: string;
  /** 按阅读顺序排列的识别结果，Markdown 格式，每页以 `## Page n` 标题开头。 */
  recognize: (
    config: { baseURL: string; credential: string; fetch: typeof fetch },
    doc: OcrDocument,
    signal?: AbortSignal,
  ) => Promise<string>;
}

/** 要识别的文档：用户附上的本地文件（`file` 可以放进 FormData 上传）。 */
interface OcrDocument {
  file: Blob;
  uri: string;
  name: string;
  mimeType: string;
}
```

返回的 Markdown 要在每页前加 `## Page n` 标题，这样助手可以像读其他文档一样引用和翻页。`recognize` 抛出错误时，附件会失败并提示「`<name>` 未能识别这个扫描版 PDF：`<message>`」，所以错误消息要写得让用户能看懂。`name` 会原样显示给用户。完整示例见 `plugins/deepseek/src/tools.ts` 中 DeepSeek 插件的 `deepseekOcr`。


# pointer (/docs/sdk/pointer)

> setPointer：按 JSON Pointer 路径往对象里写入一个值，用来把绑定的结果放进小组件的状态。

`setPointer` 按一条 JSON Pointer 路径（形如 `"/a/b"`）往对象里写入一个值。看板用它把每个绑定取到的数据放进小组件 spec 的状态里；你在插件里需要按路径更新嵌套对象时，也可以直接使用它。

源码：`packages/sdk/src/pointer.ts`。

```ts
/** 最小的 JSON Pointer 写入（"/a/b"），用来把绑定结果放进小组件状态。 */
function setPointer(target: Record<string, unknown>, pointer: string, value: unknown): Record<string, unknown>;
```

它的行为如下：

- 返回一个新对象，不改动 `target`。路径上的每一层对象都会复制一份。
- 路径上缺失的值或不是对象的值会被替换成 `{}`。
- 键名中的 `~1` 解码为 `/`，`~0` 解码为 `~`。
- 指针为空字符串（`""`）时，原样返回 `target`。

```ts
setPointer({ form: { amount: '50' } }, '/card/balance', 12.5);
// → { form: { amount: '50' }, card: { balance: 12.5 } }
```


# scheduler (/docs/sdk/scheduler)

> 调度器的类型和工具函数：Trigger、Action、Condition、Job 及其 zod schema，计算重复规则的纯函数，便于模型使用的 ScheduleInput 格式，条件判断，以及无人值守运行的限制常量。

调度器负责在指定时间运行任务，例如按时发出提醒，或者每天早上查一次校园卡余额，低于某个值时通知用户。这个模块定义了任务的数据结构，并提供计算重复时间、判断条件和检查运行频率的函数。插件创建定时任务，或者在界面上显示任务的下次运行时间时，会用到这些内容。

源码：`packages/sdk/src/scheduler/{types,recurrence,schedule-input,check,policy}.ts`。概念介绍见
[调度器](/docs/concepts/scheduler)。这里的代码都不依赖 React Native，所有时间都按设备本地时间计算。

## 类型与 schema

```ts
/** "HH:MM"，24 小时制，本地时间。 */
const timeOfDay = z.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, 'time must be HH:MM (24h)');

const triggerSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('at'), at: z.number() /* epoch ms */ }),
  z.object({
    type: z.literal('every'),
    unit: z.enum(['minute', 'hour', 'day', 'week']),
    interval: z.number().int().min(1).max(1000),
    /** 单位为 day/week 时：每天的时刻；默认为 `startAt` 的时刻。 */
    times: z.array(timeOfDay).min(1).max(24).optional(),
    /** 单位为 week 时：0 = 周日 … 6 = 周六；默认为 `startAt` 所在的星期几。 */
    weekdays: z.array(z.number().int().min(0).max(6)).min(1).max(7).optional(),
    startAt: z.number(), // epoch 毫秒；最早可能的一次
    /** 整个序列的总次数，达到后停止。 */
    count: z.number().int().min(1).optional(),
    /** 最晚可能的一次（包含在内），epoch 毫秒。 */
    until: z.number().optional(),
  }),
]);
type Trigger = z.infer<typeof triggerSchema>;

const conditionSchema = z.object({
  /** 数据源结果中的点分路径，例如 "balance"。为空表示整个结果。 */
  path: z.string().default(''),
  op: z.enum(['<', '<=', '>', '>=', '==', '!=', 'changed', 'always']),
  value: z.union([z.number(), z.string(), z.boolean()]).optional(),
});
type Condition = z.infer<typeof conditionSchema>;

const actionSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('notify'), title: z.string().min(1), body: z.string().optional(), url: z.string().optional() }),
  z.object({
    type: z.literal('check'),
    tool: z.string(),                                      // `<plugin>.<tool>`，只读
    args: z.record(z.string(), z.unknown()).optional(),
    condition: conditionSchema,
    title: z.string().min(1),                              // `{value}` 会替换成检查得到的值
    body: z.string().optional(),
    url: z.string().optional(),
  }),
  z.object({ type: z.literal('agent'), prompt: z.string().min(4).max(1000) }),
]);
type Action = z.infer<typeof actionSchema>;

type JobSource = 'user' | 'agent' | 'plugin';

type JobRun = {
  at: number;
  /** 这次运行对应的计划时间（手动运行时为 null）。 */
  scheduledAt: number | null;
  ok: boolean;
  notified: boolean;
  value?: unknown;
  error?: string;
  ms: number;
  manual?: boolean;
  /** `agent` 任务：助手的回复（保持沉默时为空）。 */
  output?: string;
  /** 未运行：延迟超过 MAX_LATE_MS。 */
  missed?: boolean;
};

type Job = {
  id: string;
  title: string;
  trigger: Trigger;
  action: Action;
  enabled: boolean;
  source: JobSource;
  runs: number;
  lastRunAt: number | null;
  nextRunAt: number | null;
  lastValue?: unknown;
  lastError?: string;
  history?: JobRun[];
  failures?: number;
  alertedAt?: number | null;
  meta?: Record<string, unknown>;
  createdAt: number;
  updatedAt: number;
};

/** 为 true 表示任务在 JS 中运行（检查或助手运行）；为 false 表示任务以预先设好的通知发出。 */
const runsInJs: (action: Action) => boolean;
```

任务的动作（Action）有三种：`notify` 直接发出通知；`check` 调用一个只读工具，满足条件时才通知；`agent` 让助手按一段提示词运行。

`timeOfDay`、`triggerSchema`、`conditionSchema` 和 `actionSchema` 都有导出。如果 `check` 任务调用的工具不是 `effect: 'read'`，宿主会拒绝运行这个任务。

## 重复规则引擎

这些纯函数根据触发器计算任务在什么时间运行。

```ts
type Occurrence = { at: number; index: number };

function nextOccurrence(trigger: Trigger, after: number): Occurrence | null;           // `after` 之后（不含）的第一次
function occurrencesAfter(trigger: Trigger, after: number, limit: number, before?: number): Occurrence[];
function lastOccurrence(trigger: Trigger, t: number): Occurrence | null;               // t 及之前的最后一次
function runsBy(trigger: Trigger, t: number): number;                                  // 到 t 为止的次数
function totalOccurrences(trigger: Trigger): number | null;                            // null 表示没有终点
function describeTrigger(trigger: Trigger, now?: number, locale?: 'zh-Hans' | 'en'): string;
function parseTime(t: string): [number, number];                                       // "08:30" → [8, 30]
const formatTime: (h: number, m: number) => string;                                    // (8, 5) → "08:05"
```

一个重复序列由一串长度相同的周期组成。周期可以是若干分钟或若干小时、一天，或者从周一开始的一周。每个周期里的时间槽都相同，由时刻和星期组合而成。早于 `startAt` 的时间槽会被跳过，其余的依次编号为 0、1、2……，直到达到 `count` 或 `until` 为止。夏令时切换不会让序列错位。

下面的例子是「从 10 月 20 日起，每 3 天早上 9 点一次，共 16 次」：

```ts
const every3Days16Times: Trigger = {
  type: 'every', unit: 'day', interval: 3, times: ['09:00'], count: 16,
  startAt: new Date(2026, 9, 20).getTime(),
};
occurrencesAfter(every3Days16Times, Date.now(), 3);   // 接下来三次
totalOccurrences(every3Days16Times);                  // 16
describeTrigger(every3Days16Times, Date.now(), 'en'); // 例如 "Every 3 days at 09:00 · 16 times"
```

## ScheduleInput（方便模型和表单使用）

`Trigger` 用 epoch 毫秒表示时间，模型和表单不容易直接填写。`ScheduleInput` 改用 `"YYYY-MM-DD HH:mm"` 格式的本地时间字符串，再用 `toTrigger` 转换成 `Trigger`。

```ts
const scheduleInputSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('once'), at: localDateTime }),
  z.object({
    type: z.literal('repeat'),
    unit: z.enum(['minute', 'hour', 'day', 'week']),
    interval: z.number().int().min(1),          // 每 N 个单位
    times: z.array(timeOfDay).optional(),       // day/week
    weekdays: z.array(z.number().int().min(0).max(6)).optional(),  // week：0 = 周日
    start: localDateTime.optional(),            // 默认为现在
    count: z.number().int().min(1).optional(),
    until: localDateTime.optional(),            // 包含在内
  }),
]);
// localDateTime: /^\d{4}-\d{2}-\d{2}[ T]\d{1,2}:\d{2}(:\d{2})?$/  ("YYYY-MM-DD HH:mm")
type ScheduleInput = z.infer<typeof scheduleInputSchema>;

function toTrigger(input: ScheduleInput, now?: number): Trigger;
function toScheduleInput(t: Trigger): ScheduleInput;
function parseLocal(s: string): number;      // 日期格式错误或不存在时抛出异常
function formatLocal(ms: number): string;    // "2026-10-20 08:00 周二"
function summarize(trigger: Trigger, now?: number, n?: number): {
  schedule: string;       // describeTrigger
  next: string[];         // 接下来 n 次，用 formatLocal 格式化
  total: number | null;
  finished: boolean;
};
```

建议把 `scheduleInputSchema` 用作工具的输入，并在工具结果里返回 `summarize` 的输出。这样模型拿到的是准确的运行时间，可以复述给用户确认。

## 条件

`check` 任务用这些函数从工具结果中取值，判断是否需要通知，并生成通知文字。

```ts
/** 从工具结果中读取点分路径（"data.balance"、"items.0.amount"）。 */
function getPath(value: unknown, path: string): unknown;
/** 判断检查得到的值是否满足条件。`previous` 是上一次运行得到的值。 */
function evaluate(cond: Condition, value: unknown, previous?: unknown): boolean;
/** 把通知文字中的 `{value}` 替换成检查得到的值（数字保留 2 位小数）。 */
function fillTemplate(template: string, value: unknown): string;
```

运算符 `changed` 只在存在上一次的值、并且与这次的值不同（按 JSON 比较）时为真。数值比较运算符会把数字字符串转成数字；无法转成数字的值，比较结果一律为假。

## 策略常量

这些常量和函数规定了任务在无人值守时的运行限制，例如最多能有多少个任务、检查任务最短多久运行一次、连续失败多少次后停用。

```ts
const MAX_ACTIVE_JOBS = 50;
const MIN_CHECK_GAP_MS = 15 * 60_000;
const MIN_AGENT_GAP_MS = 60 * 60_000;
const MAX_AGENT_JOBS = 10;
const AGENT_MAX_STEPS = 8;
const HISTORY_LIMIT = 20;
const FAIL_ALERT_AFTER = 2;
const DISABLE_AFTER = 10;
const ALERT_COOLDOWN_MS = 6 * 3_600_000;
const MAX_LATE_MS = 2 * 3_600_000;
const LATE_MS = 5 * 60_000;
const NO_REPLY = 'NO_REPLY';

function minGap(trigger: Trigger, now: number): number;                    // 一次性任务返回 Infinity
function checkScheduleProblem(trigger: Trigger, now: number): string | null; // 说明检查任务的计划为什么过于频繁
function recordRun(job: Job, run: JobRun): { patch: Pick<Job, 'history' | 'failures' | 'alertedAt' | 'enabled'>; alert: 'none' | 'failing' | 'disabled' };
const isLate: (run: Pick<JobRun, 'at' | 'scheduledAt'>) => boolean;
const isSilentReply: (text: string) => boolean;                            // 为空或以 NO_REPLY 开头
function agentJobHeader(job: { id: string; title: string; prompt: string }): string;
```

这些限制由宿主的调度引擎强制执行。插件可以导入这些常量，在用户创建任务之前就说明限制，避免用户创建后才发现不能运行。


# timetable (/docs/sdk/timetable)

> 课表的数据类型 Course 和 Semester，以及处理课表的纯函数：解析周次、计算教学周、列出某天的课、判断上课状态和生成课前提醒的触发器。

这个模块描述课表数据，并提供一组处理课表的工具函数。如果你的插件要显示今天的课、判断现在是第几教学周，或者给某门课设置课前提醒，就会用到它。课表数据本身通过 `services.timetable` 获取。

源码：`packages/sdk/src/timetable.ts`。

星期沿用 JavaScript 的编号：**0 = 周日 … 6 = 周六**。

## 类型

```ts
type Course = {
  id: string;
  name: string;
  location: string | null;
  teacher: string | null;
  weekday: number;          // 0 = 周日 … 6 = 周六
  start: string;            // "HH:MM"
  end: string;              // "HH:MM"
  /** 这门课上课的教学周；null 表示每周都上。 */
  weeks: number[] | null;
  /** 颜色标签在调色板中的序号（HostTheme.courseColor）。 */
  color: number;
  source: 'manual' | 'campus';
};

type Semester = { name: string; start: string /* "YYYY-MM-DD" */; weeks: number };
```

## 函数

下面都是纯函数，有单元测试覆盖。

```ts
/**
 * 解析周次表达式："1-16"、"1-16单"、"2-16双"、"1,3,5-8"、"单周"、"双周"、"全部"；也支持英文写法
 * （"1-15 odd"、"2-16 even"、"odd weeks"、"every week"）。null 表示每周。无法解析时抛出异常。
 */
function parseWeeks(expr: string, total?: number /* 20 */): number[] | null;

/** "1-16周"、"1-15单周"、"2,5,9周"（英文："Weeks 1-16"、"Weeks 1-15 odd"）。 */
function formatWeeks(weeks: number[] | null, locale?: 'zh-Hans' | 'en'): string;

/** 周次列表的等差规律（连续为步长 1，单双周为步长 2）；没有规律时返回 null。 */
function weekPattern(weeks: number[]): { first: number; last: number; step: number } | null;

/** 某个日期所在的教学周（从 1 开始）；没有学期信息时返回 null。 */
function weekOf(sem: Semester | null, date: Date): number | null;

/** 某个教学周里某个星期几对应的本地日期。 */
function dateOfWeek(sem: Semester, week: number, weekday: number): Date;

/** 某天要上的课，按开始时间排序。 */
function classesOn(courses: Course[], date: Date, sem: Semester | null): Course[];

/** 在当天的 `now` 时刻，这节课处于什么状态。 */
function classStatus(c: Course, now: Date): { state: 'before' | 'ongoing' | 'after'; progress: number; minutesToStart: number };

/**
 * 每周一次的提醒触发器，在上课前 `minutesBefore` 分钟触发。有学期信息时，序列从第一个教学周持续到
 * 最后一个教学周（单双周的步长为 2）；没有学期信息时，从现在起每周触发。
 */
function courseReminderTrigger(c: Course, minutesBefore: number, sem: Semester | null, now?: number): Trigger;
```

如果一门课的周次没有规律，`courseReminderTrigger` 会覆盖从第一周到最后一周的整段范围。

## 示例

```ts
const { courses, semester } = ctx.services.timetable.get();
const today = classesOn(courses, new Date(), semester);
const next = today.find((c) => classStatus(c, new Date()).state === 'before');

parseWeeks('1-15单');   // [1, 3, 5, …, 15]
formatWeeks([2, 4, 6, 8], 'en');  // "Weeks 2-8 even"
```


# todo (/docs/sdk/todo)

> 待办事项的数据类型 Todo 和 TodoInput，供 services.todos 使用。

这个模块定义了待办事项的数据类型。插件通过 `services.todos` 读取、添加或修改用户的待办时，用的就是这些类型。每条待办可以带一个提醒，提醒由调度器中的任务负责发出。

源码：`packages/sdk/src/todo.ts`。

```ts
type Todo = {
  id: string;
  title: string;
  notes: string | null;
  dueAt: number | null;
  doneAt: number | null;
  /** 调度器中对应的提醒任务（如果有）。 */
  jobId: string | null;
  createdAt: number;
};

type TodoInput = {
  title: string;
  notes?: string | null;
  dueAt?: number | null;
  /** 何时提醒；null 表示不提醒。使用触发器（Trigger）可以设置重复提醒。 */
  remind?: Trigger | null;
};
```

下面的例子添加一条周五 23:59 截止的待办，并在前一天晚上 8 点提醒：

```ts
// 周五 23:59 截止的待办，前一天晚上 8 点提醒
const due = new Date(2026, 9, 30, 23, 59).getTime();
await ctx.services.todos.add(
  { title: '交高数作业', dueAt: due, remind: { type: 'at', at: new Date(2026, 9, 29, 20, 0).getTime() } },
  'plugin',
);
```

## 完成与删除

调用 `setDone(id, true)` 把待办标为完成时，它的提醒任务会暂停；调用 `setDone(id, false)` 取消完成，提醒任务会重新启用。删除待办时，对应的提醒任务也会一起删除。


# ui (/docs/sdk/ui)

> 插件界面用到的类型：页面和小组件收到的 props，HostUI（组件、主题、导航、触感反馈、实时数据 hook），以及全部扩展类型（页面、设置项、标签页、小组件、命令）。

插件可以给 App 添加自己的界面，比如一个页面、一个设置项或一个看板小组件。这些界面用 React 编写，所需的组件、主题和数据 hook 都由宿主通过 `HostUI` 提供。这一页列出界面相关的全部类型。

源码：`packages/sdk/src/ui.ts`。使用指南：[界面扩展](/docs/build/ui)。

## Props

宿主渲染插件的页面时传入 `PluginScreenProps`，渲染插件的小组件时传入 `PluginWidgetProps`。

```ts
interface PluginScreenProps {
  host: HostUI;
  services: HostServices;
  /** 本插件的存储。 */
  kv: KV;
  /** 以用户身份运行 App 中的某个工具（校验和权限与助手调用时相同）。 */
  invoke(toolId: string, input?: Record<string, unknown>): Promise<unknown>;
  params: Record<string, string | undefined>;
  /** 本插件的云服务客户端（声明了 `PluginDef.cloud` 的插件才有）。 */
  cloud?: PluginCloud;
}

interface PluginWidgetProps {
  host: HostUI;
  services: HostServices;
  kv: KV;
  invoke(toolId: string, input?: Record<string, unknown>): Promise<unknown>;
  size: WidgetSize;
  /** 助手或用户选定的配置，按 `configSchema` 校验。 */
  config: Record<string, unknown>;
  cloud?: PluginCloud;
}
```

## HostUI

`HostUI` 是 props 中的 `host`。它提供宿主的组件、触感反馈、导航，以及读取主题、时间、语言和实时数据的 hook。

```ts
type AppLocale = 'zh-Hans' | 'en';

interface HostUI {
  components: HostComponents;
  haptics: { tap(): void; select(): void; success(): void; warning(): void };
  /** 跳转到 App 的某个路由或其他插件页面（`/p/<plugin>/<screen>`）。 */
  navigate(href: string): void;
  back(): void;
  /** 宿主的数据（任务、待办、小组件、课表）变化时重新渲染。 */
  useStoreVersion(): number;
  useTheme(): HostTheme;
  /** 当前时间，每隔 `intervalMs` 刷新一次。 */
  useNow(intervalMs?: number): Date;
  /** 关闭模态页面（从深链接打开时，改为跳转到给定的路由）。 */
  dismiss(fallback?: string): void;
  /** 切换到对话页，并向助手发送一条消息。 */
  ask(text: string): void;
  /** 只读工具的实时结果。`ttlMinutes` 默认为 5。 */
  useToolData<T = unknown>(tool: string, args?: Record<string, unknown>, opts?: { ttlMinutes?: number; path?: string }): LiveData<T>;
  /** AI 生成的小组件的 spec 状态，所有绑定都已填好。 */
  useWidgetData(widget: Pick<Widget, 'spec' | 'bindings'>): LiveData<Record<string, unknown>>;
  /** 同时获取多个绑定的实时值。 */
  useBindings(bindings: Binding[]): LiveData<unknown[]>;
  /** 强制刷新页面上所有实时查询（下拉刷新）；全部完成后 resolve。 */
  refreshAll(): Promise<void>;
  /** 把过去的时间戳格式化为「刚刚」「3 分钟前」「昨天 08:00」。 */
  formatAgo(ms: number, now?: number): string;
  /** 挂载期间禁止截屏和录屏；`brightness` 会调高屏幕亮度，方便扫码。 */
  useSecureDisplay(opts?: { brightness?: boolean }): void;
  /** App 语言（变化时重新渲染）。 */
  useLocale(): AppLocale;
  /** 当前构建没有剪贴板模块时为 undefined。 */
  clipboard?: { setString(text: string): Promise<void> };
  /** 用分享链接打开系统分享面板，插件看不到 URL。宿主支持云端频道之前为 undefined。 */
  shareLink?(link: SecretLink, opts?: { message?: string }): Promise<void>;
}
```

## LiveData

`useToolData`、`useWidgetData` 和 `useBindings` 返回 `LiveData`。它包含当前的值、加载状态和最近一次错误。

```ts
interface LiveData<T = unknown> {
  /** 只有拿到第一个值之前才是 'loading'；之后出错时保留上一次的值。 */
  status: 'loading' | 'error' | 'ready';
  value?: T;
  /** 最近一次刷新的错误（显示旧值时也会设置）。 */
  error?: string;
  /** 当前显示的值是什么时候获取的（epoch 毫秒）。 */
  updatedAt?: number;
  /** 正在请求中。 */
  fetching: boolean;
  /** 忽略 TTL，立即重新获取。 */
  refresh(): Promise<void>;
}
```

实时数据采用 stale-while-revalidate 策略：先显示缓存里的旧值，同时在后台获取新值。上一次的值在 App 重启后依然保留，打开页面时立即显示。

每个值都有一个缓存有效期（TTL，time to live）。宿主在以下情况重新获取：值已超过 TTL、页面获得焦点、App 回到前台、页面可见期间每隔一个 TTL，以及你调用 `refresh()` 时。小组件、页面和定时检查只要请求的是同一个工具和同样的参数，就共用一次请求和一条缓存。

## HostTheme

`host.useTheme()` 返回当前主题。插件应当使用这里的颜色、间距、圆角和字体样式，不要自己写死数值，这样界面才会随浅色和深色主题一起变化。

```ts
type TextVariant = 'display' | 'title' | 'headline' | 'body' | 'bodyStrong' | 'callout' | 'caption' | 'micro' | 'numberXL' | 'numberL' | 'numberM';

interface HostTheme {
  name: 'light' | 'dark';
  colors: Record<
    | 'bg' | 'surface' | 'surface2' | 'surface3' | 'border' | 'text' | 'textMuted' | 'textFaint'
    | 'accent' | 'accentMuted' | 'onAccent' | 'up' | 'upMuted' | 'down' | 'downMuted'
    | 'warn' | 'warnMuted' | 'info' | 'infoMuted' | 'elevated' | 'brand' | 'onBrand',
    string
  >;
  spacing: Record<'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl', number>;
  radius: Record<'sm' | 'md' | 'lg' | 'xl' | 'full', number>;
  typography: Record<TextVariant, Record<string, unknown>>;
  courseColor(index: number): { fill: string; ink: string };
  glass: { surface: string; rim: string; sheen: string };
  contentWidth: number;
}
```

## HostComponents

这些都是宿主传进来的 React 组件。`Style` 就是普通的 React Native 样式，会原样透传。

```ts
type Tone = 'default' | 'muted' | 'faint' | 'accent' | 'up' | 'down' | 'warn' | 'info' | 'onAccent';
type ChipTone = 'neutral' | 'accent' | 'up' | 'down' | 'warn' | 'info';

interface HostComponents {
  Screen: ComponentType<{ title: string; subtitle?: string; back?: boolean; trailing?: ReactNode; children: ReactNode; refreshControl?: ReactNode }>;
  Text: ComponentType<{ variant?: TextVariant; tone?: Tone; align?: 'left' | 'center' | 'right'; numberOfLines?: number; selectable?: boolean; style?: Style; children?: ReactNode }>;
  Button: ComponentType<{ title: string; onPress?: () => void; variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; size?: 'sm' | 'md' | 'lg'; icon?: string; loading?: boolean; disabled?: boolean; style?: Style }>;
  IconButton: ComponentType<{ icon: string; label: string; onPress?: () => void; variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; size?: number; disabled?: boolean }>;
  ListGroup: ComponentType<{ title?: string; footer?: string; children: ReactNode }>;
  ListRow: ComponentType<{ icon?: string; title: string; subtitle?: string; value?: string; accessory?: ReactNode; onPress?: () => void; chevron?: boolean; titleLines?: number }>;
  Chip: ComponentType<{ label: string; tone?: ChipTone; icon?: string }>;
  Surface: ComponentType<{ level?: 1 | 2 | 3; padded?: boolean; children?: ReactNode; style?: Style }>;
  EmptyState: ComponentType<{ icon: string; title: string; message?: string; action?: ReactNode }>;
  Skeleton: ComponentType<{ width?: number | `${number}%`; height?: number; rounded?: number }>;
  FadeIn: ComponentType<{ index?: number; children: ReactNode; style?: Style }>;
  Icon: ComponentType<{ name: string; size?: number; color?: string }>;
  Stat: ComponentType<{ label: string; value: number | null; prefix?: string; suffix?: string; decimals?: number; caption?: string; icon?: string }>;
  Switch: ComponentType<{ value: boolean; onValueChange: (v: boolean) => void; label?: string; disabled?: boolean }>;
  Checkbox: ComponentType<{ value: boolean; onValueChange: (v: boolean) => void; label: string }>;
  Segmented: ComponentType<{ options: { label: string; value: string }[]; value: string; onChange: (v: string) => void }>;
  Row: ComponentType<{ gap?: 'xs' | 'sm' | 'md' | 'lg'; align?: 'start' | 'center' | 'end' | 'between'; children: ReactNode }>;
  Column: ComponentType<{ gap?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'; children: ReactNode }>;
  Pressable: ComponentType<{ onPress?: () => void; onLongPress?: () => void; delayLongPress?: number; accessibilityLabel?: string; accessibilityRole?: string; accessibilityHint?: string; scaleTo?: number; haptic?: boolean; disabled?: boolean; style?: Style; children?: ReactNode }>;
  Field: ComponentType<{ label?: string; value: string; onChangeText: (v: string) => void; placeholder?: string; hint?: string; multiline?: boolean; secureTextEntry?: boolean; autoFocus?: boolean; keyboardType?: string; autoCapitalize?: 'none' | 'sentences' }>;
  DateTimeField: ComponentType<{ label: string; value: Date | null; onChange: (d: Date) => void; mode?: 'date' | 'time' | 'datetime'; placeholder?: string; onClear?: () => void }>;
  Stepper: ComponentType<{ value: number; onChange: (n: number) => void; min?: number; max?: number; suffix?: string; label: string }>;
  WeekdayPicker: ComponentType<{ value: number[]; onChange: (v: number[]) => void; multiple?: boolean }>;
  SheetScreen: ComponentType<{ title: string; children: ReactNode; primary: string; onPrimary: () => void; primaryDisabled?: boolean; loading?: boolean; danger?: string; onDanger?: () => void; secondary?: string; onSecondary?: () => void }>;
  Sparkline: ComponentType<{ values: number[]; tone?: 'accent' | 'up' | 'down' | 'info'; height?: number }>;
  Ring: ComponentType<{ value: number; label?: string; caption?: string; tone?: 'accent' | 'up' | 'down' | 'warn'; size?: number }>;
  Hourglass: ComponentType<{ period?: number; size?: number; tone?: 'accent' | 'up' | 'down' | 'warn' }>;
  GenUI: ComponentType<{ spec: Record<string, unknown>; onSubmit?: (form: Record<string, unknown>, label?: string) => void }>;
  SortableList: ComponentType<{ ids: string[]; rowHeight: number; onReorder: (ids: string[]) => void; renderRow: (id: string, handle: ReactNode) => ReactNode }>;
  PluginWidget: ComponentType<{ source: { plugin: string; widget: string; config?: Record<string, unknown> }; size: WidgetSize }>;
  Glass: ComponentType<{ children?: ReactNode; style?: Style; radius?: number; tone?: 'regular' | 'strong' | 'brand'; onPress?: () => void; onLongPress?: () => void; accessibilityLabel?: string; accessibilityRole?: 'button' | 'summary' | 'none'; haptic?: boolean }>;
  GlassEdges: ComponentType<{ radius?: number }>;
  QRCode: ComponentType<{ value?: string; link?: SecretLink; size?: number; ecl?: 'L' | 'M' | 'Q' | 'H' }>;
}
```

| 组件 | 说明 |
| --- | --- |
| `Screen` | 推入式页面的根组件：带标题、返回按钮和可选尾部元素的页头，支持下拉刷新。 |
| `SheetScreen` | 模态页面的表单面板布局：标题和关闭按钮、可滚动的内容区、一个主操作，以及可选的次要 / 危险操作。 |
| `Pressable` | 可点击的容器，带 App 统一的按压反馈。 |
| `Hourglass` | 沙漏按 Unix 时间对齐，在 `period` 秒内漏完，到边界时翻转，比如一个基于时间的一次性密码（TOTP）的刷新周期。 |
| `GenUI` | 用宿主的组件目录渲染一份[生成式界面 spec](/docs/sdk/genui)。 |
| `SortableList` | 纵向列表，用户拖动把手即可排序。每一行由插件自己渲染。 |
| `PluginWidget` | 挂载某个插件提供的小组件。出错时不会影响外部；对应插件关闭时会显示提示。 |
| `Glass` / `GlassEdges` | App 的面板材质。卡片和磁贴用 `Glass`；容器自己画 `colors.surface*` 底色时，用 `GlassEdges` 补上边缘和顶部高光。 |
| `QRCode` | 无论什么主题都是白底黑码。`link` 用来编码插件自己读不到的分享链接，和 `value` 同时设置时以 `link` 为准。 |

## Contributions

插件在 `PluginDef.contributes` 中声明要添加到 App 里的界面，类型是 `Contributions`。

```ts
interface Contributions {
  /** 挂载在 `/p/<plugin>/<screen>` 的页面。 */
  screens?: Record<string, ScreenContribution>;
  /** 显示在设置里的条目，点击后打开插件的某个页面。 */
  settings?: SettingsContribution[];
  /** 用一个页面填充 App 的某个标签页位置。 */
  tabs?: TabContribution[];
  /** 原生看板小组件，以 id 为键。 */
  widgets?: Record<string, WidgetContribution>;
  /** 斜杠命令，以名称为键（小写，/^[a-z][a-z0-9-]*$/）。 */
  commands?: Record<string, CommandContribution>;
}

interface ScreenContribution {
  title: string;
  component: ComponentType<PluginScreenProps>;
  /** 'modal' 页面在 `/m/<plugin>/<screen>` 打开（用于表单）；默认是 'push'，在 `/p/…` 打开。 */
  presentation?: 'push' | 'modal';
}

interface SettingsContribution {
  /** `contributes.screens` 中某个页面的键。 */
  screen: string;
  title: string;
  subtitle?: string;
  icon?: string;
}

type TabSlot = 'dashboard' | 'schedule';

interface TabContribution {
  slot: TabSlot;
  /** `contributes.screens` 中某个页面的键。 */
  screen: string;
}

interface WidgetContribution {
  title: string;
  /** 显示什么内容；助手根据它挑选小组件。 */
  description: string;
  sizes?: WidgetSize[];
  defaultSize?: WidgetSize;
  configSchema?: z.ZodType<Record<string, unknown>>;
  component: ComponentType<PluginWidgetProps>;
}

type CommandContribution = {
  /** 一行文字，显示在 / 菜单里。 */
  description: string;
  /** 菜单额外匹配的名称，比如中文（'余额'）。 */
  aliases?: string[];
  /** 参数的占位提示。写了这一项，表示命令接受输入。 */
  argHint?: string;
} & (
  | { /** 作为用户消息发送；`{{input}}` 会被替换为输入。 */ prompt: string }
  | {
      /** 在本地运行；返回的文本作为提示显示（不会发给模型）。 */
      run: (input: string, ctx: { services: HostServices; navigate: (href: string) => void; locale: AppLocale }) => Promise<string | void> | string | void;
    }
);
```

插件小组件可以由助手通过 `dashboard.addPluginWidget` 添加，也可以由用户从看板的小组件库里添加。小组件的数据请用
`host.useToolData` 加载，这样它的刷新方式和其他小组件一致。卡片的外框（标题、背景）由看板绘制，小组件只需画出内容。

命令名通常直接使用。只有两个插件用了同一个命令名时，命令才会加上 `/plugin:name` 前缀。