@itpay/cli 2.0.40 → 2.1.1

package/docs/cli-reference/index.md

@@ -2,7 +2,7 @@
 
 本目录是 ItPay CLI 的规范性命令合同。它定义命令应向人和 Agent 返回什么、如何指导下一步，以及失败后如何恢复。当前实现与本文档不一致时，以本文档作为后续校准目标。
 
-> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。当前入口同时覆盖购买新服务、查询订单、查看经用户授权的已购内容和退款；Seller 流程未来仍使用同一入口，当前尚未实现。不得为这些意图拆分新的产品入口。
+> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。当前入口同时覆盖购买新服务、查询订单、查看经用户授权的已购内容和退款；Seller 流程使用同一入口的 `itpay sell` 命令。不得为这些意图拆分新的产品入口。
 
 企知道可以作为示例数据出现，但任何命令、字段、状态和 instruction 都不得依赖某个服务。服务差异只能来自 Catalog、Service Contract、Capability metadata 和服务端状态。
 
@@ -34,6 +34,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay catalog list`](commands/catalog/list.md)
 - [`itpay install`](commands/install.md) - 查看指定 Agent 的安装说明
 - [`itpay skill show`](commands/skill.md) - 一次读取完整内置 ItPay Skill
+- [`itpay auth login / status`](commands/auth.md) - 官方登录并绑定当前已登记 Agent，继续免费查询
 - [`itpay device recover`](commands/device.md) - 仅恢复运营已确认重建的 Backend registration
 - [`itpay docs`](commands/docs/index.md)
   - [`itpay docs list`](commands/docs/list.md)
@@ -89,3 +90,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay services next`](commands/services/next.md)
   - [`itpay services read-result`](commands/services/read-result.md)
   - [`itpay services events`](commands/services/events.md)
+
+- [Sell: create, test and submit services](commands/sell.md)
+
+- [Run a published service](commands/services/run.md)

package/docs/sell.md

@@ -0,0 +1,56 @@
+# Sell Agent guide
+
+`itpay sell` is the Seller command namespace. Buyer `services` commands remain separate. Read `itpay sell guide --json` first, authenticate with `itpay sell auth login` and complete the standard ItPay browser login, then run `itpay sell auth status`, then use `sell status` to select the user's existing merchant. An unverified merchant must finish KYB and payout setup in the dashboard.
+
+## Local-first workflow
+
+1. `sell init --project <directory> --service-id <id> --name <name>` creates a local project. `sell config --file <json>` sets price, policy and explicit test fixtures. Never invent prices or required API inputs.
+2. `sell library search/get` reads platform sources. `sell sources add --file <OpenAPI> --provider-key <key>` compiles local contracts with the platform importer. `sell workflow import --file <workflow.yaml>` preserves the submitted workflow and reports unsupported semantics. Read `sell workflow catalog` for supported node configuration.
+3. Generate or modify `workflow.yaml` in the user's Agent using the exact source contracts. Bind `providerOperationVersionId`, credential profile and input/output mappings explicitly. The first workflow ID must equal the service ID. Missing mappings, incompatible schema, unsupported content types or unsupported workflow semantics block execution. Do not remove unknown fields to conceal a compatibility error.
+4. `sell credentials bind --profile <id> --file <bindings.json>` accepts field-to-environment-variable mappings, never secret values. `sell credentials upload` uploads those environment values directly to the authenticated merchant after approval; values must not appear in chat, workflow files or generated docs. Platform-managed secrets cannot be downloaded.
+5. `sell workflow validate`, then `sell workflow versions save --name <name>`. Runs never create saved versions. `sell test run --confirm` performs actual Provider calls on this machine, with simulated payment/refund/delivery gates. `sell test get --run <id>` reads results. `sell test resume` never blindly replays an unknown request.
+6. `sell workflow preview` serves the existing Builder on loopback only. Review its exact YAML, price and version; then use `sell workflow confirm --confirm` only after user agreement.
+7. `sell push --merchant-id <id> --bindings <profile-map.json> --confirm` uploads the confirmed package. Profile map values are platform profile IDs, not secrets. Optimistic revisions prevent overwriting another editor. An ambiguous write requires explicit pull/reconciliation, never guessed retries.
+8. Inspect platform-imported operations and perform any required `sell sources probe` with explicit test inputs. Follow the backend Guide and the upload's returned version/revision fields to run `sell verify`. Disclose and confirm API side effects, including the exact risk hash if the platform returns an additional confirmation barrier.
+9. `sell submission preview` returns the workflow, price, policy and current agreements. After user approval, `sell submission submit` sends the exact revision, terms version and required confirmations. This requests review; it does not publish or approve.
+10. Use `sell submission get` and `sell services list/get` to follow the actual outcome. Rejected/withdrawn/taken-down services can be edited and resubmitted through the same process. Once published, verify with buyer `catalog list`.
+
+All platform operations accept `--input-json <file>` for their declared fields and `--merchant-id`/`--draft-id` where appropriate. Run each command's `--help`; do not invent options. `sell guide --merchant-id <id> --input-json <file>` with `{"draft_id":"..."}` returns server-derived next actions.
+
+## MCP
+
+`itpay sell mcp --stdio --project <directory>` exposes local creation, import, versioning, testing, preview, sync and platform actions. It reuses the local CLI identity. Remote MCP exposes only platform actions and cannot read paths on the user's machine. Use the local server for real local tests and file access. New remote grants require the appropriate `itpay.seller.read/write/test/submit` scopes; old buyer grants do not gain Seller authority.
+
+## Invariants
+
+- Current public runtime is synchronous, acyclic, single entry, per-call pricing, one payment node, and delivery on success. Quota, prepaid consumption and async workflows are not publishable.
+- Local reports are diagnostics, not platform approval evidence. Platform verification is required; existing valid evidence may be reused. Admin approval never repeats Provider calls.
+- Every visual view reads the same YAML. Layout is presentation only.
+- Disclosure/confirmation binds the version being acted on. Do not turn `--confirm` into blanket permission for later changes.
+- Never approve real submissions or perform real payments in automated development tests.
+
+## Local recovery and packaging
+
+The local `.itpay-sell` directory contains private fixtures, reports and the encrypted run journal's local key. Exclude it from Git and shared artifacts. A terminated process may leave `runner.lock`; inspect the journal and ensure no runner is active before manual recovery. A request with an unknown outcome is never automatically replayed.
+
+Local reports never substitute for the platform verification gate. Repeated upload of an unchanged saved version reuses its cloud version; a changed cloud revision or fixture revision requires explicit pull/review.
+
+For repository builds, run `scripts/v3/build-sell-runtime.sh`, build `apps/web/vite.sell-preview.config.ts`, and then build/package `apps/cli`. Packaging rejects missing native binaries or preview assets. `scripts/v3/sync-sell-contract.mjs --check` verifies that the CLI command contracts match the backend/MCP package.
+
+Example local MCP configuration (use the existing authenticated CLI account):
+
+```json
+{
+  "mcpServers": {
+    "itpay-sell": {
+      "command": "itpay",
+      "args": ["sell", "mcp", "--stdio", "--project", "/absolute/path/to/service"],
+      "env": {"ITPAY_BACKEND_URL": "https://sandbox.itpay.ai"}
+    }
+  }
+}
+```
+
+## Seller login and dev
+
+Use `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth login --json` to receive the normal ItPay authorization link. After browser login and required email verification, run `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth status --json`. The CLI claims its own account session through the standard API and stores it in an owner-only file; never copy tokens or browser cookies. `itpay sell auth logout --json` revokes this session. Keep the same backend prefix on subsequent commands; production, dev, and sandbox state are isolated. Agent device enrollment does not grant Seller organization access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.40",
+  "version": "2.1.1",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "docs/",
     "skills/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "assets/"
   ],
   "publishConfig": {
     "access": "public"
@@ -40,8 +41,10 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
-    "qrcode": "^1.5.4"
+    "qrcode": "^1.5.4",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.7.5",
@@ -59,11 +62,12 @@
     "check": "npm run lint && npm run test:coverage && npm run test:package",
     "pack:dry-run": "npm run clean && npm run build && npm pack --dry-run --ignore-scripts",
     "prepare": "node scripts/install-git-hooks.mjs",
-    "test:package": "npm run clean && npm run build && node scripts/package-smoke.mjs",
-    "prepack": "npm run clean && npm run build",
+    "test:package": "node scripts/check-sell-package.mjs && npm run clean && npm run build && node scripts/package-smoke.mjs",
+    "prepack": "node scripts/check-sell-package.mjs && npm run clean && npm run build",
     "prepublishOnly": "npm run check",
     "test": "tsx --test tests/*.test.ts",
     "test:coverage": "c8 --all --src src --extension .ts --exclude=src/client/types.ts --exclude=tests/** --exclude=scripts/** --reporter=text --reporter=lcov --check-coverage --lines 85 --statements 85 --functions 90 --branches 70 npm test",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "precheck": "node scripts/fetch-sell-runtime.mjs"
   }
 }

package/skills/itpay/SKILL.md

@@ -3,8 +3,8 @@ name: itpay
 description: >
   Use ItPay when a human wants to discover or buy a service, view something
   they previously purchased, inspect order or delivery history, or request
-  and track a refund, or rate a purchased service. Seller workflows are not
-  yet available.
+  and track a refund, rate a purchased service, or create, test and submit
+  a Seller service using itpay sell.
 ---
 
 # ItPay
@@ -17,6 +17,7 @@ for the human; never ask them to run commands or learn internal concepts.
 
 | Human intent | First action |
 | --- | --- |
+| Create, sell or publish a service | `itpay sell guide --json`, then `itpay sell status --json` |
 | Discover services or make a new query | `itpay catalog list --json` |
 | View previously purchased content | `itpay vault list --json` |
 | Find a previous result by subject | `itpay vault list --query <subject> --json` |
@@ -106,3 +107,9 @@ a QR code.
   without the corresponding ItPay state.
 - Never infer a rating or upload chat, prompts, raw logs, contact details,
   purchased content, credentials, or internal identifiers as feedback.
+
+## Sell a Service
+
+Use only the `itpay sell` namespace for Seller work. Read its Guide and the packaged `docs/sell.md`. Authenticate with the existing account/device flow; do not create a second merchant. The user's Agent may generate the workflow only from locked API contracts and the exact supported node catalog. Required parameters, Content-Type, method and credentials are not creative choices.
+
+Use local MCP (`itpay sell mcp --stdio --project <directory>`) or the CLI for local files and real local tests. Show the existing Builder when helpful. Ask for explicit confirmation after showing the exact workflow/version, Provider side effects or submission agreements. Never pass secrets through chat or workflow files. Local success does not satisfy platform verification, and submission does not mean approval or publication. Follow the server Guide and keep buyer commands separate.