認識 LOOP-APIDOC

把雜亂的技術文件，
變成人人看得懂、可信賴的說明書

各家廠商的串接文件格式雜亂，又常有缺漏。loop-apidoc 像一座初步精煉爐，把混雜素材萃取成乾淨、查得到出處的標準說明，而且絕不自己亂編。

架構更新穩定的產品核心已是 evidence-to-contract core；模型與 agent workflow 都是可替換的 Runtime Adapter，由確定性的 Core 與 Domain 負責 grounding、assurance 與 release 治理。下方流程仍是現行 CLI adapter。

原料:PDF · 網頁 · 程式檔 · 網址 初步精煉:萃取 · 對照 · 不臆測 結晶:統一 · 可追溯 · 已檢查
先解釋一個詞:API 是什麼?
簡單說,API 就是兩套軟體互相溝通的「接口」;而 API 文件,就是教你怎麼跟對方系統「對接」的操作手冊。例如要串接金流、物流、簡訊服務時,對方都會給你一份這樣的文件。
專案入口

先到 GitHub 首頁，或直接把 plugin 裝起來

如果你想看原始碼、追版本或提 issue，先去 GitHub repo；如果你要直接跑擷取流程，照下面的安裝方式把 plugin / CLI 接好就能開始。

專案 GitHub 首頁 原始碼、commit、issue 與 workflow 都在這裡，GitHub Pages 也從這個 repo 發佈。 前往 GitHub repo →

Claude Code plugin 安裝

在 Claude Code 裡把本專案加成 plugin，agent 就能直接讀來源、組裝、驗證。CLI 由 plugin 內含，不必另外裝。

/plugin marketplace add CarlLee1983/loop-apidoc /plugin install loop-apidoc@loop-apidoc-marketplace

更新到最新版：/plugin marketplace update → /plugin update

Codex CLI 安裝

Codex 不會帶 ${CLAUDE_PLUGIN_ROOT}，所以把 CLI 裝成全域指令，再把 skill 掛到 Codex 的 skills 目錄。

uv tool install --from /path/to/loop-apidoc loop-apidoc ln -s /path/to/loop-apidoc/skills/loop-apidoc ~/.codex/skills/loop-apidoc
為什麼需要它

沒有它,日子有多難?

當一個團隊要同時串接很多家外部服務時,光是「讀懂文件」就是一場硬仗,還藏著看不見的風險。

十家廠商,十種格式

有的給你一份 PDF、有的丟一個網頁、有的是一堆程式碼檔。光是把它們「讀懂」就耗掉大把時間與耐心。

文件常常缺東缺西

漏了關鍵欄位、沒寫清楚失敗時會怎樣。最危險的是 —— 有人為了趕進度,乾脆「用猜的」把空白補上去。

猜錯就出包

一個猜錯的小細節,上線後可能變成付款失敗、訂單遺失這種真實事故,事後才發現「原來文件根本沒這樣寫」。

工程師被格式雜亂、缺漏的串接文件淹沒
AI 協作時代

為什麼 vibe coding 更需要它?

把實作交給 coding agent 之後,程式寫得再快,規格餵錯就全錯。agent 的產出品質,取決於你給它的規格品質。

原始文件是幻覺的溫床

直接把 PDF 丟給 agent,遇到缺漏它會用「常見慣例」腦補:自動假設 OAuth、標準錯誤格式。串接金流時,這種貌似合理的猜測就是最貴的 bug。

agent 需要機器可讀的事實

整理後的 OpenAPI 與整合契約是 agent 可直接消費的規格——比每個 session 重讀幾十頁 PDF 更省、更穩,而且每個 agent、每個專案讀到同一份事實。

人負責驗收,不是放手不管

vibe coding 把人的角色從「逐行寫碼」移到「驗收規格與產物」。每句話都查得到出處、離線核對頁隨附,你才敢在 agent 的產出上簽名。

直接請 AI 整理

快,但只能「信」它

  • 零建置,一句話就有結果
  • 結果對不對,只有模型自己說了算
  • 缺漏會被「常見慣例」悄悄補上
  • 每次問結果都不同,無法比對出處
  • 適合:快速看懂、一次性低風險探索
經過 loop-apidoc

用模型,但不信任模型

  • 模型只負責讀,對不對由確定性程式碼把關
  • 瞎掰會被驗證閘攔下,缺漏被明白點名
  • 漏抄也被攔下:來源寫了參數表、擷取卻空著,擋下重讀
  • 每句話都查得到出處,可離線人工核對
  • 同樣的輸入永遠產出同樣的成品,改版可比對
  • 適合:要上線的串接、金流等高風險場景

代價說在前頭:它要走完整的擷取→驗證→修正流程,比「直接問」花更多前置成本。判斷準則很簡單——整理結果會被寫進正式程式碼,就值得過閘;只是要看懂,直接問就好。

一句話:vibe coding 把「寫程式」變快了,「規格正確」就成了新的瓶頸——這個工具補的正是這個瓶頸。

最重要的一件事

它只寫「文件真正講到的」,
絕不自己編。

文件沒寫的,它一律留白、並老實標記為「缺漏」,永遠不會用慣例或猜測來填。寧可明白告訴你「這裡缺了」,也不給你一份看起來完整、其實是編出來的文件。

你可以信任它的每一句話
它怎麼運作

它是怎麼做到的?

五個清楚的階段，把雜亂來源收斂成可追溯、可驗證、能直接交付的成果。

loop-apidoc 從異質來源、讀取前風險閘、agent claim 提案到確定性驗證與可審查產物的循環流程動畫
1
取得來源

收集並檢查來源

把 PDF、DOCX、網頁、OpenAPI 或公開網址交給它。所有來源會先轉成可安全掃描的文字，再完成風險與完整性檢查；不合格的來源不會交給 agent 閱讀。

查看來源安全與授權細節
  • 文件轉換：preprocess 會將 PDF／DOCX 轉成可掃描文字；DOCX 先通過 bounded、fail-closed OOXML 驗證，並附上 source-hash provenance。DOCX 與 GitBook 兩條路徑未經真實來源驗證——十三個 benchmark case 都不是 Word 或 GitBook 來源，證據強度等同 benchmark 的 skipped，請當成可用但未證實。
  • 來源風險：inspect-source-risk 會在任何 agent 讀取前檢查 manifest 綁定的精確 bytes；它不改寫來源，也不回顯命中的 payload。
  • 受保護頁面：直接 HTTP 被擋、但瀏覽器可顯示時，import-rendered-url 會保存原始位元組與 capture provenance；只有 URL、path、method 與 SHA-256 全數吻合，才會略過 origin fetch。
  • Egress 閘門：任何對外抓取都先通過同一道閘門——只放行 HTTP(S)、URL 不得帶 userinfo，且解析出的每個位址都必須公開可路由；轉址進私有或雲端 metadata 位址一樣拒絕，並忽略 proxy 環境變數。
  • 憑證遮蔽：來源 URL 若帶簽章憑證，會用於下載但在 corpus.json、coverage.json、provenance sidecar 與產出文件中記為 ?X-Amz-Signature=[REDACTED]，其餘部分逐位元組保留，遮蔽後身分仍可比對。
  • GitBook 與草稿：若提供 llms.txt，系統會快取同範圍 Markdown，再產生具行號、待人工覆核的 extraction scaffold；它必須複製、核對並補齊後，才能作為正式 extraction。
  • 第三方授權：DOCX ZIP/XML fallback 改編自 MIT 授權的 book-to-skill（固定 revision efda3b2212ce1b2c052126e85e14de40a32442e8）。本專案另加嚴格 gate，且不宣稱支援 EPUB／RTF／MOBI；詳見第三方公告。
2
擷取事實

逐段仔細閱讀

按來源範圍逐段擷取，像認真的讀者抄重點；只記錄文件明確寫出的內容，不用慣例補空白。

3
統一結構

整理成標準格式

把分散在不同頁面與格式中的資訊，整理成一套人能審、工具也能直接讀取的契約。

4
品質閘門

自我檢查

確定性規則會核對完整性、一致性與來源依據。有缺漏就回頭重讀；真的查不到，就明確標示「缺漏／衝突」。

5
交付使用

交付成果

一次產出標準規格、繁體中文說明書、來源追溯與品質報告，讓工程實作和人工複核都能直接開始。

你會拿到什麼

最後你會拿到這些成果

從標準規格、中文說明書、來源追溯到品質報告,再加上一包能直接動工的開發者交付物,每一份都有明確用途,工程師到主管各取所需。

標準規格藍圖

openapi.yaml

業界通用的標準格式,各種工具與工程師都能直接拿去使用,不必再各自解讀。

整合契約

integration-contract.json

固定產生的機讀契約除了簽章、callback 等整合機制，也保存來源明載的 transport、金額方向、冪等、線路幣別與跨端點規則，讓下游 SDK 工具不必重讀 Markdown；request 缺少 currency 欄位不會被推論成單幣別。

看得懂的中文說明書

api-guide.zh-TW.md

用繁體中文整理好的串接指南,不必再硬啃原文文件。

來源追溯

provenance.json

每一項內容都標明出自哪份文件、哪一段,經得起「這資訊哪來的?」的追問。

品質檢查報告

validation/report

清楚列出哪裡完整、哪裡還缺,文件品質一目了然,不用憑感覺。

一頁核對清單

review.html

用瀏覽器就能離線打開的單頁,把範圍、來源、缺漏和 API 結構攤在一起,方便人眼快速複核。

開發者交付包

examples/ · handoff/

附上三種語言的請求範例,以及可直接動工的交付包:整合任務清單、Postman 匯入檔、SDK 提示,工程師拿了就能開工。

為什麼可以信任

每一句話,都查得到出處

就像論文會標注引用來源,loop-apidoc 產出的每個欄位、每條規則,都能追回是哪份來源文件、哪個段落寫的。

產出的說明書 ① 原始來源文件 ①

有人質疑「這個設定是哪來的?」時,你能立刻翻出對應的來源段落。

版本比對 · 新功能

換版本了?一眼看出差在哪

廠商更新了文件,新版到底改了什麼?loop-apidoc 能比較新舊兩版,把每一處變化標上四種「燈號」,讓你一眼判斷風險高低。

破壞性變更 breaking

可能讓你既有的串接「壞掉」,要特別小心、優先處理。

新增 additive

多了新功能或新欄位,通常是安全的,不影響現有串接。

內容調整 changed

既有內容有改動,不一定危險,但值得花一分鐘看一下。

僅來源異動 source_only

只是來源文件本身動了,最終規格其實沒變,可放心。

新舊兩版文件比對,變動處以紅綠琥珀灰四色燈號標記
品質評分 · 新功能

不只「過或不過」,還給一個分數

檢查報告告訴你「哪裡缺、能不能過」;評分再進一步,把文件品質換算成 0–100 分,方便長期追蹤、跨版本比較。分數只是儀表板,從不改變一份文件的通過與否。

看五個面向打分

規格正確性、完整度、一致性、來源依據、可複核性,五個維度加權後得出總分；報告另列 response 欄位總數與空殼 operation，避免「有 response 但沒有契約」被外觀掩蓋。

兩種評分角度

「上線把關」偏嚴格、適合自動化流程;「人工複核」較寬鬆、適合送審前自評。同一份文件,兩種視角。

看得見的進步

每次修正都能看到分數往上走,團隊有明確的努力目標,不再靠感覺說「應該還不錯」。

把文件品質量化成 0 到 100 分的品質儀表板
資產治理 · 新功能

好文件別散落,收進自己的資料庫

跑出一份滿意的成果後,可以先在本機 review 工作台比對候選版與現行版、留下可交棒的結論，再經核准收進專案自己的文件資產庫並標上版本；之後大家永遠取用同一份「現行版」,不再有人拿到過期的舊檔。

1

收進候選

把一份跑完的成果匯入資產庫,先放在「候選」區,還沒正式生效。

2

核准並標版

人在工作台確認後才核准；系統把它複製成一份自足、標上版本號的正式資產，在新 asset 的 supersedes lineage 記錄前一版，再前進 current；舊 asset bytes 永不改寫。尚有風險可核准，但會標示為待後續追蹤。

3

永遠取用現行 normative 版

下游可查詢目前供應商文件明載的契約；這個全域 pointer 保持 normative，deployment-specific Effective Contract 則依精確 scope 另外選取。

核准、版本化的文件資產櫃,書籤指向現行版
實作回饋 · 權威分離

供應商寫了什麼，和某個 deployment 觀察到什麼，不是同一種 claim

選填的 --focus 讓你在跑之前對擷取下重點指令:金流的結算回呼、遊戲平台的錢包轉帳端點、供應商的錯誤碼。斷言型指令主張來源確實記載了它,落空就讓驗證失敗;範圍型只要求掃乾淨,查無記載也算完整回答。指令逐字進入每個擷取 subagent 的 prompt,而 agent 的每一條回答都要嘛指得出來源的哪一行、要嘛列出查過的每一份可讀來源——沒有第三條路,指令也從不授權捏造。焦點材料只留在 run 目錄,不進 provenance 與 score,所以同一份來源、不同重點的兩次 run 仍然可比。

供應商來源仍是 Normative Contract 的唯一權威。被動、正規化的觀察可以在精確 Applicability Envelope 內確認或挑戰 material claim；以下流程讓回饋可用，卻不混淆兩種 authority。

前後對照

一張圖看懂前後差別

同樣一批來源文件,有沒有經過 loop-apidoc,差別非常明顯。

使用前

一疊看不懂的文件

  • 格式各家不同,讀起來費力
  • 缺頁、漏欄位,不知道完不完整
  • 不確定的地方只能用猜的
  • 出處難查,很難對帳追責
使用後

一份乾淨的說明書

  • 統一標準格式,人與工具都好讀
  • 缺漏明白標出,品質有報告佐證
  • 只寫文件真有的,絕不臆測
  • 每句話都查得到來源出處
安全導入 CORE

在不改變既有權威的前提下比較 Core

assemble --architecture-mode shadow 會在 legacy validation 後執行觀測性 Core 旁路，將 evidence、claims、canonical contract、policy decision、workflow/events 與 comparison 寫入 <run-dir>/core/。Legacy 結果、score、approval、Foundry 與退出碼仍具權威；預設模式不建立 core/。

assemble --architecture-mode strict 是阻斷式 candidate 路徑：通過的 legacy run 必須把每個 supported material claim 重新證明到 exact evidence，才會寫出未核准的 Core release。evidence 缺口會讓 run 失敗，Foundry 會在任何人工核准前重驗 strict execution record；strict 本身不會發布或改動 Foundry。

Claim-level ledger 會把每個 material claim path 以 explicit_support、derived_support、contradicts 或 insufficient 連到 exact typed fragment 與 source artifact。選填 v1 evidence[] 會在建立 run 前重新 materialize，並驗證 source identity、locator、digest 與 claim path。沒有 parsed scalar 的 prose 只能支援它精確綁定的單一 claim；versioned OpenAPI structural derivation 限 allowlist，且會連同所有必要的 local-reference context fragments 由 Core 重新計算。Runtime confidence 不決定 support，整份文件級的 legacy citation 維持 unverified。精確追蹤請看 relationships.json 與 projections/provenance.json。

Core 保留經測試的 GraphQL／AsyncAPI 純 compiler seam，但在具名下游 consumer 提供真實來源集與驗收契約前，不公開 CLI 或 run workflow。格式 fixture 只能證明 compiler 可測，不能代替產品需求或端到端 grounding。

一句話總結

該有的整理好,沒有的老實說,絕不瞎掰。

loop-apidoc 把「雜亂、不可靠的技術文件」,變成「乾淨、可信賴、查得到出處的說明書」。

團隊安心自信地使用一份乾淨、可追溯的說明書
適合誰?　需要串接多家外部服務(金流、物流、簡訊…),又重視文件正確與可追溯的團隊。
想深入技術細節?看給工程師的完整導覽

兩段式架構、seam JSON、完整的 CLI 命令表，以及風險、驗證與修正閘，一頁看懂整條 pipeline。