@carllee1983/dbcli 1.5.2 → 1.7.0

package/README.zh-TW.md

@@ -6,6 +6,8 @@
 
 **核心價值：** AI 代理可透過單一、具權限控管的 CLI 工具，在敏感資料保護下安全且智慧地存取專案資料庫。
 
+> **安全性更新：** `dbcli init` 現在只會在 `./.dbcli/config.json` 寫入一個很小的專案綁定 stub。完整的連線設定會存放在 `~/.config/dbcli/projects/<project-id>/config.json`，因此敏感設定預設不會留在專案工作區內。
+
 ## 國際化（i18n）
 
 dbcli 透過環境變數 `DBCLI_LANG` 支援多語系：
@@ -88,8 +90,8 @@ dbcli schema users
 # 查詢資料
 dbcli query "SELECT * FROM users"
 
-# 修改結構 (DDL)
-dbcli migrate create posts --column "id:int:pk" "title:varchar(100)"
+# 預覽結構變更（DDL，預設 dry-run；實際套用請加 --execute）
+dbcli migrate create posts --column "id:serial:pk" --column "title:varchar(200):not-null"
 
 # 產生 AI 代理 skill
 dbcli skill --install claude
@@ -146,7 +148,7 @@ dbcli init --conn-name staging --env-file .env.staging
 dbcli init --conn-name prod --env-file .env.production --use-env-refs
 ```
 
-每一條具名連線可以設定不同的 **`--permission`**（例如正式環境只給 `query-only`）。同一專案下的 **schema 快取、黑名單** 等仍共用同一個 `.dbcli` 目錄；切換連線只改「連到哪一台資料庫」，不複製整份專案設定目錄。
+每一條具名連線可以設定不同的 **`--permission`**（例如正式環境只給 `query-only`）。現在專案內的 `.dbcli` 主要扮演**綁定 + 快取層**；真正的連線設定會存到使用者家目錄下的 `~/.config/dbcli/projects/<project-id>/`，避免敏感設定留在工作區。
 
 ### 管理連線（`use` / 移除 / 更名）
 
@@ -187,13 +189,14 @@ dbcli init [OPTIONS]
 ```
 
 **選項 (基本)：**
-- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`
+- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`、`mongodb`
 - `--host <host>` — 主機
 - `--port <port>` — 埠號
 - `--user <user>` — 使用者
 - `--password <pass>` — 密碼
 - `--name <db>` — 資料庫名稱
 - `--permission <level>` — 權限等級：`query-only`、`read-write`、`data-admin`、`admin`
+- **僅 MongoDB：** `--uri <uri>` — 完整連線 URI（`mongodb://…` 或 `mongodb+srv://…`）；`--auth-source <db>` — 驗證資料庫（使用帳密時預設為 `admin`）
 - `--use-env-refs` — 在設定檔中儲存環境變數名稱參照，而非實際值
 - `--skip-test` — 略過連線測試
 - `--no-interactive` — 非互動模式（須提供所有必要選項）
@@ -208,7 +211,7 @@ dbcli init [OPTIONS]
 **行為：**
 - 若存在 `.env` 會讀取（自動帶入 DATABASE_URL、DB_* 等變數）
 - 缺少的欄位會互動提示（主機、埠、使用者、密碼、資料庫名、權限等級）
-- 在專案根目錄建立 `.dbcli` JSON 設定檔
+- 在 `.dbcli/config.json` 建立專案綁定 stub，並將完整設定儲存在 `~/.config/dbcli/projects/<project-id>/`
 - 儲存前會測試資料庫連線
 
 **範例：**
@@ -258,6 +261,8 @@ dbcli use --list
 
 > **`--use-env-refs`：** 啟用後，設定檔會儲存環境變數名稱（例如 `{"$env": "DB_HOST"}`）而非實際值，避免將憑證寫入檔案，適合多環境與 CI/CD。連線時 dbcli 會自動從對應環境變數讀取實際值。
 
+> **儲存模型：** 專案內的 `.dbcli` 現在是綁定 + 快取層，不再是秘密資訊的最終儲存地。若你查看 `./.dbcli/config.json`，應只會看到綁定 metadata；完整設定會放在前述 home storage 路徑中。
+
 ---
 
 #### `dbcli list`
@@ -506,8 +511,8 @@ dbcli skill --install cursor          # 安裝至 Cursor IDE
 ```
 
 **行為：**
-- 套件內建唯一的 **`assets/SKILL.md`**（單一來源）
-- 可輸出至 **stdout**、以 **`--output`** 寫入檔案，或以 **`--install`** 複製到**各平台預設路徑**
+- 內建 **`assets/SKILL.md`** 與 **`assets/reference.md`**（單一來源：精簡 skill＋完整指令參考）
+- 可輸出至 **stdout**、以 **`--output`** 寫入主要 skill 檔，或以 **`--install`** 複製到**各平台預設路徑**（`--install` 時一併寫入同目錄的 `reference.md`）
 - 實際能否存取資料庫仍由 `.dbcli` 的**權限等級**與**黑名單**決定；skill 文字描述的是完整 CLI 能力
 
 **範例：**
@@ -610,6 +615,10 @@ dbcli check orders --checks nulls,orphans --format table
 
 # 掃描所有資料表
 dbcli check --all
+
+# 以表格顯示單表／掃全庫僅執行部分檢查
+dbcli check orders --format table
+dbcli check --all --checks nulls,duplicates --format json
 ```
 
 ---
@@ -700,7 +709,7 @@ dbcli upgrade --check           # 僅檢查，不安裝
 
 **背景檢查（stderr；使用 `--quiet` 或執行 `upgrade` / `skill` 時略過）：**
 - **CLI 版本：** dbcli 會查詢 npm registry（有快取，約每 24 小時一次）。若有新版，一般指令結束後會印一行提示。
-- **已安裝的 skill：** 若曾執行 `dbcli skill --install <platform>`，dbcli 會比對各平台安裝檔與套件內的 `assets/SKILL.md`；若不一致，會列出需重新安裝的平台（`dbcli skill --install <platform>`）。執行 `dbcli upgrade` 時也會一併顯示 skill 狀態與版本資訊。
+- **已安裝的 skill：** 若曾執行 `dbcli skill --install <platform>`，dbcli 會比對各平台**主 skill 檔**（`SKILL.md` 或 Cursor 的 `dbcli.mdc`）與套件內的 `assets/SKILL.md`；若不一致，會提示需重新安裝的平台（`dbcli skill --install <platform>`）。執行 `dbcli upgrade` 時也會一併顯示 skill 與版本資訊。重新安裝時也會一併更新技能旁的 `reference.md`。
 
 #### `dbcli shell`
 
@@ -770,6 +779,43 @@ dbcli migrate drop-enum status --execute --force
 
 ---
 
+## 查詢風險規劃
+
+使用 `plan` 在執行前檢查 SQL 安全性。它只讀取本機 dbcli 設定、權限、黑名單規則與已快取的 schema metadata；不會連線到資料庫。
+
+```bash
+dbcli plan "UPDATE users SET status='inactive'" --format json
+```
+
+決策結果：
+
+- `ALLOW` — 未偵測到明顯風險。
+- `WARN` — 執行前應檢查警告。
+- `BLOCK` — 不安全、不支援，或違反安全設定。
+
+文字輸出保持精簡，適合人工閱讀：
+
+```text
+Decision: BLOCK
+Operation: UPDATE
+Target tables: users
+
+Risk factors:
+- UPDATE statement has no WHERE clause.
+
+Recommendations:
+- Add a WHERE clause.
+- Use --dry-run on the actual write command.
+```
+
+JSON 輸出會包含給 AI agent 使用的 `suggestedCommands`：
+
+```bash
+dbcli plan "SELECT id FROM users WHERE id = 1 LIMIT 1" --format json
+```
+
+---
+
 ## 全域選項
 
 所有指令皆支援下列全域選項：
@@ -954,9 +1000,26 @@ Query-only 代理無法寫入任何表，也無法讀取黑名單表或欄位
 
 ---
 
+## 已保存查詢片段（Saved queries）
+
+將參數化的 SELECT 片段保存於版控，並依名稱重複執行：
+
+```bash
+dbcli queries list
+dbcli queries show @dau
+dbcli q @dau --param days=30 --format json
+```
+
+片段位於兩層儲存：`.dbcli-shared/queries/`（commit 進版控、團隊共享）與
+`.dbcli/queries/`（gitignore、個人覆蓋）。每個 `.sql` 檔以 `-- ---` 區塊
+宣告 frontmatter（name、description、engine、params、tags），完整 schema 見
+`assets/reference.md`。
+
+---
+
 ## AI 整合指南
 
-dbcli 內建可供 AI 使用的 skill 文件（`assets/SKILL.md`），並可複製到常見 AI 開發工具的目錄。
+dbcli 內建供 AI 使用的 skill 文件（`assets/SKILL.md` 與 `assets/reference.md`），並可複製到常見 AI 開發工具的目錄。
 
 ### 快速開始
 
@@ -988,7 +1051,7 @@ dbcli skill --install cursor
 4. 重新啟動 Claude Code 擴充
 5. 在對話中詢問：「顯示資料庫 schema」或「查詢作用中使用者」
 
-**Skill 路徑：** `~/.claude/skills/dbcli/SKILL.md`
+**Skill 路徑：** `~/.claude/skills/dbcli/`（`SKILL.md` + `reference.md`）
 
 ---
 
@@ -1000,7 +1063,7 @@ dbcli skill --install cursor
 4. 啟動 Gemini：`gemini start`
 5. 在對話中請求：「查詢 users 表」或「列出資料庫資料表」
 
-**Skill 路徑：** `~/.gemini/skills/dbcli/SKILL.md`
+**Skill 路徑：** `~/.gemini/skills/dbcli/`（`SKILL.md` + `reference.md`）
 
 ---
 
@@ -1012,7 +1075,7 @@ dbcli skill --install cursor
 4. 安裝 Copilot CLI：`npm install -g @github-next/github-copilot-cli`
 5. 使用 `copilot --help` 並探索與 dbcli 的整合
 
-**Skill 路徑：** 執行 `dbcli skill --install copilot` 時，寫入**目前工作目錄**下的 `.github/skills/dbcli/SKILL.md`（通常為專案根目錄）。
+**Skill 路徑：** 執行 `dbcli skill --install copilot` 於專案根目錄時，寫入 **`.github/skills/dbcli/`**（`SKILL.md` + `reference.md`）。
 
 ---
 
@@ -1024,7 +1087,7 @@ dbcli skill --install cursor
 4. 開啟 Cursor
 5. 在 Composer 中：「新增一筆使用者」或「匯出使用者資料」
 
-**Skill 路徑：** 執行 `dbcli skill --install cursor` 時，寫入**目前工作目錄**下的 `.cursor/rules/dbcli.mdc`（專案層級 Cursor 規則）。
+**Skill 路徑：** 在**目前工作目錄**執行 `dbcli skill --install cursor` 時，寫入 **`.cursor/rules/dbcli.mdc`**（摘要與工作流程）及 **`.cursor/skills/dbcli/reference.md`**（完整旗標與範例）。
 
 ---
 
@@ -1051,7 +1114,7 @@ dbcli skill --install claude
 
 ### 升級後更新 skill
 
-`dbcli skill` 安裝的是套件內建的 **`assets/SKILL.md`**，**不會**依你目前的設定即時重新產生。當你**升級 dbcli** 或內建 skill 內容變更時，請對各平台重新安裝：
+`dbcli skill` 會複製套件內的 **`assets/SKILL.md`**；使用 **`--install`** 時另會複製 **`assets/reference.md`** 至技能旁。**不會**依你即時的 `.dbcli` 設定重新產生內文。當**升級 dbcli** 或內建 skill 變更時，請對所使用平台重新執行：
 
 ```bash
 dbcli skill --install claude
@@ -1059,7 +1122,7 @@ dbcli skill --install gemini
 # …依需求
 ```
 
-若本機安裝檔與套件內檔案不一致，多數指令結束後會在 **stderr** 提示（見 **`dbcli upgrade`**）。**權限**或**黑名單**變更會影響 CLI 實際允許的操作 — 建議搭配 `dbcli status`、`dbcli blacklist list` 等讓代理掌握專案現況；skill 文字仍可能列出完整指令集。
+若本機**主 skill 檔**早於套件內 `assets/SKILL.md`，多數指令結束後會在 **stderr** 提醒（見 **`dbcli upgrade`**）。**權限**與**黑名單**變更會影響執行期允許的操作—建議搭配 `dbcli status`、`dbcli blacklist list` 讓代理掌握現況；skill 內文仍可能列出完整指令表。
 
 ---
 
@@ -1230,6 +1293,7 @@ chmod +x dist/cli.mjs
 - **PostgreSQL：** 12.0+
 - **MySQL：** 8.0+
 - **MariaDB：** 10.5+
+- **MongoDB：** 4.4+（`mongodb://` 與 `mongodb+srv://` 查詢與列集合；見前文 **MongoDB Atlas / SRV 連線**）
 
 ### 執行環境