scrum-skills 0.3.2 → 0.3.3

package/docs/ai-assistant-guide.md

@@ -1,1008 +1,1008 @@
-# 基于 Nuxt UI 的 AI 助手前端开发指南
-
-这份文档只讲**前端**：模型设置的界面与状态、基本对话、消息历史、图片上传、消息策略在浏览器侧落地的方式，以及关键代码。服务端（读配置、拼 system prompt、转发模型、跑工具）视为已存在的黑盒，只约定接口契约。
-
-技术基线（本项目实测可用）：Nuxt 4 + `@nuxt/ui` 4 + `@comark/nuxt` 0.7。页面是 SPA（`ssr: false`），所有状态留在浏览器。
-
----
-
-## 1. 前端只做三件事
-
-```
-┌───────────────────────────── 浏览器 ─────────────────────────────┐
-│ AiAssistant.vue        悬浮球 + 抽屉 + 设置页 / 对话页切换        │
-│   ├─ 设置面板          UInput / UTextarea / USwitch / 预设 chips  │
-│   ├─ 对话区            UChatMessages + part 分发器                │
-│   └─ 输入区            UChatPrompt + 图片 / 新建 / 历史 / 策略     │
-│ use-ai.ts              消息、状态机、SSE 解析、localStorage        │
-└──────────────────────────────────────────────────────────────────┘
-              │ GET/POST /api/ai/config      POST /api/ai/chat (SSE)
-              ▼
-        服务端（黑盒，Key 与模型地址都在那边）
-```
-
-前端的三条职责边界，越界就会出问题：
-
-1. **不碰 Key**。只读 `hasKey`，写配置时把用户输入原样交给服务端。
-2. **不自己算上下文**。裁剪是服务端的事，前端只负责把历史整理成「文字 + 最近几张图」的合法结构。
-3. **只改 `messages.value` 里的元素**。任何攒起来准备后改的对象都会绕过响应式代理，表现为「流式回答一个字都不刷新」。
-
----
-
-## 2. 目录与依赖
-
-```
-app/
-  components/AiAssistant.vue          抽屉 + 悬浮球 + 设置面板 + 对话区
-  components/chat/
-    ChatComark.ts                     markdown 流式渲染（defineMarkdownComponent）
-    MessageContent.vue                part 分发器（text/reasoning/tool/image/review）
-    ReasoningBlock.vue                思考折叠块
-  composables/use-ai.ts               状态、流式解析、会话历史
-  assets/css/main.css                 .ai-* 样式（抽屉骨架、消息、输入区）
-```
-
-```jsonc
-// package.json
-{
-  "dependencies": {
-    "@comark/nuxt": "^0.7.0",
-    "@nuxt/ui": "^4.12.0",
-    "nuxt": "^4.6.2"
-  },
-  "devDependencies": { "@iconify-json/lucide": "^1.2.147" }
-}
-```
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@nuxt/ui', '@comark/nuxt'],
-  ssr: false,                                  // 单机工具，不需要 SEO，省掉一半水合问题
-  css: ['~/assets/css/main.css'],              // 先 @import "tailwindcss"; 再 @import "@nuxt/ui";
-  ui: { colorMode: false, fonts: false },       // 不用暗色/在线字体就关掉，避免白屏等字体
-})
-```
-
-`app.vue` 最外层必须是 `<UApp>`，否则 `UPopover` / `UDropdownMenu` 的浮层与 Toast 都不工作：
-
-```vue
-<template>
-  <UApp>
-    <NuxtPage />
-    <AiAssistant />   <!-- 挂在外壳上，所有页面都能叫出来 -->
-  </UApp>
-</template>
-```
-
----
-
-## 3. 与后端的数据契约
-
-前端只需要照这个形状读写，不用关心服务端怎么实现。
-
-### 3.1 消息与 part
-
-```ts
-export type AiPart =
-  | { type: 'text'; text: string }
-  // startedAt/durationSec 用来算「思考了 N 秒」：第一段思考 → 第一段正文之间的耗时
-  | { type: 'reasoning'; text: string; startedAt?: number; durationSec?: number }
-  | { type: 'tool'; toolCallId: string; toolName: string; state: 'running' | 'done' | 'error'; args?: unknown; output?: string }
-  | { type: 'image'; id: string; url: string; name?: string }
-  | { type: 'review'; pendingId: string; state: 'pending' | 'applied' | 'rejected' | 'error'; /* 业务字段 */ }
-
-export interface AiMessage { id: string; role: 'user' | 'assistant'; parts: AiPart[] }
-```
-
-为什么不用 `content: string`：一条回答里会交替出现「思考 → 正文 → 工具 → 正文」，用字符串只能靠正则切分，渲染层必然失控。`parts` 也是 `UChatMessages` 认的形状。
-
-### 3.2 配置（`GET/POST /api/ai/config`）
-
-```ts
-export interface AiConfig {
-  provider: string        // 预设 id：deepseek / openai / moonshot / siliconflow / ollama / custom
-  baseUrl: string         // 原样使用，不自动补 /v1
-  model: string
-  systemPrompt: string
-  temperature: number
-  maxToolRounds: number
-  contextLimit: number
-  autoCompact: boolean
-  reviewMode: 'manual' | 'auto'
-  hasKey?: boolean        // 只读：是否已存 Key（永远拿不到 Key 本身）
-  presets?: { id: string; label: string; baseUrl: string; model: string }[]
-  tools?: string[]
-}
-```
-
-写配置时 `apiKey` 有三种语义，前端要分清：`undefined` = 不改动、字符串 = 设置、`null` = 清除。
-
-### 3.3 SSE 事件表
-
-`POST /api/ai/chat` 返回 `text/event-stream`，每帧 `data: {json}\n\n`：
-
-| event | 字段 | 前端动作 |
-|---|---|---|
-| `text` | `delta` | 追加到最后一个 text part（没有就新建） |
-| `reasoning` | `delta` | 追加到最后一个 reasoning part，首段记 `startedAt` |
-| `tool-call` | `id` `name` `args` | push 一个 `state: 'running'` 的 tool part |
-| `tool-result` | `id` `ok` `output` `wrote?` | 对应 tool part 改 `done` / `error` |
-| `pending` | `record` | push 待审变更 part（业务可选） |
-| `awaiting-approval` | `id` | 服务端已停流，等用户点批准 |
-| `error` | `message` | 显示错误并在正文补一句 |
-| `done` | `rounds` | 正常收尾 |
-
-`UChatMessages` 的 `status` 只认 `'ready' | 'submitted' | 'streaming' | 'error'`，前端状态机照这四个值维护。
-
----
-
-## 4. 模型设置
-
-### 4.1 形态
-
-设置与对话**共用一个抽屉**，靠右上角图标来回切；不要把设置做成第二个弹窗（关起来像丢了一层）。
-
-```vue
-<header class="ai-head">
-  <b>{{ settingsOpen ? '模型设置' : '看板助手' }}</b>
-  <button class="ai-icon-btn" @click="settingsOpen = !settingsOpen">
-    <UIcon :name="settingsOpen ? 'i-lucide-message-square' : 'i-lucide-settings-2'" />
-  </button>
-  <button class="ai-icon-btn" @click="open = false"><UIcon name="i-lucide-x" /></button>
-</header>
-```
-
-首次打开（还没配 Key）**直接落到设置页**，并在悬浮球上挂红点，否则用户点了助手只看到一句「还没配置」：
-
-```ts
-if (!data.hasKey && data.provider !== 'ollama' && !data.baseUrl?.includes('localhost')) settingsOpen.value = true
-```
-
-### 4.2 表单
-
-```vue
-<script setup lang="ts">
-const form = reactive({
-  provider: 'deepseek',
-  baseUrl: 'https://api.deepseek.com',
-  apiKey: '',
-  model: 'deepseek-chat',
-  systemPrompt: '',
-  temperature: 0.3,
-  maxToolRounds: 30,
-  contextLimit: 256000,
-  autoCompact: true,
-})
-const showKey = ref(false)
-const INPUT_UI = { base: 'ai-input' }   // 圆角只在 .ai-drawer 下生效，不外溢到别的页面
-
-/** 点预设：只填服务商自带的地址与模型，用户仍可手改（网关/反代场景） */
-function applyPreset(p: AiPreset) {
-  form.provider = p.id
-  if (p.baseUrl) { form.baseUrl = p.baseUrl; form.model = p.model }
-}
-
-async function save() {
-  await saveConfig({
-    ...form,
-    temperature: Number(form.temperature),
-    maxToolRounds: Number(form.maxToolRounds),
-    contextLimit: Number(form.contextLimit),
-    // 留空 = 不改动已保存的 Key；要清空走「清除 Key」发 null
-    apiKey: form.apiKey.trim() || undefined,
-  })
-  form.apiKey = ''        // 保存后立刻从内存里抹掉，别留在输入框里
-}
-</script>
-
-<template>
-  <div class="ai-scroll">
-    <p class="ai-banner">配置只存在这台设备上，不写进项目目录，也不回传到浏览器。</p>
-
-    <p class="ai-label">常见服务（点一下填地址）</p>
-    <div class="ai-chips">
-      <button v-for="p in presets" :key="p.id" class="ai-chip" :data-on="form.provider === p.id" @click="applyPreset(p)">
-        {{ p.label }}
-      </button>
-    </div>
-
-    <div class="ai-field">
-      <label>接口地址</label>
-      <UInput v-model="form.baseUrl" :ui="INPUT_UI" placeholder="https://api.deepseek.com" />
-      <p class="ai-help">原样使用，不会自动补 /v1 —— 厂商要求带版本号的请自己填全。</p>
-    </div>
-
-    <div class="ai-field">
-      <label>API Key</label>
-      <UInput
-        v-model="form.apiKey"
-        :ui="INPUT_UI"
-        :type="showKey ? 'text' : 'password'"
-        :placeholder="config.hasKey ? '已保存，留空表示不改动' : 'sk-…'"
-        :trailing-icon="showKey ? 'i-lucide-eye-off' : 'i-lucide-eye'"
-        @click:trailing="showKey = !showKey"
-      />
-      <p class="ai-help">本地 Ollama 这类不填 Key 的服务可以留空。</p>
-    </div>
-
-    <div class="ai-field">
-      <label>系统提示词（可选）</label>
-      <UTextarea v-model="form.systemPrompt" :ui="INPUT_UI" :rows="3" placeholder="只写你自己的偏好，例如「回答先给结论」。" />
-      <p class="ai-help">「能做什么」已经内置，不用重复交代。</p>
-    </div>
-
-    <div class="ai-grid">
-      <div class="ai-field">
-        <label>温度</label>
-        <UInput v-model="form.temperature" :ui="INPUT_UI" type="number" step="0.1" min="0" max="2" />
-      </div>
-      <div class="ai-field">
-        <label>上下文上限（token）</label>
-        <UInput v-model="form.contextLimit" :ui="INPUT_UI" type="number" min="8000" step="1000" />
-      </div>
-      <div class="ai-field">
-        <label>工具调用轮数上限</label>
-        <UInput v-model="form.maxToolRounds" :ui="INPUT_UI" type="number" min="1" max="50" />
-      </div>
-    </div>
-
-    <label class="ai-check">
-      <div class="ai-check-txt">
-        <b>超长时自动压缩老对话</b>
-        <small>超过上下文上限就先丢掉最早那几轮；内置说明和当前提问永远保留。</small>
-      </div>
-      <USwitch v-model="form.autoCompact" />
-    </label>
-
-    <p v-if="saveError" class="ai-error">{{ saveError }}</p>
-    <div class="ai-actions">
-      <button class="btn btn-dark" :disabled="saving" @click="save">{{ saving ? '保存中…' : '保存并开始聊天' }}</button>
-      <button class="btn btn-quiet" @click="clearKey">清除 Key</button>
-    </div>
-  </div>
-</template>
-```
-
-`clearKey` 走 `saveConfig({ apiKey: null })`，成功后停在设置页并清空输入框。
-
-### 4.3 前端要做的错误兜底
-
-服务端会把非法值以 400 + `{ error: '配置非法：温度必须是 0~2 之间的数字' }` 返回。前端统一取 `e?.data?.error || e?.message || '保存失败'` 落到 `saveError`，不要自己再维护一套校验文案 —— 两边规则不一致时用户会看到自相矛盾的两句话。
-
----
-
-## 5. 基本对话
-
-### 5.1 composable：状态机 + 流式解析
-
-（片段里的 `newId` 是 `prefix-时间戳-随机串`；`history()` 见 7.3，`persist()` 见第 6 节。）
-
-```ts
-export function useAi() {
-  const messages = useState<AiMessage[]>('ai-messages', () => [])
-  const status = useState<'ready' | 'submitted' | 'streaming' | 'error'>('ai-status', () => 'ready')
-  const error = useState('ai-error', () => '')
-  const currentThreadId = useState('ai-thread-id', () => '')
-  let controller: AbortController | null = null
-
-  /** 只能改数组里的元素（响应式代理）。抓着刚 push 进去的普通对象改，视图不会更新 */
-  const tail = () => messages.value[messages.value.length - 1]
-
-  function editReply(fn: (m: AiMessage) => void) {
-    const m = tail()
-    if (m?.role === 'assistant') fn(m)
-  }
-
-  /** 第一段正文到来 = 思考段结束，记下耗时给「思考了 N 秒」用 */
-  function sealReasoning() {
-    editReply((m) => {
-      const now = Date.now()
-      m.parts = m.parts.map(p =>
-        p.type === 'reasoning' && p.startedAt && !p.durationSec
-          ? { ...p, durationSec: Math.max(1, Math.round((now - p.startedAt) / 1000)) }
-          : p,
-      )
-    })
-  }
-
-  function appendText(type: 'text' | 'reasoning', delta: string) {
-    if (type === 'text') sealReasoning()
-    editReply((m) => {
-      const parts = m.parts.slice()
-      const last = parts[parts.length - 1]
-      if (last && last.type === type) {
-        parts[parts.length - 1] = type === 'reasoning'
-          ? { ...last, text: last.text + delta, startedAt: (last as any).startedAt ?? Date.now() }
-          : { ...last, text: (last as any).text + delta }
-      } else {
-        parts.push(type === 'reasoning' ? { type, text: delta, startedAt: Date.now() } : { type, text: delta })
-      }
-      m.parts = parts
-    })
-  }
-
-  function pushPart(part: AiPart) {
-    sealReasoning()                       // 工具卡/图片之前先把思考段收尾
-    editReply((m) => { m.parts = [...m.parts, part] })
-  }
-
-  function settleTool(id: string, ok: boolean, output?: string) {
-    editReply((m) => {
-      m.parts = m.parts.map(p =>
-        p.type === 'tool' && p.toolCallId === id ? { ...p, state: ok ? 'done' : 'error', output } : p,
-      )
-    })
-  }
-
-  async function send(text: string, images: AiImage[] = []) {
-    const content = text.trim()
-    if ((!content && !images.length) || status.value === 'submitted' || status.value === 'streaming') return
-    error.value = ''
-
-    // 这一轮固定认一个会话 id：中途切走也不会把内容写进别的会话
-    const threadId = currentThreadId.value || newId('t')
-    currentThreadId.value = threadId
-
-    const parts: AiPart[] = content ? [{ type: 'text', text: content }] : []
-    for (const img of images) parts.push({ type: 'image', id: img.id, url: img.url, name: img.name })
-    messages.value = [...messages.value, { id: newId('u'), role: 'user', parts }]
-    messages.value = [...messages.value, { id: newId('a'), role: 'assistant', parts: [] }]   // 先落位空助手消息
-    status.value = 'submitted'
-
-    controller = new AbortController()
-    try {
-      const response = await fetch('/api/ai/chat', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        // history() 只收有文字的 part，刚落位的空 assistant 自然被排除；
-        // 这里再 slice 一刀会把用户刚问的那句切掉 —— 模型看不到问题，只会重复上一轮
-        body: JSON.stringify({ messages: history() }),
-        signal: controller.signal,
-      })
-      if (!response.ok || !response.body) throw new Error((await response.text()) || `接口返回 ${response.status}`)
-
-      status.value = 'streaming'
-      const reader = response.body.getReader()
-      const decoder = new TextDecoder()
-      let buffer = ''
-      while (true) {
-        const { value, done } = await reader.read()
-        if (done) break
-        buffer += decoder.decode(value, { stream: true })
-        const lines = buffer.split('\n')
-        buffer = lines.pop() ?? ''          // 半个 chunk 留着等下一段
-        for (const raw of lines) {
-          const line = raw.trim()
-          if (!line.startsWith('data:')) continue
-          const payload = line.slice(5).trim()
-          if (!payload) continue
-          let evt: any
-          try { evt = JSON.parse(payload) } catch { continue }
-
-          if (evt.type === 'text') appendText('text', evt.delta)
-          else if (evt.type === 'reasoning') appendText('reasoning', evt.delta)
-          else if (evt.type === 'tool-call') {
-            pushPart({ type: 'tool', toolCallId: evt.id, toolName: evt.name, state: 'running', args: evt.args })
-          } else if (evt.type === 'tool-result') settleTool(evt.id, !!evt.ok, evt.output)
-          else if (evt.type === 'error') {
-            error.value = evt.message
-            appendText('text', `（出错了：${evt.message}）`)
-            status.value = 'error'
-          }
-        }
-      }
-      if (status.value !== 'error') status.value = 'ready'
-    } catch (e: any) {
-      if (e?.name !== 'AbortError') {
-        error.value = e?.message || '对话失败'
-        status.value = 'error'
-        appendText('text', `（出错了：${error.value}）`)
-      } else {
-        status.value = 'ready'             // 主动停止不算错误
-      }
-    } finally {
-      controller = null
-      persist(threadId)                    // 正常/出错/被停都落一次盘
-    }
-  }
-
-  function stop() { controller?.abort(); status.value = 'ready' }
-
-  return { messages, status, error, send, stop, /* … */ }
-}
-```
-
-注意 `fetch` 不用 `EventSource`：需要 POST + 自定义头 + 携带整段历史，`EventSource` 只支持 GET。
-
-### 5.2 对话区
-
-```vue
-<UChatMessages
-  v-if="messages.length"
-  :messages="messages"
-  :status="status"
-  should-auto-scroll
-  :spacing-offset="96"
-  :user="{ variant: 'soft' }"
-  class="ai-messages"
->
-  <template #indicator>
-    <div class="ai-indicator"><UChatShimmer text="思考中…" /></div>
-  </template>
-
-  <template #content="{ message }">
-    <ChatMessageContent
-      :message="message"
-      :streaming="status === 'streaming' && message.id === messages[messages.length - 1]?.id"
-    />
-  </template>
-</UChatMessages>
-```
-
-`#content` 必须接管：默认渲染只画 `text` part，思考、工具、图片、待审变更都出不来。
-
-`spacing-offset` 是给底部固定输入区留出的滚动余量，不给的话最后一条回答会被输入框压住。
-
-### 5.3 part 分发器
-
-（`labelOf` / `suffixOf` / `argsText` / `resultText` 是业务小函数：工具名的中文映射、参数摘要、参数与结果的格式化文本。）
-
-```vue
-<template v-for="(part, index) in message.parts" :key="`${message.id}-${index}`">
-  <ChatReasoningBlock
-    v-if="part.type === 'reasoning'"
-    :text="part.text"
-    :streaming="isPartStreaming(index)"
-    :duration="part.durationSec"
-  />
-
-  <UChatTool
-    v-else-if="part.type === 'tool'"
-    :text="part.state === 'running' ? `${labelOf(part.toolName)}中…` : labelOf(part.toolName)"
-    :suffix="suffixOf(part)"
-    :streaming="part.state === 'running'"
-    chevron="leading"
-  >
-    <div class="ai-tool-io">
-      <p v-if="argsText(part)" class="ai-tool-label">参数</p>
-      <pre v-if="argsText(part)" class="ai-tool-body">{{ argsText(part) }}</pre>
-      <p v-if="resultText(part)" class="ai-tool-label">结果</p>
-      <pre v-if="resultText(part)" class="ai-tool-body">{{ resultText(part) }}</pre>
-    </div>
-  </UChatTool>
-
-  <img v-else-if="part.type === 'image' && part.url" class="ai-msg-img" :src="part.url" :alt="part.name" />
-  <p v-else-if="part.type === 'image'" class="ai-img-missing">图片未保存（历史会话不存图）</p>
-
-  <div v-else-if="part.type === 'text'" class="ai-md">
-    <ChatComark v-if="message.role === 'assistant'" :value="part.text" :streaming="isPartStreaming(index)" />
-    <p v-else class="ai-text">{{ part.text }}</p>   <!-- 用户消息走纯文本，保留换行 -->
-  </div>
-</template>
-```
-
-```ts
-/** 只有最后一段还在长，前面的 part 已定型 —— 流式光标只该出现在末尾 */
-const isPartStreaming = (i: number) => !!props.streaming && i === props.message.parts.length - 1
-```
-
-markdown 用 Comark（AST → Vue 组件，不走 `v-html`，流式增长不会整段重排，也不会把模型输出当 HTML 执行）：
-
-```ts
-// app/components/chat/ChatComark.ts
-export default defineMarkdownComponent({
-  name: 'ChatComark',
-  class: '*:first:mt-0 *:last:mb-0',   // 流式时首个元素的上边距会顶得很难看
-})
-```
-
-### 5.4 思考折叠块
-
-不要直接用 `UChatReasoning`：它的标题走组件库 locale，没装 `@nuxtjs/i18n` 时永远是英文 "Thought for 1 second"。自写一个，交互照官方（流式展开、结束后 600ms 自动收起）：
-
-```vue
-<script setup lang="ts">
-const props = defineProps<{ text: string; streaming?: boolean; duration?: number }>()
-const open = ref(!props.duration && !!props.streaming)
-
-watch(() => props.streaming, (streaming, was) => {
-  if (streaming) open.value = true
-  else if (was) setTimeout(() => { open.value = false }, 600)
-})
-
-const label = computed(() => {
-  if (props.streaming) return '思考中…'
-  if (props.duration) return `思考了 ${props.duration} 秒`
-  return '思考过程'
-})
-</script>
-
-<template>
-  <div class="ai-think" :data-open="open">
-    <button class="ai-think-btn" :aria-expanded="open" @click="open = !open">
-      <UIcon class="ai-think-chev" name="i-lucide-chevron-down" />
-      <span>{{ label }}</span>
-    </button>
-    <div v-show="open" class="ai-think-body">
-      <ChatComark :value="text" :streaming="streaming" />
-    </div>
-  </div>
-</template>
-```
-
-### 5.5 输入区
-
-```vue
-<UChatPrompt
-  v-model="draft"
-  color="neutral"
-  variant="subtle"
-  :rows="1"
-  :maxrows="6"
-  :autofocus="false"
-  placeholder="问点什么…（Enter 发送，截图可直接粘贴）"
-  :disabled="status === 'streaming'"
-  @submit="submit"
->
-  <template #footer>
-    <div class="ai-composer-left">
-      <!-- 从左到右：加图片 → 新建会话 → 历史 → 策略；加东西在左，策略在最右 -->
-      <button class="ai-pick-image" :disabled="adding" @click="pickImages"><UIcon name="i-lucide-image-plus" /></button>
-      <button class="ai-new-thread" @click="ai.newThread()"><UIcon name="i-lucide-plus" /></button>
-      <UPopover v-model:open="historyOpen" :content="{ align: 'start', side: 'top' }">…</UPopover>
-      <UDropdownMenu :items="reviewItems" :content="{ align: 'start', side: 'top' }">
-        <button class="ai-strategy" :data-mode="config.reviewMode">
-          <UIcon :name="config.reviewMode === 'manual' ? 'i-lucide-shield-check' : 'i-lucide-zap'" />
-        </button>
-      </UDropdownMenu>
-    </div>
-
-    <div class="ai-composer-right">
-      <span class="ai-hint">{{ status === 'streaming' ? '正在回答…' : config.model }}</span>
-      <UChatPromptSubmit
-        class="ai-stop"
-        square
-        :status="status"
-        :icon="false"
-        color="neutral"
-        variant="solid"
-        size="sm"
-        @stop="ai.stop()"
-      >
-        <svg v-if="status === 'streaming' || status === 'submitted'" viewBox="0 0 24 24" class="size-4 shrink-0">
-          <rect x="4" y="4" width="16" height="16" rx="2.5" fill="currentColor" />
-        </svg>
-        <UIcon v-else-if="status === 'error'" name="i-lucide-rotate-ccw" class="size-4 shrink-0" />
-        <UIcon v-else name="i-lucide-arrow-up" class="size-4 shrink-0" />
-      </UChatPromptSubmit>
-    </div>
-  </template>
-</UChatPrompt>
-```
-
-```css
-/* ChatPromptSubmit 的 streaming 分支写的是 `streamingIcon || 默认图标`，传 false 挡不住，
-   所以三种状态全部从插槽出，库自带的 leadingIcon 用 CSS 藏掉 */
-.ai-stop [data-slot='leadingIcon'] { display: none; }
-
-/* 输入框：外层框交给组件库，里面那层 textarea 自己再描一圈就成了「框里套框」 */
-.ai-drawer .ai-prompt textarea,
-.ai-drawer .ai-prompt textarea:focus {
-  border: 0; outline: none; box-shadow: none;
-}
-```
-
-空状态给 3~4 个「常用问题」卡片（图标 + 问题 + 一句说明），点一下直接发，比一句「问我点什么」有用得多。
-
----
-
-## 6. 消息历史
-
-浏览器本地存储，服务端一概不知。单机工具不需要账号体系；放服务端就得处理多用户隔离、清理、迁移，收益为零。
-
-```ts
-const THREAD_KEY = 'your-app:ai:threads:v1'
-export const THREAD_LIMIT = 20        // localStorage 只有几 MB
-
-interface AiThreadRecord { id: string; title: string; createdAt: number; updatedAt: number; messages: AiMessage[] }
-interface AiThreadStore { currentId: string | null; threads: AiThreadRecord[] }
-
-function readStore(): AiThreadStore {
-  const empty: AiThreadStore = { currentId: null, threads: [] }
-  if (typeof localStorage === 'undefined') return empty
-  try {
-    const parsed = JSON.parse(localStorage.getItem(THREAD_KEY) || '')
-    const list = Array.isArray(parsed.threads)
-      ? parsed.threads.filter((t: any) => t && typeof t.id === 'string' && Array.isArray(t.messages))
-      : []
-    return { currentId: typeof parsed.currentId === 'string' ? parsed.currentId : null, threads: list.slice(0, THREAD_LIMIT) }
-  } catch { return empty }             // 一条坏 JSON 不该让整个助手打不开
-}
-
-function writeStore(store: AiThreadStore) {
-  const put = (list: AiThreadRecord[]) =>
-    localStorage.setItem(THREAD_KEY, JSON.stringify({ currentId: store.currentId, threads: list.slice(0, THREAD_LIMIT) }))
-  try { put(store.threads) }
-  catch {
-    // 配额满了：砍掉一半最老的再试一次；还不行就放弃 —— 历史不值得打断当前对话
-    try { put(store.threads.slice(0, Math.max(1, Math.ceil(store.threads.length / 2)))) } catch {}
-  }
-}
-
-/**
- * threadId 与当前会话不一致说明中途切走了：宁可不写，也不要把 A 会话的内容盖到 B 上。
- */
-function persist(threadId = currentThreadId.value || newId('t')) {
-  if (currentThreadId.value && threadId !== currentThreadId.value) return
-  if (!messages.value.length) return
-  currentThreadId.value = threadId
-  const store = readStore()
-  const old = store.threads.find(t => t.id === threadId)
-  store.threads = [
-    { id: threadId, title: titleOf(messages.value), createdAt: old?.createdAt ?? Date.now(), updatedAt: Date.now(), messages: stripImages(messages.value) },
-    ...store.threads.filter(t => t.id !== threadId),
-  ]
-  store.currentId = threadId
-  writeStore(store)
-  syncThreads(store)                   // 弹层只拿摘要：id / title / updatedAt / count
-}
-```
-
-配套四件事：
-
-| 动作 | 注意 |
-|---|---|
-| 新建会话 | 先 `stop()` + `persist()` 存下当前这轮（可能只有半截回答），再清空 |
-| 切换会话 | 先 `stop()` + `persist()`；**深拷贝** `JSON.parse(JSON.stringify(record.messages))`，否则消息代理会改到存档对象上 |
-| 删除会话 | 删的正好是当前这条时，对话区一起清空，否则界面停在已不存在的会话上，下次 persist 又写回来 |
-| 标题 | 取第一条用户消息前 24 字，没有就「新会话」 |
-
-弹层里的时间只分几档（刚刚 / N 分钟前 / N 小时前 / M 月 D 日），别写成 `2026-10-26 11:20:31` 让人自己算。
-
-删除要二次确认：第一次点击按钮变红显示「再点一次」，3.2 秒内再点才真删 —— 本地数据删了没法撤销。
-
-`loadThreads()` 在 `onMounted` 里调一次（恢复会话列表 + 上次那条），`deleteThread` / `openThread` / `newThread` 之后都要同步列表。
-
----
-
-## 7. 图片上传
-
-三件事：**压缩、限额、历史不存图**。
-
-### 7.1 压缩：选图与粘贴走同一条路
-
-```ts
-const IMAGE_MAX_EDGE = 1400
-
-export async function fileToAiImage(file: File): Promise<AiImage> {
-  const name = file.name || '粘贴的图片'
-  const fallback = async () => ({ id: newId('img'), url: await readAsDataUrl(file), name })
-  try {
-    const bitmap = await createImageBitmap(file)
-    const scale = Math.min(1, IMAGE_MAX_EDGE / Math.max(bitmap.width, bitmap.height))
-    const canvas = document.createElement('canvas')
-    canvas.width = Math.max(1, Math.round(bitmap.width * scale))
-    canvas.height = Math.max(1, Math.round(bitmap.height * scale))
-    const ctx = canvas.getContext('2d')
-    if (!ctx) return fallback()
-    // JPEG 没有透明通道：先铺白底，否则截图里的透明区域会变黑
-    ctx.fillStyle = '#fff'
-    ctx.fillRect(0, 0, canvas.width, canvas.height)
-    ctx.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
-    bitmap.close()
-    return { id: newId('img'), url: canvas.toDataURL('image/jpeg', 0.86), name }
-  } catch {
-    return fallback()                  // 老浏览器 / 特殊格式：退回原图，别让用户传不了
-  }
-}
-```
-
-一张桌面截图 2~3 MB，直接 base64 塞请求既慢又容易顶到厂商体积上限；缩到长边 1400 + JPEG 0.86 通常 100~300 KB，看界面、读报错完全够。
-
-### 7.2 两条入口 + 限额
-
-```ts
-const MAX_IMAGE_ATTACHMENTS = 4
-
-function pickImages() {
-  if (attachments.value.length >= MAX_IMAGE_ATTACHMENTS) { error.value = `一次最多带 ${MAX_IMAGE_ATTACHMENTS} 张图片`; return }
-  // 模板里不放常驻 file input（会破坏抽屉皮肤），用的时候临时造一个
-  const input = document.createElement('input')
-  Object.assign(input, { type: 'file', accept: 'image/*', multiple: true })
-  input.onchange = () => void addImages([...(input.files ?? [])])
-  input.click()
-}
-
-/** 粘贴截图：paste 从 textarea 冒泡到输入区，只挑剪贴板里的图片文件 */
-function onPaste(event: ClipboardEvent) {
-  const files = [...(event.clipboardData?.items ?? [])]
-    .filter(item => item.kind === 'file' && item.type.startsWith('image/'))
-    .map(item => item.getAsFile())
-    .filter((f): f is File => !!f)
-  if (!files.length) return
-  event.preventDefault()               // 有图片就别再往输入框里插文本路径
-  void addImages(files)
-}
-```
-
-待发图片挂在输入框上方（54×54 缩略图 + 右上角删除角标 + 一行「最多 4 张」，该行只在有附件时出现）：
-
-```vue
-<div v-if="attachments.length" class="ai-attachments">
-  <figure v-for="image in attachments" :key="image.id" class="ai-attach">
-    <img :src="image.url" :alt="image.name">
-    <button class="ai-attach-x" aria-label="移除这张图片" @click="removeImage(image.id)">
-      <UIcon name="i-lucide-x" />
-    </button>
-  </figure>
-  <p class="ai-attach-tip">最多 {{ MAX_IMAGE_ATTACHMENTS }} 张，随这条提问一起发给模型</p>
-</div>
-```
-
-发送时把附件随消息一起清空，避免下一次误带：
-
-```ts
-function submit() {
-  const text = draft.value
-  const images = attachments.value
-  if (!text.trim() && !images.length) return
-  draft.value = ''
-  attachments.value = []
-  ai.send(text, images)
-}
-```
-
-### 7.3 拼进请求：只带最近 N 张
-
-```ts
-export const IMAGE_HISTORY_LIMIT = 4
-
-function history() {
-  const keep = new Set<string>()
-  for (let i = messages.value.length - 1; i >= 0 && keep.size < IMAGE_HISTORY_LIMIT; i -= 1) {
-    for (const p of messages.value[i].parts) if (p.type === 'image' && keep.size < IMAGE_HISTORY_LIMIT) keep.add(p.id)
-  }
-
-  const out = []
-  for (const m of messages.value) {
-    const text = m.parts.filter(p => p.type === 'text').map(p => p.text).join('')
-    const images = m.parts.filter(p => p.type === 'image')
-    // 从历史恢复的图片 url 是空的（落盘时清掉了），空 url 拼进请求就是非法 image_url
-    const sent = images.filter(img => keep.has(img.id) && img.url)
-    const dropped = images.length - sent.length
-    const note = dropped > 0 ? `（之前附的 ${dropped} 张图片已省略）` : ''
-    if (!text.trim() && !sent.length) continue
-    if (!sent.length) { out.push({ role: m.role, content: text.trim() ? `${text}\n${note}` : note }); continue }
-    out.push({
-      role: m.role,
-      content: [
-        ...(text.trim() ? [{ type: 'text', text }] : []),
-        ...(note ? [{ type: 'text', text: note }] : []),
-        ...sent.map(img => ({ type: 'image_url', image_url: { url: img.url } })),
-      ],
-    })
-  }
-  return out
-}
-```
-
-文字上下文一个字不丢，但请求体不会被历史截图堆爆。
-
-### 7.4 落盘时清空 url
-
-```ts
-/** 一张压缩过的截图 base64 上百 KB，几个会话就能撑爆 localStorage */
-function stripImages(messages: AiMessage[]): AiMessage[] {
-  return messages.map(m => ({
-    ...m,
-    parts: m.parts.map(p => (p.type === 'image' ? { ...p, url: '' } : p)),
-  }))
-}
-```
-
-清空 url 而不是删掉 part：恢复后还能在原位显示「图片未保存」占位，用户知道当时发过图（渲染分支见 5.3）。
-
----
-
-## 8. 消息策略（前端侧）
-
-裁剪与压缩由服务端执行，前端要保证三件事，否则服务端再聪明也救不回来。
-
-### 8.1 交给模型的只有「文字 + 最近几张图」
-
-`history()`（见 7.3）必须：
-
-- 跳过空的 assistant 消息（刚落位、还没收到任何 delta）；
-- 把 reasoning / tool / review part 排除在外 —— 它们是给人看的，塞回模型只会让上下文暴涨；
-- 图片只带最近 4 张，其余换一句「已省略」占位；
-- **不要**对 `messages.value` 再做 `slice`。多切一刀就会把用户刚问的那句切掉，模型看不到问题，只会重复上一轮。
-
-### 8.2 状态机不能中途误判
-
-`status` 只有四个值，但含义要分清：
-
-| 值 | 含义 | 界面表现 |
-|---|---|---|
-| `ready` | 空闲，可以发下一条 | 发送按钮（箭头） |
-| `submitted` | 请求已发出，还没收到第一帧 | 停止按钮 + 指示器「思考中…」 |
-| `streaming` | 正在收 delta | 停止按钮 + 末尾流式光标 |
-| `error` | 接口或模型报错 | 重试图标 + 输入区下方红字 |
-
-`awaiting-approval` 到达后服务端已停流，此时**不要**把 `status` 当成 `streaming`：改成 `ready`，另用一个 `awaiting` 变量渲染输入框上方的提示条「已停在这里等你审，点批准或驳回后我才会继续」。否则用户会一直看到转圈。
-
-### 8.3 审核策略的交互
-
-`reviewMode` 是高频操作，放输入框左下角的图标按钮 + `UDropdownMenu`，不要埋进设置页：
-
-```ts
-const reviewItems = computed(() => [[
-  {
-    label: '手动审核',
-    description: '改数据前先出待审卡，你点批准才写入',
-    icon: config.value.reviewMode === 'manual' ? 'i-lucide-check' : 'i-lucide-shield-check',
-    onSelect: () => ai.setReviewMode('manual'),
-  },
-  {
-    label: '自动审核',
-    description: '直接写入并跑校验，校验不过自动回滚',
-    icon: config.value.reviewMode === 'auto' ? 'i-lucide-check' : 'i-lucide-zap',
-    onSelect: () => ai.setReviewMode('auto'),
-  },
-]])
-```
-
-待审卡（`review` part）要点：diff 的每一行都显示 `路径 / 之前 → 之后`，两个按钮「批准并写入」「驳回」，处理完后原地换成状态文案（已写入并通过校验 / 已驳回，文件未改动），不再可点。
-
-```ts
-async function resolvePending(pendingId: string, approve: boolean) {
-  awaiting.value = ''
-  try {
-    if (approve) {
-      await post('/api/ai/pending/apply', { id: pendingId })
-      settleReview(pendingId, 'applied', '已写入并通过校验')
-      await send(`【审核】已批准变更 ${pendingId}，请确认写入结果并继续。`)
-    } else {
-      await post('/api/ai/pending/reject', { id: pendingId })
-      settleReview(pendingId, 'rejected', '已驳回，文件未改动')
-      await send(`【审核】已驳回变更 ${pendingId}，请不要写入，换个方案或先问我。`)
-    }
-  } catch (e: any) {
-    settleReview(pendingId, 'error', e?.data?.error || e?.message || '审核操作失败')
-  }
-}
-```
-
-批准/驳回之后补一条消息让模型接着干，这样「停流 → 人审 → 续跑」才闭环。
-
-### 8.4 幂等：一轮只认一个会话 id
-
-`send()` 开头固定 `threadId`，`finally` 里 `persist(threadId)`。用户中途切会话、删会话都不会把这一轮写到别处去。
-
----
-
-## 9. 布局与样式要点
-
-### 9.1 抽屉自己画，不用 UDrawer
-
-`UDrawer`（vaul）在 `direction=right` 时无条件挂拖拽手势：既吞掉正文的框选，又会在拖选时把整块面板推着走。自绘一个固定面板即可：
-
-```css
-.ai-scrim { position: fixed; inset: 0; z-index: 60; background: rgba(23,24,27,.16); }
-.ai-drawer {
-  position: fixed; top: 0; right: 0; bottom: 0; z-index: 61;
-  display: flex; flex-direction: column;
-  width: min(430px, 100vw);
-  background: #fff; border-left: 1px solid var(--line);
-}
-.ai-sheet-enter-from, .ai-sheet-leave-to { transform: translate3d(100%, 0, 0); }
-```
-
-配 `<Teleport to="body">` + `<Transition name="ai-sheet">`，打开时锁背景滚动：
-
-```ts
-watch(open, v => { if (import.meta.client) document.documentElement.style.overflow = v ? 'hidden' : '' })
-onBeforeUnmount(() => { if (import.meta.client) document.documentElement.style.overflow = '' })  // 不还原，这一页从此滚不动
-```
-
-抽屉内的下拉菜单会被压在面板下面，因为 reka 的浮层用行内 `z-index: auto`：
-
-```css
-[data-reka-popper-content-wrapper] { z-index: 70 !important; }   /* 行内样式只能 !important 压 */
-```
-
-### 9.2 `UChatMessages` 的容器
-
-它的 body 是 `min-w-0` 的 flex 子项，外层不给 `width:100%` 就会把正文压成窄条：
-
-```css
-.ai-messages { width: 100%; min-width: 0; }
-```
-
-### 9.3 控件圆角只作用于抽屉内
-
-`UInput` / `UTextarea` 的样式覆盖通过 `:ui` 传类名，选择器一律挂在 `.ai-drawer` 下，别外溢到别的页面：
-
-```ts
-const INPUT_UI = { base: 'ai-input' }
-const PROMPT_UI = { root: 'ai-prompt', base: ['px-1.5'] }
-```
-
----
-
-## 10. 坑清单
-
-| 现象 | 原因 | 处理 |
-|---|---|---|
-| 流式回答一个字都不刷，最后一次性蹦出来 | 抓着「push 进数组前捕获的普通对象」改，绕过响应式代理 | 一律通过 `messages.value` 里的元素改（`tail()` + `editReply`） |
-| 思考块永远是英文 "Thought for 1 second" | `UChatReasoning` 文案走组件库 locale | 自写折叠块（5.4） |
-| 停止按钮画成空心方块 | `ChatPromptSubmit` 写的是 `streamingIcon \|\| 默认图标`，传 `false` 挡不住 | 三态全部插槽自绘 + 隐藏 `data-slot='leadingIcon'` |
-| 抽屉里正文无法框选、拖选时面板跟着动 | `UDrawer`(vaul) 的拖拽手势 | 自绘固定面板（9.1） |
-| 抽屉里的下拉菜单点开像没反应 | reka 浮层 z-index 低于自绘抽屉 | `[data-reka-popper-content-wrapper] { z-index: 70 !important }` |
-| 最后一条回答被输入框压住 | 没给滚动余量 | `:spacing-offset="96"` |
-| 恢复历史会话后请求 400 | 图片 url 已被清空，空 url 拼进 `image_url` 非法 | `filter(img => img.url)`，缺的换文字占位 |
-| 带图请求失败，用户以为是 Key 或网络 | 模型不是多模态 | 服务端已附提示时原样展示；前端报错区不要改写成「网络错误」 |
-| 用户还没批就看到后续输出 | 待审后前端没停 | 收到 `pending` 立即 `status = 'ready'` + 显示 `awaiting` 提示条 |
-| 删了当前会话，界面还停在它上面 | 没同时清空对话区 | 删当前会话时 `messages = []`、`currentThreadId = ''` |
-| 切会话后消息错乱 / 互相覆盖 | 上一轮的 `persist` 落到新会话上 | `persist(threadId)` 校验 id，不一致直接不写 |
-| 切会话后消息改不动 | 直接赋值存档对象，代理改了原对象 | `JSON.parse(JSON.stringify(...))` 深拷贝 |
-| localStorage 写满，之后所有写操作抛异常 | 会话里存了 base64 图片 | 落盘 `stripImages`；写入失败砍半重试 |
-| 弹层关闭后某一行还亮着「确认删除」 | 待删状态没复位 | `watch(historyOpen, v => !v && resetPendingDelete())` |
-| 抽屉关掉后整页滚不动 | `overflow:hidden` 只在打开时设，没还原 | `onBeforeUnmount` 还原 |
-| 发第二条时把第一张图又带上 | 附件没在 `submit` 里清空 | 提交后 `attachments = []` |
-
----
-
-## 11. 验收清单（前端）
-
-**模型设置**
-
-1. 首次打开（无 Key）自动停在设置页，悬浮球有红点。
-2. 点预设 → 地址与模型名自动填好；手改地址后保存，刷新仍在。
-3. 页面上任何地方都拿不到 Key（DevTools 看 `/api/ai/config` 响应只有 `hasKey`）。
-4. 保存成功后输入框里的 Key 被清空；「清除 Key」后回到设置页且红点重新出现。
-5. 服务端返回 400 时，错误文案显示在设置页内，不弹全局 alert。
-
-**基本对话**
-
-6. 回答逐字出现，首字前有「思考中…」指示器。
-7. 点停止 → 立刻停，`status` 回 `ready`，已收到的内容保留。
-8. 思考模型：思考内容落在折叠块里，正文开始后自动收起并显示「思考了 N 秒」。
-9. 工具调用：先出现「xx中…」，结果回来后变成「xx」，展开能看参数与结果。
-10. 报错时正文补一句「（出错了：…）」且输入区下方有红字，发送按钮变重试图标。
-
-**消息历史**
-
-11. 聊几句 → 新建会话 → 历史弹层出现上一条，标题是第一句前 24 字。
-12. 切回旧会话，消息与 part 类型（含工具卡）完整恢复。
-13. 删除需两次点击；删当前会话后对话区同步清空。
-14. 刷新页面恢复上次会话；时间显示为「刚刚 / N 分钟前」。
-
-**图片**
-
-15. 上传 3 MB 截图 → 缩略图正常，请求体明显变小（DevTools 看 payload）。
-16. 输入框里 Ctrl+V 粘贴截图 → 变成附件，不插入文本。
-17. 发第 5 张 → 提示上限 4 张。
-18. 历史会话里的图片显示占位，且不会发出空 url。
-
-**策略与交互**
-
-19. 手动审核：待审卡出现后指示器停止转圈，输入框上方出现「等你审」提示条；批准后自动续跑。
-20. 驳回后模型换方案继续，文件未被改动（文案明确）。
-21. 自动审核：没有待审卡，直接显示「已写入并通过校验」。
-22. 审核策略切换后，图标与下拉里的勾选项一致，刷新后保持。
-23. 弹出浮层不被抽屉遮挡；抽屉关闭后页面可正常滚动。
-
----
-
-## 12. 移植到新项目
-
-| 文件 | 保留 | 替换 |
-|---|---|---|
-| `composables/use-ai.ts` | 状态机、流式解析、`history()`、会话历史 | 业务 part（如 `review`）可整段删 |
-| `AiAssistant.vue` | 抽屉骨架、设置面板、输入区、历史弹层 | 空状态示例问题、业务卡片渲染 |
-| `chat/MessageContent.vue` | part 分发结构 | `TOOL_NAME` 映射、业务 part 分支 |
-| `chat/ReasoningBlock.vue` / `ChatComark.ts` | 原样搬 | — |
-| `main.css` 的 `.ai-*` | 抽屉、消息、输入区骨架 | 配色与圆角换成本项目 token |
-
-接口侧只需满足第 3 节的契约（config 掩码 + SSE 事件表），前端一行不用改。
+# 基于 Nuxt UI 的 AI 助手前端开发指南
+
+这份文档只讲**前端**：模型设置的界面与状态、基本对话、消息历史、图片上传、消息策略在浏览器侧落地的方式，以及关键代码。服务端（读配置、拼 system prompt、转发模型、跑工具）视为已存在的黑盒，只约定接口契约。
+
+技术基线（本项目实测可用）：Nuxt 4 + `@nuxt/ui` 4 + `@comark/nuxt` 0.7。页面是 SPA（`ssr: false`），所有状态留在浏览器。
+
+---
+
+## 1. 前端只做三件事
+
+```
+┌───────────────────────────── 浏览器 ─────────────────────────────┐
+│ AiAssistant.vue        悬浮球 + 抽屉 + 设置页 / 对话页切换        │
+│   ├─ 设置面板          UInput / UTextarea / USwitch / 预设 chips  │
+│   ├─ 对话区            UChatMessages + part 分发器                │
+│   └─ 输入区            UChatPrompt + 图片 / 新建 / 历史 / 策略     │
+│ use-ai.ts              消息、状态机、SSE 解析、localStorage        │
+└──────────────────────────────────────────────────────────────────┘
+              │ GET/POST /api/ai/config      POST /api/ai/chat (SSE)
+              ▼
+        服务端（黑盒，Key 与模型地址都在那边）
+```
+
+前端的三条职责边界，越界就会出问题：
+
+1. **不碰 Key**。只读 `hasKey`，写配置时把用户输入原样交给服务端。
+2. **不自己算上下文**。裁剪是服务端的事，前端只负责把历史整理成「文字 + 最近几张图」的合法结构。
+3. **只改 `messages.value` 里的元素**。任何攒起来准备后改的对象都会绕过响应式代理，表现为「流式回答一个字都不刷新」。
+
+---
+
+## 2. 目录与依赖
+
+```
+app/
+  components/AiAssistant.vue          抽屉 + 悬浮球 + 设置面板 + 对话区
+  components/chat/
+    ChatComark.ts                     markdown 流式渲染（defineMarkdownComponent）
+    MessageContent.vue                part 分发器（text/reasoning/tool/image/review）
+    ReasoningBlock.vue                思考折叠块
+  composables/use-ai.ts               状态、流式解析、会话历史
+  assets/css/main.css                 .ai-* 样式（抽屉骨架、消息、输入区）
+```
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "@comark/nuxt": "^0.7.0",
+    "@nuxt/ui": "^4.12.0",
+    "nuxt": "^4.6.2"
+  },
+  "devDependencies": { "@iconify-json/lucide": "^1.2.147" }
+}
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', '@comark/nuxt'],
+  ssr: false,                                  // 单机工具，不需要 SEO，省掉一半水合问题
+  css: ['~/assets/css/main.css'],              // 先 @import "tailwindcss"; 再 @import "@nuxt/ui";
+  ui: { colorMode: false, fonts: false },       // 不用暗色/在线字体就关掉，避免白屏等字体
+})
+```
+
+`app.vue` 最外层必须是 `<UApp>`，否则 `UPopover` / `UDropdownMenu` 的浮层与 Toast 都不工作：
+
+```vue
+<template>
+  <UApp>
+    <NuxtPage />
+    <AiAssistant />   <!-- 挂在外壳上，所有页面都能叫出来 -->
+  </UApp>
+</template>
+```
+
+---
+
+## 3. 与后端的数据契约
+
+前端只需要照这个形状读写，不用关心服务端怎么实现。
+
+### 3.1 消息与 part
+
+```ts
+export type AiPart =
+  | { type: 'text'; text: string }
+  // startedAt/durationSec 用来算「思考了 N 秒」：第一段思考 → 第一段正文之间的耗时
+  | { type: 'reasoning'; text: string; startedAt?: number; durationSec?: number }
+  | { type: 'tool'; toolCallId: string; toolName: string; state: 'running' | 'done' | 'error'; args?: unknown; output?: string }
+  | { type: 'image'; id: string; url: string; name?: string }
+  | { type: 'review'; pendingId: string; state: 'pending' | 'applied' | 'rejected' | 'error'; /* 业务字段 */ }
+
+export interface AiMessage { id: string; role: 'user' | 'assistant'; parts: AiPart[] }
+```
+
+为什么不用 `content: string`：一条回答里会交替出现「思考 → 正文 → 工具 → 正文」，用字符串只能靠正则切分，渲染层必然失控。`parts` 也是 `UChatMessages` 认的形状。
+
+### 3.2 配置（`GET/POST /api/ai/config`）
+
+```ts
+export interface AiConfig {
+  provider: string        // 预设 id：deepseek / openai / moonshot / siliconflow / ollama / custom
+  baseUrl: string         // 原样使用，不自动补 /v1
+  model: string
+  systemPrompt: string
+  temperature: number
+  maxToolRounds: number
+  contextLimit: number
+  autoCompact: boolean
+  reviewMode: 'manual' | 'auto'
+  hasKey?: boolean        // 只读：是否已存 Key（永远拿不到 Key 本身）
+  presets?: { id: string; label: string; baseUrl: string; model: string }[]
+  tools?: string[]
+}
+```
+
+写配置时 `apiKey` 有三种语义，前端要分清：`undefined` = 不改动、字符串 = 设置、`null` = 清除。
+
+### 3.3 SSE 事件表
+
+`POST /api/ai/chat` 返回 `text/event-stream`，每帧 `data: {json}\n\n`：
+
+| event | 字段 | 前端动作 |
+|---|---|---|
+| `text` | `delta` | 追加到最后一个 text part（没有就新建） |
+| `reasoning` | `delta` | 追加到最后一个 reasoning part，首段记 `startedAt` |
+| `tool-call` | `id` `name` `args` | push 一个 `state: 'running'` 的 tool part |
+| `tool-result` | `id` `ok` `output` `wrote?` | 对应 tool part 改 `done` / `error` |
+| `pending` | `record` | push 待审变更 part（业务可选） |
+| `awaiting-approval` | `id` | 服务端已停流，等用户点批准 |
+| `error` | `message` | 显示错误并在正文补一句 |
+| `done` | `rounds` | 正常收尾 |
+
+`UChatMessages` 的 `status` 只认 `'ready' | 'submitted' | 'streaming' | 'error'`，前端状态机照这四个值维护。
+
+---
+
+## 4. 模型设置
+
+### 4.1 形态
+
+设置与对话**共用一个抽屉**，靠右上角图标来回切；不要把设置做成第二个弹窗（关起来像丢了一层）。
+
+```vue
+<header class="ai-head">
+  <b>{{ settingsOpen ? '模型设置' : '看板助手' }}</b>
+  <button class="ai-icon-btn" @click="settingsOpen = !settingsOpen">
+    <UIcon :name="settingsOpen ? 'i-lucide-message-square' : 'i-lucide-settings-2'" />
+  </button>
+  <button class="ai-icon-btn" @click="open = false"><UIcon name="i-lucide-x" /></button>
+</header>
+```
+
+首次打开（还没配 Key）**直接落到设置页**，并在悬浮球上挂红点，否则用户点了助手只看到一句「还没配置」：
+
+```ts
+if (!data.hasKey && data.provider !== 'ollama' && !data.baseUrl?.includes('localhost')) settingsOpen.value = true
+```
+
+### 4.2 表单
+
+```vue
+<script setup lang="ts">
+const form = reactive({
+  provider: 'deepseek',
+  baseUrl: 'https://api.deepseek.com',
+  apiKey: '',
+  model: 'deepseek-chat',
+  systemPrompt: '',
+  temperature: 0.3,
+  maxToolRounds: 30,
+  contextLimit: 256000,
+  autoCompact: true,
+})
+const showKey = ref(false)
+const INPUT_UI = { base: 'ai-input' }   // 圆角只在 .ai-drawer 下生效，不外溢到别的页面
+
+/** 点预设：只填服务商自带的地址与模型，用户仍可手改（网关/反代场景） */
+function applyPreset(p: AiPreset) {
+  form.provider = p.id
+  if (p.baseUrl) { form.baseUrl = p.baseUrl; form.model = p.model }
+}
+
+async function save() {
+  await saveConfig({
+    ...form,
+    temperature: Number(form.temperature),
+    maxToolRounds: Number(form.maxToolRounds),
+    contextLimit: Number(form.contextLimit),
+    // 留空 = 不改动已保存的 Key；要清空走「清除 Key」发 null
+    apiKey: form.apiKey.trim() || undefined,
+  })
+  form.apiKey = ''        // 保存后立刻从内存里抹掉，别留在输入框里
+}
+</script>
+
+<template>
+  <div class="ai-scroll">
+    <p class="ai-banner">配置只存在这台设备上，不写进项目目录，也不回传到浏览器。</p>
+
+    <p class="ai-label">常见服务（点一下填地址）</p>
+    <div class="ai-chips">
+      <button v-for="p in presets" :key="p.id" class="ai-chip" :data-on="form.provider === p.id" @click="applyPreset(p)">
+        {{ p.label }}
+      </button>
+    </div>
+
+    <div class="ai-field">
+      <label>接口地址</label>
+      <UInput v-model="form.baseUrl" :ui="INPUT_UI" placeholder="https://api.deepseek.com" />
+      <p class="ai-help">原样使用，不会自动补 /v1 —— 厂商要求带版本号的请自己填全。</p>
+    </div>
+
+    <div class="ai-field">
+      <label>API Key</label>
+      <UInput
+        v-model="form.apiKey"
+        :ui="INPUT_UI"
+        :type="showKey ? 'text' : 'password'"
+        :placeholder="config.hasKey ? '已保存，留空表示不改动' : 'sk-…'"
+        :trailing-icon="showKey ? 'i-lucide-eye-off' : 'i-lucide-eye'"
+        @click:trailing="showKey = !showKey"
+      />
+      <p class="ai-help">本地 Ollama 这类不填 Key 的服务可以留空。</p>
+    </div>
+
+    <div class="ai-field">
+      <label>系统提示词（可选）</label>
+      <UTextarea v-model="form.systemPrompt" :ui="INPUT_UI" :rows="3" placeholder="只写你自己的偏好，例如「回答先给结论」。" />
+      <p class="ai-help">「能做什么」已经内置，不用重复交代。</p>
+    </div>
+
+    <div class="ai-grid">
+      <div class="ai-field">
+        <label>温度</label>
+        <UInput v-model="form.temperature" :ui="INPUT_UI" type="number" step="0.1" min="0" max="2" />
+      </div>
+      <div class="ai-field">
+        <label>上下文上限（token）</label>
+        <UInput v-model="form.contextLimit" :ui="INPUT_UI" type="number" min="8000" step="1000" />
+      </div>
+      <div class="ai-field">
+        <label>工具调用轮数上限</label>
+        <UInput v-model="form.maxToolRounds" :ui="INPUT_UI" type="number" min="1" max="50" />
+      </div>
+    </div>
+
+    <label class="ai-check">
+      <div class="ai-check-txt">
+        <b>超长时自动压缩老对话</b>
+        <small>超过上下文上限就先丢掉最早那几轮；内置说明和当前提问永远保留。</small>
+      </div>
+      <USwitch v-model="form.autoCompact" />
+    </label>
+
+    <p v-if="saveError" class="ai-error">{{ saveError }}</p>
+    <div class="ai-actions">
+      <button class="btn btn-dark" :disabled="saving" @click="save">{{ saving ? '保存中…' : '保存并开始聊天' }}</button>
+      <button class="btn btn-quiet" @click="clearKey">清除 Key</button>
+    </div>
+  </div>
+</template>
+```
+
+`clearKey` 走 `saveConfig({ apiKey: null })`，成功后停在设置页并清空输入框。
+
+### 4.3 前端要做的错误兜底
+
+服务端会把非法值以 400 + `{ error: '配置非法：温度必须是 0~2 之间的数字' }` 返回。前端统一取 `e?.data?.error || e?.message || '保存失败'` 落到 `saveError`，不要自己再维护一套校验文案 —— 两边规则不一致时用户会看到自相矛盾的两句话。
+
+---
+
+## 5. 基本对话
+
+### 5.1 composable：状态机 + 流式解析
+
+（片段里的 `newId` 是 `prefix-时间戳-随机串`；`history()` 见 7.3，`persist()` 见第 6 节。）
+
+```ts
+export function useAi() {
+  const messages = useState<AiMessage[]>('ai-messages', () => [])
+  const status = useState<'ready' | 'submitted' | 'streaming' | 'error'>('ai-status', () => 'ready')
+  const error = useState('ai-error', () => '')
+  const currentThreadId = useState('ai-thread-id', () => '')
+  let controller: AbortController | null = null
+
+  /** 只能改数组里的元素（响应式代理）。抓着刚 push 进去的普通对象改，视图不会更新 */
+  const tail = () => messages.value[messages.value.length - 1]
+
+  function editReply(fn: (m: AiMessage) => void) {
+    const m = tail()
+    if (m?.role === 'assistant') fn(m)
+  }
+
+  /** 第一段正文到来 = 思考段结束，记下耗时给「思考了 N 秒」用 */
+  function sealReasoning() {
+    editReply((m) => {
+      const now = Date.now()
+      m.parts = m.parts.map(p =>
+        p.type === 'reasoning' && p.startedAt && !p.durationSec
+          ? { ...p, durationSec: Math.max(1, Math.round((now - p.startedAt) / 1000)) }
+          : p,
+      )
+    })
+  }
+
+  function appendText(type: 'text' | 'reasoning', delta: string) {
+    if (type === 'text') sealReasoning()
+    editReply((m) => {
+      const parts = m.parts.slice()
+      const last = parts[parts.length - 1]
+      if (last && last.type === type) {
+        parts[parts.length - 1] = type === 'reasoning'
+          ? { ...last, text: last.text + delta, startedAt: (last as any).startedAt ?? Date.now() }
+          : { ...last, text: (last as any).text + delta }
+      } else {
+        parts.push(type === 'reasoning' ? { type, text: delta, startedAt: Date.now() } : { type, text: delta })
+      }
+      m.parts = parts
+    })
+  }
+
+  function pushPart(part: AiPart) {
+    sealReasoning()                       // 工具卡/图片之前先把思考段收尾
+    editReply((m) => { m.parts = [...m.parts, part] })
+  }
+
+  function settleTool(id: string, ok: boolean, output?: string) {
+    editReply((m) => {
+      m.parts = m.parts.map(p =>
+        p.type === 'tool' && p.toolCallId === id ? { ...p, state: ok ? 'done' : 'error', output } : p,
+      )
+    })
+  }
+
+  async function send(text: string, images: AiImage[] = []) {
+    const content = text.trim()
+    if ((!content && !images.length) || status.value === 'submitted' || status.value === 'streaming') return
+    error.value = ''
+
+    // 这一轮固定认一个会话 id：中途切走也不会把内容写进别的会话
+    const threadId = currentThreadId.value || newId('t')
+    currentThreadId.value = threadId
+
+    const parts: AiPart[] = content ? [{ type: 'text', text: content }] : []
+    for (const img of images) parts.push({ type: 'image', id: img.id, url: img.url, name: img.name })
+    messages.value = [...messages.value, { id: newId('u'), role: 'user', parts }]
+    messages.value = [...messages.value, { id: newId('a'), role: 'assistant', parts: [] }]   // 先落位空助手消息
+    status.value = 'submitted'
+
+    controller = new AbortController()
+    try {
+      const response = await fetch('/api/ai/chat', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        // history() 只收有文字的 part，刚落位的空 assistant 自然被排除；
+        // 这里再 slice 一刀会把用户刚问的那句切掉 —— 模型看不到问题，只会重复上一轮
+        body: JSON.stringify({ messages: history() }),
+        signal: controller.signal,
+      })
+      if (!response.ok || !response.body) throw new Error((await response.text()) || `接口返回 ${response.status}`)
+
+      status.value = 'streaming'
+      const reader = response.body.getReader()
+      const decoder = new TextDecoder()
+      let buffer = ''
+      while (true) {
+        const { value, done } = await reader.read()
+        if (done) break
+        buffer += decoder.decode(value, { stream: true })
+        const lines = buffer.split('\n')
+        buffer = lines.pop() ?? ''          // 半个 chunk 留着等下一段
+        for (const raw of lines) {
+          const line = raw.trim()
+          if (!line.startsWith('data:')) continue
+          const payload = line.slice(5).trim()
+          if (!payload) continue
+          let evt: any
+          try { evt = JSON.parse(payload) } catch { continue }
+
+          if (evt.type === 'text') appendText('text', evt.delta)
+          else if (evt.type === 'reasoning') appendText('reasoning', evt.delta)
+          else if (evt.type === 'tool-call') {
+            pushPart({ type: 'tool', toolCallId: evt.id, toolName: evt.name, state: 'running', args: evt.args })
+          } else if (evt.type === 'tool-result') settleTool(evt.id, !!evt.ok, evt.output)
+          else if (evt.type === 'error') {
+            error.value = evt.message
+            appendText('text', `（出错了：${evt.message}）`)
+            status.value = 'error'
+          }
+        }
+      }
+      if (status.value !== 'error') status.value = 'ready'
+    } catch (e: any) {
+      if (e?.name !== 'AbortError') {
+        error.value = e?.message || '对话失败'
+        status.value = 'error'
+        appendText('text', `（出错了：${error.value}）`)
+      } else {
+        status.value = 'ready'             // 主动停止不算错误
+      }
+    } finally {
+      controller = null
+      persist(threadId)                    // 正常/出错/被停都落一次盘
+    }
+  }
+
+  function stop() { controller?.abort(); status.value = 'ready' }
+
+  return { messages, status, error, send, stop, /* … */ }
+}
+```
+
+注意 `fetch` 不用 `EventSource`：需要 POST + 自定义头 + 携带整段历史，`EventSource` 只支持 GET。
+
+### 5.2 对话区
+
+```vue
+<UChatMessages
+  v-if="messages.length"
+  :messages="messages"
+  :status="status"
+  should-auto-scroll
+  :spacing-offset="96"
+  :user="{ variant: 'soft' }"
+  class="ai-messages"
+>
+  <template #indicator>
+    <div class="ai-indicator"><UChatShimmer text="思考中…" /></div>
+  </template>
+
+  <template #content="{ message }">
+    <ChatMessageContent
+      :message="message"
+      :streaming="status === 'streaming' && message.id === messages[messages.length - 1]?.id"
+    />
+  </template>
+</UChatMessages>
+```
+
+`#content` 必须接管：默认渲染只画 `text` part，思考、工具、图片、待审变更都出不来。
+
+`spacing-offset` 是给底部固定输入区留出的滚动余量，不给的话最后一条回答会被输入框压住。
+
+### 5.3 part 分发器
+
+（`labelOf` / `suffixOf` / `argsText` / `resultText` 是业务小函数：工具名的中文映射、参数摘要、参数与结果的格式化文本。）
+
+```vue
+<template v-for="(part, index) in message.parts" :key="`${message.id}-${index}`">
+  <ChatReasoningBlock
+    v-if="part.type === 'reasoning'"
+    :text="part.text"
+    :streaming="isPartStreaming(index)"
+    :duration="part.durationSec"
+  />
+
+  <UChatTool
+    v-else-if="part.type === 'tool'"
+    :text="part.state === 'running' ? `${labelOf(part.toolName)}中…` : labelOf(part.toolName)"
+    :suffix="suffixOf(part)"
+    :streaming="part.state === 'running'"
+    chevron="leading"
+  >
+    <div class="ai-tool-io">
+      <p v-if="argsText(part)" class="ai-tool-label">参数</p>
+      <pre v-if="argsText(part)" class="ai-tool-body">{{ argsText(part) }}</pre>
+      <p v-if="resultText(part)" class="ai-tool-label">结果</p>
+      <pre v-if="resultText(part)" class="ai-tool-body">{{ resultText(part) }}</pre>
+    </div>
+  </UChatTool>
+
+  <img v-else-if="part.type === 'image' && part.url" class="ai-msg-img" :src="part.url" :alt="part.name" />
+  <p v-else-if="part.type === 'image'" class="ai-img-missing">图片未保存（历史会话不存图）</p>
+
+  <div v-else-if="part.type === 'text'" class="ai-md">
+    <ChatComark v-if="message.role === 'assistant'" :value="part.text" :streaming="isPartStreaming(index)" />
+    <p v-else class="ai-text">{{ part.text }}</p>   <!-- 用户消息走纯文本，保留换行 -->
+  </div>
+</template>
+```
+
+```ts
+/** 只有最后一段还在长，前面的 part 已定型 —— 流式光标只该出现在末尾 */
+const isPartStreaming = (i: number) => !!props.streaming && i === props.message.parts.length - 1
+```
+
+markdown 用 Comark（AST → Vue 组件，不走 `v-html`，流式增长不会整段重排，也不会把模型输出当 HTML 执行）：
+
+```ts
+// app/components/chat/ChatComark.ts
+export default defineMarkdownComponent({
+  name: 'ChatComark',
+  class: '*:first:mt-0 *:last:mb-0',   // 流式时首个元素的上边距会顶得很难看
+})
+```
+
+### 5.4 思考折叠块
+
+不要直接用 `UChatReasoning`：它的标题走组件库 locale，没装 `@nuxtjs/i18n` 时永远是英文 "Thought for 1 second"。自写一个，交互照官方（流式展开、结束后 600ms 自动收起）：
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{ text: string; streaming?: boolean; duration?: number }>()
+const open = ref(!props.duration && !!props.streaming)
+
+watch(() => props.streaming, (streaming, was) => {
+  if (streaming) open.value = true
+  else if (was) setTimeout(() => { open.value = false }, 600)
+})
+
+const label = computed(() => {
+  if (props.streaming) return '思考中…'
+  if (props.duration) return `思考了 ${props.duration} 秒`
+  return '思考过程'
+})
+</script>
+
+<template>
+  <div class="ai-think" :data-open="open">
+    <button class="ai-think-btn" :aria-expanded="open" @click="open = !open">
+      <UIcon class="ai-think-chev" name="i-lucide-chevron-down" />
+      <span>{{ label }}</span>
+    </button>
+    <div v-show="open" class="ai-think-body">
+      <ChatComark :value="text" :streaming="streaming" />
+    </div>
+  </div>
+</template>
+```
+
+### 5.5 输入区
+
+```vue
+<UChatPrompt
+  v-model="draft"
+  color="neutral"
+  variant="subtle"
+  :rows="1"
+  :maxrows="6"
+  :autofocus="false"
+  placeholder="问点什么…（Enter 发送，截图可直接粘贴）"
+  :disabled="status === 'streaming'"
+  @submit="submit"
+>
+  <template #footer>
+    <div class="ai-composer-left">
+      <!-- 从左到右：加图片 → 新建会话 → 历史 → 策略；加东西在左，策略在最右 -->
+      <button class="ai-pick-image" :disabled="adding" @click="pickImages"><UIcon name="i-lucide-image-plus" /></button>
+      <button class="ai-new-thread" @click="ai.newThread()"><UIcon name="i-lucide-plus" /></button>
+      <UPopover v-model:open="historyOpen" :content="{ align: 'start', side: 'top' }">…</UPopover>
+      <UDropdownMenu :items="reviewItems" :content="{ align: 'start', side: 'top' }">
+        <button class="ai-strategy" :data-mode="config.reviewMode">
+          <UIcon :name="config.reviewMode === 'manual' ? 'i-lucide-shield-check' : 'i-lucide-zap'" />
+        </button>
+      </UDropdownMenu>
+    </div>
+
+    <div class="ai-composer-right">
+      <span class="ai-hint">{{ status === 'streaming' ? '正在回答…' : config.model }}</span>
+      <UChatPromptSubmit
+        class="ai-stop"
+        square
+        :status="status"
+        :icon="false"
+        color="neutral"
+        variant="solid"
+        size="sm"
+        @stop="ai.stop()"
+      >
+        <svg v-if="status === 'streaming' || status === 'submitted'" viewBox="0 0 24 24" class="size-4 shrink-0">
+          <rect x="4" y="4" width="16" height="16" rx="2.5" fill="currentColor" />
+        </svg>
+        <UIcon v-else-if="status === 'error'" name="i-lucide-rotate-ccw" class="size-4 shrink-0" />
+        <UIcon v-else name="i-lucide-arrow-up" class="size-4 shrink-0" />
+      </UChatPromptSubmit>
+    </div>
+  </template>
+</UChatPrompt>
+```
+
+```css
+/* ChatPromptSubmit 的 streaming 分支写的是 `streamingIcon || 默认图标`，传 false 挡不住，
+   所以三种状态全部从插槽出，库自带的 leadingIcon 用 CSS 藏掉 */
+.ai-stop [data-slot='leadingIcon'] { display: none; }
+
+/* 输入框：外层框交给组件库，里面那层 textarea 自己再描一圈就成了「框里套框」 */
+.ai-drawer .ai-prompt textarea,
+.ai-drawer .ai-prompt textarea:focus {
+  border: 0; outline: none; box-shadow: none;
+}
+```
+
+空状态给 3~4 个「常用问题」卡片（图标 + 问题 + 一句说明），点一下直接发，比一句「问我点什么」有用得多。
+
+---
+
+## 6. 消息历史
+
+浏览器本地存储，服务端一概不知。单机工具不需要账号体系；放服务端就得处理多用户隔离、清理、迁移，收益为零。
+
+```ts
+const THREAD_KEY = 'your-app:ai:threads:v1'
+export const THREAD_LIMIT = 20        // localStorage 只有几 MB
+
+interface AiThreadRecord { id: string; title: string; createdAt: number; updatedAt: number; messages: AiMessage[] }
+interface AiThreadStore { currentId: string | null; threads: AiThreadRecord[] }
+
+function readStore(): AiThreadStore {
+  const empty: AiThreadStore = { currentId: null, threads: [] }
+  if (typeof localStorage === 'undefined') return empty
+  try {
+    const parsed = JSON.parse(localStorage.getItem(THREAD_KEY) || '')
+    const list = Array.isArray(parsed.threads)
+      ? parsed.threads.filter((t: any) => t && typeof t.id === 'string' && Array.isArray(t.messages))
+      : []
+    return { currentId: typeof parsed.currentId === 'string' ? parsed.currentId : null, threads: list.slice(0, THREAD_LIMIT) }
+  } catch { return empty }             // 一条坏 JSON 不该让整个助手打不开
+}
+
+function writeStore(store: AiThreadStore) {
+  const put = (list: AiThreadRecord[]) =>
+    localStorage.setItem(THREAD_KEY, JSON.stringify({ currentId: store.currentId, threads: list.slice(0, THREAD_LIMIT) }))
+  try { put(store.threads) }
+  catch {
+    // 配额满了：砍掉一半最老的再试一次；还不行就放弃 —— 历史不值得打断当前对话
+    try { put(store.threads.slice(0, Math.max(1, Math.ceil(store.threads.length / 2)))) } catch {}
+  }
+}
+
+/**
+ * threadId 与当前会话不一致说明中途切走了：宁可不写，也不要把 A 会话的内容盖到 B 上。
+ */
+function persist(threadId = currentThreadId.value || newId('t')) {
+  if (currentThreadId.value && threadId !== currentThreadId.value) return
+  if (!messages.value.length) return
+  currentThreadId.value = threadId
+  const store = readStore()
+  const old = store.threads.find(t => t.id === threadId)
+  store.threads = [
+    { id: threadId, title: titleOf(messages.value), createdAt: old?.createdAt ?? Date.now(), updatedAt: Date.now(), messages: stripImages(messages.value) },
+    ...store.threads.filter(t => t.id !== threadId),
+  ]
+  store.currentId = threadId
+  writeStore(store)
+  syncThreads(store)                   // 弹层只拿摘要：id / title / updatedAt / count
+}
+```
+
+配套四件事：
+
+| 动作 | 注意 |
+|---|---|
+| 新建会话 | 先 `stop()` + `persist()` 存下当前这轮（可能只有半截回答），再清空 |
+| 切换会话 | 先 `stop()` + `persist()`；**深拷贝** `JSON.parse(JSON.stringify(record.messages))`，否则消息代理会改到存档对象上 |
+| 删除会话 | 删的正好是当前这条时，对话区一起清空，否则界面停在已不存在的会话上，下次 persist 又写回来 |
+| 标题 | 取第一条用户消息前 24 字，没有就「新会话」 |
+
+弹层里的时间只分几档（刚刚 / N 分钟前 / N 小时前 / M 月 D 日），别写成 `2026-10-26 11:20:31` 让人自己算。
+
+删除要二次确认：第一次点击按钮变红显示「再点一次」，3.2 秒内再点才真删 —— 本地数据删了没法撤销。
+
+`loadThreads()` 在 `onMounted` 里调一次（恢复会话列表 + 上次那条），`deleteThread` / `openThread` / `newThread` 之后都要同步列表。
+
+---
+
+## 7. 图片上传
+
+三件事：**压缩、限额、历史不存图**。
+
+### 7.1 压缩：选图与粘贴走同一条路
+
+```ts
+const IMAGE_MAX_EDGE = 1400
+
+export async function fileToAiImage(file: File): Promise<AiImage> {
+  const name = file.name || '粘贴的图片'
+  const fallback = async () => ({ id: newId('img'), url: await readAsDataUrl(file), name })
+  try {
+    const bitmap = await createImageBitmap(file)
+    const scale = Math.min(1, IMAGE_MAX_EDGE / Math.max(bitmap.width, bitmap.height))
+    const canvas = document.createElement('canvas')
+    canvas.width = Math.max(1, Math.round(bitmap.width * scale))
+    canvas.height = Math.max(1, Math.round(bitmap.height * scale))
+    const ctx = canvas.getContext('2d')
+    if (!ctx) return fallback()
+    // JPEG 没有透明通道：先铺白底，否则截图里的透明区域会变黑
+    ctx.fillStyle = '#fff'
+    ctx.fillRect(0, 0, canvas.width, canvas.height)
+    ctx.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+    bitmap.close()
+    return { id: newId('img'), url: canvas.toDataURL('image/jpeg', 0.86), name }
+  } catch {
+    return fallback()                  // 老浏览器 / 特殊格式：退回原图，别让用户传不了
+  }
+}
+```
+
+一张桌面截图 2~3 MB，直接 base64 塞请求既慢又容易顶到厂商体积上限；缩到长边 1400 + JPEG 0.86 通常 100~300 KB，看界面、读报错完全够。
+
+### 7.2 两条入口 + 限额
+
+```ts
+const MAX_IMAGE_ATTACHMENTS = 4
+
+function pickImages() {
+  if (attachments.value.length >= MAX_IMAGE_ATTACHMENTS) { error.value = `一次最多带 ${MAX_IMAGE_ATTACHMENTS} 张图片`; return }
+  // 模板里不放常驻 file input（会破坏抽屉皮肤），用的时候临时造一个
+  const input = document.createElement('input')
+  Object.assign(input, { type: 'file', accept: 'image/*', multiple: true })
+  input.onchange = () => void addImages([...(input.files ?? [])])
+  input.click()
+}
+
+/** 粘贴截图：paste 从 textarea 冒泡到输入区，只挑剪贴板里的图片文件 */
+function onPaste(event: ClipboardEvent) {
+  const files = [...(event.clipboardData?.items ?? [])]
+    .filter(item => item.kind === 'file' && item.type.startsWith('image/'))
+    .map(item => item.getAsFile())
+    .filter((f): f is File => !!f)
+  if (!files.length) return
+  event.preventDefault()               // 有图片就别再往输入框里插文本路径
+  void addImages(files)
+}
+```
+
+待发图片挂在输入框上方（54×54 缩略图 + 右上角删除角标 + 一行「最多 4 张」，该行只在有附件时出现）：
+
+```vue
+<div v-if="attachments.length" class="ai-attachments">
+  <figure v-for="image in attachments" :key="image.id" class="ai-attach">
+    <img :src="image.url" :alt="image.name">
+    <button class="ai-attach-x" aria-label="移除这张图片" @click="removeImage(image.id)">
+      <UIcon name="i-lucide-x" />
+    </button>
+  </figure>
+  <p class="ai-attach-tip">最多 {{ MAX_IMAGE_ATTACHMENTS }} 张，随这条提问一起发给模型</p>
+</div>
+```
+
+发送时把附件随消息一起清空，避免下一次误带：
+
+```ts
+function submit() {
+  const text = draft.value
+  const images = attachments.value
+  if (!text.trim() && !images.length) return
+  draft.value = ''
+  attachments.value = []
+  ai.send(text, images)
+}
+```
+
+### 7.3 拼进请求：只带最近 N 张
+
+```ts
+export const IMAGE_HISTORY_LIMIT = 4
+
+function history() {
+  const keep = new Set<string>()
+  for (let i = messages.value.length - 1; i >= 0 && keep.size < IMAGE_HISTORY_LIMIT; i -= 1) {
+    for (const p of messages.value[i].parts) if (p.type === 'image' && keep.size < IMAGE_HISTORY_LIMIT) keep.add(p.id)
+  }
+
+  const out = []
+  for (const m of messages.value) {
+    const text = m.parts.filter(p => p.type === 'text').map(p => p.text).join('')
+    const images = m.parts.filter(p => p.type === 'image')
+    // 从历史恢复的图片 url 是空的（落盘时清掉了），空 url 拼进请求就是非法 image_url
+    const sent = images.filter(img => keep.has(img.id) && img.url)
+    const dropped = images.length - sent.length
+    const note = dropped > 0 ? `（之前附的 ${dropped} 张图片已省略）` : ''
+    if (!text.trim() && !sent.length) continue
+    if (!sent.length) { out.push({ role: m.role, content: text.trim() ? `${text}\n${note}` : note }); continue }
+    out.push({
+      role: m.role,
+      content: [
+        ...(text.trim() ? [{ type: 'text', text }] : []),
+        ...(note ? [{ type: 'text', text: note }] : []),
+        ...sent.map(img => ({ type: 'image_url', image_url: { url: img.url } })),
+      ],
+    })
+  }
+  return out
+}
+```
+
+文字上下文一个字不丢，但请求体不会被历史截图堆爆。
+
+### 7.4 落盘时清空 url
+
+```ts
+/** 一张压缩过的截图 base64 上百 KB，几个会话就能撑爆 localStorage */
+function stripImages(messages: AiMessage[]): AiMessage[] {
+  return messages.map(m => ({
+    ...m,
+    parts: m.parts.map(p => (p.type === 'image' ? { ...p, url: '' } : p)),
+  }))
+}
+```
+
+清空 url 而不是删掉 part：恢复后还能在原位显示「图片未保存」占位，用户知道当时发过图（渲染分支见 5.3）。
+
+---
+
+## 8. 消息策略（前端侧）
+
+裁剪与压缩由服务端执行，前端要保证三件事，否则服务端再聪明也救不回来。
+
+### 8.1 交给模型的只有「文字 + 最近几张图」
+
+`history()`（见 7.3）必须：
+
+- 跳过空的 assistant 消息（刚落位、还没收到任何 delta）；
+- 把 reasoning / tool / review part 排除在外 —— 它们是给人看的，塞回模型只会让上下文暴涨；
+- 图片只带最近 4 张，其余换一句「已省略」占位；
+- **不要**对 `messages.value` 再做 `slice`。多切一刀就会把用户刚问的那句切掉，模型看不到问题，只会重复上一轮。
+
+### 8.2 状态机不能中途误判
+
+`status` 只有四个值，但含义要分清：
+
+| 值 | 含义 | 界面表现 |
+|---|---|---|
+| `ready` | 空闲，可以发下一条 | 发送按钮（箭头） |
+| `submitted` | 请求已发出，还没收到第一帧 | 停止按钮 + 指示器「思考中…」 |
+| `streaming` | 正在收 delta | 停止按钮 + 末尾流式光标 |
+| `error` | 接口或模型报错 | 重试图标 + 输入区下方红字 |
+
+`awaiting-approval` 到达后服务端已停流，此时**不要**把 `status` 当成 `streaming`：改成 `ready`，另用一个 `awaiting` 变量渲染输入框上方的提示条「已停在这里等你审，点批准或驳回后我才会继续」。否则用户会一直看到转圈。
+
+### 8.3 审核策略的交互
+
+`reviewMode` 是高频操作，放输入框左下角的图标按钮 + `UDropdownMenu`，不要埋进设置页：
+
+```ts
+const reviewItems = computed(() => [[
+  {
+    label: '手动审核',
+    description: '改数据前先出待审卡，你点批准才写入',
+    icon: config.value.reviewMode === 'manual' ? 'i-lucide-check' : 'i-lucide-shield-check',
+    onSelect: () => ai.setReviewMode('manual'),
+  },
+  {
+    label: '自动审核',
+    description: '直接写入并跑校验，校验不过自动回滚',
+    icon: config.value.reviewMode === 'auto' ? 'i-lucide-check' : 'i-lucide-zap',
+    onSelect: () => ai.setReviewMode('auto'),
+  },
+]])
+```
+
+待审卡（`review` part）要点：diff 的每一行都显示 `路径 / 之前 → 之后`，两个按钮「批准并写入」「驳回」，处理完后原地换成状态文案（已写入并通过校验 / 已驳回，文件未改动），不再可点。
+
+```ts
+async function resolvePending(pendingId: string, approve: boolean) {
+  awaiting.value = ''
+  try {
+    if (approve) {
+      await post('/api/ai/pending/apply', { id: pendingId })
+      settleReview(pendingId, 'applied', '已写入并通过校验')
+      await send(`【审核】已批准变更 ${pendingId}，请确认写入结果并继续。`)
+    } else {
+      await post('/api/ai/pending/reject', { id: pendingId })
+      settleReview(pendingId, 'rejected', '已驳回，文件未改动')
+      await send(`【审核】已驳回变更 ${pendingId}，请不要写入，换个方案或先问我。`)
+    }
+  } catch (e: any) {
+    settleReview(pendingId, 'error', e?.data?.error || e?.message || '审核操作失败')
+  }
+}
+```
+
+批准/驳回之后补一条消息让模型接着干，这样「停流 → 人审 → 续跑」才闭环。
+
+### 8.4 幂等：一轮只认一个会话 id
+
+`send()` 开头固定 `threadId`，`finally` 里 `persist(threadId)`。用户中途切会话、删会话都不会把这一轮写到别处去。
+
+---
+
+## 9. 布局与样式要点
+
+### 9.1 抽屉自己画，不用 UDrawer
+
+`UDrawer`（vaul）在 `direction=right` 时无条件挂拖拽手势：既吞掉正文的框选，又会在拖选时把整块面板推着走。自绘一个固定面板即可：
+
+```css
+.ai-scrim { position: fixed; inset: 0; z-index: 60; background: rgba(23,24,27,.16); }
+.ai-drawer {
+  position: fixed; top: 0; right: 0; bottom: 0; z-index: 61;
+  display: flex; flex-direction: column;
+  width: min(430px, 100vw);
+  background: #fff; border-left: 1px solid var(--line);
+}
+.ai-sheet-enter-from, .ai-sheet-leave-to { transform: translate3d(100%, 0, 0); }
+```
+
+配 `<Teleport to="body">` + `<Transition name="ai-sheet">`，打开时锁背景滚动：
+
+```ts
+watch(open, v => { if (import.meta.client) document.documentElement.style.overflow = v ? 'hidden' : '' })
+onBeforeUnmount(() => { if (import.meta.client) document.documentElement.style.overflow = '' })  // 不还原，这一页从此滚不动
+```
+
+抽屉内的下拉菜单会被压在面板下面，因为 reka 的浮层用行内 `z-index: auto`：
+
+```css
+[data-reka-popper-content-wrapper] { z-index: 70 !important; }   /* 行内样式只能 !important 压 */
+```
+
+### 9.2 `UChatMessages` 的容器
+
+它的 body 是 `min-w-0` 的 flex 子项，外层不给 `width:100%` 就会把正文压成窄条：
+
+```css
+.ai-messages { width: 100%; min-width: 0; }
+```
+
+### 9.3 控件圆角只作用于抽屉内
+
+`UInput` / `UTextarea` 的样式覆盖通过 `:ui` 传类名，选择器一律挂在 `.ai-drawer` 下，别外溢到别的页面：
+
+```ts
+const INPUT_UI = { base: 'ai-input' }
+const PROMPT_UI = { root: 'ai-prompt', base: ['px-1.5'] }
+```
+
+---
+
+## 10. 坑清单
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 流式回答一个字都不刷，最后一次性蹦出来 | 抓着「push 进数组前捕获的普通对象」改，绕过响应式代理 | 一律通过 `messages.value` 里的元素改（`tail()` + `editReply`） |
+| 思考块永远是英文 "Thought for 1 second" | `UChatReasoning` 文案走组件库 locale | 自写折叠块（5.4） |
+| 停止按钮画成空心方块 | `ChatPromptSubmit` 写的是 `streamingIcon \|\| 默认图标`，传 `false` 挡不住 | 三态全部插槽自绘 + 隐藏 `data-slot='leadingIcon'` |
+| 抽屉里正文无法框选、拖选时面板跟着动 | `UDrawer`(vaul) 的拖拽手势 | 自绘固定面板（9.1） |
+| 抽屉里的下拉菜单点开像没反应 | reka 浮层 z-index 低于自绘抽屉 | `[data-reka-popper-content-wrapper] { z-index: 70 !important }` |
+| 最后一条回答被输入框压住 | 没给滚动余量 | `:spacing-offset="96"` |
+| 恢复历史会话后请求 400 | 图片 url 已被清空，空 url 拼进 `image_url` 非法 | `filter(img => img.url)`，缺的换文字占位 |
+| 带图请求失败，用户以为是 Key 或网络 | 模型不是多模态 | 服务端已附提示时原样展示；前端报错区不要改写成「网络错误」 |
+| 用户还没批就看到后续输出 | 待审后前端没停 | 收到 `pending` 立即 `status = 'ready'` + 显示 `awaiting` 提示条 |
+| 删了当前会话，界面还停在它上面 | 没同时清空对话区 | 删当前会话时 `messages = []`、`currentThreadId = ''` |
+| 切会话后消息错乱 / 互相覆盖 | 上一轮的 `persist` 落到新会话上 | `persist(threadId)` 校验 id，不一致直接不写 |
+| 切会话后消息改不动 | 直接赋值存档对象，代理改了原对象 | `JSON.parse(JSON.stringify(...))` 深拷贝 |
+| localStorage 写满，之后所有写操作抛异常 | 会话里存了 base64 图片 | 落盘 `stripImages`；写入失败砍半重试 |
+| 弹层关闭后某一行还亮着「确认删除」 | 待删状态没复位 | `watch(historyOpen, v => !v && resetPendingDelete())` |
+| 抽屉关掉后整页滚不动 | `overflow:hidden` 只在打开时设，没还原 | `onBeforeUnmount` 还原 |
+| 发第二条时把第一张图又带上 | 附件没在 `submit` 里清空 | 提交后 `attachments = []` |
+
+---
+
+## 11. 验收清单（前端）
+
+**模型设置**
+
+1. 首次打开（无 Key）自动停在设置页，悬浮球有红点。
+2. 点预设 → 地址与模型名自动填好；手改地址后保存，刷新仍在。
+3. 页面上任何地方都拿不到 Key（DevTools 看 `/api/ai/config` 响应只有 `hasKey`）。
+4. 保存成功后输入框里的 Key 被清空；「清除 Key」后回到设置页且红点重新出现。
+5. 服务端返回 400 时，错误文案显示在设置页内，不弹全局 alert。
+
+**基本对话**
+
+6. 回答逐字出现，首字前有「思考中…」指示器。
+7. 点停止 → 立刻停，`status` 回 `ready`，已收到的内容保留。
+8. 思考模型：思考内容落在折叠块里，正文开始后自动收起并显示「思考了 N 秒」。
+9. 工具调用：先出现「xx中…」，结果回来后变成「xx」，展开能看参数与结果。
+10. 报错时正文补一句「（出错了：…）」且输入区下方有红字，发送按钮变重试图标。
+
+**消息历史**
+
+11. 聊几句 → 新建会话 → 历史弹层出现上一条，标题是第一句前 24 字。
+12. 切回旧会话，消息与 part 类型（含工具卡）完整恢复。
+13. 删除需两次点击；删当前会话后对话区同步清空。
+14. 刷新页面恢复上次会话；时间显示为「刚刚 / N 分钟前」。
+
+**图片**
+
+15. 上传 3 MB 截图 → 缩略图正常，请求体明显变小（DevTools 看 payload）。
+16. 输入框里 Ctrl+V 粘贴截图 → 变成附件，不插入文本。
+17. 发第 5 张 → 提示上限 4 张。
+18. 历史会话里的图片显示占位，且不会发出空 url。
+
+**策略与交互**
+
+19. 手动审核：待审卡出现后指示器停止转圈，输入框上方出现「等你审」提示条；批准后自动续跑。
+20. 驳回后模型换方案继续，文件未被改动（文案明确）。
+21. 自动审核：没有待审卡，直接显示「已写入并通过校验」。
+22. 审核策略切换后，图标与下拉里的勾选项一致，刷新后保持。
+23. 弹出浮层不被抽屉遮挡；抽屉关闭后页面可正常滚动。
+
+---
+
+## 12. 移植到新项目
+
+| 文件 | 保留 | 替换 |
+|---|---|---|
+| `composables/use-ai.ts` | 状态机、流式解析、`history()`、会话历史 | 业务 part（如 `review`）可整段删 |
+| `AiAssistant.vue` | 抽屉骨架、设置面板、输入区、历史弹层 | 空状态示例问题、业务卡片渲染 |
+| `chat/MessageContent.vue` | part 分发结构 | `TOOL_NAME` 映射、业务 part 分支 |
+| `chat/ReasoningBlock.vue` / `ChatComark.ts` | 原样搬 | — |
+| `main.css` 的 `.ai-*` | 抽屉、消息、输入区骨架 | 配色与圆角换成本项目 token |
+
+接口侧只需满足第 3 节的契约（config 掩码 + SSE 事件表），前端一行不用改。