SoduWork修自己:一份AI原生开发的全流程实测记录
本文记录了使用 SoduWork 修复其自身两个真实缺陷的全过程。从搭建本地环境、接入多模型,到编写可验收的任务单,再到执行代码修改、异构模型评审及最终提交上游 PR。文章详细拆解了如何处理返工策略类型错误和多语言资源加载遗漏问题,并总结了 AI 辅助开发的适用边界与实操方法,旨在展示 AI 原生开发在真实工程场景中的
为什么把SoduWork的bug交给SoduWork自己修
网上AI编程的演示不少,多数只做到「代码生成出来」就收尾。既没有验收标准,也无人评审,更没进过真实仓库,看下来总让人心里没底。我想试一次完整的流程:把活整个交给AI,在本机笔记本上跑通,再看改出来的结果是否靠得住,最后能不能成为开源仓库里一条正经的提交。
我还给自己加了点难度:让SoduWork去修SoduWork自身的bug。
做这个选择,出于三点考虑。第一,AI原生开发这件事最容易被演示糊弄。录一段「AI写了个贪吃蛇」并不难,可真实开发不是从零写个小游戏。摆在面前的是一个陌生代码库,有自己的测试、提交规范和历史包袱,写完之后还得有人提意见、要求返工。能不能在这样的环境里干活,才是我真正想弄清楚的。
第二,SoduWork的体量正合适。仓库里有FastAPI + SQLAlchemy异步实现的Hub服务、React/Vite管理后台、Electron桌面端、一批JSON格式的内置插件,另外还有执行器Runner。每一块都配了自己的测试和检查脚本,算不上玩具项目,也没大到让人无从下手。拿它修它自己还有一层好处:修复工具和被修对象是同一套东西,好不好用一看便知。
第三,修完的结果可以直接提issue和PR,过程与结论都公开可查,评委和读者能自行核对,不必只听我一面之词。
实验台的整体配置与版本信息
全部跑在一台笔记本上。代码准备了两份:一份用来启动SoduWork,另一份从我的fork克隆出来,专门交给AI修改。之所以分开,理由很直接——我不希望AI一边改代码,一边把正在跑的服务弄坏。
SoduWork的Hub只监听本机的127.0.0.1:18989,数据单独放在一个数据目录里,桌面端自带Pi执行底座。模型走自建模型网关,执行用DeepSeek V4 Flash,评审用通义千问 3.7 Max。上游仓库是mdiri-ai/SoduWork。
环境细节如下:
- 操作系统:macOS 15.7.3,arm64
- Python / Node:3.13.5 / v24.11.0
- SoduWork:上游main @,客户端 1.13.17
15f36192 - Hub地址:
127.0.0.1:18989(仅本机) - 执行底座:Pi(桌面端内置)
- 执行模型:DeepSeek V4 Flash
- 评审模型:通义千问 3.7 Max
- 提交身份:GitHub noreply 邮箱 + DCO 签名
本机实验台从零搭起
一键启动背后做了哪些事
先在GitHub上Fork一份,再克隆到本地。SoduWork的本地入口是start.py先在 GitHub 上 Fork 一份,再克隆到本地。为了环境干净、方便复现,我添了几个参数:
git clone https://github.com/ZYFCodes/SoduWork.git
cd SoduWork
git remote add upstream https://github.com/mdiri-ai/SoduWork.git
python3 start.py --desktop --no-browser --data-dir /path/to/data --password-stdin < admin-password.txt--data-dir把虚拟环境、数据库、日志以及桌面端的私有副本都放进单独的目录,这样源码目录就不会被弄脏。--password-stdin让首次启动时从标准输入读取管理员密码,命令行历史里便不会留下明文。
首次启动共六步,每一步结束都会打印耗时。前五步走得挺顺,结果卡在最后一步——下载 Electron 运行环境。默认从 GitHub 下载,网速太慢,等了很久也没下完。翻代码才发现,它底层用的是@electron/get可以通过环境变量换成镜像。这里有个小坑:有的国内镜像,版本目录里没有v 前缀,光设 ELECTRON_MIRROR不够,还得再加一个ELECTRON_CUSTOM_DIR='{{ version }}'换完镜像再跑,这一步很快就过了。
中途停掉再重跑,前面已经完成的步骤会直接复用,不用从头再装一遍,这点让我印象不错。
模型接入的三道坎
SoduWork 并不锁定某一家的模型,它用「模型目录」把「服务」和「模型」拆成两块来管。我一开始以为接模型无非填个 Key,结果来回折腾了三回。
第一回,Key 填错了。保存之后能力检测全部失败,错误码是credentials_or_access检查发现,复制的时候把刚用过的管理员密码粘了进去。这个错误挺低级,不过也让我注意到 SoduWork 的错误码给得足够具体,一下子就把范围缩小到了凭据上。
第二回卡在协议上。我后来换成一个自建的模型网关,那网关默认给的是 Anthropic 协议的地址。SoduWork 能存 Anthropic 类型的服务,但一开对话就被挡回来,提示「当前企业模型对话通道只支持 OpenAI 兼容接口」。我把网关那几个路径挨个试了一遍,发现同一个网关在/openai/v1下有 OpenAI 兼容的接口,用同一把 Key 就能调通。
第三回,模型挑人。网关列出了几十个模型,可列出来不等于都能用。有的模型一调就返回url error;有的要求必须开启思考模式。最后我老老实实给几个候选各发了一条最小请求,挑中了qwen3.7-max 来做评审,DeepSeek V4 Flash 来做执行。
接通以后,我用 SoduWork 自带的功能又测了一轮。这轮检测有四项:连通、工具调用、流式输出、图片输入。两个模型都通过了前三项,图片输入这项不支持。这次改动只涉及代码,用不上图片,没影响。工具调用是我最看重的,Pi 执行底座靠它读文件、改文件、跑命令,这项要是过不了,模型就只能陪人聊天,活干不了。
找到两个值得修的真实缺陷
先说这两个缺陷是怎么找出来的。同一份数据,如果一处写、好几处读,那就把读的一方和写的一方对一对,看两边对数据长什么样的假设是否一致。
返工策略就是这么找出来的。读的一方是引擎,用dict()读取,默认它是个对象。写的一方是 23 个内置插件的 JSON。我用git grep 把所有 onFailure、onReject的写法列出来,一眼扫过去,只有一个插件写成了字符串。
多语言那个也是同样的思路:词典文件是写的一方,读的一方有两个,一个是 HTML 里的<script>列表,一个是manifest.json。把两边的文件名列表一比,多出来的那一行就是漏登记的。
这种对账的办法很机械,可以写成脚本,几乎没有误报,找出来的问题天然带着复现路径。
缺陷一:返工策略写成了字符串
SoduWork 的插件能带一条工作流,节点之间可以声明「失败了从哪一步重来」,这就是返工策略。引擎读取返工策略的那段代码在hub-backend/app/services/workflow_engine.py:
# workflow_engine.py(节选)
async def _begin_rework(session, run, source, policy: dict, feedback: str, *, manual_max_rounds=0) -> bool:
retry_from = str(policy.get("retryFrom") or "")
if not retry_from:
return False
...
# 节点失败时的调用方式
cfg = await _node_config(session, run, nr.node_key)
await _begin_rework(session, run, nr, dict(cfg.get("onFailure") or {}), evidence)从这段代码能看出来,引擎期待onFailure是一个对象,形如{"retryFrom": "implement", "maxRounds": 2}。调用时先用dict(...)复制一份,再从里面取retryFrom 和 maxRounds。
可内置插件 hub-backend/plugins/autonomous-dev-iterator.json,即「自主迭代研发引擎」,在quality 和 selfcheck有两个节点是这样写的:
"onFailure": "implement"dict("implement")这个字符串会被当作一组键值对来拆解。拆出来的第一个元素"i"长度仅为 1,凑不成键值对,于是直接抛出ValueError。我在 hub-backend在目录里用该插件自身的数据做了复现,报错确实出现。
这背后分两层。表层原因在于插件数据本身写错了:只要质量门禁或 AI 自检没通过,流程就无法退回「实现」节点重新执行。有些讽刺的是,插件说明里写得清清楚楚,「质量门不过必须回流实现节点重做,严禁带病交付」,可偏偏断的就是这条回路。再往深看,是清单校验环节没把它拦住。plugin_manifest.normalize这里是内置插件登记与插件包上传共用的入口,节点类型查过了,AI 节点的 prompt 也查过了,唯独没检查返工策略长什么样。
缺陷二:韩语词条走丢了一半
SoduWork 桌面端提供中、英、日、韩四种界面语言,翻译文件统一放在client/core/locales/目录下。不过加载这些文件走的是两条不同的路径。
页面(渲染进程)这一侧,desk.html 和 index.html 用 <script>标签会把语言文件逐个读进来。像desk.html就会依次加载en-US-agent-pages.js、ja-JP-agent-pages.js、ko-KR-agent-pages.js。
原生菜单和对话框归主进程管,这部分交给client/main/native-locale.cjs处理。它不解析 HTML,只认core/locales/manifest.json这份清单,照着它把词典拼起来。
偏偏清单这里出了岔子:其中列了ja-JP-agent-pages.js,却漏了 ko-KR-agent-pages.js于是韩语界面下出现两种表现:页面里的 Agent 管理文案是韩文,原生菜单和对话框里的同一批文案却退回英文。跑一条命令即可复现:
cd client
node -e 'const l=require("./main/native-locale.cjs");l.setLocale("ko-KR");console.log(l.translate("重装"))'
# 输出:Reinstall(期望:재설치)ko-KR-agent-pages.js其实"重装": "재설치"早就写好了,译文一条不缺,问题只是清单上漏登了一行。
把需求写成 AI 能执行、人能验收的任务单
这轮做完,我体会最深的一点是:AI 原生开发里,人最该下功夫的环节已经从敲代码挪到了写任务单。两个需求的任务单,我都按同一套结构拆成五部分。
开头先描述现象:哪个文件、哪一行、具体什么表现。第二部分是证据和定位:引擎读的是哪两个字段,正确写法能参照哪个插件。这些我直接写进去,省得模型自己四处试,也能压低它另搞一套「发明」新写法的可能。第三部分是验收标准,逐条列,每条都得能判断对错。第四部分是测试命令,给的是能原样复制运行的完整命令,环境变量一并带上。最后是提交约束:开哪个分支、提交说明如何写、用git commit -s、不要 push。
需求一任务单中验收标准那一段,全文如下:
autonomous-dev-iterator.json的quality、selfcheck节点onFailure改为{"retryFrom": "implement", "maxRounds": 2}插件 version 依 SemVer 从 1.0.1 升到 1.0.2,别的都不动。plugin_manifest.normalize工作流节点 config 里的onFailure/onReject如果不是对象,或者retryFrom不是非空字符串,就抛出ValueError,提示信息里得带上节点 key,并讲清正确写法。字段没给时,维持现有行为。- 新增
hub-backend/test_plugin_rework_policy.py:字符串onFailure节点 key 没写进报错信息就被挡下;换成对象写法后过关。hub-backend/plugins下所有.json内置插件这一轮全部走通。normalize。 - 测试这样跑:
AUTH_SECRET=lab-test-secret ADMIN_PASS=x <venv>/bin/python -m unittest test_plugin_rework_policy ... - 新建分支
fix/plugin-rework-policy,git commit -s只做本地提交,别 push。
验收标准我没写「代码要健壮」「测试要充分」这类话。这种表述没法判对错,评审到最后只能凭感觉给分。
执行环节:Pi 配 DeepSeek,在 SoduWork 里动代码
需求一:读、改、测、交,大约 4 分钟
任务单派下去,DeepSeek V4 Flash 没上来就改。它先读了workflow_engine.py 里处理 onFailure那套逻辑,又去看了engineering-delivery.json里该怎么写才对,另外翻了两份现成的测试文件。接着它把_begin_rework整份读到底,核对字段名没弄错,才开始下手。
最终提交动了 3 个文件,新增 99 行、删除 3 行。插件数据这块,两个节点都换成了对象写法,版本由 1.0.1 提到 1.0.2。清单校验这边,它在normalize的节点循环中补了校验:
config = dict(item.get("config") or {})
for rework_field in ("onFailure", "onReject"):
if rework_field in config:
policy = config[rework_field]
if not isinstance(policy, dict):
raise ValueError(
f"节点 {node_key} 的 {rework_field} 必须是对象,"
f"正确写法 {{\"retryFrom\": \"<节点key>\", \"maxRounds\": N}}")
retry_from = policy.get("retryFrom")
if not isinstance(retry_from, str) or not retry_from.strip():
raise ValueError(
f"节点 {node_key} 的 {rework_field}.retryFrom 必须是非空字符串,"
f"正确写法 {{\"retryFrom\": \"<节点key>\", \"maxRounds\": N}}")我一行行看过去,写得挺到位。if rework_field in config这句话的意思是:字段没填的时候压根不会进校验,正好符合「保持现有行为」的要求。isinstance(policy, dict)字符串、数字、列表这些类型全被拦下。另一处判断则专门针对null{}、{"retryFrom": ""}那种表面像对象、实际上根本不会引起返工的写法。
测试文件一共 7 个用例,各类异常情形都覆盖到了。我最有好感的是最后那个遍历hub-backend/plugins/*.json的用例。往后谁再往内置插件里写错返工策略,它准会头一个报错。
需求二:改清单、补测试,约 65 秒
需求二的改动量更小。DeepSeek 在manifest.json中加了一行,另外新建了测试文件client/tests/locale-manifest-coverage.test.cjs,里面放了两个测试:
- 一条是结构性检查:日后有人在 HTML 里新增语言文件却漏了登记清单,它会马上失败。
- 另一条是功能检查:调用真实的
native-locale.cjs,看用户最终能看到什么结果。
有个细节出乎我意料。DeepSeek 自己察觉到global-search.js同样在 HTML 里被加载,可它并非单一语言的词典,而是一张表里写着四种语言的文案;native-locale.cjs它用的文件名正则本来也不会把它加载进来。于是测试中它把这个文件标为豁免,注释里也写明了缘由。这一点,任务单上我一个字都没提。
独立评审与返工:换另一家模型来挑刺
为何要换一家模型评审
同一个模型检查自己写的代码,思路多半还是写代码时那一套。换一家模型,训练数据、推理习惯、盯的点都不一样,至少不会踩进同一个盲区。最后我再把一道关,三方各管一段。
评审对话是这样设的:只读,明确要求不许改文件、不许提交、不许切分支;对照验收标准逐条核对,每条都得给出证据;要查代码的真实行为;还要做反向验证,拿旧版本的数据去撞新校验,看能不能真拦住。
需求一:一次就过,评审还做了反向验证
通义千问 3.7 Max 花了大约 70 秒,给出「通过」。这轮有两处让我觉得它不是敷衍了事。
其一是反向验证。它拿git show main:hub-backend/plugins/autonomous-dev-iterator.json先把旧版本的文件调出来,交给新版normalize跑一遍校验,得到的结果是ValueError新版校验确实拦得住旧写法,不是做样子。
第二件事是查有没有误伤。它找到了normalize两个入口,同时确认现有写法都合法;已经装好的旧版运行时也不会被重新校验,所以不会出现「一升级就加载失败」的情况。
需求二:有条件通过,返工一轮后复审通过
需求二给出的结论是「有条件通过」。刚看到这个结论,我还以为 DeepSeek 哪里写错了。等把评审理由往下读完,才发现毛病出在我自己写的任务单上。
评审的推理过程是这样的:native-locale.cjs按照清单顺序用Object.assign合并词典,后合并的条目会覆盖先合并的;页面里ko-KR-agent-pages.js是韩语词典中最后加载的那一个;但第一版提交按我任务单的要求,把它插到了ko-KR.js前面,覆盖顺序跟页面正好相反。它还写了个只读脚本做统计,发现ko-KR-agent-pages.js 和 ko-KR-gap-pages.js当中有 4 个键同名,译文却不一样。
「重装」这个核心问题确实修好了,可同一次改动又带进来新的不一致:韩语用户在原生菜单和页面里,会看到同一个功能有两种说法。评审给出了两个方案。方案 A 是把清单里这一行挪到ko-KR-gap-pages.js后面,与页面顺序对齐,评审推荐的就是这个。方案 B 则是删掉重复的键,只保留一份译文。
我选了方案 A,把评审意见原封不动交回之前那个执行对话,让 DeepSeek 在原有上下文里返工。返工大约 30 秒就完成了,走的是新增提交,没有改写历史。它贴出的修复前失败输出,正好命中评审指出的那个键。
我自己又发现一个小问题:新测试文件末尾缺了个换行,而仓库里其他测试文件都带着。这种小事我也没上手,仍旧交给执行模型:补换行、重跑测试、合进返工提交。
复审花了大约 35 秒,结论是「通过」。复审里有一步我觉得挺有意思:评审把旧顺序和新顺序各模拟合并了一遍,旧顺序下 4 个冲突键全部对不上,新顺序下 4 个全部对上。
把成果沉淀到上游
issue 与 PR 怎么写
上游仓库有现成模板。我大致照着模板写,另外多做了三件事。
两个 issue 的开头,我都说明了来历:这是在本机用 SoduWork 跑「AI 原生开发」场景时发现的,后面附了复现命令和日志。
PR 里我交代了改动是怎么来的:用的哪个执行底座和模型,由哪家模型评审,评审结论是什么,返工改了什么,我自己又复跑了哪些。需求二的 PR 里,「第一版位置写错,是我的任务单造成的」这件事我也一并写了进去。
没验证到的部分,我也单独列了出来:Windows 和 Linux 上的原生菜单我没有实际截图看过,完整的npm test有一次完整的工作流没跑起来,那次带的是真实失败质量门,也没跑。
为什么要主动交代 AI 参与了哪些环节?我换到维护者的位置想过这件事。开源项目每天进来的 PR 只多不少,AI 生成的那部分占比也在往上走。维护者真正在意的,未必是「这是 AI 写的」,而是「这东西到底有没有人认真看过」。PR 里如果写明谁执行、谁评审、结论如何、人复跑了哪几项、还有什么没覆盖,维护者一眼就能判断这次改动有几分可信、剩下哪些风险、自己该重点补看哪里。
签名与身份
上游的规矩是每个提交都得带 DCO 签名,也就是用git commit -s,在提交说明末尾加一行Signed-off-by。这里藏着一个常被忽略的隐私问题:我全局的 git 配置填的是工作邮箱,而签名这一行会把邮箱永久写进公开仓库的历史,日后想删都删不掉。于是我在工作副本里单独把提交身份换成了 GitHub 提供的 noreply 邮箱,这样执行模型跑git commit -s的时候,就会自动以这个身份签名。
截图里出现的网关地址同样都打了码,issue 和 PR 中也只写「自建模型网关」,内部地址和密钥一概没有出现。
测评结论:适合做什么、不适合做什么
做得好的地方
本地启动这一块,我认为 SoduWork 做得相当扎实。start.py分步打印进度和耗时,已经完成的步骤可以复用,数据全部放在独立目录里,源码目录保持干净。
模型接入带诊断能力。能力检测分连通、工具调用、流式输出、图片输入四项,credentials_or_access这类错误码能把排查范围直接压缩到凭据上。碰到协议不兼容,它会明确拒绝,不会悄悄抛出一个莫名其妙的错,这点我认可。
执行过程留痕完整。读文件、改文件、跑命令都折叠成可展开的记录,汇报格式还能用任务单来约束。事后复盘不必靠回忆,每一步都能翻回去查。
模型和执行底座能按对话切换。同一个桌面端里,就能搭出「一家执行、一家评审」的流程,不用再另找平台。
不够顺手的地方
协议限制提示得太晚。Anthropic 类型的服务能保存,能力检测也只显示「未测试」,非要等到开对话那一刻才被拒。要是保存或检测时就提示「对话通道只支持 OpenAI 兼容接口」,能少走一轮弯路。
新开对话不会继承上次手选的工作文件夹。执行对话和评审对话来回切,每次都得重新选目录。我后来索性在提示词里写死仓库的绝对路径,绕过了这个问题,但终究不太优雅。
选文件夹只能用系统对话框,没法直接输入或粘贴路径。需要精确控制目录的场景下,这就不太方便。
适用边界
把这两个需求的完整过程合起来看,对「把开发任务交给 SoduWork 里的 AI」这件事,我大致是这么判断的:
- 缺陷修复(有复现、有测试):适合。这次两个需求都属此类,验收标准容易写成可判定的条目。
- 清单、配置、数据类问题:适合。改动小,容易做全量扫描式测试。
- 补测试、小步重构:适合。已有测试兜底,评审能看清。
- 大范围重构:慎用。改动面大,评审和人工复核的成本陡增。
- 数据迁移和公共协议变更这类改动同样要慎用。贡献指南里写明了,得先开issue把方向讨论清楚,不适合直接丢给AI去动手。
- 没有测试覆盖的模块也慎用。这种情况下「通过」两个字没了判断依据,只能靠人一行行去看。
这次一共花了多少时间
敲代码这件事,模型加起来动手还不到10分钟。人耗掉的时间落在前后两头:一头是读代码、找毛病、把任务写清楚,另一头是检查结果、准备对外的交代。从任务第一次派出去到两个PR交上去,中间一共24分钟。可我心里明白,这24分钟之所以顺,是因为任务单提前写得够细,复核该盯哪些点也早就定好了。写代码被AI压成几分钟之后,真正难的地方换成了「把问题想明白」和「确认结果没毛病」。
那18分钟对接模型的时间,大半其实可以省掉:Key填错了,网关协议不匹配,还有个别模型根本调不通。要是团队里有人事先在模型目录里配置好、验证过,后面的人再用,这一步几分钟就能过。
可以直接复用的方法
最后把这次的做法整理成一份清单,换个仓库也照样能用:
- 先找缺陷,再写任务单。挑问题时问四件事:值不值得修,能不能复现,能不能写出验证用的测试,改动小不小。
- 任务单分五段:现象、证据与定位、验收标准、测试命令、提交约束。验收标准每条都能判断对错,测试命令能原样复制运行。
- 执行和评审用两家不同的模型。评审只读,对照验收标准和代码的真实行为一条条查,并且要做反向验证。
- 返工回到原来的对话里做。先写一个能复现问题的测试,再修,用新增提交,不改写历史。
- 最后一道关一定是人。自己复跑测试和冒烟脚本,补一个站在用户角度的全量比对,再查一遍边界情况和脱敏。
- 往上提的时候,把前因后果交代清楚。issue里写清楚怎么复现,PR里说明怎么验证、AI参与了哪几步,哪些地方没验证到要列出来,署名用noreply邮箱。
回头再看这次实战,让我记得最牢的不是AI把代码写对了,而是我任务单里写错的那一处,被另一家模型挑了出来。用AI做开发,人不用再一行行敲代码,但需求得细到能被检验,分工得排成能相互挑错的样子,最后的活儿还是得人来兜底。