zuix-helper

name	zuix-helper
description	在独立 ZUI 扩展项目中设计、实现或修复函数、类、store 和其他 helper；实施前确认计划或复用已有批准。

ZUI 扩展 Helper 开发

准备与分析

按 共享工作流 解析本次所需上下文、读取适用规则并检查所有权；已有且未变化的发现直接复用。

阅读 helper 规范 的相关部分；涉及包角色、文档或调试页时再读对应规范。从目标和必要调用方判断库内私有 helper、纯函数/类型、状态类、store/单例或浏览器 DOM 模块，不因“可能复用”擅自创建共享包或扩大公共 API。

API 设计

按本次涉及的 helper 类别和变化选择以下决策，未变化的契约引用现状：

1. 定义输入、输出、类型、空值和非法输入行为，以及同步/异步错误语义。
2. 对状态型 helper 定义所有权、更新/订阅顺序、重入、并发、失败恢复、reset 与 destroy。
3. 对持久化定义后端、序列化格式、版本兼容、损坏数据与不可用环境的处理。
4. 对浏览器模块定义 window / document / storage 的环境防护，以及 listener、observer、timer、缓存和 DOM 引用的清理。
5. 跨库调用使用被依赖库真实的 packageName；不要从 folderName 拼出 @zui/<name>，不要通过相对路径穿越扩展项目、主仓库或符号链接。
6. zuiName 只用于宿主发现和构建选择。公共模块导入、dependency 名称和类型解析均以 packageName 为准。

确认门禁

尚无适用批准时，在修改任何文件前按共享工作流给出拟实施计划；以下仅展开本次相关决策：

• 四层上下文、目标库的 folderName / packageName / zuiName、helper 分类及必要参考依据；
• 目标、非目标、兼容性和可观察验收场景；
• 公开 API、类型、错误语义、导出路径与必要 JSDoc；
• 数据流、状态所有权、持久化/序列化与副作用；
• 浏览器监听、timer、observer、SSR/global 防护与清理策略；
• targetLibRoot 内精确文件集、入口、真实依赖和 zui.contributes 影响；
• 在 extensionRoot 执行的 dependency/lint/type/test，以及在 zuiRoot + extsName 执行的联合验证；
• 文档、调试页、剩余假设及明确标记的“拟实施范围”。

尚无适用批准时，等待用户对计划明确确认后再实施。

批准复用、修订回复、增量范围和等待期间的推进遵循共享工作流，始终服从当前协作模式。

实施

1. 确认且当前模式允许编辑后检查 gitRoot 状态，按共享工作流复用或刷新受影响的上下文。
2. 仅修改 targetLibRoot 及已批准的扩展项目文件。安装依赖、更新扩展 lockfile、lint、类型检查和测试都从 extensionRoot 执行；不修改宿主源码、依赖、lockfile 或注册；宿主生成物和缓存写入遵循共享工作流的验证隔离与批准规则。
3. 默认保持纯函数无副作用且确定；状态型工具明确实例/单例所有权、重入、并发、失败和销毁行为。
4. 为公共 API 添加有价值的 JSDoc，并从局部入口和库入口显式导出；不让消费者依赖未承诺的深层路径。
5. 依赖分类服从扩展项目当前 package 策略。不要把主仓库的 workspace:*、namespace 或“不声明 @zui 依赖”等局部惯例机械套到扩展项目。
6. 若批准范围包含正式文档或调试页，按需读取并遵循 ../zuix-doc/SKILL.md 或 ../zuix-dev/SKILL.md；完全位于共享批准范围时不重复确认。

验证与交付

按共享工作流选择本次所需的扩展检查及宿主检查，完成范围内修复和复验。验收项目按涉及的输入、错误、重入/并发、序列化、环境防护或清理行为选择。

涉及宿主运行时或分发时，使用已确认的 zuiRoot + extsName 和准确 zuiName 做所需联合验证，执行位置遵循隔离与批准规则。交付时报告 API、修改文件、影响交付的上下文及分层验证结果，不自动提交、推送或发布。