@ash-qw/dsh-theme-prts 1.0.5 → 1.1.0

package/src/client/index.js

@@ -1,3 +1,5 @@
+import { registerEmblemToolPreview } from './emblem-tool-preview.js'
+import { createCustomEmblemStore } from './custom-emblem.js'
 import { DEFAULT_PREFERENCES, isSafeMode, loadPreferences, persistPreferences, resetPreferenceGroup, updatePreferenceValue } from './preferences.js'
 import { createHostGeometryAdapter } from './host-geometry-adapter.js'
 import { createComposerGlassAdapter } from './composer-glass-adapter.js'
@@ -42,6 +44,7 @@ export function applyPrtsPlugin(ctx, environment) {
     startupTimings,
   } = environment
   const safeMode = isSafeMode(window?.location?.search ?? '')
+  const stopEmblemPreview = safeMode ? null : registerEmblemToolPreview(ctx, React)
   const storage = window?.localStorage
   const themeService = contextService(ctx, 'theme')
   const composerGlass = createComposerGlassAdapter({ document, window })
@@ -61,6 +64,7 @@ export function applyPrtsPlugin(ctx, environment) {
       sync()
     },
   })
+  const customEmblemStore = createCustomEmblemStore({ window, emblems: assets.emblems, preview: entry => particleField.previewEmblem?.(entry), onChange: value => particleField.setCustomEmblemConfiguration?.(value) })
   const startup = createPrtsStartupSequence({
     document,
     window,
@@ -187,7 +191,7 @@ export function applyPrtsPlugin(ctx, environment) {
     }
     if (!themeAlreadyApplied) theme.apply(preferences)
     operations ||= createOperationsShell({
-      document, window, assets, adapter, hostGeometry,
+      document, window, assets, adapter, hostGeometry, customEmblemStore,
       onSchemeToggle(next, interaction) {
         return theme.setTheme(next, { ...interaction, animate: true })
       },
@@ -339,7 +343,9 @@ export function applyPrtsPlugin(ctx, environment) {
     applyVisualState()
   }
   ctx.effect(() => () => {
+    if (typeof stopEmblemPreview === 'function') stopEmblemPreview()
     statusSource.dispose()
+    customEmblemStore.dispose()
     particleField.dispose()
     startup.dispose({ restoreFocus: false })
     stopStartupReadyWatch()

package/src/client/operations-shell-v2.js

@@ -46,6 +46,7 @@ export function createOperationsShell({
   onSchemeToggle = () => {},
   onSchemeDragStart = () => undefined,
   onThemeDisable = () => {},
+  customEmblemStore,
   onPreferenceChange = () => {},
   onPreferencePreview = () => {},
   onVisualReset = () => {},
@@ -456,6 +457,7 @@ export function createOperationsShell({
       trigger: shell.querySelector('[data-prts-rail-brand]'),
       panel: shell.querySelector('[data-prts-theme-settings]'),
       backdrop: shell.querySelector('[data-prts-settings-backdrop]'),
+      customEmblemStore,
       onPreferenceChange,
       onPreferencePreview,
       onResetVisual: onVisualReset,

package/src/client/particle-field-adapter.js

@@ -365,6 +365,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
     },
     opticalScale: suppliedHeroMask.opticalScale,
   } : maskRecords[rhodesIndex]
+  let customEmblemConfiguration = null
   const targetCache = new Map()
   let particles = []
   let pointerActive = false
@@ -448,35 +449,44 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   }
 
   function sequenceIndexForSegment(segmentValue) {
-    const length = Math.max(1, emblemSequence.length)
+    const length = Math.max(1, (customEmblemConfiguration?.conversation ?? emblemSequence).length)
     return ((segmentValue % length) + length) % length
   }
 
   function emblemForSegment(segmentValue) {
-    return emblemSequence[sequenceIndexForSegment(segmentValue)] ?? emblemSequence[0]
+    const sequence = customEmblemConfiguration?.conversation ?? emblemSequence
+    return sequence[sequenceIndexForSegment(segmentValue)] ?? sequence[0]
   }
 
-  function targetsForIndex(index, density = 'standard') {
-    const key = `${index}:${density}`
+  function targetsForBuiltin(entry, density = 'standard') {
+    const index = emblemSequence.findIndex(item => item.key === entry?.key)
+    const key = `builtin:${index}:${density}`
     const cached = targetCache.get(key)
     if (cached) return cached
     const record = maskRecords[index]
     const targets = record ? createOrthogonalTargets(record.mask, density) : []
-    if (!targets.length) return []
-    targetCache.set(key, targets)
+    if (targets.length) targetCache.set(key, targets)
     return targets
   }
 
+  function targetsForIndex(index, density = 'standard') {
+    const entry = (customEmblemConfiguration?.conversation ?? emblemSequence)[index]
+    if (entry?.kind === 'custom') return entry.targets[density] ?? entry.targets.standard
+    return targetsForBuiltin(entry, density)
+  }
+
   function targetsForSegment(segmentValue, density = preferences.conversationParticleDensity) {
     return targetsForIndex(sequenceIndexForSegment(segmentValue), density)
   }
 
   function heroEmblem() {
+    if (customEmblemConfiguration?.hero) return customEmblemConfiguration.hero
     return emblemSequence[rhodesIndex] ?? emblemSequence[0]
   }
 
   function targetsForHero(density = preferences.heroParticleDensity) {
     const effectiveDensity = effectiveHeroDensity(density)
+    if (customEmblemConfiguration?.hero) return customEmblemConfiguration.hero.targets[effectiveDensity] ?? customEmblemConfiguration.hero.targets.standard
     const key = `hero:${effectiveDensity}`
     const cached = targetCache.get(key)
     if (cached) return cached
@@ -688,7 +698,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   function scheduleTargetPrewarm() {
     cancelTargetPrewarm()
     if (typeof window.requestIdleCallback !== 'function' || !particles.length) return
-    targetPrewarmQueue = emblemSequence.map((_, index) => index)
+    targetPrewarmQueue = (customEmblemConfiguration?.conversation ?? emblemSequence).map((_, index) => index)
       .filter(index => index !== sequenceIndexForSegment(segment))
     const warmNext = () => {
       targetPrewarmHandle = undefined
@@ -1836,6 +1846,21 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
       schemeTransitionPaused = next
       updateFrameGate()
     },
+    previewEmblem(entry) {
+      if (entry?.kind === 'custom') return entry
+      const points = entry ? targetsForBuiltin(entry, 'standard') : heroMaskRecord ? createOrthogonalTargets(heroMaskRecord.mask, 'standard') : []
+      return { targets: { standard: points } }
+    },
+    setCustomEmblemConfiguration(value) {
+      const previousSequence = customEmblemConfiguration?.conversation ?? emblemSequence
+      const nextSequence = value?.conversation ?? emblemSequence
+      const changed = heroActive
+        ? (customEmblemConfiguration?.hero ?? null) !== (value?.hero ?? null)
+        : previousSequence.length !== nextSequence.length || previousSequence.some((entry, index) =>
+          entry.key !== nextSequence[index]?.key || entry.targets !== nextSequence[index]?.targets)
+      customEmblemConfiguration = value
+      if (canvas && changed) { resetTraversal(); scheduleFrame() }
+    },
     update(nextPreferences = {}) {
       const previousPreferences = preferences
       const traversalSpeedChanged = previousPreferences.particleTraversalSpeed !== undefined

package/src/client/theme-settings-workbench.js

@@ -1,8 +1,10 @@
+import { customEmblemMarkup, mountCustomEmblemEditor } from './custom-emblem.js'
 import { PARTICLE_TRAVERSAL_SPEED_DEFAULT, PARTICLE_TRAVERSAL_SPEED_MAX, PARTICLE_TRAVERSAL_SPEED_MIN, PARTICLE_TRAVERSAL_SPEED_STEP, SESSION_FLOW_SPEED_DEFAULT, SESSION_FLOW_SPEED_MAX, SESSION_FLOW_SPEED_MIN, SESSION_FLOW_SPEED_STEP, resolveParticleDetail } from './preferences.js'
 
 const SETTINGS_FOCUSABLE = [
   'button:not([disabled])',
   'input:not([disabled])',
+  'select:not([disabled])',
   'summary',
   '[href]',
   '[tabindex]:not([tabindex="-1"])',
@@ -119,14 +121,16 @@ export function themeSettingsMarkup() {
         </header>
 
         <div data-prts-settings-body>
-        <nav data-prts-settings-nav aria-label="设置分区">
-          <button type="button" data-prts-settings-jump="appearance">外观</button>
-          <button type="button" data-prts-settings-jump="interaction">交互</button>
-          <button type="button" data-prts-settings-jump="flow">会话流线</button>
-          <button type="button" data-prts-settings-jump="particles">粒子效果</button>
+        <nav data-prts-settings-nav role="tablist" aria-label="设置分区">
+          <button type="button" data-prts-settings-jump="appearance" role="tab" id="prts-tab-appearance" aria-controls="prts-page-appearance" aria-selected="true" tabindex="0">外观</button>
+          <button type="button" data-prts-settings-jump="interaction" role="tab" id="prts-tab-interaction" aria-controls="prts-page-interaction" aria-selected="false" tabindex="-1">交互</button>
+          <button type="button" data-prts-settings-jump="flow" role="tab" id="prts-tab-flow" aria-controls="prts-page-flow" aria-selected="false" tabindex="-1">会话流线</button>
+          <button type="button" data-prts-settings-jump="particles" role="tab" id="prts-tab-particles" aria-controls="prts-page-particles" aria-selected="false" tabindex="-1">粒子效果</button>
         </nav>
         <div data-prts-theme-settings-scroll>
-          <section data-prts-settings-presets data-prts-settings-section="appearance" tabindex="-1">
+          <section data-prts-settings-section="appearance" role="tabpanel" id="prts-page-appearance" aria-labelledby="prts-tab-appearance" tabindex="0">
+            <header data-prts-section-heading><strong>外观</strong><small>预设、界面材质与会话样式</small></header>
+          <section data-prts-settings-presets>
             <header><span><strong>视觉预设</strong></span></header>
             <div>${presetMarkup()}</div>
           </section>
@@ -138,14 +142,15 @@ export function themeSettingsMarkup() {
               ${settingButtons('conversationStyle', '会话主题', [['native', '原有'], ['deck-chat', '通讯链路']])}
             </div>
           </section>
-          <section data-prts-settings-common data-prts-settings-section="interaction" tabindex="-1">
-            <header><span><strong>交互</strong></span></header>
+          </section>
+          <section data-prts-settings-common data-prts-settings-section="interaction" role="tabpanel" id="prts-page-interaction" aria-labelledby="prts-tab-interaction" tabindex="0" hidden>
+            <header data-prts-section-heading><strong>交互</strong><small>光标、导航栏与动态反馈</small></header>
             <div data-prts-settings-common-grid>
               ${COMMON_CONTROLS.filter(([key]) => ['cursor', 'railDefaultHidden', 'motion'].includes(key)).map(([key, label, options]) => settingButtons(key, label, options)).join('')}
             </div>
           </section>
-          <section data-prts-settings-common data-prts-settings-section="flow" tabindex="-1">
-            <header><span><strong>会话流线</strong></span></header>
+          <section data-prts-settings-common data-prts-settings-section="flow" role="tabpanel" id="prts-page-flow" aria-labelledby="prts-tab-flow" tabindex="0" hidden>
+            <header data-prts-section-heading><strong>会话流线</strong><small>当前会话的流线与辉光</small></header>
             <div data-prts-settings-common-grid>
               ${COMMON_CONTROLS.filter(([key]) => ['sessionFlow', 'sessionGlow', 'sessionFlowPalette'].includes(key)).map(([key, label, options]) => settingButtons(key, label, options)).join('')}
               ${sessionFlowColorMarkup()}
@@ -157,9 +162,10 @@ export function themeSettingsMarkup() {
             </div>
           </section>
 
-          <details data-prts-settings-advanced data-prts-settings-section="particles" tabindex="-1">
-            <summary><span><strong>粒子效果</strong></span><output data-prts-advanced-summary>标准 / 1×</output></summary>
+          <section data-prts-settings-advanced data-prts-settings-section="particles" role="tabpanel" id="prts-page-particles" aria-labelledby="prts-tab-particles" tabindex="0" hidden>
+            <header data-prts-section-heading><span><strong>粒子效果</strong><small>徽记精度与跟随移动速度</small></span><output data-prts-advanced-summary>标准 / 1×</output></header>
             <div data-prts-settings-advanced-content>
+              ${customEmblemMarkup()}
               <section data-prts-particle-detail>
                 <header><strong>粒子精度</strong><span>同时调整会话与新会话徽记</span></header>
                 <div role="radiogroup" aria-label="粒子精度">${particleMarkup()}</div>
@@ -170,7 +176,7 @@ export function themeSettingsMarkup() {
                 <span data-prts-particle-error role="alert" hidden>粒子资源加载异常，主题已使用静态后备效果</span>
               </section>
             </div>
-          </details>
+          </section>
 
           <footer data-prts-settings-actions>
             <div data-prts-persistence-error hidden role="alert">
@@ -198,6 +204,7 @@ export function createThemeSettingsOverlay({
   trigger,
   panel,
   backdrop,
+  customEmblemStore,
   onOpen = () => {},
   onPreferenceChange = () => {},
   onPreferencePreview = () => {},
@@ -205,6 +212,7 @@ export function createThemeSettingsOverlay({
   onRetrySave = () => {},
 }) {
   const window = document?.defaultView
+  const customEditor = mountCustomEmblemEditor({ panel, window, store: customEmblemStore })
   const transparencyMedia = window?.matchMedia?.('(prefers-reduced-transparency: reduce)')
   const motionMedia = window?.matchMedia?.('(prefers-reduced-motion: reduce)')
   const nativeModal = typeof panel?.showModal === 'function' && typeof panel?.close === 'function'
@@ -516,18 +524,34 @@ export function createThemeSettingsOverlay({
     }, 300)
   }
 
+  let activeSection = 'appearance'
+  const sectionScroll = new Map()
+  function selectSection(key, focus = false) {
+    const scroller = panel?.querySelector('[data-prts-theme-settings-scroll]')
+    const section = panel?.querySelector(`[data-prts-settings-section="${key}"]`)
+    if (!scroller || !section) return
+    if (key !== activeSection) {
+      sectionScroll.set(activeSection, scroller.scrollTop)
+      customEditor.cancelReorder?.()
+      for (const page of panel.querySelectorAll('[data-prts-settings-section]')) page.hidden = page !== section
+      activeSection = key
+      scroller.scrollTop = sectionScroll.get(key) || 0
+      setResetConfirmation(false)
+    }
+    for (const tab of panel.querySelectorAll('[data-prts-settings-jump]')) {
+      const selected = tab.dataset.prtsSettingsJump === key
+      tab.setAttribute('aria-selected', String(selected))
+      tab.tabIndex = selected ? 0 : -1
+      if (selected && focus) tab.focus({preventScroll:true})
+    }
+  }
+
   function onPanelClick(event) {
     if (event.target === panel) { setOpen(false); return }
     const target = event.target?.closest?.('button')
     if (!target) return
     if (target.hasAttribute('data-prts-settings-jump')) {
-      const section = panel.querySelector(`[data-prts-settings-section="${target.dataset.prtsSettingsJump}"]`)
-      const scroller = panel.querySelector('[data-prts-theme-settings-scroll]')
-      if (section && scroller) {
-        if (section.tagName === 'DETAILS') section.open = true
-        scroller.scrollTo?.({ top: target.dataset.prtsSettingsJump === 'appearance' ? 0 : scroller.scrollTop + section.getBoundingClientRect().top - scroller.getBoundingClientRect().top, behavior: 'instant' })
-        section.focus?.({ preventScroll: true })
-      }
+      selectSection(target.dataset.prtsSettingsJump)
       return
     }
     if (target.hasAttribute('data-prts-theme-settings-close')) { setOpen(false); return }
@@ -595,6 +619,16 @@ export function createThemeSettingsOverlay({
 
   function onKeydown(event) {
     if (!isOpen) return
+    const tab = event.target.closest?.('[data-prts-settings-jump]')
+    if (tab && ['ArrowUp','ArrowDown','ArrowLeft','ArrowRight','Home','End'].includes(event.key)) {
+      event.preventDefault()
+      const tabs = [...panel.querySelectorAll('[data-prts-settings-jump]')]
+      const index = tabs.indexOf(tab)
+      const next = event.key === 'Home' ? 0 : event.key === 'End' ? tabs.length-1
+        : (index + (['ArrowRight','ArrowDown'].includes(event.key) ? 1 : -1) + tabs.length) % tabs.length
+      selectSection(tabs[next].dataset.prtsSettingsJump, true)
+      return
+    }
     if (event.key === 'Escape') { event.preventDefault(); setOpen(false); return }
     if (nativeModal || event.key !== 'Tab') return
     const nodes = focusable()
@@ -622,6 +656,7 @@ export function createThemeSettingsOverlay({
 
   trigger?.addEventListener('click', toggle)
   panel?.addEventListener('click', onPanelClick)
+  selectSection('appearance')
   panel?.addEventListener('cancel', onCancel)
   panel?.addEventListener('input', onPanelInput)
   panel?.addEventListener('change', commitFromControl)
@@ -648,6 +683,7 @@ export function createThemeSettingsOverlay({
     close: () => setOpen(false),
     toggle,
     dispose() {
+      customEditor.dispose()
       isOpen = false
       hidePanel()
       if (savedTimer !== undefined) window?.clearTimeout?.(savedTimer)

package/src/index.js

@@ -1,4 +1,16 @@
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { createEmblemService } from './server/emblems.js'
+import { emblemTools } from './server/tools.js'
+import { registerEmblemApi } from './server/api.js'
 export const PACKAGE_ID = '@ash-qw/dsh-theme-prts'
 export const THEME_PLUGIN_ID = 'dsh-theme-prts'
+export const inject = ['tools', 'attachments', 'connection', 'webServer']
 
-export function apply() {}
+export async function apply(ctx) {
+  const directory=join(process.env.DSH_HOME?.trim() || join(homedir(),'.dsh'),'plugins','dsh-theme-prts','emblems')
+  const service=await createEmblemService(directory)
+  const disposers=emblemTools(service,ctx.attachments).map(tool=>ctx.tools.register(tool))
+  disposers.push(registerEmblemApi(ctx,service))
+  ctx.on('dispose',()=>{for(const dispose of disposers.reverse())dispose()})
+}

package/src/server/api.js

@@ -0,0 +1,54 @@
+import { API, draftView, fault } from './emblems.js'
+
+async function body(req) {
+  const chunks=[];let size=0
+  for await(const chunk of req){size+=chunk.length;if(size>16*1024*1024)throw fault(413,'请求过大');chunks.push(chunk)}
+  try{return JSON.parse(Buffer.concat(chunks).toString('utf8'))}catch{throw fault(400,'请求数据无效')}
+}
+function json(res,status,value){res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store'});res.end(JSON.stringify(value))}
+export function registerEmblemApi(ctx,service) {
+  const streams=new Set()
+  const dispose=ctx.webServer.register({kind:'prefix',path:API,handler:async(req,res)=>{
+    try {
+      const admission=ctx.connection.admit(req)
+      if('rejection' in admission){json(res,401,{error:'请先登录 DSH'});return}
+      const path=new URL(req.url,'http://localhost').pathname.slice(API.length)
+      if(req.method==='GET'&&path==='/events') {
+        res.writeHead(200,{'content-type':'text/event-stream','cache-control':'no-cache','x-accel-buffering':'no'})
+        streams.add(res)
+        const send=revision=>res.write(`data: ${JSON.stringify({revision})}\n\n`)
+        const unsubscribe=service.subscribe(send)
+        send(service.snapshot().revision)
+        const heartbeat=setInterval(()=>res.write(': heartbeat\n\n'),25000)
+        res.on('close',()=>{clearInterval(heartbeat);unsubscribe();streams.delete(res)})
+        return
+      }
+      if(req.method==='GET'&&path==='/configuration'){json(res,200,service.snapshot());return}
+      const exported=path.match(/^\/draft\/([a-zA-Z0-9-]+)\/export$/)
+      if(req.method==='GET'&&exported){json(res,200,await service.exportAsset(exported[1]));return}
+      const match=path.match(/^\/draft\/([a-zA-Z0-9-]+)(?:\/(preview\.png|source))?$/)
+      if(req.method==='GET'&&match){
+        if(!match[2]){const d=await service.draft(match[1]);json(res,200,{...draftView(d),value:d.value});return}
+        const bytes=await service.image(match[1],match[2]==='source')
+        res.writeHead(200,{'content-type':match[2]==='source'?'application/octet-stream':'image/png','cache-control':'private, max-age=3600','x-content-type-options':'nosniff'});res.end(bytes);return
+      }
+      if(req.method!=='POST')throw fault(404,'接口不存在')
+      if(req.headers['x-prts-request']!=='1')throw fault(403,'缺少请求标识')
+      const controller=new AbortController()
+      res.on('close',()=>{if(!res.writableEnded)controller.abort(new Error('请求已取消'))})
+      const data=await body(req)
+      if(path==='/configuration'){json(res,200,await service.save(data.configuration,data.revision,controller.signal));return}
+      if(path==='/import'){
+        const d=await service.importAsset(data,controller.signal)
+        json(res,200,{...draftView(d),value:d.value});return
+      }
+      if(path==='/preview'){
+        if(data.image && (typeof data.image!=='string'||! /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data.image)))throw fault(400,'图片编码无效')
+        const d=await service.preview({bytes:data.image?Buffer.from(data.image,'base64'):undefined,baseId:data.draftId,params:data.params,label:data.label},controller.signal)
+        json(res,200,{...draftView(d),value:d.value});return
+      }
+      throw fault(404,'接口不存在')
+    }catch(error){if(!res.headersSent)json(res,error.status||500,{error:error.message});else res.end()}
+  }})
+  return()=>{dispose();for(const res of streams)res.end();streams.clear()}
+}

package/src/server/emblems.js

@@ -0,0 +1,153 @@
+import { mkdir, readFile, writeFile, rename, readdir, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { randomUUID, createHash } from 'node:crypto'
+import { Worker } from 'node:worker_threads'
+import { defaultEmblemConfiguration, validEmblemConfiguration } from '../client/custom-emblem.js'
+
+export const EMBLEMS = [
+  ['rhodes-island','罗德岛'],['lungmen','龙门'],['penguin-logistics','企鹅物流'],['rhine-lab','莱茵生命'],['reunion','整合运动'],
+].map(([key,label])=>({key,label}))
+export const API = '/prts-theme-api/emblems'
+export const DEFAULT_PARAMS = Object.freeze({mode:'auto',threshold:128,zoom:.85,x:0,y:0})
+export function fault(status,message) { return Object.assign(new Error(message),{status}) }
+export function parameters(input = {}, base = DEFAULT_PARAMS) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw fault(400,'编辑参数无效')
+  const result = {...base,...input}
+  if (Object.keys(result).some(k=>!Object.hasOwn(DEFAULT_PARAMS,k)) || !['auto','alpha','dark','light'].includes(result.mode)
+    || !Number.isInteger(result.threshold) || result.threshold<1 || result.threshold>254
+    || !Number.isFinite(result.zoom) || result.zoom<.5 || result.zoom>2
+    || !Number.isFinite(result.x) || Math.abs(result.x)>.5 || !Number.isFinite(result.y) || Math.abs(result.y)>.5) throw fault(400,'编辑参数超出范围')
+  return result
+}
+export function processImage(bytes, params, signal) {
+  signal?.throwIfAborted()
+  return new Promise((resolve,reject)=>{
+    const worker = new Worker(new URL('./image-worker.js',import.meta.url), {workerData:{bytes,params},execArgv:[]})
+    let settled = false
+    const finish = async (error,value) => {
+      if(settled)return; settled=true;clearTimeout(timer);signal?.removeEventListener('abort',abort)
+      await worker.terminate()
+      if(error)reject(error);else resolve(value)
+    }
+    const abort = ()=>void finish(signal.reason || new Error('已取消'))
+    const timer = setTimeout(()=>void finish(fault(408,'图片处理超时，请缩小图片后重试')),15000)
+    signal?.addEventListener('abort',abort,{once:true})
+    worker.once('error',error=>void finish(error))
+    worker.once('exit',code=>{if(!settled)void finish(new Error(`图片处理进程提前退出 (${code})`))})
+    worker.once('message',result=>void finish(result.error?fault(400,result.error):null,result))
+    if(signal?.aborted)abort()
+  })
+}
+async function atomic(path,value) {
+  const temp = `${path}.${randomUUID()}.tmp`
+  await writeFile(temp,value,{mode:0o600});await rename(temp,path)
+}
+const idPattern = /^[a-zA-Z0-9-]{1,80}$/
+export function checkedId(id) { if(typeof id!=='string'||!idPattern.test(id))throw fault(400,'徽记标识无效');return id }
+
+export async function createEmblemService(directory) {
+  await mkdir(directory,{recursive:true,mode:0o700})
+  let state = {revision:0,configuration:defaultEmblemConfiguration(EMBLEMS)}
+  try {
+    const stored=JSON.parse(await readFile(join(directory,'configuration.json'),'utf8'))
+    if(!Number.isInteger(stored.revision)||!validEmblemConfiguration(stored.configuration,EMBLEMS))throw Error('已保存的徽记配置无效')
+    state=stored
+  } catch(error) { if(error.code!=='ENOENT')throw error }
+  let queue=Promise.resolve(), processing=false
+  const listeners=new Set()
+  const serialize=fn=>{const next=queue.then(fn);queue=next.catch(()=>{});return next}
+  const snapshot=()=>structuredClone(state)
+  const draft=async id=>{
+    try{return JSON.parse(await readFile(join(directory,`${checkedId(id)}.draft.json`),'utf8'))}
+    catch(error){if(error.code==='ENOENT')throw fault(404,'草稿不存在');throw error}
+  }
+  const save = (configuration,revision,signal)=>serialize(async()=>{
+    signal?.throwIfAborted()
+    if(revision!==state.revision)throw fault(409,'徽记设置已在其他会话或页面更新，请重新读取后再操作')
+    if(configuration?.version!==2 || !Array.isArray(configuration.conversation) || configuration.conversation.length<1 || configuration.conversation.length>12)throw fault(400,'徽记配置无效')
+    // Custom entries must be generated by this service; clients cannot inject arbitrary particle arrays.
+    const canonical=structuredClone({version:2,hero:configuration.hero,conversation:configuration.conversation})
+    const resolveEntry=async entry=>{
+      if(!entry || typeof entry!=='object')throw fault(400,'徽记配置无效')
+      if(entry.kind==='builtin')return {kind:'builtin',...EMBLEMS.find(e=>e.key===entry.key)}
+      if(entry.kind!=='custom')throw fault(400,'徽记类型无效')
+      const source=await draft(entry.draftId)
+      return {...source.value,kind:'custom',key:entry.key,label:entry.label,draftId:source.id}
+    }
+    if(canonical.hero)canonical.hero=await resolveEntry(canonical.hero)
+    canonical.conversation=await Promise.all(canonical.conversation.map(resolveEntry))
+    if(!validEmblemConfiguration(canonical,EMBLEMS))throw fault(400,'徽记配置无效')
+    const next={revision:state.revision+1,configuration:canonical}
+    signal?.throwIfAborted();await atomic(join(directory,'configuration.json'),JSON.stringify(next));state=next
+    for(const fn of listeners) {try{fn(state.revision)}catch{}}
+    return snapshot()
+  })
+  return {
+    snapshot,save,draft,
+    async exportAsset(id) {
+      const d=await draft(id)
+      const bytes=await readFile(join(directory,`${d.sourceId}.source`))
+      return {format:'prts-emblem',version:1,label:d.label,params:d.params,image:bytes.toString('base64')}
+    },
+    async importAsset(asset,signal) {
+      if(asset?.format!=='prts-emblem'||asset.version!==1)throw fault(400,'不支持的徽记素材包格式或版本')
+      if(typeof asset.label!=='string'||!asset.label.trim()||asset.label.length>100)throw fault(400,'徽记名称无效')
+      if(typeof asset.image!=='string'||!asset.image.length||asset.image.length>Math.ceil(8*1024*1024/3)*4
+        || !/^[A-Za-z0-9+/]+={0,2}$/.test(asset.image)||asset.image.length%4!==0)throw fault(400,'素材包图片编码或大小无效')
+      const bytes=Buffer.from(asset.image,'base64')
+      if(bytes.toString('base64')!==asset.image)throw fault(400,'素材包图片编码无效')
+      // Rebuild from the editable source; never trust particle arrays or filesystem paths in a package.
+      return this.preview({bytes,params:parameters(asset.params),label:asset.label},signal)
+    },
+    previewPath: id=>join(directory,`${checkedId(id)}.png`),
+    subscribe(fn){listeners.add(fn);return()=>listeners.delete(fn)},
+    async preview({bytes,params={},baseId,label},signal) {
+      if(processing)throw fault(409,'正在处理另一张徽记，请稍后重试')
+      processing=true
+      try {
+        const previous=baseId?await draft(baseId):null
+        const effective=parameters(params,previous?.params)
+        if(previous)bytes=await readFile(join(directory,`${previous.sourceId}.source`))
+        if(!bytes?.length || bytes.length>8*1024*1024)throw fault(400,'图片须为 8 MB 以内的 PNG、JPEG 或 WebP')
+        const drafts=(await readdir(directory)).filter(f=>f.endsWith('.draft.json'))
+        if(drafts.length>=200)await serialize(async()=>{
+          const protectedIds=new Set([previous?.id,state.configuration.hero?.draftId,...state.configuration.conversation.map(e=>e.draftId)])
+          const records=await Promise.all(drafts.map(file=>draft(file.slice(0,-11))))
+          const expired=records.filter(d=>!protectedIds.has(d.id)).sort((a,b)=>a.createdAt-b.createdAt).slice(0,drafts.length-199)
+          const expiredIds=new Set(expired.map(d=>d.id))
+          const retainedSources=new Set(records.filter(d=>!expiredIds.has(d.id)).map(d=>d.sourceId))
+          for(const d of expired){await unlink(join(directory,`${d.id}.draft.json`));await unlink(join(directory,`${d.id}.png`))}
+          for(const sourceId of new Set(expired.map(d=>d.sourceId)))if(!retainedSources.has(sourceId))await unlink(join(directory,`${sourceId}.source`))
+        })
+        const result=await processImage(bytes,effective,signal)
+        signal?.throwIfAborted()
+        const id=randomUUID(),sourceId=createHash('sha256').update(bytes).digest('hex')
+        const value={id,sourceId,params:effective,label:String(label||previous?.label||'自定义徽记').slice(0,100),createdAt:Date.now(),value:result.value}
+        await atomic(join(directory,`${sourceId}.source`),bytes)
+        await atomic(join(directory,`${id}.png`),result.preview)
+        await atomic(join(directory,`${id}.draft.json`),JSON.stringify(value))
+        return value
+      } finally {processing=false}
+    },
+    async image(id,source=false) {const d=await draft(id);return readFile(join(directory,source?`${d.sourceId}.source`:`${d.id}.png`))},
+    async apply({draftId,target,entryKey,revision},signal) {
+      const d=await draft(draftId),configuration=snapshot().configuration
+      const entry={...d.value,kind:'custom',key:randomUUID(),label:d.label,draftId:d.id}
+      if(target==='hero')configuration.hero=entry
+      else if(target==='add')configuration.conversation.push(entry)
+      else if(target==='replace') {
+        const index=configuration.conversation.findIndex(e=>e.key===entryKey)
+        if(index<0)throw fault(404,'要替换的正文徽记不存在')
+        configuration.conversation[index]=entry
+      } else throw fault(400,'应用位置无效')
+      return save(configuration,revision,signal)
+    },
+  }
+}
+export function draftView(d) {
+  return {draftId:d.id,label:d.label,params:d.params,particles:Object.fromEntries(Object.entries(d.value.targets).map(([k,v])=>[k,v.length])),previewUrl:`${API}/draft/${d.id}/preview.png`}
+}
+export function stateView(state) {
+  const entry=e=>e?{key:e.key,label:e.label,kind:e.kind,...(e.draftId?{draftId:e.draftId}:{})}:null
+  return {revision:state.revision,scope:'当前 DSH 实例，跨工作区和会话共享',hero:entry(state.configuration.hero),conversation:state.configuration.conversation.map(entry)}
+}

package/src/server/image-worker.js

@@ -0,0 +1,32 @@
+import { parentPort, workerData } from 'node:worker_threads'
+import sharp from 'sharp'
+import { processCustomEmblemPixels } from '../client/custom-emblem.js'
+
+try {
+  const { bytes, params } = workerData
+  const image = sharp(Buffer.from(bytes), { limitInputPixels: 16000000, failOn: 'error' }).rotate()
+  const metadata = await image.metadata()
+  if (!['png','jpeg','webp'].includes(metadata.format)) throw new Error('仅支持 PNG、JPEG、WebP 图片')
+  const { data, info } = await image.ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+  let mode = params.mode
+  if (mode === 'auto') {
+    mode = 'dark'
+    for (let i = 3; i < data.length; i += 4) if (data[i] < 128) { mode = 'alpha'; break }
+  }
+  const scale = 320 / Math.max(info.width, info.height) * params.zoom
+  const width = Math.max(1, Math.round(info.width * scale)), height = Math.max(1, Math.round(info.height * scale))
+  const resized = await sharp(data, { raw: info }).resize(width, height).raw().toBuffer()
+  const rgba = new Uint8ClampedArray(320 * 320 * 4)
+  const left = Math.round((320-width)/2 + params.x*320), top = Math.round((320-height)/2 + params.y*320)
+  for (let y = Math.max(0,top); y < Math.min(320,top+height); y++) {
+    const x = Math.max(0,left), end = Math.min(320,left+width)
+    if (end > x) rgba.set(resized.subarray(((y-top)*width+x-left)*4,((y-top)*width+end-left)*4),(y*320+x)*4)
+  }
+  const value = processCustomEmblemPixels(rgba,320,mode,params.threshold)
+  const dots = value.targets.standard.map(p => {
+    const r = p.kind === 'skeleton' ? 1.2 : .9
+    return `<circle cx="${192+p.x*350}" cy="${192+p.y*350}" r="${r}"/>`
+  }).join('')
+  const preview = await sharp(Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="384" height="384"><rect width="384" height="384" fill="#0d1114"/><g fill="#edf1f2">${dots}</g></svg>`)).png().toBuffer()
+  parentPort.postMessage({ value, preview })
+} catch (error) { parentPort.postMessage({ error: error.message }) }

package/src/server/tools.js

@@ -0,0 +1,67 @@
+import { draftView, stateView, fault } from './emblems.js'
+
+export function sessionImages(agent) {
+  if(!agent?.session)throw fault(400,'请在 DSH 会话中调用此工具')
+  const images=new Map()
+  for(const event of agent.session.snapshotEvents()) {
+    if(event.type!=='user/message')continue
+    for(const part of event.data.content ?? [])if(part.attachment && (part.type==='image' || part.type==='file' && /\.(png|jpe?g|webp)$/i.test(part.attachment.name || '')))images.set(part.attachment.attachmentId,{...part.attachment,attachmentKind:part.type})
+  }
+  return [...images.values()]
+}
+export function emblemTools(service,attachments) {
+  const output={schema:{type:'object'},render:(_args,value)=>[{type:'text',text:JSON.stringify(value)},...(value.previewImage&&value.imageForModel?[{type:'image',attachment:value.previewImage}]:[])]}
+  return [{
+    name:'prts_emblem_inspect',
+    description:'查看 PRTS 主题的新会话徽记、正文轮换列表、配置版本，以及当前会话已上传的图片。仅当用户要求查看或调整主题徽记时使用。徽记设置跨工作区和会话共享；工具不会修改设置。',
+    parameters:{type:'object',properties:{},additionalProperties:false},output,isConcurrencySafe:()=>true,
+    async execute(_args,exec){return JSON.parse(JSON.stringify({...stateView(service.snapshot()),images:sessionImages(exec.agent)}))}
+  },{
+    name:'prts_emblem_preview',
+    description:'将当前会话上传的图片制作成 PRTS 粒子徽记草稿，或继续调整已有草稿。传 attachmentId（来自 inspect）或 draftId，二选一。调整已有正式徽记可使用 inspect 返回的 draftId。仅生成预览，不应用。优先原样使用返回的 previewMarkdown 展示给用户；没有此字段时，告知用户可展开工具卡片查看。不要将 previewUrl 当成本地图片路径。标准密度预览不是原图。用户满意后使用 apply。不要声称已看到预览，除非实际通过视觉工具查看。',
+    parameters:{type:'object',additionalProperties:false,properties:{
+      attachmentId:{type:'string'},draftId:{type:'string'},label:{type:'string',maxLength:100},
+      params:{type:'object',additionalProperties:false,properties:{mode:{type:'string',enum:['auto','alpha','dark','light']},threshold:{type:'integer',minimum:1,maximum:254},zoom:{type:'number',minimum:.5,maximum:2},x:{type:'number',minimum:-.5,maximum:.5},y:{type:'number',minimum:-.5,maximum:.5}}},
+    }},output,isConcurrencySafe:()=>false,
+    async execute(args,exec){
+      const images=sessionImages(exec.agent)
+      if(Boolean(args.attachmentId)===Boolean(args.draftId))throw fault(400,'请选择一张会话图片或一个已有草稿')
+      let bytes,label=args.label
+      if(args.attachmentId) {
+        const ref=images.find(e=>e.attachmentId===args.attachmentId)
+        if(!ref)throw fault(404,'当前会话没有这张图片，请先上传图片或重新读取图片列表')
+        if(ref.bytes>8*1024*1024)throw fault(400,'图片超过 8 MB')
+        const {attachmentKind,...attachment}=ref
+        if(attachmentKind==='file') {
+          const chunks=[];let total=0
+          for await(const chunk of attachments.readFileStream(attachment,exec.signal)) {
+            total+=chunk.length;if(total>8*1024*1024)throw fault(400,'图片超过 8 MB');chunks.push(chunk)
+          }
+          bytes=Buffer.concat(chunks)
+        } else bytes=(await attachments.readImage(attachment,exec.signal)).data
+        label ||= ref.name
+      }
+      const d=await service.preview({bytes,baseId:args.draftId,params:args.params,label},exec.signal)
+      const hostPath=service.previewPath(d.id)
+      const fs=exec.agent.ctx?.get?.('fs')
+      const previewPath=fs?.processPathFromHostPath(hostPath)
+      let previewImage, imageForModel=false
+      const llm=exec.agent.ctx?.get?.('llm')
+      const routed=exec.agent.session.requestHeader?.()?.config
+      const provider=routed?.provider ?? exec.agent.options?.provider, model=routed?.model ?? exec.agent.options?.model
+      if(llm && provider && model) {
+        const info=await llm.resolveModelInfo(provider,model,exec.signal)
+        imageForModel=info.inputModalities?.includes('image') === true
+      }
+      if(imageForModel)previewImage=await attachments.saveImage({data:await service.image(d.id),mediaType:'image/png',name:`prts-preview-${d.id}.png`})
+      return JSON.parse(JSON.stringify({...draftView(d),applied:false,revision:service.snapshot().revision,
+        ...(previewPath?{previewPath,previewMarkdown:`![粒子徽记预览](<${previewPath}>)`}:{}),
+        imageForModel,...(previewImage?{previewImage}:{})}))
+    },
+  },{
+    name:'prts_emblem_apply',
+    description:'按用户要求应用 PRTS 粒子徽记草稿。hero 替换新会话徽记；add 添加正文轮换徽记；replace 替换 entryKey 对应的正文徽记。先 inspect 取得 revision；版本冲突时重新读取并核对，不能盲目重试覆盖。只有用户明确要求应用时才调用，讨论或预览不等于应用。',
+    parameters:{type:'object',additionalProperties:false,properties:{draftId:{type:'string'},target:{type:'string',enum:['hero','add','replace']},entryKey:{type:'string'},revision:{type:'integer',minimum:0}},required:['draftId','target','revision']},output,isConcurrencySafe:()=>false,
+    async execute(args,exec){sessionImages(exec.agent);return {applied:true,...stateView(await service.apply(args,exec.signal))}},
+  }]
+}