@dsh-ft/dsh-fft-ftshare 0.0.0-stage → 0.4.0

package/lib/errors.js

@@ -0,0 +1,271 @@
+/**
+ * 上游失败的观测与四态归一的**薄**层。
+ *
+ * 只做四件事：抄事实、判 HTTP 语义、留现场、算指纹。**不解释上游**：不维护错误码表，
+ * 不按中文文案猜「配额/权限/凭据」，不编造 remedy。上游改名、改文案、加码，这里一行
+ * 都不用改。
+ *
+ * 判定只剩两条 HTTP 语义（稳定、不会随上游文案变）：
+ *
+ * - `401` / `403` → `denied`（面板遮罩要用）；
+ * - 其余 → `failed`。
+ *
+ * `empty` 不在这里判定：它由成功载荷的**正向证据**决定（见 `./index.ts` 的
+ * `observePayload`）。「成功信封里带权限标记」是载荷事实，由
+ * {@link permissionNoticeFromPayload} 识别，同样不是文案猜测。
+ * @module @dsh-ft/dsh-fft-ftshare/errors
+ */
+import { FTSHARE_UPGRADE_URL } from './contract.js';
+/** 原始报文的上限；线上真实报文 p99 约 220 B，2 KB 只为兜住 HTML 错误页。 */
+const RAW_MAX = 2048;
+/** 展示文案（notice.message）的上限：原文很短，超长只可能是 HTML 错误页。 */
+const NOTICE_TEXT_MAX = 1000;
+/** 指纹前归一文案的长度上限，避免超长 HTML 撑爆聚合键。 */
+const FINGERPRINT_TEXT_MAX = 512;
+/** 传输层错误名：Node/DOM 的超时与取消。 */
+const ABORT_NAMES = new Set(['AbortError', 'TimeoutError']);
+/** Node 网络错误码：原样出现在 `Error.code` 上。 */
+const NETWORK_CODES = new Set([
+    'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE',
+    'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT',
+]);
+/** 判断一个值是不是可当对象读的记录。 */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 读一个非空字符串；其余一律 undefined。 */
+export function asText(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** 读一个非空字符串或数字码（上游的 `upstream_code` 是数字）；其余一律 undefined。 */
+function asCode(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? String(value) : asText(value);
+}
+/** 读一个 100—599 的 HTTP 状态；其余一律 undefined。 */
+function asStatus(value) {
+    const numeric = typeof value === 'number' ? value : typeof value === 'string' && /^\d{3}$/u.test(value.trim()) ? Number(value) : undefined;
+    return numeric !== undefined && numeric >= 100 && numeric <= 599 ? numeric : undefined;
+}
+/** 不依赖 `node:crypto` 的稳定指纹：FNV-1a 64 位，十六进制 16 位。 */
+export function hashText(text) {
+    let hash = 0xcbf29ce484222325n;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= BigInt(text.charCodeAt(index));
+        hash = (hash * 0x100000001b3n) & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/**
+ * 失败指纹：同工具、同状态、同码、同归一文案的失败聚合用。
+ *
+ * 文案里的数字会归一成 `#`，否则「请等待 N 小时」会让每次失败都算新指纹。
+ * @param status - HTTP 状态。
+ * @param code - 上游码。
+ * @param message - 可读文案。
+ * @returns 16 位十六进制指纹。
+ */
+export function fingerprintOf(status, code, message) {
+    const normalized = message.replace(/\d+/gu, '#').replace(/\s+/gu, ' ').trim().slice(0, FINGERPRINT_TEXT_MAX);
+    return hashText(`${status ?? ''}|${code ?? ''}|${normalized}`);
+}
+/** 把报文压成单行，避免日志/面板出现换行。 */
+function singleLine(text) {
+    return text.replace(/\s+/gu, ' ').trim();
+}
+/** 剥掉 SDK 包装前缀，只留下网关/服务端自己的说明。 */
+function stripSdkPrefix(text) {
+    return text
+        .replace(/^Streamable HTTP error:\s*/iu, '')
+        .replace(/^Error POSTing to endpoint:\s*/iu, '')
+        .replace(/^MCP error\s+-\d+:\s*/iu, '')
+        .trim();
+}
+/** 从 error 对象自身读 HTTP 状态（`StreamableHTTPError.code` / `status`）。 */
+function statusOfThrown(value) {
+    if (!isRecord(value) && !(value instanceof Error))
+        return undefined;
+    const candidate = value;
+    return asStatus(candidate.status) ?? asStatus(candidate.statusCode) ?? asStatus(candidate.code);
+}
+/** 该抛出物是不是网络/超时类失败。 */
+function isTransportFailure(value) {
+    if (!(value instanceof Error))
+        return false;
+    if (ABORT_NAMES.has(value.name))
+        return true;
+    const code = value.code;
+    if (typeof code === 'string' && NETWORK_CODES.has(code))
+        return true;
+    return /fetch failed|network|socket hang up|timed? ?out|aborted/iu.test(value.message);
+}
+/**
+ * 从文本里读有分界的 HTTP 状态。
+ *
+ * 只认三种写法：`HTTP 403`、`status: 429` / `code=400`、以及开头就是 `401/403/429`。
+ * **不认裸 `5\d\d`**：实测「最多访问 500 次」会被误读成 HTTP 500。
+ */
+function statusOfText(text) {
+    const bounded = /(?:HTTP|http|status|code|错误码)\s*[:：=]?\s*([45]\d{2})\b/u.exec(text);
+    if (bounded?.[1] !== undefined)
+        return Number(bounded[1]);
+    const leading = /^\s*(401|403|429)\b/u.exec(text);
+    return leading?.[1] === undefined ? undefined : Number(leading[1]);
+}
+/** 尝试把报文解析成上游错误信封。 */
+function envelopeOf(raw) {
+    const candidates = [raw.trim()];
+    const brace = raw.indexOf('{');
+    if (brace > 0)
+        candidates.push(raw.slice(brace));
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (!isRecord(parsed))
+                continue;
+            return isRecord(parsed.error) ? parsed.error : parsed;
+        }
+        catch {
+            // 不是 JSON：按纯文本处理。
+        }
+    }
+    return undefined;
+}
+/**
+ * 把一次抛出物归一成 {@link UpstreamFailure}（只记事实）。
+ * @param value - 抛出物或上游返回的文本。
+ * @returns 观测事实。
+ */
+export function observeFailure(value) {
+    const thrownStatus = statusOfThrown(value);
+    const raw = value instanceof Error ? value.message : typeof value === 'string' ? value : String(value);
+    const envelope = envelopeOf(raw);
+    if (envelope !== undefined) {
+        const message = asText(envelope.message) ?? asText(envelope.error) ?? asText(envelope.detail) ?? singleLine(stripSdkPrefix(raw));
+        const code = asCode(envelope.code) ?? asCode(envelope.error_code);
+        const status = asStatus(envelope.upstream_code) ?? asStatus(envelope.upstreamCode) ?? asStatus(envelope.status) ?? thrownStatus;
+        const retryable = typeof envelope.retryable === 'boolean' ? envelope.retryable : undefined;
+        const requiredPlan = asText(envelope.required_plan) ?? asText(envelope.requiredPlan) ?? asText(envelope.plan);
+        return {
+            surface: 'envelope',
+            message: message.slice(0, RAW_MAX),
+            ...code !== undefined ? { code } : {},
+            ...status !== undefined ? { status } : {},
+            ...retryable !== undefined ? { retryable } : {},
+            ...requiredPlan !== undefined ? { requiredPlan } : {},
+            raw,
+            fingerprint: fingerprintOf(status, code, message),
+        };
+    }
+    const transport = isTransportFailure(value);
+    const cleaned = singleLine(stripSdkPrefix(raw)) || '上游未返回可读说明';
+    const status = thrownStatus ?? statusOfText(cleaned);
+    return {
+        surface: thrownStatus !== undefined ? 'http' : transport ? 'transport' : 'text',
+        message: cleaned.slice(0, RAW_MAX),
+        ...status !== undefined ? { status } : {},
+        raw,
+        fingerprint: fingerprintOf(status, undefined, cleaned),
+    };
+}
+/** retryable 的事实推导：HTTP 语义与传输层事实，不含「配额该不该重试」这类判断。 */
+function factRetryable(status, transport) {
+    if (status !== undefined)
+        return status === 408 || status === 425 || status === 429 || status >= 500;
+    return transport;
+}
+/** 组装 notice 里的上游现场。 */
+function upstreamOf(failure) {
+    return {
+        raw: failure.raw.slice(0, RAW_MAX),
+        ...failure.status !== undefined ? { status: failure.status } : {},
+        fingerprint: failure.fingerprint,
+    };
+}
+/**
+ * 把一次失败折成结局与提示。
+ *
+ * 顺序即语义：`401/403` 是上游拒绝 → `denied`；其余一律 `failed`。不再按文案细分
+ * 配额/凭据/档位——原文已经带出这些信息。
+ * @param error - 抛出物。
+ * @param tool - 上游工具名（只用于调用方日志，不写进提示）。
+ * @returns 结局与可直接展示的提示。
+ */
+export function classifyFailure(error, tool) {
+    const failure = observeFailure(error);
+    const code = failure.code ?? (failure.status !== undefined ? String(failure.status) : undefined);
+    const base = {
+        ...code !== undefined ? { code } : {},
+        message: `上游原文：${failure.message.slice(0, NOTICE_TEXT_MAX)}`,
+        retryable: false,
+        upstream: upstreamOf(failure),
+    };
+    if (failure.status === 401 || failure.status === 403) {
+        return {
+            state: 'denied',
+            // 401 是凭据问题、403 是订阅/权限问题：只有 403 挂升级入口，401 交给原文说明。
+            notice: {
+                ...base,
+                ...failure.status === 403 ? { upgradeUrl: FTSHARE_UPGRADE_URL } : {},
+                ...failure.requiredPlan !== undefined ? { requiredPlan: failure.requiredPlan } : {},
+            },
+            failure,
+        };
+    }
+    return {
+        state: 'failed',
+        notice: {
+            ...base,
+            retryable: failure.retryable ?? factRetryable(failure.status, failure.surface === 'transport'),
+        },
+        failure,
+    };
+}
+/**
+ * 从「调用成功但信封说自己无权」的载荷里读出权限提示。
+ *
+ * 部分网关把订阅门禁放在成功信封的 `metadata.permissions` 或 `permission` 里，而不是
+ * 返回错误；只看空数组就会把这种情况读成「没有数据」。这里只认**显式标记**（
+ * `access_denied` 之类布尔标记）或 `401/403` 状态码，不按文案猜。
+ * @param tool - 上游工具名（只用于调用方日志，不写进提示）。
+ * @param value - 上游返回的结构化载荷。
+ * @returns 权限提示；没有标记时 undefined。
+ */
+export function permissionNoticeFromPayload(tool, value) {
+    if (!isRecord(value))
+        return undefined;
+    const records = [value];
+    const metadata = value.metadata;
+    if (isRecord(metadata)) {
+        records.push(metadata);
+        if (Array.isArray(metadata.permissions))
+            records.push(...metadata.permissions.filter(isRecord));
+        if (isRecord(metadata.permission))
+            records.push(metadata.permission);
+    }
+    if (isRecord(value.permission))
+        records.push(value.permission);
+    if (Array.isArray(value.permissions))
+        records.push(...value.permissions.filter(isRecord));
+    for (const record of records) {
+        const marker = [record.access_denied, record.accessDenied, record.permission_denied, record.permissionDenied,
+            record.subscription_required, record.subscriptionRequired, record.upgrade_required, record.upgradeRequired]
+            .some(flag => flag === true);
+        const code = asCode(record.code) ?? asCode(record.error_code);
+        const status = asStatus(record.status) ?? asStatus(record.upstream_code) ?? asStatus(code);
+        const denied = marker || status === 401 || status === 403;
+        if (!denied)
+            continue;
+        const message = asText(record.message) ?? asText(record.reason) ?? asText(record.detail) ?? '';
+        const raw = JSON.stringify(value);
+        return {
+            ...code !== undefined ? { code } : status !== undefined ? { code: String(status) } : {},
+            message: `上游在成功响应里标注了权限限制：${message === '' ? '（未给说明）' : message}`,
+            ...asText(record.required_plan) !== undefined ? { requiredPlan: asText(record.required_plan) } : {},
+            ...status !== 401 ? { upgradeUrl: FTSHARE_UPGRADE_URL } : {},
+            retryable: false,
+            upstream: { raw: raw.slice(0, RAW_MAX), ...status !== undefined ? { status } : {}, fingerprint: fingerprintOf(status, code, message) },
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,mBAAmB,EAA4C,MAAM,eAAe,CAAA;AAyB7F,qDAAqD;AACrD,MAAM,OAAO,GAAG,IAAI,CAAA;AAEpB,oDAAoD;AACpD,MAAM,eAAe,GAAG,IAAI,CAAA;AAE5B,oCAAoC;AACpC,MAAM,oBAAoB,GAAG,GAAG,CAAA;AAEhC,8BAA8B;AAC9B,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAA;AAE3D,uCAAuC;AACvC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO;IAC5E,yBAAyB,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,sBAAsB;CAC/F,CAAC,CAAA;AAEF,wBAAwB;AACxB,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AACpF,CAAC;AAED,4DAA4D;AAC5D,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC5F,CAAC;AAED,4CAA4C;AAC5C,SAAS,QAAQ,CAAC,KAAc;IAC9B,MAAM,OAAO,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1I,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,IAAI,GAAG,IAAI,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AACxF,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,IAAI,IAAI,GAAG,mBAAmB,CAAA;IAC9B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;QACtC,IAAI,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,GAAG,mBAAmB,CAAA;IACtD,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAA0B,EAAE,IAAwB,EAAE,OAAe;IACjG,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAA;IAC5G,OAAO,QAAQ,CAAC,GAAG,MAAM,IAAI,EAAE,IAAI,IAAI,IAAI,EAAE,IAAI,UAAU,EAAE,CAAC,CAAA;AAChE,CAAC;AAED,2BAA2B;AAC3B,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;AAC1C,CAAC;AAED,kCAAkC;AAClC,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI;SACR,OAAO,CAAC,8BAA8B,EAAE,EAAE,CAAC;SAC3C,OAAO,CAAC,kCAAkC,EAAE,EAAE,CAAC;SAC/C,OAAO,CAAC,yBAAyB,EAAE,EAAE,CAAC;SACtC,IAAI,EAAE,CAAA;AACX,CAAC;AAED,oEAAoE;AACpE,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACnE,MAAM,SAAS,GAAG,KAAmE,CAAA;IACrF,OAAO,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACjG,CAAC;AAED,uBAAuB;AACvB,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5C,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAA;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACpE,OAAO,2DAA2D,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;AACxF,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,OAAO,GAAG,yDAAyD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpF,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IACzD,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjD,OAAO,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;AACpE,CAAC;AAED,sBAAsB;AACtB,SAAS,UAAU,CAAC,GAAW;IAC7B,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;IAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,KAAK,GAAG,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAChD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;YAC7C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,SAAQ;YAC/B,OAAO,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAA;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,YAAY,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAC1C,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACtG,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAA;QAChI,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;QACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,YAAY,CAAA;QAC/H,MAAM,SAAS,GAAG,OAAO,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;QAC1F,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC7G,OAAO;YACL,OAAO,EAAE,UAAU;YACnB,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;YAClC,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;YACrC,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE;YACzC,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE;YAC/C,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE;YACrD,GAAG;YACH,WAAW,EAAE,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;SAClD,CAAA;IACH,CAAC;IACD,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,WAAW,CAAA;IAC9D,MAAM,MAAM,GAAG,YAAY,IAAI,YAAY,CAAC,OAAO,CAAC,CAAA;IACpD,OAAO;QACL,OAAO,EAAE,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM;QAC/E,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;QAClC,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE;QACzC,GAAG;QACH,WAAW,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC;KACvD,CAAA;AACH,CAAC;AAED,qDAAqD;AACrD,SAAS,aAAa,CAAC,MAA0B,EAAE,SAAkB;IACnE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAA;IACpG,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,wBAAwB;AACxB,SAAS,UAAU,CAAC,OAAwB;IAC1C,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;QAClC,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE;QACjE,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,IAAY;IAC1D,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAChG,MAAM,IAAI,GAAkB;QAC1B,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;QACrC,OAAO,EAAE,QAAQ,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,EAAE;QAC5D,SAAS,EAAE,KAAK;QAChB,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC;KAC9B,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACrD,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,kDAAkD;YAClD,MAAM,EAAE;gBACN,GAAG,IAAI;gBACP,GAAG,OAAO,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE;gBACpE,GAAG,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE;aACpF;YACD,OAAO;SACR,CAAA;IACH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE;YACN,GAAG,IAAI;YACP,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,KAAK,WAAW,CAAC;SAC/F;QACD,OAAO;KACR,CAAA;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAY,EAAE,KAAc;IACtE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACtC,MAAM,OAAO,GAA8B,CAAC,KAAK,CAAC,CAAA;IAClD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IAC/B,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACtB,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;QAC/F,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IACzF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,gBAAgB;YAC1G,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,eAAe,CAAC;aAC1G,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QAC7D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC1F,MAAM,MAAM,GAAG,MAAM,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAA;QACzD,IAAI,CAAC,MAAM;YAAE,SAAQ;QACrB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;QAC9F,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QACjC,OAAO;YACL,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;YACvF,OAAO,EAAE,mBAAmB,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE;YACjE,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;YACnG,GAAG,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE;YAC5D,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,WAAW,EAAE,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE;SACvI,CAAA;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 宿主平面（**全局**）入口：`provide('ftshareData')`。
+ *
+ * 为什么这一行必须挂在全局、而不是金融 preset 里：preset 内 `provide` 会直接抛
+ * `Preset services require isolate realms`
+ * （`@deepseek-ai/dsh-agent-preset-registry` 的 `mount.ts`，`mountPreset` 结尾的
+ * `leakedServices` 检查）；而按提示加上 `isolate` 之后，服务会变成 preset 私有
+ * 的隔离域，preset 之外的插件再也 `inject` 不到，公用底座就白叫了。所以：
+ * **provider 全局，工具与投影钩子在 preset**（见 `./tools`、`./project`）。
+ *
+ * 载荷判定只有一条硬规则：`empty` 必须**正向证据**——已知数据容器存在且为空数组。
+ * 成功信封里既没有行、也没有空容器证据时落 `failed`，绝不冒充「没有数据」（P8 的
+ * 病根）；但非空载荷仍保留兜底（单对象/任意数组），避免把能用的接口判死。
+ *
+ * 凭据一律走 `ctx.ftshareSettings.apiKey.resolve()`，本包不读任何凭据文件。
+ * @module @dsh-ft/dsh-fft-ftshare
+ */
+import type { Context, Logger } from '@deepseek-ai/cordis';
+import { type FtshareDataService } from './contract.js';
+import { type FailureStore } from './status.js';
+import { type FtshareTransport } from './transport.js';
+export * from './contract.js';
+export { FTSHARE_GATEWAY_ENDPOINT } from './transport.js';
+export { statusStore } from './status.js';
+/** Cordis 插件名。 */
+export declare const name = "@dsh-ft/dsh-fft-ftshare";
+/** 凭据来自设置服务；缺这一项本行挂起等待，属刻意的 fail-loud。 */
+export declare const inject: string[];
+/** 本行发布的服务名。 */
+export declare const provide: "ftshareData"[];
+/** 宿主行的可选配置。 */
+export interface FtshareDataConfig {
+    /** 覆盖网关地址；默认 {@link FTSHARE_GATEWAY_ENDPOINT}。 */
+    endpoint?: string;
+    /** MCP 客户端自称的名字，只影响上游日志。 */
+    clientName?: string;
+}
+/** 建服务所需的依赖，全部可注入，便于测试。 */
+export interface FtshareDataServiceOptions {
+    /** 传输层；测试注入假实现即可完全不联网。 */
+    transport: FtshareTransport;
+    /** 具名 logger。 */
+    logger?: Logger;
+    /** 时钟，测试用来固定 `source.fetchedAt`。 */
+    now?: () => Date;
+    /** 失败账本；缺省用进程级实例，测试传隔离实例。 */
+    statusStore?: FailureStore;
+}
+/** 一次成功载荷的观测结果。 */
+export interface PayloadObservation {
+    /** 明细行；`available` 的依据。 */
+    rows: Record<string, unknown>[];
+    /** 已知数据容器存在且为空数组：这是 `empty` 的唯一正向证据。 */
+    emptyEvidence: boolean;
+    /** 顶层键，用于未识别载荷的诊断。 */
+    keys: string[];
+    /** 成功信封里既没有行、也没有空证据。 */
+    unrecognized: boolean;
+}
+/**
+ * 观测上游载荷：只回答「有没有行」「空有没有证据」「是不是不认识」。
+ *
+ * 规则：数组本身是行；已知容器里的非空数组/对象是行；任意数组键里的记录是行；
+ * 非信封、非容器、非数组的字段让整条记录成为一行；以上都没有时，只有「已知容器
+ * 为空数组」才算 `emptyEvidence`，否则是 `unrecognized`。
+ * @param value - 上游结构化载荷。
+ * @param depth - 当前递归深度（内部用）。
+ * @returns 观测结果。
+ */
+export declare function observePayload(value: unknown, depth?: number): PayloadObservation;
+/**
+ * 从任意上游载荷里找出明细行（`observePayload` 的兼容薄包装）。
+ * @param value - 上游结构化载荷。
+ * @returns 明细行；空数组表示没有行（**不**代表 `empty`，见 `observePayload`）。
+ */
+export declare function normalizeRows(value: unknown): Record<string, unknown>[];
+/**
+ * 建一个 `ctx.ftshareData`。
+ * @param options - 见 {@link FtshareDataServiceOptions}。
+ * @returns 服务实现；`call` 不抛异常，失败走 `state`/`notice`。
+ */
+export declare function createFtshareDataService(options: FtshareDataServiceOptions): FtshareDataService;
+/**
+ * 注册 `ctx.ftshareData`。
+ * @param ctx - 宿主上下文；必须是全局（根 loader）子树，preset 子树会抛错。
+ * @param config - 可选配置。
+ */
+export declare function apply(ctx: Context, config?: FtshareDataConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAG1D,OAAO,EAIL,KAAK,kBAAkB,EAGxB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAoD,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAExG,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,kBAAkB;AAClB,eAAO,MAAM,IAAI,4BAA4B,CAAA;AAE7C,0CAA0C;AAC1C,eAAO,MAAM,MAAM,UAAsB,CAAA;AAEzC,gBAAgB;AAChB,eAAO,MAAM,OAAO,iBAAyB,CAAA;AAa7C,gBAAgB;AAChB,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,2BAA2B;AAC3B,MAAM,WAAW,yBAAyB;IACxC,0BAA0B;IAC1B,SAAS,EAAE,gBAAgB,CAAA;IAC3B,iBAAiB;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,6BAA6B;IAC7B,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAgBD,mBAAmB;AACnB,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IAC/B,wCAAwC;IACxC,aAAa,EAAE,OAAO,CAAA;IACtB,sBAAsB;IACtB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,wBAAwB;IACxB,YAAY,EAAE,OAAO,CAAA;CACtB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,kBAAkB,CA4B5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAEvE;AA2ED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAsD/F;AAuBD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAUpE"}

package/lib/index.js

@@ -0,0 +1,271 @@
+/**
+ * 宿主平面（**全局**）入口：`provide('ftshareData')`。
+ *
+ * 为什么这一行必须挂在全局、而不是金融 preset 里：preset 内 `provide` 会直接抛
+ * `Preset services require isolate realms`
+ * （`@deepseek-ai/dsh-agent-preset-registry` 的 `mount.ts`，`mountPreset` 结尾的
+ * `leakedServices` 检查）；而按提示加上 `isolate` 之后，服务会变成 preset 私有
+ * 的隔离域，preset 之外的插件再也 `inject` 不到，公用底座就白叫了。所以：
+ * **provider 全局，工具与投影钩子在 preset**（见 `./tools`、`./project`）。
+ *
+ * 载荷判定只有一条硬规则：`empty` 必须**正向证据**——已知数据容器存在且为空数组。
+ * 成功信封里既没有行、也没有空容器证据时落 `failed`，绝不冒充「没有数据」（P8 的
+ * 病根）；但非空载荷仍保留兜底（单对象/任意数组），避免把能用的接口判死。
+ *
+ * 凭据一律走 `ctx.ftshareSettings.apiKey.resolve()`，本包不读任何凭据文件。
+ * @module @dsh-ft/dsh-fft-ftshare
+ */
+import { FTSHARE_DATA_SERVICE, } from './contract.js';
+import { asText, classifyFailure, fingerprintOf, isRecord, permissionNoticeFromPayload } from './errors.js';
+import { statusStore } from './status.js';
+import { createFtshareTransport } from './transport.js';
+export * from './contract.js';
+export { FTSHARE_GATEWAY_ENDPOINT } from './transport.js';
+export { statusStore } from './status.js';
+/** Cordis 插件名。 */
+export const name = '@dsh-ft/dsh-fft-ftshare';
+/** 凭据来自设置服务；缺这一项本行挂起等待，属刻意的 fail-loud。 */
+export const inject = ['ftshareSettings'];
+/** 本行发布的服务名。 */
+export const provide = [FTSHARE_DATA_SERVICE];
+/**
+ * 载荷里当「明细容器」看待的键，按优先级排列。
+ *
+ * 这个列表只用于**读容器**：非空时仍允许兜底（单对象/任意数组），但「空」必须来自
+ * 列表里的容器为空数组——否则无法区分「真的没有」和「形状变了」。
+ */
+const PAYLOAD_KEYS = ['data', 'rows', 'items', 'records', 'list', 'result', 'payload', 'response'];
+/** 只描述调用本身、不含事实的键；判断「是否存在事实」与「是不是一行」时忽略。 */
+const ENVELOPE_KEYS = new Set(['ok', 'success', 'cached', 'metadata', 'message', 'error', 'code', 'status', 'request_id', 'permission', 'permissions', 'source']);
+/** 载荷递归深度上限，防止异常结构把递归拖深。 */
+const MAX_PAYLOAD_DEPTH = 3;
+/** 只留下记录元素。 */
+function recordsOf(value) {
+    return value.filter(isRecord);
+}
+/**
+ * 观测上游载荷：只回答「有没有行」「空有没有证据」「是不是不认识」。
+ *
+ * 规则：数组本身是行；已知容器里的非空数组/对象是行；任意数组键里的记录是行；
+ * 非信封、非容器、非数组的字段让整条记录成为一行；以上都没有时，只有「已知容器
+ * 为空数组」才算 `emptyEvidence`，否则是 `unrecognized`。
+ * @param value - 上游结构化载荷。
+ * @param depth - 当前递归深度（内部用）。
+ * @returns 观测结果。
+ */
+export function observePayload(value, depth = 0) {
+    if (Array.isArray(value)) {
+        return { rows: recordsOf(value), emptyEvidence: value.length === 0, keys: [], unrecognized: false };
+    }
+    if (!isRecord(value))
+        return { rows: [], emptyEvidence: false, keys: [], unrecognized: true };
+    const keys = Object.keys(value);
+    if (depth < MAX_PAYLOAD_DEPTH) {
+        for (const key of PAYLOAD_KEYS) {
+            if (!(key in value))
+                continue;
+            const child = value[key];
+            if (Array.isArray(child)) {
+                return { rows: recordsOf(child), emptyEvidence: child.length === 0, keys, unrecognized: false };
+            }
+            if (isRecord(child)) {
+                const nested = observePayload(child, depth + 1);
+                if (nested.rows.length > 0 || nested.emptyEvidence)
+                    return { ...nested, keys };
+            }
+        }
+    }
+    // 非空兜底：任意数组键里的记录，或整条记录当一行（单对象返回值也是数据）。
+    for (const [key, candidate] of Object.entries(value)) {
+        if (ENVELOPE_KEYS.has(key) || !Array.isArray(candidate))
+            continue;
+        const rows = recordsOf(candidate);
+        if (rows.length > 0)
+            return { rows, emptyEvidence: false, keys, unrecognized: false };
+    }
+    const meaningful = keys.filter(key => !ENVELOPE_KEYS.has(key) && !PAYLOAD_KEYS.includes(key) && !Array.isArray(value[key]));
+    if (meaningful.length > 0)
+        return { rows: [value], emptyEvidence: false, keys, unrecognized: false };
+    return { rows: [], emptyEvidence: false, keys, unrecognized: true };
+}
+/**
+ * 从任意上游载荷里找出明细行（`observePayload` 的兼容薄包装）。
+ * @param value - 上游结构化载荷。
+ * @returns 明细行；空数组表示没有行（**不**代表 `empty`，见 `observePayload`）。
+ */
+export function normalizeRows(value) {
+    return observePayload(value).rows;
+}
+/**
+ * 未识别载荷的提示：这是本地事实（上游成功了，但我们读不出数据容器），不是上游原文。
+ * @param value - 上游结构化载荷。
+ * @param keys - 顶层键。
+ * @returns 失败提示。
+ */
+function unrecognizedPayloadNotice(value, keys) {
+    const raw = JSON.stringify(value);
+    return {
+        message: `上游返回成功，但没有可识别的数据容器（顶层键：${keys.join('、') === '' ? '无' : keys.join('、')}）`,
+        retryable: false,
+        upstream: {
+            raw: raw.slice(0, 2048),
+            fingerprint: fingerprintOf(undefined, undefined, `unrecognized|${keys.slice().sort().join(',')}`),
+        },
+    };
+}
+/**
+ * 记一次失败到账本，并按指纹节流日志：首次带原文，之后每 100 次带一次计数。
+ *
+ * 线上同一个 429 一天能打几千行（日志里 5835/11653 行是同一个指纹），节流的依据是
+ * 指纹本身，不是「这条日志重不重复」。
+ * @param logger - 具名 logger。
+ * @param store - 失败账本。
+ * @param tool - 上游接口名。
+ * @param state - 结局。
+ * @param notice - 提示。
+ * @param durationMs - 本次耗时。
+ */
+function recordFailure(logger, store, tool, state, notice, durationMs) {
+    const fingerprint = notice.upstream?.fingerprint ?? fingerprintOf(undefined, notice.code, notice.message);
+    const message = notice.upstream?.raw ?? notice.message;
+    const { record, isNew } = store.recordFailure({
+        fingerprint,
+        tool,
+        state: state === 'denied' ? 'denied' : 'failed',
+        ...notice.code !== undefined ? { code: notice.code } : {},
+        ...notice.upstream?.status !== undefined ? { status: notice.upstream.status } : {},
+        message,
+        durationMs,
+    });
+    if (logger === undefined)
+        return;
+    if (isNew) {
+        logger.warn('ftshare.call_classified', {
+            tool,
+            state,
+            ...notice.code !== undefined ? { code: notice.code } : {},
+            ...notice.upstream?.status !== undefined ? { status: notice.upstream.status } : {},
+            fingerprint,
+            durationMs,
+            count: record.count,
+            message: message.slice(0, 1000),
+        });
+    }
+    else if (record.count % 100 === 0) {
+        logger.warn('ftshare.call_classified', {
+            tool,
+            state,
+            ...notice.code !== undefined ? { code: notice.code } : {},
+            ...notice.upstream?.status !== undefined ? { status: notice.upstream.status } : {},
+            fingerprint,
+            durationMs,
+            count: record.count,
+        });
+    }
+}
+/**
+ * 上游接口清单的缓存时长。清单一天最多变几次，而目录产物是发版时生成的，运行期
+ * 只用来回答「这个接口名上游认不认」，所以短缓存足够。
+ */
+const TOOLS_TTL_MS = 5 * 60_000;
+/**
+ * 建一个 `ctx.ftshareData`。
+ * @param options - 见 {@link FtshareDataServiceOptions}。
+ * @returns 服务实现；`call` 不抛异常，失败走 `state`/`notice`。
+ */
+export function createFtshareDataService(options) {
+    const now = options.now ?? (() => new Date());
+    const store = options.statusStore ?? statusStore;
+    let cache;
+    return {
+        async call(interfaceName, args = {}, callOptions) {
+            const source = { name: 'FTShare', fetchedAt: now().toISOString() };
+            const startedAt = Date.now();
+            try {
+                const { value } = await options.transport.call(interfaceName, args, callOptions);
+                const observation = observePayload(value);
+                if (observation.rows.length > 0)
+                    return { ok: true, state: 'available', rows: observation.rows, source };
+                // 成功信封 + 显式权限标记 = denied，不是没有数据。这是 P8 的第二种形态。
+                const gated = permissionNoticeFromPayload(interfaceName, value);
+                if (gated !== undefined) {
+                    recordFailure(options.logger, store, interfaceName, 'denied', gated, Date.now() - startedAt);
+                    return { ok: false, state: 'denied', rows: [], notice: gated, source };
+                }
+                if (observation.emptyEvidence)
+                    return { ok: true, state: 'empty', rows: [], source };
+                const notice = unrecognizedPayloadNotice(value, observation.keys);
+                recordFailure(options.logger, store, interfaceName, 'failed', notice, Date.now() - startedAt);
+                return { ok: false, state: 'failed', rows: [], notice, source };
+            }
+            catch (error) {
+                const { state, notice } = classifyFailure(error, interfaceName);
+                recordFailure(options.logger, store, interfaceName, state, notice, Date.now() - startedAt);
+                return { ok: false, state, rows: [], notice, source };
+            }
+        },
+        async listTools() {
+            if (cache !== undefined && Date.now() - cache.at < TOOLS_TTL_MS)
+                return cache.tools;
+            try {
+                const tools = await options.transport.listTools();
+                cache = { tools, at: Date.now() };
+                // 目录漂移：随包快照 vs 上游实时清单的规范化哈希，不一致就留痕。
+                store.recordCatalog(tools);
+                const observation = store.snapshot().catalog;
+                if (observation.changed === true) {
+                    options.logger?.warn('ftshare.catalog_changed', {
+                        shippedCount: observation.shippedCount,
+                        liveCount: observation.liveCount,
+                        shippedHash: observation.shippedHash,
+                        liveHash: observation.liveHash,
+                    });
+                }
+                return tools;
+            }
+            catch (error) {
+                // 清单是增强信息，不该让调用方拿到异常；失败就退回上一次的清单。
+                options.logger?.warn('ftshare.list_tools_failed', { message: error instanceof Error ? error.message : String(error) });
+                return cache?.tools ?? [];
+            }
+        },
+    };
+}
+/**
+ * 取一次凭据。设置服务缺失或读取抛错都不让整行崩掉：返回 undefined，网关会以
+ * 「未携带 API Key」给出可诊断的拒绝。
+ * @param ctx - 宿主上下文。
+ * @param logger - 具名 logger。
+ * @returns API Key，或 undefined。
+ */
+async function resolveApiKey(ctx, logger) {
+    const apiKey = ctx.ftshareSettings?.apiKey;
+    if (apiKey === undefined) {
+        logger.warn('ftshare.api_key_namespace_missing', { message: '设置服务未注册 API Key 命名空间，FTShare 取数将不可用' });
+        return undefined;
+    }
+    try {
+        return asText(await apiKey.resolve());
+    }
+    catch (error) {
+        logger.warn('ftshare.api_key_resolve_failed', { message: error instanceof Error ? error.message : String(error) });
+        return undefined;
+    }
+}
+/**
+ * 注册 `ctx.ftshareData`。
+ * @param ctx - 宿主上下文；必须是全局（根 loader）子树，preset 子树会抛错。
+ * @param config - 可选配置。
+ */
+export function apply(ctx, config) {
+    const logger = ctx.logger('dsh-fft-ftshare');
+    const transport = createFtshareTransport({
+        endpoint: config?.endpoint,
+        clientName: config?.clientName,
+        resolveApiKey: () => resolveApiKey(ctx, logger),
+        logger,
+    });
+    const host = ctx;
+    host.provide(FTSHARE_DATA_SERVICE, createFtshareDataService({ transport, logger }));
+}
+//# sourceMappingURL=index.js.map