AGENT SKILL

vocab-anki

暂无简介

License 许可
MIT
最近更新
2026-07-27
Stars
★ 0
Forks
0

02 资源文件 10

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/escapeRegExp and all masking logic were removed from vocab_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 old Vocabulary Cloze note type by hand in the Anki desktop app (Tools → Manage Note Types → Vocabulary → Delete, which also removes its notes) and letting vocab_push.js recreate 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-pushes CARD_TEMPLATES via updateModelTemplates on 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 their Example Sentence field data (not just template-applied) — fixed via a one-time cleanup_cloze_markup.js pass (run once against the live collection, then deleted, per convention) before the Standard-type correction above made that whole approach moot anyway. See AgentOS/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):

  1. 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.
  2. 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).
  3. If vocab_lookup_report.json showed exists: true for 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).
  4. 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).
  5. 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 duplicateNoteIds surfaced 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