wisemind-ai

WiseMindAI 技能

使用此技能通过 HTTP 操作本地 WiseMindAI 应用。

默认设置

• 基础 URL：http://127.0.0.1:38221
• 先尝试默认端口。仅当健康检查失败，或用户明确提到其他端口时，才询问用户是否使用自定义端口。
• 优先使用 /api/v2/*，而非旧版端点。
• 使用 Content-Type: application/json 发送 JSON。
• 除非宿主 Agent 已有更好的内置 HTTP 工具，否则使用 curl。

必需工作流

1. 开始任何操作前，先检查连接。
2. 如果枚举值、路由或负载结构不确定，请获取功能信息。
3. 写入前选择正确的 WiseMindAI 对象类型。
4. 写入、更新或删除前，先搜索或读取。
5. 对文件夹、知识库、卡组和卡片文件夹使用 resolve 端点。
6. 对可能重复写入的网址或文件路径使用 upsert。
7. 除非用户明确要求删除，否则绝不删除。
8. 简要报告结果，说明保存或更改了什么，以及保存到哪里。

标准来源字段

创建或更新知识文档时，始终保留来源元数据：

来源类型	type	fileType	fileExt	fileUrl
用户输入的纯文本	input	input	input	空字符串
网页 URL、书签或网页文章	link	link	link	原始 URL
本地/导入的文件	file 或 upload	检测到的文件类型	实际扩展名	文件路径或 Wise 文件 URL

保存到知识库的网页或 URL 内容必须填写 fileUrl，且必须使用原始 URL。不要将从 URL 派生的知识文档保存为 fileUrl、fileType 或 fileExt 为空；应用会使用这些字段将文档显示为链接。

常见负载注意事项

• 笔记使用 title 和 content。保存 Markdown/纯文本笔记时，除非有意使用不同表示形式，否则将相同正文发送到 content、md 和 text。tags 必须是数组。
• 文件记录使用 name 作为可见标题，使用 filePath 存放 URL 或本地路径。对于链接，始终发送 type:"link" 和 fileType:"link"。对于输入的文本记录，发送 type:"input" 和 fileType:"input"。
• 保存到文档区域的网页应使用 /api/v2/files/save-webpage，并提供 url、title、summary 和 content。
• 知识文档使用 title 作为显示标题，且必须包含 knowledgeBaseId。对于包含来源信息的记录，必须提供 type、fileType、fileExt 和 fileUrl；不要依赖默认值。
• 卡片必须包含数值型 deckId、数值型 folderId 和非空 content。批量创建时，cards 中的每个项目都必须包含 content；如果提供 tags，则应为数组。
• Patch 请求应仅包含有意更改的字段。除非用户要求清除来源字段，否则不要在 Patch 请求中发送空白来源字段。

健康检查

先运行此命令：

curl -s http://127.0.0.1:38221/api/health

预期结构：

{"ok": true, "service": "wisemindai-local-api", "version": "2.0.0"}

如果失败：

• 请用户启动 WiseMindAI 并启用本地 API。
• 如果用户使用自定义端口，请用该端口重试。
• 服务可访问之前，不要继续执行写入操作。

功能发现

需要了解当前支持的分组、端点或枚举值时使用此功能：

curl -s http://127.0.0.1:38221/api/capabilities

此端点会提供：

• 支持的分组
• 端点列表
• fileTypeOptions
• fileCategoryOptions
• knowledgeTypeOptions
• knowledgeStatusOptions

如果可选值不确定，优先使用运行时发现，而不是硬编码。

选择合适的目标

用户意图	首选目标
随手想法、会议记录、草稿、日记、普通记笔记	notes
保存本地文件、URL、书签、网页或自由格式的文档记录	files
将内容放入命名知识库，以便长期整理	knowledge-documents
创建学习卡片或间隔重复材料	cards

默认选择：

• 没有更明确结构要求的纯文本：保存为笔记。
• URL 或外部资源：保存为文件记录。
• 明确用于知识库的内容：保存为知识文档。
• 测验、记忆、抽认卡或卡片请求：创建卡片。

核心端点

通用

• GET /api/health
• GET /api/capabilities
• GET /api/search

笔记

• GET /api/v2/notes
• GET /api/v2/notes/:id
• POST /api/v2/notes
• PATCH /api/v2/notes/:id
• DELETE /api/v2/notes/:id
• GET /api/v2/note-folders
• POST /api/v2/note-folders
• POST /api/v2/note-folders/resolve

文件、链接和网页

• GET /api/v2/files
• GET /api/v2/files/:id
• POST /api/v2/files
• PATCH /api/v2/files/:id
• DELETE /api/v2/files/:id
• POST /api/v2/files/upsert
• POST /api/v2/files/save-webpage
• GET /api/v2/file-folders
• POST /api/v2/file-folders
• POST /api/v2/file-folders/resolve

知识库

• GET /api/v2/knowledge-bases
• POST /api/v2/knowledge-bases
• PATCH /api/v2/knowledge-bases/:id
• POST /api/v2/knowledge-bases/resolve
• GET /api/v2/knowledge-documents
• GET /api/v2/knowledge-documents/:id
• POST /api/v2/knowledge-documents
• PATCH /api/v2/knowledge-documents/:id
• DELETE /api/v2/knowledge-documents/:id

卡片

• GET /api/v2/card-decks
• POST /api/v2/card-decks
• PATCH /api/v2/card-decks/:id
• POST /api/v2/card-decks/resolve
• GET /api/v2/card-folders
• POST /api/v2/card-folders
• PATCH /api/v2/card-folders/:id
• POST /api/v2/card-folders/resolve
• GET /api/v2/cards
• GET /api/v2/cards/:id
• POST /api/v2/cards
• PATCH /api/v2/cards/:id
• DELETE /api/v2/cards/:id
• POST /api/v2/cards/batch

操作规则

写入前先搜索

创建新内容前，优先使用：

curl -s "http://127.0.0.1:38221/api/search?q=keyword&limit=10"

使用此方法可避免重复创建笔记、文档、知识文档或卡片。

更新前先读取

更新时：

1. 列出或搜索候选项。
2. 必要时读取当前项目。
3. 仅修改需要变更的字段。

解析容器，而不是猜测 ID

用户指定目标但未提供 ID 时，先使用解析端点：

• /api/v2/note-folders/resolve
• /api/v2/file-folders/resolve
• /api/v2/knowledge-bases/resolve
• /api/v2/card-decks/resolve
• /api/v2/card-folders/resolve

对于便于人类理解的名称，默认采用此行为。

对 URL 和路径优先使用幂等写入

如果同一 URL 或文件路径可能被多次保存，优先使用：

curl -s -X POST "http://127.0.0.1:38221/api/v2/files/upsert" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example","filePath":"https://example.com","type":"link","fileType":"link"}'

有实际网页内容时使用 save-webpage；主要需求是按 URL 或路径去重时使用 upsert。

常见操作指南

保存笔记

创建笔记：

curl -s -X POST "http://127.0.0.1:38221/api/v2/notes" \
  -H "Content-Type: application/json" \
  -d '{"title":"Note title","content":"Body text","md":"Body text","text":"Body text","tags":["tag1","tag2"]}'

如果用户提供了文件夹名称，先解析该文件夹，再传入 from_folder。

保存自由格式文本或本地文件记录

对于应作为文档记录而非笔记保存的文本：

curl -s -X POST "http://127.0.0.1:38221/api/v2/files" \
  -H "Content-Type: application/json" \
  -d '{"name":"Document title","type":"input","fileType":"input","filePath":"","content":"Text content","summary":"Short summary"}'

对于 URL，使用链接元数据，并将原始 URL 保存在 filePath 中：

curl -s -X POST "http://127.0.0.1:38221/api/v2/files/upsert" \
  -H "Content-Type: application/json" \
  -d '{"name":"Article title","filePath":"https://example.com/article","type":"link","fileType":"link","summary":"Short summary","content":"Optional captured content"}'

对于本地文件，选择合适的 type 扩展名和 fileType 类别。如果不确定，请获取 /api/capabilities。

保存网页

如果用户只提供了 URL：

1. 使用宿主 Agent 提供的网页、浏览器或抓取功能，获取页面标题和主要内容。
2. 如果能获取完整内容，则使用 save-webpage 保存。
3. 如果无法获取完整内容，则可以使用 upsert 保存链接记录，或请用户提供要保存的内容。
4. 如果用户明确要求将 URL 保存到知识库，则改用 /api/v2/knowledge-documents，并遵循链接型知识文档负载格式。

保存包含内容的网页：

curl -s -X POST "http://127.0.0.1:38221/api/v2/files/save-webpage" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","title":"Article title","summary":"Short summary","content":"Main article content"}'

摘要指南：

• 除非用户另有要求，否则使用与用户相同的语言。
• 摘要应简洁实用。
• 优先采用一段简短摘要和几个要点。

将内容导入知识库

先解析知识库：

curl -s -X POST "http://127.0.0.1:38221/api/v2/knowledge-bases/resolve" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI Research"}'

然后创建知识文档：

curl -s -X POST "http://127.0.0.1:38221/api/v2/knowledge-documents" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId":1,"title":"RAG Notes","content":"Document body","summary":"Short summary","type":"input","fileType":"input","fileExt":"input","fileUrl":""}'

如果来源是 URL 或网页，请在 fileUrl 中保留原始 URL，并将所有来源类型字段标记为 link：

curl -s -X POST "http://127.0.0.1:38221/api/v2/knowledge-documents" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId":1,"title":"Article title","content":"Main article content","summary":"Short summary","type":"link","fileType":"link","fileExt":"link","fileUrl":"https://example.com/article"}'

对于“将这篇文章的 URL 放入知识库 X”之类的请求，请尽可能抓取标题和内容，然后使用上述链接负载创建知识文档。如果无法抓取内容，仍须保留 URL 字段，并将 content 和 summary 设为可用的标题、描述或简短说明。

如果用户要求更新现有知识文档，请先搜索或列出文档，然后再修改匹配的项目。

创建卡片

先解析卡组，再解析文件夹，然后创建卡片。

单张卡片：

curl -s -X POST "http://127.0.0.1:38221/api/v2/cards" \
  -H "Content-Type: application/json" \
  -d '{"deckId":1,"folderId":1,"content":"Card content"}'

批量卡片：

curl -s -X POST "http://127.0.0.1:38221/api/v2/cards/batch" \
  -H "Content-Type: application/json" \
  -d '{"deckId":1,"folderId":1,"cards":[{"content":"Card 1","tags":["tag1"]},{"content":"Card 2","tags":["tag2"]}]}'

卡片编写指南：

• 每张卡片只聚焦一个想法。
• 如果用户明确要求创建多张卡片，则使用批量创建。
• 如果用户只要求少量卡片，不要盲目生成大批卡片。

更新现有内容

当用户说“更新”“移动”“重命名”“更改摘要”或类似内容时：

1. 通过搜索、列出内容或明确的 ID 查找目标。
2. 如果有多个可能的匹配项，请简短地提出澄清问题。
3. 对正确的端点使用 PATCH。
4. 准确告知用户更改了哪些内容。

删除现有内容

删除操作具有破坏性。只有在以下情况下才继续：

• 用户明确要求删除；并且
• 目标明确无误。

如果目标不明确，请先询问，再删除任何内容。

结果报告

操作成功后，用一条简短消息报告：

• 创建、更新或删除了什么
• 保存位置
• 仅在有帮助时提供关键标识符

示例：

• “已将文章作为网页记录保存到 WiseMindAI 的 Reading Queue 中。”
• “已在卡组 AI Basics / 文件夹 RAG 中创建 8 张卡片。”
• “已更新 Product Notes 中现有知识文档的摘要。”

旧版端点

旧版端点仍可用于兼容，但新工作应使用 /api/v2/*。