Ashish6298/HealCode
GitHub: Ashish6298/HealCode
AI 驱动的开发者诊断 CLI 工具，通过单条命令扫描环境、容器、云配置和代码并输出加权健康评分。
Stars: 0 | Forks: 0
# HealCode • 能够发现 `git status` 遗漏问题的诊断引擎。
## 📚 目录
## 概述 **HealCode** 是一个由 AI 驱动的开发者诊断 CLI 平台，旨在扫描本地开发环境、容器、云环境上下文、项目配置和源代码文件，以识别配置漂移、性能反模式和安全异味。 你无需再为了 Docker linting、Kubernetes 上下文检查、依赖审计和静态分析而费力协调各种独立工具，HealCode 只需对所有内容执行一次 `scan`，并将结果汇总为一个加权健康评分 —— 让你随时准确了解项目的健康状况。
## ⚠️ 问题所在 大多数项目的崩溃并非源于一个巨大且明显的 bug。它们往往是因为一些没人及时注意到的小问题。 密码或密钥意外保存到了不该包含它的文件中；云配置悄悄指向了错误的位置；容器缺少在崩溃时能自动重启的设置；一段代码随着时间推移变得越来越复杂，直到最后没人敢去碰它。这些都不会在你执行 `git status` 时显示出来 —— 它们往往在后续才会暴露，表现为一个 bug、一次安全恐慌，或者一次深夜的紧急修复。 | ❌ 没有 HealCode 时 | |---| | 🔑 密钥或密码意外被保存到了代码中 | | 🐳 容器配置有误，但在崩溃前没人察觉 | | ☸️ 云端/Kubernetes 设置悄悄指向了错误的环境 | | 🧮 代码在不知不觉中慢慢变得混乱且难以理解 | | 🧰 你的工具版本（Python、Node.js 等）与项目实际需要的不同步 | | 📉 缺乏记录显示你的环境配置随着时间推移发生了什么变化及时间点 |
## 💡 解决方案 HealCode 可以为你检查所有这一切 —— 你的电脑、容器、云配置、代码 —— 只需一条简单的命令：`healcode scan`。无需再通过五种不同的工具拼凑出五份不同的报告，你可以为整个项目获得一个清晰的健康评分。 | ✅ HealCode 的不同之处 | |---| | 🔍 **一条命令检查所有内容** —— 系统、容器、云配置、工具和代码，一次性全部搞定 | | 📈 **一个简单的评分** —— 无需再拼凑五种不同工具的结果 | | 🗃️ **记录变化内容** —— 将今天的检查与上周的进行对比，准确看出差异 | | 🧠 **无需联网的智能助手** —— 一个可选的 AI 功能，能将问题归类，并告诉你优先修复什么，完全在离线状态下运行 | | ⏱️ **在你工作时持续检查** —— 开启 watch 模式，它会在你写代码时自动进行重新检查 |
## 🎯 HealCode 适合谁？ | 适用人群 | 为什么对他们有帮助 | |---|---| | 👨💻 **独立开发者** | 在你分享代码之前发现错误和暴露的密码 —— 而无需自己设置五个独立的工具。 | | 🧑🤝🧑 **小型团队** | 每个人都使用相同的配置文件，因此整个团队的项目都能以相同的方式进行检查。 | | 🏢 **DevOps / 基础设施人员** | 使用 `DevOps` 配置文件，专门关注容器、云设置和配置漂移。 | | 🔐 **注重安全的团队** | 使用 `Security` 配置文件，优先处理暴露的密钥和有风险的设置。 | | 🎓 **学生和初学者** | 在一份简单的报告中，了解“健康”的项目设置到底是什么样的 —— 这是尽早养成良好习惯的绝佳方式。 |
## ⚖️ HealCode 与手动操作的对比 你*确实可以*使用几个独立的工具来拼凑出相同的覆盖范围 —— 但以下是它们并排比较时的真实情况。 | 你需要检查的内容 | 手动操作 | 使用 HealCode | |---|---|---| | 🔑 代码中暴露的密钥 | 设置一个独立的密钥扫描工具 | 包含在 `healcode scan` 中 | | 🐳 Docker/Compose 配置错误 | 手动阅读 Dockerfile 和 compose 文件 | 包含在 `healcode scan` 中 | | ☸️ Kubernetes 上下文漂移 | 每次部署前手动检查 `kubectl config` | 包含在 `healcode scan` 中 | | 🧰 工具链版本不匹配 | 自己将 manifest 与已安装的版本进行交叉检查 | 包含在 `healcode scan` 中 | | 🧮 代码复杂度问题 | 每种语言运行一个独立的静态分析工具 | 包含在 `healcode scan` 中 | | 📊 整体的健康状况视图 | 手动汇总上述所有工具的结果 | 自动生成的一个加权评分 | | 🗃️ 跟踪随时间发生的变化 | 没有内置方法 —— 你必须自己记住或记录下来 | `healcode baseline` 会为你跟踪 | | ⏱️ 编码时的持续检查 | 每次都要手动重新运行每个工具 | `healcode watch` 会自动完成 |
## 🏗️ 扫描是如何工作的 当你运行 `healcode scan` 时，后台会发生以下事情 —— 并且是一步到位： ``` healcode scan │ ▼ ┌─────────────────────────┐ │ Runs all the checks │ └─────────────────────────┘ │ ┌───────────┬──────┼───────┬────────────┐ ▼ ▼ ▼ ▼ Your Containers Cloud & Your Tools Computer (Docker) Cloud Setup (Python, Node.js, etc.) │ ▼ Your Code (looks for messy or risky code) │ │ │ │ └────────────┴──────┬──────┴─────────────┘ ▼ ┌───────────────────┐ │ Adds it all up │ │ into one score │ └───────────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ Health Report Saves a record (what passed, (so you can compare what needs it to next time) attention) │ ▼ Optional: AI groups the problems and tells you what to fix first ```
## ⚡ 实际运行效果 运行 `healcode scan`，几秒钟内即可获得完整的环境健康报告 —— 无需任何配置。 ``` [1;36mHEALCODE DIAGNOSTICS ENGINE v1.0.0[0m [1;35m════════════════════════════════════════════════════[0m [1;34m▸ SYSTEM[0m [1;32m [✓] OS & shell environment healthy[0m [1;32m [✓] Disk space sufficient (62% free)[0m [1;34m▸ CONTAINERS[0m [1;32m [✓] Docker daemon running (v24.0.7)[0m [1;33m [!] docker-compose.yml missing restart policy on 'api' service[0m [1;34m▸ CLOUD & KUBERNETES[0m [1;33m [!] Kubernetes context using default namespace instead of dev-active[0m [1;32m [✓] AWS CLI credentials valid[0m [1;34m▸ RUNTIME & TOOLCHAINS[0m [1;32m [✓] Node.js v20.11.0 matches package.json engine constraint[0m [1;31m [✗] Python 3.9 installed — pyproject.toml requires >=3.11[0m [1;34m▸ STATIC CODE ANALYSIS[0m [1;33m [!] High cyclomatic complexity in utils/parser.py (score: 24)[0m [1;31m [✗] Found 1 exposed API key in config/settings.py:L14[0m [1;35m════════════════════════════════════════════════════[0m [1;36mOVERALL ENVIRONMENT HEALTH:[0m [[1;32m######################----[0m] [1;32m88.5%[0m [1;32m3 passed[0m · [1;33m2 warnings[0m · [1;31m2 critical[0m ``` | 符号 | 含义 | |:---:|---| | ✅ | 通过 —— 无需操作 | | ⚠️ | 警告 —— 值得复查 | | ❌ | 严重 —— 应在发布前修复 |
## 🚀 核心功能 - 🧠 **AI 驱动的诊断**：可选的 AI 编排层，提供根因分组、优先级评分和修复建议，且没有任何云端依赖。 - 📦 **Docker 和 Compose 审计**：检查引擎版本信息、Context 配置、Dockerfile 安全实践以及 docker-compose 重启结构。 - ☁️ **云端与 Kubernetes 上下文**：扫描本地 AWS、GCP 和 Azure CLI 设置，评估 kubeconfig 上下文有效性，并识别本地 Terraform 变量。 - ⚙️ **运行时和编译器智能分析**：检测 Node.js、Python、Java、Go、Rust 和 Flutter 工具链，并根据 manifest 约束匹配编译器版本。 - 🔍 **通用静态代码分析**：计算各种语言的圈复杂度、嵌套深度和嵌套循环性能瓶颈。 - 📈 **加权健康评分**：跨越 40 多个细粒度类别对代码库健康度进行评级。 - 🗃️ **基线与漂移检测**：捕获环境快照，以跟踪回归、改进和随着时间推移发生的环境变化。 - ⏱️ **Watch 模式**：实时轮询目录，实现快速增量重新扫描。
## 📦 安装说明 ``` pip install healcode ``` ### 环境要求 | 依赖项 | 版本 | 用途 | |---|---|---| | **Python** | ≥ 3.11 | Runtime | ### 验证安装 ``` healcode --version ```
## ⚡ 快速开始 只需四个命令，你就能从全新安装转变为获得一份带有已跟踪基线的完整环境健康报告。 ### 1️⃣ 初始化配置 在你的项目根目录创建一个 `healcode.json` 配置文件，让扫描从一开始就适应你的设置。 ``` healcode config init ``` ### 2️⃣ 运行诊断扫描 扫描你的本地环境、容器、云/K8s 上下文、工具链和源代码 —— 然后打印出一个加权健康评分。 ``` healcode scan ``` ### 3️⃣ 生成基线报告 为当前项目状态拍摄快照，以便将未来的扫描结果与它进行对比，从而发现配置漂移。 ``` healcode baseline create initial_state ``` ### 4️⃣ 运行 AI 智能摘要（离线优先） 按根因对发现的问题进行分组，并优先处理需要首先修复的内容 —— 不需要任何云端依赖。 ``` healcode ai --offline ```
## 📝 配置示例 运行 `healcode config init` 会在你的项目中创建一个 `healcode.json` 文件。以下是一个典型的配置示例： ``` { "profile": "DevOps", "targets": ["."], "checks": { "system": true, "docker": true, "kubernetes": true, "cloud": true, "toolchains": true, "static_analysis": true }, "exclude": [ "node_modules", "dist", ".venv" ], "ai": { "enabled": true, "offline": true } } ``` | 字段 | 控制内容 | |---|---| | `profile` | 当前激活的扫描配置（`DevOps`、`Security` 或 `Minimal`） | | `targets` | 要扫描的目录 —— 默认为当前项目 | | `checks` | 开启或关闭个别检查类别 | | `exclude` | 扫描期间要跳过的文件夹 | | `ai.enabled` / `ai.offline` | AI 层是否运行，以及是否完全保持离线状态 |
## 🛠️ 命令参考 ### 核心诊断 | 命令 | 用法 | 描述 | |---|---|---| | `scan` | `healcode scan [target]` | 运行活动的诊断检查并显示系统健康状况。 | | `baseline` | `healcode baseline create [name]` / `healcode baseline compare [name]` | 捕获项目快照或针对快照分析当前状态。 | | `watch` | `healcode watch` | 启动目录文件监视器，进行实时的增量重新扫描。 | ### 配置 | 命令 | 用法 | 描述 | |---|---|---| | `config` | `healcode config init` | 初始化项目配置文件 `healcode.json`。 | | `profile` | `healcode profile set [name]` | 调整当前活动的扫描配置（`DevOps`、`Security`、`Minimal`）。 | ### 智能与扩展 | 命令 | 用法 | 描述 | |---|---|---| | `ai` | `healcode ai --offline` | 编排根因诊断和修复建议。 | | `marketplace` | `healcode marketplace search [q]` | 搜索社区插件市场 *(模拟界面 —— 尚未上线)*。 |
## 📊 了解你的健康评分 每次 `healcode scan` 的结尾都会给出一个数字 —— 你整体的环境健康百分比。以下是如何解读它。 ### 评分是如何构成的 HealCode 运行的每一项检查（系统、容器、云/K8s、工具链、代码）都会贡献到 40 多个中的某一个。各类别的权重并不相同 —— 一个严重的发现（如暴露的密钥）比一个轻微的警告（如缺少重启策略）更能拉低分数。 分数 = 100% − (每个警告和严重发现的加权惩罚) ### 解读结果 | 分数范围 | 含义 | |---|---| | 🟢 **90–100%** | 健康 —— 无需采取紧急行动 | | 🟡 **70–89%** | 有一些警告 —— 值得在下次发布前审查 | | 🟠 **50–69%** | 存在多个问题 —— 建议在发布前予以解决 | | 🔴 **低于 50%** | 存在严重问题 —— 必须在继续操作前修复 | ### 拉低你分数的因素 | 严重程度 | 示例 | 影响 | |---|---|---| | ✅ 通过 | Docker daemon 正确运行 | 无惩罚 | | ⚠️ 警告 | Kubernetes 上下文使用了默认的 namespace | 轻微惩罚 | | ❌ 严重 | 源代码中存在暴露的 API key | 严重惩罚 |
## 📁 文档中心 完整指南位于 [`docs/`](docs/) 文件夹中。以下是每个文档的涵盖内容及适用场景： ### 📖 [快速入门](docs/getting_started.md) 你使用 HealCode 的前十分钟 —— 安装、初始化配置、运行你的第一次 `scan` 以及解读健康评分输出。如果你从未用过 HealCode，请从这里开始。 ### 💾 [安装说明](docs/installation.md) 针对 Windows、Linux 和 macOS 的特定平台设置说明，包括 Python 版本要求和常见的安装问题（权限、PATH 冲突、virtualenv 设置）。 ### ⚙️ [配置参考](docs/configuration.md) `healcode.json` 中可用的所有选项 —— 扫描配置（`DevOps`、`Security`、`Minimal`）、包含/排除哪些检查，以及如何将扫描范围限定在特定目录或目标上。 ### 📐 [架构设计](docs/architecture.md) 扫描在底层的实际运行方式：检查 pipeline、发现的问题是如何被评分并加权汇总到整体百分比中的，以及可选的 AI 层是如何在离线状态下处理结果的。 ### ⌨️ [CLI 参考](docs/cli_reference.md) 包含每个 flag 和子命令的完整命令列表 —— 这是 `scan`、`config`、`profile`、`baseline`、`watch` 和 `ai` 的权威参考。 ### 🔌 [Plugin SDK](docs/plugin_sdk.md) 如何编写自定义检查并将它们打包为插件，以及（目前为模拟的）市场打算如何分发它们。 ### 🛠️ [故障排除](docs/troubleshooting.md) 常见错误的修复方法 —— 扫描失败、工具链误检、kubeconfig 问题和 Docker daemon 连接问题。
## 🗺️ 已完成与即将推出的功能 | 状态 | 内容 | |---|---| | ✅ 已完成 | 核心检查 —— 扫描你的电脑、容器和云设置 | | ✅ 已完成 | 保存“以前”的快照并将其与后续扫描进行对比 | | ✅ 已完成 | 无需联网即可工作的可选 AI 助手 | | 🔜 即将推出 | 真正的插件市场（目前只是演示版） | | 🔜 即将推出 | 支持更多编程语言和工具 | | 🔜 即将推出 | 在 GitHub Actions / GitLab CI 中使用 HealCode 的指南 |
## ❓ 常见问题
### 🧠 关于 HealCode
不会。HealCode 并不试图在 linting 上打败你的 linter，或在扫描上胜过你的密钥扫描器。它将这些工具已经能告诉你的内容整合到**一份报告**中，添加了跨领域的检查（容器、云/K8s、工具链），并跟踪自上次扫描以来发生的变化 —— 这是独立工具自身无法做到的。
`Node.js` · `Python` · `Java` · `Go` · `Rust` · `Flutter` 更多语言已在[路线图](#️-whats-done--whats-coming)中。
| Profile | 侧重点 | |---|---| | 🏗️ `DevOps` | 容器、云设置、配置漂移 | | 🔐 `Security` | 暴露的密钥、高风险设置 | | ⚡ `Minimal` | 更轻量、更快速的检查子集 | 使用以下命令进行设置： ``` healcode profile set [name] ```
### 🔒 隐私与要求
不需要。核心扫描（`healcode scan`）**完全在本地**运行。AI 层也是离线优先的 —— `healcode ai --offline` 在没有任何云端依赖的情况下工作。
不会。扫描是在本地针对你的文件系统、Docker 上下文、云 CLI 配置和 kubeconfig 运行的。除非你明确配置了集成功能要求这么做，否则不会上传任何内容。
运行 HealCode 本身需要 `Python ≥ 3.11`。你的*项目的*工具链可以是任何版本 —— HealCode 只会标记不匹配的情况（例如项目要求 3.11 但安装的是 3.9），而不会强制要求特定版本。
### ⚙️ 使用 HealCode
分数从 **100%** 开始，并根据每个发现的问题扣除相应的加权惩罚： | 严重程度 | 惩罚 | |---|---| | ✅ 通过 | 无 | | ⚠️ 警告 | 轻微 | | ❌ 严重 | 严重 | 有关完整的明细，请参阅[了解你的健康评分](#-understanding-your-health-score)。
可以 —— 有关 pipeline 示例和退出码行为，请参阅 [CI/CD 集成](#-cicd-integration)。
🔜 还没有 —— `healcode marketplace search` 目前只是一个模拟界面。真正的插件分发功能已在[路线图](#️-whats-done--whats-coming)中。
### 🆘 出现问题
⚠️ 请**不要**提出公开的 issue。有关负责任的披露说明，请参阅 [`SECURITY.md`](SECURITY.md)。
## 🤝 参与贡献 HealCode 目前处于早期阶段，非常欢迎社区的贡献 —— 无论是修复 bug、添加新的检查、完善文档，还是仅仅提出一个关于某些令人困惑之处的 issue。 ### 🚀 贡献者快速入门 **1. 克隆仓库** ``` git clone https://github.com/Ashish6298/HealCode.git ``` **2. 进入项目目录** ``` cd HealCode ``` **3. 以可编辑模式安装并包含开发依赖** ``` pip install -e .[dev] ``` ### ✅ 在提交 Pull Request 之前 - 阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解指南和 PR 流程 - 在所有互动中遵循 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) - 在开始新的工作之前，先检查[现有的 issue](https://github.com/Ashish6298/HealCode/issues)，以避免重复劳动 - 为任何行为更改在 [`tests/`](tests/) 中添加或更新测试 如果发现了安全问题？请不要提出公开的 issue —— 有关负责任的披露，请参阅 [`SECURITY.md`](SECURITY.md)。
## 🆘 支持 / 获取帮助
### 📋 在提问之前 一个简单的检查清单，可以解决大多数支持请求，甚至在这些请求被提交之前： | ✅ 检查项 | 原因 | |---|---| | 运行 `healcode --version` | 确认你使用的是最新发布的版本 | | 运行 `healcode config init` | 排除配置文件缺失或过时的可能性 | | 检查 [`docs/troubleshooting.md`](docs/troubleshooting.md) | 涵盖了常见的扫描、kubeconfig 和 Docker 连接错误 | | 搜索 [已关闭的 issue](https://github.com/Ashish6298/HealCode/issues?q=is%3Aissue+is%3Aclosed) | 你的问题可能已经在 `main` 分支上修复了 |
## 📄 许可证 HealCode 基于 **MIT License** 发布 —— 只要保留原始版权和许可声明，即可免费使用、修改和分发，包括在商业项目中。 有关详细信息，请参阅完整的 [LICENSE](LICENSE) 文件。
## 🙏 致谢
## 💙 为那些宁愿现在发现也不愿事后解释的开发者而构建 HealCode 的存在是为了让泄露的密码、错误的云配置或混乱的代码能在你自己的电脑上就被发现 —— 而不是在已经造成问题之后。 ### ⭐ 如果 HealCode 对你有帮助，请考虑点个 Star 这只是一件小事，但它能帮助其他开发者发现这个项目 —— 这也是支持该项目开发工作最简单的方式。
|
[](https://github.com/Ashish6298/HealCode) [](LICENSE) [](https://github.com/Ashish6298/HealCode/actions)
[](https://github.com/Ashish6298/HealCode/stargazers)
[](https://pepy.tech/projects/healcode)
[](#)
|
## 📚 目录
| ### 🌟 了解 HealCode - [概述](#overview) - [问题所在](#-the-problem) - [解决方案](#-the-solution) - [HealCode 适合谁？](#-who-is-healcode-for) - [HealCode 与手动操作的对比](#️-healcode-vs-doing-it-manually) - [扫描是如何工作的](#️-how-a-scan-works) - [实际运行效果](#-see-it-in-action) ### 🚀 使用 HealCode - [核心功能](#-key-features) - [安装说明](#-installation) - [快速开始](#-quick-start) - [配置示例](#-sample-configuration) | ### 🛠️ 参考 - [命令参考](#️-commands-reference) - [退出码](#-exit-codes) - [了解你的健康评分](#-understanding-your-health-score) - [CI/CD 集成](#-cicd-integration) - [文档中心](#-documentation-hub) ### 🤝 社区与项目 - [路线图](#️-whats-done--whats-coming) - [常见问题](#-faq) - [参与贡献](#-contributing) - [支持 / 获取帮助](#-support--get-help) - [许可证](#-license) |
## 概述 **HealCode** 是一个由 AI 驱动的开发者诊断 CLI 平台，旨在扫描本地开发环境、容器、云环境上下文、项目配置和源代码文件，以识别配置漂移、性能反模式和安全异味。 你无需再为了 Docker linting、Kubernetes 上下文检查、依赖审计和静态分析而费力协调各种独立工具，HealCode 只需对所有内容执行一次 `scan`，并将结果汇总为一个加权健康评分 —— 让你随时准确了解项目的健康状况。
| | |
| -------------------- | -------------------------------------------------------- |
| **扫描内容** | 本地环境, Docker/Compose, Kubernetes, 云 CLI, 源代码 |
| **覆盖语言** | Node.js, Python, Java, Go, Rust, Flutter |
| **评分机制** | 涵盖 40 多个类别的加权健康评分 |
| **AI 层** | 可选，离线优先 —— 无需任何云端依赖 |
| **安装命令** | `pip install healcode` |
| **环境要求** | Python ≥ 3.11 |
## ⚠️ 问题所在 大多数项目的崩溃并非源于一个巨大且明显的 bug。它们往往是因为一些没人及时注意到的小问题。 密码或密钥意外保存到了不该包含它的文件中；云配置悄悄指向了错误的位置；容器缺少在崩溃时能自动重启的设置；一段代码随着时间推移变得越来越复杂，直到最后没人敢去碰它。这些都不会在你执行 `git status` 时显示出来 —— 它们往往在后续才会暴露，表现为一个 bug、一次安全恐慌，或者一次深夜的紧急修复。 | ❌ 没有 HealCode 时 | |---| | 🔑 密钥或密码意外被保存到了代码中 | | 🐳 容器配置有误，但在崩溃前没人察觉 | | ☸️ 云端/Kubernetes 设置悄悄指向了错误的环境 | | 🧮 代码在不知不觉中慢慢变得混乱且难以理解 | | 🧰 你的工具版本（Python、Node.js 等）与项目实际需要的不同步 | | 📉 缺乏记录显示你的环境配置随着时间推移发生了什么变化及时间点 |
## 💡 解决方案 HealCode 可以为你检查所有这一切 —— 你的电脑、容器、云配置、代码 —— 只需一条简单的命令：`healcode scan`。无需再通过五种不同的工具拼凑出五份不同的报告，你可以为整个项目获得一个清晰的健康评分。 | ✅ HealCode 的不同之处 | |---| | 🔍 **一条命令检查所有内容** —— 系统、容器、云配置、工具和代码，一次性全部搞定 | | 📈 **一个简单的评分** —— 无需再拼凑五种不同工具的结果 | | 🗃️ **记录变化内容** —— 将今天的检查与上周的进行对比，准确看出差异 | | 🧠 **无需联网的智能助手** —— 一个可选的 AI 功能，能将问题归类，并告诉你优先修复什么，完全在离线状态下运行 | | ⏱️ **在你工作时持续检查** —— 开启 watch 模式，它会在你写代码时自动进行重新检查 |
## 🎯 HealCode 适合谁？ | 适用人群 | 为什么对他们有帮助 | |---|---| | 👨💻 **独立开发者** | 在你分享代码之前发现错误和暴露的密码 —— 而无需自己设置五个独立的工具。 | | 🧑🤝🧑 **小型团队** | 每个人都使用相同的配置文件，因此整个团队的项目都能以相同的方式进行检查。 | | 🏢 **DevOps / 基础设施人员** | 使用 `DevOps` 配置文件，专门关注容器、云设置和配置漂移。 | | 🔐 **注重安全的团队** | 使用 `Security` 配置文件，优先处理暴露的密钥和有风险的设置。 | | 🎓 **学生和初学者** | 在一份简单的报告中，了解“健康”的项目设置到底是什么样的 —— 这是尽早养成良好习惯的绝佳方式。 |
## ⚖️ HealCode 与手动操作的对比 你*确实可以*使用几个独立的工具来拼凑出相同的覆盖范围 —— 但以下是它们并排比较时的真实情况。 | 你需要检查的内容 | 手动操作 | 使用 HealCode | |---|---|---| | 🔑 代码中暴露的密钥 | 设置一个独立的密钥扫描工具 | 包含在 `healcode scan` 中 | | 🐳 Docker/Compose 配置错误 | 手动阅读 Dockerfile 和 compose 文件 | 包含在 `healcode scan` 中 | | ☸️ Kubernetes 上下文漂移 | 每次部署前手动检查 `kubectl config` | 包含在 `healcode scan` 中 | | 🧰 工具链版本不匹配 | 自己将 manifest 与已安装的版本进行交叉检查 | 包含在 `healcode scan` 中 | | 🧮 代码复杂度问题 | 每种语言运行一个独立的静态分析工具 | 包含在 `healcode scan` 中 | | 📊 整体的健康状况视图 | 手动汇总上述所有工具的结果 | 自动生成的一个加权评分 | | 🗃️ 跟踪随时间发生的变化 | 没有内置方法 —— 你必须自己记住或记录下来 | `healcode baseline` 会为你跟踪 | | ⏱️ 编码时的持续检查 | 每次都要手动重新运行每个工具 | `healcode watch` 会自动完成 |
## 🏗️ 扫描是如何工作的 当你运行 `healcode scan` 时，后台会发生以下事情 —— 并且是一步到位： ``` healcode scan │ ▼ ┌─────────────────────────┐ │ Runs all the checks │ └─────────────────────────┘ │ ┌───────────┬──────┼───────┬────────────┐ ▼ ▼ ▼ ▼ Your Containers Cloud & Your Tools Computer (Docker) Cloud Setup (Python, Node.js, etc.) │ ▼ Your Code (looks for messy or risky code) │ │ │ │ └────────────┴──────┬──────┴─────────────┘ ▼ ┌───────────────────┐ │ Adds it all up │ │ into one score │ └───────────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ Health Report Saves a record (what passed, (so you can compare what needs it to next time) attention) │ ▼ Optional: AI groups the problems and tells you what to fix first ```
## ⚡ 实际运行效果 运行 `healcode scan`，几秒钟内即可获得完整的环境健康报告 —— 无需任何配置。 ``` [1;36mHEALCODE DIAGNOSTICS ENGINE v1.0.0[0m [1;35m════════════════════════════════════════════════════[0m [1;34m▸ SYSTEM[0m [1;32m [✓] OS & shell environment healthy[0m [1;32m [✓] Disk space sufficient (62% free)[0m [1;34m▸ CONTAINERS[0m [1;32m [✓] Docker daemon running (v24.0.7)[0m [1;33m [!] docker-compose.yml missing restart policy on 'api' service[0m [1;34m▸ CLOUD & KUBERNETES[0m [1;33m [!] Kubernetes context using default namespace instead of dev-active[0m [1;32m [✓] AWS CLI credentials valid[0m [1;34m▸ RUNTIME & TOOLCHAINS[0m [1;32m [✓] Node.js v20.11.0 matches package.json engine constraint[0m [1;31m [✗] Python 3.9 installed — pyproject.toml requires >=3.11[0m [1;34m▸ STATIC CODE ANALYSIS[0m [1;33m [!] High cyclomatic complexity in utils/parser.py (score: 24)[0m [1;31m [✗] Found 1 exposed API key in config/settings.py:L14[0m [1;35m════════════════════════════════════════════════════[0m [1;36mOVERALL ENVIRONMENT HEALTH:[0m [[1;32m######################----[0m] [1;32m88.5%[0m [1;32m3 passed[0m · [1;33m2 warnings[0m · [1;31m2 critical[0m ``` | 符号 | 含义 | |:---:|---| | ✅ | 通过 —— 无需操作 | | ⚠️ | 警告 —— 值得复查 | | ❌ | 严重 —— 应在发布前修复 |
## 🚀 核心功能 - 🧠 **AI 驱动的诊断**：可选的 AI 编排层，提供根因分组、优先级评分和修复建议，且没有任何云端依赖。 - 📦 **Docker 和 Compose 审计**：检查引擎版本信息、Context 配置、Dockerfile 安全实践以及 docker-compose 重启结构。 - ☁️ **云端与 Kubernetes 上下文**：扫描本地 AWS、GCP 和 Azure CLI 设置，评估 kubeconfig 上下文有效性，并识别本地 Terraform 变量。 - ⚙️ **运行时和编译器智能分析**：检测 Node.js、Python、Java、Go、Rust 和 Flutter 工具链，并根据 manifest 约束匹配编译器版本。 - 🔍 **通用静态代码分析**：计算各种语言的圈复杂度、嵌套深度和嵌套循环性能瓶颈。 - 📈 **加权健康评分**：跨越 40 多个细粒度类别对代码库健康度进行评级。 - 🗃️ **基线与漂移检测**：捕获环境快照，以跟踪回归、改进和随着时间推移发生的环境变化。 - ⏱️ **Watch 模式**：实时轮询目录，实现快速增量重新扫描。
## 📦 安装说明 ``` pip install healcode ``` ### 环境要求 | 依赖项 | 版本 | 用途 | |---|---|---| | **Python** | ≥ 3.11 | Runtime | ### 验证安装 ``` healcode --version ```
## ⚡ 快速开始 只需四个命令，你就能从全新安装转变为获得一份带有已跟踪基线的完整环境健康报告。 ### 1️⃣ 初始化配置 在你的项目根目录创建一个 `healcode.json` 配置文件，让扫描从一开始就适应你的设置。 ``` healcode config init ``` ### 2️⃣ 运行诊断扫描 扫描你的本地环境、容器、云/K8s 上下文、工具链和源代码 —— 然后打印出一个加权健康评分。 ``` healcode scan ``` ### 3️⃣ 生成基线报告 为当前项目状态拍摄快照，以便将未来的扫描结果与它进行对比，从而发现配置漂移。 ``` healcode baseline create initial_state ``` ### 4️⃣ 运行 AI 智能摘要（离线优先） 按根因对发现的问题进行分组，并优先处理需要首先修复的内容 —— 不需要任何云端依赖。 ``` healcode ai --offline ```
## 📝 配置示例 运行 `healcode config init` 会在你的项目中创建一个 `healcode.json` 文件。以下是一个典型的配置示例： ``` { "profile": "DevOps", "targets": ["."], "checks": { "system": true, "docker": true, "kubernetes": true, "cloud": true, "toolchains": true, "static_analysis": true }, "exclude": [ "node_modules", "dist", ".venv" ], "ai": { "enabled": true, "offline": true } } ``` | 字段 | 控制内容 | |---|---| | `profile` | 当前激活的扫描配置（`DevOps`、`Security` 或 `Minimal`） | | `targets` | 要扫描的目录 —— 默认为当前项目 | | `checks` | 开启或关闭个别检查类别 | | `exclude` | 扫描期间要跳过的文件夹 | | `ai.enabled` / `ai.offline` | AI 层是否运行，以及是否完全保持离线状态 |
## 🛠️ 命令参考 ### 核心诊断 | 命令 | 用法 | 描述 | |---|---|---| | `scan` | `healcode scan [target]` | 运行活动的诊断检查并显示系统健康状况。 | | `baseline` | `healcode baseline create [name]` / `healcode baseline compare [name]` | 捕获项目快照或针对快照分析当前状态。 | | `watch` | `healcode watch` | 启动目录文件监视器，进行实时的增量重新扫描。 | ### 配置 | 命令 | 用法 | 描述 | |---|---|---| | `config` | `healcode config init` | 初始化项目配置文件 `healcode.json`。 | | `profile` | `healcode profile set [name]` | 调整当前活动的扫描配置（`DevOps`、`Security`、`Minimal`）。 | ### 智能与扩展 | 命令 | 用法 | 描述 | |---|---|---| | `ai` | `healcode ai --offline` | 编排根因诊断和修复建议。 | | `marketplace` | `healcode marketplace search [q]` | 搜索社区插件市场 *(模拟界面 —— 尚未上线)*。 |
## 📊 了解你的健康评分 每次 `healcode scan` 的结尾都会给出一个数字 —— 你整体的环境健康百分比。以下是如何解读它。 ### 评分是如何构成的 HealCode 运行的每一项检查（系统、容器、云/K8s、工具链、代码）都会贡献到 40 多个中的某一个。各类别的权重并不相同 —— 一个严重的发现（如暴露的密钥）比一个轻微的警告（如缺少重启策略）更能拉低分数。 分数 = 100% − (每个警告和严重发现的加权惩罚) ### 解读结果 | 分数范围 | 含义 | |---|---| | 🟢 **90–100%** | 健康 —— 无需采取紧急行动 | | 🟡 **70–89%** | 有一些警告 —— 值得在下次发布前审查 | | 🟠 **50–69%** | 存在多个问题 —— 建议在发布前予以解决 | | 🔴 **低于 50%** | 存在严重问题 —— 必须在继续操作前修复 | ### 拉低你分数的因素 | 严重程度 | 示例 | 影响 | |---|---|---| | ✅ 通过 | Docker daemon 正确运行 | 无惩罚 | | ⚠️ 警告 | Kubernetes 上下文使用了默认的 namespace | 轻微惩罚 | | ❌ 严重 | 源代码中存在暴露的 API key | 严重惩罚 |
## 📁 文档中心 完整指南位于 [`docs/`](docs/) 文件夹中。以下是每个文档的涵盖内容及适用场景： ### 📖 [快速入门](docs/getting_started.md) 你使用 HealCode 的前十分钟 —— 安装、初始化配置、运行你的第一次 `scan` 以及解读健康评分输出。如果你从未用过 HealCode，请从这里开始。 ### 💾 [安装说明](docs/installation.md) 针对 Windows、Linux 和 macOS 的特定平台设置说明，包括 Python 版本要求和常见的安装问题（权限、PATH 冲突、virtualenv 设置）。 ### ⚙️ [配置参考](docs/configuration.md) `healcode.json` 中可用的所有选项 —— 扫描配置（`DevOps`、`Security`、`Minimal`）、包含/排除哪些检查，以及如何将扫描范围限定在特定目录或目标上。 ### 📐 [架构设计](docs/architecture.md) 扫描在底层的实际运行方式：检查 pipeline、发现的问题是如何被评分并加权汇总到整体百分比中的，以及可选的 AI 层是如何在离线状态下处理结果的。 ### ⌨️ [CLI 参考](docs/cli_reference.md) 包含每个 flag 和子命令的完整命令列表 —— 这是 `scan`、`config`、`profile`、`baseline`、`watch` 和 `ai` 的权威参考。 ### 🔌 [Plugin SDK](docs/plugin_sdk.md) 如何编写自定义检查并将它们打包为插件，以及（目前为模拟的）市场打算如何分发它们。 ### 🛠️ [故障排除](docs/troubleshooting.md) 常见错误的修复方法 —— 扫描失败、工具链误检、kubeconfig 问题和 Docker daemon 连接问题。
## 🗺️ 已完成与即将推出的功能 | 状态 | 内容 | |---|---| | ✅ 已完成 | 核心检查 —— 扫描你的电脑、容器和云设置 | | ✅ 已完成 | 保存“以前”的快照并将其与后续扫描进行对比 | | ✅ 已完成 | 无需联网即可工作的可选 AI 助手 | | 🔜 即将推出 | 真正的插件市场（目前只是演示版） | | 🔜 即将推出 | 支持更多编程语言和工具 | | 🔜 即将推出 | 在 GitHub Actions / GitLab CI 中使用 HealCode 的指南 |
## ❓ 常见问题
*关于人们在安装 HealCode 之前（和之后）最常问的问题的快速解答。*
### 🧠 关于 HealCode
HealCode 会取代我现有的 linter 或密钥扫描器吗？
不会。HealCode 并不试图在 linting 上打败你的 linter，或在扫描上胜过你的密钥扫描器。它将这些工具已经能告诉你的内容整合到**一份报告**中，添加了跨领域的检查（容器、云/K8s、工具链），并跟踪自上次扫描以来发生的变化 —— 这是独立工具自身无法做到的。
HealCode 支持哪些语言的静态分析？
`Node.js` · `Python` · `Java` · `Go` · `Rust` · `Flutter` 更多语言已在[路线图](#️-whats-done--whats-coming)中。
DevOps、Security 和 Minimal profile 有什么区别？
| Profile | 侧重点 | |---|---| | 🏗️ `DevOps` | 容器、云设置、配置漂移 | | 🔐 `Security` | 暴露的密钥、高风险设置 | | ⚡ `Minimal` | 更轻量、更快速的检查子集 | 使用以下命令进行设置： ``` healcode profile set [name] ```
我需要连接互联网才能使用 HealCode 吗？
不需要。核心扫描（`healcode scan`）**完全在本地**运行。AI 层也是离线优先的 —— `healcode ai --offline` 在没有任何云端依赖的情况下工作。
HealCode 会把我的代码或密钥发送到别处吗？
不会。扫描是在本地针对你的文件系统、Docker 上下文、云 CLI 配置和 kubeconfig 运行的。除非你明确配置了集成功能要求这么做，否则不会上传任何内容。
我需要什么版本的 Python？
运行 HealCode 本身需要 `Python ≥ 3.11`。你的*项目的*工具链可以是任何版本 —— HealCode 只会标记不匹配的情况（例如项目要求 3.11 但安装的是 3.9），而不会强制要求特定版本。
健康评分是如何计算的？
分数从 **100%** 开始，并根据每个发现的问题扣除相应的加权惩罚： | 严重程度 | 惩罚 | |---|---| | ✅ 通过 | 无 | | ⚠️ 警告 | 轻微 | | ❌ 严重 | 严重 | 有关完整的明细，请参阅[了解你的健康评分](#-understanding-your-health-score)。
我可以在 CI/CD 中运行 HealCode 吗？
可以 —— 有关 pipeline 示例和退出码行为，请参阅 [CI/CD 集成](#-cicd-integration)。
插件市场上线了吗？
🔜 还没有 —— `healcode marketplace search` 目前只是一个模拟界面。真正的插件分发功能已在[路线图](#️-whats-done--whats-coming)中。
我发现了一个安全漏洞 —— 我该在哪里报告？
⚠️ 请**不要**提出公开的 issue。有关负责任的披露说明，请参阅 [`SECURITY.md`](SECURITY.md)。
## 🤝 参与贡献 HealCode 目前处于早期阶段，非常欢迎社区的贡献 —— 无论是修复 bug、添加新的检查、完善文档，还是仅仅提出一个关于某些令人困惑之处的 issue。 ### 🚀 贡献者快速入门 **1. 克隆仓库** ``` git clone https://github.com/Ashish6298/HealCode.git ``` **2. 进入项目目录** ``` cd HealCode ``` **3. 以可编辑模式安装并包含开发依赖** ``` pip install -e .[dev] ``` ### ✅ 在提交 Pull Request 之前 - 阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解指南和 PR 流程 - 在所有互动中遵循 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) - 在开始新的工作之前，先检查[现有的 issue](https://github.com/Ashish6298/HealCode/issues)，以避免重复劳动 - 为任何行为更改在 [`tests/`](tests/) 中添加或更新测试 如果发现了安全问题？请不要提出公开的 issue —— 有关负责任的披露，请参阅 [`SECURITY.md`](SECURITY.md)。
## 🆘 支持 / 获取帮助
*遇到困难了？根据你的需求，这里是最快的解决途径。*
| ### 🐛 发现了 Bug？ 首先搜索[现有 issue](https://github.com/Ashish6298/HealCode/issues) —— 可能已经有人遇到了。 如果是新问题，请[创建一个 issue](https://github.com/Ashish6298/HealCode/issues/new) 并提供： - 你的操作系统和 Python 版本 - 你运行的命令 - 预期与实际的行为 - 相关的日志输出（如果有） | ### 💡 有功能想法？ [提交一个功能请求](https://github.com/Ashish6298/HealCode/issues/new) —— 描述你试图解决的问题，而不仅仅是解决方案。这有助于我们正确地进行设计。 请先查看[路线图](#️-whats-done--whats-coming)，看看该功能是否已经包含在计划中。 |
| ### ❓ 有疑问？ 请从[常见问题](#-faq)和[文档中心](#-documentation-hub)开始 —— 大多数“我该如何……”类的问题都已经在那里得到了解答。 仍然没有解决？请发起一个 [GitHub Discussion](https://github.com/Ashish6298/HealCode/discussions)（如果尚未启用讨论功能，则可以提交 issue）。 | ### 🔐 发现了安全问题？ **请不要提出公开的 issue。** 请按照 [`SECURITY.md`](SECURITY.md) 中的负责任披露流程操作 —— 我们会私下回复你。 |
### 📋 在提问之前 一个简单的检查清单，可以解决大多数支持请求，甚至在这些请求被提交之前： | ✅ 检查项 | 原因 | |---|---| | 运行 `healcode --version` | 确认你使用的是最新发布的版本 | | 运行 `healcode config init` | 排除配置文件缺失或过时的可能性 | | 检查 [`docs/troubleshooting.md`](docs/troubleshooting.md) | 涵盖了常见的扫描、kubeconfig 和 Docker 连接错误 | | 搜索 [已关闭的 issue](https://github.com/Ashish6298/HealCode/issues?q=is%3Aissue+is%3Aclosed) | 你的问题可能已经在 `main` 分支上修复了 |
## 📄 许可证 HealCode 基于 **MIT License** 发布 —— 只要保留原始版权和许可声明，即可免费使用、修改和分发，包括在商业项目中。 有关详细信息，请参阅完整的 [LICENSE](LICENSE) 文件。
## 🙏 致谢
**构建于**
The Python packaging & CLI tooling ecosystem
|
**灵感来源于**
The linters & scanners HealCode brings together
|
**测试环境**
Real-world Docker, K8s & multi-language setups
|
:heart: **致谢** Every contributor & early adopter |
## 💙 为那些宁愿现在发现也不愿事后解释的开发者而构建 HealCode 的存在是为了让泄露的密码、错误的云配置或混乱的代码能在你自己的电脑上就被发现 —— 而不是在已经造成问题之后。 ### ⭐ 如果 HealCode 对你有帮助，请考虑点个 Star 这只是一件小事，但它能帮助其他开发者发现这个项目 —— 这也是支持该项目开发工作最简单的方式。
标签：IPv6支持, JS文件枚举, LNA, MITM代理, SOC Prime, 代码诊断, 可视化界面, 子域名突变, 安全专业人员, 开发工具, 日志审计, 请求拦截, 逆向工具, 错误基检测, 静态代码分析