一张报名照卡在 50KB四条路全堵死——我用华为云码道 CodeArts 造了 CuiLianTu一键开通华为云码道 CodeArts 代码智能体https://developer.huaweicloud.com/codeartsco.html?sourcedmzntgwatomgit1sourceaddmzntgwatomgithd参与方向全场景项目实战兼及零基础入门项目仓库atomgit.com/CYXue/cuiliantu github.com/CYXue/cuiliantu当前版本v0.2.1三平台 CI 构建7 个发行资产技术栈Rust Tauri 2 SolidJS TypeScript作者CYXue摘要本文记录我使用华为云码道 CodeArts 代码智能体完成桌面端批量图片处理工具CuiLianTu淬炼图从架构设计、功能开发、工程化加固到三平台发布的全流程实践。这个项目的起点是一张怎么都传不上去的报名证件照——一个真实的、带着截止时间的痛点。文章不做产品宣传重点沉淀四样东西一套可复用的 AI 辅助开发工作流云仓库工作区 代码检查 单测生成 门禁收尾一份真实的踩坑清单——12 个坑全部有复现路径与修法其中 3 个坑 3、5、8属于「零报错、结果错」的静默失效类AI 与人都极难察觉核心功能「目标体积」的源码级拆解——一个二分搜索如何同时做到「恰好卡线」与「预览即所见」三条从踩坑中提炼的方法论纪律适用于任何 AI 编程智能体。一、项目背景一份报名表催生的工具CuiLianTu 的起点不是宏大的架构规划而是一次网上报名卡在照片上传环节。报名系统对上传材料有一串硬性要求系统要求原文规定格式所有材料仅接受JPEG/JPG证件照196×250 像素二寸免冠照≤50 KB图像清晰可辨其余材料单张≤300 KB身份证正反面、全身生活照、学历学位材料均为必传数量每人最多 10 张同类材料须合并成 1 张如身份证正面反面合一张时限简历须在20 分钟内填写完成并保存否则登录失效、信息丢失而现实是手机拍一张 3–8 MB格式还可能是 HEIC/PNG扫描件更大报名系统既不帮压也不帮转超了就拒收。临交材料那几天我把能想到的路全摸了一遍现成方案实际体验结论WPS能处理图片但要收费❌ 付费墙Adobe Photoshop功能全能可为了压几张照片装一个十几 GB 的大软件杀鸡用牛刀❌ 太重应用商店 / 网站小工具广告满天飞导出结果还有问题而且按次收费❌ 广告 不可靠 重复付费云端在线工具基本都聚焦文本/文档压缩图片方向没找到趁手的就算找到也得把身份证、学历证书传给陌生服务器❌ 隐私红线四条路全堵死。那就自己写一个——需求清单都是现成的就是那张报名须知。于是「淬炼图」诞生了——报名表里每一条要求都对应一个功能报名表要求CuiLianTu 对应能力≤50 KB / ≤300 KB目标文件体积二分自动调优 JPEG 质量直到满足 KB 预算仅 JPEG/JPG六种格式互转JPEG / PNG / GIF / BMP / TIFF / WebP196×250 证件照内置证件照预设二寸、一寸、小二寸、社保照等材料多达 10 张批量拖放一次处理数百张20 分钟限时全程本地、无网络往返批量压完以秒计二、产品实证从一张图到核心功能功能列表容易自夸直接上实测。2.1 实测一张图转格式本身就会改变体积以一张 53.4 KB 的 PNG 截图254×215为例质量 100%、不改尺寸、不做其他处理仅切换输出格式输出格式结果体积变化PNG重编码57.5 KB7.5%变大JPEG质量 100%30.2 KB−43.5%同一个文件、同一个质量参数仅仅换格式结果差了将近一倍。两个结论报名系统「仅收 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 功能全景与几个别处少有的设计在此之上工具逐步长成了完整的批量处理平台。主打隐私优先——不上传、无账号、无网络依赖处理身份证、学历证书这类材料这是底线而非卖点功能说明批量处理一次处理数百张图片拖放文件或文件夹目标体积二分自动调优 JPEG 质量直到满足 KB 预算如「上传表单要求 ≤50 KB」预设模板证件照六尺寸、web、社交、无损等支持自定义模板排序水印与实时预览文字/图片水印滑块实时预览效果多语言English / 简体中文 / 日本語跨平台macOSApple Silicon Intel与 Windows含便携版在通用功能之外有几个设计是摸排过的现成工具里基本没见过的空手预览— 不加载任何文件预览和参数调节照样可用。先把质量、尺寸、水印调到满意再拖图进来直接导出对「同一批材料用同一套参数」的报名场景参数只调一次。目标体积是「先给预算再倒着压」— 不是压完看多小而是先给定 KB 上限≤50KB、≤300KB用二分法反向搜索 JPEG 质量参数一张和一百张每张都恰好卡线达标。拖框裁剪 分屏对比— 196×250 这类尺寸要求直接在预览图上框选构图「原图 / 效果」分屏同步查看不用导出后开了又改。批量统计带中位数— 处理完给出总体 / 平均 /中位数三个压缩率。平均数会被个别异常图片拉偏中位数一对比就能发现「大多数压得正常、个别图片异常膨胀」批量场景里非常有用。大图防线— 解码前先探测图像声明的像素数超过 256 MP 直接拒绝、批次内存按 4 GiB 预算钳制——几百张大图一起拖进来程序不会静默崩溃而是明确报错第五章阶段三详述。便携与开源— Windows 便携版解压即用、免安装免管理员权限MIT 开源没有付费墙、没有按次收费、没有广告位。2.3 特色功能拆解「目标体积」是怎么做到恰好卡线的以「证件照 ≤50KB」为例。JPEG 的体积与质量参数之间没有解析公式——同一个质量值对不同内容的输出大小可以差数倍想「算出」正确参数是不可能的唯一可靠的办法是二分搜索。核心实现Rustsrc-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(Vecu8,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:u830;constMAX_SEARCH_QUALITY:u895;letlimitlimitasusize;let(mutlo,muthi)(MIN_SEARCH_QUALITY,MAX_SEARCH_QUALITY);letmutbest:Option(Vecu8,u8)None;whilelohi{letmid(lohi)/2;letencodedSelf::encode_jpeg(img,mid)?;ifencoded.len()limit{bestSome((encoded,mid));lomid1;// 达标了继续往高质量半区找}else{himid-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.letbytesSelf::encode_jpeg(img,MIN_SEARCH_QUALITY)?;Ok((bytes,MIN_SEARCH_QUALITY,false))}}}三十行里藏了三个值得说的实现决策搜索边界是 30–95不是 1–100低于 30证件照的压缩瑕疵肉眼可见压了等于废高于 95多花的字节人眼看不出区别。这是产品判断写进算法边界——搜索空间先砍掉四分之一。达标后继续向高质量半区搜lo mid 1保证输出是满足预算的最高质量而不是随便一个达标的。报名照要在 50KB 里尽量清晰差的那个质量档位肉眼真能看出来。兜底走降级不走报错连 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 RustRust 做图像处理批量场景下内存与速度是生命线imagecrate 生态成熟且可以对解码像素数做硬上限第五章阶段三的安全守卫会讲。Tauri 2 做壳相比 Electron安装包从上百 MB 降到 11–15 MB系统 WebView 渲染前端。SolidJS 做界面细粒度响应式没有虚拟 DOM diff滑块拖动实时预览不卡。代价三套语言心智Rust / TS / CSS IPC 边界序列化这正是 AI 智能体能发挥最大杠杆的地方——跨语言的契约一致性恰恰是人最容易漏、机器最擅长查的。四、码道 CodeArts 在本项目中的角色本项目代码托管在 AtomGitCYXue/cuiliantu与码道 CodeArts 天然打通。整个开发过程中码道承担四类工作4.1 云仓库工作区在码道中选中 AtomGit 仓库后智能体以仓库为工作区读取项目结构、定位文件、写入修改、Git 追踪变更。对一个 Rust TS 混合仓库来说最有价值的是代码库索引Codebase——模型不必逐个读文件就能定位符号与调用关系跨 crate 的引用如src-tauri领域模型 ↔ 前端 store修改时不容易漏下游。4.2 跨语言契约检查本项目最核心的契约是IPC 边界的 payload 结构后端领域模型按组嵌套output / resize / transform / crop / adjust五组 顶层watermarkIPC 边界保留扁平的ProcessingOptionsPayloadserde(default)经From转换前端保持扁平的store.options.xxx。这意味着新增一个后端字段要同步三处组内字段、Payload 字段、From转换。这类「改一处必须动三处」的机械工作交给智能体做全仓扫描核对比人肉 grep 可靠得多。4.3 单测生成与反向验证图像处理管线有大量数值边界NaN、负零、越界、除零码道的单测生成能力适合产出「边界用例骨架」但生成不等于验证——第七章的纪律一会讲为什么每个闸门必须手工反向测。4.4 端云协同的代码检查本地收尾跑七阶段门禁见第五章阶段三云端代码检查作为第二道网两者关注点互补本地门禁管「能不能合并」云端检查管「规范与潜在缺陷」。五、实战复盘四个阶段阶段一架构设计——双层模型定调开工前先定死架构契约这是 AI 辅助开发中最重要的一次人工决策┌─ 前端 SolidJS ─────────────────────────┐ │ store.options.quality扁平 │ └──────────────┬─────────────────────────┘ │ IPCTauri invoke ┌──────────────▼─────────────────────────┐ │ ProcessingOptionsPayload扁平serde │ ← 边界层向前兼容 ├────────────────────────────────────────┤ │ ProcessingOptions按组嵌套 │ ← 领域层output/resize/ │ │ transform/crop/adjust └────────────────────────────────────────┘扁平 payload 做 IPC 边界的好处前端零改动迁移、新增字段不破坏旧调用方serde(default)向前兼容。这个决策让后续十几次功能迭代没有再动过边界层。阶段二功能开发——迭代节奏每个功能循环需求描述 → 智能体产出改动 单测 → 本地跑测试 → 人工验收交互 → 提交。关键经验是把「人工验收交互」设为强制步骤第六章的坑 8点击永远无效但零报错就发生在「测试全绿」的盲区里纯靠测试报告根本发现不了。阶段三工程化加固——安全与稳定性解压炸弹守卫ImageProcessor::probe_dimensions在 decode 前探测图像声明尺寸超过MAX_DECODED_PIXELS256 MP直接拒绝批次线程数按最大图内存估算w·h·4×2再被BATCH_MEMORY_BUDGET_BYTES4 GiB钳制。render 与 decode 两条路径都要探漏一条就是漏洞。路径白名单defense-in-depthregister_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 ×2macOS 首次构建即通过。发布链路有两个值得记的细节tauri-action 产出的是 draft releasetag 是untagged-xxx临时名需要手动 PATCHdraft:falsetag_name才能关联正式 tagportable.zip 不在 CI 产物里要走 API 用upload_url手工补传。六、踩坑实录12 个附复现路径与修法以下全部为实战中真实踩到。按危害分级 阻断构建/发布 静默失效零报错、结果错 高频误踩。 坑 1tauri crate 与 npm 包版本必须 minor 对齐现象tauri build直接拒绝一致性检查报 tauri 2.9.5 vstauri-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 可能根本没产出。 坑 2src-tauri 双 bin 必须声明default-run现象项目有app和cuiliantu-cli两个 bintauri build报failed to find main binary。修法Cargo.toml的[package]里加default-run cuiliantu。报错信息完全不提示原因属于「知道就一秒不知道卡半天」。 坑 3f64::clamp对 NaN 是空操作现象所有比较对 NaN 均为 falseclamp 直通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 下不关 HMRfile:///solid-refresh解析失败崩溃的是整个测试套件而不是单个用例。修法vite.config.ts中按 mode 关闭 hot。 坑 7fireEvent在 pnpm 严格布局下不可用现象solidjs/testing-library不再导出fireEventtesting-library/dom被 pnpm 隔离拿不到。修法用原生.click()——事件会冒泡到 Solid 委托根行为等价。 坑 8setPointerCapture在 pointerdown 就调click 永远点不进去现象能拖能缩但按钮「永远点不动」零报错。根因down 时就捕获兼容性 mouseup 被重定向到捕获元素click 的 target 从子元素变成容器。修法拖动超过阈值如 6px才调用setPointerCapture。教训交互组件必须真机拖一遍冒烟脚本不许省。 坑 9WindowsPath::canonicalize返回\\?\前缀与未规范化路径做相等/前缀比较前必须 stripUNC 盘符则是\\?\UNC\否则白名单校验会误拒合法路径。 坑 10pnpm update会重写 package.json 的 semver 下界只提交 lockfile 不提交 package.json会导致「读工作树的发布脚本」与「git 索引」不一致校验 mismatch。纪律update 之后 package.json 和 lockfile 一起提交。 坑 11CI 的 audit 门禁与 tilde 锁定联动ci.yml有pnpm audit --audit-levelhigh。修复传递依赖漏洞如 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独立实现比对整体逻辑画反用另一套实现重算结果做交叉验证纪律三把缺陷按「发现难度」分层管理不是按严重度是按能不能等它报错分层A 层静默失效上下文遗漏、闸门漏报、类型漂移、交互语义错——全靠「主动反向测 真机手动验证」B 层有症状难寻根因边界异常、性能陷阱——靠真机复现 查证据链C 层显式报错语法错、类型不匹配——最安全一跑就暴露。AI 智能体生成的代码恰恰在 A 层的信任成本最高它写得快、测得绿但「测试没覆盖的维度」人也很难想到。这就是为什么本文坚持把「真机验收」和「反向测」设为强制流程——AI 负责产能人负责证伪。八、给零基础开发者的入门建议如果你刚开始用码道 CodeArts 做项目结合本文踩过的坑给三条建议让 AI 生成单测但自己写断言。智能体擅长枚举边界用例骨架但「什么算正确」必须由你定义否则它只是在验证自己。每完成一个功能真机跑一遍。本文坑 8点击永远无效但零报错是纯测试流程永远发现不了的。建立你自己的门禁脚本。一条命令跑完 lint / 类型检查 / 测试 / 构建每次收尾必须全绿。门禁脚本本身就是你项目的「宪法」。九、总结与展望本次活动周期的实践CuiLianTu 完成了从功能迭代到 v0.2.1 正式发布的全过程沉淀了 12 个有复现价值的坑与 3 条方法论纪律。项目已建立基线提交97 文件14483/−5549品牌图标、中英文 README、双平台 release 通道全部就位。作品体验入口AtomGit Releases 可直接下载 macOSApple Silicon / Intel与 Windows安装版 / MSI / 便携版安装包——本文第二章的功能描述均可下载逐项验证。下一步计划v0.2.2 发布合并后续快照修复重打 tag 走 CI修补发布链路签名缺口macOS 公证需要 Apple 开发者账号尝试用码道的 Skills 机制把本文的三条纪律固化成项目级自定义规则让「反向测」成为智能体的默认动作而不是人工要求。AI 辅助开发的本质不是「AI 写代码、人喝茶」而是把人的判断力用在架构契约、验收标准与证伪环节。愿这份复盘能帮到正在用码道 CodeArts 搭建自己项目的你。项目代码 MIT 开源欢迎到 AtomGit 仓库 Star 与 Issue 交流。