在 DeepSeek Harness 里跑通 Foggy：从安装插件到第一次问数

副标题：认识 CLI、Launcher、Skill 和 Runtime，再用 TM/QM 接住真实数据库

文中的命令按当前仓库整理；DeepSeek Harness 和 Foggy 插件仍在预发布阶段，页面或安装方式有变化时，以仓库说明为准。

为什么要把 Foggy 接到 Harness

如果只是想让一个模型回答数据库问题，装上 Harness 还不够。还需要有人负责连接数据库、发现表结构、把业务字段整理成语义模型，再把查询交给一个真正执行 SQL 的引擎。

这篇文章介绍的组合是：

text 复制代码

DeepSeek Harness
  ├─ dsh CLI：创建 / 管理 Web profile，安装插件
  ├─ Foggy 插件：设置页、组件状态和 onboarding 入口
  ├─ Foggy onboarding Skill：引导数据库接入和语义层建模
  └─ 用户的工作区：保存 TM/QM、查询草稿和证据
          ↓
Foggy Launcher（Java）
          ↓
Foggy Runtime（数据源、Bundle、查询模型和查询执行）

模型负责理解问题和调用工具，Foggy Runtime 负责把受约束的查询落到数据库。这样做的重点不是让模型"直接写一条 SQL"，而是让它在已有的 TM/QM 语义层上工作，查询结果也可以被校验、复现和继续修改。

这里的 Foggy 插件是社区项目，不是 DeepSeek 官方插件市场的收录或认证。DeepSeek Harness 官方文档支持 npm、Git 仓库、本地目录和 tarball 等插件分发形式；Foggy 只是按这个插件机制提供了自己的 Bundle 和设置页。

Foggy 插件到底做了什么

插件不是 Java Runtime 本身

插件包主要负责把 Foggy 接到 Harness 的原生插件和设置体系里：

在 Settings → Plugins 下增加 Foggy 数据分析 页面。
显示私有 Python、CLI、Launcher、分析 Skill、语义查询 Skill 和引导 Skill 的状态。
把 foggy-deepseek-onboarding 注册到 Harness 的原生 Skill 注册表。
初始化或修复组件，持久化 Runtime 端口，启动和停止 Java Launcher。
保存本地引导进度，并导出脱敏诊断报告。

它不会把 Python、Java 或完整 Runtime 二进制塞进 npm 包。插件先以轻量 Bundle 安装，用户第一次点击初始化时，才下载固定版本的私有 Python、CLI、Launcher 和 Skills；下载完成后会做完整性校验。

图 1：Settings → Plugins → Foggy 数据分析 页面，展示 Runtime 状态和 CLI / Launcher / Skill 组件卡片。截图来自本地开发环境，路径信息仅用于说明组件由插件管理。

CLI、Launcher、Skill、Runtime 怎么分工

可以把它们看成四个层次：

CLI ：管理本地 profile、运行 Foggy 的命令和检查流程。插件中的 CLI 是隔离环境，不要求出现在系统 PATH 中。
Launcher：负责拉起 Java Runtime。它不是查询模型，也不是 Harness 的聊天工具。
Skill ：给 Agent 一套开发流程，包含连接数据源、发现 schema、创建 TM/QM、校验、注册 Bundle 和执行受限查询的动作。foggy-deepseek-onboarding 随插件提供；foggy-ai-analysis 和 foggy-semantic-query 在初始化时按固定版本下载。
Runtime：真正持有数据源、namespace、Bundle 和 QueryModel，并负责生成和执行受约束的查询。

Harness 是上面的编排和交互外壳。数据库凭据、模型文件和 Runtime 状态仍然有各自的边界，不能把"在 Harness 里能对话"理解成"已经完成生产部署"。

环境准备

Windows

建议在 PowerShell 里先检查：

powershell 复制代码

node --version
npm --version
java -version
tar --version

Node.js 使用 22.19.x 或 24.x 及以上支持线，Java 使用 17 或更高版本。Windows 10/11 通常已经带有 tar；如果命令不存在，先补齐系统工具再安装插件。

启动 Harness Web UI 可以使用官方推荐的命令：

powershell 复制代码

npx --yes --package=@deepseek-ai/dsh@0.1.2-rc.1 --package=pnpm@11.7.0 dsh web

默认 Web UI 地址是 http://127.0.0.1:3080。如果命令输出了带 ?token=... 的完整地址，应当直接使用它，不要把这个临时地址复制到聊天、Issue 或诊断报告里。

Linux / WSL2

同一条 npm 安装命令可以在 Linux 使用。仓库还提供了一个适合干净体验环境的脚本：

bash 复制代码

git clone https://github.com/foggy-projects/foggy-deepseek-harness-plugin.git
cd foggy-deepseek-harness-plugin
bash experience/linux/prepare.sh --dry-run
bash experience/linux/prepare.sh
~/.local/share/foggy-deepseek-harness-experience/run.sh

这个脚本会创建独立的 Harness Web profile，但不会替你配置模型供应商、数据库凭据，也不会在初始化前启动 Foggy Runtime。WSL2 下建议把 DSH、node_modules、私有 Python 和 Foggy 数据放在 Linux 原生文件系统，不要放到 /mnt/c 或 /mnt/d。

系统 Python 不是必需项。插件默认下载并管理自己的 CPython 3.12.13；确实需要复用本机 Python 时，可以显式设置 FOGGY_PYTHON 指向兼容的 3.11+ 可执行文件，但不要为了安装插件去修改全局 Python 或 PATH。

安装 Foggy 插件

安装命令

如果已经有 dsh 命令，可以直接执行：

powershell 复制代码

dsh plugin --profile web add --workspace-root "@foggy-projects/deepseek-harness-plugin@0.4.0-rc.3"

如果系统没有全局 dsh，可以用 npx 固定 Harness 和 pnpm 版本：

powershell 复制代码

npx --yes --package=@deepseek-ai/dsh@0.1.2-rc.1 --package=pnpm@11.7.0 dsh plugin --profile web add --workspace-root "@foggy-projects/deepseek-harness-plugin@0.4.0-rc.3"

安装或升级后要重新启动 Web profile：

powershell 复制代码

npx --yes --package=@deepseek-ai/dsh@0.1.2-rc.1 --package=pnpm@11.7.0 dsh web

遇到 minimumReleaseAge lockfile 错误怎么办

DeepSeek Harness 的 profile 使用 pnpm 的 minimumReleaseAge 策略。刚发布不久的 Foggy 版本如果还没有达到最短等待时间，dsh plugin add 可能报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，并且错误信息里可能同时出现新版本和已安装的旧 Beta。

这通常是 DSH profile 的发布策略拦截，不代表 Foggy npm 包损坏。处理方式是使用错误信息中打印的准确 profile 目录：

powershell 复制代码

Set-Location "<错误信息里打印的 DSH profile 目录>"
npx --yes pnpm@11.7.0 clean --lockfile

然后重新执行原来的 dsh plugin add 命令。如果仍然失败，打开该 profile 的 pnpm-workspace.yaml，确认错误里提到的已安装版本和请求版本都被精确写进 minimumReleaseAgeExclude。不要为了绕过一次安装失败而全局关闭这项策略。

怎么确认安装成功

重新启动 dsh web 后，打开：

text 复制代码

Settings → Plugins → Foggy 数据分析

看到 Foggy 设置页、组件卡片和 初始化并启动 按钮，就说明 Bundle 已经进入当前 Web profile。此时只代表插件安装完成，私有 Python、CLI、Launcher 和 Skills 可能还没有下载。

初始化与设置页面

第一次点击"初始化并启动"

在 Foggy 设置页选择 初始化并启动，插件会按顺序完成：

检查 Node.js、Java 和本地目录。
下载并校验私有 Python、CLI、Launcher 和 Skills。
注册 Foggy onboarding Skill。
启动 Java Launcher。
等待 Runtime readiness。
调用 capabilities 检查 Runtime 能力并保存状态。

如果只想下载组件、不启动 Runtime，可以使用 初始化 或 更新组件 ；已安装但有更新时，页面会显示当前版本和目标版本，并提供 更新并启动。

插件升级不会静默替换正在使用的 CLI、Launcher 或 Skill。组件更新和修复在 Runtime 运行期间会被阻止，避免活动中的 Java 进程和下一次启动的 Launcher 版本不一致。

图 2：组件更新时显示当前处理的组件和进度。

图 3：点击"启动 Runtime"后的进行中状态。首次初始化也会复用同一套进度展示，完成后再进入 Launcher 启动和 Runtime readiness 检查。

Runtime 端口

默认端口是 18166。在 Runtime 连接设置 中输入 1024 到 65535 的整数，点击 保存端口 即可修改；Runtime 运行时不能改端口。

设置页会把这个端口保存到 Foggy 私有数据目录，CLI 和 Skill 都使用同一个 Runtime URL。启动前会检查和 Java 服务相近的通配地址，如果端口已被程序或 Windows portproxy 占用，会直接显示端口冲突，而不是等到 readiness 超时。

图 4：端口在 Runtime 未运行时修改并保存；启动后 CLI 和 Skill 会复用同一个 Runtime URL。

页面上应该检查哪些状态

建议第一次初始化后逐项确认：

Python 是否显示为 Foggy private，版本是否为 3.12.13。
Java 是否显示可用，并且版本至少为 17。
CLI、Launcher、分析 Skill、语义查询 Skill 是否为已安装 / 最新。
onboarding Skill 是否通过 Harness 原生 Skill 注册表提供。
Runtime 是否从"已就绪"变成"运行中"。
数据库与语义层进度是否已经出现对应工作区记录。

页面的 高级修复 区域可以分别检查 / 修复私有 Python、CLI、Launcher、分析 Skill 和语义查询 Skill；导出诊断报告 会生成脱敏 JSON，并包含受限长度的 Runtime 日志尾部。诊断报告不会替你修复生产网络、凭据或权限系统。

首次下载可能比较慢。当前设置页给 Runtime readiness 留出的最长等待时间是 180 秒；冷 JVM、杀毒软件扫描或磁盘较慢时，Windows 可能比 Linux/WSL2 更久。若 Java 进程提前退出，插件会尽快报告失败，不必一直等满 180 秒。

第一次使用：从数据库到自然语言查询

下面按一个开发库来走完整流程。这里没有真实地址、账号、密码或 API Key。

1. 准备一个 namespace 和连接文件

Foggy 的数据源需要绑定到 namespace。可以先用 sales-dev，不要一开始就把模型和生产 namespace 混在一起。

MySQL 连接文件示例：

json 复制代码

{
  "schemaVersion": "foggy-deepseek-connection/v1",
  "profile": "sales-dev",
  "name": "sales-mysql",
  "type": "mysql",
  "jdbcUrl": "jdbc:mysql://<db-host>:3306/<database>",
  "username": "<db-user>",
  "passwordEnv": "FOGGY_SALES_DB_PASSWORD",
  "namespace": "sales-dev",
  "modelsDir": "models",
  "evidenceDir": ".foggy/onboarding-command-evidence/sales-dev",
  "readOnlyRecommended": true
}

在本地开发环境中，可以把密码放在当前进程环境变量里：

powershell 复制代码

$env:FOGGY_SALES_DB_PASSWORD = "<local-development-password>"

也可以使用 SQLite，例如把连接文件中的关键字段改为：

json 复制代码

{
  "type": "sqlite",
  "jdbcUrl": "jdbc:sqlite:./data/dev.sqlite"
}

插件的 onboarding wrapper 会把密码提交给已经运行的 Runtime，用于添加和测试数据源；它不会把密码复制到 TM/QM、引导状态或命令证据里。但当前本地 Runtime 仍可能把开发凭据保存在自己的私有数据源注册表中，所以不要把这种方式直接当成生产密钥管理方案。

2. 让 Skill 发现表结构

在 Harness 对话里，不需要先背 CLI 参数。可以直接说：

text 复制代码

先帮我看看这个测试库里和订单有关的表，别改数据。连接信息在 <connection.json>，建一个 sales-dev namespace，先做表结构和字段检查。

正常流程是：添加数据源 → 测试连接 → 绑定 namespace → 发现表和列 → 读取少量只读样本。重复执行时，已完成的步骤会被恢复，不会因为重新提问就重复注册数据源或 Bundle。

图 5：Skill 检查工作区、读取参考文档并确认 CLI / Runtime 状态。正式发布文章时，数据库地址、账号、密码和本地用户目录都应使用占位符或打码。

图 6：在真实的 DeepSeek Harness 会话中完成 demo_sales namespace 与 sales_demo SQLite 数据源接入；这是本地脱敏测试文件，只读访问，不包含真实数据库地址或凭据。

图 7：Foggy onboarding 返回表级发现结果和 5 个字段的 JDBC 类型、可空性、主键及行数信息。

3. 创建 TM/QM 语义模型

表结构发现后，再让 Skill 做第一版语义层：

text 复制代码

刚才那个订单模型先做一版，覆盖订单数、含税金额、下单时间和状态。文件放当前工作区的 models/，先校验，没通过就告诉我哪里要改。

TM 可以理解为业务事实、维度、指标和字段说明；QM 是对外暴露的可查询模型。第一版不要急着把整个数据库都建进去，先选一个业务主题和几条真实问题，模型更容易检查。

Skill 背后会按这个顺序处理：

text 复制代码

TM/QM 草稿
  → models validate
  → 注册或更新本地 Bundle
  → refresh / describe QueryModel
  → query validate
  → 有界的只读 query execute

这里的"发布"是让本地 Runtime 使用当前工作区的 Bundle，不是发布到生产环境，也不是把代码推到远程仓库。

4. 用自然语言跑第一条查询

模型校验通过后，可以从简单问题开始：

text 复制代码

按月份看 2025 年订单含税金额，最多返回 20 行，告诉我实际用了哪个 QM、时间字段和查询范围。

再试一条带过滤和排序的问题：

text 复制代码

只看已完成订单，按客户统计含税金额，取前 10 名。先给结果，再说明用了哪些筛选条件。

如果你的业务模型里没有"已完成"或"含税金额"字段，就把问题换成模型已经确认过的字段。开始阶段尽量让查询有行数上限、只读，并要求返回使用的 QM、时间字段和范围，方便核对。

图 8：使用 SalesDemoQueryModel 对脱敏 SQLite 数据做第一次只读问数，页面保留 namespace、时间范围、region = 'East' 过滤、返回结果和 SQL。该 Runtime 版本没有暴露 orderDate$month，因此实际按日执行，再在结果页按月汇总；文章不把这个兼容路径描述成引擎原生月份粒度。

开发环境和生产环境不是一回事

本地体验阶段可以简单一些

本地测试时，可以在对话里提供连接文件，或者让 Skill 从 passwordEnv 读取密码。这样更适合快速发现 schema、调整模型和验证问题。当前默认的本地 Runtime 是开发 / 测试取向，不能等同于已经启用生产认证的服务。

生产环境要单独做发布

进入正式环境后，建议由人工或独立发布流程完成：

明确目标 Runtime、namespace 和数据源，不沿用本地默认值。
用密钥管理系统或目标环境的凭据机制，不把密码写入对话、模型文件或仓库。
记录模型 Git commit / tag、CLI / Launcher 版本和校验结果。
由专人部署 Launcher / Runtime，完成窄范围 smoke query。
保留回滚点和验证记录。

Foggy 插件不会自动把本地凭据、审批或授权扩展成生产权限，也不会因为本地查询通过就替你完成企业 IAM、审计和网络治理。

常见问题排查

插件装好了，Harness 还在提示安装

通常是 Web profile 没重启，或者安装和启动使用的不是同一个 profile。先停止当前 dsh web，再用同一个 --profile web 启动；如果是远程或无浏览器环境，使用命令输出的完整 token URL。进入 Settings → Plugins 后，确认能看到 Foggy 数据分析 页面。

插件升级后组件没有自动升级

这是设计如此。升级 npm Bundle 不会静默替换正在运行的 CLI、Launcher 和 Skills。打开 Foggy 设置页，查看当前 / 目标版本，停止 Runtime 后点击 更新组件 或 更新并启动 。如果只有某一项损坏，再从 高级修复 中单独处理。

Runtime 端口冲突

新安装默认使用 18166。停止 Runtime，在设置页改成 1024--65535 之间的空闲端口并保存，再重新启动。Windows 上还要留意 portproxy 或其他服务占用通配地址；插件应当在启动前直接显示冲突原因。

Runtime readiness 超时

先不要反复点击启动：

看页面显示的失败阶段，是 Java 启动、readiness 还是 capabilities。
确认 java -version 至少为 17，磁盘空间和内存足够。
检查端口是否被占用，以及杀毒软件是否正在扫描新下载的 JAR。
点击 导出诊断报告，保留启动阶段、PID 状态、Runtime 日志位置和脱敏日志尾部。
修复明确的输入后再重试，而不是直接删除整个 Foggy 数据目录。

CLI 不在 PATH，是不是安装失败

不一定。插件刻意把 CLI 放在自己的隔离目录里，不要求修改系统 PATH。先在设置页检查 CLI 状态，必要时使用 检查 / 修复 CLI ，或在对话中让 onboarding Skill 执行 doctor。不要为了让命令行能找到它，就把私有目录加入全局 PATH。

如何查看日志和导出诊断

在 Settings → Plugins → Foggy 数据分析 页面点击 导出诊断报告。报告只读取受管理 Runtime 目录下的有限日志尾部，并会做脱敏；不要手工把数据库密码、API Key、Harness 启动 token 或完整连接文件追加进去。

生态链接和边界

GitHub Topic 和社区目录只是发现入口。DeepSeek Harness 当前没有由官方运营、带审核认证含义的插件市场；即使某个第三方目录收录了 Foggy，也只能称为社区收录，不能写成 DeepSeek 官方认证。

写在最后

Foggy 插件解决的是"在 Harness 里把数据分析工程接起来"：它把安装、组件管理、Java Runtime、数据源接入和 TM/QM 建模串成一条开发路径。真正决定查询质量的，仍然是数据源、语义模型、权限边界和验证问题集。

第一次使用时，建议先做一个小 namespace、一个业务主题和三条只读问题。能看懂从表结构到 QM、从 QM 到查询结果的每一步，再逐步扩大范围。这样遇到问题时，知道应该查 Harness、插件、Launcher、Runtime，还是模型本身。

在 DeepSeek Harness 里跑通 Foggy：从安装插件到第一次问数

为什么要把 Foggy 接到 Harness

Foggy 插件到底做了什么

插件不是 Java Runtime 本身

CLI、Launcher、Skill、Runtime 怎么分工

环境准备

Windows

Linux / WSL2

安装 Foggy 插件

安装命令

遇到 minimumReleaseAge lockfile 错误怎么办

怎么确认安装成功

初始化与设置页面

第一次点击"初始化并启动"

Runtime 端口

页面上应该检查哪些状态

第一次使用：从数据库到自然语言查询

1. 准备一个 namespace 和连接文件

2. 让 Skill 发现表结构

3. 创建 TM/QM 语义模型

4. 用自然语言跑第一条查询

推荐工作流

开发环境和生产环境不是一回事

本地体验阶段可以简单一些

生产环境要单独做发布

常见问题排查

插件装好了，Harness 还在提示安装

插件升级后组件没有自动升级

Runtime 端口冲突

Runtime readiness 超时

CLI 不在 PATH，是不是安装失败

如何查看日志和导出诊断

生态链接和边界

写在最后