OpenContracts：把文件庫變成可查詢的引用圖，以及它的代價
The open document intelligence platform for builders and hackers - DMS for the agentic world
秒懂
- 它是什麼？
- OpenContracts 是 MIT 授權的開源文件情報平台，把整批文件解析成引用圖，並同時用 GraphQL／REST API、MCP server 與 React UI 三種介面暴露同一份圖。本文說明它的機制、啟動方式、適用邊界，以及導入前該先驗證什麼。
- 適合誰用？
- OpenContracts 適合手上已有一批互相引用的文件、且願意自架 Django 與 Celery 的團隊；若你只需要對少量文件做問答，或不想維運背景 worker，它會比直接串接 LLM API 更重。不適合把它當成純檔案庫：它的價值在引用圖與標註，而不是存放檔案。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫在最近一天內有新的提交。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的是引用關係，不是檔案儲存
多數團隊的文件管理停在「找得到檔案」。但法律、法遵、財報這類文件真正的問題是：這份文件引用了哪一條法規、哪一條法規又被誰引用、哪些引用目前手上根本沒有原件。OpenContracts 的定位就在這一層。README 的說法是「Point OpenContracts at a repository of documents and get a programmable citation graph」，重點在 programmable 與 citation graph 兩個詞。
目標使用者寫得相當明確：builders and hackers，以及 working at scale 的團隊。它提供的是平台而不是成品，README 直接寫「OpenContracts is a platform, not a black box」，並強調 UI 做的每一件事，你都能自己用 API 呼叫。這意味著它預設你會寫程式，會自己接管線，而不是期待一個裝好就能用的 SaaS。
反過來說，如果你的需求只是把 PDF 存起來、偶爾全文搜尋，這個專案的核心機制對你沒有作用。它的複雜度來自引用解析與圖譜，不是來自檔案儲存。
一鍵背後的資料流：corpus、agent、citation edge
README 描述的流程是：建立一個 corpus，把文件丟進去，按下 Set up。這一下會安裝所謂的 intelligence bundle，由 agents 逐份文件產生描述與摘要，同時開始編織引用網路，偵測到的每一筆法規引用都會被解析，並畫成一條邊。
值得注意的是未收錄的法規不會被丟掉。README 說「Law the library doesn't hold yet isn't dropped on the floor: it's tracked as a backlog, automatically, until you ingest it」，在截圖裡以虛線節點呈現。這個設計決定了整個系統的可用性：引用圖允許有不完整的一端，缺口本身是一筆待辦資料，而不是解析失敗。對照組是那些遇到未知引用就靜默丟棄的抽取工具，兩者在後續補資料時的成本差距很大。
抽取本身走的是 fieldset 機制。README 的定義是「a set of columns, each a natural-language query」，定義好之後對整個 corpus 執行，工作透過 Celery workers 展開，結果落在試算表式的 grid，每一格都有人工 approve 或 reject 的動作。這裡的關鍵是 fan-out 與人工覆核同時存在，不是全自動，也不是全人工。
解析、embedding、縮圖則是可替換元件。README 說註冊自訂的 parser、embedder 或 thumbnailer 之後，下游的搜尋、標註、agents 都會照常運作。這是整個架構裡最實際的一個承諾：格式支援的缺口可以用外掛補，不必等上游合併。
三個介面共用同一份圖：API、MCP、React UI
README 反覆強調「Same graph, three surfaces」。同一份引用圖同時透過 GraphQL 加 REST API、Model Context Protocol server，以及 React UI 暴露出來。這對 agent 工作流是一個具體的差異：你不必為 agent 另外維護一份向量索引或摘要快取，agent 查的就是 UI 上看到的那份圖。
MCP 的部分文件寫得很細。端點有兩個，`/mcp/` 對匿名使用者開放公開 corpus，`/mcp/me/` 需要認證。探索路徑是 `/llms.txt` 與 `/.well-known/mcp.json`。工具清單包含 `search_corpus`、`list_documents`、`get_document_text`、`list_annotations`、`list_relationships`、`list_threads`、`create_thread_message`。值得注意的是工具集合裡有寫入性質的 `create_thread_message`，README 也提到 MCP client 在取得授權後可以自行提出標註。把寫入權限交給外部 agent 是這個設計裡風險最高的一段，實務上應該先從 `/mcp/` 的唯讀公開 corpus 開始，確認 agent 的行為符合預期，再開放認證端點。
Python 端的 agent 介面只有幾行。README 的範例是 `agent = await agents.for_document(123, corpus=45)`，接著用 `async for chunk in agent.stream("Summarize the indemnification clauses")` 串流輸出，或改用 Pydantic 模型取回具型別的物件。文件位置在 `docs/architecture/llms/README.md`。這裡的設計取向是 async 與串流優先，不是同步回傳整包結果。
啟動路徑與你真正要維運的東西
README 沒有給出完整的安裝指令，只指向幾個文件位置：MCP 相關在 `docs/mcp/`，管線在 `docs/pipelines/pipeline_overview.md`，自訂抽取器在 `docs/walkthrough/advanced/write-your-own-extractors.md`，LLM 框架在 `docs/architecture/llms/README.md`。任何要評估的人都應該先讀這四份，因為安裝步驟的細節不在 README 裡，這點必須說清楚，不能假裝有。
可以確認的是技術組成。primary language 是 Python，抽取工作跑在 Celery workers 上，前端是 React，資料介面是 GraphQL 加 REST。這代表自架的維運範圍至少包含 Python 應用、Celery 背景 worker、以及前端建置產物。Celery 的存在不是裝飾：fieldset 對整個 corpus 展開時，工作量的成長是文件數乘上欄位數，這條佇列會是你最先感受到壓力的地方。
設定面的線索包括 MCP 的兩個端點路徑、`/llms.txt` 與 `/.well-known/mcp.json` 這兩個探索檔，以及 fieldset 的欄位定義。這些是評估時可以直接對照文件檢查的具體項目。至於環境變數、資料庫連線、embedder 的選擇方式，README 沒有交代，需要從上述文件與 repository 結構自行確認。
不適用的時候：它不是搜尋引擎，也不是輕量問答層
第一個限制來自引用解析本身。這套機制的前提是文件之間存在可辨識的引用關係。SEC filings 引用 Delaware General Corporation Law 這種情境很合適，因為引用有明確的形式與可解析的目標。但行銷素材、內部會議紀錄、產品規格書這類文件，彼此之間沒有結構化引用，建出來的圖會是稀疏的，你付了 corpus 與 worker 的成本，換到的圖卻沒什麼可走。
第二個限制是人工覆核的位置。fieldset 抽取的每一格都有 approve 或 reject，這是刻意的設計，也意味著抽取量放大之後，人工佇列會跟著放大。README 說「hundreds of documents at a time」，但沒有說明覆核的吞吐量如何隨之調整。如果你的場景無法接受人工瓶頸，這個機制會變成阻礙而不是保障。
第三個限制是格式覆蓋。parser、embedder、thumbnailer 都可替換，聽起來彈性很大，但反過來說，預設支援之外的格式就落在你身上。README 用「Register a custom parser」描述這件事，卻沒有列出預設涵蓋哪些格式。這是一個必須在導入前實測的項目，不能假設。
最後是寫入權限。MCP 工具組包含 `create_thread_message`，且 agent 可提出標註。對外部 agent 開放寫入，等於把資料完整性的一部分交給模型行為決定。這不是缺陷，而是需要明確決策的邊界。
和一般 RAG 堆疊的差別在哪
最直接的替代方案是自己用向量資料庫加 LLM API 搭一套檢索問答。兩者的差別不在檢索品質，而在資料模型。向量檢索把文件切塊、算相似度、回傳最接近的段落，段落之間的引用關係不在模型裡。OpenContracts 走的是另一條路：先把引用解析成邊，再讓問答沿著這張圖走。README 描述 ask bar 是「a corpus-scoped agent whose answers come back grounded and cited」，grounded 的來源是標註與引用，不是相似度分數。
這個差別在補資料的時候最明顯。向量方案遇到沒收錄的法規，只會檢索不到；OpenContracts 把它記成 dashed node 的待辦，等你 ingest。前者是無聲的缺口，後者是有紀錄的缺口。
代價也很清楚。向量方案不需要 Celery、不需要 corpus 概念、不需要人工 approve 流程，部署面積小得多。OpenContracts 換來的是可追溯的引用圖，但你要接受它是一套有狀態的平台，而不是一層可以隨時抽換的檢索 API。兩者不是同一個量級的東西，選錯會很痛。
授權、升級與維護成本
授權是 MIT，這是相對寬鬆的選擇，允許修改與商用。但要提醒的是，MIT 涵蓋的是這個專案的程式碼，不涵蓋你送進去處理的文件，也不涵蓋你選擇的 LLM 或 embedding 服務。把機密文件送進第三方模型推論端點之前，該確認的是那條路徑的合約與資料處理條款，這與 OpenContracts 的授權無關。這不是法律意見，只是提醒這兩件事不要混在一起看。
升級成本要看版本節奏。release notes 顯示 v3.0.0 的主題是 Corpus Intelligence、Authority Linking 與 Deep Research，接著 v3.1.0 在約一個月後發布。主版本號從 v2 跨到 v3，且 v3.0.0 之前有 v3.0.0.b4 這類 beta 版本，代表 v3 系列經過一段預覽期才定版。從 v3.0.0 升到 v3.1.0 屬於同系列更新，風險相對低；跨主版本則需要先讀 release notes 確認 corpus、authority linking 這些核心概念的資料結構有沒有變動，因為那會直接影響你既有的標註與抽取結果。
維護面的固定成本是 Celery worker 與前端建置。這部分不會因為你用得少而消失，只要 corpus 還在、agent 還要跑，這些元件就得活著。評估時應該把它算進人力，而不是只算伺服器費用。
編輯結論
OpenContracts 適合手上已有一批互相引用的文件、且願意自架 Django 與 Celery 的團隊；若你只需要對少量文件做問答，或不想維運背景 worker，它會比直接串接 LLM API 更重。不適合把它當成純檔案庫：它的價值在引用圖與標註，而不是存放檔案。導入前先確認三件事：你的文件格式是否有對應的 parser 與 thumbnailer 實作、你的授權情境是否允許把文件送進自行選擇的 embedder、以及 v3.0.0 到 v3.1.0 之間是否有破壞性變更。先在本機跑一次 README 的 agents.for_document 範例，確認 citation graph 在你的文件上真的連得起來，再決定要不要上線。
社群筆記