@my-life-buddies/buddy-runtime 0.8.0 → 0.10.0

package/README.md

@@ -14,7 +14,7 @@ npm install @my-life-buddies/buddy-runtime typebox
 
 ### 1.2 注册搭子
 
-通过平台开发者接口 `POST /cli/buddies` 注册，提交名称、头像、简介，平台分配搭子 id 与令牌；之后改档案用 `PUT /cli/buddies/:id/meta`。可选的模型 id 查 `GET /cli/models`。
+通过平台开发者接口 `POST /cli/buddies` 注册，提交名称、头像、简介，平台分配搭子 id 与令牌；之后改档案用 `PUT /cli/buddies/:id/meta`。用哪个模型在 `initialState.model` 里选，见 2.2。可声明的数据能力由 Runtime 导出的 `DATA_ACCESS_CAPABILITIES` 提供。
 
 ### 1.3 搭子工程框架
 
@@ -26,8 +26,8 @@ my-buddy/
 ```
 
 ```ts
-import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { BuddyServer } from "@my-life-buddies/buddy-runtime";
+import type { AgentTool } from "@my-life-buddies/buddy-runtime";
 import { Type } from "typebox";
 
 const PLAN_MENU_PARAMS = Type.Object({ date: Type.String() });
@@ -44,9 +44,10 @@ const planMenu: AgentTool<typeof PLAN_MENU_PARAMS, undefined> = {
 };
 
 await BuddyServer.start({
-	model: "kimi-k3",
+	dataRequirements: [],
 	buddy: () => ({
 		initialState: {
+			model: "kimi-k3",
 			systemPrompt: "你是「小涂阿姨」——一位管做饭的阿姨……",
 			tools: [planMenu],
 		},
@@ -74,7 +75,7 @@ await BuddyServer.start({
 - 在自己电脑上连测试网关时，平台把这个进程当作 `<id>-dev` 分身，会话与正式搭子分开。
 - 改完代码想自动重启，在启动命令里加 `--watch`。
 
-完整示例：[examples/aunt-tu/](examples/aunt-tu/)（记忆、小挂件）、[examples/stacy-sims/](examples/stacy-sims/)（资料）。
+完整示例：[examples/aunt-tu/](examples/aunt-tu/)（提问、记忆、小挂件）、[examples/stacy-sims/](examples/stacy-sims/)（资料）。
 
 ## 2. 配置
 
@@ -82,51 +83,72 @@ await BuddyServer.start({
 
 连上平台开始处理消息，返回 `{ stop(): Promise<void> }`。
 
-| 参数 | 说明 |
-|---|---|
-| `model` | 必填，模型 id，取值见 `GET /cli/models`，进程内所有会话共用。没填或运行时不认识这个 id 时启动失败 |
-| `buddy` | 必填，`(conversation: Conversation) => BuddyOptions \| Promise<BuddyOptions>`，见 2.2、2.3 |
-| `errorReply` | 可选，模型出错或空回复时发的兜底回复 |
+```ts
+interface StartOptions {
+	// 必填。这只搭子需要的用户数据及用途，见 3.4；不需要时传 []
+	dataRequirements: { id: DataAccessDatasetId; purpose: string }[];
+
+	// 必填。每场会话建起来时调一次，返回这场会话的配置，见 2.2、2.3
+	buddy: (conversation: Conversation) => BuddyOptions | Promise<BuddyOptions>;
+}
+```
+
+Runtime 启动时只在本地校验 `dataRequirements`，不会额外调用接口注册声明。Runtime 根据自身导出的能力目录补齐标题、来源和 Schema 版本；实际调用 `data_access_query`、发送 HealthKit 权限卡或申请使用数据的主动服务时，会把完整声明随业务请求携带给平台。平台在该次请求中更新用途版本并校验 Grant。
 
 用户新加搭子、新建群时，搭子会先开口打个招呼，跟平时回复一样调模型、逐字出现。开场白怎么说，写在 system prompt 里。
 
-`buddy` 在每场会话收到第一条消息时调用一次。会话空闲 30 分钟被回收、或进程重启后，下一条消息会重新调用，所以闭包里的变量不能当长期存储，要记住的东西写进记忆（3.2）。
+`buddy` 在每场会话收到第一条消息时调用一次。会话空闲 30 分钟被回收、或进程重启后，下一条消息会重新调用，所以闭包里的变量不能当长期存储，要记住的东西写进记忆（3.3）。
 
 会话历史长到一定程度（超过 128K token，窗口小的模型按窗口的四分之一算）时，运行时在会话被回收后把早先的对话压成一份摘要写回平台，下次重建时模型看到的是「摘要 + 最近的原文」。开发者不用做任何事，也没有开关。
 
 ### 2.2 `BuddyOptions`
 
-`buddy` 的返回值。字段名和签名取自 pi-agent-core 的 `AgentOptions` / `AgentState`，详见 pi 的文档。
+`buddy` 的返回值。
 
 ```ts
-type BuddyOptions = Pick<AgentOptions,
-	| "beforeToolCall" | "afterToolCall"
-	| "shouldStopAfterTurn" | "prepareNextTurnWithContext"
-	| "thinkingBudgets" | "toolExecution"
-> & {
-	platformTools?: readonly PlatformToolName[];
-	proactiveTools?: readonly string[];
-	initialState: Pick<AgentState, "systemPrompt"> & Partial<Pick<AgentState, "tools" | "thinkingLevel">>;
-};
-```
+import type {
+	AfterToolCallContext,
+	AfterToolCallResult,
+	AgentTool,
+	BeforeToolCallContext,
+	BeforeToolCallResult,
+	ModelId,
+	ShouldStopAfterTurnContext,
+	ThinkingLevel,
+} from "@my-life-buddies/buddy-runtime";
+
+interface BuddyOptions {
+	// 必填。这场会话的初始状态
+	initialState: {
+		// 必填。模型 id，ModelId 是 "kimi-k2.6" | "kimi-k3" | "deepseek-v4-flash" | "deepseek-v4-pro"。每场会话可以选不同的模型
+		model: ModelId;
+
+		// 必填。人设与做事规则。为保证模型缓存，只放不随回合变化的内容
+		systemPrompt: string;
+
+		// 可选。模型只看得到这里的工具；平台工具从 conversation.tools 里取来放进去，见第 3 节
+		tools?: AgentTool[];
+
+		// 可选，默认 "off"。ThinkingLevel 是 "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"。
+		// 模型不支持的级别在请求时就近换成支持的一档，建会话时打一条 warn
+		thinkingLevel?: ThinkingLevel;
+	};
 
-| 字段 | 说明 |
-|---|---|
-| `initialState.systemPrompt` | 必填，人设与做事规则，只放不随回合变化的内容。模型实际收到的系统提示见第 4 节 |
-| `initialState.tools` | 可选，pi 的 `AgentTool` 数组 |
-| `initialState.thinkingLevel` | 可选，默认 `off`。模型不支持的级别在请求时就近换成支持的一档，建会话时打一条 warn |
-| `platformTools` | 可选，给模型注册哪些平台工具，默认 `[]`，见第 3 节 |
-| `proactiveTools` | 可选，主动回合里还能用哪些工具，默认 `[]`（一个都不给）。写工具名，`platformTools` 选中的和 `initialState.tools` 里自己的都行；写了没注册的名字建会话时抛异常。见 3.5 |
-| 其余字段 | 原样交给 pi；`beforeToolCall` 抛异常时按放行处理 |
+	// 可选。模型出错或一句话没说时发的兜底回复，用户和模型之后都看得到；主动回合不发
+	errorReply?: string;
 
-写工具时注意：
+	// 可选。工具执行前调用，context 里有这次的 toolCall、校验过的 args 和当前上下文。
+	// 返回 { block: true, reason } 时工具不执行，模型看到 reason；抛异常时工具也不执行，模型看到异常信息
+	beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
 
-- `label` 必填，是工具执行时用户看到的状态文案，空字符串表示不显示。
-- `execute` 的返回值必须带 `details`，可以是 `undefined`；失败直接抛异常，模型能看到异常信息。
-- 先单独声明为 `AgentTool<typeof 参数 schema>` 再放进数组，`execute` 的参数才有类型；直接写在数组里时参数类型是 `unknown`。
-- 工具名不能与平台工具或其他工具重复。
+	// 可选。工具执行完调用，context 里带着执行结果；返回的 content、details、isError 会替换结果里的同名字段，抛异常时结果换成异常信息
+	afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
 
-模型、密钥与会话历史由运行时管理，不在配置里。
+	// 可选。模型说完一步（这一步的工具也跑完）后调用，返回 true 就不再请求模型。
+	// 这一步发出了权限请求卡或题卡时，这一轮直接停下，不调它
+	shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext, signal?: AbortSignal) => boolean | Promise<boolean>;
+}
+```
 
 ### 2.3 `Conversation`
 
@@ -140,26 +162,43 @@ interface Conversation {
 	// 日志，每行开头带搭子 id
 	log: BuddyLogger;
 
+	// 平台工具，见第 3 节：运行时造好、绑好这场会话，挑要用的放进 initialState.tools
+	tools: {
+		resource_list: AgentTool;
+		resource_read: AgentTool;
+		ask_question: AgentTool;
+		data_access_query: AgentTool;
+		data_access_request: AgentTool;
+		data_access_read_result: AgentTool;
+		widget_create: AgentTool;
+		widget_write: AgentTool;
+		widget_read: AgentTool;
+		widget_delete: AgentTool;
+		widget_send: AgentTool;
+	};
+
 	// 资料，见 3.1：resources/ 里的 .md，进程启动时读好，所有会话共用
-	resources: {
+	resource: {
 		list(): string[];
 		read(file: string): string;
 	};
 
-	// 记忆，见 3.2：这场会话的长期记忆，存在平台上
+	// 记忆，见 3.3：这场会话的长期记忆，存在平台上
 	memory: {
 		list(): Promise<MemoryEntry[]>;
 		write(key: string, text: string): Promise<void>;
 		delete(key: string): Promise<void>;
 	};
 
-	// 授权数据，见 3.3：私聊不传 memberId，群聊传消息前缀里的 m_…
+	// 授权数据，见 3.4：私聊不传 memberId，群聊传消息前缀里的 m_…
 	dataAccess: {
 		query(request: { datasets: string[]; memberId?: string }): Promise<DatasetAccessResult[]>;
+		request(input: DataAccessRequestInput & { idempotencyKey: string }): Promise<void>;
+		readResult(requestId: string): Promise<DataAccessReadResult>;
 	};
 
-	// 小挂件，见 3.4
-	widgets: {
+	// 小挂件，见 3.5
+	widget: {
 		list(): Promise<WidgetSummary[]>;
 		create(input: { type: string; title: string; idempotencyKey?: string }): Promise<{ id: string }>;
 		read(id: string): Promise<Widget>;
@@ -175,32 +214,44 @@ interface Conversation {
 		send(id: string, options: { idempotencyKey: string }): void;
 	};
 
-	// 主动服务，见 3.5：提订阅建议，用户在 App 里确认后才生效
+	// 主动服务，见 3.6：propose 提订阅建议，用户在 App 里确认后才生效；isRunning 判断现在是不是主动回合
 	proactive: {
 		propose(request: ProactiveSubscriptionRequest): Promise<{ id: string; status: "pending" }>;
+		isRunning(): boolean;
 	};
 }
 ```
 
-`memory`、`dataAccess`、`widgets`、`proactive` 已经绑好这场会话，直接调用，不用传令牌或拼接口路径。
+`tools`、`memory`、`dataAccess`、`widget`、`proactive` 已经绑好这场会话，直接用，不用传令牌或拼接口路径。
 
 ## 3. 平台能力
 
-| 能力 | `conversation` 对象方法 | 默认注册成的模型工具 | 默认注册成模型工具的条件 |
-|---|---|---|---|
-| 资料 | `conversation.resources.list` / `conversation.resources.read` | `resource_read` | platformTools 声明 && `resources/` 下有 `.md` |
-| 记忆 | `conversation.memory` | 无，默认不注册成模型工具，开发者可以根据具体场景，注册成适合场景需要的模型工具 | — |
-| 授权数据 | `conversation.dataAccess.query` | `data_access_query` | platformTools 声明 && 声明过至少一个 Dataset |
-| 小挂件 | `conversation.widgets.list` / `conversation.widgets.create` / `conversation.widgets.read` / `conversation.widgets.readModule` / `conversation.widgets.rename` / `conversation.widgets.write` / `conversation.widgets.deleteRecord` / `conversation.widgets.delete` / `conversation.widgets.setPresentation` / `conversation.widgets.send` | `widget_create` / `widget_write` / `widget_read` / `widget_delete` / `widget_send` | platformTools 声明 && `widgets/` 下有小挂件 |
-| 主动服务 | `conversation.proactive.propose` | 无 | — |
+| 能力 | `conversation` 对象方法 | 模型工具（`conversation.tools` 上） |
+|---|---|---|
+| 资料 | `conversation.resource.list` / `conversation.resource.read` | `resource_list` / `resource_read` |
+| 提问 | 无 | `ask_question` |
+| 记忆 | `conversation.memory` | 无，开发者可以根据具体场景，自己组装成适合的模型工具 |
+| 用户授权数据 | `conversation.dataAccess.query` / `conversation.dataAccess.request` / `conversation.dataAccess.readResult` | `data_access_query` / `data_access_request` / `data_access_read_result` |
+| 小挂件 | `conversation.widget.list` / `conversation.widget.create` / `conversation.widget.read` / `conversation.widget.readModule` / `conversation.widget.rename` / `conversation.widget.write` / `conversation.widget.deleteRecord` / `conversation.widget.delete` / `conversation.widget.setPresentation` / `conversation.widget.send` | `widget_create` / `widget_write` / `widget_read` / `widget_delete` / `widget_send` |
+| 主动服务 | `conversation.proactive.propose` / `conversation.proactive.isRunning` | 无 |
+
+```ts
+buddy: (conversation) => ({
+	initialState: {
+		model: "kimi-k3",
+		systemPrompt: PERSONA,
+		tools: [conversation.tools.resource_list, conversation.tools.resource_read, conversation.tools.ask_question, ...myTools],
+	},
+}),
+```
 
 ### 3.1 资料
 
-把 `.md` 资料放进工程目录（`package.json` 所在目录）下的 `resources/`，`platformTools` 写上 `resource_read`，模型就能按需读。
+把 `.md` 资料放进工程目录（`package.json` 所在目录）下的 `resources/`，把 `conversation.tools.resource_list` 和 `conversation.tools.resource_read` 放进 `initialState.tools`，模型先列出有哪些资料，再按需读。
 
 - 工程目录从入口脚本往上找，与启动时的工作目录无关。
 - 启动时递归读取 `.md`，跳过 `node_modules`、`venv`、`.venv`、`__pycache__` 与点开头的文件和目录；资料改了要重启进程。
-- 系统提示末尾追加资料清单，模型按清单里的相对路径读。没有资料或没选 `resource_read` 时，不注册工具，也不追加清单。
+- `resource_list` 列出全部资料的相对路径，`resource_read` 按路径读一篇。没有资料时 `resource_list` 回「没有资料」。
 
 ```
 my-buddy/                  工程目录
@@ -213,7 +264,7 @@ my-buddy/                  工程目录
 
 **在自己的代码里用**
 
-调用 `conversation.resources`，不需要写进 `platformTools`：
+调用 `conversation.resource`，不需要把这两个工具放进 `initialState.tools`：
 
 | 方法 | 做什么 |
 |---|---|
@@ -221,7 +272,7 @@ my-buddy/                  工程目录
 | `read(file)` | 读一篇的正文，`file` 照 `list()` 给的路径原样填；没有这篇时抛异常 |
 
 ```ts
-const notes = conversation.resources.read("research/01-writings.md");
+const notes = conversation.resource.read("research/01-writings.md");
 ```
 
 - 两个方法都是同步的，读的是进程启动时读好的那份。
@@ -229,7 +280,19 @@ const notes = conversation.resources.read("research/01-writings.md");
 
 完整示例见 [examples/stacy-sims/](examples/stacy-sims/)。
 
-### 3.2 记忆
+### 3.2 提问
+
+让模型发一张题卡请用户选：一个问题加 2 到 4 个可以直接点的选项。私聊、群聊都能用。
+
+把 `conversation.tools.ask_question` 放进 `initialState.tools`，模型就能发题卡。
+
+- 参数是 `question`（题目，不超过 500 字）和 `options`（2 到 4 个，每个不超过 30 字，不能重复）；不合规时模型会看到错误，改了再调。
+- 用户点选项，就是用选项原文发一条消息，跟自己打字一样；也可以不点，直接打字。
+- `conversation` 对象不提供发题卡的方法，题卡只由模型发。
+
+用法见 [examples/aunt-tu/](examples/aunt-tu/)。
+
+### 3.3 记忆
 
 这场会话的长期记忆，存在平台上，只在本会话内可见，会话删除时一并清除。
 
@@ -253,7 +316,7 @@ interface MemoryEntry {
 const REMEMBER_PARAMS = Type.Object({ topic: Type.String(), text: Type.String() });
 
 await BuddyServer.start({
-	model: "kimi-k3",
+	dataRequirements: [],
 	buddy: (conversation) => {
 		const remember: AgentTool<typeof REMEMBER_PARAMS, undefined> = {
 			name: "remember",
@@ -265,31 +328,63 @@ await BuddyServer.start({
 				return { content: [{ type: "text", text: "记下了。" }], details: undefined };
 			},
 		};
-		return { initialState: { systemPrompt: PERSONA, tools: [remember] } };
+		return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [remember] } };
 	},
 });
 ```
 
-### 3.3 授权数据
+### 3.4 用户授权数据
 
 用户同意后，搭子可以读用户的睡眠、运动等数据。数据按 Dataset 分项，用户逐项同意。搭子拿不到用户的真实 id。
 
-**声明需要哪些数据**
+这里有三层不同概念：
 
-`PUT /cli/buddies/:id/data-requirements` 提交完整清单，每次覆盖上一次：
+1. **Runtime 能力目录**：当前 SDK 支持哪些 Dataset，由包导出的 `DATA_ACCESS_CAPABILITIES` 提供。
+2. **搭子数据声明**：这只搭子实际需要其中哪些 Dataset，以及各自用途，写在 `BuddyServer.start.dataRequirements`。
+3. **用户 Grant**：用户是否同意这只搭子读取某个已声明 Dataset，由客户端授权流程管理，搭子不能代替用户授予。
 
-```json
-{
-	"datasets": [
-		{ "id": "health.sleep", "purpose": "根据你最近的睡眠调整作息建议" }
-	]
+把 `data_access_query`、`data_access_request` 等平台工具放进 `initialState.tools`，只决定模型能不能调用它们，不等于声明 Dataset，也不等于获得用户授权。
+
+位置和日历是当前会话的一次性授权结果，通过 `data_access_request` 请求，不属于 Dataset，也不写进 `dataRequirements`。HealthKit 数据会形成可重复查询的 Dataset，因此必须先在 `dataRequirements` 中声明。
+
+**读取 Runtime 能力目录**
+
+开发者工具和项目代码直接从 Runtime 包导入，不需要网络请求：
+
+```ts
+import {
+	DATA_ACCESS_CAPABILITIES,
+	dataAccessCapability,
+	type DataAccessDatasetId,
+} from "@my-life-buddies/buddy-runtime";
+
+for (const capability of DATA_ACCESS_CAPABILITIES) {
+	console.log(capability.id, capability.title, capability.source, capability.schemaVersion);
 }
+
+const sleep = dataAccessCapability("health.sleep");
 ```
 
-- `id`：从下表选。
+这份导出是开发者可选 `id` 的权威来源。新增 Dataset 随 Runtime 版本发布；developer-platform、脚手架和预检都应读取该导出，不再维护一份手写枚举。
+
+**声明需要哪些数据**
+
+声明写在 `BuddyServer.start` 的初始化参数里，Runtime 在本地展开成带标题、来源和 Schema 版本的完整声明：
+
+```ts
+await BuddyServer.start({
+	dataRequirements: [
+		{ id: "health.sleep", purpose: "根据你最近的睡眠调整作息建议" },
+	],
+	buddy: () => ({ /* ... */ }),
+});
+```
+
+- `id`：从 `DATA_ACCESS_CAPABILITIES` 中选，TypeScript 会收窄为 `DataAccessDatasetId`。
 - `purpose`：用途，1～200 字。用户看到这句话再决定是否同意。
-- 改了某项的 `purpose`，用户要重新同意；从清单里删掉的，搭子立即读不到。
-- 改完清单要重启搭子进程，模型才能看到新清单。
+- Runtime 不在启动时注册声明；查询、HealthKit 权限卡和主动服务请求会携带当前完整声明。
+- Server 在实际请求时按声明用途和 Schema 计算版本；`id`、`purpose` 与 Schema 都没变化时保留已有 Grant，变化后要求重新授权。
+- 本地进程连接线上网关时使用 `<buddyId>-dev` 身份，实际使用形成的授权上下文与正式搭子隔离。
 
 | Dataset | 内容 | `data.items` 每条的字段 |
 |---|---|---|
@@ -304,10 +399,65 @@ await BuddyServer.start({
 
 部分字段可能缺失，取值前先判断。
 
-**查询**
+**模型工具与代码接口**
+
+- `data_access_query` / `conversation.dataAccess.query`：查询已授权 Dataset。
+- `data_access_request` / `conversation.dataAccess.request`：在私聊中发数据授权卡；发卡后当前回合结束，等待用户操作。
+- `data_access_read_result` / `conversation.dataAccess.readResult`：按授权卡的 `requestId` 读取一次性位置或日历结果；HealthKit 不走这个接口。
+
+模型工具要从 `conversation.tools` 取来放进 `initialState.tools` 才能调用；没声明 Dataset 时照常注册，查询的每一项都回 `notDeclared`。开发者自己的工具直接调用 `conversation.dataAccess`，不用把这几个工具放进去。
+
+**HealthKit：先查询，缺授权再发卡**
+
+```ts
+await BuddyServer.start({
+	dataRequirements: [
+		{ id: "health.sleep", purpose: "根据你最近的睡眠调整作息建议" },
+	],
+	buddy: (conversation) => ({
+		initialState: {
+			model: "kimi-k3",
+			systemPrompt: [
+				"聊到作息时，先用 data_access_query 查询 health.sleep。",
+				"返回 notGranted 时，说明当前问题为什么需要数据，再用 data_access_request 发 HealthKit 授权卡。",
+				"用户处理授权卡后会开启新回合；再次调用 data_access_query，不要调用 data_access_read_result。",
+				"用户拒绝后不要在同一任务里反复申请。",
+			].join("\n"),
+			tools: [conversation.tools.data_access_query, conversation.tools.data_access_request],
+		},
+	}),
+});
+```
+
+完整链路：
+
+```text
+data_access_query
+→ notGranted
+→ data_access_request { kind: "healthkit", datasets: ["health.sleep"], reason: "..." }
+→ 用户在授权卡操作，平台更新 Grant 和 Snapshot
+→ 隐藏结果开启新回合
+→ data_access_query
+→ available + data
+```
+
+查询接口不会把“从未授权”和“用途变化后需重新确认”分成两种模型状态，都会返回 `notGranted`；重新确认原因由用户侧授权页面展示。
+
+**位置和日历：读取一次性结果**
+
+位置和日历不属于 Dataset，不写进 `dataRequirements`。模型先用 `data_access_request` 发卡，用户处理后，隐藏结果会带回这张卡的 `requestId`；再用 `data_access_read_result` 读取。结果只在平台短期保存，读不到时返回 `unavailable`。
+
+```text
+data_access_request { kind: "location", reason: "查找你附近的地点" }
+→ 用户在授权卡操作
+→ 隐藏结果开启新回合并带回 requestId
+→ data_access_read_result { requestId }
+→ available + data，或 unavailable
+```
+
+`calendar` 还可传 `calendarDays`，范围为 1～31，默认 7。授权请求第一期只支持私聊；群聊需要引导目标成员去私聊操作。
 
-- 让模型查：`platformTools` 写上 `data_access_query`，工具说明里会列出声明过的 Dataset 与用途。可以在系统提示里写明什么时候查，比如「聊到作息时，先用 data_access_query 查 health.sleep」。
-- 在工具里查：调用 `conversation.dataAccess.query`。
+**开发者代码查询 Dataset**
 
 ```ts
 const [sleep] = await conversation.dataAccess.query({ datasets: ["health.sleep"] });
@@ -340,9 +490,9 @@ if (sleep.status === "available") {
 - **想让某个结论以后还在场，就在回复里说出来**（用户也会看到）。模型对这些数据的记忆只能活在它说过的话里——下次它读到的是「查了 health.sleep，可用」，不是具体数字。
 - **别把查到的数据写进记忆、小挂件或别的工具的参数**。那些地方不脱敏，写进去就永久留下了。
 
-### 3.4 小挂件
+### 3.5 小挂件
 
-小挂件是会话里一块给用户看的结构化面板，比如一份菜单。模型通过平台工具、开发者通过 `conversation.widgets`，都能建小挂件、写记录、读记录、删记录，并把它发进聊天。
+小挂件是会话里一块给用户看的结构化面板，比如一份菜单。模型通过平台工具、开发者通过 `conversation.widget`，都能建小挂件、写记录、读记录、删记录，并把它发进聊天。
 
 **放进工程目录**
 
@@ -360,22 +510,22 @@ my-buddy/                  工程目录
 
 **让模型使用**
 
-把要用的 `widget_*` 写进 `platformTools`。
+把要用的 `conversation.tools.widget_*` 放进 `initialState.tools`。
 
 - 工具说明里附上各类型的模块与字段。改了 `widgets/` 要重启进程。
-- 这场会话里已有哪些小挂件，平台会在消息里告诉模型，见第 4 节。
+- 这场会话里已有哪些小挂件，平台会在消息里告诉模型。
 - 平台请求失败时，模型只看到「平台请求失败（HTTP 409），请查询最新状态后再操作」这类提示，不带具体原因。
 - `widget_send` 把小挂件放进发送队列就返回，不等平台确认送达。
 
 **在自己的代码里用**
 
-调用 `conversation.widgets`，不需要写进 `platformTools`：
+调用 `conversation.widget`，不需要把 `widget_*` 放进工具：
 
 ```ts
 execute: async (toolCallId, params) => {
-	const { id } = await conversation.widgets.create({ type: "menu", title: "本周菜单", idempotencyKey: `menu:${toolCallId}` });
-	await conversation.widgets.write(id, { module: "菜单", recordId: "2026-09-14", data: { dishes: ["红烧肉", "清炒时蔬"] } });
-	conversation.widgets.send(id, { idempotencyKey: `menu-send:${toolCallId}` });
+	const { id } = await conversation.widget.create({ type: "menu", title: "本周菜单", idempotencyKey: `menu:${toolCallId}` });
+	await conversation.widget.write(id, { module: "菜单", recordId: "2026-09-14", data: { dishes: ["红烧肉", "清炒时蔬"] } });
+	conversation.widget.send(id, { idempotencyKey: `menu-send:${toolCallId}` });
 	return { content: [{ type: "text", text: "菜单建好了。" }], details: undefined };
 },
 ```
@@ -396,11 +546,11 @@ execute: async (toolCallId, params) => {
 - `list` 和 `read` 回的 `canEdit` 为 `false` 的，是别的会话转发来的引用，只能读；改名、写记录、删除、设卡片时平台回 403。
 - `data` 要符合 `schema.json` 里这个模块的 `record`，不符合时平台回 400。
 - 平台回非 2xx、网络出错、超过 30 秒或响应超过 4 MiB 时抛异常，异常的 `status` 是 HTTP 状态码，不带平台给的原因。写操作不自动重试，失败后先读一遍真实状态再决定。
-- 主动服务回合里，除了 `list`、`read`、`readModule`，其余方法都会抛异常，见 3.5。
+- 主动服务回合里，除了 `list`、`read`、`readModule`，其余方法都会抛异常，见 3.6。
 
 用法见 [examples/aunt-tu/](examples/aunt-tu/)。
 
-### 3.5 主动服务
+### 3.6 主动服务
 
 让搭子在约定的时机主动找用户说话，比如每周一次复盘。只支持私聊。
 
@@ -435,36 +585,17 @@ await conversation.proactive.propose({
 
 主动回合里：
 
-- **模型能用的工具只有 `proactiveTools` 里点名的那些，默认一个都没有。** 用户不在场，所以不默认信任任何工具——名字叫 `read_xxx` 的也可能在里面发请求、写外部系统。没点名的工具模型仍然看得见，调了会被挡回一条说明，工具本身不执行。`data_access_query` 另外只能读订阅的 `allowedDataScopes`。
-- 系统提示和普通回合一字不差，记忆不会被附上去。要让模型用记忆，自己把 `conversation.memory.list` 包成工具注册进来，再写进 `proactiveTools`。
-- 调用 `memory.write`、`memory.delete`、`proactive.propose`，以及 `widgets` 上除 `list`、`read`、`readModule` 以外的方法，会抛异常；开发者的钩子照常执行。
-- 用户这时发来消息，主动回合中止，先回复用户；超过 4 分钟也中止。
-- 主动回合的过程不下发给用户：平台在会话流里记两条不可见的记录（叫你判断了什么、你判断的结果），中间的工具步照常写回但也不下发。**开口的那条消息才是用户看得到的**，之后作为搭子说过的话出现在会话历史里。
-
-## 4. 模型收到什么
-
-开发者不用保存会话历史，也不用自己拼模型消息。每场会话的消息存在平台上，进程重启后运行时从平台取回。每次请求模型时，运行时组出以下内容。
+- **工具清单和普通回合一样，运行时不按工具名拦。** `widget_create`、`widget_write`、`widget_delete`、`widget_send`、`ask_question`、`data_access_request`、`data_access_read_result` 调了会抛异常，模型看到错误；`data_access_query` 只能读订阅的 `allowedDataScopes`。
+- **开发者自己的工具，运行时不拦。** 用户不在场，工具里要是会发请求、写外部系统，就在 `beforeToolCall` 里按 `conversation.proactive.isRunning()` 挡掉：
 
-**系统提示**，按顺序拼接，段间空一行：
-
-1. 平台的系统提示：对每场会话都一样的规则，比如消息开头的时间怎么读、用户所在时区去哪看。
-2. `initialState.systemPrompt`。
-3. 资料清单：选了 `resource_read` 且有资料时才有。
-
-**工具**：选中的平台工具在前，`initialState.tools` 在后。
-
-**消息**：这场会话的完整历史，按时间先后排列。一轮回复里模型可能请求多次，比如调完工具接着说，每次都带上当时的完整历史。
-
-- 用户消息、工具结果的开头带 GMT 时间，如「[2026-09-10 14:00:30 GMT] 」；搭子自己说的话不带。
-- 历史末尾多一条「现在的时间（平台附注，不是谁说的话）」，时间是请求时刻，只在这一次请求里。
-- 群聊里成员说的话开头标「[名字 #m_…] 」。
-- 平台交代的情况（比如这场会话里已有哪些小挂件）是一条以「平台交代的情况：」开头的消息，情况有变化才追加新的一份。
-- 引用了别的消息时，开头加一行「[引用 发言人：原话]」，引用图片写「[引用 发言人的图片 #被引消息 id]」。
-- 转发的聊天记录卡按条目展开，每条先写「【名字】」再写正文。
-- 查过授权数据的那一轮，结束后按 3.3 替换。
-
-**图片**：用户发的图不用开发者处理。
+```ts
+beforeToolCall: async ({ toolCall }) =>
+	conversation.proactive.isRunning() && toolCall.name !== "read_plan"
+		? { block: true, reason: "这一轮用户不在场，这个工具用不了。" }
+		: undefined,
+```
 
-- 平台在上传时统一处理成 JPEG，最长边不超过 2048 px、不超过 5 MiB。
-- 图片消息是一条 user 消息：先是「[图片 #消息 id]」和用户配的文字，再跟图片本身；聊天记录卡里的图跟在所在条目的正文后面。
-- 图片读不到时换成「[图片无法读取]」；`model` 不支持看图时换成「[图片：当前模型不支持看图]」。
+- 系统提示和普通回合一字不差，记忆不会被附上去。要让模型用记忆，自己把 `conversation.memory.list` 包成工具放进 `initialState.tools`。
+- 调用 `memory.write`、`memory.delete`、`proactive.propose`，以及 `widget` 上除 `list`、`read`、`readModule` 以外的方法，会抛异常；开发者的钩子照常执行。
+- 用户这时发来消息，主动回合中止，先回复用户；超过 4 分钟也中止。
+- 主动回合的过程不下发给用户：平台在会话流里记两条不可见的记录（叫你判断了什么、你判断的结果），中间的工具步照常写回但也不下发。**开口的那条消息才是用户看得到的**，之后作为搭子说过的话出现在会话历史里。

package/dist/conversation/agent.d.ts

@@ -6,31 +6,39 @@ import { DataAccessUsageTracker } from "../tools/dataAccess.ts";
 import type { Resource } from "../tools/resource.ts";
 import type { BuddyFactory, BuddyLogger, DataRequirement, MLBMessageToWrite } from "../types.ts";
 export interface AgentDeps {
-    /** 这场会话的发送队列：widget_send 与 conversation.widgets.send 把小挂件引用放进来 */
+    /** 这场会话的发送队列：小挂件引用、权限请求卡、题卡都放进来 */
     enqueueMessage: (message: MLBMessageToWrite) => void;
+    /** 发了一张等用户操作的卡（权限请求卡、题卡）：这张卡算这一轮说过的话 */
+    onWaitingForUser?: () => void;
     onPolicyStop?: () => void;
     key: string;
     buddyId: string;
     client: MLBClient;
-    model: Model<Api>;
+    /** 平台网关地址：按开发者的 initialState.model 造模型条目时，baseUrl 指到它的 /internal/v1 */
+    gatewayUrl: string;
     streamFn: StreamFn;
     /** 搭子令牌：经 Agent 的 getApiKey 交给模型通道，变成 Authorization: Bearer 头 */
     token: string;
-    /** 小挂件类型目录（server 启动时上传平台的那些）；空数组就不装小挂件工具 */
+    /** 小挂件类型目录（server 启动时上传平台的那些）；空数组时 widget_* 照常注册，说明里的类型目录为空 */
     widgetTypes: WidgetType[];
-    /** 搭子目录下 resources/ 里的资料；空数组就不装 resource_read、不接清单 */
+    /** 搭子目录下 resources/ 里的资料；空数组时 resource_list 回「没有资料」 */
     resources: Resource[];
-    dataRequirements: () => Promise<DataRequirement[]>;
+    dataRequirements: readonly DataRequirement[];
     factory: BuddyFactory;
     log: BuddyLogger;
     /** Agent 事件的去处。pi 会等它返回，所以只能同步做事 */
     onEvent: (agent: Agent, event: AgentEvent) => void;
 }
-/** 跑开发者工厂拿配置，叠上运行时预置，建 Agent。开发者的工具名跟运行时的工具（小挂件、resource_read）重名或互相重名 → throw。 */
+/** createAgent 建好的：Agent、这场会话的模型条目、授权数据记账，以及开发者配的兜底话 */
 export interface CreatedAgent {
     agent: Agent;
+    /** 按开发者 initialState.model 造的模型条目：重建历史时抄身份、判断收不收图片都按它 */
+    model: Model<Api>;
     dataAccessUsage: DataAccessUsageTracker;
+    /** BuddyOptions.errorReply：普通回合出错或一句话没说时由 index.ts 的 runTurn 发；没配是 undefined */
+    errorReply: string | undefined;
 }
+/** 跑开发者工厂拿配置，叠上运行时预置，建 Agent。模型 id 运行时不支持、工具清单重名、拉平台 system prompt 失败 → throw。 */
 export declare function createAgent(deps: AgentDeps): Promise<CreatedAgent>;
 /**
  * 每次请求模型时接在历史末尾那条 user 消息的正文；现在的时间由 convertToLlm 按这条消息的 timestamp 拼在开头。

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

@@ -1 +1 @@
-{"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,EAAa,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;AAGrD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAA8B,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE7H,MAAM,WAAW,SAAS;IACzB,kEAAkE;IAClE,cAAc,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACrD,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,6CAA6C;IAC7C,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,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,CAsIxE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,iHAAuB,CAAC;AAEtD,iEAAiE;AACjE,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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/conversation/agent.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAExF,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7D,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,EAAiB,MAAM,aAAa,CAAC;AAE5I,MAAM,WAAW,SAAS;IACzB,mCAAmC;IACnC,cAAc,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACrD,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,uDAAuD;IACvD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,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,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,eAAe,EAAE,sBAAsB,CAAC;IACxC,gFAAgF;IAChF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,kFAAkF;AAClF,wBAAsB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CA2LxE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,iHAAuB,CAAC;AAEtD,iEAAiE;AACjE,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"}