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]
阶段一：英文基线
-
确认权威来源，只保留官方页面。
-
识别应用主记录：name 、slug 、website 、author 、description 、icon_svg 。
-
识别分类绑定，例如 Development 、Terminal 这类站内分类。
-
将严格快捷键写入 public.app_hotkey 。
-
将方法说明、配置前提、输入模式等非严格快捷键写入 public.app_faq 。
-
生成幂等 SQL。
-
按 references/output-template.md 输出计划。
-
明确列出：
-
预期 app_hotkey 行数
-
FAQ 行数
-
OS 分布
-
关键假设
-
官方依据链接
-
等待用户确认后，再执行 SQL。
阶段二：国际化
-
只在英文基线已经存在后继续。
-
默认补齐数据库 locale：zh 、ja 、ru 、ar 、de 、fr 、pt 、in 。
-
注意：当前项目里路由层 id 对应数据库 in 。
-
默认策略：
-
app_i18n.name = NULL ，保留英文品牌名回退
-
app_i18n.description 全量翻译
-
app_hotkey_i18n.category/action 全量翻译
-
app_faq_i18n.question/answer 全量翻译
-
翻译完成后：
-
若 humanizer skill 可用，用它润色 description 和 FAQ
-
category 与 action 保持短、稳、可扫描，不追求文学化
-
生成幂等 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 的官方站点与官方文档；如果找不到官方快捷键页，就明确停止，不要猜。