From 150e2d56079a6ab64d85e72b661e6b000d49fd8b Mon Sep 17 00:00:00 2001 From: root Date: Fri, 17 Apr 2026 14:07:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=B8=8E=E4=BB=A3=E7=A0=81=E5=AE=9E=E7=8E=B0=E7=9A=84=E5=B7=AE?= =?UTF-8?q?=E5=BC=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 以代码为准，修正以下内容： 1. Actions 表格添加 task_link_info 操作 2. recall 参数补充 depth 字段 3. 导入路径更新：waterflow -> waterflow-ts/dist/... 4. installTrulyMEM 需要 await（返回 Promise） 5. 新增 API 名称映射章节（mapToolIdToApiName/mapApiNameToToolId） 6. 新增 task_link_info 使用示例 --- README.md | 40 +++++++++++++++++++++++++++++++++++----- README_EN.md | 40 +++++++++++++++++++++++++++++++++++----- 2 files changed, 70 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 15d13eb..ba1c4e3 100644 --- a/README.md +++ b/README.md @@ -79,11 +79,11 @@ npm install 只需两行代码，完全不动 WaterFlow 源码： ```typescript -import { getPlatform } from 'waterflow/platform'; +import { getPlatform } from 'waterflow-ts/dist/platform/index.js'; import { installTrulyMEM } from 'trulymem/tools'; // 一行安装，返回配置好的 ToolRegistry -const registry = installTrulyMEM(getPlatform(), 'my-session-id'); +const registry = await installTrulyMEM(getPlatform(), 'my-session-id'); // 继续组装 WaterFlow... const toolExecutor = new ToolExecutor(registry); @@ -94,8 +94,8 @@ const toolExecutor = new ToolExecutor(registry); 如果你想自己控制 ToolRegistry 的创建： ```typescript -import { getPlatform } from 'waterflow/platform'; -import { initializeToolRegistry } from 'waterflow/runtime/core/tools/builtin'; +import { getPlatform } from 'waterflow-ts/dist/platform/index.js'; +import { initializeToolRegistry } from 'waterflow-ts/dist/runtime/core/tools/builtin/index.js'; import { registerGraphMemoryTool } from 'trulymem/tools'; const platform = getPlatform(); @@ -160,7 +160,7 @@ const tool = new GraphMemoryTool(sessionId?: string); | Action | 说明 | 参数 | |--------|------|------| -| `recall` | 检索记忆 | `queryIntent`, `seedEntities`, `sessionFilter` | +| `recall` | 检索记忆 | `queryIntent`, `seedEntities`, `depth`, `sessionFilter` | | `commit` | 写入记忆 | `triplets`, `sessionId`, `turnId` | | `purge` | 删除记忆 | `criteria`, `mode` | | `introspect` | 查看状态 | - | @@ -169,6 +169,7 @@ const tool = new GraphMemoryTool(sessionId?: string); | `task_create` | 创建任务 | `task_id`, `description`, `info_nodes` | | `task_set_state` | 设置状态 | `task_id`, `state` | | `task_delete` | 删除任务 | `task_id` | +| `task_link_info` | 关联信息到任务 | `task_id`, `info_node` | --- @@ -212,6 +213,35 @@ const tool = new GraphMemoryTool(sessionId?: string); } ``` +### 关联信息到任务 + +```json +{ + "action": "task_link_info", + "params": { + "task_id": "Task_学习TypeScript", + "info_node": "用户喜欢 React" + } +} +``` + +--- + +## API 名称映射 + +OpenAI/DeepSeek API 要求工具名称符合 `^[a-zA-Z0-9_-]+$` 格式（不含冒号）。 +内部工具 ID 使用 `builtin:xxx` 格式，需映射后发送给 API。 + +```typescript +import { mapToolIdToApiName, mapApiNameToToolId } from 'trulymem/tools'; + +// 发送给 API +const apiName = mapToolIdToApiName('builtin:graph_memory'); // -> 'graph_memory' + +// 收到 tool_use 后映射回 +const internalId = mapApiNameToToolId('graph_memory'); // -> 'builtin:graph_memory' +``` + --- ## 许可证 diff --git a/README_EN.md b/README_EN.md index 27e3568..f735575 100644 --- a/README_EN.md +++ b/README_EN.md @@ -80,11 +80,11 @@ npm install Just two lines, zero changes to WaterFlow: ```typescript -import { getPlatform } from 'waterflow/platform'; +import { getPlatform } from 'waterflow-ts/dist/platform/index.js'; import { installTrulyMEM } from 'trulymem/tools'; // One-line install, returns configured ToolRegistry -const registry = installTrulyMEM(getPlatform(), 'my-session-id'); +const registry = await installTrulyMEM(getPlatform(), 'my-session-id'); // Continue assembling WaterFlow... const toolExecutor = new ToolExecutor(registry); @@ -95,8 +95,8 @@ const toolExecutor = new ToolExecutor(registry); If you want to control ToolRegistry creation yourself: ```typescript -import { getPlatform } from 'waterflow/platform'; -import { initializeToolRegistry } from 'waterflow/runtime/core/tools/builtin'; +import { getPlatform } from 'waterflow-ts/dist/platform/index.js'; +import { initializeToolRegistry } from 'waterflow-ts/dist/runtime/core/tools/builtin/index.js'; import { registerGraphMemoryTool } from 'trulymem/tools'; const platform = getPlatform(); @@ -161,7 +161,7 @@ const tool = new GraphMemoryTool(sessionId?: string); | Action | Description | Parameters | |--------|-------------|------------| -| `recall` | Retrieve memories | `queryIntent`, `seedEntities`, `sessionFilter` | +| `recall` | Retrieve memories | `queryIntent`, `seedEntities`, `depth`, `sessionFilter` | | `commit` | Commit memories | `triplets`, `sessionId`, `turnId` | | `purge` | Delete memories | `criteria`, `mode` | | `introspect` | Inspect status | - | @@ -170,6 +170,7 @@ const tool = new GraphMemoryTool(sessionId?: string); | `task_create` | Create task | `task_id`, `description`, `info_nodes` | | `task_set_state` | Set state | `task_id`, `state` | | `task_delete` | Delete task | `task_id` | +| `task_link_info` | Link info to task | `task_id`, `info_node` | --- @@ -213,6 +214,35 @@ const tool = new GraphMemoryTool(sessionId?: string); } ``` +### Link Info to Task + +```json +{ + "action": "task_link_info", + "params": { + "task_id": "Task_LearnTypeScript", + "info_node": "User likes React" + } +} +``` + +--- + +## API Name Mapping + +OpenAI/DeepSeek API requires tool names to match `^[a-zA-Z0-9_-]+$` (no colons). +Internal tool IDs use `builtin:xxx` format and must be mapped before sending to API. + +```typescript +import { mapToolIdToApiName, mapApiNameToToolId } from 'trulymem/tools'; + +// Send to API +const apiName = mapToolIdToApiName('builtin:graph_memory'); // -> 'graph_memory' + +// Map back after receiving tool_use +const internalId = mapApiNameToToolId('graph_memory'); // -> 'builtin:graph_memory' +``` + --- ## License