我把 SoduWork 开源版完整跑了一遍,顺手给官方修了个启动死锁 Bug

7 年 Java 后端,最近在折腾 AI Agent 创业。看到 SoduWork 开源了,star 涨得挺快,正好我也要给自己找个能自托管的协同平台,就花了一个下午从源码完整装了一遍。中间踩了三个坑,最后干脆给官方提了两个 issue、一个修复 PR。这篇就是过程记录,国内网络想装的朋友可以直接抄我的作业。

开源地址(觉得有价值去点个 Star):https://github.com/mdiri-ai/
官网(含客户端下载):https://soduwork.mdiri.com/


一、为什么是 SoduWork

选型前我把它和市面上的同类东西放一起比了比。大多数产品走两条路:要么纯 SaaS,数据必须出企业边界;要么是 Agent 框架,只有代码没有产品形态,落地全靠自己拼。

SoduWork 卡在中间这个位置:开源、自托管、企业级的 AI 原生协同平台。说白了就是"人定标准,AI 交付"——需求、执行、验收、经验沉淀连在一条线上,而不是一个聊天框套个壳。

官方列的四个场景,对应的是真实的企业工作流:

场景干什么典型产出
全生命周期自动化把一项有边界的任务从需求推进到验收成果 + 过程记录 + 验收依据
AI 原生开发需求文档 → 拆解 → 写码 → 自测 → 交叉审查代码变更 + 测试报告 + 发布记录
跨组织协作人和 Agent 围绕同一结果协同,关键节点人工把关审批留痕的版本化成果
组织经验沉淀把验证过的方法做成 Skill/插件,全团队复用可安装的企业插件

技术栈我看着挺顺眼:桌面端 Electron + React,Hub 后端 FastAPI + SQLAlchemy(Python 3.12+),管理台 Vite,本地模式 SQLite 开箱即用。模型侧支持按环节配置,DeepSeek、火山引擎(豆包)、阿里云百炼(通义)、智谱 GLM、Kimi、OpenAI 这些都有现成接入。

仓库 703 star / 120 fork,MIT 协议(自有代码),我克隆那天它还在合并 PR,活跃度没问题。

二、初体验:客户端和管理台

源码启动就一条命令:start.cmd --desktop(Windows)。首次会自动装依赖、建数据库,把 Hub 服务(127.0.0.1:18989)、管理台和桌面客户端一起拉起来。首次启动要求给 admin 设 12-128 位密码——没有默认密码。这点我得说声好评,多少开源产品 admin/admin 就直接放过去了。

在这里插入图片描述

在这里插入图片描述

桌面客户端是个标准的协作工作台:左侧项目/会话,中间对话流。Agent 干的每一步——写文件、跑命令、中间思考——都在对话流里实时滚出来,事后能回看完整轨迹。管理台管平台配置:模型目录、成员权限、插件管理。

在这里插入图片描述

三、国内网络安装攻略(我帮你趟过了三个坑)

先把两条安装路径说清楚,免得有人问"官网不是能直接下吗":能。官网 soduwork.mdiri.com 挂着现成的客户端安装包(v1.12.86,Windows/macOS/Linux 都有),普通用户直接下最省事。

我选的是另一条——从 GitHub 拉源码跑,原因有二:一是想看它的实现(第六章有源码速览);二是这次要给官方提 PR,手里没源码提不了。所以下面三个坑全是源码路径的,走安装包的朋友大概率碰不到;但如果你也想从源码玩,这几个坑我已经替你趟平了。

直说:国内网络源码安装的成功率不高,官方下载链路对污染环境的兼容还有改进空间——这也是我后来提 issue 的原因。但三个坑的解法都很明确,照抄就行。

坑 1:pip 装依赖超时

第一次跑就卡在 [2/4] 安装服务依赖,清华源 read timeout。我还以为是自己环境的问题,换源解决:

$env:PIP_INDEX_URL = "https://mirrors.cloud.tencent.com/pypi/simple"
$env:PIP_DEFAULT_TIMEOUT = "120"

有个细节值得表扬:启动脚本做了断点复用,失败的步骤重跑会自动跳过已完成的部分,不用删数据重来。后面两个坑都吃到这个红利。

坑 2:Electron 运行时下载失败

pip、npm、管理台构建全过后,卡在 [Desktop] 下载桌面运行环境。翻了下代码发现原因:Electron 下载走 Node 原生 fetch(undici),不读代理环境变量,污染环境直连 GitHub 直接死,官方提示的 ELECTRON_MIRROR 在 undici 下也不生效。

只能手动绕过下载器:

# 实际锁定版本看 node_modules/electron/package.json,我的是 44.9.3
curl -L -o electron.zip https://npmmirror.com/mirrors/electron/44.9.3/electron-v44.9.3-win32-x64.zip
# 解压到 %LOCALAPPDATA%\SoduWork\source-service\application\client\node_modules\electron\dist\
# 确认 electron.exe 存在即可,启动脚本检测到就跳过下载

坑 3:PortableGit 下载 + 中断死锁(最有意思的一坑)

第三步还要从 GitHub Releases 拉一份 PortableGit 2.55.0.4(约 60MB)当内置 Shell 运行时,同样直连不读代理。污染环境报 ECONNREFUSED 127.0.0.1:443——github.com 被解析到了本机。

读源码发现 prepare-shell-runtime.cjs 有缓存复用机制:安装包放进 .runtime-cache/、SHA-256 对上就跳过下载(校验值脚本里直接写好了)。走代理 curl 下载放进去,重跑通过。

但我在中断重启时撞上了一个真 Bug:PortableGit 解压出的 etc/mtab 是指向 /proc/mounts 的符号链接,NTFS 上是 APPEXECLINK 类型 reparse point,Node 的 rimraf 永远删不掉它(EPERM)。首次解压后只要中断过一次,之后每次启动都在同一步崩——普通用户没有任何自救手段。

四、配模型和 Agent

管理台 → Agent 管理。我的智能体列表里有 DeepSeek、Claude Code、Codex Harness、月之暗面 Kimi、OpenAI 等,接口协议 OpenAI 兼容。

在这里插入图片描述

我配了 DeepSeek:填 API 地址 + 个人 Key,保存测试连接一次通过,前后不到一分钟。按环节配模型这个设计对多模型团队挺实用——实施和审查可以挂不同的模型。

在这里插入图片描述

五、真任务实测:7 分钟交付一个数据小工具

连通之后我给 Agent 派了个贴合日常的任务,就三句话:

  1. 在指定目录生成 10 个模拟小红书笔记 txt(AI 工具测评主题);
  2. 写 stats.py:统计每篇字数和标题长度,输出 summary.csv;
  3. 运行验证后展示结果。

15:11 发出,15:18 交付,全程 7 分钟(DeepSeek)。看它的执行轨迹:

  • 建目录、确认可写、探测 Python 版本,一步没跳;
  • 生成 10 篇笔记 → 写 stats.py → 运行,退出码 0;
  • 它自己加了一道"独立核对":用另一套算法重算每篇字数,跟 CSV 逐行比对,10 篇全对上才交付;
  • 甚至测了从其他目录调脚本(验证不依赖运行时当前目录);
  • 交付物带"口径说明"——空白字符不计入、标题按首行非空行算。

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

“实施 → 自主交叉验证 → 交付带口径"这个行为,正好对上它官方说的"实施 Agent / 审查 Agent 分工”。不管内部是不是真双 Agent,至少工程习惯是真的,不是拿到结果就交差。

六、源码速览:这个启动器比我预想的讲究

拆过不少开源项目,tools/dev/ 下这套启动器质量出乎我意料:

  • 数据目录隔离:独立 venv、独立 HOME、独立 SQLite,源码 checkout 和运行时完全分离,不污染系统;
  • 文件锁防重复启动:Windows 用 msvcrt.locking,跨平台细节都处理了;
  • 断点复用:每步安装有 stamp 校验(package-lock 的 SHA-256),完成即跳过;
  • 安全意识在线:源码 checkout 在 rebase/merge 中不允许启动;PortableGit 下载后强制 SHA-256 校验 + 剪枝 + 自测——真实跑一遍 git init/commit/log 才算装好;
  • 边界感:runtime_environment() 白名单继承环境变量,显式排除模型 key 和部署配置,"本地体验"和"企业配置"分得很清。

这套"源码即产品"的工程化程度,在我测过的开源 AI 项目里算第一梯队。

七、工具里还翻出 38 个内置技能

装完翻目录的时候我又发现一个惊喜:skills/ 下自带 38 个开箱即用的技能,不用去商店挑,clone 下来就有。挑几个我一眼相中的:

  • 研发向:tdd(测试驱动开发)、code-review、diagnosing-bugs、systematic-debugging、delivery-check、resolving-merge-conflicts——基本把一个开发团队的日常动作都预制好了
  • 产品向:agent-product-design、product-incubator、prototype、frontend-design——从产品孵化到原型一条线
  • 效率向:office、pptx、brainstorming、writing-plans
  • 平台向:skill-studio、mcp-studio、skill-creator——自己写技能、接 MCP 工具

这其实就是官方四个场景里"组织经验沉淀"的落地形式:好做法不是写 wiki,是直接做成 Agent 能执行的技能,团队谁用谁复用。
在这里插入图片描述

说明一下边界:这 38 个我这次只测了任务执行链路,技能目录没挨个跑,后续挑几个再来一篇。但目录本身就是一种态度——一个开源项目愿意把方法论沉淀成可执行资产,而不是扔一堆文档给你自己悟,这在国产开源里不多见。

八、从测评到贡献

测评里发现的两个问题,我觉得值得回馈给项目,就把流程走完了:

  1. Issue 1:Electron 和 PortableGit 两条下载链路都不遵循代理环境变量,镜像提示只覆盖了 Electron——国内污染环境首次安装基本必挂。附了完整报错和复现环境。→ mdiri-ai/SoduWork#180
  2. Issue 2 + PR:就是坑 3 那个"中断后启动死锁"。修法:rmSync 失败时把旧 runtime 改名移走再重建,别让整个准备流程崩掉。→ mdiri-ai/SoduWork#181

PR 的验证是真机做的:构造死锁现场(含 mtab 的 stale runtime + 删掉 manifest),修复前每次启动必崩;修复后脚本自己降级——

[SoduWork shell runtime] cannot remove stale runtime (EPERM); renaming it to git.stale-1794641923593
[SoduWork shell runtime] pruned 14 unused components (rev 1)
[SoduWork shell runtime] prepared: Git for Windows 2.55.0.4 (x64)

prune、post-install、selfTest 全过,manifest 正常写入,node --check 通过。→ yanweng/SoduWork PR #1

写到这里我对它的工程质量基本放心了:报错栈清晰、测试路径明确、改起来顺手。一个项目对贡献者友不友好,手感就来自这种地方。

九、总结:谁该用 SoduWork

推荐给:需要自托管 AI 协同平台的小团队;想研究多 Agent 协同工程实现的开发者(实施/审查分离的设计值得细看);对数据边界有要求、又想要产品化体验而非裸框架的企业。

亮点:开源可审计、多 harness 多模型、四场景工作流完整、断点复用的启动器、国内服务商接入齐全。

待改进(已经提给官方了):国内网络首次安装失败率高、启动中断后的重入鲁棒性。不过这两个修复成本都不高。

一个开源项目值不值得跟,star 数只是一方面,更重要的是它能不能让人从"用"走到"贡献"。这一趟我走通了全程,代码组织对贡献者是敞开的——这也是我推荐它给你的最大理由。


最后多啰嗦一句:文里贴的 issue 和 PR 链接,就是我在这个仓库留下的真实记录,你点进去就能看到它的代码质量和维护氛围。如果这篇帮你把 SoduWork 装上了,去仓库点个 Star,或者 Fork 下来自己跑一遍——比任何测评都有说服力:

更多推荐