edit | blame | history | raw

Apptag 7.0 Smart Start Project Plan

1. 项目目标

Smart Start 是 Apptag 7.0 的核心升级方向。

它要解决的不是“用户不会启动 App”,而是:

用户第一次使用 Apptag 时,不想从零开始创建标签、理解分类、手动拖动几十个 App。

目标体验:

  1. 用户第一次打开 Apptag。
  2. Apptag 扫描本机 App。
  3. Apptag 在本地自动整理大部分常见 App。
  4. 用户看到一个简单结果:已经整理多少个 App、创建了哪些分类、还有哪些未分类。
  5. 用户可以继续编辑、撤销,或者未来选择 AI Improve 进一步优化。

2. 产品原则

Local First

第一版必须默认本地完成,不依赖服务器、不上传用户数据、不需要用户注册。

原因:

  • 首次体验更快。
  • 没有 AI 成本。
  • 隐私和 App Store 压力最低。
  • 离线也能工作。
  • 实现风险更可控。

Draft First

所有智能分类都先生成“分类草案”,再决定是否应用。

对于全新用户,可以自动应用高置信度结果,但仍要显示摘要和撤销入口。

对于已有用户,默认只展示预览,不静默覆盖现有分类。

Undo First

任何自动整理动作都必须可撤销。

应用分类前要保留备份快照,至少支持一次撤销。

Stable IDs

内部分类必须使用稳定 ID,例如:

browser
communication
development
design
utilities
system

显示给用户时再本地化为:

浏览器
沟通
开发
设计
工具
系统

不要用中文、英文或其他界面显示名称作为内部身份。

3. 推荐总体方案

采用方案三:

本地分类库 + 本地规则 + 可选云端 AI Improve

第一层:本地分类库

内置一个常见 Mac App 分类表。

主匹配字段:

bundleIdentifier

辅助匹配字段:

App 名称
安装路径类型

例子:

{
  "bundleIdentifier": "com.figma.Desktop",
  "names": ["Figma"],
  "categoryID": "design",
  "confidence": 0.98
}

第二层:本地启发式规则

用于处理没有进入分类库、但很容易判断的 App。

例子:

/System/Applications/* -> system
Xcode / VS Code / Terminal / GitHub Desktop -> development 或 utilities
Safari / Chrome / Firefox / Edge -> browser
Music / VLC / Spotify -> media

本地规则的置信度低于精确 bundleIdentifier 匹配。

第三层:AI Improve

后续版本再做,不作为第一版依赖。

用户主动点击 AI Improve 后,才上传最小必要信息到服务器。

AI 返回的也必须是草案,不直接覆盖本地数据。

4. 第一版范围

第一版必须做

  • 定义稳定分类 ID。
  • 创建本地分类库 JSON。
  • 先内置一批常见 App 规则,不追求完整。
  • 实现本地分类引擎。
  • 生成统一的 SmartCategorizationDraft
  • 判断用户是否是“全新用户”。
  • 对全新用户自动应用高置信度分类。
  • 对已有用户只给预览入口,不静默覆盖。
  • 应用前创建备份。
  • 应用后显示摘要。
  • 支持撤销。

第一版暂时不做

  • 不做服务器。
  • 不做 AI Improve。
  • 不做远程规则更新。
  • 不做账号系统。
  • 不上传用户 App 列表。
  • 不重写整个数据存储 schema。
  • 不追求一次覆盖所有冷门 App。

5. 技术模块规划

建议新增目录:

Apptag/SmartCategorization/

建议文件:

SmartCategoryCatalog.json
SmartCategory.swift
SmartCategoryCatalog.swift
SmartCategorizationDraft.swift
SmartCategorizer.swift
SmartStartCoordinator.swift
TagBackupService.swift
SmartStartSummaryView.swift

SmartCategory.swift

负责定义稳定分类 ID 和默认显示信息。

核心内容:

SmartCategoryID
SmartCategoryDefinition
默认分类顺序
分类颜色建议
本地化 key

SmartCategoryCatalog.json

内置常见 App 分类表。

第一版可以先从 80-150 个高频 App 开始,验证机制跑通后再扩到 300-800。

SmartCategoryCatalog.swift

负责读取、校验、查询分类库。

能力:

按 bundleIdentifier 查询
按 normalized app name 查询
校验重复项
校验 categoryID 是否存在

SmartCategorizationDraft.swift

定义统一草案结构。

本地 Smart Start 和未来 AI Improve 都输出这个结构。

核心字段:

source
tags
tagOrder
assignments
unassigned
warnings
confidence

SmartCategorizer.swift

核心分类引擎。

输入:

[AppInfo]
当前 TagDatabase.Store

输出:

SmartCategorizationDraft

匹配顺序:

  1. 精确 bundleIdentifier 匹配。
  2. App 名称匹配。
  3. 安装路径和系统规则。
  4. 关键词规则。
  5. 无法判断则进入 unassigned。

SmartStartCoordinator.swift

负责流程控制。

它不负责具体 UI,也不负责底层分类判断。

能力:

判断是否需要首次 Smart Start
生成草案
决定是否自动应用
调用备份
调用 TagDatabase 保存
生成摘要
记录 Smart Start 已执行

TagBackupService.swift

负责应用智能分类前备份现有数据。

第一版可以做轻量备份:

读取当前 TagDatabase.Store
保存到内存作为 undo snapshot
可选保存到本地 backup json

后续再升级成完整备份历史。

SmartStartSummaryView.swift

负责结果摘要 UI。

显示:

已整理 App 数
已创建分类
未分类 App 数
撤销按钮
继续编辑按钮
未来 AI Improve 入口

6. 实施阶段

Phase 0: 合同和安全边界

目标:

先定义数据结构和应用规则,避免后面边做边猜。

任务:

  • 定义 SmartCategoryID
  • 定义默认分类列表。
  • 定义 SmartCategorizationDraft
  • 定义自动应用条件。
  • 定义已有用户保护规则。
  • 定义撤销策略。

验收标准:

  • 能在代码里表达分类草案。
  • 不接入 UI 也能构造一个合法草案。
  • 文档明确什么情况可以自动应用,什么情况必须预览。

Phase 1: 本地分类库 MVP

目标:

跑通本地分类库机制。

任务:

  • 新增 SmartCategoryCatalog.json
  • 先录入 80-150 个常见 App。
  • 实现 catalog loader。
  • 实现 bundleIdentifier 匹配。
  • 加入 catalog 校验逻辑。

验收标准:

  • 给定一组 AppInfo,能匹配出已知 App 的分类。
  • JSON 格式错误时不会让 App 崩溃。
  • 重复 bundle id 或未知 category id 能被发现。

Phase 2: 本地分类引擎

目标:

生成完整 Smart Start 草案。

任务:

  • 实现 SmartCategorizer
  • 加入名称匹配。
  • 加入路径规则。
  • 加入关键词规则。
  • 未命中 App 进入 unassigned
  • 为每个 assignment 标记 confidencereason

验收标准:

  • 同一批 App 输入,每次输出稳定。
  • 高置信度分类和低置信度分类可区分。
  • 不改变任何真实用户数据,只生成 draft。

Phase 3: 应用草案、备份、撤销

目标:

让本地草案安全地落到现有 TagDatabase.Store

任务:

  • 实现 TagBackupService
  • 实现 draft -> existing store 的转换。
  • 创建缺失标签。
  • 写入 tagOrder
  • 写入 appTags
  • 不删除用户现有标签。
  • 不覆盖已有用户分类,除非用户明确选择。
  • 支持撤销到应用前状态。

验收标准:

  • 应用前能创建备份。
  • 应用后可以撤销。
  • 已有用户数据不会被静默覆盖。
  • bash build.sh 通过。

Phase 4: 首次启动 Smart Start 流程

目标:

把 Smart Start 接入真实首次使用体验。

任务:

  • 判断用户是否已有标签数据。
  • 首次扫描完成后生成 Smart Start 草案。
  • 全新用户自动应用高置信度结果。
  • 记录 smartStartCompleted
  • 显示整理结果摘要。
  • 给用户继续编辑和撤销入口。

验收标准:

  • 新用户首次打开能看到已整理结果。
  • 已经使用过的用户不会被自动改动。
  • 用户可以撤销自动整理。
  • 用户关闭摘要后不会每次重复弹出。

Phase 5: 预览体验

目标:

让已有用户可以安全尝试 Smart Start。

任务:

  • CategorizationPlanPreviewView 或轻量 preview。
  • 展示即将创建的分类。
  • 展示每个分类下将加入的 App 数。
  • 展示未分类 App。
  • 提供 Apply / Cancel。

验收标准:

  • 已有用户能先看再应用。
  • 用户可以只应用缺失分类,不强制替换旧布局。

Phase 6: Catalog 扩展和质量控制

目标:

提高命中率。

任务:

  • 把 catalog 扩展到 300-800 个 App。
  • 覆盖中英文常见 App。
  • 覆盖 Apple 系统 App。
  • 覆盖浏览器、开发、设计、办公、媒体、沟通、工具。
  • 建立人工 review 表。

验收标准:

  • 一台普通办公/创作 Mac 上,常见 App 命中率明显高于空白初始化。
  • 分类结果基本符合直觉。
  • 没有明显错误分类的高频 App。

Phase 6A: 候选 App 数据源研究

目标:

建立一个高覆盖的常见 Mac App 候选库,不追求“全球真实使用量绝对排名”,而追求对 Smart Start 有用的高概率覆盖。

数据源分层:

  1. Homebrew Cask 安装统计。
  • 价值:真实安装量,适合开发、AI、效率、工具类 App。
  • 偏差:技术用户占比高。
  1. Mac App Store 排行榜。
  • 价值:覆盖普通用户、消费类、免费和付费 App。
  • 偏差:缺少大量官网下载/企业分发 App。
  1. 设计师图标包和 macOS 图标库。
  • 价值:反映哪些 App 在设计师和重度 Mac 用户心中“足够常见、足够高可见”,值得专门画图标。
  • 可用来源:macOSicons、Replacicon 使用的图标源、DarkOS、Glacier Icons、Adam's MacOS Icons 等。
  • 额外价值:部分图标库自带 category、downloads 或显式分组,可以帮助我们推断默认分类。
  • 偏差:偏审美/重度用户,不能单独当成使用量排名。
  1. Curated Mac app lists。
  • 价值:补充编辑推荐和专业工作流。
  • 偏差:主观性强。
  1. 人工补充区域性高频 App。
  • 价值:补齐中国、日本、韩国、欧洲等地区常见 App。
  • 偏差:需要人工 review。

候选库字段:

name
normalizedName
bundleIdentifier
categoryCandidates
sources
sourceRanks
iconPackMentions
iconDownloads
regionHints
confidence
reviewStatus
notes

合并策略:

  • 多个来源都出现的 App 优先级最高。
  • Homebrew 高排名 + 图标包高覆盖,优先进入第一版 catalog。
  • Mac App Store 高排名但 Homebrew 不出现,仍要纳入普通用户覆盖。
  • 图标包出现但没有排名数据,作为“值得人工 review”的候选。
  • 中国/亚洲高频 App 即使全球英文榜不高,也要人工加入。

Phase 7: AI Improve 预研

目标:

为后续云端增强预留接口,不阻塞本地 MVP。

任务:

  • 复用 SmartCategorizationDraft
  • 设计 AICategorizationClient 接口,但可以先不实现网络。
  • 定义上传字段。
  • 定义隐私文案。
  • 定义服务端返回 schema。

验收标准:

  • 本地 Smart Start 和未来 AI Improve 使用同一种草案结构。
  • 加 AI 时不需要推翻本地架构。

7. 自动应用规则

可以自动应用

满足全部条件时可以自动应用:

  • 用户没有明显现有分类数据。
  • Smart Start 从未执行过。
  • assignment 置信度达到阈值,例如 >= 0.85
  • 分类来自 bundleIdentifier 精确匹配或强规则。
  • 应用前已创建 backup snapshot。

必须预览,不自动应用

出现任一情况时必须预览:

  • 用户已有自定义标签。
  • 用户已有 appTags。
  • assignment 置信度较低。
  • 分类来自模糊名称或关键词。
  • 需要替换或删除现有分类。

8. 初始分类建议

第一版稳定分类 ID:

browser
communication
productivity
development
design
writing
media
utilities
system
entertainment
finance
education
ai-tools
security
other

可以先不做太细。分类越细,越容易错。

宁可第一版分类少而准。

9. 风险清单

风险 1:分类不符合用户习惯

缓解:

  • 用宽分类。
  • 支持撤销。
  • 支持手动编辑。
  • 不对已有用户自动覆盖。

风险 2:本地 catalog 覆盖不够

缓解:

  • 先覆盖高频 App。
  • 未命中就保留未分类,不强行猜。
  • 后续持续扩展 catalog。

风险 3:现有数据结构用 tag name 做身份

缓解:

  • Smart Start 内部先用 stable category ID。
  • 应用到旧 store 时再映射为本地化或默认显示名。
  • 后续 store v2 再彻底迁移到 stable tag IDs。

风险 4:首次体验等待过久

缓解:

  • 分类逻辑必须轻量。
  • 不在 first-run 调用云端。
  • 分类库加载只做一次。
  • UI 显示明确进度和结果。

风险 5:用户不信任自动整理

缓解:

  • 显示摘要。
  • 显示撤销。
  • 不隐藏未分类。
  • 不说“AI 已经替你决定”,而说“已为你准备一个初始整理方案”。

10. 验收指标

第一版 Smart Start 可以用这些指标判断是否成功:

  • 全新用户首次启动后,不再看到完全空白/混乱的分类状态。
  • 常见 App 能被自动放入合理分类。
  • 用户能一键撤销。
  • 现有用户不会被静默改动。
  • 没有云端依赖。
  • 构建通过。
  • 分类库格式错误不会导致 App 崩溃。

11. 推荐下一步

下一步不要先做 UI。

最合理的第一项开发任务是:

任务 3:建立 Smart Start 数据合同

具体内容:

  1. 新建 Apptag/SmartCategorization/
  2. 新建 SmartCategory.swift
  3. 定义 SmartCategoryID 和默认分类。
  4. 新建 SmartCategorizationDraft.swift
  5. 定义 draft 数据结构。
  6. 保证 bash build.sh 通过。

这一步完成后,Architect 可以审查分类身份是否稳定,Designer 可以围绕 draft 设计预览体验,Coder 可以继续做本地 catalog loader。