awslabs/codeknit

# codeknit 一个静态代码结构提取器。`codeknit` 解析源代码并将结构信息（函数、类、方法、关系）提取为适合 LLM 使用的紧凑中间表示。 ## 为什么需要 LLM 非常擅长生成代码，但在处理大规模重构时却显得力不从心。它们无法将整个代码库保留在上下文中，因此会忽略代码重复、不一致的模式以及架构漂移。 `codeknit` 通过将代码库转换为紧凑的结构图来解决此问题，该结构图仅关注代码骨架：函数签名、类层次结构、调用关系和模块边界。没有实现细节，也没有噪音。LLM 可以直接解析此表示，并针对数百个文件生成具体、有据可依的重构计划。 ## 支持的语言 C, C++, C#, Go, Java, JavaScript, PHP, Python, Ruby, Rust, Scala, TypeScript ## 安装说明 ### 从预编译二进制文件安装 预编译的二进制文件可在 [发布页面](https://github.com/awslabs/codeknit/releases) 获取，适用于 Linux、macOS 和 Windows（amd64 和 arm64 架构）。 下载适用于您平台的归档文件，将其解压，并将二进制文件移动到您的 `PATH` 中： ``` # macOS (Apple Silicon) — 根据需要调整 OS/arch 和版本 VERSION=0.1.0 OS=darwin # darwin, linux, or windows ARCH=arm64 # arm64 or amd64 curl -sSL -o codeknit.tar.gz \ "https://github.com/awslabs/codeknit/releases/download/v${VERSION}/codeknit_${VERSION}_${OS}_${ARCH}.tar.gz" tar -xzf codeknit.tar.gz sudo mv codeknit /usr/local/bin/ ``` 在 Windows 上，从发布页面下载 `..._windows_amd64.zip` 归档文件，将其解压，并将 `codeknit.exe` 移动到您 `PATH` 上的某个目录中。 根据发布的校验和验证下载的文件： ``` curl -sSL -O "https://github.com/awslabs/codeknit/releases/download/v${VERSION}/checksums.txt" sha256sum --ignore-missing -c checksums.txt ``` 然后确认其可以运行： ``` codeknit --version ``` ### 从源码安装 需要 Go 1.26+ 和 C 编译器（tree-sitter 需要 CGo）。 ``` git clone https://github.com/awslabs/codeknit.git cd codeknit make build # Binary 位于 ./bin/codeknit ``` ### 添加到您的 PATH 如果您将二进制文件安装在自定义位置而不是 `/usr/local/bin/`，请将其添加到您的 shell 配置中： ``` # bash (~/.bashrc) export PATH="$PATH:/path/to/codeknit" # zsh (~/.zshrc) export PATH="$PATH:/path/to/codeknit" # fish (~/.config/fish/config.fish) fish_add_path /path/to/codeknit ``` 重新加载您的 shell 或运行 `source ~/.bashrc`（或 `~/.zshrc`）以使更改生效。 验证其是否有效： ``` codeknit --version ``` ### Shell 自动补全 codeknit 支持 bash、zsh、fish 和 PowerShell 的自动补全： ``` # bash codeknit completion bash >> ~/.bashrc # zsh codeknit completion zsh >> ~/.zshrc # fish codeknit completion fish > ~/.config/fish/completions/codeknit.fish # PowerShell codeknit completion powershell >> $PROFILE ``` ## 使用方法 codeknit 有三个主要命令： - `codeknit parse` — 将结构信息提取到 `.skt` 文件中 - `codeknit fingerprint` — 使用模糊哈希检测重复和近似重复的代码 - `codeknit graph show` — 生成交互式 HTML 图表可视化 - `codeknit graph analyze` — 运行结构分析算法并输出可供 LLM 读取的报告 ### 解析代码库 ``` # 扁平目录输出（默认，写入 ./skeleton） codeknit parse ./myproject # 自定义输出目录 codeknit parse ./myproject ./output # 镜像树形目录输出 codeknit parse ./myproject ./output --output-mode directory-tree # 内联输出到 stdout codeknit parse ./myproject --output-mode inline ``` ### 交互模式 不带参数运行 `codeknit` 将启动交互式终端 UI，它将引导您完成所有可用的命令和选项。 ``` codeknit ``` ### 解析标志 ``` Flags: --output-mode string output mode: inline, directory-flat, directory-tree (default "directory-flat") --format string output format: skt, json (default "skt") --max-lines int maximum lines per output file (default 500) --collect-test include test files in analysis --minify enable dictionary-based output minification --edges include the [edges] section in output (off by default to save tokens) --clean remove stale .skt files from the output directory before writing --verbose print progress information during processing --workers int max concurrent parsing goroutines (0 = NumCPU) ``` 如果未指定，输出目录默认为 `./skeleton`。您可以通过传递第二个位置参数来覆盖它。在 `inline` 模式下，不使用输出目录——结果将输出到 stdout。 如果输出目录中已经包含上一次运行生成的 `.skt` 文件，codeknit 将拒绝写入，以避免新旧输出混淆。请使用 `--clean` 标志自动删除它们。 ### 解析示例 ``` # 包含 test files 并压缩输出 codeknit parse ./src --collect-test --minify # 包含关系边（默认关闭以节省 tokens） codeknit parse ./src --edges # 输出机器可读的 JSON 到 stdout codeknit parse ./src --output-mode inline --format json # 重新运行并覆盖之前的输出 codeknit parse ./src --clean # 自定义输出目录并采用树形布局 codeknit parse ./src ./out --output-mode directory-tree # 限制输出文件大小和并行度 codeknit parse ./src --max-lines 500 --workers 4 ``` ### 检测重复代码 ``` # 查找近似重复项（65-95% 相似度，默认） codeknit fingerprint ./myproject # 仅查找完全重复项 codeknit fingerprint ./myproject --min-similarity 100 # 查找中等相似度的代码（50-80%） codeknit fingerprint ./myproject --min-similarity 50 --max-similarity 80 # 语义重排序 — 通过 Ollama embeddings 过滤误报 # requires: ollama serve && ollama pull qwen3-embedding:0.6b codeknit fingerprint ./myproject --rerank # 使用不同模型进行语义重排序 codeknit fingerprint ./myproject --rerank --model qwen3-embedding:4b # 包含原始指纹列表 codeknit fingerprint ./myproject --show-all # 自定义输出文件 codeknit fingerprint ./myproject -o duplicates.skt ``` `fingerprint` 从每个函数、方法、变量和类型的规范化中间表示中计算模糊哈希——捕获语义操作（赋值、调用、比较、控制流），同时忽略变量名、字符串字面量和类型注解。这使得跨不同编程语言的重复检测成为可能。 ``` Flags: -o, --output string output file path (default: ./skeleton/fingerprints.skt) --min-similarity int minimum similarity percentage to report (0-100) (default 65) --max-similarity int maximum similarity percentage to report (0-100) (default 95) --show-all include the [fingerprints] section with raw token data --rerank rerank CTPH candidates with semantic embeddings via Ollama to eliminate false positives (requires: ollama serve && ollama pull qwen3-embedding:0.6b) --model string Ollama embedding model to use with --rerank (default: qwen3-embedding:0.6b) --collect-test include test files in analysis --workers int max concurrent parsing goroutines (0 = NumCPU) --verbose print progress information during processing ``` ### 可视化代码库结构 ``` # 生成交互式 HTML 图表（在浏览器中打开） codeknit graph show ./myproject # 自定义输出文件 codeknit graph show ./myproject -o graph.html # 包含 test files codeknit graph show ./src --collect-test ``` `graph show` 解析代码库并生成一个包含交互式图表可视化的独立 HTML 文件。符号（函数、类、类型）显示为节点，它们的关系（调用、包含、实现）显示为边。该文件会在您的默认浏览器中自动打开。 ``` Flags: -o, --output string output HTML file path (default: ./skeleton/codeknit-graph.html) --collect-test include test files in analysis --workers int max concurrent parsing goroutines (0 = NumCPU) --verbose print progress information during processing ``` ### 分析代码库结构 ``` # 使用默认设置运行结构分析 codeknit graph analyze ./myproject # 自定义输出和阈值 codeknit graph analyze ./myproject -o analysis.skt --fan-threshold 15 # 每个部分显示更多结果 codeknit graph analyze ./myproject --top-n 50 # 包含 test files codeknit graph analyze ./src --collect-test ``` `graph analyze` 对代码库运行结构图算法，并生成可供 LLM 读取的 `.skt` 报告。它可以检测代码质量问题，例如循环依赖、核心枢纽符号、死代码、上帝类、过深的继承链、瓶颈函数等。 算法包括：循环依赖检测（Tarjan 的 SCC）、核心枢纽检测（扇入/扇出耦合）、孤儿检测、上帝类/函数检测、不稳定性指标、深度继承链、介数中心性、关节点、PageRank、传递扇入（影响范围）、变更传播模拟、循环包依赖、层级违规检测、从入口点的可达性、弱连通分量、依赖权重以及与主序列的距离。 ``` Flags: -o, --output string output .skt file path (default: ./skeleton/graph_analysis.skt) --collect-test include test files in analysis --workers int max concurrent parsing goroutines (0 = NumCPU) --verbose print progress information during processing --fan-threshold int minimum fan-in or fan-out to flag a hub symbol (default 10) --god-threshold int minimum contains-edge count to flag a god class/function (default 15) --max-inheritance-depth int flag inheritance chains deeper than this (default 5) --top-n int cap ranked output sections; 0 = no limit (default 30) --betweenness-threshold float64 minimum betweenness centrality value to report (default 0.001) --propagation-cutoff float64 minimum probability to continue change propagation (default 0.05) ``` ## 与 AI 编程助手配合使用 `codeknit` 在 `skills/` 目录中自带了现成的技能，可以教 AI 编程助手如何有效地使用 codeknit。将它们安装到您的主目录中，以便在所有项目中都能使用： ``` # Kiro cp -r skills/codeknit-parse ~/.kiro/skills/codeknit-parse cp -r skills/codeknit-fingerprint ~/.kiro/skills/codeknit-fingerprint # Claude Code cp -r skills/codeknit-parse ~/.claude/skills/codeknit-parse cp -r skills/codeknit-fingerprint ~/.claude/skills/codeknit-fingerprint ``` 安装后，助手将知道如何调用 codeknit、选择正确的输出模式、读取 `.skt` 文件、使用结构图进行重构任务以及检测重复代码。无需额外的提示。 `codeknit-parse` 技能包括： - `SKILL.md` — 使用指南、标志、输出模式选择和工作流程 - `OUTPUT-FORMAT.md` — `.skt` 输出格式的完整参考 `codeknit-fingerprint` 技能教会助手如何使用 `fingerprint` 命令来查找重复和近似重复的代码。 ## 开发 ``` # 安装依赖 make deps # 构建 make build # 运行测试 make test # Lint 和格式化 make lint # Release（需要 git tag） git tag v1.0.0 git push --tags make release ``` ## 免责声明 本项目几乎完全使用 [Kiro](https://kiro.dev)（一款 AI 驱动的 IDE）构建。随后使用 codeknit 本身对代码库进行了迭代重构，以识别结构上的改进。 它并不适合用于生产环境，请利用它来进行实验，并规划如何借助 LLM 构建功能和进行重构。 ## 许可证 本项目基于 Apache License 2.0 授权。有关详细信息，请参阅 [LICENSE](LICENSE)。

标签：AI风险缓解, DLL 劫持, EVTX分析, SOC Prime, 代码结构提取, 代码重构, 多模态安全, 大语言模型, 开发工具, 弱口令爆破, 日志审计, 错误基检测, 静态代码分析