VeyraOS（VeyraOS）— 产品特性全量清单

版本：v0.7.0（三层模型基线，2026-06-23 线上发布）用途：作为「版本能力全量复刻」基线，用于迁移到其它语言/框架时逐项核对。维护：每次新增能力请同步更新本清单。

0. 产品定位与整体架构

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

智能体开发层：定义/版本/人设/技能的可视化开发与版本化管理
运行资源管理层：K8s 资源池规格、配额、回收策略
智能体实例层：定义 × 版本 × 资源池的运行实例，完整生命周期
统一模型网关：LiteLLM 作为全系统唯一模型出口，per-instance 精确计费
企业 IM 集成：飞书/企业微信/钉钉渠道接入，流式响应
终端门户：浏览器端 Chat 界面，复刻 hermes-webui 体验

两大后端微服务（同 namespace veyraos 部署，REST 解耦）：

服务	端口	职责
Manager	8002	业务后台 API：定义/资源池/实例/权限/计费/仪表盘；含原 Controller worker（`/api/controller/*` 引擎 Pod 生命周期：K8s 资源、Profile、存档恢复、回收调度，已并入 manager，无独立 :8001 服务）
Gateway	8010	反向代理 + IM 渠道分发 + SSE 流式 + 权限闸门

两大前端：

前端	技术栈	端口	面向
Admin Console	Vue3 + Element Plus + TS（vue-pure-admin）	8848	平台/组管理员
Enduser Portal	Vue3 + Tailwind + Vite + Pinia	3000	终端用户

一、Manager Backend（services/manager）

1.1 智能体定义层

F-MGR-001 智能体定义 CRUD

描述：管理智能体元数据（名称、描述、头像色、引擎类型、状态、所属组），支持草稿编辑。
组件：Manager Backend — AgentDefinitions API
API：POST/GET/PUT/DELETE /api/manager/agent-definitions
实现：AgentDefinition 模型（name, description, avatar_color, engine_type, status, group_id）；组隔离，跨组返回 404；配置字段 persona_config / model_config / skill_config / memory_config（JSON）。

F-MGR-002 版本快照与发布

描述：发布定义时生成不可变版本快照，支持版本回滚与语义化版本号。
组件：Manager Backend — AgentDefinitions API
API：POST /api/manager/agent-definitions/{definition_id}/publish
实现：AgentVersion 模型（version_no, 配置快照, change_log）；发布时草稿配置拷贝为快照并置为 current_version；定义详情返回 current_version_no 与 instance_count。

F-MGR-003 人设配置

描述：Markdown 格式人设，对所有引擎生效；生效通道按引擎形态区分（写文件 / 请求体注入 / 平台侧配置），改完即生效，无需重启 Pod。
组件：Manager Backend — AgentDefinitions API（配置存储）+ worker（文件通道同步）+ Gateway（请求体通道注入）
实现：存于 persona_config；通道由 EngineCaps.assets_persona 决定——system-file（Hermes 系，manager 写 SOUL.md fan-out）、request-field（Claude Code / DeepSeek，无 SOUL.md 运行时同步，Gateway 每请求从共享库读人设注入请求体）、platform-config（Dify，人设由平台侧应用配置承载）。生产实例读版本快照、调试实例读定义草稿。

F-MGR-004 技能管理（定义层）

描述：技能挂定义层，支持安装/卸载/开关/列表；改动经发布新版本 + 实例升级下发，下发不重启 Pod（调试实例读定义草稿，改完即生效）。
组件：Manager Backend — Agent Skills API
API：
- GET /api/manager/agent-definitions/{definition_id}/skills（列表）
- POST .../skills/install（安装，zip 包上传）
- PUT .../skills/{skill_id}（开关）
- DELETE .../skills/{skill_id}（卸载）
实现：技能配置存 skill_config JSON；内置技能扫描 + 自定义 zip 上传；zip→tar.gz 转换并剥离顶层目录；路径安全过滤。下发通道由引擎能力表决定：文件目录通道（Hermes 系）重写引擎 config.yaml 的 skills.disabled；共享目录通道（DeepSeek 系）把引擎可读的共享目录对账为「本实例启用集」磁盘视图（启用在位、停用/卸载移除，包缺失时按 COS 装回）——两者下发均不重启 Pod。启用集按实例自身配置取：生产实例＝版本快照、调试实例＝定义草稿，故定义层的技能增删/停用对已发布实例需发布新版本 + 升级实例后生效（与配置版本化模型一致）。

F-MGR-004b 外部工具（MCP）

1.2 资源池层

F-MGR-005 资源池 CRUD

描述：管理池级资源上限（CPU/内存总量、Pod 数上限）与回收策略，并可将池指向外部 K8s 集群；单个 Pod 的 CPU/内存规格不在池上配置，由部署实例时的「资源规格」决定（不修改按引擎默认规格）。
组件：Manager Backend — ResourcePools API
API：POST/GET/PUT/DELETE /api/manager/resource-pools
实现：ResourcePool 模型；池级配额字段 pool_cpu_quota / pool_memory_quota / max_replicas（NULL=不限；新建默认 2 核 / 4Gi / 8 Pod，按池内 Pod 实际生效 requests 逐行求和核算——每行 agent_deployments.pod_cpu_request / pod_memory_request 在部署时落库，超限拒绝新建，见 pool_quota_service.py）；创建/修改时校验同一目标集群上各池容量上限合计不超过集群实际容量（节点 allocatable 求和，K8sManager.get_cluster_capacity，容量查不到时跳过校验不阻塞保存；集群扩容后可再调高，见 resource_pool_service._check_cluster_capacity）；支持平台共享池（group_id=NULL）与组私有池；回收策略字段 idle_suspend_minutes / idle_destroy_hours；最大会话数为实例级配置（runtime_config.max_sessions_per_pod，未设按运行形态默认共享 200/独立 15，见 worker/_common.resolve_max_sessions_per_pod）；支持克隆（集群凭据一并复制）。

F-MGR-005b 资源池对接外部 K8s 集群

F-MGR-006 资源池实时监控

描述：监控资源池下所有 Pod 的 CPU/内存用量与状态。
组件：Manager Backend — ResourcePools API
API：GET /api/manager/resource-pools/{pool_id}/metrics
实现：代理 controller 拉取 metrics-server 数据；返回运行/停止/异常状态统计 + 实时用量。

1.3 实例层

F-MGR-007 实例 CRUD

描述：定义 × 版本 × 资源池的实例关联，每实例分配 LiteLLM key 归属 UserGroup Team。
组件：Manager Backend — AgentInstances API
API：POST/GET/PUT/DELETE /api/manager/agent-instances
实现：AgentInstance 模型（definition_id, version_id, resource_pool_id, status, litellm_config）；业务状态 DRAFT/PUBLISHED/OFFLINE。

F-MGR-008 实例业务生命周期

描述：上线/下架/版本切换/克隆。
组件：Manager Backend — AgentInstances API
API：
- POST .../publish（上线）
- POST .../offline（下架）
- POST .../switch-version（版本切换，触发 controller 重启）
- POST .../clone（克隆）

F-MGR-009 实例运行时生命周期

描述：通过 controller 管理部署/暂停/恢复/重启/销毁。
组件：Manager Backend — AgentInstances API（代理 Controller）
API：POST /api/manager/agent-instances/{instance_id}/{deploy|suspend|resume|restart|destroy}
实现：SUSPEND 时存档数据；DESTROY 时归档到 MinIO（ARCHIVED）；统一 ControllerError 错误处理。外接引擎实例（config_channel=external）无 Pod：deploy 内联落 RUNNING，suspend/resume/restart/destroy 只改部署状态、跳过 K8s 与备份归档操作（见 F-MGR-096）。

F-MGR-010 实例运行时详情

描述：部署状态、Pod 列表、日志、指标、概览、SSE 部署事件流；部署失败时附带机器码与结构化参数（见 F-MGR-097）。
组件：Manager Backend — AgentInstances API
API：
- GET .../deployment-status（error_message 按受众分级：管理侧详细原因、终端侧通俗文案）
- GET .../pods、GET .../pods/{pod_name}/logs
- GET .../metrics、GET .../overview
- GET .../deploy/events（SSE 流式部署进度）

F-MGR-011 实例 IM 渠道绑定

描述：为实例绑定企业微信/飞书/钉钉渠道，支持独立/共享 Profile。
组件：Manager Backend — AgentInstances API
API：GET/POST/PUT/DELETE /api/manager/agent-instances/{instance_id}/channels
实现：AgentInstanceChannel（channel_type, scope_type, config, enabled）；敏感信息脱敏显示。

F-MGR-012 实例 LiteLLM Key reprovision

描述：补实例 LiteLLM key 重新签发接口。
组件：Manager Backend — AgentInstances API
API：POST /api/manager/agent-instances/{instance_id}/litellm-key/reprovision

F-MGR-013 终端门户可访问实例

描述：为终端门户提供用户有权访问的实例列表。
组件：Manager Backend — AgentInstances API
API：GET /api/manager/agent-instances/accessible
实现：组用户仅见本组已上线实例；平台管理员跨组可见；返回简化信息（id, name, description, engine_type），并附该实例部署版本绑定的 MCP 服务名单（mcp_servers：alias + 显示名），门户据此把执行轨迹里的 MCP 工具名切分为「服务 · 工具」展示。

1.4 LiteLLM 模型网关集成

F-MGR-020 模型管理

描述：管理上游供应商（OpenAI/Anthropic/DeepSeek 等）部署与参数。
组件：Manager Backend — LiteLLM API
API：GET/POST/PUT/DELETE /api/manager/litellm/models
实现：模型别名供 Agent 表单选择，对应 model 参数；权限 litellm:model:manage（平台管理员）。

F-MGR-021 虚拟 Key 管理

描述：每实例一虚拟 Key，归属 UserGroup 对应 Team，支持预算/速率限制。
组件：Manager Backend — LiteLLM API
API：GET/POST/PUT/DELETE /api/manager/litellm/keys
实现：max_budget + budget_duration；rpm/tpm 限制；平台管理员不限范围，组管理员仅限本组；启用/禁用；通过 metadata.agent_id 或 key_alias 智能关联解析。

F-MGR-022 Team 同步

描述：UserGroup ↔ LiteLLM Team 1:1 映射同步。
组件：Manager Backend — LiteLLM API
API：GET /api/manager/litellm/teams、POST /api/manager/litellm/teams/sync
实现：创建 UserGroup 时自动 ensure Team；平台默认 Team ID settings.litellm_default_team_id。

F-MGR-023 用量计费统计

描述：按组/模型/时间维度的 token 用量与费用统计。
组件：Manager Backend — LiteLLM API
API：
- GET /api/manager/litellm/spend（明细）
- GET .../spend/summary（组维度汇总）
- GET .../spend/by-model（模型维度聚合）
- GET .../spend/trend（趋势，裁剪 end+1 的「明天」0 点）
实现：USD→CNY 汇率转换；组管理员仅见本组，平台管理员全平台。

1.5 IM 渠道接入

F-MGR-030 IM 用户绑定

描述：企业微信/飞书/钉钉用户 ID 映射到平台用户。
组件：Manager Backend — IM Bindings API
API：GET/POST/DELETE /api/manager/users/{user_id}/im-bindings
实现：ImUserBinding（channel_type, im_user_id, im_user_name）；平台管理员可管任意用户，组用户仅限共同组用户。

1.6 权限与隔离

F-MGR-040 用户组（租户内资源空间）

描述：UserGroup 是租户内的资源归属单元，所有业务资源按 group_id 归属；管理面已下线，组由账号中心组织投影维护，平台侧只读。租户根组 = 全租户共享空间（成员由租户成员关系派生、不单独落成员行），部门组 = 独立资源空间。
组件：Manager Backend — User Groups API（只读）
API：GET /api/manager/user-groups、GET /api/manager/user-groups/{id}、GET /api/manager/user-groups/{id}/members
实现：UserGroup（name, code, description, litellm_team_id, tenant_id, account_group_id）；自动生成机器码用于 MinIO 前缀与 Pod label；跨组不可见。

F-MGR-041 RBAC 角色权限

描述：基于角色的访问控制，细粒度权限（menu/api/button 三类）。
组件：Manager Backend — Roles API
API：GET/POST/PUT/DELETE /api/manager/roles
实现：Role-Permission 多对多；三类资源权限种子（definitions/instances/resource-pools）；平台管理员专属 litellm:model:manage 等。

F-MGR-042 用户身份索引

描述：users 表作为身份索引（RBAC / LiteLLM / 审计锚点），用户生命周期在账号中心统一管理；平台侧保留查询与角色绑定。
组件：Manager Backend — Users API（只读 + 角色绑定）
API：GET /api/manager/users、GET /api/manager/users/{id}、GET /api/manager/users/{id}/profiles、PUT /api/manager/users/{id}/roles
实现：JWT 双 Token（access 30min + refresh 7d）；密码 bcrypt（镜像，凭证自助在账号中心）。

F-MGR-043 管理员旁路

描述：平台管理员在管理台可绕过组隔离管理任意资源（网关侧不适用，见 F-GW-002）。
组件：Manager Backend — 核心权限逻辑
实现：is_platform_admin() 判断；group_ids=None 旁路组隔离；IM 绑定、资源池等支持跨组操作。网关数据面已去该旁路，跨组调试走代发凭证。

F-MGR-044 access_scope 访问控制

描述：实例访问范围 ALL/USER/USER_GROUP，与 RBAC 分离（终端用户不走 RBAC）。
组件：Manager Backend — 实例访问逻辑
实现：计费 Team 由 access_scope 派生（USER_GROUP→对应 Team）。

F-MGR-046 多租户（组织 → 租户投影）

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

F-MGR-047 租户分层门控（tier）

描述：按租户档位（free/standard/enterprise）下发功能开关集；未配置的功能默认放开，可按档位收紧。
组件：Manager Backend — /api/manager/features
实现：tier_capabilities 表（tier × feature 单行一键，缺行 = 放开）；get_tenant_tier 按用户所属租户并集取最高档（无租户归属兜底 standard，历史行为不变）；/features 出参含 tenant 段下发生效档位与开关集；后端端点按同一份配置门控。

F-MGR-048 登录即建（JIT）

描述：账号中心已有、本地尚未建立的用户首次登录管理台时自动完成建行与租户投影，无需预先导入。
组件：Manager Backend — Auth API
实现：本地未命中 → 账号中心反查（账号名 / 已验证邮箱手机）→ 验签通过后建 users 行（id = 账号中心用户 id）并阻塞式完成该用户的租户/角色投影；账号中心不可达或投影失败则拒绝登录（不建裸行）。

描述：部署开关（UA_DEMO_ENABLED，默认关）控制的共享演示账号免密登录，管理台与终端门户各自独立：管理台登录页「一键演示」→ POST /api/manager/auth/demo-login（演示账号落 users 表、绑定「平台管理员」角色、签发 aud=admin token）；终端门户「一键演示」→ POST /api/manager/auth/enduser/demo-login（演示账号落 end_users 表、无角色、签发 aud=enduser token）。两端演示账号共用同一演示用户组（预置 demo 智能体定义两侧可见，组隔离自动生效）；is_demo 持久化标记区分同名真实用户（非演示用户 fail-closed 503），每次登录自愈修复（激活/解锁/组成员，管理侧含角色归位）。关闭时端点 404 + 按钮隐藏。
组件：Manager Backend — Auth API + seed_demo_agents demo 组优先
API：POST /api/manager/auth/demo-login（管理台）、POST /api/manager/auth/enduser/demo-login（终端门户）
实现：app/api/auth.py demo_login/enduser_demo_login/_ensure_demo_user/_ensure_demo_group；配置 pkg/common/config.py（UA_DEMO_ENABLED/DEMO_USERNAME/DEMO_GROUP_NAME）；flag 经 /api/manager/auth/verification-channels（按钮显隐）与 /api/manager/features 暴露；工作区数据预置/重置见 scripts/seed-demo-workspace.py、scripts/reset-demo-workspace.py（F-SCR-006）。

1.7 监控仪表盘

F-MGR-050 系统仪表盘

描述：平台整体运行状态与关键指标。
组件：Manager Backend — Dashboard API
API：
- GET /api/manager/dashboard/activities（最近活动）
- GET .../group（组管理员概览）
- GET .../health（系统健康检查）
- GET .../resources（资源消耗）
- GET .../instance-status（实例状态分布）
- GET .../billing（计费概览）
- GET .../top-agents（热门 Agent 排行）

F-MGR-051 指标采样服务

描述：定期采集 Pod 资源用量，时序存储。
组件：Manager Backend — Metrics Service
实现：ResourceMetricSample（cpu_m, memory_mi, 按分钟采样）；保留 7 天；按 instance_id 或 resource_pool_id 聚合；时间范围 1h/6h/24h/7d。

1.8 备份迁移与初始化

F-MGR-060 三层模型数据迁移脚本

描述：旧单体模型 → 三层模型迁移。
组件：scripts/ — migrate_to_v3.py、migrate_to_v3_data.py
实现：Agent→Definition+Version+Instance、EngineInstance→ResourcePool；分阶段：建表 → 迁数据 → 列重命名 + FK 改指 → DROP 旧版老表。

F-MGR-061 种子数据初始化

描述：启动时自动创建默认角色/权限/用户组/管理员。
组件：Manager Backend — Seed Service
实现：幂等；三类资源权限种子；修复 startup seed greenlet bug；默认管理员 admin@veyraos.io / admin123。

1.9 系统集成

F-MGR-070 Controller 代理客户端

描述：统一代理 controller 的 deploy/status/pods 等接口。
组件：Manager Backend — Controller Client
实现：统一 ControllerError；SSE 部署事件透传。

F-MGR-071 数据库架构（三层模型）

描述：定义/资源/实例三层分离的数据库设计。
组件：Manager Backend — 数据模型
实现：AgentDefinition / AgentVersion / ResourcePool / AgentInstance / AgentInstanceChannel / AgentDeployment / AgentProfile / ResourceMetricSample；支持组隔离与权限控制。

1.10 知识库（RAG）

F-MGR-080 知识库 CRUD

描述：知识库全生命周期管理（用户组隔离的租户化资源）。
组件：Manager Backend — Knowledge API
API：GET/POST/PUT/DELETE /api/manager/knowledge-bases（支持 search 模糊搜索 + sort 排序 updated/docs/name）、GET .../stats（列表页统计卡：库数/文档数/处理中/失败）
实现：UA 表元数据 + RAG 引擎 workspace 双写；向量模型/分块方式创建后不可改；重排序模型、知识图谱开关与建图模型、图谱语言（graph_language，zh/en → LightRAG addon_params language=Chinese/English，仅影响后续入库）可编辑（编辑后引擎实例按新配置重建）；列表行合并引擎侧 processing/failed 计数供健康状态条展示。

F-MGR-081 文档管理与异步解析

描述：文档上传/粘贴文本入库/解析/删除/分块预览，后台队列解析（真异步），服务端分页与状态过滤。
组件：Manager Backend — Knowledge Documents API + 解析 Worker
API：POST .../documents/query（服务端分页/过滤桶/排序）、POST .../documents（上传即自动入队）、POST .../documents/text（粘贴文本入库）、POST .../documents/reprocess-failed（失败一键重试）、POST .../documents/{id}/parse（202 入队）、POST .../documents/batch-parse、POST .../documents/batch-delete、GET .../documents/{id}/chunks、GET .../pipeline（管线状态：busy/批次进度/日志）、POST .../pipeline/cancel
实现：原文托管 MinIO（跨副本共享）；worker 轮询 queued 文档行级抢占（多副本安全）；状态机 uploaded/queued/parsing/parsed/error + 粗粒度进度 + 阶段（queued/parsing/analyzing/processing）+ 失败机器码（unsupported_file/parse_failed/model_unavailable，前端 i18n 映射）；列表合并引擎视图与 UA 队列表（排队与入队前失败文档不丢）。

F-MGR-082 分块策略

描述：4 种分块策略 + 每策略差异化参数。
实现：标准（定长）/ 智能（递归边界）/ 语义（向量相似度）/ 段落（段落语义合并）；标准/智能/段落支持分块长度与重叠，语义仅长度，段落支持去除引用段落；解析时按策略注入引擎。

F-MGR-083 知识图谱（KB 级开关）

描述：可选的实体-关系抽取建图与图增强检索 + 只读可视化工作台。
实现：KB 级 kg_enabled + kg_model（建图模型可选）+ graph_language（实体关系提取语言）；开启后解析提取实体关系入 Neo4j、检索默认 hybrid 图增强；图谱 API GET .../graph（全局 top N）、GET .../graph/labels（起点候选，按度数倒序）、GET .../graph/subgraph（起点+深度 1–5+节点上限，变长路径深度字面量注入并钳制防 Cypher 注入）、GET .../graph/entity（属性+邻居）；管理台 ECharts 力导/环形布局 + 属性面板（邻居跳转 / 以实体为起点扩展）。

F-MGR-084 检索与重排序

描述：检索测试 + 流式问答 + 重排序 + 相似度分数 + 来源溯源。
API：POST .../retrieval（top_k/相似度阈值/检索模式/重排序开关，非流式）、POST .../query/stream（单库流式问答，NDJSON 帧：status/references/data/chunk×N/done/error）、POST .../query/multi/stream（多库合并检索流式问答）
实现：请求级相似度阈值过滤；配置重排序模型时经 LiteLLM rerank 真实重排并返回分数；流式走 LightRAG aquery_llm（llm func stream=True 返回 AsyncIterator 逐 chunk 透传），引用帧带 file_path 映射 UA 文档（track_id 目录精确命中 / 文件名回退）支持前端「定位」跳转；多库模式合并各库召回后单次生成；响应带 X-Accel-Buffering: no 防 nginx 缓冲。

F-MGR-084a 治理运维（导出 / 缓存 / 运行状态）

描述：知识库对象级治理操作。
API：GET .../export?format=csv|md|txt（LightRAG aexport_data 写临时文件后读回下载）、POST .../cache/clear（清 LLM 响应缓存）、GET .../runtime（模型四角色 + 存储探活 postgres/neo4j/对象存储 + 队列概况）

F-MGR-085 内部检索（智能体调用）

描述：智能体按绑定知识库检索（MCP 工具 retrieve），检索 MCP 由 manager 内嵌托管。
API：POST /api/manager/internal/knowledge/retrieve（X-Internal-Token，未配置即拒绝）
实现：Manager 内嵌 FastMCP streamable-http 端点 /mcp/kb_retrieval；主路径 kb_ids（由智能体↔KB 绑定关系渲染进实例的 X-KB-Ids header——文件通道写引擎 config.yaml，env 契约通道随中立绑定契约下发——经 LiteLLM extra_headers 转发到 kb_retrieval 的 retrieve 工具，多库合并检索）；kb_alias 按名为兼容回退；运行时通过 X-KB-Options JSON header 透传智能体级检索配置（TopK / 相似度阈值 / 检索模式 / 重排序开关），header 优先于工具入参；结果含来源文档与分数；终端门户聊天工具卡片渲染「参考来源」引用（文档名 + 相似度）。

F-MGR-085a 智能体级检索配置

描述：在智能体定义层配置知识库检索参数，绑定知识库后自动生效，未绑定时可预存。
API：GET|PUT /api/manager/agent-definitions/{definition_id}/retrieval-config
实现：AgentDefinition.retrieval_config JSON 字段存显式设置项（null 表示系统默认）；GET 返回 config + effective（合并系统默认值：TopK=5、相似度阈值=0.2、模式自动、重排序=true）；修改后对已部署实例 apply，config.yaml 渲染 X-KB-Options 仅注入 kb_retrieval 条目。

F-MGR-086 引擎健康

描述：RAG 存储分项探活。
API：GET /api/manager/rag/health（平台管理员）
实现：返回 checks: {postgres, neo4j} 分项可达性。

F-MGR-087 绑定智能体管理

描述：展示/管理绑定某知识库的智能体。
API：GET /api/manager/knowledge-bases/{id}/agents；DELETE .../agents/{definition_id}（解绑）；GET|PUT /api/manager/agent-definitions/{id}/knowledge-bases（智能体侧绑定集合）
实现：agent_kb_bindings 显式绑定表（definition 级 N:M，不进版本快照）；绑定变化对已部署实例 apply（config.yaml 重渲染 + 滚动重启）；绑定关系同时是系统内置 kb_retrieval 挂载态的唯一事实源（渲染时展开，不落 mcp_config）；删 KB 被绑定时 409 拦截（force 强制删）；智能体检索范围由绑定注入（见 F-MGR-085），提示词不写 KB 名、改名不断链。

F-MGR-088 附件内容识别（图片 / PDF）

描述：智能体读取用户上传到会话工作区的附件内容——图片识别票面/单据要素（发票、报销单、表单等），PDF 提取全文文本（合同评审等）。
API：GET /api/manager/agent-instances/{id}/files/download?path=&profile=（内部令牌鉴权；profile 参数仅内部调用生效，按 profile 名精确解析当前会话工作区，JWT 用户传该参数一律忽略防越权）
实现：demo-mcp 文件工具 recognize_image / extract_pdf_text；调用方定位沿用 X-KB-Ids 的 header 注入模式（manager 渲染 per-profile config.yaml 时注入 X-Agent-ID / X-Profile-Name，经 LiteLLM extra_headers 转发）；图片经降采样压缩（≤2048px JPEG）后调 LiteLLM 视觉模型组（需在模型管理注册多模态模型）提取结构化要素，识别不清的字段返回 null 由智能体向用户复核；PDF 分页提取 + 超长截断分段，扫描件（无文本层）如实说明并建议改用图片识别。

F-MGR-089 平台级文件引用规范注入

描述：智能体在工作区产出文件（图表、报告等）后，回复里自动按 Markdown 相对路径引用（图片 ![描述](output/x.png)、非图片 [文件名](相对路径)），保证终端门户/IM 通道可解析展示；对所有智能体无条件生效，且不在人设编辑器中暴露。
实现：pkg/common/persona_rules.py::compose_soul 是唯一组装事实源，两条人设通道共用同一份文本。写文件通道（Hermes 系）——persona 同步 / per-user profile 首建 seed 两条写 SOUL.md 的路径在写文件瞬间追加规范块；请求体通道（Claude Code / DeepSeek）——Gateway 每请求组装同一份文本注入，规范块随人设一起送达。DB persona_config 全程不变；存量 Pod 由启动 backfill 重放收敛。

1.11 Dify 外接引擎（External-Only）

外接是 Dify 的唯一模式——托管（平台侧部署 Dify）相关的枚举、校验、界面与原型页已全部移除，DifyEngineMode 只剩 EXTERNAL。平台对接用户自管的 Dify 实例（自托管或 Dify Cloud），不部署 Dify 的任何组件；绑定对象是外部平台上的一个应用。管理面适配层收敛在 app/core/dify_console_client.py（Console API），运行时适配在 Gateway app/adapter/dify.py（Service API）。

F-MGR-090 Dify 引擎配置（外接）

描述：登记用户自管 Dify 平台的连接信息与可选的管理员凭据，供应用列表、绑定与用量反查复用；全局单条。
组件：Manager Backend — EngineConfigs API + app/core/dify_console_client.py
API：GET/POST /api/manager/engine-configs、POST .../{config_id}/test-connection、GET .../{config_id}/dify-apps、POST .../{config_id}/dify-apps/{app_id}/select、POST .../{config_id}/dify-apps/import
实现：engine_configs 行存 base_url（必填）+ 管理员邮箱/密码（可选）+ observability_managed 开关（默认开，开启则用量采集走平台全局 Langfuse 集群 UA_LANGFUSE_*）；密码与缓存 token 一律 Fernet 加密落库，响应只回 *_configured 标记不回明文。配了管理员 → Console API 登录并列应用（过滤 completion 模式，见 F-MGR-091 映射）；未配管理员 → test-connection 以 Service API /v1/info 探活。全局唯一（group_id IS NULL），mode 枚举只有 EXTERNAL。dify-apps/import 批量导入：按勾选的 app 逐个调生命周期编排（建同名定义→绑定→发布，重名自动加 -N 后缀），同组已绑定同 app_id 的幂等跳过，单应用失败隔离不阻断其余。

F-MGR-091 外部平台健康巡检

描述：后台按周期探活每个外接引擎配置的平台地址，把最近一次结果写回配置行，管理台展示「平台状态」；失败只降级展示，不阻断配置读写。
组件：Manager Backend — app/services/engine_health_service.py + worker/background.py 的 _engine_health_loop
实现：migration 049_engine_configs_health_check.sql 给 engine_configs 加 last_check_at / last_check_status（ok/error）/ last_check_error（用户可读文案，成功即清空）；每 5 分钟对 base_url 非空的配置打 GET /v1/info，超时 10s；200/401/403 均视为可达（外接平台鉴权失败不等于平台不可达），连接错误 / 5xx / 404 记为失败。单条失败不影响同轮其余条目。

F-MGR-092 定义级应用绑定

描述：把智能体定义绑定到外部 Dify 平台上的一个应用，绑一次该定义全部实例（调试 + 生产）生效；未绑定不允许发布。
组件：Manager Backend — Agent Lifecycle API
API：GET/PUT /api/manager/agents/{definition_id}/binding、POST /api/manager/agent-instances/verify-dify-service-api
实现：agent_instances.dify_config（JSON，实例列）存 {base_url, app_id, app_name, app_type, app_api_key, source}；app_type 由应用模式映射（chat→chat、agent-chat→agent、advanced-chat→chatflow、workflow→workflow；chatflow 为对话流——对话型 API + 节点画布）。两态交互契约——已配管理员：下拉选应用，select 取/建 app_api_key 并自动回填；未配管理员：手填 base_url + app_api_key + app_type，verify-dify-service-api 调 /v1/info 验证密钥。读取视图 app_api_key 掩码；校验下沉服务层 validate_external_binding，实例 API 与发布链路共用；发布前置拦截未绑定实例。

F-MGR-093 绑定应用密钥轮换

描述：在外部平台新建一把应用密钥，该定义全部实例同步换用，无需逐实例操作。
组件：Manager Backend — Agent Lifecycle API
API：POST /api/manager/agents/{definition_id}/binding/rotate-key
实现：复用应用选择期的建密钥逻辑（Console POST /console/api/apps/{id}/api-keys），定义级语义——一次轮换写全部实例的 dify_config；受 Dify 侧「每应用最多 10 把密钥」约束，达上限返回用户可读错误而非静默失败。

F-MGR-094 模型通道可视化

描述：展示绑定应用的模型究竟经本平台网关还是直连外部模型服务（后者平台无法完整归集用量），无法判定时说明原因而不给结论。
组件：Manager Backend — Agent Lifecycle API + dify_console_client.get_provider_credentials
API：GET /api/manager/agents/{definition_id}/binding/model-channel
实现：经 Console API 读应用模型配置与供应商凭据，按供应商 api_base 与平台自身 host 比对判定 through_platform；缺 api_base、平台 host 未知、未配管理员账号、工作流型无单一模型等情况一律 available=false 或 through_platform=null + 用户可读原因。

F-MGR-095 编排摘要（变量 / 数据集 / 工具）

描述：只读展示绑定应用编排中引用的变量、数据集与工具，便于在平台内核对智能体依赖，环境变量值一律掩码。
组件：Manager Backend — Agent Lifecycle API + Dify Console API
API：GET /api/manager/agents/{definition_id}/binding/app-summary
实现：经 Console GET /console/api/apps/{id}/export 导出编排 DSL 后本地解析，再逐个 GET /console/api/datasets/{id} 补齐数据集名称/文档数/索引状态；单个数据集读取失败不影响其余条目。未配管理员账号或读取失败 → available=false + 原因，降级为引导态，不阻断页面；环境变量值掩码展示（可能是密钥）。

F-MGR-096 外接实例发布与运行时（无 Pod）

描述：外接实例没有 Pod、不占资源池，发布即上线；运行时的暂停/恢复/重启/销毁只改平台侧状态，不动外部平台。
组件：Manager Backend — Agent Lifecycle API + worker/lifecycle.py
API：POST /api/manager/agents/{definition_id}/publish、POST .../launch、POST /api/manager/agent-instances/{id}/{deploy|suspend|resume|restart|destroy}
实现：create_instance 对带 base_url 的外接引擎跳过资源池校验（resource_pool_id 置空）；deploy 内联建/更新 AgentDeployment（status=RUNNING、engine_url=base_url、pod_name=NULL、prepared_config.mode="external"），不发 Controller 调用；发布经 publish_and_sync 逐实例内联上线（未绑定进 error）。suspend/resume/restart/destroy 走 is_external_dify_deployment 判定后跳过 K8s 与备份/归档操作；空闲回收调度器不自动休眠外接实例，状态巡检也无 Pod 可探、直接刷新 last_active_at。ENGINE_RUNTIMES["DIFY"] 的 image/port（5001）仅供引擎目录展示与契约文档，无 Pod 消费者；缺 base_url 的外接实例 fail-fast 记 FAILED（不让脏数据跌落 K8s 路径起幽灵 Pod）。

F-MGR-097 部署失败归因与解决方案提示

描述：部署失败时给出失败原因 + 解决方案 + 重试/日志入口，取代原先「一句英文 + 中英混杂异常原文」；终端门户只看到通俗文案，不出现镜像/Pod/资源配额等底层词汇。
组件：Manager Backend — services/deploy_failure.py（纯函数归因）+ worker/k8s_manager.py（诊断采集）+ worker/lifecycle.py（落库）+ AgentInstances API（受众裁剪）
API：GET /api/manager/agent-instances/{id}/deployment-status（响应增 error_code / error_detail，按受众裁剪）
实现：诊断取自 get_pod_status 同一次查询里的 Pod 状态字段（不读 K8s Events，零额外 API 调用），按「terminating 不归因 → 容器态（lastState.terminated 优先）→ PodScheduled condition → Pod phase → 阶段兜底」定序归因为机器码 <域>_<原因>（7 个故障域、25 个码），落 agent_deployments.error_code + error_detail（白名单结构化参数，migration 064）。调度条件指向不存在的 PVC（销毁与部署挨得太近、卷被外部删除）归 STORAGE_VOLUME_MISSING，文案与解决方案都不套用「节点不够」。K8s 原文只用于关键词匹配并进服务端日志，不入库、不下发。wait_pod_ready_with_reason 命中不可自愈原因（镜像拉不走、卷挂不上、数据卷不存在）连续 15 次即提前返回，把原本 120s 的干等压到 ~15s；「卷在供给中」仍继续等。管理台按 deployError.<CODE> 走 i18n（中英双语，域级 __fallback 兜底），终端侧 API 层把 error_code/error_detail 置空、error_message 替换为通俗文案；tests/test_deploy_failure_i18n_parity.py 钉住「后端文案表 ↔ 前端两份语言包」不漂移。

二、Controller Backend（已并入 services/manager/app/worker）

融合说明：原 Repo2 独立 services/controller 服务（:8001）已并入 manager（services/manager/app/worker/，worker_router 在 /api/controller/* 字面路径提供服务）。下文 F-CTL-* 特性的实现均位于 services/manager/app/worker/router.py + k8s_manager.py + client.py + background.py；原 services/controller/ 死代码目录已删除。

2.1 引擎 Pod 生命周期

F-CTL-001 Agent Deploy

描述：创建/恢复引擎 Pod，支持 SUSPENDED/FAILED 状态恢复与 scope 维度部署。
组件：Controller Backend
API：POST /api/controller/agents/{agent_id}/deploy
实现：创建 K8s Deployment + Service + PVC；自动扩容（现有 Pod 全满时新建）；preferred_node 节点亲和性优化镜像缓存。

F-CTL-002 Agent Status

描述：查询引擎部署状态，含 K8s Pod 实际存活状态纠错。
API：GET /api/controller/agents/{agent_id}/status
实现：按需 reconciliation；自动修复陈旧状态（FAILED/PENDING/SUSPENDED→RUNNING）。

F-CTL-003 SUSPEND 空闲存档

描述：30 分钟空闲自动存档到 MinIO，scale=0 释放资源。
API：POST /api/controller/agents/{agent_id}/suspend
实现：exec tar → MinIO → scale=0 → SUSPENDED；PVC 跳过机制 pvc_skip_backup_on_suspend；UserGroup 隔离路径 groups/{group_code}/backups/；不设定期轮询备份（大规模不可行）。

F-CTL-004 RESUME 恢复

描述：SUSPENDED → RUNNING，从 MinIO 恢复数据。
API：POST /api/controller/agents/{agent_id}/resume
实现：Deployment scale 0→1；exec untar 恢复 backup；清理 stale gateway.lock 避免启动冲突。

F-CTL-005 DESTROY 归档销毁

描述：确认 SUSPEND 存档 → 复制到 archives → 清理 K8s 资源。
API：POST /api/controller/agents/{agent_id}/destroy
实现：archive_backup → delete_all_k8s → ARCHIVED；PVC 回收控制 pvc_reclaim_on_destroy；原子清理 AgentProfile 记录。管理台删除实例（DELETE /api/manager/agent-instances/{id}）在运行态未回收时先自动走本销毁流程再删行（已 ARCHIVED 不重复销毁；归档守卫拒绝返回 409 可重试，force=true 跳过归档强清、实例数据不保留），杜绝只删 DB 行把 Deployment/SVC/PVC 泄成孤儿。

F-CTL-006 RESTART 滚动重启

描述：配置/技能/人设变更生效，不改变副本数。
API：POST /api/controller/agents/{agent_id}/restart
实现：修改 Deployment template annotations 触发滚动更新。

F-CTL-007 部署进度 SSE

描述：SSE 流式返回部署进度。
API：GET /api/controller/agents/{agent_id}/deploy/events
实现：内存事件存储 _deploy_events；流式 JSON 事件推送。

2.2 数据持久化与存储

F-CTL-010 PVC 持久化

描述：引擎数据 PVC 持久化，确保不丢失。
实现：PVC 命名 engine-data-{short_id[-scope_hash]}；挂载 /opt/data（多 profile 布局）；ReadWriteOnce；StorageClass 可配置；实时写零开销。

F-CTL-011 MinIO 存档管理

描述：UserGroup 隔离的 MinIO 存档读写。
实现：路径前缀 groups/{group_code}/；备份 backups/{agent_id}/latest.tar.gz；归档 archives/{agent_id}/{timestamp}.tar.gz；服务端复制优化。

F-CTL-012 数据备份/恢复（WebSocket exec）

描述：通过 WebSocket 二进制通道备份/恢复。
实现：exec_tar_data（tar→WebSocket→MinIO）；exec_untar_data（WebSocket→untar→Pod）；临时文件机制避免 stderr 混流。

2.3 多 Profile 隔离架构

F-CTL-020 Profile 生命周期

描述：Hermes Profile 创建/删除/端口分配。
API：POST /api/controller/profiles、POST .../profiles/ensure、DELETE .../profiles/{profile_id}
实现：hermes profile create --clone --clone-from base；端口分配 internal_port_map JSON；update_nginx_config 动态生成并 reload。

F-CTL-021 Profile 修复（_heal_profile_runtime_config）

描述：修复 PVC 持久化的 stale profile 配置（绕过 LiteLLM 直连问题）。
实现：修复 provider auto→openai-api；清理 DEEPSEEK_API_KEY，注入 OPENAI_*；对齐当前 LiteLLM 配置。

F-CTL-022 Pod 共享调度（fan-out）

描述：多 Agent 共享同一 Pod，按负载 fan-out 端口分配。
实现：_select_pod_by_load 按负载选最空闲 Pod；_ensure_pod_exists 自动扩容；scope 维度隔离（scope_type + scope_target_id）；跨 agent 共享 Pod 走 deployment.pod_name。

F-CTL-023 Profile 目录结构

描述：/opt/data/profiles/{name}/ 多 profile 布局。
实现：base 目录 entrypoint 创建；新 profile 自动继承 base 配置。

F-CTL-024 Pod 启动注册

描述：Pod 启动后主动上报 profile 列表。
API：POST /api/controller/profiles/register
实现：识别并删除 stale DB 记录；Engine entrypoint-v2.sh 调用。

2.4 K8s 交互

F-CTL-030 K8s 资源全生命周期

描述：Deployment/Service/PVC 创建/删除/查询。
实现：资源标签 agent.veyraos/agent-id；组隔离标签 agent.veyraos/group-code；节点亲和性调度。

F-CTL-031 Pod 状态监控

描述：实时 Pod 状态查询与等待。
实现：get_pod_status / wait_pod_ready / wait_engine_ready（等待引擎 HTTP 就绪）。

F-CTL-032 Pod Exec 权限（WebSocket）

描述：二进制 WebSocket exec 通道。
实现：_ws_exec_sync 同步执行；支持二进制传输；RBAC 需 get+create 两个 verb（Python SDK 限制，kubectl 不受限）。

F-CTL-033 Metrics 采样

描述：周期性采样 CPU/内存用量。
实现：MetricSampler 类，每 60s 采样；写入 resource_metric_samples；7 天保留；集成 metrics-server。

2.5 配置与人设/技能同步

F-CTL-040 引擎配置同步

描述：配置同步到 MinIO 与运行中 Pod。
API：POST .../config/sync、POST .../config/apply
实现：MinIO 路径 groups/{group_code}/engine-config/；统一生成 config.yaml 避免 skills.disabled 被覆盖。

F-CTL-041 三层配置读取

描述：按 instance_id 读取三层配置。
实现：_load_instance_config JOIN agent_instances + agent_versions + agent_definitions；per-instance litellm_config 覆盖版本快照。

F-CTL-042 人设同步（SOUL.md fan-out）

描述：人设文件 fan-out 到所有引擎 Pod。
API：POST /api/controller/agents/{agent_id}/persona/sync
实现：自适应新旧目录；Hermes 按会话读取，写文件即生效。

F-CTL-043 技能安装/卸载/列表

描述：技能文件管理，热生效不重启。
API：POST .../skills/install、DELETE .../skills/{skill_name}、POST .../skills/config/sync、GET .../skills/list
实现：zip→tar.gz 转换剥离顶层目录；路径安全过滤；重生成 config.yaml 更新 skills.disabled；递归查找 **/SKILL.md 解析 YAML frontmatter；统一扫描脚本 /tmp/ua_scan_skills.py；技能按 agent 隔离 + 软链接。

2.6 配额与后台调度

F-CTL-050 资源配额控制

描述：CPU/内存资源限制与配额。
实现：引擎默认资源规格随引擎标准定义（pkg/common/config.py ENGINE_RUNTIMES[].resources，GET /engines 返回 default_resources）；实例部署时可经 runtime_config.pod_resources 覆盖，实际生效 requests 落 agent_deployments.pod_cpu_request / pod_memory_request；池级配额 pool_cpu_quota / pool_memory_quota 按各行实际值求和；K8s ResourceRequirements；max_sessions_per_pod 控制单 Pod 并发。

F-CTL-051 空闲回收调度器（RecycleScheduler）

描述：定时检测空闲引擎并 SUSPEND/DESTROY。
实现：每 5min 检查 RUNNING，30min 空闲 SUSPEND；每小时检查 SUSPENDED，24h 空闲 DESTROY；回调模式解耦。

F-CTL-052 状态巡检更新

描述：更新 last_active_at，修正异常状态。
实现：每 60s 执行；区分正常 SUSPEND 与外部误删；Profile 一致性检查。

2.7 其他

F-CTL-060 模型权限查询

描述：按 Agent 虚拟 Key 返回可用模型。
API：GET /api/controller/agents/{agent_id}/models
实现：调用 LiteLLM /v1/models，返回 agent 有权限的模型别名。

F-CTL-061 聊天仪表盘配置端点

描述：前端探活配置。
API：GET /api/controller/chat/dashboard/config、.../status、GET /api/controller/chat/settings、GET /api/controller/chat/models

F-CTL-062 服务解耦设计

描述：原 Controller 与 Manager/Gateway 独立部署；融合后 Controller 已并入 manager（services/manager/app/worker/，进程内直调 facade 替代 HTTP 封装，见 worker/__init__.py）。无外键约束的同表不同约束模型、Controller 只写不读关联关系、K8s Service DNS 通信等设计仍沿用。

三、Gateway Backend（services/gateway）

3.1 反向代理与路由

F-GW-001 DNS-based Agent 智能路由

描述：通过 X-Agent-ID 头 + DNS 命名规范构造 upstream URL，不查询 Controller。
组件：Gateway Backend — Proxy 模块
实现：URL engine-hermes-{agent_id[:8]}-{scope_hash[:6]}.{namespace}.svc.cluster.local:8642；build_engine_url() 传统 DNS 路由；resolve_engine_url() 支持 scope_hash pod_name 路由；Pod 重启检测缓存失效。

F-GW-002 Profile 感知路由

描述：基于用户身份与 Agent 配置动态解析目标 Profile。
实现：Profile 名 {short_agent}-{scope_hash[:6]}-{short_user}；INDEPENDENT/SHARED 两种类型；60s 成功缓存 + 10s 负缓存；IM 用户 ID 映射（im_user_bindings）；组隔离统一按身份体系校验（管理侧含租户根组派生），无平台管理员全局旁路；跨组调试由 manager 签发的短期代发凭证（显式组白名单）放行。

F-GW-003 安全头部过滤

描述：过滤 Origin/Referer 头部（Hermes 收到 Origin 返回 403）。
实现：忽略客户端 X-Hermes-Profile 头（服务端计算）；过滤 host/origin/referer/x-hermes-profile；注入 X-Hermes-Profile 与 authorization: Bearer {api_server_key}。

F-GW-004 Profile 路由 6 层问题链路修复

描述：经多轮迭代的 Profile 路由系统。
实现：①避免 Controller 查询直 DNS ②统一 Profile 名构造 ③缓存 Pod 重启检测 ④权限闸门前置无副作用 ⑤IM 用户 ID 统一映射 ⑥降级策略完善。

3.2 SSE 流式代理

F-GW-010 SSE 流式响应代理

描述：服务器发送事件流式传输，实时 AI 响应。
实现：proxy_buffering off；Content-Type text/event-stream 检测；_stream() 流式转发；OpenAI 兼容 SSE 解析；nginx 不得缓冲或修改 SSE 内容；Connection upgrade 会干扰 SSE 需避免。

F-GW-011 企业微信 chunk-flush

描述：针对 2048 字节限制智能分段传输。
实现：_split_by_bytes() UTF-8 字节级分段；优先换行处切分避免切断多字节字符；满 2048 字节立即 flush；_stream_sent 字符偏移跟踪。

F-GW-012 飞书流式编辑

描述：PATCH 卡片消息实时编辑更新。
实现：send_initial_response() 独立回复卡；update_streaming_card() 增量更新；双元素策略修复布局残留；启动状态卡 + 回复卡分离。

3.3 IM 渠道分发

F-GW-020 统一消息分发器

描述：队列化处理 IM 消息，支持去重、生命周期管理。
实现：消息去重 60s TTL + (agent_id, platform_message_id)；Per-agent 队列避免乱序；Session 30min TTL + 确定性 session ID；引擎重启清理 session 缓存。

F-GW-021 权限闸门（AccessDeniedError）

描述：消息转发前权限验证，不可吞 AccessDeniedError 当降级兜底（越权）。
实现：check_access() 轻量无副作用验证；类型 NotBoundError/AccessDeniedError/ProfileNotFoundError；IM 用户 ID 映射 + 组隔离；拒绝时返回明确 IM 提示。

F-GW-022 飞书适配器

描述：飞书回调协议完整支持。
实现：AES-256-CBC 加密消息；交互式卡片；PATCH API 实时编辑；Markdown 格式；HMAC-SHA256 签名验证。

F-GW-023 企业微信适配器

描述：企业微信回调协议与加密。
实现：SHA1 签名验证；AES-256-CBC 解密；2048 字节分段；Markdown 消息。

F-GW-024 钉钉适配器

描述：钉钉回调协议。
实现：URL 验证 checkUrl；HMAC-SHA256 签名；OAuth 2.0；无消息编辑支持。

3.4 引擎生命周期与 UX

F-GW-030 健康检查与自动恢复

描述：自动检测引擎状态，支持冷启动恢复。
实现：check_engine_health() HTTP GET /health；trigger_deploy() 30s 超时；ensure_engine_ready() 最长 300s 轮询；热/冷启动识别。

F-GW-031 启动进度 UX

描述：智能体启动时发送状态提示。
实现：冷启动发 "🤖 正在启动..." 占位；就绪后更新 "✅ 引擎已就绪"；飞书独立卡片 + 状态更新；企业微信仅发最终响应。

F-GW-032 重试与降级

描述：消息转发失败重试与降级。
实现：指数退避 3 次 [1s,2s,4s]；基础设施异常降级 legacy 路由；Profile 创建失败降级直连；用户友好错误提示。

3.5 API 代理与会话

F-GW-040 模型 API 代理

描述：OpenAI 兼容模型 API 代理到 Hermes 引擎。
实现：/v1/chat/completions；模型配置从 agent_instances.litellm_config 读取；支持 stream 参数；X-Hermes-Session-Id 头转发。

F-GW-041 会话上下文管理

描述：跨消息会话状态，连续对话体验。
实现：确定性 session ID SHA256(agent_id+channel_type+chat_id)[:24]；POST /api/sessions（含 origin 元数据）；30min TTL + 引擎重启清理；409 视为正常重复。

3.6 配置与监控

F-GW-050 数据库配置缓存

描述：DB 配置内存缓存减少查询。
实现：60s TTL；_invalidate_channel_config_cache() 主动失效；渠道配置读 agent_instance_channels；Agent 模型配置读 agent_instances.litellm_config。

F-GW-051 安全配置

描述：JWT 认证与 CORS。
实现：JWT HS256；生产环境密钥强制验证；CORS 白名单；API Server 密钥认证。

F-GW-052 健康检查端点

描述：/health 端点服务状态监控。
实现：返回状态 + 版本；异步启动验证 DB 连接；日志输出 stderr（k8s 收集）毫秒级时间戳。

3.7 Dify 外接引擎适配（External-Only）

外接实例不经 Pod、不经 Profile 路由：Gateway 从 DB 解析 dify_config 得到外部平台地址与应用密钥，直连用户自管 Dify 的 Service API，把 Dify 事件（message / node_* / agent_thought / workflow_paused 等）转换成平台统一的 VES 帧。适配层全部收在 app/adapter/dify.py + app/proxy.py，不侵入 Dify 源码。

F-GW-060 外接引擎路由解析与缓存失效

描述：按 X-Agent-ID 解析外接实例的直连地址与应用类型，不查 Controller、不构造 Pod DNS。
实现：_resolve_dify_target 直查 DB（agent_deployments.engine_url + agent_instances.dify_config，空则回退 agent_versions.model_config.dify）取 engine_url / app_type / app_api_key；模块级缓存 TTL 300s，绑定/发布变更时由 manager 通知主动失效（TTL 仅兜底），502/503 也触发失效以便下条消息重新解析。实例密钥覆盖客户端 Authorization（app_api_key 不下发终端）。非集群 DNS 的 engine_url 直接使用；解析失败回退 adapter DNS（可用性优先）。

F-GW-061 停止语义

描述：「停止生成」真正终止外部平台上正在执行的 Dify 任务，而不是只断网关侧连接。
API：POST /api/gateway/v1/runs/{run_id}/cancel
实现：DifyAdapter.get_run_stop_url 按应用类型派生停止路径——chat/agent → POST /v1/chat-messages/{task_id}/stop，workflow → POST /v1/workflows/tasks/{task_id}/stop，body 必须带与发起轮一致的 user；task_id 由适配器在流式事件中嗅探（顶层 task_id）落 run 条目；流尚未产出 task_id（极早取消）时返回 None，引擎侧尚无任务可停。

F-GW-062 流式会话回传

描述：把外部平台分配的会话标识经流式响应回传门户，实现多轮上下文继承。
实现：入站 X-Session-Id → 私有头 x-dify-conversation-id → 请求体 conversation_id 跨轮继承（local- 前缀的本地占位 id 不传）；出站首帧起在流式响应顶层回传 conversation_id，门户落本地并以 X-Session-Id 跨轮继承。workflow 型应用不产生 conversation_id，需客户端显式带 X-Session-Id。
用户锚点（E3）：请求体 user 与 GET/DELETE 请求的 query user 统一注入为 veyra-{end_user_id}（登录态覆盖客户端传值防伪冒；无登录态退化实例级匿名锚点 veyra-anon-{agent_id[:8]}），外部平台据此隔离会话。

F-GW-063 工作流节点进度帧

描述：workflow 型应用执行过程中实时显示节点进度。
实现：node_started / node_finished 在既有 Langfuse SPAN 上报之外并行发 VES step.started / step.completed 帧（两条链路互不影响），节点名入 step.title，elapsed_time 换算为耗时；门户 runTree.ts 维护节点状态机（running/waiting/completed/failed），由统一执行轨迹 ExecStep 渲染。不新增帧类型——等待态复用 step 帧。

F-GW-064 思考帧

描述：把外部平台暴露的推理过程以独立「思考卡片」呈现，不混入正文。
实现：agent_thought 映射为 reasoning.delta / reasoning.completed。平台 thought 是按 position 累计的文本（可能先空后填），按已发送前缀取增量、空增量不出帧；OpenAI 兼容链在正文或工具调用开始时补发 reasoning.completed 收束思考块，正文不重复思考内容。

F-GW-065 等待人工处理态展示

描述：工作流停在人工处理节点时，前端明确展示「等待人工处理」而不是静默挂起。
实现：workflow_paused / human_input_required 映射为 step.started + status="waiting"（不新增帧类型，等待中的步骤仍是活跃步骤），节点等待态同样标 waiting。分支带节点图应用（_NODE_GRAPH_APP_TYPES = workflow/chatflow）守卫，纯对话型应用（chat/agent）不受影响。恢复链路（表单回填提交）尚未实现，一期只做展示。

F-GW-066 历史会话列表与回看

描述：外接实例在门户侧栏提供历史会话列表，支持继续对话与删除。
实现：会话由外部平台持有（不入平台 DB），经 Service API GET /v1/conversations[/{id}/messages] 代理；放开「会话由客户端占位」限制，侧栏直接接 conversations API。历史记录按数据形态归一（role+content 直接可用，query/answer 拆成 user+assistant 两条），不引入引擎名分支；删除请求经用户锚点注入转发。

F-GW-067 工作流输入参数表单

描述：workflow 型应用在会话首开前渲染输入参数表单，提交后随首轮请求送入执行。
实现：GET /v1/parameters 的 user_input_form 由前端归一为字段模型（一期支持 text-input / paragraph / number / select 四类，其余类型静默忽略），表单作为会话首开的前置步骤渲染，值随首轮 runs 请求体的 inputs 提交；不支持表单的引擎按能力档案（profileFromCapabilities 的 inputForm）跳过。

四、Admin Console（apps/admin，Vue3 + Element Plus）

4.1 三层前端

F-ADM-001 智能体定义列表

描述：网格卡片展示定义，搜索/状态筛选/引擎筛选/分页。
路由：/agent-definitions
实现：响应式网格（xs:24,sm:12,md:6,lg:6）；统计卡片（已发布/草稿）；引擎筛选 Hermes/OpenClaw/Dify/Claude Code。

F-ADM-002 智能体定义详情

描述：3 Tab（人设 SOUL.md / 技能管理 / 版本管理），编辑/发布/删除。
路由：/agent-definitions/detail/:id
实现：头部卡片 + 引擎类型图标；下拉菜单更多操作；跳转关联实例/资源池；多步骤编辑表单。

F-ADM-003 智能体实例列表

描述：实例生命周期管理，创建/克隆/发布/停用/删除。
路由：/agent-instances
实现：三状态统计（已上线/草稿/已停用）；引擎+状态双重筛选；状态 DRAFT→PUBLISHED→OFFLINE。

F-ADM-004 智能体实例详情（5 Tab）

描述：概览/实例/监控/记忆/技能 5 Tab，运行时生命周期操作。
路由：/agent-instances/detail/:id
实现：双层状态（Manager 业务态 + Controller 部署态）；部署/暂停/恢复/重启/销毁操作；15s 轮询部署状态；Pod 重建跟踪。

F-ADM-005 资源池管理

描述：资源池配置管理，克隆/删除。
路由：/resource-pools
实现：三维统计（总数/自动回收/手动管理）；卡片网格；搜索分页。

4.2 LiteLLM 模型网关管理

F-ADM-010 模型配置管理

描述：配置 LLM 上游连接参数。
路由：/litellm/models
实现：多供应商（OpenAI/Anthropic/Azure/Gemini）；API Key 编辑可留空保持不变；自定义提供商。

F-ADM-011 API Key 管理

描述：Key 权限/预算/速率限制管理。
路由：/litellm/keys
实现：Key 状态（正常/封禁）；智能关联解析（metadata.agent_id 或 key_alias）；用户组隔离；预算 max_budget+budget_duration；rpm/tpm；封禁/解封；用量统计。

F-ADM-012 用量统计

描述：Token 用量与成本趋势。
路由：/litellm/spend
实现：ECharts 折线（趋势）/饼（用户组）/柱（模型）/柱（实例）；时间范围 + 用户组筛选；成本计算。

4.3 Dashboard 仪表盘

F-ADM-020 多角色仪表盘

描述：根据角色展示不同视角运营数据。
路由：/welcome
实现：<div class="main"><div class="welcome"> 双层容器，max-width 1400px；管理员左右分栏 md:17/md:7（73%/27%）；.chart-card+.chart-fill 自适应高度；ECharts 选项 as any 断言。
管理员视角：概览数字卡片、系统健康监控、三大分布饼图（实例状态/引擎类型/运行状态）、6 快捷入口、底部四维监控（资源消耗/Token计费/热门Top5/最近动态时间线）。
组管理员视角：组专属统计、实例状态进度条、快捷入口。
普通用户视角：可访问实例数、个人对话统计、我的实例网格、7 天对话趋势。

4.4 系统管理

F-ADM-031 角色权限管理

描述：角色 CRUD 与权限树配置；用户角色绑定（账号生命周期在账号中心管理，平台侧仅分配角色）。
路由：/system/role/index
实现：权限树形结构 + 搜索过滤 + 全选/展开联动；响应式可折叠；角色绑定走 PUT /api/manager/users/{id}/roles。

F-ADM-033 产品设置（ASR / AI 生成 / 品牌白牌）

描述：平台级运营配置在线管理——语音识别（ASR）、AI 生成能力开关与人设/头像模型配置、企业品牌定制（产品名/标语/版权/备案号/Logo/网站图标）。
路由：/system/settings/index
实现：system_settings KV 表（pkg/common/system_settings.py 单一注册表，key 前缀分 brand/ai/asr 三组）；取值链 DB 行 > 环境变量兜底 > 代码默认（存量部署空表行为不变，回滚安全）；敏感值 Fernet 加密落库、API 仅回 configured/masked；manager 每请求直查即生效，gateway 走 60s TTL 缓存 + 配置指纹重建 provider；品牌经公开端点 GET /api/manager/branding 下发，admin/enduser 双端登录页/导航/页脚/浏览器标题与图标运行时生效（未配置回落构建期默认）；品牌图片上传复用 MinIO public bucket（brand/ 前缀，≤2MB，png/jpg/webp/ico）。管理页三页签独立保存，仅提交变更字段，页签底部提供重置与保存。

4.5 国际化与配置

F-ADM-040 i18n 国际化

描述：中英文双语界面。
实现：Vue i18n + Element Plus 本地化；YAML 语言文件；import.meta.glob 服务器启动缓存（改 yaml 需重启 Vite）；$t 为占位符（i18n Ally 提示），真实翻译在 transformI18n；flatI18n 缓存有 bug 已绕过。

F-ADM-041 版本检测

描述：构建时生成 version.json 消除 version-rocket 轮询报错。

4.6 样式与技术约束

F-ADM-050 图标渲染约束

描述：禁止将图标字符串直传 IconifyIconOffline，必须 import Chat1Line from "~icons/ri/chat-1-line"；JSX 中用 {...({width:"18"} as any)}。

F-ADM-051 页面布局约束

描述：列表/内容页用 <div class="main"> 容器；按钮左筛选右；搜索框 width 260px + suffix 图标 v-show 控制；筛选下拉在前搜索在后。

F-ADM-052 技术栈

实现：Vue3 + TS + Element Plus + Vite + Pinia + Vue Router 4 + ECharts；RePureTableBar/ReIcon/ReDialog/ReCountTo/ReECharts 组件库；Tailwind + SCSS + 暗色主题 + 响应式；RBAC 动态路由 + 按钮权限 + 用户组隔离。

4.7 工作台外接引擎面板（Dify）

面板的显示与置灰由能力表驱动：后端 GET /api/manager/engines 下发每个引擎的能力声明（含 binding / console_url_template / canvas_embed_url_template），前端 src/utils/engineCaps.ts 缓存后供各面板查询。能力表未就绪时按「支持」处理（网络抖动不该让整个配置界面变灰），真实约束由后端兜底。本小节的外接判定（绑定节点注入、画布地址、控制台链接）全部走能力查询、不按引擎名分支；引擎选择列表、图标字形等枚举型展示仍按引擎类型列出（属注册点性质，非行为分支）。

F-ADM-060 应用绑定面板

描述：工作台「构建」页签的应用绑定面板——把该智能体绑定到外部平台上的一个应用，含「测试连接」与绑定状态展示。
路由：/agents/detail/:id（「构建」页签）
实现：「应用绑定」树节点不按引擎名枚举——能力表 binding=external-app 的引擎自动注入该节点（新外接引擎声明该能力即获得面板，无需改本文件）。面板按引擎配置状态呈现两态：已配管理员 → 应用下拉（列表为空给空态提示）；未配 → 手填 base_url + 密钥 + 应用类型 + 「测试连接」校验（复用 F-MGR-092 的两态契约）。绑定完成态展示应用摘要与掩码密钥，操作有「刷新」「更换应用」「密钥轮换」（F-MGR-093）与「在外部控制台打开 ↗」外链（URL 由能力表 console_url_template + 绑定值拼装）；展示元数据策略为打开面板自动拉取 + 手动刷新，不做后台轮询。

F-ADM-061 编排画布只读内嵌

描述：工作台只读内嵌外部平台的工作流编排画布，便于在平台内查看编排全貌，不提供任何编辑交互。
路由：/agents/detail/:id（「构建 → 工作流编排」面板）
实现：iframe URL = 能力表 canvas_embed_url_template + 定义级绑定（base_url/app_id）拼装，组件无引擎名分支；sandbox="allow-scripts allow-same-origin" 收敛权限 + 透明拦截层实现 UI 级只读（拦截点击/键盘，防误编辑）。未绑定 → 引导「去绑定」跳树首面板；非 workflow 型应用（如对话型）无编排画布 → 降级为「在外部控制台打开」外链；未登录外部控制台或被 X-Frame-Options 拒绝 → 画布区域空白 + 提示先登录后刷新 + 常驻外链。鉴权以用户自有外部控制台会话为前提，平台不做免密注入。权限级只读不做，由用户在外部平台侧自行用只读账号保证。

F-ADM-062 编排摘要面板

描述：画布下方三标签页只读展示绑定应用编排中的变量、数据集、工具。
路由：/agents/detail/:id（「构建 → 工作流编排」面板）
实现：数据取自 F-MGR-095 的 binding/app-summary；未配管理员账号或读取失败 → 降级为引导态，不阻断页面；环境变量值掩码展示。RAGFlow 等同类图形化编排场景复用同一模式。

F-ADM-063 引擎管理 Dify 配置面板

描述：系统管理 → 引擎管理 → Dify 的平台接入配置面板：连接信息、测试连接、应用列表与平台状态。
路由：/system/engine-management/index → /system/engine-management/detail/:type
实现：表单含平台地址 + 管理员邮箱/密码（可选）+ 「可观测纳管」开关（默认开）；密码类字段只提交不回显（响应仅 *_configured 标记）。配了管理员账号时另展示应用列表卡片（名称/模式/描述/app_id + 一键复制应用 ID，可手动刷新，支持勾选后批量导入为智能体：选目标用户组后自动创建同名定义、绑定并发布，已存在的幂等跳过，逐个展示导入结果），列表为空给空态提示。「测试连接」走平台探活（未配管理员时以 Service API /v1/info 探活、无应用数，配了则返回应用数并刷新列表）；「平台状态」按 last_check_status / last_check_at 渲染（正常/异常/未巡检三态，异常时给出可读原因），来自 F-MGR-091 的周期性探活。

五、Enduser Portal（apps/enduser，Vue3 + Tailwind）

5.1 认证与智能体发现

F-END-001 JWT 认证

描述：双 Token（access/refresh）+ LocalStorage 持久化 + 自动会话恢复 + 401 跳登录。
组件：Auth Store /stores/auth.ts

F-END-002 路由守卫

描述：meta.requiresAuth 权限控制，未认证重定向 /login。
组件：Router Guard

F-END-003 可访问智能体列表

描述：获取用户有权访问的实例列表。
API：GET /api/manager/agent-instances/accessible
实现：支持 HERMES/OPENCLAW 引擎类型；含名称/描述/引擎信息。

F-END-004 智能体部署与进度

描述：自动部署引擎，SSE 进度追踪。
实现：EventSource 监控；步骤准备→创建Pod→配置→等待就绪→验证→完成；防误判（防 EventSource 默认 error 误判）；支持重试。

F-END-005 引擎健康监控

描述：503 自动检测，不可用提示横幅，自动触发重新部署。

5.2 会话管理

F-END-010 多会话管理

描述：创建/切换/删除多个对话会话。
实现：会话存引擎本地（不入 Manager DB）；POST /api/gateway/api/sessions；按时间倒序；搜索 + 日期分组（今天/昨天/本周/上周）。

F-END-011 智能标题生成

描述：启发式从首条用户消息截取标题，避免 LLM 生成多余记录；支持内联重命名。
API：PATCH /api/gateway/api/sessions/{id}

F-END-012 会话持久化

描述：LocalStorage 缓存 + 消息懒加载 + JSON 导入导出。

5.3 消息处理

F-END-020 SSE 流式消息

描述：ReadableStream + TextDecoder 解析，AbortController 中断，实时渲染。
API：POST /api/gateway/v1/chat/completions

F-END-021 Markdown 渲染

描述：streaming-markdown 库，表格/代码块/链接，自动+手动滚动控制，时间戳。
组件：ChatMessages.vue

F-END-022 工具调用追踪

描述：实时显示工具状态（waiting/running/done）+ 活动事件分类 + 工具标签智能识别（搜索/读取/写入/命令）。执行中的过程自动展开，回答落定后收成一行摘要（单步直接说动作名，多步给出步数与总时长；有失败步骤时补一句失败步数），点击可回看每一步。「执行中断」只在整个任务失败或被强制停止时出现——某个工具失败后引擎换个工具继续重试、本轮照常跑完的，不算中断。
组件：packages/ua-chat components/ExecTrace.vue + components/ExecStep.vue + components/ToolDetail.vue（活动事件并入同一条执行轨迹）

5.4 工作区

F-END-030 文件系统浏览器

描述：树形文件结构 + 大小格式化 + 展开折叠。
API：GET /api/gateway/v1/files
组件：ChatFileBrowser.vue

F-END-031 多工作区切换

描述：工作区列表动态获取 + 状态保持 + 切换刷新。

F-END-032 文件附件上传

描述：多文件选择 + 附件标签 + 移除。
组件：ChatComposer.vue

5.5 用户界面

F-END-040 Rail 导航系统

描述：左侧 rail 导航 9 面板（对话/任务/看板/技能/记忆/工作区/配置/任务/洞察），响应式。
组件：ChatPage.vue

F-END-041 会话列表界面

描述：日期分组 + 搜索 + 批量选择删除 + 右键菜单 + 内联重命名。
组件：ChatSessionList.vue

F-END-042 智能输入框

描述：自动高度 + Enter/Shift+Enter 发送 + 模型选择下拉 + 附件按钮 + 发送/停止状态。
组件：ChatComposer.vue

5.6 模型管理

F-END-050 动态模型加载

描述：优先从 Controller 获取 Agent 配置模型，回退引擎 /v1/models。
实现：模型选择切换 + 默认模型同步；bareModel 提取 provider/model_name 中的纯模型名。

5.7 网络通信

F-END-060 API 客户端

描述：统一 HTTP 客户端，自动 JWT 头 + 401 处理跳转 + 统一错误。
组件：api/client.ts

F-END-061 Gateway 代理通信

描述：通过 Gateway 转发到引擎，base /api/gateway，自动 X-Agent-ID + X-Engine-Type + X-Session-ID 头。

F-END-062 Nginx 代理配置

描述：/api/manager/→manager:8002、/api/controller/→manager:8002（controller 已并入 manager，worker_router 在 /api/controller/* 字面路径提供服务）、/api/gateway/→gateway:8010（剥离前缀）；SSE 长连接优化；/api/manager/ 通配修复 k3s 直连 pod 时 /accessible 404。

5.8 设置与体验

F-END-070 主题与字体

描述：浅色/深色/系统主题 + 四档字体大小 + LocalStorage 持久化 + 实时预览。

F-END-071 面板记忆

描述：LocalStorage 记忆工作区面板开关 + 可调大小。

F-END-072 会话导出导入

描述：Markdown/JSON 导出 + JSON 导入验证。

F-END-073 滚动优化

描述：距底部 150px 内自动滚动 + 阅读时暂停 + 手动回到底部按钮 + 平滑动画。

F-END-074 移动端适配

描述：移动端专用侧边栏 + 触摸友好 + 自适应布局。

F-END-075 回复内图表与文件展示

描述：对话回复中的 mermaid 代码块原生渲染；markdown 相对路径图片（如 ![描述](output/chart.png)）经工作区解析为内联图片；非图片文件（PDF/CSV 等）渲染为可点击下载链接。
组件：packages/ua-chat markdown.ts + renderEnhancements.ts（imageResolver 注入回调，经 manager 文件接口取 base64）
实现：智能体侧产出规范由平台统一注入（见 F-MGR-089）；数据图表由 chart-drawing 技能脚本产出 PNG 落工作区 output/，回复以相对路径引用。

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

描述：工作流型智能体在会话首开前渲染输入参数表单（如金额、事由等），填完提交后进入对话。
组件：apps/enduser/src/components/chat/InputFormCard.vue + useChat + packages/ua-chat ves/inputForm.ts
实现：引擎档案（profileFromCapabilities 的 inputForm）为真时，会话首开拉取引擎参数端点并归一为字段模型（text-input / paragraph / number / select，其余类型忽略），按 schema 渲染前置表单（必填项标 *）；提交时组件内校验必填，缺失则原地提示「请填写「X」」不提交；通过后按字段类型收敛取值（number 转数值、空值不下发），随首轮 runs 请求体的 inputs 送入执行。无字段时不渲染表单，直接进入对话。

F-END-077 推理步骤与节点进度展示

描述：推理过程与工作流节点进度统一收进「执行轨迹」——按回答的段落切分，每段正文之前的过程收成一行摘要（执行中自动展开），正文之间因此保持连贯；思考、工具调用、工作流节点三类事件在同一轴上按到达顺序排列。MCP 工具以「服务 · 工具」两段式展示（服务显示名弱化在前），而非引擎注册的全长原始名。
组件：packages/ua-chat components/ExecTrace.vue + components/ExecStep.vue + components/ToolDetail.vue + components/execTraceTypes.ts + ves/timeline.ts（帧→展示态共享投影）+ ves/runTree.ts + ves/parser.ts；apps/enduser/src/composables/useChat.ts（活动事件）
实现：消费网关下发的 reasoning.*（思考增量/收束）与 step.started/completed（节点进度，status 含 running/waiting/completed/failed）两类 VES 帧，连同工具调用与引擎活动事件归一到同一个展示模型，再按 text 事件切分成「过程组 + 正文段」交替的序列；过程组内以单一图标位对齐各项，节点与工具按色彩区分。等待人工处理节点显示「等待人工处理」，run 收尾时仍处等待态的事件统一置 done（有回复的标「已回复」）。事件源无时间戳时（Skill Studio 的平行模型）不显示耗时。帧到轨迹的映射与引擎无关（见 F-GW-063 ~ F-GW-065），组件内无引擎名分支。

F-END-078 历史会话列表与回看

描述：会话侧栏列出历史会话，支持继续对话与删除；外接引擎的会话同样可见可续。
组件：apps/enduser/src/composables/useChat.ts + utils/historyMessages.ts；packages/ua-chat components/ChatSessionList.vue
实现：会话由引擎侧持有（不入 Manager DB），经网关代理引擎的会话接口；历史记录按数据形态归一（role+content 与 query/answer 两种载荷都兼容，不引入引擎名分支）；外接引擎无预创建会话接口，新会话先本地占位、首轮后由引擎回传的真实会话标识替换（见 F-GW-066）。

F-END-079 品牌白牌运行时

描述：登录页品牌区（Logo/产品名/标语）、顶部导航产品名、页脚版权与 ICP 备案链接、浏览器标题与图标按管理台「产品设置 → 品牌与外观」在线定制，未配置回落构建期默认。
组件：apps/enduser/src/utils/branding.ts（模块级单例）+ components/BrandFooter.vue
实现：main.ts mount 后裸 fetch 公开端点 GET /api/manager/branding（避开 api/client 的 401 跳登录语义），失败静默回落；颜色走 --muted CSS 变量双主题自适应；品牌图片经 nginx /avatars/ 反代 MinIO（dev 由 vite proxy 等价代理）。

六、Engine Integration（引擎集成）

F-ENG-001 Hermes 引擎容器化

描述：Docker 基础镜像 + nginx 多 Profile 路由，容器化部署于 k3s Pod，通过原生 HTTP API 调用，不侵入式修改源码。
实现：暴露 OpenAI 兼容接口 /v1/chat/completions；多 Profile 每实例一个；PVC 持久化 /opt/data/profiles/{name}；端口 8642。

F-ENG-002 引擎运行时强契约

描述：ENGINE_RUNTIMES 常量定义引擎类型（HERMES / OPENCLAW / DIFY / CLAUDECODE / DEEPSEEK），新增引擎必须改代码（非数据驱动）；镜像、端口、分类（GENERAL / ORCHESTRATION / CODING）在此登记，镜像可被环境变量覆盖；未知/空引擎类型显式报错，禁止回落 HERMES（回落会掩盖接入缺陷）。
实现：端口 HERMES/OPENCLAW 8642、CLAUDECODE 8648、DEEPSEEK 8649、DIFY 5001（对齐 Dify 1.14 源码实际监听）。Dify 仅外接模式（无 Pod 部署），其 image/port 仅供引擎目录展示与契约文档，无 Pod 消费者（见 F-ENG-005）。

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

描述：PENDING → DEPLOYING → RUNNING ↔ SUSPENDED → ARCHIVED，含 FAILED 分支。

F-ENG-004 DNS 命名规范路由

描述：engine-hermes-{instance_id[:8]}.{namespace}.svc.cluster.local:8642，Gateway 与 Controller 通过命名约定解耦，无运行时依赖。
例外：外接引擎实例不走 DNS 命名路由——引擎在集群外，由 Gateway 从绑定配置取外部平台地址直连（见 F-ENG-005 / F-GW-060）。

F-ENG-005 外接引擎契约（external-app）

描述：引擎可以「外接」形态接入——平台不部署、不编排其任何组件，只对接用户自管的外部平台实例；实例没有 Pod、不占资源池、发布即上线。Dify 是当前唯一启用该形态的引擎。
实现：由引擎能力表（pkg/common/engine_caps.py）声明，非引擎名分支：config_channel="external" 表示不部署 Pod（部署/暂停/恢复/重启/销毁全部跳过 K8s 操作路径）；binding="external-app" 表示实例需先绑定外部平台上的一个应用才能对外服务（前端据此注入「应用绑定」面板、发布链路强制校验绑定完整性）；console_url_template / canvas_embed_url_template 是引擎自描述的外部控制台链接与只读编排画布嵌入地址模板（占位符 {base_url} / {app_id}），空串表示不具备该入口、前端不渲染。运行时经 Gateway 适配外部平台原生 API，模型配置通道 model_config_channel="none"（模型由外部应用自带，可能经平台网关也可能直连外部模型服务）。

七、Deploy（部署架构）

F-DEP-001 k3s 部署

描述：单 namespace veyraos；双域名 Ingress（admin/chat）；Controller 按实例动态创建 Deployment+Service+PVC；本地用 colima + k3s。
路径：deploy/k8s/、deploy/k8s/infra/

F-DEP-002 基础设施组件

描述：PostgreSQL 16（StatefulSet+PVC，veyraos+litellm 两库）、MinIO（对象存储归档）、LiteLLM Proxy（模型网关）、Traefik Ingress（TLS+Let's Encrypt）。

F-DEP-003 服务端口规划

描述：见整体架构表（PostgreSQL 5432 / MinIO 9000-9001 / LiteLLM 4000 / Hermes 8642 / Manager 8002（含 controller worker）/ Gateway 8010 / Admin 8848 / Portal 3000）。

F-DEP-004 容器镜像构建

描述：Gitee Go → 容器镜像仓库；生产 Always / 开发 IfNotPresent；amd64；Dockerfile.local 宿主预构建 dist 绕过 pnpm 11 容器内 build 硬错。

F-DEP-005 安全配置

描述：veyraos-secret 统一凭据（仅本地 k3s，占位符）；ServiceAccount+Role+RoleBinding RBAC；TLS 自动签发；敏感信息只走 env/k8s Secret/.env.local（已 gitignore）。

八、Scripts（运维脚本）

F-SCR-001 三层模型数据迁移脚本

描述：建表 + 数据迁移 + 列重命名 + DROP 旧版老表。
路径：scripts/migrate_to_v3.py、migrate_to_v3_data.py

F-SCR-002 端口转发脚本

描述：一键转发本地开发所有 k8s 服务（3001→portal / 8010→gateway / 8002→manager（含 controller worker））。
路径：scripts/port-forwards.sh

F-SCR-003 版本管理脚本

描述：bump-version.sh 语义化版本更新 + VERSION 文件。

F-SCR-004 种子数据脚本

描述：seed.py 管理员初始化 + seed_test_users.py 测试用户 + migrate_im_user_bindings.sql IM 绑定迁移。

F-SCR-005 调试测试脚本

描述：im_test_simulator.py IM 模拟器；testcontainers 集成测试；E2E 端到端生命周期测试。

F-SCR-006 演示工作区脚本

描述：一键演示环境的数据预置与重置（全程走 manager HTTP API，复用生产路径）。
路径：scripts/seed-demo-workspace.py（演示组/用户/资源池/知识库+样例文档/实例创建部署轮询，幂等可重跑）、scripts/reset-demo-workspace.py（销毁+删除演示组实例清运行态，--with-instances 重建）。

九、公共包（pkg/）

F-PKG-001 统一配置

描述：pkg/common/config.py 全局配置 + ENGINE_RUNTIMES 常量；dev/prod 区分；环境变量覆盖。

F-PKG-002 共享数据模型

描述：pkg/models/ 跨服务共享模型；Controller 用无外键约束版本避免循环依赖；AgentDeployment / AgentProfile / ResourceMetricSample 等。

F-PKG-003 异步数据库连接

描述：pkg/common/database.py SQLAlchemy async 引擎 + 连接池。

F-PKG-004 引擎能力表（EngineCaps）

描述：pkg/common/engine_caps.py 是 manager / gateway 共用的唯一引擎能力事实源——引擎差异（会话文件 API、流式族、Profile 形态、模型配置通道、资产通道、沙箱、生命周期、外接绑定）一律经 get_engine_caps() / lookup_engine_caps() 查询，不得在业务代码里散落引擎名字符串分支。用于复刻时必须照搬的 EAC 强契约。配套门禁 scripts/check_engine_literals.py（接 make lint，白名单为显式注册点）——注意其当前扫描范围只覆盖 CLAUDECODE / DEEPSEEK / OPENCLAW，DIFY / HERMES 与前端目录留待后续批次。
实现：不可变 dataclass EngineCaps，字段默认值 = HERMES 现状，每个非默认项在代码注释里附现状代码依据。查询分严格/宽容两形态：入口层（HTTP 解析、adapter 构造）用严格版，未知/空值抛 UnknownEngineError；服务内部点位（引擎类型来自 DB 列、可能为空）用宽容版返回 None，按「不具备任何能力」短路。caps_view() 是唯一对外序列化形态（hot_reload 是集合、下发前转排序列表以保证响应可复现），经 GET /api/manager/engines 与实例响应下发，驱动前端 src/utils/engineCaps.ts 的 UI 门控。外接相关字段见 F-ENG-005；平台侧策略（展示过滤、调试默认形态）不收录在本表。

十、文档体系（docs/）

F-DOC-001 架构文档

描述：apps/docs/content/architecture/ 架构文档（md）；ER 关系图；运行时序图；RBAC 权限矩阵。

F-DOC-002 功能特性文档

描述：docs/features/ overview / hermes-engine / enduser-portal / gateway / im-channels。

F-DOC-003 部署与变更

描述：docs/deployment/ 部署指南；docs/changelog/ 变更日志。

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

约束	说明
Gateway 反向依赖禁止	Gateway 不得查询 Controller 获取 upstream，仅靠 `X-Agent-ID` + DNS 命名；例外：外接引擎实例不经 DNS，由绑定配置取外部平台地址直连
SSE 与 nginx	`proxy_buffering off`；`Connection upgrade` 会干扰 SSE；浏览器 ReadableStream+TextDecoder 解析；nginx 不得缓冲/修改 SSE
iframe 默认禁止	终端门户不 iframe 嵌 hermes-webui，直接渲染 Vue3 组件。唯一例外：管理台工作台「构建」页签对外部工作流引擎（Dify / RAGFlow 等）的图形化编排画布只读预览允许 iframe 内嵌——URL 只取自该实例已登记的绑定地址（不接受任意用户输入）、必须带 `sandbox` 收敛权限 + 透明拦截层实现 UI 级只读、被 `X-Frame-Options` 拒绝时降级外链、鉴权以用户自有外部控制台会话为前提（平台不做免密注入/代登录）
Gateway Origin 过滤	转发前去掉 Origin/Referer（Hermes 收 Origin 返 403）
存档策略	存档提前到 SUSPEND（30min 空闲）；不定期轮询备份；PVC 实时写；DESTROY 仅清 K8s 资源；外部实例不适用（无 Pod/PVC，不会被空闲回收调度自动休眠）
会话不入 Manager DB	聊天会话由引擎自身管理
UserGroup 隔离	租户内资源归属单元；资源表 group_id；管理台平台管理员旁路，网关数据面无旁路（跨组调试走代发凭证）
LiteLLM 唯一出口	内置引擎只走 LiteLLM；租户=Team；每 Agent 一 key；计费 Team 由 access 派生。例外：外接引擎的模型由外部应用自持，可能经平台网关也可能由外部平台直连外部模型服务（后者用量平台无法完整归集，管理台展示模型通道供核对，见 F-MGR-094）
引擎差异经能力表	引擎差异一律经能力表查询（后端 `EngineCaps`、前端 `engineCaps.ts`、门户 `profileFromCapabilities`），不得在业务代码里散落引擎名字符串分支；新增引擎靠声明能力获得支持，不靠改业务分支。Python 门禁 `scripts/check_engine_literals.py`（接 `make lint`）扫描 `pkg/common` + manager + gateway，白名单为显式注册点（能力表、`ENGINE_RUNTIMES`、adapter 注册表等）；Python 扫描范围只含 CLAUDECODE / DEEPSEEK / OPENCLAW，DIFY / HERMES 在 manager 侧尚有合法残留，待外接域边界收敛后纳入 `--strict`。前端三目录（`apps/admin/src` / `apps/enduser/src` / `packages/ua-chat/src`）由 `scripts/check_frontend_engine_literals.mjs` 门禁覆盖（只拦 `engine_type ===/!== "ENGINE"` 控制流比较，接 `make lint` 与两端 `build`），白名单登记范围外存量控制流，行漂移即 fail
开源软件不侵入	只用扩展能力 + 云化加固，引擎容器化通过原生 HTTP API 调用；外接引擎不部署不编排，只经其原生 API 对接

复刻核对清单（按组件统计）

组件	特性数
Manager Backend	49（F-MGR-001 ~ F-MGR-096）
Controller Backend	29（F-CTL-001 ~ F-CTL-062）
Gateway Backend	28（F-GW-001 ~ F-GW-067）
Admin Console	22（F-ADM-001 ~ F-ADM-063）
Enduser Portal	31（F-END-001 ~ F-END-079）
Engine Integration	5（F-ENG-001 ~ F-ENG-005）
Deploy	5（F-DEP-001 ~ F-DEP-005）
Scripts	6（F-SCR-001 ~ F-SCR-006）
公共包	4（F-PKG-001 ~ F-PKG-004）
文档	3（F-DOC-001 ~ F-DOC-003）
合计	180 项特性

复刻时建议按「定义层 → 资源层 → 实例层 → 引擎生命周期 → 模型网关 → IM 渠道 → 权限隔离 → 仪表盘 → 终端门户 → 部署运维」顺序推进，每完成一项核对编号打勾。
编号约定：编号一经发布不复用、不重排——同节新增能力顺延该节最大号 +1（如 Manager 递增到 F-MGR-090+），小节内追加用字母后缀（如 F-MGR-004b / F-MGR-085a）。本表的特性数为当前实际条目数，新增/删除条目时同步更新。

VeyraOS（VeyraOS）— 产品特性全量清单 ​

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

一、Manager Backend（services/manager） ​

1.1 智能体定义层 ​

F-MGR-001 智能体定义 CRUD ​

F-MGR-002 版本快照与发布 ​

F-MGR-003 人设配置 ​

F-MGR-004 技能管理（定义层） ​

F-MGR-004b 外部工具（MCP） ​

1.2 资源池层 ​

F-MGR-005 资源池 CRUD ​

F-MGR-005b 资源池对接外部 K8s 集群 ​

F-MGR-006 资源池实时监控 ​

1.3 实例层 ​

F-MGR-007 实例 CRUD ​

F-MGR-008 实例业务生命周期 ​

F-MGR-009 实例运行时生命周期 ​

F-MGR-010 实例运行时详情 ​

F-MGR-011 实例 IM 渠道绑定 ​

F-MGR-012 实例 LiteLLM Key reprovision ​

F-MGR-013 终端门户可访问实例 ​

1.4 LiteLLM 模型网关集成 ​

F-MGR-020 模型管理 ​

F-MGR-021 虚拟 Key 管理 ​

F-MGR-022 Team 同步 ​

F-MGR-023 用量计费统计 ​

1.5 IM 渠道接入 ​

F-MGR-030 IM 用户绑定 ​

1.6 权限与隔离 ​

F-MGR-040 用户组（租户内资源空间） ​

F-MGR-041 RBAC 角色权限 ​

F-MGR-042 用户身份索引 ​

F-MGR-043 管理员旁路 ​

F-MGR-044 access_scope 访问控制 ​

F-MGR-046 多租户（组织 → 租户投影） ​

F-MGR-047 租户分层门控（tier） ​

F-MGR-048 登录即建（JIT） ​

F-MGR-045 一键演示登录（demo-login） ​

1.7 监控仪表盘 ​

F-MGR-050 系统仪表盘 ​

F-MGR-051 指标采样服务 ​

1.8 备份迁移与初始化 ​

F-MGR-060 三层模型数据迁移脚本 ​

F-MGR-061 种子数据初始化 ​

1.9 系统集成 ​

F-MGR-070 Controller 代理客户端 ​

F-MGR-071 数据库架构（三层模型） ​

1.10 知识库（RAG） ​

F-MGR-080 知识库 CRUD ​

F-MGR-081 文档管理与异步解析 ​

F-MGR-082 分块策略 ​

F-MGR-083 知识图谱（KB 级开关） ​

F-MGR-084 检索与重排序 ​

F-MGR-084a 治理运维（导出 / 缓存 / 运行状态） ​

F-MGR-085 内部检索（智能体调用） ​

F-MGR-085a 智能体级检索配置 ​

F-MGR-086 引擎健康 ​

F-MGR-087 绑定智能体管理 ​

F-MGR-088 附件内容识别（图片 / PDF） ​

F-MGR-089 平台级文件引用规范注入 ​

1.11 Dify 外接引擎（External-Only） ​

F-MGR-090 Dify 引擎配置（外接） ​

F-MGR-091 外部平台健康巡检 ​

F-MGR-092 定义级应用绑定 ​

F-MGR-093 绑定应用密钥轮换 ​

F-MGR-094 模型通道可视化 ​

F-MGR-095 编排摘要（变量 / 数据集 / 工具） ​

F-MGR-096 外接实例发布与运行时（无 Pod） ​

F-MGR-097 部署失败归因与解决方案提示 ​

二、Controller Backend（已并入 services/manager/app/worker） ​

2.1 引擎 Pod 生命周期 ​

F-CTL-001 Agent Deploy ​

F-CTL-002 Agent Status ​

F-CTL-003 SUSPEND 空闲存档 ​

F-CTL-004 RESUME 恢复 ​

F-CTL-005 DESTROY 归档销毁 ​

F-CTL-006 RESTART 滚动重启 ​

F-CTL-007 部署进度 SSE ​

2.2 数据持久化与存储 ​

F-CTL-010 PVC 持久化 ​

VeyraOS（VeyraOS）— 产品特性全量清单

0. 产品定位与整体架构

一、Manager Backend（services/manager）

1.1 智能体定义层

F-MGR-001 智能体定义 CRUD

F-MGR-002 版本快照与发布

F-MGR-003 人设配置

F-MGR-004 技能管理（定义层）

F-MGR-004b 外部工具（MCP）

1.2 资源池层

F-MGR-005 资源池 CRUD

F-MGR-005b 资源池对接外部 K8s 集群

F-MGR-006 资源池实时监控

1.3 实例层

F-MGR-007 实例 CRUD

F-MGR-008 实例业务生命周期

F-MGR-009 实例运行时生命周期

F-MGR-010 实例运行时详情

F-MGR-011 实例 IM 渠道绑定

F-MGR-012 实例 LiteLLM Key reprovision

F-MGR-013 终端门户可访问实例

1.4 LiteLLM 模型网关集成

F-MGR-020 模型管理

F-MGR-021 虚拟 Key 管理

F-MGR-022 Team 同步

F-MGR-023 用量计费统计

1.5 IM 渠道接入

F-MGR-030 IM 用户绑定

1.6 权限与隔离

F-MGR-040 用户组（租户内资源空间）

F-MGR-041 RBAC 角色权限

F-MGR-042 用户身份索引

F-MGR-043 管理员旁路

F-MGR-044 access_scope 访问控制

F-MGR-046 多租户（组织 → 租户投影）

F-MGR-047 租户分层门控（tier）

F-MGR-048 登录即建（JIT）

F-MGR-045 一键演示登录（demo-login）

1.7 监控仪表盘

F-MGR-050 系统仪表盘

F-MGR-051 指标采样服务

1.8 备份迁移与初始化

F-MGR-060 三层模型数据迁移脚本

F-MGR-061 种子数据初始化

1.9 系统集成

F-MGR-070 Controller 代理客户端

F-MGR-071 数据库架构（三层模型）

1.10 知识库（RAG）

F-MGR-080 知识库 CRUD

F-MGR-081 文档管理与异步解析

F-MGR-082 分块策略

F-MGR-083 知识图谱（KB 级开关）

F-MGR-084 检索与重排序

F-MGR-084a 治理运维（导出 / 缓存 / 运行状态）

F-MGR-085 内部检索（智能体调用）

F-MGR-085a 智能体级检索配置

F-MGR-086 引擎健康

F-MGR-087 绑定智能体管理

F-MGR-088 附件内容识别（图片 / PDF）

F-MGR-089 平台级文件引用规范注入

1.11 Dify 外接引擎（External-Only）

F-MGR-090 Dify 引擎配置（外接）

F-MGR-091 外部平台健康巡检

F-MGR-092 定义级应用绑定

F-MGR-093 绑定应用密钥轮换

F-MGR-094 模型通道可视化

F-MGR-095 编排摘要（变量 / 数据集 / 工具）

F-MGR-096 外接实例发布与运行时（无 Pod）

F-MGR-097 部署失败归因与解决方案提示

二、Controller Backend（已并入 services/manager/app/worker）

2.1 引擎 Pod 生命周期

F-CTL-001 Agent Deploy

F-CTL-002 Agent Status

F-CTL-003 SUSPEND 空闲存档

F-CTL-004 RESUME 恢复

F-CTL-005 DESTROY 归档销毁

F-CTL-006 RESTART 滚动重启

F-CTL-007 部署进度 SSE

2.2 数据持久化与存储

F-CTL-010 PVC 持久化