osiman/openclaw-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
root
2026-03-31 21:04:10 +08:00
commit 8aac33bf65
15 changed files with 3056 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ima-skill/references/notes-api.md
+341
View File
@@ -0,0 +1,341 @@
# IMA笔记 API
## ⚠️ 必读约束
### 🔒 认证
所有请求必须携带 Header：
```
ima-openapi-clientid: {IMA_OPENAPI_CLIENTID}
ima-openapi-apikey: {IMA_OPENAPI_APIKEY}
Content-Type: application/json
```
### 🔒 安全规则
- 笔记属于用户隐私，**不要在群聊中主动展示笔记内容**。
- 仅响应授权用户的笔记操作请求。
---
## 快速决策
| 用户意图 | 接口别名 |
| ------------------------------------ | --------------------------------------------- |
| 「搜索笔记」「找包含XX的笔记」 | `/openapi/note/v1/search_note_book` |
| 「列出笔记本」「有哪些笔记本」 | `/openapi/note/v1/list_note_folder_by_cursor` |
| 「查看XX笔记本里的笔记」 | `/openapi/note/v1/list_note_by_folder_id` |
| 「从markdown新建笔记」「导入笔记」「创建笔记」「生成笔记」| `/openapi/note/v1/import_doc` |
| 「追加内容到笔记」「在笔记末尾添加」 | `/openapi/note/v1/append_doc` |
| 「获取笔记纯文本」「读取笔记内容」 | `/openapi/note/v1/get_doc_content` |
---
## 数据结构
---
#### DocBasicInfo
| 字段 | 类型 | 说明 |
| ------------ | -------- | ------------------------ |
| `basic_info` | DocBasic | 见 [DocBasic](#docbasic) |
---
#### DocBasic
| 字段 | 类型 | 说明 |
| --------------- | --------------------- | ------------------------------ |
| `docid` | string | 文章 id |
| `title` | string | 标题 |
| `summary` | string | 简介 |
| `create_time` | int64 | |
| `modify_time` | int64 | |
| `status` | DocStatus | 文章状态，`0`=正常，`1`=已删除 |
| `folder_id` | string | 文件夹 id |
| `folder_name` | string | 文件夹名称 |
| `summary_style` | map\<string, string\> | 简介样式 |
---
### FolderItem（笔记本条目）
`list_note_folder_by_cursor` 返回的笔记本对象，字段如下：
| 字段 | 类型 | 说明 |
| ------------------ | ------ | -------------------------------------------- |
| `folder_id` | string | 笔记本唯一 ID |
| `name` | string | 笔记本名称 |
| `note_number` | int64 | 笔记本内笔记数量 |
| `create_time` | int64 | 创建时间（Unix 毫秒） |
| `modify_time` | int64 | 修改时间（Unix 毫秒） |
| `parent_folder_id` | string | 上级笔记本 ID（支持嵌套） |
| `folder_type` | int | 类型：`0`=用户自建，`1`=全部笔记，`2`=未分类 |
| `status` | int | 状态：`0`=正常，`1`=已删除 |
---
#### QueryInfo
| 字段 | 类型 | 说明 |
| --------- | ------ | ---------- |
| `title` | string | 标题 query |
| `content` | string | 正文 query |
---
#### SearchedDoc
| 字段 | 类型 | 说明 |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------ |
| `doc` | DocBasicInfo | 笔记 basic 数据，见 [DocBasicInfo](#docbasicinfo) |
| `highlight_info` | map\<string, string\> | 该条笔记匹配的高亮词，key: `doc_title`（文档标题），value: 包含 `<em>高亮词</em>` 的字段值 |
---
#### NoteBookFolder
| 字段 | 类型 | 说明 |
| -------- | ----------------------- | -------------------------------------------------------------------------------- |
| `folder` | NoteBookFolderBasicInfo | 笔记本信息，非笔记本为空，见 [NoteBookFolderBasicInfo](#notebookfolderbasicinfo) |
---
#### NoteBookFolderBasicInfo
| 字段 | 类型 | 说明 |
| ------------ | ------------------- | ---------------------------------------------- |
| `basic_info` | NoteBookFolderBasic | 见 [NoteBookFolderBasic](#notebookfolderbasic) |
---
#### NoteBookFolderBasic
| 字段 | 类型 | 说明 |
| ------------- | ---------- | -------------------------------------------------- |
| `folder_id` | string | 文件夹 id |
| `name` | string | 笔记本名称 |
| `status` | DocStatus | 笔记本状态，`0`=正常，`1`=已删除 |
| `create_time` | int64 | 创建时间 |
| `modify_time` | int64 | 修改时间 |
| `note_number` | int64 | 笔记数量 |
| `folder_type` | FolderType | 文件夹类型：`0`=用户自建，`1`=全部笔记，`2`=未分类 |
---
#### NoteBookInfo
| 字段 | 类型 | 说明 |
| ------------ | ------------ | ---------------------------------------------- |
| `basic_info` | DocBasicInfo | 笔记基础信息，见 [DocBasicInfo](#docbasicinfo) |
---
## 接口详情
### 1. 搜索笔记
POST /openapi/note/v1/search_note_book
**触发场景**：用户说「搜索」「找笔记」「查找包含XX的内容」
#### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ---------- | ---- | ------------------------------------------------------------------------ |
| `search_type` | SearchType | 否 | 检索方式，默认为标题，`0`=标题，`1`=正文 |
| `sort_type` | SortType | 否 | 排序方式，默认为更新时间，`0`=更新时间，`1`=创建时间，`2`=标题，`3`=大小 |
| `query_info` | QueryInfo | 否 | 用户 query，见 [QueryInfo](#queryinfo) |
| `start` | int64 | 是 | 翻页字段 |
| `end` | int64 | 是 | 翻页字段 |
| `query_id` | string | 否 | queryid |
#### 返回字段
| 字段 | 类型 | 说明 |
| --------------- | ------------- | ------------------------------------------------- |
| `docs` | SearchedDoc[] | 检索到的笔记 list，见 [SearchedDoc](#searcheddoc) |
| `is_end` | bool | 是否为最后一批数据 |
| `total_hit_num` | int64 | 检索命中结果总数 |
---
### 2. 列出笔记本
POST /openapi/note/v1/list_note_folder_by_cursor
**触发场景**：用户说「列出笔记本」「有哪些分类」「查看笔记本目录」
#### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ------ | ---------------------------------------- |
| `cursor` | string | **是** | 游标，第一页传 `"0"`，后续传后台返回的值 |
| `limit` | uint64 | **是** | 获取笔记数量限制 |
#### 返回字段
| 字段 | 类型 | 说明 |
| ------------------- | ---------------- | ------------------------------------ |
| `note_book_folders` | NoteBookFolder[] | 见 [NoteBookFolder](#notebookfolder) |
| `next_cursor` | string | 下次请求的起始游标 |
| `is_end` | bool | 是否为最后一批数据 |
---
### 3. 按笔记本拉取笔记列表
POST /openapi/note/v1/list_note_by_folder_id
**触发场景**：用户说「查看XX笔记本的笔记」「列出这个笔记本里的内容」
> 全部笔记根目录的 `folder_id` 为 `user_list_{userid}`，可从「列出笔记本」返回的 `folder_id` 获取。
#### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ------ | ----------------------------- |
| `folder_id` | string | 否 | 笔记本 ID，根目录为空 |
| `cursor` | string | **是** | 当前游标，首次传空字符串 `""` |
| `limit` | uint64 | **是** | 获取笔记数量限制 |
#### 返回字段
| 字段 | 类型 | 说明 |
| ---------------- | -------------- | -------------------------------- |
| `note_book_list` | NoteBookInfo[] | 见 [NoteBookInfo](#notebookinfo) |
| `next_cursor` | string | 下次请求的起始游标 |
| `is_end` | bool | 是否为最后一批数据 |
---
### 4. 从 Markdown 新建笔记
POST /openapi/note/v1/import_doc
**触发场景**：用户说「从 Markdown 新建笔记」「导入笔记」「把这段 Markdown 保存为笔记」
#### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ------ | --------------------------------------------------------------- |
| `content_format` | int | **是** | 文本类型：`1`=Markdown（默认）目前仅支持 `MARKDOWN`（值为 `1`） |
| `content` | string | **是** | 笔记正文内容, 只支持markdown格式 |
| `folder_id` | string | 否 | 关联的笔记本id |
#### 返回字段
| 字段 | 类型 | 说明 |
| -------- | ------ | ------------- |
| `doc_id` | string | 新doc的唯一ID |
---
### 5. 追加内容到笔记
POST /openapi/note/v1/append_doc
**触发场景**：用户说「在这篇笔记末尾追加内容」「把 XX 添加到笔记里」
> ⚠️ **敏感操作**：追加会不可撤销地修改已有笔记。如果用户没有明确指定目标笔记（提供 `doc_id` 或笔记标题），**必须先向用户确认目标笔记**，不得自行猜测。模糊场景应优先建议用户使用 `import_doc` 新建笔记。
#### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ------ | --------------------------------------------------------------- |
| `doc_id` | string | **是** | 目标笔记的唯一ID, 需要是本人的笔记 |
| `content_format` | int | **是** | 文本类型：`1`=Markdown（默认）目前仅支持 `MARKDOWN`（值为 `1`） |
| `content` | string | **是** | 要追加的文本内容, 只支持markdown格式 |
#### 返回字段
| 字段 | 类型 | 说明 |
| -------- | ------ | ---------------- |
| `doc_id` | string | 目标笔记的唯一ID |
---
### 6. 获取笔记纯文本
POST /openapi/note/v1/get_doc_content
**触发场景**：用户说「读取笔记内容」「获取这篇笔记的纯文本」「把笔记转成 Markdown」
#### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| ----------------------- | ------ | ------ | ------------------------------------------------------------------ |
| `doc_id` | string | **是** | 目标笔记的唯一 ID, 需要是本人的笔记 |
| `target_content_format` | int | **是** | 目标文本类型：`0`=纯文本（推荐），`1`=Markdown（不支持），`2`=JSON |
#### 返回字段
| 字段 | 类型 | 说明 |
| --------- | ------ | ----------------------------------------------------- |
| `content` | string | 笔记的文本内容（按 `target_content_format` 格式返回） |
---
## 枚举值
### `sort_type`（排序方式）
| 值 | 说明 |
| --- | ---------------- |
| `0` | 更新时间（默认） |
| `1` | 创建时间 |
| `2` | 标题 |
| `3` | 大小 |
### `search_type`（检索方式）
| 值 | 说明 |
| --- | ---------------- |
| `0` | 标题检索（默认） |
| `1` | 正文检索 |
### `content_format`（文本类型）
| 值 | 说明 |
| --- | ------------------------ |
| `0` | PLAINTEXT - 纯文本 |
| `1` | MARKDOWN - Markdown 格式 |
| `2` | JSON - JSON 格式 |
### `FolderType`
| 值 | 说明 |
| --- | -------- |
| `0` | 用户自建 |
| `1` | 全部笔记 |
| `2` | 未分类 |
---
## 游标翻页使用规范
1. **首次请求**：`cursor` 传空字符串 `""`
2. 检查返回的 `is_end`：`false` 表示还有更多数据
3. 将返回的 `next_cursor` 作为下次请求的 `cursor`
4. `is_end = true` 时停止翻页
---
## 错误码
| 错误码 | 说明 |
| ------ | -------------------------------------------- |
| 0 | 成功 |
| 100001 | 参数错误 |
| 100002 | 携带无效的 ID |
| 100003 | 服务器内部错误 |
| 100004 | 拉取的 size 不合法（超出范围）/ 用户空间不够 |
| 100005 | 不能获取私有笔记的访客信息 / 不是笔记的作者 |
| 100006 | 笔记已被删除 |
| 100008 | 版本冲突 |
| 100009 | 单篇笔记超过最大限制 |
| 310001 | 笔记本不存在 |
| 20002 | apiKey超过最大限频 |
| 20004 | apikey鉴权失败 |