我手上有三篇准备发到 CSDN 的技术稿,要把 Markdown 原稿、封面、正文图和 Python 示例一起交给别人审稿。接手的人只拿到一个 ZIP,换个目录解开,也能对上每篇的素材、打开正文图,照着清单跑示例。这是我这次用 SoduWork 做验收的标准。
我在家里的 Windows 电脑上建了需求,让 Pi 整理材料、打包并记录检查过程。第一次从空目录解开,三张图的文件都在,正文里却全打不开。图链修好后,另一个 Codex Agent 拿送验包重新解压,又复现了第二篇脚本把 Q3 当作金额的问题。两次检查都留了记录,脚本修订后再另存候选 ZIP 复测。

Windows 上的复现步骤
检查本机依赖
第一次跑源码前,我在准备启动 SoduWork 的 PowerShell 窗口检查依赖。本机用 Git 2.45.2、Python 3.13.9、便携版 Node.js 22.22.1 和 npm 10.9.4。用便携版 Node.js 时,把 node.exe 和 npm.cmd 所在目录加到当前窗口的 PATH,再运行下面几条命令。
git --version
py -3 --version
node --version
npm.cmd --version
克隆 Fork 并确认提交
下面以「文档」里的 SoduWorkTest 为例。源码和本次实例的数据分别放在两个目录。有现成克隆时,先看 origin、分支和 commit,确认对应的是自己的 Fork。没有克隆时执行 git clone。
我把数据目录放在仓库旁边,里面有 Hub 的数据、安装运行时和桌面配置。这样下次更新源码时还能继续用这次的账号和项目,Git 状态里也不会混进一堆安装产物。这台电脑有两套 Python,跑完预检后我又看了一眼输出里的实际解释器路径。
$RunRoot = Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'SoduWorkTest'
$SourceDir = Join-Path $RunRoot 'SoduWork'
$DataDir = Join-Path $RunRoot 'soduwork-data'
$ForkUrl = 'https://github.com/xiaosongxiaosong1111/SoduWork.git'
New-Item -ItemType Directory -Path $RunRoot -Force | Out-Null
if (-not (Test-Path -LiteralPath (Join-Path $SourceDir '.git'))) {
git clone $ForkUrl $SourceDir
if ($LASTEXITCODE -ne 0) { throw '克隆失败,先检查 Git 输出。' }
}
Set-Location -LiteralPath $SourceDir
git remote get-url origin
git status --short --branch
git rev-parse HEAD
Git reflog 记录这份 Fork 是 11 月 16 日 14:47 在本机克隆的。次日为了补拍 CMD,在另一个目录重新克隆了一次,两次的 HEAD 都是 e18b95073e324ef70710493902fa26481f7d4318。重做这几步时,记下自己实际运行的 HEAD,因为 Fork 的分支以后可能会更新。
补拍时旧实例继续运行,新实例在旁边重新建目录。看图 1 可以确认 Git 真的接收了对象、更新了文件,最后还能查到 origin 和 HEAD。图 2 和图 3 的相对路径都写成 …\soduwork-data,因此切到源码目录以后,两条命令指向同一个实例。

图 1 11 月 17 日在隔离目录重新克隆的 CMD 原图。版本检查、克隆进度、origin 和实际 commit 都在同一窗口里。
预检和正式启动
进入源码目录后先跑预检。它会列出实际使用的依赖和桌面配置目录。图 2 截的是隔离复跑那次,退出码是 0。
Set-Location -LiteralPath $SourceDir
.\start.cmd --check --desktop --data-dir $DataDir
if ($LASTEXITCODE -ne 0) { throw '启动预检未通过,先检查上方输出。' }

图 2 隔离实例的 CMD 预检原图,显示所用数据目录、端口 18990 和退出码 0。
预检通过后,保持同一个数据目录,再去掉 --check 正式启动。首次运行会装依赖、构建管理页,再启动 Hub 和桌面端。管理员密码在启动窗口里输入。保留该窗口,另外开一个终端查健康状态。
.\start.cmd --desktop --data-dir $DataDir
原来那次启动在输入管理员密码后报 Cannot inspect source checkout files。我先从同一个启动环境检查 Git,发现是它拒绝读取这份检出目录。我核对路径后,只给这次启动进程加了 safe.directory,再用原数据目录重跑。这个报错跟在密码提示后面,真正卡住的是源码目录。
下一处卡在 Electron 下载。打开数据目录里的 startup.log,能看出服务端和管理页已经走到了哪一步。这台电脑临时用了可访问的 Electron 镜像,PortableGit 归档则校验后交给启动器。11 月 17 日补拍时另用 18990 端口,源码提交一致,数据目录单独建。三稿实测用的是 11 月 16 日启动、监听 18989 的实例。
这里我没有重装整个工程。先确认日志停在桌面依赖,而不是前面的 Python 包或管理页面构建,改对应的下载来源后再从同一个入口启动。首次安装和后续启动耗时差别大,图 3 里的时长只对应这台电脑这一次,不能拿来估算另一台电脑需要多久。

图 3 正式启动的 CMD 原图。Hub 报告 SoduWork is ready,随后显示正在打开桌面端。
确认 Hub 和桌面端
看到启动成功后,我从另一个 PowerShell 窗口查 /readyz。按实际端口替换下面的地址。18989 和 18990 都返回 ready: true,数据库检查也通过。随后在 18989 对应的桌面端登录,进到项目工作区。
curl.exe --noproxy '*' -fsS -m 5 'http://127.0.0.1:18989/readyz'

图 4 三稿实测实例的 /readyz 返回已就绪。

图 5 登录后可以进入 SoduWork 桌面工作区。

图 6 「关于」窗口显示 1.13.16 和本机 Hub 地址。
图 6 记录的是三稿实测用的桌面端。启动器运行在 Python 3.13.9,独立复核随稿脚本用的是本机另一套 Python 3.13.12。
模型测试通过后对话仍然失败
模型接在已有的 New API 服务上。入口在「进入管理后台 → 能力配置 → 模型目录 → 接一个服务」。我一开始选了 Anthropic 协议,后台连接测试通过了。回到桌面端给 Pi 发消息时,界面却提示企业模型对话通道只支持 OpenAI 兼容接口。
我增加了同一服务的 OpenAI 兼容入口,然后回到 Pi 会话重新选模型。列表里出现两个同名的 deepseek-flash,要看模型名下面的供应商。图 7 打勾的那条就是后来跑三稿用的配置。
后台同样保留了旧配置,省得影响原来走那套协议的用法。对这次测评来说,真正需要确认的是 Pi 能不能用我会话里选的入口回一条消息。测试通过也只证明这一条对话通了,下面读文件和跑代码是另外检查的。

图 7 两个入口显示同一个模型名,本次选的是兼容入口。

图 8 在桌面端发出一条消息,实际收到了回复。
我手动发了一条很短的消息,让 Pi 回复「模型连接成功」。收到回复后,再去测工作区能不能读本地文件。后面如果某个项目找不到素材,就先查目录和权限,省得把两个问题混在一起。
这里我希望界面能把协议直接显示在供应商名旁边,或者在会话选中不兼容的入口时就提示。两个模型名字一样,光看选项确实容易点错。
三篇稿件怎样才算可以交接
三篇写的是领域 Embedding、RAG 数字问答和否定排除检索。每篇都有封面和随稿脚本,配图的状态不一样。第一篇已经有 PNG,正文还挂着占位。第二、第三篇只有内嵌 Mermaid。我先用素材清单确认每张封面、每个脚本对应哪一篇。
我在 SoduWork 里建了三稿项目,绑定解压后的源文件夹。派活之前先让 Pi 只读列出顶层目录。它能看到 md/、covers/、figures/、code/ 和素材清单,才把正式任务发过去。

图 9 项目指向这次的三稿素材目录。

图 10 派正式任务前,Pi 先核对目录和素材清单。
需求取名「三篇 CSDN 技术稿的图文交付与解包验收」。原稿、封面和代码作为只读输入。Pi 可以修副本里的图链。验收的人要拿一个 ZIP,从空目录解压开始走一遍。这样既能核对有没有越过改动范围,也能看出图链是否依赖原来那台电脑的目录。
原始素材的目录本来就能在我这台电脑上打开,交过去以后接手的人只有压缩包。如果预览碰巧从工作区读到了一张图,本机看着正常,别人那里还是会坏。因此验收里特意写了换到空目录,并且从 Markdown 文件所在的位置解析图片路径。

图 11 需求详情记录了任务名称、背景和验收入口。

图 12 包结构、图片引用、原稿保留、代码运行和复核记录分别验。
我把完成标准写成五项。ZIP 解得开,稿件与素材能一一对应。图片引用从解包后的 Markdown 出发能找到。原稿和原样复制的素材可用内容或哈希对照。第 02、03 篇在解包目录实际跑随稿脚本,第 01 篇只查语法。最后把通过、失败和未验证的项分别写进复核记录。
当时还约定,遇到示例报错先留下原句、文件名和退出码,原脚本随包交接。修订示例留到下一版。这样我以后翻复核记录时,能认出错误是从哪一版开始出现的。
从空目录解包才发现三条坏链

解包复核插图,由 AI 生成。
Pi 在第一篇第 58 行找到了原来的图片占位链接 ,把它改成实际图的引用。第二、第三篇各从 Mermaid 导出一份 PNG,保留原块和 .mmd 源,再把导出的图放进对应正文。

图 13 第一篇的占位链接在首次检查时就被标出来了。

图 14 第二、第三篇的流程图被导出为可打开的文件。
第一版把 Markdown 放进 md/,图放进 figures/,正文却写成 figures/01-system-lineage.png。预览器从 md/ 出发找这个地址,于是跑到了不存在的 md/figures/。另外两篇也用了同样的写法。ZIP 能正常解开,到空目录里检查正文时,三条引用全错。
这一步我单独查了 Markdown 的链接基准。文件名本身和目录结构都对,只是写链接的人把目录基准想成了 ZIP 的根。交接时只打开资源管理器看附件数,或者只看到 Pi 回复打包完成,都很难发现这一类问题。
稿件位置 md/01-domain-embedding-finetune.md
首轮引用 figures/01-system-lineage.png
实际查找 md/figures/01-system-lineage.png
修正引用 ../figures/01-system-lineage.png
Pi 把三条路径改成 …/figures/…,更新清单,再重新打包。第二次还是换个空目录解压,沿每篇稿件的相对路径打开对应的图,三条都能解析到包内。

图 15 问题在解包后暴露,修正路径后重新打包。

图 16 再次核对稿件的改动范围和包结构。

图 17 流程图预览和代码检查记录。解包后另用图像库读取包内 PNG。
第 01 篇替换一处占位,第 02、03 篇各增加一处图片引用并调整相邻空行。把这几处差异还原,三份 Markdown 与输入逐字节一致。三块 Mermaid 也都保留。作者回看差异时,可以直接找到改的那几行。
PNG 可以直接在图片查看器里打开,.mmd 留给下次需要改流程的人。第二、第三篇导出时,Pi 查了图里的节点和像素内容。独立复核从包里再读 PNG,并把 .mmd 与原稿的 Mermaid 块逐一对应。
最后包里有 16 个文件,三篇 Markdown、三张封面、三张正文 PNG、三份 Mermaid 源、三份 Python 和根目录的交付清单。清单按稿件把材料列在一起,接手的人不用再翻执行会话对文件名。
三个 PNG 正文图和 Mermaid 源分开放。独立复核还检查了 ZIP 解压后每个图实际可读,而不是靠文件后缀判断。用于复核的命令、哈希和失败记录在包外另存,还可以回看是哪一步发现了问题。
独立复核跑出了季度标签错误
Pi 自查完,我另外请一个 Codex Agent 取送验 ZIP,在新建的空目录解包。复核方记录了哈希,检查了全部 16 个成员的 CRC,用 Windows 图像库读取了 6 张 PNG,也逐条验证了图链。封面、随稿代码和已有流程图与原输入进行过字节比对。

图 18 交付清单和过程材料可以一起查。
用 Python 分别检查三份随稿文件时,结果如下。第 01 篇的检查范围只到语法,第 03 篇入口顺序调用了四组自测。
| 随稿文件 | 送验结果 | 实际输出 |
|---|---|---|
01-triple-build.py | 语法检查退出 0 | syntax OK |
02-parse.py | 自测退出 1 | ParseError: 数字缺单位: '3 ' |
03-negation-selfcheck.py | 四组自测退出 0 | negation selfchecks ok |
第 02 篇要解析「华东区 Q3 营业收入 8.7 亿元」。正则从左往右读,先吃到了 Q3 里的 3,后面找不到单位,第一条自测就退出来了。只传 8.7 亿元时能解析。用送验包重新解开再跑,仍能重现这条报错,原脚本和失败记录都留到了下一版复测。
当时我把自测失败写进验收记录,没有为了交付状态好看就改成通过。前面检查的 CRC、文件哈希和图片读取都正常,所以这个 ZIP 可以先交接给审稿的人。第 02 篇要发出去,仍得先把会报错的示例修掉,再交新包复测。

图 19 Pi 会话里记录了第 02 篇的异常,另一位复核者随后独立解包复现。
这次留下了每条命令的退出码和失败原句。三份文件都在 ZIP 里,真正运行后才知道哪一份还有问题。
Pi 在 Windows 上还碰到过字符编码报错。切到 UTF-8 后,季度标签的异常依然能复现。独立复核也用 UTF-8 模式跑,排除了终端编码的影响。第 01 篇只检查了文件语法,训练流程和效果都没有跑。
补交清单后进入待验收
送验前,平台又卡了一次。SoduWork 把清单里的示例 evidence/placeholder 当成实际依赖,找不到就没能完成交付登记。Pi 把旧示例改写成普通说明,在 .soduwork/delivery.json 里把 ZIP 登记为主交付件,执行与复核报告作为过程材料单列。

图 20 补交时核对 ZIP 的成员、哈希和清单。
补交前后核对了 16 个 ZIP 成员,只有根目录的交付清单发生变化。平台固定文件校验通过,需求进入「待验收」。这个状态下能下载已登记的 ZIP,最终签收还要由作者在需求池确认。
图 21 可以看到待验收的固定版本和下载入口。复跑的判断依据另外留在报告中。我还没有把需求点成「已完成」。

图 21 平台登记的是 11 月 16 日送验包。

图 22 送验任务停在「待验收」。
我喜欢在需求详情里直接查固定版本,比在会话里翻最后一条 ZIP 消息省事。不过导出的验收摘要缺少实际 Agent 和模型。Pi 与 deepseek-flash 要回到会话才能核对。我希望以后导出时一并带上这两项,方便把运行记录和交付包对起来。
我把执行记录、独立复核记录和两个阶段的 ZIP 哈希一并留了下来。后续只拿到一个包时,先比哈希就知道该看哪次记录。
修完脚本再跑同一条用例
11 月 17 日,我让 Codex 把第 02 篇的修订另存成候选版。解析器现在先识别 Q1 到 Q4,再取后面的金额。同一句「华东区 Q3 营业收入 8.7 亿元」跑出了 870000000 元。如果第一笔实际金额缺单位,代码仍然报错,以免顺手拿了后面另一笔金额。
第 02 篇还用 8.7 亿元和 87,432 万元算同比。把 8.7 和 87,432 直接当同单位,约是 −99.99%。换算为 870,000,000 元和 874,320,000 元后,本期除以基期再减 1,约是 −0.49%。候选版也实测拒绝错季、累计口径、期间重叠、零基期和负基期。

图 23 11 月 17 日候选包的哈希和改动记录。
候选 ZIP 解开后还是 16 个文件。变化集中在第 02 篇正文、随稿脚本和清单,另外 13 个成员逐字节相同。三条图链和三段 Mermaid 重新核验,正文 14 段 Python 代码通过语法检查。三个随稿检查退出码都是 0,其中第 01 篇仍只查语法,第 02、03 篇跑了自测。
复测里还从第 02 篇正文提取了同比和指标示例,检查文本里的代码与随稿脚本有没有分叉。用四条构造数据分别覆盖答对、拒答、答错口径和算错数值几种情况。这些比例是用来对照指标算法的,不能当成产品或模型的准确率。
这遍仍在空目录里解包重跑,避免改好了工作区,却把旧脚本留在 ZIP 里。图 21 是平台上待签收的 11 月 16 日送验包,图 23 和图 24 是隔天的候选包及其运行记录。两份 ZIP 的校验值不同,代码通过的是候选包。

图 24 第 02 篇自测通过,复测记录保留了原单位和归一后结果。
需求池里能直接回查哪份 ZIP 在等人签收,这一点适合做稿件交接。首次安装时找日志、切模型时认供应商、交付时检查清单里有没有被当成真链接的示例,都是这次实际花工夫的地方。
对我来说,最值钱的两步都发生在压缩包生成以后。一遍按正文里的路径找图,另一遍按清单跑示例。坏图链和 Q3 报错分别在这两步被抓到。下次交稿我会把这两个动作直接写进需求,拿到 ZIP 当场检查,也方便作者根据证据决定签收还是返修。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/qq_50684356/article/details/170926387




