JoFe2/kaleidosphere-dsh-plugin

用于 DeepSeek Harness 的 KaleidoSphere

在 DeepSeek Harness 内进行原生数据库分析——只需安装一个插件，无需单独的 KaleidoSphere 检出、服务、端点或启动步骤。

预览兼容性：DeepSeek Harness dsh-v0.1.0-rc.8 / @deepseek-ai/dsh@0.1.0-rc.8，位于 141eb6fef83422698aef7a981029e843e8161534。DSH 是开发者预览版，破坏性更新可能需要发布插件版本。

有关确切的主机、Node.js、操作系统和数据库支持边界，请参阅有证据支持的兼容性矩阵。

安装并试用夹具

安装 DSH 和 pnpm，然后将不可变插件版本添加到 DSH 随附的一次性 agent 配置文件中：

npm install --global @deepseek-ai/dsh@0.1.0-rc.8 pnpm@11.7.0
dsh plugin --profile headless add github:JoFe2/kaleidosphere-dsh-plugin#v0.1.0-preview.4
dsh --profile headless --dump-config
dsh --profile headless "Analyze the configured KaleidoSphere database and report its engine and snapshot digest."

该插件默认使用捆绑的精确 MSSQL 合成夹具，因此无需单独安装 KaleidoSphere 即可立即使用以下六个原生工具：

- kaleidosphere_status
- kaleidosphere_discovery
- kaleidosphere_analyze
- kaleidosphere_plan
- kaleidosphere_preview
- kaleidosphere_readback

典型的 agent 流程是 status → analyze → discovery/plan/preview → readback。每个结果都封装在已发布的 KaleidoSphere External API v2 完整性信封和 K1 证据回执中。意图集来自已发布的 K2 封闭意图契约。使用其他 DSH 界面时，请将同一捆绑包安装到活动的 DSH 配置文件中；该配置文件必须包含 agent 运行器，例如随附的 headless 或 Web 应用。

简短演示：

User: Analyze the configured database, propose a weekly order-value view, and show the readback.
Agent: kaleidosphere_status → kaleidosphere_analyze → kaleidosphere_plan
→ kaleidosphere_preview → kaleidosphere_readback
Result: deterministic fixture snapshot 293a896156d8f6269c4ad33e8d632da653ea180d35a4ea5f390b0be52ce3e44a

配置真实数据源

KaleidoSphere v0.16.0 支持的主要运行时路径是 Microsoft SQL Server 和 Oracle。该插件包含两个必需的客户端路径（包括精确的 Oracle Thin 驱动），因此无需单独的驱动审批或 KS 安装。它直接接受现有的封闭 chimpmaera.db/analyze-profile/v1 对象；它不会发明通用的连接模式。将相关示例复制到 $DSH_HOME/profiles/headless/cordis.patch.yml 并进行调整：

- examples/live-mssql.patch.yml
- examples/live-oracle.patch.yml

将数据库密码放入由 adapter.passwordEnv 命名的环境变量中，然后启动 DSH。插件配置中既不接受密码值，工具也不会返回密码值。

export KS_MSSQL_PASSWORD='...'
dsh --profile headless "分析已配置的 KaleidoSphere 数据库。"

配置的主体必须是只读的。捆绑的 KS 查询包包含允许列表中的元数据 SELECT 语句；原始行、自由 SQL、凭据、源写入以及持久性 Superset 变更均不在本插件的工具范围内。PostgreSQL 仍是有界的 v0.16.0 试点，此处并未将其宣传为主要实时插件路径。

高级工具暴露

默认情况下会暴露全部六个工具。高级配置文件可以将 expose 下的任意单个条目设置为 false；省略的条目保持启用。值必须是布尔值，未知名称会在加载时失败，而禁用全部六个会失败，因为一个没有工具面的捆绑包应当被禁用或移除，而不是保留。参见 examples/intent-exposure.patch.yml。

高级外部运行时

默认的 embedded 模式拥有捆绑运行时，并且仍是单击即可使用的路径。高级配置文件也可以改为通过 runtimeMode: external 绑定一个已在运行的 KaleidoSphere v0.16.0 External API v2 服务；参见 examples/external-runtime.patch.yml。插件在加载时会验证 GET /v2/capabilities 及其确切的产品、契约、能力和证明摘要，然后仅向 POST /v2/intents 发送封闭请求。外部模式不会启动任何 KaleidoSphere 进程，不会创建嵌入式运行时目录，并且会拒绝 source，因为源配置仍由外部安装拥有。

External API v2 在 v0.16.0 中没有传输认证，因此此预览版仅接受带端口且不含路径、凭据、查询或片段的显式回环 HTTP URL。缺失、不兼容、过大、非 JSON 或非 2xx 的运行时都会以失败关闭方式处理。远程绑定需要另行审查的已认证传输契约。

更新、卸载和移除

DSH 拥有捆绑包组合和 HMR。禁用或重新配置 kaleidosphere-dsh-plugin 行会卸载其注册并删除其私有的嵌入式临时配置文件目录。正常关闭也会执行相同操作。外部模式从不拥有或停止现有的 KaleidoSphere 服务。

dsh plugin --profile headless update kaleidosphere-dsh-plugin
dsh plugin --profile headless remove kaleidosphere-dsh-plugin

移除会同时删除配置文件依赖和捆绑包层。插件将 fixture/readback/discovery 状态保留在内存中，不会留下任何服务、端口、后台进程、数据库文件或插件拥有的状态目录。

范围和来源

本仓库提供预构建的 ESM；GitHub 安装不需要 prepare 脚本或构建权限。它在确切提交 5a73ff8146afa0067d226cffa639efde959e8fde 处从 KaleidoSphere v0.16.0 引入了最小分析/API/K1/K2 运行时子集。参见 NOTICE 和引入的 Apache-2.0 许可证。
本预览证明了确定性夹具以及精确的 rc.8 加载/工具/卸载/移除/重新安装生命周期。它并不声称 DSH 稳定 ABI、主机范围的 DSH 安全性、恶意第三方插件遏制、生产就绪、实时客户数据库证据、通用数据库支持、Superset 变更或上游 DeepSeek 认可。

请通过
安全政策中描述的私密路径报告疑似漏洞；切勿在
公开 issue 中发布凭据或漏洞利用细节。

开发

有关 DCO、受保护 PR、兼容性、
来源和证据要求，请参阅 CONTRIBUTING.md。

npm test
npm run verify:package
npm run test:dsh
npm run test:dsh-agent

精确的 DSH 冒烟测试会将打包的 tarball 安装到全新配置文件中，检查 bundle 层和 ACTIVE 工具行，通过 ctx.tools.execute 执行全部六个工具，演练 HMR 卸载/重新加载，移除/重新安装包，并证明作用域临时清理。

agent 冒烟测试默认打包当前候选版本，或接受显式指定的不可变发布 TGZ，将其安装到全新的 rc.8 headless 配置文件中，并通过真实的 headless runner、Agent Loop、面向模型的工具 schema、工具执行器和 KS 夹具发送自然语言任务。其本地确定性模型桩会刻意强制使用 kaleidosphere_analyze；该测试证明的是组装后的 agent 流水线，而不是真实 LLM 在语义上选择了该工具。

npm run verify:release --   还会
在针对下载的字节运行相同的精确主机生命周期之前，
检查不可变的本地或 GitHub 托管的发布资产及其 sidecar。