34 · 租户运行时装配(团队 agent / 子代理 / 租户 model / MCP)
性质:方案。2026-10-19 用户点头。R1–R5 与 U1 已写进
yk-tako-eino/,当天在127.0.0.1:8901用 curl 验收过。U1 已在浏览器验收:登录、Root/Subagent 列表、编辑默认生成覆盖、重置、custom 增删、md 导入、runtime-config 密钥掩码、自定义 MCP failed 状态。同日补修两处页面缺口并复验:对话页接入登录态(发送不再 401、token 过期自动刷新、媒体图片带登录取回),保存 Team 设置后 MCP 状态当场重测。已提交 9c21b66,也不表示版本号跳了一档。 真源关系:身份/租户/会话边界看 doc/28;媒体占位看 doc/32; MCP 协议与工具面看 doc/33;子代理规格看 doc/17、doc/26。 范围:团队 agent 与子代理的 DB/UI 配置;租户 model key;系统 MCP + 自定义 MCP; 每场 run 的运行时装配;预检、失败语义、密钥与配额收尾。 不在本篇:旧接口信封 A7、API key、组织/跨租户共享、SSO、账单。U1 的页面契约在第 11.3 节,实现在yk-tako-eino/web/。
0. 一句话结论
团队 agent 不是第二种 agent runtime;它是这一场 run 的 root agent 的配置来源。 子代理也不是文件系统旁路:默认和租户配置都落 DB,agents/*.md 只做 seed / 导入格式。 一场 run 在抢闸前收成一份 RunProfile:模型、工具、MCP、instruction 都从这里来。R1–R5 和 U1 就是这条链。
1. 名词与边界
| 名词 | 真身 | 谁用 |
|---|---|---|
| 默认 root agent | 没有选团队 agent 时的 root;sessions.agent_id 为空 |
每次新会话的默认行为 |
| 团队 agent / root agent | agent_defaults 或 tenant_agents 的 root 行 |
用户在 POST /api/runs 里通过 agentId 直接选 |
| 子代理 / subagent | 同一套默认/租户行,kind=subagent/both;agents/*.md 只做 seed/导入 |
root 在 run 内通过委派工具调用,用户不直接选 |
| 默认 agent | agent_defaults 里的平台默认行;租户未覆盖时使用 |
平台 seed;租户 UI 只读 |
| 租户覆盖 | tenant_agents 里 default_id 指向默认行的 full copy |
租户 UI 编辑;同名覆盖默认 |
| 系统 MCP | 平台 mcp.json,所有租户默认可用 |
平台运维配置 |
| 自定义 MCP | 租户 runtime-config.mcpServers,配了才用 |
租户 admin 可选配置 |
| RunProfile | 一场 run 的不可变装配结果:model、translator、tools、MCP、instruction | newRunAgent 消费 |
“主 agent” 是旧称呼:进程启动时用 TAKO_MODEL、全局工具池和全局系统提示构造的默认 root。 R3 之后它仍然存在,但“默认”也按租户解析;团队 agent 只是显式覆盖。
2. 现状与病灶
当前代码的事实(以工作区为准):
newRunAgent已经每场 run 新建一个adk.ChatModelAgent,并发隔离成立;resolveRunInstruction已经读sessions.agent_id,把tenant_agents.spec放进Instruction;newRunAgent仍写死Model: w.chat、Tools: w.tools,不看model_ref/tool_policy;TenantAgent.tools是库里旧字符串;createAgent/updateAgent请求体没有tools,agentBody也不返回;自定义团队 agent 根本配不了工具;- 子代理
agentSpecHandler只LoadAgentSpecs("agents"),没有 DB/租户层; mcpToolHandler只读defaultMcpConfPath(平台mcp.json),不读租户mcpServers;- 租户
secrets已封存/掩码,但ModelRegistry用进程环境快照、cache key 只有ref; TAKO_MODEL和进程 environment 里的 key 仍是所有 run 的默认。
失败故事:
- owner 建团队 agent,填
model_ref和工具;member 选它发消息;prompt 换了,模型和工具仍是平台启动时那套。 - A、B 两个租户都用
deepseek/deepseek-v4-flash;各配自己的 key;全局 Registry 按 ref 缓存,key 串租户。 - 租户在 config 里配了 MCP,run 仍只连平台
mcp.json;配了等于没配。 - 租户想改子代理,只能改全局
agents/文件,影响所有租户;前端也没有入口。
3. 目标与不变量
- 租户隔离:model key、MCP secret、MCP 连接、工具池、子代理配置都不跨租户。
- 租户自备 model key:
TAKO_MODEL只做默认 ref;API key 来自租户secrets,没有平台 key 回退。 - 所有模型调用都按租户:root、子代理、长期记忆抽取、上下文压缩摘要,全部用租户 key。
- 默认工具全量:团队 agent 不写
tool_policy时,继承该租户的有效工具池全部; 显式 policy 才收缩;空名单 = 无工具。 - 默认/覆盖:系统默认 agent 在 DB;租户配置了就用租户,没有就用默认;同名覆盖。
- 子代理同样可配:root 和 subagent 都在 UI 可配;默认 DB,租户覆盖 DB;md 只是导入格式。
- MCP 可失败就失败:自定义 MCP 显式配置且连不上 →
503,不建 run;配置非法 → 400。 - 预检在抢闸前:坏 model/tool/MCP 配置不能先 202 再在 worker 里 error。
- 多副本:配置/密钥在 PG,连接句柄在进程内;不靠进程内状态做正确性。
- 旧接口信封不动:A7 单独做。
4. 已拍决定与待拍项
4.1 已拍
| 决定 | 口径 |
|---|---|
| 团队 agent 是什么 | agent_defaults/tenant_agents 的 root;不是子代理 |
| 子代理默认 | DB;不是文件系统;md 只做 seed/导入 |
| 默认/租户配置 | 默认在 DB;租户配置了就用租户,没有就默认;同名覆盖 |
| UI | root 和 subagent 都要能在 UI 配置;编辑、覆盖、重置、导入 md |
| 工具默认 | 不写 tool_policy = 继承全部有效工具 |
| 平台 key 回退 | 不允许;租户没配自己的 model key → 4xx,不建 run |
| 自定义 MCP 失败 | 503,不建 run;UI 显示 failed |
| 系统 MCP 失败 | 降级为少工具;UI 显示 degraded |
| 租户 md | 租户上传 API;导入到 DB,不落共享文件系统 |
| 子代理 model/tools | 默认继承根;配置了覆盖;租户 key 解析;不能扩权 |
| 模型调用范围 | root、子代理、记忆抽取、摘要全走租户 key |
4.2 待拍
| 问题 | 暂定 |
|---|---|
| 默认 agent 更新后,已有租户覆盖是否自动跟随 | 不自动;覆盖是 full copy;UI 显示“默认已更新” |
| 自定义 provider / base URL | 先按平台 provider catalog;租户只能配 key |
| secret 轮换 | 当前 seal1: 用 TAKO_JWT_SECRET 派生;R5 定独立 key/版本 |
| 团队前端页面 | 独立 U1 loop;本文只给字段/状态契约 |
5. 目标结构:RunProfile
type RunProfile struct {
TenantID string
UserID string
SessionID SessionID
AgentID string
ModelRef string
Model model.BaseChatModel
Translator Translator
Instruction string
ToolPolicy ToolPolicy
Tools []tool.BaseTool
MCP []MCPConnection
ConfigVer string
}装配顺序(postRuns):
1. auth + 解析 agent(请求 agentId 或 sessions.agent_id);默认/覆盖合并
2. 读 tenant_settings / agent 配置;解封 secrets
3. 解析 model:agent.model_ref > tenant.modelRef > TAKO_MODEL(只 ref)
4. 解析 tool policy:有效池 = 平台工具 + 系统 MCP + 自定义 MCP
5. 解析 MCP:系统 + 租户合并;自定义显式连接
6. validate(profile):model 可建、tool 名可解析、MCP 可用、策略不越界
7. AcquireRun;失败(404/409/429)→ 关闭刚建的 MCP
8. worker.Run(profile);newRunAgent 用 profile.Model / profile.Tools / profile.Instruction
Eino 的位置:adk.NewChatModelAgent 是第 8 步的构造器;它可能对 Model 为空、工具接口不合法报错, 但它不拥有租户、密钥、MCP、tool policy 的语义。validate(profile) 是我们自己的前置校验,不是 Eino API。
6. 默认 / 租户覆盖的数据模型
6.1 两张表
agent_defaults(
id, name, kind, description, spec, model_ref, tool_policy,
version, created_at, updated_at
)
tenant_agents(
id, tenant_id, default_id, name, kind, description, spec,
model_ref, tool_policy, visibility, source, created_by, created_at
)
kind:root | subagent | both;agent_defaults是平台默认;由agents/*.mdseed,运行时不再读文件系统;tenant_agents是租户覆盖(source=override,default_id非空)或自定义(source=custom);- 覆盖 = full copy:UI 点“编辑默认”时,把默认行整份复制成租户行;之后默认更新不自动改覆盖;
- 删除 override = 回到默认;删除 custom = 真删;
tenant_agents唯一性按(tenant_id, name)约束;kind 不参与唯一,避免同名 root/subagent 双份;sessions.agent_id可以是ad_(默认 id)或ag_(租户行 id); 解析时先定位默认/租户行,再找同名 override。
6.2 有效 agent 解析
root:
defaults(kind=root|both) + tenant overrides/custom
同名租户覆盖默认
subagent:
defaults(kind=subagent|both) + tenant overrides/custom
同名租户覆盖默认
GET /api/tenants/:id/agents?kind=root|subagent返回有效列表:id(当前生效 id)、defaultId、source(default/override/custom)、overridden、name/description/spec/modelRef/toolPolicy/visibility。- UI 对 default 行只读;编辑时创建 override;对 override/custom 可编辑/删除/重置。
agentId选择:- 选 default 行:
agentId=ad_...;运行时查同名 override,有就用 override; - 选 override/custom 行:
agentId=ag_...。
- 选 default 行:
- 预检:id 必须能解析成有效 agent;删除/不可见 → 404
112003,不建 run。
7. 模型
7.1 优先级
agent.model_ref(空 = 不覆盖)
> tenant_settings.modelRef(空 = 不覆盖)
> TAKO_MODEL(平台默认 ref)
agent.model_ref为空不等于“没有模型”,是“继承租户默认”;TAKO_MODEL只提供 ref,不提供 key;- 租户没配 key 时,默认 agent 也不能跑;返回 4xx,不建 run;
- 租户配了 key 但 ref 解析失败 → 4xx,不偷偷回退平台。
7.2 租户 key
tenant_settings.secrets是环境变量名到值的映射,例如DEEPSEEK_API_KEY;- 值封存后再落库。配了长度不少于 32 字节的
TAKO_DATA_KEY时,新写入是seal2:,密钥是这段数据密钥的 sha256。没配或太短时仍写seal1:,密钥来自TAKO_JWT_SECRET。解开seal2:时先试TAKO_DATA_KEY,再试TAKO_DATA_KEY_PREVIOUS;解开seal1:时先试TAKO_JWT_SECRET,再试TAKO_JWT_SECRET_PREVIOUS。已有的seal1:行在配上数据密钥之后仍然能解开; - 构造租户环境:平台非密钥配置(provider catalog、base URL 这类)+
tenantSecrets; 所有*_API_KEY(包括TAKO_PROVIDER_*_API_KEY)必须来自租户 map,平台进程里的 key 不注入; - 不使用进程级
TAKO_*API key 作为租户 run 的回退; - 日志只打 provider、model、ref 和密钥指纹,不打 key,也不打密文。
7.3 Resolver / cache
- 新增
TenantModelResolver(或在ModelResolver上加 tenant 维度); - cache key =
tenantID + ref + configVersion; configVersion来自tenant_settings.config的哈希(含 secret 密文),配置改动后新 key;- 每个进程一份 cache;多副本不共享;重启丢失可重建;
- 子代理、记忆抽取、摘要共用这个 resolver,不各自建全局 registry;
- 对外不把
tenantID明文放进响应。GET /api/tenants/:id/model-resolve(viewer 即可,owner 的角色更高,所以过得去)走和建 run 相同的 Resolve。成功时data是{ref, provider, model, keyFingerprint, cacheKey}。keyFingerprint是这把租户密钥 sha256 的前 12 个十六进制字符。cacheKey是内部键tenantID + NUL + ref + NUL + configVersion的 sha256 十六进制。没配 key 时 HTTP 409、code为111408,runs不增加。同一租户、同一配置连打两次,cacheKey相同。两个租户用同一个 ref、不同的 key,指纹和cacheKey彼此不同,也不同于进程环境里那把平台密钥。这条探针不发起模型调用。
7.4 所有模型调用
R2 之后:root newRunAgent、子代理、记忆抽取、上下文压缩摘要,全部用租户 resolver; 后台任务必须能从 session_id 找回 tenant,不能拿进程启动时的全局 chat 兜底。
8. 工具
8.1 tool_policy
{"mode":"inherit","names":[]}
{"mode":"allow","names":["get_time","read_text_file"]}
{"mode":"exclude","names":["bash"]}
{"mode":"none","names":[]}inherit:有效池全部;不写 policy = inherit;allow:只列出的名字;exclude:有效池减名字;none:空池;names只允许在allow/exclude下出现;inherit/none带 names 是 400。
8.2 有效池
有效池 = 平台第一方工具 + 系统 MCP 工具 + 租户自定义 MCP 工具
- 默认 agent 全拿;
- 显式 policy 在有效池上过滤;
- 子代理继承根过滤后的池,不能反向扩;
bash也在池里;沙箱不可用时它的调用会失败。是否剔除bash,待拍。
8.3 名字校验
- 第一方工具名来自
tool.Info().Name; - MCP 工具名 =
mcp__<server>__<tool>; tool_policy里未知名字 → 400,不建 run;- 自定义 MCP 的工具名只有连接后才知道,R4 的预检必须先连接再校验。
9. 子代理(默认 DB,租户覆盖,md 导入)
9.1 运行时来源
- 子代理不再运行时扫
agents/目录; - 启动/迁移时把
agents/*.mdseed 成agent_defaults(kind=subagent/both); - 运行时从
agent_defaults + tenant_agents解析有效子代理; - 多副本共享 PG,不共享文件系统作为 agent 真源。
9.2 租户配置
- UI 可编辑子代理:默认行只读,编辑创建 override;可重置;
- 上传 md:解析 frontmatter + 正文,创建 override/custom;
- 同名覆盖默认;不同名成为自定义子代理;
- 子代理
model/tool_policy默认继承根 profile;配置了覆盖; - 子代理工具池必须是根有效池的子集,不能借 md/UI 提权;
- 子代理没有“用户直接选”的入口;它只作为 root 的委派工具。
9.3 与团队 agent 的关系
- 团队 agent 是 root,用户选;
- 子代理是 delegate,用户不直接选;
- built-in
coder/researcher在agent_defaults里kind=both,同时出现在两个 UI; - 用户自建 root 默认不是子代理;用户自建 subagent 也不自动成为 root;
- UI 的 Agent 页分 Root / Subagent 两个 tab,共享同一套默认/覆盖规则。
10. MCP
10.1 两源合并
- 系统 MCP:平台
mcp.json;所有租户默认可用; - 自定义 MCP:
tenant_settings.mcpServers;配了才用; - 合并:同名租户覆盖系统,不同名都保留;
- 用户不需要配 MCP;不配就只用系统 MCP。
租户 config 形状:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
"env": {"TOKEN": "secret://MCP_TOKEN"}
}
}
}env值secret://<key>从租户secrets解封;缺 key → 400;- 明文 env 只允许非敏感值;界面不显示 secret 明文;
- 不允许
seal1:密文直接当 env 值传给 MCP。
10.2 失败语义与 UI 状态
| 情况 | 结果 | UI |
|---|---|---|
| 租户 config JSON 非法 | 400,不建 run | 表单错误 |
| 自定义 server 连不上/握手失败 | 503,不建 run | 红色 failed + 原因 |
| 自定义 server 工具名与 policy 不符 | 400,不建 run | 表单错误 |
| 系统 MCP 连不上 | 降级为少工具,run 继续 | 黄色 degraded |
| 抢闸前连上、AcquireRun 409 | 关闭连接,返回 409 | 会话忙提示 |
- 顺序成本:自定义 MCP 连接在
AcquireRun之前;连上了却抢闸失败要立刻关闭。 - 连接生命周期:一次 run 一份;run 结束关闭;不跨 run 复用。
- UI 状态接口:R4 增加
GET /api/tenants/:id/mcp-status(admin):system[](只读,state=connected/degraded/failed)、custom[](state=connected/failed/disabled), 不返回 secret;UI 用它显示“系统 MCP 降级 / 自定义 MCP 503”。
11. API / 存储 / UI
11.1 Agent API
GET /api/tenants/:id/agents?kind=root|subagent
POST /api/tenants/:id/agents # custom 或 override
PUT /api/tenants/:id/agents/:agent_id # override/custom
DELETE /api/tenants/:id/agents/:agent_id # override 删除=回默认;custom 删除
POST /api/tenants/:id/agents/import # md 导入,写 override/custom
- 请求/响应字段:
name、kind、description、spec、modelRef、toolPolicy、visibility; GET返回id/defaultId/source/overridden;POST同名默认 → override;否则 custom;- 导入 md 用 JSON
{files:[{name,content}]},服务端解析 frontmatter; toolPolicy结构校验 R1;工具名解析 R3/R4。
11.2 tenant runtime config
{
"modelRef": "deepseek/deepseek-v4-flash",
"mcpServers": {"...": {"command": "...", "args": [], "env": {}}},
"secrets": {"DEEPSEEK_API_KEY": "seal1:..."},
"sandbox": {"network": false}
}- R1 只校验结构;R2 用 secret;R4 用 MCP;
secrets仍封存;GET 掩码;PUT 回掩码保留旧密文。
11.3 UI 契约(独立 Vue loop,不在 R1 实现)
- Agent 页:Root/Subagent 两个 tab;列表显示来源 default/override/custom、model、policy 摘要; 编辑 default 时先复制成 override;保存后标“已覆盖”;“重置”删除 override;新建 custom; 上传 md;错误按 400/404/409 显示。
- Team 设置页:默认 modelRef;租户 model key(每个 provider 一行,掩码); 系统 MCP 只读状态;自定义 MCP 增删改 + 测试连接;状态色:系统 degraded 黄、自定义 failed 红; run 503 时显示具体 server;secret 轮换 R5,页面先不做版本 UI。
- 依赖 API:
GET/PUT runtime-config、GET mcp-status、Agent CRUD/import。 - 页面在
yk-tako-eino/web/:顶栏切「对话 / 助手 / 团队」。登录态统一在web/src/auth.ts,两个页面共用sessionStorage里的 access/refresh token——在哪边登录,另一边都算登录;一边退出,另一边也退回登录表单。 - 对话页与配置页的请求都经
authFetch:带Authorization: Bearer;遇401先用 refresh token 换一对新 token(refresh 是轮换的,并发 401 共用同一次刷新)再重试一次。refresh 已失效或旧会话没有 refresh token(U1 时期登录的存量会话)就清登录态、回到登录表单;网络错误不清登录态。对话页在未登录时直接渲染登录表单。 - 媒体图片走
GET /api/media也要求登录,而<img src>带不了请求头:页面先用authFetch取回字节、再以 object URL 交给<img>,同一 path 只取一次。 - 保存 Team 设置后当场重跑
mcp-status:状态是探针结果不是配置本身,保存后再显示旧结果会让用户以为新配置仍连着(之前要再点一次「测试连接」才更新)。
11.4 错误码
落地前补 doc/28 第 5.4 节:
| 情况 | HTTP | 建议 code |
|---|---|---|
| agent/tool policy 字段非法 | 400 | 111002 |
| 同名助手已经有租户配置 | 409 | 111412 |
| tool policy 未知工具 | 400 | 111409 |
| 模型未配置/ref 不可用 | 409 | 111408 |
| MCP 配置非法 | 400 | 111410 |
| 自定义 MCP 不可用 | 503 | 111411 |
| agent 不可见 | 404 | 112003 |
| 会话忙 | 409 | 旧体 session_busy |
server 名不合法或缺少 command,仍回 400 111002,文案是「MCP 配置不合法」。111410 用在装配时:secret:// 指到的密钥还没配,文案是「有一项 MCP 密钥还没配」;环境值本身是 seal1: 或 seal2: 密文,文案是「MCP 环境不能直接放密文」。自定义 MCP 连不上是 503 111411,文案是「自定义 MCP 连不上」。
12. R1–R5 + U1
| 段 | 用户能验收什么 | 系统改什么 | 依赖 |
|---|---|---|---|
| R1 契约 | root/subagent 能列、改、重置、导入 md;默认/覆盖/自定义来源可见;runtime config typed;运行行为不变 | agent_defaults + tenant_agents 覆盖模型;agent API/import;typed config |
无 |
| R2 租户 key | 租户能配自己的 model key;没 key 的 run 4xx;两租户同 ref 不同 key 各走各的 | secret 解封;TenantModelResolver;cache key;无平台回退;后台模型调用 | R1 |
| R3 运行时 | 选中的 root agent 真换 model/tools;默认 agent 全量;子代理 DB 覆盖/继承 | RunProfile;根 model/tools;子代理 DB 解析;预检 | R2 |
| R4 MCP | 系统+自定义 MCP 合并;自定义连不上 503;UI 能看状态 | typed MCP;merge;secret 解封;预检连接;mcp-status | R3 |
| R5 收尾 | 并发上传不超存储;过期邀请零用户;换数据密钥可解旧 secret | 存储 reservation;邀请单事务;secret 版本/轮换 | 独立 |
| U1 UI | Agent 页/Team 设置页可用 | Vue 页面;不改后端契约 | R1/R4 |
A7 旧接口信封 不在这六段;单独做。
13. 安全与多副本
- secret:不解密不落日志;
seal1:不能直传 MCP;GET 只回掩码;密钥轮换 R5。 - 跨租户:model resolver cache key 带 tenant;MCP 连接按 run;工具池按 tenant;agent 覆盖按 tenant。
- 多副本:配置/密钥/默认 agent/租户覆盖都在 PG;model client/MCP 连接在进程内;不依赖进程内 cache 做正确性。
- 审计:agent/config 变更若要审计,复用 A2-4;本轮不新开审计表。
- 配额:storage reservation / token 计量见 R5;本轮不重做 A5。
14. 验收原则
- 第一行永远打跑着的引擎;不写“页面上看到 X”。
- 每个 action 停;不自动 commit。
- 两租户、同 ref、不同 key 必须各走各的。
- 没 key / 坏 model / 坏 tool / 坏 MCP 的请求必须无 run 行。
- 默认 agent 全量工具;显式 policy 只收缩;子代理不能扩权。
- 自定义 MCP 挂掉 503;系统 MCP 失败降级并在 UI 显示 degraded。
- 409 后关闭 MCP 连接,不留进程内句柄。
- 旧接口成功体不变;新接口走信封。
15. 非目标与待拍
- 旧接口信封 A7;
- API key / SSO / 账单 / 组织共享;
- 租户自定义 provider/base URL(先按平台 catalog);
- 默认 agent 更新后覆盖是否自动跟随(暂定不自动);
- secret 轮换的页面版本 UI(R5 已有数据密钥/版本,页面不做);
- 系统 MCP 失败已定降级;自定义 MCP 失败 503。