Understand-Anything 的 C 语言知识如何驱动代码库图谱：从提示词片段到树形语法提取的完整链路

本文以 understand-anything-plugin/skills/understand/languages/csharp.md 这份 C# 语言提示词片段为核心，讲清它在 /understand 技能分析流水线中的确切位置与消费方式，并沿仓库源码补齐文档未展开的部分：语言注册配置 csharp.ts、Tree-sitter 结构提取器 csharp-extractor.ts 的映射决策，以及配套的 csharp-extractor.test.ts 测试边界。读完后你将掌握：这段 C# 语言知识在架构分析阶段如何被注入子代理、C# 的 using/文件/框架约定如何转化为图谱节点与边，以及哪些 C# 语言特性被确定性解析覆盖、哪些交给 LLM 理解。

一、文档定位：languages/csharp.md 在 /understand 流水线中的消费时机

csharp.md 位于 understand 技能的 languages/ 子目录，与 SKILL.md 同级。它不直接面向终端用户，而是被分析流程在两个阶段消费：

1. Phase 4（架构分析）注入语言上下文。 SKILL.md 的 Phase 4 明确规定：对 Phase 1 扫描出的每种语言（如 python、yaml），读取 ./languages/<language-id>.md 并追加到 architecture-analyzer 子代理提示词的 ## Language Context 小节之后。也就是说，当扫描结果把项目标记为 C# 时，csharp.md 全文会被附加到 architecture-analyzer.md 的基础模板后面，指导子代理理解 C# 的 LINQ 管道、异步模式、DI 容器、Program.cs 入口、*.csproj 配置约定，从而做出更准确的架构分层与文件摘要。该机制同时说明"若语言文件不存在则静默跳过"，即这份片段是可选增强而非硬性依赖。
2. 语言课程（languageLesson）的概念检测。 技能支持为图谱节点生成 C# 专属讲解，其中"预检测哪些概念"依赖的是核心包语言配置中同一份概念清单（见第五节）。

从 SKILL.md 的完整流程看，片段上游是 Phase 1 的语言检测，下游是 Phase 6 的图谱校验与 Phase 7 的 knowledge-graph.json 落盘；csharp.md 属于"让 LLM 看懂 C# 项目"的知识层，而不是解析器本身。

二、Key Concepts：十项 C# 核心概念清单及其下游用途

文档的 "Key Concepts" 一节列出了十项概念，这里完整继承并说明各自在下游被谁消费：

概念	文档中的说明	下游消费
LINQ Queries	方法语法 .Where().Select() 或查询语法	架构提示词上下文；语言课程概念检测（配置项 LINQ）
Async/Await with Task	返回 Task<T> 的异步模型，用于非阻塞 I/O	同时命中核心包基础概念模式 async/await（见下）
Generics and Constraints	带 where T : class, IDisposable 约束的类型参数	配置概念 generics，命中基础模式 "generics"
Properties (get/set)	一等属性：后备字段、自动属性、init-only	配置概念 properties；提取器将属性解析进 properties 数组
Delegates and Events	类型安全函数指针；事件提供发布-订阅	基础概念模式 "observer pattern"（event/publish/subscribe 关键词）
Attributes	声明式元数据标注（[HttpGet]、[Authorize]）	基础概念模式 "decorators"（含 @、annotation 关键词）
Nullable Reference Types	C# 8+ 编译器强制空安全，? 标注	配置概念 nullable reference types
Pattern Matching	is、switch 表达式中的类型/属性/关系模式	配置概念 pattern matching
Records and Init-Only Setters	C# 9+ 不可变引用类型，值相等语义	配置概念 records；提取器将 record_declaration 解析为类节点
Dependency Injection (Built-in)	ASP.NET Core 内置容器 IServiceCollection	配置概念 dependency injection，命中基础模式（inject/provider/container/di 关键词）

这份清单并不是孤立的文档内容：核心包的语言配置 csharp.ts 中的 concepts 字段与之几乎一一对应：

concepts: [
  "LINQ", "async/await", "generics", "properties",
  "delegates and events", "attributes", "nullable reference types",
  "pattern matching", "records", "dependency injection",
],

消费方在 language-lesson.ts：detectLanguageConcepts 把节点的 tags、summary、languageNotes 拼成文本，与"基础概念模式 + 语言配置概念"合并出的关键词表逐一匹配（如 "async/await" 对应 async、await、promise 等关键词），命中的概念会写入 buildLanguageLessonPrompt 生成的 LLM 提示词（"Detected concepts to explain"），让生成的 C# 语言课程聚焦于该节点真正用到的特性。文档末尾的 "Example Language Notes"（下节）正是这种讲解的语气与内容范本。

三、Import Patterns：四种 using 形式的完整说明与源码处理

文档给出四种 C# 导入模式，此处完整保留原文语义：

• using System.Collections.Generic — 导入命名空间以获得无限定类型访问
• using static System.Math — 导入静态成员，直接调用方法
• global using — 项目级文件范围 using（C# 10），对全项目生效
• using Alias = Namespace.Type — 类型别名，用于消歧

源码中 using 指令的确定性解析

提取器 csharp-extractor.ts 的 extractUsingSource 对 using_directive 节点做了分支处理：

1. 普通/限定形式（using System;、using System.Collections.Generic;）：取 qualified_name 子节点文本作为 source；
2. 别名形式（using Alias = Some.Namespace;）：先检查节点内是否存在 = 符号，若存在则取 = 后的 qualified_name 作为导入源——这与文档中 alias 模式的语义一致；
3. 提取后 specifiers 只保留点分路径的最后一段（lastComponent），例如 System.Collections.Generic 的 specifier 为 Generic。

测试文件 对此有明确断言：using System.Collections.Generic; 产生 source: "System.Collections.Generic"、specifiers: ["Generic"]，且空行间隔时行号报告正确（第 1 行与第 3 行）。

边界说明（从源码结构看）： 提取器的 walkTopLevel 只匹配 using_directive 节点，而 C# 10 的 global using 在 tree-sitter-c-sharp 中是独立的节点类型，当前提取路径未处理；using static 若被解析为 using_directive，其"静态成员"语义也不会被单独区分——这两点属于确定性解析的已知简化，相关语义（全局生效、静态直调）仍依赖 csharp.md 中的说明交给 LLM 理解。

这些 imports 最终成为图谱什么

解析出的 imports 会随扫描结果汇总为文件间的 imports 边（SKILL.md Phase 1 产出 importMap），随后在 Phase 4 作为 importEdges 输入传给 architecture-analyzer，用于计算扇入/扇出、组间依赖矩阵和依赖方向——C# 项目里 Program.cs 的 DI 注册文件与控制器/服务之间的 using 关系，正是分层判断的强证据。

四、File Patterns：项目文件模式与语言配置的对照

文档的 "File Patterns" 一节列出五种文件模式：

• *.csproj — MSBuild 项目文件，定义目标、包与构建属性
• *.sln — Visual Studio 解决方案文件，组织多个项目
• Program.cs — 应用入口（.NET 6+ 顶层语句）
• Startup.cs — 服务与中间件配置（旧式 ASP.NET Core 模式）
• appsettings.json — 分层应用配置

这些模式在核心包中落到 csharp.ts 的 filePatterns 字段，并与 csharp.md 形成可对照的映射：

filePatterns: {
  entryPoints: ["Program.cs", "**/Program.cs"],
  barrels: [],
  tests: ["*Tests.cs", "*Test.cs"],
  config: ["*.csproj", "*.sln"],
},

• Program.cs 入口约定与文档一致：entryPoints 覆盖根目录与任意子目录下的 Program.cs。此外 architecture-analyzer.md 的目录模式表也写明"文件名为 Application.java 或 Program.cs 归为 entry（JVM / .NET 入口）"，与文档对入口点的定位互相印证；SKILL.md Phase 0 的入口探测列表中也包含 Program.cs。
• *.csproj、*.sln 归为 config 模式：在图谱中它们会成为 config: 前缀的配置节点（如 config:MyApp.csproj），而不是 file: 代码节点，最终多被划入配置/根层（architecture-analyzer 的非代码文件分层指引）。
• *Tests.cs、*Test.cs 测试模式与文档提到的 xUnit 框架呼应：architecture-analyzer 的文件级模式中 *Tests.cs 会被标为 test；合并阶段 merge-batch-graphs.py 还会为测试文件与生产文件生成 tested_by 边（生产 → 测试方向），并给被测试覆盖的生产节点打上 "tested" 标签。
• Startup.cs、appsettings.json 属于文档对旧式/通用 .NET 约定的说明：前者在架构分析中通常归入配置或基础设施层，后者（JSON 配置）会作为 config: 节点参与 configures 边分析。

五、Common Frameworks 与 Example Language Notes

文档 "Common Frameworks" 列出五个框架，完整保留：

• ASP.NET Core — 跨平台 Web 框架（API、MVC、Razor Pages）
• Entity Framework — 支持 LINQ-to-SQL、迁移与变更跟踪的 ORM
• Blazor — 用 C# 而非 JavaScript 的组件化 UI 框架
• MAUI — 移动端与桌面端跨平台原生 UI
• xUnit — 具备 theory、fact 与依赖注入的现代测试框架

在 SKILL.md 的 Phase 4 中，框架检测有独立的注入通道：对 Phase 1 检出的每个框架读取 ./frameworks/<framework-id-lowercase>.md 作为 addendum 追加到提示词。当前技能的 frameworks/ 目录覆盖的是 django、express、fastapi、flask、gin、nextjs、rails、react、spring、vue（见 understand-anything-plugin/skills/understand/frameworks/），没有 ASP.NET Core 对应文件——按 SKILL.md 的规则这会被静默跳过，此时 csharp.md 中的框架清单就成为子代理理解 C# 项目的唯一框架背景。这正是该文档"知识兜底"价值的体现。

"Example Language Notes" 原文两条要点（完整继承）：

Uses LINQ method syntax .Where().Select() to compose a query pipeline over the collection. LINQ operations are lazily evaluated — the query only executes when results are enumerated, allowing efficient composition without intermediate allocations.

The built-in DI container in ASP.NET Core registers services in Program.cs and resolves them via constructor injection, following the composition root pattern.

这两条示范了 languageNotes 应有的粒度：不是复述语法，而是点出延迟求值对内存分配的影响、DI 组合根落在 Program.cs 这类对理解代码行为有实际帮助的信息。语言课程提示词（language-lesson.ts 的 buildLanguageLessonPrompt）要求 LLM 输出 languageNotes + concepts 两个字段，其中 concepts 是"面向初学者的概念解释"——与文档示例的写法一致。

六、确定性链路：从 .cs 文件到图谱节点的完整实现

第五节讲的是"LLM 知识层"，这一节补齐"确定性代码层"，两者共同构成 Understand-Anything 处理 C# 的完整链路。

语言注册与分发

C# 配置 声明 extensions: [".cs"] 与 treeSitter: { wasmPackage: "tree-sitter-c-sharp", wasmFile: "tree-sitter-c_sharp.wasm" }，并在 configs/index.ts 中注册进 builtinLanguageConfigs。LanguageRegistry 按扩展名建立索引（.cs → csharp 配置），getForFile 先按文件名精确匹配、再按扩展名兜底——扫描阶段据此把每个 .cs 文件标记为 C# 语言，Phase 4 再据此决定注入 csharp.md。提取器 CSharpExtractor 同样在 extractors/index.ts 导出，languageIds = ["csharp"]，与配置 id 对齐。

CSharpExtractor 的 C# 特化映射决策

csharp-extractor.ts 头部注释列出了其 C# 特化决策，逐条对应文档中的语言特性：

• 命名空间双形式兼容：namespace_declaration（块级 namespace Foo { ... }）递归进 body；file_scoped_namespace_declaration（C# 10 文件级 namespace Foo;）的声明是根节点的兄弟节点，不做递归——两种形式都被覆盖（测试 分别验证）。
• 类与接口统一进 classes：class_declaration、record_declaration（对应文档 "Records" 概念）、struct_declaration、interface_declaration 都映射为类节点，携带 lineRange、methods、properties。
• 构造函数映射为 functions 并以类名命名（public Foo(string name, int value) → 函数 Foo，有参数、无返回类型）；方法同时记入所在类的 methods 数组与全局 functions 数组，记录参数名列表与返回类型文本（泛型如 List<string> 完整保留）。
• 属性与字段同入 properties：property_declaration（自动属性 public int MaxRetries { get; set; }）与 field_declaration（后备字段 _host）都记入所在类，这对应文档 "Properties (get/set)" 概念中"后备字段 + 自动属性"的说法。
• exports 由 public 修饰符判定：C# 的 tree-sitter 语法把每个修饰符拆成独立的 modifier 子节点（与 Java 的单一 modifiers 容器不同），hasModifier 逐个匹配关键字；类、接口、方法、构造、属性、字段只要有 public 就进入 exports。测试断言了 UserService（类+构造各计一次）、MaxRetries、Start 被导出，而私有 Helper、_name 不导出。
• 调用图（call graph）：extractCallGraph 用一个 functionStack 追踪当前方法/构造（method_declaration、constructor_declaration），对 invocation_expression 取 function 字段文本（覆盖 FetchFromDb(limit) 与 Console.WriteLine(msg) 限定调用），对 object_creation_expression 生成 new Bar 条目；方法体外（如字段初始化）的调用因无调用者而被忽略。每条记录带 1 起始的 lineNumber。

测试证据

csharp-extractor.test.ts 加载真实的 tree-sitter-c_sharp.wasm 运行端到端断言，关键覆盖：

• 方法参数与返回类型（含无参方法、泛型返回 List<string>、跨多行签名行范围 3–9）；
• 接口签名提取（IRepository 的 FindAll/FindById，空接口 IMarker）；
• using 的普通/限定形式、行号缺口、exports 的 public 边界；
• 调用图的简单调用、限定调用、new 创建、构造内调用（caller 为构造名）、行号、方法外忽略；
• 块级/文件级命名空间；public struct Vec、public record Point(int X, int Y) 等现代类型声明；
• 一个综合的 UserService 模块用例同时断言 functions（3 个）、classes（2 个）、imports（2 条）、exports 白名单与调用图（GetUsers → FetchFromDb、Log → Console.WriteLine）。

七、小结：这段 C# 知识的边界与适用前提

• 知识层（LLM 消费）：csharp.md 的关键概念、using 模式、文件模式、框架清单与示例笔记，在 Phase 4 作为 Language Context 注入 architecture-analyzer，改善 C# 项目的分层、摘要与语言课程质量；global using、using static 的语义、Startup.cs/appsettings.json 的约定主要由这一层承载。
• 代码层（确定性消费）：csharp.ts 配置负责语言识别（.cs）、入口/测试/配置文件模式与概念清单；CSharpExtractor 负责类/接口/结构体/record、方法/构造、属性/字段、using imports、public exports 与方法内调用图的 AST 提取；两者由 测试文件 以真实 WASM 语法规则验证。
• 适用前提：该机制运行于 /understand 技能的分析流水线（Phase 1 语言检测 → Phase 4 上下文注入），依赖插件核心包已构建（SKILL.md Phase 0 的构建步骤）；语言文件缺失时流程静默降级，不影响图谱生成。

沿 understand-anything-plugin/skills/understand/SKILL.md 的七阶段流程、architecture-analyzer.md 的分层规则与本文引用的源码/测试路径，可以完整复核 C# 项目从 .cs 文件到 knowledge-graph.json 中节点、边与语言课程的每一步。