前言
动手之前我先在官网下了一次 Windows 安装包。安装向导走完,桌面多出一个客户端图标,我以为这就齐了。客户端一打开就要填服务地址,而这个地址得自己跑起来才有。
官网那份下载教程停在下载和安装这一步,后面本地 Hub 怎么起没写。我是在客户端连不上、又翻了仓库 README 之后才反应过来的,前面白白折腾了十来分钟。
后来干脆不猜了,把仓库拉下来跑。Fork 一次,Clone 到本地,在源码目录里执行
start-desktop.cmd,Hub、管理页和桌面端一起起来,一次到位。本地这条路子省掉了官网客户端单独装、Hub 单独起、再手动填地址这几步,也不用先啃文档。这篇按我实际走过的顺序写。三种获取方式各自适合谁,第一次启动要填什么,模型服务怎么配,桌面端怎么用自己加的模型跑通第一句话。最后我拿一份 30 行的销售 CSV 做了件真事,让 Agent 交付一个 Excel 工作簿,再用 openpyxl 独立核对了一遍,没直接采信它自己说的"已通过校验"。
环境是 Windows 10 Education 22H2、Python 3.12.8、Node.js 22.19.0,源码停在
main @ ee7771a(2026-11-17)。哪些环节我实际验过、哪些没验,文中都标了出来。
1. 环境与版本
| 项目 | 本机版本 |
|---|---|
| 操作系统 | Windows 10 Education 22H2,10.0.19045,Build 19045.6456 |
| Python | 3.12.8 |
| Node.js | 22.19.0 |
| npm | 10.9.3 |
| SoduWork 源码 | main @ ee7771a(2026-11-17) |
| SoduWork client | 1.13.17 |
| 实测方式 | Fork + Clone 自己的仓库,在本地源码目录运行 start-desktop.cmd |
本机有一处例外情况。Electron 44.9.3 在这台机器的默认沙箱下启动失败,退出码 2147483651,额外加上 --no-sandbox 才打开桌面端。这是我这台机器的兼容性处理,不是项目推荐配置,普通环境按下面步骤走就行。
2. 安装两个依赖,Python 3.12+ 与 Node.js 22.19+
SoduWork 启动器只要求两个运行时。
| 依赖 | 官方地址 | 版本要求 |
|---|---|---|
| Python | https://www.python.org/downloads/ | 3.12+ |
| Node.js | https://nodejs.org/ | 22.19+ |
Windows 装 Python 时记得勾选 Add Python to PATH,Node.js 保留默认安装选项,npm 会一起装上。装完关掉旧终端,重新开一个。
装完先校验版本,不满足就别往下走。
Plaintext
python --version
Python 3.12.8
node --version
v22.19.0
npm --version
10.9.3

3. 三种获取方式,官网安装包、Clone、ZIP
| 方式 | 是什么 | 适合 | 本次是否实测 |
|---|---|---|---|
| 官网安装包 | 只有桌面客户端,不含本地 Hub | 已有一个可连接的 Hub,或只想装客户端 | 已下载并运行安装向导 |
Fork + Clone + start-desktop.cmd |
一步启动 Hub、管理页和桌面端 | 本地完整体验、开发、贡献 | 已实测 |
| ZIP | 下载源码压缩包,解压后没有 .git |
只想快速体验源码,不想装 Git | 未实测 |
3.1 官网下载客户端(仅客户端,不含 Hub)
官网 https://soduwork.mdiri.com/ ,官方安装教程 https://soduwork.mdiri.com/tutorials/download-and-install ,给的步骤停在下载和安装这一步。
Plaintext
1. 打开官网,点击页面顶部的"立即下载"
2. Windows 选择 Windows 安装包
3. macOS 根据芯片选择 Apple Silicon 或 Intel
4. Linux 根据系统选择 deb、rpm 或 tar.gz
5. 下载窗口会显示当前版本与文件大小,以窗口中的实际信息为准
2026-11-18 我查了一次官网的下载配置,各平台包信息如下。
| 平台 | 安装包 | 版本 | 大小 |
|---|---|---|---|
| Windows | SoduWork-1.13.17-Setup.exe |
1.13.17 | 约 379.6 MB |
| macOS | dmg | 1.13.17 | 约 289.3 MB |
| Linux | deb / rpm / tar.gz | 1.13.17 | 约 206.8 MB 到 231.6 MB |
Windows 上实际安装时,SmartScreen 会提示"Windows 已保护你的电脑",发布者显示"未知",要点"更多信息",再点"仍要运行"。

安装向导会要求选择安装位置,本次选了 D:\Soft\Soduwork,所需空间约 1.0 GB。

关键区别在于官网安装包只是桌面客户端,里面没有本地 Hub。装完之后客户端仍然需要一个能连上的服务地址。两种用法。
- 想一步到位,直接用源码方式的
start-desktop.cmd,它同时启动 Hub 和桌面端。 - 已经装了官网客户端,可以只运行
start.cmd启动本地 Hub 或网关,再让客户端连http://127.0.0.1:18989。
这次我实际下载并运行了安装向导,安装后的客户端与 Hub 的联调截图仍以源码模式为主。
3.2 Fork + Clone + start-desktop.cmd(推荐,一步到位)
只是体验源码的话,Clone 官方仓库就够了。
Plaintext
git clone https://github.com/mdiri-ai/SoduWork.git
cd SoduWork
准备提 Issue 或 PR,先 Fork,再 Clone 自己的仓库。
Plaintext
git clone https://github.com/<你的GitHub用户名>/SoduWork.git
cd SoduWork
这次实测用的是我自己的 Fork,这里只说明来源。
3.3 ZIP 方式
ZIP 和 Clone 拿到的源码内容一致,start-desktop.cmd 都能跑。区别在 ZIP 解压后没有 .git,不能直接提交代码,而 Clone 有 .git,启动器也会检查有没有没做完的 rebase、merge 或 cherry-pick。
Plaintext
# 在 GitHub 仓库页面选择 Code → Download ZIP
# 解压后进入包含 README.md、start.py、client 的目录

4. 第一次启动,本地入口用 start-desktop.cmd
本地完整体验就用 start-desktop.cmd。它实际调用 start.cmd --desktop,一次把 Hub、管理页和 Electron 桌面端都拉起来,不用先装官网客户端,也不用分别启动网关和客户端。
已经装了官网客户端的话,只运行 start.cmd 启动本地 Hub 或网关,再让客户端连 http://127.0.0.1:18989 也行,本文走的是 --desktop 这条一步到位的路子。
在源码目录执行。
Plaintext
start-desktop.cmd
首次启动会设置 admin 密码,要输入两次,长度 12 到 128 个字符。启动器随后自动装齐 Python 依赖、npm 包和 Electron,首次需要联网,耗时看网络,之后启动会复用已装好的内容。

5. 管理页登录
浏览器打开 http://127.0.0.1:18989,点"进入管理后台",用 admin 和刚设的密码登录。

登录后是管理页总览,能看到"服务运行正常"和当前组织信息。

这一步说明三件事都过了,Hub 已经起来,SQLite 数据库初始化完成,浏览器管理端和 Hub 也连上了。
5.1 在 Hub 里配置模型服务
Hub 本身不带内置模型。桌面端底部输入区的模型选择器,读的是管理页的模型目录里配置的内容。
没配模型就直接发消息会失败,所以这一步要在桌面端上手之前完成。
准备三样东西。
| 项目 | 说明 | 示例 |
|---|---|---|
| 接口地址 | OpenAI 兼容的 baseURL | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| API Key | 对应平台的密钥 | sk-xxxx |
| 模型名 | 必须与网关实际接受的名字完全一致 | deepseek-v4.1-flash-1017 |
第一步 接一个模型服务
管理页 → 能力配置 → 模型目录 → 右上角"接一个服务",填四项。
- 名称可自取,例如"我的网关"
- 类型选 OpenAI 兼容
- 地址填 baseURL
- 密钥填 API Key
保存后,服务会出现在服务商列表里。
第二步 让模型出现在清单里
- 服务支持自动发现,点"发现模型"自动拉取。
- 不支持就手动"添加模型",填模型 ID,必须和网关实际接受的名字一致,多一个前缀都可能 404。

第三步 验证
- 桌面端底部模型选择器里能看到刚配的模型。
- 发一条消息,能返回内容就说明链路打通。
- 可选做法是管理页 → 模型目录 → 对该模型跑一次"能力检测",测连通性、图片输入、工具调用和流式。

6. 桌面端上手,登录、主界面、第一条消息
源码方式下,start-desktop.cmd 完成 [Desktop] 阶段后会自动打开 Electron 桌面窗口,不用另外下载官网安装包。
6.1 用 admin 登录
桌面端首次打开是登录页,账号 admin,密码是第一次启动时设的那个。桌面端和管理页共用同一个本地账号。

6.2 主界面结构
登录后进主界面,三块地方分得很开。
- 左侧导航,新对话、项目、最近聊天
- 中间会话区,首次进入显示"想让 SoduWork 做什么?"
- 底部输入区,模型选择、工作区、执行底座、发送按钮

6.3 确认模型和底座
底部输入区右侧显示当前模型和底座。
Plaintext
deepseek-v4.1-flash-1017 [Pi]
左边是模型名,来自管理页模型目录里手动添加的模型。右边 Pi 是默认执行底座,点它可以打开"选择执行底座"。
6.4 发送第一条消息
点底部输入框,输入"你好",按回车或点发送按钮。约 3 秒后回来这么一句。
你好!有什么可以帮你的吗? 无论是聊思路、查资料,还是需要我动手处理文件、写代码、做表格文档,都可以直接说。

这张截图里任务输入、执行过程和最终结果都在,输入框是"你好",回复上方显示 Pi 图标和用时,正文是模型返回的内容。
7. 补充,执行底座可以换成自己喜欢的 Agent
SoduWork 默认用 Pi,执行底座并不固定。桌面端底部的"选择执行底座"里能看到多个 Agent,本机显示的是这样。
- Pi,默认选中,界面显示"可以派活"
- DeepSeek Harness,界面显示"可以派活"
- Codex、Codex Harness、Kimi Code、OpenCode,界面显示"未安装",可按需安装


这部分只作补充说明。你可以按自己的习惯挑一个 Agent 执行任务,不必只用 Pi。这次我实际只用了 Pi,DeepSeek Harness 等其他底座没有切换执行,所以不对它们的实际表现下结论。
8. 实测,把一份 30 行 CSV 交付成可复核的 Excel 工作簿
前面那句"你好"只证明模型链路通了。这一节换成一件真实工作。我给 Agent 一份 30 行的销售 CSV,要求交付一个带质量清单、公式可复核的 Excel 工作簿。
8.1 任务
在桌面端新对话里挂载 sales_2026_q3(1.3 KB,30 行,7 列),输入下面这段。
Plaintext
请分析我上传的 sales_2026_q3.csv(2026 年 7 月销售数据),交付一个 Excel 工作簿,要求:
1. 先做数据质量检查:缺失值、文本型数字、区域命名不一致、异常值、日期格式混用;把发现的问题列成清单,不要擅自补造数值。
2. 给出指标口径说明(线索数、成交数、销售额、客单价如何定义,客单价怎么计算)。
3. 清洗后的数据单独放一个 sheet,原始数据保留一个 sheet 以便追溯。
4. 按区域和渠道做汇总透视,并画 1--2 个图表。
5. 给出结论,并单列一条"数据质量问题清单"。
6. 客单价为 0 且成交数为 0 的行按无效记录处理,并在说明中注明。
这条提示词把交付形态写死了,质量清单、口径说明、原始数据留档、图表、无效记录标注,一项都不能少。

8.2 执行过程
对话里能看到 Agent 的动作,不会只剩一个"思考中"。

截图里依次出现"运行了命令 2 项""深度思考",然后继续往下推进。整轮用时 12 分 34 秒,不是按一下回车就出结果的那种问答。
8.3 交付结果
最终交付一个 sales_2026_q3_分析工作簿.xlsx,6 个工作表。
| Sheet | 内容 |
|---|---|
00_说明与口径 |
指标定义、清洗规则、无效记录说明 |
01_结论 |
总体/区域/渠道结论 + 行动建议 |
02_数据质量问题清单 |
18 条,含严重程度、原始行号、原始值、处理方式、是否补造数值 |
03_清洗后数据 |
保留原值/新值对照、清洗动作、问题标记、纳入汇总开关 |
04_汇总透视 |
区域表、渠道表、交叉表,全部公式;2 张图表 |
05_原始数据 |
源 CSV 原样留档 |

工作簿给出的核心结论是,剔除 1 条无效记录后 29 条纳入汇总,线索 2140 条、成交 296 单、销售额 548,400 元、加权客单价 1690 元每单、线索到成交的转化率 13.8%。
清洗表把每一处改动都摊开了,勾稽列直接标"一致 / 不一致 / 无法校验",全零行标"整行判定为无效"。

8.4 我自己做的独立核对
它自己说"已通过校验",我没全信,用 openpyxl 打开工作簿重新查了一遍。最后的数据都可以对上
| 核对项 | 结果 |
|---|---|
| 工作表数量 | 6 个,命名与截图一致 |
| 汇总表是否真公式 | 141 个公式(COUNTIFS / SUMIFS / SUMPRODUCT),不是写死的数字 |
| 图表 | 包内 2 个 chart 部件 + 1 个 drawing |
| 质量清单条数 | 18 条(16 条数据问题 + 2 条口径提示) |
| 原始数据 | 30 行、7 列、UTF-8 BOM,与源文件一致 |
| 工作区遗留 | analyze_sales.py(61,809 字节)、verify_sales.py(19,953 字节) |
CSV 里的缺陷我另外数了一遍,跟清单能对上,日期格式混用 1 处、区域命名不一致 4 处、文本型金额 2 处、整行缺失 3 处、离群值 1 处(线索数 9999)、全零无效行 1 处、客单价勾稽不一致 3 处。
8.5 这次实测说明什么
这一轮真正验到的有五点。
- 交付的是文件,6 个 sheet、2 张图表、一份原始数据留档都在。
- 汇总层写的是公式,改清洗表能重算。
- 数据缺陷列成 18 条清单,每条标了是否补造数值,没有偷偷填数。
- 无效记录按我给的规则单独处理,说明里也注明了。
- 整轮 12 分 34 秒,中间有命令执行和深度思考。
9. 边界与参考来源
- 本文验证的是 Fork + Clone +
start-desktop.cmd的本地源码方式,一次启动 Hub、管理页和桌面端。 - 官网安装包是纯桌面客户端,不含本地 Hub。这次实际下载并运行了安装向导,但没用它做完整对话联调。
- 只要客户端的话,先运行
start.cmd启动本地 Hub,再让官网客户端连http://127.0.0.1:18989;或者直接start-desktop.cmd一步到位。 start.cmd是服务器或仅管理端的入口,本文不把它当本地桌面端主路径。- ZIP 方式这次没有重新下载验证,源码内容与 Clone 一致,教程里保留为可选方式。
- 本机 Electron 44.9.3 默认沙箱启动失败,加上
--no-sandbox后完成桌面端截图。这是单机环境处理,不代表项目默认配置。 - 模型
deepseek-v4.1-flash-1017是手动添加的,不是内置模型。 - 执行底座默认 Pi,DeepSeek Harness 等在界面上可见但没有实际切换执行。
- 第 8 节是真实执行记录,工作簿数据由我用 openpyxl 独立核对,没有直接采信 Agent 自述。
- 曾尝试准备插件,未成功,插件相关内容不在本文范围。
快来fork项目,尝试一下!
参考来源。