dsh-dbhub-live: Instructions file for Codex

AGENTS.md — dsh-dbhub-live 开发与调试说明

本文件面向在本仓库上继续开发/调试本插件的 AI 与人。业务需求见 doc/REQUIREMENTS.md，用户安装使用见 README.md。

一句话定位

DSH host 插件（Node ESM）+ Web client 插件（浏览器半）：把 dbhub（Bytebase 的数据库 MCP 服务器）接入 DSH。零知识凭据管理 + 一次性进程执行——DSN/密码只存在于宿主侧，模型只见 source 句柄与元数据（类型/主机/端口/库）；每次工具调用 spawn 一条独立 dbhub --dsn 进程跑完即杀，无常驻服务。附设置在「设置 → 插件」里的实时状态卡片与启用/禁用开关。

目录结构

lib/
  index.mjs    入口：name/inject/apply、状态命名空间(schemastery)接线、后台启动(仅登记+更新检查)、配置变更应用
  config.mjs   路径/原子持久化(store,runtime)/DSN 解析/工作区发现/零知识助手(describeConn,connLabel,scrubSecrets)/小工具
  state.mjs    运行时状态机：enabled/phase/toolCount/lastError/mode + 订阅发布（无服务器生命周期）
  options.mjs  可配置参数：updateIntervalDays（设置UI > 环境默认；dbhubPackage 仅内部环境knob）
  runtime.mjs  dbhub 可执行文件发现、按需自动安装、定期自动更新（已删除孤儿进程清理）
  mcp.mjs      MCP JSON-RPC 客户端 + 工具注册表 + 工作区×环境来源发现（collectSources/resolveSource）+ 摘要缓存
  adhoc.mjs    唯一执行引擎：每次调用一条一次性 dbhub 进程（零知识标签 + stderr 清洗）
  collect.mjs  授权扫描项目配置文件并提取 DSN 候选（含 askUser 桥接）
  tools.mjs    host 自有工具定义与注册：恒定 4 个（configure/list_sources/execute_sql/search_objects）
  client.js    Web 半（手写 lazy-CJS bundle）：折叠分区卡片（状态/配置/工作区连接）
test/          node:test 单元测试（纯逻辑 + client bundle 格式契约 + 零知识泄漏门）
doc/           需求文档
cordis.patch.yml   bundle patch：`name: dsh-dbhub-live` 挂载本包

关键架构事实

• 模块依赖只进不出（防环）：config ← state ← mcp；config ← runtime ← adhoc；mcp ← tools ← index；adhoc ← tools；collect ← tools。禁止反向或循环 import（HMR/装载顺序依赖它）。零知识助手（describeConn/connLabel/scrubSecrets）在 config.mjs，任何模块不得把裸 DSN 直接拼进用户可见文本。
• 无常驻 dbhub 服务器：dbhub_execute_sql / dbhub_search_objects 在调用时把 source 经 resolveSource 解成真实 DSN（宿主侧），然后走 runAdhoc（dbhub --transport stdio --dsn <dsn> 一次性进程，跑完 terminate）。没有 toml/指纹/mtime 监听/空闲回收/respawn/孤儿清理/配置变更重启。执行天然并发（进程级隔离）、故障隔离（一条进程挂只坏它自己）、多实例安全（无共享端口/无共享 toml/无跨实例误杀）。不要把常驻服务器那套装回来。
• 零知识模型契约（红线）：
  1. 工具参数：source/sql/object_type 等 + configure 的非密预填（type/host/port/database/user）。任何工具都不得声明 dsn 参数（模型传 DSN 会把密码带进上下文）；configure 收到 args.dsn 直接拒绝（result.noDsnViaModel）。dbhub_query/dbhub_query_objects 已删除，勿恢复。
  2. 工具输出：结果/列表/标签一律 connLabel(dsn)（type://host:port/db）或 i18n 模板，密码与用户名永不出现；dbhub 返回的文本（含 stderr）进模型前必须过 scrubSecrets(text, dsn)。
  3. 密码只在界面输入：configure 的密码/完整 DSN 一律经 askUser（用户敲键盘，不经模型上下文）；设置卡片 add/edit 的 DSN 走 configOp 通道（浏览器→Host），同样不进模型上下文。
  4. 鉴权/连接失败闭环：likelyAuthOrConnError 命中时在错误文本后附 result.authHint（引导 dbhub_configure 或设置卡片修改，密码由用户输入）。
  5. 零密码泄漏门：test/zero-knowledge.test.mjs 断言 summarizeRows 无 dsn 字段、无工具声明 dsn 参数、描述/i18n 文案不含真实形态 DSN；util.test 断言 scrubSecrets/connLabel 行为。改模型可见文案时这些测试必须保持绿。
• 状态命名空间：Host 注册 dsh-dbhub-live 命名空间（ctx.inject(['settings'], …) + schema）；Web 端 Plugins 选项卡按命名空间分发 settings.plugin.item 卡片。命名空间值 = 状态 {enabled, phase(running|disabled), toolCount(恒定4), lastError, mode('oneshot')} + 配置 {updateIntervalDays} + {workspaces(JSON 元数据摘要：title/path/env/conn(主机端口库)/source/persisted/srcId)} + {configOp}（主机消费后自动清空）+ {testResult}（连接测试的一次性回执，仅内存态、不落任何持久化）。注入回调是独立作用域：内部需要的服务（如 subprocess）必须用 ctx.get('subprocess') 就地获取，绝不能引用 apply() 的局部变量——否则 ReferenceError 会静默杀死整条发布/配置链路（卡片只剩静态值、工作区连接不刷新）。回调整体套 wrap() 防护，异常必须打日志。
• 可配置参数：options.mjs 只此一处持有部署开关：updateIntervalDays（设置 UI > 环境变量种子 > 内置默认；dbhubPackage 仅环境变量/内部，不进设置）。已删除 idleMinutes（无常驻进程可回收）。不要绕过 applyPatch 直接改 options 内部值。
• 工作区连接管理（configOp 通道）：store v2 = { [wsPath]: { environments: { [env]: {dsn, source, updatedAt} } } }（v1 单 dsn 条目自动迁移进 environments.default）。卡片只读元数据摘要（collectSources → latestSummaries，密码/用户名永不出 Host）；增/改/删通过命名空间 configOp 单向命令下发，index.mjs 用 setWorkspaceEnv/removeWorkspaceEnv 落盘后重扫摘要并发布（configOp 随发布清空，天然防环）。自动发现（mise/.env）只提供未覆盖的 default，不持久化。连接测试（{op:'test', workspace, env, nonce}）：handleTestOp 用摘要背后的真实 DSN 调 adhoc.probeConnection（一次性 dbhub + SELECT 1，Host 侧 30s 超时兜底），结果经 testResult 镜像字段回推 {nonce, ok, message}；测试失败只是行内一次性提示，不得写入 store/lastError/phase。卡片只认自己派发过的 nonce，展示 ~10s 自动消退，刷新即失，天然不保留状态。
• 工具声明数量恒定（上下文预算红线）：恒定 4 个（configure / list_sources / execute_sql / search_objects），绝不为每个工作区 × 环境注册独有工具；dbhub_execute_sql(source,…) / dbhub_search_objects(source,…) 调用时 resolveSource 按 source 值（标题_hash[_环境]）解析到真实连接。曾实现过的 per-source 注册与 dbhub_query 临时连接工具已移除，勿回恢复。
• schema 弹性依赖：优先用真实 @deepseek-ai/schemastery schema（await import）；解析失败时降级为 lib/index.mjs 内建的最小 callable schema（schema(v) 合默认值 + toJSON()），保证链路安装（dsh plugin add <本地目录>，Node ESM 按源码真实路径解析裸导入）下插件照样启动、卡片照常工作。tarball/npm 安装（真实目录在 profile node_modules 下）走真实 schemastery 路径。不要把这个 import 改回静态顶层 import——会重新引入链路安装时启动失败。
• 执行时机：apply() 只注册核心工具 + 后台 bookkeeping（startBackgroundBoot：置 phase running、刷新工具数、非阻塞检查 dbhub 自动更新）；真正的 dbhub 解析（persisted → mise → PATH → 自动安装）发生在每次调用（resolveDbhubExe 有 runtime.json 缓存，首次或缺二进制时才安装）。无工作区数据源时一切照常——工具正常注册，list_sources 返回空、execute 返回 noSource，不会拉起任何进程。
• 启用/禁用：state.setEnabled 持久化到 credentials.json（权威值）；禁用时所有工具 execute 首行返回「插件已禁用」（无进程可停，无需清理）；重新启用即恢复。