The-Billy-Company/relate

# relate：基于压缩的代码相似度搜索 近似重复的文件、克隆家族，以及粘贴片段的来源——无需 embeddings，无需模型，无需向量数据库。 ## 它是什么 `relate` 源于 Gist 之后的一个问题。如果文本就是比特，并且压缩器能给重复的结构赋予更短的描述，那么我能否在生成一个压缩数据块之前停下来，转而返回共享该结构的事物？这就是将压缩作为搜索。 `gist` 询问的是 _"这个确切的模式在哪里？"_，而 `relate` 处理的是与之相邻的集合类问题：_这个东西像什么，这里重复了什么，哪些文件共同涵盖了一个主题，以及这段粘贴的文本来自哪里？_ 确切地说只有**两个关联性问题**，现在的界面也明确展示了这一点。`similar` 是**邻近动词**：一个探针，一个排序的答案。`echoes` 是**重复动词**：没有探针，对语料库自身进行调查。过去作为独立动词的一切——`search`、`dups`、`clusters`、`concepts`——都只是这两个问题之一的_角落_，通过一个 flag 而非名称来触达。现在，五个查询动词和两个生命周期动词道出了全部故事。 肯定的产品论点、数学渊源以及证伪记录分别保存在 `relate/research/relate/CLAIM.md`、 `relate/research/relate/PRIOR_ART.md` 和 `relate/research/relate/TESTING.md` 中。本 README 解释了这个已发布的工具；档案则解释了为什么压缩能支撑每一个动词。 ``` relate similar [--as copies|twins|shapes|any] [--unit file|function] [--matching PAT]... [--min-grade G] [--top N] [--json] [--no-index] [ROOT...] THE NEIGHBOR VERB — one probe, one ranked answer. The probe's own shape picks the question: a PATH scores compression kinship against every other unit; `path#Lnnn` scores the FUNCTION containing that line (and adopts --unit function and the shapes channel, because a 40-line body cannot fill an LZ78 dictionary the way a file can); bare TEXT scores coding gain — recall, "which files describe this most cheaply" — unless --as names a kinship channel, which turns the same text into a record to compare against. Ranking always returns rows, so each one is graded and a background-only answer says so on stderr instead of looking like a find relate echoes [--unit file|function|match] [--as copies|twins|shapes|any] [--shape pairs|families|distinct] [--max-distance T] [--min-echo E] [--min-size N] [--min-lines N] [--min-mass N] [--include-generated] [--matching PAT]... [--min-grade G] [--top N] [--brief] [--json] [--no-index] [ROOT...] THE REPETITION VERB — no probe: the corpus against itself, along three independent axes. --unit what a row IS file · function · match --as which repetition copies · twins · shapes · any --shape what the answer is FOR pairs · families · distinct The default (`file`, `twins`, `pairs`) is the DRY signal byte kinship cannot see: far apart in bytes, close in structure. Corners of the same cube are the four verbs this absorbed — `--as copies` is verified near-duplicate pairs, `+ --shape families` is their transitive closure, `--unit function --shape families` is the same idea cloned across files, and `--shape distinct` inverts the whole question into "what has no kin at all?" relate pack [--matching PAT]... [--match any|all] [-F] [-i] [--top N] [--json] [ROOT...] the SET of files that jointly describes cheapest; greedy max-coverage over corpus-priced query chunks; each pick priced by the bits it ADDS beyond the picks before it (anti-redundant context assembly). With --matching, novelty is priced INSIDE the exact filter and every pick names the patterns that admitted it relate quote [--json] rewrite as maximal verbatim quotations from the WHOLE corpus, priced in bits; the Ziv–Merhav cross-parse on the persisted codex shelf is O(|text|) after load; CLI latency also includes loading the shelf and checking filesystem freshness relate patterns -e P [-e P…] [-f FILE] [-F] [-i] [--by pattern|file] [--under GLOB] [--top N] [--json] [ROOT...] ONE walk, N patterns, exact per-pattern attribution, shaped engine-side (--by groups, --under filters, --top limits) relate index [--shelf] build + persist the kinship atlas (and, with --shelf, the codex shelf quote reads) relate status [--json] atlas + shelf readiness and freshness ``` ### 被合并的名称 四个动词作为名称已被弃用，但作为问题依然保留。输入它们不会触发未知命令错误——而是会以退出码 2 退出，并显示能回答该问题的调用方式： | 过去是 | 现在是 | | ----------------- | ------------------------------------------------------------ | | `search` | `relate similar ` | | `dups` | `relate echoes --as copies` | | `clusters` | `relate echoes --as copies --shape families` | | `concepts` | `relate echoes --as shapes --shape families --unit function` | | `irregex context` | `relate pack --matching PAT` | | `irregex family` | `relate echoes --matching PAT` | 最后两个是组合的合并：精确优先再压缩是 relate 已经提出的问题上的一个**修饰符**（`--matching`），而不是一个独立的并行二进制程序。 `irregex` 仅保留了两个动词，它们是真正的新组合，而不是过滤后的 relate 查询——即 `provenance` 和 `blast`。 此外，每个 irregex 界面都保留了相同的惯例：`--help` / `--version` / `--schema`（JSON 能力清单），结果输出到 stdout（`--json` = NDJSON），诊断信息输出到 stderr，未知动词以退出码 2 退出。 ## 人体工程学：先提出问题，再选择动词 Relate 是 irregex 的原生通道。它不保留 grep 语法，因为这些不是 grep 形态的问题。它的人机交互契约是每个动词对应一个问题，并包含用于范围、结果计数、机器输出和加速的少量共享词汇表。 | 如果你的直觉反应是… | 你真正想要的是什么 | 原生 Relate 选择 | | -------------------------------------------------- | ------------------------------------------- | ------------------------------------------------ | | 搜索几个模糊的词条并检查每个匹配项 | 最能解释某些文本的文件 | `relate similar TEXT` | | 收集一个 top-K 列表并手动去重 | 一个非冗余的上下文集 | `relate pack TEXT` | | 询问粘贴的段落来自何处 | 语料库归因的逐字来源 | `relate quote TEXT` | | 将一个文件与许多候选文件进行 diff | 最接近某个已知 unit 的 unit | `relate similar PATH` | | 询问你准备编写的 helper 是否已存在 | 最接近这一个的 FUNCTIONS | `relate similar PATH#Lnnn` | | 比较可能重复的文件 | 已验证的近似重复对 | `relate echoes --as copies` | | 自己重新连接重复对 | 完整的分叉家族 | `relate echoes --as copies --shape families` | | 错过了具有字节相似性的重命名复制粘贴 | 不同词汇下的共享结构 | `relate echoes`（默认） | | 查找在不同文件中重复的同一 FUNCTION | 函数级别的家族 | `relate echoes --unit function --shape families` | | 审计什么是真正独一无二的内容 | 每个家族的补集 | `relate echoes --shape distinct` | | 先 grep，然后在匹配项内进行推理 | 限定在精确过滤器内的压缩 | `… --matching PAT` | | 运行 N 个独立的精确搜索 | 针对 N 个模式的一次归因遍历 | `relate patterns -e A -e B …` | ### 默认操作 对于人类和编码 agent： 1. 确定你是否有**探针**（probe）。如果你想要某样事物的邻居，就是 `similar`；如果是语料库自身对比，就是 `echoes`。这一个问题就决定了动词，之后的一切都是 flag。 2. 对于 `echoes`，按照你实际思考的顺序命名这三个轴：一行是什么（`--unit`），你指的是哪种重复（`--as`），以及你要对答案做什么（`--shape` —— `pairs` 用于检查，`families` 用于采取行动，`distinct` 用于审计补集）。 3. 通过位置传递 roots 来限制语料库工作。使用 `--top N` 来限制人类输出，当其他工具或 agent 需要消费记录时使用 `--json`。 4. 让 atlas 加速关联动词。仅将 `--no-index` 用作实时的差异预言机，用 `relate status` 检查新鲜度，当你同时需要热态 atlas 和引文书架时，使用 `relate index --shelf`。 5. 按照各自的方向读取每个分数——并让 **grade** 替你完成。距离越小越近（`copies`/`shapes`/`any`）；对于 `twins` 差距和 `recall` coding gain 来说，数值越大越强；`pack` 报告每个新选择贡献的边际比特数。每一行都带有其自身极性的区间，因此你永远不必记住数值的发展方向。 ### 改变问题的小众选择 - **路径探针与文本探针：** 同一个动词，两种不同的度量方式，取决于你提供的内容。路径是一个**记录**——它有字节和骨架，因此可以进行对比，答案是一个距离。纯文本是一个**查询**——散文没有骨架可供对比，因此在它上面计算结构数值就等于计算虚无；它是通过相对于语料库的 coding gain 来定价的。在文本上命名 `--as` 会覆盖这一点，表示“不，把这段代码当作一个记录来处理”：当你粘贴代码并想知道什么与它的形状相似时，这是合理的。 - **片段探针采用其规模支持的通道：** `path#Lnnn` 将 unit 移至 `function`，在没有显式 `--as` 的情况下，也会将通道移至 `shapes`。在这个语料库上度量，一个函数最近的**字节**邻居位于 ~0.81——等级 `none`，与背景无法区分——而它最近的**轮廓**邻居位于 0.52，正是读者在寻找的同级实现。40 行的函数体无法像文件那样填满 LZ78 字典，因此将标识符归一化才是留下任何信号的根本。 - **排序与调查与集合：** `similar` 针对一个探针独立对候选项进行排序。`echoes` 没有探针——它对语料库自身进行调查。`pack` 选择一个_集合_，其成员只需为未被先前选择覆盖的信息付费。在组装上下文时使用 `pack`，在期望独立排序作为输出时使用 `similar`。 - **统一通道词汇：** 每个关联动词读取相同的 `--as` 通道。`copies`（默认）尊重词汇表并寻找复制粘贴的漂移；`shapes` 归一化标识符、数字、字符串和注释，从而让重命名的双胞胎浮出水面；`twins` 对这两个之间的差距进行排序，这就是 `echoes` 信号；`any` 接受看到更强关联的通道。度量名称 `bytes`/`structure`/`echo`/`fused` 仍然作为 `--lens` 的别名被接受——它们是同一个枚举的不同拼写，而不是第二条路径。`recall` 是唯一一个 flag 无法命名的通道：它是通过将文本而非路径传递给动词来选择的，因为让文件充当查询是一个披着 flag 外衣的范畴错误。 - **等级，让背景永远不会被解读为匹配：** 排序动词总是返回行，这就是为什么一个没有真正关联的答案过去看起来完全像是一个查找结果。现在每个分数都对照本 README 记录的阈值进行了分区间处理（`identical`/`strong`/`moderate`/`weak`/`none`），该区间随每行 `--json` 输出，`--min-grade G` 隐藏任何弱于 `G` 的内容，而完全属于背景的答案会在 stderr 上用 gist 的提示语法进行自我解释（`GIST_HINTS=0` 可静音）。一个被修剪但真实的答案会报告它隐藏了什么，而不会推翻该发现。 - **对、家族和补集：** `--shape pairs`（带有 `--max-distance T`，或在差距通道上使用 `--min-echo E`）验证处于或超过阈值的指定对。种子桶是概率性的且有上限，因此这保证了输出对的精确度，而不是详尽无遗的召回率。`--shape families` 返回该已输出图的传递组件——这是重构扫描实际操作的 unit——并接受 `--min-size N`；一个家族按其**最松散的**边缘进行评级，因此一个弱链接不能隐藏在一个强 cluster 中。`--shape distinct` 颠倒了整个问题：没有接纳边缘的 unit，每个都带有其最近的未匹配项作为它为何孤独的凭证。默认通道保持在 `twins` 差距上，而不是假装结构有一个通用的重复阈值。 - **底噪是针对 unit 的，而不是针对动词的：** 调查应用一个质量下限（太小而无法进行指纹识别的文件否则会以距离 0 相互配对，因为两个空的 sketch 确实是相同的），并且在 `--unit function` 时，应用一个行下限。生成的文件默认在调查中被排除——代码生成树_理应_重复，如果留在其中，会淹没所有原创的发现——而 `--include-generated` 将其重新变回问题（“生成器是否发生了漂移？”）。探针保留生成的候选项，因为“什么与这个相似”有一个合理的生成答案。 - **模式归因：** `patterns` 保留哪个模式命中了哪一行。使用重复的 `-e`、`-f FILE`、`-F` 和 `-i` 进行匹配；`--by pattern|file` 对计数进行分组，`--under GLOB` 过滤路径，`--top N` 在引擎端限制结果。 - **引用需要书架：** `quote` 读取整个持久化的 codex，而不是 root 范围的实时的语料库。使用 `relate index --shelf` 构建它；过期的书架会被报告出来，而不是被静默当作最新处理。 - **精确优先，压缩在内部（`--matching`）：** 每个查询动词接受重复的 `--matching PAT`（加上 `--match any|all`、`-F`、`-i`）。精确引擎将语料库缩小到一个类型化的候选集，然后**仅在该子集内部**提出压缩问题——因此统计数据的定价是针对匹配的文件，而不是针对 2 万个陌生人，并且每个选择都可以命名接纳它的模式。这就是已弃用的 `irregex context` / `irregex family` 动词所做的一切；组合是一个修饰符，而不是第二个二进制程序。 - **热覆盖是特定于动词的：** 文本探针和 `pack` 从 Gist 的 mmap 支持的 trigram 索引中提名，然后通过相同的新鲜度叠加折叠修改过的文件；每个关联性问题都读取关联性 atlas（并且在 `--unit function` 时，读取并行的片段 atlas）。当加载全局 atlas 成本更高时，狭窄的显式关联范围会实时重建。缺失或损坏的加速只会改变成本，永远不会改变结果。 - **语料库准入与 Gist 共享：** 位置 roots、嵌套的 `.gitignore` / `.ignore` / `.rgignore` 优先级、隐藏文件排除和新鲜度准入都使用相同的语料库层匹配器。Relate 仅添加特定于语料库的 VCS/构建跳过。 - **分数在边界上是诚实的：** 负的 recall 分数意味着候选项对文本的描述比冷编码更差，而不是一个错误。`pack` 报告外部指纹，而不是假装语料库覆盖了它们，`quote` 对未知文本定价，而不是强制归因。 - **确定性的机器使用：** `--json` 在 stdout 上输出 NDJSON，而诊断信息保留在 stderr 上。Pair、family 和 pattern 输出具有稳定的顺序，因此 agent 应该解析记录，而不是抓取散文。 已提交的 `relate/contract/kinship.toml` 是版本化的动词契约。以下各节解释了每个选择背后的数学原理、语料库策略和证据。 此目录仅是界面。`repertoire.zig` 声明了一次性动词表面——每一行都带有其使用形式、人类简介、机器摘要、类型化 flags 以及运行它的 handler——而 [`surface/cli/manifest.zig`](https://github.com/The-Billy-Company/gist/blob/main/src/surface/cli/manifest.zig) 从该表中渲染出 `--help`、`--schema`、调度、未知动词行，**以及进程本身**。因此 `main.zig` 根本不包含任何表面：它命名其 repertoire 然后移交。工作存在于五个同级的 driver 中——`probe.zig`（邻近动词）· `repeat.zig`（重复动词）· `pack.zig` · `quote.zig` · `attribute.zig`——加上 `lifecycle.zig`，位于三个共享层之上，这三个共享层的存在恰恰是因为两个关联动词过去重复了它们：`options.zig` 将一个 flag 词汇表解析为一个 `Opts`，`units.zig` 将任何 `unit × warmth × optional exact filter` 解析为一个比较表，`kinship.zig` 包含并行的指纹识别和配对机制。评分、排序、评级和最终结论通过 [`surface/cli/grade.zig`](https://github.com/The-Billy-Company/gist/blob/main/src/surface/cli/grade.zig) 的 `Sift` 共享，因此一个动词只需贡献其问题。引擎位于 `relate/src/kernel/kinship/` （sketch · silhouette · concepts · lexicon · zipper）、 `irregex/src/kernel/slate/` （patterns · loom）、`relate/src/kernel/codex/`（FM 数学）+ `relate/src/corpus/index/shelf/>`（位于 `quote` 背后的持久化 SHLF），以及 `relate/src/corpus/index/atlas/`（位于热动词背后的持久化关联性 atlas）。 ## 热层：为什么 relate 是一个引擎，而不是一个垫片 我将每个语料库文件的一个 LZJD sketch（~1 KiB）和一个结构 silhouette（~2 KiB）持久化到 **kinship atlas** 中。然后，一个广泛的 `similar` 或 `echoes` 查询可以读取压缩视图，而不是重新读取语料库；狭窄的显式范围采用更廉价的实时路径。文本探针和 `pack` 重用 Gist 持久化的 trigram 索引进行提名，并且仅读取有界的精确决策器池。`--unit function` 读取一个并行的 **fragment atlas**（`concepts.frag`）：每个函数片段一个结构 silhouette，以相同的方式折叠以保持新鲜，因此函数级别的问题也能在热态下得到解答——字节 sketch 是那里唯一的实时读取，并且仅针对带有字节的通道实际提名的片段。提交的契约是有用的当前字节答案，而不是永恒的速度比：在你在意的语料库和机器上测量这两个层级。 我与 Gist 保持着相同的契约：index 是加速器，绝不是权威。查询会叠加自构建锚点以来更改的每个文件，输出的行会针对删除进行检查，并且 `--no-index` 或缺失/损坏的状态会回退到实时工作。recall 路径的精确决策器会看到查询证据周围的有界窗口，而不是在数 MiB 的文件上构建后缀自动机，因此 top-K 延迟受查询和证据池大小限制，而不是受语料库总字节数限制。 ## 为什么是这些动词 我一直在观察 agent 在引擎外重建相同的工作流。每个动词都将其中一个循环拉入内核。其中两个过去各有四个动词名称；它们回答的问题没有改变，所以对它的论点保留在现在承载它的名称下： - **`patterns`** 折叠了 N 次运行的循环。融合的 alternation 仅为一个跳过门；它本身无法满足真正的契约：`PatternSet` 答案必须在位级别上与 N 次独立的 Gist 运行完全相等，并且预过滤器被强制开启和关闭。`patterns_test.zig` 门控精确度；`bench/races/multipattern.sh` 是临时的吞吐量竞赛，而不是承诺的性能证明。 - **`pack`** 回答了一个独立 top-K 无法回答的问题：排序列表可能会同时浮现近似重复项，因此 agent 会为相同的信息支付 K 次费用。基于语料库定价的查询块的覆盖是子模的，因此贪婪扫描是该目标的 (1−1/e) 近似（Nemhauser–Wolsey–Fisher 1978），并输出精确的边际比特凭证。支持集合感知的 RAG 也是现有技术；Relate 的独特之处在于其无需模型、可审计的比特目标。 - **`similar`** 使关联性成为原语，而不是每个工具的 hack：交给它一个东西，得到它的邻居。字节关联性没有解析器或语言注册表；结构通道增加了一种跨语言的 token 审视，而不是每种语言单独的 AST。将检索折叠进来并不是为了整洁——文本探针和路径探针是跨越两种探针的_相同_请求（“语料库中什么在这个附近？”），将它们作为两个动词意味着 agent 必须在提问之前知道自己持有的是哪个名词。 - **`echoes`** 是该原语的调查形态，它是一个动词而不是四个的原因是，`dups`、`clusters` 和 `concepts` 从来不是不同的问题——它们是具有不同 unit、不同通道和不同输出形态的相同比较。单独命名它们迫使调用者知道哪个角落被赋予了名称（根本没有 `--unit function --shape pairs` 动词，尽管这个问题非常合理），并且它将分数-排序-评级-输出-报告流程重复了四次：`echoes.zig` 和 `similar.zig` 存在 0.2180 的结构差距——这是本目录中第二大的差距——这正是从外部衡量该共享流程的结果。其默认通道报告的是原始通道无法单独说明的内容。字节关联性将重命名的双胞胎称为不相关；单独的结构距离没有干净的绝对阈值（测量值：在每个 winnow 设置下的 family-max 与 cross-min 重叠）。_差异_——`echo = bytes − structure`——是针对每对进行自校准的：高 echo 意味着“共享的形状远远多于共享的词汇”，即抽象应该折叠的类型 2 克隆。结构通道是基于归一化 token 流（标识符→I，数字→N，字符串→S，注释被丢弃，保留跨语言关键字）的 MOSS 风格 winnowed shingles——一种跨语言的审视，而不是针对每种语言的解析。 - **`--unit function`** 将关联性从文件降到了 FUNCTION 层面。文件回答的是“什么从什么分叉而来？”；agent 提出的更细致的问题是“不管名称或文件如何，整个树中哪些函数是同一个想法——重复的引擎、重复的 JSON 转储、复制粘贴的验证器？” 比较的 unit 变成了函数片段（`regions.extractAll` 作用于原创的大括号家族 + Python 源代码），因此克隆到六个文件中的 helper 会作为一个六成员家族浮现出来，而不是隐藏在六个不相关的文件中。它重用了相同的通道、相同的种子提名和 union-find 过程，以及相同的热折叠准则——是在片段 atlas 上而不是文件 atlas 上。家族按保守的重复行机会排序，绝不是融合的相似度数值，并且通道并排放置，以便读者判断关系。 - **`quote`** 是语料库全局层级：语料库知道的文本报价为 **0.14–0.17 bits/byte**，外部字节报价为 **12.65–15.16**（在已提交的扩展表中）——**88–94 倍**的差距。每个短语都归因于一个样本文件，查询工作量与文本长度成线性关系（`zig build codex-scale`，表位于 `relate/src/kernel/codex/README.md`）。 - **`recall` 通道** 是同一想法的检索形态，它存在于 `similar` 内部，因为这是带有查询而非探针的相同请求：根据每个文件描述文本的廉价程度对文件进行排序，分两阶段进行，以便精确（昂贵）的决策器仅对提名的候选项定价。 - **`--matching`** 是组合。 手动拼装的 `gist -l | relate …` 管道在两个步骤之间丢弃了匹配信息，然后在子集上付出了整个语料库的统计噪音；在内核内部进行缩小，将精确分数和统计分数保持在不同的字段中，针对候选集对新颖性进行定价，并允许每一行命名接纳它的模式。它们各自的组合动词对于此事来说变成了错误的形态：`context` 是缩小范围的 `pack`，`family` 是缩小范围的 `echoes`，所以现在两者都成为了 flag。 ## 证据状态 证明强度有意设置得不均匀且保持透明： | 声明 | 权威来源 | 状态 | | --------------------------------------- | ------------------------------------------------------------- | ------------------------------------- | | `patterns` 等同于 N 次单独的 Gist 运行 | irregex `src/kernel/slate/patterns_test.zig`，预过滤器开启/关闭 | 已门控（在库中） | | 两个预过滤器层级都等同于该预言机 | irregex `src/kernel/slate/trawl_test.zig`，强制每个层级 | 已门控（dragnet 和 trawl，在每个 N 值下） | | `patterns` 回答了 `gist -l` 语料库 | gist `bench/conformance/gates/parity/patterns_corpus_parity.sh` | 已门控（index 武装和剥离） | | 热 atlas 等同于 `--no-index` | atlas fold/deletion 测试 | 已门控 | | quote 扩展和位分离 | `zig build codex-scale` + codex 表 | 已提交的度量 | | 压缩与语义 embeddings 对比 | `bench/conformance/relate/knn.zig` | 仅有测试框架——此处无带标签语料库 | | 热延迟 | 仅本地比较 | 无已提交的计时 artifact | | echo 排序质量 | 启发式 + unit 属性 | 无已签入的带标签评估 | 前三行在拥有该代码的包中是受门控的——N-pattern slate 属于库，而语料库一致性门控属于产品机箱——因此仅克隆此 repo 并不会运行它们。持久的测试清单位于 [`research/relate/TESTING.md`](research/relate/TESTING.md)。 没有已提交 artifact 的数字不会成为产品保证。 ## 语料库策略：在与 `gist` 比较之前阅读此内容 我在这里做出了两个刻意的决定，两者都在接口处有记录： - **relate 分析读取 INDEX 语料库**（roots 下的每个非二进制文件减去 VCS/构建子树，即 `gist index` 使用的比 gitignore 更宽泛的策略），因为它们是语料库分析，而不是逐文件的 grep。`gist ` 保留与 rg 一致的 gitignore 遍历。这两个文件集有意不完全相同（`verbs.zig` 头文件）。 - **`quote` 读取持久化的书架**（`relate index --shelf`，即 `gist codex build` 写入的相同 artifact；一个书架，两个产品界面），而不是按调用构建：只有当 index 确实跨越了语料库时，交叉解析才是语料库全局的，并且 FM-index 构建是生命周期事件，而不是查询成本。过时状态在 stderr 上报告，方式与 `gist codex` 报告它的方式相同（`quote.zig` 头文件）。 ## 研究主张与现有技术 我没有发明这套数学。核心火花来自 Benedetto、Caglioti 和 Loreto 的 [_Language Trees and Zipping_](https://doi.org/10.1103/PhysRevLett.88.048702) (Phys. Rev. Lett. 2002)：使用压缩器定义的相对熵来衡量一种文本的语言描述另一种文本的程度。那篇论文对我来说将压缩从存储变成了比较。 针对文件、集合、家族和来源的正面案例位于 `relate/research/relate/CLAIM.md`。完整的引文轨迹——LZJD、winnowing/MOSS、Ziv–Merhav、FM-indexes、子模选择，以及我们测量并放弃的相邻系统——位于 `relate/research/relate/PRIOR_ART.md`。精确度、atlas 一致性、embedding 边界和重现命令位于 `relate/research/relate/TESTING.md`。 我在这里的贡献是经过测量的组合，而不是定理。此内核中更强颖数学主张是 Gist 的 Crest sieve (`irregex/research/crest/PROOF.md`)。 ## 布局 - `src/kernel/kinship/` - metric · cluster · recall - `src/kernel/anatomy/` - 结构 silhouettes（“shapes” 通道） - `src/kernel/codex/` - 压缩 codebook + FM-index（vendored libsais） - `src/kernel/compose/` - 组合查询：blast radius、 provenance、`--matching` 候选者、family、regions（驱动 `blast` 界面的引擎） - `src/corpus/index/{atlas,frag,shelf}/` - 持久化的 artifact： 文件 kinship atlas、函数 fragment atlas、codex 书架 - `src/exec/retrieval/` - 通过 coding gain 进行文本探针检索 - `src/exec/session/warm/` - 热层：将修改过的文件折叠到 持久化的 atlas 中，与冷重建字节一致 - 动词表面 / CLI - `src/surface/face/` ## 安装 CLI 是产品，它由 Zig 从源代码构建。在 Windows 上，PowerShell 安装程序构建二进制文件，将其放在用户 PATH 上而无需提权，并创建 atlas： ``` .\install.ps1 ``` 当 setup 不应触碰语料库时传递 `-NoIndex`；每个查询仍然具有正确的实时路径。 语言绑定已发布，每一个都驱动相同的二进制文件而不是重新实现它，因此 CLI 是这三者的先决条件： | | Install | 你编写 | |---|---|---| | Python | `pip install relate-search` | `import relate` | | Rust | `cargo add relate-search` | `use relate::…` | | Go | `go get github.com/The-Billy-Company/relate/bindings/go` | `import ".../bindings/go"` | 裸名 `relate` 在 PyPI 和 crates.io 上都已被占用，那里的名称是永久性的，因此分发版带有 `-search` 后缀，而你输入的标识符保持 `relate` 不变——就像 bs4 / PIL 的拆分一样。这三者都拉取共享底层，即 PyPI 上的 `irregex` 和 crates.io 上的 `irgx`。特定语言的详细信息位于 [`bindings/python`](bindings/python/README.md)、 [`bindings/rust`](bindings/rust/README.md) 和 [`bindings/go`](bindings/go/README.md) 中。 ## 构建和测试 Zig 0.16，无网络；libsais 从 `vendor/libsais/` 构建（zon 条目是 `.lazy` url + hash pin，仅供溯源）。 ``` zig build check # compile everything, run nothing zig build test # the unit suite zig build coverage # per-function coverage ``` ## 使用 ``` // build.zig.zon .relate = .{ .path = "../relate" }, // dev: sibling checkout // releases pin url + hash ``` 依赖于 `irregex`——该库——用于语料库遍历、 `--matching` 背后的模式引擎以及共享原语。 架构由 `contract/relate.ward` 进行机器检查。 ## 溯源 从私有 monorepo 内部的包路径中提取 （切点为 ce430bbaab）。引擎最初作为内核的 kinship/codex 层诞生，并在调优边界处分离：一切针对相同的语料库统计数据进行定价的内容都留在这里，在一起。 Apache-2.0；`NOTICE` 归功于 vendored libsais。

标签：SOC Prime, 代码克隆分析, 代码搜索, 压缩算法, 可视化界面, 开发工具, 文件比对, 文档结构分析, 相似度检测