本地部署套件 CyrexML/deepseek-harness-setup

DeepSeek Harness：从零开始完整搭建，含插件与调优

Русская версия

本仓库可在 Windows PC 上安装一套完整的 DeepSeek Harness 环境：在你自己的 GPU 上运行本地模型、一个能读取并编辑项目文件的编码代理、一个用于渲染结果（HTML 页面、PDF、电子表格）的侧边面板，以及一个你真正可以在手机上使用的移动端界面。

这并非一次裸装 harness。它还会配置值得拥有的插件，应用 17 层补丁来修复开箱即用状态下无法工作的部分（其中大多数位于移动端），针对你的 GPU 调优模型服务器，并安装快捷方式、更新按钮以及完整的卸载程序。

一切都在本地运行。不会向云端发送任何内容。

这是什么

这不是一组提示，也不是一份让你自己运行的命令清单。这是一套开箱即用的安装方案：你复制 config.json，以管理员身份运行 install.cmd，最终得到一个各部件已经彼此适配、可正常工作的系统。

你将获得：

- 在你自己的 GPU 上运行的模型 —— 安装程序会挑选一个适合你显存的模型，下载它，计算上下文窗口，并通过实测验证结果；
- 一个能处理文件的代理 —— 读取项目、编辑代码、在你批准后运行命令，并在会话之间保留决策；
- 一个侧边面板 —— 资源管理器、编辑器和结果视图：可运行 JavaScript 的 HTML 页面、 PDF、电子表格、diff 和 git 提交；
- 你的手机 —— 一个在手机上真正可用的界面，可通过隧道从任何地方访问；
- 维护 —— 快捷方式、电源按钮、一键更新、完整卸载，以及清理不断堆积的内容。

为什么这不等同于“自己安装 harness”：harness 是核心。
围绕它，你仍然需要选择并接好插件、修复在手机上无法工作的部分、为你的显卡挑选模型、计算上下文窗口、设置启动项、隧道和电源行为。而在这里，这些都已经完成并固定下来：在容易出问题的地方有 17 层补丁，每个组件版本都记录在 stand.lock.json 中，模型服务器设置是根据你的 GPU 计算出来的，而不是从别人的示例中照搬的。

诚实的限制：你需要一块 12 GB 以上的 NVIDIA GPU，以及带 WSL2 的 Windows；回答质量取决于你所选模型的质量，而不是安装程序的质量；而且只有一块显卡，所以你自己的 GPU 工作（训练网络）和模型需要轮流使用——关于这一点有专门一节。

要求

| | 最低 | 调优目标 |
| 操作系统 | Windows 10 / 11 | Windows 11 |
| GPU | NVIDIA，12 GB 显存 | RTX 5080，16 GB |
| 磁盘 | 40 GB 可用空间 | |
| 内存 | 16 GB | 32 GB |
此仓库中的配置针对 16 GB 显存的 RTX 5080 进行了调优，以 UD-Q3_K_XL 运行 Qwen3.8 27B。如果显存更少，安装程序会从同一目录中挑选一个更小的模型——在 12 GB 时即为 Qwen3.5 9B（MTP 构建），它支持该支架所依赖的、用于提速的相同推测解码。
如果连这个也放不下，向导会建议使用同一文件的更低量化版本，而不是换一个不同的模型。

如果没有 NVIDIA GPU，该支架仍可安装——安装程序会挑选引擎的 CPU 构建——但模型运行速度会慢几十倍。

你无需准备的事项：

- WSL。 如果缺失，00-prereqs 会为你安装 WSL2 和一个发行版。
Windows 可能会要求重启；重启后再次运行安装程序，它会继续。
- 名为 F: 的驱动器。 那只是 config.example.json 中的默认值。如果该驱动器不存在，安装程序会挑选可用空间最大的驱动器，并将选择写回 config.json。
- CUDA Toolkit。 只需要 NVIDIA 显示驱动程序：引擎以预编译二进制文件的形式随附，并带有匹配的 CUDA 运行时库，安装程序会为你下载。仅当你选择使用 10-llama.ps1 -Build 从源码构建 llama.cpp 时，才需要 Toolkit。
- 特定的 CUDA 版本。 安装程序会读取你的驱动程序支持的内容，并挑选最合适的最新引擎构建。

安装

1. 下载此仓库（Code → Download ZIP）并解压。
2. 将 config.example.json 复制为 config.json。你只需查看一行—— windowsRoot，即模型和引擎所在的文件夹。
3. 右键点击 install.cmd → 以管理员身份运行。

安装程序会逐步解释每一步：

| 步骤 | 会发生什么 |
| 00-prereqs | 检查 GPU 和可用空间，安装 WSL2 和一个发行版，打开模型端口 |
| 10-llama | 安装 llama.cpp，并使用与你的驱动程序匹配的 CUDA 构建 |
| 20-model | 为你的 GPU 挑选一个模型并下载 |
| wsl/ | 构建 harness，安装插件，应用 17 个补丁层，写入配置 |
| 30-tune | 计算适合你的 VRAM 的上下文窗口并测量结果 |
| 40-shortcuts | 快捷方式、自启动、电源维护任务 |
| 50-verify | 验证一切是否正常启动 |

消息语言。 安装程序和启动器默认使用英语。要切换到俄语，请在 config.json 中设置 "lang": "ru"，或为单次运行使用环境变量：

$env:HARNESS_LANG = 'ru'

翻译位于 i18n/ru.json 中，是一个简单的“英文字符串 -> 翻译”表。表中缺失的字符串会以英语输出，因此部分翻译不会破坏任何东西——而添加一种新语言只需再多一个文件，而不是每个脚本的又一份副本。

每一步都是幂等的——中断的安装可以直接重新开始。单个步骤也可以单独运行：

powershell
powershell -ExecutionPolicy Bypass -File install.ps1 -Step model

安装哪些版本固定在 stand.lock.json 中：harness 标签、每个插件的版本以及补丁层列表。这就是本仓库经过测试的组合，因此安装程序不会去追逐“最新版”。

关于模型

选择模型、知道把它放在哪里以及之后调整服务器，是人们通常会卡住的地方。windows\20-model.ps1 会读取你的显存，显示哪些模型适合，并下载你选择的那个；windows\30-tune.ps1 随后会计算上下文窗口、写入启动命令和 agent 预设，并测量预填充和生成速度。

同样的内容用文字说明——docs/MODEL.md。

日常使用

- 桌面上的 Harness AI 会启动模型和界面。
- 界面：。
- 从手机访问——有三种方式：通过二维码使用家庭网络、临时隧道（立即获得地址，无需 Cloudflare 账户）以及永久域名。在对外暴露任何内容之前先设置访问密码：移动界面连接的是一个可以编辑你电脑上文件的 agent。分步说明：docs/MOBILE.md。

停止运行环境：界面左上角的电源按钮。 它可以从 PC 和手机操作，并提供四个级别——仅停止运行环境、连同 WSL 一起停止、停止并睡眠、停止并关闭 PC。

桌面快捷方式 Harness AI — stop 与第一个选项作用相同。

运行环境运行期间

PC 不会进入睡眠——那会在任务中途切断 agent，因为 CPU 和 GPU 负载对 Windows 来说不算活动；它等待的是键盘输入。屏幕仍会按通常的空闲超时关闭，这不会改变任何事：运行环境会继续工作，手机会话也不受影响。当你停止运行环境时，之前的睡眠设置会完全按原样恢复。

查看当前状态： powershell powershell -ExecutionPolicy Bypass -File F:\Harness_AI\run\harness-idle-sleep.ps1

更新

update.cmd

它会拉取本仓库的新版本、备份你的配置文件、应用 stand.lock.json（harness、插件、补丁层、设置）、重启运行环境并进行验证。备份会在任何更改发生之前完成，该命令还会打印如何回滚。

卸载

uninstall.cmd

它会要求确认，并在执行任何操作之前列出将被移除的内容。

| 命令 | 移除的内容 |
| uninstall.cmd | 快捷方式、计划任务、防火墙规则、引擎、启动脚本、模型，以及 WSL 内运行环境的数据 |
| uninstall.cmd -KeepModel | 相同，但下载的模型会保留（重新获取它们需要很长时间） |
| uninstall.cmd -KeepData | 相同，但你的聊天记录、agent 记忆和设置会保留 |
| uninstall.cmd -All | 全部清除，归零：上述内容外加整个 WSL 发行版 |
| bash wsl/uninstall.sh | 仅 Linux 侧，从 WSL 内部执行 |

-All 还会移除 WSL 发行版，因此你在其中保留的其他任何内容也会一并消失——它会要求你输入发行版名称以确认。Windows 本身、作为系统组件的 WSL 以及 GPU 驱动永远不会被触及。

安装内容

- DeepSeek Harness，位于 stand.lock.json 中的标签处，在 WSL2 内从源码构建。
- 插件，版本已固定：移动端桥接、带文件浏览器和查看器的侧边面板、办公文档、上下文计量器、图记忆、回合回退。
- 17 个补丁层——我们在 harness 和插件之上自己的修复（见下文）。
- llama.cpp 以及你选择的 GGUF 模型，位于 Windows 侧。

为什么需要补丁层

开箱即用时，harness 加插件在手机上表现很差，有些功能甚至完全无法使用。
每一层都是一个单独的脚本，通过被修补文件内部的标记来标识，因此插件更新不会悄无声息地丢失它：scripts/ensure-patches.sh 会在每次启动时重新应用缺失的部分。

| 层 | 它为你带来的功能 |
| bridge（翻译 + 11 项修复） | 可用的移动端 UI：抽屉、旋转、启动画面、电源按钮 |
| mobile-ux | 模型的问题卡片不再遮挡聊天，会折叠成一条，且不会被误关闭；没有蓝色点击闪烁 |
| preview-zoom | 双指缩放的是预览的内容——页面、PDF、表格——而不是面板本身，并且缩放后的页面可以平移 |
| zoom-scope | 输入时双指缩放不会缩放对话 |
| pdfjs-map-polyfill | PDF 可在低于 Chrome 140 的浏览器中打开（pdf.js 6.3 调用了一个非常新的 Map 方法） |
| html-no-store | 应用页面从不缓存，因此手机不会卡在旧版本包上 |
| session-sync | 点击侧边面板中的文件会打开它（在 harness 0.1.6 上完全损坏） |
| relative-path | 聊天中的文件链接与从资源管理器中打开的方式相同 |
| binary-handoff | PDF 和办公文件在面板中打开，而不是被下载 |
| turnTail 槽位 ID | 侧边面板和办公插件与 harness 0.1.6 保持兼容 |
| better-sidebar 预览 | 多页应用预览时 JavaScript 可正常工作 |
| llm-pi-ai 用量 | 模型不再基于错误的长度估计截断回答 |
| graph-memory 作用域 | 代理记忆不会混合不同项目 |
| ui-conversation 即时读取 | 粘贴的截图确实能到达模型 |

日常维护

代理会在 ~/.dsh/change-ledger 中保留每回合的文件快照（面板中显示为变更的内容），该目录位于你的项目之外——它永远不会进入 git 仓库，但会不断增长。它以及支架其余残留内容都可通过以下方式清理： bash bash ~/Harness_AI/scripts/dsh-cleanup.sh # 仅报告 bash ~/Harness_AI/scripts/dsh-cleanup.sh --apply --ledger-days 30

如果你想把某个项目纳入 git 管理，请在其文件夹中为 agent 在你的代码旁边创建的文件（截图、备份、导出文件）添加一个 .gitignore：

bash ~/Harness_AI/scripts/project-gitignore.sh --all

网络访问和你自己的 GPU 工作

读取页面（web_fetch）开箱即用——agent 打开链接并读取内容，无需任何密钥。该工具是预设常驻工具集的一部分：该集合之外的任何东西对模型来说都不存在，所以仅注册插件是不够的。私有地址（127.0.0.1、你的家庭网络）按设计会被拒绝，因此无法利用页面访问你的本地服务。

搜索（web_search）需要提供商。 在 harness 捆绑包中，搜索会发往 DeepSeek，并从 DEEPSEEK_API_KEY 获取密钥（packages/bundle/base/cordis.patch.yml:461）；本地模型不暴露此类端点。没有密钥时，搜索会返回错误，而页面读取仍可正常工作。你可以设置 DeepSeek、Exa 或 Perplexity 密钥（设置 → 搜索），或者直接把链接交给 agent——它会读取这些链接。一旦环境中存在密钥，预设会自动将 web_search 添加到模型的工具集中。

agent 不会静默运行代码。 默认是带确认的 workspace-write：命令在运行前会展示给你，文件写入被限制在工作区内（packages/bundle/base/cordis.patch.yml:231）。沙箱只管控文件影响——网络和进程启动不受限制，因此 pip install、数据集下载和训练都可以正常工作。

只有一块 GPU。 默认情况下，调优向导会把几乎整块显卡都分配给模型：仅保留 150–500 MiB 空闲。训练一个网络——CNN、扩散模型——无法放进这些空间，会以 CUDA out of memory 失败。你的任务和模型共用一块显卡，所以这个分配需要提前决定：

keep 6 GB free for your own work; the context window is computed from the rest
powershell -ExecutionPolicy Bypass -File windows\30-tune.ps1 -ReserveMb 6000

你启动训练；agent 做准备。 在它自己的 shell 中，agent 完全无法访问显卡：沙箱给它的是一个没有 GPU 设备的裸 /dev，所以在那里 nvidia-smi 会回答“GPU access blocked”。因此，agent 的工作规则（~/.dsh/AGENTS.md，已为你安装）告诉它去做那些不受阻塞的部分，并把运行交接出去：完成脚本、数据管线和配置；用一次简短的 CPU 运行证明代码可以跑通；并在项目中留下 RUN-TRAINING.md——这是你自己遵循的说明：如何释放显卡、如何搭建环境、启动命令、如何观察运行情况，以及如何把状态恢复回去。如果它仍然尝试启动训练，第一条此类命令不会被执行，而是会得到测量结果作为回应——有多少 VRAM 空闲，以及模型占用了多少。
在 16 GB 上，一个合理的分配是 Qwen3.5 9B（约 7 GB）加上 6–8 GB 用于训练。
如果你反而需要大模型，另一条路是在计算时停止模型服务器（run\stop-server.ps1）——此时 agent 处于无头状态，直到你再次启动它。GPU 从 WSL 中可见（nvidia-smi 位于 /usr/lib/wsl/lib），CUDA PyTorch wheel 可以用 pip 安装；这样做不需要 CUDA Toolkit。

关于预览沙箱。 为了让多页面应用在 JavaScript 正常工作的情况下渲染，设置中默认 htmlViewerNoSandbox: true （templates/settings.yaml.tmpl）。代价在那里已经说明：被预览的页面以界面的源运行，并且可以读写会话文件。对于你自己的项目，这正是你想要的；不要以这种方式打开别人的 HTML。

Git：保持项目整洁

agent 会在你的工作周围留下三种不同的东西，它们值得区分开来。

回合快照——面板显示为变更的内容。它们位于 ~/.dsh/change-ledger，在你的项目之外，永远不会进入 git。它们确实会增长。
用 dsh-cleanup.sh --apply --ledger-days 30 清理它们。

还原点——turn-rewind 插件将它们写入包含项目的仓库，作为 refs/dsh-turn-rewind/… 引用。它们不是分支：git branch 不会列出它们，普通的 git push 也不会发送它们，但许多界面会将它们显示在分支旁边，这就是为什么看起来像你有数百个分支。要查看和修剪它们：

bash ~/Harness_AI/scripts/git-rewind-refs.sh ~/path/to/project # how many
bash ~/Harness_AI/scripts/git-rewind-refs.sh ~/path/to/project --days 14 # drop old ones

删除还原点意味着该回合无法再被回退，因此默认情况下该脚本不做任何更改。

工作残留——.shots/（截图）、backups/（编辑前所做的副本）、out/、日志。这是唯一会真正进入提交的部分。

将项目放到 GitHub 上

bash ~/Harness_AI/scripts/project-git-init.sh ~/Harness_AI/projects/MyProject

它会写入 .gitignore，在 main 上创建仓库，准确显示提交将包含什么内容以及有多大*，进行首次提交，并配置推送，使得只有分支会被推送出去。然后：

gh repo create --private --source=. --remote=origin --push

一个警告：git push --mirror 会发送每一个引用，包括还原点。
普通的 git push 不会。

故障排除

手机通过隧道显示 530。 Cloudflare Tunnel 需要出站 TCP 7844。有些网络会阻止它，那样的话在你切换网络或开启 VPN 之前，什么都无济于事。普通的 HTTPS 仍然可用，这使得这个问题很容易被误诊——参见 docs/MOBILE.md。

生成速度慢于约 20 tokens/s。 模型没有装入 VRAM。重新运行 windows\30-tune.ps1（它会重新计算窗口）或选择更小的量化——参见 docs/MODEL.md。
启动后的第一个请求很慢。 预期情况：第一个大型提示词在冷文件缓存和未构建的 CUDA 图上运行。启动器会发送一个预热请求，因此只有在你手动启动服务器时才会出现这种情况。

许可

本仓库包含我们自己的代码：安装和卸载脚本、补丁层、配置模板、文档。它不重新分发 harness 或插件——pnpm 在安装期间从官方注册表获取它们，补丁随后在你的机器上本地应用。唯一的例外是桥接插件的 UI 翻译词典（从其 MIT 许可的源代码中提取的字符串加上我们的英文翻译）；没有它，插件更新后英文 UI 就无法重新应用。所有上游项目的许可证（MIT、Apache-2.0、BSD-3-Clause）以及我们具体更改的内容列在 NOTICE 中。

我们自己的代码采用 MIT 许可——参见 LICENSE。