@nextclaw/x-harness 0.0.0-stage → 0.1.1

package/dist/browser-native.js

@@ -0,0 +1,215 @@
+import { createAXHarness } from "./readers-ax-host.js";
+import { readAX } from "./readers-ax-parser.js";
+import { xURL } from "./platform-rules.js";
+import { serialized, missingMethods, plain, valueOf, } from "./browser-common.js";
+export function createNativeXBrowser(app) {
+    async function navigateNativeTarget(command) {
+        xURL(command.url);
+        if (!command.evidenceRef)
+            throw new Error("导航URL缺原观察证据");
+        await low.observe({ mode: "navigation" }).then((raw) => {
+            current = { raw };
+        });
+        let index = one((e) => /^文本栏 .*地址和搜索栏/.test(e.label));
+        await low
+            .act({
+            index,
+            operation: "fill",
+            value: command.url,
+            read: { mode: "navigation" },
+        })
+            .then((raw) => {
+            current = { raw };
+        });
+        index = one((e) => /^文本栏 .*地址和搜索栏/.test(e.label));
+        await low.act({
+            index,
+            operation: "pressKey",
+            value: "Return",
+            read: { mode: "navigation" },
+        });
+        current = null;
+        return;
+    }
+    let latestAX;
+    const delegated = {};
+    for (const name of [
+        "getAXState",
+        "click",
+        "pressKey",
+        "paste",
+        "scroll",
+        "performSecondaryAction",
+        "getScreenshot",
+    ]) {
+        Object.defineProperty(delegated, name, {
+            get() {
+                if (typeof app?.[name] !== "function")
+                    return undefined;
+                return name === "getAXState"
+                    ? async (options) => {
+                        latestAX = await app.getAXState(options);
+                        return latestAX;
+                    }
+                    : (...args) => app[name](...args);
+            },
+        });
+    }
+    const low = createAXHarness(delegated);
+    let current;
+    const modes = {
+        account: "navigation",
+        person: "profile",
+        posts: "posts",
+        composer: "composer",
+    };
+    async function observe(query) {
+        current = null;
+        if (!modes[query.view])
+            throw new Error("未封装的业务视图");
+        const raw = await low.observe({
+            mode: modes[query.view],
+            ...(query.targetId ? { targetId: query.targetId } : {}),
+            limit: query.limit ?? 1,
+        });
+        current = { query, raw };
+        const entries = raw.evidence ?? [];
+        // Bind actor and target to the SAME suppressed observation; no additional tool round trip.
+        const ownLinks = readAX(latestAX, { mode: "navigation" }).evidence.filter((e) => /^link 个人资料, Value: x\.com\/\w+$/.test(e.label));
+        const base = {
+            page: raw.page,
+            alerts: raw.alerts,
+            needsStateCheck: raw.needsStateCheck,
+            missing: raw.missing ?? [],
+            accountHandle: ownLinks.length === 1
+                ? ownLinks[0].label.match(/x\.com\/(\w+)$/)[1]
+                : null,
+        };
+        if (query.view === "account") {
+            const own = entries.filter((e) => /^link 个人资料, Value: x\.com\/\w+$/.test(e.label));
+            return {
+                ...base,
+                accountHandle: own.length === 1 ? own[0].label.match(/x\.com\/(\w+)$/)[1] : null,
+                accountURL: own.length === 1 ? `https://${valueOf(own[0].label)}` : null,
+            };
+        }
+        if (query.view === "person") {
+            const labels = entries.map((e) => plain(e.label));
+            return {
+                ...base,
+                handle: query.handle,
+                relationship: labels.includes(`正在关注 @${query.handle}`) ||
+                    labels.includes(`取消关注 @${query.handle}`)
+                    ? "following"
+                    : labels.includes(`回关 @${query.handle}`)
+                        ? "follows-you"
+                        : labels.includes(`关注 @${query.handle}`)
+                            ? "not-following"
+                            : "unknown",
+                blue: null,
+            };
+        }
+        if (query.view === "composer") {
+            const editors = entries.filter((e) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(e.label));
+            const ids = [
+                ...new Set(entries.flatMap((e) => e.label.match(/x\.com\/\w+\/status\/(\d+)(?:,|$)/)?.[1] ?? [])),
+            ];
+            return {
+                ...base,
+                editorText: editors.length === 1 ? valueOf(editors[0].label) : null,
+                replyToId: ids.length === 1 ? ids[0] : null,
+            };
+        }
+        return {
+            ...base,
+            posts: (raw.posts ?? []).map((p) => ({
+                ...p,
+                body: p.text,
+                replyToId: null,
+            })),
+        };
+    }
+    const one = (predicate) => {
+        const entries = (current?.raw.evidence ?? [])
+            .concat(current?.raw.navigation ?? [])
+            .filter(predicate);
+        if (entries.length !== 1)
+            throw new Error("语义控件未唯一观察：先补能力/证据");
+        return entries[0].index;
+    };
+    return serialized({
+        capabilities(operation) {
+            if (["readBookmarks", "searchSources", "readFeedback"].includes(operation))
+                return [`native.${operation}`];
+            const names = operation === "read"
+                ? ["getAXState"]
+                : ["getAXState", "click", "pressKey", "paste"];
+            return operation === "attachAssets"
+                ? ["native.attachAssets"]
+                : operation === "refreshPosts"
+                    ? ["native.refreshPosts"]
+                    : missingMethods(app, names);
+        },
+        observe,
+        async act(command) {
+            if (command.operation === "openObserved") {
+                return navigateNativeTarget(command);
+            }
+            if (command.operation === "refreshPerson") {
+                xURL(command.url);
+                await low.observe({ mode: "navigation" }).then((raw) => {
+                    current = { raw };
+                });
+                const index = one((e) => /^按钮 (重新加载|刷新)(?:,|$)/.test(e.label));
+                current = null;
+                return low.act({
+                    index,
+                    operation: "click",
+                    read: { mode: "profile" },
+                });
+            }
+            if (!current)
+                throw new Error("语义操作必须先observe");
+            let index, operation = "click", value;
+            if (command.operation === "follow")
+                index = one((e) => [
+                    `按钮 关注 @${command.handle}`,
+                    `按钮 回关 @${command.handle}`,
+                ].includes(e.label));
+            else if (command.operation === "openReply") {
+                if (current.query?.targetId !== command.postId)
+                    throw new Error("回复目标不匹配");
+                const target = current.raw.posts?.filter((p) => p.id === command.postId);
+                if (target?.length !== 1)
+                    throw new Error("回复主帖不唯一");
+                const buttons = target[0].evidence.filter((e) => /^按钮 .*回复/.test(e.label));
+                if (buttons.length !== 1)
+                    throw new Error("回复按钮不唯一");
+                index = buttons[0].index;
+            }
+            else if (command.operation === "fillComposer") {
+                index = one((e) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(e.label));
+                operation = "fill";
+                value = command.text;
+            }
+            else if (["submitPost", "submitReply"].includes(command.operation)) {
+                index = one((e) => new RegExp(command.operation === "submitReply"
+                    ? "^按钮 (回复|Reply)(?:,|$)"
+                    : "^按钮 (发帖|发布|Post)(?:,|$)", "i").test(e.label));
+            }
+            else
+                throw new Error("未封装的原生动作");
+            const read = {
+                mode: command.operation === "follow" ? "profile" : "composer",
+            };
+            if (["submitPost", "submitReply"].includes(command.operation))
+                await command.beforeSubmit?.();
+            current = null;
+            return low.act({ index, operation, value, read });
+        },
+        screenshot: () => {
+            current = null;
+            return low.screenshot();
+        },
+    });
+}

package/dist/browser.d.ts

@@ -0,0 +1,4 @@
+export { createDOMXBrowser, readXNetworkDiagnostics } from "./browser-dom.js";
+export { createNativeXBrowser } from "./browser-native.js";
+export declare function readXSurface({ view, posts, targetId, replyTargetId, }?: any): any;
+export declare const atomicObservationCode: string;

package/dist/browser.js

@@ -0,0 +1,147 @@
+import { readProfile } from "./readers-profile.js";
+import { readPosts } from "./readers-posts.js";
+import { readComposer, readMediaEditor } from "./readers-composer.js";
+import { readNavigation, readMenu } from "./readers-navigation.js";
+export { createDOMXBrowser, readXNetworkDiagnostics } from "./browser-dom.js";
+export { createNativeXBrowser } from "./browser-native.js";
+// Read-only supplement: account identity, composer context and exact tweet bodies.
+// Existing readers still own article/profile/composer boundaries.
+export function readXSurface({ view, posts = [], targetId, replyTargetId, } = {}) {
+    const visible = (el) => el.getClientRects().length > 0;
+    const profile = [...document.querySelectorAll("a[href]")].filter((el) => visible(el) &&
+        ["个人资料", "Profile"].includes(el.getAttribute("aria-label") || el.innerText.trim()) &&
+        /^\/\w{1,15}$/.test(el.getAttribute("href")));
+    const own = profile.length === 1 ? profile[0].getAttribute("href").slice(1) : null;
+    const base = {
+        page: location.href,
+        accountHandle: own,
+        accountURL: own ? `https://x.com/${own}` : null,
+        alerts: [...document.querySelectorAll('[role="alert"]')]
+            .filter(visible)
+            .map((el) => el.innerText),
+    };
+    if (view === "composer") {
+        const dialogs = [
+            ...document.querySelectorAll('[role="dialog"]'),
+        ].filter(visible);
+        const ids = dialogs.length === 1
+            ? [
+                ...new Set([...dialogs[0].querySelectorAll("a[href]")]
+                    .filter(visible)
+                    .flatMap((el) => el
+                    .getAttribute("href")
+                    .match(/^\/\w+\/status\/(\d+)$/)?.[1] ?? [])),
+            ]
+            : [];
+        const replyContexts = [...new Set(dialogs.map((el) => el.innerText))];
+        const replyQuotes = [
+            ...new Set(dialogs.flatMap((el) => [...el.querySelectorAll('[data-testid="tweetText"]')]
+                .filter(visible)
+                .map((text) => text.innerText))),
+        ];
+        return {
+            ...base,
+            replyToId: ids.length === 1 ? ids[0] : null,
+            inlineComposer: dialogs.length === 0,
+            replyContexts,
+            replyQuotes,
+        };
+    }
+    if (view === "posts") {
+        const all = [...document.querySelectorAll("article")].filter(visible);
+        return {
+            ...base,
+            bodies: posts.map((post) => {
+                const articles = all.filter((article) => [...article.querySelectorAll("time")]
+                    .filter(visible)
+                    .find((time) => time.closest("a")?.getAttribute("href") === post.primary)
+                    ?.closest("a")
+                    ?.getAttribute("href") === post.primary);
+                const texts = articles.length === 1
+                    ? [
+                        ...articles[0].querySelectorAll('[data-testid="tweetText"]'),
+                    ].filter((el) => visible(el) && !el.closest?.('[role="link"][tabindex="0"]'))
+                    : [];
+                let replyToId = null, parentEvidence = null;
+                const childIndex = all.indexOf(articles[0]);
+                if (replyTargetId &&
+                    targetId === post.id &&
+                    articles.length === 1 &&
+                    childIndex > 0 &&
+                    new URL(location.href).pathname.endsWith(`/status/${post.id}`)) {
+                    // Nested conversations can include older ancestors before the direct parent.
+                    const parent = [...all[childIndex - 1].querySelectorAll("time")]
+                        .filter(visible)
+                        .find((time) => /^\/\w+\/status\/\d+$/.test(time.closest("a")?.getAttribute("href") ?? ""))
+                        ?.closest("a")
+                        ?.getAttribute("href");
+                    const match = parent?.match(/^\/(\w+)\/status\/(\d+)$/);
+                    const labels = [...articles[0].querySelectorAll("div,span")]
+                        .filter(visible)
+                        .filter((el) => !el.closest('[data-testid="tweetText"]') &&
+                        !el.querySelector('[data-testid="tweetText"]'))
+                        .map((el) => el.innerText.trim().replace(/\s+/g, " "));
+                    const directLabel = match &&
+                        labels.some((text) => [`回复 @${match[1]}`, `Replying to @${match[1]}`].includes(text));
+                    // X can omit the inline reply label on a permalink. Its title still prefixes the direct
+                    // recipient before older ancestors; require that prefix and the adjacent parent together.
+                    const titleRecipient = (document.title ?? "").match(/[“"]@([A-Za-z0-9_]{1,15})(?=\s)/)?.[1];
+                    const titleMatchesParent = match && titleRecipient?.toLowerCase() === match[1].toLowerCase();
+                    if (match?.[2] === replyTargetId &&
+                        (directLabel || titleMatchesParent)) {
+                        replyToId = match[2];
+                        parentEvidence = {
+                            parentPrimary: parent,
+                            childPrimary: post.primary,
+                            labels: labels.filter((text) => /^(回复|Replying to) @/.test(text)),
+                            ...(titleMatchesParent ? { titleRecipient } : {}),
+                        };
+                    }
+                }
+                // Exclude observed nested quote-card text; any remaining ambiguity stays unknown.
+                return {
+                    id: post.id,
+                    body: texts.length === 1
+                        ? (() => {
+                            const root = texts[0];
+                            // innerText adds layout breaks around inline mentions and URLs.
+                            // Reconstruct only observed X permalinks; preserve all other text.
+                            const read = (node) => {
+                                if (node.nodeType === 3)
+                                    return node.textContent ?? "";
+                                if (node.nodeType === 1 &&
+                                    node.tagName === "A") {
+                                    const href = node.getAttribute("href") ?? "";
+                                    if (/^\/\w{1,15}\/status\/\d+$/.test(href))
+                                        return `https://x.com${href}`;
+                                }
+                                return [...node.childNodes].map(read).join("");
+                            };
+                            return root.childNodes ? read(root) : root.innerText;
+                        })()
+                        : null,
+                    replyToId,
+                    parentEvidence,
+                };
+            }),
+        };
+    }
+    return base;
+}
+// CUA accepts a page-function string. Compose the existing read-only parsers,
+// rather than running two browser requests or maintaining another tweet parser.
+export const atomicObservationCode = `(query) => {
+  const readPosts = ${readPosts.toString()};
+  const readProfile = ${readProfile.toString()};
+  const readComposer = ${readComposer.toString()};
+  const readMediaEditor = ${readMediaEditor.toString()};
+  const readNavigation = ${readNavigation.toString()};
+  const readMenu = ${readMenu.toString()};
+  const readXSurface = ${readXSurface.toString()};
+  const readers = { posts:readPosts, person:readProfile, composer:readComposer, media:readMediaEditor, navigation:readNavigation, menu:readMenu, account:()=>({}) };
+  if (!readers[query.view]) throw new Error('未封装的DOM视图');
+  const raw = readers[query.view](query);
+  const surface = readXSurface({...query, posts:(raw.posts??[]).map(p=>({id:p.id,primary:p.primary}))});
+  return {...raw,...surface,needsStateCheck:Boolean(raw.needsStateCheck)||!surface.accountHandle,
+    ...(query.view==='posts'?{posts:raw.posts.map(p=>({...p,...surface.bodies.find(b=>b.id===p.id)}))}: {})};
+}`;

package/dist/creator.d.ts

@@ -0,0 +1,29 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { CreatorOptions } from "./types.js";
+export declare function readCreatorMeta(): {
+    headerText: null;
+    totalPostsText: null;
+    missing: string[];
+    externalLinks?: undefined;
+} | {
+    headerText: string;
+    totalPostsText: string | null;
+    externalLinks: (string | null)[];
+    missing: string[];
+};
+export declare function readCreatorPostExtras(): {
+    id: string | null;
+    metricDescriptions: (string | null)[];
+    analytics: {
+        label: string | null;
+        text: string;
+    }[];
+    images: {
+        alt: string | null;
+        src: string | null;
+    }[];
+    videoElements: number;
+    quoted: boolean;
+    pinned: boolean;
+}[];
+export declare function collectCreatorDOM(tab: BoundaryRecord, handle: string, { target, maxScrolls, navigate, expand, }?: Omit<CreatorOptions, "handle" | "mode">): Promise<BoundaryRecord>;

package/dist/creator.js

@@ -0,0 +1,164 @@
+import { readProfile } from "./readers-profile.js";
+import { readXObservation } from "./observation.js";
+// Read-only DOM metadata. Counts retain the platform's displayed precision.
+export function readCreatorMeta() {
+    const main = document.querySelector("main");
+    if (!main)
+        return { headerText: null, totalPostsText: null, missing: ["main"] };
+    const first = main.querySelector("article");
+    const body = main.innerText;
+    const boundary = first ? body.indexOf(first.innerText) : -1;
+    const headerText = boundary >= 0 ? body.slice(0, boundary) : body;
+    return {
+        headerText,
+        totalPostsText: headerText.match(/([\d,.]+\s*(?:万|亿|[KMB])?)\s*帖子/)?.[0] ?? null,
+        externalLinks: [
+            ...new Set(Array.from(main.querySelectorAll("a[href]"))
+                .filter((a) => !a.closest("article"))
+                .map((a) => a.getAttribute("href"))
+                .filter((h) => /^https?:/.test(h ?? ""))),
+        ],
+        missing: first ? [] : ["timeline-not-loaded"],
+    };
+}
+export function readCreatorPostExtras() {
+    return Array.from(document.querySelectorAll("article"))
+        .filter((a) => a.getClientRects().length)
+        .map((a) => {
+        const primary = Array.from(a.querySelectorAll("time"))
+            .find((t) => t.getClientRects().length > 0 &&
+            /\/status\/\d+(?:$|[/?#])/.test(t.closest("a")?.getAttribute("href") ?? ""))
+            ?.closest("a")
+            ?.getAttribute("href");
+        const id = primary?.match(/\/status\/(\d+)/)?.[1] ?? null;
+        return {
+            id,
+            metricDescriptions: Array.from(a.querySelectorAll("[aria-label]"))
+                .map((e) => e.getAttribute("aria-label"))
+                .filter((l) => /回复|喜欢|书签|次观看|次查看/.test(l ?? "")),
+            analytics: Array.from(a.querySelectorAll("a[href]"))
+                .filter((l) => l.getAttribute("href")?.includes(`/status/${id}/analytics`))
+                .map((l) => ({
+                label: l.getAttribute("aria-label"),
+                text: l.innerText,
+            })),
+            images: Array.from(a.querySelectorAll("img")).map((i) => ({
+                alt: i.getAttribute("alt"),
+                src: i.getAttribute("src"),
+            })),
+            videoElements: a.querySelectorAll("video").length,
+            quoted: /\n引用\n/.test(a.innerText),
+            pinned: a.innerText.startsWith("已置顶"),
+        };
+    });
+}
+export async function collectCreatorDOM(tab, handle, { target = 10, maxScrolls = 18, navigate = true, expand = true, } = {}) {
+    if (!/^[A-Za-z0-9_]{1,15}$/.test(handle) ||
+        !Number.isInteger(target) ||
+        target < 1 ||
+        target > 50 ||
+        !Number.isInteger(maxScrolls) ||
+        maxScrolls < 0 ||
+        maxScrolls > 50)
+        throw Error("Invalid creator collection input");
+    const url = `https://x.com/${handle}`;
+    if (navigate) {
+        if ((await tab.url()) === url)
+            await tab.reload();
+        else
+            await tab.goto(url);
+    }
+    const current = new URL(await tab.url());
+    if (current.origin !== "https://x.com" ||
+        current.pathname.toLowerCase() !== "/" + handle.toLowerCase())
+        throw Error("creator-url-mismatch");
+    await tab.getAXState({ emit: false });
+    await tab.playwright
+        .locator("article")
+        .first()
+        .waitFor({ state: "visible", timeoutMs: 15000 });
+    const profile = await tab.playwright.evaluate(readProfile, { handle });
+    const meta = await tab.playwright.evaluate(readCreatorMeta);
+    const posts = new Map();
+    let scrolls = 0;
+    let stagnant = 0;
+    for (;;) {
+        if (expand) {
+            const buttons = await tab.playwright
+                .locator("article")
+                .getByRole("button", { name: "显示更多", exact: true })
+                .all();
+            for (const button of buttons) {
+                try {
+                    await button.click({ timeoutMs: 1000 });
+                }
+                catch (error) {
+                    if (!(error instanceof Error) ||
+                        !/timed out|timeout/i.test(error.message))
+                        throw error;
+                    /* Keep needsExpansion as evidence of incomplete text. */
+                }
+            }
+            if (buttons.length)
+                await tab.getAXState({ emit: false });
+        }
+        const extras = new Map((await tab.playwright.evaluate(readCreatorPostExtras)).map((p) => [p.id, p]));
+        const before = posts.size;
+        for (let offset = 0;; offset += 5) {
+            const read = await tab.playwright.evaluate(readXObservation, {
+                view: "posts",
+                offset,
+                limit: 5,
+            });
+            if (read.alerts?.length)
+                return {
+                    profile,
+                    meta,
+                    posts: [...posts.values()],
+                    complete: false,
+                    alerts: read.alerts,
+                    scrolls,
+                    observedAt: new Date().toISOString(),
+                };
+            for (const post of read.posts) {
+                const extra = extras.get(post.id) ?? {};
+                if (post.author?.toLowerCase() === handle.toLowerCase() &&
+                    !extra.pinned &&
+                    !/^(.*转帖了|.*已转帖)/.test((post.text ?? post.body ?? "").split("\n")[0]))
+                    posts.set(post.id, { ...post, ...extra, images: post.images });
+            }
+            if (!read.moreInDOM || posts.size >= target)
+                break;
+            if (offset >= 245)
+                break;
+            /* finite safety bound for unusual retained DOM */
+        }
+        if (posts.size >= target || scrolls >= maxScrolls || stagnant >= 6)
+            break;
+        stagnant = posts.size === before ? stagnant + 1 : 0;
+        await tab.scroll([780, 690], "down", 4);
+        await tab.getAXState({ emit: false });
+        scrolls++;
+    }
+    const selected = [...posts.values()]
+        .sort((a, b) => (b.datetime ?? "").localeCompare(a.datetime ?? ""))
+        .slice(0, target);
+    const missing = [
+        ...new Set(selected.flatMap((p) => [
+            !p.datetime ? "absolute-time-missing" : null,
+            p.needsExpansion ? "post-needs-expansion" : null,
+            !p.body ? "post-body-missing" : null,
+        ].filter(Boolean))),
+    ];
+    if (posts.size < target)
+        missing.push("creator-target-not-reached");
+    return {
+        profile,
+        meta,
+        posts: selected,
+        complete: missing.length === 0,
+        missing,
+        scrolls,
+        observedAt: new Date().toISOString(),
+    };
+}

package/dist/growth-batch.d.ts

@@ -0,0 +1,5 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare function createFollowBatch(dependencies: Pick<GrowthDependencies, "prepareActionsForCall" | "store" | "scope" | "stamp" | "clock" | "evidenceExists" | "executor" | "parallelRound" | "round">): {
+    followBatch: ({ taskId, handles, preparedActions }?: any) => Promise<BoundaryRecord>;
+};