連接 AI 代理與台灣官方法律來源，提供研究流程、來源查證、證據綁定與答案驗證。
目前版本為 v1.0.0（套件 1.0.0）；功能、安裝與限制請見 1.0 說明。本文件描述 1.0 現行功能。
ALR-TW v1.0.0 是供不同 AI 代理使用的台灣法律研究與查證框架，透過 MCP（模型上下文協定）提供工具介面。它負責管理研究流程、官方來源查證、證據信任邊界、答案驗證與短期資料清除；Agent 負責理解問題與起草文字。
它不是法律意見服務，也不是完整台灣法律資料庫。v1.0.0 套件版本為 1.0.0；任何輸出都必須由具資格的人員依官方原文、適用時點與個案事實複核。
本 repo 不包含 LLM，也不包含 agent 實作。Repo 內的 demo ranking／示範 ranking 參數只用於展示與測試，不是 production ranking 設定；正式部署的模型、資料集、排序與權重由部署者自行治理。
-
官方歷史法條、函釋全文、原文引句映射與固定資料稽核命令。
-
HTTPS／HMAC 遠端精確資料包；逐項整合證據見 整合紀錄。
-
build-pack／inspect-pack：建置本機資料包及查核品質摘要；附合成示例。 -
草稿新增逐項修正建議；新版受管操作可在程序中斷後用新編號接續。
-
complete-research：接續研究、嚴格驗證與修訂稿重驗；每版草稿使用新操作編號。 -
review-draft：唯讀內部草稿與來源標註，不核准正式答案。 -
import-pack：認證並匯入本機裁判資料包，使用外部信任金鑰明示啟用。 -
advise-draft：明示啟用語意模型接線取得修稿建議，顧問不能升格證據或核准答案。
操作與限制見 1.0 說明。以功能可用性為優先，模型比較列末順位。
ALR-TW 的角色不是替 Agent「想出法律答案」，而是把法律研究中容易被忽略的步驟留下紀錄並加上限制：問題理解、來源尋找、官方回查、時點與角色辨識、證據綁定，以及最後的答案驗證。
外部 Agent／使用者提出問題
↓
ALR-TW 建立研究狀態與研究義務
↓
候選召回 → 官方來源查證 → 證據與時點／角色檢查
↓
Agent 依已驗證證據起草
↓
答案驗證 → validated／qualified／blocked
這種分工讓不同的 Agent、模型或 MCP client 可以共用同一套 server-side trust boundary；但模型本身的推理品質、法律涵攝與個案判斷，仍不會由這個 repo 自動保證。
| 功能 | 白話說明 |
|---|---|
| 精確法源查詢 | 查詢法規條文、正式裁判字號、JID 與憲法法庭資料，並回到官方來源核對。 |
| 多步驟法律研究 | 建立可觀察、可恢復的研究 run；可逐步處理，也可在一次 MCP 呼叫中執行 server-owned obligations。 |
| 候選資料召回 | 使用官方搜尋或 TLR（Taiwan Legal RAG） 找普通裁判／行政函釋候選；正式證據仍由 ALR-TW 官方驗證產生。 |
| 有界歷審檢查 | 對已驗證裁判讀取 TLR 記錄的上、下級審候選，再逐件回查官方正文與分類主文結果。 |
| 分析與答案驗證 | 將核心主張綁定同一研究 run 的證據，檢查來源、角色、時點與支持關係。 |
| 立法院資料定位 | 定位提案、條文對照、委員會、黨團協商與三讀階段材料；結果只作立法沿革候選。 |
| 短期研究資料管理 | 保存研究狀態與工具紀錄，依 retention policy 自動到期，也可以手動 purge。 |
- 不會產生法律意見、律師服務或個案決定。
- 不會把 Agent 自己提供的 official URL、hash、來源角色或 trust metadata 當成官方證據。
- 搜尋結果、TLR 結果、外部網路搜尋與立法院材料都是 candidate；只有 server-owned 的官方來源或通過可信快取閘門的材料才能進入正式答案驗證。
- 不承諾指定歷史日期的完整法規版本、普通裁判全域召回率、所有程序裁定正文、完整審級關係或附件／OCR 全覆蓋。
- 立法院連結的 PDF／DOC 不在本 connector 中解析；立法材料不等於現行有效法條，也不能代表單一立法者意旨。
not_found或有限範圍內查不到，不代表全球不存在，也不代表實務一致。- 目前尚無 semantic opposition classifier；有限範圍的反方候選查詢不能證明全球沒有反面見解或實務一致。
當既定檢查偵測到來源時點、角色、內容或主張支持不足時，系統會保留限制、要求人工複核或拒絕放行；這不代表能偵測所有法律推理錯誤。
| 結果 | 意義 |
|---|---|
validated |
目前 draft 通過這個研究 run 的確定性來源、時點、角色與 claim 檢查；不等於法律結論必然正確。 |
qualified |
有可核對的證據，但召回範圍、歷史版本、receipt 或其他限制必須一併揭露。 |
blocked／refusal_only |
不應展示草稿答案；需要補資料、改變研究範圍或交由人工處理。 |
ready_for_draft 只代表目前研究狀態允許進入起草階段，不代表研究充分。最後仍須由
validate_legal_answer 決定草稿是否可以展示。
v1.0.0 內建 ResearchService 會為同一 run 中通過官方／可信快取閘門的精確
source 與 evidence 集合簽發並持久化 provider-neutral snapshot receipt；caller 提供的
receipt 不受信任。receipt 完整、未過期且其餘閘門均通過時，ordinary 才可能
成為起草前姿態；缺 receipt 最高為 conditional，混用或內容不符則 fail closed。
safe_to_draft 不授權直接展示；仍須由 validate_legal_answer 檢查草稿，且
blocked／refusal_only 不會帶出 answer body。receipt 只證明該 run 的材料綁定，
不證明全域召回完整、裁判確定或實務一致。
ALR-TW 將「找到資料」、「來源可信」與「資料支持這個主張」分開處理：
- Agent 可以提出問題、爭點與 locator，但不能自行建立正式 evidence。
- Server 會核對官方來源或合格可信快取，再建立 server-owned evidence（伺服器掌控的證據）。
- 法規時點、法院角色、主文／理由、當事人主張與個別意見會分開保存。
- 證據過期、識別不一致、角色錯置、主張超出證據或覆蓋不足時，結果會降級或拒絕。
因此，source_tier=official、caller 自帶的 URL 或「已驗證」欄位都不能繞過 server 的信任閘門。
- 先確認目前的資料模式、可用工具與限制。
- 建立研究 run，記錄問題、研究範圍與必要的法律爭點。
- 依研究義務取得候選法規、裁判、憲法或公法材料。
- 對候選來源回查官方識別碼與內容；候選資料不會直接升格。
- 檢查法律時點、來源角色、法院層級、主文／理由與個別意見等差異。
- Agent 以同一 run 的 evidence 起草，將核心主張綁定到對應證據。
- 由
validate_legal_answer決定可以展示、必須附限制，或只能拒答。
研究流程可以中斷與恢復；get_legal_research_state 只讀取狀態，不會自行發出新的網路請求，也不會延長保存期限。
| 模式 | 會不會連線 | 適合用途 |
|---|---|---|
synthetic |
不連線 | 預設的離線 demo、CI 與契約測試；不能支撐真實案件答案。 |
official_only |
預設使用官方網路來源；另行啟用的遠端包依設定連線 | 法規、司法院裁判與憲法法庭的查詢與官方回查。 |
hybrid_verified |
官方來源 + TLR | 用 TLR 提高普通裁判候選召回，再回司法院官方來源驗證。 |
召回／locator 資料層也可由部署者選擇。若使用 mcp-taiwan-legal-db 或其他能提供
正式字號、JID／官方 locator 的相容服務，前端可先取得候選，再透過
client_assisted research plan 提交給 ALR-TW；候選仍須完成官方回查才能建立 evidence。
部署環境也可用 ALR_TW_LOCAL_PORTAL_ROOT 接入既有相容的唯讀本機裁判資料層；
候選搜尋、快取驗證條件與官方回查方式見 Official Providers。
啟用 hybrid_verified 時，通過 privacy gate 的查詢文字可能送往 TLR。不要輸入個人秘密、未公開案件事實、私有契約、訴訟策略、證據弱點或談判底線。
若主要目的是找裁判，可以直接在提示詞開頭指定：
/quick 請查找定型化契約條款效力的相關裁判
也可寫成 快速模式：問題，或使用
constraints.research_depth="quick"。建議搭配 execute_legal_research，由 server
在一次呼叫內完成候選召回與最多五件官方回查。hybrid_verified quick 會先用
TLR／相容 provider 找候選；只有沒有可用候選或候選 provider 失敗時，才退回司法院
關鍵詞搜尋。候選 JID／正式字號仍逐件回查官方全文。
快速模式縮減的是研究廣度：裁判型問題預設不展開 counter-authority、歷審鏈或
未明示的法規研究；它不會跳過 JID／正式字號與官方內容驗證。至少一件候選通過
後，整條類案查詢仍只能以 qualified／conditional 呈現已驗證的 bounded
top-K 範圍；候選未通過或超出預算時再附個別限制，0 件通過仍會拒答。任何草稿
最後仍須經 validate_legal_answer。
研究尚未完成或被 gate 擋下時，get_legal_research_state 會提供正式
research_brief：只包含已驗證來源 locator、義務進度、blocker 與可重試步驟，沒有
草稿結論，且固定 answer_authorized=false、safe_to_present=false。Client 不需要為了
顯示進度而繞過 server 直接讀庫。
| 來源 | 可以協助的工作 | 不能直接宣稱的事情 |
|---|---|---|
| 法務部全國法規資料庫 | 法規名稱、條文、現行／廢止狀態與官方內容核對 | 未確認歷史日期的完整版本、地方自治法規或所有附件 |
| 司法院裁判書網站 | 普通裁判候選、JID 與官方全文回查 | 全域裁判召回、所有程序裁定或完整審級關係 |
| 憲法法庭 | 判決、實體裁定、舊制解釋及可取得的意見材料 | 把個別意見當成多數理由或拘束內容 |
| TLR | 提高普通裁判與行政函釋候選召回率；提供裁判命中片段及有界全文分頁 | TLR excerpt、全文、效力標記、排序或 URL 本身不是正式證據 |
| 立法院官方資料集 | 定位提案與立法過程材料 | 有效法條、完整立法理由或單一立法者意旨 |
立法院資料是 optional、read-only、bounded、candidate-only 的定位結果，可涵蓋議案提案、條文對照表、委員會議案、黨團協商與三讀階段材料。只有在 live data mode 中由 Agent 明示呼叫 lookup_legislative_history 才會查詢；synthetic mode 固定不連線。連結的 PDF／DOC 不在 connector 中解析，材料仍須回到正式公布版本與 server-owned official verification，才可能進一步作為研究證據。
詳細的 provider 行為、解析限制與來源升格規則見 Official Providers。
研究 run 會暫存在受管理的 SQLite 儲存中，用來保存研究狀態、工具事件與 evidence 關聯；預設位置是 ~/.cache/alr-tw，預設保留 24h，公開預覽的上限為 7d。也可以將單次 run 設為 ephemeral，在答案驗證後同步清除。
alr-tw purge --run RUN_ID --confirm
alr-tw purge --all --confirm清除本機資料不能撤回已經送到 TLR、官方網站或其他外部服務的查詢與日誌。不要把 API key、個人資料、未公開案情或秘密寫入 repo、.env.example、trace、SQLite 或 MCP client log。完整規則見 Storage and Purge 與 Data Policy。
| 你想做的事 | 建議方式 | 需要注意 |
|---|---|---|
| 只查一個條文或正式裁判 | 使用 lookup_legal_source |
查到來源不等於整份答案已驗證，仍要做 answer validation。 |
| 快速找出並核對類案 | 使用 /quick 搭配 execute_legal_research |
最多回查五件；未窮盡、查無結果與淘汰候選都不能支持全球不存在主張。 |
| 研究一個包含多個爭點的問題 | 使用 standard／deep 的 research_legal_question 與逐步研究流程 |
ready_for_draft 不是「研究已充分」的保證。 |
| 找普通裁判候選 | 使用官方搜尋或 hybrid_verified |
TLR 只提高召回，最後仍須回司法院官方全文。 |
| 找行政函釋候選 | 使用 TLR provider 的 typed public-law candidate API | 只作定位；須另經 ALR-TW 所治理的官方 public-law adapter 驗證，內建 runtime 目前不附該 connector。 |
| 查已驗證裁判的上下級審 | 在同一 run 使用 inspect_judgment_lineage |
只涵蓋 TLR 記錄與本次回查上限；查無上級審不等於裁判確定，也不自動判斷見解是否不同。 |
| 查修法背景或立法沿革 | 在 live mode 明示 lookup_legislative_history |
結果是 bounded candidate locator，不是有效法條或完整理由全文。 |
| 驗證已經寫好的草稿 | 用同一 run 的 evidence 呼叫 validate_legal_answer |
未綁定核心主張、證據衝突或範圍不足時，結果可能被拒絕。 |
需要 Python 3.11 以上：
python -m venv .venv
source .venv/bin/activate
pip install -e '.[all]'先以離線模式確認安裝：
alr-tw doctor要啟用官方 live mode，必須明確選擇資料模式：
export ALR_TW_DATA_MODE=official_only
export ALR_TW_RETENTION=24h
alr-tw doctor --live官方 HTTPS provider 預設使用作業系統憑證庫（truststore）。doctor --live 會實際
檢查法務部、憲法法庭與司法院裁判來源；憑證驗證失敗會以
OFFICIAL_TLS_VERIFICATION_FAILED 明示，而不是被誤報成查無資料。
普通裁判查詢不需要司法院 API token；live 查詢的關鍵字、案號與篩選條件會送到官方網站。不要把未公開個案事實或保密資料當成搜尋詞。
可直接使用 alr-tw quick-research 快速查證材料，接著以
alr-tw validate-draft 驗證同次研究的草稿與段落綁定；
alr-tw research-status 可查看繁中進度與待補項目。
完整範例、輸入格式與拒答補救見 快速查案與草稿驗證。
新整合建議依序：
- 呼叫
get_legal_research_capabilities，先確認目前 data mode 與可用工具。 - 快速或一般 server-managed 研究可呼叫
execute_legal_research；需要逐步除錯或 client-assisted plan 時，使用research_legal_question再依序執行continue_legal_research。 - 讀取
get_legal_research_finalization，確認證據、限制與答案姿態。 - 只使用同一 run 的 server-owned evidence 起草。
- 呼叫
validate_legal_answer，只展示允許展示的結果。 - 到期材料不能繼續授權答案；使用
purge_research_storage清除已不需要的研究，不把期限到期當成檔案已刪除。
若只需核對單一法源，可使用 lookup_legal_source；若要查立法沿革候選，可在 live mode 明示使用 lookup_legislative_history。
若本機 stdio MCP process 被強制終止，而宿主畫面仍顯示舊的 connected 狀態，先停用
再啟用該 MCP 設定或重新啟動宿主；仍為 Not connected 時移除後依原設定重新加入。
強制終止後的宿主連線顯示不由 ALR-TW process 控制，不應把殘留 UI 狀態視為健康證據。
可複製的 Agent 工作區規則見 templates/AGENTS.md。它是使用建議，不是安全邊界；真正的工具權限、證據升格與拒答規則由 MCP server 強制執行。
| 工具 | 用途 |
|---|---|
get_legal_research_capabilities |
了解目前資料模式、可用 profile 與 server 的信任責任。 |
research_legal_question |
建立一個 server-owned research run。 |
execute_legal_research |
建立 run 並一次執行可執行的 server-owned obligations；保留逐步稽核與 final-answer validation。 |
review_legal_draft |
唯讀內部草稿及來源標註，不核准正式答案 |
complete_legal_research |
接續有界研究並嚴格驗證；修稿使用新操作編號，既有結果保留 |
continue_legal_research |
執行下一個研究義務；每次只推進一個有界步驟。 |
get_legal_research_state |
唯讀恢復研究狀態，不做新的網路請求。 |
get_legal_research_finalization |
查看研究充分性、覆蓋限制、blockers 與答案姿態。 |
lookup_legal_source |
精確查詢法規、裁判或憲法法庭正式來源。 |
inspect_judgment_lineage |
查同一 run 已驗證裁判的 TLR 上下級審記錄，並回查官方主文。 |
lookup_legislative_history |
查詢立法院 candidate-only 立法資料定位。 |
validate_legal_analysis |
驗證結構化分析與 server-owned references。 |
validate_legal_answer |
以同一 run 的 evidence 驗證草稿答案。 |
purge_research_storage |
清除單一 run 或受管理的研究資料。 |
Synthetic demo tools 僅用於離線測試與契約示範，不應用於真實案件或正式法律引證。完整工具清單與 input／output schema 見 Tool Contract。
先以不連線的 synthetic mode 測試 MCP client：
{
"mcpServers": {
"alr-tw": {
"command": "alr-tw-mcp",
"env": {
"ALR_TW_DATA_MODE": "synthetic"
}
}
}
}完整 tool schema、錯誤碼、profile、MCP protocol 相容性與資料契約，請看下方技術文件。
- Official Providers
- Tool Contract
- Agent-neutral Interoperability Contract
- Error Codes
- Architecture Contract
本專案僅供軟體架構、法律研究與測試，不構成法律意見、律師服務或任何個案結論，也不保證資料完整、正確、即時或適用。
1.0 功能與限制見 正式版說明；功能與驗證範圍保留原始驗收範圍。 受管儲存目前要求 POSIX 安全開檔能力；不支援的平台會明確拒絕。人工研究成效評核尚待安排。
若啟用桌面／文件的雲端同步，建議將工作目錄、虛擬環境及持續寫入的 SQLite 研究儲存放在不受同步管理的使用者專用目錄。這可減少同步與高頻 I/O 的干擾， 但不能據此將所有逾時或資料庫鎖定歸因於 iCloud；也應檢查多程序寫入與檔案權限。
使用 ALR_TW_STORAGE_PATH 指定研究儲存目錄（不是 ALR_TW_STORAGE_DIR）。
搬移前停止寫入程序並保留完整備份，勿在資料庫仍開啟時只複製主資料庫檔。
不要以共用暫存目錄作為敏感研究的持久儲存，也不需要停用系統的全部同步功能。