话袋笔记 Skill

Agent 必读约束

唯一 Base URL：https://openapi.ihuadai.cn/open/api/v1（禁止使用其他域名或自行拼接根域）
开放 API 文档：以话袋官方发布为准（此仓库以 references/ 内文档为最终对接依据）
鉴权与必需请求头：HUADAI_API_KEY（对应请求头 Authorization）
OAuth（设备码）：按 OAuth 授权配置执行；默认使用服务端预注册的固定 client_id，一般只需要配置 HUADAI_BASE_URL 即可走授权。仅在需要覆盖时才配置 HUADAI_CLIENT_ID。
调用前检查配置：若未配置 HUADAI_API_KEY（业务请求）或未配置 HUADAI_BASE_URL（走 OAuth 时），必须停止调用并引导用户在本地配置；禁止假装成功
数据真实性：所有笔记内容、列表、详情都必须来自 API 响应；禁止编造笔记、ID、space_id 等
空结果处理：API 返回为空/未找到时，必须明确告知“未找到”，并给出下一步（换关键词/缩小范围）
写操作确认：保存/更新等写操作，必须在 API 明确返回成功后再回复“已保存/已更新”

文档索引（references）

匹配指令或 API 后，用 read 工具读取下表对应 references/*.md 获取完整字段、示例与边界说明。错误码与统一响应见话袋笔记 API 详细参考。

指令路由表

| 指令 | 角色 | 说明 | 详细文档 | |------|------|------|----------| | /huadai config 或「配置话袋」 | 配置 | 环境变量、openclaw.json 注入、请求头约定 | 配置（必须先完成） | | /huadai oauth 或「授权/连接」 | 授权 | OAuth 2.0 Device Flow、换取 API Key | OAuth 授权配置（话袋笔记） | | /huadai upload 或「记一下/保存」 | 新建 | 新建 Block 笔记（upload-block） | 新建笔记（Upload） | | /huadai update 或「更新笔记」 | 更新 | 更新 Block 内容与属性（update-block） | 更新笔记（Update） | | /huadai search 或「搜一下」 | 搜索 | 全文检索 GET /search | 搜索笔记（Search） |

自然语言路由（触发规则）

| 用户说法（示例） | 路由 | 详细文档 | |------------------|------|----------| | 「新建/上传/保存到笔记」 | Upload | 新建笔记（Upload） | | 「更新/修改笔记」 | Update | 更新笔记（Update） | | 「搜/找/检索/有哪些相关笔记」 | Search | 搜索笔记（Search） | | 「配置/连接/怎么填 key/报错未配置」 | Config / OAuth | 配置（必须先完成）、OAuth 授权配置 |

API 路由表

说明：以下为 MVP 参考路径。Base URL 为 https://openapi.ihuadai.cn/open/api/v1（与配置中 HUADAI_BASE_URL 一致）。

| 方法 | 路径 | 说明 | 详细文档 | |------|------|------|----------| | GET | /open/api/v1/search | 全文检索 | 搜索笔记（Search） | | POST | /open/api/v1/block/upload-block | 新建笔记 Block | 新建笔记（Upload） | | POST | /open/api/v1/block/update-block | 更新笔记内容/属性 | 更新笔记（Update） | | （OAuth） | /open/api/v1/oauth/device/code 等 | 设备码授权（Device Flow） | OAuth 授权配置 |

统一鉴权、响应包体与错误码分段说明见 api-details.md、错误码表。

通用错误处理（统一策略）

未配置/缺失 Key：停止请求，引导用户配置 HUADAI_API_KEY
未登录/未授权：提示需要重新登录/刷新 token（按后端返回的 code/message 给出行动建议）
无权限（403）：告知无权限访问该笔记，建议更换关键词或确认账号
限流（429）：提示稍后重试，并进行退避（例如等待数秒后再试）
服务异常（5xx/超时）：提示服务暂不可用，建议稍后重试；不要输出堆栈或内部信息

安全规则

不在对话中索取、输出或回显 HUADAI_API_KEY
不输出任何可能识别用户身份的敏感信息（除非用户明确提供并要求使用）
禁止在未调用 API 时返回“已保存/已删除/已找到”
禁止猜测或生成不存在的笔记 ID