拓冰网站定制 
Test Metadata【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agenticThis is testingreadme rendering.MiscItem 1Item 2Item 3italicboldlinkcodeCodeconst a 1 export function foo() { console.log(hello world) }Images逐段对照可以看到它刻意覆盖了以下渲染要点 | 文档段落 | 覆盖的 Markdown 特性 | | --- | --- | | Misc 小节 | 任务列表- [ ] / - [x] 未勾选与已勾选两种状态、水平分割线 ---、斜体 _italic_、加粗 **bold**、超链接、行内代码 | | Code 小节 | 带语言标注ts的围栏代码块可检验代码高亮与转义 | | Images 小节 | 外链图片语法可检验远程图片加载 | 需要注意这些内容在解析阶段只是“被整段读入文件”并不会被真正渲染渲染发生在 Agentic 对外展示项目详情的环节。解析层要保证的只是“字节级完整读取 正确的 MIME 判定”这一点由下一节的源码来印证。 ## agentic.config.tsreadme 与 icon 如何挂到项目配置上 夹具的完整配置如下[agentic.config.ts](https://link.gitcode.com/i/37974a4369416a50f50765ad474bb9a6)全文 ts import { defineConfig } from agentic/platform export default defineConfig({ name: Test Metadata 0, origin: { type: raw, url: https://httpbin.org }, icon: ./agentic-dev-icon-circle-dark.svg, readme: ./readme.md }) 要点说明 - name 为 Test Metadata 0配置中没有手写 slug由平台从 name 自动派生 kebab-case slug快照结果为 test-metadata-0见后文。slug 的规则可从负向夹具的错误信息确认“Must be ascii-only, lower-case, and kebab-case with no spaces between 1 and 256 characters”快照 [load-agentic-config.test.ts.snap](https://link.gitcode.com/i/89dbea9bdbece01c46535d4329c1b36e) 中 invalid-slug-3 用例。 - origin 使用 raw 类型并指向 https://httpbin.org与元数据本身无关只是为了满足配置必填项。 - icon 与 readme 都使用以 ./ 开头的**本地相对路径**——这正是 metadata-0 区别于其他夹具的核心特征它验证“本地文件”这一取值分支。 ## 元数据的两阶段处理URL 直通 vs 本地文件 Base64 内联 ### 校验阶段validateMetadataFile loadAgenticConfig[load-agentic-config.ts](https://link.gitcode.com/i/c2f31d73ed6456b7503a5528e72ebac7)先用 unconfig 按 agentic.config 扩展名 [ts, mts, cts, js, mjs, cjs, json] 加载配置文件再交给 validateAgenticProjectConfig 做整体校验其中 readme/icon 两个字段由 [validate-metadata-file.ts](https://link.gitcode.com/i/019806d0b21dfcabd6ab02ff5b46b5b3) 逐个处理。其核心逻辑第 1639 行是一个“先 URL 后文件”的 try/catch 分叉 ts if (!input) return let source: string | ArrayBuffer | URL try { // Check if its a URL. source new URL(input) return source.toString() } catch { try { // Not a URL; check if its a local file path. const buffer await readFile(path.resolve(cwd, input)) const mime lookupMimeType(path.extname(input)) ?? application/octet-stream return data:${mime};base64,${buffer.toString(base64)} } catch { throw new Error( Invalid ${label} (must be a URL or a path to a local file): ${input} ) } } 对照 metadata-0可以读出四个实现事实 1. **相对路径以 cwd 为基准解析**path.resolve(cwd, input) 中cwd 由 [validate-metadata-files.ts](https://link.gitcode.com/i/905cb2b039bd1a6e8be3d9d0e55c8087) 传入默认 process.cwd()在测试场景下则显式传夹具目录见 [load-agentic-config.test.ts](https://link.gitcode.com/i/13d0a286cf956891de34ff26b1d4736e) 中 loadAgenticConfig({ cwd: fixtureDir })。所以 ./readme.md 解析的是夹具目录内的文件而非仓库根目录。 2. **MIME 由扩展名查表得出**使用 mrmime 的 lookupMimeType(path.extname(input)).md 查得 text/markdown、.svg 查得 image/svgxml查不到时回退 application/octet-stream。 3. **本地文件最终变成 Data URI**data:${mime};base64,base64也就是说配置解析完成后readme/icon 不再依赖文件系统内容被完整内联进配置对象可随项目配置序列化、传输。 4. **文件读不到时抛带标签的错误**错误文案 Invalid readme (must be a URL or a path to a local file) 中的 label 会标明是 readme 还是 icon便于定位字段。 ### 解析部署阶段resolveMetadataFile 从源码结构看本地文件转 Data URI 是“加载/校验”阶段的行为在真正部署时还有一次 [resolve-metadata-file.ts](https://link.gitcode.com/i/9fc925550712caf17880c24d37b9bc48) 的处理它对输入的要求更严格——**必须是合法 URL**然后交由 uploadFileUrlToStorage 把文件拷贝进平台存储并返回新的存储 URL第 1521 行 ts try { const source new URL(input) return uploadFileUrlToStorage(source.toString()) } catch { throw new Error(Invalid ${label} must be a public URL: ${input}) } [resolve-metadata-files.ts](https://link.gitcode.com/i/c1eb05e358e343c64df77b2306ec07eb) 会把 readme 和 icon 各自走一遍该流程返回结构里 icon 字段改名为 iconUrl。这也解释了为什么 Data URI 形式对系统很友好它本身就是一个合法 URL两个阶段都能消费。 ## 快照证据metadata-0 解析后的完整形态 测试通过 toMatchSnapshot() 锁定了解析产物快照[load-agentic-config.test.ts.snap](https://link.gitcode.com/i/89dbea9bdbece01c46535d4329c1b36e#L409-L449) 中 metadata-0 用例给出了可验证的最终结果摘录关键字段 jsonc { name: Test Metadata 0, slug: test-metadata-0, readme: data:text/markdown;base64,IyBUZXN0IE1ldGFkYXRh..., icon: data:image/svgxml;base64,PHN2ZyB3aWR0aD0iOTYi..., origin: { location: external, type: raw, url: https://httpbin.org }, defaultRateLimit: { enabled: true, interval: 60, limit: 1000, mode: approximate }, pricingIntervals: [month], pricingPlans: [ { name: Free, slug: free, lineItems: [{ slug: base, usageType: licensed, amount: 0 }], rateLimit: { enabled: true, interval: 60, limit: 1000, mode: approximate } } ], toolConfigs: [] } 可以核对的事实 - readme 字段的 Base64 前缀 IyBUZXN0IE1ldGFkYXRh 解码后正是 # Test Metadata与 [readme.md](https://link.gitcode.com/i/4bba8585d92ebc92a406279c43998da6) 首行逐字节对应证明“整文件读取 → 内联”没有截断MIME 前缀 text/markdown 印证了 mrmime 查表结果。 - icon 前缀 PHN2Zy 解码为 sv即 SVG 文件起始 svgMIME 为 image/svgxml。 - 未显式声明的字段都有平台默认值defaultRateLimit每分钟 1000 次、approximate 模式、月度计费区间加一个 Free 计划base 行项、licensed、0 元。这说明元数据夹具与限流、计费默认值是同一条配置管线里被一起补齐的。 ## 边界与失败用例从负向夹具看校验规则 同一套测试还注册了 invalid-metadata-0 与 invalid-metadata-1 两个负向夹具[load-agentic-config.test.ts](https://link.gitcode.com/i/aa46069714386a8d438fe136e2eceed1)快照锁定了它们的报错形态 text [Error: Invalid readme (must be a URL or a path to a local file): ./not-found.md] [ZodValidationError: Expected string at icon]【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agentic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Test Metadata
Test Metadata【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agenticThis is testingreadme rendering.MiscItem 1Item 2Item 3italicboldlinkcodeCodeconst a 1 export function foo() { console.log(hello world) }Images逐段对照可以看到它刻意覆盖了以下渲染要点 | 文档段落 | 覆盖的 Markdown 特性 | | --- | --- | | Misc 小节 | 任务列表- [ ] / - [x] 未勾选与已勾选两种状态、水平分割线 ---、斜体 _italic_、加粗 **bold**、超链接、行内代码 | | Code 小节 | 带语言标注ts的围栏代码块可检验代码高亮与转义 | | Images 小节 | 外链图片语法可检验远程图片加载 | 需要注意这些内容在解析阶段只是“被整段读入文件”并不会被真正渲染渲染发生在 Agentic 对外展示项目详情的环节。解析层要保证的只是“字节级完整读取 正确的 MIME 判定”这一点由下一节的源码来印证。 ## agentic.config.tsreadme 与 icon 如何挂到项目配置上 夹具的完整配置如下[agentic.config.ts](https://link.gitcode.com/i/37974a4369416a50f50765ad474bb9a6)全文 ts import { defineConfig } from agentic/platform export default defineConfig({ name: Test Metadata 0, origin: { type: raw, url: https://httpbin.org }, icon: ./agentic-dev-icon-circle-dark.svg, readme: ./readme.md }) 要点说明 - name 为 Test Metadata 0配置中没有手写 slug由平台从 name 自动派生 kebab-case slug快照结果为 test-metadata-0见后文。slug 的规则可从负向夹具的错误信息确认“Must be ascii-only, lower-case, and kebab-case with no spaces between 1 and 256 characters”快照 [load-agentic-config.test.ts.snap](https://link.gitcode.com/i/89dbea9bdbece01c46535d4329c1b36e) 中 invalid-slug-3 用例。 - origin 使用 raw 类型并指向 https://httpbin.org与元数据本身无关只是为了满足配置必填项。 - icon 与 readme 都使用以 ./ 开头的**本地相对路径**——这正是 metadata-0 区别于其他夹具的核心特征它验证“本地文件”这一取值分支。 ## 元数据的两阶段处理URL 直通 vs 本地文件 Base64 内联 ### 校验阶段validateMetadataFile loadAgenticConfig[load-agentic-config.ts](https://link.gitcode.com/i/c2f31d73ed6456b7503a5528e72ebac7)先用 unconfig 按 agentic.config 扩展名 [ts, mts, cts, js, mjs, cjs, json] 加载配置文件再交给 validateAgenticProjectConfig 做整体校验其中 readme/icon 两个字段由 [validate-metadata-file.ts](https://link.gitcode.com/i/019806d0b21dfcabd6ab02ff5b46b5b3) 逐个处理。其核心逻辑第 1639 行是一个“先 URL 后文件”的 try/catch 分叉 ts if (!input) return let source: string | ArrayBuffer | URL try { // Check if its a URL. source new URL(input) return source.toString() } catch { try { // Not a URL; check if its a local file path. const buffer await readFile(path.resolve(cwd, input)) const mime lookupMimeType(path.extname(input)) ?? application/octet-stream return data:${mime};base64,${buffer.toString(base64)} } catch { throw new Error( Invalid ${label} (must be a URL or a path to a local file): ${input} ) } } 对照 metadata-0可以读出四个实现事实 1. **相对路径以 cwd 为基准解析**path.resolve(cwd, input) 中cwd 由 [validate-metadata-files.ts](https://link.gitcode.com/i/905cb2b039bd1a6e8be3d9d0e55c8087) 传入默认 process.cwd()在测试场景下则显式传夹具目录见 [load-agentic-config.test.ts](https://link.gitcode.com/i/13d0a286cf956891de34ff26b1d4736e) 中 loadAgenticConfig({ cwd: fixtureDir })。所以 ./readme.md 解析的是夹具目录内的文件而非仓库根目录。 2. **MIME 由扩展名查表得出**使用 mrmime 的 lookupMimeType(path.extname(input)).md 查得 text/markdown、.svg 查得 image/svgxml查不到时回退 application/octet-stream。 3. **本地文件最终变成 Data URI**data:${mime};base64,base64也就是说配置解析完成后readme/icon 不再依赖文件系统内容被完整内联进配置对象可随项目配置序列化、传输。 4. **文件读不到时抛带标签的错误**错误文案 Invalid readme (must be a URL or a path to a local file) 中的 label 会标明是 readme 还是 icon便于定位字段。 ### 解析部署阶段resolveMetadataFile 从源码结构看本地文件转 Data URI 是“加载/校验”阶段的行为在真正部署时还有一次 [resolve-metadata-file.ts](https://link.gitcode.com/i/9fc925550712caf17880c24d37b9bc48) 的处理它对输入的要求更严格——**必须是合法 URL**然后交由 uploadFileUrlToStorage 把文件拷贝进平台存储并返回新的存储 URL第 1521 行 ts try { const source new URL(input) return uploadFileUrlToStorage(source.toString()) } catch { throw new Error(Invalid ${label} must be a public URL: ${input}) } [resolve-metadata-files.ts](https://link.gitcode.com/i/c1eb05e358e343c64df77b2306ec07eb) 会把 readme 和 icon 各自走一遍该流程返回结构里 icon 字段改名为 iconUrl。这也解释了为什么 Data URI 形式对系统很友好它本身就是一个合法 URL两个阶段都能消费。 ## 快照证据metadata-0 解析后的完整形态 测试通过 toMatchSnapshot() 锁定了解析产物快照[load-agentic-config.test.ts.snap](https://link.gitcode.com/i/89dbea9bdbece01c46535d4329c1b36e#L409-L449) 中 metadata-0 用例给出了可验证的最终结果摘录关键字段 jsonc { name: Test Metadata 0, slug: test-metadata-0, readme: data:text/markdown;base64,IyBUZXN0IE1ldGFkYXRh..., icon: data:image/svgxml;base64,PHN2ZyB3aWR0aD0iOTYi..., origin: { location: external, type: raw, url: https://httpbin.org }, defaultRateLimit: { enabled: true, interval: 60, limit: 1000, mode: approximate }, pricingIntervals: [month], pricingPlans: [ { name: Free, slug: free, lineItems: [{ slug: base, usageType: licensed, amount: 0 }], rateLimit: { enabled: true, interval: 60, limit: 1000, mode: approximate } } ], toolConfigs: [] } 可以核对的事实 - readme 字段的 Base64 前缀 IyBUZXN0IE1ldGFkYXRh 解码后正是 # Test Metadata与 [readme.md](https://link.gitcode.com/i/4bba8585d92ebc92a406279c43998da6) 首行逐字节对应证明“整文件读取 → 内联”没有截断MIME 前缀 text/markdown 印证了 mrmime 查表结果。 - icon 前缀 PHN2Zy 解码为 sv即 SVG 文件起始 svgMIME 为 image/svgxml。 - 未显式声明的字段都有平台默认值defaultRateLimit每分钟 1000 次、approximate 模式、月度计费区间加一个 Free 计划base 行项、licensed、0 元。这说明元数据夹具与限流、计费默认值是同一条配置管线里被一起补齐的。 ## 边界与失败用例从负向夹具看校验规则 同一套测试还注册了 invalid-metadata-0 与 invalid-metadata-1 两个负向夹具[load-agentic-config.test.ts](https://link.gitcode.com/i/aa46069714386a8d438fe136e2eceed1)快照锁定了它们的报错形态 text [Error: Invalid readme (must be a URL or a path to a local file): ./not-found.md] [ZodValidationError: Expected string at icon]【免费下载链接】agenticYour API ⇒ Paid MCP. Instantly.项目地址: https://gitcode.com/GitHub_Trending/ag/agentic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考