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

117 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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) |