使用時機
針對任何需要詳細技術書面報告的場合，使用 Typst 而非 Word/.docx，例如：調查報告、架構摘要、根因分析文件、遷移說明。適用於這樣文件：
- 具有真正的技術報告樣式：封面頁、摘要、編號章節
- 列印效果良好（類似 LaTeX 的排版：
#set page、#set heading(numbering: "1.1")、左右對齊內文） - 包含圖表（架構圖、流程圖，而不只是文字）
- 包含表格（比較表、證據表、狀態表）
- 包含指向來源的可點擊連結（聊天討論串、GitHub PR、Wiki 頁面）
- 引用主要來源，並以姓名/日期直接標註引述（訊息、PR 內容）
觸發短語："write this up"、"create a doc"、"typst it"、"make a report on this" — 特別是在需要將多來源調查結果（聊天搜尋、GitHub PR 審查、即時系統證據）整合為可分享的成品時。
編譯前，請保留並查閱個人的 Typst 陷阱筆記（例如 ~/notes/typst.md），記錄已知的語法陷阱（註腳位置、#N 衝突、fletcher 導入、表格欄位大小等）— 並在發現新的編譯錯誤類型時補充進去。
關鍵語法規則（編譯前檢查清單）：
- 粗體標記使用單
*word*，絕對不要用**word**：Markdown 雙星號會產生數十個編譯器警告（warning: no text within stars; using multiple consecutive stars has no additional effect）。 - 數學模式中的字串需要引號：在
$ ... $中，多字母標識符如$Count=65$或$RTO$會導致編譯失敗（unknown variable）。請寫成$"Count"=65$或將程式碼放在反引號中（`Count=65`）。 - 數學模式中不要使用 LaTeX 反斜線運算符：撰寫
$\approx$會失敗（unknown variable: pprox）。Typst 使用 bare symbols：$approx$，不加反斜線。
深入內容；節約呈現
兩個影響每份報告的常設指令：
- 深入真正的技術內容。 追求極致的技術深度，而非淺薄摘要 — 更多的原始主控台輸出、更多架構/狀態機圖表、接近硬體時應包含暫存器/位元欄位或數位電路級別的細節、以及接近軟體執行時應包含 CPU 指令/組合語言等級的細節。當草稿寫到 5-6 頁就覺得「完成」時，這是一個訊號，應該再深入一層（多加一個
redis-cli/systemctl/暫存器內容傾印、一張額外的架構圖、一個額外的業界比較角度），而不是就此停手。請參閱下方「深度期望」以了解具體的章節劃分。 - 但在呈現方式上要節約資源，而不是內容。 內容的深度與樣式的資源消耗是兩個不同的軸線 — 深入挖掘事實、證據、圖表，但視覺呈現本身要節省墨水：使用淺色背景 + 有色邊框/文字而非實色填充，且顏色僅在具有意義的地方使用（請參閱下方色彩方案）。節約墨水的原則適用於頁面主體墨水，而非標題區塊 — 標題確實需要加框（請參閱色彩方案第 1 項）。目標是更多頁的真正技術內容，而不是每頁使用更多實心墨水。
工作流程
- 在開始寫作之前，先完整收集所有證據（聊天搜尋、GitHub PR 閱讀、即時指令輸出、問題追蹤器/聊天歷史的相關文章搜尋）— 不要在研究進行到一半時就開始寫
.typ檔案；一次完成綜合整理。 - 使用一或兩次
write/eval呼叫撰寫完整的.typ原始碼，並使用上述的結構模板（帶單引號強調色的加框標題、帶細線的強調色標題、淺色背景的表格表頭、2-4 個根據意義而非新穎性挑選的語意提示區塊、淺色主控台區塊、用於節點圖並包裝在#figure中的 fletcher 圖表，預設無目錄）。如果使用 fletcher，請務必在檔案開頭加上#import "@preview/fletcher:0.5.7": diagram, node, edge— 遺漏這個導入是編譯時最常見的錯誤。 - 編譯：
typst compile file.typ（從檔案所在的目錄執行 — 每次工作階段先執行typst --version確認二進位檔可用；如果使用 fletcher，在將其整合到正式文件之前，先進行一次丟棄式的/tmp測試編譯以確認網路和套件解析正常）。遇到編譯錯誤？在從頭開始除錯之前，先查閱你的陷阱筆記！ - 在宣告完成之前，務必進行視覺驗證 — 將每一頁轉為 PNG（
typst compile --format png --ppi 100 file.typ "page-{p}.png"— 請將輸出模式用引號括起來）並read每個 PNG 以檢查佈局、間距和渲染效果，特別是包含圖表、表格或提示區塊的頁面。具有 3 個以上邊或雙向邊對的圖表需要特別注意標籤重疊問題。 - 然後進行獨立的內容閱讀檢查 — 佈局驗證並非內容驗證。 步驟 4 證明沒有任何東西渲染錯誤；但它並不證明任何東西是真實的。再次
read每個渲染出的頁面，這次是對照原始材料閱讀內文，特別是查找：(a) 手動輸入的章節交叉引用（"參見 §9.1.3"）在插入章節後已失效；(b) 表格儲存格中的宣稱與來源相比是顛倒或錯置的；(c) 非直接來自主要成品而是間接轉錄的數字 — 將這些標記為[INFERENCE]或去驗證它們。實務上已確認必要：一份通過完整佈局檢查的文件仍然包含一個失效的§引用 AND 一個事實錯誤的表格儲存格，兩者都是在閱讀內容時才被發現。一次寫成的 40 KB 文件，僅因為它編譯成功，並不代表它已經過校對。 - 將最終的
.typ和.pdf檔案移至專案的 docs 位置（例如docs/generated/）並一起提交，然後刪除任何中繼的 PNG 檢查檔案 — 將原始碼與編譯後的輸出保存在一起，以便日後可以重新編輯。
使用語意化標記
根據 Typst 自身的無障礙指南：始終使用真實的語意元素（= Heading、#quote(...)、#table(...)），而不是手動樣式化純文字/內文來「看起來像」那個元素（例如 #text(size: 16pt, weight: "bold")[Heading]）。永遠不要發明一套並行的「看起來像標題」的慣例；始終透過真正的標記元素來驅動外觀。
色彩方案
- 正文字體：
New Computer Modern。 基準是「像 LaTeX」— NCM 就是 LaTeX 的字體，並且它隨 Typst 一起提供，所以始終可用。絕對不要選擇機器上未安裝的字體（用typst fonts驗證）：Typst 只會對缺少的字體系列發出警告並靜默回退，因此文件會編譯「成功」但顯示錯誤。如果出現unknown font family警告，這是一個需要修復的缺陷，而不是一個可以容忍的警告。 - 語意提示區塊調色板。 綠色
#1a7f37、黃色#9a6700、紅色#cf222e、藍色#0969da、紫色#6639ba、橙色#bc4c00；主控台/表格色調#f2f6fb/#eaf1fb搭配邊框#9fb8d6/#c8d6e8。行內和區塊raw應使用機器上存在的等寬字體（例如Consolas、JetBrains Mono、Menlo）。
一個結構性強調色，僅用於外框 — 加上用於傳達意義的語意提示區塊。 這是已確定的模式；預設應用它，無需從頭推導：
- 標題區塊：純文字居中加上有邊框的盒子。圍繞標題使用
#box(fill: white, stroke: 1.5pt + accent, ...)。 - 表格表頭：淺色色調背景 + 強調色文字，絕對不要使用實色填充。
- 用於有意義發現的語意提示區塊 — 這是額外顏色值得使用的地方，因為它具有功能性，而非裝飾性。根據內容選擇適合的類型；不必在每篇文件中都全部使用 — 每份報告總共 2-4 個提示區塊是很好的密度，而不是每個段落一個。
- 已驗證（綠色勾號）— 確認良好的發現，一行。
- 異常（黃色驚嘆號）— 預期之外但尚未確認是否為缺陷。
- 確認缺陷（紅色叉號）— 確認不良的發現，一行。
- 備註（藍色資訊）— 一個值得強調的非關鍵觀察。
- 提示（紫色燈泡）— 一個有幫助的建議或最佳實踐。
- 待解決問題（橙色問號）— 一個真正的未解決歧異或疑問。
- 根據文件/章節變化色調，以助於列印易讀性。
- 圖表方塊顏色保持角色/語意基礎。
- 任何地方都不要有大面積的深色實色填充（例如帶白色文字的深藍色橫幅）。章節標題：有色文字 + 下方一條細的有色線條，而不是有色填充的色塊或方塊。
- 主控台/程式碼輸出區塊：淺色調背景，而非灰色。 平淡的
#f4f4f4灰色讀起來感覺枯燥/像影印機。使用帶有微妙搭配邊框的淺色調。 - 章節之間絕對不要使用
#pagebreak()。 在每個=標題之前換頁，會導致每章留下半頁空白紙張，並在列印時浪費真正的紙張。讓章節自然流動；章節從頁面中間開始是正確的。唯一可接受的#pagebreak()是分開封面頁與正文的那一個。
兩個預設章節 — 無需提示即包含它們
- 競爭 / 產業背景。 競爭方案如何解決這個問題，而這個架構位置結構上買了什麼和付出了什麼代價？將每個優勢都框定為一個對應的可測試風險。除非來自真正的競爭性文件，否則將該章節標記為一般產業知識
[INFERENCE]。 - 自動化 / 測試機制，具體說明。 確切的呼叫方式、執行主機、虛擬環境和鎖定的依賴套件、篩選器選擇，以及如何解讀 collected vs deselected vs executed 的計數。"存在一套測試套件" 並不算是覆蓋率。
圖表放置：將圖表/表格包裝在 #figure(...) 中，讓 Typst 自動浮動它們
根據 Typst 自身的佈局指南，圖表預設放置在內容流中的內聯位置，但將圖表或表格包裝在 #figure(..., caption: [...]) 中，可以解鎖 placement: top/placement: bottom，讓 Typst 將其浮動到頁面頂部或底部，而不是尷尬地在段落中間分割內容。始終為圖表提供帶有真實標題（caption）的 #figure(...) 包裝（永遠不要在內文中使用裸露的 #diagram(...) 呼叫）— 這也使得圖表可以透過 @sec-label 進行交叉引用，並為螢幕閱讀器和內容再利用工具提供適當的語意化圖表+標題配對，而不僅僅是一個無標籤的圖像。
使用 Fletcher 繪製節點/邊線圖
工作模式，已確認編譯和渲染正確（根據上述放置指南，包裝在 #figure 中）。記得導入（請參閱工作流程步驟 2）— 此程式碼片段假定它已經在檔案頂部：
#figure(
diagram(
node-stroke: 0.6pt,
spacing: (3em, 2em),
node((0,0), [Step 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
node((0,1), [Step 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
edge((0,0), (0,1), "-|>", bend: 10deg),
edge((0,1), (0,0), "-|>", bend: 10deg),
),
caption: [一行說明，解釋兩個方向/邊，因為此處省略了內聯標籤。],
)
座標是 (column, row) 元組；node-stroke/fill/corner-radius 用於設定個別節點樣式；edge(from, to, "-|>") 繪製箭頭（標記字串，而非關鍵字引數，用於選擇箭頭形狀 — "-|>" 和 "->" 都有效；"..|>" 用於虛線箭頭）。多個獨立的線路可以使用不同的欄索引共用一個 diagram(...) 呼叫，並為每個線路加上一個 stroke: none 的標題行節點。邊線標籤保持一個短詞/短語，並將完整解釋移到 figure 的 caption 中 — 超過一個單詞的內聯邊線標籤是典型的標籤重疊失敗原因。
深度期望：預設為長篇、深度極客風格，而非摘要
除非明確要求簡短，否則目標是10-12 頁渲染輸出，用於完整的調查報告 — 一份簡短、正確但內容薄弱的報告是一種失敗模式，而非高效產出。具體而言，「深入」意味著，在主旨允許的情況下，包含：
- 完整原始的主控台/日誌輸出，而非截斷的程式片段 — 每個來自即時系統證據的宣稱，都應附上實際指令 + 實際輸出的逐字內容。
- 至少一張架構圖或狀態機圖表（透過 fletcher，見上文）顯示各個部分實際上是如何連接的，而不僅僅是文字描述。
- 加入暫存器/位元欄位或數位電路級別的細節，當主題接近硬體時（例如，特定組態暫存器的位元佈局、訊號時序圖、ASIC 區塊的連接埠對應表、從實際驅動程式原始碼中提取的真實結構體/操作碼定義）— 不要停留在「硬體做了 X」，要展示實際的機制。
- 加入 CPU 指令/組合語言或系統呼叫級別的細節，當主題接近軟體執行時（例如，驅動程式實際上發出了哪個系統呼叫、熱路徑的反組譯看起來如何）— 不要停留在「驅動程式做了 X」，要展示實際的程式碼路徑。
- 一個專門的「產業/外部背景」章節（見下文）— 永遠不要孤立地呈現內部機制。
- 真正的前置研究成果/歷史搜尋 — 檢查問題追蹤器、聊天歷史和 git 歷史，看看之前是否曾問過完全相同的問題（即使是幾年前）；一份解決了存在多年舊問題的報告，比一份將發現當作全新問題來處理的報告更強而有力。
結構：(1) 標題 + 摘要、(2) 背景、(3) 證據時間軸/方法論 — 每個不同的發現一個子章節，並附帶自己的引用證據區塊，通常是最長的章節、(4) 如果主題名稱與其他事物重疊，則加入消歧義章節、(5) 比較表、(6) 產業/外部背景、(7) 架構/綜合整理，以編號的端到端列表形式呈現，並搭配圖表、(8) 待解決問題，附上具體的後續行動、(9) 與原始調查的關聯、(10) 附錄，包含從正文中刪除的完整原始證據。當草稿感覺完成了但篇幅很短時，再做一輪實際的調查（另一次線上身分檢查、另一次暫存器傾印、另一次網路搜尋、另一張圖表、另一次歷史搜尋以尋找先前技術），而不是填充現有的文字 — 深度必須來自真實內容，永遠不要依靠文字拉長。