华为云码道 CodeArts 造了 CuiLianTu——一张报名照卡在 50KB，简历投递材料的硬性要求

一张报名照卡在 50KB，四条路全堵死——我用华为云码道 CodeArts 造了 CuiLianTu

一键开通华为云码道 CodeArts 代码智能体：https://developer.huaweicloud.com/codeartsco.html?source=dmzntgwatomgit1&sourcead=dmzntgwatomgithd

参与方向：全场景项目实战（兼及零基础入门）
项目仓库：atomgit.com/CYXue/cuiliantu ｜ github.com/CYXue/cuiliantu
当前版本：v0.2.1（三平台 CI 构建，7 个发行资产）
技术栈：Rust + Tauri 2 + SolidJS + TypeScript
作者：CYXue

摘要

本文记录我使用华为云码道 CodeArts 代码智能体，完成桌面端批量图片处理工具CuiLianTu（淬炼图）从架构设计、功能开发、工程化加固到三平台发布的全流程实践。这个项目的起点，是一张怎么都传不上去的报名证件照——一个真实的、带着截止时间的痛点。文章不做产品宣传，重点沉淀四样东西：

1. 一套可复用的 AI 辅助开发工作流（云仓库工作区 + 代码检查 + 单测生成 + 门禁收尾）；
2. 一份真实的踩坑清单——12 个坑全部有复现路径与修法，其中 3 个（坑 3、5、8）属于「零报错、结果错」的静默失效类，AI 与人都极难察觉；
3. 核心功能「目标体积」的源码级拆解——一个二分搜索如何同时做到「恰好卡线」与「预览即所见」；
4. 三条从踩坑中提炼的方法论纪律，适用于任何 AI 编程智能体。

一、项目背景：一份报名表催生的工具

CuiLianTu 的起点不是宏大的架构规划，而是一次网上报名卡在照片上传环节。报名系统对上传材料有一串硬性要求：

而现实是：手机拍一张 3–8 MB，格式还可能是 HEIC/PNG；扫描件更大；报名系统既不帮压也不帮转，超了就拒收。

临交材料那几天，我把能想到的路全摸了一遍：

四条路全堵死。那就自己写一个——需求清单都是现成的，就是那张报名须知。

于是「淬炼图」诞生了——报名表里每一条要求，都对应一个功能：

二、产品实证：从一张图到核心功能

功能列表容易自夸，直接上实测。

2.1 实测一张图：转格式本身就会改变体积

以一张 53.4 KB 的 PNG 截图（254×215）为例，质量 100%、不改尺寸、不做其他处理，仅切换输出格式：

同一个文件、同一个质量参数，仅仅换格式，结果差了将近一倍。两个结论：

• 报名系统「仅收 JPEG/JPG」不全是刁难——JPEG 对照片类图像的压缩效率确实远高于 PNG；
• 但「转个格式」并不必然变小，盲转可能反而更大（上图 PNG→PNG 反弹了 7.5%）。

而且 JPEG 只是六种输出格式之一：WebP 对应网页优化场景（参数模板区同样内置了「网页优化 WebP」预设）、PNG 保透明、GIF/BMP/TIFF 各有所需——同一张图，目标是什么平台、什么系统要求，就转什么格式，预览区都会先把结果体积摆给你看。

这正是把实时预览做成核心交互的原因：转换还没执行，预览区就已经告诉你输出体积（53.4 KB → 30.2 KB，↓43.5%）、输出尺寸，以及「原图 / 效果」的分屏对比，拖动滑块即时刷新，还支持拖框裁剪。配合参数模板区的「证件照 ≤50KB」「资料 ≤300KB」预设和「目标大小」开关（按 KB 预算自动调整 JPEG 质量），报名材料的尺寸与体积要求在点导出之前就能全部确认——20 分钟填表限时里，留给图片处理的时间以秒计。

2.2 功能全景与几个别处少有的设计

在此之上，工具逐步长成了完整的批量处理平台。主打隐私优先——不上传、无账号、无网络依赖，处理身份证、学历证书这类材料，这是底线而非卖点：

在通用功能之外，有几个设计是摸排过的现成工具里基本没见过的：

• 空手预览— 不加载任何文件，预览和参数调节照样可用。先把质量、尺寸、水印调到满意，再拖图进来直接导出；对「同一批材料用同一套参数」的报名场景，参数只调一次。
• 目标体积是「先给预算，再倒着压」— 不是压完看多小，而是先给定 KB 上限（≤50KB、≤300KB），用二分法反向搜索 JPEG 质量参数，一张和一百张，每张都恰好卡线达标。
• 拖框裁剪 + 分屏对比— 196×250 这类尺寸要求，直接在预览图上框选构图，「原图 / 效果」分屏同步查看，不用导出后开了又改。
• 批量统计带中位数— 处理完给出总体 / 平均 /中位数三个压缩率。平均数会被个别异常图片拉偏，中位数一对比，就能发现「大多数压得正常、个别图片异常膨胀」，批量场景里非常有用。
• 大图防线— 解码前先探测图像声明的像素数（超过 256 MP 直接拒绝）、批次内存按 4 GiB 预算钳制——几百张大图一起拖进来，程序不会静默崩溃，而是明确报错（第五章阶段三详述）。
• 便携与开源— Windows 便携版解压即用、免安装免管理员权限；MIT 开源，没有付费墙、没有按次收费、没有广告位。

2.3 特色功能拆解：「目标体积」是怎么做到恰好卡线的

以「证件照 ≤50KB」为例。JPEG 的体积与质量参数之间没有解析公式——同一个质量值对不同内容的输出大小可以差数倍，想「算出」正确参数是不可能的，唯一可靠的办法是二分搜索。核心实现（Rust，src-tauri/src/image/processor.rs）：

/// Bisect JPEG quality so the encoded size fits `limit`, keeping quality as/// high as possible. Returns `(bytes, quality_used, within_limit)`.fnencode_jpeg_to_target(img:&DynamicImage,limit:u64,)->Result<(Vec<u8>,u8,bool),ProcessError>{// Bounds for the search: below MIN the artifacts are too visible for// ID photos; above MAX we waste bytes with no perceptual gain.constMIN_SEARCH_QUALITY:u8=30;constMAX_SEARCH_QUALITY:u8=95;letlimit=limitasusize;let(mutlo,muthi)=(MIN_SEARCH_QUALITY,MAX_SEARCH_QUALITY);letmutbest:Option<(Vec<u8>,u8)>=None;whilelo<=hi{letmid=(lo+hi)/2;letencoded=Self::encode_jpeg(img,mid)?;ifencoded.len()<=limit{best=Some((encoded,mid));lo=mid+1;// 达标了，继续往高质量半区找}else{hi=mid-1;// 超了，往低质量半区收}}matchbest{Some((bytes,q))=>Ok((bytes,q,true)),None=>{// Even the floor quality is too big: ship the best-effort file// and flag it so the caller can warn the user.letbytes=Self::encode_jpeg(img,MIN_SEARCH_QUALITY)?;Ok((bytes,MIN_SEARCH_QUALITY,false))}}}

三十行里藏了三个值得说的实现决策：

1. 搜索边界是 30–95，不是 1–100：低于 30，证件照的压缩瑕疵肉眼可见，压了等于废；高于 95，多花的字节人眼看不出区别。这是产品判断写进算法边界——搜索空间先砍掉四分之一。
2. 达标后继续向高质量半区搜（lo = mid + 1）：保证输出是满足预算的最高质量，而不是随便一个达标的。报名照要在 50KB 里尽量清晰，差的那个质量档位肉眼真能看出来。
3. 兜底走降级不走报错：连 30 质量都塞不进预算时（比如想把一张海报压到 10KB），返回within_limit = false标记，调用方弹提示「已尽力、仍超限」——不中断批量流程、也不静默撒谎。

还有一层：这个函数同时服务导出和预览（encode_to_memory注释里写着used both for writing files and for the preview’s exact size estimation）。所以预览区显示的「30.2 KB」不是估算值，是真实编码一遍的结果——你在预览里看到多大，导出来就是多大。

最后说明为什么拿这个项目参加「全场景项目实战」：它是典型的练兵场——前端交互（SolidJS 响应式）+ 后端管线（Rust 图像处理）+ IPC 边界 + CI 门禁 + 三平台打包发布，一个项目覆盖了软件交付全生命周期，正好把码道 CodeArts 的端到端能力（需求、编码、检查、验证、发布）都用一遍。

三、为什么是 Tauri 2 + SolidJS + Rust

• Rust 做图像处理：批量场景下内存与速度是生命线，imagecrate 生态成熟，且可以对解码像素数做硬上限（第五章阶段三的安全守卫会讲）。
• Tauri 2 做壳：相比 Electron，安装包从上百 MB 降到 11–15 MB，系统 WebView 渲染前端。
• SolidJS 做界面：细粒度响应式没有虚拟 DOM diff，滑块拖动实时预览不卡。
• 代价：三套语言心智（Rust / TS / CSS）+ IPC 边界序列化，这正是 AI 智能体能发挥最大杠杆的地方——跨语言的契约一致性，恰恰是人最容易漏、机器最擅长查的。

四、码道 CodeArts 在本项目中的角色

本项目代码托管在 AtomGit（CYXue/cuiliantu），与码道 CodeArts 天然打通。整个开发过程中，码道承担四类工作：

4.1 云仓库工作区

在码道中选中 AtomGit 仓库后，智能体以仓库为工作区：读取项目结构、定位文件、写入修改、Git 追踪变更。对一个 Rust + TS 混合仓库来说，最有价值的是代码库索引（Codebase）——模型不必逐个读文件就能定位符号与调用关系，跨 crate 的引用（如src-tauri领域模型 ↔ 前端 store）修改时不容易漏下游。

4.2 跨语言契约检查

本项目最核心的契约是IPC 边界的 payload 结构：后端领域模型按组嵌套（output / resize / transform / crop / adjust五组 + 顶层watermark），IPC 边界保留扁平的ProcessingOptionsPayload（serde(default)）经From转换，前端保持扁平的store.options.xxx。这意味着新增一个后端字段要同步三处：组内字段、Payload 字段、From转换。这类「改一处必须动三处」的机械工作，交给智能体做全仓扫描核对，比人肉 grep 可靠得多。

4.3 单测生成与反向验证

图像处理管线有大量数值边界（NaN、负零、越界、除零），码道的单测生成能力适合产出「边界用例骨架」，但生成不等于验证——第七章的纪律一会讲为什么每个闸门必须手工反向测。

4.4 端云协同的代码检查

本地收尾跑七阶段门禁（见第五章阶段三），云端代码检查作为第二道网，两者关注点互补：本地门禁管「能不能合并」，云端检查管「规范与潜在缺陷」。

五、实战复盘：四个阶段

阶段一：架构设计——双层模型定调

开工前先定死架构契约，这是 AI 辅助开发中最重要的一次人工决策：

┌─ 前端 SolidJS ─────────────────────────┐ │ store.options.quality（扁平） │ └──────────────┬─────────────────────────┘ │ IPC（Tauri invoke） ┌──────────────▼─────────────────────────┐ │ ProcessingOptionsPayload（扁平，serde） │ ← 边界层，向前兼容 ├────────────────────────────────────────┤ │ ProcessingOptions（按组嵌套） │ ← 领域层，output/resize/ │ │ transform/crop/adjust └────────────────────────────────────────┘

扁平 payload 做 IPC 边界的好处：前端零改动迁移、新增字段不破坏旧调用方（serde(default)向前兼容）。这个决策让后续十几次功能迭代没有再动过边界层。

阶段二：功能开发——迭代节奏

每个功能循环：需求描述 → 智能体产出改动 + 单测 → 本地跑测试 → 人工验收交互 → 提交。关键经验是把「人工验收交互」设为强制步骤：第六章的坑 8（点击永远无效但零报错）就发生在「测试全绿」的盲区里，纯靠测试报告根本发现不了。

阶段三：工程化加固——安全与稳定性

• 解压炸弹守卫：ImageProcessor::probe_dimensions在 decode 前探测图像声明尺寸，超过MAX_DECODED_PIXELS（256 MP）直接拒绝；批次线程数按最大图内存估算（w·h·4×2），再被BATCH_MEMORY_BUDGET_BYTES（4 GiB）钳制。render 与 decode 两条路径都要探，漏一条就是漏洞。
• 路径白名单（defense-in-depth）：register_allowed_paths拒收敏感目录（.ssh/.gnupg/.aws等），统一REJECTED常量不回显路径；关键纪律是validate与register必须分离——先 register 再 validate 是自证式恒真，等于没查。
• 七阶段收尾门禁：biome / tsc / vitest / vite build / cargo fmt / clippy / cargo test。经验：改完只跑局部测试必漏门禁，全仓脚本一次跑完。

阶段四：发布——三平台与双仓库

v0.2.1 通过 CI 在三平台构建，产出 7 个资产（dmg ×2 / setup.exe / msi / portable.zip / app.tar.gz ×2），macOS 首次构建即通过。发布链路有两个值得记的细节：

• tauri-action 产出的是 draft release，tag 是untagged-xxx临时名，需要手动 PATCHdraft:false+tag_name才能关联正式 tag；
• portable.zip 不在 CI 产物里，要走 API 用upload_url手工补传。

六、踩坑实录（12 个，附复现路径与修法）

以下全部为实战中真实踩到。按危害分级：🔴 = 阻断构建/发布，🟠 = 静默失效（零报错、结果错），🟡 = 高频误踩。

🔴 坑 1：tauri crate 与 npm 包版本必须 minor 对齐

• 现象：tauri build直接拒绝，一致性检查报 tauri 2.9.5 vs@tauri-apps/api2.12.1 不匹配。
• 修法：cargo update --precise逐个对齐（tauri 2.12.1 / dialog 2.8.1 / notification 2.5.1 / opener 2.7.0）。
• 延伸：CI 的 tauri-action 面对同样的检查——本地构建过了才敢打 tag，否则 release 可能根本没产出。

🔴 坑 2：src-tauri 双 bin 必须声明default-run

• 现象：项目有app和cuiliantu-cli两个 bin，tauri build报failed to find main binary。
• 修法：Cargo.toml的[package]里加default-run = "cuiliantu"。报错信息完全不提示原因，属于「知道就一秒，不知道卡半天」。

🟠 坑 3：f64::clamp对 NaN 是空操作

• 现象：所有比较对 NaN 均为 false，clamp 直通，NaN 进入管线污染后续所有乘法，最终产物全错但无任何报错。
• 修法：任何浮点入参先is_finite()再 clamp。注意本项目blur/rotate_degrees是 f32、resize_percent是 f64，两处都要防。

🟠 坑 4：.then_some的参数先求值，长度校验写在里面无效

// ❌ 错误：数组索引在 then_some 判断前已求值，越界 panic 照旧v.len().eq(&4).then_some([v[0],v[1],v[2],v[3]])// ✅ 正确：先显式判长度ifv.len()!=4{returnNone;}Some([v[0],v[1],v[2],v[3]])

🟠 坑 5：裸#[serde(default)]的默认值与领域模型不一致

• 现象：Payload 新增字段用裸#[serde(default)]，得到 0 / false / 首个枚举变体，与ProcessingOptions::default()的语义默认值不一致——用户没动过的选项行为悄悄变了。
• 修法：写#[serde(default = "fn")]，指向default()的对应字段。

🟠 坑 6：.tsx组件测试必须solid({ hot: mode !== "test" })

• 现象：vitest 下不关 HMR，file:///@solid-refresh解析失败，崩溃的是整个测试套件而不是单个用例。
• 修法：vite.config.ts中按 mode 关闭 hot。

🟠 坑 7：fireEvent在 pnpm 严格布局下不可用

• 现象：@solidjs/testing-library不再导出fireEvent，@testing-library/dom被 pnpm 隔离拿不到。
• 修法：用原生.click()——事件会冒泡到 Solid 委托根，行为等价。

🟠 坑 8：setPointerCapture在 pointerdown 就调，click 永远点不进去

• 现象：能拖能缩，但按钮「永远点不动」，零报错。
• 根因：down 时就捕获，兼容性 mouseup 被重定向到捕获元素，click 的 target 从子元素变成容器。
• 修法：拖动超过阈值（如 6px）才调用setPointerCapture。
• 教训：交互组件必须真机拖一遍，冒烟脚本不许省。

🟡 坑 9：WindowsPath::canonicalize返回\\?\前缀

与未规范化路径做相等/前缀比较前必须 strip（UNC 盘符则是\\?\UNC\），否则白名单校验会误拒合法路径。

🟡 坑 10：pnpm update会重写 package.json 的 semver 下界

只提交 lockfile 不提交 package.json，会导致「读工作树的发布脚本」与「git 索引」不一致，校验 mismatch。纪律：update 之后 package.json 和 lockfile 一起提交。

🟡 坑 11：CI 的 audit 门禁与 tilde 锁定联动

ci.yml有pnpm audit --audit-level=high。修复传递依赖漏洞（如 seroval）时，直接 update 无效——solid-js 用 tilde 锁定了 seroval 的 minor，正确修法是升级直接依赖（solid-js）。另注意 npmmirror 无 audit endpoint，本地验证只能查 lock 版本号。

🟡 坑 12：本地曾是 shallow clone，远端拒推

shallow update not allowed。用git fetch --unshallow通过镜像修复。教训：clone 上游仓库时直接用加速镜像补全历史，不要留下截断的浅克隆。

七、方法论沉淀：AI 辅助开发的三条纪律

比坑本身更值钱的，是坑背后的共性。以下三条适用于任何 AI 编程智能体（包括码道 CodeArts）：

纪律一：闸门必须反向测

「测试全绿」只证明不误报，证明不了能拦住。每个新增校验闸门都要：故意注入违规 → 必须报出 → 改回 → 必须恢复绿灯。本项目三个新闸门（删除键值/置空/丢占位符、越界/NaN/自证式守卫）都是逐个注入违规验证的。

纪律二：断言型判据查不出「画反了」，必须配独立实现比对

更隐蔽的一层：产物整体颠倒（黑白反转），但 6 条结构判据（半径/端点/层序/鱼眼/镜像）全部照样 PASS——因为「哪一侧填白」根本不在检查维度里。反向测在这里也失效：注入故障能测出「恒真」，测不出「维度缺失」。

解法是判据双轨制：

纪律三：把缺陷按「发现难度」分层管理

不是按严重度，是按能不能等它报错分层：

• A 层（静默失效）：上下文遗漏、闸门漏报、类型漂移、交互语义错——全靠「主动反向测 + 真机手动验证」；
• B 层（有症状难寻根因）：边界异常、性能陷阱——靠真机复现 + 查证据链；
• C 层（显式报错）：语法错、类型不匹配——最安全，一跑就暴露。

AI 智能体生成的代码，恰恰在 A 层的信任成本最高：它写得快、测得绿，但「测试没覆盖的维度」人也很难想到。这就是为什么本文坚持把「真机验收」和「反向测」设为强制流程——AI 负责产能，人负责证伪。

八、给零基础开发者的入门建议

如果你刚开始用码道 CodeArts 做项目，结合本文踩过的坑给三条建议：

1. 让 AI 生成单测，但自己写断言。智能体擅长枚举边界用例骨架，但「什么算正确」必须由你定义，否则它只是在验证自己。
2. 每完成一个功能，真机跑一遍。本文坑 8（点击永远无效但零报错）是纯测试流程永远发现不了的。
3. 建立你自己的门禁脚本。一条命令跑完 lint / 类型检查 / 测试 / 构建，每次收尾必须全绿。门禁脚本本身就是你项目的「宪法」。

九、总结与展望

本次活动周期的实践，CuiLianTu 完成了从功能迭代到 v0.2.1 正式发布的全过程，沉淀了 12 个有复现价值的坑与 3 条方法论纪律。项目已建立基线提交（97 文件，+14483/−5549），品牌图标、中英文 README、双平台 release 通道全部就位。

作品体验入口：AtomGit Releases 可直接下载 macOS（Apple Silicon / Intel）与 Windows（安装版 / MSI / 便携版）安装包——本文第二章的功能描述均可下载逐项验证。

下一步计划：

• v0.2.2 发布：合并后续快照修复，重打 tag 走 CI；
• 修补发布链路签名缺口（macOS 公证需要 Apple 开发者账号）；
• 尝试用码道的 Skills 机制把本文的三条纪律固化成项目级自定义规则，让「反向测」成为智能体的默认动作而不是人工要求。

AI 辅助开发的本质不是「AI 写代码、人喝茶」，而是把人的判断力用在架构契约、验收标准与证伪环节。愿这份复盘能帮到正在用码道 CodeArts 搭建自己项目的你。

项目代码 MIT 开源，欢迎到 AtomGit 仓库 Star 与 Issue 交流。