UrbanReg AI

UrbanReg AI 是一個面向台灣都市更新與建築相關文件的「法規與合規審查系統」。

這個 repo 目前採 public showcase repo 方式公開。原始碼可閱讀與評估，但商業化與正式生產使用受到 Business Source License 1.1 保護，詳見 COMMERCIAL.md。

它的目標不是取代專業判斷，而是幫團隊更快整理文件、找出風險、保留審查依據，讓法規與契約審查更可追溯、更有效率。

它做的事情很直接：

1. 收到文件與案件資訊
2. 拆出條款與可審查單位
3. 找出可能的法規風險與不一致處
4. 產生可追溯的審查結果、建議與報告

適合誰使用

• 都市更新、建設開發與建築相關團隊
• 法務、合規、專案管理與文件審查人員
• 需要在私有環境中處理法規與契約文件的組織

Repo 定位與授權

• 這個 repo 的目的，是讓客戶、合作方與技術讀者能理解 UrbanReg AI 的問題定義、系統設計與實作用法
• 它不是一個無限制商用的 open source product repo
• 授權採用 Business Source License 1.1
• 若要正式部署、為客戶交付、代管服務或做商業化整合，請先閱讀 COMMERCIAL.md
• 案例介紹可參考：UrbanReg AI 案例頁
• 若你想先從較小範圍的合作開始，可參考：UrbanReg AI 工作流程診斷與 pilot 規劃

核心價值

• 加快審查速度：先把文件拆成可處理的條款與議題，減少從零閱讀與比對的時間
• 提早看見風險：把可能的法規問題、契約疑點與需人工確認的項目先整理出來
• 保留審查依據：每個結論都可以回溯到條款、法規依據、模型與提示詞版本
• 適合私有部署：系統定位為內部私有雲或本地環境，不依賴公開 SaaS

30 秒看懂：輸入與輸出

• 輸入：
  • 文件（pdf、png、jpg、jpeg、tif、tiff）
  • 基本案件資訊（案件名稱、法域、專案類型）
• 輸出：
  • 議題清單（每個議題都有原因、法規依據、建議改寫）
  • 報告檔（json、markdown、pdf）
  • 稽核軌跡（知道誰在什麼時候做了什麼）

目前可用範圍

• 法規範圍：目前聚焦 TW-TPE urban renewal
• 使用入口：
  • Dify workflow — 透過現成表單與流程操作，適合一般審查人員
  • Core API（推薦給開發與整合）— 直接呼叫 REST API，適合自動化腳本、系統串接或未來前端整合
• 目前沒有獨立前端介面，UrbanReg 定位為 headless 審查引擎，Dify 可作為現成的操作介面
• LLM 路線：
  • deterministic（可重現、無外部金鑰）
  • openai
  • gemini

一個實際使用情境

假設團隊正在處理一個都市更新案件，需要審查一批契約、附表、會議紀錄與相關法規文件。UrbanReg AI 可以先把文件內容拆成條款，找出可能的法規風險、需要補件或需人工確認的地方，並生成具備法規依據與建議改寫的議題清單。

這樣的價值不是「AI 幫你直接下法律結論」，而是：

• 更快整理大量文件
• 更早看到高風險條款
• 讓人工審查聚焦在真正需要判斷的地方
• 保留完整審查過程與依據

審查流程

flowchart LR
    A["使用者填入案件與檔名"] --> B["建立案件 / 登錄文件"]
    B --> C["啟動審查"]
    C --> D["Parser 讀檔（必要時 OCR）"]
    D --> E["切條款 + 找法規 + 跑規則 + LLM 判讀"]
    E --> F["產生議題清單"]
    F --> G{"審查狀態"}
    G -->|"completed"| H["可直接產生報告"]
    G -->|"review_required"| I["先人工確認，再重跑或核准"]
    G -->|"failed"| J["看錯誤指引後修正資料再重試"]

Loading

Dify 參考流程

目前給一般使用者的主要流程是：

• UrbanReg 預設審查流程
• 公開 repo 僅保留 Dify plugin 與必要的整合說明，不公開實際使用中的 workflow payload 與環境預設值設定。

flowchart LR
    S["開始"] --> C1["建立案件"]
    C1 --> C2["登錄文件"]
    C2 --> C3["建立審查模式"]
    C3 --> C4["啟動審查"]
    C4 --> C5["列出議題"]
    C5 --> C6["摘要結果"]
    C6 --> E["結束：回傳 review_status / issue_count / result_summary"]

Loading

系統架構

flowchart TD
    U["使用者"] --> W["Dify Workflow"]
    W --> P["UrbanReg Dify Plugin"]
    P --> A["API Gateway"]
    A --> CS["Case Service（主流程）"]
    CS --> PS["Parser Service（PDF/OCR 解析）"]
    CS --> RS["Retrieval + Rule + LLM Review"]
    CS --> REP["Report Service"]
    A --> AUD["Audit Service"]
    CS --> DB["PostgreSQL"]
    CS --> REDIS["Redis + Worker"]
    REP --> FS["本地報告儲存"]

Loading

設計原則

1. 以條款為核心，不是以頁碼為核心
   條款才是法律意義單位，頁碼只是定位輔助。

2. 先規則、再模型
   先用明確規則找基本問題，再用 LLM 做語意判讀與改寫建議。

3. 每個結論都要可回溯
   議題會保存法條、頁碼、提示詞版本、模型版本，不只給一句「看起來有問題」。

4. 人工核准是正式邊界
   遇到高風險或低信心，狀態會轉為 review_required，不會默默當成完成。

5. 可切換模型供應商
   同一個流程可以選 deterministic、openai、gemini。

快速上手（開發 / PoC）

1. 安裝依賴並設定文件根目錄

make install
export URBANREG_DOCUMENT_STORAGE_ROOT=$PWD

2. 建立開發資料

make seed-dev

3. 啟動本地服務

docker compose up --build

4. 跑一次完整測試

uv run pytest -q

5. 若你要走 Dify 流程，請依序看：

• docs/runbooks/dify-local-stack.md
• docs/runbooks/dify-plugin-install.md
• docs/runbooks/dify-compatibility.md

API 功能對照表

• 建立案件：POST /v1/cases
• 建立文件：POST /v1/documents
• 啟動審查：POST /v1/reviews
• 查審查狀態：GET /v1/reviews/{review_id}
• 查議題清單：GET /v1/reviews/{review_id}/issues
• 查議題詳情：GET /v1/issues/{issue_id}
• 改寫條文：POST /v1/clauses/{clause_id}/rewrite
• 產生報告：POST /v1/reports
• 下載報告：GET /v1/reports/{report_id}/download

專案目錄

apps/
  api-gateway/          對外 API 入口
  dify-plugin/          Dify Tool Plugin
  law-source-plugin/    Dify Data Source Plugin
  dify-workflows/       公開保留的知識匯入 artifact

services/
  case-service/         case/document/review/issue 主流程
  parser-service/       文件解析（含 OCR）
  legal-retrieval/      法規檢索
  rule-engine/          規則判定
  llm-review/           模型判讀與改寫
  report-service/       報告輸出與下載
  audit-service/        稽核事件
  clause-engine/        長文切片與證據包組裝
  consistency-engine/   跨條款一致性檢查

packages/
  shared-schemas/       API schema
  domain-models/        DB model
  rule-library/         規則檔
  prompt-pack/          Prompt 版本資產
  longdoc-engine/       長文審查通用骨架

docs/                   設計、API、開發與整合文件
tests/                  單元 / 整合 / 合約 / e2e 測試
infra/                  compose、migration、k8s、terraform

建議閱讀順序

1. 本檔 README
2. docs/README.md
3. docs/sdd/system-overview.md
4. docs/bdd/features.md
5. docs/runbooks/local-dev.md

常見狀態與下一步

狀態	代表什麼	你要做什麼
completed	審查完成	可直接看議題或產生報告
review_required	系統要求人工確認	看 decision packet，確認後再重跑或核准
failed	審查失敗	依 user_message 與 next_step 修正資料後重試

常見問題

• Q：這是 SaaS 嗎？
  A：不是。UrbanReg AI 目前的定位是私有雲與本地環境中的審查系統，適合需要資料控管與稽核能力的團隊。

• Q：OpenAI / Gemini 金鑰要放在 Dify UI 嗎？
  A：不用。金鑰放在 Core runtime 環境變數，不進 plugin UI。

• Q：掃描 PDF 可以嗎？ A：可以。系統會先做 OCR，再進入相同審查流程。

• Q：系統能處理數十萬字的超長文件嗎？

  可以。架構設計就是為了避免全文 prompt。處理流程如下：

  PDF (最大 5000 頁 / 2GB)
  → parser 切成 clauses（每條 ~50-500 字）
  → rule engine 標記有風險的 clauses（通常 10-30% 被標記）
  → 每個被標記 clause 組成 evidence packet（主條款 + 前後文 + 法條）
  → LLM 只看 evidence packet（~2000-4000 tokens/次）
  → consistency engine 跑結構化摘要比對（不用 LLM）
  

  LLM 永遠不會看到全文。一份 5000 頁文件跟 50 頁文件的差別只是 clause 數量和 batch 數，單次 LLM 呼叫大小不變。

• Q：超長文件的資源需求是什麼？

  主要瓶頸會落在：

  • 大型 PDF 解析
  • clause 數量帶來的檢索與批次審查次數
  • LLM rate limit 與 worker throughput

  一般而言，500 頁以下文件可用單 worker 的開發環境先驗證；數千頁等級案件則建議提高 worker 數、記憶體與 review timeout。更完整的容量估算、瓶頸分析與建議配置，請看 docs/sdd/performance-and-capacity.md。

• Q：系統的預設容量限制是什麼？

  預設限制如下：

  • 最大頁數：5000 頁
  • 最大檔案大小：2 GB
  • 審查逾時：600 秒
  • 批次大小：20 條款 / 批

  對應環境變數與調整建議也整理在 docs/sdd/performance-and-capacity.md。

主要文件入口

• 文件索引：docs/README.md
• 深度分析報告：docs/sdd/deep-analysis.md
• 系統設計（繁中）：docs/sdd/system-overview.md
• 系統設計（英文）：docs/sdd/system-overview.en.md
• 容量與效能規劃：docs/sdd/performance-and-capacity.md
• 行為驗收（BDD）：docs/bdd/features.md
• API 補充說明：docs/api/openapi-notes.md