跳至主要内容

參考手冊

參考手冊

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

目錄

  1. 手冊說明
  2. 系統概觀
  3. 命令參考
  4. Terminux 終端機(GUI)參考
  5. DQE Viewer 參考
  6. @@ 參考
  7. 設定參考
  8. 檔案與資料參考
  9. 品質判定(DQE)參考
  10. 訊息與代碼參考
  11. 上限、逾時與預設值
  12. 名詞表

1. 手冊說明

1.1 符號慣例

寫法 意思
<值> 必填,換成實際的值
[選項] 選填
a|b 擇一
… 可重複,或省略的其餘內容
~ 你的家目錄
<nodename> 主機名稱(可用 TERMINUX_NODENAME 覆寫)

1.2 命令位置

  • 從原始碼安裝:命令在 Python 環境的 bin/(例如 $VIRTUAL_ENV/bin/)。
  • 可攜式安裝包:~/.local/bin 只有 terminux(=terminux-launch)與 terminux-qt-check;其他命令在 ~/.local/opt/terminux/current/venv/bin/。
  • 原始碼中的腳本:terminux-chat、terminux-dream、terminux-lineage-graph、terminux-build-rag-index、 terminux-llm-env.sh/.csh 在原始碼的 scripts/ 目錄。

2. 系統概觀

元件 說明
daemon 每個 Linux 帳號一個的背景服務。所有資料、AI、執行管理都在這裡。以 owner lock(~/.terminux/run/owner.lock)保證唯一
Core socket ~/.terminux/run/<nodename>/terminux.sock:GUI 與 CLI 建立 session 的連線
lineage socket ~/.terminux/run/<nodename>/lineage.sock:lineage 檢查、@@、DQE Viewer、task 等請求
GUI(terminux) 終端機視窗;不會自行啟動 daemon,由 terminux-launch 負責
DQE Viewer(dqe_viewer) 由 GUI 在本機啟動,經 lineage socket 讀取資料
shell hook 與 wrapper daemon 啟動時安裝到 ~/.terminux,把命令的開始與結束通知 daemon
relay(terminux-relay) 共享 HOME 的多台主機中,非 owner 主機上的本機轉送(未驗證)

daemon 只接受與它相同 Linux 帳號的連線;連線身分由作業系統核對。


3. 命令參考

3.1 terminux-launch

語法:terminux-launch [--no-gui] [--reset] [--version]

啟動或沿用 daemon,再啟動 GUI。可攜式安裝包的 ~/.local/bin/terminux 就是這個命令。

選項 說明
(無) 確保 daemon 在跑,然後開 GUI
--no-gui 只確保 daemon(或 relay)在跑,不開 GUI
--reset 印出 owner.json,要求輸入 yes,然後只刪除 ~/.terminux/run/owner.lock。不會停止任何 daemon
--version 印出版本後結束

行為:

owner 狀態 動作
沒有 owner 背景啟動 daemon(輸出寫到 daemon.stdout.log),最多等 30 秒到就緒;逾時只警告,仍開 GUI
owner 正在啟動 最多等 30 秒
owner 在本機且行程存在 沿用
owner 在本機但行程不存在 重新啟動 daemon(殘留的鎖由 daemon 自行判定回收)
owner 在其他主機 確認 3 秒內可連上 owner 的 TCP 埠,再啟動本機 relay(未驗證)
owner 狀態不是 ready、讀不到、或為 unix-only 而在其他主機 失敗(TERM_DAEMON_OWNER_UNAVAILABLE)
你在 Profile 模式,但 owner 不是以 Profile 模式啟動 失敗(TERM_DAEMON_OWNER_UNCONTAINED),不沿用也不停止它

GUI 的尋找順序:TERMINUX_GUI_BIN → <Python 環境>/bin/terminux → <Python 環境>/../bin/terminux → PATH 中的 ELF 執行檔 (跳過啟動器本身)。找不到為 TERM_LAUNCH_GUI_NOT_FOUND。daemon 部署 hook 失敗或停用時印出 TERM_LAUNCH_WRAPPER_SETUP。

exit code:0 成功;1 失敗(訊息以 TERM_ 開頭,見第 10 章)。

3.2 terminux(GUI)

語法:terminux [--version] [--self-check](從原始碼安裝時;安裝包的 terminux 見 3.1)

選項 說明
(無) 開啟 Terminux 終端機視窗
--version 印出版本與授權後結束
--self-check 以 offscreen 模式啟動、檢查 Qt 與 plugin 後結束;不開視窗、不連 daemon

GUI 啟動後連線到 Core socket;連不上時每 3 秒重試。

3.3 terminux-daemon

語法:terminux-daemon [--version] [-h|--help];等同 python -m terminux_engine

通常由 terminux-launch 啟動。設定全部來自啟動時的環境變數(7.2)。

exit code:0 正常停止(收到 SIGINT/SIGTERM);2 socket 路徑無法解析(TERM_AGENT_SOCKET_UNAVAILABLE);3 啟動失敗 (TERM_SERVICE_START_FAILED);4 已有 owner 或偵測到舊版 daemon(TERM_DAEMON_OWNER_EXISTS、TERM_LEGACY_DAEMON_RUNNING)。

python -m terminux_engine.main 不會啟動 daemon,執行後立即結束。

3.4 python -m terminux_engine purge

語法:python -m terminux_engine purge --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--force]

清除事件紀錄(~/.terminux/ecc/event_store.db)中指定日期區間的事件。建議在 daemon 停止時執行。

選項 說明
--from、--to 起訖日期(含當日)
--force 真的刪除。先把區間內的事件寫成 JSONL 到 ~/.terminux/ecc/archive/ 並 fsync,成功後才刪除。只允許 TERMINUX_PURGE_ALLOW_USER 指定的帳號(預設目前帳號)
(不加 --force) 只預覽會影響的筆數,不改資料庫

exit code:0 成功;1 拒絕 --force;2 參數錯誤;5 daemon 在另一台主機(TERM_DATABASE_REMOTE_OWNER)。

3.5 terminux-relay(未驗證)

語法:terminux-relay(沒有選項;通常由 terminux-launch 啟動)

在非 owner 主機提供本機的 Core 與 lineage socket,逐連線讀取 owner.json,以 token 連到 owner 的 TCP 埠。單一實例以 ~/.terminux/run/<nodename>/relay.pid 保證;log 寫在同目錄的 relay.log。

3.6 terminux-doctor

語法:terminux-doctor [--agent-socket <路徑>] [--lineage-socket <路徑>] [--version]

本機診斷,不呼叫 provider、不執行 EDA、不讀憑證內容。輸出 JSON:

欄位 內容
package_version 套件版本
agent_socket、lineage_socket 兩個 socket 的路徑
daemon running、state、host、pid
llm_config 舊 Layer 2 設定檔是否存在、可讀、來源(套件範本或使用者)
bundled_knowledge 五個內建 knowledge 檔是否可讀
plugin_dir plugin 目錄是否存在(0.1.x 不附 plugin,不存在是正常的)
eap3_bindings Engineering Work 的 bindings 檔狀態(有設定時)
credentials 憑證檔來源與是否安全(本人擁有、0600、一般檔);不讀內容
background RAG 背景重建是否停用、embedding backend
status ready 或 attention

exit code:0 ready;1 attention。

3.7 terminux-qt-check

語法:terminux-qt-check --qt-dir <Qt 目錄> [--prefix <安裝 prefix>]

讀取外部 Qt 的內容,確認版本、函式庫、QML imports、xcb 與 offscreen plugin。加 --prefix 時,另以 offscreen 模式執行 terminux 與 dqe_viewer 的自我檢查(不開視窗、不連 daemon)。xcb 缺少系統函式庫時,列出 SONAME 與已知的 EL9/Ubuntu 24.04 套件名稱,但不會代為安裝。多主機環境中,Qt 目錄在每台主機必須是相同的絕對路徑。

exit code:0 通過;1 未通過。

3.8 terminux-orfs-run

語法:

terminux-orfs-run --orfs-repo-root <dir> --work-home <dir> --design <name> --platform <name>
                  --variant <name> --design-config <path> --ledger-db <file> --receipt-out <file>
                  [--env-script <file>] [--make-executable <file>] [--openroad-exe <file>] [--yosys-exe <file>]
                  [--timeout-seconds <秒>] [--receipt-store <file> | --no-receipt] [--version]

以你的帳號在主機上執行一次 ORFS flow(host-native),留下收據、產物清單與品質判定。以 root 執行會被拒絕。

選項 必填 預設 說明
--orfs-repo-root 是 — ORFS 安裝根目錄(含 flow/),可以是唯讀
--work-home 是 — 輸出目錄(ORFS WORK_HOME),必須由你擁有;上層存在時建立最後一層
--design 是 — 必須等於 ORFS 輸出目錄使用的名稱(DESIGN_NICKNAME,未設定時為 DESIGN_NAME)
--platform 是 — 例如 nangate45
--variant 是 — ORFS FLOW_VARIANT;不可為 base;會成為 step id orfs-<design>-<variant> 的一部分
--design-config 是 — config.mk 相對於 ORFS flow/ 的路徑,必須位於 flow/ 之下
--ledger-db 是 — 這次執行專用的 ledger 檔;不得指向 daemon 的 ~/.terminux/orchestration/ledger.sqlite(含別名)
--receipt-out 是 — 收據 JSON 的輸出路徑
--env-script 否 <orfs-repo-root>/env.sh 讓 EDA 工具可用的環境 script;除 HOME、LANG、PATH 外不繼承 shell 環境
--make-executable 否 PATH 上的 make 執行 flow 的 make
--openroad-exe、--yosys-exe 否 ORFS 自己的規則 明確指定 ORFS 的 OPENROAD_EXE、YOSYS_EXE
--timeout-seconds 否 900 執行時間上限(秒)
--receipt-store 否 TERMINUX_EVENT_STORE_PATH 或 ~/.terminux/ecc/event_store.db 收據改寫入指定的事件紀錄檔
--no-receipt 否 — 不寫入任何事件紀錄(--receipt-out 仍寫出);與 --receipt-store 互斥

輸出:stdout 結尾印出品質摘要與 run id;--work-home 下有 ORFS 的 results/、reports/、logs/、objects/;收據寫到 --receipt-out。工具身分(env script、make、design config 與指定工具的路徑與 SHA-256)記在收據內。

exit code:

code 意思
0 執行成功,收據已寫入(--no-receipt 時只看執行結果)
1 執行失敗(品質判定本身的結果不影響 exit code)
2 參數或環境錯誤:以 root 執行、--work-home 不屬於你、--ledger-db 指向 daemon 的 ledger、找不到 env script 或 make、使用已移除的 --docker-image
3 執行成功,但收據沒有寫入
5 daemon 在另一台主機
130/143 收到 Ctrl-C/SIGTERM(未驗證)

stderr 可能出現的代碼見 10.3。

3.9 terminux-orfs-report

語法:terminux-orfs-report --receipt <file> --run-id <run_id> --attempt <n> [--role <role>] [--stage <N> [--expect-line <L>] [--view]]

核對 report 的雜湊與收據、產物清單一致後才印出,確保看到的是那一次執行的 report。

選項 說明
--receipt、--run-id、--attempt 必填
--role orfs.finish_report(預設)或 orfs.route_drc_report
--stage N 改為定位 finish report 中 timing path 的第 N 級(從 1 開始)
--expect-line L 需搭配 --stage;要求該級位於第 L 行
--view 需搭配 --stage;以 less -N 在該行開啟已驗證的 report(需要終端機)

exit code:0 成功;2 錯誤(訊息在 stderr)。

3.10 dqe_viewer

通常由 GUI 在 @@open DQE Viewer 時以 --db、--temporary-db-path、--ipc-endpoint 啟動。手動執行時:

語法:dqe_viewer [選項]

選項 說明
--version (作為最後一個參數且不帶值時)印出版本後結束
--smoke-exit 建立並驗證 QML 介面後立即結束(安裝檢查用)
--ipc-endpoint <socket> daemon 的 lineage socket;必須搭配 Temporary 或 Archived 資料來源
--temporary-db-path <file> Temporary 資料來源(品質資料庫)
--db <file> --temporary-db-path 的相容別名
--archived-version-dir <dir> Archived 資料來源
--temporary-retention-days <天> Temporary 保留期的顯示情境(1~3650)
--workspace archived|temporary|compare 起始工作區(--select-tab 為相容別名)
--job-key <job_key> 在 Temporary 工作區聚焦這個 job(需要 Temporary 資料來源)
--window-size <W>x<H> 視窗大小,例如 1440x900
--screenshot <png> 介面就緒後截圖並結束(需要資料來源或內建範例情境)
--ui-scenario <名稱> 內建範例資料的情境(截圖與視覺比對用)

沒有 --ipc-endpoint 與資料來源時,Viewer 顯示內建的範例資料(畫面標示 MOCK)。

3.11 dqe-scheduled-clean

語法:dqe-scheduled-clean [--db <file>] [--policy <file>] [--dry-run] [--no-vacuum] [--log <file>]

依 Temporary 保留期政策清除過期的 job。

選項 預設 說明
--db ~/.terminux/dqe/dqe.sqlite 品質資料庫
--policy ~/.terminux/dqe/retention_policy.json 保留期政策
--dry-run — 只計算、不刪除
--no-vacuum — 刪除後不執行 SQLite VACUUM
--log ~/.terminux/dqe/scheduled_clean.log log 檔

輸出 JSON。exit code:0 成功;1 失敗;2 參數錯誤;3 完成,但保留期政策檔無效或有警告,改用了預設政策;5 daemon 在另一台主機。

3.12 terminux-cold-backup

語法:

terminux-cold-backup [--agent-socket <path>] [--lineage-socket <path>] create <destination> --source <LABEL>=<abs path> …
terminux-cold-backup verify <backup>
terminux-cold-backup restore <backup> --target <LABEL>=<abs path> …
子命令 規則
create daemon 必須已停止(沒有 owner lock);目的地必須是尚不存在的絕對路徑;來源是 LABEL=/絕對路徑(LABEL 只能含英數、_、-),彼此不得重疊、不得含 symlink 或特殊檔、不得包含目的地
verify 重算每個檔的 SHA-256 並與備份紀錄比對
restore daemon 必須已停止;target 的 LABEL 集合必須與備份相同、路徑必須等於備份時的原始路徑、且目前不存在;先寫到暫存目錄並驗證雜湊,再搬到位

輸出 JSON。exit code:0 成功;2 前置條件不符({"status": "error", "reason": …})。只確認過 --help。

3.13 terminux-rollback-check

語法:terminux-rollback-check --event-store <file> --agent-socket <path> --lineage-socket <path>

以唯讀交易檢查事件紀錄中的資料格式是否在這一版支援的範圍:Engineering Work engineering_work.v1、FlowTask 與 AnalysisTask schema 1、2。不切換程式、不還原資料。輸出 JSON。

exit code:0 相容(DATA_COMPATIBLE_ONLY);2 不相容或讀不到(REJECTED);5 daemon 在另一台主機。只確認過 --help。

3.14 terminux-work(未驗證)

語法:terminux-work [--agent-socket <path>] [--lineage-socket <path>] [--project <id>] [--profile-path <file>] <子命令> …

子命令 參數 說明
create <profile_id> <package_id> <objective>;[--block] [--method] [--source-root] [--criterion …] [--constraint …] [--expert …] [--review proposal_review|result_review …] 建立工作
create-from-saved-proposal <profile_id> <source_work_id> <source_proposal_id> <expected_proposal_digest> <objective>;[--source-root] [--criterion …] [--constraint …] [--request-id] 以先前保存的提案建立工作
authorize <work_id>;[--mode PLAN_ONLY|PER_PROPOSAL|BOUNDED_EXPLORATION](預設 BOUNDED_EXPLORATION)[--attempts 2] [--provider-dispatches 12] [--tool-launches 5] [--candidate-materializations 2] [--formal-proof-launches N] [--baseline-tool-launches N] [--allowed-method …] [--allowed-change-json …] [--writable-root …] [--stop-condition …] 授權預覽(設定範圍與上限)
approve、continue、get、pause、resume、cancel、takeover <work_id> 核准、推進、查詢、暫停、恢復、取消、重新接管
config <work_id> 查看這份工作實際生效的設定
export <work_id> 輸出預設遮蔽敏感內容的支援摘要(JSON),方便回報問題
list — 列出工作
answer <work_id> <message>;[--objective] [--method] 回答問題或補充資料

需要 TERMINUX_EAP3_BINDINGS_FILE;沒有設定或在 Profile 模式時這個功能不啟用。--profile-path 會先在這個 session 選用 Profile。 exit code:0 成功;2 錯誤。

3.15 terminux-tool(未驗證)

語法:terminux-tool [--format text|json] register <tool_id> [--executable <name> …]、… unregister <tool_id>、… list

自行登記 EDA 執行檔(不需要管理者權限),寫入 ~/.terminux/tools/user_tool_catalog.yaml。--executable 可重複,預設為 tool id。 list 列出內建與使用者工具。exit code:0 成功;其他值為失敗。

3.16 terminux-package-install/-uninstall/-status(未驗證)

語法 說明
terminux-package-install <source_dir> [--replace] [--format text|json] 把含 package.yaml 的目錄複製安裝到 ~/.terminux/packages;--replace 取代同 id 的已安裝 package
terminux-package-uninstall <package_id> [--format text|json] 移除使用者 package
terminux-package-status [<package_id>] [--activate] [--format text|json] 顯示已安裝的 package 與執行中 daemon 已載入的內容;--activate 請 daemon 重新載入(不需重啟)

TERMINUX_DISABLE_USER_PACKAGES 可整體停用使用者 package。exit code:0 成功;其他值為失敗。

3.17 package 開發工具(只確認 --help)

語法 說明 exit code
terminux-package-new <package_id> --root <dir> [--tool <name> …] [--package-version <v>] [--dry-run] [--format text|json] 產生 after-phase package 骨架 0 成功;2 錯誤
terminux-package-validate [--root <dir>] [--format text|json] 離線驗證 package(不帶 --root 時驗證內建 package);handler 必須是模組頂層的函式 0 有效;1 無效;2 錯誤
terminux-package-test --root <dir> --package <id> [--case <name> …] [--timeout 10] [--format text|json] 在隔離的子行程執行 package 的測試案例 0 全部通過;1 有失敗;2 錯誤
terminux-package-doctor --root <dir> [--run-cases] [--require-cases] [--junitxml <file>] [--timeout 10] [--format text|json] 綜合診斷,可輸出 JUnit XML 0 通過;1 有錯誤或失敗;2 參數錯誤

3.18 terminux-corpus-replay

驗證用的模擬資料重播工具,不是真的 ORFS,不要用於實際工作。只確認過 --help。

3.19 原始碼中的腳本(未驗證)

語法 說明
terminux-chat <問題…> 在 Terminux 終端機外送出一次 @@;每次呼叫都是新的 session;逾時 120 秒。回答是開啟 DQE Viewer 時,會在本機啟動 Viewer
terminux-lineage-graph [jobs] [--ledger <file>] [--session <S1,S2>] [--output <file>] [--no-open] 產生 artifact lineage graph 的 HTML 並以瀏覽器開啟;--session 篩選並依 session 著色
terminux-lineage-graph trace --session <SESS> [--event-store <file>] [--output <file>] [--no-open] 產生某個 session 的執行追蹤圖
terminux-dream --user-id <帳號> --date <yesterday|today|YYYY-MM-DD> 產生指定日期的工作摘要
terminux-dream --user-id <帳號> --backfill [--days <N>] 補做最近 N 天(預設 1)的摘要
terminux-build-rag-index [--source-dir <dir>] [--index-dir <dir>] [--chunk-size 512] [--chunk-overlap 64] 從 ~/.terminux/rag_knowledge(預設)建立 RAG 索引到 ~/.terminux/rag_index(預設);需要 rag extra 與 embedding 設定
source terminux-llm-env.sh/source terminux-llm-env.csh LLM 設定範本;取消註解其中一種 backend 後再 source,不要在其中寫入憑證

3.20 可攜式安裝包的 install.sh 與 uninstall.sh

install.sh:./install.sh [--qt-dir <dir>] [--prefix <dir>] [--no-bin-link] [--yes] [--reinstall] [--force]

選項 預設 說明
--qt-dir 既有的 current/qt Qt SDK 目錄
--prefix ~/.local/opt/terminux 安裝位置;每個版本一個子目錄,current 指向使用中的版本
--no-bin-link — 不在 ~/.local/bin 建立 terminux 與 terminux-qt-check
--yes — 不逐項詢問
--reinstall — 重裝相同版本
--force — 只略過「不支援的 OS」阻擋

安裝前會核對 SHA256SUMS;有執行中的 daemon 時拒絕安裝。Qt 檢查通過才切換 current;失敗時移除新建的 .partial。

uninstall.sh:~/.local/opt/terminux/current/uninstall.sh (--version <v> | --all) [--purge-data] [--yes]

預設保留 ~/.terminux;--purge-data 才刪除資料,且即使加 --yes 也必須輸入完整的資料路徑確認。不修改 rc 檔; ~/.local/bin 中不是本安裝建立的檔案不會被刪除。


4. Terminux 終端機(GUI)參考

4.1 主視窗

區域 內容
標題列 shell 的標題;連不上 daemon 時顯示「⚠ Terminux Core 未連線(daemon 未啟動)」與原因
狀態列 啟動時依序顯示「Connecting to Terminux Core…」「Initialising session…」,就緒後顯示「Terminux 服務已就緒」(依介面語言)
選單列 View ▸ Work Panel:開關 Engineering Work 面板(預設隱藏;未驗證)。Help ▸ About Terminux:版本與授權;Help ▸ About Qt
終端機 你的 shell(PTY);bash 自動載入 hook
通知列 視窗上方,見 4.4

4.2 終端機與 shell

  • 內建 bash 以 --rcfile ~/.terminux/hooks/bash_rcfile 啟動:先載入你的 ~/.bashrc,再載入 ~/.terminux/bash_hooks.sh; 已在 .bashrc 載入過的 hook 不會重複註冊。
  • GUI 在終端機環境注入 TERMINUX_ACTIVE=1,讓 tcsh 的 rc 只在 Terminux 內載入 hook。
  • csh/tcsh 啟動後 10 秒內沒有收到 hook 標記(OSC 133)時,顯示一次設定提示,不會修改 rc 檔。
  • 以 @@ 開頭的輸入不會交給 shell(第 6 章)。

4.3 右鍵選單

項目 快捷鍵 作用
Copy Ctrl+Shift+C 複製選取的文字
Paste Ctrl+Shift+V 貼上
Select All — 全選
Clear Terminal — 清除畫面
Notification Bar ▸ Show — 展開通知列
Notification Bar ▸ Remove Oldest 10 Messages — 刪除最舊的 10 則通知
Notification Bar ▸ Remove All Messages — 刪除全部通知
Language ▸ 繁體中文/English/简体中文 — 介面與 AI 回答的語言,存到 ~/.terminux/preferences.json
Open URL — 選取的文字是網址時出現,以瀏覽器開啟
Font Size + Ctrl+= 放大字型
Font Size - Ctrl+- 縮小字型
Reset Font Size Ctrl+0 回到預設字型大小
Ask AI about this — 以選取的文字提問;沒有選取時不可用

4.4 通知列

項目 說明
通知類型 Warn(警告,例如 lineage 疑慮)、AI(AI 回答與背景分析結果)、Gate(quality gate 結果)、Hint(提示)
自動收合 滑鼠離開約 5 秒後收合成標題列;點標題列可再展開
調整高度 可拖曳調整通知列的高度
背景通知 GUI 約每 1.2 秒向 daemon 取一次新通知;daemon 端最多緩衝 500 則

4.5 Work 面板(未驗證)

標題為「工程工作」,從 View ▸ Work Panel 開啟。

欄位 範圍/預設 說明
Profile 檔 — Profile 檔的路徑;按「選 Profile」在這個 session 選用
Profile ID、Package — 建立工作用的 Profile 與 package
來源目錄 — 選用的來源目錄(受 Profile 限制)
工程目標 — 工作的目標
Work ID — 要操作的工作
授權模式 PLAN_ONLY、PER_PROPOSAL、BOUNDED_EXPLORATION 授權預覽的模式
嘗試上限 0~100,預設 1
Provider 上限 0~1000,預設 5
Tool launch 上限 0~100,預設 2
候選寫入上限 0~100,預設 1
補充資料 — 回答工作提出的問題

按鈕:選 Profile、建立、授權預覽、核准(會要求確認)、查詢、重新接管、暫停、恢復、取消(會要求確認)、 送出補充。下方顯示工作狀態摘要與 daemon 的原始回覆;「查詢」不會推進工作。


5. DQE Viewer 參考

5.1 共同元素

元素 說明
工作區分頁 暫存(Temporary)、已歸檔(Archived)、比較(Compare)
語言選單 標題列可切換 English/繁體中文/简体中文;起始語言跟隨終端機的設定
資料來源 狀態列顯示資料來源(正式資料為 Terminux daemon;範例資料標示 MOCK)
重新整理 Refresh 重新讀取
狀態值 Pass(通過)、Warn(警告)、Fail(失敗)、Unknown(未知)

5.2 暫存(Temporary)工作區

區塊 內容與操作
暫存 Job 清單 以 job 為單位列出每次執行的品質紀錄;「搜尋 job_key / block / flow」
DQE 項目 所選 job 的檢查項目:DQE_ID、標題、數值、單位、狀態、日期/時間、說明、參考、來源路徑、附件數、可執行檔數;可依狀態與 Block 篩選;標頭顯示總計與各狀態數量
選取項目檢視 所選項目的完整資訊
證據/附件預覽 附件的預覽
簽入(CHECK-IN)(未驗證) 簽入試跑(Check-in dry-run)、簽入整個 job(Check in whole job)、確認簽入(Confirm check-in);欄位為既有目標版本(相對路徑)與 Workspace 根目錄。經外部 isvn 工具執行
暫存保留政策 適用所有暫存 job 的全域政策:編輯政策(Edit policy)、儲存政策(Save policy);保留 N 天
暫存清除 預覽清除選取 job(Preview selected job purge)、預覽清除已過期 job(Preview expired jobs purge);預覽後確認才執行

5.3 已歸檔(Archived)工作區(未驗證)

列出已 check-in 的版本;可依 phase/block/version 篩選(「篩選 phase / block / version」);選取版本後檢視其 DQE 項目。

5.4 比較(Compare)工作區

區塊 內容
比較來源 選擇要比較的 job 或版本(勾選比較在 0.1.1 未驗證)
正規化趨勢 以第一個來源為 baseline(100%)畫出各指標的趨勢;可選取資料點
原始數值比較 各來源的原始數值
相對基準差 與 baseline 的差
Block 篩選 以 block 篩選 series
匯出 匯出 HTML(Export HTML):把比較結果存成 HTML

6. @@ 參考

6.1 輸入規則

  • 在 Terminux 終端機提示字元輸入 @@,後接問題或指令,按 Enter;這一行不交給 shell。
  • @@ 後的文字不展開 shell 變數;路徑請寫絕對路徑。
  • 選取文字後右鍵 Ask AI about this,以選取的文字提問;這種輸入永遠視為資料,不會被當成 / 指令。
  • 回答顯示在通知列。需要設定 LLM backend;Agent 只在 openai_compatible 與 gemini 可用。

6.2 不經 AI 的關鍵字

條件 作用
同時含「dqe viewer」(或 dqe_viewer、dqeviewer,不分大小寫)與任一動詞:開啟、打開、打开、啟動、启动、顯示、显示、open、launch、start、show 開啟 DQE Viewer(Temporary 工作區)
含 lineage graph、lineage dag、blood line、show lineage、血緣圖、祖譜圖 產生 ~/.terminux/lineage_graph.html 並開啟

6.3 本機指令

以 / 開頭的已知指令由 Terminux 在本機處理,不送 LLM。可用的指令依模式而不同:

模式 可用的本機指令
一般模式 下列除了 run 綁定以外的全部指令。/bind-run、/unbind-run 在一般模式不是本機指令,會被當成一般問題
Profile 模式 只有 /bind-run、/unbind-run。其他控制指令一律回 LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE,不執行也不外送

因此「綁定 run 後提問」與「以明確指令執行解說或比較」無法在同一個 daemon 設定下並用。

run 綁定(需要 Profile 模式,且 Profile 有 run_binding)

指令 作用
/bind-run <收據的絕對路徑> 把一次 run 綁定到這個 session。收據必須是事件紀錄中本人的正式紀錄、內容雜湊一致、符合 Profile 的 run_binding 規則
/unbind-run 解除這個 session 的所有綁定

計畫、提案與結果

指令 作用
/plan-only <目標> 產生一份計畫;不執行、不建立提案
/plan-propose <plan_id> <step_id> 針對計畫中的一個步驟建立提案;不執行
/plans、/plan <plan_id> 列出、查看計畫
/use-plan <plan_id> 把這份計畫設為後續提問的延續情境
/cancel-plan <plan_id> <plan_digest> 取消計畫
/proposals 列出提案
/approve <proposal_id> <proposal_digest> 核准(待核准的提案 10 分鐘後過期)
/reject <proposal_id> <proposal_digest> 拒絕
/execute <proposal_id> <proposal_digest> 執行一次;參數必須與提案相同;不可重複
/results 列出執行結果
/use-result <result_id> <result_digest> 後續提問帶入這份結果
/clear-result 不再帶入結果
/approve-plan、/execute-plan、/approve-all 一律拒絕:沒有整份計畫一次核准或執行的機制

task(未驗證)

指令 作用
/profile <Profile 的絕對路徑> 在這個 session 選用 Profile
/profiles 列出已選用的 Profile
/task-create <profile_id> <問題…> 建立 flow task 草案
/task-start <task_id> <task_digest> 授權並開始
/task <task_id> 查詢 task
/task-cancel <task_id> <task_digest> 要求停止
/tasks 列出你在這個 daemon 的所有 task

Engineering Work(未驗證)

指令 作用
/work-create <profile_id> <package_id> <目標> 建立工作
/work-authorize <work_id> <plan|proposal|bounded> 授權預覽
/work-approve <work_id>、/work-continue <work_id> 核准、推進
/work <work_id>、/works 查詢、列出
/work-answer <work_id> <回答或補充> 回答
/work-pause、/work-resume、/work-cancel、/work-takeover <work_id> 暫停、恢復、取消、重新接管

6.4 AI 可用的工具

情境 可用工具
雲端 backend(openai_compatible、gemini) 只有兩個執行證據查詢工具:查一次 run 的證據、比較 2~3 次 run 的證據。其他工具不提供給模型,被呼叫時回 CLOUD_AGENT_CAPABILITY_DENIED
Profile 模式 Profile 的 tools(目前只能是 query_orchestration_evidence)

AI 不能讀取檔案、不能執行 shell 命令、不能自行建立待核准的動作。有副作用的動作只能經 6.3 的明確指令(只在一般模式可用)。


7. 設定參考

7.1 載入時機與優先序

daemon 只在啟動時讀取設定;修改後要重啟。

對象 優先序(高 → 低)
LLM router ~/.terminux/llm_router.yaml(存在即使用)→ 環境變數
憑證 憑證檔(TERMINUX_CREDENTIALS_FILE 或 ~/.terminux/credentials.json)→ 同名環境變數
舊 Layer 2 設定 TERMINUX_LLM_CONFIG_PATH → ~/.terminux/config/llm_config.yaml → 套件範本
STA playbook TERMINUX_PLAYBOOK_PATH → ~/.terminux/ecc/sta_signoff_playbook.yaml
品質資料庫 TERMINUX_DQE_DB_PATH → ~/.terminux/dqe/dqe.sqlite
介面語言 ~/.terminux/preferences.json → TERMINUX_PREFERRED_LANGUAGE → zh-Hant

7.2 環境變數

「truthy」=1、true、yes(不分大小寫)。

LLM 與 AI

變數 預設 說明
TERMINUX_LLM_BACKEND 不設(AI 關閉) openai_compatible、gemini、llama_cpp
TERMINUX_OPENAI_MODEL deepseek-chat OpenAI 相容服務的 model
TERMINUX_OPENAI_TIMEOUT_SEC 120 每次請求的逾時(秒)
TERMINUX_GEMINI_MODEL gemini-3.6-flash Gemini 的 model
TERMINUX_LLM_MODEL_PATH — llama_cpp 的 GGUF 檔
TERMINUX_LLM_DISABLE_THINKING 不設 1:關閉 thinking mode(例如 Qwen3)
TERMINUX_EMBEDDING_BACKEND 依 LLM backend noop/none、local、gemini
TERMINUX_EMBEDDING_MODEL_PATH — local embedding 的模型
GEMINI_API_KEY、GEMINI_EMBEDDING_MODEL — 只在 TERMINUX_EMBEDDING_BACKEND=gemini 時另外接受;model 預設 gemini-embedding-001
TERMINUX_CREDENTIALS_FILE ~/.terminux/credentials.json 憑證檔位置
TERMINUX_DISABLE_CREDENTIAL_FILE 不設 1:完全不讀憑證檔
TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME 關閉 1:lineage 檢查有疑慮時請 LLM 說明
TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME 關閉 1:固定格式讀不出 runfile 時請 LLM 解析(送出完整 runfile)
TERMINUX_DISABLE_RAG_BACKGROUND_REBUILD 不設 truthy:不在背景重建 RAG 索引
TERMINUX_PREFERRED_LANGUAGE — 尚未選擇語言時的預設:zh-Hant、en、zh-Hans

Profile 模式

變數 說明
TERMINUX_AGENT_TASK_PROFILE_FILE Profile 檔(7.5)
TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE 外送 policy 檔(7.6)
TERMINUX_EGRESS_AUDIT_DIGEST 外送紀錄的雜湊模式(7.7)
TERMINUX_EGRESS_AUDIT_KEYRING_FILE keyed_persisted 模式的 keyring 檔
TERMINUX_CHAT_QUERY_REQUIRE_ORIGIN 預設關閉;開啟時,沒有標示來源的舊 client 輸入一律視為資料、不解析 / 指令(Profile 模式本來就如此)

路徑、身分與連線

變數 預設 說明
TERMINUX_HOME_DIR 帳號資料中的家目錄 socket、owner lock、log 的私有基底目錄;必須是絕對路徑、已存在、本人擁有、group/other 無權限
TERMINUX_NODENAME 主機名稱 run/<nodename>/ 的目錄名;只能含 ASCII 英數與 ._-
TERMINUX_CORE_SOCK、TERMINUX_SOCK — Core/lineage socket 的隔離部署覆寫(絕對路徑;父目錄必須本人擁有且 group/other 無權限)
TERMINUX_ADVERTISE_HOST 主機的 FQDN owner.json 對外公告的主機名
TERMINUX_UNIX_ONLY_IPC 0 1:不開 TCP 轉送埠;只接受 0、1
TERMINUX_GUI_BIN — GUI 執行檔
TERMINUX_DQE_VIEWER_BIN GUI 同目錄的 dqe_viewer DQE Viewer 執行檔
TERMINUX_PROJECT_ID(舊名 TERMINUX_PROJECT) 不設 宣告 project

資料位置

變數 預設
TERMINUX_EVENT_STORE_PATH ~/.terminux/ecc/event_store.db
TERMINUX_ECC_STORE_PATH ~/.terminux/ecc/ecc_store.jsonl
TERMINUX_PLAYBOOK_PATH ~/.terminux/ecc/sta_signoff_playbook.yaml
TERMINUX_DQE_DB_PATH ~/.terminux/dqe/dqe.sqlite
TERMINUX_DQE_DEFAULT_DB_POLICY 不設=允許使用預設品質資料庫;deny:沒有明確指定時拒絕寫入預設位置
TERMINUX_ORCHESTRATION_LEDGER_PATH ~/.terminux/orchestration/ledger.sqlite
TERMINUX_LLM_CONFIG_PATH、TERMINUX_PLUGIN_DIR 舊 Layer 2 設定檔;plugin 目錄(~/.terminux/plugins)。皆須絕對路徑
TERMINUX_AGENT_AUDIT_LOG_PATH ~/.terminux/agent_tool_audit.jsonl
TERMINUX_LOG_PATH、TERMINUX_PROJECT_ROOT pre-exec 觀測 log:TERMINUX_LOG_PATH → <TERMINUX_PROJECT_ROOT>/artifacts/lineage_preexec.log → ~/.terminux/lineage_preexec.log

功能開關與上限

變數 預設 說明
TERMINUX_LOG_LEVEL ERROR daemon log 等級:DEBUG、INFO、WARNING、ERROR、CRITICAL
TERMINUX_AUTO_SETUP_WRAPPERS 1 0:daemon 啟動時不安裝 hook 與 wrapper
TERMINUX_DISABLE_PACKAGES 不設 truthy:停止 package 派送
TERMINUX_DISABLE_USER_PACKAGES 不設 停用使用者 package
TERMINUX_DISABLE_PLUGINS 不設 truthy:不訂閱舊的 plugin 管線
TERMINUX_FLOW_MAX_ACTIVE_TASKS、TERMINUX_FLOW_MAX_PARALLEL_EDA、TERMINUX_FLOW_MAX_PARALLEL_PROVIDER 各 1 task 的同時執行上限
TERMINUX_EAP3_BINDINGS_FILE 不設 Engineering Work 的 provider bindings(未驗證)
TERMINUX_FORMAL_YOSYS_EXE 不設 formal 驗證使用的 Yosys(未驗證)
TERMINUX_PURGE_ALLOW_USER 目前帳號 允許 purge --force 的帳號

由 Terminux 自己設定、不要手動設定的變數:TERMINUX_ACTIVE、TERMINUX_HOOKS_LOADED、TERMINUX_TRACE_ROOT、TERMINUX_TRACE_SELF、 TERMINUX_TRACE_PARENT、TERMINUX_TRACE_JOB、TERMINUX_TRACE_QUEUE、TERMINUX_VENV_PYTHON。

7.3 credentials.json

{
  "TERMINUX_OPENAI_API_KEY": "<key>",
  "TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com",
  "TERMINUX_GEMINI_API_KEY": "<key>"
}
  • JSON 物件;只認得 TERMINUX_OPENAI_API_KEY、TERMINUX_OPENAI_BASE_URL、TERMINUX_GEMINI_API_KEY,其他名稱忽略。
  • 必須是本人擁有、權限恰好 0600 的一般檔(不是 symlink);不符合時整份忽略。
  • TERMINUX_OPENAI_BASE_URL 預設 https://api.deepseek.com;本機服務例如 http://127.0.0.1:8080/v1。

7.4 llm_router.yaml(未驗證)

~/.terminux/llm_router.yaml 存在時,daemon 以它為 LLM router 的設定,不再依環境變數組合。格式:

realtime:   {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
background: {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
analysis:   {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
embedding:  {backend: noop}
鍵 欄位
realtime、background、analysis(三者皆必填) backend(openai_compatible、gemini、llama_cpp、none)、model_name、model_path(llama_cpp)、api_key、base_url(openai_compatible)
embedding(必填) backend(gemini、local、noop)、model_name、model_path、api_key
  • 字串中的 ${變數名} 會以環境變數展開;未設定的變數保留原樣。
  • 使用此檔時,router 的金鑰取自檔案中的 api_key,不讀憑證檔;請避免把金鑰直接寫在檔案裡。
  • 只要此檔存在,就可能把資料送到其中設定的 provider(見使用指南 13.2)。

7.5 Profile 檔

TERMINUX_AGENT_TASK_PROFILE_FILE 指定。必須是本人擁有、權限 0600、64 KiB 以內的 UTF-8 JSON 檔。任何不符都使整份無效,所有 AI 外送一律拒絕。

鍵 必填 型別與規則
profile_id 是 非空字串
tools 是 不重複的字串陣列;只能包含 query_orchestration_evidence
context_sections 是 不重複的字串陣列;只能包含 conversation_history
allowed_runs 是 物件:鍵為 run id(以 run_ 開頭,其餘為英數或 _),值為正整數 attempt。可為 {}
run_binding 否 物件,四個鍵皆必填(見下表);沒有此鍵時不能使用 /bind-run

不得出現其他鍵。

run_binding 的鍵 規則
max_runs_per_session 整數 1~8
require_runner 非空字串,不可前後有空白;terminux-orfs-run 的收據是 host_native
allowed_designs 非空、不重複的字串陣列,每項為 <platform>/<design>(各段只能含英數、_、-)
max_age_sec 整數 1~31536000(收據完成時間距今的最長秒數)

Profile 模式下 AI 的指示文字由 Terminux 固定提供,Profile 檔不能修改。

7.6 外送 policy 檔

TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE 指定。必須是本人擁有、權限 0600、64 KiB 以內的一般檔。

v2(建議):

鍵 規則
policy_version terminux.egress_policy.v2
approval_mode structural_c2(依資料類別與上限放行)或 exact_digest(只放行列出的請求內容雜湊)
endpoint 必須等於 <TERMINUX_OPENAI_BASE_URL>/v1/chat/completions
model 必須等於 TERMINUX_OPENAI_MODEL
allowed_payload_sha256 雜湊陣列;structural_c2 時必須是空陣列
approved_data_classes 允許外送的資料類別,取自:system_instructions、learner_text、conversation_history、tool_schema、tool_call、evidence_bundle、model_output、budget_summary、timing_path_evidence
limits 五個鍵皆必填(見下表)
non_agent_egress 只能是 deny
limits 的鍵 合法範圍
learner_text_max_chars 1~65536
history_max_turns 0~200
history_max_chars 0~262144
model_output_max_chars 1~262144
requests_per_turn 1~8
  • timing_path_evidence(timing path 的逐級資料)不在 approved_data_classes 時不會送出;evidence_bundle 不涵蓋它。
  • 舊的 v1 形狀(只有 endpoint、model、allowed_payload_sha256、approved_data_classes 四鍵)只能搭配 digest 白名單使用;新設定請用 v2。

7.7 外送紀錄的雜湊模式

TERMINUX_EGRESS_AUDIT_DIGEST 決定每筆外送紀錄如何記錄請求內容的完整性(紀錄本身不含內容):

值 說明
metadata_only 不記錄任何內容雜湊;不適用於需要外送紀錄的情境
plain_sha 記錄請求內容的 SHA-256
keyed_ephemeral 以 daemon 啟動時產生、不落盤的金鑰計算 HMAC;同一次 daemon 期間可比對,重啟後無法關聯
keyed_persisted 以 TERMINUX_EGRESS_AUDIT_KEYRING_FILE 的管理端 keyring 計算,並為每筆紀錄加上整筆 MAC;可在 daemon 重啟後驗證。keyring 內容改變即拒絕外送,輪替需重啟 daemon

policy 使用 structural_c2 時必須設定為後三者之一。紀錄位置:~/.terminux/run/<nodename>/egress_audit/<日期>.jsonl,保存 90 天。

7.8 STA playbook

  • 範本:套件內 terminux_engine/ecc/templates/sta_signoff_playbook.yaml;部署到 ~/.terminux/ecc/(部署方式見使用指南 4.5)。
  • 最上層為 playbook:,含 id、name、description、playbook_type、version、milestone_model、stage_specs。
  • 沒有 playbook 時 stage 追蹤、quality gate 與提示停用,其他功能不受影響;daemon log 會出現 TERM_ECC_PLAYBOOK_UNAVAILABLE。

7.9 preferences.json

~/.terminux/preferences.json:{"preferred_language": "zh-Hant"},值為 zh-Hant、en、zh-Hans。由右鍵 Language 寫入;讀寫失敗時退回 zh-Hant。

7.10 package.yaml(使用者 package,未驗證)

package:
  id: my_package             # 全域唯一
  version: 0.1.0
  api: terminux.package.v1
schema: 1
when:
  tools: [orfs]              # 這些工具執行完後派送
phases:
  after: after.run           # <模組>.<函式>;函式必須是模組頂層的 def
permissions:
  services: {file: read, store: write, notify: emit}

也可以在 actions: 下定義 action(handler、timeout_sec、description、parameters)。以 terminux-package-validate 離線驗證。

7.11 daemon 安裝的 hook 與 wrapper

位置 內容
~/.terminux/bin/ EDA 工具的 wrapper(指向 _terminux_wrapper 的 symlink)、terminux-notify、terminux-tcsh-postcmd
~/.terminux/hooks/bash_env、bash_rcfile bash 整合
~/.terminux/bash_hooks.sh、~/.terminux/tcsh_hooks.csh 給 rc 檔 source 的 hook

安裝是冪等的:不覆蓋你放在 ~/.terminux/bin 的同名檔或指向他處的 symlink,也不修改 rc 檔。


8. 檔案與資料參考

8.1 ~/.terminux

~/.terminux/
├── credentials.json            憑證(0600)
├── preferences.json            介面語言
├── llm_router.yaml             選用的 router 設定
├── terminux.db                 舊的命令紀錄
├── agent_tool_audit.jsonl      AI 工具使用紀錄
├── lineage_graph.html          最近產生的 lineage graph
├── lineage.<nodename>.jsonl    wrapper 的執行紀錄(舊版為 lineage.jsonl)
├── lineage_preexec.log         pre-exec 觀測 log
├── ecc/                        事件紀錄 event_store.db、ECC 快照、playbook、archive/
├── dqe/                        品質資料庫 dqe.sqlite、retention_policy.json、scheduled_clean.log
├── lineage/                    ledger.jsonl、artifact_manifests/、branch_tree.jsonl
├── orchestration/              daemon 的執行狀態 ledger.sqlite
├── memory/                     搜尋索引 search_index.db
├── rag_knowledge/、rag_index/  你的 RAG 知識與索引
├── tools/                      user_tool_catalog.yaml
├── packages/                   使用者 package
├── plugins/                    plugin 目錄(0.1.x 為空)
├── bin/、hooks/、bash_hooks.sh、tcsh_hooks.csh   hook 與 wrapper
└── run/
    ├── owner.lock/owner.json   daemon 所在主機與狀態
    └── <nodename>/             terminux.sock、lineage.sock、daemon.log、daemon.stdout.log、
                                relay.pid、relay.log、egress_audit/(Profile 模式)

~/.terminux 必須是本人擁有、group/other 不可寫的目錄,且不是 symlink。

8.2 執行收據(receipt JSON)

terminux-orfs-run --receipt-out 寫出的 JSON 主要欄位:

欄位 內容
schema_version 格式版本
run_id、step_id、attempt 執行身分;run_id 為 run_ 加 32 個十六進位字元;step_id 為 orfs-<design>-<variant>
tool_id、adapter_id、adapter_version 工具與 adapter 身分
tool_version_evidence 工具版本與身分的證據
started_at、finished_at 開始、結束時間(epoch 秒)
process_exit_code、timed_out、termination_reason 結束情況
stdout_tail、stderr_tail 輸出的最後幾行
execution_lifecycle_status、dispatch_status、evidence_status 執行、package 派送、證據就緒的狀態
output_roots 輸出根目錄
artifact_manifest_reference、artifact_manifest_id、artifact_capture_status 產物清單的參照與擷取狀態
adapter_metadata 含 runner(host_native)、platform、design 等

/bind-run 需要這個檔案;它也必須存在於事件紀錄中,且內容雜湊一致。

8.3 owner.json

~/.terminux/run/owner.lock/owner.json(0600):state(starting/ready)、host、nodename、pid、instance_id、version、started_at、 TCP 轉送的 core_port、lineage_port、token(或 unix_only_ipc)、hook 部署結果,以及只含列舉值與雜湊的啟動身分。 token 是 TCP 轉送的認證值,不要外流。

8.4 log

檔案 內容 輪替
run/<nodename>/daemon.log daemon 取得所有權後的結構化訊息 10 MiB,保留 3 份
run/<nodename>/daemon.stdout.log terminux-launch 收集的 daemon 輸出(取得所有權前) —
run/<nodename>/relay.log、relay.stdout.log relay 10 MiB,保留 3 份
run/<nodename>/egress_audit/<日期>.jsonl Profile 模式的外送紀錄(只有中繼資料與雜湊) 保存 90 天
agent_tool_audit.jsonl AI 工具使用紀錄 —
dqe/scheduled_clean.log DQE 排程清除 —

daemon 預設只記錄 ERROR;正常運作時 daemon.log 為空。


9. 品質判定(DQE)參考

9.1 ORFS 的檢查項目

檢查 說明 來源 必要
orfs_manifest_integrity 產物清單的身分與雜湊 產物清單 是
orfs_artifact_completeness 必要的產物都存在且穩定 產物清單 是
orfs_final_deliverables 已產生最終的 layout、DEF、database、netlist 產物清單 是
orfs_process_exit_code 工具行程的 exit code 為 0 執行結果 是
orfs_setup_wns Setup WNS ≥ 0(單位 ns) 6_finish.rpt 是
orfs_setup_tns Setup TNS ≥ 0 6_finish.rpt 否
orfs_setup_violation_count Setup 違規路徑數 = 0 6_finish.rpt 是
orfs_hold_violation_count Hold 違規路徑數 = 0 6_finish.rpt 是
orfs_max_slew_violation_count Max transition 違規數 = 0 6_finish.rpt 否
orfs_max_fanout_violation_count Max fanout 違規數 = 0 6_finish.rpt 否
orfs_max_cap_violation_count Max capacitance 違規數 = 0 6_finish.rpt 否
orfs_route_drc_violation_count Detailed route DRC 違規數 = 0 5_route_drc.rpt 是
orfs_log_error_markers log 錯誤標記數 = 0 ORFS log(6_report.log) 是
orfs_log_warning_markers log 警告標記數 = 0 ORFS log(6_report.log) 否

門檻是 signoff 的意義(例如 WNS 小於 0 就是違規),不是 ORFS 對個別設計的回歸門檻。

9.2 判定規則

  • 每項結果:pass、warn、fail、unknown(讀不到或無法判定)。
  • 整體結果:任何必要項目 fail → fail;否則任何一項 warn → warn;否則任何必要項目 unknown → unknown;否則 pass。 非必要項目的 unknown 不會讓整體變成 pass。
  • 整體結果為 warn、fail 或 unknown 時發出一則通知。
  • 判定只依固定規則,不使用 LLM,不做根因推論、不重跑、不修改設計。

9.3 品質紀錄的欄位

DQE Viewer 顯示的每一列對應品質資料庫中的一筆紀錄,主要欄位:ProjectCode、Phase、Block、Stage、Flow、Version、DQE_ID、 VALUE、UNIT、STATUS、DATE_TIME、Reporter、PATH、附件與可執行檔(各上限 5 MiB)、job_key(格式 YYYYMMDD_HHMMSS_NNN), 以及執行身分(run id、step id、attempt)。同一次派送重送時不會重複寫入。


10. 訊息與代碼參考

10.1 exit code 總表

命令 exit code
terminux-launch 0 成功;1 失敗
terminux-daemon 0 正常停止;2 socket 路徑無法解析;3 啟動失敗;4 已有 owner 或舊版 daemon
terminux-doctor 0 ready;1 attention
terminux-qt-check 0 通過;1 未通過
terminux-orfs-run 0、1、2、3、5、130、143(3.8)
terminux-orfs-report 0 成功;2 錯誤
python -m terminux_engine purge 0 成功;1 拒絕 --force;2 參數錯誤;5 owner 在其他主機
dqe-scheduled-clean 0 成功;1 失敗;2 參數錯誤;3 部分完成;5 owner 在其他主機
terminux-cold-backup 0 成功;2 前置條件不符
terminux-rollback-check 0 相容;2 不相容或讀不到;5 owner 在其他主機
terminux-work、terminux-package-new 0 成功;2 錯誤
terminux-package-validate 0 有效;1 無效;2 錯誤
terminux-package-test 0 全部通過;1 有失敗;2 錯誤
terminux-package-doctor 0 通過;1 有錯誤或失敗;2 參數錯誤

10.2 daemon 與 launcher 的代碼

代碼 出現在 意思與處理
TERM_DAEMON_OWNER_EXISTS daemon stderr(exit 4) 已有 daemon 持有 owner lock(可能在其他主機)。到 owner 主機使用或停止它;確認不存在後才用 terminux-launch --reset
TERM_LEGACY_DAEMON_RUNNING daemon stderr(exit 4) 舊版 daemon 仍在舊路徑 ~/.terminux/terminux.sock 上執行;先停止它
TERM_AGENT_SOCKET_UNAVAILABLE daemon(exit 2) socket 路徑無法使用;訊息中附帶下列細項代碼、UID 與預期路徑
TERM_RUNTIME_DIR_MISSING、_NOT_A_DIRECTORY、_IS_SYMLINK、_WRONG_OWNER、_TOO_PERMISSIVE、_UNAVAILABLE 同上 ~/.terminux 不存在、不是目錄、是 symlink、不是你擁有、group/other 可寫、無法使用。修正權限或路徑;Terminux 不會自動刪除既有檔案
TERM_HOME_DIR_UNRESOLVED、TERM_HOME_DIR_UNAVAILABLE 同上 無法從帳號資料取得家目錄,或家目錄不可用
TERM_AGENT_SOCKET_PATH_OCCUPIED 同上 socket 路徑被一般檔案、目錄或 symlink 占用
TERM_SOCKET_PATH_TOO_LONG 同上 socket 路徑太長(Unix socket 上限約 107 bytes);縮短 TERMINUX_HOME_DIR 或覆寫路徑
TERM_AGENT_SOCKET_OVERRIDE_INVALID 同上 TERMINUX_CORE_SOCK、TERMINUX_SOCK 或 TERMINUX_HOME_DIR 的值不合法
TERM_AGENT_SOCKET_LEGACY_PATH_REJECTED 同上 覆寫值是已退役的 /tmp/terminux.sock 或 /run/user/<uid>/terminux/terminux.sock
TERM_LEGACY_SOCKET_OVERRIDE_IGNORED daemon.log(WARNING) 覆寫值等於舊的預設路徑,已忽略並改用目前的規則
TERM_NODENAME_INVALID daemon、CLI TERMINUX_NODENAME 含不允許的字元
TERM_UNIX_ONLY_IPC_INVALID daemon TERMINUX_UNIX_ONLY_IPC 不是 0 或 1
TERM_SERVICE_START_FAILED daemon(exit 3) 啟動過程失敗;以 TERMINUX_LOG_LEVEL=INFO 重啟並查看 daemon.log
TERM_SOCKET_BIND_FAILED、TERM_LINEAGE_LISTENER_NOT_STARTED、TERM_SOCKET_CONFLICT_HINT daemon.log lineage socket 無法建立,AI 與背景分析不會啟動。能連上代表有人在使用,不可刪除;確認是遺留檔後再手動移除
TERM_DAEMON_OWNER_LOCK_RETAINED daemon.log 停止時無法確認資料已乾淨關閉,刻意保留 owner lock
TERM_EVENT_STORE_UNAVAILABLE daemon.log 事件紀錄無法開啟或寫入;package 派送與事件紀錄停擺。修正 ~/.terminux/ecc 後重啟
TERM_ECC_PLAYBOOK_UNAVAILABLE daemon.log 沒有 STA playbook(選用功能);其他功能不受影響
TERM_EGRESS_AUDIT_UNAVAILABLE daemon.log Profile 模式的外送紀錄目錄無法使用;外送會被拒絕
TERM_DATABASE_REMOTE_OWNER 直接開資料庫的命令(exit 5) daemon 在另一台主機;到該主機執行
TERM_DAEMON_OWNER_UNAVAILABLE terminux-launch、relay owner 狀態不是 ready、讀不到,或無法經 TCP 連上
TERM_DAEMON_OWNER_UNCONTAINED terminux-launch 你在 Profile 模式,但既有 daemon 不是以 Profile 模式啟動;先停止它再以 Profile 設定重啟
TERM_DAEMON_OWNER_IDENTITY_MISMATCH terminux-launch 既有 daemon 載入的 Profile/policy 與本次不同(Learner 發行版)
TERM_LAUNCH_DAEMON_NOT_READY terminux-launch 等 30 秒仍未就緒;hook 可能還沒部署
TERM_LAUNCH_WRAPPER_SETUP terminux-launch hook 部署失敗或停用;依訊息查看 daemon.log
TERM_LAUNCH_GUI_NOT_FOUND terminux-launch 找不到 GUI 執行檔
TERM_LAUNCH_RELAY_START_FAILED、TERM_LAUNCH_RELAY_START_TIMEOUT、TERM_LAUNCH_RELAY_STOP_TIMEOUT terminux-launch relay 啟動失敗、逾時,或停止舊 relay 逾時
TERM_LAUNCH_OWNER_DIRECTORY_UNSAFE terminux-launch --reset owner lock 不是你擁有的目錄,拒絕刪除
TERM_LAUNCH_FAILED terminux-launch 其他失敗;後面附原因

10.3 terminux-orfs-run 的代碼

代碼 意思
NATIVE_RUN_AS_ROOT_REFUSED 以 root 執行(exit 2)
NATIVE_SETUP_INVALID 找不到 env script、make 或其他執行設定不合法(exit 2)
DOCKER_EXECUTION_REMOVED 使用了已移除的 --docker-image(exit 2)
LEDGER_SHARED_WITH_DAEMON --ledger-db 指向 daemon 的 ledger(exit 2)
EXECUTION_RECEIPT_NOT_DURABLE 執行成功,但收據沒有寫入事件紀錄(exit 3)
PACKAGE_RECORD_STORE_UNAVAILABLE 事件紀錄無法開啟或寫入,package 的紀錄(含 timing path 證據)無法保存;exit code 的語意不變
EXECUTION_INTERRUPTED、EXECUTION_INTERRUPTED_BEFORE_START 執行中或開始前收到 signal
EXECUTION_CLEANUP_UNCONFIRMED 無法確認 flow 的 process group 已結束,因此不寫收據
EXECUTION_FINALIZATION_INTERRUPTED、SIGNAL_DURING_FINALIZATION、SIGNAL_AFTER_PERSISTENCE 在收尾階段或收據寫入後才收到 signal;收據已完成後收到的 signal 不改變 exit code
TERMINUX_DESIGN_NICKNAME_MISMATCH --design 與 ORFS 解析出的 design 名稱不一致,flow 開始前停止
TERMINUX_FORBIDDEN_ENV 環境或 env script 設定了不允許的變數:MAKEFLAGS、GNUMAKEFLAGS、MAKEOVERRIDES、MAKEFILES、DESIGN_CONFIG、FLOW_VARIANT、WORK_HOME、IN_NIX_SHELL,以及未以 --openroad-exe/--yosys-exe 指定時的 OPENROAD_EXE、YOSYS_EXE。這些值只能來自 Terminux 組裝的參數
TERMINUX_NATIVE_TOOL_MISSING、TERMINUX_NATIVE_TOOL_DIGEST_MISMATCH、TERMINUX_NATIVE_TOOL_REALPATH_CHANGED 宣告的工具不存在,或執行期間工具檔案的內容或實際路徑改變

10.4 @@ 回應中的代碼

代碼 意思
RUN_BOUND 綁定成功(或已綁定)
RUN_UNBOUND 已解除綁定
RUN_NOT_BOUND 這個 session 沒有綁定的 run
RUN_BIND_DISABLED 沒有有效的 session,或 Profile 沒有 run_binding
RUN_BIND_USAGE 指令格式錯誤(/bind-run 需要一個絕對路徑;/unbind-run 不帶參數)
RUN_BIND_UNSUPPORTED 不支援的參數(例如 last),請給收據的絕對路徑
RUN_BIND_RECEIPT_UNREADABLE 收據路徑不是絕對路徑、讀不到,或不是一般檔
RUN_BIND_RECEIPT_INVALID 收據不是合法的 JSON,或缺少 run_id、attempt、adapter_metadata
RUN_BIND_NOT_PROJECTED 事件紀錄中找不到這次 run 的正式收據
RUN_BIND_FOREIGN_OR_UNTRUSTED 同一個 run 有不是你寫入的紀錄,或紀錄的內容雜湊不一致
RUN_BIND_ATTEMPT_MISMATCH 事件紀錄中沒有這個 attempt
RUN_BIND_AMBIGUOUS 同一個 run/attempt 對應到多筆紀錄
RUN_BIND_OUTSIDE_POLICY runner、<platform>/<design> 或收據時間不符合 Profile 的 run_binding
RUN_BIND_LIMIT 已達 max_runs_per_session
RUN_BIND_AUTHORITY_UNAVAILABLE 事件紀錄無法使用
RUN_BIND_POLICY_UNAVAILABLE 外送 policy 讀不到,拒絕綁定
TASK_POLICY_INVALID Profile 檔無效(格式、權限、大小),所有 AI 外送被拒絕
PROFILE_PROVIDER_UNSUPPORTED Profile 模式只支援 openai_compatible backend;沒有送出任何請求
LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE Profile 模式下只有 /bind-run、/unbind-run 可用;沒有執行或送出任何東西
CLOUD_AGENT_CAPABILITY_DENIED 雲端 backend 的 AI 嘗試使用不允許的工具
PLAN_BATCH_CONTROL_NOT_SUPPORTED 使用了 /approve-plan、/execute-plan、/approve-all
PROPOSAL_PENDING_LIMIT_EXCEEDED 這個 session 待核准的提案已達上限(16 個)

10.5 task 的代碼(未驗證)

代碼 意思
TASK_NOT_FOUND_OR_OUT_OF_SCOPE task 不存在或不在你的範圍(刻意不區分)
TASK_DIGEST_MISMATCH task_digest 與草案不符
TASK_ORIGIN_SESSION_REQUIRED 只有建立這個 task 的 session 能開始它
TASK_INSTANCE_EXPIRED 不是目前這個 daemon 的 task(重啟前的歷史),只能唯讀
TASK_BUSY 名額已被其他 task 占用;沒有消耗任何授權
TASK_WORKER_UNCONFIRMED 前一個動作尚未確認結束,名額不可重用
TASK_ALREADY_STARTED 同一個 task 不可重複開始
TASK_REVALIDATION_FAILED 開始時的重新驗證不符
TASK_RUN_ACCESS_UNVERIFIABLE 無法證明你可以存取指定的 run
TASK_PROPOSAL_CONTROL_DENIED 不能用單筆提案指令操作 task 內部的提案
TASK_BUDGET_EXHAUSTED、TASK_DEADLINE_EXCEEDED 預算或期限用完,不再派工
TASK_EVIDENCE_INVALID 紀錄、範圍或雜湊不一致或缺失
TASK_OUTCOME_UNCONFIRMED 不確定動作是否完成;不會自動重送
TASK_INPUT_INVALID 建立時的輸入不合法
TASK_PROVIDER_UNAVAILABLE 分析所需的 LLM provider 不可用(查詢與取消仍可用)
LEGACY_DOCKER_EXECUTION_DISABLED、LEGACY_HOST_RUNNER_EXECUTION_DISABLED 舊的執行方式已停用;歷史 task 仍可讀取

11. 上限、逾時與預設值

項目 值
terminux-launch 等待 daemon 就緒 30 秒
GUI 重連 daemon 每 3 秒
GUI 取得背景通知 約每 1.2 秒;每次逾時 1.5 秒
daemon 的通知緩衝 500 則
通知列自動收合 滑鼠離開約 5 秒後
lineage 檢查(GUI 等待) 30 秒
hook 通知 daemon(terminux-notify) 2 秒;daemon 不在時靜默略過
csh/tcsh hook 設定提示 啟動後 10 秒內沒收到標記時
terminux-chat 120 秒;建立 session 5 秒
OpenAI 相容服務的請求 120 秒(TERMINUX_OPENAI_TIMEOUT_SEC)
terminux-orfs-run 900 秒(--timeout-seconds)
解說一次 run(explain_run) 300 秒
待核准的提案 10 分鐘後過期;每個 session 最多 16 個
執行結果 保存 30 分鐘(只在記憶體)
run 綁定 每個 session 1~8 個(Profile 設定);daemon 重啟即清除
task 同時執行 各上限預設 1
Profile、外送 policy 檔大小 64 KiB
daemon/relay log 10 MiB 輪替,保留 3 份
wrapper 執行紀錄 超過 10 MiB 時 gzip 備份,保留 3 份;每 300 秒檢查
外送紀錄 保存 90 天
品質紀錄的附件與可執行檔 各 5 MiB
DQE Viewer 保留期設定 1~3650 天
Core socket 單一訊息 1 MiB
package 測試的預設逾時 10 秒
terminux-work authorize 預設 attempts 2、provider dispatches 12、tool launches 5、candidate materializations 2

12. 名詞表

名詞 說明
attempt 同一個 run 的第幾次嘗試
artifact manifest(產物清單) 一次執行後對輸出檔的機械紀錄(路徑、大小、SHA-256),寫入後不可修改
baseline 比較時作為基準的 run
cloud backend openai_compatible 或 gemini;此時 AI 只能查證據
daemon 每個 Linux 帳號一個的背景服務
DQE Design Quality Evidence,以固定規則產生的品質判定
Engineering Work 有總預算的多輪工程工作(未驗證)
event records(事件紀錄) ~/.terminux/ecc/event_store.db,所有正式紀錄只增不改
flow task 固定步驟的有界任務:baseline → 解說 → 一項變更 → 候選 → 比較(未驗證)
host-native 以使用者帳號在主機上直接執行工具
job/job_key DQE 中一次執行的品質紀錄群組,job_key 格式為 YYYYMMDD_HHMMSS_NNN
lineage 資料血緣:一個步驟實際讀了哪些輸入、寫了哪些輸出
一般模式 沒有設定 Profile 時的運作方式;除了 run 綁定以外的本機指令都可用
owner 持有 owner lock、正在服務的 daemon
package package.yaml 加 Python 程式的擴充單位
Profile 模式 管理者限制 AI 範圍與外送資料的模式;設定錯誤一律拒絕
proposal(提案) 一個有副作用、待核准的動作;核准後執行一次
receipt(收據) 一次工具執行的正式結果紀錄
relay 非 owner 主機上的本機轉送
session GUI 或 CLI 連上 daemon 後取得的身分;連線關閉即失效
Temporary/Archived DQE 中尚未簽入的紀錄/已透過 isvn 簽入的版本