扩展¶

扩展商店（管理 → 扩展）用于安装由供应商签名的扩展，在不更改 Turbo EA 核心的前提下（「clean core」原则）添加客户专属能力——额外的元模型内容、集成、后台任务，甚至新页面。

扩展有两种安装方式：从内置商店一键安装（实例需能访问互联网），或直接上传文件——扩展是签名的 .teax 包，许可证是签名的文本文件，通常都通过电子邮件发送。基于文件的方式无需商店账户或对外连接，因此在隔离（air-gapped）环境中同样适用。

该页面有两个标签页：商店用于浏览供应商的扩展目录并一键安装；已安装 用于管理许可证并通过文件安装。

扩展由 Turbo EA 构建并签名——不支持自行构建，也不向第三方开放。如果您需要为贵组织量身定制的功能，我们可以为您构建并授权。请参阅 Turbo EA 咨询服务。

信任机制¶

两项相互独立的检查保护您的实例：

来源（签名）。 每个包都带有供应商密钥的 Ed25519 签名。Turbo EA 在上传时验证签名，并在每次后端启动时再次验证。未签名、被篡改或第三方的包都会被拒绝——已安装的扩展保证与供应商构建的完全一致。
激活（许可证）。 签名的许可证文件列出您的授权——每个扩展一项，各有自己的到期日。已安装的扩展只有在存在可用授权时才会运行。许可证绑定到您的实例 ID——为其他实例签发的许可证会被拒绝。

免费扩展¶

部分扩展是免费的，完全无需许可证。它们会立即安装并运行——没有购买步骤，也没有需要粘贴的许可证文件。免费扩展在「商店」和「已安装」选项卡中以免费徽章标记，并且对它们隐藏了购买和续订操作。签名校验仍与付费扩展完全一样地生效（免费扩展同样由供应商签名），因此无论哪种情况来源都有保证。由于无需授权，免费扩展永远不会过期，也不会进入宽限期。

您的实例 ID¶

每个安装都会一次性生成唯一的实例 ID（TEA-XXXX-XXXX-XXXX），显示在管理 → 扩展页面顶部，并带有复制按钮。它是您的许可身份：购买时请提供它（应用内商店会自动发送；在线商店结账时会要求填写），这样为该实例购买的每个扩展——无论由哪位管理员、使用哪个邮箱购买——都会汇入同一份组合许可证。它仅用于标识您的实例；绝不是凭证，因此可以放心提供给供应商。

该 ID 会随工作区转移一起迁移，因此迁移到新主机后许可证仍然有效。完全重装后实例会获得新 ID——请供应商为新 ID 重新签发许可证（供应商侧的快速「re-key」操作）。

商店标签页¶

商店标签页开箱即用，会列出供应商发布的扩展及其描述和价格：

购买会在浏览器的新标签页中打开支付页面。付款确认后，许可证会自动应用（副本也会通过电子邮件发送）。
安装（当有更新版本发布时显示更新）会先检查您的许可证——如果扩展尚未获得授权，会弹出对话框供您购买或粘贴许可证，然后自动继续——并让软件包经过与手动上传完全相同的签名验证和模拟预览。带演示的扩展会显示观看演示链接，发布更新版本后按钮会变为更新。

当目录包含分类标签时，每个条目会显示小药丸标签（free 或 commercial，以及 integration 等主题），列表上方会出现筛选栏——点击标签可缩小范围（多个标签组合生效），点击 All 重置视图。

商店标签页是只读且匿名的：无需账户、无需令牌，也不会发送任何关于实例的信息——只读取供应商的公开目录。隔离实例无需任何配置——标签页只会显示友好的提示，并使用下面基于文件的流程；供应商的商店网站可在任何联网浏览器上提供相同的购买和下载。如果您的实例与商店之间有环节阻止了该请求——代理、防火墙或商店前端的机器人防护——该标签页会予以说明并列出收到的 HTTP 状态码，因此被阻止的实例绝不会被误认为隔离实例。

实例还会每天检查一次目录并告知变化，这样新扩展 — 或您正在使用的扩展的安全修复 — 就不必等到有人碰巧打开此页面。当商店发布新扩展时，管理员（角色具备 admin.manage_extensions 的任何人）会在通知铃中收到提醒；当已安装的扩展有更新版本时也会收到提醒。每项变化只公告一次，发布密集的日子会按类型汇总成一条通知，而不是每个扩展一条。系统不会下载或安装任何内容 — 通知只是把您带到这里。可在管理 → 设置 → 更新通知中完全关闭每日检查。

试用¶

部分付费扩展提供30 天免费试用 — 请在商店标签页中查找开始 30 天试用按钮（或商店网站上的试用选项）。开始试用的流程与购买相同，只是无需付款：不需要信用卡，许可证会自动更新（对于隔离网络安装，副本也会通过电子邮件送达），扩展在 30 天内以完整功能运行。

每个 Turbo EA 实例对同一扩展只能试用一次。
试用在结束日期当天准时结束 — 没有宽限期。此后扩展将停止运行，直到您订阅为止；您的数据绝不会被删除，应用订阅许可证后一切立即恢复。
「已安装」标签页会将试用权益显示为试用至 …。
试用会自动结束 — 无需取消，也绝不会产生任何费用。

安装扩展¶

如果尚未操作，请先应用许可证（见下文）。
打开管理 → 扩展，在商店标签页中选择从文件安装…，上传收到的 .teax 文件。
Turbo EA 验证签名并显示预览：对于包含内容的扩展，这是对其将创建或更新的每个卡片类型、标签组、卡片和关系的试运行——此时尚未写入任何内容。
检查预览后点击安装扩展。
如果扩展包含后端代码，会出现横幅提示重启后端容器（docker compose restart backend）。内容和界面扩展立即生效——用户在下次刷新页面时即可看到新界面。

重复上传同一个包是安全的——预览会将所有内容显示为「已跳过」，应用后不会有任何变化。

更新扩展¶

当商店发布了已安装扩展的更新版本时,「已安装」标签页会在版本号旁显示 更新到 X 标签(商店标签页的按钮也会变为更新)。点击一次即可执行与全新安装完全相同的签名验证、预览和应用流程。有两项保护措施:

更新一个您有意停用的扩展会保持其停用状态——新版本已写入磁盘,但其内容仍然隐藏,在您重新启用之前不会运行任何东西。
安装比已安装版本更旧的软件包会先要求明确确认:降级后的版本可能无法理解较新版本写入的数据。无论哪种情况都不会删除任何数据。

许可证与续期¶

通过「已安装」标签页中的输入许可证…应用许可证（粘贴文本或上传文件）——需要许可证的每个扩展行上也会显示该按钮。页面随后会显示被许可方以及每项授权的徽章及其到期日期。

您的实例一次仅保留一个许可证——应用新许可证会替换旧的。Store 签发的许可证始终包含为您的实例购买的全部内容，因此替换是安全的。如果您还持有手动签发的许可证，请向供应商索取一份合并许可证，而不是按扩展分别应用文件；如果要应用的许可证会移除当前许可证仍涵盖的授权，Turbo EA 会列出它们并先请求确认（无论如何都不会删除数据）。

授权过期后会进入宽限期（默认 30 天）：一切照常工作，管理员会看到警告横幅。宽限期结束后，扩展将被软停用——其页面消失、API 拒绝请求、后台任务暂停。任何数据都不会被删除。 应用续期后的许可证文件即可立即恢复一切，无需重启。

通过商店购买的许可证在联网实例上会自动续期：每次付款成功后，实例会自动获取延长后的许可证——无需任何粘贴操作。在隔离环境中，续期流程是：粘贴续订邮件中的最新许可证文件（或向供应商索取）——仅此而已。

自动续订状态与取消订阅¶

每个授权标签都会说明到期日会发生什么：有效订阅显示将于 {日期} 续订，取消后显示于 {日期} 到期 — 不会续订。该信息来自签名许可证本身，因此在隔离实例上同样准确 — 订阅发生任何变化后通过电子邮件发送的许可证文件都带有最新状态；粘贴后标签即为最新。

要查看续订日期、取消或恢复自动续订、更改付款方式或下载发票，请使用被许可方名称旁的管理订阅按钮（商店购买的许可证会显示）。它会在新标签页中打开您的账单门户 — 无需账户。在隔离实例上该按钮无法连接商店；请改用每封许可证邮件中的「管理订阅」链接（只需您的浏览器能上网，Turbo EA 实例无需联网）。

取消订阅不会立即停用任何功能：扩展会继续工作到已付费周期结束，之后进入正常的宽限期 + 软停用流程。您的数据永远不会被删除，重新订阅即可恢复一切。

启用、禁用与卸载¶

已启用开关会立即软停用扩展（无需重启），且可随时切换回来。对于内容包，这会将其卡片类型从元模型中隐藏——卡片保持原位。
卸载会删除扩展的文件并将其卡片类型从元模型中隐藏。卡片和扩展自己的表会被特意保留，重新安装后一切（包括类型）都会恢复。

权限¶

整个页面及其所有 API 路由都由专用权限 admin.manage_extensions 保护（授予内置管理员角色）。扩展可以定义自己的权限键（ext.<名称>.…），扩展加载后会出现在管理 → 用户与角色中。

高级字段功能¶

某些扩展可解锁核心本身不提供的高级数据描述方式：

字段帮助文本 —— 在录入数据时显示在字段下方的可折叠提示，让表单能够自我说明。
自定义字段类型 —— 内置类型之外的新字段种类（例如可配置的 1–5 或 0–10 评分）。

这些选项仅在提供它们的扩展已安装并获得许可时才会出现在元模型字段编辑器中。如果此类扩展随后被禁用或其许可证到期，您已录入的值仍会以只读纯文本形式继续显示 —— 不会被清空或删除 —— 而编辑选项会一直消失，直到该扩展重新生效。

数据访问授权¶

大多数扩展只处理自己的数据。与核心数据集成的扩展 — 例如把待办事项与 Jira 或 MS Planner 等外部任务跟踪工具同步的连接器（#921）— 必须在其签名清单中声明 grants：

core.todos.read / core.todos.write — 通过扩展 SDK 读取或修改待办事项。写权限包含读权限。对于系统待办（例如签署请求），同步扩展只能设置以标签形式显示的外部引用——永远无法完成、编辑、重新分配或删除它们；属于其他扩展的待办同样不可触碰。
core.events.todo — 接收待办变更事件，让连接器立即响应，而不是等到下一个轮询周期。
core.users.read — 查询用户（仅姓名、邮箱和激活状态），以便连接器将负责人与外部工具中的账户匹配。不会暴露任何角色、登录或偏好数据，扩展也永远无法修改用户。
core.cards.read — 读取卡片、关系和元模型，例如让连接器将您的应用与外部系统中的记录进行匹配。已归档的卡片保持不可见。
core.cards.write — 创建、更新或归档卡片并添加关系，验证规则与应用自带编辑器完全一致。更新会合并字段值而不是整体替换，因此扩展永远无法抹除它不管理的数据；并且没有永久删除——带恢复窗口的归档是扩展唯一可执行的移除操作。
core.events.card — 接收卡片和关系的变更事件，让连接器即时响应清单变化，而不是等到下一个轮询周期。

授权是供应商签名包的一部分，在打包时即已固定，安装前即可查看。它们仅在扩展已安装、已启用且有有效许可时生效 — 禁用扩展或许可过期会立即撤销访问，无需重启。扩展做出的每一次变更都会以扩展来源记录在 管理 → 审计日志 中，从外部工具镜像来的待办会显示一个链接到外部条目的标签。

扩展做出的每一次更改都会以 ext:<key> 批次的形式出现在「管理 → 审计日志」中，包含逐字段差异，并可像任何其他批次一样在那里回滚。运维人员拥有最终决定权：设置环境变量 EXTENSION_WRITES_ENABLED=false 可立即暂停所有扩展写入（读取不受影响，无需重启），EXTENSION_MAX_WRITES_PER_BATCH / EXTENSION_MAX_BATCHES_PER_MINUTE 则限制单个扩展每批次和每分钟可更改的数量。

扩展页面出现的位置¶

扩展页面在扩展安装并获得许可后会出现在导航中 —— 通常作为其自己的顶级菜单项，但某些报表会与内置报表一起放在报表菜单下。