tako 文档 GitHub

前端可用性欠账:后端有契约、页面没入口,先补齐再谈观感

模块:前端 · 页面与交互(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 取消 + 焦点落在取消按钮),不沿用成员页的两段式小按钮。弹窗把后果写全:

服务端拒绝时把信封的 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 不重叠:

P0 的修法是把「名字合法」从模型调用那一刻提前到保存那一刻:agentNamePattern = ^[A-Za-z0-9_-]{1,64}$ 在创建/改名时校验(agents.go:66)。这条也是「验证要放在最靠近输入的地方」的一个实例——放过非法名字,代价由整个租户的下一场 run 承担。

5. 侧栏树的边界(doc/50)

侧栏从「扁平 10 条最近会话」改成「项目 → 对话」二级树:

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. 现状