动图魔方技术拆解 20：HarmonyOS 工具 App 发布前工程清单与复盘

SEO 信息

• SEO 标题：动图魔方技术拆解 20：HarmonyOS 工具 App 发布前工程清单与复盘
• SEO 摘要：本文作为"动图魔方技术拆解"20 篇系列收官，基于 HarmonyOS NEXT / ArkTS 项目 GIFRubiksCube，整理一个工具类 App 发布前的工程清单：从素材导入、GIF 编辑、导出、作品持久化、3D 预览，到 Hvigor 构建、模拟器截图、CSDN 发布记录和后续 SDK 路线，形成可复验、可交接、可继续迭代的发布复盘。
• 关键词：HarmonyOS, harmonyOS, ArkTS, ArkUI, GIF 工具, 发布前清单, 工程复盘, Hvigor, CSDN 系列
• 文章封面 ：doc/csdn-series/covers/cover-20-release-checklist-retrospective.jpg
• 投稿方向：普通技术拆解文
• 项目环境 ：HarmonyOS SDK 6.1.0(23)、ArkTS、DevEco Studio、GIFRubiksCube
• 验证时间：2026-06-27 16:40 +08:00
• 验证对象 ：doc/csdn-series/20篇系列规划.md、doc/csdn-series/publish-record.json、entry/src/main/ets/products/main/Index.ets、build-profile.json5、doc/screenshots_current/*.jpeg

第 20 篇不再拆一个单点函数，而是把整个系列收回来：一个 HarmonyOS 工具 App 从功能实现到技术文章发布，最终要留下什么证据，哪些记录能支撑下一次迭代，哪些口径不能被宣传文案带跑。这篇就是动图魔方这一轮工程和 CSDN 系列的发布前清单。

一、真实工程问题背景

写到第 20 篇时，最容易出现的不是"没有内容可写"，而是内容太多、证据太散。动图魔方已经有素材导入、视频转 GIF、图片序列合成、GIF 重编辑、字幕滤镜、导出进度、作品列表、主题切换、3D 预览和能力降级。如果最后只说"项目完成了"，读者和后续维护者都不知道到底完成到哪一步。

为什么发布前必须做工程清单？

1. 功能很多，但用户只看连续体验。素材能导入，不代表导出结果能保存；导出能成功，不代表作品页能回看；3D 入口能打开，不代表当前构建已经具备真实 3DGS 执行体。
2. 截图很多，但截图需要对应源码。如果截图只作为效果展示，后续 UI 变化时没有人知道它要保护哪条规则。
3. 文章很多，但发布记录要能去重。20 篇系列必须用编号、标题、封面、articleId 和公开页互相校验，否则最后两篇发布时很容易重复或漏记。
4. 构建成功不是全部，但它是底线 。第 19 篇已经证明当前 Hvigor assembleHap 能通过，第 20 篇要把这个结果放进发布清单。
5. 未来路线不能挤进当前版本承诺。3DGS、多模态素材、跨设备创作都可以规划，但当前发布复盘要分清"已交付""已预留"和"待 SDK/平台条件成熟"。

为什么这个问题会在收官阶段集中出现？原因是用户路径已经从单页演示变成了跨 Tab 的连续任务：用户可能先在首页理解功能，再切页到编辑区导入素材，导出后回作品页复查，最后又到 3D 或设置页确认能力边界。任何一个页面截图、源码规则或构建口径不一致，都会导致验收结论变得含糊。最典型的风险是"截图看起来能用，但源码实际保护的是另一条规则"，或者"构建通过了，但发布记录仍停在上一篇"。所以第 20 篇必须把现象、原因、影响和验证路径放在同一张清单里。

这一篇的角色有点像关灯前的巡场：不是为了再加一个酷功能，而是确认门窗、账本、工具和下一步路线都对得上。

二、目标与边界

第 20 篇的目标是形成一张可复验的发布前工程清单。它服务三个对象：开发者、测试者和下一次自动化发布。

对象	关心什么	本文给出的证据
开发者	功能入口和源码对象是否清楚	Index.ets、服务层、构建配置
测试者	哪些截图对应哪些验收项	doc/screenshots_current/*.jpeg
发布者	文章、封面、公开链接是否一致	doc/csdn-series/publish-record.json
维护者	后续要从哪里继续	第 19 篇构建口径和第 20 篇复盘清单

边界也要明确：本文不是 AppGallery 上架说明，不替代隐私合规、资质材料和正式签名检查；也不是 CSDN 平台教程，不讨论后台推荐机制。本文只做当前工程本身的发布前复盘。

三、20 篇系列的工程主线

这 20 篇不是随机凑题，而是从产品入口一路拆到发布闭环：

阶段	篇目	工程主线
产品基础	01-05	底部导航、媒体链路、本地优先、服务卡片、3D 前瞻
GIF 内核	06-10	GIF89a、LZW、调色板、帧处理、GIF 重编辑
任务体验	11-13	TaskPool、导出进度、作品和草稿持久化
UI 收口	14-16	Tab 状态、主题模式、移动端宽度一致性
验收增强	17-18	真实素材、3D 能力检测与降级
发布底座	19-20	SDK/Hvigor 构建、发布前清单与复盘

这个顺序的好处是读者可以按问题链路阅读：先理解 App 做什么，再理解 GIF 怎么生成，再理解长任务和本地数据怎么保护，最后看构建和发布如何收尾。

四、源码对象总表

发布前清单要避免"口头完成"。下面这张表把主要能力和源码对象对齐：

能力	主要源码对象	发布前检查点
主页面和导航	entry/src/main/ets/products/main/Index.ets	五个 Tab 可进入，底部导航不遮挡
素材导入	entry/src/main/ets/common/services/TestAssetService.ets	测试素材能进入编辑链路
GIF 导出	entry/src/main/ets/features/gif/services/ExportService.ets	导出有进度、可取消、可进入作品
帧处理	entry/src/main/ets/features/gif/services/media/FrameProcessor.ets	图片、视频、GIF 多帧进入统一流水线
编码任务	entry/src/main/ets/features/gif/services/GifEncodeTask.ets	长任务不阻塞 UI
本地存储	entry/src/main/ets/common/services/StorageService.ets	作品、草稿、主题可持久化
3D 预览	entry/src/main/ets/features/threeD/components/Model3DView.ets	不支持时有降级说明
能力路由	entry/src/main/ets/features/threeD/services/CapabilityService.ets	设备能力和构建能力分开
构建配置	build-profile.json5	SDK、签名、strictMode 可复查
启动入口	entry/src/main/ets/entryability/EntryAbility.ets	Ability 生命周期能进入主页面
页面路由	entry/src/main/resources/base/profile/main_pages.json	主页面声明和构建产物一致
系列发布记录	doc/csdn-series/publish-record.json	文章编号、封面、URL 去重

这张表的意义是让"发布前检查"从口号变成路径。后续如果某个功能出问题，不需要翻 20 篇文章找上下文，先从这里定位对象。

五、主页面不是页面堆叠，而是发布前验收入口

Index.ets 在这个项目里承担了一个很重的角色：它既是主页面，也是发布前验收入口。不是因为所有逻辑都应该塞进一个文件，而是因为当前工具的用户旅程需要从同一个页面切换到不同工作区。

@Entry
@Component
struct Index {
  @State private activeTab: string = 'home';
  @State private works: WorkRecord[] = [];
  @State private drafts: DraftRecord[] = [];
  @State private selectedTheme: ThemeMode = 'system';

  build() {
    Stack() {
      Column() {
        this.PageContent()
      }
      .width(this.contentWidth())
      .height('100%')

      this.BottomNav()
    }
    .backgroundColor(this.theme.background)
  }
}

发布前看这个文件，不是为了检查某个 @State 是否写得漂亮，而是确认这些状态背后都有验收路径：

1. activeTab 对应首页、作品、编辑、发现、我的切换。
2. works 对应导出后的作品列表回看。
3. drafts 对应编辑中断后的草稿恢复。
4. selectedTheme 对应第 15 篇深浅色和跟随系统。
5. 3D 入口和能力文案对应第 18 篇能力边界。

这也解释了为什么第 20 篇仍然要引用 Index.ets。它不是所有能力的最终归宿，却是用户能否把能力串起来的第一验收点。

六、功能链路清单

工具类 App 的发布前检查，不能只列"功能已开发"。更好的方式是按用户动作串联：

用户动作	应用响应	源码对象	验收证据
打开首页	看到 GIF 工具入口和底部导航	Index.ets	gifrubik_home.jpeg
进入编辑	能选择素材类型和参数	Index.ets	gifrubik_editor.jpeg
使用测试素材	自动准备真实素材	TestAssetService.ets	gifrubik_test_asset_loaded.jpeg
点击导出	显示进度和取消能力	ExportService.ets	gifrubik_test_asset_exported.jpeg
查看作品	导出结果进入作品列表	StorageService.ets	gifrubik_works.jpeg
打开 3D	显示预览或降级说明	Model3DView.ets / CapabilityService.ets	gifrubik_3d.jpeg
切换主题	深色和浅色可读	StorageService.ets / Index.ets	gifrubik_profile_expanded_dark.jpeg
发布前构建	HAP 构建成功	build-profile.json5	Hvigor 输出

这张表也能帮助判断优先级。如果某次发布前时间很紧，至少要跑通"打开首页 -> 编辑 -> 导出 -> 作品 -> 构建"这条主链路；3D、主题、分享则按版本目标补充验收。

七、构建证据不能只留在终端

第 19 篇已经跑过 Hvigor，本篇把结果收入发布前清单：

$env:DEVECO_SDK_HOME = 'D:\HuaweiDevelopFormalStudy\DevEco Studio\sdk'
$env:Path = 'D:\HuaweiDevelopFormalStudy\DevEco Studio\jbr\bin;D:\HuaweiDevelopFormalStudy\DevEco Studio\sdk\default\openharmony\toolchains;D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\node;' + $env:Path
& 'D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.bat' assembleHap --mode module -p product=default --no-daemon

构建摘要：

> hvigor UP-TO-DATE :entry:default@CompileArkTS...
> hvigor UP-TO-DATE :entry:default@PackageHap...
> hvigor UP-TO-DATE :entry:default@SignHap...
> hvigor BUILD SUCCESSFUL in 3 s 189 ms

这段结果说明当前版本至少满足三个底线：

1. ArkTS 编译没有阻塞。
2. HAP 打包和签名流程没有阻塞。
3. build-profile.json5 当前 SDK 和 product 配置能被 Hvigor 接受。

官方命令行构建文档也强调可以通过 hvigorw 读取工程配置并执行构建任务，参考：命令行构建工具 hvigorw。

构建配置本身也应该和工程 build-profile.json5 对齐，字段含义和 product / module 组织方式可以参考：build-profile.json5 配置说明。

八、截图证据与源码映射

第 20 篇的截图不是为了展示"界面挺好看"，而是为了给发布前清单落证据。

截图	对应源码位置	需要证明的规则
https://i-blog.csdnimg.cn/direct/efeec2074b0247fe8b4629b27a1a90aa.jpeg	entry/src/main/ets/products/main/Index.ets:1578	主容器宽度和底部导航同源
https://i-blog.csdnimg.cn/direct/11214b59c5d0419cb03f0357f69ac06e.jpeg	entry/src/main/ets/products/main/Index.ets:931	编辑页存在测试素材入口
https://i-blog.csdnimg.cn/direct/0d9ad31abba14c4c9d9cbf5e69137272.jpeg	entry/src/main/ets/products/main/Index.ets:466	真实素材能进入编辑链路
https://i-blog.csdnimg.cn/direct/3d18169d59e94382b04727cfd1aa0d50.jpeg	entry/src/main/ets/products/main/Index.ets:889	3D 预览入口可见
https://i-blog.csdnimg.cn/direct/8d56691f324d40d5885465386d1e5322.jpeg	entry/src/main/ets/products/main/Index.ets:595	导出结果能进入作品列表
doc/screenshots_current/gifrubik_profile_expanded_dark.jpeg	entry/src/main/ets/products/main/Index.ets:337	主题偏好可保存

这张映射表让截图具备回归价值。以后如果页面重构，只要这些截图对应的规则还在，就可以重新截图复核；如果规则变了，也能知道该更新哪篇文章和哪段验收。

九、发布记录也是工程资产

CSDN 系列发布记录不是后台流水账，它对工程有三个作用：

1. 防止重复发布同一编号。
2. 保证标题、封面、articleId、公开页和本地稿件一致。
3. 记录平台状态，例如审核中、公开、高质量、封面缩略图是否验证。

本系列使用的记录文件是：

doc/csdn-series/publish-record.json

第 20 篇发布前必须确认：

node -e "const fs=require('fs'); const j=JSON.parse(fs.readFileSync('doc/csdn-series/publish-record.json','utf8').replace(/^\\uFEFF/,'')); console.log(j.items.map(x=>x.number).join(','));"

发布记录的字段不只是给人看的，也给自动化去重：

{
  "number": 20,
  "localSource": "doc/csdn-series/20-HarmonyOS工具App发布前工程清单与复盘.md",
  "title": "动图魔方技术拆解 20：HarmonyOS 工具 App 发布前工程清单与复盘",
  "articleId": "",
  "editorUrl": "",
  "successUrl": "",
  "publicUrl": "",
  "coverSourcePath": "doc/csdn-series/covers/cover-20-release-checklist-retrospective.jpg",
  "coverUrl": "",
  "publishedAt": "",
  "reviewStatus": "",
  "qualityBadgeActual": ""
}

文章发布后，这些字段必须回填。尤其是封面缩略图，第 18 篇已经证明"上传成功"不等于"列表页有封面"，所以第 20 篇之后要把内容管理页缩略图核验也写进记录。

十、CSDN 发布前清单

检查项	必须结果	说明
编号	20	不超过 20 篇，不重复
标题	动图魔方技术拆解 20：...	普通技术文不加共创季前缀
封面	复用系列模板	背景、编号、标签、页脚保持一致
本地质检	node tools/check_csdn_article_quality.js 20 通过	先过本地结构检查
正文图片	至少 4 张工程截图	截图必须对应源码规则
代码证据	至少 6 段关键代码/命令	不只写概念
官方链接	至少 1 个官方文档	支撑构建或配置说明
标签	同时包含 harmonyOS 和 HarmonyOS	全局发布规则
成功页	/creation/success/{articleId}	证明发布动作完成
公开页	title/H1 无乱码	防止中文编码事故
管理页	有封面缩略图	不再只看上传响应
记录	回填 publish-record.json	完成系列闭环

这张清单之后也可以复用于其他 HarmonyOS 工具类项目，只需要替换项目名、截图、源码对象和发布记录路径。

十一、自动化发布的经验复盘

这轮系列发布中，自动化最值得保留的经验有四条。

第一，旧规则要能被覆盖。曾经有"必须先核验上一篇高质量"的硬规则，但用户后来明确改成不再把它作为下一篇阻塞。全局 skill 和自动化记忆都要跟着改，否则自动化会拿旧规则阻碍新目标。

第二，真实 UI 操作更稳 。CSDN 编辑器的接口和前端 bundle 不稳定，能通过真实按钮上传封面、插入图片、点击发布，就不要凭猜测拼 saveArticle payload。第 18 篇封面问题也说明，上传响应本身不能证明编辑器封面状态真的被设置。

第三，内容管理页是发布后证据的一部分。成功页、公开页和管理页分别证明不同事情：成功页证明发布动作完成；公开页证明文章可访问且标题无乱码；管理页证明后台状态、封面缩略图和高质量标识。

第四，本地文档要及时回写 。如果 publish-record.json、发布清单和 memory 不同步，下一次自动化就会从错误编号开始，或者重复处理已经发布的文章。

十二、当前版本能力边界

第 20 篇必须把能力边界说清楚，这对读者和后续维护都很重要。

能力	当前状态	后续路线
图片序列转 GIF	已具备工程链路	继续优化尺寸和调色板质量
视频抽帧转 GIF	已具备工程链路	真机素材和长视频性能继续补测
GIF 多帧重编辑	已拆解实现路径	后续加强内存峰值控制
字幕和滤镜	已进入帧处理流水线	后续做更多预设
导出进度和取消	已形成用户可感知状态	后续补后台任务/通知
作品和草稿	已本地持久化	后续补导入导出或备份
深浅色主题	已有应用级 ColorMode	后续补更多系统动态适配
3D 预览	已有入口和降级	真实 3DGS 执行体等待 SDK 条件
Hvigor 构建	当前通过	后续接入更正式的发布签名和流水线

这个表比一句"功能已完成"更诚实。发布不是把所有规划都说成现实，而是把已完成、已预留和待验证分清。

十三、复现命令与本地质量检查

第 20 篇发布前保留这些命令：

rg -n "动图魔方技术拆解 20|cover-20|162" doc/csdn-series

rg -n "targetSdkVersion|compatibleSdkVersion|runtimeOS|strictMode" build-profile.json5

rg -n "ExportService|StorageService|CapabilityService|Model3DView|TestAssetService" entry/src/main/ets/products/main/Index.ets entry/src/main/ets/features -g "*.ets"

Get-ChildItem -Path 'doc\screenshots_current' -Filter '*.jpeg' | Select-Object -First 20 -ExpandProperty FullName

node tools/check_csdn_article_quality.js 20

本地质检要看的是结构完整度，不替代 CSDN 后台状态。它能提前发现标题编号错、SEO 信息缺失、截图太少、代码证据不足、没有验收表等问题。真正发布后，还要检查公开页和内容管理页。

十四、发布后核验清单

核验对象	方法	失败时处理
成功页	检查 /creation/success/{articleId}	没有成功页就不记录为已发布
公开页标题	检查 document.title 和 h1	乱码则回编辑器修标题
正文图片	检查公开页图片可加载	失败则重新托管图片
标签	检查含 harmonyOS / HarmonyOS	缺失则编辑补录
封面预览	编辑器中可见封面	不可见则重传封面
列表缩略图	内容管理页目标行有缩略图	显示 未设置封面 则回编辑器补传
发布记录	回填 articleId / URL / coverUrl	缺字段则下次自动化会误判
系列清单	更新第 20 篇状态	保证 20 篇目标闭环

第 18 篇留下的教训已经写进全局 skill：封面必须核验内容管理页缩略图。第 20 篇作为收官，尤其不能在这一步漏掉。

十五、工程验收清单

验收项	结果	证据
20 篇规划已覆盖	通过	doc/csdn-series/20篇系列规划.md
第 20 篇标题规范	通过	普通技术文标题无活动前缀
功能主链路可说明	通过	首页、编辑、导出、作品、3D
截图和源码有映射	通过	第八节截图表
构建已验证	通过	BUILD SUCCESSFUL in 3 s 189 ms
发布记录具备回填字段	通过	publish-record.json 字段结构
封面缩略图核验规则已纳入	通过	全局 csdn-publishing skill
后续能力边界明确	通过	当前能力边界表
本地质量检查入口存在	通过	node tools/check_csdn_article_quality.js 20
系列收官有复盘结论	通过	本文第十六节

十六、系列收官复盘

回看这 20 篇，动图魔方系列真正沉淀下来的不是"发了 20 篇文章"，而是一套工作方式。

1. 功能拆解要贴着真实代码。每篇都有自己的源码对象、截图或日志证据，而不是把同一套介绍换标题。
2. 发布动作要回写本地记录 。CSDN 后台状态、公开页、封面和 articleId 都要落到 publish-record.json，否则自动化没有可靠记忆。
3. 工程文档要能反向指导开发。第 16 篇后的卡片宽度，第 18 篇后的能力边界，第 19 篇后的构建命令，都会影响后续代码和发布。
4. 不能为了平台分数牺牲工程诚实。高质量标识和 QC 分数可以作为反馈，但文章主体必须服务读者和真实问题。
5. 未来能力要留接口，也要留边界。3DGS、多模态、跨设备都值得继续，但当前版本的可交付范围必须说清楚。

这一轮结束后，doc/csdn-series 就不只是发布素材目录，而是项目的一组工程审计记录。以后再做 AppGallery 上架、版本更新、或者迁移到新 SDK，都可以从这里回看每条能力的来龙去脉。

十七、后续路线

第 20 篇是"动图魔方技术拆解"这个 20 篇目标的收官，但不是项目停止。后续更适合进入三个方向：

1. 发布工程：把调试签名、正式签名、隐私合规、AppGallery 素材和审核记录单独沉淀。
2. 性能工程：围绕长视频、高清图片序列、GIF 大文件和内存峰值继续做专项优化。
3. 能力升级：等 SDK 和设备条件成熟后，把第 18 篇预留的 3DGS 执行体补上，并重新跑第 19 篇构建清单。

至此，20 篇系列完成了一个从功能实现、体验验收、构建排查到发布复盘的闭环。下一次继续做，不应该从"我还记得当时怎么改的"开始，而应该从这些本地文档、源码对象、构建命令和发布记录开始。