Official Hotkey Ingestion

这个技能负责什么

• 将某个 App 的官方快捷键按当前项目数据库模型落库。
• 把整个流程固定成两段：先英文基线，再国际化。
• 始终先给计划与 SQL，再等用户确认执行。

进入任务后的第一步

先读取这些项目内信息，把它们当作当前仓库的真实约束：

• CLAUDE.md：数据库表结构、字段语义、页面路由与构建约束
• src/i18n/config.ts：语言列表与 id -> in 的数据库映射
• references/source-discovery.md：如何定位官方来源
• references/output-template.md：计划输出骨架
• references/sql-rules.md：SQL 组织方式与执行前核对项

不可妥协的边界

• 只使用官方来源：官网、官方帮助中心、官方文档、官方发布说明、官方产品内帮助内容。
• 允许的输入只有三类：
  • App 官网
  • 一段产品介绍
  • 只有 App 名称
• 如果用户只给 App 名称，先定位官方站点，再在官方域名内寻找快捷键资料。
• 如果官方文档存在 llms.txt，先读取它作为文档索引，再展开浏览。
• 绝不把第三方快捷键站、论坛帖子、社区回答当作快捷键事实来源。
• 绝不根据通用习惯、平台惯例、UI 猜测任何未被官方明确写出的按键。
• 若缺少官方快捷键依据，必须停止执行并明确说明“证据不足，不能安全入库”。
• 全程使用简体中文回复。
• 不改仓库业务代码；只有在用户确认后，才允许通过 PostgreSQL MCP 写数据库。

总流程

flowchart TD
    A[收到 App 名称 / 官网 / 介绍] --> B[定位官方站点与官方文档]
    B --> C{官方 docs 有 llms.txt?}
    C -- 有 --> D[先读 llms.txt 建索引]
    C -- 无 --> E[直接在官方域名内定位 shortcuts 页面]
    D --> F[提取产品描述 图标 分类 快捷键 FAQ 素材]
    E --> F
    F --> G[阶段一：英文基线计划与 SQL]
    G --> H{用户确认执行?}
    H -- 否 --> I[继续修订英文计划]
    H -- 是 --> J[PostgreSQL MCP 单事务写入英文基线]
    J --> K{用户是否需要 i18n?}
    K -- 否 --> L[输出英文阶段验收 SQL]
    K -- 是 --> M[阶段二：i18n 计划与 SQL]
    M --> N{用户确认执行?}
    N -- 否 --> O[继续修订 i18n 计划]
    N -- 是 --> P[PostgreSQL MCP 单事务写入 i18n]
    P --> Q[输出最终手动验收 SQL]

阶段一：英文基线

1. 确认权威来源，只保留官方页面。
2. 识别应用主记录：name、slug、website、author、description、icon_svg。
3. 识别分类绑定，例如 Development、Terminal 这类站内分类。
4. 将严格快捷键写入 public.app_hotkey。
5. 将方法说明、配置前提、输入模式等非严格快捷键写入 public.app_faq。
6. 生成幂等 SQL。
7. 按 references/output-template.md 输出计划。
8. 明确列出：
   • 预期 app_hotkey 行数
   • FAQ 行数
   • OS 分布
   • 关键假设
   • 官方依据链接
9. 等待用户确认后，再执行 SQL。

阶段二：国际化

1. 只在英文基线已经存在后继续。
2. 默认补齐数据库 locale：zh、ja、ru、ar、de、fr、pt、in。
3. 注意：当前项目里路由层 id 对应数据库 in。
4. 默认策略：
   • app_i18n.name = NULL，保留英文品牌名回退
   • app_i18n.description 全量翻译
   • app_hotkey_i18n.category/action 全量翻译
   • app_faq_i18n.question/answer 全量翻译
5. 翻译完成后：
   • 若 humanizer skill 可用，用它润色 description 和 FAQ
   • category 与 action 保持短、稳、可扫描，不追求文学化
6. 生成幂等 SQL，先给计划，等用户确认后再执行。

数据归类规则

• 写入 public.app_hotkey：
  • 官方明确给出的按键组合
  • 官方明确当作输入触发符展示的单字符触发，例如 /、!、@、?
• 写入 public.app_faq：
  • 非严格键盘快捷键的方法说明
  • 终端或编辑器前置设置
  • 某快捷键为何可能无效的原因说明
  • “直接粘贴”“进入某模式再输入”这类行为说明
• 分类优先沿用官方分节标题；如果必须归并，只做最小化归并。
• 只有在官方明确区分 OS 时才写平台差异；若官方明确说某绑定通用于多平台，才对适用平台展开，绝不脑补额外平台。

SQL 生成规则

• 所有写入必须放在单事务里：BEGIN ... COMMIT。
• 优先用 WITH CTE 组织输入数据与 upsert 逻辑。
• 所有写入都必须幂等：
  • INSERT ... ON CONFLICT DO UPDATE
  • 或 ON CONFLICT DO NOTHING 配合存在性判断
• 英文阶段至少覆盖：
  • public.app
  • public.app_category
  • public.app_hotkey
  • public.app_faq
• 国际化阶段至少覆盖：
  • public.app_i18n
  • public.app_hotkey_i18n
  • public.app_faq_i18n
• 大批量翻译映射优先使用 jsonb_each / jsonb_each_text 展开。
• slug、app.id、app_hotkey.id 要尽量稳定、可读，方便重复执行和后续维护。
• 如果 SQL 很长，计划里可以省略部分映射正文，但必须：
  • 给出完整事务骨架
  • 说明哪些长映射被省略
  • 明确承诺“执行时使用完整 SQL，不遗漏任何映射”
• 真正调用 PostgreSQL MCP 时，必须发送完整无删节 SQL，不允许遗漏任何 locale、action、FAQ 或热键行。

图标与描述规则

• description 必须来自官方产品概述页或首页文案，必要时可做最小化摘写，但不要杜撰卖点。
• icon_svg 优先使用官方站点里可直接复用的 SVG 标识。
• 如果没有可安全复用的官方 SVG，不要私自重绘；应向用户说明并请求是否接受占位图标或稍后补充。

输出格式

• 信息不足时，只补最少的问题，优先确认官方站点与官方快捷键页面。
• 信息足够后，先输出“计划稿”，结构遵循 references/output-template.md。
• 规划超过 3 步时，计划里必须包含 Mermaid 流程图。
• 不要在未确认前直接写库。
• 执行完成后，只汇报：
  • 是否成功
  • 实际写入或覆盖的数量
  • 手动验收 SQL
  • 因证据不足而被排除的条目

典型触发

示例 1 用户：收录 Raycast 的快捷键，官网你自己找，只能用官方资料。

你应该：先定位 Raycast 官方站点和官方快捷键文档，输出英文基线计划与 SQL，确认后入库，再做 i18n。

示例 2 用户：这是官网 https://example.com ，把这个工具的 shortcuts 入库。

你应该：只在该官方域名及其官方 docs 域名内寻找权威页面，识别 hotkey 与 FAQ，先给计划再执行。

示例 3 用户：英文基线已经有了，补这个 app 的多语言快捷键翻译。

你应该：跳过英文阶段，直接生成 i18n 计划与 SQL，确认后用 PostgreSQL MCP 写入。

示例 4 用户：我只有应用名，叫 FooBar，帮我收录快捷键。

你应该：先定位 FooBar 的官方站点与官方文档；如果找不到官方快捷键页，就明确停止，不要猜。