vocab-anki
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-07-27
- Stars
- ★ 0
- Forks
- 0
02 资源文件 10
- 其他.gitignore48 B
- 参考文档package.json308 B
- 脚本scripts/lib/anki.js809 B
- 脚本scripts/lib/word_validate.js1.3 KB
- 脚本scripts/tests/anki.test.js1.5 KB
- 脚本scripts/tests/vocab_lookup.test.js3.5 KB
- 脚本scripts/tests/vocab_push.test.js6.8 KB
- 脚本scripts/tests/word_validate.test.js2.0 KB
- 脚本scripts/vocab_lookup.js3.2 KB
- 脚本scripts/vocab_push.js6.7 KB
03 SKILL.md 正文
vocab-anki
Per-run pipeline: Todoist #vocab words → single-sense Anki Vocabulary
notes, each generating two cards — Production (definition → word) and
Recognition (word → definition + example) — no masking involved. Standalone
skill — shares no code, note type, or deck with anki-flashcards (NF-04).
Spec: AgentOS/reference/plans/2026-07-17-vocab-anki-pipeline.md.
Trigger: manual invocation (you say "run vocab-anki" / "push vocab words", or trigger the equivalent headless CLI call from a local cron per FR-10 — either way, this SKILL.md is what runs; there is no version of this pipeline that runs without an AI turn, since sense generation is AI knowledge, not an API call — FR-11).
Decisions made with the user (2026-07-17, revised 2026-07-18, revised again 2026-07-18, corrected 2026-07-18):
- Card template: two directions. Production (Word Class + Definition →
Word — the example sentence is dropped from the front entirely; it does
still appear on the back, unmasked, for review context) and Recognition
(Word → Word Class + Definition + Example Sentence, shown in full/
unmasked — no leak risk since the word is already given on the front).
maskWord/escapeRegExpand all masking logic were removed fromvocab_push.js— fields are pushed as plain text now, no transformation. The note type moved from 2 fields (Word,Senses— a bundled HTML blob of up to 4 senses) to 4 flat fields (Word,Word Class,Definition,Example Sentence), one primary sense per word (no more multi-sense bundling/merge) — that part of the 2026-07-18 revision is unchanged. - Correction (2026-07-18, later same day): the note type is now a true
Standard note type (
isCloze: false), not Cloze. An earlier pass of this revision assumed a Cloze-type note type could host plain templates alongside cloze ones — that assumption was wrong and was disproved live: Anki's own model validation rejects any template in a Cloze-type note type that doesn't reference{{cloze:...}}on both front and back ("Card template N ... Expected to find '{{cloze:Text}}' or similar"). Since neither Production nor Recognition needs cloze semantics anymore, Standard is the correct type. AnkiConnect has no way to change an existing model's Cloze/Standard flag or delete a model, so the fix required deleting the oldVocabularyCloze note type by hand in the Anki desktop app (Tools → Manage Note Types → Vocabulary → Delete, which also removes its notes) and lettingvocab_push.jsrecreate it fresh as Standard on the next run — the 9 words that existed at the time were re-pushed using their already-stored field data (no regeneration needed; this was a template/model bug, not a content bug). - Backfill for future template edits: automatic as long as the model stays
Standard —
ensureDeckAndModel()re-pushesCARD_TEMPLATESviaupdateModelTemplateson every run when the model exists, and Standard note types accept arbitrary template edits without Anki's cloze-filter validation getting in the way. - One historical wrinkle (already resolved, kept for context): notes pushed
live under the earlier masked-Cloze revision had had literal
{{c1::word}}markup baked into theirExample Sentencefield data (not just template-applied) — fixed via a one-timecleanup_cloze_markup.jspass (run once against the live collection, then deleted, per convention) before the Standard-type correction above made that whole approach moot anyway. SeeAgentOS/reference/plans/2026-07-17-vocab-anki-pipeline.md's Revision sections for the full history. - FR-08 flag mechanism: Todoist comment on the task itself (task stays open/incomplete).
Step 1: Query Todoist for incomplete #vocab tasks (FR-01)
Use your task-management connector (AgentOS/reference/harness_compat.md).
On the Todoist MCP connector (Claude Code / Cowork):
find-tasks({ labels: ["vocab"], limit: 100 })
No projectId — this must cover every project (FR-01). find-tasks returns
active (incomplete) tasks only, which is also the idempotency mechanism
(NF-02): a task that was completed by a prior run's Step 5 won't reappear
here. Page with cursor if more than 100 tasks come back (unlikely in
practice, but don't silently truncate).
If zero tasks come back, stop here — nothing to do.
Step 2: Validate word shape (FR-02 / FR-08)
scripts/lib/word_validate.js exports partitionTasks(tasks) — pass it the
Step 1 results shaped as [{ id, content }]; it returns
{ clean: [{id, word}], malformed: [{id, content, reason}] }. It's a small
pure function (no I/O), so drive it via a one-off node -e invocation
against a temp JSON file, or a short throwaway script — either way, run it,
don't hand-check word shapes yourself.
This is a shape check only (single token, letters + internal hyphen/apostrophe) — it does not judge whether the word is spelled correctly or real. That judgment happens in Step 4, on your own knowledge.
For each malformed entry, per the chosen flag mechanism:
add-comments({ comments: [{ taskId: id, content: "vocab-anki: couldn't process — task content isn't a single clean word ('<content>'). Fix the task text and it'll be picked up next run." }] })
Leave the task open. Do not proceed to Step 3 for these words.
Step 3: Look up existing Anki notes (FR-09 context)
Before generating anything, check what's already in Anki for the clean
word list — this is what lets Step 4 see prior context for a word instead of
regenerating blind:
node scripts/vocab_lookup.js /path/to/words.json
where words.json is a JSON array of the clean words (write it to a temp
path first — e.g. AgentOS/skills/vocab-anki/_tmp_words.json, gitignored
pattern, delete after use). Writes vocab_lookup_report.json:
{
"status": "ok",
"results": [
{ "word": "goad", "exists": true, "noteId": 111, "wordClass": "noun", "definition": "a spiked stick used to drive cattle", "exampleSentence": "The herder carried a goad.", "duplicateNoteIds": [] },
{ "word": "perspicacious", "exists": false, "noteId": null, "wordClass": null, "definition": null, "exampleSentence": null, "duplicateNoteIds": [] }
],
"generated_at": "..."
}
If status: "skipped" (AnkiConnect unreachable), stop the whole run —
report this to the user rather than proceeding without Anki (NF-01). No
Todoist tasks are touched.
If any duplicateNoteIds is non-empty, flag it to the user in the run
summary — FR-09's one-note-per-word invariant has already been violated by
something outside this pipeline; don't try to auto-resolve it.
Step 4: Generate the primary sense (FR-03 / FR-04 / FR-11, revised)
For each clean word, from your own knowledge (no external dictionary/API — FR-11):
- Identify the single most common/relevant dictionary sense: part of speech
- definition + exactly one example sentence (FR-03 — the sense may not lack an example). It's good practice for the example sentence to literally use the headword (any inflection/case is fine) since it's shown verbatim on the Recognition card and on Production's back — but this is no longer a hard technical requirement; Step 5 does no masking, so there's nothing to leak.
- Check for an informal/slang/cultural usage (e.g. "goad" → egg on). If it's more relevant/common than the literal dictionary sense for the user's purposes, use it as the primary sense instead of the dictionary one — only one sense is ever stored per note now (FR-04, revised; no more multi-sense cap since there's no bundling).
- If
vocab_lookup_report.jsonshowedexists: truefor this word, you may leave the note as-is and skip it (nothing new to add) unless you have a clearly better sense to offer. There's no multi-sense merge anymore — a Step 5 update fully replaces the existing sense (FR-09, revised). - If a word can't be resolved to any real sense at all (nonsense token,
unrecognizable, not actually a word despite passing the Step 2 shape
check), treat it like Step 2's malformed path: Todoist comment
(
vocab-anki: couldn't resolve "<word>" to a definition — check spelling), leave the task open, do not proceed to Step 5/6 for this word (FR-08). - Assemble the resolved entry as plain fields — no HTML wrapper:
{ "word": "goad", "wordClass": "noun", "definition": "a spiked stick used to drive cattle", "exampleSentence": "The herder carried a goad." }
Step 5: Push to Anki (FR-05 / FR-06 / FR-09, revised)
Assemble the resolved entries into a JSON array
[{ word, wordClass, definition, exampleSentence }] — only words that made
it through Steps 2 and 4 — write to a temp path, then:
node scripts/vocab_push.js /path/to/entries.json
This auto-creates the Vocabulary deck and note type on first run if either
is missing (FR-06) — fields Word/Word Class/Definition/Example Sentence unchanged, two card templates (Production, Recognition — see
decisions above). If the model already exists, it pushes template/styling
updates instead, so template edits — including the addition of the
Recognition template — take effect on re-runs for every existing note, not
just newly-created ones.
Fields are pushed to Anki as plain text — no masking or other transform happens at push time anymore.
It re-checks existence per word at push time (defends against staleness
since Step 3) and either updateNoteFields (existing note — full replace of
Word Class/Definition/Example Sentence, not a merge) or addNote (new
word), with allowDuplicate: false as a backstop duplicate guard on the
Word field. Writes vocab_push_report.json:
{
"status": "ok",
"results": [
{ "word": "goad", "status": "pushed", "noteId": 999 },
{ "word": "perspicacious", "status": "updated", "noteId": 111 }
],
"pushed": 1, "updated": 1, "failed": 0,
"warnings": [],
"generated_at": "..."
}
If status: "skipped" here too, stop — same as Step 3.
For any status: "failed" result, surface the warnings entry to the user;
do not complete that word's Todoist task in Step 6.
Step 6: Complete Todoist tasks (FR-07)
For every word whose Step 5 result was "pushed" or "updated", complete
its source task:
complete-tasks({ ids: [<taskId>, ...] })
Only after the Anki write succeeded — never complete a task pre-emptively (this is the idempotency backbone, NF-02, alongside Step 1's incomplete-only query).
Step 7: Clean up + summarize
- Delete any temp JSON files written in Steps 3/5 (
_tmp_words.json, entries file) — scratch state, not meant to persist. - Report to the user: words pushed, words updated (refreshed), words flagged
(Step 2 malformed / Step 4 unresolvable, with the Todoist comment already
left on each), and any
duplicateNoteIdssurfaced in Step 3.
Files
scripts/lib/anki.js AnkiConnect client (standalone copy — NF-04)
scripts/lib/word_validate.js FR-02 shape check (isCleanWord, partitionTasks)
scripts/vocab_lookup.js Step 3 — read-only existing-note lookup
scripts/vocab_push.js Step 5 — deck/model creation + addNote/updateNoteFields (Production + Recognition templates)
scripts/tests/ node --test coverage for all of the above
Run tests from this directory: node --test 'scripts/tests/*.test.js' (this
sandbox's Node needs the glob form, not the bare directory form — see
package.json).
04 同仓库更多 Skills
vault-maintenance
暂无简介
transcript-distillation
暂无简介
daily-log
暂无简介
capture-promotion
暂无简介
review
Clear due memory reviews with free recall — the two-minute habit that makes learning permanent. Use when reviews are due, or the user wants to review, practice, or "do my engram reviews".
learn
Learn any topic properly — first-principles curriculum, generation-first tutoring, verified free recall, FSRS scheduling. Use when the user wants to learn, understand, study, or continue studying something.