# 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](https://github.com/open-webui/open-webui) | 158,304 | 引用弹层、状态历史(多步过程)、错误态 | | [LobeChat(lobehub)](https://github.com/lobehub/lobehub) | 84,848 | 思考折叠面板、自动滚动阈值、追问建议 | | [vercel/chatbot(原 ai-chatbot)](https://github.com/vercel/ai-chatbot) | 21,042 | Next.js 对话模板整体结构、多会话管理 | | [assistant-ui](https://github.com/assistant-ui/assistant-ui) | 13,046 | 工具调用状态语义、ActionBar、Suggestion | | [microsoft/vscode-copilot-chat](https://github.com/microsoft/vscode-copilot-chat) | 9,939 | 请求步骤渐进披露、followup 数据流 | | [streamdown](https://github.com/vercel/streamdown) | 5,752 | 流式 Markdown 的「未闭合块」处理思路 | | [react-markdown](https://github.com/remarkjs/react-markdown) | 15,936 | 可直接引入的渲染器 | | [ai-elements](https://github.com/vercel/ai-elements) | 2,514 | 组件语义清单(message/reasoning/sources/tool/confirmation…) | --- ## 借鉴点(按投入小→效果大排序) ### 1. 证据卡:区分「已观察事实 / 推测」,并带上证据时间与知识版本 —— 投入 ~1 小时 - **出处**:open-webui 引用实现 [`Citations.svelte`](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Messages/Citations.svelte):来源带相关度、点开是弹层,正文只留编号;ai-elements 的 [`sources`](https://elements.ai-sdk.dev/api/registry/sources.json) 与 [`inline-citation`](https://elements.ai-sdk.dev/api/registry/inline-citation.json) 组件也是同样分工(正文内联编号 + 底部来源列表)。 - **现状差距**:`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`](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Messages/ResponseMessage.svelte) 把 `message.error` 作为一等状态与正常回答互斥渲染;assistant-ui 的工具/消息状态语义(running→incomplete→error,[tools 文档](https://github.com/assistant-ui/assistant-ui/tree/main/apps/docs/content/docs/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`](https://github.com/lobehub/lobehub/blob/main/src/features/Conversation/components/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](https://github.com/vercel/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](https://github.com/assistant-ui/assistant-ui/blob/main/apps/docs/content/docs/(reference)/api-reference/tools/status.mdx)(实测抓取):每步 running/success/error + `useToolArgsElapsed` 耗时;open-webui 的 [`StatusHistory.svelte`](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Messages/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](https://github.com/assistant-ui/assistant-ui/blob/main/apps/docs/content/docs/primitives/action-bar.mdx)(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`](https://elements.ai-sdk.dev/api/registry/confirmation.json)(执行前把「将发生什么」摆出来确认)与 assistant-ui [`suggestion`](https://github.com/assistant-ui/assistant-ui/blob/main/apps/docs/content/docs/primitives/suggestion.mdx) 的「选一下 → 立刻反映到后续」语义。 - **现状差距**:`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 文档](https://github.com/assistant-ui/assistant-ui/tree/main/apps/docs/content/docs/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) |