specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/platforms/x/web/client.js

@@ -0,0 +1,202 @@
+import { SpecificAIError } from '../../../core/errors.js';
+import { parseJson } from '../../../core/http.js';
+import { jsonLoads } from '../../../core/py.js';
+import { authError, httpClient } from '../../../core/toolkit.js';
+import { GraphQLOperation } from './graphql.js';
+import { BROWSER, buildHeaders, COOKIE_DOMAIN, PROFILE, PUBLIC_BEARER, X_HOST } from './profile.js';
+import { userIdFromTwid } from './resolve.js';
+import { transaction } from './transaction.js';
+/**
+ * X web 端会话，移植自上游 builder/auth.py（XAuth）+ x_apis 里的 graphql_get / graphql_post_query /
+ * graphql_post / _rest_post。
+ *
+ * XAuth 持有的动态状态（cookie 含 ct0）在 specific-ai 里都存进凭证，由 core 落盘。web 端不支持游客态
+ * （AGENTS 5.2），上游的 guest token 不移植。
+ * XCTID 素材用打包进仓库的 static/x/transaction_l1.json（上游 from_cached）：上游优先
+ * from_network 抓 /i/flow/login 的 app shell，但它现在 307 到 jetfuel 登录页、拿不到素材，
+ * 上游实际也是回退到这份缓存。
+ */
+/** 会话过期 / 未授权（上游 main.py 的 _AUTH_FAILURE_CODES，加上 353 = ct0 不匹配）。 */
+const AUTH_CODES = new Set([32, 89, 215, 326, 353]);
+/** GraphQL 错误码是否表示未登录 / 会话失效。 */
+export const isAuthCode = (code) => AUTH_CODES.has(Number(code));
+/** 限流 / 风控（88 = rate limit，226 / 344 = 自动化 / 日上限）。 */
+const RISK_CODES = new Set([88, 226, 344]);
+export class GraphQLError extends Error {
+    operation;
+    errors;
+    res;
+    constructor(operation, errors, res) {
+        super(`${operation}: ${errors.map((e) => e?.message ?? e).join('; ')}`);
+        this.operation = operation;
+        this.errors = errors;
+        this.res = res;
+    }
+    get code() {
+        return this.errors[0]?.code;
+    }
+}
+export class XClient {
+    ctx;
+    http;
+    jar;
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.http = httpClient(ctx, { browser: BROWSER, os: 'windows' });
+        this.jar = this.http.jar;
+    }
+    get isLoggedIn() {
+        return Boolean(this.jar.get('auth_token'));
+    }
+    get ct0() {
+        return this.jar.get('ct0') ?? '';
+    }
+    /** `x-twitter-client-language` 与 `lang` cookie 一致（上游 with_client_language）。 */
+    get lang() {
+        return (this.jar.get('lang') || PROFILE.clientLanguage).toLowerCase();
+    }
+    /** twid cookie 里的数字用户 id（上游 XAuth.user_id）。 */
+    get userId() {
+        return userIdFromTwid(this.jar.get('twid'));
+    }
+    /**
+     * 建立会话（上游 XAuth.prepare_auth）：已登录会话的 ct0 由服务端签发，缺了只能报错；补上 lang cookie。
+     * 上游未登录时本地生成 ct0 给游客用，web 端没有游客态，不移植。
+     */
+    async init() {
+        if (this.isLoggedIn && !this.ct0)
+            throw authError(this.ctx, 'cookie 里有 auth_token 但缺 ct0，请把浏览器 cookie 完整复制过来');
+        if (!this.jar.has('lang'))
+            this.jar.set('lang', PROFILE.clientLanguage, COOKIE_DOMAIN);
+    }
+    view() {
+        return { bearer: PUBLIC_BEARER, ct0: this.ct0, lang: this.lang, loggedIn: this.isLoggedIn };
+    }
+    xctid(method, path) {
+        return transaction().generate(method.toUpperCase(), path);
+    }
+    // ---------------------------------------------------------------- GraphQL
+    /** query 型 GraphQL 读接口（GET）。读接口存在「部分成功」，有 data 时不抛。上游 graphql_get。 */
+    async graphqlGet(operationName, variables, options = {}) {
+        const op = new GraphQLOperation(operationName);
+        const res = await this.http.request({
+            method: 'GET',
+            url: op.url(),
+            query: op.queryParams(variables),
+            headers: this.graphqlHeaders(op.url(), 'GET', op.path(), options.referer),
+        });
+        return this.checkGraphQL(res, operationName, false);
+    }
+    /** POST 发送的 query 型操作（HomeTimeline 带 seenTweetIds、SearchTimeline）。上游 graphql_post_query。 */
+    async graphqlPostQuery(operationName, variables, options = {}) {
+        const op = new GraphQLOperation(operationName);
+        const res = await this.http.request({
+            method: 'POST',
+            url: op.url(),
+            json: op.jsonBody(variables),
+            headers: this.graphqlHeaders(op.url(), 'POST', op.path(), options.referer),
+        });
+        return this.checkGraphQL(res, operationName, false);
+    }
+    /** mutation 型写接口。上游 graphql_post：有 errors 就算失败。 */
+    async graphqlPost(operationName, variables, options = {}) {
+        const op = new GraphQLOperation(operationName);
+        const res = await this.http.request({
+            method: 'POST',
+            url: op.url(),
+            json: op.jsonBody(variables),
+            headers: this.graphqlHeaders(op.url(), 'POST', op.path(), options.referer),
+        });
+        return this.checkGraphQL(res, operationName, true);
+    }
+    graphqlHeaders(url, method, path, referer = `${X_HOST}/home`) {
+        return buildHeaders('GRAPHQL', url, this.view(), { xctid: this.xctid(method, path), referer });
+    }
+    /** 老 REST 表单接口（friendships 等）。上游 _rest_post。 */
+    async restPost(api, data) {
+        const url = `${X_HOST}/i/api/1.1${api}`;
+        const res = await this.http.request({
+            method: 'POST',
+            url,
+            form: data,
+            headers: buildHeaders('FORM', url, this.view(), { xctid: this.xctid('POST', `/i/api/1.1${api}`), referer: `${X_HOST}/home` }),
+        });
+        return this.checkJson(res, `/1.1${api}`);
+    }
+    /** 自定义请求（媒体上传、X Chat）。 */
+    request(req) {
+        return this.http.request(req);
+    }
+    buildHeaders(type, url, options = {}) {
+        return buildHeaders(type, url, this.view(), options);
+    }
+    /** 给不走 graphql* 的请求算 XCTID（媒体元数据、X Chat）。 */
+    transactionId(method, path) {
+        return this.xctid(method, path);
+    }
+    /** HTTP 状态不是 2xx 时报错（上游 raise_for_status），否则解析 JSON。operation 用在错误信息里。 */
+    async checkJson(res, operation = 'request') {
+        if (!res.ok)
+            throw this.httpError(res.status, await res.text(), operation);
+        return parseJson(res);
+    }
+    /** 只校验 HTTP 状态（响应体为空的接口）。 */
+    async checkOk(res, operation = 'request') {
+        if (!res.ok)
+            throw this.httpError(res.status, await res.text(), operation);
+    }
+    /**
+     * X 的 GraphQL 失败不一定用 HTTP 状态码表达：会话过期、限流都可能是 200 + errors。
+     * 读接口存在「部分成功」，有 data 时不抛；mutation 有 errors 就抛（上游 graphql_get / graphql_post）。
+     */
+    async checkGraphQL(res, operation, mutation) {
+        const body = await this.checkJson(res, operation);
+        const errors = body?.errors;
+        if (errors?.length && (mutation || !body.data))
+            throw this.mapErrors(new GraphQLError(operation, errors, body));
+        return body;
+    }
+    /**
+     * 非 2xx。X 的错误响应体多半也是 `{errors: [{code, message}]}`：REST 的业务拒绝（158 不能关注自己、
+     * 160 已发出关注请求、161 关注数到上限、162 被对方屏蔽）和 353（ct0 不匹配）都是 403，
+     * 所以先按错误码映射；没有错误码时，401 / 403 才当作登录态失效。
+     */
+    httpError(status, text, operation) {
+        let errors;
+        try {
+            errors = jsonLoads(text)?.errors;
+        }
+        catch { }
+        if (Array.isArray(errors) && errors[0]?.code != null)
+            return this.mapErrors(new GraphQLError(operation, errors, text.slice(0, 300)), status);
+        if (status === 401 || status === 403)
+            return authError(this.ctx);
+        if (status === 429)
+            return new SpecificAIError('RISK_CONTROL', `X 限流（HTTP ${status}）`, { detail: { kind: 'rate_limit', status } });
+        return new SpecificAIError('UPSTREAM', `X 返回 HTTP ${status}`, { detail: { status, body: text.slice(0, 300) } });
+    }
+    /** errors 里的错误码映射成 specific-ai 错误（AGENTS 6.4）；status 是 HTTP 状态（200 + errors 时不给）。 */
+    mapErrors(err, status) {
+        const code = err.code;
+        if (code != null && AUTH_CODES.has(code))
+            return authError(this.ctx, err.message);
+        if (code != null && RISK_CODES.has(code)) {
+            return new SpecificAIError('RISK_CONTROL', err.message, { detail: { kind: code === 88 ? 'rate_limit' : 'blocked', code, ...(status ? { status } : {}) } });
+        }
+        return new SpecificAIError('UPSTREAM', err.message, { detail: { code: code ?? null, operation: err.operation, errors: err.errors, ...(status ? { status } : {}) } });
+    }
+    /** 确认 cookie 里有 auth_token / ct0（registry 已挡住未登录，这里防 cookie 不全）。 */
+    requireLogin() {
+        if (!this.isLoggedIn || !this.ct0)
+            throw authError(this.ctx, '当前账号缺少 auth_token / ct0，请重新登录');
+    }
+}
+/** 建立 X 会话。 */
+export async function xclient(ctx) {
+    const x = new XClient(ctx);
+    await x.init();
+    return x;
+}
+export function multipartMedia(chunk) {
+    return { name: 'media', data: chunk, contentType: 'application/octet-stream', filename: 'blob' };
+}

package/dist/platforms/x/web/commands.js

@@ -0,0 +1,363 @@
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { SpecificAIError, toSpecificAIError } from '../../../core/errors.js';
+import { downloadMedia, readMedia } from '../../../core/files.js';
+import { cookieCredential, finishLogin, loginContext } from '../../../core/login.js';
+import * as n from '../../../core/normalize.js';
+import * as rand from '../../../core/rand.js';
+import { authError, paged } from '../../../core/toolkit.js';
+import * as api from './api.js';
+import { markdownToContentState, splitTitle } from './article.js';
+import { isAuthCode, xclient } from './client.js';
+import * as norm from './normalize.js';
+import { COOKIE_DOMAIN, PROFILE } from './profile.js';
+import { isUserId, parseArticleId, parseTweetId } from './resolve.js';
+// ================================================================ 公共
+/**
+ * 当前账号（Viewer）。cookie 失效时 X 仍回 200 和部分 data，只在 errors 里给 code 32，
+ * 所以按错误码判断登录态（上游 main.py 的 _saved_cookie_is_valid）。
+ */
+async function viewer(x) {
+    const res = await api.getViewer(x);
+    const u = res?.data?.viewer?.user_results?.result;
+    if (u?.rest_id)
+        return u;
+    const errors = res?.errors ?? [];
+    if (errors.some((e) => isAuthCode(e?.code)))
+        throw authError(x.ctx, errors.map((e) => e?.message).join('; '));
+    throw new SpecificAIError('UPSTREAM', 'Viewer 响应里没有当前用户', { detail: res });
+}
+/** 校验登录态用的 Viewer：cookie 无效或已失效时返回 null，其他错误照抛。 */
+async function viewerOrNull(x) {
+    try {
+        return await viewer(x);
+    }
+    catch (err) {
+        if (err instanceof SpecificAIError && (err.code === 'AUTH_EXPIRED' || err.code === 'AUTH_REQUIRED'))
+            return null;
+        throw err;
+    }
+}
+/** UserByScreenName / UserByRestId 响应里的用户；不存在、被封禁时报错。 */
+function userOf(res, input) {
+    const u = res?.data?.user?.result;
+    if (!u?.rest_id) {
+        const reason = u?.__typename === 'UserUnavailable' ? `：${u.message ?? u.reason ?? '不可用'}` : '';
+        throw new SpecificAIError('UPSTREAM', `用户 ${input} 不存在或不可见${reason}`, { detail: u ?? res });
+    }
+    return u;
+}
+/** 用户参数 → 数字 rest_id：`me` 取 twid，纯数字直接用，其余按用户名查（上游 get_user_id）。 */
+async function resolveUserId(x, input) {
+    if (input === 'me') {
+        x.requireLogin();
+        return x.userId || (await viewer(x)).rest_id;
+    }
+    if (isUserId(input))
+        return input.trim();
+    return userOf(await api.getUserInfo(x, input), input).rest_id;
+}
+/** 推文对象；已删除、受保护等不可见时报错。 */
+async function tweetOf(x, input) {
+    const res = await api.getWorkResult(x, input);
+    const t = res?.data?.tweetResult?.result;
+    if (!norm.unwrap(t)?.legacy) {
+        const reason = t?.reason ?? t?.tombstone?.text?.text;
+        throw new SpecificAIError('UPSTREAM', `推文 ${input} 不存在或不可见${reason ? `：${reason}` : ''}`, { detail: t ?? res });
+    }
+    return t;
+}
+/**
+ * 时间线分页：游标没变或这一页是空的就算翻到底了。
+ * got 是这一页取到的条数（过滤之前）；按类型过滤后这一页可能为空，但后面还有。
+ */
+function timeline(ctx, list, res, got = list.length) {
+    const next = norm.cursorOf(res, 'Bottom');
+    return paged(list, next, Boolean(next) && got > 0 && next !== ctx.cursor);
+}
+// ================================================================ auth
+/** 只支持 cookie 导入（注册表只声明了 cookie）；上游的账密登录依赖 Castle token，不移植。 */
+export async function authLogin(ctx) {
+    const credential = cookieCredential(ctx, COOKIE_DOMAIN);
+    const names = new Set(credential.scopes.main.cookies.map((c) => c.name));
+    if (!names.has('auth_token') || !names.has('ct0')) {
+        throw new SpecificAIError('USAGE', 'X 的 cookie 需要包含 auth_token 和 ct0', { hint: '在已登录的 x.com 页面复制完整的 Cookie 请求头' });
+    }
+    const me = await viewerOrNull(await xclient(loginContext(ctx, credential)));
+    if (!me)
+        throw new SpecificAIError('AUTH_REQUIRED', '登录没有成功：cookie 无效或已过期', { hint: '重新在浏览器登录 x.com 后复制 cookie' });
+    return finishLogin(ctx, credential, norm.userRef(me));
+}
+export async function authStatus(ctx) {
+    const x = await xclient(ctx);
+    const out = { logged_in: false, user: null, method: null, expires_at: null };
+    const me = x.isLoggedIn ? await viewerOrNull(x) : null;
+    if (!me)
+        return out;
+    const expires = x.jar.cookies.find((c) => c.name === 'auth_token')?.expires;
+    return { logged_in: true, user: norm.userRef(me), method: ctx.credential.method, expires_at: expires ? n.time(expires) : null };
+}
+// ================================================================ user
+export async function userGet(ctx) {
+    const x = await xclient(ctx);
+    const input = ctx.args.user;
+    if (input === 'me') {
+        x.requireLogin();
+        return norm.user(await viewer(x));
+    }
+    const res = isUserId(input) ? await api.getUserById(x, input.trim()) : await api.getUserInfo(x, input);
+    return norm.user(userOf(res, input));
+}
+export async function userSearch(ctx) {
+    const x = await xclient(ctx);
+    const res = await api.searchWork(x, ctx.args.keyword, ctx.cursor ?? undefined, 'People');
+    return timeline(ctx, norm.userResults(res).map(norm.user), res);
+}
+export async function userItems(ctx) {
+    const x = await xclient(ctx);
+    const id = await resolveUserId(x, ctx.args.user);
+    // 登录后主页 Posts 标签是 UserOriginalsTimeline（上游 get_user_post_note 的默认）
+    const res = await api.getUserPostNote(x, id, ctx.cursor ?? undefined);
+    return timeline(ctx, norm.tweetResults(res).map(norm.item), res);
+}
+async function follow(ctx, on) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const id = await resolveUserId(x, ctx.args.user);
+    await (on ? api.followUser(x, id) : api.unfollowUser(x, id));
+    return { id };
+}
+export const userFollow = (ctx) => follow(ctx, true);
+export const userUnfollow = (ctx) => follow(ctx, false);
+// ================================================================ item
+export async function itemGet(ctx) {
+    const x = await xclient(ctx);
+    return norm.item(await tweetOf(x, ctx.args.item));
+}
+const SEARCH_PRODUCT = { general: 'Top', latest: 'Latest' };
+/**
+ * `--type video|image` 走媒体搜索（product=Media，网页的「媒体」标签）：结果里图片和视频混在一起，
+ * 按 Item.kind 过滤（既有图又有视频的推文算 video）。
+ */
+export async function itemSearch(ctx) {
+    const { sort, type } = ctx.options;
+    const media = type === 'video' || type === 'image';
+    if (media && sort != null && sort !== 'general') {
+        throw new SpecificAIError('UNSUPPORTED', `X 的媒体搜索不能和 --sort ${sort} 一起用`, { hint: '去掉 --sort，或去掉 --type' });
+    }
+    const x = await xclient(ctx);
+    const product = media ? 'Media' : (SEARCH_PRODUCT[sort ?? 'general'] ?? 'Top');
+    const res = await api.searchWork(x, ctx.args.keyword, ctx.cursor ?? undefined, product);
+    const results = (media ? [...norm.tweetResults(res), ...norm.gridResults(res)] : norm.tweetResults(res)).map(norm.item);
+    return timeline(ctx, media ? results.filter((it) => it.kind === type) : results, res, results.length);
+}
+export async function itemMedia(ctx) {
+    const x = await xclient(ctx);
+    return norm.item(await tweetOf(x, ctx.args.item)).media;
+}
+export async function itemDownload(ctx) {
+    const x = await xclient(ctx);
+    const it = norm.item(await tweetOf(x, ctx.args.item));
+    // 图片显式要 orig 才是原图（上游 download_work）
+    const media = it.media.map((m) => (m.type === 'image' ? { ...m, url: `${m.url}?format=jpg&name=orig` } : m));
+    return downloadMedia(ctx, x.http, it.id, media, {
+        headers: [['user-agent', PROFILE.ua]],
+        ext: (m) => (m.type === 'image' ? 'jpg' : 'mp4'),
+    });
+}
+/** 点赞 / 收藏 / 转发这类只带推文 id 的写操作。 */
+async function act(ctx, target, call) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const id = parseTweetId(target);
+    await call(x, id);
+    return { id };
+}
+export const itemLike = (ctx) => act(ctx, ctx.args.item, api.favoriteTweet);
+export const itemUnlike = (ctx) => act(ctx, ctx.args.item, api.unfavoriteTweet);
+export const itemCollect = (ctx) => act(ctx, ctx.args.item, api.createBookmark);
+export const itemUncollect = (ctx) => act(ctx, ctx.args.item, api.deleteBookmark);
+export const itemRepost = (ctx) => act(ctx, ctx.args.item, api.createRetweet);
+export const itemUnrepost = (ctx) => act(ctx, ctx.args.item, api.deleteRetweet);
+export const itemDelete = (ctx) => act(ctx, ctx.args.item, api.deleteTweet);
+/** thread 两条之间的间隔（上游 post_thread 的 interval），太快容易触发风控。 */
+const THREAD_INTERVAL = 2000;
+/** `--quote`：链接原样作为 attachment_url（上游 quote_url）；给的是 ID 时先查出推文，用它的链接。 */
+async function quoteUrl(x, input) {
+    const id = parseTweetId(input);
+    if (id !== input.trim())
+        return input.trim();
+    return norm.item(await tweetOf(x, id)).url;
+}
+/**
+ * 发推：先传媒体（最多 4 张图，或 1 个视频），再发推。正文超过 280 权重时自动改发长推（CreateNoteTweet）。
+ * 带 `--thread` 时接着逐条发，每条回复上一条（上游 post_thread），返回第一条。上游 XWriteAPI.post_tweet。
+ */
+export async function itemPublish(ctx) {
+    const o = ctx.options;
+    const images = o.image ?? [];
+    if (images.length && o.video)
+        throw new SpecificAIError('USAGE', 'X 的一条推文不能同时带图片和视频');
+    if (images.length > 4)
+        throw new SpecificAIError('USAGE', 'X 的一条推文最多 4 张图片');
+    const text = o.text ?? '';
+    if (!text && !images.length && !o.video)
+        throw new SpecificAIError('USAGE', '发推需要 --text、--image 或 --video');
+    const thread = o.thread ?? [];
+    if (thread.some((t) => !t.trim()))
+        throw new SpecificAIError('USAGE', '--thread 的每一条都不能为空');
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const mediaIds = [];
+    for (const input of o.video ? [o.video] : images) {
+        const file = await readMedia(x.http, input);
+        mediaIds.push((await api.upload(x, file.data, file.filename)).mediaId);
+    }
+    const quote = o.quote ? await quoteUrl(x, o.quote) : undefined;
+    const first = api.createdTweet(await api.postTweet(x, text, mediaIds, undefined, quote));
+    const posted = [norm.item(first)];
+    for (const [i, t] of thread.entries()) {
+        await rand.sleep(THREAD_INTERVAL);
+        try {
+            posted.push(norm.item(api.createdTweet(await api.postTweet(x, t, [], posted.at(-1).id))));
+        }
+        catch (err) {
+            const e = toSpecificAIError(err);
+            // 中途失败：前面几条已经发出去了，把它们的 id 放进 detail，方便删除或接着发
+            throw new SpecificAIError(e.code, `thread 第 ${i + 2} 条失败：${e.message}`, {
+                hint: e.hint,
+                detail: { posted: posted.map((p) => ({ id: p.id, url: p.url })), error: e.detail },
+            });
+        }
+    }
+    return posted[0];
+}
+// ================================================================ comment
+export async function commentList(ctx) {
+    const x = await xclient(ctx);
+    const id = parseTweetId(ctx.args.item);
+    const res = await api.getWorkInfo(x, id, ctx.cursor ?? undefined);
+    return timeline(ctx, norm.replyResults(res).map((r) => norm.comment(r, id)), res);
+}
+/**
+ * 评论就是一条回复推文；`--reply-to` 时回复那条评论。和发推一样，正文超过 280 权重时自动改发长推
+ * （上游 main.py post --reply-to 走的就是 post_tweet）。
+ */
+export async function commentAdd(ctx) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const id = parseTweetId(ctx.args.item);
+    const to = ctx.options.replyTo;
+    const created = api.createdTweet(await api.postTweet(x, ctx.args.text, [], to ? parseTweetId(to) : id));
+    return norm.comment(created, id);
+}
+export const commentDelete = (ctx) => act(ctx, ctx.args.comment, api.deleteTweet);
+export const commentLike = (ctx) => act(ctx, ctx.args.comment, api.favoriteTweet);
+export const commentUnlike = (ctx) => act(ctx, ctx.args.comment, api.unfavoriteTweet);
+// ================================================================ feed
+export async function feedList(ctx) {
+    const kind = ctx.options.kind ?? 'recommend';
+    if (kind === 'following')
+        throw new SpecificAIError('NOT_IMPLEMENTED', 'x 的 feed list --kind following 尚未实现', { detail: { upstream: 'none' } });
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const res = await api.getHomeTimeline(x, ctx.cursor ?? undefined);
+    return timeline(ctx, norm.tweetResults(res).map(norm.item), res);
+}
+// ================================================================ msg（X Chat）
+/**
+ * 收件箱首页。单聊对方的资料缺名字时（参与者只有 rest_id），再用 GetUsersByIdsForXChat 查一次成员资料
+ * （上游 get_users_by_ids，网页进私信页时也发这个）。
+ *
+ * 只取首页：上游 get_initial_chat_page 的 max_local_sequence_id / message_pull_version 是增量同步的
+ * 水位（取某个序号之后的新消息事件），不是翻页游标；翻更早的会话要 GetInboxPageRequestQuery，上游没有。
+ */
+export async function msgList(ctx) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const page = (await api.getInitialChatPage(x))?.data?.get_initial_chat_page ?? {};
+    // 自己的 id 取 twid cookie；cookie 里没有 twid 时查一次 Viewer，不然会把自己当成对方
+    const self = x.userId || (await viewer(x)).rest_id;
+    const items = page.items ?? [];
+    const missing = [...new Set(items.flatMap((it) => norm.peersWithoutName(it, self)))];
+    const members = missing.length ? norm.memberResults(await api.getUsersByIds(x, missing)) : new Map();
+    return paged(items.map((it) => norm.conversation(it, self, members)), null, false);
+}
+export async function msgHistory(ctx) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const conversationId = ctx.args.conversation;
+    const page = (await api.getConversationPage(x, conversationId))?.data?.get_conversation_page ?? {};
+    const events = page.encoded_message_events ?? [];
+    if (events.length)
+        ctx.log.warn('X Chat 的消息是端到端加密的，specific-ai 不解密：只给出占位的消息，原始事件用 --raw 查看');
+    return paged(events.map((e, i) => norm.encryptedMessage(e, i, conversationId)), null, false);
+}
+// ================================================================ media
+export async function mediaUpload(ctx) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const file = await readMedia(x.http, ctx.args.file);
+    const { mediaId, mediaType, result } = await api.upload(x, file.data, file.filename);
+    const img = result?.image ?? {};
+    return n.media({ id: mediaId, type: mediaType.startsWith('video/') ? 'video' : 'image', url: null, width: n.count(img.w), height: n.count(img.h) }, result);
+}
+// ================================================================ article（平台扩展，AGENTS 4.7）
+const articleUrl = (id) => `https://x.com/i/article/${id}`;
+/** 在 specific-ai 的错误上补充已建草稿的信息：发布失败时草稿还在，方便到网页上处理或删除。 */
+function withDraft(err, articleId) {
+    const e = toSpecificAIError(err);
+    return new SpecificAIError(e.code, `${e.message}（草稿 ${articleId} 已创建）`, {
+        hint: e.hint ?? `到 ${api.articleEditUrl(articleId)} 查看，或 specific-ai x article delete ${articleId}`,
+        detail: { article_id: articleId, edit_url: api.articleEditUrl(articleId), error: e.detail },
+    });
+}
+/**
+ * 从 Markdown 发文章：传正文插图 → 建草稿 → 标题 → 正文 → 传封面、设封面 → 发布（同时生成一条文章推文）。
+ * 没给 `--title` 时取正文第一行的 `# 标题`。上游 XArticleAPI.post_article（publish=True）。
+ *
+ * 正文里 `![](图片)` 的相对路径按 Markdown 文件所在目录解析（上游 main.py 的 base_dir）：`--text @file`
+ * 时 dispatch 把文件路径记在 textFile 里，直接给正文时按当前目录。`--cover` 是命令行参数，按当前目录。
+ */
+export async function articlePublish(ctx) {
+    const o = ctx.options;
+    let title = o.title;
+    let body = o.text;
+    if (title == null)
+        [title, body] = splitTitle(body);
+    if (!title)
+        throw new SpecificAIError('USAGE', '文章标题不能为空：传 --title，或让正文第一行是 `# 标题`');
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const upload = async (input) => {
+        const file = await readMedia(x.http, input);
+        return api.articleUploadImage(x, file.data, file.filename);
+    };
+    const baseDir = o.textFile ? dirname(resolve(o.textFile)) : null;
+    const inline = (path) => upload(baseDir && !/^https?:\/\//i.test(path) && !isAbsolute(path) ? resolve(baseDir, path) : path);
+    const contentState = await markdownToContentState(body, inline);
+    const articleId = api.extractArticleId(await api.articleCreateDraft(x));
+    let published;
+    try {
+        await api.articleUpdateTitle(x, articleId, title);
+        await api.articleUpdateContent(x, articleId, contentState);
+        if (o.cover)
+            await api.articleUpdateCover(x, articleId, await upload(o.cover));
+        published = await api.articlePublish(x, articleId);
+    }
+    catch (err) {
+        throw withDraft(err, articleId);
+    }
+    // 发布时同时生成一条带文章卡片的推文（上游 cmd_article 打印的就是它）
+    const tweetId = api.articleTweetId(published);
+    if (tweetId)
+        ctx.log.info(`文章推文：${norm.tweetUrl(tweetId)}`);
+    return { id: articleId, url: articleUrl(articleId) };
+}
+/** 删文章：草稿或已发布的都可以，已发布的连同文章推文一起删（不可撤销）。上游 XArticleAPI.delete。 */
+export async function articleDelete(ctx) {
+    const x = await xclient(ctx);
+    x.requireLogin();
+    const id = parseArticleId(ctx.args.article);
+    await api.articleDelete(x, id);
+    return { id };
+}

package/dist/platforms/x/web/graphql.js

@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs';
+import { SpecificAIError } from '../../../core/errors.js';
+import { staticFile } from '../../../core/paths.js';
+import { compactJson } from '../../../core/py.js';
+/**
+ * GraphQL 操作装配，移植自上游 utils/graphql_registry.py + builder/params.py。
+ *
+ * queryId 与 features 不写死，全部取自 `static/x/graphql.json`（上游从线上前端机器提取的注册表）。
+ * 前端发版后在上游跑 `python main.py refresh-graphql`，再把 graphql.json 原样同步过来。
+ */
+const GRAPHQL_BASE = 'https://x.com/i/api/graphql';
+let cached = null;
+function registry() {
+    cached ??= JSON.parse(readFileSync(staticFile('x', 'graphql.json'), 'utf8'));
+    return cached;
+}
+/**
+ * 浏览器在各操作上实际发送的 fieldToggles 子集（上游 BROWSER_FIELD_TOGGLES，2026-08-16 / 09-27 实抓）。
+ * null 表示浏览器不发 fieldToggles；没登记的操作退回注册表全集。
+ */
+const BROWSER_FIELD_TOGGLES = {
+    SearchTimeline: null,
+    HomeTimeline: null,
+    CreateTweet: null,
+    // 长推：body 形态与 CreateTweet 相同，同样不发 fieldToggles
+    CreateNoteTweet: null,
+    // 文章编辑器全链路都不发 fieldToggles，虽然注册表里声明了 withPayments / withAuxiliaryUserLabels
+    ArticleEntityDraftCreate: null,
+    ArticleEntityUpdateTitle: null,
+    ArticleEntityUpdateContent: null,
+    ArticleEntityUpdateCoverMedia: null,
+    ArticleEntityPublish: null,
+    ArticleEntityDelete: null,
+    ArticleEntitiesSlice: null,
+    UserByScreenName: { withPayments: false, withAuxiliaryUserLabels: true },
+    UserTweets: { withArticlePlainText: false },
+    UserOriginalsTimeline: { withPayments: false, withArticlePlainText: false },
+    TweetDetail: {
+        withPayments: false,
+        withArticleRichContentState: true,
+        withArticlePlainText: false,
+        withArticleSummaryText: true,
+        withArticleVoiceOver: true,
+        withGrokAnalyze: false,
+        withDisallowedReplyControls: false,
+    },
+    TweetResultByRestId: {
+        withArticleRichContentState: true,
+        withArticlePlainText: false,
+        withArticleSummaryText: true,
+        withArticleVoiceOver: true,
+        withPayments: false,
+    },
+};
+/** 一个 GraphQL 操作的完整请求形态（上游 GraphQLOperation）。 */
+export class GraphQLOperation {
+    name;
+    meta;
+    constructor(name) {
+        this.name = name;
+        const op = registry().operations[name];
+        if (!op)
+            throw new SpecificAIError('UPSTREAM', `GraphQL 注册表里没有操作 ${name}，可能是前端改名或本地注册表过期`);
+        this.meta = op;
+    }
+    /** XCTID 要的 pathname：与真实请求路径一致，不含 query。 */
+    path() {
+        return `/i/api/graphql/${this.meta.queryId}/${this.name}`;
+    }
+    url() {
+        return `${GRAPHQL_BASE}/${this.meta.queryId}/${this.name}`;
+    }
+    /** 按操作声明的开关名，从 defaults 取布尔值（上游 build_features）。 */
+    features() {
+        const defaults = registry().featureDefaults;
+        return Object.fromEntries(this.meta.featureSwitches.map((k) => [k, defaults[k] ?? false]));
+    }
+    /** 浏览器实抓的子集，没登记时用注册表全集（上游 _resolve_toggles）。 */
+    fieldToggles() {
+        if (this.name in BROWSER_FIELD_TOGGLES)
+            return BROWSER_FIELD_TOGGLES[this.name];
+        const defaults = registry().featureDefaults;
+        return Object.fromEntries(this.meta.fieldToggles.map((k) => [k, defaults[k] ?? false]));
+    }
+    /** GET 型操作的 query 参数；features / fieldToggles 为空时不带（上游 query_params）。 */
+    queryParams(variables) {
+        const params = [['variables', compactJson(variables)]];
+        const features = this.features();
+        if (Object.keys(features).length)
+            params.push(['features', compactJson(features)]);
+        const toggles = this.fieldToggles();
+        if (toggles && Object.keys(toggles).length)
+            params.push(['fieldToggles', compactJson(toggles)]);
+        return params;
+    }
+    /** POST 型操作的请求体：variables [+ features] [+ fieldToggles] + queryId（上游 json_body）。 */
+    jsonBody(variables) {
+        const body = new Map([['variables', variables]]);
+        const features = this.features();
+        if (Object.keys(features).length)
+            body.set('features', features);
+        const toggles = this.fieldToggles();
+        if (toggles && Object.keys(toggles).length)
+            body.set('fieldToggles', toggles);
+        body.set('queryId', this.meta.queryId);
+        return body;
+    }
+}