话袋笔记 Skill

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

Security Scan

The skill's files, instructions, and optional environment variables align with a notes service integration (OAuth + API calls) and there are no obvious mismatches or hidden endpoints.

Purpose & Capability

The skill advertises create/update/search for personal notes and all code and docs correspond to that purpose (API paths, headers, OAuth). Minor inconsistency: the registry metadata lists no required env vars while SKILL.md and references clearly require HUADAI_API_KEY and HUADAI_USER_UUID (and HUADAI_BASE_URL for OAuth); this appears to be an omission in metadata rather than malicious mismapping.

Instruction Scope

Runtime instructions stay within the stated purpose: call the service API, require Authorization and USER-UUID headers, and only return results that come from the API. Two things to be aware of: (1) the skill is designed to automatically start the OAuth Device Flow if credentials are missing (it may initiate background polling after presenting the verification link), and (2) the included oauth_poll.py prints the returned credentials JSON to stdout (the instructions rely on capturing that output to write HUADAI_API_KEY / HUADAI_USER_UUID into local config). Both behaviors are coherent with the described setup but increase the importance of user consent and secure local handling of the returned API key.

Install Mechanism

No install spec or remote downloads; only a small local Python script (oauth_poll.py) and documentation files are included. No external archives, shorteners, or untrusted URLs are used for installation.

Credentials

The only sensitive values referenced are HUADAI_API_KEY and HUADAI_USER_UUID (plus optional HUADAI_BASE_URL/HUADAI_CLIENT_ID). These map directly to the service's authentication model and are proportionate to a notes integration. No unrelated secrets or system credentials are requested.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It does instruct writing API credentials to local Skill config (openclaw.json) after OAuth — this is expected for a persistent integration but means local config must be considered sensitive.

Assessment

This skill appears coherent for integrating with the Huadai notes API. Before installing: 1) Confirm you trust the service/owner (https://ihuadai.cn) because the skill will obtain and store an API key (HUADAI_API_KEY) and user UUID locally (openclaw.json) after OAuth. 2) Expect the agent to automatically initiate the OAuth Device Flow if credentials are missing — you must complete the browser authorization and the agent will poll the token endpoint in the background. 3) The included script prints the credential JSON to stdout and the skill expects to capture and persist it; ensure your environment/session logs are secure. 4) Do not paste API keys into chat; the skill's docs explicitly forbid that. 5) If you want stricter control, manually perform the OAuth and place HUADAI_API_KEY/HUADAI_USER_UUID in your openclaw config instead of allowing automatic flow. If you want, provide the skill's source origin (repo/owner) and verify it before trusting stored credentials.

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