get

# 得到大脑（Get笔记）Skill ## ⚠️ Agent 必读约束 ### 🌐 Base URL ``` https://openapi.biji.com ``` 所有 API 请求必须使用此 Base URL，不要使用 `biji.com` 或其他地址。 ### 🔑 认证 请求头： - `Authorization: $GETNOTE_API_KEY`（格式：`gk_live_xxx`） - `X-Client-ID: $GETNOTE_CLIENT_ID`（格式：`cli_xxx`） **每次调用 API 前先检查 `$GETNOTE_API_KEY` 是否存在**。若不存在，提示用户运行 `/note config` 完成配置，配置完成后再继续执行用户原本的请求。 Scope 权限：`note.content.read`（读取）、`note.content.write`（写入）、`note.recall.read`（搜索）。完整列表见 [references/api-details.md](references/api-details.md#scope-权限列表)。 ### 🔢 笔记 ID 处理规则（重要！） 笔记 ID 是 **64 位整数（int64）**，超出 JavaScript `Number.MAX_SAFE_INTEGER`，直接 `JSON.parse` 会**静默丢失精度**。 **正确做法**：始终把 ID 当字符串处理，在 `JSON.parse` 之前替换： ```javascript const safe = text.replace(/"(id|note_id|parent_id|follow_id|live_id)"\s*:\s*(\d+)/g, '"$1":"$2"'); // 注：next_cursor 已不需要处理，翻页请直接使用响应中的 cursor（string）字段 const data = JSON.parse(safe); ``` Python / Go 等语言原生支持大整数，无此问题。 ### 🔒 安全规则 - 笔记数据属于用户隐私，不在群聊中主动展示笔记内容 - 若配置了 `GETNOTE_OWNER_ID`，检查 sender_id 是否匹配；不匹配时回复「抱歉，笔记是私密的，我无法操作」 - API 返回 `error.reason: "not_member"` 或错误码 `10201` 时，引导开通会员：https://www.biji.com/checkout?product_alias=9Ab36BB3ZD&spm=wangye - 创建笔记建议间隔 1 分钟以上，避免触发限流 ### 🚫 反幻觉边界（严格禁止） - **禁止编造 note_id**：所有 note_id 必须来自 API 响应，不得凭空构造或推测 - **禁止跳过轮询**：链接/图片笔记返回 `task_id` 后，**必须**轮询 `/task/progress` 直到 `success` 或 `failed`，不得假设任务已完成 - **禁止伪造 API 响应**：不得在未实际调用 API 的情况下告诉用户「已保存」「已删除」 - **禁止忽略错误码**：API 返回 `success: false` 时必须处理，不得静默吞掉 - **禁止混淆内链和分享链接**：`biji.com/note/{id}` 是内链（仅笔记主人可见），`share_note/{id}` 是分享链接（公开可访问），两者不可互换 ### 🔄 失败重试策略 **异步任务失败**（链接/图片保存）： 1. `/task/progress` 返回 `status: "failed"` 时，向用户报告失败原因（`error_msg`） 2. 自动重试一次：用相同参数重新调用 `/note/save`，获取新 `task_id` 并重新轮询 3. 二次失败则停止，告知用户「保存失败，请稍后重试或检查链接是否可访问」 **网络/服务错误**（HTTP 5xx 或超时）： 1. 等待 5 秒后重试一次 2. 仍然失败则报告错误，附上 `request_id` 方便排查 **限流**（错误码 `10202` 或 HTTP 429）： 1. 读取响应中的 `rate_limit.retry_after` 字段 2. 等待指定秒数后重试 3. 无 `retry_after` 时默认等待 10 秒 --- ## 执行流程概览 ``` 用户意图 → 路由匹配 → 读取 references 文档 → 构造 API 请求 → 执行 ↓ ┌─ 同步操作 ──→ 验证响应 → 返回结果 │ └─ 异步操作 ──→ 轮询进度 ──→ success → 返回结果 ↓ ↓ 10-30s 间隔 failed → 自动重试(1次) ↓ 二次失败 → 报告用户 ``` **关键原则**： - **模型输出 ≠ 最终结果**：API 调用后必须验证响应，确认 `success: true` 且数据完整 - **状态来自 API**：所有笔记状态（是否存在、内容、标签等）以 API 返回为准，不依赖上下文记忆 - **最小操作原则**：更新笔记时只传需要修改的字段，不重写整篇内容 --- ## 指令路由表 > 匹配指令后，用 **read 工具**读取对应的 `references/xxx.md` 获取完整 API 文档。 | 指令 | 角色 | 说明 | 详细文档 | |------|------|------|---------| | `/note save` 或「记一下」| 📝 速记员 | 保存文本/链接/图片笔记（含异步轮询流程） | [references/save.md](references/save.md) | | `/note search` 或「搜一下」| 🔍 搜索官 | 全局语义搜索 + 知识库语义搜索 | [references/search.md](references/search.md) | | `/note list` 或「最近的笔记」| 📋 整理师 | 浏览列表、查看详情、更新、删除 | [references/list.md](references/list.md) | | `/note kb` 或「知识库」| 📚 图书管理员 | 知识库 CRUD + 博主订阅 + 直播订阅 | [references/knowledge.md](references/knowledge.md) | | `/note tag` 或「加标签」| 🏷️ 标签员 | 添加/删除标签 | [references/tags.md](references/tags.md) | | `/note config` 或「配置笔记」| ⚙️ 配置 | 配置 API Key 和 Client ID | [references/oauth.md](references/oauth.md) | --- ## 🎬 视频链接处理流程（YouTube / Bilibili / 抖音） > **路由说明**：视频 URL 由 `url-process` skill 识别后路由到此流程。当用户说「这个视频」「视频笔记」等自然语言时，getnote 直接处理。 **核心思路**：视频链接不适合 web_fetch 抓取（JS 渲染、反爬），交给 Get笔记服务端异步提取内容（`note_type=link`）。流程分两步：先存链接拿 `task_id`，轮询完成后用 `note_id` 查详情。 ### 第一步：用户发来视频链接（首次） **识别视频平台**（实测均兼容）： | URL 模式 | 平台 | 实测结果 | |---------|------|---------| | `youtube.com/watch?v=` `youtu.be/` | YouTube | ⚠️ 部分视频可能提取失败（无字幕/反爬），需降级 | | `bilibili.com/video/` `b23.tv/` | Bilibili | 未实测 | | `douyin.com/video/` `iesdouyin.com/share/video/` | 抖音 | ✅ 实测成功，30-44s 完成 | | `douyin.com/jingxuan?modal_id=` | 抖音（精选页） | ✅ 实测成功，~120s 完成 | **直接调 save API（note_type=link），不读 references**： ```bash # 步骤 1：写 JSON payload（用 note_type 和 link_url 字段） file_write(path="/tmp/note_payload.json", content='{"note_type":"link","link_url":"视频URL","title":"可选标题"}') # 步骤 2：curl 调 API curl -s -X POST "https://openapi.biji.com/open/api/v1/resource/note/save" \ -H "Authorization: $GETNOTE_API_KEY" \ -H "X-Client-ID: $GETNOTE_CLIENT_ID" \ -H "Content-Type: application/json" \ -d @/tmp/note_payload.json ``` **解析响应**（普通链接是异步的）： ```json { "data": { "created_count": 1, "tasks": [{"task_id": "69c3995e99f5a67e", "url": "https://..."}], "message": "链接笔记任务已创建，请通过 /note/task/progress 接口查询处理状态" } } ``` - ⚠️ `task_id` 在 `data.tasks[0].task_id`，不是 `data.task_id` - 拿到 task_id 后，Get笔记服务端开始异步提取视频内容 **回复用户（关键！）**： > ✅ 已把这个视频存到 Get笔记了，服务端正在提取内容（task_id: `xxx`）。 > 过几分钟你再来问我「那个视频讲了什么」，我就能查到笔记内容了。 **⚠️ 必须在回复中埋下「下次查询」的说明**： 1. 告诉用户过几分钟再来问 2. 告诉用户怎么问（示例：「那个视频的内容好了吗」「视频笔记查一下」） ### 第二步：用户回来问视频内容（后续） **当用户回来问「那个视频」「视频笔记好了吗」「视频讲了什么」时**： 1. 从对话历史中找到之前的 `task_id` 2. 先轮询任务进度： ```bash curl -s -X POST "https://openapi.biji.com/open/api/v1/resource/note/task/progress" \ -H "Authorization: $GETNOTE_API_KEY" \ -H "X-Client-ID: $GETNOTE_CLIENT_ID" \ -H "Content-Type: application/json" \ -d '{"task_id":"TASK_ID"}' ``` 3. 解析响应（实测经验）： - `status: "success"` → 任务完成，`note_id` 字段有值 - `status: "processing"` → 还在处理中，note_id 可能已有值但 content 为空 - `status: "failed"` → 失败，报告 error_msg - ⚠️ **不要只看 error_msg**：success 状态下 error_msg 可能有残留值（如"生成笔记失败，请手动重试"），必须以 `status` 字段为准 4. **轮询策略**（实测：抖音 30-120s，YouTube 可能失败）： - 首次轮询：保存后等 30 秒 - 后续轮询：每 30 秒一次，最多轮询 5 次（共 ~150s） - 超过 150s 仍 processing → 告诉用户「还在处理，稍后再来问」 - status=failed → 告诉用户提取失败，**降级到 web_search/web_fetch** 抓取视频信息 5. 任务成功后，用 `note_id` 调 detail API 查笔记内容： ```bash curl -s -X GET "https://openapi.biji.com/open/api/v1/resource/note/detail?id=NOTE_ID" \ -H "Authorization: $GETNOTE_API_KEY" \ -H "X-Client-ID: $GETNOTE_CLIENT_ID" ``` 6. 解析响应：内容在 `data.note.content` 字段，链接原文在 `data.note.web_page.content` 7. 总结或原样返回给用户 **⚠️ 查询时的决策逻辑**： - 对话历史中有 task_id → 先轮询 `/task/progress`，成功后用 note_id 调 `detail API` - 对话历史中没有 task_id → 用 `POST /resource/recall` 搜索关键词（如视频标题/平台名） - 搜索结果中 `note_type: "link"` 的就是之前存的视频笔记 ### 视频链接处理铁律 - ❌ 不要用 `web_fetch` / `web_search` 抓视频页面（JS 渲染，拿不到内容） - ❌ 不要用 `agent-browser` 打开视频页面（慢且不必要） - ✅ 直接用 `save API (note_type=link, link_url=URL)` 交给 Get笔记服务端提取 - ✅ 存完后告诉用户「过几分钟再来问」 - ✅ 用户回来问时，先用 `task_id` 轮询 `/task/progress`，成功后用 `note_id` 调 `detail API`（参数 `id`） - ✅ detail API 参数名是 `id`（不是 `note_id`），响应内容在 `data.note.content`，原文在 `data.note.web_page.content` - ✅ 如果对话历史中找不到 task_id，用 `recall` 搜索 - ✅ **降级策略**：task 失败（status=failed）时，允许 fallback 到 `web_search`/`web_fetch` 抓取视频信息，并告知用户「Get笔记提取失败，改用网页抓取」 - ✅ **轮询策略**：首次等 30s，之后每 30s 一次，最多 5 次 --- ## 自然语言路由 ``` 包含 URL（`biji.com/note/share_note/*` 或 `d.biji.com/*` 短链） → /note save（link 模式，同步返回 note_id） 包含 URL（`biji.com/note/{note_id}` 内链） → /note list（查看详情），如需在正文引用其他笔记请使用 `https://biji.com/note/{note_id}` 格式内链（**默认用内链，除非用户明确要求分享**） 其他 URL → /note save（link 模式，异步返回 task_id） 包含图片 → /note save（image 模式） 「记/存/保存/收藏」 → /note save（text 模式） 「搜/找找/有没有 XX」 → /note search 「最近/列表/看看/查笔记」 → /note list 「改/更新/编辑笔记」 → /note list（更新笔记） 「知识库」相关 → /note kb 「标签」相关 → /note tag 「配置/授权/连接笔记」 → /note config ``` **决策原则**：优先匹配最具体的意图。有 URL 就是 `/save link`，有图片就是 `/save image`，不确定时询问用户。 --- ## API 路由表 > ⚠️ **构造请求时必须使用下表中的完整路径**，Base URL 为 `https://openapi.biji.com`。如果收到 404，说明路径不对，请对照此表检查。 ### 笔记 | 方法 | 路径 | 说明 | 详细文档 | |------|------|------|----------| | POST | `/open/api/v1/resource/note/save` | 新建笔记（文本/链接/图片） | [save.md](references/save.md) | | POST | `/open/api/v1/resource/note/task/progress` | 查询异步任务进度 | [save.md](references/save.md) | | GET | `/open/api/v1/resource/note/list` | 笔记列表（分页） | [list.md](references/list.md) | | GET | `/open/api/v1/resource/note/detail` | 笔记详情 | [list.md](references/list.md) | | POST | `/open/api/v1/resource/note/update` | 更新笔记 | [list.md](references/list.md) | | POST | `/open/api/v1/resource/note/delete` | 删除笔记 | [list.md](references/list.md) | | POST | `/open/api/v1/resource/note/sharing` | 创建笔记分享链接 | [list.md](references/list.md) | | POST | `/open/api/v1/resource/note/tags/add` | 添加标签 | [tags.md](references/tags.md) | | POST | `/open/api/v1/resource/note/tags/delete` | 删除标签 | [tags.md](references/tags.md) | | GET | `/open/api/v1/resource/image/upload_token` | 获取图片上传凭证 | [save.md](references/save.md) | ### 搜索 | 方法 | 路径 | 说明 | 详细文档 | |------|------|------|----------| | POST | `/open/api/v1/resource/recall` | 全局语义搜索 | [search.md](references/search.md) | | POST | `/open/api/v1/resource/recall/knowledge` | 知识库语义搜索 | [search.md](references/search.md) | ### 知识库 | 方法 | 路径 | 说明 | 详细文档 | |------|------|------|----------| | GET | `/open/api/v1/resource/knowledge/list` | 我的知识库列表 | [knowledge.md](references/knowledge.md) | | GET | `/open/api/v1/resource/knowledge/subscribe/list` | 订阅知识库列表 | [knowledge.md](references/knowledge.md) | | POST | `/open/api/v1/resource/knowledge/create` | 创建知识库 | [knowledge.md](references/knowledge.md) | | GET | `/open/api/v1/resource/knowledge/notes` | 知识库笔记列表 | [knowledge.md](references/knowledge.md) | | POST | `/open/api/v1/resource/knowledge/note/batch-add` | 添加笔记到知识库 | [knowledge.md](references/knowledge.md) | | POST | `/open/api/v1/resource/knowledge/note/remove` | 从知识库移除笔记 | [knowledge.md](references/knowledge.md) | | GET | `/open/api/v1/resource/knowledge/bloggers` | 知识库博主列表 | [knowledge.md](references/knowledge.md) | | GET | `/open/api/v1/resource/knowledge/blogger/contents` | 博主内容列表 | [knowledge.md](references/knowledge.md) |