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

package/lib/catalog.js

@@ -0,0 +1,60 @@
+/**
+ * 目录（catalog）：上游接口的**全量快照**，回答「上游有什么」。
+ *
+ * 与接口表（`capabilities.ts`，回答「我们承接什么」）不是一回事。目录由
+ * `scripts/build-catalog.mjs` 从 `tools/list` 生成，随包发布两份产物：
+ * `catalog.json`（完整，含 `description` 与 `inputSchema`）与 `catalog.txt`
+ * （一线索引，供模型 `grep`）。本模块只做纯函数——查名字、读必填入参——因此宿主
+ * 与浏览器两侧都能用；读文件的那一半在 `catalog-host.ts`。
+ * @module @dsh-ft/dsh-fft-ftshare/catalog
+ */
+/** 判断一个值是不是可当对象读的记录。 */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 把任意解析结果收敛成目录。字段缺失的条目直接丢掉而不是留半条：目录是准入判据，
+ * 半条会让「在目录里」这个断言变得没有意义。
+ * @param value - `catalog.json` 的解析结果。
+ * @returns 目录；形状不对时为空目录。
+ */
+export function asCatalog(value) {
+    const raw = isRecord(value) && Array.isArray(value.entries) ? value.entries : [];
+    const entries = [];
+    for (const entry of raw) {
+        if (!isRecord(entry) || typeof entry.name !== 'string' || entry.name === '')
+            continue;
+        entries.push({
+            name: entry.name,
+            title: typeof entry.title === 'string' && entry.title !== '' ? entry.title : entry.name,
+            ...typeof entry.description === 'string' && entry.description !== '' ? { description: entry.description } : {},
+            ...entry.inputSchema !== undefined ? { inputSchema: entry.inputSchema } : {},
+        });
+    }
+    return { entries };
+}
+/**
+ * 按接口名查目录。
+ * @param catalog - 目录。
+ * @param name - 上游接口名。
+ * @returns 条目；不在目录里时 undefined。
+ */
+export function catalogEntryOf(catalog, name) {
+    return catalog.entries.find(entry => entry.name === name);
+}
+/**
+ * 读出上游 `inputSchema.required` 里、这次调用没有给的入参名。
+ *
+ * 只查「有没有给」，不查类型与取值：本地能确定说出口的只有缺席，类型判断留给上游，
+ * 免得把「上游其实能容忍的写法」判成错误。
+ * @param entry - 目录条目。
+ * @param args - 本次调用入参。
+ * @returns 缺席的必填入参名，按 schema 顺序。
+ */
+export function missingRequiredArgs(entry, args) {
+    const schema = entry.inputSchema;
+    if (!isRecord(schema) || !Array.isArray(schema.required))
+        return [];
+    return schema.required.filter((name) => typeof name === 'string' && (args === undefined || args[name] === undefined || args[name] === null));
+}
+//# sourceMappingURL=catalog.js.map

package/lib/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoBH,wBAAwB;AACxB,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;IAChF,MAAM,OAAO,GAAmB,EAAE,CAAA;IAClC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE;YAAE,SAAQ;QACrF,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI;YACvF,GAAG,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE;YAC9G,GAAG,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE;SAC7E,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAA;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,IAAY;IAC3D,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB,EAAE,IAAyC;IAChG,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAAA;IAChC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAA;IACnE,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CACrD,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAA;AACxG,CAAC"}

package/lib/client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 浏览器助手：造一个与宿主**同名同形**的 `ftshareData`（**消费方自己挂**）。
+ *
+ * ```ts
+ * ctx.provide('ftshareData', createFtshareClient({ catalog, fetch: window.fetch.bind(window) }))
+ * ```
+ *
+ * 面板因此与宿主消费方写法一致：`state === 'denied'` 显示「去升级」，
+ * `state === 'empty'` 才是「没有数据」。两处刻意的差别（设计 §5.2）：
+ *
+ * - **可调集合是目录全量**，不是模型那张策展接口表 —— 面板不受提示词预算约束；
+ * - **发现靠本地 `search()`**，是对目录的纯函数，不发网络。
+ *
+ * 这个模块是**只读子集**：不碰凭据、不碰网关地址、不维护接口表。它只认两样输入——
+ * 随包的目录与被注入的 `fetch`；`@dsh-ft/dsh-fft-ftshare/route` 与网关常量都不在这里的
+ * 依赖里，`scripts/test-crossplane.mjs` 会 grep 产物把这条钉住。
+ *
+ * 过桥时只做「形状收敛」，不解释内容：`notice.code` 可缺省（上游不给码就省略），
+ * `notice.upstream` 原样保留（面板要定位时用）。
+ * @module @dsh-ft/dsh-fft-ftshare/client
+ */
+import { type CatalogEntry } from './catalog.js';
+import { type FtshareDataService } from './contract.js';
+/** 浏览器侧可用的 `fetch` 子集；测试直接注入假实现。 */
+export type FtshareFetch = (input: string, init: RequestInit) => Promise<Response>;
+/** 客户端服务的调用选项。 */
+export interface FtshareClientOptions {
+    /** 随包目录（`catalog.json` 的解析结果），决定哪些接口可调。 */
+    catalog: unknown;
+    /** 同源 fetch；浏览器传 `window.fetch.bind(window)`。 */
+    fetch: FtshareFetch;
+    /** 路由覆盖，默认 {@link FTSHARE_DATA_ROUTE}。 */
+    route?: string;
+    /** 成功结果的缓存时长；`denied` 与失败从不缓存。 */
+    ttlMs?: number;
+    /** 时钟，测试用来固定 `source.fetchedAt`。 */
+    now?: () => Date;
+}
+/** 客户端服务：与 {@link FtshareDataService} 同名同形，另加一个本地检索。 */
+export interface FtshareClientService extends FtshareDataService {
+    /**
+     * 在目录里本地检索（纯函数，不发网络）。
+     * @param query - 关键词，大小写不敏感；空串返回前 `limit` 条。
+     * @param limit - 最多返回条数，默认 20。
+     * @returns 命中的目录条目。
+     */
+    search(query: string, limit?: number): CatalogEntry[];
+}
+/**
+ * 造一个客户端 `ftshareData`。
+ * @param options - 见 {@link FtshareClientOptions}。
+ * @returns 与宿主同名同形的服务，外加本地 `search()`。
+ */
+export declare function createFtshareClient(options: FtshareClientOptions): FtshareClientService;
+//# sourceMappingURL=client.d.ts.map

package/lib/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAgE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAC9G,OAAO,EAA8F,KAAK,kBAAkB,EAA4C,MAAM,eAAe,CAAA;AAE7L,oCAAoC;AACpC,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAElF,kBAAkB;AAClB,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,KAAK,EAAE,YAAY,CAAA;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAA;CACtD;AAmDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CA6FvF"}

package/lib/client.js

@@ -0,0 +1,184 @@
+/**
+ * 浏览器助手：造一个与宿主**同名同形**的 `ftshareData`（**消费方自己挂**）。
+ *
+ * ```ts
+ * ctx.provide('ftshareData', createFtshareClient({ catalog, fetch: window.fetch.bind(window) }))
+ * ```
+ *
+ * 面板因此与宿主消费方写法一致：`state === 'denied'` 显示「去升级」，
+ * `state === 'empty'` 才是「没有数据」。两处刻意的差别（设计 §5.2）：
+ *
+ * - **可调集合是目录全量**，不是模型那张策展接口表 —— 面板不受提示词预算约束；
+ * - **发现靠本地 `search()`**，是对目录的纯函数，不发网络。
+ *
+ * 这个模块是**只读子集**：不碰凭据、不碰网关地址、不维护接口表。它只认两样输入——
+ * 随包的目录与被注入的 `fetch`；`@dsh-ft/dsh-fft-ftshare/route` 与网关常量都不在这里的
+ * 依赖里，`scripts/test-crossplane.mjs` 会 grep 产物把这条钉住。
+ *
+ * 过桥时只做「形状收敛」，不解释内容：`notice.code` 可缺省（上游不给码就省略），
+ * `notice.upstream` 原样保留（面板要定位时用）。
+ * @module @dsh-ft/dsh-fft-ftshare/client
+ */
+import { asCatalog, catalogEntryOf, missingRequiredArgs } from './catalog.js';
+import { FTSHARE_DATA_ROUTE } from './contract.js';
+/** 默认缓存时长：面板会连点，一次调用不值得重复出站；`denied` 例外。 */
+const DEFAULT_TTL_MS = 60_000;
+/** 默认检索条数上限。 */
+const DEFAULT_SEARCH_LIMIT = 20;
+/** 传输层失败（断网、超时、非 2xx、解析失败）统一落的结局。 */
+const TRANSPORT_FAILURE = 'failed';
+/** 四态集合；客户端只认这四个，别的一律当形状不符。 */
+const STATES = new Set(['available', 'empty', 'denied', 'failed']);
+/** 判断一个值是不是可当对象读的记录。 */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 读一个非空字符串；其余 undefined。 */
+function asText(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * 收敛宿主过桥的 `notice`：只校验「有说明」，不要求「有码」。
+ * @param value - 过桥的 notice。
+ * @returns 收敛后的 notice；形状不符时 undefined。
+ */
+function normalizeNotice(value) {
+    if (!isRecord(value) || typeof value.message !== 'string')
+        return undefined;
+    const code = asText(value.code);
+    const requiredPlan = asText(value.requiredPlan);
+    const upgradeUrl = asText(value.upgradeUrl);
+    const upstream = isRecord(value.upstream) && typeof value.upstream.raw === 'string'
+        ? {
+            raw: value.upstream.raw,
+            ...typeof value.upstream.status === 'number' ? { status: value.upstream.status } : {},
+            fingerprint: typeof value.upstream.fingerprint === 'string' ? value.upstream.fingerprint : '',
+        }
+        : undefined;
+    return {
+        ...code !== undefined ? { code } : {},
+        message: value.message,
+        ...requiredPlan !== undefined ? { requiredPlan } : {},
+        ...upgradeUrl !== undefined ? { upgradeUrl } : {},
+        retryable: value.retryable === true,
+        ...upstream !== undefined ? { upstream } : {},
+    };
+}
+/**
+ * 造一个客户端 `ftshareData`。
+ * @param options - 见 {@link FtshareClientOptions}。
+ * @returns 与宿主同名同形的服务，外加本地 `search()`。
+ */
+export function createFtshareClient(options) {
+    const catalog = asCatalog(options.catalog);
+    const route = options.route ?? FTSHARE_DATA_ROUTE;
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    const now = options.now ?? (() => new Date());
+    const send = options.fetch;
+    const cache = new Map();
+    /** 本地就能定的失败：`source` 用客户端时钟，其余字段与宿主同形。 */
+    const failure = (code, message, retryable = false) => ({
+        ok: false,
+        state: TRANSPORT_FAILURE,
+        rows: [],
+        notice: { code, message, retryable },
+        source: { name: 'FTShare', fetchedAt: now().toISOString() },
+    });
+    /** 收敛远端返回；形状不对一律 undefined（由调用方落成 failed）。 */
+    const asCallResult = (value) => {
+        if (!isRecord(value))
+            return undefined;
+        const state = value.state;
+        if (typeof state !== 'string' || !STATES.has(state))
+            return undefined;
+        if (typeof value.ok !== 'boolean' || !Array.isArray(value.rows))
+            return undefined;
+        if (!isRecord(value.source))
+            return undefined;
+        const notice = value.notice;
+        const normalizedNotice = notice === undefined ? undefined : normalizeNotice(notice);
+        // notice 存在但形状不对（没有 message）时按形状不符处理，不吞掉失败原因。
+        if (notice !== undefined && normalizedNotice === undefined)
+            return undefined;
+        return {
+            ok: value.ok,
+            state: state,
+            rows: value.rows.filter(isRecord),
+            source: value.source,
+            ...normalizedNotice === undefined ? {} : { notice: normalizedNotice },
+        };
+    };
+    return {
+        async call(interfaceName, args = {}, callOptions) {
+            const entry = catalogEntryOf(catalog, interfaceName);
+            if (entry === undefined) {
+                return failure('unknown_interface', `接口 ${interfaceName} 不在 FTShare 目录里，不能调用`);
+            }
+            const missing = missingRequiredArgs(entry, args);
+            if (missing.length > 0)
+                return failure('missing_arguments', `缺必填入参：${missing.join('、')}`);
+            const key = `${interfaceName} ${JSON.stringify(args)}`;
+            const hit = cache.get(key);
+            if (hit !== undefined && Date.now() - hit.at < ttlMs)
+                return hit.result;
+            try {
+                const response = await send(route, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ interface: interfaceName, args }),
+                    ...callOptions?.signal === undefined ? {} : { signal: callOptions.signal },
+                });
+                if (!response.ok) {
+                    const detail = await readErrorBody(response);
+                    // 非 2xx 一律 failed：面板只需要一种方式渲染「取数失败」。
+                    return failure(detail?.code ?? `http_${response.status}`, detail?.message ?? `FTShare 取数失败（HTTP ${response.status}）`, true);
+                }
+                const result = asCallResult(await response.json());
+                if (result === undefined)
+                    return failure('invalid_response', 'FTShare 底座返回的形状不对，无法渲染');
+                // denied 不缓存：用户可能正好在另一个标签页里改了订阅或 Key。
+                if (result.state !== 'denied')
+                    cache.set(key, { at: Date.now(), result });
+                return result;
+            }
+            catch (error) {
+                return failure('transport_failed', `FTShare 取数失败：${error instanceof Error ? error.message : String(error)}`, true);
+            }
+        },
+        async listTools() {
+            // 面板不需要为清单再跑一趟网络：目录就是清单。
+            return catalog.entries.map(entry => ({
+                tool: entry.name,
+                title: entry.title,
+                ...entry.description !== undefined ? { description: entry.description } : {},
+                ...entry.inputSchema !== undefined ? { inputSchema: entry.inputSchema } : {},
+            }));
+        },
+        search(query, limit = DEFAULT_SEARCH_LIMIT) {
+            const needle = query.trim().toLowerCase();
+            const matched = needle === ''
+                ? catalog.entries
+                : catalog.entries.filter(entry => entry.name.toLowerCase().includes(needle)
+                    || entry.title.toLowerCase().includes(needle)
+                    || (entry.description ?? '').toLowerCase().includes(needle));
+            return matched.slice(0, Math.max(0, limit));
+        },
+    };
+}
+/** 读路由的错误信封；读不出来就返回 undefined，由调用方给通用措辞。 */
+async function readErrorBody(response) {
+    try {
+        const body = await response.json();
+        if (!isRecord(body) || !isRecord(body.error))
+            return undefined;
+        const code = typeof body.error.code === 'string' ? body.error.code : undefined;
+        const message = typeof body.error.message === 'string' ? body.error.message : undefined;
+        if (code === undefined || message === undefined)
+            return undefined;
+        return { code, message };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=client.js.map

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/lib/contract.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `@dsh-ft/dsh-fft-ftshare/contract` —— FTShare 公用底座的冻结契约。
+ *
+ * 消费方只需要 `import type { FtshareDataService } from '@dsh-ft/dsh-fft-ftshare/contract'`，
+ * 不依赖本包的实现、传输层或 MCP SDK。本模块只有类型与常量，没有运行时依赖，
+ * 因此宿主插件与测试都能安全引用。
+ *
+ * 设计要点是 **四态归一**：FTShare 网关把「真的没有数据」「上游拒绝（401/403）」
+ * 「取数失败」三种情况都表现为「空」，调用方若只判断空数组就会把「拒绝」误读成
+ * 「没有数据」。{@link FtshareCallResult.state} 强制区分这四种结局。
+ *
+ * 失败说明（{@link FtshareNotice}）只**抄上游事实**：码、HTTP 状态、原文、重试提示。
+ * 本包不翻译、不归因、不编造 remedy；是不是配额、要不要升级，由原文与消费方判断。
+ * @module @dsh-ft/dsh-fft-ftshare/contract
+ */
+/** 服务在 cordis `Context` 上的名字，也是 `ctx.provide` 的键。 */
+export declare const FTSHARE_DATA_SERVICE: "ftshareData";
+/**
+ * 跨平面通路的精确路由：浏览器侧的 `createFtshareClient` POST 到这里，宿主侧的
+ * `registerFtshareRoute` 在这里应答。走 `connection.fetch` 的 `/api` 载体，因此
+ * Host/Origin 围栏与浏览器鉴权由载体负责。
+ */
+export declare const FTSHARE_DATA_ROUTE: "/api/ftshare-data";
+/** 用户可升级订阅的页面，{@link FtshareNotice.upgradeUrl} 的默认值（仅 `denied` 带）。 */
+export declare const FTSHARE_UPGRADE_URL: "https://ftai.chat/me/profile?tab=subscription";
+/**
+ * 一次取数的四态结局。
+ *
+ * - `available`：调用成功且至少返回了一行；
+ * - `empty`：调用成功，且载荷里有**正向证据**（已知数据容器存在且为空数组）；
+ * - `denied`：上游以 HTTP 401/403 拒绝—— **不是**「没有数据」；
+ * - `failed`：连接、超时、参数、上游 5xx 等其他失败，或成功信封无法识别。
+ */
+export type FtshareCallState = 'available' | 'empty' | 'denied' | 'failed';
+/**
+ * 四态归一后的取数结果。
+ *
+ * 形状已冻结：字段只增不改，消费方按需读取。
+ */
+export interface FtshareCallResult {
+    /**
+     * 调用是否走通到「上游给出了答复」这一步：`available` 与 `empty` 为真，
+     * `denied` 与 `failed` 为假。它回答的是「通道是否可用」，不回答「有没有数据」——
+     * 后者看 {@link state}。把两者分开是有意的：只有 `empty` 才允许下游说
+     * 「没有数据」。
+     */
+    ok: boolean;
+    /** 四态结局，见 {@link FtshareCallState}。 */
+    state: FtshareCallState;
+    /** 归一后的明细行；`available` 之外通常为空数组，绝不是权限判断依据。 */
+    rows: Record<string, unknown>[];
+    /** 需要向用户/模型解释的异常；成功时为 undefined。 */
+    notice?: FtshareNotice;
+    /** 取数来源与时点，用于在报告里给出处。 */
+    source: FtshareSource;
+}
+/**
+ * 上游失败的现场。
+ *
+ * 只放事实：网关说了什么、HTTP 状态是多少、同一类失败怎么聚在一起。不存
+ * 「原因」或「补救办法」——那两样会随上游文案一起失效。
+ */
+export interface FtshareUpstream {
+    /** 上游原文（剥掉 SDK 包装后的可读报文），最多 2 KB。 */
+    raw: string;
+    /** HTTP 状态：`Error.code`、信封 `upstream_code`，或文本里带分界的写法。 */
+    status?: number;
+    /** 失败指纹：同工具、同状态、同码、同归一文案的失败聚合用（数字已归一）。 */
+    fingerprint: string;
+}
+/** 面向用户/模型的异常说明。 */
+export interface FtshareNotice {
+    /**
+     * 上游错误码，**照抄**（如 `UPSTREAM_UNAVAILABLE`）；没有信封码但拿到 401/403 时，
+     * 用 HTTP 状态字符串 `"401"`/`"403"`（事实，不是编造）。本地失败码（目录外接口、
+     * 缺参、传输失败）由调用方自己给。
+     */
+    code?: string;
+    /** 面向展示的说明：上游原文（`上游原文：…`）或本地失败的事实描述。 */
+    message: string;
+    /** 上游信封真给了所需档位才写，不做推断。 */
+    requiredPlan?: string;
+    /** 升级入口，只有 `denied` 带。 */
+    upgradeUrl?: string;
+    /** 是否值得原样重试：上游 hint，缺失时按 HTTP/传输事实推导。 */
+    retryable: boolean;
+    /** 上游失败的现场；本地失败（目录外、缺参）没有。 */
+    upstream?: FtshareUpstream;
+}
+/** 取数来源与时点。 */
+export interface FtshareSource {
+    name: 'FTShare';
+    /** ISO-8601 取数时点。 */
+    fetchedAt: string;
+}
+/** 单次调用的可选项。 */
+export interface FtshareCallOptions {
+    /** 调用方取消信号；已取消时立刻返回 `failed`，不发起连接。 */
+    signal?: AbortSignal;
+}
+/** 上游 FTShare MCP 网关暴露的一个工具。 */
+export interface FtshareToolInfo {
+    /** 上游工具名，例如 `ft_v1_finance_income`。 */
+    tool: string;
+    /** 上游标题；上游未提供时回落为工具名。 */
+    title: string;
+    /** 上游说明原文；随包目录的两份产物都由它生成。 */
+    description?: string;
+    /** 上游入参 JSON Schema 原文；`ftshare_call` 的本地预校验用它。 */
+    inputSchema?: unknown;
+}
+/**
+ * `ctx.ftshareData`：FTShare 取数的唯一入口。
+ *
+ * 实现由本包的宿主入口（裸包名 `@dsh-ft/dsh-fft-ftshare`）`provide`，且必须挂在
+ * **全局平面**：preset 内的 `provide` 会直接抛
+ * `Preset services require isolate realms`（`agent-preset-registry` 的
+ * `mount.ts`），而加上 isolate 之后服务会变成 preset 私有，preset 之外的插件再也
+ * inject 不到。消费方因此统一用 `inject: ['ftshareData']` 声明依赖。
+ */
+export interface FtshareDataService {
+    /**
+     * 调一个上游 FTShare 接口并把结果归一成 {@link FtshareCallResult}。
+     * @param interfaceName - 上游接口名，例如 `ft_v1_finance_income`。
+     * @param args - 上游接口入参，原样透传。
+     * @param options - 取消信号等。
+     * @returns 归一后的结果；本方法不抛异常，权限与失败都走 `state`/`notice`。
+     */
+    call(interfaceName: string, args?: Record<string, unknown>, options?: FtshareCallOptions): Promise<FtshareCallResult>;
+    /**
+     * 上游当前可用的接口清单（名字、标题、说明、入参 schema）。
+     *
+     * 自己触发拉取并做短 TTL 缓存：不依赖「先调通一次」才有人填缓存。上游不可达时
+     * 返回上一次的清单，没有则返回空数组——清单是增强信息，不该让取数失败。
+     */
+    listTools(): Promise<readonly FtshareToolInfo[]>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        ftshareData: FtshareDataService;
+    }
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,EAAG,aAAsB,CAAA;AAE1D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAG,mBAA4B,CAAA;AAE9D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,EAAG,+CAAwD,CAAA;AAE3F;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE1E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,EAAE,EAAE,OAAO,CAAA;IACX,uCAAuC;IACvC,KAAK,EAAE,gBAAgB,CAAA;IACvB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IAC/B,oCAAoC;IACpC,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,yBAAyB;IACzB,MAAM,EAAE,aAAa,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,oBAAoB;AACpB,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAA;IAClB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAED,eAAe;AACf,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,gBAAgB;AAChB,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,gCAAgC;AAChC,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACrH;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAAA;CACjD;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,WAAW,EAAE,kBAAkB,CAAA;KAChC;CACF"}

package/lib/contract.js

@@ -0,0 +1,26 @@
+/**
+ * `@dsh-ft/dsh-fft-ftshare/contract` —— FTShare 公用底座的冻结契约。
+ *
+ * 消费方只需要 `import type { FtshareDataService } from '@dsh-ft/dsh-fft-ftshare/contract'`，
+ * 不依赖本包的实现、传输层或 MCP SDK。本模块只有类型与常量，没有运行时依赖，
+ * 因此宿主插件与测试都能安全引用。
+ *
+ * 设计要点是 **四态归一**：FTShare 网关把「真的没有数据」「上游拒绝（401/403）」
+ * 「取数失败」三种情况都表现为「空」，调用方若只判断空数组就会把「拒绝」误读成
+ * 「没有数据」。{@link FtshareCallResult.state} 强制区分这四种结局。
+ *
+ * 失败说明（{@link FtshareNotice}）只**抄上游事实**：码、HTTP 状态、原文、重试提示。
+ * 本包不翻译、不归因、不编造 remedy；是不是配额、要不要升级，由原文与消费方判断。
+ * @module @dsh-ft/dsh-fft-ftshare/contract
+ */
+/** 服务在 cordis `Context` 上的名字，也是 `ctx.provide` 的键。 */
+export const FTSHARE_DATA_SERVICE = 'ftshareData';
+/**
+ * 跨平面通路的精确路由：浏览器侧的 `createFtshareClient` POST 到这里，宿主侧的
+ * `registerFtshareRoute` 在这里应答。走 `connection.fetch` 的 `/api` 载体，因此
+ * Host/Origin 围栏与浏览器鉴权由载体负责。
+ */
+export const FTSHARE_DATA_ROUTE = '/api/ftshare-data';
+/** 用户可升级订阅的页面，{@link FtshareNotice.upgradeUrl} 的默认值（仅 `denied` 带）。 */
+export const FTSHARE_UPGRADE_URL = 'https://ftai.chat/me/profile?tab=subscription';
+//# sourceMappingURL=contract.js.map

package/lib/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAsB,CAAA;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAA4B,CAAA;AAE9D,sEAAsE;AACtE,MAAM,CAAC,MAAM,mBAAmB,GAAG,+CAAwD,CAAA"}

package/lib/errors.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 上游失败的观测与四态归一的**薄**层。
+ *
+ * 只做四件事：抄事实、判 HTTP 语义、留现场、算指纹。**不解释上游**：不维护错误码表，
+ * 不按中文文案猜「配额/权限/凭据」，不编造 remedy。上游改名、改文案、加码，这里一行
+ * 都不用改。
+ *
+ * 判定只剩两条 HTTP 语义（稳定、不会随上游文案变）：
+ *
+ * - `401` / `403` → `denied`（面板遮罩要用）；
+ * - 其余 → `failed`。
+ *
+ * `empty` 不在这里判定：它由成功载荷的**正向证据**决定（见 `./index.ts` 的
+ * `observePayload`）。「成功信封里带权限标记」是载荷事实，由
+ * {@link permissionNoticeFromPayload} 识别，同样不是文案猜测。
+ * @module @dsh-ft/dsh-fft-ftshare/errors
+ */
+import { type FtshareNotice } from './contract.js';
+/** 失败从哪条通道来：成功信封内、HTTP 非 2xx、传输层、纯文本。 */
+export type FailureSurface = 'envelope' | 'http' | 'transport' | 'text';
+/** 一次失败的观测事实。只记事实，不下结论。 */
+export interface UpstreamFailure {
+    /** 观测通道。 */
+    surface: FailureSurface;
+    /** 剥掉 SDK 包装后的可读文本；单行。 */
+    message: string;
+    /** 上游信封里的码，原样大小写；不猜、不改写。 */
+    code?: string;
+    /** HTTP 状态：`Error.code`、信封 `upstream_code`，或文本里有分界的写法。 */
+    status?: number;
+    /** 上游自己的 retryable hint；只有信封里有，只作提示。 */
+    retryable?: boolean;
+    /** 上游真给了才带上。 */
+    requiredPlan?: string;
+    /** 原始报文（未截断），用于指纹与 fixture 草稿。 */
+    raw: string;
+    /** 稳定短指纹，见 {@link fingerprintOf}。 */
+    fingerprint: string;
+}
+/** 判断一个值是不是可当对象读的记录。 */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** 读一个非空字符串；其余一律 undefined。 */
+export declare function asText(value: unknown): string | undefined;
+/** 不依赖 `node:crypto` 的稳定指纹：FNV-1a 64 位，十六进制 16 位。 */
+export declare function hashText(text: string): string;
+/**
+ * 失败指纹：同工具、同状态、同码、同归一文案的失败聚合用。
+ *
+ * 文案里的数字会归一成 `#`，否则「请等待 N 小时」会让每次失败都算新指纹。
+ * @param status - HTTP 状态。
+ * @param code - 上游码。
+ * @param message - 可读文案。
+ * @returns 16 位十六进制指纹。
+ */
+export declare function fingerprintOf(status: number | undefined, code: string | undefined, message: string): string;
+/**
+ * 把一次抛出物归一成 {@link UpstreamFailure}（只记事实）。
+ * @param value - 抛出物或上游返回的文本。
+ * @returns 观测事实。
+ */
+export declare function observeFailure(value: unknown): UpstreamFailure;
+/**
+ * 把一次失败折成结局与提示。
+ *
+ * 顺序即语义：`401/403` 是上游拒绝 → `denied`；其余一律 `failed`。不再按文案细分
+ * 配额/凭据/档位——原文已经带出这些信息。
+ * @param error - 抛出物。
+ * @param tool - 上游工具名（只用于调用方日志，不写进提示）。
+ * @returns 结局与可直接展示的提示。
+ */
+export declare function classifyFailure(error: unknown, tool: string): {
+    state: 'denied' | 'failed';
+    notice: FtshareNotice;
+    failure: UpstreamFailure;
+};
+/**
+ * 从「调用成功但信封说自己无权」的载荷里读出权限提示。
+ *
+ * 部分网关把订阅门禁放在成功信封的 `metadata.permissions` 或 `permission` 里，而不是
+ * 返回错误；只看空数组就会把这种情况读成「没有数据」。这里只认**显式标记**（
+ * `access_denied` 之类布尔标记）或 `401/403` 状态码，不按文案猜。
+ * @param tool - 上游工具名（只用于调用方日志，不写进提示）。
+ * @param value - 上游返回的结构化载荷。
+ * @returns 权限提示；没有标记时 undefined。
+ */
+export declare function permissionNoticeFromPayload(tool: string, value: unknown): FtshareNotice | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAuB,KAAK,aAAa,EAAwB,MAAM,eAAe,CAAA;AAE7F,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;AAEvE,2BAA2B;AAC3B,MAAM,WAAW,eAAe;IAC9B,YAAY;IACZ,OAAO,EAAE,cAAc,CAAA;IACvB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,gBAAgB;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAA;CACpB;AAoBD,wBAAwB;AACxB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,+BAA+B;AAC/B,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEzD;AAaD,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG3G;AA8DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA+B9D;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CA6B7I;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CA+BnG"}