loop-apidoc 技術導覽 — 給新進工程同仁

不可協商的核心不變式

供應商來源是「供應商文件明載內容」的唯一權威。

來源沒寫的東西，一律留 null 並記錄到 missing —— 絕不推論、絕不用 REST/OAuth 慣例補上。

驗證遇到缺漏會大聲失敗（fail loudly），而不是用猜測讓文件「看起來完整」。整個專案的每一個設計決策，都是為了守住這條線。

次級佐證也不會削弱它。供應商信件的人工摘錄可以填 missing,但它不是正式文件:與正式文件衝突時正式文件勝,它永遠到不了 explicit_support,而每一條只靠它成立的主張都會被逐條點名(ADR 0010)。

被動 Implementation Observation 不會削弱這條規則。它只回報精確 Applicability Envelope 內的經驗行為，使用獨立的 confirms／contradicts／inconclusive／out_of_scope 軸；任何結果都不會變成供應商來源支持。

反過來說，「來源沒寫」也必須拿得出證據：source_facts/ 會機械掃描 Markdown 來源的參數表與範例區塊，來源明明寫了、擷取卻空著就擋下；「之後再擷取」「需進一步擷取」這類佔位答案同樣擋下。要主張某欄位來源真的沒寫，就在 missing 裡具名——所以這道閘只逼出具名缺口，不會逼出捏造。

但要清楚它的界線：掃描只認得結構良好的 Markdown（標題、GFM 表格、圍籬區塊）。來源若被壓成一行行超長文字，掃出零筆事實，這道閘等於沒作用。閘門乾淨通過 ≠ 擷取完整——它擋掉的是「機械證明得了的遺漏」，其餘仍要人工核對。

寧可標記「缺漏」，也不編造內容

Loop Engineering

四個閉環：來源、品質、版本、交接

loop-apidoc 的工程重點，是讓來源、品質、版本與交接都能被機器重跑、被人核對、被 downstream 使用者接手，而不只是產一份文件。

Source-grounded loop

sources → extraction → provenance

所有輸出必須回到來源引用;來源沒寫的資訊留缺漏,不靠慣例補齊。

Quality loop

preparation · validate · score

preparation 在生成前標出需注意的治理項目,驗證阻擋錯誤,score 把完成品轉成可比較的品質訊號。

Version loop

run-dir → diff/report

兩次 run 能依 breaking/additive/changed/source_only 分類,讓版本更新有 downstream impact 判讀。

Handoff loop

integration-contract · examples · handoff/

OpenAPI 與固定產生的 integration-contract 是機讀契約；後者保留 typed transport、金額方向、冪等、線路幣別與跨端點 operational 規則，衍生的 Postman、SDK hints、任務清單與 examples 幫下一位工程師接手。

第五個 loop · 權威分離

回饋可以改善 exact-scope operational view，但不會改寫供應商文件

feedback 命令群組會評估被動 normalized observations、提出並保存 review case、要求獨立人工核准有期限 amendment，並解析 exact-scope Effective Contract。assessment 與 preview 不做 network I/O，輸出寫在 .foundry 外；只有明確的 submit／review／approve 會改動受治理狀態。

Normative Contract

供應商來源權威

不可變的已核准版本，記錄供應商文件明載內容。Foundry 全域 current 永遠指向此軸。

Implementation Observation

empirical · exact envelope

經消毒、digest-bound 的行為證據，記錄 producer、runner、replay、attempt、時間、環境、region、identity 與設定 scope。

Compatibility Amendment

reviewed · expiring · scoped

安全、可重現的差異可以提出，但必須由獨立人工核准；proposal 綁定完整 Normative release digest：contract、documentary fragments 與 support relationships。

Effective Contract

deterministic composition

一份 normative release 加上精確 target 適用的 active amendments；composition 會重驗完整 release digest，每個值都保留 normative 或 observed-override authority 及 lineage。

Provider Erratum：正式供應商更正是補充來源，必須重走 source-risk → source-quality → extraction → verification → assembly → review → Foundry approval，不能走 Compatibility Amendment 捷徑。

Bounded assurance：「fully verified」只代表這個精確 Applicability Envelope、這個時間、這個 suite version 與已宣告 material-claim coverage；有限測試無法證明普遍、永久的 100% 真實。

關鍵架構

兩段式：agent 擷取 ‖ 確定性 CLI 後段

這是你最需要先建立的心智模型。整條 pipeline 切成兩半，中間用兩個 JSON 檔當唯一交界，兩邊各自可獨立測試、獨立替換。

兩段式架構 — 不確定性集中在擷取前段；確定性後段只讀 seam JSON 並產生可重跑產物。

前段 · 不確定性

agent 擷取(Claude Code / Codex)

Agent 讀取前風險閘：前處理與 manifest 建立後，必須先通過 inspect-source-risk，任何 agent 才能讀取來源內容。
唯讀 subagent fan-out:主 agent 派出多個 subagent,每個只讀檔 / 搜尋 / 抓 URL,回傳結構化 JSON,從不寫檔。
主 agent 把回傳的 JSON 彙整、寫成交界檔。
依 SKILL.md 分段擷取(見下方十段),確保只記錄來源真正寫的內容。

唯一交界 (seam) inventory.json endpoints/*.json

後段 · 確定性純函式

assemble(deterministic CLI)

不擷取,只組裝 agent 寫出的 JSON。
依序跑 manifest → plan → preparation → generate → validate。
以 --json 回報 ok / run_dir / report,讓 agent 自行驅動修正。

為什麼這樣切? 把「需要語意理解、本質不確定」的擷取交給 agent,把「組裝、生成、驗證」這些必須可重現的步驟交給確定性程式碼。曾經有過用子行程 claude -p 擷取的 run-agent 模式與 NotebookLM 後端,皆已於 2026-06 退役,現在 agent-native 是唯一擷取路徑。

Core shadow seam。以 assemble --architecture-mode shadow 明確啟用。Legacy report 寫出後，shadow/ 把記憶體中的 manifest 與 plan 映成 Core evidence/claims，只執行到 Core validation，並把觀測性產物寫入 <run-dir>/core/。它不會 approval、publish、更新 Foundry，也不改 legacy status 或退出碼。另有阻斷式 candidate 路徑 assemble --architecture-mode strict：每個 legacy-supported material claim 都必須重新驗證到 exact evidence，才會寫入未核准的 Core release；Foundry 會在核准前獨立驗證 strict record。選填 v1 evidence[] 會在 run 前重新 materialize，並驗證 source identity、locator、digest 與 claim path。Claim path 會以 explicit_support、derived_support、contradicts 或 insufficient 綁定 exact fragment。沒有 parsed scalar 的 prose 只能支援它精確綁定的單一 claim；OpenAPI structural derivation 限 versioned allowlist，並由 Core 連同所有必要 context fragments 重新計算。整份文件級的 legacy citation 不會變成 supported；請檢查 relationships.json 與 projections/provenance.json。

端到端資料流

一次完整執行，經過哪些階段

每一階段都有明確的輸入 / 輸出(產物)。原始 PDF／Word 必須先轉成可掃描文字，manifest 綁定的 source-risk gate 也必須在 agent 擷取前通過。灰色標記的是可選階段;preparation、score、diff、review 與 handoff 讓一次 run 從「生成」延伸成可審查、可比較、可交接的工程資產。

端到端資料流 — 主幹流程產出 run-dir；score、diff 與 review 把完成品延伸成品質、版本與人工結論訊號。

0preprocess / normalize 原始 PDF／Word 在風險掃描前先轉成支援的文字；內建 preprocess 處理 PDF／DOCX → Markdown，DOCX 並經 bounded、fail-closed OOXML 驗證。可掃描來源目錄

1manifest 盤點稍後 agent 將讀取的精確文字來源。 manifest.json

2inspect-source-risk 掃描 manifest 綁定文字的兩個方向 —— 會不會操縱 agent、會不會洩漏東西給 agent；不改寫來源、不回顯 payload；blocker 或 unscannable 輸入會在 agent 接觸前拒絕。 source-risk-report.{json,zh-TW.md}

3assess-sources 驗證必要的 risk-report binding、嵌入 audit，再評估可追溯的來源品質 observation。 source-quality-report · source-diff

4擷取只有此時 agent 唯讀 fan-out 才讀來源，由主 agent 寫出交界 JSON。 inventory.json · endpoints/*.json

5plan 把擷取結果規格化成計畫,並做來源比對分類。 plan/normalization-plan.json

6preparation 生成前評估 manifest、inventory、endpoint JSON 與 plan 的就緒度。 preparation-report.{json,md}

7generate 生成 OpenAPI、中文指南、人工核對頁、來源追溯與交接輔助產物。 openapi.yaml · api-guide.zh-TW.md · review.html · provenance.json · handoff/

8validate 結構 / 完整性 / 一致性 / 禁止推測四類檢查並出報告。 validation/report.{json,md}

9score 對完成的 run-dir 做品質評分,不改變 validate 的 pass/fail 語意。可選 → score/score.{json,md}

10diff 比較兩個已完成 run-dir,依 downstream impact 分類差異。可選 → diff/report.{json,md}

11review 在本機比對 candidate 與 current／baseline，保存人工結論並可明確核准。可選 → .foundry/api/.../review/decision.json

CLI 介面

CLI 指令，各司其職

CLI 進入點是 Typer(cli.py)。注意:擷取不在 CLI 裡 —— 那是 agent 的事;CLI 只負責後段與工具步驟(來源處理、URL evidence、來源品質、run 處理、資產治理與本機人工覆核)。

preprocess

PDF／DOCX → markdown；DOCX 另產生 deterministic source-hash provenance，並在輸出前拒絕 unsafe OOXML。

manifest

掃描本地來源 + URL,建立 manifest.json。

snapshot-openapi-url

固定單一 Swagger/OpenAPI JSON/YAML URL 為不可變本機來源，並建立 direct coverage ledger。

catalog-url

只下載入口頁一次,建立側欄導航索引(coverage universe);絕不自動擷取子頁。

select-url

依明確範圍(分支/關鍵詞)選取 catalog 節點作為閱讀起點;不下載任何 URL。

cache-url-pages

快取 catalog 全部頁面,建立本機正文/連結/實體索引(corpus.json);不呼叫模型。若頁面是未渲染 SPA shell，只探測同 origin 的 /swagger.json、/openapi.json、/v3/api-docs、/api-doc/v3/sections；僅根欄位含 openapi 或 swagger 的 JSON 另存為獨立 corpus source。失敗、非規格與一般 JSON 不記錄，shell 計數只寫至 stderr，不會自動 headless rendering。

cache-url-entry

直接快取單一入口頁,供空 catalog 或單頁文件使用。

normalize-html-snapshot

把靜態 HTML 快照正規化為受支援 Markdown,並保留 URL/SHA-256 provenance sidecar。

import-rendered-url

把受保護頁面的 browser-rendered HTML/Markdown 匯入為 immutable 本機證據、版本化 provenance 與 fetched_rendered coverage。驗證匹配後 manifest/assemble 省略該 origin probe；mismatch fail closed。

import-supplementary-note

把供應商信件／通訊軟體補充說明的人工摘錄匯入為次級佐證,寫出綁定內容的 provenance sidecar(出處、收到時間、摘錄者、SHA-256)。它填得了 missing,支撐不了 explicit_support,也不進新鮮度指紋 —— 分界線是可重新取得性。摘錄由人所寫,sidecar 買到的是可追責,不是可驗證(ADR 0010)。

related-url-pages

依正文連結與共享實體輸出候選頁卡片,模型只在需要時讀取候選頁正文。

inspect-source-risk

任何 agent 讀來源前的必要步驟。掃描 manifest 綁定的 Markdown、HTML、OpenAPI JSON/YAML，不改寫來源、不回顯命中 payload；原始 PDF／Word 無法掃描，須先轉檔。

退出碼：0 pass · 1 reject · 2 輸入無效、過期、不安全或不可讀。

assess-sources

擷取前來源品質閘：要求 --source-risk、驗證其來源／manifest binding、嵌入 audit，再評估可追溯 observation。reject 可回傳來源明確連出的去重 required_source_refs 作為 bounded next-capture list，不自動 crawl。

verify-extraction

檢查 agent 產出的擷取 JSON 是否符合 assemble 輸入契約;不寫檔、不建立 run-dir。選填 v1 evidence[] 會重新 materialize、驗證 digest 並解析 claim path。契約包含來源事實盤點:來源小節白紙黑字列了參數表或範例區塊,擷取卻空著,就是靜默遺漏而非「來源沒寫」;要主張來源沒寫,必須在 missing 裡具名該欄位。

assemble

組裝 agent 寫出的 JSON → plan → preparation → generate → validate,以 --json 回報;可選 --score、--url-coverage，但必須帶 --source-quality。assemble 會重建 manifest，並在建立 run-dir 前重新驗證內嵌 source-risk binding，拒絕未稽核 run，但不宣稱能證明流程外讀取來源的時間順序。

退出碼:0 驗證 PASS · 1 驗證 FAIL · 2 擷取輸入檔錯誤(不留孤兒目錄)。

validate

對既有 run-dir 重跑驗證並出報告(不重新生成)。

score

讀取既有 run-dir 的 OpenAPI、provenance、manifest 與 validation report,產出品質評分。

退出碼:0 pass · 1 needs_attention / fail · 2 run-dir 輸入錯誤。

evaluate

比較同案例版本的兩份 runtime replay JSON，產出品質、成本與延遲 delta 的 immutable 報告；不會組裝、匯入或核准契約。

feedback

實作 conformance 命令群組：assess（0 結案、1 可審查／未解、2 錯誤）、propose（0 有提案、1 無提案、2 錯誤）、submit（immutable candidate case stage）、review（有／無 proposal 都可寫入一次 non-approval decision 與 corrective route）、approve（分開的 immutable approved Effective release；獨立人工、expiry 必填、exact-scope 發布）、compose（不發布的預覽）、current（要求 timezone-aware --at 的 exact-target Effective 查詢），以及 provider-erratum（不改動狀態、交棒至完整 normative source pipeline）。Current lookup 會拒絕 not-yet-effective／expired asset、非 current normative base、stale pointer／artifact digest，並揭露 validity、open／untested、stale amendment 與 unresolved contradiction counters。同 target 衝突會 fail closed，除非明確記錄同 scope supersession。Foundry 全域 current 維持 normative。

governance-scan

把 freshness watchlist 的批次結果轉成受控的人工處理觸發：變動來源為 review_required，無法判定或讀取錯誤為 attention_required。選填 --snapshot-dir 僅保存同次掃描中已變動的原始 bytes，作為不可覆寫、內容定址的 evidence pack；不會重新擷取、生成、匯入 Foundry 或核准契約。

diff

比較兩個已完成 run-dir 的版本差異。

退出碼:0 完成 · 2 輸入 run-dir 缺檔或格式錯誤(DiffInputError)。

foundry

專案本地資產治理子群組(init / import / approve / list / current):把完成的 run 匯入為 candidate,核准成版本化 asset 並維護 current 指標。

review

以 127.0.0.1 工作台自動匯入 candidate、比對 current／baseline、保存 review/decision.json handoff；只有人工明確核准才更新 current。它不呼叫模型，也不取代 validation。

擷取分段

擷取拆成十段

為什麼分段?避免單一回答承載全部內容而失真。agent 依這十段逐步擷取,收斂成 inventory.json 與逐 endpoint 的 endpoints/*.json。

01來源盤點

02API 系統概覽與術語

03環境 / base URL / 版本

04驗證 / 授權 / 簽章

05Endpoint 清單

06逐 endpoint 細節(method / path / 參數 / req / resp / 範例)

07共用 schema / enum / 資料限制

08錯誤碼與失敗行為

09operational 限制、跨端點業務規則、欄位語意與公式

10來源衝突、缺漏、無法確認事項

產物

一次 run 交付契約、證據與交接資產

核心產物提供 API 契約與來源依據;衍生產物提供品質判讀、版本比較與 downstream 工程交接。

標準規格

openapi.yaml

OpenAPI 3.1,工具鏈與工程師可直接取用,不必各自解讀來源。

繁中串接指南

api-guide.zh-TW.md

給人讀的 Traditional Chinese 指南,不必硬啃原文。

來源追溯

provenance.json

每項輸出都標明出自哪份來源、哪一段,可逐一交叉比對。

驗證報告

validation/report

列出缺漏／衝突，也會揭露 supported 但零引用的來源與無可用 schema 欄位的成功 response。

品質評分

score/score.{json,md}

把五類品質轉成可比較分數，並列出 response 欄位數、operation 數與空殼 operation 數。

交接包

handoff/ · examples/

任務清單、Postman collection、SDK hints 與請求範例,協助串接工程師接手。

人工核對頁

review.html

離線可開的單檔 HTML,把範圍、來源、API 結構與規格治理清單彙整成一頁,供人眼快速核對。缺漏、來源衝突與未確認事項會保留為可追蹤項目；文件未提供 Server URL、authentication details 或 sandbox credentials，本身不等於整合風險。

可追溯 ↔ 驗證對齊

禁止推測，靠 target 逐一對齊來把關

這是「絕不臆測」如何被機器強制執行的關鍵機制：provenance.json 的 target 字串，與 OpenAPI 位置一對一對齊。

target 一對一對齊 — provenance 的 target 字串與 OpenAPI 位置一對一對齊，是 no-speculation 檢查的比對基準。

no-speculation 檢查就在這些 target 上交叉比對:任何進入輸出的內容,都必須能追溯回一個具來源依據的計畫項目,否則視為違規。對齊的位置包含 paths.{path}.{method}、components.schemas.{name}、components.securitySchemes.{name}。

修正迴圈

驗證問題會被分類，而不是盲目重試

沒有 CLI 內建的修正迴圈。assemble 回報分類結果,修正由 agent 自行驅動:回頭重讀來源、覆寫對應 JSON、再跑一次,最多 3 輪。問題分兩類:

可修正(FIXABLE)

OPENAPI_INVALID · OUTPUT_MISMATCH

產物本身有誤 → agent 修正 JSON 後重新生成即可。

REQUIRED_INFO_MISSING

必要資訊缺漏 → agent 回頭重讀受影響來源,補齊那一塊。

不可修正(fail-closed)

SOURCE_UNVERIFIED · SOURCE_CONFLICT · UNSUPPORTED_ASSERTION

來源無法確認 / 彼此衝突 / 不被支援的斷言 → 不補寫,如實回報為缺漏或衝突。這正是核心不變式落地的地方。

回歸證據架構

Benchmark 有四層，SKIP 不是 PASS

新工程師最容易把「fixture 已提交」「測試找到 case」「來源斷言跑過」混成同一件事。Harness 刻意拆成四層；完整定義與加 case 流程見 docs/BENCHMARK_VALIDATION_PLAN.md。

1 · Committed inventory

fixture identity

case 同時具有 extraction/inventory.json 與 expected/validation.expect.json；目前共 13 個唯一 case。

2 · Discovery guard

CI-safe

即使本機沒有來源快照，CI 仍確認所有 fixture 可被探索，並與 required inventory 完全一致。

3 · Source-backed execution

original sources required

只有原始、具日期的 sources/ 存在時，assemble 與產物斷言才會執行；缺來源會 SKIP。

4 · Strict-local preflight

all sources · zero skips

要求全部 required case 都有非空來源、所有 source-backed checks 跑完，且零 skip。

為什麼來源不進 git？ 部分上游文件有著作權、存取限制或不可再散布，所以 benchmarks/<case>/sources/ 是 operator 提供、gitignored 的原始快照。CI 可以證明 committed/discovered/exact parity，卻不能把來源缺席的 SKIP 稱為通過。找不到歷史快照時也不能拿新版文件、合成資料或錯誤頁面頂替。

補充 sanitized-fixture lane： scripts/quality_gate.py --sanitized-fixtures 可在 CI 重播經審核、保留原始行號的 exact-evidence 片段。目前 pilot 是 rsg-game-transfer-wallet。它在四層之外，只證明 retained claims 的 fixture-backed parity；不能替代原始 sources/，也不能稱為 source-backed 或 strict-local PASS。

Implementation-backed conformance lane：runtime observation 會以 Applicability Envelope、時間、suite version 與 open discrepancy 分開回報，不能算 documentary grounding，也不能算 source-backed strict-local PASS。

版本差異

換版本時，依 downstream impact 分四類

diff 拿同一支 API 的新舊兩個已完成 run-dir 相比,看的是「這次改版會不會害到下游串接」,而不是「來源改了哪幾個字」。每一筆差異都被歸到下面四種 impact 之一,並依嚴重度由高到低排序,讓你一眼看出該不該擋、該通知誰。

破壞性 breaking

可能讓既有串接直接壞掉,風險最高。

例如:刪掉一個端點(operation removed)、既有欄位/參數改成必填(became required)、新增必填參數、拿掉某個 response 或 security scheme、schema 結構改變。

→ 上線前先擋,主動通知所有串接方調整。

新增 additive

純粹多了東西,通常向後相容。

例如:新增端點(operation added)、新增選填參數/欄位、新增 response 或 media type、新增 schema / security scheme。

→ 可安心採用,下游要不要用新功能自己決定。

內容調整 changed

既有內容改了,但不必然破壞相容性。

例如:參數/欄位的說明文字變更(description changed)、servers 位址更動、info 版本資訊更新、components 內未被引用的 schema 移除。

→ 讀一下改了什麼,確認對自己這端沒有隱性影響。

僅來源異動 source_only

來源或中繼資料動了,但最終 API 契約沒變。

例如:來源檔本身變更(manifest source changed)、provenance 追溯調整、validation / preparation 報告內容變動,但 OpenAPI 規格本身不受影響。

→ 可放心,規格未變;若在意可回頭看來源為何動。

比較範圍:OpenAPI 路徑·方法·參數·schema·security·webhook、integration-contract、provenance、validation 摘要與 manifest(第一版不比 Markdown guide 與 examples)。輸出寫到 diff/report.{json,md};exit code 0 完成、2 代表輸入 run-dir 缺檔或格式錯誤(DiffInputError)。

套件邊界

程式碼怎麼分包

原則：除了少數 I/O 出口，其餘模組皆為純函式，便於單元測試。修改時請守住這個邊界，讓每個 loop 都能獨立驗證。

套件	職責
`manifest/`	掃描本地來源 + 建立 manifest.json；每份來源的 `authority`(normative 預設／supplementary)由同名 `.source.json` sidecar 標定,讀取端 fail closed
`rendered_url.py`	離線 rendered-source import 與只讀 provenance 驗證；寫入 immutable source/sidecar/coverage，並防止匹配的 protected origin probe
`url_safety.py`	egress 閘：`safe_client()` 在 httpx `request` event hook 裡驗證呼叫端 URL 與每一段 redirect,讓 fetcher 不可能漏檢、302 也跳不進 private address。判準是 HTTP(S) scheme、無 userinfo,且解析出的每一個位址都可全域路由(而非任一個 —— 一個名字同時解到公開與私有位址是標準繞法);`trust_env=False` 讓 proxy 環境變數也繞不過去。同一支模組也是寫入端:`RedactedUrl` 是 annotated 型別,serializer 會在落地前把 URL 裡的憑證值換成 `[REDACTED]`(`corpus.json`、`coverage.json`、provenance sidecar、CLI stdout);記憶體內仍是完整 URL,因為 fetcher 要在送出請求之前從 model 讀出它。哪些欄位名算憑證是 `privacy.py` 的 `is_credential_key` 決定,不歸這支模組管。`catalog.json` 是唯一例外,保留完整 URL —— `cache-url-pages` 要拿它回頭抓資料,URL 在那裡是指令而非證據(ADR 0015)。
`supplementary_note.py`	把供應商補充說明的人工摘錄匯入為次級佐證；寫出 immutable source 與綁定內容的 provenance sidecar
`agentcli/`	assemble.py(組裝 JSON → plan→preparation→generate→validate)、input_schema.py(交界處的 pydantic 驗證)、evidence.py(v1 exact evidence 的 read-side materialization/digest 與 claim-path 驗證)、gate.py/verify.py(`verify-extraction` 的擷取契約檢查,含 `source_facts/` 的來源事實與延後語句閘,不寫檔)、extraction.py(inventory → plan 答案)、preprocess.py(typed PDF／DOCX→markdown 編排)
`docx_*.py`	`docx_normalization.py` 是穩定 facade；package-wide fail-closed OOXML 驗證／rendering 維持 pure，`docx_publish.py` 負責分段暫存且於可回報寫入失敗時回滾的 provenance publication
`shadow/`	選用的 legacy/Core bridge 與 in-memory runner；只有 `shadow/report.py` 會寫出觀測性的 `core/` 產物集或安全錯誤報告。
`core/conformance.py` + `domain/conformance.py`	純 ContractConformance assess/propose/compose 邊界，以及不可變的 authority、observation、amendment 與 Effective Contract models。
`feedback/`	normalized-JSON 載入、綁定完整 Normative-release digest 的 assessment／proposal／composition、治理 workflow adapters、timezone-aware exact-target 查詢與 Provider Erratum handoff。Current lookup 拒絕 not-yet-effective／expired asset 與 stale base／pointer／artifact binding，並揭露 bounded validity／discrepancy counters。dry-run 輸出位於 `.foundry` 外，submit／review／approve 持久化委派給 Foundry，所有命令都不做 provider network I/O。
`extraction/`	共用 models + 工具(stages / questions / store / jsonblock)
`plan/`	規格化計畫 + 來源比對分類
`preparation/`	產生前就緒度評估 + preparation-report(report.py 寫檔)
`generate/`	生成 OpenAPI / Markdown / review.html / provenance / examples / handoff(寫檔)
`validate/`	結構 / 完整性 / 一致性 / 禁止推測檢查 + 報告
`run/`	run-id 產生、result/status models、把計畫寫入 run-dir(寫檔)
`score/`	讀取完成 run-dir,以五類權重產生 score/score.{json,md}(report.py 寫檔)
`diff/`	loader.py / compare.py / models.py / report.py(report.py 寫檔)
`freshness/`	排程用的便宜新鮮度閘:record.py 從已完成 run-dir 寫出基準 fingerprint(本地取 sha256、每個 URL 取一次版本訊號,次級佐證一律排除 —— 它不可重新取得,納入只會永遠回報新鮮;零可重取得來源則直接拒絕寫出,無 `--force` 亦拒絕覆寫)、signals.py 重算當下訊號並分類(網路讀取但不寫檔)、check.py 彙總單一 docset、batch.py 依 watchlist 扇出多個 docset(單項錯誤收進該項結果不中斷整批)、report.py 輸出報告。退出碼即契約:0 未變動、1 已變動、2 無法判定
`source_risk/`	以 manifest 綁定、在 agent 讀取前執行的文字風險掃描與 audit 驗證,涵蓋兩個方向:來源會不會操縱 agent,以及會不會洩漏東西給 agent。洩漏類只有自證性材料(PEM 私鑰區塊、JWT)會擋,憑證引用只給 warning —— 合格文件本來就會示範 Authorization 標頭。讀取精確來源 bytes，寫出 `source-risk-report.{json,zh-TW.md}`，不改寫或回顯來源 payload
`source_quality/`	擷取前來源品質評估與來源版本差異報告；要求並嵌入已驗證的 source-risk audit；reject 可輸出明確 bounded `required_source_refs` 且不 crawl(寫檔)
`focus/`	提出者的擷取重點指令:models.py(嚴格契約;kind 決定 severity、intent 決定錨點型別,只有 satisfied／not_found 兩種結局)、loader.py(讀 focus.json 與 focus-response.json,本套件唯一讀檔出口)、gate.py／fields.py／codes.py(純檢查:應答對應、錨點解析、not_found 必須交代每一份可讀來源)、report.py(寫出 `<run-dir>/focus/`,唯一寫檔出口)。落空的斷言走 ValidationReport 的 `FOCUS_UNMET`,不走輸入閘 —— 那樣產物才留得下來給人判斷。`collect_error_codes` 答得比來源表格算出的記載錯誤碼下界少,同樣走 ValidationReport,成為具名列出漏碼與其出處的 `FOCUS_INCOMPLETE`
`source_facts/`	來源事實盤點:markdown.py 機械掃描 Markdown 來源的端點宣告、參數表與範例區塊,collect.py 讀取 manifest 指名的來源(本套件唯一讀檔出口),gate.py 比對擷取 JSON(並沿 `schema_ref` 遞迴解析進 `inventory.schemas`,讓共用型別算去重複而非遺漏)、deferral.py 攔截佔位式延後答案
`gitbook_llms.py` / `markdown_drafts/` / `extraction_scaffold/`	GitBook 工程化取源只抓一次 `llms.txt`，安全快取範圍內 Markdown 與 provenance/coverage；再從 manifest 指名 Markdown 產生具行號的非權威端點／表格／範例草稿，並可投影為 extraction-shaped scaffold。scaffold 必須複製、覆核、補齊至 workdir；不能取代 `source_facts/`、最終擷取或直接作為 `--extraction`。
`url_catalog.py` / `url_corpus.py`	受限 URL 導航索引、頁面快取與關聯候選,讓 agent 以本機證據讀取網頁文件(寫檔)
`foundry/`	專案本地資產治理：normative assets 保持 immutable，新 asset 記錄 supersession 後 pointer 才前進。Feedback inputs 是 write-once candidate stage；綁定的 decision／amendment records 為 append-only，核准會建立另一份 immutable Effective release。全域 `current` 維持 normative；Effective selection 綁定 exact scope／time、驗證 digest，在 approval／composition 前、expiry 後或 normative-base supersession 後拒絕。
`review/`	本機單使用者工作台：自動匯入 candidate、比對 current／baseline、保存結構化 handoff，人工明確核准後才透過 Foundry 更新 current(寫檔)

別讀錯欄位。UrlSource.fetch_url 是拿來發送請求的;它的 redacted 版本 citation_id 才是拿來命名、比對、寫進產物的。讀錯欄位,輕則把憑證寫進 plan.json,重則讓比對／join 悄悄失效 —— 因為從磁碟讀回來的 URL 是已 redact 過的,記憶體裡同一個欄位卻不是。tests/test_citation_identity_contract.py 會擋下 ALLOWED 名單外任何讀取 fetch_url 的地方。

標記列含檔案 I/O 出口:generate/、run/、agentcli/preprocess.py、shadow/report.py、feedback/report.py、preparation/report.py、score/report.py、diff/report.py、source_risk/report.py、source_quality/、freshness/、docx_publish.py、rendered URL import、supplementary_note.py、URL corpus 快取、foundry/ 與經 Foundry 寫入的 review/workflow.py 會寫檔。feedback/loader.py、docx_normalization.py、source_risk/inspect.py 與 adapters/fragments.py 是 read-side I/O exit；Core 與 Domain 維持 pure。

收尾

名詞速查 · 接下來讀什麼

名詞速查

seam: 前後兩段的唯一交界(inventory.json + endpoints/*.json),也是測試的切點。
manifest: 來源盤點檔,記錄掃到哪些來源與 URL。
normalization-plan: 把擷取結果規格化後的計畫,generate 與 validate 的共同輸入。
provenance: 來源追溯;target 與 OpenAPI 位置逐一對齊。
preparation: 生成前就緒度評估,在品質 loop 裡先標出阻塞與注意事項。
score: 完成 run-dir 的品質分數,用於 CI 或 review profile 的後段判讀。
handoff: 從 OpenAPI 與 integration-contract 衍生的工程交接包,不是新的契約來源。
Normative / Effective Contract: 前者是已核准的供應商來源 release（contract + documentary fragments + support relationships），後者則是它與適用 amendments 的 deterministic exact-scope composition；兩者是不同的 digest-bound artifact 與 authority view。
Applicability Envelope: 用來解讀一個 observation 或 amendment 的完整 provider、deployment、environment、identity、configuration、client、test-data 與 time boundary。
fail-closed: 遇到無法確認 / 衝突時,選擇「不輸出」而非「猜一個」。
run-dir: 單次執行的輸出目錄,裝著該次全部產物。

接下來讀什麼

跑一次看看 — 依 README.md 安裝(uv sync)，先讀 docs/BENCHMARK_VALIDATION_PLAN.md 分清 CI-safe 與 source-backed，再用 benchmarks/ 的樣本走一遍。
架構細節 — docs/ARCHITECTURE.md:seam、套件圖、資料流表。
擷取行為 — skills/loop-apidoc/SKILL.md:agent 實際怎麼讀來源、怎麼分段。
設計依據 — docs/DESIGN_DECISIONS.md 的長期產品決策。