# @haneinfo/plugin-api 中文文档

规范地址：https://npmcn.com/package/%40haneinfo/plugin-api/

版本：1\.29\.1
npm 元数据更新时间：2026-11-17T01:10:04.223Z
中文译文更新时间：2026-11-17T07:40:07.621Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40haneinfo/plugin-api
原文对照：https://npmcn.com/package/%40haneinfo/plugin-api/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：794 kB，192 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2026-10-02T05:26:17.529Z
- 最新版本发布：2026-11-17T01:10:04.011Z
- 近 30 天下载量：9899（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

Haneinfo 插件合同: 显示 v1 类型和 JSON Schema, 稳定能力符, 定义 Plugin (), 生命周期/诊断合同, 显示加载器和依赖解析器.

## 安装

```sh
npm install @haneinfo/plugin-api
```

也可以使用：`pnpm add @haneinfo/plugin-api`、`yarn add @haneinfo/plugin-api`、`bun add @haneinfo/plugin-api`

## README

# @ haneinfo/ plugin- api

框架中立插件显示、能力和生命周期合同。 生命周期跑者 可从 `@haneinfo/plugin-api/runtime`。 。 。 .

## 合作生命周期的取消

跑者提供可选的 `context.signal` 每一个生命周期的钩子。 现有背景 对象和钩子仍然有效。 每次引用都收到新的信号,包括停止引用. 传出可以取消I/O的信号,在获取资源前检查,并在钩子结算前加入所有初始化/取消童工的工作. 钩子不能 拆分初始化承诺,日后可以获取资源. 长期背景工作 启动时必须有关闭的拥有者在资源崩溃前停止并加入它.

```ts
import type { PluginLifecycleHooks } from '@haneinfo/plugin-api';

const lifecycle: PluginLifecycleHooks = {
  async register(context) {
    try {
      context.signal?.throwIfAborted();
      await connectResources({ signal: context.signal });
      context.signal?.throwIfAborted();
      await registerSubscriptions({ signal: context.signal });
    } catch (error) {
      await releasePartialResources();
      throw error;
    }
  },
  async shutdown(context) {
    // Must tolerate missing or already-released resources.
    await releaseResources({ signal: context.signal });
  },
};
```

这些资源功能是针对应用程序的。 起动钩的承诺必须涵盖它的获得, 取消和部分清理; 达成承诺是跑者安全拆卸的边界. 使用 `finally` 在适当情况下。 关闭必须是一能的,并容忍部分登记.

启动阶段的超时请求取消并中止启动,即使是可选实例也是如此. 与普通错误和解的可选钩子保持其表征的降解政策. 直线呼叫者必须呼叫 `shutdown()` 终止后, 巢穴主机这样做 当初始化失败时自动; 它不依赖于后端 `app.close()`。 。 。 .

关机要等机上钩子 才说要清理或拆掉 先前开始的提供者。 现有的逐一停产预算限制在等待和 它的清理。 如果钩子超过预算, 关闭返回报告并恢复倒序 钩子解决后自动清理. 从未到达寄存器的验证钩 等待,但没有得到 关闭引用。 并行/重复的关闭电话不 又引一清净钩. 报告超时停机钩和 保留其余实例.

`HostShutdownResult` 保留现有的结果字符串并添加 `pendingCleanup` 财务报告和审定财务报表 `diagnostics`。无空 `pendingCleanup` 表示尚未确认释放资源; `shutdown-completed-with-reported-timeout` 表示报告证结束,不是所有的钩子 停下来。 显示目录条目 `cleanupPending`。 。 。 . `runner.cleanupDiagnostics` 和巢穴目录 刷新等待诊断作为后期清理结算. 返回的停产结果和生命周期 事件是快照/历史;在最终清理后,历史的超时.

信号无法强制停止 JavaScript 。 忽略取消的后遗症钩子可能继续存在 获得资源直至其解决; 推迟清理等待解决。 钩子 永不和解, 屏蔽事件循环, 或解锁工作无法在此过程中安全地停止 . 启动仍然失败,自有进程/监督员必须在清理时终止这一进程 无法完成 。 图书馆不打电话 `process.exit()` 或终止主机本身.

抓取界面保留新报告字段的可选类型, 因此已有测试双倍 返回仅生成结果/事件。 真正的跑道和绳索总是提供两者.

取消意识主机和 testkit 需要插件- api `^1.5.0`释放他们必须包括: 匹配的插件- api 次要; 这不需要更改现有的钩子签名 .

## 合同编号

`NUMBERING` 编号 : `haneinfo.numbering` 绑定 `NumberingPort.allocate({ scope, at }, tx)`。来电者 必须提供提交交易; 提供者不得独立承诺或分配. 只有国家机器过渡使用这个口. 运行时间的可选性 `queryNumberedFor` 方法 为国家机器 MCP 工具提供授权的、仅限读的查询.

定义类型可以实施 `validatePublishedChange(previous, next)` 保护变化性 发表后。 定义登记处将其应用于运行时的草稿写作、出版和重播 同步 。 根据现行通用登记册规则,元数据.编码仍然不可改变.

## 背景工作和实例清单合同

`BACKGROUND_JOBS` 编号 : `haneinfo.background-jobs` 绑定 `BackgroundJobsPort`: 登记器输入处理器, 与经认证的创作者排队,只读取/取消该创作者的工作。 处理器收到 独立的尝试交易、进度回调、取消检查站和中止Signal. 制片人宣布具备下列能力: `requires`;不要即时使用另一个工人模块.

`LIST_VIEW` 编号 : `haneinfo.list-view` 绑定 `ListViewPort.queryFor` 财务报告和审定财务报表 `batchesFor`。查询输入为 在提供者处验证,每一页都应用数据库中的实例授权. 被绑定的批量接口是对未来输出的活扫描; 它不创建文件或承诺 一个冻结的跨页快照。 这些合同不取决于供应商包件或表格.

## 锁定身份采集器搜索

身份StorePort 可选地曝光搜索 AactiveBy Name ({ q, 排除Id, 排除后Id?, 限制 }, 交易 ?) 。 提供商只返回活动身份的ID/名,有大小写不敏感的名字封装,id密钥集命令和最多20页. 消费者必须单独强制执行案例读者人数。 较老的提供者在结构上仍然相容;需要搜索的特性在缺失时必须关闭。 身份-核心执行它,合作消耗它。 可选添加被排队为次要放出;PLUGIN API VERSION保持与当前包版本同步,直到维护者运行放出版本步骤.

## 可选批次身份名称

`IdentityStorePort.findActiveNamesByIds?(ids, transaction?)` 解析授权的页面/批次提交符 ids 到活动 `{ id, name }` 作行相会. 缺失/不活动/删除的ID被省略;老的提供者仍然兼容. `InstanceListItem.submitterName` 无效. `StateMachineInstanceView.submitterName` 是可选的,因为信任的内部快照和较旧的运行时间不提供显示元数据;授权的公共国家机器读取总是供应字符串或无效. 公共消费者将姓名作为文字,MCP将其包装为 `$userContent`。 。 。 .

PLUGIN API VERSION和软件包版本为1.12.0. 受影响的插件显示接受^1.12.0;可选的方法是特征检测,因此老的提供者仍然可以使用.

## 任择期间代表团

代表团ResolverPort 解决 one- hop( 代表Id, 代表Id, 代表团Id) 匹配的原始 受让人的身份证、转让代码和时间,并验证在答复时记录在案的代表团. (原始内容存档于2017-10-21). Delegation resolver map to hanneinfo.delegation-resolver. 可选的内部转让效果 注册加入呼叫者交易, 立即进行回填和取消, 没有能力 依赖周期。 转让触发归属添加了可选的代理用户(Active Userid)和"BeastOfId". 1.13.0合同由PLUGIN API VERSION公司广告,而包件 更改et;版本测试要求当合同由一位未成年人领导时,更改et.

当解析器被安装时, StateMachine 将使用其可选的共享交易咨询锁 或任何实例行锁定/写入。 设立/撤销代表团 独锁同一键. 正常实例交易保持并行;图变异 短短地屏蔽新实例作者,直到其回填/取消。 比赛结束了 在那里,创建和状态输入 否则会错过对方的未承诺行。 咨询锁总是先于实例锁;任务 CAS 和 代表团行共享锁 留在交易中。 不增加额外的表格或工人.

## 实例访问清单(执行草案)

针对第202610-c8e3号决定草案已执行;该决定仍然是草案.

API 1.14.0 添加可选 RbacPolicyPort.find RolesByNames(名称,交易?),返回已存在的 {名称, 显示名: 字符串 {} 无效} 条目 。 较老的供应商在结构上仍然兼容。 无 方法,国家机器拒绝角色授予并返回无效角色标签. 现有角色 PrincipleAuthorization.roleNames 支持角色扩展而无需新建端口. 新方法消费者 (状态-机器和RBAC)需要API 1.14.0;无关的表列发动机地板保持不变.

应用App迁移后,将受影响的机制一起升级。 维持的模式, HTTP 路由,只读列表 instance 访问 MCP 工具,错误和权限合同都有文件记录 在@haneinfo/状态-机器/代理-guide.md中。 它的棱镜a/ intance- access. sql 迁移了现有的读者 在保留时间戳的同时,将表格移至用户/区域办事处、读取/写取和指定/指定/指定行. 选择的维护者(InstanceId,主Type,主Id,源)独有性. 人工补助金为: 默认限制为100;永久 READ 条目在人工删除后幸存. 见软件包寄存器 sQL、测试和应用程序恢复证据的验证/设备 -- -- 贷款/进入/报告.

## 可选流流文件 (API 1. 15. 0)

文件StoragePort / FILE STORAGE / haneninfo.file-surage 提供了 put(键,可读,可选项)返回实际字节,得到(键)返回可读,删除并存在. 附件ScannerPort / ATTACHMENT SCANDER / haneninfo. attachment- scanner 选择从流和元数据返回 CLEAN 或 REJECDED( 理由) 。 执行必须保持内容流,并在失败时发布流. 不提供预先签署/公开的URL合同。 运行时的版本将 package.json 引导到一个次要,直到其待发的小更改器被发布.

## 案件生命周期(202610-f1a8草案)

根据决定草案202610-f1a8执行;决定草案仍为草案。 国家机器升级, 列表视图、协作、附件、进出口、指派和计时器。 没有前端, 包括自动归档或散装使用周期操作。 永久清理的数据不能是 此 API 恢复: 数据库和私有文件备份必须覆盖整个删除保留 持续恢复.

API 1.16.0 在 State MachineInstanceView 中添加可选存档/存档At和可选存档 因此,较老的供应商和消费者仍然兼容。 寿命周期- 认识运行时间 和列表视图提供者总是充斥它们。 只有国家机器和列表视图 才能显示 发动机最少为1.16.0. 事件使用已有的 Madelevent 信封和字符串名称; 无新名称 引入了能力、标志、事件总线或生命周期变异端口.

## 实例标签(合同1.17.0)

纯正态InstanceTag/正态TagText帮助器和输出有效/无效矢量体 由写入和列表过滤器共享。 实例TagsPort / INSTANCE TAGS / haneinfo.intance-tags 可选择供应最大TagLength和一个标签 关于每个授权页面的查询。 实例列表项目. tags 对旧的提供者来说是可选的;新列表视图总是返回一个数组。 见标签/README.md 正常化,Unicode案例扩展和继承授权.

## 数据编制草案(202610-8b3e)

执行草案;决定仍然是草案。 第1.18.0号合同增加了可选准备数据选项 (需要吗?: boolean)去定义KindRegistration.prepareData和定义Registry Port.prepareData. 豁免保留了全部验证。 国家机器InstanceView可选地曝光字段 已删除的战地墓碑; 较老的提供者可以省略。 没有新能力、 MCP 写入工具或运行时间 添加了端口方法。 modelError.toJSON保留了细节. 当前修订版,有界限的冲突和 重试 Afterseconds 没有新的错误信封。 升级登记册转发人和表格消费者 - 其清单需要1.18.0.

## 统一查询(合同1.19.0, 202610-a3d8)

执行草案;决定仍然是草案. `SearchPort` 编号 : `SEARCH` 编号 : `haneinfo.search` 提供搜索、 reindexFor 和状态For, 每一个授权调用者. `SEARCH_PROVIDERS` 没有 能力:它决定选择 `SearchProviderRegistry` (单位:千美元)`limits`, (中文(简体) ), `register`(出口) 由 @ haneinfo/ search; 巢穴没有多提供者的符号, 所以贡献者以 @ optional () 注入它 并注册一个 `SearchProvider` (单位:千美元)`source`, (中文(简体) ), `events`, (中文(简体) ), `documentFor(instanceId, tx)`每个来源. 每个提供者必须用共享的来构建行 `composeSearchBody` 编号 : `truncateSearchText` 匹配 与 `normalizeSearchText` (NFKC, 小写, 空白折叠, 控件为空格, 格式) 删除字符, 应用到每个基本字符 `normalizeSearchTextWithMap` 地图返回到 原文). `SEARCH_NORMALIZATION_TEST_VECTORS` 是共享的委托书。 常数覆盖来源, 重量,默认限额, `SEARCH_ADMIN_PERMISSION` (单位:千美元)`search:search:admin`, (中文(简体) ), `SEARCH_READ_SCOPE` (单位:千美元)`search:read`和新的 `STATE_MACHINE_START_RECORDED` 事件名称.

## 实例分析(合同1.28.0, 第202610-fed6号决定更名)

`CAPABILITY.instanceAnalytics` 财务报告和审定财务报表 `INSTANCE_ANALYTICS` 识别重命名的能力. `CAPABILITY.reports` 财务报告和审定财务报表 `REPORTS` 在下一个主要项目之前保持折旧;没有列出 旧的能力。 1.20.0中引入的报告域合同没有变化.

执行草案;决定仍然是草案. `ReportsPort` 编号 : `INSTANCE_ANALYTICS` 编号 : `haneinfo.instance-analytics` (可选能力,由@haneinfo/Instance-analytics提供) 提供字段For, 查询For, 状态 指定日期和保存报告 CRUD(创建用于、列表用于、获取用于、更新用于、删除用于、, shareFor, runFor; 每一种方法都授权调用者。 类型涵盖汇总查询(与 `count`编号 :`sum`编号 :`avg`编号 :`min`编号 :`max`组合 `$createdAt` 桶 列表视图过滤器存档, 命令By,限制),状态询问,结果,显示提示并保存报告. 常数覆盖 `REPORT_ERROR_CODES` (原始内容存档于2019-09-26) (中文(简体) ), 报告 NOT FOUND),内置维度和 `$leadTime`,测量操作,时间桶,图表类型, 粘度、默认和 MCP 范围后缀 `REPORTS_READ_SCOPE` (单位:千美元)`reports:read`和 `REPORTS_WRITE_SCOPE` (单位:千美元)`reports:write`) (中文(简体) ). `reportBucketStart` 为本地 以星期一为基础的桶; `REPORT_BUCKET_TEST_VECTORS` 是SQL必须同意的共享程序.

## 数据更改日志来源(合同1.21.0,202610-d9a5)

执行草案;决定仍然是草案. `StateMachineRuntimePort.start` 接受一个 选项 `source` (单位:千美元)`CREATE` 默认,或 `IMPORT`标记创建时的写入 实例数据更改日志 。 导入适配器通过 `IMPORT`; 旧运行时间 忽略字段。 没有增加新的能力、标志或范围。 diff格式本身生活在 纯库@haneinfo/diff,不在本合同中.

## 设置和特征旗帜(合同1.22.0,草案202610-e6c1)

执行草案;决定仍然是草案. `SettingsPort` 编号 : `SETTINGS` 编号 : `haneinfo.settings` (可选能力,由@haneinfo/settings提供)提供系统如下: 获取(数值、源代码Override/STATIC/DEFAULT,修订),值、评价Flag和已启用. `SETTING_DECLARATIONS` 不是一个能力:它决定了可选的 `SettingDeclarationRegistry` (单位:千美元)`register(...declarations)`),注入到 @ optional () 如 `SEARCH_PROVIDERS`。 。 。 . `SettingDeclaration` 覆盖代码、类型(设置或旗帜)、描述、类型 (boolean, 整数, 数字, 字符串, enum, 字符串列表), 默认, 约束( min, 最大值, 值, ), 模式、最大项目、最大链接、静态参考和已知项目; `validateSettingDeclaration` 拒绝 不明或敏感属性和隐蔽代码,以及 `validateSettingValue` 应用 限制和硬盖(每串2 000个代码点,200个列表条目)和规范 a 布尔旗值为 `{ enabled }`。 。 。 . `evaluateSettingFlag` 拒绝用户 允许用户 允许 Roles ——% —— 启用; `settingFlagBucket` 是一桶FNV -1a马桶 `<code>:<userId>` 财务报告和审定财务报表 `SETTING_FLAG_BUCKET_TEST_VECTORS` 共有的保险箱。 常数覆盖 `SETTING_ERROR_CODES` (SETTING NOT FOUND,SETTING INVALID,SETTING REVISION CONFLICT,"小说集成","小说集成","小说集成","小说集成","小说集成","小说集成","小说集成"等, (原始内容存档于2013-10-12). Setting PROPOSAL NOT FOUND, setting PROPOSAL NOT PENDING),来源,状态,变化源, 提案状况, `SETTINGS_CHANGED_EVENT`,权限 `settings:setting:read` 财务报告和审定财务报表 `settings:setting:write`后缀 `settings:read` 财务报告和审定财务报表 `settings:propose`。 。 。 .

## 实物参考(合同1.23.0,202610-f7a2草案)

执行草案;决定仍然是草案. `ReferencesPort` 编号 : `REFERENCES` 编号 : `haneinfo.references` (可选能力,由@haneinfo/References提供)提供listFor, 图表For, CreateFor, removeFor 和系统清除AllFor . `OBJECT_TYPE_PROVIDERS` 财务报告和审定财务报表 `LINK_KINDS` 不是能力:他们决心选择 `ObjectTypeProviderRegistry` 财务报告和审定财务报表 `LinkKindRegistry`,注入 @ optional () 如 `SEARCH_PROVIDERS`。一个 `ObjectTypeProvider` 有一个 `type` 分批进行 `readableIds`, (中文(简体) ), `writableIds` 财务报告和审定财务报表 `previewFor` (张卡) `{ type, id, title, subtitle?, state?, stateLabel?, archived?, path }`),加上可选 `recordLinkActivity` 财务报告和审定财务报表 `onPermanentlyRemoved`。 。 。 . `ObjectRef` 实值 `{ type, id }`· ; `parseObjectRef` 编号 : `formatObjectRef` 操作 `<type>:<id>` 窗体( 类型: 小写连字符至 64; id: 1–128 个代码点, 无 空白、 控制或格式字符)和 `OBJECT_REF_TEST_VECTORS` 是共享的委托书. `BUILT_IN_LINK_KINDS` (对称性、衍生出、块、取代)和 `validateLinkKindDeclaration` 封面种类。 常数覆盖 `REFERENCE_ERROR_CODES` (电话:, (原始内容存档于2017-10-25). LINK KIND UNKNONWN, OBJCT NOT FOUND, LINK LIMIT-EXED, LINK NOT FOUND, FORBIDDEN),, `STATE_MACHINE_INSTANCE_OBJECT_TYPE`,事件 `references.linked` 编号 : `references.unlinked`,则 权限 `references:link:admin`,MCP范围后缀 `references:read` 财务报告和审定财务报表 `references:write`,和默认限制.

## 空间和继承的访问(合同1.24.0,202610-b1d6草案)

执行草案;决定仍然是草案. `SpacesPort` 编号 : `SPACES` 编号 : `haneinfo.spaces` (可选能力,由@haneinfo/spaces提供)提供列表空间 给诺德福 孩子们, 创建 SpaceFor, 创建 FolderFor, 更新 NodeFor, 删除 NodeFor, accessFor, put Access 因为, 删除 AccessFor, placeFor, unplaceFor和例F, 每个授权调用者 。 类型覆盖 节点( e)`SPACE` 编号 : `FOLDER`, (中文(简体) ), `SpaceNodeView` 与打电话者 `access` 财务报告和审定财务报表 `canManage`面包屑, 访问条目( e)`USER` 编号 : `ROLE`, (中文(简体) ), `READ` 编号 : `WRITE` 编号 : `MANAGE`),与 `viaNodeId`, (中文(简体) ), 安置人数(`{ object: ObjectRef, nodeId, placedBy, placedAt }`)和实例列表页。 纯洁 帮助者 `effectiveSpaceAccess` (所有条目加上父母的有效访问,同时 `inheritAccess` 真实的,每本金的最高水平,关系上最近的节点, `spaceAccessLevelFor`, (中文(简体) ), `spaceAccessAtLeast`, (中文(简体) ), `inheritedInstanceLevel` 编号 : `inheritedInstanceAccess` (MANAGE成为实例) (中文(简体) ) `normalizeSpaceName` 与共享 `SPACE_ACCESS_TEST_VECTORS` 财务报告和审定财务报表 `SPACE_NAME_TEST_VECTORS`。 。 。 . `INSTANCE_ACCESS_SOURCES` 添加 `INHERITED` (单位:千美元)`INHERITED_ACCESS_SOURCE`改为: 发射, 授权和授予。 常数覆盖 `SPACE_ERROR_CODES` (SPACE NODE NOT FOUND, 空间 评估、空间 NAME TAKEN、空间 NOT EMPTY、空间 TOO LARGE、空间 DEPTH EXEDEN、, 事件 `spaces.placed` 财务报告和审定财务报表 `spaces.access-changed`,权限 `spaces:space:create` 财务报告和审定财务报表 `spaces:space:admin`后缀 `spaces:read` 和默认限制(深度8,500) 儿童,5 000起受影响事件,200个代码点的名称,50至200页.

## 生成的MCP读取工具(合同1.25.0,第202610-c5e8号草案)

执行草案;决定仍然是草案. `McpGeneratedToolsPort` 编号 : `MCP_GENERATED_TOOLS` 编号 : `haneinfo.mcp-generated-tools` (可选能力,由@haneinfo/mcp生成工具提供) 提议 `diagnosticsFor(userId)` (许可) `mcp-generated-tools:tools:read`返回时 `McpGeneratedToolsDiagnostics` 与 `McpGeneratedToolDescriptor` 财务报告和审定财务报表 `McpGeneratedToolSkip` 条目. 常数覆盖 `MCP_GENERATED_TOOL_KINDS` (列表,获取,搜索,报告), `MCP_GENERATED_TOOL_ERROR_CODES` (UNKNOWN FIELD,INVALID INPUT,FORBIDDEN,INSTANCE NOT-FOUND), 互联网档案馆的存檔,存档日期2014-12-21.,, `MCP_GENERATED_SKIP_REASONS` (中文(简体) ), 怀念 脱口而出,机制-可受理), `MCP_GENERATED_WARNING_CODES` (中文(简体) ) 默认(60个刷新、20个机器、32个KB计划、32个特征名称碎片)、标签限制和 `MCP_TOOL_NAME_MAX_LENGTH` (64) 纯粹的帮助者: `mcpGeneratedToolNameFragment` 编号 : `isMcpGeneratedToolNameFragment` 编号 : `mcpGeneratedToolName` (与 `MCP_GENERATED_NAME_TEST_VECTORS`, (中文(简体) ), `mcpGeneratedScalarSchema` 编号 : `mcpGeneratedFilterSchema` 编号 : `mcpGeneratedComparisonOperators` (单位:千美元) 每种字段类型的 JSON Schema 由 `MCP_GENERATED_FILTER_SCHEMA_TEST_VECTORS`, (中文(简体) ), `mcpGeneratedUserText` 财务报告和审定财务报表 `mcpGeneratedFieldDescription` (标签为已清理、 限定和引用的用户) 内容). `McpToolSourcePort` 选项 `McpToolsPort.registerToolSource` 编号 : `refreshToolSources` 描述运行时间变化工具源(mcp-server 3.4); `StateMachineRuntimePort.getFor` 可选的用户授权实例已读取.

## 本地化标签和状态吨位(合同1.26.0,草案202610-a8d3)

执行草案;决定仍然是草案. `LocalizedText` 是普通字符串或地图 支持非空字符串的语言,例如 . `{ "zh-TW": "借用人", "en": "Borrower" }`。 。 。 . `SUPPORTED_LOCALES` 实值 `['zh-TW', 'en']` 财务报告和审定财务报表 `DEFAULT_LOCALE` 实值 `zh-TW`。 。 。 . `localizeText(text, locale?)` 返回一个字符串:请求的地块,然后是zh-TW,然后是en,然后是第一个可用的 值; 字符串按原样返回,空地图给出 `''`。 。 。 . `localizedTextValues` 列表中 独立翻译(用于索引). `localizedTextJsonSchema({ minLength?, maxLength })` 这是 schema 片段定义类型嵌入( 字符串保持其先前的界限; 地图至少需要一个) 以 1–maxLength 代码点支持的地块 ; `localizedTextIssues` 编号 : `isLocalizedText` 检查 相同的规则加上只显示空白的地图值。 5. 请: `parseLocale` (大小写不敏感白名单), `localeFromAcceptLanguage` (质量顺序; `en*` 给予en, `zh*` 给予zh-TW; 限值)和 `resolveRequestLocale({ query, acceptLanguage })` (明确 `?locale=` 必须是zh -TW或en, 否则 INVALID LOCALE/400;然后是接受语;然后是zh-TW. 共享向量 : `LOCALIZE_TEXT_TEST_VECTORS`, (中文(简体) ), `LOCALIZED_TEXT_ISSUE_TEST_VECTORS`, (中文(简体) ), `LOCALE_RESOLUTION_TEST_VECTORS`。 。 。 .

`StateTone` 这是其中之一 `STATE_TONES` (单位:千美元)`neutral`, (中文(简体) ), `info`, (中文(简体) ), `success`, (中文(简体) ), `warning`, (中文(简体) ), `danger`(三); `DEFAULT_STATE_TONES` 将INITIAL和最后图示中性、NORMAL和CHOICE用于信息,以及 `stateToneOf(state)` 返回一个有效的已声明的音调或类型默认值(对其它任何事物都中立, `STATE_TONE_TEST_VECTORS`) (中文(简体) ). `InstanceListItem` 财务报告和审定财务报表 `StateMachineInstanceView` 获取可选 `stateLabel` 财务报告和审定财务报表 `stateTone` (播放公众读取的元数据); `StateMachineRuntimePort.getFor` 接受可选选项 `{ locale }`。 。 。 .

## IAM简介和签定时间合同(合同1.29.0)

`IAM_PROFILE` (单位:千美元)`CAPABILITY_IAM_PROFILE` 编号 : `haneinfo.iam-profile`和 `IAM_TOKEN_EXCHANGE` (单位:千美元)`CAPABILITY_IAM_TOKEN_EXCHANGE` 编号 : `haneinfo.iam-token-exchange`)定义后端 IAM配置 和出入境证券交换端口(`IamProfilePort`, (中文(简体) ), `IamTokenExchangePort`, (中文(简体) ), `TokenExchangeProvider`, (中文(简体) ), `IamDeploymentConfig`, (中文(简体) ), `IamCapabilityAssessment`,并按 `IamTokenUse`) (中文(简体) ). `validateTokenTimestamps` 财务报告和审定财务报表 `TOKEN_TIME_TEST_VECTORS` 共享 `iat`编号 :`exp` 跨时间戳规则 `@haneinfo/oidc-auth` 财务报告和审定财务报表 `@haneinfo/mcp-server`。见 `specs/topics/iam-contract.md` 完整规格.

## 常见问题

### @haneinfo/plugin-api 是什么？

Haneinfo 插件合同: 显示 v1 类型和 JSON Schema, 稳定能力符, 定义 Plugin \(\), 生命周期/诊断合同, 显示加载器和依赖解析器\.

### 如何安装 @haneinfo/plugin-api？

在项目目录运行 npm install @haneinfo/plugin-api，或使用 pnpm add / yarn add / bun add。

### @haneinfo/plugin-api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @haneinfo/plugin-api 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @haneinfo/plugin-api 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @haneinfo/plugin-api 可以商用吗？

@haneinfo/plugin-api 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @haneinfo/plugin-api 的下载量有多少？

根据 npm 官方下载统计，@haneinfo/plugin-api 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,899 次，日均约 330 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @haneinfo/plugin-api 还在维护吗？

最新版本 1\.29\.1 发布于 2026/11/17（今天）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/10/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

