@ash-qw/dsh-theme-prts 2.6.0 → 2.6.1

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

@@ -1,3 +1,4 @@
+import { mountPageControls } from './page-controls.js'
 import { themeTransferMarkup, mountThemeTransfer } from './theme-transfer-panel.js'
 import { backgroundMarkup, mountBackgroundSettings } from './custom-background.js'
 import { avatarMarkup, mountAvatarSettings } from './custom-avatar.js'
@@ -13,8 +14,14 @@ const SETTINGS_FOCUSABLE = [
   '[tabindex]:not([tabindex="-1"])',
 ].join(',')
 
+const CURSOR_DESCRIPTIONS = {
+  system: '使用系统默认外观，由浏览器与系统处理移动，不播放 PRTS 点击动画。',
+  prts: '由系统移动 PRTS 光标，页面繁忙时仍较跟手。小控件播放完整点击动画，中等容器仅显示按下与恢复，大容器保持静态。',
+  'prts-follower': '由页面绘制并跟随鼠标，普通区域均可播放 PRTS 按压动画。页面繁忙时可能跟随延迟；文字、缩放等区域显示对应形态。',
+}
+
 const COMMON_CONTROLS = [
-  ['cursor', 'PRTS 光标', [['system', '关闭'], ['prts', '开启']]],
+  ['cursor', '光标模式', [['system', '系统光标'], ['prts', 'PRTS 原生光标'], ['prts-follower', 'PRTS 跟随光标（实验）']]],
   ['railDefaultHidden', '默认隐藏导航栏', [['false', '关闭'], ['true', '开启']]],
   ['motion', '动态效果', []],
   ['sessionFlow', '当前会话流线', [['false', '关闭'], ['true', '开启']]],
@@ -23,9 +30,9 @@ const COMMON_CONTROLS = [
 ]
 
 const SESSION_FLOW_COLOR_CONTROLS = [
-  ['sessionFlowColorBack', '后层'],
-  ['sessionFlowColorCore', '中层'],
   ['sessionFlowColorFront', '前层'],
+  ['sessionFlowColorCore', '中层'],
+  ['sessionFlowColorBack', '后层'],
 ]
 
 const PARTICLE_OPTIONS = [
@@ -62,10 +69,14 @@ function settingButtons(key, label, options) {
       : key === 'sessionFlowPalette'
         ? '<small data-prts-setting-note>同时适配日间与夜间模式</small>'
       : ''
-  if (['heroContrast', 'composerGlass', 'bakerLoading', 'motion', 'cursor', 'railDefaultHidden', 'sessionFlow', 'sessionGlow', 'bakerGroupAvatars', 'conversationEmblem', 'sessionPreview', 'aiToolsEnabled', 'previewOngoing', 'previewTools', 'previewWarning', 'previewDone', 'previewDoubleClick', 'previewFollowOngoing', 'previewFollowWarning'].includes(key)) return `<div data-prts-setting-row="${key}">
+  if (['heroContrast', 'composerGlass', 'bakerLoading', 'motion', 'railDefaultHidden', 'sessionFlow', 'sessionGlow', 'bakerGroupAvatars', 'conversationEmblem', 'sessionPreview', 'aiToolsEnabled', 'previewOngoing', 'previewTools', 'previewWarning', 'previewDone', 'previewDoubleClick', 'previewFollowOngoing', 'previewFollowWarning'].includes(key)) return `<div data-prts-setting-row="${key}">
     <span><strong>${label}</strong>${note}</span>
     <button type="button" role="switch" aria-label="${label}" aria-checked="false" data-prts-setting-switch="${key}" ${key === 'cursor' ? 'data-prts-cursor-switch' : ''}><span aria-hidden="true"></span></button>
   </div>`
+  if (key === 'cursor') return `<label data-prts-setting-row="cursor">
+    <span><strong>光标模式</strong><small id="prts-cursor-description" data-prts-setting-note data-prts-cursor-description></small></span>
+    <select data-prts-cursor-mode aria-label="光标模式" aria-describedby="prts-cursor-description">${options.map(([value,text])=>`<option value="${value}" data-description="${CURSOR_DESCRIPTIONS[value]}">${text}</option>`).join('')}</select>
+  </label>`
   const sample = value => key === 'sessionFlowPalette'
     ? `<i data-prts-option-sample="${key}" data-prts-option-sample-value="${value}" aria-hidden="true"></i>`
     : ''
@@ -88,11 +99,11 @@ function sessionFlowPreviewMarkup() {
     ['core', 'M 3 24 C 30 35 61 7 94 23 C 124 37 148 7 177 20'],
     ['front', 'M 3 18 C 34 4 66 30 96 12 C 125 -1 148 30 177 24'],
   ]
-  return `<svg data-prts-session-flow-preview viewBox="0 0 180 42" aria-label="三色流线预览" role="img">
+  return `<svg data-prts-session-flow-preview viewBox="0 0 180 42" preserveAspectRatio="none" aria-label="三色流线预览" role="img">
     ${filaments.map(([strand, path]) => `<g data-prts-session-flow-preview-filament="${strand}">
-      <path data-prts-session-flow-preview-layer="halo" d="${path}"></path>
-      <path data-prts-session-flow-preview-layer="body" d="${path}"></path>
-      <path data-prts-session-flow-preview-layer="core" d="${path}"></path>
+      <path vector-effect="non-scaling-stroke" data-prts-session-flow-preview-layer="halo" d="${path}"></path>
+      <path vector-effect="non-scaling-stroke" data-prts-session-flow-preview-layer="body" d="${path}"></path>
+      <path vector-effect="non-scaling-stroke" data-prts-session-flow-preview-layer="core" d="${path}"></path>
     </g>`).join('')}
   </svg>`
 }
@@ -176,9 +187,9 @@ export function themeSettingsMarkup() {
           </section>
           <section data-prts-settings-section="ai-tools" data-prts-ai-tools role="tabpanel" id="prts-page-ai-tools" aria-labelledby="prts-tab-ai-tools" tabindex="0" hidden>
             <div data-prts-preview-settings><div data-prts-preview-master>
-            ${previewSetting('aiToolsEnabled', '允许 AI 定制主题', '默认开启 · 共 5 个工具 · 影响此 DSH 实例的所有会话')}
+            ${previewSetting('aiToolsEnabled', '允许 AI 定制主题', '默认开启 · 12 个定制工具，另有只读状态入口 · 影响此 DSH 实例的所有会话')}
             </div></div>
-            <p>开启后，AI 可以通过工具调整粒子徽记和 Baker 头像。关闭后，后续模型请求不再提供这些工具，手动设置不受影响；已有对话中的工具记录不会删除。</p>
+            <p>开启后，AI 可以通过工具调整粒子徽记、Baker 头像和背景图片、保护区域、背景模式、遮罩与材质，以及导入、导出主题配置。关闭后停止提供定制工具，仅保留只读状态入口，提示 AI 请你手动开启开关，不自行改文件绕过。手动设置不受影响；已有对话中的工具记录不会删除。</p>
             <section>
               <h3>粒子徽记 <small>3 个工具</small></h3>
               <p>将会话中的图片制作成粒子徽记，用于新会话页面或正文轮换。</p>
@@ -200,6 +211,29 @@ export function themeSettingsMarkup() {
                 <dt><code>prts_avatar_apply</code></dt><dd>替换用户或 AI 头像、基于现有原图重新裁剪，或恢复默认头像。</dd>
               </dl><p>单图最大 5 MB、2500 万像素；裁剪支持 1～4 倍缩放。修改立即影响此实例所有会话，不会自动切换会话样式。替换后不保留旧原图；恢复默认会删除自定义原图。</p></details>
             </section>
+            <section>
+              <h3>会话背景 <small>4 个工具</small></h3>
+              <p>使用上传、AI 生成或搜索下载的图片设置背景，也可以调整重要区域保护、背景模式、遮罩和材质。</p>
+              <ol><li>提供图片，或让具备相应工具的 AI 生成、寻找图片。</li><li>让 AI 将图片设为完整背景、左侧边栏背景或会话正文背景，再启用对应模式。</li></ol>
+              <blockquote>“找一张适合阅读的背景图，设为完整背景，尽量保住图中的人物。”</blockquote>
+              <details><summary>工具说明与限制</summary><dl>
+                <dt><code>prts_background_inspect</code></dt><dd>查看背景、模式、遮罩、材质及会话可用图片。</dd>
+                <dt><code>prts_background_preview</code></dt><dd>预览候选或已保存图片的日夜遮罩、裁剪效果，不修改主题；不包含气泡、文字和毛玻璃。</dd>
+                <dt><code>prts_background_apply</code></dt><dd>替换或移除图片，设置或清除保护区域。</dd>
+                <dt><code>prts_background_configure</code></dt><dd>切换默认、分区或完整背景，调整遮罩及五个区域的模糊度、底色不透明度。</dd>
+              </dl><p>支持 PNG、JPEG、WebP、AVIF，单图最大 10 MB、4000 万像素。图片在同一实例共享，模式、遮罩和材质在同一 profile 同步。替换或移除不保留旧图；切回默认背景会保留素材。图片列表按最近出现排序，并标记同名图片的最近版本。生成与搜索需要会话已有相应工具，下载或生成的本地图片可先用 read_image 读取，无需重新上传。工具不会自动启用主题总开关。</p></details>
+            </section>
+            <section>
+              <h3>主题导入与导出 <small>3 个工具</small></h3>
+              <p>在会话中导出主题文件，或上传主题文件，让 AI 先检查内容再导入。</p>
+              <blockquote>“导出当前主题，包含素材。” “检查这个主题文件，告诉我会覆盖哪些设置。”</blockquote>
+              <details><summary>工具说明与限制</summary><dl>
+                <dt><code>prts_theme_export</code></dt><dd>导出可下载的主题附件，默认包含背景、头像和徽记，也可仅导出设置。</dd>
+                <dt><code>prts_theme_import_preview</code></dt><dd>预检文件，列出配置变化、素材覆盖范围和无法保留的字段，不修改主题。</dd>
+                <dt><code>prts_theme_import</code></dt><dd>使用预检结果导入，先保存备份附件；失败时尝试回退已写入的素材。</dd>
+              </dl><p>与设置界面文件互通，最大 160 MB。完整导入会清理被替换的旧背景和头像，并为自定义徽记生成新草稿；草稿约 200 份时清理较旧且未受保护的记录，正在使用的徽记受保护。预检 15 分钟内有效，仅限当前会话，配置发生变化后需重新预检。导入可能关闭主题或 AI 工具，请先核对变化；需要恢复时可重新导入备份文件。</p></details>
+            </section>
+            <details><summary>工具关闭时的提示</summary><p><code>prts_theme_status</code> 始终可用，仅报告开关状态和手动开启位置，不读取素材、不修改配置。AI 应先检查此状态；关闭时先提醒你开启，不通过脚本、接口或文件编辑绕过开关。</p></details>
           </section>
           <section data-prts-settings-section="assistance" role="tabpanel" id="prts-page-assistance" aria-labelledby="prts-tab-assistance" tabindex="0" hidden>
             <section data-prts-preview-settings>
@@ -585,6 +619,10 @@ export function createThemeSettingsOverlay({
       toggle.setAttribute('aria-checked', String(enabled))
       toggle.classList.toggle('is-active', enabled)
     }
+    const cursorSelect = panel.querySelector('[data-prts-cursor-mode]')
+    if (cursorSelect) cursorSelect.value = currentPreferences.cursor
+    const cursorDescription = panel.querySelector('[data-prts-cursor-description]')
+    if (cursorDescription) cursorDescription.textContent = CURSOR_DESCRIPTIONS[currentPreferences.cursor]
     const replyLimitSelect = panel.querySelector('[data-prts-preview-reply-limit]')
     if (replyLimitSelect) replyLimitSelect.value = String(currentPreferences.previewReplyLimit)
     const replyLimitRow = panel.querySelector('[data-prts-setting-row="previewReplyLimit"]')
@@ -806,6 +844,7 @@ export function createThemeSettingsOverlay({
   const renderMediaState = () => renderState()
   const commitFromControl = event => {
     const target = event.target
+    if (target?.matches?.('[data-prts-cursor-mode]')) { if (event.type === 'change') onPreferenceChange('cursor', target.value); return }
     if (target?.matches?.('[data-prts-corner-color]')) { if (event.type === 'change') onPreferenceChange(cornerCustomKey(), target.value); return }
     if (target?.matches?.('input[data-prts-setting-color]')) {
       if (event.type === 'change' || event.type === 'focusout') commitSessionFlowColor(target.dataset.prtsSettingKey)
@@ -816,6 +855,7 @@ export function createThemeSettingsOverlay({
     if (target.dataset.prtsSettingKey === 'sessionFlowSpeed') commitSessionFlowSpeed()
   }
 
+  const pageControls = mountPageControls({panel,window})
   trigger?.addEventListener('click', toggle)
   panel?.addEventListener('click', onPanelClick)
   selectSection('appearance')
@@ -855,6 +895,7 @@ export function createThemeSettingsOverlay({
     close: () => setOpen(false),
     toggle,
     dispose() {
+      pageControls.dispose()
       transferEditor.dispose()
       customEditor.dispose()
       avatarEditor.dispose()

package/src/client/theme-transfer.js

@@ -101,7 +101,7 @@ export function describeThemePackage(value) {
   return `${count} 项主题设置、${transferSlots.filter(k => a.backgrounds[k]).length} 张背景、${transferRoles.filter(k => a.avatars[k]).length} 个头像、${a.emblems.items.length} 个自定义徽记。将替换当前素材及徽记排列，空项恢复为默认。`
 }
 
-export function createThemeTransfer({ window, getPreferences, savePreferences, checkWritable, checkExport = checkWritable, themeVersion, onAvatarConfiguration = () => {} }) {
+export function createThemeTransfer({ window, getPreferences, savePreferences, checkWritable, checkExport = checkWritable, themeVersion, onAvatarConfiguration = () => {}, onDownload, readImage = (blob, signal) => readTransferFile(window, blob, signal, undefined, true), backupNotice = '导入前备份已发起下载，可重新导入恢复。' }) {
   let busy = false, backup
   const request = async (path, data, signal) => {
     checkTransferCancelled(signal)
@@ -128,7 +128,7 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
           if (!/^[a-f0-9-]{36}$/.test(entry.id)) throw Error('背景引用无效')
           const response = await window.fetch('/prts-theme-api/backgrounds/image/' + entry.id, { credentials: 'same-origin', signal })
           if (!response.ok) throw Error('无法导出背景图片')
-          backgrounds[slot] = await readTransferFile(window, await response.blob(), signal, undefined, true)
+          backgrounds[slot] = await readImage(await response.blob(), signal)
         }
       }
       progress({ value: 0.35, label: '正在读取头像…' })
@@ -169,6 +169,7 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
     try { return await fn() } finally { busy = false }
   }
   function download(value, name = 'theme') {
+    if (onDownload) return onDownload(value, name)
     const blob = new window.Blob([JSON.stringify(value)], { type: 'application/json' })
     if (blob.size > THEME_PACKAGE_LIMIT) throw Error('主题文件超过 160 MB，请减少素材后重试')
     const url = window.URL.createObjectURL(blob), link = window.document.createElement('a')
@@ -185,7 +186,7 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
     progress({ value: 0.3, label: '正在生成导入前备份…' })
     await new Promise(resolve => window.setTimeout(resolve, 0))
     checkTransferCancelled(signal)
-    download(backup, 'before-import')
+    await download(backup, 'before-import')
     let completed = 0
     const total = value.assets ? value.assets.emblems.items.length + 7 : 1
     const step = label => progress({ value: 0.35 + 0.65 * completed / total, label })
@@ -229,7 +230,7 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
       let failures = 0
       for (const restore of undo.reverse()) { try { await restore() } catch { failures++ } }
       if (signal?.aborted && !failures && error.name === 'AbortError') throw Error('操作已取消，已回退已写入的素材。')
-      throw Error(`${error.message}。${failures ? '部分素材未能自动恢复。' : '已回退已确认写入的素材。'}若连接中断，请检查实际状态；导入前备份已发起下载，可重新导入恢复。`)
+      throw Error(`${error.message}。${failures ? '部分素材未能自动恢复。' : '已回退已确认写入的素材。'}若连接中断，请检查实际状态；${backupNotice}`)
     }
   }
   return {

package/src/index.js

@@ -5,6 +5,10 @@ import { createAvatarService, registerAvatarApi } from './server/avatars.js'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { createEmblemService } from './server/emblems.js'
+import { themeToolStatus, THEME_TOOL_POLICY, ENABLE_THEME_TOOLS } from './server/theme-tool-status.js'
+import { transferTools } from './server/transfer-tools.js'
+import { readFile } from 'node:fs/promises'
+import { backgroundTools } from './server/background-tools.js'
 import { avatarTools } from './server/avatar-tools.js'
 import { emblemTools } from './server/tools.js'
 import { registerEmblemApi } from './server/api.js'
@@ -28,12 +32,29 @@ export async function apply(ctx, config = {}) {
   const service=await createEmblemService(directory)
   const backgrounds=await createBackgroundService(join(directory,'..','backgrounds'))
   const avatars=await createAvatarService(join(directory,'..','avatars'))
-  const definitions=[...emblemTools(service,ctx.attachments),...avatarTools(avatars,ctx.attachments)]
+  const themeVersion=JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')).version
+  const definitions=[...emblemTools(service,ctx.attachments),...avatarTools(avatars,ctx.attachments),...backgroundTools(backgrounds,ctx.attachments,ctx),...transferTools({backgrounds,avatars,emblems:service,attachments:ctx.attachments,host:ctx,themeVersion})]
+  const toolsEnabled=()=>(config.aiToolsEnabled?.get?.() ?? config.aiToolsEnabled) !== false
+  const disposeStatus=ctx.tools.register(themeToolStatus(toolsEnabled))
+  ctx.inject(['systemPrompt'], promptCtx=>{
+    if(typeof promptCtx.systemPrompt?.context!=='function')return
+    promptCtx.effect(()=>promptCtx.systemPrompt.context({
+      name:'prts-theme-tools:'+ (ctx.fiber?.entry?.id ?? THEME_PLUGIN_ID),
+      order:1500,required:true,interpolate:false,
+      text:()=> 'PRTS AI 定制工具当前'+(toolsEnabled()?'已开启。':'已关闭。'+ENABLE_THEME_TOOLS)+' '+THEME_TOOL_POLICY,
+    }))
+  })
   let toolDisposers=[]
   const syncTools=()=>{
-    const enabled=(config.aiToolsEnabled?.get?.() ?? config.aiToolsEnabled) !== false
+    const enabled=toolsEnabled()
     if(enabled && !toolDisposers.length) {
-      for(const tool of definitions)toolDisposers.push(ctx.tools.register(tool))
+      for(const tool of definitions)toolDisposers.push(ctx.tools.register({...tool,
+        description:tool.description+' '+THEME_TOOL_POLICY,
+        execute:(args,exec)=>{
+          if(!toolsEnabled())throw Error('PRTS AI 定制工具已关闭。'+ENABLE_THEME_TOOLS+' '+THEME_TOOL_POLICY)
+          return tool.execute(args,exec)
+        },
+      }))
     } else if(!enabled) {
       for(const dispose of toolDisposers.splice(0).reverse())dispose()
     }
@@ -43,7 +64,7 @@ export async function apply(ctx, config = {}) {
   const stopConfig=ctx.on('app-boot/config-reload',syncTools)
   const disposers=[registerEmblemApi(ctx,service),registerAvatarApi(ctx,avatars),registerBackgroundApi(ctx,backgrounds)]
   ctx.effect(()=>async()=>{
-    stopConfig()
+    stopConfig();disposeStatus()
     for(const dispose of toolDisposers.splice(0).reverse())dispose()
     for(const dispose of disposers.reverse())dispose()
     await service.dispose();await backgrounds.dispose()

package/src/server/avatar-tools.js

@@ -43,7 +43,7 @@ export function avatarTools(service,attachments){
         const ref=images.find(image=>image.attachmentId===args.attachmentId)
         if(!ref)throw fault(404,'当前会话没有这张图片，请先上传或用 read_image 读取图片，再 inspect')
         if(ref.bytes>limit)throw fault(400,'图片超过 5 MB')
-        const {attachmentKind,origin,toolName,...attachment}=ref
+        const {attachmentKind,origin,toolName,lastSeenOrder,lastSeenAt,latestForName,...attachment}=ref
         let bytes
         if(attachmentKind==='file'){
           const chunks=[];let size=0

package/src/server/background-preview.js

@@ -0,0 +1,100 @@
+import sharp from 'sharp'
+import { sessionImages } from './tools.js'
+import { fault } from './emblems.js'
+import { prepareBackgroundImage } from './backgrounds.js'
+import { backgroundPlacement, validBackgroundRegion } from '../shared/background-region.js'
+
+// Keep these paired with the root light/dark canvas tokens in prts.css.
+export const BACKGROUND_CANVAS={dark:'#080a0c',light:'#eef1f3'}
+export async function readBackgroundAttachment(attachments,images,id,exec){
+  const ref=images.find(image=>image.attachmentId===id),limit=10*1024*1024
+  if(!ref)throw fault(404,'当前会话没有这张图片，请先上传或 read_image 读取生成/下载的图片，再 inspect')
+  if(ref.bytes>limit)throw fault(400,'图片超过 10 MB')
+  const {attachmentKind,origin,toolName,lastSeenOrder,lastSeenAt,latestForName,...attachment}=ref
+  let bytes
+  if(attachmentKind==='file'){
+    const chunks=[];let size=0
+    for await(const chunk of attachments.readFileStream(attachment,exec.signal)){
+      exec.signal?.throwIfAborted()
+      size+=chunk.length;if(size>limit)throw fault(400,'图片超过 10 MB');chunks.push(chunk)
+    }
+    bytes=Buffer.concat(chunks)
+  }else bytes=(await attachments.readImage(attachment,exec.signal)).data
+  exec.signal?.throwIfAborted()
+  if(bytes.length>limit)throw fault(400,'图片超过 10 MB')
+  return Buffer.from(bytes)
+}
+export async function renderBackgroundPreview(bytes,{width,height,scheme,dim,region}){
+  const metadata=await sharp(bytes).metadata(),sw=metadata.width,sh=metadata.height
+  const placement=backgroundPlacement(sw,sh,width,height,region)
+  const scale=placement.width/sw
+  // Crop before resizing to bound memory even for extremely wide/tall images.
+  const left=Math.max(0,Math.min(sw-1,Math.round(-placement.x/scale)))
+  const top=Math.max(0,Math.min(sh-1,Math.round(-placement.y/scale)))
+  const crop={left,top,width:Math.max(1,Math.min(sw-left,Math.round(width/scale))),height:Math.max(1,Math.min(sh-top,Math.round(height/scale)))}
+  const canvas=BACKGROUND_CANVAS[scheme]
+  const image=await sharp(bytes).extract(crop).resize(width,height,{fit:'fill'}).flatten({background:canvas}).toColourspace('srgb').png().toBuffer()
+  // Match CSS color-mix(in srgb); do not blend in linear-light space.
+  const rgb={r:parseInt(canvas.slice(1,3),16),g:parseInt(canvas.slice(3,5),16),b:parseInt(canvas.slice(5,7),16),alpha:dim}
+  const overlay=await sharp({create:{width,height,channels:4,background:rgb}}).png().toBuffer()
+  return {data:await sharp(image).composite([{input:overlay,blend:'over'}]).png().toBuffer(),clipped:placement.clipped,crop,canvas}
+}
+export function backgroundPreviewTool(service,attachments,readSettings){
+  return {
+    name:'prts_background_preview',
+    description:'预览 PRTS 背景的裁剪与遮罩合成，不应用、不修改主题。指定 slot 预览已保存背景，或 attachmentId 预览会话候选图片（二选一）；候选图先按实际保存规则转正、缩放并转 WebP。dim 默认使用当前背景遮罩，可临时覆盖；scheme 默认为 both，同时生成日间/夜间图，因为服务端不能判断用户页面当前日夜模式。可指定预览宽高和归一化保护区域，默认使用已保存图片的保护区域。返回预览附件、尺寸、底色、遮罩、裁剪信息；这是背景层预览，不含消息泡、文字、侧栏毛玻璃等界面材质，不是实际页面截图。必须查看预览才能评价视觉效果；预览图不能再作为原始背景素材。修改 dim 后可再次预览。',
+    parameters:{type:'object',additionalProperties:false,properties:{
+      slot:{type:'string',enum:['full','sidebar','conversation']},attachmentId:{type:'string'},
+      dim:{type:'number',minimum:0,maximum:.9},scheme:{type:'string',enum:['dark','light','both']},
+      width:{type:'integer',minimum:64,maximum:1920},height:{type:'integer',minimum:64,maximum:1920},
+      region:{anyOf:[{type:'null'},{type:'object',additionalProperties:false,properties:{
+        x:{type:'number',minimum:0,maximum:1},y:{type:'number',minimum:0,maximum:1},
+        width:{type:'number',exclusiveMinimum:0,maximum:1},height:{type:'number',exclusiveMinimum:0,maximum:1},
+      },required:['x','y','width','height']}]},
+    }},
+    output:{schema:{type:'object'},render:(_args,value)=>[
+      {type:'text',text:JSON.stringify(value)},
+      ...value.previews.flatMap(p=>[{type:'file',attachment:p.file},...(value.imageForModel?[{type:'image',attachment:p.image}]:[])]),
+    ]},
+    isConcurrencySafe:()=>false,
+    async execute(args,exec){
+      exec.signal?.throwIfAborted()
+      const images=sessionImages(exec.agent)
+      if(Boolean(args.slot)===Boolean(args.attachmentId))throw fault(400,'请选择已保存背景 slot 或候选 attachmentId，二选一')
+      if(args.slot && !['full','sidebar','conversation'].includes(args.slot))throw fault(400,'背景区域无效')
+      const configuration=service.snapshot(),settings=readSettings()
+      const scheme=args.scheme ?? 'both',dim=args.dim ?? settings.dim
+      const width=args.width ?? (args.slot==='sidebar'?360:1280),height=args.height ?? (args.slot==='sidebar'?900:720)
+      if(!['dark','light','both'].includes(scheme)||!Number.isFinite(dim)||dim<0||dim>.9)throw fault(400,'请指定有效日夜模式和 0..0.9 遮罩；设置不可读时须显式指定 dim')
+      if(![width,height].every(v=>Number.isInteger(v)&&v>=64&&v<=1920))throw fault(400,'预览宽高须为 64..1920 的整数')
+      const region=Object.hasOwn(args,'region')?args.region:args.slot?configuration[args.slot]?.region ?? null:null
+      if(!validBackgroundRegion(region))throw fault(400,'背景保护区域无效')
+      let bytes
+      if(args.slot){
+        const entry=configuration[args.slot]
+        if(!entry)throw fault(400,'此区域尚未设置图片')
+        bytes=await service.image(entry.id)
+      }else bytes=(await prepareBackgroundImage(await readBackgroundAttachment(attachments,images,args.attachmentId,exec))).data
+      let imageForModel=false
+      const llm=exec.agent.ctx?.get?.('llm'),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)imageForModel=(await llm.resolveModelInfo(provider,model,exec.signal)).inputModalities?.includes('image')===true
+      const previews=[]
+      for(const mode of scheme==='both'?['dark','light']:[scheme]){
+        exec.signal?.throwIfAborted()
+        const {data,...details}=await renderBackgroundPreview(bytes,{width,height,scheme:mode,dim,region})
+        exec.signal?.throwIfAborted()
+        const name=`prts-background-preview-${mode}.png`,file=await attachments.saveFile({data,name})
+        const image=imageForModel?await attachments.saveImage({data,mediaType:'image/png',name}):undefined
+        const hostPath=attachments.fileHostPath?.(file),fs=exec.agent.ctx?.get?.('fs')
+        const previewPath=hostPath?fs?.processPathFromHostPath(hostPath):undefined
+        previews.push({scheme:mode,width,height,dim,region,...details,file,...(image?{image}:{}),
+          ...(previewPath?{previewPath,previewMarkdown:`![${mode==='dark'?'夜间':'日间'}背景预览](<${previewPath}>)`}:{})})
+      }
+      exec.signal?.throwIfAborted()
+      if(args.slot && service.snapshot().revision!==configuration.revision || args.dim===undefined && readSettings().revision!==settings.revision)throw fault(409,'背景或遮罩已变化，请重新预览')
+      return {applied:false,imageForModel,revision:configuration.revision,settingsRevision:settings.revision,
+        note:'仅模拟背景铺满裁剪、保护区域和遮罩；裁剪按源图像素取整，不包含正文、气泡、毛玻璃。',previews}
+    },
+  }
+}

package/src/server/background-tools.js

@@ -0,0 +1,109 @@
+import { backgroundPreviewTool, readBackgroundAttachment } from './background-preview.js'
+import { sessionImages } from './tools.js'
+import { fault } from './emblems.js'
+import { validBackgroundRegion } from '../shared/background-region.js'
+import { normalizePreferences } from '../client/preferences.js'
+
+const slots=['full','sidebar','conversation']
+const materialTargets=['sidebar','rightSidebar','rail','baker','classicUser']
+const materialSchema={type:'object',additionalProperties:false,properties:Object.fromEntries(
+  [['blur',32],['opacity',1]].map(([kind,max])=>[kind,{type:'object',additionalProperties:false,
+    properties:Object.fromEntries(materialTargets.map(target=>[target,{type:kind==='blur'?'integer':'number',minimum:0,maximum:max}]))}]))}
+function materialView(value){
+  return Object.fromEntries(['blur','opacity'].map(kind=>[kind,Object.fromEntries(
+    materialTargets.map(target=>[target,value[target+(kind==='blur'?'Blur':'Opacity')]]))]))
+}
+function materialPatch(material){
+  const patch={}
+  const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value)
+  if(!object(material))throw fault(400,'material 必须是对象')
+  for(const [kind,values] of Object.entries(material)){
+    if(!['blur','opacity'].includes(kind)||!object(values))throw fault(400,'material 仅支持 blur 和 opacity 对象')
+    for(const [target,value] of Object.entries(values)){
+      if(!materialTargets.includes(target))throw fault(400,'未知材质区域：'+target)
+      const max=kind==='blur'?32:1
+      if(!Number.isFinite(value)||value<0||value>max||(kind==='blur'&&!Number.isInteger(value)))
+        throw fault(400,kind==='blur'?'blur 必须是 0..32 的整数（px）':'opacity 必须在 0..1')
+      patch[target+(kind==='blur'?'Blur':'Opacity')]=value
+    }
+  }
+  return patch
+}
+const revision={type:'integer',minimum:0}
+const region={anyOf:[{type:'null'},{type:'object',additionalProperties:false,properties:{
+  x:{type:'number',minimum:0,maximum:1},y:{type:'number',minimum:0,maximum:1},
+  width:{type:'number',exclusiveMinimum:0,maximum:1},height:{type:'number',exclusiveMinimum:0,maximum:1},
+},required:['x','y','width','height']}]}
+function checkRevision(value){if(!Number.isInteger(value)||value<0)throw fault(400,'请先 inspect 获取配置版本')}
+export function backgroundTools(service,attachments,host){
+  const readSettings=()=>{
+    const settings=host?.get?.('settings'),ns=host?.fiber?.entry?.options?.id
+    const descriptor=ns && settings?.describe({redactSecrets:true}).find(item=>item.ns===ns)
+    if(!descriptor)return {available:false,writable:false}
+    const value=normalizePreferences(descriptor.value)
+    return {available:true,writable:settings.writable===true,revision:descriptor.revision,
+      enabled:value.enabled,mode:value.backgroundMode,dim:value.backgroundDim,material:materialView(value),conversationStyle:value.conversationStyle}
+  }
+  const view=()=>{
+    const state=service.snapshot(),settings=readSettings()
+    return {...state,settings,activeSlots:settings.enabled
+      ? settings.mode==='full'?['full'].filter(slot=>state[slot])
+      :settings.mode==='split'?['sidebar','conversation'].filter(slot=>state[slot]):[]:[]}
+  }
+  const output={schema:{type:'object'},render:(_args,value)=>[{type:'text',text:JSON.stringify(value)}]}
+  return [backgroundPreviewTool(service,attachments,readSettings),{
+    name:'prts_background_inspect',
+    description:'查看 PRTS 背景图片尺寸、保护区域、图片 revision，以及当前 profile 的模式、遮罩 dim、五个区域的 material（blur/opacity）、conversationStyle、settings.revision 和启用状态；列出当前会话上传或工具返回的图片，不修改设置。支持用户图片和 AI 生成、编辑、搜索下载的图片：若生成/搜索工具未直接返回图片附件，先用该会话已有工具保存图片到工作区，再 read_image 读取，然后 inspect 获取 attachmentId。列表按最近出现排序，lastSeenOrder 是会话出现顺序，latestForName 标记同名图片最近出现的版本，并非文件修改时间。需要评估视觉效果时调用 prts_background_preview。本工具不生成、搜索或下载图片，不接受 URL 或任意本地路径。',
+    parameters:{type:'object',properties:{},additionalProperties:false},output,isConcurrencySafe:()=>true,
+    async execute(_args,exec){return {...view(),images:sessionImages(exec.agent)}},
+  },{
+    name:'prts_background_apply',
+    description:'按用户要求设置背景素材。slot=full 完整背景、sidebar 左侧边栏、conversation 会话正文。action=replace 使用 inspect 返回的当前会话 attachmentId；protect 调整已有图片的保护区域；remove 删除该区域图片。region 为按 EXIF 转正后图片的归一化矩形 x/y/width/height，范围 0..1；null 清除保护框；替换时未指定会清除旧框。保护框只指导铺满裁剪，不能保证所有窗口完整容纳。先 inspect 获取图片 revision，冲突时重新读取，勿盲目覆盖。支持上传及 AI 工具返回的图片；生成图或下载图先 read_image 再 inspect。支持 PNG/JPEG/WebP/AVIF，最大 10 MB、4000 万像素，保存为最长 3840×2160 范围内的 WebP。修改素材影响同一 DSH 实例，替换/移除不保留旧原图。本工具不切换模式；保存后检查 activeSlots，必要时用 configure 启用对应模式。主题总开关不会自动打开。',
+    parameters:{type:'object',additionalProperties:false,properties:{
+      slot:{type:'string',enum:slots},action:{type:'string',enum:['replace','protect','remove']},
+      attachmentId:{type:'string'},region,revision,
+    },required:['slot','action','revision']},output,isConcurrencySafe:()=>false,
+    async execute(args,exec){
+      const images=sessionImages(exec.agent)
+      exec.signal?.throwIfAborted()
+      checkRevision(args.revision)
+      if(!slots.includes(args.slot)||!['replace','protect','remove'].includes(args.action))throw fault(400,'背景区域或操作无效')
+      if(args.revision!==service.snapshot().revision)throw fault(409,'背景已更新，请重新 inspect')
+      if(args.action!=='replace'&&args.attachmentId!==undefined)throw fault(400,'仅替换图片可以指定 attachmentId')
+      if(Object.hasOwn(args,'region')&&!validBackgroundRegion(args.region))throw fault(400,'背景保护区域无效')
+      const data={slot:args.slot,revision:args.revision}
+      if(args.action==='protect'){
+        if(!Object.hasOwn(args,'region'))throw fault(400,'请指定保护区域或 null')
+        data.region=args.region
+      }else if(args.action==='remove'){
+        if(Object.hasOwn(args,'region'))throw fault(400,'移除图片不需要保护区域')
+        data.image=null
+      }else{
+        const bytes=await readBackgroundAttachment(attachments,images,args.attachmentId,exec)
+        data.image=bytes.toString('base64')
+        if(Object.hasOwn(args,'region'))data.region=args.region
+      }
+      exec.signal?.throwIfAborted()
+      await service.save(data,exec.signal)
+      return {applied:true,...view(),previewHint:'可调用 prts_background_preview 查看当前遮罩下的日夜背景合成图；该预览不包含材质模糊和底色不透明度效果。'}
+    },
+  },{
+    name:'prts_background_configure',
+    description:'按用户要求修改当前 profile 的背景模式、遮罩和材质。material.blur 为 0..32 整数像素；material.opacity 为 0..1 底色不透明度，越高越不透明（与界面的透明度方向相反）。区域 sidebar=左侧边栏、rightSidebar=右侧边栏、rail=设置侧栏、baker=Baker 气泡、classicUser=经典用户消息。Baker 气泡仅在 deck-chat 风格、经典用户消息仅在 native 风格生效，且需要启用完整背景图片或分区正文图片；其它区域遵循当前背景模式的材质样式。配置可提前保存，不自动切换会话风格或启用图片。mode=off 默认背景（保留素材）、split 分区背景、full 完整背景；dim=0..0.9，越高越接近主题底色，图片越淡。先 inspect 获取 settings.revision，作为本工具 revision；不要使用图片 revision。只修改传入字段，冲突时重新读取，不能盲目重试。模式和遮罩同步到同一 profile 在线页面，素材在实例内共享。工具不修改主题总开关；enabled=false 时应告知用户需要启用主题。',
+    parameters:{type:'object',additionalProperties:false,properties:{
+      revision,mode:{type:'string',enum:['off','split','full']},dim:{type:'number',minimum:0,maximum:.9},material:materialSchema,
+    },required:['revision']},output,isConcurrencySafe:()=>false,
+    async execute(args,exec){
+      sessionImages(exec.agent);exec.signal?.throwIfAborted();checkRevision(args.revision)
+      const patch=args.material===undefined?{}:materialPatch(args.material)
+      if(args.mode!==undefined){if(!['off','split','full'].includes(args.mode))throw fault(400,'背景模式无效');patch.backgroundMode=args.mode}
+      if(args.dim!==undefined){if(!Number.isFinite(args.dim)||args.dim<0||args.dim>.9)throw fault(400,'遮罩 dim 必须在 0..0.9');patch.backgroundDim=args.dim}
+      if(!Object.keys(patch).length)throw fault(400,'请指定背景模式、遮罩或至少一项材质参数')
+      const current=readSettings()
+      if(!current.writable)throw fault(400,'当前宿主不支持持久化主题设置，请在设置界面调整背景和材质')
+      if(current.revision!==args.revision)throw fault(409,'主题设置已更新，请重新 inspect')
+      await host.get('settings').update(host.fiber.entry.options.id,{...patch,preferencesInitialized:true},args.revision)
+      return {applied:true,...view(),previewHint:'可调用 prts_background_preview 查看当前遮罩下的日夜背景合成图；该预览不包含材质模糊和底色不透明度效果。'}
+    },
+  }]
+}

package/src/server/backgrounds.js

@@ -8,6 +8,14 @@ import { fault } from './emblems.js'
 
 export const BACKGROUND_API = '/prts-theme-api/backgrounds'
 const BACKGROUND_SLOTS = ['full', 'sidebar', 'conversation']
+export async function prepareBackgroundImage(bytes) {
+  try {
+    const input=sharp(bytes,{limitInputPixels:40000000,animated:false})
+    const metadata=await input.metadata()
+    if(!['png','jpeg','webp','avif'].includes(metadata.format))throw Error('format')
+    return await input.rotate().resize({width:3840,height:2160,fit:'inside',withoutEnlargement:true}).webp({quality:86}).toBuffer({resolveWithObject:true})
+  }catch{throw fault(400,'无法读取图片，请使用 PNG、JPEG、WebP 或 AVIF（最多 4000 万像素）')}
+}
 export async function createBackgroundService(directory) {
   await mkdir(directory, { recursive: true, mode: 0o700 })
   const configurationPath = join(directory, 'configuration.json')
@@ -23,8 +31,9 @@ export async function createBackgroundService(directory) {
       if (!BACKGROUND_SLOTS.some(slot => state[slot]?.id === id)) throw fault(404, '背景不存在')
       return readFile(join(directory, id + '.webp'))
     },
-    save(data) {
+    save(data, signal) {
       const task = queue.then(async () => {
+        signal?.throwIfAborted()
         if (!BACKGROUND_SLOTS.includes(data?.slot)) throw fault(400, '背景区域无效')
         if (data.revision !== state.revision) throw fault(409, '背景已在其他页面更新，请重新操作')
         const regionOnly = Object.hasOwn(data, 'region') && !Object.hasOwn(data, 'image')
@@ -35,20 +44,17 @@ export async function createBackgroundService(directory) {
           if (!isBase64(data.image) || data.image.length > 14 * 1024 * 1024) throw fault(400, '请上传不超过 10 MB 的图片')
           const bytes = Buffer.from(data.image, 'base64')
           if (!bytes.length || bytes.length > 10 * 1024 * 1024) throw fault(400, '请上传不超过 10 MB 的图片')
-          try {
-            const input = sharp(bytes, { limitInputPixels: 40000000, animated: false })
-            const metadata = await input.metadata()
-            if (!['png', 'jpeg', 'webp', 'avif'].includes(metadata.format)) throw Error('format')
-            const result = await input.rotate().resize({ width: 3840, height: 2160, fit: 'inside', withoutEnlargement: true }).webp({ quality: 86 }).toBuffer({ resolveWithObject: true })
-            output = result.data
-            entry = { id: randomUUID(), width: result.info.width, height: result.info.height, region: data.region ?? null }
-          } catch { throw fault(400, '无法读取图片，请使用 PNG、JPEG、WebP 或 AVIF（最多 4000 万像素）') }
+          const result=await prepareBackgroundImage(bytes)
+          output=result.data
+          entry={id:randomUUID(),width:result.info.width,height:result.info.height,region:data.region ?? null}
         }
+        signal?.throwIfAborted()
         const next = { ...state, revision: state.revision + 1, [data.slot]: entry }
         const temporary = configurationPath + '.' + randomUUID() + '.tmp'
         try {
           if (output) await writeFile(join(directory, entry.id + '.webp'), output, { mode: 0o600 })
           await writeFile(temporary, JSON.stringify(next), { mode: 0o600 })
+          signal?.throwIfAborted()
           await rename(temporary, configurationPath)
         } catch (error) {
           if (output) await rm(join(directory, entry.id + '.webp'), { force: true }).catch(() => {})

package/src/server/theme-tool-status.js

@@ -0,0 +1,13 @@
+export const ENABLE_THEME_TOOLS = '请用户手动打开主界面左上角罗德岛徽记 → AI 工具 →「允许 AI 定制主题」。若导航栏已隐藏，先展开 P.R.T.S. 导航。'
+export const THEME_TOOL_POLICY = '涉及 PRTS 背景、头像、徽记、配置导入导出时，先检查 prts_theme_status。若工具被关闭，应先提醒用户手动开启「允许 AI 定制主题」，等待用户开启后再继续；不要自行启用开关，也不要用 shell、文件编辑、HTTP 或其他工具绕过开关修改主题配置或素材。'
+export function themeToolStatus(isEnabled){
+  return {
+    name:'prts_theme_status',
+    description:'只读查看 PRTS AI 定制工具是否开启及手动开启位置；关闭定制工具后此入口仍可用，不读取配置内容或素材。'+THEME_TOOL_POLICY,
+    parameters:{type:'object',properties:{},additionalProperties:false},
+    output:{schema:{type:'object'},render:(_args,value)=>[{type:'text',text:JSON.stringify(value)}]},
+    isConcurrencySafe:()=>true,
+    execute:async()=>({enabled:isEnabled(),nextAction:isEnabled()?'使用 PRTS 专用工具处理用户要求。':ENABLE_THEME_TOOLS,
+      policy:THEME_TOOL_POLICY,scope:'此状态入口只报告状态，不能更改开关。'}),
+  }
+}

package/src/server/tools.js

@@ -2,23 +2,28 @@ import { draftView, stateView, fault } from './emblems.js'
 
 export function sessionImages(agent) {
   if(!agent?.session)throw fault(400,'请在 DSH 会话中调用此工具')
-  const images=new Map(), calls=new Map()
+  const images=new Map(), calls=new Map();let order=0
   for(const event of agent.session.snapshotEvents()) {
     if(event.type==='tool/call')calls.set(event.data.callId,event.data.name)
     const uploaded=event.type==='user/message'
     const message=uploaded?event.data:event.type==='tool/result'?event.data.message:null
     const toolName=calls.get(message?.toolCallId ?? message?.source?.callId)
     // Preview attachments are rendered particle images, not editable source images.
-    if(!message || message.isError || toolName==='prts_emblem_preview')continue
+    if(!message || message.isError || ['prts_emblem_preview','prts_background_preview'].includes(toolName))continue
     for(const part of message.content ?? []) {
       const ref=part.attachment
       if(!ref || typeof ref.attachmentId!=='string' || !ref.attachmentId)continue
       if(part.type!=='image' && !(part.type==='file' && (/^image\/(png|jpeg|webp|gif|avif)$/.test(ref.mediaType || '') || /\.(png|jpe?g|webp|gif|avif)$/i.test(ref.name || ''))))continue
-      if(images.has(ref.attachmentId))continue
-      images.set(ref.attachmentId,{...ref,attachmentKind:part.type,origin:uploaded?'upload':'tool',...(toolName?{toolName}:{})})
+      images.set(ref.attachmentId,{...ref,attachmentKind:part.type,origin:uploaded?'upload':'tool',...(toolName?{toolName}:{}),
+        lastSeenOrder:++order,...(Number.isFinite(event.createdAt)?{lastSeenAt:new Date(event.createdAt).toISOString()}:{})})
     }
   }
-  return [...images.values()]
+  const result=[...images.values()].sort((a,b)=>b.lastSeenOrder-a.lastSeenOrder),names=new Set()
+  return result.map(image=>{
+    const latestForName=Boolean(image.name && !names.has(image.name))
+    if(image.name)names.add(image.name)
+    return {...image,latestForName}
+  })
 }
 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}]:[])]}
@@ -42,7 +47,7 @@ export function emblemTools(service,attachments) {
         const ref=images.find(e=>e.attachmentId===args.attachmentId)
         if(!ref)throw fault(404,'当前会话没有这张图片，请先上传图片或用 read_image 读取生成图，再重新读取图片列表')
         if(ref.bytes>8*1024*1024)throw fault(400,'图片超过 8 MB')
-        const {attachmentKind,origin,toolName,...attachment}=ref
+        const {attachmentKind,origin,toolName,lastSeenOrder,lastSeenAt,latestForName,...attachment}=ref
         if(attachmentKind==='file') {
           const chunks=[];let total=0
           for await(const chunk of attachments.readFileStream(attachment,exec.signal)) {