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

package/lib/mask.js

@@ -0,0 +1,106 @@
+/**
+ * preset 平面：把 `dsh_kline` 的 **FTShare wrapper 工具**从模型可见面掩掉。
+ *
+ * ### 为什么掩而不是删
+ *
+ * kline 的 MCP 工具是那一层（mcp 行）的自有注册，MCP 客户端**没有工具白名单**
+ * （`@deepseek-ai/dsh-mcp-client`），所以「只挂一部分 MCP 工具」做不到，只能在
+ * 可见性上掩。替代能力走 `ctx.ftshareData`（`ftshare_*` 与 `ftshare_call`），
+ * 这也是「替代接口必须进接口表」的硬理由。
+ *
+ * ### 为什么落到 agent 自己的 layer
+ *
+ * `ctx.tools.restrict()` 只过滤**继承来的**工具，永不过滤调用者自己层的注册
+ * （`@deepseek-ai/dsh-tools` 的 `view()`）。preset 行 ctx 的 scope 就是它的
+ * standing scope，kline 工具属于那一层的自有注册，在它上面 restrict 会直接抛
+ * `unknown global tool`。落到 agent 自己的 layer 还有两个好处：随 agent 销毁自动
+ * 解除，且只影响这一支。
+ *
+ * ### 四个坑（都实测过）
+ *
+ * 1. **未知名字会抛**：必须与当前可见集取交集再 restrict。
+ * 2. **`agent/created` 是串行监听**：监听器抛错会连带 agent 创建失败，因此这里
+ *    自己 try/catch 记 warn，绝不上抛。
+ * 3. **MCP 工具可能晚于 agent 创建到达**（stdio + 重连），所以同时监听
+ *    `tools/change`；掩掉的工具会从可见集消失，因此「交集」本身就是去重，不会
+ *    重复 append 限制。
+ * 4. **清单只有一处**：{@link MASKED_KLINE_TOOLS}，由 `dsh-fft-bundle` 的契约测试
+ *    断言它是 kline `server.py` 里 `@mcp.tool` 名字集合的子集。
+ * @module @dsh-ft/dsh-fft-ftshare/mask
+ */
+import { DEFAULT_MCP_SERVER_NAME } from './project.js';
+/** Cordis 插件名。 */
+export const name = '@dsh-ft/dsh-fft-ftshare/mask';
+/**
+ * 被掩掉的 kline 工具（MCP 公共名去掉 `mcp__<server>__` 前缀之后的那一段）。
+ *
+ * 只掩 FTShare wrapper：它们的实现直接连 FTShare 网关，凭据与错误语义都自成一套，
+ * 现在由本底座统一承接。「行情 / K 线 / 指标 / 自选」是 kline 的保留能力，一条都不
+ * 在这里。
+ *
+ * 边界由人定过一次（2026-10-16）：`configure_ftshare` / `test_ftshare_connection` /
+ * `data_source_status` **不掩** —— 它们属于 kline 自己的设置与自检面，掩掉会让
+ * kline 侧边栏的既有路径失效。
+ */
+export const MASKED_KLINE_TOOLS = [
+    'market_pulse',
+    'market_board_detail',
+    'security_intelligence',
+];
+/**
+ * 一个 kline 工具名对应的 MCP 公共名。
+ * @param tool - 短名，例如 `market_pulse`。
+ * @returns 公共名，例如 `mcp__dsh-kline__market_pulse`。
+ */
+export function publicToolName(tool) {
+    return `mcp__${DEFAULT_MCP_SERVER_NAME}__${tool}`;
+}
+/**
+ * 纯函数：算出这次该 deny 哪些名字。
+ *
+ * 与当前可见集取交集是必须的——`restrict` 对未知名字直接抛错。掩掉的工具会从可见集
+ * 消失，所以下一次调用自然只剩新到达的那些，不需要另记「已 deny 集合」。
+ * @param visible - 该 agent 当前可见的工具名。
+ * @returns 需要 deny 的名字，按 {@link MASKED_KLINE_TOOLS} 的顺序。
+ */
+export function maskPlan(visible) {
+    const names = new Set(visible);
+    return MASKED_KLINE_TOOLS.map(publicToolName).filter(name => names.has(name));
+}
+/**
+ * 注册掩码行。
+ * @param ctx - preset 子树的上下文（standing scope）。
+ */
+export function apply(ctx) {
+    const logger = ctx.logger('dsh-fft-ftshare-mask');
+    const host = ctx;
+    const live = new Set();
+    /**
+     * 给一个 agent 补上缺失的掩码。绝不抛：`agent/created` 是串行监听，抛错会连带
+     * agent 创建失败。
+     * @param agent - 目标 agent。
+     */
+    const applyMask = (agent) => {
+        try {
+            const deny = maskPlan(agent.ctx.tools.schemas(agent).map(tool => tool.name));
+            if (deny.length === 0)
+                return;
+            agent.ctx.tools.restrict({ deny });
+            logger.info('ftshare.kline_tools_masked', { tools: deny.join(',') });
+        }
+        catch (error) {
+            logger.warn('ftshare.mask_failed', { message: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    host.on('agent/created', ({ agent }) => {
+        live.add(agent);
+        agent.ctx.effect(() => () => { live.delete(agent); });
+        // MCP 工具可能晚到；先掩一次能掩的，剩下的交给 tools/change。
+        applyMask(agent);
+    });
+    host.on('tools/change', () => {
+        for (const agent of live)
+            applyMask(agent);
+    });
+}
+//# sourceMappingURL=mask.js.map

package/lib/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../src/mask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,kBAAkB;AAClB,MAAM,CAAC,MAAM,IAAI,GAAG,8BAA8B,CAAA;AAElD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,cAAc;IACd,qBAAqB;IACrB,uBAAuB;CACxB,CAAA;AA8BD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,QAAQ,uBAAuB,KAAK,IAAI,EAAE,CAAA;AACnD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAyB;IAChD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;IAC9B,OAAO,kBAAkB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY;IAChC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAA;IACjD,MAAM,IAAI,GAAG,GAA0B,CAAA;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAe,CAAA;IAEnC;;;;OAIG;IACH,MAAM,SAAS,GAAG,CAAC,KAAkB,EAAQ,EAAE;QAC7C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YAC5E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAM;YAC7B,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;YAClC,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACtE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACzG,CAAC;IACH,CAAC,CAAA;IAED,IAAI,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QACrC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACf,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC,CAAC,CAAA;QACpD,yCAAyC;QACzC,SAAS,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE;QAC3B,KAAK,MAAM,KAAK,IAAI,IAAI;YAAE,SAAS,CAAC,KAAK,CAAC,CAAA;IAC5C,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/lib/project.d.ts

@@ -0,0 +1,98 @@
+/**
+ * preset 平面：`tools/post-execute` 投影钩子。
+ *
+ * ### 它现在只做一件事
+ *
+ * `@ftshare-lab/dsh-kline` 的摘要式 MCP 工具把明细放进 `structuredContent`，
+ * `content` 只有一行 `fetch_candles · 600519.XSHG · rows=250`。DSH 的 MCP 桥只把
+ * `content` 投影给模型（`@deepseek-ai/dsh-mcp-client` 的 `createOutput`），所以模型
+ * 看不到那 250 行（**P7**）；而且这行摘要把「真的没有」「套餐无权限（网关 403
+ * `route_not_allowed`）」「取数失败」一律印成 `0`（**P8**）。
+ *
+ * 所以保留工具（K 线、指标、自选）的投影统一走通用渲染：摊开数组、写全标量、
+ * 空数组写「无数据」，绝不输出 `key=count` 这类裸计数。
+ *
+ * 三个「明细藏在 `structuredContent`」的重灾区（`security_intelligence` /
+ * `market_pulse` / `market_board_detail`）不再由本行接管：它们是 FTShare wrapper，
+ * 已被 `./mask` 从模型可见面掩掉，替代能力走 `ctx.ftshareData`（见设计 §6）。
+ *
+ * ### 三条约束写死在实现里
+ *
+ * 1. **只替换 `content`，绝不动 `value`**——同时给 `content` 和 `value` 会抛
+ *    `TypeError`（`postExecute` 里的显式检查）。
+ * 2. **绝不用 `block`**——那会把结果变成错误。
+ * 3. **形状不符就原样放行**（`return decision`）并记一条 warn，绝不吞结果。
+ *
+ * 钩子用 `ctx.on` 注册在 preset 子树里，DSH 对瀑布按 `exec.agent` 做作用域过滤，
+ * 因此**只有金融模式的 agent 受影响**，标准模式一个字都不变。
+ * @module @dsh-ft/dsh-fft-ftshare/project
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { FtshareCallResult } from './contract.js';
+/** MCP 公共名的服务器段：`mcp__<server>__<tool>`。缺省只接管 dsh-kline。 */
+export declare const DEFAULT_MCP_SERVER_NAME = "dsh-kline";
+/**
+ * 接管投影的工具（MCP 公共名去掉前缀之后的那一段）。
+ *
+ * 只列保留工具：FTShare wrapper 那三个已由 `./mask` 掩掉，不再需要投影。
+ * `analyze_kline` 不在列表里：它的 content 本身就是完整行情说明，重排它只会丢掉
+ * 信息。
+ */
+export declare const PROJECTED_TOOLS: readonly string[];
+/**
+ * 通用渲染：保留工具统一走它。
+ *
+ * 只做两件正确的事：把数组摊开、把标量写全。**不输出 `key=count` 这类裸计数**——
+ * 那正是 P8 的形态；数组为空时写「无数据」，不写 `0`。
+ * @param payload - 工具返回的 `structuredContent`。
+ * @returns 模型可见文本；没有可渲染内容时 undefined（放行原结果）。
+ */
+export declare function renderGenericPayload(payload: unknown): string | undefined;
+/**
+ * 把 MCP 公共名拆成服务器段与工具段。
+ * @param publicName - 形如 `mcp__dsh-kline__fetch_candles`。
+ * @returns 两段名字；不是 MCP 公共名时 undefined。
+ */
+export declare function mcpToolNameOf(publicName: string): {
+    server: string;
+    tool: string;
+} | undefined;
+/** 该工具是否由本包接管投影。 */
+export declare function isProjectedTool(tool: string): boolean;
+/**
+ * 纯函数：给公共工具名与结果值，产出替换用的文本。
+ * @param publicName - MCP 公共名。
+ * @param value - `ToolExecutionSuccess.value`（MCP 的 `{content, structuredContent}`）。
+ * @returns 模型可见文本；不接管或形状不符时 undefined。
+ */
+export declare function renderProjection(publicName: string, value: unknown): string | undefined;
+/**
+ * 纯函数：算出要替换的 `content`。
+ *
+ * 文本块被替换，非文本块（图片等）原样保留在末尾；失败结果与无可渲染内容一律
+ * 返回 undefined，由调用方原样放行。
+ * @param name - 公共工具名。
+ * @param result - 归一后的执行结果视图。
+ * @returns 新的 content 数组，或 undefined。
+ */
+export declare function projectContent(name: string, result: {
+    isError: boolean;
+    value?: unknown;
+    content: ContentBlock[];
+}): ContentBlock[] | undefined;
+/**
+ * 把一次 `ctx.ftshareData.call()` 的结果渲染成模型可见文本（工具平面与投影平面共用）。
+ * @param title - 中文标题。
+ * @param tool - 上游接口名。
+ * @param result - 归一结果。
+ * @returns 文本。
+ */
+export declare function renderCallResult(title: string, tool: string, result: FtshareCallResult): string;
+/**
+ * 注册投影钩子。必须在 preset 子树里挂载：DSH 对 `tools/post-execute` 按
+ * `exec.agent` 做作用域过滤，钩子只对所选 preset 的 agent 生效。
+ * @param ctx - preset 子树的上下文。
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=project.d.ts.map

package/lib/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAwBtD,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,cAAc,CAAA;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAM5C,CAAA;AAoGD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkDzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK9F;AAED,oBAAoB;AACpB,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,GACrE,YAAY,EAAE,GAAG,SAAS,CAM5B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAa/F;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAkCxC"}

package/lib/project.js

@@ -0,0 +1,326 @@
+/**
+ * preset 平面：`tools/post-execute` 投影钩子。
+ *
+ * ### 它现在只做一件事
+ *
+ * `@ftshare-lab/dsh-kline` 的摘要式 MCP 工具把明细放进 `structuredContent`，
+ * `content` 只有一行 `fetch_candles · 600519.XSHG · rows=250`。DSH 的 MCP 桥只把
+ * `content` 投影给模型（`@deepseek-ai/dsh-mcp-client` 的 `createOutput`），所以模型
+ * 看不到那 250 行（**P7**）；而且这行摘要把「真的没有」「套餐无权限（网关 403
+ * `route_not_allowed`）」「取数失败」一律印成 `0`（**P8**）。
+ *
+ * 所以保留工具（K 线、指标、自选）的投影统一走通用渲染：摊开数组、写全标量、
+ * 空数组写「无数据」，绝不输出 `key=count` 这类裸计数。
+ *
+ * 三个「明细藏在 `structuredContent`」的重灾区（`security_intelligence` /
+ * `market_pulse` / `market_board_detail`）不再由本行接管：它们是 FTShare wrapper，
+ * 已被 `./mask` 从模型可见面掩掉，替代能力走 `ctx.ftshareData`（见设计 §6）。
+ *
+ * ### 三条约束写死在实现里
+ *
+ * 1. **只替换 `content`，绝不动 `value`**——同时给 `content` 和 `value` 会抛
+ *    `TypeError`（`postExecute` 里的显式检查）。
+ * 2. **绝不用 `block`**——那会把结果变成错误。
+ * 3. **形状不符就原样放行**（`return decision`）并记一条 warn，绝不吞结果。
+ *
+ * 钩子用 `ctx.on` 注册在 preset 子树里，DSH 对瀑布按 `exec.agent` 做作用域过滤，
+ * 因此**只有金融模式的 agent 受影响**，标准模式一个字都不变。
+ * @module @dsh-ft/dsh-fft-ftshare/project
+ */
+import { asText, isRecord } from './errors.js';
+/** MCP 公共名的服务器段：`mcp__<server>__<tool>`。缺省只接管 dsh-kline。 */
+export const DEFAULT_MCP_SERVER_NAME = 'dsh-kline';
+/**
+ * 接管投影的工具（MCP 公共名去掉前缀之后的那一段）。
+ *
+ * 只列保留工具：FTShare wrapper 那三个已由 `./mask` 掩掉，不再需要投影。
+ * `analyze_kline` 不在列表里：它的 content 本身就是完整行情说明，重排它只会丢掉
+ * 信息。
+ */
+export const PROJECTED_TOOLS = [
+    'fetch_candles',
+    'calc_metrics',
+    'analyze_kline_rows',
+    'get_watchlist',
+    'save_watchlist',
+];
+/** 通用渲染的条数上限，避免把上下文灌满。 */
+const MAX_GENERIC_ITEMS = 8;
+/** 整段投影的字符上限；超长按行截断。 */
+const MAX_CHARS = 4000;
+/** 四态结局的中文名。 */
+const STATE_LABELS = {
+    available: '可用',
+    empty: '无数据',
+    denied: '无权访问',
+    failed: '取数失败',
+};
+/** 读数组；非数组得空数组。 */
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** 读记录数组；过滤掉非对象元素。 */
+function asRecords(value) {
+    return asArray(value).filter(isRecord);
+}
+/**
+ * 「情报卡片」已经占用的字段；兜底渲染时要跳过，免得同一字段出现两次。
+ * 形状见 `dsh-kline` 的 `_intelligence_item` / `_flow_history_items`。
+ */
+const ITEM_KEYS = new Set(['title', 'value', 'change', 'detail', 'tone']);
+/**
+ * 把一条记录渲染成一行。
+ * @param row - 明细行。
+ * @param label - 是否给 value 加「净额」、change 加「占比」这类业务标签。
+ * @returns 一行文本，或 undefined（整行没有任何可读字段）。
+ */
+function itemLine(row, label) {
+    const value = asText(row.value);
+    const change = asText(row.change);
+    const parts = [
+        asText(row.title),
+        value === undefined ? undefined : label ? `净额 ${value}` : value,
+        change === undefined ? undefined : label ? `占比 ${change}` : change,
+        asText(row.detail),
+    ].filter((part) => part !== undefined);
+    if (parts.length === 0) {
+        // 不是情报卡片（例如原始 K 线行）就如实摊开标量字段，总比什么都不显示强。
+        for (const [key, field] of Object.entries(row)) {
+            if (ITEM_KEYS.has(key) || field === null || field === undefined || typeof field === 'object')
+                continue;
+            parts.push(`${key} ${String(field)}`);
+        }
+    }
+    return parts.length === 0 ? undefined : parts.join(' · ');
+}
+/**
+ * 渲染一组明细，带条数上限。
+ * @param rows - 明细行。
+ * @param cap - 最多渲染条数。
+ * @param label - 传给 {@link itemLine} 的标签开关。
+ * @returns 渲染出的行数组。
+ */
+function renderItems(rows, cap, label) {
+    const lines = [];
+    let printed = 0;
+    for (const row of rows.slice(0, cap)) {
+        const rendered = itemLine(row, label);
+        if (rendered === undefined)
+            continue;
+        printed += 1;
+        lines.push(`${printed}. ${rendered}`);
+    }
+    if (rows.length > cap)
+        lines.push(`（共 ${rows.length} 条，此处只显示前 ${cap} 条）`);
+    return lines;
+}
+/** 数据来源行。 */
+function sourceLine(source) {
+    const record = isRecord(source) ? source : undefined;
+    if (record === undefined)
+        return undefined;
+    const name = asText(record.name);
+    const updated = asText(record.updated_at) ?? asText(record.updatedAt) ?? asText(record.fetchedAt);
+    const status = asText(record.status);
+    const parts = [name, updated ?? status].filter((part) => part !== undefined);
+    return parts.length === 0 ? undefined : `数据源 ${parts.join(' · ')}`;
+}
+/**
+ * 收口：拼行、去空、限长。
+ * @param lines - 渲染出的行。
+ * @returns 文本，或 undefined（没有任何可渲染内容时放行原结果）。
+ */
+function finish(lines) {
+    const text = lines.filter(line => line.trim() !== '').join('\n');
+    if (text === '')
+        return undefined;
+    if (text.length <= MAX_CHARS)
+        return text;
+    const cut = text.lastIndexOf('\n', MAX_CHARS);
+    return `${text.slice(0, cut > 0 ? cut : MAX_CHARS)}\n…（内容过长，已截断）`;
+}
+/**
+ * 通用渲染：保留工具统一走它。
+ *
+ * 只做两件正确的事：把数组摊开、把标量写全。**不输出 `key=count` 这类裸计数**——
+ * 那正是 P8 的形态；数组为空时写「无数据」，不写 `0`。
+ * @param payload - 工具返回的 `structuredContent`。
+ * @returns 模型可见文本；没有可渲染内容时 undefined（放行原结果）。
+ */
+export function renderGenericPayload(payload) {
+    const lines = [];
+    /**
+     * 递归摊平一层层对象；数组只摊开一层元素。
+     * @param value - 当前值。
+     * @param prefix - 键路径前缀。
+     * @param depth - 当前深度，限制在 3 层内。
+     */
+    const walk = (value, prefix, depth) => {
+        if (Array.isArray(value)) {
+            const rows = value.filter(isRecord);
+            if (value.length === 0) {
+                lines.push(`${prefix}：无数据`);
+                return;
+            }
+            if (rows.length === 0) {
+                lines.push(`${prefix}（${value.length} 条）：${value.slice(0, MAX_GENERIC_ITEMS).map(item => String(item)).join('、')}`);
+                return;
+            }
+            const rendered = renderItems(rows, MAX_GENERIC_ITEMS, false);
+            lines.push(`${prefix}（${value.length} 条）`, ...rendered);
+            return;
+        }
+        if (isRecord(value)) {
+            if (prefix === 'source' || prefix === 'metadata')
+                return;
+            if (depth >= 3) {
+                lines.push(`${prefix}：${Object.keys(value).length} 个字段`);
+                return;
+            }
+            const keys = Object.keys(value).filter(key => key !== 'metadata' && key !== 'source');
+            if (keys.length === 0) {
+                lines.push(`${prefix}：无数据`);
+                return;
+            }
+            for (const key of keys)
+                walk(value[key], prefix === '' ? key : `${prefix}.${key}`, depth + 1);
+            return;
+        }
+        if (value === null || value === undefined)
+            return;
+        lines.push(`${prefix}：${String(value)}`);
+    };
+    if (!isRecord(payload))
+        return undefined;
+    const envelope = new Set(['ok', 'success', 'cached', 'metadata', 'source']);
+    for (const [key, value] of Object.entries(payload)) {
+        if (envelope.has(key))
+            continue;
+        walk(value, key, 1);
+    }
+    const source = sourceLine(payload.source);
+    if (source !== undefined)
+        lines.push(source);
+    return finish(lines);
+}
+/**
+ * 把 MCP 公共名拆成服务器段与工具段。
+ * @param publicName - 形如 `mcp__dsh-kline__fetch_candles`。
+ * @returns 两段名字；不是 MCP 公共名时 undefined。
+ */
+export function mcpToolNameOf(publicName) {
+    const matched = /^mcp__(.+?)__(.+)$/u.exec(publicName);
+    if (matched === null)
+        return undefined;
+    const [, server, tool] = matched;
+    return server === undefined || tool === undefined ? undefined : { server, tool };
+}
+/** 该工具是否由本包接管投影。 */
+export function isProjectedTool(tool) {
+    return PROJECTED_TOOLS.includes(tool);
+}
+/**
+ * 纯函数：给公共工具名与结果值，产出替换用的文本。
+ * @param publicName - MCP 公共名。
+ * @param value - `ToolExecutionSuccess.value`（MCP 的 `{content, structuredContent}`）。
+ * @returns 模型可见文本；不接管或形状不符时 undefined。
+ */
+export function renderProjection(publicName, value) {
+    const parsed = mcpToolNameOf(publicName);
+    if (parsed === undefined || parsed.server !== DEFAULT_MCP_SERVER_NAME)
+        return undefined;
+    if (!isProjectedTool(parsed.tool))
+        return undefined;
+    // MCP 桥的 value 是 `{content, structuredContent}`；明细只在后者里。
+    const payload = isRecord(value) && value.structuredContent !== undefined ? value.structuredContent : value;
+    return renderGenericPayload(payload);
+}
+/**
+ * 纯函数：算出要替换的 `content`。
+ *
+ * 文本块被替换，非文本块（图片等）原样保留在末尾；失败结果与无可渲染内容一律
+ * 返回 undefined，由调用方原样放行。
+ * @param name - 公共工具名。
+ * @param result - 归一后的执行结果视图。
+ * @returns 新的 content 数组，或 undefined。
+ */
+export function projectContent(name, result) {
+    if (result.isError)
+        return undefined;
+    const text = renderProjection(name, result.value);
+    if (text === undefined)
+        return undefined;
+    const preserved = result.content.filter(block => block.type !== 'text');
+    return [...preserved, { type: 'text', text }];
+}
+/**
+ * 把一次 `ctx.ftshareData.call()` 的结果渲染成模型可见文本（工具平面与投影平面共用）。
+ * @param title - 中文标题。
+ * @param tool - 上游接口名。
+ * @param result - 归一结果。
+ * @returns 文本。
+ */
+export function renderCallResult(title, tool, result) {
+    const lines = [`${title}（${tool}）：${STATE_LABELS[result.state] ?? result.state}`];
+    const notice = result.notice;
+    if (notice !== undefined) {
+        lines.push(`⚠ ${notice.message}`);
+        if (notice.requiredPlan !== undefined)
+            lines.push(`所需订阅：${notice.requiredPlan}`);
+        if (notice.upgradeUrl !== undefined)
+            lines.push(`升级入口：${notice.upgradeUrl}`);
+        if (notice.retryable)
+            lines.push('该失败可重试。');
+    }
+    if (result.state === 'available')
+        lines.push(...renderItems(result.rows, MAX_GENERIC_ITEMS, false));
+    if (result.state === 'empty')
+        lines.push('上游返回成功、没有权限限制标记，只是没有记录。');
+    lines.push(sourceLine(result.source) ?? `数据源 FTShare · ${result.source.fetchedAt}`);
+    return lines.join('\n');
+}
+/**
+ * 注册投影钩子。必须在 preset 子树里挂载：DSH 对 `tools/post-execute` 按
+ * `exec.agent` 做作用域过滤，钩子只对所选 preset 的 agent 生效。
+ * @param ctx - preset 子树的上下文。
+ */
+export function apply(ctx) {
+    const logger = ctx.logger('dsh-fft-ftshare-projection');
+    const host = ctx;
+    host.on('tools/post-execute', async (exec, result, next) => {
+        // 先让下游听完：本钩子只做「补充投影」，不该改变别人的决定。
+        const decision = await next();
+        try {
+            if (result.isError)
+                return decision;
+            const parsed = mcpToolNameOf(exec.name);
+            if (parsed === undefined || parsed.server !== DEFAULT_MCP_SERVER_NAME || !isProjectedTool(parsed.tool))
+                return decision;
+            // 下游若整块替换了 value，或把结果判成失败，就别再动 content。
+            if (decision.kind === 'block' || Object.hasOwn(decision, 'value'))
+                return decision;
+            const content = projectContent(exec.name, { isError: result.isError, value: result.value, content: result.content });
+            if (content === undefined) {
+                const payload = isRecord(result.value) && result.value.structuredContent !== undefined ? result.value.structuredContent : result.value;
+                logger.warn('ftshare.projection_shape_mismatch', {
+                    tool: exec.name,
+                    keys: isRecord(payload) ? Object.keys(payload).join(',') : typeof payload,
+                });
+                return decision;
+            }
+            return {
+                kind: 'accept',
+                content,
+                ...(decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {}),
+            };
+        }
+        catch (error) {
+            logger.warn('ftshare.projection_failed', {
+                tool: exec.name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return decision;
+        }
+    });
+}
+//# sourceMappingURL=project.js.map

package/lib/project.js.map

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

package/lib/route.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 宿主助手：把 `ctx.ftshareData` 挂到跨平面路由上（**消费方自己挂**）。
+ *
+ * 底座不声明 `dsh.client` —— 它不是客户端面，只发布两段实现。需要浏览器取数的消费方
+ * 自己挂这一行：
+ *
+ * ```ts
+ * ctx.inject(['connection', 'ftshareData'], scope =>
+ *   scope.effect(() => registerFtshareRoute(scope.ctx, scope.ftshareData), 'ftshare: /api route'))
+ * ```
+ *
+ * 路由是 `connection.fetch` 的**精确**路由，复用 `/api` 载体的 Host/Origin 围栏与
+ * 浏览器鉴权。契约（设计 §5.1）：
+ *
+ * - **原样过桥**：成功就是一份 `FtshareCallResult`，`notice` 与 `upgradeUrl` 一起带，
+ *   面板才能把「没权限」渲染成「去升级」而不是「没有数据」；
+ * - **接口名校验**：只接受目录里的接口名，否则 400 —— 底座不能变成任意上游的穿透代理；
+ * - **取消与超时**：`request.signal` 原样转给 `call({ signal })`，面板的连点与切标的
+ *   因此能真的取消掉在途请求。
+ * @module @dsh-ft/dsh-fft-ftshare/route
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type FtshareDataService } from './contract.js';
+/** 交给 `connection.fetch.register` 的精确路由定义。 */
+export interface FtshareRoute {
+    /** 精确路径，不接受通配。 */
+    readonly path: string;
+    /** 允许的方法。 */
+    readonly methods: readonly string[];
+    /** 载体预读请求体的方式。 */
+    readonly requestBody: 'buffered';
+    /** 处理一次请求。 */
+    readonly fetch: (request: Request) => Promise<Response>;
+}
+/**
+ * 造一条只回答 `/api/ftshare-data` 的路由定义（纯函数，便于测试）。
+ * @param data - 宿主侧的 `ctx.ftshareData`。
+ * @returns 路由定义。
+ */
+export declare function createFtshareRoute(data: FtshareDataService): FtshareRoute;
+/**
+ * 注册路由；调用方自己决定挂在哪一层（返回值就是载体的 disposer）。
+ * @param ctx - 已经 inject 到 `connection` 的上下文。
+ * @param data - 宿主侧的 `ctx.ftshareData`。
+ * @returns 载体的注销函数，交给 `ctx.effect` 管。
+ */
+export declare function registerFtshareRoute(ctx: Context, data: FtshareDataService): () => Promise<void>;
+//# sourceMappingURL=route.d.ts.map

package/lib/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAG3E,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,aAAa;IACb,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAA;IAChC,cAAc;IACd,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CACxD;AAOD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,YAAY,CAoBzE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAKhG"}