@jackwener/opencli 1.7.12 → 1.7.13

package/clis/pubmed/utils.js

@@ -0,0 +1,309 @@
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+export const EUTILS_BASE = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils';
+export const SEARCH_COLUMNS = ['rank', 'pmid', 'title', 'authors', 'journal', 'year', 'article_type', 'doi', 'url'];
+export const LINK_COLUMNS = ['rank', 'pmid', 'title', 'authors', 'journal', 'year', 'article_type', 'doi', 'url'];
+export const RELATED_COLUMNS = ['rank', 'pmid', 'title', 'authors', 'journal', 'year', 'article_type', 'score', 'doi', 'url'];
+
+let lastRequestAt = 0;
+
+export function requireText(value, label) {
+    const text = String(value ?? '').trim();
+    if (!text) {
+        throw new ArgumentError(`pubmed ${label} cannot be empty`);
+    }
+    return text;
+}
+
+export function requirePmid(value, label = 'pmid') {
+    const pmid = requireText(value, label);
+    if (!/^\d+$/.test(pmid)) {
+        throw new ArgumentError(`pubmed ${label} must be a numeric PMID`, 'Example: 37780221');
+    }
+    return pmid;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const text = String(raw).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new ArgumentError(`pubmed ${label} must be a positive integer`);
+    }
+    const n = Number(text);
+    if (!Number.isSafeInteger(n) || n < 1) {
+        throw new ArgumentError(`pubmed ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`pubmed ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireYear(value, label) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const year = requireBoundedInt(value, 1900, 3000, label);
+    if (year < 1800) {
+        throw new ArgumentError(`pubmed ${label} must be >= 1800`);
+    }
+    return year;
+}
+
+export function requireChoice(value, choices, label, defaultValue) {
+    const text = String(value ?? defaultValue).trim();
+    if (!choices.includes(text)) {
+        throw new ArgumentError(`pubmed ${label} must be one of: ${choices.join(', ')}`);
+    }
+    return text;
+}
+
+export function buildEutilsUrl(tool, params = {}) {
+    const searchParams = new URLSearchParams();
+    searchParams.set('db', 'pubmed');
+    if (!params.retmode) {
+        searchParams.set('retmode', 'json');
+    }
+    if (process.env.NCBI_API_KEY) {
+        searchParams.set('api_key', process.env.NCBI_API_KEY);
+    }
+    if (process.env.NCBI_EMAIL) {
+        searchParams.set('email', process.env.NCBI_EMAIL);
+    }
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null && value !== '') {
+            searchParams.set(key, String(value));
+        }
+    }
+    return `${EUTILS_BASE}/${tool}.fcgi?${searchParams.toString()}`;
+}
+
+async function waitForRateLimit() {
+    if (process.env.NODE_ENV === 'test') {
+        return;
+    }
+    const delayMs = process.env.NCBI_API_KEY ? 110 : 360;
+    const now = Date.now();
+    const waitMs = Math.max(0, lastRequestAt + delayMs - now);
+    if (waitMs > 0) {
+        await new Promise(resolve => setTimeout(resolve, waitMs));
+    }
+    lastRequestAt = Date.now();
+}
+
+export async function eutilsFetch(tool, params = {}, { retmode = 'json', label = 'PubMed E-utilities' } = {}) {
+    const url = buildEutilsUrl(tool, { ...params, retmode });
+    await waitForRateLimit();
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(`${label} request failed`, detail);
+    }
+    if (!response.ok) {
+        throw new CommandExecutionError(`${label} HTTP ${response.status}`, 'Check NCBI availability, request parameters, and optional NCBI_API_KEY.');
+    }
+    if (retmode === 'xml') {
+        return response.text();
+    }
+    try {
+        const json = await response.json();
+        assertNoEutilsError(json, label);
+        return json;
+    }
+    catch (error) {
+        if (error instanceof CommandExecutionError) {
+            throw error;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(`${label} returned invalid JSON`, detail);
+    }
+}
+
+export function assertNoEutilsError(json, label = 'PubMed E-utilities') {
+    const error = json?.error
+        || json?.esearchresult?.errorlist?.phrasesnotfound?.join(', ')
+        || json?.esearchresult?.errorlist?.fieldsnotfound?.join(', ');
+    if (error) {
+        throw new CommandExecutionError(`${label} returned an error`, String(error));
+    }
+}
+
+export function buildPubMedUrl(pmid) {
+    return `https://pubmed.ncbi.nlm.nih.gov/${pmid}/`;
+}
+
+export function decodeXmlEntities(value) {
+    return String(value ?? '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#39;/g, "'")
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10)));
+}
+
+export function cleanText(value) {
+    return decodeXmlEntities(value).replace(/\s+/g, ' ').trim();
+}
+
+export function truncateText(value, maxLength) {
+    const text = cleanText(value);
+    if (!text || text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, maxLength - 3)}...`;
+}
+
+export function extractFirst(xml, tag) {
+    const match = String(xml ?? '').match(new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'i'));
+    return match ? cleanText(match[1].replace(/<[^>]+>/g, ' ')) : '';
+}
+
+export function extractAll(xml, tag) {
+    const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'gi');
+    const out = [];
+    let match;
+    while ((match = re.exec(String(xml ?? ''))) !== null) {
+        out.push(cleanText(match[1].replace(/<[^>]+>/g, ' ')));
+    }
+    return out;
+}
+
+export function extractAttribute(xml, tag, attr) {
+    const match = String(xml ?? '').match(new RegExp(`<${tag}\\b[^>]*\\b${attr}="([^"]*)"`, 'i'));
+    return match ? decodeXmlEntities(match[1]) : '';
+}
+
+export function extractAuthors(authorList, maxAuthors = 3) {
+    if (!Array.isArray(authorList) || authorList.length === 0) {
+        return '';
+    }
+    const names = authorList.map(author => author?.name || author?.collectivename || [author?.lastname, author?.initials].filter(Boolean).join(' ')).filter(Boolean);
+    const shown = names.slice(0, maxAuthors);
+    if (names.length > maxAuthors) {
+        shown.push('et al.');
+    }
+    return shown.join(', ');
+}
+
+export function extractDoi(articleIds) {
+    if (!Array.isArray(articleIds)) {
+        return '';
+    }
+    const doi = articleIds.find(id => String(id?.idtype ?? '').toLowerCase() === 'doi');
+    return String(doi?.value ?? '').trim();
+}
+
+export function articleTypeFromList(types) {
+    const values = Array.isArray(types)
+        ? types.map(type => typeof type === 'string' ? type : type?.value).filter(Boolean)
+        : [];
+    const priority = ['Systematic Review', 'Meta-Analysis', 'Review', 'Randomized Controlled Trial', 'Clinical Trial', 'Case Reports', 'Journal Article'];
+    for (const wanted of priority) {
+        const found = values.find(type => type.toLowerCase() === wanted.toLowerCase());
+        if (found) {
+            return found;
+        }
+    }
+    return values[0] || 'Journal Article';
+}
+
+export function summaryToRow(article, rank, pmid = article?.uid) {
+    const id = String(pmid ?? article?.uid ?? '').trim();
+    return {
+        rank,
+        pmid: id,
+        title: truncateText(String(article?.title ?? '').replace(/\.$/, ''), 120),
+        authors: extractAuthors(article?.authors, 3),
+        journal: truncateText(article?.fulljournalname || article?.source || '', 60),
+        year: String(article?.pubdate ?? '').split(' ')[0] || '',
+        article_type: articleTypeFromList(article?.pubtype),
+        doi: extractDoi(article?.articleids),
+        url: buildPubMedUrl(id),
+    };
+}
+
+export function ensureCompleteSummaryRows(pmids, result, commandLabel) {
+    if (!result || typeof result !== 'object' || !result.result || typeof result.result !== 'object') {
+        throw new CommandExecutionError(`${commandLabel} returned an unreadable summary payload`);
+    }
+    const rows = pmids.map((pmid, index) => {
+        const article = result.result[pmid];
+        if (!article) {
+            return null;
+        }
+        return summaryToRow(article, index + 1, pmid);
+    });
+    if (rows.some(row => row === null)) {
+        throw new CommandExecutionError(`${commandLabel} omitted summaries for one or more PMIDs`, 'Refusing to return a partial result set.');
+    }
+    return rows;
+}
+
+export function buildSearchQuery(query, filters = {}) {
+    const terms = [requireText(query, 'query')];
+    if (filters.author) terms.push(`${requireText(filters.author, 'author')}[Author]`);
+    if (filters.journal) terms.push(`${requireText(filters.journal, 'journal')}[Journal]`);
+    if (filters.yearFrom || filters.yearTo) {
+        const from = filters.yearFrom || 1800;
+        const to = filters.yearTo || new Date().getFullYear();
+        if (from > to) {
+            throw new ArgumentError('pubmed year-from must be <= year-to');
+        }
+        terms.push(`${from}:${to}[PDAT]`);
+    }
+    if (filters.articleType) terms.push(`${requireText(filters.articleType, 'article-type')}[PT]`);
+    if (filters.hasAbstract) terms.push('hasabstract[text]');
+    if (filters.hasFullText) terms.push('free full text[sb]');
+    if (filters.humanOnly) terms.push('humans[mesh]');
+    if (filters.englishOnly) terms.push('english[lang]');
+    return terms.join(' AND ');
+}
+
+export function parseArticleXml(xml, pmid) {
+    const text = String(xml ?? '');
+    if (!text || /<ERROR\b/i.test(text) || !/<PubmedArticle\b/i.test(text)) {
+        return null;
+    }
+    const articleBlock = text.match(/<Article\b[^>]*>([\s\S]*?)<\/Article>/i)?.[1] || text;
+    const journalBlock = articleBlock.match(/<Journal\b[^>]*>([\s\S]*?)<\/Journal>/i)?.[1] || '';
+    const journalIssue = journalBlock.match(/<JournalIssue\b[^>]*>([\s\S]*?)<\/JournalIssue>/i)?.[1] || '';
+    const pubDate = journalIssue.match(/<PubDate\b[^>]*>([\s\S]*?)<\/PubDate>/i)?.[1] || '';
+    const authorBlocks = [...text.matchAll(/<Author\b[^>]*>([\s\S]*?)<\/Author>/gi)].map(match => match[1]);
+    const authors = authorBlocks.map(block => {
+        const name = extractFirst(block, 'CollectiveName') || [extractFirst(block, 'LastName'), extractFirst(block, 'ForeName') || extractFirst(block, 'Initials')].filter(Boolean).join(' ');
+        return name;
+    }).filter(Boolean);
+    const abstract = extractAll(articleBlock, 'AbstractText').join(' ');
+    const pubTypes = extractAll(articleBlock, 'PublicationType');
+    const meshTerms = extractAll(text, 'DescriptorName');
+    const keywords = extractAll(text, 'Keyword');
+    const doi = text.match(/<ArticleId\b[^>]*IdType="doi"[^>]*>([\s\S]*?)<\/ArticleId>/i)?.[1] || '';
+    const pmc = text.match(/<ArticleId\b[^>]*IdType="pmc"[^>]*>([\s\S]*?)<\/ArticleId>/i)?.[1] || '';
+    return {
+        pmid,
+        title: extractFirst(articleBlock, 'ArticleTitle'),
+        abstract,
+        authors,
+        journal: extractFirst(journalBlock, 'Title') || extractFirst(journalBlock, 'ISOAbbreviation'),
+        year: extractFirst(pubDate, 'Year') || extractFirst(text, 'MedlineDate').slice(0, 4),
+        date: [extractFirst(pubDate, 'Year'), extractFirst(pubDate, 'Month'), extractFirst(pubDate, 'Day')].filter(Boolean).join(' '),
+        doi: cleanText(doi),
+        pmc: cleanText(pmc),
+        article_type: articleTypeFromList(pubTypes),
+        language: extractFirst(articleBlock, 'Language'),
+        mesh_terms: meshTerms.slice(0, 10).join(', '),
+        keywords: keywords.slice(0, 10).join(', '),
+        url: buildPubMedUrl(pmid),
+    };
+}
+
+export async function fetchSummaryRows(pmids, commandLabel) {
+    const result = await eutilsFetch('esummary', { id: pmids.join(',') }, { label: commandLabel });
+    return ensureCompleteSummaryRows(pmids, result, commandLabel);
+}

package/clis/pypi/downloads.js

@@ -0,0 +1,66 @@
+// pypi downloads — fetch download counts for a single PyPI package via
+// pypistats.org's public JSON API.
+//
+// Default endpoint is `/api/packages/<pkg>/recent` which returns last-day /
+// last-week / last-month totals as a single row. Pass `--period overall` to
+// hit `/api/packages/<pkg>/overall` for the full daily history (one row per
+// day).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { PYPISTATS_BASE, pypiFetch, requirePackageName } from './utils.js';
+
+const PERIODS = new Set(['recent', 'overall']);
+
+function requirePeriod(value) {
+    const s = String(value ?? 'recent').trim().toLowerCase();
+    if (!PERIODS.has(s)) {
+        throw new ArgumentError(
+            `pypi downloads period "${value}" is invalid`,
+            'Allowed values: recent (default — last day/week/month totals) or overall (full daily history).',
+        );
+    }
+    return s;
+}
+
+cli({
+    site: 'pypi',
+    name: 'downloads',
+    access: 'read',
+    description: 'PyPI download stats for a package (recent totals or full daily history)',
+    domain: 'pypistats.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'PyPI package name (e.g. "requests", "pandas")' },
+        { name: 'period', default: 'recent', help: 'recent (default — 1 row, last day/week/month) or overall (1 row per day)' },
+    ],
+    columns: ['rank', 'package', 'period', 'date', 'downloads'],
+    func: async (args) => {
+        const name = requirePackageName(args.name);
+        const period = requirePeriod(args.period);
+        if (period === 'recent') {
+            const body = await pypiFetch(`${PYPISTATS_BASE}/api/packages/${encodeURIComponent(name)}/recent`, `pypi downloads ${name}`);
+            const data = body?.data;
+            if (!data || (data.last_day == null && data.last_week == null && data.last_month == null)) {
+                throw new EmptyResultError('pypi downloads', `pypistats has no recent download data for "${name}".`);
+            }
+            return [
+                { rank: 1, package: String(body.package ?? name), period: 'last_day', date: '', downloads: data.last_day != null ? Number(data.last_day) : null },
+                { rank: 2, package: String(body.package ?? name), period: 'last_week', date: '', downloads: data.last_week != null ? Number(data.last_week) : null },
+                { rank: 3, package: String(body.package ?? name), period: 'last_month', date: '', downloads: data.last_month != null ? Number(data.last_month) : null },
+            ];
+        }
+        const body = await pypiFetch(`${PYPISTATS_BASE}/api/packages/${encodeURIComponent(name)}/overall?mirrors=false`, `pypi downloads ${name}`);
+        const days = Array.isArray(body?.data) ? body.data : [];
+        if (!days.length) {
+            throw new EmptyResultError('pypi downloads', `pypistats has no overall download history for "${name}".`);
+        }
+        return days.map((row, i) => ({
+            rank: i + 1,
+            package: String(body.package ?? name),
+            period: 'daily',
+            date: String(row.date ?? ''),
+            downloads: row.downloads != null ? Number(row.downloads) : null,
+        }));
+    },
+});

package/clis/pypi/package.js

@@ -0,0 +1,79 @@
+// pypi package — fetch a single PyPI package's metadata.
+//
+// Hits `https://pypi.org/pypi/<pkg>/json`. Returns the most agent-useful
+// projection: name, latest version, summary, author, license, homepage,
+// project URLs, requires-python, last-modified time. Download stats are
+// intentionally separate (see `pypi downloads`).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { PYPI_BASE, pypiFetch, requirePackageName } from './utils.js';
+
+function pickHomepage(info) {
+    if (info.home_page) return String(info.home_page);
+    const proj = info.project_urls;
+    if (proj && typeof proj === 'object') {
+        return String(proj.Homepage || proj.homepage || proj.Documentation || proj.Source || proj['Source Code'] || '');
+    }
+    return '';
+}
+
+function pickRepository(info) {
+    const proj = info.project_urls;
+    if (proj && typeof proj === 'object') {
+        return String(proj.Source || proj['Source Code'] || proj.Repository || proj.repository || '');
+    }
+    return '';
+}
+
+cli({
+    site: 'pypi',
+    name: 'package',
+    access: 'read',
+    description: 'Single PyPI package metadata (latest version, license, homepage, classifiers)',
+    domain: 'pypi.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'PyPI package name (e.g. "requests", "pandas")' },
+    ],
+    columns: [
+        'name', 'latestVersion', 'summary', 'author', 'license', 'homepage', 'repository',
+        'requiresPython', 'keywords', 'releases', 'firstReleased', 'lastReleased', 'url',
+    ],
+    func: async (args) => {
+        const name = requirePackageName(args.name);
+        const body = await pypiFetch(`${PYPI_BASE}/pypi/${encodeURIComponent(name)}/json`, `pypi package ${name}`);
+        const info = body?.info;
+        if (!info || !info.name) {
+            throw new EmptyResultError('pypi package', `PyPI returned no metadata for "${name}".`);
+        }
+        const releases = body?.releases ?? {};
+        const releaseVersions = Object.keys(releases).filter((v) => Array.isArray(releases[v]) && releases[v].length > 0);
+        // earliest / latest release timestamps from the upload_time fields
+        let firstReleased = '';
+        let lastReleased = '';
+        for (const v of releaseVersions) {
+            for (const file of releases[v]) {
+                const t = String(file?.upload_time ?? '').slice(0, 10);
+                if (!t) continue;
+                if (!firstReleased || t < firstReleased) firstReleased = t;
+                if (!lastReleased || t > lastReleased) lastReleased = t;
+            }
+        }
+        return [{
+            name: String(info.name),
+            latestVersion: String(info.version ?? ''),
+            summary: String(info.summary ?? ''),
+            author: String(info.author ?? info.author_email ?? ''),
+            license: String(info.license_expression ?? info.license ?? ''),
+            homepage: pickHomepage(info),
+            repository: pickRepository(info),
+            requiresPython: String(info.requires_python ?? ''),
+            keywords: String(info.keywords ?? ''),
+            releases: releaseVersions.length,
+            firstReleased,
+            lastReleased,
+            url: String(info.package_url ?? `${PYPI_BASE}/project/${info.name}/`),
+        }];
+    },
+});

package/clis/pypi/utils.js

@@ -0,0 +1,55 @@
+// Shared helpers for the pypi adapters that hit the PyPI public JSON API
+// (pypi.org/pypi/<pkg>/json) and pypistats.org for download stats.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const PYPI_BASE = 'https://pypi.org';
+export const PYPISTATS_BASE = 'https://pypistats.org';
+const UA = 'opencli-pypi-adapter (+https://github.com/jackwener/opencli)';
+
+// PEP 508 / PEP 426 normalized name: letters, digits, "._-", with leading-letter rule relaxed by PyPI.
+const PKG_NAME = /^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+
+export function requirePackageName(value) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError('pypi package name is required (e.g. "requests", "pandas")');
+    if (!PKG_NAME.test(s)) {
+        throw new ArgumentError(
+            `pypi package name "${value}" is not a valid distribution name`,
+            'PyPI accepts ASCII letters / digits / "._-" with no leading or trailing separator.',
+        );
+    }
+    return s;
+}
+
+export async function pypiFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that pypi.org / pypistats.org are reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `PyPI returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'PyPI throttles unauthenticated bursts; wait a few seconds and retry.',
+        );
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}

package/clis/quark/mv.js

@@ -9,11 +9,11 @@ cli({
     domain: 'pan.quark.cn',
     strategy: Strategy.COOKIE,
     defaultFormat: 'json',
-    timeoutSeconds: 120,
     args: [
         { name: 'fids', required: true, positional: true, help: 'File IDs to move (comma-separated)' },
         { name: 'to', default: '', help: 'Destination folder path (required unless --to-fid is set)' },
         { name: 'to-fid', default: '', help: 'Destination folder ID (overrides --to)' },
+        { name: 'timeout', type: 'int', required: false, default: 120, help: 'Max seconds for the overall command (default: 120)' },
     ],
     func: async (page, kwargs) => {
         const to = kwargs.to;

package/clis/quark/save.js

@@ -21,7 +21,6 @@ cli({
     domain: 'pan.quark.cn',
     strategy: Strategy.COOKIE,
     defaultFormat: 'json',
-    timeoutSeconds: 120,
     args: [
         { name: 'url', required: true, positional: true, help: 'Quark share URL or pwd_id' },
         { name: 'to', default: '', help: 'Destination folder path' },
@@ -29,6 +28,7 @@ cli({
         { name: 'fids', default: '', help: 'File IDs to save (comma-separated, from share-tree). Omit to save all.' },
         { name: 'stoken', default: '', help: 'Share token (from share-tree output, required with --fids)' },
         { name: 'passcode', default: '', help: 'Share passcode (if required)' },
+        { name: 'timeout', type: 'int', required: false, default: 120, help: 'Max seconds for the overall command (default: 120)' },
     ],
     func: async (page, kwargs) => {
         const url = kwargs.url;

package/clis/qwen/ask.js

@@ -0,0 +1,85 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, TimeoutError } from '@jackwener/opencli/errors';
+import {
+    QIANWEN_DOMAIN,
+    QIANWEN_URL,
+    authRequired,
+    bubbleHtmlToMarkdown,
+    dismissLoginModal,
+    ensureOnQianwen,
+    getMessageBubbles,
+    hasLoginGate,
+    normalizeBooleanFlag,
+    sendMessage,
+    setFeatureToggle,
+    startNewChat,
+    waitForAnswer,
+} from './utils.js';
+
+cli({
+    site: 'qwen',
+    name: 'ask',
+    access: 'write',
+    description: 'Send a prompt to Qianwen and return the assistant reply',
+    domain: QIANWEN_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    navigateBefore: false,
+    defaultFormat: 'plain',
+    args: [
+        { name: 'prompt', required: true, positional: true, help: 'Prompt to send to Qianwen' },
+        { name: 'timeout', type: 'int', default: 120, help: 'Max seconds to wait for the response' },
+        { name: 'new', type: 'boolean', default: false, help: 'Start a new chat before sending' },
+        { name: 'think', type: 'boolean', default: false, help: 'Enable 深度思考 (DeepThink)' },
+        { name: 'research', type: 'boolean', default: false, help: 'Enable 深度研究 (DeepResearch)' },
+        { name: 'markdown', type: 'boolean', default: false, help: 'Emit assistant reply as markdown' },
+    ],
+    columns: ['Role', 'Text'],
+    func: async (page, kwargs) => {
+        const prompt = String(kwargs.prompt || '').trim();
+        if (!prompt) throw new ArgumentError('prompt is required');
+        const timeout = Number(kwargs.timeout ?? 120);
+        if (!Number.isInteger(timeout) || timeout <= 0) {
+            throw new ArgumentError('timeout must be a positive integer');
+        }
+        const startFresh = normalizeBooleanFlag(kwargs.new, false);
+        const useThink = normalizeBooleanFlag(kwargs.think, false);
+        const useResearch = normalizeBooleanFlag(kwargs.research, false);
+        const wantMarkdown = normalizeBooleanFlag(kwargs.markdown, false);
+
+        await ensureOnQianwen(page);
+        await dismissLoginModal(page);
+
+        if (startFresh) {
+            await startNewChat(page);
+            await dismissLoginModal(page);
+        }
+
+        if (useThink) await setFeatureToggle(page, 'think', true);
+        if (useResearch) await setFeatureToggle(page, 'research', true);
+
+        const send = await sendMessage(page, prompt);
+        if (!send?.ok) {
+            if (await hasLoginGate(page)) throw authRequired();
+            throw new CommandExecutionError(send?.reason || 'Failed to send Qianwen prompt');
+        }
+
+        const result = await waitForAnswer(page, prompt, timeout);
+        if (result.status === 'auth_required') throw authRequired();
+        if (result.status === 'timeout') {
+            throw new TimeoutError('qianwen ask', timeout, 'No Qianwen reply observed before timeout. Retry with --timeout increased.');
+        }
+        const assistant = result.assistant;
+        if (!assistant) {
+            throw new CommandExecutionError('No assistant reply found in Qianwen chat.');
+        }
+        const answer = wantMarkdown && assistant.html
+            ? (bubbleHtmlToMarkdown(assistant.html) || assistant.text)
+            : assistant.text;
+        return [
+            { Role: 'User', Text: prompt },
+            { Role: 'Assistant', Text: answer },
+        ];
+    },
+});