kaolegion/codebase-snapshot
GitHub: kaolegion/codebase-snapshot
将任意代码仓库转换为 AI 就绪的结构化快照，通过确定性规则分析项目架构、语义和依赖关系。
Stars: 0 | Forks: 0
# 代码库快照
确定性的 Shell 优先工具，可将任何软件仓库转换为 **AI 就绪的结构化快照**。
其目标是让人类和 AI 系统能够快速理解代码库，而无需浏览整个仓库。
快照解释了：
- 仓库中有什么
- 它是做什么用的
- 它的结构如何
- 执行从哪里开始
- 其主要模块和子系统是如何组织的
# 项目状态
版本：**v0.4.0**
当前功能：
- 确定性仓库扫描
- 仓库结构图
- 依赖提取
- 语义组件检测
- 仓库入口点检测
- 仓库用途推断
- 确定性仓库模块建模
- 确定性仓库子系统建模
- AI 就绪快照导出
- 确定性测试套件
# 快照产物
每次快照都会生成一个描述仓库的结构化包。
核心产物：
PROJECT_TREE.txt
INDEX.tsv
DEPENDENCIES.tsv
GRAPH.tsv
SEMANTICS.tsv
ENTRYPOINTS.tsv
MODULES.tsv
SUBSYSTEMS.tsv
PURPOSE.md
人类可读产物：
ARCHITECTURE.md
DOCUMENTATION.md
LANGUAGES.md
COMPONENTS.md
上下文产物：
MANIFEST.md
AI_INGESTION_GUIDE.md
运行时产物：
LOG.txt
SNAPSHOT_META.json
结构化代码导出：
CODEBASE/
# 仓库语义
语义层使用确定性规则对仓库文件进行分类。
每个文件接收四个语义信号：
- component（组件）
- group（分组）
- role（角色）
- rule（规则）
组件代表高层级的仓库区域，例如：
- cli
- core
- tests
- docs
- examples
- tools
- config
- root
- unknown
分组代表组件内部的功能子系统。
角色描述文件的操作角色，例如入口点、引擎、指南、测试或工具。
规则指示所使用的确定性检测信号。
产物：
SEMANTICS.tsv
- 机器可读的语义映射
COMPONENTS.md
- 人类可读的层级组件摘要
# 入口点检测
入口点用于识别仓库中执行开始的位置。
产物：
ENTRYPOINTS.tsv
检测信号包括：
- bin/*
- cmd/*
- main.*
- app.*
- server.*
- Makefile
- docker-compose.yml
- 根目录 Shell 脚本
# 仓库结构建模
结构建模层描述单个文件语义之上的仓库拓扑结构。
产物：
MODULES.tsv
- 仓库到主要架构模块的确定性映射
SUBSYSTEMS.tsv
- 这些模块内部稳定功能子系统的确定性映射
该层帮助 AI 系统不仅理解仓库文件，还能理解引擎本身的架构组织。
# 仓库用途推断
用途推断解释了 **仓库的用途是什么**。
产物：
PURPOSE.md
推断引擎检测：
- 仓库分类
- 操作角色
- 执行配置文件
- 支持该解释的结构信号
示例分类：
- cli_tool
- application
- service
- library
- automation_toolkit
- documentation_repository
- configuration_repository
- multi_purpose
- unknown
该系统是确定性的且基于规则。
# CLI 使用
基本用法：
bin/snapshot --target --label
标签：AI SDK, AI上下文, Cutter, Homebrew安装, LLM工具, RAG预处理, Shell脚本, 云安全监控, 仓库分析, 代码库快照, 代码挖掘, 代码理解, 依赖提取, 入口点检测, 威胁情报, 开发者工具, 技术债管理, 知识提取, 确定性分析, 结构化数据, 自动化文档, 软件架构, 防御加固, 静态分析