easysoft ZUI 扩展 Helper 开发
准备与分析
按 共享工作流 解析本次所需上下文、读取适用规则并检查所有权；已有且未变化的发现直接复用。
阅读 helper 规范 的相关部分；涉及包角色、文档或调试页时再读对应规范。从目标和必要调用方判断库内私有 helper、纯函数/类型、状态类、store/单例或浏览器 DOM 模块，不因“可能复用”擅自创建共享包或扩大公共 API。
API 设计
按本次涉及的 helper 类别和变化选择以下决策，未变化的契约引用现状：
- 定义输入、输出、类型、空值和非法输入行为，以及同步/异步错误语义。
- 对状态型 helper 定义所有权、更新/订阅顺序、重入、并发、失败恢复、reset 与 destroy。
- 对持久化定义后端、序列化格式、版本兼容、损坏数据与不可用环境的处理。
- 对浏览器模块定义
window/document/ storage 的环境防护，以及 listener、observer、timer、缓存和 DOM 引用的清理。 - 跨库调用使用被依赖库真实的
packageName；不要从folderName拼出@zui/<name>，不要通过相对路径穿越扩展项目、主仓库或符号链接。 zuiName只用于宿主发现和构建选择。公共模块导入、dependency 名称和类型解析均以packageName为准。
确认门禁
尚无适用批准时，在修改任何文件前按共享工作流给出拟实施计划；以下仅展开本次相关决策：
- 四层上下文、目标库的
folderName/packageName/zuiName、helper 分类及必要参考依据； - 目标、非目标、兼容性和可观察验收场景；
- 公开 API、类型、错误语义、导出路径与必要 JSDoc；
- 数据流、状态所有权、持久化/序列化与副作用；
- 浏览器监听、timer、observer、SSR/global 防护与清理策略；
targetLibRoot内精确文件集、入口、真实依赖和zui.contributes影响；- 在
extensionRoot执行的 dependency/lint/type/test，以及在zuiRoot+extsName执行的联合验证； - 文档、调试页、剩余假设及明确标记的“拟实施范围”。
尚无适用批准时，等待用户对计划明确确认后再实施。
批准复用、修订回复、增量范围和等待期间的推进遵循共享工作流，始终服从当前协作模式。
实施
- 确认且当前模式允许编辑后检查
gitRoot状态，按共享工作流复用或刷新受影响的上下文。 - 仅修改
targetLibRoot及已批准的扩展项目文件。安装依赖、更新扩展 lockfile、lint、类型检查和测试都从extensionRoot执行；不修改宿主源码、依赖、lockfile 或注册；宿主生成物和缓存写入遵循共享工作流的验证隔离与批准规则。 - 默认保持纯函数无副作用且确定；状态型工具明确实例/单例所有权、重入、并发、失败和销毁行为。
- 为公共 API 添加有价值的 JSDoc，并从局部入口和库入口显式导出；不让消费者依赖未承诺的深层路径。
- 依赖分类服从扩展项目当前 package 策略。不要把主仓库的
workspace:*、namespace 或“不声明 @zui 依赖”等局部惯例机械套到扩展项目。 - 若批准范围包含正式文档或调试页，按需读取并遵循
../zuix-doc/SKILL.md或../zuix-dev/SKILL.md；完全位于共享批准范围时不重复确认。
验证与交付
按共享工作流选择本次所需的扩展检查及宿主检查，完成范围内修复和复验。验收项目按涉及的输入、错误、重入/并发、序列化、环境防护或清理行为选择。
涉及宿主运行时或分发时，使用已确认的 zuiRoot + extsName 和准确 zuiName 做所需联合验证，执行位置遵循隔离与批准规则。交付时报告 API、修改文件、影响交付的上下文及分层验证结果，不自动提交、推送或发布。