@agentrhq/webcmd 0.1.1 → 0.2.0

package/skills/webcmd-usage/SKILL.md

@@ -1,170 +1,179 @@
 ---
 name: webcmd-usage
-description: Use at the start of any Webcmd session — this is the top-level map of what `webcmd` can do, how to discover adapters, what flags and output formats are universal, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?".
+description: Use at the start of any Webcmd session. This is the top-level map of what `webcmd` can do, how to discover adapters, what flags and output formats are universal, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?".
 allowed-tools: Bash(webcmd:*), Read
 ---
 
 # webcmd-usage
 
-Webcmd turns any website, Electron desktop app, or external CLI into a uniform `webcmd <site> <command>` surface that agents can drive without screen-scraping. This skill is the orientation layer — once you know what you want to do, load one of the specialized skills below.
+Webcmd turns websites, Electron desktop apps, and external CLIs into a uniform `webcmd <site> <command>` surface that agents can drive without screen scraping. This skill is the orientation layer. Once you know the task, load the specialized skill that fits it.
 
-## The three pillars
+## The Three Pillars
 
-- **Adapter commands** — `webcmd <site> <command> [...]`. Built-in adapters live in `clis/`, user adapters in `~/.webcmd/clis/`. Each is backed by a strategy (`PUBLIC | COOKIE | INTERCEPT | UI | LOCAL`) that tells you whether a Chrome session is needed.
-- **Browser driving** — `webcmd browser *` subcommands (`open`, `state`, `click`, `type`, `select`, `find`, `extract`, `network`, …) for ad-hoc interaction and scraping when no adapter covers the task. See `webcmd-browser`.
-- **Cloak-tab binding** — `webcmd browser <session> bind --page <page-id>` attaches an existing webcmd-managed Cloak tab to that browser session. Run `webcmd browser <session> tab list` first; follow-up commands use `webcmd browser <session> ...`. See `webcmd-browser` before using it.
-- **External CLI passthrough** — `webcmd gh`, `webcmd docker`, `webcmd vercel`, etc. Managed via `webcmd external install <name>` (auto-install from `external-clis.yaml`) or `webcmd external register <name>` (bring your own).
+- **Adapter commands:** `webcmd <site> <command> [...]`. Built-in adapters live in `clis/`; user adapters live in `~/.webcmd/clis/`. Each command has a strategy such as `PUBLIC`, `COOKIE`, `INTERCEPT`, `UI`, or `LOCAL`.
+- **Browser driving:** `webcmd browser *` subcommands (`open`, `state`, `click`, `type`, `select`, `find`, `extract`, `network`) for ad-hoc interaction when no adapter covers the task. See `webcmd-browser`.
+- **External CLI passthrough:** `webcmd gh`, `webcmd docker`, `webcmd vercel`, and similar wrappers. Manage them with `webcmd external install <name>` or `webcmd external register <name>`.
 
 ## Install
 
 ```bash
-# npm global
-npm install -g @agentrhq/webcmd          # binary: webcmd, requires Node >= 21
-webcmd doctor                              # run before browser-dependent work (see below)
+npm install -g @agentrhq/webcmd
+webcmd doctor
+```
+
+From source:
 
-# From source
+```bash
 git clone git@github.com:agentrhq/webcmd.git
-cd webcmd && npm install
-npx tsx src/main.ts <command>               # same surface, no global install
+cd webcmd
+npm install
+npx tsx src/main.ts <command>
 ```
 
-`webcmd doctor` prints a structured `DoctorReport` — daemon status, runtime connection, version checks, and a live browser connectivity probe. Scope is narrow: it diagnoses the **browser runtime** (daemon + CloakBrowser wiring). `PUBLIC` / `LOCAL` adapters, `webcmd list`, `validate`, `verify`, plugin commands, and external-CLI passthrough don't need it to be green — only `COOKIE` / `INTERCEPT` / `UI` adapters and the `webcmd browser *` subcommands do. Flag: `-v` (verbose).
+`webcmd doctor` reports daemon status, runtime connection, version checks, and live browser connectivity. It is required for `COOKIE`, `INTERCEPT`, `UI`, and `webcmd browser *` work. It is not required for `PUBLIC`, `LOCAL`, `webcmd list`, `validate`, `verify`, plugin commands, or external CLI passthrough.
 
-## Prerequisites by command type
+## Prerequisites By Strategy
 
-| Strategy tag on `webcmd list` | What it needs |
-|--------------------------------|---------------|
-| `PUBLIC` | Nothing — pure HTTP, no browser. |
-| `COOKIE` | Logged into the target site in the webcmd-managed CloakBrowser profile. Existing Chrome logins are not imported, so run the site's login command again. |
-| `INTERCEPT` | Same as COOKIE, plus webcmd opens an automation window to capture a signed request. |
-| `UI` | Same as COOKIE, full DOM interaction. |
-| `LOCAL` | No browser; talks to a local/dev endpoint. |
+| Strategy | Needs |
+| --- | --- |
+| `PUBLIC` | No browser; pure HTTP. |
+| `COOKIE` | Logged into the target site in the webcmd-managed browser profile. |
+| `INTERCEPT` | Same as `COOKIE`, plus an automation window to capture a signed request. |
+| `UI` | Same as `COOKIE`, plus full DOM interaction. |
+| `LOCAL` | No browser; talks to a local or development endpoint. |
 
-Electron desktop apps (cursor, codex, chatwise, discord-app, doubao-app, antigravity, chatgpt-app) route through CDP against the running app — same cookie-less flow as a logged-in browser. Make sure the app is running before invoking.
+Electron desktop app adapters route through CDP against the running app. Make sure the app is open before invoking those commands.
 
-## Discover what's installed — don't read this file, run a command
+## Discover Installed Commands
+
+Run commands instead of reading static docs:
 
 ```bash
-webcmd list                    # table, grouped by site
-webcmd list -f json            # machine-readable; pipe to jq or your agent
-webcmd list | grep -i twitter  # find commands for a specific site
-webcmd <site> --help           # see that site's commands + flags
-webcmd <site> <command> --help # see positional args and command-specific flags
+webcmd list
+webcmd list -f json
+webcmd list | grep -i github
+webcmd <site> --help
+webcmd <site> <command> --help
 ```
 
-Do not hard-code adapter lists — there are 100+ sites and the count moves every week. `webcmd list -f json` is the source of truth; it emits one entry per command with `{site, name, aliases, description, strategy, browser, args, columns, ...}`. For an agent, that is always better than grepping a doc.
+Do not hard-code adapter lists. `webcmd list -f json` is the source of truth and emits one entry per command with fields such as `{site, name, aliases, description, strategy, browser, args, columns}`.
 
-Before falling back to raw `webcmd browser` commands on high-change authenticated sites, check whether a site adapter already exposes the workflow. For example, ChatGPT web has higher-level commands for conversation reads and Deep Research result extraction; discover the current surface with `webcmd chatgpt --help` or `webcmd list -f json`.
+Before falling back to raw `webcmd browser` on high-change authenticated sites, check whether a site adapter already exposes the workflow.
 
-## Universal flags (work on every adapter command)
+## Universal Flags
 
-| flag | effect |
-|------|--------|
-| `-f, --format <fmt>` | `table` (default in TTY) · `yaml` (default in non-TTY) · `json` · `plain` · `md` · `csv`. Pass explicitly when you want a specific shape; agents almost always want `-f json`. |
-| `-v, --verbose` | Debug logs + stack traces on failure; also sets `WEBCMD_VERBOSE=1` for the process. |
+| Flag | Effect |
+| --- | --- |
+| `-f, --format <fmt>` | `table` in TTY by default; `yaml` outside TTY by default; also supports `json`, `plain`, `md`, `csv`. Agents usually want `-f json`. |
+| `-v, --verbose` | Debug logs and stack traces on failure; also sets `WEBCMD_VERBOSE=1`. |
 
-Command-specific flags (`--limit`, `--tab`, `--filter`, …) are not universal — consult `<site> <command> --help`.
+Command-specific flags such as `--limit`, `--tab`, and `--filter` are not universal. Read `<site> <command> --help`.
 
-## Output formats
+## Output Formats
 
-- `json` — pretty-printed, 2-space indent. Default choice for agents.
-- `plain` — prints a single primary field for chat-style commands (`response`/`content`/`text`/`value`). Useful for piping to another tool.
-- `yaml` — fallback when output is not a TTY and `-f` is not explicit.
-- `table` — color-coded, site-grouped; meant for humans.
-- `md`, `csv` — straightforward tabular dumps.
+- `json`: pretty-printed, 2-space indent. Best default for agents.
+- `plain`: prints the primary text field for chat-style commands.
+- `yaml`: default when output is not a TTY and `-f` is not explicit.
+- `table`: color-coded and grouped for humans.
+- `md`, `csv`: tabular dumps.
 
-A few commands override the default via `cmd.defaultFormat` (e.g. chat commands default to `plain`), so don't assume without reading `--help`.
+Some commands override the default through `cmd.defaultFormat`; read `--help`.
 
-## Environment variables
+## Environment Variables
 
-| variable | default | purpose |
-|----------|---------|---------|
+| Variable | Default | Purpose |
+| --- | --- | --- |
 | `WEBCMD_BROWSER_CONNECT_TIMEOUT` | `45` | Seconds to wait for the browser bridge. |
 | `WEBCMD_BROWSER_COMMAND_TIMEOUT` | `60` | Per-command timeout. |
-| `WEBCMD_CDP_ENDPOINT` | — | Manual CDP endpoint override (dev / remote Chrome / Electron). |
-| `WEBCMD_CACHE_DIR` | `~/.webcmd/cache` | Network capture + browser-state cache. |
+| `WEBCMD_CDP_ENDPOINT` | unset | Manual CDP endpoint override. |
+| `WEBCMD_CACHE_DIR` | `~/.webcmd/cache` | Network capture and browser-state cache. |
 | `WEBCMD_WINDOW` | command-specific | `foreground` or `background` browser window mode. |
-| `WEBCMD_VERBOSE` | `false` | Verbose logging (also triggered by `-v`). |
+| `WEBCMD_VERBOSE` | `false` | Verbose logging, also triggered by `-v`. |
 
-## Self-repair
+## Self-Repair
 
-When an adapter command fails because the site changed (selectors drifted, API rotated, response schema shifted), re-run with `--trace retain-on-failure`. The error envelope includes a `trace` block pointing at `summary.md`; patch only the `adapterSourcePath` from that summary and retry. Max 3 repair rounds. The full flow is in `webcmd-autofix`.
+When an adapter command fails because a site changed, rerun with:
 
-## Writing your own adapter
+```bash
+webcmd <site> <command> [args...] --trace retain-on-failure
+```
 
-Two-path storage:
+The error envelope includes a `trace` block pointing at `summary.md`. Patch only `adapterSourcePath` from that summary and retry. Maximum 3 repair rounds. See `webcmd-autofix`.
 
-- **Private**: `~/.webcmd/clis/<site>/<command>.js` — no build step, hot-available, not visible in the public package.
-- **Public / PR**: `clis/<site>/<command>.js` — for upstream contribution; requires build.
+## Writing An Adapter
 
-Scaffolding & verification:
+Two storage paths:
+
+- Private: `~/.webcmd/clis/<site>/<command>.js`
+- Public / PR: `clis/<site>/<command>.js`
+
+Scaffolding and checks:
 
 ```bash
-webcmd browser init <site>/<command>   # generates a skeleton
-webcmd validate [target]               # semantic checks on the loaded registry (description, domain, pipeline step names, func|pipeline|_lazy presence, arg duplicates) — no network, no browser
-webcmd verify [target] [--smoke]       # run the command with synthetic args
-webcmd browser verify <site>/<command> # end-to-end smoke inside the bridge
+webcmd browser init <site>/<command>
+webcmd validate [target]
+webcmd verify [target] [--smoke]
+webcmd browser verify <site>/<command>
 ```
 
-Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`. `columns` must align 1:1 (in name and order) with keys of the object returned by `func`. For the full workflow see `webcmd-adapter-author`.
+Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`. `columns` must align one-to-one, in name and order, with returned row object keys. See `webcmd-adapter-author`.
 
 ## Plugins
 
-Plugins are third-party extensions pulled from git, separate from the main adapter registry:
-
 ```bash
-webcmd plugin install github:user/repo    # install
-webcmd plugin list [-f json]              # see installed
-webcmd plugin update [name] | --all       # keep current
+webcmd plugin install github:user/repo
+webcmd plugin list [-f json]
+webcmd plugin update [name] | --all
 webcmd plugin uninstall <name>
-webcmd plugin create <name>               # scaffold a new plugin
+webcmd plugin create <name>
 ```
 
-## External CLI passthrough
+Plugins are third-party extensions pulled from git and separate from the main adapter registry.
 
-Wraps external command-line tools so you can discover + invoke them through the same `webcmd …` entrypoint:
+## External CLI Passthrough
 
 ```bash
-webcmd external install gh    # auto-install via brew/apt/npm per external-clis.yaml
+webcmd external install gh
 webcmd external register my-tool \
-    --binary my-tool \
-    --install "npm i -g my-tool" \
-    --desc "My internal CLI"
+  --binary my-tool \
+  --install "npm i -g my-tool" \
+  --desc "My internal CLI"
 webcmd external list
-webcmd gh pr list --limit 5   # passthrough; stdio is inherited, exit code propagated
+webcmd gh pr list --limit 5
 webcmd docker ps
 ```
 
-Built-in entries live in `src/external-clis.yaml`; user overrides and additions in `~/.webcmd/external-clis.yaml`. Commonly shipped: `gh`, `docker`, `vercel`, `lark-cli`, `longbridge`, `dws`, `wecom-cli`, `obsidian`, `ntn`, `tg(tg-cli)`, `discord(discord-cli)`, `wx(wx-cli)`.
+Built-in entries live in `src/external-clis.yaml`; user overrides live in `~/.webcmd/external-clis.yaml`.
 
-Some official CLIs use shell-script installers instead of a shell-free package-manager command. Entries without an `install` config, such as `ntn`, must be installed manually from their homepage before passthrough use.
-
-## Shell completion
+## Shell Completion
 
 ```bash
-webcmd completion bash   # also: zsh, fish
-# -> script on stdout; source or save per your shell's convention
+webcmd completion bash
+webcmd completion zsh
+webcmd completion fish
 ```
 
-## Where to go next
+The script prints to stdout; source or save it according to your shell.
+
+## Where To Go Next
 
-| If you're about to… | Load this skill |
-|---------------------|-----------------|
-| Drive a live browser ad-hoc (no adapter available, or prototyping) | `webcmd-browser` |
-| Write a new adapter, or add a command to an existing site | `webcmd-adapter-author` |
-| Fix a broken adapter after a command failure | `webcmd-autofix` |
-| Route a search / lookup / research request to the right adapter | `smart-search` |
+| Task | Load |
+| --- | --- |
+| Drive a live browser ad-hoc | `webcmd-browser` |
+| Write a new adapter or command | `webcmd-adapter-author` |
+| Fix a broken adapter after failure | `webcmd-autofix` |
+| Route a search or research request | `smart-search` |
 
-## Commands that used to exist
+## Removed Commands
 
-The following were removed in the PR #1094 consolidation — don't try to invoke them:
+Do not invoke these removed commands:
 
-- `webcmd explore <url>` — superseded by `webcmd browser network` + `webcmd browser find` for live API discovery, and by the `webcmd-adapter-author` workflow for capture.
-- `webcmd record <url>` — removed; manual capture now lives in `webcmd browser network --detail`.
-- `webcmd web read` / `webcmd desktop *` as top-level groups — folded into their respective adapters (`webcmd web read` still exists as the `web` adapter's `read` command, but there is no standalone `web` / `desktop` top-level group command).
+- `webcmd explore <url>`: use `webcmd browser network` and `webcmd browser find`, or the `webcmd-adapter-author` workflow.
+- `webcmd record <url>`: manual capture now lives in `webcmd browser network --detail`.
+- Top-level `webcmd web read` / `webcmd desktop *` groups: use their adapters instead.
 
-## Don't
+## Do Not
 
-- Don't paste this skill's command list into your plan; it will rot. Call `webcmd list -f json` at the start of a task instead.
-- Don't assume every adapter needs a browser — strategy `PUBLIC` and `LOCAL` don't. Check the `strategy` field.
-- Don't silently fall back from a failing adapter to a hand-rolled `fetch` — `--trace retain-on-failure` gives you the browser evidence and adapter source path. Do that first.
+- Do not paste static command lists into plans; call `webcmd list -f json`.
+- Do not assume every adapter needs a browser; check `strategy`.
+- Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first.

package/clis/12306/auth.js

@@ -1,59 +0,0 @@
-import { AuthRequiredError, CommandExecutionError } from '@agentrhq/webcmd/errors';
-import { registerSiteAuthCommands } from '../_shared/site-auth.js';
-
-async function has12306SessionCookie(page) {
-  const cookies = await page.getCookies({ url: 'https://kyfw.12306.cn' });
-  return cookies.some(c => c.name === 'tk' && c.value);
-}
-
-async function verify12306Identity(page) {
-  if (!await has12306SessionCookie(page)) {
-    throw new AuthRequiredError('12306.cn', '12306 tk auth cookie missing');
-  }
-  await page.goto('https://kyfw.12306.cn/otn/view/index.html');
-  await page.wait(2);
-  const probe = await page.evaluate(`(async () => {
-    try {
-      const r = await fetch('/otn/index/initMy12306Api', {
-        method: 'POST',
-        credentials: 'include',
-        headers: { 'X-Requested-With': 'XMLHttpRequest' },
-      });
-      if (/login\\.html/.test(r.url)) {
-        return { kind: 'auth', detail: '12306 initMy12306Api redirected to login' };
-      }
-      const t = await r.text();
-      let d = null;
-      try { d = JSON.parse(t); } catch {}
-      if (!d || d.status === false || /未登录|登录超时|NotLogin/i.test(t)) {
-        return { kind: 'auth', detail: '12306 initMy12306Api returned NotLogin' };
-      }
-      const userName = d.data?.user_name || d.data?.userName || d.user_name || '';
-      if (!userName) {
-        return { kind: 'auth', detail: '12306 initMy12306Api 200 but no user_name surface' };
-      }
-      return { ok: true, user_name: String(userName) };
-    } catch (e) {
-      return { kind: 'exception', detail: String(e && e.message || e) };
-    }
-  })()`);
-  if (probe?.kind === 'auth') throw new AuthRequiredError('12306.cn', probe.detail);
-  if (probe?.kind === 'exception') throw new CommandExecutionError(`12306 whoami failed: ${probe.detail}`);
-  if (!probe?.ok) throw new CommandExecutionError(`Unexpected 12306 probe: ${JSON.stringify(probe)}`);
-  return { user_name: probe.user_name };
-}
-
-registerSiteAuthCommands({
-  site: '12306',
-  domain: '12306.cn',
-  loginUrl: 'https://kyfw.12306.cn/otn/resources/login.html',
-  columns: ['user_name'],
-  quickCheck: has12306SessionCookie,
-  verify: verify12306Identity,
-  poll: async (page) => {
-    if (!await has12306SessionCookie(page)) {
-      throw new AuthRequiredError('12306.cn', 'Waiting for 12306 tk auth cookie');
-    }
-    return verify12306Identity(page);
-  },
-});

package/clis/12306/me.js

@@ -1,73 +0,0 @@
-/**
- * 12306 account summary for the logged-in user.
- *
- * Returns non-sensitive identity fields plus masked email / mobile.
- * Use `--include-sensitive` to surface unmasked values from 12306's
- * own response (12306 already masks the ID number server-side; this
- * adapter never decodes that mask).
- */
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
-import { AuthRequiredError, CommandExecutionError } from '@agentrhq/webcmd/errors';
-import { isAuthLikePayload, maskEmail, maskMobile, maskChineseName, require12306Login, requireEvaluateObject } from './utils.js';
-
-const ACCOUNT_INFO_URL = 'https://kyfw.12306.cn/otn/modifyUser/initQueryUserInfoApi';
-
-cli({
-    site: '12306',
-    name: 'me',
-    access: 'read',
-    description: 'Show the logged-in 12306 account summary. Sensitive fields (real name, email, mobile, birth date) are masked by default; pass --include-sensitive to opt in.',
-    domain: 'kyfw.12306.cn',
-    strategy: Strategy.COOKIE,
-    browser: true,
-    args: [
-        { name: 'include-sensitive', type: 'boolean', default: false, help: 'Reveal unmasked real name / email / mobile / birth date. The 12306 ID-number mask is server-side and never decoded.' },
-    ],
-    columns: ['username', 'real_name', 'email', 'mobile', 'birth_date', 'sex', 'country', 'user_type', 'member', 'active'],
-    func: async (page, kwargs) => {
-        if (!page) throw new CommandExecutionError('Browser session required for 12306 me');
-        await page.goto('https://kyfw.12306.cn/otn/view/index.html');
-        await require12306Login(page, AuthRequiredError);
-        const json = requireEvaluateObject(await page.evaluate(`async () => {
-      const r = await fetch(${JSON.stringify(ACCOUNT_INFO_URL)}, { credentials: 'include' });
-      if (!r.ok) return { __http: r.status };
-      try {
-        return await r.json();
-      } catch (err) {
-        return { __parse: String(err && err.message || err) };
-      }
-    }`), 'account info');
-        if (json?.__http) {
-            if ([401, 403].includes(Number(json.__http))) {
-                throw new AuthRequiredError('kyfw.12306.cn', '12306 account info requires a valid login session');
-            }
-            throw new CommandExecutionError(`12306 returned HTTP ${json.__http} for account info`);
-        }
-        if (json?.__parse) {
-            throw new CommandExecutionError(`12306 account info returned non-JSON body: ${json.__parse}`);
-        }
-        if (isAuthLikePayload(json)) {
-            throw new AuthRequiredError('kyfw.12306.cn', '12306 account info requires a valid login session');
-        }
-        if (json?.status !== true || !json?.data?.userDTO) {
-            throw new CommandExecutionError('12306 account info payload missing userDTO');
-        }
-        const dto = json.data.userDTO;
-        const loginDto = dto.loginUserDTO || {};
-        const username = loginDto.user_name || loginDto.name || '';
-        const realName = loginDto.real_name || loginDto.realname || '';
-        const include = kwargs['include-sensitive'] === true;
-        return [{
-            username,
-            real_name: include ? realName : maskChineseName(realName),
-            email: include ? (dto.email || '') : maskEmail(dto.email || ''),
-            mobile: include ? (dto.mobile_no || '') : maskMobile(dto.mobile_no || ''),
-            birth_date: include ? (dto.born_date || '') : (dto.born_date || '').slice(0, 4),
-            sex: dto.sex_code === 'M' ? '男' : (dto.sex_code === 'F' ? '女' : ''),
-            country: dto.country_code || '',
-            user_type: json.data.userTypeName || '',
-            member: dto.flag_member === '1',
-            active: dto.is_active === '1',
-        }];
-    },
-});

package/clis/12306/orders.js

@@ -1,96 +0,0 @@
-/**
- * 12306 in-progress orders for the logged-in user.
- *
- * Returns orders that have not yet been ridden / refunded / completed
- * (the `noComplete` slice). Order history covering completed and
- * refunded tickets uses a separate endpoint that requires extra
- * referer / page-state handshakes and is left for a follow-up so this
- * command can ship reliably.
- */
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
-import { AuthRequiredError, CommandExecutionError, EmptyResultError } from '@agentrhq/webcmd/errors';
-import { isAuthLikePayload, maskChineseName, require12306Login, requireEvaluateObject } from './utils.js';
-
-const NO_COMPLETE_URL = 'https://kyfw.12306.cn/otn/queryOrder/queryMyOrderNoComplete';
-
-cli({
-    site: '12306',
-    name: 'orders',
-    access: 'read',
-    description: 'List in-progress 12306 orders (not yet ridden, refunded, or completed) for the logged-in user',
-    domain: 'kyfw.12306.cn',
-    strategy: Strategy.COOKIE,
-    browser: true,
-    args: [
-        { name: 'include-sensitive', type: 'boolean', default: false, help: 'Reveal unmasked passenger names in order rows. Masked by default.' },
-    ],
-    columns: ['order_id', 'order_date', 'train_code', 'from_station', 'to_station', 'departure', 'passengers', 'status', 'amount'],
-    func: async (page, kwargs) => {
-        if (!page) throw new CommandExecutionError('Browser session required for 12306 orders');
-        await page.goto('https://kyfw.12306.cn/otn/view/index.html');
-        await require12306Login(page, AuthRequiredError);
-        const include = kwargs['include-sensitive'] === true;
-        const json = requireEvaluateObject(await page.evaluate(`async () => {
-      const r = await fetch(${JSON.stringify(NO_COMPLETE_URL)}, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: '_json_att=', credentials: 'include',
-      });
-      if (!r.ok) return { __http: r.status };
-      try {
-        return await r.json();
-      } catch (err) {
-        return { __parse: String(err && err.message || err) };
-      }
-    }`), 'orders');
-        if (json?.__http) {
-            if ([401, 403].includes(Number(json.__http))) {
-                throw new AuthRequiredError('kyfw.12306.cn', '12306 orders requires a valid login session');
-            }
-            throw new CommandExecutionError(`12306 returned HTTP ${json.__http} for queryMyOrderNoComplete`);
-        }
-        if (json?.__parse) {
-            throw new CommandExecutionError(`12306 orders returned non-JSON body: ${json.__parse}`);
-        }
-        if (isAuthLikePayload(json)) {
-            throw new AuthRequiredError('kyfw.12306.cn', '12306 orders requires a valid login session');
-        }
-        if (json?.status !== true) {
-            throw new CommandExecutionError('12306 queryMyOrderNoComplete returned a failure status');
-        }
-        let orders;
-        if (Array.isArray(json?.data?.orderDBList)) {
-            orders = json.data.orderDBList;
-        } else if (Array.isArray(json?.data?.orderDTODataList)) {
-            orders = json.data.orderDTODataList;
-        } else if (Array.isArray(json?.data?.orders)) {
-            orders = json.data.orders;
-        } else if (Array.isArray(json?.data)) {
-            orders = json.data;
-        } else {
-            throw new CommandExecutionError('12306 queryMyOrderNoComplete payload missing order list array');
-        }
-        if (orders.length === 0) {
-            throw new EmptyResultError('No in-progress 12306 orders on this account');
-        }
-        return orders.map((o) => {
-            const tickets = Array.isArray(o.tickets) ? o.tickets : [];
-            const passengerNames = tickets
-                .map((t) => t.passenger_name || '')
-                .filter(Boolean)
-                .map((name) => include ? name : maskChineseName(name))
-                .join(', ');
-            return {
-                order_id: o.sequence_no || o.order_id || o.sequenceNo || '',
-                order_date: o.order_date || '',
-                train_code: o.train_code_page || o.station_train_code || o.train_code || '',
-                from_station: o.from_station_name_page || o.from_station_name || '',
-                to_station: o.to_station_name_page || o.to_station_name || '',
-                departure: o.start_train_date_page || o.start_train_date || '',
-                passengers: passengerNames,
-                status: o.ticket_status_name || o.order_status_name || o.statusName || '',
-                amount: o.ticket_total_price_page || o.ticket_total_price || '',
-            };
-        });
-    },
-});

package/clis/12306/passengers.js

@@ -1,90 +0,0 @@
-/**
- * 12306 saved passenger list for the logged-in user.
- *
- * 12306 already masks ID numbers (`xxxx***********xxx`) and mobile
- * numbers (`138****xxxx`) server-side. This adapter further masks the
- * passenger's Chinese real name and birth date by default; pass
- * `--include-sensitive` to surface the unmasked-by-12306 fields.
- */
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
-import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@agentrhq/webcmd/errors';
-import { isAuthLikePayload, maskChineseName, require12306Login, requireEvaluateObject } from './utils.js';
-
-const PASSENGER_QUERY_URL = 'https://kyfw.12306.cn/otn/passengers/query';
-const MAX_PAGE_SIZE = 50;
-
-function normalizeLimit(value, defaultValue, max) {
-    if (value === undefined || value === null || value === '') return defaultValue;
-    const n = Number(value);
-    if (!Number.isInteger(n) || n < 1) throw new ArgumentError(`limit must be a positive integer (1-${max})`);
-    if (n > max) throw new ArgumentError(`limit must be <= ${max}`);
-    return n;
-}
-
-cli({
-    site: '12306',
-    name: 'passengers',
-    access: 'read',
-    description: 'List the logged-in user\'s saved 12306 passengers. Sensitive fields are masked by default; pass --include-sensitive to opt in.',
-    domain: 'kyfw.12306.cn',
-    strategy: Strategy.COOKIE,
-    browser: true,
-    args: [
-        { name: 'limit', type: 'int', default: 20, help: `Max passengers to return (1-${MAX_PAGE_SIZE})` },
-        { name: 'include-sensitive', type: 'boolean', default: false, help: 'Reveal unmasked real names and birth dates. The 12306 ID-number / mobile masks are server-side and never decoded.' },
-    ],
-    columns: ['name', 'sex', 'born_year', 'id_type', 'id_no', 'mobile', 'passenger_type', 'country'],
-    func: async (page, kwargs) => {
-        if (!page) throw new CommandExecutionError('Browser session required for 12306 passengers');
-        const limit = normalizeLimit(kwargs.limit, 20, MAX_PAGE_SIZE);
-        const include = kwargs['include-sensitive'] === true;
-
-        await page.goto('https://kyfw.12306.cn/otn/view/index.html');
-        await require12306Login(page, AuthRequiredError);
-        const json = requireEvaluateObject(await page.evaluate(`async () => {
-      const body = "pageIndex=1&pageSize=${MAX_PAGE_SIZE}";
-      const r = await fetch(${JSON.stringify(PASSENGER_QUERY_URL)}, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body, credentials: 'include',
-      });
-      if (!r.ok) return { __http: r.status };
-      try {
-        return await r.json();
-      } catch (err) {
-        return { __parse: String(err && err.message || err) };
-      }
-    }`), 'passengers');
-        if (json?.__http) {
-            if ([401, 403].includes(Number(json.__http))) {
-                throw new AuthRequiredError('kyfw.12306.cn', '12306 passengers requires a valid login session');
-            }
-            throw new CommandExecutionError(`12306 returned HTTP ${json.__http} for passengers/query`);
-        }
-        if (json?.__parse) {
-            throw new CommandExecutionError(`12306 passengers returned non-JSON body: ${json.__parse}`);
-        }
-        if (isAuthLikePayload(json)) {
-            throw new AuthRequiredError('kyfw.12306.cn', '12306 passengers requires a valid login session');
-        }
-        if (json?.status !== true || !Array.isArray(json?.data?.datas)) {
-            throw new CommandExecutionError('12306 passengers payload missing data.datas array');
-        }
-        const datas = json.data.datas;
-        if (datas.length === 0) {
-            throw new EmptyResultError('No saved passengers on this 12306 account');
-        }
-        return datas.slice(0, limit).map((p) => ({
-            name: include ? (p.passenger_name || '') : maskChineseName(p.passenger_name || ''),
-            sex: p.sex_name || '',
-            born_year: (p.born_date || '').slice(0, 4),
-            id_type: p.passenger_id_type_name || '',
-            id_no: p.passenger_id_no || '',
-            mobile: p.mobile_no || '',
-            passenger_type: p.passenger_type_name || '',
-            country: p.country_code || '',
-        }));
-    },
-});
-
-export const __test__ = { normalizeLimit };