Skip to content

README_PowerShellTools-WebUI.md

Latest commit

 

History

History
134 lines (96 loc) · 5.36 KB

README_PowerShellTools-WebUI.md

File metadata and controls

134 lines (96 loc) · 5.36 KB

PowerShell-Tools WebUI

概览

PowerShellTools-WebUI/ 是本仓库的本地管理面板。它是独立的 Node.js 原生 HTTP 应用，默认只绑定本机地址，不复用 Gallery 的媒体访问权限，也不保存 Pixiv token。

WebUI 不自动安装 npm、Python、Docker、Flutter 或 Playwright 依赖。它只负责展示仓库索引、依赖状态、服务状态、风险预览、低风险 Runner 和审计日志。

启动

cd PowerShellTools-WebUI
npm install
npm start

默认监听：

http://127.0.0.1:3000

如端口被占用：

$env:WEBUI_PORT = "3001"
npm start

WEBUI_HOST 默认是 127.0.0.1，保持本机访问边界。

已实现范围

能力 说明
仓库只读索引 扫描 .ps1、关键 .py/.js、package.json、docker-compose.yml、计划文档和根目录 README。
风险识别 标记删除、移动、重命名、系统设置、镜像挂载、ADB / fastboot、网络请求、硬编码凭据、私密输出等风险。
脚本详情页 源码只读预览，命中行脱敏显示。
依赖检查 PowerShell、Node、npm、git、gh、7z、ExifTool、ffmpeg、aria2c、adb / scrcpy、Docker、Edge、项目 .venv 和端口。
低风险 Runner 仅允许运行白名单中的只读 PowerShell 脚本。
风险预览 不执行高风险脚本，只提取破坏性命中、可能影响路径、dry-run 线索、所需凭据名称和审计要求。
实时日志 /api/jobs/:id/events SSE 推送，默认视图使用脱敏日志。
输出解析 照片 CSV、SnowLuma 统计、Fanbox metadata、HyperOS 数据、Gallery reindex、Windows ISO、Danbooru JSON、AutoClicker 配置。
服务状态 Gallery、pixiVenera、WebPages 的本地直连健康检查。
文档入口 可查看允许清单内的根目录 README、AGENTS.md、PLAN.md、PowerShellTools-WebUI-Plan.md 和 REPORT_pixiVenera_Gallery.md。

只读索引

索引逻辑位于 PowerShellTools-WebUI/src/core.js。默认只读取允许范围内的源码、脚本、配置摘要和文档，不读取 .env 内容，不扫描 SnowLuma/output/groups/*/chat-record.md 正文。

WebUI 会识别不同目录的信任边界：

边界 示例
Gallery 媒体服务 Gallery-Server/、Gallery-WebPage/、Gallery-WebPageLite/、Gallery-Flutter/
Pixiv / Venera pixiVenera/、Extractors/、Extractors-Playwright/
本机脚本 根目录脚本、HyperOS/、Scrcpy/、WindowsISOs/ 等
私密输出 NapCat/、SnowLuma/

依赖检查

GET /api/dependencies 会检查命令、固定路径和常用本地端口。检查结果用于提示环境状态，不会自动安装或修改依赖。

常见检查项包括：

  • node、npm、git、gh。
  • 7z、ExifTool、ffmpeg、ffprobe、aria2c。
  • adb、scrcpy、Docker、Edge。
  • 项目 .venv。
  • Gallery、pixiVenera、WebPages 等本地端口。

风险预览与 Runner

Runner 只允许低风险白名单脚本运行。高风险脚本默认只生成影响预览，不执行。

审计记录包含任务 ID、脚本 hash、stdout / stderr、退出码和耗时。日志输出必须脱敏，不应包含 token、Basic Auth、Bearer token、OAuth body 或完整图片 URL。

默认不可运行的脚本类别包括：

  • 删除、移动、重命名或系统设置脚本。
  • 镜像挂载、ADB / fastboot、外部网络请求脚本。
  • danbooru/*.ps1、NapCat/*.ps1、SnowLuma/*.ps1。
  • HyperOS/patchboot.ps1。

API 摘要

API 用途
GET /api/catalog 仓库索引、脚本风险、文档、策略和解析器列表。
GET /api/script?path=... 单个脚本详情。
GET /api/dependencies 依赖、固定路径、端口检查。
GET /api/preview?path=... 脚本影响预览与阻止原因。
GET /api/services 本地服务健康检查。
GET /api/parsers 解析器列表。
GET /api/parser?id=... 输出解析结果。
POST /api/jobs 启动低风险白名单脚本。
GET /api/jobs/:id/events SSE 实时日志。
POST /api/jobs/:id/cancel 取消运行中任务。
GET /api/audit 审计事件。
GET /api/docs?path=... 读取允许清单内文档。

VSCode Codex + SOCKS5 代理

WebUI 启动时会补齐：

NO_PROXY=localhost,127.0.0.1,::1,0.0.0.0,*.local
no_proxy=localhost,127.0.0.1,::1,0.0.0.0,*.local

后端对 Gallery、pixiVenera、WebPages 等本地服务使用 127.0.0.1 和 Node 原生 http 直连检查，不通过 SOCKS5 代理。若健康检查失败但端口实际存在，优先检查 NO_PROXY / no_proxy 是否被覆盖。

信任边界

  • WebUI 不继承 Gallery 媒体访问权限。
  • WebUI 不保存 Pixiv token。
  • WebUI 不把 pixiVenera 代理视为脚本执行权限来源。
  • Gallery 媒体服务、WebUI 脚本执行、Pixiv 代理、QQ / NapCat 私密输出互相独立。
  • .env 只显示存在性，不读取内容。

测试

cd PowerShellTools-WebUI
npm test

测试覆盖本地代理绕过配置、脱敏、仓库索引、风险阻止、低风险白名单、服务检查、解析器和核心 API。

相关文档