From 942f8de3b7a382b0fecd5824e0c45d0f6c8340ec Mon Sep 17 00:00:00 2001
From: CNWei <t6g888@163.com>
Date: Mon, 26 Oct 2026 00:04:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=20=E5=B9=B6?=
 =?UTF-8?q?=E5=8A=A0=E5=85=A5=20uv=20=E7=A4=BA=E4=BE=8B=E4=B8=8E=E7=AB=AF?=
 =?UTF-8?q?=E5=88=B0=E7=AB=AF=E8=87=AA=E6=A3=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README 重排为快速开始、执行语义、输入校验、API 参考与故障排查
- 新增 samples/python-task：uv 管理的演示任务
- 新增 tools/verify.py：14 项 API 全链路自检
---
 README.md                          | 678 ++++++++++++++++++-----------
 docs/RELEASE.md                    |  17 +-
 samples/python-task/main.py        |  60 +++
 samples/python-task/pyproject.toml |   6 +
 tools/verify.py                    | 266 +++++++++++
 5 files changed, 758 insertions(+), 269 deletions(-)
 create mode 100644 samples/python-task/main.py
 create mode 100644 samples/python-task/pyproject.toml
 create mode 100644 tools/verify.py

diff --git a/README.md b/README.md
index 03051bc..28acef1 100644
--- a/README.md
+++ b/README.md
@@ -1,216 +1,309 @@
 # TaskPilot
 
-TaskPilot 是一个面向 Windows 的本地定时任务管理平台。项目目标是用 React 提供任务管理界面，用 Rust 实现 Cron 调度、Windows 进程管理和运行日志。
+TaskPilot 是一个面向 **Windows 单机** 的本地定时任务管理平台：React 提供任务管理与观测界面，Rust 负责 Cron 调度、进程治理、运行日志与本地 API。
 
-当前已完成 Phase 1 至 Phase 6：React 任务管理界面、Rust API、SQLite 持久化、Cron 调度、三类任务执行器、实时日志、安全边界、生产静态托管和 Windows 本地打包均已落地。
+- 单用户、单实例，只监听 `127.0.0.1`
+- 三类任务：Python/Shell 脚本、HTTP 请求、二进制进程
+- SQLite 持久化，重启后任务与历史仍在
+- 运行日志实时推送（SSE），断线自动回退轮询
+- 前端零外部依赖：字体、样式、脚本全部随包自带，**断网可用**
 
-仓库根目录的 `task_pilot.html` 是最初的单文件视觉原型，目前只作为 React 迁移期间的设计参考，不是正式前端入口。
+> 根目录的 `task_pilot.html` 只是最初的单文件视觉原型，正式入口是 React 应用。
 
-React 页面沿用该原型作为视觉基线：1040px 主容器、紧凑指标卡、任务表格、660px 编辑弹窗、Cron 预览区和深色日志查看器均在保留真实功能的前提下复刻。
+---
 
-## 当前能力
+## 目录
 
-- React 页面可以检测 Rust 后端连接状态。
-- Vite 开发服务器将 `/api` 代理到 Axum 后端。
-- Rust 服务提供健康检查和 OpenAPI 文档。
-- OpenAPI 可以导出为稳定快照，并生成前端 TypeScript 类型。
-- Cron POC 支持 5/6 位表达式、秒级调度、别名、月份/星期名称和 POSIX 日/星期语义。
-- 任务可以持久化到 SQLite，并支持创建、查询、更新和删除。
-- 任务列表支持名称/ID 搜索、启用状态筛选、Action 类型筛选和分页。
-- 脚本、HTTP 和二进制进程任务具有独立的类型化载荷与后端校验。
-- 启用的脚本任务由 Tokio 调度循环自动执行，并支持启动后恢复调度。
-- 后端重启后，已启用任务仍可持久化并重新注册。
-- 支持手动立即运行，重复触发时记录为 `skipped`，不会并发执行同一任务。
-- 每次运行记录触发来源、状态、耗时、退出码和错误信息。
-- 已实现 Windows Job Object，超时或关闭时会终止目标进程树。
-- stdout 和 stderr 会写入独立运行日志，并可通过 API 增量读取。
-- HTTP Action 支持 GET/POST、Header、Body、超时和期望状态码。
-- 二进制进程 Action 使用 Job Object 执行，并支持工作目录、参数和环境变量。
-- 运行中任务可以通过 API 或前端日志抽屉取消。
-- `/api/v1/events` 使用 SSE 推送运行状态和日志增量，前端断线时自动回退到轮询。
-- 运行历史支持按状态和触发方式筛选，并支持下载完整日志。
-- 敏感环境变量和敏感 Header 的值不会写入系统日志，输出中的匹配值会替换为 `[REDACTED]`。
-- Python 脚本支持显式虚拟环境配置，并会自动向上探测 `.venv`、`venv`、`env`。
-- 编辑器会随工作目录实时探测虚拟环境，显示 `已关联虚拟环境: .venv\Scripts\python.exe` 并同步更新调用预览。
-- 工作目录支持「选择文件夹…」打开页面内的目录浏览器（盘符 → 逐级进入 → 使用此目录），选中后回填输入框，同时保留手动输入。
-- 执行前会校验 `pyvenv.cfg` 和 `Scripts/python.exe`，优先使用虚拟环境解释器，并注入 PATH、`VIRTUAL_ENV` 和无缓冲输出设置。
-- 日志按系统 ANSI 代码页（如 GBK）解码非 UTF-8 输出，中文程序不再显示为 `����`，且长日志跨 64 KiB 分块读取不会丢失字符。
-- 日志支持保留期限和总容量清理，单次日志仍有 5 MiB 上限。
-- React 页面已接入真实任务列表、搜索筛选、分页、CRUD、启停、手动运行、运行历史和日志轮询。
-- 三类 Action 使用不同动态表单，并以类型化载荷提交，不再固定为脚本任务。
-- Playwright 已覆盖运行日志、编辑、停用、删除和窄屏布局主流程。
-- 后端只监听 `127.0.0.1`，拒绝非本地 Origin。
-- 浏览器写操作需要运行期随机管理令牌，进程重启后自动更换。
-- Axum 在生产模式托管 React 静态资源，并支持 SPA 路由回退。
-- 弹窗和日志抽屉支持初始焦点、Tab 循环、Escape 关闭和焦点恢复。
-- 提供 Windows Release 打包和一键启动脚本。
-- 前端与后端均具备基础测试和统一质量检查命令。
+- [快速开始](#快速开始)
+- [功能总览](#功能总览)
+- [任务模型](#任务模型)
+- [调度与执行语义](#调度与执行语义)
+- [日志与编码](#日志与编码)
+- [Python 与虚拟环境](#python-与虚拟环境)
+- [Web 界面](#web-界面)
+- [安全模型](#安全模型)
+- [配置项](#配置项)
+- [API 参考](#api-参考)
+- [输入校验](#输入校验)
+- [数据与文件布局](#数据与文件布局)
+- [架构与模块](#架构与模块)
+- [开发与测试](#开发与测试)
+- [故障排查](#故障排查)
+- [已知限制](#已知限制)
+- [架构决策记录](#架构决策记录)
 
-## 技术栈
+---
 
-### 前端
+## 快速开始
 
-- React 19
-- TypeScript 5.9
-- Vite 8
-- React Router
-- TanStack Query
-- React Hook Form
-- Zod
-- Vitest + Testing Library
-- Playwright
-
-### 后端
-
-- Rust 1.95.0 MSVC
-- Axum
-- Tokio
-- Serde
-- Utoipa / OpenAPI
-- Croner
-- SQLx / SQLite
-- Tower HTTP
-
-### 工具链
-
-- Volta 2.0.2
-- Node.js 24.12.0
-- pnpm 11.20.0
-
-Node.js 和 pnpm 版本固定在 `frontend/package.json` 的 `volta` 字段中，Rust 版本固定在根目录的 `rust-toolchain.toml` 中。
-
-## 环境要求
-
-- Windows 10/11
-- Volta
-- Rustup
-- Visual Studio C++ Build Tools，供 Rust MSVC 工具链使用
-
-首次使用 Volta 时会自动切换到项目固定版本：
+### 方式一：打包版（推荐）
 
 ```powershell
-volta --version
-node --version
-pnpm --version
-rustc --version
+.\scripts\build-release.ps1     # 构建前端 + Release 可执行文件 + 可分发目录
+.\release\TaskPilot\start.ps1   # 启动并访问 http://127.0.0.1:3000
 ```
 
-## 本地开发
+`start.ps1 -OpenBrowser` 会自动打开浏览器。产物目录结构：
 
-首次拉取项目后安装前端依赖：
+```text
+release/TaskPilot/
+├── task-pilot-backend.exe   # 单可执行文件（内嵌 Web 资源托管）
+├── web/                     # 前端静态资源（含本地字体）
+├── data/task_pilot.db       # SQLite 数据库（首次启动创建）
+├── logs/{task_id}/{run_id}.log
+├── start.ps1
+└── README.md                # 即 docs/RELEASE.md
+```
+
+### 方式二：本地开发
 
 ```powershell
 pnpm --dir frontend install
+cargo run --manifest-path backend/Cargo.toml     # 终端一：API，127.0.0.1:3000
+pnpm --dir frontend dev                          # 终端二：http://127.0.0.1:5173
 ```
 
-终端一，启动 Rust API：
+Vite 把 `/api` 代理到后端。改后端端口时（`TASK_PILOT_PORT`）需同步修改
+`frontend/vite.config.ts` 的代理目标；打包版同源，不需要改前端。
+
+### 方式三：用 uv 跑官方示例与自检
+
+仓库自带一个 uv 管理的演示任务和一个端到端自检脚本：
 
 ```powershell
+# 1) 在示例目录创建虚拟环境（Python 3.11）
+cd samples\python-task
+uv venv
+cd ..\..
+
+# 2) 启动一个临时后端（任意终端）
 cargo run --manifest-path backend/Cargo.toml
+
+# 3) 运行 14 项端到端自检
+uv run --no-project tools/verify.py --base-url http://127.0.0.1:3000
 ```
 
-终端二，启动 React 前端：
+自检会真实创建任务、立即运行、读回日志，校验：健康检查、令牌、目录列举、
+虚拟环境探测、创建/调度注册、运行成功、中文日志、`VIRTUAL_ENV` 注入、
+无替换字符、统计口径、删除任务。
 
-```powershell
-pnpm --dir frontend dev
+```text
+[OK  ] venv probe links the demo environment  status=linked path=.venv\Scripts\python.exe
+[OK  ] task is registered in the schedule  next_run_at=2026-10-25T19:00:00Z
+[OK  ] run succeeded  status=succeeded exit=0
+[OK  ] log contains Chinese output
+14/14 checks passed
 ```
 
-访问 <http://127.0.0.1:5173>。Rust 服务默认监听 `127.0.0.1:3000`，可通过 `TASK_PILOT_PORT` 修改端口：
+`--keep` 保留任务，`--working-dir` 可换成任意含 `.venv` 的目录。
 
-```powershell
-$env:TASK_PILOT_PORT = "3100"
-cargo run --manifest-path backend/Cargo.toml
+---
+
+## 功能总览
+
+| 分组 | 能力 |
+| --- | --- |
+| 任务管理 | 增删改查、启用/停用、按 ID/名称搜索、按启用状态与 Action 类型筛选、分页 |
+| 调度 | 5/6 位 Cron（支持秒级、别名、月份/星期名）、IANA 时区、启动恢复调度、下次触发时间 |
+| 执行 | 手动立即运行；同一任务重叠触发记为 `skipped`；启动时对账遗留运行 |
+| 进程治理 | Windows Job Object 管理进程树；超时或取消时终止整棵树 |
+| 观测 | 运行历史（状态/触发方式筛选）、退出码、耗时、错误信息、日志下载 |
+| 日志 | SSE 实时推送 + 增量轮询 + 断线重连；编码自动识别；敏感值脱敏；容量与保留期清理 |
+| Python | 自动关联 `.venv`/`venv`/`env`、注入 PATH/`VIRTUAL_ENV`/`PYTHONIOENCODING`、虚拟环境校验 |
+| 界面 | 三类动态表单、Cron 预览、虚拟环境状态条、页面内目录浏览器、深色日志抽屉 |
+| 安全 | 仅回环监听、Origin 白名单、写操作令牌、常量时间比较、请求体上限 |
+| 交付 | 单进程静态托管、SPA 回退、Release 打包、离线字体、OpenAPI 契约 |
+
+---
+
+## 任务模型
+
+### 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 稳定标识，`[A-Za-z0-9_-]`，1–64 字符；同时决定日志目录名 |
+| `name` | 展示名，1–120 字符 |
+| `cron` | 5 或 6 位表达式，例：`0 0 2 * * *`、`*/30 * * * * *`、`@daily` |
+| `timezone` | IANA 时区，例：`Asia/Shanghai` |
+| `enabled` | 是否注册调度 |
+| `timeout_secs` | 1–86400；超时终止整个进程树 |
+| `concurrency_policy` | 目前仅 `skip`（同任务重叠触发被跳过） |
+| `retry_policy` | `max_attempts` ≤ 10、`delay_secs` ≤ 3600；**当前只持久化，不自动重试** |
+| `action` | 见下 |
+
+### 三类 Action
+
+```jsonc
+// 脚本
+{ "type": "script", "working_dir": "D:\\Projects\\sync", "venv": null,
+  "interpreter": "python.exe", "script": "main.py",
+  "args": ["--mode", "full"], "env": { "PYTHONUNBUFFERED": "1" } }
+
+// HTTP
+{ "type": "http", "url": "https://api.example.com/health", "method": "GET",
+  "headers": { "X-Token": "..." }, "body": null, "expected_status": [200, 204] }
+
+// 进程
+{ "type": "process", "executable": "C:\\Tools\\agent.exe",
+  "working_dir": "C:\\Tools", "args": ["--serve"], "env": {} }
 ```
 
-修改后端端口后，还需要同步调整 `frontend/vite.config.ts` 中的代理目标。
+### 运行状态机
 
-## Windows Release
-
-构建前端生产资源、Rust Release 可执行文件和可分发目录：
-
-```powershell
-.\scripts\build-release.ps1
+```text
+queued ──► running ──► succeeded / failed / timed_out / cancelled
+   └────────────────► skipped        （同一任务已有运行实例）
 ```
 
-产物位于 `release/TaskPilot/`。启动打包版本：
+终态不可再取消；进程被强杀后，下次启动会把遗留的 `queued`/`running`
+统一标记为 `cancelled`，并写入「TaskPilot 进程重启，运行被中断」。
 
-```powershell
-.\release\TaskPilot\start.ps1
-```
+---
 
-访问 <http://127.0.0.1:3000>。打包使用同源 API，因此 Release 模式修改 `TASK_PILOT_PORT` 后无需重新构建前端。
+## 调度与执行语义
 
-打包目录中的 [RELEASE.md](docs/RELEASE.md) 会作为使用与故障排查说明一并复制。
+- **三类任务都参与调度**。启用即注册，停用即取消；后端重启后从数据库恢复注册。
+- 每个任务一个独立 Tokio 循环：计算下次触发 → 等待 → 调用执行器。
+- **重叠触发**：同一任务已有运行实例时，新触发记为 `skipped`，不会并发。
+- **没有全局并发上限**：10 个任务同时到点会各自启动一个进程。
+- **取消**：通过 `CancellationToken` + `TerminateJobObject`，5 秒内未退出则 `kill`。
+- **超时**：与取消同一路径，状态记为 `timed_out`。
+- **取消后立即重跑**：允许；旧进程终止与新进程启动可能短暂重叠。
+- **错过的触发不补跑**：下次触发始终从"现在"开始计算。
+- **下次触发时间**：调度器保存在内存中，`GET /api/v1/schedule` 暴露给前端。
+- **重试**：字段已持久化但执行器尚未实现自动重试（见「已知限制」）。
 
-SQLite 数据库默认创建在启动目录的 `data/task_pilot.db`。通过以下环境变量可以使用其他数据库路径：
+---
 
-```powershell
-$env:TASK_PILOT_DATABASE_URL = "sqlite://data/custom.db"
-cargo run --manifest-path backend/Cargo.toml
-```
+## 日志与编码
 
-数据库迁移会在后端启动时自动执行。
+文件布局：`logs/{task_id}/{run_id}.log`（UTF-8 写入）
 
-运行日志默认写入 `logs/{task_id}/{run_id}.log`，可通过以下环境变量配置：
+- 每次运行 **5 MiB** 上限，超出后丢弃后续输出并写一条 `[system]` 说明。
+- **单行 256 KiB** 上限：超出部分丢弃、继续读到行尾，避免内存无界增长。
+- 保留期（默认 30 天）与总容量（默认 512 MiB）清理；**跳过正在写入的日志**。
+- 读取按 64 KiB 分块且对齐 UTF-8 边界；`complete` 只在"运行结束且读到文件末尾"时为真。
+- **输出编码**：默认 `auto` = 逐行先按 UTF-8 解码，失败回退到系统 ANSI 代码页（简体中文为 GBK）。
+  可用 `TASK_PILOT_LOG_ENCODING=gbk|utf-8|windows-1251` 强制。
+- **脱敏**：环境变量/Header 名包含 `SECRET`、`TOKEN`、`PASSWORD`、`PASS`、`API_KEY`、
+  `PRIVATE_KEY`、`CREDENTIAL`、`AUTHORIZATION`、`AUTH` 时，其值在日志中被替换为 `[REDACTED]`。
 
-```powershell
-$env:TASK_PILOT_LOG_DIR = "logs"
-$env:TASK_PILOT_LOG_RETENTION_DAYS = "30"
-$env:TASK_PILOT_LOG_MAX_TOTAL_MB = "512"
-$env:TASK_PILOT_LOG_ENCODING = "auto"
-```
+---
 
-`TASK_PILOT_LOG_ENCODING` 默认为 `auto`：逐行先按 UTF-8 解码，失败时回退到系统 ANSI 代码页（简体中文为 GBK），保证中文程序输出不会变成 `����`。需要强制某一种编码时可填写 `gbk`、`utf-8`、`windows-1251` 等标签。
+## Python 与虚拟环境
 
-单次运行日志达到 5 MiB 后会停止记录后续输出。程序启动和每次运行结束时会清理过期日志，并在总容量超限时优先删除最旧日志。
+解析顺序（执行期与编辑器探测共用同一份逻辑）：
 
-## API
+1. 手动指定的 `action.venv`
+2. 从解释器路径推断（`...\.venv\Scripts\python.exe`）
+3. 从工作目录向上查找 `.venv`、`venv`、`env`
 
-| 方法 | 路径 | 用途 |
+虚拟环境必须同时存在 `pyvenv.cfg` 与 `Scripts\python.exe`，否则显式配置在保存时被拒绝。
+
+命中虚拟环境后注入：
+
+| 变量 | 行为 |
+| --- | --- |
+| `PATH` | 虚拟环境 `Scripts` 目录置前，保留用户 PATH，按大小写不敏感去重 |
+| `VIRTUAL_ENV` / `VIRTUAL_ENV_PROMPT` | 指向虚拟环境根目录 |
+| `PYTHONUNBUFFERED` | 强制 `1`（实时日志依赖） |
+| `PYTHONIOENCODING` | 默认 `utf-8`，用户显式设置优先；避免 GBK 控制台下打印 emoji/生僻字符直接崩溃 |
+| `PYTHONHOME` / `PYTHONPATH` | 虚拟环境模式下清理继承的污染值 |
+
+编辑器会实时显示 `● 已关联虚拟环境: .venv\Scripts\python.exe`，并同步更新调用预览。
+
+---
+
+## Web 界面
+
+- **指标卡**：已托管任务、运行中任务、可用脚本、引擎在线状态。
+- **任务表**：名称/ID、调度周期（含时区与**下次触发时间**）、类型、状态、超时、操作。
+- **编辑器**：三类动态表单、Cron 预览（实时计算未来 5/10 次）、虚拟环境状态条、调用预览。
+- **目录选择**：页面内目录浏览器（盘符 → 逐级进入 → 使用此目录），同时保留手动输入。
+- **日志抽屉**：运行历史筛选、SSE 实时日志、取消运行、下载日志、Escape/焦点陷阱。
+- **视觉**：对齐 Alright 主题（`#3858f6` 主色、灰阶体系、0.3s 缓动），字体 `LXGW WenKai` +
+  `Outfit-Medium` 全部本地托管，断网仍可完整渲染。
+
+---
+
+## 安全模型
+
+| 边界 | 实现 |
+| --- | --- |
+| 监听地址 | 固定 `127.0.0.1`（`TASK_PILOT_PORT` 只改端口） |
+| Origin | 带 `Origin` 的请求必须是 `http://127.0.0.1:*` 或 `http://localhost:*`，否则 403 |
+| 管理令牌 | 非 GET/HEAD/OPTIONS 必须带 `X-TaskPilot-Token`；进程启动时随机生成，重启轮换 |
+| 比较方式 | 常量时间比较，避免时序侧信道 |
+| 请求体 | 上限 2 MiB |
+| 命令执行 | 参数以 argv 传递，不经过 Shell 拼接 |
+| 读取接口 | 只读接口（任务列表、日志、目录列举、统计）免令牌 |
+| 前端令牌 | 客户端缓存令牌；写请求 403 时丢弃缓存并重试一次 |
+
+> 这是**本地单用户工具**的威胁模型：本机其他进程仍可调用只读接口。不要把端口暴露到局域网。
+
+---
+
+## 配置项
+
+| 变量 | 默认值 | 说明 |
 | --- | --- | --- |
-| `GET` | `/api/v1/health` | 后端健康检查 |
-| `GET` | `/api/v1/session` | 获取当前进程的本地管理令牌 |
+| `TASK_PILOT_PORT` | `3000` | 监听端口（地址固定回环） |
+| `TASK_PILOT_DATABASE_URL` | `sqlite://data/task_pilot.db` | SQLite 路径；`sqlite::memory:` 用于测试 |
+| `TASK_PILOT_LOG_DIR` | `logs` | 运行日志根目录 |
+| `TASK_PILOT_STATIC_DIR` | `frontend/dist` | 生产静态资源目录（打包版由 `start.ps1` 设为 `web`） |
+| `TASK_PILOT_LOG_RETENTION_DAYS` | `30` | 日志保留天数 |
+| `TASK_PILOT_LOG_MAX_TOTAL_MB` | `512` | 日志总容量上限 |
+| `TASK_PILOT_LOG_ENCODING` | `auto` | 子进程输出编码；`auto` 为 UTF-8→系统代码页回退 |
+| `RUST_LOG` | `task_pilot_backend=debug,tower_http=debug` | 日志级别 |
+
+数据库连接：SQLite 开启 `foreign_keys`、**WAL**、`busy_timeout=5s`、`synchronous=NORMAL`，最多 5 个连接。
+
+---
+
+## API 参考
+
+### 系统
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/api/v1/health` | 健康检查 |
+| `GET` | `/api/v1/session` | 获取当前进程的管理令牌 |
 | `GET` | `/api/v1/openapi.json` | 运行时 OpenAPI 文档 |
-| `POST` | `/api/v1/python/venv` | 探测工作目录会关联的 Python 虚拟环境 |
-| `GET` | `/api/v1/system/directories` | 列出盘符或指定目录下的子文件夹 |
-| `GET` | `/api/v1/tasks` | 查询任务列表 |
+| `POST` | `/api/v1/cron/preview` | 计算未来若干次触发时间 |
+| `POST` | `/api/v1/python/venv` | 探测工作目录会关联的虚拟环境 |
+| `GET` | `/api/v1/system/directories?path=` | 列盘符或子文件夹（目录浏览器） |
+| `GET` | `/api/v1/stats` | 仪表盘计数（总数/启用/运行中/三类数量） |
+| `GET` | `/api/v1/schedule` | 已启用任务的下次触发时间 |
+
+### 任务与运行
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/api/v1/tasks` | 任务列表（`q`、`enabled`、`action_type`、`page`、`page_size`） |
 | `POST` | `/api/v1/tasks` | 创建任务 |
-| `GET` | `/api/v1/tasks/{id}` | 查询任务详情 |
-| `PUT` | `/api/v1/tasks/{id}` | 完整更新任务 |
-| `DELETE` | `/api/v1/tasks/{id}` | 删除任务 |
-| `POST` | `/api/v1/tasks/{id}/enable` | 启用任务并注册调度 |
-| `POST` | `/api/v1/tasks/{id}/disable` | 停用任务并取消调度 |
-| `POST` | `/api/v1/tasks/{id}/run` | 手动立即执行 |
-| `GET` | `/api/v1/tasks/{id}/runs` | 查询任务运行历史 |
-| `GET` | `/api/v1/runs/{run_id}` | 查询单次运行状态 |
-| `GET` | `/api/v1/runs/{run_id}/logs?offset=0` | 增量读取运行日志 |
-| `GET` | `/api/v1/runs/{run_id}/logs/download` | 下载完整运行日志 |
-| `POST` | `/api/v1/runs/{run_id}/cancel` | 取消正在运行的任务 |
-| `GET` | `/api/v1/events` | SSE 运行状态和日志事件 |
+| `GET` | `/api/v1/tasks/{id}` | 任务详情 |
+| `PUT` | `/api/v1/tasks/{id}` | 完整更新 |
+| `DELETE` | `/api/v1/tasks/{id}` | 删除（级联删除运行记录） |
+| `POST` | `/api/v1/tasks/{id}/enable` | 启用并注册调度 |
+| `POST` | `/api/v1/tasks/{id}/disable` | 停用并取消调度 |
+| `POST` | `/api/v1/tasks/{id}/run` | 手动立即执行（`202`） |
+| `GET` | `/api/v1/tasks/{id}/runs` | 运行历史（`status`、`trigger`、分页） |
+| `GET` | `/api/v1/runs/{run_id}` | 单次运行详情 |
+| `GET` | `/api/v1/runs/{run_id}/logs?offset=0` | 增量日志（`content`、`next_offset`、`complete`） |
+| `GET` | `/api/v1/runs/{run_id}/logs/download` | 下载完整日志 |
+| `POST` | `/api/v1/runs/{run_id}/cancel` | 取消运行 |
+| `GET` | `/api/v1/events` | SSE：`run` / `log` / `lagged` / `ready` |
 
-任务列表查询参数：
+### 示例
 
-- `q`：按任务 ID 或名称搜索。
-- `enabled`：按启用状态筛选。
-- `action_type`：`script`、`http` 或 `process`。
-- `page`：页码，默认 `1`。
-- `page_size`：每页数量，默认 `20`，最大 `100`。
+创建任务：
 
-运行历史查询额外支持 `status` 和 `trigger` 过滤。
+```http
+POST /api/v1/tasks
+X-TaskPilot-Token: <session token>
+Content-Type: application/json
 
-健康检查示例：
-
-```json
-{
-  "status": "ok",
-  "service": "task-pilot-backend",
-  "version": "0.1.0"
-}
-```
-
-创建脚本任务示例：
-
-```json
 {
   "id": "sync_data",
   "name": "数据同步",
@@ -218,157 +311,212 @@ $env:TASK_PILOT_LOG_ENCODING = "auto"
   "timezone": "Asia/Shanghai",
   "enabled": true,
   "timeout_secs": 300,
-  "retry_policy": {
-    "max_attempts": 0,
-    "delay_secs": 0
-  },
   "action": {
     "type": "script",
     "working_dir": "D:\\Projects\\sync",
     "interpreter": "python.exe",
     "script": "main.py",
     "args": ["--mode", "full"],
-    "env": {
-      "PYTHONUNBUFFERED": "1"
-    }
+    "env": {}
   }
 }
 ```
 
-校验失败和资源不存在时统一返回结构化错误：
+统计数据：
 
 ```json
-{
-  "code": "VALIDATION_ERROR",
-  "message": "Cron 表达式无效",
-  "field": "cron",
-  "details": {}
-}
+{ "total": 12, "enabled": 9, "running": 1, "script": 7, "http": 3, "process": 2 }
 ```
 
-## 开发命令
+调度信息：
 
-### 完整检查
+```json
+[ { "task_id": "sync_data", "next_run_at": "2026-10-26T18:00:00Z" } ]
+```
 
-在项目根目录执行：
+统一错误结构：
+
+```json
+{ "code": "VALIDATION_ERROR", "message": "Cron 表达式无效", "field": "cron", "details": {} }
+```
+
+常见错误码：`VALIDATION_ERROR`、`INVALID_JSON`、`INVALID_QUERY`、`TASK_NOT_FOUND`、
+`RUN_NOT_FOUND`、`RUN_LOG_NOT_FOUND`、`RUN_NOT_CANCELLABLE`、`TASK_ID_CONFLICT`、
+`DIRECTORY_PATH_INVALID`、`DIRECTORY_NOT_FOUND`、`DIRECTORY_UNREADABLE`、`FORBIDDEN`、`INTERNAL_ERROR`。
+
+---
+
+## 输入校验
+
+保存任务时逐项强制（失败返回 `400 VALIDATION_ERROR` 并带 `field`）：
+
+| 字段 | 规则 |
+| --- | --- |
+| `id` | 1–64，`[A-Za-z0-9_-]`；重复返回 `409 TASK_ID_CONFLICT` |
+| `name` | 去空格后 1–120 字符 |
+| `cron` | 可解析且存在未来触发点 |
+| `timezone` | 有效 IANA 名称 |
+| `timeout_secs` | 1–86400 |
+| `retry_policy` | `max_attempts ≤ 10`，`delay_secs ≤ 3600` |
+| `action.working_dir` / `interpreter` / `script` | 非空 |
+| `action.venv` | 若填写，必须存在 `pyvenv.cfg` 与 `Scripts\python.exe` |
+| `action.args` | ≤ 256 个，单个 ≤ 2048 字符 |
+| `action.env` | ≤ 128 条；key ≤ 128、不含 `=`/`\0`；value ≤ 8192、不含 `\0` |
+| `action.url` | 可解析、限 `http`/`https`、必须有主机名 |
+| `action.headers` | 名称/值符合 HTTP 规范 |
+| `action.body` | ≤ 1 MiB |
+| `action.expected_status` | 每项 100–599 |
+| 请求体 | 未知字段直接拒绝（`deny_unknown_fields`） |
+
+查询与读取：`page ≥ 1`、`page_size` 夹到 1–100、日志 `offset` 不得超过文件长度。
+
+**不在保存时校验**：工作目录是否存在、脚本文件是否存在、解释器是否存在（虚拟环境除外）。
+这些在执行时才暴露，属于日志里的运行错误。
+
+---
+
+## 数据与文件布局
+
+```text
+data/task_pilot.db          # SQLite（WAL）
+logs/{task_id}/{run_id}.log # UTF-8 运行日志
+.tmp/                       # check.ps1 的测试临时目录（已 gitignore）
+```
+
+`tasks` 表：主键 `id`，索引 `updated_at`、`enabled`、`action_type`。
+`task_runs` 表：`task_id` 外键 `ON DELETE CASCADE`，`status`/`trigger_type` 带 CHECK 约束，
+索引 `(task_id, created_at DESC)` 与 `status`。
+
+---
+
+## 架构与模块
+
+```text
+React (Vite) ──fetch──► Axum router ──security::api_guard(Origin + token)
+                          │
+                          ├── tasks: routes → service(校验) → repository(SQL)
+                          ├── runs : routes → repository
+                          ├── Scheduler ──trigger──► TaskExecutor ──► Job Object
+                          └── broadcast(512) ──► SSE /api/v1/events
+```
+
+| 模块 | 职责 |
+| --- | --- |
+| `api.rs` | 路由、OpenAPI 聚合、系统级接口（health/session/cron/stats/schedule） |
+| `tasks/` | 任务模型、校验、SQL、CRUD 路由 |
+| `runs/` | 运行记录、执行器、日志落盘、日志读取与 SSE |
+| `scheduler.rs` | 每任务一个调度循环、下次触发时间、注册与取消 |
+| `executor.rs` | 三类 Action 执行、并发闸门、超时/取消、日志脱敏与截断 |
+| `process_job.rs` | Windows Job Object（`KILL_ON_JOB_CLOSE`） |
+| `python_env.rs` | 虚拟环境解析与探测、PATH/编码注入 |
+| `directory_browser.rs` | 盘符与目录列举（页面内目录选择器） |
+| `security.rs` | Origin 白名单、令牌校验、常量时间比较 |
+| `database.rs` | 连接池与迁移（WAL/busy_timeout） |
+
+前端：
+
+| 模块 | 职责 |
+| --- | --- |
+| `pages/TaskDashboard.tsx` | 列表、筛选、分页、指标卡、下次触发时间 |
+| `components/TaskEditorModal.tsx` | 三类动态表单、Cron 预览、虚拟环境状态条 |
+| `components/DirectoryPickerDialog.tsx` | 页面内目录浏览器 |
+| `components/RunLogDrawer.tsx` | 运行历史、日志、取消、下载、SSE |
+| `api/client.ts` | 类型化客户端、令牌缓存、403 重试 |
+| `lib/taskForm.ts` | Zod 校验与表单 ↔ API 载荷映射 |
+
+---
+
+## 开发与测试
+
+### 环境
+
+- Windows 10/11
+- Rust 1.95（`rust-toolchain.toml` 固定，MSVC）
+- Node.js 24 / pnpm 11（`frontend/package.json` 的 `volta` 固定）
+- Visual Studio C++ Build Tools（Rust MSVC 需要）
+- 可选：`uv`（跑示例任务与自检脚本）
+
+### 完整质量门
 
 ```powershell
 .\scripts\check.ps1
 ```
 
-该脚本依次运行：
+依次执行：前端 lint → 类型检查 → Vitest → 生产构建 → `cargo fmt --check` →
+`clippy -D warnings` → `cargo test` → Playwright（真实后端 + Vite + Chrome）。
 
-- 前端 lint
-- TypeScript 类型检查
-- Vitest
-- 前端生产构建
-- Rust 格式检查
-- Rust Clippy
-- Rust 单元和集成测试
-- Playwright 浏览器端到端测试
+脚本会把 `TMP`/`TEMP` 指向仓库内 `.tmp/`，让测试不依赖系统临时目录的权限策略，
+结束时自动清理。
 
-### 浏览器端到端测试
+### 单独命令
 
 ```powershell
+pnpm --dir frontend lint | typecheck | test | build
+cargo fmt   --manifest-path backend/Cargo.toml -- --check
+cargo clippy --manifest-path backend/Cargo.toml --all-targets -- -D warnings
+cargo test  --manifest-path backend/Cargo.toml
 pnpm --dir frontend test:e2e
 ```
 
-端到端测试会清理并重建 `.e2e-data/`，启动临时 Rust 服务和 Vite，使用本机 Chrome 完成真实任务执行和页面操作。
-
-### 生成接口契约和类型
-
-修改后端 API DTO 或路由后执行：
+### 契约与类型
 
 ```powershell
-.\scripts\generate-api.ps1
+.\scripts\generate-api.ps1   # 更新 contracts/openapi.json 与 frontend/src/api/generated.ts
 ```
 
-该命令会更新：
+生成文件不要手工修改。
 
-- `contracts/openapi.json`
-- `frontend/src/api/generated.ts`
+### 测试构成
 
-生成文件不应手工修改。
+| 层 | 覆盖 |
+| --- | --- |
+| Rust 单元（52） | Cron、虚拟环境解析与探测、执行器（编码/截断/清理/句柄归属）、安全、目录列举 |
+| Rust 集成（30） | 任务 CRUD 与校验、运行生命周期、取消与超时、日志分块、调度恢复、统计与调度接口、重启对账 |
+| 前端 Vitest（13） | 仪表盘渲染、表单载荷、虚拟环境状态、目录浏览器（进入/取消/错误）、下次触发时间 |
+| Playwright（4） | 真实任务执行与日志、编辑/停用/删除、窄屏、**完全离线渲染**（拦截所有外部请求） |
+| Python 自检（14 项） | `tools/verify.py` 覆盖 API 全链路 |
 
-### 单独检查
+---
 
-```powershell
-pnpm --dir frontend lint
-pnpm --dir frontend typecheck
-pnpm --dir frontend test
-pnpm --dir frontend build
+## 故障排查
 
-cargo fmt --manifest-path backend/Cargo.toml -- --check
-cargo clippy --manifest-path backend/Cargo.toml --all-targets -- -D warnings
-cargo test --manifest-path backend/Cargo.toml
-```
+| 现象 | 处理 |
+| --- | --- |
+| `start.ps1` 无法运行 | `powershell -ExecutionPolicy Bypass -File .\release\TaskPilot\start.ps1` |
+| 端口被占用 | `$env:TASK_PILOT_PORT = "3100"` 后重启 |
+| 任务不执行 | 确认已启用、Cron 与下次触发时间正确；查看运行历史里的错误信息 |
+| PowerShell 脚本任务报「不是数字签名」 | 执行策略拦未签名脚本：在参数里加 `-ExecutionPolicy Bypass`，或对脚本目录 `Unblock-File` |
+| 日志出现 `����` | 程序未按 UTF-8 输出：设置 `TASK_PILOT_LOG_ENCODING=gbk`（或让程序输出 UTF-8） |
+| 日志尾部缺失 | 单次运行超过 5 MiB 或单行超过 256 KiB，会截断并写 `[system]` 说明 |
+| 运行一直显示"运行中" | 已由启动对账修复；若仍出现，检查进程是否被系统挂起 |
+| 虚拟环境未生效 | 目录下需同时有 `pyvenv.cfg` 与 `Scripts\python.exe`；也可在表单里显式指定 |
+| `cargo test` 报临时目录拒绝访问 | 用 `.\scripts\check.ps1`（会把 TEMP 指向 `.tmp/`）或手动设置 `TEMP` 到可写目录 |
 
-## 项目结构
+---
 
-```text
-task_pilot/
-├── backend/
-│   ├── src/
-│   │   ├── api.rs
-│   │   ├── cron.rs
-│   │   ├── database.rs
-│   │   ├── error.rs
-│   │   ├── lib.rs
-│   │   ├── main.rs
-│   │   ├── process_job.rs
-│   │   ├── scheduler.rs
-│   │   ├── security.rs
-│   │   ├── state.rs
-│   │   ├── runs/
-│   │   └── tasks/
-│   ├── migrations/
-│   ├── tests/
-│   ├── Cargo.toml
-│   └── Cargo.lock
-├── contracts/
-│   └── openapi.json
-├── docs/
-│   └── decisions/
-├── frontend/
-│   ├── e2e/
-│   ├── src/
-│   │   ├── components/
-│   │   ├── lib/
-│   │   └── pages/
-│   ├── package.json
-│   ├── playwright.config.ts
-│   ├── vite.config.ts
-│   └── vitest.config.ts
-├── scripts/
-│   ├── check.ps1
-│   ├── build-release.ps1
-│   ├── e2e.ps1
-│   ├── generate-api.ps1
-│   └── start.ps1
-├── task_pilot.html
-├── PLAN.md
-├── README.md
-└── rust-toolchain.toml
-```
+## 已知限制
 
-架构决策记录：
+- 自动重试尚未实现：`retry_policy` 只校验与存储。
+- 并发策略只有 `skip`；没有全局并发上限与队列。
+- HTTP Action 只校验状态码，不支持响应体断言、认证方案或 Header 断言。
+- 敏感值脱敏基于变量名关键词与值替换，不是凭据保险箱。
+- Conda 环境不会自动激活，需要显式填写解释器路径。
+- 本地单用户工具：读取接口免令牌，不支持远程部署与多用户。
+- 未安装为 Windows 服务；关闭启动脚本后调度停止。
+- 错过的调度不会补跑。
+
+---
+
+## 架构决策记录
 
 - [ADR-0001：Cron 解析与任务调度](docs/decisions/0001-cron-engine.md)
 - [ADR-0002：前后端开发与生产托管](docs/decisions/0002-static-hosting.md)
 - [ADR-0003：Python 虚拟环境启动环境](docs/decisions/0003-python-environment.md)
 - [ADR-0004：运行日志的输出编码](docs/decisions/0004-log-encoding.md)
 - [ADR-0005：由后端提供系统文件夹选择](docs/decisions/0005-folder-picker.md)
-
-## 当前限制
-
-- 重试策略字段已持久化，但自动重试尚未实现。
-- HTTP 任务执行器尚未提供响应 Header 转换等高级断言，只校验状态码。
-- 敏感值脱敏基于变量名关键词和值替换，不是系统凭据保险箱。
-- Conda 环境不会按 venv 自动激活，目前需要显式填写其 Python 解释器路径。
-- 当前版本是本地单用户工具，不支持多用户账户和远程部署。
-- 尚未安装为 Windows 系统服务，关闭启动脚本后调度器也会停止。
-- 旧 `task_pilot.html` 暂时保留在根目录作为设计参考，正式入口为 React 应用。
+- [ADR-0006：视觉风格对齐主题并自托管字体](docs/decisions/0006-visual-theme-and-offline-fonts.md)
+- [ADR-0007：运行期可靠性优化](docs/decisions/0007-runtime-reliability.md)
 
 ## 开发计划
 
-完整架构、数据模型、API 草案、阶段任务和验收标准见 [PLAN.md](PLAN.md)。六个开发阶段均已完成，后续进入维护、功能反馈和版本迭代。
+完整架构、数据模型、阶段任务与验收标准见 [PLAN.md](PLAN.md)。六个阶段均已完成，当前处于维护与迭代阶段。
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 710e8ee..45c9c46 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -16,7 +16,7 @@
 
 ## 数据目录
 
-- SQLite 数据库：`data/task_pilot.db`
+- SQLite 数据库：`data/task_pilot.db`（WAL 模式，运行中会额外出现 `-wal`/`-shm` 文件）
 - 运行日志：`logs/{task_id}/{run_id}.log`
 
 ## 配置
@@ -33,16 +33,25 @@ $env:TASK_PILOT_STATIC_DIR = "web"
 
 `TASK_PILOT_LOG_ENCODING` 默认 `auto`，会按 UTF-8 → 系统 ANSI 代码页（简体中文为 GBK）的顺序解码子进程输出；日志出现乱码时可显式指定 `gbk` 或 `utf-8`。
 
+单次运行日志上限 5 MiB，单行上限 256 KiB；日志按保留期与总容量清理，正在写入的文件不会被删除。
+
 ## 安全边界
 
 - 服务只监听 `127.0.0.1`。
 - 浏览器跨站 Origin 会被拒绝。
-- 写操作需要运行期随机管理令牌。
-- 管理令牌在进程重启后自动更换。
+- 写操作需要运行期随机管理令牌，进程重启后自动更换。
+- 请求体上限 2 MiB。
+
+## 离线使用
+
+前端资源、字体（`LXGW WenKai` / `Outfit-Medium`）与所有脚本都随包自带，不需要联网即可打开界面与执行任务。
 
 ## 故障排查
 
 - 3000 端口被占用时，通过 `TASK_PILOT_PORT` 修改端口；打包版前端使用同源 API，无需重新构建。
 - 页面无法打开时，确认 `web/index.html` 存在。
-- 任务未执行时，确认任务已启用、Action 配置有效，并在日志抽屉查看错误。
+- 任务未执行时，确认任务已启用、Cron 正确，并在任务表的「调度周期」列查看下次触发时间。
+- PowerShell 脚本任务报「不是数字签名」时，是执行策略拦截未签名脚本：在参数里加 `-ExecutionPolicy Bypass`，或对脚本目录执行 `Unblock-File`。
 - 进程无法启动时，检查解释器或可执行文件路径、工作目录和执行权限。
+- 日志里出现 `����`：改用 UTF-8 输出，或设置 `TASK_PILOT_LOG_ENCODING=gbk`。
+- 进程被强杀后，遗留的运行会在下次启动时标记为「已取消（进程重启中断）」，不是数据损坏。
diff --git a/samples/python-task/main.py b/samples/python-task/main.py
new file mode 100644
index 0000000..2a0de2b
--- /dev/null
+++ b/samples/python-task/main.py
@@ -0,0 +1,60 @@
+"""TaskPilot 演示任务。
+
+在 TaskPilot 里把「项目工作目录」指向本目录、解释器填 ``python.exe``、脚本填
+``main.py``，后端会自动关联同级的 ``.venv`` 并以虚拟环境解释器运行。
+
+常用参数：
+    --lines N     输出 N 行中文（默认 3）
+    --sleep N     执行前等待 N 秒，用于验证超时与取消
+    --fail        以退出码 3 结束，用于验证失败状态
+    --append PATH 把一行结果追加到指定文件，用于验证副作用
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="TaskPilot python demo task")
+    parser.add_argument("--lines", type=int, default=3)
+    parser.add_argument("--sleep", type=float, default=0.0)
+    parser.add_argument("--fail", action="store_true")
+    parser.add_argument("--append", type=Path)
+    args = parser.parse_args()
+
+    started = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    print(f"[demo] 启动时间 {started}")
+    print(f"[demo] 解释器 {sys.executable}")
+    print(f"[demo] VIRTUAL_ENV {os.environ.get('VIRTUAL_ENV', '<未设置>')}")
+    print(f"[demo] 工作目录 {Path.cwd()}")
+    print(f"[demo] 参数 lines={args.lines} sleep={args.sleep} fail={args.fail}")
+
+    for index in range(args.lines):
+        print(f"[demo] 第 {index + 1} 行：中文输出与勾选 √")
+
+    if args.append is not None:
+        args.append.parent.mkdir(parents=True, exist_ok=True)
+        with args.append.open("a", encoding="utf-8") as handle:
+            handle.write(f"{started} ok\n")
+        print(f"[demo] 已追加写入 {args.append}")
+
+    if args.sleep > 0:
+        print(f"[demo] 开始等待 {args.sleep} 秒", flush=True)
+        time.sleep(args.sleep)
+
+    if args.fail:
+        print("[demo] 按要求返回失败", file=sys.stderr)
+        return 3
+
+    print("[demo] 完成")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/samples/python-task/pyproject.toml b/samples/python-task/pyproject.toml
new file mode 100644
index 0000000..b9a6917
--- /dev/null
+++ b/samples/python-task/pyproject.toml
@@ -0,0 +1,6 @@
+[project]
+name = "taskpilot-python-demo"
+version = "0.1.0"
+description = "TaskPilot 演示任务：验证虚拟环境、中文输出与退出码"
+requires-python = ">=3.10"
+dependencies = []
diff --git a/tools/verify.py b/tools/verify.py
new file mode 100644
index 0000000..0273f4b
--- /dev/null
+++ b/tools/verify.py
@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""TaskPilot 端到端自检（仅标准库）。
+
+用法：
+    uv run tools/verify.py
+    uv run tools/verify.py --base-url http://127.0.0.1:3000 --keep
+
+它会真实地：创建任务 → 立即运行 → 读回日志 → 校验中文输出与虚拟环境注入 →
+校验调度与统计接口 → 删除任务（--keep 可保留）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+TASK_ID = "verify_python_demo"
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str = ""
+
+    def render(self) -> str:
+        marker = "OK  " if self.ok else "FAIL"
+        suffix = f"  {self.detail}" if self.detail else ""
+        return f"[{marker}] {self.name}{suffix}"
+
+
+@dataclass
+class Api:
+    base_url: str
+    token: str | None = None
+    checks: list[Check] = field(default_factory=list)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: dict | None = None,
+        authenticated: bool = False,
+    ) -> tuple[int, object]:
+        url = f"{self.base_url}{path}"
+        data = None
+        headers = {"Accept": "application/json"}
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if authenticated:
+            headers["X-TaskPilot-Token"] = self.token or ""
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=15) as response:
+                raw = response.read()
+                status = response.status
+        except urllib.error.HTTPError as error:
+            raw = error.read()
+            status = error.code
+        except urllib.error.URLError as error:
+            raise SystemExit(f"无法连接 {url}: {error.reason}") from error
+
+        if not raw:
+            return status, None
+        try:
+            return status, json.loads(raw.decode("utf-8"))
+        except json.JSONDecodeError:
+            return status, raw.decode("utf-8", errors="replace")
+
+    def check(self, name: str, ok: bool, detail: str = "") -> bool:
+        self.checks.append(Check(name, ok, detail))
+        return ok
+
+    def session(self) -> str:
+        status, body = self.request("GET", "/api/v1/session")
+        if status != 200 or not isinstance(body, dict):
+            raise SystemExit(f"获取会话令牌失败: HTTP {status}")
+        self.token = str(body["token"])
+        return self.token
+
+    def poll_run(self, run_id: int, timeout: float) -> dict:
+        deadline = time.monotonic() + timeout
+        terminal = {"succeeded", "failed", "timed_out", "cancelled", "skipped"}
+        while time.monotonic() < deadline:
+            status, body = self.request("GET", f"/api/v1/runs/{run_id}")
+            if status != 200 or not isinstance(body, dict):
+                raise SystemExit(f"读取运行记录失败: HTTP {status}")
+            if body.get("status") in terminal:
+                return body
+            time.sleep(0.2)
+        raise SystemExit(f"运行 {run_id} 在 {timeout} 秒内未结束")
+
+    def read_logs(self, run_id: int, timeout: float) -> str:
+        deadline = time.monotonic() + timeout
+        content = ""
+        offset = 0
+        while time.monotonic() < deadline:
+            status, body = self.request(
+                "GET", f"/api/v1/runs/{run_id}/logs?offset={offset}"
+            )
+            if status != 200 or not isinstance(body, dict):
+                raise SystemExit(f"读取运行日志失败: HTTP {status}")
+            content += str(body.get("content", ""))
+            offset = int(body.get("next_offset", offset))
+            if body.get("complete"):
+                return content
+            time.sleep(0.1)
+        return content
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="TaskPilot end-to-end self check")
+    parser.add_argument("--base-url", default="http://127.0.0.1:3000")
+    parser.add_argument(
+        "--working-dir",
+        default=str(Path(__file__).resolve().parent.parent / "samples" / "python-task"),
+        help="包含 .venv 的演示任务目录",
+    )
+    parser.add_argument("--keep", action="store_true", help="检查完成后保留任务")
+    parser.add_argument("--timeout", type=float, default=60.0)
+    args = parser.parse_args()
+
+    working_dir = Path(args.working_dir).resolve()
+    api = Api(args.base_url.rstrip("/"))
+
+    # 1. 健康检查
+    status, health = api.request("GET", "/api/v1/health")
+    api.check(
+        "health endpoint",
+        status == 200 and isinstance(health, dict) and health.get("status") == "ok",
+        f"HTTP {status}",
+    )
+
+    # 2. 会话令牌
+    token = api.session()
+    api.check("session token", bool(token), f"{len(token)} chars")
+
+    # 3. 目录列举能看到演示目录下的 .venv
+    query = urllib.parse.urlencode({"path": str(working_dir)})
+    status, listing = api.request("GET", f"/api/v1/system/directories?{query}")
+    names = [entry["name"] for entry in (listing or {}).get("entries", [])]
+    api.check(
+        "directory listing sees .venv",
+        status == 200 and ".venv" in names,
+        f"entries={names}",
+    )
+
+    # 4. 虚拟环境探测识别出 .venv\Scripts\python.exe
+    status, probe = api.request(
+        "POST",
+        "/api/v1/python/venv",
+        {"working_dir": str(working_dir), "interpreter": "python.exe", "venv": None},
+        authenticated=True,
+    )
+    probe = probe if isinstance(probe, dict) else {}
+    display_path = str(probe.get("display_path") or "")
+    api.check(
+        "venv probe links the demo environment",
+        status == 200
+        and probe.get("status") == "linked"
+        and display_path.endswith(r"Scripts\python.exe"),
+        f"status={probe.get('status')} path={display_path}",
+    )
+
+    # 5. 创建任务（启用 → 自动注册调度）
+    payload = {
+        "id": TASK_ID,
+        "name": "Python 演示任务",
+        "cron": "0 0 3 * * *",
+        "timezone": "Asia/Shanghai",
+        "enabled": True,
+        "timeout_secs": 30,
+        "action": {
+            "type": "script",
+            "working_dir": str(working_dir),
+            "interpreter": "python.exe",
+            "script": "main.py",
+            "args": ["--lines", "2"],
+            "env": {},
+        },
+    }
+    api.request("DELETE", f"/api/v1/tasks/{TASK_ID}", authenticated=True)
+    status, created = api.request(
+        "POST", "/api/v1/tasks", payload, authenticated=True
+    )
+    api.check("create task", status == 201, f"HTTP {status}")
+
+    # 6. 调度接口给出下次触发时间
+    status, schedule = api.request("GET", "/api/v1/schedule")
+    entries = schedule if isinstance(schedule, list) else []
+    entry = next((item for item in entries if item.get("task_id") == TASK_ID), None)
+    api.check(
+        "task is registered in the schedule",
+        status == 200 and entry is not None and bool(entry.get("next_run_at")),
+        f"next_run_at={(entry or {}).get('next_run_at')}",
+    )
+
+    # 7. 立即运行并等待结束
+    status, run = api.request(
+        "POST", f"/api/v1/tasks/{TASK_ID}/run", authenticated=True
+    )
+    run = run if isinstance(run, dict) else {}
+    run_id = int(run.get("id", 0))
+    api.check("run accepted", status == 202 and run_id > 0, f"run={run_id}")
+
+    finished = api.poll_run(run_id, args.timeout)
+    api.check(
+        "run succeeded",
+        finished.get("status") == "succeeded" and finished.get("exit_code") == 0,
+        f"status={finished.get('status')} exit={finished.get('exit_code')}",
+    )
+
+    # 8. 日志里能看到中文、虚拟环境注入与真实解释器路径
+    log = api.read_logs(run_id, args.timeout)
+    api.check("log contains Chinese output", "中文输出" in log)
+    api.check(
+        "log shows the venv interpreter",
+        ".venv" in log.lower() or "Scripts" in log,
+    )
+    api.check(
+        "log shows VIRTUAL_ENV injection",
+        "VIRTUAL_ENV" in log and "<未设置>" not in log,
+    )
+    api.check("log has no replacement characters", "\ufffd" not in log)
+
+    # 9. 统计接口口径正确
+    status, stats = api.request("GET", "/api/v1/stats")
+    stats = stats if isinstance(stats, dict) else {}
+    api.check(
+        "stats endpoint reports the task",
+        status == 200 and int(stats.get("total", 0)) >= 1 and int(stats.get("running", -1)) == 0,
+        f"total={stats.get('total')} enabled={stats.get('enabled')} running={stats.get('running')}",
+    )
+
+    # 10. 清理
+    if args.keep:
+        api.check("cleanup skipped (--keep)", True)
+    else:
+        status, _ = api.request(
+            "DELETE", f"/api/v1/tasks/{TASK_ID}", authenticated=True
+        )
+        api.check("delete task", status == 204, f"HTTP {status}")
+
+    failures = [check for check in api.checks if not check.ok]
+    print(f"\nTaskPilot self check against {args.base_url}\n")
+    for check in api.checks:
+        print(check.render())
+    print(f"\n{len(api.checks) - len(failures)}/{len(api.checks)} checks passed")
+    if failures:
+        print("\n失败的检查：")
+        for check in failures:
+            print(f"  - {check.name}: {check.detail}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())