agent-miniprogram 0.1.0

package/dist/snapshot/refs.js

@@ -0,0 +1,68 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const STATE_DIR = path.join(os.homedir(), '.agent-miniprogram');
+const REFS_FILE = path.join(STATE_DIR, 'refs.json');
+let registry = new Map();
+let counter = 0;
+function ensureStateDir() {
+    if (!fs.existsSync(STATE_DIR)) {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+    }
+}
+export function loadRefs() {
+    if (!fs.existsSync(REFS_FILE))
+        return;
+    try {
+        const data = JSON.parse(fs.readFileSync(REFS_FILE, 'utf-8'));
+        registry = new Map(Object.entries(data.registry || {}));
+        counter = data.counter || 0;
+    }
+    catch {
+        registry = new Map();
+        counter = 0;
+    }
+}
+export function saveRefs() {
+    ensureStateDir();
+    const obj = {};
+    for (const [k, v] of registry)
+        obj[k] = v;
+    fs.writeFileSync(REFS_FILE, JSON.stringify({ registry: obj, counter }, null, 2));
+}
+export function clearRefs() {
+    registry.clear();
+    counter = 0;
+    saveRefs();
+}
+export function registerRef(selector, tag, text) {
+    // Count how many times this selector has already been registered (for $$()[N] resolution)
+    let matchIndex = 0;
+    for (const [, entry] of registry) {
+        if (entry.selector === selector)
+            matchIndex++;
+    }
+    counter++;
+    const ref = `@e${counter}`;
+    registry.set(ref, { selector, tag, text, matchIndex });
+    return ref;
+}
+export function resolveRef(ref) {
+    if (!ref?.startsWith('@'))
+        return undefined;
+    loadRefs();
+    return registry.get(ref)?.selector;
+}
+export function resolveRefFull(ref) {
+    if (!ref?.startsWith('@'))
+        return undefined;
+    loadRefs();
+    const entry = registry.get(ref);
+    if (!entry)
+        return undefined;
+    return { selector: entry.selector, matchIndex: entry.matchIndex ?? 0 };
+}
+export function getRefInfo(ref) {
+    return registry.get(ref);
+}
+//# sourceMappingURL=refs.js.map

package/dist/snapshot/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/snapshot/refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,oBAAoB,CAAC,CAAC;AAChE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AASpD,IAAI,QAAQ,GAA0B,IAAI,GAAG,EAAE,CAAC;AAChD,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB,SAAS,cAAc;IACrB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO;IACtC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7D,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QACrB,OAAO,GAAG,CAAC,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,cAAc,EAAE,CAAC;IACjB,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,QAAQ;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,OAAO,GAAG,CAAC,CAAC;IACZ,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,GAAW,EAAE,IAAa;IACtE,0FAA0F;IAC1F,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAAE,UAAU,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,CAAC;IACV,MAAM,GAAG,GAAG,KAAK,OAAO,EAAE,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IACvD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,QAAQ,EAAE,CAAC;IACX,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,QAAQ,EAAE,CAAC;IACX,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agent-miniprogram",
+  "version": "0.1.0",
+  "description": "CLI tool for AI-driven WeChat miniprogram automation testing",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "agent-mp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "wechat",
+    "miniprogram",
+    "automation",
+    "testing",
+    "cli",
+    "ai",
+    "agent"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/cli.ts",
+    "cli": "tsx src/cli.ts",
+    "daemon": "tsx src/daemon/server.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "miniprogram-automator": "^0.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  }
+}

package/skills/agent-miniprogram/SKILL.md

@@ -0,0 +1,163 @@
+# Agent Miniprogram — Claude Code Skill
+
+## Trigger Conditions
+
+Use this skill when asked to:
+- Test, explore, or debug a WeChat miniprogram
+- Automate interactions in the WeChat Developer Tools simulator
+- Verify miniprogram UI behavior or page data
+- Run regression tests on a miniprogram
+
+## Setup
+
+The tool requires:
+1. WeChat Developer Tools installed, with "Security Settings → Enable HTTP Calls" turned on
+2. The daemon running: `agent-mp daemon`
+   - Or if running from source: `npm run daemon`
+
+All commands communicate with the daemon via HTTP at `localhost:9430`.
+
+## CLI Reference
+
+```bash
+# Session
+agent-mp launch <project-path>     # Launch DevTools + connect
+agent-mp connect [--ws <endpoint>] # Connect to already-running DevTools
+agent-mp status                    # Show connection status
+agent-mp close                     # Close connection
+
+# Inspection
+agent-mp snapshot                  # WXML tree with @eN refs (~200-400 tokens)
+agent-mp snapshot --data           # Also shows page.data
+agent-mp screenshot [--path <f>]   # Save screenshot
+agent-mp data [<dot.path>]         # Read page.data
+agent-mp diff snapshot             # Diff vs last snapshot
+
+# Navigation
+agent-mp navigate <url>            # Navigate to page
+agent-mp navigate <url> --type reLaunch|navigateTo|switchTab
+agent-mp back                      # Navigate back
+
+# Interaction (use @eN refs from snapshot)
+agent-mp tap <@ref|selector>
+agent-mp input <@ref|selector> <text>
+agent-mp scroll <@ref|selector> --x <n> --y <n>
+agent-mp long-press <@ref|selector>
+agent-mp swipe <@ref|selector> <up|down|left|right>
+
+# Advanced
+agent-mp wait <@ref|ms>            # Wait for element or duration
+agent-mp wait --text "some text"   # Wait for text to appear
+agent-mp eval "<js code>"          # Run JS in AppService
+agent-mp mock <api> '<json>'       # Mock wx.* API
+
+# Record / Replay
+agent-mp record start
+agent-mp record stop [--output <file.amp>]
+agent-mp replay <file.amp>
+```
+
+All commands support `--json` for structured output.
+
+## Workflow 1: Exploratory Testing
+
+```bash
+# 1. Start session
+agent-mp launch /path/to/miniprogram
+
+# 2. Observe current state
+agent-mp snapshot
+
+# 3. Interact using refs from snapshot
+agent-mp tap @e5         # tap the login button (ref from snapshot)
+agent-mp snapshot        # re-snapshot after action
+
+# 4. Fill in forms
+agent-mp input @e3 "13800138000"   # phone input
+agent-mp input @e4 "password123"   # password input
+agent-mp tap @e7                   # tap submit button
+
+# 5. Verify result
+agent-mp snapshot --data
+
+# 6. Close
+agent-mp close
+```
+
+## Workflow 2: Debug Workflow
+
+```bash
+agent-mp launch /path/to/miniprogram
+agent-mp navigate /pages/product/detail?id=123
+
+# Check page data
+agent-mp data
+
+# Execute JS in page context
+agent-mp eval "getCurrentPages()[0].data"
+
+# Take screenshot for visual inspection
+agent-mp screenshot --path /tmp/debug.png
+
+# Mock an API to test edge case
+agent-mp mock request '{"statusCode":200,"data":{"items":[]}}'
+agent-mp navigate /pages/list/index --type reLaunch
+agent-mp snapshot
+```
+
+## Workflow 3: Regression Testing (Record & Replay)
+
+```bash
+# Record a user flow
+agent-mp launch /path/to/miniprogram
+agent-mp record start
+agent-mp navigate /pages/index/index
+agent-mp tap @e3
+agent-mp input @e5 "test@example.com"
+agent-mp tap @e7
+agent-mp record stop --output tests/login-flow.amp
+
+# Later: replay to verify
+agent-mp launch /path/to/miniprogram
+agent-mp replay tests/login-flow.amp
+agent-mp snapshot --data
+```
+
+## Snapshot Format
+
+The `snapshot` command outputs a compact WXML tree:
+
+```
+Page: /pages/index/index
+
+[view @e1]
+  [image @e2] src="/img/logo.png"
+  [text @e3] "欢迎登录"
+[form @e4]
+  [input @e5] placeholder="手机号" (bindinput=onPhoneInput)
+  [input @e6] type="password" placeholder="密码" (bindinput=onPasswordInput)
+  [button @e7] "登录" (bindtap=onLogin)
+[navigator @e8] → /pages/register/index "注册账号"
+```
+
+Key rules:
+- `@eN` refs are stable within a session — use them instead of selectors
+- **After every navigation, run `snapshot` again** — refs reset on each snapshot call
+- Elements with `(bindtap)` are tappable
+- Elements with `(bindinput)` accept text input
+
+## Best Practices
+
+1. **Always snapshot after navigation** — page content changes, refs reset
+2. **Prefer refs over selectors** — `@e5` is cleaner than `.form > input:nth-child(2)`
+3. **Use `--data` to debug state** — `agent-mp snapshot --data` shows both UI and data
+4. **Use `diff snapshot` for assertions** — run before and after an action to see what changed
+5. **Use `eval` for complex assertions** — `agent-mp eval "getCurrentPages()[0].data.loginStatus"`
+6. **Mock network calls for deterministic tests** — `agent-mp mock request '...'`
+7. **Add `wait` after async operations** — e.g., `agent-mp wait 500` after a form submit
+
+## Error Handling
+
+- `Daemon not running` → run `agent-mp daemon` first
+- `Not connected` → run `agent-mp launch <path>` or `agent-mp connect`
+- `Element not found: @e5` → snapshot is stale, run `agent-mp snapshot` again