Morphowiki

/lint — 字典健檢與語意校正

執行字典庫的全面結構檢查，或針對單一單字進行語意與拆解邏輯的審核。

/lint — Health check and audit

Run a structural consistency check over the whole dictionary, or a deep semantic audit on a single word's breakdown and logic.

為什麼需要這個功能？

Morphowiki 的核心在於雙向連結：單字頁 international 指向字根 nat，則字根 nat 的 ## 包含此語素的單字 也必須回填 international。一旦連結斷裂，字典的結構價值就會大打折扣。

常見的資料不一致情況包括：

  • 單字檔漏掉 ## 筆記區，導致複習介面 (/review-word) 抓取資料失敗。
  • 同一個字同時存在於字典與 Stopwords 名單中，造成系統行為矛盾。
  • flashcards.json 殘留已刪除單字的卡片資訊（孤兒卡片）。
  • 語素頁面引用了不存在的單字檔（手動更名或刪除後的殘留）。

當字典規模擴大時，手動巡檢幾乎不可能達成。/lint 能在數秒內掃描全庫，列出所有檔案的問題位置與類別，是維持資料高品質的守護者。

Why this exists

The whole point of a morphowiki is two-way links: the word page international points at the root nat, and the ## Words containing this section of nat must point back at international. If one side is missing, the link is silently broken and the dictionary loses its teaching value.

Other invisible breakages of the same kind:

  • A word file is missing its ## 筆記區 section, so the review web app (/review-word) reads it as incomplete.
  • The same word lives in both dictionary/words/ and stopwords.md — the system disagrees with itself.
  • review/flashcards.json still has a card whose underlying word file has been deleted, so the review web app shows a blank.
  • A morpheme page lists a word that no longer exists (an orphan left over from a manual rename).

By the time your dictionary holds 50 or 100 words, eyeballing every file is impossible. /lint automates that sweep: a few seconds to scan, and you get a list of problems by file and category — a map of exactly where to go fix things.

模式說明

/lint 指令具備「靜態掃描」與「語意審核」雙重功能：

/lint (無參數)

全庫結構檢查：純在地解析，不耗費模型點數。掃描所有單字、語素、Stopwords 以及複習卡清單。

檢查重點：斷裂連結、Section 命名規範、Frontmatter 格式、語素引用是否存在、複習卡與檔案對應關係。

/lint <word> (單字模式)

語意深度校正：針對特定單字呼叫 LLM 進行檢驗（會耗費少量點數）。檢查拆解邏輯、詞源敘述一致性、IPA 及釋義準確度。

互動式引導：系統會列出具體建議並編號。您可以回應 1,2 或 all 來指示 Claude 自動套用指定的修正建議。

安全提示：無參數模式絕不會更動您的任何檔案；單字模式則必須在取得您的明確授權（Apply fixes）後，才會自動重寫檔案內容。

Two modes

/lint behaves quite differently depending on whether you pass a word. The distinction matters:

/lint (no argument)

Whole-dictionary structural check. Pure parsing, no LLM call (free), report-only. It walks every word file, every morpheme file, stopwords.md, and flashcards.json.

What it catches: broken two-way links, missing fixed-Chinese section names, malformed frontmatter, malformed breakdown lines, stopword conflicts, orphan flashcards, missing morpheme files referenced by a word, missing ## 筆記區 sections.

/lint <word> (one English word)

Whole-dictionary structural check PLUS an LLM semantic check on that word. The structural part is the same; the semantic part calls the LLM once for that word (cost roughly equal to one small /ingest) and checks the morpheme breakdown, definition accuracy, etymology-vs-breakdown consistency, POS, and IPA.

Interactive: semantic findings are numbered, and Claude waits for you to reply 1,3 / all / none / details 2 before it touches any file. Structural findings remain report-only.

Key distinction: structural mode never modifies your files — you can run it as often as you like. Semantic mode only edits after you approve, and only files related to that one word. Neither mode writes a lint-report file, updates log.md, or touches stopwords.md / flashcards.json.

具體範例

批次 ingest 完一句英文後,跑:

/lint

Claude 大概會回類似這樣的報告(問題依檔案分組,每個問題標 error 或 warn): 

✗ dictionary/words/unbelievable.md
  error  拆解引用 [[../prefix/un-]] 但 dictionary/prefix/un-.md
         的 ## Words containing this 沒有回填 [[../words/unbelievable]]

✗ dictionary/words/predict.md
  error  缺 section: ## 筆記區

✗ dictionary/words/international.md
  warn   "international" 同時出現在 stopwords.md (custom),
         可能是先 ingest 後補 stopword

✗ review/flashcards.json
  error  cards[] 內 "old-word" 在 dictionary/words/ 找不到對應檔

摘要: 3 errors, 1 warn, 12 word files / 8 morpheme files / 1 flashcards.json checked

讀法:

  • 檔名行(✗ dictionary/words/…)告訴你去哪一個檔修。
  • error 會讓複習網頁讀不到資料,或破壞雙向連結對稱性 — 一定要修。
  • warn 可疑但不致命 — 看情況處理。
  • 摘要行讓你知道掃了多少檔。全部通過時會看到 ✓。

若你想針對某個字做深度檢查,加參數:

/lint unbelievable

除了上面同樣的結構區之外,還會多一段語意檢查與互動提示:

=== 語意檢查 ===
[1] error  拆解詞源不合理:現行 root 寫成 [[../root/believ]],
           但 unbelievable 詞源 root 通常記為 believe。
           建議改成 [[../root/believe]] + suffix [[../suffix/-able]]。
[2] warn   IPA /ˌʌn.bɪˈliː.və.bəl/ 看起來合理。
[3] warn   ## 詞源 段未說明古英語 belyfan 來源,
           與拆解 root believe 預期一致性偏弱

要套用哪幾條? 回 "1,3" / "all" / "none" / "details <n>":

回 1,3 套用第一、三條;all 套全部;none 一條也不套;details 1 看第一條的完整改寫內容再決定。Claude 套用完會回報實際改了哪幾個檔。

關於拆解格式:上面範例顯示的固定中文 section 名(## 拆解 / ## 詞源 / ## 記憶法 / ## 筆記區)、固定中文欄位標籤(**詞性**: / **IPA**: / **中文釋義**:)、以及 wiki-link 格式([[../prefix/un-]] 等)都是字典的固定格式。/lint 結構檢查之中,「section 名是否正確」就是其中一項;手改成英文 section 名會被 lint 抓出來。

A concrete example

After batch-ingesting a whole sentence, run:

/lint

Claude returns something like this (problems grouped by file, each tagged error or warn): 

✗ dictionary/words/unbelievable.md
  error  Breakdown references [[../prefix/un-]] but dictionary/prefix/un-.md
         is missing [[../words/unbelievable]] under "## Words containing this"

✗ dictionary/words/predict.md
  error  Missing section: ## 筆記區

✗ dictionary/words/international.md
  warn   "international" appears in both dictionary/words/ AND
         stopwords.md (custom) — likely ingested first, stopworded later

✗ review/flashcards.json
  error  cards[] has "old-word" but dictionary/words/old-word.md does not exist

Summary: 3 errors, 1 warn, 12 word files / 8 morpheme files / 1 flashcards.json checked

How to read it:

  • File line (✗ dictionary/words/…) tells you which file to open and fix.
  • error will make the review web app misread data or break two-way link symmetry — must fix.
  • warn suspicious but not fatal — fix as appropriate.
  • Summary line tells you how much was scanned. A clean run shows ✓.

For a deeper check of one word, pass it as an argument:

/lint unbelievable

You get the same structural block plus a numbered semantic block and an interactive prompt: 

=== Semantic check ===
[1] error  Breakdown root mismatch: current file uses [[../root/believ]],
           but the etymological root of unbelievable is recorded as believe.
           Suggestion: change to [[../root/believe]] + suffix [[../suffix/-able]].
[2] warn   IPA /ˌʌn.bɪˈliː.və.bəl/ looks plausible.
[3] warn   ## 詞源 section doesn't mention the Old English source belyfan;
           consistency with the breakdown root "believe" is weak.

Apply which? Reply "1,3" / "all" / "none" / "details <n>":

Reply 1,3 to apply items 1 and 3, all for everything, none for nothing, or details 1 to see the full proposed rewrite of item 1 before deciding. After applying, Claude reports which files were actually modified.

About dictionary format: the fixed Chinese section names shown above (## 拆解 / ## 詞源 / ## 記憶法 / ## 筆記區), the fixed Chinese field labels (**詞性**: / **IPA**: / **中文釋義**:), and the wiki-link format ([[../prefix/un-]], etc.) are fixed in the dictionary regardless of UI language. One of the things /lint structurally verifies is that those exact section names are present. If you rename them to English by hand, lint will flag the file.

操作指南

  1. 在對話框輸入 /lint (無參數) 以執行全庫結構檢查。
  2. 若看到 ✓ 全部通過，代表您的字典連結狀態完美。
  3. 若出現錯誤：
    • 查看報告中的「檔案路徑」找到出問題的單字檔。
    • 根據錯誤描述（如缺少雙向連結或區塊遺失）進行修正。
    • 推薦做法：直接刪除該單字檔並重新執行 /ingest <word>，系統會自動重建完整連結。
  4. 修復完成後建議再次執行 /lint 確保問題已全數排解。
  5. 針對特定單字執行 /lint <word> 進行深度語意審核。

自動化修護建議：結構錯誤通常需要手動檢查，而語意錯誤則是透過互動式選單進行修復。修復順序建議：先格檢查，後語意，因為格式錯誤可能會干擾語意分析。本操作不消耗模型額外配額。

Step by step

  1. In the Claude Code chat, type /lint (no argument). Wait a few seconds for the report.
  2. If you see ✓ All clear, the dictionary is healthy — you're done.
  3. If there are errors / warnings, work through them one by one:
    • Read the "file line" to find which file to open.
    • Read the problem description to know what's needed (add a back-link? add a ## 筆記區 section? remove from stopwords.md?).
    • The cleanest fix is usually to re-run /ingest <word> (delete the old word file first, then ingest) — this regenerates all the back-links correctly.
    • For smaller issues, edit the named file directly.
  4. After fixing, run /lint again to confirm the issues are gone.
  5. To do a semantic review on one word — for example, after /ingest you want to double-check the morpheme breakdown — run /lint <word>: 
    /lint unbelievable
    When you see the numbered semantic suggestions, reply with which to apply (1,3 / all / none / details 2). Claude will use the Edit tool on the related files and report what was actually changed.

When to run /lint

  • After a batch ingest: a long sentence can produce a dozen+ words, and inconsistencies can creep in.
  • After any manual edit to a word or morpheme file: to verify you haven't broken a back-link.
  • Before relying on the dictionary for review: so the review web app doesn't hit broken data.
  • Weekly or monthly as a routine health check: keeps the dictionary clean.

The no-argument structural check costs zero LLM tokens — run it as often as you like.

常見誤區與建議

常見誤區 1：將 /lint 誤認為自動修復工具。純 /lint 指令（結構模式）絕不會更動您的檔案，僅負責偵測並報告。若發現問題，您需要手動編輯該檔案，或刪除後透過 /ingest 重建。這是為了防止 AI 在不確定真實性的情況下誤改資料。

常見誤區 2：批次收錄（Batch Ingest）後未進行檢查。單次收錄長句可能同時產生多個新單字與語素連結，偶爾會發生連結沒對齊的情況。建議在大量操作後執行一次 /lint。

常見誤區 3：手動修復語素的回向連結。若報告指出 prefix/un-.md 缺少回填連結，比起手動補寫，更推薦的做法是刪除該單字檔並重新執行 /ingest <word>。系統會全自動且準確地重建所有雙向關聯。

常見誤區 4：盲目採納語意審核建議。處理特定單字的 /lint <word> 時，模型給出的詞源或 IPA 修正建議並非 100% 絕對正確。請詳閱建議理由後再決定是否套用（或使用 details <n> 檢視差異）。

常見誤區 5：期待偵測「筆記區」的內容品質。目前的檢查僅確認 ## 筆記區 區塊是否存在，並不對內容進行主觀評分（那是屬於您的個人學習空間）。

後續探索：

返回 首頁。

Common mistakes & next steps

Mistake 1 — Treating /lint as an auto-fixer: structural mode never modifies files; it only reports. You open the named files and fix them yourself (or re-run /ingest). This is intentional: for issues like "back-link missing on one side", the LLM cannot know which side is the source of truth, and auto-applying a guess would be dangerous.

Mistake 2 — Skipping /lint after a batch ingest: a long sentence can recurse into 5 or 6 words, and occasionally one back-link slips. Running /lint after any batch operation is a good habit.

Mistake 3 — Hand-editing morpheme files to "fix" a missing back-link: when lint reports "prefix/un-.md is missing [[../words/unbelievable]]", the instinct is to open that morpheme file and add the line. You can — but the cleaner fix is usually to delete dictionary/words/unbelievable.md and re-run /ingest unbelievable. Ingest rebuilds all back-links correctly and may fix related issues you hadn't noticed.

Mistake 4 — Blindly applying all semantic suggestions from /lint <word>: the LLM's calls on morpheme etymology, IPA, and definition accuracy are not 100% reliable. Each suggestion comes with a reason — read it before accepting. Use details <n> to see the full proposed change, or reply none and handle it manually if unsure. all is convenient but bites you on false positives.

Mistake 5 — Expecting /lint to check the content of ## 筆記區: lint only verifies that section exists; the content is yours and lint won't grade it. Also not checked: Traditional / Simplified mixing, mnemonic quality, or other subjective things.

Next steps:

  • The best fix for structural issues is usually re-ingesting — see /ingest.
  • Want to understand why back-links matter? Read What is a Morphowiki.
  • Want to remove an orphan flashcard? Use /flashcard remove <word>.
  • Want to settle a stopword conflict by moving a word permanently into the allow-list? Use /stopword (and remember to delete the matching file under dictionary/words/).

Back to home.