1688-cli 0.1.40 → 0.1.42

package/dist/session/supplier-search.js

@@ -0,0 +1,403 @@
+import { waitWithDeadline } from './wait.js';
+export const COMPANY_SEARCH_SERVICE = 'companySearchBusinessService';
+export function readSupplierSearchRequestMeta(url) {
+    if (!url.includes(COMPANY_SEARCH_SERVICE))
+        return null;
+    const parsed = new URL(url);
+    const beginPage = numberFromSearch(parsed.searchParams.get('beginPage'));
+    const pageSize = numberFromSearch(parsed.searchParams.get('pageSize'));
+    return {
+        ...(beginPage !== null ? { beginPage } : {}),
+        ...(pageSize !== null ? { pageSize } : {}),
+        ...(parsed.searchParams.get('keywords')
+            ? { keywords: parsed.searchParams.get('keywords') ?? undefined }
+            : {}),
+        ...(parsed.searchParams.get('pageName')
+            ? { pageName: parsed.searchParams.get('pageName') ?? undefined }
+            : {}),
+    };
+}
+export function parseSupplierItemsFromCompanySearchText(text) {
+    return parseCompanySearchServiceText(text).suppliers;
+}
+export function parseCompanySearchServiceText(text) {
+    const root = asRecord(parseJsonLike(text));
+    const topData = asRecord(root?.data);
+    const payload = asRecord(topData?.data);
+    const rawItems = asArray(payload?.companyWithOfferLists);
+    return {
+        suppliers: rawItems
+            .map(mapSupplierWrapper)
+            .filter((s) => s !== null),
+        pageCount: toNumber(payload?.pageCount),
+        docsReturn: toNumber(payload?.docsReturn),
+        code: toNumber(topData?.code),
+        message: toStringOrNull(topData?.msg),
+        requestId: toStringOrNull(root?.requestId),
+        pageName: toStringOrNull(root?.pageName),
+        rtTime: toNumber(root?.rtTime),
+    };
+}
+export function startSupplierSearchCapture(opts) {
+    const maxDiagnosticsEntries = 5;
+    const startedAt = new Date().toISOString();
+    let endedAt;
+    let disposed = false;
+    let pageClosed = false;
+    let finalStatus;
+    let timedOut = false;
+    let data = null;
+    let bestPayloadSize = 0;
+    let lastParsedAt = 0;
+    let seenCount = 0;
+    let matchedCount = 0;
+    let parsedCount = 0;
+    let lastSeenUrl;
+    let lastMatchedUrl;
+    let lastParsedUrl;
+    let lastError;
+    const failures = [];
+    const errorInfo = (error) => {
+        if (error instanceof Error) {
+            return { name: error.name, message: error.message };
+        }
+        return { message: String(error) };
+    };
+    const recordFailure = (url, error) => {
+        const info = errorInfo(error);
+        lastError = info;
+        failures.push({
+            at: new Date().toISOString(),
+            url,
+            ...info,
+        });
+        if (failures.length > maxDiagnosticsEntries)
+            failures.shift();
+    };
+    const diagnostics = () => ({
+        startedAt,
+        endedAt,
+        disposed,
+        finalStatus,
+        timedOut,
+        seenCount,
+        matchedCount,
+        parsedCount,
+        failureCount: failures.length,
+        lastSeenUrl,
+        lastMatchedUrl,
+        lastParsedUrl,
+        lastError,
+        failures: [...failures],
+    });
+    const onResponse = async (resp) => {
+        if (disposed)
+            return;
+        const url = resp.url();
+        seenCount++;
+        lastSeenUrl = url;
+        try {
+            const meta = readSupplierSearchRequestMeta(url);
+            if (!meta)
+                return;
+            const targetPage = opts.targetPage?.();
+            if (targetPage !== undefined && (meta.beginPage ?? 1) !== targetPage)
+                return;
+            matchedCount++;
+            lastMatchedUrl = url;
+            const text = await resp.text();
+            const parsed = parseCompanySearchServiceText(text);
+            if (parsed.suppliers.length === 0)
+                return;
+            const shouldReplace = !data ||
+                opts.keep !== 'largest' ||
+                parsed.suppliers.length > data.suppliers.length ||
+                (parsed.suppliers.length === data.suppliers.length &&
+                    text.length > bestPayloadSize);
+            if (shouldReplace) {
+                data = parsed;
+                bestPayloadSize = text.length;
+            }
+            parsedCount++;
+            lastParsedAt = Date.now();
+            lastParsedUrl = url;
+        }
+        catch (error) {
+            recordFailure(url, error);
+        }
+    };
+    const onClose = () => {
+        pageClosed = true;
+        finalStatus ??= 'browser_closed';
+        endedAt ??= new Date().toISOString();
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        endedAt ??= new Date().toISOString();
+        opts.page.off('response', onResponse);
+        opts.page.off('close', onClose);
+    };
+    const wait = async (optsWait) => {
+        const settleMs = optsWait.settleMs ?? 1200;
+        const result = await waitWithDeadline(async (state) => {
+            if (pageClosed || optsWait.isClosed?.())
+                return 'browser_closed';
+            if (data && state.now - lastParsedAt >= settleMs)
+                return 'captured';
+            if (await optsWait.isBlocked?.())
+                return 'blocked';
+            if (disposed)
+                return 'stream_closed';
+            return null;
+        }, {
+            timeoutMs: optsWait.timeoutMs,
+            intervalMs: optsWait.intervalMs ?? 300,
+            onTimeout: () => (data ? 'captured' : 'timeout'),
+        });
+        finalStatus = result;
+        timedOut = result === 'timeout';
+        endedAt ??= new Date().toISOString();
+        return { status: result, data, diagnostics: diagnostics() };
+    };
+    const waitForAction = async (action, optsWait) => {
+        try {
+            const actionResult = await action();
+            const result = await wait(optsWait);
+            return {
+                actionResult,
+                status: result.status,
+                data: result.data,
+                diagnostics: result.diagnostics,
+            };
+        }
+        finally {
+            dispose();
+        }
+    };
+    opts.page.on('response', onResponse);
+    opts.page.on('close', onClose);
+    return {
+        wait,
+        waitForAction,
+        dispose,
+        diagnostics,
+        data: () => data,
+    };
+}
+function mapSupplierWrapper(raw) {
+    const wrapper = asRecord(raw);
+    const company = asRecord(wrapper?.companyModel);
+    const brand = asRecord(wrapper?.companyBrandSiteVO);
+    if (!wrapper || !company)
+        return null;
+    const companyName = toStringOrNull(company.company) ??
+        toStringOrNull(brand?.companyName) ??
+        toStringOrNull(brand?.company) ??
+        '';
+    if (!companyName)
+        return null;
+    const enterpriseId = toStringOrNull(company.enterpriseId);
+    const memberId = normalizeMemberId(toStringOrNull(company.userId) ?? enterpriseId ?? toStringOrNull(wrapper.memberId));
+    const domainUri = toStringOrNull(company.domainUri);
+    const shopUrl = normalizeUrl(toStringOrNull(brand?.url)) ??
+        normalizeDomainUrl(domainUri);
+    const factoryTag = toStringOrNull(wrapper.factoryTag) ?? toStringOrNull(company.factoryTag);
+    const factoryLevel = toStringOrNull(company.factoryLevel);
+    const factoryLevelIsFactory = factoryLevel !== null && /工厂|厂/.test(factoryLevel);
+    const shiliFactory = toBool(wrapper.shiliFactory);
+    const superFactory = toBool(wrapper.superFactory);
+    const factoryInspection = toBool(wrapper.factoryInspection);
+    const isFactory = toBool(company.isFactory) ||
+        shiliFactory ||
+        superFactory ||
+        factoryInspection ||
+        factoryLevelIsFactory ||
+        !!factoryTag;
+    return {
+        companyName,
+        loginId: toStringOrNull(company.loginId),
+        memberId,
+        enterpriseId,
+        realUserId: toStringOrNull(company.realUserId),
+        companyId: toStringOrNull(company.id),
+        shopUrl,
+        factoryCardUrl: memberId
+            ? `https://sale.1688.com/factory/card.html?memberId=${encodeURIComponent(memberId)}`
+            : null,
+        domainUri,
+        location: {
+            province: toStringOrNull(company.province),
+            city: toStringOrNull(company.city),
+            address: toStringOrNull(company.address),
+            latitude: toNumber(company.latitude),
+            longitude: toNumber(company.longitude),
+        },
+        productionService: toStringOrNull(company.productionService),
+        businessMode: toStringOrNull(company.businessMode),
+        tp: {
+            memberLevel: toStringOrNull(company.memberLevel),
+            serviceYears: toNumber(company.tpServiceYear),
+            tpNum: toNumber(company.tpNum),
+        },
+        factory: {
+            isFactory,
+            factoryTag,
+            factoryLevel,
+            shiliFactory,
+            shiliCompany: toBool(wrapper.shiliCompany),
+            superFactory,
+            businessInspection: toBool(wrapper.businessInspection),
+            factoryInspection,
+            qiJianCompany: toBool(wrapper.qiJianCompany),
+            safePurchase: toBool(wrapper.safePurchase),
+            trust: toBool(wrapper.trust),
+        },
+        service: {
+            compositeScore: toNumber(company.compositeNewScore),
+            wwResponseRate: toNumber(company.wwResponseRate),
+            repeatRate: toNumber(company.repeatRate),
+            complianceRate: toNumber(company.complianceRate),
+        },
+        demand: {
+            payOrderCount3m: toNumber(company.payMordCnt3Month),
+            payAmount3m: toNumber(company.payOrdAmt3m),
+            fuzzyPayAmount3m: toStringOrNull(wrapper.fuzzyPayOrdAmt3m),
+            saleQuantity3m: toNumber(company.saleQuantity3Month),
+            memberBookedCount: toNumber(wrapper.memberBookedCount),
+        },
+        tags: uniqueStrings([
+            ...splitTags(toStringOrNull(company.memberTags)),
+            ...splitTags(toStringOrNull(company.productionService)),
+            factoryTag,
+            factoryLevel,
+            toStringOrNull(company.memberLevel),
+        ]),
+        offersPreview: asArray(wrapper.companyOffers)
+            .map(mapOfferPreview)
+            .filter((o) => o !== null),
+    };
+}
+function mapOfferPreview(raw) {
+    const offer = asRecord(raw);
+    if (!offer)
+        return null;
+    const title = cleanText(toStringOrNull(offer.subject) ?? '');
+    if (!title)
+        return null;
+    const url = normalizeUrl(toStringOrNull(offer.detailUrl));
+    const offerId = toStringOrNull(offer.offerId) ??
+        (url ? url.match(/\/offer\/(\d+)\.html/)?.[1] ?? null : null);
+    const priceValue = toNumber(offer.price);
+    return {
+        offerId,
+        title,
+        url,
+        price: {
+            text: priceValue !== null ? `¥${priceValue}` : toStringOrNull(offer.price),
+            value: priceValue,
+        },
+        unit: toStringOrNull(offer.unit),
+        image: normalizeUrl(toStringOrNull(offer.picUrl)),
+        bookedCount: toNumber(offer.bookedCount),
+        saleQuantity: toNumber(offer.saleQuantity),
+        quantitySumMonth: toNumber(offer.quantitySumMonth),
+        brief: cleanText(toStringOrNull(offer.brief) ?? '') || null,
+    };
+}
+function parseJsonLike(text) {
+    const trimmed = text.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/^[\w$.]+\((.*)\);?$/s);
+        if (!match?.[1])
+            throw new Error('Company search response is not JSON.');
+        return JSON.parse(match[1]);
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function toStringOrNull(value) {
+    if (typeof value === 'string') {
+        const trimmed = cleanText(value);
+        return trimmed || null;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return null;
+}
+function toNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'string')
+        return null;
+    const cleaned = value.replace(/,/g, '').trim();
+    if (!cleaned || cleaned === '-1')
+        return null;
+    const n = Number(cleaned);
+    return Number.isFinite(n) ? n : null;
+}
+function numberFromSearch(value) {
+    if (value === null)
+        return null;
+    return toNumber(value);
+}
+function toBool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value === 1;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        return ['true', '1', 'y', 'yes', '是'].includes(normalized);
+    }
+    return false;
+}
+function cleanText(value) {
+    return value.replace(/<\/?font[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+}
+function normalizeMemberId(value) {
+    if (!value)
+        return null;
+    if (value.startsWith('a-b2b-'))
+        return value.slice(2);
+    if (value.startsWith('b2b-'))
+        return value;
+    return null;
+}
+function normalizeDomainUrl(value) {
+    if (!value)
+        return null;
+    return normalizeUrl(value.includes('://') || value.startsWith('//') ? value : `https://${value}`);
+}
+function normalizeUrl(value) {
+    if (!value)
+        return null;
+    if (value.startsWith('//'))
+        return `https:${value}`;
+    if (/^https?:\/\//i.test(value))
+        return value;
+    return null;
+}
+function splitTags(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/[;；,，|]/)
+        .map((s) => s.trim())
+        .filter((s) => !!s && !/^\d+$/.test(s));
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((v) => !!v))];
+}
+//# sourceMappingURL=supplier-search.js.map

package/dist/session/supplier-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supplier-search.js","sourceRoot":"","sources":["../../src/session/supplier-search.ts"],"names":[],"mappings":"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"}

package/dist/util/encoding.js

@@ -0,0 +1,8 @@
+import iconv from 'iconv-lite';
+export function encodeGbkPercent(input) {
+    const gbkBytes = iconv.encode(input, 'gbk');
+    return Array.from(gbkBytes)
+        .map((b) => '%' + b.toString(16).padStart(2, '0').toUpperCase())
+        .join('');
+}
+//# sourceMappingURL=encoding.js.map

package/dist/util/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/util/encoding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,YAAY,CAAC;AAE/B,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;SAC/D,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/util/temp.js

@@ -0,0 +1,6 @@
+import os from 'node:os';
+import path from 'node:path';
+export function debugTmpPath(filename) {
+    return path.join(os.tmpdir(), filename);
+}
+//# sourceMappingURL=temp.js.map

package/dist/util/temp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp.js","sourceRoot":"","sources":["../../src/util/temp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC"}

package/docs/AGENT_MAPS_PLAN.md

@@ -0,0 +1,171 @@
+# Agent Maps Plan
+
+Date: 2026-05-28
+
+## Sources Reviewed
+
+- OpenAI: <https://openai.com/zh-Hans-CN/index/harness-engineering/>
+- Reference repo: `/Users/nobodyjack2050/code/go-backend`
+
+## OpenAI Article Takeaways
+
+The article's core lesson is that agent-first engineering needs maps and
+feedback loops more than huge instruction files. The useful pattern is:
+
+- Keep `AGENTS.md` short. It should be a table of contents and routing layer,
+  not a full manual.
+- Put durable knowledge in versioned repo files, especially `docs/`, because
+  knowledge outside the repo is invisible to agents.
+- Use progressive disclosure: start agents at a small map, then point them to
+  the precise product spec, playbook, architecture note, or generated index.
+- Make the app and repo readable to agents: logs, metrics, traces, screenshots,
+  DOM state, generated indexes, and reproducible commands should all be
+  queryable.
+- Encode taste and architecture as mechanical checks where possible. Guidance
+  that matters repeatedly should become lint, tests, generated docs checks, or
+  verification commands.
+- Treat plans as first-class repo artifacts for complex work so progress,
+  decisions, and blockers survive conversation loss.
+- Add recurring cleanup. As agent throughput rises, drift becomes normal unless
+  quality rules and doc-gardening are part of the system.
+
+## go-backend Agent Map Pattern
+
+`go-backend` implements this pattern with several concrete artifacts:
+
+- `AGENTS.md`: short "Agent Map" with first-read links, project shape, common
+  commands, task routing, hard rules, and done criteria.
+- `ARCHITECTURE.md`: system map with layer responsibilities, dependency rules,
+  major domains, generated code rules, and verification surfaces.
+- `docs/README.md`: documentation map and maintenance rules.
+- `docs/specs`, `docs/design-docs`, `docs/integrations`,
+  `docs/playbooks`, `docs/references`: durable context split by use.
+- `docs/exec-plans/active` and `docs/exec-plans/completed`: long-running
+  state for complex work.
+- `docs/generated/*`: generated repo indexes such as API, proto, DB schema,
+  package map, test index, and OpenAPI summary.
+- `scripts/generate_agent_context.sh`: builds generated indexes.
+- `make agent-context`, `make agent-verify`, `make eval-agent`: standard
+  commands for regenerating context and proving agent-readiness.
+- `docs/evals/graders/agent-map.sh`: deterministic check that the map exists
+  and points to verification/playbooks.
+- `docs/QUALITY_SCORE.md`: blunt scorecard for agent-readiness and known gaps.
+
+The important design choice is not the exact file names. It is the loop:
+small map -> routed docs -> generated indexes -> mechanical verification ->
+quality score -> cleanup.
+
+## Proposed Agent Maps For 1688-cli
+
+`1688-cli` should use a smaller version of the same system. This repo is a
+TypeScript CLI with browser automation, daemon IPC, JSON contracts, and real
+buyer write actions, so the map should emphasize command ownership, output
+shape stability, risk-control recovery, and approval boundaries.
+
+### Target Structure
+
+```text
+AGENTS.md
+ARCHITECTURE.md
+docs/
+  README.md
+  WORKFLOW.md
+  COMMANDS.md
+  JSON_CONTRACTS.md
+  SAFETY.md
+  RELIABILITY.md
+  QUALITY_SCORE.md
+  specs/
+    sourcing-research.md
+    seller-im.md
+    checkout-and-orders.md
+  playbooks/
+    add-command.md
+    change-json-output.md
+    debug-risk-control.md
+    add-mtop-capture.md
+    update-cli-release.md
+  generated/
+    command-index.md
+    module-map.md
+    test-index.md
+    json-shapes.md
+  exec-plans/
+    active/
+    completed/
+    tech-debt-tracker.md
+scripts/
+  generate_agent_context.mjs
+  check_agent_map.mjs
+```
+
+### `AGENTS.md` Target Role
+
+Keep only the short, high-signal contract:
+
+- First read: `ARCHITECTURE.md`, `docs/README.md`, `docs/SAFETY.md`,
+  `docs/COMMANDS.md`, and `docs/JSON_CONTRACTS.md`.
+- Project shape: `src/commands`, `src/session`, `src/daemon`, `src/io`,
+  `src/auth`, `src/util`.
+- Common commands: `pnpm build`, `pnpm test`, `pnpm typecheck`, future
+  `pnpm agent-context`, future `pnpm agent-verify`.
+- Task routing: new command, JSON shape change, browser/session flow,
+  daemon/protocol change, checkout/order safety, seller IM, release/update.
+- Hard rules: never place orders without prepare plus current-turn approval,
+  never silently retry login/risk-control loops, preserve JSON compatibility,
+  do not handwave browser verification failures.
+
+The current detailed CLI operation contract can move into `docs/COMMANDS.md`,
+`docs/JSON_CONTRACTS.md`, and `docs/SAFETY.md`.
+
+### Generated Context
+
+`scripts/generate_agent_context.mjs` should generate:
+
+- `docs/generated/command-index.md`: Commander commands/options from
+  `src/cli.ts`, mapped to `src/commands/*.ts`.
+- `docs/generated/module-map.md`: top-level source directories and file counts.
+- `docs/generated/test-index.md`: test files, if present, plus risk notes for
+  browser/session/integration-style tests.
+- `docs/generated/json-shapes.md`: exported result interfaces from command
+  modules, especially stable agent-facing payloads.
+
+This gives agents a fast way to understand the repo without reading every file.
+
+### Verification Gate
+
+Add scripts/Make targets roughly equivalent to:
+
+```bash
+pnpm agent-context   # generate docs/generated/*
+pnpm agent-verify    # typecheck, tests, generated docs freshness, agent map check
+pnpm eval-agent      # deterministic repo-specific graders, later
+```
+
+Initial `agent-verify` can stay modest:
+
+- `pnpm typecheck`
+- `pnpm test`
+- generate context and fail if `docs/generated/*` changes
+- check that `AGENTS.md`, `ARCHITECTURE.md`, `docs/README.md`, and core
+  playbooks exist
+
+### Rollout Order
+
+1. Add `docs/README.md`, `ARCHITECTURE.md`, `docs/COMMANDS.md`,
+   `docs/JSON_CONTRACTS.md`, `docs/SAFETY.md`, and `docs/WORKFLOW.md`.
+2. Move durable detail out of `AGENTS.md`, keeping `AGENTS.md` as a concise
+   routing map.
+3. Add `scripts/generate_agent_context.mjs` and generated indexes.
+4. Add `agent-context` and `agent-verify` package scripts.
+5. Add playbooks for the workflows that repeat most often.
+6. Add `QUALITY_SCORE.md` and update it whenever the map reveals a new gap.
+
+## Open Questions
+
+- Whether to preserve the current long `AGENTS.md` for external skill registry
+  compatibility, or split it while keeping a compact compatibility section.
+- Whether generated JSON-shape docs should parse TypeScript AST or start with a
+  simple regex-based extractor.
+- Whether browser/risk-control verification should be part of the default gate
+  or a separate live/manual gate.