tako 文档 GitHub

Handoff · 多租户运行时,2026-10-19 全改之后

性质:现状交接。给下一场会话读,让它不用翻这场对话就能知道代码停在哪、哪些 curl 已经打过、哪些口还开着。 触发:用户问「现在是还有什么问题吗」,接着说「写个 handoff」。 状态:媒体两处 P0 和当时列开的 P1 已落地,并在 127.0.0.1:8903 打过。model_ref、tools、worker 按租户配置装模型和 MCP、A7 信封,都还没做。 这份文件不是开工令。 下一场要改上面还开着的口,先等用户点头。不要自行宣布版本号。不要 commit,除非用户明确说留。 取信:下面的字节和文件名是 2026-10-19 当日实读、实打。台账 tmp/28-多租户/ 被 gitignore,换机器就没了,以本文件和 doc/28-多租户.md、doc/32-media-offload.md 为准。 前置阅读:doc/28-多租户.md(方案,头注仍不标「已验收」)→ doc/32-media-offload.md(占位行;2026-10-19 那一段写了登录后的路径)→ 本文件。AGENTS.md 的协作顺序仍然有效:契约、curl、再改代码。

1. 接手时仓库在哪

HEAD 是 29f9d18,提交说明是长期记忆与对话召回。多租户从 A0 到今天的全改,全部在这颗提交之上,没有 commit。git status 会看到 yk-tako-eino/internal/runengine/ 里一大片修改,以及未跟踪的 auth.go、identity_store.go、product_api.go、product_store.go、sandbox.go、scope.go、secretseal.go、session_access.go、tenant_api.go 和对应测试。doc/28-多租户.md、doc/32-media-offload.md、AGENTS.md 也是脏的。

施工面只有 yk-tako-eino/。yk-tako-eino-backup/ 是旧实现的冻结存档,不要改。v1/v2 的 run 级协议、用 409 表示「会话忙」的旧语义、旧单页前端,都不作论据。

真源划分没变:方案在 doc/,执行台账在 tmp/28-多租户/planning.md 和 todos.md。台账第 12 节记了 8903 的 curl 字节。doc/28 第 4 节的表已改成和 Go 结构体一致,头注仍写着「不标已验收」。

2. 这场对话收掉了什么

用户要的是多租户 agent 运行时。2026-10-18 把 A0 到 A6 的 API 写进了工作区。2026-10-19 的检查认为台账不能当成验收通过:上传的图和后来读取不在同一目录,getMedia 能借 .. 读到兄弟会话,另外还有邀请、密钥、沙箱、配额四条 P1。用户先让把团队助手的 spec 接进这场 run,再让「全改」把媒体和这些 P1 做完。助手预检那一段没有再改。

2.1 上传、取图、模型读图走同一条路径

一个人上传一张图时,postRuns 先铸好 sessionId,再把字节写进 <workspace>/tenants/<tid>/sessions/<sid>/.media/<sha 前 16 位>.<扩展名>。user 行里的占位 path 是 sessions/<sid>/.media/<sha16>.ext。GET /api/media?path= 和 read_media_file 用这同一条字符串。read_media_file 只在路径以本会话的 sessions/<sid>/ 开头时剥掉这段前缀,再在会话目录里解析。文件工具的根仍是这场会话的目录,没有放宽到租户根,所以 write_file 到不了兄弟会话。

没做这步时的失败是:占位写着 .media/...,页面按登录身份去租户根找,模型按会话根找,三处对不上,本人打开自己刚传的图也是 404。

2026-10-19 在 127.0.0.1:8903 打过。8 字节小图 POST /api/runs 返回 202,sessionId 是 s_01M5812GVTAVEDX5PFMKV1DGBA。占位 path 是 sessions/s_01M5812GVTAVEDX5PFMKV1DGBA/.media/26807183f40c3844.png。本人 GET 是 200,响应体就是那 8 个字节。另一个用户用同一条 path 是 404 {"error":"not_found"}。带登录身份去取不带 sessions/<sid>/ 的 .media/26807183f40c3844.png,也是这个 404。盘上文件在会话目录的 .media/ 里。

抢闸之前如果后面 400、413 或 409,会话目录里可能留下内容寻址文件。落库面仍然是空的。这是接受的残留,不是再开一条清理拍。

2.2 getMedia 先 Clean,再查清完的会话

同租户的 member 能看一场 visibility=tenant 的会话。他把 path 写成 sessions/<这场看得见的>/../<别人的 private 会话>/.media/secret.png。旧代码只把第一段会话 id 交给 SessionAccess,Clean 之后路径仍在租户根里,于是读到别人的文件。

现在 parseSessionMediaPath 先 Clean。上面那条会变成别人的会话 id。访问检查用清完的 id。看不见就是旧体 404 {"error":"not_found"},不是 400。没有登录身份时,getMedia 仍相对 mediaRoot,单测 TestGetMediaEndpoint 走这条:越界 400,缺文件 404。

8903 上,member 用穿越 path 得到 404 {"error":"not_found"}。owner 用清完之后的真实 path 是 200,字节相同。

2.3 团队助手的 prompt 已经进这场 run

tenant_agents.spec 是 prompt 正文,不是模型名,也不是工具名单。postRuns 在 AcquireRun 之前决定这场用哪个助手:请求里的 agentId 优先,没带就用 sessions.agent_id。然后 VisibleAgent。看不见则 404 {"code":112003,"message":"找不到这个助手","data":null},不建 run。角色门槛只卡「这次请求新带了 agentId」。抢闸成功之后,只有请求里带了 agentId 才 UPDATE sessions.agent_id。

worker 的 resolveRunInstruction 读这一列,把 spec 放进 ctx,newRunAgent 的 Instruction 用它。折叠和笔记快照重写走同一段。空 spec 是合法值。没绑助手时仍用进程启动时的系统提示。助手若在预检之后才消失,worker 把这场 run 收成 error,不用全局提示顶上。这条 error 不能拿来论证「POST 没做预检」。

2026-10-19 更早一场 curl(同一天、引擎后来停了):spec 要求回复恰好是 SPEC-OK3。带 agentId 的 POST 是 202,log 里 assistant 的 text 是 SPEC-OK3。同一会话下一条不带 agentId,回复仍是 SPEC-OK3。sessions.agent_id 是 ag_01M57X42WYP1RQ02GF01YK26M0。未知 id ag_does_not_exist 是上面的 404。

newRunAgent 的 Model 仍是 w.chat,Tools 仍是 w.tools。子代理仍 LoadAgentSpecs("agents") 读磁盘上的 agents/*.md,不读 tenant_agents。

2.4 过期邀请在注册之前拒绝

register-by-invite 若先 Signup 再发现邀请过期,库里会多一个用户和他的个人 tenant,团队成员关系却没写成。现在在 bcrypt 和 Signup 之前就看邀请仍是 pending 且 ExpiresAt 未过。过期则 404 {"code":111405,"message":"邀请无效或已过期","data":null}。

8903:先把 tenant_invitations.expires_at 改到一小时前,再注册。响应就是这条 404。users 里这个邮箱前后都是 0 行。LookupInvitation 仍只按 token_hash 查,公开预览还要能看到状态,所以过期判断放在注册入口,没有放进 LookupInvitation。

邀请若在这次检查和后面的 AcceptInvitation 之间那一下才过期,仍可能先建出用户。curl 没打到这个缝。

2.5 runtime secret 不再明文落库

admin PUT /api/tenants/:id/runtime-config 时,PutRuntimeConfig 先读旧配置,再 sealSecrets。密钥是 TAKO_JWT_SECRET 的 SHA-256,算法是 AES-GCM,库存前缀是 seal1:。空串和已经带这个前缀的值原样通过。GET 经 maskSecrets 把非空 secret 显示成「••••」。客户端把这四个点 PUT 回去,或整段不带 secrets,都沿用库里的密文。存量明文在下一次 GET、且环境变量够长时,会顺手封存回库。

8903:PUT secrets.apiKey=sk-live-plain 之后,tenant_settings.config 含 seal1:,不含这串明文。GET 的 apiKey 是「••••」。再 PUT 掩码,以及再 PUT 一次不带 secrets,三次读出的 config 相同。

worker 装配 MCP 的地方仍是 mcpToolHandler,confPath 是 defaultMcpConfPath(mcp.json)。newRunAgent 不用 tenant_settings.config 里的 modelRef。落库和掩码已经成立。这场 run 换了模型或 MCP,还没有成立。

2.6 沙箱要真的 apply 成功才算隔离

sandboxAvailable 不只 LookPath("sandbox-exec")。它会跑一次 sandbox-exec -p "(version 1)(allow default)" /bin/echo ok,退出码是 0 且输出含 ok 才算可用。结果用 sync.Once 缓存在这个进程里。requireSandbox 为真而探测失败时,startBash 直接返回「这台机器的 sandbox-exec 不能 apply,不能把工作目录当成隔离」,sandboxed 是 false,不跑裸 bash。dev 探针 POST /api/dev/workspace/bash 的 sandboxed 字段跟着这次探测走。

这次在这台 Mac 上 apply 成功。dev bash 的 body 是 {"code":0,"message":"","data":{"output":"退出码:0\nstdout:\nok\n","sessionId":"s_01M5812HYJQZ66J96FG0E2H3JZ","sandboxed":true}}。TestBashTimeoutMessage 也过了,大约 1 秒。同一台机器上 apply 曾经被拒绝,所以这一条不能单独当稳定门禁。探测失败时测试会 t.Skip。Linux 上通常没有 sandbox-exec,生产 bash 同样拒绝。doc/28 第 2.3 节和第 9.4 节写了这件事。

2.7 子代理槽和存储帽按租户算

有 Redis 时,delegationTool.InvokableRun 只走 trySubagentSlot(键 tk:subagents:<tenant>)。进程级 sem 只在 store 为空或 rdb 为空时使用,单测 TestDelegationToolForwardsOptsAndGates 仍靠它证明「满闸时取消不会调用内层」。TestDelegationRedisSkipsProcessSem 把进程 sem 填满,内层工具仍然被调用。没有另打「两个租户同时让模型委派」的 curl。

存储帽数 <workspace>/tenants/<tid>/ 整棵目录,上限 0 表示不限制。write_file 经 rejectStorage。入口图在 ingestImagesAt 里、抢闸之前数已用字节加本张大小。超帽则 429 {"code":113001,"message":"这个工作区的额度用完了","data":null},不建 run。dev 写文件探针不走这道帽。

8903:团队目录里已经有那张 8 字节的图,把 max_storage_bytes 改成 1,再对一场新会话 POST 另一张图。响应是上面的 429。这个租户的 runs 行数前后都是 2。两个人同时上传,都可能在写入前看到「还没超」,然后都写进去。这是目录计数的缝,不是单次超帽还能建 run。

2.8 表和文档对齐过的地方

doc/28 第 4 节现在写的是代码里的样子:tenant_settings 只有一列 config JSON;表名是 tenant_agents,id 前缀 ag_;邀请 id 前缀 in_,没有 accepted_at,状态含 declined;refresh_tokens 有 tenant_id;notes.user_id 是 not null default '',scope=tenant 写入的是创建者,不是 NULL。tenants 上有 max_concurrent_runs、max_subagents、daily_tokens、max_storage_bytes,后两列 0 表示不限制。

3. 还开着的口

这三块是产品上还没接上的能力。下一场不要把「列已经在库里」或「GET 能读到」写成「这场 run 已经按它跑」。

3.1 助手的模型和工具名单

owner 给团队助手填了 model_ref 和 tools,member 用这个 agentId 发消息。现在会 202,prompt 换成 spec,模型和工具仍是进程启动时的那一套。用户以为选了这个助手就换了模型,实际仍打到 TAKO_MODEL 配的那个模型,工具也仍是全局池。子代理更是读 agents/*.md,和库里的 tenant_agents 无关。

要接的话,改的是 newRunAgent 的 Model 和 Tools,以及子代理装载。预检逻辑(请求或已存的 agent_id,VisibleAgent,看不见就 404 且不建 run)保持不动。空 model_ref 应该是什么、工具名单和磁盘规格怎么合成,用户还没拍,不要在交接里自己定死。

3.2 租户的模型和 MCP 还没进 worker

admin 把模型和 MCP 写进 tenant_settings.config。member 打开设置页能看到掩码后的 secret。下一场 run 启动时,mcpToolHandler 仍打开 mcp.json,w.chat 仍是启动参数里的模型。A 租户配的 key 不会被 B 租户的 run 用到,也没有被 A 自己的 run 用到。unsealSecret 已经写好,worker 还没调用它。

把配置接进 worker 时,不要把 seal1: 密文当成明文去连 MCP。GET 的「••••」也不能写回库。

3.3 旧接口的成功体

新的产品错误用信封 {code,message,data},字段顺序是 code、message、data,失败时 data 为 null 但键在。旧的 runs、sessions、log、frames、mcp、media、memory 成功体仍是原来的 JSON。media 和会话找不到时仍是 {"error":"not_found"} 或 {"error":"session_not_found"}。内部故障仍是 {"error":"internal"}。整包换成信封是 A7,这轮明确不做。团队前端是独立 loop,不在这份交接里开工。

常用码:111405 邀请无效,112003 找不到助手,113001 这个工作区的额度用完了,111204 没有权限做这件事(写和 stop 的 owner 门槛;有的路径文案是「只有本人能修改」)。

4. 下一场不要动的东西

5. 环境与复验

Go 不在 PATH。在 yk-tako-eino/ 下:

export PATH="$HOME/sdk/go1.27.0/bin:$PATH"
export TAKO_JWT_SECRET='dev-only-jwt-secret-change-me-32bytes'
export TAKO_ACCESS_TTL=15m
export TAKO_MODEL=deepseek/deepseek-v4-flash
go run ./cmd/yktako -engine 127.0.0.1:8903 \
  -redis 127.0.0.1:6390 \
  -pg "host=127.0.0.1 port=5433 dbname=tako sslmode=disable" \
  -workspace "$PWD/tmp/ws-p0"

TAKO_JWT_SECRET 至少 32 字节,否则封存 secret 会失败。.env 会被 godotenv 加载,但盖不过已经导出的变量。Postgres 是 127.0.0.1:5433,库名 tako。psql 在 $HOME/dev/ykcode/learn-golang/otel-ch-native/bin/postgres/bin/psql。Redis 是 127.0.0.1:6390。不要动 6379 和 5432,那是另一套活实例。

单测打真实例,不要 skip:

go test ./internal/runengine/ -count=1 -timeout 240s

2026-10-19 全改之后这一条通过,internal/runengine 22.429s。注册用 POST /api/auth/signup,密码至少 8 个字符,响应在 data.accessToken 和 data.tenant.id。要管别的工作区,先 POST /api/auth/switch-tenant,URL 上的 tenant 必须等于 token 里的 active tenant。

6. 代码落点

事情 落点
铸会话 id、落图、超帽 429、助手预检 server.go 的 postRuns
占位 path、parseSessionMediaPath media.go 的 ingestImagesAt
登录后的取图 server.go 的 getMedia
模型读占位 path filetools.go 的 sessionRelativeMediaPath,只包了 read_media_file
会话目录和租户目录字节 scope.go 的 sessionWorkspace、tenantStorageRoot、directoryBytes
这场 run 的 prompt worker.go 的 resolveRunInstruction、newRunAgent
MCP 仍读 mcp.json worker.go 里 mcpToolHandler 的 defaultMcpConfPath
邀请过期 product_api.go 的 registerByInvite
封存 secret secretseal.go;product_store.go 的 GetRuntimeConfig、PutRuntimeConfig、maskSecrets
沙箱探测 sandbox.go 的 sandboxAvailable、startBash
子代理闸 agents.go 的 delegationTool.InvokableRun;scope.go 的 trySubagentSlot
助手表 product_store.go 的 TenantAgent,表名 tenant_agents

7. 所以这份交接解决了什么

下一场不用从对话里重建「哪些口已经 curl 过、哪些列在库里却还没进 worker」。媒体、邀请过期、secret 密文、沙箱探测、租户存储帽和 Redis 子代理槽,按第 2 节的字节已经收掉。助手的 model_ref 和 tools、租户 MCP 与模型进 worker、旧接口的信封,按第 3 节仍开着。用户点头之前,不要把第 3 节写成下一行代码。

2026-10-19 后续:团队 agent / 子代理 md / 租户 model key / 系统与自定义 MCP 的运行时装配,另见 doc/34-租户运行时装配.md。本文件只记录到当前交接时点。