@itpay/cli 2.0.32 → 2.0.33

package/dist/src/client/backend.js

@@ -58,6 +58,9 @@ export class BackendClient {
     getOrderDeliveryAccess(orderID) {
         return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/delivery-access`);
     }
+    submitServiceFeedback(orderID, input) {
+        return this.http.post(`/v1/orders/${encodeURIComponent(orderID)}/feedback`, input);
+    }
     listAccountOrders(limit, status, bearer, cursor) {
         const qs = new URLSearchParams({ limit: String(limit) });
         if (status) {

package/dist/src/commands/feedback.js

@@ -0,0 +1,143 @@
+import { CLI_VERSION } from "../state/config.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+const MAX_FEEDBACK_NOTE_CODE_POINTS = 2000;
+export async function runFeedbackSubmit(backend, orderID, options) {
+    const normalizedOrderID = orderID?.trim() ?? "";
+    if (!normalizedOrderID) {
+        throw new CommandContractError("order_required", "--order is required", "先恢复用户所说的原订单；Agent 自己取得订单，不要求用户提供内部 ID。本次未提交反馈。", [{ command: "itpay orders --json", reason: "列出当前授权账号的订单摘要" }]);
+    }
+    const rating = normalizeFeedbackRating(options.rating);
+    const itemRank = normalizeItemRank(options.itemRank);
+    const userNote = normalizeUserNote(options.note ?? "");
+    const order = await backend.getOrder(normalizedOrderID);
+    const choices = feedbackItemChoices(order);
+    if (choices.length === 0) {
+        throw new CommandContractError("feedback_unavailable", "this order has no service item available for feedback", "告诉用户这笔订单当前没有可评价的服务项目并停止；不要猜测项目 ID、切换身份或创建其他反馈。", []);
+    }
+    if (choices.length > 1 && itemRank === undefined) {
+        writeCommandEnvelope({
+            status: "feedback_item_selection_required",
+            result: {
+                ...(order.order_code ? { order_code: order.order_code } : {}),
+                items: choices.map(({ rank, title, subject }) => ({ rank, title, ...(subject ? { subject } : {}) })),
+            },
+            instruction: "用服务名称和主题让用户选择要评价哪一项；不要展示内部 ID。用户选择后，Agent 使用同一订单、评分和留言并加入所选 item rank 自己执行提交。",
+            next: null,
+            recovery: [],
+        }, outputOptions(options));
+        return;
+    }
+    const choice = itemRank === undefined
+        ? choices[0]
+        : choices.find((candidate) => candidate.rank === itemRank);
+    if (!choice) {
+        throw new CommandContractError("feedback_item_invalid", `item rank ${itemRank} is not available for feedback`, "只使用当前订单返回的服务项目编号；不要猜测内部 ID。本次未提交反馈。", []);
+    }
+    const note = formatFeedbackNote({
+        userNote,
+        outcome: order.status,
+        serviceTitle: choice.title,
+        environment: options.environment,
+        ...(options.agentType ? { agentType: options.agentType } : {}),
+    });
+    if (codePointLength(note) > MAX_FEEDBACK_NOTE_CODE_POINTS) {
+        throw new CommandContractError("feedback_note_too_long", `formatted feedback note exceeds ${MAX_FEEDBACK_NOTE_CODE_POINTS} Unicode code points`, "请用户缩短反馈内容；不要截断、改写或拆分提交。本次未提交反馈。", []);
+    }
+    const response = await backend.submitServiceFeedback(normalizedOrderID, {
+        order_item_id: choice.item.order_item_id,
+        rating,
+        note,
+    });
+    writeCommandEnvelope({
+        status: "feedback_submitted",
+        result: {
+            ...(order.order_code ? { order_code: order.order_code } : {}),
+            service_title: choice.title,
+            rating: response.feedback.rating,
+            feedback_status: response.feedback.status,
+        },
+        instruction: "告诉用户反馈已经记录并表示感谢，然后停止。不要承诺回复、处理时间、退款或结果变更。",
+        next: null,
+        recovery: [],
+    }, outputOptions(options));
+}
+export function normalizeFeedbackRating(value) {
+    const normalized = value?.trim().toLowerCase() ?? "";
+    const numeric = normalized.match(/^([1-5])(?:\s*(?:\/\s*5|分|星|stars?))?$/u);
+    if (numeric)
+        return Number(numeric[1]);
+    const chinese = normalized.match(/^([一二三四五])(?:分|星)?$/u)?.[1];
+    if (chinese)
+        return { 一: 1, 二: 2, 三: 3, 四: 4, 五: 5 }[chinese];
+    throw new CommandContractError("feedback_rating_invalid", "--rating must be an explicit score from 1 to 5", "请用户明确给出 1–5 分；不要从好评、差评或情绪推断评分。本次未提交反馈。", []);
+}
+function normalizeItemRank(value) {
+    if (value === undefined)
+        return undefined;
+    const match = value.trim().match(/^#?([1-9]\d*)$/u);
+    if (!match) {
+        throw new CommandContractError("feedback_item_invalid", "--item-rank must be a positive integer", "使用当前订单返回的正整数服务项目编号；本次未提交反馈。", []);
+    }
+    const rank = Number(match[1]);
+    if (!Number.isSafeInteger(rank)) {
+        throw new CommandContractError("feedback_item_invalid", "--item-rank is outside the supported integer range", "使用当前订单返回的服务项目编号；本次未提交反馈。", []);
+    }
+    return rank;
+}
+function feedbackItemChoices(order) {
+    return order.items.flatMap((item, index) => {
+        if (!item.order_item_id?.trim())
+            return [];
+        const subject = feedbackSubject(item);
+        return [{
+                rank: index + 1,
+                item,
+                title: safeLine(item.title) || "未命名服务",
+                ...(subject ? { subject } : {}),
+            }];
+    });
+}
+function feedbackSubject(item) {
+    for (const field of ["company_name_or_credit_no", "company_name", "company", "target", "keyword"]) {
+        const value = item.input?.[field];
+        if (typeof value === "string") {
+            const safe = safeLine(value);
+            if (safe)
+                return safe.slice(0, 160);
+        }
+    }
+    return undefined;
+}
+function normalizeUserNote(value) {
+    return value
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/gu, " ")
+        .trim();
+}
+function formatFeedbackNote(input) {
+    const summary = input.userNote
+        ? `## Summary\n${input.userNote.split("\n").map((line) => `> ${line}`).join("\n")}\n\n`
+        : "";
+    return `${summary}## Context\n` + [
+        "- Source: user-confirmed via agent",
+        `- Outcome: ${safeLine(input.outcome) || "unknown"}`,
+        `- Service: ${safeLine(input.serviceTitle) || "未命名服务"}`,
+        `- Client: @itpay/cli ${CLI_VERSION}`,
+        `- Agent type: ${safeLine(input.agentType ?? "unspecified")}`,
+        `- Environment: ${input.environment}`,
+    ].join("\n");
+}
+function safeLine(value) {
+    return value.replace(/[\r\n\u0000-\u001F\u007F]+/gu, " ").trim();
+}
+function codePointLength(value) {
+    return Array.from(value).length;
+}
+function outputOptions(options) {
+    return {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        ...(options.agentType ? { agentType: options.agentType } : {}),
+    };
+}

package/dist/src/commands/guidance.js

@@ -5,6 +5,12 @@ import { qualifyBackendCommand } from "../state/config.js";
 export function isTerminalServiceExecutionStatus(status) {
     return status === "failed" || status === "refunded" || status === "cancelled";
 }
+export function appendOptionalFeedbackInvitation(instruction, outcome) {
+    const invitation = outcome === "delivered"
+        ? "结果解释完毕后，可以询问用户是否愿意给这次服务 1–5 分和一句可选建议。只有用户明确评分后，Agent 才使用同一订单提交反馈；不要展示命令或内部 ID，同一对话最多询问一次。"
+        : "先完成同一订单的恢复和退款权利解释；处理清楚后，可以询问用户是否愿意给 1–5 分并说明卡壳点。只有用户明确评分后才提交反馈，同一对话最多询问一次。";
+    return `${instruction} ${invitation}`;
+}
 export class CommandContractError extends Error {
     code;
     instruction;

package/dist/src/commands/order.js

@@ -1,5 +1,5 @@
 import { formatMoney } from "../render/output.js";
-import { writeCommandEnvelope } from "./guidance.js";
+import { appendOptionalFeedbackInvitation, writeCommandEnvelope } from "./guidance.js";
 export async function runOrder(backend, orderID, options = {}) {
     const order = await backend.getOrder(orderID);
     const [delivery, refundResponse] = await Promise.all([
@@ -29,7 +29,7 @@ function orderEnvelope(order, delivery, lockedRefund) {
         next = { command: `itpay services next ${delivery.service_execution_id} --json`, reason: "读取交付状态" };
     }
     else if (order.status === "failed") {
-        instruction = "先告诉用户这笔订单没有正常交付，不需要重复付款或重新下单；先检查原订单是否已有退款，再由用户决定是否申请。";
+        instruction = appendOptionalFeedbackInvitation("先告诉用户这笔订单没有正常交付，不需要重复付款或重新下单；先检查原订单是否已有退款，再由用户决定是否申请。", "failed");
         next = { command: `itpay refund list --order ${order.order_id} --json`, reason: "检查同一订单的退款状态" };
     }
     else if (order.status === "refunded") {

package/dist/src/commands/services.js

@@ -8,7 +8,7 @@ import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
 import { buildCheckoutQRPlan } from "./buy.js";
-import { CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
+import { appendOptionalFeedbackInvitation, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
 export async function runServicesStart(backend, serviceID, options = {}) {
     const host = options.host ?? "terminal";
@@ -622,7 +622,16 @@ export async function runServicesList(backend, options = {}) {
     });
 }
 export async function runServicesReadResult(backend, serviceExecutionID, options = {}) {
-    const envelope = grantedResultEnvelope(await backend.getGrantedServiceResult(serviceExecutionID));
+    const response = await backend.getGrantedServiceResult(serviceExecutionID);
+    let orderID;
+    try {
+        const model = await backend.getServiceExecution(serviceExecutionID);
+        orderID = (model.current_delivery ?? model.delivery_bindings.at(-1))?.order_id;
+    }
+    catch {
+        // Feedback context is optional and must never block an authorized result.
+    }
+    const envelope = grantedResultEnvelope(response, orderID);
     writeCommandEnvelope(envelope, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
         ...(options.output ? { output: options.output } : {}),
@@ -669,7 +678,7 @@ function servicesNextEnvelope(model) {
             instruction: execution.status === "refunded"
                 ? "告诉用户这笔服务已经退款并永久结束。Agent 不重放服务步骤、不创建付款页面或尝试读取旧交付。"
                 : paidFailure
-                    ? "告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。"
+                    ? appendOptionalFeedbackInvitation("告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。", "failed")
                     : "告诉用户本次服务已经结束且没有可继续的交付。Agent 不重放服务步骤或创建付款页面。",
             next: null,
             recovery: [
@@ -730,14 +739,21 @@ function servicesNextEnvelope(model) {
             result: {
                 service_execution_id: execution.service_execution_id,
                 ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                ...(delivery?.order_id ? { order_id: delivery.order_id } : {}),
                 delivery_mode: deliveryMode,
                 items,
             },
-            instruction: items.length > 0
-                ? selection
-                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
-                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Graph、safe_payload 或内部 ID。"
-                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。",
+            instruction: delivery?.order_id
+                ? appendOptionalFeedbackInvitation(items.length > 0
+                    ? selection
+                        ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
+                        : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Graph、safe_payload 或内部 ID。"
+                    : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
+                : items.length > 0
+                    ? selection
+                        ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
+                        : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Graph、safe_payload 或内部 ID。"
+                    : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。",
             next: selection ? {
                 command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
                 reason: "仅在用户明确选择后锁定来源候选",
@@ -860,16 +876,19 @@ function serviceDeliveryMode(model) {
 function normalizeGrantStatus(status) {
     return !status || status === "missing" ? "none" : status;
 }
-function grantedResultEnvelope(response) {
+function grantedResultEnvelope(response, orderID) {
     return {
         status: "granted_result_ready",
         result: {
             service_execution_id: response.service_execution_id,
+            ...(orderID ? { order_id: orderID } : {}),
             ...(response.expires_at ? { grant_expires_at: response.expires_at } : {}),
             granted_fields: Object.keys(response.result),
             payload: response.result,
         },
-        instruction: "结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。",
+        instruction: orderID
+            ? appendOptionalFeedbackInvitation("结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。", "delivered")
+            : "结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。",
         next: null,
         recovery: [],
     };

package/dist/src/main.js

@@ -16,6 +16,7 @@ import { runCheckoutPresentation } from "./commands/checkout.js";
 import { runPay } from "./commands/pay.js";
 import { runOrder } from "./commands/order.js";
 import { runListOrders } from "./commands/orders.js";
+import { runFeedbackSubmit } from "./commands/feedback.js";
 import { runCancelRefund, runGetRefund, runListRefunds, runRefund, runWatchRefund } from "./commands/refund.js";
 import { runCartAdd, runCartAddQuoteServer, runCartAddServer, runCartAbandonServer, runCartClear, runCartNext, runCartRemove, runCartRemoveServer, runCartShow, runCartShowServer, } from "./commands/cart.js";
 import { CommandContractError, errorRecoveryActions, printErrorRecovery, writeCommandEnvelope } from "./commands/guidance.js";
@@ -42,6 +43,7 @@ Common human intents:
   Previously purchased item vault list
   Purchase history           orders
   Delivery or refund problem resume the known Order or Refund
+  Rate a purchased service   feedback submit
 
 The Agent runs commands. Ask the human only to choose, authorize, pay, provide
 required contact details, or confirm a refund. Never expose commands or internal IDs.
@@ -961,6 +963,49 @@ program
         });
     }
 });
+const feedback = program.command("feedback").description("Rate one service item from an existing order");
+feedback
+    .command("submit")
+    .description("Submit a human-confirmed rating and optional comment")
+    .option("--order <order_id>")
+    .option("--rating <rating>")
+    .option("--note <text>")
+    .option("--item-rank <rank>")
+    .option("--json", "output JSON instead of terminal text")
+    .action(async (options) => {
+    const config = loadConfig();
+    const jsonOutput = Boolean(options.json);
+    try {
+        await runFeedbackSubmit(newBackendClient(config), options.order, {
+            ...(options.rating !== undefined ? { rating: options.rating } : {}),
+            ...(options.note !== undefined ? { note: options.note } : {}),
+            ...(options.itemRank !== undefined ? { itemRank: options.itemRank } : {}),
+            environment: config.environment,
+            ...(config.agentType ? { agentType: config.agentType } : {}),
+            jsonOutput,
+        });
+    }
+    catch (error) {
+        if (error instanceof HttpTransportError) {
+            reportCLIError(new CommandContractError("feedback_submission_unknown", error.message, "告诉用户反馈是否记录目前无法确认并停止。不要自动重试；只有用户明确要求再次提交时才可更新同一反馈。", []), { jsonOutput, code: "feedback_submission_unknown", instruction: "", recovery: [] });
+            return;
+        }
+        if (error instanceof HttpError && error.status === 404) {
+            reportCLIError(new CommandContractError("feedback_not_available_for_agent", "feedback is not available to this Agent for the selected order", "告诉用户当前 Agent 不能代这笔原订单提交反馈；可以使用官方订单页或原 Local Agent。不要切换身份、Backend、Device 或 MCP/Vault 线路绕过。", []), { jsonOutput, code: "feedback_not_available_for_agent", instruction: "", recovery: [] });
+            return;
+        }
+        if (error instanceof HttpError && error.status >= 400 && error.status < 500) {
+            reportCLIError(new CommandContractError("feedback_rejected", error.message, "告诉用户这次反馈没有被记录；只有用户修正明确的评分或内容后才可再次提交。", []), { jsonOutput, code: "feedback_rejected", instruction: "", recovery: [] });
+            return;
+        }
+        reportCLIError(error, {
+            jsonOutput,
+            code: "feedback_submit_failed",
+            instruction: "告诉用户反馈没有确认记录并停止；不要自动重试、切换身份或影响原订单。",
+            recovery: [],
+        });
+    }
+});
 const refund = program
     .command("refund")
     .enablePositionalOptions()

package/dist/src/state/config.js

@@ -12,7 +12,7 @@ import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
-export const CLI_VERSION = "2.0.32";
+export const CLI_VERSION = "2.0.33";
 export const API_CONTRACT_REVISION = "sha256:95a6077248c820f92511ef6d41635881072ad399c18f347ee282253edb83e55f";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/docs/agent/buyer/orders-refunds.json

@@ -68,6 +68,10 @@
     {
       "condition": "Need the original purchase path",
       "topic": "quickstart"
+    },
+    {
+      "condition": "The original order is handled and the human wants to rate the experience",
+      "topic": "service-feedback"
     }
   ],
   "search_terms": [

package/docs/agent/buyer/quickstart.json

@@ -7,7 +7,7 @@
   "purpose": "Choose the correct first action from the human's words and continue through one authoritative CLI envelope at a time.",
   "when_to_use": [
     "The agent has just installed this CLI version.",
-    "The user asks to buy something, read previous content, inspect orders, or handle a refund."
+    "The user asks to buy something, read previous content, inspect orders, handle a refund, or rate a purchased service."
   ],
   "required_state": {
     "needs": [
@@ -25,6 +25,7 @@
     "previous_content": "Use vault list, optionally with the subject as --query.",
     "purchase_history": "Use orders.",
     "refund_or_paid_problem": "Resume the known Order or Refund before creating anything new.",
+    "service_feedback": "Finish the original order outcome first; after the human explicitly gives a 1-5 rating, use feedback submit.",
     "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay."
   },
   "commands": [{
@@ -74,6 +75,10 @@
       "condition": "Need order or refund recovery",
       "topic": "orders-refunds"
     },
+    {
+      "condition": "Need to rate a purchased service or report an experience",
+      "topic": "service-feedback"
+    },
     {
       "condition": "Need install or identity details",
       "topic": "install-and-setup"
@@ -90,6 +95,8 @@
     "recovery",
     "delivery",
     "refund",
+    "feedback",
+    "rating",
     "target",
     "input"
   ]

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

@@ -0,0 +1,69 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point. Service feedback records a human-confirmed rating for one existing order item; it never replaces delivery recovery, refund policy, or customer care.",
+  "topic": "service-feedback",
+  "title": "Rate A Purchased Service Or Report A Blocker",
+  "purpose": "Help the human finish the original order outcome first, then record an explicit 1-5 rating and optional comment without exposing commands or internal identifiers.",
+  "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 invites optional feedback.",
+    "A paid service failed and its order, delivery, and refund path have already been explained or recovered."
+  ],
+  "intent_routing": {
+    "known_order": "Ask only for a missing 1-5 rating, then run feedback submit yourself.",
+    "unknown_order": "Use orders to show human-readable candidates; never ask the human for an order or item ID.",
+    "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 human-confirmed service feedback",
+      "command": "itpay feedback submit --order <known_order_id> --rating <1-5> [--note <human_words>] --json",
+      "success_signal": "feedback_submitted"
+    }
+  ],
+  "agent_rules": [
+    "The human must explicitly provide a 1-5 rating. Normalize their exact rating to an integer before the command; a written comment is optional and sentiment never implies a score.",
+    "Run every command yourself. Speak to the human only about the service, their rating, whether feedback was recorded, and any original order rights.",
+    "Ask at most once per order in one conversation. If the human declines, ignores the invitation, or already submitted feedback, stop asking.",
+    "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."
+  ],
+  "human_language": {
+    "invitation": "If you would like, tell me a 1-5 rating and one short suggestion, and I can record it for you.",
+    "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 submit without an explicit 1-5 rating.",
+    "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",
+    "review",
+    "stars",
+    "complaint",
+    "blocker",
+    "反馈",
+    "评价",
+    "建议",
+    "体验",
+    "卡住",
+    "投诉",
+    "几分",
+    "五星"
+  ]
+}

package/docs/cli-reference/commands/feedback/index.md

@@ -0,0 +1,29 @@
+# `itpay feedback`
+
+## 命令范围
+
+替用户记录一笔已有订单中某项服务的评分和可选建议。Agent 负责定位订单和项目、
+询问缺失的评分并执行命令；用户不运行命令，也不处理内部 ID。
+
+Feedback 不创建客服工单、不改变订单、交付或退款状态，也不承诺回复时间。
+
+## 子命令
+
+- [`feedback submit`](submit.md)
+
+直接运行 `itpay feedback` 只显示帮助，不访问 Backend、不提交反馈。
+
+## 权限边界
+
+- Local CLI 只能以原 Order Item 对应的 exact Device + Agent Instance 提交；
+- Buyer 可继续在官方订单页用 Buyer Session 提交；
+- MCP 和 Vault 临时读取授权保持只读，不能提交反馈；
+- 无权限时不得切换 Agent Type、Backend、Device 或登录账号绕过。
+
+## Agent 服务口径
+
+- 用户必须明确给出 1–5 分；文字建议可选；
+- 先完成交付、故障恢复和退款权利解释，再邀请反馈；
+- 用户拒绝、忽略或已经反馈后，同一对话不再询问；
+- 成功后只告诉用户反馈已经记录并表示感谢；
+- 不自动上传聊天、Prompt、日志、Token、联系方式或已购内容。

package/docs/cli-reference/commands/feedback/submit.md

@@ -0,0 +1,123 @@
+# `itpay feedback submit`
+
+## 范围与意义
+
+把用户明确给出的评分和可选建议记录到一笔已有 Order 的具体服务项目。CLI 读取
+同一 Order 选择真实 `order_item_id`，再调用现有 Feedback Owner。用户不需要知道
+Order ID、Order Item ID、Device 或 Agent Instance。
+
+## 语法与参数
+
+```bash
+itpay feedback submit \
+  --order <order_id> \
+  --rating <1-5> \
+  [--note <text>] \
+  [--item-rank <positive_integer>] \
+  [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--order <order_id>` | 是 | Agent 从当前订单流程取得，不要求用户提供。 |
+| `--rating <1-5>` | 是 | 用户明确给出的 1–5 评分；CLI 归一常见精确写法。 |
+| `--note <text>` | 否 | 用户明确表达的建议或卡壳点。 |
+| `--item-rank <n>` | 多项目订单条件必填 | 当前 Order items 的 1-based rank。 |
+| `--json` | 否 | 输出一个稳定 JSON envelope；Agent 应使用。 |
+
+rating、rank 和 note 长度在任何 Feedback POST 前验证。rating 接受 `5`、`5/5`、
+`5分`、`5星`、`5 stars` 和中文 `一` 至 `五` 的精确写法，统一保存为整数；
+`2.5`、`6`、`很好` 等含糊或越界值拒绝，不能猜测。完整结构化 note 最长 2000
+Unicode code points；超长时不截断用户原话，而是请用户缩短。
+
+## 项目选择
+
+```text
+0 个可反馈 item -> feedback_unavailable，不提交
+1 个可反馈 item -> 自动选择
+多个 item 且无 rank -> feedback_item_selection_required，不提交
+rank 无效 -> feedback_item_invalid，不提交
+```
+
+多项目选择只展示 rank、服务标题和安全主题，不展示 `order_item_id`。该状态固定
+`next:null`，避免把用户 note 拼进 shell command。用户选定后，Agent 使用同一
+订单、评分和留言并加入 `--item-rank` 自己执行。
+
+## 保存格式
+
+Backend 继续保存现有 `rating` 和 `note`。CLI 的 note 是可直接在 Admin 阅读的短
+Markdown：
+
+```markdown
+## Summary
+> 支付后等了很久才拿到结果。
+
+## Context
+- Source: user-confirmed via agent
+- Outcome: delivered
+- Service: 企业综合报告
+- Client: @itpay/cli <version>
+- Agent type: workbuddy
+- Environment: development
+```
+
+只写用户明确内容和已知安全上下文；禁止 Token、Session、联系方式、内部身份、
+Provider 响应、Vault payload、完整命令输出、stack trace 或环境变量。
+
+## 成功 JSON
+
+```json
+{
+  "status": "feedback_submitted",
+  "result": {
+    "order_code": "IP-…",
+    "service_title": "企业综合报告",
+    "rating": 5,
+    "feedback_status": "new"
+  },
+  "instruction": "告诉用户反馈已经记录并表示感谢，然后停止。不要承诺回复、处理时间、退款或结果变更。",
+  "next": null,
+  "recovery": []
+}
+```
+
+正常结果不返回 `feedback_id`、`order_item_id`、Device、Agent Instance 或 Buyer。
+同一 submitter 再次由用户明确提交会更新现有记录并重新进入 `new`，不是创建第二条。
+
+## 多项目 JSON
+
+```json
+{
+  "status": "feedback_item_selection_required",
+  "result": {
+    "order_code": "IP-…",
+    "items": [
+      { "rank": 1, "title": "企业名称建议", "subject": "京东" },
+      { "rank": 2, "title": "企业综合报告", "subject": "北京京东世纪贸易有限公司" }
+    ]
+  },
+  "instruction": "用服务名称和主题让用户选择要评价哪一项；不要展示内部 ID。用户选择后，Agent 使用同一订单、评分和留言并加入所选 item rank 自己执行提交。",
+  "next": null,
+  "recovery": []
+}
+```
+
+## 错误合同
+
+| 状态/错误 | 行为 |
+| --- | --- |
+| `feedback_rating_invalid` | 询问明确的 1–5 评分；没有 HTTP，不猜测。 |
+| `feedback_note_too_long` | 请用户缩短；不截断、不提交。 |
+| `feedback_unavailable` | 该 Order 当前没有可反馈项目；不猜 ID。 |
+| `feedback_item_invalid` | 重新使用返回的项目 rank；不提交。 |
+| `feedback_not_available_for_agent` | 当前 Agent 不能代该订单提交；指向官方订单页或原 Local Agent，不切身份绕过。 |
+| `feedback_rejected` | 输入未被记录；只有用户修正明确输入后才重试。 |
+| `feedback_submission_unknown` | 无法确认是否记录；停止自动重试，只有用户明确要求后才再次提交。 |
+
+Feedback POST 不做自动 transport retry。虽然 Backend 使用 upsert，重放仍会更新记录
+并追加事件，CLI 不能把它当成无副作用查询。
+
+## Agent Type / Host
+
+所有 Local Agent Type 使用相同命令、Device Authority 和 JSON。Host 不改变权限。
+Remote MCP 保持只读且没有 Feedback tool。

package/docs/cli-reference/index.md

@@ -63,6 +63,11 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay refund watch`](commands/refund/watch.md)
   - [`itpay refund cancel`](commands/refund/cancel.md)
 
+### 服务反馈
+
+- [`itpay feedback`](commands/feedback/index.md)
+  - [`itpay feedback submit`](commands/feedback/submit.md)
+
 ### 跨平台已购内容
 
 - [`itpay vault`](commands/vault/index.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.32",
+  "version": "2.0.33",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {

package/skills/itpay/SKILL.md

@@ -3,7 +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. Seller workflows are not yet available.
+  and track a refund, or rate a purchased service. Seller workflows are not
+  yet available.
 ---
 
 # ItPay
@@ -21,6 +22,7 @@ for the human; never ask them to run commands or learn internal concepts.
 | Find a previous result by subject | `itpay vault list --query <subject> --json` |
 | Inspect purchase history | `itpay orders --json` |
 | Track or request a refund | Resume the known Order or Refund returned by ItPay |
+| Rate a purchased service or report a blocker | Resume the known Order; submit only after the human gives a 1–5 rating |
 
 Words such as "my", "previous", "bought", "history", "report", "以前",
 "之前", "买过", "查过", "历史", and "已购内容" usually mean an existing
@@ -59,6 +61,9 @@ The current Backend response always overrides general documentation.
   If delivery fails, recover that same order before discussing a refund.
 - Explain refund eligibility as a policy route, not a promise. Only ItPay's
   final refund state proves success.
+- Finish delivery or failure recovery before inviting feedback. Ask at most
+  once per order; require an explicit 1–5 rating, run the feedback command
+  yourself, and promise only that the feedback was recorded.
 - Describe Vault/artifact/grant as "已购内容", the actual report title, or
   "临时只读授权". Do not expose Provider, Buyer, Device, Execution, capability,
   token, or internal identifiers.
@@ -90,3 +95,5 @@ The current Backend response always overrides general documentation.
   separate attempt.
 - Never claim a handoff, payment, authorization, delivery, or refund succeeded
   without the corresponding ItPay state.
+- Never infer a rating or silently upload chat, prompts, logs, contact details,
+  purchased content, credentials, or internal identifiers as feedback.