76 · 项目内容目录与运行资源容器
性质:已落地。本稿解决用户内容与异步执行资源混在一个项目目录里的问题:用户只看
content/,其余归runtime/。 状态:✅ 已落地;2026-11-12 立项并方案收口,同日施工,2026-11-13 活体验收与文档收口。 施工包:tmp/75-76-目标重规划与项目目录/施工包.md(与 doc/75 合并施工;施工期材料,用户验收后留档doc/log/)。 日期:2026-11-12 成文,2026-11-13 落地。 代码落点:internal/runengine/project_layout.go(容器/content/runtime 路径与旧布局准入)、scope.go/worker.go(WorkspaceRef 带 RuntimeRoot)、media*.go、bashspill.go、webfetch.go、websearch.go、memory_markdown.go/memory_migrate.go、workspace_{provider,engine,git,directory,result,publish,view}.go、filetools.go/product_api.go(文件清单与整容器删除 +cleanup=done|pending)、pgstore.go/store.go(project_cleanups与补偿)、archive_sweep.go/tempsweep.go、cmd/yktako/main.go(-migrate-project-layout离线迁移);前端web/src/{ProjectsView.vue,TasksView.vue,api.ts}(删除反馈与工作区标识)。验收:scripts/acceptance/{project_layout,project_layout_migration,workspace_directory,workspace_git,workspace_publication,workspace_crash,memory_markdown,memory_migrate,memory_project_delete}_live.sh、契约用例 58/60 与contract_test.go(删除体cleanup字段、117116 字节)、go test ./internal/runengine、npm run typecheck/npm run build。 前置真源:doc/35(现有项目目录)、doc/37(删除与保留窗口)、doc/52(技能与工具归属)、doc/65(记忆文件)、doc/74(异步工作区与结果发布)。 边界:本篇只调整目录归属、内容可见性、迁移和删除;动态重规划归 doc/75,用户级 skill/plugin 本期不做。
1. 目标:用户内容与执行资源不再混在一起
以用户项目 Tomcat 为例,目标逻辑布局是:
Tomcat-project/ # 项目资源容器:删除项目时整容器清理
├── Tomcat/ # 项目内容根:用户真正需要看到的内容
└── runtime/ # 执行资源:默认不出现在用户文件清单
├── orchestrations/<编排组ID>/ # 异步工作区、不可变结果、验证与发布记录
├── tmp/ # 有明确清理规则的临时文件
├── media/ # 上传媒体与内部读取副本
└── memory/MEMORY.md # Markdown 模式的项目记忆
真实磁盘仍可使用租户与工作区 ID 防重名,例如:
<workspace>/tenants/<tenantId>/workspaces/<workspaceId>/
├── content/
└── runtime/
workspaces/<workspaceId> 从“模型直接读写的项目根”改成“项目资源容器”;content/ 才是用户内容根。UI 中的项目名 Tomcat 与磁盘 ID 分离,不因项目改名移动目录。
这个方案解决的是:用户打开 Tomcat 时只看到自己想看的内容,而不是 .tako、.media、工作副本、验证记录或项目记忆。
2. 当前真实布局与差距
当前代码把以下内容混在项目根:
workspaces/<workspaceId>/
├── .media/
├── .tako/bash/
├── .tako/fetch/
├── MEMORY.md
└── <用户文件>
同时,异步隔离组在租户级:
tenants/<tenantId>/.tako/orchestrations/<orchestrationId>/workspace/
技能与工具则在:
tenants/<tenantId>/skills/
tenants/<tenantId>/tools/
当前项目删除只删除项目根和关联会话目录;编排组目录仍等终态过窗后清理。技能、工具与用户 USER.md 不随项目删除。
所以目标与现状有三个根本差距:
- 项目根既是用户内容,又承载运行资源;
- 编排组归租户目录,不归项目资源容器;
- 删除没有一个可以完整代表项目磁盘资源的容器边界。
3. 两个目录概念必须分开
| 概念 | 操作定义 | 谁使用 |
|---|---|---|
项目内容根 content/ |
文件工具、普通聊天和用户文件列表所看到的项目根 | 用户与普通文件操作 |
| 项目资源容器 | 内容根与 runtime 的共同父目录;删除项目时的磁盘边界 | 引擎、迁移与删除 |
运行资源根 runtime/ |
保存异步工作区、结果、临时文件、媒体与项目记忆 | Provider、Worker、清理器 |
| 会话目录 | 保存子代理 wire 等会话自有档案 | 现有会话生命周期 |
| 租户资源根 | 保存租户共享技能、工具与用户记忆 | 租户级能力,不归单个项目 |
代码不能继续让 workspaceDir() 同时回答“内容根”和“资源容器”。需要拆成:
projectContainerDir(root, tenantId, workspaceId)
projectContentDir(root, tenantId, workspaceId)
projectRuntimeDir(root, tenantId, workspaceId)
WorkspaceRef.Root 表示当前执行者真正的工作根;另增通用 RuntimeRoot 承载 bash 输出、抓取全文等内部落盘。媒体与项目记忆通过各自路径函数定位,不再从 Root 猜资源位置。
4. shared 与 isolated 在容器里的准确含义
本方案讨论的是异步 Task。普通聊天仍可直接修改 content/,行为不变。
4.1 shared 异步工作区
shared 表示同一编排组里的 Task 共用一个工作现场,不是直接写用户内容根:
runtime/orchestrations/<编排组ID>/workspace/work/shared/
- A/B 在同一个共享工作目录中工作;
- 文件工具的短写入保护仍生效,但 bash 任意写仍是非合作边界;
- 中间结果不直接进入
content/; - 最终结果经过接受与发布后进入
content/。
4.2 isolated 异步工作区
isolated 表示每 Task 一个工作现场:
runtime/orchestrations/<编排组ID>/workspace/work/<taskId>/
- Git 项目仍由 GitProvider 使用本组中间仓库与 linked worktree;
- 非 Git 项目仍由 DirectoryProvider 使用独立目录副本与变更清单;
- 不可变父结果通过现有结果引用交接;
- 最终发布仍走 doc/74 的验证、项目准入与恢复。
因此 shared/isolated 的区别是“同组共享现场还是每 Task 独立现场”,不是“一个写项目、另一个不写项目”。两种异步模式都不把中间产物直接暴露到用户内容根。
模式选择与默认值是否调整不在本篇范围;本篇只改变目录归属与发布边界。
5. 结果、产物与临时文件
5.1 不可变结果
每个 Task 的已接受结果保存在:
runtime/orchestrations/<编排组ID>/workspace/results/<taskId>/<resultRevision>/
中间 Task 结果只供下游、审查与恢复使用,不复制进 content/。只有最终 Task 的结果经发布链进入用户内容根。
结果产物仍通过 doc/74 的 Task artifact 端点按版本读取;项目当前文件仍走现有 media/文件出口。两者不能因为路径相同就混用。
5.2 临时文件
统一逻辑落点为 runtime/tmp/,但不同用途仍分子目录与清理规则:
- Provider staging;
- 目录复制与迁移 staging;
- 内部 Git 临时输出;
- 其他有明确超时与清理者的临时内容。
不能把所有临时文件堆到一个无归属目录。每个条目必须带组/任务/操作归属,过期清扫只删满足既有时间与安全条件的条目;正在使用、身份不明或包含唯一未保存工作的目录保留。
bash 全文与 web_fetch 全文是有恢复价值的运行输出,不叫临时垃圾。它们分别进入当前工作现场对应的 runtime/ 记录区,不进入 content/.tako/。
6. 技能、工具、plugin 与记忆的归属
6.1 本期不变的部分
<workspace>/system-skills/ # 系统技能
<tenant>/skills/ # 租户技能
<tenant>/tools/ # 租户上传工具
<tenant>/users/<userId>/USER.md # 用户记忆
这些不是 Tomcat 项目独占资产,不移动到 Tomcat 的资源容器,也不随 Tomcat 删除。
当前没有用户级 skill/plugin;本期不增加。当前也没有项目级技能归属,不从现有租户技能推造一层。
6.2 项目记忆
Markdown 模式的项目 MEMORY.md 改到:
runtime/memory/MEMORY.md
它仍按原 WorkspaceID 归属与加锁,仍随项目删除;只是不再出现在用户文件清单中。pipeline 模式的 PG 记忆与任务不受目录迁移影响,项目删除仍按 scope 清理。
7. 项目删除:整容器删除,但不误删租户资产
目标删除链:
用户删除项目
→ 锁项目与发布准入
→ 拒绝默认项目、活 run、未收口组、publishing/blocked 发布
→ PG 事务软删会话、清项目记忆/记忆任务、删项目行
→ 提交后删除整个项目资源容器
→ 删除关联会话目录中的项目私有档案
→ 发既有 workspace_deleted 事件
整容器删除包括:
content/;runtime/;- 本项目的全部异步工作区、结果、验证与发布记录;
- 项目记忆文件与媒体;
- 本项目临时文件。
不删除:
- 租户技能与工具;
- 系统技能;
- 用户
USER.md与用户级记忆; - 按 doc/37 仍需保留的 PG run/runlog/用量档案。
目录删除失败只记日志并保留清理记录,API 不把“目录没删掉”伪装成磁盘已清理;现有业务响应与保留策略如需调整,在施工包中单独钉契约,不顺手改旧接口。
8. 存量项目迁移
不能因为目录改名就丢现有项目。每个存量项目独立迁移,迁移期间禁止该项目新 run 与发布:
锁项目
→ 检查无活 run/未收口组/发布
→ 在同级创建唯一 staging 容器
→ 把现有用户文件复制到 staging/content/
→ 把 .media、.tako、MEMORY.md 复制到 staging/runtime/ 的对应位置
→ 把本项目已有编排组目录复制到 staging/runtime/orchestrations/
→ 校验迁移清单与文件哈希
→ 当前容器改名为 backup,staging 原子改名为正式容器
→ 成功后按保留策略清 backup
要求:
- 迁移清单记录源、目标、哈希与完成状态,崩溃后可对账;
- 不把未知目录或别人的容器删了;backup 清理只认本次迁移身份;
- 任何一个文件校验失败则该项目不切换,旧容器仍可用;
- 同一项目同时只有一个迁移者,其他项目可独立迁移;
- 迁移与启动装配解耦,不能让引擎启动时无界扫盘;由显式迁移命令或有限批量任务执行;
- 已有 PG 路径字段若只存逻辑项目 ID 则不变;若存有绝对路径,施工时先列清单并迁移,不留双写。
doc/74 当前工作区实现需要同步改路径来源;不得保留一个仍指向租户 .tako/orchestrations/ 的旧写口。
9. 权限、安全与多副本
- 文件列表、项目文件下载和普通文件工具只以 content 为根;runtime 不通过项目文件枚举暴露。
- Task artifact 是唯一的不可变结果读口;权限仍走 Task 属主链。
- 所有路径由租户、工作区、编排组和 Task ID 推导,模型不能指定容器路径。
- 项目容器、会话目录与租户资源仍位于所有引擎副本共享的持久卷;本机另造目录不算恢复。
- 内容迁移、工作区准备、发布和删除各有共享锁与恢复记录;不把文件操作塞进 PG 事务。
- 存储配额继续按整租户目录计算;容器重归后不得重复计数或绕过配额。
- 日志与 trace 不记录敏感文件正文;迁移报告使用相对路径与哈希。
10. 验收与完成线
10.1 目录与迁移
- 新建项目得到 content/runtime 容器;普通聊天写文件只影响 content。
- 媒体、bash 输出、抓取全文与项目 MEMORY.md 不出现在 content 或用户文件清单。
- 存量项目迁移后用户文件逐字不变,运行资源进入 runtime;迁移中途 kill -9 可恢复,不双份混入正式目录。
- 迁移过程中该项目不能开新 run 或发布;其他项目不受影响。
- 租户技能、工具、系统技能与用户 USER.md 路径不变。
10.2 异步链
- shared 同组 Task 共用工作目录,不直接写 content;最终发布后才看到结果。
- isolated Git/Directory 各 Task 使用独立目录,不可变结果与父结果交接不受迁移影响。
- 中间 Task 完成不污染 content;最终 Task 验证与发布失败时 content 不被冒充更新。
- 结果产物仍可按版本读取;项目当前文件与结果版本不混淆。
- doc/74 的 Git、Directory、双副本与崩溃场景在新路径下全绿。
10.3 删除
- 活 run、未收口组与发布受阻仍阻止删除;默认项目仍不可删。
- 删除成功后整个项目容器不存在,包括 content、工作区、结果、媒体、项目记忆与临时文件。
- 关联会话私有档案按现有规则清理;租户技能/工具、系统技能、用户记忆与 PG 保留档案不受影响。
- 目录删除失败有日志与清理记录,不能宣称物理清理成功。
10.4 标准门禁
除 Go/前端/契约测试外,还需真实跑:存量迁移、shared/isolated、Git/Directory、项目删除、kill -9、双副本、浏览器文件可见性与 doc/70/72/73/74 回归。
完成线是:用户只看到项目内容;所有异步执行资源都归项目容器;中间结果不提前污染项目;最终发布与删除边界一致;存量项目不丢文件;租户共享资产不被误删。
10.5 施工中确认的发布边界
shared 组的结果现在也走 doc/74 的发布链(先写 runtime/,发布后才进 content/),这带来两条必须写清楚的边界,否则测试和后续实现都会误判:
- 发布准入按项目静默,不按组静默。
admitPublication排除的是 同一个项目的所有其它活 run(runs.workspace_id = 项目 AND status='running' AND lease_until > now()),不只是同一编排组的 run。真实失败故事:一个项目里有一场挂在ask_user上等人的 Task,人还没回答;同时另一场带检查点的最终 Task 跑完了。挂起 run 的status仍是running、租约仍有效——发布准入一直等不到项目静默;而最终 Task 的检查点暂停又是在发布收口之后才应用,于是那场检查点永远进不了“计划待决策”。 构造“检查点暂停”场景时,忙线 run 必须挂到另一个项目(或先回答完);doc/70 的 busy 活体与 doc/72/73 的处理项活体已按这条改动,脚本注释写明原因。挂起问题 Task 与检查点 Task 不应放在同一项目里同时等人工。 - “新增或修改”仍是产物声明的唯一依据。 共享现场以组基线做 diff,任务声明的 artifact 必须是本次执行新增或修改的文件。把文件提前放进
content/再让任务“声明”它,会被提交校验拒绝(回执明确写artifact 必须是本次新增或修改的文件),结果里就没有产物。活体 fixture 改为由任务自己创建产物,再按workspaces/<wid>/<path>读取。 - shared 受阻后与 isolated 共用同一条恢复路径。 shared 组走发布链后,同样会因项目被推进或工作区脏而让最终 Task 进
blocked(workspace_changed/workspace_dirty/publication_recovery),注意力面板把它标成publication_blocked。恢复入口仍是POST /api/tasks/:id/retry-publication:它不按工作区模式分叉,只认「最终 Task、blocked 且带发布三码、当前结果版本与不可变结果仍有效」。若这里还按 isolated 拦截,shared 的最终 Task 会停在 blocked 且没有任何人工出口(117112 死路)。契约用例 59 的 shared 夹具是非 blocked 任务,所以字节期望不变(117112),差别只在「blocked + 发布三码」这一档。 - 新项目首次使用的并发请求不能被误判成存量。 初始化先写
layout.json再建content//runtime/;「容器已有条目、但这次没读到 layout」时再读一次;原子写的.tako-tmp-*临时文件不计入存量条目。反例是本轮契约套件抓到的真实 117116:同一个新项目的第一场 run 在后台初始化容器,紧接着第二个POST /api/runs在「content/已建、layout.json还没落盘」的窗口里查projectLayoutNeedsMigration,把刚建的项目判成存量。活体表现是一条随机 409,TestEnsureProjectLayoutConcurrentFirstUse钉住。
11. 代码落点与施工纪律
| 位置 | 实际修改点 |
|---|---|
project_layout.go |
projectContainerDir/projectContentDir/projectRuntimeDir/ensureProjectLayout;容器非空而无 layout.json 回旧布局错误,HTTP 层统一 117116 |
scope.go / worker.go |
项目绑定会话的 runWorkspace 同时给出 content 根与 runtime 根;WorkspaceRef.RuntimeRoot |
media.go / media_send.go |
媒体物理落点移 runtime,逻辑授权与读取不变;workspaces/<wid>/<path> 映射 content |
bashspill.go / webfetch.go / websearch.go |
内部输出落 runtime/记录区,不再写 content/.tako |
memory_markdown.go / memory_migrate.go |
项目 MEMORY.md 移 runtime/memory/,锁与归属不变 |
workspace_{provider,engine,git,directory,result,publish,view}.go |
编排组目录从项目容器推导(runtime/orchestrations/<id>);shared 也走发布链;Provider 只消费路径函数 |
filetools.go / product_api.go |
文件清单与媒体只暴露 content;删除整容器,响应带 `cleanup=done |
pgstore.go / store.go |
删除事务写 project_cleanups.pending,提交后删容器;调度器补偿回写 done |
archive_sweep.go / tempsweep.go |
清扫按新容器与恢复边界执行 |
cmd/yktako/main.go |
离线 -migrate-project-layout:复制 → 校验 → 原子切换,可重复执行 |
web/src/ |
项目文件区只显示 content;删除后按 cleanup 提示“磁盘清理稍后完成”;Task 详情标共享/隔离工作区 |
scripts/acceptance/ |
project_layout_live.sh(36 条)、project_layout_migration_live.sh(51 条),以及既有目录/Git/发布/崩溃/记忆活体按新路径回归 |
施工纪律(2026-11-13 回填):没有临时实现或过渡开关——旧布局项目在 HTTP 层直接 117116,迁移只走离线命令;没有 content/ 的直写旁路,所有异步结果都经发布链进入内容根。
12. 所以这解决了什么
doc/76 把“项目目录”从一个混杂的大目录拆成用户内容根与项目资源容器:用户只看到 Tomcat,异步工作区、结果、媒体、项目记忆和临时文件都在容器内但不污染内容根。
它同时统一了 shared/isolated 的最终发布边界和项目删除边界,并明确租户共享技能、工具与用户记忆不属于某个项目。这样目录结构、可见性、隔离与生命周期才指向同一个项目模型。