CNWei/task_pilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 本地 uv 与托管 Python 环境管理

Browse Source 
- 新增 uv 管理：只认程序目录副本或指定路径，支持从科大镜像下载并按 sha256 校验

- uv 环境变量（UV_*）可配置，默认相对程序目录（python / uv-cache），同时注入 uv 调用与任务进程

- 新增托管虚拟环境与 Python 版本管理：用 uv 下载解释器、预创建环境、查看已装包

- 新建任务保存时自动创建 .venv，运行期只校验、不再自动装依赖；镜像只在装包时使用

- 前端改为顶部品牌栏 + 三栏工作台，uv / 镜像源 / 虚拟环境各自独立弹窗

- 发布包构建后去掉工作区继承的低完整性标签

- 修复调度集成测试并发时误取 skipped 运行的问题
This commit is contained in:
CNWei
2026-11-07 16:57:27 +08:00
parent 2aa2a1ac18
commit 1914d38451
36 changed files with 5168 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+66 -20
View File
@@ -50,6 +50,8 @@ TaskPilot 是一个面向 **Windows 单机** 的本地定时任务管理平台
release/TaskPilot/
├── task-pilot-backend.exe # 单可执行文件（内嵌 Web 资源托管）
├── web/ # 前端静态资源（字体可选）
├── uv/ # 程序下载/自备的 uv.exe 放这里（Python 环境页可切换来源）
├── python/ # uv 下载的 Python 解释器（UV_PYTHON_INSTALL_DIR 默认指这里）
├── data/task_pilot.db # SQLite 数据库（首次启动创建）
├── logs/{task_id}/{run_id}.log
├── start.ps1
@@ -64,7 +66,7 @@ npm --prefix ..\stash-ui install
npm --prefix ..\stash-ui run build
pnpm --dir frontend install
cargo run --manifest-path backend/Cargo.toml # 终端一：API，127.0.0.1:3000
cargo run --manifest-path backend/Cargo.toml --bin task-pilot-backend # 终端一：API，127.0.0.1:3000
pnpm --dir frontend dev # 终端二：http://127.0.0.1:5173
```
@@ -117,8 +119,8 @@ uv run --no-project tools/verify.py --base-url http://127.0.0.1:3000
| 进程治理 | Windows Job Object 管理进程树；超时或取消时终止整棵树 |
| 观测 | 运行历史（状态/触发方式筛选）、退出码、耗时、错误信息、日志下载 |
| 日志 | SSE 实时推送 + 增量轮询 + 断线重连；编码自动识别；敏感值脱敏；容量与保留期清理 |
| Python | 自动关联 `.venv`/`venv`/`env`、解释器可选、用 uv 从 `pyproject.toml` / `requirements*.txt` 创建环境、注入 PATH/`VIRTUAL_ENV`/`PYTHONIOENCODING`、默认 PyPI 镜像注入 |
| 界面 | 左侧导航（任务调度 / Python 镜像）、任务类型 + 脚本语言联动表单、Cron 预览、虚拟环境状态条、页面内目录浏览器、深色日志弹窗 |
| Python | 自动关联 `.venv`/`venv`/`env`、解释器可选、用 uv 从 `pyproject.toml` / `requirements*.txt` 创建环境（新任务保存时自动创建）、uv 只用程序目录副本或自定义路径（不读系统 PATH）、没有 uv 时可从科大镜像一键下载、`UV_*` 环境变量可配置、注入 PATH/`VIRTUAL_ENV`/`PYTHONIOENCODING`、默认 PyPI 镜像注入 |
| 界面 | 顶部品牌栏 + 三栏工作台（用户/概览/调度 · 任务分组 · uv/镜像/环境卡片）、任务类型 + 脚本语言联动表单、Cron 预览、虚拟环境状态条、页面内目录浏览器、深色日志弹窗 |
| 安全 | 仅回环监听、Origin 白名单、写操作令牌、常量时间比较、请求体上限 |
| 交付 | 单进程静态托管、SPA 回退、Release 打包、OpenAPI 契约、可选离线字体 |
@@ -220,14 +222,22 @@ queued ──► running ──► succeeded / failed / timed_out / cancelled
**没有虚拟环境时**：
- 工作目录根部有 `pyproject.toml` 或 `requirements*.txt`，且 PATH 中能找到 `uv`：
编辑器会显示「用 uv 创建环境」按钮，点击后
`pyproject.toml` 走 `uv sync`，仅 requirements 走 `uv venv .venv` + `uv pip install -r`。
已有 `.venv`/`venv`/`env` 会优先复用，不会重复创建。创建时会使用当前默认 PyPI 镜像
（`PIP_INDEX_URL` / `UV_DEFAULT_INDEX`），不会绕过镜像设置。
- 没装 uv：必须手动准备虚拟环境；Python 任务缺少 `.venv` 时运行失败并给出提示。
- 既没有虚拟环境、也没有 pyproject/requirements：编辑器显示错误，Python 任务运行失败。
Python 任务不再静默回退到系统解释器。
- 先看用户自己的环境：任务里指定的 `venv`、解释器路径、工作目录向上查找，命中就直接用，不重复创建。
- 都没有时，**新建任务时会用 uv 自动创建 `.venv`**：`pyproject.toml` 走 `uv sync`，
仅有 `requirements*.txt` 走 `uv venv .venv` + `uv pip install -r`，纯标准库脚本（没有依赖文件）建一个空环境。
保存按钮会显示「正在创建虚拟环境…」，环境问题当场暴露。手动路径是编辑器里的「用 uv 创建环境」按钮。
- 运行期只做校验、不再自动装依赖：没有 `.venv` 的 Python 任务会直接失败并提示先创建环境。
- 创建时会使用当前默认 PyPI 镜像（`PIP_INDEX_URL` / `UV_DEFAULT_INDEX`），不会绕过镜像设置。
- uv 只用平台认的两份：程序目录下的 `uv\uv.exe`（「程序目录 uv」，默认），或你指定的 `uv.exe`（「指定路径」）。
**不读系统 PATH**——PATH 上的 uv 版本会随启动方式变化，不适合当调度器的隐式依赖。
没有 uv 时点「Python 环境」页的「下载 uv」，从科大镜像
`mirrors.ustc.edu.cn/github-release/astral-sh/uv/LatestRelease` 下载当前架构的压缩包，
校验 sha256 后解压到 `uv\uv.exe` 并自动切换过去；本机已经装了 uv 的话，把它填进「指定路径」即可。
- 「Python 环境」页还能配置 `UV_*` 环境变量（如 `UV_CACHE_DIR`、`UV_PYTHON_INSTALL_DIR`），
会注入到每一次 uv 调用，并优先于镜像注入与进程环境。
- uv 不可用：保存任务时不会自动建环境，运行时会失败并提示先去「Python 环境」配置。
- 运行任务时会把平台 uv 目录加到 PATH 前面，并注入 `UV_PYTHON_INSTALL_DIR`、页面里配置的 `UV_*` 和默认 `UV_DEFAULT_INDEX`
（任务自己配置的环境变量优先）。这样脚本里直接写 `uv ...` 用的也是平台这一份，装包默认走镜像；不会再注入 `PIP_*`。
- 解释器由语言自动决定，界面不再显示解释器输入框：
Python 始终使用虚拟环境里的 Python，Shell 使用 `cmd.exe`，Node 使用 `node.exe`，Lua 使用 `lua.exe`。
自定义解释器仍可通过 API 的 `action.interpreter` 字段传入。
@@ -248,7 +258,10 @@ queued ──► running ──► succeeded / failed / timed_out / cancelled
## Web 界面
- **左侧导航**：任务调度 / Python 镜像两个入口；底部显示 Rust 引擎在线状态与版本。
- **顶部品牌栏**：品牌 + 右侧 Rust 引擎在线状态与版本；页面级导航已去掉，配置都收到任务调度页的卡片里。
- **三栏工作台**（任务调度页）：左栏用户卡片 + 概览指标 + 调度摘要；中栏搜索筛选 + 按类型（脚本 / HTTP / 二进制）分组的任务卡片与分页；
右栏 uv（版本只显示版本号 / 缓存目录 / Python 目录）、镜像源、托管虚拟环境摘要——点「配置 / 管理」打开对应**弹窗**
（uv 与镜像源分属两个弹窗，不放在一起）。
- **指标卡**：已托管任务、运行中任务、可用脚本、引擎在线状态。
- **任务表**：名称/ID + 类型标签、时区、调度周期（Cron + **下次触发时间**）、状态、超时、操作。
- **编辑器**：先选任务类型（脚本 / HTTP / 二进制），脚本类型再选语言（Python / Shell / Node / Lua），
@@ -257,9 +270,21 @@ queued ──► running ──► succeeded / failed / timed_out / cancelled
缺少虚拟环境但项目有依赖文件时可直接用 uv 创建。解释器由语言自动选择，界面不再要求手填。
- **目录选择**：页面内目录浏览器（盘符 → 逐级进入 → 使用此目录），同时保留手动输入。
- **日志弹窗**：运行历史筛选、SSE 实时日志、取消运行、下载日志、Escape/焦点陷阱。
- **Python 镜像**：内置清华 TUNA / 阿里云 / 中科大 / PyPI 官方；可新增、编辑、启用停用、设为默认。
默认镜像在 Python 脚本任务启动时注入 `PIP_INDEX_URL` / `UV_INDEX_URL`
（任务自身配置的环境变量优先），不会自动安装依赖。
- **Python 环境**：两块配置。
- uv 可执行文件：显示当前使用的 uv 与版本、候选来源探测结果；可切「程序目录 uv（`uv\uv.exe`）」
或「指定路径」；本机已装 uv 就把它的路径填进「指定路径」；本机没有就点「下载 uv」，
从科大镜像下载并自动切换。保存自定义路径时会先运行 `uv --version` 校验。
- uv 环境变量：键值列表，只接受 `UV_` 前缀（如 `UV_CACHE_DIR`、`UV_PYTHON_INSTALL_DIR`、
`UV_HTTP_TIMEOUT`），会注入到每一次 uv 调用，并优先于镜像注入与进程环境。
`UV_PYTHON_INSTALL_DIR` 未配置时默认指向程序目录下的 `python\`。
- 包索引镜像：内置清华 TUNA / 阿里云 / 中科大 / PyPI 官方；可新增、编辑、启用停用、设为默认。
只在**装包**（建环境 / 预装依赖）时生效，任务运行时不再注入镜像变量。
- **虚拟环境**：管理 uv 提供的 Python 版本和预创建的托管环境。
- Python 版本：列出 uv 下载到程序目录 `python\` 的解释器（只算平台目录里的，不含系统 Python）；
填版本（如 `3.12`）点「下载 Python」即用 uv 下载，之后可在这里和新建环境下拉里选用。
- 托管虚拟环境：预创建常用环境（放在 `data\envs\<名称>`），Python 版本从已下载列表里选，
可选预装包；列表显示版本与绝对路径，「查看包」按需读取 `uv pip list` 的已安装包。
任务里把该路径填进「虚拟环境目录」即可复用。环境只在创建时装包，不会自动升级。
- **设计系统**：按钮、输入框、表格、标签、分页、弹窗、Toast、排版全部来自
`@stash/ui`（同级目录 `../stash-ui`，`file:` 依赖）；本仓库只保留页面级布局与
业务块（侧栏、任务表单元格、日志控制台、表单栅格）。
@@ -330,6 +355,25 @@ queued ──► running ──► succeeded / failed / timed_out / cancelled
| `DELETE` | `/api/v1/python/mirrors/{id}` | 删除镜像 |
| `POST` | `/api/v1/python/mirrors/{id}/default` | 设为默认（同一时间仅一个默认，并自动启用） |
### uv
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/uv` | 当前 uv 来源、可执行文件、版本、`UV_*` 环境变量，以及各来源的探测结果 |
| `PUT` | `/api/v1/uv` | 保存 uv 来源（`managed` / `custom`）、自定义路径和 `extra_env`；`custom` 会校验可运行 |
| `POST` | `/api/v1/uv/download` | 从科大镜像下载当前架构的 uv、校验 sha256、安装到程序目录 `uv\` 并切换过去 |
### 托管虚拟环境
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/python/pythons` | uv 下载到程序目录 `python\` 的解释器（版本、路径） |
| `POST` | `/api/v1/python/pythons` | 用 uv 下载指定 Python 版本（`version`，如 `3.12`），返回最新列表 |
| `GET` | `/api/v1/python/envs` | 列出 `data/envs` 下的环境（名称、绝对路径、`pyvenv.cfg` 里的 Python 版本） |
| `POST` | `/api/v1/python/envs` | 用 uv 创建环境（`name`、可选 `python_version`、可选 `packages` 预装） |
| `GET` | `/api/v1/python/envs/{name}/packages` | 已安装的包（`uv pip list --format json`） |
| `DELETE` | `/api/v1/python/envs/{name}` | 删除整个环境目录 |
### 任务与运行
| 方法 | 路径 | 说明 |
@@ -475,7 +519,7 @@ React (Vite) ──fetch──► Axum router ──security::api_guard(Origin +
| 模块 | 职责 |
| --- | --- |
| `@stash/ui`（同级 `../stash-ui`） | 设计令牌与通用组件：按钮、输入、表格、标签、弹窗、分页、Toast、排版 |
| `components/AppSidebar.tsx` | 左侧导航、品牌、引擎状态 |
| `components/AppHeader.tsx` | 顶部导航、品牌、引擎状态 |
| `components/PageHeader.tsx` | 页面标题区（标题 / 说明 / 操作） |
| `pages/TaskDashboard.tsx` | 列表、筛选、分页、指标卡、下次触发时间 |
| `pages/PythonMirrorsPage.tsx` | Python 镜像列表、默认项、新增 / 编辑 / 删除 |
@@ -547,9 +591,9 @@ uv run --with fonttools --with brotli tools/build-fonts.py
| 层 | 覆盖 |
| --- | --- |
| Rust 单元（59） | Cron、虚拟环境解析与探测、项目依赖文件扫描、uv 可用性、执行器（编码/截断/清理/句柄归属/日志合并推送）、安全、目录列举 |
| Rust 集成（39） | 任务 CRUD 与校验、运行生命周期、取消与超时、日志分块、调度恢复、统计与调度接口、重启对账、镜像 CRUD、venv 探测/创建、Shell 脚本执行 |
| 前端 Vitest（31） | 仪表盘渲染、侧栏导航到镜像页、表单载荷与脚本语言、虚拟环境状态、uv 创建入口、目录浏览器、下次触发时间、日志行切分/窗口计算/虚拟滚动 |
| Rust 单元（73） | Cron、虚拟环境解析与探测、项目依赖文件扫描、uv 来源解析/校验/压缩包解压/`UV_*` 环境变量校验、托管环境名校验、PATH 注入去重、执行器（编码/截断/清理/句柄归属/日志合并推送）、安全、目录列举 |
| Rust 集成（48） | 任务 CRUD 与校验、运行生命周期、取消与超时、日志分块、调度恢复、统计与调度接口、重启对账、镜像 CRUD、uv 设置读写与下载鉴权、托管环境校验与 404、venv 探测/创建、无环境运行提示、Shell 脚本执行 |
| 前端 Vitest（37） | 仪表盘渲染、侧栏导航到 Python 环境页、保存 uv 来源与 `UV_*` 环境变量、镜像下载、Python 版本下载、托管环境创建与包列表、新建任务前先建虚拟环境、表单载荷与脚本语言、虚拟环境状态、uv 创建入口、目录浏览器、下次触发时间、日志行切分/窗口计算/虚拟滚动 |
| Playwright（8） | 真实任务执行与日志、编辑/停用/删除、脚本语言切换、目录切换单状态、窄屏、**无外部网络渲染**、1500 行日志的虚拟滚动、镜像增删与设默认 |
| Python 自检（14 项） | `tools/verify.py` 覆盖 API 全链路 |
@@ -578,7 +622,9 @@ uv run --with fonttools --with brotli tools/build-fonts.py
- HTTP Action 只校验状态码，不支持响应体断言、认证方案或 Header 断言。
- 敏感值脱敏基于变量名关键词与值替换，不是凭据保险箱。
- Conda 环境不会自动激活，需要显式填写解释器路径。
- 用 uv 创建环境是编辑器里的显式操作；运行中的任务不会在后台自动安装依赖。首次创建需要网络与可写的 uv 缓存目录。
- Python 任务缺少虚拟环境时，新建任务会先用 uv 创建（需要网络与可写的 uv 缓存目录）；运行期不会再自动装依赖。已有环境的项目不会被自动升级。
- 托管虚拟环境只负责创建 / 删除 / 查看已装包，不会自动升级依赖；任务运行也不会改动它。
- 「下载 uv」依赖 `mirrors.ustc.edu.cn` 可达；网络不通时请自己下载 uv 放到程序同级 `uv` 目录或指定路径。
- 本地单用户工具：读取接口免令牌，不支持远程部署与多用户。
- 未安装为 Windows 服务；关闭启动脚本后调度停止。
- 错过的调度不会补跑。