wishforge-ide/docs/design/copilot-references.md
wishforge 5855d5a43c
Some checks failed
CI / Format, types and tests (pull_request) Has been cancelled
CI / PostgreSQL migrations and integration tests (pull_request) Has been cancelled
CI / IDE gateway, collaboration and policy tests (pull_request) Has been cancelled
✨ Render diagnosis cards, tool steps, safe Markdown, and editable Wish drafts
Display structured Copilot diagnoses with verdict badges, server-stamped evidence chips, confidence-tagged hypotheses, missing-evidence callouts, and an explicit handoff path when evidence is insufficient.

Add progressive start/end tool step rows, path-scrubbed Markdown rendering via react-markdown and remark-gfm, typed stream error banners, sticky-threshold auto-scroll, copy actions, Grill-me choice previews, editable Wish drafts, and the accompanying design and operations docs.
2026-11-11 07:59:03 -08:00

17 KiB
Raw Blame History

Copilot 前端借鉴清单(GitHub 调研)

调研人:searcher · 2026-11-10 · 状态:待 Chief 确认 目的:给 Copilot「对话定位客户问题」的前端改造提供有出处的借鉴点,按「投入小、效果大」排序。 现状代码:apps/web/src/features/copilot.tsx(676 行)、apps/web/src/features/copilot-stream.ts、apps/web/src/features/copilot-composer.tsx、契约 packages/contracts/src/copilot.ts、协议 apps/api/src/domain/copilot-stream.ts。

0. 复用总判断(先看这个)

  • 本仓库没有 Tailwind/shadcn:apps/web 只有 next/react/swr/lucide-react(package.json),样式全在 apps/web/src/app/globals.css 手写 .copilot-* 类(:3282 起)。
  • 因此 assistant-ui、ai-elements、streamdown、vercel/chatbot 都不整包引入(它们依赖 Tailwind + shadcn CSS 变量,迁移成本 > 收益)。正确姿势:借交互结构和文案模式,在现有组件里手写;唯一建议新增的依赖是 react-markdown(见第 4 条)。
  • ai-elements 注意:README 顶部声明 2026-11 底迁移进 shadcn/ui,引用时按「模式参考」而非长期依赖对待。

候选项目与量级(GitHub API 实测,2026-11-10):

项目 stars 参考价值
open-webui 158,304 引用弹层、状态历史(多步过程)、错误态
LobeChat(lobehub) 84,848 思考折叠面板、自动滚动阈值、追问建议
vercel/chatbot(原 ai-chatbot) 21,042 Next.js 对话模板整体结构、多会话管理
assistant-ui 13,046 工具调用状态语义、ActionBar、Suggestion
microsoft/vscode-copilot-chat 9,939 请求步骤渐进披露、followup 数据流
streamdown 5,752 流式 Markdown 的「未闭合块」处理思路
react-markdown 15,936 可直接引入的渲染器
ai-elements 2,514 组件语义清单(message/reasoning/sources/tool/confirmation…)

借鉴点(按投入小→效果大排序)

1. 证据卡:区分「已观察事实 / 推测」,并带上证据时间与知识版本 —— 投入 ~1 小时

  • 出处:open-webui 引用实现 Citations.svelte:来源带相关度、点开是弹层,正文只留编号;ai-elements 的 sources 与 inline-citation 组件也是同样分工(正文内联编号 + 底部来源列表)。
  • 现状差距:copilot.tsx:21-36 的 Sources 只渲染 title + excerpt;契约里 CopilotSource.version(contracts/copilot.ts:7)、message.knowledgeVersion(:34)、message.createdAt(:29)字段都在、一个都没渲染。群规则要求「写明证据时间和缺失的证据」,现在做不到。
  • 改哪里:
    1. Sources 头部渲染「来源快照 · Wiki 版本 {knowledgeVersion 短 hash} · 回答于 {createdAt HH:mm}」(11px --wf-text-muted,对齐 docs/design/tokens.md)。
    2. 每条来源标题后加序号上标 [1],正文回答里的对应句子标同序号(纯文本方案即可,不做 hover 弹层)。
    3. 诊断结论渲染走已定稿的 CopilotMessage.diagnosis(contracts/copilot.ts:24-43,claude 11-10 落库),字段映射:verdict(problem=发现问题/expected=符合规则/insufficient=证据不足)画成结论徽标;facts[](text+evidenceId)画「已确认」,每条的时间取对应 evidence[].observedAt(服务端实测时间,勿用模型措辞);hypotheses[](text+confidence)画「可能原因」;missing[] 画「还缺的证据」。evidence[].available === false 必须画灰/警示,绝不能进「已确认」。恢复历史消息和流式中(card:'diagnosis')用同一组件。

2. 错误态分类:503 / 429 / 中断各说各话,不许显示成「正常」—— 投入 ~40 分钟

  • 出处:open-webui 在 ResponseMessage.svelte:886-954 把 message.error 作为一等状态与正常回答互斥渲染;assistant-ui 的工具/消息状态语义(running→incomplete→error,tools 文档)同样是「错误必须可见、可重试」。
  • 现状差距:前端 SSE 类型里 {type:'error'; code?: string}(copilot-stream.ts:17)声明了 code 但处理时丢弃(:108-109 只取 message);服务端协议(apps/api/src/domain/copilot-stream.ts:30)压根不发 code。docs/copilot.md:46 定义的 COPILOT_UNAVAILABLE(503) 只能靠裸文案看出来,客户容易把「服务不通」误读成「没问题」。
  • 改哪里(服务端 11-10 已落地,取值为 claude 定稿的枚举,见 docs/copilot-diagnostics-plan.md §4.1):error 帧带 code ∈ rate_limited(429) / upstream_unavailable(503/5xx) / upstream_refused(其他 4xx) / timeout / no_answer / not_configured / not_found / invalid_input / internal;前端 copilot-stream.ts 把 code 存进 state,StreamingAnswer(copilot.tsx:245-252)按 code 出文案:upstream_unavailable→「诊断服务暂不可用,这不是正常结果」;rate_limited→「查询太频繁,约 Xs 后可再试」。任何 error 帧都不得渲染成正常回答(Chief 转 claude 规则)。样式用 docs/design/tokens.md 1.2 的 Danger/Warning 底色。

3. 滚动:用户往上读时别硬拽回底部,加「回到底部」胶囊 —— 投入 ~30 分钟

  • 出处:LobeChat 的思考面板用 useAutoScroll({ threshold: 120 }) 控制跟滚(Thinking/index.tsx,滚动仅在阈值内生效);vercel/chatbot 的 conversation 组件也是「贴底才跟流」。
  • 现状差距:copilot.tsx:414-417 每个 delta 都无条件 scrollTop = scrollHeight,流式期间客户翻历史记录会被不断拽回。
  • 改哪里:CopilotPanel 里先判断 scrollHeight - scrollTop - clientHeight < 120 才自动滚;否则在 copilot-messages 底部悬一个「↓ 回到底部」小胶囊(新 CSS 类,走现有 token)。十几行改动。

4. 回答用 Markdown 渲染(日志、步骤、小代码块)—— 投入 ~1.5 小时

  • 出处:streamdown README(实测抓取):专为 AI 流式场景设计,处理「未闭合 Markdown 块」(remend)、GFM 表格、代码高亮、rehype-harden 安全渲染;它是 ai-elements message 组件的底座。但它要求 Tailwind @source 和 shadcn CSS 变量——本仓库没有 Tailwind,不直接装。
  • 现状差距:copilot.tsx 全文用 plainText()(:231、:277 等),Copilot 引日志片段、列复现步骤时全是糊在一起的一坨纯文本;docs/design/pages.md:38-47 线框里的编号列表/代码片段根本表达不出来。
  • 改哪里:apps/web 加依赖 react-markdown + remark-gfm(15.9k stars,无 Tailwind 依赖,输出 React 元素、不 innerHTML,XSS 面小)。渲染前仍先过现有 plainText 的源码路径/行号过滤——过滤逻辑绝不能随 markdown 化丢掉(docs/copilot.md:16 是客户可见范围的硬约束)。流式尾部按 streamdown 思路做简化处理:**、``` 未闭合时先按纯文本追加。样式在 globals.css 新增 .copilot-md(列表缩进、code 用 --wf-bg-subtle + 等宽栈)。思考折叠(:219-224)保持纯文本。

5. 工具调用「步骤列表」渐进披露,而不是一行覆盖一行 —— 投入 ~2 小时(前后端各一半)

  • 出处:assistant-ui 的 Tool Status API(实测抓取):每步 running/success/error + useToolArgsElapsed 耗时;open-webui 的 StatusHistory.svelte 把多阶段状态存成列表渲染(ResponseMessage.svelte:741 传入 statusHistory)。
  • 现状差距:SSE 已发 tool_use {name, progress}(apps/api:27),前端只把 progress 存成单个字符串、每步把上一步顶掉(copilot-stream.ts:107),name 直接丢弃。诊断要连查 nodes→pods→tasks→logs 四五步,客户只能看见最后一句,过程感为零。
  • 改哪里(服务端 11-10 已落地,帧结构见 docs/copilot-diagnostics-plan.md §4.1):每步两帧 tool_use{stepId, phase:'start'|'end', name, progress, outcome?, evidenceId?, observedAt?},outcome ∈ ok/missing/failed。前端把两帧按 stepId 收敛成 steps[],StreamingAnswer 默认一行(当前步 + LoaderCircle 转圈),完成后可展开「排查步骤(N)」:ok=✓、failed=✗、missing=灰/警示色,绝不画绿勾(证据没拿到不是好消息)。步骤列表不落库:刷新后历史消息只靠 diagnosis 卡恢复,无步骤条。

6. 消息操作条:复制结论 / 复制整条回答 —— 投入 ~20 分钟

  • 出处:assistant-ui 的 ActionBar primitive(copy/reload/edit 是标准件);vercel/chatbot 每条回答下有 actions 行。
  • 现状差距:全仓库没有任何复制按钮;而 docs/design/pages.md:54 线框明确画了「仅复制结论」——客户要把诊断结论贴回飞书群是主场景(Lark 的 case-1 就来自群聊)。
  • 改哪里:Message 完成态气泡尾部加 hover 显示的图标行(Copy/RefreshCw 已有 lucide):复制结论 = 复制 content;重试已有(:634)。navigator.clipboard.writeText + 「已复制」toast 文案,20 行内。

7. Grill-me 选项:选中即预览对目标的影响 —— 投入 ~30 分钟

  • 出处:ai-elements confirmation(执行前把「将发生什么」摆出来确认)与 assistant-ui suggestion 的「选一下 → 立刻反映到后续」语义。
  • 现状差距:copilot.tsx:160-177 的选项按钮选中后(168 行 selected 态),卡片其余部分毫无变化——goal/criteria 已经实时算好了(:100-101)却没展示,客户不知道点这个按钮会改变什么。
  • 改哪里:fieldset 下方加一行浅色预览「选这个后,需求目标会变成:…(新增验收标准:…)」;quickReplies(:329-337)保持现状即可,样式统一成 tokens.md 的胶囊。

8. Wish 草稿可编辑再提交 —— 投入 ~1 小时

  • 出处:assistant-ui 的 generative UI / form 语义(工具产出的确认卡允许用户改参数再放行,tools 文档);vercel/chatbot 的 artifact/编辑模式同理。
  • 现状差距:WishDraft(copilot.tsx:68-196)的目标和验收标准全是只读段落,客户只能原样提交或放弃;goal 短于 8 字时还靠 :111 自动拼前缀兜底,客户看不到拼完的样子。
  • 改哪里:goal / acceptanceCriteria 改成 textarea(默认值 = AI 草稿),提交用编辑后的值;校验沿用现有(≥8 字、非空)。契约不用动(copilotWishInput 已收 goal/criteria,contracts/copilot.ts:75-82)。

9. 空态与追问话术:引导客户给出任务 ID / 请求 ID —— 投入 ~20 分钟(文案级)

  • 出处:vercel/chatbot 的 prompt suggestions(空态胶囊 → 一键成句);LobeChat 空会话同样用可点问题引导。
  • 现状差距:copilot.tsx:610-624 空态已有 3 个 scene,但都不带信息量;docs/design/pages.md:127-129 要求空态说明「已挂载当前项目 Wiki 与集群只读监控」(该词仅内部线框用,对客户措辞见下)——现在客户不知道 Copilot 能查线上。Lark 已确认 case-1 的缺口正是没有 annotation-task ID 和 X-Request-ID(.wishforge/cases/case-1.md):客户不知道该给什么,Copilot 就只能瞎猜。
  • 改哪里:欢迎语加一句中性能力说明,如「我可以结合项目资料帮你排查问题,部分项目还能查线上运行情况和最近请求记录(只读)」——客户可见文案不出现「集群/Pod/命名空间」(claude 11-10 评审定;我原措辞带「集群」,作废);scene 里加一个「任务失败了,我告诉你任务编号」示例(点开带出输入模板「平台地址是 …,任务编号 …,现象是 …」,编号=浏览器地址栏里的那串);诊断拿不到 ID 时的追问也用同一话术。与 claude 的对话流程方案对齐,字段和文案以他为主。

与并行工作的接缝

  • 第 1/2/5/9 条涉及 SSE 帧与契约的新增可选字段(observations/inference、error.code、steps 帧),建议 claude 在 docs/copilot-diagnostics-plan.md 的契约节直接收编,避免两边各定一套。
  • 11-10 对齐结果:claude 方案已定契约加 CopilotMessage.diagnosis(结论/已确认/可能原因/还缺的证据),与本文第 1 条的「事实 vs 推测 + 缺证」是同一张卡——前端实现以 claude 契约节的字段名为准,本文第 1 条不再单独引入 observations/inference。第 2 条 error.code 与第 5 条 steps 帧仍需 claude 在 SSE 协议里落地,前端按此准备文案。
  • 第 4 条要新增 react-markdown + remark-gfm 两个依赖,Chief 已批准(11-10 群内);plainText 的路径过滤必须保留,这条 Chief 也点了名。
  • 全部改动只动 apps/web/src/features/copilot* + globals.css + packages/contracts,不碰执行器与部署。

核验记录

  • 现状行号均来自 git@review/overhaul 工作区实际文件(ops_read_files 全文读取);依赖缺失结论来自 apps/web/package.json 与 ls tailwind.config.*。
  • 仓库 stars/描述:GitHub API api.github.com/repos/... 实测(2026-11-10)。
  • streamdown/assistant-ui/open-webui/ai-elements 的行为描述:抓取对应 README 或源码原文(open-webui Citations.svelte、ResponseMessage.svelte:211/741/886/954;assistant-ui tools/status.mdx;LobeChat Thinking/index.tsx;ai-elements registry 实测:message/conversation/reasoning/sources/tool/suggestion/code-block/confirmation/inline-citation/task/prompt-input/attachments 均返回 200,response/actions/branch/web-search-result 返回 404——未引用)。

落地追踪(searcher 维护)

基线 2026-11-10 10:13 PT(复核 10:52 PT 首轮;11:05 PT 对 claude 评审 4+2 条修复二次核到代码行):git status apps/web 只有 auth.ts(第 1 阶段改动),以下 9 项全部未落地。Dev 每落地一项,searcher 收尾时逐项复核。

# 借鉴点 状态
1 证据卡:时间 + Wiki 版本 + diagnosis 渲染 ✅ 已落地(copilot.tsx:69-75 时间+版本、137-148 observedAt、180 missing 区、DiagnosisCard)
2 错误态分类(error.code:503/429/中断) ✅ 已落地(copilot-stream.ts:49 errorCode、:63-79 文案映射、:132 HTTP 层 code)
3 流式不硬拽底 + 「回到底部」 ✅ 已落地(copilot.tsx:793-810,120px 阈值+回到底部胶囊)
4 Markdown 渲染(react-markdown@10.1.0 + remark-gfm@4.0.1,先过滤后渲染) ✅ 已落地(SafeMarkdown :51-61 先 plainText 过滤再渲染,流式 :559 / 历史 :670 双入口)
5 工具步骤列表(steps) ✅ 已落地,评审问题已修:折叠行四分支图标 copilot.tsx:219-226;running→failed 四处调用 copilot-stream.ts:95/207/234/245
6 复制结论/回答 ✅ 已落地(:259-270 clipboard+「复制结论」)
7 Grill-me 选中即预览 ✅ 已落地(copilot-choice-preview :471-485)
8 Wish 草稿可编辑 ✅ 已落地(编辑草稿 :397)
9 空态引导任务 ID / X-Request-ID ✅ 已落地,评审问题已修:欢迎语无「集群」;快捷问题改为填入输入框模板(copilot.tsx:1036)