@sophiacyl/dsh-plugin-waves 0.0.0-stage → 0.1.0-beta.1

package/lib/host/aliashint.js

@@ -0,0 +1,70 @@
+// 用户话里出现鸣潮别名时, 在这一步的上下文尾部补一条对照。
+// 只给线索不下断言: 别名匹配是子串命中, 完全可能是误判, 由模型自己权衡。
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+
+const PLUGIN = 'waves-alias'
+const MAX_CHARS = 500
+
+function textOf(messages) {
+  const out = []
+  for (const message of messages || []) {
+    for (const block of message?.content || []) {
+      if (block?.type === 'text' && block.text) out.push(block.text)
+    }
+  }
+  return out.join('\n').slice(0, 2000)
+}
+
+function render(hits) {
+  const items = hits.map((h) => `${h.alias}→${h.name}(${h.kind})`).join('、')
+  return [
+    `鸣潮（Wuthering Waves）的本地别名表里有这些相近词条：${items}。`,
+    '这些是鸣潮的角色/武器/声骸/套装名，别按其他游戏的同名内容理解。',
+    '仅按字面子串匹配得到，可能与用户实际所指无关；用得上再用，别当成用户已经确认的指代。',
+  ]
+    .join('\n')
+    .slice(0, MAX_CHARS)
+}
+
+export function registerAliasHint(ctx, client) {
+  ctx.inject(['agents'], (actx) => {
+    actx.on(
+      'agent/pre-step',
+      async (payload, next) => {
+        const decision = await next()
+        if (decision.kind === 'reject' || payload.signal?.aborted) return decision
+        // 只在用户刚说完话的那一步补, 工具往返的后续步骤不重复注入
+        if (payload.step !== 1) return decision
+        const text = textOf(decision.messages)
+        if (!text) return decision
+        let hits = []
+        try {
+          const data = await client.call(
+            `/api/alias/lookup?text=${encodeURIComponent(text)}`,
+            { timeoutMs: 1500, signal: payload.signal },
+          )
+          hits = (data && data.hits) || []
+        } catch {
+          return decision
+        }
+        if (!hits.length) return decision
+        const note = render(hits)
+        return {
+          kind: 'enter',
+          messages: [
+            ...decision.messages,
+            createUserMessage({
+              content: [{ type: 'text', text: note }],
+              source: {
+                kind: PLUGIN,
+                form: 'snapshot',
+                sections: [{ name: PLUGIN, text: note }],
+              },
+            }),
+          ],
+        }
+      },
+      { prepend: true },
+    )
+  })
+}

package/lib/host/attachments.js

@@ -0,0 +1,25 @@
+// 将 DSH 已接收的附件交给鸣潮服务；读取失败直接报错，让输入框保留附件。
+export async function readAttachments(ctx, blocks, signal) {
+  const store = ctx.get('attachments')
+  const images = []
+  const files = (blocks || []).filter((block) => block.type === 'file')
+  if (files.length > 1) throw new Error('鸣潮命令一次只接受一个文件')
+  if (blocks?.length && !store) throw new Error('DSH 附件服务不可用')
+  let file
+  for (const block of blocks || []) {
+    if (block.type === 'image') {
+      const { data } = await store.readImage(block.attachment, signal)
+      images.push('base64://' + Buffer.from(data).toString('base64'))
+    } else if (block.type === 'file') {
+      const chunks = []
+      for await (const chunk of store.readFileStream(block.attachment, signal)) {
+        chunks.push(Buffer.from(chunk))
+      }
+      file = {
+        file_name: block.attachment.name,
+        file_data: Buffer.concat(chunks).toString('base64'),
+      }
+    }
+  }
+  return { images, ...file }
+}

package/lib/host/command.js

@@ -0,0 +1,34 @@
+// /ww 斜杠命令: 直接打服务, 不经过模型
+import { SLASH_USAGE } from './consts.js'
+import { resultText } from './results.js'
+
+export function parseSlashInput(rawInput) {
+  let command = String(rawInput || '').trim()
+  let scene = 'group'
+  const flag = /^(-p|--private)(\s+|$)/.exec(command)
+  if (flag) {
+    scene = 'direct'
+    command = command.slice(flag[0].length).trim()
+  }
+  return { command, scene }
+}
+
+// 斜杠命令直接打服务, 不经过模型
+export async function runSlashCommand(client, results, invocation, readAttachments = async () => ({})) {
+  const { command, scene } = parseSlashInput(invocation.rawInput)
+  if (!command) return { kind: 'error', text: SLASH_USAGE }
+  try {
+    const attachments = await readAttachments(invocation.attachments || [], invocation.signal)
+    const data = await client.call('/api/chat', {
+      method: 'POST',
+      body: { command, scene, session_id: invocation.agent?.id || 'dsh', ...attachments },
+      signal: invocation.signal,
+    })
+    if (!data?.ok) return { kind: 'error', text: data?.summary || `执行失败: ${command}` }
+    results.put(invocation.commandId, { command, scene, sessionId: invocation.agent?.id, ...data })
+    return { kind: 'success', text: resultText(command, data) }
+  } catch (e) {
+    if (invocation.signal?.aborted) return { kind: 'error', text: `已取消: ${command}` }
+    return { kind: 'error', text: `${command} 执行失败: ${String(e?.message || e)}` }
+  }
+}

package/lib/host/consts.js

@@ -0,0 +1,16 @@
+// 共享常量
+export const PKG_NAME = '@sophiacyl/dsh-plugin-waves'
+
+export const PROXY_PREFIX = '/waves-api'
+
+// 命令卡片按 commandId 回取图文段的路径; 结果带落盘, 重启后仍能还原
+export const RESULT_PATH = '/host/results/'
+// 会话是否已经真的建起来了; 闪屏上还没有会话, 命令下不去
+export const SESSION_PATH = '/host/session/'
+export const RESULT_KEEP = 200
+
+export const SLASH_USAGE = [
+  '用法: /ww <命令>',
+  '例: /ww 查询 · /ww 深塔 · /ww 椿面板 · /ww 签到 · /ww 帮助',
+  '命令不带 ww 前缀会自动补; 开头加 -p 按私聊执行（如 /ww -p 获取ck）',
+].join('\n')

package/lib/host/dataguide.js

@@ -0,0 +1,35 @@
+// 开了"AI 可使用鸣潮插件"时一并给出的数据地图。
+// 只放常驻部分: 够模型判断"要不要深挖", 细节让它按需去读 service/ai/AI_DATA.md, 省上下文也吃得到缓存
+import path from 'node:path'
+
+import { venvPython } from './service.js'
+
+export function dataGuide(serviceDir) {
+  const service = serviceDir || '.'
+  const data = path.join(service, 'data')
+  const ww = path.join(data, 'XutheringWavesUID')
+  return [
+    '',
+    '除了下命令出图，你还可以直接读本地数据、写脚本自己算（用户问"最优/怎么分配/帮我规划"这类',
+    '需要跨角色统筹的问题时就该这么做）：',
+    `- 只读库 ${path.join(service, 'tools', 'wwdata.py')}（跑脚本一律用服务自己的解释器`,
+    `  ${venvPython(service)}，系统 python 缺依赖）：`,
+    '  default_uid() / roles(uid) 角色与练度 /',
+    '  echoes(uid, sonata=) 声骸 / score(uid, 角色, 声骸) 按该角色评分模板打分 /',
+    '  cross_scores()、swap_gains() 同套装跨角色换装推演 / matrix_summary() 矩阵战绩 /',
+    '  resolve() 别名转正式名 / id2name() / char_info(角色) 图鉴文本(技能/链, 已净化标记) /',
+    '  kb(查询)、kb_get(id) 游戏常识库(库洛 wiki 全站文本: 机制/攻略/图鉴/活动)',
+    `- 玩家原始数据 ${path.join(ww, 'players')}/<特征码>/：rawData.json.gz 面板、matrixData/slashData/`,
+    '  rover.json.gz 挑战、gacha_logs.json.gz 抽卡、baseInfo.json 概览（.gz 要先解压）',
+    `- 静态资料 ${path.join(ww, 'resource', 'map')}/：CharId2Data.json 角色 id↔名、detail_json/ 角色武器声骸详情`,
+    `- 字段清单、两类统筹场景的完整做法，看 ${path.join(service, 'ai', 'AI_DATA.md')}（按需读，别整份贴）`,
+    '规矩：',
+    `- ${data} 只读，不写不删不"顺手修"。要落中间结果就用 wwdata.scratch()（系统临时目录下），`,
+    '  沙箱只放行临时目录和工作区。改用户数据只能由用户自己发命令或在设置页操作。',
+    '- sqlite 一律 file:...?mode=ro&immutable=1 只读打开，服务正在写，读写连接会损坏库。',
+    '- 数据可能过期：挑战数据看 record_time，面板看文件 mtime。旧了先用本工具跑对应命令刷新',
+    '  （面板 ww刷新面板 / 矩阵 ww矩阵 / 深塔 ww深塔 / 海墟 ww海墟 / 抽卡 ww抽卡记录 / 概览 ww查询），再读。',
+    '- 插件已有的分析别重写：伤害 ww<角色>伤害、词条优化 ww<角色>优化、练度 ww练度、排行 ww<角色>总排行。',
+    '- 想把重组/转录的声骸渲成完整面板卡给用户看，用 waves_panel 工具（只本地渲染，不上传排行）。',
+  ].join('\n')
+}

package/lib/host/imagebridge.js

@@ -0,0 +1,41 @@
+// Observe attachments for an explicitly requested Waves image operation.
+// Never change model capabilities, message content, or the decision returned by
+// the host. Text-only model admission remains the host's responsibility; users
+// can use /ww with attachments without sending images through a text model.
+const pending = new Map()
+const MAX_SESSIONS = 64
+const MAX_IMAGES = 16
+
+export function takeImages(agentId) {
+  const refs = pending.get(agentId) ?? []
+  pending.delete(agentId)
+  return refs
+}
+
+export function registerImageBridge(ctx) {
+  ctx.inject(['agents'], (actx) => {
+    actx.on('agent/pre-step', async (payload, next) => {
+      const decision = await next()
+      const agentId = payload.agent.id
+      pending.delete(agentId)
+      if (decision.kind === 'reject' || payload.signal?.aborted) return decision
+      const refs = []
+      for (const message of decision.messages || []) {
+        if (message?.role !== 'user') continue
+        if (message.source?.kind && message.source.kind !== 'user') continue
+        for (const block of message.content || []) {
+          if (block?.type === 'image' && block.attachment && refs.length < MAX_IMAGES) {
+            refs.push(block.attachment)
+          }
+        }
+      }
+      if (refs.length) {
+        if (pending.size >= MAX_SESSIONS) pending.delete(pending.keys().next().value)
+        pending.set(agentId, refs)
+      }
+      return decision
+    }, { prepend: true })
+    actx.on('agent/disposed', (payload) => pending.delete(payload?.agent?.id))
+    actx.effect(() => () => pending.clear())
+  })
+}

package/lib/host/native-result.js

@@ -0,0 +1,91 @@
+// Panel assets need a plugin owner; chat uses file-backed dsh-go/media.
+import { readFileSync, statSync, realpathSync } from 'node:fs'
+import { join, sep } from 'node:path'
+import { createHash } from 'node:crypto'
+
+const ASSETS = 'asset:'
+const FILE = /^[a-f0-9]{20}\.native\.jpg$/
+
+export function plainSummary(value) {
+  return String(value?.summary || (value?.ok ? '已执行' : '执行失败'))
+    .replace(/\[(?:图片|图文卡片)已在(?:卡片|界面)中展示\]\s*/g, '')
+    .trim() || '已执行，暂无文字摘要'
+}
+
+export function nativeResultView(value) {
+  const children = []
+  let count = 0
+  const walk = (segments, depth = 0) => {
+    if (depth > 5) return
+    for (const seg of (Array.isArray(segments) ? segments : []).slice(0, 40)) {
+      if (count >= 8) break
+      if (seg?.type === 'node') walk(seg.items, depth + 1)
+      else if (FILE.test(String(seg?.native_image || ''))) {
+        children.push({ type: 'image', src: ASSETS + seg.native_image, alt: '鸣潮图文结果' })
+        count++
+      }
+    }
+  }
+  walk(value?.segments)
+  const summary = plainSummary(value).slice(0, 1400)
+  children.push({ type: 'text', text: summary })
+  if (children.length === 1 && (value?.segments || []).some((s) => s.type === 'html' || s.type === 'image')) {
+    children.push({ type: 'callout', tone: 'info', text: '图片暂不可用，已保留文字摘要。' })
+  }
+  const view = { type: 'stack', title: '鸣潮', children }
+  return Buffer.byteLength(JSON.stringify(view)) <= 8000 ? view : {
+    type: 'stack', title: '鸣潮', children: [{ type: 'text', text: summary.slice(0, 800) }],
+  }
+}
+
+function jpegSize(bytes) {
+  if (bytes[0] !== 0xff || bytes[1] !== 0xd8) return undefined
+  for (let offset = 2; offset + 9 < bytes.length;) {
+    if (bytes[offset] !== 0xff) return undefined
+    const marker = bytes[offset + 1]
+    const length = bytes.readUInt16BE(offset + 2)
+    if (length < 2 || offset + length + 2 > bytes.length) return undefined
+    if ([0xc0, 0xc1, 0xc2].includes(marker)) return {
+      width: bytes.readUInt16BE(offset + 7), height: bytes.readUInt16BE(offset + 5),
+    }
+    offset += length + 2
+  }
+}
+
+export function resultMeta(args, value, serviceDir) {
+  const base = { segments: value?.segments ?? [], matched: value?.matched ?? [] }
+  const items = []
+  if (serviceDir) {
+    try {
+      const root = realpathSync(join(serviceDir, 'data', 'media'))
+      const walk = (segments, depth = 0) => {
+        if (depth > 5) return
+        for (const segment of (Array.isArray(segments) ? segments : []).slice(0, 40)) {
+          if (items.length >= 8) break
+          if (segment?.type === 'node') walk(segment.items, depth + 1)
+          else if (FILE.test(String(segment?.native_image || ''))) {
+            try {
+              const path = realpathSync(join(root, segment.native_image))
+              if (!path.startsWith(root + sep)) continue
+              const stat = statSync(path)
+              if (!stat.isFile() || stat.size > 1048576) continue
+              const size = jpegSize(readFileSync(path))
+              if (size) items.push({ path, mime: 'image/jpeg', ...size, bytes: stat.size })
+            } catch { /* Missing/expired images fall back to the summary. */ }
+          }
+        }
+      }
+      walk(value?.segments)
+    } catch { /* Service media directory not initialized yet. */ }
+  }
+  if (items.length) return { ...base, 'dsh-go/media': {
+    v: 1,
+    rid: 'waves_' + createHash('sha256').update(items.map((item) => item.path).join('|')).digest('hex').slice(0, 24),
+    kind: 'image', status: 'done', items,
+    request: { provider: 'waves', model: 'local-render', label: '鸣潮', n: items.length },
+    prompt: String(args?.command || (args?.char ? args.char + '面板' : '鸣潮查询')).slice(0, 200),
+  } }
+  return { ...base, 'dsh-go/view': { type: 'stack', title: '鸣潮', children: [
+    { type: 'text', text: plainSummary(value).slice(0, 1400) },
+  ] } }
+}

package/lib/host/native.js

@@ -0,0 +1,191 @@
+import { plainSummary } from './native-result.js'
+
+const text = (value) => ({ type: 'text', text: String(value).slice(0, 1800) })
+const action = (label, id, args) => ({ label, action: args ? { id, args } : id })
+const canV2 = (caps) => caps?.components?.includes('form')
+const keyOf = (scope) => scope.sessionId || 'global'
+const editData = (item) => ({ form: { value: item.secret || item.upload && !item.upload.with_text ? '' :
+  item.type === 'DictConfig' ? JSON.stringify(item.value) : item.type.includes('List') ? (item.value || []).join(',') : item.value }, notice: '' })
+const pending = (label, work) => ({ pending: { label, timeoutMs: 60000 }, result: async (signal) => {
+  try { return await work(signal) } catch { return { toast: '操作失败，请稍后重试' } }
+} })
+
+export function registerNative(ctx, client, results) {
+  ctx.inject(['dshGo'], (nctx) => {
+    // Keep only navigation identifiers, never secrets or user input. Bound memory.
+    const states = new Map()
+    const state = (scope) => {
+      const key = keyOf(scope)
+      if (!states.has(key)) {
+        if (states.size >= 64) states.delete(states.keys().next().value)
+        states.set(key, { group: 0, page: 0 })
+      }
+      return states.get(key)
+    }
+    const config = () => client.call('/api/config', { timeoutMs: 1800 })
+    const selected = async (scope) => {
+      const groups = (await config()).groups || []
+      const s = state(scope)
+      const group = groups.find((g) => g.name === s.editGroup)
+      const item = group?.items?.find((i) => i.key === s.editKey)
+      if (!item) throw Error('配置项不存在')
+      return { group, item }
+    }
+    const latest = (scope) => results.latest(scope.sessionId)
+    const resultPatch = (scope) => {
+      const value = latest(scope)
+      const images = []
+      const collect = (segments, depth = 0) => {
+        if (depth > 5) return
+        for (const seg of (segments || []).slice(0, 40)) {
+          if (seg?.type === 'node') collect(seg.items, depth + 1)
+          else if (/^[a-f0-9]{20}\.native\.jpg$/.test(seg?.native_image || '') && images.length < 8) {
+            images.push({ src: 'asset:' + seg.native_image, alt: '鸣潮结果' })
+          }
+        }
+      }
+      collect(value?.segments)
+      return { summary: value ? plainSummary(value).slice(0, 1800) : '暂无查询结果。可输入命令，或发送 /ww 查询。', images, form: { command: '' } }
+    }
+    const run = (scope, command) => pending('正在查询鸣潮', async (signal) => {
+      if (typeof command !== 'string' || !command.trim() || command.length > 500) return { toast: '请输入 1—500 字的命令' }
+      const value = await client.call('/api/chat', { method: 'POST', body: {
+        command: command.trim(), session_id: scope.sessionId || 'dsh', native: true,
+      }, signal, timeoutMs: 55000 })
+      results.put(`native:${keyOf(scope)}`, { ...value, command, sessionId: scope.sessionId })
+      return { patch: resultPatch(scope), toast: value.ok ? '查询完成' : '命令未完成，请查看结果' }
+    })
+
+    nctx.dshGo.panel('waves-home', {
+      view: (_scope, caps) => {
+        if (!canV2(caps)) return { type: 'stack', children: [text('请在对话中发送 /ww 查询；完整原生面板需要支持视图 v2 的 App。'),
+          { type: 'text', text: { $: 'data.summary' } }] }
+        return { v: 2, type: 'stack', children: [
+          { type: 'form', submit: 'query', submitLabel: '执行命令', children: [
+            { type: 'textField', label: '鸣潮命令', placeholder: '查询、体力、椿面板、帮助', bind: 'data.form.command', required: true, maxLength: 500 },
+          ] },
+          { type: 'actions', items: [action('帮助', 'help'), action('刷新结果', 'latest'), action('设置', 'settings')] },
+          { type: 'gallery', items: { $: 'data.images' }, columns: 2 },
+          { type: 'text', text: { $: 'data.summary' } },
+        ] }
+      },
+      data: (scope, emit) => { emit(resultPatch(scope)); return () => {} },
+      actions: {
+        query: (scope, event) => run(scope, event.value?.values?.['data.form.command']),
+        help: (scope) => run(scope, 'ww帮助'),
+        latest: (scope) => ({ patch: resultPatch(scope) }),
+        settings: () => ({ open: 'panel:waves-settings' }),
+      },
+    })
+
+    nctx.dshGo.panel('waves-settings', {
+      view: async (scope, caps) => {
+        if (!canV2(caps)) return { type: 'stack', children: [text('原生设置需要支持视图 v2 的 App。')] }
+        try {
+          const groups = (await config()).groups || []
+          const s = state(scope)
+          s.group = Math.max(0, Math.min(s.group, groups.length - 1))
+          const group = groups[s.group]
+          const items = group?.items || []
+          s.page = Math.max(0, Math.min(s.page, Math.ceil(items.length / 12) - 1))
+          return { v: 2, type: 'stack', children: [
+            text(`${group?.name || '配置'} · ${s.page + 1}/${Math.max(1, Math.ceil(items.length / 12))}`),
+            { type: 'actions', items: [action('上一组', 'group', { delta: -1 }), action('下一组', 'group', { delta: 1 }), action('刷新', 'reload')] },
+            { type: 'list', items: items.slice(s.page * 12, s.page * 12 + 12).map((item) => ({
+              title: String(item.title || item.key).slice(0, 80),
+              subtitle: item.secret ? (item.is_set ? '已设置，点按可从文件更新' : '未设置，点按可从文件导入') : String(typeof item.value === 'object' ? JSON.stringify(item.value) : item.value).slice(0, 120),
+              action: { id: 'edit', args: { group: group.name, key: item.key } },
+            })) },
+            { type: 'actions', items: [action('上一页', 'page', { delta: -1 }), action('下一页', 'page', { delta: 1 }), action('返回查询', 'home')] },
+          ] }
+        } catch { return { type: 'stack', children: [text('服务尚未就绪，请稍后重试。'), { type: 'actions', items: [action('重试', 'reload')] }] } }
+      },
+      actions: {
+        group: (scope, event) => { const s = state(scope); s.group = Math.max(0, s.group + (event.value?.delta === -1 ? -1 : 1)); s.page = 0; return { refresh: true } },
+        page: (scope, event) => { const s = state(scope); s.page = Math.max(0, s.page + (event.value?.delta === -1 ? -1 : 1)); return { refresh: true } },
+        reload: () => ({ refresh: true }),
+        home: () => ({ open: 'panel:waves-home' }),
+        edit: async (scope, event) => {
+          const groups = (await config()).groups || []
+          const group = groups.find((g) => g.name === event.value?.group)
+          const item = group?.items?.find((i) => i.key === event.value?.key)
+          if (!item) return { toast: '配置项不存在' }
+          Object.assign(state(scope), { editGroup: group.name, editKey: event.value.key })
+          // The bridge retains panel feeds for 30s. Reset a reused editor feed
+          // before opening the next setting, so an old draft is never reused.
+          return [{ type: 'patch', id: 'waves-edit', data: editData(item) }, { open: 'panel:waves-edit' }]
+        },
+      },
+    })
+
+    nctx.dshGo.panel('waves-edit', {
+      view: async (scope, caps) => {
+        if (!canV2(caps)) return { type: 'stack', children: [text('此设置需要支持视图 v2 的 App。')] }
+        try {
+          const { item } = await selected(scope)
+          const children = [text(item.title || item.key), text(item.desc || '修改后点保存。')]
+          if (item.needs_restart) children.push({ type: 'callout', tone: 'info', text: '修改此项后需要重启引擎或鸣潮服务。' })
+          if (item.secret) {
+            children.push(text(item.is_set ? '已设置，原值不会显示。' : '尚未设置。'))
+            children.push(text('将此项值单独保存为 UTF-8 文本文件，点下面按钮导入；内容不会出现在对话或面板中。'))
+            children.push({ type: 'actions', items: [action('从文件更新', 'pick'), action('返回设置', 'back')] })
+          } else if (item.upload && !item.upload.with_text) {
+            children.push(text(item.upload.exists ? '已有文件，可选择新文件替换。' : '尚未上传文件。'))
+            children.push({ type: 'actions', items: [action('选择文件', 'pick'), action('返回设置', 'back')] })
+          } else {
+            const type = item.type === 'BoolConfig' ? 'toggle' : ['IntConfig', 'FloatConfig'].includes(item.type) ? 'number' : item.options?.length ? 'select' : 'textField'
+            const input = { type, label: '新值', bind: 'data.form.value' }
+            if (type === 'select') input.options = item.options.slice(0, 24).map(String)
+            if (type === 'textField') Object.assign(input, { maxLength: 1000, multiline: item.type.includes('List') || item.type === 'DictConfig', maxLines: 4 })
+            children.push({ type: 'form', submit: 'save', submitLabel: '保存', children: [input] })
+            children.push({ type: 'actions', items: [action('返回设置', 'back')] })
+          }
+          children.push({ type: 'text', text: { $: 'data.notice' } })
+          return { v: 2, type: 'stack', children }
+        } catch { return { type: 'stack', children: [text('请先从设置列表选择一项。'), { type: 'actions', items: [action('返回设置', 'back')] }] } }
+      },
+      data: (scope, emit) => {
+        let active = true
+        selected(scope).then(({ item }) => {
+          if (!active) return
+          emit(editData(item))
+        }).catch(() => { if (active) emit({ form: { value: '' } }) })
+        return () => { active = false }
+      },
+      actions: {
+        back: () => ({ open: 'panel:waves-settings' }),
+        save: (scope, event) => pending('正在保存', async (signal) => {
+          const { group, item } = await selected(scope)
+          if (item.secret || item.upload && !item.upload.with_text) return { toast: '请使用文件导入' }
+          const value = event.value?.values?.['data.form.value']
+          if (value === undefined || value === null || JSON.stringify(value).length > 2000) return { toast: '请填写有效值' }
+          if (item.type === 'BoolConfig' && typeof value !== 'boolean') return { toast: '请填写开关值' }
+          if (['IntConfig', 'FloatConfig'].includes(item.type) && (typeof value !== 'number' || !Number.isFinite(value) || item.type === 'IntConfig' && !Number.isInteger(value))) return { toast: '请填写有效数字' }
+          if (item.options && !item.options.map(String).includes(String(value))) return { toast: '请选择列表中的值' }
+          const result = await client.call('/api/config', { method: 'POST', body: { group: group.name, key: item.key, value }, signal, timeoutMs: 5000 })
+          return { patch: { form: { value } }, toast: result.needs_restart ? '已保存，重启后生效' : '已保存' }
+        }),
+        pick: () => ({ type: 'pickFile', action: 'import-file', maxFiles: 1 }),
+        'import-file': async (scope, event) => {
+          try {
+          if (event.value?.status !== 'selected') return { patch: { notice: '已取消' } }
+          const file = event.value.files?.[0]
+          if (!file || typeof nctx.dshGo.readPickedFile !== 'function') return { patch: { notice: '无法读取文件' } }
+          // Read while the callback lease is active; never return the contents.
+          const bytes = nctx.dshGo.readPickedFile(file.handle)
+          const { group, item } = await selected(scope)
+          if (item.secret) {
+            if (bytes.length > 16000) return { patch: { notice: '凭据文件过大' } }
+            const value = bytes.toString('utf8').trim()
+            if (!value || value.length > 8000) return { patch: { notice: '凭据文件无效' } }
+            await client.call('/api/config', { method: 'POST', body: { group: group.name, key: item.key, value }, timeoutMs: 1800 })
+          } else if (item.upload) {
+            await client.call('/api/config/upload', { method: 'POST', body: { group: group.name, key: item.key, data: bytes.toString('base64') }, timeoutMs: 1800 })
+          } else return { patch: { notice: '此项不支持文件导入' } }
+          return { patch: { notice: '已保存，原值不会显示', form: { value: '' } } }
+          } catch { return { patch: { notice: '导入失败，请检查文件后重试' } } }
+        },
+      },
+    })
+  })
+}

package/lib/host/proxy.js

@@ -0,0 +1,59 @@
+// /waves-api 反代与命令结果回取
+import { PROXY_PREFIX, RESULT_PATH, SESSION_PATH } from './consts.js'
+
+export function registerProxy(ctx, client, results) {
+  // 会话查在这个作用域里拿, 拿不到就当查不了, 由前端按"能下命令"处理
+  let sessions = null
+  ctx.inject(['sessions'], (sctx) => {
+    sessions = sctx.sessions
+    sctx.effect(() => () => {
+      sessions = null
+    })
+  })
+
+  ctx.inject(['webServer'], (wctx) => {
+    wctx.effect(() =>
+      wctx.webServer.register({
+        kind: 'prefix',
+        path: PROXY_PREFIX,
+        handler: async (req, res) => {
+          const rest = req.url.slice(PROXY_PREFIX.length)
+          if (rest.startsWith(SESSION_PATH)) {
+            const id = decodeURIComponent(rest.slice(SESSION_PATH.length).split('?')[0])
+            const alive = sessions ? sessions.get(id) !== undefined : null
+            res.writeHead(200, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({ alive }))
+            return
+          }
+          if (rest.startsWith(RESULT_PATH)) {
+            const id = decodeURIComponent(rest.slice(RESULT_PATH.length).split('?')[0])
+            const found = results.get(id)
+            res.writeHead(found ? 200 : 404, { 'content-type': 'application/json' })
+            res.end(JSON.stringify(found || { error: '结果已过期' }))
+            return
+          }
+          const target = client.base + rest
+          try {
+            const chunks = []
+            for await (const chunk of req) chunks.push(chunk)
+            const upstream = await fetch(target, {
+              method: req.method,
+              headers: req.headers['content-type']
+                ? { 'content-type': req.headers['content-type'] }
+                : undefined,
+              body: chunks.length ? Buffer.concat(chunks) : undefined,
+            })
+            const buf = Buffer.from(await upstream.arrayBuffer())
+            res.writeHead(upstream.status, {
+              'content-type': upstream.headers.get('content-type') || 'application/octet-stream',
+            })
+            res.end(buf)
+          } catch (e) {
+            res.writeHead(502, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({ error: String(e?.message || e) }))
+          }
+        },
+      }),
+    )
+  })
+}

package/lib/host/results.js

@@ -0,0 +1,67 @@
+// 命令结果暂存与文本化
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { PROXY_PREFIX, RESULT_KEEP } from './consts.js'
+import { plainSummary } from './native-result.js'
+
+// 结果落盘: 重启后历史卡片还能还原成图文, 不至于退化成一段裸链接
+export function makeResultStore(serviceDir) {
+  const file = serviceDir ? path.join(serviceDir, 'data', 'command_results.json') : ''
+  const items = new Map()
+  let timer = null
+
+  if (file && fs.existsSync(file)) {
+    try {
+      for (const [id, value] of Object.entries(JSON.parse(fs.readFileSync(file, 'utf8')))) {
+        items.set(id, value)
+      }
+    } catch {
+      // 存档坏了就当没有, 下次写入会覆盖
+    }
+  }
+
+  const flush = () => {
+    timer = null
+    if (!file) return
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true })
+      fs.writeFileSync(file, JSON.stringify(Object.fromEntries(items)))
+    } catch {
+      // 落盘失败不影响本次会话
+    }
+  }
+
+  return {
+    put(id, value) {
+      // Updating a session's native result must also advance recency.
+      items.delete(String(id))
+      items.set(String(id), value)
+      while (items.size > RESULT_KEEP) items.delete(items.keys().next().value)
+      if (file && !timer) timer = setTimeout(flush, 400)
+    },
+    get(id) {
+      return items.get(String(id))
+    },
+    latest(sessionId) {
+      return [...items.values()].reverse().find((value) => value.sessionId === sessionId)
+    },
+  }
+}
+
+export function collectLinks(segments, out = []) {
+  for (const seg of segments || []) {
+    if (!seg) continue
+    if (seg.type === 'node') collectLinks(seg.items, out)
+    else if (seg.type === 'image' || seg.type === 'html' || seg.type === 'file') {
+      const url = String(seg.url || '')
+      if (url) out.push(url.startsWith('/api/') ? PROXY_PREFIX + url : url)
+    }
+  }
+  return out
+}
+
+// Native clients do not run the Web command renderer. Always retain the digest.
+export function resultText(command, data) {
+  return `${command} · ${plainSummary(data).slice(0, 6000)}`
+}