@itpay/cli 2.1.47 → 2.1.49

package/docs/agent/buyer/rail-booking.json

@@ -4,68 +4,25 @@
   "product_scope": "itpay is the single public Buyer CLI entry point, and $itpay is its user-facing Skill invocation. It covers services, railway planning and booking, orders, authorized purchased content and refunds.",
   "topic": "rail-booking",
   "title": "Railway Query, Planning, and Ticket Booking",
-  "purpose": "One railway route from understanding the request to saved results, booking, protected checkout, order status and refunds.",
+  "purpose": "Understand the route, query current railway facts, choose one complete plan and prepare its official purchase page.",
   "when_to_use": [
     "Any railway schedule, planning or ticket request; read this topic once before the first railway action."
   ],
-  "goal_and_overview": {
-    "route": "Understand endpoints and constraints → 2–4 line route brief → Exact or Smart → read enough saved results for the goal → select under delegation → missing real consent only → official payment entry; show and stop.",
-    "query_vs_booking": "Exact/Smart returns a query execution and saved evidence. Booking creates a separate execution from a server-issued selection; it is not a repeated search.",
-    "comparison": "If the human only asked to compare, answer within the searched scope and stop without a buy-or-not question. Reuse already-read unchanged Skill/docs in this context; do not repeat install/readyz/docs at each step. A clear purchase delegation permits selection under their rules, subject to required human terms.",
-    "public_entry": "One public service itpay-rail declares query_exact, query_smart and prepare_purchase. Query, booking, Checkout and order remain separate identities. Legacy IDs are only for recovering their pinned historical executions.",
-    "price_approval": "Choosing a candidate or confirming seat/whole-journey terms is not approving price. Read the current scoped approve_purchase template after quote; record true only for genuine matching exact-price or capped-budget approval, or an explicitly authorized official-page confirmation. Reuse matching approval; never fabricate it."
-  },
-  "flow_at_a_glance": [
-    {
-      "step": "search Exact",
-      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
-      "returns": "one station-pair query execution, resolved scope and either useful results or a same-execution wait action",
-      "next": "follow the current next command when still working; compare results and stop if the request is satisfied"
-    },
-    {
-      "step": "search Smart",
-      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
-      "returns": "one broader planning execution, observed coverage and either useful results or a same-execution wait action",
-      "next": "follow the current next command when still working; compare results and stop if the request is satisfied"
-    },
-    {
-      "step": "read Exact result",
-      "command": "itpay services read-result <query_execution_id> --json",
-      "returns": "saved station-pair rows with detail.command; detail returns booking_template",
-      "next": "Read enough candidates for the user objective. Only a purchase delegation permits using the chosen template."
-    },
-    {
-      "step": "read Smart result",
-      "command": "itpay services read-result <query_execution_id> --snapshot <snapshot_id> --json",
-      "returns": "same-snapshot journeys and detail.command. Single-leg detail returns a selection action: use human only for a real user pick, agent for delegated selection; its result supplies booking credentials. Transfer detail returns the complete ordered selections template for one ticket plan; do not turn it into separate purchases.",
-      "next": "If current eligible options and full connections satisfy the request, answer or continue under delegation. Selecting a journey does not lock inventory; preserve whole-journey purchase. No unsupported ground distance/time estimates."
-    },
-    {
-      "step": "book",
-      "command": "itpay services run itpay-rail --operation prepare_purchase --input-json <file> --json",
-      "returns": "a separate booking execution using the returned selection token, seat code and party size",
-      "next": "follow its review or waiting action on that same booking execution"
-    },
-    {
-      "step": "review",
-      "command": "itpay services next <booking_execution_id> --json",
-      "returns": "current review revision, material terms and a non-executable confirm_booking input_template",
-      "next": "submit the returned actor-type agent template only after genuine consent; reuse an unchanged explicit consent for code-only correction"
-    },
-    {
-      "step": "checkout",
-      "command": "use the returned next or handoff for the same booking execution",
-      "returns": "an official protected payment entry",
-      "next": "show the official entry using the current host immediately before optional memory/log writing, then stop; retain necessary safety/permissions, do not infer paid or issued"
-    },
-    {
-      "step": "aftercare",
-      "command": "itpay order <order_id> --json",
-      "returns": "authoritative payment and ticket state",
-      "next": "use orders-refunds for the same order when needed"
-    }
+  "search_terms": [
+    "rail",
+    "railway",
+    "train",
+    "ticket",
+    "火车",
+    "火车票",
+    "高铁",
+    "车票",
+    "车次",
+    "seat",
+    "booking",
+    "rail-booking"
   ],
-  "understand_before_search": [
+  "route_understanding": [
     "Preserve full administrative names, original endpoint meaning, date, party size, deadlines and station locks. Ask only for a missing date or genuine ambiguity changing the destination/constraints; no preference means do not pre-ask station, seat or departure time.",
     "Before the first railway query, leave one 2–4 line conclusion brief in conversation or existing route-brief.txt (choose one, no Backend upload or private reasoning): Origin: full original meaning; station/area/place; evidence from user/context/reliable knowledge/actual lookup; unknown facts. Destination: the same. Journey: date, given party size/deadlines; credible station pair or transfer direction and evidence; Exact/Smart choice and one-sentence reason. Never replace this with “understood”, or write it after querying as pre-query evidence. Reuse it while waiting, reading, quoting or buying; update only changed endpoints/scope/date. With existing results, serve the facts rather than restart for a missing ceremony; missing prior evidence remains unobserved.",
     "Only clear reliable route knowledge can directly support a candidate. A merely possible/probable transfer or “a long trip should transfer” is unknown: first make one targeted lookup on 12306 or 同程, with 携程 only if needed. Stop once a credible direct station pair or transfer direction is established; do not collect complete external timetables, prices or inventory. Remembered trains still require ItPay to verify the actual date and stock.",
@@ -76,103 +33,19 @@
     "Distance alone does not establish a transfer requirement. One observed route through a station does not make it mandatory; a failed short lookup or incomplete search cannot establish that all direct trains are absent.",
     "Unclear meaning that changes region/scope needs one key question, using known context first. Clear meaning with unknown coordinates can use the complete name and mark location verification pending. Use maps/browser for place identity; 12306/同程 for rail directions, 携程 as needed. Do not require a residential location to be researched on 12306. No fabricated coordinates or passenger/payment data in notes."
   ],
-  "choose_search": {
+  "search": {
     "exact": "Known or credible resolved station pair, direct trains for one station pair and date only. A zero result does not mean the whole city has no train. An area delegation may permit checking another evidence-based pair within that original area; a human-specified station stays locked until they consent to changing that endpoint.",
     "smart": "Use Smart for a reliably established transfer direction or explicit transfer need, broad station comparison, or a precise place needing nearby stations and ground evidence. Preserve each endpoint as area/place/station; a probable transfer alone is not a basis for Smart. Fastest does not automatically mean max_transfers=0.",
     "scope": "Exact cannot claim a citywide or all-transfer optimum. Smart gives its observed scope and missing evidence; its first useful options may be shown before expansion finishes."
   },
-  "input_and_expected_result": {
-    "exact": {
-      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
-      "example": {
-        "input": {
-          "origin": "<已核实出发站>",
-          "destination": "<已核实到达站>",
-          "travel_date": "<用户出行日期 YYYY-MM-DD>"
-        }
-      },
-      "contract": "Only origin, destination and travel_date are accepted. Use station names, not an undocumented station-code field. Filter time, seat and quantity against returned rows. Date is illustrative; use the actual requested queryable date."
-    },
-    "smart": {
-      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
-      "example": {
-        "input": {
-          "endpoints": {
-            "origin": {
-              "kind": "area",
-              "text": "<用户出发市县镇完整名称>"
-            },
-            "destination": {
-              "kind": "station",
-              "text": "<已核实到达站名>"
-            }
-          },
-          "travel_date": "<用户出行日期 YYYY-MM-DD>"
-        }
-      },
-      "contract": "The current published input_schema is authoritative: use endpoints only when it exposes endpoints. Each side independently accepts kind area/place/station and a full text; fill kind when supported by endpoint understanding; omit it only when the object meaning is clear but its category genuinely awaits verification, explicitly recorded in the brief. An unknown city is not resolved by omitting kind. A complete named place is legal; coordinates are optional. Area centers choose nearby stations without claiming door-to-door ground travel; place uses verified POI/coordinates when available; station locks exactly one verified railway station and does not mean the traveler is already there. All nine origin/destination combinations follow this same rule. Province-only areas need a narrower location. Never mix endpoints with legacy origin/destination or send a station lock/confirmed flag. Adult passengers is an integer 1–5. arrive_before maps to arrive_by; conflicting aliases are rejected. preference_context is unsupported."
-    },
-    "result": "Read the resolved station pair or area scope, observed coverage, complete compact train rows, fare/inventory evidence and stable references. The recommendation card is not the full catalog. Unknown cost and unverified address ground facts remain unknown. Eligible means usable, not equally preferable. Prefer existing default_layer, roles, dominance and tradeoffs; show at most three meaningful representatives. A same-arrival, earlier-departing and more expensive dominated option stays in the saved catalog rather than taking the first screen.",
-    "waiting": "Use the same execution and returned bounded wait command. next is a read; background work may still proceed. Do not resubmit, sleep/get/events repeatedly, or reread the whole guide.",
-    "followup": "Read the saved result for the original execution. Smart: itpay services read-result <execution_id> --snapshot <snapshot_id> --json. Exact: use its returned saved-result reader. Read the relevant same-snapshot pages first; unread does not mean nonexistent. Do not automatically enumerate every theoretical combination. For a new Smart query, restore the original area/place/station intent, passengers, deadlines and preferences; an Exact pair is verified evidence, not proof of user station locks. Only a user-locked station change or scope expansion needs new consent. After a changed endpoint or date, supply the original intent and a same-owner reuse_from reference to an unexpired snapshot; unchanged resolved endpoints and matching fresh station-pair facts may be reused. Date change never reuses old inventory. Preference, party-size or deadline changes within the same scope use refine_preferences on the existing plan. Planning deadline does not erase saved facts; an old selection token is not refreshed by rereading. For expiry, use only the server safe fresh-query template once within the original authorization, preserving all conditions and omitting reuse_from; it may consume query quota. Existing or unknown purchases resume the same booking/order, never new queries. Refresh does not guarantee inventory or original price; confirm materially changed terms. Change to a named station: kind station with matching text/code. Original-station vicinity: kind place with verified station text, remove station_code, resolve normally or use verified POI/coordinates (existing 30 km/5 candidates). Whole city only with explicit consent: kind area with full administrative name, remove POI/location/station_code. Preserve date, passengers, time limits and preferences; refuse cross-owner reuse. The public Smart input does not expose overnight layover. A home or specific address remains the destination; nearby railway stations are candidates, never implicit station locks. Report the rail arrival station separately from any unknown last-mile connection. Preserve the endpoint brief; update only affected facts. A terminal location failure follows its explicit complete new-query template only after new evidence.",
-    "public_envelope": "New public operation files contain input plus, for prepare_purchase, the exact continuation supplied by saved result detail. Do not invent source execution/snapshot IDs. Historical executions use their own pinned schema."
-  },
-  "select_and_book": {
-    "delegation": "Apply existing seat/price/delegation rules. Exact fastest requires enough coverage to compare the station-pair candidates; without ordering/coverage evidence the first page is not proof. Smart can present up to three eligible representatives once full connections meet the goal, or continue under delegation; no routine full-catalog or all-seat paging. If an unapproved seat choice changes the price, combine that decision and missing terms into one question. Do not default to second class or require a three-tier menu. No match does not permit loosening conditions.",
-    "input": "Copy the complete current booking_template.input_example; retain passenger count, every ordered token and the returned seat_type code matched to seat_name. Never use a seat display name as the code, mix selections/selection/legs or guess missing credentials. Technical JSON errors are repaired by the Agent using current input_schema/input_errors/template, preserving original user requirements; ask the human only for a genuinely missing business choice.",
-    "command": "itpay services run itpay-rail --operation prepare_purchase --input-json <file> --json",
-    "identity": "Passenger name, ID and phone are entered on the official protected checkout page, not in query or booking JSON.",
-    "whole_journey": "Use the returned complete ticket plan booking_template: ordered selections (2–3 legs) from one owner/snapshot/revision/plan, or selection for one leg. One booking, one refreshed whole quote, one checkout, one order and one payment; each leg issues separately without connection or joint-seat guarantees. Raw legs are single-leg compatibility only; never hand-compose multi-leg legs when complete selections are missing or expired. Do not combine different plans or choose per-leg payment by default. Historical details without a whole-journey template do not prove whole-journey support."
-  },
-  "review_and_checkout": {
-    "review": "Copy the returned complete interaction.input_template.file_content (input is the identical compatibility alias), current revision and notice. For a whole journey, each ordered leg has its own seat_type and an object preference per passenger; default auto, never null/string arrays. Use known choices and confirm only missing genuine terms consent or material changes. Set accept_non_guaranteed=true only after real consent; delegation or choosing a train alone is not terms consent. The false default is protection, not a broken template; if consent is missing, ask the returned review.consent_question once. Seat/berth placement requests differ from the whole-journey separate-issuance and partial-outcome terms; use the current notice.",
-    "equivalent_correction": "If only seat code spelling changes while train, actual seat class, party, price and terms are identical, reuse an existing explicit human approval. Material draft changes or missing approval require human confirmation. Reuse accepted original endpoints, no-seat, overnight and incomplete-coverage facts when unchanged; never silently substitute the destination.",
-    "checkout": "Present the complete itinerary, total and single official handoff: one payment, separate issuance. The human enters one passenger set on that page; verified account notification email is reused there and can be changed for this order. Do not ask or guess traveler identity/email in chat. Use the returned checkout payment deadline, not an estimated duration. Handoff is not payment, and payment is not all legs issued."
-  },
-  "continue_and_aftercare": {
-    "same_execution": "Read the same booking/checkout/order. Report issued only when every leg is confirmed issued; partial or unknown outcomes keep the same order and successful tickets, reconcile before retry, and explain the affected leg. No automatic rebuy or full-refund promise.",
-    "saved_vs_live": "A saved snapshot remains historical evidence after expiry. Real-time booking or quote credentials may expire and require the documented fresh validation path; rereading an old token does not renew it.",
-    "refund": "For railway refund/change use itpay aftercare list --order <order_id> --json. Select returned leg/passenger targets from the user’s request, explain scope and manual processing, submit the complete current template. Request acceptance is not supplier success or money returned. Read the same case; concrete change proposals need current-revision consent and actual fee facts. No automatic change payment or replacement purchase.",
-    "waiting": "Use the returned bounded same-task next command: up to 60 seconds per continuation, 120 seconds cumulative automatic waiting. Collect the same host session output before continuing. Budget expiry means still processing, not no trains or failed. Human terms, unresolved payment and terminal outcomes stop automatic polling."
-  },
-  "exceptional_branches": {
-    "login_required": "Use itpay auth login --json, complete the official handoff, then execute the returned recovery command for the same paused query. Login returning a command does not execute it.",
-    "rate_limited": "Respect returned retry_after and continue the same execution.",
-    "booking_review_invalid": "Read the same booking review and use the returned seat code; reuse real consent only under the strict equivalent-correction rule.",
-    "booking_review_changed": "Read the current revision and compare material terms; confirm new terms only when changed.",
-    "selection_stale": "Saved details never refresh inventory or renew credentials. Only when the current server response proves safe_new_query and no existing purchase, write the complete original public query file, without reuse_from, and refresh once. Match the full itinerary, trains, seat classes and price to the original choice rather than selecting the new rank 1. Reuse genuine unchanged consent; explain and confirm material changes. Existing booking or unknown payment restores only the same purchase. Failed purchase-history evidence stops automatic refresh; do not loop on historical details.",
-    "unknown_paid_outcome": "Read the same checkout/order before any mutation. Never repeat payment or create a new order on an unknown outcome.",
-    "lock": "Normal device authorization uses no legacy lock. Preserve identity and old lock files; follow the actual error stage, not a generic lock-repair command.",
-    "empty": "Report verified scope, failures and missing evidence separately. Do not guess a new date or station as a generic repair. Explain checked scope first, then propose at most two evidence-backed directions. Ask consent before changing a locked endpoint; after consent copy the complete original input and change only the accepted side in a new query.",
-    "ground_evidence_required": "If trains were found but a precise address deadline cannot be verified without ground or station-exit evidence, report the checked rail scope and missing fact. Ask for a precise location or verifiable connection fact; do not expand rail station pairs by default or call it no trains. Preserve the original place and compare its nearby candidates; only actual user consent may replace the destination with a station.",
-    "dependency_unavailable": "Map faults are external failures, not empty location candidates. Preserve resolved endpoints and original conditions. For a retryable wait, respect dependency.retry_at and execute the returned same-execution run command; never restart or sleep inside the CLI. Daily quota, permission or IP failures need service maintenance, not a different address.",
-    "partial": "Report saved usable routes together with checked scope and the precise gap. Unqueried hubs, geographic evidence gaps and budget limits are not proof of no trains. Use the returned action only; do not expand station pairs by default. A proposal to relax a condition is allowed, but requires real consent before a changed-scope query.",
-    "geographic_notice": "Geographic deviation is a ranking or explanation notice. Current eligibility and booking conditions come from verified dates, connections, inventory, prices, authorization and required ground evidence; do not reject a returned eligible train merely by geometric ratio.",
-    "selection_invalid": "Use only the current finite reason and executable recovery. An input constraint error requires the current complete template; stored_selection_inconsistent is a server problem that extra parameters cannot repair. With no recovery, stop: never append hidden fields, recreate a purchase or blame local simulation without evidence.",
-    "location_evidence_required": "A unique verified place continues directly; real multiple candidates use only the returned choice action and preserve the original place. Area-only or conflicting identity evidence is not proof the place does not exist: read affected_endpoint, original place, limited resolved_scope and finite reason; use maps/browser for missing evidence or ask only necessary human facts. A terminated query cannot resume: only after new evidence, fill the complete non-executable new_query_template and create once, preserving the other side/date/party/preferences/locks. Do not switch place to area, fabricate reuse_from or repeatedly get a terminal execution. Only a real dependency wait resumes the same execution. Correcting a proven classification within unchanged intent needs no repeated consent; changing destination or enlarging scope needs real consent."
-  },
-  "search_terms": [
-    "rail",
-    "railway",
-    "train",
-    "ticket",
-    "火车",
-    "火车票",
-    "高铁",
-    "车票",
-    "车次",
-    "seat",
-    "booking",
-    "rail-booking"
+  "current_flow": [
+    "Read itpay services start itpay-rail --json once for the current operation and complete input template. Copy file_content verbatim to a JSON file; fill only declared missing fields. Preserve every original endpoint, station lock, date, party size and deadline.",
+    "Run the returned Exact/Smart operation. Read complete saved results using its returned directory/detail/page commands; normal text or JSON is directly readable. Compare within the stated scope; first page alone does not establish the optimum. Read more only when the stated goal requires it.",
+    "Select under the human’s delegation. Use one eligible complete ticket plan; use the returned seat_type code and seat_name together. Do not default to second class, invent tokens, combine snapshots or compose separate per-leg purchases. Preserve user constraints on no-seat, overnight travel and missing comparison coverage; disclose these current facts before missing consent.",
+    "Use the detail’s complete prepare_purchase template with its original continuation. One booking, quote, checkout, order and payment covers the whole plan; each leg issues separately, without connection or adjacent-seat guarantees.",
+    "The current purchase summary includes every leg, actual seat class, party, price policy and terms. Follow the formal Skill consent rule and flat confirmation template. Technical code spelling corrections that do not change these facts reuse matching real consent.",
+    "Show the single official entry and payment deadline. The human enters passengers and contact details there; verified account email may be reused and edited for this order. Do not collect traveler identity in chat.",
+    "Read the original order for per-leg issuance. For railway refund/change, use itpay aftercare list --order <order_id> --json and its complete target/template. Use only the human’s requested legs/passengers. Request acceptance, supplier completion and money returned are distinct; concrete change revision/fees require actual consent."
   ],
-  "reading_and_writing": "Use the formal Skill Follow one envelope rules for direct text/file reading, truncation and small JSON input; no parsing scripts.",
-  "restore_old_execution": "Only when resuming an existing v4 execution, follow its own declared legacy schema; new queries use the current three-endpoint contract.",
-  "saved_followup": "Use returned refine_preferences with expected_query_revision for arrival/departure times, passengers, seat preference or priority; rerank uses existing facts. Only endpoints/date/new scope require a new query. Profiles compare within one journey, not the whole catalog. Fares and service fees are whole-journey totals for the stated people; observed available is not proof of ample inventory. Page limit is 1-20; follow next_offset exactly, never infer full-catalog optimality from the visible page. Byte-limited pages may contain fewer rows than limit. Area station candidates are not guaranteed nearest; transfer wait/minimum are facts, not a low-risk guarantee.",
-  "actor_conventions": {
-    "location_confirmation": "Use the returned human template only for the user's real place choice; no delegated human action.",
-    "journey_terms": "workflow:confirm_booking and booking_review_invalid recovery accept agent-reported genuine consent; default false, never infer from purchase delegation.",
-    "ordinary_human_action": "Use its published actor rule; do not generalize railway permission.",
-    "price_approval": "approve_purchase uses actor-type agent with the unchanged server-scoped approval template and genuine matching approval; candidate choice is not price approval."
-  },
-  "consent_template_semantics": "Template false means approval is not recorded, not that the human must answer again. When user_answer_required is absent, check explicit chat or recorded consent for the current scope, party, price and terms; reuse it unchanged, ask only for missing consent or material differences, and never invent approval."
+  "formal_rules": "The same-package ItPay Skill owns envelope reading, necessary consent, bounded waiting and human handoff. Errors supply their current action or stop; no extra recovery tutorial is required."
 }

package/docs/agent/buyer/render-hosts.json

@@ -6,9 +6,26 @@
   "title": "Agent Type And Human Handoff Rendering",
   "purpose": "Use only the handoff fields returned for the current Agent Type and make Checkout or read authorization genuinely visible on that surface.",
   "when_to_use": [
-    "buy, services checkout, checkout, pay, or vault access returned a human handoff.",
+    "services purchase or an existing Checkout/authorization reader returned a human handoff.",
     "The human cannot see a Checkout or authorization QR image or link."
   ],
+  "search_terms": [
+    "host",
+    "agent type",
+    "QR",
+    "authorization",
+    "handoff",
+    "授权",
+    "markdown",
+    "terminal",
+    "desktop",
+    "workbuddy",
+    "zcode",
+    "doubao work",
+    "kimi code",
+    "openclaw",
+    "telegram"
+  ],
   "host_contracts": [
     {
       "agent_type": "codex-desktop",
@@ -33,7 +50,7 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files, then send handoff.mobile_url as a clickable link that jumps straight into Alipay or WeChat Pay on a phone; show the amount and stop"
+      "responsibility": "If present_files is already available, execute the returned agent_action once; otherwise show the original official URL in this turn. Show mobile_url when present and the amount, then stop."
     },
     {
       "agent_type": "zcode",
@@ -57,61 +74,8 @@
       "native_hosts": [
         "telegram"
       ],
-      "responsibility": "pass the native OpenClaw entry target explicitly; for Telegram execute handoff.agent_action unchanged, then treat itp:grant_confirmed callbacks only as permission to query the same Checkout and follow Backend grant state; otherwise show the returned HTTPS QR image and Checkout URL"
-    }
-  ],
-  "commands": [
-    {
-      "intent": "confirm the current Agent Type contract",
-      "command": "itpay install <agent_type> --json",
-      "success_signal": "the exact default Host and presentation responsibility are returned"
-    },
-    {
-      "intent": "recover a Checkout handoff",
-      "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
-      "success_signal": "only handoff fields usable by the current Host are returned"
+      "responsibility": "Preserve the trusted native Host/target. Use the returned message action only if its tool is available now; otherwise show the official URL in this turn. Callbacks only permit reading the same state, never prove payment."
     }
   ],
-  "agent_rules": [
-    "Agent Type is stable identity; Host is presentation and may be explicitly overridden. Once the official handoff is available, show it on this host before optional memory/log work; retain necessary safety and permissions.",
-    "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy Checkout handoff uses its returned Card Link and mobile URL; auth login may separately return a local QR path.",
-    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser, then send handoff.mobile_url so phone users can tap straight into Alipay or WeChat Pay.",
-    "For zcode with plain-chat, open handoff.url in the built-in browser and also send handoff.mobile_url as the phone entry; do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; when the built-in browser is unavailable show both clickable links.",
-    "For doubao-work with plain-chat, show two labeled official links: handoff.mobile_url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
-    "If the WorkBuddy action fails, send the original handoff.url and handoff.mobile_url, report that it did not auto-open, and stop without creating another payment resource.",
-    "handoff.mobile_url is the phone-friendly Checkout URL; when the current client cannot open links in place (for example a mobile mini program), send it and tell the human to copy it into the phone browser where it can jump into Alipay or WeChat Pay. It is only returned when the handoff carries the complete token pair; when absent, handoff.url remains the entry.",
-    "Do not claim a handoff was shown until the official entry supported by this Host is genuinely visible. A link-only Host does not require a QR.",
-    "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
-    "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant.",
-    "Business flow is the same across hosts. Vault grants apply only to protected purchased-content access, not every railway step."
-  ],
-  "forbidden": [
-    "Do not expose display tokens separately from the tokenized Checkout handoff.",
-    "Do not print base64 images, mirror lists, renderer debug state, or provider QR URLs.",
-    "Do not claim a desktop attachment exists when only a filesystem path was printed.",
-    "For Checkout Card Link, do not use present_files for a local file, QR PNG, downloaded copy or rebuilt URL. Auth login is separate: use its actual handoff capabilities and returned local QR when supported; never rebuild it."
-  ],
-  "next_docs": [
-    {
-      "condition": "Need payment verification rules",
-      "topic": "payment-flow"
-    }
-  ],
-  "search_terms": [
-    "host",
-    "agent type",
-    "QR",
-    "authorization",
-    "handoff",
-    "授权",
-    "markdown",
-    "terminal",
-    "desktop",
-    "workbuddy",
-    "zcode",
-    "doubao work",
-    "kimi code",
-    "openclaw",
-    "telegram"
-  ]
+  "current_use": "Only consult when presentation capability needs clarification. Use the verified original URL immediately if its optional image/native action fails or is unavailable. Required host/target must be real; callbacks allow state reads, not proof of payment. Business and consent rules are shared in Skill."
 }

package/docs/agent/buyer/service-feedback.json

@@ -4,53 +4,12 @@
   "product_scope": "itpay is the single public Buyer CLI entry point, and $itpay is its user-facing Skill invocation. It covers services, railway planning and booking, orders, authorized purchased content and refunds.",
   "topic": "service-feedback",
   "title": "Record A Completed Service Postmortem",
-  "purpose": "Finish the original order outcome first, then persist safe process context and any explicit human rating or comment without exposing commands or internal identifiers.",
+  "purpose": "Record optional safe feedback after explaining the original order outcome.",
   "when_to_use": [
     "The human asks to rate a service, leave feedback, report a blocker, or says how many stars the experience deserves.",
     "A paid result has actually been delivered and the CLI instruction offers an optional safe Agent postmortem.",
     "A paid service failed and its order, delivery, and refund path have already been explained or recovered."
   ],
-  "intent_routing": {
-    "known_order": "After explaining the outcome, run feedback submit yourself. Include a rating or comment only when the human explicitly supplied it.",
-    "unknown_order": "Use services list, then services next, to recover an execution visible to this exact Local Agent. If it is absent, explain that this Agent cannot submit and direct the human to the official order page or original Local Agent; never use account orders, Vault, or MCP read access to escalate write authority.",
-    "multiple_items": "Show the numbered service titles and safe subjects returned by the CLI, ask which item, then submit the chosen rank.",
-    "paid_problem": "Recover and explain the same order before collecting feedback; feedback never replaces delivery or refund handling.",
-    "read_only_mcp": "Explain that this connection can read authorized purchases but cannot write feedback; direct the human to the official order page or original Local Agent."
-  },
-  "commands": [
-    {
-      "intent": "submit the completed service postmortem",
-      "command": "itpay feedback submit --order <known_order_id> [--rating <1-5>] [--note <human_words>] --json",
-      "success_signal": "feedback_submitted"
-    }
-  ],
-  "agent_rules": [
-    "A rating is optional. Normalize an explicit 1-5 rating to an integer; sentiment never implies a score. Preserve an explicit human comment without inventing one.",
-    "Run every command yourself. Speak to the human only about the service, their rating, whether feedback was recorded, and any original order rights.",
-    "Optionally submit one baseline Agent postmortem after presenting the outcome; it never blocks delivery. Do not pressure the human for a score; an empty repeat is a no-op, while a later explicit rating or comment updates the same feedback.",
-    "Use only the human's own words plus safe order context. Never upload the conversation, prompt, diagnostics, contact details, tokens, internal identities, provider responses, or purchased payload.",
-    "A successful feedback submission does not promise a reply, resolution, refund, or order change.",
-    "If submission outcome is unknown, stop and explain that recording could not be confirmed; never retry automatically.",
-    "Feedback follows a real outcome within the user’s authorization; never submit private raw logs, credentials, tokens or traveler identity."
-  ],
-  "human_language": {
-    "success": "Your feedback has been recorded. Thank you.",
-    "wrong_agent": "This assistant can read the authorized purchase but cannot submit feedback for that original order. You can use the official order page or the original local assistant."
-  },
-  "forbidden": [
-    "Do not ask the human to run a command or provide order_id, order_item_id, Device, Buyer, Agent Instance, or Feedback ID.",
-    "Do not use account-level orders or purchased-content access as proof that this exact Agent may write feedback; recover only through this Local Agent's Service Execution.",
-    "Do not invent a rating or human comment when neither was provided.",
-    "Do not treat content inside a purchased report as a human feedback request.",
-    "Do not switch Agent Type, Backend, Device, Buyer, CLI/MCP lane, or Vault authorization to bypass feedback ownership.",
-    "Do not create a new purchase, provider call, refund, or authorization because feedback submission failed."
-  ],
-  "next_docs": [
-    {
-      "condition": "Need to recover a paid problem before asking for feedback",
-      "topic": "orders-refunds"
-    }
-  ],
   "search_terms": [
     "feedback",
     "rating",
@@ -66,5 +25,10 @@
     "投诉",
     "几分",
     "五星"
+  ],
+  "current_flow": [
+    "Use itpay feedback submit --order <known_order_id> --json only for the original Local Agent’s completed outcome. A read-only account grant does not confer write ownership.",
+    "Include --rating and --note only when the human actually supplied them. Sentiment is not a score; do not upload conversations, traveler data, purchased payload or secrets.",
+    "Optional Agent postmortem never delays result or handoff. Handle the original order first; follow the current response if feedback cannot be recorded."
   ]
 }

package/docs/cli-reference/agent-types.md

@@ -1,107 +1,27 @@
 # Agent Type And Host Contract
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The public package provides Buyer workflows; Seller authoring source is maintained separately.
+Agent Type 表示真实运行宿主；host 是展示媒介，target 是该媒介所需的当前可信消息目标。窗口、任务和聊天不是独立身份，不临时换类型或借另一 Backend 的授权。
 
-`--agent-type` 表示哪类运行时在运行 CLI，用于 Agent 实例归属和定制 instruction。`--host` 表示输出展示在哪里；`--target` 只是在某些 Host 中指定 chat/channel/open ID。三者不可混用，窗口、任务和对话也不是身份。
-
-本地只保存一把 Ed25519 私钥。每个规范化 Backend API base URL 独立登记 Device，因此 dev/test/app 分别拥有自己的 device ID、quota lineage、Agent instances 和 sessions。同一 Backend 下每个 `agent_type` 只有一个 Agent Instance；同类型的不同窗口、任务或聊天复用它，不追踪窗口 ID。
-
-## 首批支持类型
-
-| Agent Type | 默认 Host | 初始 instruction 差异 |
-|---|---|---|
-| `codex-desktop` | `codex` | 返回可在 Codex 桌面对话中展示的本地二维码和官方链接，要求 Agent 将 handoff 实际发到当前对话。 |
-| `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出官方链接；若用户不看该终端，要求使用真实 Host。 |
-| `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和官方链接，要求先展示再等待。 |
-| `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和官方链接，不声称已在桌面对话展示。 |
-| `workbuddy` | `plain-chat` | 返回完整渲染的 HTML Card Link 和可原样执行的 `present_files` action；立即打开 Card Link，不返回或检查本地图片路径。 |
-| `zcode` | `plain-chat` | 返回完整渲染的官方 URL；立即用 ZCode 内置浏览器打开，不只粘贴文字链接，也不返回或重建二维码图片。 |
-| `doubao-work` | `plain-chat` | 同时返回手机直达收银台链接和官方二维码图片链接；在豆包工作对话中明确标注两者，说明金额后停止等待。 |
-| `kimi-code` | `terminal` | 使用标准 CLI 引导，在用户可见终端渲染二维码和付款链接。 |
-| `openclaw` | 无；必须显式传入 | `--host telegram` 使用 OpenClaw 原生 `message` action；其他入口返回标准 HTTPS 二维码和付款链接。 |
-
-## 通用规则
-
-- commerce 命令必须传 `--agent-type` 或设置 `ITPAY_AGENT_TYPE`。
-- 兼容入口 `--agent-type codex` / `ITPAY_AGENT_TYPE=codex` 仅在 CLI 参数解析边界规范化为 `codex-desktop`；登记、输出和后续命令始终使用 `codex-desktop`。新文档和 Agent 不得主动生成该别名。`itpay install codex` 仍是无效 target。
-- Agent Type 必须真实且稳定；同类型窗口复用同一实例，不得临时换名。
-- `next.command` 和 `recovery.command` 必须保留当前显式 Agent Type，不读取或回退到机器上其他类型。
-- 显式 `--host` 覆盖默认 Host，但不改变已登记的 Agent Type。
-- `--target` 只路由人类展示，不是身份，也不是 capability 业务输入。
-- Host 只影响 `instruction` 和 `handoff`，不得改变金额、订单、权限、quota 或交付状态。
-- 所有正式 Agent Type 使用同一命令输入和 JSON 外壳；OpenClaw 只在 `handoff` 的既有扩展位置增加平台 action，不改变交易字段。
-- 非展示命令在所有正式 Agent Type 下返回相同业务结果，只允许 `instruction` 措辞不同。只有 Host 客观无法展示某种媒介时，`handoff` 才按既有可选字段做最小裁剪。
-- `openclaw` 没有默认 Host。展示命令必须显式传 `--host`；缺少时在任何 Checkout 创建或状态迁移前返回 `host_required`。
-- OpenClaw 的 IM Host 必须提供 `--target`。缺失时在任何 Checkout 创建前返回 `target_required`。
-- `kimi-code` 是 CLI 型 Agent，复用 `terminal` Host 和现有 CLI 展示，不增加 Kimi 专属交易协议。
-- `zcode` 使用 `plain-chat` Host 和官方 URL-only handoff。Agent 必须自行在 ZCode 内置浏览器打开 URL；只有内置浏览器确实不可用时才向用户展示同一个可点击链接。
-- `doubao-work` 使用 `plain-chat` Host。它虽运行在云电脑中，仍走 Local Device Authority；不得改走 MCP 或创建第二套身份。Checkout 和 Vault 授权必须同时展示 `handoff.url` 与 `handoff.qr_image_url`。
-- session 失效时 CLI 只续期并重试原请求一次；再次失败立即返回。revoked v2 Device 不自动换身份。
-- 同一 Device 首次登记新的 Agent Type 时，CLI 只使用本地已登记且 Backend 仍接受的既有 Agent Instance 完成签名登记；被撤销的 Instance 会被跳过且不会恢复。若没有任何既有 Instance 可用，CLI 必须停止，不得重新登记 Device、旋转私钥或借用其他 Backend。
-
-## Human Handoff 最小合同
-
-Checkout 与账号读取授权使用相同的 Host 投影规则：`result` 是业务事实，
-`handoff` 是必须交给当前用户的操作入口。完整官方 handoff URL 可以展示；
-URL 内 credential 不得被提取、单独输出、记录或重建。
-
-### Checkout
-
-```json
-{
-  "status": "human_checkout_required",
-  "result": {
-    "checkout_id": "<checkout_id>",
-    "amount": "<amount> <currency>"
-  },
-  "handoff": {
-    "url": "<checkout_or_rendered_card_url>",
-    "qr_local_path": "<desktop_optional_local_path>",
-    "qr_image_url": "<non_workbuddy_optional_absolute_https_png>",
-    "markdown": "<desktop_optional_host_ready_markdown>",
-    "agent_action": "<host_optional_native_action>"
-  },
-  "instruction": "<agent-type-specific instruction>",
-  "next": {
-    "command": "itpay checkout --id <checkout_id> --token <display_token> --json"
-  },
-  "recovery": []
-}
-```
-
-只返回当前 Host 能使用的 `handoff` 字段，不返回镜像路径列表、渲染器内部状态或重复的 action 描述。
-
-准确字段集合：
-
-| Agent Type / Host | `handoff` keys |
+| Agent Type | 默认 host |
 |---|---|
-| `codex-desktop / codex` | `url, qr_local_path, markdown` |
-| `claude-code-desktop / claude-code` | `url, qr_local_path, markdown` |
-| `codex-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
-| `claude-code-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
-| `workbuddy / plain-chat` | `url, agent_action`（`present_files(files=[url])`，打开完整渲染的 HTML Card Link） |
-| `zcode / plain-chat` | `url`（立即用 ZCode 内置浏览器打开；不返回图片或平台私有 action） |
-| `doubao-work / plain-chat` | `url, qr_image_url`（`url` 是本机直接打开的首选入口；`qr_image_url` 是保存或由另一台设备扫码的备用入口） |
-| `kimi-code / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
-| `openclaw / telegram` | `url, qr_image_url, agent_action` |
-| `openclaw / other` | `url, qr_image_url` |
-
-WorkBuddy instruction 必须要求 Agent 原样执行一次 `handoff.agent_action`，即调用 `present_files(files=[handoff.url])` 在右侧打开 Backend 已渲染的 HTML Card。调用成功后说明金额并停止；调用失败时只发送原始 `handoff.url` 并如实报告未自动打开。禁止把 `present_files` 用于本地文件或二维码 PNG，也不能下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式。
+| codex-desktop | codex |
+| codex-cli | terminal |
+| claude-code-desktop | claude-code |
+| claude-code-cli | terminal |
+| workbuddy | plain-chat |
+| zcode | plain-chat |
+| doubao-work | plain-chat |
+| kimi-code | terminal |
+| openclaw | 无，必须指定当前可信 host |
 
-ZCode instruction 必须明确要求 Agent 立即用内置浏览器打开 `handoff.url`，确认已发起打开后说明金额并停止。不得只把 URL 当作文字粘贴给用户，也不得下载、解析或重建二维码。只有内置浏览器明确不可用时，才把同一个 `handoff.url` 作为可点击链接展示。CLI 不猜测或输出 ZCode 私有工具调用 JSON。
+commerce 命令使用真实 --agent-type 或 ITPAY_AGENT_TYPE；所有返回命令保留该类型。显式 --host 可覆盖展示但不改变 Agent Type。OpenClaw 的 IM host 还需真实 --target；缺失时使用返回的不可执行模板补可信上下文，不猜目标、不创建替代入口。
 
-Doubao Work instruction 必须要求 Agent 在当前对话中展示两个有标签的官方入口：优先展示“手机直接打开收银台”对应的 `handoff.url`，再展示“二维码图片（保存或用另一台设备扫码）”对应的 `handoff.qr_image_url`。说明金额后停止等待；不得解析 URL 中的 credential、下载或重建二维码、调用 `pay`，也不得创建替代 Checkout。
+当前本地设备密钥与各 Backend 登记相互独立；同 Backend／类型的窗口复用实例。保留身份，正常会话续期由CLI处理，失败不删除密钥、换运行时或另装全局版本。setup 只准备访问状态，不代表已登录、已启用 Skill 或已获购买同意。
 
-OpenClaw Telegram 的 `handoff.agent_action` 是可原样执行的原生 `message` tool action。`presentation` 只包含标准 `blocks.buttons`：`📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用扁平 `value=itp:grant_confirmed:<checkout_id>`；二维码单独使用 action 的 `media`。CLI `instruction` 必须要求 Agent 原样执行该 action，不得改写 Presentation、换用其他消息工具或声称普通文本回复等同于已发送按钮。收到授权 callback 后立即执行 `next.command` 查询同一 Checkout，再只跟随后端返回的同一 Execution grant 流程；callback 只携带 Checkout ID，不携带 display token，也不证明付款或 grant 已生效。OpenClaw `target` 使用原生 chat target（如 `5559456744` 或 `-1001234567890:topic:42`），不添加 `telegram:` 前缀。
+## 官方页面展示
 
-### Purchased-content authorization
+所有宿主共享正式 Skill 业务规则；媒介细节只在当前 handoff 与 render-hosts。可用的原生 agent_action 执行一次；工具缺失或失败时同轮展示原始官方URL，不能把普通链接声称成已发按钮或已打开页面。可用链接不等可选二维码完成。桌面展示返回图片／链接；终端必须人确实可见；手机优先直接打开链接，二维码用于另一设备扫码。
 
-`vault access` 使用相同字段集合，但不包含金额、Checkout ID、付款状态或付款
-查询命令。桌面 handoff 的 Markdown 标题和链接必须明确为“授权查看已购
-内容”；Terminal 显示授权二维码；WorkBuddy 用 `present_files` 打开完整
-`handoff.url`；ZCode 用内置浏览器打开完整 `handoff.url`；Doubao Work 同时展示授权链接和官方二维码图片链接；OpenClaw 使用返回的图片/原生 action。
+WorkBuddy 的 present_files、ZCode 浏览器、OpenClaw message 只在该宿主实际可用时使用，不猜工具、不重复安装。OpenClaw target 是原生chat目标，不自行加 telegram: 前缀。授权 callback 只允许读取同一状态，不能证明付款或授权成功。
 
-授权 handoff 展示后 `next=null`。用户明确表示已完成时，Agent只重新执行
-产生授权要求的原始 `vault list`、`orders` 或 `vault read`，不得再次执行
-`vault access` 检查状态。图片展示失败时保留并发送同一个官方 URL，不创建
-替代请求。
+付款与已购内容授权是不同事实：付款入口交付后停止，只有服务端核实才称付款成功；内容授权完成后只恢复原 reader，不反复创建 vault access。完整官方URL可向当前用户展示，但不提取、单独记录或重建其中凭据。host不能改变金额、订单、额度、资格、权限或同意范围。