# StarTrace

**Repository Path**: wzFeel/star-trace

## Basic Information

- **Project Name**: StarTrace
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 星迹 · StarTrace

简体中文 | [English](README.md)

<img src="tools/LocalMetricsBar/assets/StarTrace-logo.png" alt="星迹彗星" width="120">

原生 Windows 11 任务栏指标小组件，采用“上方名称、下方数据”的自适应布局与条件触发的彗星粒子效果。C++17 / Win32，无需安装 Rainmeter 或 TrafficMonitor。

[GitHub](https://github.com/wzf-cn/StarTrace) · [Gitee 镜像](https://gitee.com/wzFeel/star-trace) · [GitHub 安装包](https://github.com/wzf-cn/StarTrace/releases) · [Gitee 安装包](https://gitee.com/wzFeel/star-trace/releases)

## 示例与动画

![合成数据展示示例](docs/images/startrace-preview.png)

![使用实际彗星引擎生成的动画](docs/images/startrace-demo.gif)

上图数值**全部虚构**，由项目实际布局与彗星引擎离屏渲染，不是桌面截图或真实账号信息。GIF 为便于观察而循环；程序默认仅在相关指标突变时触发。实际显示取决于任务栏可用空隙，窄屏可能比这个宽幅演示少显示几列。

| 示例 | 含义 |
| --- | --- |
| `codex / 68%` | 使用者账号返回的剩余配额，不是已使用比例 |
| `Points / 12000` | 接口提供的账号积分；缺失时为 `--`，不是 API 美元余额 |
| `24h / 23%` | 第三方预测概率，不代表已确认的重置时间 |
| `Uses / 2` | 可用总次数；有临期时显示 `1/2`，分子红色加粗 |
| `Reset / 02-06:30` | 重置倒计时：2 天 6 小时 30 分钟 |
| `C / 480G`、`D / 6.1T` | 各盘剩余空间，不是吞吐量或已用/总空间 |

中文模式分别显示“积分、24h预测、次数、重置、上传、下载”等名称，英文模式如图。

### 动画规则

- **条件触发（默认）：** 有效突变触发一次，冷却 30 秒；启动不预演，没有随机间歇或定时循环。
- **连续演示：** 连续飞行以检查效果；**关闭：** 不显示彗星。
- 彗星左下飞入，在右侧列附近的组件内部掉头，再由左上飞出。掉头时头部保持在上下及右侧边界内。飞行 8 秒，尾部最多再消散 1.4 秒。
- 色彩微动和临期呼吸可单独设置。7 日内到期的次数以红色加粗分子显示；不足 24 小时且开启呼吸时平滑呼吸。无临期时显示“次数”与总数。

| 触发来源 | 阈值 |
| --- | --- |
| 同一网卡上传或下载 | 变化至少 1 MB/s，且变化比至少 2 倍 |
| 同一 GPU 占用率 | 变化至少 20 个百分点 |
| 可用重置次数 | 次数增加，不是仅积分增加 |
| 24h 或 6h 预测 | 变化至少 10 个百分点 |

初始或缺失数据不会触发。参见[动画引擎](tools/LocalMetricsBar/MetricsBarCore.cpp)及[合成演示程序](docs/demo/RenderDemo.cpp)。

## 功能

- CPU、内存、逐个 GPU 占用率、上传/下载速度，以及固定磁盘和移动存储逐盘剩余空间。仅过滤**总容量**低于 1 GB 的盘。十进制单位：G 为 10⁹ 字节，T 为 10¹² 字节。
- 可选 Codex 剩余配额、重置倒计时 `dd-hh:mm`、可用/临期重置次数与积分。需要使用者自己安装并登录 Codex CLI，不携带或迁移账号凭据。
- 可选 LunarWerx 的 24 小时和近期重置概率；属于第三方统计估计，不是官方重置安排，可能不可用。
- 中英文切换、逐项显示与配色、低对比度保护、色彩微动、临期呼吸，以及关闭/条件触发/连续演示三种彗星模式。
- 保留分组并按优先级压缩：Codex > 积分 > 24h 预测 > RTX > CPU > 次数 > 重置 > 流量；其他 GPU、内存、磁盘和近期预测优先级较低。
- 可选登录启动；点击展示非模态详情，无悬停提示。彗星左下飞入，在组件内掉头，从左上飞出。

## 安装与设置

发行文件提供中文 `zh-CN` 和英文 `en` 两个 x64 安装包，内部是**相同程序**，区别为安装界面和首次启动语言。两者更新同一个安装位置，不是两个并行程序。

安装包**未进行代码签名**，运行前核对 SHA256，不要关闭系统安全功能。升级、安装或卸载前退出星迹。按当前用户安装，不强制结束资源管理器，不修改 Windows 搜索或天气设置。

点击托盘彗星图标（也可能位于隐藏图标区），或右键组件选择“设置”。选择语言并应用后，任务栏标签、菜单和新开的详情立即切换；关闭再打开设置窗口以切换控件文字。已有明确语言设置优先于安装包首次默认语言。

Codex 账号数据和第三方预测**默认关闭**，可在设置中分别启用。硬件指标无需联网。积分到期日可留空或填写 `YYYY-MM-DD`，仅为手动元数据，不能视为 API 确认的到期日。登录启动默认关闭。

### 获取使用者自己的 Codex 数据

安装并登录自己的 Windows 原生 Codex CLI（`codex login`），在设置中启用 Codex 账号数据，再刷新。星迹启动本地 Codex app-server，读取当前账号返回的配额和积分字段；不会提供共享账号或共享余额，无需向星迹粘贴 API 密钥。当前仅自动寻找 Codex 桌面的 `codex.exe` 路径或 PATH 中的 `codex.exe`；只有 WSL 安装或 `codex.cmd` 包装脚本时可能无法发现。账号或接口未提供的字段保持 `--`。提交问题时不要上传个人配置、登录文件或真实账号详情截图。

配置保存在 `%LOCALAPPDATA%\LocalMetricsBar\settings.ini`。为了兼容旧版本，保留 `LocalMetricsBar.exe` 文件名及内部标识。卸载保留用户配置和文件，需要时由用户自行清理。

## 适用范围和限制

- 安装包支持 Windows 11 x64，不支持 ARM64 或 Windows 10；运行无需开发工具。
- 通过 Win32 子窗口和 UI Automation 嵌入任务栏，**不是 Windows 官方稳定扩展接口**。系统更新、替代任务栏、缩放和布局可能影响显示。当前定位主显示器横向任务栏，天气右侧、居中开始按钮左侧的空隙；没有足够空隙时指标条可能不显示，托盘和设置入口仍保留。
- GPU 数据来自 Windows 性能计数器，不包含温度或功耗；驱动、权限、远程会话等可能影响数据。网络指标是网卡流量，不是测速结果。
- 外部数据约每五分钟刷新。失败时保留上次有效值，并在详情提示；关闭来源后清空对应显示。已经开始的请求可能在关闭后完成，但其结果不会重新显示。
- Codex app-server 的路径/协议及预测接口可能变化。本项目与 OpenAI、Microsoft、LunarWerx 无隶属或背书关系。
- 项目提供原生布局、控件、资源和隔离安装生命周期自动测试，不等于所有系统版本、开机登录或笔记本布局均已验证，请在目标设备验收。

## 构建与测试

安装 Visual Studio 或 Build Tools 的“使用 C++ 的桌面开发”工作负载及 Windows SDK。脚本自动寻找工具链，或使用已初始化的开发者终端。必须保留完整源码树，应用会编译两个 provider 目录中的源码，不依赖插件 DLL。

```powershell
$taskPath = 'C:\temp\codex\startrace-build-your-task'
New-Item -ItemType Directory -Path $taskPath
$env:LOCAL_METRICS_BUILD_DIR = "$taskPath\build"
$env:TEMP = $taskPath
$env:TMP = $taskPath
.\tools\LocalMetricsBar\test.cmd
.\tools\LocalMetricsBar\build.cmd
```

打包需要 Inno Setup 6（本次使用 6.7.3）及官方简体中文语言文件：

```powershell
.\tools\LocalMetricsBar\package.ps1 -TaskRoot $taskPath -CompilerPath 'C:\path\to\ISCC.exe' -ChineseLanguageFile 'C:\path\to\ChineseSimplified.isl'
.\tools\LocalMetricsBar\InstallerTests.ps1 -TaskRoot "$taskPath\zh-CN" -PayloadDir "$taskPath\zh-CN\payload"
.\tools\LocalMetricsBar\InstallerTests.ps1 -TaskRoot "$taskPath\en" -PayloadDir "$taskPath\en\payload" -Language en
```

两个语言的安装测试必须**顺序执行**，因为共享隔离测试身份；不会覆盖正式安装或启动测试程序。测试安装版本号 1.0.0/1.0.1 仅用于验证升级过程，载荷仍是当前程序，不是历史版本。完成正式交付与验证、确认无进程占用后，仅清理自己创建的临时子目录。

## 发布到 GitHub / Gitee

GitHub 与 Gitee 提供相同的公开源码。发行附件应包括中英文安装包、源码 ZIP 和 SHA256 校验清单，请选择附件齐全的版本下载。此仓库由干净源码导出并建立独立历史。**不要**上传个人工作区、账号、配置、验收日志或原工作区 Git 历史。演示数值为合成数据，`docs/demo` 提供可复现的离屏渲染方法，不收集账号或硬件数据。

阅读 [隐私说明](PRIVACY.md)、[安全说明](SECURITY.md)、[更新记录](CHANGELOG.md) 和 [MIT 许可证](LICENSE)。

## 许可证与素材

项目原创代码与随附彗星素材按 MIT 提供。主图与托盘图由 AI 图像工具生成，并组装成不同尺寸图标；没有捆绑第三方皮肤。AI 素材不保证独占权或商标注册资格。Windows 字体、图标、API 与第三方服务不因本项目而被重新授权或分发。