Skip to content

dify-plugin-install.md

Latest commit

 

History

History
146 lines (102 loc) · 4.95 KB

dify-plugin-install.md

File metadata and controls

146 lines (102 loc) · 4.95 KB

UrbanReg Dify Plugin 技術規格

安裝步驟請見 dify-local-stack.md 的「Plugin 安裝」章節。 本文件為 plugin 的技術規格與 API 對應表，供開發者修改 plugin 時參考。

Plugin 清單

Plugin 路徑 類型 說明
UrbanReg AI 核心介接器 apps/dify-plugin/ Tool 把 Dify workflow 工具呼叫轉送到 Core REST API
UrbanReg 法規來源 apps/law-source-plugin/ Datasource 把 Core 匯出的法規鏡像同步到 Dify 知識庫

Tool Plugin — 工具對應表

Dify 工具名稱 Core API Endpoint 說明
create_case POST /v1/cases 建立案件（需 tenant_id, project_id）
upload_document POST /v1/documents 註冊文件到案件
get_llm_provider_options GET /v1/reviews/llm-providers 查詢可用 LLM provider
start_review POST /v1/reviews 啟動審查（觸發完整 pipeline）
get_review_status GET /v1/reviews/{review_id} 查詢審查進度
rerun_review POST /v1/reviews/{review_id}/rerun 重新執行審查
list_issues GET /v1/reviews/{review_id}/issues 列出審查發現的問題
list_consistency_findings GET /v1/reviews/{review_id}/consistency-findings 列出跨條款一致性問題
get_issue_detail GET /v1/issues/{issue_id} 取得單一問題詳情
rewrite_clause POST /v1/clauses/{clause_id}/rewrite 取得條款改寫建議
generate_report POST /v1/reports 產生審查報告

Tool Plugin — Provider Credentials

欄位 型別 必填 預設 說明
core_base_url text 是 — Core API 位址。本地開發：http://host.docker.internal:18080
core_api_prefix text 否 /v1 API 路徑前綴
core_api_token secret 否 — Bearer token（開發環境可留空）

Tool Plugin — LLM Provider 選擇

start_review 工具有 llm_provider 欄位：

值 行為
auto（預設） 依 Core 配置的 API key 自動決定
deterministic 僅用確定性規則引擎
openai 使用 OpenAI (gpt-4o-mini)
gemini 使用 Google Gemini

auto 的解析邏輯：

  • 只有 Gemini key → gemini
  • 只有 OpenAI key → openai
  • 都有或都沒有 → deterministic

API key 在 Core 端管理（URBANREG_OPENAI_API_KEY、URBANREG_GEMINI_API_KEY），不在 Dify UI 輸入。

Datasource Plugin — 法規來源

功能

將 Core 的 GET /v1/laws/export 回傳的法規快照匯入 Dify 知識庫，用於 RAG pipeline。

Credentials

與 Tool Plugin 相同的三個欄位（core_base_url、core_api_prefix、core_api_token）。

使用方式

  1. Dify UI → 知識庫 → 新建知識 → 選「UrbanReg Law Source」
  2. 設定 credentials
  3. 選擇分塊策略（推薦搭配「通用文本分塊」plugin）
  4. 啟動 indexing

語系規則

所有使用者可見文字必須包含三個 locale key：

label:
  en_US: "English label"
  zh_Hant: "繁體中文標籤"
  zh_Hans: "繁體中文標籤"    # ← 故意與 zh_Hant 相同

原因：Dify 1.9.2 各畫面的 locale lookup 不一致（有些讀 zh_Hant、有些讀 zh_Hans）。少一個 key 會退回英文。

Runtime 規格

Tool Spec 必要欄位

Dify plugin_daemon 的 runtime 驗證比打包更嚴格：

  • 最上層 description 需有 human / llm
  • 每個參數需有 human_description
  • form 型別參數需設 form: form

Datasource Spec 必要條件

  • Provider tag 使用 Dify 支援的 tag
  • Provider 用 credentials_schema（非 credentials_for_provider）
  • Page content 對齊 output_schema 的 variable message

打包指令

# Tool Plugin
make package-dify-plugin
# 產出：apps/dify-plugin/dist/urbanreg-dify-plugin.difypkg

# Law Source Plugin
make package-law-source-plugin
# 產出：apps/law-source-plugin/dist/urbanreg-law-source-plugin.difypkg

打包依賴 dify-plugin CLI。若不在 PATH 中，build helper 會明確失敗。

版本對應

元件 版本 Pin 位置
Dify Core 1.9.2 infra/compose/dify-local.sh
Plugin SDK >=0.5.0,<0.6.0 apps/*/requirements.txt
Manifest Spec 0.0.2 apps/*/manifest.yaml → meta.version
minimum_dify_version 1.9.0 apps/*/manifest.yaml
Plugin Python 3.12 apps/*/manifest.yaml → runner.language

變更版本前必須參考：dify-compatibility.md

注意事項

  • 能打包 ≠ 能執行：.difypkg 可安裝但 plugin 可能沒 load。檢查： 
    docker logs --tail 200 urbanreg-dify-plugin_daemon-1
  • Core API 改了 → 同步更新 plugin：修改 YAML tool spec + Python router
  • Plugin runtime 自足：不依賴 repo 的 shared package 在 Dify sandbox 中存在