CXLD10/spec-atlas-ki-platform

# Spec-Atlas：面向工程化的知识智能    ## 什么是 Spec-Atlas？ Spec-Atlas 是一个**零成本、本地优先的知识智能平台**，它通过索引代码库和文档来创建可查询的智能知识库。它结合了： - **代码理解**：解析源代码以提取符号、依赖项和关系 - **文档智能**：支持对 PDF、Markdown 和电子表格进行结构化感知的导入 - **语义搜索**：使用 embeddings 查找相关的代码和文档 - **自动化规范**：使用 LLM 按需生成知识卡片（L3 specs） - **知识图谱**：以 3D 可视化方式展示代码库的结构与关系 - **引用系统**：每个答案都会链接回其来源（代码对应 file:line，文档对应 page/cell） ### 为什么选择 Spec-Atlas？ - **新人上手**：新团队成员可以直接查询代码库，而无需反复提问 - **文档编写**：从代码自动生成规范；让文档与实际情况保持同步 - **搜索查找**：在 10 万行以上的代码中瞬间找到代码、概念和决策 - **架构梳理**：在交互式 3D 图谱中直观展现组件间的关联方式 - **零成本**：本地优先，支持离线，默认使用免费/开源的 LLM 提供商 - **隐私安全**：一切均在本地运行；无云端依赖，无数据泄露 ## 核心功能 ### 多来源数据导入 - **代码**：克隆任何 Git 仓库（Python、JavaScript/TypeScript、Go 等） - **文档**：支持 PDF、Markdown、Excel 电子表格，具备页码/单元格感知能力 - **Git 历史**：追踪代码变更与提交上下文 - **Jira**：导入问题（Issue）和需求 ### 智能检索 (RAG) - 用于语义搜索的 vector embeddings - 双重定位引用（代码：`file:line`，文档：`page:bbox`） - 跨会话的对话记忆 - 上下文感知的排序与检索 ### 知识图谱 - 3 层可视化（L1 来源、L3 规范、L4 领域） - 使用 Three.js 进行交互式 3D 渲染 - 点击式工作流：图谱 → 提问 → 规范化 - 实时来源追踪 ### 自动化规范生成 - 一键为任何代码实体生成知识卡片 - 基于 LLM 的结构化输出生成（用途、输入、输出、不变量等） - 规范版本控制与验证工作流 - 代码变更时的漂移检测标记 ### Ask Atlas (聊天) - 使用自然语言查询您的整个知识库 - 获取基于代码并附带引用的回答 - 缺少代码上下文时回退至通用知识库 - 实时流式响应 ## 架构概述 ### 系统架构图 ``` Frontend (React 18, Vite) ↓ HTTP/REST Backend (FastAPI, SQLAlchemy) Ingest Pipeline (6 phases) Retrieval Engine (RAG) Answer Generation (LLM) Knowledge Graph ↓ SQLAlchemy ORM Databases (PostgreSQL + pgvector) Analysis DB (source units, entities, graph) Spec DB (specs, embeddings, verification) ``` ### 数据导入流水线 (6 个阶段) ``` Phase 1: Inventory → Clone repo, detect language, hash files Phase 2: Parse → Extract symbols, build AST, create entities Phase 3: Graph → Find dependencies, build call graph Phase 4: Clustering → Group symbols into domains (L4) Phase 5: Detection → Drift detection, stale spec flags Phase 6: Specs → Generate L3 knowledge cards via LLM (ETA tracking, parallel processing) ``` ### 数据模型 **稳定主键**（支持幂等重复导入）： - `SourceUnit`: `(source_type, source_id, locator)` - `Entity`: `(source_id, qualified_name)` — 在代码变更时保持稳定 - `Spec`: `(component_ref, version)` — 具有版本控制的不可变规范 ## 快速入门 ## 快速开始设置 ### 步骤 1：安装前置条件 请确保您已安装以下内容： - Python 3.12 或更高版本 - Node.js 18 或更高版本 - Docker 和 Docker Compose ### 步骤 2：克隆仓库 ``` git clone https://github.com/CXLD10/spec-atlas-ki-platform.git cd spec-atlas-ki-platform ``` ### 步骤 3：启动数据库 ``` docker-compose up -d postgres ``` 等待 5 秒钟让数据库准备就绪。 ### 步骤 4：安装后端依赖 ``` python3.12 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` ### 步骤 5：创建环境配置 在项目根目录下创建一个 `.env` 文件： ``` cat > .env << 'EOF' ANALYSIS_DB_URL=postgresql+psycopg://spec_atlas:spec_atlas_dev@localhost:5432/spec_atlas_analysis SPEC_DB_URL=postgresql+psycopg://spec_atlas:spec_atlas_dev@localhost:5432/spec_atlas_spec LLM_PROVIDER=groq GROQ_API_KEY=your_key_here_KEY_HERE EMBED_PROVIDER=fake EOF ``` 将 `gsk_YOUR_KEY_HERE` 替换为您从 https://console.groq.com 获取的 Groq API 密钥。 ### 步骤 6：应用数据库迁移 ``` alembic upgrade head ``` ### 步骤 7：启动后端 打开一个终端并运行： ``` source .venv/bin/activate cd /home/cxld/projects/spec-atlas-ki-platform export PYTHONPATH=$PWD/src uvicorn spec_atlas.api.app:app --reload --host 0.0.0.0 --port 8000 ``` 等待出现提示信息：`Uvicorn running on http://0.0.0.0:8000` ### 步骤 8：安装前端依赖 打开另一个终端并运行： ``` cd /home/cxld/projects/spec-atlas-ki-platform/frontend npm install ``` ### 步骤 9：启动前端 ``` npm run dev ``` 等待出现提示信息：`Local: http://localhost:5173` ### 步骤 10：访问应用 打开浏览器并访问：**http://localhost:5173** 现在您可以开始索引代码库了。 ## 使用指南 ### 1. 索引代码库 1. 进入 **Sources** 页面 2. 粘贴一个公开的 GitHub URL 3. 点击 **Index** 4. 等待操作完成（会显示预计剩余时间 ETA） 5. 查看生成的知识卡片 ### 2. 提问 1. 打开 **Ask Atlas** 2. 输入：*"身份验证是如何工作的？"* 3. 获取带有引用的、有依据的回答 4. 点击引用以跳转到源码 ### 3. 探索知识图谱 1. 打开 **Knowledge Graph** 2. 选择代码库 3. 交互操作：拖拽旋转、滚动缩放、点击查看详情 4. 点击节点 → 查看规范和关系 ### 4. 生成规范 1. 打开 **Specify** 工具 2. 输入仓库名称和实体 3. 点击 **Generate** 4. 审阅并保存 ## 技术栈 ### 后端 - **框架**：FastAPI（REST API、SSE 流式传输） - **数据库**：PostgreSQL + pgvector - **ORM**：SQLAlchemy - **解析**：tree-sitter - **Embeddings**：Ollama（默认）或 Groq - **LLM**：Groq（免费）或 Ollama ### 前端 - **框架**：React 18 - **构建**：Vite - **路由**：React Router v6 - **状态**：TanStack Query - **3D**：Three.js - **样式**：CSS + Design Tokens（苹果风格设计） ## 项目结构 ``` spec-atlas-ki-platform/ src/spec_atlas/ api/ # REST endpoints ingest/ # Ingest pipeline parse/ # Language parsing graph/ # Dependencies embed/ # Embeddings db/ # SQLAlchemy models llm/ # LLM provider abstraction answer/ # RAG + answer generation frontend/src/ pages/ # Ask, Sources, Graph, KB, Specify components/ # UI components lib/ # Hooks, utilities, types api/ # API client app/ # Theme, shell docs/ DECISIONS.md # Architecture decisions PLAYBOOK.md # Development process decisions/ # ADRs specs/ # Product specs ``` ## 开发命令 ``` # Backend make dev-backend # Run with auto-reload make test # Run tests (offline, fake providers) make lint && make format # Frontend make dev-frontend # Dev server npm run type-check # Type checking npm run build # Production build # Database make migrate # Apply migrations make db-drop # Reset (careful!) ``` ## 设计系统 **受苹果启发的暗黑模式**，采用专业配色： - **背景**：深空黑（`#1a1a1a`） - **表面**：暖炭灰（`#242424`、`#2a2a2a`） - **文字**：浅灰色（`#f5f5f5`） - **强调色**：柔和的靛蓝色（`#6ba3d4`） - **效果**：Glassmorphism（毛玻璃效果） ## 测试 ``` # Backend: 离线并使用 fake providers make test # 运行特定测试 pytest tests/api/test_answer.py -v # 针对 real providers 运行 (本地) make test-real # Frontend: Type checking npm run type-check ``` ## 性能表现 ### 导入速度 - 小型仓库（<5 万行代码）：30–60 秒 - 中型仓库（5 万 - 50 万行代码）：1–3 分钟 - 大型仓库（>50 万行代码）：5–15 分钟 ### 查询性能 - 向量搜索：<100ms - RAG 检索：200–500ms - 图谱渲染：16ms/帧 ## 安全与隐私 - 本地优先（一切均在您的机器上运行） - 无外部调用（代码绝不外传） - 支持离线运行（LLM 调用除外） - 无遥测数据收集 - 凭据存放在被 git 忽略的 `.env` 文件中 ## 贡献指南 请参阅 `docs/PLAYBOOK.md`： 1. 查看 `specs/product/SCOPE.md`（保持在范围内） 2. 从 `tasks/BOARD.md` 中挑选状态为 `ready` 的任务 3. 认领任务（附上您的姓名 + 日期） 4. 仅在标记为 "Owns" 的文件中进行开发 5. 根据 `docs/TESTING.md` 添加测试 6. 为架构决策创建 ADR 7. 标记为 `done` 并附带 HANDOFF 备注 ## 相关资源 - **API 契约**：`API_CONTRACT.md` - **架构**：`ARCHITECTURE-E2E.md` - **数据模型**：`specs/architecture/DATA-MODEL.md` - **路线图**：`specs/FEATURES.md` - **决策**：`docs/decisions/` ## 许可证 MIT — 详见 LICENSE 文件。 ## 作者 **Joshua Jom** (CXLD10) ## 支持 - **问题反馈**：GitHub Issues - **邮箱**：joshuajomjose@gmail.com **版本：** 0.6.0 | **状态：** 生产就绪 (Production Ready) | **最后更新：** 2026 年 6 月 24 日

标签：AI风险缓解, RAG, Ruby, SOC Prime, 代码理解, 开发工具, 文档解析, 测试用例, 知识库, 语义搜索, 请求拦截, 逆向工具