跳至主要内容

使用指南

使用指南

適用版本:Terminux 0.1.1。不同版本的命令與功能可能不同。

目錄

  1. 開始之前
  2. 快速開始
  3. 安裝
  4. 設定
  5. 啟動、停止與狀態
  6. 使用 Terminux 終端機
  7. Lineage 檢查
  8. 執行 ORFS
  9. 品質判定(DQE)與 DQE Viewer
  10. 使用 AI(@@)
  11. 有界任務與 Engineering Work(未驗證)
  12. 其他工具
  13. 資料、隱私與安全
  14. 維護
  15. 疑難排解
  16. 常見問題
  17. 附錄

1. 開始之前

1.1 Terminux 是什麼

Terminux 是給 IC 設計工程師用的終端機與個人背景服務。你在 Terminux 終端機裡照常使用 bash 或 tcsh;背景服務(以下稱 daemon)會在你下 EDA 命令時檢查資料血緣、在每次執行後留下可驗證的證據與品質判定,並讓 AI 只根據這些證據回答你的問題。

每個 Linux 帳號有一個 daemon,資料放在你自己的 ~/.terminux。不設定 LLM provider 時,Terminux 不會把任何資料送給 provider。

1.2 你會用到的元件

元件 指令 用途
Terminux 終端機(GUI) terminux 終端機視窗、通知列、AI 問答
啟動器 terminux-launch 啟動或沿用 daemon,再開 GUI
DQE Viewer 由 @@open DQE Viewer 開啟 檢視與比較品質紀錄
ORFS 執行 terminux-orfs-run 以你的帳號在主機上執行一次 ORFS flow
驗證過的 report terminux-orfs-report 依收據與產物清單印出 report
診斷 terminux-doctor 檢查安裝與 daemon 狀態

所有命令的完整清單見 附錄 A。

1.3 名詞

名詞 意思
daemon 每個 Linux 帳號一個、在背景運作的 Terminux 服務
收據(receipt) 一次工具執行的正式結果紀錄:run id、attempt、工具身分、exit code、產物清單參照
產物清單(artifact manifest) 執行後對輸出檔的客觀紀錄(路徑、大小、SHA-256),寫入後不可修改
DQE Design Quality Evidence:以固定規則對執行結果做的品質判定
@@ 在終端機提示字元輸入 @@問題,問題交給 Terminux 的 AI,不交給 shell
Profile 模式 管理者設定、限制 AI 範圍與外送資料的模式
host-native 以你自己的帳號、直接在主機上執行 EDA 工具,不經過 container

2. 快速開始

STOP:安裝包與 checksum 必須經獨立可信來源驗證;未通過時不要解壓或安裝。

以可攜式安裝包、DeepSeek(OpenAI 相容服務)與 nangate45/gcd 為例:

  1. 確認主機是 Linux x86_64,並已安裝 Qt 6.7 以上(Desktop gcc 64-bit 預設元件)。

  2. 下載 terminux-<版本>-linux-x86_64.tar.gz 與 SHA256SUMS,核對後安裝:

    請依安裝教學核對獨立校驗值、停止條件及後續安裝順序。

  3. 建立憑證檔(權限必須是 0600):

    mkdir -p ~/.terminux
    cat > ~/.terminux/credentials.json <<'JSON'
    {"TERMINUX_OPENAI_API_KEY": "<你的 API key>", "TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com"}
    JSON
    chmod 600 ~/.terminux/credentials.json
    
  4. 選擇 backend 並啟動:

    export TERMINUX_LLM_BACKEND=openai_compatible
    terminux
    
  5. 在 Terminux 終端機裡執行 ORFS(路徑換成你的 ORFS 安裝位置):

    terminux-orfs-run --orfs-repo-root /path/to/OpenROAD-flow-scripts \
      --work-home ~/orfs-runs/run1 --design gcd --platform nangate45 --variant run1 \
      --design-config ./designs/nangate45/gcd/config.mk \
      --ledger-db ~/orfs-runs/run1-ledger.sqlite --receipt-out ~/orfs-runs/run1-receipt.json
    

    在安裝包的環境裡,terminux-orfs-run 位於 ~/.local/opt/terminux/current/venv/bin/,可用完整路徑執行或加入 PATH。

  6. 輸入 @@open DQE Viewer 查看品質結果。提問時把第 5 步結尾印出的 run id 寫進問題,例如 @@run_… 哪些檢查是 WARN 或 FAIL?證據在哪裡?(把 run_… 換成完整的 run id,形式是 run_ 加 32 個十六進位字元);問題裡沒有 run id、也沒有綁定 run 時,AI 會回答沒有可查的證據 (綁定 run 需要 Profile 模式,見 10.3)。

各步驟的細節見後續章節。


3. 安裝

STOP:安裝包與 checksum 必須經獨立可信來源驗證;未通過時不要解壓或安裝。

3.1 系統需求

項目 需求
作業系統 Linux x86_64。安裝包的說明列出 Ubuntu 24.04、RHEL/Rocky/AlmaLinux 9、CentOS Stream 9;0.1.1 只在 Ubuntu 24.04 驗證過
C 函式庫 安裝包需要 glibc 2.34 以上,以及提供 GLIBCXX_3.4.29 的 libstdc++
Qt Qt 6.7 以上、Qt 6 系列的 Desktop gcc 64-bit 預設元件;不隨附。需包含函式庫、QML imports、xcb 與 offscreen platform plugin
圖形環境 可用的 X11 工作階段;以及 xcb 相關系統函式庫(見 3.2)
Python 從原始碼安裝時需要 Python 3.12 以上與 uv;安裝包已內附 Python 3.12
建置工具 從原始碼建置 GUI 時需要 CMake 3.16 以上與 C++17 編譯器
權限 不需要 root、sudo 或 Docker

3.2 方式一:可攜式安裝包

下載與核對

請依安裝教學的獨立可信校驗與停止條件操作。忽略缺失項目的檢查無法證明目標安裝包確實已被檢查。

系統函式庫:請系統管理員提供 X11/xcb 相關套件。安裝器會用 terminux-qt-check 列出實際缺少的函式庫,但不會代為安裝。

用途 EL9 Ubuntu 24.04
xcb cursor xcb-util-cursor libxcb-cursor0
xcb utility、image、keysyms、renderutil、wm xcb-util、xcb-util-image、xcb-util-keysyms、xcb-util-renderutil、xcb-util-wm libxcb-util1、libxcb-image0、libxcb-keysyms1、libxcb-render-util0、libxcb-icccm4
XKB libxkbcommon、libxkbcommon-x11 libxkbcommon0、libxkbcommon-x11-0
X11/xcb libX11、libX11-xcb、libxcb libx11-6、libx11-xcb1、libxcb1

安裝:先停止這個帳號正在執行的 daemon(安裝器不會替你停止;共享 HOME 而 daemon 在另一台主機時,要到那台主機停止)。

身分核驗通過後,請使用安裝教學中的安裝順序。

選項 作用
--qt-dir <Qt 目錄> 指定 Qt SDK(例如 …/6.7.3/gcc_64)。已有 current/qt 時可省略
--yes 不逐項詢問
--prefix <路徑> 安裝位置,預設 ~/.local/opt/terminux
--no-bin-link 不在 ~/.local/bin 建立入口
--reinstall 重新安裝相同版本(預設遇到同版本會停止)
--force 只略過「不支援的 OS」阻擋;不會略過架構、ABI、Qt 或執行中 daemon 的檢查

安裝後的結構:

  • 每個版本裝在 ~/.local/opt/terminux/<版本>;current 指向目前使用的版本。Qt 檢查通過後才切換 current,失敗時不切換。
  • 升級時保留舊版本。
  • ~/.local/bin 只會建立兩個入口:terminux(執行 terminux-launch,也就是啟動 daemon 並開 GUI)與 terminux-qt-check。 其他命令在 ~/.local/opt/terminux/current/venv/bin/,請用完整路徑執行,或自行加入 PATH。
  • 安裝包只含基本相依,不含 Gemini、local-llm(llama.cpp)、RAG 與 Anthropic 的 extras。要用 Gemini backend 或建立 RAG 知識庫, 需要自行在安裝包的 Python 環境安裝對應套件。openai_compatible backend 不需要額外套件。
  • 不修改任何 rc 檔。

把入口加入 PATH

export PATH="$HOME/.local/bin:$PATH"          # bash
setenv PATH "$HOME/.local/bin:$PATH"          # tcsh

再次檢查 Qt

~/.local/bin/terminux-qt-check --qt-dir ~/.local/opt/terminux/current/qt --prefix ~/.local/opt/terminux/current

3.3 方式二:從原始碼安裝

Python 套件(在原始碼根目錄):

uv venv --python 3.12 .venv
source .venv/bin/activate              # tcsh:source .venv/bin/activate.csh
uv pip install './engine[gemini]'
extra 何時需要
gemini 使用 Gemini backend,或以 Gemini 做 embedding
local-llm 使用 llama_cpp backend
rag 以 terminux-build-rag-index 建立 RAG 知識庫
anthropic 只給保留中的舊通知路徑使用,一般不需要

openai_compatible backend 不需要額外套件。

GUI 與 DQE Viewer:安裝到與 Python 環境相同的 prefix。

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.7.3/gcc_64 -DTERMINUX_BUILD_TESTS=OFF
cmake --build build
cmake --install build --prefix "$VIRTUAL_ENV"

安裝後會有 $VIRTUAL_ENV/bin/terminux(GUI)與 $VIRTUAL_ENV/bin/dqe_viewer(DQE Viewer),以及它們需要的 Qt runtime 與 QML module。

使用外部 Qt(不把 Qt 部署進 prefix,改用系統上的 Qt)(未驗證):

cmake -S . -B build-external -DCMAKE_PREFIX_PATH=/absolute/path/to/Qt/gcc_64 \
  -DTERMINUX_EXTERNAL_QT=ON -DTERMINUX_BUILD_TESTS=OFF -DTERMINUX_BUILD_INTERNAL_TARGETS=OFF
cmake --build build-external --target terminux dqe_viewer
cmake --install build-external --prefix "$VIRTUAL_ENV"
ln -s /absolute/path/to/Qt/gcc_64 "$VIRTUAL_ENV/qt"
terminux-qt-check --qt-dir "$VIRTUAL_ENV/qt" --prefix "$VIRTUAL_ENV"

這個模式下執行檔以 $ORIGIN/../qt/lib 尋找 Qt,不需要設定 LD_LIBRARY_PATH、QT_PLUGIN_PATH 或 QML2_IMPORT_PATH。 多台主機使用時,Qt 目錄在每台主機都必須是相同的絕對路徑。

注意:從原始碼安裝時,terminux 是 GUI 本身;請用 terminux-launch 啟動(它會先確保 daemon 在跑)。 可攜式安裝包的 ~/.local/bin/terminux 則已經是 terminux-launch。

3.4 確認安裝

terminux --version                                   # 從原始碼安裝時印出 GUI 版本;安裝包的入口則印出啟動器版本
QT_QPA_PLATFORM=offscreen dqe_viewer --smoke-exit && echo ok
terminux-doctor                                      # daemon 啟動後執行:ready 時 exit 0

terminux-doctor 印出 JSON:socket 路徑、daemon 狀態、設定檔與內建 knowledge 是否可讀、憑證檔是否安全(不讀內容)。


4. 設定

daemon 的設定在啟動時讀取。改了環境變數或設定檔之後,要重新啟動 daemon 才會生效(5.3)。

4.1 LLM provider 與憑證

憑證檔 ~/.terminux/credentials.json:

mkdir -p ~/.terminux
cat > ~/.terminux/credentials.json <<'JSON'
{
  "TERMINUX_OPENAI_API_KEY": "<你的 API key>",
  "TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com"
}
JSON
chmod 600 ~/.terminux/credentials.json
  • 權限必須恰好是 0600、是一般檔案(不是 symlink)、屬於你;任何一項不符,整份檔案都會被忽略。
  • 支援的名稱:TERMINUX_GEMINI_API_KEY、TERMINUX_OPENAI_API_KEY、TERMINUX_OPENAI_BASE_URL。
  • 用 TERMINUX_CREDENTIALS_FILE 可指定其他位置。
  • 同名環境變數仍可使用,但只是相容的替代方式;憑證檔優先。

選擇 backend:TERMINUX_LLM_BACKEND 沒有預設值;不設定時 AI 功能關閉。

backend 需要的設定 能力
openai_compatible TERMINUX_OPENAI_MODEL(預設 deepseek-chat);憑證檔的 TERMINUX_OPENAI_API_KEY、TERMINUX_OPENAI_BASE_URL(預設 https://api.deepseek.com);選用 TERMINUX_OPENAI_TIMEOUT_SEC(預設 120 秒) 問答與 Agent;Profile 模式
gemini TERMINUX_GEMINI_MODEL(預設 gemini-3.6-flash);憑證檔的 TERMINUX_GEMINI_API_KEY;需要 gemini extra 問答與 Agent
llama_cpp TERMINUX_LLM_MODEL_PATH(本機 GGUF 檔);有 thinking mode 的模型(例如 Qwen3)另設 TERMINUX_LLM_DISABLE_THINKING=1;需要 local-llm extra 只有基本問答,沒有 Agent 能力

本機的 OpenAI 相容服務:以 openai_compatible 連線,在憑證檔設定 {"TERMINUX_OPENAI_BASE_URL": "http://127.0.0.1:8080/v1", "TERMINUX_OPENAI_API_KEY": "local"},再以 TERMINUX_OPENAI_MODEL 指定模型名稱。本機服務能否完成 Agent 流程,取決於模型與服務本身,目前尚未驗證。

設定範本:原始碼的 scripts/terminux-llm-env.sh(bash)與 scripts/terminux-llm-env.csh(tcsh)列出所有選項;取消註解其中一種 backend 後再 source。憑證不要寫在範本裡。

4.2 Embedding(搜尋索引)

過去的問答與紀錄會建立搜尋索引。embedding 的目的地與上面的 provider 分開決定:

設定 結果
TERMINUX_LLM_BACKEND=gemini,或 openai_compatible 且憑證檔有 TERMINUX_GEMINI_API_KEY 送到 Gemini embedding API(gemini-embedding-001)
TERMINUX_EMBEDDING_BACKEND=noop 關閉 embedding,只用全文搜尋
TERMINUX_EMBEDDING_BACKEND=local 與 TERMINUX_EMBEDDING_MODEL_PATH 使用本機模型

4.3 宣告 project(選用)

TERMINUX_PROJECT_ID=<名稱> 會在連線時宣告你所在的 project(舊名 TERMINUX_PROJECT 也接受)。不設定也可以正常使用; Profile 模式下,未宣告的 session 會採用 Profile 的 project。

4.4 介面語言

在終端機按右鍵 Language,選 繁體中文、English 或 简体中文。設定存在 ~/.terminux/preferences.json,影響 daemon 的 訊息、AI 回答的語言與 DQE Viewer 的起始語言;DQE Viewer 也可以在自己的標題列另外切換。未設定時是繁體中文; TERMINUX_PREFERRED_LANGUAGE 只在還沒選過時作為預設。

4.5 STA playbook(選用)

要啟用 STA 的 stage 追蹤、quality gate 與提示,把隨套件安裝的範本部署到 ~/.terminux/ecc:

mkdir -p ~/.terminux/ecc
python3 -c "from importlib.resources import files; import shutil, pathlib; shutil.copy(files('terminux_engine.ecc') / 'templates' / 'sta_signoff_playbook.yaml', pathlib.Path.home() / '.terminux' / 'ecc')"

python3 要用安裝 Terminux 的那個 Python 環境。已在執行的 daemon 要重啟才會載入;TERMINUX_PLAYBOOK_PATH 可指定其他位置。 沒有 playbook 時,daemon log 會出現一行 TERM_ECC_PLAYBOOK_UNAVAILABLE,這是正常的,其他功能不受影響。

4.6 Shell 整合

daemon 啟動時會自動安裝並更新 hook 與 wrapper(~/.terminux/bin、~/.terminux/hooks、~/.terminux/bash_hooks.sh、 ~/.terminux/tcsh_hooks.csh),不修改任何 rc 檔。設定 TERMINUX_AUTO_SETUP_WRAPPERS=0 時不會安裝,hook 也就不會送出通知。

shell 怎麼啟用
GUI 內建的 bash 自動。GUI 以 --rcfile 先載入你的 ~/.bashrc,再載入 Terminux 的 hook
GUI 內建的 tcsh 在 ~/.tcshrc(沒有才用 ~/.cshrc)加一行:if ( $?TERMINUX_ACTIVE ) source ~/.terminux/tcsh_hooks.csh(未驗證)
外部的 bash 終端機 不會自動整合;要用的話在 ~/.bashrc 加:[ -f ~/.terminux/bash_hooks.sh ] && source ~/.terminux/bash_hooks.sh
  • TERMINUX_ACTIVE=1 由 GUI 注入,讓 tcsh 那一行只在 Terminux 終端機內生效。
  • csh/tcsh 啟動後 10 秒內 GUI 沒收到 hook 的標記時,會顯示一次設定提示。
  • 傳統 csh 沒有 tcsh 的自動 postcmd/precmd 機制。
  • 互動提示出現前,wrapper 目錄會被移到 PATH 最前面,EDA 命令因此會經過 wrapper。

4.7 Profile 模式(管理者設定)

Profile 模式把 AI 的對話限制在管理者指定的範圍內,並開放 @@/bind-run。它只支援 openai_compatible backend。 daemon 啟動時讀取下列環境變數;兩個檔案都必須是本人擁有、權限 0600 的一般檔案,以絕對路徑指定。內容有任何不合法之處,整份視為 無效,所有 AI 請求都會被拒絕,不會退回沒有限制的模式。

環境變數 內容
TERMINUX_AGENT_TASK_PROFILE_FILE Profile(JSON):AI 可用的工具、可帶入的對話內容、允許的 run,以及 /bind-run 的規則
TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE 外送 policy(JSON):允許的 endpoint 與 model、可外送的資料類別與各項上限
TERMINUX_EGRESS_AUDIT_DIGEST 外送紀錄的雜湊方式:plain_sha、keyed_ephemeral 或 keyed_persisted(後者另需 TERMINUX_EGRESS_AUDIT_KEYRING_FILE)。policy 使用 structural_c2 時必須設定

Profile 範例(只允許查詢執行證據,允許綁定 nangate45/gcd 的 host-native 執行):

{
  "profile_id": "gcd-evidence",
  "tools": ["query_orchestration_evidence"],
  "context_sections": ["conversation_history"],
  "allowed_runs": {},
  "run_binding": {
    "max_runs_per_session": 2,
    "require_runner": "host_native",
    "allowed_designs": ["nangate45/gcd"],
    "max_age_sec": 604800
  }
}
  • tools 目前只能是 query_orchestration_evidence;context_sections 只能是 conversation_history。
  • allowed_runs 是預先允許的 run id 與 attempt,一般留空,改用 run_binding 讓使用者自己綁定。
  • run_binding 四個鍵都必填:每個 session 最多綁定幾次(1~8)、receipt 的 runner(terminux-orfs-run 是 host_native)、允許的 <platform>/<design>、receipt 距今的最長秒數。

外送 policy 範例(v2、structural_c2;DeepSeek 的 deepseek-chat):

{
  "policy_version": "terminux.egress_policy.v2",
  "approval_mode": "structural_c2",
  "endpoint": "https://api.deepseek.com/v1/chat/completions",
  "model": "deepseek-chat",
  "allowed_payload_sha256": [],
  "approved_data_classes": ["system_instructions", "learner_text", "conversation_history",
                            "tool_schema", "tool_call", "evidence_bundle", "model_output",
                            "budget_summary"],
  "limits": {"learner_text_max_chars": 4000, "history_max_turns": 20, "history_max_chars": 60000,
             "model_output_max_chars": 60000, "requests_per_turn": 4},
  "non_agent_egress": "deny"
}
  • endpoint 必須等於 <TERMINUX_OPENAI_BASE_URL>/v1/chat/completions,model 必須等於 TERMINUX_OPENAI_MODEL;不一致時每個請求都會被拒絕。
  • approved_data_classes 列出允許外送的資料類別;timing_path_evidence(timing path 的逐級資料)不列出就不會送出。limits 五個鍵都必填。
  • allowed_payload_sha256 在 structural_c2 模式必須是空的;exact_digest 模式則只放行清單內的請求內容。
  • 每個外送決策都記在 ~/.terminux/run/<nodename>/egress_audit/<日期>.jsonl,只有中繼資料與雜湊、沒有內容,保存 90 天。
  • Profile 模式下,Engineering Work 的 provider binding 不會啟用(11.2)。

5. 啟動、停止與狀態

5.1 啟動

terminux-launch            # 啟動或沿用 daemon,再開 GUI(安裝包的 ~/.local/bin/terminux 就是這個指令)
terminux-launch --no-gui   # 只確保背景服務在跑
terminux-launch --reset    # 顯示 owner 資訊,輸入 yes 後只刪除 owner lock(不會停止任何 daemon)
  • 每個帳號只有一個 daemon。terminux-launch 讀 ~/.terminux/run/owner.lock/owner.json:沒有 daemon 就啟動一個並最多等 30 秒到就緒; daemon 已在本機就沿用;daemon 在另一台共享 HOME 的主機時,改啟動本機轉送(5.5)。
  • 等 30 秒仍未就緒時只會警告,繼續開 GUI;這時 hook 可能還沒部署。
  • GUI 的尋找順序:TERMINUX_GUI_BIN → <Python 環境>/bin/terminux → <Python 環境>/../bin/terminux → PATH。
  • daemon 使用啟動 terminux-launch 的那個 shell 的環境變數。要換 backend 或 Profile,請在新的設定下重啟 daemon。

5.2 確認狀態

方法 看什麼
terminux-doctor "status": "ready" 且 exit 0
GUI 標題列與狀態列 連不上 daemon 時標題列會出現警告;GUI 每 3 秒自動重連
cat ~/.terminux/run/owner.lock/owner.json state 為 ready;host、pid 是 daemon 所在的主機與行程。此檔含 TCP 轉送的 token,請不要外流

5.3 停止與重新啟動

Terminux 沒有 stop 指令。在 daemon 所在的主機上:

cat ~/.terminux/run/owner.lock/owner.json      # 找到 pid
kill -TERM <pid>
while [ -e ~/.terminux/run/owner.lock ]; do sleep 1; done   # owner lock 消失=已乾淨關閉
terminux-launch --no-gui                       # 在想要的環境設定下重新啟動
  • 已開著的 GUI 會自動重新連線,不必重開;但會取得新的 session。綁定的 run、待核准的提案、計畫與執行結果只存在 daemon 記憶體中,重啟後都會清空。 task 與 Engineering Work 的歷史保存在事件紀錄中;上一次 daemon 留下的未完成 task 會顯示為唯讀的 INTERRUPTED。
  • daemon 異常結束(例如被 SIGKILL)或主機重開機後,下次在同一台主機啟動時會自動判定並回收殘留的 owner lock。
  • 若停止後 owner lock 一直沒有消失,daemon.log 會有 TERM_DAEMON_OWNER_LOCK_RETAINED:daemon 無法確認資料已乾淨關閉而刻意保留鎖。 請先確認沒有 daemon 行程,再決定是否用 terminux-launch --reset。

5.4 Log 位置

內容 位置
daemon 的結構化訊息 ~/.terminux/run/<nodename>/daemon.log(10 MiB 輪替,保留 3 份備份)
daemon 取得所有權前的輸出 ~/.terminux/run/<nodename>/daemon.stdout.log
轉送服務 同目錄的 relay.log、relay.stdout.log

daemon 預設只記錄 ERROR,正常運作時 log 是空的,不代表故障。除錯時以 TERMINUX_LOG_LEVEL=INFO(或 DEBUG、WARNING)重啟 daemon。 <nodename> 是主機名稱;TERMINUX_NODENAME 可覆寫。

5.5 多台 login server(未驗證)

同一個帳號從多台 login server 登入、而 HOME 是共用的(例如 NFS)時:

  • 每個帳號只有一個 daemon(owner)。在其他主機執行 terminux-launch 時,會啟動 terminux-relay,在本機提供同樣的 socket, 並以 token 連到 owner 的 TCP 埠。
  • TCP 轉送沒有加密,只能在受信任的網段使用。只用單機時可設 TERMINUX_UNIX_ONLY_IPC=1 不開 TCP。
  • Python 環境與 GUI 執行檔在各主機必須位於相同路徑。
  • 直接開啟資料庫的命令(例如 terminux-orfs-run)在 owner 位於其他主機時會以 exit code 5 拒絕,請到 owner 主機執行。
  • 已知限制:owner 換到別台主機後,原主機的 GUI 要再執行一次 terminux-launch --no-gui 才會恢復連線;多個 GUI 會同時顯示同一則通知的 action,重複點擊會執行多次;GUI 斷線太久時,超過 500 筆緩衝的通知會遺失。
  • 多主機限制:只在模擬環境(兩台 VM、NFSv4.2)驗證過,正式站點與 NFSv3、時鐘偏差、混用不同 OS 等情況都還沒有驗證。

6. 使用 Terminux 終端機

6.1 視窗

  • 終端機:你的 shell。
  • 通知列:視窗上方,顯示 lineage 檢查、AI 回答與其他通知。回答出現幾秒後會收合成標題列;點標題列,或按右鍵 Notification Bar ▸ Show 可以重看。
  • 選單列:View ▸ Work Panel 開關 Engineering Work 面板(預設隱藏;未驗證);Help ▸ About Terminux、About Qt。

6.2 右鍵選單

項目 作用
Copy(Ctrl+Shift+C)、Paste(Ctrl+Shift+V)、Select All、Clear Terminal 一般終端機操作
Notification Bar ▸ Show/Remove Oldest 10 Messages/Remove All Messages 重看或清理通知列
Language ▸ 繁體中文/English/简体中文 介面與 AI 回答的語言(4.4)
Open URL 選取的文字是網址時出現,用瀏覽器開啟
Font Size +(Ctrl+=)、Font Size -(Ctrl+-)、Reset Font Size(Ctrl+0) 字型大小
Ask AI about this 以選取的文字提問(10.1)

6.3 已知現象

GUI 內建的 bash 在每個命令結束後會多一行 [1]+ Done … terminux-notify post_exec …。這是 hook 背景工作的回報,不影響命令本身。


7. Lineage 檢查

Lineage 檢查回答「這一步讀到的輸入是不是對的版本」。

  • 什麼時候檢查:你在 Terminux 終端機送出命令後,GUI 請 daemon 檢查。命令已經先開始執行,檢查結果只是事後提示,不會攔下命令。

  • 怎麼判斷:對認得的 EDA 工具,daemon 讀取命令帶的 runfile(-f <runfile>)宣告的輸入,與過去的紀錄比對:

    結果 通知列
    一致(CONSISTENT) 不提示
    混用了不同來源(MIXED_LINEAGE) 警告
    證據不足(INSUFFICIENT_EVIDENCE) 警告
    不支援的工具(UNSUPPORTED_TOOL) 不提示
  • 留下紀錄:成功結束、且帶 -f <runfile> 的 EDA 命令,daemon 會把 runfile 宣告的輸入與輸出記到 ~/.terminux/lineage/ledger.jsonl。 daemon 只讀這些檔案,不會建立或修改它們。wrapper 另外把每台主機的執行紀錄寫到 ~/.terminux/lineage.<nodename>.jsonl。

  • 選用的 LLM 輔助(預設關閉,開啟後會外送資料,見 第 13 節):

    • TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME=1:檢查有疑慮時請 LLM 說明。
    • TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME=1:固定格式讀不出 runfile 時請 LLM 解析(會送出完整的 runfile 內容)。
  • 看圖:@@ 問題中含「lineage graph」「血緣圖」等字時,會產生 lineage graph 的 HTML(10.5)。


8. 執行 ORFS

terminux-orfs-run 在你的帳號下、直接在主機上執行一次 ORFS flow,並留下收據、產物清單與品質判定。不需要 Docker、container、sudo 或 root, 也不需要 ORFS 安裝目錄的寫入權;以 root 執行會被拒絕。

8.1 前置條件

  • CAD/IT 管理者已安裝 ORFS 與 EDA 工具(OpenROAD、Yosys、KLayout)。
  • ORFS 的最後一步需要 KLayout:klayout 必須在執行時的 PATH 上,或由 --env-script 加進 PATH。找不到時 flow 會在 check-klayout 停下並以 exit code 1 結束,前面各階段的輸出與品質紀錄仍會保留。
  • 一個你自己擁有的輸出目錄。

8.2 執行

terminux-orfs-run --orfs-repo-root /path/to/OpenROAD-flow-scripts \
  --work-home ~/orfs-runs/my-run --design gcd --platform nangate45 --variant my-run \
  --design-config ./designs/nangate45/gcd/config.mk \
  --ledger-db ~/orfs-runs/my-run-ledger.sqlite --receipt-out ~/orfs-runs/my-run-receipt.json

結束時 stdout 會印出品質摘要與這次的 run id;收據寫到 --receipt-out,並預設寫入你的事件紀錄,daemon 與 @@ 因此查得到這個 run。

8.3 參數

參數 必填 說明
--orfs-repo-root 是 ORFS 安裝根目錄(含 flow/),可以是唯讀的
--work-home 是 這次執行的輸出目錄(ORFS 的 WORK_HOME),必須由你擁有;上層存在時會建立最後一層。results/、reports/、logs/、objects/ 都寫在這裡
--design 是 design 名稱;必須等於 ORFS 輸出目錄使用的名稱(DESIGN_NICKNAME,未設定時為 DESIGN_NAME),不一致時 flow 開始前就停止
--platform 是 例如 nangate45
--variant 是 ORFS 的 FLOW_VARIANT;不可以是 base。它也會成為 step id 的一部分並可能隨證據送給 LLM provider,請勿使用機密名稱
--design-config 是 config.mk 相對於 ORFS flow/ 的路徑;設定檔必須位於 flow/ 之下
--ledger-db 是 這次執行專用的 ledger 檔。不可以指向 daemon 的 ~/.terminux/orchestration/ledger.sqlite(含 symlink、hard link 等別名)
--receipt-out 是 收據 JSON 的輸出路徑
--env-script 否 讓 EDA 工具可用的環境 script,預設 <orfs-repo-root>/env.sh。Terminux 除了 HOME、LANG、PATH 不繼承你 shell 的環境
--make-executable 否 執行 flow 的 make,預設為 PATH 上的 make
--openroad-exe、--yosys-exe 否 明確指定工具(ORFS 的 OPENROAD_EXE、YOSYS_EXE)
--timeout-seconds 否 執行時間上限,預設 900 秒
--receipt-store 否 把收據寫到指定的事件紀錄檔,而不是預設位置(與 --no-receipt 二選一)
--no-receipt 否 不寫入任何事件紀錄(--receipt-out 仍會寫出)

沒有 ORFS 安裝目錄的寫入權、又需要改設定時:自備一份 --env-script,先 source 原本的 env.sh,再 export 設定檔中以 ?= 定義的變數 (例如 CORE_UTILIZATION)。env script 的內容雜湊會記在收據內。

8.4 Exit code

exit code 意義
0 執行成功,且收據已寫入(--no-receipt 時只看執行結果)
1 執行失敗
2 參數或環境錯誤(含以 root 執行、--work-home 不屬於你、--ledger-db 指向 daemon 的 ledger、找不到 env script 或 make)
3 執行成功,但收據沒有寫入
5 daemon 在另一台主機,拒絕直接開資料庫
130/143 收到 Ctrl-C/SIGTERM

品質判定的結果(例如 timing fail)不影響 exit code。

8.5 中斷(未驗證)

按 Ctrl-C 或送 SIGTERM 時,Terminux 會先終止 flow 的整個 process group 並確認它已結束,才寫入 cancelled 收據,再以原 signal 結束 (shell 看到 130/143)。無法確認時不寫收據,stderr 顯示 EXECUTION_CLEANUP_UNCONFIRMED。

8.6 查看驗證過的 report

terminux-orfs-report --receipt ~/orfs-runs/my-run-receipt.json --run-id <run_id> --attempt <attempt>
參數 說明
--receipt、--run-id、--attempt 必填。run id 與 attempt 在收據內,也印在 terminux-orfs-run 的結尾
--role orfs.finish_report(預設)或 orfs.route_drc_report
--stage N 改成定位 finish report 中 timing path 的第 N 級(從 1 開始),不印整份 report
--expect-line L 搭配 --stage,要求該級位於 report 的第 L 行
--view 搭配 --stage,以 less 在該行開啟已驗證的 report(需要終端機)

這個命令會先核對 report 的雜湊與收據、產物清單一致才顯示,因此你看到的就是那一次執行的 report。成功時 exit 0,錯誤時 exit 2。


9. 品質判定(DQE)與 DQE Viewer

9.1 判定了什麼

ORFS 執行結束後,orfs_dqe 以固定規則(不使用 LLM)解析 6_finish.rpt、5_route_drc.rpt、6_report.log 與產物清單,對下列 14 項逐項判定:

檢查 說明 必要項目
orfs_manifest_integrity 產物清單的身分與雜湊 是
orfs_artifact_completeness 必要的產物都存在且穩定 是
orfs_final_deliverables 已產生最終的 layout、DEF、database、netlist 是
orfs_process_exit_code 工具行程的 exit code 是
orfs_setup_wns Setup worst negative slack(WNS),小於 0 為違規 是
orfs_setup_tns Setup total negative slack(TNS) 否
orfs_setup_violation_count Setup 違規路徑數 是
orfs_hold_violation_count Hold 違規路徑數 是
orfs_max_slew_violation_count Max transition(slew)違規數 否
orfs_max_fanout_violation_count Max fanout 違規數 否
orfs_max_cap_violation_count Max capacitance 違規數 否
orfs_route_drc_violation_count Detailed route 的 DRC 違規數 是
orfs_log_error_markers ORFS log 中的錯誤標記 是
orfs_log_warning_markers ORFS log 中的警告標記 否

每一項的結果是 pass、warn、fail 或 unknown。整體結果的規則:任何必要項目 fail → fail;否則任何一項 warn → warn; 否則任何必要項目 unknown → unknown;否則 pass。非必要項目的 unknown 不會讓整體結果變成 pass。結果有 warn、fail 或 unknown 時會發一則通知。品質判定只給出結果,不做根因推論,也不會重跑或修改設計。

9.2 開啟 DQE Viewer

在 Terminux 終端機輸入:

@@open DQE Viewer

這個指令由 Terminux 在本機處理,不會送出 AI 請求。Viewer 由 GUI 在你的主機上啟動,預設使用與 GUI 同目錄的 dqe_viewer;要用別的 執行檔時設定 TERMINUX_DQE_VIEWER_BIN。終端機外可用 terminux-chat "open DQE Viewer"(未驗證)。

9.3 Temporary 工作區

每次執行寫入的品質紀錄以 job 為單位,出現在 Temporary(暫存)工作區:

  • 工作區列出 job,可用「搜尋 job_key / block / flow」找;選一個 job 會列出它的 DQE 項目,可依狀態篩選(通過/警告/失敗/未知, 例如選「失敗」只看 fail 的項目)。
  • 選取一個項目可以看它的值、單位、說明、來源路徑與附件預覽。
  • 標頭顯示總計與各狀態數量(例如 total 14、pass 10、warn 2、fail 2)。

9.4 Archived 工作區與 check-in(未驗證)

  • Check in whole job(簽入整個 job)把一個 temporary job 整理成 archived package,並透過外部的 isvn 工具 check-in 到你指定的版本路徑; 可以先用 Check-in dry-run(簽入試跑)確認。isvn 為獨立發布的產品,需另行安裝。
  • Archived(已歸檔)工作區列出已 check-in 的版本,可依 phase/block/version 篩選。

9.5 Compare 工作區

  • Compare(比較)以第一個來源為 baseline(100%),畫出各 DQE 指標的正規化趨勢,也可以看原始數值與相對 baseline 的差。
  • 可用 Export HTML 把比較結果匯出成 HTML。
  • 勾選多個 job 做比較的操作在 0.1.1 未驗證。

9.6 保留期與清除

  • 保留期:Temporary 的保留天數是適用所有 temporary job 的全域政策,在 Viewer 的 Temporary retention policy 用 Edit policy 修改、 Save policy 儲存(存在 ~/.terminux/dqe/retention_policy.json)。
  • 手動清除:先 Preview selected job purge(預覽清除選取 job)或 Preview expired jobs purge(預覽清除已過期 job),確認清單後才會執行。
  • 排程清除:dqe-scheduled-clean(可加 --dry-run 先看結果、--no-vacuum、--db <路徑>、--policy <路徑>、--log <路徑>)。 預設 log 在 ~/.terminux/dqe/scheduled_clean.log。

品質資料庫預設在 ~/.terminux/dqe/dqe.sqlite;TERMINUX_DQE_DB_PATH 可指定其他位置。


10. 使用 AI(@@)

需要先設定 LLM backend(4.1)。Agent 只在 openai_compatible 與 gemini 可用。

10.1 提問

  • 在 Terminux 終端機的提示字元後輸入 @@,後面接問題,按 Enter。這一行不會交給 shell 執行,回答顯示在通知列。
  • 另一種方式:用滑鼠選取終端機上的文字,按右鍵 Ask AI about this,選取的文字就是問題;之後用 @@ 追問會接續同一段對話。
  • @@ 後面的文字是交給 Terminux 的,shell 變數不會展開,路徑請寫完整的絕對路徑。

10.2 AI 能做與不能做

  • AI 只能查詢已記錄的執行證據(收據、產物清單、品質結果)。它不能讀取你的檔案、不能執行 shell 命令,也不會替你核准或執行任何動作。
  • 沒有可查的證據時,AI 會直接說明沒有證據,只給一般性的說明。
  • AI 看到的是品質摘要,不是 report 本身;timing 數值請用 DQE Viewer 與 terminux-orfs-report 自己核對。

10.3 針對一次 ORFS 執行提問

  1. 以 terminux-orfs-run 執行 flow。--receipt-out 寫出的收據裡有這次執行的 run_id 與 attempt;stdout 最後的品質摘要也會列出 run id。

  2. 綁定這次執行(需要 Profile 模式,4.7):

    @@/bind-run /absolute/path/to/receipt.json
    

    成功時通知列顯示 RUN_BOUND: run_… attempt 1 is now bound to this session (host_native nangate45/gcd).。綁定只存在這個視窗的 session 內,daemon 重啟後消失;@@/unbind-run 解除。

  3. 直接提問,例如:

    @@For the Run I just bound, which DQE checks are WARN or FAIL? Show the run evidence and where I can verify it.
    @@Based on the evidence from this run, what should I inspect next, and why?
    

    沒有 Profile 模式時,把 run id 寫在問題裡也可以讓 AI 查詢同一份證據。

  4. 自己核對:@@open DQE Viewer 在「失敗」篩選下看各項檢查;terminux-orfs-report 印出經驗證的 finish report。

10.4 解說與比較:明確指令

雲端 backend 的 AI 不會從自然語言自行建立待核准的動作。要讓 Terminux 執行「解說一次 run」或「比較兩次 run」,用下列四步。 這組指令只在一般模式可用:Profile 模式下只有 /bind-run、/unbind-run 兩個本機指令,其他指令都會回 LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE。

步驟 指令 作用
1 @@/plan-only <目標> 產生一份計畫,不執行任何步驟、不建立提案。例:@@/plan-only 規劃如何分析這次 run 為什麼沒過品質判定,只產生計畫、不要執行。
2 @@/plan-propose <plan_id> <step_id> 針對計畫中的一個步驟建立提案;仍然不執行
3 @@/approve <proposal_id> <proposal_digest> 核准這個提案(/reject 拒絕)。提案 10 分鐘內未核准會過期
4 @@/execute <proposal_id> <proposal_digest> 執行一次。參數必須與提案時完全相同;不能重複執行
  • @@/proposals 列出提案;@@/plans、@@/plan <plan_id> 查看計畫,@@/cancel-plan <plan_id> <plan_digest> 取消計畫。
  • @@/results 列出執行結果;@@/use-result <result_id> <result_digest> 讓後續的提問帶入這份結果,@@/clear-result 取消。 執行結果只存在 daemon 記憶體中,保存 30 分鐘。
  • 沒有整份計畫一次核准或一次執行的功能:/approve-plan、/execute-plan、/approve-all 一律被拒絕,每一步都必須各自 /approve、/execute。
  • 一份計畫只放一個步驟。帶有相依步驟的計畫目前無法逐步提案,請一次規劃一個步驟。
  • 未核准就執行、digest 錯誤、重複執行都會被拒絕。
  • 已知限制:兩次 run 的比較結果最多是「有條件可比」(conditionally_comparable)。比較沒有使用執行紀錄中的設定檔與 env script 雜湊, 無法證明兩次 run 之間只有你宣告的那一項不同;指標差異照實列出。

10.5 不經 AI 的指令

輸入 作用
同時含「DQE Viewer」與開啟動詞(開啟、打開、啟動、顯示、open、launch、start、show),例如 @@open DQE Viewer 開啟 DQE Viewer
含「lineage graph」「lineage dag」「show lineage」「血緣圖」等 產生 lineage graph 的 HTML 並開啟(瀏覽器會從 jsDelivr 載入固定版本的 Mermaid)
以 / 開頭的已知指令 由 Terminux 本機處理(第 10.3、10.4 節與第 11 節)

10.6 Profile 模式下的差異

  • 系統提示只有 Profile 的指示、這個視窗的對話紀錄與已綁定的 run;其他 session 狀態、工作摘要、其他 terminal 的狀態都不會送出。
  • 本機指令只剩 /bind-run、/unbind-run;/plan-only、/approve、/execute、/task…、/work… 等都會回 LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE。反過來,一般模式下 /bind-run 不是本機指令。所以「綁定 run 後提問」與「以明確指令執行解說或比較」 無法在同一個 daemon 設定下並用。
  • Profile 模式只支援 openai_compatible;用其他 backend 時回 PROFILE_PROVIDER_UNSUPPORTED,不送出任何請求。
  • 沒有綁定 run、問題也沒有附帶文字時,AI 只給一般性的說明或請你先綁定 run;例如選取 config.mk 的一行按 Ask AI about this,會得到 「請先綁定 run 或明確提問」,而不是那一行的解釋。

11. 有界任務與 Engineering Work(未驗證)

這一節的功能在 0.1.1 沒有以公開產物驗證。本節的 @@ 指令只在一般模式可用(Profile 模式下停用)。

11.1 Task

Task 先建立草稿,經你核准後由 daemon 依固定步驟執行;同時執行的數量有上限,超過時排隊。

指令 作用
@@/profile <Profile 的絕對路徑> 在這個 session 選用一份 Profile
@@/profiles 列出這個 session 已選用的 Profile
@@/task-create <profile_id> <問題…> 以已選用的 Profile 建立 flow task 草案(尚未執行任何 EDA)
@@/task-start <task_id> <task_digest> 授權並開始(只需授權這一次)
@@/task <task_id> 查詢一筆 task
@@/task-cancel <task_id> <task_digest> 要求停止
@@/tasks 列出這個 daemon 內你的所有 task

flow task 的固定流程是:跑 baseline → 解說 → 依核准的一項變更建立候選 → 跑候選 → 比較。

11.2 Engineering Work

Engineering Work 是有總預算的多輪工程工作:你提出目標與條件,經授權後由系統協作提出方案、在核准後執行,並依實際的工程證據判斷是否達標。

  • 前置條件:管理者以 TERMINUX_EAP3_BINDINGS_FILE 提供 provider bindings 設定檔;沒有設定時這個功能不會啟用,terminux-work list 會回報錯誤。Profile 模式下不會啟用。

  • 命令列:

    terminux-work [--profile-path <Profile>] create <profile_id> <package_id> "<目標>" [--criterion …] [--constraint …]
    terminux-work authorize <work_id> --mode PLAN_ONLY|PER_PROPOSAL|BOUNDED_EXPLORATION
    terminux-work approve <work_id>
    terminux-work continue <work_id>
    terminux-work get <work_id>
    terminux-work list
    terminux-work answer <work_id> "<回答或補充>"
    terminux-work pause|resume|cancel|takeover <work_id>
    

    authorize 可另外限制次數與範圍:--attempts(預設 2)、--provider-dispatches(預設 12)、--tool-launches(預設 5)、 --candidate-materializations(預設 2)、--formal-proof-launches、--baseline-tool-launches、--allowed-method、--allowed-change-json、 --writable-root、--stop-condition。

  • 終端機內:@@/works、@@/work <work_id>、@@/work-create、@@/work-authorize <work_id> <plan|proposal|bounded>、@@/work-approve、 @@/work-continue、@@/work-answer、@@/work-pause、@@/work-resume、@@/work-cancel、@@/work-takeover;或用 View ▸ Work Panel。


12. 其他工具

工具 用途 狀態
terminux-chat "<問題>" 在 Terminux 終端機以外的地方問 @@;每次都是新的 session 未驗證
terminux-lineage-graph [--ledger PATH] [--session S1,S2] [--output PATH] [--no-open] 產生 lineage graph 的 HTML;trace --session SESS 產生執行追蹤圖 未驗證
terminux-dream --user-id <帳號> --date <yesterday|today|YYYY-MM-DD>;--backfill --days N 手動產生工作摘要(平常由 daemon 自動產生) 未驗證
terminux-build-rag-index [--source-dir DIR] [--index-dir DIR] 從 ~/.terminux/rag_knowledge 建立你自己的 RAG 知識庫索引(~/.terminux/rag_index);需要 rag extra 與 embedding 設定 未驗證
terminux-tool register <tool_id> [--executable NAME]、unregister、list 自行登記 EDA 執行檔,不需要管理者權限 未驗證
terminux-package-install <目錄> [--replace]、terminux-package-uninstall <id>、terminux-package-status [<id>] [--activate] 安裝、移除、查看自己的 package(安裝到 ~/.terminux/packages);--activate 請執行中的 daemon 重新載入,不需重啟 未驗證
terminux-package-new <id> --root DIR、terminux-package-validate、terminux-package-test --root DIR --package ID、terminux-package-doctor --root DIR 開發 package:產生骨架、離線驗證、本機測試、診斷 只確認 --help

terminux-chat、terminux-dream、terminux-lineage-graph、terminux-build-rag-index 隨原始碼的 scripts/ 提供。


13. 資料、隱私與安全

13.1 資料放在哪裡

所有紀錄都在你自己帳號的 ~/.terminux:事件紀錄、品質資料庫、執行收據、產物清單、lineage 紀錄、搜尋索引與 log。完整清單見 附錄 C。

13.2 什麼時候會送資料給 LLM provider

TERMINUX_LLM_BACKEND、TERMINUX_EMBEDDING_BACKEND 都沒有設定、也沒有 ~/.terminux/llm_router.yaml 時,Terminux 不會把資料送給任何 LLM provider。設定之後,下列功能會把資料送到所選的 provider。gemini 與 openai_compatible(例如 DeepSeek)是雲端服務;llama_cpp 與 本機的 OpenAI 相容服務只在本機處理。

功能 何時送出 送出的資料
AI 問答與 @@ Agent 你提問時 問題與對話紀錄;目前 session 的狀態(stage、corner、block、gate 結果、WNS,以及最近的 lineage 檢查,含命令與工作目錄);工作摘要與相關的過去問答;其他 terminal 的狀態。Agent 另外只送出它查到的執行證據:所查 run 的狀態與結束原因、step 與工具的識別、收據與產物清單的識別碼與雜湊、DQE 結果,以及 report 與 lineage 的索引(只有雜湊與大小,不含檔案內容)。timing path 的逐級資料預設不送出
ORFS run 的解說、比較與狀況評估 你透過 @@ 要求時;狀況評估也會在新的 ORFS run 寫入品質結果後自動執行(未驗證) run 的識別資訊(design、platform、variant)、DQE 結果與 metrics、ORFS report/log 的節錄,以及與 baseline 的比較
工作摘要 終端機閒置一段時間後再次使用時,以及 daemon 啟動時補做先前的摘要 時段內用過的 EDA 工具、corner、gate 結果、WNS 變化、問答次數與對話重點
對話整理 對話紀錄過長時 對話內容
block 名稱推斷 載入 STA playbook 後,執行命令前判斷不出所屬 block 時(tcsh hooks 會對每個命令做這項判斷) 命令與工作目錄
Embedding(搜尋索引) 背景執行;建立 RAG 知識索引時 問答、AI 回覆、提示訊息、lineage 檢查訊息、對話重點與工作摘要;搜尋時的問題;知識文件內容
Lineage 說明(預設關閉) 設定 TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME=1,且 lineage 檢查有疑慮時 命令、工作目錄、runfile 路徑、檢查結果與相關檔案的訊息
runfile 解析備援(預設關閉) 設定 TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME=1,且固定格式解析器讀不出 runfile 時 完整的 runfile 內容、命令、工作目錄與 runfile 路徑
  • 自動的狀況評估、工作摘要與對話整理沒有個別開關;不設定 backend 就不會送出。
  • 若 /projusers/<project>/<帳號>/.terminux/event_store.sqlite 存在且可讀(<project> 是 HOME 上一層目錄的名稱),AI 問答也會帶入同一 project 其他成員的帳號、block、corner 與 WNS 摘要。
  • Profile 模式下只送出 Profile 的指示、這個視窗的對話紀錄、已綁定的 run 與查到的證據,並以外送 policy 限制(4.7)。
  • 設計腳本、路徑、設計名稱與 timing 結果屬於機密時,請先確認 provider 的資料處理條款,或只使用本機 provider。--design、--variant 也可能隨證據送出,請勿使用機密名稱。

13.3 其他連線

  • lineage graph 的 HTML 在瀏覽器開啟時,會從 jsDelivr 下載固定版本的 Mermaid,並以 Subresource Integrity 驗證;這個下載不含任何 Terminux 資料。
  • 多台 login server 使用的 TCP 轉送只有 token 認證、沒有加密(5.5)。
  • 可攜式安裝包在安裝時不連網。

13.4 憑證與存取

  • 金鑰只從權限 0600 的憑證檔(或相容的環境變數)讀取;terminux-doctor 只檢查檔案是否安全,不讀內容。
  • daemon 只接受同一個 Linux 帳號的連線;連線的身分由系統核對,不採信 client 自己宣稱的帳號。
  • Profile、外送 policy 與 keyring 檔都必須是本人擁有、權限 0600 的一般檔案。

14. 維護

14.1 診斷

terminux-doctor

不呼叫 provider、不執行 EDA。"status": "ready"(exit 0)表示 daemon 就緒、設定檔與內建 knowledge 都可讀;"attention"(exit 1) 時看 JSON 內各欄位。

14.2 備份與還原(只確認 --help)

terminux-cold-backup 只在 daemon 已停止(沒有 ~/.terminux/run/owner.lock)時運作:

# 建立:目的地必須是尚不存在的絕對路徑;來源以 LABEL=/絕對路徑 指定,彼此不得重疊、不得含 symlink
terminux-cold-backup create /backup/terminux-20261110 \
  --source ecc=$HOME/.terminux/ecc --source dqe=$HOME/.terminux/dqe \
  --source orch=$HOME/.terminux/orchestration --source lineage=$HOME/.terminux/lineage

# 驗證:重算每個檔的 SHA-256
terminux-cold-backup verify /backup/terminux-20261110

# 還原:target 必須與備份時的原始路徑相同,且目前不存在
terminux-cold-backup restore /backup/terminux-20261110 \
  --target ecc=$HOME/.terminux/ecc --target dqe=$HOME/.terminux/dqe \
  --target orch=$HOME/.terminux/orchestration --target lineage=$HOME/.terminux/lineage
  • 建議備份:ecc/(事件紀錄)、dqe/(品質資料庫與保留期政策)、orchestration/、lineage/(含產物清單)、memory/(搜尋索引沒有重建工具)、 terminux.db、tools/、packages/、preferences.json。run/ 是執行期檔案,不需要備份。
  • 憑證檔與 Profile、policy、keyring 檔不要放進一般備份,請另外妥善保管。
  • 成功時輸出 JSON 並 exit 0;前置條件不符時輸出 {"status": "error", "reason": …} 並 exit 2。

14.3 升級前檢查(只確認 --help)

terminux-rollback-check --event-store ~/.terminux/ecc/event_store.db \
  --agent-socket ~/.terminux/run/<nodename>/terminux.sock --lineage-socket ~/.terminux/run/<nodename>/lineage.sock

以唯讀方式核對事件紀錄內的資料格式是否為這一版支援的範圍。它不切換程式,也不還原資料。

14.4 清除舊資料

  • 事件紀錄:python -m terminux_engine purge --from YYYY-MM-DD --to YYYY-MM-DD 先預覽筆數;加 --force 才會刪除,刪除前會先把區間內的事件 寫成 JSONL 到 ~/.terminux/ecc/archive/。建議在 daemon 停止時執行;python 要用安裝 Terminux 的那個環境(安裝包是 ~/.local/opt/terminux/current/venv/bin/python)。
  • 品質資料庫:見 9.6。
  • lineage 的 wrapper 紀錄:超過 10 MiB 時 daemon 會自動 gzip 備份並開新檔,保留 3 份。

14.5 升級 Terminux

  • 安裝包:停止 daemon,對新版本執行 ./install.sh;Qt 檢查通過後 current 切換到新版本,舊版本保留。資料(~/.terminux)不受影響。
  • 原始碼:更新原始碼後重新 uv pip install './engine[...]',並重新建置、安裝 GUI;然後重啟 daemon。

14.6 移除 Terminux

~/.local/opt/terminux/current/uninstall.sh --version <版本>     # 移除指定版本
~/.local/opt/terminux/current/uninstall.sh --all                # 移除全部版本

預設保留 ~/.terminux 的資料、設定與 log;加 --purge-data 才清除資料,而且即使加了 --yes,仍須輸入完整的資料路徑確認。移除器不修改任何 rc 檔;請自行刪除不再使用的 hook 行。從原始碼安裝時,刪除 Python 環境與安裝的執行檔即可。要先移除 wrapper 與 hook,可執行已安裝套件內的 terminux_engine/resources/scripts/terminux-setup-wrappers --remove:它只移除 Terminux 自己建立、且未被改寫的檔案,保留其他檔案與 rc 設定。


15. 疑難排解

症狀 可能原因 處理
@@ 沒有回應或回錯誤 沒設 TERMINUX_LLM_BACKEND;憑證檔權限不是 0600;daemon 沒有啟動 執行 terminux-doctor;修正後重啟 daemon
AI 說「沒有可查的證據」 沒有綁定 run,問題裡也沒有 run id Profile 模式用 @@/bind-run <收據>;或在問題中寫出 run id
回覆中出現 CLOUD_AGENT_CAPABILITY_DENIED 雲端 backend 的 AI 只能查詢證據 這是預期行為;要執行解說或比較,用 10.4 的明確指令
Profile 模式下所有 AI 請求都被拒絕 Profile 或 policy 檔不合法、權限不是 0600、endpoint/model 與實際設定不一致、外送紀錄寫不進去 修正檔案後重啟 daemon;設定無效時不會退回無限制模式
daemon 起不來(exit code 4,TERM_DAEMON_OWNER_EXISTS) 已有另一個 daemon(可能在另一台主機) 看 owner.json 的 host、pid;到那台主機使用或停止它。確認它不存在後才用 terminux-launch --reset
daemon 起不來(exit code 2,TERM_AGENT_SOCKET_UNAVAILABLE) ~/.terminux 權限過寬(group/other 可寫)、是 symlink、owner 不對,或 socket 路徑被其他檔案占用 依訊息中的路徑修正;Terminux 不會自動刪除既有檔案
GUI 連得上,但 @@ 與 DQE Viewer 都沒反應 daemon 的 lineage socket 沒有起來 以 TERMINUX_LOG_LEVEL=INFO 重啟,看 daemon.log 是否有 TERM_SOCKET_BIND_FAILED
@@open DQE Viewer 打不開 找不到 dqe_viewer 執行檔 把 Viewer 安裝到與 GUI 相同的目錄,或設定 TERMINUX_DQE_VIEWER_BIN
tcsh 裡 hook 沒作用 rc 檔沒加 source 那一行;或 TERMINUX_AUTO_SETUP_WRAPPERS=0 依 4.6 設定;確認 ~/.terminux/tcsh_hooks.csh 存在
terminux-launch 警告 TERM_LAUNCH_WRAPPER_SETUP daemon 部署 hook 失敗或被停用 依訊息查看 daemon.log
terminux-orfs-run 在 check-klayout 停下(exit 1) klayout 不在 PATH 把 KLayout 加入 PATH,或由 --env-script 設定
terminux-orfs-run exit 2 以 root 執行、--work-home 不屬於你、--ledger-db 指向 daemon 的 ledger、找不到 env script 或 make 依 stderr 訊息修正
terminux-orfs-run exit 3 執行成功但收據沒寫入事件紀錄 確認事件紀錄可寫,或用 --receipt-store 指定可寫的位置
命令以 exit code 5 拒絕(TERM_DATABASE_REMOTE_OWNER) daemon 在另一台主機 到那台主機執行
daemon.log 是空的 預設只記錄 ERROR 這是正常的;需要時以 TERMINUX_LOG_LEVEL=INFO 重啟
log 出現 TERM_ECC_PLAYBOOK_UNAVAILABLE 沒有部署 STA playbook(選用) 不用 playbook 時可忽略;要用時依 4.5 部署
log 出現 TERM_EVENT_STORE_UNAVAILABLE 事件紀錄檔無法開啟或不可寫 修正 ~/.terminux/ecc 的權限後重啟;在此之前 package 與事件紀錄都不會運作
安裝包安裝失敗,提示缺少函式庫 缺 xcb 等系統函式庫 依 terminux-qt-check 列出的 SONAME 請管理者安裝(3.2)
安裝包環境中找不到 terminux-orfs-run 等命令 ~/.local/bin 只有兩個入口 用 ~/.local/opt/terminux/current/venv/bin/<命令>,或把該目錄加入 PATH

16. 常見問題

Q:不設定 LLM 也能用嗎? 可以。終端機、lineage 檢查、ORFS 執行、收據、品質判定與 DQE Viewer 都不需要 LLM;只有 AI 問答、解說、比較與摘要需要。

Q:AI 會改我的設計或自己跑工具嗎? 不會。雲端 backend 的 AI 只能查詢已記錄的執行證據。要執行解說或比較,必須由你以明確指令建立提案、核准,再執行一次。

Q:資料會離開我的機器嗎? 只有在你設定了 LLM backend 之後,才會依 13.2 的表把資料送到你選的 provider。使用本機 provider 時資料留在本機。

Q:可以用本機模型嗎? 可以。llama_cpp 只有基本問答、沒有 Agent;本機的 OpenAI 相容服務可以接上,但能否完成 Agent 流程目前尚未驗證。

Q:需要 Docker 或 root 嗎? 不需要。ORFS 以你的帳號在主機上執行;安裝包裝在你的家目錄。

Q:為什麼 lineage 警告了,命令還是執行了? lineage 檢查在命令送出之後才進行,結果只是提示,不會攔下命令。

Q:重啟 daemon 會遺失什麼? 事件紀錄、品質資料庫、收據與產物清單都保留。只有存在記憶體中的 run 綁定、待核准的提案、計畫與執行結果會清空。

Q:tcsh 可以用嗎? 可以,在 rc 檔加一行即可(4.6);tcsh hook 在 0.1.1 未驗證。

Q:Terminux 是開源軟體嗎? 不是。Terminux 採 PolyForm Shield License 1.0.0,是 source-available 軟體。任何組織都可以免費使用,包括內部業務與客戶專案;但不得用來提供 與 Terminux 競爭的產品或服務。

Q:怎麼回報問題? 目前不接受外部 pull request,請以 GitHub Issues 回報。


17. 附錄

A. 命令一覽

命令 用途
terminux-launch(安裝包:terminux) 啟動或沿用 daemon,再開 GUI
terminux(從原始碼安裝) GUI 本身;--version、--self-check
terminux-daemon daemon(通常由 terminux-launch 啟動)
terminux-relay 非 owner 主機的本機轉送
terminux-orfs-run 執行一次 ORFS
terminux-orfs-report 依收據與產物清單印出 report
terminux-doctor 本機診斷
terminux-qt-check --qt-dir DIR [--prefix DIR] 檢查 Qt 與 GUI 自我檢查
dqe_viewer DQE Viewer(由 GUI 開啟);--version、--smoke-exit
terminux-work Engineering Work
terminux-tool 登記使用者的 EDA 執行檔
terminux-package-install、-uninstall、-status 管理使用者 package
terminux-package-new、-validate、-test、-doctor 開發 package
terminux-cold-backup 冷備份、驗證、還原
terminux-rollback-check 升級前的資料相容檢查
dqe-scheduled-clean DQE 排程清除
terminux-corpus-replay 驗證用的模擬資料重播工具,不是真的 ORFS

表中的 Python 命令除了 terminux-qt-check 與 terminux-orfs-report,都支援 --version;terminux 與 dqe_viewer 也支援 --version。

B. 環境變數

變數 用途
TERMINUX_LLM_BACKEND openai_compatible、gemini、llama_cpp;不設定=關閉 AI
TERMINUX_OPENAI_MODEL、TERMINUX_OPENAI_TIMEOUT_SEC OpenAI 相容服務的 model(預設 deepseek-chat)與逾時(預設 120 秒)
TERMINUX_GEMINI_MODEL Gemini 的 model(預設 gemini-3.6-flash)
TERMINUX_LLM_MODEL_PATH、TERMINUX_LLM_DISABLE_THINKING llama_cpp 的模型檔;關閉 thinking mode
TERMINUX_EMBEDDING_BACKEND、TERMINUX_EMBEDDING_MODEL_PATH embedding 的目的地(noop、local、gemini)與本機模型
TERMINUX_CREDENTIALS_FILE、TERMINUX_DISABLE_CREDENTIAL_FILE 憑證檔位置;設 1 完全不讀憑證檔
TERMINUX_PROJECT_ID 宣告 project(選用)
TERMINUX_PREFERRED_LANGUAGE 尚未選擇語言時的預設:zh-Hant、en、zh-Hans
TERMINUX_PLAYBOOK_PATH STA playbook 的位置
TERMINUX_LOG_LEVEL daemon 的 log 等級(預設 ERROR)
TERMINUX_GUI_BIN、TERMINUX_DQE_VIEWER_BIN 指定 GUI 或 Viewer 執行檔
TERMINUX_DQE_DB_PATH、TERMINUX_EVENT_STORE_PATH 品質資料庫與事件紀錄的位置
TERMINUX_AUTO_SETUP_WRAPPERS 設 0 時 daemon 不安裝 hook 與 wrapper
TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME、TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME lineage 的 LLM 輔助(預設關閉,見第 7 節)
TERMINUX_AGENT_TASK_PROFILE_FILE、TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE、TERMINUX_EGRESS_AUDIT_DIGEST、TERMINUX_EGRESS_AUDIT_KEYRING_FILE Profile 模式(4.7)
TERMINUX_EAP3_BINDINGS_FILE Engineering Work 的 provider bindings(11.2)
TERMINUX_HOME_DIR、TERMINUX_NODENAME、TERMINUX_ADVERTISE_HOST、TERMINUX_UNIX_ONLY_IPC 進階:私有基底目錄、主機識別、對外公告的主機名、只用本機 socket

C. 檔案與目錄

位置 內容
~/.terminux/credentials.json 憑證(0600)
~/.terminux/preferences.json 介面語言
~/.terminux/ecc/event_store.db 事件紀錄(收據、品質紀錄、task 等)
~/.terminux/ecc/sta_signoff_playbook.yaml STA playbook(選用)
~/.terminux/dqe/dqe.sqlite 品質資料庫
~/.terminux/dqe/retention_policy.json Temporary 保留期政策
~/.terminux/lineage/ledger.jsonl lineage 紀錄
~/.terminux/lineage/artifact_manifests/ 產物清單
~/.terminux/lineage.<nodename>.jsonl wrapper 的執行紀錄
~/.terminux/orchestration/ledger.sqlite daemon 管理的執行狀態
~/.terminux/memory/search_index.db 搜尋索引
~/.terminux/rag_knowledge/、~/.terminux/rag_index/ 你自己的 RAG 知識與索引
~/.terminux/tools/user_tool_catalog.yaml 你登記的 EDA 工具
~/.terminux/packages/ 你安裝的 package
~/.terminux/bin/、~/.terminux/hooks/、~/.terminux/bash_hooks.sh、~/.terminux/tcsh_hooks.csh wrapper 與 hook(daemon 自動安裝)
~/.terminux/run/owner.lock/owner.json daemon 所在主機與狀態
~/.terminux/run/<nodename>/ socket、daemon.log、外送紀錄(Profile 模式)
~/.local/opt/terminux/ 可攜式安裝包的安裝位置

D. 授權與第三方軟體

Terminux 採 PolyForm Shield License 1.0.0(source-available,不是 OSI 定義的開源軟體),條款以 LICENSE.md 為準;第三方軟體的授權見 THIRD_PARTY_NOTICES.md。ORFS、OpenROAD、Yosys、KLayout 不隨 Terminux 提供,由站點另行安裝。isvn 為獨立發布的產品。