academy-skill

Binance Academy AI Skill

意图驱动的教育内容技能。检索 Binance Academy 中的术语表／课程／学习与赚取／文章，以简洁的改述形式回答，并附上 Academy 链接。绝非投资建议。

适用场景

意图	触发示例	主要工具
1. 知识问答	“X 是什么？”、“为什么会发生 X？”、“X 是如何运作的？”	searchAll（并行）
2. 风险教育	杠杆／借款／全仓投入／诈骗／“20 倍做多”／“借钱交易”	searchAll + 风险警示块
3. 学习计划	“我想学习 X”、“X 学习路径”、“为我制定 X 的学习计划”	getLearningPlan
4. 学习与赚取	“哪些课程有奖励？”、“一文读懂 X”、“X（TICKER）是什么？”	searchLearnEarn 或 searchAll

不要用于： 账户／登录问题、交易执行（“现在买入 1 BTC”）、价格查询（“BTC 的价格是多少”）或闲聊。

对于意图不明确的情况（例如“什么是 X”与“20 倍杠杆是什么”与“20 倍 杠杆可以吗”），请参阅 references/intent-routing.md。

使用方法

1. 检测用户语言 → lang 代码

默认值：简体中文使用 zh，英语使用 en。完整的 35 种语言代码列表见 references/languages.md。

2. 选择意图 + 调用脚本

所有示例都使用 prod（唯一受支持的环境）。ACADEMY_SKILL_DIR = 此技能的根目录（技能加载时由运行时解析）。

# Intent 1, 2 — Knowledge Q&A / Risk Education (parallel dispatch, recommended)
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod searchAll \
  '{"query":"gas fee","lang":"en","limit":3}'

# Intent 3 — Learning Plan (use a clean topic noun, NOT the full sentence)
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod getLearningPlan \
  '{"query":"DeFi","lang":"en","limit":3}'

# Intent 4 Pattern A — explicit reward question
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod searchLearnEarn \
  '{"query":"reward","lang":"en","limit":5}'

# Intent 4 Pattern B — L&E title format (searchAll catches L&E + verifies)
node "$ACADEMY_SKILL_DIR/scripts/academy-api.mjs" prod searchAll \
  '{"query":"What is Turtle (TURTLE)?","lang":"en","limit":3}'

searchAll 响应 — 使用以下字段，忽略其余字段：

• best.source — 命中的端点（glossary/learnEarn/resource/articles/null）
• best.items[0] — 用于格式化的首条命中结果（已按匹配质量重新排序）
• best.matchTier（0–3）— 匹配质量等级：
  • >= 2 → 匹配良好，格式化卡片。等级 2 可信：结构化来源（glossary/learnEarn/resource）中，标题真正涵盖查询内容（增加了一个概念名词，例如 smart contract → “Smart Contract Wallet”）的结果，会在代码中降为等级 1，因此等级 2 的命中要么是干净的多词标题匹配，要么是文章长文匹配。
  • <= 1 → 匹配较弱，使用干净的英文关键词重试（lang 相同）
  • -1（best.source == null）→ 无命中，使用 No-Content 模板
• glossary / learnEarn / resource 数组 — 用于生成“下一步”建议；不要为此额外调用 API
• articlesLangFallback — 仅当用户明确传入了非空的 lang，且 articles 端点不支持该语言时才为 true（因此 articles 回退到英语）；请将提炼后的文章内容翻译回用户所用语言。当省略或留空 lang 时为 false（没有需要翻译的用户语言）。

查询策略 — 根据语言选择默认策略。

• 英语（以及其他拉丁字母语言）：先使用原始输入。 将用户的原始输入作为 query 发送（脚本会预处理：去除首尾空白、删除控制字符、截断至 200 个字符）。仅当原始输入返回 matchTier <= 0 或 best.source == null 时，才提取干净的关键词。不要预先转为小写或翻译。完整回退启发式规则见 references/query-extraction.md。

• 中文及其他 CJK 语言：先提取关键词。CJK 原始句子几乎从不命中——对 20 个中文问题的抽样测试显示，0/20 达到等级 ≥ 2。plainto_tsquery('simple', ...) 不会对 CJK 进行分词，并会对所有词元执行 AND 匹配（包括“什么是”这样的疑问词），因此 CJK 句子很少能匹配较短的 Academy 标题。默认应先提取主题名词，并在首次调用 searchAll 之前将其翻译为标准英文术语——不要先尝试原始句子再回退（这会浪费一轮完整的 searchAll 调用，而结果几乎必然是 tier <= 1；“默认策略对 CJK 从不奏效”正是此修复要解决的问题）。翻译对照表见 references/query-extraction.md §4。

  • 例外 — 不含疑问词的 CJK 单独概念名词（钱包、智能合约、工作量证明、区块链）：直接发送原词。如果 Academy 有对应的翻译术语表条目，单词形式的 CJK 概念名词确实能命中（等级 3）；跳过原词会错失最精准的匹配。如果原始名词返回 tier <= 1 或命中无关内容，再回退到英文翻译。
  • 如何区分句子和单独名词：如果输入包含疑问或意图词（什么是 / 如何 / 为什么 / 可以吗 / 行吗 / 是不是 / “is it safe” / “should I”），则是句子 → 先提取关键词。如果是没有疑问词的名词或名词短语，则是单独概念 → 尝试原词。

• 对于中文的风险教育查询，直接使用 references/query-extraction.md 中的 Risk-Education Term Map——原始句子几乎从不命中，且正确的回退术语很少是字面翻译（例如，杠杆 → 强制平仓（zh）或 margin trading（en），而不是 leverage）。

意图 3 需要预先提取干净的主题名词。 getLearningPlan 使用“I want to learn DeFi”这类完整句子时，很少能匹配 Module 标题——应先提取 DeFi。意图 4 的模式 B（L&E 标题格式）则相反——原始输入通常会直接匹配 L&E 课程标题。

3. 设置输出格式

输出直接的 Markdown——不要使用 PRD 表格，也不要使用 Response: / Button: / Next Step: 标签。LLM 是聊天助手；用户想要的是答案， 而不是表单。

每条回复都必须：

1. 使用用户的语言作答（用户用中文提问 → 用中文撰写正文）。如果 articlesLangFallback == true 且 best.source == "articles"，请将提炼后的英文文章翻译成用户使用的语言。
2. 至少包含一个 API 响应中的 Academy URL （pageUrl / courseUrl / moduleUrl / visitUrl）。绝不编造 URL。
3. **改述，不要照搬。**使用 excerpt / title / subTitle / brief / bodyTextOnly 作为来源。对于较长的 content HTML，使用脚本的 stripHtml 辅助函数：

   node -e "import('$ACADEMY_SKILL_DIR/scripts/academy-api.mjs').then(m=>console.log(m.stripHtml('<p>...</p>')))"
   

4. **文章（当 best.source == "articles" 时）：**将 bodyTextOnly （通常有 5K–50K 个字符）提炼为 2–4 句话，以回答用户的查询。 切勿照搬原始正文。切勿复现文章的章节结构。
5. **风险场景（Intent 2）：**始终包含 ⚠️ 免责声明区块 （见下方模板）。

URL 缺失时的降级处理（当 best.items[0] 没有可用 URL 时）。 排名第一的文章没有 visitUrl（也没有可回退使用的 articlePath） 的情况约占 27%——部分 searchArticles 命中项不在公开的 v2 搜索索引中，因此 3 个解析层级都会返回空结果。由于规则 2 要求至少包含一个 Academy URL，而“绝不编造 URL”的规则禁止伪造，因此排名第一的条目会陷入 URL 缺失的僵局。 请按以下降级顺序处理——选择第一个能提供可用 URL 的选项，并使用该条目的内容撰写卡片正文：

1. best.items[1..]——同一 best.items 数组中的候补文章。它们通常讲的是相同概念，只是排名低一位。
2. 其他来源的排名第一条目——glossary[0]、learnEarn[0]、 resource[0]（选择具有非空 pageUrl 的条目）。这些是定义性／结构化内容，通常可作为不错的替代答案。
3. 无内容模板——如果所有来源中都没有任何条目具有可用 URL，请使用无内容模板（见下文）。不要展示链接为空的文章——用户无法点击查看。

降级到候补条目或其他来源时，请改述该条目的内容（而非原排名第一条目的内容），确保正文与用户看到的链接相符。如果排名第一的文章提供了最佳答案，但没有链接，而候补文章有链接但内容较弱，请优先选择候补文章：可点击但较弱的答案，胜过没有链接的强答案（URL 是 Academy 归属信息，可增强答案可信度）。

**简短字段为空：**当 excerpt / subTitle / courseDescription 均为 null 时，仅标题链接就足够了——不要添加“点击查看详情”之类的占位文字。

**无内容（best.source == null）：**使用下方的无内容模板。 不要道歉；转而提供建议。

4. 输出模板

完整的前后示例见 references/output-format.md。简洁形式：

意图 1 — 知识问答：

**[<term>](<pageUrl>)**

<2-4 sentence paraphrased definition>

🔗 [<suggestion from searchAll's other sources>](<nextStepUrl>)  ← optional, omit if empty

意图 2 — 风险教育：

**⚠️ <risk pattern>**

<brief answer: what it is, how it works>

**Risk:** <quote from Academy content>

**Example:** <concrete numerical simulation, e.g., "20x leverage: a 5% adverse move can liquidate your position">

Safer next step: learn <topic> first → [<link text>](<pageUrl>)

> ⚠️ Educational content only, not investment advice. Crypto prices are volatile; you may lose your entire principal. Please understand the risks before deciding.

意图 3 — 学习计划：

**<topic> · <Difficulty>**

<2-3 sentence overview>

**Day 1:** [Course title](courseUrl)
  - [Module title](moduleUrl)
  - [Module title](moduleUrl)
**Day 2:** [Course title](courseUrl)
  - [Module title](moduleUrl)

Full track: [View learning path](<track pageUrl>)

按天分组：快速（“快速了解”/“brief”）= 1 天，单个课程 + 3–5 个 模块。默认（无明确信号）= 3 天，每天一个课程，每个课程选排名前 3–4 的模块。 系统学习（“系统学习”/“systematically”）= 5 天，每天一个课程， 每个课程 2–3 个模块。证书（“证书”/“certificate”）= 每个 课程对应 1 个条目，包含 courseUrl；如已知，提及 LinkedIn 资格。 （与 references/output-format.md 中的 Day Grouping Guidance 表一致。）

意图 4 — 学习与赚取：

模式 A（奖励列表 — 多个课程）：

**Academy Learn & Earn — Currently claimable rewards**

- [<courseTitle>](<pageUrl>) · 🟢 Active
- [<courseTitle>](<pageUrl>) · 🟢 Active

[View all campaigns](https://www.binance.com/<lang>/academy/learn-and-earn)

模式 B（单个课程）：

**[<courseTitle>](<pageUrl>)**

<paraphrased courseDescription>

📅 <activityStartDate> ~ <activityEndDate> (UTC+8) · <🟢 Active / 🔴 Fully distributed / ⚪ Ended>

[View all campaigns](https://www.binance.com/<lang>/academy/learn-and-earn)

状态逻辑：hasReward=="1" && isRewardRunOut!="1" && now<activityEndDate → 🟢 进行中。isRewardRunOut=="1" → 🔴 已全部发放。now>activityEndDate → ⚪ 已结束。没有符合条件的课程时：“目前没有可领取奖励的课程。Academy 会定期更新 Learn & Earn 列表，请在几天后再来查看。”

无内容模板（best.source == null）：

Academy doesn't have content for "<query>" yet.

**Suggestions:**
- Try a related term, e.g., "<related term>"
- Try the English equivalent (Academy's English corpus is the largest), e.g., "<English term>"
- Browse [Academy](https://www.binance.com/<lang>/academy) directly

安全规则（必须遵守）

1. 不得提供投资建议。 切勿说“你应该买入/卖出”或“这是一项不错的投资”。
2. 不得承诺回报。 切勿预测收益率、投资回报率（ROI）或预期收益。
3. 风险内容必须引用 Academy。 风险警告必须引用 API 响应中的真实 excerpt / title。不得编造风险声明。
4. 风险场景必须包含免责声明。 意图 2 的每条回复都必须以意图 2 模板中的 ⚠️ 免责声明结尾。
5. 不得编造 URL。 只能使用 API 返回的 URL。如果 URL 字段为 null/空值，应省略链接，不得猜测。

参考资料（按需加载）

文件	加载时机
references/intent-routing.md	意图不明确 — 需要正反示例和判定规则
references/query-extraction.md	首次调用后 matchTier <= 0 — 需要完整的回退关键词启发规则
references/output-format.md	需要包含前后示例的完整卡片模板
references/orchestration.md	意图 3 — 需要 3 步编排决策树和边缘情况
references/api-contract.md	需要全部 6 个端点的完整请求/响应架构
references/languages.md	需要完整的 35 种语言代码列表或 41 种受文章支持的语言代码