dsh-zookeeper

DeepSeek Harness (dsh) 插件：访问 Apache ZooKeeper——把 JavaFX 桌面客户端 PrettyZoo 的核心能力搬进 dsh： 浏览器内节点树浏览 / 数据编辑、四字命令（4lw）终端、zkCli 风格 shell，以及 zookeeper_* agent 工具。

• 宿主半（Node / Cordis 插件）经 npm zookeeper （官方 ZooKeeper C 客户端绑定）访问 ZK；
• 浏览器半与 agent 工具都走同一条 connection.fetch.register() 精确路由 （/api/dsh-zookeeper/<endpoint>），原生绑定永远不进浏览器。

构建与检查

npm install
npm run build      # tsc → lib/ + scripts/wrap-client.mjs 包浏览器 bundle
npm run check      # check:plugin + check:parse + check:client 冒烟
npm run typecheck  # tsc --noEmit

配置

「设置 → 插件 → dsh-zookeeper」是 PrettyZoo 原版风格的表单（非 JSON 编辑）：

• 左侧服务器列表（对应 PrettyZoo 主界面 serverListView）：点击行进入编辑， ☆/★ 切换默认服务器，「＋ 新增」新建，「↻」重新读取；
• 右侧表单（对应 PrettyZoo ServerView）：zookeeper host : port、server alias、 连接鉴权（可选 digest:user:password）、ACL 预设（每行一条）、 Connection Config 开关展开高级连接参数（connection timeout / session timeout / max retries / retry interval time）；
• 保存 / 连接测试 / 删除 按钮：连接测试用当前 host:port 内联试连并列出根路径。

存储上 servers 仍是 JSON 字符串（.volatile()，改完即生效），表单负责序列化/反序列化：

[
  {
    "id": "local",
    "host": "127.0.0.1",
    "port": 2181,
    "alias": "本地",
    "auth": "digest:app:secret"
  },
  {
    "id": "prod",
    "host": "zk1.prod.internal",
    "port": 2181,
    "enableConnectionAdvanceConfiguration": true,
    "connectionConfiguration": {
      "maxRetries": 3,
      "retryIntervalTime": 1000,
      "connectionTimeout": 3000,
      "sessionTimeout": 30000
    }
  }
]

字段	说明
id / host / port	必填；缺 port 用 2181，缺 id 自动派生
alias	面板下拉显示名
auth	连接鉴权，digest:user:password（连接后 addauth）
aclList	创建节点的 ACL 预设，如 ["world:anyone:crdwa"]
enableConnectionAdvanceConfiguration + connectionConfiguration	高级连接参数（PrettyZoo 同款：maxRetries / retryIntervalTime / connectionTimeout / sessionTimeout）
defaultServer（独立字段）	默认服务器 id，留空取列表第一项

每个操作都新建连接、用完即关（无状态），配置每次请求现读——面板改完配置无需重启。

浏览器面板

侧边栏底部 ZooKeeper 按钮（sidebar.footer.action）打开浮动面板； 设置页插槽挂配置区；两个插槽都不可用时左下角浮动按钮兜底。

• 树：懒加载展开，节点行显示子节点计数，选中加载详情；
• 详情：stat 表格（version/dataLength/numChildren/ephemeralOwner/ctime/mtime/zxid…）+ 数据编辑框（JSON/XML 自动美化）+ 保存 / 删除（非空时可转递归）/ 查看-编辑 ACL / 复制路径；
• 新建节点：路径 + 7 种 NodeMode（含 sequential / ephemeral / TTL / container）+ 初始数据 + ACL；
• 搜索：contains / exact / prefix / glob / regex，遍历上限 5000 节点；
• 终端：一行输入自动分派——4 个小写字母走 4lw（srvr、ruok、mntr…），其余走 zkCli（ls、get、set、create [-s|-e|-t ttl]、delete、rmr、getAcl、setAcl、sync、help）。

Agent 工具

一次操作一个聚焦工具，全部复用 RPC 分发器（与面板同一条校验路径）：

工具	作用
zookeeper_servers	列出已配置服务器（不知道 server id 时先调它）
zookeeper_list	列出子节点 + stat
zookeeper_get	读节点（stat + text/base64，截断上限 512KB）
zookeeper_create	建节点（mode / ttl / acl / data）
zookeeper_set	写数据（可带 version 乐观锁）
zookeeper_delete	删节点（非空需 recursive）
zookeeper_search	按模式搜路径
zookeeper_execute	4lw 四字命令（srvr / ruok / conf / mntr…）
zookeeper_shell	zkCli 行命令（ls /app、create -e /tmp/x hi…）
zookeeper_acl	查看 / 设置节点 ACL

所有工具都接受 server（服务器 id）；省略时用默认服务器。

RPC 端点

POST /api/dsh-zookeeper/<endpoint>，信封 {type:'client-request', rpcId, method, payload:{args}} → {type:'server-response', rpcId, result:{ok:true,value}|ok:false,error:{code,message,details}} （业务错误保持 HTTP 200，信封畸形 HTTP 400）。

端点：version servers list get create set delete search acl exec shell。

与 PrettyZoo 的功能对照

PrettyZoo	本插件
树形浏览器 / 节点数据编辑 / NodeMode 七种	✅ 面板 + zookeeper_create/set
Terminal（zkCli shell）	✅ shell 端点 / zookeeper_shell
FourLetterCommand（4lw 终端）	✅ exec 端点 / zookeeper_execute
搜索（PathTrie）	✅ search 端点（contains/exact/prefix/glob/regex）
ACL 编辑	✅ 面板 ACL 弹窗 / zookeeper_acl
服务器配置（含高级连接参数）	✅ settings servers JSON
SSH 隧道	❌ 按需裁剪（不做）
ZooKeeper 3.5+	依赖 npm zookeeper 支持的服务器版本（3.5–3.8）

已知边界

• 配置保存依赖 dsh 的 configForms 服务（设置页同款写通道）：通道每次读写现探测， 配置镜像异步就绪前会先等待；若 dsh 版本过旧没有该服务，面板配置只读， 保存会给出可读诊断（列出镜像里已知的命名空间），此时改宿主 profile 的 cordis.patch.yml；
• 通过 RPC 退路读取时 servers 是脱敏快照（auth 密码显示为掩码），状态栏会提示；
• 数据预览超过 512KB 截断（truncated: true），全量取数请用工具/shell；
• 搜索遍历上限 5000 节点（truncated: true 标记）；
• 4lw 需要服务端放开 4lw.commands.whitelist；
• zookeeper npm 包需要预编译/构建的原生绑定，加载失败时 version 端点返回 client.available:false 并附原因（插件本身不崩，面板与工具给可读错误）。

目录

src/index.ts     宿主插件入口（name/inject/Config/apply）
src/settings.ts  配置 schema + volatile 解包 + 服务器解析
src/rpc.ts       RPC 分发器 + ZooKeeper 操作 + 4lw/shell + 路由注册
src/tool.ts      zookeeper_* agent 工具
src/client.ts    浏览器面板（tsc 后由 wrap-client.mjs 包成 CJS 闭包工厂）
scripts/         build / check 脚本