Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

繁體中文 | 简体中文 | English

awesome-agentic-ai-zh 風格指南

這份指南是這份 catalog 的單一真實來源——術語、entry 結構、license 標註、寫作風格、禁用詞,全部以這份文件為準。

PR 之前請先讀完本文。專案維護者也會用這份指南做 review。


📋 目錄


1. 專案 entry schema

每個 project entry 統一格式如下:

### [Repo Name](https://github.com/owner/repo) ⭐⭐⭐⭐

| 欄位 | 內容 |
|---|---|
| 語言 | Python |
| License | MIT |
| 推薦度 | ⭐⭐⭐⭐ |

**教什麼**:1-2 句話,這個 project 在這個 stage 教什麼具體的東西。

**適合誰**:1 句話,誰應該讀這個、為什麼。

**備註**:1-3 句個人評價。哪裡好、哪裡弱、哪裡可以跳。(可省略)

**怎麼跑**:
\`\`\`bash
# 最小安裝指令、第一次跑該執行什麼
\`\`\`

必填欄位(GitHub repo entry)

對「真實 GitHub repo」的 entry:

  • License(SPDX ID 或標註例外,見 5)
  • 推薦度(⭐ × N,見 2)
  • 教什麼、適合誰

必填欄位(非 repo entry:article / course / video / protocol / documentation)

某些 entry 不是 GitHub repo 而是文章、影片、官方文件、catalog hub。對這類:

  • 推薦度(必填)
  • 教什麼、適合誰(必填)
  • 形式(必填,標明是 文章 / 影片 / 課程 / 精選清單 / 規格文件 等)

範例:Anthropic — Building Effective Agents 部落格文章用 形式 = 文章 + 推薦度,不需要 repo 的 License 欄位。

全站資源選擇規則

推薦度是每筆 entry 必填的編輯判斷。

  • 用現行官方文件、規格與 model card 查證事實。
  • 新收錄的第三方 GitHub repo 在查核當下至少要有 1,000 stars,再用知名或廣泛使用、可實作的 repo,給讀者一條動手的路。供應商官方文件、標準規格、model card 與不可替代的 canonical source 不是第三方 repo,不套這個門檻。
  • 1,000 stars 只是收錄門檻,不是品質分數;它不能取代維護、License、安全、相關性與教學價值檢查。頁面仍不保存會漂移的 stars 數字。
  • 每個 project 都要說明它教什麼、適合誰,以及目前狀態或限制。

選填欄位

  • 語言 — 主要程式語言(Python / TypeScript / 中文 等)
  • 最後更新 / 狀態 — 已停滯或維護放緩時加註
  • 備註、怎麼跑

標題格式

  • Stage 1-4 / 6 用 ### [Repo](url)
  • Stage 5 / 7 / branches 用 #### [Repo](url)(已有上層 H3 分類時)
  • 標題後可接星等:### [Repo](url) ⭐⭐⭐⭐⭐ 或副標:### [Repo](url) ⭐ 官方

2. 推薦星等定義

星等含義何時用
⭐⭐⭐⭐⭐必讀 / 必做該 stage 不讀這個會卡住
⭐⭐⭐⭐強烈建議深入學該主題的好材料
⭐⭐⭐紮實範例值得跑一遍、互相對照
⭐⭐有用參考有興趣再看
⭐利基 / 進階 / 為了完整性多數讀者可跳

這是編輯評分,不是 GitHub stars。只有資源用途、品質或維護狀態的查證結果改變時,才能連同理由調整評分。

準則:

  • 同一個 repo 出現在不同 stage / branch 時,星等應一致(除非有明確 audience-specific 理由,且註明在備註)
  • 不要因為「想要看起來推薦」就給高星等。誠實 > 客氣
  • 商業產品(Cursor、LangSmith 等)也照同一套標準

3. 禁用詞與替代

這份文件以繁體中文(zh-TW,台灣慣例) 為準。下表列出常見的 zh-Hans 用詞與替代。

📌 語言代碼慣例(BCP 47 / W3C i18n):repo 用 .zh-Hans.md(不是 .zh-CN.md)標記簡體中文檔。Hans / Hant 是 BCP 47 script subtag,跟地區解耦——簡體中文不只用在中國大陸(也用在新加坡、馬來西亞),用 Hans 比 CN 更準確。canonical README 的內容是 zh-Hant-TW(繁體中文,台灣慣例),但檔名保持無 suffix 的 README.md 作為 GitHub 預設首頁。未來若要分地區可再擴成 zh-Hans-CN / zh-Hant-HK 等。感謝 @xfq(W3C i18n lead)在 #9 指出這個問題。

繁簡用詞替換

禁用(zh-Hans)改用(zh-TW)
教程教學 / 課程 / 導讀
視頻影片
軟件軟體
文件(指 file 時)檔案
文档 / 文件(指 docs 時)文件 / 文件(這個保留)
代碼程式碼 / 原始碼
用戶使用者
網絡網路
接口介面
默認預設
函数函式
算法演算法
程序(指程式時)程式
質量(指品質時)品質
信息資訊
數據資料
內存記憶體

Overclaim(誇大)用語禁用

禁用改用
全世界最好的 / 業界最強完整的 / 知名的 / 廣泛使用的
production-grade(描述教材時)教學導向 / 用來學 production pattern 的教材
首選 / 唯一選擇不錯的選項 / 入門選擇之一
最緊迫 / 最重要(直接不要修飾)
權威參考(除非真的是官方 spec)重要參考實作 / 官方範本
沒問題(法律或 license 判斷時)使用前先讀條款 / 條款還是要自己看過

中夾英(English-in-Chinese)禁用句型

禁用改用
follow 條款遵守條款
ready-made 教材現成可改的教材
Gemini Notebook-like 工具類 Gemini Notebook 的工具 / 類似 Gemini Notebook 的工具
視覺化 node-based視覺化節點式
Anthropic host 的 serverAnthropic 維護的 server
coding 流程開發流程 / 程式開發流程

4. 可保留的英文名詞

技術寫作中保留英文比硬翻譯讀起來更自然的詞:

  • LLM、API、SDK、MCP
  • agent、tool use、function calling、prompt、prompt caching
  • framework、library、repo、commit、PR、branch
  • RAG、embedding、vector DB、retrieval、chunk、token
  • streaming、async、batch、webhook
  • marketplace、plugin、skill、hook
  • project、repo (可保留也可改用「專案」)
  • production(指「正式環境」時)— 但本 catalog 多數場合刻意避免(見 3)
  • 動手練習、hello-world — 保留

判準:技術文件圈讀者習慣的英文術語就保留,避免「太政治正確的中文化」。


5. License 標註慣例

常見 license 直寫

  • MIT
  • Apache-2.0
  • BSD-3-Clause
  • GPL-3.0
  • LGPL-3.0

需要加註的特殊情況

情況寫法
上游無 SPDXNOASSERTION(上游未提供 SPDX;使用前請讀 LICENSE)
AGPL(傳染性)AGPL-3.0 + 備註:AGPL-3.0 license(傳染性開源)— 修改後散布的衍生產品需遵守條款。
自訂非商用NOASSERTION(自訂非商用) + 備註:License 是自訂非商用條款,使用前請先讀原始條款。
多元 license(每個 plugin 自己有)NOASSERTION(每個 plugin 獨立 license,請看各自目錄)
Creative Commons直寫 CC-BY-4.0、CC-BY-NC-SA-4.0 等

規則:永遠不要把 license 解讀成法律建議。「研究 / 個人使用沒問題」這種句子禁用。改成「使用前先讀原始條款」。


6. Stage 頁面模板

同一個模板適用於兩個位置:

  • stages/0X-*.md — 共用基礎(0-2)+ Track B(Stage 3-8)
  • tracks/cli/AX-*.md — Track A(A1-A3)的 sub-stage,也照同一模板,只是 cross-link 比例較高(多數 entry 引用既有 Stage 5 / 7 / cli-agents-guide)

每個 stage(Stage 0 除外)都應該有:

# Stage N — 主題

> [English](./0N-slug.en.md) | **繁體中文**

[1-2 句話描述這個 stage 的核心問題]

## 📌 學習目標
- bullet 1
- bullet 2
...

## 🧩 先認識核心詞

### **正確術語(需要時附中文)**
一句白話定義。再給一個不會扭曲概念的生活比喻,並說明後面的哪個練習會用到它。

## 🚪 進入條件(Stage 1+ 才需要)
<details markdown="1">
<summary>⏱ 開始前先看:時間、先備工具與預算</summary>

**時間估算**:N-M 週(約 X-Y 小時)

你應該已經:
- ...

</details>

## 📚 必修閱讀
先列出 1–3 個完成眼前練習真的會用到的來源。這些連結保持可見,不能只藏在收合區。

1. [必要連結](url) — 會在哪一步用到
2. ...

<details markdown="1">
<summary>展開:完整閱讀順序與延伸來源</summary>

1. [延伸連結](url) — 描述
2. ...

</details>

## 🛠 動手練習(不是看過就好)

### 練習 N:標題
一句話描述完成後會看到什麼。標題留在 details 外,讓深連結可見。

<details markdown="1">
<summary>展開詳細步驟</summary>

時間、費用、程式碼、預期輸出與疑難排解。

</details>

可執行資料夾必須先提供可直接複製的 PowerShell 指令,再用預設收合的 `<details>` 提供 macOS/Linux 替代指令;同時提供 Path A 與 Path B 腳本,以及不打 API 的 offline mock tests。SDK 依賴要限制 major version,cloud model 要使用釘住的 model ID;執行前必須驗證不受信任的工具名稱與參數。Cloud 成本寫成 token 公式並標示核對日期,不要假設一個固定金額。不同 framework 的範例各自建立 Python 3.11 `.venv`,不要合併 requirements。測試必須走過核心行為;只驗 import 成功不算通過。

[3-5 個動手練習 items]

## 🎯 精選 Projects

### [Project Name](url) ⭐⭐⭐⭐
[entry schema 見 1]

[N 個 entries]

## ✅ 進 Stage N+1 前的自我檢查
你能不能:

- [ ] ...
- [ ] ...

如果可以 → 進 Stage N+1。
如果不行 → ...

## 💡 接下來(選填,多在最後一個 stage 用)

練習標題、成果和第一步保持可見。次要 <details> 預設不加 open。雙路徑練習仍以 Ollama Path A 為主要路徑,但不是看到 Path A 就一律展開:只有它是讀者眼前唯一要做的事,而且展開後內容很短時才可加 open。長程式碼與疑難排解預設收合;Anthropic Path B 也預設收合。不要把可被連結的 heading 包進 <details>,也不要用三層以上的巢狀收合。

若一個進階主題已大到有自己的必讀、核心詞、練習與精選資源表,建立可獨立閱讀的三語頁面,不要把整章塞進 Stage 的長 <details>。Stage overview 必須提供可見入口;獨立頁的頁首與頁尾都要回到同語言 Stage。被搬出的重要名詞、必讀與五星資源仍直接可見,只有安裝、成本、替代方案與排錯收合。舊深連結留在語意相符的可見 gateway,不能讓 anchor 落入關閉內容。

全站白話規則(ELI5)

這份規則適用整個學習地圖。目標是讓五歲小孩也能跟得上「現在要做什麼」,但不能犧牲技術正確性。

  • 技術詞第一次出現在可見教學文字時,要用粗體標出;接著先說白話用途,再保留正確術語。例如:「讓程式拿資料的入口(API)」。H1 可以直接使用章名,但正文第一次使用仍要套用這條規則。
  • 一句只講一件事,一個步驟只要求一個主要動作。看見長句、縮寫或 jargon,先拆開或補一句定義。
  • 指令、檔名、錯誤碼、模型名稱、價格、數字與安全提醒必須保持精確。
  • 不展開任何 <details> 時,讀者仍要知道下一步要做什麼,以及完成時會看到什麼。
  • Review 時抽查可見主線:第一次來的讀者若無法用自己的話說出下一步,就先改寫;需要多段的原理移入預設收合內容。

核心詞寫法

  • 每個完成回溯的 Stage/Track,都要在第一個練習前放一個可見核心詞區。核心詞名稱與最短解釋不能放進 <details>。
  • 每個核心詞獨立回答四件事:它是什麼、它像什麼、這章用它做什麼、正確術語是什麼。需要更深原理時,再把補充放進預設收合區。
  • 新建頁面或輪到該章進行閱讀體驗重整時,若核心詞有四個以上,或能分成兩組以上,不要堆成長串小標題。改用一張保持展開的 HTML 表格,欄位固定回答「先處理什麼/正式核心詞/白話說法/本章用途與技術界線」。同一組用獨立 <tbody> 和真正的 <th scope="rowgroup" rowspan="N"> 合併;詳細限制可在表格後補充,但不可再複製一份同內容的速記清單。尚未輪到重整的既有頁面依 stacked PR 順序遷移,不因新增本規則而一次改寫全站。
  • 只收後文、練習或 self-check 真的會用到的關鍵概念。不要把每個普通名詞拉出來湊數,也不能用「太細」當理由刪掉 Zero-Shot、Token、MCP 等必要術語。
  • 三語的概念、順序、用途與限制一致;英文名、縮寫、指令與規格名稱保持精確。
  • scripts/reader-ux-pages.yml 的 core_terms 會記錄核心區、第一個練習、三語 term/label、順序與最低解釋長度。加入後只能維持或加強,不能靜默移除。

概念圖寫法

  • 先在正文用白話定義核心詞,再用圖整理它們的關係;不要讓圖成為讀者第一次遇到術語的地方。
  • 預設參考主頁 README:奶油白底、深藍主字、少量亮色、圓角卡、簡單線條 icon、充足留白與一個主要閱讀方向。每張圖只回答一個核心問題;資訊太多時拆成兩張,不縮字硬塞。
  • 新畫或重畫的概念圖優先以現行 GPT-Image-2.5 Sunburst 產出 PNG,不用臨時 SVG 代替;若執行工具沒有暴露可選 model ID,就只能記錄「使用目前內建 image generation」,不能假稱指定了 Sunburst。舊圖輪到該章重畫時才套用,不一次改壞全站歷史。
  • 頂部 Banner 試版例外:明確核准的 README banner 使用自包含動畫 SVG,內嵌各語言的原版插圖,不重畫構圖、字體、圖示或配色。三語共用路線順序與 18 秒時間軸,光點依各自原圖接線移動、節點外框短暫加亮。原版代表性圖示也要有意義地動:CLI 游標輸入、工具輕轉、Hub 箭頭旋轉、清單確認及角色回饋;13 個裁切區域重用原圖,不另換圖示,文字與卡片不動。A、B 依序動,最後 2 秒完全靜止。內嵌原圖使用高品質壓縮,同版 PNG 提供靜態、減少動態與 PDF 使用;文件站有停止/播放控制,README 有靜態圖入口。SVG 不含 JavaScript 或外部資源,不轉 GIF,不提高容量上限;其他教學圖仍依上面的 PNG 規則。
  • 三語圖保持同一畫布比例、構圖、共同格線、順序、數字與限制,並各自提供正確語系的圖檔與 alt text。卡片位置、外距、內距與同層高度要一致。
  • 圖裡的精確數字也要有官方依據。沒有固定通則時,寫「多個」「依模型而異」等誠實文字,不要為了好看造出範圍。
  • 箭頭只走留白通道,不穿過文字、icon 或其他卡片;arrowhead、icon、標籤與框線不得互相重疊。同層卡片使用共同格線、等高與一致內距。
  • 逐張以原尺寸檢查安全邊界、文字、繁簡字形、箭頭、共同格線與對比;任何文字、icon、箭頭或框線重疊都視為失敗。最後跑 image-locale gate 與三語 MkDocs build。
  • 角色圖試版例外:使用者核准 branch-decision-tree 沿用原畫加入五個代表性圖示的小動作,一次只動一個角色,文字、卡片、接線固定。18 秒循環的最後 2 秒靜止;三語沿用各自原畫布,不另換圖示或重排文字。保留靜態 PNG、PDF、減少動態與停止/播放控制,仍用 lazy loading。此試版不表示原圖三語文字已重新核對:採用前須校正舊英文角色名稱等差異;其他圖仍用 PNG,舊學習地圖先修內容再做動畫。
  • 文件站會自動替非首屏教學圖加入 lazy loading、async decoding 與可鍵盤操作的「開啟原圖」入口;README 頂端 banner 保持 eager,不要在各章重複手寫這些 HTML。新增或替換圖檔要通過 scripts/check-image-delivery.py 的單圖、單頁、總量與建置後 HTML ratchet,並以 320/375/768/1440 px 人工確認 caption、表格、觸控目標與圖中文字真的讀得到。

Eval 教學寫法

  • 初次解釋 Eval 時,先說清楚 Outcome(要得到的結果),再依序介紹 Eval Case、Eval Suite、Reviewed Eval Set。只有讀者看懂這三層後,才補充 Golden Set/Reference Set 等外部常見叫法。
  • 一個 Eval Case 不是只有輸入。完整案例至少要交代輸入、初始狀態、成功條件、禁止行為、選用的參考答案、grader 與 case metadata;沒有參考答案時,也要能靠明確條件判斷結果。
  • Reviewed Eval Set 是本專案的主要教學名稱,表示一組已由人檢查、可重複使用的完整案例。Golden Set/Reference Set 的實際意思會依團隊而異;第一次出現時要說明它在當前來源裡指什麼,不能直接當成跨供應商標準。
  • Golden/Reference Set 用來檢查系統,不只是 input,也不等於訓練資料或 Few-shot 範例。圖中要把 input 畫成完整案例的一部分。
  • 再依需要補充 Trial、Grader、Baseline、Regression、Development Set、Holdout Set。每個詞先用白話說用途,再保留正式術語;重要定義、圖、完成條件與學習資源保持可見。
  • Development/reference cases 用來反覆改進;frozen holdout 只在 release candidate 或最後驗證時使用。報告至少寫 dataset version、split、case ID、trial 次數、grader、Outcome/Trajectory 與 baseline。
  • 能精確判斷就先用 deterministic grader;模型或人工 grader 必須附 rubric 與版本。Regression 要依多次 trials、預先定義的門檻與失敗案例判斷,不把單次隨機波動寫成必然退步。

Reader UX ratchet

  • 章節完成三語遷移與人工複查後,才加入 scripts/reader-ux-pages.yml。這是逐章收緊,不要求尚未整理的頁面一次全部通過。
  • scripts/check-reader-ux.py 使用保守的 source-level proxy,計算第一次開頁時可見 Markdown 的非空白字元。預設展開內容與可見 fenced code 算入;HTML comment 與收合內容不算。這是可重複的 ratchet,不是瀏覽器 DOM 字數。
  • 設定檔會保存三語各自的字數上限、允許預設展開的數量、必須保持可見的精確 heading/anchor、核心詞契約,以及資源表的分組列數。沒有重新審查,不得調高上限或刪除保護項目。
  • 自動 gate 只能防止已知結構倒退。人工 review 仍要確認:不展開任何選單時,讀者知道要做什麼,也知道成功會看到什麼。

分組資源表

  • 同一分類連續出現兩列以上時,改用 HTML <table>,並以 <th scope="rowgroup" rowspan="N"> 合併分類欄。
  • 每個 <thead> 欄位標題 <th> 都要加 scope="col"。
  • 每個分類使用一個獨立的 <tbody>;分類的第一列保留 <th scope="rowgroup" rowspan="N">。
  • 只合併真正共用的分類。不同分類不可因狀態、Context 或其他文字剛好相同而跨組合併。
  • 轉換後保留原有資源數量、順序、連結與三語對應,並用 MkDocs 檢查實際渲染。
  • 沒有重複分類的短表格繼續使用 Markdown,避免為了格式增加維護成本。

含模型、價格、context、授權或生命週期狀態的頁面,把可見查核日期用小字放在受影響的表格或段落附近。只有該內容本身是補充資料時,日期才跟著收合;頁首只保留不顯示的機器 marker:

<small>資料查核:YYYY-MM-DD UTC</small>

<!-- freshness: canonical=stages/0N-slug.md; verified_on=YYYY-MM-DD; scope=models,pricing,availability,deprecations; max_age_days=90 -->

日期只寫查核範圍與日期,不重複加入「資料不會永久正確」等通用提醒。三語 marker 必須完全一致;canonical 一律指向繁中主頁。官方沒有公布的欄位寫「官方未公布」,不要從第三方榜單反推;第三方 benchmark 只能教讀者怎麼自己評測。

Stage 0 例外:可以省略 精選 Projects、進入條件,因為它是 prerequisite gateway。可見主線依序保留 skip 判斷、4 個學習目標、1 個整合練習、18 筆五星學習資源與短版完成檢查;時間、環境、補充練習與名詞預設收合。


7. Branch 頁面模板

# 給 [audience] — 專業分支

> [English](./for-X.en.md) | **繁體中文**

> [← 回主路線 README](../README.md) · 從 Stage 7 結尾分支出來

## 使用情境
- bullet 1
- bullet 2

## 精選 Projects

### 子分類 1
#### [Project](url) ⭐⭐⭐⭐
[entry]

### 子分類 2
...

## 必修閱讀
1. ...

## 必練流程
- bullet 1
- bullet 2

Branch 的 entry 格式可以比 stage 簡潔(不一定要完整 schema 表格),但連結 + 星等 + 1-2 句描述是最低門檻。


8. 寫作風格規範

句長

  • 單句不超過 60 字(中文標點計入)
  • 太長就斷成兩句
  • 英文 rhythm 強迫塞進中文 = 翻譯腔,要避免

標點

  • 中文用全形:,。:;「」()
  • 句中夾英文時,英文前後可以留空格也可以不留,但全文要一致
  • 避免 ASCII 逗號 , 在中文句中(會中夾英)

主動 vs 被動

  • 偏好主動句:「Claude 呼叫工具」 ✓
  • 避免被動句:「工具被 Claude 呼叫」 ✗

「你」 vs 「我們」

  • 「你」優先——這是給讀者的學習材料
  • 「我」用於作者發表意見時:「我建議...」
  • 避免「我們」(除了合著者實際存在的場合)

連接詞

  • 偏好簡單:「但、所以、因為、不過」
  • 避免:「然而、因此、由於、之所以」

9. 連結與引用

角色路線頁

完成回溯並加入 scripts/reader-ux-pages.yml 的角色頁,三語都保留可見主線 📌 → 🎯 → 🧩 → 🛠 → 📚 → ✅:先說這條路解決什麼,再列學習目標、粗體核心詞、可直接複製的小任務、入口與完成檢查。先用白話定義核心詞,再保留正確英文術語;不能因為簡化而刪除後文會用到的技術詞。

第一個任務必須小、可測、可回復。若任務會改檔案,要明寫 read-only plan、人工批准、diff、test、rollback,以及 agent 不得自行 push/merge/deploy。必修閱讀、精選專案、完整五星學習資源與安全警告保持可見;替代方案、費用、進階流程與排錯才放進預設關閉的 <details markdown="1">。專門的大型 catalog 可讓每個分類入口與安全邊界可見,再讓讀者按分類展開其中上百筆項目。既有深連結的空 anchor 放在語意相符的新 heading 或 summary 旁,並保留可見的回主路線連結。

工具的核心身分和 surface 分開寫。IDE、CLI、desktop、cloud、CI、SDK 可以同時出現,不能當成互斥分類。OpenRouter 是 Provider/Router,Ollama 是 Model/Runtime,coding agent/harness 是另一個身分軸。

角色頁的分組資源表遵守上面的 rowspan 規則。三語須保留相同 URL 順序、狀態、授權、限制與穩定的編輯評分(⭐⭐⭐–⭐⭐⭐⭐⭐);不寫易變的 GitHub stars。ELI5 白話仍須保留等價語意、技術名詞與安全限制。

Cookbook

Cookbook 的用途、選擇表、核心詞、六份 recipe 標題、成果、第一個可複製動作、必修閱讀、精選資源與完成檢查保持可見;九個完整步驟/替代方案/排錯區塊預設收合且不加 open。每個核心詞第一次出現就用粗體白話定義,不能把可執行命令或產品名稱翻成另一個東西。

完整資源表固定使用六個獨立 <tbody>,以 scope="rowgroup" 和 rowspan 合併分類欄。三語的 URL、命令、日期、授權、安全限制與編輯評分一致;社群整合明標非官方、可能失效與官方 fallback。易變事實附查核日期,但不加入「永遠最新」之類的保證。

Resources 工具櫃入口

resources/README* 先問讀者卡在哪裡,再用粗體白話定義 Reference、Guide、Cookbook、Catalog 與 Glossary。12 份 reference 的入口、用途、限制與回主線連結保持可見;只有分檔理由與 maintainer 規則收合。不要加會漂移的行數、GitHub stars 或把舊產品名稱寫成現行名稱。

完整入口表固定使用五個獨立 <tbody>,分類列數為 4/2/3/2/1。同類型只在第一列出現一次,使用 scope="rowgroup" 與真正 rowspan;不可用重複文字或空白儲存格假裝合併。三語檔名依 locale 指向自己的 mirror,順序與語意一致。

Glossary 查字入口

Glossary 的快速地圖、工具身分表、每個詞的 heading 與一句白話定義保持可見;不能把最短答案藏進 <details>。只有 maintainer 完整分類表、來源與查核說明預設收合。第一次出現的核心詞照全站規則用粗體標出,並保留正確英文術語。

工具身分表要直接分清 Provider API、Router、Model Runtime、Coding Agent/Agent Harness 與 Agent Framework。型號、價格、context、固定 token 換算等易變快照不要複製到 Glossary;改連到有 freshness gate 的章節或官方文件。

內部連結

  • Stage 之間:相對路徑 [Stage 4](04-agent-frameworks.md)
  • Branch ↔ README:[← 回主路線](../README.md)
  • 跨 stage 引用同一 repo:用全名 + 連結,不要只寫「之前提過」

外部連結

  • GitHub repo:https://github.com/owner/repo ✓ 不加 trailing slash
  • 文章 / 部落格:完整 URL,標題用粗體
  • 商業產品(Cursor、Make.com 等):用官方網址,不是 affiliate
  • 正文第一次提到 repo、規格或官方工具時,就加上超連結;不要讓初學者看到裸露的 owner/repo 後還要自己搜尋。完整資源表再補狀態、授權、限制與評分。

連結文字慣例

  • Repo entry 標題:[owner/repo](url) 或 [Project Name](url)
  • 句中引用:[Repo Name](url) 或 \owner/repo``(短引用用 inline code)
  • 連結文字避免「點這裡」、「按這個」

相關內部設計文件

這份 style-guide 講「entry 怎麼寫」。為什麼分這 5 個 branch、為什麼是 8 個 stage 這類設計理由,見:

修改本指南

這份指南本身也歡迎 PR。修改前請先開 Issue 討論——術語決策會影響三語的許多 entry。

當前 maintainer:@WenyuChiou。