wimotek-edge-agent 1.0.6 → 1.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wimotek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include setup.py
+recursive-include wimotek_edge_agent *.py py.typed

package/README.md

@@ -8,6 +8,7 @@ Commercial-grade edge access control, service bridge, and tunnel agent featuring
 - [Architecture](#architecture)
 - [Decision matrix](#decision-matrix)
 - [Installation & Quickstart](#installation--quickstart)
+  - [PyPI 安装与 ModuleNotFoundError 深度排查](#pypi-安装与-modulenotfounderror-深度排查)
 - [Environment variables](#environment-variables)
 - [CLI usage](#cli-usage)
 - [Programmatic usage](#programmatic-usage)
@@ -73,25 +74,158 @@ Commercial-grade edge access control, service bridge, and tunnel agent featuring
 
 ## Installation & Quickstart
 
-### Python Package
+### 1. PyPI 安装与导入规则
+
+> 📌 **关键名称区别**：
+> - **PyPI 仓库包名（用于 pip 安装）**：`wimotek-edge-agent`（中划线 `-`）
+> - **Python 导入包名（用于代码 import）**：`wimotek_edge_agent`（下划线 `_`）
+
+在终端中使用当前 Python 运行环境安装：
 
 ```bash
-pip install wimotek-edge-agent
+# 推荐做法：使用当前 Python 解释器执行，避免装错环境
+python -m pip install --upgrade wimotek-edge-agent
+```
+
+在 Python 代码中使用标准导入：
+
+```python
+from wimotek_edge_agent import EdgeAgent, Config, AccessPolicyEngine
 ```
 
-From source:
+---
+
+### PyPI 安装与 ModuleNotFoundError 深度排查
+
+如果在上传 PyPI 后本地执行 `from wimotek_edge_agent ...` 报 `ModuleNotFoundError: No module named 'wimotek_edge_agent'`，请按以下 4 种最常见情况逐一排查：
+
+#### 🔴 原因 1：Python 运行环境不一致（最常见，占 80%）
+- **根因分析**：
+  在终端中执行的 `pip install` 将包安装到了全局 Python、系统 Python 或 Conda 的 base 环境；而你在 IDE（VS Code、PyCharm、Cursor）或者运行代码时，使用的是项目独立的虚拟环境（例如 `.venv`）。
+- **一键自查命令**：
+  在运行报错的代码同级终端中执行：
+  ```bash
+  python -c "import sys; print('当前 Python 解释器路径:', sys.executable); print('模块搜索路径:', sys.path)"
+  ```
+- **解决方法**：
+  确保使用**执行代码的同一个 Python 解释器**进行安装：
+  ```bash
+  python -m pip install --upgrade wimotek-edge-agent
+  ```
+  如果使用了虚拟环境，先激活虚拟环境再安装：
+  ```bash
+  # Linux / macOS:
+  source .venv/bin/activate
+  python -m pip install --upgrade wimotek-edge-agent
+
+  # Windows (PowerShell / CMD):
+  .venv\Scripts\activate
+  python -m pip install --upgrade wimotek-edge-agent
+  ```
+
+---
+
+#### 🔴 原因 2：PyPI 全球 CDN 刷新延迟 或 国内镜像源未同步
+- **根因分析**：
+  1. 上传到 PyPI（通过 `twine upload dist/*`）后，PyPI 主站的全球 Fastly CDN 边缘节点通常需要 1~5 分钟同步刷新。
+  2. 如果你的本地 pip 配置了国内镜像源（如清华源、阿里源、腾讯源），镜像源通常会有几十分钟到数小时的同步周期。如果刚上传就立刻通过镜像源安装，镜像源尚未同步，会提示找不到包或匹配不到版本。
+  3. `pip` 本地存在 HTTP 缓存，可能命中了上传前的 404 记录。
+- **解决方法**：
+  直连 PyPI 官方源，并跳过本地缓存强制安装：
+  ```bash
+  python -m pip install -i https://pypi.org/simple/ --no-cache-dir --upgrade wimotek-edge-agent
+  ```
+
+---
+
+#### 🔴 原因 3：打包时生成了“空包”（Empty Wheel 陷阱）
+- **根因分析**：
+  打包工具在执行 `python -m build` 或 `python setup.py bdist_wheel` 时，如果打包配置中未显式声明包路径，生成的 `.whl` 文件可能**只包含元数据 `wimotek_edge_agent-1.0.0.dist-info/`，而漏掉了 `wimotek_edge_agent/` 源码目录**。
+  安装时 pip 会显示安装成功，但 `site-packages` 里其实没有代码目录，因此运行时必然报错 `ModuleNotFoundError`。
+- **一键自查本地构建产物**：
+  在执行打包的机器上检查生成的 `.whl` 和 `.tar.gz` 内容：
+  ```bash
+  # 检查 wheel 文件内容列表
+  unzip -l dist/wimotek_edge_agent-*.whl
+
+  # 或检查源码 tar 包
+  tar -ztvf dist/wimotek_edge_agent-*.tar.gz
+  ```
+  **正常的文件列表**必须包含以下源码文件：
+  ```text
+  wimotek_edge_agent/__init__.py
+  wimotek_edge_agent/agent.py
+  wimotek_edge_agent/config.py
+  wimotek_edge_agent/policy.py
+  wimotek_edge_agent/trust_store.py
+  ...
+  wimotek_edge_agent/py.typed
+  ```
+  如果列表里全都是 `dist-info/` 开头的文件，而**没有** `wimotek_edge_agent/`，则说明上传的是空包！
+- **彻底根治与重新发布**：
+  本项目已在 `pyproject.toml` 中配置了明确的 setuptools 规则：
+  ```toml
+  [tool.setuptools]
+  packages = ["wimotek_edge_agent"]
+
+  [tool.setuptools.package-data]
+  wimotek_edge_agent = ["py.typed"]
+  ```
+  并配备了 `MANIFEST.in` 与 `setup.py` 双重保障。重新打包与发布：
+  ```bash
+  # 1. 清理所有历史缓存构建目录
+  rm -rf dist build *.egg-info
+
+  # 2. 安装/升级标准构建工具
+  python -m pip install --upgrade build twine
+
+  # 3. 规范打包
+  python -m build
+
+  # 4. 验证 wheel 是否包含代码
+  unzip -l dist/*.whl | grep "wimotek_edge_agent/__init__.py"
+
+  # 5. 上传到 PyPI（注意修改 pyproject.toml 递增版本号，如 1.0.1）
+  twine upload dist/*
+  ```
+
+---
+
+#### 🔴 原因 4：当前工作目录文件遮蔽（Shadowing）
+- **根因分析**：
+  Python 会把执行命令的当前目录（`sys.path[0]`）作为最高优先级的模块搜索路径。如果当前目录下碰巧有一个名为 `wimotek_edge_agent.py` 的测试脚本，或者一个空的同名文件夹，Python 会直接加载该文件，导致无法找到内部类和函数。
+- **排查验证**：
+  ```bash
+  python -c "import wimotek_edge_agent; print('实际加载的文件路径:', wimotek_edge_agent.__file__)"
+  ```
+  如果路径指向了当前临时目录而非 `site-packages`，说明发生了路径遮蔽。
+
+---
+
+### 2. 本地源码免上传开发（推荐）
+
+在日常开发、测试或修改功能时，建议在本地项目根目录下使用可编辑模式（Editable Mode）直接安装，无需频繁上传 PyPI：
 
 ```bash
-git clone https://github.com/wimotek/wimotek-edge-agent.git
 cd wimotek-edge-agent
 pip install -e .
 ```
 
-### Node.js CLI Runner
+安装后，本地对 `wimotek_edge_agent/` 目录中代码的任何改动会立即反映在 Python 环境中。验证：
+
+```bash
+python -c "import wimotek_edge_agent; print('版本:', wimotek_edge_agent.__version__, '路径:', wimotek_edge_agent.__file__)"
+```
+
+---
+
+### 3. Node.js CLI Runner
+
+除了 Python CLI 外，还可通过 npm / npx 直接运行：
 
 ```bash
 npm install -g wimotek-edge-agent
-# or directly execute:
+# 或者直接免安装执行：
 npx wimotek-edge-agent --help
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wimotek-edge-agent",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Universal Edge Reverse Proxy & Service Bridge Agent CLI Runner",
   "bin": {
     "wimotek-edge-agent": "./bin/cli.js",

package/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wimotek-edge-agent"
-version = "1.0.0.6"
+version = "1.0.0.7"
 description = "Universal Edge Reverse Proxy & Service Bridge Agent"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -42,10 +42,12 @@ wimotek-edge-agent = "wimotek_edge_agent.agent:main"
 wimotek-agent = "wimotek_edge_agent.agent:main"
 edge-agent = "wimotek_edge_agent.agent:main"
 
-[tool.setuptools.packages.find]
-where = [
-    ".",
+[tool.setuptools]
+packages = [
+    "wimotek_edge_agent",
 ]
-include = [
-    "wimotek_edge_agent*",
+
+[tool.setuptools.package-data]
+wimotek_edge_agent = [
+    "py.typed",
 ]

package/setup.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Standard setup.py shim for backward compatibility with older build tools and editable installs."""
+from setuptools import setup, find_packages
+
+setup(
+    packages=find_packages(include=["wimotek_edge_agent", "wimotek_edge_agent.*"]),
+    package_data={
+        "wimotek_edge_agent": ["py.typed"],
+    },
+)