自定义编辑器
有些工作不在任何面板中，因为它只属于您：按供应商公式重新计算价格、将目录与他方核算系统核对、一次性填写批次特征的界面。“自定义编辑器” 板块让您自己编写这样的小型编辑器（或委托他人编写），并在管理后台内部运行——在沙盒中，仅访问您所授权的数据。
打开方式：管理面板 → 自定义编辑器（admin.cenaly.com/custom-editors）。该板块通过应用商店中的**“自定义编辑器 (SDK)”卡片启用——默认处于隐藏状态。页面上的“📌 添加到侧边栏”**按钮可在频繁使用时将其放入侧边菜单。
这是什么板块#
插件是一个编译好的脚本（index.js）及其描述文件（manifest.json）。面板将脚本加载到隔离框架中：它无法访问您的会话、管理后台代码或网络。它只能通过网桥与数据交互——一组允许的请求，每个请求都会根据所授予的权限进行校验。
页面由以下区块组成：
| 区块 | 内容 |
|---|---|
| 已安装编辑器 | 插件卡片：名称、“版本”、“权限”、“放置位置”、“允许的网络主机”、“已更新”、来源（仓库和标签链接）。操作：“打开”、“启用”/“停用”、检查更新、“删除” |
| 安装编辑器 | 从磁盘文件安装 |
| 从 GitHub 安装 | 通过公开仓库地址和标签安装 |
| 🤖 使用 AI 开发（氛围编程） | 项目模板、AI 代理提示词和作为测试数据的目录快照 |
| 👩💻 开发者访问权限 | 向承包商授予开发者模式的临时权限 |
| 🛠️ 开发者模式 | 直接从您的计算机运行插件，无需安装 |
打开的编辑器占据整个屏幕，页面地址会带有 ?app=<标识符> 标记——可将此链接分享给有访问权限的人。
启动所需条件#
| 条件 | 用途 |
|---|---|
| 应用商店中的**“自定义编辑器 (SDK)”**卡片 | 该板块较为小众，默认关闭 |
| 您是账户所有者 | 只有所有者才能安装、启用、删除插件及授予权限；员工只能查看只读列表 |
编译好的插件：index.js + manifest.json |
可以是您自己的、来自开发者的，或公开 GitHub 仓库中的发布版本 |
| 用于开发——为开发者准备的员工账户 | 开发者模式通过其工作登录邮箱授予 |
第 1 步：决定由谁编写编辑器#
有三种途径，区别在于谁持有代码：
| 途径 | 适合谁 | 如何操作 |
|---|---|---|
| 按我们的模板使用 AI 代理 | 愿意用语言描述任务的所有者 | “使用 AI 开发”区块：模板 + 提示词 → 代理构建发布版本 → 您进行安装 |
| 自己或聘请的开发者 | 有承包商或团队中有开发者 | 授予其开发者模式权限，他在真实账户上编写和调试，您安装完成的发布版本 |
| 来自 GitHub 的现成发布版本 | 插件已编写完成（由您或为您编写） | “从 GitHub 安装”：仓库地址和标签 |
在所有三种情况下，安装权始终归所有者：即使拥有权限的开发者也只能在自己的开发者模式中运行其代码，而不能将其安装到账户中。
第 2 步：使用 AI 开发（氛围编程）#
**“🤖 使用 AI 开发（氛围编程）”**区块提供四项内容，以便将任务交给 AI 代理（Claude Code、Cursor 等）而无需从头解释契约：
- “⬇️ 下载项目模板 (zip)”——现成的插件框架：清单、入口点、契约描述（
GUIDE.en.md）和代理指令。压缩包直接在浏览器中生成，无需下载任何外部内容。 - “📋 复制代理提示词”——英文任务文本：从模板开始，参照指南，如何验证结果。
- 代理工具集配置——借助它，代理可构建插件、启动沙盒的本地副本测试台、截取屏幕截图和状态快照，最后构建发布版本：用于手动安装的 zip 或 GitHub 发布版本。
- “⬇️ 下载目录快照（测试夹具）”——您的分类和项目以文件形式提供，以便代理在真实数据而非虚构数据上进行测试。
⚠️ 快照中会完全剔除其他插件的自定义字段：其他扩展存储在您卡片上的数据不会随夹具离开账户。
第 3 步：安装编辑器#
从文件安装。 “安装编辑器”区块：选择“捆绑包 (index.js)”和“清单 (manifest.json)” → “检查并安装”。面板首先检查清单——标识符、本地化名称、版本、最低 SDK 版本、放置位置、权限和网络主机列表——然后显示同意书：“此编辑器请求：”以及用通俗语言列出的权限。在您点击“安装”之前，不会安装任何内容。
从 GitHub 安装。 “从 GitHub 安装”区块：“仓库（URL 或 owner/repo）”字段、“标签（留空 = 最新发布版本）”字段和“检查仓库”按钮。约定很简单：manifest.json 位于仓库根目录，编译好的 dist/index.js 在标签中，标签格式为 v{版本}。清单和捆绑包直接从您的浏览器拉取。在两种情况下，安装时都会计算并记住捆绑包指纹 (sha256)：如果文件之后被替换，启动将被阻止，面板会要求重新安装编辑器。
权限与放置位置#
权限（也叫作用域）由插件在清单中申请，安装时由你确认。完整列表如下，网桥不具备除此之外的任何能力：
| 权限 | 可访问内容 |
|---|---|
| 读取目录 | 分类、项目、特征以及卡片的自定义字段 |
| 创建和修改目录项目 | 创建和编辑项目、批量导入、自定义字段和特征定义 |
| 按门店修改价格、可售状态和停售清单 | 与门店菜单中的面板功能相同 |
| 读取商品库存目录 | 只读访问库存的品名表 |
| 在你的存储中保存自身设置 | 插件在你账户中的自有键（每个键最多 1 MB） |
| 扩展的服务端部分 | 在我们服务器上调用插件代码——这是它访问互联网的唯一方式 |
列表中完全没有的内容，插件无论如何配置都拿不到：访客与客户、订单、收据、财务、员工、聊天和通话，网桥一律不提供。
放置位置（插槽）有三种：
| 插槽 | 出现位置 |
|---|---|
| 独立页面 | “自定义编辑器”分区内的条目，全屏打开 |
| 目录页面上的按钮 | 目录项目旁边的工具 |
| “库存”分区的标签页 | 插件以库存标签页形式呈现——我们的内置扩展“VetIS”就是这样打包的 |
开发者模式与承包商访问权限#
开发者模式（“🛠️ 开发者模式”区块）会从你的电脑实时挂载插件：“包 URL”字段只接受 localhost / 127.0.0.1 地址，旁边是“清单 JSON”，以及“启动 dev 会话”按钮。此时指纹不会被固定，会话持续到标签页关闭为止；“停止 dev 会话”会立即将其关闭。
开发者授权（“👩💻 开发者访问”区块）在编写者不是所有者时需要。为开发者创建一个普通的员工账户，然后由所有者发放授权：“开发者邮箱（其 staff 登录名）”、“允许的权限”、“有效期（天）”以及可选备注 → “授予访问权限”。随时可通过“撤销”按钮收回。
授权能做什么、不能做什么：
- 能——仅限开发者模式，且限于你勾选的权限（默认有效期 14 天，最长 90 天）；
- 权限按交集裁剪：清单申请的与授权发放的取交集；即使清单中申请了多余权限，插件也拿不到；
- 不能——安装、启用和删除插件：这些仍归所有者。
更新、启用与删除#
| 操作 | 方式 |
|---|---|
| 打开 | 卡片上的“打开”按钮（或带 ?app=… 的链接） |
| 临时停用 | “停用”——插件仍保持安装，但不执行，也不在其位置显示 |
| 更新 | 来自 GitHub 的插件——先“检查更新”，再“更新到 …”；如果版本已是最新，面板会提示“已安装最新版本”。来自文件的插件通过重新安装来更新 |
| 删除 | “删除”并确认：设置和条目会被移除，已上传的发行版保留在存储中 |
没有自动更新是刻意的：他人代码的新版本意味着新指纹，可能还有新权限，因此更新始终是所有者的自觉操作。
内置扩展#
我们自己的部分模块也打包为相同格式——从行为上可以看出，但无需安装它们：它们随面板一同提供，在应用商店中通过卡片启用，而不是在本分区。
目前这样的模块只有一个——面向俄罗斯的 “Mercury/VetIS”：它以“库存”分区的标签页形式存在，在同一沙箱中执行，并接受相同的指纹校验。内置扩展不会出现在已安装编辑器列表中。
编辑器能做什么、不能做什么#
| 能 | 不能 |
|---|---|
| 在已授予权限范围内读取和修改目录 | 获取你的密码或利用你的会话 |
| 显示自己的界面、通知和确认请求 | 打开自身周围管理后台的代码或数据 |
| 打开面板原生的项目编辑器 | 从插件窗口直接访问互联网 |
| 在你的账户中保存自身设置 | 在你的卡片上看到其他插件的数据 |
| 通过服务端部分访问互联网——且仅限于清单中列出的 https 地址（不超过八个） | 在文件被替换后执行：指纹不匹配会阻止启动 |
第三方插件会在卡片上标注警告：“沙箱中的第三方应用——它绝不会索要密码。” 如果插件索要面板登录信息、支付数据或短信验证码，那是诈骗，而不是扩展在正常工作。
限制#
- 该板块默认关闭，面向编写代码（或委托编写代码）的人：普通所有者在这里无事可做。
- 除查看外，所有操作仅限账户所有者。 员工只能只读访问该中心；开发者模式仅在有效授权下可用。
- 不支持私有 GitHub 仓库——仓库必须公开，安装按标签进行。
- 没有自动更新：插件更新始终由所有者发起。
- 没有第三方插件商店。 现成扩展不会通过面板发布或出售——来源只能是你的文件或你的仓库。
- 只有三个插槽（自有页面、目录按钮、仓库标签页）——插件无法嵌入面板的任意界面。
- 网桥不提供客人、订单、财务、员工和对话数据——无法通过权限绕过，这类请求根本不存在。
- 没有单独的“插件做了某事”日志。 权限显示在卡片上，目录修改会进入常规项目历史；如需管控，请从仅授予只读权限的插件开始。
- 技术上限： 包最大 4 MB，清单中最多 8 个网络地址，单个存储键最大 1 MB；服务端运行最长 30 秒，单次最多 50 次外部请求。
- 插件数据保留在你品牌的云端：
cenaly.ru上的账户，其服务端状态存放在俄罗斯境内。
故障排除#
| 症状 | 请检查 |
|---|---|
| 菜单中没有该板块 | 应用商店中是否启用了“自定义编辑器 (SDK)”卡片；是否通过“📌 添加到侧边栏”按钮将板块移出 |
| 员工看不到安装按钮 | 这是设计如此：安装、删除和授权仅限账户所有者 |
| “存储中的包与已安装的指纹不匹配。启动已阻止” | 插件文件在安装后被替换——请重新安装编辑器以写入新指纹 |
| “编辑器未按时启动（10 秒内没有 connect()）” | 插件未建立连接：其代码有误或打包的文件不对 |
| “无法加载编辑器包” | 发布版本不可用或文件已损坏——请重新安装 |
通过链接 ?app=… 跳转时提示“编辑器未找到或已关闭” |
插件已在卡片上删除或关闭 |
| “无法从 GitHub 获取编辑器” | 仓库为私有、根目录缺少 manifest.json、标签中缺少 dist/index.js，或标签未按 v{版本} 约定命名 |
| “仅允许 localhost / 127.0.0.1 地址” | 开发者模式有意不接受外部地址——请在本地启动构建 |
| 插件看不到所需数据 | 核对卡片上的“权限”；开发者的授权权限还会与授权范围取交集进一步削减 |
| 插件无法访问外部服务 | 沙箱没有直接网络：访问由服务端发起，且地址必须在清单中 |
| “编辑器报告有未保存的更改。仍要关闭吗？” | 插件自身报告了草稿——关闭前请先在插件内保存工作 |
常见问题#
需要会编程吗？#
安装现成的发布版本——不需要。获得发布版本本身——需要：由开发者或 AI 代理按照“使用 AI 开发”板块中的模板编写。该板块是代码工具，而不是“鼠标”构建器。
别人的插件能看到我的客户或营收吗？#
不能。插件在沙箱中运行，只能通过网桥获取数据，而网桥恰好只能做六件事：目录、价格和停售清单、仓库参考、自有存储、调用自有服务端以及界面元素。客人、订单、收据、财务、员工和对话数据根本不在其中。特定插件被允许什么，始终显示在其卡片的“权限”一行中。
如何将开发交给承包商，又不让他进入整个账户？#
为他创建一个员工账户，然后在“开发者访问”板块中授予权限：只勾选所需的权限并设置期限（默认 14 天，最长 90 天）。他将获得开发者模式，仅此而已；插件安装仍由你负责。授权可通过一个按钮撤销。
作者发布新版本时，插件会自动更新吗？#
不会。更新由所有者发起：“检查更新” → “更新到 …”。这样新版本不会在无人知晓的情况下出现在账户中——因为随版本一起，请求的权限也可能发生变化。
插件将自己的设置和数据存储在哪里？#
在你的账户中，位于其标识符下的独立存储中（每个键最大 1 MB），此外，如果插件使用它们，还会存储在你卡片的自定义字段中——每个插件只能看到自己的空间。cenaly.ru 上的账户，其服务端及其状态保留在俄罗斯境内。
这与 API 和 MCP 有何不同？#
开发者 API 和 自有 PBX 的 MCP 用于程序在外部工作时：自有网站、第三方账户系统、AI 代理。自定义编辑器则相反，是面板内部的界面：员工像打开普通管理页面一样打开它，无需离开工作窗口。
相关板块#
- 应用商店 — 板块和内置扩展的启用位置
- 仓库 — 存放“VetIS”等扩展的标签页，以及商品参考
- 目录导入 — 如果任务仅在于此，这是加载项目的标准途径
- 自有代码的店面 (headless) — 面向外部网站的开放数据契约
- 自有 PBX 的 API 和 MCP 和 面向 AI 代理的 Guest API — 在面板外部而非内部工作
- 员工和班次 — 开发者账户和角色
- 安全与数据 — 数据存储位置及谁有权访问
- 支持 — 如果插件行为可疑，可在此联系