tako 文档 GitHub

78 · 对话页右侧工作区:项目目录、任务与 Todo,以及改动文件回执

性质:方案(已落地)。把 doc/77 的单一面板扩成「项目目录 / 任务 / Todo / 文件」多标签工作区,并让每一轮写完文件的回复在结尾列出改动文件、点开就在右侧查看。 状态:✅ 2026-11-13 落地(未 commit,等验收)。后端两个只读端点 + 快闸 + 契约用例 65;前端多标签工作区、目录树、文件查看、Todo 标签与回复回执。go test ./internal/runengine(171.8s)、go vet ./internal/runengine、npm run typecheck、npm run build 通过;契约全量 475 步通过(用例 65 全 21 步);浏览器活体走查见 §7 第 3 层与「验收结果」。 2026-11-14 补充(doc/79):文件标签里的 .md / .markdown 按 markdown 渲染显示,默认预览态、可切「原文」(§2 第 6 条已改口径;样式与判定见 doc/48 §10)。取字节的路径、端点与响应字节一个字没变。 2026-11-14 补充(doc/80):「任务」标签的列表默认显示本会话派发的任务,可一键切「本项目全部」(本节 §3「不按会话过滤」与 §4.5 末句里的「不按会话过滤」被 doc/80 取代;其余条款继续有效)。 代码落点:internal/runengine/{runviews.go,runviews_test.go,server.go,contract_test.go}、web/src/{App.vue,api.ts,ChatDock.vue,WorkspaceTree.vue,WorkspaceFileView.vue,RunTodoPanel.vue,RunChangedFiles.vue}(TasksView.vue 只改滚动归属注释)、scripts/acceptance/expected.json(用例 65)、doc/19-v6/19v6-04-验收-curl.md、doc/40-响应信封统一.md(端点表)。 前置真源:doc/77(右侧任务面板,已落地;本篇取代它的 §3 第 4 条「不把 Todo 合并进面板」)、doc/76(项目容器 content/ 与 runtime/)、doc/48(文件清单端点与媒体字节出口)、doc/59(工具卡)、doc/41(run_tasks 看板)、doc/19-v6/19v6-08(折叠用的 file-ops 提取)。 边界:两个只读新端点;不改 run 执行、Task 状态机、文件工具行为与帧格式。

1. 病灶:文件写完了,人却在别的页面找它

一场日常的编码对话:

用户:把报价小工具补上折扣,顺便修一下那个红着的测试
→ 助手 write_file quote.py、edit_file test_quote.py,跑 bash 得到 unittest 输出
→ 回复写「已修好,test_discount 通过」
→ 用户想看看改成了什么样
→ 对话里只有一句「已修好」:工具卡里能翻到调用参数,但没有可点的文件
→ 离开对话 → 左侧「项目」→ 选项目 → 在项目页的文件列表里找 quote.py → 预览
→ 想接着聊,再点回对话,草稿和阅读位置重新找

第二次更糟:同一轮改了三个文件,用户只记得其中一个名字;或者过了两天刷新页面回来,回复还在,却没有任何线索指向「这一轮动过哪些文件」。

另一半问题在右侧面板本身。doc/77 之后,右侧只有一个任务列表:

完整业务链路(今天断在哪):

用户发消息 → agent 调 write_file/edit_file/bash 写盘 → 调用记录落 runlog(role=tool_call,payload 带 name/args/toolCallId)
→ run 终态 → assistant 回复进 runlog → 对话页渲染回复
     ↑ 链到这里断:回复只说「做完了」,程序手里有调用记录,但没有任何读口把「这轮改过哪些路径」交给页面
→ 用户想核对 → 只能离开对话,从项目页重新找入口

面板的目标链路:

同一份 runlog 调用记录 → GET /api/runs/:id/changed-files(新增,程序派生)
→ 回复结尾「改动的文件」→ 点击 → 右侧工作区开一个文件标签
项目 content/ 目录 → GET /api/workspaces/:id/files(既有)→ 右侧「项目」标签的目录树 → 点击文件 → 同一套文件标签
run_tasks → GET /api/runs/:id/tasks(新增)→ 右侧「Todo」标签(刷新后仍在)

2. 完成线

  1. 对话页右侧是一个可收起的工作区,标签固定三枚——项目 / 任务 / Todo——外加打开文件时追加的文件标签(可关闭)。收起后留一条窄轨,三个入口都在,任务标签带处理项计数;点任一入口展开并切到对应标签。
  2. 「项目」标签显示当前项目 content/ 的目录树:目录可展开/收起(按需拉取子目录),点文件在右侧开文件标签;有刷新;旧布局项目显示可读的迁移提示。
  3. 「任务」标签就是 doc/77 的任务面板:处理条 + 嵌入的任务页,行为逐条不变(含 dockFocus 定位互斥、事件/重连/聚焦重拉)。
  4. 「Todo」标签显示当前会话最近一场 run 的看板(编号、主题、状态、完成数/总数),刷新页面后仍在;桌面端输入框上方的 Todo 条移除,≤860px 仍留在输入框上方(此时右侧工作区整体不显示)。
  5. 每一轮写过或改过文件的助手回复,结尾多一行「改动的文件」:逐个文件一个可点条目,带「写入 / 编辑」标记;点击展开工作区(若已收起)并打开该文件标签。没有改动时不出现这一行。
  6. 文件标签能看内容:.md / .markdown 按 markdown 渲染显示(默认预览态,可切「原文」看原始字节,排版走全局 .md-body;doc/48 §10),其它文本按原样显示(超上限给截断说明与下载),图片直接预览,其它类型给下载;文件读失败有明确文案,不留白屏。
  7. 窄屏(≤860px)与今天一致:右侧工作区不显示、无横向溢出,Todo 回到输入框上方。
  8. 页面上不出现第二套任务详情实现、第二套文件列表协议或「假数据」占位。

3. 非目标

4. 已拍定的设计选择

4.1 右侧从「任务面板」变成「工作区」,标签是唯一的内容通道

doc/77 的面板只有一个内容面。再加文件树就必须有第二面,否则「看文件」和「看任务」互斥,用户又要在两个状态之间来回切。标签页是这一层最省的做法:固定标签回答「这里有哪些种类的信息」,文件标签回答「我正在看哪一个文件」。

没这么做会怎样:要么文件树只能以弹窗出现(离开对话的阅读位置,正是要修的病灶),要么把任务和文件塞进同一个纵向滚动区(两件事互相挤占,任务多了文件永远在屏幕外)。

4.2 目录树与文件字节全部复用既有端点

没这么做会怎样:新写一套列目录/取字节,就要重新实现一遍「可见性判定 + 路径越界检查 + 旧布局拒绝 + 内部目录过滤」,漏一条就是一个越权或一个打不开的文件。

4.3 「改动的文件」由服务端从 runlog 派生,而不是从回复文字里抓

引擎在折叠上下文时已经有一份文件操作提取器(fileops.go:firstPartyFileEffects 声明表 + classifyToolCall + pathsFromArgs,含 bash 命令的写意图扫描)。它今天只服务「压缩后提醒模型自己做过什么」。这一轮把同一套判定放到 HTTP 读口上,按 run 读 runlog_entries 的 role=tool_call 行。

为什么不让模型在回复末尾自己写文件清单:模型会漏、会改写成口语、会在没写盘时说写了。清单要能回答「程序知道这一轮动了哪些路径」,只能以调用记录为真源;模型的文字是叙述,不是证据。

派生规则(与折叠的 file-ops 完全同源):

输入 处理
工具名在 firstPartyFileEffects write_file/create_directory/bash… → 写入;edit_file/move_file → 编辑;read_* → 读取,不进清单;memory 等显式 none → 不计
工具名不在声明表 沿用前缀表(write/edit/create/save/append/touch → 写入,read/cat/ls/... → 读取);有路径但判不出意图 → 记为写入(歧义按强信号记,与折叠一致)
路径来源 参数里的 path 字段 + bash 的 command 写意图扫描(重定向、cp/mv、tee/touch/mkdir/install、sed/perl -i、dd of=)
只保留可打开的 必须能解析到当前项目 content/ 下、stat 到普通文件;绝对路径、含 .. 段、.tako/、.media/、目录、当前已不存在的路径一律剔除
去重与顺序 按首次出现顺序;同一路径再次出现不换位置,op 取最后一次

已知边界(写进契约,不假装覆盖):

4.4 回复结尾的位置与触发条件

只挂在助手气泡上,且该气泡满足:有 runId、是这场 run 的最后一段(没有 segmentCallId)、状态已是终态(done / error / stopped / interrupted)。位置在用量/复制那一行之下,即「回复的结尾」。

没这么做会怎样:每渲染一次气泡就打一次接口;或者把清单挂到每个工具卡里——用户还是得自己把多次调用拼成「这轮改了哪些文件」。

4.5 Todo 从输入框上方搬进工作区(桌面端)

同一份看板今天有两个位置会重复。桌面端右侧工作区常驻,Todo 进「Todo」标签;≤860px 工作区不渲染,Todo 仍留在输入框上方。数据源换成新端点(见 §5.2),因此刷新页面后 Todo 不再消失——这是从 doc/41 前端以来一直存在的缺口。

与 doc/77 的边界变更:doc/77 §3 第 4 条「不把 Todo 合并进面板」作废,由本节取代;其余条款(面板跟当前项目、详情抽屉复用、定位 nonce 互斥)全部继续有效(其中「不按会话过滤」一项已由 doc/80 取代)。

4.6 当前 run 的取法

Todo 标签跟「本场对话最近一场 run」:取当前会话气泡里最后一条带 runId 的助手消息。理由:用户看到的是这场对话,Todo 属于这一轮;刷新后历史气泡仍带 runId(rowBubbles 逐行赋值),所以同一规则在刷新前后一致。会话还没有 run 时显示空态,不请求接口。

5. 契约:两个只读端点

两个端点都挂在 authn 上,鉴权与 GET /api/runs/:runId/skills(doc/52 B4)同一套:按 run 所属会话的可见性判,看不见与不存在同字节。信封三字段 code → message → data。

5.1 GET /api/runs/{runId}/changed-files

200 {"code":0,"message":"","data":{
  "runId":"r_01J…",
  "files":[{"path":"quote.py","op":"write"},{"path":"test_quote.py","op":"edit"}]
}}

错误:

401 {"code":111102,"message":"请先登录","data":null}
404 {"code":112002,"message":"找不到这次运行","data":null}
409 {"code":117116,"message":"这个项目还需要迁移目录后才能使用","data":null}
500 {"code":111901,"message":"服务暂时不可用,请再试一次","data":null}

409 与文件清单端点(doc/76)同一判据:旧布局项目的 content/ 还不能当读根。会话没有项目(历史数据)时返回 files: []。

5.2 GET /api/runs/{runId}/tasks

200 {"code":0,"message":"","data":{
  "runId":"r_01J…",
  "rows":[
    {"no":1,"subject":"读现有脚本","status":"completed","description":"","result":"读到 3 个函数","skillName":"","updatedAt":"2026-11-13T10:02:11Z"},
    {"no":2,"subject":"补折扣函数","status":"in_progress","description":"","result":"","skillName":"","updatedAt":"2026-11-13T10:03:40Z"}
  ],
  "total":2,
  "done":1
}}

这是 run_tasks 的第一个 HTTP 读口;工具层的 TaskList 与 kind=task 帧不改字节。

5.3 不改的东西

6. 前端施工面

文件 变更
web/src/api.ts 两个新类型的封装 getRunChangedFiles(runId)、getRunTasks(runId);沿用现有 listWorkspaceFiles、workspaceFileUrl、authFetch
web/src/App.vue 用 ChatDock 替换内联 .task-dock;把 taskDockOpen、dockFocus、dockReloadNonce、attentionItems 传给工作区;新增 dockFileRequest(workspaceId/path/nonce)与「打开文件」的入口;气泡结尾挂 RunChangedFiles;Todo 条改为仅窄屏显示
web/src/ChatDock.vue(新) 标签壳:固定三标签 + 文件标签、收起轨道、换行不滚动的标签条;持有文件标签列表与当前标签;消费 dockFileRequest
web/src/WorkspaceTree.vue(新) 懒加载目录树、展开/收起、刷新、错误态(含 409 117116 文案)
web/src/WorkspaceFileView.vue(新) 文本/图片/其它三档查看;加载失败与超限文案;下载链接
web/src/RunTodoPanel.vue(新) 读 §5.2,空态与错误态;看板变化(气泡上的 task 帧文本)与工作区重拉信号触发刷新
web/src/RunChangedFiles.vue(新) 读 §5.1、模块级按 runId 缓存;渲染文件条目与「写入/编辑」标记,emit('open', path)

交互约束:

7. 验收

三层都要有:

  1. 快闸(go test ./internal/runengine):新增纯函数/存储侧单测——去重与顺序、op 取最后一次、绝对路径/../内部目录/目录/不存在文件的剔除、空清单是 [];看板行映射与 total/done。期望字节先 curl 实跑再抄进测试,不手写。
  2. 契约(scripts/acceptance/):新增机器用例(用例 65,needs: pg)——用 seed_ws 造 content/ 文件,用 SQL 造会话/run/runlog_entries 工具调用行/run_tasks 行,逐字节断言两个端点的成功体(键序、files 顺序与 op、rows 顺序与 total/done、空态 [])、404 112002、401 111102、跨租户不可见;同号散文进 doc/19-v6/19v6-04-验收-curl.md;check-expected.sh 与 assert_contract.py 变绿。
  3. 活体(浏览器,dev 8901 / 5173):用一段真实编码对话(补折扣 + 修红测试)跑一轮,检查——回复结尾出现「改动的文件」且与 runlog 实际调用一致;点条目展开工作区并打开文件标签;「项目」标签目录树展开/刷新;「任务」标签行为与 doc/77 走查项一致;「Todo」标签在 run 结束后显示看板、刷新页面后仍在;收起后窄轨三入口与计数可用;≤860px 无横溢、Todo 回到输入框上方。截图留证,失败项如实报。

完成线:上面 8 条全部满足,且 go vet、npm run typecheck、npm run build 绿。

验收结果(2026-11-13):

8. 风险与边界

9. 所以这解决了什么

agent 写完文件,用户不必离开对话去项目页找:回复结尾直接列出这一轮动过的文件,点开就在右侧看;右侧本身也从「只能看任务」变成「项目目录、任务、Todo、文件」四类信息的一个工作区,收起只留一条窄轨。看、点、继续聊都在同一页完成。