1688-cli 0.1.41 → 0.1.42

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.

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. |