anki-connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AnkiConnect

Overview

概述

Enable reliable interaction with Anki through the AnkiConnect local HTTP API. Use this skill to translate user requests into AnkiConnect actions, craft JSON requests, run them via curl/jq (or equivalent tools), and interpret results safely.

通过AnkiConnect本地HTTP API实现与Anki的可靠交互。使用此Skill将用户请求转换为AnkiConnect操作，编写JSON请求，通过curl/jq（或等效工具）执行，并安全解析结果。

Preconditions and Environment

前置条件与环境

If Anki is not running, launch Anki, then wait until the AnkiConnect server responds at
```
http://127.0.0.1:8765
```
(default). Verify readiness using curl, e.g.
```
curl -sS http://127.0.0.1:8765
```
should return
```
Anki-Connect
```
.

如果Anki未运行，请启动Anki，然后等待AnkiConnect服务器在默认地址
```
http://127.0.0.1:8765
```
响应。可通过curl验证就绪状态，例如执行
```
curl -sS http://127.0.0.1:8765
```
应返回
```
Anki-Connect
```
。

Safety and Confirmation Policy (Critical)

安全与确认策略（关键）

CRITICAL — NO EXCEPTIONS

Before any destructive or modifying operation on notes or cards (adding, updating, deleting, rescheduling, suspending, unsuspending, changing deck, or changing fields/tags), request confirmation from the user. Use the AskUserQuestion tool if available; otherwise ask via chat. Only request confirmation once per logical operation, even if it requires multiple API calls (e.g., search + update + verify). Group confirmation by intent and scope (e.g., “Update 125 notes matching query X”).

Treat the following as confirmation-required by default:

Notes:

addNote

addNotes

updateNoteFields

updateNoteTags

updateNote

updateNoteModel

deleteNotes

removeEmptyNotes

replaceTags

replaceTagsInAllNotes

clearUnusedTags

Cards:

setEaseFactors

setSpecificValueOfCard

suspend

unsuspend

forgetCards

relearnCards

answerCards

setDueDate

changeDeck

Deck or model modifications that materially change cards/notes (deck deletion, model edits). Ask even if the action is not explicitly listed above.

关键要求 — 无例外

在对笔记或卡片执行任何破坏性或修改操作（添加、更新、删除、重新安排、暂停、恢复、更改卡组或修改字段/标签）之前，必须请求用户确认。如果有

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 Fundamentals

API基础

Request Format

请求格式

Every request is JSON with:

```
action
```
: string action name
```
version
```
: API version (use
```
6
```
unless user specifies otherwise)
```
params
```
: object of parameters (optional)

每个请求都是包含以下字段的JSON：

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

Response Format

响应格式

Every response is JSON with:

```
result
```
: return value
```
error
```
:
```
null
```
on success or a string describing the error

Always check

error

before using

result

每个响应都是包含以下字段的JSON：

```
result
```
：返回值
```
error
```
：成功时为
```
null
```
，失败时为描述错误的字符串

使用

result

前务必检查

error

字段。

Permissions

权限

Use
```
requestPermission
```
first when interacting from a non-trusted origin; it is the only action that accepts any origin.
Use
```
version
```
to ensure compatibility; older versions may omit the
```
error
```
field in responses when
```
version
```
≤ 4.

从未受信任源交互时，首先调用
```
requestPermission
```
；这是唯一接受任何源的操作。
使用
```
version
```
确保兼容性；当
```
version ≤ 4
```
时，旧版本响应可能省略
```
error
```
字段。

curl + jq Patterns

curl + jq 模式

Prefer

jq

to build JSON and parse responses. Keep requests explicit and structured.

优先使用

jq

构建JSON并解析响应。保持请求明确且结构化。

Minimal request template

最小请求模板

bash

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

bash

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

With params

带参数的请求

bash

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

bash

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

Handling result/error

处理结果/错误

bash

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'

bash

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'

Batching multiple actions

批量执行多个操作

Use

multi

to reduce round-trips and to group actions under a single confirmation when modifying data.

bash

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

Replace the empty array with the result of the previous action when chaining; in CLI usage, split into two calls unless using a scripting language.

使用

multi

减少往返次数，并在修改数据时将操作分组到单个确认下。

bash

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

链式调用时，将空数组替换为前一个操作的结果；在CLI使用中，除非使用脚本语言，否则拆分为两次调用。

Core Workflow Guidance

核心工作流指南

1) Verify connectivity and version

1) 验证连接性与版本

Call
```
requestPermission
```
(safe).
Call
```
version
```
to confirm the API level and use
```
version: 6
```
in requests.

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

2) Discover supported actions

2) 发现支持的操作

Use
```
apiReflect
```
with
```
scopes: ["actions"]
```
to list supported actions.
Use this list to map user intent to action names.

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

3) Resolve user request into action sequence

3) 将用户请求转换为操作序列

Identify read-only vs destructive operations.
For destructive/modifying operations on notes/cards, request confirmation once with the scope and count.
Prefer
```
findNotes
```
/
```
findCards
```
+
```
notesInfo
```
/
```
cardsInfo
```
for previews before modification.

区分只读操作与破坏性操作。
对笔记/卡片的破坏性/修改操作，按范围和数量请求一次确认。
修改前优先使用
```
findNotes
```
/
```
findCards
```
+
```
notesInfo
```
/
```
cardsInfo
```
进行预览。

4) Execute and validate

4) 执行与验证

Execute the call(s) in order.
Check
```
error
```
for each response.
Report summarized results and any IDs returned.

按顺序执行调用。
检查每个响应的
```
error
```
字段。
报告汇总结果及返回的所有ID。

Common Task Recipes (CLI-Oriented)

常见任务示例（面向CLI）

List decks

列出卡组

Action:
```
deckNames
```

操作：
```
deckNames
```

Create deck

创建卡组

Action:
```
createDeck
```
Confirmation required if the deck is being created as part of a card/note modification workflow.

操作：
```
createDeck
```
如果创建卡组是卡片/笔记修改工作流的一部分，则需要确认。

Search notes / cards

搜索笔记/卡片

Actions:
```
findNotes
```
,
```
findCards
```
Use Anki search syntax (see “Search Syntax Quick Notes” below).

操作：
```
findNotes
```
,
```
findCards
```
使用Anki搜索语法（见下方“搜索语法快速说明”）。

Preview note data

预览笔记数据

Action:
```
notesInfo
```
(note IDs)

操作：
```
notesInfo
```
（需提供笔记ID）

Add notes

添加笔记

Actions:
```
addNote
```
,
```
addNotes
```
Confirmation required.
Use
```
canAddNotes
```
or
```
canAddNotesWithErrorDetail
```
for preflight checks.

操作：
```
addNote
```
,
```
addNotes
```
需要确认。
使用
```
canAddNotes
```
或
```
canAddNotesWithErrorDetail
```
进行预检查。

Update note fields or tags

更新笔记字段或标签

Actions:

updateNoteFields

updateNoteTags

, or combined

updateNote

Confirmation required.
Warning: Do not have the note open in the browser; updates may fail to apply.

操作：

updateNoteFields

updateNoteTags

，或组合操作

updateNote

需要确认。
警告：请勿在浏览器中打开该笔记；否则更新可能无法生效。

Delete notes

删除笔记

Action:
```
deleteNotes
```
Confirmation required.

操作：
```
deleteNotes
```
需要确认。

Suspend/unsuspend cards

暂停/恢复卡片

Actions:
```
suspend
```
,
```
unsuspend
```
Confirmation required.

操作：
```
suspend
```
,
```
unsuspend
```
需要确认。

Move cards to a deck

将卡片移动到卡组

Action:
```
changeDeck
```
Confirmation required.

操作：
```
changeDeck
```
需要确认。

Set due date or reschedule

设置到期日期或重新安排

Action:
```
setDueDate
```
Confirmation required.

操作：
```
setDueDate
```
需要确认。

Media upload/download

媒体上传/下载

Actions:

storeMediaFile

retrieveMediaFile

getMediaFilesNames

getMediaDirPath

deleteMediaFile

Use base64 (
```
data
```
), file path (
```
path
```
), or URL (
```
url
```
) for upload.

操作：

storeMediaFile

retrieveMediaFile

getMediaFilesNames

getMediaDirPath

deleteMediaFile

上传时可使用base64（
```
data
```
）、文件路径（
```
path
```
）或URL（
```
url
```
）。

Sync

同步

Action:
```
sync
```

操作：
```
sync
```

Search Syntax Quick Notes (for

findNotes

findCards

)

搜索语法快速说明（适用于

findNotes

findCards

）

Separate terms by spaces; terms are ANDed by default.
Use
```
or
```
, parentheses, and
```
-
```
for NOT logic.

Use

deck:Name

tag:tagname

note:ModelName

card:CardName

Use
```
front:...
```
or other field names to limit by field.
Use
```
re:
```
for regex,
```
w:
```
for word-boundary searches,
```
nc:
```
to ignore accents.

Use

is:due

is:new

is:learn

is:review

is:suspended

is:buried

to filter card states.

Use
```
prop:
```
searches for properties like interval or due date.
Escape special characters with quotes or backslashes as needed.

用空格分隔术语；默认情况下术语为逻辑与关系。
使用
```
or
```
、括号和
```
-
```
表示逻辑非。

使用

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:
```
搜索属性，如间隔或到期日期。
必要时用引号或反斜杠转义特殊字符。

Action Catalog (Use as a mapping reference)

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

Card Actions

卡片操作

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

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

Deck Actions

卡组操作

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

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

Graphical Actions

图形界面操作

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

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

Media Actions

媒体操作

```
storeMediaFile
```
```
retrieveMediaFile
```
```
getMediaFilesNames
```
```
getMediaDirPath
```
```
deleteMediaFile
```

```
storeMediaFile
```
```
retrieveMediaFile
```
```
getMediaFilesNames
```
```
getMediaDirPath
```
```
deleteMediaFile
```

Miscellaneous Actions

杂项操作

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

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

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

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

Note Actions

笔记操作

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

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

Statistic Actions

统计操作

```
getNumCardsReviewedToday
```
```
getNumCardsReviewedByDay
```
```
getCollectionStatsHTML
```
```
cardReviews
```
```
getReviewsOfCards
```
```
getLatestReviewID
```
```
insertReviews
```

```
getNumCardsReviewedToday
```
```
getNumCardsReviewedByDay
```
```
getCollectionStatsHTML
```
```
cardReviews
```
```
getReviewsOfCards
```
```
getLatestReviewID
```
```
insertReviews
```

Notes and Pitfalls

注意事项与陷阱

Keep Anki in the foreground on macOS or disable App Nap to prevent AnkiConnect from pausing.
When updating a note, ensure it is not being viewed in the browser editor; updates may not apply.
```
importPackage
```
paths are relative to the Anki
```
collection.media
```
folder, not the client.
```
deleteDecks
```
requires
```
cardsToo: true
```
to delete cards along with decks.

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

Resources

资源

No bundled scripts or assets are required for this skill.

此Skill无需捆绑脚本或资产。

anki-connect

Original

Translation

AnkiConnect

AnkiConnect

Overview

概述

Preconditions and Environment

前置条件与环境

Safety and Confirmation Policy (Critical)

安全与确认策略（关键）

API Fundamentals

API基础

Request Format

请求格式

Response Format

响应格式

Permissions

权限

curl + jq Patterns

curl + jq 模式

Minimal request template

最小请求模板

With params

带参数的请求

Handling result/error

处理结果/错误

Batching multiple actions

批量执行多个操作

Core Workflow Guidance

核心工作流指南

1) Verify connectivity and version

1) 验证连接性与版本

2) Discover supported actions

2) 发现支持的操作

3) Resolve user request into action sequence

3) 将用户请求转换为操作序列

4) Execute and validate

4) 执行与验证

Common Task Recipes (CLI-Oriented)

常见任务示例（面向CLI）

List decks

列出卡组

Create deck

创建卡组

Search notes / cards

搜索笔记/卡片

Preview note data

预览笔记数据

Add notes

添加笔记

Update note fields or tags

更新笔记字段或标签

Delete notes

删除笔记

Suspend/unsuspend cards

暂停/恢复卡片

Move cards to a deck

将卡片移动到卡组

Set due date or reschedule

设置到期日期或重新安排

Media upload/download

媒体上传/下载

Sync

同步

Search Syntax Quick Notes (for findNotes/findCards)

搜索语法快速说明（适用于findNotes/findCards）

Action Catalog (Use as a mapping reference)

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

Card Actions

卡片操作

Deck Actions

卡组操作

Graphical Actions

图形界面操作

Media Actions

媒体操作

Miscellaneous Actions

杂项操作

Model Actions

Search Syntax Quick Notes (for
`findNotes`
/
`findCards`
)

搜索语法快速说明（适用于
`findNotes`
/
`findCards`
）