uniner-cli 1.0.0 → 1.0.2

package/bin/uniner-cli-uninstall.js

@@ -21,6 +21,7 @@ const {
     rootDir,
     versionDir,
     skillDir,
+    skillFile,
 } = require('../lib/paths');
 
 function log(msg)  { console.log(`[uniner-cli] ${msg}`); }
@@ -40,6 +41,20 @@ function rmRf(p) {
     }
 }
 
+function rmFile(p) {
+    try {
+        if (fs.existsSync(p)) {
+            fs.unlinkSync(p);
+            log(`Removed ${p}`);
+            return true;
+        }
+        return false;
+    } catch (e) {
+        warn(`Could not remove ${p}: ${e.message}`);
+        return false;
+    }
+}
+
 function main() {
     console.log('');
     console.log('==========================================');
@@ -71,14 +86,57 @@ function main() {
         warn(`Could not inspect ${rootDir()}: ${e.message}`);
     }
 
-    // 3. Remove the Claude Code skill.
-    if (rmRf(skillDir())) didSomething = true;
+    // 3. Remove ONLY the SKILL.md file. NEVER rm -rf the whole skill dir,
+    //    because the user's accumulated scenarios/<name>/ subdirectories
+    //    live there and represent real work they've sedimented over time.
+    //    If they really want everything gone they can do it manually; we
+    //    surface the path below so they know where to look.
+    const dir = skillDir();
+    if (rmFile(skillFile())) didSomething = true;
+
+    // 4. Look for scenarios/ — if there are any, keep them and tell the user.
+    let scenariosKept = 0;
+    const scenariosDir = path.join(dir, 'scenarios');
+    if (fs.existsSync(scenariosDir)) {
+        try {
+            scenariosKept = fs.readdirSync(scenariosDir).filter(n => {
+                const meta = path.join(scenariosDir, n, 'meta.json');
+                return fs.existsSync(meta);
+            }).length;
+        } catch (_) {
+            // best-effort
+        }
+    }
+
+    // 5. If skill dir is now genuinely empty, remove it. Otherwise keep it.
+    try {
+        if (fs.existsSync(dir)) {
+            const remaining = fs.readdirSync(dir);
+            if (remaining.length === 0) {
+                fs.rmdirSync(dir);
+                log(`Removed empty ${dir}`);
+                didSomething = true;
+            }
+        }
+    } catch (_) {
+        // best-effort
+    }
 
     if (!didSomething) {
         log('Nothing to clean — already removed.');
     }
 
     console.log('');
+    if (scenariosKept > 0) {
+        console.log('==========================================');
+        console.log(`  ${scenariosKept} scenario(s) PRESERVED at:`);
+        console.log(`    ${scenariosDir}`);
+        console.log('  (your accumulated knowledge — not deleted)');
+        console.log('  To delete them too:');
+        console.log(`    rm -rf "${scenariosDir}"          # bash`);
+        console.log(`    Remove-Item "${scenariosDir}" -Recurse -Force   # PowerShell`);
+        console.log('==========================================');
+    }
     console.log('Cleanup done. To complete uninstall, also run:');
     console.log('  npm uninstall -g uniner-cli');
     console.log('');

package/lib/SKILL.md.template

@@ -8,6 +8,29 @@ description: RPA 自动化 CLI 工具，提供浏览器自动化、Excel 操作
 > 由 UninerCLI Installer v{{VERSION}} 自动安装到 `%USERPROFILE%\.claude\skills\uniner-cli\`
 > 安装位置（绝对路径）：`{{INSTALL_PATH}}`
 
+## 🛑 任务结束硬性规则（最重要，先读这一节）
+
+**每次用 uniner-cli 完成一个任务后，在你要说"任务完成"或写汇总表之前，必须先执行下面这段：**
+
+如果这次任务**满足任一条件**：
+
+- 调用了 ≥ 3 个 uniner-cli 命令
+- 涉及 web / desktop / OCR 任何一个模块
+- 用户提到过"以后还会跑" / "每天都要" / "做成自动化"
+- 任务里踩过坑（XPath 不稳、参数名错、Vue 组件、超时调整等）
+
+→ **必须主动问用户**："这个流程涉及多步，要不要保存为可重放场景？以后 `uniner-cli skill run <name> --param ...` 就能 0 token 重放，可以放定时任务/RPA 平台里跑。要保存吗？"
+
+不要等用户开口，**主动**问。这是最有价值的一步——你刚刚花了上千 token 调通的流程，沉淀下来下次就能秒跑。
+
+如果用户说"好" / "可以" / "保存吧"：按下面"场景沉淀（4 步流程）"章节执行。
+
+如果用户说"不用"：直接结束，不再追问。
+
+**违反这条规则 = 任务未完成。** 不管你跑得多顺，没问就是没问完整。
+
+---
+
 ## 何时使用本 Skill
 
 用户提到以下任一关键词或任务，**优先调用 uniner-cli**：
@@ -179,6 +202,167 @@ uniner-cli excel data write-range --file "{{INSTALL_PATH}}\workdir\out.xlsx" --c
 uniner-cli web browser close
 ```
 
+## 场景沉淀（4 步流程）
+
+> 这是顶部"任务结束硬性规则"提到的"4 步流程"。用户同意保存场景后，按这里走。
+
+每个场景一个目录，三件套：`meta.json` + `steps.json` + `SKILL.md`，存到：
+
+```
+%USERPROFILE%\.claude\skills\uniner-cli\scenarios\<kebab-case-name>\
+```
+
+**4 步标准流程**：
+
+```bash
+# Step 1: 生成骨架（自动创建目录和模板文件）
+uniner-cli skill init <name>
+
+# Step 2: 用 Write 工具改 meta.json / steps.json / SKILL.md（见下方 schema）
+
+# Step 3: 校验
+uniner-cli skill validate <name>
+
+# Step 4: 试跑一次
+uniner-cli skill run <name> --param ...
+```
+
+### meta.json schema
+
+```json
+{
+  "name": "<kebab-case-name>",
+  "version": "1.0",
+  "description": "一句话描述（会被用来匹配触发关键词）",
+  "params": {
+    "URL": { "type": "string", "required": true, "description": "登录页地址" },
+    "USERNAME": { "type": "string", "required": true, "description": "账号" },
+    "PASSWORD": { "type": "string", "required": true, "sensitive": true, "description": "密码" },
+    "DATE_FROM": { "type": "string", "required": false, "default": "today", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+  }
+}
+```
+
+### steps.json schema
+
+```json
+{
+  "version": "1.0",
+  "name": "<同 meta.name>",
+  "steps": [
+    {
+      "id": "open-browser",
+      "cmd": "web browser open",
+      "args": { "url": "${URL}" },
+      "timeout_ms": 10000
+    },
+    {
+      "id": "ocr-captcha",
+      "cmd": "tool ocr ddddocr",
+      "args": { "img": "workdir/captcha.png" },
+      "store": "ocrResult",
+      "comment": "整个 stdout JSON 存到 ocrResult，下面用 ${ocrResult.data.result} 取"
+    },
+    {
+      "id": "input-captcha",
+      "cmd": "web element input",
+      "args": { "xpath": "//input[@placeholder='验证码']", "value": "${ocrResult.data.result}" }
+    },
+    {
+      "id": "close-browser",
+      "cmd": "web browser close",
+      "always_run": true,
+      "comment": "无论前面成功与否都跑（清理用）"
+    }
+  ]
+}
+```
+
+### 每个 step 支持的字段
+
+| 字段 | 必需 | 说明 |
+|---|---|---|
+| `id` | ✅ | 步骤 ID（唯一） |
+| `cmd` | ✅ | uniner-cli 子命令，**不带 `uniner-cli` 前缀**，如 `web element input` |
+| `args` | ✅ | dict 形式参数，对应 CLI 的 `--key value` |
+| `store` | ❌ | 把 stdout JSON 整个存到变量名 |
+| `if` | ❌ | 条件表达式（见下） |
+| `on_fail` | ❌ | `abort`（默认）/ `continue` / `goto:<step_id>` |
+| `retry` | ❌ | 失败重试次数（不含首次） |
+| `retry_delay_ms` | ❌ | 重试间隔（默认 1000） |
+| `timeout_ms` | ❌ | 单步超时（覆盖全局） |
+| `always_run` | ❌ | 即使前面失败也跑（清理用） |
+| `comment` | ❌ | 给人/AI 看的注释 |
+
+### 变量替换语法
+
+| 写法 | 含义 |
+|---|---|
+| `${URL}` | 用户传入的 `--param URL=xxx` |
+| `${ocrResult.data.result}` | 上一步 store 的 dict 字段（点号路径） |
+| `${tableData.0.1}` | list 索引（0-based） |
+| `${env:USERPROFILE}` | 环境变量 |
+
+### 条件表达式语法（白名单）
+
+| 写法 | 含义 |
+|---|---|
+| `${var}` | 真值判断 |
+| `!${var}` | 取反 |
+| `${var} == 'yes'` | 字符串/数值相等 |
+| `${var} != 'no'` | 不等 |
+| `${var} > 5` | 数值比较（>=, <=, < 同理） |
+| `${var}.includes('login')` | 包含 |
+| `${var}.startsWith('https')` / `endsWith('.xlsx')` | 前/后缀 |
+| `!${var}.includes('admin')` | 取反组合 |
+
+**故意不支持** `&&` / `||` / `()`。要复合逻辑用多步 + `if` + `on_fail` 拆开。
+
+### 失败时的客户体验
+
+```
+$ uniner-cli skill run tms-export --param URL=...
+{"success": false, "failed_step": "click-search", ...}
+
+────────── How to debug ──────────
+Step 'click-search' failed: timeout
+Open Claude Code, paste this:
+
+   I ran 'uniner-cli skill run' and step 'click-search' failed.
+   Error: timeout
+   Please look at the scenario at:
+     C:\Users\xxx\.claude\skills\uniner-cli\scenarios\tms-export
+   Especially steps.json. Help me figure out why and suggest a fix.
+──────────────────────────────────
+```
+
+客户复制这段给你 → 你 Read steps.json 调试 → 改完 `Write` 回去 → 让客户重跑。
+
+### 给 Claude 的对话范式（用户同意保存后）
+
+按这个顺序，**不要跳步**：
+
+1. 想一个 kebab-case 名字（如 `tms-export-waybills` / `sap-monthly-report`）
+2. Bash 跑 `uniner-cli skill init <name>`（生成骨架）
+3. Write 写**真正的**：
+   - `meta.json`：含动态参数 schema（URL / USERNAME / PASSWORD / DATE_FROM 等）
+   - `steps.json`：把刚才跑过的命令序列**完整**写进去，含已知坑的避坑配置（retry / on_fail / always_run）
+   - `SKILL.md`：经验文档（已知坑、用法说明）
+4. Bash 跑 `uniner-cli skill validate <name>` 确认格式无误
+5. 让用户 `uniner-cli skill run <name> --param ...` 自己跑一次确认 0 token 重放可行
+
+**关键**：steps.json 不是命令清单的注释——是**真正可执行的工作流**。要把 `${URL}` `${USERNAME}` `${ocrResult.data.result}` 这种变量绑好，让 `skill run` 真能跑通。
+
+### 已沉淀的场景库
+
+```bash
+uniner-cli skill list                  # 看所有
+uniner-cli skill show <name>           # 看某个的元数据 + 步骤摘要
+uniner-cli skill show <name> --steps   # 看完整步骤
+uniner-cli skill where                 # 看场景库根目录（可手动浏览）
+uniner-cli skill delete <name> --yes   # 删除（默认 dry-run）
+```
+
 ## 不确定时
 
 - `uniner-cli --help` 看一级

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "uniner-cli",
-  "version": "1.0.0",
-  "description": "uniner-cli — RPA automation CLI: browser automation (Playwright/CDP), Excel, OCR, desktop/SAP, crypto/HTTP/email tools. Auto-installs a Claude Code skill on install.",
-  "keywords": [
-    "rpa",
-    "automation",
-    "uniner",
-    "playwright",
-    "excel",
-    "ocr",
-    "claude-code",
-    "ai-agent"
-  ],
-  "homepage": "https://www.uniner.com/",
-  "bugs": {
-    "url": "https://www.uniner.com/",
-    "email": "support@uniner.com"
-  },
-  "license": "Proprietary",
-  "author": "Uniner Tech",
-  "main": "lib/paths.js",
-  "bin": {
-    "uniner-cli": "bin/uniner-cli.js",
-    "uniner-cli-uninstall": "bin/uniner-cli-uninstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js"
-  },
-  "engines": {
-    "node": ">=14"
-  },
-  "os": [
-    "win32"
-  ],
-  "cpu": [
-    "x64"
-  ],
-  "files": [
-    "bin/",
-    "lib/",
-    "scripts/",
-    "README.md",
-    "LICENSE"
-  ]
-}
+{
+    "name":  "uniner-cli",
+    "version":  "1.0.2",
+    "description":  "uniner-cli — RPA automation CLI: browser automation (Playwright/CDP), Excel, OCR, desktop/SAP, crypto/HTTP/email tools. Auto-installs a Claude Code skill on install.",
+    "keywords":  [
+                     "rpa",
+                     "automation",
+                     "uniner",
+                     "playwright",
+                     "excel",
+                     "ocr",
+                     "claude-code",
+                     "ai-agent"
+                 ],
+    "homepage":  "https://www.uniner.com/",
+    "bugs":  {
+                 "url":  "https://www.uniner.com/",
+                 "email":  "support@uniner.com"
+             },
+    "license":  "Proprietary",
+    "author":  "Uniner Tech",
+    "main":  "lib/paths.js",
+    "bin":  {
+                "uniner-cli":  "bin/uniner-cli.js",
+                "uniner-cli-uninstall":  "bin/uniner-cli-uninstall.js"
+            },
+    "scripts":  {
+                    "postinstall":  "node scripts/postinstall.js"
+                },
+    "engines":  {
+                    "node":  "\u003e=14"
+                },
+    "os":  [
+               "win32"
+           ],
+    "cpu":  [
+                "x64"
+            ],
+    "files":  [
+                  "bin/",
+                  "lib/",
+                  "scripts/",
+                  "README.md",
+                  "LICENSE"
+              ]
+}

package/scripts/postinstall.js

@@ -231,8 +231,28 @@ function writeSkillMd(installPath, version) {
 
     const dir = skillDir();
     fs.mkdirSync(dir, { recursive: true });
+
+    // IMPORTANT: only writeFileSync the single SKILL.md file. Do NOT touch
+    // anything else under ~/.claude/skills/uniner-cli/. In particular, the
+    // scenarios/ subdirectory is the user's accumulated knowledge — if we
+    // ever rmdir or rmSync this directory we'd wipe their library on every
+    // upgrade. Single-file write is the contract.
     fs.writeFileSync(skillFile(), content, 'utf8');
     log(`    SKILL.md written to ${skillFile()}`);
+
+    // Tell the user we kept their scenarios (if any).
+    const scenariosDir = path.join(dir, 'scenarios');
+    if (fs.existsSync(scenariosDir)) {
+        try {
+            const count = fs.readdirSync(scenariosDir).filter(n => {
+                const meta = path.join(scenariosDir, n, 'meta.json');
+                return fs.existsSync(meta);
+            }).length;
+            log(`    [INFO] Preserved ${count} scenario(s) in ${scenariosDir}`);
+        } catch (_) {
+            // best-effort; never fail postinstall over a logging stat
+        }
+    }
 }
 
 // ----------------------------------------------------------------------