开发包、调试包与上传包

一条主线，一条调试支线

Agent 开发辅助工具包 ──提供规则和代理──┐
                                      ↓
组件开发工程 ──构建──→ dist（本次验证基线）──→ 现有 pack 脚本 ──→ package.zip ──→ 目标空间
                           │
                           └──本地预览 / 页面代理──→ 联调结果──→ 返回源码修改

本文推荐调试和打包基于同一次已验证的 dist。执行目标工程现有的 pack 脚本时，还应确认它使用的是本次构建结果；如脚本会重新构建，则以脚本完成后再次验证的产物为准。源码有修改时，应重新执行“构建—联调—打包”。

术语和边界

“Agent 开发辅助工具包”和组件的“开发包”不是同一份内容：前者提供规则和联调工具，后者才是可修改、可构建的业务源码工程。下文统一把后者写作“组件开发工程”。

标准开发路径

1. 准备输入：解压 Agent 开发辅助工具包，并提供现有组件工程、测试页面和验收标准。

2. 确认工程：先读取目标工程的 package.json、构建配置和现有约定；单组件工程与多包工程的命令可能不同。

3. 完成开发：维护 data.json 和 IConfig，实现 Edit、Use、Option 及所需的属性面板、事件和校验。

4. 本地检查：按项目已有脚本执行类型检查、测试和代码规范检查。

5. 构建：执行目标工程现有的构建脚本，并按当前开发辅助工具包契约、工程模板和产物检查脚本核对 dist/。

6. 联调：先做独立预览，再按需用本地代理放进真实编辑页和使用页验证。

7. 冻结产物：记录已验证 dist/ 对应的源码提交、组件名和版本。

8. 生成上传包：执行目标工程 scripts 中已有的 pack 命令生成 package.zip；确认它对应本次已验证的源码和构建产物，不混入调试信息和敏感文件。

9. 平台验收：导入目标空间并重新拖入组件，检查编辑态、属性面板、使用态和事件；入口和页面操作可参考 DeepUX 的自定义组件说明。

命令和包管理器都以目标工程的 package.json、锁文件及 scripts 为准。例如工程确实提供以下脚本时，依次执行：

pnpm run build
pnpm run pack

如果没有 pack 脚本，应先取得目标项目当前使用的模板或同类组件工程，确认上传包生成方式；不要根据本文手工猜测 ZIP 目录结构。

构建产物检查

当前开发辅助工具包的 UX1 契约要求 dist/ 包含：

dist/
├── data.json
├── edit.js
├── use.js
├── option.js
└── icon.svg       # 声明图标时需要

优先执行目标工程已有的产物检查脚本；没有检查脚本时，按当前模板逐项确认：

• data.json 是合法 JSON，组件名称、版本和配置与源码约定一致。

• edit.js、use.js、option.js 都存在，并按当前契约提供默认导出。

• 三个入口是当前契约要求的 SystemJS 产物，外部依赖只使用目标工程允许的公开入口。

• 元数据声明的图标及其它资源都能从构建产物中找到。

• 构建过程没有类型错误、测试失败或被忽略的加载错误。

以上是当前开发辅助工具包的契约，不应用来覆盖目标工程已锁定的旧模板。模板或构建脚本版本不同时，应先核对该工程的检查脚本和加载约定。

调试产物怎么用

当前推荐方式是让页面代理读取组件工程的 public/data.json 和相邻的 dist/，将真实页面对当前组件文件的请求临时替换为本地产物。因此：

• 每次源码修改后先重新构建，再刷新代理页面。

• 没有必要为了联调再制作一个压缩包。

• 临时令牌或 Cookie 只放在被忽略的本地环境文件中。

• 代理、环境文件、页面转储、客户数据和日志都不能进入上传包。

• 联调只做查看和验证，不在真实页面保存、提交、发布或删除数据。

操作提示和只读边界见页面联调。

生成上传包

当前单组件模板执行 scripts 中的 pack 命令后生成 package.zip，约定结构如下：

package.zip
├── package.json
└── dist/
    ├── data.json
    ├── edit.js
    ├── use.js
    ├── option.js
    └── icon.svg       # 声明图标时需要

这份结构用于解释当前流程，实际生成仍以目标工程的现有脚本为准；不要手工套用到模板版本不同的旧工程。

制作时注意：

• 当前模板中 package.json 和 dist/ 位于 ZIP 根目录；不手工调整打包脚本生成的目录层级、文件名或模块内容。

• 本文推荐打包前先验证本次 dist/；任务需要真实页面联调时，还应先完成代理验证。如果 pack 会重新构建，需对最终构建结果补做验证。

• 确认上传包未意外包含代理配置、环境文件、令牌、Cookie、日志或其它敏感信息；实际收录文件由当前打包脚本决定。

• 元数据、源码工程和上传包中的组件名与版本应符合目标工程当前的一致性规则。

• 修改已交付组件时按目标空间的版本规则生成新版本，不复用旧版本内容。

本页只规定上传包如何生成和验收；具体导入入口以目标空间当前页面为准。

多组件物料工程

已有业务物料工程通常在根目录使用 manifest.json 管理分组，并在 packages/* 下放多个组件：

materials-project/
├── manifest.json
├── package.json
├── pnpm-workspace.yaml
└── packages/
    ├── component-a/
    └── component-b/

manifest.json 描述工程和分组，不等于某个组件的上传包。packages/* 子项目按现有工程约定分别开发、构建和联调；最终如何打包和交付，应遵循该物料工程已有的整体流程，不能把单组件工程的打包方式直接套在整个物料工程上。同一工程的命名、作用域和版本也应沿用既有规范。只有确实需要统一维护多个相关组件时才使用这种结构，单个自定义组件不必升级为物料工程。

交付完成标准

• 能指出组件开发工程的准确目录和修改文件。

• 本地检查通过，dist/ 符合目标工程当前模板且加载契约正确。

• dist/ 已完成本地可见预览；任务需要真实数据或页面上下文时，还应完成真实编辑页和使用页的代理验证。

• 上传包由目标工程现有 pack 脚本生成，并能追溯到本次已验证的源码和构建产物；若打包时重新构建，最终产物也已验证。

• 目标空间导入后，组件可拖入、可配置、可使用，事件与多实例互不干扰。

返回UX1 自定义组件完整开发流程，或继续查看组件工程与加载契约。