PRD：Raycast 搜索 TagLauncher 标签与备注

日期：2026-07-02
状态：Backlog 需求备忘，今天不开发
适用产品：TagLauncher macOS App + Raycast Extension

1. 功能名

Raycast 搜索 TagLauncher 标签、备注与应用

2. 需求描述

用户希望 TagLauncher 里维护的应用标签和应用备注可以被 Raycast 搜索到，从而在 Raycast 中通过标签、备注或 App 名称快速找到并启动应用。

本需求不要求把 TagLauncher 数据直接并入 Raycast 根搜索结果。推荐方案是开发一个 Raycast Extension，提供一个“搜索 TagLauncher”命令。用户进入该命令后，可以搜索 TagLauncher 导出的标签、备注和应用数据。

3. 背景与目标

3.1 背景

TagLauncher 的核心数据包括：

App 列表。
App 与标签 / 容器的关系。
用户维护的应用备注。
标签名称、颜色、自定义颜色等信息。

这些数据目前主要服务于 TagLauncher 自身的 AppGrid、Quick Search 和设置页。Raycast 用户可能已经形成了从 Raycast 启动一切的习惯，因此把 TagLauncher 的组织信息开放给 Raycast，有助于扩大 TagLauncher 数据的使用场景。

3.2 目标

目标	说明
提升标签 / 备注复用价值	用户在 TagLauncher 中维护的备注和标签，可以在 Raycast 中继续发挥搜索价值。
降低切换成本	Raycast 重度用户无需回到 TagLauncher 主界面，也能用标签和备注定位应用。
控制隐私与稳定性风险	Raycast 不直接读取 TagLauncher 主数据库，而是读取 TagLauncher 主动导出的只读索引。
保持架构解耦	后续 TagLauncher 数据结构迁移，不应直接破坏 Raycast 扩展。

4. 推荐方案

推荐采用“TagLauncher 导出本地只读索引 + Raycast Extension 读取索引”的方案。

4.1 TagLauncher 侧

TagLauncher 增加一个可选开关：

允许 Raycast 搜索标签和备注

开启后，TagLauncher 在本机生成一个只读 JSON 搜索索引文件。建议路径：

~/Library/Application Support/TagLauncher/Raycast/index.json

索引由 TagLauncher 负责生成和刷新。Raycast Extension 只读取索引，不直接读取 TagLauncher 主数据库。

4.2 Raycast Extension 侧

Raycast Extension 提供一个命令：

Search TagLauncher

命令打开后显示 Raycast List，支持按以下内容搜索：

App 名称。
标签名称。
应用备注。
Bundle Identifier。
App 路径。

选中结果后回车打开对应 App。

Raycast 官方 List API 适合这类同构列表数据展示与搜索；Raycast extension 使用 React + TypeScript 开发。参考：

Raycast List API：https://developers.raycast.com/api-reference/user-interface/list
Raycast 开发者介绍：https://www.raycast.com/developers

5. 用户故事

编号	用户故事
RAY-01	作为 Raycast 用户，我希望输入应用备注中的关键词，就能找到对应 App。
RAY-02	作为 Raycast 用户，我希望输入 TagLauncher 标签名，就能看到该标签下的 App。
RAY-03	作为 Raycast 用户，我希望回车后直接打开 App。
RAY-04	作为隐私敏感用户，我希望 TagLauncher 不默认把备注开放给第三方工具。
RAY-05	作为长期用户，我希望 TagLauncher 数据结构升级后，Raycast 搜索仍尽量稳定。

6. 索引数据设计草案

6.1 文件结构

{
  "schemaVersion": 1,
  "generatedAt": "2026-07-02T00:00:00Z",
  "appVersion": "8.3.x",
  "items": [
    {
      "id": "/Applications/Safari.app",
      "name": "Safari",
      "path": "/Applications/Safari.app",
      "bundleIdentifier": "com.apple.Safari",
      "tags": ["浏览器", "Mac 自带"],
      "note": "默认浏览器",
      "tagColors": [
        {
          "name": "浏览器",
          "baseColor": 3,
          "customColorHex": null
        }
      ]
    }
  ]
}

6.2 字段说明

字段	说明
`schemaVersion`	索引 schema 版本，后续兼容迁移使用。
`generatedAt`	索引生成时间。
`appVersion`	生成该索引的 TagLauncher 版本。
`items[].id`	稳定 ID，建议先用 App path。
`items[].name`	App 显示名。
`items[].path`	App 路径，用于 Raycast 打开。
`items[].bundleIdentifier`	Bundle ID，用于辅助搜索和未来兼容。
`items[].tags`	App 所属标签名称列表。
`items[].note`	App 备注。
`items[].tagColors`	可选，用于 Raycast 列表中辅助展示。

7. 产品交互

7.1 TagLauncher 设置

建议在设置页增加一个开关：

状态	行为
关闭	不生成 Raycast 索引；如已有旧索引，可删除或清空。
开启	生成 Raycast 索引，并在标签 / 备注 / App 扫描结果变化后刷新。

建议文案：

允许 Raycast 搜索标签和备注

说明文案：

开启后，TagLauncher 会在本机生成只读搜索索引，供 Raycast 扩展读取。索引包含应用名称、标签和备注。

7.2 Raycast 命令

命令名称：

Search TagLauncher

列表项建议：

Title：App 名称。
Subtitle：标签 + 备注摘要。
Accessories：标签、Bundle ID 或路径片段。
Action：Open App。

8. 发布流程

Raycast Extension 不随 TagLauncher DMG 发布，也不走 Apple App Store 审核。推荐流程：

本地开发 Raycast Extension。
发布前检查 Extension Store 基本要求：

package.json 的 author 使用 Raycast 账号用户名。
license 使用 MIT。
使用最新 Raycast API 版本。
如果使用平台相关能力，需要配置合适的 platforms。
使用 npm 安装依赖，并提交 package-lock.json。
至少配置一个 Raycast Store category。
准备 512x512 PNG extension icon，不能使用默认 Raycast icon。
如果用户需要额外配置，需要在 extension 根目录提供 README。

本地运行：

npm run build

需要时本地运行：

npm run lint

本地验证 Raycast Extension 行为。
运行：

npm run publish

Raycast 官方文档说明，npm run publish 会通过 GitHub 认证，并自动向 raycast/extensions 仓库创建 Pull Request。PR 审核通过并合并后，扩展会自动发布到 Raycast Store。

参考：

Raycast 发布扩展：https://developers.raycast.com/basics/publish-an-extension
Raycast Store 准备要求：https://developers.raycast.com/basics/prepare-an-extension-for-store
Raycast Store：https://www.raycast.com/store

9. 隐私与权限

项	规则
默认状态	默认关闭，不主动生成 Raycast 可读索引。
用户授权	用户必须主动开启。
数据范围	只导出 App 名称、路径、Bundle ID、标签、备注和必要展示信息。
存储位置	本机 Application Support 目录，不上传云端。
删除行为	关闭开关后应删除或清空索引文件。
敏感说明	备注可能包含用户私人信息，设置页必须明确提示。

10. 免费 / Pro 关系

待产品确认。

初步建议：

Raycast 搜索基础能力可以作为免费用户可用能力，增强产品生态价值。
如果后续希望作为 Pro 转化点，可以把“Raycast 搜索备注”或“高级过滤 / 多命令”作为 Pro 能力，但不建议 MVP 首版就过度收费。

11. 验收标准

编号	验收项
RAY-QA-01	TagLauncher 开关关闭时，不生成 Raycast 索引或索引为空。
RAY-QA-02	TagLauncher 开关开启后，能生成合法 JSON 索引。
RAY-QA-03	修改标签后，索引中对应 App 的标签可刷新。
RAY-QA-04	修改备注后，索引中对应 App 的备注可刷新。
RAY-QA-05	Raycast Extension 可按 App 名搜索。
RAY-QA-06	Raycast Extension 可按标签名搜索。
RAY-QA-07	Raycast Extension 可按备注内容搜索。
RAY-QA-08	Raycast Extension 回车可打开目标 App。
RAY-QA-09	索引文件损坏或不存在时，Raycast Extension 给出可理解的空态或修复提示。
RAY-QA-10	不直接读取 TagLauncher 主数据库。

12. 不做范围

不做范围	说明
今天不开发	本文档仅做 Backlog 备忘。
不接入 Raycast 根搜索	MVP 不承诺每条标签 / 备注直接出现在 Raycast 根搜索。
不做云同步	索引只在本机生成和读取。
不直接读取主数据库	Raycast Extension 不依赖 TagLauncher 内部 Store 文件结构。
不改变 Quick Search	TagLauncher 内置 Quick Search 不因本需求改变。
不改变 Pro 权益	Raycast 能力是否收费，另行产品确认。

13. 风险与待确认问题

风险 / 问题	说明
Raycast 审核周期	Raycast Store 发布依赖官方 PR 审核。
隐私感知	用户备注可能敏感，必须默认关闭并清楚说明。
索引刷新时机	需要确认是每次保存立即刷新，还是延迟批量刷新。
索引文件兼容	后续字段变化需通过 `schemaVersion` 兼容。
商标和图标	发布 Raycast Extension 时，需要确认使用 TagLauncher 名称和图标的展示规范。
Pro 策略	是否把部分 Raycast 能力作为 Pro 权益，后续再定。