# XStats 仓库规则

## 技术栈（Tech Stack）

- macOS 客户端使用 Swift 6、AppKit 与 SwiftUI，包含 WidgetKit 扩展；目标为 macOS 14+、Apple Silicon（arm64）。
- `project.yml` 由 XcodeGen 生成 Xcode 工程；可测试模块位于 Swift Package `Packages/XStatsKit`，构建任务定义在 `Taskfile.yml`。
- 系统采集使用 IOKit / SMC；特权操作通过 `SMAppService` 注册的 XPC 辅助工具完成。本机历史和 AI 统计使用 SQLite，偏好设置使用 UserDefaults，凭据使用 Keychain。
- 在线更新使用 Sparkle 2.10.0 统一管理检查调度、跳过版本与安装，沿用 XStats 更新界面及系统通知开关；不得并存独立检查定时器或自动下载/安装。固定 XML API 合并安装统计并原样返回已签名清单，旧 JSON 协议继续兼容。发布前必须先部署双区域 XML 入口，验证同团队签名、公证与 Gatekeeper，并先上传已签名的版本 XML 和安装包再发布 JSON 清单。
- 日历使用 Tyme4Swift；更新检查服务位于 `server/api`，使用 Go、Fiber v3、GORM 和 SQLite。依赖版本以 `Packages/XStatsKit/Package.swift` 和 `server/api/go.mod` 为准，构建与发布步骤见 [DEVELOPMENT.md](DEVELOPMENT.md)。

## 架构与代码质量

- macOS 客户端优先使用系统原生框架和现有模块；引入新的运行时、跨平台 UI 层、依赖或抽象前，先说明当前需求为何不能由现有机制满足。此约束不排斥已有的 Go 服务和必要的第三方库。
- 新代码保持直接、可读：优先提前返回、清晰分支和有意义的局部变量，避免深层嵌套与层层转发的控制流。
- 尽量少写嵌套函数；仅在框架回调要求，或局部闭包明显比新增符号更简单时使用。
- 不要仅为缩短调用方，把只有一个调用点、又不表达稳定业务概念的逻辑抽成模块级辅助函数。可复用行为、接口或框架回调、导出 API、测试夹具，以及值得直接测试的复杂业务逻辑，可以独立成函数；保留单次使用的辅助函数时，名称应表达持久的领域概念，而不是机械步骤。

## 性能、资源与能耗

- 轻量、低资源占用和低能耗是常驻菜单栏应用的基本约束。新增功能和代码审查应同时考虑 CPU、内存、磁盘 I/O、网络请求与定时唤醒成本；不能以持续后台开销换取偶尔使用的便利。
- 监控采样沿用现有需求驱动机制，只采集当前展示、历史记录或已启用功能确实需要的数据。功能关闭、窗口关闭或最小化、锁屏及休眠时，按实际需求停止或降频；恢复时避免重复注册观察者、定时器或并发启动同一任务。
- 优先复用采样结果、事件通知和批量处理；确需轮询时采用满足体验的最低频率，为定时器设置合理容差并合并刷新。避免忙等、无退避重试、高频启动子进程和不可见界面的持续动画。
- 日志、目录、网络响应与历史数据采用有界读取和按需处理，避免每轮全量解码、排序或聚合未变化数据。缓存须有明确的大小或生命周期边界及失效条件，不常驻保存无必要的完整历史；不为推测中的性能问题预先增加缓存或并发层。
- 主线程仅承担必要的界面工作，耗时扫描、解析和阻塞 I/O 沿用项目现有后台执行机制。限制并发量，长任务在内部循环及阶段边界响应取消，取消后不发布过期或不完整的结果。
- SwiftUI 热路径保持低成本，列表使用稳定标识，避免在视图计算和布局回调中反复生成昂贵数据。几何测量与窗口尺寸调整不得形成同步反馈循环；状态无变化时避免无效重绘和重建视图。
- 性能验证与风险匹配：涉及采样、轮询、扫描、缓存、布局或动画的改动，应定向验证空闲、功能运行及关闭后的行为；涉及数据增长或资源释放时覆盖大数据量、重复开关或持续运行。性能优化尽可能在相同环境和负载下比较修改前后 CPU、内存、唤醒或 I/O，按需使用 `sample`、Instruments 等工具。构建和单元测试通过不能代替资源验证，未实测的能耗改善或长期稳定性必须明确说明。

## 国际化（i18n）

- 新增或修改用户可见文案时以简体中文为源文案，使用 `Packages/XStatsKit/Sources/Localization` 的 `tr(...)` 与现有翻译资源，同步补齐受影响语言的译文；不要只在某个视图中硬编码单一语言。系统名称、日志标识和协议字段不作为界面文案翻译。
- 日期、数字、单位使用当前应用语言对应的 Locale；检查长译文、动态文本及阿拉伯语从右到左布局，避免靠固定宽度或字符串拼接假定中文语序。相关界面改动至少验证受影响语言和布局。
- 业务行为测试优先校验状态、数值和错误语义，不对本地化提示写死中文断言，也不依赖开发机或 CI 的系统语言。曾出现卸载测试单独通过、完整测试失败：其他用例通过 `AppSettings.language` 切换了进程全局的 `L10n`，使中文提示变为译文。
- 翻译文案测试优先使用显式语言的翻译表；必须修改全局语言时，隔离所有受影响用例并恢复原状态，不能仅靠单个测试套件串行或临时切回中文避免并行干扰。涉及此类状态的测试修改须运行完整 `task test`，单例通过不足以确认隔离有效。

## 代码许可

- 本仓库自行编写的新增代码、测试及对上游代码的修改，采用 **AGPL-3.0-or-later**（GNU Affero General Public License 第 3 版或更新版本）。许可范围以 [LICENSING.md](LICENSING.md) 为准，完整许可见 [LICENSE](LICENSE)。
- 新建源码和测试文件在支持注释时标注 `SPDX-License-Identifier: AGPL-3.0-or-later`；脚本保留首行 shebang。不支持注释的文件在许可说明中记录，不破坏文件格式；文件头不写应用版本号或虚构邮箱。
- 修改上游或第三方文件时，保留原有版权与许可声明，明确区分 XStats 修改部分的授权；其他贡献者按真实归属署名，不机械改写已有年份，也不将上游原始代码声称为 AGPL 独占授权。
- OpenStats 原有 MIT 许可与版权声明保留在 [LICENSES/OpenStats-MIT.txt](LICENSES/OpenStats-MIT.txt)，其他第三方声明见 [ThirdPartyNotices.md](ThirdPartyNotices.md)。
- 引入第三方代码、依赖或素材时，核对许可兼容性并保留来源、版权及必要声明；不新增与本项目新增代码许可相冲突的默认 MIT 声明。
- 调整许可相关内容时，同步核对 LICENSE、LICENSING.md、第三方声明及四语言 README。不得声称本次许可变更撤销了历史版本已有的 MIT 授权。