---
name: zuix-helper
description: "在独立 ZUI 扩展项目中设计、实现或修复函数、类、store 和其他 helper；需求明确时完成必要规划后直接实施。"
---

# ZUI 扩展 Helper 开发

## 准备与分析

按 [共享工作流](../zuix-standards/references/workflow.md) 解析本次所需上下文、读取适用规则并检查所有权；已有且未变化的发现直接复用。

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

新增工具或能力前执行[先查找，再复用](../zuix-standards/references/workflow.md#复用已有能力)，检索当前扩展项目和宿主已有 helper、类型与基础设施；设计中说明所复用的真实包名、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、修改文件、影响交付的上下文及分层验证结果，不自动提交、推送或发布。