taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
88240dc79ebee429c13e0c4424784a9a372b9236
heicode-mananger/docs/design/heicode-hm-team-control-design.md
T
chenchenandClaude Opus 4.8 88240dc79e docs(design): HM team-control design referencing Claude Code enterprise paradigm 
Synthesizes Claude's admin-setup/authentication/server-managed-settings/settings/
managed-mcp/auto-mode docs into a team-management design for HM, mapped onto the
analogy (client≈Claude Code, HM≈Claude.ai admin console, AM≈cloud agent) and
grounded in HM's existing primitives (new-api users/groups/sk-token model-limits/
quota, plus our V2 device auth, resource bindings, agent templates, /v1 gateway).
Covers org/team/seat model, roles, allocation, managed-settings push over the V2
channel, managed agent/tool catalog, auth/SSO, auto-mode, audit, and a phased plan.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-05 16:27:50 +08:00

16 KiB
Raw Blame History

HM 团队管控设计（参考 Claude Code 企业范式）

起草：2026-06-05 · 状态：设计草案（供讨论，不含实现）

类比锚点：我们的桌面客户端 ≈ Claude Code · HM（Heicode Manager）≈ Claude.ai 企业/管理控制台 · AM（agent_management）≈ 云端 agent 运行时。

本文把 Claude 的企业管控范式（来自官方文档 admin-setup / authentication / server-managed-settings / settings / managed-mcp / auto-mode-config）提炼为「团队如何通过 HM 控制与分配」的设计，并逐条对齐 HM 现状（new-api fork 本身已有的能力 + 我们已加的 V2 设备鉴权 / 资源绑定 / agent 模板 / 模型网关）。

0. 一句话目标

让一个团队/组织的管理员，能在 HM 控制台里：拉人 → 分角色 → 配可用模型与额度 → 授权可用资源/agent/工具 → 把策略强制下发到每个客户端 → 看用量与审计。客户端（我们的桌面端）只能在 HM 划定的边界内工作；真正的硬边界由 HM 网关侧强制，而非依赖客户端自觉。

1. Claude 范式精炼：三层控制

Claude 的企业管控可归纳为三层，HM 应整体借鉴这套分层：

层 Claude 机制 作用
身份与准入 提供商选择 + 座位(seat) + 邀请/角色 + SSO/SCIM/域名捕获 决定「谁能用、用哪个组织身份」
策略下发（受管设置） server-managed-settings：管理员在 Web 控制台下发 JSON，客户端登录时拉取、每小时刷新、最高优先级不可本地覆盖、数组规则只增不删 决定「客户端能做什么、不能做什么」
能力供给（受管工具/agent） managed-mcp + agent/插件下发：组织级统一发一批可用 MCP/工具，可「软允许」或「独占控制」，deny 永远优先 决定「客户端有哪些工具/agent 可用」

外加两条贯穿性能力：分配与计费（模型白名单、支出/速率上限、用量归属）与审计（compliance API、审计日志、ZDR）。

Claude 自己承认的最大短板，正是 HM 的机会：

  • server-managed 是纯客户端控制（client-side control）——有 sudo 的用户能改二进制/绕过；HM 是网关，可把强制放在服务端，更硬。
  • server-managed 暂不支持分组（全组织统一）；HM 用 V2 设备鉴权天然能按设备/用户/组织下发。
  • 配置第三方 provider（Bedrock/自定义 BASE_URL）会完全绕过 server-managed；HM 须在网关侧封死这条旁路。

2. HM 现状盘点（已有 vs 缺口）

重要：HM 是 new-api fork，很多分配原语已经现成，团队管控不是从零造，而是「加一个组织层 + 一套策略下发通道」。

2.1 已有（可直接复用的原语）

  • 用户与角色：new-api 有 role（普通=1 / 管理员=10 / 超级管理员=100）。
  • 分组(group)：User.Group + 分组级模型倍率/可用性。
  • 令牌(sk-)：model.Token 支持 per-token 模型限制 model_limits、配额 RemainingQuota/UnlimitedQuota、过期 ExpiredTime、速率、HideFromUserUI 等——这就是「按 key 限模型 + 限额」的现成能力。
  • 配额/计费：用户 Quota/UsedQuota、计费表达式系统（pkg/billingexpr）、日志归属。
  • 模型网关：/v1/* 统一鉴权 + 计费 + 路由（团队可用模型的强制点天然在这）。
  • V2 设备鉴权（我们加的）：Ed25519 验签 + X25519/ChaCha20 加密，/api/agnet/user/* 用户身份唯一来源——这是策略安全下发的现成通道。
  • 资源绑定（我们加的）：KV + secret_ref，按用户隔离。
  • agent 模板库（我们加的）：admin CRUD + 下发客户端列表 + 部署到 AM——这已经是一个「受管 agent registry」雏形。

2.2 缺口（需新建）

  1. 组织/团队对象层：当前是「用户」单层，没有 org→team→member 的多租户层与座位概念。
  2. 角色细化：只有 1/10/100 三档全局角色，缺「组织内 owner/admin/member/auditor」与「能配 AM / 能配模型 / 只能用客户端」的能力维度。
  3. 受管设置下发通道：没有「服务端下发、客户端强制、不可覆盖」的策略机制（对标 server-managed-settings）。
  4. 受管工具/agent 的 allow/deny 策略语义：agent 模板目前是「全部可见」，缺组织级白/黑名单与「软下发 vs 独占」两档。
  5. SSO/SCIM/域名捕获：缺企业身份联邦与自动归属。
  6. 组织级用量看板与审计日志：缺按组织/成员的用量归属与策略变更审计。

3. HM 团队管控设计

3.1 对象模型：组织 → 团队 → 成员 → 座位

Organization (租户，计费主体)
  ├─ Team (可选二级，部门/项目组)
  │    └─ Membership (User × role × seat)
  ├─ Plan / Seats (席位订阅：座位是否含「客户端访问」「AM 调用额度」)
  ├─ Policy (受管设置，§3.4)
  ├─ ToolCatalog (受管 agent/MCP/资源目录，§3.5)
  └─ Quota / SpendLimit (组织级额度池，§3.3)
  • 座位(seat)= 客户端访问的硬开关（对标 Claude「座位不含 Claude Code 访问会被拒登」）。HM 落点：V2 设备登录后，先校验该用户在某组织有有效座位，才签发客户端身份；无座位 → 拒绝拿到 agent 列表/资源/模型 key。
  • 复用 new-api：Organization 可由现有 group 升级承载，或新建 organizations/memberships 表（GORM AutoMigrate 加表，跨 SQLite/MySQL/PG）。

3.2 角色与权限

借鉴 Claude「角色 = 能创建/使用哪类凭证 + 能调哪些能力」的朴素范式，定义组织内角色：

角色 能力
Owner 全权：计费、座位、下发受管策略、增删 admin
Admin 管成员、配模型白名单/额度、配 agent 目录、下发策略（不含计费/删 owner）
Member 用客户端 + 已授权的 agent/资源/模型
Auditor（只读） 看用量、审计日志，不能改

并用正交的能力位细分（参考 Claude 把「能创建哪类 key」做成角色）：can_manage_models / can_manage_agents / can_manage_resources / can_push_policy / can_view_audit。落点：成员表加 role + capabilities 位图。

3.3 分配（模型 / 配额 / 资源 / agent）—— 大量复用 new-api 现成能力

这是 HM 相对 Claude 的强项（Claude 这部分靠外部 gateway，HM 自己就是 gateway）：

分配维度 机制 复用 HM 现状
可用模型白名单 组织/团队/成员级允许模型集 复用 Token.model_limits + 分组模型可用性；网关 /v1/* 已是强制点
支出上限(spend limit) 组织额度池 + 成员子额度 复用 User.Quota/UnlimitedQuota + 计费表达式
速率限制(rate limit) 按组织/成员/key 复用 new-api 既有 rate limit
凭据有效期 CI/服务用短期/长期 token（对标 claude setup-token 一年期、仅推理、不可建远控会话） 复用 Token.ExpiredTime + 范围位
可用资源 授权某成员/团队可绑定哪些资源类型 复用资源绑定 + KV secret_ref
可用 agent 模板 组织级 agent 目录（§3.5） 复用 agent 模板库 + 下发列表

关键设计：把「分配」做成组织池 → 成员子额度的两级（组织买总量，admin 切给成员），对应 Claude 的座位/支出归属。

3.4 受管设置下发（核心，对标 server-managed-settings）

这是最值得照搬的范式。HM 设计：

a) 下发通道 = 复用 V2 设备鉴权

  • 策略以 JSON 形式，挂在设备鉴权返回里下发（/api/agnet/user/* 已是身份唯一来源）。
  • Ed25519 验签保证策略不被中间篡改——比 Claude 纯客户端控制更强。
  • 天然支持按组织/团队/设备分组下发，补上 Claude「暂不支持分组」的缺口。

b) 优先级与合并（照搬 Claude 语义）

  • 受管层 = 最高优先级，客户端 user/project/CLI 本地配置不可覆盖。
  • 区分两类：强制项(enforced，不可改) vs 默认值(default，客户端可改)。
  • 数组类规则（如允许模型、允许域）只增不删：客户端只能在受管基础上扩展，不能删受管项；但允许「自我收紧」（客户端可为自己再 deny）。

c) 拉取 / 缓存 / 故障策略（照搬）

  • 客户端启动拉取 + 周期刷新（Claude 每小时）；本地缓存，断网仍按上次策略执行。
  • fail-closed 开关（对标 forceRemoteSettingsRefresh）：高敏组织拉取失败即拒绝启动客户端，杜绝「未强制窗口」。
  • 豁免重认证：fail-closed 不能把「登录/续签」也锁死（Claude 的教训——凭证过期时要留重认证口子）。
  • /status 式自检：客户端能显示「当前生效策略来源 + 是否受管」。

d) 优先做的强制项（对标 Claude managed-only 键，挑贴合 HM 的）

HM 强制项 对标 Claude 键 为什么
可用模型白名单 availableModels HM 是 /v1/* 网关，计费/合规边界
网络/域名准入 sandbox.network.allowedDomains + allowManagedDomainsOnly 锁客户端只能连 HM 及受信域
危险操作禁止 permissions.deny + allowManagedPermissionRulesOnly 禁读 secrets、禁危险命令，且禁客户端放宽
登录组织绑定 forceLoginOrgUUID / forceLoginMethod 强制客户端只认 HM 签发身份，堵旁路
高危能力开关 disableBypassPermissionsMode / disableRemoteControl 等 按组织策略关高危能力
审计 hook managed hooks + PostToolUse 客户端编辑后强制跑审计

⚠️ MEMORY 已记的隐患：策略状态不要只放单实例内存 map，要持久化 + 多实例一致（HM 单实例内存 map 隐患）。

3.5 受管工具 / agent（对标 managed-mcp）

HM 已有 agent 模板下发，等于自带 registry（Claude 反而没有内置 registry）。把它升级为带策略的「组织级能力供给」：

a) 两档下发语义（必须显式，不要隐式）

  • 软下发(additive)：HM 发一批可用 agent/工具，客户端仍可叠加自配 → 对标 Claude「软允许列表」。
  • 独占控制(exclusive)：客户端只能用 HM 下发的，本地自建被服务端拒绝 → 对标 managed-mcp.json 独占控制。

b) allow/deny 三步评估（照搬）

  1. 各源 allow/deny 合并；开启「仅受管」开关时本地 allow 失效、只认 HM allow；
  2. deny 永远优先、不可被任何层覆盖，且 deny 从所有源合并（用户能为自己再禁，不能放宽）；
  3. allow 命中才放行。

c) 匹配落到不可伪造标识

  • Claude 警告「只按 server 名字匹配不安全」。HM 校验客户端可用 agent/工具时，不要只信客户端上报的名字，要绑定模板 ID + 签名 + 设备身份（V2 鉴权链已具备）。
  • 直接受益：解决我们 AM 契约 §3.1 那条「按用户隔离」——agent 准入也走同一套不可伪造标识。

d) 凭据 per-user，不入下发物

  • Claude 禁止把 key 写进下发的 env。HM 下发「连接定义」但凭据按用户动态注入/OAuth（契合已有 Managed Identity / Key Vault）——下发物里绝不出现共享密钥。

e) 变更可观测

  • Claude 痛点是「server 被新策略静默消失、用户不知原因」。HM 作为网关，下发变更时给客户端可见原因，并在服务端记录「客户端实际调了哪些工具/agent」。

3.6 认证与准入（对标 authentication + SSO）

  • 多种登录分层：个人订阅式 OAuth、Console 式 key、CI 长期 token（范围限定：仅推理、不可建远控会话）、网关 bearer token（ANTHROPIC_AUTH_TOKEN 路线天然契合 HM 作网关）。
  • 确定性凭据优先级：客户端需一套固定选择顺序（网关 token > 设备 OAuth > …），并处理「key 属过期组织→认证失败」的冲突态，给 /status 诊断。
  • 企业强制：组织可强制 SSO/SAML + SCIM 自动配置 + 域名捕获，把同域用户自动归属到组织身份——决定「客户端用哪个组织身份接入」。
  • 封旁路：Claude 承认配第三方 provider 会绕过 server-managed。HM 必须在网关侧强制：客户端的模型请求只能经 HM，绕过即无额度/无身份。

3.7 auto-mode 类客户端行为（软策略 + 网关硬边界）

  • auto-mode 的教训：分类器合并是累加、可被用户 allow 覆盖，不是硬边界；真正不可绕过的放 permissions.deny（分类器之前）。
  • 映射 HM：
    • HM 可下发一套「受信环境/允许/拒绝」语义偏好（组织级），统一风险口径、减少误拦；
    • 但**「绝不允许」的能力边界，HM 在网关侧（请求进模型/工具前）硬拦**，等同 permissions.deny 角色，不依赖客户端分类器。
  • 隔离不可信来源：客户端/项目侧上报的规则只能收紧、不能放宽 HM 下发的策略（对标「分类器不读 check-in 的共享项目设置」）。

3.8 审计与用量

  • 用量归属看板：对标 Claude Analytics（每用户指标、贡献、排行榜）——按组织/团队/成员的 token 用量、模型分布、agent 调用，复用 new-api 日志 + 计费。
  • 审计日志：对标 compliance API——策略下发、成员变更、agent 部署/删除全程留痕（操作者、设备、新旧值）。HM 作网关是放请求级审计的天然位置。
  • 数据留存：可选 ZDR / 零留存档位。

4. 关键设计原则（HM 要比 Claude 更硬的三点）

  1. 硬强制在服务端，不在客户端。Claude 的 server-managed 是客户端控制、可被 sudo 绕过。HM 把模型/工具/agent 的真正准入放在网关 + V2 鉴权侧——客户端策略只是第一道 UX，越权请求在 HM 被拒。
  2. 下发通道带验签。复用 V2（Ed25519+ChaCha20）下发策略，防篡改、可按组织/设备分组——一举补上 Claude「分组缺失 + 纯客户端控制」两个短板。
  3. 不对称权限：受管策略「能自我收紧、不能自我放宽」；deny 永远优先且不可覆盖；凭据 per-user 永不入下发物。

5. 落地优先级（建议分阶段）

P0（地基）

  • 组织/团队/成员/座位对象模型（新表，AutoMigrate）；座位作为 V2 登录签发客户端身份的前置门。
  • 组织内角色 + 能力位。

P1（分配，复用现成原语，见效快）

  • 组织池 → 成员子额度（模型白名单 / 支出上限 / 速率 / 凭据有效期），全部映射到 Token.model_limits + 配额 + ExpiredTime。
  • 组织级 agent 目录：给现有 agent 模板加「组织可见性 + allow/deny + 软/独占」字段。

P2（受管设置下发，核心差异化）

  • 受管策略表 + V2 通道下发 + 优先级合并 + 拉取/缓存/fail-closed + /status 自检。
  • 先落 6 个强制项中的：可用模型白名单、网络域白名单、permissions.deny、登录组织绑定。

P3（企业身份与审计）

  • SSO/SAML + SCIM + 域名捕获；组织用量看板 + 审计日志。

附：来源与对照

本文章节 Claude 文档来源
§1、§3.1 座位/准入、§3.6 认证 admin-setup、authentication
§3.4 受管设置下发 server-managed-settings、settings
§3.5 受管 agent/工具 managed-mcp
§3.7 auto-mode auto-mode-config

待补（Claude 文档外链未展开，设计 SSO/SCIM 细节前再抓）：SAML 字段、SCIM 属性映射、域名捕获流程、Enterprise 完整角色清单（在《Claude Enterprise Administrator Guide》）。

Reference in New Issue View Git Blame Copy Permalink