---
name: zui-optimize
description: "审计 ZUI 主仓库整库质量或编排多库、跨领域优化；审计只读，优化请求在调查和规划后直接实施。单独的文档、调试页或 i18n 任务使用对应技能。"
---

# ZUI 库优化

## 确定范围与模式

1. 按 [共享工作流](../zui-standards/references/workflow.md) 定位仓库并复用已有上下文。
2. 读取 [references/audit.md](references/audit.md) 中本次审计涉及的维度。
3. 将用户范围解析为：
   - 单库：一个 `lib/<name>` 或 `@zui/<name>`；
   - 多库：明确名称列表；
   - 全库：当前 `lib/*/package.json` 实际发现的全部内置库。不要沿用硬编码数量；`exts/` 仅在用户明确纳入时处理。
4. 检查 `git status`，记录用户已有改动和可用验证基线。明确“全库”默认在只读盘点中包含 WIP/notReady 内置库并单独标记；是否实施这些库的优化由用户请求范围决定。目标名称或是否包含扩展库仍不明确时，先提出最少必要问题。
5. 区分请求模式：
   - 只要求审计、检查或报告时保持只读，输出发现和修复建议；
   - 要求优化、完善或修复时，先调查与审计，再形成计划并直接实施。
6. 只读审计仅运行不会写入仓库、生成目录或缓存的检查。实施任务按共享工作流安排必要的构建、文档、开发服务或 lint 修复及验证，保护用户已有产物。用户明确要求带构建验证的只读审计时，优先使用仓库外临时输出，否则先说明副作用并取得许可。

## 盘点与审计

1. 运行 `../zui-standards/scripts/inspect-zui-lib.mjs` 盘点全部或指定目标。多库可逐库使用 `--lib`；脚本信号不能代替源码判断。
2. 对单库或当前待计划批次中的每个目标，按审计范围追踪相关 package、入口、类型、实现、样式、i18n、正式文档、静态组件预览和调试页；全领域审计覆盖这些维度，窄领域审计只展开相关部分。必要时选择角色、架构或消费方式相近的成熟实现。
3. 大范围任务先依据全体 package 元数据、盘点信号、依赖和现有验证状态做浅层分组，再深读本批目标。浅层盘点不能宣称已确认源码缺陷；不要在尚未形成整体优先级时随机修改第一个库。
4. 按发现类型读取对应领域技能中影响本次判断或计划的部分；实施时复用已有发现：
   - 规范与包角色：`../zui-standards/SKILL.md`
   - UI 组件实现：`../zui-component/SKILL.md`
   - helper/store/utils：`../zui-helper/SKILL.md`
   - 正式文档与静态组件预览：`../zui-doc/SKILL.md`
   - 调试页：`../zui-dev/SKILL.md`
   - 国际化：`../zui-i18n/SKILL.md`
   - 单库跨领域或 package 契约：`../zui-lib/SKILL.md`
5. 按 audit reference 检查代码质量、缺陷、公开 API 文档、调试示例、i18n 和规范一致性。每项发现都记录证据、影响、置信状态、严重度、建议处理和负责技能。
6. 不把风格偏好包装成缺陷。无法从源码、复现或构建结果确认的问题标为风险并制定验证/修复计划，不进行猜测性修复。

## 统一实施计划

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

- 目标库清单、范围排除项、工作区基线和相似库；
- 按库列出的已确认缺陷、风险、文档/示例/i18n/规范缺口及优先级；
- 每项优化的目标、非目标、公开 API/兼容性影响和验收场景；
- 选用的兄弟技能、文件边界、依赖顺序和跨库影响；
- 源码 JSDoc、正式文档、调试页及 i18n 的纳入范围；
- 每库验证命令、基线失败、批次顺序和剩余假设；
- 本次任务范围，精确列出本次允许修改的库、问题和领域。

单库或少量库形成计划后直接实施。全库或大范围先形成整体路线图，再逐批深审、规划、实施和验证，不等待逐批确认；每批修改必须有证据并符合用户请求，不预先承诺尚未调查的修复。

任务范围、必要澄清及协作模式遵循共享工作流。用户只要求审计时，输出发现和建议并保持只读。

## 编排实施

1. 实施前重新检查工作区，只处理用户请求范围内的工作。
2. 对单库跨领域优化可调用 `$zui-lib` 作为该库执行器；窄领域直接调用相应技能。不要让 `$zui-lib` 与直接子技能重复处理同一项。
3. 将任务范围、证据和计划传给子技能，范围内直接实施。范围内的新发现更新计划后处理；超出用户请求或仍有关键歧义时，按共享工作流澄清受影响部分。
4. 先处理共享基础和 helper，再处理依赖它们的组件，然后依次处理 i18n、正式文档和调试页。互不依赖的库按批次并行或顺序执行，但不得混淆各库验收结果。
5. 只修复证据充分且属于任务范围的问题。实施中新发现的范围内问题纳入计划或后续批次；范围外问题单独报告，不顺手扩张。
6. 保留已有库合理的局部目录与 API 风格，避免无关格式化、重命名、迁移和公共契约破坏。
7. 每完成一个库按共享工作流验证并修复范围内问题，更新进度账本；批次结束后仅补充尚未覆盖的组合构建、文档或浏览器验证，不重复有效检查。

## 交付

- 按库汇报已修复缺陷、质量改进、API/JSDoc、正式文档、调试示例和 i18n 变化。
- 区分通过、被基线阻断、未验证和移入后续批次的事项。
- 对比优化前后的可验证行为，不用文件数量代替质量结果。
- 不手工修改 `docs/_` 代替文档源；验证产物及服务管理遵循共享工作流，不自动提交、推送或发布。