万亿模型接入智能体：手搓图片拼接工具

一、教程目标：这篇文章要带你完成什么

近期，一个万亿参数级、采用混合线性注意力架构的开源”思考模型”（下文简称”该模型”）宣布开源。公开信息显示，它在国际顶级数学竞赛级别的题目上取得了金牌水平的成绩，同时在长文本生成、数学推理、智能体长程任务执行三方面相比上一代有阶跃式提升，并全面兼容当前主流的智能体编程框架与命令行式编码助手。

但”模型很强”和”我能用它干活”之间，隔着一条工程化的鸿沟。本教程不讨论模型架构本身，而是把重点放在如何把这类模型接入智能体框架，完成一次端到端的真实交付。

学完并动手实践后，你将获得三项能力：

1. 交付一个可运行的产物：一个本地桌面小工具，支持多张图片的水平/垂直拼接、留白间距控制、等比缩放对齐、结果导出。功能范围刻意收敛，属于典型的”丐版专业图像处理软件”。
2. 掌握一套可复用的协作方法：如何写一份让智能体”一次读懂、分步执行”的规格说明；如何划分”自动执行”与”必须人工确认”的边界。
3. 建立合理的能力预期：哪些环节模型可以基本独立完成，哪些环节（依赖选择、破坏性操作、权限授予、性能调优）必须人来把关。

适用读者：具备基础前端与脚本语言认知的开发者；希望用小模型/大模型快速产出内部工具的独立开发者与效率工具爱好者；需要评估”AI 辅助编码”在团队中如何落地的技术负责人。

二、适用场景与能力边界

这个案例的价值不在于那个图片拼接工具本身——用任何图像处理库写它都不难。它的价值在于验证了一条链路：自然语言需求 → 规格拆解 → 代码生成 → 运行验证 → 迭代修正，且这条链路可以在很少人工干预下走完。

类似的场景包括：

• 内部小工具：格式转换、批量重命名、日志切分、报表合并；
• 技术验证原型（PoC）：在决定投入前，快速验证某个交互或算法是否可行；
• 遗留代码理解：阅读没有文档的旧代码库，补齐注释或做跨语言移植（例如把某种编译型语言的旧代码库迁移为带类型的脚本代码）；
• 前端页面组件化：把零散的页面代码整理为可复用、开箱即用的组件或本地应用。

必须明确的能力边界，否则很容易踩坑：

• 模型对算法正确性（几何计算、坐标换算、边界判断）表现较好，因为它可以逐步推导；
• 模型对环境相关的知识（某个依赖的最新版本、某个平台的最新安装方式）不一定准确，这部分知识会过时，需要你核对官方文档；
• 模型不会主动替你承担风险：删除文件、安装全局依赖、开放网络端口这类操作，它会征求确认，你不应该无脑通过。

三、前置准备

3.1 基础环境

项目	要求	说明
模型访问方式	本地部署推理服务，或云上托管的模型推理接口	万亿参数模型无法在消费级单机运行，通常采用云端推理服务或 API 调用
智能体运行环境	一个兼容主流智能体协议的命令行编码助手	提供”读写文件、执行命令、查看差异”三类基础能力即可
运行时	脚本运行时（支持包管理与模块化的通用运行环境）	用于执行构建、启动与测试命令
图形环境	具备图形界面的桌面操作系统	桌面应用必须能真实打开窗口验证
显存/算力	若本地推理，需多卡集群级资源	否则走云端推理服务更经济

关于云端接入，通用做法是：在云服务控制台开通对应的大模型推理服务，获取访问凭据（Access Key / Secret），配置到智能体框架的环境变量或配置文件中。凭据应通过环境变量或密钥管理服务注入，不要硬编码进代码仓库。若素材图片较多，可配合对象存储存放输入与输出文件，用内容分发加速素材分发，用日志服务与监控告警观察调用量、延迟与失败率。

3.2 权限准备（最容易被忽略的一步）

智能体框架通常提供分级权限模式，建议这样设置：

• 只读模式（plan / read-only）：仅允许读取文件与输出方案，用于需求分析和方案设计阶段；
• 工作区写入模式（auto-edit）：允许在项目目录内创建、修改文件，用于代码生成阶段；
• 命令执行模式（yolo / full-auto）：允许执行任意命令，仅在明确的本地沙箱中使用，且需人工确认高风险命令。

核心原则：让模型跑得远，但把”不可逆操作”的闸门留在人手里。

3.3 素材准备

准备 3~5 张尺寸不一的图片（建议一张竖图、一张横图、一张极小的图标），用于后续验证缩放与对齐逻辑。刻意准备尺寸差异大的素材，是发现算法缺陷最有效的手段。

四、总体方案设计

在让模型写第一行代码之前，先把方案定下来，这决定了后面十分钟是顺畅还是反复返工。

4.1 技术选型（中立方案）

• 界面层：使用标准 Web 技术（HTML + CSS + 原生脚本）构建界面；
• 画布层：使用浏览器/系统 WebView 提供的 canvas 绘图 API 完成合成；
• 桌面封装：使用通用的跨平台桌面容器框架，把 Web 界面包装成可双击运行的本地应用；
• 导出层：调用画布的原生导出能力，输出 PNG 或 JPEG。

之所以选这条路线：Web 绘图 API 的文档最完整、示例最多，模型对它的掌握程度最高，生成质量也最稳定。给模型选它熟悉的成熟技术栈，能显著降低试错成本——这是提升 AI 辅助编码成功率最实用的一条经验。

4.2 架构分层

┌─────────────────────────────────────────┐
│  界面层：文件选择、方向切换、间距输入、导出按钮  │
├─────────────────────────────────────────┤
│  状态层：图片列表、排列方向、间距、对齐方式      │
├─────────────────────────────────────────┤
│  渲染层：布局计算 → 画布尺寸计算 → 逐张绘制     │
├─────────────────────────────────────────┤
│  导出层：画布序列化 → 写入本地文件            │
└─────────────────────────────────────────┘

分层的意义在于：布局计算是纯函数，可以单独测试；绘制是副作用，集中在渲染层。当结果不对时，你能立刻判断是”算错了”还是”画错了”。

4.3 拼接算法核心逻辑（伪代码）

输入: images[]  // 已解码的位图列表
      direction // "horizontal" | "vertical"
      gap       // 相邻图片间距（像素）
      targetW   // 归一化后的统一宽度（水平拼接时）
步骤:
1. 若 images 为空 → 报错返回
2. 计算归一化尺寸:
   若 direction == horizontal:
       for each img: h_i = img.height * targetW / img.width
                     w_i = targetW
   否则:
       for each img: w_i = img.width * targetH / img.height
                     h_i = targetH
3. 计算画布总尺寸:
   horizontal: totalW = Σw_i + gap * (n - 1);  totalH = max(h_i)
   vertical:   totalW = max(w_i);              totalH = Σh_i + gap * (n - 1)
4. 创建 totalW × totalH 画布，填充背景色
5. 沿主轴累加偏移 cursor = 0:
   for i, img in images:
       交叉轴偏移 cross = (主轴方向上的画布尺寸 - 该图对应边) / 2   // 居中对齐
       绘制 img 到 (x, y)，其中 x/y 由 direction 与 cursor、cross 决定
       cursor += 该图主轴边 + gap
6. 返回画布

这段伪代码里有两个最容易被模型写错的点，你在审查时重点看这两处：

• 第 5 步的交叉轴居中：(画布该轴尺寸 - 图片该轴尺寸) / 2，很多实现会直接写 0，导致图片全部顶部对齐或左侧对齐；
• 第 3 步的间距项：间距数量是 n - 1 而不是 n，首尾不留间距。

五、实施步骤

步骤 1：写规格说明（做什么、为什么、注意什么）

做什么：在项目根目录创建一个 SPEC.md，用自然语言把需求、功能清单、验收标准、技术约束写清楚。

为什么：模型的长上下文能力意味着它能一次读完一份完整规格，但前提是你把规格写完整。含糊的一句话需求（”做个图片拼接工具”）会得到含糊的实现；一份带验收标准的规格能显著减少来回。规格质量决定生成质量。

注意：验收标准必须是可观测的，不要写”体验流畅”，要写”三张不同尺寸的图水平拼接后，输出图宽度等于三张图缩放后宽度之和加两个间距”。

规格模板（通用示例）：

# 目标
一个本地桌面应用：把多张图片拼接为一张长图。
# 功能清单（MVP）
1. 支持一次选择多张本地图片
2. 支持水平 / 垂直两种拼接方向切换
3. 支持设置相邻图片间距（0~100 px）
4. 实时预览拼接结果
5. 导出为 PNG，文件保存到用户指定路径
# 非目标（本期不做）
图层、滤镜、文字、蒙版、撤销历史
# 技术约束
- 界面使用原生 HTML/CSS/JS，不引入 UI 框架
- 合成使用 canvas 2D 上下文
- 桌面封装使用通用跨平台容器方案
- 所有处理在本地完成，不上传任何图片
# 验收标准
- 3 张 1920x1080 / 800x600 / 200x200 图片水平拼接：
  输出宽 = 3*W_norm + 2*gap，高 = max(缩放后高度)
- 垂直拼接时输出高为各图缩放后高度之和 + (n-1)*gap
- 大图（>4000px）导出时内存占用可控，不崩溃
- 空列表点击导出给出明确提示，不白屏

步骤 2：初始化项目骨架

做什么：让智能体创建目录结构、初始化包管理、安装桌面容器与构建工具。

为什么：骨架决定后续所有文件的位置，先定好可以避免后期大规模移动文件。

注意：这一步会联网下载依赖，属于需要人工确认的操作。建议：

• 先让模型输出”将要执行哪些命令、安装哪些依赖及各自作用”的清单，你确认后再放行；
• 锁定依赖版本（生成锁文件并提交），避免不同机器构建结果不一致；
• 不要安装来源不明的包，遇到不认识的包名，让模型说明用途或改为不引入该依赖。

推荐骨架：

image-stitcher/
├── SPEC.md
├── package.json
├── src/
│   ├── index.html
│   ├── renderer.js      // 画布合成
│   ├── layout.js        // 纯函数：布局与尺寸计算
│   ├── ui.js            // 界面交互与状态管理
│   └── main.js          // 应用入口
└── test/
    └── layout.test.js

注意 layout.js 被独立拆出：纯计算逻辑必须可单元测试，这是后面能快速定位问题的关键。

步骤 3：实现布局计算并先写测试

做什么：先让模型实现 layout.js，同时为它写单元测试；再实现绘制。

为什么：这是”测试先行”在 AI 辅助编码中最有价值的应用。布局计算是纯函数，输入输出明确，模型生成的正确率最高，而它一旦正确，绘制层就只是”照着坐标画像素”的机械工作。先把确定性最强、最容易验证的部分锁死，再处理不确定性高的部分。

示例测试（通用断言写法）：

// test/layout.test.js
const assert = require('assert');
const { computeLayout } = require('../src/layout');
// 场景：三张图统一宽度 100，间距 10，水平拼接
const items = [
  { w: 1920, h: 1080 },
  { w: 800,  h: 600  },
  { w: 200,  h: 200  },
];
const r = computeLayout(items, { direction: 'horizontal', gap: 10, target: 100 });
assert.strictEqual(r.canvas.width, 100 * 3 + 10 * 2); // 320
assert.strictEqual(r.canvas.height, Math.round(1080 * 100 / 1920)); // 56
assert.deepStrictEqual(r.slots.map(s => s.x), [0, 110, 220]);
// 交叉轴居中：第二张图缩放后高度 75，画布高 56 → 出现负偏移，
// 说明"按宽度统一缩放"会让矮宽图溢出，需要改为"等比缩放到适配"策略

最后一条断言故意暴露了一个设计缺陷：当各图宽高比差异过大时，统一按宽度缩放会导致部分图片高度超出画布。这正是”AI 写出来的代码看起来对、跑起来不对”的典型情况，必须靠测试而不是靠肉眼审查发现。修正方向有两种，让模型给出对比后你再选：

• 方案 A：统一宽度，画布高度取最大值，超出的图片按高度裁切或等比缩小；
• 方案 B：统一”短边”，长边自适应，各图完整显示但视觉宽度不一致。

MVP 建议选 A（长图拼接的常见预期），并在界面上提供一个”适配方式”开关。

步骤 4：实现画布合成与实时预览

做什么：读取文件为位图，调用布局结果绘制到预览画布。

为什么：预览是这类工具的体验核心——用户调间距、换方向时需要立刻看到结果，否则只能靠反复导出试错。

关键实现要点（让模型必须遵守）：

// renderer.js（通用示例）
async function render(canvas, images, options) {
  const layout = computeLayout(images, options);
  canvas.width  = layout.canvas.width;
  canvas.height = layout.canvas.height;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = options.background || '#ffffff';
  ctx.fillRect(0, 0, canvas.width, layout.canvas.height);
  for (const slot of layout.slots) {
    ctx.drawImage(slot.bitmap, slot.x, slot.y, slot.w, slot.h);
  }
}

注意事项：

• 位图对象必须显式释放（调用其 close() 方法），否则连续导入几十张大图会迅速耗尽内存；
• 预览画布不要直接用原图尺寸，应按容器宽度等比缩放显示，避免超大画布拖慢界面；
• 图片解码是异步的，UI 必须处理”解码中”状态，不能让用户重复点击导入。

步骤 5：接入导出能力

做什么：把合成结果导出为图片文件写入本地。

为什么：预览用画布、导出需要落盘，两者路径不同。浏览器环境用 canvas.toBlob 触发下载；桌面容器环境通常通过主进程写文件对话框 + 文件写入 API 完成。

注意：

• 导出前必须让用户选择保存路径，不要在后台静默覆盖同名文件；
• JPEG 不支持透明通道，若背景色为空且导出 JPEG，需先填充白底，否则透明区域会变黑；
• 超大画布（例如超过 16000px 单边）可能超出浏览器画布上限，需要在导出前检查并给出明确提示，而不是静默失败。

步骤 6：长程执行中的权限确认与差异审查

做什么：在模型执行多文件写入、安装依赖、启动应用时，逐个确认权限请求，并在每完成一个阶段后审查代码差异。

为什么：长程执行的价值在于模型能连续完成十几个步骤，但风险也在于”错误会连续传播”。分段确认 + 阶段性质检能把返工成本压到最低。

建议的确认节奏：

阶段	权限策略	你要看什么
方案设计	只读	功能清单是否覆盖规格、有无擅自扩大范围
骨架初始化	需确认	依赖清单是否合理、有无可疑包
代码生成	工作区写入	每批文件生成后看 diff，重点看布局算法与边界处理
运行验证	需确认	启动命令、端口占用、是否监听外网地址
清理收尾	需确认	是否删除非预期文件

特别提醒：如果模型尝试修改 .gitignore、CI 配置、系统级配置或删除目录，停下来先问原因。这类操作与当前任务无关的概率很高。

六、结果验证：怎么判断真的做成了

不要以”程序能打开”作为完成标准。用下面四层验证：

1. 单元层：运行布局计算测试，全部通过。这是最快的反馈，秒级完成。

2. 功能层：按验收标准逐项走一遍，重点测这五组：

• 单张图片（间距项应为 0，不能出现负数尺寸）；
• 两张同尺寸图片（最容易，作为基线）；
• 三张差异极大的图片（触发缩放与居中逻辑）；
• 20 张以上批量（触发性能与内存问题）；
• 空列表 / 单张异常损坏文件（触发错误处理）。

3. 精度层：导出后用任意图像查看器读取输出的像素尺寸，与预期公式对比：

预期宽度 = Σ(统一边) + gap × (n - 1)
预期高度 = max(缩放后各图对应边)     // 水平方向

尺寸差 1 像素通常来自四舍五入取整，可接受；差一个 gap 就是间距项算错；差一整张图就是绘制循环有遗漏。

4. 性能层：用系统监视器观察导入 20 张 4000×3000 图片时的内存峰值与响应时间。若内存持续上涨不回落，几乎可以肯定是位图未释放。

七、常见问题与排查

现象	常见原因	排查思路
拼接结果图片错位/重叠	主轴偏移累加时误用了缩放前宽度	检查循环中 cursor 累加的是 slot.w 还是原图 width
所有图片顶部对齐，没居中	交叉轴偏移写成了 0	检查 (canvasSize - imgSize) / 2 是否实现
导出图比预期宽/高一个间距	间距乘了 n 而非 n-1	单张图导出，尺寸应等于原图缩放后尺寸
大图导出后全黑	透明背景 + JPEG 导出	导出前强制填充背景色
导入多张后界面卡死	同步解码 + 未释放位图	改为异步逐张解码，及时释放
智能体反复修改同一文件	需求描述存在歧义，模型在两种解释间摇摆	回到 SPEC.md 补充明确规则，而不是让它继续试
生成的代码依赖了不存在的包	模型对生态最新状态认知滞后	核对官方文档，替换为成熟替代或直接自行实现
权限提示刷屏，流程中断	权限模式设置过严	按阶段切换权限模式，而非全程最严或全程放开

其中”反复修改同一文件”最值得展开：这几乎总是规格歧义的信号，而不是模型能力问题。处理方式是暂停执行、把冲突点在规格里写死（例如明确规定”统一按宽度缩放，超出高度的部分等比缩小至适配”），然后重新开始。带着模糊需求反复对话，只会让上下文里堆满相互矛盾的方案。

八、优化建议

性能

• 预览用降采样后的位图，导出时才用原始分辨率，可让大图操作从”卡住数秒”降到”即时响应”；
• 布局计算加入缓存：只有图片列表、方向、间距变化时重算，单纯平移画布不重算；
• 超大批量改为分批解码，边解码边释放，把内存峰值压成常量级。

安全

• 全程本地处理，不做任何网络上传——这既是隐私要求，也是这类工具的核心卖点，建议在界面上明示；
• 导出路径必须用户显式选择，禁止静默覆盖；
• 若后续加上”从网络加载图片”功能，需校验来源与文件类型，避免解码不受信任的文件；
• 云端调用模型时，凭据走环境变量或密钥管理服务，代码仓库中不出现明文密钥。

稳定性

• 每个外部输入（文件损坏、格式不支持、尺寸超限）都要有明确的用户提示，而不是抛异常白屏；
• 给导出加进度反馈与可取消能力，长任务无反馈会被用户误判为崩溃；
• 提交锁文件、固定依赖版本，保证不同机器构建一致。

可维护性

• 保持 layout.js 的纯函数特性，它是整个项目里唯一必须被测试覆盖的部分；
• 把”适配策略””背景色””间距上限”做成配置项，而不是散落在代码里的魔法数字；
• 每次让模型修改代码后，要求它同步更新 SPEC.md，让规格与实现不脱节。

成本

• 长程智能体任务会持续消耗推理 token。若使用云上推理服务，建议：任务开始时先让模型输出完整计划并确认，避免无效往返；把小工具生成这类任务放在成本更低的模型档位；用监控告警观察调用量与费用趋势，设置阈值提醒；
• 无状态的小工具类任务，输入输出都可以精简——不必把整个日志贴进上下文，只给相关片段。

九、可以继续延伸的方向

跑通这个 MVP 之后，有几个自然的进阶方向，都能沿用同一套”规格 + 分阶段执行 + 测试先行”的方法：

• 功能扩展：拖拽调整图片顺序、按指定像素宽高导出、支持 GIF 动图拼接；
• 能力升级：从”拼接”扩展到裁剪、缩放、加水印，逐步接近轻量图像编辑器的能力范围；
• 代码理解类任务：找一个没有文档的旧代码库，让模型先输出模块地图与调用关系图，再逐模块补注释——这是长上下文能力最直接的用武之地；
• 跨语言移植：把编译型语言的旧实现迁移到带类型的脚本语言，全程不逐行看代码，只审查模块边界与测试用例；
• 工程化沉淀：把这套流程固化为团队模板——统一的规格文件格式、统一的测试分层、统一的权限确认清单。

十、总结

这篇文章的核心不是”十分钟做出一张长图拼接工具”，而是 Three 个可迁移的结论：

第一，规格质量决定生成质量。 万亿参数模型的长上下文足以装下完整需求，但装不下你脑子里的隐含假设。把验收标准写成可测量的公式，是提升一次成功率最便宜的手段。

第二，把不确定性关进笼子。 先实现可测试的纯计算逻辑并用断言锁死，再让模型处理绘制、交互、导出这些副作用密集的部分。测试不是为了证明代码对，而是为了给模型一个可自我修正的反馈信号。

第三，长程执行的闸门在人手里。 让模型连续跑完十几个步骤是它的优势，但依赖安装、文件删除、端口监听、凭据配置这些操作必须人工确认。分级权限 + 阶段性质检，是”放它跑远”和”不出事故”之间唯一可行的平衡点。

至于那个模型本身——它在数学竞赛级别的题目上取得金牌成绩，长文本与长程任务能力有阶跃式提升，这些是事实。但对你我更有意义的判断标准只有一个：它能不能在你真实的项目里，把一件你原本不想自己动手的脏活干完。 十分钟做出一个丐版图像处理工具，已经足够回答这个问题了。