anki-connect

AnkiConnect

概述

通过 AnkiConnect 本地 HTTP API 与 Anki 可靠交互。使用此技能将用户请求转换为 AnkiConnect 操作，构造 JSON 请求，通过 curl/jq（或等效工具）运行，并安全地解读结果。

前提条件和环境

• 如果 Anki 尚未运行，请启动 Anki，然后等待 AnkiConnect 服务在 http://127.0.0.1:8765（默认值）响应。使用 curl 验证其是否就绪，例如，curl -sS http://127.0.0.1:8765 应返回 Anki-Connect。

安全与确认策略（关键）

关键——无例外

在对笔记或卡片执行任何破坏性或修改操作（添加、更新、删除、重新排程、暂停、取消暂停、更改牌组或更改字段/标签）之前，必须征求用户确认。如果有 AskUserQuestion 工具，请使用；否则通过聊天询问。每个逻辑操作只请求确认一次，即使该操作需要多次 API 调用（例如，搜索 + 更新 + 验证）。按意图和范围归组确认（例如：“更新符合查询 X 的 125 条笔记”）。

默认情况下，以下操作需要确认：

• 笔记：addNote、addNotes、updateNoteFields、updateNoteTags、updateNote、updateNoteModel、deleteNotes、removeEmptyNotes、replaceTags、replaceTagsInAllNotes、clearUnusedTags。
• 卡片：setEaseFactors、setSpecificValueOfCard、suspend、unsuspend、forgetCards、relearnCards、answerCards、setDueDate、changeDeck。
• 会实质性更改卡片/笔记的牌组或模板修改（删除牌组、编辑模板）。即使操作未在上方明确列出，也要征求确认。

API 基础知识

请求格式

每个请求都是包含以下内容的 JSON：

• action：字符串类型的操作名称
• version：API 版本（除非用户另有指定，否则使用 6）
• params：参数对象（可选）

响应格式

每个响应都是包含以下内容的 JSON：

• result：返回值
• error：成功时为 null，否则为描述错误的字符串

使用 result 前，务必检查 error。

权限

• 从非受信任来源交互时，先使用 requestPermission；它是唯一接受任意来源的操作。
• 使用 version 确保兼容性；较旧版本在 version ≤ 4 时，响应中可能省略 error 字段。

curl + jq 模式

优先使用 jq 构建 JSON 和解析响应。请求应明确且结构清晰。

最简请求模板

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 @-

带参数

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 @-

处理 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'

批量执行多个操作

使用 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 @-

链接操作时，将空数组替换为上一个操作的结果；使用命令行时，除非使用脚本语言，否则应拆分为两次调用。

核心工作流指南

1) 验证连接和版本

• 调用 requestPermission（安全）。
• 调用 version 确认 API 级别，并在请求中使用 version: 6。

2) 查找支持的操作

• 使用 apiReflect，并设置 scopes: ["actions"]，列出支持的操作。
• 使用此列表将用户意图映射到操作名称。

3) 将用户请求解析为操作序列

• 确定哪些操作是只读的，哪些具有破坏性。
• 对笔记/卡片执行破坏性或修改操作时，按范围和数量征求一次确认。
• 修改前，优先使用 findNotes/findCards + notesInfo/cardsInfo 进行预览。

4) 执行并验证

• 按顺序执行调用。
• 检查每个响应中的 error。
• 汇总报告结果以及返回的任何 ID。

常见任务示例（面向命令行）

列出牌组

• 操作：deckNames

创建牌组

• 操作：createDeck
• 如果创建牌组属于修改卡片/笔记工作流的一部分，则需要征求确认。

搜索笔记/卡片

• 操作：findNotes、findCards
• 使用 Anki 搜索语法（参见下方“搜索语法速览”）。

预览笔记数据

• 操作：notesInfo（笔记 ID）

添加笔记

• 操作：addNote、addNotes
• 需要确认。
• 执行预检时使用 canAddNotes 或 canAddNotesWithErrorDetail。

更新笔记字段或标签

• 操作：updateNoteFields、updateNoteTags 或组合操作 updateNote
• 需要确认。
• 警告：请勿在浏览器中打开该笔记，否则更新可能无法应用。

删除笔记

• 操作：deleteNotes
• 需要确认。

暂停／取消暂停卡片

• 操作：suspend、unsuspend
• 需要确认。

将卡片移至牌组

• 操作：changeDeck
• 需要确认。

设置到期日期或重新安排

• 操作：setDueDate
• 需要确认。

上传／下载媒体

• 操作：storeMediaFile、retrieveMediaFile、getMediaFilesNames、getMediaDirPath、deleteMediaFile
• 上传时使用 base64（data）、文件路径（path）或 URL（url）。

同步

• 操作：sync

搜索语法速览（适用于 findNotes／findCards）

• 用空格分隔搜索词；默认使用 AND 逻辑。
• 使用 or、括号和 - 表示 NOT 逻辑。
• 使用 deck:Name、tag:tagname、note:ModelName、card:CardName。
• 使用 front:... 或其他字段名来限定字段。
• 使用 re: 进行正则表达式搜索，使用 w: 进行单词边界搜索，使用 nc: 忽略重音符号。
• 使用 is:due、is:new、is:learn、is:review、is:suspended、is:buried 按卡片状态筛选。
• 使用 prop: 搜索间隔或到期日期等属性。
• 根据需要用引号或反斜杠转义特殊字符。

操作目录（用作映射参考）

卡片操作

• getEaseFactors
• setEaseFactors
• setSpecificValueOfCard
• suspend
• unsuspend
• suspended
• areSuspended
• areDue
• getIntervals
• findCards
• cardsToNotes
• cardsModTime
• cardsInfo
• forgetCards
• relearnCards
• answerCards
• setDueDate

牌组操作

• deckNames
• deckNamesAndIds
• getDecks
• createDeck
• changeDeck
• deleteDecks
• getDeckConfig
• saveDeckConfig
• setDeckConfigId
• cloneDeckConfigId
• removeDeckConfigId
• getDeckStats

图形界面操作

• guiBrowse
• guiSelectCard
• guiSelectedNotes
• guiAddCards
• guiEditNote
• guiAddNoteSetData
• guiCurrentCard
• guiStartCardTimer
• guiShowQuestion
• guiShowAnswer
• guiAnswerCard
• guiUndo
• guiDeckOverview
• guiDeckBrowser
• guiDeckReview
• guiImportFile
• guiExitAnki
• guiCheckDatabase
• guiPlayAudio

媒体操作

• storeMediaFile
• retrieveMediaFile
• getMediaFilesNames
• getMediaDirPath
• deleteMediaFile

杂项操作

• requestPermission
• version
• apiReflect
• sync
• getProfiles
• getActiveProfile
• loadProfile
• multi
• exportPackage
• importPackage
• reloadCollection

模型操作

• 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

笔记操作

• addNote
• addNotes
• canAddNotes
• canAddNotesWithErrorDetail
• updateNoteFields
• updateNote
• updateNoteModel
• updateNoteTags
• getNoteTags
• addTags
• removeTags
• getTags
• clearUnusedTags
• replaceTags
• replaceTagsInAllNotes
• findNotes
• notesInfo
• notesModTime
• deleteNotes
• removeEmptyNotes

统计操作

• getNumCardsReviewedToday
• getNumCardsReviewedByDay
• getCollectionStatsHTML
• cardReviews
• getReviewsOfCards
• getLatestReviewID
• insertReviews

注意事项与陷阱

• 在 macOS 上让 Anki 保持前台运行，或禁用 App Nap，以防止 AnkiConnect 暂停。
• 更新笔记时，请确保未在浏览器编辑器中查看该笔记；否则更新可能不会生效。
• importPackage 路径是相对于 Anki 的 collection.media 文件夹，而非客户端。
• deleteDecks 需要设置 cardsToo: true，才能连同卡片一起删除牌组。

资源

此技能无需附带脚本或资源。