@nextclaw/x-harness 0.0.0-stage → 0.1.1

package/dist/readers-posts.js

@@ -0,0 +1,141 @@
+// Self-contained, read-only DOM function for cua_repl's documented evaluate.
+export function readPosts({ offset = 0, limit = 5, targetId = "", } = {}) {
+    if (!Number.isInteger(offset) ||
+        offset < 0 ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 5)
+        throw new Error("offset>=0；limit为1～5");
+    if (targetId && !/^\d+$/.test(targetId))
+        throw new Error("targetId必须是数字公开ID");
+    const visible = (el) => el.getClientRects().length > 0;
+    const primaryTime = (a) => Array.from(a.querySelectorAll("time")).find((t) => visible(t) &&
+        /\/status\/\d+(?:$|[/?#])/.test(t.closest("a")?.getAttribute("href") ?? "")) ?? null;
+    const all = Array.from(document.querySelectorAll("article")).filter(visible);
+    const candidates = targetId
+        ? all.filter((a) => {
+            const primary = primaryTime(a)?.closest("a")?.getAttribute("href");
+            return (primary && new RegExp(`/status/${targetId}(?:$|[/?#])`).test(primary));
+        })
+        : all;
+    const posts = candidates.slice(offset, offset + limit).map((a) => {
+        const time = primaryTime(a);
+        const primary = time?.closest("a")?.getAttribute("href") ?? null;
+        const links = [
+            ...new Set(Array.from(a.querySelectorAll("a[href]"))
+                .filter(visible)
+                .map((l) => l.getAttribute("href"))),
+        ];
+        const buttons = Array.from(a.querySelectorAll("button"))
+            .filter(visible)
+            .map((b) => ({
+            label: b.getAttribute("aria-label") || b.innerText,
+            disabled: b.hasAttribute("disabled"),
+        }));
+        const text = a.innerText;
+        const datetime = time?.getAttribute("datetime") ?? null;
+        const id = primary?.match(/\/status\/(\d+)/)?.[1] ?? null;
+        const author = primary?.match(/\/([^/]+)\/status\//)?.[1] ?? null;
+        const images = Array.from(a.querySelectorAll('[data-testid="tweetPhoto"] img'))
+            .filter(visible)
+            .map((img) => ({
+            alt: img.getAttribute("alt"),
+            src: img.getAttribute("src"),
+        }));
+        const media = Array.from(a.querySelectorAll('[data-testid="videoPlayer"],video'))
+            .filter(visible)
+            .map((el) => ({
+            kind: "video",
+            label: el.getAttribute("aria-label"),
+            poster: el.getAttribute("poster"),
+            requiresViewing: true,
+        }));
+        return {
+            id,
+            author,
+            datetime,
+            primary,
+            text,
+            links,
+            buttons,
+            // View/quote counts may be visible links rather than buttons; collect in this same read.
+            metrics: [
+                ...buttons,
+                ...Array.from(a.querySelectorAll('a[href$="/analytics"],a[href$="/quotes"]'))
+                    .filter(visible)
+                    .map((link) => ({
+                    label: link.getAttribute("aria-label") ||
+                        `${link.getAttribute("href").endsWith("/analytics") ? "观看" : "引用"} ${link.innerText}`,
+                })),
+            ],
+            images,
+            media,
+            needsExpansion: /显示更多|Show more/i.test(text),
+            missing: [
+                !id && "id",
+                !author && "author",
+                !datetime && "datetime",
+                !text && "text",
+            ].filter(Boolean),
+        };
+    });
+    const versionLinks = Array.from(document.querySelectorAll("a[href]"))
+        .filter(visible)
+        .filter((a) => /最新版本|查看最新帖子|Latest version|View latest/i.test(a.innerText))
+        .slice(0, 5)
+        .map((a) => ({ label: a.innerText, href: a.getAttribute("href") }));
+    const emptyEvidence = all.length === 0
+        ? [
+            ...new Set(Array.from(document.querySelectorAll("main span"))
+                .filter(visible)
+                .map((e) => e.innerText?.trim())
+                .filter((text) => text &&
+                text.length <= 400 &&
+                !text.includes("\n") &&
+                /^(?:没有.*结果|未找到.*结果|No results for)/i.test(text))),
+        ].slice(0, 2)
+        : [];
+    return {
+        renderedArticles: all.length,
+        matched: candidates.length,
+        offset,
+        moreInDOM: candidates.length > offset + posts.length,
+        pageComplete: false,
+        needsStateCheck: all.length === 0 && emptyEvidence.length === 0,
+        posts,
+        versionLinks,
+        emptyEvidence,
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((e) => e.innerText),
+    };
+}
+export function changes(result, cache, page, fresh = false) {
+    const unchangedIds = [];
+    const posts = result.posts.filter((post) => {
+        if (!post.id)
+            return true;
+        const key = `${page}|${post.id}`;
+        const value = JSON.stringify(post);
+        const changed = cache[key] !== value;
+        cache[key] = value;
+        if (!fresh && !changed)
+            unchangedIds.push(post.id);
+        return fresh || changed;
+    });
+    const outputChars = JSON.stringify({ ...result, posts, unchangedIds }).length;
+    const optimizationHint = outputChars > 8000
+        ? posts.length > 1
+            ? "缩小读取窗口或按已观察ID定向读取；保留完整正文"
+            : "单篇证据本身长，保留全文，不截断"
+        : null;
+    return {
+        ...result,
+        posts,
+        unchanged: result.posts.length - posts.length,
+        unchangedIds,
+        fresh,
+        outputChars,
+        optimizationHint,
+    };
+}

package/dist/readers-profile.d.ts

@@ -0,0 +1,3 @@
+export declare function readProfile({ handle }?: any): any;
+export declare function readPeople({ offset, limit }?: any): any;
+export declare function screenCandidates(profiles: any, { minRatio }?: any): any;

package/dist/readers-profile.js

@@ -0,0 +1,157 @@
+// Profile selectors are the visible controls observed in the live X workflow.
+// Missing/ambiguous counters remain unknown; rounded counts carry their precision.
+export function readProfile({ handle } = {}) {
+    if (!/^[A-Za-z0-9_]{1,15}$/.test(handle ?? ""))
+        throw new Error("需要已观察的X handle");
+    const visible = (el) => el.getClientRects().length > 0;
+    const main = document.querySelector("main");
+    if (!main)
+        return {
+            handle,
+            blue: null,
+            relationship: "unknown",
+            alerts: ["missing-main"],
+            observedAt: new Date().toISOString(),
+        };
+    const buttons = Array.from(main.querySelectorAll("button")).filter(visible);
+    const labels = buttons.map((b) => b.getAttribute("aria-label") || b.innerText);
+    const relationship = labels.includes(`正在关注 @${handle}`) ||
+        labels.includes(`取消关注 @${handle}`)
+        ? "following"
+        : labels.includes(`回关 @${handle}`)
+            ? "follows-you"
+            : labels.includes(`关注 @${handle}`)
+                ? "not-following"
+                : "unknown";
+    const badges = buttons
+        .filter((b) => b.getAttribute("aria-label") === "提供已验证账号的详细信息。")
+        .map((b) => b.querySelector("svg"))
+        .filter(Boolean);
+    const blue = badges.length === 1
+        ? [
+            getComputedStyle(badges[0]).color,
+            getComputedStyle(badges[0]).fill,
+        ].includes("rgb(29, 155, 240)")
+        : null;
+    const links = Array.from(main.querySelectorAll("a[href]")).filter(visible);
+    const counter = (suffixes) => {
+        const matched = links.filter((a) => suffixes.some((s) => a.getAttribute("href")?.toLowerCase() ===
+            `/${handle}/${s}`.toLowerCase()));
+        const texts = [...new Set(matched.map((a) => a.innerText.trim()))];
+        if (texts.length !== 1)
+            return { value: null, text: texts, precision: "unknown" };
+        const match = texts[0].match(/^([\d,.]+)\s*(万|亿|[KMB])?/i);
+        const factors = {
+            万: 1e4,
+            亿: 1e8,
+            K: 1e3,
+            M: 1e6,
+            B: 1e9,
+        };
+        const value = match
+            ? Number(match[1].replaceAll(",", "")) *
+                (factors[match[2]?.toUpperCase()] ?? 1)
+            : null;
+        const hrefs = [...new Set(matched.map((a) => a.getAttribute("href")))];
+        return {
+            value: Number.isFinite(value) ? value : null,
+            text: texts[0],
+            precision: match?.[2] ? "rounded" : "exact",
+            url: hrefs.length === 1 ? "https://x.com" + hrefs[0] : null,
+        };
+    };
+    return {
+        handle,
+        blue,
+        relationship,
+        relationshipControls: labels
+            .filter((label) => label.includes("@" + handle) || /取消关注|订阅/.test(label))
+            .slice(0, 5),
+        biography: main.querySelector('[data-testid="UserDescription"]')
+            ?.innerText ?? null,
+        following: counter(["following"]),
+        followers: counter(["followers", "verified_followers"]),
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((a) => a.innerText),
+        observedAt: new Date().toISOString(),
+    };
+}
+// Bounded visible person cells for a currently loaded follower/following list.
+export function readPeople({ offset = 0, limit = 5 } = {}) {
+    if (!Number.isInteger(offset) ||
+        offset < 0 ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 5)
+        throw new Error("人物窗口须为非负offset及1–5 limit");
+    const visible = (el) => el.getClientRects().length > 0;
+    const cells = Array.from(document.querySelectorAll('main [data-testid="UserCell"]')).filter(visible);
+    const people = cells.slice(offset, offset + limit).map((cell) => {
+        const links = Array.from(cell.querySelectorAll("a[href]"))
+            .filter(visible)
+            .map((a) => ({ text: a.innerText, href: a.getAttribute("href") }));
+        const buttons = Array.from(cell.querySelectorAll("button"))
+            .filter(visible)
+            .map((b) => ({
+            label: b.getAttribute("aria-label") || b.innerText,
+            disabled: b.disabled,
+        }));
+        return { text: cell.innerText, links, buttons };
+    });
+    return {
+        page: location.href,
+        people,
+        offset,
+        renderedPeople: cells.length,
+        moreInDOM: offset + limit < cells.length,
+        pageComplete: false,
+        needsStateCheck: !people.length,
+        missing: people.length ? [] : ["people-cells-not-found"],
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((a) => a.innerText),
+        observedAt: new Date().toISOString(),
+    };
+}
+// This ranks observed clues, never a predicted follow-back probability.
+export function screenCandidates(profiles, { minRatio = 0.8 } = {}) {
+    if (!Array.isArray(profiles) || !Number.isFinite(minRatio) || minRatio <= 0)
+        throw new Error("profiles数组和正minRatio必填");
+    const seen = new Set();
+    return profiles
+        .map((p) => {
+        const key = String(p.handle ?? "").toLowerCase();
+        const duplicate = seen.has(key);
+        seen.add(key);
+        const following = p.following?.value, followers = p.followers?.value;
+        const ratio = Number.isFinite(following) &&
+            Number.isFinite(followers) &&
+            followers > 0
+            ? following / followers
+            : null;
+        const clues = [];
+        if (typeof p.mutualEvidence === "string" && p.mutualEvidence.trim())
+            clues.push({ kind: "explicit-mutual", evidence: p.mutualEvidence });
+        if (ratio !== null && ratio >= minRatio)
+            clues.push({
+                kind: "following-ratio",
+                ratio,
+                following: p.following,
+                followers: p.followers,
+                evidence: "关注/粉丝比例线索，非回关概率",
+            });
+        const rejected = [
+            duplicate && "duplicate",
+            p.blue !== true && "blue-unconfirmed",
+            p.relationship !== "not-following" && "relationship-ineligible",
+            p.alerts?.length && "page-alert",
+            !clues.length && "no-followback-clue",
+            !/^[A-Za-z0-9_]{1,15}$/.test(p.handle ?? "") && "invalid-handle",
+        ].filter(Boolean);
+        return { ...p, ratio, clues, eligible: rejected.length === 0, rejected };
+    })
+        .sort((a, b) => Number(b.eligible) - Number(a.eligible) ||
+        Number(b.clues.some((c) => c.kind === "explicit-mutual")) -
+            Number(a.clues.some((c) => c.kind === "explicit-mutual")));
+}

package/dist/readers.d.ts

@@ -0,0 +1,9 @@
+/** Compatibility exports only. Implementation owners are task-specific modules. */
+export { readPosts, changes } from "./readers-posts.js";
+export { readAX } from "./readers-ax-parser.js";
+export { createAXTabHarness, createAXHarness } from "./readers-ax-host.js";
+export { readProfile, readPeople, screenCandidates, } from "./readers-profile.js";
+export { readComposer, readMediaEditor } from "./readers-composer.js";
+export { readMenu, readNavigation } from "./readers-navigation.js";
+export { attachImage, openReply } from "./readers-actions.js";
+export { setupCode, profileCode, profilesCode, browserCode, axCode, runReaderCLI, } from "./readers-cli.js";

package/dist/results.d.ts

@@ -0,0 +1,6 @@
+import type { PostEvidence, ReadResult, ReadMode, Diagnostic, ExecutionDecision } from "./types.js";
+export declare const stableReason: (value: unknown) => string | undefined;
+export declare function diagnostic(value: unknown): Diagnostic | undefined;
+export declare function source(value: unknown, page?: string): PostEvidence;
+export declare function readResult(operation: string, value: unknown, mode: ReadMode): ReadResult;
+export declare function decisions(value: unknown): ExecutionDecision[];

package/dist/results.js

@@ -0,0 +1,233 @@
+const object = (value) => value && typeof value === "object" ? value : {};
+const list = (value) => (Array.isArray(value) ? value : []);
+const strings = (value) => list(value).filter((v) => typeof v === "string");
+function pick(value, keys) {
+    const input = object(value), out = {};
+    for (const key of keys) {
+        const v = input[key];
+        if (v !== undefined &&
+            (v === null || ["string", "number", "boolean"].includes(typeof v)))
+            out[key] = v;
+    }
+    return out;
+}
+export const stableReason = (value) => typeof value === "string"
+    ? /^[a-z][a-z0-9.-]{0,95}$/.test(value)
+        ? value
+        : "harness-boundary-error"
+    : undefined;
+export function diagnostic(value) {
+    const raw = object(value);
+    if (typeof raw.code !== "string")
+        return undefined;
+    return {
+        ...pick(raw, ["operation", "category", "next", "evidenceRef"]),
+        code: stableReason(raw.code),
+    };
+}
+export function source(value, page) {
+    const raw = object(value), out = pick(raw, [
+        "id",
+        "author",
+        "datetime",
+        "url",
+        "body",
+        "needsExpansion",
+    ]);
+    out.id = typeof raw.id === "string" ? raw.id : null;
+    if (out.body === undefined && typeof raw.text === "string")
+        out.body = raw.text;
+    if (!out.url && typeof raw.primary === "string" && page) {
+        try {
+            out.url = new URL(raw.primary, page).href;
+        }
+        catch {
+            /* explicit missing below */
+        }
+    }
+    if (raw.images !== undefined)
+        out.images = list(raw.images).map((v) => pick(v, ["src", "alt"]));
+    if (raw.media !== undefined)
+        out.media = list(raw.media).map((v) => pick(v, [
+            "kind",
+            "src",
+            "poster",
+            "label",
+            "duration",
+            "requiresViewing",
+        ]));
+    if (raw.links !== undefined)
+        out.links = list(raw.links).flatMap((v) => typeof v === "string"
+            ? [v]
+            : typeof object(v).href === "string"
+                ? [
+                    pick(v, ["href", "text", "label"]),
+                ]
+                : []);
+    if (out.links)
+        out.links = out.links.filter((link) => isContentLink(link, out));
+    if (strings(raw.missing).length)
+        out.missing = strings(raw.missing);
+    return out;
+}
+function isContentLink(link, post) {
+    const href = typeof link === "string" ? link : link.href;
+    try {
+        const url = new URL(href, post.url ?? "https://x.com");
+        if (url.hostname !== "x.com")
+            return true;
+        if (/\/status\/\d+\/(?:analytics|quotes|retweets|likes|bookmarks)\/?$/.test(url.pathname))
+            return false;
+        if (post.author &&
+            url.pathname.toLowerCase() === `/${post.author}`.toLowerCase())
+            return false;
+        if (post.url && url.href === new URL(post.url).href)
+            return false;
+    }
+    catch {
+        /* Keep an observed unresolved link; do not infer its destination. */
+    }
+    return true;
+}
+function person(value) {
+    const raw = object(value), out = pick(raw, [
+        "handle",
+        "url",
+        "blue",
+        "relationship",
+        "biography",
+    ]);
+    for (const key of ["following", "followers"]) {
+        if (raw[key] !== undefined) {
+            out[key] =
+                raw[key] === null
+                    ? null
+                    : pick(raw[key], ["value", "raw", "text", "precision", "url"]);
+            const counter = object(raw[key]);
+            if (out[key] && Array.isArray(counter.text))
+                out[key].text = strings(counter.text);
+        }
+    }
+    return out;
+}
+function feedback(value) {
+    const raw = object(value), out = pick(raw, ["id", "pageComplete"]);
+    if (raw.metrics !== undefined)
+        out.metrics = list(raw.metrics).flatMap((v) => {
+            const label = typeof v === "string" ? v : object(v).label, value = object(v).value;
+            if (typeof label !== "string" ||
+                !/(?:回复|转帖|喜欢|书签|观看|查看|引用|replies|reply|reposts?|retweets?|likes?|bookmarks?|views?|quotes?)/i.test(label))
+                return [];
+            if (!/\d/.test(label) &&
+                typeof value !== "number" &&
+                typeof value !== "string")
+                return [];
+            return [typeof v === "string" ? v : pick(v, ["label", "value"])];
+        });
+    if (out.metrics)
+        out.metrics = [
+            ...new Map(out.metrics.map((metric) => [JSON.stringify(metric), metric])).values(),
+        ];
+    if (raw.replies !== undefined)
+        out.replies = list(raw.replies).map((v) => source(v));
+    if (raw.unconfirmedReplyIds !== undefined)
+        out.unconfirmedReplyIds = strings(raw.unconfirmedReplyIds);
+    if (strings(raw.missing).length)
+        out.missing = strings(raw.missing);
+    return out;
+}
+export function readResult(operation, value, mode) {
+    const raw = object(value), out = pick(raw, [
+        "status",
+        "fresh",
+        "complete",
+        "pageComplete",
+        "evidenceRef",
+        "reason",
+    ]);
+    if (out.reason)
+        out.reason = stableReason(out.reason);
+    if (!["observed", "needsDecision", "needsCapability"].includes(out.status))
+        out.status = "needsDecision";
+    if (out.status !== "observed" && out.complete === undefined)
+        out.complete = false;
+    if (raw.ids !== undefined)
+        out.ids = strings(raw.ids);
+    const missing = strings(raw.missing);
+    if (list(raw.alerts).length && !missing.includes("platform-alert"))
+        missing.push("platform-alert");
+    if (missing.length)
+        out.missing = missing;
+    const d = diagnostic(raw.diagnostic);
+    if (d)
+        out.diagnostic = d;
+    if (operation === "inspectAccount")
+        Object.assign(out, pick(raw, ["accountHandle", "accountURL"]));
+    if (mode === "receipt")
+        return out;
+    if (operation === "readPost") {
+        const posts = list(raw.posts);
+        if (posts.length === 1)
+            out.post = source(posts[0], typeof raw.page === "string" ? raw.page : undefined);
+    }
+    else if (operation === "readPerson" && typeof raw.handle === "string")
+        out.person = person(raw);
+    else if (operation === "readCreator" && raw.profile && raw.meta) {
+        const meta = object(raw.meta);
+        const header = typeof meta.headerText === "string" ? meta.headerText : "";
+        out.person = person(raw.profile);
+        out.creator = {
+            ...pick(raw, ["scrolls", "observedAt"]),
+            ...pick(meta, ["totalPostsText"]),
+            name: header.split("\n")[0] || null,
+            joined: header.match(/\d{4}年\d{1,2}月 加入/)?.[0] ?? null,
+            externalLinks: strings(meta.externalLinks).filter((href) => {
+                try {
+                    const host = new URL(href).hostname;
+                    return !/(^|\.)(?:x\.com|twitter\.com)$/.test(host);
+                }
+                catch {
+                    return true;
+                }
+            }),
+        };
+        out.sources = list(raw.sources).map((v) => {
+            const row = object(v);
+            const post = source(v, typeof raw.page === "string" ? raw.page : undefined);
+            post.metrics = [
+                ...new Set([
+                    ...strings(row.metricDescriptions),
+                    ...list(row.buttons).map((b) => object(b).label),
+                    ...list(row.analytics).map((a) => object(a).label),
+                ].filter((label) => typeof label === "string" &&
+                    /(?:回复|转帖|喜欢|书签|观看|查看|replies|reposts?|likes?|bookmarks?|views?)/i.test(label) &&
+                    /\d/.test(label))),
+            ];
+            Object.assign(post, pick(row, ["quoted", "videoElements"]));
+            return post;
+        });
+    }
+    else if (raw.sources !== undefined)
+        out.sources = list(raw.sources).map((v) => source(v));
+    else if (raw.feedback !== undefined)
+        out.feedback = list(raw.feedback).map(feedback);
+    return out;
+}
+export function decisions(value) {
+    return list(value).map((v) => {
+        const raw = object(v), out = pick(raw, [
+            "actionId",
+            "kind",
+            "status",
+            "reason",
+            "resumeAt",
+            "owner",
+            "evidenceRef",
+        ]);
+        if (out.reason)
+            out.reason = stableReason(out.reason);
+        if (strings(raw.missing).length)
+            out.missing = strings(raw.missing);
+        return out;
+    });
+}

package/dist/round-state.d.ts

@@ -0,0 +1,3 @@
+export declare function checkRound(state: any, { now, evidenceExists }?: any): any;
+export declare function readRound(markdown: any): any;
+export declare function runRoundCLI(): void;