话袋笔记 Skill

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

Agent 必读约束

• 唯一 Base URL：https://openapi.ihuadai.cn/open/api/v1。禁止使用其他域名，禁止重复拼接 /open/api/v1。
• 鉴权方式：业务 API 仅使用请求头 Authorization: <HUADAI_API_KEY>。
• API Key 来源：用户需先在 话袋开放平台 创建 API Key。如果用户未配置，引导用户创建并配置 HUADAI_API_KEY。
• 数据真实性：所有笔记内容、搜索结果、笔记 ID 都必须来自 API 响应。禁止编造「已保存」「已找到」「已更新」。
• 写操作确认：只有 API 返回 code=200 后，才能回复用户已保存或已更新。
• 更新笔记约束：unique_id 必须来自搜索结果或用户明确提供，禁止猜测或生成已有笔记 ID。
• 密钥安全：不要在对话中要求用户粘贴 API Key，不要回显、记录、总结或展示 HUADAI_API_KEY。

快速开始：配置 API Key

如果还没有配置 HUADAI_API_KEY，引导用户：

• 打开 https://ihuadai.cn/desktop/openai 创建 API Key
• 设置环境变量：export HUADAI_API_KEY=<你的Key>

文档索引

文档	内容	何时读取
API 参考	完整请求体、curl 示例、响应判断、错误码	需要构造 API 调用或处理错误时

指令路由表

指令	角色	说明	详细文档
/huadai config 或「配置话袋」	配置	引导用户到开放平台创建并配置 API Key	API 参考
/huadai upload 或「记一下/保存」	新建	新建 Block 笔记	API 参考
/huadai update 或「更新笔记」	更新	搜索确认目标后更新 Block 内容	API 参考
/huadai search 或「搜一下」	搜索	关键词检索笔记	API 参考

自然语言路由

用户说法（示例）	路由	执行方式
「授权话袋」「连接话袋笔记」「配置话袋」「怎么填 Key」	Config	不调用业务 API，引导配置 HUADAI_API_KEY
「新建/上传/保存/写入到笔记」「记一下」	Upload	POST /block/upload-block
「更新/修改笔记」「补充到这条」	Update	先确认 unique_id，再 POST /block/update-block
「搜/找/检索/有哪些相关笔记」	Search	GET /search

API 路由表

方法	路径	说明
GET	/search	关键词搜索笔记
GET	/block/:unique_id	获取单条笔记详情
POST	/block/upload-block	新建笔记
POST	/block/update-block	更新笔记

完整 URL 等于 Base URL + 路径。例如：https://openapi.ihuadai.cn/open/api/v1/search。

执行规则

搜索笔记

• 调用 GET /search?query=<关键词>&page=1&size=10。
• 无结果时明确回复「未找到」，不要编造类似笔记。
• 从响应中提取关键信息展示给用户：
  • unique_id — 笔记唯一标识（更新/查详情时需要）
  • content — Quill Delta 数组，提取 insert 字段拼接为纯文本摘要
  • create_time / update_time — Unix 时间戳，可转为可读时间
  • type — 笔记类型
• 展示结果时优先给标题/摘要/unique_id，方便用户选择要更新哪条。
• 如果结果超过一页（total > size），提示用户缩小搜索范围或翻页。

获取笔记详情

• 调用 GET /block/:unique_id 查看笔记完整内容。
• 仅在用户明确要求查看某条笔记详情，或需要获取完整内容用于更新时使用。

新建笔记

• 为新笔记生成新的 unique_id，格式：b_<unix_time>_<random8>。
• 普通文本笔记使用 type=1。
• content 直接传 Markdown 字符串。后端会自动转为 Quill Delta，无需手动构建数组。
• create_time 使用当前 Unix 秒。
• status=1 表示正常笔记。
• is_collect=0 表示非收藏笔记（必填，0=否 1=是）。
• is_todo=0 表示非待办笔记（必填，0=否 1=是）。

更新笔记

• 更新前必须确认目标 unique_id。
• 如果用户没有提供明确 unique_id，先搜索，再让用户确认或选择最匹配的一条。
• content 传更新后的完整 Markdown 字符串。
• status=1 表示正常笔记。
• is_collect=0 表示非收藏笔记（必填，0=否 1=是）。
• is_todo=0 表示非待办笔记（必填，0=否 1=是）。
• 不要只发送「追加内容」并假装已合并，除非 API 请求体确实包含最终要保存的内容。

脚本调用指引

本 Skill 提供了 scripts/ 目录下的辅助脚本。在环境中配置了 HUADAI_API_KEY 后，可以直接执行：

bash

# 搜索笔记
./scripts/search.sh "关键词"

# 新建笔记
./scripts/upload.sh "笔记内容（Markdown）"

# 更新笔记
./scripts/update.sh <unique_id> "新内容"

Agent 可优先选择调用脚本而非手动拼接 curl。脚本已处理参数校验、错误处理和响应格式化。

通用错误处理

code	处理方式
200	成功。写操作可回复已保存/已更新
400001	API Key 无效，引导用户重新创建并配置 API Key
400003	无权限访问该资源
400018	笔记不存在，提示重新搜索确认
400024	需要有效会员，引导用户在话袋开通对应权益
500000	服务异常，提示稍后重试

安全规则

• 不输出 API Key。
• 不保存 API Key 到笔记正文。
• 不在未调用 API 或 API 未成功时声称操作完成。
• 不猜测已有笔记 ID、用户身份、隐藏内容。
• 不泄露搜索结果以外的任何用户数据。