25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
docs: clarify safe plugin tool lifecycle patterns
Qing Liang065171bc182e
diff --git a/docs/content/docs/plugin-development.cn.mdx b/docs/content/docs/plugin-development.cn.mdxindex c2e8adefde..e9d8e75c27 100644--- a/docs/content/docs/plugin-development.cn.mdx+++ b/docs/content/docs/plugin-development.cn.mdx@@ -902,6 +902,14 @@ Sidecar 约束:stdout 只能输出协议消息,日志写 stderr;请求 ID同样的工具也会出现在外部 `dbx` MCP 服务器(Claude Code、Cursor 等)上,名称为 `dbx_<前缀>__<工具名>`,并受全局 MCP 设置(工具白名单 + 连接白名单)约束、绑定到插件已保存的连接。该面按作者声明加入:manifest 中的 `mcp` 贡献声明 `external_tools: true` 才会暴露;连接选择参数为 `dbx_connection`。+### 有状态工具的生命周期与失败语义++对于管理监听器、后台会话或可丢弃故障实验的插件,请将资源管理与工具发现分开:++- **发现只描述,显式调用才执行。** `mcp/tools` 不应创建插件自己的监听器、连接数据库或注入故障。宿主可能为了发现工具而启动 Sidecar,但这不代表允许启动插件的实际工作负载。外部客户端需要管理会话时,请提供明确的修改型 start/stop 工具,并限制会话数量、时长和清理时间。不要将生命周期变更标为只读。+- **执行时检查策略。** 发现阶段隐藏写工具不能代替授权。在 `mcp/call` 执行操作前,应验证宿主绑定的连接身份及本次调用可用的策略。故障实验插件应在连接只读或插件自身未开启故障注入时拒绝注入。这些是插件自己的检查,MCP 标注不会授予额外权限。内置 Agent 使用已打开连接的 lifecycle 快照,外部 MCP 后端则在调用时依据宿主保存的连接配置生成载荷。不要假定修改已保存连接后,运行中会话的配置就会刷新;若插件无法安全协调变更,应要求停止并重新启动会话。+- **如实报告不确定结果。** PostgreSQL `COMMIT` 已转发后发生超时或断连,不能证明事务已回滚。除非通过独立检查确定了结果,否则应报告事务结果为 `unknown`;不要自动重试可能已经提交的写操作。应区分注入的传输事件与数据库结果,分别验证已提交数据和锁清理。这是事务感知插件的设计模式,不是 DBX 提供的通用事务状态 API。+## 创建插件直接安装预编译 CLI,不需要 Rust,也不需要克隆 DBX 源码:diff --git a/docs/content/docs/plugin-development.mdx b/docs/content/docs/plugin-development.mdxindex 049079205b..0b11c20f2b 100644--- a/docs/content/docs/plugin-development.mdx+++ b/docs/content/docs/plugin-development.mdx@@ -903,6 +903,14 @@ What the host adds on top:The built-in agent treats tool output as untrusted data. Return facts, not instructions, and never echo secrets in results.+### Lifecycle and failure semantics for stateful tools++For plugins that manage listeners, background sessions, or disposable fault experiments, keep resource ownership separate from tool discovery:++- **Discovery describes; explicit calls act.** Keep `mcp/tools` free of plugin-owned listener creation, database connections, and fault injection. The host may start a sidecar to discover its tools; that is not permission to start the plugin's workload. Expose explicit mutating start/stop tools when external clients need to manage a session, and bound session count, duration, and cleanup. Do not mark lifecycle changes as read-only.+- **Check policy when executing.** Hiding a write tool during discovery is not authorization. In `mcp/call`, validate the host-bound connection identity and the policy available for that call before acting. A fault-lab plugin should reject injection when its connection is read-only or its own injection opt-in is off. These are plugin checks, not extra permissions granted by an MCP annotation. The built-in agent uses the open connection's lifecycle snapshot; the external MCP backend builds it from the host's saved-connection configuration at call time. Do not assume an open session's configuration refreshes when a saved connection changes; require a stop/restart if your plugin cannot safely reconcile the change.+- **Report uncertain outcomes honestly.** A timeout or broken connection after forwarding PostgreSQL `COMMIT` does not prove rollback. Report the transaction outcome as `unknown` unless it has been established independently; do not automatically retry a possibly committed write. Distinguish the injected transport event from the database outcome, and test committed data and lock cleanup separately. This is a design pattern for transaction-aware plugins, not a generic transaction-status API supplied by DBX.+## Create a PluginInstall the precompiled CLI without Rust or a DBX source checkout: