| | |
|---|
| | | # Taglauncher 代码治理与 Git 规范 |
|---|
| | | |
|---|
| | | 本文档是 `/Users/ar/Projects/Taglauncher` 的代码管理、Git 使用、交付和 Agent 协作规范。根目录 `AGENTS.md` 是强制入口；本文件是完整执行标准。 |
|---|
| | | 本文档是 `/Users/ar/Projects/Taglauncher/03-O` 的代码管理、Git 使用、交付和 Agent 协作规范。根目录 `AGENTS.md` 是强制入口；本文件是完整执行标准。 |
|---|
| | | |
|---|
| | | ## 1. 项目边界 |
|---|
| | | |
|---|
| | | - 主仓库工作区固定为 `/Users/ar/Projects/Taglauncher`。 |
|---|
| | | - 唯一源码根目录固定为 `/Users/ar/Projects/Taglauncher/src`。 |
|---|
| | | - App 源码、构建脚本、QA 脚本、SmartStart/Apple catalog 资料、发布资料都必须在 `src/` 下维护。 |
|---|
| | | - 主仓库工作区固定为 `/Users/ar/Projects/Taglauncher/03-O`。 |
|---|
| | | - 唯一源码根目录固定为 `/Users/ar/Projects/Taglauncher/03-O/C1.source`。 |
|---|
| | | - App 源码、构建脚本、QA 脚本、SmartStart/Apple catalog 资料都必须在 `C1.source/` 下维护；发布证据进入 `K3.运营与发布资料/Release/`，当前迁入构建包进入 `C2.builds/`。 |
|---|
| | | - 项目根目录只保留仓库入口文档、公开网站资料、治理规范和非源码管理说明。 |
|---|
| | | - 不允许再创建或继续使用 `/Users/ar/Projects/Taglauncher-*source`、`/Users/ar/Projects/Apptag-*` 等外部源码目录。 |
|---|
| | | - 不允许再创建或继续使用 `/Users/ar/Projects/Taglauncher/03-O-*source`、`/Users/ar/Projects/Apptag-*` 等外部源码目录。 |
|---|
| | | |
|---|
| | | ## 2. Git 工作区规则 |
|---|
| | | |
|---|
| | | - 开始任何代码、文档、发布或迁移任务前，必须先执行并检查： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | git status --short 2>&1 | head -c 6000 |
|---|
| | | git branch --show-current 2>&1 | head -c 2000 |
|---|
| | | git worktree list --porcelain 2>&1 | head -c 6000 |
|---|
| | | git status --short |
|---|
| | | git branch --show-current |
|---|
| | | git worktree list --porcelain |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | - 如果工作区已有改动，必须区分改动来源： |
|---|
| | |
|---|
| | | - 提交前必须确认： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | git status --short 2>&1 | head -c 6000 |
|---|
| | | git diff --stat 2>&1 | head -c 6000 |
|---|
| | | git diff --cached --stat 2>&1 | head -c 6000 |
|---|
| | | git status --short |
|---|
| | | git diff --stat |
|---|
| | | git diff --cached --stat |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | - 提交信息使用简洁英文或项目已有风格，示例： |
|---|
| | |
|---|
| | | git tag -a pre-src-migration-main-YYYYMMDD.HHMM -m "Pre src migration main" |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | - tag、`Info.plist`、`CHANGELOG.md`、`Release/` 资料、最终安装包文件名和 build 编号必须一致。 |
|---|
| | | - tag、`Info.plist`、`CHANGELOG.md`、发布资料、最终安装包文件名和 build 编号必须一致。 |
|---|
| | | - 生成 App Store 发布资料时，App Store Connect 的 What's New 不得只依据目标版本 release scope 或目标版本 changelog 小节。必须先确认当前 App Store 线上版本或当前待替换版本，并从 `CHANGELOG.md` 提取当前商店版本之后到目标版本之间的累计用户可感知变更。 |
|---|
| | | - 每个 App Store release checklist 必须包含可勾选的 What's New 累计变更门禁：当前商店基线版本、目标版本、累计 changelog 范围、中间版本用户可感知变更、排除原因，以及中英文 What's New 用户审核结果。 |
|---|
| | | |
|---|
| | | ## 6. Worktree 使用规则 |
|---|
| | | |
|---|
| | |
|---|
| | | - 对应分支。 |
|---|
| | | - 预计生命周期。 |
|---|
| | | - 清理条件。 |
|---|
| | | - worktree 不得放在 `/Users/ar/Projects/Taglauncher-*source` 或 `/Users/ar/Projects/Apptag-*` 这类容易被误认为正式源码根目录的位置。 |
|---|
| | | - worktree 不得放在 `/Users/ar/Projects/Taglauncher/03-O-*source` 或 `/Users/ar/Projects/Apptag-*` 这类容易被误认为正式源码根目录的位置。 |
|---|
| | | - 任务完成后必须执行： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | git worktree remove WORKTREE_PATH 2>&1 | head -c 6000 |
|---|
| | | git worktree prune 2>&1 | head -c 6000 |
|---|
| | | git worktree list --porcelain 2>&1 | head -c 6000 |
|---|
| | | git worktree remove WORKTREE_PATH |
|---|
| | | git worktree prune |
|---|
| | | git worktree list --porcelain |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | - 如果 worktree 有未提交改动，禁止直接删除；必须先确认归属和处理方式。 |
|---|
| | |
|---|
| | | ## 7. 构建产物与敏感文件 |
|---|
| | | |
|---|
| | | - `build/`、临时安装包、编译缓存、用户本地数据、钥匙串资料、p12 证书、provisioning profile 默认不进源码提交。 |
|---|
| | | - 只有明确作为 release archive 的产物，才可放入 `src/Release/.../Archive/`，并必须配套说明、hash、版本和 QA 证据。 |
|---|
| | | - 只有明确作为 release archive 的产物，才可放入 `C2.builds/.../Archive/`，并必须在 `K3.运营与发布资料/Release/...` 配套说明、hash、版本和 QA 证据。 |
|---|
| | | - 证书目录只作为本地敏感资料管理，不作为源码迁移内容。 |
|---|
| | | - 不允许把真实用户数据、隐私资料、账号凭证或本地配置写入 Git。 |
|---|
| | | |
|---|
| | |
|---|
| | | 接手旧线程、长期任务、发布任务或迁移任务时，必须先完成以下检查，不得等待旧线程： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | git status --short 2>&1 | head -c 6000 |
|---|
| | | git branch --show-current 2>&1 | head -c 2000 |
|---|
| | | git log --oneline --decorate --graph --max-count=12 2>&1 | head -c 6000 |
|---|
| | | git worktree list --porcelain 2>&1 | head -c 6000 |
|---|
| | | git status --short |
|---|
| | | git branch --show-current |
|---|
| | | git log --oneline --decorate --graph --max-count=12 |
|---|
| | | git worktree list --porcelain |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | - 必须读取最近会话记录，确认未完成项、已完成项、阻塞项和用户最新指令。 |
|---|
| | |
|---|
| | | - 迁移、发布、构建任务必须记录可复核证据：版本/build、执行命令、关键结果、产物路径、hash 或 QA 报告。 |
|---|
| | | - QA 失败不能只口头解释；必须判断是产品回归、脚本断言问题、环境问题还是迁移无关问题，并记录结论。 |
|---|
| | | |
|---|
| | | ## 10. 命令输出保护 |
|---|
| | | ## 10. UI Preview Gate |
|---|
| | | |
|---|
| | | 任何未知或可能很大的命令输出都必须 byte-cap： |
|---|
| | | TagLauncher 的 UI 工作必须先确认视觉目标，再修改生产 SwiftUI / AppKit 源码。经验复盘见： |
|---|
| | | |
|---|
| | | `/Users/ar/Projects/Taglauncher/03-O/K2.项目管理/KM2.项目管理-经验门禁/关于TagLauncher所有UI类问题的经验与教训.md` |
|---|
| | | |
|---|
| | | ### 10.1 触发范围 |
|---|
| | | |
|---|
| | | 以下变更默认属于非平凡 UI 改动，必须先过本门禁： |
|---|
| | | |
|---|
| | | - AppGrid、Settings、Theme、Pro、Quick Search、usage tips、弹窗、窗口尺寸、菜单栏、hover bubble、拖拽、点击热区或可访问性变化。 |
|---|
| | | - 布局、字号、字重、行高、间距、颜色、主题 token、material、阴影、图标、文案长度、状态提示或空态变化。 |
|---|
| | | - 会影响截图、录屏、App Store 展示、发布说明、QA 截图 smoke 或用户验收观感的变化。 |
|---|
| | | |
|---|
| | | 纯只读调查、日志定位、静态文本检索或不接触生产 UI 源码的 throwaway 原型，可以暂不进入完整门禁，但必须明确“不修改生产 UI 源码”。 |
|---|
| | | |
|---|
| | | ### 10.2 UI 合约 |
|---|
| | | |
|---|
| | | 非平凡 UI 改动开工前必须先写 UI 合约。推荐模板： |
|---|
| | | |
|---|
| | | `/Users/ar/Projects/Taglauncher/03-O/K2.项目管理/KM2.项目管理-经验门禁/UI合约模板.md` |
|---|
| | | |
|---|
| | | 如果当前任务已有 PRD、TODO、Round 文档或 issue，也可以在该文档中写入同等字段，不强制复制模板。UI 合约至少包含： |
|---|
| | | |
|---|
| | | - 目标界面：目标截图、标注、Penpot / Figma frame、baoyu-design HTML / 静态 screen，或等价可审阅预览。 |
|---|
| | | - 影响 surface：具体窗口、tab、弹窗、AppGrid 区域、Quick Search 区域、tips、Pro 入口或 release screenshot。 |
|---|
| | | - 不做范围：本轮明确不改的视觉、交互、文案、数据、状态和旧行为。 |
|---|
| | | - 状态矩阵：free / Pro / legacy Pro / preview / expired / purchase pending / cancel / fail / restore fail 等相关状态。 |
|---|
| | | - 主题和语言长度矩阵：默认、黑色、深蓝、亮色、暗色炫彩、亮色炫彩，以及长语种、长标签、长备注、价格、倒计时等文本压力。 |
|---|
| | | - 交互互斥关系：tips vs 图标点击、hover scroll vs hover bubble、sorting vs empty drop、Quick Search only vs AppGrid tips、modal vs backdrop dismiss、theme preview vs persistent theme、Pro preview vs real Pro state。 |
|---|
| | | - 验收证据：需要产出的真实 App 截图、录屏、AX 读取、真实鼠标点击 / hover / 拖拽 / 滚动证据，以及对应保存路径。 |
|---|
| | | |
|---|
| | | ### 10.3 高保真预览与用户确认 |
|---|
| | | |
|---|
| | | - 非纯调查任务必须先产出高保真预览，再进入生产 UI 源码修改。 |
|---|
| | | - 高保真预览可以来自 baoyu-design HTML / 静态 screen、Penpot / Figma frame、用户标注图、真实 App 参考截图或等价可审阅 artifact。 |
|---|
| | | - Agent 可以先产出 2-3 个候选预览；候选未被用户确认前，只能标记为 preview / candidate / experiment。 |
|---|
| | | - 用户确认视觉目标后，才允许修改 SwiftUI / AppKit 生产源码；确认范围只覆盖被确认的 surface、状态和不做范围。 |
|---|
| | | - 如果为了验证可行性需要写 throwaway 原型，必须放在非生产路径并注明不可直接发布；不得把实验代码混入正式 App 源码。 |
|---|
| | | |
|---|
| | | ### 10.4 实现与视觉验收 |
|---|
| | | |
|---|
| | | - 实现必须保护 UI 合约的不做范围，不得借 UI 修复顺手重写已验收视觉、交互或文案。 |
|---|
| | | - 静态 QA、构建通过、脚本 PASS 只能证明静态条件，不等于视觉通过。 |
|---|
| | | - 视觉 PASS 必须有真实渲染或真实交互证据：真实 App 截图、录屏、AX 窗口 / 控件读取、真实点击、hover、拖拽、滚动或 Esc / 外部点击证据。 |
|---|
| | | - 缺少哪类证据就如实记录缺口；不得用静态 QA 替代截图、录屏、AX 或真实点击证据。 |
|---|
| | | - 用户判定视觉倒退时，必须保留失败结论；失败候选不得进入正式发布候选，不得写成防回退 QA。 |
|---|
| | | |
|---|
| | | ## 11. 命令输出保护 |
|---|
| | | |
|---|
| | | 任何未知或可能很大的命令输出都必须控制范围。规则、CODEGRAPH、交接材料和标准验证命令必须保留原始可执行形式，不能为了展示输出而追加 `head -c`、`2>&1 | head` 等截断管道。执行时通过工具输出上限控制展示，或把完整输出写入日志文件并保留原始命令退出码。 |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | COMMAND 2>&1 | head -c 6000 |
|---|
| | | COMMAND |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | - 构建、测试、目录遍历、日志、Git diff、搜索结果都应限制输出。 |
|---|
| | | - 构建、测试、目录遍历、日志、Git diff、搜索结果都应控制展示范围。 |
|---|
| | | - 搜索优先用 `rg` / `rg --files`。 |
|---|
| | | - 不无上限打印大文件、构建日志、目录树或二进制信息。 |
|---|
| | | - 不无上限打印大文件、构建日志、目录树或二进制信息；需要压缩展示时由执行工具限制输出，不把截断管道写进标准命令。 |
|---|
| | | |
|---|
| | | ## 11. 禁止事项 |
|---|
| | | ## 12. 禁止事项 |
|---|
| | | |
|---|
| | | - 禁止在 `src/` 外新增 App 源码副本。 |
|---|
| | | - 禁止在 `C1.source/` 外新增 App 源码副本。 |
|---|
| | | - 禁止用外部目录长期承载源码开发。 |
|---|
| | | - 禁止在不看 `git status` 的情况下提交、合并、发布或清理。 |
|---|
| | | - 禁止擅自回滚用户改动。 |
|---|
| | | - 禁止把证书、账号、用户数据、临时 build 缓存提交进 Git。 |
|---|
| | | - 禁止把阶段性通过当成整体完成；仍有明确未完成项时必须继续推进。 |
|---|
| | | - 禁止没有 QA 证据就声称可交付。 |
|---|
| | | - 禁止非平凡 UI 改动跳过 UI 合约、高保真预览、用户视觉确认或真实渲染 / 交互证据。 |
|---|
| | | |
|---|
| | | ## 12. 常用检查命令 |
|---|
| | | ## 13. 常用检查命令 |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | git status --short 2>&1 | head -c 6000 |
|---|
| | | git branch --show-current 2>&1 | head -c 2000 |
|---|
| | | git log --oneline --decorate --graph --max-count=12 2>&1 | head -c 6000 |
|---|
| | | git worktree list --porcelain 2>&1 | head -c 6000 |
|---|
| | | git diff --stat 2>&1 | head -c 6000 |
|---|
| | | git diff --cached --stat 2>&1 | head -c 6000 |
|---|
| | | git ls-files src 2>&1 | wc -l | head -c 2000 |
|---|
| | | git status --short |
|---|
| | | git branch --show-current |
|---|
| | | git log --oneline --decorate --graph --max-count=12 |
|---|
| | | git worktree list --porcelain |
|---|
| | | git diff --stat |
|---|
| | | git diff --cached --stat |
|---|
| | | git ls-files C1.source | wc -l |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | 从源码根目录运行 QA： |
|---|
| | | |
|---|
| | | ```bash |
|---|
| | | cd /Users/ar/Projects/Taglauncher/src |
|---|
| | | bash Scripts/apple_default_apps_resource_qa.sh 2>&1 | head -c 12000 |
|---|
| | | bash Scripts/apple_default_note_policy_qa.sh 2>&1 | head -c 12000 |
|---|
| | | bash Scripts/smartstart_catalog_resource_qa.sh 2>&1 | head -c 12000 |
|---|
| | | bash Scripts/quick_search_app_name_qa.sh 2>&1 | head -c 12000 |
|---|
| | | bash Scripts/quick_search_system_app_qa.sh 2>&1 | head -c 12000 |
|---|
| | | cd /Users/ar/Projects/Taglauncher/03-O/C1.source |
|---|
| | | bash Scripts/apple_default_apps_resource_qa.sh |
|---|
| | | bash Scripts/apple_default_note_policy_qa.sh |
|---|
| | | bash Scripts/smartstart_catalog_resource_qa.sh |
|---|
| | | bash Scripts/quick_search_app_name_qa.sh |
|---|
| | | bash Scripts/quick_search_system_app_qa.sh |
|---|
| | | ``` |
|---|
