millenium-helpers

# 千禧助手脚本 适用于 Linux 和 Windows 的跨平台实用脚本集，用于管理、修复、升级、回滚、查看日志、管理主题和调度更新（适用于客户端和皮肤）。 --- ## 目录 - [功能](#功能) - [安装和设置](#安装和设置) - [Linux/Unix 先决条件和设置](#linuxunix-先决条件和设置) - [Windows 先决条件和设置](#windows-先决条件和设置) - [管理命令](#管理命令) - [手动卸载/清理](#手动卸载清理) - [环境变量](#环境变量) - [统一配置文件](#统一配置文件) - [干燥运行模式](#干燥运行模式) - [Shell 自动补全](#shell-自动补全) - [脚本概述](#脚本概述) - [故障排除和常见问题](#故障排除和常见问题) - [安全设计](#安全设计) - [许可证](#许可证) --- ## 功能 - **跨平台支持**：Linux/Unix（Bash shell 脚本）和 Windows（PowerShell 脚本）功能对等。 - **自动安装和设置**：系统范围内安装助手工具并配置自动补全。 - **每日自动更新调度器**：配置用户级 `systemd` 计时器（Linux）或 **Windows 任务调度器** 任务（Windows），在后台每天运行更新。 - **安全设计**：利用 `/etc/sudoers.d/` 插入式配置（Linux）或 Windows UAC 提升保护措施（`sudo` / `Start-Process RunAs`）安全执行更新。 - **支持多个发布渠道**：轻松在 `stable` 和 `beta` 更新之间切换。 - **修复实用程序**：所有权修正、缓存清除和主题刷新，从存储库元数据中。 - **诊断工具**：彻底的健康检查、版本验证、自我修复机制和更新状态分析。 --- ## 安装和设置 ### Linux/Unix 先决条件和设置 #### 先决条件 这些脚本需要标准的 Linux shell 实用程序： - `curl`、`tar`、`awk`、`sha256sum`、`unzip`（用于下载和验证） - `sudo` 和 `visudo`（用于提升检查） - `systemd` 或 `cron`（用于后台调度） #### 系统范围安装 克隆此存储库并运行安装程序。安装程序启动一个**交互式配置向导**，指导您选择更新渠道（稳定版或测试版）、后台更新配置和可选的 GitHub 个人访问令牌（PAT）设置： ```bash sudo ./install.sh ``` 如果您更喜欢非交互式安装，请传递特定子命令： ```bash sudo ./install.sh install ``` #### 启用每日自动更新计时器 始终以**普通用户**（不带 `sudo`）运行调度命令，以便 systemd 在您自己的用户会话空间中配置后台计时器： ```bash millennium-schedule enable [stable|beta] ``` --- ### Windows 先决条件和设置 #### 先决条件 这些脚本需要 Windows PowerShell： - PowerShell 5.1+（Windows 10/11 内置）或 PowerShell Core 7+。 - 执行策略必须允许脚本执行： ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` #### 安装和设置（Windows） 克隆此存储库，打开 PowerShell 终端并运行安装脚本： ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\windows\install.ps1 ``` 此安装程序将： 1. 将所有助手脚本复制到 `$HOME/.millennium-helpers/bin`。 2. 为所有脚本生成 `.cmd` 包装器（以便您可以在任何命令 shell 或终端中直接键入 `millennium-diag` 或 `millennium-upgrade` 运行命令）。 3. 将 bin 目录添加到您的用户 `PATH` 环境变量中。 安装后，运行交互式配置向导配置后台更新调度和更新渠道： ```powershell millennium-schedule setup ``` 要卸载助手脚本并清理环境： ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\windows\install.ps1 -Uninstall ``` --- ## 管理命令 ### 检查诊断和健康状态 ```bash # Linux millennium-diag # Windows millennium-diag ``` ### 运行医生（自动修复和自我更新） 扫描您的设置是否有任何损坏的钩子、缺失的目录、停止的计时器或过时的助手脚本，并自动修复/自我更新它们： ```bash # Linux millennium-diag doctor [--force] # Windows millennium-diag doctor ``` （或别名 `millennium-diag --fix` 或 `millennium-diag -f`） 使用 `--force` 选项强制运行所有修复、权限调整和完成文件更新，即使系统报告健康。 ### 检查更新调度器状态 ```bash # Linux millennium-schedule status # Windows millennium-schedule status ``` ### 禁用自动更新计时器 ```bash # Linux millennium-schedule disable # Windows millennium-schedule disable ``` ### 修复千禧安装 ```bash # Linux sudo millennium-repair # Windows（以管理员身份运行） millennium-repair ``` ### 从 Steam 中清除/注销千禧客户端 ```bash # Linux sudo millennium-purge # Windows（以管理员身份运行） millennium-purge ``` ### 卸载所有助手脚本（Linux） 自动删除二进制文件、systemd 计时器、sudoers 规则和 shell 补全： ```bash sudo ./install.sh uninstall ``` ### 手动卸载/清理（Linux） 如果您更喜欢手动删除所有文件和配置，请执行以下命令： 1. **禁用和删除每日更新 systemd 用户计时器**： ```bash systemctl --user disable --now millennium-update.timer systemctl --user stop millennium-update.service rm -f ${XDG_CONFIG_HOME:-~/.config}/systemd/user/millennium-update.timer \ ${XDG_CONFIG_HOME:-~/.config}/systemd/user/millennium-update.service systemctl --user daemon-reload ``` 2. **从 `/usr/local/bin` 删除脚本二进制文件**： ```bash sudo rm -f /usr/local/bin/millennium-repair \ /usr/local/bin/millennium-upgrade \ /usr/local/bin/millennium-schedule \ /usr/local/bin/millennium-purge \ /usr/local/bin/millennium-diag \ /usr/local/bin/millennium-theme \ /usr/local/bin/millennium-mcp ``` 3. **删除无密码 sudoers 规则**： ```bash sudo rm -f /etc/sudoers.d/millennium-helpers ``` 4. **删除 shell 自动补全配置**： ```bash # Bash 补全和符号链接 sudo rm -f /usr/share/bash-completion/completions/millennium-helpers \ /usr/share/bash-completion/completions/millennium-repair \ /usr/share/bash-completion/completions/millennium-upgrade \ /usr/share/bash-completion/completions/millennium-schedule \ /usr/share/bash-completion/completions/millennium-purge \ /usr/share/bash-completion/completions/millennium-diag \ /usr/share/bash-completion/completions/millennium-theme \ /usr/share/bash-completion/completions/millennium-mcp # Zsh 补全和符号链接 sudo rm -f /usr/share/zsh/site-functions/_millennium-helpers \ /usr/share/zsh/site-functions/_millennium-repair \ /usr/share/zsh/site-functions/_millennium-upgrade \ /usr/share/zsh/site-functions/_millennium-schedule \ /usr/share/zsh/site-functions/_millennium-purge \ /usr/share/zsh/site-functions/_millennium-diag \ /usr/share/zsh/site-functions/_millennium-theme \ /usr/share/zsh/site-functions/_millennium-mcp # Fish 补全 sudo rm -f /usr/share/fish/vendor_completions.d/millennium-repair.fish \ /usr/share/fish/vendor_completions.d/millennium-upgrade.fish \ /usr/share/fish/vendor_completions.d/millennium-schedule.fish \ /usr/share/fish/vendor_completions.d/millennium-purge.fish \ /usr/share/fish/vendor_completions.d/millennium-diag.fish \ /usr/share/fish/vendor_completions.d/millennium-theme.fish # Nushell 补全 sudo rm -f /usr/share/nushell/completions/millennium-helpers.nu \ /usr/local/share/nushell/completions/millennium-helpers.nu ``` --- ## 环境变量 助手脚本尊重以下环境变量（如果定义）： | 变量 | 描述 | | --- | --- | | `GITHUB_TOKEN` | 可选。用于身份验证 API 请求的 GitHub 个人访问令牌（PAT）。建议频繁更新时定义以防止触发 GitHub 速率限制。 | | `XDG_CONFIG_HOME` | 可选。动态解析以定位用户配置文件。默认为 Linux 上的 `~/.config`。 | | `LOCALAPPDATA` | 在 Windows 上用于定位用户配置文件路径 (`%LOCALAPPDATA%\millennium-helpers`)。 | --- ## 统一配置文件 代替管理环境变量，配置可以存储在统一的 JSON 文件中： * **Linux**：`${XDG_CONFIG_HOME:-~/.config}/millennium-helpers/config.json` * **Windows**：`%LOCALAPPDATA%\millennium-helpers\config.json` 配置文件由交互式设置向导自动生成，格式如下： ```json { "update_channel": "stable", "github_token": "your_github_token_here", "backup_limit": 5 } ``` *注意：配置文件权限会自动限制为所有者可读/写入 (`600`) 以确保安全。* --- ## 干燥运行模式 所有脚本都支持干燥运行模式 (`--dry-run` 或 `-d`) 以预览文件复制、配置生成、权限修复和调度器任务注册，而不修改系统状态： ```bash # Linux ./install.sh --dry-run millennium-upgrade --channel stable --dry-run millennium-repair --dry-run # Windows millennium-upgrade -Channel stable -DryRun millennium-diag doctor -DryRun ``` --- ## Shell 自动补全（Linux） 安装程序自动部署 shell 自动补全配置： - **Bash**：复制到 `/usr/share/bash-completion/completions/`（支持所有脚本自动加载）。 - **Zsh**：复制到 `/usr/share/zsh/site-functions/`（自动加载；需要在 `~/.zshrc` 中使用 `compinit`）。 - **Fish**：复制到 `/usr/share/fish/vendor_completions.d/`。 - **Nushell**：复制到 `/usr/share/nushell/completions/` 或 `/usr/local/share/nushell/completions/`。 --- ## 脚本概述 ### 1. [install.sh](install.sh) 主安装程序。它将所有助手脚本复制到 `/usr/local/bin`，将权限设置为 `755`（普通用户只读，所有者拥有），并自动配置 `/etc/sudoers.d/millennium-helpers` 以无密码执行更新程序。 ### 2. [scripts/millennium-repair.sh](scripts/millennium-repair.sh) / `millennium-repair.ps1` 修复 Steam 主题或设置面板的问题。纠正目录权限、刷新 CEF 缓存，并使用最新 git 提交刷新活动主题。 ### 3. [scripts/millennium-upgrade.sh](scripts/millennium-upgrade.sh) / `millennium-upgrade.ps1` 下载、校验和安装最新稳定版或测试版的千禧系统范围。 - **智能绕过**：读取当前版本信息，跳过重新安装如果已经是最新的。 - **强制重新安装**：使用 `-f` 或 `--force` 重新安装，无论版本如何。 - **回滚支持**：立即回滚到以前安装的客户端版本。 ### 4. [scripts/millennium-schedule.sh](scripts/millennium-schedule.sh) / `millennium-schedule.ps1` 管理每日更新计时器和触发器（Linux 上的 `systemd` 用户计时器，Windows 上的 **Windows 任务调度器** 任务）。 ### 5. [scripts/millennium-purge.sh](scripts/millennium-purge.sh) / `millennium-purge.ps1` 从所有本地 Steam 用户注销千禧，并完全清除其文件和目录。 ### 6. [scripts/millennium-diag.sh](scripts/millennium-diag.sh) / `millennium-diag.ps1` 运行综合系统健康检查（报告 Steam 运行状态、安装的千禧版本、配置和权限）。 ### 7. [scripts/millennium-theme.sh](scripts/millennium-theme.sh) / `millennium-theme.ps1` 皮肤/主题管理器 CLI。允许列出主题、从 GitHub 安装皮肤仓库、检查更新和删除皮肤目录。 ### 8. [scripts/millennium-mcp.py](scripts/millennium-mcp.py) (`millennium-mcp`) 模型上下文协议（MCP）服务器。将整个千禧助手脚本套件作为原生 AI 工具公开给编码助手（如 Claude Desktop、Cursor、Windsurf 或 Antigravity），允许它们动态运行诊断、管理主题、应用修复和执行升级。 #### 公开的 MCP 工具 | 工具名称 | 描述 | 参数 | | --- | --- | --- | | `millennium_diag` | 运行只读诊断或应用医生模式下的自动修复。 | `doctor`（布尔值，可选）：设置为 `true` 以自动修复。 | | `millennium_theme` | 管理主题/皮肤目录（列出、安装、删除、更新）。 | `action`（字符串，必填）：`list`、`install`、`remove`、`update`。<br> `theme`（字符串，可选）：仓库或名称。<br> `all`（布尔值，可选）：更新所有主题。 | | `millennium_upgrade` | 系统范围升级千禧客户端。 | `channel`（字符串，可选）：`stable`（默认）或 `beta`。 | | `millennium_schedule` | 管理后台自动更新计时器。 | `action`（字符串，必填）：`enable`、`disable`、`status`。<br> `channel`（字符串，可选）：`stable` 或 `beta`。<br> `cron`（布尔值，可选）：强制 crontab（仅限 Linux）。 | | `millennium_repair` | 运行系统范围的权限和符号链接修复。 | 无。 | | `millennium_purge` | 完全卸载所有千禧客户端钩子和文件。 | 无。 | #### 自动注册 要自动将 `millennium-mcp` 服务器与已安装的 AI 工具（Claude Desktop 和 Windsurf）注册，请运行： ```bash millennium-mcp --register ``` 这会检测 Claude Desktop 和 Windsurf 的配置文件文件夹，更新或创建 JSON 配置文件，并自动添加 `millennium-helpers` 服务器。 #### 配置示例 要在 AI 助手中使用这些工具，请将 `millennium-mcp` 添加到您的配置文件： **Claude Desktop**： * **Linux**：`~/.config/Claude/claude_desktop_config.json` * **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "millennium-helpers": { "command": "millennium-mcp" } } } ``` **Cursor / Windsurf**： 前往设置 -> 功能 -> MCP，单击 **+ 添加新的 MCP 服务器**，并配置： - **名称**：`millennium-helpers` - **类型**：`command` - **命令**：`millennium-mcp` --- ## 故障排除和常见问题 ### Steam 升级千禧后显示空白/黑色屏幕 通常由过时的 CEF 缓存文件引起。运行修复实用程序修复本地权限并清除 Steam 的 htmlcache： ```bash # Linux sudo millennium-repair # Windows millennium-repair ``` ### 背景计时器未运行更新 1. 检查计时器状态： ```bash millennium-schedule status ``` 2. 验证无密码 sudo（Linux）或调度任务（Windows）是否正确配置。 3. 如果您想在 Linux 上更新，即使您已退出会话，请启用用户延迟： ```bash loginctl enable-linger $USER ``` --- ## 安全设计 允许后台用户级计时器运行更新时修改系统目录，更新程序脚本必须以提升的权限运行。 此设置安全地实现此目的： 1. **Sudoers 自动配置（Linux）**：在 `sudo ./install.sh` 期间，安装程序检测原始调用用户 (`SUDO_USER`) 并自动配置 Linux 上的安全插入文件 `/etc/sudoers.d/millennium-helpers`。 2. **受保护的脚本**：助手脚本复制到 `/usr/local/bin/`，所有者为 `root:root`，权限为 `755`，意味着普通用户无法编辑或篡改它们。 3. **任务调度器（Windows）**：使用原生 Windows 任务调度器安全边界注册调度任务。 --- ## Arch Linux 的打包（AUR） 如果您使用 Arch Linux，您可以使用提供的 PKGBUILD 配方在 [packaging/](file:///home/panda/dev/millenium-helpers/packaging/) 目录中的提供的 PKGBUILD 配方原生打包和安装助手脚本： - **`millennium-helpers-git`**：解析依赖项、将所有可执行文件安装到 `/usr/bin/`、设置补全并为 `%wheel` 组部署无密码 sudoers 更新规则。 要本地构建和安装软件包： ```bash cd packaging makepkg -si ``` --- ## 许可证 本项目根据 MIT 许可证 - 请参阅 [LICENSE](LICENSE) 文件了解详情。