From de70545c701f3b11277d5ba115eb6a360aecc946 Mon Sep 17 00:00:00 2001
From: Jinpy <wanhjp@vip.qq.com>
Date: Wed, 30 Sep 2026 00:57:40 +0800
Subject: [PATCH] docs(plugins): document the options_action launch-options
 contract

---
 .../src/plugins/manifest.rs                   | 12 ++++++----
 plugins/README.md                             | 23 +++++++++++++++++++
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/crates/dbx-plugin-runtime/src/plugins/manifest.rs b/crates/dbx-plugin-runtime/src/plugins/manifest.rs
index ba7d672790..cd8076b786 100644
--- a/crates/dbx-plugin-runtime/src/plugins/manifest.rs
+++ b/crates/dbx-plugin-runtime/src/plugins/manifest.rs
@@ -870,11 +870,13 @@ pub struct PluginOpenWorkbenchAction {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub context: Option<serde_json::Value>,
     /// Generic launch-options extension point: a sidecar method the host calls
-    /// (POST-less invoke, empty params) to fetch dynamic launch entries —
-    /// `{ "entries": [{ "label": string, "description"?: string, "context"?: object }] }`.
-    /// The host renders them as picker items and opens one panel per selection
-    /// with the returned context merged into the host-authored context; the
-    /// host never interprets the entries' business meaning.
+    /// (POST-less invoke, `{ "locale": "en" }` — the current DBX UI locale, so
+    /// entries can be labeled in the user's language) to fetch dynamic launch
+    /// entries — `{ "entries": [{ "label": string, "description"?: string,
+    /// "context"?: object }] }`. The host renders the entries as picker items
+    /// and opens one panel per selection with the returned context merged into
+    /// the host-authored context; the host never interprets the entries'
+    /// business meaning.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub options_action: Option<String>,
     /// When true, the host also offers the plugin's own saved connections
diff --git a/plugins/README.md b/plugins/README.md
index 53eaef9f2e..fd610dcb56 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -494,6 +494,29 @@ For legacy entries without `action`, clicking a connection item dispatches `cont
 
 For a declarative `open-workbench` action, DBX passes the current connection summary as Workbench context for `menu: "connection"`, and the stable `TableContext` object above directly as Workbench context for `menu: "table"` (without the backend `table` envelope). Connection context includes only `id`, `dbType`, `name`, and `database`; the host may also provide the standard `connectionId` for tab association. Neither path includes `host`, `port`, `username`, `password`, a connection string, or raw connection configuration. Reopening the same Workbench refreshes it with the latest invocation context.
 
+#### Declarative launch options (`options_action`)
+
+A dock `command` contribution's `open-workbench` action may declare `options_action: "<sidecar method>"` (context-menu entries cannot: their action form has no such field, and unknown fields are rejected at manifest validation). Before offering launch targets, the host invokes that method with the current UI locale so labels arrive localized:
+
+```json
+{ "locale": "zh-CN" }
+```
+
+The sidecar answers:
+
+```json
+{
+  "entries": [
+    { "label": "Local terminal", "description": "Default shell: /bin/zsh", "context": {} },
+    { "label": "zsh", "description": "/bin/zsh", "context": { "shell": "zsh" } }
+  ]
+}
+```
+
+- `context` is opaque plugin payload: it is merged into the host-authored Workbench context of the panel opened for that entry, and the host never interprets it.
+- A command declaring `options_action` owns the picker: the host's generic replay item hides while `options_action` is declared and does not come back if the sidecar fetch fails or returns nothing — the picker then simply has no launch entries.
+- Plugins ignore the `locale` field safely if they do not localize.
+
 A backend entrypoint is required only for legacy context-menu entries without a declarative action. Their `{ "message": "..." }` result continues to surface as a toast.
 
 ### `filesystem-provider`