feat(twitter): 新增 list-create 命令（GraphQL CreateList mutation） (#1656)

huanghe · huanghe · karyhe1019 · web-flow · commit d1c714ecd37b · 2026-05-19T12:51:57.000+08:00
* feat(twitter): add list-create command Adds a new `twitter list-create` command so users can create Twitter/X lists from the CLI (the existing list commands only covered reading, adding, and removing members). Uses the GraphQL CreateList mutation with the same cookie + CSRF pattern as list-add, no UI clicks needed. Args: name (positional, max 25), --description (max 100), --mode (public|private). QueryId resolved at runtime via resolveTwitterQueryId, with a known fallback for offline / bundle-scan misses. * fix(twitter): pin list-create queryId + features to a working pair Twitter's GraphQL rejects CreateList when queryId and the features schema drift apart (DecodeException). Stop resolving the queryId dynamically (which would pull a newer schema), hardcode a known-good queryId, and trim features to the minimal set the real web client sends. Also: Twitter sometimes returns a non-fatal errors array from a side-effect serializer while still creating the list. Check for a valid list payload first and only treat errors as fatal when no list came back. * fix(twitter): add missing access:'write' on list-create (#9) `twitter/list-create` was missing the required `access` field, which made manifest validation fail on every opencli invocation and spam stderr with: ⚠ Failed to load manifest .../cli-manifest.json: Command twitter/list-create must declare access: 'read' | 'write' Per docs/conventions/convention-audit.md (rule missing-access-metadata), every adapter command must declare access. Since list-create is a create action, set access: 'write'. Also rebuilds cli-manifest.json — picks up missing `quoted_tweet` columns on list-tweets / search / list-tweets-username from PR #8 (which didn't rebuild the manifest). * fix(twitter): harden list-create mutation contract * fix(twitter): verify created list name --------- Co-authored-by: huanghe <he.huang@extremevision.mo> Co-authored-by: Kary <karyhe1019@gmail.com> Co-authored-by: jackwener <jakevingoo@gmail.com>
diff --git a/cli-manifest.json b/cli-manifest.json
@@ -24112,6 +24112,49 @@
     "sourceFile": "twitter/list-add.js",
     "navigateBefore": true
   },
+  {
+    "site": "twitter",
+    "name": "list-create",
+    "description": "Create a new Twitter/X list (returns the new list id)",
+    "access": "write",
+    "domain": "x.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": true,
+        "positional": true,
+        "help": "List name (max 25 chars)"
+      },
+      {
+        "name": "description",
+        "type": "string",
+        "default": "",
+        "required": false,
+        "help": "Optional list description (max 100 chars)"
+      },
+      {
+        "name": "mode",
+        "type": "string",
+        "default": "public",
+        "required": false,
+        "help": "public | private"
+      }
+    ],
+    "columns": [
+      "id",
+      "name",
+      "description",
+      "mode",
+      "status"
+    ],
+    "type": "js",
+    "modulePath": "twitter/list-create.js",
+    "sourceFile": "twitter/list-create.js",
+    "navigateBefore": "https://x.com"
+  },
   {
     "site": "twitter",
     "name": "list-remove",
diff --git a/clis/twitter/list-create.js b/clis/twitter/list-create.js
@@ -0,0 +1,155 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { unwrapBrowserResult } from './shared.js';
+import { TWITTER_BEARER_TOKEN } from './utils.js';
+
+const CREATE_LIST_QUERY_ID = 'UQRa0jJ9doxGEIQRea1Y0w';
+const NAME_MAX = 25;
+const DESCRIPTION_MAX = 100;
+
+// Minimal feature set as observed in the real CreateList web request payload.
+// Twitter rejects requests with extra/unknown features (DecodeException).
+const FEATURES = {
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: false,
+    rweb_tipjar_consumption_enabled: false,
+    verified_phone_label_enabled: false,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+};
+
+export function parseListCreateArgs(kwargs) {
+    const name = String(kwargs.name || '').trim();
+    const description = String(kwargs.description || '').trim();
+    const modeRaw = String(kwargs.mode || 'public').trim().toLowerCase();
+    if (!name) {
+        throw new ArgumentError('List name is required', 'Example: opencli twitter list-create "My List"');
+    }
+    if (name.length > NAME_MAX) {
+        throw new ArgumentError(`List name too long: ${name.length} chars (max ${NAME_MAX})`);
+    }
+    if (description.length > DESCRIPTION_MAX) {
+        throw new ArgumentError(`Description too long: ${description.length} chars (max ${DESCRIPTION_MAX})`);
+    }
+    if (modeRaw !== 'public' && modeRaw !== 'private') {
+        throw new ArgumentError(`Invalid mode: ${JSON.stringify(kwargs.mode)}. Expected "public" or "private".`);
+    }
+    return { listName: name, listDescription: description, listMode: modeRaw, privateFlag: modeRaw === 'private' };
+}
+
+function requireCreateListResult(result, expectedName, expectedMode) {
+    if (!result || typeof result !== 'object') {
+        throw new CommandExecutionError(`Unexpected result from twitter list-create: ${JSON.stringify(result)}`);
+    }
+    if (result.httpStatus === 401 || result.httpStatus === 403) {
+        throw new AuthRequiredError('x.com', `Twitter CreateList returned HTTP ${result.httpStatus}`);
+    }
+    if (!result.ok) {
+        const snippet = String(result.bodyText || '').slice(0, 300);
+        throw new CommandExecutionError(`HTTP ${result.httpStatus} from CreateList: ${snippet}`);
+    }
+    if (!result.bodyJson || typeof result.bodyJson !== 'object') {
+        throw new CommandExecutionError(`CreateList returned malformed JSON payload. Body: ${String(result.bodyText || '').slice(0, 300)}`);
+    }
+    const list = result.bodyJson?.data?.list;
+    if (!list || typeof list !== 'object') {
+        const errors = result.bodyJson?.errors;
+        if (Array.isArray(errors) && errors.length > 0) {
+            throw new CommandExecutionError(`CreateList failed: ${errors[0].message || JSON.stringify(errors[0])}`);
+        }
+        throw new CommandExecutionError(`CreateList returned no list payload. Body: ${String(result.bodyText || '').slice(0, 300)}`);
+    }
+    const id = String(list.id_str || list.id || '');
+    if (!/^\d+$/.test(id)) {
+        throw new CommandExecutionError('CreateList returned a list payload without a numeric list id.');
+    }
+    if (typeof list.name !== 'string' || !list.name.trim()) {
+        throw new CommandExecutionError('CreateList returned a list payload without a list name.');
+    }
+    if (list.name.trim() !== expectedName) {
+        throw new CommandExecutionError(`CreateList returned name ${JSON.stringify(list.name)}, expected ${JSON.stringify(expectedName)}.`);
+    }
+    const modeValue = typeof list.mode === 'string' ? list.mode : '';
+    if (!modeValue) {
+        throw new CommandExecutionError('CreateList returned a list payload without list mode.');
+    }
+    const mode = /private/i.test(modeValue) ? 'private' : 'public';
+    if (mode !== expectedMode) {
+        throw new CommandExecutionError(`CreateList returned mode ${mode}, expected ${expectedMode}.`);
+    }
+    return { createdList: list, listId: id, listMode: mode };
+}
+
+export function buildListCreateRow({ result, name, description, mode }) {
+    const { createdList, listId, listMode } = requireCreateListResult(result, name, mode);
+    return {
+        id: listId,
+        name: createdList.name,
+        description: typeof createdList.description === 'string' ? createdList.description : description,
+        mode: listMode,
+        status: 'success',
+    };
+}
+
+cli({
+    site: 'twitter',
+    name: 'list-create',
+    description: 'Create a new Twitter/X list (returns the new list id)',
+    access: 'write',
+    domain: 'x.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'name', positional: true, type: 'string', required: true, help: `List name (max ${NAME_MAX} chars)` },
+        { name: 'description', type: 'string', default: '', help: `Optional list description (max ${DESCRIPTION_MAX} chars)` },
+        { name: 'mode', type: 'string', default: 'public', help: 'public | private' },
+    ],
+    columns: ['id', 'name', 'description', 'mode', 'status'],
+    func: async (page, kwargs) => {
+        const { listName: name, listDescription: description, listMode: mode, privateFlag: isPrivate } = parseListCreateArgs(kwargs);
+
+        await page.goto('https://x.com');
+        await page.wait(3);
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
+        if (!ct0) throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
+
+        // Hardcode queryId: it must match the FEATURES schema below.
+        // Letting resolveTwitterQueryId() drift would pull a newer queryId
+        // whose schema would reject our simplified features payload.
+        const queryId = CREATE_LIST_QUERY_ID;
+
+        const headers = JSON.stringify({
+            'Authorization': `Bearer ${decodeURIComponent(TWITTER_BEARER_TOKEN)}`,
+            'X-Csrf-Token': ct0,
+            'X-Twitter-Auth-Type': 'OAuth2Session',
+            'X-Twitter-Active-User': 'yes',
+            'Content-Type': 'application/json',
+        });
+        const body = JSON.stringify({
+            variables: { isPrivate, name, description },
+            features: FEATURES,
+            queryId,
+        });
+        const apiUrl = `/i/api/graphql/${queryId}/CreateList`;
+
+        const result = unwrapBrowserResult(await page.evaluate(`async () => {
+            const r = await fetch(${JSON.stringify(apiUrl)}, {
+                method: 'POST',
+                headers: ${headers},
+                credentials: 'include',
+                body: ${JSON.stringify(body)},
+            });
+            const bodyText = await r.text();
+            let bodyJson = null;
+            try { bodyJson = JSON.parse(bodyText); } catch {}
+            return { ok: r.ok, httpStatus: r.status, bodyJson, bodyText };
+        }`));
+
+        // Note: Twitter sometimes returns a non-fatal `errors` array (e.g. a
+        // strato DecodeException from a side-effect serializer) WHILE STILL
+        // creating the list. So check for a valid list payload FIRST and
+        // only treat errors as fatal if no list came back.
+        return [buildListCreateRow({ result, name, description, mode })];
+    },
+});
diff --git a/clis/twitter/list-create.test.js b/clis/twitter/list-create.test.js
@@ -0,0 +1,169 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { buildListCreateRow, parseListCreateArgs } from './list-create.js';
+import './list-create.js';
+
+function createPayload(overrides = {}) {
+    return {
+        ok: true,
+        httpStatus: 200,
+        bodyText: '{}',
+        bodyJson: {
+            data: {
+                list: {
+                    id_str: '123456789',
+                    name: 'My List',
+                    description: 'A list',
+                    mode: 'Private',
+                    ...overrides,
+                },
+            },
+        },
+    };
+}
+
+describe('twitter list-create registration', () => {
+    it('registers the list-create command with the expected shape', () => {
+        const cmd = getRegistry().get('twitter/list-create');
+        expect(cmd?.func).toBeTypeOf('function');
+        expect(cmd?.columns).toEqual(['id', 'name', 'description', 'mode', 'status']);
+        const nameArg = cmd?.args?.find((a) => a.name === 'name');
+        expect(nameArg).toBeTruthy();
+        expect(nameArg?.required).toBe(true);
+        expect(nameArg?.positional).toBe(true);
+        const modeArg = cmd?.args?.find((a) => a.name === 'mode');
+        expect(modeArg?.default).toBe('public');
+        const descArg = cmd?.args?.find((a) => a.name === 'description');
+        expect(descArg?.default).toBe('');
+    });
+
+    it('rejects empty name', async () => {
+        const cmd = getRegistry().get('twitter/list-create');
+        await expect(cmd.func({}, { name: '   ' })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('rejects names over 25 chars', async () => {
+        const cmd = getRegistry().get('twitter/list-create');
+        await expect(cmd.func({}, { name: 'x'.repeat(26) })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('rejects descriptions over 100 chars', () => {
+        expect(() => parseListCreateArgs({ name: 'ok', description: 'x'.repeat(101) })).toThrow(ArgumentError);
+    });
+
+    it('rejects invalid mode', async () => {
+        const cmd = getRegistry().get('twitter/list-create');
+        await expect(cmd.func({}, { name: 'ok', mode: 'secret' })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('reads ct0 from cookies and unwraps Browser Bridge mutation envelopes', async () => {
+        const cmd = getRegistry().get('twitter/list-create');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            getCookies: vi.fn().mockResolvedValue([{ name: 'ct0', value: 'csrf-token' }]),
+            evaluate: vi.fn().mockResolvedValue({ session: 'browser:default', data: createPayload() }),
+        };
+
+        const rows = await cmd.func(page, { name: 'My List', description: 'A list', mode: 'private' });
+
+        expect(page.goto).toHaveBeenCalledWith('https://x.com');
+        expect(page.wait).toHaveBeenCalledWith(3);
+        expect(page.getCookies).toHaveBeenCalledWith({ url: 'https://x.com' });
+        expect(rows).toEqual([{ id: '123456789', name: 'My List', description: 'A list', mode: 'private', status: 'success' }]);
+    });
+
+    it('rejects missing ct0 before mutation', async () => {
+        const cmd = getRegistry().get('twitter/list-create');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            getCookies: vi.fn().mockResolvedValue([]),
+            evaluate: vi.fn(),
+        };
+
+        await expect(cmd.func(page, { name: 'My List' })).rejects.toBeInstanceOf(AuthRequiredError);
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('keeps non-fatal GraphQL errors when a valid created list payload exists', () => {
+        const row = buildListCreateRow({
+            result: {
+                ...createPayload(),
+                bodyJson: {
+                    ...createPayload().bodyJson,
+                    errors: [{ message: 'DecodeException' }],
+                },
+            },
+            name: 'My List',
+            description: 'A list',
+            mode: 'private',
+        });
+
+        expect(row).toEqual({ id: '123456789', name: 'My List', description: 'A list', mode: 'private', status: 'success' });
+    });
+
+    it('maps mutation auth and HTTP failures to typed errors', () => {
+        expect(() => buildListCreateRow({
+            result: { ok: false, httpStatus: 401, bodyText: 'login' },
+            name: 'My List',
+            description: '',
+            mode: 'public',
+        })).toThrow(AuthRequiredError);
+
+        expect(() => buildListCreateRow({
+            result: { ok: false, httpStatus: 500, bodyText: 'server' },
+            name: 'My List',
+            description: '',
+            mode: 'public',
+        })).toThrow(CommandExecutionError);
+    });
+
+    it('fails typed when the mutation response lacks post-condition evidence', () => {
+        for (const result of [
+            createPayload({ id_str: '', id: '' }),
+            createPayload({ name: '' }),
+            createPayload({ mode: '' }),
+        ]) {
+            expect(() => buildListCreateRow({
+                result,
+                name: 'My List',
+                description: '',
+                mode: 'public',
+            })).toThrow(CommandExecutionError);
+        }
+    });
+
+    it('fails typed when returned list name does not match the requested name', () => {
+        expect(() => buildListCreateRow({
+            result: createPayload({ name: 'Other List' }),
+            name: 'My List',
+            description: '',
+            mode: 'private',
+        })).toThrow(/expected "My List"/);
+    });
+
+    it('fails typed when returned list mode does not match requested mode', () => {
+        expect(() => buildListCreateRow({
+            result: createPayload({ mode: 'Public' }),
+            name: 'My List',
+            description: '',
+            mode: 'private',
+        })).toThrow(/expected private/);
+    });
+
+    it('fails typed when errors appear without a list payload', () => {
+        expect(() => buildListCreateRow({
+            result: {
+                ok: true,
+                httpStatus: 200,
+                bodyText: '{}',
+                bodyJson: { errors: [{ message: 'duplicate name' }] },
+            },
+            name: 'My List',
+            description: '',
+            mode: 'public',
+        })).toThrow(/duplicate name/);
+    });
+});
diff --git a/docs/adapters/browser/twitter.md b/docs/adapters/browser/twitter.md
@@ -22,6 +22,7 @@
 | `opencli twitter likes` | |
 | `opencli twitter lists` | |
 | `opencli twitter list-tweets` | |
+| `opencli twitter list-create` | Create a Twitter/X list via GraphQL and return the created list id |
 | `opencli twitter list-add` | |
 | `opencli twitter list-remove` | |
 | `opencli twitter article` | |
@@ -62,6 +63,11 @@ opencli twitter download @elonmusk --limit 50 --output ./twitter-media
 # Download media from a single tweet
 opencli twitter download --tweet-url https://x.com/jack/status/20 --output ./twitter-media
 
+# Create a list and then manage members (requires login)
+opencli twitter list-create "AI research" --description "Papers and labs" --mode private
+opencli twitter list-add 123456789 alice
+opencli twitter list-remove 123456789 alice
+
 # Write actions (require login). Idempotent — calling twice is safe.
 opencli twitter like https://x.com/jack/status/20
 opencli twitter unlike https://x.com/jack/status/20
