@my-life-buddies/buddy-runtime 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -8,6 +8,37 @@
 
 0.23.0 及更早的版本未记录。
 
+## 0.30.0（2026-10-27）
+
+不兼容改动：有
+
+### 不兼容改动
+
+- `ModelId` 移除 `deepseek-v4-flash`、`deepseek-v4-pro` 和 `glm-5.3`。`initialState.model` 或 `configureTurn` 返回的 `model` 使用这三个值时，开发者需改为 `kimi-k2.6`、`kimi-k3`、`deepseek-v4.1-flash-1017` 或 `MiniMax-M3`；否则类型检查失败，创建会话时也会报错。
+- 已发布且内含旧版 Runtime 的搭子产物不会随 npm 发版自动升级；只有升级 Runtime 的工程需要调整上述配置。
+
+### 新增
+
+- 新增主聊模型 `deepseek-v4.1-flash-1017`，支持文字与图片输入，上下文窗口为 1,048,576 tokens，输出上限为 384,000 tokens。
+- 当前四个可选主聊模型均支持图片输入，并提供运行时内置的 `view_image` 工具读取历史图片。
+
+## 0.29.0（2026-10-26）
+
+不兼容改动：有
+
+### 不兼容改动
+
+- 内置 `data_access_query` 查询 `xhs_user_behaviour_data` 时，由返回完整 `data.memory` 改为先返回 `data.view="index"` 和片段目录，再通过 `profileRead: { version, sectionId }` 读取正文。依赖该工具原始结果的代码需适配目录与片段；`conversation.dataAccess.query` 的原始 Dataset 契约保持不变。
+- 画像工具对未知 JSON 封装不再按纯文本返回；旧纯文本和 XML 继续按大小分片。
+
+### 新增
+
+- 新增可选 `initialState.imageModel`、`conversation.image.generate`、`generateAndSend` 及对应模型工具，支持生成图片和使用参考图片改图；生图请求不会自动重试。
+- `image.send` 和 `send_image` 支持通过 `mediaId` 发送已存图片，等待消息保存后返回 `messageId`。原有按字节、文件和 URL 发图的调用方式及完成标准保留。
+- 新增小红书资料与行为画像 Dataset，以及 `platformAuthorizationRequired`、`bindingRequired` 授权状态和绑定授权卡，需要平台支持。
+- 画像按目录和片段读取，每段最多 4 KiB，每回合目录及片段 JSON 合计最多 24 KiB；主题目录每页最多 8 项，可通过 `profileOffset` 翻页。画像版本变化时重新返回目录，读取过程持续校验授权。
+- 新增可选 `beforeReply`，在需要回复的用户消息交给模型前执行；返回 `true` 表示已由开发者处理，本次不调用模型。
+
 ## 0.28.0（2026-10-19）
 
 不兼容改动：无（相对正式版 0.27.0）

package/README.md

@@ -110,9 +110,12 @@ import type {
 interface BuddyOptions {
 	// 必填。这场会话的初始状态
 	initialState: {
-		// 必填。模型 id，ModelId 是 "kimi-k2.6" | "kimi-k3" | "deepseek-v4-flash" | "deepseek-v4-pro" | "glm-5.3" | "MiniMax-M3"。每场会话可以选不同的模型
+		// 必填。模型 id，ModelId 是 "kimi-k2.6" | "kimi-k3" | "deepseek-v4.1-flash-1017" | "MiniMax-M3"，都支持图片输入。每场会话可以选不同的模型
 		model: ModelId;
 
+		// 可选。独立的生图模型，如 "Doubao-Seedream-5.0-lite"；调用生图方法或选用两个生图工具时必填
+		imageModel?: string;
+
 		// 必填。人设与做事规则。为保证模型缓存，只放不随回合变化的内容
 		systemPrompt: string;
 
@@ -127,6 +130,10 @@ interface BuddyOptions {
 	// 可选。模型出错或一句话没说时发的兜底回复，用户和模型之后都看得到；主动服务的回合不发
 	errorReply?: string;
 
+	// 可选。每条需要回复的用户消息送模型前调用，可按消息判断是否需要数据。返回 true 表示已自行处理（例如发授权卡），本轮不调用模型。
+	// 适合对必须先授权的数据做确定性检查，不依赖模型主动调用工具。
+	beforeReply?: (messages: readonly AgentMessage[]) => boolean | void | Promise<boolean | void>;
+
 	// 可选。工具执行前调用，context 里有这次的 toolCall、校验过的 args 和当前上下文。
 	// 返回 { block: true, reason } 时工具不执行，模型看到 reason；抛异常时工具也不执行，模型看到异常信息
 	beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
@@ -142,84 +149,23 @@ interface BuddyOptions {
 
 ### 2.3 `Conversation`
 
-`buddy` 拿到的参数，工具闭包里也能用。
-
-```ts
-interface Conversation {
-	// 会话键：私聊以 p_ 开头，群聊以 g_ 开头。开发者自己存的数据要按它隔离
-	key: string;
-
-	// 日志，每行开头带搭子 id
-	log: BuddyLogger;
-
-	// 平台工具，见第 3 节：运行时造好、绑好这场会话，挑要用的放进 initialState.tools
-	tools: {
-		resource_list: AgentTool;
-		resource_read: AgentTool;
-		ask_question: AgentTool;
-		data_access_query: AgentTool;
-		data_access_request: AgentTool;
-		buddy_relationship_request?: AgentTool;
-		widget_create: AgentTool;
-		widget_read: AgentTool;
-		widget_read_module: AgentTool;
-		widget_rename: AgentTool;
-		widget_write_record: AgentTool;
-		widget_delete_record: AgentTool;
-		widget_send: AgentTool;
-		send_image: AgentTool;
-	};
-
-	// 资料，见 3.1：resources/ 里的 .md，进程启动时读好，所有会话共用
-	resource: {
-		list(): string[];
-		read(file: string): string;
-	};
-
-	// 发图，见 3.4：把开发者自己拿到的图片字节发进聊天流
-	image: {
-		send(input: { bytes: Uint8Array; mimeType: "image/jpeg" | "image/png" | "image/webp"; text?: string; idempotencyKey: string }): Promise<void>;
-	};
-
-	// 记忆，见 3.5：这场会话的长期记忆，存在平台上
-	memory: {
-		list(): Promise<MemoryEntry[]>;
-		write(key: string, text: string): Promise<void>;
-		delete(key: string): Promise<void>;
-	};
-
-	// 授权数据，见 3.6：私聊不传 memberId，群聊传消息前缀里的 m_…
-	dataAccess: {
-		query(request: { datasets: string[]; memberId?: string }): Promise<DatasetAccessResult[]>;
-		request(input: DataAccessRequestInput & { idempotencyKey: string }): Promise<void>;
-	};
-
-	// 小挂件，见 3.7
-	widget: {
-		list(): Promise<WidgetSummary[]>;
-		create(input: { type: string; title: string; idempotencyKey?: string }): Promise<{ id: string }>;
-		read(id: string): Promise<Widget>;
-		readModule(id: string, module: string): Promise<{ records: WidgetRecord[] }>;
-		rename(id: string, title: string): Promise<void>;
-		writeRecord(
-			id: string,
-			input: { module: string; recordId: string; data: Record<string, unknown>; expectedRevision?: number },
-		): Promise<{ revision?: number }>;
-		deleteRecord(id: string, module: string, recordId: string): Promise<void>;
-		setPresentation(id: string, input: { summary: string; imageMediaId: string }): Promise<void>;
-		send(id: string, options: { idempotencyKey: string; openTarget?: WidgetOpenTarget }): void;
-	};
+`buddy` 工厂拿到的当前会话对象。方法已绑定这场私聊或群聊，开发者可以在工具回调或其他会话业务代码中调用，不需要重复传会话键。
 
-	// 主动服务，见 3.8：按稳定 key 订阅、查询和关闭；isRunning 判断现在是不是主动服务的回合
-	proactive: {
-		subscribe(key: string, request: ProactiveSubscriptionRequest): Promise<ProactiveSubscription>;
-		list(): Promise<ProactiveSubscription[]>;
-		unsubscribe(key: string): Promise<boolean>;
-		unsubscribeAll(): Promise<number>;
-		isRunning(): boolean;
-	};
-}
-```
+| 成员 | 用途与详细说明 |
+|---|---|
+| `key` | 会话键，类型为 `string`；私聊以 `p_` 开头，群聊以 `g_` 开头，开发者自己的会话数据按它隔离 |
+| `log` | `BuddyLogger`，日志带搭子编号 |
+| `tools` | 平台提供的模型工具，按需放进 `initialState.tools`；见下方平台能力表 |
+| `resource` | 读取工程里的只读资料，见 [3.1 资料](#31-资料) |
+| `search` | 搜索网页或小红书，见 [3.2 搜索](#32-搜索) |
+| `image` | 生成、发送、生成并发送图片，见 [3.4 图片消息](#34-图片消息) |
+| `memory` | 读写当前会话的长期记忆，见 [3.5 记忆](#35-记忆) |
+| `dataAccess` | 查询用户授权数据、请求授权，见 [3.6 用户授权数据](#36-用户授权数据) |
+| `widget` | 创建、修改和发送小挂件，见 [3.7 小挂件](#37-小挂件) |
+| `proactive` | 管理主动服务订阅，见 [3.8 主动服务](#38-主动服务) |
+| `product` | 展示商品、读取和管理服务凭证，见 [3.9 商品与模拟购买](#39-商品与模拟购买) |
+
+各方法的参数、返回值和调用示例集中在对应能力一节。
 
 ## 3. 平台能力
 
@@ -228,7 +174,7 @@ interface Conversation {
 | 资料 | `conversation.resource.list` / `conversation.resource.read` | `resource_list` / `resource_read` |
 | 搜索 | `conversation.search.web` / `conversation.search.rednote` | `search_web` / `search_rednote` |
 | 提问 | 无 | `ask_question` |
-| 图片消息 | `conversation.image.send` | `send_image`（resources/ 里的文件或公网地址） |
+| 图片消息 | `conversation.image.generate / send / generateAndSend` | `generate_image`、`send_image`、`generate_and_send_image`，与方法职责对应 |
 | 记忆 | `conversation.memory` | 无，开发者可以根据具体场景，自己组装成适合的模型工具 |
 | 用户授权数据 | `conversation.dataAccess.query` / `conversation.dataAccess.request` | `data_access_query` / `data_access_request` |
 | 搭子关系 | 无 | `buddy_relationship_request` |
@@ -246,7 +192,7 @@ buddy: (conversation) => ({
 }),
 ```
 
-`conversation` 上的方法在自己的模型工具里调，各节「`conversation` 对象方法」下都有一个完整的注册例子。
+`conversation` 上的方法供开发者代码直接调用，也可以封装成业务专用的模型工具；`conversation.tools` 上的工具由平台提供，选入 `initialState.tools` 后主聊模型才能调用。
 
 ### 3.1 资料
 
@@ -439,69 +385,119 @@ await BuddyServer.start((conversation) => ({
 
 ### 3.4 图片消息
 
-用户发送图片消息：模型自己看得到，不用开发者做任何事，模型不支持图片输入（如 deepseek 系列）时看不到图。
-搭子发送图片消息：图从哪来不限：`resources/` 里的文件、搜索结果里的配图地址、搭子自己生成或其他方式，都通过接口上传图片，在消息里展现上传的图片（本质上和用户发送图片消息一样）。
+搭子可以看用户发来的图片、生成或修改图片，也可以发送已有图片。图片消息发进当前私聊或群聊；修改图片会发送一张新图，原图保留。
+
+新图片直接交给主聊模型；历史中只保留图片编号时，通过 `view_image` 取回内容。这个工具由 runtime 自动提供，不在 `conversation.tools` 上，无需开发者注册，自定义工具也不能使用这个名字。
 
 **`conversation` 对象方法**
 
 | 方法 | 做什么 |
 |---|---|
-| `image.send(input)` | 把一份图片字节传给平台，再写一条图片消息 |
+| `image.generate(input, signal?)` | 只生成并保存图片，返回 `mediaId`，不发送聊天消息 |
+| `image.send(input, signal?)` | 发送已有图片；传字节时上传并入队后返回，传 `mediaId` 时等待消息保存并返回 `mediaId` 和 `messageId` |
+| `image.generateAndSend(input, signal?)` | 生成并发送，等待消息保存后返回 `mediaId` 和 `messageId` |
+
+方法供开发者代码直接调用，不依赖工具注册。生图使用 `initialState.imageModel`，应在工厂返回配置后调用；只发送已有图片不需要配置生图模型。`Conversation`、`ImageSendInput`、`ImageSendResult` 均可从 runtime 导入，类型中可选的方法在调用前先检查是否存在。
 
 ```ts
-image: {
-	send(input: { bytes: Uint8Array; mimeType: "image/jpeg" | "image/png" | "image/webp"; text?: string; idempotencyKey: string }): Promise<void>;
+type ImageSendInput = (
+	{ bytes: Uint8Array; mimeType: "image/jpeg" | "image/png" | "image/webp"; mediaId?: never }
+	| { mediaId: string; bytes?: never; mimeType?: never } // 与图片字节二选一，须属于本搭子、本会话
+) & {
+	text?: string; // 可选配文，最多 500 字；默认无配文
+	idempotencyKey: string; // 非空；同一次发送沿用同一个键，只防止重复写消息，不能防止重复生图
+};
+interface ImageSendResult {
+	mediaId: string; // 已存图片的媒体编号，用于发送
+	messageId: string; // 已保存的图片消息编号，用于看图和参考图
+}
+interface Conversation {
+	image: {
+		generate?(input: {
+			prompt: string; // 必填，1 到 4000 字，本次完整画面要求
+			referenceMessageIds?: string[]; // 默认无参考图；当前会话的图片消息编号，按顺序填写，最多 14 张且不能重复
+		}, signal?: AbortSignal): Promise<{ mediaId: string }>;
+
+		send(input: Extract<ImageSendInput, { bytes: Uint8Array }>, signal?: AbortSignal): Promise<void>; // 字节上传并入队后返回
+		send(input: Extract<ImageSendInput, { mediaId: string }>, signal?: AbortSignal): Promise<ImageSendResult>; // 等消息保存后返回
+
+		generateAndSend?(input: {
+			prompt: string; // 与 generate 相同
+			referenceMessageIds?: string[]; // 与 generate 相同
+			text?: string; // 与 send 相同
+			idempotencyKey: string; // 与 send 相同
+		}, signal?: AbortSignal): Promise<ImageSendResult>;
+	};
 }
 ```
 
-注册成模型工具：
+生图方法也可以参考当前会话的图片。例如，先生成并发送一个蓝色圆形，再把它改成橙色：第二次调用将前一张图的 `messageId` 放入 `referenceMessageIds`，`prompt` 写明「以图 1 为底图，只把圆形改成橙色，保留背景、构图和大小」。多张参考图按数组顺序对应图 1、图 2；卡片内图片使用「消息编号/第几张」。
+
+注册成模型工具：下面的业务工具只让模型填写活动标题，由开发者代码确定海报风格并调用 `image.generateAndSend`。
 
 ```ts
 await BuddyServer.start((conversation) => {
-	const SEND_CHART_PARAMS = Type.Object({ week: Type.String({ description: "哪一周，如 2026-W41" }) });
-	const sendWeightChart: AgentTool<typeof SEND_CHART_PARAMS, undefined> = {
-		name: "send_weight_chart",
-		label: "正在画体重曲线",
-		description: "把这一周的体重曲线画成图发给用户。",
-		parameters: SEND_CHART_PARAMS,
-		execute: async (toolCallId, { week }) => {
-			const png = await renderWeightChart(week); // 自己的画图代码，回 PNG 字节
-			await conversation.image.send({ bytes: png, mimeType: "image/png", text: `${week} 的体重曲线`, idempotencyKey: `weight-chart:${toolCallId}` });
-			return { content: [{ type: "text", text: "曲线图已发给用户。" }], details: undefined };
+	const PARAMS = Type.Object({ title: Type.String({ description: "活动标题" }) });
+	const makePoster: AgentTool<typeof PARAMS, undefined> = {
+		name: "make_event_poster",
+		label: "正在制作活动海报",
+		description: "根据活动标题生成并发送一张海报。成功后不要重复发送，失败时不要自行再次生成。",
+		parameters: PARAMS,
+		execute: async (callId, { title }, signal) => {
+			if (!conversation.image.generateAndSend) throw new Error("请使用支持生图的 runtime 版本");
+			const { messageId } = await conversation.image.generateAndSend({
+				prompt: `制作活动海报，标题为「${title}」，白底蓝字，简洁排版。`,
+				idempotencyKey: `event-poster:${callId}`,
+			}, signal);
+			return { content: [{ type: "text", text: `海报消息已保存。内部引用：[图片 #${messageId}]，供看图与后续改图使用，不向用户展示编号。` }], details: undefined };
 		},
 	};
-	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [sendWeightChart] } };
+	return { initialState: { model: "kimi-k3", imageModel: "Doubao-Seedream-5.0-lite", systemPrompt: "按用户要求制作海报。", tools: [makePoster] } };
 });
 ```
 
 **内建模型工具**
 
+不需要自定义业务逻辑时，直接从 `conversation.tools` 选择工具放进 `initialState.tools`，主聊模型就能调用。三个工具与上面的三个方法职责对应，均不会自动注册。
+
 | 工具 | 参数 | 结果 |
 |---|---|---|
-| `send_image` | `file` 与 `url` 二选一：`file` 是 `resources/` 里的图片路径（.jpg / .jpeg / .png / .webp）；`url` 是图片的公网 http(s) 地址，比如 `search_rednote` 结果里的配图。`text` 可选，配一句话 | 图片进入发送队列 |
+| `generate_image` | `prompt`、可选 `referenceMessageIds`，含义与 `image.generate` 相同 | 只生成，返回 `mediaId`，尚未发送 |
+| `send_image` | `mediaId`、`file`、`url` 三选一，可附 `text`；`file` 是 `resources/` 内图片路径，`url` 是公网图片地址 | 传 `mediaId` 时等待消息保存并返回编号；文件或网址读取后上传，入队后返回 |
+| `generate_and_send_image` | `prompt`、可选 `referenceMessageIds` 和 `text`，含义与 `image.generateAndSend` 相同 | 生成并发送，返回 `mediaId` 和 `messageId` |
 
-```ts
-await BuddyServer.start((conversation) => ({
-	initialState: {
-		model: "kimi-k3",
-		systemPrompt: "……搜到的笔记里有合适的配图，挑一两张用 send_image 发给用户，配一句说明。",
-		tools: [conversation.tools.search_rednote, conversation.tools.send_image],
-	},
-}));
-```
+普通画图回复选入 `generate_and_send_image` 即可；需要生成、发送分开控制时，再选 `generate_image` 和 `send_image`。工具的消息幂等键由 runtime 填写。`systemPrompt` 说明什么时候生图、成功后不重复发送、失败时等待用户决定：
 
-**限制与异常**
+```ts
+import { BuddyServer } from "@my-life-buddies/buddy-runtime";
 
-`image.send` 与 `send_image` 都受：
+await BuddyServer.start((conversation) => {
+	const generateAndSend = conversation.tools.generate_and_send_image;
+	if (!generateAndSend) throw new Error("请使用支持生图的 runtime 版本");
+	return {
+		initialState: {
+			model: "kimi-k3",
+			imageModel: "Doubao-Seedream-5.0-lite",
+			systemPrompt: "用户要求画图或改图时用 generate_and_send_image。成功后不要重复发送或生成，不向用户展示内部编号。失败时告知用户，等待用户决定。",
+			tools: [generateAndSend],
+		},
+	};
+});
+```
 
-- 原图不超过 5 MiB、宽高不超过 4096，否则抛异常；平台把图缩到最长边 2048 px、去掉 EXIF，格式不变（PNG 透明保留），处理后超过 5 MiB 也抛异常。
+`model` 负责聊天并决定何时调用工具，`imageModel` 负责实际生图，二者分别配置。平台管理生图模型的接口和凭据，开发者只填写模型名称。
 
-`send_image` 另有，不满足即抛异常：
+使用内建生图工具改图时，由主聊模型将底图放在 `referenceMessageIds` 首位，再放必要的原图和历史版本，并在 `prompt` 中保留仍有效的画面要求。历史图片不会自动传给生图模型；`view_image` 只用于查看细节，不会自动加入参考图。内部编号不向用户展示。
 
-- `url`：http(s)；不收 localhost 和私网 IP；不跟重定向；30 秒超时；响应 Content-Type 须为 JPEG、PNG 或 WebP。
-- `file`：须在 `resources/` 内，扩展名为 .jpg / .jpeg / .png / .webp。
+**限制与异常**
 
-开发者自己的工具不能叫 `view_image`：运行时内部用这个名字，重名时建会话抛异常。
+- 生图不自动重试。超时、断线或取消可能已产生费用，结果未确认时等待用户决定。生成成功但发送失败时，`generateAndSend` 的报错保留 `mediaId` 和消息幂等键；确认需要重发后，只发送同一 `mediaId` 并沿用原键，不要重新生图。取消等待不撤回已入队的消息。
+- 选入生图工具却未配置 `imageModel` 时，创建会话 Agent 报错；只使用方法时，在调用时检查配置。平台未配置或不支持模型时，明确提示本次没有调用生图服务。
+- 每次生成一张 2048 × 2048 图片。
+- 参考图使用图片消息的 `messageId`，不能填用于发送的 `mediaId`；只生成但未发送的图片不能直接作为参考图。参考图无权限、编号重复、超限或读取失败时停止生成，不忽略参考图继续生成。
+- 发送图片字节、文件或地址时，每次重新上传。原图不超过 5 MiB、宽高不超过 4096；平台缩到最长边 2048 px、去掉 EXIF，保留格式和透明。处理后超过 5 MiB 时拒绝。发送 `mediaId` 不重复上传，平台检查会话归属。
+- `send_image` 的 `file` 只收 `resources/` 内 .jpg／.jpeg／.png／.webp；`url` 只收 HTTP(S)，拒绝 localhost 和字面量私网 IP，不跟重定向，30 秒超时，响应须为 JPEG／PNG／WebP。
+- 查询过用户授权数据的回合不能生图，直接调用方法与模型工具都检查；主动服务回合采用相同规则。
 
 ### 3.5 记忆
 
@@ -580,7 +576,7 @@ await BuddyServer.start((conversation) => {
 
 ### 3.6 用户授权数据
 
-用户同意后，搭子可以读用户的睡眠、运动、位置、日程等数据。数据按 Dataset 分项，用户逐项同意。搭子拿不到用户的真实 id。查到的数据只在当轮可见，见本节末尾。
+搭子可以按声明读取睡眠、运动、位置、日程和小红书数据。用户按 Dataset 授权给当前搭子；小红书登录只负责绑定账号，模型使用公开资料或画像前均需取得这项授权。搭子拿不到用户的真实 id。查到的数据只在当轮可见，见本节末尾。
 
 这里有三层不同概念：
 
@@ -643,7 +639,21 @@ const sleep = dataAccessCapability("health.sleep");
 | `device.location` | 当前位置 | `latitude`、`longitude`、`accuracy`、`timestamp` |
 | `device.calendar` | 未来日程 | `events` 数组，每条含 `title`、`startAt`、`endAt`、`isAllDay`、`calendar` |
 
-部分字段可能缺失，取值前先判断。
+小红书公开资料与行为画像使用同一项声明：
+
+| Dataset | `data` 内容 | 使用条件 |
+|---|---|---|
+| `xhs_user_behaviour_data` | `publicData` 为昵称、头像、简介及最多 20 条公开发布笔记 ID 样本；`memory` 为经过上游过滤的 RedKV 画像；收藏暂不透传 | 绑定小红书账号且用户授权给当前搭子；两个来源独立读取，部分缺失时只返回实际取得的部分 |
+
+```json
+{
+  "requirements": [
+    { "id": "xhs_user_behaviour_data", "purpose": "根据用户的小红书行为偏好数据，做精准的规划推荐" }
+  ]
+}
+```
+
+部分字段可能缺失，取值前先判断。画像来自已有的点点 Memory，搭搭不生成画像。两个上游都不可用时返回 `unavailable`，不要等待生成或重复申请授权。合并后的 Schema 为 v2；旧授权不会自动扩展范围，声明升级后用户需重新确认。旧 `xhs.profile` 和 `xhs.contentProfile` 声明继续识别，不自动转换为新授权。
 
 **`conversation` 对象方法**
 
@@ -667,7 +677,7 @@ interface DataAccessQuery {
 
 type DatasetAccessResult =
 	| { id: string; status: "available"; schemaVersion: number; revision: number; sourceUpdatedAt: number; data: Record<string, unknown> }  // data.items 的字段见上面各 Dataset 那张表
-	| { id: string; status: "notDeclared" | "notGranted" | "disabledInGroup" | "unavailable" | "systemPermissionDenied" };
+	| { id: string; status: "relationshipRequired" | "notDeclared" | "notGranted" | "platformAuthorizationRequired" | "bindingRequired" | "disabledInGroup" | "unavailable" | "systemPermissionDenied" };
 
 interface DataAccessRequestInput {
 	reason: string;      // 为什么要这些数据，用户在授权卡上看到的就是这句
@@ -701,6 +711,18 @@ await BuddyServer.start((conversation) => {
 
 把 `conversation.tools.data_access_query`、`data_access_request` 放进 `initialState.tools`，模型就能自己查数据、发授权卡。放进去只决定模型能不能调用它们，不等于声明 Dataset，也不等于获得用户授权；没声明 Dataset 时照常注册，查询的每一项都回 `notDeclared`。
 
+业务明确某类问题必须先完成授权时，可在 `beforeReply(messages)` 中判断本轮消息、调用 `conversation.dataAccess.query` 检查状态；返回 `notGranted` 后调用 `conversation.dataAccess.request` 并返回 `true`。授权卡写回后本轮不会调用模型。用户处理授权卡后开启的新回合再次经过检查，再由模型按需读取目录和主题。
+
+查询 `xhs_user_behaviour_data` 时采用渐进式披露：首次不传 `profileRead`，返回 `data.view="index"`、可用的 `publicData`、`version` 和画像目录。结构化主题目录每页最多 8 项，字段为 `sectionId/topic/time/preference?/description`，不含具体详情；需要下一页时单独查询该 Dataset 并传入 `profileOffset: nextOffset`。旧文本目录使用 `sectionId/preview`，预览是片段开头最多 48 个字符，不是摘要。模型确有需要时，再单独查询该 Dataset 并传入 `profileRead: { version, sectionId }`，得到 `data.view="section"` 和 `text`，不会重复公开资料。只有公开资料时返回 `publicOnly`，只有画像时目录标记 `publicDataStatus="unavailable"`。不要遍历整份画像；`profileOffset` 与 `profileRead` 不能同时传。
+
+每段正文最多 4 KiB；同一回合所有成员的目录及片段 JSON 合计最多 24 KiB，重复读取也计入预算，耗尽返回 `budgetExceeded`。每次读取都重新查询平台权限；画像版本或成员改变时返回新目录，撤权时只返回权限状态。未知格式或超过 128 KiB 输入上限的画像返回 `unsupported`，不会退回全文。输入上限只约束 Runtime 接收的画像大小，模型仍按页读取目录和片段。
+
+这一限制作用于内置模型工具。`conversation.dataAccess.query` 仍返回原始 Dataset，供自定义业务代码处理；自定义工具也应按需选择字段，避免把完整 `memory` 放入提示词或工具结果。`memory` 可为主题对象或主题数组的 JSON 文本，主题字段按[画像逻辑细化 - 2026.10](https://docs.xiaohongshu.com/doc/eb9ad825bf1fabcd80913d7b4f6ac410)识别：`主题`、`关注时间`、可选数值 `偏好程度`、`描述`、字符串数组 `具体详情`。主题目录只含最多 50 字描述，正文只含详情，不透传未知字段；未知 JSON 封装返回 `unsupported`。文档没有定义 RedKV 的 value 外层封装，多主题数组为本地适配约定，实际接入时需确认。
+
+旧纯文本和 XML 按 UTF-8 大小分片；超长主题详情也按此规则续分。偏好分沿用上游值，不当作概率或重新计算；浏览、点赞、收藏和分享不代表用户亲身经历。
+
+平台提示词要求只读取当前问题相关的主题，分数高或领域相近不构成额外读取理由。回答区分画像记载、用户确认和待确认信息：未返回来源时不推测来自哪种行为，画像中的问句不当作已确定安排；用户限定只依据画像时，不补充未经验证的路线、价格等外部结论。这是模型使用规则，仍需通过实际调用与回答记录核验遵守情况。
+
 先查询，缺授权再发卡：
 
 ```ts
@@ -741,6 +763,8 @@ data_access_query
 | `available` | 读到了 |
 | `notDeclared` | 搭子没有声明这项数据 |
 | `notGranted` | 用户没有同意，或改过用途后还没重新同意 |
+| `platformAuthorizationRequired` | 旧服务返回的状态，提示升级服务后重试，不发送授权卡 |
+| `bindingRequired` | 小红书账号尚未完成可信绑定，可发卡引导绑定 |
 | `relationshipRequired` | 目标成员还没有添加当前搭子；群聊里可先发搭子名片 |
 | `disabledInGroup` | 这位成员在这个群里关掉了这项数据 |
 | `unavailable` | 平台上还没有这位用户的这项数据，或数据已过期 |
@@ -754,7 +778,7 @@ data_access_query
 `dataAccess.request` 与 `data_access_request`：
 
 - `relationshipRequired` 应先用 `buddy_relationship_request` 发搭子名片。
-- 发卡前须在同一回合查过对应 Dataset 且结果为 `notGranted`；`systemPermissionDenied` 引导用户去系统设置，其余状态不发卡。
+- 发卡前须在同一回合查过对应 Dataset，状态为 `notGranted`，或小红书画像为 `bindingRequired`；`systemPermissionDenied` 引导用户去系统设置，其余状态不发卡。
 - 群聊里查询与发卡用同一个 `memberId`，取消息前缀里的 `#m_…`；卡片全群可见，只有目标成员能操作。
 - 发卡后本回合结束。
 
@@ -777,6 +801,8 @@ data_access_query
 - **不要把查到的数据往长期存的地方搬**。往 `memory` / `widget` / `proactive` 里写会被 Runtime 直接拒收；开发者工具未声明策略时按 `external` 拦截，声明为 `durable` / `external` 的工具既不能在已读数据后执行，也不能在自身执行过程中读取 DataAccess。直接绕过 Runtime 写文件或发网络请求不在工具 Gate 的控制范围内。
 - 只有查询结果真正包含 `available + data` 时才进入敏感状态；`notGranted`、`unavailable`、`disabledInGroup`、`notDeclared` 只是状态，不会误封后续操作。
 
+小红书行为画像复用现有 DataAccess 授权。用户在统一授权卡中确认当前搭子及用途后，搭搭为该用途按需读取已有画像；目录和详情每次查询都检查授权。
+
 #### 搭子关系工具
 
 `buddy_relationship_request` 用于群聊中目标成员明确索要名片，或尚未添加当前搭子而需要建立关系的情况。即使目标成员已经添加，也可以发送全群可见的名片；未添加的群成员可点击名片为自己添加搭子。只有 `memberId` 指定的目标成员原本未添加、随后完成添加时，平台才会用 `relationshipResult` 从持久历史开启新回合，继续原任务。已添加时名片仅供展示，不会触发新回合。发名片会结束当前回合，搭子不应轮询或在原回合等待用户操作；无需名片即可回答的问题应直接回答。私聊不可使用该工具。
@@ -1053,13 +1079,13 @@ beforeToolCall: async ({ toolCall }) =>
 ```ts
 await BuddyServer.start((conversation) => {
   if (!conversation.key.startsWith("p_")) {
-    return { initialState: { model: "deepseek-v4-flash", systemPrompt: "提供普通群聊帮助。", tools: [] } };
+    return { initialState: { model: "deepseek-v4.1-flash-1017", systemPrompt: "提供普通群聊帮助。", tools: [] } };
   }
   const product = conversation.product;
   const showCard = conversation.tools.show_product_card;
   if (!product || !showCard) throw new Error("当前 Runtime 不支持商品能力");
   const basic = {
-    model: "deepseek-v4-flash" as const,
+    model: "deepseek-v4.1-flash-1017" as const,
     systemPrompt: "提供基础养护帮助；用户有持续养护需求时可展示 plant_care 商品。",
     tools: [showCard],
   };

package/dist/conversation/agent.d.ts

@@ -5,12 +5,17 @@ import type { MLBClient, WidgetType } from "../mlbClient.ts";
 import { DataAccessUsageTracker } from "../tools/dataAccess.ts";
 import type { Resource } from "../tools/resource.ts";
 import type { ProductEvent } from "../services/types.ts";
-import type { BuddyFactory, BuddyLogger, DataRequirement, MLBMessageToWrite } from "../types.ts";
+import type { BuddyFactory, BuddyLogger, BuddyOptions, DataRequirement, MLBMessageToWrite } from "../types.ts";
 export interface AgentDeps {
     /** 当前普通用户回合的真实来源消息；模型参数不能覆盖。 */
     sourceMessage?: () => string | undefined;
     /** 这场会话的发送队列：小挂件引用、服务引用、权限请求卡、题卡都放进来 */
     enqueueMessage: (message: MLBMessageToWrite) => void;
+    /** 同一发送队列，等待这条消息的保存凭据。 */
+    enqueueMessageAndWait: (message: MLBMessageToWrite, signal?: AbortSignal) => Promise<{
+        messageId: string;
+        timestamp: number;
+    }>;
     /** 发了一张等用户操作的卡（权限请求卡、题卡）：这张卡算这一轮说过的话 */
     onWaitingForUser: () => void;
     /** shouldStopAfterTurn 让这一轮停下了（发了等用户操作的卡，或开发者的钩子回 true）：index.ts 据此不再接着 continue */
@@ -37,13 +42,16 @@ export interface AgentDeps {
     /** Agent 事件的去处。pi 会等它返回，所以只能同步做事 */
     onEvent: (agent: Agent, event: AgentEvent) => void;
 }
-/** createAgent 建好的：Agent、这场会话的模型条目、授权数据记账，以及开发者配的兜底话 */
+/** createAgent 建好的：Agent、这场会话的模型条目、授权数据记账，以及开发者配的回复前检查和兜底话 */
 export interface CreatedAgent {
     prepareTurn: () => Promise<Model<Api>>;
     handleProductEvent: (event: ProductEvent) => Promise<string | undefined>;
     invalidateCredential: () => void;
     agent: Agent;
-    /** 按开发者 initialState.model 造的模型条目：重建历史时抄身份按它 */
+    beforeReply: BuddyOptions["beforeReply"];
+    /** 回复前发卡不进入 Agent run，需要由会话层直接结束等待状态。 */
+    clearWaitingForUser: () => void;
+    /** 按开发者 initialState.model 造的模型条目：重建历史时抄身份、判断收不收图片都按它 */
     model: Model<Api>;
     dataAccessUsage: DataAccessUsageTracker;
     /** BuddyOptions.errorReply：普通回合出错或一句话没说时由 index.ts 的 runRound 发；没配是 undefined */

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/conversation/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/conversation/agent.ts"],"names":[],"mappings":"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"}

package/dist/conversation/agent.js

@@ -2,6 +2,7 @@
 // 管：造好这场会话的平台工具，拼好交给开发者工厂的 Conversation（会话键、日志、平台工具、进程启动时读好的资料、绑好会话键的记忆、授权数据查询、权限请求、主动服务与小挂件），跑工厂拿配置；
 //     systemPrompt 按 平台的（GET /internal/v1/system-prompt，每场会话建 Agent 时拉一次）→ 开发者的 拼，段间空一行；
 //     工具清单 = 开发者的 initialState.tools（平台工具也是开发者从 conversation.tools 取来放进去的）+ 运行时自己挂的 view_image（只给收图片的模型，builtinTools），查重名；
+//     image 方法与图片工具共用实现；generate_image 只生成，generate_and_send_image 生成并等待消息保存；生图独立配置 initialState.imageModel。
 //     按 initialState.model 造网关的模型条目（id 运行时不支持就 throw，这场会话起不来）；开发者显式设的 thinkingLevel 这个模型不支持时打一条 warn，写明支持哪几档、实际会怎么发；
 //     钩子叠加——开发者的 beforeToolCall / afterToolCall 包一层授权数据记账，beforeToolCall 抛错时打 warn 再抛给 pi（工具不执行，模型看到错误）；
 //     发了等用户操作的卡（权限请求卡、题卡）的那一轮，shouldStopAfterTurn 在这一步收尾后停下；其余直通；
@@ -23,7 +24,9 @@ import { DATA_ACCESS_TAINTED_SUMMARY, DATA_ACCESS_TOOL_NAME, dataAccessSummary,
 import { resourceListTool, resourceReadTool } from "../tools/resource.js";
 import { assertUniqueToolNames } from "../tools/registry.js";
 import { widgetTools } from "../tools/widget.js";
-import { sendImage, sendImageTool } from "../tools/sendImage.js";
+import { sendImageTool } from "../tools/sendImage.js";
+import { generateImageTool, generateAndSendImageTool } from "../tools/generateImage.js";
+import { createConversationImage } from "./image.js";
 import { viewImageTool } from "../tools/viewImage.js";
 import { dataAccessRequestTool, validateDataAccessRequest } from "../tools/dataAccessRequest.js";
 import { proactiveTools, validateProactiveSubscribe } from "../tools/proactive.js";
@@ -59,6 +62,8 @@ export async function createAgent(deps) {
         web: (input) => client.searchWeb(deps.key, input),
         rednote: (input) => client.searchRednote(deps.key, input),
     };
+    let imageModel;
+    const image = createConversationImage(client, deps.key, () => imageModel, deps.enqueueMessage, deps.enqueueMessageAndWait, () => dataAccessUsage.guardTool("image.generate", { retention: "external", result: "independent", arguments: "private" }));
     const platformTools = {
         show_product_card: productCardTool(product.api),
         proactive_subscribe: proactiveSubscribe,
@@ -79,7 +84,9 @@ export async function createAgent(deps) {
         widget_delete_record: widgetDeleteRecord,
         widget_delete: widgetDelete,
         widget_send: widgetSend,
-        send_image: sendImageTool(client, deps.key, deps.resourcesDir, deps.enqueueMessage),
+        generate_image: generateImageTool(image),
+        generate_and_send_image: generateAndSendImageTool(image),
+        send_image: sendImageTool(image, deps.resourcesDir),
         search_web: searchWebTool(search),
         search_rednote: searchRednoteTool(search),
     };
@@ -90,8 +97,7 @@ export async function createAgent(deps) {
         log: deps.log,
         tools: platformTools,
         search,
-        // 跟 send_image 走同一条路：传上平台拿 mediaId，再进这场会话的发送队列
-        image: { send: (input) => sendImage(client, deps.key, deps.enqueueMessage, input) },
+        image,
         // 进程启动时读好的那份资料，开发者代码读它不用把 resource_list / resource_read 放进工具
         resource: {
             list: () => deps.resources.map((resource) => resource.file),
@@ -162,6 +168,10 @@ export async function createAgent(deps) {
         },
     };
     const options = await deps.factory(conversation);
+    imageModel = options.initialState.imageModel?.trim();
+    if (options.initialState.tools?.some(tool => tool === platformTools.generate_image || tool === platformTools.generate_and_send_image) && !imageModel) {
+        throw new Error("启用 generate_image 或 generate_and_send_image 时必须配置 initialState.imageModel");
+    }
     const model = createModel(deps.gatewayUrl, options.initialState.model);
     // 平台的 system prompt 拉失败就 throw：这场会话起不来，等下一条消息再重建
     const platformPrompt = await deps.client.systemPrompt(deps.key);
@@ -299,7 +309,8 @@ export async function createAgent(deps) {
         return nextModel;
     };
     return {
-        agent, model, dataAccessUsage, errorReply: options.errorReply,
+        agent, model, dataAccessUsage, beforeReply: options.beforeReply,
+        clearWaitingForUser: () => { waitingForUser = false; }, errorReply: options.errorReply,
         invalidateCredential: () => product.invalidate(),
         prepareTurn: async () => {
             if (!supportsProducts || !options.configureTurn)