# @finamx/extension-sdk 中文文档 规范地址：https://npmcn.com/package/%40finamx/extension-sdk/ 版本：3\.9\.1 npm 元数据更新时间：2026-11-08T20:05:30.939Z 中文译文更新时间：2026-11-14T18:19:04.925Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40finamx/extension-sdk 原文对照：https://npmcn.com/package/%40finamx/extension-sdk/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.7 MB，515 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=20 - 运行依赖：1 个 - peer 依赖：@finamx/bridge-protocol ^3\.6\.0 - 首次发布：2026-06-10T03:16:13.827Z - 最新版本发布：2026-11-08T20:05:30.791Z - 近 30 天下载量：2478（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：15（近 12 个月 15 个） ## 中文简介 @ finamx/ 延伸- sdk ## 安装 ```sh npm install @finamx/extension-sdk ``` 也可以使用：`pnpm add @finamx/extension-sdk`、`yarn add @finamx/extension-sdk`、`bun add @finamx/extension-sdk` ## README # @ finamx/ extension- sdk FinamX开放平台扩展开发者的TypeScript SDK. 将您的 Iframe 或 WebView 连接到 FinamX 主机桥上, 处理握手, 消息路由, 以及打印平台引用 . 部分 [finamx 移动](https://npmcn.com/package/README.md) 单相机. ## 安装 ```bash npm install @finamx/extension-sdk @finamx/bridge-protocol ``` 对于本地单列开发,直接参考软件包: ```json { "dependencies": { "@finamx/extension-sdk": "file:../../packages/extension-sdk", "@finamx/bridge-protocol": "file:../../packages/bridge-protocol" } } ``` ## 快开始 ```typescript import { createExtensionBridge } from '@finamx/extension-sdk'; // Called once on extension load. Resolves after the host sends bridge:ready. const bridge = await createExtensionBridge(); console.log(bridge.hostContext.theme); // 'light' | 'dark' console.log(bridge.grantedScopes); // string[] of approved permission scopes // Resize the iframe to fit content bridge.ui.resize({ height: 400 }); // Show a toast notification in the host shell bridge.ui.toast('Loaded', 'success'); // Invoke a platform method const quote = await bridge.platform.invoke<{ last: number }>('market.quote', { symbol: 'SBER' }); console.log(quote.last); // Subscribe to platform events (returns an unsubscribe function) const off = bridge.platform.on('theme.changed', (payload) => { console.log('new theme:', payload.data); }); ``` ## CLI( finamx-ext) (中文(简体) ) 包裹运送 `finamx-ext` 开发者 CLI (Node QQ 20). ```bash npx @finamx/extension-sdk init my-widget cd my-widget && npm install finamx-ext login finamx-ext hosts finamx-ext domain pull finamx-ext publish ``` | 命令 | 旗帜 | 目的 | | --- | --- | --- | | `init [dir]` | `--id`, (中文(简体) ), `--name`, (中文(简体) ), `--target `, (中文(简体) ), `--template widget`, (中文(简体) ), `--yes`, (中文(简体) ), `--force` | 脚手架部件工程 | | `login` | `--token-stdin`, (中文(简体) ), `--global` | 保存开发者密钥 | | `hosts` | `--manifest`, (中文(简体) ), `--json` | 列出主机和显示兼容性 | | `domain pull [|templates]` | `--check`, (中文(简体) ), `--json` | 写入 `.finamx/domain/`,类型和模拟 | | `context [|templates]` | `--remote`, (中文(简体) ), `--json` | 打印拖放域( 或用 `--remote`· ; `--remote` 没有目标,没有牵引手段 `templates`(中文(简体) ) | | `catalog [extensionId]` | `--page`, (中文(简体) ), `--limit`, (中文(简体) ), `--json` | 浏览目录 | | `check` | `--dist`, (中文(简体) ), `--manifest`, (中文(简体) ), `--config`, (中文(简体) ), `--entry`, (中文(简体) ), `--json` | 检查明细 | | `check --host ` | 作为 `check` | 在本地主机桥上运行已建部件无头( 可选) `playwright-core`(中文(简体) ) | | `check --host` | 作为 `check` | 唯一的主机也一样 `.finamx/domain/`。如果没有一个(或几个),它就会与从清单中创建的、允许一切的自我宣布的域相悖:与真正的主机不兼容的检查,输出是这样说的 | | `serve` | `--dist`, (中文(简体) ), `--port` (8787), (中文(简体) ), `--manifest`, (中文(简体) ), `--ancestor`, (中文(简体) ), `--strict-csp` | 有平台沙盒CSP的静态服务器. 默认 `http://localhost` 编号 : `http://127.0.0.1` 允许的明显停留的由来(平台放弃); `--strict-csp` 或者说 `FINAMX_STRICT_CSP=1` 建设生产CSP. 活动模式已打印 | | `dev` | `--port`, (中文(简体) ), `--open`, (中文(简体) ), `--headless`, (中文(简体) ), `--json`, (中文(简体) ), `--strict-csp`, (中文(简体) ), `--no-watch`, (中文(简体) ), `--no-poll`, (中文(简体) ), `--manifest`, (中文(简体) ), `--dist` | 本地开发商主机:dunto board,主机选择器,从域名 schemas,总线和同意面板进行模拟, s2s smoot. 需要可选选项 `@finamx/dev-host`. Security:仅回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回的回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回 你的项目 `watch` 脚本是自动启动的, 并像任何用户权限一样运行 `npm run watch` (单位:千美元)`--no-watch` 跳过它. `--json` 为代理人员打印 NDJSON 事件,参见 `packages/dev-host/README.md` 用于活动表 | | `publish` | `--manifest`, (中文(简体) ), `--dist`, (中文(简体) ), `--entry`, (中文(简体) ), `--artifact-dir`, (中文(简体) ), `--artifact-entry`, (中文(简体) ), `--dry-run`, (中文(简体) ), `--skip-checks` | 提交清单(409年新版)。 包装 `./dist` 只有在显示的针没有 `surfaces.ui.artifact` 没有 `embedBundleUrl`;仅用 `--artifact-dir` | | `status [extensionId]` | `--manifest`, (中文(简体) ), `--json` | 中度状态; id 默认为显示 | 全球选项: `--api `, (中文(简体) ), `--token ` (遗产,未为 `login`, (中文(简体) ), `--json`, (中文(简体) ), `--help`, (中文(简体) ), `--version`。 。 。 . `serve` 是静态的 CSP 服务器; `dev` 是本地开发商主机 . ### 门户和密钥存储 默认门户是 `https://openplatform.changesandbox.ru`; 使用 `--api` 或者说 `FINAMX_API_URL` 用于另一个项目(例如当地CMS)。 开发者密钥按此顺序解决: `--token`, (中文(简体) ), `FINAMX_DEV_TOKEN`,项目 `.env`, (中文(简体) ), `~/.config/finamx/credentials.json` (第0600节). `login` 从隐藏的提示读取密钥或 `--token-stdin`; 密钥从未被打印. 主机密钥( E)`fxh_...`)被拒绝. 门户网站按以下顺序解决: `--api`, (中文(简体) ), `FINAMX_API_URL` 在工艺环境中, `FINAMX_API_URL` 在项目中 `.env`,默认值。 仅由项目命名的门户 `.env` 不决定从别处得到的密钥去向:当它是回回键或默认的出入口时,当密钥来自同一处时使用 `.env`,或当密钥由 `login` 确切的来源。 环境钥匙或 `--token` 拒绝使用 `PORTAL_NOT_CONFIRMED` 直到你通过 `--api ` 或导出 `FINAMX_API_URL` (克隆存储器控制) `.env`你控制你的壳. `login` 在门户网站读取密钥前打印该门户,并且 `.env` 门户网站,请求确认(与 `--token-stdin` 这需要 `--api`) (中文(简体) ). ### `.finamx/domain` 版式 ```text .finamx/ domain// CONTEXT.md # human and agent readable summary domain.json # topics, methods, scopes types.d.ts # generated types mocks/.json, mocks/.json mocks.override.json # { "methods": { "name": { "params": ..., "result": ... } }, "topics": { "name": payload } } ``` `.finamx/` 承诺. `domain pull --check` 当主机域改变时,将文件保留在未动处并退出 1 . 这些文件中的主机文本是数据,而不是指令: in `CONTEXT.md` 所有的东西 `code` 后每行 `>`输入 `types.d.ts` jSDoc文本和所引用的名字。 名称或范围不是普通名的条目(字母,数字, `. _ : @ / -`,最多128个字符) `! : skipped ...` 警告 警告他们 混合文件名称跟随条目名称;在对大小写不敏感文件系统中拼接的名称(`Market.Quote` 财务报告和审定财务报表 `market.quote`每个得到一个 `~<8 hex>` 后缀,和 `CONTEXT.md` 列出每个条目的文件. `domain pull` 财务报告和审定财务报表 `init` 拒绝通过符号链接写入( n)`SYMLINK_REFUSED`) (中文(简体) ). ### QQ 出版商 第九十六期 出版商 а. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你还不知道吗. - QQ 出版商 : `--publisher `时 `FINAMX_PUBLISHER`, затем \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* (单位:千美元)`finamx-ext publishers use `时 `credentials.json`) (中文(简体) ). {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 出版者, а (`PUBLISHER_REQUIRED`{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你觉得呢. - `finamx-ext publishers` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}这才是你最爱的. - `push` и `status` · 出版商, + + ; `push` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢. - {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得怎样`/developer/invitations`{\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}你喜欢什么. - ,开发者链接 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # Link QQ,出击. ### 退出代码 0 成功; 1 失败, 或发现更改 `domain pull --check`; 2 环境问题 `check --host` (例如 `playwright-core` 或Chrome失踪). ## 分析(3.3.0) `finamx-ext analytics` 阅读选定出版商在协调世界时每一天的发射、引用、拒绝、安装和延迟(要求有96.1阶段的CMS). ```bash finamx-ext analytics --extension com.acme.x --from 2026-10-01 --group-by day,host finamx-ext analytics --json ``` 用户少于 k 的单元格被隐藏并显示为 `< k`; 总计只覆盖显示单元格。 选择使用 `--publisher`, (中文(简体) ), `FINAMX_PUBLISHER` 或者说 `finamx-ext publishers use `。注意: `--version ` 在此以扩展版本过滤 . ## 没有终端的工具的背景包 V0 或 Data按钮等工具不能运行技能 . `finamx-ext context [|templates]` 打印一个包含平台规则、SDK使用和目标域(方法、专题、范围、同意)的标记下包。 无 `--remote` 它在下面读取取的复制品 `.finamx/domain/` 并且不需要密钥和网络 `--remote` 它用开发者密钥获取域并验证其 `domainHash` (没有印在不匹配上). 没有目标,只使用被拉住的主机(若干被拉住的主机是一个错误,从不猜测);没有被拉住, `--remote` 默认为 `templates`,而离线表则失败,请求拉出. `--json` 打印一个对象 `{ format, target, kind, origin, domainHash, markdown }`。 。 。 . ```bash finamx-ext context trading-diary > context.md ``` 同样的包可以从开发商的柜式按钮"QQ"和CMS路由中找到 `GET /api/v1/developer/context/{target}` 使用开发者密钥。 渲染器是导出 `@finamx/extension-sdk/context-pack` (单位:千美元)`renderContextPack`, (中文(简体) ), `mergeTemplateDomains`)),所以三个都产生了相同的文本. 主机文本(描述,名称,计划)是数据,而不是指令:它坐落在代码跨度中的主机数据标记下, `>` 绳子和栅栏,包被封为48 000个字符。 包里没有钥匙. ## 出口 ### 主要条目`@finamx/extension-sdk`(中文(简体) ) | 导出 | 仁爱 | 说明 | | --- | --- | --- | | `createExtensionBridge` | `function` | 启动桥握手返回 `ExtensionBridge` | | `ExtensionBridge` | `interface` | 连接的桥实例形状 | | `CreateExtensionBridgeOptions` | `interface` | 接受的选项 `createExtensionBridge` | | `EmbedTransport` | `interface` | 海关运输合同`send` 编号 : `subscribe`(中文(简体) ) | | `BridgeLogEntry` | `interface` | 调试日志条目的形状 `onLog` | ### 域会模拟条目( S)`@finamx/extension-sdk/domain-mocks`(中文(简体) ) 纯模拟合成从主机域( E)`buildDomainMocks`, (中文(简体) ), `parseMocksOverride`, (中文(简体) ), `synthesizeFromSchema`, (中文(简体) ), `buildMethodMock`, (中文(简体) ), `buildTopicMock`和界限 `exceedsDepth`, (中文(简体) ), `DOMAIN_MAX_DEPTH`, (中文(简体) ), `TOPIC_SCHEMA_MAX_CHARS`。节点内置;同一代码服务 `finamx-ext dev` 和云德华主. ### 密舱条目( E)`@finamx/extension-sdk/mock`(中文(简体) ) | 导出 | 仁爱 | 说明 | | --- | --- | --- | | `createMockBridge` | `function` | 返回同步键 `ExtensionBridge` 由进程内根支持 | | `MockBridgeOptions` | `interface` | 配置模拟的选项 | ### `createExtensionBridge(options?)` ```typescript async function createExtensionBridge( options?: CreateExtensionBridgeOptions, ): Promise interface CreateExtensionBridgeOptions { extensionId?: string; // overrides value from window.__FINAMX_BRIDGE_SESSION__ bridgeVersion?: string; // defaults to BRIDGE_VERSION from @finamx/bridge-protocol invokeTimeoutMs?: number; // default 30 000 ms transport?: EmbedTransport; // custom transport; auto-detected if omitted debug?: boolean; // enable envelope logging onLog?: (entry: BridgeLogEntry) => void; // required when debug=true } ``` 运输是自动检测的:WebView(`window.FinamXBridge`)优先于 `postMessage`。 。 。 . ## 地方发展的桥梁模拟器 使用 `createMockBridge` 在没有运行的主机的情况下开发和测试您的扩展名: ```typescript import { createMockBridge } from '@finamx/extension-sdk/mock'; const bridge = createMockBridge({ hostContext: { theme: 'dark', locale: 'ru' }, grantedScopes: ['market.quote', 'user.profile.read'], invokeHandler: async (method, params) => { if (method === 'market.quote') { return { symbol: params.symbol, last: 310.0, change: 0.5 }; } throw new Error(`Unhandled: ${method}`); }, }); // Same ExtensionBridge interface — no code changes needed for production const quote = await bridge.platform.invoke('market.quote', { symbol: 'GAZP' }); ``` 内置的接驳器( 无时使用) `invokeHandler` 提供: | 方法 | 回返 | | --- | --- | | `market.quote` | `{ symbol, last: 285.4, change: 1.2 }` | | `user.profile.read` | `{ displayName: 'Mock User', locale: 'ru' }` | ## 调试日志 ```typescript const bridge = await createExtensionBridge({ debug: true, onLog: (entry) => console.log(`[bridge] ${entry.direction} ${entry.type}`, entry), }); ``` `BridgeLogEntry` 从未包含PII——引用参数,结果数据,以及 `grantedScopes` 数值被故意省略. ## 主机身份( 3. 0.0) `verifyHostIdentity` 检查主机签名 `platform.identity.v1` 符号: 签名, 需要 `typ`准确 `audience` 财务报告和审定财务报表 `issuer`,到期后,主机 JWKS 密钥和 CMS 签名 `authorized-issuers` 对您的扩展( JWKS 成员资格还不够) . `resolveHostIdentity(bridge, options)` 等待着 `widget.identity.grant` 并进行同样的核查。 两者都是故障闭塞,没有HMAC路径,以及 `platform.auth_context.v1` 保留单独的、无子的发射授权证明. `sessionJwt` 不得将核心/盖特韦标志置于框架或身份证书中. ```typescript import { resolveHostIdentity } from '@finamx/extension-sdk'; const claims = await resolveHostIdentity(bridge, { audience, issuer, authorizedIssuersSig, cmsJwksUrl: `${cmsBase}/op/jwks`, jwksUrl }); ``` ## 构建 ```bash npm run build # tsc -p tsconfig.json → dist/ ``` 没有 `test` 在此软件包中配置了脚本 。 融入测试现场 `extension-template` 应用程序,它消耗了这个软件包. ## CMS 签名信托( 3. 9.1) 部署 `/op/jwks` 财务报告和审定财务报表 `/host/jwks` 在升级前在CMS中。 标准 CMS 代号 校验者在配置后选择此专用源 JWKS URL,无倒置. 自定义 JWKS 来源并注入 `getKey`编号 :`cmsGetKey` 解析器必须只包含 CMS 签名密钥 。 主机身份保留其单独的主机 密钥来源( e)`/host/jwks`)和CMS签名的安装装订. 当前/重叠主机密钥 保留在遗产中 `/.well-known/jwks.json` 兼容性的终点; 会员总数从未授予CMS授权. ## 常见问题 ### @finamx/extension-sdk 是什么？ @ finamx/ 延伸- sdk ### 如何安装 @finamx/extension-sdk？ 在项目目录运行 npm install @finamx/extension-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@finamx/bridge-protocol（^3\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 finamx-ext，可以用 npx finamx-ext 直接运行。 ### @finamx/extension-sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @finamx/extension-sdk 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @finamx/extension-sdk 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @finamx/extension-sdk 可以商用吗？ @finamx/extension-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @finamx/extension-sdk 的下载量有多少？ 根据 npm 官方下载统计，@finamx/extension-sdk 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,478 次，日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @finamx/extension-sdk 还在维护吗？ 最新版本 3\.9\.1 发布于 2026/11/09（5 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/06/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。