bogdanv98/blossa

# Blossa **Blossa** 连接到（通常是遗留的本地部署）**Oracle** 数据库，以**只读**方式读取它，并 重构其 schema 的**业务含义**：每张表和每一列实际代表的内容、它们之间可能的关系， 以及一份人类可读的**整个数据库映射图** —— 这样一名新 工程师就能理解一个没有任何文档的数据库，而不需要找到当初构建它的人。 该引擎是**领域无关的**。首个切入点是**遗留的本地部署 Oracle**。 ## 为什么 当理解某个数据库的人员离开时，关于数据在业务层面*意味着*什么的知识也随之被带走。Blossa 加速了理解过程（让一个新人在一天内而不是几周内达到约 70% 的理解度）。它对自己的局限性很坦诚：它只重构可以从 schema + 数据 + 现有文档中*推断*出的内容 —— 它无法恢复那些从未被记录下来的纯粹隐性知识。 ## 工作原理 ``` Oracle (read-only) │ introspect data dictionary (ALL_TABLES, ALL_TAB_COLUMNS, ALL_CONSTRAINTS, …) ▼ [ deterministic core ] ── PKs/FKs, candidate FKs, orphans, type/naming issues, missing comments │ build compact, PII-SAFE per-table summaries (aggregates + masked samples, never raw rows) ▼ [ LLM semantic pass ] ── runs ONLY over the structured summaries (local model by default) │ → table purpose + column meaning, each with confidence + evidence ▼ [ renderer ] ── database_map.md + database_map.json ``` 确定性核心完成了绝大部分繁重的工作。LLM 仅被谨慎使用，且只用于紧凑的 结构化摘要 —— **绝不**用于原始 schema 转储或原始数据。 ## 隐私 / 安全（硬性约束） - 数据库连接是**只读**的。 - **绝不**将原始行值发送给任何 LLM —— 仅发送聚合数据、值模式和脱敏后的样本。 - 默认**在本地运行**（Ollama / vLLM）。使用本地模型时，Blossa **不会发起任何外部网络调用**。 - **不要**针对生产环境或雇主数据进行开发或测试 —— 请使用内置的合成 schema。 ## 安装 一旦发布到 PyPI： ``` python -m pip install blossa ``` 从源码安装（用于开发）： ``` python -m pip install -e ".[dev]" ``` 需要 Python 3.12+。在**瘦模式**下使用 `oracledb` 驱动 —— 无需 Oracle Instant Client。 ## 首次运行（快速通道） ``` blossa init # interactive: writes blossa.local.yml (DSN, user, schema, LLM choice) blossa doctor # checks Python, driver, config, Oracle, the LLM, and output dir — tells you what's missing blossa scan # run it ``` `blossa doctor` 就像一位朋友，会在扫描前直接告诉新用户需要修复什么 （例如“Ollama 无法访问 —— 请运行 `ollama pull qwen2.5:14b`”，或者“启动演示数据库”）。 ## 快速开始 ### 1. 启动合成 Oracle（用于开发） ``` cd docker docker compose up -d # Oracle XE + the synthetic BLOSSA_DEMO schema ``` 种子脚本会创建几个相关的表，并故意缺失部分注释以及一个 **未声明的**外键，这样无需真实数据即可测试整个 pipeline。 ### 2. 配置 复制 `blossa.yml` → `blossa.local.yml` 并设置你的 DSN / 凭据（或使用 `BLOSSA_*` 环境变量）。 对于密码，建议使用环境变量： ``` export BLOSSA_ORACLE__PASSWORD=blossa_demo ``` ### 3. 扫描 ``` blossa scan --config blossa.local.yml ``` 输出 `out/database_map.md` 和 `out/database_map.json`。 ### 在没有 Oracle 或 GPU 的情况下尝试 ``` # 在打包的离线 fixture 上运行完整 pipeline，使用 heuristic (no-LLM) provider。 blossa scan --demo --llm-provider heuristic ``` ## 命令 | 命令 | 功能描述 | | --- | --- | | `blossa init` | 交互式首次运行设置；生成 `blossa.local.yml`。 | | `blossa doctor` | 检查所有前置条件（Python、驱动、配置、Oracle、LLM、输出）并报告修复建议。 | | `blossa scan` | 针对已配置的 Oracle schema 运行完整 pipeline → Markdown + JSON。 | | `blossa scan --demo` | 针对内置的离线 fixture 运行（无需 Oracle）。 | | `blossa introspect` | 仅将内省到的原始 schema 转储为 JSON（无检查，无 LLM）。 | | `blossa check-llm` | 验证已配置的 LLM provider 是否可访问。 | 运行 `blossa --help` 查看所有标志。 ## 范围 (MVP) 包含：只读 Oracle 内省、确定性 schema 分析、PII 安全摘要、本地 LLM 语义处理、Markdown + JSON 输出。 暂不包含：Web UI、聊天界面、任何写入访问、非 Oracle 引擎、查询日志/血缘 摄入、托管云服务、模型微调。 ## 开发与发布 ``` python -m pip install -e ".[dev]" ruff check src tests # lint pytest # tests python -m build # build sdist + wheel into dist/ ``` CI（在 Python 3.12/3.13、Linux + Windows 上进行 lint + 测试）通过 `.github/workflows/ci.yml` 运行。 要发布到 PyPI：请在 PyPI 上为项目配置 [Trusted Publisher](https://docs.pypi.org/trusted-publishers/)， 然后推送一个版本标签： ``` git tag v0.1.0 && git push --tags ``` `.github/workflows/release.yml` 会自动构建并发布（无需 API token）。 注意：在首次发布前，请确认 PyPI 上的 `blossa` 名称可用。 ## 许可证 Blossa 采用 **[GNU Affero General Public License v3.0](LICENSE)** (AGPL-3.0-only) 授权。 简而言之：你可以自由地使用、运行、研究和修改 Blossa —— 但如果你将其分发，或作为网络服务运行修改后的版本，你必须在相同的 许可证下公开你的源码更改。版权详情请参见 [NOTICE](NOTICE)。 Copyright (c) 2026 Bogdan Voinea。“Blossa” 是项目名称；该许可证涵盖代码，但不包含名称。未来可能提供单独的商业许可证 —— 贡献将在 [CLA](CLA.md) 下接受（参见 [CONTRIBUTING.md](CONTRIBUTING.md)）以保留此项选择。

标签：AI风险缓解, DLL 劫持, Oracle, 云资产清单, 大语言模型, 安全规则引擎, 数据库文档, 请求拦截, 逆向工具, 逆向工程, 遗留系统