dsh-offexplorer

DeepSeek Harness (dsh) 插件：把 offexplorer_rs 的 Kafka 浏览 / 管理能力移植进 dsh。Rust 半基于 rdkafka，经 napi-rs 暴露给 Node 宿主， 再以 /api/offexplorer/* 精确 Fetch 路由和一个 kafka agent 工具对外提供。

结构

src/
  index.ts         插件入口：name / inject / Config / apply
  settings.ts      Config schema + 集群 JSON 规范化（兼容 connections.json PascalCase）
  native.ts        原生模块加载（createRequire → lib/native/index.cjs）
  native-types.ts  原生函数面手写类型
  rpc.ts           RPC 分发器 + connection.fetch.register 路由
  tool.ts          kafka agent 工具
rust/
  src/config.rs    集群配置解析 / 校验 / kinit / GSSAPI 环境
  src/kafka.rs     rdkafka 封装（无状态，每次调用新建客户端）
  src/types.rs     napi 返回结构
  src/lib.rs       #[napi] 导出
  vendor/rdkafka-sys  Windows MIT Kerberos 补丁版（见下）
scripts/
  check-native.mjs 原生模块加载冒烟
  check-plugin.mjs 宿主半冒烟（假 cordis ctx，不连集群）

构建

npm install
npm run build:native   # cargo + napi，产物 lib/native/index.cjs 与 .node
npm run build          # tsc → lib/
npm run check          # check:native + check:plugin

build:native 需要 Rust 工具链、CMake（librdkafka 用 cmake-build 特性现场编译）。 Windows 上首次构建会编译 vendored 的 librdkafka，耗时较长。

配置

插件配置（设置 → 插件 → Offset Explorer）：

{
  "clusters": "[{\"id\":\"prod\",\"name\":\"生产\",\"bootstrapServers\":[\"broker1:9092\"],\"security\":\"SASL_PLAINTEXT\",\"sasl\":\"GSSAPI\",\"krb\":{\"principal\":\"user@REALM\",\"keytabPath\":\"C:/keys/user.keytab\",\"autoKinit\":true}}]",
  "defaultCluster": "prod",
  "maxRows": 100,
  "maxPerPartition": 50,
  "maxValueBytes": 4096
}

• clusters 是 JSON 字符串（schemastery 无数组对象编辑能力），元素兼容 Offset Explorer connections.json 的 PascalCase 字段（BootstrapServers / SASL / TLS / CCachePath / CAPemPath …）。
• security：PLAINTEXT | SSL | SASL_PLAINTEXT | SASL_SSL；sasl： GSSAPI | PLAIN | SCRAM-SHA-256 | SCRAM-SHA-512。
• keytab / 密码等敏感信息只放在 dsh 配置里，不要提交进仓库。

RPC 端点

全部为 POST /api/offexplorer/<endpoint>，信封 {type:'client-request',rpcId,method,payload:{args}} → {type:'server-response',rpcId,result}，result 为 {ok:true,value} 或 {ok:false,error:{code,message,details}}。

endpoint	说明
version / clusters	原生版本 / 集群清单（无需集群连接）
kinit	按集群配置执行一次 Kerberos 取票
ping / clusterInfo / brokers	连通性、cluster id + controller、broker 列表
topics / topicDetail / topicConfigs / brokerConfigs	topic 列表 / 分区明细 / 动态配置
groups / groupDetail	消费者组列表 / 成员与分配
watermarks	单分区 earliest / latest
browse	拉取消息（start: OLDEST / NEWEST / SPECIFIC / TIMESTAMP）
produce / createTopic / deleteTopic / increasePartitions	写入与管理
health	离线分区 / 副本不足 / 离线副本巡检

Agent 工具

宿主半注册一个名为 kafka 的 agent 工具，参数为 { endpoint, args, cluster? }， 直接复用上面的 RPC 分发器（与面板同一条校验路径）。省略 cluster 时用默认集群。 endpoint 在 schema 里是枚举，传错会被参数校验直接拒绝。

列出已配置的 Kafka 集群          → {endpoint:"clusters"}
orders 有哪些分区                → {endpoint:"topicDetail",args:{topic:"orders"}}
看看 orders 最新 20 条消息       → {endpoint:"browse",args:{topic:"orders",start:"NEWEST",limit:20}}
检查集群健康                     → {endpoint:"health"}
往 orders 发一条 hello           → {endpoint:"produce",args:{topic:"orders",value:"hello"}}

produce / createTopic / deleteTopic / increasePartitions 会改动集群， 工具描述里要求模型先与用户确认。GSSAPI 集群在 autoKinit 打开时自动 kinit。

Windows Kerberos 说明

rust/vendor/rdkafka-sys 是打过补丁的 rdkafka-sys 4.10（librdkafka 2.12.1）： 新增 rdkafka_sasl_mit.c，当环境变量 RDKAFKA_SASL_MIT=1 时使用 MIT Kerberos （gssapi64.dll）而不是 SSPI，避免 SSPI 把 SPN 大写导致认证失败。

宿主进程会设置：

• RDKAFKA_SASL_MIT=1（Windows GSSAPI）；
• KRB5_CONFIG（若配置了 krb.krb5ConfPath）；
• KRB5CCNAME=FILE:<ccache>（autoKinit 或 kinit 端点成功后）。

autoKinit 使用 kinit -c FILE:<ccache> -k -t <keytab> <principal>。 默认 ccache 为 %TEMP%\dsh_offexplorer_krb5cc_<principal>。

安全 / 开发约定

• 冒烟脚本只做本地断言，不连接任何集群；联调请使用本地或测试集群。
• TLS / SCRAM 相关配置项已归一化传递，但当前构建未启用 rdkafka 的 ssl / sasl 扩展特性（与 offexplorer_rs 的构建面保持一致），连接时若服务端强制 TLS 会得到明确的客户端错误。
• 原生模块加载失败不会让 apply 抛错：version / clusters 仍可用，其余端点 返回可读错误。