工程手记

AI 项目做多以后,真正难的是把边界接起来

从多个 AI 项目的 Git 记录和设计文档看,工程难点已经从“能不能生成”转向任务、计费、交付、恢复与用户反馈能否形成闭环。

STRUCTURE ── 篇幅剖面4 节 · 点击跳转

这段时间回看 /Users/xingye/Ai 下的项目,最明显的变化不是项目数量增加,而是问题的重心变了。

早期问题集中在“功能能不能跑起来”:语音推理、网页生成、桌面端启动、小程序页面、视频服务。进入平台化阶段以后,问题变成了另一组:任务是否可追踪,失败是否能恢复,费用是否能对账,版本是否能回滚,用户是否知道发生了什么。

这是一条从功能开发走向系统工程的分水岭。

一、项目群已经形成几条清晰的产品线

Agent 与多租户平台

yun-clawyun-claude 的记录显示,平台主线已经覆盖用户容器、模型接入、画布工作流、代理渠道、后台管理和运营工具。近期提交涉及画布自绘 Select、资产大图预览、代理激活码申请,以及渠道注册页的差异化展示。

这些功能看起来分属不同页面,底层却共享一套问题:用户身份、资源权限、异步任务和状态反馈必须保持一致。只改页面,不补状态契约,功能就会在跨页面操作时暴露断点。

内容生产流水线

ai-writeinstantlink-siteai-auto-editai-digital-human-workflow 分别覆盖写作、漫剧、自动剪辑和数字人视频。提交记录里反复出现几个关键词:任务网关、切片下载、共享卷、FFmpeg、提示词优化、失败提示和构建复现。

这说明内容生产已经不是单次调用模型,而是一条有中间产物的流水线。文本、图片、视频、音频和项目资产都有生命周期,任何一步的状态丢失都会让用户无法判断下一步该做什么。

交付、网关与桌面端

newCodexnew-openclawopenclaw服务器管理SSHTS 的记录,集中在更新、恢复、远程诊断、单实例生命周期和离线环境上。这里的核心指标不是“新版本发布了没有”,而是安装失败能否定位、更新中断能否恢复、客户机器能否留下可审计证据。

这也是为什么桌面端工程会逐渐靠近运维工程:安装器、后台服务、日志、配置和回滚必须一起设计。

网关、计费与数据观察

NewAPInew-api 的近期记录包括按模型统计 Token 消耗、扣费量、时间粒度聚合、昨日活跃用户和订单搜索。网关不只是转发请求,它还承担了模型选择、消耗记录、后台观察和问题追踪。

一旦计费数据进入用户体验,接口成功与业务成功就不再是同一个概念。请求返回 200,只能说明一次网络调用完成;扣费、产物落盘和任务终态是否一致,需要单独核对。

二、Git 记录里最有价值的变化,是“边界被写出来了”

多个项目的文档都在补同一类内容:部署手册、验收清单、测试报告、故障复盘、模型环境快照和用户协议。

这类文档的价值不在于把代码再讲一遍,而在于把系统边界写清楚:

  • 输入是什么,哪些字段必须存在;
  • 状态有哪些,什么条件才能进入下一状态;
  • 外部服务超时后,如何判断请求是否已经执行;
  • 产物写入失败时,是否允许重试;
  • 更新中断后,哪个版本可以安全恢复;
  • 用户看到的成功,是否和后台记录的成功一致。

当这些问题没有答案时,系统只能靠人工经验维持。一旦项目数量增加,经验就会变成不可复制的隐性依赖。

三、下一阶段的重点不是再加一个入口

从现有项目的提交和文档可以看到,下一阶段更值得投入的是四个基础能力。

第一,统一任务状态。不同项目都在处理异步任务,但状态命名、失败原因和重试策略不应各自发明。

第二,统一产物账本。一个任务产生了哪些文件、消耗了哪些资源、是否对用户可见,需要能从提交到终态完整追踪。

第三,统一故障出口。401、超时、部分成功、未知执行和版本回滚,应该有明确的用户反馈与后台证据。

第四,统一发布验收。构建通过不代表线上可用,应该把健康检查、代理路径、真实端口、关键日志和浏览器操作放到同一份验收清单里。

项目多以后,工程能力不再体现在“能写多少功能”,而体现在“能否让不同功能遵守同一套边界”。

四、我会保留的判断

AI 项目最容易被低估的部分,不是模型调用,而是模型调用之后的系统。

生成只是起点。身份、任务、费用、存储、交付、恢复和反馈,决定了一个功能能不能进入真实使用。

当 Git 提交开始频繁出现“补状态”“补恢复”“补验收”“补审计”时,这不是工程变慢了,而是产品从演示阶段进入了可运营阶段。

星野的头像

星野 XINGYE

全栈工程师。这里记录 82 篇复盘:24 份故障档案、OTA、架构演进与工作流。