參考手冊
參考手冊
適用版本:Terminux 0.1.1。不同版本的命令與功能可能不同。
目錄
- 手冊說明
- 系統概觀
- 命令參考
- Terminux 終端機(GUI)參考
- DQE Viewer 參考
- @@ 參考
- 設定參考
- 檔案與資料參考
- 品質判定(DQE)參考
- 訊息與代碼參考
- 上限、逾時與預設值
- 名詞表
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 簽入的版本 |