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

package/README.md

@@ -1,8 +1,10 @@
 # @my-life-buddies/buddy-runtime
 
-MLB 搭子运行时。基于 [`@earendil-works/pi-agent-core`](https://www.npmjs.com/package/@earendil-works/pi-agent-core) 构建，负责搭子与 MLB 平台之间的全部交互：订阅事件流、拉取消息、驱动模型、写回回复、推送在线状态。开发者只需提供搭子的配置。
+MLB 搭子运行时，基于 [`@earendil-works/pi-agent-core`](https://www.npmjs.com/package/@earendil-works/pi-agent-core)。它替搭子接上平台：收消息、调模型、把回复写回聊天，会话历史存在平台上。开发者只写人设和工具。
 
-## 1. 安装
+## 1. 快速开始
+
+### 1.1 安装
 
 ```bash
 npm install @my-life-buddies/buddy-runtime typebox
@@ -10,12 +12,16 @@ npm install @my-life-buddies/buddy-runtime typebox
 
 要求 Node.js ≥ 22.19。
 
-## 2. 快速开始
+### 1.2 注册搭子
+
+通过平台开发者接口 `POST /cli/buddies` 注册，提交名称、头像、简介，平台分配搭子 id 与令牌；之后改档案用 `PUT /cli/buddies/:id/meta`。可选的模型 id 查 `GET /cli/models`。
+
+### 1.3 写入口
 
 ```
 my-buddy/
 ├─ package.json
-├─ .env              MLB_BUDDY_ID / MLB_BUDDY_TOKEN
+├─ .env              MLB_BUDDY_ID、MLB_BUDDY_TOKEN
 └─ src/main.ts
 ```
 
@@ -38,7 +44,7 @@ const planMenu: AgentTool<typeof PLAN_MENU_PARAMS, undefined> = {
 };
 
 await BuddyServer.start({
-	model: "kimi-k3",   // 必填；可选值见开发者接口 GET /cli/models
+	model: "kimi-k3",
 	buddy: () => ({
 		initialState: {
 			systemPrompt: "你是「小涂阿姨」——一位管做饭的阿姨……",
@@ -56,82 +62,110 @@ await BuddyServer.start({
 }
 ```
 
-完整示例见 [examples/aunt-tu/](examples/aunt-tu/)。
+### 1.4 启动
 
-## 3. API
+在 `.env` 里配好环境变量，`npm start` 启动。搭子进程主动连平台，不监听端口。
 
-### 3.1 `BuddyServer.start(options)`
+| 变量 | 说明 |
+|---|---|
+| `MLB_BUDDY_ID` | 必填，搭子 id |
+| `MLB_BUDDY_TOKEN` | 必填，搭子令牌 |
+| `MLB_GATEWAY_URL` | 可选，平台网关地址，缺省为测试环境 `http://47.116.168.81:8788` |
 
-启动搭子进程，连接平台事件流。返回 `{ stop(): Promise<void> }`。
+- 在自己电脑上连测试网关时，平台把这个进程当作 `<id>-dev` 分身，会话与正式搭子分开。
+- 从回环地址连网关算正式身份：连本机起的网关要用本机注册的凭据，不要拿正式搭子的令牌再起一个进程。
+- 改完代码想自动重启，在启动命令里加 `--watch`。
 
-| 参数 | 类型 | 说明 |
-|---|---|---|
-| `options.model` | `string`，必填 | 模型 id，取值见平台 `GET /cli/models`。进程内所有会话共用。没填，或 id 在运行时内置的模型目录中不存在时，启动失败 |
-| `options.welcome` / `options.errorReply` | `string`，可选 | 应用提供的静态问候，以及模型出错、空回复时发的兜底回复 |
-| `options.buddy` | `(conversation: Conversation) => BuddyOptions \| Promise<BuddyOptions>` | 搭子配置工厂。每场会话在第一条消息到达时调用一次 |
+完整示例：[examples/aunt-tu/](examples/aunt-tu/)（记忆、小挂件）、[examples/stacy-sims/](examples/stacy-sims/)（资料）。
 
-### 3.2 `BuddyOptions`
+## 2. 配置
 
-配置的形状与字段名与 pi-agent-core 的 `AgentOptions` / `AgentState` 一致，签名请参考 pi 的文档。
+### 2.1 `BuddyServer.start(options)`
+
+连上平台开始处理消息，返回 `{ stop(): Promise<void> }`。
+
+| 参数 | 说明 |
+|---|---|
+| `model` | 必填，模型 id，取值见 `GET /cli/models`，进程内所有会话共用。没填或运行时不认识这个 id 时启动失败 |
+| `buddy` | 必填，`(conversation: Conversation) => BuddyOptions \| Promise<BuddyOptions>`，见 2.2、2.3 |
+| `welcome` | 可选，用户打开一场还没聊过的会话时发的问候，不经过模型 |
+| `errorReply` | 可选，模型出错或空回复时发的兜底回复 |
+
+`buddy` 在每场会话收到第一条消息时调用一次。会话空闲 30 分钟被回收、或进程重启后，下一条消息会重新调用，所以闭包里的变量不能当长期存储，要记住的东西写进记忆（3.1）。
+
+### 2.2 `BuddyOptions`
+
+`buddy` 的返回值。字段名和签名取自 pi-agent-core 的 `AgentOptions` / `AgentState`，详见 pi 的文档。
 
 ```ts
-type BuddyOptions =
-	Pick<AgentOptions,
-		| "beforeToolCall" | "afterToolCall"
-		| "shouldStopAfterTurn" | "prepareNextTurnWithContext"
-		| "thinkingBudgets" | "toolExecution">
-	& { platformTools?: readonly PlatformToolName[]; initialState: Pick<AgentState, "systemPrompt"> & Partial<Pick<AgentState, "tools" | "thinkingLevel">> };
+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">>;
+};
 ```
 
 | 字段 | 说明 |
 |---|---|
-| `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 |
-| `beforeToolCall` / `afterToolCall` / `shouldStopAfterTurn` / `prepareNextTurnWithContext` / `thinkingBudgets` / `toolExecution` | 原样传递给 pi |
+| `initialState.systemPrompt` | 必填，人设与做事规则，只放不随回合变化的内容。模型实际收到的系统提示见第 4 节 |
+| `initialState.tools` | 可选，pi 的 `AgentTool` 数组 |
+| `initialState.thinkingLevel` | 可选，默认 `off`。模型不支持的级别在请求时就近换成支持的一档，建会话时打一条 warn |
+| `platformTools` | 可选，给模型注册哪些平台工具，默认 `[]`，见第 3 节 |
+| `proactiveTools` | 可选，主动回合里还能用哪些工具，默认 `[]`（一个都不给）。写工具名，`platformTools` 选中的和 `initialState.tools` 里自己的都行；写了没注册的名字建会话时抛异常。见 3.5 |
+| 其余字段 | 原样交给 pi；`beforeToolCall` 抛异常时按放行处理 |
 
-密钥、会话历史与插话策略由运行时统一管理；工厂提供当前会话键与已绑定的平台能力，不传递 Token。模型通过 `BuddyServer.start` 的 `model` 选择。
+写工具时注意：
 
-### 3.3 `Conversation` 与平台能力
+- `label` 必填，是工具执行时用户看到的状态文案，空字符串表示不显示。
+- `execute` 的返回值必须带 `details`，可以是 `undefined`；失败直接抛异常，模型能看到异常信息。
+- 先单独声明为 `AgentTool<typeof 参数 schema>` 再放进数组，`execute` 的参数才有类型；直接写在数组里时参数类型是 `unknown`。
+- 工具名不能与平台工具或其他工具重复。
 
-工厂拿到的对象，可在工具闭包中使用。会话之间的数据应以 `key` 隔离。
+模型、密钥与会话历史由运行时管理，不在配置里。
+
+### 2.3 `Conversation`
+
+`buddy` 拿到的参数，工具闭包里也能用。
 
 ```ts
 interface Conversation {
-	readonly key: string;              // 会话键：私聊为 p_ 前缀，群聊为 g_ 前缀
+	readonly key: string;
 	readonly log: BuddyLogger;
-	readonly signal: AbortSignal;      // 会话删除、空闲淘汰、stop 时中止
-	readonly platform: PlatformClient; // 已绑好这场会话的平台能力
-}
-
-interface PlatformClient {
 	readonly memory: {
 		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 };
+	readonly dataAccess: {
+		query(request: { datasets: string[]; memberId?: string }): Promise<DatasetAccessResult[]>;
+	};
+	readonly proactive: {
+		propose(request: ProactiveSubscriptionRequest): Promise<{ id: string; status: "pending" }>;
+	};
 }
 ```
 
-`platform` 下的方法由开发者在代码里调用，会话键已经绑好，不需要传 Token 或拼 HTTP 路径。其中授权数据、小挂件、资料三项，运行时还提供了给模型用的工具，把工具名写进 `BuddyOptions.platformTools` 才注册：
+- `key`：会话键，私聊以 `p_` 开头，群聊以 `g_` 开头。开发者自己存的数据要按它隔离。
+- `log`：日志，每行开头带搭子 id。
+- `memory`、`dataAccess`、`proactive`：已经绑好这场会话，直接调用，不用传令牌或拼接口路径，分别见 3.1、3.2、3.5。
+
+## 3. 平台能力
 
-| 能力 | 代码里调用 | 给模型的工具 | 工具注册还要满足 |
+| 能力 | 开发者代码调用 | 模型工具 | 模型工具注册还需要 |
 |---|---|---|---|
-| 记忆 | `platform.memory` | 无，要给模型用就自己包成工具，见 3.3.1 | 无 |
-| 授权数据 | `platform.dataAccess.query` | `data_access_query` | 声明过至少一个 Dataset |
-| 小挂件 | `platform.widgets` | `widget_create` / `widget_write` / `widget_read` / `widget_delete` / `widget_send` | 登记过至少一个小挂件类型 |
+| 记忆 | `conversation.memory` | 无，需要时自己包成工具 | — |
+| 授权数据 | `conversation.dataAccess.query` | `data_access_query` | 声明过至少一个 Dataset |
+| 小挂件 | 无 | `widget_create` / `widget_write` / `widget_read` / `widget_delete` / `widget_send` | 登记过至少一个小挂件类型 |
 | 资料 | 无 | `read_resource` | `resources/` 下有 `.md` |
-| 发消息 | `platform.messages.send` | 无 | 无 |
-| 主动服务建议 | `platform.proactive.propose`，见第 7 节 | 无 | 用户在 App 确认后生效 |
+| 主动服务 | `conversation.proactive.propose` | 无 | — |
 
-- `platformTools` 默认 `[]`，一个平台工具都不注册。名单里有不认识或重复的名字时，这场会话起不来。
-- 注册的平台工具排在 `initialState.tools` 前面；和开发者的工具重名时，这场会话起不来。
-- 没写进名单的，照样可以在代码里调用 `platform`。
+- 模型工具要写进 `BuddyOptions.platformTools` 才注册，排在 `initialState.tools` 前面。
+- `platformTools` 只决定模型看得到哪些工具，不影响开发者代码里的调用。
+- 名单里有不认识或重复的名字，或与开发者工具重名时，这场会话启动失败。
 
 ```ts
 return {
@@ -140,19 +174,25 @@ return {
 };
 ```
 
-#### 3.3.1 记忆
+### 3.1 记忆
 
-`platform.memory` 是这场会话的长期记忆，由平台保存，只在本会话内可见，会话删除时平台一并清除。`key` 为主题名（非空、不含空白与 `/`，最长 64 字），`text` 单条不超过 16KB；每场会话最多 64 条、合计不超过 256KB。`list` 全量列出，按 `key` 字典序；`write` 覆盖写一条；`delete` 删一条，删不存在的也算成功。超出配额、`key` 不合法或网络出错时直接抛出异常，异常信息为平台给出的原因；在工具的 `execute` 中调用时，模型能看到这个原因。
+这场会话的长期记忆，存在平台上，只在本会话内可见，会话删除时一并清除。
+
+- `list()`：列出全部，按 `key` 字典序。
+- `write(key, text)`：覆盖写一条。
+- `delete(key)`：删一条，不存在也算成功。
+
+`key` 非空、不含空白与 `/`、最长 64 字；`text` 单条不超过 16 KB；每场会话最多 64 条、合计不超过 256 KB。超限、`key` 不合法或网络出错时抛异常，异常信息是平台给出的原因，在工具里调用时模型能看到。
 
 ```ts
 interface MemoryEntry {
-	key: string;        // 主题名
+	key: string;
 	text: string;
 	updatedAt: number;  // 最后写入时刻，毫秒
 }
 ```
 
-运行时不提供记忆工具，要让模型记东西，开发者自己包成工具：
+运行时不提供记忆工具，要让模型记东西，自己包一个：
 
 ```ts
 const REMEMBER_PARAMS = Type.Object({ topic: Type.String(), text: Type.String() });
@@ -166,7 +206,7 @@ await BuddyServer.start({
 			description: "把一条关于对方的印象记下来，同一主题覆盖旧的。",
 			parameters: REMEMBER_PARAMS,
 			execute: async (_id, { topic, text }) => {
-				await conversation.platform.memory.write(topic, text);
+				await conversation.memory.write(topic, text);
 				return { content: [{ type: "text", text: "记下了。" }], details: undefined };
 			},
 		};
@@ -175,15 +215,13 @@ await BuddyServer.start({
 });
 ```
 
-完整示例见 [examples/aunt-tu/](examples/aunt-tu/)：`taste_read` / `taste_write` 两个工具用 `platform.memory` 记每个人爱吃什么、不爱吃什么。
-
-#### 3.3.2 授权数据
+### 3.2 授权数据
 
-经用户同意，搭子可以读取用户授权数据。数据按 Dataset 分项，每项内容与字段固定，用户逐项授权。开发者要做的是声明需要哪些 Dataset，然后让模型用 `data_access_query` 查，或者在自己的工具里查。会话与真实用户身份由平台绑定，搭子拿不到真实用户 id。
+用户同意后，搭子可以读用户的睡眠、运动等数据。数据按 Dataset 分项，用户逐项同意。搭子拿不到用户的真实 id。
 
 **声明需要哪些数据**
 
-通过平台 CLI 接口 `PUT /cli/buddies/:id/data-requirements` 提交完整清单，每次提交覆盖上一次：
+`PUT /cli/buddies/:id/data-requirements` 提交完整清单，每次覆盖上一次：
 
 ```json
 {
@@ -194,11 +232,9 @@ await BuddyServer.start({
 ```
 
 - `id`：从下表选。
-- `purpose`：写给用户看的用途，1~200 字。用户在 App 里看到这句话，再决定是否同意。
-- 改了某项的 `purpose`，用户之前的同意失效，要重新同意；从清单里删掉的数据，搭子立即读不到。
-- 声明或改动之后，重启搭子进程，模型才能看到新的清单。
-
-目前支持的 Dataset：
+- `purpose`：用途，1～200 字。用户看到这句话再决定是否同意。
+- 改了某项的 `purpose`，用户要重新同意；从清单里删掉的，搭子立即读不到。
+- 改完清单要重启搭子进程，模型才能看到新清单。
 
 | Dataset | 内容 | `data.items` 每条的字段 |
 |---|---|---|
@@ -213,177 +249,141 @@ await BuddyServer.start({
 
 部分字段可能缺失，取值前先判断。
 
-**让模型去查**
-
-`platformTools` 里有 `data_access_query`，且声明过至少一项数据，模型就有了这个工具，工具说明里列着开发者声明的数据与用途。开发者可以在系统提示里写明什么时候查，例如「聊到作息时，先用 data_access_query 查 health.sleep」。
-
-**在自己的工具里查**
+**查询**
 
-调用 `conversation.platform.dataAccess.query`，不需要写进 `platformTools`：
+- 让模型查：`platformTools` 写上 `data_access_query`，工具说明里会列出声明过的 Dataset 与用途。可以在系统提示里写明什么时候查，比如「聊到作息时，先用 data_access_query 查 health.sleep」。
+- 在工具里查：调用 `conversation.dataAccess.query`。
 
 ```ts
-const [sleep] = await conversation.platform.dataAccess.query({ datasets: ["health.sleep"] });
+const [sleep] = await conversation.dataAccess.query({ datasets: ["health.sleep"] });
 if (sleep.status === "available") {
 	// sleep.data.items 是每天一条的睡眠记录
 }
 ```
 
-- `datasets`：一次最多 8 个；响应超过 512 KiB 时抛出异常，减少 Dataset 后重试。
-- `memberId`：私聊不传；群聊必须传，即群消息前缀 `[名字 #m_…]` 里的 `m_…`，查的是这位成员的数据。传错时直接抛出异常。
+- `datasets`：一次最多 8 个；响应超过 512 KiB 时抛异常，减少 Dataset 再查。
+- `memberId`：私聊不传；群聊必传，取群消息开头 `[名字 #m_…]` 里的 `m_…`，查这位成员的数据，传错时抛异常。
 
-**查询结果**
-
-每个 Dataset 各有一个状态，一个读不到不影响其他。只有 `available` 带 `data`：
+每个 Dataset 各自一个状态，只有 `available` 带 `data`：
 
 | 状态 | 意思 |
 |---|---|
 | `available` | 读到了 |
 | `notDeclared` | 搭子没有声明这项数据 |
-| `notGranted` | 用户没有同意，或改过用途后用户还没重新同意 |
+| `notGranted` | 用户没有同意，或改过用途后还没重新同意 |
 | `disabledInGroup` | 这位成员在这个群里关掉了这项数据 |
 | `unavailable` | 平台上还没有这位用户的这项数据，或数据已过期 |
 
-**数据只在这一轮回复里可见**
-
-一轮回复里只要查过授权数据，这一轮结束后，聊天记录和会话历史里这一轮的工具参数、工具结果与 thinking，都会换成「查了哪些数据、各是什么状态」，给用户看的回复照常保留。开发者自己写进记忆或小挂件的内容不会被替换，不要把查到的数据写进去。
+**数据只在当轮可见**
 
-#### 3.3.3 小挂件
-
-**登记类型**
+一轮回复里查过授权数据，这轮结束后，聊天记录和会话历史里这一轮的工具参数、工具结果与 thinking 都换成「查了哪些 Dataset、各是什么状态」，给用户的回复照常保留。写进记忆和小挂件的内容不会被替换，不要把查到的数据写进去。
 
-开发者通过平台 CLI 接口给搭子登记小挂件类型：`PUT /cli/buddies/:id/widget-types/:typeId/schema` 交 schema，每个模块写一句 `description` 给模型读，每条记录的形状是一份 JSON Schema；`PUT /cli/buddies/:id/widget-types/:typeId/page` 交展示页面，单个 HTML 文件。
+### 3.3 小挂件
 
-**让模型去用**
+小挂件是会话里一块给用户看的结构化面板，比如一份菜单。模型通过平台工具建小挂件、写记录、读记录、删记录，并把它发进聊天。
 
-`platformTools` 里写了哪几个 `widget_*`，运行时就注册哪几个：进程里第一次要用时拉一次 `GET /internal/v1/widget-types`，之后共用；工具说明里附上各类型的模块与字段；一个类型都没登记时一个也不注册。这场会话里已有哪些小挂件，由平台消息流里的 `context` 记录告诉模型。
+**登记类型**
 
-- 平台请求失败时工具抛出异常，模型看到的是「平台请求失败（HTTP 409），请查询最新状态后再操作」这样的提示，不带平台返回的具体原因。
-- `widget_create` 用 `widget-create:<toolCallId>` 作幂等键，同一次工具调用重发不会建出两个。
-- `widget_send` 把小挂件放进这场会话的发送队列就返回，不等平台确认送达。
+- `PUT /cli/buddies/:id/widget-types/:typeId/schema`：交 schema。每个模块写一句 `description` 给模型读，每条记录的形状是一份 JSON Schema。
+- `PUT /cli/buddies/:id/widget-types/:typeId/page`：交展示页面，单个 HTML 文件。
 
-**在自己的工具里用**
+**让模型使用**
 
-调用 `conversation.platform.widgets`，不需要写进 `platformTools`：
+把要用的 `widget_*` 写进 `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 状态码。写操作不自动重试，失败后先读一遍真实状态再决定。
+- 工具说明里附上各类型的模块与字段。类型在进程里第一次用到时读取，改了类型要重启进程。
+- 这场会话里已有哪些小挂件，平台会在消息里告诉模型，见第 4 节。
+- 平台请求失败时，模型只看到「平台请求失败（HTTP 409），请查询最新状态后再操作」这类提示，不带具体原因。
+- `widget_send` 把小挂件放进发送队列就返回，不等平台确认送达。
 
 用法见 [examples/aunt-tu/](examples/aunt-tu/)。
 
-#### 3.3.4 资料
+### 3.4 资料
 
-资料放在工程目录（`package.json` 所在目录）下的 `resources/`。工程目录由入口脚本向上定位，与启动进程的工作目录无关。
+把 `.md` 资料放进工程目录（`package.json` 所在目录）下的 `resources/`，`platformTools` 写上 `read_resource`，模型就能按需读。
 
-- 启动时递归读取 `.md`，跳过 `node_modules`、`venv`、`.venv`、`__pycache__` 及点开头的目录/文件；资料变更后需重启进程。
-- `platformTools` 里有 `read_resource` 时，系统提示末尾追加资料清单；模型通过清单中的相对路径读取内容。
-- 没有资料或名单里没有 `read_resource` 时，不注册 `read_resource`，也不追加资料清单。
+- 工程目录从入口脚本往上找，与启动时的工作目录无关。
+- 启动时递归读取 `.md`，跳过 `node_modules`、`venv`、`.venv`、`__pycache__` 与点开头的文件和目录；资料改了要重启进程。
+- 系统提示末尾追加资料清单，模型按清单里的相对路径读。没有资料或没选 `read_resource` 时，不注册工具，也不追加清单。
 
 ```
 my-buddy/                  工程目录
 ├─ package.json
-├─ resources/              资料目录
+├─ resources/
 │  └─ research/
-│     └─ 01-writings.md    清单中写作 research/01-writings.md
+│     └─ 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` 必填。
-- 会话已经删除或淘汰时直接抛出异常。
-
-**图片**
+### 3.5 主动服务
 
-用户发的图不需要开发者处理。平台在拉取消息时把图片内容一起给运行时，运行时把它放进会话历史，之后每次请求模型原样带上：
+让搭子在约定的时机主动找用户说话，比如每周一次复盘。只支持私聊。
 
-- 图片在用户上传时由平台统一处理成 JPEG，最长边不超过 2048 px、不超过 5 MiB。
-- 图片消息交给模型时是一条 user 消息：正文前标着「[图片 #消息 id]」，用户配了文字接在后面，再跟图片本身。
-- 引用了别的消息的，开头加一行：引用文字写「[引用 发言人：原话]」，引用图片写「[引用 发言人的图片 #被引消息 id]」，模型按 id 对上是哪一张。
-- 转发进聊天记录卡的图，跟在卡里那条正文后面。
-- 图片已经读不到时换成「[图片无法读取]」；`model` 选的模型不支持看图时换成「[图片：当前模型不支持看图]」。
+1. 开发者的工具调用 `conversation.proactive.propose` 提订阅建议。订阅建成时是 `pending`，用户在 App 里确认后才生效。
+2. 触发条件满足，且没被免打扰时段、冷却时间、每日上限拦下时，平台发起一次主动回合。
+3. 模型判断要不要开口：要就直接写出发给用户的消息，不要就输出跳过标记。平台复核后把消息发给用户。
 
-## 4. 会话历史：MLBMessage → AgentMessage → LLMMessage
-
-开发者不需要保存会话历史，也不需要把聊天里的消息换成模型消息，这些由运行时完成。每场会话的消息都保存在平台上，搭子进程重启后历史照样在。从平台上的 `MLBMessage` 到模型收到的 `LLMMessage`：
-
-```
-MLBMessage[] → AgentMessage[] → convertToLlm() → LLMMessage[] → LLM
-     ▲      (1)     │ ▲              (2)                         │
-     └─────(4)──────┘ └──────────────────(3)─────────────────────┘
+```ts
+await conversation.proactive.propose({
+	title: "每周复盘",
+	reason: "在约定时间结合最近聊天做一次简短复盘",
+	sources: ["schedule"],
+	eventTypes: ["schedule.due"],
+	allowedDataScopes: [],
+	schedule: { at: firstReviewAt, intervalMinutes: 7 * 24 * 60 },
+});
 ```
 
-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) 在模型每说完一段、每跑完一步工具时发生。
+| 字段 | 说明 |
+|---|---|
+| `title` | 必填，订阅名称，最长 100 字 |
+| `reason` | 必填，为什么要主动找用户，最长 500 字 |
+| `sources` | 必填，触发来源，`[]` 表示不限 |
+| `eventTypes` | 必填，至少一个，触发事件类型 |
+| `allowedDataScopes` | 必填，主动回合里允许读的 Dataset，只能从已声明的里选，`[]` 表示不读 |
+| `schedule` | 可选，定时触发：`at` 为首次时刻（UTC 毫秒），`intervalMinutes` 为重复间隔（60～525600），按固定间隔算，不随夏令时调整。用它时 `eventTypes` 要含 `schedule.due`，`sources` 为 `[]` 或含 `schedule` |
+| `quietHours` | 可选，免打扰时段，缺省 `{ start: "22:30", end: "08:00", timezone: "Asia/Shanghai" }` |
+| `cooldownMinutes` | 可选，冷却时间，缺省 120，取 0～10080 |
+| `dailyLimit` | 可选，每天最多几次，缺省 3，取 1～20 |
 
-## 5. 环境变量
+字段不合法、在群聊里调用，或同一用户对这只搭子已有 20 个未撤销的订阅时抛异常，异常信息只有 HTTP 状态码。
 
-| 变量 | 说明 |
-|---|---|
-| `MLB_BUDDY_ID` | 搭子 id，注册时由平台分配 |
-| `MLB_BUDDY_TOKEN` | 搭子令牌，注册时由平台分配 |
+主动回合里：
 
-`MLB_GATEWAY_URL` 可覆盖平台网关。当前缺省为 ecs-test（`http://47.116.168.81:8788`）；本地测试必须显式配置回环地址及虚拟凭据，不能用正式搭子 Token 启动第二个进程。
+- **模型能用的工具只有 `proactiveTools` 里点名的那些，默认一个都没有。** 用户不在场，所以不默认信任任何工具——名字叫 `read_xxx` 的也可能在里面发请求、写外部系统。没点名的工具模型仍然看得见，调了会被挡回一条说明，工具本身不执行。`data_access_query` 另外只能读订阅的 `allowedDataScopes`。
+- 系统提示和普通回合一字不差，记忆不会被附上去。要让模型用记忆，自己把 `conversation.memory.list` 包成工具注册进来，再写进 `proactiveTools`。
+- 调用 `memory.write`、`memory.delete`、`proactive.propose` 会抛异常；开发者的钩子照常执行。
+- 用户这时发来消息，主动回合中止，先回复用户；超过 4 分钟也中止。
+- 主动回合的过程不下发给用户：平台在会话流里记两条不可见的记录（叫你判断了什么、你判断的结果），中间的工具步照常写回但也不下发。**开口的那条消息才是用户看得到的**，之后作为搭子说过的话出现在会话历史里。
 
-搭子的档案（名称、头像、简介）由平台保存：注册时通过 `POST /cli/buddies` 提交，修改通过 `PUT /cli/buddies/:id/meta`。搭子进程不监听端口、不接收入站请求。从非回环地址连接网关时，平台将其识别为 `<id>-dev` 分身，会话与正式身份隔离。
+## 4. 模型收到什么
 
-## 6. 开发
+开发者不用保存会话历史，也不用自己拼模型消息。每场会话的消息存在平台上，进程重启后运行时从平台取回。每次请求模型时，运行时组出以下内容。
 
-- 改完代码需要自动重启时，自行在 `package.json` 里用 `node --watch` 启动。
-- 会话消息拉取遇到临时网络错误时会主动指数退避重试（1 秒起步、最高 30 秒）；新的 SSE 通知会取消等待并立即重拉。
+**系统提示**，按顺序拼接，段间空一行：
 
-## 7. 主动服务
+1. 平台的系统提示：对每场会话都一样的规则，比如消息开头的时间怎么读、用户所在时区去哪看。
+2. `initialState.systemPrompt`。
+3. 资料清单：选了 `read_resource` 且有资料时才有。
 
-Runtime 消费平台 SSE `proactive {runId}`，领取 Run 后恢复对话、临时召回会话 Memory，并让模型按需查询授权 Dataset。数据查询携带短期执行令牌；最终 send/skip 结果由平台复核和落库，不经过普通消息写口。
+**工具**：选中的平台工具在前，`initialState.tools` 在后。
 
-主动回合仅开放 `platformTools` 已选择的 `data_access_query` 和 `read_resource`，不会自动增加工具。临时 Trigger、Memory 注入和工具数据在结束后移除；普通用户消息到达会中止主动生成并优先回复。执行重试归平台，Runtime 不自行维护调度器。
+**消息**：这场会话的完整历史，按时间先后排列。一轮回复里模型可能请求多次，比如调完工具接着说，每次都带上当时的完整历史。
 
-普通聊天中的开发者工具可提出订阅建议：
+- 用户消息、工具结果、运行时提醒的开头带 GMT 时间，如「[2026-09-10 14:00:30 GMT] 」；搭子自己说的话不带。
+- 历史末尾多一条「现在的时间（平台附注，不是谁说的话）」，时间是请求时刻，只在这一次请求里。
+- 群聊里成员说的话开头标「[名字 #m_…] 」。
+- 平台交代的情况（比如这场会话里已有哪些小挂件）是一条以「平台交代的情况：」开头的消息，情况有变化才追加新的一份。
+- 引用了别的消息时，开头加一行「[引用 发言人：原话]」，引用图片写「[引用 发言人的图片 #被引消息 id]」。
+- 转发的聊天记录卡按条目展开，每条先写「【名字】」再写正文。
+- 查过授权数据的那一轮，结束后按 3.2 替换。
 
-```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 时间戳；固定间隔不承诺夏令时地区的墙上时间不变。
+- 平台在上传时统一处理成 JPEG，最长边不超过 2048 px、不超过 5 MiB。
+- 图片消息是一条 user 消息：先是「[图片 #消息 id]」和用户配的文字，再跟图片本身；聊天记录卡里的图跟在所在条目的正文后面。
+- 图片读不到时换成「[图片无法读取]」；`model` 不支持看图时换成「[图片：当前模型不支持看图]」。
 
-此能力要求匹配的 Proactive Server 版本。旧 Server 不支持这些端点，不会自动降级为直接主动写消息。
+在钩子里读会话历史时，除了 pi 的 `user` / `assistant` / `toolResult`，还会遇到 `role` 为 `note` 的消息：运行时补给模型的提醒，比如一轮回复没说出话时的提示，发给模型时换成 user 消息。

package/dist/conversation/agent.d.ts

@@ -1,13 +1,13 @@
 import { Agent } from "@earendil-works/pi-agent-core";
-import type { AgentEvent, AgentMessage, AgentTool, StreamFn } from "@earendil-works/pi-agent-core";
+import type { AgentEvent, AgentMessage, 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, MLBMessageToWrite } from "../types.ts";
 export interface AgentDeps {
-    signal?: AbortSignal;
-    enqueueMessage?: (message: MLBMessageToWrite) => void;
+    /** 这场会话的发送队列：widget_send 把小挂件引用放进来 */
+    enqueueMessage: (message: MLBMessageToWrite) => void;
     onPolicyStop?: () => void;
     key: string;
     buddyId: string;
@@ -29,7 +29,6 @@ export interface AgentDeps {
 export interface CreatedAgent {
     agent: Agent;
     dataAccessUsage: DataAccessUsageTracker;
-    proactiveReadTools: AgentTool[];
 }
 export declare function createAgent(deps: AgentDeps): Promise<CreatedAgent>;
 /**

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,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"}
+{"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,sCAAsC;IACtC,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,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,CAmHxE;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"}