coread-explainer — 共讀插圖（附稽核）

coread-explainer — 共讀的圖解(附稽核)

這個 skill 由兩層構成。繪製方法使用 anatomy 的 kit(等角相機、四層陰影、框架卡片、零件)。這個 skill 的核心是建立在它之上的紀律與機制: 只讀取凍結的數據、重新計數、將限制顯示在整個畫面上、將可說/不可說記錄在帳本中、並將圖面引發的問題轉化為卡片來回答。圖解是「讓 AI 的讀數與人類的理解對齊」的面向，而非裝飾。因此，哪怕一個數字若無法追溯到來源，整個圖的可信度就會下降。

最初的範例是經過多次迭代的圖解條目(v1~v5)。範例條目可從 gallery 的 DOI(10.5281/zenodo.23992312·所有版本的 concept DOI)取得。如果感到疑惑，請閱讀其 NOTES、CLAIMS、README。

0. 開始前決定的事項(寫在 BRIEF 中)

每次圖解請求，都必須先寫成 BRIEF(委託書)再開始製作。如果沒有 BRIEF，製作者會讀取材料以外的內容、手動放置數字、並自行決定評估標準。BRIEF 應包含：

1. 委託的逐字記錄(委託人的原話·日期)。
2. 讀者與最終評估(預設為三個。若有不同讀者則替換)：
   • E1 編輯: 圖與文字忠於論文(或報告)，不宣稱論文未主張的內容。品質可作為論文圖表或補充材料。
   • E2 影片作者: 僅依賴 1920×1080 的拍攝與腳本，即可製作 1~2 分鐘的單一場景。前 10 秒呈現核心。
   • E4「因為是這個儀器，所以得到這個讀數」: 陽性對照、門(eligible 判定)、改變帶或條件時讀數會改變——這些可作為證據鏈在拍攝中呈現。
   • 若更換讀者，也需撰寫該讀者的驗收測試(例如：課堂學生則需在觀看圖後回答三個問題，以及正確答案的標準)。僅保留 E1/E2/E4 的名稱，無法作為學生用圖解的衡量標準。
3. 材料清單(絕對路徑·只讀這些)與 不讀取的項目(其他製作者的資料夾、判定、記憶)。
4. 比對用的數值(執行層從數據中讀取的數個值)。若不符，則以數據為準。
5. 放置位置(entry_<卡片>_vN/·不覆寫前一個版本的資料夾)與 草稿區(每位製作者使用不同的子目錄)。
6. 截止時間(分鐘)與 回傳項目(≤ 10 行: 檔案、狀態數、拍攝、比對結果、最沒把握的點)。

→ 模板在 references/brief-template.md。

1. 材料的契約(data contract)

• 只讀取 凍結的卡片輸出(JSON、npz、圖的 png)。卡片 = PREREG(問題、宇宙、對照、判定、不主張的事項)+ 腳本 + 輸出(provenance = commit、dirty、md5)。圖中不顯示卡片外的數字。
• 不匯入也不執行實驗腳本(沒有 main 保護的彙整腳本，匯入時可能改寫凍結的結果)。只讀取數據檔案。
• 數字由腳本從數據中產生。不用手動寫入 HTML 或腳本。產生的數字需經 兩個以上獨立路徑重新計數(例如：pack 的 Python assert / 頁面的 JS / kernel 端 / check_claims.py 的 anchor = 檔案、鍵、期望值)。若與比對用的值不符，則以數據為準並通知委託方。
• 截斷值的柵欄: 上限截斷的排名(例如：第 1000 名以下 = 1001)以迷霧、均勻的顏色描繪，不描述為「沉沒了」「被壓制了」。截斷的順序(先截斷再取中位數，或先取中位數再截斷)需與卡片文件及實作一致。若因偶數個數值導致中位數衝突，需揭露。
• 非 eligible 的帶或條件的數值，僅在比較的一側以附有「未通過稽核」卡片的狀態顯示。不在該處將 null 描繪為「不存在」。
• 來自相同 seed、相同 prompt 群組的行不獨立計數(需明確說明計數方式，例如「不同場景有 3 個」)。
• RESULT 的讀數(L3)不是數據。在將 RESULT 的文字寫入圖中之前，必須確認該文字是否建立在數據的數字之上。曾有將比例誤解為數量的例子(「上層多為預告與迴響」= 以位置比例來看是正確的，但數量上基線位置佔了 80%)。若不成立，則不寫入圖中，將其轉入帳本的「不可說」，並要求 RESULT 方修正。
• 正在增長的檔案需先凍結副本再傳遞(log、日誌): 在 BRIEF 中寫明行範圍與 md5，製作者僅讀取該範圍。防止後續新增的記錄(例如評估答案)混入材料。

→ 詳細說明與陷阱在 references/data-contract.md。

2. 製作物件(一個 entry 資料夾)

entry_<卡片>_vN/
  build.mjs            從 kit 組合頁面與 widget 的 ESM / CSS(不手動修改 HTML)
  pack_*.py            數據 → 圖的 pack(assert 作為重新計數的第一路徑)
  data.mjs / live.js   頁面狀態的機制與繪製(第二路徑的重新計數)
  i18n.js              ja / en 的語言文字
  *_widget.py/.js/.css anywidget(traits: state、row、t、layer、band、lang、theme 等)
  demo_marimo.py  demo_jupyter.ipynb
  check_claims.py  make_check.py  run_*.sh   檢查(§5)
  captures/            拍攝(§6)
  CLAIMS.md  NOTES.md  README.md  SCRIPT_yukkuri.md
  (內部層為獨立檔案: *_layer.js / *.css / README_internal.md — §8)

• 章節與狀態: 以可步進的圖呈現狀態(0, 1, 2 …)，並用章節來分組(例如：場景 → 稽核 → 主題場景 → 共讀一輪 → 帳本)。在狀態編號序列的上方放置 章節按鈕(點擊後跳轉至該章的第一個狀態)。章節與狀態按鈕應放在標題上方(頁面頂端)(.sh-nav·在頁面中以 sticky 固定在螢幕頂端): 若放在下方，按鈕會因標題文字長度而在不同狀態上下移動，導致點擊後迷失(委託者 10-28 晚「按按鈕後因頁面高度差異而迷失，請放在沒有上下移動的上方」·修正前不同狀態可移動超過 900 px)。檢查應包含「所有狀態的帶之上端位置相同」。重新編號後，應列出標題清單(狀態編號 → 標題)進行自我檢查(重新編號腳本的雙重偏移已實際發生過)。
• widget 不包裹在 iframe 中。圖的操作可送達 Python，Python 也可寫入狀態(雙向)。需同時在 marimo 與 JupyterLab 中運作。
• 頁面有 4 個版本(暗 / 明 × ja / en)，由 build 過程生成。

→ 實作模板在 references/implementation.md(以範例 entry 為基礎的骨架)。最小模板在 assets/(使用合成數據完成 build、檢查、拍攝的骨架: config.json 作為狀態、章節、框架編號的唯一存放處 / run_checks.sh / list_headings.py / _smoke/ 存放運作證據)。新的圖解從此處複製開始。

3. 語言的紀律(帳本: 可說 / 讀數 / 不可說)

帳本放在圖的最後一章，每行附上來源(檔案與鍵):

• 可說(L1): 數據值的副本、凍結的判定。
• 讀數(L3): 明確標明誰的讀數(執行層 / 製作者)，並附上「採納與否由人類決定」的卡片。對於預設由委託者替換措辭的句子，附上相應的卡片。
• 不可說: 用陳述句明確表達(「不稱為~」)。不以小註解或「~說不定」結尾。至少包含：機制 / 同定(將僅為並置的裁定稱為相同事物)/ 量的判斷(差小於誤差帶)/ 儀器有效範圍外的讀數 / 未讀取的一方(例如 prompt 方)/ 從單一實例推論「唯一」/ 將非獨立行獨立計數。

本文與腳本中不使用詞彙：「model 考慮過·猶豫過·注意到·知道·其實明白」、「看到 AI 的心靈」、「看穿謊言」類似的誇張。應在圖中標明 lens 的排名是 lens 的讀數，而非 model 內部的地圖。

將限制的卡片顯示在章節的每個畫面上(框架下方一行 + 右上角身分卡片): 有效範圍、僅描述、不同定、未讀取方、n。未出現在拍攝中的限制等同於不存在。但限制必須確認確實適用於該畫面的數據後才貼上。不要直接將範例文字(references/wording.md)複製到所有章節。例如：「位置全部在儀器 fit 範圍外」必須逐行確認位置(在範例中，某些條件的行位於外部，但其他條件的行因 prompt 較短而在內部)。若適用範圍在章節內有所區分，則將卡片逐行分開。

→ 範例文字與禁用詞清單在 references/wording.md。

4. 顯示方式的類型(v1~v5 中有效的方法)

• 入口是場景: 第一章以單張畫面呈現「發生了什麼事的瞬間」(例如：在寫答案前的 prompt 上浮現中間語言·答案區塊保持空白)。數據的稽核放在其後。
• 立體的三軸: 橫軸 = 位置(寫入的 token)·縱軸 = 層·深度 = 儀器排名(前景 = 第 1 名·對數·超過上限後為迷霧)。對照的帶為厚板，帶外為灰色表示「對照外·僅供參考」。
• 並排成功與失敗: 將兩個立體放在 同一個投影·同一台相機·共用刻度 中，轉動一個時兩者皆轉。影片左右並排 / desktop 與 phone 上下堆疊(為保持卡片最小字體)。
• 宣告對齊方式: 對於輸出不同的兩行，明確標明在哪裡對齊(分歧點 / 關鍵詞 / 欄位開頭)，如果從對齊點到關鍵詞的距離不同，則標註「+1 token / +3 token」。並排顯示以距離對齊的視圖(以關鍵詞位置 k 對齊的 small multiples)。
• 長度為 0 的部分也要用框架描繪: 對於只有一方存在的部分(例如：思考欄 token / 0 token)，在兩邊都立起相同寬度的框架，其中一邊為虛線的空框架。僅保留空白會被視為漏繪而受到質疑。
• 預告與迴響: 若儀器將「即將寫的詞」「剛寫的詞」排在前面，則用標記區分該位置(F / E)，與安靜的位置分開顯示。
• 不補足數據中不存在的部分: 若數據僅有彙整而沒有逐行位置，則入口場景需附上「示意圖(非實際行)」的卡片。不描繪記錄中不存在的過渡狀態(例如：3 台 → 1 台之間插入 2 台·逐一消失的順序)。記錄間隔(例如：每 2 分鐘)外的時刻以「這段期間的某處」並附上範圍來表示。
• 名稱在單一位置決定: 位置、行、面的名稱(例如：「分歧點」「對齊位置」)放在 helper 或 config 的單一位置中，所有畫面的文字使用相同名稱。加入檢查以確保沒有殘留舊名稱(§5)。
• 顏色意義唯一: 保留已具有意義的顏色(例如：橙色 = He/Hi 組·藍色 = apex 組)，不添加新顏色。只在非數據的裝飾(內部層的比喻)中添加顏色時，需使用 dataviz 的 validator 確認與現有顏色在暗 / 明兩面均符合 normal ΔE ≥ 15·CVD ΔE ≥ 8。不使用第三方角色、圖片、外部字型。

5. 檢查(拍攝前全部通過)

• console 乾淨(頁面 4 個版本·desk·phone·video·reduced motion·marimo·JupyterLab)。與圖無關的擴充功能警告需記錄並區分。
• robust: 所有狀態 × 所有行 × 部分層級 的例外為 0。
• 數字比對: check_claims.py 的所有 anchor(檔案·鍵·期望值)全部一致·缺失為 0。比對用值 N / N。
• 章節按鈕: 透過真實點擊，驗證能跳轉到各章的第一個狀態，並檢查選中外觀、hash、標籤(ja / en)是否正確。
• 字體大小: 對每個拍攝框架測量卡片的最小 px(參考標準 video ≥ 10 px·desk ≥ 10 px·phone ≥ 9.5 px)。無法閱讀的卡片等同於不存在。
• 超出範圍: viewBox 外的文字數為 0。
• 公開柵欄: 主要檔案中內部用語(§8)的出現次數為 0(使用 grep 計數)。
• 名稱掃描: 掃描所有狀態 × ja / en 頁面的文字，確保舊名稱、禁用上下文出現次數為 0。同時需包含掃描本身的陽性對照(驗證可檢測到混入舊文字的頁面)。
• 工具備忘：phone 的卡片最小 px，需在縮小 viewBox 放大文字，並將 kit 四角文字改為垂直排列後才能達到 9.5 px(模板初始值為 2.7 px)。?video=1 會隱藏章節按鈕，因此點擊測試需在 desk 與 phone 進行。

→ references/checks-and-captures.md。

6. 拍攝與腳本

• 每個狀態的 1920 × 1080(用於 video·精確尺寸)+ desk(暗 / 明)+ phone。對於顯示瞬間的狀態，需前後兩張(例如：位置 24 → 25)。
• SCRIPT_yukkuri.md: 對話形式(A = 聽眾 / B = 解說) ≤ 150 秒·每行標註要顯示的狀態 cue·前 10 秒為場景。不使用真實角色名稱或圖片。

7. 共讀的一輪(這個圖解最重要的用途)

觀看圖的人提出問題時(例如：「He 從哪裡湧現出來？」)，將其轉化為卡片來回答。步驟： 0. 確認問題的用語: 確認問題所指的位置、行、語詞在圖中是否唯一確定。如果圖中名稱不一致(例如：同一位置，某個畫面稱為「分歧點」，另一個畫面稱為「分歧點前一個」)，則在讀取數字前先向提問者確認一次，並將圖中名稱不一致的部分列入修正。

1. 提出候選(讀數·L3): 提供二到三個可能回答問題的解釋。每個解釋附帶三個標記：(a) 是否依賴儀器(lens) / (b) 該量是否在 persist(已儲存的數據)中·需要新的 forward·需要新的生成**(「persist 中沒有」不代表「量不存在」——例如：model 自身輸出的排名在任何位置都有，但僅儲存了已寫入 token 的排名)/ (c) 是否觸及稿件的柵欄(例如：不將述語連結到對照帶外的層級)。優先順序為「不依賴 lens·在 persist 中」的候選在先，其次是需要 forward 的候選，依賴 lens 的候選在後。觸及柵欄的候選則剔除。
2. 先凍結卡片: 將 PREREG(問題·宇宙·對照(包含陽性對照)·讀取用語·不主張的事項·預先所見內容的揭露)與腳本放入一個 commit，並設定僅在 non-dirty 狀態時才能執行 --fire。在看見數值前先凍結。
3. 讀取 → RESULT: 數字為輸出的副本(L1)·讀數為 L3·不主張的事項保持 PREREG 原樣。
4. 對照失敗則停止: 不先繪製圖的數據即停止，僅在本文端診斷原因，並將修正版作為 新的卡片 重新凍結(不在執行後移動卡片定義)。範例：逐 token 的字元解碼在多 byte 字元邊界變成 U+FFFD，導致位置與本文偏移 → 對照 C2 捕捉到 → 使用 byte 對應的新卡片。記錄為「AI 的讀數也需要對照」的實例。
5. 作為一個狀態回到圖中: 「從圖產生問題，以卡片回答」= 看圖 → 人類提問 → AI 候選 → 凍結卡片並讀取 → 答案與不可說的事項 → 下一個問題。

→ references/coread-loop.md(卡片模板·對照的思考方式)。

8. 內部層(比喻·內部用語)

若要在圖中放入研究室內部的比喻(例如：內部名稱、吉祥物)，將其作為 隱藏層：放在獨立檔案(*_layer.js / *.css / README_internal.md)中，主要部分僅需「存在時讀取·不存在時不做任何事」。開啟/關閉透過隱藏指令(按鍵組合)+ URL flag + widget trait。預設關閉·僅在日文頁面啟用·英文頁面不做任何事。層開啟時，右上角顯示「內部層·不對外公開」。在主要檔案中內部用語出現次數設為 0，並將其納入檢查(避免整個圖解從公開包中脫落)。比喻圖自行繪製，並確保比喻不會被解讀為機構的主張，即使在層內也明確標示「不可說」。

9. 審查與版本

• 每個版本分開放置(_v1…_vN)，不覆寫前一個版本。小幅修正以 vN.1, vN.2 … 方式記錄，並在 NOTES 中寫明「修正了什麼·誰的指摘」。
• 審查由 與製作者不同族的 model 的冷讀者進行，僅提供判定標準檔案、拍攝檔案與 CLAIMS / NOTES / README(不讓對方看到彼此的判定·不讓對方推測製作者)。標準為 E1 / E2 / E4(+ 參考的 E3)。標準模板在 references/judging.md。

10. 公開(在論文中附加時)

• 可操作的頁面透過 GitHub Pages(靜態網站)展示，同一個 repo 的 release 在 Zenodo 以 DOI 方式凍結(Zenodo 不渲染 HTML，但下載完整套件後可在 file:// 下運作)。論文中同時列出兩者。
• 從公開包中移除內部層(§8)。保留 Anatomy 的 MIT 標示(Copyright (c) 2026 Ryan)在 README 與頁面底部。
• 將此 SKILL.md 本身放入包中：即使無法完全再現，也能展示製作圖解的步驟(提示)。
• md5 放入 MANIFEST。→ references/publishing.md。