Imported from YohanJx/GrandleTick (AGENTS.md). Install upstream with npx skills add YohanJx/GrandleTick. Copyright stays with the author.

AGENTS

历史意图核查要求

• 分析、修改或删除既有代码前，必须先检查相关文件和逻辑的 Git 历史，确认该逻辑是何时、因为什么需求被新增、调整或删除，不能只根据当前代码或表面现象推断设计意图。
• 核查时应按实际需要使用 git log -- <file>、git log -S/-G、git show、git blame 等方式，至少定位引入该逻辑的提交，并阅读提交信息及相关差异。
• 如果历史记录表明某段代码承载用户明确添加的功能、兼容性策略、数据迁移规则或隐私权衡，除非用户明确要求改变该功能，否则不得以修复其他问题为由删除、弱化或替换它。
• 当新需求可能与历史功能冲突时，必须先向用户说明原功能意图、冲突点和可选方案；在未获得明确授权前，应保留原功能，只处理已授权的范围。
• 完成修改后，必须对照修改前的基线提交检查最终差异，确认没有意外带入对历史功能的新增、删减或语义改变。

代码编写要求

• 以后修改或新增代码时，必须为关键逻辑、非显而易见的分支、复杂数据转换和重要边界条件补充必要的中文注释。
• 注释应解释“为什么这样做”和“这段逻辑解决什么问题”，避免只重复代码表面含义。
• 简单赋值、明显的 UI 布局属性、常规函数调用等无需额外注释，避免制造噪音。

算法说明要求

涉及算法、复杂流程或多步骤业务逻辑时，必须在函数内部按执行阶段分块写中文序号注释。序号注释的作用是分隔过程块，而不是在函数顶部集中列一个步骤清单。

func rebuildReport() {
    // 1. 准备输入数据，过滤无效记录。
    let validLogs = logs.filter { !$0.isInvalid }

    // 2. 按业务规则计算中间结果。
    let summary = buildSummary(from: validLogs)

    // 3. 写回状态或返回最终结果。
    self.summary = summary
}

步骤编号必须使用 1. 2. 3. 这样的阿拉伯数字加英文句点格式，并放在对应代码块之前，让函数执行过程一段一段清晰可读。

提交要求

• 每实现完成一个功能后，必须自动创建 Git 提交并推送到远程仓库。
• 提交信息必须遵循 Conventional Commits 格式，并使用中文描述，例如：

feat: 添加活动统计筛选功能
fix: 修复窗口标题解析异常
refactor: 优化数据迁移流程

• 提交前应检查工作区变更，避免提交与当前功能无关的文件。

更新后安装要求

• 每次完成代码更新并验证后，必须运行 Scripts/build_and_install_release.sh。该脚本负责退出当前运行中的 GrandleTick、构建 Release、严格验签、完整覆盖安装到 /Applications/GrandleTick.app，然后启动新版应用。
• 禁止把签名失败的构建产物复制到 /Applications，禁止使用 CODE_SIGNING_ALLOWED=NO 绕过签名，也禁止只覆盖 .app 内部的可执行文件。
• 构建产物必须通过 codesign --verify --deep --strict，并确认 TeamIdentifier 为 7PDMGBAPNH 且不是 ad-hoc 签名；任一条件不满足时必须停止安装。
• Release 构建目录必须位于不受 File Provider 影响的系统临时目录，避免 FinderInfo、资源分叉等扩展属性导致开发者签名失败。