SoduWork 上手实测,本地跑通 Hub、桌面端和第一个对话

前言

动手之前我先在官网下了一次 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。
第三步 验证
  1. 桌面端底部模型选择器里能看到刚配的模型。
  2. 发一条消息,能返回内容就说明链路打通。
  3. 可选做法是管理页 → 模型目录 → 对该模型跑一次"能力检测",测连通性、图片输入、工具调用和流式。

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项目,尝试一下!

参考来源。

相关推荐
江湖有缘4 天前
基于Ubuntu部署SoduWork:企业级 AI 原生协同平台实战全流程
linux·人工智能·ubuntu·ai·soduwork
阿Q说代码4 天前
SoduWork 上手体验:把 Codex、Claude Code 等 AI Agent 放进一个工作平台
ai·agent·soduwork