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 个问题(都是写完第一版复审时发现的,记在这里免得下次重犯):
- 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(四条断言,含一条把「哪种形态会坏」钉死的对照)。.stage缺min-height: 0:窄屏下.app变 column 方向,flex item 默认min-height:auto不肯收缩 →.stage被对话内容撑高 → body 溢出 126px、页面能滚 → 登录时聚焦密码框把页面滚下半截,顶部的导航全被推出视口(真实手机浏览器同样会这样)。scrollBottom()在空列表时也滚:空态「从一句话开始」被推出视野(窄屏尤其明显)。改成空列表时scrollTop = 0。- 拆 form 后保存会连带提交别的卡片:在「模型」卡片点保存,会把「密钥」卡片里还没保存的编辑一起提交 —— 「各有各的保存」就名存实亡。改成:只提交本卡片的编辑,其余用服务端已保存的值(
savedConfig)原样带回。- 限宽用
width不生效:.projects/.cfg/.stack是 flex item(flex: 1→flex-basis: 0%),width 会被顶掉 → 宽屏留白根本没修掉。改用max-width。- markdown 每次渲染都重算:
v-html="renderSafe(b.text)"在模板里,流式输出时每个 token 到达都要把所有气泡重新 parse + sanitize 一遍。加v-memo="[b.text]"。.recent在窄屏 grid 里没grid-area:.rail在 ≤860px 是 grid,不指定 area 它被自动放置到 nav 那一行,把 brand / 新对话 / 导航全挤没。- 密钥 placeholder 被「显示」按钮挡住:那个按钮浮在输入框右侧,值框要留出右内边距。
- playwright 测试污染开发库:断言发的消息会在开发库留下会话。断言现在自己收尾删掉。
- 拆 form 的修复自己引入了一个新 bug:保存某张卡片后调
loadConfig()全量重载,把用户在其它卡片里还没保存的编辑一起冲掉(在「密钥」卡片点保存 → 「模型」卡片里刚填的模型被覆盖回旧值 = 用户白填了)。改成:保存后只更新「已保存值」里刚提交的那一块,编辑框保持原样;已标记删除的行从表里移除(删除已生效,「撤销」无意义了)。回归网:web/e2e/ui.spec.ts的「保存一张卡片不会冲掉另一张卡片里未保存的编辑」(旧行为下判红)。 另外修掉一个 17 条之外的问题(复审时发现的,不在本篇清单里):SSE 事件流的重连死循环——access token 过期 + 连接断开 + 页面静止三者同时成立时,前端每 3 秒拿过期 token 重连一次、服务端一律 401,引擎日志被刷满、事件流实际是死的。修法与对照实验见 doc/46 §7.5。 施工进度(2026-10-23):全部 17 拍已落地。
- A0:playwright 装在
web/,断言落在web/e2e/。- Loop B(B1-1 端点 / B1-2 文件区):新增
GET /api/workspaces/:id/files,快闸两条 + 活体「用例 12」(9 步)全过。- Loop A(A1-1/A1-2 markdown、A2 最近会话、A3 停止、A4 子代理条、A5 工作区名):
web/src/markdown.ts+web/test/markdown.test.ts(7 条单测)+web/e2e/{ui,markdown}.spec.ts。- Loop C(C1 默认项目、C2 密钥、C3 保存按钮、C4 成员页文案):C1 加了
isDefault字段(快闸一条 + 活体「用例 13」)。- Loop D(D1 限宽、D2 长文本、D3 隐藏 id、D4 术语与窄屏)。 过程中修掉一处 Vue 3 陷阱(另有一处是同写法但并非真 bug,见下):
p.x ?? (p.x = {...})的赋值表达式值是 raw 对象不是 reactive proxy,后续赋值绕过响应式 set 拦截器 → 数据进了内存、DOM 不更新;触发条件是「赋值与改值之间隔着 await」。ProjectsView.vue的loadFiles真踩了(文件列表永远空白),已改成「先判空再赋值、再读出来用」。chat.ts的upsertQuestion(doc/47 的问答主界面)是同一写法但今天并不坏(赋值后紧接着 push、中间无 await,渲染发生在 push 之后)——同样改成防御式写法,理由与回归网见 §2 A1 与web/test/reactive-trap.test.ts。全部落地后回填本行(写 commit 与验收结论),并同批更新 doc/README.md 与 doc/16。 日期:2026-10-23。 代码落点:yk-tako-eino/web/src/{App.vue,chat.ts,api.ts,ProjectsView.vue,Configure.vue,MembersView.vue,markdown.ts,markdown.css,markdown.test.ts}、yk-tako-eino/web/src/WorkspaceFileView.vue、yk-tako-eino/web/e2e/(playwright 断言,含md-preview.spec.ts)、yk-tako-eino/internal/runengine/{server.go,product_api.go,product_store.go,contract_test.go}、scripts/acceptance/expected.json。 真源关系:项目与目录是 doc/35;删除语义与保留窗口是 doc/37;团队前端是 doc/36;产品形态收窄(项目只有属主可见)是 doc/42;契约字节真源是 doc/19-v6。本篇不改任何既有契约字节,只在两处新增(见 §3.1、§4.1)。 不在本篇:协同编辑(doc/42 已拍不做)、回收站与恢复入口、项目文件的在线编辑、MCP 配置的图形化向导、多语言。
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)。
POST /api/runs/:runId/stop早在server.go:75注册好了,前端grep stop只有stopped这个状态名,一次都没调用过。GET /api/sessions不带workspaceId早就能跨项目列会话,前端listSessions()也早就能这么调——只是ProjectsView永远带着workspaceId调。GET /api/media?path=workspaces/<wid>/…早就能取项目里 agent 写出的文件,前端只在图片的时候用了一下。
病根不是「懒得做」,是没人把「后端有」和「页面能用」对过账。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「与代码冲突时先判断哪一边过期」,这里过期的是代码。
做什么。
新增
web/src/markdown.ts,导出三个函数:导出 做什么 碰 DOM 吗 renderMarkdown(text): stringmarked.parse(text)→ HTML 字符串否(纯函数) sanitizeHtml(html): stringDOMPurify.sanitize(html)是 renderSafe(text): string前两者串起来 是(浏览器里跑) 依赖装两个:
marked@18.1.1+dompurify@3.4.17(选型出处见下)。App.vue的气泡正文从{{ b.text }}改成v-html="renderSafe(b.text)"。样式:给
.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 是纯前端改动,零后端。
做什么。
- 侧边栏
rail的导航(.nav)下面加一个「最近会话」区,标题写「最近会话」。 - 数据:
GET /api/sessions(不带参数),按createdAt倒序取最近 10 场,每行显示会话标题(空标题显示「未命名对话」)+ 时间(toLocaleString('zh-CN', {dateStyle:'short', timeStyle:'short'}))。 - 点一行 = 打开那场会话。复用现成的
openSession(id)(chat.ts已导出,ProjectsView的「打开」按钮就是调它)。 - 当前正在看的那场会话,在列表里高亮。
- 列表底部一行「在项目页里看全部 →」,跳到项目页。
为什么是「最近 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 还在烧。
做什么。
api.ts加stopRun(runId: string): Promise<{ status: string }>(走现成的request(),信封统一)。chat.ts加stopCurrent():拿当前busy那条气泡的runId调stopRun;成功后把该气泡state置'stopped'(chat.ts的closeOut已有stopped分支,App.vue:947已有「已停止,没有写进历史」的文案,不用新写文案)。App.vue的 composer 栏:busy为真时,把状态提示「正在回复」换成「正在回复 · 停止」按钮;点了就调stopCurrent(),按钮进入 disabled + 「正在停止…」。- 排队中(
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,生产验收后修的一轮)。 上线后用户报「当前会话找不到停止按钮」。排查下来不是样式问题,是三处真实缺口:
- 按钮只认本实例的忙态。
busy由本页的投递(deliver)和轮询(pollFrames)置位。同一场 run 若是另一个标签页 / 另一台设备发起的,本页没有轮询者,busy一直是 false,按钮根本不渲染——可这场 run 确实在烧 token。用户看到的正是这一条。 busy是布尔开关,多个写者互相覆盖。 投递与每个轮询者各自在finally里把它置 false,先结束的一轮会把仍在跑的那轮按钮一起关掉。同一场 run 还会被reconcile与投递各起一个轮询者:画两个 streaming 气泡,问答面板随之出现「2 / 2」。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 实测)。 上一批修完停止能力后,按手机视口量了一轮,四处不是审美问题、是能测出来的缺陷:
- 每个气泡底部多一条空行。
.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。 - 长工具卡摘要和宽表格把气泡撑出视口。 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。 - 触屏尺寸与 iOS 缩放。 ≤860px:输入框 16px(低于 16px 时 iOS 聚焦会放大整页)、发送/附件/菜单/新对话 36px、会话行 40px、提问选项最小 44px;
.list加overscroll-behavior: contain(滚到头不把整页拉出回弹)。 - 提问面板 footer 在 320px 挤成两行。 「数字键选择 · Enter 提交 · Shift+Enter 换行」是键盘说明,手机上没意义还占行;≤480px 隐藏
.ask-hint、按钮右对齐,dock 内边距同时收紧。 - 停止失败提示被手机端规则误藏。 ≤860px 有一条「只留正在回复/排队提示」的规则
.hint:not(.live):not(.queue){display:none},.hint.stop-fail也命中——手机上点了停止失败依旧毫无反馈,与本篇开头修的问题同形。选择器补:not(.stop-fail)。 #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 实测)。 用户报「回复不是一个字一个字出的,会停一段时间突然出一段,停的时候也不知道它在干嘛」。量下来是两件事叠在一起:
- 源头不是问题。 引擎把厂商 chunk 逐条压成 delta 帧(一帧 1–3 字,中位间隔 0ms、均值 7ms,一轮 782 字共 522 帧);SSE 通道同样以 ~150ms、每批 25–66 字送达。停顿发生在两个地方:模型首字之前(TTFT 2.2–3.8s),以及工具执行期间(
bash sleep 6实测算工具卡 1.4s 出现、之后 5.8s 页面没有任何变化)。 - 前端 400ms 一拉、一拉一刷。
POLL_MS = 400把 ~90 字攒成一次 DOM 更新,所以看到的是「停一下、出一段」;空等时页面上只有三个点,没有任何阶段或时长信息。
修法两拍(纯前端,不动帧与端点):
- 状态行(A1)。
Bubble/ToolCard各记一个startedAt(进入 streaming、调用帧到达时打点);正文空且没有在跑的工具时显示「● ● ● 正在思考 · Ns」,工具在跑时秒数挂到卡片 chip(「执行中 · Ns」),工具都回执了还没出字显示「正在继续 · Ns」;正文一出,点和状态行同时消失,只留光标。计秒用 1s 时钟,只在存在 streaming/offline 气泡时跑,收口即停。 - 自适应轮询(A2)。 上一拉有帧 → 150ms 后再拉;空拍 → 400ms。冗余 status 核对从「每 5 拍」改成「每 ≥2s」(按拍数算会在有帧时变成 0.75s 一次)。
实测(同一模型同一提示):正文刷新间隔中位 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 个)。
- (推荐,纯 CSS) 名字超长时不截断,改成两行,并给
.who加min-width: 0+word-break: break-all;.switcher-btn的title属性放全名,鼠标悬停可见。同时把「退出」按钮挪到头像的右侧(或收进工作区切换菜单里),把宽度还给名字。 - 缩短「退出」为图标按钮(可读性换宽度)。
- 侧边栏加宽到 17rem(影响所有页面,不推荐)。
没它会怎样。 多工作区场景下用户分不清自己在哪。
验收。 浏览器活体:侧边栏底部的工作区名完整可见(不出现 …);名字超长时换行显示且不撑破侧边栏。
3. Loop B · 产出可达
B1 · agent 产出的文件,用户拿不走(P0)
病灶。 用户让模型「把结果写成 report.md」,模型说写好了。然后没有然后:
- 项目页只列项目与项目下的会话,不列项目目录里的文件;
- 聊天里那行
report.md是个.bubble-file文字片(App.vue:925),不可点击; GET /api/media挂着authn中间件要 Bearer 头,用户右键另存、贴进新标签页都会 401。
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=<相对路径,默认 ".">
- 成功体:
{"code":0,"message":"","data":{"path":".","entries":[{"name":"report.md","kind":"file","size":1234,"modifiedAt":"2026-10-23T…"},{"name":"sub","kind":"dir"}]}} - 围栏:复用
resolveInWorkspace(root, path)(filetools.go:33)——越出项目目录与绝对路径一律 400111002「路径不对」(与 agent 侧工具同一把锁,还带符号链接逃逸检查,不新开一条能绕过的路)。错误码按现状取111002,不是111001:同一个resolveInWorkspace失败在product_api.go的 dev 文件端点上已经用111002(codeBadInput「路径不对」),沿用同一个码,前端能复用同一套处理分支。 - 可见性:先
VisibleWorkspace(ctx, wid, tenantID, userID),看不见回 404114001。 - 内部目录不列:
.media/(入口媒体,doc/32)与.tako/(搜索截断落盘,doc/21 H3:<项目>/.tako/search/*.md)不进entries。用户不需要看这两样,看了反而困惑。(更正:子代理 wire 不在项目目录——它在会话目录.tako/subagents/,doc/39;这个端点碰不到它。)但.media/里的图片仍然要能显示——见下条。 - 符号链接不列:symlink 条目直接跳过。它可能指向项目外,列出来等于泄露「那边有什么」,而点进去
resolveInWorkspace也会挡住——列了是坏体验,不列是安全。 - 排序:目录在前,同类按名字升序(与
list_directory工具口径一致)。 - 大小与时间:
size是字节数,modifiedAt是 mtime(ISO8601)。
② 前端(2026-10-23 已落地,web/src/ProjectsView.vue):
- 项目页每个项目卡片加一个「文件」区(默认收起,与「查看对话」并列的两个可展开区之一)。
- 展开时
GET /api/workspaces/:id/files?path=.,列出条目;点目录 → 往下钻(面包屑:项目根 / sub);面包屑可点回任意一层。 - 取字节走
GET /api/media?path=workspaces/<wid>/<相对路径>(前端要带 Bearer,用现成的authFetch)。因为要带 Authorization 头,不能直接把 href 指过去(浏览器直接导航不带 → 401),所以一律先fetch成 blob:图片出缩略图、文本出内容、其他给「下载」。 - 「预览」按钮按扩展名白名单给(图片 png/jpg/jpeg/gif/webp/bmp/svg/ico;文本 txt/md/markdown/csv/json/log/yml/yaml/toml/html/css/js/ts/go/py/sh/xml/ini/conf)。为什么不看 Content-Type:
/api/media的 mime 表(mediaMimeByExt)只覆盖图片/pdf/音视频,.md/.csv/.txt落到application/octet-stream,blob.type 判断不出文本。服务端条目里也没带 mime 字段(那是字节出口的事),所以前端按扩展名近似——判错的后果只是「少一个预览按钮」,不会出错内容。 - 文本预览最多显示 2000 字,超出部分提示「用下载拿全文」。
③ .media/ 的可达性(2026-10-23 已查清,开放项关闭)。 「内部目录不列」会让 .media/ 里的入口图片从文件浏览器里消失。查了落盘口径(media.go:69):.media/ 里只有用户上传的入口图,文件名是内容寻址的 sha256[:16] + 扩展名(没有原名);模型产出的图不走这里(模型自己 write_file 写进项目目录)。而入口图在聊天气泡里全部能看(App.vue 的 <img class="bubble-media">)。→ 不列 .media/ 不会让用户失去任何入口,这一条不用再改。
每一步的输入输出。
- 输入:项目 id + 相对路径;输出:该项目目录下的直接子项清单。
- 输入:
workspaces/<wid>/<相对路径>;输出:文件字节(Content-Type 按扩展名,表外为application/octet-stream,见mediaMimeByExt)。 - 前端把两者接起来:点文件名 → 取字节 → 图片内联 / 其他下载。
没它会怎样。 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。」于是前端只能等点了才知道删不掉。
做什么。
- 后端:
GET /api/workspaces的每个 workspace 对象加一个字段"isDefault": bool(默认项目为 true)。加字段不改既有字段,是增量,不是契约翻转——但仍是字节变更,所以要进expected.json+ 19v6-04 同批改。 - 前端:
api.ts的Workspace类型加isDefault?: boolean。- 项目页:默认项目不渲染「删除」按钮(改成一句静态说明「默认项目不能删除」),「重命名」也去掉(改名默认项目没有意义,且会让用户失去「这是默认项目」的视觉标识)。
- 项目名后面加一个「默认」徽标(跟「新对话落点」徽标同款样式)。
- 「新对话落点」那一行的文案:「默认项目」改成「默认」,跟列表里的项目名对上(见 C4)。
- 保留后端 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 掉那一行、没有任何确认。用户以为「移除」只是把它从列表里拿走,保存后它真的被删了。
做什么。
- 密钥值不再是输入框里的真实值。 改成
type="password"的输入框 + 一个独立的「显示/隐藏」按钮(像登录页的密码框那样,App.vue:842已有这个模式,直接抄)。- 服务端返回
••••时:输入框留空,placeholder 写「已保存(留空则不改动)」。 - 用户输入了内容 →
masked = false,保存时用用户输入的值。 - 用户没输入 → 保存时传
••••(服务端认这个占位符、保留原值)。 - 这样「输入框里有什么」与「保存什么」永远是同一件事,占位符永远进不了真实值。
- 服务端返回
- 「移除」改名为「删除这把密钥」,并加二次确认(复用现成的
ConfirmDialog.vue):「删掉 DEEPSEEK_API_KEY?保存后这把密钥不再可用,模型调用会失败。」 - 「清空格子删除」这条路径取消(已拍,2026-10-23)。因为 1 改完后,「清空」和「输入新值」不再能靠「格子是不是空的」区分了。所以:
- 输入框留空 = 不改动(不是删除);
- 点「删除这把密钥」= 删除。
- 一个输入框的「空」只该有一种含义。文案改成:「留空表示不改动;要删除请点删除按钮。」
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,读的是库里的配置)。
做什么。
- 每个卡片自带自己的「保存」。拆成三个独立的
<form>(模型 / 密钥 / MCP),各自一个保存按钮,卡片底部。- 「密钥」和「模型」的保存只提交自己那部分字段。
- 「自定义 MCP」的保存只提交 mcpServers +(可选)测试。
- 服务端
PUT /api/tenants/:id/runtime-config是整体 PUT(Configure.vue:301),所以拆 form 后,前端在提交某一块时要带上其它块的当前值(不然整份配置被覆盖成空)。实现上:保留一份cfg状态,各卡片保存时组装完整请求体再 PUT。
- 「测试连接」挪到 MCP 卡片的顶部,并改名为「测试已保存的配置」。或者:改成测当前编辑内容——这需要后端给「未保存的 MCP 配置」开一个试连入口(后端加端点,超出本篇范围,不做)。所以本篇采用改名 + 挪位。
- 保存后不再自动
testMcp()(Configure.vue:313)——保存完自动测一次连接,会让保存这个动作变慢且可能拉起 MCP 子进程。改成保存成功后提示「已保存」。
没它会怎样。 用户改了模型但没找到保存 → 以为改了其实没改;或者点了「测试连接」看到「连接失败」,实际失败的是旧配置。
验收。 浏览器活体:改「默认模型」→ 不滚动就能看到「模型」卡片里的保存按钮 → 点它 → 刷新页面,模型仍是新值;改 MCP 但不保存 → 点「测试已保存的配置」→ 报的是旧配置的连接状态(且按钮文案明确写着「已保存的」)。
C4 · 「个人工作区没有成员」在 owner 视角下自相矛盾(P1)
病灶。 实测:当前租户 a7-envelope-test,kind=personal,而当前用户角色是 owner(侧边栏底部就写着「所有者」)。点「团队 → 成员」,整页只有一句:
个人工作区没有成员
「你就是所有者,怎么可能没有成员」——这句话是写给「个人租户不搞成员制」这个实现事实的,不是写给用户的。用户会当成 bug。
再往上一层:概念撞名。 同一个界面体系里,「工作区」这个词同时指三样东西:
| 出现在哪 | 指什么 | 用户看到的样子 |
|---|---|---|
| 侧边栏切换器 | tenant | 「a7-envelope-test / 所有者」 |
| 团队页 | tenant | 「个人工作区没有成员」 |
| 项目页顶部 | workspace(没选时) | 「新对话落点:默认项目」 |
| 项目页列表 | workspace | 一个真名叫「默认」的项目 |
于是页面上同时出现「默认项目」和「默认」两个词,分处两地,用户得靠猜知道是一回事。
做什么。
- 成员页文案改成人话:个人租户时显示「这是你一个人的工作区,不需要邀请成员。」(而不是「个人工作区没有成员」)。加一句说明「要和人一起用,建一个团队工作区」+ 一个「+ 创建团队工作区」按钮(后端
POST /api/tenants已存在,前端切换器里已有「+ 创建工作区」入口,见App.vue:806)。 - 「个人工作区」这个词在界面上统一改成「个人工作区」→ 用户自己的那一个叫「我的工作区」。具体:
- 团队页成员 tab:
个人工作区没有成员→这是你一个人的工作区(+ 上面那句说明)。 - 切换器里的
kindLabel('personal')返回的「个人」标签 → 「我的」。
- 团队页成员 tab:
- 「默认项目」→「默认」(项目页「新对话落点」那一行),跟列表里的项目名对齐。
- 项目页顶部那行「新对话落点」改名为「新对话默认进入」——「落点」是内部词。
没它会怎样。 新用户第一次点「团队」,看到一句自相矛盾的话;项目页上「默认项目」和「默认」两个词让人怀疑自己看错了。
验收。 浏览器活体:个人租户 → 团队 → 成员 → 看到「这是你一个人的工作区」;项目页 → 「新对话默认进入:默认」。
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/:
- 为什么是 Node 版不是 Python 版:
scripts/acceptance/那层是 python3 + curl + jq,但界面断言要驱动浏览器、要跟 web 共享 TS 配置与类型;web 已经是 Node 工程,装一个 devDependency 就不引第二套工具链。契约字节那层仍归scripts/acceptance/(python),界面这层归web/e2e/(node)——两层各管一段,跟 AGENTS.md「两台机器」一致。 - 前置:
npm i -D @playwright/test+npx playwright install chromium(下载 chromium 约 150MB,一次性;离线环境要预先缓存)。 - 断言随仓库入库(AGENTS.md「可机器重跑的验收必须入库,不许只留在 tmp/」)。
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 一起(浏览器拍)
依赖关系。
- B1-2 依赖 B1-1(端点字节先定)。
- A2 依赖 A5 的侧边栏改造(两者改同一块
rail),同拍做。 - D1 的限宽会影响 A2 新加的「最近会话」区的宽度 → D1 在 A2 之后。
- D4 的窄屏适配依赖 A2(要适配新加的会话区)→ D4 最后。
- C1 要改
GET /api/workspaces的响应体 → 与 B1 的端点同批进expected.json(一次改完机器真源,避免改两遍)。
风险。
| 风险 | 怎么对冲 |
|---|---|
| markdown 渲染引入 XSS | marked + DOMPurify.sanitize 两步(DOMPurify 默认剥掉 <script>、事件属性、javascript: URL);XSS 断言放 playwright 里跑,钉死 <script> 那条 |
| B1 的列目录端点开了新的越界面 | 复用 resolveInWorkspace(与 agent 工具同一把锁);越界用例进 expected.json,红了就红 |
| 拆 form 后整体 PUT 把别的卡片配置覆盖成空 | 保存时组装完整请求体;每张卡片的保存都要在回归里验「别的卡片没被清空」 |
| 密钥改造把已有租户的密钥改坏 | 存量 •••• 值的语义不变(仍表示「不改动」);改造后要验一把已有密钥在「不输入直接保存」后仍然是原来的值 |
8. 要你拍的一件事(其余已拍)
已拍(2026-10-23,用户点头):
界面验收引 playwright —— 选 Node 版
@playwright/test(理由与装法见 §6)。这一条让 14 项修复里 9 项界面改动都有机器断言,不用靠人眼返工。markdown 渲染用
marked+dompurify—— 选型出处见 §2 A1(三家参考实现一致),版本 marked 18.1.1 + dompurify 3.4.17。「清空密钥格子 = 删除」这条路径取消(C2)——用户 2026-10-23 点头:取消。改成「留空 = 不改动」+ 显式的「删除这把密钥」按钮 + 二次确认。一个输入框的「空」有两种含义是最容易出事的写法。细节见 §8.1。
8.1 「清空密钥格子 = 删除」是什么意思
现在的界面长这样(团队 → 设置 → 密钥):
密钥
格子里仍是 •••• 时,保存不会改这把密钥。把格子清空再保存,会删掉它。
DEEPSEEK_API_KEY │ •••• │ [移除]
三个事实:
- 格子里的
••••不是密钥本身,是服务端给的占位符,意思是「这把密钥已经存在,但我不给你看真值」。 - 今天的
••••是真的躺在那个输入框的 value 里。用户以为那 4 个点是遮罩、点进去会看到真密钥——其实点进去看到的就是 4 个点。 - 于是有两条删除路径,界面只用一句话带过:
- 路径甲:把格子里的
••••删干净(留空)→ 保存 → 这把密钥被删除。 - 路径乙:点「移除」按钮 → 那一行从界面上消失 → 保存 → 这把密钥也被删除(而且「移除」这个词听起来只是「从列表里拿掉」,没有任何确认)。
- 路径甲:把格子里的
更要命的是第三条路径——用户想改一把密钥,不是删:
- 他点进值格子,全选
••••,敲下新密钥sk-abc123→ 没问题,格子变成sk-abc123,保存正确。 - 但他没全选,只是在末尾接着敲、或者只删掉一个点 → 格子变成
•••sk-abc123→ 保存进去的就是这个带占位符前缀的垃圾串 → 这把密钥当场失效,而界面照样弹「已保存」。
所以这条要拍的是:输入框的「空」到底该表示什么。
- 现状:空 = 删除(甲),外加一个「移除」按钮也 = 删除(乙),外加「空 = 不改动」这条只在一个字都没动的时候才成立——同一个状态三种含义。
- 建议:输入框的「空」只表示「不改动」(这是绝大多数人改设置时的期望);删除走单独的按钮 + 二次确认。这样「输入框里有什么」与「保存什么」永远是同一件事,占位符永远进不了真实值。
另外一条要你确认的(不算拍板,是澄清):A2 我按「项目下挂对话的结构保留,只在对话页加一个『最近 10 场』的快捷入口」写。如果你要的是完整的项目-会话树也搬到对话页,那是另一套(侧边栏要变三栏),施工量翻倍,请明确说一声。
已知的遗留(不算 bug,是还没做的):
GET /api/sessions没有上限(session_access.go:77的ListSessions没有Limit)→ 项目页一次列全部会话,上百场时会慢。最近会话区只取 10 场 ✓- 文件浏览器是只读的:不能上传、编辑、删除项目里的文件(那要另做权限与安全设计)
9. 落地后的回填清单
2026-10-23 已全部完成(施工完,每条 loop 收口时):
- 本篇头注改「✅ 已落地」+ 写 commit 与验收结论。
doc/README.md§1 的 48 行改状态与代码落点。doc/16§2 表 #8 行:「登录 / 聊天 / 续传 / 停止 ✅」改成如实描述(停止端点早已存在、前端入口本批才接);§5.1 划掉本篇;§6 索引加本篇。doc/19-v6/19v6-04-验收-curl.md+scripts/acceptance/expected.json同批改(B1 的用例 + C1 的isDefault),check-expected.sh绿。scripts/check-master-plan.sh绿。
10. 补充(2026-11-14 · doc/79):项目里的 md 文件按 markdown 渲染显示
10.1 病灶:同一份 markdown,聊天里排好版,项目文件里是符号
用户在对话页让 agent 写一份说明文档。agent 写完,在回复里说:「文档写好了,见 docs/设计说明.md。」
用户点开那份文档。右侧工作区弹出文件标签,正文是这样的:
# 设计说明
## 背景
本系统需要解决三个问题:
| 环节 | 现状 | 目标 |
| --- | --- | --- |
| 拉取 | 轮询 | 增量 |
表格边框没了,标题跟正文一样大,# 和 | 直接摆在眼前。
用户想看的是排好版的文档,看到的是一堆符号。于是他不用文档了——他让 agent「把要点直接写在回复里」,或者下载到本地用编辑器看。文档写下来,没人看。
这不是「少了个功能」,是同一套能力已经存在、只是没接上:
web/src/markdown.ts里早就有renderSafe()(marked 解析 + DOMPurify 消毒),聊天气泡与任务交接正文都在用;- 而项目里的两个文件视图,一个把
.md归进TEXT_EXT后用<pre>吐原文,另一个同样。
同一份 markdown,聊天里是排好版的,项目文件里是符号。
10.2 两个入口都要修(同一个病的两张脸)
| 入口 | 代码位置 | 改前的样子 | 谁在用 |
|---|---|---|---|
| 对话页右侧工作区文件标签 | web/src/WorkspaceFileView.vue |
<pre> 原文,256KB 上限 |
刚被 agent 告知文件写好了,点开就看 |
| 项目页文件列表「预览」 | web/src/ProjectsView.vue |
<pre> 原文,截 2000 字 |
离开对话页专门去看文件 |
两处是同一个毛病的两张脸:同一种文件、同一个项目目录、两种看法。只修一处,用户换个入口就又看见符号了——这正是 §0.3 说的「同一个病,两副面孔」。
10.3 做了什么(每一步:做什么/为什么/输入从哪来/输出到哪去)
第 1 步 · 判定:哪些文件按 markdown 渲染。 按扩展名,只有 md 与 markdown 两个。
- 为什么按扩展名而不看 Content-Type:
/api/media的 mime 表只覆盖图片/pdf/音视频,.md落到application/octet-stream,blob.type判断不出文本。 - 为什么只这两个:
json/yaml/csv这些也在TEXT_EXT里,但把它们当 markdown 渲染是倒退——散文排版套在数据文件上,读不懂。 - 输入 = 文件路径(两个入口各自已有);输出 = 一个布尔「这是不是 markdown」。
第 2 步 · 渲染:复用 renderSafe(),不新写解析器。
- 为什么不新写:① 安全口径已经过验收(DOMPurify 那一步本就是为「模型写进来的原始 HTML 不能被执行」加的,md 文件同样是外部内容:agent 写的、用户上传的,一样可能有
<script>、onerror);② 不引新依赖(marked + dompurify 已在package.json里);③ 裸链接的中文标点处理白捡(markdown.ts那条 CJK_STOP 规则是为中文句子里的裸链接写的,项目里的 md 多半是中文)。 - 换行规则分家:聊天气泡用
breaks: true(模型输出常把一句拆成多行,不折行会挤成一坨);md 文件用breaks: false(文件里的换行是作者排版的结果,标准 markdown 语义下单个换行不等于换行,GitHub 的 README 就是这样渲染的)。 - 实现上不能改全局
setOptions(改了会把气泡的换行规则一起带跑),而是给渲染函数加一个可选参数:renderMarkdown(text, opts?)/renderSafe(text, opts?)。marked 的parse(src, opts)是「全局默认值 + 本次 opts」合并({...this.defaults, ...opts}),per-call 覆盖不回写全局——所以传过{ breaks: false }之后,默认渲染仍是breaks: true。 - 输入 = 文件字节(取字节的路径一个字没变:仍是
GET /api/media,带 Bearer 头);输出 = 一段已消毒的 HTML 字符串。
第 3 步 · 样式:抽成全局一份,三处共用。 新建 web/src/markdown.css,类名 .md-body。
- 这一步最容易做错:Vue 的 scoped 样式只作用于本组件的元素。气泡那套排版原先写在
App.vue里、选择器是.bubble-text :deep(h1)——直接复制到WorkspaceFileView.vue/ProjectsView.vue里,一条都不会生效(scoped 的data-v属性不在别人组件的元素上)。所以排版必须抽到全局样式表,用一个中性类名承载,三个入口挂同一个类。 - 气泡专属的不搬:用户气泡是深色底,那套「浅底深字」的反色覆盖(
.bubble.user .bubble-text :deep(code)等)留在App.vue不动——搬过来会让用户气泡的代码块变浅色,那是视觉回归。 - 为什么不用
.bubble-text当类名:气泡样式带着用户气泡的深底覆盖,与文件视图的浅底排版不是一回事,混在一起会互相污染。 - 没它会怎样:三个入口各写一份
:deep()段,前两份根本不生效(用户看到的还是没排版的符号),第三份生效——同一个产品里两种排版。
第 4 步 · 截断先于渲染。 顺序是「取字节 → 截断 → 渲染」,不是「渲染 → 截 HTML」。
- 为什么:markdown 渲染后再截,会拦腰砍断表格与代码块——半张表比显示原文更糟。截断拿到的是纯文本,渲染的是截断后的结果。
- 上限沿用现状,不新造:项目页 2000 字(超出照旧显示「…(还有 N 个字,用「下载」拿全文)」);对话页右侧 256KB(超限仍走「不能内嵌预览」那一档)。
第 5 步 · 安全:不多开一个口子。
- md 内容走
DOMPurify.sanitize(与聊天气泡同一条管线 = 同一份保证),<script>、onerror、javascript:URL 一律剥掉。 - 相对图片保持原样:md 里写
时 marked 出的<img src="logo.png">是相对路径,找不到就是坏图。本次不做路径改写(属独立一拍),但不许把src改成一个会 401 的/api/mediaURL——那会制造一堆坏图请求;坏图显示浏览器的默认占位。 - 不把 token 拼进 URL(包括给图片造
/api/media?access_token=):字节出口挂在 authn 上,前端不新增任何绕过鉴权的取字节方式。
10.4 切换语义
| 入口 | 切换控件放哪 | 形态 |
|---|---|---|
| 对话页右侧文件标签 | 头部 .file-head,下载按钮左侧 |
两枚小按钮:「预览」/「原文」,默认「预览」 |
| 项目页文件列表 | 文件行的操作区 | md 文件行一组「预览」/「原文」;非 md 文件不出现这组控件 |
- 默认进预览态;切到「原文」=今天的行为逐字不变(
<pre>+ 原始字节 + 同样的截断与上限说明);切回「预览」=渲染结果。 - 非 md 文件不给切换控件:只有一种看法,md 才需要选。给
.txt也加「预览/原文」是噪音。 - 对话页切文件时复位到预览态:在 A 文件点了「原文」,打开 B 文件也还是原文态是 bug 不是特性。
- 项目页的切换状态记在
FileRow里(raw: Record<string, boolean>,与既有的preview/text两张按文件名的表同形),两个入口互不影响。
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 里测,执行在浏览器里测。
顺带修的两处——都不是本篇的能力,只是收尾时顺手修掉的既有红:
web/e2e/files.spec.ts(doc/76 的遗留):此前是红的——doc/76 之后项目内容落在容器下的content/,而它仍把文件写到容器根,服务端只扫content/、根本看不见,页面列不出来。修法是三处:写盘路径加content/、建项目后写盘前先打一次GET /api/workspaces/:id/files(让服务端先把容器转正,否则会撞 409117116)、断言与页面行为一个字不改。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)后即可跑——那是运维动作(要动用户数据),不在本篇范围内。