@mcptoolshop/venvkit 0.2.5 → 1.0.0

package/README.zh.md

@@ -1,74 +1,74 @@
-<p align="center">
-  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.md">English</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/venvkit/readme.png" alt="venvkit" width="400">
 </p>
-
-# venvkit
-
-> [MCP Tool Shop](https://mcptoolshop.com) 的一部分
-
+
+# venvkit
+
+> [MCP Tool Shop](https://mcptoolshop.com) 的一部分
+
 <p align="center">
   <a href="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
   <a href="https://mcp-tool-shop-org.github.io/venvkit/"><img src="https://img.shields.io/badge/Landing_Page-live-blue?style=flat-square" alt="Landing Page"></a>
   <a href="https://www.npmjs.com/package/@mcptoolshop/venvkit"><img src="https://img.shields.io/npm/v/@mcptoolshop/venvkit?style=flat-square&color=cb3837" alt="npm version"></a>
 </p>
-
-**用于 Windows 机器学习工作流程的 Python 虚拟环境诊断工具包。**
-
-该工具会扫描您的系统中的 Python 环境，诊断健康问题（SSL、DLL、ABI 不匹配、路径泄露），跟踪任务执行历史，检测不可靠的任务，并生成一个生态系统图。
-
-## 30 秒快速入门
-
+
+**适用于 Windows 机器学习工作流程的 Python 虚拟环境诊断工具包。**
+
+该工具会扫描您的系统中的 Python 环境，诊断健康问题（SSL、DLL、ABI 不匹配、路径泄露），跟踪任务执行历史记录，检测不可靠的任务，并生成一个生态系统地图。
+
+## 30 秒快速入门
+
 ```bash
 git clone https://github.com/mcp-tool-shop-org/venvkit && cd venvkit
 npm install && npm run build
 node dist/map_cli.js --root C:\projects --httpsProbe
 # Open .venvkit/venv-map.html in your browser
 ```
-
-## 功能
-
-- **doctorLite** - 快速检查任何 Python 解释器的健康状况
-- SSL/TLS 验证
-- DLL 加载失败（常见于 PyTorch/CUDA）
-- ABI 不匹配（ARM 与 x86）
-- pip 检查
-- 用户站点和 PYTHONPATH 泄露检测
-
-- **scanEnvPaths** - 发现系统中的所有 Python 环境
-- 查找 venvs、conda 环境、pyenv 版本、基本解释器
-- 可配置的深度和过滤
-
-- **mapRender** - 可视化您的 Python 生态系统
-- 图形 JSON 输出，用于程序化使用
-- Mermaid 图表，用于文档
-- 基本解释器分组，并进行影响范围分析
-- 任务路由可视化
-
-- **runLog** - 跟踪任务执行历史
-- 仅追加的 JSONL 格式
-- 记录哪个环境运行了哪个任务
-- 记录成功/失败，并进行错误分类
-
-- **taskCluster** - 按签名聚合任务运行
-- 检测不可靠的任务（不一致的通过/失败）
-- 基于环境的不可靠性检测
-- 识别失败热点
-- 传染分析（共享的根本原因）
-
-## 安装
-
+
+## 功能
+
+- **doctorLite** - 快速检查任何 Python 解释器的健康状况
+- SSL/TLS 验证
+- DLL 加载失败（常见于 PyTorch/CUDA）
+- ABI 不匹配（ARM 与 x86）
+- pip 检查
+- 检测用户站点和 PYTHONPATH 泄露
+
+- **scanEnvPaths** - 发现系统中的所有 Python 环境
+- 查找 venvs、conda 环境、pyenv 版本、基本解释器
+- 可配置的深度和过滤
+
+- **mapRender** - 可视化您的 Python 生态系统
+- 图形 JSON 输出，用于程序化使用
+- Mermaid 图表，用于文档
+- 基本解释器分组，并进行影响范围分析
+- 任务路由可视化
+
+- **runLog** - 跟踪任务执行历史记录
+- 仅追加的 JSONL 格式
+- 记录哪个环境运行了哪个任务
+- 记录成功/失败，并进行错误分类
+
+- **taskCluster** - 按签名聚合任务运行
+- 检测不可靠的任务（一致性不通过）
+- 检测与环境相关的不可靠性
+- 识别失败热点
+- 传染分析（共享的根本原因）
+
+## 安装
+
 ```bash
 npm install
 npm run build
 ```
-
-## 命令行用法
-
+
+## 命令行用法
+
 ```bash
 # Scan current directory and generate ecosystem map
 node dist/map_cli.js
@@ -82,33 +82,33 @@ node dist/map_cli.js --runlog .venvkit/runs.jsonl
 # Output options
 node dist/map_cli.js --out ./output --minScore 50 --strict --httpsProbe
 ```
-
-### 命令行选项
-
-| Flag | 描述 |
-| ------ | ------------- |
-| `--root, -r` | 要扫描的目录（可以指定多个） |
-| `--out` | 输出目录（默认为：`.venvkit`） |
-| `--maxDepth` | 要扫描的最大目录深度（默认为：5） |
-| `--strict` | 启用严格模式检查 |
-| `--httpsProbe` | 测试 HTTPS 连接 |
-| `--minScore` | 过滤健康评分低于此值的环境 |
-| `--concurrency` | 并行检查（默认为：CPU 数量） |
-| `--runlog` | 任务运行日志的路径（JSONL） |
-| `--no-tasks` | 跳过任务可视化 |
-
-### 输出
-
-| File | 描述 |
-| ------ | ------------- |
-| `venv-map.json` | 完整的图形数据（节点、边、摘要） |
-| `venv-map.mmd` | Mermaid 图表源代码 |
-| `venv-map.html` | 交互式查看器 |
-| `reports.json` | 原始的 doctorLite 报告 |
-| `insights.json` | 可操作的建议 |
-
-## 程序化用法
-
+
+### 命令行选项
+
+| 标志 | 描述 |
+|------|-------------|
+| `--root, -r` | 要扫描的目录（可以指定多个） |
+| `--out` | 输出目录（默认为：`.venvkit`） |
+| `--maxDepth` | 要扫描的最大目录深度（默认为：5） |
+| `--strict` | 启用严格模式检查 |
+| `--httpsProbe` | 测试 HTTPS 连接 |
+| `--minScore` | 过滤健康评分低于此值的环境 |
+| `--concurrency` | 并行检查（默认为：CPU 数量） |
+| `--runlog` | 任务运行日志的路径（JSONL） |
+| `--no-tasks` | 跳过任务可视化 |
+
+### 输出
+
+| 文件 | 描述 |
+|------|-------------|
+| `venv-map.json` | 完整的图形数据（节点、边、摘要） |
+| `venv-map.mmd` | Mermaid 图表源代码 |
+| `venv-map.html` | 交互式查看器 |
+| `reports.json` | 原始的 doctorLite 报告 |
+| `insights.json` | 可操作的建议 |
+
+## 程序化用法
+
 ```typescript
 import { doctorLite, scanEnvPaths, mapRender, readRunLog } from 'venvkit';
 
@@ -143,11 +143,11 @@ const { graph, mermaid, insights } = mapRender(reports, runs, {
   includeHotEdgeLabels: true,
 });
 ```
-
-## 运行日志模式
-
-通过将事件追加到 JSONL 文件来跟踪任务执行：
-
+
+## 运行日志模式
+
+通过将事件追加到 JSONL 文件来跟踪任务执行：
+
 ```typescript
 import { appendRunLog, newRunId } from 'venvkit';
 
@@ -172,11 +172,11 @@ await appendRunLog('.venvkit/runs.jsonl', {
   },
 });
 ```
-
-## 任务聚类
-
-当您有许多任务运行时，venvkit 会根据签名对它们进行聚类：
-
+
+## 任务聚类
+
+当您有许多任务运行时，venvkit 会根据签名对它们进行聚类：
+
 ```typescript
 import { clusterRuns, isFlaky, getFailingEnvs } from 'venvkit';
 
@@ -192,11 +192,11 @@ for (const c of clusters) {
   }
 }
 ```
-
-## 图形模式
-
-`mapRender` 输出遵循稳定的 JSON 模式：
-
+
+## 图形模式
+
+`mapRender` 输出遵循稳定的 JSON 模式：
+
 ```typescript
 type GraphJSONv1 = {
   version: '1.0';
@@ -217,47 +217,58 @@ type GraphJSONv1 = {
   edges: GraphEdge[];
 };
 ```
-
-### 节点类型
-
-| Type | 描述 |
-| ------ | ------------- |
-| `base` | 基本 Python 解释器（例如：`C:\Python311`） |
-| `venv` | 虚拟环境 |
-| `task` | 任务签名（聚类运行） |
-
-### 边类型
-
-| Type | 描述 |
-| ------ | ------------- |
-| `USES_BASE` | venv → 基本关系 |
-| `ROUTES_TASK_TO` | 任务 → 环境路由 |
-| `FAILED_RUN` | 任务 → 环境失败（Mermaid 中以虚线表示） |
-
-## 查找代码
-
-| Code | 严重性 | 描述 |
-| ------ | ---------- | ------------- |
-| `SSL_BROKEN` | bad | SSL 模块无法导入 |
-| `CERT_STORE_FAIL` | warn | HTTPS 证书验证失败 |
-| `DLL_LOAD_FAIL` | bad | 本机扩展 DLL 加载失败 |
-| `ABI_MISMATCH` | bad | 二进制不兼容（ARM/x86） |
-| `PIP_MISSING` | warn | pip 不可用 |
-| `PIP_CHECK_FAIL` | warn | 检测到依赖项冲突 |
-| `USER_SITE_LEAK` | warn | venv 环境中启用了用户 site-packages。 |
-| `PYTHONPATH_INJECTED` | warn | 已设置 PYTHONPATH 环境变量。 |
-| `ARCH_MISMATCH` | bad | 使用了 32 位的 Python，但需要 64 位。 |
-| `PYVENV_CFG_INVALID` | warn | pyvenv.cfg 文件损坏或缺失。 |
-
-## 开发
-
+
+### 节点类型
+
+| 类型 | 描述 |
+|------|-------------|
+| `base` | 基本 Python 解释器（例如：`C:\Python311`） |
+| `venv` | 虚拟环境 |
+| `task` | 任务签名（聚类运行） |
+
+### 边类型
+
+| 类型 | 描述 |
+|------|-------------|
+| `USES_BASE` | venv → 基本关系 |
+| `ROUTES_TASK_TO` | 任务 → 环境 路由 |
+| `FAILED_RUN` | 任务 → 环境 失败（Mermaid 中为虚线） |
+
+## 错误代码
+
+| 代码 | 严重性 | 描述 |
+|------|----------|-------------|
+| `SSL_BROKEN` | bad | SSL 模块导入失败 |
+| `CERT_STORE_FAIL` | warn | HTTPS 证书验证失败 |
+| `DLL_LOAD_FAIL` | bad | 本机扩展 DLL 加载失败 |
+| `ABI_MISMATCH` | bad | 二进制不兼容（ARM/x86） |
+| `PIP_MISSING` | warn | pip 不可用 |
+| `PIP_CHECK_FAIL` | warn | 检测到依赖项冲突 |
+| `USER_SITE_LEAK` | warn | venv 中启用了用户站点包 |
+| `PYTHONPATH_INJECTED` | warn | 设置了 PYTHONPATH 环境变量 |
+| `ARCH_MISMATCH` | bad | 当需要 64 位的 Python 时，使用了 32 位的 Python |
+| `PYVENV_CFG_INVALID` | warn | pyvenv.cfg 文件损坏或缺失 |
+
+## 开发
+
 ```bash
 npm install
 npm run typecheck  # Type check
 npm run test       # Run tests
 npm run build      # Build to dist/
 ```
-
-## 许可证
-
-MIT 协议。
+
+## 安全与数据范围
+
+- **只读扫描：** Python 可执行文件和 pyvenv.cfg 文件会被读取，但绝不会被修改。
+- **子进程：** 使用受控参数启动 `python` 进程，不涉及 shell 执行。
+- **网络：** 可选的 `--httpsProbe` 参数用于测试 SSL 证书，不会发送其他类型的网络请求。
+- **不收集或发送任何遥测数据**，详细的安全策略请参见 [SECURITY.md](SECURITY.md) 文件。
+
+## 许可证
+
+MIT
+
+---
+
+由 [MCP Tool Shop](https://mcp-tool-shop.github.io/) 构建。

package/dist/doctorLite.d.ts

@@ -0,0 +1,75 @@
+export type Severity = "info" | "warn" | "bad";
+export type HealthStatus = "good" | "warn" | "bad" | "unknown";
+export type FindingCode = "PYTHON_EXEC_MISSING" | "NOT_A_VENV" | "ARCH_MISMATCH" | "PIP_MISSING" | "PIP_POINTS_TO_OTHER_PYTHON" | "PYTHONPATH_INJECTED" | "USER_SITE_ENABLED" | "USER_SITE_LEAK" | "PIP_CHECK_FAIL" | "MULTI_VERSION_ON_PATH" | "RESOLVER_CONFLICT_HINT" | "OUTDATED_INSTALL_TOOLING" | "IMPORT_FAIL" | "DLL_LOAD_FAIL" | "ABI_MISMATCH" | "SSL_BROKEN" | "CERT_STORE_FAIL" | "SUBPROCESS_BROKEN" | "PYVENV_CFG_INVALID";
+export type Finding = {
+    code: FindingCode;
+    severity: Severity;
+    penalty: number;
+    what: string;
+    why: string;
+    fix: Array<{
+        title: string;
+        steps: string[];
+    }>;
+    evidence?: Record<string, unknown>;
+};
+export type RunResult = {
+    ok: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+};
+export type CmdRunner = (cmd: string, args: string[], opts: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs: number;
+}) => Promise<RunResult>;
+export type DoctorLiteOptions = {
+    /** Python executable path (venv python or base python). Required. */
+    pythonPath: string;
+    /** Modules to import-test (task required caps). */
+    requiredModules?: string[];
+    /** If true, also do a HTTPS probe to pypi.org (can fail in corp MITM; still useful). */
+    httpsProbe?: boolean;
+    /** If task requires 64-bit python, set true. If unknown, leave undefined. */
+    requireX64?: boolean;
+    /** Timeout per subprocess (ms). */
+    timeoutMs?: number;
+    /** If true, run heavier checks (pip check, multi-version scan). */
+    strict?: boolean;
+    /** Override environment variables passed to python. */
+    env?: Record<string, string | undefined>;
+};
+export type DoctorLiteReport = {
+    pythonPath: string;
+    ranAt: string;
+    status: HealthStatus;
+    score: number;
+    summary: string;
+    facts?: FactsResult;
+    findings: Finding[];
+};
+type FactsResult = {
+    version: string;
+    version_info: number[];
+    executable: string;
+    prefix: string;
+    base_prefix: string | null;
+    bits: number;
+    machine: string;
+    os: string;
+    py_path: string[];
+    enable_user_site: boolean | null;
+    user_site: string;
+};
+/**
+ * Run a subprocess with timeout, capturing stdout/stderr.
+ */
+export declare function runCmd(cmd: string, args: string[], opts: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs: number;
+}): Promise<RunResult>;
+export declare function doctorLite(opts: DoctorLiteOptions, runner?: CmdRunner): Promise<DoctorLiteReport>;
+export declare function envIdFromPythonPath(pythonPath: string): string;
+export {};
+//# sourceMappingURL=doctorLite.d.ts.map

package/dist/doctorLite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctorLite.d.ts","sourceRoot":"","sources":["../doctorLite.ts"],"names":[],"mappings":"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"}