PowerShellTools-WebUI-Plan.md

PowerShell-Tools WebUI 管理面板实施计划表

0. 背景信息：VSCode 内 Codex 与代理环境

项目	说明
运行环境	当前任务运行在 VSCode 内的 Codex，不是独立终端环境。
代理来源	Codex 可能会继承或接受 VSCode 配置文件中的 SOCKS5 代理设置。
外网访问	访问 GitHub、npm、API、远程资源等外网目标时，可以使用 VSCode 配置的 SOCKS5 代理。
本地访问	访问 localhost、127.0.0.1、::1、本机端口、局域网地址时，必须避免错误地走 SOCKS5 代理。
重点风险	如果本地服务请求被代理转发，可能导致 WebUI 健康检查、SSE/WebSocket、本地 API、Gallery、pixiVenera、NapCat 等服务探测失败。

本地服务访问要求

场景	要求
WebUI 后端访问前端	本地请求必须优先直连。
前端访问本地 API	http://localhost:*、http://127.0.0.1:* 不应走代理。
健康检查	检查本地端口和本地 HTTP 服务时，应绕过 SOCKS5 代理。
SSE / WebSocket	实时日志流、本地任务监控连接必须按本地直连处理。
Gallery / pixiVenera / NapCat	访问这些本地服务时，需要明确处理代理绕过问题。
外网请求	外网请求可以使用代理，但必须与本地服务请求区分。

NO_PROXY / no_proxy 建议

配置项	建议值
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

实现要求

模块	要求
后端 HTTP 请求	区分外网请求和本地请求；本地请求默认不走代理。
依赖检查	如果本地服务探测失败，需要提示可能是代理绕过配置问题。
服务健康检查	对 localhost / 127.0.0.1 的检查必须显式绕过代理。
日志输出	失败日志中应显示请求目标是“本地服务”还是“外网资源”。
文档	README 中需要说明 VSCode Codex + SOCKS5 代理环境下的本地服务访问注意事项。

验收标准

验收项	标准
本地直连	WebUI 能正常访问本地后端 API，不因 SOCKS5 代理失败。
健康检查	本地端口健康检查不会被代理劫持。
实时日志	SSE/WebSocket 实时日志连接可正常建立。
错误提示	本地服务访问失败时，能提示检查 NO_PROXY / no_proxy。
外网兼容	外网请求仍可按 VSCode/Codex 代理配置访问。

1. 项目目标

目标	说明
统一入口	将当前仓库中分散在根目录、Test-Photos、HyperOS、Scrcpy、Extractors-Playwright、NapCat、SnowLuma、danbooru 等目录的脚本整理为一个本地 WebUI 管理面板。
可视化管理	在 WebUI 中查看脚本用途、风险等级、依赖状态、参数、运行记录、输出文件和日志。
安全运行	默认只读扫描；脚本运行必须经过分类、权限控制、参数校验、工作目录限制、超时限制和敏感信息脱敏。
实时监控	对 PowerShell、Node、Python、Docker/外部工具调用提供任务队列、实时 stdout/stderr、退出码、运行耗时和可取消能力。
结构化输出	对已有 CSV、JSON、Markdown、日志输出做专用解析页面，例如照片 EXIF 报告、NapCat 群消息统计、Fanbox 下载进度、HyperOS ROM 更新结果、Gallery 重建索引状态。
保持原仓库语义	WebUI 第一阶段只建立索引和管理层，不强行重构现有脚本；任何未来修改都必须遵守 AGENTS.md 的 Conventional Commits、SSH 签名和 Python .venv 规则。

2. 当前仓库结构分析

区域	实际目录/文件	当前用途理解	WebUI 接入建议
根目录总览	README.md、AGENTS.md、PLAN.md、README_Gallery.md、README_pixiVenera.md、REPORT_pixiVenera_Gallery.md	仓库说明、提交规范、Gallery/pixiVenera 审查与计划记录。	作为 WebUI 首页“项目说明”和“规则中心”的只读资料来源。
根目录维护脚本	AliDoH.ps1、Get-GitHubReleaseAsset.ps1、Get-GitHubReleaseAsset-Prism.ps1、Update-GitHubRepoFileTimestamp.ps1、Update‑ArchiveFileTimestamp.ps1	DNS over HTTPS 注册、GitHub Release 下载、Git/压缩包时间戳修正。	分类为“系统与仓库维护”；AliDoH.ps1 和时间戳写入脚本默认高风险阻止直接运行。
自动点击配置	AutoClicker/generate.ps1、多个 [分辨率]QQ聊天记录滑动(延迟xMS).accs	生成不同分辨率和延迟的自动滑动配置。	分类为“移动端辅助”；可展示分辨率/延迟矩阵，运行时要求确认会覆盖生成 .accs。
照片/视频整理	Test-Photos/*.ps1	ExifTool 读取照片/视频信息、生成 CSV、按拍摄时间重命名、MD5 重命名、GIF 魔数检查。	分类为“媒体整理”；只读检测脚本和重命名脚本分开，重命名脚本必须要求 dry-run/预览。
gallery-dl 后处理	gallery-dl/Set-FileTimeFromName.ps1、gallery-dl/test.ps1	根据文件名或 metadata HTML 调整时间戳、生成带媒体预览的 HTML。	分类为“下载后整理”；展示匹配规则、影响路径和输出 HTML。
Gallery Web 服务	Gallery/server.js、Gallery/js/server/*、Gallery/js/utils/*、Gallery/index.html	已有 Node HTTP 画廊服务器，包含 /api/list、/api/search、/api/reindex、缩略图、SQLite 索引、目录树。	可复用其“模块化 server + 原生 JS 前端”的设计经验；WebUI 不应直接混用 Gallery 的媒体访问权限。
Gallery 稳定版	Gallery-Stable/*	Gallery 的稳定参考副本。	只读展示版本对照，不作为默认运行入口。
简易 WebPages	WebPages/server.js、serverGallery.js、serverShare.js、index.html	早期/简化版静态或媒体服务器，端口 25567/25571/25572，路径硬编码到 F:/Gallery。	分类为“Web 服务实验”；高亮硬编码路径和路径遍历检查要求。
Fanbox/Pixiv 提取	Extractors/Get-FanboxPost.ps1、Extractors/fanbox_api_*.py、Extractors-Playwright/Start-FanboxCreatorDownload.ps1、fanbox-api.js、fanbox-downloads.js、pixiv_oauth_watch.py	Fanbox API/Playwright 下载，Pixiv OAuth 观察与脱敏验证。	分类为“内容提取”；Python 必须强制 .venv，下载脚本限制目标目录和并发。
pixiVenera	pixiVenera/server/src/*、pixiVenera/venera-source/pixiv-source.js、pixiv-direct-source.js、README_pixiVenera.md	Pixiv Venera 漫画源，Node 服务为无状态 OAuth/API/图片代理。	分类为“Pixiv/Venera”；提供服务状态、端点说明、token 存储风险检查，不在 WebUI 保存 Pixiv token。
venera / pixez-flutter	venera/*、pixez-flutter/*	大型参考仓库，含 Flutter/Dart/平台代码。	只作为参考资料索引；默认排除运行和深度扫描，避免把 WebUI 变成 Flutter 项目管理器。
HyperOS	HyperOS/Update-HyperOS.ps1、patchboot.ps1、qqupdate.ps1、test.ps1、xiaomicloudtest.ps1、devices.json、devices.txt	小米 ROM 更新检测/下载、KernelSU boot patch、QQ/XiaomiCloud 版本探测。	分类为“Android/HyperOS”；下载、删除旧包、boot patch 全部高风险，必须手动批准。
Scrcpy	Scrcpy/镜像屏幕.ps1、启动QQ.ps1、游戏.ps1、包名.txt、*.ahk	ADB 连接、scrcpy 投屏、新显示启动 QQ/游戏。	分类为“Android 控制”；WebUI 提供设备/序列号输入，禁止保存敏感设备地址为公开日志。
NapCat / SnowLuma	NapCat/testGET.ps1、SnowLuma/testGET.ps1、SnowLuma/test-msg-history.ps1、SnowLuma/output/*	调用本地 NapCat API 导出群列表、成员、群消息历史，SnowLuma 已有大量输出结果。	分类为“QQ/NapCat 数据”；硬编码 Bearer token、群消息隐私和大输出目录必须作为高风险处理。
danbooru	danbooru/upload_and_post.ps1、upload-EVERYTHING.ps1、update_post.ps1	调用本地 Danbooru API 上传、发帖、修改帖子。	分类为“Danbooru 发布”；脚本含 Basic Auth 凭据，默认禁止运行并要求迁移到 WebUI 秘钥注入。
Windows ISO	WindowsISOs/hash.ps1、WindowsISOs/test.ps1	ISO SHA256 统计、挂载 Windows ISO 并用 7-Zip 解析 install.wim/esd XML。	分类为“镜像/安装包分析”；挂载/解挂和 D:\uupdump 临时文件清理需独立安全策略。
小米备份	XiaomiBackups/test.ps1	解析 MIUI 备份 descript.xml，批量调整备份目录时间戳。	分类为“备份整理”；高风险写入时间戳，必须预览影响数量。
Docker/PiGallery2	docker/docker-compose.yml、docker/config/config.json、docker/db/sqlite.db	PiGallery2 容器配置，映射 F:/Gallery/gallery-dl/gallery-dl 到容器。	分类为“外部服务”；展示 Compose 状态和认证配置风险，不自动启动容器。
Edge 工作区	EdgeWorkspace/start.ps1、workspaces.txt	启动 Edge/Edge Dev 多个 workspace。	分类为“浏览器工作区”；运行前显示将启动的 workspace 数量。
MinecraftFriends	MinecraftFriends/test.py	Minecraft Friends API 测试，读取 MINECRAFT_ACCESS_TOKEN 或交互输入 token。	分类为“API 实验”；Python .venv 强制，token 禁止写日志。
环境与敏感文件	.env、各脚本中的 token/password 字符串	本地环境与历史测试凭据。	WebUI 索引时只显示“存在敏感文件/硬编码凭据”，不读取、不展示实际值。

3. 脚本分类建议

一级分类	二级分类	代表脚本/文件	默认风险	主要依赖
系统与仓库维护	DNS / 时间戳 / Release 下载	AliDoH.ps1、Update-GitHubRepoFileTimestamp.ps1、Update‑ArchiveFileTimestamp.ps1、Get-GitHubReleaseAsset*.ps1	中到高	PowerShell、git、gh、7z、管理员权限
媒体整理	照片/视频 EXIF、MD5、GIF 检查	Test-Photos/Test-PhotoInfo.ps1、Test-PhotoFileName.ps1、Update-PhotoFileName*.ps1、Update-VideoFileName.ps1、pictures-filename-md5.ps1	读：低；改名：高	ExifTool、PowerShell 并行
下载后处理	gallery-dl 输出整理	gallery-dl/Set-FileTimeFromName.ps1、gallery-dl/test.ps1	中	PowerShell、文件系统写入
画廊服务	Gallery / PiGallery / WebPages	Gallery/server.js、Gallery/js/server/reindex.js、WebPages/serverGallery.js、docker/docker-compose.yml	中	Node.js、sql.js、ffmpeg/ffprobe、Docker
Pixiv/Venera	漫画源与代理	pixiVenera/server/src/index.js、pixiVenera/venera-source/*.js、README_pixiVenera.md	中到高	Node.js、undici、express、代理、Venera
Fanbox/Pixiv 抓取	Fanbox 下载、OAuth 观察	Extractors/Get-FanboxPost.ps1、Extractors-Playwright/Start-FanboxCreatorDownload.ps1、pixiv_oauth_watch.py	高	Node.js、Playwright、Python .venv、Edge Dev、代理
Android/小米	ROM、boot patch、Scrcpy	HyperOS/Update-HyperOS.ps1、patchboot.ps1、Scrcpy/镜像屏幕.ps1、启动QQ.ps1、游戏.ps1	高	aria2c、KernelSU CLI、magiskboot、fastboot、adb、scrcpy
QQ/NapCat	群列表、成员、消息历史	NapCat/testGET.ps1、SnowLuma/testGET.ps1、SnowLuma/test-msg-history.ps1	高	NapCat 本地 API、Bearer token、CSV/Markdown 输出
Danbooru	上传/发帖/更新	danbooru/upload_and_post.ps1、upload-EVERYTHING.ps1、update_post.ps1	高	curl.exe、本地 Danbooru、Basic Auth
镜像/备份分析	Windows ISO / MIUI 备份	WindowsISOs/hash.ps1、WindowsISOs/test.ps1、XiaomiBackups/test.ps1	中到高	Mount-DiskImage、7z、PowerShell XML
自动点击/浏览器	AutoClicker、Edge workspace	AutoClicker/generate.ps1、EdgeWorkspace/start.ps1、*.ahk	中	PowerShell、Edge、AutoHotkey/外部 app
参考代码	venera、pixez-flutter、Gallery-Stable	venera/doc/*.md、pixez-flutter/README.md、Gallery-Stable/server.js	只读	不运行

4. 左侧 WebUI 侧边栏分类设计

侧边栏入口	子项	对应本地内容	页面目标
仪表盘	总览、最近任务、风险提醒、依赖缺失	全仓库索引	显示脚本数量、风险分布、可运行/阻止状态、最近日志。
脚本库	全部脚本、按目录、按风险、按依赖	所有 .ps1、关键 .py、.js	搜索、筛选、查看脚本详情、参数、依赖和输出。
系统维护	DNS、Git、压缩包、Release	根目录脚本	展示系统级操作，默认高风险确认。
媒体整理	照片、视频、GIF、gallery-dl	Test-Photos、gallery-dl	EXIF/重命名预览、CSV 输出查看。
Gallery 管理	Gallery 服务、索引、搜索、缩略图、PiGallery2	Gallery、Gallery-Stable、docker、WebPages	查看服务状态、重建索引进度、风险配置。
Pixiv / Venera	pixiVenera、Venera 源、Pixiv OAuth 工具	pixiVenera、README_pixiVenera.md、Extractors-Playwright/pixiv_oauth_watch.py	只读端点说明、依赖检查、脱敏状态。
Fanbox 下载	旧 Python 版、Playwright/Node 版	Extractors、Extractors-Playwright	下载任务模板、metadata 解析、断点/part 文件状态。
Android / HyperOS	ROM 更新、boot patch、scrcpy、AutoClicker	HyperOS、Scrcpy、AutoClicker	设备、ROM、ADB、投屏和配置生成管理。
QQ / NapCat	群列表、成员、消息历史、SnowLuma 输出	NapCat、SnowLuma	私有数据查看、统计、输出文件解析和权限提醒。
Danbooru	上传、批量上传、帖子更新	danbooru	API 请求预览、结果 JSON 解析、凭据迁移提醒。
镜像与备份	Windows ISO、XiaomiBackups	WindowsISOs、XiaomiBackups	ISO 哈希/版本表、备份时间戳预览。
依赖检查	PowerShell、Node、Python、外部 exe	全仓库命令引用	逐项检查 Get-Command、固定路径、端口、.venv。
日志中心	实时输出、历史任务、输出文件	WebUI 任务日志和脚本现有输出	原始日志、结构化事件、敏感信息脱敏查看。
安全策略	风险规则、路径白名单、凭据、角色	WebUI 配置	管理 allowlist、denylist、审批和脱敏规则。

5. 后端功能模块规划

模块	职责	需理解的现有文件	关键设计
RepositoryIndexer	扫描仓库结构，排除 .git、node_modules、大参考仓库和生成输出。	README.md、AGENTS.md、所有顶层目录	生成脚本目录、文件类型、大小、最近修改、分类建议、风险标签。
ScriptAnalyzer	解析 .ps1 的 param()、Read-Host、ForEach-Object -Parallel、外部命令、写入操作。	SnowLuma/test-msg-history.ps1、Scrcpy/*.ps1、HyperOS/*.ps1、Test-Photos/*.ps1	自动识别 Rename-Item、Remove-Item、Move-Item、Mount-DiskImage、Start-Process 等风险。
CatalogStore	存储脚本索引、风险分类、依赖状态、运行模板。	全仓库	建议使用 SQLite；索引输出放在未来 WebUI 私有数据目录，不改写脚本目录。
DependencyChecker	检查 PowerShell、Node、Python .venv、外部 exe 和端口。	AGENTS.md、package.json、硬编码路径	不自动安装；只报告缺失、版本和建议。
SafetyPolicy	运行前校验风险等级、用户确认、路径白名单、敏感参数、超时和并发。	danbooru/*.ps1、NapCat/*.ps1、HyperOS/patchboot.ps1	默认阻止高风险脚本；允许运行前显示命令、工作目录、影响路径。
SecretVault	管理 token、Basic Auth、代理、API 密钥。	.env、NapCat/Danbooru/Pixiv 相关脚本	不读取 .env 内容；未来通过 WebUI 单独录入或环境变量注入，日志全脱敏。
JobRunner	用子进程运行 PowerShell/Node/Python/Docker 命令。	.ps1、Gallery/server.js、pixiVenera/server/src/index.js	使用非交互进程、任务 ID、退出码、取消、超时、并发限制。
StreamHub	实时推送 stdout/stderr/结构化事件。	所有脚本输出	WebSocket 或 SSE；支持行级解析和 tail。
LogStore	保存原始日志、脱敏日志、结构化事件、输出文件引用。	SnowLuma/output、Test-Photos/*.csv、Gallery 日志	原始日志默认本机可见；对 token、路径、群号、URL query 做脱敏策略。
OutputParsers	将 CSV/JSON/Markdown/文本输出转换为专用页面。	PhotoInfo.csv、VideoInfo.csv、msg-history-summary.csv、metadata.json、HyperOS 输出	每个解析器声明输入文件、字段、隐私等级和刷新方式。
ServiceSupervisor	管理长驻服务状态。	Gallery/server.js、pixiVenera/server/src/index.js、WebPages/server*.js、docker/docker-compose.yml	展示端口、PID、健康检查；默认不暴露到公网。
AuditReporter	生成执行审计和计划/验收报告。	REPORT_pixiVenera_Gallery.md 风格	记录谁在何时运行了什么脚本、参数、审批、结果。

6. 前端页面规划

页面	主要组件	直接引用的本地对象	验收要点
仪表盘	风险分布、缺失依赖、最近任务、服务状态	全仓库索引、Gallery、pixiVenera	能一眼看出哪些脚本可安全运行、哪些被阻止。
脚本库	表格、目录树、标签筛选、全文搜索	.ps1、关键 .py/.js	能按目录、风险、依赖、用途过滤。
脚本详情	摘要、源码只读预览、依赖、风险、参数表、输出说明	单个脚本	高风险行如 Remove-Item、Rename-Item、Bearer token 命中要突出显示但不展示敏感值。
运行面板	参数表单、工作目录、环境变量选择、dry-run、确认弹窗	可运行脚本模板	Read-Host 脚本提供 UI 输入，未分类脚本不允许直接运行。
任务监控	队列、实时日志、取消、重试、退出码、耗时	JobRunner	stdout/stderr 实时滚动，退出后保留历史。
日志中心	日志搜索、脱敏视图、原始视图权限、输出文件关联	LogStore、脚本输出目录	能从一次任务跳转到 CSV/JSON/Markdown 解析结果。
依赖检查	依赖矩阵、版本、固定路径、端口占用	gh、git、7z、ExifTool、aria2c、adb、scrcpy、ffmpeg、.venv	不安装，只报告。
Gallery 管理	服务状态、API 健康、索引进度、搜索性能警告	Gallery/server.js、/api/reindex-status、README_Gallery.md	能查看 Gallery 当前硬编码 F:\Gallery 风险和重建索引状态。
Pixiv/Venera 管理	pixiVenera 服务、端点、OAuth 安全说明、代理配置检查	pixiVenera/server、README_pixiVenera.md	不保存 Pixiv token；只展示服务健康和配置风险。
Fanbox 下载	creatorId、下载目录、post metadata、part 文件、失败重试	Extractors-Playwright/Start-FanboxCreatorDownload.ps1	能展示下载进度和 metadata.json 摘要。
照片/视频输出	EXIF 表、重命名预览、CSV 导出、差异过滤	Test-Photos 输出 CSV	重命名脚本必须先显示“旧名 -> 新名”。
NapCat/SnowLuma 输出	群列表、消息总数、缺口、消息类型、错误	SnowLuma/output/groups/*	默认隐藏消息正文，先展示统计与隐私提醒。
HyperOS/Android	设备表、ROM 版本、下载/MD5、patchboot 状态、ADB 设备	HyperOS/devices.json、Scrcpy/包名.txt	boot/fastboot 相关必须二次确认。
Danbooru	上传队列、API 响应、重复 MD5、帖子字段	danbooru/*.ps1	禁止使用硬编码凭据运行；必须改为秘钥注入后才允许。
设置/安全	路径白名单、敏感字段、角色、端口、保留策略	WebUI 配置	所有默认设置偏保守，本地绑定 127.0.0.1。

7. 脚本运行与监控设计

设计项	方案
默认策略	第一版只允许运行低风险、只读、无硬编码凭据、无外部破坏性命令的脚本；中高风险脚本仅可查看和做依赖检查。
任务状态	blocked、queued、running、succeeded、failed、cancelled、timed_out。
运行隔离	每个任务使用独立子进程、固定工作目录、有限环境变量、最大运行时长、最大输出大小。
PowerShell 运行	优先使用 pwsh，缺失时使用 Windows PowerShell；记录版本。
Python 运行	严格遵守 AGENTS.md：只允许在项目级 .venv 存在并激活后运行；没有 .venv 时阻止 Extractors/*.py、pixiv_oauth_watch.py、MinecraftFriends/test.py。
Node 运行	对 Gallery、pixiVenera/server、Extractors-Playwright 检查 package.json 和 node_modules 状态；不自动 npm install。
交互输入	Read-Host 转换为 Web 表单字段，例如 Scrcpy/镜像屏幕.ps1 的 ADB/Wireless 选择、IP:Port 输入。
并发控制	全局并发默认 1-2；下载类、扫描类、NapCat 类独立队列；ForEach-Object -Parallel 脚本需显示内部并发。
取消机制	向子进程发送终止信号；对长任务记录“已请求取消”，必要时提示可能残留外部进程。
运行前预览	展示命令、脚本路径、工作目录、参数、会写入的目录、命中的高风险语句。
审计	保存用户、时间、脚本版本 hash、参数脱敏、依赖快照、退出码和输出文件清单。

8. 日志保存与实时输出设计

日志类型	内容	保存策略	隐私处理
原始 stdout/stderr	子进程输出原文	仅本机管理员/开发者可查看，可设置保留天数	默认不在列表页直接展示。
脱敏日志	替换 token、Basic Auth、URL query 中的敏感字段	默认展示	Bearer、refresh_token、access_token、-u user:pass、xsec_token 等全部遮蔽。
结构化事件	开始、进度、下载成功、跳过、错误、退出码	长期保存	不保存敏感参数。
输出文件索引	CSV/JSON/MD/HTML/图片等输出路径和大小	保存引用，不复制大文件	SnowLuma/output 默认标记为私密。
服务日志	Gallery/pixiVenera/WebPages 的请求状态、端口、PID	按服务分组	URL query 脱敏。
审计日志	谁运行、审批、风险、参数摘要	不可由普通页面删除	凭据值不入库。

实时输出建议：

• 使用 SSE 或 WebSocket 推送任务日志行。
• 前端提供“原始/脱敏/结构化”三种视图。
• 对 SnowLuma/test-msg-history.ps1 这类长输出脚本按阶段折叠：获取群列表、分页消息、生成报告、统计结果。
• 对 Extractors-Playwright/Start-FanboxCreatorDownload.ps1 解析 [SUCCESS]、[SKIPPED]、[WARNING]、[ERROR-X] 前缀。
• 对 Gallery 服务日志解析 method path status ms。

9. 专用于部分脚本的输出解析页面设计

专用页面	输入来源	解析字段	页面展示
照片 EXIF 检查	Test-Photos/PhotoInfo.csv、VideoInfo.csv、Test-PhotoFileName_Result.csv、screenshotsInfo.csv	文件名、拍摄时间、机型、XMP 标记、建议新名、状态	表格筛选、缺失字段统计、重命名预览。
视频重命名预览	Test-Photos/Update-VideoFileName.ps1 输出	原文件名、创建时间、时长、Dolby 标记、目标名	只读脚本先模拟，确认后才允许真实改名。
NapCat 群数据	SnowLuma/output/msg-history-summary.csv、groups/*/group-metadata.json、gaps.csv、message-types.csv	群号、群名、消息总数、请求次数、缺口、错误、消息类型	默认只看统计；查看正文需额外权限。
SnowLuma Markdown 聊天记录	SnowLuma/output/groups/*/chat-record.md	时间、发送者、内容摘要	默认脱敏/折叠正文，支持搜索但记录审计。
Fanbox 下载	Extractors-Playwright/Fanbox/*/metadata.json、脚本日志	creator/user、post id、标题、发布日期、媒体数量、跳过/失败	下载进度、失败重试、已存在统计。
HyperOS 更新	HyperOS/devices.json、devices.txt、Update-HyperOS.ps1 输出	设备代号、设备名、版本、文件名、MD5、本地是否存在	ROM 更新候选表、下载状态、旧版本清理预览。
KernelSU patchboot	HyperOS/patchboot.ps1 输出和生成文件	KMI、原始 boot/init_boot、目标文件、生成 bat	高危提示、生成结果查看，不自动 fastboot。
QQ/XiaomiCloud 探测	HyperOS/found_qq_versions.txt、qqupdate.ps1/xiaomicloudtest.ps1 输出	版本、日期、URL、HTTP 状态	可用版本表、重复去重。
Gallery 索引	Gallery/js/server/reindex.js 的 /api/reindex-status	running、state、current、total、msg、stats	进度条、耗时、最近错误、全量/增量模式。
Gallery 搜索风险	README_Gallery.md 审查记录、API health	搜索路径、查询、耗时、是否 FS 回退	性能提示和超时记录。
Windows ISO	WindowsISOs/WindowsISOsHash.csv、WindowsISOs/test.ps1 输出	SHA256、路径、LastWriteTime、版本号、Build、Branch	ISO 清单、版本解析结果。
Danbooru API	danbooru/*.ps1 的 curl JSON 输出	upload id、post id、tag_string、rating、source、错误码	请求预览、响应查看、失败原因；凭据必须外置。
AutoClicker 配置	AutoClicker/*.accs、generate.ps1	分辨率、延迟、滑动坐标、文件名	配置矩阵、生成预览、重复检测。
Scrcpy 会话	Scrcpy/包名.txt、脚本运行日志	serial、package、窗口参数、fps、退出码	启动记录、失败原因、ADB 连接状态。

10. 高风险脚本和安全限制

风险类型	命中的实际脚本/目录	风险说明	WebUI 限制
系统设置	AliDoH.ps1	调用 Add-DnsClientDohServerAddress 修改系统 DoH。	默认阻止；需要管理员确认和回滚说明。
批量重命名	Test-Photos/Update-PhotoFileName.ps1、Update-PhotoFileNameFULL.ps1、Update-VideoFileName.ps1、pictures-filename-md5.ps1	对真实照片/视频批量 Rename-Item。	必须先 dry-run 生成映射表；无映射表不允许执行。
批量时间戳写入	Update-GitHubRepoFileTimestamp.ps1、Update‑ArchiveFileTimestamp.ps1、gallery-dl/Set-FileTimeFromName.ps1、XiaomiBackups/test.ps1	改写文件/目录时间戳，可能影响备份和同步。	显示影响数量和样例；默认需要二次确认。
删除/移动文件	HyperOS/Update-HyperOS.ps1、patchboot.ps1、WindowsISOs/test.ps1、Extractors-Playwright/Start-FanboxCreatorDownload.ps1	Remove-Item、Move-Item、删除 .part 或旧 ROM 包。	路径白名单；禁止计算路径越界；显示删除列表。
镜像挂载	WindowsISOs/test.ps1	Mount-DiskImage/Dismount-DiskImage，使用 D:\uupdump 临时目录。	需要管理员/系统能力检查；失败时确保提示手动卸载。
boot/fastboot	HyperOS/patchboot.ps1	KernelSU patch、生成 fastboot bat，涉及设备刷机。	WebUI 只允许生成/查看；不允许直接执行 fastboot flash。
下载与清理旧包	HyperOS/Update-HyperOS.ps1	aria2c 下载 ROM，MD5 后移动并删除旧版本。	默认仅检测版本；下载/清理拆成两个显式步骤。
硬编码凭据	danbooru/*.ps1、NapCat/testGET.ps1、SnowLuma/*.ps1	脚本中存在 Basic Auth/Bearer token 字符串。	禁止直接运行；先迁移为 WebUI SecretVault 注入，日志脱敏。
私密数据输出	SnowLuma/output/groups/*/chat-record.md	群消息内容与群号属于隐私数据。	默认仅显示统计；正文查看需要权限与审计。
外部账号 OAuth	pixiVenera、Extractors-Playwright/pixiv_oauth_watch.py	Pixiv token、refresh token、OAuth code。	WebUI 不持久化 token；只显示字段存在性和 HTTP 状态。
ADB 控制	Scrcpy/*.ps1	连接真实设备、启动 App、保持唤醒。	需要用户输入 serial/IP；禁止后台无提示自动启动。
公开 Web 服务	Gallery、WebPages、docker/config/config.json	端口监听、Gallery 无内建认证、PiGallery2 可配置匿名访问。	默认绑定 localhost；公网访问前必须配置认证/反代/VPN。

11. 依赖检查设计

依赖	检查方式	关联脚本/目录	缺失时处理
PowerShell 7 / Windows PowerShell	Get-Command pwsh、$PSVersionTable	所有 .ps1	只显示不可运行原因。
项目 .venv	检查 .venv\Scripts\Activate.ps1	Extractors/*.py、Extractors-Playwright/pixiv_oauth_watch.py、MinecraftFriends/test.py	按 AGENTS.md 阻止 Python 脚本运行。
Node.js / npm	node --version、npm --version，检查 package.json	Gallery、pixiVenera/server、Extractors-Playwright、WebPages	不自动安装；提示进入对应目录手动安装。
git	git --version	Update-GitHubRepoFileTimestamp.ps1	缺失时阻止。
GitHub CLI gh	gh --version	Get-GitHubReleaseAsset*.ps1	缺失或未登录时显示登录状态。
7-Zip 7z	Get-Command 7z	Update‑ArchiveFileTimestamp.ps1、WindowsISOs/test.ps1	缺失时阻止解析/时间戳脚本。
ExifTool	检查 D:\Tools\ExifTool\exiftool.exe 或 PATH	Test-Photos/*.ps1	显示固定路径缺失。
ffmpeg / ffprobe	Get-Command ffmpeg、ffprobe	Gallery/js/server/thumbnail.js、Gallery/js/utils/media.js	缩略图/视频信息能力降级。
aria2c	检查 D:\Tools\aria2\aria2c.exe	HyperOS/Update-HyperOS.ps1	只允许版本检测，不允许下载。
KernelSU CLI / magiskboot	检查 D:\Tools\KernelSU CLI\ksud.exe、magiskboot.exe	HyperOS/patchboot.ps1	阻止 patchboot。
adb / scrcpy	检查 D:\Tools\Scrcpy\adb.exe、scrcpy.exe	Scrcpy/*.ps1	阻止 Android 控制页面运行。
curl.exe	Get-Command curl.exe	danbooru/*.ps1	缺失时阻止；即使存在也需凭据迁移。
Docker	docker --version、docker compose version	docker/docker-compose.yml	仅显示状态，不自动启动。
Edge / Edge Dev	检查固定安装路径	EdgeWorkspace/start.ps1、Extractors-Playwright/startedge.ps1	缺失时禁用启动。
Playwright	检查 Extractors-Playwright/package.json 和 node_modules/playwright	Fanbox/Pixiv OAuth 工具	不自动安装浏览器。
Windows 镜像能力	Get-Command Mount-DiskImage	WindowsISOs/test.ps1	非 Windows/权限不足时阻止。
端口占用	检查 8081、8082、25567、25570、25571、25572、3000	Gallery、pixiVenera、WebPages、NapCat/Danbooru	冲突时提示服务名和 PID。

12. 分阶段实施计划

阶段	目标	具体任务	验收标准
Phase 0：只读盘点与安全基线	建立当前仓库事实表，不运行脚本。	扫描 README.md、AGENTS.md、顶层目录、.ps1/.py/.js；排除 .git、node_modules、SnowLuma/output 正文、大型参考仓库深层内容；生成初始分类和风险标签；标记 .env 存在但不读取。	WebUI 或索引报告能列出至少根目录脚本、Test-Photos、HyperOS、Scrcpy、Extractors-Playwright、NapCat、SnowLuma、danbooru；不产生任何脚本执行记录。
Phase 1：脚本库与详情页	做出可浏览的 WebUI 骨架。	实现侧边栏、脚本表格、目录树、搜索、脚本详情只读预览；展示风险命中行、依赖、固定路径、可能输出文件。	能打开 HyperOS/Update-HyperOS.ps1、SnowLuma/test-msg-history.ps1、Test-Photos/Test-PhotoInfo.ps1、Gallery/server.js 的详情页，并看到正确分类和风险提示。
Phase 2：依赖检查	建立不安装依赖的检查页。	实现 PowerShell、Node、Python .venv、gh、git、7z、ExifTool、ffmpeg、aria2c、adb/scrcpy、Docker、Edge、端口占用检查。	缺失依赖显示“不可运行原因”；Python .venv 不存在时所有 Python 脚本被阻止。
Phase 3：低风险 Runner	只接入低风险只读脚本。	支持运行读取/查询类脚本，例如 WindowsISOs/hash.ps1 的哈希统计、Test-Photos/Test-PhotoInfo.ps1 这类生成报告脚本在白名单路径下运行；实现任务状态、退出码、超时。	运行任务能实时显示日志、结束后记录退出码；未分类脚本不能运行。
Phase 4：日志与实时输出	完成任务监控基础设施。	增加 SSE/WebSocket；保存原始/脱敏/结构化日志；实现 token/Basic Auth/URL query 脱敏；输出文件与任务关联。	Bearer ...、-u user:password、refresh_token 等在默认视图中被遮蔽；任务日志可搜索和下载。
Phase 5：专用解析页面	对现有输出做结构化 UI。	实现照片 CSV、NapCat/SnowLuma 统计、Fanbox metadata、HyperOS 版本、Gallery reindex、Windows ISO、Danbooru JSON 响应解析器。	至少 5 类真实输出能被解析为表格/统计；解析失败显示原始文件和错误。
Phase 6：中高风险审批流	允许部分高风险脚本在强约束下运行。	增加 dry-run、影响路径预览、二次确认、角色权限；将 Danbooru/NapCat token 迁移到 SecretVault；拆分 HyperOS 检测/下载/清理步骤。	danbooru/*.ps1 不再使用硬编码凭据运行；Update-HyperOS.ps1 清理旧文件前展示删除列表。
Phase 7：服务管理	管理长驻 Node/Docker 服务状态。	接入 Gallery/server.js、pixiVenera/server、WebPages/server*.js、docker/docker-compose.yml 的健康检查、端口、PID、启动/停止策略。	能看到 Gallery 8081、pixiVenera 8082、WebPages 端口状态；默认绑定本机，公网风险明确提示。
Phase 8：验收、文档和发布	将 WebUI 管理面板变成可维护工具。	补充 README、操作手册、风险规则说明、测试用例；若提交，按 AGENTS.md 使用 Conventional Commits 中文描述和 SSH 签名。	新用户能按文档完成只读索引、依赖检查、低风险脚本运行；测试覆盖安全策略、日志脱敏、解析器。

13. 每阶段任务清单

Phase 0：只读盘点与安全基线

• 建立顶层目录清单：AutoClicker、danbooru、docker、EdgeWorkspace、Extractors、Extractors-Playwright、Gallery、Gallery-Stable、gallery-dl、HyperOS、MinecraftFriends、NapCat、pixiVenera、Scrcpy、SnowLuma、Test-Photos、WebPages、WindowsISOs、XiaomiBackups、venera、pixez-flutter。
• 建立脚本索引：自定义 .ps1、关键 .py/.js、package.json、docker-compose.yml。
• 识别敏感区域：.env、SnowLuma/output、danbooru/*.ps1、NapCat/*.ps1、pixiVenera token 相关文件。
• 生成风险标签：只读、写文件、改名、删除、移动、系统设置、网络请求、凭据、设备控制、长驻服务。

Phase 1：脚本库与详情页

• 实现脚本列表字段：路径、分类、语言、大小、风险、依赖、是否可运行。
• 实现源码只读预览，高亮 Remove-Item、Move-Item、Rename-Item、Set-ItemProperty、Mount-DiskImage、Start-Process、Invoke-WebRequest、Invoke-RestMethod、curl.exe、fastboot、adb。
• 为 README_Gallery.md、README_pixiVenera.md、REPORT_pixiVenera_Gallery.md 做文档入口。
• 对 venera、pixez-flutter 标记“参考仓库，只读”。

Phase 2：依赖检查

• 编写依赖规则表，不执行安装命令。
• 检查固定路径：D:\Tools\ExifTool\exiftool.exe、D:\Tools\aria2\aria2c.exe、D:\Tools\KernelSU CLI\ksud.exe、D:\Tools\Scrcpy\scrcpy.exe、Edge/Edge Dev。
• 检查项目依赖：Gallery/package.json、Extractors-Playwright/package.json、pixiVenera/server/package.json。
• 检查端口：8081、8082、25567、25570、25571、25572、3000。

Phase 3：低风险 Runner

• 定义低风险白名单，不包含 Danbooru、NapCat/SnowLuma 私密输出、HyperOS boot patch、批量删除/改名脚本。
• 实现 PowerShell 子进程运行、超时、取消、退出码。
• 实现工作目录固定为脚本所在目录或仓库根目录。
• 记录任务 hash，避免脚本变更后历史混淆。

Phase 4：日志与实时输出

• 实现实时日志流。
• 实现脱敏规则：Bearer token、Basic Auth、Pixiv refresh/access token、URL query token、.env 值。
• 建立日志保留策略：原始日志短期、脱敏日志长期、审计日志长期。
• 将输出文件与任务关联。

Phase 5：专用解析页面

• 照片/视频 CSV 解析器。
• NapCat/SnowLuma 输出统计解析器。
• Fanbox metadata.json 和下载日志解析器。
• HyperOS ROM 更新表解析器。
• Gallery reindex 状态解析器。
• Windows ISO / Danbooru / AutoClicker 解析器。

Phase 6：中高风险审批流

• 每个高风险脚本增加“为什么危险”说明。
• 实现 dry-run 输出和真实运行分离。
• 实现删除/移动/重命名影响路径预览。
• 将 Danbooru/NapCat/Pixiv 相关凭据迁移为 SecretVault 注入。
• 所有高风险运行写入审计日志。

Phase 7：服务管理

• Gallery 服务状态检查：/api/scan-mode、/api/reindex-status。
• pixiVenera 服务状态检查：/api/ping、/pixiv-source.js、/pixiv-direct-source.js。
• WebPages 服务端口检查。
• Docker Compose 状态只读查看；启动/停止需要单独权限。

Phase 8：验收、文档和发布

• 编写 WebUI 使用文档、风险策略文档、依赖检查文档。
• 编写测试：索引、风险识别、依赖缺失、日志脱敏、解析器。
• 若需要提交，提交标题使用 feat(webui): 中文描述 或合适类型，正文列出变动文件并按 AGENTS.md SSH 签名。

14. 不应该做的事情

禁止事项	原因
不要把 .env、Bearer token、Basic Auth、Pixiv refresh/access token 显示在 WebUI 或日志里。	当前仓库存在本地敏感配置和历史 token 风险。
不要默认运行 danbooru/*.ps1、NapCat/*.ps1、SnowLuma/*.ps1。	脚本含凭据或会处理私密聊天数据。
不要让 WebUI 直接执行 fastboot flash 或任何刷机命令。	HyperOS/patchboot.ps1 涉及 boot 镜像和设备刷写风险。
不要在用户未确认前执行 Remove-Item、Move-Item、Rename-Item、Set-ItemProperty。	大量脚本会改名、删除、移动或改时间戳。
不要自动 npm install、安装 Playwright 浏览器、安装 Python 包或 Docker 镜像。	当前任务和未来安全策略都应避免自动改变环境。
不要把 Gallery、WebUI、pixiVenera、PiGallery2 直接暴露到公网。	Gallery 文档已指出自身无内建认证；PiGallery2 配置中认证也需要检查。
不要混用 Gallery 媒体服务器权限和 WebUI 脚本执行权限。	媒体浏览和脚本执行是不同信任边界。
不要默认扫描 SnowLuma/output/groups/*/chat-record.md 正文。	输出包含大量私密聊天内容，应按需、授权、审计读取。
不要把 venera、pixez-flutter 当作 WebUI 的运行目标。	它们是大型参考仓库，运行/构建成本和风险都不同。
不要假设所有硬编码路径都存在。	脚本中有 F:\Gallery、G:\Backups、E:\tgzs、D:\Tools、D:\uupdump 等本机路径。
不要绕过 AGENTS.md 的 Python .venv 规则。	Python 脚本必须在项目级虚拟环境中运行。

15. 后续可扩展方向

方向	说明
脚本元数据标准	为未来脚本增加可选 front matter 或旁路 manifest，声明用途、参数、风险、依赖、输出解析器。
调度器	支持定时运行低风险任务，例如 Gallery 增量索引、GitHub Release 检查、HyperOS 版本检测。
多主机 Agent	将 WebUI 与执行 Agent 分离，远程机器只暴露受限执行接口。
更强沙箱	用 Windows Job Object、低权限用户、容器或受限 PowerShell 会话隔离脚本。
变更预览引擎	对重命名、移动、删除、时间戳写入生成可审查 diff。
凭据轮换提醒	对 Danbooru/NapCat/Pixiv/Minecraft token 做过期提醒和泄漏扫描。
Gallery 深度集成	对 Gallery/js/utils/scan.js 的索引结果、缩略图缓存、搜索慢查询做可视化。
输出知识库	将 README_Gallery.md、README_pixiVenera.md、脚本说明和审计报告组合成可搜索知识库。
插件化解析器	每类脚本输出解析器独立注册，便于新增 Torrent/PNG/APK/JAR 等 README 待办方向。
移动端控制台	为 Scrcpy、AutoClicker、NapCat 统计等提供移动端只读监控页面。

17. 2026-06-12 实施记录

项目	结果
落地目录	PowerShellTools-WebUI/
后端	server.js + src/core.js，使用 Node.js 原生 HTTP，不引入额外 npm 依赖。
前端	public/index.html、public/styles.css、public/app.js，提供仪表盘、脚本库、依赖检查、任务监控、输出解析、服务状态、安全策略和文档入口。
安全策略	默认阻止未分类、高风险、含凭据、私密输出、设备控制、刷机、批量删除/移动/重命名脚本；仅低风险白名单 PowerShell 脚本可由 Runner 执行。
本地代理绕过	WebUI 启动时补齐 NO_PROXY/no_proxy，服务健康检查使用 127.0.0.1 和 Node 原生 HTTP 直连。
Runner	低风险 PowerShell Runner 支持任务 ID、脚本 hash、实时 SSE 日志、退出码、取消、超时、原始/脱敏日志和审计事件。
高风险处理	提供影响预览 API，不执行高风险脚本；预览包含破坏性命中、可能影响路径、dry-run 线索、所需凭据名称和审计要求。
输出解析	已接入照片/视频 CSV、SnowLuma 统计、Fanbox metadata、HyperOS、Gallery reindex、Windows ISO、Danbooru JSON、AutoClicker 配置解析器。
文档	新增 PowerShellTools-WebUI/README.md，根 README.md 增加入口，.gitignore 排除 WebUI 运行时数据。
验证	node --check PowerShellTools-WebUI\src\core.js、node --check PowerShellTools-WebUI\public\app.js、node PowerShellTools-WebUI\tests\run-tests.js 均通过。

16. 总体验收标准

验收项	标准
仓库理解	页面能准确引用当前存在的目录和脚本，例如 HyperOS/Update-HyperOS.ps1、Scrcpy/镜像屏幕.ps1、SnowLuma/test-msg-history.ps1、Gallery/server.js、pixiVenera/server/src/index.js。
安全默认值	未分类、高风险、含凭据、含私密输出的脚本默认不可运行。
依赖透明	缺少 .venv、ExifTool、7z、gh、Node、adb/scrcpy、ffmpeg 等时给出明确原因，不自动安装。
日志可追踪	每次运行都有任务 ID、开始结束时间、退出码、脱敏日志、输出文件引用。
输出可读	至少照片 CSV、NapCat/SnowLuma 统计、Fanbox metadata、HyperOS 更新、Gallery reindex 五类输出能结构化展示。
信任边界	WebUI 默认本机访问；脚本执行、媒体服务、Pixiv 代理、私密聊天数据各自有独立权限和提示。
合规提交	未来若提交实现，必须符合 AGENTS.md：Conventional Commits 中文描述、SSH 签名、Python .venv。