工业 IDE Node.js 插件开放能力建设：从公共 API 到一键安装

本轮工作围绕一个目标展开：把工业 IDE 内部已有的二次开发能力整理成稳定、易用、可交付的外部插件体系。为避免暴露具体产品与内部实现，文中的产品名、真实接口名、目录、版本和错误信息均已抽象化。

一、为什么需要稳定的公共门面

内部能力通常分散在多个命名空间中，直接对外开放会带来三个问题：

1. 内部结构暴露给插件开发者；
2. 命名方式不统一，学习成本较高；
3. 内部重构容易破坏插件兼容性。

因此可以增加独立的公共门面，并采用统一的“平台、领域、动作”分层。下面仅为概念示例，不代表任何真实产品接口：

const status = await platform.status.query();
const asset = await platform.asset.getCurrent();
const robots = await platform.robot.list();

原有内部接口保持不变，公共门面只负责选择性暴露、类型约束和兼容隔离。声明文件应作为公开契约，并为参数、返回值、生命周期和失败情况补充说明。

二、动态顶部入口

除了数据查询，插件还需要稳定的用户入口。可以提供动态注册顶部菜单的公共能力，允许插件配置标识、标题、命令、图标、顺序、显示条件和启用条件。

实现时需要注意：

• 工作区相关上下文应随状态变化更新；
• 需要启动后立即显示的入口应在合适的激活阶段注册；
• 注册结果应以可释放对象返回，并交由插件生命周期统一管理；
• 图标应使用主题友好的资源，避免依赖固定背景色；
• 菜单命令仍需经过平台权限和上下文校验。

三、让模板成为真正可用的用户工程

仅有 API 不足以形成开发体验。插件模板应自动完成以下工作：

• 根据解决方案名称更新包信息；
• 同步更新命令前缀，避免不同项目冲突；
• 保留可重复使用的模板占位符；
• 提供覆盖命令、公共 API、菜单与事件的最小示例；
• 携带与运行时一致的公开类型声明；
• 在 README 中说明环境、构建、安装与调试方式。

模板、运行时和测试必须同步维护。否则示例可以编译，却可能在真实 IDE 中因接口漂移而失败。

四、一键安装：缩短修改到验证的距离

传统插件开发需要安装依赖、编译、打包、安装并重新加载窗口。开发模式下可以提供一键安装能力，自动完成：

1. 检查或安装依赖；
2. 编译最新源码；
3. 清理当前配置中的同标识旧引用；
4. 覆盖安装当前插件；
5. 根据激活状态提示是否需要重新加载窗口。

服务依赖应在异步边界前完成解析，避免持有已经失效的访问上下文。“已经安装”也不应阻止开发期覆盖更新，但生产环境仍要遵循版本与签名策略。

五、构建与插件包交付

模板应提供类型检查、Lint、编译、监听和打包脚本，例如：

npm run check-types
npm run lint
npm run compile
npm run watch
npm run package

当运行时较旧时，应选择与其兼容的打包工具版本，并在 CI 中锁定依赖。缺少仓库信息、许可证或发布元数据可能只产生警告，但正式交付前仍应补齐。

六、公共能力建设的完整交付面

一套可持续使用的插件体系至少包含：

• 稳定的公共 API 门面；
• 查询、菜单与事件等基础能力；
• 与运行时一致的类型声明；
• 可直接创建的插件模板；
• 开发期覆盖安装流程；
• 用户文档与培训材料；
• 基于真实工程的端到端验证；
• API 兼容性和回归测试。

最重要的经验是：对外开放能力不能停留在“接口可调用”。声明文件、运行时门面、模板、示例、安装入口、验证路径和交付文档必须一起完成，才能形成真正可维护的开发产品。

后续还可以围绕 API 稳定等级、版本兼容策略、模板升级机制和自动化集成测试继续完善。