CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载导读本文以 x-cmd 的 skill0 技能库中 yfm 的 Jekyll 方言文档 为核心系统讲解 Jekyll 站点 front matterYAML 前置元数据中tags与categories的真实形态、标签提取规则与常见解析陷阱。读完本文你将掌握 Jekyll 方言与其他 Markdown 方言Obsidian、Agent Skills、Hugo在分隔符与类型约定上的差异理解为什么categories: jekyll update这类空格分隔字符串必须与列表形态分开处理并能按 skill0 的规范正确实现标签收集与本体ontology属性映射。一、Jekyll 方言在 skill0 yfm 体系中的位置x-cmd 的yfm技能mod/skill0/lib/skill0/core/yfm/SKILL.md为所有可能被 Agent、索引器或本体管线扫描的 Markdown 文件定义了 YAML front matter 约定。其核心原则是如果某个 Markdown 表面已有既定方言在起作用Agent Skills、Obsidian、Jekyll、Hugo 等就遵循该方言只有没有任何方言管辖时才使用 x-cmd 默认的三字段tags、description、memo。由于本体收集器collector要摄入多种方言yfm 技能按方言拆分了独立文档agentskills.md —metadata:为字符串映射顶层字段封闭obsidian.md —tags/aliases/cssclasses为保留属性jekyll.md — 本文主题tags/categories支持列表或空格分隔字符串hugo.md — 可能使用 TOML 格式分类法由站点配置决定。各 Markdown 表面的读写字段映射见 git-issue-pr-wiki-markdown-etc.md 中的快速映射表Jekyll 站点文件属于由 Jekyll 原生写入、由 yfm 读取的表面有效字段为title、date、tags、categories。这意味着 Jekyll 文件通常不需要x-cmd 重写 front matteryfm 的重点在于正确读取与解析。二、Jekyll front matter 的典型形态Jekyll 官方文档jekyllrb.com/docs/front-matter规定的典型 front matter 示例如下--- layout: post title: Welcome to Jekyll date: 2026-07-31 10:00:00 0800 categories: jekyll update tags: [intro, meta] ---逐个字段说明字段类型语义layout字符串指定模板布局如post决定页面渲染使用的布局文件title字符串文章标题可被模板读取并渲染进页面title与正文标题date时间戳文章发布日期格式为YYYY-MM-DD HH:mm:ss ±HHMM含时区偏移categories空格分隔字符串文章所属分类多个分类用空格隔开tagsYAML 列表文章标签标准 YAML 列表形态注意上例中date的写法2026-07-31 10:00:00 0800这是 Jekyll 认可的带时区偏移的时间格式与 x-cmd 默认方言中memo:键使用的 ISO 8601 格式如2026-07-31T14:30:0008:00见 story.md不同——时间戳解析同样需要按方言区分。三、第一个陷阱同一文件中两种类型共存仔细观察上面的典型示例会发现一个极易被忽略的问题categories: jekyll update是一个空格分隔的字符串tags: [intro, meta]是一个YAML 列表。两种形态同时存在于一个文件之中——这就是 Jekyll 方言最大的陷阱。如果解析器用同一种假设去处理这两个字段必然出错。Jekyll 规范对 tags/categories 的原文定义是can be specified as a YAML list or a space-separated string可以写成 YAML 列表也可以写成空格分隔的字符串。这带来两个直接影响类型必须先检测后解析。提取器必须先用 YAML 解析器确认字段类型是列表就逐项遍历是字符串就按空格拆分。不能默认它是列表也不能默认它是字符串。不能假定单一分隔符。Jekyll 的空格分隔约定与 Agent Skills 方言metadata.tags使用逗号分隔、无空格见 agentskills.md恰好相反这正是一个共享的拆分例程无法同时服务两种方言的根本原因。四、标签提取规范针对 Jekyll 方言yfm 文档明确了以下提取规则key键—tags和categories两者都位于顶层都要提取type类型— 列表list或字符串string需按实际解析结果判断separator分隔符— 字符串形态下为空格绝不是逗号。提取器的正确处理流程可以归纳为1. 用 YAML 解析 front matter 块 2. 对顶层 keys 逐个检查tags、categories 3. 若该 key 的值为 list → 逐项取出每一项都是一个标签/分类 4. 若该 key 的值为 string → 按空格空白符拆分成多个标签/分类 5. 永远不要用逗号拆分字符串形态的 Jekyll 标签这里要特别强调第 4 步与第 5 步如果对categories: jekyll update用逗号拆分由于字符串中根本没有逗号整串会被当成一个标签jekyll update。五、为什么逗号拆分是致命的Obsidian 与 Agent Skills 的冲突用逗号拆分 Jekyll 的 categories 字符串后果不只是多出一个带空格的标签而是会污染下游的整条处理链Obsidian 方言明确规定标签不能包含空格多词标签必须写成camelCase、PascalCase、snake_case或kebab-case详见 obsidian.md。因此jekyll update这个带空格的值会被 Obsidian 直接拒绝被拒绝的坏值会继续传播进下游的标准化normalization流程导致后续的标签归一化、去重、索引全部产生偏差。与之形成鲜明对比的是 Agent Skills 方言其metadata.tags是字符串且约定用逗号分隔、不带空格。逗号连接在 Agent Skills 中之所以安全是因为其值域受限——slug 只能是[a-z0-9-]天然不含逗号见 agentskills.md。甚至在同一份 Agent Skills front matter 内部allowed-tools是空格分隔、metadata.tags是逗号分隔分隔符并不统一必须按 key 分发处理。所以结论是Jekyll 用空格Agent Skills 用逗号两者的分隔符恰好相反。这就是为什么一个共享的字符串拆分例程无法同时服务两种方言——正确的做法是像 yfm 这样按方言、按 key 分别实现提取逻辑。六、categories 不是 tags语义必须分开除了解析形态Jekyll 方言还在语义层上区分categories与tagscategories参与 URL 路径生成。Jekyll 会根据分类构建文章的永久链接路径例如/jekyll/update/2026/07/31/welcome-to-jekyll.html这类包含分类层级的 URLtags不参与 URL 路径生成只是平铺的关键词标注。从语义上说categories 是层级化的hierarchicaltags 是扁平的关键词flat keywords。二者不是同义词不能混为一谈。因此 yfm 对收集器collector的明确要求是将二者保持为两个独立的集合separate sets绝不要合并进同一个标签袋tag bag。合并会导致层级信息丢失进而破坏本体图中分类关系与扁平标签的区分。七、容易被忽略的细节yfm 文档还补充了两个实战细节1. 单数形式同样合法。category/tag单数与categories/tags复数等价都会被 Jekyll 识别。解析器必须扫描全部四个键tags、categories、tag、category。2. 顶层自定义字段直接映射为本体属性。Jekyll 允许在 front matter 顶层自由添加自定义字段这些字段在模板中可以直接访问。对于本体ontology管线而言剩余的自定义字段会直接成为本体实体的属性properties。这一点与 Obsidian 方言的属性名在整个 vault 中类型一致约束obsidian.md不同也与 Agent Skills 方言顶层字段封闭、扩展字段必须放入metadata:的规则agentskills.md形成对照——Jekyll 是顶层开放的方言。八、在 x-cmd 中的落地yfm 模块与本体收集器上述规范在 x-cmd 中由yfm模块承载三个命令详见 yfm/SKILL.mdx yfm ls [path]— 列出路径下 Markdown 文件的 YFM 块默认当前目录x yfm init [path]— 为路径下每个 Markdown 文件写入 x-cmd 默认三字段块x yfm lint [path]— 校验每个 YFM 块是否为合法 YAML、并遵循其声称的方言。注意init写入的是 x-cmd 默认形态对于 Jekyll 站点文件Jekyll 原生写 front matter并不适用Jekyll 方言文档的价值主要在于让lint与收集器按 Jekyll 规则正确解析既有文件。收集器解析出的实体与关系最终进入 skill0 的本体数据库ontology-database/SKILL.md该数据库以 TSV 追加日志为存储协议一切实体id type properties与有向关系from → rel → to都由x ondb命令读写。按 yfm/SKILL.md 的关联说明yfm 是本体数据库推荐的摄取表面——Jekyll 文件中解析出的tags/categories集合、以及顶层自定义字段属性最终都会被写入本体图形成可推理的知识结构。九、与相邻方言的对比速查维度JekyllObsidianAgent SkillsHugo标签键顶层tags/categories含单数共 4 键顶层tags正文#tag嵌套metadata.tagstags/categories/keywords 站点自定义分类法类型列表或空格分隔字符串必须为列表必须为字符串[]string数组分隔符空格N/A列表逗号、无空格N/A数组顶层字段开放自定义字段可作模板变量保留tags/aliases/cssclasses封闭仅 6 个键开放特殊语义categories 参与 URL 生成/构成嵌套层级无类型推断字符串直接映射TOML 边界keywords弱标签这张表来自 yfm 各方言文档jekyll.md、obsidian.md、agentskills.md、hugo.md的综合结论也是收集器按来源分发解析、不做跨方言调和的原因。十、实践清单在实现或审查 Jekyll front matter 解析逻辑时请逐条核对类型先行先由 YAML 解析器确认tags/categories是列表还是字符串再决定遍历还是拆分空格拆分字符串形态用空格拆分永远不要用逗号扫描四个键tags、categories、tag、category都要处理两个集合categories 与 tags 保持独立不得合并防御坏值拆分结果若含空格且下游是 Obsidian 等禁止空格标签的方言需在标准化前拦截自定义字段顶层剩余字段按 Jekyll 开放方言直接映射为本体属性不共享拆分例程跨方言的分隔符约定不一致按 key 分发处理避免一个例程打天下。赞分享CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载相关推荐x-cmd yfm为 Agent、索引与本体管线统一 Markdown 的 YAML Front Matter 规范x cmd yfm为 Agent、索引与本体管线统一 Markdown 的 YAML Front Matter 规范 YAML Front MatterYFCLI开发工具AI Agent人工智能包管理器x-cmd yfm skillMarkdown 各场景的 YAML Front Matter 使用映射与 GitHub Issue/PR 实践指南x cmd yfm skillMarkdown 各场景的 YAML Front Matter 使用映射与 GitHub Issue/PR 实践指南 导读 本文CLI开发工具AI Agent人工智能包管理器Jekyll Front Matter高级用法元数据管理终极指南Jekyll Front Matter高级用法元数据管理终极指南 你是否曾经在Jekyll项目中重复编写相同的布局配置是否希望更高效地管理网站元数据本文将前端CMS上一篇cube-composer游戏状态管理Storage模块完整解析下一篇如何自动解决依赖冲突Vuls漏洞扫描工具的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考