# TaskPilot Windows 本地版

## 启动

```powershell
.\start.ps1
```

然后访问 <http://127.0.0.1:3000>。

需要自动打开浏览器时：

```powershell
.\start.ps1 -OpenBrowser
```

## 数据目录

- SQLite 数据库：`data/task_pilot.db`（WAL 模式，运行中会额外出现 `-wal`/`-shm` 文件）
- 运行日志：`logs/{task_id}/{run_id}.log`

## 配置

```powershell
$env:TASK_PILOT_PORT = "3000"
$env:TASK_PILOT_DATABASE_URL = "sqlite://data/task_pilot.db"
$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"
$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` 存在。
- 任务未执行时，确认任务已启用、Cron 正确，并在任务表的「调度周期」列查看下次触发时间。
- PowerShell 脚本任务报「不是数字签名」时，是执行策略拦截未签名脚本：在参数里加 `-ExecutionPolicy Bypass`，或对脚本目录执行 `Unblock-File`。
- 进程无法启动时，检查解释器或可执行文件路径、工作目录和执行权限。
- 日志里出现 `����`：改用 UTF-8 输出，或设置 `TASK_PILOT_LOG_ENCODING=gbk`。
- 进程被强杀后，遗留的运行会在下次启动时标记为「已取消（进程重启中断）」，不是数据损坏。