@logictan/dsh-desktop-agent 0.1.5 → 0.1.7

package/lib/client.js

@@ -9,12 +9,14 @@
  * `<bundle>#desktop-agent`, the key the Plugins page derives from the bundle
  * that declares the row.
  *
- * The field list mirrors the schema in `src/config.js`; the two are kept in step
- * by hand because this half ships as plain browser code.
+ * The card renders the host's `Config` schema through the shared `ConfigForm`.
+ * Scalar fields are rendered automatically from the describe mirror; this half
+ * supplies only the vision-catalog dropdowns (replacing the route fields via
+ * `renderControl`) and the catalog status banners in `children`.
  *
  * Two catalogs feed this card, and they are not interchangeable:
  *
- *  - The VISION list comes from this plugin's own loopback route
+ *  - The VISION list comes from this plugin's own same-origin route
  *    (`/api/dsh-desktop-agent/vision-models`). It has to: the host's
  *    `session.modelCatalog` does not carry `inputModalities` at all — its
  *    builder maps a fixed set of fields off the resolved model info and drops
@@ -33,6 +35,7 @@ window.__ModuleLoader__.load({
   id: "@logictan/dsh-desktop-agent",
   factory: function (require) {
     var React = require("react");
+    var UI = require("@logictan/dsh-plugins-shared-client");
 
     /** Loader entry id this card's form is keyed by. */
     var NS = "desktop-agent";
@@ -58,10 +61,6 @@ window.__ModuleLoader__.load({
       intro:
         "用截图作为主要感知、通过 Cua Driver 操作桌面窗口。留空表示继承默认值。需先在 profile 挂载 computer-use 的 cua-driver-native provider。",
       inherit: "继承默认",
-      save: "保存",
-      saving: "保存中…",
-      reset: "恢复默认",
-      overridden: "已覆盖",
       unwritable: "当前连接不写回本机设置，无法保存。",
       catalogLoading: "正在读取视觉模型目录…",
       catalogError: "视觉模型目录读取失败，可切换为手填。",
@@ -72,149 +71,8 @@ window.__ModuleLoader__.load({
       manual: "手填",
       picker: "从目录选择",
       routeMissing: "已存的路由不在当前目录中（provider 读取失败或模型已下线），已切换为手填。",
-      deliveryBackground: "后台投递（默认）",
-      deliveryForeground: "前台投递（画布/游戏）",
     };
 
-    /**
-     * Editable fields, in render order. `kind` picks the control.
-     *
-     * The three vision-route keys are rendered together below the catalog picker
-     * and are listed here only so that override detection, save, and reset see
-     * them.
-     */
-    var FIELDS = [
-      {
-        key: "maxSteps",
-        label: "步数上限",
-        kind: "number",
-        min: 1,
-        step: 1,
-        hint: "一次任务最多执行多少个动作，默认 40。",
-      },
-      {
-        key: "maxImageDimension",
-        label: "截图长边上限",
-        kind: "number",
-        min: 200,
-        step: 1,
-        hint: "送给模型的截图最长边（像素），默认 1568。调小可省 token，但太小会看不清控件。",
-      },
-      {
-        key: "deliveryMode",
-        label: "投递方式",
-        kind: "select",
-        options: [
-          { value: "background", label: copy.deliveryBackground },
-          { value: "foreground", label: copy.deliveryForeground },
-        ],
-        hint: "后台投递不抢焦点；游戏等自绘表面会过滤按 pid 路由的事件，需要前台投递。",
-      },
-      {
-        key: "allowBringToFront",
-        label: "允许抢前台",
-        kind: "checkbox",
-        hint: "关闭时模型不能使用 bring_to_front。开启后模型可把目标窗口提到最前，代价是抢走你当前的焦点；仅当窗口被压在后台、内容不刷新时才需要。",
-      },
-    ];
-
-    /** The three vision route fields, rendered together below the catalog. */
-    var ROUTE_KEYS = ["visionProvider", "visionModel", "visionReasoningEffort"];
-
-    var wrapStyle = {
-      display: "flex",
-      flexDirection: "column",
-      gap: "12px",
-      maxWidth: "620px",
-      color: "var(--dsw-alias-label-primary)",
-      fontSize: "13px",
-      lineHeight: 1.6,
-    };
-    var headingStyle = { fontSize: "14px", fontWeight: 600 };
-    var hintStyle = { color: "var(--dsw-alias-label-tertiary)" };
-    var rowStyle = { display: "flex", alignItems: "center", gap: "8px", flexWrap: "wrap" };
-    var fieldStyle = { display: "flex", alignItems: "center", gap: "8px", flexWrap: "wrap" };
-    var labelStyle = { minWidth: "140px" };
-    var controlStyle = {
-      padding: "6px 8px",
-      border: "1px solid var(--dsw-alias-border-l2)",
-      borderRadius: "6px",
-      background: "var(--dsw-alias-bg-layer-1)",
-      color: "inherit",
-      font: "inherit",
-      fontVariantNumeric: "tabular-nums",
-    };
-    var inputStyle = Object.assign({ width: "132px" }, controlStyle);
-    var textStyle = Object.assign({ width: "260px" }, controlStyle);
-    var selectStyle = Object.assign({ minWidth: "200px" }, controlStyle);
-    var buttonStyle = {
-      padding: "6px 12px",
-      border: "1px solid var(--dsw-alias-border-l2)",
-      borderRadius: "6px",
-      background: "var(--dsw-alias-bg-layer-1)",
-      color: "inherit",
-      font: "inherit",
-      cursor: "pointer",
-    };
-    var primaryButtonStyle = Object.assign({}, buttonStyle, {
-      border: "1px solid var(--dsw-alias-button-primary-fill)",
-      background: "var(--dsw-alias-button-primary-fill)",
-      color: "var(--dsw-alias-label-primary-foreground)",
-    });
-    var errorStyle = { color: "var(--dsw-alias-state-error-primary)" };
-    var badgeStyle = {
-      padding: "1px 6px",
-      borderRadius: "999px",
-      background: "var(--dsw-alias-bg-layer-2, rgba(0, 0, 0, 0.08))",
-      color: "var(--dsw-alias-label-secondary)",
-      fontSize: "12px",
-    };
-
-    function has(object, key) {
-      return Object.prototype.hasOwnProperty.call(object, key);
-    }
-
-    function objectLayer(snapshot, which) {
-      var layer = snapshot && snapshot[which];
-      return layer !== null && typeof layer === "object" ? layer : {};
-    }
-
-    /** The schema-resolved section the Host last accepted. */
-    function accepted(snapshot) {
-      return objectLayer(snapshot, "value");
-    }
-
-    /** The raw user layer; a key's presence here is what marks it overridden. */
-    function userLayer(snapshot) {
-      return objectLayer(snapshot, "user");
-    }
-
-    function overridden(snapshot, key) {
-      return has(userLayer(snapshot), key);
-    }
-
-    /** The effective value for a field, as the string a control holds. */
-    function stored(snapshot, key) {
-      var value = accepted(snapshot)[key];
-      return value === undefined || value === null ? "" : String(value);
-    }
-
-    /**
-     * Parse a draft string into the value to store.
-     * @throws {Error} when the draft does not satisfy the field's schema.
-     */
-    function parse(field, raw) {
-      if (field.kind === "text") return raw;
-      if (field.kind === "select") return raw;
-      if (field.kind === "checkbox") return raw === "true";
-      var value = Number(raw);
-      if (!isFinite(value)) throw new Error(field.label + "必须是数字。");
-      if (field.step === 1 && !Number.isInteger(value)) throw new Error(field.label + "必须是整数。");
-      if (field.min !== undefined && value < field.min) throw new Error(field.label + "不能小于 " + field.min + "。");
-      if (field.max !== undefined && value > field.max) throw new Error(field.label + "不能大于 " + field.max + "。");
-      return value;
-    }
-
     /**
      * Load this plugin's own vision-capable model list.
      *
@@ -328,11 +186,15 @@ window.__ModuleLoader__.load({
      * The row's configuration card.
      *
      * `scope` is the configuration form `apply` obtained for this entry from
-     * `configForms.get(NS)`; `ctx` is the scoped context it was obtained on,
-     * which supplies both catalogs.
+     * `configForms.get(NS)`; `describe` is the schema mirror obtained from
+     * `configForms.describe()`; `ctx` is the scoped context supplying the live
+     * model directory.
      */
     function DesktopAgentSettingsCard(props) {
+      if (props.view === "summary") return copy.summary;
+
       var scope = props.scope;
+      var describe = props.describe;
       var ctx = props.ctx;
 
       var subscribe = React.useCallback(
@@ -352,417 +214,152 @@ window.__ModuleLoader__.load({
       var catalog = useVisionCatalog(ctx);
       var host = useHostCatalog(ctx);
 
-      var draftState = React.useState({});
-      var draft = draftState[0];
-      var setDraft = draftState[1];
-      var busyState = React.useState(false);
-      var busy = busyState[0];
-      var setBusy = busyState[1];
-      var errorState = React.useState(null);
-      var error = errorState[0];
-      var setError = errorState[1];
       /** Whether the user chose to type the route instead of picking it. */
       var manualState = React.useState(false);
       var manual = manualState[0];
       var setManual = manualState[1];
 
-      if (props.view === "summary") return copy.summary;
-
       var writable = snapshot.writable === true;
-      var current = accepted(snapshot);
-
-      /** Record one field's draft, leaving the others untouched. */
-      function edit(key, value) {
-        setDraft(function (previous) {
-          var next = {};
-          for (var name in previous) if (has(previous, name)) next[name] = previous[name];
-          next[key] = value;
-          return next;
-        });
-      }
+      var current = snapshot && snapshot.value && typeof snapshot.value === "object" ? snapshot.value : {};
 
-      /**
-       * Stage several fields at once.
-       *
-       * Picking a provider clears the model and the effort, because both belong
-       * to the previous provider and would otherwise be saved as a route the
-       * Host cannot resolve.
-       */
-      function editMany(patch) {
-        setDraft(function (previous) {
-          var next = {};
-          for (var name in previous) if (has(previous, name)) next[name] = previous[name];
-          for (var key in patch) if (has(patch, key)) next[key] = patch[key];
-          return next;
-        });
-      }
-
-      var allFields = FIELDS.concat([
-        { key: "visionProvider", label: "视觉 provider", kind: "text" },
-        { key: "visionModel", label: "视觉 model", kind: "text" },
-        { key: "visionReasoningEffort", label: "视觉 reasoning effort", kind: "text" },
-      ]);
-
-      /** Whether a field currently carries a user override. */
-      function isOverridden(field) {
-        return overridden(snapshot, field.key);
-      }
+      var groups = catalog.value.groups || [];
+      var provider = typeof current.visionProvider === "string" ? current.visionProvider : "";
+      var model = typeof current.visionModel === "string" ? current.visionModel : "";
+      var selected = matchModel(groups, provider, model);
 
-      // Every field whose draft no longer matches what is stored. A draft that
-      // is an empty string means "clear the override", which is a real edit
-      // whenever a value is currently in effect.
-      var edits = [];
-      var invalid = null;
-      allFields.forEach(function (field) {
-        if (!has(draft, field.key)) return;
-        var raw = draft[field.key];
-        if (raw === "") {
-          if (isOverridden(field)) edits.push({ field: field, raw: raw });
-          return;
-        }
-        var value;
-        try {
-          value = parse(field, raw);
-        } catch (cause) {
-          if (invalid === null) invalid = String((cause && cause.message) || cause);
-          return;
-        }
-        if (String(value) !== String(current[field.key])) edits.push({ field: field, raw: raw, value: value });
+      var providers = [];
+      groups.forEach(function (group) {
+        if (providers.indexOf(group.id) === -1) providers.push(group.id);
       });
-
-      var anyOverridden = allFields.some(isOverridden);
-      var dirty = edits.length > 0;
-      var blocked = busy || invalid !== null;
-
-      /** Persist every edit, in order, one write at a time. */
-      function save() {
-        if (!dirty || blocked) return;
-        setError(null);
-        setBusy(true);
-        var chain = Promise.resolve();
-        edits.forEach(function (item) {
-          chain = chain.then(function () {
-            return item.raw === "" ? scope.unset(item.field.key) : scope.set(item.field.key, item.value);
-          });
+      var modelsForProvider = [];
+      groups.forEach(function (group) {
+        if (group.id !== provider) return;
+        (group.models || []).forEach(function (entry) {
+          modelsForProvider.push(entry);
         });
-        chain.then(
-          function () {
-            setBusy(false);
-            setDraft({});
-          },
-          function (cause) {
-            setBusy(false);
-            setError(String((cause && cause.message) || cause));
-          },
-        );
-      }
+      });
 
-      /** Drop every override so the fields re-inherit the composition values. */
-      function reset() {
-        if (busy) return;
-        var keys = allFields
-          .filter(function (field) {
-            return isOverridden(field);
-          })
-          .map(function (field) {
-            return field.key;
-          });
-        if (keys.length === 0) return;
-        setError(null);
-        setDraft({});
-        setBusy(true);
-        var chain = Promise.resolve();
-        keys.forEach(function (key) {
-          chain = chain.then(function () {
-            return scope.unset(key);
-          });
-        });
-        chain.then(
-          function () {
-            setBusy(false);
-          },
-          function (cause) {
-            setBusy(false);
-            setError(String((cause && cause.message) || cause));
-          },
-        );
-      }
+      var routeLost = (provider !== "" || model !== "") && selected === null;
+      var pickable = catalog.value.status === "ready" && providers.length > 0;
+      var usePicker = pickable && !manual && !routeLost;
 
-      /** The draft for a key, or the stored value. */
-      function rawOf(key) {
-        return has(draft, key) ? draft[key] : stored(snapshot, key);
-      }
+      function renderControl(field) {
+        if (!usePicker) {
+          return undefined;
+        }
 
-      var children = [
-        React.createElement("div", { key: "heading", style: headingStyle }, copy.heading),
-        React.createElement("div", { key: "intro" }, copy.intro),
-      ];
-
-      FIELDS.forEach(function (field) {
-        var disabled = !writable || busy;
-        var control;
-        if (field.kind === "select") {
-          control = React.createElement(
-            "select",
-            {
-              style: selectStyle,
-              value: rawOf(field.key),
-              disabled: disabled,
-              "aria-label": field.label,
-              onChange: function (event) {
-                edit(field.key, event.target.value);
-              },
-            },
-            field.options.map(function (option) {
-              return React.createElement("option", { key: option.value, value: option.value }, option.label);
-            }),
-          );
-        } else if (field.kind === "checkbox") {
-          control = React.createElement("input", {
-            type: "checkbox",
-            checked: rawOf(field.key) === "true",
-            disabled: disabled,
-            "aria-label": field.label,
-            onChange: function (event) {
-              edit(field.key, event.target.checked ? "true" : "false");
-            },
-          });
-        } else if (field.kind === "number") {
-          control = React.createElement("input", {
-            type: "number",
-            min: field.min,
-            max: field.max,
-            step: field.step,
-            style: inputStyle,
-            value: rawOf(field.key),
-            disabled: disabled,
+        if (field.key === "visionProvider") {
+          return React.createElement(UI.Select, {
+            value: provider,
+            disabled: !writable,
+            label: "视觉 provider",
             placeholder: copy.inherit,
-            "aria-label": field.label,
-            onChange: function (event) {
-              edit(field.key, event.target.value);
-            },
-            onKeyDown: function (event) {
-              if (event.key === "Enter") save();
+            options: [{ value: "", label: copy.inherit }].concat(
+              providers.map(function (id) {
+                return { value: id, label: id };
+              }),
+            ),
+            onChange: function (value) {
+              var ops = [
+                value === "" ? { op: "unset", path: ["visionProvider"] } : { op: "set", path: ["visionProvider"], value: value },
+                { op: "unset", path: ["visionModel"] },
+                { op: "unset", path: ["visionReasoningEffort"] },
+              ];
+              void scope.mutate(ops, snapshot.revision);
             },
           });
-        } else {
-          control = React.createElement("input", {
-            type: "text",
-            style: textStyle,
-            value: rawOf(field.key),
-            disabled: disabled,
+        }
+
+        if (field.key === "visionModel") {
+          return React.createElement(UI.Select, {
+            value: selected === null ? "" : model,
+            disabled: !writable || provider === "",
+            label: "视觉 model",
             placeholder: copy.inherit,
-            "aria-label": field.label,
-            onChange: function (event) {
-              edit(field.key, event.target.value);
-            },
-            onKeyDown: function (event) {
-              if (event.key === "Enter") save();
+            options: [{ value: "", label: copy.inherit }].concat(
+              modelsForProvider.map(function (entry) {
+                return { value: entry.id, label: entry.name || entry.id };
+              }),
+            ),
+            onChange: function (value) {
+              var ops = [
+                value === "" ? { op: "unset", path: ["visionModel"] } : { op: "set", path: ["visionModel"], value: value },
+                { op: "unset", path: ["visionReasoningEffort"] },
+              ];
+              void scope.mutate(ops, snapshot.revision);
             },
           });
         }
 
-        children.push(
-          React.createElement(
-            "div",
-            { key: field.key, style: fieldStyle },
-            React.createElement("span", { style: labelStyle }, field.label),
-            control,
-            isOverridden(field) ? React.createElement("span", { style: badgeStyle }, copy.overridden) : null,
-          ),
-        );
-        if (field.hint) {
-          children.push(React.createElement("div", { key: field.key + "-hint", style: hintStyle }, field.hint));
+        if (field.key === "visionReasoningEffort") {
+          var hostEntry = matchModel(host.groups, provider, model);
+          var reasoning = (hostEntry && hostEntry.reasoning) || null;
+          var effortOptions = reasoning ? reasoning.efforts || [] : [];
+          if (effortOptions.length > 0) {
+            var currentEffort = typeof current.visionReasoningEffort === "string" ? current.visionReasoningEffort : "";
+            var effortValue = currentEffort || reasoning.defaultEffort || "";
+            return React.createElement(UI.Select, {
+              value: effortValue,
+              disabled: !writable,
+              label: "视觉 reasoning effort",
+              placeholder: copy.inherit,
+              options: [{ value: "", label: copy.inherit }].concat(
+                effortOptions.map(function (effort) {
+                  return { value: effort.id, label: effort.name || effort.id };
+                }),
+              ),
+              onChange: function (value) {
+                var ops = [
+                  value === ""
+                    ? { op: "unset", path: ["visionReasoningEffort"] }
+                    : { op: "set", path: ["visionReasoningEffort"], value: value },
+                ];
+                void scope.mutate(ops, snapshot.revision);
+              },
+            });
+          }
+          if (reasoning) {
+            return React.createElement("div", { className: "dsp-field-hint" }, copy.effortNone);
+          }
+          return React.createElement(UI.Select, {
+            value: "",
+            disabled: true,
+            label: "视觉 reasoning effort",
+            placeholder: copy.inherit,
+            options: [{ value: "", label: copy.inherit }],
+            onChange: function () {},
+          });
         }
-      });
-
-      children.push(
-        React.createElement("hr", {
-          key: "route-sep",
-          style: { border: "none", borderTop: "1px solid var(--dsw-alias-border-l2)", margin: "4px 0" },
-        }),
-      );
-      children.push(React.createElement("div", { key: "route-heading", style: headingStyle }, "视觉模型路由"));
-      children.push(
-        React.createElement(
-          "div",
-          { key: "route-hint", style: hintStyle },
-          "每步决策用哪个模型看图。全空 = 用会话当前模型；会话模型不支持图像时自动走 AX 元素表。",
-        ),
-      );
 
-      var groups = catalog.value.groups || [];
-      var provider = rawOf("visionProvider");
-      var model = rawOf("visionModel");
-      var selected = matchModel(groups, provider, model);
-      var providers = [];
-      groups.forEach(function (group) {
-        if (providers.indexOf(group.id) === -1) providers.push(group.id);
-      });
-      var modelsForProvider = [];
-      groups.forEach(function (group) {
-        if (group.id !== provider) return;
-        (group.models || []).forEach(function (entry) {
-          modelsForProvider.push(entry);
-        });
-      });
+        return undefined;
+      }
 
-      // The dropdown is usable only when the catalog loaded AND a provider is
-      // available. A stored route the catalog no longer offers (a provider that
-      // failed to load, or a model removed upstream) is never silently
-      // rewritten: the card falls back to manual entry and says so.
-      var pickable = catalog.value.status === "ready" && providers.length > 0;
-      var usePicker = pickable && !manual;
+      var children = [];
 
       if (catalog.value.status === "loading") {
-        children.push(React.createElement("div", { key: "catalog-status", style: hintStyle }, copy.catalogLoading));
+        children.push(React.createElement(UI.Banner, { key: "catalog-status", kind: "info" }, copy.catalogLoading));
       } else if (catalog.value.status === "error") {
-        children.push(React.createElement("div", { key: "catalog-status", style: errorStyle }, copy.catalogError));
+        children.push(React.createElement(UI.Banner, { key: "catalog-status", kind: "error" }, copy.catalogError));
       } else if (providers.length === 0) {
-        children.push(React.createElement("div", { key: "catalog-status", style: hintStyle }, copy.catalogEmpty));
+        children.push(React.createElement(UI.Banner, { key: "catalog-status", kind: "info" }, copy.catalogEmpty));
       } else if (catalog.value.failures > 0) {
-        children.push(React.createElement("div", { key: "catalog-status", style: hintStyle }, copy.catalogPartial));
+        children.push(React.createElement(UI.Banner, { key: "catalog-status", kind: "warn" }, copy.catalogPartial));
       }
 
-      if (usePicker) {
-        children.push(
-          React.createElement(
-            "div",
-            { key: "route-provider", style: fieldStyle },
-            React.createElement("span", { style: labelStyle }, "provider"),
-            React.createElement(
-              "select",
-              {
-                style: selectStyle,
-                value: provider,
-                disabled: !writable || busy,
-                "aria-label": "视觉 provider",
-                onChange: function (event) {
-                  // The previous model and effort belong to the previous
-                  // provider, so they are cleared together with it.
-                  editMany({ visionProvider: event.target.value, visionModel: "", visionReasoningEffort: "" });
-                },
-              },
-              [React.createElement("option", { key: "", value: "" }, copy.inherit)].concat(
-                providers.map(function (id) {
-                  return React.createElement("option", { key: id, value: id }, id);
-                }),
-              ),
-            ),
-            overridden(snapshot, "visionProvider")
-              ? React.createElement("span", { style: badgeStyle }, copy.overridden)
-              : null,
-          ),
-        );
-        children.push(
-          React.createElement(
-            "div",
-            { key: "route-model", style: fieldStyle },
-            React.createElement("span", { style: labelStyle }, "model"),
-            React.createElement(
-              "select",
-              {
-                style: selectStyle,
-                value: selected === null ? "" : model,
-                disabled: !writable || busy || provider === "",
-                "aria-label": "视觉 model",
-                onChange: function (event) {
-                  editMany({ visionModel: event.target.value, visionReasoningEffort: "" });
-                },
-              },
-              [React.createElement("option", { key: "", value: "" }, copy.inherit)].concat(
-                modelsForProvider.map(function (entry) {
-                  return React.createElement("option", { key: entry.id, value: entry.id }, entry.name || entry.id);
-                }),
-              ),
-            ),
-            overridden(snapshot, "visionModel") ? React.createElement("span", { style: badgeStyle }, copy.overridden) : null,
-          ),
-        );
-
-        // The effort list comes from the HOST catalog, which does carry it; the
-        // vision route above only decides which models may appear at all.
-        var hostEntry = matchModel(host.groups, provider, model);
-        var reasoning = (hostEntry && hostEntry.reasoning) || null;
-        var effortOptions = reasoning ? reasoning.efforts || [] : [];
-        if (effortOptions.length > 0) {
-          var effortValue = rawOf("visionReasoningEffort") || reasoning.defaultEffort || "";
-          children.push(
-            React.createElement(
-              "div",
-              { key: "route-effort", style: fieldStyle },
-              React.createElement("span", { style: labelStyle }, "reasoning effort"),
-              React.createElement(
-                "select",
-                {
-                  style: selectStyle,
-                  value: effortValue,
-                  disabled: !writable || busy,
-                  "aria-label": "视觉 reasoning effort",
-                  onChange: function (event) {
-                    edit("visionReasoningEffort", event.target.value);
-                  },
-                },
-                [React.createElement("option", { key: "", value: "" }, copy.inherit)].concat(
-                  effortOptions.map(function (effort) {
-                    return React.createElement("option", { key: effort.id, value: effort.id }, effort.name || effort.id);
-                  }),
-                ),
-              ),
-              overridden(snapshot, "visionReasoningEffort")
-                ? React.createElement("span", { style: badgeStyle }, copy.overridden)
-                : null,
-            ),
-          );
-        } else if (reasoning) {
-          children.push(
-            React.createElement("div", { key: "route-effort", style: hintStyle }, "reasoning effort：" + copy.effortNone),
-          );
-        }
-
-        if (selected === null && (provider !== "" || model !== "")) {
-          children.push(React.createElement("div", { key: "route-missing", style: hintStyle }, copy.routeMissing));
-        }
-      } else {
-        // Manual entry, also the fallback when the catalog failed: the card must
-        // stay usable when a provider is unreachable.
-        ROUTE_KEYS.forEach(function (key) {
-          var label = key === "visionProvider" ? "provider" : key === "visionModel" ? "model" : "reasoning effort";
-          children.push(
-            React.createElement(
-              "div",
-              { key: "route-" + key, style: fieldStyle },
-              React.createElement("span", { style: labelStyle }, label),
-              React.createElement("input", {
-                type: "text",
-                style: textStyle,
-                value: rawOf(key),
-                disabled: !writable || busy,
-                placeholder: copy.inherit,
-                "aria-label": "视觉 " + label,
-                onChange: function (event) {
-                  edit(key, event.target.value);
-                },
-                onKeyDown: function (event) {
-                  if (event.key === "Enter") save();
-                },
-              }),
-              overridden(snapshot, key) ? React.createElement("span", { style: badgeStyle }, copy.overridden) : null,
-            ),
-          );
-        });
+      if (catalog.value.status === "ready" && routeLost) {
+        children.push(React.createElement(UI.Banner, { key: "route-missing", kind: "warn" }, copy.routeMissing));
       }
 
       if (pickable) {
         children.push(
           React.createElement(
             "div",
-            { key: "route-mode", style: rowStyle },
+            { key: "route-mode", style: { display: "flex", alignItems: "center", gap: "8px" } },
             React.createElement(
-              "button",
+              UI.Button,
               {
-                type: "button",
-                style: buttonStyle,
+                variant: "secondary",
+                size: "sm",
                 onClick: function () {
                   setManual(!manual);
                 },
@@ -773,42 +370,26 @@ window.__ModuleLoader__.load({
         );
       }
 
-      children.push(React.createElement("div", { key: "route-fallback", style: hintStyle }, copy.catalogFallback));
+      children.push(
+        React.createElement("div", { key: "route-fallback", className: "dsp-field-hint" }, copy.catalogFallback),
+      );
 
-      if (invalid !== null) children.push(React.createElement("div", { key: "invalid", style: errorStyle }, invalid));
-      if (error !== null) children.push(React.createElement("div", { key: "error", style: errorStyle }, error));
       if (!writable && snapshot.status === "ready") {
-        children.push(React.createElement("div", { key: "unwritable", style: errorStyle }, copy.unwritable));
+        children.push(React.createElement(UI.Banner, { key: "unwritable", kind: "warn" }, copy.unwritable));
       }
 
-      children.push(
-        React.createElement(
-          "div",
-          { key: "actions", style: rowStyle },
-          React.createElement(
-            "button",
-            {
-              type: "button",
-              style: dirty && writable && !blocked ? primaryButtonStyle : buttonStyle,
-              disabled: !dirty || !writable || blocked,
-              onClick: save,
-            },
-            busy ? copy.saving : copy.save,
-          ),
-          React.createElement(
-            "button",
-            {
-              type: "button",
-              style: buttonStyle,
-              disabled: !writable || busy || !anyOverridden,
-              onClick: reset,
-            },
-            copy.reset,
-          ),
-        ),
+      return React.createElement(
+        UI.ConfigForm,
+        {
+          namespace: NS,
+          form: scope,
+          describe: describe,
+          title: copy.heading,
+          description: copy.intro,
+          renderControl: renderControl,
+        },
+        children,
       );
-
-      return React.createElement("div", { style: wrapStyle }, children);
     }
 
     /**
@@ -821,11 +402,16 @@ window.__ModuleLoader__.load({
      * just for this card. Nested, a host without the settings UI loses only this
      * card.
      *
+     * The nested context inherits the services declared here (`slots`,
+     * `remote`, `remote.session`), so the card is handed the scoped context and
+     * can reach both the form and the model directory through it.
+     *
      * @param ctx - client root context.
      */
     function apply(ctx) {
       ctx.inject(["configForms"], function (scoped) {
         var scope = scoped.configForms.get(NS);
+        var describe = scoped.configForms.describe();
         BUNDLE_NAMES.forEach(function (bundle) {
           scoped.slots.inject("plugins.row.config", function () {
             return scoped.slots.register(
@@ -833,7 +419,7 @@ window.__ModuleLoader__.load({
                 name: "plugins.row.config",
                 key: bundle + "#" + ROW_ID,
                 inject: function () {
-                  return { scope: scope, ctx: scoped };
+                  return { scope: scope, describe: describe, ctx: scoped };
                 },
               },
               DesktopAgentSettingsCard,

package/lib/config.js

@@ -76,13 +76,52 @@ export const DELIVERY_MODES = ['background', 'foreground'];
  * opt into, never a default this plugin picks on their behalf.
  */
 export const Config = z.object({
-  visionProvider: z.string().default('').volatile(),
-  visionModel: z.string().default('').volatile(),
-  visionReasoningEffort: z.string().default('').volatile(),
-  maxSteps: z.number().step(1).min(1).default(DEFAULT_MAX_STEPS).volatile(),
-  maxImageDimension: z.number().step(1).min(200).default(1568).volatile(),
-  deliveryMode: z.union(DELIVERY_MODES).default('background').volatile(),
-  allowBringToFront: z.boolean().default(false).volatile(),
+  visionProvider: z
+    .string()
+    .default('')
+    .comment('视觉 provider')
+    .description('每步决策用哪个模型看图。全空 = 用会话当前模型；会话模型不支持图像时自动走 AX 元素表。')
+    .volatile(),
+  visionModel: z
+    .string()
+    .default('')
+    .comment('视觉 model')
+    .description('')
+    .volatile(),
+  visionReasoningEffort: z
+    .string()
+    .default('')
+    .comment('视觉 reasoning effort')
+    .description('')
+    .volatile(),
+  maxSteps: z
+    .number()
+    .step(1)
+    .min(1)
+    .default(DEFAULT_MAX_STEPS)
+    .comment('步数上限')
+    .description('一次任务最多执行多少个动作，默认 40。')
+    .volatile(),
+  maxImageDimension: z
+    .number()
+    .step(1)
+    .min(200)
+    .default(1568)
+    .comment('截图长边上限')
+    .description('送给模型的截图最长边（像素），默认 1568。调小可省 token，但太小会看不清控件。')
+    .volatile(),
+  deliveryMode: z
+    .union(DELIVERY_MODES)
+    .default('background')
+    .comment('投递方式')
+    .description('后台投递不抢焦点；游戏等自绘表面会过滤按 pid 路由的事件，需要前台投递。')
+    .volatile(),
+  allowBringToFront: z
+    .boolean()
+    .default(false)
+    .comment('允许抢前台')
+    .description('关闭时模型不能使用 bring_to_front。开启后模型可把目标窗口提到最前，代价是抢走你当前的焦点；仅当窗口被压在后台、内容不刷新时才需要。')
+    .volatile(),
 });
 
 /**

package/lib/index.js

@@ -2,7 +2,7 @@
  * dsh-desktop-agent — host half.
  *
  * Registers one model-facing tool, `desktop_agent`, that runs a native-vision
- * decision loop against the host desktop, plus the loopback route the settings
+ * decision loop against the host desktop, plus the same-origin route the settings
  * card reads its model list from.
  *
  * The plugin owns no execution engine of its own. Every action is dispatched to
@@ -220,7 +220,7 @@ export async function apply(ctx, config, loadSdk) {
   ctx.inject(['webServer'], (scoped) => {
     scoped.effect(
       () => {
-        const disposers = makeRoutes({ llm }).map((route) => scoped.webServer.register(route));
+        const disposers = makeRoutes({ llm, connection: () => scoped.get('connection') }).map((route) => scoped.webServer.register(route));
         return () => {
           for (const dispose of disposers) dispose();
         };

package/lib/routes.js

@@ -1,5 +1,5 @@
 /**
- * The /api/dsh-desktop-agent route family: a loopback-only bridge that answers
+ * The /api/dsh-desktop-agent route family: a bridge that answers
  * one question the browser half cannot answer for itself.
  *
  * The settings card must list only models that can actually see, and the fact it
@@ -23,32 +23,33 @@ import { visionCatalog } from './route.js';
 export const VISION_MODELS_API = '/api/dsh-desktop-agent/vision-models';
 
 /**
- * Loopback literal check plus browser same-origin markers (mirrors the imagegen
- * bridge and dsh-ssh).
+ * Ask the composition whether one request may be served.
  *
+ * `connection.requestRejection` is the deployment's single trust fence: it
+ * applies the Host/Origin checks (loopback plus the LAN authorities the
+ * deployment declares) and the browser authentication that rides with them.
+ * This plugin answers with the verdict instead of re-deriving it, because the
+ * declared LAN authorities live in `connection`'s config and a local check
+ * cannot see them.
+ *
+ * A missing `connection` refuses rather than serves: these routes sit in front
+ * of Connection's `/api` prefix route, so serving them without its fence would
+ * serve them unfenced.
+ *
+ * @param connection - the composition's Connection service, when it is up.
  * @param request - the incoming request.
- * @returns whether the request may be served.
+ * @param response - the response, written to when the request is refused.
+ * @returns whether the request was refused.
  */
-function isLoopbackRequest(request) {
-  const address = request.socket.remoteAddress;
-  if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1') return false;
-  const host = request.headers.host;
-  if (typeof host !== 'string') return false;
-  let hostUrl;
-  try {
-    hostUrl = new URL(`http://${host}`);
-  } catch {
-    return false;
-  }
-  if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]') return false;
-  if (request.headers['sec-fetch-site'] === 'cross-site') return false;
-  const origin = request.headers.origin;
-  if (origin === undefined) return true;
-  try {
-    return new URL(origin).host === hostUrl.host;
-  } catch {
-    return false;
+function refuseUntrusted(connection, request, response) {
+  if (connection === undefined) {
+    writeJson(response, 403, { error: 'forbidden' });
+    return true;
   }
+  const rejection = connection.requestRejection(request);
+  if (rejection === undefined) return false;
+  writeJson(response, rejection, { error: rejection === 401 ? 'unauthorized' : 'forbidden' });
+  return true;
 }
 
 /** Write one JSON response. */
@@ -66,7 +67,11 @@ function writeJson(response, status, body) {
 /**
  * Build the route family.
  *
- * @param deps - the host's `ctx.llm` service.
+ * @param deps - the host dependencies.
+ * @param deps.llm - the host's `ctx.llm` service.
+ * @param deps.connection - resolves the composition's trust fence per request.
+ *   Resolved per call rather than captured: a composed row order does not imply
+ *   an activation order, so the service can still be absent when routes are built.
  * @returns the routes to register.
  */
 export function makeRoutes(deps) {
@@ -75,10 +80,7 @@ export function makeRoutes(deps) {
       kind: 'exact',
       path: VISION_MODELS_API,
       async handler(request, response) {
-        if (!isLoopbackRequest(request)) {
-          writeJson(response, 403, { error: 'loopback-only' });
-          return;
-        }
+        if (refuseUntrusted(deps.connection(), request, response)) return;
         if (request.method !== 'GET' && request.method !== 'POST') {
           writeJson(response, 405, { error: 'method-not-allowed' });
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logictan/dsh-desktop-agent",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "DSH desktop agent: a native-vision decision loop that drives the host desktop through the Cua Driver tools. DSH 桌面 Agent 子插件。",
   "type": "module",
   "main": "lib/index.js",
@@ -14,6 +14,9 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
+      "external": [
+        "@logictan/dsh-plugins-shared-client"
+      ],
       "inject": [
         "slots",
         "remote",
@@ -54,16 +57,21 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-connection": "^0.1.5-alpha.1 || ^0.1.6-alpha.1 || ^0.1.7-alpha.1 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1 || ^0.1.6-alpha.1 || ^0.1.7-alpha.1 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.1 || ^0.1.6-alpha.1 || ^0.1.7-alpha.1 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-mcp-client": "^0.1.5-alpha.1 || ^0.1.6-alpha.1 || ^0.1.7-alpha.1 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-alpha.1 || ^0.1.6-alpha.1 || ^0.1.7-alpha.1 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.3"
+    "@deepseek-ai/schemastery": "^3.18.3",
+    "@logictan/dsh-plugins-shared-client": "^0.1.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
       "optional": true
     },
+    "@deepseek-ai/dsh-client-connection": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
@@ -78,6 +86,9 @@
     },
     "@deepseek-ai/schemastery": {
       "optional": true
+    },
+    "@logictan/dsh-plugins-shared-client": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -85,6 +96,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-mcp-client": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",