@my-life-buddies/buddy-runtime 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ MLB 搭子运行时。基于 [`@earendil-works/pi-agent-core`](https://www.npmjs
 ## 1. 安装
 
 ```bash
-npm install @my-life-buddies/buddy-runtime
+npm install @my-life-buddies/buddy-runtime typebox
 ```
 
 要求 Node.js ≥ 22.19。
@@ -67,6 +67,7 @@ await BuddyServer.start({
 | 参数 | 类型 | 说明 |
 |---|---|---|
 | `options.model` | `string`，必填 | 模型 id，取值见平台 `GET /cli/models`。进程内所有会话共用。没填，或 id 在运行时内置的模型目录中不存在时，启动失败 |
+| `options.welcome` / `options.errorReply` | `string`，可选 | 应用提供的静态问候，以及模型出错、空回复时发的兜底回复 |
 | `options.buddy` | `(conversation: Conversation) => BuddyOptions \| Promise<BuddyOptions>` | 搭子配置工厂。每场会话在第一条消息到达时调用一次 |
 
 ### 3.2 `BuddyOptions`
@@ -76,40 +77,74 @@ await BuddyServer.start({
 ```ts
 type BuddyOptions =
 	Pick<AgentOptions,
-		| "transformContext" | "beforeToolCall" | "afterToolCall"
+		| "beforeToolCall" | "afterToolCall"
 		| "shouldStopAfterTurn" | "prepareNextTurnWithContext"
 		| "thinkingBudgets" | "toolExecution">
-	& { initialState: Pick<AgentState, "systemPrompt"> & Partial<Pick<AgentState, "tools" | "thinkingLevel">> };
+	& { platformTools?: readonly PlatformToolName[]; initialState: Pick<AgentState, "systemPrompt"> & Partial<Pick<AgentState, "tools" | "thinkingLevel">> };
 ```
 
 | 字段 | 说明 |
 |---|---|
-| `initialState.systemPrompt` | 系统提示。静态内容；每回合变化的信息不应写在这里。工程目录下有 `resources/` 时，运行时在末尾追加资料清单 |
-| `initialState.tools` | 工具列表，类型为 pi 的 `AgentTool`。`label` 为必填，用作用户可见的状态行文案（空字符串表示不显示）；`execute` 返回值的 `details` 为必填（可为 `undefined`）；执行失败应直接抛出异常。工具名不得与内置工具或其他工具重复。先单独声明为 `AgentTool<typeof 参数 schema>` 再放入数组，`execute` 的参数才有类型；直接写在数组里时参数类型为 `unknown` |
+| `platformTools` | 要注册给模型的平台工具名单，默认 `[]`，见 3.3 |
+| `initialState.systemPrompt` | 系统提示。静态内容；每回合变化的信息不应写在这里。运行时在前面拼上平台的系统提示（平台对每场会话都一样的规则，比如消息开头的时间怎么读），两者之间空一行；`platformTools` 里有 `read_resource` 且有 `resources/` 时，运行时在末尾追加资料清单 |
+| `initialState.tools` | 工具列表，类型为 pi 的 `AgentTool`。`label` 为必填，用作用户可见的状态行文案（空字符串表示不显示）；`execute` 返回值的 `details` 为必填（可为 `undefined`）；执行失败应直接抛出异常。工具名不得与平台工具或其他工具重复。先单独声明为 `AgentTool<typeof 参数 schema>` 再放入数组，`execute` 的参数才有类型；直接写在数组里时参数类型为 `unknown` |
 | `initialState.thinkingLevel` | 思考级别，默认 `off`。模型不支持的级别在发请求前就近换成支持的一档。显式设了模型不支持的级别时，每场会话建立时打一条 warn |
-| `transformContext` | 历史裁剪。入参是这场会话完整的 Agent 历史，平台交代的场合也在其中，消息从哪来、长什么样见下方「4. 会话历史」一节；返回值只用于这一次模型请求，不改动历史；抛出异常时使用原历史 |
 | `beforeToolCall` / `afterToolCall` / `shouldStopAfterTurn` / `prepareNextTurnWithContext` / `thinkingBudgets` / `toolExecution` | 原样传递给 pi |
 
-密钥、会话历史、会话标识与插话策略由运行时统一管理，不对开发者开放。模型通过 `BuddyServer.start` 的 `model` 选择。
+密钥、会话历史与插话策略由运行时统一管理；工厂提供当前会话键与已绑定的平台能力，不传递 Token。模型通过 `BuddyServer.start` 的 `model` 选择。
 
-### 3.3 `Conversation`：给开发者调用的方法
+### 3.3 `Conversation` 与平台能力
 
-工厂拿到的对象。上面的属性和方法由开发者在代码里调用，不会注册给模型；要让模型用到，开发者自己包成工具放进 `initialState.tools`，见下方 `remember` 的例子。
+工厂拿到的对象，可在工具闭包中使用。会话之间的数据应以 `key` 隔离。
 
 ```ts
 interface Conversation {
-	readonly key: string;        // 会话键：私聊为 p_ 前缀，群聊为 g_ 前缀
+	readonly key: string;              // 会话键：私聊为 p_ 前缀，群聊为 g_ 前缀
 	readonly log: BuddyLogger;
+	readonly signal: AbortSignal;      // 会话删除、空闲淘汰、stop 时中止
+	readonly platform: PlatformClient; // 已绑好这场会话的平台能力
+}
+
+interface PlatformClient {
 	readonly memory: {
-		list(): Promise<MemoryEntry[]>;                   // 全量列出，按 key 字典序
-		write(key: string, text: string): Promise<void>;  // 覆盖写一条
-		delete(key: string): Promise<void>;               // 删一条，删不存在的也算成功
-	};
-	readonly dataAccess: {
-		query(request: { datasets: string[]; memberId?: string }): Promise<DatasetAccessResult[]>;  // 读用户授权的数据，见 3.4.2
+		list(): Promise<MemoryEntry[]>;
+		write(key: string, text: string): Promise<void>;
+		delete(key: string): Promise<void>;
 	};
+	readonly dataAccess: { query(request: { datasets: string[]; memberId?: string }): Promise<DatasetAccessResult[]> };
+	readonly proactive: { propose(request: ProactiveSubscriptionRequest): Promise<{ id: string; status: "pending" }> };
+	readonly widgets: WidgetClient;
+	readonly messages: { send(message: MLBMessageToWrite & { idempotencyKey: string }): void };
 }
+```
+
+`platform` 下的方法由开发者在代码里调用，会话键已经绑好，不需要传 Token 或拼 HTTP 路径。其中授权数据、小挂件、资料三项，运行时还提供了给模型用的工具，把工具名写进 `BuddyOptions.platformTools` 才注册：
 
+| 能力 | 代码里调用 | 给模型的工具 | 工具注册还要满足 |
+|---|---|---|---|
+| 记忆 | `platform.memory` | 无，要给模型用就自己包成工具，见 3.3.1 | 无 |
+| 授权数据 | `platform.dataAccess.query` | `data_access_query` | 声明过至少一个 Dataset |
+| 小挂件 | `platform.widgets` | `widget_create` / `widget_write` / `widget_read` / `widget_delete` / `widget_send` | 登记过至少一个小挂件类型 |
+| 资料 | 无 | `read_resource` | `resources/` 下有 `.md` |
+| 发消息 | `platform.messages.send` | 无 | 无 |
+| 主动服务建议 | `platform.proactive.propose`，见第 7 节 | 无 | 用户在 App 确认后生效 |
+
+- `platformTools` 默认 `[]`，一个平台工具都不注册。名单里有不认识或重复的名字时，这场会话起不来。
+- 注册的平台工具排在 `initialState.tools` 前面；和开发者的工具重名时，这场会话起不来。
+- 没写进名单的，照样可以在代码里调用 `platform`。
+
+```ts
+return {
+	platformTools: ["data_access_query", "widget_read"],
+	initialState: { systemPrompt: PERSONA, tools: [remember] },
+};
+```
+
+#### 3.3.1 记忆
+
+`platform.memory` 是这场会话的长期记忆，由平台保存，只在本会话内可见，会话删除时平台一并清除。`key` 为主题名（非空、不含空白与 `/`，最长 64 字），`text` 单条不超过 16KB；每场会话最多 64 条、合计不超过 256KB。`list` 全量列出，按 `key` 字典序；`write` 覆盖写一条；`delete` 删一条，删不存在的也算成功。超出配额、`key` 不合法或网络出错时直接抛出异常，异常信息为平台给出的原因；在工具的 `execute` 中调用时，模型能看到这个原因。
+
+```ts
 interface MemoryEntry {
 	key: string;        // 主题名
 	text: string;
@@ -117,9 +152,7 @@ interface MemoryEntry {
 }
 ```
 
-传入配置工厂，可在工具闭包中使用。会话之间的数据应以 `key` 隔离。
-
-`memory` 是这场会话的长期记忆，由平台保存，只在本会话内可见，会话删除时平台一并清除；会话键已经绑好，调用时无需传入。`key` 为主题名（非空、不含空白与 `/`，最长 64 字），`text` 单条不超过 16KB；每场会话最多 64 条、合计不超过 256KB。超出配额、`key` 不合法或网络出错时直接抛出异常，异常信息为平台给出的原因；在工具的 `execute` 中调用时，模型能看到这个原因。
+运行时不提供记忆工具，要让模型记东西，开发者自己包成工具：
 
 ```ts
 const REMEMBER_PARAMS = Type.Object({ topic: Type.String(), text: Type.String() });
@@ -133,7 +166,7 @@ await BuddyServer.start({
 			description: "把一条关于对方的印象记下来，同一主题覆盖旧的。",
 			parameters: REMEMBER_PARAMS,
 			execute: async (_id, { topic, text }) => {
-				await conversation.memory.write(topic, text);
+				await conversation.platform.memory.write(topic, text);
 				return { content: [{ type: "text", text: "记下了。" }], details: undefined };
 			},
 		};
@@ -142,42 +175,11 @@ await BuddyServer.start({
 });
 ```
 
-完整示例见 [examples/aunt-tu/](examples/aunt-tu/)：`taste_read` / `taste_write` 两个工具用 `memory` 记每个人爱吃什么、不爱吃什么。
-
-`dataAccess.query` 读取用户授权给搭子的数据，用法见 3.4.2。
-
-### 3.4 内置工具：运行时注册给模型
-
-以下工具由运行时注册到 Agent，排在开发者工具之前，由模型调用。开发者不需要注册，也不能再注册同名工具；系统提示中可按名称引用。
-
-| 工具 | 何时注册 | 做什么 |
-|---|---|---|
-| `read_resource` | 工程目录下有 `resources/`，且其中有 `.md` | 按资料清单里的相对路径读一篇资料 |
-| `data_access_query` | 搭子声明过至少一个 Dataset | 按需读取当前会话用户授权的数据；单次最多 8 个 Dataset，响应上限 512 KiB |
-| `widget_create` / `widget_write` / `widget_read` / `widget_delete` / `widget_send` | 搭子在平台上登记了小挂件类型 | 建小挂件、写 / 读 / 删记录、把小挂件发进聊天 |
-
-#### 3.4.1 资料
-
-资料放在工程目录下的 `resources/` 里，是一篇篇 `.md` 文件。运行时自动让模型按需读取，开发者不需要写代码。
-
-- 读哪些文件：进程启动时读一次 `resources/` 下全部 `.md`，包括子目录；跳过以 `.` 开头的文件与目录，以及 `node_modules`、`venv`、`.venv`、`__pycache__`；其他扩展名的文件忽略。资料改动后需重启进程。
-- 模型看到什么：系统提示末尾追加一份资料清单，列出每篇资料相对 `resources/` 的路径；模型调用 `read_resource` 并传入清单中的路径，读到该篇全文。
-- 没有资料时：`resources/` 不存在或其中没有 `.md`，不注册 `read_resource`，也不追加清单。
-
-```
-my-buddy/                  工程目录
-├─ package.json
-├─ resources/              资料目录
-│  └─ research/
-│     └─ 01-writings.md    清单中写作 research/01-writings.md
-└─ src/main.ts             入口脚本
-```
-
-完整示例见 [examples/stacy-sims/](examples/stacy-sims/)。
+完整示例见 [examples/aunt-tu/](examples/aunt-tu/)：`taste_read` / `taste_write` 两个工具用 `platform.memory` 记每个人爱吃什么、不爱吃什么。
 
-#### 3.4.2 授权数据
+#### 3.3.2 授权数据
 
-经用户同意，搭子可以读取用户授权数据。数据按 Dataset 分项，每项内容与字段固定，用户逐项授权。开发者要做的是声明需要哪些 Dataset；查询工具由运行时注册给模型，开发者的工具里也能直接查。
+经用户同意，搭子可以读取用户授权数据。数据按 Dataset 分项，每项内容与字段固定，用户逐项授权。开发者要做的是声明需要哪些 Dataset，然后让模型用 `data_access_query` 查，或者在自己的工具里查。会话与真实用户身份由平台绑定，搭子拿不到真实用户 id。
 
 **声明需要哪些数据**
 
@@ -213,20 +215,20 @@ my-buddy/                  工程目录
 
 **让模型去查**
 
-声明过至少一项数据，模型就有了 `data_access_query` 工具，工具说明里列着开发者声明的数据与用途。开发者可以在系统提示里写明什么时候查，例如「聊到作息时，先用 data_access_query 查 health.sleep」。
+`platformTools` 里有 `data_access_query`，且声明过至少一项数据，模型就有了这个工具，工具说明里列着开发者声明的数据与用途。开发者可以在系统提示里写明什么时候查，例如「聊到作息时，先用 data_access_query 查 health.sleep」。
 
 **在自己的工具里查**
 
-调用 `conversation.dataAccess.query`：
+调用 `conversation.platform.dataAccess.query`，不需要写进 `platformTools`：
 
 ```ts
-const [sleep] = await conversation.dataAccess.query({ datasets: ["health.sleep"] });
+const [sleep] = await conversation.platform.dataAccess.query({ datasets: ["health.sleep"] });
 if (sleep.status === "available") {
 	// sleep.data.items 是每天一条的睡眠记录
 }
 ```
 
-- `datasets`：一次最多 8 个。
+- `datasets`：一次最多 8 个；响应超过 512 KiB 时抛出异常，减少 Dataset 后重试。
 - `memberId`：私聊不传；群聊必须传，即群消息前缀 `[名字 #m_…]` 里的 `m_…`，查的是这位成员的数据。传错时直接抛出异常。
 
 **查询结果**
@@ -243,33 +245,109 @@ if (sleep.status === "available") {
 
 **数据只在这一轮回复里可见**
 
-一轮回复里只要查过授权数据，这一轮结束后，聊天记录和会话历史里这一轮的工具参数、工具结果与 thinking，都会换成「查了哪些数据、各是什么状态」，给用户看的回复照常保留。开发者自己写进 `memory` 或小挂件的内容不会被替换，不要把查到的数据写进去。
+一轮回复里只要查过授权数据，这一轮结束后，聊天记录和会话历史里这一轮的工具参数、工具结果与 thinking，都会换成「查了哪些数据、各是什么状态」，给用户看的回复照常保留。开发者自己写进记忆或小挂件的内容不会被替换，不要把查到的数据写进去。
 
-#### 3.4.3 小挂件
+#### 3.3.3 小挂件
+
+**登记类型**
 
 开发者通过平台 CLI 接口给搭子登记小挂件类型：`PUT /cli/buddies/:id/widget-types/:typeId/schema` 交 schema，每个模块写一句 `description` 给模型读，每条记录的形状是一份 JSON Schema；`PUT /cli/buddies/:id/widget-types/:typeId/page` 交展示页面，单个 HTML 文件。
 
-运行时在第一场会话建立时拉一次 `GET /internal/v1/widget-types`，按拉到的类型注册五个 `widget_*` 工具，工具说明里附上各类型的模块与字段；一个类型都没登记时不注册。这场会话里已有哪些小挂件，由平台写进消息流的会话上下文告诉模型。
+**让模型去用**
+
+`platformTools` 里写了哪几个 `widget_*`，运行时就注册哪几个：进程里第一次要用时拉一次 `GET /internal/v1/widget-types`，之后共用；工具说明里附上各类型的模块与字段；一个类型都没登记时一个也不注册。这场会话里已有哪些小挂件，由平台消息流里的 `context` 记录告诉模型。
+
+- 平台请求失败时工具抛出异常，模型看到的是「平台请求失败（HTTP 409），请查询最新状态后再操作」这样的提示，不带平台返回的具体原因。
+- `widget_create` 用 `widget-create:<toolCallId>` 作幂等键，同一次工具调用重发不会建出两个。
+- `widget_send` 把小挂件放进这场会话的发送队列就返回，不等平台确认送达。
+
+**在自己的工具里用**
+
+调用 `conversation.platform.widgets`，不需要写进 `platformTools`：
+
+```ts
+execute: async (toolCallId, params, signal) => {
+	const widgets = conversation.platform.widgets.withSignal(signal);
+	const { id } = await widgets.create({ type: "itinerary", title: "杭州行程", idempotencyKey: `itinerary:${toolCallId}` });
+	await widgets.write(id, { module: "days", recordId: "day-1", data: { city: "杭州" } });
+	widgets.send(id, { idempotencyKey: `itinerary-send:${toolCallId}` });
+	return { content: [{ type: "text", text: "行程建好了。" }], details: undefined };
+},
+```
+
+| 方法 | 做什么 | 平台接口 |
+|---|---|---|
+| `list()` | 列出这场会话里的小挂件，不带记录 | `GET /internal/v1/widgets` |
+| `create({ type, title, idempotencyKey? })` | 新建一个，回 `{ id }`；同一个 `idempotencyKey` 重复建回同一个 id | `POST /internal/v1/widgets` |
+| `read(id)` | 读整个小挂件，含各模块的记录 | `GET /internal/v1/widgets/:widgetId` |
+| `readModule(id, module)` | 读一个模块，回 `{ records }` | `GET /internal/v1/widgets/:widgetId/:module` |
+| `rename(id, title)` | 改标题，id 不变 | `PUT /internal/v1/widgets/:widgetId` |
+| `write(id, { module, recordId, data, expectedRevision? })` | 写一条记录，已存在就整条覆盖；带 `expectedRevision` 时版本号对不上，平台回 409 | `PUT /internal/v1/widgets/:widgetId/:module/:recordId` |
+| `deleteRecord(id, module, recordId)` | 删一条记录 | `DELETE /internal/v1/widgets/:widgetId/:module/:recordId` |
+| `setPresentation(id, { summary, imageMediaId })` | 设置聊天流里小挂件卡片的摘要（不超过 500 字）和封面图，`imageMediaId` 传空串去掉封面 | `PUT /internal/v1/widgets/:widgetId/presentation` |
+| `send(id, { idempotencyKey })` | 放进发送队列，按顺序发一条 `type: "widget"` 的消息 | `POST /internal/v1/messages` |
+| `withSignal(signal)` | 回一个同时受这个 signal 与会话 `signal` 控制的 Client | 无 |
+
+- 每个方法最后都可以传 `{ signal }`。
+- `data` 要符合登记的 schema，不符合时平台回 400。
+- 平台回非 2xx、网络出错、超过 30 秒或响应超过 4 MiB 时抛出 `PlatformRequestError`，异常只带 HTTP 状态码。写操作不自动重试，失败后先读一遍真实状态再决定。
 
 用法见 [examples/aunt-tu/](examples/aunt-tu/)。
 
+#### 3.3.4 资料
+
+资料放在工程目录（`package.json` 所在目录）下的 `resources/`。工程目录由入口脚本向上定位，与启动进程的工作目录无关。
+
+- 启动时递归读取 `.md`，跳过 `node_modules`、`venv`、`.venv`、`__pycache__` 及点开头的目录/文件；资料变更后需重启进程。
+- `platformTools` 里有 `read_resource` 时，系统提示末尾追加资料清单；模型通过清单中的相对路径读取内容。
+- 没有资料或名单里没有 `read_resource` 时，不注册 `read_resource`，也不追加资料清单。
+
+```
+my-buddy/                  工程目录
+├─ package.json
+├─ resources/              资料目录
+│  └─ research/
+│     └─ 01-writings.md    清单中写作 research/01-writings.md
+└─ src/main.ts             入口脚本
+```
+
+完整示例见 [examples/stacy-sims/](examples/stacy-sims/)。
+
+#### 3.3.5 发消息与图片
+
+**发消息**
+
+`platform.messages.send(message)` 把一条消息放进这场会话的发送队列，和模型的回复排在同一条队列里按顺序发（`POST /internal/v1/messages`），调用后立即返回，不等平台确认。
+
+- `message.type` 取 `message` / `tool` / `note` / `widget`；`idempotencyKey` 必填。
+- 会话已经删除或淘汰时直接抛出异常。
+
+**图片**
+
+用户发的图不需要开发者处理。平台在拉取消息时把图片内容一起给运行时，运行时把它放进会话历史，之后每次请求模型原样带上：
+
+- 图片在用户上传时由平台统一处理成 JPEG，最长边不超过 2048 px、不超过 5 MiB。
+- 图片消息交给模型时是一条 user 消息：正文前标着「[图片 #消息 id]」，用户配了文字接在后面，再跟图片本身。
+- 引用了别的消息的，开头加一行：引用文字写「[引用 发言人：原话]」，引用图片写「[引用 发言人的图片 #被引消息 id]」，模型按 id 对上是哪一张。
+- 转发进聊天记录卡的图，跟在卡里那条正文后面。
+- 图片已经读不到时换成「[图片无法读取]」；`model` 选的模型不支持看图时换成「[图片：当前模型不支持看图]」。
+
 ## 4. 会话历史：MLBMessage → AgentMessage → LLMMessage
 
 开发者不需要保存会话历史，也不需要把聊天里的消息换成模型消息，这些由运行时完成。每场会话的消息都保存在平台上，搭子进程重启后历史照样在。从平台上的 `MLBMessage` 到模型收到的 `LLMMessage`：
 
 ```
-MLBMessage[] → AgentMessage[] → transformContext() → AgentMessage[] → convertToLlm() → LLMMessage[] → LLM
-     ▲      (1)     │ ▲                (2)                                 (3)                         │
-     └─────(5)──────┘ └──────────────────────────────────────(4)───────────────────────────────────────┘
+MLBMessage[] → AgentMessage[] → convertToLlm() → LLMMessage[] → LLM
+     ▲      (1)     │ ▲              (2)                         │
+     └─────(4)──────┘ └──────────────────(3)─────────────────────┘
 ```
 
-1. 平台上的 `MLBMessage` 换成 pi 的 `AgentMessage`，追加进会话历史。一条消息只换一次：会话起来时换一遍平台上已有的全部消息，之后来一条换一条。什么消息换成什么，见 4.1。
-2. `transformContext()`：开发者可选。入参是完整的会话历史，返回值只用于这一次请求，不改动历史。
-3. `convertToLlm()`：运行时实现，开发者不能替换，做什么见 4.3。换出来的 `LLMMessage`（即 pi-ai 的 `Message`）连同 `systemPrompt` 与 `tools` 发给模型。
-4. 模型的回复，以及它调用工具得到的结果，直接追加进会话历史，不经过 (1)。
-5. 经 (4) 追加进历史的消息，运行时再换成 `MLBMessage` 写回平台；经 (1) 从平台来的不会写回。用户在聊天里看到的回复就是这一步写上去的。用过授权数据的那一轮，写回前先脱敏，见 3.4.2。搭子重启后，这些消息经 (1) 取回。
+1. 平台上的 `MLBMessage` 换成 pi 的 `AgentMessage`，追加进会话历史。一条消息只换一次：会话起来时换一遍平台上已有的全部消息，之后来一条换一条。图片、引用和聊天记录卡怎么换，见 3.3.5。
+2. `convertToLlm()`：运行时实现，开发者不能替换。每次请求模型都拿完整的会话历史来换：每条消息正文开头拼上它的时间，统一用 GMT、精确到秒，如「[2026-09-10 14:00:30 GMT] 」；运行时补的提醒（note）换成 user，其余原样，按原来的先后一条对一条，相邻的 user 不合并。换之前，运行时先在历史末尾接一条提醒，开头的时间就是现在，正文是「现在的时间（平台附注，不是谁说的话）」；这条只进这一次请求，不进会话历史。这些时间怎么读、用户所在时区去哪看，写在平台的系统提示里。换出来的 `LLMMessage`（即 pi-ai 的 `Message`）连同 `systemPrompt` 与 `tools` 发给模型。
+3. 模型的回复，以及它调用工具得到的结果，直接追加进会话历史，不经过 (1)。
+4. 经 (3) 追加进历史的消息，运行时再换成 `MLBMessage` 写回平台；经 (1) 从平台来的不会写回。用户在聊天里看到的回复就是这一步写上去的。用过授权数据的那一轮，写回前先脱敏，见 3.3.2。搭子重启后，这些消息经 (1) 取回。
 
-(1) 在消息到来时发生；(2)、(3) 在每次请求模型前都完整跑一遍，一轮回复里模型可能请求好几次，比如调完工具接着说，每次都从当时完整的会话历史重新算；(4)、(5) 在模型每说完一段、每跑完一步工具时发生。
+(1) 在消息到来时发生；(2) 在每次请求模型前都完整跑一遍，一轮回复里模型可能请求好几次，比如调完工具接着说，每次都从当时完整的会话历史重新算；(3)、(4) 在模型每说完一段、每跑完一步工具时发生。
 
 ## 5. 环境变量
 
@@ -278,12 +356,34 @@ MLBMessage[] → AgentMessage[] → transformContext() → AgentMessage[] → co
 | `MLB_BUDDY_ID` | 搭子 id，注册时由平台分配 |
 | `MLB_BUDDY_TOKEN` | 搭子令牌，注册时由平台分配 |
 
-网关地址无需配置，搭子连接测试平台 ecs-test（`http://47.116.168.81:8788`）。
+`MLB_GATEWAY_URL` 可覆盖平台网关。当前缺省为 ecs-test（`http://47.116.168.81:8788`）；本地测试必须显式配置回环地址及虚拟凭据，不能用正式搭子 Token 启动第二个进程。
 
 搭子的档案（名称、头像、简介）由平台保存：注册时通过 `POST /cli/buddies` 提交，修改通过 `PUT /cli/buddies/:id/meta`。搭子进程不监听端口、不接收入站请求。从非回环地址连接网关时，平台将其识别为 `<id>-dev` 分身，会话与正式身份隔离。
 
 ## 6. 开发
 
-- `npm run dev`：以 `node --watch` 启动，文件变更后自动重启。停止时需终止整个进程树（`pkill -f "node --watch .* src/main.ts"`），仅终止子进程会被父进程重新拉起。
+- 改完代码需要自动重启时，自行在 `package.json` 里用 `node --watch` 启动。
 - 会话消息拉取遇到临时网络错误时会主动指数退避重试（1 秒起步、最高 30 秒）；新的 SSE 通知会取消等待并立即重拉。
-- 运行时仓库：`npm test`、`npm run typecheck`、`npm run build`。
+
+## 7. 主动服务
+
+Runtime 消费平台 SSE `proactive {runId}`，领取 Run 后恢复对话、临时召回会话 Memory，并让模型按需查询授权 Dataset。数据查询携带短期执行令牌；最终 send/skip 结果由平台复核和落库，不经过普通消息写口。
+
+主动回合仅开放 `platformTools` 已选择的 `data_access_query` 和 `read_resource`，不会自动增加工具。临时 Trigger、Memory 注入和工具数据在结束后移除；普通用户消息到达会中止主动生成并优先回复。执行重试归平台，Runtime 不自行维护调度器。
+
+普通聊天中的开发者工具可提出订阅建议：
+
+```ts
+await conversation.platform.proactive.propose({
+  title: "每周复盘",
+  reason: "在约定时间结合最近聊天做一次简短复盘",
+  sources: ["schedule"],
+  eventTypes: ["schedule.due"],
+  allowedDataScopes: [],
+  schedule: { at: firstReviewAt, intervalMinutes: 7 * 24 * 60 },
+});
+```
+
+返回的订阅始终是 pending，用户在 App 确认后才能触发。`at` 为毫秒 UTC 时间戳；固定间隔不承诺夏令时地区的墙上时间不变。
+
+此能力要求匹配的 Proactive Server 版本。旧 Server 不支持这些端点，不会自动降级为直接主动写消息。

package/dist/conversation/agent.d.ts

@@ -1,11 +1,14 @@
 import { Agent } from "@earendil-works/pi-agent-core";
-import type { AgentEvent, StreamFn } from "@earendil-works/pi-agent-core";
+import type { AgentEvent, AgentMessage, AgentTool, StreamFn } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { MLBClient, WidgetType } from "../mlbClient.ts";
 import { DataAccessUsageTracker } from "../tools/dataAccess.ts";
 import type { Resource } from "../tools/resource.ts";
-import type { BuddyFactory, BuddyLogger, DataRequirement } from "../types.ts";
+import type { BuddyFactory, BuddyLogger, DataRequirement, MLBMessageToWrite } from "../types.ts";
 export interface AgentDeps {
+    signal?: AbortSignal;
+    enqueueMessage?: (message: MLBMessageToWrite) => void;
+    onPolicyStop?: () => void;
     key: string;
     buddyId: string;
     client: MLBClient;
@@ -26,6 +29,17 @@ export interface AgentDeps {
 export interface CreatedAgent {
     agent: Agent;
     dataAccessUsage: DataAccessUsageTracker;
+    proactiveReadTools: AgentTool[];
 }
 export declare function createAgent(deps: AgentDeps): Promise<CreatedAgent>;
+/**
+ * 每次请求模型时接在历史末尾那条 note 的正文；现在的时间由 convertToLlm 按这条 note 的 timestamp 拼在开头。
+ * 方括号时间怎么读、回复里别写，交代在平台的 system prompt 里（my-life-buddies-server 的 src/messages/systemPrompt.ts），
+ * 那边按「现在的时间」这几个字指认这条；改这里的正文或时间格式，那边一起改。
+ */
+export declare const CURRENT_TIME_NOTE = "\u73B0\u5728\u7684\u65F6\u95F4\uFF08\u5E73\u53F0\u9644\u6CE8\uFF0C\u4E0D\u662F\u8C01\u8BF4\u7684\u8BDD\uFF09";
+/** 历史副本：末尾接一条 now 时刻的 note，传进来的数组不改 */
+export declare function withCurrentTime(messages: AgentMessage[], now: number): AgentMessage[];
+/** 打日志用的副本：图片块的 data、请求体里 base64 的 data URL 换成字节数，其余原样 */
+export declare function withoutImageData(value: unknown): unknown;
 //# sourceMappingURL=agent.d.ts.map

package/dist/conversation/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/conversation/agent.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAa,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAErF,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAkB,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAA8B,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1G,MAAM,WAAW,SAAS;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACzC,sDAAsD;IACtD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACnD,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,WAAW,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACnD;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,EAAE,sBAAsB,CAAC;CACxC;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CA2GxE"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/conversation/agent.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAEnG,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAkB,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIrD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAA8B,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE7H,MAAM,WAAW,SAAS;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACtD,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACzC,sDAAsD;IACtD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACnD,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,WAAW,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACnD;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,EAAE,sBAAsB,CAAC;IACxC,kBAAkB,EAAE,SAAS,EAAE,CAAC;CAChC;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAqGxE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,iHAAuB,CAAC;AAEtD,uCAAuC;AACvC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAErF;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUxD"}

package/dist/conversation/agent.js

@@ -1,9 +1,11 @@
 // 一场会话的 Agent 怎么建：运行时先把该填的填好，开发者的配置叠上去。
-// 管：拼好交给开发者工厂的 Conversation（会话键、日志、绑好会话键的 memory / DataAccess），跑工厂拿配置；
-//     运行时工具（DataAccess、小挂件、有资料时的 read_resource）排在开发者工具前面并查重名；有资料时把资料清单接在 systemPrompt 末尾；
+// 管：拼好交给开发者工厂的 Conversation（会话键、日志、绑好会话键的平台能力），跑工厂拿配置；
+//     systemPrompt 按 平台的（GET /internal/v1/system-prompt，每场会话建 Agent 时拉一次）→ 开发者的 → 资料清单 拼，段间空一行；
+//     显式选中的平台工具排在开发者工具前面并查重名；选择 read_resource 时才追加资料清单；
 //     开发者显式设的 thinkingLevel 这个模型不支持时打一条 warn，写明支持哪几档、实际会怎么发；
-//     钩子叠加——开发者的 transformContext 包 try/catch 抛了用原历史；开发者的 beforeToolCall 包 try/catch 抛了按放行；其余直通；
-//     模型调用日志只记规模，不打印消息、Tool 结果和请求体，避免用户对话与授权数据进入日志。
+//     钩子叠加——开发者的 beforeToolCall 包 try/catch 抛了按放行；其余直通；
+//     transformContext 由运行时自己装、不开放给开发者：每次请求模型在历史末尾接一条写当前时间的 note，不进会话历史；
+//     普通回合沿用模型输入日志，图片换成字节数；主动回合只记规模，临时 Trigger、Memory 和查询结果不入日志。
 // 不管：Agent 建好之后的事（回合、事件分发在 index.ts）。
 import { Agent } from "@earendil-works/pi-agent-core";
 import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
@@ -11,36 +13,39 @@ import { agentMessagesToLLMMessages } from "./agentMessageLLMMessageConverter.js
 import { errorText } from "../log.js";
 import { dataAccessTool, DataAccessUsageTracker } from "../tools/dataAccess.js";
 import { readResourceTool, resourceCatalog } from "../tools/resource.js";
+import { createPlatformClient } from "../platform/client.js";
+import { validatePlatformTools, registerTools } from "../tools/registry.js";
 import { widgetTools } from "../tools/widgets.js";
 export async function createAgent(deps) {
     const dataAccessUsage = new DataAccessUsageTracker();
+    const lifetimeSignal = deps.signal ?? new AbortController().signal;
+    const platform = createPlatformClient({
+        client: deps.client, key: deps.key, signal: lifetimeSignal,
+        assertWritable: () => dataAccessUsage.assertWritable(),
+        enqueueMessage: message => { if (!deps.enqueueMessage)
+            throw new Error("消息队列不可用"); deps.enqueueMessage(message); },
+        queryDataAccess: ({ datasets, memberId }) => dataAccessUsage.query(deps.client, deps.key, datasets, memberId, lifetimeSignal),
+    });
     const conversation = {
-        key: deps.key,
-        log: deps.log,
-        memory: {
-            list: () => deps.client.memoryList(deps.key),
-            write: (key, text) => deps.client.memoryWrite(deps.key, key, text),
-            delete: (key) => deps.client.memoryDelete(deps.key, key),
-        },
-        dataAccess: {
-            query: ({ datasets, memberId }) => dataAccessUsage.query(deps.client, deps.key, datasets, memberId),
-        },
+        signal: lifetimeSignal, platform,
+        key: deps.key, log: deps.log,
+        proactive: platform.proactive,
     };
     const options = await deps.factory(conversation);
-    const [types, requirements] = await Promise.all([deps.widgetTypes(), deps.dataRequirements()]);
-    const dataTools = requirements.length === 0 ? [] : [dataAccessTool(deps.client, deps.key, dataAccessUsage, requirements)];
-    const tools = [
-        ...dataTools,
-        ...widgetTools(deps.client, deps.key, types),
-        ...(deps.resources.length > 0 ? [readResourceTool(deps.resources)] : []),
-        ...(options.initialState.tools ?? []),
-    ].map((tool) => dataAccessUsage.track(tool));
-    const seen = new Set();
-    for (const tool of tools) {
-        if (seen.has(tool.name))
-            throw new Error(`工具重名：${tool.name}`);
-        seen.add(tool.name);
-    }
+    const selected = validatePlatformTools(options.platformTools);
+    // 平台的 system prompt 拉失败就 throw：这场会话起不来，等下一条消息再重建
+    const [platformPrompt, types, requirements] = await Promise.all([
+        deps.client.systemPrompt(deps.key),
+        [...selected].some(name => name.startsWith("widget_")) ? deps.widgetTypes() : [],
+        selected.has("data_access_query") ? deps.dataRequirements() : [],
+    ]);
+    const resources = selected.has("read_resource") ? deps.resources : [];
+    const readTools = [
+        ...(requirements.length ? [dataAccessTool(deps.client, deps.key, dataAccessUsage, requirements, lifetimeSignal)] : []),
+        ...(resources.length ? [readResourceTool(resources)] : []),
+    ];
+    const available = [...readTools, ...(types.length ? widgetTools(platform.widgets, types) : [])];
+    const tools = registerTools(selected, available, options.initialState.tools ?? []).map(tool => dataAccessUsage.track(tool));
     const { log, key } = deps;
     const thinkingLevel = options.initialState.thinkingLevel;
     if (thinkingLevel !== undefined) {
@@ -55,8 +60,7 @@ export async function createAgent(deps) {
             });
         }
     }
-    const catalog = resourceCatalog(deps.resources);
-    const devTransform = options.transformContext;
+    const catalog = resourceCatalog(resources);
     const devBefore = options.beforeToolCall;
     const devAfter = options.afterToolCall;
     const agent = new Agent({
@@ -65,38 +69,30 @@ export async function createAgent(deps) {
         sessionId: `buddy:${deps.buddyId}:${key}`,
         initialState: {
             model: deps.model,
-            // 资料清单是静态的，接在开发者人设末尾；没资料时 resourceCatalog 回空串，人设原样
-            systemPrompt: catalog === "" ? options.initialState.systemPrompt : `${options.initialState.systemPrompt}\n\n${catalog}`,
+            // 平台的规矩在最前，开发者人设在中间，资料清单是静态的接在末尾；没资料时 resourceCatalog 回空串，不接
+            systemPrompt: [platformPrompt, options.initialState.systemPrompt, ...(catalog === "" ? [] : [catalog])].join("\n\n"),
             tools,
             thinkingLevel: options.initialState.thinkingLevel ?? "off",
         },
         steeringMode: "all",
         followUpMode: "all",
-        // 下面三个钩子按 pi 每次请求模型时的调用顺序排；只记录规模，不记录正文或请求体。
-        // 平台的场合交代是历史里的记录，不在这里插；这里只跑开发者的裁剪
-        transformContext: async (messages, signal) => {
-            log.info("transformContext 入参", { convoKey: key, messageCount: messages.length });
-            if (devTransform === undefined)
-                return messages;
-            let base = messages;
-            try {
-                base = await devTransform(messages, signal);
-            }
-            catch (e) {
-                log.warn("开发者的 transformContext 抛错，用原历史", { convoKey: key, error: errorText(e) });
-                base = messages;
-            }
-            log.info("开发者 transformContext 出参", { convoKey: key, messageCount: base.length });
-            return base;
-        },
+        // 下面三个钩子按 pi 每次请求模型时的调用顺序排：transformContext → convertToLlm → onPayload；普通回合出参和请求体全量打日志，主动回合只记规模。
+        // transformContext 的返回值只交给这一次请求，不写回会话历史；场合交代和图片本来就是历史里的记录，不在这里加
+        transformContext: async (messages) => withCurrentTime(messages, Date.now()),
         convertToLlm: (messages) => {
             const llmMessages = agentMessagesToLLMMessages(messages);
-            log.info("convertToLlm 出参", { convoKey: key, messageCount: llmMessages.length });
+            if (dataAccessUsage.isProactive())
+                log.info("Proactive 模型输入已构建", { convoKey: key, messageCount: llmMessages.length });
+            else
+                log.info("convertToLlm 出参", { convoKey: key, messages: withoutImageData(llmMessages) });
             return llmMessages;
         },
         // 只打日志、返回 undefined：返回别的值 pi-ai 会拿它顶替请求体发出去
-        onPayload: () => {
-            log.info("模型请求已构建", { convoKey: key });
+        onPayload: (payload) => {
+            if (dataAccessUsage.isProactive())
+                log.info("Proactive 模型请求已构建", { convoKey: key });
+            else
+                log.info("模型请求体", { convoKey: key, payload: withoutImageData(payload) });
             return undefined;
         },
         beforeToolCall: devBefore === undefined
@@ -113,12 +109,45 @@ export async function createAgent(deps) {
         afterToolCall: devAfter === undefined
             ? undefined
             : (context, signal) => dataAccessUsage.runForTool(context.toolCall.id, () => devAfter(context, signal)),
-        shouldStopAfterTurn: options.shouldStopAfterTurn,
+        shouldStopAfterTurn: options.shouldStopAfterTurn ? async (context, signal) => {
+            const stop = await options.shouldStopAfterTurn(context, signal);
+            if (stop)
+                deps.onPolicyStop?.();
+            return stop;
+        } : undefined,
         prepareNextTurnWithContext: options.prepareNextTurnWithContext,
         thinkingBudgets: options.thinkingBudgets,
         toolExecution: options.toolExecution,
     });
     agent.subscribe((event) => deps.onEvent(agent, event));
-    return { agent, dataAccessUsage };
+    return { agent, dataAccessUsage, proactiveReadTools: tools.filter((tool) => readTools.some((read) => read.name === tool.name)) };
+}
+/**
+ * 每次请求模型时接在历史末尾那条 note 的正文；现在的时间由 convertToLlm 按这条 note 的 timestamp 拼在开头。
+ * 方括号时间怎么读、回复里别写，交代在平台的 system prompt 里（my-life-buddies-server 的 src/messages/systemPrompt.ts），
+ * 那边按「现在的时间」这几个字指认这条；改这里的正文或时间格式，那边一起改。
+ */
+export const CURRENT_TIME_NOTE = "现在的时间（平台附注，不是谁说的话）";
+/** 历史副本：末尾接一条 now 时刻的 note，传进来的数组不改 */
+export function withCurrentTime(messages, now) {
+    return [...messages, { role: "note", text: CURRENT_TIME_NOTE, timestamp: now }];
+}
+/** 打日志用的副本：图片块的 data、请求体里 base64 的 data URL 换成字节数，其余原样 */
+export function withoutImageData(value) {
+    if (typeof value === "string") {
+        const marker = value.startsWith("data:") ? value.indexOf(";base64,") : -1;
+        return marker === -1 ? value : `${value.slice(0, marker)};base64,[${base64Bytes(value.slice(marker + 8))} 字节]`;
+    }
+    if (Array.isArray(value))
+        return value.map(withoutImageData);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const record = value;
+    if (record.type === "image" && typeof record.data === "string")
+        return { ...record, data: `[${base64Bytes(record.data)} 字节]` };
+    return Object.fromEntries(Object.entries(record).map(([name, field]) => [name, withoutImageData(field)]));
+}
+function base64Bytes(data) {
+    return Math.floor((data.length * 3) / 4) - (data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0);
 }
 //# sourceMappingURL=agent.js.map