From febe04a5691033c88b43bb5aa5ca3da8fa5440c5 Mon Sep 17 00:00:00 2001
From: caoqianming <caoqianming@foxmail.com>
Date: Wed, 20 May 2026 16:33:47 +0800
Subject: [PATCH] =?UTF-8?q?ui(media):=20tool=20=E7=BB=93=E6=9E=9C=E4=B8=8E?=
 =?UTF-8?q?=20assistant=20=E6=AD=A3=E6=96=87=E5=90=8C=E8=B7=AF=E5=BE=84=20?=
 =?UTF-8?q?chip/inline=20=E5=9B=BE=E5=8E=BB=E9=87=8D=20=E2=80=94=20Set=20O?=
 =?UTF-8?q?(n)=20+=20CLAUDE.md=20=E5=8A=A0=20"=E5=AE=9E=E6=96=BD=E5=89=8D?=
 =?UTF-8?q?=E5=85=88=E5=AF=B9=E6=96=B9=E6=A1=88"=20=E6=AE=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md           | 11 +++++++++++
 PROGRESS.md         |  2 ++
 web/static/dev.html | 28 ++++++++++++++++++++++------
 3 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ebd41d1..357ccf7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,17 @@
 - 跑脚本 / 测试一律用 `.venv/Scripts/python.exe ...`,**不要用全局 `python`**(没装 litellm/python-pptx 等会报 ModuleNotFoundError)
 - requirements 见 `requirements.txt`
 
+## 实施前先对方案
+
+非平凡改动(改 >1 个文件 / 涉及行为变化 / 多个候选方案有取舍)动手前**先用自然语言把方案讲给用户确认,认可后再写代码**。一次性 bug 修复 / 改字面量 / 样式微调 / 加日志这类无歧义动作可以直接动手。
+
+讲方案时要包含:
+- 问题定位(指到具体文件 / 行号 / 当前行为)
+- 至少 1 个替代方案 + 当前方案为什么更优
+- 涉及性能 / 兼容 / 数据迁移时主动说
+
+理由:开发期需求漂移快,写到一半被推翻代价高 —— 口头对齐方案是最低成本的纠偏机会。
+
 ## 开发阶段心智
 
 当前处于**开发测试期**(开发自用 + 内部测试,DB 已有真实测试数据)。改需求 / 重构时,**以最优实现为准,不为旧数据 / 旧字段 / 旧 API 留兼容层**,但**不删现有数据**:
diff --git a/PROGRESS.md b/PROGRESS.md
index 3aae313..66e07c6 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -23,6 +23,8 @@
 
 ### 2026-05-20
 
+- **dev SPA 中间产物 chip / inline 图去重 + CLAUDE.md 新增"实施前先对方案"段**:用户报"工具结果里挂了一张图,后面 assistant 正文又挂了一张同图,有点重复"。根因:`renderArtifactBarHtml(extractArtifactRels(...))` 在 5 个渲染点都跑过 — `renderMessages` 里 tool 结果卡 / assistant 正文 / assistant tool_calls args 各一处,`handleSseEvent` 里 tool_call / tool_result 各一处。同一 rel 在 tool 结果与紧随 assistant 正文里同时出现(模型 echo 路径)→ 历史回放渲两次。修法:`renderMessages` 顶部建 `const seenRels = new Set()` + `pickFresh(rels)` 闭包,3 个调用点(tool 结果 / assistant 正文 / tool_calls args)全部包一层 — chronological 顺序,首次出现保留(tool 结果常在前),后续重复丢;SSE `ctx` 加 `seenRels: new Set()`,tool_call / tool_result 两 handler 共享去重。**对比 querySelector 版**:DOM 查询版 O(n²)(每条 card 渲染时扫 wrap 已有 `[data-rel]`),Set 版 O(n) 无查询,代码量相同还把"什么是 source of truth"明确(不依赖 DOM 已挂 chip 这个隐式状态)。**CLAUDE.md 增段**:开发期需求漂移快,非平凡改动(改 >1 文件 / 行为变化 / 多候选取舍)动手前先用自然语言把方案讲给用户确认,认可后再写代码;一次性 bug 修 / 字面量 / 样式微调可直接动手。方案描述要包含问题定位(文件 / 行号)+ 至少 1 个替代方案 + 涉及性能 / 兼容 / 数据迁移时主动说。**没动**:`extractArtifactRels` / `renderArtifactBarHtml` 实现(它们内部本身已 Set 去重单次调用内重复)、`_workingDirName` / chip 点击委托 / 媒体 blob 缓存、后端、DESIGN(纯前端 UX 修复)、RUN(无对外行为变化)。
+
 - **dev SPA 顶栏加生图模型下拉 + 中间产物图片/视频内联展示**:用户要 ① 项目栏右侧的模型选区加一个生图模型选择(目前只 seedream,默认选上),② 中间产物若是图片/视频直接在对话区展示(不只点击预览)。**生图选择范式判断**:不入 task 列(seedream/seedance 是 tool 范畴,non-chat,task 切粒度太粗;且现在仅一个 variant,加 DB 列纯负债)→ 走**消息级**:UI 下拉的选择跟 `POST /v1/tasks/{id}/messages` body 的 `image_model` 字段一起发,`_run_agent_bg` → `build_agent(image_variant=...)` → seedream tool 装配时按 key 挑 yaml 里 `image` 段的对应 variant_cfg;不入 DB,本 run 内多次 tool call 共用,下条消息可重选。**后端新接口** `GET /v1/image_models`(scan `config/media/doubao.yaml` image 段返 `{variant, display_name, model_id, price_cny_per_image, is_default}` 列表;不要求 `ARK_API_KEY` 已设 — UI 只展示元数据,真调时 `ArkConfig.load()` 那侧再过 key 检查),`_resolve_image_model(variant)` 校验存在性(空串 → 透传走 fallback,非空 → 必须命中 yaml,否则 400)。`agent_builder.build_agent` 新参 `image_variant: str = ""`:非空且命中 → 用它装 SeedreamTool;不命中(yaml 改动后旧选择 stale)静默回 fallback;空 → 沿用"取第一个 variant"。**前端**:`state.imageModels` + `state.imageModel`(per-session,不持久);`loadModels()` 同时拉 `/v1/image_models` 并锁第一个为默认;`renderImageModelDropdown()` 在 `renderModelDropdown` 旁画一个 `生图 [▾]`(yaml 无 variant 时不画);`onChangeImageModel` 纯前端 state 更新无 PATCH;`sendMessage` 把 `state.imageModel` 跟在 POST body 上发出去。**内联媒体**:`_EXT_GROUPS` 加 `video: {mp4,webm,mov,mkv,m4v}` 集合;`renderArtifactBarHtml` 按 `_categorize(rel)` 分支:image/video → 占位 `<span class="art-media[-image|-video]" data-rel="...">`,其他 → 沿用 `.art-chip`;新 `upgradeMediaArtifacts(root)` DOM walk 把占位异步换 `<img>`/`<video controls>`,经 `_fetchMediaBlobUrl(rel)`(Bearer header 不能直 `<img src=>` → fetch 拿 blob 转 `URL.createObjectURL`)+ `_mediaArtifactCache` 同 rel 复用;模态 `openFilePreview` 加 `_showVideo`(`<video controls autoplay>`);chip / `.art-media-image` 点击 → 弹模态放大,视频走原生 controls 不拦截(点击=暂停/播放,全屏走浏览器按钮,弹模态反而打断播放)。**缓存生命周期**:cache 走 `selectTask` 切换时 `_flushMediaArtifactCache` 撤销 blob URL;同 task 流式 / 历史回放复用,/clear 不清(FS 文件保留,rel 仍有效);logout 走 `location.reload()` 全清。**没动**:DESIGN(无架构/schema 变化)、Task / TaskState / TaskCreateRequest / TaskPatchRequest schema(早期一稿曾加 `Task.image_model` 列 + 0008 migration,用户复盘后判定 task 粒度不合适撤回 — 测试期 DB downgrade 不留 0008,模型/字段也清干净)、`record_image_usage`(model_profile 仍走 `doubao.<variant_key>`,自然跟着 build_agent 选的 variant)、artifact chip 抽取(其他类型仍走 chip + openFilePreview)。**Tradeoff**:① 不入 DB → 浏览器刷新会回到 yaml 第一个 variant 默认值,但用户中途切换的"上次选了什么"丢了 — 改用 localStorage 即可,先简单版;② 内联图片对每条带产物的消息都触发 fetch,blob URL 累积在 cache 里直到切 task 才回收,长会话场景 + 数十张图理论上内存吃几百 MB(普通 PNG 1-3MB),后续若问题再加 IntersectionObserver 懒加载。
 
 - **LLM 调用切 streaming(cancel 秒退 + 前端打字机)+ 发送/停止合并单按钮**:用户反馈"点停止要等很久"+"发送/停止可以合并"。**问题 1 根因**:`litellm.completion(...)` 是同步阻塞,Python 没标准办法外部线程打断同步 IO;`broker.is_cancelled` 只在 `core/loop.py:run()` 每轮 LLM 前 + tool_calls 之间 poll,所以 cancel 必须等当前整轮 generation 跑完才生效(deepseek v4 + thinking + 长输出几十秒)。**修法**:切 `litellm.completion(stream=True)`,`core/llm.py` 加 `chat_stream()` generator(`stream_options={"include_usage": True}` 让最后 chunk 带 usage;`_build_kwargs` 抽出来给 chat/chat_stream 共用,免重复参数装配);`core/loop.py` 主循环改 `_stream_llm()` 流式迭代,chunk 间 poll cancel,命中 `break` + generator finally `stream.close()` 关底层 httpx 连接;chunks 攒齐用 `litellm.stream_chunk_builder(chunks, messages=...)` 拼回完整 response(自动处理 tool_call name/arguments 跨 chunk 拼接)给 tool_calls 解析 + usage 记账。**cancel 语义对齐**:stream 中途 cancel → 已收 chunk 丢弃不入库不记账(下次 resume 上下文干净);stream 完结后 tool_calls 之间 cancel → 沿用原 `_fill_cancelled_tool_results` 补 cancelled tool message。**前端打字机免费 bonus**:`dev.html:1500-1510` 早就备好接 `text` 事件的 `delta` 字段(rAF 节流 + nearBottom 不抢滚动 + 流中不跑 highlight),但后端原来发的是 `{"type":"text","content":"<整段>"}` 字段名对不上 → 前端永远 match 不到。新逻辑在 `_stream_llm` 里 chunk 到达即 `_emit({"type":"text","delta":...})`,前端自然激活打字机。loop.py 主流程末尾不再 emit 整段 text(content 已通过 delta 流过)。**问题 2 UI**:`web/static/dev.html` 把 `#chat-send`(发送)+ `#chat-cancel`(停止)合并为单 `#chat-action`,新 helper `setActionMode(mode)`(idle="发送" primary 红实心 / streaming="停止" danger 红边 / cancelling="停止中…" disabled);form submit + `chatAction()` 根据 `state.streaming` 分派 sendMessage / cancelCurrentTask;streaming 期间 Enter 不触发停止(textarea 编辑下一条草稿,误触发风险高)。**Smoke 验证**:① 18 chunks 流式 + 文本拼回 ✓ ② tool_call 49 chunks 跨片拼回 `{"a":7,"b":5}` 完整 ✓ ③ 提前 break + close 仅 0.7s(模拟"写 500 字散文中途 cancel")✓。**Tradeoffs**:① streaming 重试只在连接建立阶段(没拿到第一个 chunk 前)生效,中途断流不续 — 实务罕见;② timeout 行为从"整段 timeout"变"chunk 间隔 timeout",新模型接入要测 thinking 不吐 reasoning chunk 的极端情况;③ litellm `stream_chunk_builder` + `stream_options.include_usage` 在 deepseek/doubao/glm/openai 标准协议都正常,新接非主流 provider 时验证。**没动**:probe.py(仍用同步 `chat()`,离线探测不需要 cancel)、CLI 路径(probe 走 chat 不受影响)、broker / SSE 帧格式 / `record_chat_usage` 入参 / DB schema / messages 入库时机(拼回 response 跟非流式等价)。**文档**:`DESIGN.md` §3.1 翻转 tradeoff 表「LLM 同步 call 不可中断」→「LLM 调用走 streaming」+ §7 API 表 cancel 描述改 chunk-level 延迟;`RUN.md` cancel 接口 + 故障兜底表对应行同步;`web/app.py` 两条 docstring 同步。
diff --git a/web/static/dev.html b/web/static/dev.html
index 0506818..e2e45e5 100644
--- a/web/static/dev.html
+++ b/web/static/dev.html
@@ -1358,6 +1358,18 @@ function renderMessages(msgs) {
   // 模型切换点小标:assistant 行的 model_profile 与上一个 assistant 不同就插一行分隔
   // (含首条);避免每条都标制造噪声。空 model_profile(历史旧数据)不画。
   let lastAsstModel = null;
+  // chip 去重:同一路径在 tool 结果里挂过 inline 图后,assistant 正文 echo 同路径不再重挂。
+  // chronological 遍历,首次出现保留(tool 结果常在前),后续重复过滤掉。
+  const seenRels = new Set();
+  const pickFresh = (rels) => {
+    const fresh = [];
+    for (const r of rels) {
+      if (seenRels.has(r)) continue;
+      seenRels.add(r);
+      fresh.push(r);
+    }
+    return fresh;
+  };
   for (const m of msgs) {
     const p = m.payload || {};
     const role = p.role || "?";
@@ -1381,7 +1393,7 @@ function renderMessages(msgs) {
       card.innerHTML = `
         <div class="role">工具调用 · ${escapeHtml(p.name || "")}</div>
         <details class="tool-call"><summary>结果(${(txt || "").length} 字符)${banner}</summary><pre>${escapeHtml(txt || "")}</pre></details>
-        ${renderArtifactBarHtml(extractArtifactRels(txt || "", wd))}
+        ${renderArtifactBarHtml(pickFresh(extractArtifactRels(txt || "", wd)))}
       `;
       wrap.appendChild(card);
       continue;
@@ -1395,7 +1407,7 @@ function renderMessages(msgs) {
       // assistant 正文里 echo 的 <wd>/... 路径同样挂 chip 条(只对 assistant,user 输入不抽)
       if (role === "assistant") {
         const wd = _workingDirName(state.taskMeta && state.taskMeta.working_dir);
-        html += renderArtifactBarHtml(extractArtifactRels(p.content, wd));
+        html += renderArtifactBarHtml(pickFresh(extractArtifactRels(p.content, wd)));
       }
     }
     if (Array.isArray(p.tool_calls) && p.tool_calls.length) {
@@ -1408,7 +1420,7 @@ function renderMessages(msgs) {
         } catch (e) { args = (tc.function && tc.function.arguments) || ""; }
         html += `
           <details class="tool-call"><summary>工具调用:${escapeHtml(fn)}</summary><pre>${escapeHtml(args)}</pre></details>
-          ${renderArtifactBarHtml(extractArtifactRels(args, wd))}
+          ${renderArtifactBarHtml(pickFresh(extractArtifactRels(args, wd)))}
         `;
       }
     }
@@ -1537,7 +1549,7 @@ function streamSse(url, asstCard) {
 
 async function fetchSse(url, asstCard) {
   const body = asstCard.querySelector(".body");
-  const ctx = { acc: "", body, pending: false };
+  const ctx = { acc: "", body, pending: false, seenRels: new Set() };
   try {
     const r = await fetch(url, {
       headers: { "Authorization": "Bearer " + state.token, "Accept": "text/event-stream" },
@@ -1617,7 +1629,9 @@ function handleSseEvent(ev, asstCard, ctx) {
     det.innerHTML = `<summary>工具调用:${escapeHtml(fn)}</summary><pre>${escapeHtml(argsStr)}</pre>`;
     asstCard.appendChild(det);
     const wd = _workingDirName(state.taskMeta && state.taskMeta.working_dir);
-    const barHtml = renderArtifactBarHtml(extractArtifactRels(argsStr, wd));
+    const fresh = extractArtifactRels(argsStr, wd).filter(r => !ctx.seenRels.has(r));
+    fresh.forEach(r => ctx.seenRels.add(r));
+    const barHtml = renderArtifactBarHtml(fresh);
     if (barHtml) {
       asstCard.insertAdjacentHTML("beforeend", barHtml);
       upgradeMediaArtifacts(asstCard);
@@ -1632,7 +1646,9 @@ function handleSseEvent(ev, asstCard, ctx) {
     det.innerHTML = `<summary>工具结果${banner}</summary><pre>${escapeHtml(txtStr)}</pre>`;
     asstCard.appendChild(det);
     const wd = _workingDirName(state.taskMeta && state.taskMeta.working_dir);
-    const barHtml = renderArtifactBarHtml(extractArtifactRels(txtStr, wd));
+    const fresh = extractArtifactRels(txtStr, wd).filter(r => !ctx.seenRels.has(r));
+    fresh.forEach(r => ctx.seenRels.add(r));
+    const barHtml = renderArtifactBarHtml(fresh);
     if (barHtml) {
       asstCard.insertAdjacentHTML("beforeend", barHtml);
       upgradeMediaArtifacts(asstCard);