tako 文档 GitHub

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. 现状与病灶

当前代码的事实(以工作区为准):

失败故事:

3. 目标与不变量

  1. 租户隔离:model key、MCP secret、MCP 连接、工具池、子代理配置都不跨租户。
  2. 租户自备 model key:TAKO_MODEL 只做默认 ref;API key 来自租户 secrets,没有平台 key 回退。
  3. 所有模型调用都按租户:root、子代理、长期记忆抽取、上下文压缩摘要,全部用租户 key。
  4. 默认工具全量:团队 agent 不写 tool_policy 时,继承该租户的有效工具池全部; 显式 policy 才收缩;空名单 = 无工具。
  5. 默认/覆盖:系统默认 agent 在 DB;租户配置了就用租户,没有就用默认;同名覆盖。
  6. 子代理同样可配:root 和 subagent 都在 UI 可配;默认 DB,租户覆盖 DB;md 只是导入格式。
  7. MCP 可失败就失败:自定义 MCP 显式配置且连不上 → 503,不建 run;配置非法 → 400。
  8. 预检在抢闸前:坏 model/tool/MCP 配置不能先 202 再在 worker 里 error。
  9. 多副本:配置/密钥在 PG,连接句柄在进程内;不靠进程内状态做正确性。
  10. 旧接口信封不动: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
)

6.2 有效 agent 解析

root:
  defaults(kind=root|both) + tenant overrides/custom
  同名租户覆盖默认
subagent:
  defaults(kind=subagent|both) + tenant overrides/custom
  同名租户覆盖默认

7. 模型

7.1 优先级

agent.model_ref(空 = 不覆盖)
  > tenant_settings.modelRef(空 = 不覆盖)
  > TAKO_MODEL(平台默认 ref)

7.2 租户 key

7.3 Resolver / cache

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":[]}

8.2 有效池

有效池 = 平台第一方工具 + 系统 MCP 工具 + 租户自定义 MCP 工具

8.3 名字校验

9. 子代理(默认 DB,租户覆盖,md 导入)

9.1 运行时来源

9.2 租户配置

9.3 与团队 agent 的关系

10. MCP

10.1 两源合并

租户 config 形状:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
      "env": {"TOKEN": "secret://MCP_TOKEN"}
    }
  }
}

10.2 失败语义与 UI 状态

情况 结果 UI
租户 config JSON 非法 400,不建 run 表单错误
自定义 server 连不上/握手失败 503,不建 run 红色 failed + 原因
自定义 server 工具名与 policy 不符 400,不建 run 表单错误
系统 MCP 连不上 降级为少工具,run 继续 黄色 degraded
抢闸前连上、AcquireRun 409 关闭连接,返回 409 会话忙提示

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

11.2 tenant runtime config

{
  "modelRef": "deepseek/deepseek-v4-flash",
  "mcpServers": {"...": {"command": "...", "args": [], "env": {}}},
  "secrets": {"DEEPSEEK_API_KEY": "seal1:..."},
  "sandbox": {"network": false}
}

11.3 UI 契约(独立 Vue loop,不在 R1 实现)

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. 安全与多副本

14. 验收原则

  1. 第一行永远打跑着的引擎;不写“页面上看到 X”。
  2. 每个 action 停;不自动 commit。
  3. 两租户、同 ref、不同 key 必须各走各的。
  4. 没 key / 坏 model / 坏 tool / 坏 MCP 的请求必须无 run 行。
  5. 默认 agent 全量工具;显式 policy 只收缩;子代理不能扩权。
  6. 自定义 MCP 挂掉 503;系统 MCP 失败降级并在 UI 显示 degraded。
  7. 409 后关闭 MCP 连接,不留进程内句柄。
  8. 旧接口成功体不变;新接口走信封。

15. 非目标与待拍