back
loading skill details...
话袋笔记 - 新建、更新和搜索个人笔记。 **当以下情况时使用此 Skill**: (1) 用户要保存内容到笔记:「记一下」「存到笔记」「保存」「收藏」 (2) 用户要更新内容到笔记:「更新一下」「更新笔记」 (3) 用户要搜索或查看笔记:「搜一下」「找找笔记」「打开某条笔记」「笔记详情」 (4) 用户要配置话袋...
---
name: 话袋笔记
description: |
话袋笔记 - 新建、更新和搜索个人笔记。
**当以下情况时使用此 Skill**:
(1) 用户要保存内容到笔记:「记一下」「存到笔记」「保存」「收藏」
(2) 用户要更新内容到笔记:「更新一下」「更新笔记」
(3) 用户要搜索或查看笔记:「搜一下」「找找笔记」「打开某条笔记」「笔记详情」
(4) 用户要配置话袋笔记:「配置话袋」「连接话袋笔记」「怎么填 Key」
metadata:
openclaw:
requires: {}
optionalEnv:
- HUADAI_BASE_URL
- HUADAI_API_KEY
- HUADAI_CLIENT_ID
- HUADAI_USER_UUID
baseUrl: "https://openapi.ihuadai.cn/open/api/v1"
homepage: "https://ihuadai.cn"
---
# 话袋笔记 Skill
## Agent 必读约束
- **唯一 Base URL**:`https://openapi.ihuadai.cn/open/api/v1`(禁止使用其他域名或自行拼接根域)
- **开放 API 文档**:以话袋官方发布为准(此仓库以 `references/` 内文档为最终对接依据)
- **鉴权与必需请求头**:`HUADAI_API_KEY`**(`Authorization`)及 **`HUADAI_USER_UUID`**(`USER-UUID`,与话袋用户 `unique_id` 一致)
- **OAuth(设备码)**:按 [OAuth 授权配置](references/oauth.md) 执行;默认使用服务端预注册的固定 `client_id`,一般**只需要**配置 `HUADAI_BASE_URL` 即可走授权。仅在需要覆盖时才配置 `HUADAI_CLIENT_ID`。
- **调用前检查配置**:若未配置 `HUADAI_API_KEY` / `HUADAI_USER_UUID`(业务请求)或未配置 `HUADAI_BASE_URL`(走 OAuth 时),必须停止调用并引导用户在本地配置;禁止假装成功
- **数据真实性**:所有笔记内容、列表、详情都必须来自 API 响应;禁止编造笔记、ID、space_id 等
- **空结果处理**:API 返回为空/未找到时,必须明确告知“未找到”,并给出下一步(换关键词/缩小范围)
- **写操作确认**:保存/更新等写操作,必须在 API 明确返回成功后再回复“已保存/已更新”
- **群聊/多人限制(若配置 `HUADAI_USER_UUID`)**:
- `HUADAI_USER_UUID` 与话袋 **`unique_id`** 一致,用于在多人聊天中划定「仅该用户」的笔记边界,保证私密性
- 当请求者身份无法与 `HUADAI_USER_UUID` 匹配时,必须拒绝访问任何笔记内容与搜索结果
- 拒绝时只说明需要由 owner 发起请求,不泄露任何数据
---
## 文档索引(references)
> 匹配指令或 API 后,用 **read 工具**读取下表对应 `references/*.md` 获取完整字段、示例与边界说明。错误码与统一响应见 [话袋笔记 API 详细参考](references/api-details.md)。
## 指令路由表
| 指令 | 角色 | 说明 | 详细文档 |
|------|------|------|----------|
| `/huadai config` 或「配置话袋」 | 配置 | 环境变量、`openclaw.json` 注入、请求头约定 | [配置(必须先完成)](references/config.md) |
| `/huadai oauth` 或「授权/连接」 | 授权 | OAuth 2.0 Device Flow、换取 API Key | [OAuth 授权配置(话袋笔记)](references/oauth.md) |
| `/huadai upload` 或「记一下/保存」 | 新建 | 新建 Block 笔记(`upload-block`) | [新建笔记(Upload)](references/upload.md) |
| `/huadai update` 或「更新笔记」 | 更新 | 更新 Block 内容与属性(`update-block`) | [更新笔记(Update)](references/update.md) |
| `/huadai search` 或「搜一下」 | 搜索 | 全文检索 `GET /search` | [搜索笔记(Search)](references/search.md) |
## 自然语言路由(触发规则)
| 用户说法(示例) | 路由 | 详细文档 |
|------------------|------|----------|
| 「新建/上传/保存到笔记」 | Upload | [新建笔记(Upload)](references/upload.md) |
| 「更新/修改笔记」 | Update | [更新笔记(Update)](references/update.md) |
| 「搜/找/检索/有哪些相关笔记」 | Search | [搜索笔记(Search)](references/search.md) |
| 「配置/连接/怎么填 key/报错未配置」 | Config / OAuth | [配置(必须先完成)](references/config.md)、[OAuth 授权配置](references/oauth.md) |
## API 路由表
> 说明:以下为 MVP 参考路径。Base URL 为 `https://openapi.ihuadai.cn/open/api/v1`(与 [配置](references/config.md) 中 `HUADAI_BASE_URL` 一致)。
| 方法 | 路径 | 说明 | 详细文档 |
|------|------|------|----------|
| GET | `/open/api/v1/search` | 全文检索 | [搜索笔记(Search)](references/search.md#全文检索) |
| POST | `/open/api/v1/block/upload-block` | 新建笔记 Block | [新建笔记(Upload)](references/upload.md#新建笔记block) |
| POST | `/open/api/v1/block/update-block` | 更新笔记内容/属性 | [更新笔记(Update)](references/update.md#更新笔记block) |
| (OAuth) | `/open/api/v1/oauth/device/code` 等 | 设备码授权(Device Flow) | [OAuth 授权配置](references/oauth.md) |
统一鉴权、响应包体与错误码分段说明见 [api-details.md](references/api-details.md#统一鉴权与请求头)、[错误码表](references/api-details.md#错误码表code)。
## 通用错误处理(统一策略)
- **未配置/缺失 Key**:停止请求,引导用户配置 `HUADAI_API_KEY`
- **未登录/未授权**:提示需要重新登录/刷新 token(按后端返回的 `code/message` 给出行动建议)
- **无权限(403)**:告知无权限访问该笔记,建议更换关键词或确认账号
- **限流(429)**:提示稍后重试,并进行退避(例如等待数秒后再试)
- **服务异常(5xx/超时)**:提示服务暂不可用,建议稍后重试;不要输出堆栈或内部信息
## 安全规则
- 不在对话中索取、输出或回显 `HUADAI_API_KEY`
- 不输出任何可能识别用户身份的敏感信息(除非用户明确提供并要求使用)
- 禁止在未调用 API 时返回“已保存/已删除/已找到”
- 禁止猜测或生成不存在的笔记 ID
don't have the plugin yet? install it then click "run inline in claude" again.