publishport-opencli 1.8.4-pp.1

package/clis/grok/utils.test.js

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { __test__, isOnGrok, normalizeBooleanFlag, parseGrokSessionId, sendMessage } from './utils.js';
+
+describe('grok parseGrokSessionId', () => {
+    const id = '7c4197f2-10a1-4ebb-a84a-fea89f4f1d06';
+
+    it('returns a bare UUID unchanged', () => {
+        expect(parseGrokSessionId(id)).toBe(id);
+    });
+
+    it('lowercases an upper-case ID', () => {
+        expect(parseGrokSessionId(id.toUpperCase())).toBe(id);
+    });
+
+    it('extracts the session ID from a full grok.com chat URL', () => {
+        expect(parseGrokSessionId(`https://grok.com/c/${id}`)).toBe(id);
+        expect(parseGrokSessionId(`https://grok.com/c/${id}/`)).toBe(id);
+        expect(parseGrokSessionId(`https://grok.com/c/${id}?rid=abc`)).toBe(id);
+        expect(parseGrokSessionId(`https://x.grok.com/c/${id}`)).toBe(id);
+    });
+
+    it('throws ArgumentError on empty input', () => {
+        expect(() => parseGrokSessionId('')).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(null)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(undefined)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId('   ')).toThrow(ArgumentError);
+    });
+
+    it('throws ArgumentError on non-UUID input', () => {
+        expect(() => parseGrokSessionId('not-an-id')).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId('123')).toThrow(ArgumentError);
+        // 32 hex chars (no dashes) — not the Grok UUID shape
+        expect(() => parseGrokSessionId('7c4197f210a14ebba84afea89f4f1d06')).toThrow(ArgumentError);
+        // UUID-shaped but bad hex
+        expect(() => parseGrokSessionId('zc4197f2-10a1-4ebb-a84a-fea89f4f1d06')).toThrow(ArgumentError);
+        // Bare-ID mode must not accept URL/query suffixes.
+        expect(() => parseGrokSessionId(`${id}?next=abc`)).toThrow(ArgumentError);
+        // URL with the wrong path shape must not silently fall through.
+        expect(() => parseGrokSessionId('https://grok.com/somewhere/else')).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`http://grok.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://evil.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://fakegrok.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://grok.com.evil.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://evil.com/?next=https://grok.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://grok.com/c/${id}/extra`)).toThrow(ArgumentError);
+        // URL embedding extra hex tail after the UUID must not silently truncate
+        // and open the wrong conversation.
+        expect(() => parseGrokSessionId(`https://grok.com/c/${id}0`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://grok.com/c/${id}-extra`)).toThrow(ArgumentError);
+    });
+});
+
+describe('grok isOnGrok', () => {
+    const fakePage = (url) => ({
+        evaluate: () => url instanceof Error ? Promise.reject(url) : Promise.resolve(url),
+    });
+
+    it('returns true for grok.com URLs', async () => {
+        expect(await isOnGrok(fakePage('https://grok.com/'))).toBe(true);
+        expect(await isOnGrok(fakePage('https://grok.com/c/abc'))).toBe(true);
+    });
+
+    it('returns true for grok.com subdomains', async () => {
+        expect(await isOnGrok(fakePage('https://api.grok.com/v1'))).toBe(true);
+    });
+
+    it('returns false for non-grok domains and rejects substring matches', async () => {
+        expect(await isOnGrok(fakePage('https://fakegrok.com/'))).toBe(false);
+        expect(await isOnGrok(fakePage('https://example.com/?next=grok.com'))).toBe(false);
+        expect(await isOnGrok(fakePage('about:blank'))).toBe(false);
+    });
+
+    it('returns false when evaluate throws (detached tab)', async () => {
+        expect(await isOnGrok(fakePage(new Error('detached')))).toBe(false);
+    });
+});
+
+describe('grok normalizeBooleanFlag', () => {
+    it('passes through actual booleans', () => {
+        expect(normalizeBooleanFlag(true)).toBe(true);
+        expect(normalizeBooleanFlag(false)).toBe(false);
+    });
+
+    it('returns the fallback for null/empty input', () => {
+        expect(normalizeBooleanFlag(null)).toBe(false);
+        expect(normalizeBooleanFlag(undefined)).toBe(false);
+        expect(normalizeBooleanFlag('')).toBe(false);
+        expect(normalizeBooleanFlag(null, true)).toBe(true);
+    });
+
+    it('parses common truthy strings', () => {
+        for (const v of ['true', 'TRUE', '1', 'yes', 'on', ' Yes ']) {
+            expect(normalizeBooleanFlag(v)).toBe(true);
+        }
+    });
+
+    it('treats anything else as falsy', () => {
+        for (const v of ['no', 'off', '0', 'false', 'random']) {
+            expect(normalizeBooleanFlag(v)).toBe(false);
+        }
+    });
+});
+
+describe('grok getPinStateFromMenuLabels', () => {
+    it('detects pinned state from unpin labels without substring collisions', () => {
+        expect(__test__.getPinStateFromMenuLabels(['Open in new tab', 'Unpin', 'Delete'])).toBe('pinned');
+        expect(__test__.getPinStateFromMenuLabels(['打开新标签页', '取消置顶', '删除'])).toBe('pinned');
+    });
+
+    it('detects unpinned state from pin labels', () => {
+        expect(__test__.getPinStateFromMenuLabels(['Open in new tab', 'Pin', 'Delete'])).toBe('unpinned');
+        expect(__test__.getPinStateFromMenuLabels(['打开新标签页', '置顶', '删除'])).toBe('unpinned');
+    });
+
+    it('returns empty string when neither state label is visible', () => {
+        expect(__test__.getPinStateFromMenuLabels(['Open in new tab', 'Delete'])).toBe('');
+        expect(__test__.getPinStateFromMenuLabels([])).toBe('');
+    });
+});
+
+describe('grok sendMessage', () => {
+    it('requires a submitted user turn after both submit-button and Enter fallback paths', async () => {
+        let script = '';
+        const page = {
+            evaluate: async (value) => {
+                script = String(value);
+                return { ok: false, reason: 'test-capture' };
+            },
+        };
+
+        await sendMessage(page, 'hello from test');
+
+        expect(script).toContain('waitForSubmittedUserTurn');
+        expect(script).toContain('Grok submit button was clicked but no new user turn appeared.');
+        expect(script).toContain('Grok Enter-key fallback fired but no new user turn appeared.');
+        expect(script).toContain('[data-testid="user-message"]');
+        expect(script).toContain("submittedVia: 'submit-button'");
+        expect(script).toContain("submittedVia: 'enter-key'");
+    });
+});

package/clis/guazi/__fixtures__/detail.html

@@ -0,0 +1,7 @@
+<!doctype html><html><head>
+<meta property="og:title" content="【准新车】二手奔腾T90 2025款 龙耀版 1.5T 舒享型报价，真实车源图片/视频 - 瓜子二手车"/>
+</head><body><script>
+ess=image/quality,q_88/resize,m_fill,w_750,h_750\"}],\"type\":2}],\"videoList\":[],\"videoAbResult\":true,\"videoFeedsSwitch\":true,\"imageCropRatio1x1\":false},\"carRecordInfo\":{\"simpleSummary\":[{\"label\":\"首次上牌\",\"value\":\"2024-12\",\"fullRow\":false},{\"label\":\"表显里程\",\"value\":\"0.17万公里\",\"fullRow\":false},{\"label\":\"过户次数\",\"value\":\"0次\",\"fullRow\":false,\"bottomBall\":{\"title\":\"关于过户次数\",\"desc\":\"部分商家为周转车辆会临时过户至他人名下，建议通过视频看车功能直接与商家确认最新状态。\"}},{\"label\":\"车源地\",\"value\":\"苏州\",\"fullRow\":false}],\"carParamsSummary\":[{\"label\":\"发动机\",\"value\":\"1.5T\",\"fullRow\":false},{\"label\":\"变速箱\",\"value\":\"自动\",\"fullRow\":false},{\"key\":\"emission\",\"label\":\"排放标准\",\"value\":\"国六b\",\"fullRow\":false},{\"label\":\"驱动方式\",\"value\":\"前置前驱\",\"fullRow\":false}],\"archiveSummary\":[{\"key\":\"emission\",\"label\":\"排放标准\",\"value\":\"国六b\",\"fullRow\":false},{\"label\":\"车源地\",\"value\":\"苏州\",\"fullRow\":false},{\"label\":\"车身颜色\",\"value\":\"白色\",\"fullRow\":false},{\"label\":\"车源编号\",\"value\":\"162563585\",\"fullRow\":false}],\"highlightConfigItem\":[{\"id\":5,\"title\":\"方向盘加热\",\"image\":\"https://image1.guazistatic.com/qn2105181024035ead3ad6da599924f0d05a54e3f30885.png\",\"desc\":\"由方向盘内的加热系统实现，由方向盘或中控台上的按钮开启或关闭。属于较高的舒适型配置。\"},{\"id\":11,\"title\":\"自适应巡航\",\"image\":\"https://image1.guazistatic.com/qn2105181212480a405f49434fc91994a49bed6888e181.png\",\"desc\":\"Adaptive Cruise Control简称ACC，可依所设定速度行驶，还可保持预设跟车距离，随着车距变化自动加速与减速。\"},{\"id\":13,\"title\":\"自适应远近光\",\"image\":\"https://image1.guazistatic.com/qn210518121604812071c5c5251de8b33dcf01a5319478.png\",\"desc\":\"开启大灯时，行驶中传感器判断对向或同向车辆情况，自动切换远近光灯，有效保护其他车辆行车安全。\"},{\"id\":14,\"title\":\"并线辅
+s://m.guazi.com/car-detail/c162563585115789.html","price":73800,"priceCurrency":"CNY","priceValidUnt
+1年6个月，车况S，基础车况极品/理赔0次/过户0次，瓜子二手车，每车必检，超200项官方检测认证，
+</script></body></html>

package/clis/guazi/__fixtures__/list.html

@@ -0,0 +1,5 @@
+<!doctype html><html><body><div class="list">
+<a class="text-gz-black-303740" href="/car-detail/c168029452296957.html"><section class="mb-20 flex justify-between gap-12"><div class="overflow-hidden rounded-md w-114 h-85"><div class="rounded-md object-cover w-114 h-85" style="position:relative;overflow:hidden"><img alt="创维汽车 创维HT-i 2024款 1.5L PHEV 115KM 泰道版" loading="lazy" width="114" height="85" decoding="async" data-nimg="1" class="object-cover" style="color:transparent;position:absolute;width:100%;height:100%;top:0;left:0;opacity:0;transition:opacity 0.3s ease" src="https://image-public.guazistatic.com/qnbdp7206xf2022ab5473b42ad9bced3eb032b23b71780880135.jpg?x-bce-process=image/quality,q_88/resize,m_fill,w_280,h_210"/></div></div><div class="flex-1"><h4 class="line-height-1.5 line-clamp-2"><img alt="icon" loading="lazy" width="41" height="14" decoding="async" data-nimg="1" class="mr-5 inline-block h-14 w-41 -translate-y-1.5" style="color:transparent" src="https://image-public.guazistatic.com/qnbdp1066x2bcdce4af34c493db02eddd6babff42e1754566654.png"/>创维汽车 创维HT-i 2024款 1.5L PHEV 115KM 泰道版</h4><div class="flex h-20 flex-wrap gap-y-10 overflow-hidden whitespace-nowrap w-274 py-4"><span class="text-10 mr-3 flex h-14 items-center justify-center rounded-xs border border-solid px-3" data-text="已检测" style="color:#009B3F;border-color:#99D7B2">已检测</span><span class="text-10 mr-3 flex h-14 items-center justify-center rounded-xs border border-solid px-3" data-text="插电混动" style="color:#009B3F;border-color:#99D7B2">插电混动</span></div><p class="text-11 text-gz-gray-999 leading-11"><span>2025年</span><span>｜</span><span>0.64万公里</span><span>｜</span><span>北京</span></p><div class="flex justify-start pt-4 leading-12"><div class="flex items-end justify-start"><span class="text-gz-red-f22a18 font-din text-18 leading-12 font-bold">6.85</span><span class="text-gz-red-f22a18 text-12 mr-2">万</span></div><div class="flex flex-1 items-end justify-between"><span class="text-gz-glod-997147 text-12 ml-4">首付<!-- -->0.69万</span></div></div></div></section></a>
+<a class="text-gz-black-303740" href="/car-detail/c168569647231900.html"><section class="mb-20 flex justify-between gap-12"><div class="overflow-hidden rounded-md w-114 h-85"><div class="rounded-md object-cover w-114 h-85" style="position:relative;overflow:hidden"><img alt="雪佛兰 科帕奇 2014款 2.4L 四驱旗舰版 7座" loading="lazy" width="114" height="85" decoding="async" data-nimg="1" class="object-cover" style="color:transparent;position:absolute;width:100%;height:100%;top:0;left:0;opacity:0;transition:opacity 0.3s ease" src="https://image-public.guazistatic.com/qnbdp7206x97a811e2903f49e09bb878a57fdcbd0b1781747835.jpg?x-bce-process=image/quality,q_88/resize,m_fill,w_280,h_210"/></div></div><div class="flex-1"><h4 class="line-height-1.5 line-clamp-2"><img alt="icon" loading="lazy" width="41" height="14" decoding="async" data-nimg="1" class="mr-5 inline-block h-14 w-41 -translate-y-1.5" style="color:transparent" src="https://image-public.guazistatic.com/qnbdp1066x1ee05047385e452c90ad8ae7a264a0b51754566654.png"/>雪佛兰 科帕奇 2014款 2.4L 四驱旗舰版 7座</h4><div class="flex h-20 flex-wrap gap-y-10 overflow-hidden whitespace-nowrap w-274 py-4"><span class="text-10 mr-3 flex h-14 items-center justify-center rounded-xs border border-solid px-3" data-text="已检测" style="color:#009B3F;border-color:#99D7B2">已检测</span><span class="text-10 mr-3 flex h-14 items-center justify-center rounded-xs border border-solid px-3" data-text="顶配" style="color:#303741;border-color:#DFE0E2">顶配</span></div><p class="text-11 text-gz-gray-999 leading-11"><span>2015年</span><span>｜</span><span>18.27万公里</span><span>｜</span><span>北京</span></p><div class="flex justify-start pt-4 leading-12"><div class="flex items-end justify-start"><span class="text-gz-red-f22a18 font-din text-18 leading-12 font-bold">1.41</span><span class="text-gz-red-f22a18 text-12 mr-2">万</span></div><div class="flex flex-1 items-end justify-between"><span class="text-gz-glod-997147 text-12 ml-4">首付<!-- -->0.14万</span></div></div></div></section></a>
+<a class="text-gz-black-303740" href="/car-detail/c168109339309545.html"><section class="mb-20 flex justify-between gap-12"><div class="overflow-hidden rounded-md w-114 h-85"><div class="rounded-md object-cover w-114 h-85" style="position:relative;overflow:hidden"><img alt="吉利银河 银河A7 2026款 EV 550km 臻享版" loading="lazy" width="114" height="85" decoding="async" data-nimg="1" class="object-cover" style="color:transparent;position:absolute;width:100%;height:100%;top:0;left:0;opacity:0;transition:opacity 0.3s ease" src="https://image-public.guazistatic.com/qnbdp7206xfeffa252cc524361918effe5eca6e18b1780731400.jpg?x-bce-process=image/quality,q_88/resize,m_fill,w_280,h_210"/></div></div><div class="flex-1"><h4 class="line-height-1.5 line-clamp-2"><img alt="icon" loading="lazy" width="41" height="14" decoding="async" data-nimg="1" class="mr-5 inline-block h-14 w-41 -translate-y-1.5" style="color:transparent" src="https://image-public.guazistatic.com/qnbdp1066x2bcdce4af34c493db02eddd6babff42e1754566654.png"/>吉利银河 银河A7 2026款 EV 550km 臻享版</h4><div class="flex h-20 flex-wrap gap-y-10 overflow-hidden whitespace-nowrap w-274 py-4"><span class="text-10 mr-3 flex h-14 items-center justify-center rounded-xs border border-solid px-3" data-text="已检测" style="color:#009B3F;border-color:#99D7B2">已检测</span><span class="text-10 mr-3 flex h-14 items-center justify-center rounded-xs border border-solid px-3" data-text="纯电动" style="color:#009B3F;border-color:#99D7B2">纯电动</span></div><p class="text-11 text-gz-gray-999 leading-11"><span>2026年</span><span>｜</span><span>300公里</span><span>｜</span><span>北京</span></p><div class="flex justify-start pt-4 leading-12"><div class="flex items-end justify-start"><span class="text-gz-red-f22a18 font-din text-18 leading-12 font-bold">10.08</span><span class="text-gz-red-f22a18 text-12 mr-2">万</span></div><div class="flex flex-1 items-end justify-between"><span class="text-gz-glod-997147 text-12 ml-4">首付<!-- -->1.01万</span></div></div></div></section></a>
+</div></body></html>

package/clis/guazi/browse.js

@@ -0,0 +1,95 @@
+/**
+ * guazi browse — list used cars for sale in a city.
+ *
+ * Reads the mobile SSR list page `https://m.guazi.com/<city>/buy/`. Each
+ * listing is an `<a href="/car-detail/c<clueId>.html">` whose `<img alt>`
+ * holds the full title and whose visible text carries price / down-payment
+ * / mileage / year / city. Parsing is a pure HTML→rows function (no DOM,
+ * no network) so it runs identically in the unit test against a frozen page.
+ */
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    BROWSE_COLUMNS,
+    CommandExecutionError,
+    GUAZI_M_BASE,
+    clean,
+    guaziFetch,
+    requireStableId,
+    requireText,
+    requireLimit,
+    resolveCityCode,
+} from './utils.js';
+
+/** Energy types Guazi tags on a card. */
+const ENERGY = ['插电混动', '纯电动', '油电混动', '增程式', '汽油', '柴油'];
+
+/**
+ * Pure parser: list-page HTML → listing rows. Exported for unit testing.
+ */
+export function parseListings(html, limit) {
+    const anchors = String(html || '').match(/<a[^>]+href="\/car-detail\/c\d+\.html"[\s\S]*?<\/a>/g) || [];
+    const rows = [];
+    const seen = new Set();
+    for (const a of anchors) {
+        const idM = a.match(/car-detail\/c(\d+)\.html/);
+        if (!idM) continue;
+        const clueId = requireStableId(idM[1], `guazi listing row ${rows.length + 1}`);
+        if (seen.has(clueId)) continue;
+        seen.add(clueId);
+
+        const altM = a.match(/<img[^>]+alt="([^"]+)"/);
+        const title = requireText(altM && altM[1], `guazi listing ${clueId} title`);
+
+        const text = clean(a.replace(/<[^>]+>/g, ' '));
+        const priceM = text.match(/(\d+(?:\.\d+)?)\s*万\s*首付/);
+        const downM = text.match(/首付\s*(\d+(?:\.\d+)?)\s*万/);
+        const mileM = text.match(/(\d+(?:\.\d+)?万公里|\d+公里)/);
+        const yearM = text.match(/(\d{4})年/);
+        // city sits between the mileage and the price ("… ｜ 北京 6.85 万 首付 …")
+        const cityM = text.match(/[｜|]\s*([^｜|]{1,8}?)\s+\d+(?:\.\d+)?\s*万\s*首付/);
+        const energy = ENERGY.find((e) => text.includes(e)) || '';
+
+        rows.push({
+            rank: rows.length + 1,
+            clue_id: clueId,
+            title,
+            price: priceM ? `${priceM[1]}万` : '',
+            down_payment: downM ? `${downM[1]}万` : '',
+            mileage: mileM ? mileM[1] : '',
+            year: yearM ? yearM[1] : '',
+            city: cityM ? clean(cityM[1]) : energy,
+            url: `${GUAZI_M_BASE}/car-detail/c${clueId}.html`,
+        });
+        if (rows.length >= limit) break;
+    }
+    return rows;
+}
+
+cli({
+    site: 'guazi',
+    name: 'browse',
+    access: 'read',
+    aliases: ['list'],
+    description: '瓜子二手车在售车源列表（按城市，含售价/首付/里程/年份）',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'city', positional: true, help: '城市名（北京/上海/...）或瓜子城市码（bj/sh/...）。默认 bj 北京' },
+        { name: 'limit', type: 'int', default: 20, help: '返回的车源数量（最多 40，单页 SSR 上限）' },
+    ],
+    columns: BROWSE_COLUMNS,
+    func: async (args) => {
+        const code = resolveCityCode(args.city);
+        const limit = requireLimit(args.limit, 20, 40);
+        const html = await guaziFetch(`/${code}/buy/`, `browse ${code}`);
+        const rows = parseListings(html, limit);
+        if (rows.length === 0) {
+            throw new CommandExecutionError(
+                `guazi browse ${code}`,
+                'No SSR listing anchors found on a successful Guazi mobile page; the mobile layout may have changed.',
+            );
+        }
+        return rows;
+    },
+});

package/clis/guazi/car.js

@@ -0,0 +1,110 @@
+/**
+ * guazi car — detail of one used-car listing by its clue id.
+ *
+ * Reads the mobile SSR detail page `https://m.guazi.com/car-detail/c<id>.html`:
+ * the sale price (`"price":<fen-ish int>`), the spec/condition `label`/`value`
+ * pairs embedded in the RSC flight payload, and the condition summary. Returns
+ * a key/value sheet. Pure HTML→rows so it is unit-tested against a frozen page.
+ */
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    CAR_COLUMNS,
+    EmptyResultError,
+    GUAZI_M_BASE,
+    clean,
+    guaziFetch,
+    normalizeClueId,
+    requireText,
+} from './utils.js';
+
+/** Spec/condition labels worth surfacing, in display order. */
+const SPEC_LABELS = ['首次上牌', '表显里程', '过户次数', '车源地', '车身颜色', '发动机', '变速箱', '驱动方式', '排放标准', '车源编号'];
+
+/** Clean Guazi's SEO title down to the car name. */
+function cleanTitle(raw) {
+    let t = clean(raw);
+    t = t.replace(/^【[^】]*】/, '');      // drop a leading 【准新车】-style tag
+    t = t.replace(/^二手/, '');            // drop the 二手 prefix
+    t = t.replace(/报价[，,].*$/, '');     // drop "报价，真实车源…- 瓜子二手车"
+    t = t.replace(/\s*-\s*瓜子二手车.*$/, '');
+    return clean(t);
+}
+
+/**
+ * Pure parser: detail-page HTML → field/value rows. Exported for unit testing.
+ */
+export function parseCarDetail(html, clueId) {
+    const u = String(html || '').replace(/\\"/g, '"');
+
+    const titleM = u.match(/<meta[^>]+property="og:title"[^>]+content="([^"]+)"/)
+        || u.match(/"title":"([^"]{6,80})"/);
+    const rawTitle = titleM ? titleM[1] : '';
+    const tagM = clean(rawTitle).match(/^【([^】]+)】/);
+
+    const priceM = u.match(/"price":(\d{4,8})/);
+    const price = priceM ? `${(Number(priceM[1]) / 10000).toFixed(2)}万` : '';
+
+    // label/value pairs from the flight payload (deduped, first wins).
+    const labels = {};
+    for (const [, k, v] of u.matchAll(/"label":"([^"]{1,12})","value":"([^"]{1,40})"/g)) {
+        if (!(k in labels)) labels[k] = clean(v);
+    }
+
+    const condM = u.match(/基础车况[^,，"<]{0,16}/);
+
+    const fields = [
+        ['clue_id', String(clueId)],
+        ['title', rawTitle ? cleanTitle(rawTitle) : ''],
+        ['tag', tagM ? tagM[1] : ''],
+        ['price', price],
+        ['reg_date', labels['首次上牌'] || ''],
+        ['mileage', labels['表显里程'] || ''],
+        ['transfers', labels['过户次数'] || ''],
+        ['source_city', labels['车源地'] || ''],
+        ['color', labels['车身颜色'] || ''],
+        ['engine', labels['发动机'] || ''],
+        ['gearbox', labels['变速箱'] || ''],
+        ['drivetrain', labels['驱动方式'] || ''],
+        ['emission', labels['排放标准'] || ''],
+        ['condition', condM ? clean(condM[0]) : ''],
+        ['listing_no', labels['车源编号'] || ''],
+        ['url', `${GUAZI_M_BASE}/car-detail/c${clueId}.html`],
+    ];
+    return fields.map(([field, value]) => ({ field, value }));
+}
+
+/** Whether the parsed sheet actually found a car (vs. a 404/empty page). */
+function hasData(rows) {
+    const map = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+    return Boolean(map.title || map.price || map.reg_date);
+}
+
+cli({
+    site: 'guazi',
+    name: 'car',
+    access: 'read',
+    aliases: ['detail'],
+    description: '瓜子二手车车源详情（售价 / 上牌 / 里程 / 过户 / 配置 / 车况）',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'clue_id', required: true, positional: true, help: '车源 ID（来自 browse 的 clue_id，或 /car-detail/c<id>.html URL）' },
+    ],
+    columns: CAR_COLUMNS,
+    func: async (args) => {
+        const clueId = normalizeClueId(args.clue_id);
+        const html = await guaziFetch(`/car-detail/c${clueId}.html`, `car ${clueId}`);
+        const rows = parseCarDetail(html, clueId);
+        if (!hasData(rows)) {
+            throw new EmptyResultError(
+                `guazi car ${clueId}`,
+                'No listing detail found — the car may have been sold/removed, or the id is wrong.',
+            );
+        }
+        const map = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        requireText(map.title, `guazi car ${clueId} title`);
+        requireText(map.price, `guazi car ${clueId} price`);
+        return rows;
+    },
+});

package/clis/guazi/guazi.test.js

@@ -0,0 +1,126 @@
+/**
+ * Unit tests for the 瓜子二手车 (Guazi) adapter.
+ *
+ * Both commands parse mobile SSR HTML, so the pure parsers are exercised
+ * against frozen real-data fixtures captured from m.guazi.com. No network.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { getRegistry, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+
+import {
+    BROWSE_COLUMNS,
+    CAR_COLUMNS,
+    resolveCityCode,
+    normalizeClueId,
+    requireLimit,
+} from './utils.js';
+import { parseListings } from './browse.js';
+import { parseCarDetail } from './car.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LIST = readFileSync(join(__dirname, '__fixtures__/list.html'), 'utf8');
+const DETAIL = readFileSync(join(__dirname, '__fixtures__/detail.html'), 'utf8');
+
+describe('guazi adapter — registration', () => {
+    it('registers browse + car as PUBLIC (no browser)', () => {
+        for (const n of ['browse', 'car']) {
+            const cmd = getRegistry().get(`guazi/${n}`);
+            expect(cmd, n).toBeTruthy();
+            expect(cmd.strategy, n).toBe(Strategy.PUBLIC);
+            expect(cmd.browser, n).toBe(false);
+            expect(cmd.access, n).toBe('read');
+        }
+        expect(getRegistry().get('guazi/browse').columns).toEqual(BROWSE_COLUMNS);
+        expect(getRegistry().get('guazi/car').columns).toEqual(CAR_COLUMNS);
+    });
+});
+
+describe('guazi adapter — utils', () => {
+    it('resolveCityCode maps names, codes, and defaults to bj', () => {
+        expect(resolveCityCode('北京')).toBe('bj');
+        expect(resolveCityCode('shanghai')).toBe('sh');
+        expect(resolveCityCode('gz')).toBe('gz');
+        expect(resolveCityCode('')).toBe('bj');
+        expect(resolveCityCode(undefined)).toBe('bj');
+        expect(() => resolveCityCode('火星')).toThrow();
+    });
+    it('normalizeClueId accepts numbers and URLs', () => {
+        expect(normalizeClueId('162563585115789')).toBe('162563585115789');
+        expect(normalizeClueId('https://m.guazi.com/car-detail/c162563585115789.html')).toBe('162563585115789');
+        expect(() => normalizeClueId('abc')).toThrow();
+    });
+    it('requireLimit enforces [1,max]', () => {
+        expect(requireLimit(undefined, 20, 40)).toBe(20);
+        expect(() => requireLimit(41, 20, 40)).toThrow();
+    });
+});
+
+describe('guazi adapter — parsers against frozen fixtures', () => {
+    it('parseListings extracts listings with price/mileage/year', () => {
+        const rows = parseListings(LIST, 40);
+        expect(rows.length).toBe(3);
+        for (const r of rows) {
+            expect(Object.keys(r).sort()).toEqual([...BROWSE_COLUMNS].sort());
+            expect(r.clue_id).toMatch(/^\d+$/);
+            expect(r.title).toBeTruthy();
+            expect(r.url).toContain('/car-detail/c');
+        }
+        const first = rows[0];
+        expect(first.price).toMatch(/万$/);
+        expect(first.mileage).toMatch(/公里$/);
+        expect(first.year).toMatch(/^\d{4}$/);
+    });
+
+    it('parseListings respects the limit and dedupes', () => {
+        expect(parseListings(LIST, 2).length).toBe(2);
+        expect(parseListings('<html>nothing</html>', 40)).toEqual([]);
+    });
+
+    it('browse treats a successful page with no listing anchors as parser drift', async () => {
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = async () => ({
+            ok: true,
+            status: 200,
+            text: async () => '<html><title>瓜子二手车</title><main>new layout</main></html>',
+        });
+        try {
+            await expect(getRegistry().get('guazi/browse').func({ city: 'bj', limit: 20 }))
+                .rejects.toBeInstanceOf(CommandExecutionError);
+        } finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+
+    it('parseListings rejects malformed listing cards instead of silently dropping them', () => {
+        expect(() => parseListings('<a href="/car-detail/c123.html"><span>6.8 万 首付 1 万</span></a>', 40))
+            .toThrow(/stable text value/);
+    });
+
+    it('parseCarDetail builds a field/value sheet with price + specs', () => {
+        const rows = parseCarDetail(DETAIL, '162563585115789');
+        const map = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(rows.every((r) => Object.keys(r).sort().join() === 'field,value')).toBe(true);
+        expect(map.title).toBeTruthy();
+        expect(map.title).not.toContain('二手');
+        expect(map.title).not.toContain('报价');
+        expect(map.price).toMatch(/万$/);
+        expect(map.reg_date).toMatch(/^\d{4}-\d{2}$/);
+        expect(map.mileage).toMatch(/公里$/);
+        expect(map.engine).toBeTruthy();
+        expect(map.gearbox).toBeTruthy();
+        expect(map.condition).toContain('基础车况');
+        expect(map.url).toContain('/car-detail/c162563585115789.html');
+    });
+
+    it('parseCarDetail tolerates an empty page', () => {
+        const rows = parseCarDetail('<html></html>', '1');
+        const map = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(map.title).toBe('');
+        expect(map.price).toBe('');
+    });
+});

package/clis/guazi/utils.js

@@ -0,0 +1,133 @@
+/**
+ * Shared helpers for the 瓜子二手车 (Guazi) used-car adapter.
+ *
+ * The desktop www.guazi.com SPA renders an empty shell and loads listings
+ * from a signature-locked API (`mapi.guazi.com`, rejects unsigned requests
+ * with 签名验证失败). The MOBILE site `m.guazi.com`, however, server-side
+ * renders the full listing list and car detail into the HTML with no login,
+ * no signature, and no anti-bot challenge — so this adapter reads the mobile
+ * SSR HTML with an iPhone UA.
+ *
+ * Limitation: deep pagination and brand/keyword filtering route through the
+ * signed API, so `browse` returns the first SSR page (~40 fresh listings) for
+ * a city. That is surfaced honestly rather than faked.
+ */
+
+import {
+    ArgumentError,
+    AuthRequiredError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+export const GUAZI_M_BASE = 'https://m.guazi.com';
+
+const UA =
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 16_5 like Mac OS X) AppleWebKit/605.1.15 '
+    + '(KHTML, like Gecko) Version/16.5 Mobile/15E148 Safari/604.1';
+
+export const BROWSE_COLUMNS = ['rank', 'clue_id', 'title', 'price', 'down_payment', 'mileage', 'year', 'city', 'url'];
+export const CAR_COLUMNS = ['field', 'value'];
+
+/**
+ * Common city → Guazi city code (the path segment in m.guazi.com/<code>/buy/).
+ */
+export const CITY_CODE = {
+    beijing: 'bj', '北京': 'bj',
+    shanghai: 'sh', '上海': 'sh',
+    guangzhou: 'gz', '广州': 'gz',
+    shenzhen: 'sz', '深圳': 'sz',
+    hangzhou: 'hz', '杭州': 'hz',
+    chengdu: 'cd', '成都': 'cd',
+    chongqing: 'cq', '重庆': 'cq',
+    nanjing: 'nj', '南京': 'nj',
+    wuhan: 'wh', '武汉': 'wh',
+    tianjin: 'tj', '天津': 'tj',
+    xian: 'xa', '西安': 'xa',
+    suzhou: 'su', '苏州': 'su',
+    zhengzhou: 'zz', '郑州': 'zz',
+    changsha: 'cs', '长沙': 'cs',
+    qingdao: 'qd', '青岛': 'qd',
+    shenyang: 'sy', '沈阳': 'sy',
+    dalian: 'dl', '大连': 'dl',
+    jinan: 'jn', '济南': 'jn',
+    hefei: 'hf', '合肥': 'hf',
+    foshan: 'fs', '佛山': 'fs',
+};
+
+/** Resolve a city arg (name or code) to a Guazi city code; defaults to bj. */
+export function resolveCityCode(cityArg) {
+    if (cityArg == null || cityArg === '') return 'bj';
+    const raw = String(cityArg).trim().toLowerCase();
+    if (CITY_CODE[raw]) return CITY_CODE[raw];
+    if (CITY_CODE[String(cityArg).trim()]) return CITY_CODE[String(cityArg).trim()];
+    if (/^[a-z]{2,3}$/.test(raw)) return raw; // already a code
+    const names = Object.keys(CITY_CODE).filter((k) => /^[a-z]+$/.test(k)).join(', ');
+    throw new ArgumentError('city', `unknown city '${cityArg}'. pass a Guazi city code or one of: ${names}`);
+}
+
+/** Normalize a clue id: a bare number or a /car-detail/c<id>.htm(l) URL. */
+export function normalizeClueId(rawInput) {
+    const raw = String(rawInput || '').trim();
+    if (!raw) throw new ArgumentError('clue_id must be a non-empty value');
+    const m = raw.match(/car-detail\/c(\d+)/) || raw.match(/^c?(\d+)$/);
+    if (!m) {
+        throw new ArgumentError(`'${rawInput}' does not look like a guazi clue id (a number, or a /car-detail/c<id>.html URL)`);
+    }
+    return m[1];
+}
+
+export function requireLimit(value, def, max) {
+    const raw = value == null || value === '' ? def : value;
+    const n = typeof raw === 'number' ? raw : Number(String(raw).trim());
+    if (!Number.isInteger(n) || n < 1 || n > max) {
+        throw new ArgumentError(`limit must be an integer between 1 and ${max}`);
+    }
+    return n;
+}
+
+export function clean(s) {
+    return String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+}
+
+export function requireText(value, label) {
+    const text = clean(value);
+    if (!text) throw new CommandExecutionError(`${label} did not include a stable text value.`);
+    return text;
+}
+
+export function requireStableId(value, label) {
+    const id = String(value ?? '').trim();
+    if (!/^\d+$/.test(id)) throw new CommandExecutionError(`${label} did not include a stable numeric id.`);
+    return id;
+}
+
+/** Fetch a Guazi mobile page as HTML text, throwing typed errors. */
+export async function guaziFetch(path, contextHint) {
+    let resp;
+    try {
+        resp = await fetch(`${GUAZI_M_BASE}${path}`, {
+            headers: {
+                'User-Agent': UA,
+                Referer: `${GUAZI_M_BASE}/`,
+                'Accept-Language': 'zh-CN,zh;q=0.9',
+            },
+        });
+    } catch (err) {
+        throw new CommandExecutionError(`guazi ${contextHint} network error: ${err?.message || err}`);
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`guazi ${contextHint} HTTP ${resp.status}`);
+    }
+    const html = await resp.text();
+    // Guazi may eventually push the mobile pages behind their JS challenge.
+    if (/瑞数|reese84|captcha|滑动验证|verify\.guazi|安全验证/i.test(html) && !/car-detail\/c\d+/.test(html)) {
+        throw new AuthRequiredError(
+            'guazi.com',
+            `guazi ${contextHint} hit an anti-bot challenge — Guazi may have started gating the mobile site.`,
+        );
+    }
+    return html;
+}
+
+export { ArgumentError, CommandExecutionError, EmptyResultError };