@harrylabsj/kiwi 0.7.21 → 0.8.0

package/dist/agent/merchant/merchant-presentations.js

@@ -0,0 +1,184 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ */
+import { sanitizeModelText } from "../context/fencing.js";
+import { publicCandidatePreview } from "./merchant-enrichment.js";
+import { PresentationRegistry } from "../presentation/registry.js";
+const MAX_PERIOD = /^(?:[1-9]|[1-8][0-9]|90)d$/;
+function objectInput(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("presentation input must be an object");
+    }
+    return value;
+}
+function optionalText(value, field, maxChars) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length > maxChars)
+        throw new Error(`${field} must be a string of at most ${maxChars} characters`);
+    return sanitizeModelText(value, { maxChars });
+}
+function requireText(value, field, maxChars) {
+    const text = optionalText(value, field, maxChars);
+    if (text === undefined || text === "")
+        throw new Error(`${field} must be a non-empty string`);
+    return text;
+}
+function intelligence(context) {
+    if (context.intelligence === undefined)
+        throw new Error("merchant intelligence is unavailable");
+    return context.intelligence;
+}
+function boundedLimit(value, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 50) {
+        throw new Error("limit must be an integer between 1 and 50");
+    }
+    return value;
+}
+function parseDigest(value) {
+    const v = objectInput(value);
+    const period = optionalText(v.period, "period", 20);
+    if (period !== undefined && !MAX_PERIOD.test(period))
+        throw new Error("period must use 1d–90d syntax");
+    return { ...(optionalText(v.title, "title", 80) ? { title: optionalText(v.title, "title", 80) } : {}), ...(period ? { period } : {}) };
+}
+function parseMetrics(value) {
+    const v = objectInput(value);
+    const metric = requireText(v.metric, "metric", 80);
+    const period = optionalText(v.period, "period", 20);
+    if (period !== undefined && !MAX_PERIOD.test(period))
+        throw new Error("period must use 1d–90d syntax");
+    const granularity = v.granularity === undefined ? "day" : v.granularity;
+    if (granularity !== "day" && granularity !== "week" && granularity !== "month")
+        throw new Error("invalid granularity");
+    return { metric, ...(period ? { period } : {}), granularity };
+}
+function parseCatalog(value) {
+    return { limit: boundedLimit(objectInput(value).limit, 20) };
+}
+function parseNegotiations(value) {
+    const v = objectInput(value);
+    const status = v.status === undefined ? "all" : v.status;
+    if (status !== "active" && status !== "agreement" && status !== "all")
+        throw new Error("invalid negotiation status");
+    return { status, limit: boundedLimit(v.limit, 20) };
+}
+function parseHumanReview(value) {
+    return { limit: boundedLimit(objectInput(value).limit, 20) };
+}
+function parseChangePreview(value) {
+    const v = objectInput(value);
+    return {
+        candidate_id: requireText(v.candidate_id, "candidate_id", 200),
+        ...(optionalText(v.headline, "headline", 120) ? { headline: optionalText(v.headline, "headline", 120) } : {}),
+        ...(optionalText(v.note, "note", 200) ? { note: optionalText(v.note, "note", 200) } : {}),
+    };
+}
+function parseSuggestions(value) {
+    const raw = objectInput(value).suggestions;
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > 4)
+        throw new Error("suggestions must contain 1 to 4 items");
+    return { suggestions: raw.map((item) => requireText(item, "suggestion", 80)) };
+}
+function component(input) {
+    return input;
+}
+export function createMerchantPresentationRegistry() {
+    const registry = new PresentationRegistry();
+    registry
+        .register(component({
+        toolName: "present_merchant_digest",
+        component: "merchant_digest",
+        label: "展示经营摘要",
+        description: "展示商家经营摘要、告警、A2A 磋商和待审批事项。真实数据由服务端读取和补全。",
+        inputSchema: { type: "object", properties: { title: { type: "string", maxLength: 80 }, period: { type: "string", pattern: "^(?:[1-9]|[1-8][0-9]|90)d$" } }, additionalProperties: false },
+        validate: parseDigest,
+        enrich: async (input, context) => {
+            const backend = intelligence(context);
+            const max = context.profile.merchant_experience?.max_presentation_items ?? 12;
+            const [snapshot, negotiations, pending] = await Promise.all([
+                backend.getBusinessSnapshot({ merchant_id: context.principalId, ...(input.period ? { period: input.period } : {}) }),
+                backend.getNegotiationDigest({ merchant_id: context.principalId, status: "active", limit: max }),
+                backend.getPendingActions(),
+            ]);
+            return { title: input.title ?? "经营摘要", snapshot, negotiations: negotiations.slice(0, max), pending_actions: pending.slice(0, max) };
+        },
+    }))
+        .register(component({
+        toolName: "present_metrics",
+        component: "metrics",
+        label: "展示经营指标",
+        description: "展示一项按日、周或月聚合的经营指标；数据和限制说明由服务端补全。",
+        inputSchema: { type: "object", properties: { metric: { type: "string", maxLength: 80 }, period: { type: "string", pattern: "^(?:[1-9]|[1-8][0-9]|90)d$" }, granularity: { type: "string", enum: ["day", "week", "month"] } }, required: ["metric"], additionalProperties: false },
+        validate: parseMetrics,
+        enrich: (input, context) => intelligence(context).queryMetric({ merchant_id: context.principalId, ...input }),
+    }))
+        .register(component({
+        toolName: "present_catalog",
+        component: "catalog",
+        label: "展示商品目录",
+        description: "展示商家商品目录及库存健康摘要；真实商品数据由服务端读取和补全。",
+        inputSchema: { type: "object", properties: { limit: { type: "integer", minimum: 1, maximum: 50 } }, additionalProperties: false },
+        validate: parseCatalog,
+        enrich: async (input, context) => {
+            const [products, health] = await Promise.all([
+                context.merchantClient.listProducts(context.principalId),
+                intelligence(context).getCatalogHealth({ merchant_id: context.principalId }),
+            ]);
+            return { health, products: products.slice(0, input.limit) };
+        },
+    }))
+        .register(component({
+        toolName: "present_negotiations",
+        component: "negotiations",
+        label: "展示磋商列表",
+        description: "展示当前 A2A 磋商列表；状态、报价和时间由 Ledger 服务端补全。",
+        inputSchema: { type: "object", properties: { status: { type: "string", enum: ["active", "agreement", "all"] }, limit: { type: "integer", minimum: 1, maximum: 50 } }, additionalProperties: false },
+        validate: parseNegotiations,
+        enrich: (input, context) => intelligence(context).getNegotiationDigest({ merchant_id: context.principalId, ...input }),
+    }))
+        .register(component({
+        toolName: "present_human_review",
+        component: "human_review",
+        label: "展示人工审核",
+        description: "展示需要人工处理的事项；审核原因和实体由服务端读取和补全。",
+        inputSchema: { type: "object", properties: { limit: { type: "integer", minimum: 1, maximum: 50 } }, additionalProperties: false },
+        validate: parseHumanReview,
+        enrich: async (input, context) => ({ reviews: (await context.merchantClient.getHumanReviewQueue(context.principalId)).slice(0, input.limit) }),
+    }))
+        .register(component({
+        toolName: "present_change_preview",
+        component: "change_preview",
+        label: "展示变更预览",
+        description: "展示一个 WriteApprovalCandidate 的前后差异。展示不会批准或执行变更。",
+        inputSchema: { type: "object", properties: { candidate_id: { type: "string" }, headline: { type: "string", maxLength: 120 }, note: { type: "string", maxLength: 200 } }, required: ["candidate_id"], additionalProperties: false },
+        validate: parseChangePreview,
+        enrich: async (input, context) => {
+            const preview = context.intelligence === undefined
+                ? publicCandidatePreview(context.approvals.get(input.candidate_id))
+                : await context.intelligence.getCandidatePreview({
+                    principal_id: context.principalId,
+                    candidate_id: input.candidate_id,
+                });
+            if (preview === undefined)
+                throw new Error("未找到当前 principal 的候选操作");
+            return { ...preview, headline: input.headline ?? "变更预览", note: input.note ?? "" };
+        },
+    }))
+        .register(component({
+        toolName: "present_suggestions",
+        component: "suggestions",
+        label: "展示下一步建议",
+        description: "展示 1–4 个下一步建议。建议只影响 UI，不改变权限或业务状态。",
+        inputSchema: { type: "object", properties: { suggestions: { type: "array", minItems: 1, maxItems: 4, items: { type: "string", maxLength: 80 } } }, required: ["suggestions"], additionalProperties: false },
+        validate: parseSuggestions,
+        enrich: async (input) => ({ suggestions: input.suggestions }),
+    }));
+    return registry;
+}
+//# sourceMappingURL=merchant-presentations.js.map

package/dist/agent/merchant/merchant-presentations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-presentations.js","sourceRoot":"","sources":["../../../src/agent/merchant/merchant-presentations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,MAAM,UAAU,GAAG,4BAA4B,CAAC;AAEhD,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,KAAa,EAAE,QAAgB;IACnE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,gCAAgC,QAAQ,aAAa,CAAC,CAAC;IACzI,OAAO,iBAAiB,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,KAAa,EAAE,QAAgB;IAClE,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,6BAA6B,CAAC,CAAC;IAC9F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,OAA4B;IAChD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAChG,OAAO,OAAO,CAAC,YAAY,CAAC;AAC9B,CAAC;AAUD,SAAS,YAAY,CAAC,KAAc,EAAE,YAAoB;IACxD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACvG,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACzI,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACvG,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IACxE,IAAI,WAAW,KAAK,KAAK,IAAI,WAAW,KAAK,MAAM,IAAI,WAAW,KAAK,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACvH,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;AAChE,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACzD,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACrH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO;QACL,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,YAAY,EAAE,cAAc,EAAE,GAAG,CAAC;QAC9D,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7G,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1F,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACtH,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,SAAS,SAAS,CAAO,KAAkC;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,kCAAkC;IAChD,MAAM,QAAQ,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC5C,QAAQ;SACL,QAAQ,CAAC,SAAS,CAAuB;QACxC,QAAQ,EAAE,yBAAyB;QACnC,SAAS,EAAE,iBAAiB;QAC5B,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,yCAAyC;QACtD,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE;QACzL,QAAQ,EAAE,WAAW;QACrB,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC/B,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE,sBAAsB,IAAI,EAAE,CAAC;YAC9E,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAC1D,OAAO,CAAC,mBAAmB,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpH,OAAO,CAAC,oBAAoB,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;gBAChG,OAAO,CAAC,iBAAiB,EAAE;aAC5B,CAAC,CAAC;YACH,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACtI,CAAC;KACF,CAAC,CAAC;SACF,QAAQ,CAAC,SAAS,CAAwB;QACzC,QAAQ,EAAE,iBAAiB;QAC3B,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,kCAAkC;QAC/C,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE;QACjR,QAAQ,EAAE,YAAY;QACtB,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,GAAG,KAAK,EAAE,CAAC;KAC9G,CAAC,CAAC;SACF,QAAQ,CAAC,SAAS,CAAwB;QACzC,QAAQ,EAAE,iBAAiB;QAC3B,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,kCAAkC;QAC/C,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE;QACjI,QAAQ,EAAE,YAAY;QACtB,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC/B,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAC3C,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC;gBACxD,YAAY,CAAC,OAAO,CAAC,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;aAC7E,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,CAAC;KACF,CAAC,CAAC;SACF,QAAQ,CAAC,SAAS,CAA6B;QAC9C,QAAQ,EAAE,sBAAsB;QAChC,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,uCAAuC;QACpD,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE;QACnM,QAAQ,EAAE,iBAAiB;QAC3B,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,GAAG,KAAK,EAAE,CAAC;KACvH,CAAC,CAAC;SACF,QAAQ,CAAC,SAAS,CAA4B;QAC7C,QAAQ,EAAE,sBAAsB;QAChC,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,+BAA+B;QAC5C,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE;QACjI,QAAQ,EAAE,gBAAgB;QAC1B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,OAAO,CAAC,cAAc,CAAC,mBAAmB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;KAC/I,CAAC,CAAC;SACF,QAAQ,CAAC,SAAS,CAA8B;QAC/C,QAAQ,EAAE,wBAAwB;QAClC,SAAS,EAAE,gBAAgB;QAC3B,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,gDAAgD;QAC7D,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,cAAc,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE;QAClO,QAAQ,EAAE,kBAAkB;QAC5B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC/B,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,KAAK,SAAS;gBAChD,CAAC,CAAC,sBAAsB,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;gBACnE,CAAC,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,mBAAmB,CAAC;oBAC7C,YAAY,EAAE,OAAO,CAAC,WAAW;oBACjC,YAAY,EAAE,KAAK,CAAC,YAAY;iBACjC,CAAC,CAAC;YACP,IAAI,OAAO,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;YACpE,OAAO,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;QACpF,CAAC;KACF,CAAC,CAAC;SACF,QAAQ,CAAC,SAAS,CAA4B;QAC7C,QAAQ,EAAE,qBAAqB;QAC/B,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,oCAAoC;QACjD,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,aAAa,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE;QAC3M,QAAQ,EAAE,gBAAgB;QAC1B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;KAC9D,CAAC,CAAC,CAAC;IACN,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/agent/merchant/merchant-tools.d.ts

@@ -30,6 +30,7 @@
  */
 import type { AgentHarnessTool } from "@earendil-works/pi-agent-core";
 import type { AgentProfile } from "../../config/profile.js";
+import type { AgentHostEventType } from "../host/events.js";
 import type { CommerceDataSource } from "../../commerce/data-source.js";
 import type { CommerceClient } from "../../commerce/types.js";
 import type { AgentMode } from "../mode.js";
@@ -37,6 +38,7 @@ import type { WriteApprovalCandidateStore } from "./action-candidate.js";
 import type { CredentialBroker } from "./credential-broker.js";
 import type { MerchantClient } from "./types.js";
 import type { WriteGateDeps, WriteGateResult } from "../write-gate.js";
+import type { MerchantIntelligenceBackend } from "./intelligence/backend.js";
 type Tool = AgentHarnessTool<undefined>;
 export interface MerchantToolDeps {
     profile: AgentProfile;
@@ -72,6 +74,12 @@ export interface MerchantToolDeps {
     /** 商家 A2A 节点 ledger 目录（`<dataDir>/a2a/ledger`）；提供时挂载
      *  `list_a2a_negotiations` 工具，让运营者查看真实发生的 A2A 磋商记录。 */
     a2aLedgerDir?: string;
+    /** Optional commerce-agents-style merchant application layer. */
+    intelligence?: MerchantIntelligenceBackend;
+    /** Optional host event projection; business state never depends on it. */
+    emitEvent?: (type: AgentHostEventType, data: unknown) => Promise<void>;
+    /** Process-bound principal id used by server enrichment. */
+    principalId?: string;
 }
 export declare function buildMerchantTools(deps: MerchantToolDeps): Tool[];
 export type { WriteGateResult };

package/dist/agent/merchant/merchant-tools.js

@@ -13,12 +13,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { fenceModelPayload } from "../context/fencing.js";
 import { LedgerStore } from "../../negotiation/ledger/index.js";
 import { TERMINAL_PHASES } from "../../negotiation/state/phase.js";
 import { buildNegotiationChatTools, writeGateText } from "../negotiation-chat.js";
 import { requireScopeCredential } from "./credential-broker.js";
 import { MerchantClientError } from "./types.js";
 import { routeWriteCandidate } from "../write-gate.js";
+import { createMerchantPresentationRegistry } from "./merchant-presentations.js";
+import { runPresentation } from "../presentation/runner.js";
 function textResult(text, details) {
     return { content: [{ type: "text", text }], details };
 }
@@ -37,6 +40,13 @@ function errorText(err) {
 function optString(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
+function experienceEnabled(profile, capability) {
+    const config = profile.merchant_experience;
+    return config?.enabled === true && config[capability] !== false;
+}
+function experienceMaxChars(profile) {
+    return profile.merchant_experience?.max_external_context_chars ?? 12_000;
+}
 function parseProductInput(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new MerchantClientError("validation", "product 必须是对象");
@@ -152,7 +162,7 @@ export function buildMerchantTools(deps) {
                         stock: p.stock ?? null,
                         paused: false,
                     }));
-                    return textResult(rows.length === 0 ? "目录为空。" : JSON.stringify(rows), {
+                    return textResult(rows.length === 0 ? "目录为空。" : fenceModelPayload("merchant_api", rows, { maxChars: experienceMaxChars(profile) }), {
                         count: rows.length,
                         source: "data-source",
                     });
@@ -165,7 +175,7 @@ export function buildMerchantTools(deps) {
                     stock: p.stock,
                     paused: p.paused,
                 }));
-                return textResult(rows.length === 0 ? "目录为空。" : JSON.stringify(rows), { count: rows.length });
+                return textResult(rows.length === 0 ? "目录为空。" : fenceModelPayload("merchant_api", rows, { maxChars: experienceMaxChars(profile) }), { count: rows.length });
             }
             catch (err) {
                 return textResult(errorText(err));
@@ -186,7 +196,7 @@ export function buildMerchantTools(deps) {
             try {
                 const { sku } = params;
                 const product = await merchantClient.getProduct(sku);
-                return textResult(JSON.stringify(productPreconditions(product)));
+                return textResult(fenceModelPayload("merchant_api", productPreconditions(product), { maxChars: experienceMaxChars(profile) }));
             }
             catch (err) {
                 return textResult(errorText(err));
@@ -207,7 +217,7 @@ export function buildMerchantTools(deps) {
             try {
                 const { sku } = params;
                 const snapshot = await merchantClient.getInventorySnapshot(sku);
-                return textResult(JSON.stringify(snapshot));
+                return textResult(fenceModelPayload("merchant_api", snapshot, { maxChars: experienceMaxChars(profile) }));
             }
             catch (err) {
                 return textResult(errorText(err));
@@ -266,7 +276,10 @@ export function buildMerchantTools(deps) {
             rows.sort((a, b) => (a.at > b.at ? -1 : a.at < b.at ? 1 : 0));
             if (rows.length === 0)
                 return textResult("当前没有进行中的磋商。", { count: 0 });
-            return textResult(`共 ${rows.length} 笔进行中磋商：\n${rows.map((r) => r.line).join("\n")}`, {
+            return textResult(fenceModelPayload("a2a_message", {
+                total: rows.length,
+                items: rows.map((r) => r.line),
+            }, { maxChars: experienceMaxChars(profile) }), {
                 count: rows.length,
             });
         },
@@ -285,9 +298,13 @@ export function buildMerchantTools(deps) {
                 const reviews = await merchantClient.getHumanReviewQueue(ownerId);
                 if (reviews.length === 0)
                     return textResult("人工处理队列为空。");
-                return textResult(reviews
-                    .map((r) => `· #${String(r.review_id)} ${r.sku} [${r.severity}] ${r.reason}（${r.conversation_id}）`)
-                    .join("\n"), { count: reviews.length });
+                return textResult(fenceModelPayload("human_review", reviews.map((r) => ({
+                    review_id: r.review_id,
+                    conversation_id: r.conversation_id,
+                    sku: r.sku,
+                    severity: r.severity,
+                    reason: r.reason,
+                })), { maxChars: experienceMaxChars(profile) }), { count: reviews.length });
             }
             catch (err) {
                 return textResult(errorText(err));
@@ -572,6 +589,184 @@ export function buildMerchantTools(deps) {
             }
         },
     };
+    const experienceTools = [];
+    if (experienceEnabled(profile, "intelligence") && deps.intelligence !== undefined) {
+        const intelligence = deps.intelligence;
+        const getBusinessSnapshot = {
+            name: "get_business_snapshot",
+            label: "读取经营摘要",
+            description: "读取当前商家经营摘要、咨询/磋商和待处理事项。只读；指标由服务端计算并注明数据限制。",
+            parameters: {
+                type: "object",
+                properties: {
+                    period: {
+                        type: "string",
+                        pattern: "^(?:[1-9]|[1-8][0-9]|90)d$",
+                        description: "UTC 统计窗口，1d 到 90d，例如 7d、14d、30d",
+                    },
+                },
+                additionalProperties: false,
+            },
+            execute: async (_id, params) => {
+                try {
+                    const period = optString(params.period);
+                    const snapshot = await intelligence.getBusinessSnapshot({
+                        merchant_id: ownerId,
+                        ...(period === undefined ? {} : { period }),
+                    });
+                    return textResult(fenceModelPayload("metric", snapshot, { maxChars: experienceMaxChars(profile) }), {
+                        status: "ok",
+                        metric: "business_snapshot",
+                    });
+                }
+                catch (err) {
+                    return textResult(errorText(err));
+                }
+            },
+        };
+        const queryMetric = {
+            name: "query_merchant_metric",
+            label: "读取经营指标",
+            description: "读取一项按日/周/月聚合的商家指标。不可得的指标返回明确说明，不用零值代替。",
+            parameters: {
+                type: "object",
+                properties: {
+                    metric: { type: "string", description: "指标名，例如 contact_events、negotiations" },
+                    period: {
+                        type: "string",
+                        pattern: "^(?:[1-9]|[1-8][0-9]|90)d$",
+                        description: "UTC 统计窗口，1d 到 90d，例如 7d、14d、30d",
+                    },
+                    granularity: { type: "string", enum: ["day", "week", "month"] },
+                },
+                required: ["metric"],
+                additionalProperties: false,
+            },
+            execute: async (_id, params) => {
+                try {
+                    const p = params;
+                    const metric = optString(p.metric);
+                    if (metric === undefined)
+                        return textResult("metric 必须是非空字符串。");
+                    const granularity = p.granularity === "week" || p.granularity === "month" ? p.granularity : "day";
+                    const series = await intelligence.queryMetric({
+                        merchant_id: ownerId,
+                        metric,
+                        granularity,
+                        ...(optString(p.period) === undefined ? {} : { period: optString(p.period) }),
+                    });
+                    return textResult(fenceModelPayload("metric", series, { maxChars: experienceMaxChars(profile) }), {
+                        status: "ok",
+                        metric,
+                    });
+                }
+                catch (err) {
+                    return textResult(errorText(err));
+                }
+            },
+        };
+        const getNegotiationDigest = {
+            name: "get_negotiation_digest",
+            label: "读取磋商摘要",
+            description: "读取商家 A2A 磋商摘要。返回当前 phase、公开报价和是否需要人工；只读。",
+            parameters: {
+                type: "object",
+                properties: {
+                    status: { type: "string", enum: ["active", "agreement", "all"] },
+                    limit: { type: "integer", minimum: 1, maximum: 100 },
+                },
+                additionalProperties: false,
+            },
+            execute: async (_id, params) => {
+                try {
+                    const p = params;
+                    const status = p.status === "active" || p.status === "agreement" ? p.status : "all";
+                    const rawLimit = typeof p.limit === "number" && Number.isFinite(p.limit) ? Math.trunc(p.limit) : 20;
+                    const rows = await intelligence.getNegotiationDigest({
+                        merchant_id: ownerId,
+                        status,
+                        limit: Math.max(1, Math.min(100, rawLimit)),
+                    });
+                    return textResult(fenceModelPayload("a2a_message", rows, { maxChars: experienceMaxChars(profile) }), {
+                        status: "ok",
+                        count: rows.length,
+                    });
+                }
+                catch (err) {
+                    return textResult(errorText(err));
+                }
+            },
+        };
+        const getCatalogHealth = {
+            name: "get_catalog_health",
+            label: "读取目录健康度",
+            description: "读取商品总量、上下架状态和缺货数量；精确库存不可得时返回 null 及限制说明。",
+            parameters: { type: "object", properties: {}, additionalProperties: false },
+            execute: async () => {
+                try {
+                    const health = await intelligence.getCatalogHealth({ merchant_id: ownerId });
+                    return textResult(fenceModelPayload("merchant_api", health, { maxChars: experienceMaxChars(profile) }), {
+                        status: "ok",
+                    });
+                }
+                catch (err) {
+                    return textResult(errorText(err));
+                }
+            },
+        };
+        const getPendingActions = {
+            name: "get_pending_actions",
+            label: "读取待审批操作",
+            description: "读取当前 principal 的待审批写操作。返回候选元数据，不返回私有阈值或凭据。",
+            parameters: { type: "object", properties: {}, additionalProperties: false },
+            execute: async () => {
+                try {
+                    const rows = await intelligence.getPendingActions();
+                    return textResult(fenceModelPayload("merchant_api", rows, { maxChars: experienceMaxChars(profile) }), {
+                        status: "ok",
+                        count: rows.length,
+                    });
+                }
+                catch (err) {
+                    return textResult(errorText(err));
+                }
+            },
+        };
+        experienceTools.push(getBusinessSnapshot, queryMetric, getCatalogHealth, getNegotiationDigest, getPendingActions);
+    }
+    if (experienceEnabled(profile, "presentation") && deps.emitEvent !== undefined) {
+        const registry = createMerchantPresentationRegistry();
+        const emitUi = async (component, payload) => {
+            await deps.emitEvent?.("ui", { component, payload });
+        };
+        const presentationContext = {
+            profile,
+            principalId: deps.principalId ?? ownerId,
+            merchantClient,
+            approvals,
+            ...(deps.intelligence !== undefined ? { intelligence: deps.intelligence } : {}),
+        };
+        for (const component of registry.list()) {
+            const presentationTool = {
+                name: component.toolName,
+                label: component.label,
+                description: component.description,
+                parameters: component.inputSchema,
+                execute: async (_id, params) => {
+                    try {
+                        const result = await runPresentation(registry, component.toolName, params, presentationContext, emitUi);
+                        return textResult(component.toolName === "present_change_preview"
+                            ? "已展示变更预览；尚未批准或执行。"
+                            : `已展示${component.label.replace(/^展示/, "")}。`, { component: result.component });
+                    }
+                    catch (err) {
+                        return textResult(errorText(err));
+                    }
+                },
+            };
+            experienceTools.push(presentationTool);
+        }
+    }
     const negotiationTools = deps.commerceClient !== undefined
         ? buildNegotiationChatTools({
             profile,
@@ -658,7 +853,10 @@ export function buildMerchantTools(deps) {
             const recent = rows.slice(0, limit);
             if (recent.length === 0)
                 return textResult("暂无 A2A 磋商记录。", { count: 0 });
-            return textResult(`共 ${rows.length} 笔 A2A 磋商（最近 ${recent.length} 笔）：\n${recent.map((r) => r.line).join("\n")}`, {
+            return textResult(fenceModelPayload("a2a_message", {
+                total: rows.length,
+                items: recent.map((r) => r.line),
+            }, { maxChars: experienceMaxChars(profile) }), {
                 count: recent.length,
             });
         },
@@ -670,6 +868,7 @@ export function buildMerchantTools(deps) {
         listConsultations,
         humanReviewQueue,
         viewPrivateThresholds,
+        ...experienceTools,
         ...negotiationTools,
         createProduct,
         updateProduct,