aihaoji

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ai好记

通过 Ai好记 Agent Open Platform 查询、读取、导出和整理用户笔记。实际接口、字段和场景细节见

references/agent-open-platform.md

；处理写入、记录读取、导出、自动归类或接口参数不确定时必须读取该参考。

Use the Ai好记 Agent Open Platform to query, read, export, and organize user notes. For actual endpoints, fields, and use-case details, see

references/agent-open-platform.md

; this reference must be read when handling writes, record retrieval, exports, automatic classification, or when API parameters are uncertain.

触发边界

Trigger Boundaries

按以下优先级路由：

用户明确指定操作对象位于本地文件、代码仓库、Obsidian、Notion、有道云笔记或其他服务时，服从指定载体，不触发本 Skill。
未指定载体，且请求对象是个人笔记、个人笔记本或本 Skill 支持的笔记详情时，默认触发 Ai好记；这里指用户的外部个人笔记库，不是 Agent 或 Claude memory，无需出现“Ai好记”“AI好记”或
```
aihaoji
```
。
只出现
```
notes
```
、
```
folder
```
、记录、文件或内容等宽泛词，不足以触发；源码、测试、接口字段和本地文件上下文均不属于个人笔记意图。

正向范围包括查询、搜索、导出、创建空白笔记、整理、移动和自动归类笔记，管理笔记本，以及查看总结、大纲、全文、原文、润色稿、划线、高亮、批注、我的记录和 AI 高亮。导出个人笔记为 Markdown 仍属于本 Skill；创建笔记公开使用 Markdown；创建、读取或修改一个本地 Markdown 文件则不属于本 Skill。

路由到本 Skill 不等于授权写入：创建、重命名、移动、删除和自动归类前，必须先只读查询真实 ID、展示变更计划并等待明确确认；确认前不得调用写接口，删除笔记本仍须单独确认。

Route requests according to the following priority:

When the user explicitly specifies that the target is in local files, a code repository, Obsidian, Notion, Youdao Note, or another service, follow the specified carrier and do not trigger this Skill.
When no carrier is specified and the request concerns personal notes, personal notebooks, or note details supported by this Skill, trigger Ai好记 by default. This refers to the user’s external personal note library, not Agent or Claude memory, and the user does not need to mention “Ai好记,” “AI好记,” or
```
aihaoji
```
.
Broad terms such as
```
notes
```
,
```
folder
```
, records, files, or content are not sufficient on their own. Source code, tests, API fields, and local-file contexts do not indicate a personal-note intent.

The positive scope includes querying, searching, exporting, creating blank notes, organizing, moving, and automatically classifying notes; managing notebooks; and viewing summaries, outlines, full text, original text, polished versions, highlights, annotations, My Records, and AI Highlights. Exporting personal notes to Markdown still falls within this Skill; creating notes uses Markdown directly; creating, reading, or modifying a local Markdown file does not fall within this Skill.

Routing to this Skill does not authorize writes. Before creating, renaming, moving, deleting, or automatically classifying anything, first perform read-only queries to obtain the real IDs, present a change plan, and wait for explicit confirmation. Do not call write endpoints before confirmation. Deleting a notebook still requires separate confirmation.

配置

Configuration

优先从

~/.aihaoji/config.json

读取：

json

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

缺失时再读

$AIHAOJI_API_KEY

和

$AIHAOJI_BASE_URL

。请求头固定为：

text

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

校验，再写入权限为

的

~/.aihaoji/config.json

。自动配置失败时再提示用户使用可用的配置入口。

Prefer reading from

~/.aihaoji/config.json

json

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

If it is missing, then read

$AIHAOJI_API_KEY

and

$AIHAOJI_BASE_URL

. The request header is always:

text

Authorization: $AIHAOJI_API_KEY

When no API Key is available, guide the user to

https://openapi.aihaoji.com

to create an

sk-s...

developer key. The user may provide the Key directly in chat, in which case the current Agent validates it and writes it to the shared configuration. If the

aihaoji-skills

CLI is installed locally, the user may also run

aihaoji-skills setup

. After obtaining the Key, first validate it by calling

GET /agent-open/api/v1/auth/verify

, then write it to

~/.aihaoji/config.json

with

permissions. If automatic configuration fails, prompt the user to use an available configuration entry point.

宿主安装位置

Host Installation Locations

跨平台安装时，以

~/.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 配置：

yaml

skills:
  external_dirs:
    - ~/.agents/skills

~/.aihaoji/config.json

是 Codex、OpenClaw、Claude Code 和 Hermes Agent 共用的机器级 Key 配置，不属于任何宿主的 Skill 目录。用户可以在聊天中直接提供 Key，由当前 AI 写入该文件；写入后保持

权限。Claude Desktop 与 Claude Code 的 Skill 加载机制不同，上述 Claude 路径针对 Claude Code。

For cross-platform installation, use

~/.agents/skills/aihaoji

as the global master copy and do not duplicate separate content for every host:

Host	Read Location	Description
Codex	`~/.agents/skills/aihaoji`	Latest official user-level Skill directory
OpenClaw	`~/.agents/skills/aihaoji`	personal-agent source; takes priority over `~/.openclaw/skills`
Claude Code	`~/.claude/skills/aihaoji`	Symlink to `~/.agents/skills/aihaoji`
Hermes Agent	`~/.agents/skills/aihaoji`	Enabled through `skills.external_dirs` in `~/.hermes/config.yaml`

Hermes Agent configuration:

yaml

skills:
  external_dirs:
    - ~/.agents/skills

~/.aihaoji/config.json

is the shared machine-level Key configuration for Codex, OpenClaw, Claude Code, and Hermes Agent, and does not belong to any host’s Skill directory. Users may provide the Key directly in chat, in which case the current AI writes it to this file. Keep the file permissions at

after writing. Claude Desktop and Claude Code use different Skill-loading mechanisms; the Claude path above applies to Claude Code.

安装与配置入口

Installation and Configuration Entry Points

跨平台安装 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

。不要同时保留多个同名副本，以免宿主加载到旧版本。

Cross-platform Skill installation: run
```
npx skills add AiHaoJi-Agent/aihaoji-skills -g
```
. This installs the Skill into the user-level directory. Codex and OpenClaw read
```
~/.agents/skills/aihaoji
```
, Claude Code uses
```
~/.claude/skills/aihaoji
```
, and Hermes Agent reads the shared directory through
```
external_dirs
```
.
Key configuration: preferably, the current Agent validates the Key and writes it to the shared configuration. If the
```
aihaoji-skills
```
CLI is installed locally, the user may run
```
aihaoji-skills setup
```
.

Hermes Agent uses

skills.external_dirs

for this repository. Do not keep multiple copies with the same name, as this may cause a host to load an outdated version.

强制规则

Mandatory Rules

用户要查、看、找、整理 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好记开放平台获取数据，不要退回本地搜索。
写入前必须展示变更计划并等待用户确认；删除笔记本必须单独确认，不能包含在自动整理默认计划里。

When the user wants to query, view, find, or organize Ai好记 notes, the Open Platform endpoints must be called. Do not scan local directories, logs, caches, or source code to guess note content.
Every internal ID must come from an API response and must never be written manually.
```
folder_id
```
,
```
target_folder_id
```
,
```
note_id
```
, and
```
move_item_list[].item_id
```
must first be queried and confirmed.
Hide
```
note_id
```
,
```
folder_id
```
,
```
user_id
```
, and
```
key_id
```
during normal display. Show them only when the user requests debugging information or raw fields.
If an endpoint reports an error, times out, or returns
```
401/403/429/5xx
```
, clearly state that data cannot currently be obtained through the Ai好记 Open Platform. Do not fall back to a local search.
Before every write, present the change plan and wait for user confirmation. Deleting a notebook requires separate confirmation and must not be included in the default automatic-organization plan.

参数来源

Parameter Sources

参数	来源
`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`

Parameter	Source
`folder_id`	Real notebook ID returned by `GET /agent-open/api/v1/folders`
`parent_id`	For a new sub-notebook, use the real parent `folder_id` ; for a top-level notebook, pass `parent_id=0` , not `null`
`target_folder_id`	Target notebook ID for moving one or multiple notes, also used when bulk-moving notebooks; must be a real notebook ID; use `-1` to move a notebook to the root directory
`note_id`	Real note ID returned by `GET /agent-open/api/v1/notes` or a details endpoint
`move_item_list`	Same structure as the PC move endpoint: notes use `move_type=1` , notebooks use `move_type=2` , and `item_id` is the real ID
`name`	Explicit user input, or an AI-generated automatic-classification plan that has been confirmed by the user
`include_records`	Set to `true` when the user wants highlights, annotations, or My Records, or when classification requires annotation evidence
`include_export_markdown`	Set to `true` when the user selects exporting Markdown to the local system

常用接口

Common Endpoints

意图	接口
校验 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

。

Intent	Endpoint
Verify Key	`GET /agent-open/api/v1/auth/verify`
Notebook tree	`GET /agent-open/api/v1/folders`
Note list / search / recent notes	`GET /agent-open/api/v1/notes`
Note details / semantic view / export / highlights, annotations, and My Records	`GET /agent-open/api/v1/notes/{note_id}`
Create notebook	`POST /agent-open/api/v1/folders`
Rename notebook	`PUT /agent-open/api/v1/folders/{folder_id}`
Delete notebook	`DELETE /agent-open/api/v1/folders/{folder_id}`
Create blank note	`POST /agent-open/api/v1/notes` , with `title` , `content_markdown` , and optional `folder_id` in the request body
Move a single note	`PATCH /agent-open/api/v1/notes/{note_id}/folder` , with `target_folder_id` in the request body
Bulk-move notes	`POST /agent-open/api/v1/notes/batch-move`
Bulk-move notebooks	`POST /agent-open/api/v1/folders/batch-move`

Reading the notebook tree requires

folder:list

; creating a blank note requires

note:create

; other write permissions generally require

folder:write

note:move

; reading records requires

note:read

意图路由

Intent Routing

列出笔记本：先调
```
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
```
回读验证。

List notebooks: first call
```
GET /agent-open/api/v1/folders
```
, then display the actual hierarchy from the endpoint’s
```
folder_tree_text
```
or
```
children
```
.
View notes in a notebook: first use
```
/folders
```
to locate the real
```
folder_id
```
, then call
```
/notes?folder_id=...
```
; do not reuse the notebook name as
```
keyword
```
.
Search for a keyword within a notebook: first locate
```
folder_id
```
, then call
```
/notes?folder_id=...&keyword=...
```
; use the number of results returned by the API without applying an additional manual reduction.
Find the most recent N notes: use
```
/notes?page_no=1&page_size=N&sort_mode=create_time&sort_order=desc
```
; if N is not specified, default to 10.
Find the oldest N notes: use
```
sort_order=asc
```
; if N is not specified, default to 10.
Find a note by URL: search using the complete URL as
```
keyword
```
and prioritize matching the real URL in the returned results.
View a summary, outline, or highlights overview: pass
```
semantic_view=summary|outline|highlights
```
to the details endpoint.

View full text, original text, or a polished version: first ask

A: Export as a Markdown file to the local system

B: View directly in the chat

. For A, use

include_export_markdown=true

; for B, view it in chunks using

semantic_chunk_no

View highlights, annotations, or My Records: call the details endpoint with

include_records=true

; focus on

data.records_detail.records

data.records_detail.my_record

data.records_detail.ai_highlights

, and

data.records_detail.ai_highlights_status

Create a blank note: first ask for and confirm the title, target notebook, and Markdown body summary, then call
```
POST /agent-open/api/v1/notes
```
. After creation succeeds, use the returned
```
note_id
```
to call the details endpoint with
```
semantic_view=full
```
and verify the result by reading it back.

整理与写入

Organization and Writes

写入固定顺序：

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

创建空白笔记的首版边界：单篇创建，

content_markdown

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

新建顶层笔记本时请求体必须使用

"parent_id": 0

。后端会把

归一为根级

parent_id=None

；不要传 JSON

null

，线上接口可能返回“创建笔记本失败”。

自动归类整理要求：

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

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

json

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

移动笔记本时

move_type=2

，

target_folder_id=-1

表示移动到根目录。

The required write sequence is:

Read
```
folders
```
and
```
notes
```
to confirm the real IDs.
Read note details and any necessary record information.
Present a plan containing the notebooks to create, notes or notebooks to move, target locations, and classification rationale.
Wait for explicit user confirmation.
Create missing notebooks, then move the notes or notebooks.
Re-query the target notebook or note list to verify the result.

Initial boundaries for creating blank notes: create one note at a time;

content_markdown

is required and may contain at most 100000 characters. Safe Markdown such as headings, bold text, lists, tables, links, and code is supported. Do not pass unrestricted HTML. Attachments, image uploads, @ references, editing, appending, deleting, and bulk creation are not supported.

When creating a top-level notebook, the request body must use

"parent_id": 0

. The backend normalizes

to the root-level

parent_id=None

; do not send JSON

null

, because the production endpoint may return a “Failed to create notebook” error.

Requirements for automatic classification and organization:

AI-powered automatic classification must first read the note content and record evidence. Do not bulk-move notes based only on their titles unless the user explicitly requests rough organization.
Reuse an existing notebook with the same name instead of creating a duplicate.
List notes with uncertain destinations as “Pending confirmation”; do not force them into a destination.
Do not delete notebooks during the same automatic-organization run.

Prefer the same parameters as the PC endpoint for bulk-move requests:

json

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

When moving notebooks, use

move_type=2

. A

target_folder_id=-1

value moves the notebook to the root directory.

错误处理

Error Handling

```
401/403
```
：提示 API Key 可能无效、过期、停用、删除、无权限、非会员或应用绑定失效。

权限不足：指出需要

note:list

、

note:read

、

note:create

、

folder:list

、

folder:write

或

note:move

。

```
404
```
：说明笔记或笔记本不存在，重新查询候选让用户确认。
```
429
```
：说明触发频率限制，建议稍后再试或减少批量范围。

```
401/403
```
: Explain that the API Key may be invalid, expired, disabled, deleted, unauthorized, associated with a non-member account, or no longer bound to the application.
Insufficient permissions: Identify the required permission:
```
note:list
```
,
```
note:read
```
,
```
note:create
```
,
```
folder:list
```
,
```
folder:write
```
, or
```
note:move
```
.
```
404
```
: Explain that the note or notebook does not exist, then re-query the candidates and ask the user to confirm.
```
429
```
: Explain that the rate limit was triggered and suggest trying again later or reducing the batch size.

参考

Reference

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

Detailed API information, fields, record structures, export rules, and scenario wording:
```
references/agent-open-platform.md
```