CAD 開發研究案例
影片
指南
TUT04 Developer Guide(S00–S07,CAD Engineer 版,v0.2.1)
你是一位 CAD Engineer。WNS 告訴你 Setup Path 沒過,卻沒有說明背後是哪些 Cell 和 Net。在這份 Guide 裡,你要擴充 Terminux,讓它能從 STA Report 取出一條 Reported Timing Path,變成結構化的 Evidence。你會請 Coding AI 協助找 Source,自己決定怎麼改,再用實際輸出和 Focused Tests 確認結果。
**這是一堂平台開發課。**不是教你詢問 Terminux AI 的 Timing 課程,也不是 ECO 流程或 Global Worst Path 分析。
兩個容易混淆的詞
- Flow Stage 是 Terminux 或 Design Flow 的執行階段,例如 Placement,語意不變。
- Path Element(路徑項目) 是 STA Report 中,一條 Timing Path 上依序排列的一個項目;內容視該列報告而定。例如索引 1 的
DFF_X1是路徑項目,Placement 則是 Flow Stage。 - Source 裡把路徑項目稱為
PathStage與parsed.stages,程式也會印出32 ordered stages。這些是真實名稱與真實輸出,一律維持原樣;它們指的不是 Flow Stage。
重放需要指定分支、a0ac96ee 與 b4aa3601 版本及 D1–D7 patches。缺少任一項時,請勿執行 patch 重放。
開始之前:這次重放的範圍
- D1–D7 在可丟棄的教材工作樹中重放,不是你的產品主樹,也不會有任何 Commit。
- 有三個範圍外檔案仍與
a0ac96ee不同:DESIGN.md、release/classification.txt、tests/packages/test_orfs_dqe_after.py。這不是 Byte-identical 的 Commit 重現。 tests/packages/test_orfs_dqe_after.py未執行。- Focused Tests 不能證明真實 CLI 已持久化。
a0ac96ee只產生RecordRequest;b4aa3601之後才接上真實 Run 的持久化。 - 本 Guide 不會執行 EDA,也不會呼叫 Terminux Provider。
圖片都是拍攝時的真實畫面。部分拍攝指令使用簡短的輔助命令,或印出比本文指令更多的內容,請比對數值,不要比對版面。
T04D-G01: 建立隔離的教材工作樹
Scene S00–S01
為什麼需要這一步: 修改團隊依賴的工具之前,先要有一個碰不到正式環境的工作區。
目的: 在可丟棄的 Clone 中工作,並固定在 Baseline,產品主樹完全不受影響。
前置條件: 含 feature/tut04-critical-path-evidence 分支的 Terminux Repository;Git。開一個 Shell,整份 Guide 都在同一個 Shell 操作。
固定版本: Baseline 338bff770f2ab9a4906583407bec65f81a44a327
工作目錄: 你的 Terminux Repository 根目錄,之後是 $TUT04_WORK/teach
操作:
export TERMINUX_REPO="$(git rev-parse --show-toplevel)"
export TUT04_WORK="${TUT04_WORK:-$HOME/tut04-workshop}"
export TUT04_PATCHES="${TUT04_PATCHES:-$HOME/tut04_production_private/platform_dev_phase_a_20261109/diffs}"
mkdir -p "$TUT04_WORK"
git clone -q --no-hardlinks --no-checkout --no-tags --single-branch --branch feature/tut04-critical-path-evidence "$TERMINUX_REPO" "$TUT04_WORK/teach"
git -C "$TUT04_WORK/teach" remote remove origin
git -C "$TUT04_WORK/teach" switch -q --detach 338bff770f2ab9a4906583407bec65f81a44a327
cd "$TUT04_WORK/teach"
P=engine/src/terminux_engine
git rev-parse --short=8 HEAD; git status --short | wc -l; git remote | wc -l
預期結果: 338bff77,接著 0 個修改檔案。

拍攝時的 Baseline 確認:固定的 Commit,沒有任何修改。
驗證: git remote 沒有輸出,代表這棵樹無法 Push。
失敗分支: Clone 或 switch 失敗表示你的 Repository 沒有這些 Commit。請 STOP,不要改用其他分支。
AI Prompt: 本步驟不使用 AI。
限制: ENV_SPECIFIC:Repository 與工作路徑。
下一步: 看 Terminux 現在怎麼處理 Timing。
T04D-G02: 閱讀修改前的狀態
Scene S01
為什麼需要這一步: WNS 告訴你問題存在,但要追原因就需要 Path。先弄清楚工具已經提供什麼,才不會重做一套。
目的: 確認現在有什麼(Scalar DQE)、還沒有什麼:一條 Timing Path 上依序排列的路徑項目。
前置條件: 已完成 G01。具備專案相依套件的 Python 環境。
固定版本: 338bff77
工作目錄: $TUT04_WORK/teach
操作:
export TUT04_PY="${TUT04_PY:-$TERMINUX_REPO/.venv/bin/python}"
tut04_py() { env -i HOME="$TUT04_WORK" PATH=/usr/bin:/bin LANG=C.UTF-8 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH="$TUT04_WORK/teach/engine/src:$TUT04_WORK/teach" "$TUT04_PY" "$@"; }
sed -n '53,62p' $P/packages/orfs_dqe/parsers.py
sed -n '134,137p' $P/packages/orfs_dqe/parsers.py
sed -n '320,324p' $P/packages/orfs_dqe/evaluator.py
git grep -n -E 'Startpoint|Path Type' -- $P/packages/orfs_dqe/parsers.py $P/packages/orfs_dqe/after.py; echo "exit=$?"
ls $P/timing_evidence 2>&1 | cut -c1-90
tut04_py -c 'from terminux_engine.packages.orfs_dqe import timing_path' 2>&1 | tail -1 | cut -c1-70
預期結果: extract_finish_scalar 的簽名;Evaluator 依檢查規格呼叫它;git grep 回 exit=1;timing_evidence 顯示 No such file;timing_path 出現 ImportError。

拍攝時的修改前狀態:Scalar Parser、Evaluator 呼叫、這兩個檔案的搜尋回 exit=1,以及還不存在的 timing_evidence。
驗證: exit=1 只代表這兩個檔案沒有符合的內容,不代表「Terminux 沒有 Timing 分析」:DQE 已能評估 WNS 等摘要指標。
失敗分支: 如果 timing_path 可以 Import,代表 PYTHONPATH 指向別的工作樹。請先修正再繼續。
AI Prompt: 本步驟不使用 AI。
Source 證據: 338bff77 的 parsers.py L53–62、L134–137;evaluator.py L320–324。
限制: NEEDS_LOCAL_VERIFICATION:TUT04_PY,本次以 Repository 自帶的 .venv(Python 3.12)驗證。
下一步: 找出新資料要走哪條路徑。
T04D-G03: 用審核過的摘錄詢問 Coding AI,再自己核對 Source
Scene S02
為什麼需要這一步: Terminux 的資料流跨好幾個檔案,用猜的很容易接錯。AI 提供線索,判斷是否屬實的是你。
目的: 讓 Coding AI 協助追資料路徑,但只提供你審核過的摘錄,並親自以 Source 核對它的說法。
前置條件: 已完成 G02。檔案存取權限確實可受限的 Coding AI 工具。只寫在 Prompt 裡不算檔案系統限制。
固定版本: 338bff77
工作目錄: $TUT04_WORK/teach
操作:
X="$TUT04_WORK/excerpt-only/excerpts"; mkdir -p "$X"
sed -n '53,63p' $P/packages/orfs_dqe/parsers.py > "$X/01_parsers_scalar_dataclass.txt"
sed -n '134,174p' $P/packages/orfs_dqe/parsers.py > "$X/02_parsers_extract_finish_scalar.txt"
sed -n '320,324p' $P/packages/orfs_dqe/evaluator.py > "$X/03_evaluator_scalar_dispatch.txt"
sed -n '88,160p' $P/packages/orfs_dqe/after.py > "$X/04_after_emit.txt"
sed -n '36,50p' $P/orchestration/evidence_bundle.py > "$X/05_evidence_bundle_class.txt"
sed -n '441,453p' $P/orchestration/daemon_service.py > "$X/06_daemon_receipt_bundle_branch.txt"
sed -n '28,40p' $P/llm/egress_policy.py > "$X/07_egress_data_classes.txt"
wc -l "$X"/*.txt | tail -1
grep -n -E 'record = RecordRequest|records=\[record\]' $P/packages/orfs_dqe/after.py
grep -n 'class EvidenceBundle' $P/orchestration/evidence_bundle.py
grep -n 'V2_DATA_CLASSES = ' $P/llm/egress_policy.py
預期結果: 七個摘錄檔。詢問 AI 後,回答應指出真實 Symbol,並說明無法檢視的部分。接著:record = RecordRequest( 在 L109、records=[record] 在 L154、EvidenceBundle 在 L36、V2_DATA_CLASSES 在 L34。

拍攝時畫面上的回答;完整原文見附錄 B。

回到 Source 核對:after.py 回傳 records=[record]。
驗證: AI 引用的每個 Symbol 都必須存在於所述行號或其附近。其餘一律視為未驗證。
失敗分支: 無法把 AI 限制在這個目錄時,請跳過 AI,自己閱讀摘錄。絕不要把 Repository、Report 或憑證交給它。回答不理想就保留並自行核對,不要反覆重問到滿意為止。
AI Prompt: excerpt-only/question.txt,見附錄 A。拍攝時的回答見附錄 B。兩者都是原文,其中的 "stage" 維持原樣。
限制: 呼叫 AI 本身不在 Guide 自動檢查範圍內。
下一步: 決定哪些程式只負責讀報告,哪些資料應該能沿用到別的 STA Tool。
T04D-G04: 決定責任分層
Scene S03
為什麼需要這一步: CAD 環境常會換工具或 Report 格式。新資料若綁死在某一份 Report 的文字上,每次格式變動都會牽動後面的分析。
目的: 動手之前先決定分層,判斷依據是 STA Tool 或 Report 格式改變時的維護成本。
前置條件: 已完成 G03。
固定版本: a0ac96ee(唯讀)
工作目錄: $TUT04_WORK/teach
操作:
git show a0ac96ee:$P/packages/orfs_dqe/timing_path.py | sed -n '18,20p'
預期結果: Adapter 的 Docstring 說明它負責 OpenSTA 格式,tool-neutral 的 Model 位於 timing_evidence。

拍攝時回答的第 4 節,提案在 parsers.py 新增 sibling dataclass。

已驗證的設計:Adapter 的 Docstring 說明它負責 OpenSTA 格式。
驗證: 用自己的話說出三個理由:Adapter 理解 OpenSTA 文字,格式變動只影響這一層;Model 保存 Path 與有序的路徑項目,可沿用到其他工具;獨立的 Evidence Class 控制 AI 可以收到什麼。
失敗分支: 若你偏好擴充 parsers.py,請先寫下 Report 格式或 STA Tool 改變時要改哪些地方,再做比較。
AI Prompt: AI 提案在 parsers.py 新增 sibling dataclass,並維持 V2_DATA_CLASSES 不變(附錄 B 第 4 節)。a0ac96ee 早於這次對話,這次回答並未導致該 Commit。
Source 證據: a0ac96ee 的 timing_path.py L18–20。
限制: 這是設計取捨的教學說明,不是對原始開發過程的陳述。
下一步: 完成第一層:把 Report 文字變成有序的路徑項目。
T04D-G05: 套用 Parser 與 Model,看見有序的路徑項目
Scene S04
為什麼需要這一步: 後續分析需要的是有順序、有來源的 Path,而不是再多一個 Scalar。
目的: 重放已驗證的 Parser 與 Model Patch,把 Report 文字變成帶型別、有順序、能回溯到 Report 的路徑項目。
前置條件: 已完成 G04。D1–D7 Patch。
固定版本: 由 338bff77 → a0ac96ee 產生的 Patch
工作目錄: $TUT04_WORK/teach
操作:
git apply --check "$TUT04_PATCHES"/D1*.patch "$TUT04_PATCHES"/D2*.patch "$TUT04_PATCHES"/D6*.patch "$TUT04_PATCHES"/D7*.patch && git apply "$TUT04_PATCHES"/D1*.patch "$TUT04_PATCHES"/D2*.patch "$TUT04_PATCHES"/D6*.patch "$TUT04_PATCHES"/D7*.patch; echo "apply=$?"
git show a0ac96ee:$P/timing_evidence/__init__.py > $P/timing_evidence/__init__.py
: > tests/timing_evidence/__init__.py
git status --short | grep -E 'timing_path.py|timing_evidence/$' | cut -c1-70
sed -n '184,190p' $P/packages/orfs_dqe/timing_path.py
sed -n '321,337p' $P/timing_evidence/model.py | head -3
grep -rnE -i 'orfs|opensta|nangate' $P/timing_evidence; echo "exit=$?"
mkdir -p "$TUT04_WORK/demo"
cat > "$TUT04_WORK/demo/show_stages.py" <<'PY'
from terminux_engine.packages.orfs_dqe import timing_path as T
from tests.packages import orfs_dqe_timing_path_fixture as X
parsed = T.parse_worst_setup_path(X.FINISH_REPORT_PATH_SECTION.split("\n"))
print(f"{len(parsed.stages)} ordered stages")
for s in parsed.stages[:5] + parsed.stages[18:23]:
print(s.index, s.kind, s.role or "-", s.cell_type or "-", f"{s.incr:.2f}", f"{s.arrival:.2f}", s.fanout, s.cap)
PY
tut04_py "$TUT04_WORK/demo/show_stages.py"
預期結果: apply=0;新增 timing_path.py 與 timing_evidence/;Neutrality grep 顯示 exit=1(無符合);32 ordered stages。32 ordered stages 是目前實作的原始輸出文字;本教學稱其為 32 個有序 Path Elements,以免與 Flow Stage 混淆。

拍攝時套用 Patch 之後:apply=0,並多了新的 Parser 檔案與 timing_evidence/ 目錄。拍攝時這一步套用 D1、D2、D6;上方指令另外也套用 D7。

拍攝時的輸出。32 ordered stages 是程式目前的文字,本教學稱為 32 個有序路徑項目。拍攝用的輔助指令多印了標題列,請比對數量與各列內容。
驗證: 第 1 個路徑項目是 DFF_X1、0.12 ns。此 Fixture 中 Cell 與 Net 交錯。選取的是此區段的 Worst Reported Path,不是 Global Worst。
失敗分支: git apply --check 失敗時請 STOP,不要修改 Patch 或自行手寫程式;改用 git show a0ac96ee:<path> 唯讀檢視。
AI Prompt: 可選:請 AI 依你提供的摘錄說明 parse_worst_setup_path()。
Source 證據: D1、D2、D6、D7;timing_path.py L184–209、L512–518;model.py L321–337、L405–417。
限制: 在可丟棄工作樹中的 GUIDED_RECONSTRUCTION。Fixture 數值來自公開 GCD,Run 身分為合成。PathStage 與 parsed.stages 是 Source 中的真實名稱,指的是路徑項目,不是 Flow Stage;不要改名。
下一步: 看 Delay 在這條 Path 上怎麼分布。
T04D-G06: 計算 Feature,並保留不確定性
Scene S05
為什麼需要這一步: Delay 分布、Fanout、負載,以及 Report 精度的限制,決定你要先查哪裡。
目的: 從路徑項目算出 Delay Feature,並用公開 Fixture 手算核對。
前置條件: 已完成 G05。
固定版本: 教材工作樹中的 a0ac96ee 內容
工作目錄: $TUT04_WORK/teach
操作:
sed -n '401,409p' $P/timing_evidence/features.py | head -3
sed -n '78p;127p' tests/packages/orfs_dqe_timing_path_fixture.py
cat > "$TUT04_WORK/demo/show_features.py" <<'PY'
from terminux_engine.packages.orfs_dqe import timing_path as T
from terminux_engine.timing_evidence import features as F
from tests.packages import orfs_dqe_timing_path_fixture as X
parsed = T.parse_worst_setup_path(X.FINISH_REPORT_PATH_SECTION.split("\n"))
ev = T.build_evidence(parsed, run_id="run_" + "1" * 32, attempt=1, step_id="demo", artifact_manifest_id="am_demo",
artifact_manifest_sha256="0" * 64, artifact_instance_id=None, report_content_sha256=X.SOURCE_REPORT_SHA256)
fs = F.compute_features(ev)
top, cn = fs.max_stage_contribution.value, fs.cell_vs_net_delay.value
comb = top["max_combinational_stage"]
print("data_path", f"{fs.data_path_delay.value['value']:.2f}")
print("ck_to_q", f"{top['max_stage']['value']:.2f}")
print("combinational", f"{comb['value']:.2f}", fs.max_stage_contribution.status, comb["delta_t_candidates"])
print("cell", f"{cn['cell_sum']:.2f}", "net_shown", f"{cn['net_sum_shown']:.2f}", "net_upper_bound", f"{cn['net_sum_upper_bound']:.2f}")
PY
tut04_py "$TUT04_WORK/demo/show_features.py"
預期結果: Data Path 0.40、CK→Q 0.12、ambiguous 候選 [21, 23](索引 21 與 23 對應的候選路徑項目)、Cell 0.39、Net 顯示 0.00、Net 上限 0.08。

拍攝時的數值。拍攝用的輔助指令格式與 show_features.py 不同,請比對數字。

Source 中的算法:Data Arrival 減去 Launch Clock Arrival。
驗證: 手算:Data Arrival 0.47 − Launch Clock Arrival 0.07 = 0.40。路徑項目 23 的 Arrival 0.41 是累積值,不是 Data Path Delay。顯示 0.00 的 Net 不是物理零;0.08 是上限。兩個候選都未被證實是最慢,也都不是根因。
失敗分支: 數值不同時,請確認 Fixture 與 Patch 沒有被修改。
AI Prompt: 可選:請 AI 檢查單位或 Rounding 問題,並以 Fixture 核對它的說法。
Source 證據: features.py L138–153、L326–329、L401–409;test_features.py L146–150;Fixture 第 78、127 行。
限制: 公開 Fixture,不是真實 Run 的量測。
下一步: 讓 Terminux 的其他功能也能取得這些結果。
T04D-G07: 接上 Record、Bundle 與 Policy
Scene S06
為什麼需要這一步: Flow 跑完以後,找得到這份資料嗎?AI 是否只能取得允許提供的部分?
目的: 讓 Flow 跑完後 Terminux 找得到 Evidence、控制 AI 能收到什麼,並分清楚哪個版本做了什麼。
前置條件: 已完成 G06。
固定版本: a0ac96ee 內容;b4aa3601 唯讀
工作目錄: $TUT04_WORK/teach
操作:
git apply --check "$TUT04_PATCHES"/D3*.patch "$TUT04_PATCHES"/D4*.patch "$TUT04_PATCHES"/D5*.patch && git apply "$TUT04_PATCHES"/D3*.patch "$TUT04_PATCHES"/D4*.patch "$TUT04_PATCHES"/D5*.patch; echo "apply=$?"
git --no-pager diff -U0 -- $P/packages/orfs_dqe/after.py | grep -E '^[+-] +records' | cut -c1-80
sed -n '376,382p' $P/orchestration/evidence_bundle.py
grep -n 'TIMING_PATH_EVIDENCE_CLASS =' $P/llm/egress_policy.py
git grep -n -A1 'services = RuntimeServices(' a0ac96ee -- $P/orchestration/orfs_cli.py | cut -c40-140
git grep -n -A3 'services = RuntimeServices(' b4aa3601 -- $P/orchestration/orfs_cli.py | cut -c40-140
grep -c 'store=record_store' $P/orchestration/orfs_cli.py; echo "exit=$?"
預期結果: apply=0;After-hook Diff 顯示 records = [record, timing_path.collect_record(...)];Bundle 比對 Run、Attempt、Step 與 Manifest;新增 TIMING_PATH_EVIDENCE_CLASS。a0ac96ee 的 RuntimeServices(notify=...) 沒有 Store;b4aa3601 有 store=record_store ...。

拍攝時的 Diff:records 多了 collect_record 產生的第二筆。

唯讀歷史:a0ac96ee 沒有 store;b4aa3601 加上 store=record_store。
驗證: 三個層次不可合併:a0ac96ee 產生第二筆 RecordRequest,但未在真實 CLI 路徑持久化;測試用 EventStore 讓 Bundle 讀得到它(G08);真實 CLI 持久化是後來 b4aa3601 才接上。不要在此套用 b4aa3601,那是獨立的修改。
失敗分支: 如果工作樹裡出現 store=record_store,代表套用了別的內容。請從 G01 重建。
AI Prompt: Master 的 S06 Prompt(SUGGESTED_CODING_PROMPT),僅搭配你審核過的摘錄使用:"Show me the minimal integration points for the new timing record. Where does the after-hook emit it, how does the bundle select the same run, and how do we reject timing_path_evidence if the data policy doesn't approve it? Point to the real negative tests."
Source 證據: D3、D4、D5;evidence_bundle.py L376–396;task_scope.py L833–847、L1023–1034;orfs_cli.py L303(a0ac96ee)、L311–314(b4aa3601)。
限制: GUIDED_RECONSTRUCTION,加上唯讀的歷史核對。
下一步: 驗證資料該出現時會出現,不該提供時不會外送。
T04D-G08: 執行 Focused Tests:正向、Tool 移除、Gate 拒送
Scene S07
為什麼需要這一步: 只看一個 PASS 不夠。兩種行為都要有證據,也要知道每個測試不能證明什麼。
目的: 證明 Evidence 該出現時會出現,沒有授權時不會送出。
前置條件: 已完成 G07。Home 目錄以外、權限 0700 的 QA 目錄(tests/conftest.py 的要求)。
固定版本: 教材工作樹中的 a0ac96ee 內容
工作目錄: $TUT04_WORK/teach
操作:
export TUT04_QA="${TUT04_QA:-/var/tmp/tut04-qa-$(id -un)}"
install -d -m 700 "$TUT04_QA" "$TUT04_QA/root"; printf '%s\n' "$TUT04_QA" > "$TUT04_QA/.terminux-test-qa-parent"; chmod 600 "$TUT04_QA/.terminux-test-qa-parent"
mkdir -p "$TUT04_WORK/guard"
cat > "$TUT04_WORK/guard/egress_guard_plugin.py" <<'PY'
import ipaddress, socket, sys
def _audit(event, args):
if event == "socket.connect":
sock, addr = args
if sock.family in (socket.AF_INET, socket.AF_INET6) and not ipaddress.ip_address(addr[0]).is_loopback:
raise RuntimeError("egress guard: non-loopback connect")
elif event == "socket.getaddrinfo" and args[0] not in (None, "localhost", "127.0.0.1", "::1"):
raise RuntimeError("egress guard: dns")
sys.addaudithook(_audit)
PY
tut04_pytest() { env -i HOME="$TUT04_QA" PATH=/usr/bin:/bin LANG=C.UTF-8 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH="$TUT04_WORK/teach/engine/src:$TUT04_WORK/teach:$TUT04_WORK/guard" TERMINUX_TEST_QA_PARENT="$TUT04_QA" TERMINUX_TEST_QA_ROOT="$TUT04_QA/root" "$TUT04_PY" -m pytest -p egress_guard_plugin -p no:cacheprovider --no-header -q "$@"; }
B=tests/orchestration/test_evidence_bundle_timing_path.py; E=tests/llm/test_timing_path_egress.py
tut04_pytest "$B::test_matching_own_record_becomes_an_available_section" "$B::test_without_reader_the_bundle_has_no_timing_path_key" 2>&1 | tail -1; echo "exit=${PIPESTATUS[0]}"
tut04_pytest "$E::test_only_evidence_bundle_class_strips_timing_path" 2>&1 | tail -1; echo "exit=${PIPESTATUS[0]}"
tut04_pytest "$E::test_gate_denies_unapproved_timing_path_even_if_tool_layer_is_bypassed" 2>&1 | tail -1; echo "exit=${PIPESTATUS[0]}"
tut04_pytest tests/packages/test_orfs_dqe_timing_path.py::test_stage_table_matches_the_hand_derived_reference tests/timing_evidence/test_features.py::test_max_stage_is_launch_clock_to_q_and_combinational_max_is_ambiguous tests/packages/test_orfs_dqe_after_timing_path.py::test_after_emits_dqe_record_first_and_timing_record_second "$B::test_matching_own_record_becomes_an_available_section" "$E::test_only_evidence_bundle_class_strips_timing_path" "$E::test_gate_denies_unapproved_timing_path_even_if_tool_layer_is_bypassed" 2>&1 | tail -1; echo "exit=${PIPESTATUS[0]}"
預期結果: 分開執行三次:2 passed(正向)、1 passed(Tool 移除)、1 passed(Gate 拒送),皆 exit=0。再跑一組重點測試 6 passed。

正向:2 passed、exit=0,僅限測試 EventStore。拍攝時顯示完整 pytest 輸出,上方指令只印最後一行。

Tool 移除:1 passed、exit=0。

Gate 拒送:1 passed、exit=0。

重點測試:6 passed、exit=0。
驗證: 正向測試使用臨時的測試 EventStore:bundle["timing_path"]["status"] == "available" 不代表真實 CLI 已持久化。Tool 層移除該 Section,其餘照常送出;Gate 拒送則回 C2_CLASS_DENIED:timing_path_evidence。兩者是不同結果。
失敗分支: QA_PARENT_* 錯誤代表 QA 目錄或 Marker 不正確:請修正位置,不要放寬檢查。缺少相依套件時請停止此步並回報,不要貼上他人的輸出。
AI Prompt: 可選:請 AI 解釋測試失敗原因,再對照測試原始碼核對。
Source 證據: test_evidence_bundle_timing_path.py L138–144;test_timing_path_egress.py L217–223、L243–251。實跑紀錄見 SOURCE_VERSION_AND_TEST_EVIDENCE.md。
限制: 教材工作樹與 a0ac96ee 仍有三個範圍外檔案不同,且未執行 tests/packages/test_orfs_dqe_after.py,因此不是 Byte-identical 重現,也不是完整回歸。這些測試不是 Timing Signoff,也不是全平台 E2E。沒有 EDA、沒有 Provider。NEEDS_LOCAL_VERIFICATION:QA 路徑與 Python。
下一步: 真實 GCD Run 的紀錄屬於後續課程,不在本 Guide 範圍內。
附錄 A:拍攝時的問句(原文)
來源:NEWLY_CAPTURED_AI_REPLY,AGY CLI 1.4.10、gemini-4-argon-medium、effort medium,2026-11-09 呼叫一次,回答 sha256 eb440359…。這是新錄的教學素材,不是 2026-11-08 的原始開發過程。AI 回答維持英文原文。
I am a CAD engineer extending Terminux to extract stage-level timing evidence from the worst reported setup path in an ORFS finish report.
Only the supplied reviewed excerpts are available. Identify what they prove and what you cannot inspect. Do not infer unseen symbols or test results.
Trace how scalar DQE evidence currently leaves the ORFS after-hook and reaches the evidence bundle / AI data policy. Name the actual symbols visible here, say what is missing for stage-level evidence, and propose the smallest layer boundary.
Cite only supplied code; state explicitly anything you cannot verify. Read-only: no changes, no ECO. Keep the answer under 30 lines.
附錄 B:拍攝時的回答(原文,未修改)
來源:NEWLY_CAPTURED_AI_REPLY,AGY CLI 1.4.10、gemini-4-argon-medium、effort medium,2026-11-09 呼叫一次,回答 sha256 eb440359…。這是新錄的教學素材,不是 2026-11-08 的原始開發過程。AI 回答維持英文原文。
### 1. Scalar DQE Evidence Trace (Proven by Excerpts)
1. **Extraction (`packages/orfs_dqe/parsers.py`, `evaluator.py`)**: When `spec["extractor"] == "finish_section_scalar"` (L320–321), `parsers.extract_finish_scalar(lines, section=..., pattern=...)` (L134–174) calls `split_finish_sections(lines)`, matches the first regex `group("value")`, converts via `_to_number(raw)`, hashes the single matched line via `excerpt_hash`, and returns a `ScalarExtraction(value, section, line_start, line_end, excerpt_hash, problem)` (`value: float | int | None`, L53–63).
2. **Persistence & After-Hook Emission (`packages/orfs_dqe/after.py`)**: `_emit(ctx: PackageContext, evaluation: DqeEvaluation) -> PhaseResult` (L88–156) calls `db_writer.write_dqe_batch(ctx, _db_checks(evaluation), flow=DQE_FLOW, dqe_meta=_db_meta(evaluation), ...)` (L90–102) returning `receipt`. It builds:
- `record = RecordRequest(namespace=DQE_NAMESPACE, record_type=DQE_RECORD_TYPE, key=evaluation.evaluation_id, payload=payload, ...)` where `payload = evaluation.to_json_dict()` plus `payload["dqe_write"] = db_writer.receipt_to_evidence(receipt)` (L106–124).
- `facts` (`overall_status`, `counts`, `evaluation_id`, `policy_version`, `manifest_id`, L131–137) and `evidence` (`dqe_write`, `evaluation_id`, `manifest_id`, `manifest_sha256`, `overall_status`, L138–147) wrapped in `PhaseResult` (L149–156).
3. **Bundle Projection (`orchestration/evidence_bundle.py`, `daemon_service.py`)**: `EvidenceBundle` defines `dqe: dict[str, Any]` and `reports: dict[str, Any]` (L36–50). In `daemon_service.py` (L441–453), after `_read_receipt_projection(run_id)` and `make_receipt_projection_evidence_bundle(run_id, receipts=receipts)`, if `_resolve_execution_evidence` returns `evidence` with `evidence.dqe == "bound"` and `evidence.dqe_db_path`, `bundle["dqe"] = read_bound_dqe_items(Path(evidence.dqe_db_path), run_id)`, returned via `self._with_execution_evidence(bundle, evidence)`.
4. **AI Egress Policy (`llm/egress_policy.py`)**: `V2_DATA_CLASSES` (L33–37) includes `"evidence_bundle"` (alongside `V2_KEYS` with `"limits"`, `"approval_mode"`, etc., L39–40); `V1_DATA_CLASSES` (L29–32) only allows fixed digests like `"public_gcd_nangate45"`, `"sanitized_n1b_evidence"`, `"bounded_ecc"`.
### 2. What Cannot Be Inspected / Verified from Excerpts
- **Unseen parser/evaluator internals**: `split_finish_sections`, `_to_number`, `excerpt_hash`, how `ScalarExtraction` becomes `DqeEvaluation`, `_db_checks`, `_db_meta`, and `evaluation.to_json_dict()`.
- **Unseen DB & projection schemas**: `db_writer.write_dqe_batch`, `receipt_to_evidence`, `read_bound_dqe_items` SQLite schema/columns, `make_receipt_projection_evidence_bundle`, and normal (non-fallback) bundle assembly before line 441.
- **Unseen egress enforcement**: How `"evidence_bundle"` payload size/redaction (`"limits"`) or pin/cell/net sanitization is enforced in `egress_policy.py`.
### 3. Missing for Stage-Level Worst Setup Path Evidence
- **Multi-line structured extraction**: `ScalarExtraction` only holds a single scalar (`float | int | None`) and single-line `line_start == line_end` match (`extract_finish_scalar` returns on first matched line). It cannot represent an ordered list of timing path stages (instance/pin, cell type, incremental delay, cumulative arrival, transition/fanout, multi-line `line_start..line_end` span).
- **Storage & projection contract**: Whether `_db_checks` / `write_dqe_batch` / `read_bound_dqe_items` only persist flat scalar check rows or support structured stage lists in `bundle["dqe"]` vs. `bundle["reports"]`.
### 4. Smallest Layer Boundary Proposal
- **Keep `PhaseResult.facts`, `PhaseResult.evidence` (barrier receipt contract), and `V2_DATA_CLASSES` (`"evidence_bundle"`) unchanged.**
- **Parser (`parsers.py`)**: Add a sibling frozen dataclass (e.g., `StagePathExtraction` with `stages: tuple[StageRow, ...]`, multi-line `line_start`/`line_end`, `excerpt_hash`, `problem`) and table parser alongside `extract_finish_scalar`.
- **Evaluator → DB/Bundle (`evaluator.py` → `after.py` / `evidence_bundle.py`)**: Dispatch a new `spec["extractor"]` value in `evaluator.py`. Keep scalar checks in `_db_checks` intact; attach bounded stage-level path records either via `dqe_meta` / `RecordRequest.payload` or a dedicated `read_bound_dqe_items` subkey under `EvidenceBundle["dqe"]` (subject to verifying unseen `write_dqe_batch` / `read_bound_dqe_items` schemas and `V2_KEYS["limits"]`).