feat(browser): add network --filter <fields> for agent-native request discovery (#1103)

Agents often know what fields a target request's body should contain
but not which captured request carries it. --filter lets them declare
the field set and get back only matching entries.

Matching is "any-segment": a field matches when it equals any segment
name of any inferShape() path (ignoring root $, array indices, and
bracket-quoted key syntax). Multiple fields AND together. Case-sensitive.

- invalid_filter for empty / commas-only values
- invalid_args when combined with --detail (mutually exclusive)
- 0 matches is a valid empty result, not an error
- persisted cache stays unfiltered so later --detail lookups still resolve

Envelope gains `filter` (echo) and `filter_dropped` (count of entries
passing the static-resource filter but not --filter). Existing --raw
and --all compose normally.

Author: jackwener

skills/opencli-adapter-author/references/api-discovery.md

@@ -29,6 +29,22 @@ opencli browser network
 - 路径里出现 `nickname / avatar / title / price / tweets / items` → 就是它
 - shape 只有 `$: string` 或全是 HTML 噪音 → 下一条
 
+### 按期望字段反查（`--filter`）
+
+已经知道目标 body 该含哪些字段就直接让 CLI 把列表筛到只剩候选，不用自己 scroll 翻 shape：
+
+```bash
+opencli browser network --filter author,text,likes
+```
+
+- 字段以英文逗号分隔；AND 语义，必须每个字段都作为 shape 路径的**任意一段**出现才保留（`$.data.items[0].author` 命中 `author`、`items`、`data` 都算）
+- 区分大小写（JSON key 本来就 case-sensitive）
+- 输出 envelope 新增 `filter` / `filter_dropped`，`count` 是过滤后数量
+- 0 命中不是 error，返回 `entries: []`；说明字段组合不对，换一组或去掉约束再试
+- 不要跟 `--detail` 一起用——`--detail` 按 key 取单条、`--filter` 是列表缩窄，组合会报 `invalid_args`
+- 空值 / `,,,` → `invalid_filter` 结构化错误
+- capture 依然按全量持久化，后续 `--detail <key>` 能找到被过滤掉的条目
+
 ### 拉完整 body
 
 候选定了再拉完整 body（by key，不是 index — 数组顺序会随每次 capture 变）：

skills/opencli-autofix/SKILL.md

@@ -130,6 +130,9 @@ opencli browser open https://example.com/target-page && opencli browser state
 # Interact to trigger API calls
 opencli browser click <N> && opencli browser network
 
+# Narrow to the request you care about by the fields its body should have
+opencli browser network --filter author,text,likes
+
 # Inspect specific API response (key is the `key` field from the default JSON output)
 opencli browser network --detail <key>
 ```

src/browser/shape-filter.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import type { Shape } from './shape.js';
+import {
+    collectShapeSegments,
+    extractSegments,
+    parseFilter,
+    shapeMatchesFilter,
+} from './shape-filter.js';
+
+describe('parseFilter', () => {
+    it('splits comma-separated fields, trims, and drops empty tokens', () => {
+        const r = parseFilter('author, text , likes');
+        expect(r).toEqual({ fields: ['author', 'text', 'likes'] });
+    });
+
+    it('dedupes while preserving first-seen order', () => {
+        const r = parseFilter('a,b,a,c,b');
+        expect(r).toEqual({ fields: ['a', 'b', 'c'] });
+    });
+
+    it('rejects empty string as invalid_filter', () => {
+        const r = parseFilter('');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+
+    it('rejects whitespace-only as invalid_filter', () => {
+        const r = parseFilter('   ');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+
+    it('rejects commas-only as invalid_filter', () => {
+        const r = parseFilter(',,,');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+
+    it('accepts a single field', () => {
+        expect(parseFilter('author')).toEqual({ fields: ['author'] });
+    });
+});
+
+describe('extractSegments', () => {
+    it('returns empty for root', () => {
+        expect(extractSegments('$')).toEqual([]);
+    });
+
+    it('splits dotted path and drops $', () => {
+        expect(extractSegments('$.data.user.name')).toEqual(['data', 'user', 'name']);
+    });
+
+    it('drops numeric array indices', () => {
+        expect(extractSegments('$.items[0].author')).toEqual(['items', 'author']);
+        expect(extractSegments('$.rows[0][12]')).toEqual(['rows']);
+    });
+
+    it('unwraps bracket-quoted keys', () => {
+        expect(extractSegments('$.data["weird key"]')).toEqual(['data', 'weird key']);
+    });
+
+    it('handles bracket-quoted keys at root', () => {
+        expect(extractSegments('$["123bad"]')).toEqual(['123bad']);
+    });
+
+    it('mixes bracket keys and dot segments', () => {
+        expect(extractSegments('$.data.user["nick name"].age'))
+            .toEqual(['data', 'user', 'nick name', 'age']);
+    });
+});
+
+describe('collectShapeSegments', () => {
+    it('collects every segment name from every path in a shape', () => {
+        const shape: Shape = {
+            '$': 'object',
+            '$.data': 'object',
+            '$.data.items': 'array(3)',
+            '$.data.items[0]': 'object',
+            '$.data.items[0].author': 'string',
+            '$.data.items[0].text': 'string',
+        };
+        const segs = collectShapeSegments(shape);
+        expect(segs.has('data')).toBe(true);
+        expect(segs.has('items')).toBe(true);
+        expect(segs.has('author')).toBe(true);
+        expect(segs.has('text')).toBe(true);
+        expect(segs.has('$')).toBe(false);
+        expect(segs.has('[0]')).toBe(false);
+    });
+
+    it('returns an empty set for an empty shape', () => {
+        expect(collectShapeSegments({}).size).toBe(0);
+    });
+});
+
+describe('shapeMatchesFilter', () => {
+    const shape: Shape = {
+        '$': 'object',
+        '$.data': 'object',
+        '$.data.items': 'array(1)',
+        '$.data.items[0].author': 'string',
+        '$.data.items[0].text': 'string',
+        '$.data.items[0].likes': 'number',
+    };
+
+    it('returns true when every field matches some path segment (AND)', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'text', 'likes'])).toBe(true);
+    });
+
+    it('matches nested container names, not just leaves (any-segment rule)', () => {
+        // `data` and `items` are container segments, not leaves; still must match.
+        expect(shapeMatchesFilter(shape, ['data', 'items'])).toBe(true);
+    });
+
+    it('returns false when any field is missing', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'missing'])).toBe(false);
+    });
+
+    it('is case-sensitive', () => {
+        expect(shapeMatchesFilter(shape, ['Author'])).toBe(false);
+        expect(shapeMatchesFilter(shape, ['author'])).toBe(true);
+    });
+
+    it('empty filter list vacuously matches', () => {
+        expect(shapeMatchesFilter(shape, [])).toBe(true);
+    });
+
+    it('rejects requests whose shape has no body (empty shape)', () => {
+        expect(shapeMatchesFilter({}, ['author'])).toBe(false);
+    });
+});

src/browser/shape-filter.ts

@@ -0,0 +1,114 @@
+/**
+ * Shape-based field filter for `browser network --filter <fields>`.
+ *
+ * Agents know what fields a target request's body should contain
+ * (e.g. "author, text, likes") but not which of the captured requests
+ * carries that body. This module lets the network command filter
+ * entries down to those whose inferred shape exposes every requested
+ * field name as some path segment.
+ *
+ * Matching is "any-segment" (not last-segment-only): a field matches
+ * if it equals any segment name of any path in the shape map. This
+ * keeps nested-container fields (e.g. `legacy`, `author` used as an
+ * object key with further nesting) findable.
+ */
+import type { Shape } from './shape.js';
+
+export interface ParsedFilter {
+    /** Deduped, order-preserving, trimmed non-empty field names. */
+    fields: string[];
+}
+
+export interface FilterParseError {
+    /** `invalid_filter` structured error reason for agents. */
+    reason: string;
+}
+
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export function parseFilter(raw: string): ParsedFilter | FilterParseError {
+    if (typeof raw !== 'string') {
+        return { reason: `--filter value must be a non-empty comma-separated field list` };
+    }
+    const parts = raw.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return { reason: `--filter value must be a non-empty comma-separated field list (got "${raw}")` };
+    }
+    const seen = new Set<string>();
+    const fields: string[] = [];
+    for (const p of parts) {
+        if (!seen.has(p)) { seen.add(p); fields.push(p); }
+    }
+    return { fields };
+}
+
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export function extractSegments(path: string): string[] {
+    if (!path || path === '$') return [];
+    const out: string[] = [];
+    // Start past the leading `$`; if path doesn't start with `$` treat
+    // it as a raw segment list (keeps us robust to unexpected input).
+    let i = path.startsWith('$') ? 1 : 0;
+    while (i < path.length) {
+        const c = path[i];
+        if (c === '.') { i++; continue; }
+        if (c === '[') {
+            // Either `[N]` (numeric) or `["key"]` (quoted key). Handle both.
+            const end = path.indexOf(']', i);
+            if (end === -1) break;
+            const inner = path.slice(i + 1, end);
+            i = end + 1;
+            if (inner.length >= 2 && inner.startsWith('"') && inner.endsWith('"')) {
+                try { out.push(JSON.parse(inner) as string); }
+                catch { out.push(inner.slice(1, -1)); }
+            }
+            // numeric index: drop
+            continue;
+        }
+        // Bare identifier: read up to next `.` or `[`
+        let j = i;
+        while (j < path.length && path[j] !== '.' && path[j] !== '[') j++;
+        out.push(path.slice(i, j));
+        i = j;
+    }
+    return out;
+}
+
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export function collectShapeSegments(shape: Shape): Set<string> {
+    const acc = new Set<string>();
+    for (const p of Object.keys(shape)) {
+        for (const seg of extractSegments(p)) acc.add(seg);
+    }
+    return acc;
+}
+
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export function shapeMatchesFilter(shape: Shape, fields: string[]): boolean {
+    if (fields.length === 0) return true;
+    const segs = collectShapeSegments(shape);
+    for (const f of fields) {
+        if (!segs.has(f)) return false;
+    }
+    return true;
+}