@carllee1983/dbcli 1.1.0 → 1.2.0

package/README.zh-TW.md

@@ -1,395 +1,643 @@
-# dbcli — 為 AI 代理的資料庫 CLI
+# dbcli — 為 AI 代理設計的資料庫 CLI
 
-[English](./README.md) | 繁體中文
+**語言：** [English](./README.md) | [繁體中文](./README.zh-TW.md)
 
-## 概述
+統一的資料庫 CLI 工具，讓 AI 代理（Claude Code、Gemini、Copilot、Cursor）能安全地查詢、探索與操作資料庫。
 
-dbcli 是一個統一的資料庫 CLI 工具，能讓 AI 代理（Claude Code、Gemini、Copilot、Cursor）安全地查詢、探索及操作資料庫。它扮演 AI 代理和多個資料庫系統（PostgreSQL、MySQL、MariaDB）之間的橋樑，簡化連接複雜度並強制實施基於權限的訪問控制。開發者每個專案初始化一次，之後 AI 代理就能智慧地與資料庫互動，無需手動架構探索或 SQL 語法知識。
+**核心價值：** AI 代理可透過單一、具權限控管的 CLI 工具，在敏感資料保護下安全且智慧地存取專案資料庫。
 
-## 核心價值
+## 國際化（i18n）
+
+dbcli 透過環境變數 `DBCLI_LANG` 支援多語系：
+
+```bash
+# 英文（預設）
+dbcli init
+
+# 繁體中文
+DBCLI_LANG=zh-TW dbcli init
+
+# 或在 .env 中設定
+export DBCLI_LANG=zh-TW
+dbcli init
+```
+
+**支援語言：**
+- `en` — English（預設）
+- `zh-TW` — 繁體中文（台灣）
+
+所有訊息、說明文字、錯誤訊息與指令輸出會依語言設定自動切換。
 
-**AI 代理能透過單一的、權限受控的 CLI 工具安全且智慧地訪問專案資料庫，並提供敏感資料保護。**
 
 ## 快速開始
 
 ### 安裝
 
-使用 Bun 安裝：
+#### 全域安裝（建議）
 
 ```bash
-bun add -D @carllee1983/dbcli
+npm install -g @carllee1983/dbcli
+# 或使用 Bun：bun install -g @carllee1983/dbcli
 ```
 
-或使用 npm：
+#### 免安裝（無需事先安裝）
 
 ```bash
-npm install --save-dev @carllee1983/dbcli
+npx @carllee1983/dbcli init
+npx @carllee1983/dbcli query "SELECT * FROM users"
+# 或使用 Bun：bunx @carllee1983/dbcli init
 ```
 
-### 更新
+#### 更新
 
 ```bash
-# 自動更新（推薦）
+# 自我更新（建議）
 dbcli upgrade
 
-# 或手動更新
-bun update @carllee1983/dbcli
+# 或透過 npm
+npm update -g @carllee1983/dbcli
 ```
 
-### 初始化
+#### 開發安裝
 
 ```bash
-# 交互式設定
-dbcli init
-
-# 或非交互模式
-dbcli init --host localhost --port 5432 --user postgres --password secret --name mydb --system postgresql
+git clone https://github.com/CarlLee1983/dbcli.git
+cd dbcli
+bun install
+bun run src/cli.ts -- --help
+# 或：bun run dev -- --help
 ```
 
-### 基本使用
+若 `dbcli` 未在 `PATH` 中，請使用 `bun run src/cli.ts <子指令> ...`（與 `bun run dev -- <子指令> ...` 相同）。
+
+### 第一步
 
 ```bash
-# 列出所有表
+# 以資料庫連線初始化專案
+dbcli init
+
+# 具備自動補全功能的互動式 Shell
+dbcli shell
+
+# 列出可用資料表
 dbcli list
 
-# 查看特定表的架構
+# 檢視資料表結構
 dbcli schema users
 
-# 執行查詢
-dbcli query "SELECT * FROM users LIMIT 10"
+# 查詢資料
+dbcli query "SELECT * FROM users"
+
+# 修改結構 (DDL)
+dbcli migrate create posts --column "id:int:pk" "title:varchar(100)"
 
-# 新增資料
-dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
+# 產生 AI 代理 skill
+dbcli skill --install claude
+```
 
-# 更新資料
-dbcli update users --where "id=1" --set '{"status":"active"}'
+---
 
-# 刪除資料（僅限 Admin）
-dbcli delete users --where "id=1" --force
+## 多重連線支援 (v2)
 
-# 導出結果
-dbcli export "SELECT * FROM users" --format json --output users.json
-```
+dbcli 支援在單一專案中管理多個具名的資料庫連線。這對於管理不同環境（開發、測試、正式）或多個資料庫非常有用。
 
-## 國際化
+### 初始化具名連線
 
-dbcli 支援多語言，可透過 `DBCLI_LANG` 環境變數控制：
+若要建立具名連線，請在 `init` 時使用 `--conn-name` 選項。您也可以為該連線指定自訂的 `.env` 檔案。
 
 ```bash
-# 英文（預設）
-dbcli init
-
-# 繁體中文
-DBCLI_LANG=zh-TW dbcli init
+# 使用 .env.staging 建立名為 staging 的連線
+dbcli init --conn-name staging --env-file .env.staging
 
-# 或在 .env 中設定
-export DBCLI_LANG=zh-TW
-dbcli init
+# 建立名為 prod 的正式環境連線，並使用環境變數引用
+dbcli init --conn-name prod --env-file .env.production --use-env-refs
 ```
 
-支援語言：
-- `en` — English（英文，預設）
-- `zh-TW` — 繁體中文（台灣）
+### 管理連線
 
-所有訊息、幫助文字和錯誤都會根據語言設定自動翻譯。
+使用 `dbcli use` 指令切換連線或列出所有連線。
 
-## 功能
+```bash
+# 列出所有連線（* 標記目前的預設值）
+dbcli use --list
 
-### 初始化與配置
+# 將預設連線切換至 'staging'
+dbcli use staging
 
-- `dbcli init` — 混合模式初始化（先讀取 .env，再提示缺少的值）
-- 支援混合資料庫系統配置（PostgreSQL、MySQL、MariaDB）
-- 自動解析專案 .env 檔案
-- 將配置儲存在 `.dbcli`（JSON 格式，按資料庫系統區分）
-- 定義粗粒度權限：Query-only / Read-Write / Admin
+# 顯示目前的預設連線
+dbcli use
 
-### 架構探索與存儲
+# 移除連線
+dbcli init --remove staging
 
-- `dbcli list` — 列出所有表
-- `dbcli schema [table]` — 檢查單個或所有表的架構
-- 自動生成 `.dbcli` 搭配表結構及關聯
-- 支援增量架構刷新
+# 重新命名連線
+dbcli init --rename staging:production
+```
 
-### 查詢操作
+### 臨時使用特定連線
 
-- `dbcli query "SELECT ..."` — 直接 SQL 查詢執行
-- 尊重權限等級（Query-only 模式拒絕寫入）
-- 返回結構化結果（便於 AI 解析）
-- 提供有用的錯誤訊息
+您可以使用 `--use <name>` 全域旗標，針對特定連線執行任一指令，而無需變更預設設定。
 
-### 資料修改（附帶安全措施）
+```bash
+# 針對正式資料庫執行一次查詢
+dbcli query "SELECT count(*) FROM users" --use prod
 
-- `dbcli insert [table]` — 插入資料（需要驗證，權限檢查）
-- `dbcli update [table]` — 更新資料（需要驗證，權限檢查）
-- `dbcli delete [table]` — 刪除資料（僅限 Admin）
-- 返回確認及受影響行數
+# 檢查測試環境資料表的健康狀態
+dbcli check users --use staging
+```
 
-### 導出
+---
 
-- `dbcli export "SELECT ..." [--format json|csv]` — 導出查詢結果
 
-### 資料存取控制（黑名單）
+#### `dbcli init`
 
-- `dbcli blacklist table add/remove <table>` — 封鎖或解除封鎖整個表
-- `dbcli blacklist column add/remove <table>.<column>` — 隱藏或顯示特定欄位
-- `dbcli blacklist list` — 查看目前黑名單設定
-- 欄位黑名單在查詢結果中自動省略，並顯示安全通知
-- 可透過 `DBCLI_OVERRIDE_BLACKLIST=true` 環境變數覆蓋（僅限管理員）
+以資料庫連線設定初始化新的 dbcli 專案。
 
-### AI 整合
+**用法：**
+```bash
+dbcli init [OPTIONS]
+```
 
-- 生成 dbcli 技能文檔（Claude Code 相容）
-- 支援跨平台 AI 代理使用（Claude Code、Gemini、Copilot CLI、Cursor、IDE）
-- 技能動態反映 dbcli 功能
+**選項 (基本)：**
+- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`
+- `--host <host>` — 主機
+- `--port <port>` — 埠號
+- `--user <user>` — 使用者
+- `--password <pass>` — 密碼
+- `--name <db>` — 資料庫名稱
+- `--permission <level>` — 權限等級：`query-only`、`read-write`、`data-admin`、`admin`
+- `--use-env-refs` — 在設定檔中儲存環境變數名稱參照，而非實際值
+- `--skip-test` — 略過連線測試
+- `--no-interactive` — 非互動模式（須提供所有必要選項）
+- `--force` — 覆寫既有設定且不詢問確認
+
+**選項 (多重連線 v2)：**
+- `--conn-name <name>` — 建立具名連線（例如 `staging`、`prod`）
+- `--env-file <path>` — 從指定的 `.env` 檔案載入此連線的憑證
+- `--remove <name>` — 從設定中移除具名連線
+- `--rename <old:new>` — 重新命名現有連線（格式：`舊名:新名`）
+**行為：**
+- 若存在 `.env` 會讀取（自動帶入 DATABASE_URL、DB_* 等變數）
+- 缺少的欄位會互動提示（主機、埠、使用者、密碼、資料庫名、權限等級）
+- 在專案根目錄建立 `.dbcli` JSON 設定檔
+- 儲存前會測試資料庫連線
+
+**範例：**
+```bash
+# 互動式初始化
+dbcli init
 
-### 診斷與維護
+# 多重連線設定
+dbcli init --conn-name staging --env-file .env.staging
+dbcli init --conn-name prod --env-file .env.production --use-env-refs
 
-- `dbcli doctor` — 執行環境、設定、連線與資料的全面診斷
-- `dbcli upgrade` — 檢查更新並自動升級 dbcli
-- `dbcli completion [shell]` — 產生 shell 自動補全腳本（bash、zsh、fish）
+# 儲存環境變數參照（非互動）
+dbcli init --use-env-refs --system mysql \
+  --env-host DB_HOST --env-port DB_PORT \
+  --env-user DB_USER --env-password DB_PASSWORD \
+  --env-database DB_DATABASE \
+  --no-interactive
+```
 
-## 權限模型
+---
 
-dbcli 使用三層粗粒度權限模型，並搭配黑名單系統提供敏感表和欄位的細粒度保護（見[資料存取控制](#資料存取控制)）：
+#### `dbcli use` (需要 v2 設定)
 
-### 1. Query-only（查詢只讀）
+在多重連線專案中管理或切換預設資料庫連線。
 
-可用命令：
-- `dbcli list` — 列出表
-- `dbcli schema [table]` — 查看架構
-- `dbcli query "SELECT ..."` — 查詢
+**用法：**
+```bash
+dbcli use [連線名稱] [選項]
+```
 
-限制：
-- 寫入操作（INSERT、UPDATE、DELETE）被拒絕
-- 查詢自動限制為 1000 行（防止意外全表掃描）
+**選項：**
+- `--list` — 列出所有連線並顯示目前的預設值
 
-### 2. Read-Write（讀寫）
+**範例：**
+```bash
+# 顯示目前的預設連線
+dbcli use
 
-可用命令：
-- Query-only 的所有命令
-- `dbcli insert` — 插入資料
-- `dbcli update` — 更新資料
+# 將預設連線切換至 'prod'
+dbcli use prod
 
-限制：
-- DELETE 被拒絕（需要 Admin）
-- Insert/Update 需要確認（除非 `--force`）
+# 列出所有連線
+dbcli use --list
+```
 
-### 3. Admin（管理員）
+---
 
-完全訪問：
-- 所有讀寫操作
-- DELETE 無限制
-- 可跳過確認（`--force`）
+> **`--use-env-refs`：** 啟用後，設定檔會儲存環境變數名稱（例如 `{"$env": "DB_HOST"}`）而非實際值，避免將憑證寫入檔案，適合多環境與 CI/CD。連線時 dbcli 會自動從對應環境變數讀取實際值。
 
-## 資料存取控制
+---
 
-dbcli 提供黑名單系統，與權限模型協同運作，防止 AI 代理存取敏感表或欄位，無論其權限等級為何。
+#### `dbcli list`
 
-### 表層級黑名單
+列出已連線資料庫中的所有資料表。
+
+**用法：**
+```bash
+dbcli list [OPTIONS]
+```
 
-封鎖表後，所有操作（查詢、插入、更新、刪除）均會被拒絕，並顯示明確的錯誤訊息。
+**選項：**
+- `--format json` — 以 JSON 輸出，而非 ASCII 表格
 
+**範例：**
 ```bash
-dbcli blacklist table add secrets_vault
-dbcli query "SELECT * FROM secrets_vault"
-# 錯誤：表 'secrets_vault' 已被列入黑名單
+# 表格（人類可讀）
+dbcli list
+
+# JSON（供 AI 解析）
+dbcli list --format json
+
+# 串接工具
+dbcli list --format json | jq '.data[].name'
 ```
 
-### 欄位層級黑名單
+---
 
-黑名單欄位會從 SELECT 結果中自動省略，並在輸出中顯示安全通知，讓 AI 代理了解結果集已被過濾。
+#### `dbcli schema [table]`
 
+顯示資料表結構（欄位、型別、限制、外鍵）。
+
+**用法：**
 ```bash
-dbcli blacklist column add users.password_hash
-dbcli query "SELECT * FROM users"
-# [安全通知] 已省略黑名單欄位：password_hash
+dbcli schema [table]
+dbcli schema                 # 掃描整個資料庫並更新 .dbcli
+dbcli schema users           # 顯示 `users` 表結構
 ```
 
-### 黑名單配置範例
+**選項：**
+- `--format json` — JSON 輸出
+- `--refresh` — 偵測並增量更新 schema 變更（需 `--force` 核准）
+- `--reset` — 清除既有 schema 並自資料庫重新抓取（切換連線後適用）
+- `--force` — 重新整理／覆寫／重置時略過確認
 
-黑名單規則儲存在 `.dbcli` 配置檔案中：
+**範例：**
+```bash
+# 顯示 users 表結構
+dbcli schema users
 
-```json
-{
-  "blacklist": {
-    "tables": ["audit_logs", "secrets_vault"],
-    "columns": {
-      "users": ["password_hash", "ssn"]
-    }
-  }
-}
+# JSON 與完整中繼資料
+dbcli schema users --format json
+
+# 增量更新 schema（新表等）
+dbcli schema --refresh --force
+
+# 清空後全量重抓（切換 DB 後）
+dbcli schema --reset --force
+
+# 掃描整個資料庫
+dbcli schema
 ```
 
-### 覆蓋黑名單
+---
+
+#### `dbcli query "SQL"`
 
-管理員可透過環境變數在緊急情況下繞過黑名單：
+執行 SQL 查詢並回傳結果。
 
+**用法：**
 ```bash
-DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
+dbcli query "SELECT * FROM users"
 ```
 
-## 常見命令
+**選項：**
+- `--format json|table|csv` — 輸出格式（預設：table）
+- `--limit <數字>` — 限制列數（覆寫 query-only 下的自動上限）
+- `--no-limit` — 在 query-only 模式下關閉自動 1000 列上限
 
-### 初始化
+**行為：**
+- 依權限限制操作（Query-only 會阻擋 INSERT/UPDATE/DELETE）
+- Query-only 模式預設自動限制最多 1000 列（並顯示提示），除非使用 `--no-limit` 或 `--limit`
+- 回傳含中繼資料的結構化結果（列數、執行時間等）
+- 若要將 CSV／JSON 寫入檔案，請用 shell 重新導向或 `export` 指令
 
+**範例：**
 ```bash
-dbcli init
-# 提示：主機、埠口、用戶、密碼、資料庫名稱、權限級別
+# 表格輸出
+dbcli query "SELECT * FROM users"
 
-dbcli init --host db.example.com --port 5432 --user admin --password secret --name prod_db --system postgresql
-# 非交互式初始化
+# JSON
+dbcli query "SELECT * FROM users" --format json
 
-dbcli init --use-env-refs
-# 交互式：提示輸入環境變數名稱，config 中儲存 {"$env": "DB_HOST"} 而非實際值
+# CSV 輸出至 stdout（重新導向成檔案）
+dbcli query "SELECT * FROM users" --format csv > users.csv
 
-dbcli init --use-env-refs --system mysql \
-  --env-host DB_HOST --env-port DB_PORT \
-  --env-user DB_USER --env-password DB_PASSWORD \
-  --env-database DB_DATABASE --no-interactive
-# 非交互式環境變數參照模式，適合 CI/CD
+# 串接其他工具
+dbcli query "SELECT * FROM products" --format json | jq '.data[] | .name'
+
+# 大量結果（以 LIMIT/OFFSET 分頁）
+dbcli query "SELECT * FROM users LIMIT 100 OFFSET 0"
 ```
 
-> **`--use-env-refs` 說明：** 使用此選項時，config 中儲存的是環境變數名稱（如 `{"$env": "DB_HOST"}`）而非實際值。這樣可以避免將敏感資訊寫入 config 檔案，適合多環境部署或 CI/CD 場景。連線時 dbcli 會自動從環境變數讀取實際值。
+---
 
-### 列出表
+#### `dbcli insert [table]`（需要 Read-Write 或 Admin 權限）
 
-```bash
-dbcli list
-# 以表格輸出
-# ┌─────────┬──────────┬────────┐
-# │ Table   │ Rows     │ Engine │
-# ├─────────┼──────────┼────────┤
-# │ users   │ 1,250    │ InnoDB │
-# │ posts   │ 8,431    │ InnoDB │
-# └─────────┴──────────┴────────┘
+插入資料列。
 
-dbcli list --format json
-# 以 JSON 輸出
+**用法：**
+```bash
+dbcli insert users --data '{"name": "Alice", "email": "alice@example.com"}'
 ```
 
-### 查看架構
+**選項：**
+- `--data JSON` — 資料列 JSON 物件（**必填**）
+- `--dry-run` — 僅顯示 SQL，不執行
+- `--force` — 略過確認
+
+**行為：**
+- 驗證 JSON 格式
+- 產生參數化 SQL（降低 SQL 注入風險）
+- 插入前顯示確認（除非使用 `--force`）
 
+**範例：**
 ```bash
-dbcli schema users
-# 列出 users 表的欄位、型別、約束
+# 插入一列
+dbcli insert users --data '{"name": "Bob", "email": "bob@example.com"}'
 
-dbcli schema
-# 掃描整個資料庫架構
+# 預覽 SQL
+dbcli insert users --data '{"name": "Charlie"}' --dry-run
 
-dbcli schema --refresh --force
-# 檢測並應用架構變更（增量）
+# 略過確認
+dbcli insert users --data '{"name": "Diana"}' --force
+```
 
-dbcli schema --reset --force
-# 清空舊 schema 並重新從 DB 抓取（切換 DB 後使用）
+---
+
+#### `dbcli update [table]`（需要 Read-Write 或 Admin 權限）
+
+更新既有資料列。
+
+**用法：**
+```bash
+dbcli update users --where "id=1" --set '{"name": "Alice Updated"}'
 ```
 
-### 執行查詢
+**選項：**
+- `--where condition` — WHERE 條件（**必填**，例如 `"id=1 AND status='active'"`）
+- `--set JSON` — 要更新的欄位 JSON（**必填**）
+- `--dry-run` — 僅顯示 SQL
+- `--force` — 略過確認
 
+**範例：**
 ```bash
-dbcli query "SELECT id, name FROM users WHERE active = true"
+# 更新單列
+dbcli update users --where "id=1" --set '{"name": "Alice"}'
 
-dbcli query "SELECT * FROM posts" --format json
-# 以 JSON 輸出
+# 更新多列
+dbcli update users --where "status='inactive'" --set '{"status":"active"}'
 
-dbcli query "SELECT * FROM large_table" --limit 100
-# 限制行數
+# 預覽 SQL
+dbcli update users --where "id=1" --set '{"name": "Bob"}' --dry-run
 
-dbcli query "SELECT * FROM large_table" --no-limit
-# 停用自動限制（Query-only 模式下需要 `--force`）
+# 略過確認
+dbcli update users --where "id=2" --set '{"email": "new@example.com"}' --force
 ```
 
-### 插入資料
+---
 
-```bash
-dbcli insert users --data '{"name":"Bob","email":"bob@example.com"}'
+#### `dbcli delete [table]`（需要 Data-Admin 或 Admin 權限）
 
-echo '{"name":"Charlie","email":"charlie@example.com"}' | dbcli insert users
+刪除資料列（query-only 與 read-write 不可用；需較高 DML 權限）。
 
-dbcli insert users --data '{"name":"David","email":"david@example.com"}' --force
-# 跳過確認提示
+**用法：**
+```bash
+dbcli delete users --where "id=1" --force
 ```
 
-### 更新資料
+**選項：**
+- `--where condition` — WHERE 條件（**必填**）
+- `--dry-run` — 僅顯示 SQL
+- `--force` — 實際刪除時必填（安全閘門）
 
+**範例：**
 ```bash
-dbcli update users --where "id=1" --set '{"status":"active"}'
+# 刪除單列（須 `--force`）
+dbcli delete users --where "id=1" --force
 
-dbcli update posts --where "author_id=5" --set '{"updated_at":"2026-03-26"}'
+# 預覽刪除
+dbcli delete products --where "status='deprecated'" --dry-run
 
-dbcli update users --where "id=1" --set '{"name":"Updated"}' --dry-run
-# 顯示 SQL 但不執行
+# 刪除多列
+dbcli delete orders --where "created_at < '2020-01-01'" --force
 ```
 
-### 刪除資料
+---
 
-```bash
-# 僅限 Admin 權限
-dbcli delete users --where "id=1"
+#### `dbcli export "SQL"`
 
-dbcli delete users --where "status='inactive'" --force
-# 跳過確認提示
+將查詢結果匯出至檔案。
+
+**用法：**
+```bash
+dbcli export "SELECT * FROM users" --format json --output users.json
 ```
 
-### 導出資料
+**選項：**
+- `--format json|csv` — 輸出格式
+- `--output file` — 寫入檔案（預設 stdout 供管道使用）
 
+**行為：**
+- Query-only 權限下每次匯出最多 1000 列
+- 產生符合 RFC 4180 的 CSV
+- 產生結構良好的 JSON 陣列
+
+**範例：**
 ```bash
+# 匯出 JSON
 dbcli export "SELECT * FROM users" --format json --output users.json
 
-dbcli export "SELECT id, name FROM posts" --format csv > posts.csv
+# 匯出 CSV
+dbcli export "SELECT * FROM orders" --format csv --output orders.csv
+
+# 管道壓縮
+dbcli export "SELECT * FROM products" --format csv | gzip > products.csv.gz
+
+# 搭配 jq
+dbcli export "SELECT * FROM users WHERE active=true" --format json | jq '.data | length'
 ```
 
-### 生成技能
+---
+
+#### `dbcli skill`
+
+產生或安裝 AI 代理 skill 說明文件。
 
+**用法：**
 ```bash
-dbcli skill
-# 輸出到標準輸出（用於管道傳輸）
+dbcli skill                           # 輸出至 stdout
+dbcli skill --output SKILL.md         # 寫入檔案
+dbcli skill --install claude          # 安裝至 Claude Code 設定
+dbcli skill --install gemini          # 安裝至 Gemini CLI
+dbcli skill --install copilot         # 安裝至 GitHub Copilot
+dbcli skill --install cursor          # 安裝至 Cursor IDE
+```
 
-dbcli skill --output ./SKILL.md
-# 寫入檔案
+**行為：**
+- 依 CLI 內省動態產生 SKILL.md
+- 依權限等級過濾指令（Query-only 會隱藏寫入類指令）
+- 支援 stdout、檔案、各平台安裝等輸出方式
 
+**範例：**
+```bash
+# 為 Claude Code 產生 skill
 dbcli skill --install claude
-# 安裝至 Claude Code 技能目錄
+
+# 手動產生文件
+dbcli skill > ./docs/SKILL.md
+
+# 檢視產生的 skill（stdout）
+dbcli skill
+
+# 為多平台安裝
+dbcli skill --install claude && \
+dbcli skill --install gemini && \
+dbcli skill --install copilot && \
+dbcli skill --install cursor
 ```
 
-### 管理黑名單
+---
+
+#### `dbcli blacklist`
 
+管理資料存取黑名單，阻擋 AI 代理存取敏感資料表或欄位。
+
+**用法：**
 ```bash
-# 查看目前黑名單
 dbcli blacklist list
+dbcli blacklist table add <table>
+dbcli blacklist table remove <table>
+dbcli blacklist column add <table>.<column>
+dbcli blacklist column remove <table>.<column>
+```
+
+**子指令：**
 
-# 封鎖整個表
+| 子指令 | 說明 |
+|--------|------|
+| `dbcli blacklist list` | 顯示目前黑名單（表與欄位） |
+| `dbcli blacklist table add <table>` | 將表加入黑名單（阻擋所有操作） |
+| `dbcli blacklist table remove <table>` | 從黑名單移除表 |
+| `dbcli blacklist column add <table>.<column>` | 將欄位加入黑名單（SELECT 結果中省略） |
+| `dbcli blacklist column remove <table>.<column>` | 從黑名單移除欄位 |
+
+**行為：**
+- 表黑名單會阻擋該表所有操作（query、insert、update、delete）
+- 欄位黑名單會從 SELECT 結果中靜默省略欄位，並顯示安全通知
+- 規則存在 `.dbcli`，適用於所有權限等級
+- 管理員可透過環境變數 `DBCLI_OVERRIDE_BLACKLIST=true` 覆蓋
+
+**範例：**
+```bash
+# 檢視黑名單
+dbcli blacklist list
+
+# 封鎖敏感表
 dbcli blacklist table add audit_logs
 dbcli blacklist table add secrets_vault
 
-# 從黑名單移除表
-dbcli blacklist table remove audit_logs
-
-# 隱藏敏感欄位
+# 在查詢結果中隱藏敏感欄位
 dbcli blacklist column add users.password_hash
 dbcli blacklist column add users.ssn
 
-# 從黑名單移除欄位
+# 移除表黑名單
+dbcli blacklist table remove audit_logs
+
+# 移除欄位黑名單
 dbcli blacklist column remove users.ssn
 
-# 管理員覆蓋黑名單（緊急使用）
+# 覆蓋黑名單（僅管理用途）
 DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
 ```
 
+---
+
+#### `dbcli check`
+
+執行資料品質與健康檢查。
+
+**用法：**
+```bash
+dbcli check [資料表] [選項]
+```
+
+**選項：**
+- `--all` — 檢查所有表（預設略過極大表，除非加 `--include-large`）
+- `--include-large` — 與 `--all` 一併使用時一併檢查極大表
+- `--checks <類型>` — 逗號分隔：`nulls`、`duplicates`、`orphans`、`emptyStrings`、`rowCount`、`size`
+- `--sample <數字>` — 大表取樣列數（預設：`10000`）
+- `--format json|table` — 輸出格式（預設：`json`）
+
+**範例：**
+```bash
+# 檢查 users 表
+dbcli check users
+
+# 僅執行特定檢查
+dbcli check orders --checks nulls,orphans --format table
+
+# 掃描所有資料表
+dbcli check --all
+```
+
+---
+
+#### `dbcli diff`
+
+儲存 schema 快照，或將目前資料庫與先前快照比對（表、欄位、索引）。
+
+**用法：**
+```bash
+dbcli diff --snapshot ./schema-before.json
+dbcli diff --against ./schema-before.json
+dbcli diff --against ./schema-before.json --format table
+```
+
+**選項：**
+- `--snapshot <path>` — 將目前 schema 寫入 JSON 檔
+- `--against <path>` — 與已存快照比對差異
+- `--format json|table` — 輸出格式（預設：`json`）
+- `--config <path>` — 設定路徑（預設：`.dbcli`）
+
+---
+
+#### `dbcli status`
+
+顯示不含連線憑證的設定摘要（權限、資料庫系統、黑名單筆數、設定中繼版本），適合提供給 AI 代理。
+
+**用法：**
+```bash
+dbcli status
+dbcli status --format text
+dbcli status --format json
+```
+
+**選項：**
+- `--format text|json` — 輸出格式（預設：`json`）
+
+**注意：** 此指令固定讀取專案預設路徑 `.dbcli`（不使用全域 `--config` 旗標）。
+
+---
+
 #### `dbcli doctor`
 
-執行環境、設定、連線與資料的全面診斷。
+對環境、設定、連線與資料執行診斷檢查。
 
 ```bash
 dbcli doctor                    # 彩色文字輸出
-dbcli doctor --format json      # JSON 輸出供 AI agent 使用
+dbcli doctor --format json      # JSON 輸出（供 AI 代理）
 ```
 
 **檢查項目：**
 - **環境：** Bun 版本相容性、dbcli 版本（與 npm registry 比對）
-- **設定：** 設定檔存在/合法、權限等級、blacklist 完整性
-- **連線與資料：** 資料庫連線測試、schema cache 新鮮度（> 7 天警告）、大表警告（> 1M 列）
+- **設定：** 設定檔是否存在／有效、權限等級、黑名單完整性
+- **連線與資料：** 資料庫連線、schema 快取新鮮度（超過 7 天警告）、大表警告（超過 100 萬列）
 
-**選項：** `--format <text|json>`
+**選項：** `--format <text|json>`  
+**結束代碼：** 0 = 全部通過或僅警告，1 = 有錯誤
 
 ---
 
@@ -398,10 +646,10 @@ dbcli doctor --format json      # JSON 輸出供 AI agent 使用
 產生 shell 自動補全腳本。
 
 ```bash
-dbcli completion bash            # 輸出 bash 補全腳本
-dbcli completion zsh             # 輸出 zsh 補全腳本
-dbcli completion fish            # 輸出 fish 補全腳本
-dbcli completion --install       # 自動偵測 shell 並安裝
+dbcli completion bash            # bash 補全輸出至 stdout
+dbcli completion zsh             # zsh
+dbcli completion fish            # fish
+dbcli completion --install       # 自動偵測 shell 並寫入 rc
 dbcli completion --install zsh   # 指定 shell 安裝
 ```
 
@@ -411,203 +659,568 @@ dbcli completion --install zsh   # 指定 shell 安裝
 
 #### `dbcli upgrade`
 
-檢查更新並自動升級 dbcli。
+檢查更新並自我升級 dbcli。
+
+```bash
+dbcli upgrade                   # 有新版則升級
+dbcli upgrade --check           # 僅檢查，不安裝
+```
+
+**選項：** `--check` — 只檢查，不安裝  
+**背景檢查：** dbcli 每 24 小時會靜默查詢 npm registry 一次；若有新版，會在指令輸出結束後顯示提示。
+
+#### `dbcli shell`
 
+互動式資料庫 shell：執行 SQL、自動補全、語法高亮。
+
+**用法：**
 ```bash
-dbcli upgrade                   # 檢查並升級
-dbcli upgrade --check           # 僅檢查，不升級
+dbcli shell          # 互動模式（SQL + dbcli 指令）
+dbcli shell --sql    # 僅 SQL 模式
 ```
 
-**背景檢查：** 每個指令靜默檢查 npm registry（每 24 小時一次），有新版時在指令完成後顯示提示。
+**Shell 內：**
+- 以 `;` 結尾的 SQL 會執行
+- 可輸入 dbcli 子指令且不需 `dbcli` 前綴（例如 `schema users`、`list`）
+- Tab 可觸發情境式補全（SQL 關鍵字、表／欄位名）
+- `.help` 可查看 meta 指令（`.quit`、`.clear`、`.format`、`.history`、`.timing`）
+- 多行 SQL：輸入會累積直到出現 `;`
+- 歷史記錄跨工作階段保存在 `~/.dbcli_history`
+
+**權限：** 繼承設定檔；SQL 與子指令皆受權限／黑名單約束。
+
+#### `dbcli migrate`
+
+Schema DDL 操作。**所有子指令預設為 dry-run** — 實際執行 SQL 請加 `--execute`。
+
+**用法：**
+```bash
+# 建立表
+dbcli migrate create posts \
+  --column "id:serial:pk" \
+  --column "title:varchar(200):not-null" \
+  --column "body:text" \
+  --column "created_at:timestamp:default=now()"
+
+# 執行（真正跑 SQL）
+dbcli migrate create posts --column "id:serial:pk" --execute
+
+# 刪表（破壞性 — 需 `--execute --force`）
+dbcli migrate drop posts --execute --force
+
+# 欄位操作
+dbcli migrate add-column users bio text --nullable --execute
+dbcli migrate alter-column users name --type "varchar(200)" --execute
+dbcli migrate alter-column users email --rename user_email --execute
+dbcli migrate drop-column users temp_field --execute --force
+
+# 索引
+dbcli migrate add-index users --columns email --unique --execute
+dbcli migrate drop-index idx_users_email --table users --execute --force
+
+# 限制條件
+dbcli migrate add-constraint orders --fk user_id --references users.id --on-delete cascade --execute
+dbcli migrate add-constraint users --unique email --execute
+dbcli migrate add-constraint users --check "age >= 0" --execute
+dbcli migrate drop-constraint orders fk_orders_user_id --execute --force
+
+# 列舉型別（僅 PostgreSQL）
+dbcli migrate add-enum status active inactive suspended --execute
+dbcli migrate alter-enum status --add-value archived --execute
+dbcli migrate drop-enum status --execute --force
+```
+
+**欄位規格格式：** `name:type[:modifier...]` — 修飾子：`pk`、`not-null`、`unique`、`auto-increment`、`default=<value>`、`references=<table>.<column>`
+
+**選項（各子指令）：** `--execute`（執行 SQL）、`--force`（DROP 時略過確認）、`--config <path>`  
+**權限：** 僅 admin
+
+---
 
 ## 全域選項
 
-以下選項適用於所有指令：
+所有指令皆支援下列全域選項：
 
-| 選項 | 說明 |
+| 旗標 | 說明 |
 |------|------|
-| `--config <path>` | 指定 .dbcli 設定檔路徑（預設：`.dbcli`） |
-| `-v, --verbose` | 增加輸出詳細度（`-v` 詳細、`-vv` 除錯） |
-| `-q, --quiet` | 靜音模式，抑制非必要輸出 |
-| `--no-color` | 關閉彩色輸出（支援 `NO_COLOR` 環境變數） |
+| `--config <path>` | `.dbcli` 設定檔路徑（預設：`.dbcli`） |
+| `-v, --verbose` | 提高詳細度（`-v` 詳細、`-vv` 除錯） |
+| `-q, --quiet` | 抑制非必要輸出 |
+| `--no-color` | 關閉彩色輸出（亦遵守 `NO_COLOR` 環境變數） |
+
+---
+
+## 內部機制與策略
+
+### Schema 更新策略
+
+dbcli 會在您的 `.dbcli` 設定檔中維護一份 Schema 快照。這讓 AI 代理無需頻繁連網即可理解資料庫結構。了解此快取何時更新至關重要：
+
+1.  **手動更新：**
+    *   `dbcli schema`：執行全量資料庫掃描。
+    *   `dbcli schema --refresh`：增量更新。偵測變更並僅更新受影響的資料表。
+    *   `dbcli schema --reset`：清除快取並重新抓取所有內容。
+2.  **自動更新 (DDL)：**
+    *   當您透過 `dbcli migrate` 執行 DDL 指令（例如 `add-column`）時，CLI 會在成功執行後自動重新掃描該資料表，並更新 `.dbcli` 中的快照。
+3.  **即時驗證（不存入快取）：**
+    *   `insert`、`update`、`delete` 與 `check` 等指令在執行前會立即從資料庫抓取最新 Schema 以確保資料完整性，但它們**不會**更新 `.dbcli` 中的長期快照。
+
+> **注意：** 若您使用外部工具（如 DBeaver 或遷移腳本）變更資料庫結構，您**必須**執行 `dbcli schema --refresh` 同步快照，AI 代理才能看到變更。
+
+### `dbcli migrate` 的原理
+
+`migrate` 指令遵循嚴格的安全流程，以防止意外損壞資料庫：
+
+1.  **權限檢查：** 驗證使用者是否具備 `admin` 權限。其他等級皆無法執行 DDL。
+2.  **黑名單檢查：** 確保操作目標未包含在安全黑名單中。
+3.  **資料庫方言生成：** `DDLGenerator` 會根據您的系統將請求轉換為正確的 SQL：
+    *   **PostgreSQL：** 使用 `SERIAL`、原生 `ENUM` 型別以及雙引號識別字。
+    *   **MySQL/MariaDB：** 使用 `AUTO_INCREMENT`、行內 `ENUM` 定義以及反引號識別字。
+4.  **測試執行 (預設)：** 所有指令預設僅輸出產生的 SQL 供審核，不實際執行。
+5.  **執行與確認：**
+    *   需要加上 `--execute` 旗標才會執行。
+    *   破壞性操作（如 `drop`）需要同時具備 `--execute` 與 `--force`。
+6.  **快照同步：** 成功執行後，會自動觸發該資料表的 Schema 更新，保持 `.dbcli` 檔案為最新狀態。
+
+---
+
+## 權限模型
+
+dbcli 採用粗粒度權限系統，共四個等級。權限在 `dbcli init` 時設定並存於 `.dbcli`。黑名單與權限並行，針對敏感表與欄位提供細部保護（見[資料存取控制](#資料存取控制)）。
+
+### 權限等級
+
+| 等級 | 允許的指令 | 阻擋的指令 | 適用情境 |
+|------|------------|------------|----------|
+| **Query-only** | `init`、`list`、`schema`、`query`、`export`（最多 1000 列） | `insert`、`update`、`delete`、`migrate` | 唯讀 AI 代理、分析、報表 |
+| **Read-Write** | 另含 `insert`、`update` | `delete`、`migrate` | 應用開發、內容管理 |
+| **Data-Admin** | 另含 `delete` | `migrate` | 完整 DML，無 DDL |
+| **Admin** | 含 `migrate`（DDL）在內的全部指令 | — | DBA、結構變更 |
 
-## 環境配置
+### 設定
 
-### .dbcli 配置檔案
+權限在初始化時設定：
 
-初始化後，dbcli 會創建 `.dbcli` 檔案：
+```bash
+dbcli init
+# 提示：權限等級（query-only / read-write / data-admin / admin）
+# 儲存於專案 .dbcli/config.json： "permission": "query-only"
+```
+
+### 依權限的範例
+
+#### Query-only 模式（AI 代理）
+```bash
+# 允許：讀取
+dbcli query "SELECT * FROM users"
+dbcli schema users
+dbcli export "SELECT * FROM orders" --format json
+
+# 阻擋：寫入
+dbcli insert users --data '{...}'  # 錯誤：權限不足
+dbcli delete users --where "id=1"  # 錯誤：權限不足
+```
+
+#### Read-Write 模式（應用開發者）
+```bash
+# 允許：讀寫
+dbcli query "SELECT * FROM users"
+dbcli insert users --data '{"name": "Alice"}'
+dbcli update users --where "id=1" --set '{"name": "Bob"}'
+
+# 阻擋：刪除（須 data-admin 或 admin）
+dbcli delete users --where "id=1"  # 錯誤：read-write 無法執行 DELETE
+```
+
+#### Admin 模式（資料庫管理員）
+```bash
+# 允許：含 DDL 在內的全部操作
+dbcli query "SELECT * FROM users"
+dbcli insert users --data '{"name": "Eve"}'
+dbcli update users --where "id=1" --set '{"status": "active"}'
+dbcli delete users --where "id=1" --force  # Data-Admin 以上可刪除
+dbcli migrate create posts --column "id:serial:pk" --execute  # 僅 Admin
+```
+
+### 最佳實踐
+
+- **AI 代理：** 唯讀情境使用 Query-only，降低誤刪／誤改風險
+- **應用程式：** 一般 CRUD 使用 Read-Write，避免誤執行 DROP TABLE
+- **維運：** 僅在結構變更、大量刪除或緊急處理時使用 Admin
+- **最小權限：** 依實際需求給予最低足夠的權限等級
+
+---
+
+## 資料存取控制
+
+黑名單與權限模型搭配，防止 AI 代理存取敏感表或欄位，不受其權限等級影響。
+
+### 表層級黑名單
+
+封鎖表後，查詢、插入、更新、刪除皆會被拒絕，並顯示明確錯誤。
+
+```bash
+dbcli blacklist table add secrets_vault
+
+dbcli query "SELECT * FROM secrets_vault"
+# 錯誤：表 'secrets_vault' 已列入黑名單
+```
+
+### 欄位層級黑名單
+
+黑名單欄位會從 SELECT 結果中省略，輸出中會附安全通知，讓代理知道結果已被過濾。
+
+```bash
+dbcli blacklist column add users.password_hash
+dbcli blacklist column add users.ssn
+
+dbcli query "SELECT * FROM users"
+# [Security] Columns omitted by blacklist: password_hash, ssn
+```
+
+### 安全通知
+
+當黑名單過濾查詢輸出時，dbcli 會在結果中附加通知列，避免代理在不知情下依不完整資料決策。
+
+### 以環境變數覆蓋
+
+管理員可在緊急或維護時以 `DBCLI_OVERRIDE_BLACKLIST=true` 略過黑名單：
+
+```bash
+DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
+```
+
+此覆蓋會被記錄，僅應在必要時由管理員使用。
+
+### 黑名單設定
+
+規則存於 `.dbcli`，亦可手動編輯：
 
 ```json
 {
-  "connection": {
-    "system": "postgresql",
-    "host": "localhost",
-    "port": 5432,
-    "user": "postgres",
-    "password": "secret",
-    "database": "mydb"
-  },
-  "permission": "read-write",
-  "metadata": {
-    "createdAt": "2026-03-26T12:00:00Z",
-    "tables": [
-      {
-        "name": "users",
-        "columns": [...],
-        "primaryKey": ["id"],
-        "foreignKeys": [...]
-      }
-    ]
+  "blacklist": {
+    "tables": ["audit_logs", "secrets_vault"],
+    "columns": {
+      "users": ["password_hash", "ssn"]
+    }
   }
 }
 ```
 
-### 環境變數參考
+### 黑名單與權限的關係
+
+兩者互補：
 
-| 變數 | 說明 | 預設值 |
-|------|------|--------|
-| `DBCLI_LANG` | 語言（en、zh-TW） | `en` |
-| `DATABASE_URL` | 資料庫連接字串（可選，init 會嘗試解析） | 無 |
+| 層級 | 控制內容 | 作用範圍 |
+|------|----------|----------|
+| **權限模型** | 操作類型（讀／寫／刪） | 所有表 |
+| **黑名單** | 特定表與欄位 | 敏感資料 |
 
-### .env 整合
+Query-only 代理無法寫入任何表，也無法讀取黑名單表或欄位 — 兩層限制同時生效。
 
-dbcli init 會自動解析 .env 檔案以預先填入連接詳細資訊：
+---
+
+## AI 整合指南
+
+dbcli 可產生供 AI 使用的 skill 文件，並可整合至常見 AI 開發工具。
+
+### 快速開始
+
+為慣用平台產生 skill：
 
 ```bash
-# .env
-DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+# Claude Code（Anthropic VS Code 擴充）
+dbcli skill --install claude
 
-dbcli init
-# 自動填入資料庫詳細資訊，只需確認或調整
+# Gemini CLI（Google 命令列 AI）
+dbcli skill --install gemini
+
+# GitHub Copilot CLI
+dbcli skill --install copilot
+
+# Cursor IDE
+dbcli skill --install cursor
 ```
 
-## 故障排除
+安裝後，AI 可依你的權限等級使用 dbcli 查詢、插入、更新或匯出資料。
 
-### 「未配置資料庫」
+### 各平台設定
 
-```
-Database not configured. Run: dbcli init
-```
+#### Claude Code（Anthropic）
 
-**解決方案：** 執行 `dbcli init` 建立 `.dbcli` 配置檔案。
+1. 全域安裝 dbcli：`npm install -g @carllee1983/dbcli`
+2. 初始化：`dbcli init`（選擇權限等級）
+3. 安裝 skill：`dbcli skill --install claude`
+4. 重新啟動 Claude Code 擴充
+5. 在對話中詢問：「顯示資料庫 schema」或「查詢作用中使用者」
 
-### 「連接失敗」
+**Skill 路徑：** `~/.claude/skills/SKILL.md`
 
+---
+
+#### Gemini CLI（Google）
+
+1. 全域安裝：`npm install -g @carllee1983/dbcli`
+2. 初始化：`dbcli init`
+3. 安裝 skill：`dbcli skill --install gemini`
+4. 啟動 Gemini：`gemini start`
+5. 在對話中請求：「查詢 users 表」或「列出資料庫資料表」
+
+**Skill 路徑：** `~/.local/share/gemini/skills/`（Linux）或各平台對應路徑
+
+---
+
+#### GitHub Copilot CLI
+
+1. 全域安裝：`npm install -g @carllee1983/dbcli`
+2. 初始化：`dbcli init`
+3. 安裝 skill：`dbcli skill --install copilot`
+4. 安裝 Copilot CLI：`npm install -g @github-next/github-copilot-cli`
+5. 使用 `copilot --help` 並探索與 dbcli 的整合
+
+**Skill 路徑：** 依 Copilot 設定而定
+
+---
+
+#### Cursor IDE
+
+1. 全域安裝：`npm install -g @carllee1983/dbcli`
+2. 初始化：`dbcli init`
+3. 安裝 skill：`dbcli skill --install cursor`
+4. 開啟 Cursor
+5. 在 Composer 中：「新增一筆使用者」或「匯出使用者資料」
+
+**Skill 路徑：** `~/.cursor/skills/`
+
+---
+
+### 範例：AI 代理工作流程
+
+**情境：** 希望 AI 分析使用者參與度。
+
+```bash
+# 1. 安裝並初始化
+npm install -g @carllee1983/dbcli
+dbcli init  # 選擇「query-only」較安全
+
+# 2. 為 Claude Code 安裝 skill
+dbcli skill --install claude
+
+# 3. 在 Claude Code 對話中：
+# 「分析最近 7 天的使用者活動並摘要重點」
+
+# Claude Code 可能會：
+# - 使用：dbcli schema users、dbcli query "SELECT ..."
+# - 解析 JSON 輸出
+# - 提供分析
 ```
-Failed to connect to database: ECONNREFUSED 127.0.0.1:5432
+
+### 重新整理 Skill
+
+權限或設定變更後，可重新產生 skill：
+
+```bash
+# 例如編輯 .dbcli/config.json，將 "permission" 設為 "admin"（或重新執行 dbcli init）
+dbcli skill  # 會顯示 delete 與 migrate 等指令
+
+# 再安裝一次以更新 AI 平台
+dbcli skill --install claude
 ```
 
-**檢查清單：**
-- 資料庫伺服器是否執行中？
-- 主機和埠口是否正確？
-- 用戶和密碼是否有效？
-- 網路是否可達？（特別是遠程資料庫）
+---
+
+## 故障排除
+
+### 連線問題
+
+#### 「ECONNREFUSED: Connection refused」
+
+資料庫未執行或主機／埠錯誤。
+
+**處理方式：**
 
-### 「權限被拒」
+```bash
+# 確認資料庫是否在跑
+psql --version   # PostgreSQL
+mysql --version  # MySQL
+
+# 檢查連線字串
+dbcli init  # 重新初始化以確認憑證
 
+# 命令列測試主機／埠
+psql -h localhost -U postgres
+mysql -h 127.0.0.1 -u root
 ```
-Permission denied (required: admin)
+
+#### 「ENOTFOUND: getaddrinfo ENOTFOUND hostname」
+
+主機名稱無法解析（拼字錯誤或 DNS 問題）。
+
+**處理方式：**
+
+```bash
+# 檢查專案設定中的 host（目錄型配置：.dbcli/config.json）
+grep host .dbcli/config.json
+
+# 測試 DNS
+ping your-hostname.com
+
+# 若仍有問題可改試 127.0.0.1
+dbcli init
 ```
 
-**解決方案：**
-- 該命令需要更高的權限等級
-- 執行 `dbcli init` 並選擇更高的權限級別
-- 或聯繫資料庫管理員
+---
+
+### 權限錯誤
 
-### 「表不存在」
+#### 「Permission denied: INSERT requires Read-Write or Admin」
 
+在 Query-only 下嘗試寫入。
+
+**處理方式：** 以較高權限重新初始化：
+
+```bash
+rm -rf .dbcli   # 移除專案設定（具破壞性 — 請先備份）
+dbcli init      # 選擇 read-write、data-admin 或 admin
 ```
-Table not found: nonexistent_table
+
+#### 「Permission denied: DELETE operation requires Data-Admin or Admin」
+
+DELETE 在 query-only 與 read-write 下不允許。
+
+**處理方式：** 改用 `data-admin` 或 `admin` 權限（重新執行 `dbcli init`，或編輯 `.dbcli/config.json`），或洽管理員。
+
+```bash
+dbcli init  # 選擇 data-admin 或 admin
+dbcli delete users --where "id=1" --force
 ```
 
-**解決方案：**
-- 執行 `dbcli list` 檢查可用表
-- 檢查表名拼寫
-- 確認已連接到正確的資料庫
+---
+
+### 查詢錯誤
+
+#### 「Table not found: users」
+
+表不存在或名稱拼錯。
 
-### 查詢超時
+**處理方式：**
 
+```bash
+dbcli list
+dbcli query "SELECT * FROM user" --format json
 ```
-Query timeout after 30s
+
+#### 「Syntax error near SELECT」
+
+SQL 語法錯誤。
+
+**處理方式：**
+
+```bash
+# 先在原生用戶端測試
+psql  # 或 mysql
+
+# 再在 dbcli 使用
+dbcli query "SELECT * FROM users"
 ```
 
-**解決方案：**
-- 簡化查詢（新增 WHERE 條件、JOIN 等）
-- 使用 `--limit` 限制行數
-- 檢查資料庫索引是否最佳化
+---
 
-## 技術棧
+### 效能問題
 
-| 組件 | 技術 | 理由 |
-|------|------|------|
-| 執行時 | Bun | 快速啟動、原生 TS 支援 |
-| 資料庫 | PostgreSQL、MySQL、MariaDB | 廣泛使用、成熟生態 |
-| 測試 | Vitest | 快速、全面的單位 & 集成測試 |
-| 分發 | npm | 標準 Node.js/Bun 生態 |
+#### 「查詢只回傳 1000 列而非完整結果」
 
-## 開發
+Query-only 會自動限制列數以策安全。
 
-### 設定開發環境
+**處理方式：** 提高權限或分段抓取：
 
 ```bash
-# 克隆倉庫
-git clone https://github.com/your-org/dbcli.git
-cd dbcli
+dbcli init  # read-write 或 admin
 
-# 安裝依賴
-bun install
+# 或分塊查詢
+dbcli query "SELECT * FROM users LIMIT 100 OFFSET 0"
+dbcli query "SELECT * FROM users LIMIT 100 OFFSET 100"
+```
 
-# 執行測試
-bun test
+#### 「第一次執行 CLI 超過 30 秒」
 
-# 本地開發
-bun run src/cli.ts init
-```
+npx 正在下載並快取套件。
 
-### 測試
+**處理方式：** 首次較慢屬正常，之後會很快：
 
 ```bash
-# 執行所有測試
-bun test
+npx @carllee1983/dbcli init   # 首次約 30s
+npx @carllee1983/dbcli init   # 之後 <1s
+
+# 或全域安裝
+npm install -g @carllee1983/dbcli
+dbcli init
+```
+
+---
+
+### 跨平台問題
+
+#### Windows：「Command not found: dbcli」
+
+npm 未建立 .cmd 或 PATH 未更新。
+
+**處理方式：**
 
-# 執行特定測試檔案
-bun test src/commands/query.test.ts
+```bash
+# 重開終端機以更新 PATH
+# 或重新全域安裝
+npm uninstall -g @carllee1983/dbcli
+npm install -g @carllee1983/dbcli
 
-# 監視模式
-bun test --watch
+where dbcli
 ```
 
-### 構建
+#### macOS／Linux：「Permission denied: ./dist/cli.mjs」
+
+未設定執行位元。
+
+**處理方式：**
 
 ```bash
-# 構建發行版本
-bun build src/cli.ts --outfile dist/cli.mjs
+chmod +x dist/cli.mjs
+./dist/cli.mjs --help
 ```
 
-## 貢獻
+---
 
-貢獻歡迎！請提交問題和拉請求。
+## 系統需求
 
-### 開發者指南
+### 資料庫支援
 
-詳見 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+- **PostgreSQL：** 12.0+
+- **MySQL：** 8.0+
+- **MariaDB：** 10.5+
 
-### 國際化貢獻
+### 執行環境
 
-如果要新增訊息或翻譯：
+- **Node.js：** 18.0.0+
+- **Bun：** 1.3.3+
 
-1. 編輯 `resources/lang/{en,zh-TW}/messages.json`
-2. 在命令中使用 `t()` 或 `t_vars()`
-3. 執行測試確保一致性
+### 平台
 
-## 授權
+- **macOS：** Intel 與 Apple Silicon
+- **Linux：** x86_64（Ubuntu、Debian、CentOS 等）
+- **Windows：** 10+（透過 npm .cmd 包裝）
+
+---
 
-MIT — 見 [LICENSE](./LICENSE)
+## 開發
 
-## 更新日誌
+```bash
+bun test        # 執行測試
+bun run build   # 建置 CLI 至 dist/（發布前使用）
+```
 
-見 [CHANGELOG.md](./CHANGELOG.md)。
+完整環境、測試與發布流程見 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
 ---
 
-**最後更新：** 2026-03-26 | **版本：** v1.0.0+
+## 授權
+
+詳見專案中的 LICENSE 檔案。