VeyraOS 文档

Appearance

进入控制台

VeyraOS — 产品特性全量清单 ​

版本：1.0.0（2026-10 发布基线） 用途：作为「版本能力全量复刻」基线，用于迁移到其它语言/框架时逐项核对。 维护：每次新增/裁剪能力请同步更新本清单。 编号约定：按 1.0 功能树重新编号（域前缀 + 序号）；编号一经发布不复用、不重排。

0. 产品定位与整体架构 ​

VeyraOS 是面向企业客户的多智能体平台，核心价值：

  • 多租户与工作空间：个人空间 / 企业组织空间 / 部门空间，空间切换器承载资源上下文
  • 智能体开发层：定义/版本/人设/技能的可视化开发与版本化管理（定义/版本/实例三层模型）
  • 运行资源管理层：K8s 资源池规格、配额、回收策略，支持对接外部 K8s 集群
  • 智能体实例层：定义 × 版本 × 资源池的运行实例，完整生命周期
  • 统一模型网关：全系统统一模型出口，per-instance 精确计费
  • 企业 IM 集成：飞书/企业微信/钉钉渠道接入，流式响应
  • 终端门户：浏览器端 Chat 界面，复刻 hermes-webui 体验
  • SSO 统一认证：管理台收口账号中心（OIDC 授权码 + PKCE + 后通道统一登出）

平台服务清单（同 namespace veyraos 部署，REST 解耦）：

服务端口职责
Manager8002业务后台 API：定义/资源池/实例/权限/计费/仪表盘/知识库/资产代理；含原 Controller worker（/api/controller/* 引擎 Pod 生命周期：K8s 资源、Profile、存档恢复、回收调度，已并入 manager，无独立 :8001 服务）
Gateway8010反向代理 + IM 渠道分发 + SSE 流式 + 权限闸门
Hub8003资产中心（资产目录/审核/发布）
Skill Engine8004技能开发工作区与调试进程托管

外部对接（非本仓组件）：账号中心（bss/account，组织/租户/认证事实源）、Router（独立产品线）。

两大前端：

前端技术栈端口面向
Admin ConsoleVue3 + Element Plus + TS（vue-pure-admin）8848平台员工 / 租户管理员
Enduser PortalVue3 + Tailwind + Vite + Pinia3000终端用户

一、多租户与工作空间 ​

F-WS-001 组织 → 租户投影 ​

  • 描述：账号中心的 organization 1:1 投影为 manager 租户；租户内成员、资源空间与计费团队随投影同步。用户可同时属于个人租户与企业租户。
  • 实现：tenants（account_org_id 唯一锚点、kind、tier、status、litellm_team_id）+ tenant_members（role 原样）；四层搬运：组织→租户、组织成员→租户成员、组→用户组（tenant_id / account_group_id）、组成员→用户组成员。租户根组成员由 tenant_members 派生（不落成员行）。模型网关 Team 按租户（非按用户组）建立，实例密钥、管理台密钥、账户 vkey 三处统一按租户解析。

F-WS-002 工作空间切换器 ​

  • 描述：管理台顶栏树形空间切换器，以「当前工作空间」为全部业务资源的上下文。
  • 实现：请求头 X-Org-ID（<account_org_id> 具体空间 / all 平台超管跨空间只读 / legacy 存量手工组伪空间）+ X-Workspace-Group-ID（部门空间）；GET /api/manager/workspaces 返回可见空间（个人/企业/部门/平台段）与 default_id，按组织分页 + 部门懒加载。个人空间在响应层统一显示「个人空间」。平台超管可按姓名/邮箱搜索进入他人个人空间（只读，不可创建）。
  • 归属规则：新建资源未显式传组时落当前空间根组；实例继承所选定义的组；all 空间无归属组，创建返回 workspace_required。

F-WS-003 用户组（租户内资源空间） ​

  • 描述：UserGroup 是租户内的资源归属单元，所有业务资源按 group_id 归属；管理面已下线，组由账号中心组织投影维护，平台侧只读。租户根组 = 全租户共享空间，部门组 = 独立资源空间（父子树 parent_group_id）。
  • API：GET /api/manager/user-groups、GET .../{id}、GET .../{id}/members

F-WS-004 登录即建（JIT） ​

  • 描述：账号中心已有、本地尚未建立的用户首次登录管理台时自动完成建行与租户投影，无需预先导入。
  • 实现：本地未命中 → 账号中心反查 → 验签通过后建 users 行（id 与账号中心一致）并阻塞式完成租户/角色投影；投影失败拒绝登录（不建裸行）。

F-WS-005 租户分层门控（tier） ​

  • 描述：按租户档位（free/standard/enterprise）下发功能开关集；未配置的功能默认放开。
  • 实现：tier_capabilities 表（tier × feature）；GET /api/manager/features 出参含生效档位与开关集；后端端点按同一份配置门控。

二、作用域 RBAC 与权限 ​

F-RBAC-001 权限模型 ​

  • 描述：作用域化访问控制，细粒度权限码（菜单 / API / 按钮统一按权限码判定）。
  • API：GET/POST/PUT/DELETE /api/manager/roles、GET/POST/DELETE /api/manager/role-bindings、GET /api/manager/role-bindings/candidates、GET /api/manager/auth/permissions
  • 实现：生效权限是四级并集——平台员工 scope（platform_staff_scopes）→ 企业租户 owner/admin 派生 → 部门组 admin 派生 → role_bindings（租户 / 部门作用域）显式绑定；企业普通成员无显式租户绑定时默认「开发者」，显式绑定「只读成员」时抑制默认角色。roles 按 tenant_id 分平台 / 租户两层，租户自定义角色只能选租户安全码白名单；GET /permissions 按当前空间解析并请求级缓存。

F-RBAC-002 预置角色与分配权 ​

  • 预置角色：平台员工（账号中心 scope 投影，不在管理台分配）、租户管理员、部门管理员、开发者、只读成员。
  • 分配权：租户管理员可建改本租户自定义角色并分配任意本租户角色；部门管理员只能把「可委派」角色分配给本部门及下级部门成员；派生角色不可在管理台分配或回收。

F-RBAC-003 资源可见性与写谓词 ​

  • 描述：资源可见性 = 空间隔离 + 创建者私有（agent_definitions / knowledge_bases 的 visibility 取 inherit / private，实例与定时任务继承所属定义）。
  • 实现：可见组集合由 visible_group_ids 统一给出；读谓词 = 资源所属组在可见组集合内 ∧（inherit ∨ 创建者本人 ∨ 空间管理员）；写谓词 = 组范围通过 ∧ 动作权限码 ∧（创建者本人 ∨ 空间管理员）。inherit 只在本部门内生效，跨部门复用走克隆或上架资产中心。

F-RBAC-004 用户身份索引 ​

  • 描述：users 表作为身份索引（RBAC / 模型网关 / 审计锚点），用户生命周期在账号中心统一管理；平台侧保留查询与角色绑定。终端用户（end_users 表）不参与 RBAC，可见性由实例 access_scope + 终端用户组归属隔离。
  • API：GET /api/manager/users、GET .../{id}、PUT .../{id}/roles
  • 实现：JWT 双 Token（access 30min + refresh 90d）；管理台与终端门户令牌按 aud（admin / enduser）互不通用。

F-RBAC-005 网关鉴权归一（无平台员工旁路） ​

  • 描述：网关是纯数据面：验签 → 解析身份 → 按身份体系校验实例所属组的成员关系；管理台平台员工在管理 API 有旁路，网关数据面无旁路。
  • 实现：管理侧身份查 user_group_members ∪ 租户根组派生；终端侧查 end_user_group_members；跨组调试由 manager 签发短期代发凭证（≤5min，aud=gateway，显式组白名单）放行。

三、SSO 统一认证 ​

F-SSO-001 管理台收口账号中心 ​

  • 描述：管理台无独立登录页；未登录访问自动经 /oauth/authorize 跳转账号中心登录，授权码回跳 /sso/callback 后由 manager（BFF）集群内兑换 id_token 并验签，按 sub 建/查本地用户签发管理台令牌。
  • 实现：OIDC 授权码 + PKCE(S256)；state 与 PKCE verifier 由 manager 落库（单次消费、10 分钟有效）；授权请求携带 nonce 并在 id_token 校验回声。首次登录建档时登录名由账号中心用户 ID 派生（account-<ID 前 8 位>），显示名落「姓名」字段。SSO 未配置时登录页显示故障态而非本地表单。
  • 部署配置：UA_ACCOUNT_SSO_CLIENT_ID / UA_ADMIN_PUBLIC_URL / UA_ACCOUNT_OAUTH_ISSUER / UA_ACCOUNT_BASE_URL 等由部署链路注入；接入方注册走 IdP 侧 BSS_OAUTH_SEED_CLIENTS 幂等播种。

F-SSO-002 统一登出（后通道） ​

  • 描述：管理台「退出」清本地会话后联动跳 IdP /oauth/logout；IdP 以服务端 POST 把签名 logout_token 投到 POST /api/manager/auth/sso/backchannel-logout。
  • 实现：manager 校验 iss/aud/exp + events 事件键（拒绝携带 nonce 的令牌）后把该账号的 users.session_invalid_before 置为登出时刻——早于该水位签发的令牌随即失效（无状态 JWT 的服务端撤销）。重复投递幂等 200。前通道 /sso/logout 保留作升级窗口兜底。

F-SSO-003 平台员工授权同步 ​

  • 描述：users.is_platform_admin 是本地投影，判定以账号中心 platform_staff 为准（status=active 且 scopes 含 staff:manage 或 saas:ops）。
  • 实现：登录 / SSO / JIT / refresh / GET /me 主动同步；已链接账号按短 TTL 复验，撤销/停用即时降权；账号中心不可达保留本地值（可用性优先）。

四、管理台（业务控制台） ​

路由骨架：apps/admin/src/router/modules/*.ts；菜单文案 apps/admin/locales/zh-CN.yaml 的 menus.*。

4.1 首页仪表盘 ​

F-ADM-001 多角色仪表盘 ​

  • 描述：根据角色展示不同视角运营数据（/welcome）。
  • 实现：平台员工视角（概览数字卡、系统健康、三大分布饼图、快捷入口、四维监控）；部门管理员视角（组专属统计、实例状态进度条）；普通用户视角（可访问实例数、个人对话统计、7 天对话趋势）；租户管理员视角。

4.2 智能体管理 ​

F-AGT-001 智能体列表与三种创建方式 ​

  • 描述：/agents/index 网格卡片列表（搜索/状态/引擎筛选/分页），顶部三张创建路径卡：AI 助建（对话式生成人设与配置，受功能开关控制）、从模板创建（资产中心模板选择器）、自定义创建（向导表单）。
  • 组件：Manager — AgentDefinitions / AgentLifecycle / AgentBuilder API

F-AGT-002 智能体定义 CRUD 与版本快照 ​

  • 描述：管理智能体元数据（名称、描述、头像、引擎类型、状态、所属组），草稿编辑；发布时生成不可变版本快照，支持版本回滚。
  • API：POST/GET/PUT/DELETE /api/manager/agent-definitions（含 GET .../versions 版本列表）；POST /api/manager/agents/{definition_id}/publish（发布编排：生成版本快照，首次发布创建并上线首个实例）
  • 实现：AgentDefinition + AgentVersion（version_no 严格递增、配置快照、change_log）；配置字段 persona_config / model_config / skill_config / memory_config（JSON）。

F-AGT-003 智能体工作台（7 页签） ​

  • 描述：/agents/detail/:id 工作台，7 个页签：概览 / 构建 / 调试 / 版本 / 渠道 / 部署 / 分析。
  • 构建页签：人设（SOUL.md，Markdown）、模型、技能、MCP 服务、知识库、提示词、对话引导（开场白 + 推荐问题）、外接应用绑定与工作流编排只读预览（Dify）等面板。
  • 调试页签：与调试实例实时对话（复用统一对话实现）；调试实例读定义草稿，改完即生效。
  • 版本页签：版本列表 / 发布 / 回滚 / 变更说明。
  • 渠道页签：IM 渠道绑定（见 IM 章节）。
  • 部署页签：实例运行时状态、Pod 列表、日志、监控曲线、deploy/suspend/resume/restart/destroy、部署失败归因（管理侧详细原因 + 解决方案）。
  • 分析页签：用量与对话统计。

F-AGT-004 实例层生命周期 ​

  • 描述：定义 × 版本 × 资源池的实例关联，每实例分配模型网关虚拟 Key；业务状态 DRAFT/PUBLISHED/OFFLINE；上线/下架/版本切换/克隆；运行时 deploy/suspend/resume/restart/destroy。
  • API：POST/GET/PUT/DELETE /api/manager/agent-instances；POST .../publish、POST .../offline、POST .../switch-version、POST .../clone；POST .../{deploy|suspend|resume|restart|destroy}
  • 实现：SUSPEND 时存档数据到 MinIO；DESTROY 归档后仅清 K8s 资源。外接引擎实例（Dify）无 Pod：deploy 内联落 RUNNING，生命周期操作只改平台侧状态。

F-AGT-005 实例运行时详情与部署失败归因 ​

  • API：GET .../deployment-status（错误按受众分级：管理侧详细、终端侧通俗）、GET .../pods、GET .../pods/{pod}/logs、GET .../metrics、GET .../overview、GET .../deploy/events（SSE）
  • 实现：部署失败归因为机器码 <域>_<原因>（7 个故障域、25 个码），诊断取自 Pod 状态字段（不读 K8s Events）；不可自愈原因连续命中即提前返回（~15s 短路）；管理台按机器码走 i18n，终端侧只回通俗文案。

F-AGT-006 定时任务 ​

  • 描述：为智能体配置 cron 周期任务，到点自动驱动智能体执行并留存执行记录。
  • 组件：Manager — Agent Cron Jobs API
  • 实现：5 段 cron 表达式；任务归档；执行历史与状态展示（实例详情「定时任务」页签）。1.0 不含出站 Webhook（已裁剪）。

F-AGT-007 人设下发（引擎无关） ​

  • 描述：Markdown 人设对所有引擎生效；生效通道按引擎能力区分（写文件 / 请求体注入 / 平台侧配置），改完即生效。
  • 实现：system-file（Hermes 系，manager 写 SOUL.md fan-out）、request-field（DeepSeek，Gateway 每请求注入）、platform-config（Dify，外部平台侧承载）。生产实例读版本快照、调试实例读定义草稿。平台级文件引用规范（产出文件按 Markdown 相对路径引用）由统一组装事实源注入，对所有智能体无条件生效。

F-AGT-008 实例访问控制（access_scope） ​

  • 描述：实例访问范围 ALL/USER/USER_GROUP，与 RBAC 分离（终端用户不走 RBAC）；计费 Team 由 access_scope 派生。
  • API：GET /api/manager/agent-instances/accessible（终端门户可访问实例列表；对「无权限」与「不存在」同码同文案）

4.3 技能开发（Skill Studio） ​

F-SK-001 技能工作室 ​

  • 描述：在线技能开发工作台——浏览器内与开发/调试引擎对话生成技能文件，发布为不可变技能版本；版本可直接绑定到智能体，或提交资产中心审核后对其他用户开放安装。
  • 组件：Manager — Skills API（skills / skill_versions）+ skill-engine（工作区/子进程调试，:8004）+ Hub（审核发布）
  • API：POST /api/manager/internal/skills/publish（内部，X-Internal-Token）；GET /api/manager/skills/by-workspace/{workspace_id}；POST .../versions/{version_id}/submit-to-hub；POST /api/manager/agent-definitions/{id}/skills/install-from-skill
  • 实现：skill_versions 不可变快照，包存对象存储；调试进程 SSE 断开 10 分钟回收、单进程最长 2 小时、并发上限按 LRU 驱逐；软删工作区保留 30 天。
  • 菜单：「技能开发」（一级菜单）

F-SK-002 技能安装与下发 ​

  • 描述：技能挂定义层，支持安装/卸载/开关/列表；下发不重启 Pod（调试实例读草稿即生效；已发布实例需发布新版本 + 升级实例）。
  • API：GET/POST/PUT/DELETE /api/manager/agent-definitions/{id}/skills*（zip 包上传、preview 预检）
  • 实现：下发通道按引擎能力表分文件目录通道（Hermes 系，渲染引擎 config.yaml 的 skills.disabled）与共享目录通道（DeepSeek 系，共享目录对账为「本实例启用集」磁盘视图）；zip→tar.gz 剥离顶层目录 + 路径安全过滤；全链 reconcile（对象存储 ↔ DB ↔ Pod ↔ secrets.enc）自愈。
  • 从资产中心安装：技能详情页「安装到智能体」/ 智能体侧「从技能市场安装」弹窗。

F-SK-003 技能安全凭证 ​

  • 描述：技能可声明 secret 参数（manifest config_params），凭证「加密集中存储 + sidecar 解密」：明文不进 Pod env/日志、不回显、Pod 内本地解密。
  • 实现：skill_credentials.credentials_encrypted（Fernet/MultiFernet，支持 key 轮换）；密文 fan-out 到 Pod skills/{name}/secrets.enc；sidecar 容器（skill-secret-sidecar，Pod 内 :8004）按 skill+key 返回明文，解密 key 走 projected Secret 文件挂载（每请求重读，轮换无需重启）。详见 skill-credentials.md 与 skill-secret-sidecar-design.md。

4.4 MCP 服务 ​

F-MCP-001 MCP 目录与注册 ​

  • 描述：「MCP服务」一级菜单（卡片式目录）：注册/编辑/删除/测试连接外部 MCP server（Streamable HTTP / SSE / OpenAPI——OpenAPI 支持上传定义文件 ≤2MB 由平台托管）；凭证提交给模型网关加密持有，不落平台 DB。
  • API：GET/POST/PUT/DELETE /api/manager/mcp-servers；POST .../openapi-spec；GET .../alias-suggest；POST .../{id}/test
  • 接入信息：显示名 + 标识名、Logo / 来源链接、协议、认证方式（none / API Key / Bearer / Basic / OAuth2 / AWS SigV4）、实例级变量、最大并发数、请求配置。

F-MCP-002 两级可见性 ​

  • 描述：SYSTEM 级服务全租户可见（仅平台员工可改）；工作空间级服务按空间隔离，写入口要求 mcp:manage 权限码 + 当前空间可写（组织空间普通成员只读）。

F-MCP-003 定义级绑定与工具白名单 ​

  • 描述：智能体定义绑定 MCP server（多选弹窗），绑定可启停（停用保留条目）；支持工具白名单收敛智能体可见工具子集。
  • API：GET/PUT /api/manager/agent-definitions/{id}/mcp-servers；PUT .../mcp-servers/{alias}；POST .../mcp-servers/connect-from-hub（资产中心一键接入）
  • 实现：绑定经引擎能力表分文件通道（渲染进引擎 config.yaml）/ env 契约通道（引擎中立绑定契约，绑定变更自动下发并滚动重启）；凭证由模型网关代理托管，per-agent 可见性由平台侧绑定裁定。

F-MCP-004 系统内置知识库检索 MCP ​

  • 描述：kb_retrieval 为系统内置、目录不可见的 MCP server，由 manager 直接托管；智能体绑定任一知识库即挂载、全解绑即摘除（由绑定关系派生，不落用户绑定配置）。
  • 实现：经 forward_headers 转发 X-KB-Ids / X-KB-Options，static_headers 注入 X-Internal-Token 保护端点。

4.5 知识管理 ​

F-KB-001 知识库 CRUD（LightRAG） ​

  • 描述：知识库全生命周期管理（空间隔离的租户化资源），基于 LightRAG 引擎（PostgreSQL + pgvector，可选 Neo4j 图谱）。
  • API：GET/POST/PUT/DELETE /api/manager/knowledge-bases（搜索/排序）、GET .../stats
  • 实现：UA 表元数据 + 引擎 workspace 双写；向量模型/分块方式创建后不可改；问答模型（KB 级 qa_model，留空回落平台默认）、重排序模型、知识图谱开关与建图模型、图谱语言（中文/英文）可编辑；列表行合并引擎侧 processing/failed 计数。

F-KB-002 文档管理与异步解析 ​

  • 描述：文档上传/粘贴文本入库/解析/删除/分块预览，后台队列真异步解析，服务端分页与状态过滤；PDF 走 MinerU 解析。
  • API：POST .../documents/query、POST .../documents（上传即入队）、POST .../documents/text、POST .../documents/reprocess-failed、POST .../documents/{id}/parse、POST .../documents/batch-parse|batch-delete、GET .../documents/{id}/chunks、GET .../pipeline、POST .../pipeline/cancel
  • 实现：原文托管对象存储；worker 行级抢占（多副本安全）；失败一键重试先清引擎旧记录再入队；状态机 uploaded/queued/parsing/parsed/error + 阶段进度 + 失败机器码（前端 i18n 映射）。
  • Office 预览：Word/Excel/PPT 等 Office 文档在文档详情中在线预览。

F-KB-003 分块策略与知识图谱 ​

  • 分块：标准（定长）/ 智能（递归边界）/ 语义（向量相似度）/ 段落（段落语义合并），每策略差异化参数。
  • 图谱：KB 级开关 + 建图模型 + 图谱语言；开启后解析提取实体关系入 Neo4j、检索默认 hybrid 图增强；管理台只读可视化工作台（力导/环形布局 + 属性面板，邻居跳转/起点扩展）。图谱 API 含变长路径钳制防注入。

F-KB-004 检索测试与流式问答 ​

  • API：POST .../retrieval（top_k/阈值/模式/重排序）、POST .../query/stream（单库 NDJSON 帧流式问答）、POST .../query/multi/stream（多库合并检索）
  • 实现：配置重排序模型时经模型网关真实重排并返回分数；问答生成走 KB 级 qa_model，生成前预检模型可用性（不可用时错误帧带机器码，前端提示并支持一键切换）；引用帧映射 UA 文档支持「定位」跳转。

F-KB-005 绑定智能体与智能体级检索配置 ​

  • 描述：知识库 ↔ 智能体定义为显式 N:M 绑定（不进版本快照）；绑定变化对已部署实例滚动生效；绑定关系是内置检索 MCP 挂载态的唯一事实源；删库被绑定时拦截（可强制）。
  • API：GET/PUT /api/manager/agent-definitions/{id}/knowledge-bases；GET /api/manager/knowledge-bases/{id}/agents；GET|PUT .../retrieval-config（TopK/阈值/模式/重排序，effective 合并系统默认值）

F-KB-006 治理运维 ​

  • API：GET .../export?format=csv|md|txt、POST .../cache/clear、GET .../runtime（模型四角色 + 存储探活 + 队列概况）、GET /api/manager/rag/health

F-KB-007 附件内容识别（图片 / PDF） ​

  • 描述：智能体读取用户上传到会话工作区的附件——图片识别票面/单据要素（视觉模型），PDF 提取全文文本；扫描件如实说明并建议改用图片识别。
  • 实现：平台内置文件工具经 header 注入定位会话工作区；图片降采样后调视觉模型提取结构化要素。

4.6 资产中心（Hub） ​

F-HUB-001 资产目录 ​

  • 描述：「资产中心」一级菜单，统一管理三类可上架资产：智能体模板（可作为新智能体起点）、技能（安装到智能体）、MCP 服务（一键接入）。引擎不是可上架资产。
  • 实现：独立 hub 服务（:8003），管理台经 manager 代理访问；卡片式目录 + 详情页（版本记录/安全扫描/文件内容）。

F-HUB-002 上架审核流 ​

  • 描述：资产提交审核 → 平台员工在 Hub 批准发布；技能工作室的版本可一键「提交到资产中心」。
  • 权限：审核操作限平台员工（ua:hub:review scope）。

F-HUB-003 平台预置技能 ​

  • 描述：平台开箱预置一批技能（研究/生产力/编程/数据分析/设计/写作六类），带「官方」标识，与自行上架技能使用方式一致（直接安装到智能体）。

F-HUB-004 智能体模板创建 ​

  • 描述：从资产中心智能体模板创建新智能体（列表页「从模板创建」卡片打开模板选择器）；模板的开场白与推荐问题随模板下发。

4.7 监控中心（9 个子页） ​

子页路由数据源
对话记录/monitoring/conversationsLangfuse（按会话聚合，含工具调用入参出参）
链路追踪/monitoring/traceLangfuse（单次调用视角，可关联 Hermes 内部调用）
资源监控/monitoring/resourcesPrometheus / metrics-server
服务健康/monitoring/service-healthPrometheus（含 SLO 阈值）
用量分析/monitoring/usage模型网关用量日志（Token 与成本）
调用分析/monitoring/callsLangfuse
异常告警/monitoring/alerts告警引擎（alert_rules / alert_channels / alert_events）
操作记录/monitoring/operation-logManager 操作日志表（仅覆盖管理台用户行为）
服务日志/monitoring/log-searchLoki
  • 权限：业务监控码按空间收敛（租户/部门管理员仅本空间只读）；平台监控码（资源/健康全平台口径）限平台员工。
  • 实现：告警支持从告警跳链路追踪；用量分析支持 USD→CNY 汇率转换与部门维度过滤。

4.8 社区 ​

F-COM-001 社区模块 ​

  • 描述：社区文章区（/community，地址直达、不占侧边栏菜单）：文章列表 / 详情 / 创建 / 编辑，提交后由平台运营在运营侧审核上线（community_articles），供租户内知识分享与内容运营。1.0 不提供控制台内审核页。

4.9 系统管理（业务控制台） ​

F-SYS-001 终端用户管理 ​

  • 描述：/system/enduser/index——终端用户（end_users 表）列表、启停用、删除；停用后无法登录终端门户、数据保留；操作留痕。

F-SYS-002 个人额度 ​

  • 描述：/ops/user-quotas（运营控制台，仅平台员工）——按用户配置其个人空间用量额度（user_resource_quotas），超限即限制新增；业务侧公司/部门空间不提供入口。

角色管理 / 资源池 / 模型与 Key / 引擎管理 / 产品设置已迁入运营控制台（见第五章）；业务菜单旧路径保留 redirect 兼容书签。

4.10 账户设置与通用能力 ​

F-ADM-010 账户设置 ​

  • 描述：/account-settings——当前账号资料与凭证自助（跳账号中心，SSO 已配置时免登直达）。

F-ADM-011 i18n 与技术栈 ​

  • 实现：中英文双语（Vue i18n + YAML 语言文件）；Vue3 + TS + Element Plus + Vite + Pinia + Vue Router 4 + ECharts；Tailwind + SCSS + 暗色主题；RBAC 动态路由 + 按钮权限。

五、运营控制台（/ops） ​

独立顶层路由树（apps/admin/src/router/opsRoutes.ts），复用业务控制台外壳组件，顶栏带「运营控制台」标签；业务侧旧路径保留 redirect。访问收口：平台员工，或当前企业空间的租户 owner/admin。业务控制台与运营控制台可互相切换（顶栏入口）。

F-OPS-001 租户 ​

  • 描述：/ops/tenants——租户台账（个人/企业两类）：名称/所有者/成员数/部门数/实例数/状态，详情含组织空间与部门树；支持停用（关闭）。（scope：saas:ops）

F-OPS-002 终端用户管理（运营面） ​

  • 描述：/ops/end-users——跨租户终端用户检索（用户名/姓名/手机/邮箱）、按租户过滤、启停用与删除，含未归属用户过滤。

F-OPS-003 角色管理 ​

  • 描述：/ops/roles——角色 CRUD 与权限树配置；按作用域（租户/部门）分配；权限树搜索过滤 + 全选/展开联动；绑定弹窗按当前空间展示绑定明细与撤销入口。

F-OPS-004 资源池管理（运营面） ​

  • 描述：/ops/resource-pools（+ 详情页）——资源池列表、容量与回收策略、池内实例与实时用量监控（CPU/内存趋势图）。

F-OPS-005 模型与 API Key（运营面） ​

  • 描述：/ops/models、/ops/keys——模型管理（上游供应商连接参数）与 API Key 管理（预算/速率限制/封禁），详见「模型网关」章。

F-OPS-006 引擎管理 ​

  • 描述：/ops/engines（+ 详情页）——引擎目录（Hermes / DeepSeek / Dify 外接）与默认规格展示；Dify 平台接入配置（连接信息、管理员凭据、可观测纳管开关、应用列表与批量导入、平台状态巡检）；引擎版本升级（对存量实例滚动换镜像，灰度与失败可见）。

F-OPS-007 产品设置 ​

  • 描述：/ops/settings——平台级运营配置三页签：语音识别（ASR）、AI 生成（人设/头像/对话引导开关与模型配置）、品牌与外观（产品名/标语/版权/备案号/Logo/网站图标）。
  • 实现：取值链 DB > 环境变量兜底 > 代码默认；敏感值加密落库、API 只回配置状态；品牌经公开端点下发，管理台与终端门户登录页/导航/页脚/浏览器标题运行时生效。

六、终端门户（Enduser Portal） ​

详见 enduser-portal.md。技术栈 Vue3 + Tailwind + Pinia，全部对话交互自研 Vue 3 组件直渲染（无 iframe）。

F-END-001 三个页面 ​

  • 路由：/login（登录，支持账号密码/邮箱/手机/短信验证码）、/agents（落地解析：直达目标对话页；无可用智能体时空态引导）、/agents/:id（可访问性校验 → 部署检测 → 进度展示 → 对话页）。

F-END-002 认证与落地 ​

  • 实现：JWT 双 Token + LocalStorage 持久化 + 401 跳登录；落地优先级 = redirect 深链 > 上次对话智能体（localStorage，按用户隔离）> 服务端最近访问 > 可访问列表第一个。路由守卫统一记录 last_agent_id；判定无权时清除该记录避免反复掉回无权页。

F-END-003 五相位状态机与出口保证 ​

  • 描述：对话页按 loading / deploy / chat / error / access-denied 五相位渲染；非聊天态统一套外壳组件，「切换智能体」与「退出登录」出口恒在，不存在死胡同。权限判据唯一权威 = 可访问列表成员资格（后端对无权限/不存在同码同文案）。异常文案统一映射，不把后端错误原文上屏。

F-END-004 会话管理 ​

  • 描述：会话由引擎自身管理（不入平台 DB），门户经 Gateway /v1/sessions* 访问；两种会话形态（引擎侧预创建 / 本地占位首轮替换）按引擎能力自动选择。历史列表按最后活跃倒序 + 搜索 + 日期分组；历史记录按数据形态归一（消息列表/轮次列表两种载荷兼容）；支持继续对话与删除。

F-END-005 统一对话体验 ​

  • 描述：流式渲染（ReadableStream + TextDecoder 逐块解析 SSE）、「VES 帧 → 展示态」投影、思考收束、工具卡落定等协议级行为与管理台调试面板、Skill Studio 复用同一份共享实现；门户只保留会话管理、鉴权头、持久化等宿主业务。
  • 执行轨迹：思考、工具调用、工作流节点三类事件在同一轴上按到达顺序排列，按回答段落收成可展开摘要行（单步说动作名、多步给步数与总时长）；MCP 工具以「服务 · 工具」两段式展示；「执行中断」只在整个任务失败或被强制停止时出现；等待人工处理节点显示等待态。
  • 停止生成：中断 SSE 读取并向取消端点发取消；对支持取消的引擎真正终止引擎侧执行；对已结束的 run 重复取消幂等。

F-END-006 工作流输入参数表单 ​

  • 描述：工作流型智能体在会话首开前渲染输入参数表单（text-input / paragraph / number / select 四类，必填校验），值随首轮请求 inputs 提交；不支持表单的引擎按能力档案跳过。

F-END-007 工作区与附件 ​

  • 描述：树形文件浏览器（按引擎能力显隐：仅暴露会话文件接口的引擎渲染）；附件上传两条链路（平台工作区链路 / 引擎原生链路，按能力显隐）；工作区打包下载（workspace.tar.gz，排除平台凭据）；回复内 mermaid 渲染、相对路径图片内联、非图片文件可点击下载。

F-END-008 消息反馈（点踩） ​

  • 描述：助手回复提供点踩入口，弹窗选择原因 + 补充说明，提交落库；历史反馈随消息加载恢复展示，供运营回溯分析。

F-END-009 品牌白牌运行时 ​

  • 描述：登录页品牌区、顶部导航产品名、页脚版权与 ICP 备案链接、浏览器标题与图标按「产品设置 → 品牌与外观」在线定制；启动时经公开端点拉取，失败回落构建期默认。

F-END-010 体验细节 ​

  • 浅色/深色/系统主题 + 四档字体大小；面板开关记忆；会话 Markdown/JSON 导出导入；距底部 150px 内自动滚动 + 阅读暂停 + 回到底部按钮；移动端三档断点（手机抽屉化 + 底部 tabbar + 触摸手势 + 软键盘适配）。

七、引擎集成 ​

F-ENG-001 引擎清单与镜像版本 ​

  • 描述：引擎仅三类——HERMES（veyra/veyra-os/engine-hermes:0.19.0-veyra.3，:8642）、DEEPSEEK（veyra/veyra-os/engine-deepseek:0.2.1-rc.2-veyra.1，:8649）、DIFY（仅外接，无 Pod）。
  • 实现：ENGINE_RUNTIMES 强契约（镜像/端口/分类在此登记，新增引擎必须改代码）；镜像 tag 走引擎独立语义化版本（<上游版本>-veyra.<修订号>，唯一真相 engines/<name>/VERSION），部署链路按该文件渲染注入；未知/空引擎类型显式报错，禁止回落。

F-ENG-002 引擎能力表（EngineCaps） ​

  • 描述：pkg/common/engine_caps.py 是 manager / gateway 共用的唯一引擎能力事实源——引擎差异（会话文件 API、流式族、Profile 形态、模型配置通道、资产通道、沙箱、生命周期、外接绑定）一律经能力查询，不得在业务代码散落引擎名分支。
  • 实现：不可变 dataclass，默认值 = HERMES 现状；严格/宽容两形态查询；caps_view() 唯一对外序列化形态，经 GET /api/manager/engines 下发驱动前端 UI 门控；前后端均有字面量扫描门禁（接 make lint）。

F-ENG-003 Hermes 引擎容器化 ​

  • 描述：不侵入式修改源码，容器化部署于 K8s Pod，通过原生 HTTP API 调用；多 Profile 隔离（per-profile UID 降权 + port_map.json 端口单源真相，绝不串号）；PVC 持久化 /opt/data/profiles/{name}。
  • 模型注入：部署时按实例模型配置派生 env（模型网关地址 + per-instance key + 默认模型）。

F-ENG-004 DeepSeek Harness 引擎 ​

  • 描述：把 dsh CLI 包装为 OpenAI 兼容 HTTP/SSE 服务；模型统一经平台模型网关（per-instance key）；技能走共享目录「启用集」磁盘视图（变更下一轮请求即生效），MCP/知识库走引擎中立契约（绑定变更自动下发滚动重启）；人设经 env 进入引擎原生 system prompt 通道。
  • 连续对话：每轮独立子进程，session/resume 恢复原生上下文；旧版升级的会话从文本历史恢复。

F-ENG-005 Dify 外接引擎（External-Only） ​

  • 描述：外接是 Dify 的唯一模式——平台对接用户自管的 Dify 实例（自托管或 Dify Cloud），不部署其任何组件；绑定对象是外部平台上的一个应用。
  • 引擎配置：全局单条（平台地址必填 + 管理员凭据可选 + 可观测纳管开关）；凭据加密落库只回配置状态；后台每 5 分钟平台健康巡检写回展示。
  • 定义级绑定：已配管理员 → 下拉选应用自动回填密钥；未配 → 手填地址+密钥+类型并验证；支持密钥轮换（定义级一次换全部实例）、模型通道可视化（经平台网关 / 直连外部模型服务）、编排摘要只读展示（变量/数据集/工具，环境变量值掩码）、应用批量导入为智能体。
  • 运行时：无 Pod、不占资源池，发布即上线；生命周期操作只改平台侧状态；空闲回收调度器不休眠外接实例。

F-ENG-006 命令沙箱（OpenSandbox） ​

  • 描述：实例可启用命令沙箱：终端命令提交到独立沙箱 Pod 执行（与引擎隔离，每用户一个沙箱、空闲自动回收、产物同步回实例数据卷）。
  • 实现：实例 runtime_config.sandbox 段（enabled/image/cpu/memory/disk/lifetime）→ 部署时注入引擎 Pod env；沙箱镜像二选一（平台默认预置绘图/PDF/PPT/Word/Excel 库与中文字体，或 slim 无预置包）。

F-ENG-007 编排画布只读内嵌（管理台 iframe 唯一例外） ​

  • 描述：工作台「构建 → 工作流编排」只读内嵌外部平台的图形化编排画布；URL 只指向平台画布代理地址（不接受用户输入），iframe 带 sandbox 收敛权限 + 透明拦截层实现 UI 级只读；代理仅放行 GET/HEAD + 路径白名单，剥离上游 Set-Cookie/X-Frame-Options；代理不可用时降级「在外部控制台打开」外链。终端门户不适用此例外。

F-ENG-008 引擎生命周期状态机 ​

  • PENDING → DEPLOYING → RUNNING ↔ SUSPENDED → ARCHIVED，含 FAILED 分支；30min 空闲自动 SUSPEND（存档 MinIO + scale=0），24h 空闲 DESTROY（归档后清 K8s 资源）。

八、资源池与 K8s 编排（Manager worker，原 Controller 职责） ​

原独立 services/controller（:8001）已并入 manager（services/manager/app/worker/），字面路径仍为 /api/controller/*。

F-POOL-001 资源池 CRUD ​

  • 描述：管理池级资源上限（CPU/内存总量、Pod 数上限）与回收策略；单 Pod 规格由部署实例时的「资源规格」决定。
  • API：POST/GET/PUT/DELETE /api/manager/resource-pools；GET .../metrics（池下 Pod 实时用量）
  • 实现：池级配额按池内各行实际生效 requests 求和核算，超限拒绝新建；创建/修改校验同集群各池容量合计不超过集群实际容量（查不到不阻塞）；支持平台共享池与空间私有池；回收策略 idle_suspend_minutes / idle_destroy_hours；支持克隆（集群凭据一并复制）。

F-POOL-002 对接外部 K8s 集群 ​

  • 描述：资源池可绑定内置集群以外的 K8s 集群（数据不出域/就近部署）；平台仍统一管理实例生命周期，Pod 落到该集群，引擎经 NodePort 暴露。
  • 实现：kubeconfig 加密落库（明文不出 API）；保存前连通性预检；按池缓存独立客户端；集群不可达明确失败绝不回落本集群；仅支持共享运行与目录式引擎（独立运行前置拦截）；巡检/备份按部署所属池解析目标集群，不可达本轮跳过不拿本集群视角纠正状态。

F-POOL-003 引擎 Pod 生命周期（worker） ​

  • API：POST /api/controller/agents/{id}/{deploy|suspend|resume|restart|destroy}、GET .../status、GET .../deploy/events（SSE）
  • 实现：Deployment + Service + PVC 创建（命名 engine-hermes-{id[:8]}[-scope]，标签 agent.veyraos/agent-id / group-code）；SUSPEND 存档到 MinIO（组隔离路径 groups/{group_code}/backups/）；RESUME 清理 stale 锁恢复；DESTROY 归档守卫（拒绝 409 可重试，force=true 强清）；管理台删除实例在运行态未回收时先自动走销毁流程，杜绝孤儿资源。
  • 多 Profile 共享调度：多智能体共享同一 Pod 按负载 fan-out；profile 创建/端口分配/nginx 动态 reload；Pod 启动主动注册 profile 列表并清理 stale 记录。
  • 配置与人设/技能同步：POST .../config/sync|apply 统一生成 config.yaml；人设 SOUL.md fan-out 写文件即生效；技能 install/uninstall/sync 热生效。

F-POOL-004 配额与后台调度 ​

  • 实现：引擎默认资源规格随引擎标准定义（GET /engines 返回），实例可覆盖，实际生效值落库供池配额核算；空闲回收调度器（每 5min 检查 RUNNING、30min 空闲 SUSPEND；每小时检查 SUSPENDED、24h DESTROY）；状态巡检每 60s 更新 last_active_at 并修正异常；指标采样每 60s 经 metrics-server 落库（保留 7 天，按实例/资源池聚合）。

九、Gateway（数据面网关） ​

F-GW-001 DNS 命名规范路由（无反向依赖） ​

  • 描述：通过 X-Agent-ID 头 + DNS 命名规范构造 upstream（engine-hermes-{id[:8]}[-{scope}].{ns}.svc.cluster.local:8642），不查询任何服务取地址；Pod 重启检测缓存失效。外接引擎实例例外：从绑定配置取外部平台地址直连（300s 缓存 + 变更主动失效 + 502/503 触发失效）。

F-GW-002 Profile 感知路由与权限闸门 ​

  • 描述：基于用户身份与实例配置动态解析目标 Profile（INDEPENDENT 按用户 / SHARED 组内共享）；60s 正缓存 + 10s 负缓存；IM 用户 ID 映射（im_user_bindings）；组隔离统一校验无平台员工旁路；转发前权限验证，权限拒绝不吞错当降级。
  • 实现：Pod 内 nginx 按 X-Hermes-Profile 头路由到 per-profile 端口（port_map.json 唯一真相）；共享运行实例走路径前缀 /p/{profile}/。

F-GW-003 安全头过滤与 SSE ​

  • 实现：过滤 Origin/Referer/host/客户端 X-Hermes-Profile（服务端重算），注入引擎认证头；SSE 流式不缓冲（proxy_buffering off），Connection: upgrade 会干扰 SSE 需避免。

F-GW-004 两个流式出口 ​

  • 描述：POST /v1/runs → 统一 VES 事件流（各引擎原生事件归一为单一协议，门户只消费这一种）；POST /v1/chat/completions → OpenAI chunk 流（引擎私有帧清洗掉，与 OpenAI SDK 生态兼容）；非流式保持引擎原生格式。

F-GW-005 Dify 外接适配 ​

  • 描述：从 DB 解析绑定配置直连外部平台 Service API，把外部事件（message / node_* / agent_thought / workflow_paused 等）归一为 VES 帧；停止语义真正终止外部平台任务（按应用类型派生停止路径）；会话标识经流式响应回传实现多轮继承；用户锚点统一注入 veyra-{end_user_id} 防伪冒；历史会话经 Service API 代理（数据形态归一）；工作流节点进度帧与等待人工处理态复用 step 帧（不新增帧类型）。

F-GW-006 会话与健康 ​

  • 实现：确定性 session ID + 30min TTL + 引擎重启清理；健康检查与自动恢复（冷启动最长 300s 轮询）；重试指数退避 [1s,2s,4s]；DB 配置 60s 缓存 + 主动失效。

十、企业 IM 渠道接入 ​

详见 IM 渠道接入说明。

F-IM-001 渠道绑定与管理 ​

  • 描述：为实例绑定企业微信/飞书/钉钉渠道（工作台「渠道」页签），支持独立/共享 Profile；敏感配置脱敏显示；回调地址自动生成。
  • API：GET/POST/PUT/DELETE /api/manager/agent-instances/{id}/channels

F-IM-002 Webhook 入口与异步分发 ​

  • 路径：POST/GET /api/gateway/channel/{channel_type}/{agent_id}/callback（消息回调 / URL 验证）、POST .../menu（企微菜单）、POST .../send（引擎主动发消息）
  • 实现：验签后立即 200 ACK，dispatcher 异步处理：消息去重（60s TTL）→ 权限闸门（未绑定 IM 用户拒绝并提示）→ 语音转录（ASR）→ 引擎唤醒（冷/热启动）→ 会话（30min TTL）→ Profile 解析 → 转发。

F-IM-003 平台适配器 ​

  • 企业微信：SHA1 签名 + AES-256-CBC 解密；不支持编辑/流式，2048 字节智能分段（UTF-8 安全切分）；卡片 JSON 括号配平容错提取。
  • 飞书：HMAC-SHA256 + Challenge；交互式卡片 PATCH 流式编辑（启动卡 + 回复卡双卡策略）。
  • 钉钉：HMAC-SHA256 + checkUrl + OAuth 2.0；无编辑/流式。
  • 企微 AI Bot（wecom_bot）：WS 透明桥接，不经 dispatcher。
  • 扩展：新增渠道实现 BaseChannelAdapter + @register 注册即可。

十一、模型网关 ​

F-LLM-001 模型管理 ​

  • 描述：声明式供应商目录驱动模型新建/编辑与草稿连接测试；内置 12 家常用供应商及兼容端点/本地/高级入口，统一处理 Azure API 版本、AWS Bedrock 凭据、用途校验、密钥保留和供应商切换清理；模型别名供智能体表单选择。
  • API：GET /api/manager/litellm/model-presets；GET/POST/PUT/DELETE /api/manager/litellm/models；POST /api/manager/litellm/models/test-connection-draft；权限 litellm:model:manage。

F-LLM-002 API Key 管理 ​

  • 描述：每实例一虚拟 Key，归属租户对应 Team，支持预算（max_budget + budget_duration）/速率（rpm/tpm）限制、封禁/解封、智能关联解析（metadata.agent_id 或 key_alias）；平台员工不限范围，部门管理员仅限本部门。
  • API：GET/POST/PUT/DELETE /api/manager/litellm/keys；POST /api/manager/agent-instances/{id}/litellm-key/reprovision（重签发）

F-LLM-003 计费与用量统计 ​

  • 描述：Team 按租户建立（UserGroup ↔ Team 1:1 同步保留）；按组/模型/时间维度的 token 用量与费用统计。
  • API：GET /api/manager/litellm/spend[ /summary | /by-model | /trend]；USD→CNY 汇率转换；部门管理员仅见本部门。
  • 例外：外接引擎的模型由外部应用自持（可能经平台网关也可能直连外部模型服务，后者用量平台无法完整归集，管理台展示模型通道供核对）。

十二、部署架构 ​

F-DEP-001 一键部署 ​

  • 描述：bash deploy/ci/deploy.sh <版本号>——读 deploy/ci/.env.local（域名/镜像仓库/DB 凭据，gitignore）+ 各 engines/*/VERSION，用 sed/envsubst 渲染 deploy/ci/deployment.yaml 的 ${VERSION} / ${REGISTRY} / 引擎版本等占位符后 kubectl apply。
  • 组件：Deployment × 6（manager / gateway / console-admin / enduser-portal / hub / skill-engine，无独立 controller）+ LiteLLM + Secret + Ingress（chat/admin 两个子域；account 与 landing 子域由 veyra-bss / veyra-router 仓部署）。

F-DEP-002 基础设施 ​

  • PostgreSQL 16（StatefulSet+PVC，veyraos+litellm 两库）、MinIO（对象存储）、Neo4j（知识图谱，可选）、OpenSandbox（命令沙箱，可选）、metrics-server（资源监控数据源）、monitoring 栈（Prometheus/Loki/Langfuse/Grafana）。

F-DEP-003 镜像与发布 ​

  • 描述：平台/引擎镜像由主仓流水线手动 job 构建推送（已发布 tag 不可变）；镜像名统一 veyra/veyra-os/<service> 形态；构建期基础镜像统一经本仓 registry 分发（不依赖第三方加速服务）；离线 bundle 在 Linux 执行机构建。
  • 入口地址：UA_PORTAL_BASE_URL（终端门户）/ UA_ACCOUNT_PORTAL_URL（账号中心，为空时管理台内账号中心入口隐藏）由部署链路按域名注入。

F-DEP-004 安全配置 ​

  • veyraos-secret 统一凭据（仓库内仅占位符）；ServiceAccount+Role+RoleBinding RBAC；TLS 证书 Secret；敏感信息只走 env/k8s Secret/.env.local。

十三、公共包与文档体系 ​

F-PKG-001 统一配置 ​

  • pkg/common/config.py 全局配置 + ENGINE_RUNTIMES 常量；dev/prod 区分；UA_ 前缀环境变量覆盖。

F-PKG-002 共享数据模型与异步连接 ​

  • pkg/models/ 跨服务共享模型；pkg/common/database.py SQLAlchemy async 引擎 + 连接池。

F-PKG-003 版本号体系 ​

  • SemVer，仓库根 VERSION 文件唯一真相（scripts/bump-version.sh 同步）；镜像 tag 用裸版本号，git tag 加 v 前缀。

F-DOC-001 文档体系 ​

  • apps/docs/content/：架构（architecture/）、特性（features/）、部署（deployment/）、使用指南（guide/）、变更日志（changelog/）。

十四、关键技术约束（复刻必须遵守） ​

约束说明
Gateway 反向依赖禁止Gateway 不得查询其他服务获取 upstream，仅靠 X-Agent-ID + DNS 命名；例外：外接引擎实例不经 DNS，由绑定配置取外部平台地址直连
SSE 与 nginxproxy_buffering off；Connection upgrade 会干扰 SSE；浏览器 ReadableStream+TextDecoder 解析；nginx 不得缓冲/修改 SSE
iframe 默认禁止终端门户不 iframe 嵌 hermes-webui，直接渲染 Vue3 组件。唯一例外：管理台工作台「构建」页签对外部工作流引擎 Dify 的图形化编排画布只读预览（经平台同源代理 + sandbox + 透明拦截层 UI 级只读 + 降级外链）
Gateway Origin 过滤转发前去掉 Origin/Referer（Hermes 收 Origin 返 403）
存档策略存档提前到 SUSPEND（30min 空闲）；不定期轮询备份；PVC 实时写；DESTROY 仅清 K8s 资源；外部实例不适用（无 Pod/PVC，不被空闲回收自动休眠）
会话不入 Manager DB聊天会话由引擎自身管理，门户经 Gateway 会话接口访问
空间隔离UserGroup 为租户内资源归属单元；资源表 group_id；管理台平台员工旁路，网关数据面无旁路（跨组调试走代发凭证）
模型网关统一出口内置引擎只走模型网关；租户=Team；每实例一 key；计费 Team 由 access 派生。例外：外接引擎模型由外部应用自持（用量归集见 F-LLM-003）
引擎差异经能力表引擎差异一律经能力表查询（后端 EngineCaps、前端能力缓存、门户协议档案），不得散落引擎名分支；前后端字面量扫描门禁接 make lint 与 build
开源软件不侵入只用扩展能力 + 云化加固，引擎容器化通过原生 HTTP API 调用；外接引擎不部署不编排，只经其原生 API 对接
对话行为共享所有对话页面的流式行为复用同一份共享实现；修改帧语义/收束时机/轨迹展示只改共享层

1.0 裁剪说明 ​

以下能力在 1.0 已移除，复刻时不应再出现：出站 Webhook、一键演示（演示账号/演示实例）、coding projects、Cloud Browser（云端浏览器引擎）、多引擎列表中的其他实验性引擎、控制台内社区审核页（文章审核由平台运营在运营侧处理）。引擎仅 HERMES / DEEPSEEK / DIFY（外接）三类。

复刻核对清单（按域统计） ​

域特性数
多租户与工作空间5（F-WS-001 ~ F-WS-005）
作用域 RBAC5（F-RBAC-001 ~ F-RBAC-005）
SSO 统一认证3（F-SSO-001 ~ F-SSO-003）
管理台（仪表盘/智能体/技能/MCP/知识/资产/监控/社区/系统/通用）32（F-ADM/F-AGT/F-SK/F-MCP/F-KB/F-HUB/F-COM/F-SYS）
运营控制台7（F-OPS-001 ~ F-OPS-007）
终端门户10（F-END-001 ~ F-END-010）
引擎集成8（F-ENG-001 ~ F-ENG-008）
资源池与编排4（F-POOL-001 ~ F-POOL-004）
Gateway6（F-GW-001 ~ F-GW-006）
IM 渠道3（F-IM-001 ~ F-IM-003）
模型网关3（F-LLM-001 ~ F-LLM-003）
部署架构4（F-DEP-001 ~ F-DEP-004）
公共包与文档4（F-PKG/F-DOC）
合计94 项特性

复刻时建议按「多租户与权限 → SSO → 智能体三层模型 → 资源池与引擎生命周期 → 模型网关 → 技能/MCP/知识库 → 资产中心 → IM 渠道 → 监控 → 终端门户 → 部署运维」顺序推进，每完成一项核对编号打勾。

基于内网部署的企业级 AI 智能体平台

© 2026 VeyraOS