先交代一下背景。我之前用 ZCode 做开发辅助后来切到了 DeepSeek Harness再配合 GitHub Actions 把 Windows 打包整个自动化了。整个过程大概花了两个晚上中间踩的坑不少但最终跑通的那一刻确实挺值。这篇文章就把完整过程、配置文件、踩坑记录都写出来给正在纠结要不要迁移的朋友一个参考。我做的项目是一个偏内部的 Windows 桌面工具Python PySide6 写的要分发到同事的机器上所以打包 exe 是刚需。开发阶段我用 ZCode 补代码、写测试、解释报错效率确实高。但用着用着心里开始不踏实。ZCode 是云端化的服务代码、依赖清单、项目结构都要发出去才能给出建议团队里一些核心模块我实在不敢交出去。后来我把辅助开发的工作流整体迁到了 DeepSeek Harness也顺手把 Windows 打包流水线搬到了 GitHub Actions 上自建。这一套组合拳下来开发效率和发布效率都没降隐私和可控性反而提高了不少。1. 先说结论为什么我把 ZCode 换成了 DeepSeek Harness1.1 ZCode 真正让我放弃的不是功能而是不可控ZCode 用起来其实很顺手尤其是在自动补全和上下文理解上处理多文件项目的时候能省很多事。它支持 skill可以自定义一些提示词甚至能接入 DeepSeek 之类的模型。如果你是一个人做开源项目、写点不敏感的脚本它完全够用我甚至觉得它比很多同类工具体验都好。真正让我下定决心换掉的是它的运行模式。ZCode 的处理链路是在云端完成的这意味着你的代码片段、项目结构、甚至一些未提交的注释都会进入它的服务端上下文。社区里陆续有人讨论过代码外传这件事不管最终结论是什么对我来说有一点是确定的我无法为商业项目里的核心代码承担这个不确定性。我不想某天被问为什么一个内部模块的命名风格出现在了外部服务日志里的时候只能回答不知道。另外一个现实问题是审计和权限。我在团队里用的是演示账号没有细粒度的权限收敛也没有可导出的操作日志。一旦多人同时用谁在什么时间把哪段代码提交给了外部服务完全是无感知的。对于个人开发者这可能无所谓但对于任何需要交付给客户的项目这个漏洞就是合规风险。ZCode 不是不好而是不可控。它是个黑盒而我需要的是一个我能查日志、能改配置、能决定数据往哪走的方案。1.2 我对 DeepSeek Harness 的核心需求清单决定迁移之前我列了一份需求清单不是说哪个工具热门就换哪个而是先想清楚我到底要什么需求说明为什么重要本地化部署核心代码和对话上下文不出本机消除代码外传风险同时支持断网使用模型可切换既能连本地模型也能在必要时走云端大模型 API平衡效果和隐私本地模型不够强时能有兜底多智能体编排规划、编码、评审分成不同角色而不是一个对话从头聊到尾更适合复杂任务拆解减少遗漏Skill 机制把窗口期经验固化成可复用的技能文件让 AI 不止会聊天还会按照我的打包规范来干活与 CI/CD 打通能生成工作流配置、能检查构建产物让 AI 辅助真正落到交付环节拿这份清单去对比DeepSeek Harness 是目前比较贴合的一个方案。它不是单纯的一个AI 对话工具而是更接近一个本地运行的智能体编排框架可以把任务拆给不同角色每个角色有独立的上下文和输出规则。而且它的配置是纯文本的所有东西都放在项目里能进 Git能审计也能随时改。提示我在下面写的安装路径和配置结构是以我当时拉取的某个版本为例。这工具迭代很快不同版本的命令和目录结构差异很大建议以仓库 README 为准把下文当成思路参考别当成固定答案。2. DeepSeek Harness 本地化部署与多智能体编排2.1 安装和最小配置从零到能跑通本地模型我的环境是 Windows 11 专业版Python 3.11。Harness 本身是个 Python 项目所以安装思路很简单git clone https://github.com/yourorg/deepseek-harness.git cd deepseek-harness python -m venv .venv .venv\Scripts\activate pip install -e . harness --version这里有两个细节值得说。第一我坚持用虚拟环境而不是直接装到全局 Python因为这个工具依赖的包版本比较激进直接装全局很容易把其他项目的依赖顶掉。第二在 Windows PowerShell 下手动激活虚拟环境之后如果执行harness提示无法加载先检查一下执行策略我当时是用管理员 PowerShell 执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser解决的。最小配置文件我放在项目根目录的harness.yaml里长这样model: provider: local endpoint: http://127.0.0.1:11434 model_name: deepseek-r1:14b thinking_mode: true temperature: 0.2 workspace: root: ./ ignore: - .git - dist - build - __pycache__先解释一下endpoint和model_name。本地部署我选的是 Ollama 作为模型运行时默认监听 11434 端口。thinking_mode: true是推理模型的一个重要开关开启之后 Harness 会让模型先生成内部的推理链再输出最终答案。这个模式对代码审阅和打包脚本调试特别有用因为你能看到它是怎么一步步得出结论的而不是直接甩给你一个结果。temperature: 0.2也是我专门调的。默认值是 0.7但生成构建脚本这种任务我更希望它是稳定、可复现的而不是天马行空。温度越低输出随机性越小适合这种工程任务。如果你让它做头脑风暴可以调回 0.7 以上我自己是习惯在写代码和写文档时用两套配置。配置好之后我先跑了一个最简单的测试任务harness run 读取当前项目下的 requirements.txt列出所有顶层依赖第一次跑就遇到一个问题Harness 连不上本地模型。排查了一下不是端口的问题而是 Ollama 默认只监听本机回环地址但 Harness 在某些版本里会用localhost解析成 IPv6 的::1两边没对上。我在 Ollama 的环境变量里加了一行OLLAMA_HOST127.0.0.1重启服务就通了。这个坑很小但能卡你半小时先写出来。2.2 多智能体编排planner、coder、reviewer 怎么配合Harness 最吸引我的点是它能跑多个智能体而且彼此之间有明确的分工。我第一次用的时候只把它当升级版聊天框后来发现完全不是一回事。我配置了三个角色agents: planner: prompt: | 你是项目规划者。接到任务后先拆解实现步骤输出计划不写具体代码。 计划中必须包含改动文件列表、每个文件的职责、验证方式。 coder: prompt: | 你是编码者。根据 planner 输出的计划写代码。 遵守项目现有代码风格不重构无关代码每段代码都要有简短注释。 reviewer: prompt: | 你是代码审查者。检查 coder 产出的代码关注以下问题 1. 是否有明显 bug 或边界问题 2. 是否引入了未使用的依赖 3. 是否符合项目风格 发现问题直接返回给 coder 修改最多迭代 3 轮。调用方式类似这样harness run --agent planner 我有一个 PySide6 应用入口在 app/main.py需要打包成单文件 exe请给出执行计划planner 会先输出一份计划确认之后我再交给 coder 执行harness run --agent coder --context 参考 planner 的计划生成一个 PyInstaller 的 spec 文件这里最需要注意的是工作目录权限问题。因为多个智能体都会读写项目文件我强烈建议把harness.yaml的workspace.ignore写好把dist、build、.git全排除掉避免 AI 在检查代码的时候误读构建产物甚至把二进制文件当成文本加载。我第一次跑的时候没配 ignorereviewer 直接去读了一个 200MB 的 exe 文件卡了十几分钟。多智能体不一定每次都用。小任务比如帮我解释这个报错直接用默认单 agent 就行开全套反而慢。我自己的经验是任务涉及三个以上文件改动、或者需要多步骤验证的时候才值得启动完整编排。简单任务就别为了仪式感上重武器了。2.3 Skills 和插件把打包经验变成可复用技能如果说多智能体解决的是分工问题那 Skills 解决的就是经验固化问题。Harness 的 Skill 机制跟一些编码工具里的技能包思路类似一份 Markdown 文件里面写清楚这个技能适用的场景、操作步骤、注意事项。模型在运行时会读取这份文件按照里面的约束来执行。比如我给自己常用的打包流程做了一个 skill文件路径skills/pyinstaller-windows/SKILL.md--- name: pyinstaller-windows description: 将 Python 桌面应用打包为 Windows 单文件 exe --- ## 适用场景 - 项目是 PySide6 / PyQt 桌面应用 - 用户希望输出一个可双击运行的单文件 exe ## 执行步骤 1. 检查入口文件是否存在确认 __main__.py 或显式入口 2. 用 PyInstaller 生成 specpyinstaller --onefile --windowed --name AppName 3. 检查 spec 中的 hiddenimports确认是否包含 PySide6 全部模块 4. 手动执行一次构建验证 dist 目录下 exe 能否启动 5. 如果 exe 体积超过预期排查是否需要排除模块 ## 常见问题 - exe 启动后闪退多半是缺动态库或 hiddenimports 不完整 - exe 被杀毒软件误报建议签名或改用 onedir 模式有了这个 skill 之后我再跑打包任务就可以直接指定harness run --skill pyinstaller-windows 把这个项目打包成单文件 exeHarness 会先读 SKILL.md按里面的步骤执行而不是凭模型自己的印象瞎猜。这个价值很大因为模型有时候会一本正经地给你编造打包步骤装上 skill 之后它就等于是按照你沉淀下来的流程在走。Skills 的编写有个原则不要太长不要写成文档。每个 skill 控制在 30 到 50 行重点写清楚触发条件、关键参数、常见问题。它就是给模型看的操作备忘不是知识库越精炼越好用。2.4 版本回退为什么我从新版本退回 v0.1.5-rc.2用 Harness 大概一周后我升级了一次。升级完发现一个很别扭的变化输出格式改了原本在终端里直接打印结构化计划新版本默认变成了类 JSON 的流式输出看起来是面向二次开发的但对命令行用户非常不友好。更要命的是旧版本里能用的某个内建 skill在新版本里被标记为 deprecated触发方式也变了我现有的自动化脚本全都不兼容。我个人的风格是AI 辅助工具的作用是提升效率不是让我去追新版本。所以当时就决定退回 v0.1.5-rc.2等大版本稳定了再升。回退操作其实很简单git tag git checkout v0.1.5-rc.2 pip install -e .这里唯一要提醒的是回退之后配置文件的 schema 也可能对应变化。如果启动报配置解析错误去看对应 tag 下的config.example.yaml把新字段删掉即可。我还顺便把当前版本号写进了项目的 CONTRIBUTING 文档里避免团队成员误用新版本命令导致脚本失效。版本回退这个操作本身不值得夸耀但它提醒了我一件事底层工具要选可控的升级策略也要自己定不能让上游的节奏绑架你的交付计划。3. 用 GitHub Actions 自建 Windows 打包流水线3.1 为什么不自建 Windows 打包机而是用 GitHub Actions本地打包最大的问题是不稳定。我自己的开发机装了一大堆 Python 包、Node 环境、各种运行库PyInstaller 在打包的时候会把当前环境里的气味都吸进去结果就是我本机打出来的 exe 能跑换到同事的干净机器上就报缺 DLL。真实原因是打包环境不干净带入了不必要的依赖同时漏掉了真正需要的动态库。GitHub Actions 的windows-latest跑起来是一个临时分配的干净 Windows Server 环境每次构建从零开始。这有两个好处第一可复现性极强你今天打包的结果和三个月后打包的结果行为一致第二触发方式灵活我可以只在打 tag 的时候自动构建也可以手动触发还可以在 PR 阶段先跑一个测试构建确保代码改动没有破坏打包链路。成本也要说一句。GitHub Actions 对公共仓库免费私有仓库每个月有免费额度对小型项目来说基本够用。一次 Windows 构建大概消耗 10 到 20 分钟额度你按自己的月构建次数算一下就清楚。相比自己养一台 Windows 构建机这个成本可以忽略。3.2 完整 workflow 拆分从检出代码到产出单文件 exe我最开始写的 workflow 比较简单只做了一件事拉代码、装依赖、跑打包。后来随着项目变大慢慢加上了缓存、测试、自动创建 Release。完整内容如下你可以直接抄name: build-windows-exe on: push: tags: - v* workflow_dispatch: jobs: build: runs-on: windows-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Cache pip uses: actions/cachev4 with: path: ~\AppData\Local\pip\Cache key: ${{ runner.os }}-pip-${{ hashFiles(requirements.txt) }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install pyinstaller - name: Run tests run: python -m pytest tests - name: Build exe with PyInstaller run: | pyinstaller --noconfirm --clean --onefile --windowed --name AppName --icon assets/app.ico app/main.py - name: Upload artifact uses: actions/upload-artifactv4 with: name: AppName-windows-x64 path: dist/AppName.exe重点关注几个步骤。actions/setup-pythonv5会帮你装好指定版本的 Python 并把 PATH 配好这是后面一切的前提。Cache pip这步很关键因为 Windows Runner 每次都是新机器不缓存的话每次都要重新下载 torch、numpy 这类几百 MB 的包构建时间能差一倍以上。缓存路径~\AppData\Local\pip\Cache是 pip 在 Windows 上的默认缓存目录hashFiles(requirements.txt)确保依赖变化的时候缓存自动失效。Run tests这步是你打包质量的保险丝。我见过很多项目删掉这步因为打包而已跑什么测试。但我实际经历是有一次某个版本更新引入了 bug但打包依然成功直到同事运行 exe 才发现问题。如果当时打包前跑一遍测试这个问题在 CI 里就能拦下来。测试不通过的代码不应该进入发布流程。Upload artifact这步产生的是原始构建产物也就是一个裸的 exe。我一般会再配置一个自动化 Release 的步骤把产物挂到 tag 对应的 Release 页面。这一步不是必须的但你如果每次都要去 Artifacts 页面下载会很烦。3.3 打包参数怎么选onefile、windowed、图标和版本信息PyInstaller 的参数看起来简单实际坑不少。我先把最常用的几个参数选择逻辑说清楚。--onefile和--onedir的选择。onefile 最终产出一个独立的 exe用户下载即用不用解压体验最好但启动速度稍慢因为每次运行都要把内部文件解压到临时目录。onedir 模式产出一个文件夹里面有很多依赖文件启动快但分发和更新都更麻烦。对于给同事用的内部工具我推荐 onefile因为双击就能用这个体验能省掉大量技术支持。如果后期发现杀毒软件对 onefile 误报严重再切回 onedir 并配合压缩包分发。--windowed这个参数决定了程序是否带控制台窗口。PySide6 是 GUI 应用必须加这个参数否则用户启动 exe 的时候还会弹出一个黑色的命令行窗口很掉价。但调试的时候要注意加了 windowed 之后你在终端里看不到任何 print 输出如果程序启动失败你很难定位错误。所以我通常分两步先在本地不加--windowed跑一次确认没有报错再在 CI 里用--windowed打正式包。图标和版本信息。单位内部工具虽然不需要上架但图标最好还是带上不然 exe 默认就是个丑丑的 Python 图标。版本信息我是通过 PyInstaller 的 spec 文件里version参数来设置的或者用--version-file指定一个资源文件。版本号建议和 Git tag 保持一致我一般用脚本读取 tag 然后动态写入。我后来还加了一个步骤把 exe 的哈希值和大小写进构建日志。这样同事下载文件后能自己校验完整性避免传输过程中的损坏。3.4 让 Harness 参与打包脚本的生成与校验这部分算是我自己的扩展玩法。GitHub Actions 和 DeepSeek Harness 不是两个孤立系统我把它们串起来了。因为 workflow 本身也是代码它一样会出 bug一样需要调试。有一次我需要给项目加一个自动更新提示的功能涉及修改入口文件、调整 PyInstaller 的 hiddenimports、还要在 workflow 里增加版本校验步骤。这种事情让 Harness 的 planner 拆解、coder 落地效率很高。我先让 planner 分析入口文件和现有 workflow输出一个改动计划然后让 coder 按照计划修改。reviewer 会在最后检查一遍 PyInstaller 的 hiddenimports 是否覆盖了新增模块。具体执行时我把 workflow 文件路径也加入了 Harness 的 workspace这样它可以直接读取并理解整个 CI 链路。为了让模型更准确我还写了一个skills/gha-windows/skill描述 GitHub Actions 中 Windows Runner 的一些关键差异比如pwsh和cmd的语法区别、actions/cache 在 Windows 上的路径格式等。有了这个 skillHarness 生成 workflow 时的准确率明显提高不再出现和后台符号在 PowerShell 里解析失败的尴尬情况。这一节的核心思路是不要把 CI 配置当成写一次就完事的静态文件它和项目代码一样需要持续演化和维护而 AI 辅助工具完全可以承担这部分工作。4. 实操中踩过的坑与排查记录4.1 PyInstaller 打包后缺少动态库 / 运行闪退这个问题几乎每个做 Python 桌面应用的人都会遇到。具体表现是本地能跑打包后点击 exe 闪退或者提示找不到某个 DLL。我遇到的一次是 PySide6 的一个 WebEngine 模块PyInstaller 默认收集不全。排查步骤我当时是这么做的先在本地用--onedir模式打包然后到目录里手动执行AppName.exe看命令行窗口里的报错信息。如果是 Python 层缺模块会直接告诉你 ModuleNotFoundError如果是缺动态库可以用 Dependencies 这类工具扫描 exe查询缺失的 DLL。解决方式是在 spec 文件的hiddenimports里显式声明模块。比如当时我就加了a Analysis( [app/main.py], ... hiddenimports[PySide6.QtWebEngineCore, PySide6.QtWebEngineWidgets], ... )还有一个很隐蔽的问题PyInstaller 打包的时候会把 locale 和 openssl 相关文件处理得比较奇怪如果你用到了 requests 或者某些加密库exe 在别的机器上可能报 SSL 相关错误。解决思路是在 spec 里把certifi的 cacert.pem 用--add-data打进去并在代码里显式设置 SSL 证书路径。这些坑都很细遇到了才知道。4.2 Action 缓存不生效每次都在重复装依赖我之前配的缓存一直不生效看了 Actions 日志发现 cache 步骤提示找不到缓存原因是requirements.txt有更新hashFiles结果变了所以永远 miss。这个逻辑本身没问题问题在于我更新 requirements 太频繁导致缓存命中率很低约等于每次都全量重装。后来我把缓存策略改了一下不再用 requirements.txt 的哈希作为 key而是用requirements.in顶层依赖列表的哈希作为 keyrequirements.txt只是锁文件。顶层依赖一般很少变锁文件频繁更新也不会导致缓存失效。这样缓存命中率大幅提升。这个操作背后的道理是缓存要跟随变化频率低的输入文件而不是跟随每次构建都可能变的文件。4.3 Harness 连不上本地模型 / 思考模式失灵这个在 2.1 节已经提过一次我再补充一个更隐蔽的现象本地模型正常启动Harness 也能出结果但/think的内容始终不显示。后来发现是我在配置里把thinking_mode写成了false没注意到。这个字段在不同的模型上支持程度不同如果你的模型是个非推理模型开启thinking_mode反而可能导致输出为空。排查思路就一条先确认模型本身支持 Reasoning再确认 Harness 配置里没有二次关闭。还有一个我印象深刻的场景Harness 的多个智能体同时跑多个任务时如果本地显存不够Ollama 会把模型反复换进换出导致每个任务的响应时间都飙升到几十秒。我的机器是 RTX 3060跑 14B 模型已经到了边缘。后来我把模型换成了 7B 的量化版本同时限制了并发的 agent 数体验立刻正常了。本地部署模型不是越强越好要平衡效果和响应速度。4.4 常见问题速查表问题可能原因解决方式exe 启动闪退缺动态库 / hiddenimports 不全用 onedir 打包看报错或用 Dependencies 扫描exe 被杀毒软件误报onefile 自解压行为触发启发式检测代码签名或改用 onedir 压缩包GitHub Actions 缓存 misskey 对应的文件频繁变化改用频率低的顶层依赖文件作为 keyHarness 输出为空thinking_mode 配置错误或模型不支持确认模型支持 Reasoning关闭该字段多个 agent 同时跑很慢显存不足 / 并发数过高换更小的量化模型限制并发pip 安装依赖超时Windows Runner 网络不稳定配置国内 PyPI 镜像或重试机制最后再分享一个小技巧GitHub Actions 的 Windows Runner 上PowerShell 的换行符和反引号跟 Linux 不一样写长的 PowerShell 命令时很容易被格式问题坑到。我现在的习惯是所有复杂脚本都放到scripts/build.ps1文件里workflow 里只写一行powershell -File scripts/build.ps1。这样既方便本地联调也避免了 YAML 换行和引号地狱。一行调用本地和 CI 行为完全一致这个习惯帮我省了非常多时间。
