# AxiomDemo
**Repository Path**: vpacking/axiom-demo
## Basic Information
- **Project Name**: AxiomDemo
- **Description**: 将 spec → api → code 建模为显式、可追溯、可约束的工程事实，并以此约束工程变更行为。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-02-17
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Axiom - Engineering Fact & Guardrail System with AI
**本地 AI 驱动的工程约束系统**
[]
[]
[]
提供语义索引、影响分析、补丁验证等工程辅助功能
## 📖 目录
- [特性](#-特性)
- [快速开始](#-快速开始)
- [详细使用](#-详细使用)
- [架构设计](#-架构设计)
- [配置说明](#-配置说明)
- [开发指南](#-开发指南)
- [常见问题](#-常见问题)
## ✨ 特性
Axiom 是一个本地运行的 AI 驱动工程工具，提供以下核心能力：
### 🔍 语义搜索
- 基于向量的语义搜索，理解代码意图而非仅匹配关键字
- 支持 Rust 代码、Markdown 文档、OpenAPI 规范的索引
- 实时相似度计算，返回最相关的代码片段
### 📊 影响分析
- **正向分析**：查看修改某个函数/模块会影响哪些其他代码
- **反向分析**：查看哪些代码依赖于当前节点
- **双向分析**：完整的依赖关系视图
- 支持深度控制和置信度过滤
### 🔒 补丁验证
- 验证代码变更是否符合工程约束
- 支持多种验证模式（strict/lenient/warn）
- 增量式验证，适合 CI/CD 集成
### 📈 为什么分析
- 理解节点间的依赖关系
- 支持查询和追踪依赖路径
- 识别关键依赖链路
### 🧩 MCP 服务器
- 提供 Model Context Protocol 集成
- 支持 AI Agent 调用
- 可扩展的插件架构
### 🧹 数据清理
- 清理数据库和索引数据
- 支持选择性清理（向量/图/缓存）
- 安全的确认机制
## 🚀 快速开始
### 环境要求
- Rust 1.74+
- SQLite 3
- 约 2GB 磁盘空间（用于模型文件）
### 安装
```bash
# 克隆仓库
git clone
cd axiom
# 编译
cargo build --release
# 安装到本地
cargo install --path .
```
### 下载模型
```bash
# 参考 scripts/download_model.py 下载模型
# 默认使用 bge-small-zh-v1.5 模型（中文优化）
# 模型文件应放置在 ./models/ 目录下：
# ./models/bge-small-zh-v1.5/
# ├── config.json
# ├── model.safetensors
# ├── tokenizer.json
# └── ...
```
### 初始化项目
```bash
# 在你的项目根目录
ax init
# 这会创建：
# - .axiom/ 目录
# - axiom.toml 配置文件
```
### 首次索引
```bash
# 索引项目并生成 embeddings
ax index --embed
# 这会：
# 1. 扫描所有代码文件
# 2. 生成语义向量
# 3. 构建依赖图
# 4. 存储 SQLite 数据库
```
### 基本使用
```bash
# 语义搜索
ax search "如何处理用户登录"
# 影响分析
ax impact "fn_authenticate" --depth 5
# 查看状态
ax status --verbose
# 清理数据
ax clean
```
## 📚 详细使用
### 1. `ax init` - 初始化项目
创建 `.axiom` 目录和配置文件。
```bash
ax init [OPTIONS]
# 选项：
# -p, --path 项目路径 [default: .]
# 示例
ax init
ax init --path /path/to/project
```
**生成的文件结构**：
```
your-project/
├── .axiom/
│ ├── axiom.toml # 配置文件
│ ├── axiom.db # SQLite 数据库（索引后生成）
│ ├── vectors/ # 向量索引（索引后生成）
│ └── index_cache.json # 增量索引缓存（可选）
├── src/
└── README.md
```
### 2. `ax index` - 索引项目
扫描项目文件并构建索引。
```bash
ax index [OPTIONS]
# 选项：
# -p, --path 项目路径 [default: .]
# -i, --incremental 增量索引（只索引变更文件）
# -f, --force 强制重新索引
# --embed 生成 embeddings [default: true]
# 示例
ax index --embed # 完整索引 + embeddings（当前目录）
ax index --force # 强制重新索引
ax index --path src/ --incremental # 增量索引 src/ 目录
```
**索引器支持**：
- Rust 代码 (`.rs`) - 函数、结构体、枚举、trait、模块等
- Markdown 文档 (`.md`) - 文档章节
- OpenAPI 规范 (`.yaml`, `.yml`, `.json`) - API 端点
### 3. `ax search` - 语义搜索
基于语义相似度搜索代码。
```bash
ax search [OPTIONS]
# 选项：
# -l, --limit <数量> 返回结果数 [default: 10]
# -t, --threshold <分数> 相似度阈值 [default: 0.6]
# -v, --verbose 显示详细信息
# -k, --kind <类型> 按类型过滤 (doc, api, code)
# 示例
ax search "用户认证"
ax search "database connection" --limit 5
ax search "API endpoint" --threshold 0.8
ax search "function to parse JSON" --verbose
ax search "文档" --kind doc
```
**输出格式**：
```
[1] 0.8562 - src/core/engine.rs:42
[2] 0.7821 - src/parsing/rust_indexer.rs:130
[3] 0.6543 - src/storage/db.rs:100
```
使用 `--verbose` 查看详细信息：
```
[1] 0.8562 - src/core/engine.rs:42
📝 fn_index_project
Content: /// Index a project directory...
```
### 4. `ax impact` - 影响分析
分析代码变更的影响范围。
```bash
ax impact [OPTIONS]
# 选项：
# -n, --node <节点> 节点 ID
# -d, --depth <深度> 最大遍历深度 [default: 10]
# --semantic 包含语义关系 [default: true]
# 示例
ax impact --node "fn_main"
ax impact --node "fn_authenticate" --depth 5
ax impact --node "api_user_list" --semantic
```
**输出示例**：
```
📊 Analyzing impact...
Node: fn_main
Max depth: 5
Include semantic: no
Found node: fn_main_code_main_rs_42
✅ Impact analysis complete
Total impacted nodes: 3
Max depth reached: 2
By edge type:
- Calls: 2
- Implements: 1
Impacted nodes:
[depth 1] ✓ Calls - src/core/engine.rs:42
[depth 2] ✓ Calls - src/storage/db.rs:100
[depth 2] ✓ References - src/models/chunk.rs:15
```
**影响类型图标**：
- `✓` - 显式关系（代码引用）
- `?` - 启发式关系（推断）
- `~` - 语义关系（相似度）
### 5. `ax patch` - 补丁验证
验证代码变更是否符合工程约束。
```bash
ax patch [OPTIONS]
# 选项：
# -b, --base [ Git ref
# -m, --mode <模式> 验证模式：strict/lenient/warn [default: strict]
# strict - 严格模式，任何违规都失败
# lenient - 宽松模式，只报告
# warn - 警告模式，总是成功
# 示例
ax patch --base main --mode strict
ax patch --base HEAD~1 --mode lenient
```
**验证规则**：
- API 兼容性检查
- 代码风格一致性
- 依赖关系验证
- 自定义规则支持
### 6. `ax why` - 为什么分析
解释节点之间的依赖关系。
```bash
ax why [OPTIONS]
# 选项：
# -n, --node <节点> 节点 ID
# 示例
ax why --node "fn_main"
ax why --node "UserRepository"
```
### 7. `ax status` - 查看状态
显示索引和系统状态。
```bash
ax status [OPTIONS]
# 选项：
# -v, --verbose 显示详细信息
# 示例
ax status
ax status --verbose
```
**输出示例**：
```
✅ Axiom Status
📁 Database: .axiom/axiom.db
📊 Chunks: 1,234
📈 Embeddings: 1,234
📝 Files Indexed: 45
```
### 8. `ax clean` - 清理数据
清理数据库和索引数据。
```bash
ax clean [OPTIONS]
# 选项：
# -p, --path 项目路径 [default: .]
# --vectors 只清理向量数据
# --graph 只清理图数据
# --cache 只清理索引缓存
# -f, --force 强制清理（不询问）
# 示例
ax clean # 清理所有数据（需确认）
ax clean --force # 强制清理所有数据
ax clean --vectors # 只清理向量数据
ax clean --graph --cache # 清理图和缓存
```
**清理的内容**：
- **Database**: 清空 `chunks` 和 `embeddings` 表（保留表结构）
- **Vector store**: 删除 `.axiom/vectors/` 目录
- **Graph data**: 删除 `.axiom/graph/` 目录
- **Index cache**: 删除 `.axiom/index_cache.json`
### 9. `ax mcp` - MCP 服务器
启动 Model Context Protocol 服务器。
```bash
ax mcp
# 子命令：
# start 启动 MCP 服务器
# test 测试 MCP 连接
# list-tools 列出可用工具
# 示例
ax mcp start
ax mcp start --addr 127.0.0.1:3000
ax mcp test
ax mcp list-tools
```
## 🏗️ 架构设计
### 系统架构
```
┌─────────────────────────────────────────────────┐
│ CLI │
│ (ax init, index, search, impact, clean, etc.) │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ Core Layer │
│ ┌──────────────┐ ┌─────────────┐ │
│ │ Indexer │ │ ImpactAnalyzer│ │
│ │ │ │ │ │
│ │ RustIndexer │ │ Validator │ │
│ │ MarkdownIndexer│ │ │ │
│ │ OpenAPIIndexer│ └─────────────┘ │
│ └──────────────┘ │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ Storage Layer │
│ ┌───────────────┐ ┌──────────────────┐ │
│ │ ChunkStore │ │ GraphStore │ │
│ │ (SQLite) │ │ (SQLite) │ │
│ └───────────────┘ └──────────────────┘ │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ AI Layer │
│ ┌──────────────────────────────────┐ │
│ │ Embedding Model (Candle) │ │
│ │ bge-small-zh-v1.5 (512 dim) │ │
│ │ bge-large-zh-v1.5 (1024 dim) │ │
│ │ bge-m3 (1024 dim, multilingual)│ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
```
### 模块组织
```
src/
├── main.rs # CLI 入口
├── cli/ # 命令行解析
│ └── commands.rs # 命令定义
├── core/ # 核心逻辑
│ ├── engine.rs # 索引引擎
│ ├── indexer.rs # 索引器定义
│ ├── impact.rs # 影响分析
│ ├── validator.rs # 补丁验证
│ └── why.rs # 为什么分析
├── parsing/ # 解析器
│ ├── code/ # 代码语言索引器
│ │ └── rust.rs # Rust 解析器
│ ├── markdown_indexer.rs
│ └── openapi_indexer.rs
├── models/ # 数据模型
│ ├── chunk.rs # Chunk 模型
│ ├── edge.rs # Edge 模型
│ └── node.rs # Node 模型
├── storage/ # 存储层
│ ├── chunk_store.rs # Chunk 存储
│ └── graph_store.rs # Graph 存储
├── ai/ # AI 功能
│ └── embeddings/ # 向量嵌入
│ ├── config.rs # 模型配置
│ ├── factory.rs # 模型工厂
│ ├── loader.rs # 模型加载
│ └── bge_small_zh.rs # BGE 模型实现
├── mcp/ # MCP 服务器
└── error.rs # 错误处理
```
### 数据模型
**Chunk（代码块）**
- 代码索引的最小单位
- 包含文件路径、行号、语言、内容等信息
- 支持向量化嵌入
**Edge（关系边）**
- 表示节点间的依赖关系
- 类型：Defines, Implements, Calls, References
- 置信度：Explicit, Heuristic, Semantic
**Node（节点）**
- Chunk 的图结构投影
- 类型：Doc, Api, Code
- 支持双向关系查询
## ⚙️ 配置说明
### 配置文件
项目根目录的 `.axiom/axiom.toml`：
```toml
[project]
name = "my-project"
root = "."
# ================================================================
# 索引器配置
# ================================================================
[indexer]
auto_embed = true
embed_docs = true
embed_apis = true
embed_code = true
# 排除的目录列表
exclude_dirs = [
"node_modules",
"target",
".git",
"dist",
"build",
"vendor",
".axiom",
"models",
]
# 包含的文件扩展名列表（空列表表示包含所有支持的文件类型）
include_extensions = []
# ================================================================
# Embedding 模型配置
# ================================================================
[embedding]
# 模型基础路径
base_path = "./models"
# 模型类型：
# - "bge-small-zh" 或 "bge-small-zh-v1.5" （默认，中文优化，512维）
# - "bge-large-zh" 或 "bge-large-zh-v1.5" （中文高质量，1024维）
# - "bge-m3" （多语言，长文档，1024维）
model_type = "bge-small-zh"
# 推理设备 (cpu, cuda, metal)
device = "cpu"
# 向量存储路径
vector_store_path = ".axiom/vectors"
# 向量索引类型 (Flat, IVFFlat, HNSW)
index_type = "Flat"
# 语义相似度阈值
semantic_threshold = 0.6
```
### 环境变量
```bash
# 日志级别
export RUST_LOG=info # 基本日志
export RUST_LOG=debug # 详细日志
# 数据库路径（可选，覆盖配置文件）
export AXIOM_DB_PATH=/custom/path/axiom.db
```
## 🔧 开发指南
### 构建项目
```bash
# 开发版本
cargo build
# 发布版本
cargo build --release
# 运行测试
cargo test
# 运行特定测试
cargo test impact
cargo test search
```
### 项目结构
```
axiom/
├── src/ # 源代码
│ ├── ai/ # AI 功能
│ │ └── embeddings/ # 向量嵌入
│ ├── cli/ # CLI 命令
│ ├── core/ # 核心逻辑
│ ├── models/ # 数据模型
│ ├── parsing/ # 解析器
│ │ └── code/ # 代码索引器
│ ├── storage/ # 存储层
│ └── main.rs # 入口
├── tests/ # 集成测试
├── examples/ # 示例
├── docs/ # 文档
├── models/ # ML 模型文件
└── scripts/ # 工具脚本
```
### 添加新的索引器
1. **创建解析器** (`parsing/your_lang.rs`)
2. **创建索引器** (`parsing/code/your_lang_indexer.rs`)
3. **注册索引器** (`core/indexer.rs`)
示例：
```rust
// parsing/code/python.rs
pub struct PythonFile {
pub items: Vec,
}
// parsing/code/python_indexer.rs
pub struct PythonIndexer;
impl Indexer for PythonIndexer {
fn supports(&self, path: &Path) -> bool {
path.extension().and_then(|e| e.to_str())
.map(|e| e == "py").unwrap_or(false)
}
fn index(&self, path: &Path, ...) -> Result {
// 实现索引逻辑
}
}
```
### 扩展验证规则
在 `core/validator.rs` 中添加自定义规则：
```rust
pub trait ValidationRule {
fn validate(&self, change: &Change) -> ValidationResult;
fn name(&self) -> &str;
}
// 示例规则
pub struct NoDirectDbInHandlerRule;
```
## ❓ 常见问题
### Q: 为什么搜索没有结果？
**A**: 检查以下几点：
1. 是否已运行 `ax index --embed`
2. 查询是否过于具体（尝试更通用的关键词）
3. 搜索阈值是否过高（降低 `--threshold`）
4. 模型文件是否正确配置
### Q: embeddings 占用多少空间？
**A**: 对于 1000 个代码块：
- 向量数据：约 2MB (512维 × 4字节 × 1000)
- 元数据：约 500KB
- 总计：约 2.5MB
### Q: 支持哪些编程语言？
**A**: 当前支持：
- ✅ Rust (完整支持)
- 🚧 Markdown (文档支持)
- 🚧 OpenAPI/Swagger (API 规范)
- 📋 Python, JavaScript, Go (规划中)
### Q: 支持哪些模型？
**A**: 当前支持：
- ✅ bge-small-zh-v1.5 (默认，512维，中文优化)
- ✅ bge-large-zh-v1.5 (1024维，中文高质量)
- ✅ bge-m3 (1024维，多语言支持)
### Q: 如何切换模型？
**A**: 修改 `.axiom/axiom.toml`：
```toml
[embedding]
model_type = "bge-large-zh" # 或 bge-m3
base_path = "./models"
```
然后重新索引：
```bash
ax clean --force
ax index --embed
```
### Q: 影响分析的深度如何选择？
**A**:
- `--depth 1-3`: 快速查看直接依赖
- `--depth 4-10`: 常规影响范围（默认）
- `--depth 10+`: 深度分析，可能较慢
### Q: 如何集成到 CI/CD？
**A**: 示例 GitLab CI 配置：
```yaml
stages:
- validate
axiom-check:
stage: validate
script:
- cargo install --path /path/to/axiom
- ax patch --base origin/main --mode strict
only:
- merge_requests
```
### Q: 如何清理所有数据？
**A**:
```bash
# 清理所有数据（需确认）
ax clean
# 或强制清理
ax clean --force
```
## 📄 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
### 开发路线图
- [ ] 支持更多编程语言（Python, JavaScript, Go）
- [ ] Web UI 可视化
- [ ] 性能优化（大项目索引）
- [ ] VSCode 插件
- [ ] 更多验证规则
- [ ] 分布式索引支持
## 📮 联系方式
- Issues: [GitHub Issues](https://github.com/your-org/axiom/issues)
- Discussions: [GitHub Discussions](https://github.com/your-org/axiom/discussions)
---
]
**Built with ❤️ by the Axiom team**