Agenticagentic/platformSDK 详解从defineConfig到配置解析流水线写一份类型安全的agentic.config.ts【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agenticagentic/platform是 Agentic 平台面向开发者的公开 SDK其核心职责是让你以完全类型安全、可自动补全的方式定义项目配置agentic.config.ts并在加载、校验与解析阶段把一份原始配置变成可供 API 网关使用的已解析配置。读完本文你将掌握该 SDK 的完整导出 API、agenticProjectConfigSchema中每个配置项的取值约束与默认值、mcp/openapi/raw三种 origin 适配器的差异以及配置从文件加载到解析落地的完整内部流水线。一、包定位与安装根据 packages/platform/readme.md该包定位是 Public SDK for developers building on top of the Agentic platform在 Agentic 平台上构建应用的公开 SDK安装方式npm i agentic/platform从 packages/platform/package.json 可以确认几个工程事实与适用前提当前版本8.4.4运行时要求node 18包类型为 ESMtype: modulesideEffects: false许可证为 AGPL-3.0它依赖同仓库内的四个包agentic/platform-core、agentic/platform-openapi-utils、agentic/platform-types、agentic/platform-validators以及modelcontextprotocol/sdk用于连接 MCP 源服务器、unconfig用于多格式配置文件加载、mrmime、semver。入口文件 的公共导出只有六行也就是全部 API 表面export * from ./define-config export * from ./load-agentic-config export * from ./resolve-agentic-project-config export type * from ./types export * from ./validate-agentic-project-config export { defaultFreePricingPlan } from agentic/platform-types即defineConfig、loadAgenticConfig、resolveAgenticProjectConfig、validateAgenticProjectConfig四个函数加上UploadFileUrlToStorageFn类型与重新导出的defaultFreePricingPlan常量。二、defineConfig定义一份类型安全的项目配置readme 中给出的核心用法是agentic/platform的主导出是defineConfig(...)用于在agentic.config.ts中以完整类型安全和自动补全的方式配置 Agentic 项目。官方示例import { defineConfig } from agentic/platform export default defineConfig({ name: Your Project Name, description: A brief description of your project, origin: { type: mcp, url: Your Remote MCP Server URL } })仓库内的实际 fixture 与之一致见 fixtures/valid/basic-mcp/agentic.config.tsimport { defineConfig } from agentic/platform export default defineConfig({ name: Test Basic MCP, origin: { type: mcp, url: https://agentic-basic-mcp-test.onrender.com/mcp } })defineConfig的 实现 本身很薄export function defineConfig( config: AgenticProjectConfigInput ): AgenticProjectConfig { return parseAgenticProjectConfig(config) }它接收AgenticProjectConfigInput类型获得完整补全并调用parseAgenticProjectConfig做基础校验后返回。也就是说defineConfig在模块加载时就会用 Zod schema 对配置做一次即时校验——配置写错会在导入agentic.config.ts时立即失败而不是拖到部署时。2.1 配置项完整参考所有字段的约束与默认值定义在 packages/types/src/agentic-project-config.ts 的agenticProjectConfigSchema第 36–251 行中字段类型必填默认值 / 约束说明namestring是最长 1024 字符项目显示名称slugstring否缺省时由nameslugify 得到仅小写 ASCII、kebab-case、1–256 字符项目全限定标识为namespace/slugnamespace 来自作者的 username 或 team slugversionstring否—语义化版本semver字符串如1.0.0descriptionstring否—简短描述建议不超过几行readmestring否—Markdown 文档支持 GitHub-Flavored Markdown取值可以是远程 URL、本地文件路径或>export function parseAgenticProjectConfig( inputConfig: unknown, { strip false, strict false }: { strip?: boolean; strict?: boolean } {} ): AgenticProjectConfig默认对agenticProjectConfigSchema做普通解析该 schema 本身已调用.strip()未知字段会被静默丢弃传strip: true时显式使用.strip()传strict: true时使用.strict()出现未知字段即报错解析前经过pruneUndefined来自agentic/platform-core剥离undefined字段解析失败抛出带statusCode: 400的错误。同文件还导出parseResolvedAgenticProjectConfig用于解析已解析配置见第五节。三、origin三种源服务器适配器origin是配置中唯一的必填核心字段用于声明 Agentic API 网关下游的源 API 服务器它既指定源服务器是自托管还是托管在 Agentic 基础设施内也指定源工具的格式MCP 服务器或 OpenAPI 规范。从 schema 注释可以推断当前仅支持外部源服务器——若想托管在 Agentic 基础设施内需要联系其官方支持。分派逻辑在 resolveOriginAdapter先调用validateOriginUrl校验origin.url为合法的 https URL按origin.type分派openapi→resolveOpenAPIOriginAdapter实现文件借助agentic/platform-openapi-utils从 OpenAPI 规范推导工具列表mcp→resolveMCPOriginAdapter实现文件以slug作为 server name、version缺省0.0.0连接远程 MCP 服务器获取工具raw→ 不做工具推导原样返回 origin 配置其他值直接以 400 报错。仓库中fixtures/valid/下的样例覆盖了这些分支basic-mcpMCP 源、basic-openapiOpenAPI 源附带jsonplaceholder.json规范文件、basic-raw-free-json/basic-raw-free-tsraw 源、everything-openapi完整 OpenAPI 规范推导工具。非法场景也各有对应用例如fixtures/invalid/invalid-origin-url-0至invalid-origin-url-3验证 URL 校验规则。官方发布文档中各指南与源码分支一一对应MCP 服务器、OpenAPI 服务 等完整的端到端流程见 Quick Start。四、配置加载loadAgenticConfig与校验流水线当 CLI 或平台侧需要从磁盘读取配置时使用 loadAgenticConfigexport async function loadAgenticConfig({ cwd }: { cwd?: string } {}) { const { config } await loadConfig({ cwd, sources: [ { files: agentic.config, extensions: [ts, mts, cts, js, mjs, cjs, json] } ] }) return validateAgenticProjectConfig(config, { cwd }) }两点值得注意文件定位由unconfig完成文件名固定为agentic.config扩展名支持.ts/.mts/.cts/.js/.mjs/.cjs/.json——这解释了仓库中为什么同时存在agentic.config.ts多数 fixture与agentic.config.json如 fixtures/valid/basic-raw-free-json、fixtures/invalid/invalid-origin-url-2/agentic.config.json两种写法加载到对象后直接交给validateAgenticProjectConfig因此加载与校验是同一条链路。validateAgenticProjectConfig 的内部顺序是parseAgenticProjectConfig(inputConfig, { strip, strict: !strip })——默认非 strip 模式即严格模式未知字段报错resolveMetadata(config)得到slug与versionslug 缺省时从 name 推导version 缺省时回退默认值validatePricing(config)校验定价配置规则在 validate-pricing.tsvalidateMetadataFiles(config, opts)解析并校验 readme / icon 文件支持本地路径、远程 URL、data-uri实现见 validate-metadata-file.tsvalidateOriginAdapter(...)校验源适配器配置最后把slug、version、readme、icon、origin合并回配置再做一次 schema 解析返回最终的AgenticProjectConfig。单测与快照见 load-agentic-config.test.ts 及其 快照文件。五、配置解析resolveAgenticProjectConfig与 Resolved 配置校验产出的是合法的项目配置而真正供网关消费的是已解析配置Resolved 配置resolveAgenticProjectConfig 在parseAgenticProjectConfig之后依次执行resolveMetadata→ 得到slug、versionvalidatePricingresolveMetadataFiles→ 把本地 readme / icon 实际读入并上传得到readme字符串与iconUrlresolveOriginAdapter→ 得到最终的origin对象与推导出的tools数组用parseResolvedAgenticProjectConfig组装ResolvedAgenticProjectConfigvalidateTools交叉校验tools与toolConfigs的一致性。Resolved 配置与原始配置的差异体现在 resolvedAgenticProjectConfigSchemaslug变为必填、icon被移除并替换为iconUrl已上传后的 URL、origin换为解析后的originAdapterSchema、并新增tools数组默认[]。resolveAgenticProjectConfig的opts中需要传入uploadFileUrlToStorage即UploadFileUrlToStorageFn签名(source: string) Promisestring定义在 packages/platform/src/types.ts用于把本地文件上传为存储 URL——这也解释了为什么该函数只在具备存储能力的环境中如 CLI 发布流程、API 服务端被调用而不是在本地defineConfig阶段。六、开发、测试与许可在 packages/platform 目录下脚本与行为对应关系为buildtsup构建发布产物只包含dist/test串联test:*即先tsc --noEmit类型检查再vitest run跑单测本地开发直接暴露./src/index.ts作为 entryexports: { .: ./src/index.ts }无需先构建即可被 workspace 内其他包引用。该包以 AGPL-3.0 许可发布readme 与 license 说明 一致。七、小结agentic/platform的 API 面很小但链路完整defineConfig导入期类型安全定义 即时校验→loadAgenticConfigunconfig 多格式加载 严格校验→resolveAgenticProjectConfig元数据推导、定价校验、文件上传、origin 适配与工具推导。对使用者而言日常只需要defineConfig与agentic.config.ts需要深入排错时上文各节给出的 schema 定义、校验函数与 fixture 目录fixtures/valid、fixtures/invalid就是逐层定位问题的准确入口。【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agentic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Agenticagentic/platformSDK 详解从defineConfig到配置解析流水线写一份类型安全的agentic.config.ts【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agenticagentic/platform是 Agentic 平台面向开发者的公开 SDK其核心职责是让你以完全类型安全、可自动补全的方式定义项目配置agentic.config.ts并在加载、校验与解析阶段把一份原始配置变成可供 API 网关使用的已解析配置。读完本文你将掌握该 SDK 的完整导出 API、agenticProjectConfigSchema中每个配置项的取值约束与默认值、mcp/openapi/raw三种 origin 适配器的差异以及配置从文件加载到解析落地的完整内部流水线。一、包定位与安装根据 packages/platform/readme.md该包定位是 Public SDK for developers building on top of the Agentic platform在 Agentic 平台上构建应用的公开 SDK安装方式npm i agentic/platform从 packages/platform/package.json 可以确认几个工程事实与适用前提当前版本8.4.4运行时要求node 18包类型为 ESMtype: modulesideEffects: false许可证为 AGPL-3.0它依赖同仓库内的四个包agentic/platform-core、agentic/platform-openapi-utils、agentic/platform-types、agentic/platform-validators以及modelcontextprotocol/sdk用于连接 MCP 源服务器、unconfig用于多格式配置文件加载、mrmime、semver。入口文件 的公共导出只有六行也就是全部 API 表面export * from ./define-config export * from ./load-agentic-config export * from ./resolve-agentic-project-config export type * from ./types export * from ./validate-agentic-project-config export { defaultFreePricingPlan } from agentic/platform-types即defineConfig、loadAgenticConfig、resolveAgenticProjectConfig、validateAgenticProjectConfig四个函数加上UploadFileUrlToStorageFn类型与重新导出的defaultFreePricingPlan常量。二、defineConfig定义一份类型安全的项目配置readme 中给出的核心用法是agentic/platform的主导出是defineConfig(...)用于在agentic.config.ts中以完整类型安全和自动补全的方式配置 Agentic 项目。官方示例import { defineConfig } from agentic/platform export default defineConfig({ name: Your Project Name, description: A brief description of your project, origin: { type: mcp, url: Your Remote MCP Server URL } })仓库内的实际 fixture 与之一致见 fixtures/valid/basic-mcp/agentic.config.tsimport { defineConfig } from agentic/platform export default defineConfig({ name: Test Basic MCP, origin: { type: mcp, url: https://agentic-basic-mcp-test.onrender.com/mcp } })defineConfig的 实现 本身很薄export function defineConfig( config: AgenticProjectConfigInput ): AgenticProjectConfig { return parseAgenticProjectConfig(config) }它接收AgenticProjectConfigInput类型获得完整补全并调用parseAgenticProjectConfig做基础校验后返回。也就是说defineConfig在模块加载时就会用 Zod schema 对配置做一次即时校验——配置写错会在导入agentic.config.ts时立即失败而不是拖到部署时。2.1 配置项完整参考所有字段的约束与默认值定义在 packages/types/src/agentic-project-config.ts 的agenticProjectConfigSchema第 36–251 行中字段类型必填默认值 / 约束说明namestring是最长 1024 字符项目显示名称slugstring否缺省时由nameslugify 得到仅小写 ASCII、kebab-case、1–256 字符项目全限定标识为namespace/slugnamespace 来自作者的 username 或 team slugversionstring否—语义化版本semver字符串如1.0.0descriptionstring否—简短描述建议不超过几行readmestring否—Markdown 文档支持 GitHub-Flavored Markdown取值可以是远程 URL、本地文件路径或>export function parseAgenticProjectConfig( inputConfig: unknown, { strip false, strict false }: { strip?: boolean; strict?: boolean } {} ): AgenticProjectConfig默认对agenticProjectConfigSchema做普通解析该 schema 本身已调用.strip()未知字段会被静默丢弃传strip: true时显式使用.strip()传strict: true时使用.strict()出现未知字段即报错解析前经过pruneUndefined来自agentic/platform-core剥离undefined字段解析失败抛出带statusCode: 400的错误。同文件还导出parseResolvedAgenticProjectConfig用于解析已解析配置见第五节。三、origin三种源服务器适配器origin是配置中唯一的必填核心字段用于声明 Agentic API 网关下游的源 API 服务器它既指定源服务器是自托管还是托管在 Agentic 基础设施内也指定源工具的格式MCP 服务器或 OpenAPI 规范。从 schema 注释可以推断当前仅支持外部源服务器——若想托管在 Agentic 基础设施内需要联系其官方支持。分派逻辑在 resolveOriginAdapter先调用validateOriginUrl校验origin.url为合法的 https URL按origin.type分派openapi→resolveOpenAPIOriginAdapter实现文件借助agentic/platform-openapi-utils从 OpenAPI 规范推导工具列表mcp→resolveMCPOriginAdapter实现文件以slug作为 server name、version缺省0.0.0连接远程 MCP 服务器获取工具raw→ 不做工具推导原样返回 origin 配置其他值直接以 400 报错。仓库中fixtures/valid/下的样例覆盖了这些分支basic-mcpMCP 源、basic-openapiOpenAPI 源附带jsonplaceholder.json规范文件、basic-raw-free-json/basic-raw-free-tsraw 源、everything-openapi完整 OpenAPI 规范推导工具。非法场景也各有对应用例如fixtures/invalid/invalid-origin-url-0至invalid-origin-url-3验证 URL 校验规则。官方发布文档中各指南与源码分支一一对应MCP 服务器、OpenAPI 服务 等完整的端到端流程见 Quick Start。四、配置加载loadAgenticConfig与校验流水线当 CLI 或平台侧需要从磁盘读取配置时使用 loadAgenticConfigexport async function loadAgenticConfig({ cwd }: { cwd?: string } {}) { const { config } await loadConfig({ cwd, sources: [ { files: agentic.config, extensions: [ts, mts, cts, js, mjs, cjs, json] } ] }) return validateAgenticProjectConfig(config, { cwd }) }两点值得注意文件定位由unconfig完成文件名固定为agentic.config扩展名支持.ts/.mts/.cts/.js/.mjs/.cjs/.json——这解释了仓库中为什么同时存在agentic.config.ts多数 fixture与agentic.config.json如 fixtures/valid/basic-raw-free-json、fixtures/invalid/invalid-origin-url-2/agentic.config.json两种写法加载到对象后直接交给validateAgenticProjectConfig因此加载与校验是同一条链路。validateAgenticProjectConfig 的内部顺序是parseAgenticProjectConfig(inputConfig, { strip, strict: !strip })——默认非 strip 模式即严格模式未知字段报错resolveMetadata(config)得到slug与versionslug 缺省时从 name 推导version 缺省时回退默认值validatePricing(config)校验定价配置规则在 validate-pricing.tsvalidateMetadataFiles(config, opts)解析并校验 readme / icon 文件支持本地路径、远程 URL、data-uri实现见 validate-metadata-file.tsvalidateOriginAdapter(...)校验源适配器配置最后把slug、version、readme、icon、origin合并回配置再做一次 schema 解析返回最终的AgenticProjectConfig。单测与快照见 load-agentic-config.test.ts 及其 快照文件。五、配置解析resolveAgenticProjectConfig与 Resolved 配置校验产出的是合法的项目配置而真正供网关消费的是已解析配置Resolved 配置resolveAgenticProjectConfig 在parseAgenticProjectConfig之后依次执行resolveMetadata→ 得到slug、versionvalidatePricingresolveMetadataFiles→ 把本地 readme / icon 实际读入并上传得到readme字符串与iconUrlresolveOriginAdapter→ 得到最终的origin对象与推导出的tools数组用parseResolvedAgenticProjectConfig组装ResolvedAgenticProjectConfigvalidateTools交叉校验tools与toolConfigs的一致性。Resolved 配置与原始配置的差异体现在 resolvedAgenticProjectConfigSchemaslug变为必填、icon被移除并替换为iconUrl已上传后的 URL、origin换为解析后的originAdapterSchema、并新增tools数组默认[]。resolveAgenticProjectConfig的opts中需要传入uploadFileUrlToStorage即UploadFileUrlToStorageFn签名(source: string) Promisestring定义在 packages/platform/src/types.ts用于把本地文件上传为存储 URL——这也解释了为什么该函数只在具备存储能力的环境中如 CLI 发布流程、API 服务端被调用而不是在本地defineConfig阶段。六、开发、测试与许可在 packages/platform 目录下脚本与行为对应关系为buildtsup构建发布产物只包含dist/test串联test:*即先tsc --noEmit类型检查再vitest run跑单测本地开发直接暴露./src/index.ts作为 entryexports: { .: ./src/index.ts }无需先构建即可被 workspace 内其他包引用。该包以 AGPL-3.0 许可发布readme 与 license 说明 一致。七、小结agentic/platform的 API 面很小但链路完整defineConfig导入期类型安全定义 即时校验→loadAgenticConfigunconfig 多格式加载 严格校验→resolveAgenticProjectConfig元数据推导、定价校验、文件上传、origin 适配与工具推导。对使用者而言日常只需要defineConfig与agentic.config.ts需要深入排错时上文各节给出的 schema 定义、校验函数与 fixture 目录fixtures/valid、fixtures/invalid就是逐层定位问题的准确入口。【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agentic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
