feat(browser): polish adapter author verify workflow

Author: jackwener

README.md

@@ -97,7 +97,7 @@ If you want to add your own commands, start with the [Extending OpenCLI guide](.
 |------|------------------|
 | Keep personal website commands in your own Git repo | `opencli plugin create` + `opencli plugin install file://...` |
 | Quickly draft a private local adapter | `opencli browser init <site>/<command>` in `~/.opencli/clis/` |
-| Modify an official adapter locally | `opencli adapter eject/status/reset` |
+| Modify an official adapter locally | `opencli adapter eject <site>` + `opencli adapter reset <site>` |
 | Publish or install third-party commands | `opencli plugin install github:user/repo` |
 | Wrap an existing local binary | `opencli external register <name>` |
 
@@ -174,7 +174,7 @@ When the site you need is not yet covered, use the `opencli-adapter-author` skil
 2. Discover the right endpoint — network inspection, initial state, bundle search, token trace, or interceptor fallback.
 3. Decide the auth strategy — `PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`.
 4. Decode response fields and design output columns.
-5. `opencli browser init <site>/<name>` → write adapter → `opencli browser verify <site>/<name>`.
+5. `opencli browser analyze <url>` for one-shot recon, then `opencli browser init <site>/<name>` → write adapter → `opencli browser verify <site>/<name>`.
 6. Persist site knowledge to `~/.opencli/sites/<site>/` so the next adapter for the same site is faster.
 
 ### CLI Hub and desktop adapters
@@ -407,7 +407,7 @@ Before writing any adapter code, read the [`opencli-adapter-author` skill](./ski
 - Recon the site and pick a pattern (SPA / SSR / JSONP / Token / Streaming).
 - Discover the right endpoint via `opencli browser network`, `eval`, or the interceptor fallback.
 - Decide auth strategy (`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`).
-- Decode response fields, design columns, scaffold with `opencli browser init`.
+- Run `opencli browser analyze <url>` for one-shot recon, decode response fields, design columns, scaffold with `opencli browser init`.
 - Verify with `opencli browser verify <site>/<name>` before shipping.
 
 For long-lived personal commands that should live in your own Git repo, use a local plugin instead; see [Extending OpenCLI](./docs/guide/extending-opencli.md). Quick private adapters can still live at `~/.opencli/clis/<site>/<name>.js`. Site knowledge (endpoints, field maps, fixtures) accumulates in `~/.opencli/sites/<site>/` so the next adapter for the same site starts from context instead of zero.

README.zh-CN.md

@@ -81,7 +81,7 @@ opencli bilibili hot --limit 5
 |------|----------|
 | 把个人网站命令放在自己的 Git repo | `opencli plugin create` + `opencli plugin install file://...` |
 | 快速写一个本机私人 adapter | `opencli browser init <site>/<command>`，放在 `~/.opencli/clis/` |
-| 本地修改官方 adapter | `opencli adapter eject/status/reset` |
+| 本地修改官方 adapter | `opencli adapter eject <site>` + `opencli adapter reset <site>` |
 | 发布或安装第三方命令 | `opencli plugin install github:user/repo` |
 | 包装已有本机 binary | `opencli external register <name>` |
 
@@ -158,7 +158,7 @@ Agent 在内部自动处理所有 `opencli browser` 命令——你只需用自
 2. 发现目标 endpoint——network 精读、initial state、bundle 搜索、token 溯源，或 interceptor 兜底
 3. 定认证策略——`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`
 4. 字段解码 + 设计输出列
-5. `opencli browser init <site>/<name>` → 写适配器 → `opencli browser verify <site>/<name>`
+5. `opencli browser analyze <url>` 一步侦察，再 `opencli browser init <site>/<name>` → 写适配器 → `opencli browser verify <site>/<name>`
 6. 把站点知识沉到 `~/.opencli/sites/<site>/`，下次写同站点的其他命令直接吃缓存
 
 ### CLI 枢纽与桌面端适配器
@@ -505,7 +505,7 @@ opencli plugin uninstall my-tool                            # 卸载
 - 侦察站点，选定 pattern（SPA / SSR / JSONP / Token / Streaming）
 - 用 `opencli browser network`、`eval`、interceptor 等找到目标 endpoint
 - 定认证策略（`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`）
-- 字段解码、设计 columns、`opencli browser init` 生成骨架
+- 先用 `opencli browser analyze <url>` 一步侦察，再字段解码、设计 columns、`opencli browser init` 生成骨架
 - 交付前用 `opencli browser verify <site>/<name>` 验证
 
 在仓库外写的私有适配器放到 `~/.opencli/clis/<site>/<name>.js`；每个站点的 endpoint、字段映射、抓包样本会累积在 `~/.opencli/sites/<site>/`，下次写同站点的其他命令可以直接复用。

docs/developer/ai-workflow.md

@@ -11,10 +11,11 @@ From a new site URL to a passing `opencli browser verify` — one skill, one set
 #    skills/opencli-adapter-author/SKILL.md
 
 # 2. Reconnaissance
-opencli browser open https://example.com
-opencli browser wait time 3
-opencli browser network        # inspect XHR / fetch calls
-opencli browser state          # extract __INITIAL_STATE__ / __NEXT_DATA__
+opencli browser analyze https://example.com
+# Fallback primitives when analyze says deeper inspection is needed:
+# opencli browser open https://example.com
+# opencli browser network      # inspect XHR / fetch calls
+# opencli browser state        # extract __INITIAL_STATE__ / __NEXT_DATA__
 
 # 3. Scaffold + verify
 opencli browser init <site>/<name>
@@ -30,6 +31,7 @@ See [skills/opencli-adapter-author/SKILL.md](https://github.com/jackwener/opencl
 | Command | Purpose |
 |---------|---------|
 | `opencli doctor` | Sanity check: bridge, Chrome, signals |
+| `opencli browser analyze <url>` | One-shot site recon: anti-bot, pattern, nearest adapter, next step |
 | `opencli browser open <url>` | Open a tab in the Chrome session |
 | `opencli browser network` | List recent XHR / fetch calls |
 | `opencli browser state` | Page state: URL, title, interactive elements |

docs/guide/extending-opencli.md

@@ -45,18 +45,30 @@ User adapters are loaded from:
 
 This path is convenient for quick local automation. For code you want to version, review, or share, prefer a plugin.
 
+If the command takes required positional args and no fixture exists yet, seed the first verify run explicitly:
+
+```bash
+opencli browser verify instagram/collection-create --write-fixture --seed-args opencli-verify
+opencli browser verify example/detail --write-fixture --seed-args '["https://example.com/item/1", "--limit", 3]'
+```
+
+`--seed-args` is only used when the fixture has no `args`. Once the fixture is written, `opencli browser verify` reads args from `~/.opencli/sites/<site>/verify/<command>.json`.
+
 ## Local overrides for official adapters
 
 Use `adapter eject` when you want to customize an existing official adapter.
 
 ```bash
 opencli adapter eject twitter
-opencli adapter status
 # edit ~/.opencli/clis/twitter/*.js
 opencli adapter reset twitter
 ```
 
-Ejected adapters override the packaged official adapter on this machine. `adapter reset` removes the local override and returns to the packaged version.
+Files in `~/.opencli/clis/<site>/<command>.js` override packaged adapters with the same `site/command` on this machine. `opencli browser verify <site>/<command>` also runs the local override, so a passing local verify does not prove that the packaged adapter was changed.
+
+The packaged `cli-manifest.json` only describes bundled adapters. User adapters are discovered at runtime and do not need manifest entries.
+
+After copying a local fix into the repository for a PR, remove the local copy or run `opencli adapter reset <site>` after merge. Otherwise the local file keeps shadowing future package updates. `opencli doctor` warns when it detects this shadowing.
 
 ## Plugins for sharing commands
 

docs/zh/guide/extending-opencli.md

@@ -45,18 +45,30 @@ User adapter 加载路径是：
 
 这条路径适合快速本地自动化。需要版本管理、review、共享的代码推荐做成 plugin。
 
+如果命令有 required positional args，而且 fixture 还没创建，第一次 verify 时直接传 seed：
+
+```bash
+opencli browser verify instagram/collection-create --write-fixture --seed-args opencli-verify
+opencli browser verify example/detail --write-fixture --seed-args '["https://example.com/item/1", "--limit", 3]'
+```
+
+`--seed-args` 只在 fixture 没有 `args` 时生效。fixture 写出后，`opencli browser verify` 会从 `~/.opencli/sites/<site>/verify/<command>.json` 读取 args。
+
 ## 本地覆盖官方 adapter
 
 如果你想改一个已有官方 adapter，用 `adapter eject`。
 
 ```bash
 opencli adapter eject twitter
-opencli adapter status
 # edit ~/.opencli/clis/twitter/*.js
 opencli adapter reset twitter
 ```
 
-Ejected adapter 会在本机覆盖 package 里的官方 adapter。`adapter reset` 会移除本地覆盖，恢复到 package 版本。
+`~/.opencli/clis/<site>/<command>.js` 会在本机覆盖同名 package adapter。`opencli browser verify <site>/<command>` 也会跑本地覆盖版本，所以本地 verify 通过不代表 package 里的 adapter 已经改好。
+
+Package 里的 `cli-manifest.json` 只描述 bundled adapter。User adapter 是运行时发现的，不需要写 manifest。
+
+把本地修复复制到仓库发 PR 后，merge 后要删除本地副本，或运行 `opencli adapter reset <site>`。否则本地文件会继续 shadow 后续 package 更新。`opencli doctor` 会在发现这种 shadowing 时给出 warning。
 
 ## Plugin：共享命令
 

src/adapter-shadow.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { findShadowedUserAdapters, formatAdapterShadowIssue } from './adapter-shadow.js';
+
+describe('adapter shadow detection', () => {
+  it('reports user adapters that shadow packaged manifest commands', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-adapter-shadow-'));
+    try {
+      const userClisDir = path.join(root, 'user-clis');
+      const builtinRoot = path.join(root, 'pkg');
+      const builtinClisDir = path.join(builtinRoot, 'clis');
+      fs.mkdirSync(path.join(userClisDir, 'instagram'), { recursive: true });
+      fs.mkdirSync(path.join(userClisDir, 'twitter'), { recursive: true });
+      fs.mkdirSync(path.join(builtinClisDir, 'instagram'), { recursive: true });
+      fs.mkdirSync(path.join(builtinClisDir, 'twitter'), { recursive: true });
+
+      fs.writeFileSync(path.join(userClisDir, 'instagram', 'saved.js'), '', 'utf-8');
+      fs.writeFileSync(path.join(userClisDir, 'instagram', 'utils.js'), '', 'utf-8');
+      fs.writeFileSync(path.join(userClisDir, 'twitter', 'search.js'), '', 'utf-8');
+      fs.writeFileSync(path.join(builtinClisDir, 'instagram', 'saved.js'), '', 'utf-8');
+      fs.writeFileSync(path.join(builtinClisDir, 'instagram', 'utils.js'), '', 'utf-8');
+      fs.writeFileSync(path.join(builtinClisDir, 'twitter', 'search.js'), '', 'utf-8');
+      fs.writeFileSync(path.join(builtinRoot, 'cli-manifest.json'), `${JSON.stringify([
+        { site: 'instagram', name: 'saved', sourceFile: 'instagram/saved.js' },
+      ])}\n`, 'utf-8');
+
+      expect(findShadowedUserAdapters({ userClisDir, builtinClisDir })).toEqual([
+        {
+          name: 'instagram/saved',
+          userPath: path.join(userClisDir, 'instagram', 'saved.js'),
+          builtinPath: path.join(builtinClisDir, 'instagram', 'saved.js'),
+        },
+      ]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('formats a concise doctor issue', () => {
+    const issue = formatAdapterShadowIssue([
+      {
+        name: 'instagram/saved',
+        userPath: '/home/me/.opencli/clis/instagram/saved.js',
+        builtinPath: '/pkg/clis/instagram/saved.js',
+      },
+    ]);
+
+    expect(issue).toContain('instagram/saved');
+    expect(issue).toContain('opencli adapter reset <site>');
+  });
+});

src/adapter-shadow.ts

@@ -0,0 +1,87 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ManifestEntry } from './manifest-types.js';
+import { findPackageRoot, getCliManifestPath } from './package-paths.js';
+
+export type AdapterShadow = {
+  name: string;
+  userPath: string;
+  builtinPath: string;
+};
+
+export type AdapterShadowOptions = {
+  userClisDir?: string;
+  builtinClisDir?: string;
+};
+
+function defaultBuiltinClisDir(): string {
+  return path.join(findPackageRoot(fileURLToPath(import.meta.url)), 'clis');
+}
+
+function safeReaddir(dir: string): fs.Dirent[] {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function loadBuiltinCommandFiles(builtinClisDir: string): Set<string> {
+  try {
+    const raw = fs.readFileSync(getCliManifestPath(builtinClisDir), 'utf-8');
+    const entries = JSON.parse(raw) as ManifestEntry[];
+    const files = new Set<string>();
+    for (const entry of entries) {
+      const rel = entry.sourceFile ?? entry.modulePath;
+      if (rel) files.add(path.resolve(builtinClisDir, rel));
+    }
+    return files;
+  } catch {
+    return new Set();
+  }
+}
+
+export function findShadowedUserAdapters(opts: AdapterShadowOptions = {}): AdapterShadow[] {
+  const userClisDir = opts.userClisDir ?? path.join(os.homedir(), '.opencli', 'clis');
+  const builtinClisDir = opts.builtinClisDir ?? defaultBuiltinClisDir();
+  const builtinCommandFiles = loadBuiltinCommandFiles(builtinClisDir);
+  const shadows: AdapterShadow[] = [];
+
+  for (const siteEntry of safeReaddir(userClisDir)) {
+    if (!siteEntry.isDirectory()) continue;
+    const site = siteEntry.name;
+    const userSiteDir = path.join(userClisDir, site);
+    const builtinSiteDir = path.join(builtinClisDir, site);
+
+    for (const commandEntry of safeReaddir(userSiteDir)) {
+      if (!commandEntry.isFile() || !commandEntry.name.endsWith('.js')) continue;
+      const userPath = path.join(userSiteDir, commandEntry.name);
+      const builtinPath = path.join(builtinSiteDir, commandEntry.name);
+      const builtinResolved = path.resolve(builtinPath);
+      if (!builtinCommandFiles.has(builtinResolved)) continue;
+
+      shadows.push({
+        name: `${site}/${commandEntry.name.replace(/\.js$/, '')}`,
+        userPath,
+        builtinPath,
+      });
+    }
+  }
+
+  return shadows.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function formatAdapterShadowIssue(shadows: AdapterShadow[]): string {
+  const visible = shadows.slice(0, 10);
+  const lines = ['Local adapter overrides shadow packaged adapters:'];
+  for (const shadow of visible) {
+    lines.push(`  ${shadow.name}: ${shadow.userPath} overrides ${shadow.builtinPath}`);
+  }
+  if (shadows.length > visible.length) {
+    lines.push(`  ... and ${shadows.length - visible.length} more`);
+  }
+  lines.push('Remove the local ~/.opencli/clis copy, or run opencli adapter reset <site>, when you want packaged updates.');
+  return lines.join('\n');
+}

src/browser/verify-fixture.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { deriveFixture, expandFixtureArgs, validateRows, type Fixture } from './verify-fixture.js';
+import { deriveFixture, expandFixtureArgs, parseSeedArgs, validateRows, type Fixture } from './verify-fixture.js';
 
 describe('validateRows', () => {
     it('passes when rows meet all expectations', () => {
@@ -221,3 +221,22 @@ describe('expandFixtureArgs', () => {
         ]);
     });
 });
+
+describe('parseSeedArgs', () => {
+    it('treats plain text as one positional arg', () => {
+        expect(parseSeedArgs('opencli-verify')).toEqual(['opencli-verify']);
+    });
+
+    it('accepts JSON array seed args', () => {
+        expect(parseSeedArgs('["subject", "--limit", 3]')).toEqual(['subject', '--limit', 3]);
+    });
+
+    it('accepts JSON object seed args', () => {
+        expect(parseSeedArgs('{"limit":3,"sort":"hot"}')).toEqual({ limit: 3, sort: 'hot' });
+    });
+
+    it('ignores empty input', () => {
+        expect(parseSeedArgs(undefined)).toBeUndefined();
+        expect(parseSeedArgs('   ')).toBeUndefined();
+    });
+});

src/browser/verify-fixture.ts

@@ -239,6 +239,21 @@ export function expandFixtureArgs(args: FixtureArgs | undefined): string[] {
   return out;
 }
 
+export function parseSeedArgs(raw: string | undefined): FixtureArgs | undefined {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+
+  try {
+    const parsed = JSON.parse(trimmed) as unknown;
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed !== null && typeof parsed === 'object') return parsed as Record<string, unknown>;
+    return [parsed];
+  } catch {
+    return [raw];
+  }
+}
+
 function jsType(v: unknown): string {
   if (v === null) return 'null';
   if (Array.isArray(v)) return 'array';