Nacos AgentSpec 规范详解AI 智能体规范包的标识、版本模型与运行时条件监听协议【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos本篇基于 Nacos 仓库中的 AgentSpec 规范文档系统拆解 AI Registry 中 AgentSpec 资源的完整契约从namespaceId - agentspec - name的标识模型、以manifest.json为核心的 ZIP 包结构与上传安全校验到版本存储 provider 持久化、草稿替换的原子性语义、共享搜索 Facade再到客户端基于 MD5/ETag 的条件轮询协议与授权资源解析规则。读完后你可以准确实现一个对接 Nacos AgentSpec 的运行时加载器并理解各管理端点的行为边界与底层实现依据。1. 资源标识namespaceId → agentspec → nameAgentSpec 在 Nacos AI Registry 中的身份由三级坐标唯一确定namespaceId - agentspec - name其中name不是用户随意填写的参数而是从 AgentSpec 包内的manifest.json中读取的稳定资源名。这一设计决定了 AgentSpec 的“名称主权”归属于包本身上传 ZIP 时解析器会从 manifest 中提取资源名并以此建立资源条目而非以 HTTP 参数为准。在实现层面name的提取逻辑位于 AgentSpecZipParser.parseManifest()解析器读取 manifest 根对象中的worker.suggested_name字段若该字段缺失或为空白直接抛出参数缺失错误worker.suggested_name is required in manifest.json并将该值 trim 后设为资源名。同时还会顺带提取description资源描述与tags/bizTags业务标签列表或字符串两种形态均支持列表会被归一化为 JSON 数组字符串。默认命名空间常量为public见 Constants.AgentSpecs 中的AGENTSPEC_DEFAULT_NAMESPACE。2. 包模型manifest.json 资源文件 元数据一个 AgentSpec 是一个带版本的智能体规范包规范要求其包含manifest.json作为主描述文件main descriptor可选的资源文件例如智能体指令文件或带类型的资产文件元数据如 description、业务标签biz tags、owner、scope、labels、version 与下载计数。2.1 上传入口与 ZIP 契约上传接受ZIP 归档对应管理端点POST /v3/admin/ai/agentspecs/uploadmultipart/form-data入口实现在 AgentSpecAdminController.uploadAgentSpec()支持参数参数说明namespaceId命名空间缺省时按 Nacos 规则处理为默认命名空间overwrite是否覆盖同名已有草稿默认falsefileAgentSpec ZIP 文件该端点自 3.2.0 版本引入Since(3.2.0)要求 WRITE 权限、AIsign type、ADMIN_API 类型。规范要求“解析器必须在写入版本前校验 manifest 与资源引用”。AgentSpecZipParser 实现了这一约束其校验与解析规则包括1manifest.json 定位既接受 ZIP 根目录的manifest.json也接受子目录下的*/manifest.json找不到则报manifest.json file not found in zip。manifest 内容同时作为 AgentSpec 的content字段整体保存。2资源文件映射除manifest.json外其余条目都转换为AgentSpecResource。顶层文件如Dockerfile、tool-analysis.json会被赋予特定 typedockerfile、tool-analysis见determineResourceType()子目录文件以目录路径作为 type、文件名作为 name资源 key 由type/name组合生成AgentSpecUtils.generateResourceId(type, resourceName)。文本文件以 UTF-8 保存二进制文件如.ttf、.png做 Base64 编码并在 resource metadata 中标记encodingbase64。3噪声过滤macOS 打包产生的__MACOSX/目录、.DS_Store文件与._前缀的 AppleDouble 资源叉文件都会被过滤避免污染资源索引。4安全硬校验这是规范“写入前必须校验”的关键落地防御项规则可配置属性默认值压缩包大小上限拒绝超限 ZIPnacos.ai.agentspec.zip.max-upload-size-mb50 MB条目数量上限防条目洪泛攻击nacos.ai.agentspec.zip.max-entries500解压后总大小上限防 Zip Bombnacos.ai.agentspec.zip.max-uncompressed-size-mb50 MB路径穿越拒绝..与绝对路径条目SkillUtils.validatePathSafety—强制这些上限默认值定义在 Constants.AgentSpecsMAX_UPLOAD_ZIP_BYTES 50MB与 AgentSpecZipParser运营者可通过上述三个属性调高上限但注意非正数值会被静默忽略并回退默认值防止误配置“悄悄禁用”安全护栏见resolvePositiveIntProperty()。解压使用 Apache Commons Compress 的ZipArchiveInputStream并开启严格校验以兼容带 data descriptor 的 STORED 条目。3. 版本模型持久化存储 provider 与草稿替换语义AgentSpec 复用标准ai_resource/ai_resource_version资源模型manifest.json与资源文件统一走 AI 存储AI storage能力。从源码结构看默认存储实现为 NacosConfigAiResourceStorage即nacos_configprovider资源以agentspec_前缀的 group 组织AGENTSPEC_GROUP_PREFIX主数据 dataId 即manifest.jsonAGENTSPEC_MAIN_DATA_ID。规范中有三条值得展开的契约细节1每个版本描述符持久化其选定的存储 provider。读、草稿替换、删除一律使用该版本持久化时记录的 provider而“生效的 provider 配置”只影响新写入的版本。这样在集群从一种存储切换到另一种存储例如从nacos_config切到对象存储插件时存量版本仍可被正确读取。provider 键本身也可配置nacos.ai.agentspec.storage.providerAGENTSPEC_STORAGE_PROVIDER_CONFIG_KEY。没有记录 provider 的遗留描述符一律按nacos_config处理。2更新/覆盖草稿是“整包替换”且清理失败必须整体回退。规范规定的替换顺序是先把替换包中的资源文件写入存储再删除“旧manifest.json引用过、但新包中没有”的资源文件通过该版本持久化的 provider 执行删除最后持久化新的manifest.json与存储描述符。若第 2 步清理失败本次更新必须失败并保留旧的 manifest 与描述符使清理可以重试。这一顺序保证了任何中间状态下客户端读到的 manifest 与资源文件集合始终自洽——不会出现 manifest 引用了已被删除的资源。3AgentSpec 不维护独立的 manifest 索引。与 Skill 不同AgentSpec 的版本元数据与存储指针本身就是权威数据authoritative不需要额外的索引表做二级查询。4. 搜索共享索引 资源专属 Facade规范将 AgentSpec 纳入通用 AI Resource Search同时提供resourceTypeagentspec固定的资源专属搜索 Facade。两者复用 AI Resource Search Spec 中定义的 document/chunk/facet 模型、时效性currentness、可见性visibility与分页语义。索引投影由 AgentSpecSearchIndexProjector 与 AgentSpecAiResourceSearchTypeHandler 实现规范明确了投影范围进入索引最新 online 版本的 name、description、业务标签、公开依赖public dependencies与能力描述禁止进入索引包含凭据credentials或私有运行时数值的资源内容不得进入 chunk——这是一条安全底线避免敏感信息泄露到检索层。迁移约束同样明确既有的关键词分页式 Client Search 迁移到该 Facade 后不得在共享索引分页之后再二次过滤否则会造成页内结果缺失限定到 AgentSpec 的通用搜索与资源专属搜索具有相同的候选资格判定。客户端搜索端点为GET /v3/client/ai/agentspecs/search见 AgentSpecClientController.search()3.2.0 引入READ AIsign type OPEN_API。其参数契约由 AgentSpecSearchForm 与父类 AiResourcePageSearchForm 共同定义参数说明校验keyword关键词长度不超过 1024 字符query结构化查询文本长度不超过 1024 字符tagsAll可重复的业务标签过滤AND 语义去空白、去重后不超过 32 个pageNo/pageSize分页参数由PageForm校验namespaceId命名空间经NamespaceUtil归一化并校验返回ResultPageAgentSpecBasicInfo只暴露运行时检索所需的基础信息而非完整包内容。5. 生命周期draft → submit → publishAgentSpec 遵循共享的 AI Resource Lifecycle Spec允许的操作集合为上传或创建草稿、更新草稿、通过发布流水线或直接发布提交草稿/已评审版本对 reviewing 版本的 submit 幂等、发布、强制发布、更新 labels、更新业务标签、更新 scope、上下线、删除。版本编号可采用“简单生成的版本”或“显式目标版本”但类型特定实现必须拒绝重复版本号。这些操作与管理端点一一对应完整清单均以 AgentSpecAdminController 为准基路径/v3/admin/ai/agentspecs方法路径引入版本说明GET详情3.2.0管理端详情含版本治理信息与全部版本摘要GET/version3.2.0指定版本完整内容GET/version/meta3.2.1版本元数据主内容 资源清单仅 name/type跳过资源文件 IODELETE3.2.0删除整个 AgentSpecGET/list3.2.1管理端分页列表含 status/tags/labels 等治理元数据POST/upload3.2.0上传 ZIPmultipartPOST/draft3.2.0基于basedOnVersion创建草稿可指定targetVersionPUT/draft3.2.0整包替换当前草稿内容DELETE/draft3.2.0删除当前草稿版本POST/submit3.2.0提交版本进入流水线评审POST/publish3.2.0发布已评审版本POST/force-publish3.2.1绕过流水线校验强制发布接受 draft/reviewing/reviewed仅管理员可调用对.../force-publish路径单独做资源级鉴权POST/redraft3.2.2将已评审版本退回 draft 重新编辑PUT/labels3.2.0更新运行时路由 labelsJSON 字符串解析为 Map不改变版本状态PUT/biz-tags3.2.0更新业务标签不改变版本状态POST/online3.2.0上线按scope支持版本级或 AgentSpec 级POST/offline3.2.0下线同上PUT/scope3.2.0更新可见性 scopePUBLIC / PRIVATE版本状态机常量draft/reviewing/reviewed/online/offline定义在 AiConstants.Agent行为验证可参考 AgentSpecVersionStateMachineTest、AgentSpecVersionResolutionTest 与 AgentSpecDeletionTest 等测试。6. 运行时行为与客户端监听协议6.1 运行时能力边界运行时客户端可以按显式版本、label 或 latest加载已组装好的 AgentSpec订阅subscription应在解析到的 AgentSpec 发生变更时通知客户端。同时规范划定了明确的禁止清单运行时客户端不应获得 upload、publish、force publish、delete 以及宽泛的管理列表能力——这些只能走 Admin API。6.2 MD5 条件轮询Client Listener Protocol客户端采用 HTTP 轮询 条件查询MD5 作为 ETag 的载体来检测内容变化避免每个周期都下载完整载荷。完整契约如下轮询间隔通过nacosAiAgentSpecCacheUpdateInterval配置默认10 000 ms常量AI_AGENTSPEC_CACHE_UPDATE_INTERVAL定义于 AiConstants默认值DEFAULT_AI_CACHE_UPDATE_INTERVAL 10000L与 MCP Server、Agent Card、Prompt、Skill 的缓存刷新间隔统一取值。请求GET /v3/client/ai/agentspecs?namespaceIdnamemd5cached-md5。304 Not Modified服务端将请求携带的 MD5 与存储的contentMd5发布时计算比对一致则返回 HTTP 304 与ETag响应头客户端保持本地缓存不变。200 OK响应体为ResultAgentSpecJSON并携带响应头X-Nacos-AgentSpec-Md5与X-Nacos-AgentSpec-Resolved-Version后者告知 latest/label 最终解析到了哪个具体版本。客户端更新本地缓存与 md5Cache 后发布AgentSpecChangedEvent事件。遗留版本回填对contentMd5字段引入之前发布的版本服务端在首次条件查询时惰性计算并持久化MD5此后即可正常走 304 路径。实现链路可逐层验证端点 AgentSpecClientController.get() 标注了Secured(READ, SignType.AI, OPEN_API, parser AgentSpecNameHttpResourceParser.class, tags {ALLOW_ANONYMOUS})即匿名可读在授权开启时仍受可见性约束queryAgentSpecForClient()返回 AgentSpecQueryResult其中isNotModified()为真时走buildAgentSpecNotModifiedResponse()构造 304。两个响应头常量X-Nacos-AgentSpec-Md5、X-Nacos-AgentSpec-Resolved-Version定义在 Constants.AgentSpecs。contentMd5的存储位置是版本行storageJSON 列中的contentMd5键STORAGE_KEY_CONTENT_MD5见 Constants惰性回填与发布时计算逻辑在 AgentSpecOperationServiceImpl 中MD5 由 AgentSpecContentDigestUtils.computeContentMd5() 基于完整 AgentSpec 内容计算持久化仅更新storageJSON 中的该键AiResourceVersionPersistService 的mergeContentMd5不触碰其他存储字段。对客户端实现的直接启示304 分支要保留md5Cache原样200 分支必须先缓存新 MD5 再触发变更事件X-Nacos-AgentSpec-Resolved-Version是排查“latest 漂移”问题的关键观测点。7. 授权资源解析规则AgentSpec 的 HTTP API 使用复数/ai/agentspecs路径段并保持声明的AIsign type 与 API type但各端点解析“被鉴权的资源名”的规则不同规范第 5.2 节实现对应 AgentSpecHttpParamExtractor 与各端点的Secured声明常规 Admin 与 Console 操作从agentSpecName参数解析资源名由AgentSpecHttpParamExtractor作为整个 Admin 控制器的默认 HTTP extractor 完成GET .../agentspecs/list这是命名空间范围namespace-range操作不解析单一资源名行级可见性由可见性插件visibility plugin强制PUT .../agentspecs/draft从agentSpecCard.name解析权威目标——因为该请求中agentSpecName是可选的而 card 才是服务端真正写入的对象鉴权对象必须与实际写入对象一致防止用参数 A 的权限写对象 B。对应实现为 AgentSpecCardHttpResourceParser在 updateDraft() 上以parser指定GET /v3/client/ai/agentspecs从客户端name参数解析资源由 AgentSpecNameHttpResourceParser 处理。这条规则的通用意义在于鉴权解析的“事实来源”必须与服务端实际读写的对象来源一致card 而非 query 参数否则会出现越权写入窗口。8. 演进方向与兼容性约束规范第 6 节给出前瞻性约束AgentSpec 预期会跟随智能体框架的打包方式演进未来版本可能加入 schema 校验、签名signing、依赖清单dependency manifests或兼容性元数据。任何此类变更必须保持基于版本的检索能力或提供迁移规则——即存量版本永远可被旧客户端按原协议读取。结合第 3 节中“版本描述符持久化 provider”的设计可以看到该规范整体采用“新写入跟随新配置、旧读取跟随旧记录”的双轨策略来消化存储与协议演进这是跨版本兼容性承诺的落地基础。小结AgentSpec 规范把“智能体规范包”定义为一种有身份、有版本、有存储治理、有安全边界的 Registry 资源包结构以manifest.json为唯一名称与内容事实源写入路径上 ZIP 解析的四重安全校验大小/条目数/解压量/路径穿越先行于任何版本落库读取路径上 MD5 条件轮询以 304 消除带宽浪费并以Resolved-Version头保证 latest 语义可观测鉴权路径上资源名解析规则逐端点钉死。规范文档specs/en/ai/agentspec-spec.md、specs/zh-cn/ai/agentspec-spec.md与上述源码相互印证可作为对接 AgentSpec API 与实现客户端缓存器的完整契约依据。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考