milestone 2.0.0

.agents/skills/conversion-specials/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: conversion-specials
+description: >
+  只在使用者要新增或修改 ConvertZZ 字形特例時使用：改
+  conversion-specials/rules.txt 或 place-names.txt、加入 skip／variant／s2t-multi／t2s-multi／pin
+  規則。觸發：加入特例、修改特例、改 rules.txt、台灣縣市鄉鎮里名稱、/conversion-specials。
+  不要在一般轉換、extra-correction、roundtrip、除錯既有行為時套用。
+---
+
+# 撰寫 conversion-specials
+
+只在本次任務要**新增或修改**字形特例時跟這份 skill。討論轉換結果、修 extra-correction、跑 roundtrip、或只讀現有規則，不要套用。
+
+字形特例只改 `src-tauri/resources/conversion-specials/rules.txt`。台灣完整「xx縣／xx市／xx鄉／xx鎮／xx里」放 `place-names.txt`（用 `fetch-place-names.py` 更新），不要把幾千個地名寫進 `rules.txt`。欄位、`when` 語法與現況案例以同目錄 [README.md](../../../src-tauri/resources/conversion-specials/README.md) 為準；改規則前先讀完。不要把字寫進 `conversion.rs`，也不要寫進 `segment-dict`。
+
+## 放哪一層
+
+| 情況 | 放哪 |
+| --- | --- |
+| 單字、有上下文的一簡多繁／一繁多簡、異體、引擎錯映射 | `rules.txt` |
+| 固定整詞保護（和牛、胜肽、里長） | `rules.txt` 的 `pin` 或 `word=`／`word^=`（分詞釘入、轉換再套用） |
+| 台灣完整縣／市／鄉／鎮／里名 | `place-names.txt`（分詞釘入、簡轉繁拉回、roundtrip-dict 寫回 extra） |
+| 語料產生的整詞同義（手錶、範圍、機制）＋詞性 | `extra-correction` 同義詞／分詞表 |
+| 語意取代清單或 `skip: "…"` 字串 | 不准；改 `rules.txt` |
+
+extra 已有整詞＋詞性的（只／隻、制／製），不要再在這裡做無條件單字取代。需要單字量詞時用 `s2t-multi`＋`pos=`。
+
+## 選 kind
+
+| 目標 | kind | 注意 |
+| --- | --- | --- |
+| 引擎會改、我們要維持原字（璇不要變璿） | `skip` | `to` 留空。不要再 `variant` 把目標改回來（璿／璇是不同人名） |
+| 無條件單字正規化（皰→疱） | `variant`／`s2t`／`t2s` | 一對一單字走字形表，不靠分詞 |
+| 同一簡體依上下文選不同繁體 | `s2t-multi` | 有 `when` 的例外必須寫在無條件預設**上面** |
+| 同一繁體依上下文選不同簡體 | `t2s-multi` | 若引擎會先改掉來源字，先對該字 `skip` 該 `dir` |
+| 只要整詞不被切開、不必改字 | `pin` | `to` 留空。2 字以上才釘入 |
+
+`dir`：`s2t`／`t2s`／`both`。省略時 `skip`／`s2t`／`variant`／`s2t-multi` 預設 `s2t`。
+
+## 寫一行
+
+UTF-8，**欄位用 Tab，不是空白**。`from` 多個來源用 `|`。`when` 多條件用 `;`（AND），同一條件內 `|` 為 OR。`#`／`//` 為註解。
+
+```
+kind<TAB>from<TAB>to<TAB>dir<TAB>when
+```
+
+同一方向、能對上 `from` 的規則由上而下第一條命中即停。出現在帶 `when` 的 `from` 裡的字不會進字形 override 表（避免「老么」在分詞前變成「老麼」）。
+
+`when` 只准 README 列出的鍵：`word=`、`word^=`、`next=`、`next^=`、`ch0=`、`ch1=`、`pos=`、`prev-pos=`。不要發明新欄位；`pos` 名稱與 extra-correction 相同（`D_MQ`、`A_Q`、`D_MQ+A_Q`）。
+
+寫完用真實 Tab 檢查，例如：
+
+```bash
+python3 -c "
+from pathlib import Path
+p = Path('src-tauri/resources/conversion-specials/rules.txt')
+for i, line in enumerate(p.read_text().splitlines(), 1):
+    s = line.strip()
+    if not s or s.startswith('#') or s.startswith('//'):
+        continue
+    print(i, line.split('\t'))
+"
+```
+
+## 驗證
+
+1. 在 `src-tauri/src/core/conversion/specials.rs` 的 `bundled_rules_parse`（或新測試）鎖定新行為。
+2. 需要整句／分詞時補 `src-tauri/src/core/conversion/tests.rs` 黃金案例。
+3. 跑：
+
+```bash
+cargo test --manifest-path src-tauri/Cargo.toml --lib core::conversion::specials
+cargo test --manifest-path src-tauri/Cargo.toml --lib glyph_s2t
+```
+
+規則已載入後，`OnceLock` 不會重讀；改 `rules.txt` 後相關測試要新進程。發行包路徑與 `CONVERTZZ_CONVERSION_SPECIALS` 覆寫見 README，一般改倉庫檔即可。

.agents/skills/linux-desktop-acceptance/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: linux-desktop-acceptance
+description: >
+  Linux X11 桌面人工驗收：避開 IME／檔案選擇器／原生對話／剪貼簿坑，用 AT-SPI、CLI
+  路徑注入與 gpaste 歷史取證。觸發：驗收、人工證據、ConvertZZ D/E/G/I、Tauri Linux UI
+  驗證、/linux-desktop-acceptance。
+---
+
+# Linux 桌面人工驗收
+
+在 Linux 上為 ConvertZZ（或同類 Tauri 桌面程式）補齊遷移驗收證據。先讀環境閘門，再依正確操作取證；細節反模式見 [references/pitfalls.md](references/pitfalls.md)。
+
+## 何時使用
+
+- 使用者要求驗證 `docs/MIGRATION_PLAN.md` 的 D／E／G／I 待人工項
+- 需要截圖、錄影、程序清單等桌面證據
+- 先前自動化卡在檔案對話、輸入法、Element Plus 下拉或原生確認框
+
+## 開始前（環境閘門）
+
+記錄並依結果裁切範圍，不可硬測：
+
+```bash
+echo "SESSION=$XDG_SESSION_TYPE DESKTOP=$XDG_CURRENT_DESKTOP"
+echo "WAYLAND=${WAYLAND_DISPLAY:-unset} DISPLAY=${DISPLAY:-unset}"
+busctl --user list 2>/dev/null | grep -iE 'StatusNotifier|secrets|keyring' || true
+systemctl --user is-active gnome-keyring-daemon.service 2>/dev/null || true
+```
+
+| 條件 | 可測 | 不可測（標環境受限） |
+| --- | --- | --- |
+| `XDG_SESSION_TYPE=x11` | X11 項、多數 D／E／G | I-03～I-05（需 Wayland） |
+| 無 Wayland session | — | Wayland 簽核 |
+| 有 StatusNotifierWatcher | 托盤正常路徑 | I-06（缺 AppIndicator） |
+| Secret Service 啟用 | 金鑰可持久 | I-07 完整「關閉後重啟兩次」（勿貿然殺 keyring） |
+| GitHub latest ＜ 本機版 | G-16 後備查詢 | G-16「開啟下載頁」、G-15 簽署安裝 |
+
+二進位優先用今日 `src-tauri/target/release/convertzz`；資料目錄為 `~/.local/share/dev.flier268.convertzz/`（見 `tauri.conf.json` 的 `identifier`）。
+
+**禁止** `convertzz --version`／對 GUI 二進位跑會掛起的「版本」指令（會開視窗且不退出）。  
+**禁止** `pkill -f convertzz`（會誤殺含該字串的 shell wrapper）；改 `pgrep -x convertzz` 後依 PID `kill`。
+
+## 證據目錄
+
+證據**不要**寫進倉庫的 `docs/`（錄影／截圖體積大）。預設：
+
+```text
+~/Desktop/ConvertZZ-acceptance/YYYY-MM-DD/
+  META.txt          # git SHA、二進位、平台、日期
+  README.md         # 項目→檔案對照與環境限制
+  <ID>-*.png|mp4|txt
+```
+
+驗收前備份設定目錄到同一證據夾。只有必要證據齊全才把項目改為 `已通過` 並移入 `docs/MIGRATION_COMPLETED.md`（見 `AGENTS.md`）；遷移文件只記摘要路徑，不提交媒體檔。
+
+## 工具選擇
+
+| 目的 | 用法 |
+| --- | --- |
+| 點選主視窗控件 | **pyatspi**：依 `name`／`role` 找節點，`queryAction().doAction(0)`；失敗再用 `getExtents` + `xdotool` |
+| 視窗截圖 | `xdotool getwindowgeometry --shell` → `ffmpeg -f x11grab -video_size WxH -i :0.0+X,Y -frames:v 1 -update 1 out.png` |
+| 操作錄影 | `ffmpeg -f x11grab -video_size 螢幕 -framerate 8 -i :0.0 -vf scale=1600:-2 ... out.mp4` |
+| 寫入剪貼簿 | `gpaste-client add '文字'` |
+| 讀取剪貼簿 | `gpaste-client history \| head -1 \| sed 's/^[^:]*: //'`（**不要** `gpaste-client get 0`） |
+| 注入檔案路徑 | Python `subprocess.Popen([bin,'/file','/f:t','/b:f', unicode_path])` 交給既有實例；**不要**用 `xdotool type` 打路徑 |
+| Element Plus 下拉 | 點 combo → `xdotool key Down`（次數依選項）→ `Return`；驗證欄位顯示已變 |
+| 原生確認（rfd／plugin-dialog） | AT-SPI 找 `alert`；按鈕常為 `確定(O)`／`取消(C)`；`Tab` 後 `space` 可確認 |
+
+切換輸入法至英文（例如 `fcitx5-remote -s keyboard-us`）仍不足以保證 `xdotool type` 路徑正確；路徑一律走剪貼簿貼上或 CLI argv。
+
+## 項目流程（ConvertZZ）
+
+### D-07 首次匯入前詢問
+
+1. 備份並移走資料目錄，建立空目錄。
+2. 將舊 `ConvertZZ.json` 放在啟動 cwd（`legacy_settings_path` 查 exe 旁與 cwd）。
+3. 從該 cwd 啟動 release 二進位；導覽至「匯入舊版設定」。
+4. 證據：畫面須有「匯入找到的設定／選擇檔案／略過匯入」，且未自動寫入。
+
+### D-11 儲存字典前詢問
+
+1. 設定可寫 `dictionaryPath`（可寫入 `settings-v2.json` 後重啟，或成功選檔後）。
+2. 「新增」一筆即可讓 `changeCount>0`（單元格未填也可觸發儲存確認）。
+3. 按「儲存變更」→ 擷取「確認字典備份」。
+
+### E-02 檔名預覽顯示來源與輸出
+
+1. 用 CLI 注入簡體檔名樣本路徑（避免檔案選擇器）。
+2. 取消自動「內容」計畫 → 作業改「轉換檔名」、方向「簡轉繁」→「建立預覽」。
+3. 證據：表格同時有「來源」「輸出」欄且檔名已轉換。
+
+### E-05 覆寫額外確認
+
+1. 同目錄備好 `电脑.txt` 與已存在的 `電腦.txt`。
+2. CLI 注入來源 → 作業「轉換檔名」、衝突策略「覆寫」（鍵盤選取並確認 UI 顯示「覆寫」與警告「輸出路徑已存在。」）。
+3. 「確認執行」→「確認檔案轉換」按 `確定(O)` → 擷取「確認覆寫」。不要真的覆寫時按取消。
+
+### G-12 快捷鍵／托盤／浮動球同路由
+
+1. 寫入設定：`quickActions.leftClickCtrl=a3`；啟用一組快捷鍵指向 `a3`；重啟以套用。
+2. 同一輸入文字，依序：浮動球 Ctrl+左鍵、快捷鍵、右鍵選單「Unicode 簡 → Unicode 繁」（與托盤選單同一組 legacy action id）。
+3. 用 gpaste history 比對三次輸出；寫入 `G-12-compare.txt`。
+
+### G-13 第二實例交棒
+
+1. `pgrep -ax convertzz` 存 before。
+2. 再啟動 `convertzz /audio`（或 `/file …`）。
+3. after：只剩一個 PID；第二程序應已退出；UI 導向對應頁。
+
+### G-15／G-16 更新
+
+- **G-15**：需要已發佈且已簽署、版本新於本機的 AppImage／Windows 安裝包與有效 `latest.json`。
+- **G-16**：DEB／無簽署通道時應走 GitHub 後備。若遠端 latest 舊於本機，只會「已是最新」——記錄 DEB、`latest.json` HTTP 狀態與截圖，標部分完成；勿偽造成「已開啟下載頁」。
+
+### I 平台項
+
+- I-03～I-05：僅 Wayland；可先截 X11 關於頁能力表作對照，但不算通過。
+- I-06／I-07：需缺托盤或可安全關閉 Secret Service 的受控環境。
+- I-08：三平台矩陣簽核後才結案。
+
+## 結束
+
+1. 寫 `README.md`／`META.txt`。
+2. 通過項移入 `docs/MIGRATION_COMPLETED.md`，更新 `docs/MIGRATION_PLAN.md` 摘要與待補備註。
+3. 告知使用者設定備份路徑；非經要求不要默默覆寫其設定。

.agents/skills/linux-desktop-acceptance/references/pitfalls.md

@@ -0,0 +1,68 @@
+# 坑與正確作法
+
+從 2026-08-18 ConvertZZ Linux X11 驗收整理。SKILL 正文只保留流程；此處為反模式對照。
+
+## 程序與啟動
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| `convertzz --version` 或對 GUI 二進位跑「印版本就退」 | 開主視窗，指令不退出 | 用 `dpkg -l`、`stat` 二進位、或設定／關於頁看版本 |
+| `pkill -f convertzz` | 誤殺含該字串的 agent shell | `pgrep -x convertzz` → 對 PID `kill`／`kill -9` |
+| 假設已安裝 DEB 與 repo release 同建置 | 驗到舊行為 | 優先 `src-tauri/target/release/convertzz`；在 `META.txt` 記 mtime 與 git SHA |
+
+## 輸入法與路徑
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| `xdotool type /tmp/.../中文或長路徑` | fcitx／Rime 把按鍵組成錯字，設定寫入垃圾路徑 | `gpaste-client add "$path"` → 對話框 `Ctrl+L` → `Ctrl+V`；或完全避開對話框 |
+| 依賴檔案／資料夾選擇器完成 E／D | 對話殘留、位置列彈層、路徑未進 app | 第二實例 CLI：`[bin,'/file','/f:t','/b:f', unicode_path]`（Python argv，勿經 shell 弄壞編碼） |
+| 選完資料夾未確認「尚未選取路徑」是否消失 | 後續預覽空白仍繼續點 | 每次選路徑後截圖確認 path summary |
+
+## UI 自動化
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| 用視窗百分比盲點「下一步」 | Tour 不動或誤關 | pyatspi 找 `push button`「下一步」／「結束導覽」 |
+| AT-SPI `doAction` 點 Element Plus `list item` 就當選取成功 | 下拉仍顯示舊值（例如衝突策略一直「略過」） | 點 combo 後 `Down`×N + `Return`；截圖確認欄位文字已變 |
+| 原生確認找 `Yes`／`No`／`是`／`否` | 找不到按鈕 | 找 `alert`；按鈕多為 `確定(O)`／`取消(C)`；或 `Tab` + `space` |
+| `Escape` 以為一定關掉 rfd 確認 | 對話殘留，擋住後續操作 | 明確點取消；重開流程前先確認無 `alert` |
+| 像素找 Element Plus primary 藍鈕 | 深色主題／進度點誤判 | 以 AT-SPI name 為準；像素僅輔助 |
+
+## 剪貼簿（G-12）
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| `gpaste-client get 0` | UUID API 失敗，誤判轉換沒跑 | `gpaste-client history` 取第一筆內容 |
+| 未先寫入 `quickActions`／`hotkeys` 就測 | 全是 `"0"`／未啟用，無輸出 | 改 `settings-v2.json` 後**重啟**再測 |
+| 只測浮動球就宣稱托盤通過 | 證據不足 | 快捷鍵 + 浮動球手勢 + 與托盤共用 action id 的選單項；在 compare 檔註明托盤與右鍵選單同源 |
+
+## 檔案／覆寫（E）
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| CLI 注入後不改作業模式 | 一直是「轉換內容」預覽 | 取消計畫 → 改「轉換檔名」→ 再建立預覽 |
+| 衝突策略 UI 未變成「覆寫」就按執行 | 不會出現第二次「確認覆寫」 | 確認警告「輸出路徑已存在。」且策略顯示「覆寫」 |
+| 覆寫測完不還原樣本 | 後續重跑缺衝突 | 測前重建 `电脑.txt`／`電腦.txt`；確認框用取消離開 |
+
+## 更新（G-15／G-16）
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| 本機 2.0.0 + GitHub latest 1.0.0.8 卻期待「開啟下載頁」 | 只會「已是最新版本」 | 記 DEB、`latest.json` 狀態、截圖；標部分完成 |
+| 無簽署 `latest.json` 卻標 G-15 通過 | 違反證據規則 | 等正式簽署發行通道 |
+
+## 平台（I）
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| 在 X11 截關於頁就標 I-03～I-05 通過 | 證據平台不符 | 明確寫「需 Wayland」 |
+| 為 I-07 直接殺 gnome-keyring | 可能鎖死桌面金鑰／登入 | 受控環境或標受限；程式契約另用單元／程式碼核對 |
+
+## 證據與文件
+
+| 錯誤作法 | 後果 | 正確作法 |
+| --- | --- | --- |
+| 單元測試通過就改 `已通過` | 違反 AGENTS.md | 必要證據入倉庫外目錄（預設 `~/Desktop/ConvertZZ-acceptance/YYYY-MM-DD/`） |
+| 把錄影／截圖提交進 `docs/` | 倉庫膨脹 | 證據留本機；遷移文件只寫摘要與路徑 |
+| 不寫環境限制 | 下次重複踩坑 | README 固定「環境限制」表 |
+| 驗收中覆寫使用者設定不備份 | 難以還原 | 先 `cp -a` 資料目錄到證據夾 |

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.gitattributes

@@ -1,7 +1,8 @@
 ###############################################################################
-# Set default behavior to automatically normalize line endings.
+# Normalize text to LF in the working tree too. Windows runners otherwise
+# check out CRLF, and Prettier --check (endOfLine: lf) fails in release CI.
 ###############################################################################
-* text=auto
+* text=auto eol=lf
 
 ###############################################################################
 # Set default behavior for command prompt diff.

.githooks/pre-commit

@@ -0,0 +1,39 @@
+#!/bin/sh
+set -eu
+
+staged="$(git diff --cached --name-only --diff-filter=ACM || true)"
+[ -n "$staged" ] || exit 0
+
+js_files="$(printf '%s\n' "$staged" | grep -E '\.(cjs|css|html|js|json|mjs|ts|tsx|vue|ya?ml)$' || true)"
+rs_files="$(printf '%s\n' "$staged" | grep '\.rs$' || true)"
+
+if [ -n "$js_files" ]; then
+  if ! command -v pnpm >/dev/null 2>&1; then
+    printf '%s\n' "pnpm 不存在，無法自動格式化 Vue 與 Node.js。" >&2
+    exit 1
+  fi
+  set --
+  while IFS= read -r file; do
+    [ -f "$file" ] || continue
+    set -- "$@" "$file"
+  done <<EOF
+$js_files
+EOF
+  if [ "$#" -gt 0 ]; then
+    pnpm exec prettier --write --ignore-unknown -- "$@"
+    git add -- "$@"
+  fi
+fi
+
+if [ -n "$rs_files" ]; then
+  if ! command -v cargo >/dev/null 2>&1; then
+    printf '%s\n' "cargo 不存在，無法自動格式化 Rust。" >&2
+    exit 1
+  fi
+  cargo fmt --manifest-path src-tauri/Cargo.toml
+  printf '%s\n' "$rs_files" | while IFS= read -r file; do
+    if [ -f "$file" ]; then
+      git add -- "$file"
+    fi
+  done
+fi

.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+        with:
+          run_install: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - name: 安裝相依套件
+        run: pnpm install --frozen-lockfile
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: src-tauri
+          shared-key: ci
+          save-if: ${{ github.event_name != 'pull_request' }}
+      - name: 安裝 Linux 建置套件
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential ffmpeg libayatana-appindicator3-dev libdbus-1-dev \
+            librsvg2-dev libwebkit2gtk-4.1-dev pkg-config
+      - name: 檢查前端
+        run: pnpm run check
+      - name: 執行 Rust 核心測試
+        run: cargo test --manifest-path src-tauri/Cargo.toml --workspace -- --test-threads=1
+
+  e2e:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+        with:
+          run_install: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - name: 安裝相依套件
+        run: pnpm install --frozen-lockfile
+      - name: 安裝 Playwright Chromium
+        run: pnpm exec playwright install --with-deps chromium
+      - name: 執行前端 e2e
+        run: pnpm run test:e2e
+
+  rust-format:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - name: 檢查 Rust 格式
+        run: cargo fmt --manifest-path src-tauri/Cargo.toml -- --check