dsh-skill-picker 0.3.4 → 0.5.4

package/src/client/index.jsx

@@ -15,7 +15,7 @@
  * @module dsh-skill-picker/client
  */
 
-import React, { useCallback, useEffect, useRef, useState } from 'react'
+import React, { Fragment, useCallback, useEffect, useRef, useState } from 'react'
 import fuzzysort from 'fuzzysort'
 import { pinyin } from 'pinyin-pro'
 
@@ -25,6 +25,30 @@ export const inject = ['slots', 'connection', 'sessions', 'inputTriggers']
 /** localStorage key for the picker's per-browser usage history. */
 const USAGE_KEY = 'dsh-skill-picker:usage'
 
+/** localStorage key for the user's manually pinned skills (ordered array of names). */
+const PINNED_KEY = 'dsh-skill-picker:pinned'
+
+/** Read the pinned list {string[]}; never throws. */
+function loadPinned() {
+  try {
+    const raw = localStorage.getItem(PINNED_KEY)
+    if (raw === null) return []
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+/** Persist the pinned list; never throws. */
+function savePinned(pinned) {
+  try {
+    localStorage.setItem(PINNED_KEY, JSON.stringify(pinned))
+  } catch {
+    /* storage unavailable — pinning just won't persist */
+  }
+}
+
 /** Read the usage history {name: {count, lastUsed}}; never throws. */
 function loadUsage() {
   try {
@@ -65,6 +89,30 @@ function rankByUsage(skills, usage) {
   })
 }
 
+/**
+ * Grouped ordering for the ⚡ panel: pinned (manual, pinned order) first,
+ * then recently/frequently used (usage order), then the untouched rest (by
+ * name). Groups with no members are dropped. A fresh structure is returned;
+ * the input arrays are untouched.
+ */
+function groupByPinned(skills, usage, pinned) {
+  const pinnedSet = new Set(pinned)
+  const pinnedList = pinned.map((name) => skills.find((s) => s.name === name)).filter(Boolean)
+  const ranked = rankByUsage(skills, usage)
+  const recent = []
+  const rest = []
+  for (const skill of ranked) {
+    if (pinnedSet.has(skill.name)) continue
+    if (usage[skill.name] !== undefined) recent.push(skill)
+    else rest.push(skill)
+  }
+  return [
+    { title: '📌 置顶', items: pinnedList },
+    { title: '🔥 最近使用', items: recent },
+    { title: '🗂️ 全部', items: rest },
+  ].filter((group) => group.items.length > 0)
+}
+
 /**
  * Pinyin search text for a skill name/description: spaced full pinyin
  * (`ji yi`), joined (`jiyi`), and initials (`jy`) for the name, plus joined
@@ -241,10 +289,38 @@ function SkillPickerButton(props) {
   const [source, setSource] = useState(undefined)
   const [query, setQuery] = useState('')
   const [usage, setUsage] = useState(() => loadUsage())
+  const [pinned, setPinned] = useState(() => loadPinned())
   const [active, setActive] = useState(0)
   const boxRef = useRef(null)
   const itemRefs = useRef([])
 
+  // The usage store is shared with the official `/` menu: picks made there go
+  // through window.__dshSkillPickerTrack (localStorage only). Refresh this
+  // panel's state from storage whenever that event fires, so a slash pick
+  // shows up as "recently used" here too — not just in the slash list.
+  useEffect(() => {
+    const onUsageUpdated = () => setUsage(loadUsage())
+    window.addEventListener('dsh-skill-picker:usage-updated', onUsageUpdated)
+    return () => window.removeEventListener('dsh-skill-picker:usage-updated', onUsageUpdated)
+  }, [])
+
+  // Latest draft mirror: `useInput` is a selector hook and may only be called
+  // during render, while the pick handler runs from a click callback. Sync the
+  // store's current draft into a ref here (render time), so the click handler
+  // appends onto the REAL current draft instead of a stale snapshot. The
+  // owner-provided `input` snapshot is a secondary fallback only.
+  const draftRef = useRef('')
+  if (typeof props.useInput === 'function') {
+    try {
+      const state = props.useInput((s) => s)
+      if (state !== undefined && typeof state.draft === 'string') draftRef.current = state.draft
+    } catch {
+      /* keep the last known draft */
+    }
+  } else if (props.input !== undefined && typeof props.input.draft === 'string') {
+    draftRef.current = props.input.draft
+  }
+
   const load = useCallback(async () => {
     if (skills !== undefined || error !== undefined) return
     try {
@@ -273,23 +349,18 @@ function SkillPickerButton(props) {
   }, [skills, error, props.listSkills, props.session, props.cwd])
 
   const toggle = () => {
-    if (!open) void load()
+    if (!open) {
+      setUsage(loadUsage())
+      void load()
+    }
     setOpen(!open)
   }
 
   const pick = (name) => {
-    // Draft source: owner InputZone snapshot first, framework hook second.
-    let draft = ''
-    try {
-      if (props.input !== undefined && typeof props.input.draft === 'string') {
-        draft = props.input.draft
-      } else if (typeof props.useInput === 'function') {
-        const state = props.useInput((s) => s)
-        if (state !== undefined && typeof state.draft === 'string') draft = state.draft
-      }
-    } catch (cause) {
-      console.error('[dsh-skill-picker] reading draft failed:', cause)
-    }
+    // Draft source: the render-time mirror of the live input store (see the
+    // `draftRef` sync above). Appending onto anything else risks overwriting
+    // the user's typed draft with a stale snapshot.
+    const draft = draftRef.current
     const separator = draft === '' || draft.endsWith(' ') || draft.endsWith('\n') ? '' : ' '
     const next = `${draft}${separator}/${name} `
     try {
@@ -311,6 +382,12 @@ function SkillPickerButton(props) {
     setQuery('')
   }
 
+  const togglePin = (name) => {
+    const next = pinned.includes(name) ? pinned.filter((n) => n !== name) : [...pinned, name]
+    setPinned(next)
+    savePinned(next)
+  }
+
   // Close on outside pointer-down (the shell's menu convention).
   useEffect(() => {
     if (!open) return
@@ -321,11 +398,12 @@ function SkillPickerButton(props) {
     return () => document.removeEventListener('mousedown', onDown)
   }, [open])
 
-  // Usage ordering: last picked first, then most frequent, then by name
-  // (shared with the `/` completion — one rule everywhere).
-  const ordered = rankByUsage(skills ?? [], usage)
+  // Grouped ordering: pinned first (manual), then usage-ranked (recent then
+  // frequent then untouched by name). Shared rule with the `/` completion.
+  const groups = groupByPinned(skills ?? [], usage, pinned)
+  const flat = groups.flatMap((group) => group.items)
 
-  const filtered = ordered
+  const filtered = flat
     .filter((skill) => {
       const q = query.trim().toLowerCase()
       if (q === '') return true
@@ -337,6 +415,11 @@ function SkillPickerButton(props) {
     })
     .slice(0, 60)
 
+  // Group titles show only while browsing (no query); searching collapses the
+  // list into one flat, pinned-first result set.
+  const showTitles = query.trim() === '' && groups.length > 1
+  const filteredNames = new Set(filtered.map((skill) => skill.name))
+
   // Keyboard navigation (#1): reset highlight when the query changes, keep it
   // in range when the result list shrinks, and keep the highlighted row visible.
   useEffect(() => {
@@ -401,8 +484,9 @@ function SkillPickerButton(props) {
               <div style={listStyle}>
                 {filtered.length === 0 ? (
                   <div style={statusStyle}>没有匹配的技能</div>
-                ) : (
-                  filtered.map((skill, index) => (
+                ) : (() => {
+                  let itemIndex = 0
+                  const renderItem = (skill, index) => (
                     <button
                       key={skill.name}
                       type="button"
@@ -419,16 +503,73 @@ function SkillPickerButton(props) {
                       }}
                       style={{
                         ...itemStyle,
+                        flexDirection: 'row',
+                        alignItems: 'center',
                         ...(index === active
                           ? { background: 'var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,0.12))' }
                           : {}),
                       }}
                     >
-                      <span style={nameStyle}>{`/${skill.name}`}</span>
-                      <span style={descStyle}>{skill.description ?? ''}</span>
+                      <span style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-start', gap: '2px', flex: '1', minWidth: '0' }}>
+                        <span style={nameStyle}>{`/${skill.name}`}</span>
+                        <span style={descStyle}>{skill.description ?? ''}</span>
+                      </span>
+                      <span
+                        role="button"
+                        tabIndex={-1}
+                        title={pinned.includes(skill.name) ? '取消置顶' : '置顶到列表顶部'}
+                        aria-label={pinned.includes(skill.name) ? '取消置顶' : '置顶'}
+                        onClick={(event) => {
+                          event.stopPropagation()
+                          togglePin(skill.name)
+                        }}
+                        style={{
+                          flex: 'none',
+                          marginLeft: '6px',
+                          padding: '2px 4px',
+                          borderRadius: '6px',
+                          fontSize: '12px',
+                          lineHeight: '16px',
+                          cursor: 'pointer',
+                          color: pinned.includes(skill.name)
+                            ? 'var(--dsw-alias-label-primary-bluish, #4cc9f0)'
+                            : 'var(--dsw-alias-label-tertiary, #8a94a6)',
+                          opacity: pinned.includes(skill.name) ? 1 : 0.55,
+                          userSelect: 'none',
+                        }}
+                      >
+                        {pinned.includes(skill.name) ? '📌' : '📍'}
+                      </span>
                     </button>
-                  ))
-                )}
+                  )
+                  if (!showTitles) {
+                    return filtered.map((skill) => renderItem(skill, itemIndex++))
+                  }
+                  return groups.map((group) => {
+                    const items = group.items.filter((skill) => filteredNames.has(skill.name))
+                    if (items.length === 0) return null
+                    return (
+                      <Fragment key={group.title}>
+                        <div
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'space-between',
+                            padding: '6px 10px 2px',
+                            color: 'var(--dsw-alias-label-tertiary, #8a94a6)',
+                            fontSize: '11px',
+                            fontWeight: 600,
+                            letterSpacing: '0.04em',
+                          }}
+                        >
+                          <span>{group.title}</span>
+                          <span style={{ opacity: 0.7 }}>{items.length}</span>
+                        </div>
+                        {items.map((skill) => renderItem(skill, itemIndex++))}
+                      </Fragment>
+                    )
+                  })
+                })()}
               </div>
               {source === 'host' && (
                 <div style={sourceBadgeStyle} title="官方技能 API 不可用，列表来自本地目录扫描（与官方 / 补全同源）">
@@ -445,12 +586,6 @@ function SkillPickerButton(props) {
 
 /** Apply the browser half: register the picker into the composer tool row. */
 export function apply(ctx) {
-  // Resolve the trigger pipeline service at apply scope (not inside an effect),
-  // exactly like the official ui-skill plugin does — in DSH 0.1.2-alpha.x the
-  // service lives in @deepseek-ai/dsh-client-ui-input-trigger and is only
-  // reachable from the plugin root context.
-  const inputTriggers = (typeof ctx.get === 'function' ? ctx.get('inputTriggers') : ctx.inputTriggers)
-
   // Primary skill source: the official host skills API. In DSH 0.1.2-alpha.x
   // the RPC moved from `connection.api.skills` (rc.x) to `remote.skills`
   // (used by the official ui-skill plugin); try both before falling back.
@@ -481,28 +616,6 @@ export function apply(ctx) {
     }
   }
 
-  // Host-route fallback: same scan the ⚡ panel uses (official provider roots).
-  const fetchHostSkills = async () => {
-    const cwd = typeof currentCwd === 'string' && currentCwd !== '' ? `?cwd=${encodeURIComponent(currentCwd)}` : ''
-    const res = await fetch(`/dsh-skill-picker/skills${cwd}`, { headers: { accept: 'application/json' } })
-    const json = await res.json()
-    if (!json.ok) throw new Error(json.error || 'bad response')
-    return Array.isArray(json.skills) ? json.skills : []
-  }
-
-  // Resolve skills by official RPC first, then the host scan route; never
-  // throws (returns [] when both fail) so `/` completion degrades gracefully.
-  const resolveSkills = async (sessionId) => {
-    try {
-      return await listSkills(sessionId)
-    } catch {
-      try {
-        return await fetchHostSkills()
-      } catch {
-        return []
-      }
-    }
-  }
   syncCwd()
   const unsubscribe = ctx.sessions.list.subscribe(syncCwd)
   ctx.effect(() => {
@@ -523,107 +636,57 @@ export function apply(ctx) {
     }
   }, 'dsh-skill-picker: composer input slot')
 
-  // Fuzzy `/` completion source: negative order puts the skill group ABOVE
-  // the slash commands (command source sits at order 0), and beats the
-  // official ui-skill prefix source too — typing `/` matches name AND
-  // description anywhere, with usage ordering (same rule as the ⚡ panel).
+  // Fuzzy `/` completion: instead of registering a parallel source group
+  // (which would appear as a second list next to the official one), expose a
+  // global matcher that the patched official ui-skill candidates calls. The
+  // official group stays THE single `/` list; only its matching behaviour is
+  // upgraded to fuzzy + pinyin (name AND description, subsequence scoring).
   ctx.effect(() => {
-    // Skills cache per session, so both candidates and the lexicon (chip
-    // decoration of `/skill-name` in the draft) have the same names.
-    const namesCache = new Map() // sessionId -> string[] (skill names)
-    const lexiconListeners = new Map() // sessionId -> Set<listener>
-    const notifyLexicon = (sessionId) => {
-      for (const fn of [...(lexiconListeners.get(sessionId) ?? [])]) {
-        try { fn() } catch (err) { console.error('[dsh-skill-picker] lexicon listener failed:', err) }
-      }
+    // Mirror the ⚡ panel's ordering: pinned first, then recently/frequently
+    // used skills, then the untouched rest — so both stay in sync.
+    const fuzzyMatch = (skills, query = '') => {
+      const ordered = groupByPinned(skills, loadUsage(), loadPinned()).flatMap((group) => group.items)
+      const q = String(query).trim().toLowerCase()
+      if (q === '') return ordered
+      // Rank by the ⚡ panel's exact order (pinned → recent → frequent → rest)
+      // so both lists stay in sync: fuzzysort only decides WHO matches, not
+      // the display order. Without this, a slash query re-sorts matches by
+      // match score and the two menus diverge for the same skill.
+      const rankByName = new Map(ordered.map((skill, index) => [skill.name, index]))
+      const targets = ordered.map((s) => ({
+        s,
+        search: `${s.name} ${s.description ?? ''} ${skillPinyinText(s.name, s.description ?? '')}`,
+      }))
+      const results = fuzzysort.go(q, targets, {
+        key: 'search',
+        limit: 30,
+        threshold: -10000,
+      })
+      return results
+        .filter((r) => r.score > 0)
+        .map((r) => r.obj.s)
+        .sort((a, b) => (rankByName.get(a.name) ?? 0) - (rankByName.get(b.name) ?? 0))
     }
-    const refreshNames = async (sessionId) => {
+    window.__dshSkillPickerFuzzy = fuzzyMatch
+    // Usage tracking for picks made from the official `/` menu: the patched
+    // ui-skill onPick calls this so a slash pick ranks like a bolt-panel pick.
+    const trackPick = (name) => {
+      const usage = loadUsage()
+      const nextUsage = { ...usage, [name]: { count: (usage[name]?.count ?? 0) + 1, lastUsed: Date.now() } }
+      saveUsage(nextUsage)
+      // Notify the bolt panel (and any other listeners) to re-read storage so
+      // a slash pick ranks as "recently used" there too, not only in the
+      // official / menu.
       try {
-        const skills = await resolveSkills(sessionId)
-        namesCache.set(sessionId, (Array.isArray(skills) ? skills : []).map((s) => s.name))
-        notifyLexicon(sessionId)
+        window.dispatchEvent(new CustomEvent('dsh-skill-picker:usage-updated'))
       } catch {
-        /* keep last cache; lexicon stays empty until a successful fetch */
+        /* best-effort */
       }
     }
-
-    const source = {
-      trigger: '/',
-      name: 'skill-fuzzy',
-      order: -10,
-      async candidates(session, { query, signal }) {
-        const skills = await resolveSkills(session.sessionId)
-        if (signal.aborted) return []
-        namesCache.set(session.sessionId, skills.map((s) => s.name))
-        notifyLexicon(session.sessionId)
-        const ordered = rankByUsage(skills, loadUsage())
-        const q = String(query ?? '').trim().toLowerCase()
-        if (q === '') {
-          // Empty `/` surfaces ALL skills, usage first (same rule as ⚡ panel).
-          return ordered.map((s) => ({ name: s.name, description: s.description }))
-        }
-        // Typing uses fuzzysort (subsequence matching + relevance score) over
-        // name AND description, so partial/gappy queries and keywords match.
-        // The search string also carries the skill's pinyin forms (spaced,
-        // joined, initials — name and description), so `ji yi` / `jiyi` / `jy`
-        // match Chinese skill names & descriptions.
-        const targets = ordered.map((s) => ({
-          s,
-          search: `${s.name} ${s.description ?? ''} ${skillPinyinText(s.name, s.description ?? '')}`,
-        }))
-        const results = fuzzysort.go(q, targets, {
-          key: 'search',
-          limit: 12,
-          threshold: -10000,
-        })
-        return results
-          .filter((r) => r.score > 0)
-          .map((r) => ({ name: r.obj.s.name, description: r.obj.s.description }))
-      },
-      warm(session) {
-        refreshNames(session.sessionId)
-      },
-      lexicon(session) {
-        return namesCache.get(session.sessionId)
-      },
-      subscribeLexicon(session, listener) {
-        const key = session.sessionId
-        const set = lexiconListeners.get(key) ?? new Set()
-        set.add(listener)
-        lexiconListeners.set(key, set)
-        return () => {
-          const cur = lexiconListeners.get(key)
-          if (cur !== undefined) {
-            cur.delete(listener)
-            if (cur.size === 0) lexiconListeners.delete(key)
-          }
-        }
-      },
-      onPick({ candidate }) {
-        // Record usage (same rule as the ⚡ panel) so slash-picked skills
-        // rank higher the next time they open `/`.
-        try {
-          const usage = loadUsage()
-          const name = candidate.name
-          const next = { ...usage, [name]: { count: (usage[name]?.count ?? 0) + 1, lastUsed: Date.now() } }
-          saveUsage(next)
-        } catch {
-          /* usage recording is best-effort */
-        }
-        return { text: `/${candidate.name} ` }
-      },
-    }
-    // inputTriggers is resolved at apply scope (see top of apply); fail loudly
-    // instead of silently dropping the fuzzy `/` source.
-    if (inputTriggers === undefined || typeof inputTriggers.registerSource !== 'function') {
-      console.warn('[dsh-skill-picker] inputTriggers service unavailable; fuzzy / completion disabled (⚡ panel still works)')
-      return
-    }
-    const unregister = inputTriggers.registerSource(source)
+    window.__dshSkillPickerTrack = trackPick
     return () => {
-      unregister()
-      namesCache.clear()
-      lexiconListeners.clear()
+      if (window.__dshSkillPickerFuzzy === fuzzyMatch) delete window.__dshSkillPickerFuzzy
+      if (window.__dshSkillPickerTrack === trackPick) delete window.__dshSkillPickerTrack
     }
-  }, 'dsh-skill-picker: fuzzy / source')
+  }, 'dsh-skill-picker: fuzzy matcher for official / source')
 }

package/src/index.js

@@ -22,6 +22,8 @@ import { readFile, readdir } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 
+import { healUiSkillPatches } from './patch-ui-skill.js'
+
 /** Required services: the route registry and the prompt band. */
 export const inject = ['webServer', 'systemPrompt']
 
@@ -138,4 +140,19 @@ export function apply(ctx) {
     order: SECTION_ORDER,
     text: SKILL_PICKER_GUIDANCE,
   }), 'dsh-skill-picker: prompt section')
+
+  // Self-healing patch for the official ui-skill package: keeps the `/`
+  // completion's skill group ordered above commands and its matching fuzzy
+  // across DSH upgrades. Runs once per boot; idempotent, backed up, and
+  // never allowed to take the host down.
+  ctx.effect(() => {
+    healUiSkillPatches().then((report) => {
+      if (report.files.length > 0) {
+        console.log('[dsh-skill-picker] ui-skill patch report:', JSON.stringify(report))
+      }
+    }).catch((error) => {
+      console.warn('[dsh-skill-picker] ui-skill patch failed:', error)
+    })
+    return () => {}
+  }, 'dsh-skill-picker: ui-skill self-heal patch')
 }

package/src/patch-ui-skill.js

@@ -0,0 +1,185 @@
+/**
+ * dsh-skill-picker — host-side self-healing patch for the official
+ * `@deepseek-ai/dsh-client-ui-skill` package.
+ *
+ * The picker upgrades the official `/` completion in two ways that the
+ * official package does not provide out of the box:
+ *
+ *  1. `order: 2 → -1`  — the skill group sorts ABOVE the command group
+ *     (commands register with the default order 0; lower = higher in the
+ *     official menu).
+ *  2. fuzzy+pinyin candidates — the official prefix-only matcher
+ *     (`skill.name.startsWith(query)`) is replaced by the picker's
+ *     `window.__dshSkillPickerFuzzy` matcher when the picker is mounted
+ *     (single source group, same list, upgraded matching).
+ *
+ * Every DSH boot this module scans every profile under `$DSH_HOME/profiles`
+ * (default `~/.dsh/profiles`) for an installed ui-skill `lib/client.js` —
+ * either the user's local patched copy (`local/dsh-client-ui-skill`) or the
+ * plain npm install (`node_modules/@deepseek-ai/dsh-client-ui-skill`) — and
+ * re-applies both patches when DSH upgrades overwrote them. The original file
+ * is backed up once as `<file>.dsh-skill-picker.bak` before the first write.
+ * All operations are idempotent and never throw: a missing profile, package
+ * or read failure is reported and skipped so a broken patch can never take
+ * the host down.
+ *
+ * @module dsh-skill-picker/patch-ui-skill
+ */
+
+import { readFile, writeFile, copyFile, readdir, access } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+/** Marker that the candidates patch is already in place. */
+const FUZZY_MARKER = '__dshSkillPickerFuzzy'
+
+/** Marker that the pick-tracking patch is already in place. */
+const TRACK_MARKER = '__dshSkillPickerTrack'
+
+/** The self-healing patches, in application order. */
+export const PATCHES = [
+  {
+    id: 'order',
+    title: 'skill group order 2 → -1 (above commands)',
+    isApplied(text) {
+      return /name: "skill",[\s\S]*?order:\s*-1,/.test(text)
+    },
+    apply(text) {
+      return text.replace(/(name: "skill",\s*order: )2,/, '$1-1,')
+    },
+  },
+  {
+    id: 'fuzzy-candidates',
+    title: 'prefix matcher → fuzzy+pinyin matcher',
+    isApplied(text) {
+      return text.includes(FUZZY_MARKER)
+    },
+    apply(text) {
+      return text.replace(
+        /(\t*)return skills\.filter\(\(skill\) => skill\.name\.startsWith\(query\)\)\.map\(\(skill\) => \(\{/,
+        (match, indent) =>
+          `${indent}// dsh-skill-picker patch: fuzzy+pinyin matcher (self-healed)\n` +
+          `${indent}const matcher = typeof window.${FUZZY_MARKER} === "function" ? window.${FUZZY_MARKER}(skills, query) : skills.filter((skill) => skill.name.startsWith(query));\n` +
+          `${indent}return matcher.map((skill) => ({`,
+      )
+    },
+  },
+  {
+    id: 'pick-tracking',
+    title: 'record usage when picked from the official / menu',
+    isApplied(text) {
+      return text.includes(TRACK_MARKER)
+    },
+    apply(text) {
+      return text.replace(
+        /(\t*)onPick\(\{ candidate \}\) \{\n(\t*)return \{ text: `\/\$\{candidate\.name\} ` \};\n(\t*)\}/,
+        (match, i1, i2, i3) =>
+          `${i1}onPick({ candidate }) {\n` +
+          `${i2}  // dsh-skill-picker patch: usage tracking (self-healed)\n` +
+          `${i2}  try { window.${TRACK_MARKER}?.(candidate.name) } catch { /* best-effort */ }\n` +
+          `${i2}  return { text: \`/\${candidate.name} \` };\n` +
+          `${i3}}`,
+      )
+    },
+  },
+]
+
+/** Resolve the DSH home directory, mirroring the official convention. */
+export function dshHome() {
+  return process.env.DSH_HOME ?? path.join(os.homedir(), '.dsh')
+}
+
+/**
+ * Enumerate every installed ui-skill `lib/client.js` across all profiles:
+ * the user's local patched copy first (that is what the profile actually
+ * loads when linked), then the plain npm install. Deduplicated by real path.
+ * Never throws — a missing profiles dir yields [].
+ * @returns {Promise<string[]>} candidate file paths.
+ */
+export async function uiSkillClientPaths() {
+  const profilesDir = path.join(dshHome(), 'profiles')
+  let profiles
+  try {
+    profiles = await readdir(profilesDir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const seen = new Set()
+  const found = []
+  for (const entry of profiles) {
+    if (!entry.isDirectory()) continue
+    const candidates = [
+      path.join(profilesDir, entry.name, 'local', 'dsh-client-ui-skill', 'lib', 'client.js'),
+      path.join(profilesDir, entry.name, 'node_modules', '@deepseek-ai', 'dsh-client-ui-skill', 'lib', 'client.js'),
+    ]
+    for (const candidate of candidates) {
+      try {
+        await access(candidate)
+        const real = await import('node:fs/promises').then(({ realpath }) => realpath(candidate))
+        if (!seen.has(real)) {
+          seen.add(real)
+          found.push(candidate)
+        }
+      } catch {
+        /* not present at this location */
+      }
+    }
+  }
+  return found
+}
+
+/**
+ * Apply both patches to one ui-skill client.js. Idempotent: already-applied
+ * patches are reported as skipped; the original file is backed up once before
+ * the first modification. Never throws for a patch that does not match (it is
+ * reported as `noop`), only for actual I/O failures.
+ * @param {string} file - absolute path to the target client.js.
+ * @returns {Promise<{file: string, patched: string[], skipped: string[], noop: string[]}>}
+ */
+export async function patchUiSkillFile(file) {
+  const text = await readFile(file, 'utf8')
+  const result = { file, patched: [], skipped: [], noop: [] }
+  let next = text
+  for (const patch of PATCHES) {
+    if (patch.isApplied(next)) {
+      result.skipped.push(patch.id)
+      continue
+    }
+    const candidate = patch.apply(next)
+    if (candidate === next) {
+      result.noop.push(patch.id)
+      continue
+    }
+    next = candidate
+    result.patched.push(patch.id)
+  }
+  if (result.patched.length === 0) return result
+  const backup = `${file}.dsh-skill-picker.bak`
+  try {
+    await access(backup)
+  } catch {
+    await copyFile(file, backup)
+  }
+  await writeFile(file, next, 'utf8')
+  return result
+}
+
+/**
+ * Self-heal entry point: scan all profiles, patch every ui-skill copy found,
+ * and return one combined report. Never throws — each failure is collected
+ * into `errors` so the host boot is never taken down by a broken patch.
+ * @returns {Promise<{files: Array, errors: string[]}>}
+ */
+export async function healUiSkillPatches() {
+  const files = await uiSkillClientPaths()
+  const filesReport = []
+  const errors = []
+  for (const file of files) {
+    try {
+      filesReport.push(await patchUiSkillFile(file))
+    } catch (error) {
+      errors.push(`${file}: ${String(error?.message ?? error)}`)
+    }
+  }
+  return { files: filesReport, errors }
+}