linguistic-semantic-algorithms

pproenca 语言与语义算法最佳实践

为 Agent 提供的 40 种算法参考，在从源代码和提交数据中提取结构、含义、历史或风险信号时可优先考虑。各类别按洞察与投入比排序，即技术揭示非显而易见事实的能力与应用难易程度之比。前两个类别针对最具价值的问题：这段代码中有哪些业务实体？以及这个概念还出现在哪里？——这些问题无法通过 grep 和直觉回答。

何时应用

遇到以下情况时，可优先考虑这些算法：

• 熟悉不熟悉的代码库：对导入图进行 PageRank，找出核心；对标识符令牌运行 LDA，发现业务主题；挖掘变更耦合，揭示隐藏的架构耦合。
• 根据描述排查 bug：BM25 + 历史先验 + 嵌入重排序生成的文件候选列表，远胜于 grep。
• 确定功能范围：通过嵌入相似度查找执行过类似工作的既有 PR；通过 TF-IDF 和名词短语挖掘，将功能词汇与代码库的领域进行映射。
• 审查重构：AST 级别的 GumTree diff 能揭示文本 diff 隐藏的语义影响；PDG 同构能找出“逻辑相同、代码不同”的对应实现，你也应一并更新。
• 审计风险：热点（变更频率 × 复杂度）、总线因子、缺陷磁铁密度、死代码候选——这些指标结合起来，能将注意力引向代码库中值得重点关注的部分。
• 识别领域实体和限界上下文：名词短语挖掘 + TF-IDF 稀有词提取 + Louvain 社区发现 + 按集群词汇计算 Jensen-Shannon 散度。

按优先级划分的规则类别

优先级	类别	影响	前缀	回答的问题
1	概念与领域提取	CRITICAL	concept-	这段代码中有哪些业务实体？
2	语义相似度与功能映射	CRITICAL	sim-	这个概念还出现在哪里？
3	架构拓扑	HIGH	graph-	这个代码库的结构是什么样的？
4	协同变更与时间挖掘	HIGH	mine-	历史记录揭示了哪些隐藏耦合？
5	克隆与重复检测	MEDIUM-HIGH	clone-	哪些内容在重复？
6	Bug 与功能定位	MEDIUM-HIGH	local-	给定描述，代码在哪里？
7	标识符语言学	MEDIUM	ling-	如何准备令牌，以便其他算法正常工作？
8	复杂度与风险指标	MEDIUM	risk-	风险集中在哪里？

快速参考

1. 概念与领域提取（CRITICAL）

• concept-lda-topic-modeling — 对标识符令牌运行 LDA，揭示潜在业务主题
• concept-noun-phrase-mining — 对标识符进行词性标注和分块，提取实体候选项
• concept-tfidf-rare-terms — 根据通用语料计算 IDF，从框架噪声中分离领域词汇
• concept-identifier-cooccurrence-network — 基于 PMI 加权的共现图揭示概念邻域
• concept-entity-name-resolution — 通过嵌入 + 编辑距离对名称变体（user/usr/u/userAccount）进行聚类
• concept-bounded-context-detection — 通过 Louvain + Jensen-Shannon 散度检测 DDD 限界上下文

2. 语义相似度与特性映射（关键）

• sim-codebert-embeddings — 使用 CodeBERT + 余弦相似度，在代码重命名后进行语义代码搜索
• sim-pdg-semantic-clones — 使用程序依赖图同构检测 Type-4 克隆
• sim-cross-pr-feature-mapping — 对已合并的 PR 进行一次嵌入，在特性设计阶段检索先例
• sim-cosine-vsm-files — 无 GPU 时使用 TF-IDF VSM 进行文件相似度分析
• sim-call-pattern-similarity — 对调用序列进行 N-gram 分析，查找行为相似的代码
• sim-doc-code-alignment — 联合嵌入代码与文档，标记文档和代码之间的偏差

3. 架构拓扑（高）

• graph-pagerank-core — 对导入关系图计算 PageRank，找出代码库的核心
• graph-betweenness-bottlenecks — 通过介数中心性找出瓶颈模块
• graph-louvain-modules — 使用 Louvain 社区检测揭示自然的模块边界
• graph-scc-cycle-tangles — 使用 Tarjan 的 SCC 算法揭示循环依赖纠缠
• graph-feedback-arcs — 使用 Eades-Lin-Smyth FAS 选取规模最小的断环边集

4. 协同变更与时间维度挖掘（高）

• mine-change-coupling — 根据提交历史计算条件概率，揭示隐藏的耦合关系
• mine-hotspots-churn-complexity — 代码变更量 × 复杂度 = 标准热点分数（Tornhill）
• mine-bus-factor — 计算每个文件作者贡献的基尼系数，揭示知识集中情况
• mine-commit-topic-modeling — 对提交消息进行 LDA 分析，揭示季度主题
• mine-bug-fix-density — 对提交分类，并按修复密度排列文件，找出缺陷高发点
• mine-codebase-aging — 结合最后修改时间与可达性，将稳定代码与死代码区分开来

5. 克隆与重复代码检测（中高）

• clone-minhash-lsh — 使用 MinHash + LSH，以次线性时间检索近似重复内容
• clone-simhash — 使用 SimHash 64 位指纹，进行 O(1) 海明距离查找
• clone-suffix-array-cpd — 使用基于词元的后缀数组（PMD CPD）精确定位克隆边界
• clone-ast-gumtree — 使用 GumTree 算法进行细粒度 AST 差异比较
• clone-zhang-shasha-ted — 使用 Zhang-Shasha 树编辑距离，精确比较子树相似度

6. Bug 与特性定位（中高）

• local-tfidf-bug-reports — 根据 Bug 报告中的词元，使用 TF-IDF 为源文件排序
• local-bm25-saturation — BM25 可处理长度归一化和 TF 饱和
• local-history-prior-localization — 将 IR 分数与 Bug 历史先验进行贝叶斯融合
• local-embedding-bug-text — 先使用 BM25，再通过嵌入重新排序，实现语义定位

7. 标识符语言学（中等）

• ling-camel-snake-split — 在任何分析前拆分 camelCase、snake_case 和数字边界
• ling-abbreviation-expansion — 通过词典和挖掘展开 idx→index、mgr→manager
• ling-porter-stemming — 应用 Porter 词干提取算法，统一单数和复数形式
• ling-pos-tagging-identifiers — 对标识符核心词进行词性标注，以标记命名不当的函数/类

8. 复杂度与风险指标（中等）

• risk-cyclomatic-mccabe — McCabe 圈复杂度，用于衡量分支测试范围
• risk-cognitive-complexity — SonarSource 认知复杂度，用于可读性门槛
• risk-halstead-volume — Halstead 体量，用于衡量与语言无关的规模和工作量
• risk-shannon-entropy-naming — 逐词元熵，用于标记含义过载的名称

使用方法

选择与用户问题匹配的类别，然后阅读该类别中的一两条具体规则。大多数规则都会引用可组合的配套规则（例如“与 mine-change-coupling 结合使用……”），这些规则可以增强信号；需要更高精度时，请阅读配套规则。

对于不熟悉的代码库，最具投资回报率的入门顺序是：

1. graph-pagerank-core → 阅读中心性最高的 20 个文件
2. concept-lda-topic-modeling + concept-tfidf-rare-terms → 识别业务主题
3. mine-hotspots-churn-complexity → 找出 Bug 集中的位置
4. mine-change-coupling → 揭示隐藏的架构耦合

对于单个任务的 Bug 修复或功能开发，流程如下：

1. local-bm25-saturation（广泛筛选候选项）→ local-embedding-bug-text（语义重新排序）→ local-history-prior-localization（提升修复历史相关项的优先级）
2. 使用 sim-cross-pr-feature-mapping 查找新功能的过往先例
3. 使用 mine-change-coupling 找出历史上经常共同变更的配套文件

在任何基于词汇的算法运行前，务必依次通过 ling-camel-snake-split → ling-abbreviation-expansion → ling-porter-stemming 对标识符词元进行预处理。跳过此步骤会悄然降低所有后续信号的质量。

跨语言解析。 为简洁起见，大多数规则代码示例使用 Python 内置的 ast 模块。对于真实的跨语言工作（在同一代码库中处理 Go、Rust、Java、TS、C++），请使用 tree-sitter——它为 40 多种语言提供稳健的解析器，并提供统一的 API。此技能中所有基于 AST 的规则（PDG 克隆、GumTree、Zhang-Shasha、词性标注核心词、标识符共现）都可以轻松映射到 tree-sitter AST。

参考文件

文件	描述
references/_sections.md	类别定义和影响排序
assets/templates/_template.md	添加新算法规则的模板
metadata.json	版本和参考信息