aihaoji

Ai好记

Ai好记 Agent Open Platform を通じて、ユーザーのノートを検索、読み取り、エクスポート、整理します。実際のインターフェース、フィールド、利用シーンの詳細については references/agent-open-platform.md を参照してください。書き込み、記録の読み取り、エクスポート、自動分類、またはインターフェースパラメーターが不明な場合は、必ずこのリファレンスを読み込んでください。

トリガー条件

以下の優先順位に従って振り分けます。

1. ユーザーが操作対象をローカルファイル、コードリポジトリ、Obsidian、Notion、有道云笔记、またはその他のサービスにあると明示した場合は、指定された場所を優先し、この Skill をトリガーしません。
2. 場所が指定されておらず、リクエスト対象が個人ノート、個人ノートブック、またはこの Skill が対応するノートの詳細である場合は、デフォルトで Ai好记 をトリガーします。ここでいう個人ノートとは、ユーザーの外部個人ノートライブラリを指し、Agent や Claude の memory ではありません。「Ai好记」「AI好记」または aihaoji という語が含まれている必要はありません。
3. notes、folder、記録、ファイル、コンテンツなどの広い語があるだけでは、トリガーするには不十分です。ソースコード、テスト、インターフェースフィールド、ローカルファイルに関する文脈は、いずれも個人ノートの意図には該当しません。

対象範囲には、ノートの検索、エクスポート、空白のノートの作成、整理、移動、自動分類、ノートブックの管理、および要約、アウトライン、全文、原文、推敲稿、ハイライト、マーカー、注釈、自分の記録、AI ハイライトの確認が含まれます。個人ノートを Markdown でエクスポートする場合も、この Skill の対象です。ノートの作成時は Markdown を公開形式として使用します。ローカルの Markdown ファイルを作成、読み取り、または変更する場合は、この Skill の対象外です。

この Skill への振り分けは、書き込みの許可を意味しません。作成、名前変更、移動、削除、自動分類を行う前に、必ず読み取り専用で実際の ID を照会し、変更計画を提示して、明確な確認を待ってください。確認前に書き込みインターフェースを呼び出してはいけません。ノートブックの削除には、個別の確認が必要です。

設定

まず ~/.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 を直接提供でき、現在の Agent が検証して共有設定に書き込めます。このマシンに aihaoji-skills CLI がインストール済みの場合は、aihaoji-skills setup を実行することもできます。Key を取得したら、まず GET /agent-open/api/v1/auth/verify を呼び出して検証し、その後、権限を 0600 に設定して ~/.aihaoji/config.json に書き込みます。自動設定に失敗した場合に限り、利用可能な設定方法を使うようユーザーに案内します。

ホストへのインストール先

クロスプラットフォームでインストールする場合は、~/.agents/skills/aihaoji をグローバルなメインコピーとし、ホストごとに個別の内容を複製しません。

ホスト	読み込み先	説明
Codex	~/.agents/skills/aihaoji	最新の公式ユーザーレベル Skill ディレクトリ
OpenClaw	~/.agents/skills/aihaoji	personal-agent の参照元であり、~/.openclaw/skills より優先度が高い
Claude Code	~/.claude/skills/aihaoji	~/.agents/skills/aihaoji へのリンク
Hermes Agent	~/.agents/skills/aihaoji	~/.hermes/config.yaml の skills.external_dirs で有効化

Hermes Agent の設定：

skills:
  external_dirs:
    - ~/.agents/skills

~/.aihaoji/config.json は Codex、OpenClaw、Claude Code、Hermes Agent が共用するマシンレベルの Key 設定であり、いずれのホストの Skill ディレクトリにも属しません。ユーザーはチャットで Key を直接提供でき、現在の AI がこのファイルに書き込めます。書き込み後は権限を 0600 に保ちます。Claude Desktop と Claude Code では Skill の読み込み方式が異なります。上記の Claude のパスは Claude Code 用です。

インストールと設定方法

• クロスプラットフォームで Skill をインストールする場合：npx skills add AiHaoJi-Agent/aihaoji-skills -g を実行します。Skill はユーザーレベルのディレクトリにインストールされます。Codex と OpenClaw は ~/.agents/skills/aihaoji を読み込み、Claude Code は ~/.claude/skills/aihaoji を使用し、Hermes Agent は external_dirs を通じて共有ディレクトリを読み込みます。
• Key を設定する場合：まず現在の Agent が Key を検証して共有設定に書き込みます。このマシンに aihaoji-skills CLI がインストール済みの場合は、aihaoji-skills setup を実行できます。

Hermes Agent は、このリポジトリに skills.external_dirs を使用します。同じ名前のコピーを複数残すと、ホストが古いバージョンを読み込むおそれがあるため、複数残さないでください。

必須ルール

• ユーザーが Ai好记 のノートの検索、閲覧、探索、整理を求めた場合は、必ずオープンプラットフォームのインターフェースを呼び出してください。ノートの内容を推測するために、ローカルディレクトリ、ログ、キャッシュ、ソースコードをスキャンしてはいけません。
• 内部 ID はすべてインターフェースの戻り値から取得し、手入力してはいけません。folder_id、target_folder_id、note_id、move_item_list[].item_id は、いずれも事前に照会して確認する必要があります。
• 通常の表示では note_id、folder_id、user_id、key_id をデフォルトで非表示にします。ユーザーがデバッグまたは元のフィールドを要求した場合に限り表示します。
• インターフェースのエラー、タイムアウト、401/403/429/5xx が発生した場合は、Ai好记 オープンプラットフォームからデータを取得できないことを明確に説明してください。ローカル検索に切り替えてはいけません。
• 書き込み前に、必ず変更計画を提示してユーザーの確認を待ってください。ノートブックの削除には個別の確認が必要であり、自動整理のデフォルト計画に含めてはいけません。

パラメーターの取得元

パラメーター	取得元
folder_id	GET /agent-open/api/v1/folders が返す実際のノートブック ID
parent_id	子ノートブックを新規作成する場合は、実際の親 folder_id を使用します。トップレベルのノートブックには parent_id=0 を渡し、null は渡さないでください
target_folder_id	単一または複数のノートを移動する際の移動先ノートブック ID。ノートブックの一括移動にも使用します。実在するノートブック ID を指定する必要があります。ノートブックをルートに移動する場合は -1 を渡せます
note_id	GET /agent-open/api/v1/notes または詳細インターフェースが返す実際のノート ID
move_item_list	PC 版の移動インターフェースと同じ形式です。ノートは move_type=1、ノートブックは move_type=2 とし、item_id には実際の ID を指定します
name	ユーザーが明示的に入力した名前、または AI の自動分類計画で生成され、ユーザーが確認した名前
include_records	ユーザーがマーカー、ハイライト、注釈、自分の記録を確認する場合、または分類の根拠として注釈が必要な場合は true を渡します
include_export_markdown	ユーザーが Markdown をローカルにエクスポートすることを選択した場合は true を渡します

よく使うインターフェース

意図	インターフェース
Key の検証	GET /agent-open/api/v1/auth/verify
ノートブックツリー	GET /agent-open/api/v1/folders
ノート一覧／検索／最近のノート	GET /agent-open/api/v1/notes
ノートの詳細／セマンティックビュー／エクスポート／マーカー、注釈、自分の記録	GET /agent-open/api/v1/notes/{note_id}
ノートブックの新規作成	POST /agent-open/api/v1/folders
ノートブックの名前変更	PUT /agent-open/api/v1/folders/{folder_id}
ノートブックの削除	DELETE /agent-open/api/v1/folders/{folder_id}
空白のノートの作成	POST /agent-open/api/v1/notes。リクエスト本文には title、content_markdown、任意の folder_id を使用します
単一ノートの移動	PATCH /agent-open/api/v1/notes/{note_id}/folder。リクエスト本文には target_folder_id を使用します
ノートの一括移動	POST /agent-open/api/v1/notes/batch-move
ノートブックの一括移動	POST /agent-open/api/v1/folders/batch-move

ノートブックツリーの読み取りには folder:list が必要です。空白のノートの作成には note:create が必要です。その他の書き込み権限には通常 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。
• 创建空白笔记：先询问并确认标题、目标笔记本和 Markdown 正文摘要，再调用 POST /agent-open/api/v1/notes；创建成功后用返回的 note_id 调详情接口 semantic_view=full 回读验证。

整理与写入

写入固定顺序：

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

创建空白笔记的首版边界：单篇创建，content_markdown 必填且最多 100000 个字符；支持标题、粗体、列表、表格、链接、代码等安全 Markdown。不要传开放 HTML，不支持附件、图片上传、@ 引用、编辑、追加、删除或批量创建。

新建顶层笔记本时请求体必须使用 "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、note:create、folder:list、folder:write 或 note:move。
• 404：说明笔记或笔记本不存在，重新查询候选让用户确认。
• 429：说明触发频率限制，建议稍后再试或减少批量范围。

参考

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