35 · 项目目录(workspace)
性质:已落地(2026-10-21 收口)。A1–A8c 共 13 拍全部落地并 curl 验收过,随
e30d1f9入库(2026-10-20)。 后续修改方案:doc/76(2026-11-13 已落地)已把项目目录改为“资源容器 + content 用户内容根 + runtime 运行资源根”:本篇描述的磁盘路径(workspaces/<wid>直接放用户文件、.media/、.tako/)与取回端点路径以 doc/76 为准;项目的归属、会话挂载与默认项目这些语义仍以本篇为准。 验收结论:逐拍实测实录在tmp/35-项目目录/planning.md第 12 节(引擎127.0.0.1:8904,PG 5433 / Redis 6390)。 2026-10-21 活体抽验(引擎127.0.0.1:8942、独立库、Redis db 8,本篇 10 项断言全过):建项目拿到ws_前缀 id; 空项目名回 400;跨租户读别人的项目回 404;带workspaceId投消息拿到 sessionId;GET /api/sessions?workspaceId=只列该项目下的会话;PATCH /api/sessions/:id传空串解绑后该项目不再列它; 同项目第二场 live run 回 HTTP 409、业务码114004;带图投消息的占位 path 锚在workspaces/<wid>/.media/,GET /api/media取回字节与上传同长、跨租户取同一张图回 404;删默认工作区回 HTTP 409、业务码114005。 这一批明确不做的:项目目录的前端页面(独立 loop;2026-10-23 已由 doc/44 落地);把别人的会话改挂到别的项目(只能解绑); 乐观并发(write_file 写前校验版本)留为远期缝,v1 不做;不做两套路径并存——存量sessions/<sid>/.media/已清,老占位 path 自然 404(dev 期接受,上线前写进 release note)。 2026-10-22 已落地(形态收窄,doc/42):跨成员共享项目退役 + 项目闸(A7d)退役 + 「乐观并发远期缝」撤销。 本篇的「共享」语义改为个人项目(一个成员自己的项目,项目文件由他的多场 session 共享); A7d 那道整层串行的闸改为文件级防护:flock 写锁 + 写前指纹比对(doc/19-v6/19v6-08 §语义裁定)。 代码侧的落点:可见性判定只剩属主(pgstore.go三处 SQL + 列举)、PATCH /api/workspaces/:id/visibility端点退役(恒 404114001)、runs.one_live_run_per_workspace索引已 DROP(pgstore.go迁移处)、业务码114004退役(doc/40 §4.1)。 另:不再有「游离会话」——每场会话都挂一个项目(没指定就用该成员的默认项目,存量游离会话在下一场 run 时归位), 产出因此落项目目录、会话目录只放会话自己的档案(子代理 wire / .media)→ 删会话不再留孤儿文件。 真源关系:租户、token、会话默认私有看 doc/28。附件的目标落点是本篇第 0 节第 2 条和第 6 条。 doc/32 里「字节落在会话目录、占位 path 带sessions/<sid>/」那一版已经被本篇换掉。 回执仍按 doc/32:read_media_file只写 size 和 sha,不把图字节写进对话。 施工面只有yk-tako-eino/。 不在本篇:前端页面(2026-10-23 已由 doc/44 落地)。删除项目时连带删会话已由 doc/37 落地(2026-10-21)。
0. 已拍的六条
开工时前五条按推荐项生效。第 2 条、第 5 条在 2026-10-20 重拍。第 6 条同一天补上。
- 挂在同一个项目上的所有会话,共用一个物理目录
tenants/<tid>/workspaces/<wid>/。A 会话的 agent 写下的文件,B 会话的 agent 在同一路径读得到。 - 附件永远挂 workspace。目标工作区是会话行上的
workspace_id;这一列为空时,落到第 6 条的默认工作区。字节在tenants/<tid>/workspaces/<wid>/.media/<sha16>.<ext>,占位 path 是workspaces/<wid>/.media/<sha16>.<ext>。取图和模型读图按这个工作区的可见性查,复用VisibleWorkspace。图跟着容器走:项目是tenant,同租户成员取得到图;项目或默认工作区是private,只有属主取得到。会话自己的visibility不决定这张图谁能取。agent 的工作产出仍按今天的规则:挂了项目进项目目录,没挂进会话目录。存量sessions/<sid>/.media/清掉,旧占位 path 直接 404,不做两套路径并存。施工分成三拍,三拍都已写。A8a 做默认工作区,以及「会话和这次请求都没有项目」时入口图的字节目录。A8b 把占位 path、getMedia、已经挂上项目的入口图换到工作区。A8c 让模型按工作区读图,并在进程启动时清掉sessions/<sid>/.media/。 - 删除只删空项目。项目下还有会话时回 409,先把会话挪走。空项目删表行,并递归删掉项目目录。连带删会话另立拍。默认工作区即使下面没有会话也不能删,见第 6 条。2026-10-21 doc/37 已落地,本条里「项目下还有会话时回 409」和「连带删会话另立拍」不再作施工依据:有会话改为连带软删,
114002退役;项目下有活 run 回114006,删单场会话遇到活 run 回114007。 - 项目只有创建者能看、能改名、能删(2026-10-22 形态收窄,doc/42)。表上的
visibility列保留但只写private——跨成员共享项目已退役:GET /api/workspaces?scope=tenant不再有任何作用(与不传同形),PATCH /api/workspaces/:id/visibility端点退役(恒 404114001)。 ⚠️ 别混:会话自己的visibility(private/tenant,同租户成员可读对方的对话)不受影响——那是 doc/28 的另一码事;退役的只是项目与文件的共享。 POST /api/runs不带workspaceId→ 挂该成员的默认项目(没有就当场建,doc/35 §0 第 6 条)。2026-10-22 形态收窄(doc/42):不再有「游离会话」——每场会话都挂一个项目,产出落项目目录。存量会话(workspace_id为空)在下一场 run 时归位到默认项目。附件照旧落工作区的.media/(内容寻址)。- 每个(租户,用户)有一个私有默认工作区。
workspaces.is_default为 true 时,部分唯一索引(tenant_id, user_id) WHERE is_default保证这一对至多一行。插入冲突就是闸,闸在库里。id 仍是随机的ws_,名字是「默认」,visibility是private。创建、列表、改名和普通项目相同,列表响应里不额外露出is_default。它特殊的两处:解析附件目标时,会话和这次请求都没有项目,就用这一行,没有就当场建;DELETE回 HTTP 409{"code":114005,"message":"默认工作区不能删除","data":null},行不删,目录不删。注册时不建这行。纯文本的游离 run 也不建。同租户的另一个用户有自己的一行,默认列表互相看不见。团队里不设「全员共用的一个默认工作区」,否则一个人的私人附件会进所有成员的眼。
1. 背景与动机
doc/28 落地之后,一个租户看不到另一个租户的会话和文件。同一个租户里面,文件仍按一场会话一个目录隔开。agent 的文件工具根是 tenants/<tid>/sessions/<sid>/。
用户在租户 t_acme 里做「Q4 调研」,连开三场会话。第一场让 agent 写下 中间产物.md。第二场想接着改,agent 调用 read_file("中间产物.md") 失败:文件根是第二场自己的目录,第一场的文件在隔壁 sessions/<sid>/ 里。用户只能把内容复制过去。一个月后想把这几场翻出来继续,会话列表是平铺的,哪几场属于哪件事只能靠标题回忆。
tenant 管租户之间的隔离,session 管一场对话。中间缺的那一层,是同一件事的多场对话,加上它们共用的文件。这一层叫项目,表名 workspaces。
项目是 tenant 下的一行表记录,外加一个目录。表管归属和名字,目录管字节。会话挂进项目后,这场 run 的 agent 以项目目录为工作根。没挂的会话,包括全部存量,维持现状。「按项目切换」是每次请求自己带 workspaceId 做筛选。当前看哪个项目,由前端记住。多副本下服务端不保存「我正在看哪个项目」。
2. 名词
- 项目(workspace):
workspaces表一行。id以ws_开头,后面是 ULID。列还有tenant_id、user_id(创建者)、name、visibility、is_default、created_at。visibility是private或tenant。is_default为 true 的那一行是第 0 节第 6 条的默认工作区。磁盘路径是<workspace>/tenants/<tid>/workspaces/<wid>/。<workspace>是启动参数-workspace,沿用现义,不改这个参数的名字。 - 作业根:一场 run 里,agent 的文件工具和 bash 的工作目录。今天是
tenants/<tid>/sessions/<sid>/。挂上项目之后是tenants/<tid>/workspaces/<wid>/。 - 游离会话:
sessions.workspace_id为 NULL 的会话。全部存量会话都是游离的。以后建会话时不传workspaceId,也是游离的。这个词只描述作业根。附件另有归属,见第 0 节第 2 条。 - 默认工作区:当前租户里、当前用户名下、
is_default为 true 的那一行项目。没有这行时,第一次要给游离会话落附件才会建。 - active tenant:access token 里的
tid。POST /api/auth/switch-tenant切换它。新建项目挂在这个租户下。
A1 只插入表行,不建磁盘目录。目录在 A3:worker 起一场已经挂上项目的 run 时创建。一个项目如果还没有任何 run,盘上可以还没有 workspaces/<wid>/。A6 删除时空目录不存在,RemoveAll 也算成功。
3. 用户原话怎么落
| 用户原话 | 落法 |
|---|---|
| 系统支持多 tenant | 现状已有(doc/28),本篇不动 |
| tenant 下面每个 user 能建多个项目目录 | workspaces 带 tenant_id 和 user_id。POST /api/workspaces |
| session 挂到某个项目下 | sessions 加可空列 workspace_id。POST /api/runs 的请求体加可选 workspaceId |
| 一个目录对应多个 session | 挂同一个项目的 session,作业根都是 workspaces/<wid>/ |
| 按项目切换 | GET /api/sessions?workspaceId= 做无状态过滤。后端没有「当前项目」 |
| 删除 | DELETE /api/workspaces/:id。创建者才能删。还有会话则 409。空则删行并删目录 |
4. 端到端链路
用户注册或登录,token 带上 active tenant。
POST /api/workspaces,body 是{"name":"Q4 调研"}。服务端用 token 的 tenant 和 user 插入一行,回 201。这一跳是 A1,代码已经写上。POST /api/runs带workspaceId。请求字段是text,不是input。postRuns先确认这个项目当前用户看得见:自己创建的,或本租户visibility=tenant的。对不上则 404,code114001,不建 run。对得上,新会话仍由服务端铸sessionId(请求里不带这个字段)。AcquireRun只在插入新sessions行时写下workspace_id,写入前锁的是看得见的项目行。请求里带了未登记的sessionId,仍是 404{"code":112001,"message":"找不到这场会话","data":null},不建行。已有会话再带workspaceId也不改这一列,挪进挪出走 A5 的 PATCH。下一场 run 的作业根看的是库里的列,不看这次请求。已经挂上的会话再发消息时,按这一列再看一次项目;成员已经看不见,同样 114001,不建 run。- worker 起 run,读 session 行的
workspace_id。有值,作业根是tenants/<tid>/workspaces/<wid>/。没有值,作业根仍是tenants/<tid>/sessions/<sid>/。 - agent 调用
write_file("中间产物.md"),字节落在项目目录。同一项目的另一场会话再read_file("中间产物.md"),读得到。 GET /api/sessions?workspaceId=ws_x只返回挂在这个项目上的会话。不带这个参数时,返回这个用户能看到的全部会话,含游离的。PATCH /api/sessions/:id,body{"workspaceId":""},把会话解绑。{"workspaceId":"ws_x"}则挂上去。解绑之后,已经写在项目目录里的文件留在原地。下一场 run 的作业根跟着新的归属走。- 项目下已经没有会话时,
DELETE /api/workspaces/ws_x删掉表行,并递归删掉目录。成功是 HTTP 200{"code":0,"message":"","data":{"status":"deleted"}}。还有会话则 409,code114002。会话行不删。
链路可以点名:用户 → postWorkspaces 或 postRuns(server.go)→ AcquireRun(store.go)→ worker 起 run 时调用 runWorkspace(worker.go)→ scope.go 的目录解析 → listSessions。挪进挪出走 patchSessionWorkspace → SetSessionWorkspace。删空项目走 deleteWorkspace → DeleteWorkspace,提交之后 RemoveAll。A1 到 A6 已经接通。入口图在 postRuns 里先走 imageRoot。已有会话只看会话行上的项目;新会话看这次请求的 workspaceId。两边都空时,EnsureDefaultWorkspace 取出或建出默认工作区。字节写到 workspaces/<wid>/.media/,占位 path 是 workspaces/<wid>/.media/<sha16>.<ext>。登录后的 GET /api/media 先 Clean 这条 path,再按 VisibleWorkspace 决定能不能读。看不见回 404 {"code":114001,"message":"找不到这个项目","data":null}(2026-10-22 换信封,见 doc/40)。read_media_file 用同一条 path:先查 VisibleWorkspace,再从租户根下的 workspaces/<wid>/ 读。回执带 size 和 sha,不带图字节。sessions/<sid>/... 读不到。进程启动时删掉各租户 sessions/<sid>/.media/,工作区里的 .media 不动。dev 探针继续用会话目录。
5. 分拍
| 拍 | 用例 | API | 存储 | 状态 |
|---|---|---|---|---|
| A1 | 建项目 | POST /api/workspaces |
新表 workspaces |
已落地 + curl 验收(e30d1f9) |
| A2 | 列表、改名、创建者边界 | GET /api/workspaces,PATCH /api/workspaces/:id |
同一张表 | 已落地 + curl 验收(e30d1f9) |
| A3 | 在项目里开聊,文件互通 | POST /api/runs 加可选 workspaceId |
sessions.workspace_id;磁盘 workspaces/<wid>/ |
已落地 + curl 验收(e30d1f9) |
| A4 | 按项目看会话 | GET /api/sessions?workspaceId=;详情带 workspaceId |
同一列 | 已落地 + curl 验收(e30d1f9) |
| A5 | 挪进、挪出 | PATCH /api/sessions/:id 接 workspaceId,空串表示解绑 |
同一列 | 已落地 + curl 验收(e30d1f9) |
| A6 | 删空项目 | DELETE /api/workspaces/:id |
删行,并 RemoveAll 目录 |
已落地 + curl 验收(e30d1f9) |
| A7a | 项目可见性、团队列表 | PATCH /api/workspaces/:id/visibility;GET /api/workspaces?scope=tenant |
workspaces.visibility,默认 private |
已落地 + curl 验收(e30d1f9) |
| A7b | 成员在共享项目里新开会话 | POST /api/runs 不带 sessionId、带 workspaceId |
新会话 user_id 是成员,workspace_id 是项目,会话 visibility 是 private |
已落地 + curl 验收(e30d1f9) |
| A7c | 创建者看见并解绑别人的会话 | GET /api/sessions?workspaceId=;PATCH 空 workspaceId |
只改列,不删会话,不搬文件 | 已落地 + curl 验收(e30d1f9) |
| A7d | POST /api/runs 抢闸失败回 409,code 114004 |
runs.workspace_id 上 status='running' 的部分唯一索引 |
已退役(2026-10-22,doc/42):项目闸随跨成员共享项目一起取消;同项目并发不再被拒,改由文件级防护兜(flock + 写前指纹比对,doc/19-v6-08) | |
| A8a | 每人一个私有默认工作区;没挂项目的入口图字节落进去 | DELETE 命中默认工作区回 409,code 114005 |
workspaces.is_default;部分唯一索引 (tenant_id, user_id) WHERE is_default |
已落地 + curl 验收(e30d1f9) |
| A8b | 占位 path 和取图换到工作区 | GET /api/media 按 VisibleWorkspace |
占位 path workspaces/<wid>/.media/… |
已落地 + curl 验收(e30d1f9) |
| A8c | 模型按工作区读图,清掉旧目录 | read_media_file |
租户根下的工作区目录;启动时删除旧 sessions/<sid>/.media/ |
已落地 + curl 验收(e30d1f9) |
施工时的纪律:每拍做完停下等验收,不自动 commit。
2026-10-21 收口:13 拍全部落地并 curl 验收过,随
e30d1f9入库。A6 的删除语义已由 doc/37 改写(2026-10-21 已落地):有会话改为连带软删,114002退役;项目下有活 run 回114006。第 0 节第 3 条与 §10 的错误码表是现行口径,本表 A6 那一行是当时的施工口径。
6. A1 契约:POST /api/workspaces
调用者是已登录用户。路由挂 RequireAuth。归属不从 body 取:tenant_id 用 token 的 tid,user_id 用 token 的 sub。
POST /api/workspaces
Authorization: Bearer <accessToken>
Content-Type: application/json
{"name":"Q4 调研"}
成功是 HTTP 201。字段顺序是 code、message、data,项目对象里是 id、name、createdAt:
{"code":0,"message":"","data":{"workspace":{"id":"ws_…","name":"Q4 调研","createdAt":"2026-10-19T12:00:00.123456+08:00"}}}createdAt 是 Go time.Time 的 RFC3339。响应不带回 tenantId 和 userId,这两列只在表里。同名项目可以有多行,名字不是唯一键。这一拍不建磁盘目录。
名字先去掉首尾空白。去掉之后是空字符串,HTTP 400:
{"code":114003,"message":"请填写项目名称","data":null}请求体不是 JSON,HTTP 400,code 111001,message 是「请求格式不对」。
没带 token,HTTP 401:
{"code":111102,"message":"请先登录","data":null}插入失败,HTTP 500,code 111901,message 是「服务暂时不可用,请再试一次」。具体错误只进服务端日志。
7. 后面几拍的契约
A2 到 A6 已经按下面的形状写进代码。
A2 列表。 GET /api/workspaces。条件是 tenant_id 等于 active tenant,并且 user_id 等于当前用户。按 created_at、再按 id 升序。没有项目时 workspaces 是空数组,不是 null。成功是 HTTP 200:
{"code":0,"message":"","data":{"workspaces":[{"id":"ws_…","name":"Q4 调研","createdAt":"…"}]}}同租户的另一个用户看到的是 {"code":0,"message":"","data":{"workspaces":[]}}。他后来自己建的项目只出现在他自己的列表里。
A2 改名。 PATCH /api/workspaces/:id,body {"name":"…"}。名字的空白规则和创建相同,空名称仍是 HTTP 400,code 114003。只有创建者能改。成功是 HTTP 200,体和创建一样,createdAt 不变:
{"code":0,"message":"","data":{"workspace":{"id":"ws_…","name":"Q4 调研(改)","createdAt":"…"}}}别人来改、项目不存在、或者 active tenant 对不上,都是 HTTP 404。不存在和无权看用同一个响应,避免靠状态码区分出别人有这个项目:
{"code":114001,"message":"找不到这个项目","data":null}A3 挂接。 POST /api/runs 增加可选字段 workspaceId。预检失败是上面的 404,并且 sessions 和 runs 都不新增行。预检在会话准入之前。未登记的 sessionId 再加一个对不上的 workspaceId,回 114001。workspaceId 对得上、sessionId 却未登记,仍是 404 {"code":112001,"message":"找不到这场会话","data":null}。预检通过之后,新会话的 workspace_id 写成这个 id。worker 起 run 时读这一列:有值就 MkdirAll 到 tenants/<tid>/workspaces/<wid>/,没有值就仍用 sessions/<sid>/。2026-10-20 在 127.0.0.1:8904 打过:项目里的 hello.md 内容是 abc;同一项目的另一场会话 read_file 读到 abc;不带 workspaceId 的 free.md 落在会话目录;已有游离会话再带上合法 workspaceId,列仍是 NULL,新文件仍进会话目录。
A4 筛选。 GET /api/sessions?workspaceId=ws_x 只返回挂在这个项目上的会话。参数先按创建者预检:对不上是 HTTP 404 {"code":114001,"message":"找不到这个项目","data":null}。项目在、下面没有会话,则是 HTTP 200 {"code":0,"message":"","data":{"sessions":[]}}。不带这个参数时,本人的全部会话都在,含游离的。过滤加在现有 scope 上,默认仍是本人。列表项在原字段后加 workspaceId,游离时为 null。GET /api/sessions/:id 仍是旧的成功体,字段顺序是 liveRunId、runlogOffset、lastRunStatus、lastRunId、workspaceId。游离会话的 workspaceId 是 null,键仍在。2026-10-20 在 127.0.0.1:8904 打过:项目 ws_01M5AEXM2D81379KN6HC2FKATN 的过滤结果是两场挂着的会话,游离的 s_01M5AEXP8PT5XKX6VPX3E17SZT 只出现在不带参数的列表里。
A5 挪动。 新增 PATCH /api/sessions/:id,与现有的 PATCH /api/sessions/:id/visibility 并存。body 必须带 workspaceId。{"workspaceId":"ws_x"} 挂上。{"workspaceId":""} 解绑;去掉首尾空白后仍是空,也解绑。字段缺席,或 JSON 值是 null,是 HTTP 400 {"code":111001,"message":"请求格式不对","data":null},不会当成解绑。挂上之前做和 A3 相同的项目预检。对不上是 HTTP 404 {"code":114001,"message":"找不到这个项目","data":null},列不改。门槛是 sessions.user_id 等于当前用户。看不到这场会话的人,仍是 404 {"code":112001,"message":"找不到这场会话","data":null}。同租户里能看见、但不是本人的,是 HTTP 403 {"code":111204,"message":"只有本人能修改","data":null}。成功是新信封 HTTP 200。挂上时 data.workspaceId 是项目 id,解绑时是 null。已经写下的文件留在原地。下一场 run 的作业根读更新后的列,不搬旧文件。
2026-10-20 在 127.0.0.1:8904 打过。用户沿用 A3 的 u_01M5AEXM1X5FCWHDM3M26TFVJW,项目 ws_01M5AEXM2D81379KN6HC2FKATN,会话 s_01M5AEXP8PT5XKX6VPX3E17SZT。
- 挂上:200
{"code":0,"message":"","data":{"workspaceId":"ws_01M5AEXM2D81379KN6HC2FKATN"}}。详情的workspaceId是这个 id。 workspaceId为ws_no:404,code114001。列仍是这个项目。- 另一个用户来解绑:404
{"code":112001,"message":"找不到这场会话","data":null}。同租户、能看见但不是本人的 403 这一拍没有单独打。 - body 是
{}:400{"code":111001,"message":"请求格式不对","data":null}。 - 挂上之后让 agent 写
moved-in.md:202,runr_01M5AFQD87GNKZGEE5AR09FAAB,状态complete。文件在项目目录,字节是in,不在会话目录。hello.md和free.md仍在原处。 - 解绑
{"workspaceId":""}:200{"code":0,"message":"","data":{"workspaceId":null}}。详情是{"liveRunId":"","runlogOffset":12,"lastRunStatus":"complete","lastRunId":"r_01M5AFQD87GNKZGEE5AR09FAAB","workspaceId":null}。 - 解绑后再写
moved-out.md:202,runr_01M5AFQF8BS3FFVZCH1BPRGS84,状态complete。文件在sessions/<sid>/,字节是out,不在项目目录。hello.md和moved-in.md仍在项目目录。列是 NULL。
A6 删除。 DELETE /api/workspaces/:id。同一笔事务里锁住创建者自己的项目行,数 sessions.workspace_id 等于这个 id 的行。大于 0 则整笔回滚,HTTP 409:
{"code":114002,"message":"项目里还有会话,先挪走再删","data":null}等于 0 则删行,提交之后再 RemoveAll 项目目录。目录还没建过,RemoveAll 也算成功。别人的项目、已经删掉的项目,都是 HTTP 404 {"code":114001,"message":"找不到这个项目","data":null}。没带 token 是 HTTP 401 {"code":111102,"message":"请先登录","data":null}。
DELETE /api/tenants/:id 回的是 HTTP 200 {"code":0,"message":"","data":{"status":"archived"}},因为那一拍是归档。项目删除是真删,成功体因此用 deleted:
{"code":0,"message":"","data":{"status":"deleted"}}新建会话写入 workspace_id、以及 PATCH 把会话挂进项目时,也锁同一行。删除持有锁的时候,挂接会等到锁释放;行已经没了,挂接就回 114001,不会把列写成一个已删的 id。反过来,挂接先提交,删除的计数能看见这场会话,于是回 114002。
2026-10-20 在 127.0.0.1:8904 打过。用户 u_01M5AEXM1X5FCWHDM3M26TFVJW,项目 ws_01M5AEXM2D81379KN6HC2FKATN 上还有两场会话。当时目录里 hello.md 的字节是 abc,moved-in.md 的字节是 in。
- 没登录就删:401,code
111102。 - 创建者来删:409,code
114002。两个文件还在。 - 另一个用户
u_01M5AGN5V10AK3A4D27CC0S4NG来删:404,code114001。创建者再删仍是 409。 ws_no:404,code114001。- 从没建过目录的空项目
ws_01M5AFDV316H8FB7FFFNDAYJMR:200,data.status是deleted。再删一次是 404。列表里不再有它。 - 另一个用户自己的
ws_01M5AGN5W3X46JGAJK9T2P0595:创建者去删是 404,对方自己删是 200deleted。 - 两场会话解绑之后,
GET /api/sessions?workspaceId=这个项目是 200{"code":0,"message":"","data":{"sessions":[]}}。再删项目:200deleted。目录没了,hello.md和moved-in.md一起没了。三场会话还在,workspace_id是 NULL。游离会话目录里的free.md字节仍是free-ok。 - 再删同一个 id,以及再用这个 id 过滤会话,都是 404,code
114001。
8. 这一篇明确不动的部分
| 保持原样 | 原因 |
|---|---|
媒体落盘和 getMedia 的路径检查 |
2026-10-19 刚收掉的路径问题。项目只装 agent 的工作产出 |
存储上限 rejectStorage / directoryBytes |
上限数的是 tenants/<tid>/ 整棵目录。项目目录在这棵下面,会被数进去 |
子代理槽、tenant_usage_daily |
配额按 tenant 算,项目不新开一档配额 |
sessionWorkspace 现有的三处调用里,媒体和 dev 探针那两处 |
这两处要维持会话目录。只改 worker 起 run 时选根的那一处 |
| 游离会话和存量行 | 可空列加可选参数,不做迁移 |
POST /api/auth/switch-tenant |
租户切换已经有了。项目不在服务端记「当前项目」 |
| runs、sessions、mcp、media、memory 的旧成功体 | 换成 {code,message,data} 是 doc/28 的 A7,不借这一篇改 |
9. 存储与多副本
Workspace 经 GORM AutoMigrate 建表,不另写迁移文件。这和 pgstore.go 里现有表的建法相同。
列表会按 tenant_id 加 user_id 查,所以建表时带了复合索引 workspaces_owner。
归属和权限都在 PG 的行上。worker 起 run 时从 session 行读 workspace_id,再决定作业根。没有进程内缓存,也没有用 channel 等「当前项目」。多副本要读到同一批文件,仍然靠 -workspace 指向同一块共享盘。项目目录是 tenant 目录的子树。
10. 错误码
新码用 114 段。身份模块的 111 段不拿来表示项目不存在。
| code | 场景 | HTTP | 哪一拍开始用 |
|---|---|---|---|
114001 |
项目不存在,或当前用户不是创建者 | 404 | A2 |
114002 |
项目里还有会话,不能删 | 409 | A6 起用;2026-10-21 起退役,删除项目不再返回,码位不重用 |
114003 |
项目名称去掉空白后是空的 | 400 | A1 |
114004 |
— | 已退役(2026-10-22,doc/42;同项目并发不再被拒) | |
114005 |
默认工作区不能删除 | 409 | A8a |
114006 |
项目下有活 run,拒绝删除项目 | 409 | doc/37 D1 |
114007 |
会话下有活 run,拒绝删除会话 | 409 | doc/37 D3 |
114003 的 message 是「请填写项目名称」。tenant 名称是空的仍用 111003「请填写工作区名称」。两个空名称不是同一件事,页面靠 code 区分,弹窗文案用各自的 message。114006 的 message 是「项目里有正在运行的会话,等它跑完再删」。114007 的 message 是「这场会话正在运行,等它跑完再删」。114002 从 2026-10-21 起不再返回。
可见性不是 private 或 tenant,以及 body 里没有 visibility 字段,用已有的 111002,message 是「可见性只能是 private 或 tenant」,HTTP 400。缺 JSON 仍是 111001「请求格式不对」。不是创建者,或项目不存在,仍是 114001。
成功和失败都回 code、message、data。失败且没有额外内容时 data 是 null,字段仍在。HTTP 状态保持 400、401、404、409、500,不把失败收成 200。
11. A1 的代码落点
| 事情 | 落点 |
|---|---|
Workspace 结构体、CreateWorkspace、AutoMigrate |
yk-tako-eino/internal/runengine/pgstore.go |
POST 处理 |
product_api.go 的 postWorkspaces |
| 列表和改名 | product_api.go 的 listWorkspaces、patchWorkspace;存储是 ListWorkspaces、RenameWorkspace |
| 路由 | server.go 的 POST、GET /api/workspaces 和 PATCH /api/workspaces/:id,中间件是 RequireAuth |
| 空名称业务码 | auth.go 的 codeWorkspaceNameRequired,值 114003 |
| 找不到项目 | auth.go 的 codeWorkspaceMissing,值 114001 |
| 挂接 | server.go 的 postRuns 预检 VisibleWorkspace;AcquireRun 插入 workspace_id;scope.go 的 workspaceRoot、runWorkspace;worker.go 起 run 时调用 runWorkspace |
| 按项目列会话、详情带项目 | server.go 的 listSessions、getSession;ListSessions 增加 workspaceID 条件 |
| 挪进、挪出 | server.go 的 PATCH /api/sessions/:id 指向 patchSessionWorkspace;存储是 session_access.go 的 SetSessionWorkspace |
| 删空项目 | product_api.go 的 deleteWorkspace;存储是 pgstore.go 的 DeleteWorkspace。挂接和新建会话写列前调用 lockOwnedWorkspace。目录路径是 scope.go 的 workspaceDir,删除时不创建目录 |
| 项目闸 | runs.workspace_id 加部分唯一索引 one_live_run_per_workspace(status='running')。AcquireRun 写入这列;冲突时 postRuns 回 409,code 114004 |
| 项目可见性 | workspaces.visibility,默认 private。product_api.go 的 patchWorkspaceVisibility;存储是 SetWorkspaceVisibility。listWorkspaces 在 scope=tenant 时列本租户已共享的项目。路由是 PATCH /api/workspaces/:id/visibility |
| 成员新开会话 | VisibleWorkspace 认创建者或本租户 visibility=tenant。新建会话用 lockVisibleWorkspace。已挂上的会话在 AcquireRun 里用 seeVisibleWorkspace 再看一次,不加第二把项目锁。删除和 PATCH 挪进仍用 lockOwnedWorkspace |
| 创建者解绑别人的会话 | ListSessions 在默认列表筛到创建者自己的项目时,不再按 user_id 收窄。SetSessionWorkspace 在 workspaceId 为空、且会话正挂在创建者的项目上时,允许创建者解绑。改挂仍要会话主人 |
| 默认工作区 | workspaces.is_default,部分唯一索引 one_default_workspace_per_user。pgstore.go 的 EnsureDefaultWorkspace 在自己的事务里先查、再在保存点 default_ws 里插入;唯一冲突就回滚到保存点,再读已有的那一行。server.go 的 imageRoot 在目标工作区为空时调用它。DeleteWorkspace 在锁住创建者的行之后、数会话之前,看到 is_default 就回 ErrWorkspaceDefault。deleteWorkspace 把它写成 409,code 114005。业务码常量在 auth.go 的 codeWorkspaceDefault |
| 入口图换锚 | imageRoot 返回工作区目录和前缀 workspaces/<wid>/。ingestImagesAt 把字节写进该目录的 .media/。parseSessionMediaPath 先 Clean,再认 workspaces/<wid>/。getMedia 有登录身份时用 VisibleWorkspace,字节从 tenants/<tid>/workspaces/<wid>/ 读。没有身份时仍相对 -workspace 根 |
| 模型读图 | filetools.go 的 resolveReadMediaPath。workspaces/<wid>/ 先过 VisibleWorkspace,再从 WorkspaceRef.TenantRoot 下的这个工作区读。sessions/<sid>/ 直接报文件不存在。newReadMediaFileTool 收 *Store,在 worker.go 里单独装配。回执函数仍是 mediaReceiptPlaceholder。media.go 的 ClearSessionMedia 在 cmd/yktako/main.go 启动时调用 |