AGENT SKILL

notes

暂无简介

License 许可
MIT
最近更新
2026-11-10
Stars
★ 1
Forks
0

02 资源文件 1

03 SKILL.md 正文

Notes (笔记)

Prerequisites: see root ../SKILL.md for setup, credentials, and ima_api() helper.

API base path: openapi/note/v1

通过 IMA OpenAPI 管理用户个人笔记,支持读取(搜索、列表、获取内容)和写入(新建、追加)。

完整的数据结构和接口参数详见 references/api.md。

隐私规则: 笔记内容属于用户隐私,在群聊场景中只展示标题和摘要,禁止展示笔记正文。

接口决策表

用户意图 调用接口 关键参数
搜索/查找笔记 search_note_book query_info(QueryInfo 对象)
查看笔记本列表 list_note_folder_by_cursor cursor(必填,首页传"0") + limit(必填)
浏览某笔记本里的笔记,当用户表述"最新"、"最近"之类的通用限定,没有指明笔记本时,都应该直接在全部笔记里去拉 list_note_by_folder_id folder_id(选填,空为全部笔记本) + cursor(必填,首次传"") + limit(必填)
读取笔记正文 get_doc_content doc_id + target_content_format(必填,推荐0纯文本)
新建一篇笔记(用户明确说"新建/创建笔记"时走此接口) import_doc content + content_format(必填,固定1) + 可选 folder_id
往已有笔记追加内容(⚠️ 敏感操作:用户必须明确指定目标笔记,否则先确认再操作) append_doc doc_id + content + content_format(必填,固定1)

⚠️ 新建 vs. 追加 — 行为规则

新建笔记(import_doc) 和 追加内容到已有笔记(append_doc) 是两个完全不同的操作,务必正确区分:

明确走新建的信号词

用户说以下任一表述时,直接调用 import_doc 创建新笔记:

  • "新建笔记"、"创建笔记"、"写一篇笔记"
  • "新建一篇笔记记录这些内容"

明确走追加的信号词

用户说以下任一表述时,调用 append_doc 追加到已有笔记(但仍需确认目标笔记,见下方规则):

  • "把这段话追加到《XX》笔记里"
  • "在那篇笔记末尾加上这段内容"

模糊场景 — 必须先询问用户

以下表述既可能是新建、也可能是追加,agent 不得自行假设,必须先向用户确认:

  • "帮我记一下"、"记录一下"、"保存为笔记"、"存成笔记"
  • "把这段内容记到笔记里"
  • "添加到笔记里"
  • 任何其他未明确表达"新建"或"追加"意图的表述

询问示例:

"您是想创建一篇新笔记,还是追加到某篇已有笔记?"

追加到已有笔记是敏感操作

append_doc 会不可撤销地修改用户的现有笔记,因此必须谨慎处理:

  1. 用户明确指定了目标笔记 — 可以直接追加。例如:

    • "把这段话追加到《会议纪要》笔记里"
    • "在那篇笔记末尾加上这段内容"(上下文中已有明确的笔记对象)
  2. 用户没有明确指定目标笔记 — 必须先向用户确认,不要自行猜测。例如:

    • 用户说"添加到笔记里" → 询问:"您想追加到哪篇已有笔记?请提供笔记标题或让我帮您搜索。"
    • 用户说"把这个加到之前那篇笔记" → 如果上下文中有多篇笔记或不确定是哪篇 → 列出候选笔记让用户选择

原则:不确定时,先问。宁可多问一句,也不要误改用户的已有笔记或自作主张创建新笔记。

🖼️ 本地图片不支持

import_doc 和 append_doc 的 content 字段仅支持纯文本/Markdown,不支持本地图片。

写入笔记内容前,必须检查并处理图片引用:

  1. 过滤本地图片 — 如果用户提供的内容中包含本地图片路径(如 ![](file:///...), ![](/Users/...), ![](C:\...) 等),移除这些图片引用,不要将其写入笔记。
  2. 告知用户 — 移除后主动提醒用户:

    "笔记接口暂不支持上传本地图片,以下图片已被过滤:xxx.png、yyy.jpg。您可以先将图片上传到网络,再用网络链接插入笔记。"

  3. 保留网络图片 — 以 http:// 或 https:// 开头的图片链接可以正常保留。

常用工作流

查找并阅读笔记

先搜索获取 docid,再用 get_doc_content 读取正文:

# 1. 按标题搜索
ima_api "openapi/note/v1/search_note_book" '{"search_type": 0, "query_info": {"title": "会议纪要"}, "start": 0, "end": 20}'
# 从返回的 docs[].doc.basic_info.docid 中取目标笔记 ID

# 2. 读取正文(纯文本格式,Markdown 格式目前不支持)
ima_api "openapi/note/v1/get_doc_content" '{"doc_id": "目标docid", "target_content_format": 0}'

浏览笔记本里的笔记

先拉笔记本列表获取 folder_id,再拉该笔记本下的笔记:

# 1. 列出笔记本(首页 cursor 传 "0")
ima_api "openapi/note/v1/list_note_folder_by_cursor" '{"cursor": "0", "limit": 20}'

# 2. 拉取指定笔记本的笔记(首页 cursor 传 "")
ima_api "openapi/note/v1/list_note_by_folder_id" '{"folder_id": "user_list_xxx", "cursor": "", "limit": 20}'

新建笔记

# 新建到默认位置
ima_api "openapi/note/v1/import_doc" '{"content_format": 1, "content": "# 标题\n\n正文内容"}'

# 新建到指定笔记本
ima_api "openapi/note/v1/import_doc" '{"content_format": 1, "content": "# 标题\n\n正文内容", "folder_id": "笔记本ID"}'
# 返回 doc_id,后续可用于 append_doc

追加内容到已有笔记

ima_api "openapi/note/v1/append_doc" '{"doc_id": "笔记ID", "content_format": 1, "content": "\n## 补充内容\n\n追加的文本"}'

按正文搜索

ima_api "openapi/note/v1/search_note_book" '{"search_type": 1, "query_info": {"content": "项目排期"}, "start": 0, "end": 20}'

核心响应字段

搜索结果(SearchedDoc):笔记信息路径为 doc.basic_info(DocBasic),关键字段:docid、title、summary、folder_id、folder_name、create_time(Unix 毫秒)、modify_time、status。额外包含 highlight_info(高亮匹配,key 为 doc_title,value 含 <em>高亮词</em>)。

笔记本条目(NoteBookFolder):信息路径为 folder.basic_info(NoteBookFolderBasic),关键字段:folder_id、name、note_number、create_time、modify_time、folder_type(0=用户自建,1=全部笔记,2=未分类)、status。

笔记列表条目(NoteBookInfo):信息路径为 basic_info.basic_info(DocBasicInfo → DocBasic),关键字段:docid、title、summary、folder_id、folder_name、create_time、modify_time、status。

写入结果(import_doc/append_doc):返回 doc_id(新建或目标笔记的唯一 ID)。

完整字段定义见 references/api.md。

分页

  • 游标分页 — 笔记本列表(list_note_folder_by_cursor):首次 cursor: "0",后续用 next_cursor,is_end=true 时停止。
  • 游标分页 — 笔记列表(list_note_by_folder_id):首次 cursor: "",后续用 next_cursor,is_end=true 时停止。
  • 偏移量分页(search_note_book):首次 start: 0, end: 20,翻页时递增,is_end=true 时停止。

枚举值

  • content_format: 0=纯文本,1=Markdown,2=JSON。写入(import_doc/append_doc)目前仅支持 1(Markdown)。读取(get_doc_content)推荐 0(纯文本),Markdown 格式不支持。
  • search_type: 0=标题检索(默认),1=正文检索
  • sort_type: 0=更新时间(默认),1=创建时间,2=标题,3=大小(仅 search_note_book 使用)
  • folder_type: 0=用户自建,1=全部笔记(根目录),2=未分类

注意事项

  • folder_id 不可为 "0",根目录 ID 格式为 user_list_{userid}(从 folder_type=1 的笔记本条目获取)
  • 笔记内容有大小上限,超过时返回 100009,可拆分为多次 append_doc 写入
  • 写入内容不支持本地图片,写入前必须过滤本地图片路径并告知用户(详见"🖼️ 本地图片不支持"规则)
  • 展示笔记列表时只展示标题、摘要和修改时间,不要主动展示正文
  • 时间字段是 Unix 毫秒时间戳,展示时转为可读格式
  • 返回数据为嵌套结构:搜索结果取 docs[].doc.basic_info.docid,笔记本取 note_book_folders[].folder.basic_info.folder_id,笔记列表取 note_book_list[].basic_info.basic_info.docid,注意按层级解析

错误处理

错误码 含义 建议处理
100001 参数错误 检查请求参数格式和必填字段
100002 无效 ID 检查凭证配置
100003 服务器内部错误 等待后重试
100004 size 不合法 / 空间不够 检查参数范围
100005 无权限 确认操作的是用户自己的笔记
100006 笔记已删除 告知用户该笔记不存在
100008 版本冲突 重新获取内容后再操作
100009 超过大小限制 拆分为多次 append_doc 写入
310001 笔记本不存在 检查 folder_id 是否正确
20002 apiKey超过最大限频
20004 apikey 鉴权失败 检查凭证配置是否正确

04 同仓库更多 Skills

YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

vercel-sandbox

Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include "Vercel Sandbox browser", "microVM Chrome", "agent-browser in sandbox", "browser automation on Vercel", or any task requiring Chrome in a Vercel Sandbox.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

slack

Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include "check my Slack", "what channels have unreads", "send a message to", "search Slack for", "extract from Slack", "find who said", or any task requiring programmatic Slack interaction.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

electron

Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include "automate Slack app", "control VS Code", "interact with Discord app", "test this Electron app", "connect to desktop app", or any task requiring automation of a native Electron application.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

dogfood

Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.

★ 1
YYC-Cube
YYC-Cube/YYC3-Knowledge-Base

shadcn

Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.

★ 1