@zenalexa/unicli 0.211.2 → 0.213.0-beta.2

package/AGENTS.md

@@ -4,22 +4,24 @@
      Install: npm install -g @zenalexa/unicli
      Discover: unicli search "your intent" (bilingual EN/ZH)
      Run: unicli <site> <command> [args]
-     Output is JSON when piped. Errors are structured JSON to stderr.
+     Output is structured Markdown by default (non-TTY + agent UA auto-detected). Use -f json for JSON. Errors are structured envelopes to stderr.
      You can fix broken adapters yourself — read the Self-Repair section. -->
 
-> 198 sites, 1020 commands, 35 pipeline steps, BM25 bilingual search. `npm install -g @zenalexa/unicli`
+<!-- BEGIN COUNTS -->
+
+> <!-- STATS:site_count -->200<!-- /STATS --> sites, <!-- STATS:command_count -->968<!-- /STATS --> commands, <!-- STATS:pipeline_step_count -->54<!-- /STATS --> pipeline steps, BM25 bilingual search. `npm install -g @zenalexa/unicli`
+
+<!-- END COUNTS -->
 
 ## For AI Agents
 
-Universal CLI for websites, desktop apps, and local tools. JSON when piped. Self-repairing YAML adapters.
+Universal CLI for websites, desktop apps, and local tools. Markdown when piped (structured envelope). Self-repairing YAML adapters.
 
 ```bash
 unicli search "推特热门"             # Find commands by intent (bilingual)
-unicli search "download video"       # → bilibili download, yt-dlp download, ...
 unicli <site> <command> [options]    # Run any command
 unicli repair <site> <command>       # Diagnose + fix a broken adapter
-unicli test [site]                   # Verify adapters work
-unicli list                          # All commands (JSON when piped)
+unicli list                          # All commands (MD when piped)
 ```
 
 ## Install
@@ -28,61 +30,43 @@ unicli list                          # All commands (JSON when piped)
 npm install -g @zenalexa/unicli
 ```
 
+<!-- BEGIN ADAPTERS -->
+
 ## What You Can Do
 
-### Web (80+ sites)
+### Web (108+ sites)
 
-**Chinese**: bilibili (14), weibo (10), zhihu (9), douban (12), xueqiu (12),
-linux-do (10), jike (10), zsxq (5), tieba (4), weread (7), v2ex (12),
-xiaohongshu (14), douyin (13), 36kr (5), sspai (2), smzdm (4), taobao (2),
-pinduoduo (2), meituan (2), ctrip (2), netease-music (4), eastmoney (4),
-cnki, jd (4), 1688 (4), weixin (5), sinablog (5)
+**Chinese**: xiaohongshu (22), zhihu (21), bilibili (17), douyin (13), douban (12), v2ex (12), jike (10), linux-do (10), +33 more (`unicli list`)
 
-**International**: twitter (27), youtube (5), reddit (20), hackernews (10),
-bluesky (12), medium (5), substack (4), producthunt (5), lobsters (5), devto (5),
-stackoverflow (6), mastodon (4), facebook (12), instagram (21), tiktok (16),
-twitch (4), unsplash (2), pexels (2)
+**International**: twitter (34), instagram (26), reddit (20), tiktok (16), lesswrong (15), boss (14), bluesky (12), facebook (12), +38 more (`unicli list`)
 
-**AI / ML**: ollama (4), openrouter (2), hf (4), huggingface-papers (2),
-replicate (3), deepseek, perplexity, grok, gemini (5), minimax (3),
-doubao (3), doubao-web (9), novita (3), notebooklm (15)
+**AI / ML**: notebooklm (15), doubao-web (9), gemini (5), hf (4), ollama (4), doubao (3), minimax (3), novita (3), +6 more (`unicli list`)
 
-**Finance**: bloomberg (10), sinafinance (5), xueqiu (12), eastmoney (4),
-yahoo-finance (3), barchart (5)
+**Finance**: xueqiu (12), sinafinance (5), barchart (4), eastmoney (4), binance (3), yahoo-finance (3), coinbase (2), futu (2)
 
-**Developer**: github-trending (3), gitlab (3), gitee (3), npm (4),
-pypi (3), crates-io (3), cocoapods (2), docker-hub (3), npm-trends (2),
-homebrew (2), stackoverflow (6)
+**Developer**: stackoverflow (6), devto (5), producthunt (5), npm (4), crates-io (3), docker-hub (3), gitee (3), github-trending (3), +5 more (`unicli list`)
 
-**News**: bbc (4), cnn (2), nytimes (2), reuters (5), techcrunch (2),
-theverge (2), infoq (2), ithome (2)
+**News**: bloomberg (10), hackernews (10), 36kr (5), bbc (4), reuters (4), ithome (3), cnn (2), infoq (2), +3 more (`unicli list`)
 
-**Reference**: google (4), wikipedia (5), arxiv (3), dictionary (3),
-paperreview (3), spotify (4), ctrip (2), xiaoyuzhou (3), steam (6), imdb (7),
-exchangerate (2), ip-info, qweather (2), web
+**Reference**: imdb (7), wikipedia (5), google (4), netease-music (4), spotify (4), arxiv (3), dictionary (3), paperreview (3), +8 more (`unicli list`)
 
-### macOS (32 cmds)
+### macOS (58 cmds)
 
-reminders-list, reminders-complete, shortcuts-list, shortcuts-run,
-calendar-today, notes-list, contacts-search, spotlight, system-info,
-battery, disk-usage, clipboard, wifi-info, processes, open-app, say,
-screenshot, volume, brightness, apps-list, notification, trash, empty-trash,
-dark-mode, active-app, uptime, sleep, do-not-disturb, bluetooth,
-finder-selection, screen-lock, safari-tabs
+active-app, apps, apps-list, battery, bluetooth, brightness, caffeinate, calendar-create, calendar-list, calendar-today, clipboard, contacts-search, … (`unicli list --site macos`)
 
-### Desktop (15 apps)
+### Desktop (24 apps)
 
-ffmpeg (11 cmds), imagemagick (6), blender (4), gimp (3), freecad (2),
-inkscape (3), pandoc, libreoffice (2), mermaid, musescore (2), drawio,
-ollama (4), comfyui (4), docker (7), macos (32)
+freecad (15 cmds), blender (13 cmds), gimp (12 cmds), ffmpeg (11 cmds), audacity (8 cmds), docker (7 cmds), imagemagick (6 cmds), slay-the-spire-ii (6 cmds), +16 more (`unicli list --category desktop`)
 
 ### Bridge (3 CLIs)
 
-gh (5 cmds), yt-dlp (4), jq (2)
+gh (5 cmds), jq (2 cmds), yt-dlp (4 cmds)
+
+<!-- END ADAPTERS -->
 
 ## Authentication
 
-Some sites require cookies. The engine reads cookies from `~/.unicli/cookies/<site>.json`:
+Some sites require cookies:
 
 ```bash
 unicli auth setup <site>    # Show required cookies + template
@@ -90,145 +74,203 @@ unicli auth check <site>    # Validate cookie file
 unicli auth list            # List configured sites
 ```
 
-Cookie file format: `{ "SESSDATA": "value", "bili_jct": "value" }`
+Cookie file format: `{ "SESSDATA": "value", "bili_jct": "value" }`. Store at `~/.unicli/cookies/<site>.json`.
 
-Sites requiring auth: bilibili, weibo, zhihu, twitter, xueqiu, zsxq, jike, weread, douban, linux-do, v2ex (some commands)
+Sites requiring auth: bilibili, weibo, zhihu, twitter, xueqiu, zsxq, jike, weread, douban, linux-do, v2ex (some commands).
 
-## Output Protocol
+## Output Contract
 
-- **Piped** → auto-JSON, zero flags needed
-- **TTY** → human-readable table
-- **Errors** → structured JSON to stderr with `adapter` path, `step`, `suggestion`
-- **Exit codes**: 0=ok, 66=empty, 69=unavailable, 77=auth, 78=config
+Adapter dispatch, `core.*`, `ext.list`, and `dev.watch` return v2 `AgentEnvelope`. Format auto-selected — pipe or set agent UA env var to get structured Markdown. Admin commands migrate in v0.214.
 
-## External CLI Passthrough
+### Format auto-selection (priority order)
 
-32 external CLIs are registered for passthrough. If installed on your system, they're available as top-level commands:
+1. `--format` / `-f` flag (`json | yaml | md | csv | compact`)
+2. `UNICLI_OUTPUT` or `OUTPUT` env var (same values)
+3. Non-TTY stdout — defaults to `md`
+4. Agent UA env vars — if any is set, defaults to `md`
+5. `md` default for all other cases
 
-```bash
-unicli ext list                    # Show all external CLIs + install status
-unicli ext install <name>          # Install an external CLI
-unicli ext run <name> [args]       # Run explicitly
-unicli lark-cli calendar +agenda   # Direct passthrough (if installed)
+**Agent UA env vars** (set any to trigger md auto-selection):
+`CLAUDE_CODE`, `CODEX_CLI`, `OPENCODE`, `HERMES_AGENT`, `UNICLI_AGENT`
+
+### Envelope shape
+
+Success:
+
+```yaml
+ok: true
+schema_version: "2"
+command: "twitter.mentions"
+meta:
+  duration_ms: 412
+  count: 20
+  surface: web # web | desktop | system | mobile
+  pagination:
+    has_more: true
+    next_cursor: "abc123"
+data:
+  - { id: "...", text: "...", author: "..." }
+error: null
+```
+
+Error:
+
+```yaml
+ok: false
+schema_version: "2"
+command: "twitter.mentions"
+meta:
+  duration_ms: 91
+data: null
+error:
+  code: auth_required # see error codes below
+  message: "401 Unauthorized"
+  adapter_path: "src/adapters/twitter/mentions.yaml"
+  step: 1
+  suggestion: "Run: unicli auth setup twitter"
+  retryable: false
+  alternatives: ["twitter.search", "twitter.timeline"]
+```
+
+### MD body sections
+
+Success output shape:
+
+```markdown
+---
+ok: true
+schema_version: "2"
+command: twitter.mentions
+duration_ms: 412
+count: 20
+---
+
+## Data
+
+### 1 · 1912345678901234567
+
+- **author**: alice_dev
+- **text**: Hey @zenalexa love the new self-repair feature!
+- **date**: 2026-04-16
+
+## Context
+
+- **surface**: web
+- **has_more**: true
+- **next_cursor**: abc123
+
+## Next Actions
+
+- Fetch next page with cursor: `abc123`
 ```
 
-Key CLIs: lark-cli (200+ cmds), wecom-cli (100+), dws (86), vercel, supabase, stripe, firebase, wrangler, aliyun (1000+), tccli (500+).
+Error output shape:
+
+```markdown
+---
+ok: false
+schema_version: "2"
+command: twitter.mentions
+duration_ms: 91
+---
+
+## Error
+
+- **code**: auth_required
+- **message**: 401 Unauthorized
+- **adapter_path**: src/adapters/twitter/mentions.yaml
+- **step**: 1
+- **retryable**: false
+
+## Suggestion
+
+Run: unicli auth setup twitter
+
+## Alternatives
+
+- `twitter.search`
+- `twitter.timeline`
+```
+
+### Error codes
+
+`selector_miss` `auth_required` `not_found` `rate_limited` `network_error`
+`invalid_input` `not_authenticated` `upstream_error` `internal_error`
+`api_error` `permission_denied`
+
+`quarantined` also emitted by dispatch. Remaining codes reserved for future transports.
+
+### Exit codes
+
+0 ok · 66 empty · 69 unavailable · 75 temp-fail · 77 auth · 78 config
 
 ## Self-Repair Protocol
 
-When a command fails, you can fix it:
+When a command fails:
 
 ```
-1. Read error JSON → get adapter path
-2. Read the YAML file (20 lines, no imports)
-3. Edit the YAML (URL changed? selector moved? auth needed?)
+1. Read error envelope (MD or JSON) → get adapter_path
+2. Open the YAML (~20 lines, no imports)
+3. Edit the failing step (URL changed, selector moved, auth needed)
 4. Save to ~/.unicli/adapters/<site>/<command>.yaml
 5. Verify: unicli repair <site> <command>
 ```
 
 Fixes persist in `~/.unicli/adapters/` and survive `npm update`.
 
-## Creating New Adapters
-
-Drop a YAML file into `src/adapters/<site>/<command>.yaml`:
+## Creating Adapters
 
 ```yaml
 site: example
 name: search
-description: Search example.com
 type: web-api
 strategy: public
-
 pipeline:
-  - fetch:
-      url: "https://api.example.com/search"
-      params:
-        q: "${{ args.query }}"
+  - fetch: { url: "https://api.example.com/search?q=${{ args.query }}" }
   - select: data.results
-  - map:
-      title: "${{ item.title }}"
-      url: "${{ item.url }}"
+  - map: { title: "${{ item.title }}", url: "${{ item.url }}" }
   - limit: ${{ args.limit }}
-
 args:
-  query:
-    type: str
-    required: true
-    positional: true
-  limit:
-    type: int
-    default: 20
-
+  query: { type: str, required: true, positional: true }
+  limit: { type: int, default: 20 }
 columns: [title, url]
 ```
 
-That's it. No TypeScript, no build step, no imports. The engine handles everything.
+Full reference: [`docs/ADAPTER-FORMAT.md`](docs/ADAPTER-FORMAT.md).
 
-## Browser Automation
+## Pipeline Steps
 
-For sites that require a real browser (intercept/UI strategy):
+31 steps across 5 families — api (fetch, fetch_text, parse_rss, html_to_md), transform (select, map, filter, sort, limit), control (set, if, each, parallel, rate_limit, assert, retry, append), browser (navigate, evaluate, click, type, press, scroll, intercept, snapshot, tap, extract, wait), other (exec, write_temp, download, websocket). See [`docs/ADAPTER-FORMAT.md`](docs/ADAPTER-FORMAT.md) for the full table with examples.
+
+## MCP Server
 
 ```bash
-unicli browser start          # Launch Chrome with CDP
-unicli browser status         # Check connection
+npx @zenalexa/unicli mcp serve                                # stdio (4 meta-tools)
+npx @zenalexa/unicli mcp serve --transport streamable --port 19826
+npx @zenalexa/unicli mcp serve --transport sse --port 19826   # SSE for remote
+npx @zenalexa/unicli mcp serve --auth                         # OAuth 2.1 PKCE
 ```
 
-Requires Chrome. The engine connects via raw CDP WebSocket — zero extensions needed.
-
-## Pipeline Steps (35)
-
-| Step         | What it does                                     |
-| ------------ | ------------------------------------------------ |
-| `fetch`      | HTTP JSON (GET/POST, retry, backoff, cookies)    |
-| `fetch_text` | HTTP raw text (RSS, HTML)                        |
-| `parse_rss`  | Extract RSS + Atom feed items                    |
-| `html_to_md` | Convert HTML to Markdown                         |
-| `select`     | Navigate into JSON (`data.items`)                |
-| `map`        | Transform each item via `${{ }}` templates       |
-| `filter`     | Keep matching items                              |
-| `sort`       | Sort by field                                    |
-| `limit`      | Cap results                                      |
-| `exec`       | Run subprocess (stdin, env, file output)         |
-| `write_temp` | Create temp script file (for desktop adapters)   |
-| `navigate`   | Navigate Chrome to URL via CDP                   |
-| `evaluate`   | Execute JavaScript in page context               |
-| `click`      | Click element by CSS selector                    |
-| `type`       | Type text into input element                     |
-| `wait`       | Wait for time (ms) or CSS selector to appear     |
-| `intercept`  | Capture page network requests matching a pattern |
-| `press`      | Keyboard key with modifiers (Ctrl+A, Enter)      |
-| `scroll`     | Direction scroll, auto-scroll to bottom          |
-| `snapshot`   | DOM accessibility tree with interactive refs     |
-| `tap`        | Vue Store Action Bridge (Pinia/Vuex → network)   |
-| `download`   | HTTP + yt-dlp, batch concurrent, skip_existing   |
-| `websocket`  | WebSocket connect/send/receive (OBS auth)        |
-| `set`        | Store variables into `vars` context              |
-| `if`         | Conditional execution of sub-pipeline branches   |
-| `append`     | Push ctx.data into vars array for accumulation   |
-| `each`       | Loop sub-pipeline with do-while + max iterations |
-| `parallel`   | Run sub-pipelines concurrently with merge        |
-| `rate_limit` | Per-domain token bucket request throttling       |
-| `assert`     | Verify page state (URL, selector, text)          |
-| `extract`    | Structured data extraction with CSS + types      |
-| `retry`      | Generic retry with exponential backoff           |
-
-## Strategies
-
-`public` → `cookie` → `header` → `intercept` → `ui`
-
-The engine auto-probes the first three on first run. `intercept` and `ui` require explicit configuration per adapter.
+Default tools: `unicli_run`, `unicli_list`, `unicli_search`, `unicli_explore`. Agents call `unicli_search` first (bilingual BM25), then `unicli_run` with the chosen site + command.
 
-## MCP Server
+## ACP (avante.nvim / Zed)
 
 ```bash
-npx @zenalexa/unicli mcp serve              # stdio (default, 4 meta-tools)
-npx @zenalexa/unicli mcp serve --expanded   # all 1020 tools with full schemas
-npx @zenalexa/unicli mcp serve --transport sse --port 19826  # SSE for remote
-npx @zenalexa/unicli mcp serve --auth       # OAuth 2.1 PKCE
+unicli acp          # JSON-RPC 2.0 over stdio
 ```
 
-Default tools: `unicli_run` (execute), `unicli_list` (browse), `unicli_search` (BM25 bilingual discovery), `unicli_explore` (auto-discover from URL).
+See [`docs/AVANTE.md`](docs/AVANTE.md).
+
+## External CLI Passthrough
+
+35 registered external CLIs. If installed on your system, they're available as top-level commands:
+
+```bash
+unicli ext list                    # Show all external CLIs + install status
+unicli ext install <name>          # Install an external CLI
+unicli lark-cli calendar +agenda   # Direct passthrough
+```
 
 ## Version
 
-0.211.2 — Vostok · Volynov
+0.213.0-beta.2 — Vostok · Gagarin