@szc-ft/mcp-szcd-client 0.29.0 → 0.31.0

package/opencode-extension/skills/local-browser-test/SKILL.md

@@ -25,6 +25,9 @@ compatibility:
 **视觉对比（用 --action compare）：**
 - "对比设计稿" / "还原度" / "像素对比"
 
+**凭据管理（用 decrypt-creds.mjs）：**
+- "获取密码" / "解密密码" / "自动登录" / "读取浏览器保存的密码" / "接管浏览器，帮我登录"
+
 ## ⚡ 路径解析（必读，避免 ad-hoc 脚本）
 
 **执行器内置在 skill 目录中（自包含），会话开始时先解析 skill 路径：**
@@ -149,15 +152,22 @@ Agent / SKILL.md
   → $SKILL_DIR/lib/expect.js          (validation/locator/url/api + poll)
   → puppeteer-core + CDP
   → 用户真实 Chrome / Edge
+
+  ── 凭据分支 ──
+  → $SKILL_DIR/decrypt-creds.mjs          (CLI 入口)
+  → $SKILL_DIR/lib/cdp-browser-config.js  (检测 user-data-dir)
+  → $SKILL_DIR/lib/decrypt-passwords.js   (DPAPI + AES-GCM 解密)
+  → 输出 { username, password, url }
 ```
 
-执行器 + lib 内置在 skill 目录中（自包含），`postinstall` 会把整个 skill 目录复制到各 IDE。
+执行器 + lib + 凭据解密模块内置在 skill 目录中（自包含），`postinstall` 会把整个 skill 目录复制到各 IDE。
 **禁止 AI 在用户机器上写 ad-hoc puppeteer 脚本**——会丢失：
 - 微前端 frame 探活 + 自动召回
 - `closeAllDropdowns` 跨 frame 清理
 - Ant Select VERIFY 回写
 - testCase recovery 重试
 - API 按 frame scope 过滤
+- 浏览器凭据自动解密（使用内置 `decrypt-creds.mjs`）
 
 `local-browser-executor.cjs`（同目录）是 CommonJS 过渡版，仅支持基础诊断。**Ant 适配层 / testCase DSL / expect 断言仅 `local-browser-executor.js`（ES Module 版）支持。**
 
@@ -168,6 +178,9 @@ Agent / SKILL.md
 ### connect 模式（推荐）
 连接用户已启动的调试 Chrome，天然继承登录态/微前端环境。
 
+**connect 时自动解密凭据**：连接浏览器后，engine 自动检测 `--user-data-dir` 并解密所有保存的密码，
+结果缓存到 `~/.szcd-mcp/deps/decrypted-creds.json`。后续可直接用 `engine._credentials` 获取。
+
 用户一次性配置：
 ```bash
 # macOS
@@ -376,7 +389,7 @@ node "$EXECUTOR" \
   --output /tmp/browser-observe.json
 ```
 
-`observe` 输出 `frames`、`tree`、`interactiveElements[index]`、`selectorCandidates`、`bbox`、`state`。Agent 后续应优先使用 `index` 调用 `act`，不要从 DOM 树重新猜 selector。直接 `--action observe` 默认只连接用户已启动的真实浏览器 CDP；如确需无 CDP 时启动 headless 回退，追加 `--allow-launch`。
+`observe` 输出 `frames`、`tree`、`interactiveElements[index]`、`selectorCandidates`、`bbox`、`state`、`wujieContext`（含 `shadowBodyText` 全文 + `shadowBodyTextLength`）。Agent 后续应优先使用 `index` 调用 `act`，不要从 DOM 树重新猜 selector。直接 `--action observe` 默认只连接用户已启动的真实浏览器 CDP；如确需无 CDP 时启动 headless 回退，追加 `--allow-launch`。
 
 ### 观察后按 index 交互（主链路闭环）
 ```bash
@@ -440,6 +453,38 @@ node "$EXECUTOR" \
 
 计划内可直接在 `apiCapture` 后追加 `{ "type": "assertApi", "maxFailed": 0, "forbidStatusGte": 400 }`，会自动读取上一步捕获结果。
 
+### 浏览器端 JS 执行（构造 testCase 前提取表单元数据）
+```bash
+node "$EXECUTOR" \
+  --action evaluate \
+  --url-contains "platform.aicityos.com" \
+  --frame-index 1 \
+  --expression '(() => Array.from(document.querySelectorAll(".ant-form-item")).map(item => ({
+    label: item.querySelector(".ant-form-item-label")?.textContent?.trim() || "",
+    required: !!item.querySelector(".ant-form-item-required"),
+    error: item.querySelector(".ant-form-item-explain-error")?.textContent?.trim() || ""
+  })).filter(x => x.label))()' \
+  --fail-on-falsy \
+  --output /tmp/form-fields.json
+```
+
+`--action evaluate` 在目标 frame 中执行任意 JS 表达式（需用 IIFE 包裹），返回 `{ result, passed }`。这是构造 testCase JSON 前的核心步骤：**无源码依赖地提取页面表单元数据、校验错误、Select 选项列表等**。
+
+关键参数：
+- `--expression <js>`：执行的 JS 表达式（必填）
+- `--fail-on-falsy`：结果为 falsy 时标记 FAIL
+- `--expect-result-contains <text>`：结果 JSON 包含指定文本
+
+### 执行测试计划 JSON（ES Module 版）
+```bash
+node "$EXECUTOR" \
+  --action plan \
+  --plan-file /tmp/test-plan.json \
+  --output /tmp/browser-test-result.json
+```
+
+`--action plan` 使用 ES Module 执行器运行测试计划 JSON，支持全部步骤类型（包括 evaluate、antSelect 等）。与 `--action test-case` 的区别：plan 不走 dataset 循环，适合单次执行。
+
 ### 快速诊断（过渡兼容）
 ```bash
 NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.cjs" \
@@ -526,7 +571,8 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.
   --scroll down --scroll-amount 500
 ```
 选择器语法：
-- `text=Build` → 按文本内容查找（类似 Playwright text selector）
+- `text=Build` → 按文本内容模糊查找，多个匹配时选 innerText 最短的元素（叶子节点优先，避免命中父容器）
+- `text==Build` → 精确文本匹配（Playwright 风格），只匹配 innerText 完全相等的元素
 - `role=button` → 按 ARIA role 查找
 - `~ant-menu-item` → CSS class 模糊匹配（`[class*="ant-menu-item"]`）
 - `.my-class` → 精确 CSS 选择器
@@ -599,12 +645,12 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/local-browser-executor.
 ## 依赖管理
 
 浏览器测试依赖采用**共享缓存 + 按需安装**方案：
-- `observe/act/assert/diagnose/screenshot` 主链路只安装 `puppeteer-core` 到 `~/.szcd-mcp/deps/`
+- 主链路（`observe/act/assert/diagnose/screenshot` + 凭据解密）安装 `puppeteer-core` + `sql.js` 到 `~/.szcd-mcp/deps/`
 - 只有执行设计稿像素对比 `compare` 时才安装 `pixelmatch/pngjs/sharp`
 - 后续所有项目共享复用，无需重复安装
 - 如果核心依赖自动安装失败，引导用户手动执行：
 ```bash
-cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com puppeteer-core
+cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com puppeteer-core sql.js
 ```
 - 如果视觉对比依赖自动安装失败，引导用户手动执行：
 ```bash
@@ -687,6 +733,133 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
    ```
    `runTask` 会自动从 `context.lastApiCapture` 拿菜单树，不需要再传文件。
 
+## 🔑 凭据解密（自动获取浏览器保存的密码）
+
+当测试需要登录但浏览器已保存密码时，使用内置的 `decrypt-creds.mjs` 自动从 Edge/Chrome 的密码管理器中解密凭据，**无需人工输入密码**。
+
+### 工作原理
+
+```
+Agent / SKILL.md
+  → $SKILL_DIR/lib/cdp-browser-config.js  自动检测浏览器 user-data-dir
+  → $SKILL_DIR/lib/decrypt-passwords.js    DPAPI + AES-GCM 解密 v10 密码
+  → $SKILL_DIR/decrypt-creds.mjs           CLI 入口（一键调用）
+  → 返回 { username, password, url }
+```
+
+### 前置条件
+
+- 浏览器以 `--remote-debugging-port=9222` 启动（CDP 已连接）
+- 浏览器以 `--user-data-dir=<path>` 指定了自定义数据目录（开发/测试环境常见）
+- 密码以 **v10 格式**存储（开发环境默认；生产环境 v20 需 Python 方案）
+- skill 目录下已安装 `sql.js`：`cd $SKILL_DIR && npm install sql.js`
+- 首次解密后结果自动缓存到 `~/.szcd-mcp/deps/decrypted-creds.json`，后续秒级返回
+
+### 使用方式
+
+```bash
+# 自动检测浏览器配置 + 解密所有凭据（使用共享缓存依赖）
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/decrypt-creds.mjs" --url aicityos
+
+# 首次运行：全量解密 + 写入缓存（~/.szcd-mcp/deps/decrypted-creds.json）
+# 后续运行：秒级返回（自动检测 Login Data 修改时间判断缓存是否过期）
+
+# 强制刷新缓存（如手动修改了密码）
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/decrypt-creds.mjs" --url aicityos --refresh
+
+# JSON 格式输出（供脚本解析）
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/decrypt-creds.mjs" --url aicityos --json
+
+# 手动指定 user-data-dir（跳过自动检测）
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/decrypt-creds.mjs" --user-data-dir "C:/EdgeDevSession" --url aicityos
+
+# 查看帮助
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/decrypt-creds.mjs" --help
+```
+
+### 典型场景：SSO 登录自动化
+
+**⚠️ 强制流程：解密后必须先向用户澄清使用哪一个账号登录，禁止自动选择！**
+
+```bash
+# 1. 解密凭据（使用共享缓存依赖）
+CREDS=$(NODE_PATH=~/.szcd-mcp/deps/node_modules node "$SKILL_DIR/decrypt-creds.mjs" --url aicityos --json)
+
+# ❌ 错误：拿到第一个凭据就直接登录
+# USER=$(echo "$CREDS" | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))[0].username")
+
+# ✅ 正确：先把去重后的用户列表展示给用户，让用户选择
+# LLM 根据解密结果，用 AskUserQuestion 列出所有可用账号供用户选择：
+#   "解密到以下 X 个账号，请选择使用哪一个登录："
+#   - admin (密码: Jx***01#)
+#   - 18718576547 (密码: Jx***01#)
+#   - zengzhijie (密码: zen***123)
+#   ...
+# 用户选择后，再继续后续步骤
+
+# 2. 用户确认后，用选定的凭据构造登录 testCase
+cat > /tmp/login.json <<EOF
+{
+  "title": "自动登录",
+  "options": { "timeout": 30000 },
+  "steps": [
+    { "type": "antInput", "placeholder": "请输入账户", "value": "$USER" },
+    { "type": "antInput", "placeholder": "请输入密码", "value": "$PASS" },
+    { "type": "antInput", "placeholder": "请输入图形验证码", "value": "6" },
+    { "type": "act", "click": "text==登 录" }
+  ]
+}
+EOF
+
+# 3. 执行登录
+node "$EXECUTOR" --action plan --plan-file /tmp/login.json --url-contains "platform.aicityos.com" --wait 8000
+```
+
+**LLM 处理流程：**
+1. 调用 `decrypt-creds.mjs --json` 获取用户列表（首次慢，后续秒级缓存命中）
+2. 对凭据去重（同一用户名取首次出现的密码）
+3. **用 `AskUserQuestion` 列出所有可用账号（只展示完整用户名，不展示密码），让用户选择**
+4. 用户选择后，从解密结果中查找对应密码，构造登录 testCase
+5. 执行登录
+
+**⚠️ 强制约束：**
+- 只展示账号列表，**不展示密码**（含脱敏也不展示）
+- **展示完整账号**，不截断
+- **每次登录都向用户询问**，不自动选择
+
+**多账号切换场景（如测试不同角色权限）：**
+- 首次登录时一次性询问："本次测试需要用到哪些账号？"，用户可多选
+- 后续切换直接用缓存的选择，不再重复询问
+- 构造 testCase 时，用 `dataset` 数组参数化不同账号：
+```json
+{
+  "title": "多账号权限测试",
+  "dataset": [
+    { "user": "admin", "pwd": "Jx@shSmt01#" },
+    { "user": "18718576547", "pwd": "Jx@shSmt01#" }
+  ],
+  "steps": [
+    { "type": "cdpScript", "script": "logout" },
+    { "type": "cdpScript", "script": "login", "params": { "username": "{{user}}", "password": "{{pwd}}" } },
+    { "type": "act", "click": "text=提交", "waitAfterEach": 3000 }
+  ]
+}
+```
+
+### 技术栈（纯 Node.js，零原生编译）
+
+| 模块 | 功能 | 依赖 |
+|------|------|------|
+| `lib/cdp-browser-config.js` | 通过 wmic + CDP 自动获取 `--user-data-dir` | Node.js 内置 |
+| `lib/decrypt-passwords.js` | DPAPI 解密 AES 密钥 + AES-256-GCM 解密密码 | `sql.js`（共享缓存）+ `crypto` + PowerShell |
+| `decrypt-creds.mjs` | CLI 入口：检测配置 → 解密 → 输出 | 以上两者 |
+
+### 兼容性说明
+
+- ✅ **v10 格式**（开发/测试环境 Edge/Chrome）：完全支持
+- ❌ **v20 格式**（生产环境，App-Bound Encryption）：需 Python `pywin32` + `cryptography` 方案
+- ⚠️ Windows 专属（DPAPI），macOS/Linux 需 Keychain/KWallet 方案
+
 ## 反模式备忘（来自 6/17 + 6/18 实战反馈）
 
 | 错误做法 | 正确做法 | 原因 |
@@ -701,6 +874,76 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 | 每个 Select 后忘记 `closeAllDropdowns` | `act` 自动检测上一次 antSelect/antTreeSelect 并预清理 | 下拉浮层残留会污染下一次 Select 操作，选项串选 |
 | 硬编码 `sleep(15*200)` 等选项渲染 | `antSelect` 内置 `pollEval` 15×200ms 轮询，`expect(poll)` 可自定义条件 | 选项渲染时间受网络/数据量影响，固定 sleep 时机不可靠 |
 | 表单校验用 ad-hoc evaluate 检查 | 用 `expect validation.toPass` 或 `formFill` 的 `validateAfter` | 语义断言自带 poll + 结构化错误信息（field + message），可直接进报告 |
+| 登录/登出写多步 antInput + act | 用 `cdpScript` 一次搞定：`{ "type": "cdpScript", "script": "login", "params": {...} }` | 已封装为内置脚本，自动处理 appId/viewId 参数保留和 cookie 清理 |
+| 登出后硬编码裸 URL 导航 | 从主 frame 提取 `appId`/`viewId` 构建完整登录 URL | 裸 URL 不会自动补充 SSO 参数，导致后续登录失败 |
+| CDP captureApi 请求数为 0 | 关闭 DevTools 后再用 `Network.enable` 监听 | DevTools 的 Network 面板会抢占 CDP Network 域，导致 captureApi 捕获不到请求 |
+
+## 🛡️ 测试健壮性三层架构（L1/L2/L3）
+
+每次 testCase 执行都会自动运行三层监控与恢复，无需额外配置：
+
+```
+testCase 执行
+  ├── L1 自动监控（每步内置）
+  │   ├── Runtime.exceptionThrown → browserErrors[]
+  │   ├── console.error → consoleErrors[]
+  │   └── Network.response ≥400 → failedRequests[]
+  │
+  ├── L2 智能诊断（失败时自动生成）
+  │   ├── 失败步骤定位（哪个 step/dataRow 失败）
+  │   ├── 网络错误归类（401/403/5xx 统计）
+  │   └── 推断建议（session 过期/验证码/服务器异常）
+  │
+  └── L3 自动修复（条件触发）
+      ├── 登录失败 → 刷新页面 + 重新登录（maxRetries 次）
+      ├── 元素未找到 → 等待渲染 + 重试
+      └── 网络错误 → 页面重载 + 重试
+```
+
+### testCase 新增选项
+
+```json
+{
+  "title": "测试",
+  "options": {
+    "autoRecover": true,        // 开启自动恢复（默认 true）
+    "autoRecoverRetries": 2     // 最大恢复重试次数（默认 2）
+  },
+  "steps": [...]
+}
+```
+
+### testCase 返回增强
+
+```json
+{
+  "passedSteps": 8,           // 最终通过数
+  "failedSteps": 0,           // 最终失败数
+  "browserErrors": [...],     // L1: JS 异常详情
+  "failedRequests": [...],    // L1: 4xx/5xx 请求列表
+  "consoleErrors": [...],     // L1: console.error 消息
+  "diagnosticHint": {         // L2: 诊断结果（仅失败时）
+    "failedAt": [...],
+    "suggestions": ["建议刷新登录页重试..."],
+    "summary": "1 个步骤失败, 0 个请求异常"
+  },
+  "autoRecovery": {           // L3: 恢复结果（仅触发时）
+    "strategies": [{"type": "login", "result": "success"}],
+    "recovered": true,
+    "retries": 2
+  }
+}
+```
+
+### cdpScript login 增强
+
+- `params.username` 必填，`params.password` 可选（自动从 `engine._credentials` 查找）
+- 内置验证码过期重试：失败时自动刷新页面重新填表（`params.maxRetries` 默认 3）
+- 自动处理 appId/viewId URL 参数
+
+```json
+{ "type": "cdpScript", "script": "login", "params": { "username": "admin" } }
+```
 
 ## Ant Design 适配层（6/22 反馈落地）
 
@@ -766,18 +1009,20 @@ node local-browser-executor.js --action test-case --test-case-file /tmp/case.jso
 |------|---------|---------|------|---------|
 | 1 | evaluate | 浏览器端 | DOM 查询/操作 | 简单检查、点击元素 |
 | 2 | rawScript | Node.js 端 | 完整 puppeteer API | 跨 frame、等待、多标签页 |
-| 3 | cdpScript | Node.js 端 | 调用已注册脚本 | 复用通用交互模式 |
-| 4 | 内置 cdpScript | Node.js 端 | 预定义通用 UI 交互 | Drawer/Modal/表格等 |
+| 3 | cdpScript | Node.js 端 | 调用内置或用户注册脚本 | 登录/登出/切换账号/抽屉/弹窗等通用交互 |
+| 4 | 内置 cdpScript | Node.js 端 | 预定义通用 UI 交互 + 凭据管理 | login/logout/getCredentials/drawer-action/modal-action/switch-tab/wait-api/get-table-data |
 
 **evaluate**：浏览器端执行 JS，只能操作 DOM，不能等待/跨 frame/调用 puppeteer
 **rawScript**：Node.js 端执行 async 函数，接收 `(page, frame, params, browser)`，可调用所有 puppeteer API
 **registerCdpScript**：注册可复用脚本，后续通过 cdpScript 步骤按 name 调用
-**cdpScript**：调用 registerCdpScript 注册的脚本或内置脚本
+**cdpScript**：调用内置脚本或用户注册脚本。内置脚本包括登录（支持自动查凭据+验证码重试）、登出（自动保留 appId/viewId）、凭据列表获取等
 
 ### 内置 cdpScript（通用 UI 交互模式）
 
 | script | 功能 | params |
 |--------|------|--------|
+| `login` | **自动登录**（填表+提交） | `username`, `password`, `captcha?`(默认6), `loginUrl?` |
+| `logout` | **登出**（清 cookie+跳转登录页） | `appUrl?`(默认/szc-ai-data/) |
 | `drawer-action` | Drawer 操作 | `action: 'search'\|'select'\|'confirm'\|'cancel'`, `radioIndex?`, `searchText?`, `searchPlaceholder?` |
 | `modal-action` | Modal/Popconfirm 操作 | `action: 'confirm'\|'cancel'`, `buttonText?` |
 | `switch-tab` | 多标签页切换 | `urlContains?`, `titleIncludes?`, `pageIndex?` |

package/opencode-extension/skills/local-browser-test/decrypt-creds.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * 浏览器凭据解密工具
+ *
+ * 自动检测 Edge/Chrome 的 user-data-dir 配置并解密保存的密码。
+ * 解密结果缓存到 ~/.szcd-mcp/deps/decrypted-creds.json，避免重复解密。
+ *
+ * 用法:
+ *   NODE_PATH=~/.szcd-mcp/deps/node_modules node decrypt-creds.mjs --url aicityos
+ *   NODE_PATH=~/.szcd-mcp/deps/node_modules node decrypt-creds.mjs --json
+ *   NODE_PATH=~/.szcd-mcp/deps/node_modules node decrypt-creds.mjs --refresh   # 强制刷新缓存
+ *
+ * 前置条件:
+ *   - 浏览器以 --remote-debugging-port 和 --user-data-dir 启动
+ *   - ~/.szcd-mcp/deps/ 已安装 sql.js（共享缓存，跨 IDE 共享）
+ */
+import { getFullBrowserConfig } from './lib/cdp-browser-config.js';
+import { decryptAllPasswords } from './lib/decrypt-passwords.js';
+import { existsSync, readFileSync, writeFileSync, statSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// 缓存文件路径（共享缓存目录）
+const CACHE_DIR = join(homedir(), '.szcd-mcp', 'deps');
+const CACHE_FILE = join(CACHE_DIR, 'decrypted-creds.json');
+
+// 解析命令行参数
+const args = process.argv.slice(2);
+const options = {
+  url: null,
+  json: false,
+  refresh: false,      // 强制刷新，忽略缓存
+  cdpUrl: 'http://localhost:9222',
+  userDataDir: null,
+  verbose: false,
+};
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--url': options.url = args[++i]; break;
+    case '--json': options.json = true; break;
+    case '--refresh': case '-r': options.refresh = true; break;
+    case '--cdp': options.cdpUrl = args[++i]; break;
+    case '--user-data-dir': options.userDataDir = args[++i]; break;
+    case '--verbose': case '-v': options.verbose = true; break;
+    case '--help': case '-h':
+      console.log(`浏览器凭据解密工具（带缓存）
+
+用法:
+  node decrypt-creds.mjs [选项]
+
+选项:
+  --url <pattern>       按 URL 过滤（如 aicityos）
+  --json                 JSON 格式输出
+  --refresh, -r          强制刷新，忽略缓存重新解密
+  --cdp <url>            CDP 地址（默认 http://localhost:9222）
+  --user-data-dir <path> 手动指定 user-data-dir 路径
+  --verbose, -v          输出详细信息
+  --help, -h             显示帮助
+
+缓存说明:
+  解密结果自动缓存到 ${CACHE_FILE}
+  缓存以 userDataDir + filter 为 key，监测 Login Data 文件修改时间判断是否过期
+`);
+      process.exit(0);
+  }
+}
+
+/**
+ * 尝试从缓存读取凭据
+ * @returns {Array|null} 缓存的凭据数组，null 表示缓存无效
+ */
+function tryReadCache(userDataDir, filter) {
+  if (options.refresh) {
+    if (options.verbose) console.error('[decrypt-creds] --refresh 强制刷新，跳过缓存');
+    return null;
+  }
+  if (!existsSync(CACHE_FILE)) {
+    if (options.verbose) console.error('[decrypt-creds] 缓存文件不存在');
+    return null;
+  }
+
+  try {
+    const cache = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+    const cacheKey = `${userDataDir}::${filter}`;
+
+    if (!cache[cacheKey]) {
+      if (options.verbose) console.error('[decrypt-creds] 缓存 key 不匹配');
+      return null;
+    }
+
+    // 检查缓存有效性：Login Data 未变 + 24 小时内
+    const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+    const entry = cache[cacheKey];
+    const age = Date.now() - entry.cachedAt;
+
+    const loginDataPath = join(userDataDir, 'Default', 'Login Data');
+    if (existsSync(loginDataPath)) {
+      const loginDataMtime = statSync(loginDataPath).mtimeMs;
+      if (loginDataMtime > entry.cachedAt) {
+        if (options.verbose) console.error('[decrypt-creds] Login Data 已更新，缓存过期');
+        return null;
+      }
+    }
+
+    if (age > CACHE_MAX_AGE_MS) {
+      if (options.verbose) console.error(`[decrypt-creds] 缓存已过期 (${Math.round(age / 3600000)}h)，重新解密`);
+      return null;
+    }
+
+    if (options.verbose) {
+      console.error(`[decrypt-creds] ✓ 使用缓存（${Math.round(age / 60000)}min 前缓存，${entry.credentials.length} 条凭据）`);
+    }
+    return entry.credentials;
+  } catch (e) {
+    if (options.verbose) console.error('[decrypt-creds] 缓存读取失败:', e.message);
+    return null;
+  }
+}
+
+/**
+ * 将凭据写入缓存
+ */
+function writeCache(userDataDir, filter, credentials) {
+  try {
+    let cache = {};
+    if (existsSync(CACHE_FILE)) {
+      try { cache = JSON.parse(readFileSync(CACHE_FILE, 'utf8')); } catch {}
+    }
+    const cacheKey = `${userDataDir}::${filter}`;
+    cache[cacheKey] = {
+      cachedAt: Date.now(),
+      userDataDir,
+      filter,
+      credentials,
+    };
+    writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2), 'utf8');
+    if (options.verbose) console.error('[decrypt-creds] ✓ 已缓存到', CACHE_FILE);
+  } catch (e) {
+    if (options.verbose) console.error('[decrypt-creds] 缓存写入失败:', e.message);
+  }
+}
+
+async function main() {
+  console.error('[decrypt-creds] 检测浏览器配置...');
+
+  // 1. 获取 user-data-dir
+  let userDataDir = options.userDataDir;
+  if (!userDataDir) {
+    try {
+      const config = await getFullBrowserConfig(options.cdpUrl);
+      if (config) {
+        userDataDir = config.userDataDir;
+        if (options.verbose) {
+          console.error('[decrypt-creds] 浏览器:', config.browserInfo?.browser);
+          console.error('[decrypt-creds] CDP 端口:', config.remoteDebuggingPort);
+          console.error('[decrypt-creds] user-data-dir:', userDataDir);
+        }
+      }
+    } catch (e) {
+      console.error('[decrypt-creds] CDP 检测失败:', e.message);
+    }
+  }
+
+  if (!userDataDir) {
+    console.error('[decrypt-creds] 错误: 未检测到 user-data-dir，请用 --user-data-dir 指定');
+    process.exit(1);
+  }
+
+  const filter = options.url ? `%${options.url}%` : '%';
+
+  // 2. 尝试读缓存
+  let credentials = tryReadCache(userDataDir, filter);
+
+  // 3. 缓存未命中，执行解密
+  if (!credentials) {
+    console.error(`[decrypt-creds] 解密凭据 (filter: ${filter})...`);
+    try {
+      credentials = await decryptAllPasswords({
+        userDataDir,
+        filter,
+        verbose: options.verbose,
+      });
+      // 写入缓存
+      writeCache(userDataDir, filter, credentials);
+    } catch (e) {
+      console.error('[decrypt-creds] 解密失败:', e.message);
+      process.exit(1);
+    }
+  }
+
+  // 4. 输出结果
+  if (options.json) {
+    console.log(JSON.stringify(credentials, null, 2));
+  } else {
+    if (credentials.length === 0) {
+      console.log('(未找到匹配的凭据)');
+    } else {
+      const maxUserLen = Math.max(...credentials.map(c => c.username.length));
+      for (const { url, username, password } of credentials) {
+        console.log(`${username.padEnd(maxUserLen)}  ${password}  (${url})`);
+      }
+    }
+  }
+}
+
+main();