betovildoza/Architect_compass
GitHub: betovildoza/Architect_compass
这是一个无需安装的Python脚本，能通过正则表达式映射多技术栈项目的依赖关系，检测死文件并生成结构健康评分，从而辅助技术审计。
Stars: 0 | Forks: 0
# 🧭 Architect's Compass
[](https://python.org)
[](https://github.com/betovildoza/Architect_Compass)
[](LICENSE)
[](https://github.com/betovildoza/Architect_Compass)
[](https://github.com/betovildoza/Architect_Compass)
**面向长期项目和多技术架构的技术审计。** 检测死文件，通过文件身份映射依赖关系，并生成结构健康评分 — 无需触碰你的代码。
## 为什么选择 Architect's Compass？
当你同时管理多个项目 — WordPress、Next.js、AI Agent、APIs — 时，文件树难免会充斥旧版本、备份和离线组件，没人知道它们是否仍然重要。
通常的应对方案是手动遍历项目或依赖记忆。这两种方式都难以扩展。
Architect's Compass 提供了一种不同的方式：**运行一个脚本，几秒钟内即可获得存活、孤立以及应当删除内容的完整地图。**
它完全在本地运行。无需安装或外部依赖。不会修改项目的任何文件 — 所有智能数据都保存在一个隐藏文件夹 `.map/` 中，你可以选择忽略或将其提交。
有时候，最有用的东西也往往是最不显眼的。
## ✨ 特性
| Feature | 描述 |
|---|---|
| 🗺️ Atlas JSON | 位于 `.map/atlas.json` 的完整技术报告 |
| 💀 孤儿检测 | 识别未检测到逻辑连接的文件 |
| 🔁 反重复 | 检测同一组件的多个版本（`v1`、`_old`、`_backup`） |
| 📡 连接图 | 包含组件间 inbound/outbound 流向的 `.dot` 图 |
| 📈 健康评分 | 基于项目结构清理度的 0–100% 指标 |
| 📓 历史日志 | 记录每次执行时的评分演变 |
| 🧩 技术栈无关 | 基于 Regex 的引擎 — 适用于任何语言或框架 |
| 🪟 隐身模式 | 不在工作树中生成文件；所有内容存入 `.map/` |
## 🔬 核心能力
**🔍 身份统一**
引擎在分析 imports 之前会先索引项目中的所有文件。如果发现 `from services.monitor import X`，它知道这是指物理文件 `services/monitor.py` — 并将该路径作为图中的节点。无重复，无幽灵节点。
**🛡️ 动态健康审计**
评分（0–100%）根据文件总数与至少有一个检测到连接的文件之间的关系计算。孤立文件会降低评分。重复文件也会。
**📂 分层配置**
Compass 接受全局 `mapper_config.json`（位于工具文件夹）或每个项目中 `.map/mapper_config.json` 的本地配置。本地配置优先，允许在不触及基础配置的情况下按项目定义技术栈。
**🕸️ 干净的可视化导出**
`.dot` 图仅包含业务逻辑。环境文件夹（`.venv`、`node_modules`、`__pycache__`）默认被排除，将原本的外部库“蜘蛛网”转变为真实架构的可读地图。
## 📊 生成的输出
在项目根目录下运行 Compass 时，会创建包含三个文件的 `.map/` 文件夹：
**`atlas.json`** — 完整报告。包括：
```
{
"generated_at": "2025-06-15 14:32:10",
"project_name": "mi-proyecto",
"identities": [{ "tech": "WordPress-Development", "confidence": 90 }],
"summary": { "total_files": 84, "relevant_files": 31 },
"connectivity": { "inbound": [...], "outbound": [...] },
"audit": {
"structural_health": 87.5,
"warnings": [
{ "type": "ORPHAN", "file": "utils/old_helper.js", "description": "..." },
{ "type": "AMBIGUITY", "files": ["api.php", "api_v2.php"], "description": "..." }
]
}
}
```
**`connectivity.dot`** — Graphviz 格式的依赖图。将其粘贴到 [GraphvizOnline](https://dreampuf.github.io/GraphvizOnline) 即可可视化。
**`feedback.log`** — 执行历史记录，包含按日期统计的评分和统计信息。
## 
## 🚀 安装
无需安装。只需在系统中安装 Python 3.8+。
```
# 克隆或将 repo 下载到工具文件夹
git clone https://github.com/betovildoza/Architect_compass C:\DevTools\ArchitectCompass
# 复制示例 config
cp mapper_config.example.json mapper_config.json
```
编辑 `mapper_config.json` 以调整定义以适应你的技术栈（见配置章节）。
### 快速使用
```
# 导航到要审计的项目根目录
cd C:\Projects\mi-proyecto
# 运行 script
python C:\DevTools\ArchitectCompass\architect_compass.py
```
### 使用环境变量自动化（Windows）
将以下文件保存为与脚本同文件夹下的 `compass.bat`：
```
@echo off
set SCRIPT_PATH="C:\DevTools\ArchitectCompass\architect_compass.py"
if exist %SCRIPT_PATH% (
python %SCRIPT_PATH%
) else (
echo [ERROR] No se encontro el motor en %SCRIPT_PATH%
echo Revisa la ruta en compass.bat
)
pause
```
然后将该文件夹添加到系统 **PATH** 中：
`环境变量 → Path → 编辑 → 新建 → 粘贴路径`
之后，在任何终端的项目根目录下：
```
compass
```
## ⚙️ 配置
工具的强大之处在于 `mapper_config.json`。它包含两个主要部分：
**`basal_rules`** — 适用于所有项目的全局规则：
- `ignore_folders`：扫描器完全忽略的文件夹
- `text_extensions`：进行深度分析的文件扩展名
- `network_triggers`：指示网络调用的模式
- `persistence_triggers`：指示访问持久化数据的模式
**`definitions`** — 按技术的技术栈定义。每个条目允许 Compass 识别该技术并映射其连接性：
```
{
"name": "Mi-Stack-Custom",
"priority": 10,
"indicators": {
"files": ["config.custom"],
"folders": ["src/logic"],
"patterns_in_files": ["mi_init_function\\("]
},
"patterns": {
"inbound": ["on_request\\(", "register_handler\\("],
"outbound": ["call_external_api\\(", "write_to_db\\("]
}
}
```
`mapper_config.example.json` 文件包含可直接使用的定义：**PHP Backend**、**Vanilla Frontend** 和 **WordPress**。
## 🛠️ 技术栈
**Runtime**
- Python 3.8+
**Dependencies**
- 仅标准库（`os`、`json`、`re`、`pathlib`、`datetime`）
**Outputs**
- JSON (atlas)
- Graphviz DOT (connectivity graph)
- Plain text (historical log)
## 🗂️ 仓库结构
```
ArchitectCompass/
├── architect_compass.py # Motor principal
├── mapper_config.example.json # Configuración de referencia
├── compass.bat # Launcher para Windows con PATH
└── README.md
```
## ⚠️ 需要注意的行为
### 文件名中的特殊字符
身份解析引擎会在文件注册中查找之前清理捕获的路径。允许的字符集为：字母、数字、`. / _ -`。
如果被审计的项目包含超出该字符集的文件（例如：`@`、`$`、`~`、空格），这些字符将被静默删除，文件可能无法正确解析 — 在图中显示为无连接节点。
**症状：** 指向与真实文件不匹配名称的箭头（“幽灵节点”）。
**解决方案：** 检查 `architect_compass.py` 中 `_resolve_identity` 内的 regex，并将必要的字符添加到允许集中。
### 本地配置行为（`.map/mapper_config.json`）
本地配置**不会替换**全局配置 — 而是**扩展**它们：
- `basal_rules`：本地的键会覆盖全局中同名的键。
- `definitions`：如果本地定义的 **`name`** 与全局定义的相同，则完全替换它。如果是新名称，则添加到列表中。
这意味着要向已在全局中定义的技术（例如：WordPress）添加模式，必须将完整定义复制到本地并进行修改 — 仅放置新模式是不够的。
## 📜 许可证
本软件在 MIT 许可证下分发。
详情请参阅 `LICENSE` 文件。
*由 [Alberto Vildoza](https://github.com/betovildoza) 维护。*
标签：Homebrew安装, Python, WebSocket, 云安全监控, 代码健康, 代码维护, 依赖分析, 多技术栈, 孤立文件检测, 技术债务, 数字取证, 文件清理, 文件管理, 无依赖, 无侵入式, 无后门, 本地工具, 架构分析, 死代码检测, 自动化脚本, 逆向工具, 静态分析, 项目重构