去年我们团队在给公司做内部 AI 平台的时候碰到了一个挺现实的问题智库里的 agent 越接越多每个人都在往里面塞自己的工具包、技能包有的叫 plugin有的叫 skill有的是Excel 处理有的是爬虫脚本还有的是画架构图的。问题是这些东西上线之后完全不可控——更新没人管、冲突没人查、跑挂了没人知道。后来我们干脆做了一个带治理属性的 Skill 工具市场和动态沙箱热插拔平台把整个 Skill 从提交、审核、上架到运行隔离、版本切换、下架回收的流程彻底打通了。前端用的 Vue3后端用的是 FastAPI配套了 PRD、三端高保真源码和一块可视化大屏。这篇文章我把整个设计和实现过程拆开来讲包括为什么选这套技术栈、动态沙箱怎么做到热插拔、以及我在实际落地的时候踩过哪些坑希望对正在做类似内部工具平台的团队有参考价值。1. 项目整体设计与模块拆解1.1 先想清楚要解决什么问题很多团队做内部 AI 平台一开始都是“能跑就行”但跑着跑着问题就全冒出来了。就拿 Skill 来说它不像普通前端组件丢到 npm 上就结束了。Skill 是带着执行逻辑的后面连的是外部 API、数据库、甚至命令行工具。它真正的痛点有三个一是分发混乱。有人写了一个 skill 之后往群里丢个压缩包用完就没人维护了下一个同事根本不知道怎么用。二是运行不可控。Skill 的执行代码在主进程里直接跑一旦有死循环或者内存泄漏整个 agent 服务都跟着遭殃。三是更新全靠重启。新版本要生效就得重启服务这在企业场景下很难接受因为旁边还挂着很多线上任务。所以这个平台一开始就定了三条核心原则。第一Skill 要走全生命周期管理提交、审核、上架、下架、归档每一步都有状态记录。第二Skill 要在动态沙箱里运行不跟主服务共享进程。第三Skill 的版本更新要做成热插拔上线新版本的时候不影响老版本正在跑的任务。1.2 角色与权限怎么设计平台分了几类用户每一类看到的界面和能做的操作不一样。管理员负责全局治理能看到所有 Skill 的运行状态、资源消耗、版本迭代记录还能对异常 Skill 一键下线。普通用户是消费方可以进入 Skill 市场浏览、搜索、安装、调用也可以查看自己装的 Skill 的配额使用情况。开发者则是提交方上传 Skill 包之后能在开发者控制台看到审核进度、运行日志和沙箱测试结果。权限这块没有做太细粒度到按钮级别而是按“端”来切。管理后台、开发者控制台、监控大屏各自对应不同的 API Token 策略。后端在依赖注入层统一校验角色前端只是隐藏入口真正拦截还是靠后端。这一点在项目推进中建议强调给团队前端隐藏按钮只是体验优化不能作为安全边界。1.3 技术选型为什么是 Vue3 加 FastAPI前端的 Vue3 没有太多纠结。团队之前一直用 Vue2上 Vue3 最大的收益是组合式 API。这个项目的页面复杂度不低尤其是开发者控制台里的 Skill 编辑页一个页面要同时维护基本信息、参数 Schema、运行配置、测试用例四块内容。如果用 Options API逻辑会散在 data、methods、computed 各个地方互相之间要来回看。组合式 API 可以按业务模块来组织代码比如 useSkillManifest、useFileUpload、useSandboxTest每个文件负责一块完整领域复用性高很多。后端选 FastAPI 的原因就更直接了。它原生支持 Async对于 Skill 执行这类带有 IO 密集属性的场景非常合适。而且 FastAPI 基于 Pydantic在处理 Skill 这种“半结构化”的 manifest 配置时特别省心字段校验、嵌套模型、枚举约束都可以直接用类型声明不用再手写一大堆 if-else。再加上它自动生成的 OpenAPI 文档前端同学联调的时候可以直接对着文档找参数沟通成本降了不少。当然选 FastAPI 不是看不惯 Java 或者 Go。这个平台的核心逻辑在 Python 这边因为 Skill 本身多数就是用 Python 写的沙箱执行也要借助 Python 的生态比如 concurrency 控制、信号处理、subprocess 调用。用 FastAPI 让后端和 Skill 运行时处于同一个技术语境里很多事情处理起来会比较顺手。1.4 整体架构一句话讲明白这个项目可以分成四层。接入层是 Vue3 三端应用管理后台、开发者控制台、监控大屏统一通过 API 网关访问后端。控制层是 FastAPI 服务处理 Skill 的 CRUD、审核流、权限校验、配额管理。执行层是动态沙箱接收控制层的执行请求在隔离环境里运行 Skill 代码。数据层则是 PostgreSQL 存业务数据Redis 做缓存和实时状态记录Elasticsearch 存运行日志。核心思路是“市场管分发沙箱管运行热插拔管切换”。调用方不直接持有 Skill 的执行逻辑而是通过平台统一的分发器去调用。分发器根据当前版本号、灰度策略、资源配额动态决定把请求发给哪一个沙箱实例。2. 动态沙箱设计与热插拔机制实战2.1 为什么普通服务进程隔离挡不住问题最早的方案很简单像很多团队一样把每个 Skill 当成一个 Python 模块 import 进主进程。结果上线第一周就出事了。有个负责爬数据的 Skill内部用了 requests 且没有设置超时对方服务器响应很慢每个请求要卡 30 多秒直接占满了 asyncio 的事件循环。虽然 FastAPI 可以处理并发但 CPU 密集的死循环也会让主进程的响应速度明显下降。后来我们把 Skill 的执行挪到了子进程以为这样就安全了结果又踩坑。Python 的 subprocess 虽然隔离了进程空间但还是共享文件系统。那个 Skill 在处理一个临时文件时直接把同一目录下别的配置文件覆盖了。所以单纯的进程隔离不够还需要文件系统隔离、网络隔离、资源配额综合起来。2.2 沙箱技术方案容器和受限进程搭配使用我们的动态沙箱其实分了两套策略。对于官方维护的 Skill可信度高用受限子进程就够了。具体实现是用 Python 的 subprocess 启动独立进程在启动前通过 resource 模块设置 CPU 时间上限、内存上限同时配合 signal 机制在超时时强制杀掉进程。子进程的工作目录设置为一个临时目录每次执行完清理掉避免残留文件。对于第三方来源或标记为高风险的 Skill直接上 Docker 容器。每个 Skill 启动一个独立容器挂载只读代码目录数据目录用 volume 隔离网络默认 bridge 模式并限制出网。容器的镜像基础是 python:3.11-slim再预装一些通用依赖。每个容器有 CPU 和内存的 quota由平台侧的容器管理模块统一维护。容器冷启动比较慢我们就设计了一个“沙箱预热池”。常用的 Skill 容器保持在运行态需要执行的时候直接把任务塞进已有的容器避免了 docker run 的开销。不常用的容器在闲置超过 15 分钟后自动回收释放资源。注意沙箱隔离不是绝对的这里有一个权衡。我们允许官方 Skill 走轻量隔离是因为这些代码经过了代码评审和灰度测试第三方 Skill 一律容器隔离。建议在实现的时候把这两种方式做成可配置而不是写死在系统里这样后续可以根据 Skill 的来源或者评分动态调整执行策略。2.3 热插拔的实现原理注册表加版本切换热插拔的关键点在于“调用方不依赖具体实现只依赖接口协议”。实现上做了三个组件。第一个是Skill 注册中心。每一个 Skill 在数据库里有一条记录保存编号、名称、当前生效版本、可用版本列表、依赖声明、接口协议。注册中心同时维护一个内存态Redis 里存了一份活跃 Skill 的概要信息这样调度器查 Skill 的时候不用每次都打数据库。第二个是版本切换器。版本切换不是一个简单的“改了数据库就完事”因为正在运行的任务可能还在用旧版本。我们做了一个版本迁移机制当管理员将某个 Skill 的新版本切换为“当前版本”时系统会先查询这个 Skill 正在运行的实例数如果为零立即切换如果不为零标记新版本为“pending”让调度器优先调度新版本同时等待旧版本的任务自然结束。只有当旧版本的任务全部结束后才真正完成版本切换。第三个是回滚机制。这个必须要提前设计好别等到线上出问题再补。我们在版本记录表里保存了每个版本的 manifest 和代码快照。一旦新版本在灰度期间出现异常管理员可以一键将生效版本回退到上一个版本。回滚之后新版本的沙箱实例会被强制回收旧版本的预热实例被重新激活。2.4 资源治理与配额控制企业级环境中Skill 不能无限制调用。我们给每个开发者设置了配额每秒最大调用次数、每天最大 API 调用量、最大沙箱内存、最大单次执行时长。这些配额在 FastAPI 中间件里统一校验。同时在执行沙箱内部也会做一层限制防止回调绕过后端配额直接访问资源。比如在容器里设置了 pids-limit 防止 fork 炸弹使用 --memory 限制内存使用 --cpus 限制 CPU。这些配置都通过平台的管理界面设置不需要人工去写 docker 命令。顺带说一下 Redis 在这里的作用不只是缓存还承担了计数器职责。每次 Skill 调用在 Redis 里通过 INCR 增加计数配合 TTL 实现秒级窗口的限流。这样配额的校验不会给数据库带来压力。3. 用 Vue3 和 FastAPI 实现核心流程3.1 前端工程结构怎么组织前端不是简单的单页应用而是拆成了三个独立构建的子应用admin、dev、screen。它们共享一套组件库和 API 封装但路由和权限完全独立。这样的好处是构建速度更快监控大屏挂了不会影响管理后台。代码结构上通过 monorepo 来管理packages 下面有 shared、admin、dev、screen 四个包。shared 里放公共的 API 类型定义、工具函数、组件admin、dev、screen 各自维护独立的入口和路由。在 Vue3 项目里面比较值得说的是组合式 API 的实际收益。举一个具体例子Skill 编辑页结构上是基本信息表单、入参 Schema 编辑器、运行配置、测试记录四个区域。如果按照传统的 Vue2 写法这些数据都要放在 data 里methods 会越来越臃肿。我们改成把“编辑 Skill 的状态和逻辑”封装成 useSkillEditor把“测试运行”封装成 useSkillRunner。页面组件只负责把这两块的 UI 拼起来。后面要加新的功能比如“版本对比”只需要再写一个 useVersionCompare不碰原有逻辑。3.2 三端高保真源码里有哪些可复用的页面管理后台的 Skill 列表页有几个值得说的细节。表格用的是 Element Plus 的 ProTable 封装但重点在于表格列配置是用 schema 描述的后端的字段名一改前端只需要改一个配置文件。列表页的筛选区不是写死的而是根据当前的用户权限动态渲染。开发者只能看到自己的 Skill管理员可以看到全部。开发者控制台的“提交 Skill”流程比较复杂。第一步上传压缩包后端返回 manifest 解析结果第二步在页面上回显 Skill 的名称、描述、参数定义让开发者确认第三步填写资源申请期望的沙箱规格第四步提交审核。这个过程里前后端有多次交互如果写在一个提交按钮里面用户等待时间会特别长体验不好。我们把它做成了步骤条每步独立保存下次进入还可以继续编辑。监控大屏则用了 Vue3 加 ECharts。大屏中间是 Skill 运行状态的地图分布左侧是实时调用排行和异常 Top10右侧是资源配额使用率和沙箱容器健康度。大屏的数据不能靠轮询那样延迟高我们直接用 WebSocket 推送后端在沙箱监控模块采集到数据后实时推给前端。ECharts 实例的销毁这块也要重视大屏页面如果反复切换容易内存泄漏用 beforeUnmount 里调 dispose 可以解决。3.3 FastAPI 后端的关键接口实现后端的设计不复杂但有几个点值得展开。先看 Skill manifest 的定义。使用 Pydantic 建模确保上传的 Skill 包的格式是合法的from enum import Enum from typing import List, Optional, Dict, Any from pydantic import BaseModel, Field class SkillStatus(str, Enum): PENDING pending APPROVED approved REJECTED rejected ON_SHELF on_shelf OFF_SHELF off_shelf ARCHIVED archived class SkillManifest(BaseModel): name: str Field(..., min_length2, max_length64, descriptionSkill 唯一名称) display_name: str Field(..., max_length128) version: str Field(default1.0.0, patternr^\d\.\d\.\d$) description: Optional[str] None author: str entry_point: str Field(..., description入口函数如 main:run) dependencies: List[str] Field(default_factorylist) parameters_schema: Dict[str, Any] Field(default_factorydict) execution_timeout: int Field(default30, ge1, le600) memory_limit_mb: int Field(default512, ge64, le8192)上传接口接受的是上传文件然后解析压缩包内的 manifest.json如果格式不对直接返回 422。格式对了之后把文件存到对象存储同时写一条 pending 状态的记录进入审核队列router.post(/skills/upload) async def upload_skill( file: UploadFile File(...), user: User Depends(get_current_user), db: AsyncSession Depends(get_db) ): if not file.filename.endswith(.zip): raise HTTPException(status_code400, detail仅支持 zip 格式) content await file.read() manifest extract_and_validate_manifest(content) if manifest is None: raise HTTPException(status_code422, detailmanifest 解析失败) skill_id await skill_service.save_skill( dbdb, creator_iduser.id, manifestmanifest, package_datacontent ) return {skill_id: skill_id, status: SkillStatus.PENDING}运行时调用接口不会直接执行 Skill 里的代码而是先查注册中心拿到当前活跃版本的沙箱地址再把参数通过消息队列发给沙箱执行router.post(/skills/{skill_id}/execute) async def execute_skill( skill_id: str, payload: SkillInvocationPayload, user: User Depends(get_current_user), quota: QuotaChecker Depends(require_quota) ): active_route await registry_router.get_active_route(skill_id) if active_route.is_pending: raise HTTPException(status_code409, detailSkill 版本切换中请稍后重试) result await sandbox_dispatcher.dispatch( routeactive_route, payloadpayload.dict(), trace_idgenerate_trace_id() ) return result这里我建议使用 Pydantic 还做一层请求入参的校验。Skill 的 parameters_schema 由开发者定义但实际调用的时候这个 schema 没有经过代码编译而是存成 JSON 在数据库里。调用时的校验不能只信任前端也不能只信任数据库里的 schema必要时可以加一层“运行时校验默认值填充”。3.4 大屏和日志为什么用 SSE 而不是轮询Skill 执行是异步的前端的调试台需要实时看到运行日志。一开始我们用轮询每 2 秒拉一次结果任务多的时候数据库查询压力很大日志多的时候还有延迟。后来改成 SSEServer-Sent Events。FastAPI 集成了 EventSource 的支持实现起来很简单。前端用原生的 EventSource 就可以了不需要额外的库router.get(/skills/{skill_id}/logs) async def stream_task_logs(request: Request, skill_id: str): async def event_generator(): async for log_line in log_stream.subscribe(skill_id): if await request.is_disconnected(): break yield fdata: {log_line}\n\n return StreamingResponse( event_generator(), media_typetext/event-stream, headers{ Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no } )前端调用方式const eventSource new EventSource(/api/skills/${skillId}/logs); eventSource.onmessage (event) { const logLine JSON.parse(event.data); appendLogToConsole(logLine); };提示使用 SSE 的时候如果前端项目部署在 Nginx 后面记得在 Nginx 配置里关掉代理缓冲不然日志流会等攒够一批才推过来实时性会大打折扣。3.5 Skill 状态机设计Skill 的状态流转是治理功能的核心。我们从提交到下架完整定义了一个状态机状态描述允许的后续状态pending已提交待审核approved, rejectedapproved审核通过待上架on_shelf, rejectedon_shelf已上架可被调用off_shelf, archivedoff_shelf已下架不可调用on_shelf, archivedarchived已归档保留记录无rejected已驳回需要修改pending状态机的切换都用事务来保证。例如从 on_shelf 到 off_shelf操作的时候会先检查是否有正在运行的任务。如果还有任务在跑就先把状态标记为“下架中”等任务结束后再真正变成 off_shelf。这个过程没有做成定时任务而是在沙箱执行完成后的回调里检查。4. 常见问题与排查技巧实录4.1 沙箱容器启动太慢怎么办最开始每次执行 Skill 都要临时 docker run速度非常慢光是容器启动加依赖导入就要花 3 到 5 秒。后来做了两个优化。第一个是前面提到的预热池。把高频 Skill 的容器保持在运行状态新任务直接复用容器的标准输入输出通道。第二个是用持久化虚拟环境。容器退出的时候不删除 volume等下一次启动的时候可以直接用已经装好依赖的环境。这样大部分官方 Skill 的首次调用时间可以压到 1 秒以内。4.2 热插拔遇到“版本切换期间执行失败”有一次上线新版本管理员刚切换版本立刻就有好几个人报错说 Skill 调用失败。查了半天发现问题不是代码 bug而是旧版本的任务还没有跑完新版本又没完全生效调度器在切换期间返回了 409。虽然有重试机制但用户体验不好。后来在“切换版本”的交互上做了改进。切换动作本身需要二次确认并且弹窗里会显示当前正在运行的实例数。如果实例数大于零系统会显示“预计切换完成时间”让管理员明确知道这中间不是故障。同时后端优化了策略版本切换后旧实例还在跑的任务一定让它跑完但调度器会优先把新请求全部分给新版本不会出现同一个版本混用的情况。4.3 大屏图表内存泄漏大屏页面上图表很多刚开始测试的时候没发现问题等连续开了一晚上第二天页面已经卡得动不了。用 Chrome 的 Performance 面板一查发现 ECharts 实例没有被销毁。问题出在 Vue3 组件的 watch 逻辑。当图表配置变化的时候更新了 option但旧实例没有 dispose。因为大屏里的图表大多数是定时更新每次都新建实例旧实例就堆积成了泄漏。后来统一封装了一个 BaseChart 组件在 watch 回调里判断是否已有实例如果有先 dispose 或者直接用 setOption而不是重新 new。同时在组件的 onUnmounted 钩子里显式调用 dispose。4.4 SSE 连接频繁断开还在内网环境里测试的时候没有问题放到生产环境就发现 SSE 连接总是几十秒就断开。后来排查到是 Nginx 的 proxy_read_timeout 默认只有 60 秒。因为是长连接需要把这个值调大同时关闭缓冲。配置如下location /api/skills { proxy_pass http://backend_service; proxy_buffering off; proxy_read_timeout 3600s; proxy_set_header Connection ; proxy_http_version 1.1; chunked_transfer_encoding off; }这个坑比较隐蔽因为本地开发环境不经过 Nginx根本发现不了。4.5 权限校验不能只靠前端表单上根据用户角色隐藏了“下架”按钮看起来没问题但有人直接拿着接口请求尝试调用下架接口后端如果没有校验依然会成功。我们在 FastAPI 的依赖层统一写了 role_checker每个需要权限的接口都声明。def require_admin(user: User Depends(get_current_user)): if user.role ! UserRole.ADMIN: raise HTTPException(status_code403, detail需要管理员权限) return user不要抱着“公司内部系统应该不会有人乱来”的心态企业级系统就要按企业级标准来做。4.6 Python 沙箱超时后的“僵尸进程”处理子进程沙箱超时之后主进程把进程 kill 掉了但有时候子进程本身又开了一个孙进程kill 的只是直接子进程孙进程还在后台跑占用资源。解决办法是使用进程组。在创建 subprocess 的时候设置 start_new_sessionTrue超时之后直接 kill 掉整个进程组而不是只杀进程本身。import subprocess import signal proc subprocess.Popen( cmd, start_new_sessionTrue, stdoutsubprocess.PIPE, stderrsubprocess.PIPE ) try: stdout, stderr proc.communicate(timeout5) except subprocess.TimeoutExpired: os.killpg(proc.pid, signal.SIGKILL) proc.wait()认真讲这个问题不遇到一次基本想不到等线上出现资源悄悄耗尽的时候再查就晚了。5. 一些延伸经验和避坑心得5.1 Skill 包应该用什么格式我们最终统一为标准 zip 包里面强制包含 manifest.json 和入口代码目录。入口代码不要求一定是一个文件可以是一个完整的 Python 包但 manifest.json 里声明的 entry_point 必须是一个可导入的路径。在沙箱里执行之前后端的校验服务会把包解开把 entry_point 对应的函数加载出来做一次冒烟测试。这一点很建议做。很多“市场型”平台只做文件和索引不做冒烟测试结果 Skill 上架之后用户第一次调用就报“模块不存在”的错误。我们在审核环节就加上冒烟测试虽然审核时间会多几秒但能挡住大部分明显的问题。5.2 日志规范要从第一天做起Skill 的执行日志不能只写到控制台就算了。我们统一用 JSON 格式输出必须包含 skill_id、version、request_id、level、message、timestamp 这几个字段。日志统一打到 stdout由容器运行时收集到 Elasticsearch。前端调试台展示日志的时候也是按 request_id 聚合的。如果没有这个规范后续排查问题基本靠猜。5.3 灰度策略做到 Skill 维度版本热插拔虽然解决了“不停机更新”的问题但没有解决“新版有没有问题”的问题。如果新版刚上线不是立刻全量而是先让 5% 的请求走新版跑一段时间没有问题再逐步放量风险会小很多。我们的设计是支持多版本同时在线。当前版本可以有多个 active 版本每个版本配置权重。调度器在分发的时候根据权重随机选择版本。目前这个功能在管理后台已经能用但交互上还有优化空间比如权重调整后是否能通过一个横向滑动条直观改变百分比。5.4 关于 AI Agent Skill 的思考现在大家都在说 AI Agent 的 Skill 生态很多人在做“AI 自动挖掘漏洞 Skill”“去 AI 味 Skill”“宠物皮肤健康 AI Skill”这类东西。我的观点是工具本身的产品形态很重要但比工具更重要的是治理。如果企业内部有 100 个 Skill没有一套标准的管理平台最后一定会变成一团乱麻。我们的项目虽然叫“工具市场”本质上是给这个乱象画了一条线——“线”以下怎么提交、怎么审核线上面怎么运行、怎么切换。所以如果你也要做类似东西建议把更多的精力放在“生命周期管理”和“运行治理”上而不是纠结单个 Skill 效果的魔法参数。5.5 高保真原型和源码的时间分配这个项目在 PRD 和设计稿阶段花了不少时间现在回头看其实是值得的。三端高保真原型把交互细节都定好了开发阶段基本没有出现过“这里怎么跳转”这类问题。大屏设计则提前固定了数据字段和更新频率后端接口开发时就预留了对齐的数据结构。比较有经验的做法的建议是高保真并不能替代后端架构设计但它能逼着产品经理把细节想清楚。比如 Skill 的版本回滚需要哪些按钮沙箱测试的按钮是否根据状态置灰这些细节如果等到开发阶段才让前端临场发挥大概率会不一致。最后再分享两个小技巧在真实开发过程中总会有一些零碎的小技巧很容易被忽略。一个是 Vue3 大屏加 ECharts 的响应式问题。如果直接用 window.resize 事件去触发布局变化在高密度屏下会很卡。我建议用 ResizeObserver 监听图表容器的大小变化只在容器尺寸确实变化的时候才去 setOption。另一个是 FastAPI 里上传大文件的时候不要用 UploadFile 直接读全部内容到内存应该改成流式写入到临时文件避免大 Skill 包把 worker 的内存打满。做这个平台最大的感受就是企业级系统没有那么多奇技淫巧更多是把最基础的事情做到有规范、有记录、可回滚。动态沙箱、热插拔这些词听起来很高级但拆开了看无非就是先“分而治之”再“按版本切换”最后“有能力回退”。希望这些设计思路和踩坑记录对正在做类似项目的你有实际帮助。
去年我们团队在给公司做内部 AI 平台的时候碰到了一个挺现实的问题智库里的 agent 越接越多每个人都在往里面塞自己的工具包、技能包有的叫 plugin有的叫 skill有的是Excel 处理有的是爬虫脚本还有的是画架构图的。问题是这些东西上线之后完全不可控——更新没人管、冲突没人查、跑挂了没人知道。后来我们干脆做了一个带治理属性的 Skill 工具市场和动态沙箱热插拔平台把整个 Skill 从提交、审核、上架到运行隔离、版本切换、下架回收的流程彻底打通了。前端用的 Vue3后端用的是 FastAPI配套了 PRD、三端高保真源码和一块可视化大屏。这篇文章我把整个设计和实现过程拆开来讲包括为什么选这套技术栈、动态沙箱怎么做到热插拔、以及我在实际落地的时候踩过哪些坑希望对正在做类似内部工具平台的团队有参考价值。1. 项目整体设计与模块拆解1.1 先想清楚要解决什么问题很多团队做内部 AI 平台一开始都是“能跑就行”但跑着跑着问题就全冒出来了。就拿 Skill 来说它不像普通前端组件丢到 npm 上就结束了。Skill 是带着执行逻辑的后面连的是外部 API、数据库、甚至命令行工具。它真正的痛点有三个一是分发混乱。有人写了一个 skill 之后往群里丢个压缩包用完就没人维护了下一个同事根本不知道怎么用。二是运行不可控。Skill 的执行代码在主进程里直接跑一旦有死循环或者内存泄漏整个 agent 服务都跟着遭殃。三是更新全靠重启。新版本要生效就得重启服务这在企业场景下很难接受因为旁边还挂着很多线上任务。所以这个平台一开始就定了三条核心原则。第一Skill 要走全生命周期管理提交、审核、上架、下架、归档每一步都有状态记录。第二Skill 要在动态沙箱里运行不跟主服务共享进程。第三Skill 的版本更新要做成热插拔上线新版本的时候不影响老版本正在跑的任务。1.2 角色与权限怎么设计平台分了几类用户每一类看到的界面和能做的操作不一样。管理员负责全局治理能看到所有 Skill 的运行状态、资源消耗、版本迭代记录还能对异常 Skill 一键下线。普通用户是消费方可以进入 Skill 市场浏览、搜索、安装、调用也可以查看自己装的 Skill 的配额使用情况。开发者则是提交方上传 Skill 包之后能在开发者控制台看到审核进度、运行日志和沙箱测试结果。权限这块没有做太细粒度到按钮级别而是按“端”来切。管理后台、开发者控制台、监控大屏各自对应不同的 API Token 策略。后端在依赖注入层统一校验角色前端只是隐藏入口真正拦截还是靠后端。这一点在项目推进中建议强调给团队前端隐藏按钮只是体验优化不能作为安全边界。1.3 技术选型为什么是 Vue3 加 FastAPI前端的 Vue3 没有太多纠结。团队之前一直用 Vue2上 Vue3 最大的收益是组合式 API。这个项目的页面复杂度不低尤其是开发者控制台里的 Skill 编辑页一个页面要同时维护基本信息、参数 Schema、运行配置、测试用例四块内容。如果用 Options API逻辑会散在 data、methods、computed 各个地方互相之间要来回看。组合式 API 可以按业务模块来组织代码比如 useSkillManifest、useFileUpload、useSandboxTest每个文件负责一块完整领域复用性高很多。后端选 FastAPI 的原因就更直接了。它原生支持 Async对于 Skill 执行这类带有 IO 密集属性的场景非常合适。而且 FastAPI 基于 Pydantic在处理 Skill 这种“半结构化”的 manifest 配置时特别省心字段校验、嵌套模型、枚举约束都可以直接用类型声明不用再手写一大堆 if-else。再加上它自动生成的 OpenAPI 文档前端同学联调的时候可以直接对着文档找参数沟通成本降了不少。当然选 FastAPI 不是看不惯 Java 或者 Go。这个平台的核心逻辑在 Python 这边因为 Skill 本身多数就是用 Python 写的沙箱执行也要借助 Python 的生态比如 concurrency 控制、信号处理、subprocess 调用。用 FastAPI 让后端和 Skill 运行时处于同一个技术语境里很多事情处理起来会比较顺手。1.4 整体架构一句话讲明白这个项目可以分成四层。接入层是 Vue3 三端应用管理后台、开发者控制台、监控大屏统一通过 API 网关访问后端。控制层是 FastAPI 服务处理 Skill 的 CRUD、审核流、权限校验、配额管理。执行层是动态沙箱接收控制层的执行请求在隔离环境里运行 Skill 代码。数据层则是 PostgreSQL 存业务数据Redis 做缓存和实时状态记录Elasticsearch 存运行日志。核心思路是“市场管分发沙箱管运行热插拔管切换”。调用方不直接持有 Skill 的执行逻辑而是通过平台统一的分发器去调用。分发器根据当前版本号、灰度策略、资源配额动态决定把请求发给哪一个沙箱实例。2. 动态沙箱设计与热插拔机制实战2.1 为什么普通服务进程隔离挡不住问题最早的方案很简单像很多团队一样把每个 Skill 当成一个 Python 模块 import 进主进程。结果上线第一周就出事了。有个负责爬数据的 Skill内部用了 requests 且没有设置超时对方服务器响应很慢每个请求要卡 30 多秒直接占满了 asyncio 的事件循环。虽然 FastAPI 可以处理并发但 CPU 密集的死循环也会让主进程的响应速度明显下降。后来我们把 Skill 的执行挪到了子进程以为这样就安全了结果又踩坑。Python 的 subprocess 虽然隔离了进程空间但还是共享文件系统。那个 Skill 在处理一个临时文件时直接把同一目录下别的配置文件覆盖了。所以单纯的进程隔离不够还需要文件系统隔离、网络隔离、资源配额综合起来。2.2 沙箱技术方案容器和受限进程搭配使用我们的动态沙箱其实分了两套策略。对于官方维护的 Skill可信度高用受限子进程就够了。具体实现是用 Python 的 subprocess 启动独立进程在启动前通过 resource 模块设置 CPU 时间上限、内存上限同时配合 signal 机制在超时时强制杀掉进程。子进程的工作目录设置为一个临时目录每次执行完清理掉避免残留文件。对于第三方来源或标记为高风险的 Skill直接上 Docker 容器。每个 Skill 启动一个独立容器挂载只读代码目录数据目录用 volume 隔离网络默认 bridge 模式并限制出网。容器的镜像基础是 python:3.11-slim再预装一些通用依赖。每个容器有 CPU 和内存的 quota由平台侧的容器管理模块统一维护。容器冷启动比较慢我们就设计了一个“沙箱预热池”。常用的 Skill 容器保持在运行态需要执行的时候直接把任务塞进已有的容器避免了 docker run 的开销。不常用的容器在闲置超过 15 分钟后自动回收释放资源。注意沙箱隔离不是绝对的这里有一个权衡。我们允许官方 Skill 走轻量隔离是因为这些代码经过了代码评审和灰度测试第三方 Skill 一律容器隔离。建议在实现的时候把这两种方式做成可配置而不是写死在系统里这样后续可以根据 Skill 的来源或者评分动态调整执行策略。2.3 热插拔的实现原理注册表加版本切换热插拔的关键点在于“调用方不依赖具体实现只依赖接口协议”。实现上做了三个组件。第一个是Skill 注册中心。每一个 Skill 在数据库里有一条记录保存编号、名称、当前生效版本、可用版本列表、依赖声明、接口协议。注册中心同时维护一个内存态Redis 里存了一份活跃 Skill 的概要信息这样调度器查 Skill 的时候不用每次都打数据库。第二个是版本切换器。版本切换不是一个简单的“改了数据库就完事”因为正在运行的任务可能还在用旧版本。我们做了一个版本迁移机制当管理员将某个 Skill 的新版本切换为“当前版本”时系统会先查询这个 Skill 正在运行的实例数如果为零立即切换如果不为零标记新版本为“pending”让调度器优先调度新版本同时等待旧版本的任务自然结束。只有当旧版本的任务全部结束后才真正完成版本切换。第三个是回滚机制。这个必须要提前设计好别等到线上出问题再补。我们在版本记录表里保存了每个版本的 manifest 和代码快照。一旦新版本在灰度期间出现异常管理员可以一键将生效版本回退到上一个版本。回滚之后新版本的沙箱实例会被强制回收旧版本的预热实例被重新激活。2.4 资源治理与配额控制企业级环境中Skill 不能无限制调用。我们给每个开发者设置了配额每秒最大调用次数、每天最大 API 调用量、最大沙箱内存、最大单次执行时长。这些配额在 FastAPI 中间件里统一校验。同时在执行沙箱内部也会做一层限制防止回调绕过后端配额直接访问资源。比如在容器里设置了 pids-limit 防止 fork 炸弹使用 --memory 限制内存使用 --cpus 限制 CPU。这些配置都通过平台的管理界面设置不需要人工去写 docker 命令。顺带说一下 Redis 在这里的作用不只是缓存还承担了计数器职责。每次 Skill 调用在 Redis 里通过 INCR 增加计数配合 TTL 实现秒级窗口的限流。这样配额的校验不会给数据库带来压力。3. 用 Vue3 和 FastAPI 实现核心流程3.1 前端工程结构怎么组织前端不是简单的单页应用而是拆成了三个独立构建的子应用admin、dev、screen。它们共享一套组件库和 API 封装但路由和权限完全独立。这样的好处是构建速度更快监控大屏挂了不会影响管理后台。代码结构上通过 monorepo 来管理packages 下面有 shared、admin、dev、screen 四个包。shared 里放公共的 API 类型定义、工具函数、组件admin、dev、screen 各自维护独立的入口和路由。在 Vue3 项目里面比较值得说的是组合式 API 的实际收益。举一个具体例子Skill 编辑页结构上是基本信息表单、入参 Schema 编辑器、运行配置、测试记录四个区域。如果按照传统的 Vue2 写法这些数据都要放在 data 里methods 会越来越臃肿。我们改成把“编辑 Skill 的状态和逻辑”封装成 useSkillEditor把“测试运行”封装成 useSkillRunner。页面组件只负责把这两块的 UI 拼起来。后面要加新的功能比如“版本对比”只需要再写一个 useVersionCompare不碰原有逻辑。3.2 三端高保真源码里有哪些可复用的页面管理后台的 Skill 列表页有几个值得说的细节。表格用的是 Element Plus 的 ProTable 封装但重点在于表格列配置是用 schema 描述的后端的字段名一改前端只需要改一个配置文件。列表页的筛选区不是写死的而是根据当前的用户权限动态渲染。开发者只能看到自己的 Skill管理员可以看到全部。开发者控制台的“提交 Skill”流程比较复杂。第一步上传压缩包后端返回 manifest 解析结果第二步在页面上回显 Skill 的名称、描述、参数定义让开发者确认第三步填写资源申请期望的沙箱规格第四步提交审核。这个过程里前后端有多次交互如果写在一个提交按钮里面用户等待时间会特别长体验不好。我们把它做成了步骤条每步独立保存下次进入还可以继续编辑。监控大屏则用了 Vue3 加 ECharts。大屏中间是 Skill 运行状态的地图分布左侧是实时调用排行和异常 Top10右侧是资源配额使用率和沙箱容器健康度。大屏的数据不能靠轮询那样延迟高我们直接用 WebSocket 推送后端在沙箱监控模块采集到数据后实时推给前端。ECharts 实例的销毁这块也要重视大屏页面如果反复切换容易内存泄漏用 beforeUnmount 里调 dispose 可以解决。3.3 FastAPI 后端的关键接口实现后端的设计不复杂但有几个点值得展开。先看 Skill manifest 的定义。使用 Pydantic 建模确保上传的 Skill 包的格式是合法的from enum import Enum from typing import List, Optional, Dict, Any from pydantic import BaseModel, Field class SkillStatus(str, Enum): PENDING pending APPROVED approved REJECTED rejected ON_SHELF on_shelf OFF_SHELF off_shelf ARCHIVED archived class SkillManifest(BaseModel): name: str Field(..., min_length2, max_length64, descriptionSkill 唯一名称) display_name: str Field(..., max_length128) version: str Field(default1.0.0, patternr^\d\.\d\.\d$) description: Optional[str] None author: str entry_point: str Field(..., description入口函数如 main:run) dependencies: List[str] Field(default_factorylist) parameters_schema: Dict[str, Any] Field(default_factorydict) execution_timeout: int Field(default30, ge1, le600) memory_limit_mb: int Field(default512, ge64, le8192)上传接口接受的是上传文件然后解析压缩包内的 manifest.json如果格式不对直接返回 422。格式对了之后把文件存到对象存储同时写一条 pending 状态的记录进入审核队列router.post(/skills/upload) async def upload_skill( file: UploadFile File(...), user: User Depends(get_current_user), db: AsyncSession Depends(get_db) ): if not file.filename.endswith(.zip): raise HTTPException(status_code400, detail仅支持 zip 格式) content await file.read() manifest extract_and_validate_manifest(content) if manifest is None: raise HTTPException(status_code422, detailmanifest 解析失败) skill_id await skill_service.save_skill( dbdb, creator_iduser.id, manifestmanifest, package_datacontent ) return {skill_id: skill_id, status: SkillStatus.PENDING}运行时调用接口不会直接执行 Skill 里的代码而是先查注册中心拿到当前活跃版本的沙箱地址再把参数通过消息队列发给沙箱执行router.post(/skills/{skill_id}/execute) async def execute_skill( skill_id: str, payload: SkillInvocationPayload, user: User Depends(get_current_user), quota: QuotaChecker Depends(require_quota) ): active_route await registry_router.get_active_route(skill_id) if active_route.is_pending: raise HTTPException(status_code409, detailSkill 版本切换中请稍后重试) result await sandbox_dispatcher.dispatch( routeactive_route, payloadpayload.dict(), trace_idgenerate_trace_id() ) return result这里我建议使用 Pydantic 还做一层请求入参的校验。Skill 的 parameters_schema 由开发者定义但实际调用的时候这个 schema 没有经过代码编译而是存成 JSON 在数据库里。调用时的校验不能只信任前端也不能只信任数据库里的 schema必要时可以加一层“运行时校验默认值填充”。3.4 大屏和日志为什么用 SSE 而不是轮询Skill 执行是异步的前端的调试台需要实时看到运行日志。一开始我们用轮询每 2 秒拉一次结果任务多的时候数据库查询压力很大日志多的时候还有延迟。后来改成 SSEServer-Sent Events。FastAPI 集成了 EventSource 的支持实现起来很简单。前端用原生的 EventSource 就可以了不需要额外的库router.get(/skills/{skill_id}/logs) async def stream_task_logs(request: Request, skill_id: str): async def event_generator(): async for log_line in log_stream.subscribe(skill_id): if await request.is_disconnected(): break yield fdata: {log_line}\n\n return StreamingResponse( event_generator(), media_typetext/event-stream, headers{ Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no } )前端调用方式const eventSource new EventSource(/api/skills/${skillId}/logs); eventSource.onmessage (event) { const logLine JSON.parse(event.data); appendLogToConsole(logLine); };提示使用 SSE 的时候如果前端项目部署在 Nginx 后面记得在 Nginx 配置里关掉代理缓冲不然日志流会等攒够一批才推过来实时性会大打折扣。3.5 Skill 状态机设计Skill 的状态流转是治理功能的核心。我们从提交到下架完整定义了一个状态机状态描述允许的后续状态pending已提交待审核approved, rejectedapproved审核通过待上架on_shelf, rejectedon_shelf已上架可被调用off_shelf, archivedoff_shelf已下架不可调用on_shelf, archivedarchived已归档保留记录无rejected已驳回需要修改pending状态机的切换都用事务来保证。例如从 on_shelf 到 off_shelf操作的时候会先检查是否有正在运行的任务。如果还有任务在跑就先把状态标记为“下架中”等任务结束后再真正变成 off_shelf。这个过程没有做成定时任务而是在沙箱执行完成后的回调里检查。4. 常见问题与排查技巧实录4.1 沙箱容器启动太慢怎么办最开始每次执行 Skill 都要临时 docker run速度非常慢光是容器启动加依赖导入就要花 3 到 5 秒。后来做了两个优化。第一个是前面提到的预热池。把高频 Skill 的容器保持在运行状态新任务直接复用容器的标准输入输出通道。第二个是用持久化虚拟环境。容器退出的时候不删除 volume等下一次启动的时候可以直接用已经装好依赖的环境。这样大部分官方 Skill 的首次调用时间可以压到 1 秒以内。4.2 热插拔遇到“版本切换期间执行失败”有一次上线新版本管理员刚切换版本立刻就有好几个人报错说 Skill 调用失败。查了半天发现问题不是代码 bug而是旧版本的任务还没有跑完新版本又没完全生效调度器在切换期间返回了 409。虽然有重试机制但用户体验不好。后来在“切换版本”的交互上做了改进。切换动作本身需要二次确认并且弹窗里会显示当前正在运行的实例数。如果实例数大于零系统会显示“预计切换完成时间”让管理员明确知道这中间不是故障。同时后端优化了策略版本切换后旧实例还在跑的任务一定让它跑完但调度器会优先把新请求全部分给新版本不会出现同一个版本混用的情况。4.3 大屏图表内存泄漏大屏页面上图表很多刚开始测试的时候没发现问题等连续开了一晚上第二天页面已经卡得动不了。用 Chrome 的 Performance 面板一查发现 ECharts 实例没有被销毁。问题出在 Vue3 组件的 watch 逻辑。当图表配置变化的时候更新了 option但旧实例没有 dispose。因为大屏里的图表大多数是定时更新每次都新建实例旧实例就堆积成了泄漏。后来统一封装了一个 BaseChart 组件在 watch 回调里判断是否已有实例如果有先 dispose 或者直接用 setOption而不是重新 new。同时在组件的 onUnmounted 钩子里显式调用 dispose。4.4 SSE 连接频繁断开还在内网环境里测试的时候没有问题放到生产环境就发现 SSE 连接总是几十秒就断开。后来排查到是 Nginx 的 proxy_read_timeout 默认只有 60 秒。因为是长连接需要把这个值调大同时关闭缓冲。配置如下location /api/skills { proxy_pass http://backend_service; proxy_buffering off; proxy_read_timeout 3600s; proxy_set_header Connection ; proxy_http_version 1.1; chunked_transfer_encoding off; }这个坑比较隐蔽因为本地开发环境不经过 Nginx根本发现不了。4.5 权限校验不能只靠前端表单上根据用户角色隐藏了“下架”按钮看起来没问题但有人直接拿着接口请求尝试调用下架接口后端如果没有校验依然会成功。我们在 FastAPI 的依赖层统一写了 role_checker每个需要权限的接口都声明。def require_admin(user: User Depends(get_current_user)): if user.role ! UserRole.ADMIN: raise HTTPException(status_code403, detail需要管理员权限) return user不要抱着“公司内部系统应该不会有人乱来”的心态企业级系统就要按企业级标准来做。4.6 Python 沙箱超时后的“僵尸进程”处理子进程沙箱超时之后主进程把进程 kill 掉了但有时候子进程本身又开了一个孙进程kill 的只是直接子进程孙进程还在后台跑占用资源。解决办法是使用进程组。在创建 subprocess 的时候设置 start_new_sessionTrue超时之后直接 kill 掉整个进程组而不是只杀进程本身。import subprocess import signal proc subprocess.Popen( cmd, start_new_sessionTrue, stdoutsubprocess.PIPE, stderrsubprocess.PIPE ) try: stdout, stderr proc.communicate(timeout5) except subprocess.TimeoutExpired: os.killpg(proc.pid, signal.SIGKILL) proc.wait()认真讲这个问题不遇到一次基本想不到等线上出现资源悄悄耗尽的时候再查就晚了。5. 一些延伸经验和避坑心得5.1 Skill 包应该用什么格式我们最终统一为标准 zip 包里面强制包含 manifest.json 和入口代码目录。入口代码不要求一定是一个文件可以是一个完整的 Python 包但 manifest.json 里声明的 entry_point 必须是一个可导入的路径。在沙箱里执行之前后端的校验服务会把包解开把 entry_point 对应的函数加载出来做一次冒烟测试。这一点很建议做。很多“市场型”平台只做文件和索引不做冒烟测试结果 Skill 上架之后用户第一次调用就报“模块不存在”的错误。我们在审核环节就加上冒烟测试虽然审核时间会多几秒但能挡住大部分明显的问题。5.2 日志规范要从第一天做起Skill 的执行日志不能只写到控制台就算了。我们统一用 JSON 格式输出必须包含 skill_id、version、request_id、level、message、timestamp 这几个字段。日志统一打到 stdout由容器运行时收集到 Elasticsearch。前端调试台展示日志的时候也是按 request_id 聚合的。如果没有这个规范后续排查问题基本靠猜。5.3 灰度策略做到 Skill 维度版本热插拔虽然解决了“不停机更新”的问题但没有解决“新版有没有问题”的问题。如果新版刚上线不是立刻全量而是先让 5% 的请求走新版跑一段时间没有问题再逐步放量风险会小很多。我们的设计是支持多版本同时在线。当前版本可以有多个 active 版本每个版本配置权重。调度器在分发的时候根据权重随机选择版本。目前这个功能在管理后台已经能用但交互上还有优化空间比如权重调整后是否能通过一个横向滑动条直观改变百分比。5.4 关于 AI Agent Skill 的思考现在大家都在说 AI Agent 的 Skill 生态很多人在做“AI 自动挖掘漏洞 Skill”“去 AI 味 Skill”“宠物皮肤健康 AI Skill”这类东西。我的观点是工具本身的产品形态很重要但比工具更重要的是治理。如果企业内部有 100 个 Skill没有一套标准的管理平台最后一定会变成一团乱麻。我们的项目虽然叫“工具市场”本质上是给这个乱象画了一条线——“线”以下怎么提交、怎么审核线上面怎么运行、怎么切换。所以如果你也要做类似东西建议把更多的精力放在“生命周期管理”和“运行治理”上而不是纠结单个 Skill 效果的魔法参数。5.5 高保真原型和源码的时间分配这个项目在 PRD 和设计稿阶段花了不少时间现在回头看其实是值得的。三端高保真原型把交互细节都定好了开发阶段基本没有出现过“这里怎么跳转”这类问题。大屏设计则提前固定了数据字段和更新频率后端接口开发时就预留了对齐的数据结构。比较有经验的做法的建议是高保真并不能替代后端架构设计但它能逼着产品经理把细节想清楚。比如 Skill 的版本回滚需要哪些按钮沙箱测试的按钮是否根据状态置灰这些细节如果等到开发阶段才让前端临场发挥大概率会不一致。最后再分享两个小技巧在真实开发过程中总会有一些零碎的小技巧很容易被忽略。一个是 Vue3 大屏加 ECharts 的响应式问题。如果直接用 window.resize 事件去触发布局变化在高密度屏下会很卡。我建议用 ResizeObserver 监听图表容器的大小变化只在容器尺寸确实变化的时候才去 setOption。另一个是 FastAPI 里上传大文件的时候不要用 UploadFile 直接读全部内容到内存应该改成流式写入到临时文件避免大 Skill 包把 worker 的内存打满。做这个平台最大的感受就是企业级系统没有那么多奇技淫巧更多是把最基础的事情做到有规范、有记录、可回滚。动态沙箱、热插拔这些词听起来很高级但拆开了看无非就是先“分而治之”再“按版本切换”最后“有能力回退”。希望这些设计思路和踩坑记录对正在做类似项目的你有实际帮助。
