@my-life-buddies/buddy-runtime 0.9.0 → 0.11.0

package/README.md

@@ -1,8 +1,14 @@
 # @my-life-buddies/buddy-runtime
 
-搭子运行时，基于 [`@earendil-works/pi-agent-core`](https://www.npmjs.com/package/@earendil-works/pi-agent-core)。
-它提供了让搭子接入平台的基本能力：接收消息、模型调用、回复消息链路，并可以快速接入平台所提供的包括资料引入、记忆系统、授权数据、主动性、付费服务等特色化能力。
-开发者只需基于搭子的领域逻辑书写工具、人设等。
+搭子服务的运行时基座，负责平台通信与会话管理，开发者可专注在领域逻辑。主要职责：
+
+1. **平台通信**：基于平台协议接收消息、调用模型，并将回复写回平台。运行时本身无状态，会话历史、记忆等数据均持久化在平台 —— **开发者无需为会话历史与记忆自建存储，服务运维无需关注数据持久**。
+
+2. **会话管理**：搭子与每位用户的私聊、群聊各对应一个会话，每个会话持有一个基于 [`@earendil-works/pi-agent-core`](https://www.npmjs.com/package/@earendil-works/pi-agent-core) 的 Agent 实例。基座接管会话的完整生命周期：冷启重建、空闲回收、超长历史压缩 —— **开发者无需关注 Agent 生命周期，基座全接管**。
+
+3. **会话配置**：每个会话实例创建时调用开发者传入的 Buddy 配置工厂函数，入参为当前会话的 `conversation` 对象，提供已绑定当前会话的平台能力，包括资料、提问、记忆、用户授权数据、小挂件、主动服务、付费服务等 —— **开发者可以尽情组合各种数据和能力，提供有特色差异的服务**。
+
+开始创造你的「搭子」吧！
 
 ## 1. 快速开始
 
@@ -12,22 +18,22 @@
 npm install @my-life-buddies/buddy-runtime typebox
 ```
 
-### 1.2 注册搭子
+### 1.2 创建搭子
 
-通过平台开发者接口 `POST /cli/buddies` 注册，提交名称、头像、简介，平台分配搭子 id 与令牌；之后改档案用 `PUT /cli/buddies/:id/meta`。可选的模型 id 查 `GET /cli/models`，可声明的数据能力查 `GET /cli/data-access/capabilities`。
+通过 `@my-life-buddies/cli` 完成搭搭账号注册，并创建一个新的搭子，获取 buddyId & buddyToken
 
 ### 1.3 搭子工程框架
 
 ```
 my-buddy/
-├─ package.json
-├─ .env              MLB_BUDDY_ID、MLB_BUDDY_TOKEN
-└─ src/main.ts
+├─ .env            BUDDY_ID、BUDDY_TOKEN
+├─ src/index.ts   
+└─ package.json
 ```
 
 ```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,10 +50,12 @@ const planMenu: AgentTool<typeof PLAN_MENU_PARAMS, undefined> = {
 };
 
 await BuddyServer.start({
-	model: "kimi-k3",
+	buddyId: process.env.BUDDY_ID!,
+	token: process.env.BUDDY_TOKEN!,
 	dataRequirements: [],
 	buddy: () => ({
 		initialState: {
+			model: "kimi-k3",
 			systemPrompt: "你是「小涂阿姨」——一位管做饭的阿姨……",
 			tools: [planMenu],
 		},
@@ -55,26 +63,6 @@ await BuddyServer.start({
 });
 ```
 
-```json
-{
-	"scripts": {
-		"start": "node --env-file-if-exists=.env src/main.ts"
-	}
-}
-```
-
-### 1.4 启动
-
-在 `.env` 里配好环境变量，`npm run dev` 启动
-
-| 变量 | 说明 |
-|---|---|
-| `MLB_BUDDY_ID` | 必填，搭子 id |
-| `MLB_BUDDY_TOKEN` | 必填，搭子令牌 |
-
-- 在自己电脑上连测试网关时，平台把这个进程当作 `<id>-dev` 分身，会话与正式搭子分开。
-- 改完代码想自动重启，在启动命令里加 `--watch`。
-
 完整示例：[examples/aunt-tu/](examples/aunt-tu/)（提问、记忆、小挂件）、[examples/stacy-sims/](examples/stacy-sims/)（资料）。
 
 ## 2. 配置
@@ -83,54 +71,74 @@ await BuddyServer.start({
 
 连上平台开始处理消息，返回 `{ stop(): Promise<void> }`。
 
-| 参数 | 说明 |
-|---|---|
-| `model` | 必填，模型 id，取值见 `GET /cli/models`，进程内所有会话共用。没填或运行时不认识这个 id 时启动失败 |
-| `dataRequirements` | 必填，这只搭子需要的用户数据及用途；不需要时传 `[]`。Runtime 启动时整份上传平台，失败则不启动 |
-| `buddy` | 必填，`(conversation: Conversation) => BuddyOptions \| Promise<BuddyOptions>`，见 2.2、2.3 |
-| `errorReply` | 可选，模型出错或空回复时发的兜底回复 |
+```ts
+interface StartOptions {
+	// 必填。搭子 id 与令牌，注册时平台分配，见 1.2。平台托管时以环境变量 BUDDY_ID、BUDDY_TOKEN 注入
+	buddyId: string;
+	token: string;
+
+	// 必填。这只搭子需要的用户数据及用途，见 3.4；不需要时传 []
+	dataRequirements: { id: DataAccessDatasetId; purpose: string }[];
 
-Runtime 启动时先校验 `dataRequirements`，再凭搭子令牌把整份声明上传平台；平台补齐 Dataset 的标题、来源、Schema 版本和声明版本。上传失败时启动直接失败，不连接事件流，也不会出现“进程在线但没有正确数据权限”的半成品状态。
+	// 必填。每场会话建起来时调一次，返回这场会话的配置，见 2.2、2.3
+	buddy: (conversation: Conversation) => BuddyOptions | Promise<BuddyOptions>;
+}
+```
 
-用户新加搭子、新建群时，搭子会先开口打个招呼，跟平时回复一样调模型、逐字出现。开场白怎么说，写在 system prompt 里。
+Runtime 启动时只在本地校验 `dataRequirements`，不会额外调用接口注册声明。Runtime 根据自身导出的能力目录补齐标题、来源和 Schema 版本；实际调用 `data_access_query`、发送 HealthKit 权限卡或申请使用数据的主动服务时，会把完整声明随业务请求携带给平台。平台在该次请求中更新用途版本并校验 Grant。
 
-`buddy` 在每场会话收到第一条消息时调用一次。会话空闲 30 分钟被回收、或进程重启后，下一条消息会重新调用，所以闭包里的变量不能当长期存储，要记住的东西写进记忆（3.3）。
+**buddy 的生命周期**：`buddy` 在每场会话收到第一条消息时调用一次。会话空闲 30 分钟被回收、或进程重启后，下一条消息会重新调用，所以闭包里的变量不能当长期存储，需要存储会话状态可以根据场景使用 3.3 记忆、3.5 小挂件实现。
 
-会话历史长到一定程度（超过 128K token，窗口小的模型按窗口的四分之一算）时，运行时在会话被回收后把早先的对话压成一份摘要写回平台，下次重建时模型看到的是「摘要 + 最近的原文」。开发者不用做任何事，也没有开关。
+**buddy 的会话压缩**：会话历史长到一定程度时，运行时在会话被回收后把早先的对话压成一份摘要写回平台，下次重建时模型看到的是「摘要 + 最近的原文」。开发者不用做任何事，也没有开关。
 
 ### 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.6 |
-| 其余字段 | 原样交给 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`
 
@@ -144,8 +152,23 @@ 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;
 	};
@@ -160,10 +183,12 @@ interface Conversation {
 	// 授权数据，见 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.5
-	widgets: {
+	widget: {
 		list(): Promise<WidgetSummary[]>;
 		create(input: { type: string; title: string; idempotencyKey?: string }): Promise<{ id: string }>;
 		read(id: string): Promise<Widget>;
@@ -179,34 +204,44 @@ interface Conversation {
 		send(id: string, options: { idempotencyKey: string }): void;
 	};
 
-	// 主动服务，见 3.6：提订阅建议，用户在 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` |
-| 提问 | 无 | `ask_question` | platformTools 声明 |
-| 记忆 | `conversation.memory` | 无，默认不注册成模型工具，开发者可以根据具体场景，注册成适合场景需要的模型工具 | — |
-| 授权数据 | `conversation.dataAccess.query` | `data_access_query` | platformTools 声明 && 声明过至少一个 Dataset |
-| 会话内权限 | `conversation.permissions.request` / `conversation.permissions.readResult` | `permission_request` / `permission_result_read` | platformTools 声明；第一期仅私聊 |
-| 小挂件 | `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/                  工程目录
@@ -214,12 +249,12 @@ my-buddy/                  工程目录
 ├─ resources/
 │  └─ research/
 │     └─ 01-writings.md    清单里写作 research/01-writings.md
-└─ src/main.ts             入口脚本
+└─ src/index.ts            入口脚本
 ```
 
 **在自己的代码里用**
 
-调用 `conversation.resources`，不需要写进 `platformTools`：
+调用 `conversation.resource`，不需要把这两个工具放进 `initialState.tools`：
 
 | 方法 | 做什么 |
 |---|---|
@@ -227,7 +262,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");
 ```
 
 - 两个方法都是同步的，读的是进程启动时读好的那份。
@@ -239,7 +274,7 @@ const notes = conversation.resources.read("research/01-writings.md");
 
 让模型发一张题卡请用户选：一个问题加 2 到 4 个可以直接点的选项。私聊、群聊都能用。
 
-把 `ask_question` 写进 `platformTools`，模型就能发题卡。
+把 `conversation.tools.ask_question` 放进 `initialState.tools`，模型就能发题卡。
 
 - 参数是 `question`（题目，不超过 500 字）和 `options`（2 到 4 个，每个不超过 30 字，不能重复）；不合规时模型会看到错误，改了再调。
 - 用户点选项，就是用选项原文发一条消息，跟自己打字一样；也可以不点，直接打字。
@@ -271,7 +306,6 @@ 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> = {
@@ -284,58 +318,51 @@ 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.4 授权数据
+### 3.4 用户授权数据
 
 用户同意后，搭子可以读用户的睡眠、运动等数据。数据按 Dataset 分项，用户逐项同意。搭子拿不到用户的真实 id。
 
 这里有三层不同概念：
 
-1. **平台能力目录**：平台目前能提供哪些 Dataset，由 `GET /cli/data-access/capabilities` 返回。
+1. **Runtime 能力目录**：当前 SDK 支持哪些 Dataset，由包导出的 `DATA_ACCESS_CAPABILITIES` 提供。
 2. **搭子数据声明**：这只搭子实际需要其中哪些 Dataset，以及各自用途，写在 `BuddyServer.start.dataRequirements`。
 3. **用户 Grant**：用户是否同意这只搭子读取某个已声明 Dataset，由客户端授权流程管理，搭子不能代替用户授予。
 
-`platformTools` 只决定模型能不能调用 `data_access_query`、`permission_request` 等工具，不等于声明 Dataset，也不等于获得用户授权。
+把 `data_access_query`、`data_access_request` 等平台工具放进 `initialState.tools`，只决定模型能不能调用它们，不等于声明 Dataset，也不等于获得用户授权。
 
-位置和日历是当前会话的一次性权限结果，通过 `permission_request` 请求，不属于 Dataset，也不写进 `dataRequirements`。HealthKit 数据会形成可重复查询的 Dataset，因此必须先在 `dataRequirements` 中声明。
+位置和日历是当前会话的一次性授权结果，通过 `data_access_request` 请求，不属于 Dataset，也不写进 `dataRequirements`。HealthKit 数据会形成可重复查询的 Dataset，因此必须先在 `dataRequirements` 中声明。
 
-**查看平台能力目录**
+**读取 Runtime 能力目录**
 
-开发者凭 CLI 用户令牌请求：
+开发者工具和项目代码直接从 Runtime 包导入，不需要网络请求：
 
-```http
-GET /cli/data-access/capabilities
-Authorization: Bearer <用户 token>
-```
-
-响应示例：
-
-```json
-{
-	"datasets": [
-		{
-			"id": "health.sleep",
-			"title": "睡眠",
-			"source": "healthkit",
-			"schemaVersion": 1
-		}
-	]
+```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 每次启动时整份上传平台：
+声明写在 `BuddyServer.start` 的初始化参数里，Runtime 在本地展开成带标题、来源和 Schema 版本的完整声明：
 
 ```ts
 await BuddyServer.start({
-	model: "kimi-k3",
 	dataRequirements: [
 		{ id: "health.sleep", purpose: "根据你最近的睡眠调整作息建议" },
 	],
@@ -343,13 +370,11 @@ await BuddyServer.start({
 });
 ```
 
-- `id`：从下表选，也可以调用 `GET /cli/data-access/capabilities` 获取平台当前的完整能力目录。
+- `id`：从 `DATA_ACCESS_CAPABILITIES` 中选，TypeScript 会收窄为 `DataAccessDatasetId`。
 - `purpose`：用途，1～200 字。用户看到这句话再决定是否同意。
-- 每次启动都是整份覆盖：新增项进入待授权，删除项立即停止访问并撤销对应 Grant。
-- `id` 与 `purpose` 都没变化时保留声明版本和已有 Grant；修改 `purpose` 会提升声明版本，已有 Grant 变成 `reconsentRequired`，需要用户重新确认。
-- 声明不再通过 `PUT /cli/buddies/:id/data-requirements` 修改；改代码并重启或发布搭子即可生效。
-- 本地进程连接线上网关时使用 `<buddyId>-dev` 身份，其声明和用户授权与正式搭子隔离，不会覆盖线上版本。
-- 可用 `GET /cli/buddies/:id/data-requirements` 查看某搭子当前已经上传并生效的声明；这个接口只读。
+- Runtime 不在启动时注册声明；查询、HealthKit 权限卡和主动服务请求会携带当前完整声明。
+- Server 在实际请求时按声明用途和 Schema 计算版本；`id`、`purpose` 与 Schema 都没变化时保留已有 Grant，变化后要求重新授权。
+- 本地进程连接线上网关时使用 `<buddyId>-dev` 身份，实际使用形成的授权上下文与正式搭子隔离。
 
 | Dataset | 内容 | `data.items` 每条的字段 |
 |---|---|---|
@@ -364,11 +389,65 @@ await BuddyServer.start({
 
 部分字段可能缺失，取值前先判断。
 
-**查询**
+**模型工具与代码接口**
 
-- 让模型查：`platformTools` 写上 `data_access_query`，工具说明里会列出声明过的 Dataset 与用途。可以在系统提示里写明什么时候查，比如「聊到作息时，先用 data_access_query 查 health.sleep」。
-- 要在聊天中申请位置、日历或 HealthKit 权限，把 `permission_request` 加进 `platformTools`。HealthKit 先查询，收到 `notGranted` / `reconsentRequired` 后再发卡；位置和日历授权完成后，以卡片消息 ID 调 `permission_result_read` 读取一次性结果。用户拒绝后不要在同一任务里反复申请。
-- 在工具里查：调用 `conversation.dataAccess.query`。
+- `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。授权请求第一期只支持私聊；群聊需要引导目标成员去私聊操作。
+
+**开发者代码查询 Dataset**
 
 ```ts
 const [sleep] = await conversation.dataAccess.query({ datasets: ["health.sleep"] });
@@ -403,7 +482,7 @@ if (sleep.status === "available") {
 
 ### 3.5 小挂件
 
-小挂件是会话里一块给用户看的结构化面板，比如一份菜单。模型通过平台工具、开发者通过 `conversation.widgets`，都能建小挂件、写记录、读记录、删记录，并把它发进聊天。
+小挂件是会话里一块给用户看的结构化面板，比如一份菜单。模型通过平台工具、开发者通过 `conversation.widget`，都能建小挂件、写记录、读记录、删记录，并把它发进聊天。
 
 **放进工程目录**
 
@@ -416,27 +495,27 @@ my-buddy/                  工程目录
 │  └─ menu/                类型 id 是 menu
 │     ├─ schema.json       每个模块写一句 description 给模型读，每条记录的形状是一份 JSON Schema
 │     └─ index.html        展示页面，单个 HTML 文件
-└─ src/main.ts
+└─ src/index.ts
 ```
 
 **让模型使用**
 
-把要用的 `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 };
 },
 ```
@@ -496,8 +575,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` 以外的方法，会抛异常；开发者的钩子照常执行。
+- **工具清单和普通回合一样，运行时不按工具名拦。** `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()` 挡掉：
+
+```ts
+beforeToolCall: async ({ toolCall }) =>
+	conversation.proactive.isRunning() && toolCall.name !== "read_plan"
+		? { block: true, reason: "这一轮用户不在场，这个工具用不了。" }
+		: undefined,
+```
+
+- 系统提示和普通回合一字不差，记忆不会被附上去。要让模型用记忆，自己把 `conversation.memory.list` 包成工具放进 `initialState.tools`。
+- 调用 `memory.write`、`memory.delete`、`proactive.propose`，以及 `widget` 上除 `list`、`read`、`readModule` 以外的方法，会抛异常；开发者的钩子照常执行。
 - 用户这时发来消息，主动回合中止，先回复用户；超过 4 分钟也中止。
-- 主动回合的过程不下发给用户：平台在会话流里记两条不可见的记录（叫你判断了什么、你判断的结果），中间的工具步照常写回但也不下发。**开口的那条消息才是用户看得到的**，之后作为搭子说过的话出现在会话历史里。
+- 主动回合的过程不下发给用户：平台在会话流里记两条不可见的记录（叫你判断了什么、你判断的结果），中间的工具步照常写回但也不下发。**开口的那条消息才是用户看得到的**，之后作为搭子说过的话出现在会话历史里。

package/dist/conversation/agent.d.ts

@@ -14,13 +14,14 @@ export interface AgentDeps {
     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: readonly DataRequirement[];
     factory: BuddyFactory;
@@ -28,11 +29,16 @@ export interface AgentDeps {
     /** 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;AAE7D,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,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,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,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,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,CAmKxE;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"}