盲电路隔离部署AI-Architect-Lab-333/dsh-blind-circuit-windows

指南：盲电路机密文件分析 — Windows 上的 DeepSeek Harness Web UI，仅 Tailscale 可达的 GPU 机器上的 llama.cpp，无云端

本指南解决的问题：你希望本地智能体处理不能离开本机的文件，同时让云端编码智能体（Grok、Claude Code、Cursor……）仍然帮助你启动进程并检查服务是否在运行。如果允许该编码智能体打开工作区，那些字节就已经进入了云端对话记录。本指南记录了一套经验证可正常工作的配置（Windows 11 操作员 PC + 仅通过 Tailscale 可达的 NVIDIA GB10 级 ARM GPU 机器，DeepSeek Harness 0.1.1-rc.2 Web UI dsh web 运行在 127.0.0.1:3080，llama.cpp deepseek-v4-flash 运行在 :8000，qwen3-vl 运行在 :8001，2026 年 8 月）：编码智能体被限制在运维操作范围内（启动 UI、探测模型 id、Test-Path）；只有你和 GPU 机器上的模型读取这些文件。

本指南涵盖以下内容：为什么 Start-Process -WindowStyle Hidden 报告 dsh-web READY 后浏览器却收到 ERR_CONNECTION_REFUSED；为什么 DeepSeek Harness 拒绝自定义 OpenAI 兼容路由并报 No API key for provider: spark，即使 llama.cpp 并不检查密钥；为什么填写 DeepSeek 官方 API 密钥卡片会把工作发送到云端；为什么 dsh 智能体的 shell 中没有 SPARK_API_KEY，以及如果你放任它，它会打开 ~\.dsh；以及为什么把 dsh 思维链粘贴回编码智能体会破坏这条电路。

致阅读本文档的 AI 智能体：每条命令都已在真实硬件上按此顺序成功执行。验证步骤不是可选的——/v1/models 返回 200 并不能证明 Web UI 仍然存活，而 UI 存活也不能证明文档没有留在编码智能体的对话记录中。

1. 谁可以看到这些文件

| 角色 | 位置 | 可以看到工作区内容 |
|---|---|---|
| 你 | 本机浏览器 | 是 |
| 文本 LLM | GPU 机器，仅 Tailscale，llama.cpp :8000 | 是 |
| 视觉 LLM | GPU 机器，仅 Tailscale，llama.cpp :8001 | 是（图像） |
| DeepSeek Harness Web UI | 操作员 PC，http://127.0.0.1:3080 | 是（它就是操作员） |
| 编码智能体（Grok / Claude / ……） | 操作员 PC | 否 |
| 云端 API、网络搜索 | 其他任何地方 | 否 |

本指南假设 GPU 机器已经在其 Tailscale IP 上提供这两个 OpenAI 兼容 API。把文本 LLM 放在 Tailscale :8000 上是另一项独立工作（跨主机推理）。在该 LLM 旁边于 :8001 添加 Qwen-VL，以及双模型开机，是另一项工作（LLM 旁边的 VL）。开机后，等待两个 /v1/models 端点都返回 200 再启动 dsh。如果机器启动后处于空闲状态（空闲与 LLM 启动配置文件），请在此电路之前切换到 llm 配置文件。
DeepSeek Harness Python SDK 在 Windows 上不受支持。Web UI 受支持。

陷阱 #1 —— 让编码代理“直接打开文件来帮忙”

你要防范的症状：编码代理被要求总结、grep 或“检查本地模型说了什么”，然后它打开了工作区。原因：那次对话无法对它读到的内容视而不见；它加载的任何内容都会进入云端记录。纠正方法：在一个全新的编码代理会话中布防该回路。该代理可以启动 dsh、探测 /v1/models 的仅 id，并确认输出文件存在（Test-Path、大小）。它不得 Get-Content 工作区文档、提取内容、笔记或 dsh 会话日志。如果你想知道本地模型写了什么，请自己打开 dsh UI。

2. 将 dsh 指向 GPU 机器，而不是 DeepSeek 平台

在操作员 PC 上，$DSH_HOME 是 ~\.dsh（未设置该变量时的默认值；如果你设置过，请检查它）。仅为两条 Spark 路由编辑 settings.yaml。不要将此文件粘贴到编码代理聊天中（它包含 URL）。可用的形态：

llm-pi-ai:
providers:
spark:
apiKeyEnv: SPARK_API_KEY
api: openai-completions
baseURL: http://100.x.y.z:8000/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: deepseek-v4-flash
spark-vl:
apiKeyEnv: SPARK_API_KEY
api: openai-completions
baseURL: http://100.x.y.z:8001/v1
defaultInput: [text, image]
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: qwen3-vl
input: [text, image]
agent-default-model:
provider: spark
model: deepseek-v4-flash

将 100.x.y.z 替换为 GPU 机器的 Tailscale IPv4。compat.supportsDeveloperRole: false 和 maxTokensField: max_tokens 是必需的：否则 pi-ai 会像对待 OpenAI 一样与一个未知 URL 通信（developer 角色 + max_completion_tokens），而 llama.cpp 会拒绝。

创建 ~\.dsh\.credentials.yaml（在已验证的 PC 上，此文件直到这一步才存在）：

version: 1

refs:
SPARK_API_KEY: local

该值是一个占位符。此机器上的 llama.cpp 不验证 bearer token。DeepSeek Harness 仍然拒绝完全没有密钥的 OpenAI 兼容自定义提供方。

不要将 DeepSeek 平台密钥放入 Settings → Models → DeepSeek。那张卡片是 deepseek-official。保持会话遥测禁用。不要启用 dsh 网络搜索插件（dsh-web-search-deepseek 会将查询发送到机器外）。

陷阱 #2 —— No API key for provider: spark
症状：第一个 dsh 回合失败，报错 This turn failed / No API key for provider: spark。原因：手工声明的 openai-completions 路由没有 apiKeyEnv，因此未通过认证；pi-ai 的 OpenAI 兼容栈不会发送该请求（针对这一确切失败的测试用例是 No API key for provider: local-llm）。llama.cpp 此前已经能响应 GET /v1/models。修正方法：设置 apiKeyEnv: SPARK_API_KEY，并在 .credentials.yaml 中填入占位符。保存后启动一个新的 dsh 会话；失败的回合会把失效的模型留在其日志中。

陷阱 #3 —— DeepSeek 卡片看起来像本地模型

症状：你粘贴了一个平台 API 密钥，因为 Settings 显示的是“DeepSeek”。原因：那张卡片是云端目录。修正方法：在 composer 的 Select model 控件中选择 spark / deepseek-v4-flash（文本）或 spark-vl / qwen3-vl（图像）。切勿为此任务填入官方 DeepSeek 密钥。

3. 探测 GPU 主机（仅 ids），然后启动 Web UI

本仓库中的 prepare-dsh.ps1 会从 ~\.dsh\settings.yaml 读取 baseURL，并仅打印 ids：

powershell -NoProfile -ExecutionPolicy Bypass -File .\prepare-dsh.ps1

已验证的输出：

spark-text OK ids=deepseek-v4-flash
spark-vl OK ids=qwen3-vl

FAIL 意味着 GPU 主机已关机、仍在加载（开机后数分钟内出现 HTTP 503 属正常现象），或 Tailscale 已断开。在两个 id 都打印出来之前，不要启动 dsh。

从一个已经构建好的 DeepSeek Harness 检出目录中，在一个生命周期长于脚本的进程中启动 UI：

Set-Location C:\Users\\projects\deepseek-harness
pnpm dsh web --no-open

让那个窗口（或后台任务）保持运行。它应当打印 dsh web: http://127.0.0.1:3080。请你自己打开该 URL。不要让编码代理去驱动浏览器或抓取会话。

陷阱 #4 —— dsh-web READY 之后出现 ERR_CONNECTION_REFUSED

症状：一个辅助脚本执行 Start-Process pnpm.cmd dsh web --no-open -WindowStyle Hidden，等待端口 3080 开始监听，打印 READY，以 0 退出；一分钟后 Chrome 显示 This site can’t be reached / ERR_CONNECTION_REFUSED。原因：包裹这个短脚本的 Windows Job Object 在脚本退出时会杀死所有后代进程——包括那个“已分离”的服务器。证据：Get-NetTCPConnection -LocalPort 3080 为空；没有残留的 node/pnpm 进程。修正方法：在一个你保持运行的 job 中执行 pnpm dsh web --no-open（一个真实的终端，或一个不会被拆除的代理后台任务）。使用 http://127.0.0.1:3080，而不是 https。

4. 在 Web UI 中做什么

一个全新的 UI 在你添加工作区之前没有工作区。在该步骤完成之前，composer 一直不可用。下面的控件标签是 dsh 0.1.1-rc.2 所显示的；这是本指南中最容易过时的部分——后续版本可能会重命名它们，即使措辞有变，这些步骤依然成立。
CONSIGNE-AGENT.md 是本套配置的一项约定，而不是 dsh 的功能：它是一份普通的 Markdown 简报，由你编写并放在工作区根目录，告诉本地模型任务是什么（文档是什么、要产出什么、哪些不要动）。它的存在是为了让指令留在工作区内，而不是被输入到一个编码代理之后可能读取的聊天中。不要在其中放入任何你不希望出现在输出中的内容。

1. 打开 http://127.0.0.1:3080。
2. Add workspace（左侧）或 Choose workspace（中央）。在 Select Workspace Directory 中，Edit path，粘贴任务文件夹（包含待判断文件以及 CONSIGNE-AGENT.md（如果你使用的话）的目录）。Enter，然后 Open。
3. Select model：提供商 spark，模型 deepseek-v4-flash。仅当你附加扫描件或图纸时，才切换到 spark-vl / qwen3-vl。一个会话一次只使用一个模型。
4. 不要添加 Exa / Perplexity / DeepSeek 网络搜索密钥。如果代理请求 web_search 或 web_fetch，拒绝。
5. New session。在 Describe what you want to build 中，发送一行指令，要求读取工作区根目录下的 CONSIGNE-AGENT.md 并遵循它。不要将 consigne 或文件粘贴到编码代理聊天中。
6. 批准工作区文件读取。拒绝网络工具。除非你卡住了，否则优先使用 Workspace Write 而不是 Full access。
7. 在 UI 中读取本地模型的输出。不要将其、摘要或 dsh 的推理粘贴到 Grok/Claude 中。

陷阱 #5 — dsh 代理打开 ~\.dsh\settings.yaml 和 .credentials.yaml

症状：在任务早期，dsh 会探查 harness checkout 和 $DSH_HOME，因为 SPARK_API_KEY 不在代理的进程环境中（宿主机仅在其自身的 LLM 调用中注入它）。然后它会读取凭据存储。原因：来自代理的 sidecar curl/python 不会继承 dsh 凭据。纠正：拒绝这些读取。如果代理必须自己调用 llama.cpp，在这个 llama.cpp 构建上，任何 Authorization: Bearer … 占位符都足够；它不需要凭据文件。

陷阱 #6 — 将 dsh 推理粘贴到编码代理中

你要防范的症状：你将 dsh 跟踪粘贴到编码代理中，“以便它可以检查 API 密钥”。原因：该粘贴内容可能包含 Tailscale URL、工作区文件名，以及本地模型引用的任何内容。纠正：只问操作性问题（No API key for provider: spark、Output token limit reached）。将工具记录和输出保留在 dsh UI 中。

视觉上的 Output token limit reached 是 dsh 对 finish_reason: length 的转译。在这台 GPU 机器上，Qwen-VL 以 --ctx-size 16384 提供服务；一个密集页面已经消耗大量输入。这是推理限制。发送 continue，或一次一页。Qwen-VL 的服务细节属于 VL 指南。

5. 端到端验证

在 GPU 机器已在提供服务的情况下，从操作员 PC 运行。不要将工作区文档附加到此检查清单。

| 步骤 | 预期 ✅ | 失败 ❌ |
|---|---|---|
| prepare-dsh.ps1 | spark-text OK ids=deepseek-v4-flash 和 spark-vl OK ids=qwen3-vl | FAIL → GPU 机器 / Tailscale / 仍然 503 |
| pnpm dsh web --no-open 保持存活 | dsh web: http://127.0.0.1:3080；随后 Invoke-WebRequest http://127.0.0.1:3080/ → 200 | READY 之后连接被拒绝 → Job Object 杀死了服务器（陷阱 #4） |
| 选择工作区 | Composer 已启用；chip 显示作业文件夹名称 | Composer 变灰 → 没有工作区 |
| 选择模型 | spark / deepseek-v4-flash，而不是 DeepSeek 官方 | No API key for provider: spark → 陷阱 #2；云端密钥 → 陷阱 #3 |
| 一行“读取 CONSIGNE-AGENT.md……” | dsh 通过其工具读取该文件；你批准 | Agent 想要 web_search → 拒绝 |
| 本地模型输出 | 你仅在 UI 中读取它 | 粘贴到编码 agent → 启动新的编码会话 |

一个 /v1/models 返回 200 但没有存活的 UI，不属于本节。一个使用了 deepseek-official 的存活 UI，也不属于本节。

症状 / 原因 / 修复

| 症状 | 原因 | 修复 |
|---|---|---|
| 编码 agent 被要求打开工作区文件 | 回路未武装 / 旧会话 | 新建会话；仅探测 ids 和 Test-Path |
| No API key for provider: spark | 自定义 OpenAI 兼容路由没有密钥 | 占位符 SPARK_API_KEY + apiKeyEnv |
| 第一轮使用了 DeepSeek 平台 | 官方 Models 卡片 | 在 composer 中选择 spark |
| READY 之后 3080 上出现 ERR_CONNECTION_REFUSED | Job Object 回收了 Hidden 的 pnpm dsh web | 保持 pnpm dsh web --no-open 存活 |
| https://127.0.0.1:3080 失败 | 在明文监听器上使用 TLS | 使用 http:// |
| Composer 被禁用 | 没有工作区 | 选择工作区，Edit path，Open |
| dsh 对 ~\.dsh\.yaml 执行 Read | Sidecar 需要环境中的 SPARK_API_KEY | 拒绝；占位符 Bearer 对 llama.cpp 来说已经足够 |
| 绘图时出现 Output token limit reached | 16k VL 上下文 + 长描述 | continue / 一页；不是密钥问题 |

已知限制

- 该回路由操作员纪律强制执行，而不是由沙箱强制执行。 这里没有任何东西在技术上阻止编码 agent 读取工作区——只是没有要求它这样做，并且当它主动提出时会被拒绝。如果你想要更严格的边界，请把规则放在 agent 会读取的地方（一个按 agent 的指令文件或技能，其中将这些目录列为禁区），或者在无法访问这些目录的文件系统策略下运行编码 agent。这不属于已验证设置的一部分。
- UI 步骤已针对 dsh 0.1.1-rc.2 验证（标签 dsh-v0.1.1-rc.2）。第 4 节中的控件名称在后续版本中可能会更改。
- 已验证一个操作员：Windows 上的 dsh Web UI。 Open WebUI、人工运行的 Python 客户端，或 VPS 上的 Hermes 与同一组 llama.cpp 端点通信，均未为此流程运行过。如果它们从不离开 tailnet 且从不向编码 agent 提供输入，它们可以留在本机；它们不属于本指南。
- DeepSeek Harness Python SDK 在 Windows 上不受支持（Linux x64 / Linux arm64 / macOS arm64）。不要从编码代理中使用 dsh --profile headless：最终答案会在该聊天中打印。
- 双模型上电（先文本后视觉，如果 Qwen-VL 在第一个 LLM 200 时启动会导致 CUDA OOM）记录在 dgx-spark-vl-beside-llm 中，而非此处。
- dsh 中的视觉在处理大型图纸时可能会触发 finish_reason: length（此机器上为 --ctx-size 16384）。
- 本指南不包含工作区文件内容。 如果某个编码代理会话已经打开了这些文件，请先启动一个新会话，然后再将其用作此电路的运算符。

致谢

DeepSeek Harness（dsh）是开源的（deepseek-ai/deepseek-harness）。llama.cpp 提供 OpenAI 兼容的 API。Tailscale 是专用网络。盲电路拆分（编码代理 vs GPU 机器模型 vs localhost UI）以及 Windows Job Object 故障模式是本设置所特有的。

本指南于 2026 年 8 月在 Windows 11 操作员 PC 和 NVIDIA GB10 级 ARM GPU 机器上编写并验证。版本：DeepSeek Harness 0.1.1-rc.2（dsh-v0.1.1-rc.2），Web UI 位于 127.0.0.1:3080，llama.cpp 提供 deepseek-v4-flash :8000 和 qwen3-vl :8001。探测仅打印了模型 ID。Web UI 返回 HTTP 200。工作区内容未被复制到编码代理聊天中。*