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

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)) {

package/src/server/transfer-tools.js

@@ -0,0 +1,166 @@
+import { randomUUID, createHash } from 'node:crypto'
+import { createThemeTransfer, validateThemePackage, ignoredThemePackageFields, describeThemePackage, mergeThemePreferences, THEME_PACKAGE_LIMIT } from '../client/theme-transfer.js'
+import { normalizePreferences } from '../client/preferences.js'
+import { draftView, fault } from './emblems.js'
+
+function sessionFiles(agent){
+  if(!agent?.session)throw fault(400,'请在 DSH 会话中调用此工具')
+  const refs=new Map()
+  for(const event of agent.session.snapshotEvents()){
+    const message=event.type==='user/message'?event.data:event.type==='tool/result'?event.data.message:null
+    if(!message || message.isError)continue
+    for(const part of message.content ?? []){
+      if(part.type==='file' && typeof part.attachment?.attachmentId==='string')refs.set(part.attachment.attachmentId,part.attachment)
+    }
+  }
+  return [...refs.values()]
+}
+export function transferTools({backgrounds,avatars,emblems,attachments,host,themeVersion}){
+  const services={backgrounds,avatars,emblems},previews=new Map()
+  let busy=false
+  const settings=()=>{
+    const service=host.get?.('settings'),ns=host.fiber?.entry?.options?.id
+    const descriptor=service?.describe({redactSecrets:true}).find(value=>value.ns===ns)
+    if(!descriptor)throw fault(400,'当前宿主无法读取主题配置')
+    return {service,ns,...descriptor}
+  }
+  const revisions=assets=>({settings:settings().revision,...(assets?Object.fromEntries(Object.entries(services).map(([key,value])=>[key,value.snapshot().revision])):{})})
+  const verify=expected=>{
+    const current=revisions(Object.hasOwn(expected,'backgrounds'))
+    if(Object.keys(expected).some(key=>current[key]!==expected[key]))throw fault(409,'主题或素材已变化，请重新预检导入文件')
+  }
+  const saveFile=async(value,label,signal)=>{
+    signal?.throwIfAborted()
+    const data=Buffer.from(JSON.stringify(value))
+    if(data.length>THEME_PACKAGE_LIMIT)throw fault(400,'主题文件超过 160 MB')
+    const name=`prts-${label}-${new Date().toISOString().replace(/[:.]/g,'-')}.prts-theme.json`
+    const file=await attachments.saveFile({data,name})
+    return file
+  }
+  const read=async(ref,signal)=>{
+    if(ref.bytes>THEME_PACKAGE_LIMIT)throw fault(400,'主题文件超过 160 MB')
+    let size=0;const chunks=[]
+    for await(const chunk of attachments.readFileStream(ref,signal)){
+      signal?.throwIfAborted();size+=chunk.length
+      if(size>THEME_PACKAGE_LIMIT)throw fault(400,'主题文件超过 160 MB')
+      chunks.push(chunk)
+    }
+    signal?.throwIfAborted()
+    const data=Buffer.concat(chunks)
+    let value
+    try{value=JSON.parse(data.toString('utf8').replace(/^\uFEFF/,''))}catch{throw fault(400,'无法解析主题 JSON 文件')}
+    validateThemePackage(value)
+    return {value,hash:createHash('sha256').update(data).digest('hex')}
+  }
+  const bridge=(expected,onDownload)=>{
+    const request=async(path,options={})=>{
+      options.signal?.throwIfAborted()
+      const route=path.replace('/prts-theme-api/','')
+      const [kind,...parts]=route.split('/'),service=services[kind],tail=parts.join('/')
+      if(!service)throw Error('未知素材服务')
+      const data=options.body===undefined?undefined:JSON.parse(options.body)
+      let value
+      if(tail==='configuration'){
+        if(data===undefined){
+          value=service.snapshot()
+          if(expected && expected[kind]!==undefined && expected[kind]!==value.revision)throw fault(409,'素材已变化，请重新预检')
+        }else value=kind==='emblems'?await service.save(data.configuration,data.revision):await service.save(data)
+      }else if(kind==='backgrounds' && tail.startsWith('image/')){
+        return new Response(await backgrounds.image(parts[1]),{headers:{'content-type':'image/webp'}})
+      }else if(kind==='avatars' && tail.startsWith('edit/'))value=avatars.edit(parts[1])
+      else if(kind==='emblems' && tail==='import')value=draftView(await emblems.importAsset(data,options.signal))
+      else if(kind==='emblems' && parts[0]==='draft' && parts[2]==='export')value=await emblems.exportAsset(decodeURIComponent(parts[1]))
+      else throw Error('未知素材操作')
+      return {ok:true,json:async()=>value}
+    }
+    return createThemeTransfer({
+      window:{fetch:request,setTimeout,Blob},themeVersion,onDownload,
+      readImage:async(blob,signal)=>{signal?.throwIfAborted();return Buffer.from(await blob.arrayBuffer()).toString('base64')},
+      getPreferences:()=>normalizePreferences(settings().value),
+      checkExport:()=>settings().revision,
+      checkWritable:()=>{
+        const state=settings()
+        if(!state.service.writable)throw fault(400,'当前宿主无法持久化主题配置')
+        if(expected)verify(expected)
+        return state.revision
+      },
+      savePreferences:async(value,revision)=>{
+        const state=settings()
+        await state.service.update(state.ns,{...value,preferencesInitialized:true},revision)
+      },
+      backupNotice:'导入前备份已保存为附件，可重新导入恢复。',
+    })
+  }
+  const exclusive=async fn=>{
+    if(busy)throw fault(409,'正在处理主题文件，请稍候')
+    busy=true
+    try{return await fn()}finally{busy=false}
+  }
+  const prune=()=>{for(const [id,preview] of previews)if(preview.expires<Date.now())previews.delete(id)}
+  const output={schema:{type:'object'},render:(_args,value)=>[
+    {type:'text',text:JSON.stringify(value)},
+    ...[value.file,value.backup].filter(ref=>ref && typeof ref==='object' && typeof ref.attachmentId==='string' && typeof ref.name==='string' && Number.isFinite(ref.bytes)).map(attachment=>({type:'file',attachment})),
+  ]}
+  return [{
+    name:'prts_theme_export',
+    description:'按用户要求导出当前 PRTS 主题为可下载的 .prts-theme.json 文件附件，和设置界面导出格式一致。includeAssets 默认为 true，含背景、保护区域、用户/AI 头像原图与裁剪、徽记原图及排列；false 仅导出设置。不会修改主题。不包含会话或凭据。最大 160 MB，素材或配置在导出期间变化会拒绝不一致结果。',
+    parameters:{type:'object',additionalProperties:false,properties:{includeAssets:{type:'boolean'}}},output,isConcurrencySafe:()=>false,
+    execute:(args,exec)=>exclusive(async()=>{
+      sessionFiles(exec.agent)
+      if(args.includeAssets!==undefined && typeof args.includeAssets!=='boolean')throw fault(400,'includeAssets 必须是布尔值')
+      const value=await bridge().export(args.includeAssets!==false,undefined,exec.signal)
+      const file=await saveFile(value,'theme',exec.signal)
+      return {exported:true,summary:describeThemePackage(value),file}
+    }),
+  },{
+    name:'prts_theme_import_preview',
+    description:'只预检 PRTS 主题文件，不修改主题。未传 attachmentId 时列出当前会话上传或工具返回的 JSON 文件；指定后验证文件并返回 previewId、摘要、将忽略的字段和设置变化。支持本工具导出的文件，也支持上传或由会话文件工具返回的文件附件；不接受任意路径/URL。请向用户说明覆盖范围及 ignoredFields；得到导入授权后才调用 import。预检有效期 15 分钟，仅限当前会话，配置或素材变化后需重新预检。',
+    parameters:{type:'object',additionalProperties:false,properties:{attachmentId:{type:'string'}}},output,isConcurrencySafe:()=>false,
+    execute:(args,exec)=>exclusive(async()=>{
+      const files=sessionFiles(exec.agent);exec.signal?.throwIfAborted();prune()
+      if(!args.attachmentId)return {files:files.filter(ref=>/\.json$/i.test(ref.name || '') || /json/.test(ref.mediaType || ''))}
+      const ref=files.find(file=>file.attachmentId===args.attachmentId)
+      if(!ref)throw fault(404,'当前会话没有此文件，请先上传或通过会话工具返回文件附件')
+      const {value,hash}=await read(ref,exec.signal),expected=revisions(Boolean(value.assets))
+      const current=normalizePreferences(settings().value),next=mergeThemePreferences(current,value.preferences)
+      const previewId=randomUUID(),expires=Date.now()+15*60*1000
+      while(previews.size>=20)previews.delete(previews.keys().next().value)
+      previews.set(previewId,{ref,hash,expected,session:exec.agent.session,expires})
+      return {previewId,expiresAt:new Date(expires).toISOString(),summary:describeThemePackage(value),
+        ignoredFields:ignoredThemePackageFields(value),
+        changes:Object.entries(next).filter(([key,val])=>val!==current[key]).map(([key,after])=>({key,before:current[key],after})),
+        scope:'设置影响当前 profile；完整文件中的素材替换影响同一 DSH 实例。仅配置文件保留现有素材。',
+        backupNotice:'导入前会先保存备份附件；失败时尝试回退已确认写入的素材。',
+        effects:value.assets?[
+          '替换或移除背景会删除旧 WebP 文件；备份附件保留恢复所需数据。',
+          '替换或移除头像不保留旧原图；备份附件包含原图和裁剪参数。',
+          '每个自定义徽记会生成新的草稿和预览；相同原图按内容哈希复用。',
+          '草稿达到约 200 份时，按创建时间清理较旧且未受保护的草稿；正在应用的徽记受保护。反复完整导入会增加草稿。',
+        ]:['仅修改设置，保留当前素材。'],
+      }
+    }),
+  },{
+    name:'prts_theme_import',
+    description:'用户授权后，使用当前会话的 previewId 导入已预检的主题文件。完整文件替换背景、头像、徽记及排列，空素材恢复默认；仅设置文件保留现有素材。替换/移除背景会删除旧 WebP，头像旧原图也不会保留。每个自定义徽记会新增草稿和预览，相同原图按内容哈希复用；草稿达到约 200 份时清理较旧且未受保护的草稿，正在应用的徽记受保护。导入前先保存备份附件，失败或取消时尝试回退素材。配置/素材版本变化、预检过期、文件内容变化会拒绝执行，需要重新预检。返回 applied=false 时必须报告错误和备份，不能宣称成功；部分回退失败时应核对实际状态。导入可能关闭 AI 工具或主题总开关，预检时应告知相应变化。',
+    parameters:{type:'object',additionalProperties:false,properties:{previewId:{type:'string'}},required:['previewId']},output,isConcurrencySafe:()=>false,
+    execute:(args,exec)=>exclusive(async()=>{
+      sessionFiles(exec.agent);exec.signal?.throwIfAborted();prune()
+      const preview=previews.get(args.previewId)
+      if(!preview || preview.session!==exec.agent.session)throw fault(404,'预检不存在或已过期，请在当前会话重新预检')
+      verify(preview.expected)
+      const {value,hash}=await read(preview.ref,exec.signal)
+      if(hash!==preview.hash)throw fault(409,'文件内容已变化，请重新预检')
+      verify(preview.expected)
+      previews.delete(args.previewId)
+      let backup
+      const transfer=bridge(preview.expected,async data=>{backup=await saveFile(data,'before-import',exec.signal)})
+      try{
+        await transfer.import(value,undefined,exec.signal)
+        return {applied:true,summary:describeThemePackage(value),backup}
+      }catch(error){
+        if(!backup)throw error
+        return {applied:false,error:error.message,backup}
+      }
+    }),
+  }]
+}

package/src/styles/cursor.css

@@ -1,10 +1,12 @@
 /* Native cursor; gesture frames override the resting image without a DOM overlay. */
 @media (any-pointer: fine) {
   html[data-dsh-prts][data-prts-cursor="prts"] {
-    --prts-hand-cursor: var(--prts-hand-frame, url("__PRTS_HAND__") 7 6);
+    --prts-rest-hand-cursor: url("__PRTS_HAND__") 7 6;
+    --prts-hand-cursor: var(--prts-hand-frame, var(--prts-rest-hand-cursor));
     --prts-text-cursor: var(--prts-text-frame, url("__PRTS_TEXT__") 24 24);
     --prts-sort-cursor: url("__PRTS_GRABBING__") 22 19, grabbing;
-    --prts-link-cursor: url("__PRTS_LINK__") 7 7;
+    --prts-rest-link-cursor: url("__PRTS_LINK__") 7 7;
+    --prts-link-cursor: var(--prts-rest-link-cursor);
     cursor: var(--prts-hand-cursor), default;
   }
   html[data-dsh-prts][data-prts-cursor="prts"] :is(button, a[href], summary, [role="button"], [role="tab"], [role="treeitem"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [data-prts-workspace-row], [data-prts-session-row], .dsh-partner-sidebar-row, select, input[type="button"], input[type="submit"], input[type="checkbox"], input[type="radio"], input[type="color"], input[type="range"]) {
@@ -41,3 +43,25 @@ html[data-dsh-prts] [data-prts-region-stage] [data-prts-region-handle] { cursor:
 html[data-dsh-prts] [data-prts-region-stage] :is([data-prts-region-handle="e"],[data-prts-region-handle="w"]) { cursor:ew-resize!important; }
 html[data-dsh-prts] [data-prts-region-stage] :is([data-prts-region-handle="nw"],[data-prts-region-handle="se"]) { cursor:nwse-resize!important; }
 html[data-dsh-prts] [data-prts-region-stage] :is([data-prts-region-handle="ne"],[data-prts-region-handle="sw"]) { cursor:nesw-resize!important; }
+
+/* A single renderer owns every in-page cursor state. State classification
+   reads mirrored cursor metadata, so hiding never needs to be toggled to read. */
+html[data-dsh-prts][data-prts-follower-visible],
+html[data-dsh-prts][data-prts-follower-visible] :is(*,#prts-cursor-layer-specificity) {
+  cursor:none!important;
+}
+.prts-cursor-follower {
+  position:fixed;top:0;left:0;width:1px;height:1px;z-index:2147483647;
+  pointer-events:none!important;user-select:none;contain:layout style;
+  margin:0;padding:0;border:0;background:transparent;overflow:visible;right:auto;bottom:auto;
+}
+.prts-cursor-follower[hidden] { display:none!important; }
+.prts-cursor-follower * { pointer-events:none!important; }
+.prts-cursor-follower img { position:absolute;max-width:none!important;max-height:none!important; }
+
+/* Known DSH horizontal resize boundaries must have their native image before
+   pointer events fire, including the chat width handle and its hit children. */
+html[data-dsh-prts][data-prts-cursor="prts"] :is([class$="_widthHandle"],[class$="_detailsResizeHandle"],.dsh-ssh-workbench-resizer),
+html[data-dsh-prts][data-prts-cursor="prts"] :is([class$="_widthHandle"],[class$="_detailsResizeHandle"],.dsh-ssh-workbench-resizer) * {
+  cursor: url("__PRTS_RESIZE_EW__") 16 16, col-resize;
+}

package/src/styles/refinement.css

@@ -520,7 +520,7 @@ html[data-dsh-prts] :is([data-chat-flow-kind],[data-message-role],[data-submissi
   }
   &:active{transform:none}
 }
-html[data-dsh-prts] [data-prts-body-target-frame] {
+html[data-dsh-prts] :is([data-prts-body-target-frame],[data-prts-body-target-ghost]) {
   position:fixed;inset:auto;left:0;top:0;width:0;height:0;margin:0;padding:0;border:0;background:transparent;overflow:visible;z-index:100;pointer-events:none;opacity:0;--prts-corner-width:1px;
   & > i {
     position:absolute;left:0;top:0;width:7px;height:7px;will-change:transform;