learn

学习

通过收集在线资源并创建经过 RAG 优化的索引，研究任意主题并编写全面的学习指南。

解析参数

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const depth = args.find(a => a.startsWith('--depth='))?.split('=')[1] || 'medium';
const topic = args.filter(a => !a.startsWith('--')).join(' ');

输入

参数：<topic> [--depth=brief|medium|deep]

• topic：要研究的主题（必填）
• --depth：收集来源的深度
  • brief：10 个来源（快速概览）
  • medium：20 个来源（默认，均衡）
  • deep：40 个来源（全面）

研究方法

基于以下最佳实践：

• Anthropic 的上下文工程
• DeepLearning.AI 的工具使用模式
• Anara 的 AI 文献综述

1. 渐进式查询架构

使用漏斗式方法，避免冗长的查询列表带来噪声：

广泛阶段（映射全貌）：

"{topic} overview introduction"
"{topic} documentation official"

聚焦阶段（核心内容）：

"{topic} best practices"
"{topic} examples tutorial"
"{topic} site:stackoverflow.com"

深入阶段（深度为 deep 时使用）：

"{topic} advanced techniques"
"{topic} pitfalls mistakes avoid"
"{topic} 2025 2026 latest"

2. 来源质量评分

多维度评估（最高分：100）：

因素	权重	最高分	标准
权威性	3x	30	官方文档（10）、公认专家（8）、知名网站（6）、博客（4）、普通来源（2）
时效性	2x	20	<6 个月（10）、<1 年（8）、<2 年（6）、<3 年（4）、更早（2）
深度	2x	20	全面（10）、详细（8）、概览（6）、浅显（4）、片段（2）
示例	2x	20	多个代码示例（10）、一个示例（6）、无示例（2）
独特性	1x	10	独特视角（10）、部分重复（6）、内容重复（2）

筛选门槛：按得分选出排名前 N 的来源（N = 深度目标）

3. 即时检索

不要预先加载所有内容（这会导致上下文退化）：

1. 先通过 WebSearch 收集 URL
2. 根据元数据（标题、描述、URL）评分
3. 仅通过 WebFetch 获取筛选出的来源
4. 提取摘要（而非完整内容）

4. 内容提取指南

对于每个来源，提取：

{
  "url": "https://...",
  "title": "Article Title",
  "qualityScore": 85,
  "scores": {
    "authority": 9,
    "recency": 8,
    "depth": 7,
    "examples": 9,
    "uniqueness": 6
  },
  "keyInsights": [
    "Concise insight 1",
    "Concise insight 2"
  ],
  "codeExamples": [
    {
      "language": "javascript",
      "description": "Basic usage pattern"
    }
  ],
  "extractedAt": "2026-02-05T12:00:00Z"
}

版权合规：仅提供摘要和见解，绝不逐字摘录段落。

输出结构

主题指南模板

创建 agent-knowledge/{slug}.md：

# Learning Guide: {Topic}

**Generated**: {date}
**Sources**: {count} resources analyzed
**Depth**: {brief|medium|deep}

## Prerequisites

What you should know before diving in:
- Prerequisite 1
- Prerequisite 2

## TL;DR

Essential points in 3-5 bullets:
- Key point 1
- Key point 2
- Key point 3

## Core Concepts

### {Concept 1}

{Synthesized explanation from multiple sources}

**Key insight**: {Most important takeaway}

### {Concept 2}

{Synthesized explanation}

## Code Examples

### Basic Example

```{language}
// Description of what this demonstrates
{code}

高级模式

{code}

常见陷阱

陷阱	成因	如何避免
问题 1	根本原因	预防策略

最佳实践

综合自 {n} 个来源：

1. 实践 1：说明
2. 实践 2：说明

延伸阅读

资源	类型	推荐理由
Title	官方文档	权威参考资料
Title	教程	分步指南

---

由 /learn 根据 {count} 个来源生成。 完整来源元数据请见 resources/{slug}-sources.json。

### Master Index Template

Create/update `agent-knowledge/CLAUDE.md`:

```markdown
# Agent Knowledge Base

> Learning guides created by /learn. Reference these when answering questions about listed topics.

## Available Topics

| Topic | File | Sources | Depth | Created |
|-------|------|---------|-------|---------|
| {Topic 1} | {slug1}.md | {n} | medium | 2026-02-05 |
| {Topic 2} | {slug2}.md | {n} | deep | 2026-02-04 |

## Trigger Phrases

Use this knowledge when user asks about:
- "How does {topic1} work?" → {slug1}.md
- "Explain {topic1}" → {slug1}.md
- "{Topic2} best practices" → {slug2}.md

## Quick Lookup

| Keyword | Guide |
|---------|-------|
| recursion | recursion.md |
| hooks, react | react-hooks.md |

## How to Use

1. Check if user question matches a topic
2. Read the relevant guide file
3. Answer based on synthesized knowledge
4. Cite the guide if user asks for sources

复制到 agent-knowledge/AGENTS.md，供 OpenCode/Codex 使用。

来源元数据

创建 agent-knowledge/resources/{slug}-sources.json：

{
  "topic": "{original topic}",
  "slug": "{slug}",
  "generated": "2026-02-05T12:00:00Z",
  "depth": "medium",
  "totalSources": 20,
  "sources": [
    {
      "url": "https://...",
      "title": "...",
      "qualityScore": 85,
      "scores": {
        "authority": 9,
        "recency": 8,
        "depth": 7,
        "examples": 9,
        "uniqueness": 6
      },
      "keyInsights": ["..."]
    }
  ]
}

自我评估清单

定稿前，为输出评分（1–10）：

指标	问题	目标
覆盖度	指南是否涵盖主要方面？	≥7
多样性	来源类型是否多样？	≥6
示例	代码示例是否实用？	≥7
准确性	对内容准确性的信心如何？	≥8

标记缺口：注明任何未涵盖的重要子主题。

增强集成

如果 enhance=true，则在创建指南后调用：

// Enhance the topic guide for RAG
Skill({ name: 'enhance-docs', args: `agent-knowledge/${slug}.md --ai` });

// Enhance the master index
Skill({ name: 'enhance-prompts', args: 'agent-knowledge/CLAUDE.md' });

输出格式

在标记之间返回结构化 JSON：

=== LEARN_RESULT ===
{
  "topic": "recursion",
  "slug": "recursion",
  "depth": "medium",
  "guideFile": "agent-knowledge/recursion.md",
  "sourcesFile": "agent-knowledge/resources/recursion-sources.json",
  "sourceCount": 20,
  "sourceBreakdown": {
    "officialDocs": 4,
    "tutorials": 5,
    "stackOverflow": 3,
    "blogPosts": 5,
    "github": 3
  },
  "selfEvaluation": {
    "coverage": 8,
    "diversity": 7,
    "examples": 9,
    "accuracy": 8,
    "gaps": ["tail recursion optimization not covered"]
  },
  "enhanced": true,
  "indexUpdated": true
}
=== END_RESULT ===

错误处理

错误	操作
WebSearch 失败	使用更简单的查询重试
WebFetch 超时	跳过来源，并在元数据中注明
找到的来源少于 <minSources	警告用户，并使用现有来源继续
增强失败	跳过，并在输出中注明
索引不存在	创建新索引

令牌预算

各阶段的预估令牌用量：

阶段	令牌数	备注
WebSearch 查询	~2,000	5-8 个查询
来源评分	~1,000	仅元数据
WebFetch 提取	~40,000	20 个来源 × 平均 2,000
综合	~10,000	生成指南
增强	~5,000	两次技能调用
总计	~60,000	在 opus 预算范围内

集成

此技能由以下项目调用：

• learn-agent 用于 /learn 命令
• 其他研究型 Agent 也可能调用