前端可用性欠账:后端有契约、页面没入口,先补齐再谈观感
模块:前端 · 页面与交互(doc/44 / doc/48 / doc/49 / doc/50)|状态:已落地(doc/44/48/49 全部;doc/50 A1–A4 已落,A5 部分未做)|证据:
doc/44-前端三处欠账.md、doc/48-前端可用性欠账.md、doc/49-走查缺陷修复.md、doc/50-侧栏项目树.md、yk-tako-eino/web/src/
1. 场景与病灶
后端每多一条契约,用户在页面上就多一个「知道它存在、却够不到」的动作。积到 2026-10-23,三件事已经能跑、页面却没有入口:
故事一(项目在终端里,不在眼前)。 用户在「验收项目」里跟 agent 做了两天活,想再建一个项目分开做。POST /api/workspaces 一早就能建,但页面上没有项目列表——只能在终端里建,建完看不到;项目越积越多,想删没用的那个也只能 curl。更糟的是,页面永远把新对话送进默认项目(POST /api/runs 从不带 workspaceId),用户建的项目里永远不会有对话落进去。
故事二(删除动作没有刹车)。 DELETE /api/sessions/:id、DELETE /api/workspaces/:id 都在,页面没有删除按钮。删除不可逆,后端已经用 409 挡住「有活 run」和「默认项目」;页面如果自己猜一句「操作失败」,用户就不知道该去停 run 还是换项目。
故事三(子代理跑完就消失)。 researcher 跑了十几分钟,折叠成三行摘要回到主对话。用户想追问「那个对比表的数据源是哪几个」,页面上看不到实例、也不知道 sa_id。档案在 .tako/subagents/,GET /api/sessions/:id/subagents 能列,resume_subagent 工具能接——两端都存在,中间没有入口。
这三件事的共同点不是「界面丑」,而是功能欠账:后端有契约、页面没入口,功能等于不存在。它和观感欠账(字号、留白、气泡形状)是两笔不同的账,修的顺序也必须分开——先修「点不到」,再修「不好看」(doc/51 §0 的同一判据)。
第三次走查(doc/49)还暴露了更重的一类:一个空格能拖垮整个租户。助手名 qa 空格 保存成功、列表正常,但名字同时是 AgentTool 的工具名;下一次任何 run 组装工具表时都撞上 tools[25].function.name 的 ^[a-zA-Z0-9_-]+$ 模式校验,整租户 400。名字合法性只在「模型调用那一刻」被第三方校验,创建时没人拦。
2. 候选与代价
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 只补「后端有、前端无」的入口 | 按 doc/44 三处逐个加页面 | 范围小、目标明确 | 走查中发现的交互缺陷(markdown 卡、停止无反馈、窄屏挤爆)留到下次 |
| B 按现象清单全量修 | doc/48 的 17 条一次全上 | 覆盖面大 | 17 条里同一处代码/同一拍的被拆散,实施与验收都碎;观感与功能混在一批,返工 |
| C 先归并、按「功能伤 → 观感伤」排序(选定) | 17 条现象归并成 14 项修复、4 个 loop;每项标严重度;doc/49 第二轮 12 项再按 P0/P1/P2 排 | 同一处代码一次改完;破坏性操作与观感各自成 loop;每批都能独立验收 | 归并本身要读代码、做判断;严重度排错会让「能用」被观感抢先 |
| D 推倒重做前端 | 换框架/重写页面 | 干净 | 后端契约与已验收交互全部要重新对一遍;与「用例驱动」节奏冲突 |
选 C。归并后的节奏:Loop A 对话面 → Loop B 产出可达 → Loop C 破坏性操作与文案 → Loop D 观感;doc/49 再按 P0 / P1 / P2 排。
3. 三处入口的裁量(doc/44)
3.1 项目页:会话挂在项目下
导航加第四页「项目」。数据只需两个现有端点:GET /api/workspaces + GET /api/sessions?workspaceId=。会话按需加载(展开项目才请求),首屏只打一次项目列表。
「当前项目」只记在浏览器(tako.workspaceId.<tid>),服务端不保存「我正在看哪个项目」。新对话的 POST /api/runs 只在没有 sessionId 时带 workspaceId:已有会话不带——服务端本来就不会改已有会话的项目,带了反而会让一个已删除项目的 id 把已有会话的投递挡在项目预检上。
3.2 删除:独立确认弹窗,不裸按钮
删除项目和删除会话都走 ConfirmDialog(遮罩 + role="dialog" + Esc 取消 + 焦点落在取消按钮),不沿用成员页的两段式小按钮。弹窗把后果写全:
- 删项目:「项目里的 N 场对话会一起删除,项目目录里的文件会清掉」;
- 删会话:「只删会话档案;项目目录里的产出文件不受影响」。
服务端拒绝时把信封的 message 原样显示,弹窗保持打开——不自造文案,也不替用户决定下一步。删项目前先拉一次该项目的会话列表拿 sessionIds,用于事后判断当前对话是否被连带删除。
3.3 子代理「继续」:不在页面起 run
每行显示规格名、sa_id、状态(complete / interrupted)、创建时间。只有 complete 给「继续」;interrupted 是崩溃/中断的半成品,不给按钮。
「继续」不是直接 POST 一个 resume 端点,而是把一句话追加到输入框并聚焦(不覆盖已有内容、不自动发送):
请用 resume_subagent 继续子代理 sa_xxx(researcher):接着它刚才的任务继续做下去,完成后把结果告诉我。
用户按 Enter,父 agent 在正常对话里调 resume_subagent({id, instruction})。为什么不做 HTTP 端点:resume 的 instruction 是对话语义的一部分;页面起一场 run 后「结果往哪写回父对话」没有答案,会多出第二套生命周期。这个选择保持 doc/39「resume 入口是模型侧工具」的裁定。
4. 走查怎么变成修单(doc/48 / doc/49)
4.1 doc/48:17 条现象 → 14 项修复
2026-10-23 下午在真实浏览器里走四个页面 × 两种宽度(1015px / 1511px):真发消息、真让模型调工具、真触发删除确认、真刷新验证恢复。17 条全部有当场证据。归并成 14 项,落到 4 个 loop:
| Loop | 管什么 | 代表项 |
|---|---|---|
| A 对话面 | markdown 渲染与 XSS、最近会话、停止反馈、子代理条、工作区名 | 点「停止」后页面无任何变化;用户不知道 run 停在哪儿 |
| B 产出可达 | 新增 GET /api/workspaces/:id/files,让项目产出在页面上看得见 |
后端写进项目目录,页面没有入口 |
| C 破坏性操作与文案 | 默认项目标记、密钥格子的删除语义、保存按钮归属、成员页文案 | 「清空密钥格子 = 删除」没有说清;一张卡保存连带提交别卡 |
| D 观感 | 限宽、长文本、隐藏内部 id、窄屏 | 宽屏内容贴左、内部 id 暴露给用户 |
落地过程中又自审出 10 个问题(Vue 3 raw object、.stage 缺 min-height、空列表也滚到底、拆 form 后连带提交、width 对 flex item 不生效、markdown 每 token 重算、.recent 缺 grid-area、placeholder 被按钮挡住、Playwright 污染开发库、保存后全量重载冲掉别卡编辑)。每一条都补了回归网,理由见 界面验收双轨。
4.2 doc/49:第二轮 12 项,P0 先修
2026-10-23 晚第二次全站走查(Playwright 逐页点击 + 真发消息 + 真停止 + 跨标签页 + 窄屏 + 引擎日志对读),12 项与 doc/48 不重叠:
- 1 项 P0:子代理名字含空格 → 整个租户的 run 全部 400(
tools[25].function.name)。 - 5 项 P1:刷新丢结果、面板卡输入框、侧栏留死链、内置助手被静默清空、导入默认可见性与手工相反。
- 6 项 P2/P3:文案、反馈、边界与日志卫生。
P0 的修法是把「名字合法」从模型调用那一刻提前到保存那一刻:agentNamePattern = ^[A-Za-z0-9_-]{1,64}$ 在创建/改名时校验(agents.go:66)。这条也是「验证要放在最靠近输入的地方」的一个实例——放过非法名字,代价由整个租户的下一场 run 承担。
5. 侧栏树的边界(doc/50)
侧栏从「扁平 10 条最近会话」改成「项目 → 对话」二级树:
- 数据零后端改动:一次
GET /api/workspaces+ 一次GET /api/sessions(不带workspaceId= 本人全部会话,每行带workspaceId); - 项目顺序:默认项目第一(
isDefault),其余按接口给的createdAt升序;workspaceId = null的游离会话排最后(实测开发库有 4 条); - 双层上限:整栏先取 10 条,每个项目再限 10 条;组内有被截住的才出「展示全部」,点开只放开这一个项目;有会话但全被截掉的项目不显示「还没有对话」;
- 空项目显示一行灰字「还没有对话」;当前会话所属项目若收起,打开时自动展开;
- 别的窗口改名/删项目:
workspace_renamed/workspace_deleted要重拉树——这两条已于 2026-11-15 落地(doc/50 A5,commitcba0339);在此之前侧栏常驻项目名,改名后会一直显示旧名。新会话出现沿用现有重拉点,不新增session_created事件。
6. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| 欠账的修复顺序 | 功能伤 → 观感伤 | 先修点不到/没法用;观感另立 loop(doc/51) |
| 一轮走查的现象怎么进单 | 先归并成项、再分 loop | 同一处代码的几条现象合成一项,否则实施与验收都碎 |
| 破坏性操作的形式 | 独立确认弹窗,不复用两段式按钮 | 删除不可逆,后果要完整写出来 |
| 服务端拒绝的文案 | 原样显示信封 message |
不自造;用户需要知道是「有活 run」还是「默认项目」 |
| 项目删除后的当前会话 | 前端先拉 sessionIds,删完按集合清理 |
否则对话页可能停在一条已不存在的会话上 |
| 子代理「继续」 | 向输入框追加指令,由父 agent 调工具 | 不在页面起第二场 run;保持 doc/39 的裁定 |
| 助手名合法性 | 创建/改名时校验(^[A-Za-z0-9_-]{1,64}$) |
放到模型调用时校验,代价是全租户的下一场 run |
| 项目列表加载 | 按需(展开项目才拉会话) | 首屏只打一次;项目多时不拖慢页面 |
| 「当前项目」存哪 | 浏览器(按租户),服务端不存 | doc/35 的裁定;服务端不记「我在看哪个项目」 |
| 侧栏翻页形态 | 列表内不放滚动条,用「展示更多」+10 | 用户明确不要内部滚动条(全列全展开偏好) |
7. 证据
方案:doc/44-前端三处欠账.md(三处入口、§2.4 为什么不做 resume 端点、§4 验收);doc/48-前端可用性欠账.md(17→14、4 loop、§6 两层验收、落地自审 10 条);doc/49-走查缺陷修复.md(第二轮 12 项、P0 故事、§14 四问);doc/50-侧栏项目树.md(树结构与双层上限、A5 未做)。
台账:tmp/44-前端三处欠账/、tmp/48-前端可用性欠账/、tmp/49-走查缺陷修复/、tmp/50-侧栏项目树/(本地,不入库)。
代码符号:
| 位置 | 是什么 |
|---|---|
yk-tako-eino/web/src/ProjectsView.vue |
项目页(列表 / 展开会话 / 开新对话 / 改名 / 删除) |
yk-tako-eino/web/src/ConfirmDialog.vue |
删除确认弹窗(遮罩、Esc、焦点) |
yk-tako-eino/web/src/chat.ts:343 |
新对话才带 workspaceId |
yk-tako-eino/web/src/chat.ts:472-477 |
发送那一刻定落点,事后切项目不覆盖 |
yk-tako-eino/web/src/api.ts:356 |
GET /api/sessions/:id/subagents |
yk-tako-eino/internal/runengine/agents.go:66-77 |
agentNamePattern 与 validAgentName(P0 修法) |
yk-tako-eino/internal/runengine/product_store.go:42-44 |
tenant_agent_name 唯一索引(名字同时是标签与工具名) |
复核命令:
cd yk-tako-eino
grep -n "agentNamePattern\|validAgentName" internal/runengine/agents.go
grep -n "workspaceId" web/src/chat.ts | head
grep -n "subagents" web/src/api.ts
cd web && npm run typecheck && npm test && npm run test:e2e # 需 ./scripts/dev.sh 起着活体验收:doc/44 浏览器 7 场全过(项目列表/新建/改名、项目内开新对话、历史恢复、项目与单场删除的取消与确认、默认项目 409 文案、级联删除与目录清理、子代理列出与「继续」);doc/48 两层全绿(快闸 3、活体 27、单测 7、Playwright 11);doc/49 在隔离引擎 8944 + 浏览器逐条手验 12 项;doc/50 A1–A4 浏览器验收,A5 未做。
8. 现状
- 仍有效:先功能伤后观感伤;破坏性操作必须确认弹窗 + 原样透传 409 文案;子代理「继续」走输入框指令;项目/会话的数据来源不新增后端契约;侧栏双层 10 条上限。
- 已落地(2026-11-15):doc/50 A5——
workspace_renamed/workspace_deleted事件触发侧栏树重载(commitcba0339,Playwrightweb/e2e/sidebar-events.spec.ts三条先红后绿);「侧栏改名后显示旧名」这条真实缺陷已消。窄屏部分已由 doc/51 U6 覆盖,不再重复。 - 已翻转:单会话形态作废(doc/44 → doc/50 的二级树);「后端有就能用」不再成立——没有页面入口的功能视为不存在。
- 同族问题:验收怎么断言 → 界面验收双轨;项目目录与归属 → 项目目录归谁;跨窗口失效靠什么事件 → 变更同步用事件通道;子代理档案与 resume → 子代理档案放哪里。