Ai好记

Ai好记

通过 Ai好记 Agent Open Platform 查询、读取、导出和整理用户笔记。实际接口、字段和场景细节见 references/agent-open-platform.md；处理写入、记录读取、导出、自动归类或接口参数不确定时必须读取该参考。

配置

优先从 ~/.aihaoji/config.json 读取：

{
  "apiKey": "sk-sxxxxxxxx",
  "baseUrl": "https://openapi.aihaoji.com"
}

缺失时再读 $AIHAOJI_API_KEY 和 $AIHAOJI_BASE_URL。请求头固定为：

Authorization: $AIHAOJI_API_KEY

没有 API Key 时，引导用户去 https://openapi.aihaoji.com 创建 sk-s... 开发者密钥；拿到 key 后先调 GET /agent-open/api/v1/auth/verify 校验，再写入 ~/.aihaoji/config.json。自动配置失败时再提示 npx aihaoji-openclaw setup。

强制规则

• 用户要查、看、找、整理 Ai好记 笔记时，必须调用开放平台接口；不要扫描本地目录、日志、缓存或源码来猜笔记内容。
• 所有内部 ID 必须来自接口返回，不能手写：folder_id、target_folder_id、note_id、move_item_list[].item_id 都必须先查询确认。
• 普通展示默认隐藏 note_id 和 folder_id；只有用户要求调试或原始字段时再展示。
• 接口报错、超时、401/403/429/5xx 时，明确说明当前无法通过 Ai好记开放平台获取数据，不要退回本地搜索。
• 写入前必须展示变更计划并等待用户确认；删除笔记本必须单独确认，不能包含在自动整理默认计划里。

参数来源

常用接口

写入权限通常需要 folder:write 或 note:move；记录读取需要 note:read。

意图路由

• 列出笔记本：先调 GET /agent-open/api/v1/folders，按接口的 folder_tree_text 或 children 真实层级展示。
• 看某个笔记本里的笔记：先用 /folders 定位真实 folder_id，再调 /notes?folder_id=...；不要把笔记本名复用成 keyword。
• 在某个笔记本里搜关键词：先定位 folder_id，再调 /notes?folder_id=...&keyword=...；结果数量以 API 返回为准，不做人为二次删减。
• 查最近/最新 N 篇：/notes?page_no=1&page_size=N&sort_mode=create_time&sort_order=desc；未给 N 默认 10。
• 查最早/最老 N 篇：sort_order=asc；未给 N 默认 10。
• 按 URL 找笔记：把完整 URL 作为 keyword 搜索，优先匹配返回里的真实 URL。
• 看总结/大纲/精华速览：详情接口传 semantic_view=summary|outline|highlights。
• 看全文/原文/润色稿：先问 A：导出为 Markdown 文件到本地 / B：直接在聊天里查看；用户选 A 时用 include_export_markdown=true，选 B 时按 semantic_chunk_no 分块查看。
• 看划线/高亮/批注/我的记录：调详情接口并传 include_records=true；重点读取 data.records_detail.records、data.records_detail.my_record、data.records_detail.ai_highlights 和 data.records_detail.ai_highlights_status。

整理与写入

写入固定顺序：

1. 读取 folders 和 notes，确认真实 ID。
2. 读取详情和必要的记录信息。
3. 输出计划：将创建的笔记本、将移动的笔记/笔记本、目标位置、归类依据。
4. 等用户明确确认。
5. 创建缺失笔记本，再移动笔记或笔记本。
6. 重新查询目标笔记本或笔记列表验证结果。

新建顶层笔记本时请求体必须使用 "parent_id": 0。后端会把 0 归一为根级 parent_id=None；不要传 JSON null，线上接口可能返回“创建笔记本失败”。

自动归类整理要求：

• AI 自动归类整理必须先读笔记内容和记录依据，不能只凭标题批量移动，除非用户明确要求粗略整理。
• 已存在同名笔记本时复用，不重复创建。
• 目标不确定的笔记列为“待确认”，不要强行移动。
• 同一轮自动整理不删除笔记本。

批量移动请求优先使用 PC 端同形参数：

{
  "target_folder_id": 123,
  "move_item_list": [
    {"move_type": 1, "item_id": "task_xxx", "pre_id": null}
  ]
}

移动笔记本时 move_type=2，target_folder_id=-1 表示移动到根目录。

错误处理

• 401/403：提示 API Key 可能无效、过期、停用、删除、无权限、非会员或应用绑定失效。
• 权限不足：指出需要 note:list、note:read、folder:write 或 note:move。
• 404：说明笔记或笔记本不存在，重新查询候选让用户确认。
• 429：说明触发频率限制，建议稍后再试或减少批量范围。

参考

• 详细 API、字段、记录结构、导出规则和场景话术：references/agent-open-platform.md