使用指南
使用指南
適用版本:Terminux 0.1.1。不同版本的命令與功能可能不同。
目錄
- 開始之前
- 快速開始
- 安裝
- 設定
- 啟動、停止與狀態
- 使用 Terminux 終端機
- Lineage 檢查
- 執行 ORFS
- 品質判定(DQE)與 DQE Viewer
- 使用 AI(@@)
- 有界任務與 Engineering Work(未驗證)
- 其他工具
- 資料、隱私與安全
- 維護
- 疑難排解
- 常見問題
- 附錄
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 為例:
-
確認主機是 Linux x86_64,並已安裝 Qt 6.7 以上(Desktop gcc 64-bit 預設元件)。
-
下載
terminux-<版本>-linux-x86_64.tar.gz與SHA256SUMS,核對後安裝:請依安裝教學核對獨立校驗值、停止條件及後續安裝順序。
-
建立憑證檔(權限必須是 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 -
選擇 backend 並啟動:
export TERMINUX_LLM_BACKEND=openai_compatible terminux -
在 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。 -
輸入
@@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_compatiblebackend 不需要額外套件。 - 不修改任何 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 執行提問
-
以
terminux-orfs-run執行 flow。--receipt-out寫出的收據裡有這次執行的run_id與attempt;stdout 最後的品質摘要也會列出 run id。 -
綁定這次執行(需要 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解除。 -
直接提問,例如:
@@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 查詢同一份證據。
-
自己核對:
@@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 為獨立發布的產品。