---
name: zui-helper
description: "在 ZUI 主仓库的 lib/* 中设计、实现或修复函数、类、store 和其他 helper；需求明确时完成必要设计后直接实施。"
---

# ZUI 辅助工具开发

## 准备与分析

按 [共享工作流](../zui-standards/references/workflow.md) 定位目标并复用已有上下文，阅读 [helper 规范](../zui-standards/references/helper.md) 中与本次变更有关的部分。涉及包角色、文档或调试页时再读对应规范。

维护 `@zui/core` 的 Web Component 工厂、属性描述符或元素运行时时，同时读取 [Web Component 规范](../zui-standards/references/web-component.md)，核对调用方的类型推导、注册与生命周期契约。

从目标及必要调用方判断纯函数/常量/类型、状态类、store/单例、浏览器 DOM 模块或库内私有 helper 的归属，核实本次涉及的副作用、错误和清理约定。不要擅自把私有 helper 提升为共享包。

新增工具或能力前执行[先查找，再复用](../zui-standards/references/workflow.md#复用已有能力)，按行为及符号名检索已有 helper、类型与基础设施；设计中说明所复用的 API 或必须新增的缺口。

## 实施计划

按共享工作流形成实施计划；以下仅展开本次相关决策：

- 类型判断、放置目标及相似实现；
- 目标、非目标和验收场景；
- 公开 API、类型、错误语义、导出路径和必要 JSDoc；
- 数据流、状态所有权、持久化/序列化以及副作用；
- 浏览器监听、计时器、observer、SSR/global 防护和清理策略（若适用）；
- 文件集、依赖、入口和 `contributes` 影响；
- 文档/调试需求、验证方式和假设。

需求明确后直接实施；任务范围、必要澄清及协作模式遵循共享工作流。

## 实施

1. 重新检查工作区状态，仅实现任务范围内的工作。
2. 默认保持纯函数无副作用、确定性和完整类型；状态型工具明确所有权、重入、并发、失败和销毁行为。
3. 对公开 API 添加有价值的 JSDoc，并从局部 `index.ts` 与库入口显式导出；不要依赖未承诺的深层路径。
4. 仅在范围内组合 `$zui-doc` 或 `$zui-dev`，不要为文档或演示修改不相关运行时代码。
5. 按共享工作流验证本次改动、修复范围内问题并复跑受影响检查；按涉及的行为选择 helper 验收项目。
6. 汇报 API、文件、验证结果和风险，不自动提交。