# TagLauncher 7.5 产品需求文档：快速建议

状态：产品与架构评审草案  
负责人：产品经理 / 架构师  
功能：快速建议  
所属能力：快速搜索  
版本：7.5  

## 1. 产品目标

快速建议是快速搜索在空查询状态下显示的默认建议列表。

当用户打开快速搜索，但还没有输入任何内容时，TagLauncher 不应该展示完整应用列表，也不应该显示空白界面，而应该主动给出一组“此刻最可能想打开的应用”。

快速建议的目标是：

- 让快速搜索一打开就有可操作对象。
- 帮用户快速重复打开最近使用的应用。
- 帮用户快速进入高频应用。
- 在不输入任何字符的情况下，也能通过 `Enter` 直接打开最可能的应用。
- 保持快速搜索作为“快速启动入口”的产品气质，而不是退化成另一个应用列表。

一句话定义：

```text
快速建议 = 用户还没输入时，TagLauncher 对“你现在可能想打开什么”的本地预测。
```

## 2. 产品定位

快速搜索有两个状态：

| 状态 | 用户输入 | 产品行为 |
|---|---|---|
| 快速建议 | 查询为空 | 显示推荐应用 |
| 搜索结果 | 查询不为空 | 显示匹配应用 |

快速建议不是搜索结果，也不是完整应用目录。

它的定位是：

```text
打开即建议。
默认可回车。
少量、高质量、动态变化。
```

快速建议的生成原则是：

```text
近期优先，频率兜底，当前上下文轻微加权。
```

## 3. 已确认的产品规则

### 3.1 不显示列表标题

快速建议列表上方不显示“快速建议”“最近使用”“推荐应用”等标题。

快速搜索输入框下方直接显示建议列表。这样可以保持接近 Spotlight / Raycast 的快速感，避免界面变成列表页或管理页。

### 3.2 固定最多显示 6 个建议

快速建议最多显示 6 个应用。

规则：

- 建议数量上限固定为 6 个。
- 不做 5 到 8 个的自适应数量。
- 不足 6 个时显示实际数量。
- 不为了凑满 6 个而显示低质量、随机或无意义的应用。
- 不显示完整应用目录。

### 3.3 默认显示一行备注

每个建议项默认显示应用备注，但只显示一行。

展示优先级：

1. 应用图标。
2. 应用名称。
3. 一行应用备注。
4. 如果没有备注，则显示标签信息。
5. 如果备注和标签都没有，则只显示应用名称。

备注过长时：

- 只显示一行。
- 超出部分截断。
- 不撑高建议项。
- 不影响列表整体高度。

### 3.4 冷启动复用 Smart Start 分类

新用户或历史不足的用户进入冷启动模式。

冷启动触发条件：

```text
通过 TagLauncher 成功启动应用的总次数少于 3 次
或
通过 TagLauncher 成功启动过的不同应用少于 3 个
```

冷启动时，快速建议优先展示本机已安装且属于高价值分类的应用。

高价值分类顺序：

```text
浏览器 > 沟通 > AI 工具 > 开发 > 效率 > 设计 > 系统工具
```

冷启动候选来源：

1. 当前标签上下文中的应用，如果用户是从某个标签视图进入快速搜索。
2. 本机已安装且命中 Smart Start 高价值分类的应用。
3. 本机已安装的常见高价值应用。
4. 应用名称字母排序兜底。

冷启动不允许随机。

### 3.5 7.5 不支持用户手动固定建议项

7.5 不提供用户手动固定快速建议项的功能。

不做的内容：

- 不做固定按钮。
- 不做取消固定。
- 不做右键固定菜单。
- 不做固定建议项设置页。

可以预留的数据和架构能力：

- 数据模型可以预留 `isPinned` 字段。
- 排序服务可以预留固定加权入口。
- 7.5 的用户界面不暴露固定操作。

### 3.6 使用明确的本地排序公式

7.5 使用简单、可解释、可测试的本地评分模型。

排序公式：

```text
总分 =
最近启动分
+ 高频启动分
+ 当前标签加权分
+ 冷启动分
```

核心约束：

```text
最近启动分 > 高频启动分 > 当前标签加权分
```

也就是说：

- 最近启动是最强信号。
- 高频启动用于兜底长期习惯。
- 当前标签只做轻微加权，不能变成过滤条件。
- 冷启动分只在用户历史不足时明显生效。

## 4. 用户故事

1. 作为用户，我打开快速搜索后，即使不输入，也能看到几个可能想打开的应用。
2. 作为用户，我可以直接按 `Enter` 打开默认选中的第一个建议。
3. 作为用户，我可以用 `↑` / `↓` 在建议列表中移动选择。
4. 作为用户，我最近通过 TagLauncher 打开过的应用，会优先出现在建议里。
5. 作为用户，我经常打开的应用，即使今天还没打开，也有机会出现在建议里。
6. 作为用户，如果我从某个标签上下文里打开快速搜索，相关应用可以更容易出现，但快速建议仍然不局限于当前标签。
7. 作为新用户，我没有足够启动历史时，仍然能看到一组合理的常见应用建议。

## 5. 入口行为

当快速搜索被打开时：

- 如果查询为空，显示快速建议。
- 第一个建议项默认被选中。
- 用户按 `Enter`，打开当前选中的建议应用。
- 用户开始输入任意字符后，快速建议切换为搜索结果。
- 用户删除所有输入，使查询再次为空时，重新显示快速建议。

状态流：

```text
打开快速搜索
        ↓
查询为空
        ↓
显示快速建议
        ↓
用户输入
        ↓
显示搜索结果
        ↓
用户清空输入
        ↓
重新显示快速建议
```

## 6. 展示要求

快速建议显示在快速搜索输入框下方。

列表规则：

- 不显示列表标题。
- 最多显示 6 个建议。
- 第一个建议默认选中。
- 每个建议项高度稳定，不因备注长短变化而跳动。
- 建议列表需要紧凑、可扫读、可键盘操作。
- 不显示几十个应用。
- 不把快速建议做成浏览页面。

每个建议项至少包含：

- 应用图标。
- 应用名称。

每个建议项推荐包含：

- 一行应用备注。
- 如果没有备注，则显示标签信息。

展示优先级：

```text
应用图标 + 应用名称 + 一行备注
应用图标 + 应用名称 + 标签信息
应用图标 + 应用名称
```

如果没有任何可用建议：

- 显示轻量空状态。
- 输入框继续保持聚焦。
- `Enter` 不执行任何操作。
- 不显示错误态。

空状态文案：

```text
输入应用、标签或备注开始搜索
```

## 7. 排序信号

### 7.1 最近启动分

最近启动是快速建议的第一优先级。

数据来源：

- 仅使用 TagLauncher 自己记录的启动历史。
- 不读取 macOS 全局应用使用记录。
- 不依赖系统隐私敏感数据。

最近启动分规则：

| 最近成功启动时间 | 分数 |
|---|---:|
| 10 分钟内 | 100 |
| 1 小时内 | 80 |
| 今天内 | 60 |
| 7 天内 | 40 |
| 30 天内 | 20 |
| 30 天以前或从未启动 | 0 |

规则说明：

- 最近刚通过 TagLauncher 启动的应用应该明显靠前。
- 同一个应用只出现一次。
- 如果应用启动失败，不更新最近启动时间。

### 7.2 高频启动分

高频启动用于补充“最近启动”的不足。

原因：

- 用户每天都用的应用，即使今天还没打开，也应该有机会出现。
- 只按最近启动排序会导致列表过于短期化。

高频启动分规则：

```text
高频启动分 =
min(过去 7 天成功启动次数 × 4, 24)
+ min(过去 30 天成功启动次数 × 1, 20)
```

分数上限：

```text
高频启动分最高 44 分
```

规则说明：

- 过去 7 天启动次数反映近期习惯。
- 过去 30 天启动次数反映稳定习惯。
- 高频分不能压过强最近分。
- 如果应用启动失败，不增加启动次数。

### 7.3 当前标签加权分

如果用户是在主界面的某个标签上下文中打开快速搜索，则当前标签下的应用获得轻微加权。

当前标签加权分：

```text
属于当前标签：+12 分
不属于当前标签：+0 分
```

重要规则：

- 当前上下文只加权，不过滤。
- 快速建议仍然可以显示其他标签下的应用。
- 快速搜索始终是全局启动入口。

错误行为：

```text
当前标签是“设计”，所以快速建议只显示设计类应用。
```

正确行为：

```text
当前标签是“设计”，所以设计类应用获得 12 分加权。
Chrome、Cursor、ChatGPT 等高意图应用仍然可以出现。
```

### 7.4 冷启动分

冷启动分只在冷启动模式下启用。

冷启动触发条件：

```text
通过 TagLauncher 成功启动应用的总次数少于 3 次
或
通过 TagLauncher 成功启动过的不同应用少于 3 个
```

冷启动分类分：

| Smart Start 分类 | 分数 |
|---|---:|
| 浏览器 | 50 |
| 沟通 | 45 |
| AI 工具 | 42 |
| 开发 | 40 |
| 效率 | 36 |
| 设计 | 32 |
| 系统工具 | 25 |
| 其他分类 | 0 |

规则说明：

- 一个应用属于多个分类时，取最高分类分。
- 冷启动分只用于历史不足的用户。
- 当用户积累足够启动历史后，冷启动分不再参与排序。
- 冷启动候选必须是本机已安装应用。
- 冷启动不允许随机推荐。

### 7.5 固定项加权入口

7.5 不启用用户手动固定功能。

实现上可以预留：

```text
固定项加权分 = 0
```

未来如果支持固定项，可以在不重写排序架构的情况下加入固定加权。

## 8. 最终排序规则

每个候选应用计算一次总分：

```text
总分 =
最近启动分
+ 高频启动分
+ 当前标签加权分
+ 冷启动分
```

排序规则：

1. 总分高的排前面。
2. 总分相同时，最近启动时间更近的排前面。
3. 最近启动时间也相同时，过去 7 天启动次数更多的排前面。
4. 仍然相同时，应用名称按当前语言环境排序。

候选去重规则：

1. 优先按 `bundleIdentifier` 去重。
2. 没有 `bundleIdentifier` 时按稳定应用标识去重。
3. 仍无法判断时按规范化后的应用名称兜底去重。

数量规则：

```text
排序后取前 6 个。
```

## 9. 排序例子

### 9.1 普通用户

用户最近通过 TagLauncher 打开过：

```text
Cursor
Chrome
Figma
ChatGPT
```

用户过去 30 天高频打开：

```text
Chrome
Notion
WeChat
Finder
```

快速建议可能显示：

```text
Cursor
Chrome
ChatGPT
Figma
Notion
WeChat
```

### 9.2 当前标签是设计

当前主界面标签是：

```text
设计
```

最近启动：

```text
Chrome
Cursor
ChatGPT
```

设计标签下高相关应用：

```text
Figma
Photoshop
Sketch
```

快速建议可能显示：

```text
Chrome
Cursor
Figma
ChatGPT
Photoshop
```

说明：

- 设计类应用获得 12 分加权。
- 列表没有被设计标签过滤。

### 9.3 新用户

用户没有足够启动历史。

本机已安装：

```text
Finder
Safari
Chrome
WeChat
Cursor
Figma
Notion
```

快速建议可能显示：

```text
Chrome
Safari
WeChat
Cursor
Notion
Figma
```

说明：

- 使用 Smart Start 高价值分类产生冷启动建议。
- 不显示完整应用列表。
- 不随机推荐。

## 10. 数据要求

快速建议需要以下本地数据：

| 字段 | 是否必须 | 说明 |
|---|---|---|
| 应用稳定标识 | 必须 | 本地稳定身份 |
| 包标识 | 推荐 | 用于去重和应用身份识别 |
| 应用名称 | 必须 | 用于展示和兜底排序 |
| 应用图标 | 必须 | 用于展示 |
| 标签标识 / 标签名称 | 必须 | 用于当前标签加权和展示 |
| 应用备注 | 可选 | 用于展示一行备注 |
| 最近成功启动时间 | 必须 | 用于最近启动分 |
| 过去 7 天成功启动次数 | 推荐 | 用于高频启动分 |
| 过去 30 天成功启动次数 | 推荐 | 用于高频启动分 |
| 总成功启动次数 | 推荐 | 用于判断历史是否充足 |
| 成功启动过的不同应用数量 | 推荐 | 用于判断历史是否充足 |
| 是否固定 | 预留 | 7.5 不暴露用户操作 |
| Smart Start 分类 | 推荐 | 用于冷启动分 |

启动历史记录要求：

- 应用通过 TagLauncher 成功启动后，记录启动时间。
- 应用通过 TagLauncher 成功启动后，增加启动次数。
- 应用启动失败时，不更新最近启动时间，不增加启动次数。
- 数据存储在本地。

## 11. 隐私要求

快速建议必须是本地优先能力。

要求：

- 不上传应用启动历史。
- 不上传快速搜索输入内容。
- 7.5 不读取 macOS 全局应用使用历史。
- 仅使用 TagLauncher 自己记录的启动历史和本地应用元数据。
- 排序数据存储在本地。

这点很重要，因为快速建议可能反映用户的使用习惯。

## 12. 刷新规则

快速建议应该在以下时机重新计算：

- 快速搜索打开时。
- 应用通过 TagLauncher 成功启动后。
- 应用目录发生变化时。
- 应用标签发生变化时。
- 应用备注发生变化时。
- 用户在打开快速搜索前切换了当前标签。

当快速搜索已经打开且查询为空时：

- 本次打开会话中的建议列表保持稳定。
- 用户正在用键盘导航时，不因为后台数据变化而重新排序。
- 避免用户准备按 `Enter` 时选中项突然移动。

## 13. 键盘和选择行为

要求：

- 第一个建议默认选中。
- `Enter` 打开选中的建议应用。
- `↑` 和 `↓` 移动选择。
- 鼠标悬停可以更新视觉高亮。
- 鼠标点击打开建议应用。
- 用户输入任意字符后切换到搜索结果。

如果建议为空：

- `Enter` 不执行任何操作。
- 输入框保持聚焦。

## 14. 边界情况

### 14.1 没有启动历史

进入冷启动模式，使用 Smart Start 高价值分类生成建议。

### 14.2 建议不足 6 个

如果排序结果少于 6 个：

1. 先补充冷启动候选。
2. 再补充本机已安装的常见高价值应用。
3. 最后按应用名称排序兜底。

不允许使用随机应用补齐。

### 14.3 应用已被移除

如果历史中的应用已经不在本机可启动应用列表中：

- 不显示为可启动建议。
- 是否保留历史数据，遵循现有应用历史数据策略。

### 14.4 重复应用记录

重复应用只显示一次。

去重优先级：

1. 包标识。
2. 稳定应用标识。
3. 规范化应用名称。

### 14.5 用户正在其他输入框编辑文本

快速建议只在快速搜索被明确打开后显示。

如果用户正在其他输入框中输入空格，不应触发快速搜索，也不应显示快速建议。

## 15. 非目标

7.5 不做以下内容：

- 读取 macOS 屏幕使用时间或系统级应用使用历史。
- 云端排序。
- AI 生成建议。
- 跨设备同步启动历史。
- 用户手动固定建议项。
- 完整命令面板推荐。
- 文件、联系人、浏览器历史或网页建议。
- 按窗口高度动态改变建议数量。

## 16. 验收标准

快速建议行为：

- 打开快速搜索且查询为空时，显示快速建议。
- 快速建议最多显示 6 个应用。
- 快速建议不显示列表标题。
- 快速建议不显示完整应用目录。
- 第一个建议默认选中。
- 按 `Enter` 打开选中的建议应用。
- 按 `↑` / `↓` 改变选中项。
- 输入任意字符后，从快速建议切换到搜索结果。
- 清空输入后，重新显示快速建议。

展示：

- 每个建议项显示应用图标和应用名称。
- 有备注时显示一行备注。
- 无备注但有标签时显示标签信息。
- 备注过长时只显示一行，不撑高列表。

排序：

- 最近启动的应用在正常情况下优先出现。
- 高频应用即使今天没打开，也有机会出现。
- 当前标签相关应用获得 12 分加权。
- 当前标签加权不能把列表过滤成当前标签内应用。
- 冷启动用户看到基于 Smart Start 高价值分类的合理建议。
- 重复应用不会出现两次。
- 建议不足 6 个时，不使用随机应用补齐。

隐私：

- 建议在本地生成。
- 搜索输入不上传。
- 启动历史不上传。
- 7.5 不读取 macOS 全局应用使用历史。

稳定性：

- 用户在空查询建议列表中导航时，列表不应突然重新排序。
- 已移除应用不显示为可启动建议。
- 应用成功启动后才更新启动时间和启动次数。

## 17. 测试用例

1. 打开快速搜索且不输入内容，确认快速建议可见。
2. 确认列表最多显示 6 个应用。
3. 确认列表上方不显示“快速建议”“最近使用”等标题。
4. 确认第一个建议默认选中。
5. 按 `Enter`，确认选中的应用被打开。
6. 按 `↓` 后再按 `Enter`，确认第二个建议被打开。
7. 输入一个字符，确认界面切换为搜索结果。
8. 删除输入内容，确认界面回到快速建议。
9. 通过 TagLauncher 成功打开一个应用后，再次打开快速搜索，确认该应用获得最近启动优先级。
10. 构造一个过去 7 天和 30 天的高频应用，确认它可以进入快速建议。
11. 从某个标签上下文打开快速搜索，确认该标签下应用获得加权，但列表没有被过滤到该标签。
12. 使用全新用户状态，确认冷启动建议来自本机已安装的高价值分类应用。
13. 移除或卸载一个曾经启动过的应用，确认它不再作为可启动建议出现。
14. 确认快速建议展示时不会产生网络请求。
15. 应用启动失败时，确认不更新最近启动时间和启动次数。

## 18. 发布原则

快速建议第一版不需要复杂，但必须稳定、直觉、可解释。

它应该让用户在打开快速搜索的第一眼就感觉：

```text
这些就是我大概率现在要打开的应用。
```

快速搜索负责输入后的搜索命中。

快速建议负责输入前的启动预测。