貢獻者百科

社群協作久了會累積許多不成文規定：標題該如何下、檔名如何命名、PR 描述要寫什麼、Issue 如何分類、新貢獻者第一週會碰到的疑問。貢獻者百科把散落在 README、Issue 留言、Matrix 對話裡的內容整合成一頁，方便新成員一次看完，也讓資深成員有共同對話的依據。

如果你是第一次參與，建議先看 如何參與與認領主題 決定方向，再回來這頁查具體做法。完整的工具入口與帳號申請見 社群自架服務。

第一週的入門路徑

依「我想做什麼」分流：

• 想試水溫，先看看內容：先讀 基礎概念 任一篇，再用 自我技能評估表 評估自己對 Tor、Tails、OONI 的熟悉度
• 想開始寫作或翻譯：申請 Matrix 帳號（見 社群自架服務）→ 加入 Public Space → 表達意願 → 認領一個 Issue
• 想參與技術維運：申請 GitHub 對 anoni-net/docs 的協作權限 → 看 專案研究預先準備 建好開發環境
• 想加入活動籌備：到 Matrix 對應 room 詢問近期活動（COSCUP、工作坊、小聚），協助文宣、現場、報名等任務

每條路徑的第一步都是「進到 Matrix 表達意願」。社群運作偏向 async，留訊息後等一兩天回覆是正常節奏。

寫作風格規範

套用範圍

規範適用於 docs/ 底下三個語系的文件內容，也適用於 repo 自己的說明文件：根目錄的 README.md、CONTRIBUTING.md、AGENTS.md、CLAUDE.md、NOTICE，以及各子目錄的 README.md。讀者會從那些檔案認識專案，寫法跟站上的文件同一套。

CI 的 docs-style-lint 只在 docs/zh-TW、docs/zh-CN、docs/en 的 Markdown 變更時觸發。說明文件改完需要自己執行一次：

python3 tools/docs_style_lint.py README.md CONTRIBUTING.md

NOTICE 沒有 .md 副檔名，linter 只收 .md 與 .js，那一份要人工看。

有一組規則明文豁免既有內容，目前只有下方「標題句構」的 title-colon。CI 傳 --changed-since <base>，讓這組規則只在這個 PR 真的動過的行上報。本機想看整個檔案的全貌就不要帶那個旗標：

python3 tools/docs_style_lint.py --changed-since origin/main docs/en/tools/vpn-guide.md

沒有這個機制的話，改一行圖片引用就會帶出整篇舊標題的 annotation，跟作者的改動無關，而真正該修的那幾條會被淹在裡面。

規則文件本身逐條寫出被禁用的標點與句型，掃自己的規則描述必然全紅。這份百科與工作區的投影檔靠 linter 的 RULE_DOCS 依檔名豁免，tools/README.md 的規則表與已知邊界兩段用 <!-- docs-style-lint: disable --> 與 enable 包住。寫規則說明時照同一個做法，引用的例子要保持原樣。

禁用句型與標點

• 不使用 ——（雙破折號）作為句中插入語。需要補充說明時，改用冒號、逗號，或拆成兩句
  • 引用或照錄的內容不在此限：連結文字是外部來源的原始標題時保留原樣（例 [Developer mode — apps...](url)）。英文版（docs/en）的破折號屬正常英文排版，也不適用此規則
• 不使用「不是...而是...」、「不再只是...而是...」句型。改用正向直述。省略「而」、靠逗號銜接的「不是甲，是乙」也算同一個句型
• 避免用「；」斷句，優先用「。」或拆句
• 並列詞語或短語請用「、」，不要用全形「／」當列舉符號（半形 / 用在路徑、URL、技術慣用寫法）
• 中文句子裡的逗號用全形「，」。半形 , 只留給英文、程式碼、URL 與數字，中英混排時最容易誤打
  • 例：在台灣架設 Tor WebTunnel 橋接,把流量偽裝成 HTTPS 改成 在台灣架設 Tor WebTunnel 橋接，把流量偽裝成 HTTPS
• 補充說明或指引看哪裡的短資訊，邏輯上依附前一句時，用括號內嵌，不獨立成句
  • 例：也有 Etherpad 做即時共筆、Matrix 做即時討論。三者分工見社群自架服務。 改成 也有 Etherpad 做即時共筆、Matrix 做即時討論（三者分工見社群自架服務）。
• 不使用「評語 + 冒號 + 具體展開」的鋪墊句型，例如「想做的事情很具體：」、「最重要的是：」、「答案很簡單：」。把評語刪掉，直接寫具體的事。冒號用來帶出列表、引述對話或當簡單標籤（方式：用 Matrix）不在此限
  • 例：社群這半年想做的事情很具體：把架設校園節點的過程整理成文件 改成 社群這半年想把架設校園節點的過程整理成文件
• 指示詞、引號內容、抽象名詞不要疊成一個名詞片語，例如「把那段「A、B、C」的經驗」。先給一個總稱，再用頓號接引號內容
  • 例：把那段「跟學校溝通、走 TANet 行政流程、技術部署、長期維運」的經驗整理成文件 改成 把這段過程、「跟學校溝通、走 TANet 行政流程、技術部署、長期維運」的經驗整理成文件
• 不使用「結論。說明」的句型，也就是先用一句話下判斷、句號收尾，接著才解釋。把判斷併進完整的句子，用逗號接下去。粗體的版本（**一句話。** 內文）由 bold-lead-sentence 規則攔得到，沒有粗體的版本要人工看
  • 例：小工具區的起點是照片的 metadata。線上的清除工具幾乎都需要先上傳檔案 改成 小工具區從照片的 metadata 開始，線上的清除工具幾乎都需要先上傳檔案
• 不用序數接力的修辭，例如「下一所學校」、「第二、第三所學校」、「下一棒」。改用中性的集體說法（之後加入的學校、更多學校一起響應）
• 不使用「讓 X 不再因為 Y 而 Z」、「讓 X 終於可以 Y」、「讓 X 真正成為 Y」這類願景式句型，寫出實際發生的事，標題尤其要避免
  • 例：讓加密協作工具不再因為語言而擋在門外 改成 CryptPad 2026.5.0 內建正體中文語系

標題句構

• 標題用名詞片語，不寫成句子。以動詞為主幹的標題改寫成名詞結構，需要交代第二層資訊時用逗號接續，或把補述留給前言與 summary
  • 這三週文件站多了什麼，以及照著舊版做過準備的人要補的五件事
  • 2026/09 文件站更新回顧
• 標題不使用「主題：說明」的冒號句構
  • Brave 抹平 GPU 指紋：一致化與隨機化在同一次更新裡分工
  • Brave 抹平 GPU 指紋的兩種相反手法
• 標題裡不讓非人的主體做動作，判準與內文的擬人化同一條
  • 設定抽屜把散落的開關收在一起
  • 設定抽屜
• 不用比喻性或散文化的小標題，例如「這條路」、「談談…」、「我們的故事」，改用具體名詞（工作的進展、翻譯歷程）
• 段落內容有讓步與權衡時，標題不用「堅持」這類帶教條暗示的詞，改用中性的名詞片語（X 與 Y 的用字）
• 文章標題與各層小標題同樣適用
• 翻譯文章照錄外部來源的原始標題時保留原樣，例：介紹 oniux：針對任何 Linux 應用程式的核心層級 Tor 隔離技術
• 既有文章不必回頭改寫，新文章與大幅改版時套用

並列引號的標點

連續的「」引號之間要加「、」。錯誤與正確對照：

• 「決策者」「被諮詢者」「需被告知者」
• 「決策者」、「被諮詢者」、「需被告知者」

段落語氣

• 像一位了解主題的社群成員在解釋，而非教科書或百科條目
• 不在每段末尾加總結句，讓段落自然收尾
• 避免「值得注意的是」、「總的來說」、「綜上所述」、「談的是」、「指的是」、「涵蓋的是」這類開頭
• 避免過度對稱的三段結構（常見 AI 寫作模式）。兩段對仗的空句也算，例如「對外面的人來說…。對裡面的人來說…」只有形式、沒有資訊，改成寫出規模、數字、誰受影響
• 能用完整句子說清楚的內容，不拆成條列
• 號召語不用「找人做一做」這類太鬆的說法，改用「邀請…一起參與」、「歡迎…一起加入」

敘事結構

• 前言不堆日期、版本號、PR 編號與 URL。第一段交代這件事為什麼重要，事實放到對應的段落
• 整篇要有一條主張，每個段落都連回它，避免寫成依時間排列的事件報告
• 時間線可以條列日期，前後要有敘述銜接：開頭交代為什麼值得做，結尾交代做完對誰有意義
• 號召型文章在開頭就寫出邀請誰、做什麼、做不到時的替代方案，必要時用 admonition（!!! tip）讓它跳出來

品牌名稱與受眾

• 品牌名稱寫 anoni.net 或 匿名網路社群 anoni.net，一律小寫，英文段落也一樣（anoni.net Docs Project），不寫 Anoni.net。網址與 email 照原樣
• 內容涉及正體中文使用者時，受眾寫「正體中文使用者」，不要只寫「台灣使用者」，後者把香港、澳門等地的讀者排除在外。前言點明一次範圍（例：無論在台灣、香港、澳門或其他華語環境），之後用簡潔的說法帶過
• 寫「華文社群」、「華語使用者」前，先確認是否同時包含正體與簡體中文使用者。只想指特定字系或地區時直接寫出來（正體中文使用者、中港澳的中文使用者）
• 描述在地脈絡時寫「台灣的法規環境」是準確的。寫到「希望讓 X 用得上」這類訴求段時，先確認真正的受眾範圍

擬人化

非人的主體不做人的動作，四種常見情況與改法：

情況
組織說話	Brave 說之後會補上	Brave 的公告寫了之後會補上
文件說話	原文說、報告指出、文章點出風險	原文裡寫、報告的結論是、風險寫在同一篇文章
軟體有感知	網站看到不認識的字串、網站以為取得了真實資訊	網站取得的字串不在既有清單裡、網站收到的值與真實硬體無異
抽象物有意志	開關的存在說明取捨仍在、規則要做對	保留這些開關代表取捨仍在、要讓規則生效

兩種情況不在此限。組織作為行為者，動詞是實際做得出來的動作時保留原樣（Brave 推出防護、Tor Project 發布新版、OONI 蒐集量測）。直接引述照錄時，引號內保留原始說法。

標點集合

正文主要使用：「、」、「，」、「。」、「：」、「！」、「「」」、「（）」。技術術語（Tor、OONI、IP、USB 等）保持英文原文，不加引號，也不加粗體。

版面元件裡的項目分隔可以用半形間隔點（·），例如首頁主按鈕下方那一列次要連結。限定在元件上，句子裡的並列詞語仍然用「、」。

精簡與去 AI 味

校稿時最常做的修法，多數是把 AI 生成痕跡與贅語拿掉：

• 刪掉開場的鋪陳句。例：把 CryptPad 的基本資料先擺出來。它由… 改成 CryptPad 由…，直接進入內容，不先宣告「接下來要講什麼」。對讀者喊話的預告也算，例如「這封信想跟你說」、「以下要告訴你」、「讀完會知道…」。
• 避免「這…」、「這個…」開頭，與「其實」、「換句話說」、「把它換成白話」這類填充轉折，能刪則刪。
• 「這」與「那」不要在同一句裡堆疊。同一個字在同句出現 3 次以上，或兩次中間隔不到 9 個字，就把其中一個換成它實際指的名詞，或整句重寫。例：這件事說明有人在賣這個概念，不等於這套技術已經在運作 改成 有人在賣這個概念，不等於技術已經在運作。兩個字分別計數，這份文件提到那個結論 各出現一次，不算堆疊。全文密度可以拿來抓大方向，站上每千漢字約 5 個是常態，超過 10 個的文章通常整段都要重寫。zhe-repeat 與 na-repeat 規則只掃同句堆疊，全文密度要人工判斷。
• 抽象說法改成具體內容。例：下一段會說明這個結論為什麼不準 改成 下一段的使用量資料會推翻它。
• 「橋樑」、「拼圖」、「最後一哩」這類意象，沒有具體可指的對應物就不用。比喻偶一為之可以，不要整篇靠比喻撐，也不要在同一句裡疊用同一個比喻。例：台灣多一個節點，就是把一個入口放到那張地圖上 改成 台灣每多架一個節點，當地人就多一個還沒被封鎖、能連上 Tor 的入口。

• 不用行銷腔與 AI 常見的套話，改用具體的動詞或描述：

  避免	改用
  賦能、強化能力	寫出實際能做到的事
  打造、構建（用在抽象意義時）	建立、製作、開發
  對接	銜接、對應到、參與、溝通
  痛點、剛需	寫出實際遇到的問題
  大幅提升	寫出提升了多少
  一站式、無縫、零門檻、全方位	刪除，或寫出具體的範圍
  加碼、加持、生態（行銷意義）	刪除，或寫出實際內容
  共創、共榮、共贏、攜手、引領	寫出誰做了什麼

  「生態系」指技術上的一群專案（Tor 生態系）時不在此限。新寫的內容適用，既有文章不必回頭改寫。 - 句子偏短中等。一句話接了四個以上的逗號分句時拆成兩句。 - 去掉誇飾與情緒詞。例：經過真實使用壓力 改成 有實際使用紀錄。一般詞語不必加引號強調，例：是「可被驗證的隱私」 改成 是可被驗證的隱私。 - 段落開頭不要放一句粗體的完整句子。並列的項目升成小標題，單獨一段就寫成正常句子。例：**位置。** OONI 記錄國家與 ASN… 改成 ### 位置，空一行再接內文。升成小標題後語意也更準確，那些多半本來就是子章節，順帶會進側邊目錄。粗體詞作為句子成分或清單標籤不在此限，例：**對照日**用同樣的參數、**資料來源**：…。判準是粗體內容有沒有自成一個以句號結尾的完整句子，bold-lead-sentence 規則掃的就是這個形式。

用詞與譯名

• 口語字改書面語。例：「講」改成「提到」、「說明」，「照實講」改成「不迴避」。常見的還有：

  口語	書面語
  跑（執行軟體）	依語境用執行、架設、運作、營運
  拿到	取得
  得先、得靠	需先、需仰賴
  動手	實際操作、著手、實作
  踩到	遇到
  找上門	依語境用接洽、找上、追究
  省事、省力	簡便、容易
  怎樣	副詞用「如何」，修飾語（怎樣的 X）用「什麼樣的」。「長怎樣」整句改寫，不要寫成「長如何」
  照舊	維持原狀
  差不多	相近
  掛了	無法連線
  搞錯、弄壞	出錯、損壞
  說不過去	前後不一致、於理不合
  灌爆	失真、超出範圍
  玩（在瀏覽器裡）	執行、操作
  做出來、做得出來	完成、開發
  卡住、卡在	受阻
  拿去用、拿來用	取用
  自己（副詞，例：自己挑）	自行
  是不是	是否
  反過來看	相對地
  能用的	可用的

  照錄他人說法不在此限。例：把讀者的感受寫成「連不上」、「跑很慢」時保留原樣，因為那正是要呈現的口吻。

  兩個判斷準則。表示能不能做到的「V 得 + 結果」要改，用「可以」、「能」加動詞（找得到 改成 可以找到、下載得到 改成 可以直接下載）。表示程度的「V 得 + 補語」不必改（解釋得清楚、回答得最準）。另外，書面語不等於官腔，改到像機關公告一樣也是問題。低門檻與概數這類自然的說法保留（當天走進教室就能參與、只聽一兩場），「跟」與「與」都可以用。 - 定義、併排列舉與正式說明裡的疑問詞用「如何」，不用「怎麼」。動詞寫完整詞組，不要為了對仗縮成單字。例：發行端（誰能發、怎麼發） 改成 發行端（誰能發行、如何發行）。FAQ 問句與模擬讀者口吻的段落可以保留「怎麼」。 - 用詞跟著臺灣走。同一個東西兩岸的說法不同時，正體版用臺灣的說法，簡體版用簡體讀者慣用的那個。

  中國慣用	臺灣慣用
  站台	網站。指這個站自己時也可以寫文件站
  網關	閘道。照錄合約或產品名稱裡的「安全網關」不在此限

• 譯名分三種處理：

  • 工具、協定、產品名保持英文原文（Tor、OONI、Tails、CryptPad）。
  • 學術或概念性名詞用中文譯名，首次出現在括號附原文，之後用中文。例：Lorenz 曲線 首次寫成 羅倫茲曲線（Lorenz curve）。
  • 機器欄位或程式內部名稱改用人類可讀說法再附原文，不要把欄位名直接丟給讀者。例：web_connectivity 寫成 網路連線測試（Web Connectivity）。
• 縮寫首次出現附中文說明，之後直接用縮寫，例：ASN（自治系統編號）。面向一般讀者時，專有名詞第一次出現用括號補一句白話，說明它做什麼，例：深度封包檢測（DPI，逐筆分析連線、判斷要不要放行的技術）。

數字與編號

• 清單編號、ID、流水號用 inline code 標記，例：10006、10298，讓讀者一眼分辨那是識別碼而非一般數字。

安全與隱私寫作

匿名與隱私是這個網站的主題，寫作本身也要守住同一條線：

• 不提供可被濫用的操作配方。即使資料與 API 都公開，文章也不手把手教「全量枚舉」、「逐一抓取」這類步驟。改用結果導向的陳述，例：我們以某日為快照盤點全部清單，而非貼出枚舉所有編號的指令。
• 不揭露個別操作者的個人帳號或 handle。引用他人的觀測時用地區或角色代稱，例如把某個真實帳號代稱為 泰國觀測者，只在當事人公開且必要時才具名。
• 涉及受害者、未公開研究、個資的內容，走上傳機敏資訊流程。

檔案命名與目錄

檔名

• 全部小寫，使用連字號分隔（tor-browser-advanced.md、anonymity-vs-privacy.md）
• slug 以英文為主，避免中文檔名
• 縮寫保持小寫（vasp-2026.md 而非 VASP-2026.md）
• 數字直接接連字號（roadmap-2026.md、updates-202506.md）

目錄結構

文件站的目錄結構維持扁平，不再加深層子目錄。新文章放進現有的 7 大分類：

分類	內容性質
basics/	概念層，匿名與隱私的核心思考工具
tools/	工具層，具體的工具介紹與比較
scenarios/	場景層，特定角色或情境的應用
advanced/	進階層，技術深度的延伸閱讀
taiwan/	在地脈絡，台灣的法規、觀測、研究
reports/	嚴選報告，外部研究的中譯
community/	社群文件，治理、流程、入口頁

如果你的新文章不確定該放哪一類，先在 Matrix 上問一聲，避免直接 PR 後又要搬。

搬檔、改名、刪頁要補 redirect

移動、改名或刪除已上線的頁面時，在同一個 PR 補上 redirect，讓舊網址不會變成 404。舊網址會長期活在搜尋引擎、書籤與外部連結裡，少了 redirect 就流失既有讀者與累積的 SEO 權重。

• redirect 寫在三支 mkdocs 設定的 plugins.redirects.redirect_maps：mkdocs.yml 對應 zh-TW（/docs/）、mkdocs_en.yml 對應 en、mkdocs_cn.yml 對應 zh-cn。
• 格式是「舊路徑: 新路徑」，路徑相對各語系的 docs 目錄，不含 docs/<lang>/ 前綴。例：'tools/what-is-ooni.md': 'tools/index.md'。
• 找不到一對一的新頁時，導向所屬分類的 index 頁（community/index.md、tools/index.md 等）。
• 既有 redirect 保留不刪，舊網址會一直有人點進來。唯一要回頭改的情況：某條的目標頁自己也被移掉，redirect 變成斷鏈。

拆頁或搬走段落要回頭檢查入口連結

redirect 管不到內容搬移。頁面留著、只有其中一段被拆到新頁時，舊網址仍然回 200，沒有任何工具會報錯，但指向舊頁的按鈕與連結承諾的東西已經在別處。

• 拆頁或把段落搬到別頁時，在同一個 PR 內搜尋站內指向來源頁的連結，把文案提到搬走內容的那幾條重新指向新頁。
• strict build 與 docs-style-lint 都抓不到這種錯。兩個目標檔都存在，錯的是連結語意而非能不能連，只有讀按鈕文案對照目的地才找得到。
• 已發布的 blog 文也算在內。按鈕是功能性入口，讀者點它是要找那份內容，重新指向不等於改寫文章當時的記述。

實例：2025-05 把工作坊頁拆成兩頁時，event-workshop-2025.md 留下活動資訊，招募與籌備內容搬到 event-workshop-2025-prepare.md。兩篇 2025-04 的貼文有「查看工作坊招募頁面說明」與「瞭解籌備事項」兩個按鈕仍指向活動頁，到 2026-08 才被發現。

圖片與資源

截圖與示意圖走不同的路徑。

截圖（操作畫面、網站畫面）放在 docs/<lang>/assets/images/：

• 在 markdown 引用：對於 basics/、tools/ 等深度 1 的目錄，用 ../../assets/images/檔名
• 對於 reports/interseclab-network-coup/ 等深度 2 的目錄，用 ../../assets/images/檔名（剛好一樣）
• 優先使用 webp 或最佳化過的 png，不直接放手機原始大檔
• 有 lightbox（點擊放大）時，HTML 用 <figure> + <a href> 包 <img>，兩個的相對路徑都要對齊
• 三個語系的 assets/images/ 各自獨立，補了一個語系記得補另外兩個。漏掉的話建置不會報錯，站上就是一頁破圖，執行 python3 tools/check_image_refs.py 掃得出來

示意圖（流程圖、架構圖、對照矩陣、時間軸）的原始檔放 docs/diagrams/，發布到 assets.anoni.net，三個語系引用同一個網址。製作、命名與發布流程見品牌識別的「貢獻技術圖示」一節。

跨檔連結規則

內部連結用相對路徑，不要寫成 /docs/zh-TW/... 絕對路徑：

• 同一目錄：./other-file.md 或直接 other-file.md
• 跨目錄：../basics/anonymity-vs-privacy.md
• 跨深度：../../blog/posts/2025to2026.md

正文的連結用描述性的文字，不直接露出網址，也不拿網址當連結文字。例：詳見[社群工具頁](./tools.md)。

外部連結加 {target="_blank"}，在新分頁開啟：[Freedom on the Net](https://freedomhouse.org/explore-the-map){target="_blank"}。

需要寫對外完整網址時（社群貼文、外部引用），網站預設語系 zh-TW 不帶語系區段：docs/zh-TW/community/i18n.md 對應 https://anoni.net/docs/community/i18n/。zh-CN 用小寫 https://anoni.net/docs/zh-cn/...，en 用 https://anoni.net/docs/en/...。資料夾路徑仍保留語系大小寫。

文章末尾建議放「接下來」、「相關閱讀」之類的小節，連結到 2–4 篇相關文章。基礎、工具、場景、進階之間的橫向連結比單向引用更有用。

文章格式

front matter

每一頁開頭的 front matter 至少有三個欄位：

---
title: 威脅模型
description: 一句完整的句子，說明這一頁在講什麼、對讀者有什麼用
icon: material/shield-account-outline
---

• title 不加問號，也不加站名。社群分享卡與頁面標題會自動帶上站名
• description 會用在搜尋結果的摘要與社群分享卡。寫成一句完整的句子，交代這一頁對讀者有什麼用，不要只重述標題
• icon 以 material/ 為主，少數情境用 fontawesome-solid-、fontawesome-brands-
• front matter 之後緊接 H1，寫成 # :material-icon-name: 標題，圖示通常與 icon 欄位相同
• blog 文章另外要有 date、slug、categories、authors
• 社群分享卡要換標題、描述或底圖時，見品牌素材的「社群分享卡」一節

註腳

引用研究與報導時用 Markdown 註腳，註腳放在文章末尾：

中國的防火長城[^1]長期過濾大量國際網站。

[^1]: [原文標題](https://example.org/article){target="_blank"} - 媒體名稱

主要來源避免選付費牆的內容。只找得到付費牆版本時，另外附一個 archive.org 的存檔連結。

圖表

文件站支援 Vega-Lite 圖表（mkdocs-charts-plugin），用語言標記為 vegalite 的程式碼區塊撰寫，資料來源優先用 Pulse API（https://api.anoni.net/api/...）。可參考 taiwan/tor-relay-watcher.md。

結構化資料

整站的 Organization JSON-LD 寫在 docs/overrides/main.html，文章裡不要再手動加 <script type="application/ld+json">。

PR 流程

Branch 命名

• blog/<short-slug> 處理 blog 文章（例：blog/throttle-drill-results）
• feat/<short-slug> 處理新功能、新分類、寫作規範，以及既有文件的大幅改寫（例：feat/title-colon-rule）
• fix/<short-slug> 處理 bug、樣式與小幅修正（例：fix/table-width）

docs/ 不能當前綴。docs 本身是建置觸發分支，git 不允許同一個名稱同時是 ref 與 ref 的目錄，git switch -c docs/vasp-2026-rewrite 會回報 cannot lock ref。

Commit 訊息格式

採用 conventional commits：

<type>(<scope>): <subject>

<body>

常用 type：docs、feat、fix、chore、refactor。scope 用語系或子專案名稱（zh-TW、zh-CN、en、pulse、asn_coverage）。

PR 描述

PR 描述至少包含：

• 改動的「為什麼」（連結 Issue 或社群討論）
• 改動的範圍（哪些檔案、哪幾個段落）
• 對讀者的影響（連結是否會壞、URL 是否變更、有沒有相依的檔案要一起改）

Review

• 翻譯、文字校對：請求至少一位非作者 review
• 結構性變動（搬檔、改 nav）：先在 Matrix 提案討論，再開 PR
• 圖片、資源：自我檢查 alt 文字、檔名、版權標示

Issue 分類

Issue 標籤體系（持續調整中）：

• type:docs 文件相關
• type:bug 行為錯誤
• type:enhancement 改進建議
• type:question 問題討論
• area:zh-TW / area:zh-CN / area:en 語系區分
• area:tools / area:scenarios 等對應分類
• good first issue 給新貢獻者的入門 Issue
• help wanted 需要更多協助的 Issue

開 Issue 前可以先在 GitHub 搜尋既有 Issue，避免重複。

翻譯流程

zh-TW 是 single source of truth，zh-CN 與 en 從 zh-TW 同步。詳細流程見 中文化與文件翻譯：

• 新文章預設先寫 zh-TW
• zh-CN 用工具輔助初翻 + 人工調整詞彙差異（用語、慣用詞）
• en 需要更多人工，因為文化脈絡轉換比語系翻譯費時
• zh-CN 與 en 的翻譯不必同步上線，依社群人力滾動處理
• 把外部文章（Tor Project、OONI、EFF 等部落格）翻成 blog 的順序、格式與各語系的觀點段，見中文化與文件翻譯的「翻譯外部文章到 blog」一節
• 校對時要抓「翻漏」，也就是 zh-TW 具名的國家、公司、機構、法條、數字在譯文被換成上位詞。判準與檢查方式見 校對時要抓的是翻漏

AI 協作

這個專案不限制貢獻者用哪一家的 AI 服務協助寫作、翻譯或寫程式。為了讓不同的人、不同的工具產出一致的內容，規則只寫在這份百科，AI 設定檔都指回這裡。

入口檔

• repo 根目錄的 AGENTS.md 整理 repo 結構、開發指令與容易出錯的地方，多數 AI 工具會自動讀它。pulse/ 另有一份
• CLAUDE.md 引入 AGENTS.md，另外說明 .claude/ 底下的 subagent 與 skill
• 使用的工具不會自動讀這兩份時，開工前把 AGENTS.md 與這份百科的「寫作風格規範」一節提供給它

AI 產出的檢查

AI 產出與人工撰寫走同一套流程：執行 docs_style_lint.py、照 PR 範本自我檢查、經過 review。「安全與隱私寫作」一節的界線同樣適用。AI 給的數字、引文與來源連結要實際點開核對，送出 PR 的人為內容負責。

角色

寫一篇文章時，可以把工作拆給幾個角色，各自只做一件事。使用 Claude Code 的貢獻者可以直接叫用 .claude/agents/ 底下對應的 subagent，其他工具照下面的描述下指令即可。每個角色的讀者前提相同：記者、公民團體、開源科技社群，熟悉 Tor、OONI 與數位人權的專家也會讀。

動筆前的三個角色：

• 選題雷達：掃指定期間（預設近兩週）匿名網路工具、數位身分與 eID、監控與審查立法、審查量測、支付隱私、吹哨與洩密平台、台灣與 APAC 數位人權的新事件，篩掉炒作、純產品發布與無關的題目。每則候選回報一句話的事件、日期、一手來源連結、跟社群的關聯、有沒有台灣或 APAC 的角度、時效，依值得寫的程度排序，最多六則。不寫文章，也不決定切角
• 切角顧問：針對一個題目提出三到四個切角，說明每個切角從哪個面向切入、社群能補什麼觀點、有沒有台灣或 APAC 的在地連結，並排出建議順序。只給選項，不替作者決定，也不動筆
• 資料蒐集：題目選定後，蒐集一手來源（官方公告、原始文件、權威報導）並附連結與發布日期，掃 docs/zh-TW/blog/posts/ 列出該交叉連結的既有文章與相對路徑，標出之後寫進文章時要附出處的宣稱。站內已有很接近的文章時直接指出。不寫文章，也不決定切角

審稿的四個角色：

• 結構審查：讀完全文，用一句話寫出核心主張與它想說服的對象，再檢查每段是否服務這條主線，哪些順序該調、哪些可刪、哪些缺銜接。回報主線判讀、依嚴重程度排序的結構問題（標出段落位置）與調整建議。不改字句
• 文字潤稿：找出冗詞、語意含糊與邏輯跳接的句子，檢查語氣前後一致，雙語文件核對兩個版本說的是同一件事。每個問題回報原句位置、問題與改寫版本，針對句子，不重寫整段
• 事實查核：列出文章裡每個可查證的宣稱，包括數字、日期、國家案例、技術描述、對專案或組織的描述，逐一判定為準確、需要出處、可能有誤或過度宣稱，可能有誤的實際查證。每個問題回報原句位置與宣稱、判定、證據或來源連結、建議改法（改數字、加出處、改成保守的說法或刪除）。不潤稿，也不評論文采
• 目標讀者：扮演一位不熟主題、願意花五分鐘讀完的讀者，標出哪句讀不懂、哪個論點沒被說服、讀完記得什麼、會想做什麼。只給讀者反應，不給編輯建議

提問前先看哪裡

新貢獻者最常問的問題與對應出處：

問題	看這裡
如何選擇主題開始？	如何參與與認領主題
如何申請 Matrix 帳號？	社群自架服務
我的程度適合做什麼？	自我技能評估表
如何設定開發環境？	專案研究預先準備
翻譯有什麼規範？	中文化與文件翻譯
緊急情況的對外資源？	緊急求救

如果上述都沒答案，到 Matrix 詢問。詢問前盡量提供：你想做什麼、你已經試過什麼、你卡在哪。

行為準則摘要

社群以開放、互助、合法為原則。以下是快速摘要，完整版（含角色定義、決策流程、爭議處理）見 治理章程，兩者不一致時以治理章程為準。重點：

• 互相尊重：不同背景、不同熟悉度的成員一視同仁
• 討論議題不攻擊個人：對事不對人
• 合法前提：所有討論與協作以合法用途為前提，不協助洗錢、規避稅務、騷擾、跟蹤、未授權入侵等行為
• 資訊揭露：涉及個人資料、機敏資訊的處理走 上傳機敏資訊流程
• 爭議處理：先在 Matrix 討論，沒有共識可提案到下一次社群同步討論

違反原則的行為會由核心成員依治理章程處理。

這份百科是活文件

新貢獻者遇到本頁沒有涵蓋的問題、發現某個流程其實沒寫清楚，歡迎提案修改本頁。改 contributor-handbook 本身就是一個 good first issue 的好題目。