需要通过 AnkiConnect 本地 HTTP API…

用户要求与 Anki 交互（读取或修改牌组、笔记、卡片、模型、媒体、同步）时，通过 AnkiConnect 安全地翻译请求为 HTTP JSON 调用并解析结果

适用场景

解决思路

1. 如果 Anki 未运行，启动 Anki，然后等待 AnkiConnect 服务器在默认地址 http://127.0.0.1:8765 响应；用 curl 验证就绪，例如 curl -sS http://127.0.0.1:8765 应返回 Anki-Connect。
2. 在任何对 notes 或 cards 的破坏性或修改性操作（添加、更新、删除、重新调度、暂停、取消暂停、更改牌组、更改字段/标签）之前，向用户请求确认。
3. 如果可用，使用 AskUserQuestion 工具请求确认；否则通过聊天询问。
4. 每个逻辑操作只请求一次确认，即使需要多个 API 调用（例如搜索 + 更新 + 验证）。
5. 按意图和范围分组确认，例如“更新匹配查询 X 的 125 条笔记”。
6. 默认将以下 Notes 操作视为需要确认：addNote, addNotes, updateNoteFields, updateNoteTags, updateNote, updateNoteModel, deleteNotes, removeEmptyNotes, replaceTags, replaceTagsInAllNotes, clearUnusedTags。
7. 默认将以下 Cards 操作视为需要确认：setEaseFactors, setSpecificValueOfCard, suspend, unsuspend, forgetCards, relearnCards, answerCards, setDueDate, changeDeck。
8. 对实质性更改卡片/笔记的牌组或模型修改（例如牌组删除、模型编辑）也要询问，即使操作未明确列在上面。
9. 请求格式：每个请求是 JSON，包含 action（字符串动作名）、version（API 版本，除非用户指定否则用 6）、params（参数对象，可选）。
10. 响应格式：每个响应是 JSON，包含 result（返回值）和 error（成功时为 null，或描述错误的字符串）。
11. 始终在使用 result 之前检查 error。
12. 从非可信来源交互时先使用 requestPermission；它是唯一接受任意来源的 action。
13. 使用 version 确保兼容性；旧版本在 version ≤ 4 时可能省略响应中的 error 字段。
14. 优先使用 jq 构建 JSON 和解析响应；保持请求显式且结构化。
15. 最小请求模板：jq -n --arg action "deckNames" --argjson version 6 '{action:$action, version:$version}' | curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
16. 带 params 的模板：jq -n --arg action "findNotes" --argjson version 6 --arg query "deck:French tag:verbs" '{action:$action, version:$version, params:{query:$query}}' | curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
17. 处理 result/error：curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @- | jq -e 'if .error then halt_error(1) else .result end'
18. 批量多个动作：使用 multi 减少往返，并在修改数据时归组到一个确认下。
19. multi 示例：jq -n --argjson version 6 --arg query "deck:French" '{action:"multi", version:$version, params:{actions:[{action:"findNotes", params:{query:$query}},{action:"notesInfo", params:{notes:[]}}]}}' | curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-
20. 链式调用时，用前一个 action 的结果替换空数组；在 CLI 用法中，除非使用脚本语言，否则拆成两次调用。
21. 核心工作流 1：验证连通性和版本——调用 requestPermission（安全）；调用 version 确认 API 级别，并在请求中使用 version:6。
22. 核心工作流 2：发现支持的动作——使用 apiReflect 带 scopes:["actions"] 列出支持的动作；使用该列表将用户意图映射到 action 名称。
23. 核心工作流 3：将用户请求解析为动作序列——识别只读操作与破坏性操作；对 notes/cards 的破坏性/修改性操作，请求一次确认，附范围和数量；在修改前，优先使用 findNotes/findCards + notesInfo/cardsInfo 进行预览。
24. 核心工作流 4：执行并验证——按顺序执行调用；检查每个响应的 error；报告汇总结果和任何返回的 ID。
25. 列出牌组：使用 action deckNames。
26. 创建牌组：使用 action createDeck；如果创建牌组是卡片/笔记修改工作流的一部分，需要确认。
27. 搜索笔记/卡片：使用 findNotes, findCards；使用 Anki 搜索语法（见搜索语法快速说明）。
28. 预览笔记数据：使用 notesInfo（传 note IDs）。
29. 添加笔记：使用 addNote, addNotes；需要确认；使用 canAddNotes 或 canAddNotesWithErrorDetail 进行预检。
30. 更新笔记字段或标签：使用 updateNoteFields, updateNoteTags，或组合的 updateNote；需要确认；警告：不要让笔记在浏览器中打开，更新可能无法应用。
31. 删除笔记：使用 deleteNotes；需要确认。
32. 暂停/取消暂停卡片：使用 suspend, unsuspend；需要确认。
33. 移动卡片到牌组：使用 changeDeck；需要确认。
34. 设置到期日或重新调度：使用 setDueDate；需要确认。
35. 媒体上传/下载：使用 storeMediaFile, retrieveMediaFile, getMediaFilesNames, getMediaDirPath, deleteMediaFile；上传使用 base64(data)、文件路径(path) 或 URL(url)。
36. 同步：使用 sync。
37. 搜索语法：空格分隔词，默认 AND。
38. 搜索语法：使用 or、括号和 - 表示 NOT 逻辑。
39. 搜索语法：使用 deck:Name, tag:tagname, note:ModelName, card:CardName。
40. 搜索语法：使用 front:... 或其他字段名按字段限制。
41. 搜索语法：使用 re: 表示正则，w: 表示词边界搜索，nc: 忽略口音。
42. 搜索语法：使用 is:due, is:new, is:learn, is:review, is:suspended, is:buried 过滤卡片状态。
43. 搜索语法：使用 prop: 搜索属性，如 interval 或 due date。
44. 搜索语法：按需用引号或反斜杠转义特殊字符。
45. 动作目录映射参考——Card Actions：getEaseFactors, setEaseFactors, setSpecificValueOfCard, suspend, unsuspend, suspended, areSuspended, areDue, getIntervals, findCards, cardsToNotes, cardsModTime, cardsInfo, forgetCards, relearnCards, answerCards, setDueDate。
46. 动作目录映射参考——Deck Actions：deckNames, deckNamesAndIds, getDecks, createDeck, changeDeck, deleteDecks, getDeckConfig, saveDeckConfig, setDeckConfigId, cloneDeckConfigId, removeDeckConfigId, getDeckStats。
47. 动作目录映射参考——Graphical Actions：guiBrowse, guiSelectCard, guiSelectedNotes, guiAddCards, guiEditNote, guiAddNoteSetData, guiCurrentCard, guiStartCardTimer, guiShowQuestion, guiShowAnswer, guiAnswerCard, guiUndo, guiDeckOverview, guiDeckBrowser, guiDeckReview, guiImportFile, guiExitAnki, guiCheckDatabase, guiPlayAudio。
48. 动作目录映射参考——Media Actions：storeMediaFile, retrieveMediaFile, getMediaFilesNames, getMediaDirPath, deleteMediaFile。
49. 动作目录映射参考——Miscellaneous Actions：requestPermission, version, apiReflect, sync, getProfiles, getActiveProfile, loadProfile, multi, exportPackage, importPackage, reloadCollection。
50. 动作目录映射参考——Model Actions：modelNames, modelNamesAndIds, findModelsById, findModelsByName, modelFieldNames, modelFieldDescriptions, modelFieldFonts, modelFieldsOnTemplates, createModel, modelTemplates, modelStyling, updateModelTemplates, updateModelStyling, findAndReplaceInModels, modelTemplateRename, modelTemplateReposition, modelTemplateAdd, modelTemplateRemove, modelFieldRename, modelFieldReposition, modelFieldAdd, modelFieldRemove, modelFieldSetFont, modelFieldSetFontSize, modelFieldSetDescription。
51. 动作目录映射参考——Note Actions：addNote, addNotes, canAddNotes, canAddNotesWithErrorDetail, updateNoteFields, updateNote, updateNoteModel, updateNoteTags, getNoteTags, addTags, removeTags, getTags, clearUnusedTags, replaceTags, replaceTagsInAllNotes, findNotes, notesInfo, notesModTime, deleteNotes, removeEmptyNotes。
52. 动作目录映射参考——Statistic Actions：getNumCardsReviewedToday, getNumCardsReviewedByDay, getCollectionStatsHTML, cardReviews, getReviewsOfCards, getLatestReviewID, insertReviews。
53. 注意事项：在 macOS 上保持 Anki 在前台或禁用 App Nap，以防止 AnkiConnect 暂停。
54. 注意事项：更新笔记时，确保它不在浏览器编辑器中查看；更新可能不应用。
55. 注意事项：importPackage 路径相对于 Anki collection.media 文件夹，而不是客户端。
56. 注意事项：deleteDecks 需要 cardsToo: true 才能删除卡片连同牌组。
57. 资源：不需要为此技能捆绑脚本或资产。

适用边界 · 注意事项

• Anki 未安装、无法启动，或 AnkiConnect 插件未启用/不可用。
• 无法访问 http://127.0.0.1:8765，或需要操作远程/非本地 Anki 实例。
• 不允许请求用户确认破坏性/修改性操作，或需要完全自动修改笔记/卡片。