芯捷图匠

英文名：Xinjie ImageCraft。中文系统显示“芯捷图匠”，英文系统显示英文品牌名。

仓库：https://gitcode.com/XJ-Cyber/xinjie-imagecraft

鸿蒙原生、本地优先的批量图片处理工具。Stage + ArkTS + ArkUI，图片不上传服务器，工程不申请网络权限。

开发环境

• DevEco Studio 26.0.0。
• 内置 HarmonyOS SDK 26.0.0.105，目标版本为 26.0.0，最低兼容版本为 HarmonyOS 5.0.0（API 12）。
• 设备类型：phone、tablet、2in1；折叠屏通过窗口宽度使用同一套布局。
• 业务流程：系统选图 → 配置和单张预览 → 批量处理 → 相册、文件或系统分享。

产品界面

• 底部为“首页”和“我的”两个 Tab，中间为应用内拍照入口；拍摄成功后加入待处理图片。
• 中央入口为应用内相机，支持前后摄像头、闪光、倍率、拍摄确认；另提供三维扫描模式，使用 AR Engine + Spatial Recon Kit 生成 PLY/MP4，设备不支持时保留普通拍照。
• 首页提供搜索、基础/创作/批量分类、12 个工具、示例照片、快捷预设和最近任务。
• 图片压缩、修改尺寸、格式转换、批量处理接入既有引擎；裁剪已接入单图编辑器，支持自由、1:1、4:3、16:9、选框拖动与四角缩放；加水印已接入批量配置，支持文字、图片和满屏平铺，支持位置、大小、不透明度、颜色、角度和间距；拼图已开放长图、横向、网格和自由拼图；九宫格已开放四格、六格、九格、方形单格和保留全图；像素化已开放精细、标准、复古和块大小调整；拼豆图纸已开放 32×32、48×48、64×64 网格、三种色板和颜色统计；人像抠图已开放透明、纯色和证件照背景；一图多规格已开放独立页面，支持常用/自定义规格、焦点裁切、彩色留白和独立输出。
• “我的”提供任务统计、处理记录、默认偏好、隐私和关于；默认偏好独立保存，不被单次任务覆盖。
• 设置中提供五类主题：清爽风格（清透青绿、深海蓝）、简约风格（极简留白）、漫画风格（漫画活力）、深色模式（深夜专注）和温暖风格（暖阳橙）。主题通过 Preferences 持久化，页面和组件使用统一 ThemeToken，切换后当前页面实时更新；深色主题已在模拟器上检查文字、分割线、输入框和选择器对比度。
• 配置页按格式与压缩、尺寸、命名与导出分组；结果页显示缩略图、前后体积、错误与重试。

设计依据和交互验收：产品 UI 文档。拼豆图纸实现规格见 拼豆图纸功能，人像抠图实现规格见 人像抠图功能。

一图多规格的模块划分与验收范围见 一图多规格。功能按独立 domain / policy / service / component / page 组织，完成验证后单独提交并推送。

2026-10-09 CHZ-AL00（API 26）真机已验证多规格双图生成、文件保存、相册保存与系统选图回读、分享面板打开后取消、人像真实透明 PNG、一寸/二寸蓝底证件照和拼豆图纸输出。应用内相机拍照已由用户确认正常；三维扫描入口按运行时能力返回“不支持”，未伪造输出。首页轮播、统一居中标题、顶部对齐短页面和统计字号调整已在模拟器真机尺寸上复核。修复相册 URI 中的中文文件名显示为编码字符串，36 项测试与 SDK 26 签名构建通过。详细边界见 真机调试记录 和 应用内相机与三维场景扫描。 2026-10-10 已完成企业级 UI/主题审查：修复 ArkTS 严格类型问题，统一主题色在页面、工具卡片、设置项、输入框、选择器、相机入口和结果页的使用；模拟器验证首页、偏好页和深色主题切换，36 项自动化测试与 SDK 26 签名构建通过。尚未完成的发布级检查仍包括平板/折叠屏、动态字体、读屏、真实 100 张图片性能和最低 API 12 真机验证。

2026-10-14 CHZ-AL00 发布前回归：真实相册输入（系统选图）→ 九宫格 3×3 生成 9 张全部成功（141.5 KB → 17.7 KB），保存到相册授权与回读正常；深色主题、历史页、语义搜索（"截图"命中 34%）、隐私页新增说明和工具搜索通过。修复 Select 下拉弹层在深色主题下不可见的问题（18 处 Select 补弹出层主题背景并关闭系统模糊材质）。38 项自动化测试与签名构建通过。详见 真机回归记录。

当前界面为 2026-10-14 概念 v3「极简摄影工具」改版：中性暖白底、照片是界面唯一彩色、单一强调色与线性图标；首页为品牌行 + 轮播头图 + 单色工具格 + 最近处理；全部工具为分组行式列表；「我的」为统计卡 + 卡片菜单；新增主题商店（12 套内置主题，分类筛选、迷你预览、一键应用，离线可用）。设计稿与规范见 UI 概念 v3 和 主题池规范。2026-10-14 CHZ-AL00 真机已验证主题商店、8 套主题应用与持久化、深色主题页面和工具列表筛选；38 项自动化测试与签名构建通过。

当前界面按用户六屏参考改为清透青绿风格：首页三列工具、山湖照片轮播、独立工具列表、压缩强度选择、环形任务进度与真实结果对比；统一使用应用内线性图标资源，避免不同系统图标造成的视觉跳变。已有裁剪、加水印、拼图、九宫格、像素化和批处理能力保留。样式与验证见 清透青绿 UI。拼图实现规格见 拼图功能，九宫格实现规格见 九宫格功能，像素化实现规格见 像素化功能。

手机已实测工具分类、搜索空态、待开放详情与示例导入/预览/压缩，示例 JPEG 从 308.8 KB 降至 226.6 KB。裁剪已实测四角缩放、平移、比例切换、重置、生成、再次处理和取消选图保留区域；最终生成 837 × 837 JPEG，应用内本地预览正常，系统分享及文件路径选择器可打开并取消。13 项测试和最终签名构建通过，最新包已安装。真实相册输入、完整导出、最低系统和不同设备布局尚待验收。裁剪实现规格见 裁剪功能。

构建与测试

首次克隆后，先创建本机工程配置（已有 build-profile.json5 时跳过此步）：

cp -n build-profile.example.json5 build-profile.json5

build-profile.json5 可能包含 DevEco 自动生成的签名密码，已从版本控制中排除；仓库仅保存无签名的模板。

在工程根目录执行；如果 DevEco 安装位置不同，调整命令路径。命令行构建需要显式指定 SDK 路径（DevEco 内置终端会自动设置，外部终端需手动传入，否则报 Invalid value of 'DEVECO_SDK_HOME'）。

/Applications/DevEco-Studio.app/Contents/tools/node/bin/node --test tools/test.mjs
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw --mode module -p product=default assembleHap --no-daemon

自动化测试运行实际业务源码，以替身模拟 ImageKit、Preferences、TaskPool 与文件系统。它验证规则、状态流转及资源清理，不能证明真机图片质量、内存峰值或系统授权行为。

未签名构建产物：entry/build/default/outputs/default/entry-default-unsigned.hap。

真机运行

1. 用 DevEco Studio 打开工程。
2. 在 File → Project Structure → Signing Configs 为 com.von.picflow 配置 debug 签名，选择当前连接设备；自动签名需要开发者账号。 在本机 build-profile.json5 的 app.products 中，为 default 产品设置 "signingConfig": "default"，引用同名签名配置。仅添加 app.signingConfigs 材料而没有产品引用时，仍会输出未签名包。
3. 运行 entry 模块，完成选图、预览、处理和导出验证。

签名证书、私钥、profile 和密码保留在本机，不放入仓库。签名产物为 entry/build/default/outputs/default/entry-default-signed.hap。2026-10-08 已修复本机产品签名引用；产品 UI 已完成签名构建、真机安装与启动，完整相册输入/导出及批量性能仍待验收。

实现边界

• 每次最多选 500 张；普通图片最多 2 路 TaskPool，大图单路。保持比例且不放大图片；过大的解码任务提示缩小尺寸。
• 输出格式通过 ImagePacker 能力检测；HEIF 仅在设备编码器支持时显示。动态图片拒绝处理，JPEG 的透明区域合成白底。
• 默认清除 EXIF；选择保留时复制拍摄信息，并校正方向和尺寸。目标体积压缩会逐步降低质量和尺寸，无法达到上限则返回失败。
• 后台策略是停止派发新图片、尽量完成当前图片并保存进度；返回后点击继续。未实现系统挂起后持续后台运算或 WorkScheduler 调度，不能保证被系统强杀前当前图片处理完成。
• 历史保留最近 20 个任务，Preferences 分片保存状态和参数；只记录原图 URI，不复制原图。URI 失效需要重新选图。
• 导出由用户在处理完成页发起；删除记录清理应用内输出，已保存到相册或文件的图片保留。
• 尚未验收：真实图片的 EXIF 隐私清除和旋转、透明 WEBP；文件管理器二次打开导出文件、分享发送；真实 100 张成功率；4K/8K 内存峰值；深色、动态字体、读屏、平板及折叠屏布局。透明 PNG、系统选图回读和相册保存的本轮真机证据见调试记录。

当前状态见 workflow-status.md。尚未达到发布所需的完整真机验收条件。