Java 数据分析引擎 foggy-projects/foggy-deepseek-harness-plugin

Foggy for DeepSeek Harness（Beta）

本包是 Foggy Java 数据分析引擎的轻量 DeepSeek Harness Bundle。安装 Bundle 后，设置 → 内置插件下会多出一个原生 Foggy 标签页。私有 Python 运行时、Launcher 和隔离的命令行环境，只在你选择 初始化并启动（或执行对应的组件操作）时才下载。升级插件包时，不会悄悄改动已有的安装。

Foggy 设置标签页里有一个 教程 入口，链接到 Foggy AI Data tutorials。

0.4.4-rc.1 兼容候选版面向 DeepSeek Harness 0.2.1-rc.2，要求系统 Node.js >=24.0.0。Foggy 的 Java Launcher 使用系统 Java 17+。Foggy 在每用户组件目录内管理自己固定版本的 Python 3.12 运行时；不需要系统 Python，不修改 PATH，也不全局注册 Python。高级用户可以显式把 FOGGY_PYTHON 设为兼容的 Python 3.11+ 可执行文件。

本地候选版安装

dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.4-rc.1.tgz

重启 dsh web，用它打开的浏览器（或打印出的完整 URL，含 ?token=...）访问，打开 设置 → 内置插件 → Foggy Data Analysis，在那里初始化组件。不要分享启动 token 的 URL。

版本在 npm 上可用后，安装这个精确的 DSH 0.2.1-rc.2 兼容候选版，这样稳定的 beta 通道不会被改动：

dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@0.4.4-rc.1

DSH 0.2.1 候选版使用 dsh021 这个 npm dist-tag。使用前先确认该 tag 解析到你打算安装的版本。registry 尚未发布时，可以直接安装 GitHub 上发布的 tarball：

dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@dsh021

更早的 DSH 0.1.7-rc.2 和 0.1.5-rc.2 候选版仍可用，分别是 @foggy-projects/deepseek-harness-plugin@dsh017 和 @foggy-projects/deepseek-harness-plugin@dsh015。dsh021 候选版不会移动现有的 beta 或 latest 通道。

对现有的稳定 beta 通道，对应的一行安装命令是：

dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@beta

打开设置页时，会自动检查官方 Launcher 和命令行版本，缓存六小时。页面分别显示已安装版本、上游最新版本和插件验证过的版本，包括预发布标签。用 检查更新 刷新列表，然后选一个版本，点 下载并使用。自动检查不会下载或切换任何组件。

切换版本前先停止 Runtime。下载内容会对照官方 SHA256SUMS 与发布元数据。Launcher 和 CLI 的版本分别存放在不同目录，之前下载的版本会保留，可离线回滚。选定的组件版本在插件升级后仍然保留；选定 CLI 不会改变已安装的 Launcher 版本，反之亦然。内置的已验证默认版本是 Launcher 0.1.46 和 CLI 0.1.25；两个 Foggy 技能仍为 0.1.18。在这条兼容线上，早于 0.1.24 的组件不提供激活。

升级插件包后，用 Update components（或 Update and start）把目标版本应用到没有保存用户选择的组件。设置页显示当前版本和目标版本。组件专属的修复操作仍在 Advanced repair 下提供。网络检查失败不会阻塞已安装的 Runtime，也不会清空缓存的版本列表。

DeepSeek Harness 配置档可以对 lockfile 应用 pnpm 的最小发布年龄策略。因此，在发布后不久执行升级可能失败，报错会点名新插件或之前安装的某个版本。这是 DSH 配置档策略失败，不是 Foggy 包损坏。用报错中打印的配置档目录重建 lockfile，然后重新运行同一条 dsh plugin add 命令：

Set-Location "<the DSH profile directory printed in the error>"
npx --yes pnpm@11.7.0 clean --lockfile

失败的 add 通常会在返回前把请求的确切版本记录到 minimumReleaseAgeExclude 下。如果错误重复出现，请确认报错点名的已安装版本和请求版本都出现在配置档 pnpm-workspace.yaml 的该键下；不要全局关闭策略。

开发时，FOGGY_ASSET_CACHE_DIRS 可以包含以平台分隔符分隔的已验证资源缓存目录。正常安装不需要它。

内置的引导技能刻意以开发为先。用户可以在对话中提供本地数据源密码、用户管理的连接文件、Agent 环境变量，或兼容的 Runtime Console。直接密码会提交给已在运行的 Runtime，不会复制进引导状态或证据。随后技能会驱动 schema 发现、语义草拟、本地 Bundle 注册和有界查询验证，全程不重启 Runtime。

原生技能与工作区约定

Bundle 通过 DeepSeek Harness 的原生技能服务商 API 注册 foggy-deepseek-onboarding 和下载的 foggy-ai-analysis。技能在每个 DSH 工作区都可用，无需复制或符号链接 .agents。当前会话的 cwd 仍是语义草稿和证据的工作区边界。
已有 Harness 会话会保留其原始工作区，即使另一个工作区成为默认。测试模型文件隔离时，请在选定的工作区新建会话；仅隔离 DSH_HOME 不会改变会话的 cwd。插件安装命令里的 --workspace-root 选项是 pnpm 的安装选项，不是 Harness 的工作区选择器。

不透明 CLI 配置档仍然保留，供偏好这种方式的用户使用，默认放在私有的持久目录 <dataRoot>/cli-profiles 下，但它不是日常开发的必备条件。组合式引导命令是幂等的：已完成的阶段没有变化就继续沿用，不会重新添加数据源，也不会重新注册本地 Bundle。恢复的数据源检查点还会与运行中的 Runtime 核对；如果数据源在包装器之外被删除，就只恢复数据源配置、验证和 schema 发现。设置会检测遗留的临时配置档，并提供一条显式、经过校验的迁移路径，把它们迁入持久存储。

私有 Python、CLI、Launcher、分析技能、安装状态和 Runtime 状态都放在用户级的 Foggy 组件目录里。托管的 CLI 有意隔离，不需要出现在 PATH 上。重新下载 / 修复会校验全局分析技能，备份被修改或过期的托管内容，再将其恢复，并使 DSH 的技能目录失效。引导技能随插件打包，重装或升级插件包即可恢复。

Foggy 设置标签页显示已持久化的数据库/语义引导阶段，提供固定检查，以及针对 CLI、Launcher、托管分析技能和私有 Python 的修复，还能导出一份经过脱敏的私有诊断报告。报告包含 Runtime 日志有长度上限、已清理的尾部内容，同时拒绝读取托管 Runtime 目录之外的路径。Runtime 启动时会在 wait-ready 期间监控 Launcher 的 PID，Java 一退出就立即失败，并且保持幂等：已记录在案的进程会用 wait-ready 和 capabilities 校验，而不是当成第二次启动失败。

同一个设置标签页还管理一个持久的本地 Runtime 端口。新安装默认使用 18166；Runtime 停止时用户可以另选端口。启动时会检查与 Java 服务器相同的通配符绑定，因此冲突的应用或 Windows 端口代理会立刻报出醒目的错误，而不是等到就绪超时。CLI 和技能会从托管状态中解析出最终稳定的 Runtime URL。

通过原生 foggy_query 工具成功发起一次标准的 QueryModel DSL 调用后，Harness 会在已完成的回复下方、折叠的工具轨迹之外显示一张紧凑的结果卡片。一个可见的「Generated by Foggy plugin」标签把这条程序化记录的执行结果与 AI 回复区分开。卡片显示模型、命名空间、行数、可选的结果预览（五行，附 DSL/SQL 详情），以及查看数据。如果一轮对话中有超过六次成功查询，先显示前六次，直到用户展开列表。详细的 DSL 和执行记录仍留在工具轨迹中。点击 View data 通过 Harness 的工具策略管道，调用已配置的 Foggy MCP 连接器的 dataset.open_in_viewer 工具。请只配置一个连接器来暴露这个工具。它的传输层会保留已配置的授权头；插件不会把凭据写进浏览器侧的契约，也不会退回到匿名创建 HTTP 链接。让助手打开数据视图时，走的是同一个 MCP 工具。授权链接使用宿主由服务端管理的服务身份。只有当 lite 启动器的本地开发路由与正在运行、受管理的回环 Runtime 匹配，且处于 none-dev-test-only 模式时，才接受这条路由。该预览不会把 MCP Authorization 传给浏览器，UI 会把它标记为本地开发预览。受保护的服务必须提供授权链接；插件不会自动启用可选的身份服务商模块。
页面会针对当前模型和数据重新执行 DSL，而不是冻结原始行。查看器持久化默认使用 SQLite。在支持授权查看的宿主上，链接可以设置 TTL 或撤销；每个浏览器会话默认一天，并有单独可配置的 TTL。只要会话记录、连接器、Runtime 和模型都可用，历史卡片就能申请新链接。显式的聚合 having 条件会与明细级的 slice 条件一起保留。预览至少需要一个 slice 过滤条件。未过滤的查询仍会显示结果和过滤提示。不包含 CTE 预览。
Harness 卡片保留完整的执行结果；Web 视图显示 Runtime 模型元数据支持的字段。
DataViewer 页面可以把当前经过过滤和排序、由模型支撑的结果导出为 CSV（最多 10,000 行）。超出上限时它会拒绝导出，而不是悄悄截断。

原生 foggy_query 工具使用受管理命令行单独配置的 Runtime 授权（例如 FOGGY_RUNTIME_AUTHORIZATION）。它不会提取 MCP 连接器的请求头。演示受限数据时，请核实查询工具及其身份。MCP 链接创建与原生命令行查询是两条独立的授权路径。

这个 beta 仍是本地开发/测试集成。它不会自动把本地凭据或审批延伸到正式环境。生产环境的模型发布应使用单独的手动或专用部署工作流，并明确目标、模型 Git commit/tag、凭据、验证和回滚方案。

已测试的公开 Beta 范围、发布门槛和稳定版阻塞项见 docs/PUBLIC-BETA-READINESS.md。
DSH 0.2.1-rc.2 兼容候选版本的说明见 docs/RELEASE-CANDIDATE-0.4.3-DSH-0.2.0-RC.1.md。
上一个 DSH 0.1.7-rc.2 候选版本的说明见 docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.2.md。
早先的 DSH 0.1.5-rc.2 候选版本记录在 docs/RELEASE-CANDIDATE-0.4.1-DSH-0.1.5-RC.1.md。
原生 Windows 验收说明见 docs/WINDOWS-BETA-ACCEPTANCE.md；数据库凭据有意留在公开仓库之外。

社区发现

DeepSeek Harness 目前不发布官方插件市场。
为了方便被发现，本仓库会带上 GitHub dsh-plugin 话题标签。独立社区目录及其提交规则记录在 docs/COMMUNITY-MARKETPLACES.md；被任何目录收录都属于社区筛选，不代表 DeepSeek 或 Foggy 的认可。

Linux 与 WSL2 体验

Ubuntu 和 WSL2 用户可以使用 experience/linux 下已入库的预检安装器。它把 DSH、其配置档、项目工作区和 Foggy 数据都放在 Linux 原生文件系统上。