@my-life-buddies/buddy-runtime 0.25.0-dev.1 → 0.25.0-dev.2

package/README.md

@@ -208,10 +208,10 @@ interface Conversation {
 
 ## 3. 平台能力
 
-| 能力 | `conversation` 对象方法 | 模型工具（`conversation.tools` 上） |
+| 能力 | `conversation` 对象方法 | 内建模型工具（`conversation.tools` 上） |
 |---|---|---|
 | 资料 | `conversation.resource.list` / `conversation.resource.read` | `resource_list` / `resource_read` |
-| 搜索 | 无 | `search_web` / `search_rednote` |
+| 搜索 | `conversation.search.web` / `conversation.search.rednote` | `search_web` / `search_rednote` |
 | 提问 | 无 | `ask_question` |
 | 记忆 | `conversation.memory` | 无，开发者可以根据具体场景，自己组装成适合的模型工具 |
 | 用户授权数据 | `conversation.dataAccess.query` / `conversation.dataAccess.request` | `data_access_query` / `data_access_request` |
@@ -228,6 +228,8 @@ buddy: (conversation) => ({
 }),
 ```
 
+`conversation` 上的方法在自己的模型工具里调，各节「`conversation` 对象方法」下都有一个完整的注册例子。
+
 ### 3.1 资料
 
 搭子随身带的只读资料：把 `.md` 放进工程目录下的 `resources/`，模型先列出有哪些资料，再按需读一篇。资料在进程启动时一次读好，整场会话、每个回合读到的都是同一份。
@@ -251,14 +253,36 @@ my-buddy/                  工程目录
 
 | 方法 | 做什么 |
 |---|---|
-| `list()` | 全部资料的路径，相对 `resources/`，按路径排序 |
-| `read(file)` | 读一篇的正文，`file` 照 `list()` 给的路径原样填 |
+| `resource.list()` | 列出全部资料的路径 |
+| `resource.read(file)` | 读一篇的正文 |
 
 ```ts
-const notes = conversation.resource.read("research/01-writings.md");
+resource: {
+	list(): string[];            // 相对 resources/ 的路径，按路径排序，如 research/01-writings.md
+	read(file: string): string;  // file 照 list() 给的路径原样填；没有这篇抛异常
+}
 ```
 
-**模型工具**
+注册成模型工具：
+
+```ts
+await BuddyServer.start((conversation) => {
+	const READ_NOTES_PARAMS = Type.Object({});
+	const readNotes: AgentTool<typeof READ_NOTES_PARAMS, undefined> = {
+		name: "read_notes",
+		label: "正在翻资料",
+		description: "读这只搭子带的写作研究笔记，回答写作方法的问题前先读。",
+		parameters: READ_NOTES_PARAMS,
+		execute: async () => {
+			const notes = conversation.resource.read("research/01-writings.md");
+			return { content: [{ type: "text", text: notes }], details: undefined };
+		},
+	};
+	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [readNotes] } };
+});
+```
+
+**内建模型工具**
 
 把 `conversation.tools.resource_list` 和 `conversation.tools.resource_read` 放进 `initialState.tools`，模型就能先列出有哪些资料，再按路径读一篇。`systemPrompt` 里交代清楚这只搭子带了哪类资料、什么时候该去翻。
 
@@ -277,56 +301,76 @@ const notes = conversation.resource.read("research/01-writings.md");
 
 | 方法 | 做什么 |
 |---|---|
-| `search.web({ query, topic?, timeRange?, maxResults? })` | 搜站外网页，回结果数组，字段见下面 `search_web` 的结果表；`maxResults` 1～20，缺省 20 |
-| `search.rednote({ query, timeRange?, maxResults?, includeComments? })` | 搜小红书笔记，回结果数组，字段见下面 `search_rednote` 的结果表 |
+| `search.web(input)` | 搜站外网页，回结果数组 |
+| `search.rednote(input)` | 搜小红书笔记，回结果数组 |
+
+```ts
+search: {
+	web(input: SearchWebRequest): Promise<SearchWebResult[]>;
+	rednote(input: SearchRednoteRequest): Promise<SearchRednoteResult[]>;
+}
+
+interface SearchWebRequest {
+	query: string;                                   // 必填，1～120 字
+	topic?: "general" | "news";                      // 缺省 general
+	timeRange?: "day" | "week" | "month" | "year";   // 缺省不限时间
+	maxResults?: number;                             // 1～20，缺省 20
+}
+
+interface SearchWebResult {
+	title: string;
+	url: string;
+	content: string;       // 上游按查询词挑出的片段，不是整页
+	score: number;         // 相关度，0～1
+	publishedAt?: string;  // 上游给了才有
+}
+
+interface SearchRednoteRequest {
+	query: string;                                   // 必填，1～120 字
+	timeRange?: "day" | "week" | "month" | "year";   // 缺省不限时间
+	maxResults?: number;                             // 1～40，缺省 20
+	includeComments?: boolean;                       // 缺省 false
+}
+
+interface SearchRednoteResult {
+	title: string;
+	url: string;
+	content: string;       // 正文原文，不截断
+	score: number;         // 相关度，0～1
+	publishedAt?: string;  // 上游给了才有
+	likes?: string;        // 点赞数所在的区间，如 "1000-10000"，上游给了才有
+	collects?: string;     // 收藏数所在的区间，同上
+	comments?: string[];   // 评论原文，每篇最多 10 条；includeComments 为 true 且有评论才有
+}
+```
 
-模型工具 `search_web` / `search_rednote` 就是这两个方法的包装。要换说明、换结果排法、搜完再加工，就自己包一个工具：
+注册成模型工具：
 
 ```ts
-const FIND_RECIPE_PARAMS = Type.Object({ dish: Type.String({ description: "菜名" }) });
-const findRecipe: AgentTool<typeof FIND_RECIPE_PARAMS, undefined> = {
-	name: "find_recipe",
-	label: "正在找菜谱",
-	description: "按菜名找做法，只看小红书。",
-	parameters: FIND_RECIPE_PARAMS,
-	execute: async (_id, { dish }) => {
-		const notes = await conversation.search.rednote({ query: `${dish} 做法`, maxResults: 5 });
-		return { content: [{ type: "text", text: notes.map((n) => `${n.title}\n${n.url}\n${n.content}`).join("\n\n") }], details: undefined };
-	},
-};
+await BuddyServer.start((conversation) => {
+	const FIND_RECIPE_PARAMS = Type.Object({ dish: Type.String({ description: "菜名" }) });
+	const findRecipe: AgentTool<typeof FIND_RECIPE_PARAMS, undefined> = {
+		name: "find_recipe",
+		label: "正在找菜谱",
+		description: "按菜名找做法，只看小红书。",
+		parameters: FIND_RECIPE_PARAMS,
+		execute: async (_toolCallId, { dish }) => {
+			const notes = await conversation.search.rednote({ query: `${dish} 做法`, maxResults: 5 });
+			return { content: [{ type: "text", text: notes.map((n) => `${n.title}\n${n.url}\n${n.content}`).join("\n\n") }], details: undefined };
+		},
+	};
+	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [findRecipe] } };
+});
 ```
 
-**模型工具**
+**内建模型工具**
 
 把需要的工具放进 `initialState.tools`；什么时候该搜、搜哪边、回答里怎么引用，在 `systemPrompt` 里交代。
 
 | 工具 | 参数 | 结果 |
 |---|---|---|
-| `search_web` | `query`（必填，1～120 字）、`topic`（`general` / `news`，缺省 `general`）、`timeRange`（`day` / `week` / `month` / `year`，缺省不限时间）。走哪家搜索引擎由平台定，开发者和模型都不选 | 最多 20 条，字段见下表 |
-| `search_rednote` | `query`、`timeRange`、`maxResults`（1～40，缺省 20）、`includeComments`（缺省 false） | 最多 40 篇，字段见下表 |
-
-`search_web` 每条结果的字段：
-
-| 字段 | 说明 |
-|---|---|
-| `title` | 网页标题 |
-| `url` | 链接 |
-| `content` | 上游按查询词挑出的相关内容片段 |
-| `score` | 相关度，0 到 1 |
-| `publishedAt` | 发布时间，上游给了才有 |
-
-`search_rednote` 每篇结果的字段：
-
-| 字段 | 说明 |
-|---|---|
-| `title` | 笔记标题 |
-| `url` | 笔记链接 |
-| `content` | 正文原文 |
-| `score` | 相关度，0 到 1 |
-| `publishedAt` | 发布时间 |
-| `likes` | 点赞数所在的区间，如 `1000-10000` |
-| `collects` | 收藏数所在的区间，同上 |
-| `comments` | 评论原文，每篇最多 10 条；`includeComments` 为 true 且有评论才有 |
+| `search_web` | 同 `SearchWebRequest`，少 `maxResults`，固定 20。走哪家搜索引擎由平台定，开发者和模型都不选 | 最多 20 条 `SearchWebResult` |
+| `search_rednote` | 同 `SearchRednoteRequest` | 最多 40 篇 `SearchRednoteResult` |
 
 ```ts
 await BuddyServer.start((conversation) => ({
@@ -343,7 +387,7 @@ await BuddyServer.start((conversation) => ({
 **限制与异常**
 
 - `query` 超过 120 字、`maxResults` 超出 1～40 时参数校验不通过，工具不执行。
-- 同一会话一分钟最多 12 次搜索，同一搭子全部会话一分钟最多 180 次，超出时方法与工具都抛异常（HTTP 429）。
+- 同一会话一分钟最多 12 次搜索，同一搭子全部会话一分钟最多 180 次；本地用开发令牌跑的 `<id>-dev` 身份两项都是 4 次。超出时方法与工具都抛异常（HTTP 429）。
 - 平台搜索服务不可用或超时时工具抛异常，异常只带 HTTP 状态码，不带上游原文；模型可以告诉用户暂时搜不了，不应编造结果。
 - 没有结果时工具正常返回「没有找到相关结果。可以换个说法再搜一次。」
 - `search_rednote` 的正文和评论不截断，40 篇带评论的一次结果可能有几万字，会占用较多上下文；不需要那么多时让模型用缺省篇数。
@@ -356,7 +400,7 @@ await BuddyServer.start((conversation) => ({
 
 没有。`conversation` 不提供发题卡的方法，题卡只由模型发。
 
-**模型工具**
+**内建模型工具**
 
 把 `conversation.tools.ask_question` 放进 `initialState.tools`，模型就能发题卡。
 
@@ -378,19 +422,45 @@ await BuddyServer.start((conversation) => ({
 
 | 方法 | 做什么 |
 |---|---|
-| `list()` | 列出全部，按 `key` 字典序 |
-| `write(key, text)` | 覆盖写一条 |
-| `delete(key)` | 删一条，不存在也算成功 |
+| `memory.list()` | 列出全部记忆 |
+| `memory.write(key, text)` | 覆盖写一条 |
+| `memory.delete(key)` | 删一条 |
 
 ```ts
+memory: {
+	list(): Promise<MemoryEntry[]>;                   // 按 key 字典序
+	write(key: string, text: string): Promise<void>;  // 同一个 key 覆盖写；超配额、key 不合法时抛异常，文案是平台给的原因
+	delete(key: string): Promise<void>;               // 不存在也算成功
+}
+
 interface MemoryEntry {
-	key: string;
+	key: string;        // 主题名
 	text: string;
 	updatedAt: number;  // 最后写入时刻，毫秒
 }
 ```
 
-**模型工具**
+注册成模型工具：
+
+```ts
+await BuddyServer.start((conversation) => {
+	const RECALL_PARAMS = Type.Object({});
+	const recall: AgentTool<typeof RECALL_PARAMS, undefined> = {
+		name: "recall",
+		label: "正在翻印象",
+		description: "读出记过的全部印象，回答跟对方有关的问题前先读。",
+		parameters: RECALL_PARAMS,
+		execute: async () => {
+			const entries = await conversation.memory.list();
+			const text = entries.length === 0 ? "还没记过印象。" : entries.map((e) => `【${e.key}】\n${e.text}`).join("\n\n");
+			return { content: [{ type: "text", text }], details: undefined };
+		},
+	};
+	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [recall] } };
+});
+```
+
+**内建模型工具**
 
 运行时不提供记忆工具。要让模型自己记东西，按这只搭子要记什么，自己包一个：
 
@@ -493,20 +563,53 @@ const sleep = dataAccessCapability("health.sleep");
 
 | 方法 | 做什么 |
 |---|---|
-| `query({ datasets, memberId? })` | 查询已授权 Dataset，每个 Dataset 各自一个状态 |
-| `request({ reason, datasets, memberId?, idempotencyKey })` | 发数据授权卡；群聊必须明确目标成员 |
+| `dataAccess.query(request)` | 查询已授权的 Dataset，每个各自一个状态 |
+| `dataAccess.request(input)` | 发数据授权卡，这一轮到此停下 |
 
 ```ts
-const [sleep] = await conversation.dataAccess.query({ datasets: ["health.sleep"] });
-if (sleep.status === "available") {
-	// sleep.data.items 是每天一条的睡眠记录
+dataAccess: {
+	query(request: DataAccessQuery): Promise<DatasetAccessResult[]>;
+	request(input: DataAccessRequestInput & { idempotencyKey: string }): Promise<void>;  // 用户处理授权卡后开新回合，再 query 一次
+}
+
+interface DataAccessQuery {
+	datasets: string[];  // Dataset id，如 health.sleep；一次最多 8 个
+	memberId?: string;   // 私聊不传；群聊必传，取群消息开头 [名字 #m_…] 里的 m_…，查这位成员的数据，传错抛异常
+}
+
+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" };
+
+interface DataAccessRequestInput {
+	reason: string;      // 为什么要这些数据，用户在授权卡上看到的就是这句
+	datasets: string[];  // 只能是 data-access.json 里声明过的
+	memberId?: string;   // 同 query
 }
 ```
 
-- `datasets`：一次最多 8 个。
-- `memberId`：私聊不传；群聊必传，取群消息开头 `[名字 #m_…]` 里的 `m_…`，查这位成员的数据，传错时抛异常。
+注册成模型工具：
+
+```ts
+await BuddyServer.start((conversation) => {
+	const SLEEP_PARAMS = Type.Object({});
+	const readSleep: AgentTool<typeof SLEEP_PARAMS, undefined> = {
+		name: "read_sleep",
+		label: "正在看睡眠",
+		description: "读用户最近的睡眠记录，聊作息时先调。",
+		parameters: SLEEP_PARAMS,
+		execute: async () => {
+			const [sleep] = await conversation.dataAccess.query({ datasets: ["health.sleep"] });
+			if (sleep.status !== "available") return { content: [{ type: "text", text: `睡眠数据现在拿不到：${sleep.status}` }], details: undefined };
+			const items = sleep.data.items as { date: string; totalSleepMinutes: number }[];
+			return { content: [{ type: "text", text: items.map((d) => `${d.date}：睡了 ${d.totalSleepMinutes} 分钟`).join("\n") }], details: undefined };
+		},
+	};
+	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [readSleep] } };
+});
+```
 
-**模型工具**
+**内建模型工具**
 
 把 `conversation.tools.data_access_query`、`data_access_request` 放进 `initialState.tools`，模型就能自己查数据、发授权卡。放进去只决定模型能不能调用它们，不等于声明 Dataset，也不等于获得用户授权；没声明 Dataset 时照常注册，查询的每一项都回 `notDeclared`。
 
@@ -631,33 +734,78 @@ my-buddy/                  工程目录
 
 | 方法 | 做什么 |
 |---|---|
-| `list()` | 列出这场会话里的小挂件，不带记录 |
-| `create({ type, title, idempotencyKey? })` | 新建一个，回 `{ id }`；同一个 `idempotencyKey` 重复建回同一个 id |
-| `read(id)` | 读整个小挂件，含各模块的记录 |
-| `readModule(id, module)` | 读一个模块，回 `{ records }` |
-| `rename(id, title)` | 改标题，id 不变，聊天里发过的卡片跟着显示新标题 |
-| `writeRecord(id, { module, recordId, data, expectedRevision? })` | 写一条记录，已存在就整条覆盖，回 `{ revision }`；带 `expectedRevision` 时版本号对不上，平台回 409 |
-| `deleteRecord(id, module, recordId)` | 删一条记录 |
-| `setPresentation(id, { summary, imageMediaId })` | 设聊天里卡片的摘要（不超过 500 字）和封面图，`imageMediaId` 传空串去掉封面 |
-| `send(id, { idempotencyKey, openTarget? })` | 发进聊天：可把这张卡锚到声明过的语义入口和具体记录；放进发送队列就返回，不等平台确认送达；同一个 `idempotencyKey` 重复发只落一条 |
+| `widget.list()` | 列出这场会话里的小挂件，不带记录 |
+| `widget.create(input)` | 新建一个 |
+| `widget.read(id)` | 读整个小挂件，含各模块的记录 |
+| `widget.readModule(id, module)` | 读一个模块 |
+| `widget.rename(id, title)` | 改标题 |
+| `widget.writeRecord(id, input)` | 写一条记录 |
+| `widget.deleteRecord(id, module, recordId)` | 删一条记录 |
+| `widget.setPresentation(id, input)` | 设聊天里卡片的摘要和封面图 |
+| `widget.send(id, options)` | 把小挂件发进聊天 |
+
+```ts
+widget: {
+	list(): Promise<WidgetSummary[]>;
+	create(input: { type: string; title: string; idempotencyKey?: string }): Promise<{ id: string }>;  // 同一个 idempotencyKey 重复建回同一个 id
+	read(id: string): Promise<Widget>;
+	readModule(id: string, module: string): Promise<{ records: WidgetRecord[] }>;
+	rename(id: string, title: string): Promise<void>;  // id 不变，聊天里发过的卡片跟着显示新标题
+	writeRecord(id: string, input: { module: string; recordId: string; data: Record<string, unknown>; expectedRevision?: number }): Promise<{ revision?: number }>;  // 已存在就整条覆盖；带 expectedRevision 时版本号对不上平台回 409
+	deleteRecord(id: string, module: string, recordId: string): Promise<void>;
+	setPresentation(id: string, input: { summary: string; imageMediaId: string }): Promise<void>;  // summary 不超过 500 字；imageMediaId 传空串去掉封面
+	send(id: string, options: { idempotencyKey: string; openTarget?: WidgetOpenTarget }): void;  // 放进发送队列就返回，不等平台确认送达；同一个 idempotencyKey 重复发只落一条
+}
+
+interface WidgetSummary {
+	id: string;
+	type: string;        // 开发者登记的类型 id
+	title: string;
+	updatedAt: number;   // 最后改动时刻，毫秒
+	canEdit: boolean;    // 这场会话能不能改：别的会话转发来的引用是 false，改名、写记录、删除、设卡片平台都回 403
+}
+
+interface Widget extends WidgetSummary {
+	modules: Record<string, WidgetRecord[]>;
+}
+
+interface WidgetRecord {
+	id: string;
+	data: Record<string, unknown>;
+	revision: number;    // 从 1 起，每次覆盖加一；写的时候带上它当 expectedRevision，防止互相覆盖
+	updatedAt: number;
+}
+
+interface WidgetOpenTarget {
+	version: 1;
+	entry: string;                                  // schema.json 里声明过的语义入口
+	resource?: { module: string; recordId: string };  // 点开直接落到这条记录
+	state?: Record<string, unknown>;
+}
+```
+
+注册成模型工具：
 
 ```ts
-execute: async (toolCallId, params) => {
-	const { id } = await conversation.widget.create({ type: "menu", title: "本周菜单", idempotencyKey: `menu:${toolCallId}` });
-	await conversation.widget.writeRecord(id, { module: "菜单", recordId: "2026-09-14", data: { dishes: ["红烧肉", "清炒时蔬"] } });
-	conversation.widget.send(id, {
-		idempotencyKey: `menu-send:${toolCallId}`,
-		openTarget: {
-			version: 1,
-			entry: "menu-day",
-			resource: { module: "菜单", recordId: "2026-09-14" },
+await BuddyServer.start((conversation) => {
+	const MENU_PARAMS = Type.Object({ date: Type.String({ description: "哪天的菜单，YYYY-MM-DD" }), dishes: Type.Array(Type.String()) });
+	const writeMenu: AgentTool<typeof MENU_PARAMS, undefined> = {
+		name: "write_menu",
+		label: "正在排菜单",
+		description: "把一天的菜写进「本周菜单」小挂件并发进聊天。",
+		parameters: MENU_PARAMS,
+		execute: async (toolCallId, { date, dishes }) => {
+			const { id } = await conversation.widget.create({ type: "menu", title: "本周菜单", idempotencyKey: "menu:weekly" });
+			await conversation.widget.writeRecord(id, { module: "菜单", recordId: date, data: { dishes } });
+			conversation.widget.send(id, { idempotencyKey: `menu-send:${toolCallId}`, openTarget: { version: 1, entry: "menu-day", resource: { module: "菜单", recordId: date } } });
+			return { content: [{ type: "text", text: `${date} 的菜单排好了。` }], details: undefined };
 		},
-	});
-	return { content: [{ type: "text", text: "菜单建好了。" }], details: undefined };
-},
+	};
+	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [writeMenu] } };
+});
 ```
 
-**模型工具**
+**内建模型工具**
 
 把要用的 `conversation.tools.widget_*` 放进 `initialState.tools`，模型就能自己建、读、改、发小挂件。
 
@@ -689,35 +837,66 @@ execute: async (toolCallId, params) => {
 
 | 方法 | 做什么 |
 |---|---|
-| `subscribe(key, request)` | 按稳定 `key` 创建或更新一条订阅，相同 `key` 更新原订阅并重新启用 |
-| `list()` | 当前会话的全部订阅，包括已关闭项 |
-| `unsubscribe(key)` | 关闭指定订阅，回是否找到 |
-| `unsubscribeAll()` | 关闭全部 active 订阅，回关掉几条 |
-| `isRunning()` | 现在是不是主动服务的回合 |
+| `proactive.subscribe(key, request)` | 按稳定 `key` 创建或更新一条订阅 |
+| `proactive.list()` | 当前会话的全部订阅 |
+| `proactive.unsubscribe(key)` | 关闭一条订阅 |
+| `proactive.unsubscribeAll()` | 关闭全部订阅 |
+| `proactive.isRunning()` | 现在是不是主动服务的回合 |
 
 它挂在这场会话的 `conversation` 上，凡是拿得到 `conversation` 的地方都能调：自己工具的 `execute` 里、`beforeToolCall` / `afterToolCall` 里、配置工厂函数体里。
 
 ```ts
-await conversation.proactive.subscribe("weekly-review", {
-	title: "每周复盘",
-	reason: "在约定时间结合最近聊天做一次简短复盘",
-	trigger: { type: "schedule", at: firstReviewAt, intervalMinutes: 7 * 24 * 60 },
-});
+proactive: {
+	subscribe(key: string, request: ProactiveSubscriptionRequest): Promise<ProactiveSubscription>;  // key 1～64 位小写字母、数字、点、下划线或横线，首位为字母或数字；相同 key 更新原订阅并重新启用
+	list(): Promise<ProactiveSubscription[]>;  // 包括已关闭的
+	unsubscribe(key: string): Promise<boolean>;  // 回是否找到
+	unsubscribeAll(): Promise<number>;           // 回关掉几条
+	isRunning(): boolean;
+}
+
+interface ProactiveSubscriptionRequest {
+	title: string;    // 订阅名称，最长 100 字
+	reason: string;   // 为什么要主动找用户，最长 500 字
+	trigger:          // 什么时候触发，一条订阅只对应一种
+		| { type: "workout.completed" }
+		| { type: "sleep.ready" }
+		| { type: "data.updated"; dataset?: DataAccessDatasetId }
+		| { type: "schedule"; at: number; intervalMinutes?: number };  // at 是 UTC 毫秒
+	quietHours?: { start: string; end: string; timezone: string };  // 免打扰时段，缺省 { start: "22:30", end: "08:00", timezone: "Asia/Shanghai" }
+	cooldownMinutes?: number;  // 冷却时间，缺省 120，取 0～10080
+	dailyLimit?: number;       // 每天最多几次，缺省 3，取 1～20
+}
+
+interface ProactiveSubscription extends Required<ProactiveSubscriptionRequest> {
+	key: string;
+	status: "active" | "revoked";
+}
 ```
 
-`subscribe` 的字段：
+注册成模型工具：
 
-| 字段 | 说明 |
-|---|---|
-| `key` | 必填，订阅的稳定标识：1～64 位小写字母、数字、点、下划线或横线，首位为字母或数字；相同 `key` 更新原订阅并重新启用 |
-| `title` | 必填，订阅名称，最长 100 字 |
-| `reason` | 必填，为什么要主动找用户，最长 500 字 |
-| `trigger` | 必填，什么时候触发：`workout.completed`、`sleep.ready`、`{ type: "data.updated", dataset? }`，或 `{ type: "schedule", at, intervalMinutes? }`。一条订阅只对应一种触发 |
-| `quietHours` | 可选，免打扰时段，缺省 `{ start: "22:30", end: "08:00", timezone: "Asia/Shanghai" }` |
-| `cooldownMinutes` | 可选，冷却时间，缺省 120，取 0～10080 |
-| `dailyLimit` | 可选，每天最多几次，缺省 3，取 1～20 |
-
-**模型工具**
+```ts
+await BuddyServer.start((conversation) => {
+	const REVIEW_PARAMS = Type.Object({ hour: Type.Integer({ minimum: 0, maximum: 23, description: "每周一几点复盘，24 小时制" }) });
+	const subscribeReview: AgentTool<typeof REVIEW_PARAMS, undefined> = {
+		name: "subscribe_review",
+		label: "正在订每周复盘",
+		description: "用户想坚持训练时，订一条每周一次的复盘。",
+		parameters: REVIEW_PARAMS,
+		execute: async (_toolCallId, { hour }) => {
+			await conversation.proactive.subscribe("weekly-review", {
+				title: "每周复盘",
+				reason: "在约定时间结合最近聊天做一次简短复盘",
+				trigger: { type: "schedule", at: nextMondayAt(hour), intervalMinutes: 7 * 24 * 60 },  // nextMondayAt 算下个周一那个点的 UTC 毫秒，自己实现
+			});
+			return { content: [{ type: "text", text: `订好了，每周一 ${hour} 点复盘。` }], details: undefined };
+		},
+	};
+	return { initialState: { model: "kimi-k3", systemPrompt: PERSONA, tools: [subscribeReview] } };
+});
+```
+
+**内建模型工具**
 
 让模型自己决定是否订阅或关闭时，把需要的 `conversation.tools.proactive_*` 放进 `initialState.tools`，字段与上面那张表一样。什么场景可以订阅、何时只能查询或关闭，要在 `systemPrompt` 里说清楚：
 

package/dist/mlbClient.d.ts

@@ -45,7 +45,7 @@ export interface WidgetType {
  * package.json（测试机上的 fitness-buddy 就是这样，它那份没有 version 字段）。常量会被打包器原样搬走。
  * 发版时由 scripts/release.ts 连同 package.json 一起改，scripts/check-publish.ts 在 npm publish 前比对两处是否一致。
  */
-export declare const RUNTIME_VERSION = "0.25.0-dev.1";
+export declare const RUNTIME_VERSION = "0.25.0-dev.2";
 export declare const MAX_DATASETS_PER_QUERY = 8;
 export declare const MAX_DATA_ACCESS_RESPONSE_BYTES: number;
 /** 不向模型暴露服务端原文、凭据或临时媒体地址。写入失败不自动重试。 */

package/dist/mlbClient.js

@@ -11,7 +11,7 @@ import { errorText } from "./log.js";
  * package.json（测试机上的 fitness-buddy 就是这样，它那份没有 version 字段）。常量会被打包器原样搬走。
  * 发版时由 scripts/release.ts 连同 package.json 一起改，scripts/check-publish.ts 在 npm publish 前比对两处是否一致。
  */
-export const RUNTIME_VERSION = "0.25.0-dev.1";
+export const RUNTIME_VERSION = "0.25.0-dev.2";
 /** 除事件流以外的请求都限时 30 秒：卡死的请求超时后按网络错误处理，调用方决定重不重发 */
 const REQUEST_TIMEOUT_MS = 30_000;
 export const MAX_DATASETS_PER_QUERY = 8;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@my-life-buddies/buddy-runtime",
-	"version": "0.25.0-dev.1",
+	"version": "0.25.0-dev.2",
 	"type": "module",
 	"description": "「搭搭」搭子服务的运行时基座",
 	"exports": {