跳转到内容

分析可靠性

以下行为描述了 0.5.0 版本后未发布的 Go/CLI 变更。

所有五个源处理命令(parse、fingerprint、graph show、graph analyze 和 graph hotspots)接受以下参数:

参数 默认值 含义
--include GLOB 所有支持的源 包含匹配的源路径;可重复使用以选择多个模式。
--exclude GLOB 无 排除匹配的路径或目录;可重复使用以排除多个模式。
--max-file-size BYTES 10485760 (10 MiB) 跳过大于此大小的源文件;0 禁用此限制。
--strict false 如果扫描或解析诊断出现,则在输出结果前失败。

模式使用相对于所选输入目录的斜杠分隔的 gitignore 风格 glob。对于单文件输入,模式匹配其基本名称。对模式加引号以防止 shell 展开。包含模式形成并集;排除模式优先。包含模式不覆盖 .gitignore、测试过滤或内置排除项。这些参数不接受否定模式(!pattern);请使用单独的包含和排除控制。

终端窗口
codeknit parse ./src --include '**/*.go' --exclude '**/generated/' --strict
codeknit fingerprint ./src --max-file-size 2097152 --include '**/*.ts'
codeknit parse ./src/app.go --output-mode inline --format json

目录扫描遵循相对于其项目位置的祖先和嵌套 .gitignore 文件,与进程工作目录无关。最近的 .git 目录或工作树标记确定仓库边界。在仓库外部,祖先忽略文件仍然适用。被忽略目录下的选定子目录仍然被忽略。显式选择常规源文件会绕过忽略和测试过滤,但仍然应用包含/排除和大小限制。

源符号链接、目录符号链接和非常规源会被跳过并报告。读取限制在扫描根目录内,并且在读取时再次强制执行大小限制,因此在发现后增长的文件无法绕过限制。内置目录排除项包括 .git、.hg、.svn、node_modules、Python 缓存和常见的 Python 虚拟环境。除非设置 --collect-test,否则测试文件仍然被排除。

不可读的目录/文件、忽略文件读取失败、跳过的符号链接、过大的源文件和语法警告会导致分析不完整。默认情况下,可用的部分结果会被保留,诊断信息会出现在 stderr 上。解析 JSON 包含路径/原因记录在 errors 中;SKT 包含内联或在 warnings.skt 中的 [errors]。图/指纹命令也会在 stderr 上报告诊断信息。故意忽略或过滤的文件不会被视为警告。--strict 会在输出发布前拒绝不完整的结果。如果没有选定支持的源,或者每个源读取都失败,则始终以失败退出。

TUI 使用相同的符号链接策略和 10 MiB 默认值。其表单尚未公开新的选择和严格参数。

树输出将 .skt 附加到完整源名称:src/foo.c 变为 src/foo.c.skt,而 src/foo.h 变为 src/foo.h.skt。分割输出使用 src/foo.c_part1.skt、src/foo.c_part2.skt 等。字典和诊断文件保留保留名称 dict.skt 和 warnings.skt。输出路径冲突(包括仅大小写不同的冲突)会可见地失败。

树 SKT 要求 --max-lines 至少为 3。每个符号块重复其 [symbols] 和 ## source-path 标头。仅边块携带 [edges]。每个源块遵循限制;字典和诊断文件是单独的辅助输出。平面 SKT 保持源块完整,因此其行限制是分割目标而非大型源块的硬性限制。JSON 是单个文档,不按行数分割。

目录生成在同级临时目录中完成。未使用 --clean 时,选定格式的现有生成输出会导致错误。使用 --clean 时,过时的 .skt 文件(SKT 模式)或 codeknit.json(JSON 模式)仅在成功生成后被替换。不相关的条目会被保留;与其中一个发生冲突会导致错误。不要将源目录或其祖先用作输出目录。

发布持有目录特定的锁,备份先前的输出,并在替换失败时恢复。如果进程在目录重命名之间终止,下次调用会在生成任何内容之前恢复备份。同级 .NAME.codeknit.lock 文件有意保留以协调未来的发布者;不要移除活动锁或恢复备份。两次目录重命名之间存在短暂间隔,因此需要不间断访问的读取器应与生成协调。这提供了进程故障恢复,但不保证防止存储故障或断电。

各个报告被写入并同步到临时同级目录,然后替换目标。现有文件在生成期间不会被截断。内联 stdout 无法在消费者失败时回滚。

精确匹配指的是在相同符号类别中可进行指纹识别的声明之间,完全规范化的标记流相同。这并不意味着源文本相同或已证明的语义等价。精确候选组使用标记流本身,而非模糊哈希相等。

在符合条件的符号少于 500 个时,结构检测会比较所有同类别对。在 500 个或更多时,所有精确标记对会独立于候选检索被保留,其他对使用每个符号的近似前 50 个结构邻居。因此,近似重复检索在大型输入上不是穷举的。检索仍然扫描所有向量;它不会使整体算法次二次。

相似度范围过滤仍然适用。默认范围为 65–95%,这排除了 100% 匹配。要包含精确匹配,请使用:

终端窗口
codeknit fingerprint ./src --min-similarity 100 --max-similarity 100

可选的 --rerank 添加语义候选,应用余弦一致性,并根据组合分数进行过滤;它可以移除结构上精确的候选。嵌入文本来自用于提取的相同有界源快照。稳定的输入和固定分数会产生确定性的排序,包括平局;模型响应本身是外部输入。

internal/emitter/calibration_test.go 在 70% 阈值下评估一个小型标记源固件,报告真/假阳性和阴性、精确度和召回率,与相似度分数分开。该固件有一个精确对、两个近似克隆对和三个无关对,在 500 个符号边界内外进行测试。这是一个回归检查,而不是对真实世界准确性的代表性估计。更大的多语言校准和性能预算仍在路线图工作中。