1688-cli 0.1.40 → 0.1.42

package/docs/AGENT_WORKING_PRINCIPLES.md

@@ -0,0 +1,143 @@
+# Agent Working Principles
+
+These principles apply to all coding agents working in this repository. The
+first half is a reusable baseline shared with other agent-ready repositories;
+the second half adds `1688-cli`-specific rules for buyer safety, JSON
+contracts, and browser automation.
+
+Tradeoff: these guidelines bias toward caution over speed. For trivial tasks,
+use judgment.
+
+## 1. Think Before Coding
+
+Don't assume. Don't hide confusion. Surface tradeoffs.
+
+Before implementing:
+
+- State assumptions explicitly when they matter.
+- If multiple interpretations exist, present them instead of picking silently.
+- If a simpler approach exists, say so.
+- Push back when a request conflicts with safety, compatibility, or the repo's
+  existing architecture.
+- Ask only when the missing answer changes product behavior, account safety,
+  checkout/order behavior, data retention, or a breaking contract.
+
+## 2. Simplicity First
+
+Minimum code that solves the problem. Nothing speculative.
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No flexibility or configurability that was not requested.
+- No broad error handling that hides the real failure.
+- If the implementation is much larger than the problem, simplify it.
+
+Ask yourself: would a senior engineer say this is overcomplicated? If yes,
+rewrite it smaller.
+
+## 3. Surgical Changes
+
+Touch only what you must. Clean up only your own mess.
+
+When editing existing code:
+
+- Do not improve adjacent code, comments, or formatting unless needed.
+- Do not refactor unrelated behavior.
+- Match existing style, even if you would design it differently.
+- If you notice unrelated dead code or risk, mention it; do not delete it.
+
+When your changes create orphans:
+
+- Remove imports, variables, files, and functions that your changes made unused.
+- Do not remove pre-existing dead code unless asked.
+
+Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+Define success criteria. Loop until verified.
+
+Transform tasks into verifiable goals:
+
+- "Add validation" -> write invalid-input tests, then make them pass.
+- "Fix the bug" -> reproduce it or narrow it, then make the check pass.
+- "Refactor X" -> keep behavior stable and run the relevant gate.
+- "Add command" -> implement, document, update generated context, and verify.
+
+For multi-step tasks, use a brief plan:
+
+```text
+1. [Step] -> verify: [check]
+2. [Step] -> verify: [check]
+3. [Step] -> verify: [check]
+```
+
+Strong success criteria let agents loop independently. Weak criteria such as
+"make it work" require clarification or a conservative assumption.
+
+## 5. Read The Map First
+
+- Start with `AGENTS.md`, then load only the relevant deeper docs.
+- Use `ARCHITECTURE.md` to find the owning layer before changing code.
+- Use `docs/generated/*` for fast orientation instead of hand-building stale
+  inventories.
+- Do not rely on chat history for durable decisions; write important context
+  into docs or an ExecPlan.
+
+## 6. Work In Small Verified Slices
+
+- Prefer one bounded change that can be tested independently.
+- Run focused checks first, then the default gate when risk warrants it.
+- Use `pnpm agent-context` after command, JSON contract, source layout, or test
+  layout changes.
+- Use `pnpm agent-verify` as the default green gate before handoff.
+
+## 7. Preserve Buyer Safety
+
+- Treat 1688 as a real buyer account with real sellers, cart state, orders, and
+  session risk controls.
+- Never place an order without the prepare plus current-turn approval protocol.
+- Never send seller messages unless the user requested the specific send or
+  approved the exact message.
+- Do not force logout, force login reset, or global package upgrades without
+  explicit current-turn approval.
+- Login and slider/risk-control flows require the user; do not silently loop.
+
+## 8. Protect JSON Contracts
+
+- Agent-facing JSON is part of the product surface.
+- Prefer additive fields over renamed or removed fields.
+- Keep `--json`, `--get`, `--pick`, and watch-mode line-delimited JSON stable.
+- Update `docs/JSON_CONTRACTS.md` when output shape changes.
+- Add tests or fixtures when parser changes affect stable JSON.
+
+## 9. Make Failures Inspectable
+
+- Preserve `requestId`, `errorCode`, `pageState`, `verification`, and
+  `artifactDir` when browser/session flows fail.
+- Use `1688 debug list`, `1688 debug last`, and `1688 debug show <requestId>`
+  to inspect recent command events.
+- Do not hide failures by broad retry loops or vague error messages.
+- Record exact command and failure summary in ExecPlans or final responses when
+  verification cannot pass.
+- Distinguish system-level failure from item-level failure in batch workflows.
+
+## 10. Browser Automation Discipline
+
+- Prefer mtop/structured payload parsing over fragile DOM scraping.
+- Keep locator changes scoped and add fixture-backed tests where practical.
+- Use `--headed` as the manual escape hatch for slider verification.
+- Probe scripts are for discovery; stable behavior belongs in `src/`, `tests/`,
+  and docs.
+- Avoid aggressive bulk scraping patterns that increase WAF/risk-control
+  exposure.
+
+## 11. Documentation Discipline
+
+- Update command docs when command names, flags, examples, or behavior change.
+- Update safety docs when write actions or approval boundaries change.
+- Promote repeated debugging steps into playbooks.
+- Keep feature ideas in `docs/FEATURES.md` and long-running work in
+  `docs/exec-plans/`.
+- Keep `AGENTS.md` short; move durable detail into `docs/`.
+

package/docs/COMMANDS.md

@@ -0,0 +1,199 @@
+# Command Catalog
+
+Commands are organized by buyer journey: sourcing -> inquiry -> cart ->
+checkout -> tracking -> post-sale.
+
+## Sourcing
+
+```bash
+1688 search <keyword>             # keyword search; --max N to limit
+1688 search <keyword> --sort best-selling --price-max 50 --exclude-ads
+1688 search --headed              # open window if slider verification appears
+1688 research <keyword...>        # multi-keyword research, scoring, export
+1688 similar <offerId>            # find similar offers from other suppliers
+1688 image-search <pathOrUrl>     # local .jpg/.png/.webp or http(s) URL
+1688 offer <offerId>              # product detail, SKUs, price tiers, package info
+1688 compare <offerId...>         # compare offer details for sourcing
+1688 supplier inspect <target>    # supplier/factory trust signals from offerId or b2b-* memberId
+1688 supplier search <keyword...> # supplier discovery from 1688 company search
+1688 supplier research <keyword...> # supplier scoring + inspect enrichment from company search
+```
+
+Research-oriented `search` filters:
+
+```bash
+--sort relevance|best-selling|price-asc|price-desc
+--price-min <n>
+--price-max <n>
+--province <name>
+--city <name>
+--verified any|factory|business|super-factory
+--min-turnover <n>
+--exclude-ads
+```
+
+`research` adds:
+
+```bash
+--max-per-query <n>
+--enrich top:N|N|0|none
+--jsonl
+--csv
+--output <file>
+```
+
+Supplier company-search commands:
+
+```bash
+1688 supplier search 键盘 --factory-only --json
+1688 supplier research 键盘 --enrich top:10 --csv
+```
+
+`supplier search` and `supplier research` use 1688's company search source
+(`companySearchBusinessService`). They do not aggregate suppliers from offer
+search results. Shared flags:
+
+```bash
+--max <n>
+--factory-only
+--province <name>
+--city <name>
+--min-years <n>
+--min-repeat-rate <n>     # accepts 0.4 or 40
+--min-response-rate <n>   # accepts 0.6 or 60
+--enrich top:N|N|all|0|none
+--jsonl
+--csv
+--output <file>
+```
+
+`supplier search` defaults to `--enrich 0`. `supplier research` defaults to
+`--enrich top:10`.
+
+## Pre-Sale Inquiry
+
+```bash
+1688 seller inquire <offerId> <message>
+1688 seller messages --offer <offerId>
+1688 seller messages --offer <offerId> --watch [--interval N]
+```
+
+`--watch` is long-running and emits one line of JSON per newly-arrived message
+when stdout is piped. Default interval is 30 seconds, minimum is 10 seconds.
+
+## Cart
+
+```bash
+1688 cart list
+1688 cart add <offerId> --sku <skuId> --qty N
+1688 cart remove <cartId>
+```
+
+`cart add` returns `{added, isNewRow, addedQuantity}` so pipelines can pick up
+the cart row reliably.
+
+## Checkout
+
+```bash
+1688 checkout prepare <cartId>...
+1688 checkout confirm <cartId>...
+1688 checkout confirm <cartId>... --agent
+```
+
+`prepare` is read-only. `confirm` places a real order and must follow the
+approval protocol in `docs/SAFETY.md`.
+
+## Order Tracking
+
+```bash
+1688 order list
+1688 order list --status waitsellersend
+1688 order list --status waitbuyerreceive
+1688 order get <orderId>
+1688 order logistics <orderId>
+1688 shipped <orderId>
+1688 stuck [--days N]
+1688 fake-shipped [--days N] [--debug]
+1688 seller-history <sellerName>
+```
+
+Status filters:
+
+| Value | Meaning |
+|---|---|
+| `all` | All orders |
+| `waitbuyerpay` | Pending payment |
+| `waitsellersend` | Paid, seller has not shipped |
+| `waitbuyerreceive` | Shipped, awaiting delivery |
+| `success` | Completed |
+| `cancel` | Canceled |
+
+## Post-Sale Chat
+
+```bash
+1688 seller chat <orderId|loginId> <message>
+1688 seller chat <orderId> <message> --no-card
+1688 seller messages <orderId>
+1688 seller messages <orderId> --watch
+```
+
+With an `orderId`, chat auto-attaches the order card unless `--no-card` is
+given.
+
+## Account And Daemon
+
+```bash
+1688 login
+1688 login --headed
+1688 login --force
+1688 logout [--yes]
+1688 whoami [--verify]
+1688 doctor [--no-launch]
+1688 daemon start | stop | status | reload
+1688 serve
+```
+
+## Output Flags
+
+Every command supports:
+
+```bash
+--json            # force JSON output even in a TTY
+--pretty          # indent JSON by 2 spaces
+--get <path>      # print one field by dot-path
+--pick <paths>    # comma-separated dot-paths as a JSON object
+```
+
+Examples:
+
+```bash
+1688 offer X --get supplier.name
+1688 offer X --get supplier
+1688 offer X --get 'skus[*].price'
+1688 offer X --pick price,supplier.name
+1688 offer X --json --pretty
+1688 research 手机壳 数据线 --jsonl
+1688 research 手机壳 --csv --output research.csv
+1688 compare 123 456 --csv
+1688 supplier inspect 628196518518 --json --pretty
+1688 supplier search 键盘 --json --pretty
+1688 supplier research 键盘 --csv --output suppliers.csv
+```
+
+## Agent-Friendly Pipelines
+
+```bash
+1688 search 雨伞 | jq '.offers[0:5]'
+1688 order list --status waitsellersend | jq '.orders[] | {id: .orderId, paid: .paidAt}'
+id=$(1688 cart add <offerId> --sku <skuId> --qty 1 | jq -r '.added.cartId')
+```
+
+PowerShell without `jq`:
+
+```powershell
+1688 offer <offerId> --get supplier.name
+1688 supplier search 键盘 --pick total,source.kind,'items[0].supplier.companyName'
+$added = 1688 cart add <offerId> --sku <skuId> --qty 1 --json | ConvertFrom-Json
+1688 cart remove $added.added.cartId
+1688 supplier research 键盘 --csv --output "$env:TEMP\suppliers.csv"
+```

package/docs/FEATURES.md

@@ -0,0 +1,45 @@
+# Feature Backlog
+
+This file records product ideas that should survive chat context loss. Status
+is intentionally lightweight: `Idea`, `Planned`, `Active`, or `Done`.
+
+Last updated: 2026-06-04
+
+## Sourcing Research
+
+| Feature | Status | Notes |
+|---|---|---|
+| `1688 search --sort` | Done | Added `relevance`, `best-selling`, `price-asc`, and `price-desc`; local deterministic sorting is the contract, with remote sort hints where known. |
+| Search filters | Done | Added price range, province/city, verified supplier, minimum turnover/order count, and optional ad exclusion. |
+| `1688 research <keyword...>` | Done | Multi-keyword research records `sourceKeyword`, rank, demand signals, supplier trust signals, score, JSON/JSONL/CSV output. |
+| Top-N enrichment | Done | `research --enrich top:N` enriches only top N results through `offer` detail extraction. |
+| Supplier quality fields | Planned | Basic service tags, product badges, demand, and verification fields are additive; deeper trade-service scores still need reliable payload mapping. |
+| `1688 supplier inspect` | Done | Inspect supplier/factory trust signals from offerId or `b2b-*` memberId. loginId-only lookup is intentionally rejected until a deterministic resolver exists. |
+| `1688 supplier search` | Done | Supplier discovery now comes from 1688 company search (`companySearchBusinessService`) with GBK keyword encoding, not offer-result aggregation. |
+| `1688 supplier research` | Done | Scores company-search suppliers and optionally enriches top N via `supplier inspect`; supports JSONL/CSV export. |
+| `1688 compare <offerId...>` | Done | Compares price tiers, MOQ, sales signals, supplier identity, SKU depth, stock, freight/package hints, and score. |
+| Export formats | Done | Added `--jsonl` and `--csv` for research datasets while keeping normal command JSON stable for agents. |
+| Sourcing score | Done | Computed, explainable V1 score from price, demand, supplier tenure, verification, tags, and ad status. |
+
+## Agent Maps
+
+| Feature | Status | Notes |
+|---|---|---|
+| Short agent entrypoint | Done | `AGENTS.md` is now a concise routing map; durable detail moved into `docs/`. |
+| Documentation map | Done | `docs/README.md` now maps commands, JSON contracts, safety, reliability, workflow, specs, playbooks, exec plans, and generated indexes. |
+| Architecture map | Done | `ARCHITECTURE.md` describes CLI layers, command ownership, session/daemon boundaries, and verification surfaces. |
+| Specs directory | Done | Domain specs live under `docs/specs/` instead of `docs/product-specs/`. |
+| Playbooks | Done | Added playbooks for adding commands, changing JSON output, debugging risk control, adding mtop capture, and release/update work. |
+| Generated context | Done | `scripts/generate_agent_context.mjs` generates command, module, test, and JSON-shape indexes under `docs/generated/`. |
+| Agent verification gate | Done | Added `pnpm agent-context`, `pnpm docs-check`, `pnpm agent-map-check`, `pnpm test:unit`, and `pnpm agent-verify`. |
+| Agent map grader | Done | `scripts/check_agent_map.mjs` checks required docs, generated indexes, package scripts, and short-map constraints. |
+| Quality score | Done | `docs/QUALITY_SCORE.md` tracks agent-readiness, known gaps, and latest verification. |
+| Live doctor gate split | Planned | Full `pnpm test` still includes `tests/doctor-live.test.ts`; consider adding explicit `pnpm test:live` and making `pnpm test` deterministic or clearly documented. |
+| JSON schema/snapshot tests | Idea | Add tests that lock stable agent-facing JSON contracts beyond the heuristic `docs/generated/json-shapes.md` index. |
+| AST-based JSON shape index | Idea | Replace the current regex/heuristic interface extractor with TypeScript AST parsing when shape extraction needs more precision. |
+
+## Platform Compatibility
+
+| Feature | Status | Notes |
+|---|---|---|
+| Windows CLI compatibility baseline | Done | Implemented cross-platform build, root-hashed Windows named-pipe daemon isolation, platform-aware doctor/postinstall hints, `os.tmpdir()` debug paths, PowerShell docs, and deterministic tests. Verified with focused tests, `pnpm build`, `pnpm test:unit`, `pnpm agent-verify`, and `npm pack --dry-run`; manual Windows smoke checklist remains documented in the spec. |