openclacky 1.5.11 → 1.5.13

data/lib/clacky/default_extensions/advisor/panels/advisor/view.js

@@ -1,12 +1,15 @@
 // ── Advisor recommendations bar + settings toggle ─────────────────────
 //
-// session.composer slot: recommendation card above the input box. The ✕
-// button dismisses the card for the rest of this page lifetime — purely
-// local, no server call, so a page refresh brings recommendations back.
-// The ⏻ button turns the advisor off globally (persisted to advisor.yml);
-// a toast reminds the user it can be re-enabled in Settings. Clicking an
-// option fills the input box so the user can review (or edit) before
-// sending. Nothing is executed automatically.
+// session.composer slot: recommendation card above the input box. Card
+// state is keyed by session id - each session's recommendations live in
+// their own bucket, so switching sessions never leaks one session's card
+// into another (and switching back restores it). The ✕ button dismisses
+// the card for the rest of the current round only - the next round's
+// pending event resets the flag, so recommendations return without a
+// page refresh. The ⏻ button turns the advisor off globally (persisted to
+// advisor.yml); a toast reminds the user it can be re-enabled in Settings.
+// Clicking an option fills the input box so the user can review (or edit)
+// before sending. Nothing is executed automatically.
 //
 // settings.tabs + settings.body: an "Advisor" tab with a master on/off
 // switch, persisted to ~/.clacky/advisor.yml via /api/ext/advisor/*.
@@ -85,7 +88,6 @@
       .advisor-option-send { position: absolute; right: 6px; top: 50%; transform: translateY(-50%); width: 22px; height: 22px; display: inline-flex; align-items: center; justify-content: center; border: none; border-radius: var(--radius-sm); background: transparent; color: var(--color-text-secondary); cursor: pointer; opacity: 0; transition: opacity 0.12s; padding: 0; }
       .advisor-option:hover .advisor-option-send { opacity: 1; }
       .advisor-option-send:hover { background: var(--color-accent-primary); color: #fff; }
-      .advisor-card-text { font-size: 12px; color: var(--color-text-secondary); white-space: pre-wrap; }
       .advisor-error { font-size: 12px; color: var(--color-error, #c0392b); background: var(--color-error-bg, #fef2f2); padding: 6px 8px; border-radius: var(--radius-sm); white-space: pre-wrap; }
       .advisor-pending { font-size: 12px; color: var(--color-text-tertiary); display: flex; align-items: center; gap: 8px; }
       .advisor-spinner { width: 12px; height: 12px; flex: none; border: 2px solid var(--color-border-strong, #c9c9c2); border-top-color: transparent; border-radius: 50%; animation: advisor-spin 0.8s linear infinite; }
@@ -95,31 +97,17 @@
     document.head.appendChild(style);
   }
 
-  function parseOptions(content) {
-    const options = [];
-    (content || "").split("\n").forEach((line) => {
-      const m = line.match(/^\s*[-*]\s*\[([^\]]+)\]\s*(.*)$/);
-      if (m) {
-        options.push({ action: m[1].trim(), reason: m[2].trim() });
-      } else if (line.trim()) {
-        // Tolerate models that skip the [action] wrapper — the whole line
-        // still becomes a clickable option.
-        options.push({ action: line.trim(), reason: "" });
-      }
-    });
-    return options;
+  function normalizeOptions(list) {
+    if (!Array.isArray(list)) return [];
+    return list
+      .filter((o) => o && typeof o.action === "string" && o.action.trim())
+      .map((o) => ({ action: o.action.trim(), reason: (o.reason || "").trim() }));
   }
 
   function fillInput(text) {
     const input = document.getElementById("user-input");
-    if (!input) return;
-    input.value = text;
-    // Match the host's auto-grow behaviour (sessions.js input handler): a raw
-    // value assignment never fires the input event, so multi-line fills would
-    // otherwise stay at one-line height with the rest clipped.
-    input.style.height = "auto";
-    input.style.height = Math.min(input.scrollHeight, 200) + "px";
-    input.focus();
+    if (!input || !Clacky.Composer) return;
+    Clacky.Composer.setText(input, text);
   }
 
   // Fill the composer and send immediately. _sendMessage clears the input
@@ -127,9 +115,8 @@
   function sendNow(text) {
     const input = document.getElementById("user-input");
     const btn = document.getElementById("btn-send");
-    if (!input || !btn) return;
-    input.value = text;
-    input.style.height = "auto";
+    if (!input || !btn || !Clacky.Composer) return;
+    Clacky.Composer.setText(input, text);
     btn.click();
   }
 
@@ -179,26 +166,46 @@
     });
   }
 
-  // Module-level state, shared by the card and the settings switch.
-  // dismissed: the user hit ✕ — hide the card for this page lifetime and
-  // ignore incoming events until a refresh (or the settings switch turns
-  // the advisor back on).
-  const state = { mode: "hidden", options: [], fallback: "", errorMessage: "", dismissed: false };
+  // Module-level state for the global advisor switch. advisor.yml is a
+  // global config, so `off` applies to every session for the rest of this
+  // page lifetime (⏻ button or settings switch).
+  const state = { off: false };
+
+  // Per-session card state, keyed by sessionId. The bus mirrors every ext.*
+  // event regardless of the active session, so each session's card state must
+  // live in its own bucket: session A's recommendations stay in A while you
+  // view B, and come back when you return to A. roundDismissed: the user hit ✕
+  // this round - hide the card and ignore events until the next round's
+  // pending event resets the flag.
+  //
+  // The host's per-session `create(ctx)` runtime can't hold this - it is only
+  // allocated during a render pass, and background sessions receive events
+  // while they have no render context.
+  const sessionStates = new Map();
+
+  function stateFor(sessionId) {
+    let s = sessionStates.get(sessionId);
+    if (!s) {
+      s = { mode: "hidden", options: [], errorMessage: "", roundDismissed: false };
+      sessionStates.set(sessionId, s);
+    }
+    return s;
+  }
 
   function dismiss() {
-    state.dismissed = true;
-    state.mode = "hidden";
+    const s = sessionStates.get(Clacky.ext.context.sessionId);
+    if (!s) return;
+    s.roundDismissed = true;
+    s.mode = "hidden";
     redraw();
   }
-
   // Global off: POST the disable endpoint (persisted in advisor.yml) and
   // hide the card; the toast tells the user where to re-enable.
   function turnOff() {
     fetch("/api/ext/advisor/disable", { method: "POST" })
       .then((r) => { if (!r.ok) throw new Error("HTTP " + r.status); return r.json(); })
       .then((d) => {
-        state.dismissed = true;
-        state.mode = "hidden";
+        state.off = true;
         redraw();
         if (window.Clacky && Clacky.Modal && Clacky.Modal.toast) {
           Clacky.Modal.toast(t("advisor.offHint", "已关闭工作建议，可在设置页重新打开"), {
@@ -224,10 +231,15 @@
       });
   }
 
-  // Build the current card from `state`. Returns null when hidden — the host
-  // treats a null result as "render nothing", which clears the slot.
-  function renderContent() {
-    if (state.dismissed || state.mode === "hidden") return null;
+  // Build the current card for the render context's session. Returns null
+  // when hidden - the host treats a null result as "render nothing", which
+  // clears the slot.
+  function renderContent(ctx) {
+    if (!ctx || !ctx.sessionId || state.off) return null;
+    // Read-only lookup: a session with no advisor event yet has no bucket and
+    // renders nothing, so rendering never allocates state.
+    const s = sessionStates.get(ctx.sessionId);
+    if (!s || s.mode === "hidden") return null;
 
     const slot = document.createElement("div");
     slot.className = "advisor-card";
@@ -264,7 +276,7 @@
     head.appendChild(actions);
     slot.appendChild(head);
 
-    if (state.mode === "pending") {
+    if (s.mode === "pending") {
       const row = document.createElement("div");
       row.className = "advisor-pending";
 
@@ -277,21 +289,16 @@
       return slot;
     }
 
-    if (state.mode === "error") {
+    if (s.mode === "error") {
       const row = document.createElement("div");
       row.className = "advisor-error";
-      row.textContent = state.errorMessage;
+      row.textContent = s.errorMessage;
       slot.appendChild(row);
       return slot;
     }
 
-    if (state.options.length > 0) {
-      renderOptions(slot, state.options);
-    } else {
-      const text = document.createElement("div");
-      text.className = "advisor-card-text";
-      text.textContent = state.fallback;
-      slot.appendChild(text);
+    if (s.options.length > 0) {
+      renderOptions(slot, s.options);
     }
     return slot;
   }
@@ -307,7 +314,9 @@
     }
     // The card pushes the message stream up; scroll to the bottom so the
     // last message stays visible instead of being hidden under it.
-    if (!state.dismissed && state.mode !== "hidden") {
+    const active = Clacky.ext.context.sessionId;
+    const s = active ? sessionStates.get(active) : null;
+    if (!state.off && s && s.mode !== "hidden") {
       requestAnimationFrame(() => {
         const m = document.getElementById("messages");
         if (m) m.scrollTop = m.scrollHeight;
@@ -315,35 +324,43 @@
     }
   }
 
-  Clacky.ext.subscribe("ext.advisor.pending", () => {
-    if (state.dismissed) return;
-    state.mode = "pending";
-    redraw();
+  Clacky.ext.subscribe("ext.advisor.pending", (payload) => {
+    const sid = payload && payload.sessionId;
+    if (!sid || state.off) return;
+    const s = stateFor(sid);
+    s.roundDismissed = false;
+    s.mode = "pending";
+    if (sid === Clacky.ext.context.sessionId) redraw();
   });
   Clacky.ext.subscribe("ext.advisor.recommendations", (payload) => {
-    if (state.dismissed) return;
-    const content = (payload && (payload.content || payload.advice)) || "";
-    const opts = parseOptions(content);
-    state.mode = "options";
-    state.options = opts;
-    state.fallback = opts.length > 0 ? "" : content;
-    redraw();
+    const sid = payload && payload.sessionId;
+    if (!sid || state.off) return;
+    const s = stateFor(sid);
+    if (s.roundDismissed) return;
+    const opts = normalizeOptions(payload && payload.options);
+    if (opts.length === 0) return;
+    s.mode = "options";
+    s.options = opts;
+    if (sid === Clacky.ext.context.sessionId) redraw();
   });
   Clacky.ext.subscribe("ext.advisor.done", (payload) => {
-    if (state.dismissed) return;
+    const sid = payload && payload.sessionId;
+    if (!sid || state.off) return;
+    const s = stateFor(sid);
+    if (s.roundDismissed) return;
     const reason = payload && payload.reason;
     if (reason === "error" || reason === "empty") {
-      state.mode = "error";
-      state.errorMessage = (reason === "error" && payload && payload.message)
+      s.mode = "error";
+      s.errorMessage = (reason === "error" && payload && payload.message)
         ? t("advisor.error", "建议生成失败") + "：" + payload.message
         : t("advisor.empty", "未能生成建议，请稍后重试");
     } else {
-      state.mode = "hidden";
+      s.mode = "hidden";
     }
-    redraw();
+    if (sid === Clacky.ext.context.sessionId) redraw();
   });
 
-  Clacky.ext.ui.mount("session.composer", () => renderContent(), { order: 200 });
+  Clacky.ext.ui.mount("session.composer", (container, ctx) => renderContent(ctx), { order: 200 });
 
   // ── Settings tab: master on/off switch ─────────────────────────────────
 
@@ -419,7 +436,7 @@
         .then((d) => {
           checkbox.checked = !!d.enabled;
           // Reflect the change on the open composer card immediately.
-          state.dismissed = !d.enabled;
+          state.off = !d.enabled;
           redraw();
         })
         .catch((err) => {

data/lib/clacky/default_extensions/ext-studio/api/handler.rb

@@ -189,6 +189,33 @@ class ExtStudioExt < Clacky::ApiExtension
     json(ok: true, ext_id: ext_id)
   end
 
+  # POST /api/ext/ext-studio/set_disabled
+  # body: { ext_id, disabled }
+  # Disables/enables a local extension. A disabled extension stays discoverable
+  # but stops contributing units (panels, api, skills, agents, ...) until it is
+  # re-enabled.
+  post "/set_disabled" do
+    ext_id   = require_ext_id!
+    disabled = json_body["disabled"] == true
+
+    result    = Clacky::ExtensionLoader.load_all(force: false)
+    container = Array(result.containers).find { |id, _| id == ext_id }&.last
+    error!("extension not found: #{ext_id}", status: 404) unless container
+    error!("not a local extension", status: 422) unless container[:layer] == :local
+
+    if disabled
+      Clacky::ExtensionLoader.disable!(ext_id)
+    else
+      Clacky::ExtensionLoader.enable!(ext_id)
+    end
+
+    # Reload the API registry so a disabled extension's routes unmount (and an
+    # enabled one remounts) without restarting the server.
+    Clacky::ApiExtensionLoader.load_all
+
+    json(ok: true, ext_id: ext_id, disabled: disabled)
+  end
+
   # POST /api/ext/ext-studio/unpublish
   # body: { ext_id }
   post "/unpublish" do
@@ -317,6 +344,9 @@ class ExtStudioExt < Clacky::ApiExtension
     ext_id  = require_ext_id!
     version = presence(json_body["version"])
     error!("version required", status: 422) unless version
+    unless Clacky::ExtensionVerifier.valid_version?(version)
+      error!("version must use three numeric segments (for example, 1.0.0)", status: 422)
+    end
 
     result  = Clacky::ExtensionLoader.load_all(force: false)
     container = Array(result.containers).find { |id, _| id == ext_id }&.last
@@ -470,6 +500,7 @@ class ExtStudioExt < Clacky::ApiExtension
       version: raw["version"],
       origin: container[:origin],
       layer: container[:layer].to_s,
+      disabled: container[:disabled] == true,
       dir: dir,
       mtime: File.mtime(File.join(dir, "ext.yml")).to_i,
       units: ext_units.map { |u| serialize_unit(u) },

data/lib/clacky/default_extensions/ext-studio/panels/studio/view.js

@@ -144,7 +144,10 @@
       "extlist.btn.packing": "Packing…",
       "extlist.btn.unpublish": "Unpublish",
       "extlist.btn.iterate": "Iterate",
+      "extlist.btn.disable": "Disable",
+      "extlist.btn.enable": "Enable",
       "extlist.btn.delete": "Delete",
+      "extlist.badge.disabled": "Disabled",
       "extlist.delete.confirm": "Delete local extension \"{{id}}\"? This cannot be undone.",
       "extlist.iterate.seed": "Iterate on extension {{id}}",
       "extlist.changelog.prompt": "Changelog (optional):",
@@ -339,7 +342,10 @@
       "extlist.btn.packing": "打包中…",
       "extlist.btn.unpublish": "下架",
       "extlist.btn.iterate": "迭代",
+      "extlist.btn.disable": "禁止",
+      "extlist.btn.enable": "启用",
       "extlist.btn.delete": "删除",
+      "extlist.badge.disabled": "已禁用",
       "extlist.delete.confirm": "确定要删除本地扩展「{{id}}」吗？此操作不可恢复。",
       "extlist.iterate.seed": "迭代扩展 {{id}}",
       "extlist.changelog.prompt": "更新说明（可选）：",
@@ -621,8 +627,12 @@
     }
   }
 
+  function normalizeVersion(v) {
+    return String(v || "").replace(/[^0-9.]/g, "").split(".").slice(0, 3).join(".");
+  }
+
   function isSemver(v) {
-    return /^\d+\.\d+\.\d+$/.test(v);
+    return /^[0-9]+\.[0-9]+\.[0-9]+$/.test(v);
   }
 
   // Unified publish flow: one modal that walks the creator from a release form
@@ -636,23 +646,14 @@
       const titleNew = isBrand ? t("pub.brand.title.new") : t("pub.title.new");
       const titleUpdate = isBrand ? t("pub.brand.title.update") : t("pub.title.update");
       const introText = isBrand ? t("pub.brand.intro", { name: ext.name }) : t("pub.intro", { name: ext.name });
-      let currentVersion = ext.version || "";
+      let currentVersion = normalizeVersion(ext.version);
       let isUpdate = false;
 
       const verField = el("div", { class: "studio-field" });
       verField.appendChild(el("label", { class: "studio-label", text: t("pub.version.label") }));
-      const verInput = el("input", { class: "studio-input", type: "text", value: currentVersion, placeholder: "1.0.0" });
-      verInput.addEventListener("input", () => {
-        currentVersion = verInput.value.trim();
-        const valid = isSemver(currentVersion);
-        verInput.classList.toggle("studio-input-error", !!currentVersion && !valid);
-        publishBtn.disabled = !valid;
-        publishBtn.textContent = valid ? t("pub.btn.publish", { ver: currentVersion }) : t("pub.btn.publish", { ver: currentVersion || "?" });
-        if (currentVersion && !valid) {
-          setProgress(t("err.invalid_version"), true);
-        } else {
-          status.style.display = "none";
-        }
+      const verInput = el("input", {
+        class: "studio-input", type: "text", value: currentVersion,
+        placeholder: "1.0.0", inputmode: "decimal", autocomplete: "off", spellcheck: "false",
       });
       verField.appendChild(verInput);
 
@@ -688,7 +689,8 @@
 
       const publishBtn = modal.footer.querySelector(".btn-primary");
       const cancelBtn = modal.footer.querySelector(".btn-secondary");
-      if (!currentVersion) publishBtn.disabled = true;
+      verInput.addEventListener("input", () => syncVersionState({ normalize: true }));
+      syncVersionState();
 
       Promise.resolve(prevVersionOrPromise).then((prevVersion) => {
         if (done || !prevVersion) return;
@@ -696,10 +698,8 @@
         const titleEl = modal.overlay.querySelector(".modal-title");
         if (titleEl) titleEl.textContent = titleUpdate;
         if (prevVersion !== currentVersion) {
-          currentVersion = prevVersion;
-          verInput.value = currentVersion;
-          publishBtn.disabled = false;
-          publishBtn.textContent = t("pub.btn.publish", { ver: currentVersion });
+          verInput.value = normalizeVersion(prevVersion);
+          syncVersionState();
         }
       });
 
@@ -709,9 +709,34 @@
         status.className = "studio-modal-status" + (isError ? " studio-modal-status-error" : "");
       }
 
+      function syncVersionState({ normalize = false, updateFeedback = true } = {}) {
+        if (normalize) {
+          const raw = verInput.value;
+          const cursor = verInput.selectionStart;
+          const normalized = normalizeVersion(raw);
+          if (normalized !== raw) {
+            verInput.value = normalized;
+            if (cursor != null) {
+              const normalizedCursor = normalizeVersion(raw.slice(0, cursor)).length;
+              verInput.setSelectionRange(normalizedCursor, normalizedCursor);
+            }
+          }
+        }
+
+        currentVersion = verInput.value.trim();
+        const valid = isSemver(currentVersion);
+        publishBtn.disabled = !valid;
+        publishBtn.textContent = t("pub.btn.publish", { ver: valid ? currentVersion : (currentVersion || "?") });
+
+        if (updateFeedback) {
+          verInput.classList.toggle("studio-input-error", !!currentVersion && !valid);
+          if (currentVersion && !valid) setProgress(t("err.invalid_version"), true);
+          else status.style.display = "none";
+        }
+      }
+
       function resetButtons() {
-        publishBtn.disabled = !currentVersion;
-        publishBtn.textContent = currentVersion ? t("pub.btn.publish", { ver: currentVersion }) : t("pub.btn.publish", { ver: "?" });
+        syncVersionState({ updateFeedback: false });
         cancelBtn.disabled = false;
         notes.disabled = false;
         verInput.disabled = false;
@@ -1582,9 +1607,15 @@
       const head = el("div", { class: "studio-skill-head" });
       head.appendChild(el("span", { class: "studio-skill-name", text: `${ext.name} (${ext.id})` }));
       head.appendChild(badge(published ? t("extlist.badge.published") : t("extlist.badge.local"), published ? "published" : "local"));
-      if (ext.error_count) head.appendChild(badge("✕ " + t("extlist.verify.errors", { n: ext.error_count }), "changed"));
-      else if (ext.warning_count) head.appendChild(badge("● " + t("extlist.verify.warnings", { n: ext.warning_count }), "changed"));
-      else head.appendChild(badge("✓ " + t("extlist.verify.ok"), "published"));
+      if (ext.disabled) {
+        head.appendChild(badge(t("extlist.badge.disabled"), "changed"));
+      } else if (ext.error_count) {
+        head.appendChild(badge("✕ " + t("extlist.verify.errors", { n: ext.error_count }), "changed"));
+      } else if (ext.warning_count) {
+        head.appendChild(badge("● " + t("extlist.verify.warnings", { n: ext.warning_count }), "changed"));
+      } else {
+        head.appendChild(badge("✓ " + t("extlist.verify.ok"), "published"));
+      }
       card.appendChild(head);
       if (ext.description) card.appendChild(el("p", { class: "studio-skill-desc", text: ext.description }));
 
@@ -1616,6 +1647,13 @@
       const packBtn = el("button", { class: "studio-btn studio-btn-ghost", text: t("extlist.btn.pack") });
       packBtn.addEventListener("click", () => doPack(ext, packBtn));
       actions.appendChild(packBtn);
+
+      const toggleBtn = el("button", {
+        class: "studio-btn studio-btn-ghost",
+        text: ext.disabled ? t("extlist.btn.enable") : t("extlist.btn.disable"),
+      });
+      toggleBtn.addEventListener("click", () => doToggleDisabled(ext, toggleBtn));
+      actions.appendChild(toggleBtn);
       card.appendChild(actions);
 
       if (!published) {
@@ -1638,6 +1676,18 @@
       }
     }
 
+    async function doToggleDisabled(ext, btn) {
+      const next = !ext.disabled;
+      btn.disabled = true;
+      try {
+        await postJson("/set_disabled", { ext_id: ext.id, disabled: next });
+        location.reload();
+      } catch (e) {
+        btn.disabled = false;
+        alert(t("err.generic", { msg: e.message }));
+      }
+    }
+
     async function doDelete(ext, btn) {
       if (!await Clacky.Modal.confirm(t("extlist.delete.confirm", { id: ext.id }))) return;
       btn.disabled = true;

data/lib/clacky/default_extensions/ext-studio/skills/ext-develop/SKILL.md

@@ -104,9 +104,9 @@ Clacky.ext.api.register(name, fn)         // expose a named data source; api.res
 - gets a host-owned `container` DOM element — append into it, **or** return a Node / HTML
   string and the host appends for you;
 - returning a **function** registers it as a teardown callback;
-- returning **`null`/`undefined` renders nothing** — but returning `null` from a wrong
-  signature (e.g. `(ctx) => …` instead of `(container, ctx) => …`) is the #1 cause of a
-  red "crashed" placeholder. Match the signature exactly.
+- returning **`null`/`undefined` renders nothing** (safe) — a red "crashed" placeholder
+  means the render **threw**; the #1 cause is a wrong signature shifting every argument
+  (e.g. `(ctx) => …` instead of `(container, ctx) => …`). Match the signature exactly.
 
 `ctx` carries `{ sessionId, agentProfile }`. `opts`: `order` (lower renders first,
 default 100), `tab: { id, label, badge? }` (**required** for tabbed slots — `session.aside`
@@ -289,7 +289,7 @@ Rules:
 
 ## Scaffold
 
-Turn a plain-language idea into a working skeleton, then read the generated files.
+Turn a plain-language idea into a working skeleton.
 
 ### 1 — Understand the idea
 
@@ -333,20 +333,10 @@ This creates `~/.clacky/ext/local/<id>/` with a working hello panel + handler:
 Use `--full` only when the user needs the kitchen-sink reference exercising all eight
 contributes types — it's a lot to read, so prefer the plain scaffold otherwise.
 
-### 3 — Read what was generated
+### 3 — Reshape to the idea
 
-Always read the generated `ext.yml`, `view.js`, `handler.rb`, and `test/handler_test.rb`
-before editing. This is your starting point; you'll reshape it to match the idea.
-
-### 4 — Reshape to the idea
-
-Before editing, re-read the contract for whatever the idea needs (panel / API / patch /
-hook) in **Reference: the contracts** above — don't guess field names, slot names, hook
-events, or the `Clacky.ext` surface.
-
-The scaffold ships a working "hello" panel that pings its backend. Turn it into the real
-feature by editing those three files. Below is a concrete before → after for a tiny
-"add a note" panel — use it as the shape to copy, not the literal content.
+Below is a concrete before → after for a tiny "add a note" panel — use it as
+the shape to copy, not the literal content.
 
 **`ext.yml`** — rename the panel id/view to the feature; add `skills:`/`agents:` only if needed:
 
@@ -385,8 +375,7 @@ Clacky.ext.ui.mount("session.aside", function (container, ctx) {
 ```
 
 **`api/handler.rb`** — stay a `Clacky::ApiExtension` subclass; add the route the panel
-calls. Persist user data with `data_path` (lands in `~/.clacky/ext-data/<id>/`, survives
-reloads, `gem update`, and uninstall/reinstall), never into the code dir:
+calls. Persist user data with `data_path`, never into the code dir:
 
 ```ruby
 class <Prefix>Ext < Clacky::ApiExtension
@@ -403,21 +392,11 @@ Rules while reshaping:
   are the #1 cause of a `loader.error`.
 - Routes in `handler.rb` are **relative** to `/api/ext/<id>/`; the `view.js` `fetch` must
   match. A mismatch is a silent 404, not a verify error.
-- Persist state with `data_path(...)`, never by writing into the extension's code dir.
-- The `ui.mount` render signature is `(container, ctx, runtime)` — `container` is the first
-  argument, not `ctx`. Writing a shorter `(ctx) => ...` signature shifts every argument, so
-  session checks misbehave. Returning `null` is safe (renders nothing); only a **thrown
-  exception** shows the red crashed-panel box.
-- **UI styling: default to host classes; anything the host has no class for,
-  build freely.** The host covers `btn-*` buttons, `form-*` inputs, `modal-*`
-  dialogs, `Clacky.Modal.toast/confirm` feedback, and `var(--color-*)` colors
-  (raw hex breaks the dark theme). For exact definitions grep the host
-  stylesheet `lib/clacky/web/app.css`; the scaffold templates show real usage.
-- A skill is a `SKILL.md` under `skills/<id>/`; an agent is a `system_prompt.md` that can
-  reference `panels: [id]` and `skills: [id]`. Add those blocks to `ext.yml` only if the
-  idea needs them.
-
-### 5 — Write tests
+- **UI styling: default to host classes; anything the host has no class for, build
+  freely.** Colors: only `var(--color-*)` — raw hex breaks the dark theme. For the
+  full class/variable list grep the host stylesheet `lib/clacky/web/app.css`.
+
+### 4 — Write tests
 
 Test the backend before you call it done. Rewrite the scaffolded `test/handler_test.rb`
 to exercise your real routes (parse the JSON response, assert its fields), then run it
@@ -432,7 +411,7 @@ ruby test/handler_test.rb
 - A handler that only returns a static string may keep the scaffold's hello test;
   anything that fetches, transforms, caches, or computes MUST have a real test.
 
-### 6 — Confirm it loads
+### 5 — Confirm it loads
 
 Run `clacky ext verify` and confirm the new units resolve with no errors, then have the
 user reload the WebUI page. If verify reports problems, go to **Debug & verify**.
@@ -459,7 +438,7 @@ is structured with a `code`, `message`, the offending `file`, and a `hint`.
 
 | Symptom | Almost always | Fix |
 |---|---|---|
-| Red error box where the panel should be | `ui.mount` render signature is wrong / returned `null` | signature is `(container, ctx, runtime)` — not `(ctx)` |
+| Red error box where the panel should be | `ui.mount` render threw — usually a wrong signature | signature is `(container, ctx, runtime)` — not `(ctx)` |
 | Panel doesn't appear at all | `slot` name typo (silent) or no `attach:` | use a valid slot; set `attach: ["*"]` or an agent id |
 | Frontend `fetch` gets 404 | route in `handler.rb` ≠ path in `view.js` fetch | routes are relative to `/api/ext/<id>/` |
 | `loader.error` on verify | `ext.yml` `view:` path ≠ the on-disk `view.js` path | make the two match exactly |
@@ -530,7 +509,7 @@ If verify is clean but a change isn't visible:
   console for a "unknown slot" warning); (2) check the panel's `attach:` (or the agent
   that references it via `panels: [id]`) — a panel with no `attach` and no referencing
   agent has nothing to mount onto; (3) a red error box means the render function threw
-  or returned `null` from a wrong signature — open the console for the stack.
+  (usually a wrong signature) — open the console for the stack.
 - **API 404?** Routes are relative to `/api/ext/<ext_id>/`. Confirm the handler subclasses
   `Clacky::ApiExtension` and the route pattern matches what `view.js` fetches.
 - **Skill not triggering?** The AI selects skills by their `description`. Make the

data/lib/clacky/default_extensions/git/ext.yml

@@ -1,7 +1,7 @@
 id: git
 name: Git
 display_name: Git
-display_name_zh: Git
+display_name_zh: Git 管理
 description: Changes panel — a friendly view of what the AI changed in the working tree
 description_zh: 变更面板 — 直观查看 AI 在工作区的每一处修改
 version: "0.1.0"