42 · 产品形态收窄与共享项目退役
性质:已落地(2026-10-22)。三件拍板项全部施工并验收:① 跨成员共享项目退役 ② 项目闸退役 ③ 不再有游离会话(每场会话都挂项目)。 状态:✅ 已施工。验收结论(2026-10-22):可见性判定只剩属主(
pgstore.go三处 SQL +ListWorkspaces的 scope 分支);PATCH /api/workspaces/:id/visibility端点留着路由恒回 404114001(摘掉路由会让 gin 的默认 404 接管,前端接不住 doc/40 的信封),SetWorkspaceVisibility存储方法退役留档;业务码114004退役(doc/40 §4.1 登记);runs.one_live_run_per_workspace索引在迁移处 DROP(幂等)——同项目并发不再被 409 挡;每场 run 自动挂该成员的默认项目,存量游离会话下一场 run 归位。 随44cf7ca入库(2026-10-22):形态收窄的代码与文档都在那一笔。 日期:2026-10-22。 代码落点:yk-tako-eino/internal/runengine/{pgstore.go,store.go,product_store.go,product_api.go,server.go,auth.go,filetools.go};前端 0 处(§3.1 S7);契约文档doc/19-v6-04与doc/40 §4.1(114004退役登记);台账tmp/42-形态收窄/(本地,不入库)。 与 doc/16 的关系:给总纲补一节「产品形态与资源模型」,并改 §2 能力表 #9/#12/#13 三行、§5.1 排序与 §0.1 的判断句。 与其他文档的关系:改写 doc/35 的「共享」语义;改 doc/28 §15 与 doc/36 的项目切换面;给 doc/41 §7 补一句前提条件(闸退役依赖它)。 决定来源:用户 2026-10-22 拍板——① 不做跨成员共享项目 ② 项目是资源管理单位、项目文件多 session 共享 ③ 项目闸退役 ④ 游离会话强制挂默认项目 ⑤visibility列留 ⑥ 开放问题 1 走 Kimi 的内容锚定路线 ⑦ doc/16 §0.1 判断句要改。
0. 背景与动机
0.1 起因
2026-10-22 复核运行时机制时,把「共享项目」这件事从机制层一路追到了产品层,追出来的不是某个 bug,而是产品形态没定:
- 代码里有一道「项目闸」:同一项目同时只允许一场 run 在跑(
pgstore.go:512-515的部分唯一索引one_live_run_per_workspace),撞了就回 409「项目正在另一场会话里运行」(server.go:418)。 - 当年定这道闸的理由写得很清楚(
tmp/35-项目目录/planning.md规则 8):共享目录让两场 run 第一次写同一块可变状态,失败是无声的——A 的 agent 正在重写output/report.json,B 的 agent 同时读它,读到写了一半的字节;更糟的是 bash:B 的 agent 起手rm -rf output/,A 十分钟的产物消失,两道 run 都报「成功」,没有一方收到错误。 - 同一份台账里也写了正解:「哪天真要同时改,正确解是乐观并发(write_file 写前校验读时版本、变了让模型重读重做),不是放宽闸——留为远期缝,v1 不做」。
也就是说:闸不是最终解,是在"改不动写协议"的前提下选的替代方案。 而「共享项目」这个产品能力本身,从来没有被当成一个产品决定拍过——它是一路从「多租户隔离」长出来的副产品。
0.2 为什么现在要收窄:三个理由,只有一条致命
| 理由 | 成立吗 | 说明 |
|---|---|---|
| 共享文件的多人在线同时修改 | 成立,且致命 | 这是另一个产品:协同编辑要 CRDT/OT、在线状态、冲突合并、版本历史、撤销重做。tako 现在的形态是「agent 写文件 + 帧流回页面」,没有这个地基。 |
| 权限是问题 | 可解,不致命 | 可见性模型已经在(workspaces.visibility 两值 + 三处判定),真要做不难。 |
| 共享目录的存储是问题 | 可解,不致命 | 配额与计量都已有(租户级整树统计),要做只是加粒度。 |
准确的表述(比"难做"硬得多,也好讲得多):
「共享文件」真正要做的是协同编辑。tako 不做协同编辑 → 于是共享项目这条线整条不立。
这条护栏与 doc/16 §4「不做 RAG/知识库产品」同款:它是一条边界,不是一个待补的功能。
0.3 砍掉之后,tako 是什么
tako 是多租户的 AI 工作台:一个员工 = 一个项目,项目里有多场对话。 团队共享的是账号、额度、审计;不共享文件。不做协同编辑(共享文件的多人同时修改)。
不是什么(新增一条,与 §4 RAG 护栏并列):
不做协同编辑 / 共享文件的多人同时修改。 项目是个人的:别人看不见你的项目、读不到你的文件、进不去你的 run。
1. 名词准入(操作定义,后文只用这几个词)
| 名词 | 真身(长什么样) | 谁能碰 |
|---|---|---|
| 租户 | tenants 表的一行 = 一个组织;users 表里 tenant_id 指向它 |
管理员 + 成员 |
| 成员 | users 表一行 = 一个员工账号;tenant_members 记谁在租户里 |
本人 |
| 项目 | workspaces 表一行 = 成员自己的一个工作项目;物理目录 tenants/<tid>/workspaces/<wid>/;只有属主可见(visibility 恒为 private)。一个项目里有多场会话,项目的文件由这些会话共享。 |
只有属主 |
| 会话 | sessions 表一行 = 项目里的一场对话;物理目录 tenants/<tid>/sessions/<sid>/,只放会话自己的档案(.tako/ 子代理 wire、.media/) |
只有属主 |
| 产出 | agent 写出的文件(报告、代码、中间件) | 落在项目目录里,不在会话目录里 |
| 闸 | 一条 PG 部分唯一索引,插不进去就是撞了 | 闸在库里,不在进程里 |
产品叫法 ↔︎ 代码叫法(本文统一用产品叫法,代码里仍叫 workspace/工作区):
| 本文说 | 代码/表里叫 | 备注 |
|---|---|---|
| 项目 | workspaces 表 / workspace_id 列 / workspaceDir() |
不打算改代码命名——改名的收益是零,代价是全仓字符串替换与迁移风险 |
| 项目目录 | tenants/<tid>/workspaces/<wid>/ |
物理路径不变 |
| 默认项目 | workspaces.is_default = true 的那一行 |
今天叫「默认工作区」(doc/35 §0 第 6 条),它本来就是 private,退役后正好接上 |
| 跨成员共享项目 | visibility = 'tenant' 的项目 |
本次退役的那个(本文 §3.1)。它与上面的「项目」不是一回事:上面的是个人的,这个是多人可见的 |
⚠️ 消歧提醒:本文之后「项目」一律指个人项目(多 session 共享文件);被退役的那个一律写全称**「跨成员共享项目」**。
2. 资源模型(本文的主轴)
2.1 三层三个单位
| 层 | 单位 | 文件归属 | 用量计量 | 生命周期 | 闸 |
|---|---|---|---|---|---|
| 租户 | 租户 | 全树 | 额度总上限 + 日 token | 租户删除 | 租户并发闸(待修,见 §4.3) |
| 项目 | 项目(= 资源管理单位) | 项目目录 | 算到项目 | 删项目 = 递归删目录 + 连带删它下面的会话目录 | 本次退役 |
| 会话 | 会话 | 会话目录(只有档案) | 并入项目 | 删会话 = 删会话目录(含产出落点调整后不再有孤儿) | 会话闸(一场会话一场 run)保留 |
2.2 产出落点要跟着改(这是本次改动里最实的一处)
现状(今天):产出和会话档案混在同一个会话目录里——sessions/<sid>/ 下既有 .tako/、.media/,也有 agent 写的 report.md。挂了项目的会话,产出落项目目录;没挂的,落会话目录。
改后:拆成两层,各归各的。
tenants/<tid>/
├── workspaces/<wid>/ ← 项目:产出落这里(报告、代码、中间件)
│ └── .media/ ← 附件(内容寻址 sha16,并发写是 no-op)
└── sessions/<sid>/ ← 会话:只放会话自己的档案
├── .tako/subagents/*.jsonl ← 子代理 wire
└── .media/ ← 旧媒体兜底
这么改顺带解掉一个真缺口:今天删会话只清 .tako 与 .media,产出文件原地留下(product_api.go:269-282 的注释写明「产出留在会话目录里」),于是软删会话的产出成了没人认领的孤儿,还继续吃租户配额(配额按 tenants/<tid> 整棵树算,worker.go:479)。产出挪到项目层之后,删会话不再产生孤儿——垃圾只有一种(会话档案),而垃圾的清理路径已经存在。
项目要成为默认落点(用户 2026-10-22 拍板:游离会话强制挂默认项目):既然项目是资源管理单位,它就该是默认的作业根——每个成员有一个默认项目(今天叫「默认工作区」,workspaces.is_default),会话默认挂在它下面。不再保留"不挂项目"的游离会话(那类会话的产出落会话目录 → 删会话后成孤儿 → 与 §2.2 的解法直接冲突)。挂载点在建会话时定死,不再提供"游离"这个选项。
2.3 闸退役后,项目里两场会话同时跑会怎样
先说清楚退役后剩下什么:
| 原闸挡的场景 | 退役后 |
|---|---|
两个员工同时改同一目录(A 的产物被 B 的 rm -rf 删掉) |
不存在了——项目是个人的,别人进不来 |
| 同一个人的两场会话同时写同一个文件 | 仍在。后果:自己覆盖自己,或一场会话的 rm -rf 删掉另一场的产物 |
所以闸退役不是白退,它把"防人"换成了"防 agent 互相踩"。这一档怎么处理,取决于两件事:
- 危险 bash 由 doc/41 的人审闸收掉(doc/41 §3.1:v1
bash 一律 ask,deny 表优先)——rm -rf output/这种要人点头。这是闸退役的前提条件,§6 的 Loop 顺序因此把 doc/41 排在前面。 - 同名文件覆盖:靠内容锚定(下节 Kimi 的做法)——冲突要显式失败让模型重读,不能静默覆盖。
2.4 同文件冲突:抄 Kimi 的做法(2026-10-22 核对 ref-agent/kimi-code)
Kimi 的三层(packages/agent-core-v2/):
| 层 | 实现 | 干什么 | 粒度 |
|---|---|---|---|
| ① 同文件写串行 | src/agent/toolExecutor/toolScheduler.ts:17-70 + src/tool/toolContract.ts:184-206(ToolAccesses.conflict) |
每个工具声明它对文件的访问集(读/写/搜 + 路径);两个调用有一个是写且路径重叠 → 后来的排队等前面的跑完 | 文件(不是项目/工作区) |
| ② 未声明访问集 = 访问一切 | src/agent/toolExecutor/toolExecutorService.ts:438:execution.accesses ?? ToolAccesses.all() |
bash 没声明访问集 → 按「访问一切」算 → 与所有文件操作串行(bash 能动一切,所以它必须独占) | 工具级 |
| ③ 内容锚定的乐观并发 | src/app/edit/fileEditService.ts(read → apply old_string → write)+ src/agent/tools/edit/edit.md |
Edit 锚定精确 old_string;文件被改过 → 报 old_string not found → 模型必须重读。契约里还明写:「写锁只保证同文件编辑按响应顺序串行,串行化不能让陈旧的 old_string 变有效」 |
字段级 |
| ④ Write 禁增量覆盖 | src/agent/tools/os/write/write.md |
「Write is NOT ALLOWED for incremental changes to existing files … Use Edit instead」+「Read before overwriting an existing file」→ 增量修改必须走 Edit | 工具契约级 |
抄哪几层,抄不了哪一层(这是关键,不能照抄):
| Kimi 的层 | tako 现状 | 结论 |
|---|---|---|
| ① 同文件写串行(进程内) | Eino ToolsNode 默认并行;跨 run 更是跨进程/跨副本 | 抄,但换手段:进程内 mutex 只管一个进程 → 改用 flock(OS 级,同机跨进程跨副本都串),比 Kimi 强一档 |
| ② bash = 访问一切 → 独占 | tako 无「访问集」概念 | 不抄——被下面的 ④ 覆盖;且 bash 超时 30 秒(bash.go:16),让它持全局锁会30 秒内阻塞整个项目的文件写(Kimi 是单进程桌面应用,才敢这么干) |
| ③ Edit 内容锚定 | tako 的 edit_file 已经是同款(filetools.go:255-270:OldText 精确匹配,不匹配就报错让模型重读) |
已有 ✓ |
| ④ Write 禁增量覆盖 | Kimi 那条其实是 prompt 级(writeTool.ts:88-92 的实现是 fs.writeText(path, content)——整份覆盖、零检查);tako 的 write_file 同样无约束(filetools.go:120-140) |
抄,但要做成程序级(tako 的 ③ 比 Kimi 的 ④ 还硬) |
| ⑤ 真 CAS(版本号 + 原子递增) | 无 | 抄,但版本号用文件系统指纹((mtime, size, sha256)):零状态、跨机天然成立、不碰 PG |
⚠️ 本节 2026-10-22 16:53 修正两处(前一条消息里的分析有错,已按代码复核改正):
- 「内容锚定不保证写回的整体是最新的」——错。
edit_file的第一步是编辑时刻现读磁盘(filetools.go:257),写回时用的也是它 → 别的写者在你读之后落盘的改动,会被原样带过去。所以内容锚定 + 现读 = 只在"锚点那一段"被并发改动时才失败,别的段落不失败、也不会被抹掉。丢更新的真实窗口因此从「模型读→模型写」(几秒到几分钟)压到「程序读→程序写」(微秒到几十毫秒)。 - 「不需要任何跨 run 的锁」——要限定。 跨机没有共享锁可依(flock 只在同机有效),但可以做显式失败:写前比对指纹,变了就拒(跨机成立,因为判据是文件本身)。同机则用 flock 真串行。
落到 tako's 结论:
乐观并发 = 四件事(2026-10-22 已落地,见
tmp/文件写入并发/): ① flock 写锁(粒度=文件;锁文件tenants/<tid>/.tako/locks/<桶号>.lock(256 桶:锁键 =sha256(路径)首字节 % 256 → 锁文件数恒 ≤ 256,锁目录永远不大);接进write_file/edit_file/move_file)——同机全串,跨机看共享盘是否支持 POSIX 锁(CephFS/NFSv4 ✓;NFS 崩溃后要等 lease ~30s)→ 部署前提要钉; ② Edit 内容锚定(tako 已有):old_text精确匹配,且编辑时刻现读 → 别的写者的改动被带过去; ③ write_file 写前比对指纹(新落地):没读过 → 拒;读过但内容变了 → 拒(引导改用edit_file);读过但文件被删/移走 → 拒。判据 = 从磁盘现算的sha256(内容级;>64MB 降级 mtime+size 且显式标注弱判据); ④ run 级基准表(新落地,内存,键 = agent 名 + 绝对路径):「我读到的是哪一版」。不落库、不跨 run 共享、零清理。关键:比对必须在锁内做——锁让「检查—写」成为原子的一段(否则两者之间有缝);快照让「拒」成为可能。只有锁 → 照样用旧版覆盖;只有快照 → 检查与写不原子。
诚实边界:跨机的极窄窗口(指纹比完到写之间)关不掉——共享文件 + 无协调的写者这个模型下没有免费的原子 CAS(
rename是 last-writer-wins;O_EXCL只对新建有效),而 bash 绕过工具层会让任何外部协调状态与磁盘脱节。要 100% 就得禁止并发,那等于把闸请回来,与本文直接矛盾。 本篇的选择是:允许并发,冲突显式失败。不做:Redis 锁 / PG advisory lock(flock 够;Redis 也是 advisory 的、对 bash 一点帮助没有,还要 TTL + 新依赖 + 破坏 doc/38 的「Redis 只留两键」收敛);版本号表(版本信息只取自目标文件自身,避免「文件写了 version 没跟上」的裂缝);rename 日志(「B 把文件移哪去了」查不到,机制补不了)。
当时的展开施工:tmp/文件写入并发/(planning.md + todos.md,七拍:W1 指纹+基准表 → W4a 锁封装 → W2 write 判据 → W4b edit/move 接入 → W3 edit 基准+单测 → W5 文案 → W6 收口;现已落地,临时目录不保留)。当时的拍序理由是:比对必须在锁内 → 先把锁封装好再写判据,否则返工。当前代码仍是 flock + SHA256 指纹(>64MB 降级为 mtime+size,且显式标注弱判据);多副本 PG 锁与原子替换的后续方向见 doc/71(方案待点头),不把该方案写成本篇已经落地。
所以开放问题 1 落定:闸退役后,同文件冲突靠** flock + 内容锚定 + 写前指纹比对**处理;bash 的写由 doc/41 的人审兜底。乐观并发从"远期缝"提上来,与闸退役同批。
3. 退役清单(代码)
逐处可点名。每处都标了「退役后变成什么」与「验收怎么看」。
3.1 跨成员共享项目退役
| # | 位置 | 现状 | 退役后 |
|---|---|---|---|
| S1 | pgstore.go:146 Workspace.Visibility |
default:'private',两值 |
列保留,不写 tenant(用户 2026-10-22 拍板)。删列要迁存量行,收益只有"少一列" |
| S2 | pgstore.go:185-186(scope=tenant 列举) |
GET /api/workspaces?scope=tenant 列全租户可见项目 |
scope 参数退役:只列属主的(scope 参数本身可以留着当 no-op,或直接删参数 → 字节要定) |
| S3 | pgstore.go:262 / 294 / 411(可见性判定) |
(user_id = ? OR visibility = 'tenant') |
简化为 user_id = ?(三处) |
| S4 | product_api.go:120(scope=tenant 注释与分支) |
同 S2 | 同 S2 |
| S5 | product_api.go:176(创建时的 visibility 校验) |
允许 private/tenant |
只允许 private;传 tenant → 回什么字节要定(建议 400 111001 理由「不再支持团队可见」) |
| S6 | server.go:97 PATCH /api/workspaces/:id/visibility |
改可见性的端点 | 端点退役:回什么字节要定(建议 404 114001「找不到这个项目」——端点不存在与目标不存在同形) |
| S7 | web/src/ |
前端一行都没调过 workspaces 端点(项目目录页本来就没做,doc/35 头注写明「项目目录的前端页面明确不在本篇」) | 前端零改动;反而省掉「项目目录页」这个前端欠账(doc/16 §5.1 第 4 项要改;2026-10-23 已由 doc/44 落地) |
| S8 | web/src/Configure.vue:445 |
有 visibility 下拉(private/tenant) |
不动——那是 agent 的可见性(doc/34 租户 agent 配置),与项目可见性是两码事。⚠️ 极易误伤,代码评审时盯住这一处 |
默认工作区(is_default)不受影响:它本来就是 private(doc/35 §0 第 6 条),退役后它就是"每个成员的默认项目"——正好接上 §2.2。
3.2 项目闸退役
| # | 位置 | 现状 | 退役后 |
|---|---|---|---|
| G1 | pgstore.go:512-515 one_live_run_per_workspace |
部分唯一索引(workspace_id WHERE status='running') |
索引删除,但必须两拍(顺序有讲究,见下) |
| G2 | store.go:233-256(AcquireRun 抢闸段) |
SAVEPOINT project_gate + 唯一冲突 → 判 errGateBusy / errProjectBusy |
冲突兜底保留(不再区分"项目忙"),等 G1 的索引删掉后它自然永不触发 |
| G3 | server.go:417-419 |
409 114004「项目正在另一场会话里运行」 |
分支退役(统一并到会话忙的码)。该码未进 19v6-01/19v6-04,也未进 scripts/acceptance/expected.json → 契约字节影响面小(核过) |
| G4 | auth.go:167 codeWorkspaceBusy = 114004 |
常量 | 退役(码表 doc/40 §4 同步标退役或留空) |
| G5 | product_api.go:215 codeWorkspaceBusyLive = 114006 |
删项目时有活 run → 409 | 保留——那是删除闸(doc/37),与项目闸无关 |
G1 的两拍顺序(为什么不能一把梭):
唯一索引是数据库层面强制的——代码不做任何检查,INSERT 撞了照样报错。所以两件事的顺序会决定"中间那段时间用户看到什么":
| 顺序 | 中间窗口里发生什么 | 后果 |
|---|---|---|
| 先删索引,再发新代码 | 索引没了 → 老代码的"冲突分支"永远不触发 → 老副本静默放行两场并发 | 闸的保护提前消失(窗口 = 从 DDL 到滚动完成)。不报错,但保护没了 |
| 先发新代码(且不留兜底),再删索引 | 索引还在 → 新代码的 INSERT 撞唯一约束 → 没人翻译这个错误 → 500 | 用户看到"服务暂时不可用"(随机:老副本 409、新副本 500)。报错,但是错的那种 |
| 先发新代码(保留 409 兜底),再删索引 ✅ | 索引还在 → 新旧代码都把冲突翻译成 409 → 用户看到的与今天一模一样;索引删掉后两边都不再冲突 → 并发真的放开 | 没有坏行为的窗口 |
所以两拍是:R2a = 代码侧把"唯一约束冲突"统一成 409(不再有"项目忙"的专属语义),索引不动 → 行为零变化;R2b = 执行 DROP INDEX IF EXISTS one_live_run_per_workspace(纯 DDL)→ 并发真的放开。多副本下 DDL 在所有副本升级完之后执行;此时老副本的行为也已经是"新行为"(它不再期待冲突),所以没有不一致窗口。
3.3 闸退役带来的新问题:项目内并发
同一项目两场会话同时跑,runs 表上不再有约束拦着 → 两场 run 都进 worker.Run → 都往项目目录写。处置:
- 帧面不冲突(
runlive按 runId 分键)✓ - mh / runlog 不冲突(按 session 分)✓
- 文件层会撞(见 §2.3)→ 前置条件是 doc/41 的 bash 审批闸 + 后续的乐观并发
4. 影响面清单
4.1 文档
| 文件 | 改什么 |
|---|---|
doc/16 |
① §0 加护栏「不做协同编辑」;② 新增 §0.2「产品形态与资源模型」(四句话 + 三层表);③ §2 能力表 #9 备注里的「组织共享」移出、#12 语义改成「个人项目」、#13 跟着调;④ §5.1 第 3 项去掉「组织共享」、第 4 项去掉「项目目录页」、撤销「乐观并发 v1 不做」(若 §8 开放问题 1 通过);⑤ §0.1 那句「剩下的是产品外围」要改(另见 §4.4) |
doc/28 |
§15 同步:并行会话 2026-10-22 已把「团队计费 / API key / SSO / 组织共享 / 审计导出」整组移出路线图;本文落地的是「组织共享」那一半的技术侧退役(代码与契约),商业化那几项不归本文 |
doc/35 |
整篇的「共享」语义降级为「个人项目」;A7d 那一条(项目闸)标退役;补「产出落项目层、会话目录只放档案」的新形状 |
doc/36 |
团队前端的「工作区切换」面重新界定:切的是我自己的项目,不是同事的项目(前端本来就没做项目页,实际影响小) |
doc/41 |
§7「不做沙箱」补一句前提:闸退役依赖本文的 bash 审批闸;§3.1 的 gate 规则里「写类文件工具目标在工作区外 → ask」的口径要跟新的项目语义对齐 |
doc/README |
新增 42 行;同批同步 16/28/35/36/41 五行 |
4.2 代码
见 §3 逐处。总量估计:后端 8~10 处(含 3 处可见性判定简化 + 抢闸段整段删),前端 0 处(项目页本来没做)。
4.3 顺带修的两处(本次形态收窄的副产品,量小)
先澄清「租户闸」是什么(容易误会):它不是"租户之间"的闸。不同租户的数据互相隔离、互不可见,本来就没有共享资源要争。它是同一个租户内同时最多跑几场 run 的上限(
max_concurrent_runs,默认 8),保护的是共享资源:模型供应商的 API 配额与成本、同一台机器的 CPU/内存。 所以它与本文退役的「项目闸」是两码事:项目闸管"一个项目内能跑几场"(管的是共享文件),租户闸管"一个租户总共能跑几场"(管的是算力与成本)。前者随本文退役,后者留下但要修。
- 租户并发闸改成 DB 约束 → 已落地(2026-10-23,doc/43)。原状:
overQuota(product_api.go:26-57)用CountLiveRuns读-判-写 → 并发下可超发(两个请求都读到 7 < 8 就都放行,实际 9 场在跑;2026-10-23 活体实测:上限 2,并发四打进来 4 场)。落地形态:数活 run 与插 run 行收进同一笔 PG 事务,中间持一把所有副本共享的顾问锁(pg_advisory_xact_lock)→ 并发下不可能超发。无 DDL、无存量迁移、计数口径逐字不变(僵尸行不算活 → 不误拒)、契约字节不变(满租户仍回 429113001)。槽位唯一索引那种「插入冲突=满」的形态没选(要 DDL + 存量回填 + 全租户僵尸清扫),取舍见 doc/43 §3。 - 并发额度分成员:现在并发额度是租户共享池(一个成员占满 8 场,其他人全被挡),且它与日 token 配额共用同一个业务码
codeQuota与同一句文案(product_api.go:41-56)→ 用户分不清是 token 没了还是并发满了。形态定成"租户=员工的集合"后,并发额度该能分到成员。
这两条不在本文的必做范围(用户 2026-10-22 拍板:不同批做)。它们是"租户=员工集合"这句话的直接推论。 注意区分:额度分档(计费)已随「团队计费」整组移出路线图(2026-10-22 用户裁);但并发闸是运行时闸、不是商业化项——它现在有竞态、且被单个成员占满就挡住全租户,这一条仍建议修(与本文的闸退役同属"闸要真"这一族)。
4.4 不在本文、但同源的两处(提醒,别混进来)
- MCP 进程无围栏 → 跨租户泄漏 → 已修(2026-10-22):租户自己配的 MCP 进 seatbelt 围栏,围栏根 = 该租户的存储根;平台的系统 MCP 不围栏;没有沙箱 → fail closed;command 必须在租户目录内(依赖要预装到租户目录里);连接缓存的键含围栏根。详见 doc/33。
- 失败不留痕 → 已落地(2026-10-22):失败轮「已产出的内容」照落库(runlog + mh),前端收口也拉 log。
- 召回块在 mid-run 折叠时被抹掉 → 已由另一方案解决(2026-10-22,
f4df5ef):召回块进「本轮输入」并写回 mh 的 seq=1,折叠重建时从 mh 取 → 块活过折叠。属召回块那条方案的事,不在本篇范围。
这两条已还(2026-10-22):失败留痕已落地(doc/19-v6-03 + doc/30 + doc/16 §0.1 判断句同批改);召回块活过折叠由另一方案解决(f4df5ef)。归属说明:召回块那条属召回块方案的事,不在本篇范围。**
5. 数据与迁移
| 数据 | 现状 | 处置 |
|---|---|---|
workspaces.visibility = 'tenant' 的行 |
开发库可能有,线上待查 | 迁成 private(一行 UPDATE),或保留列但不再读(两者都安全,因为判定改成只看 user_id) |
workspaces.is_default 行 |
每(租户,用户)一行,private |
不动,它就是新的"默认项目" |
sessions.workspace_id 指向的项目 |
会话挂载点 | 保留(项目仍在,只是变成个人的) |
| 项目目录里的文件 | 已有产出 | 不动(形状本来就对,只是语义从"共享"变"个人") |
runs.workspace_id 列 |
闸的载体 + 删除闸要用 | 保留列(114006 删除闸还在用),只删索引 |
6. Loop 拆分(点头后逐拍施工;每拍先交 todos.md)
顺序:P(前置:doc/41 的人审闸)→ R1(跨成员共享项目退役)→ R2a(闸退役·代码侧)→ R2b(闸退役·DDL 侧)→ R2c(内容锚定)→ R3(形态落文档)。 为什么 doc/41 在前:闸退役后,危险的 bash 就没有第二道防线(§2.3)。人可以先不点头 doc/41,但那时 R2 不许开工。
| 拍 | 改什么 | 怎么验收(curl 第一) | 回答什么 |
|---|---|---|---|
| R0 | (前置)doc/41 Loop A 的 A1–A4 落地 | POST /api/dev/seed-approval 造行 → POST /api/approvals/:id/decide 批 → bash 调用真的执行了 |
危险 bash 已经有人点头这道闸 |
| R1a | ✅ 已落地(2026-10-22):可见性判定三处简化(pgstore.go 的 seeVisibleWorkspace / lockWorkspace / VisibleWorkspace)+ scope=tenant 列举退役(ListWorkspaces 只列属主,scope 参数保留但已退役) |
GET /api/workspaces → 只列属主的 |
跨成员可见性真的断了 |
| R1b | ✅ 已落地(2026-10-22):PATCH /api/workspaces/:id/visibility 端点退役(留着路由恒回 404 114001——摘掉路由会让 gin 的默认 404 接管,前端的信封拆包器接不住);SetWorkspaceVisibility 存储方法退役(留档在注释里);游离会话强制挂默认项目(新会话在 postRuns 里挂默认项目;存量游离会话在下一场 run 时归位) |
PATCH /api/workspaces/<id>/visibility → 404 114001;新会话 workspaceId 非空 |
对外契约:不再有"团队可见",也不再有"游离会话" |
| R2a | ✅ 已落地(2026-10-22):唯一约束冲突统一回 errGateBusy(不再有"项目忙"的专属语义),索引暂不动的过渡拍 |
同一项目连投两条 → 409 | 行为零变化的过渡拍(为 R2b 铺路) |
| R2b | ✅ 已落地(2026-10-22):迁移处 DROP INDEX IF EXISTS one_live_run_per_workspace(幂等,每次启动跑一遍);业务码 114004 与它的 409 分支退役(doc/40 §4.1 已登记) |
同一项目连投两条 → 两条都 202 | 项目内不再整层排队 |
| R2c | 同文件冲突防护(展开在 tmp/文件写入并发/,七拍:W1 指纹+基准表 → W4a 锁封装 → W2 write 判据 → W4b edit/move 接入 → W3 edit 基准+单测 → W5 文案 → W6 收口):flock 写锁(粒度=文件;同机全串,跨机看存储——CephFS/NFSv4 ✓)+ 写前指纹比对(判据 = 从磁盘现算的 sha256,>64MB 降级为 mtime+size 且显式标注弱判据;比对必须在锁内)+ run 级基准表(键 = agent 名 + 绝对路径) |
两场会话同时改同一文件 → 后者收到「它跟你读到的不一样了,先 read_file 或改用 edit_file」而不是静默覆盖;同机两场并发写 → flock 串行 | 闸退役后不留下静默覆盖 |
| R3 | 文档同批:doc/16(§0 护栏 + §0.2 形态 + §2 表 + §5.1 + §0.1 判断句改写)、doc/28、doc/35、doc/36、doc/41、doc/README | ./scripts/check-master-plan.sh 通过;doc/16 §0.1 的判断句已改 |
总纲的"现状"是真的 |
| R4 | 全量回归 + 活体验收 | go test ./internal/runengine + go vet + npm run typecheck + npm run build + assert_contract.py + check-expected.sh 全绿 |
两台机器都钉住新契约 |
脚手架与转正:本文不新增 dev 探针端点。R1/R2 的验收口用现有的(GET /api/workspaces、POST /api/runs、跨账号 token)。
7. 明确不做(本期)
- 协同编辑 / 共享文件的多人同时修改——本文的护栏本身(§0.3)。
- 跨成员可见的项目、跨成员可见的 agent 之外的一切共享(agent 的团队可见性不受影响,那是 doc/34 的另一码事)。
- 沙箱读围栏(
sandbox.go:50的allow read "/"):本期靠工作区围栏 + 审批,不靠目录隔离。这条 doc/41 §7 已写「不做沙箱」,本文只补一句"读侧围栏同样不做"。 - MQ 同步写入、hosted mode、扫描件 OCR 与音视频:沿用 doc/16 §5 的既有裁断,不在本轮重开。
- 版本号式的乐观并发(加列维护版本):不做。改用内容锚定——
edit_file的old_text匹配(已有)+write_file写前比对内容(新增),见 §2.4。无状态、无迁移、跨副本天然成立。
8. 开放问题(2026-10-22 已全部拍完)
| # | 问题 | 结论 | 落在哪 |
|---|---|---|---|
| 1 | 闸退役后,项目内同文件冲突怎么收? | 四件事:flock 同机写锁(粒度=文件)+ Edit 内容锚定(已有)+ write_file 写前比对指纹 + 版本号用文件系统指纹(mtime+size+sha256,不用 PG 版本号列)。bash 独占不做(被写前比对覆盖,且 30s 持锁会阻塞全项目)。不追求 100% 原子——跨机极窄窗口靠"显式失败"兜,要 100% 就得把闸请回来。展开施工见 tmp/文件写入并发/(W1–W6,待点头) |
§2.4 / tmp/文件写入并发/ |
| 2 | 游离会话(不挂项目)保留还是退役? | 强制挂默认项目——不再提供"游离"这个选项(否则它就是孤儿制造机) | §2.2 / R1b |
| 3 | workspaces.visibility 列留还是删? |
留(不写 tenant)——删列要迁存量行,收益只有"少一列" |
§3.1 S1 |
| 4 | 索引删除的顺序? | 两拍:R2a 代码侧统一回 409(索引不动,行为零变化)→ R2b 执行 DROP INDEX(并发才真的放开)。理由与三种顺序的后果对比见 §3.2 的表 |
§3.2 / R2a、R2b |
| 5 | 租户并发闸那条(§4.3)同批做吗? | 不同批。它是租户内总并发的闸(保护算力与 API 成本),不是"租户之间"的闸,与本文退役的项目闸是两码事。它现在是读-判-写有竞态、且被单个成员占满就挡住全租户——仍建议修,但另开一笔 | §4.3 |
| 6 | doc/16 §0.1 那句"剩下的是产品外围"怎么改? | 已改(2026-10-22):两条地基欠账(失败留痕、召回块活过折叠)都已还 → 判断句改为「核心循环已经跑通——成功路径、失败路径、长对话路径三条都验过;剩下的是产品外围;地基还欠审批闸与任务看板」 | §4.4 / R3 |
9. 所以这解决了什么
产品形态从"没定"变成"一句话":tako 是多租户的 AI 工作台,一个员工一个项目,团队共享账号与额度、不共享文件。 这条形态一旦写死,三件一直悬着的事当场落地:① 跨成员共享项目退役(连同它的权限分支与存储分支);② 项目闸退役——它当年挡的"两个员工互相删产物"场景,因为项目变个人的而不复存在;③ 产出与会话档案分层,删会话不再产生孤儿文件,项目的配额与清理归口明确。
同时把当年那条"乐观并发是远期缝"的搁置理由掀了:它当初被搁置是因为"闸先顶着",而闸现在要退役——但落法变了:不是加版本号列,而是抄 Kimi 的内容锚定(§2.4)——edit_file 的 old_text 匹配 tako 已经有了,只差 write_file 写前比对内容。这是无状态、无迁移、跨副本天然成立的版本,比当年设想的版本号方案便宜一个量级。
代价也要说清楚:团队叙事从"共享一个项目"收窄为"各自的项目 + 共享额度与审计",对外可讲的故事少了一条(doc/16 §2 的 #9b 团队协作前端仍在,但它讲的不再是"一起改同一个项目");跨成员共享文件这条需求从"待做"变成"明确不做"(doc/16 §5.1 第 3 项与 doc/28 §15 要同步改口)。这是定位收窄,不是工程量收窄——换来的是不用去做协同编辑这个级别的地基。
10. 演进记录
2026-10-22 22:20:R1 / R2a / R2b 全部施工并活体验收通过。落地形态:① 可见性判定只剩属主 (
pgstore.go的seeVisibleWorkspace/lockWorkspace/VisibleWorkspace三处 SQL +ListWorkspaces的 scope 分支删除;scope 参数保留但已退役);②PATCH /api/workspaces/:id/visibility端点留着路由恒回 404114001(摘掉路由会让 gin 的默认 404 接管 → 前端信封拆包器接不住); ③SetWorkspaceVisibility存储方法退役(留档在注释里);④ 不再有游离会话——postRuns里没指定 项目就用该成员的默认项目(没有就当场建),存量游离会话在下一场 run 时归位;⑤one_live_run_per_workspace索引在迁移处 DROP;⑥ 业务码114004与它的 409 分支退役(doc/40 §4.1 登记)。 活体四问:同项目连投两条 → 两条都 202 ✓;PATCH .../visibility→ 404114001✓; 新会话workspaceId非空(挂默认项目)✓;跨成员可见性只认属主 ✓。 前端零改动(项目页本来没做;Configure.vue的 visibility 是 agent 的、不是项目的)。2026-10-22 16:16:建方案。事实核对基于当日实读代码:
pgstore.go:141-152(Workspace 表)、pgstore.go:185-186/262/294/411(可见性判定四处)、pgstore.go:512-515(项目闸索引)、store.go:129-285(AcquireRun 抢闸段)、server.go:94-98(工作区端点五个)、server.go:417-419(409114004)、auth.go:167/169(114004/114006)、product_api.go:120/176/215(列举、visibility 校验、删除闸)、product_api.go:26-57(租户闸与配额文案)、product_api.go:200-282(删项目 / 删会话清理)、scope.go:81-135(目录布局)、worker.go:479(配额统计口径)、web/src/(零调用 workspaces 端点;Configure.vue的 visibility 是 agent 的)、doc/16§0.1/§2/§5.1、doc/35§0/§A7d、tmp/35-项目目录/planning.md规则 8(闸的原始理由)。用户拍板:共享项目立即退役、闸退役、项目为资源管理单位、先出文档交审。2026-10-23:§4.3 第 1 条(租户并发闸改成 DB 约束)已落地——方案、形态取舍与验收见 doc/43。用户 2026-10-23 拍「DB 互斥 + 计数」(顾问锁 + 活 run 计数,收在
AcquireRun同一笔事务里),未选槽位唯一索引。活体实测:修前上限 2 并发四打 = 4 个202;修后 = 2 个202+ 2 个429(113001,字节不变)。回归网入库(存储层用例摘掉闸即红 + 活体scripts/acceptance/tenant_gate.sh)。本篇 §4.3 第 2 条(并发额度分成员 / 拆codeQuota)仍未做。2026-10-22 16:30:按用户第二轮拍板修订全文——① 命名「空间」→「项目」,并加「产品叫法 ↔︎ 代码叫法」对照表与消歧(被退役的叫「跨成员共享项目」);② 游离会话强制挂默认项目(不再提供"游离"选项);③
workspaces.visibility列留;④ 新增 §2.4「同文件冲突:抄 Kimi 的做法」——实读ref-agent/kimi-code/packages/agent-core-v2:toolScheduler.ts:17-70(同文件写串行,粒度=文件)、toolContract.ts:184-206(冲突判据)、toolExecutorService.ts:438(未声明访问集 =ToolAccesses.all()→ bash 独占)、fileEditService.ts+src/agent/tools/edit/edit.md(old_string内容锚定;契约明写"串行化不能让陈旧的 old_string 变有效")、src/agent/tools/os/write/write.md(Write 禁增量覆盖)。结论:tako 的edit_file已是同款,缺的是write_file写前校验(R2c);⑥ 闸退役索引删除的顺序讲清(§3.2 三种顺序的后果对比 → 定为 R2a 代码侧留 409 兜底、R2b 再 DROP INDEX);⑦ 澄清「租户闸」不是"租户之间"的闸,是租户内总并发(§4.3);⑧ doc/16 §0.1 判断句的改法写进 §8 第 6 条(用户已拍"改")。六个开放问题全部拍完,本文可点头开工。