dbcli 完整說明文件

快速入門

使用您偏好的套件管理器進行全域安裝：

# 使用 Bun（執行時必要）
bun install -g @carllee1983/dbcli

# 使用 npm
npm install -g @carllee1983/dbcli

dbcli 執行於 Bun 1.4.0+。npm 與 npx 可作為發布通道，但安裝後的 dbcli 執行檔需要 PATH 上有 Bun；只有 ./agent-core 這個 subpath export 能被純 Node 程序 import。

單獨執行 dbcli --version 或 dbcli -V 時會使用輕量 launcher，不載入資料庫 driver；其他指令仍會照常載入完整 command runtime。

透過互動式導覽初始化您的第一個連線：

dbcli init

若是 MongoDB，init 會逐欄詢問連線資訊（Host、是否為 SRV、Port、User、Password、authSource，最後是可選的 replicaSet / tls）——完整欄位列表與 --uri 的拆解規則請見下方「引擎支援矩陣」一節的「MongoDB 連線設定」。

每次新建或新增連線都必須有非空白的連線名稱。可傳入 --conn-name <name>，或在互動式終端機執行 dbcli init，由程式主動詢問。名稱提示不會建議 default；輸入空字串或只有空白時，會說明名稱必填並再次詢問。取消或結束名稱提示會在連線測試、設定或憑證寫入前停止。明確提供非空白的 --conn-name 就不會再問名稱，--conn-name default 仍然合法。明確傳入空白的 --conn-name 則在任何模式都會於連線測試或寫入前報錯。--name 仍代表資料庫名稱（Redis 則是邏輯資料庫索引），不能當作連線名稱。

沒有 TTY、指定 --no-interactive，或 --use-env-refs 搭配全部五個 --env-* 選項而自動停用互動時，缺少或空白的 --conn-name 會在存取資料庫、寫入設定或憑證前明確報錯，並提示補上名稱。完整憑證、--name、--env-file 與 --force 都不能代替連線名稱。

新初始化一律建立具名 v2 設定，包含單純的 init 與明確的 --config 路徑，不再建立未命名的 v1 設定。既有 v1 設定仍可讀取，也保留原有的具名 v2 匯入流程。全新 registry 的第一條明確具名連線仍會成為預設；新增到既有 registry 時，則保留原本的預設值或無預設狀態。明確選擇已存在的名稱時，仍須互動確認覆寫或指定 --force；非互動同名操作未帶 --force，或拒絕互動確認時，都不會改動檔案。--remove 與 --rename 不會詢問新的連線名稱。

在幕後，init 會在專案的 ./.dbcli/config.json 寫入一個 version: 3 的 binding stub，真正的連線設定與任何憑證則存放在家目錄的 ~/.config/dbcli/projects/<project-name>-<sha1-12>/。如此可還原的敏感資料不會留在專案工作區，掃描 repo 的工具或 AI agent 也看不到。專案的 .dbcli/ 只保留 binding 與非敏感快取（schema 快取、稽核記錄、快照、驗證產物）。

若要讓多個專案共用連線，請使用明確的全域 scope。它會把 v2 registry 儲存在 ~/.config/dbcli/config.json，且不會建立專案 binding：

dbcli --global init --conn-name shared --system postgresql \
  --host db.example.com --port 5432 --user app --password '<secret>' \
  --name appdb --skip-test --no-interactive --force
dbcli --global use --list --format json
dbcli --global status --format json

Root 層級的 --global 必須放在指令之前。全域 registry 與專案 registry 彼此獨立；未帶 --global 時仍使用目前專案的 registry。全域檔案與 home storage 的專案設定一樣，會使用 integrity record 與私有檔案權限保護。

遮蔽輸入憑證

互動式 init 以遮蔽提示收集資料庫密碼，以及貼上的 MongoDB 連線字串（它本身就帶著憑證），輸入值不會留在終端機捲動紀錄、錄影或螢幕分享畫面裡。Host、Port、使用者名稱、資料庫名稱與環境變數名稱維持一般的可見提示。

沒有純文字的退路。當遮蔽輸入無法提供時——沒有終端機，或提示實作載入不到——init 會在寫出任何設定之前停下來，並指出你可以改用哪一種輸入：--password、從 .env 或行程環境變數解析到的憑證、--use-env-refs，MongoDB 則是 --uri。明確給定的 --password 或 --uri 會原樣保留，也不會被當成可見的提示預設值印出來；--no-interactive 則根本不會走到任何 secret 提示。

若接下來的連線測試失敗，driver 的訊息與提示會先遮蔽並截斷再輸出——driver 經常把憑證或整條連線 URI 原樣寫回錯誤訊息裡。

這解決的是終端機回顯，不是儲存：dbcli 不會加密靜態憑證。要讓憑證不落在設定檔裡，用的是 --use-env-refs 與家目錄儲存。

PostgreSQL、MySQL 與 MariaDB 驗證式 TLS

建立具名 PostgreSQL、MySQL 或 MariaDB profile 時，必須一起提供兩個 SQL TLS 參數。以下範例會詢問密碼，並在保存前測試連線：

dbcli init --conn-name verified-pg --system postgresql \
  --host db.example.com --port 5432 --user reader --name appdb \
  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
dbcli --use verified-pg blacklist list
dbcli --use verified-pg schema public.events --format json
dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json

MySQL 與 MariaDB 使用相同參數，各自保存具名 profile 與 CA 路徑。選取對應 profile 後，同樣先檢查 blacklist 與 schema，再執行已獲授權的查詢：

dbcli init --conn-name verified-mysql --system mysql \
  --host mysql.example.com --port 3306 --user reader --name appdb \
  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
dbcli init --conn-name verified-mariadb --system mariadb \
  --host mariadb.example.com --port 3306 --user reader --name appdb \
  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem

請將主機、資料庫與資料表換成已獲授權的目標，並先透過 schema 確認實際欄位再查詢。保存的連線會包含獨立的 SQL 設定物件（以下為連線片段）：

{
  "sqlTls": {
    "mode": "verify-full",
    "caPath": "/absolute/path/to/certs/root-ca.pem"
  }
}

--sql-tls verify-full 與 --sql-tls-ca <path> 必須成對提供；空值、其他模式與不支援的引擎都會明確失敗。此 SQL TLS 契約支援 PostgreSQL、MySQL 與 MariaDB；其他引擎會拒絕明確要求。MongoDB 的 tls 與 Elasticsearch 的 TLS 設定仍是各自獨立的契約。未設定 sqlTls 的既有 profile 維持原行為，不新增全域 TLS 政策。V1 目錄與 v2 profile 的讀取、正常 init 從 V1 目錄匯入 v2，以及公開的 migrateV1ToV2 helper，均保留 TLS 物件。Legacy V1 單檔 TLS profile 仍可在人類模式下讀取與使用，但自動 init 匯入會在連線或寫入前明確拒絕，保留原檔不變。此情況請在獨立設定目錄建立具名驗證式 TLS profile，完成驗證後再選取；遷移全程保留 sqlTls。

init 會以執行時的工作目錄解析相對 CA 路徑，再保存為絕對路徑。保存的 caPath 必須是非空白的 PEM CA bundle 絕對字面路徑，不接受環境變數參照；host／user 等既有欄位的受支援環境參照仍可使用。明確 TLS 只使用所選 profile 的 CA 與身分設定；ambient TLS 設定不能降低驗證要求或帶入其他 profile 的信任條件。每次建立連線都會重新讀取 CA bundle；無法讀取、空白或無效的 bundle 會在連線前停止。--skip-test 只略過初始化測試，不會略過後續使用時的驗證。

verify-full 要求加密、可信憑證鏈、有效日期，以及憑證身分符合設定的 DNS 主機名或 IP 位址。明確 SQL TLS 會拒絕 Unix socket。不受信任、過期或主機名不符的憑證，以及不支援 TLS 的伺服器，均在使用者查詢前失敗；不會明文重試或降低驗證要求。請修正 CA、目標主機名或憑證有效期後重試。只有 cipher 證據不能證明身分驗證成立。

TLS 錯誤復原時，請保留 TLS 設定，先修正 CA、主機名或憑證，再以 --config <path>（或 --global）明確選取設定；v2 還需以 --use <name> 選取具名 profile（也接受 DBCLI_CONNECTION）。所選 profile 必須仍有 sqlTls.mode: verify-full；缺少、無法明確解析或明文連線選取會阻擋即時復原步驟，不會退回預設明文連線。保存的 recovery envelope 已遮蔽原始 selector；目前選取代表你刻意指定的目標，不是原始目標的證明。Recovery apply 與驗證使用目前執行的 CLI，避免呼叫 PATH 上的舊版 dbcli。以上述 MySQL 範例為例：

bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json

Agent mode 仍允許透過已設定 profile 執行權限內的唯讀操作；DBCLI_AGENT_MODE=1 仍拒絕 init 與其他設定修改。TLS 不會繞過 production 明確選取、原生資料庫授權、permission、黑名單、write gate 或 audit 控制。

回滾執行檔時，請停止需要驗證式 TLS 的流程，或維持支援此功能的版本。舊版可能剝除 sqlTls；降版後保留 profile 並不保證仍符合要求。移除 TLS 設定或改用明文重試都不能恢復符合。本機隔離 PostgreSQL、MySQL 與 MariaDB fixture 結果不代表真實 RDS 已通過驗收；RDS 仍未驗證。

連線管理

在正式 (Prod)、測試 (Staging) 及本地 (Local) 環境間切換：

使用 --global 可在不依賴目前專案的情況下管理或執行 user-level registry 的具名連線：

dbcli --global use --list
dbcli --global use shared
dbcli --global query "SELECT 1"

未帶 --global 時，dbcli 仍會解析目前專案的 .dbcli binding。明確指定 scope 可避免在不相關的專案中意外選到全域連線。

Root-level --timeout <ms> 可針對單次執行覆寫連線 timeout（整數，100～600000；必須放在指令之前，與 --global、--use 同樣是 root-level flag）。它會覆寫連線設定中的 timeout 欄位；兩者都沒設定時，各 adapter 沿用內建的 5000ms 預設值。這個覆寫只在本次建立連線時套用，不會寫回 config.json；要永久生效請在連線設定裡寫 timeout 欄位。Elasticsearch 是把 timeout 套用在每個 request 上，而不是整條連線一次性生效。當預設值太緊時很實用，例如 MongoDB 跨 VPN 或連 Atlas：

dbcli --timeout 20000 --use <conn> list

連線逾時與語句逾時是兩個獨立的上限。--timeout 會同時收緊兩者，所以 --timeout 3000 也會中止跑超過 3 秒的 SQL。只想調整「一句查詢能跑多久」時，用 root-level --statement-timeout <ms>（整數，0～3600000；0 表示取消上限）或連線設定的 statementTimeout 欄位。兩者都沒設定時 dbcli 不設語句上限，交給伺服器自己的設定——跑六秒的分析查詢不會再因為連線逾時預設五秒而被砍掉：

dbcli --timeout 2000 --statement-timeout 120000 query "SELECT ... FROM big_table"

dbcli use --list         # 列出所有連線名稱
dbcli use --list --format json # 不含憑證的 JSON 連線清單
dbcli use --unset        # 清除預設值，不移除連線
dbcli use staging        # 切換預設連線
dbcli --use prod query "SELECT count(*) FROM users" # 全域單次 selector
dbcli query --use prod "SELECT count(*) FROM users" # 支援的指令層級寫法
DBCLI_CONNECTION=prod dbcli query "SELECT count(*) FROM users" # 環境變數 selector

若要提供明確且不含機密的環境標籤，可在 v2 具名連線設定可選的 environment 欄位，例如 "environment": "production"。dbcli use --list --format json 會回傳每個連線的名稱、環境標籤（或 null）、權限、系統、伺服器／資料庫識別與預設標記；由環境變數提供的識別欄位會是 null，只有 URI 的 MongoDB 與只有 Cloud ID 的 Elasticsearch 也會以 null 取代預設占位值。它刻意不輸出 user、password、URI、Cloud ID、API key 或環境變數名稱。拼錯連線 selector 時，dbcli 會提示相近的既有名稱。

在 v2 中，實際選取的連線名稱會保留到指令執行期間，因此 audit 記錄會路由到該連線自己的 audit stream。

dbcli use production --confirm-production production

選擇優先序為明確的 --use、DBCLI_CONNECTION、最後才是設定檔預設連線。環境變數值會移除前後空白，空值則視為未設定。單次 selector 不會修改持久化預設值。query、schema、list、export、check 支援指令層級寫法；其他指令請把全域 selector 放在指令之前。root 與指令層級值衝突時會清楚失敗。Selector 需要 v2 設定：單連線（v1）專案沒有具名連線可選，因此在 v1 下給 --use 或 DBCLI_CONNECTION 會被拒絕，而不是靜默改跑那唯一的連線。若把 --use 放在不支援的指令後面，dbcli 會維持拒絕並印出可直接複製的 root-level 寫法，例如 dbcli --use <connection> status。

不設定預設連線

v2 設定可以省略最外層的 default 欄位。如果提供此欄位，必須是指向既有連線的非空字串；null、"" 與不存在的名稱都無效。新 registry 的第一條明確具名連線會成為預設；新增連線則保留原本的預設值或無預設狀態。既有 v1 讀取與具名 v1 升級到 v2 的匯入流程仍受支援。

dbcli use --unset
dbcli --use staging query "SELECT 1"
DBCLI_CONNECTION=staging dbcli query "SELECT 1"

沒有儲存的預設連線時，需要連線的指令必須透過 --use 或 DBCLI_CONNECTION 明確選取，否則會在存取資料庫之前失敗，並列出可用的連線名稱，不包含端點或憑證。 dbcli 不會自動挑選第一條連線。上述選擇優先序與衝突檢查仍適用：CLI selector 不得空白，空白的環境變數 selector 則視為未設定。不存在的名稱與正式環境連線仍受既有的驗證及明確選取防護約束。

dbcli use --unset 只移除 v2 設定中持久化的 default 欄位，並回報已清除。欄位已不存在時也會成功，且不會修改連線。若同時提供連線名稱、--list、 --confirm-production 或 --format json，會拒絕且不寫入；它也不會轉換或覆寫 v1 設定。清除預設值與切換預設值使用相同的核准及 integrity record 保護寫入流程，在 agent mode 中仍會被擋下。

dbcli use 會說明目前沒有預設連線；文字清單不會將任何連線標為預設，JSON 清單的每筆連線都會是 isDefault: false，doctor 也會將省略預設值視為有效的 v2 設定；其連線檢查仍須明確指定 selector，例如 dbcli --use staging doctor。 dbcli init --remove <name> 若移除的是預設連線，會清除預設值並回報此變更，不會另選替代連線。移除其他連線時，會保留原本的預設值或無預設狀態；刪除最後一條連線則會被拒絕，設定不會改變。連線更名會保留無預設狀態；若更名的是目前預設連線，則會同步更新預設名稱。要重新設定預設值，請使用 dbcli use <name>；正式環境的確認要求維持不變。

舊版專案設定相容性：如果新增連線會匯入直接存放在專案內的 v2 registry，且既有連線的 envFile 不是 .env.local，init 會在寫入前拒絕，保留原設定與 env 檔案。請先由管理員將 registry 與自訂 env 檔案遷移到受支援的 home storage，再重試。一般已綁定／home-storage v2 設定，以及未設定 envFile 或只使用 .env.local 的直接專案 v2 設定，仍可正常使用。

伺服器強制的 SQL query-only 模式

在 PostgreSQL、MySQL 與 MariaDB 上，只要操作的有效權限是 query-only，每一句由呼叫端提供的 SQL 都會在實際執行它的 physical connection 上，包進一個全新的資料庫原生唯讀 transaction。這涵蓋 query、export、saved query 本體與驗證、report diagnostics、SQL shell、會實際執行的 explain plan，以及所選連線即使儲存較高 permission tier 的 fan-out。dbcli 若無法建立此邊界，會在送出目標語句前 fail closed。既有的 classifier、blacklist、hidden-write 與 multi-statement 檢查仍會先執行。若目標語句完成後 transaction 清理失敗，dbcli 會回報結果不確定並丟棄受影響的連線；SQL shell 會為後續語句重新連線，但不會重送已完成的目標語句。

這項保證涵蓋持久、非 temporary 的資料與 schema。各引擎的原生唯讀規則仍可能允許 temporary 或 session-local state；此邊界也無法阻止目標資料庫之外的副作用，例如不安全 extension 發出的網路呼叫。資料庫帳號與 ACL 仍是重要的獨立防線。

唯讀 query fan-out

明確指定逗號分隔的 --use，即可對多個具名連線執行同一個唯讀 query。Root 層級與指令層級寫法效果相同：

dbcli --use primary,staging query "SELECT count(*) FROM users" --format json
dbcli query --use primary,staging "SELECT count(*) FROM users"

連線名稱會移除前後空白，結果則維持 selector 的順序；空白或重複名稱會被拒絕。只指定一個名稱時仍走既有的單連線路徑。Fan-out 只會由明確的 --use 啟用：DBCLI_CONNECTION 仍代表一個完整的連線名稱，不會依逗號拆分。兩種 --use 寫法都不會修改持久化的預設連線。

在任何 adapter 建立連線前，dbcli 會先載入並驗證所有選定的連線配置。SQL fan-out 只允許唯讀分類（SELECT、SHOW、DESCRIBE、EXPLAIN）；MongoDB 允許 filter object 與唯讀 aggregation pipeline，但拒絕頂層 $out 或 $merge stage；Elasticsearch 只允許 search。Redis 不支援 fan-out。多連線 query 也會拒絕 --recovery、--ui、CSV 與 HTML 輸出；請使用 --format table（預設）或 --format json。

每個連線都會獨立使用自己的 adapter、blacklist 過濾、row-limit／截斷 metadata、audit entry、計時與 disconnect；其中一個連線失敗不會取消或隱藏其他結果。JSON 會依序回傳 results array，每個連線都有標示清楚的 ok 或 error outcome；table 則依各自 schema 顯示獨立且具連線標籤的區段。全部成功時 aggregate exit code 為 0，成功與失敗混合時為 2，全部失敗或執行前拒絕請求時為 1。

密碼輪替

dbcli password 只變更單一連線的密碼，其他設定完全不動——專為密碼會定期自動輪替的環境設計。

dbcli password                       # 遮蔽輸入，輪替預設連線
dbcli password prod                  # 遮蔽輸入，輪替 'prod'
rotate-secret | dbcli password prod --stdin   # 非互動，密碼不會留在 shell 歷史
dbcli password prod --password "$NEW" --skip-test --format json

密碼寫到哪裡是從設定檔讀出來的，不是用猜的：若連線的 password 是 { "$env": "NAME" }，就會改寫該連線 envFile 裡的 NAME。連線沒宣告 envFile 時，輪替會順便把 envFile（.env.local）記錄進該連線設定——不記錄的話讀取端根本不會載入那個檔案。若連線目前仍是明文密碼，會一次性轉換成 { "$env": "DBCLI_<CONN>_PASSWORD" }，之後的輪替就只會動 env 檔。值會以加引號的形式寫入（NAME="..."），密碼首尾的空白因此能原樣保留。

v1 設定則會改寫 .env.local 裡的 DBCLI_PASSWORD，與 v1 的讀取邏輯一致。若 v1 設定的密碼來自其他環境變數（不是 DBCLI_PASSWORD），指令會直接報錯說明：v1 沒有 per-connection env 檔，dbcli 寫任何檔案都無法讓那個變數有值，請直接更新環境變數，或升級到 v2。

預設會先用新密碼實際連線驗證，通過才會寫入檔案，避免輪替失敗卻留下壞掉的憑證。資料庫連不到時可用 --skip-test 跳過驗證。env 檔在 POSIX 系統上會以 0600 權限寫入（Windows 沒有對應的權限位元，檔案沿用所在目錄的 ACL），密碼不會被回顯或寫進 log。

選項： [connection]、--stdin、--password <value>（會留在 shell 歷史與行程列表中，建議優先用 --stdin）、--skip-test、--format <text|json>。

在 DBCLI_AGENT_MODE=1 下，和其他憑證變更一樣會被擋下。

指令詳解

探索與發現

dbcli blacklist list --format json 會在 stdout 輸出一個 machine-readable 文件，包含 tables、columns 與 warnings；不合法的 MongoDB blacklist path 會放進結構化的 warnings 陣列，不會把人類可讀診斷混入 stdout。

檢視單一 SQL 物件的完整名稱

PostgreSQL 使用 schema.table，MySQL 與 MariaDB 使用 database.table，可檢視一個有權存取的表或 view（包含系統視圖）。欄位、enum、鍵、索引與外鍵均綁定同一 namespace 與局部名稱。不會變更連線、PostgreSQL search_path、預設 database 或 schema 快取；list、掃描與不帶物件的 schema 範圍不變。

dbcli schema pg_catalog.pg_roles --format json
dbcli schema information_schema.TABLES --format json
dbcli schema '"Audit"."Order.Items"' --format json
dbcli schema '`reporting`.`order.items`' --format json

以上 shell 範例外層的單引號會保留引擎原生識別字引號：PostgreSQL 用雙引號，MySQL／MariaDB 用反引號。每個 component 分別引用，以保留大小寫或名稱內的點號；內嵌的原生引號以連續兩個引號跳脫，例如 PostgreSQL 的 "Audit"."Order""Items"。PostgreSQL 完整名稱中未引用的 component 會折成小寫；MySQL／MariaDB 依伺服器的識別字大小寫規則處理。空 component、超過兩層、無效或未閉合的引號均拒絕，不會猜測另一種解讀。

未限定名稱保留既有精確名稱語意：PostgreSQL 使用 public，MySQL／MariaDB 使用連線的預設 database。完整名稱不存在時不會退回預設 namespace 的同名物件。相容性提醒：局部名稱本身含點號時，現在必須明確指定，例如 dbcli schema 'public."audit.orders"' --format json。此名稱解析僅適用於單一物件的 schema，不改變其他命令。

完整名稱的 JSON 輸出保留局部 name，另提供獨立的 schema 字串（MySQL／MariaDB 為 database 名稱）；文字輸出也會區分兩個 component，包含引用的點號與大小寫敏感名稱。tableType 為 table 或 view；PostgreSQL materialized view 歸為 view。完整名稱查詢不對關係資料執行 COUNT(*)。可用的 metadata 估計值只是估計，不是精確筆數；未知時 JSON 為 estimatedRowCount: null 與 sizeCategory: null，不虛構 metadata.rowCount: 0。文字不會以零筆或 small 分類替代未知值。既有未限定名稱的計數行為不變。

SQL 單一物件查詢的未限定與完整名稱都套用 blacklist。bare 或 qualified 規則任一命中即生效，沿用既有 glob 與大小寫匹配。受保護的表會拒絕查詢；受保護欄位會隱藏，含該欄位的主鍵或索引也會整項省略。外鍵來源或目標的表／欄位受保護時，表層級與欄位層級的外鍵 metadata 都會整條省略，複合約束不會被裁切成誤導的部分約束。此單一物件 schema 命令也會在無法安全表達完整欄位相依性時，整項省略 expression 或 partial index。省略 metadata 時，JSON 會輸出 metadataOmitted: true，文字輸出會顯示省略通知，可與原本不存在的 metadata 區分；回傳的 metadata 不一定完整。全欄位被隱藏不代表物件不存在。必要 metadata 讀取失敗（包含原生權限不足）會使命令失敗，不會以成功的空集合代替；資料庫無法區分不存在與不可見時，錯誤會保留此不確定性。

完整名稱不可與 --refresh 或 --reset 並用（也不能同時帶兩者），命令會在掃描前拒絕。快取維護請另行使用不帶完整名稱的 schema --refresh 或 schema --reset，範圍沿用既有行為。完整名稱檢視不會提升原生權限，也不會繞過 query-only、agent mode 或 blacklist 保護。

給 Skill 的能力探索

dbcli capabilities 用一個有版本、可解析的形狀回答「這個工具能做什麼」，讓外部 Skill 在動工之前就能決定。dbcli capabilities check --require <ids> 接著依本機設定回答「這裡有沒有」。兩者都不會建立資料庫連線。

dbcli capabilities --format json
dbcli capabilities check --require schema.read,query.read --format json

connection.tls 由引擎 capability matrix 表示 PostgreSQL、MySQL 與 MariaDB 的支援能力，對應既有連線指令介面，不新增 TLS 子指令。可執行 dbcli --use verified-pg capabilities check --require connection.tls --format json。available 只表示工具支援，不證明此 profile 已設定 TLS、CA 可讀取、握手成功或操作已獲授權。Catalog／check 維持離線，不讀取 CA bundle、不握手、不修改設定。其他引擎不會回報此能力為 available；沒有此 ID 的舊版回傳 unknown。設定修改仍需獨立授權。

套件內的 assets/integration-kit/ 提供可直接複製的 Bun/TypeScript consumer 與 Task Pack fixture。它會 pin 兩個 schema version、strictly parse catalog 與 Operation Envelope，並示範 exit、correlation 與 evidence 的邊界。其中的 CRUD、CQRS 與 DBA 範例仍是外部 consumer 的需求；dbcli 不實作也不核准這些工作流程。

Agent output v1

--agent-output 是 root option，必須放在 subcommand 前。PLAT-005 支援 dbcli --agent-output capabilities 與 dbcli --agent-output capabilities check --require <ids>；兩者都會在 stdout 輸出一份 compact UTF-8 JSON 文件與一個換行，stderr 不會有任何輸出。它是暫態的：不是 evidence，也不會建立 timestamp。

可在 subcommand 前使用可選 root option --correlation-id <id>，把一次 invocation 關聯到 Story、incident、change request、migration 或 backfill。ID 限 1–160 個 ASCII 英數字、點、底線、冒號或連字號；不可放憑證、SQL、個人資料或自由文字標籤。已支援且非 static 的回應會在 context.correlationId 顯示 ID，既有 audit entry 會在 metadata.correlation_id 記錄它；command summary 會遮蔽它。Static capabilities 仍保持 context: null。此 option 不會建立 evidence，也不會改動 receipt。

v1 envelope 一律有十個 key：schemaVersion、ok、operation、status、context、data、warnings、evidence、recovery 與 error。schemaVersion 是 1；operation 是 capabilities.list 或 capabilities.check；status 是 succeeded 或 failed；consumer 必須依 key 名稱讀取，不能依欄位順序。文件連同換行上限為 64 KiB。

不可把 --agent-output 和明確提供的 --format 或 --for-agent 一起使用；這類衝突、放在 subcommand 後、無效輸入或不支援的 operation，都會回傳一份 envelope 並以 exit 2 結束。成功 exit 0；需求未滿足或未預期的 internal failure exit 1。未使用 --agent-output 時，既有輸出行為不變。

error 與 warning 的 code/message vocabulary 永遠是 locale-independent English。Error code 為 INVALID_AGENT_OUTPUT_OPTIONS（無效、位置錯誤或衝突的 output option）、UNSUPPORTED_AGENT_OUTPUT_OPERATION（PLAT-005 範圍外的 operation）、INVALID_CAPABILITY_REQUIREMENTS（無效的 --require）、CAPABILITY_REQUIREMENTS_UNMET（已完成的 negative capability result）、AGENT_OUTPUT_LIMIT_EXCEEDED（64 KiB 上限）、AGENT_OUTPUT_INTERNAL_ERROR（未預期但安全的 failure）與 INVALID_CORRELATION_ID（無效的 root correlation ID）。Warning code 為 DUPLICATE_CAPABILITY_REQUIREMENT、CAPABILITY_CONTEXT_UNAVAILABLE、CAPABILITY_CONTEXT_UNRESOLVABLE 與 AGENT_MODE_RESTRICTION_ACTIVE。

一個 capability 是 dbcli 的單一原子能力——schema.read、data.delete。它絕不是職務或方法：dba.tune-production 與 crud.scaffold 屬於組合 dbcli 的 Role Skill 或 Method Skill。分層是 Story + AGENTS.md + Role Skill + Method Skill + Tool Skill + dbcli，而 dbcli 只回答最後兩層。

輸出刻意不代表的四件事：

• Discovery 不是授權。 列出一項能力只表示這個程式做得到，不表示你可以做。
• available 不等於已核准。 它只說 engine 與 permission 不會拒絕。Blacklist、write gate、確認與 audit 仍然全部會跑，也沒有任何人類同意過什麼。設定檔裡的 admin 是權限等級，不是 DBA 的簽核。
• schemaVersion 不是套件版本。 要 pin 的是 contract 版本，不是 7.x。
• Task Pack 的 plan 不是結果。 status: "planned" 與驗證結果始終是兩回事。

狀態有 available、unavailable 與 unknown。unavailable 的原因有 engine、agent-mode、permission、context-unavailable 與 context-unresolvable，依「最難修的排前面」回報，讓 reason 指到真正擋路的那一個。在 DBCLI_AGENT_MODE=1 之下，會變更設定的能力一律被拒，不管權限等級寫什麼。context-unresolvable 與 context-unavailable 刻意分開：{"$env": "..."} 密碼指向未設定變數的設定檔是存在且可讀的，宣稱「沒有設定」是假話。

無法辨識的 id 一律 fail closed，絕不會被解析成長得像的那一個。Exit code：0 全部可用、1 有任一不可用或未知、2 輸入無效。

Catalog 涵蓋所有公開指令，包含 capabilities 自己，而且每一條 engine 宣稱都是從實作讀出來的。程式碼會直接拒絕非 SQL 連線的那些指令——explain、plan、assert、snapshot、verify、proxy——在 MongoDB、Redis 與 Elasticsearch 上會回 unavailable 加上 reason engine。只有某一個模式需要 SQL 的指令——impact assess 與 design 的 --against-cache、semantic 的 draft validate——在那三個引擎上仍是 available，只標成 limited。程式碼判定不了的引擎，一律不會被標成支援。

required 與 results 依首次出現的輸入順序（first-seen input order）保留你送進來的 id，因此 results[i] 回答的就是 required[i]，重複的 id 只出現一次。把參數換個順序等於換了一份輸入，輸出也會跟著換順序——相同輸入才保證 byte-identical。換順序不會改變的是任何 capability 的 status、reason 與整體 ok。

inspect 給 agent 的輸出

dbcli inspect 回傳兩個平行陣列，讓 agent 在第一次呼叫就能定位：

• suggestedCommands — 可直接執行的後續指令，依三層排序：
  1. Bootstrap（啟動） — dbcli schema --refresh（schema 快取缺失或過期時）與 dbcli list --format json。
  2. Context-aware（情境感知） — 由近期活動驅動。當 audit log 偵測到熱門資料表且有可用的 task pack 時，建議 dbcli skill tasks plan analyze-table-perf --param table=<table>；並依 snippet intent 提供 dbcli queries suggest <intent>。
  3. Discovery（探索） — dbcli skill tasks list（有 task pack 時）與 dbcli doctor --format json。
• hints — 人類可讀、不可執行的提示：近期 audit 中最常查詢的資料表、可用 task pack 數量、以及 schema 快取規模與最後刷新時間。在 markdown 輸出會呈現為 ## Hints 區塊。

兩個陣列在 --for-agent / --brief 下都會被裁切（hints ≤ 3 條，suggestedCommands 只留最安全的 1 條）。

查詢與資料操作

# 原生查詢
dbcli query "SELECT * FROM users LIMIT 10"

# 靜態 SQL 顧問 (不連線資料庫)
dbcli lint "SELECT * FROM users" --format json

# 執行 Snippet
dbcli q @snippet --param id=1

# 匯出資料
dbcli export "SELECT * FROM logs" --format csv --output logs.csv

# 安全寫入
dbcli insert users --data '{"name":"Alice"}' --dry-run

# DML --plan 預檢 (不連線資料庫；SQL、MongoDB、Redis、Elasticsearch)
dbcli insert users --data '{"name":"Alice","email":"a@b.com"}' --plan --format json
dbcli update users --where '{"_id":"abc"}' --set '{"status":"inactive"}' --plan
dbcli delete products --where '{"_id":"abc"}' --plan --format json
dbcli delete 'user:42' --where '' --plan --format json

寫入確認閘門（2.0.0）

所有寫入都會經過兩級閘門。第一級是一個問題，第二級是一道沒有旗標可以繞過的拒絕。

第一級——一般寫入。 INSERT、帶 WHERE 的 UPDATE / DELETE、CREATE、ALTER。在互動終端下，dbcli 會先印出它把這句理解成什麼，再問你要不要執行；--yes 可以跳過。非互動執行（stdout 被導向、CI、agent）根本不會看到這個問題，--format json 即使在終端下也會關掉它。

第二級——收不回來的寫入。 沒有 WHERE 的 UPDATE / DELETE、DROP、TRUNCATE、SQL parser 讀不懂的語句、一個字串裡塞了多句語句、裡面夾著另一個寫入的語句（資料修改型 CTE，例如 WITH x AS (DELETE FROM t RETURNING *) INSERT INTO …）、帶 WHEN … THEN DELETE 或 THEN UPDATE 動作的 MERGE，以及 dbcli update / dbcli delete 中 --where 沒有命中主鍵或唯一索引的情況。dbcli 會要求你打出目標資料表的名稱，沒有任何旗標可以跳過，--yes 與 --force 都不行。當現場沒有人時，dbcli 直接拒絕：退出碼 1、什麼都不會送到資料庫，訊息會點名 reason=no_where、reason=ddl_destruction、reason=unparseable、reason=multiple_statements 、reason=non_unique_where、reason=multi_table 或 reason=nested_write。

接了另一張表的寫入一律第二級，不管 WHERE 寫什麼。 這種寫入會動到幾列取決於資料而不是語句：DELETE p FROM p JOIN o ON p.id = o.ref WHERE o.x > 0 在一組資料上刪了 5 列中的 2 列，在另一組上刪光 2000 列。join 的 ON 一定會提到目標表，所以它什麼也證明不了。這會讓 UPDATE … FROM、UPDATE … JOIN … SET 與多表 DELETE 這些標準寫法對無人看管的呼叫端被拒——把另一張表改寫成 WHERE 裡的子查詢，或改在有人可以確認的地方執行。

單表寫入的 WHERE 必須是在講那張表。 只存在於子查詢裡的 WHERE 不算：UPDATE p SET c = (SELECT max(x) FROM o WHERE o.id = 1) 有 WHERE，但改寫每一列。回頭指向目標表的相關參照則算數，所以 DELETE FROM t WHERE EXISTS (SELECT 1 FROM o WHERE o.tid = t.id) 是普通寫入，同一句改成裡面寫 WHERE o.id = 1 就會刪光整張表，屬第二級。這是下界而不是保證——WHERE id IS NOT NULL 提到了目標表，卻依然動到每一列。

逃生路徑寫在語句裡，不是寫在旗標上。 要在無人看管下執行全表寫入，就把意圖寫進 SQL——補上 WHERE 1=1 或 LIMIT。這是刻意的設計：對已經有 WHERE 的語句再接一個 WHERE 1=1 是語法錯誤，所以「乾脆全部都加上去」會立刻壞掉，養不成習慣；旗標的性質剛好相反。DROP 與 TRUNCATE 沒有子句可加：能不能執行由連線的 permission 層級決定，而打字確認仍然必須由人完成。

dbcli shell 只接第二級，不接第一級。shell 裡的每一句都是人手打的，逐句 y/N 會變成反射動作；但沒有 WHERE 的 DELETE、DROP、TRUNCATE 一樣要打出資料表名稱。打錯只會印出「已取消」並回到提示符——連線、緩衝區與歷史都還在，行程不會結束。按 Ctrl-C 則是收回這個提問：什麼都不會執行，接下來打的那一行會被當成語句，而不是被吃成確認答案。以管線餵進來的輸入（dbcli shell < script.sql）沒有人能回答，該句會被拒絕，其餘的行照跑。Redis、MongoDB 與 Elasticsearch 的 shell 不走寫入閘門，改由連線的 permission 等級把關。Elasticsearch 這一道在 4.0.0 之前並不存在 —— ES shell 完全沒有 permission 檢查就送到叢集，query-only 連線可以刪除文件、刪掉索引或改寫 mapping，而且什麼都沒被記錄。現在它用與 dbcli query 相同的分類器判斷每個請求，拒絕該等級不允許的操作，並且不論執行或被拒都寫入 audit —— 送出前一列、回應後一列，每列都以 <METHOD> <path> 寫明操作本身。伺服器端 script（script、script_fields）在 shell 裡也一律拒絕，與 dbcli query 一致：它們會在叢集上執行任意程式碼，並能把黑名單欄位以請求自選的名稱讀回來。以管線驅動的 shell 現在會把 audit 寫完才結束，printf 'DELETE /orders\n\n' | dbcli shell 不再能送到叢集卻不留紀錄；SQL shell 的同一個缺陷一併修正。SQL shell 從 5.0.0 起為每一句語句寫稽核列，形狀與 Elasticsearch shell 相同——送出前 attempt、回來後 outcome，被拒絕的語句只寫 outcome，因為它從未被嘗試。先前它只記錄 tier-two 的寫入閘門決策，所以在提示符打的 SELECT 與一句真的改了資料的 UPDATE 同樣不留痕跡，而同樣這兩句走 dbcli query 都會被記下。兩個 shell 的 phase 都放在 metadata.shell_phase。audit 預設是 best-effort——磁碟滿或 .dbcli/audit 不可寫時請求照樣送出，只留一行警告——若你認為「沒有紀錄的請求」比「被拒絕的請求」更糟，在設定裡開 audit.strict: true。它涵蓋 dbcli 在執行之前記錄操作的每一處：兩個 shell 送出前那一列，以及 SQL 寫入閘門的決定紀錄——現在也包含在 dbcli> 提示符打的 SELECT。事後才寫的紀錄不在範圍內——那時拒絕擋不回任何東西，只會把一次已完成的操作回報成失敗。dbcli audit health 看得到它現在是開是關。在 shell 裡以子指令形式打的 dbcli 指令（query "..."、\delete ...）跑在沒有 stdin 的獨立行程裡，沒有辦法提問，所以第二級語句會被拒絕，訊息會請你回到 dbcli> 提示符直接打。

名稱與 SQL 關鍵字相同的子指令需要 \ 前綴。 delete users --where id=1 會被當成 SQL——shell 就是拿來打 SQL 的，DELETE FROM users WHERE … 一定要能照打——所以它會等分號而不是執行子指令。要呼叫子指令請打 \delete users --where id=1。insert、update、explain 同理——與 SQL 關鍵字同名的子指令就這四個；前綴對每一個子指令都有效，所以要記的是一條規則而不是一張清單。語句還在累積時，.quit 與 .clear 依然有效、Ctrl-C 可取消——它們原本會被吃進緩衝區，讓 shell 看起來像當掉。

子指令跑在自己的行程裡且沒有 stdin，所以它原本的確認提問會讀到 EOF 而取消：在 shell 裡 \insert、\update、\delete 需要加 --force，或者直接在提示符打 SQL——那裡才答得了。第二級的確認不受影響：它會在子行程裡被拒絕，並請你回到提示符，因為表名只有在那裡打得出來。

每一次第二級判定都會寫進稽核紀錄——放行、取消、拒絕都記——所以這道閘門有沒有擋到東西是可以量測的，不是靠印象。dbcli audit write-gate 就是那個量測：第二級被觸及幾次、依哪一條判準，以及最後怎麼被回答。如果數字是零，該檢討的是判準，不是閘門。

# 拒絕：沒有 WHERE，也沒有人能確認
dbcli query "UPDATE users SET banned = 1" --format json
# → 退出碼 1、reason=no_where，什麼都沒送到資料庫

# 放行：意圖已經寫在語句裡
dbcli query "UPDATE users SET banned = 1 WHERE 1=1" --format json

# 一般寫入，無人看管或直接跳過提問
dbcli query "UPDATE users SET banned = 1 WHERE id = 3" --yes

# 條件欄位不唯一的結構化刪除：第二級
dbcli delete users --where "status=active"

從 positional、檔案或 stdin 讀取 query

dbcli query [sql] [-f, --query-file <path>] 必須且只能指定一個 query 來源：positional query 文字、--query-file 指定的 UTF-8 檔案，或以 --query-file - 從 stdin 讀取。未提供來源，或同時提供 positional 文字與 --query-file 都會報錯。dbcli 讀取來源後會移除一個開頭的 UTF-8 BOM 與前後空白；處理後若為空內容，則會拒絕執行。--query-file - 需要 piped input：當 stdin 是互動式終端時，dbcli 會立即拒絕，而不是無提示地空等輸入。

透過 stdin 傳入多行 SQL，就不需要把整段內容 escape 成單一 shell argument：

dbcli query --query-file - <<'SQL'
SELECT id, email
FROM users
WHERE status = 'active'
ORDER BY id;
SQL

MongoDB filter 與 aggregation pipeline 也使用相同的檔案／stdin 來源。如果 pipeline.json 包含 [{"$match":{"message":{"$regex":"user's event"}}}]，下列兩種寫法都不必處理其中對 shell 不友善的 apostrophe：

dbcli query --collection raw_logs --query-file ./pipeline.json

dbcli query --collection raw_logs --query-file - <<'JSON'
[{"$match":{"message":{"$regex":"user's event"}}}]
JSON

被動慢查詢提示

query 與 q 會觀察已完成查詢所回傳的執行時間。預設門檻為 1000ms；跨過門檻時，table 輸出會附上 Performance hint，JSON 輸出則會在 metadata.performanceAdvisory 提供結構化資訊。快速查詢的輸出維持不變，因此正常查詢不會反覆收到建議。

# 查詢花費 250ms 以上時才提示後續檢視方式
dbcli query "SELECT * FROM events WHERE account_id = 42" --slow-ms 250

# 為這次 invocation 關閉被動提示
dbcli q @daily-active-users --slow-ms 0

此提示不會執行 EXPLAIN、讀取 schema，也不會發出第二個資料庫請求。在 PostgreSQL、MySQL、MariaDB 與 Redis 上，它建議不會修改資料的下一步：dbcli guide slow-query --format markdown；更深入的診斷應在檢閱該指引與相關 query 後才執行。MongoDB 與 Elasticsearch 沒有對應該目標的診斷 snippet，因此提示只陳述耗時，不會指向一個查不到東西的指令。

使用 --fields 投影欄位

--fields 可將 SQL 或 MongoDB query 結果縮減為需要的欄位。使用 inclusion list 保留欄位，輸出順序會依照指定順序：

dbcli query "SELECT * FROM events" --fields id,name,created_at
dbcli query '{}' --collection raw_logs --fields station_code,bet,win,created_at

在每個欄位前加上 - 即可排除欄位。為了讓開頭的 hyphen 明確屬於 option value，請使用可攜的 = 寫法：

dbcli query "SELECT * FROM events" --fields=-raw_response,-request_payload
dbcli query '{}' --collection raw_logs --fields=-raw_response,-request_payload

每次執行只能使用 inclusion 或 exclusion 其中一種語法，不可混用。空白 list、空白項目與重複 path 都會被拒絕。支援 profile.name 這類 dotted path；inclusion 輸出會遵循指定順序。MongoDB inclusion 預設排除 _id，只有明確指定 _id 時才會保留。結果中不存在的欄位會回傳 null 而非報錯，因此拼錯的欄位名會得到一整欄 null——在把「全 null」解讀成有意義之前，先用 dbcli schema 核對欄位名。

SQL 會在 query 執行完畢後對回傳 rows 套用 projection。MongoDB 會將 projection 下推至 find 或 aggregation pipeline 以減少傳輸資料量，之後再於 blacklist masking 完成後正規化回傳 rows。Redis 與 Elasticsearch query 不支援 --fields。

Blacklist 仍是最終權限邊界：--fields 無法顯示受保護欄位；field projection 只是調整結果形狀的便利功能，不是 security boundary。

寫入結果

insert、update 或 delete 在互動終端完成後，dbcli 會以自然語句摘要實際結果：受影響的列數與資料表、沒有符合資料、取消、dry-run 或失敗；只有真正執行的操作才會顯示耗時。stdout 被重新導向或透過 pipe 傳遞時，仍維持供腳本使用的穩定 JSON result envelope。在終端中使用 --format json 也可明確保留該 envelope。SQL、MongoDB 與 Redis 使用相同的 outcome 詞彙；dry-run 會回報 dry_run，不再回報 success。

真的改動到資料的寫入，摘要還會說明如何取回先前的值——就這三個指令而言只有備份一途：寫入成功之後 dbcli 不保留任何自動還原機制。失敗時改為指出 --recovery，也就是產生回復計畫、供 dbcli recover 讀取的旗標。沒有造成任何改動的結局（取消、dry-run、沒有符合的列）不會提到還原，因為沒有東西需要還原。

失敗同樣是散文，並且寫到 stderr、退出碼 1——不論是 blacklist 拒絕、--set 格式錯誤，或資料庫退回的語句。--format 在這三個指令只接受 text 或 json，其他值會在連線之前就被拒絕，而不是悄悄當成 text。

沒有加 --force 的寫入所詢問的確認內容——產生的 SQL、參數、刪除的危險警告，以及 y/n 問句——一律寫到 stderr，不寫 stdout。終端機兩個串流都看得到，所以手動執行時外觀不變；而擷取 stdout 的腳本無論有沒有 --force，拿到的都只會是一份 JSON 文件。dry-run 與取消都不會對資料庫送出任何寫入，但兩者仍會連線並讀取資料表 schema——因為它們要顯示的 SQL 沒有欄位清單就組不出來；完全不連線的預檢請改用 --plan。MongoDB 與 Redis 的寫入也會問同一個問題——它們是由指令直接送出而非經過 SQL executor，過去完全不問就執行——所以 cancelled 現在在每個引擎都可能出現。它們的提示顯示的是 dry-run 會印出的那段語句，沒有參數區塊，因為那些語句的值本來就寫在裡面。

--recovery 同時改變 insert / update / delete 失敗時寫到 stdout 的內容：失敗時 recovery envelope 會取代 JSON result envelope，而不是接在它後面，因此解析 stdout 的呼叫端無論如何都只會拿到一份文件。沒有加這個旗標時，失敗仍然是印出 status: "error" 的 result envelope 並以 1 退出。

insert、update、delete 支援 --plan，可在不連線資料庫的情況下對即將執行的寫入操作執行靜態風險分析。此預檢現已支援 SQL（postgresql、mysql、mariadb）、MongoDB、Redis 與 Elasticsearch。預檢會套用該連線的 permission、blacklist 與該引擎的 schema 快取。--format text（預設）輸出人類可讀結論，--format json 輸出完整 QueryRiskResult。分析器回傳 BLOCK 時 exit code 仍為 0；設定 / 連線系統 / 無效 DSL 等錯誤才會 exit 1。--plan 與 --dry-run 互斥。

各引擎在 MVP 中的保守限制：

BLOCK 表示預檢偵測到不安全的意圖。實際執行寫入前仍建議使用 --dry-run 再次確認。

儲存查詢管理

在版本控制中維護複雜的查詢片段，支援參數化與視覺化元資料。

• dbcli queries list：檢視所有可用片段。
• dbcli queries search：使用模糊關鍵字搜尋。
• dbcli queries suggest：根據操作意圖獲取建議。
• dbcli queries new @my/query --local：建立新的本地片段。

健康度與診斷

dbcli backfill artifact --source ./backfill.json \
  --source-use staging --target-use production

dbcli skill tasks plan orm-drift-review --param orm_path=prisma/schema.prisma --format json
dbcli diff --against-orm prisma/schema.prisma --format json

drizzle-kit generate
dbcli diff --against-orm drizzle/meta/0001_snapshot.json --orm-format drizzle --format table

bunx typeorm schema:log -d <path/to/datasource> > schema.sql
dbcli diff --against-orm schema.sql --orm-format typeorm --format table

# 先將專案的 Sequelize config 指向空的 scratch database
bunx sequelize-cli db:migrate
pg_dump --schema-only <scratch-database> > schema.sql
# MySQL 則改用：
mysqldump --no-data <database> > schema.sql
dbcli diff --against-orm schema.sql --orm-format sequelize --format json

dbcli diff --against-orm "migrations/*.sql" --orm-format ddl --format markdown
dbcli diff --against-orm schema.normalized.json --orm-format json --format table
dbcli diff --against-orm prisma/schema.prisma --recovery --format json

dbcli skill tasks plan migration-review \
  --param "table=${exact_table}" \
  --param "ddl=${captured_ddl}"

資料驗證

驗證資料處理結果是否正確 — 擷取結果指紋,再針對指紋、第二個查詢或行內條件斷言不變量。僅支援 SQL 引擎(PostgreSQL / MySQL / MariaDB)。

assert --write-verification-artifact

使用 --write-verification-artifact 可在 read-back 斷言執行後，將結果佐證記錄（v1 VerificationArtifact JSON）寫入 .dbcli/verification/，提供可稽核的持久化軌跡。驗證文物會持續寫入 <cwd>/.dbcli/verification/（相對於當前工作目錄），不受 --config 檔案位置影響。

旗標：

assert --expect ... --evidence-receipt <path> 不必搭配 --write-verification-artifact 也能寫入 receipt。只有各項檢查的布林 pass bits 會投影至既有 receipt schema，不包含原始 SQL 或結果值。要求 receipt 時，失敗斷言仍會寫入 failed receipt。--no-fail 只影響斷言的退出行為，不會把 receipt 改成成功；receipt 寫入失敗仍 exit 1。

evidence compose 可用 --receipt <path> 參照該明確且 workspace-contained 的 receipt；provenance 不是執行核准。

輸出合約：

• --format json — 在 AssertVerdict 信封中新增 verificationArtifactPath 欄位。
• --format table — 額外印出 Verification artifact: <path> 那一行。
• 狀態跟隨斷言真值：--no-fail 失敗仍會記錄 not_verified / 佐證 exitCode: 1。

計畫佐證 vs 結果佐證的區別。 dbcli skill tasks plan safe-backfill-verify 產生的計畫 JSON 包含一個 verification 區塊，其 status 為 "planned" — 這是計畫中的佐證定義，描述哪項檢查將在執行時進行。最後的 assert --write-verification-artifact 步驟才會產生結果佐證（status: verified 或 not_verified）。這兩者是不同的記錄；"planned" 不代表驗證已執行。

注意： Postgres 的 bigint 聚合函數（count(*)、sum()）回傳的是字串，但比較時會依數值進行，因此 value == 0 不必轉型也成立。若要比對文字，把期望值加引號（value == "0"）。

# 1. 規劃工作流（plan-only，計畫佐證）
dbcli skill tasks plan safe-backfill-verify \
  --param table=orders \
  --param query="UPDATE orders SET status = 1 WHERE status IS NULL" \
  --param verify_query="SELECT count(*)::int FROM orders WHERE status IS NULL" \
  --param expect="value == 0"

# 2. 手動 dry-run 寫入操作
dbcli update orders --where "status IS NULL" --set '{"status": 1}' --dry-run

# 3. 在既有寫入權限下執行寫入
dbcli update orders --where "status IS NULL" --set '{"status": 1}'

# 4. 執行最終斷言並持久化結果佐證
dbcli assert "SELECT count(*)::int FROM orders WHERE status IS NULL" \
  --expect "value == 0" \
  --write-verification-artifact \
  --verification-subject backfill:safe-backfill-verify

dbcli verify 執行驗證情境（safe-backfill、migration、rollback、constraint），永不執行寫入或 DDL。dbcli verification 檢視與管理這些情境產生的本機結果文物（位於 .dbcli/verification/）。

在 --after-write 執行完成後，可加入 --evidence-receipt <工作區相對路徑>，原子寫入連結至結果文物的安全 provenance receipt。receipt 不含 SQL、rows、credentials 或使用者路徑；它只記錄 provenance，不代表核准執行。預檢模式沒有已執行的結果文物，因此不支援 receipt。receipt outcome（succeeded/failed）與情境 status（verified、not_verified、indeterminate 或 blocked）分開；task-pack 的 planned evidence 仍僅限計畫。

inspect、report、schema、plan、lint、explain 與 impact assess 也支援 --evidence-receipt <工作區相對路徑>。receipt 只含固定 command subject、capability、時間、安全 context digest 與可選 correlation ID。要求 receipt 時，成功與失敗的指令結果都會產生 receipt；receipt 寫入失敗不會改變指令結果或 exit code。

verify safe-backfill

在不執行任何 UPDATE 的前提下，驗證安全 backfill 的正確性。預檢模式（預設）執行唯讀防護並印出實際的 after-write 指令；--after-write 模式重新執行防護、執行回讀斷言，並寫入驗證文物。

⚠️ verify safe-backfill 永遠不會執行 backfill 寫入。請先透過一般寫入指令執行已核准的寫入，再執行 --after-write。

預檢（Preflight）：

dbcli verify safe-backfill \
  --table users \
  --query "UPDATE users SET status = 1 WHERE status IS NULL" \
  --verify-query "SELECT count(*)::int AS n FROM users WHERE status IS NULL" \
  --expect "value == 0"

After-write（寫入文物）：

dbcli verify safe-backfill ... --after-write

檢視結果：dbcli verification show <artifact-id>。

預檢也會回顯預計執行的 update（你需自行執行的 --query），讓印出的內容成為此操作完整、可直接複製的紀錄。

結果狀態：verified（回讀符合 --expect）、not_verified（回讀與 --expect 相悖）、blocked（防護失敗 — blacklist、schema、plan，或 verify-query 非唯讀）、indeterminate（斷言已執行但無法產生可信的結論）。

即使其中一項失敗，四項防護仍會全部執行並分別回報結果。After-write 只有在四項全數通過時才執行斷言；持久化的失敗原因使用固定安全標籤，不會保存 driver 錯誤文字。持久化的自訂標籤與 SQL 證據也會遮蔽憑證、檔案系統路徑及 SQL 註解。

防護約束（fail closed）：

• --verify-query 必須是單純的 SELECT。EXPLAIN / EXPLAIN ANALYZE、SHOW、DESCRIBE，以及會寫入資料的 CTE（WITH … (DELETE … RETURNING) …）都會被拒絕 — 在 PostgreSQL 上 EXPLAIN ANALYZE <write> 會真的執行寫入，因此回讀僅限於絕不會變更資料的語句。
• --query 的 UPDATE 目標必須等於 --table，並以 schema-aware 方式比對（public.users 不會通過 --table audit.users）。對其他資料表的 UPDATE 會被阻擋，確保你斷言的回讀對象與實際寫入的資料表一致。
• 持久化的文物僅儲存 verify-query 與 --expect 的有界、去除字面值的標籤：字串、數字與 dollar-quoted（$$…$$）字面值都會被移除，原始 SQL 及任何內嵌值都不會寫入磁碟。
• 印出的 after-write 指令會做 shell escaping，即使 SQL 含有引號也維持正確；並會帶上 --subject-name、--summary 與非預設的 --format。

💡 同一資料表的重複 backfill。文物的 subject 名稱預設為資料表（backfill:<table>）。當你對同一資料表執行多個不同的 backfill 時，請傳入 --subject-name <唯一標籤>，讓每次操作在 dbcli verification list 中都能獨立追蹤。

verify migration

針對 schema migration 進行預檢或 after-write 驗證。此指令永遠不會執行 DDL — 它分析提案的 ALTER TABLE、執行唯讀防護，並（在 after-write 模式下）在你於外部套用 migration 後記錄佐證。

⚠️ verify migration 永不執行 DDL。請先在外部套用 migration，再執行 --after-write 記錄佐證。

預檢（Preflight）：

dbcli verify migration \
  --table users \
  --ddl "ALTER TABLE users ADD COLUMN verified_at TIMESTAMPTZ" \
  --verify-query "SELECT count(*)::int AS n FROM users WHERE verified_at IS NOT NULL" \
  --expect "value == 0"

在外部套用 migration 後：

dbcli verify migration ... --after-write

預檢回傳 ready 或 blocked 並印出精確的 after-write 指令；ready 不等於 verified — 只表示防護通過。After-write 將回讀斷言對應至 verified / not_verified / indeterminate，防護失敗則為 blocked。MVP 中 CREATE TABLE、DROP TABLE、CREATE INDEX 及多語句 DDL 均會被阻擋。

ALTER TABLE 目標可為 table、schema.table 或 catalog.schema.table。每個區段可為簡單未加引號的名稱（[A-Za-z_][A-Za-z0-9_]*）或加引號的識別字 — 雙引號（"…"）、反引號（`…`）或方括號（[…]） — 因此 "user accounts" 或 "tenant-1"."orders" 皆可接受。無法在此契約下完整解析的目標（未封閉的引號、不支援的跳脫、或超過三個區段）會在 after-write 斷言之前被阻擋，原因明示「目標無法解析」，與 must match --table 的不符原因有所區別。

verify rollback

針對你於外部套用的 rollback 進行預檢或 after-write 驗證 — 可還原 schema migration（--kind ddl）或還原資料變更（--kind dml）。此指令永遠不會執行還原語句 — 它分析提案的 --statement、執行唯讀防護，並（在 after-write 模式下）在你自行套用 rollback 後記錄佐證。

⚠️ verify rollback 永不執行 rollback 語句。請先在外部套用 rollback，再執行 --after-write 記錄佐證。

Schema rollback 預檢（--kind ddl，單一 ALTER TABLE）：

dbcli verify rollback \
  --kind ddl \
  --table users \
  --statement "ALTER TABLE users DROP COLUMN verified_at" \
  --verify-query "SELECT count(*)::int AS n FROM information_schema.columns WHERE table_name = 'users' AND column_name = 'verified_at'" \
  --expect "value == 0"

資料 rollback 預檢（--kind dml，單一 UPDATE）：

dbcli verify rollback \
  --kind dml \
  --table users \
  --statement "UPDATE users SET status = NULL WHERE status = 9" \
  --verify-query "SELECT count(*)::int AS n FROM users WHERE status = 9" \
  --expect "value == 0"

在外部套用 rollback 後：

dbcli verify rollback --kind <ddl|dml> ... --after-write

--kind 決定語句須符合哪一種文法，並復用同類 scenario 的防護：ddl 復用 verify migration 的 ALTER TABLE 契約（單一語句、目標須符合 --table）；dml 復用 verify safe-backfill 的 plan 契約（僅 UPDATE、須含 WHERE、目標須符合 --table）。預檢回傳 ready 或 blocked；ready 不等於 verified。After-write 將回讀斷言對應至 verified / not_verified / indeterminate，防護失敗則為 blocked。文物會以既有的 subject kind 記錄此 rollback（ddl 為 migration，dml 為 backfill），並標記 command: verify rollback。MVP 中 ddl 僅支援單一 ALTER TABLE、dml 僅支援單一 UPDATE；尚未支援 INSERT／DELETE 還原。

verify constraint

預檢或 after-write 驗證「資料完整性不變式是否成立」 — 外鍵一致性、NOT NULL 覆蓋率、唯一性或自訂違規查詢。此指令永遠不會執行寫入 — 只執行唯讀 COUNT(*) 違規查詢，並（在 after-write 模式下）記錄佐證。

⚠️ verify constraint 永不執行寫入或 DDL 語句。請在變更前執行 preflight，變更套用後再以 --after-write 記錄佐證。

以 --check 選擇四種檢查類型：

• fk — 統計孤兒列數（子欄位無對應父列）。需提供 --column 與 --references <table.column>。
• not-null — 統計欄位值為 NULL 的列數。--column 可重複使用。
• unique — 統計欄位值重複的列數。--column 可重複使用。
• custom — 執行你提供的 --violation-query <sql>（唯讀 SELECT，回傳單一整數違規筆數）。

FK 預檢（在 migration 前驗證無孤兒 orders）：

dbcli verify constraint \
  --table orders \
  --check fk \
  --column customer_id \
  --references customers.id

NOT NULL 預檢（驗證欄位已完整填寫）：

dbcli verify constraint \
  --table users \
  --check not-null \
  --column email

在外部套用變更後：

dbcli verify constraint --table orders --check fk --column customer_id \
  --references customers.id --after-write

預檢回傳 ready 或 blocked；ready 不等於 verified。After-write 將違規筆數對應至 verified（violations ≤ threshold）或 not_verified（violations > threshold）。預設 threshold 為 0（嚴格模式）。啟用 --allow-preexisting 時，threshold 為 preflight 量測的 --baseline 筆數 — 只要 after-write 筆數不超過預既存水準即視為通過。查詢錯誤回傳 indeterminate，防護失敗回傳 blocked。文物使用 subject.kind = 'table'、command: verify constraint。MVP：僅限 SQL 引擎；FK 僅支援單一欄位；永不執行寫入。

verification — 檢視與管理驗證文物

dbcli verification 操作寫入於 <cwd>/.dbcli/verification/ 下的文物。它不連線資料庫、也不寫入稽核記錄。list、show、summary 為唯讀的檔案系統檢視；prune 為本機生命週期指令，預設為 dry-run，僅在帶上 --execute --force 時才刪除檔案。儲存根目錄為目前工作目錄，與 --config 位置無關。

• dbcli verification list [--format json|table] [--limit <n>] [--status <status>] [--subject <kind[:name]>] [--include-invalid] — 依最新優先列出文物。
• dbcli verification show <id-or-path> [--format json|table] — 以精確 id、唯一 id 前綴、檔名或路徑印出單筆文物。
• dbcli verification summary [--format json|table] [--status <status>] [--subject <kind[:name]>] [--latest-only] — 顯示最新狀態、各狀態計數、無效計數及每個 subject 的細分。--latest-only 縮小為最新的一筆符合有效文物加上各狀態計數（省略 subjects 細分）；無符合文物時以 0 退出並回傳 latest: null。
• dbcli verification prune --older-than <Nd> [--format json|table] [--keep-latest <n>] [--status <status>] [--subject <kind[:name]>] [--include-invalid] [--execute --force] — 預覽（dry-run）或依保留條件刪除本機驗證產物檔案。

狀態值：verified、not_verified、indeterminate、blocked。
Subject kind：recovery、task-pack、assertion、migration、backfill、manual。

若 .dbcli/verification/ 目錄不存在，回傳空結果並以 0 退出。list/summary 執行時會略過格式有誤的檔案（可透過 --include-invalid 及 summary 的無效計數觀察）；對格式有誤的檔案執行 show 時，會以 1 退出。

prune 預設為 dry-run。--keep-latest（預設 20）一律保護最新的 N 筆有效文物，範圍涵蓋所有 subject 與 status，且在套用 --status/--subject 篩選之前先行保護。只有同時帶上 --execute 與 --force 時才會刪除，且僅刪除 .dbcli/verification/ 內符合 verification-*.json 的一般檔案；execute 模式的表格輸出會逐一列出已刪除與略過的檔案。

dbcli verification summary --format json
dbcli verification list --status verified --subject backfill:safe-backfill-verify
dbcli verification show ver_abcd --format json
dbcli verification prune --older-than 30d --format json
dbcli verification prune --older-than 30d --keep-latest 20 --execute --force

evidence — 建立離線證據包

dbcli evidence 把既有 verification artifact 與 audit entry 收斂為可供審閱或交接的、工作區內 canonical JSON 證據包。它不連線資料庫，也不會把 SQL、target、audit metadata、verification summary 或憑證複製進包內。Claim 是外部提供的陳述，會被明確標示；它不是 dbcli 的驗證裁決。

• dbcli evidence compose --claims <file> [--verification <selector...>] [--audit <selector...>] [--receipt <path...>] --output <path> [--format json|markdown] — 解析既有參照並寫入新證據包。receipt 只記錄 provenance，不代表核准執行。claims JSON 只含 subject 與 claims；claim 文字不得含 SQL、憑證、錯誤內容或黑名單識別字。輸出必須留在目前工作區內，且不會覆寫既有檔案。
• dbcli evidence validate --file <path> [--format json|markdown] — 驗證 SHA-256 digest 與來源證據可用性。已保留的 pack 若對應 audit/artifact 之後輪替、清除或消失，回傳 references: "source-expired" 並以 1 退出，但仍可 render。
• dbcli evidence render --file <path> [--format json|markdown] — 驗證目前的黑名單政策後，不重讀原始參照就輸出有效 pack，因此來源保留期屆滿後仍可供歷史審閱。

dbcli evidence compose --claims ./claims.json --verification ver_abcd --audit 1a2b \
  --receipt .dbcli/evidence/verify-receipt.json \
  --output .dbcli/evidence/review.json
dbcli evidence validate --file .dbcli/evidence/review.json --format json
dbcli evidence render --file .dbcli/evidence/review.json

Artifact 格式版本

Pack 與 receipt 帶有自己的 version，那不是 dbcli 套件版本（見 ADR-0013）。目前格式為 version: 2；dbcli 3.0.0 以前寫出的是 version: 1，而且是兩種彼此不相容的結構。validate --format json 會在 status 回報三種答案之一，只有第一種代表這個 pack 可以採信。

舊格式的 pack 與 receipt 可讀、可驗 integrity，但永遠不會被當成 current-valid，而且沒有 migration：pack 的識別碼由 digest 推導而來，改寫它等於用舊 artifact 的來源憑證鑄造一份新的 artifact。需要目前格式時，請用現有證據重新 compose 一份。

dbcli proxy — 本機觀察型 Proxy

本機開發觀察型 Proxy — 將現有應用程式指向 Proxy 埠號，dbcli 便會將所有查詢轉發至真實資料庫，同時記錄查詢文字、延遲、位元組數、資料列數及錯誤事件。這不是正式環境閘道器。 僅限本機開發環境使用。

快速開始

# 明確指定上游 / 下游
dbcli proxy mysql --listen 127.0.0.1:3307 --target 127.0.0.1:3306
dbcli proxy postgresql --listen 127.0.0.1:5433 --target 127.0.0.1:5432

# 從具名連線推斷引擎與目標
dbcli --use local proxy --listen 127.0.0.1:3307

將應用程式的 DB host/port 改為 --listen 位址，憑證維持不變。Proxy 完全透明 — 應用程式的行為與直連相同。

選項

事件日誌（JSONL）

每筆完成的查詢會在事件日誌中附加一個 JSON 物件：

{"version":1,"type":"query_completed","timestamp":"2026-06-04T12:00:00.000Z","engine":"mysql","sessionId":"pxy_1","queryId":"qry_pxy_1_1","client":"127.0.0.1:54321","target":"127.0.0.1:3306","sql":"SELECT * FROM users WHERE id = ?","statement":"SELECT","tables":["users"],"durationMs":4,"requestBytes":42,"responseBytes":318,"rowCount":1,"error":null,"tags":[]}

隱私

SQL 文字一律儲存於事件日誌。結果資料列永不儲存。 使用 --redact literals 可在記錄前遮罩 SQL 中的字串與數字字面值（例如 WHERE id = ? 取代 WHERE id = 42）。

離線分析事件日誌

dbcli proxy analyze — 離線分析擷取的事件日誌（不連 DB）。--format json|text、--top、--slow-ms、--n-plus-one、--no-include-rotated。輸出總覽、各查詢指紋統計、最慢查詢、錯誤分群、熱點表、N+1 嫌疑。

每個可行動的區塊都附帶機器可讀的後續步驟，讓 AI agent 能從「診斷」直接推進到「修正」：

• SELECT 熱點 / N+1 — suggestedCommands 提供 dbcli explain "<sql>" 與 dbcli guide missing-index-for "<sql>"。
• 錯誤（errors） — suggestedCommands 提供 dbcli schema <table>（最多前 3 個表），並附 hints 提醒先核對表名/欄名再修正——切勿臆測欄名。
• N+1 嫌疑 — hints 建議將重複查詢批次化（JOIN / IN (...)）或快取結果。

建議流程：跑 proxy analyze 後，逐一針對每個發現讀其 hints、執行其 suggestedCommands 蒐集 schema/查詢計畫證據，再套用修正。text 格式會把這些彙整成 SUGGESTED COMMANDS 與 HINTS 區段；JSON 格式則把建議附在各發現上。建議僅以字串輸出——proxy analyze 不會自動執行。若 proxy 啟動時帶了 --redact literals，範例 SQL 會含 ? 佔位符；執行指令前請先填回真實值。

限制（v1）

• TLS：v1 不會解密 TLS。加密連線仍會產生 session 與位元組統計事件，但不會解析或顯示 SQL — 若需要查詢可見度，請在本機分析時停用 SSL。
• MySQL prepared/binary 協議：盡力解析；標記為 prepared_statement。
• PostgreSQL extended query 協議：盡力解析；標記為 extended_protocol 或 parse_partial。

QueryLens — Proxy 查詢分析

QueryLens 是 dbcli proxy analyze 的可分享 Markdown 報告格式，可將 proxy 事件日誌轉為本機查詢分析報告；它不是完整的資料庫協定分析器。

分析時不需要資料庫連線，也不需要 dbcli connection 設定：它只讀取磁碟上的 JSONL 檔案。QueryLens Markdown 報告會在分析前遮罩 SQL literal；擷取時也請使用 literal 遮罩，避免事件檔本身保留應用程式的值。

快速開始

# 1. 擷取已遮罩的本機開發流量 JSONL 日誌。
dbcli proxy mysql --listen 127.0.0.1:3307 --target 127.0.0.1:3306 \
  --events .dbcli/proxy/events.jsonl --redact literals

# 2. 在本機產生 QueryLens Markdown 報告；不會連線至資料庫。
dbcli proxy analyze \
  --events .dbcli/proxy/events.jsonl --format markdown

# 若要供其他工具或 CI 步驟使用，保留既有 proxy JSON 報告。
dbcli proxy analyze \
  --events .dbcli/proxy/events.jsonl --format json

執行應用程式時，將它指向 proxy 的 --listen 位址。停止 proxy 後，請在 repository root 對產生的日誌執行分析指令。

分析選項

QueryLens 只會分析它能讀取的 proxy 事件；請勿把結果視為已完整擷取所有資料庫協定或查詢形式的證據。將發現當作調查線索，修改正式程式碼前仍應確認查詢、schema 或執行計畫。

進階工具

dbcli semantic validate --format json
dbcli semantic context --format json
dbcli semantic search purchases --kind model --format json
dbcli semantic drift --format json
dbcli semantic migrate --to 2 --format json
dbcli skill context --format json

dbcli contract validate --format json
dbcli contract context --format json
dbcli contract search customer --format json
dbcli contract drift --format json

{
  "version": 1,
  "questionHash": "<原始問題的-sha256>",
  "candidate": { "kind": "sql", "sql": "<已檢閱的唯讀-sql>" },
  "semanticReferences": ["model:<model>", "field:<model>.<field>"]
}

# 只會寫入這個明確指定且不存在的路徑；請先編輯 starter 再驗證。
dbcli design init --output ./dbcli.design.json --dialect postgresql

# 兩個指令都離線且唯讀。
dbcli design validate --format json
dbcli design render --format mermaid
dbcli design diff --against-cache --format markdown
dbcli design diff --against-orm ./prisma/schema.prisma --format markdown
dbcli design propose --against-orm ./prisma/schema.prisma --format markdown

dbcli impact assess --design ./dbcli.design.json --against-cache --events ./.dbcli/proxy/events.jsonl --output ./impact.json --format json --fail-on warn
dbcli impact assess --design ./dbcli.design.json --against-orm ./prisma/schema.prisma --output ./impact.md --format markdown --fail-on never

📊 互動式 HTML 儀表板

在指令後加上 --ui 旗標，即可產生獨立的 React 報表並自動開啟。

dbcli query "SELECT day, count(*) FROM sessions" --ui

豐富的視覺化組件（圖表、KPI）可透過 Snippet frontmatter 中的 visual: 區塊進行設定。支援的圖表類型為 line、bar、area、pie 四種；指定其他類型會在解析時報錯。

當 dbcli 的 lookahead 證明結果遭截斷時，dashboard 會在所有 KPI、圖表與 table 之前顯示警示並標出實際上限；blacklist 的遮蔽／省略通知也會顯示在同一區域。query HTML/UI、saved-query HTML/UI 與 HTML export 只要執行路徑有產生對應 metadata，都會沿用此行為。

執行溯源（saved query）

由 saved query 產生的 dashboard（dbcli q @name --ui 或 --format html）會帶上獨立的 Execution Traceability 區塊，位置在截斷與 blacklist 通知之後、KPI／圖表／table 之前。它就存在 HTML 檔案裡，收檔的人不需要 dbcli、資料庫或你的工作目錄也看得到。

• Connection — 邏輯連線名稱：v2 的連線 key，單一連線設定則為 default。不會是主機或 endpoint。
• Engine — postgresql、mysql、mariadb、mongodb、redis 或 elasticsearch。
• Saved Query — Snippet key，例如 @dau。不會是檔案路徑。
• Snippet Source — builtin、shared 或 local。
• Effective Permission — 實際約束該次執行的權限：query-only、read-write、data-admin 或 admin。
• Applied Limit — 實際生效的筆數上限與是否截斷；若未套用上限，會明確寫出「No limit applied」而不是留白。

Applied Limit 一定與上方的截斷警示一致；兩者矛盾的 dashboard 會在寫檔前就被拒絕。

溯源是封閉契約，不會攜帶原始查詢內容、參數預設值或列舉、憑證、endpoint、來源路徑、verification 的 query 與 expects、目標 index 或 collection 名稱，也不會帶上未顯示的資料列。同一份 allowlist 管的是整個內嵌 payload，不只是看得見的那一區：只有已顯示的資料列、applied-limit 與安全通知、provenance 物件，以及顯示用的 name／description 與引用已顯示欄位的圖表／KPI 定義會被序列化。無效、超長或未知的 metadata 會在寫出任何 HTML 之前被拒絕，失敗的 dashboard 不會留下半成品檔案。

直接查詢產生的 dashboard（dbcli query --ui、dbcli export --format html）行為不變，不會有溯源區塊。

🤖 AI 代理整合

Dbcli 設計成 AI 代理的「資料庫驅動程式」：

• 機器可讀錯誤：JSON 格式的 --recovery 故障修復封包。
• 內容優化：--for-agent 旗標大幅減少 Token 消耗。
• 風險控制：dbcli plan 處理原生 SQL，insert / update / delete 的 --plan 旗標則在不連線資料庫的情況下對 DML 進行預檢。
• 專家任務包：針對診斷與稽核的引導式工作流。
• 稽核日誌 (Audit Log)：audit tail --for-agent 用於 session handoff；每個指令失敗時加上 --recovery 都會寫入互相對應的 audit.recovery_ref ↔ envelope.audit_ref UUID，agent 可透過 audit show --recovery-ref <id> 從 envelope 反查 audit entry。
• AI 協作提示注入：dbcli skill context 將連線資訊、schema 快取和儲存查詢序列化為高度壓縮且專門設計用於 AI 提示詞注入的 XML/Markdown/JSON 格式。
• 自我驗證循環：儲存的查詢片段支援定義 verify 斷言；在 q 執行時加上 --verify 即可自動化驗證。
• Agent Plugin：repo root 採用 Ponytail-style plugin layout，包含 .agents/plugins/marketplace.json、.codex-plugin/plugin.json、.claude-plugin/plugin.json、.cursor-plugin/plugin.json、.github/skills/dbcli/ 與 skills/dbcli/；若未全域安裝 dbcli，skill 會 fallback 到 bunx @carllee1983/dbcli <command>。Codex、Claude Code、GitHub Copilot CLI、Antigravity、Cursor 的安裝命令請見 plugins/dbcli-agent/INSTALL.md，其中包含提交 Cursor marketplace 審核/索引的步驟。
• 共用 agent CLI interface：套件使用者可從 @carllee1983/dbcli/agent-core 匯入 loadEnvFile、resolveEnvRef、resolveConnectionSelector、parseConnectionNames、trimAppliedLimit，以及 AppliedLimitMetadata、AppliedLimitResult、ConnectionSelectorInputs。此小型 interface 不相依 CLI framework 或資料庫並遵守 semver；較廣的 ./core 產品介面維持分離，CLI option factory、config storage binding 與連線字串解析刻意不納入 agent-core。

受限跨引擎 context（版本 2）

將資料庫 metadata 交給外部 agent 時，使用 dbcli skill context --context-version 2 --format json。版本 2 是穩定的 agent contract，離線執行，絕不開啟連線、建立 adapter、掃描 Redis key、讀取文件或讀取專案 source。Agent 可在自身 workspace safety rule 下自行檢查專案 code，以補足 context 未包含的業務意義。

dbcli skill context --context-version 2 --format json

將此輸出和 agent 自行安全發現的 code context 交給 agent；不要把 source path 交給 dbcli，也不要要求 dbcli 解讀自然語言。將 permission 與描述性的 capabilities 視為限制，不是執行指令的授權。只能使用回傳的 resources 與 approved semantic/contracts metadata。若 metadata 缺少或回傳 gaps，不可猜測名稱、type、relationship、key 或意義：檢查允許的 project code，或要求補上證據。

版本 2 只輸出 safe fields：已設定的 engine 與 permission、blacklist policy、capability 的 command/status/sideEffectTier、resource 與 field ID/name/type、可見 SQL nullable/primary-key 與可見 foreign-key link、flattened Elasticsearch field path/type、已宣告的 Redis family/field、沒有 body/default 的 snippet metadata、沒有 source path 的 declared data-access metadata、approved semantic/contracts metadata、truncation count 與 gap。它絕不輸出 credentials、value/result、default/count、raw Elasticsearch mapping 或 setting、Redis key/value、query body/default，或 project source path/content。Blacklisted identifier 只會出現在 blacklist。

Redis declaration 有意保持很小：context file ≤512 KiB；family ≤500；family name 為小寫 kebab-case，pattern ≤200 字元，含唯一且有效的 {placeholder}，不得有 glob token、空白、control character 或 backslash；type 為 string、hash、list、set、zset 或 stream。僅 hash 與 stream 可宣告 field（≤100）；description ≤1,000 字元，alias ≤20 個且每個 ≤100 字元。malformed、concrete、unsafe、blacklisted 或與 Redis field mask 重疊的 declaration 會直接失敗，不會輸出 partial model。

缺少 optional evidence 時會明確輸出：SQL_SCHEMA_UNAVAILABLE、ELASTICSEARCH_MAPPING_UNAVAILABLE、REDIS_KEY_FAMILIES_UNAVAILABLE、SEMANTIC_CONTEXT_UNAVAILABLE、SAVED_QUERIES_UNAVAILABLE、DATA_ACCESS_UNAVAILABLE 或 ALL_RESOURCES_FILTERED；truncation 另輸出 CONTEXT_TRUNCATED。已存在但無效的 evidence 會以相應的 INVALID_SCHEMA_CACHE、INVALID_SEMANTIC_CONTEXT、INVALID_SAVED_QUERY、INVALID_DATA_ACCESS_MANIFEST、INVALID_REDIS_CONTEXT 或 INVALID_RESOURCE_REFERENCE 失敗。MongoDB（及 unknown engine）明確要求 v2 時會回傳 UNSUPPORTED_CONTEXT_ENGINE。

省略 --context-version 時，維持 byte-compatible 的 version 1 JSON、XML 與 Markdown output。version 仍是 configuration metadata；v2 另加整數 contextVersion: 2。consumer 必須忽略未知的 optional v2 field；若要不相容地變更 required field 或 ID encoding，必須建立新的 context version。

業務請求的意圖確認

已安裝的 skill 支援三種當次請求的對話偏好，它們不是 dbcli 旗標或儲存的設定。Agent 不得先以「要不要讓我提問？」這類後設問題打斷使用者。

例如「查昨天的銷售資料」在結果形狀（總額或明細）、指標定義、時區、訂單狀態／退款處理、分組或連線未知時仍有歧義。Agent 應摘要候選解讀，只詢問會改變結果的問題。若使用者明確要求自行判斷、不要再問，agent 會以 auto 模式繼續並說明重要假設。這個偏好絕不繞過 blacklist、schema、permission、dry-run、production 選取或寫入確認閘門。

何時 dbcli 比 MCP database server 或直接 DB client 更合適

沒有任何一種工具永遠勝出。可信任的人員在可拋棄的本機環境做一次性變更時，直接使用資料庫 client 是最短路徑；Agent host 需要以工具形式進行低風險互動探索時，MCP database server 很有價值。當同一個資料庫任務必須讓 Agent、人員、CI 與 incident runbook 都能安全且可重現地執行時，dbcli 才是更合適的邊界。

即使只是本機 vibe coding

本機開發改變的是爆炸半徑，不是基本的失敗模式。在可隨時丟棄、只含合成資料的資料庫上，當你會逐條看著 SQL 執行時，直接使用 client 完全合理；它更快，因為 Agent 可以立刻連線、探索並執行臨時 SQL。

代價是 client session 本身成了完整的安全契約。Agent 仍可能猜錯欄位名稱、查詢到本機的 production dump、對仍要保留的 fixture 執行無範圍操作，或留下當工作移到 CI 時沒有人能重跑的變更。資料庫 client 可能有自己的保護功能，但它們不會自動成為專案其餘部分使用的同一份政策與工作流。

dbcli 在 Agent 操作前加入一個很小、但刻意的停頓：先檢查保護範圍、讀取真實 schema，再預覽寫入。這些指令同時也是交接用的 artifact。開發者能把同一組步驟貼到 terminal、測試 script 或 PR 說明中，而不必重建 Agent 擁有的 client session 裡發生了什麼。

dbcli blacklist list
dbcli schema <table> --format json
dbcli update <table> --where "<predicate>" --set '<json>' --dry-run

這不代表每一條本機 SELECT 都值得一套儀式。結果不會進入任何操作流程的可拋棄實驗，就用直接 client。只要 Agent 會碰到接近真實的資料、修改共享 fixture 或 migration、需要可重跑的答案，或工作很可能進到 CI、staging、production，就使用 dbcli。它的價值不在於讓本機開發神奇地安全，而在於清楚地把快速實驗轉換成可負責工作流的時機標示出來。

在最後一種情境中，dbcli 有四個實際優勢：

1. 操作者能審查並授權一次 invocation。 指令本身是具體交付物：執行前，人可以檢查選用連線、操作與 flags。像 Claude Code 這類可依 CLI 參數授權的 host，可形成實用的權限梯度——安全的探索指令能預先授權，查詢與寫入仍保留審查。MCP 權限通常以 tool 名稱為邊界；是否有更細的參數層級政策，取決於 host 與 server。
2. 相同 guardrail 不依賴 Agent 仍會執行。 權限分級、blacklist 檢查、結果筆數限制、schema 探索、dry-run 預檢與機器可讀輸出都在 CLI path 上。CI job 與 incident responder 可執行相同指令並得到同樣的防護，不必仰賴特定 editor 或 agent session。
3. 工作流會留下可操作的證據。 在支援的指令使用 --recovery，可產生結構化失敗封包並連結到 audit 紀錄。Saved queries 與 task packs 是團隊可 version、review、重用的檔案，而不是只存在聊天紀錄中的指示。
4. 沒有 Agent 時工具仍可使用。 Terminal、Makefile、CI job 或 runbook 都能以有意義的 exit code 執行指令。因此 dbcli 是耐久的操作介面，而不只是 AI 整合。

例如，Agent 協助資料變更的安全基線，仍是一組人員或 CI 可重跑的步驟：

dbcli blacklist list
dbcli schema <table> --format json
dbcli update <table> --where "<predicate>" --set '<json>' --dry-run

當 MCP server 的對話式介面是主要價值，且它的授權、日誌與執行模型滿足環境需求時，使用 MCP。當風險允許以簡單性為優先時，使用直接 client。真正重要的是受治理、可審查的執行路徑，而非僅僅送出一條 query 的能力時，選擇 dbcli。

安全邊界：dbcli 是 defence in depth，不是資料庫授權的替代品。給 Agent 的資料庫憑證必須遵循最小權限。能修改自己 dbcli 設定的 process 可以提高宣告權限或改用其他 client；blacklist 與 dry-run 單獨無法讓該憑證變得安全。