tako 文档 GitHub

48 · 前端可用性欠账(界面走查 17 条现象 / 14 项修复)

性质:方案(2026-10-23 已点头,可施工)。 状态:🔶 方案已点头,施工中。台账在 tmp/48-前端可用性欠账/(不入库)。 验收结论(2026-10-23):两层全绿——快闸 3 条(TestContractWorkspaceFilesBytes / TestContractWorkspaceBodyBytes 等)、活体 core 层 27 步(新增「用例 12」文件清单、「用例 13」isDefault)、前端单测 7 条(npm test)、playwright 11 条(npm run test:e2e:冒烟 2 + 文件区 1 + 界面 6 + markdown/XSS/停止 2)。go test / go vet / npm run typecheck / npm run build / check-expected.sh / check-master-plan.sh 全绿。 2026-11-14 补充(doc/79,已落地):项目里的 .md 文件在两个入口都按 markdown 渲染显示,默认预览态、可切「原文」(对话页右侧文件标签 + 项目页文件列表)。排版样式抽成全局 .md-body 三处共用(scoped 样式不跨组件,抄不进别的组件);渲染复用 markdown.ts 那条既有管线(marked + DOMPurify),md 文件用 breaks: false、气泡仍 breaks: true。详见 §10。 落地过程中发现并修掉的 10 个问题(都是写完第一版复审时发现的,记在这里免得下次重犯):

  1. Vue 3 陷阱:p.x ?? (p.x = {...}) 的赋值表达式值是 raw 对象、不是 reactive proxy → 后续赋值绕过响应式 set 拦截器 → 数据进了内存、DOM 不更新。精确的触发条件是「赋值与改值之间隔着 await」:赋值标脏 → await 期间 Vue 渲染一次(读到当时的值)→ 之后的 raw 赋值不再标脏 → 界面停在 await 那会儿的样子。ProjectsView.vue 的 loadFiles 就栽在这(文件列表永远空白)。chat.ts 的 upsertQuestion(doc/47 的问答主界面)是同一个写法、但不是同一个 bug——它赋值后紧接着 push、中间没有 await,渲染发生在 push 之后,所以显示正常;仍改成「先判空再赋值、再读出来用」,是防将来有人在中间插 await。回归网:web/test/reactive-trap.test.ts(四条断言,含一条把「哪种形态会坏」钉死的对照)。
  2. .stage 缺 min-height: 0:窄屏下 .app 变 column 方向,flex item 默认 min-height:auto 不肯收缩 → .stage 被对话内容撑高 → body 溢出 126px、页面能滚 → 登录时聚焦密码框把页面滚下半截,顶部的导航全被推出视口(真实手机浏览器同样会这样)。
  3. scrollBottom() 在空列表时也滚:空态「从一句话开始」被推出视野(窄屏尤其明显)。改成空列表时 scrollTop = 0。
  4. 拆 form 后保存会连带提交别的卡片:在「模型」卡片点保存,会把「密钥」卡片里还没保存的编辑一起提交 —— 「各有各的保存」就名存实亡。改成:只提交本卡片的编辑,其余用服务端已保存的值(savedConfig)原样带回。
  5. 限宽用 width 不生效:.projects / .cfg / .stack 是 flex item(flex: 1 → flex-basis: 0%),width 会被顶掉 → 宽屏留白根本没修掉。改用 max-width。
  6. markdown 每次渲染都重算:v-html="renderSafe(b.text)" 在模板里,流式输出时每个 token 到达都要把所有气泡重新 parse + sanitize 一遍。加 v-memo="[b.text]"。
  7. .recent 在窄屏 grid 里没 grid-area:.rail 在 ≤860px 是 grid,不指定 area 它被自动放置到 nav 那一行,把 brand / 新对话 / 导航全挤没。
  8. 密钥 placeholder 被「显示」按钮挡住:那个按钮浮在输入框右侧,值框要留出右内边距。
  9. playwright 测试污染开发库:断言发的消息会在开发库留下会话。断言现在自己收尾删掉。
  10. 拆 form 的修复自己引入了一个新 bug:保存某张卡片后调 loadConfig() 全量重载,把用户在其它卡片里还没保存的编辑一起冲掉(在「密钥」卡片点保存 → 「模型」卡片里刚填的模型被覆盖回旧值 = 用户白填了)。改成:保存后只更新「已保存值」里刚提交的那一块,编辑框保持原样;已标记删除的行从表里移除(删除已生效,「撤销」无意义了)。回归网:web/e2e/ui.spec.ts 的「保存一张卡片不会冲掉另一张卡片里未保存的编辑」(旧行为下判红)。 另外修掉一个 17 条之外的问题(复审时发现的,不在本篇清单里):SSE 事件流的重连死循环——access token 过期 + 连接断开 + 页面静止三者同时成立时,前端每 3 秒拿过期 token 重连一次、服务端一律 401,引擎日志被刷满、事件流实际是死的。修法与对照实验见 doc/46 §7.5。 施工进度(2026-10-23):全部 17 拍已落地。

0. 背景与动机

0.1 这轮走查是怎么做的

2026-10-23 下午,在真实浏览器(本地 Vite + 引擎)里登录进去,把**四个页面(对话 / 项目 / 助手 / 团队)、两种视口宽度(1015px 与 1511px)**都走了一遍:真发消息、真让模型调工具跑一轮、真触发删除确认弹窗、真刷新页面验证会话恢复;再用只读 API 交叉核对了租户类型、项目归属与默认项目的服务端行为。17 条现象全部有当场证据,不是读代码推测的。

本篇要解决的是这 17 条里会让人用不下去或用错的那些。§1 把它们归并成 14 项修复(同一处代码、同一拍能改完的合并成一项),并给每项标了严重度。

0.2 用词的真身

本文反复用这几个词,先把它们的真身贴出来(后文不再解释):

词 真身(代码里的东西)
工作区(tenant) 租户。一个账号可以属于多个。侧边栏底部那个切换器切的就是它。GET /api/tenants
项目(workspace) 工作区下面的一层,id 形如 ws_01M5…。项目目录 = <workspace根>/tenants/<tid>/workspaces/<wid>/。GET /api/workspaces
会话(session) 一场对话,id 形如 s_01M5…。每场会话挂一个项目(doc/42 起没有游离会话)。GET /api/sessions
默认项目 每个成员自动有的那一个项目,名字叫「默认」,不可删(服务端回 409 114005)
run 一次「发一条消息 → 模型跑完」的执行。id 形如 r_01M5…
帧(frame) run 执行过程中流出来的一条事件。kind 词表八种:start/delta/usage/terminal/resume/task(doc/41)
落点 「这场新对话进哪个项目」。前端记在 localStorage['tako.workspaceId.<tid>']

0.3 病灶:同一个病,两副面孔

这 17 条里有 6 条是同一个病:后端的能力或契约早就在了,前端没有入口或没接上(A1、A2、A3、B1、C1、C4)。

病根不是「懒得做」,是没人把「后端有」和「页面能用」对过账。doc/44 补过一批(项目页 / 删除确认 / 子代理列表),补完的结论是「后端都有契约、前端都没有入口」;这轮走查证明那批补的是同一片区域里恰好被路过的三个洞,剩下的洞还在。

这副面孔还有第二张脸:doc/16 §2 表 #8 现在写着「登录 / 聊天 / 续传 / 停止 ✅」——而页面上根本没有停止按钮。 总纲是结论页,它那格现在写着假话。AGENTS.md 要求「产品能力状态翻转,同批更新 doc/16」——本篇的第一件事就是把这格改成真的。


1. 清单:17 条现象 → 14 项修复(4 个 loop)

严重度(按修复项计,共 14 项):P0 = 不修就用不下去 / 用错;P1 = 日常会被硌到;P2 = 观感与噪音。

表里 14 行,是从走查的 17 条现象归并来的:C4 把「个人工作区没有成员」与「三个『工作区』撞名」并成一项(同在团队/项目页、文案一起改);D4 把「内部术语」「文案绕」「只有一个响应式断点」并成一项(同属文案与响应式收尾)。17 是现象数,14 是修复项数,16 是 action 数(A1 与 B1 各拆成「先定契约」与「再接界面」两拍)。

# 问题 严重度 改哪一层 loop
A1 Markdown 完全不渲染(v6 契约违背) P0 前端 A
A2 对话页没有会话历史入口 P0 前端 A
A3 运行中没有「停止」按钮 P1 前端 A
A4 「子代理 0 / 展开」条常驻 P2 前端 A
A5 侧边栏工作区名被截断成 a7-envelope... P2 前端 A
B1 agent 产出的文件,用户拿不走 P0 前端 + 后端 B
C1 默认项目跟普通项目长得一样,删除必失败 P1 前端 + 后端 C
C2 密钥 •••• 是真实值,改一下就写成垃圾 P1 前端 C
C3 整个设置只有一个「保存」按钮,藏在最后一个卡片里 P1 前端 C
C4 「个人工作区没有成员」在 owner 视角下自相矛盾 P1 前端 C
D1 宽屏大面积无效留白 P2 前端 D
D2 助手页「说明」「工具名」是单行 input,长文本看不全 P2 前端 D
D3 会话列表把内部 session id 当主信息显示 P2 前端 D
D4 面向用户的文案混着内部术语;只有一个响应式断点 P2 前端 D

只有 B1 与 C1 要动后端,其余 12 项是纯前端。本篇不新增也不修改任何既有端点的请求/响应/帧字节,只新增 1 个端点(B1)、给 1 个响应体加 1 个字段(C1)。

2. Loop A · 对话面

对话页是唯一的高频页面,先修它。

A1 · Markdown 完全不渲染(P0 · 契约违背)

病灶。 doc/19-v6/19v6-03 第 118 行写着:「text 里的 \n 原样保留,客户端按 markdown 渲染,排版不受影响。」而 App.vue:932 是 <p v-if="b.text" class="bubble-text">{{ b.text }}</p>——纯文本插值,一个标签都不多。

实测(2026-10-23,模型被明确要求输出 markdown):回复里的 ## hello.txt 说明、| 属性 | 值 | 表格、```text 代码块、1. 2. 3. 列表、**加粗**,全部以字面符号显示。用户看到的是一堆管道符和井号。

为什么这件事是 P0 而不是「美化」。 模型输出 markdown 是这个系统的常态,不是意外:doc/19-v6-07 里 compact 摘要本身就是用 ## 槽头组织的 markdown 骨架;用户给模型的指令("整理成待办清单"、"写份说明")几乎必然引出 markdown。现在每一轮对话都在把模型的结构化输出退化成符号噪音,用户要自己把 | 和 --- 翻译回表格。而且这不是"少实现一个功能",是v6 文档写明的渲染责任从来没被实现——按 AGENTS.md「与代码冲突时先判断哪一边过期」,这里过期的是代码。

做什么。

  1. 新增 web/src/markdown.ts,导出三个函数:

    导出 做什么 碰 DOM 吗
    renderMarkdown(text): string marked.parse(text) → HTML 字符串 否(纯函数)
    sanitizeHtml(html): string DOMPurify.sanitize(html) 是
    renderSafe(text): string 前两者串起来 是(浏览器里跑)
  2. 依赖装两个:marked@18.1.1 + dompurify@3.4.17(选型出处见下)。

  3. App.vue 的气泡正文从 {{ b.text }} 改成 v-html="renderSafe(b.text)"。

  4. 样式:给 .bubble-text 补 markdown 元素的排版规则(标题字号、表格边框、代码块底色、列表缩进、行内代码底色)。

为什么是 marked + dompurify(选型出处,不是拍脑袋)。 参照仓库里三家同类产品的现成选型:

参考实现 markdown 库 消毒
pi(ref-agent/pi,TS agent,doc/16 §2b 的主要参考) marked@18.0.11(TUI + coding-agent) —
opencode(ref-agent/opencode) marked@18.0.11 dompurify@3.4.14
WeKnora(ref-agent/WeKnora,Vue 聊天) marked@^17.0.5 dompurify@^3.4.11

三家全部是 marked,没有一家用 markdown-it。 而且 marked 的 sanitize 选项早已废弃(官方指引:改用 DOMPurify),所以「marked + DOMPurify」是这对库的现代标准写法——三家做法一致不是巧合,是这条路已经被走通了。

doc/16 §1 的借鉴纪律说「抄『问题本质』不抄『历史包袱』」。这里的「问题本质」是**「用成熟解析器 + 成熟消毒器」,不是「用哪个包」——所以照抄这个组合**是对的,不是抄历史包袱。

版本取当前最新(2026-10-23 查 npm registry):marked 18.1.1(三家参考实现都钉在 18.0.x,同一大版本)、dompurify 3.4.17。

代价与好处。 代价:多一个依赖(DOMPurify 约 20KB min+gzip),且它是 DOM-only 的(Node 里跑要 jsdom)。好处:与三家参考实现一致(出问题时有人可对照)、marked 的 GFM 表格/任务列表/代码块开箱即用、生态成熟。

这个代价怎么绕开。 上表里 renderMarkdown 不碰 DOM → node --test 直接测它,不需要为测试额外引 jsdom;而「<script> 会不会被执行」这条 XSS 断言放到 playwright 浏览器里测(浏览器才是 DOMPurify 的真实运行环境)。

每一步的输入输出。 输入 = 气泡里的 b.text 原始字符串(runlog 里的原话,服务端一个字都不改);输出 = 一段 HTML 字符串,交给 v-html。

没它会怎样。 已在 §0.3 讲透:模型所有结构化输出退化成符号噪音。

一个必须一起处理的坑。 b.text 里还可能夹着 media 占位行([media seq=… path=… mime=… size=…B sha=…;…])。现在这些行是被 parseMedia 剥掉的(api.ts 的 parseMedia 过滤掉占位行、留下正文),所以渲染的输入已经是剥干净的正文,不含占位行。改造时不要把整条 runlog 原文直接喂给渲染器——那会把占位行当普通文本渲染出来。

验收。 机器断言用 Node 内置 test runner(零新依赖,Node 22 自带 --experimental-strip-types + node:test)钉住渲染输出:

cd yk-tako-eino/web && node --experimental-strip-types --test src/markdown.test.ts

期望字节(node --test 钉住 renderMarkdown 的输出):

输入 期望输出包含
## 标题 <h2>标题</h2>
- a\n- b <ul> 且含 <li>a</li>
| a | b |\n| --- | --- |\n| 1 | 2 | <table> 且含 <th>a</th> <td>1</td>
```text\nx\n``` <pre><code class="language-text">
**粗** <strong>粗</strong>

XSS 那条要单独说清楚:marked 本身不转义原始 HTML(它会原样输出 <script>)——这正是必须配 DOMPurify 的原因。所以 <script>alert(1)</script> 这一条不能在 node 里断言(node 里没有 DOMPurify),要放到 playwright:发一条含 <script> 的消息 → 断言页面把它当文字显示、window.alert 未被调用。

这个分工是刻意的:结构在 node 里测(快、零依赖),执行在浏览器里测(真实环境)。

浏览器活体(人工):发一条要 markdown 的消息,回复里标题有层级、表格有边框、代码块有底色。

A2 · 对话页没有会话历史入口(P0)

先说清楚不动的部分(用户 2026-10-23 表态:「很多 agent 都是项目下面挂着对话」)。 「会话挂在项目下」这个数据结构保留不动——sessions.workspace_id 这一列不动、项目页的树形结构不动、GET /api/sessions?workspaceId= 不动。本条要补的只是一个直接回到旧对话的入口:结构照旧挂在项目下,但用户不必先想到「是哪个项目」才能回去。

病灶。 侧边栏只有「对话 / 项目 / 助手 / 团队」四个按钮,没有任何会话列表。想回到上一场对话,路径是:点「项目」→ 找到那个项目 → 点「查看对话」展开 → 在两场会话里靠标题认 → 点「打开」。而标题是模型用首句生成的,不是用户起的名。实测那个项目里两场会话叫「说一句 ho」「说一句 hi」——用户拿这两行字认不出哪场是昨天那场。

关键事实(决定了这条有多便宜)。 GET /api/sessions 不带 workspaceId 时就列本人的全部会话(跨项目)——server.go:780 的 listSessions 只在 workspaceId 非空时才校验项目可见性,否则 ListSessions(ctx, p, scope, "") 返回本人全部会话。前端 api.ts 的 listSessions(workspaceId?) 早就能这么调,只是 ProjectsView 永远带着 workspaceId 调。

所以 A2 是纯前端改动,零后端。

做什么。

  1. 侧边栏 rail 的导航(.nav)下面加一个「最近会话」区,标题写「最近会话」。
  2. 数据:GET /api/sessions(不带参数),按 createdAt 倒序取最近 10 场,每行显示会话标题(空标题显示「未命名对话」)+ 时间(toLocaleString('zh-CN', {dateStyle:'short', timeStyle:'short'}))。
  3. 点一行 = 打开那场会话。复用现成的 openSession(id)(chat.ts 已导出,ProjectsView 的「打开」按钮就是调它)。
  4. 当前正在看的那场会话,在列表里高亮。
  5. 列表底部一行「在项目页里看全部 →」,跳到项目页。

为什么是「最近 10 场」而不是完整树。 对话页最常见的需求是「回到刚才那场」,不是「找三个月前某场」。完整树放在项目页(已有)。这两者不重复:一个是快捷回跳,一个是归档检索。

输入从哪 / 输出到哪。 输入 = GET /api/sessions 的 sessions[]({id,title,createdAt,workspaceId});输出 = 侧边栏 10 行;点击 = 调 openSession(id) → 它走 reconcile() 重建对话(已验证可用:实测从项目页「打开」旧会话,历史完整回来了)。

没它会怎样。 用户每次想回到上一场对话,都要先猜项目名、再在会话标题里认字。

验收。 浏览器活体(两个窗口交叉核对):

窗口 A(浏览器):登录 → 对话页 → 侧边栏应出现「最近会话」区,列出 ≥3 场(按时间倒序)
窗口 B(终端):curl -s -H "Authorization: Bearer $TOK" "$BASE/api/sessions" | jq -c '.data.sessions[0]'

期望:窗口 A 列表第一行的标题与窗口 B 的 sessions[0].title 逐字相同(时间倒序必须对)。点第一行 → 对话区出现那场会话的历史气泡。

A3 · 运行中没有「停止」按钮(P1)

病灶。 引擎有 POST /api/runs/:runId/stop(server.go:75,doc/17 §4 手动停止,带条件 UPDATE 竞态裁决 + 跨副本 cancel)。前端一次都没调过。用户让模型干一件耗时的活,做到一半发现方向错了,唯一的办法是刷新页面——那场 run 还在服务端跑着,token 还在烧。

做什么。

  1. api.ts 加 stopRun(runId: string): Promise<{ status: string }>(走现成的 request(),信封统一)。
  2. chat.ts 加 stopCurrent():拿当前 busy 那条气泡的 runId 调 stopRun;成功后把该气泡 state 置 'stopped'(chat.ts 的 closeOut 已有 stopped 分支,App.vue:947 已有「已停止,没有写进历史」的文案,不用新写文案)。
  3. App.vue 的 composer 栏:busy 为真时,把状态提示「正在回复」换成「正在回复 · 停止」按钮;点了就调 stopCurrent(),按钮进入 disabled + 「正在停止…」。
  4. 排队中(pending.length)不显示停止——那不是 run,是本地队列(chat.ts 的 pump)。

每一步的输入输出。 输入 = 气泡上的 b.runId;输出 = 服务端把 run 标成 stopped → 前端把那条气泡渲染成「已停止,没有写进历史」。

没它会怎样。 方向错了只能刷新;正在跑的那场 run 继续烧 token,用户还以为它停了。

验收。 浏览器活体:

窗口 A(浏览器):发一条要跑很久的请求 → 状态栏出现「停止」按钮 → 点它
窗口 B(终端):curl -s -X POST -H "Authorization: Bearer $TOK" "$BASE/api/runs/$RID/stop" | jq -c .

期望:窗口 A 的气泡变成「已停止,没有写进历史」;窗口 B 在 A 点之前调会回 {"code":0,…,"data":{"status":"stopped"}}(幂等:A 已经停过再调一次仍回 stopped,不报错)。

补记(2026-11-03,生产验收后修的一轮)。 上线后用户报「当前会话找不到停止按钮」。排查下来不是样式问题,是三处真实缺口:

  1. 按钮只认本实例的忙态。 busy 由本页的投递(deliver)和轮询(pollFrames)置位。同一场 run 若是另一个标签页 / 另一台设备发起的,本页没有轮询者,busy 一直是 false,按钮根本不渲染——可这场 run 确实在烧 token。用户看到的正是这一条。
  2. busy 是布尔开关,多个写者互相覆盖。 投递与每个轮询者各自在 finally 里把它置 false,先结束的一轮会把仍在跑的那轮按钮一起关掉。同一场 run 还会被 reconcile 与投递各起一个轮询者:画两个 streaming 气泡,问答面板随之出现「2 / 2」。
  3. stopError 只写不读。 点停止失败时页面毫无变化,看起来跟「没有停止能力」一模一样。

修法(chat.ts + App.vue):chat.ts 增加会话级 liveRunId——值来自 getSession(sid).liveRunId,在 gateIdle、投递成功、轮询、reconcile 处记录;页面可见且空闲时每 5 秒跑一次 probeLive 兜底,发现本实例不认识的活 run 就接管帧面(从 offset 0 起拉,与 reconcile 同一套),并给出停止入口。busy 改成持有者计数(holdBusy/releaseBusy),pollingRuns 保证同一 run 只有一个轮询者,delivering 让 reconcile 认出「这一轮是我自己的」不再重放。App.vue 的 canStop = 有 liveRunId,或任一 streaming/offline 气泡带 runId;stopCurrent 依次按 target.runId → 气泡 runId → liveRunId 取目标;runId 还没回来(投递在飞)时按钮显示「正在启动…」并禁用;stopError 在输入栏与提问面板都渲染出来。

验收(2026-11-03,PRD)。 四场活体全过:当前会话自己发起的 run(按钮出现、点击后气泡变「已停止,没有写进历史」)、另一台设备打开同一会话(3 秒内出现可点的「停止」,点了之后发起端同步变 stopped)、刷新时 run 仍活着(刷新后按钮仍在并可停)、ask_user 等待面板(面板里的停止按钮可点,点了面板消失、气泡变 stopped)。

移动端一轮(2026-11-03,390×844 与 320×844 实测)。 上一批修完停止能力后,按手机视口量了一轮,四处不是审美问题、是能测出来的缺陷:

  1. 每个气泡底部多一条空行。 .bubble-main 的 white-space: pre-wrap 被 .bubble-text 继承,markdown 渲染出的结尾换行被当成一行画出来:一行文字的气泡实测 54.6px,而它自己的行高只有 24.75px。改成 .bubble-text { white-space: normal }(marked 开了 breaks: true,用户手打的换行仍由 <br> 保留)。修后同一气泡正文 24.8px、整块 59–61px。
  2. 长工具卡摘要和宽表格把气泡撑出视口。 flex item 默认 min-width: auto,内容不肯收缩:ask_user 卡片的参数串直接顶到屏幕外,8 列表格把整页撑宽(document.scrollWidth 跟视口一样,右侧根本滚不到)。给 .bubble-main / .tool-cards 加 min-width: 0,.tool-name 改成 flex: 1 1 0 + 省略号;markdown 的表格在 markdown.ts 里套一层 <div class="table-scroll">(markdown.test.ts 加断言),窄屏时只有表格横向滚。修后 390/320 两种视口 docScrollW 都等于视口宽,表格 scrollWidth 353 > clientWidth 330。
  3. 触屏尺寸与 iOS 缩放。 ≤860px:输入框 16px(低于 16px 时 iOS 聚焦会放大整页)、发送/附件/菜单/新对话 36px、会话行 40px、提问选项最小 44px;.list 加 overscroll-behavior: contain(滚到头不把整页拉出回弹)。
  4. 提问面板 footer 在 320px 挤成两行。 「数字键选择 · Enter 提交 · Shift+Enter 换行」是键盘说明,手机上没意义还占行;≤480px 隐藏 .ask-hint、按钮右对齐,dock 内边距同时收紧。
  5. 停止失败提示被手机端规则误藏。 ≤860px 有一条「只留正在回复/排队提示」的规则 .hint:not(.live):not(.queue){display:none},.hint.stop-fail 也命中——手机上点了停止失败依旧毫无反馈,与本篇开头修的问题同形。选择器补 :not(.stop-fail)。
  6. #app 高度改 100dvh,地址栏收起/展开时不再多出一截滚动。

验收:npm run typecheck、node --experimental-strip-types --test test/markdown.test.ts 11/11、npm run build 均过;以上 1–6 的数值均为 390×844 / 320×844 Playwright 移动视口实测。

流式反馈一轮(2026-11-04,390×844 实测)。 用户报「回复不是一个字一个字出的,会停一段时间突然出一段,停的时候也不知道它在干嘛」。量下来是两件事叠在一起:

  1. 源头不是问题。 引擎把厂商 chunk 逐条压成 delta 帧(一帧 1–3 字,中位间隔 0ms、均值 7ms,一轮 782 字共 522 帧);SSE 通道同样以 ~150ms、每批 25–66 字送达。停顿发生在两个地方:模型首字之前(TTFT 2.2–3.8s),以及工具执行期间(bash sleep 6 实测算工具卡 1.4s 出现、之后 5.8s 页面没有任何变化)。
  2. 前端 400ms 一拉、一拉一刷。 POLL_MS = 400 把 ~90 字攒成一次 DOM 更新,所以看到的是「停一下、出一段」;空等时页面上只有三个点,没有任何阶段或时长信息。

修法两拍(纯前端,不动帧与端点):

实测(同一模型同一提示):正文刷新间隔中位 162ms、每次 25 字(改前 ~400ms / ~90 字);bash sleep 6 一轮里空拍 407–423ms、有帧拍 156–164ms,session 核对间隔 2.1s / 2.1s / 1.8s。npm run typecheck 通过。

输入框高度可拖动(2026-11-04)。 长提示词超过 168px 就只能在框内滚。卡片上沿正中加一条白色短条(20px 透明热区包 5px 条,cursor: ns-resize):按住上下拖改输入框高度,双击复位成自动高度;上限 min(480px, 55% 视口高),拖到 48px 以下视为回到自动。拖出来的高度是 min-height,叠在原有自动增高之上(没拖过仍 168px 封顶,拖过后封顶抬到用户定的那档);选择存本机 localStorage['tako.composer.minHeight'],不入库。验收:两视口拖 120px 高度 +120、重载保持、双击回基线、拖后输 8 行仍自动长高,390 无横向溢出;npm run typecheck 通过。

A4 · 「子代理 0 / 展开」条常驻(P2)

病灶。 对话区顶部常驻一条「子代理 0 / 展开」(App.vue:868,v-if="sessionId" 就显示)。没有子代理时它占一行,还带着一个「展开」按钮诱导用户去点空的。实测每一轮对话、每一个会话,这张条都在。

做什么。 改成有子代理才显示:v-if="sessionId && (subagents.length || subagentsLoading || subagentsError)"。「展开 / 收起」两个按钮保留(subagentsOpen 状态不动)。加载中与出错时仍要显示(否则用户点了「展开」看到空白,不知道是加载中还是真没有)。

没它会怎样。 每轮对话顶部多一行噪音,并训练用户去点一个永远空的开关。

验收。 浏览器活体:新会话(没有子代理)→ 对话区顶部不出现「子代理」字样;展开过的会话仍然能列出子代理。

A5 · 侧边栏工作区名被截断(P2)

病灶。 侧边栏底部的当前工作区名显示成 a7-envelope...(省略号截断)。这个名字是用户区分「我现在在哪个工作区」的唯一标识——多开一个工作区后,截断成 a7-envelope... 和 a7-envelope-t... 的两个工作区在界面上分不出来。

为什么会被截断。 侧边栏宽 15.5rem(248px),底部一行挤着:头像(30px)+ 工作区名 + 箭头(14px)+ 「退出」(45px)。留给名字的只有 96px 左右,a7-envelope-test(15 个字符)放不下。

做什么(按代价从低到高,三选一,方案里定第 1 个)。

  1. (推荐,纯 CSS) 名字超长时不截断,改成两行,并给 .who 加 min-width: 0 + word-break: break-all;.switcher-btn 的 title 属性放全名,鼠标悬停可见。同时把「退出」按钮挪到头像的右侧(或收进工作区切换菜单里),把宽度还给名字。
  2. 缩短「退出」为图标按钮(可读性换宽度)。
  3. 侧边栏加宽到 17rem(影响所有页面,不推荐)。

没它会怎样。 多工作区场景下用户分不清自己在哪。

验收。 浏览器活体:侧边栏底部的工作区名完整可见(不出现 …);名字超长时换行显示且不撑破侧边栏。

3. Loop B · 产出可达

B1 · agent 产出的文件,用户拿不走(P0)

病灶。 用户让模型「把结果写成 report.md」,模型说写好了。然后没有然后:

agent 干完活,成果锁在服务端目录里,用户唯一能带走的是模型复述的那段话。

关键事实(决定了这条要多少工作量)。 getMedia(server.go:1278)的 path 形如 workspaces/<wid>/<相对路径>:它先 parseSessionMediaPath 拆出 wid,再 VisibleWorkspace 校验项目可见性,然后把 root 设成项目目录、rel 设成 wid 之后的相对路径,最后过 resolveInWorkspace 那把围栏。也就是说 GET /api/media?path=workspaces/<wid>/report.md 今天就能读到 agent 写出的文件。

所以 B1 缺的只有两样:① 一个「列目录」端点;② 前端的一个入口。 字节取用复用现成的 GET /api/media,不新开下载端点。

做什么。

① 后端新增一个端点(本篇唯一的全新端点):

GET /api/workspaces/:id/files?path=<相对路径,默认 ".">

② 前端(2026-10-23 已落地,web/src/ProjectsView.vue):

③ .media/ 的可达性(2026-10-23 已查清,开放项关闭)。 「内部目录不列」会让 .media/ 里的入口图片从文件浏览器里消失。查了落盘口径(media.go:69):.media/ 里只有用户上传的入口图,文件名是内容寻址的 sha256[:16] + 扩展名(没有原名);模型产出的图不走这里(模型自己 write_file 写进项目目录)。而入口图在聊天气泡里全部能看(App.vue 的 <img class="bubble-media">)。→ 不列 .media/ 不会让用户失去任何入口,这一条不用再改。

每一步的输入输出。

没它会怎样。 agent 的产出不可达。这个产品的价值主张是「agent 帮你把活干完」,干完的东西拿不走,价值就断在最后一步。

验收。

# 1) 新端点(这个 action 的契约拍)
curl -s -H "Authorization: Bearer $TOK" "$BASE/api/workspaces/$WID/files?path=." | jq -c .
# 期望:{"code":0,"message":"","data":{"path":".","entries":[...]}}

# 2) 越界挡死
curl -s -H "Authorization: Bearer $TOK" "$BASE/api/workspaces/$WID/files?path=../../etc" | jq -c .
# 期望:{"code":111002,"message":"路径不对","data":null}

# 3) 看不见的项目
curl -s -H "Authorization: Bearer $TOK" "$BASE/api/workspaces/$WID_NOWHERE/files" | jq -c .
# 期望:{"code":114001,"message":"找不到这个项目","data":null}

字节断言进 scripts/acceptance/expected.json(新用例「用例 12」——用例 10 已被 doc/47 的人审问答码段占用,编号不能撞)+ doc/19-v6/19v6-04-验收-curl.md 散文版同批改,check-expected.sh 守两边一致。

为了让机器断言能造出「目录里有文件」这个前提,断言器加了一个步骤 op=seed_ws(往项目目录里造文件/目录/符号链接——产出文件在文件系统上,SQL 造不出来);项目目录布局 = <workspace根>/tenants/<tid>/workspaces/<wid>/,workspace 根由新环境变量 TAKO_WS_ROOT 给(默认 <仓库根>/tmp/workspace-acc)。

4. Loop C · 破坏性操作与文案

C1 · 默认项目跟普通项目长得一样(P1)

病灶。 系统「默认」项目在项目页里跟用户自己建的项目完全一样:有「删除」按钮、有改名按钮。点删除,弹窗先许愿:

「"默认"会被删除。项目里的 2 场对话会一起删除(保留窗口内仍可恢复)。项目目录里的文件会清掉。」

用户读完这段会以为文件要没了、点了「删除」,等来一句错误——服务端 auth.go:169 的 codeWorkspaceDefault = 114005 必然拒绝(我核对过服务端实现)。

为什么前端不知道哪个是默认项目。 api.ts 的 Workspace 类型注释写得很直白:「默认项目不单独标 isDefault,删除时靠 409 message。」于是前端只能等点了才知道删不掉。

做什么。

  1. 后端:GET /api/workspaces 的每个 workspace 对象加一个字段 "isDefault": bool(默认项目为 true)。加字段不改既有字段,是增量,不是契约翻转——但仍是字节变更,所以要进 expected.json + 19v6-04 同批改。
  2. 前端:
    • api.ts 的 Workspace 类型加 isDefault?: boolean。
    • 项目页:默认项目不渲染「删除」按钮(改成一句静态说明「默认项目不能删除」),「重命名」也去掉(改名默认项目没有意义,且会让用户失去「这是默认项目」的视觉标识)。
    • 项目名后面加一个「默认」徽标(跟「新对话落点」徽标同款样式)。
    • 「新对话落点」那一行的文案:「默认项目」改成「默认」,跟列表里的项目名对上(见 C4)。
  3. 保留后端 409 作为兜底(前端隐藏按钮不等于后端放松;老前端、直接 curl 仍要撞 409)。

没它会怎样。 每个新用户第一次进项目页,都会看到「删除」按钮加一段会清空文件的许诺,然后失败一次。

验收。 字节:GET /api/workspaces 的 workspaces[] 里默认项目那一项含 "isDefault":true,其余含 "isDefault":false;浏览器:默认项目卡片上没有「删除」按钮,有「默认」徽标。

C2 · 密钥 •••• 是真实值,改一下就写成垃圾(P1)

病灶。 Configure.vue:255 把密钥值设成字面量 '••••' 存进 row.value,同时 row.masked = true。用户在那个输入框里改字时,@input 只做 row.masked = false(Configure.vue:493),不会清掉已有的 '••••' 占位符。用户手一抖就是在 •••• 后面续写,保存进去的密钥变成 ••••sk-xxxx——带占位符前缀的垃圾值,这把密钥就此失效。

还有两条并行的删除路径:文案只说了「把格子清空再保存,会删掉它」,但界面上还有一个「移除」按钮(Configure.vue:494)直接 splice 掉那一行、没有任何确认。用户以为「移除」只是把它从列表里拿走,保存后它真的被删了。

做什么。

  1. 密钥值不再是输入框里的真实值。 改成 type="password" 的输入框 + 一个独立的「显示/隐藏」按钮(像登录页的密码框那样,App.vue:842 已有这个模式,直接抄)。
    • 服务端返回 •••• 时:输入框留空,placeholder 写「已保存(留空则不改动)」。
    • 用户输入了内容 → masked = false,保存时用用户输入的值。
    • 用户没输入 → 保存时传 ••••(服务端认这个占位符、保留原值)。
    • 这样「输入框里有什么」与「保存什么」永远是同一件事,占位符永远进不了真实值。
  2. 「移除」改名为「删除这把密钥」,并加二次确认(复用现成的 ConfirmDialog.vue):「删掉 DEEPSEEK_API_KEY?保存后这把密钥不再可用,模型调用会失败。」
  3. 「清空格子删除」这条路径取消(已拍,2026-10-23)。因为 1 改完后,「清空」和「输入新值」不再能靠「格子是不是空的」区分了。所以:
    • 输入框留空 = 不改动(不是删除);
    • 点「删除这把密钥」= 删除。
    • 一个输入框的「空」只该有一种含义。文案改成:「留空表示不改动;要删除请点删除按钮。」
  4. originalSecrets 那段「删除的行在保存时写 ''」的逻辑(Configure.vue:283)同步改成「只有显式点删除的行才写 ''」。

每一步的输入输出。 输入 = 用户在输入框里敲的字符(空 / 非空);输出 = 保存请求里 secrets[name] 的值(非空=用户值;••••=不改;''=删除)。

没它会怎样。 用户改一把密钥,改完就再也调不动模型了,而且看不出是哪一步坏的(前端显示保存成功)。

验收。 浏览器活体 + 字节交叉核对:

窗口 A(浏览器):团队 → 设置 → 密钥 → 在 DEEPSEEK_API_KEY 的值框里输入 sk-test123 → 保存
窗口 B(终端):curl -s -H "Authorization: Bearer $TOK" "$BASE/api/tenants/$TID/runtime-config" | jq -c '.data.config.secrets'

期望:窗口 B 里 DEEPSEEK_API_KEY 的值不含 •••• 前缀(今天会返回 ••••sk-test123,这是 bug 的证据)。

C3 · 一个表单,一个保存按钮,藏在最后一个卡片里(P1)

病灶。 模型、密钥、MCP 三块共用一个 <form>(Configure.vue:481),「保存」按钮只出现在「自定义 MCP」卡片底部(Configure.vue:517)。用户改了个默认模型,要滚到页面最下面才找得到保存。而且「测试连接」按钮紧挨着表单内容,用户理所当然认为它测的是正在编辑的内容——而它测的是服务端已存的配置(testMcp 打 GET /api/mcp-status,读的是库里的配置)。

做什么。

  1. 每个卡片自带自己的「保存」。拆成三个独立的 <form>(模型 / 密钥 / MCP),各自一个保存按钮,卡片底部。
    • 「密钥」和「模型」的保存只提交自己那部分字段。
    • 「自定义 MCP」的保存只提交 mcpServers +(可选)测试。
    • 服务端 PUT /api/tenants/:id/runtime-config 是整体 PUT(Configure.vue:301),所以拆 form 后,前端在提交某一块时要带上其它块的当前值(不然整份配置被覆盖成空)。实现上:保留一份 cfg 状态,各卡片保存时组装完整请求体再 PUT。
  2. 「测试连接」挪到 MCP 卡片的顶部,并改名为「测试已保存的配置」。或者:改成测当前编辑内容——这需要后端给「未保存的 MCP 配置」开一个试连入口(后端加端点,超出本篇范围,不做)。所以本篇采用改名 + 挪位。
  3. 保存后不再自动 testMcp()(Configure.vue:313)——保存完自动测一次连接,会让保存这个动作变慢且可能拉起 MCP 子进程。改成保存成功后提示「已保存」。

没它会怎样。 用户改了模型但没找到保存 → 以为改了其实没改;或者点了「测试连接」看到「连接失败」,实际失败的是旧配置。

验收。 浏览器活体:改「默认模型」→ 不滚动就能看到「模型」卡片里的保存按钮 → 点它 → 刷新页面,模型仍是新值;改 MCP 但不保存 → 点「测试已保存的配置」→ 报的是旧配置的连接状态(且按钮文案明确写着「已保存的」)。

C4 · 「个人工作区没有成员」在 owner 视角下自相矛盾(P1)

病灶。 实测:当前租户 a7-envelope-test,kind=personal,而当前用户角色是 owner(侧边栏底部就写着「所有者」)。点「团队 → 成员」,整页只有一句:

个人工作区没有成员

「你就是所有者,怎么可能没有成员」——这句话是写给「个人租户不搞成员制」这个实现事实的,不是写给用户的。用户会当成 bug。

再往上一层:概念撞名。 同一个界面体系里,「工作区」这个词同时指三样东西:

出现在哪 指什么 用户看到的样子
侧边栏切换器 tenant 「a7-envelope-test / 所有者」
团队页 tenant 「个人工作区没有成员」
项目页顶部 workspace(没选时) 「新对话落点:默认项目」
项目页列表 workspace 一个真名叫「默认」的项目

于是页面上同时出现「默认项目」和「默认」两个词,分处两地,用户得靠猜知道是一回事。

做什么。

  1. 成员页文案改成人话:个人租户时显示「这是你一个人的工作区,不需要邀请成员。」(而不是「个人工作区没有成员」)。加一句说明「要和人一起用,建一个团队工作区」+ 一个「+ 创建团队工作区」按钮(后端 POST /api/tenants 已存在,前端切换器里已有「+ 创建工作区」入口,见 App.vue:806)。
  2. 「个人工作区」这个词在界面上统一改成「个人工作区」→ 用户自己的那一个叫「我的工作区」。具体:
    • 团队页成员 tab:个人工作区没有成员 → 这是你一个人的工作区(+ 上面那句说明)。
    • 切换器里的 kindLabel('personal') 返回的「个人」标签 → 「我的」。
  3. 「默认项目」→「默认」(项目页「新对话落点」那一行),跟列表里的项目名对齐。
  4. 项目页顶部那行「新对话落点」改名为「新对话默认进入」——「落点」是内部词。

没它会怎样。 新用户第一次点「团队」,看到一句自相矛盾的话;项目页上「默认项目」和「默认」两个词让人怀疑自己看错了。

验收。 浏览器活体:个人租户 → 团队 → 成员 → 看到「这是你一个人的工作区」;项目页 → 「新对话默认进入:默认」。

5. Loop D · 观感

这一组不改变任何行为,只改呈现。四条一起做,作为一个「界面整理」action。

D1 · 宽屏大面积无效留白

病灶(实测 1511px 视口)。 项目页:「新建项目」的输入框宽 1400px;「新对话落点」卡片横跨全宽,里面只有左端 6 个字;项目卡片上项目名在左、按钮在最右,中间 1500px 全空。设置页:「设置 / 成员」两个 tab 挤在左上角,右侧 1800px 全空。

做什么。 给内容区加最大宽度(建议 72rem ≈ 1152px)并居中:项目页、设置页、成员页的 .projects / .cfg / .stack 外层加 max-width + margin: 0 auto。项目卡片内部改成「标题在上、操作在下」的两行布局(或者标题与按钮同排但限宽到 60rem 内)。对话页的 .thread 当时是 min(46rem, …),不动。2026-11-03 用户翻案(doc/47 §5.5):对话列不再限宽,铺满内容区左右各留 1.5rem;doc/51 的 720px 规格同批改。

D2 · 助手页长文本被裁

病灶。 助手编辑器的「说明」和「工具名」是单行 <input>(Configure.vue:442、Configure.vue:458)。「说明」的真身是一整段话(coder 的说明有 80+ 字),「工具名」是 7 个工具名的逗号串。两者在 280px 宽的框里都被裁掉尾部,用户看不到自己写的是什么。规格 textarea 底部还出现「半行文字被切一半」的观感(rows="12" 但容器高度不够,最后一行被裁)。

做什么。 「说明」改 <textarea rows="3">;「工具名」改 <textarea rows="2">(本来就该容得下多行);「规格」textarea 的 rows 与容器高度对齐(改成 rows="16" 并给 min-height,让行完整不裁)。

D3 · 会话列表把内部 id 当主信息

病灶。 项目页展开后的会话行,第二行是「2026年10月22日 22:24 · s_01M5J00E7P9JVR31NRRRYSXT0C」。这个 id 是内部标识,用户读不出任何含义,却占据了比时间更显眼的位置。

做什么。 删掉 id(ProjectsView.vue:327)。要保留可查性就放进 title 属性(悬停可见)。会话标题为空时显示「未命名对话」(已有)。

D4 · 内部术语与响应式

病灶一(术语)。 面向用户的文案里混着内部词:

现在写的 用户读到的是 改成
「项目里的 N 场对话会一起删除(保留窗口内仍可恢复)」 「保留窗口」是多久? 「项目里的 N 场对话会一起删除(删除后 7 天内可以在回收站找回)」——天数要跟服务端 -archive-ttl 的真值对齐(默认 168h = 7 天,cmd/yktako/main.go)。若该值可配,就改写成「删除后一段时间内可以找回」
「新对话落点」 内部词 「新对话默认进入」(C4 已改)
「档位」「围栏」等 — 界面文案里不出现(当前没出现,保持)

病灶二(响应式)。 全站只有一个断点(App.vue:1932 的 max-width: 860px)。手机(375px)上侧边栏会变成顶部横条 + 4 个横排按钮("brand new foot" / "nav nav nav"),加上「最近会话」区(A2 加的),375px 宽会挤成一团。

做什么。 加第二个断点 max-width: 480px:侧边栏的「工作区名 + 退出」折叠成一个「⋯」菜单;导航按钮改成只留图标(aria-label 保留文字);「最近会话」区在窄屏下默认收起。注意:这条要等 A2 落地后做(顺序见 §7)。

6. 验收怎么挂

沿用 AGENTS.md「两台机器,各管一段」:

层 放哪 覆盖什么 什么时候跑
快闸 yk-tako-eino/internal/runengine/contract_test.go 新端点 GET /api/workspaces/:id/files 的响应字节、GET /api/workspaces 的 isDefault 字段、POST /api/runs/:id/stop 的幂等字节 每拍收尾随 go test 跑
活体(契约字节) scripts/acceptance/expected.json + assert_contract.py B1 的三个 curl 用例(正常 / 越界 / 看不见)、C1 的 isDefault 字段 改契约字节时跑,红了退出码非零
前端逻辑 web/src/markdown.test.ts + node --test markdown 渲染的输出字节(不含 XSS 那条——marked 不转义原始 HTML,消毒在浏览器里做) A1 落地后随每拍跑
界面活体 web/e2e/(@playwright/test,新建) A2/A3/A5/C1/C2/C3/C4/D1–D4 的页面态断言;XSS 断言(<script> 不执行) 改界面后跑 npm run test:e2e

关于 playwright(已拍,2026-10-23)。 仓库现在没有任何浏览器自动化(无 playwright / puppeteer / vitest),所以本篇引入。选 Node 版 @playwright/test,装在 web/ 下、测试文件放 web/e2e/:

7. 顺序、依赖与风险

施工顺序(按 AGENTS.md「契约 → 数据需求 → 存储 → 实现」与「第一个 action 必须是一个能被 curl 打到的端点」):

Loop B(B1 文件浏览器)  ← 唯一的新契约,先把字节钉死
   └─ B1-1 后端端点(curl 拍)✓ 已落地 2026-10-23
   └─ B1-2 前端文件区(浏览器拍)
Loop A(对话面)
   └─ A1 markdown 渲染(前端逻辑断言 + 浏览器拍)
   └─ A2 会话历史入口(浏览器拍)
   └─ A3 停止按钮(curl + 浏览器拍)
   └─ A4 子代理条、A5 工作区名(浏览器拍)
Loop C(破坏性操作与文案)
   └─ C1 默认项目(字节拍 + 浏览器拍)
   └─ C2 密钥(浏览器 + curl 拍)
   └─ C3 保存与测试连接(浏览器拍)
   └─ C4 成员页文案与概念撞名(浏览器拍)
Loop D(观感)
   └─ D1–D4 一起(浏览器拍)

依赖关系。

风险。

风险 怎么对冲
markdown 渲染引入 XSS marked + DOMPurify.sanitize 两步(DOMPurify 默认剥掉 <script>、事件属性、javascript: URL);XSS 断言放 playwright 里跑,钉死 <script> 那条
B1 的列目录端点开了新的越界面 复用 resolveInWorkspace(与 agent 工具同一把锁);越界用例进 expected.json,红了就红
拆 form 后整体 PUT 把别的卡片配置覆盖成空 保存时组装完整请求体;每张卡片的保存都要在回归里验「别的卡片没被清空」
密钥改造把已有租户的密钥改坏 存量 •••• 值的语义不变(仍表示「不改动」);改造后要验一把已有密钥在「不输入直接保存」后仍然是原来的值

8. 要你拍的一件事(其余已拍)

已拍(2026-10-23,用户点头):

  1. 界面验收引 playwright —— 选 Node 版 @playwright/test(理由与装法见 §6)。这一条让 14 项修复里 9 项界面改动都有机器断言,不用靠人眼返工。

  2. markdown 渲染用 marked + dompurify —— 选型出处见 §2 A1(三家参考实现一致),版本 marked 18.1.1 + dompurify 3.4.17。

  3. 「清空密钥格子 = 删除」这条路径取消(C2)——用户 2026-10-23 点头:取消。改成「留空 = 不改动」+ 显式的「删除这把密钥」按钮 + 二次确认。一个输入框的「空」有两种含义是最容易出事的写法。细节见 §8.1。

8.1 「清空密钥格子 = 删除」是什么意思

现在的界面长这样(团队 → 设置 → 密钥):

密钥
格子里仍是 •••• 时,保存不会改这把密钥。把格子清空再保存,会删掉它。

DEEPSEEK_API_KEY  │  ••••  │ [移除]

三个事实:

  1. 格子里的 •••• 不是密钥本身,是服务端给的占位符,意思是「这把密钥已经存在,但我不给你看真值」。
  2. 今天的 •••• 是真的躺在那个输入框的 value 里。用户以为那 4 个点是遮罩、点进去会看到真密钥——其实点进去看到的就是 4 个点。
  3. 于是有两条删除路径,界面只用一句话带过:
    • 路径甲:把格子里的 •••• 删干净(留空)→ 保存 → 这把密钥被删除。
    • 路径乙:点「移除」按钮 → 那一行从界面上消失 → 保存 → 这把密钥也被删除(而且「移除」这个词听起来只是「从列表里拿掉」,没有任何确认)。

更要命的是第三条路径——用户想改一把密钥,不是删:

所以这条要拍的是:输入框的「空」到底该表示什么。

另外一条要你确认的(不算拍板,是澄清):A2 我按「项目下挂对话的结构保留,只在对话页加一个『最近 10 场』的快捷入口」写。如果你要的是完整的项目-会话树也搬到对话页,那是另一套(侧边栏要变三栏),施工量翻倍,请明确说一声。

已知的遗留(不算 bug,是还没做的):


9. 落地后的回填清单

2026-10-23 已全部完成(施工完,每条 loop 收口时):

  1. 本篇头注改「✅ 已落地」+ 写 commit 与验收结论。
  2. doc/README.md §1 的 48 行改状态与代码落点。
  3. doc/16 §2 表 #8 行:「登录 / 聊天 / 续传 / 停止 ✅」改成如实描述(停止端点早已存在、前端入口本批才接);§5.1 划掉本篇;§6 索引加本篇。
  4. doc/19-v6/19v6-04-验收-curl.md + scripts/acceptance/expected.json 同批改(B1 的用例 + C1 的 isDefault),check-expected.sh 绿。
  5. scripts/check-master-plan.sh 绿。

10. 补充(2026-11-14 · doc/79):项目里的 md 文件按 markdown 渲染显示

10.1 病灶:同一份 markdown,聊天里排好版,项目文件里是符号

用户在对话页让 agent 写一份说明文档。agent 写完,在回复里说:「文档写好了,见 docs/设计说明.md。」

用户点开那份文档。右侧工作区弹出文件标签,正文是这样的:

# 设计说明

## 背景

本系统需要解决三个问题:

| 环节 | 现状 | 目标 |
| --- | --- | --- |
| 拉取 | 轮询 | 增量 |

表格边框没了,标题跟正文一样大,# 和 | 直接摆在眼前。

用户想看的是排好版的文档,看到的是一堆符号。于是他不用文档了——他让 agent「把要点直接写在回复里」,或者下载到本地用编辑器看。文档写下来,没人看。

这不是「少了个功能」,是同一套能力已经存在、只是没接上:

同一份 markdown,聊天里是排好版的,项目文件里是符号。

10.2 两个入口都要修(同一个病的两张脸)

入口 代码位置 改前的样子 谁在用
对话页右侧工作区文件标签 web/src/WorkspaceFileView.vue <pre> 原文,256KB 上限 刚被 agent 告知文件写好了,点开就看
项目页文件列表「预览」 web/src/ProjectsView.vue <pre> 原文,截 2000 字 离开对话页专门去看文件

两处是同一个毛病的两张脸:同一种文件、同一个项目目录、两种看法。只修一处,用户换个入口就又看见符号了——这正是 §0.3 说的「同一个病,两副面孔」。

10.3 做了什么(每一步:做什么/为什么/输入从哪来/输出到哪去)

第 1 步 · 判定:哪些文件按 markdown 渲染。 按扩展名,只有 md 与 markdown 两个。

第 2 步 · 渲染:复用 renderSafe(),不新写解析器。

第 3 步 · 样式:抽成全局一份,三处共用。 新建 web/src/markdown.css,类名 .md-body。

第 4 步 · 截断先于渲染。 顺序是「取字节 → 截断 → 渲染」,不是「渲染 → 截 HTML」。

第 5 步 · 安全:不多开一个口子。

10.4 切换语义

入口 切换控件放哪 形态
对话页右侧文件标签 头部 .file-head,下载按钮左侧 两枚小按钮:「预览」/「原文」,默认「预览」
项目页文件列表 文件行的操作区 md 文件行一组「预览」/「原文」;非 md 文件不出现这组控件

10.5 验收(两层)

层 在哪 覆盖什么
快闸 web/test/markdown.test.ts(Node 内置 runner,零新依赖) 不传 opts 时输出与改动前逐字相同(标题/表格/代码块三类,期望字节是改动前实跑抄下来的);breaks: false 单换行不产 <br>;per-call 覆盖不污染全局;表格滚动壳仍在
活体 web/e2e/md-preview.spec.ts(Playwright,不需要真模型:造文件用写盘,不发消息) 两个入口都渲染出 h2/table/pre code;window.__xss 未被设置;「原文/预览」来回切;对话页切文件复位;非 md 不出现切换控件;截断提示在渲染后的预览里

renderSafe 那一半(DOMPurify 要 DOM)在 Node 里调不动,断言放在浏览器里——这与本篇 §2 A1 当初的分工一致:结构在 node 里测,执行在浏览器里测。

顺带修的两处——都不是本篇的能力,只是收尾时顺手修掉的既有红:

  1. web/e2e/files.spec.ts(doc/76 的遗留):此前是红的——doc/76 之后项目内容落在容器下的 content/,而它仍把文件写到容器根,服务端只扫 content/、根本看不见,页面列不出来。修法是三处:写盘路径加 content/、建项目后写盘前先打一次 GET /api/workspaces/:id/files(让服务端先把容器转正,否则会撞 409 117116)、断言与页面行为一个字不改。
  2. web/e2e/smoke.spec.ts / web/e2e/ui.spec.ts 的「项目」按钮 strict mode 歧义(doc/78 引入的):对话页右侧工作区有一枚「项目」标签,页面上于是有两个同名按钮,旧写法 getByRole('button', { name: '项目' }) 在 strict mode 下报歧义(选中了两个)。修法是把选择器收窄到左侧导航(getByRole('navigation', { name: '页面' })),断言逻辑与页面行为一个字没动。

本轮的环境障碍(不是代码问题,但要知道):web/e2e/markdown.spec.ts(聊天气泡的回归网)本轮未跑——开发库里默认项目 ws_01M5J00E99HHDH7MQXNKCAK46K 的容器仍是 doc/76 之前的老布局(缺 layout.json,根目录直接躺着 .media/、.tako/ 与 10 月的样本 hello.txt),ensureProjectLayout 判为存量容器 → 起 run 回 409 117116「这个项目还需要迁移目录后才能使用」,于是没有助手气泡、没有停止按钮,断言超时。已用对照实验排除代码因素:同一租户下新建项目起 run 回 202、模型正常出字。恢复办法:跑项目布局迁移命令(cmd/yktako -migrate-project-layout)后即可跑——那是运维动作(要动用户数据),不在本篇范围内。