Document Raycast extension backlog

Ariver

2026-07-02 0f7ee6e29f70017dd4fdfe2dd3a6106f7204f04f

Document Raycast extension backlog

 src/.hermes/plans/2026-07-02-raycast-extension-search-backlog.md

New file
@@ -0,0 +1,81 @@
# TagLauncher Raycast Extension Search - Backlog Plan

日期：2026-07-02  
状态：Backlog，仅备忘，今天不开发  
需求文档：`/Users/ar/Projects/Taglauncher/src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md`

## Goal

未来开发一个 Raycast Extension，让 Raycast 用户可以搜索 TagLauncher 中的应用、标签和备注，并回车启动目标 App。

## Current Decision

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

不建议 Raycast Extension 直接读取 TagLauncher 主数据库，避免隐私、半写入、schema 绑定和后续迁移风险。

## Backlog Rule

本计划只作为未来需求备忘。今天不进入开发，不创建 Raycast Extension 项目，不修改 TagLauncher 生产代码，不改变现有 Pro 权益和 Quick Search 行为。

## Future Implementation Phases

### Phase 1 - TagLauncher Index Export

- 增加设置开关：允许 Raycast 搜索标签和备注。
- 默认关闭。
- 开启后生成本地只读 JSON 索引：
  - 建议路径：`~/Library/Application Support/TagLauncher/Raycast/index.json`
- 标签、备注、App 扫描结果变化后刷新索引。
- 关闭后删除或清空索引。

### Phase 2 - Raycast Extension Prototype

- 使用 Raycast React + TypeScript Extension。
- 新增命令：`Search TagLauncher`。
- 读取 TagLauncher 导出的 JSON index。
- 支持按 App 名、标签名、备注、Bundle ID 搜索。
- 回车打开 App。

### Phase 3 - QA And Privacy Review

- 验证索引关闭态、开启态、损坏态、不存在态。
- 验证备注隐私提示。
- 验证标签和备注变更后的索引刷新。
- 验证 Raycast Extension 搜索与打开 App。

### Phase 4 - Raycast Store Release

- 准备扩展图标、metadata、README、截图。
- 检查 Raycast Store 发布要求：
  - `package.json` 的 author / MIT license / latest Raycast API / platforms。
  - 使用 `npm` 和 `package-lock.json`。
  - 至少一个 category。
  - 512x512 PNG extension icon。
  - 需要额外配置时提供 README。
- 本地执行：

```bash
npm run lint
npm run build
npm run publish
```

- 通过 `npm run publish` 创建 Raycast 官方 `raycast/extensions` 仓库 PR。
- 等 Raycast 审核通过后进入 Raycast Store。

## Out Of Scope For Now

- 今天不写代码。
- 不接入 Raycast 根搜索。
- 不做云同步。
- 不改变 TagLauncher Quick Search。
- 不直接读取 TagLauncher 主数据库。
- 不在本计划中决定免费 / Pro 策略。

## Open Questions

- Raycast 搜索基础能力是否免费开放，还是部分高级能力纳入 Pro。
- 索引刷新采用即时写入还是 debounce / 批量写入。
- 是否需要导出标签颜色供 Raycast accessory 展示。
- Raycast Extension 是否随 TagLauncher 官网提供安装说明。

 src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md

New file
@@ -0,0 +1,260 @@
# 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 搜索索引文件。建议路径：

```text
~/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 文件结构

```json
{
  "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 审核。推荐流程：

1. 本地开发 Raycast Extension。
2. 发布前检查 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。
3. 本地运行：

```bash
npm run build
```

4. 需要时本地运行：

```bash
npm run lint
```

5. 本地验证 Raycast Extension 行为。
6. 运行：

```bash
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 权益，后续再定。 |

 src/TODO.md

@@ -20,6 +20,13 @@

## Todo

- [Backlog][2026-07-02] Raycast Extension 搜索 TagLauncher 标签与备注。
  - 状态: 仅需求备忘，今天不开发。
  - 目标: 未来通过官方 Raycast Extension，让用户在 Raycast 中搜索 TagLauncher 的 App、标签和备注，并回车启动目标 App。
  - 当前决策: 推荐“TagLauncher 导出本地只读 JSON 索引 + Raycast Extension 读取索引”；不让 Raycast 直接读取 TagLauncher 主数据库。
  - 计划: `/Users/ar/Projects/Taglauncher/src/.hermes/plans/2026-07-02-raycast-extension-search-backlog.md`。
  - PRD: `/Users/ar/Projects/Taglauncher/src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md`。

- [发布后独立任务] 设置页 tab 容器 AppKit/自控化评估与实现。
  - 决策: 当前发布前 No-Go；保留 SwiftUI `TabView`，不改 QA 脚本。
  - 背景: QA 过程中曾观察到设置页顶部 tab 偶发折叠/消失，但目前不是稳定可复现 release blocker。