From adff2bab8968a83a110dd3c85ddd36c2bbdf0c3a Mon Sep 17 00:00:00 2001
From: q <qaiu@qq.com>
Date: Mon, 12 Jan 2026 18:59:19 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E4=BD=BF=E7=94=A8=20graalpy-maven-plug?=
 =?UTF-8?q?in=20=E8=87=AA=E5=8A=A8=E5=AE=89=E8=A3=85=20requests=20pip=20?=
 =?UTF-8?q?=E5=8C=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- parser/pom.xml: 添加 packages 配置让 Maven 自动安装 requests 及其依赖
  - 移除手动 pip 安装依赖，改为 Maven 构建时自动安装
  - 添加注释说明 python-lsp-server 仍需 setup-graalpy-packages.sh

- README.md: 更新本地构建文档
  - Maven 现在自动安装 requests 核心包
  - setup-graalpy-packages.sh 变为可选（仅 Playground 代码提示需要）

- PyContextPool.java: 更新注释和错误消息
  - 说明 pip 包来源变化
  - 更新 requests 不可用时的提示信息
---
 README.md                                     | 48 +++++++++++++++++--
 parser/pom.xml                                | 22 +++++++--
 .../qaiu/parser/custompy/PyContextPool.java   | 10 ++--
 3 files changed, 65 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index a76dea6..2bf8bab 100644
--- a/README.md
+++ b/README.md
@@ -318,13 +318,51 @@ json返回数据格式示例:
 
 ## 开发和打包
 
-```shell
-# 环境要求: Jdk17 + maven;
-mvn clean
-mvn package -DskipTests
+### 环境要求
+- JDK 17+
+- Maven 3.x
+- Python 3.x（可选，仅当需要 Playground 代码智能提示功能时）
 
+### 本地构建步骤
+
+#### 1. Maven 打包
+
+```shell
+# 清理并打包（跳过测试）
+mvn clean package -DskipTests
+
+# 如果遇到代理问题，可以禁用代理
+mvn clean package -DskipTests -Dhttp.proxyHost= -Dhttps.proxyHost=
 ```
-打包好的文件位于 web-service/target/netdisk-fast-download-bin.zip
+
+> **说明：** 
+> - Maven 构建时会自动安装 **requests** 等核心 Python 包（由 graalpy-maven-plugin 处理）
+> - 打包好的文件位于 `web-service/target/netdisk-fast-download-bin.zip`
+
+#### 2. （可选）安装 Python LSP 服务器
+
+如果需要使用 **Playground 代码智能提示功能**，需要额外安装 python-lsp-server：
+
+```shell
+# 进入 parser 目录
+cd parser
+
+# 运行 pip 包安装脚本
+chmod +x setup-graalpy-packages.sh
+./setup-graalpy-packages.sh
+
+# 返回项目根目录
+cd ..
+```
+
+该脚本会将以下包安装到 `parser/src/main/resources/graalpy-packages/`：
+- **python-lsp-server** 及其依赖（jedi, python-lsp-jsonrpc, pluggy）- Python LSP 服务器（代码智能提示）
+- **pylsp 可选功能**（pyflakes, pycodestyle, autopep8, rope, yapf）- 代码检查和格式化
+
+> **注意：** 
+> - 这些包需要用系统 pip 安装，因为 python-lsp-server 依赖 ujson（需编译 C 扩展）
+> - 安装后的包会被打包进 jar 文件，不会被 `mvn clean` 清理
+> - 如果不需要 Playground 的代码智能提示功能，可以跳过此步骤
 
 ## 🚀 快速部署
 
diff --git a/parser/pom.xml b/parser/pom.xml
index 553bc47..ca4a261 100644
--- a/parser/pom.xml
+++ b/parser/pom.xml
@@ -152,16 +152,28 @@
     <build>
         <plugins>
 
-            <!-- GraalPy Maven Plugin - 仅创建 Python Home，不使用 pip 安装 -->
-            <!-- pip 包手动安装到 src/main/resources/graalpy-packages/，可打包进 jar -->
-            <!-- 安装方法: ./setup-graalpy-packages.sh -->
+            <!-- GraalPy Maven Plugin - 创建 Python Home 和 venv，自动安装 pip 包 -->
+            <!--
+                注意: python-lsp-server 依赖 ujson（需编译 C 扩展），GraalPy pip 无法安装。
+                如需 python-lsp-server 功能，请运行 setup-graalpy-packages.sh 使用系统 pip 安装。
+                
+                此处只配置 requests 及其纯 Python 依赖，Maven 构建时会自动安装到 
+                target/classes/org.graalvm.python.vfs/venv/lib/python3.11/site-packages/
+            -->
             <plugin>
                 <groupId>org.graalvm.python</groupId>
                 <artifactId>graalpy-maven-plugin</artifactId>
                 <version>${graalpy.version}</version>
                 <configuration>
-                    <!-- 不声明 packages，避免代理问题 -->
-                    <!-- pip 包从 resources/graalpy-packages 加载 -->
+                    <!-- pip 包列表 - 仅纯 Python 包 -->
+                    <packages>
+                        <!-- requests 及其依赖 - HTTP 客户端 (解析器核心功能必需) -->
+                        <package>requests</package>
+                        <package>urllib3</package>
+                        <package>charset_normalizer</package>
+                        <package>idna</package>
+                        <package>certifi</package>
+                    </packages>
                 </configuration>
                 <executions>
                     <execution>
diff --git a/parser/src/main/java/cn/qaiu/parser/custompy/PyContextPool.java b/parser/src/main/java/cn/qaiu/parser/custompy/PyContextPool.java
index c77fb3d..3cf6577 100644
--- a/parser/src/main/java/cn/qaiu/parser/custompy/PyContextPool.java
+++ b/parser/src/main/java/cn/qaiu/parser/custompy/PyContextPool.java
@@ -448,13 +448,13 @@ public class PyContextPool {
      * 配置 Python 路径，确保能够加载 pip 包
      * 使用路径缓存机制，避免重复检测文件系统
      * 
-     * pip 包安装在 src/main/resources/graalpy-packages/ 中，会打包进 jar。
-     * 运行时从 classpath 或文件系统加载。
+     * pip 包安装来源：
+     * 1. Maven 构建时 graalpy-maven-plugin 自动安装 requests 等核心包到
+     *    target/classes/org.graalvm.python.vfs/venv/lib/python3.11/site-packages/
+     * 2. 可选：运行 parser/setup-graalpy-packages.sh 安装 python-lsp-server（Playground 代码提示）
      * 
      * 注意：GraalPy 的 NativeModules 限制 - 只有进程中的第一个 Context 可以使用原生模块。
      * 后续 Context 会回退到 LLVM 模式，这可能导致某些依赖原生模块的库无法正常工作。
-     * 
-     * 安装方法：运行 parser/setup-graalpy-packages.sh
      */
     private void setupPythonPath(Context context) {
         try {
@@ -541,7 +541,7 @@ public class PyContextPool {
             } else {
                 String error = bindings.getMember("_error_msg").asString();
                 log.warn("Python 环境配置: requests 不可用 ({}), sys.path长度: {}. " +
-                        "请运行: ./setup-graalpy-packages.sh", error, pathLength);
+                        "检查 Maven 构建是否正常完成 (graalpy-maven-plugin)", error, pathLength);
             }
             
         } catch (Exception e) {