话袋笔记 Skill

话袋笔记 - 新建、更新和搜索个人笔记。 **当以下情况时使用此 Skill**： (1) 用户要保存内容到笔记：「记一下」「存到笔记」「保存」「收藏」 (2) 用户要更新内容到笔记：「更新一下」「更新笔记」 (3) 用户要搜索或查看笔记：「搜一下」「找找笔记」「打开某条笔记」「笔记详情」 (4) 用户要配置话袋笔记：「配置话袋」「连接话袋笔记」「怎么填 Key」

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 授权配置 执行；默认使用服务端预注册的固定 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 详细参考。

指令路由表

指令	角色	说明	详细文档
/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