From 0f7ee6e29f70017dd4fdfe2dd3a6106f7204f04f Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Thu, 02 Jul 2026 02:40:40 +0800
Subject: [PATCH] Document Raycast extension backlog

---
 src/TODO.md                                                      |    7 +
 src/.hermes/plans/2026-07-02-raycast-extension-search-backlog.md |   81 +++++++++++++
 src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md |  260 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 348 insertions(+), 0 deletions(-)

diff --git a/src/.hermes/plans/2026-07-02-raycast-extension-search-backlog.md b/src/.hermes/plans/2026-07-02-raycast-extension-search-backlog.md
new file mode 100644
index 0000000..f590773
--- /dev/null
+++ b/src/.hermes/plans/2026-07-02-raycast-extension-search-backlog.md
@@ -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 官网提供安装说明。
diff --git a/src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md b/src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md
new file mode 100644
index 0000000..9cf21ae
--- /dev/null
+++ b/src/Docs/Requirements/2026-07-02-raycast-extension-search-prd.md
@@ -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 权益，后续再定。 |
diff --git a/src/TODO.md b/src/TODO.md
index d1bcd09..48ba903 100644
--- a/src/TODO.md
+++ b/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。

--
Gitblit v1.9.3