JSON 家族识别指南Understand-Anything 如何将 JSON/JSONC/JSON Schema 解析为知识图谱节点【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything本文聚焦 Understand-Anything 项目中understandskill 的 JSON 语言分析片段languages/json.md剖析它如何指导代码分析 Agent 在生成项目知识图谱时正确理解package.json、tsconfig.json、*.schema.json等非代码文件的核心语法、常见模式与语义关系并配套讲解其底层语言配置、扫描分类与 JSON/JSONC 解析器的实现。读完本文你将掌握该图谱工具处理配置型 JSON 生态的完整链路并能据此判断与分析 JSON 相关文件在项目架构中的角色。语言片段注入架构分析的一线语义知识在 Understand-Anything 的七阶段分析流程中语言片段在Phase 4ARCHITECTURE被投入使用。根据 SKILL.md 中的说明架构分析子代理architecture-analyzer在下发前会针对 Phase 1 检测到的每一种语言读取 languages/ 目录下对应的language-id.md文件将其内容附加到提示模板的## Language Context之后——JSON 的对应文件正是本篇文章的主题文档 json.md。值得强调的是这些非代码语言片段与代码语言片段同等重要。设计意图在 SKILL.md 中写得很明确Include non-code language snippets — they provide edge patterns and summary styles for non-code files.请包含非代码语言片段——它们为非代码文件提供边缘模式和摘要风格。也就是说当分析一个以package.json、tsconfig.json或 JSON Schema 为主的项目时Phase 4 的层分配与关系判定质量直接依赖这段 JSON 语义知识。片段本身通常不长约 40 行但信息密度高它浓缩了 JSON 家族的核心概念Key Concepts、常见文件模式Notable File Patterns、边缘模式Edge Patterns即该文件与其他文件如何建立关系边以及摘要风格Summary Style。下面逐节拆解并对照仓库源码还原其背后的真实实现。核心概念JSON 家族与它的变体光谱文档首先划定 JSON 语言家族的分析边界共七条关键概念可分为两个层次标准 JSON 的硬性语法规则严格语法Strict Syntax不允许尾随逗号、不允许注释这是与 JSONC/JSON5 的关键分界、字符串只能使用双引号数据类型Data Types对象、数组、字符串、数字、布尔值与null——没有undefined与日期类型这一点使 JSON 无法直接表达 JS 的undefined日期通常序列化为 ISO 字符串嵌套结构Nested Structure支持任意深度的递归嵌套这是它能承载层级化配置与数据结构的根本原因。围绕标准 JSON 形成的扩展/变体Schema 校验Schema Validation通过 JSON Schema 与$schema关键字描述并校验结构与类型JSONC带注释的 JSON 变体被 VS Code、tsconfig.json及大量前端工具链采用JSON5进一步放宽语法的扩展——允许注释、尾随逗号、非引号键名等JSON Lines.jsonl每行一个 JSON 对象面向流式数据处理。仓库中的语言配置忠实体现了这一边界。在 json-config.ts 中JSON 语言的注册配置为export const jsonConfigConfig { id: json, displayName: JSON, extensions: [.json, .jsonc], // 同时接管 .json 与 .jsonc concepts: [objects, arrays, nesting, schema references, comments (JSONC)], filePatterns: { entryPoints: [package.json], barrels: [], tests: [], config: [tsconfig.json, package.json, .eslintrc.json], }, } satisfies LanguageConfig;concepts字段与语言片段中的 Key Concepts 高度一致objects、arrays、nesting、schema references、comments (JSONC)filePatterns.config则把tsconfig.json、package.json、.eslintrc.json列为该语言配置文件形态的代表模式——这正是片段中 Notable File Patterns 前半部分的来源。你可以在 index.ts 看到它与其他二十多种语言配置一起被导出并合入builtinLanguageConfigs。从扩展名到节点类型JSON 文件如何在扫描中被归类在 Phase 1SCAN中扫描脚本 scan-project.mjs 负责为每个文件推断语言与类别JSON 家族在此处的规则清晰可见语言映射.json→json.jsonc→jsonc源码中同时存在.yaml/.yml/.toml/.xml等非代码语言映射类别映射.json与.jsonc均归类为config配置类与.yaml、.toml、.env等同属一类。随后file-analyzer.md 中的fileCategory → 节点类型映射将config类别映射为知识图谱中的config节点ID 形如config:relative-path例如config:package.json、config:tsconfig.json。本仓库自身就是一个绝佳实例根目录的 package.json、tsconfig.json 以及 pnpm-workspace.yaml 等都属于此类节点。一个值得注意的边界JSON Schema*.schema.json并没有独立扩展名。在 json-schema.ts 中其配置的extensions为空数组并留有一段明确的 TODO 注释说明设计取舍JSON Schema files have no unique extension —*.schema.jsonfiles will matchjsonConfigConfigby the.jsonextension. Detection requires content-based heuristics (e.g., checking for$schemaortypekeys at the root level).也就是说*.schema.json目前按.json扩展名落入json语言配置其Schema 身份依赖内容启发式判断如根级$schema或type键来做进一步区分——这一点在阅读图谱结果时值得留意Schema 类文件在节点类型上可能是schema:path也可能是config:path取决于内容层面如何被判定。常见文件模式图谱中最常出现的 JSON 文件文档给出七类高频 JSON 文件模式它们是分析任何真实项目时几乎必然遇到的文件模式典型作用域分析要点package.jsonNode.js 项目依赖dependencies、脚本scripts与项目元数据tsconfig.jsonTypeScript编译器配置注意实际上是 JSONC允许注释与尾随逗号.eslintrc.jsonESLint静态检查规则与配置*.schema.json数据校验JSON Schema 定义composer.jsonPHP ComposerPHP 包与依赖清单appsettings.json.NET应用运行时配置manifest.json浏览器扩展 / PWAWeb 应用清单从源码结构看本仓库对这些模式的处理呈多文件覆盖形态JSONConfigParser的注释明确提到它处理package.json、tsconfig.json、wrangler.jsonc、JSON Schema 与 OpenAPI 规格文件见下节dashboard 子包understand-anything-plugin/packages/dashboard中可见真实的package.json、tsconfig*.json、vite.config.ts而 knowledge-graph.json 本身即是图谱输出物——JSON 既是被分析对象也是分析产物。底层解析器JSONConfigParser 如何读懂 JSON/JSONC语言片段只负责告诉 LLM该关注什么而真正确定性提取结构的是 json-parser.ts 中的JSONConfigParser。它注册的语言集合为[json, jsonc, json-schema, openapi]这意味着 JSON 家族的多种风味都会走同一解析路径避免落入no parser matched分支而丢失结构提取。JSONC 语法剥离stripJsoncSyntax由于tsconfig.json等文件是 JSONC 而非严格 JSON直接JSON.parse会失败。解析器先调用stripJsoncSyntax做三件事的预处理字符串字面量原样保留——遇到双引号则逐字符复制并正确处理\转义序列确保字符串内部的//或/*不会被误当注释删除行注释剥离// ...与块注释剥离/* ... */尾随逗号清洗——通过正则/,(\s*[}\]])/g删除}或]之前的逗号。纯 JSON 内容不含这三类语法因此会原样通过几乎无性能损失。顶层键提取为 sectionsextractSections解析成功后只遍历根对象不递归深入嵌套子结构把每个顶层键作为一条sections记录返回并尽力定位其在源文件中的真实行号用JSON.stringify(key)做转义后再去原文逐行查找保证tsconfig.json中带注释的行号与用户所见一致最后把相邻 section 的行区间补全。于是像package.json的name、scripts、dependencies、devDependencies这样的顶层键会成为图谱中描述该配置文件管什么的原始结构证据。$ref外部引用提取extractReferences用正则/\$ref\s*:\s*([^])/g抓取 JSON Schema / OpenAPI 中的$ref跳过以#开头的内部引用把指向外部文件的引用解析为referenceType: schema的引用记录含源文件、目标与行号——这为后续建立跨文件的语义边提供了确定性锚点。值得注意的是该解析器处理失败并不会让分析中断而是console.warn输出一行 Failed to parse JSON 后返回空 sections体现可降级、保留部分结果的整体容错哲学。边缘模式JSON 文件如何长出关系边语言片段 Edge Patterns 部分用动词明确了每类 JSON 文件的语义角色package.jsonconfigures配置构建工具链定义项目依赖tsconfig.jsonconfigures所有.ts文件的 TypeScript 编译JSON Schema 文件defines_schema定义结构服务于 API 请求/响应的校验运行时配置 JSONconfigures应用的运行时行为。这些动词与图谱边类型一一对应。在 file-analyzer.md 的非代码边规则表中configures边的方向为 forward、权重 0.6用于配置文件影响某个代码文件或模块例tsconfig.json配置 TypeScript 编译、.env配置运行时defines_schema权重 0.8用于Schema 文件定义代码所用结构。文件分析 Agent 被明确要求tsconfig.json应对所有.ts文件建configures边package.json应对构建入口建configures边Schema 文件则应对实现该数据结构的处理代码建defines_schema边。在知识图谱 Schema 的边类型总表中见 SKILL.md Reference 部分这两个边分属Dependenciesconfigures与Schema/Datadefines_schema两个类别。加上从图谱输出的类型约定可推断schema:path节点专用于 GraphQL/Protobuf/Prisma 等 Schema 定义而 JSON Schema*.schema.json在实际运行中会经由 JSON 解析器路径与config/schema节点身份之间的内容判定——这类推断性结论需要在阅读具体项目图谱时结合节点 ID 前缀确认。摘要风格让每个 JSON 节点一句话讲清自己语言片段以三条示例句给出 JSON 文件节点摘要的写作范式Node.js project manifest defining N dependencies, build scripts, and project metadata. TypeScript compiler configuration enabling strict mode with path aliases for monorepo packages. JSON Schema defining the request/response structure for the user API endpoint.这与 file-analyzer.md 对配置类文件的摘要要求完全同构Describe what the config controls描述这份配置控制了什么并给出反例与正例——反例 The utils file contains utility functions正例如 TypeScript compiler configuration enabling strict mode with path aliases for the monorepo。把片段规则与 Agent 规范对照可以提炼出撰写 JSON 节点摘要的四条实用准则动词导向使用defining、configuring、enabling等说明作用而非静态描述包含点出被作用对象manifest 之于项目、tsconfig 之于.ts文件、Schema 之于 API 接口携带关键决策strict mode、path aliases、依赖数量 N 等具体事实比形容词更有检索价值配套 tags 词汇非代码文件常用configuration、build-system、schema-definition、api-schema等标签与摘要互相印证。对本仓库图谱的直接观察将上述规则应用回本仓库可以立刻看到 JSON 节点在真实项目中的分布形态仓库根与各包core、dashboard、homepage的 package.json 被归为config类节点承担 monorepopnpm workspace依赖管理职责应对pnpm-workspace.yaml及构建脚本建立关系各层的 tsconfig.json /tsconfig.app.json以 JSONC 形态存在应与其覆盖的.ts/.tsx源码建立configures边dashboard 的 knowledge-graph.json 则是图谱即数据的产物文件若要二次分析可复用同一套 JSON 解析与 Schema 识别逻辑。小结以 json.md 为代表的语言片段是 Understand-Anything 将非代码配置资产纳入知识图谱的关键语义层它在 Phase 4 把 JSON 家族的语法边界、高频文件模式、关系动词与摘要范式注入架构分析子代理而json-config.ts/json-schema.ts的语言配置、scan-project.mjs 的扩展名分类、以及 json-parser.ts 的 JSONC 剥离与$ref提取共同构成该语义层下方的确定性引擎。理解这一语言片段语义 解析器结构的双层设计不仅能帮你读懂图谱中 JSON 节点的由来也为扩展或复用它分析自身项目中的 JSON 资产提供了清晰的参考路径。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 JSON 家族识别指南：Understand-Anything 如何将 JSON/JSONC/JSON Schema 解析为知识图谱节点
JSON 家族识别指南Understand-Anything 如何将 JSON/JSONC/JSON Schema 解析为知识图谱节点【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything本文聚焦 Understand-Anything 项目中understandskill 的 JSON 语言分析片段languages/json.md剖析它如何指导代码分析 Agent 在生成项目知识图谱时正确理解package.json、tsconfig.json、*.schema.json等非代码文件的核心语法、常见模式与语义关系并配套讲解其底层语言配置、扫描分类与 JSON/JSONC 解析器的实现。读完本文你将掌握该图谱工具处理配置型 JSON 生态的完整链路并能据此判断与分析 JSON 相关文件在项目架构中的角色。语言片段注入架构分析的一线语义知识在 Understand-Anything 的七阶段分析流程中语言片段在Phase 4ARCHITECTURE被投入使用。根据 SKILL.md 中的说明架构分析子代理architecture-analyzer在下发前会针对 Phase 1 检测到的每一种语言读取 languages/ 目录下对应的language-id.md文件将其内容附加到提示模板的## Language Context之后——JSON 的对应文件正是本篇文章的主题文档 json.md。值得强调的是这些非代码语言片段与代码语言片段同等重要。设计意图在 SKILL.md 中写得很明确Include non-code language snippets — they provide edge patterns and summary styles for non-code files.请包含非代码语言片段——它们为非代码文件提供边缘模式和摘要风格。也就是说当分析一个以package.json、tsconfig.json或 JSON Schema 为主的项目时Phase 4 的层分配与关系判定质量直接依赖这段 JSON 语义知识。片段本身通常不长约 40 行但信息密度高它浓缩了 JSON 家族的核心概念Key Concepts、常见文件模式Notable File Patterns、边缘模式Edge Patterns即该文件与其他文件如何建立关系边以及摘要风格Summary Style。下面逐节拆解并对照仓库源码还原其背后的真实实现。核心概念JSON 家族与它的变体光谱文档首先划定 JSON 语言家族的分析边界共七条关键概念可分为两个层次标准 JSON 的硬性语法规则严格语法Strict Syntax不允许尾随逗号、不允许注释这是与 JSONC/JSON5 的关键分界、字符串只能使用双引号数据类型Data Types对象、数组、字符串、数字、布尔值与null——没有undefined与日期类型这一点使 JSON 无法直接表达 JS 的undefined日期通常序列化为 ISO 字符串嵌套结构Nested Structure支持任意深度的递归嵌套这是它能承载层级化配置与数据结构的根本原因。围绕标准 JSON 形成的扩展/变体Schema 校验Schema Validation通过 JSON Schema 与$schema关键字描述并校验结构与类型JSONC带注释的 JSON 变体被 VS Code、tsconfig.json及大量前端工具链采用JSON5进一步放宽语法的扩展——允许注释、尾随逗号、非引号键名等JSON Lines.jsonl每行一个 JSON 对象面向流式数据处理。仓库中的语言配置忠实体现了这一边界。在 json-config.ts 中JSON 语言的注册配置为export const jsonConfigConfig { id: json, displayName: JSON, extensions: [.json, .jsonc], // 同时接管 .json 与 .jsonc concepts: [objects, arrays, nesting, schema references, comments (JSONC)], filePatterns: { entryPoints: [package.json], barrels: [], tests: [], config: [tsconfig.json, package.json, .eslintrc.json], }, } satisfies LanguageConfig;concepts字段与语言片段中的 Key Concepts 高度一致objects、arrays、nesting、schema references、comments (JSONC)filePatterns.config则把tsconfig.json、package.json、.eslintrc.json列为该语言配置文件形态的代表模式——这正是片段中 Notable File Patterns 前半部分的来源。你可以在 index.ts 看到它与其他二十多种语言配置一起被导出并合入builtinLanguageConfigs。从扩展名到节点类型JSON 文件如何在扫描中被归类在 Phase 1SCAN中扫描脚本 scan-project.mjs 负责为每个文件推断语言与类别JSON 家族在此处的规则清晰可见语言映射.json→json.jsonc→jsonc源码中同时存在.yaml/.yml/.toml/.xml等非代码语言映射类别映射.json与.jsonc均归类为config配置类与.yaml、.toml、.env等同属一类。随后file-analyzer.md 中的fileCategory → 节点类型映射将config类别映射为知识图谱中的config节点ID 形如config:relative-path例如config:package.json、config:tsconfig.json。本仓库自身就是一个绝佳实例根目录的 package.json、tsconfig.json 以及 pnpm-workspace.yaml 等都属于此类节点。一个值得注意的边界JSON Schema*.schema.json并没有独立扩展名。在 json-schema.ts 中其配置的extensions为空数组并留有一段明确的 TODO 注释说明设计取舍JSON Schema files have no unique extension —*.schema.jsonfiles will matchjsonConfigConfigby the.jsonextension. Detection requires content-based heuristics (e.g., checking for$schemaortypekeys at the root level).也就是说*.schema.json目前按.json扩展名落入json语言配置其Schema 身份依赖内容启发式判断如根级$schema或type键来做进一步区分——这一点在阅读图谱结果时值得留意Schema 类文件在节点类型上可能是schema:path也可能是config:path取决于内容层面如何被判定。常见文件模式图谱中最常出现的 JSON 文件文档给出七类高频 JSON 文件模式它们是分析任何真实项目时几乎必然遇到的文件模式典型作用域分析要点package.jsonNode.js 项目依赖dependencies、脚本scripts与项目元数据tsconfig.jsonTypeScript编译器配置注意实际上是 JSONC允许注释与尾随逗号.eslintrc.jsonESLint静态检查规则与配置*.schema.json数据校验JSON Schema 定义composer.jsonPHP ComposerPHP 包与依赖清单appsettings.json.NET应用运行时配置manifest.json浏览器扩展 / PWAWeb 应用清单从源码结构看本仓库对这些模式的处理呈多文件覆盖形态JSONConfigParser的注释明确提到它处理package.json、tsconfig.json、wrangler.jsonc、JSON Schema 与 OpenAPI 规格文件见下节dashboard 子包understand-anything-plugin/packages/dashboard中可见真实的package.json、tsconfig*.json、vite.config.ts而 knowledge-graph.json 本身即是图谱输出物——JSON 既是被分析对象也是分析产物。底层解析器JSONConfigParser 如何读懂 JSON/JSONC语言片段只负责告诉 LLM该关注什么而真正确定性提取结构的是 json-parser.ts 中的JSONConfigParser。它注册的语言集合为[json, jsonc, json-schema, openapi]这意味着 JSON 家族的多种风味都会走同一解析路径避免落入no parser matched分支而丢失结构提取。JSONC 语法剥离stripJsoncSyntax由于tsconfig.json等文件是 JSONC 而非严格 JSON直接JSON.parse会失败。解析器先调用stripJsoncSyntax做三件事的预处理字符串字面量原样保留——遇到双引号则逐字符复制并正确处理\转义序列确保字符串内部的//或/*不会被误当注释删除行注释剥离// ...与块注释剥离/* ... */尾随逗号清洗——通过正则/,(\s*[}\]])/g删除}或]之前的逗号。纯 JSON 内容不含这三类语法因此会原样通过几乎无性能损失。顶层键提取为 sectionsextractSections解析成功后只遍历根对象不递归深入嵌套子结构把每个顶层键作为一条sections记录返回并尽力定位其在源文件中的真实行号用JSON.stringify(key)做转义后再去原文逐行查找保证tsconfig.json中带注释的行号与用户所见一致最后把相邻 section 的行区间补全。于是像package.json的name、scripts、dependencies、devDependencies这样的顶层键会成为图谱中描述该配置文件管什么的原始结构证据。$ref外部引用提取extractReferences用正则/\$ref\s*:\s*([^])/g抓取 JSON Schema / OpenAPI 中的$ref跳过以#开头的内部引用把指向外部文件的引用解析为referenceType: schema的引用记录含源文件、目标与行号——这为后续建立跨文件的语义边提供了确定性锚点。值得注意的是该解析器处理失败并不会让分析中断而是console.warn输出一行 Failed to parse JSON 后返回空 sections体现可降级、保留部分结果的整体容错哲学。边缘模式JSON 文件如何长出关系边语言片段 Edge Patterns 部分用动词明确了每类 JSON 文件的语义角色package.jsonconfigures配置构建工具链定义项目依赖tsconfig.jsonconfigures所有.ts文件的 TypeScript 编译JSON Schema 文件defines_schema定义结构服务于 API 请求/响应的校验运行时配置 JSONconfigures应用的运行时行为。这些动词与图谱边类型一一对应。在 file-analyzer.md 的非代码边规则表中configures边的方向为 forward、权重 0.6用于配置文件影响某个代码文件或模块例tsconfig.json配置 TypeScript 编译、.env配置运行时defines_schema权重 0.8用于Schema 文件定义代码所用结构。文件分析 Agent 被明确要求tsconfig.json应对所有.ts文件建configures边package.json应对构建入口建configures边Schema 文件则应对实现该数据结构的处理代码建defines_schema边。在知识图谱 Schema 的边类型总表中见 SKILL.md Reference 部分这两个边分属Dependenciesconfigures与Schema/Datadefines_schema两个类别。加上从图谱输出的类型约定可推断schema:path节点专用于 GraphQL/Protobuf/Prisma 等 Schema 定义而 JSON Schema*.schema.json在实际运行中会经由 JSON 解析器路径与config/schema节点身份之间的内容判定——这类推断性结论需要在阅读具体项目图谱时结合节点 ID 前缀确认。摘要风格让每个 JSON 节点一句话讲清自己语言片段以三条示例句给出 JSON 文件节点摘要的写作范式Node.js project manifest defining N dependencies, build scripts, and project metadata. TypeScript compiler configuration enabling strict mode with path aliases for monorepo packages. JSON Schema defining the request/response structure for the user API endpoint.这与 file-analyzer.md 对配置类文件的摘要要求完全同构Describe what the config controls描述这份配置控制了什么并给出反例与正例——反例 The utils file contains utility functions正例如 TypeScript compiler configuration enabling strict mode with path aliases for the monorepo。把片段规则与 Agent 规范对照可以提炼出撰写 JSON 节点摘要的四条实用准则动词导向使用defining、configuring、enabling等说明作用而非静态描述包含点出被作用对象manifest 之于项目、tsconfig 之于.ts文件、Schema 之于 API 接口携带关键决策strict mode、path aliases、依赖数量 N 等具体事实比形容词更有检索价值配套 tags 词汇非代码文件常用configuration、build-system、schema-definition、api-schema等标签与摘要互相印证。对本仓库图谱的直接观察将上述规则应用回本仓库可以立刻看到 JSON 节点在真实项目中的分布形态仓库根与各包core、dashboard、homepage的 package.json 被归为config类节点承担 monorepopnpm workspace依赖管理职责应对pnpm-workspace.yaml及构建脚本建立关系各层的 tsconfig.json /tsconfig.app.json以 JSONC 形态存在应与其覆盖的.ts/.tsx源码建立configures边dashboard 的 knowledge-graph.json 则是图谱即数据的产物文件若要二次分析可复用同一套 JSON 解析与 Schema 识别逻辑。小结以 json.md 为代表的语言片段是 Understand-Anything 将非代码配置资产纳入知识图谱的关键语义层它在 Phase 4 把 JSON 家族的语法边界、高频文件模式、关系动词与摘要范式注入架构分析子代理而json-config.ts/json-schema.ts的语言配置、scan-project.mjs 的扩展名分类、以及 json-parser.ts 的 JSONC 剥离与$ref提取共同构成该语义层下方的确定性引擎。理解这一语言片段语义 解析器结构的双层设计不仅能帮你读懂图谱中 JSON 节点的由来也为扩展或复用它分析自身项目中的 JSON 资产提供了清晰的参考路径。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考