diffity-learn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diffity Learn Skill

Diffity Learn 技能

You are creating a teaching tour — a narrated, step-by-step walkthrough that teaches a programming concept using real examples found in the current codebase. Unlike a regular code tour that explains "how does feature X work", this tour teaches a concept (e.g. closures, generics, error handling patterns) by finding real instances in the code and explaining them progressively.

你正在创建一个教学导览——一种带解说的分步指引，通过当前代码库中的真实示例教授编程概念。与讲解「X功能如何运行」的常规代码导览不同，该导览通过查找代码中的真实实例并逐步讲解，来教授某个概念（例如 closures、generics、错误处理模式）。

Arguments

参数

concept

(required): The programming concept to teach. Examples:

```
/diffity-learn closures in JavaScript
```
```
/diffity-learn async/await
```
```
/diffity-learn dependency injection
```
```
/diffity-learn React hooks
```
```
/diffity-learn error handling patterns
```
```
/diffity-learn generics in TypeScript
```

concept

（必填）：需要教授的编程概念，示例：

```
/diffity-learn closures in JavaScript
```
```
/diffity-learn async/await
```
```
/diffity-learn dependency injection
```
```
/diffity-learn React hooks
```
```
/diffity-learn error handling patterns
```
```
/diffity-learn generics in TypeScript
```

CLI Reference

CLI 参考

diffity agent tour-start --topic "<text>" [--body "<text>"] --json
diffity agent tour-step --tour <id> --file <path> --line <n> [--end-line <n>] --body "<text>" [--annotation "<text>"] --json
diffity agent tour-done --tour <id> --json
diffity list --json

diffity agent tour-start --topic "<text>" [--body "<text>"] --json
diffity agent tour-step --tour <id> --file <path> --line <n> [--end-line <n>] --body "<text>" [--annotation "<text>"] --json
diffity agent tour-done --tour <id> --json
diffity list --json

Prerequisites

前置条件

Check that
```
diffity
```
is available: run
```
which diffity
```
. If not found, install it with
```
npm install -g diffity
```
.
Ensure a tree instance is running: run
```
diffity list --json
```
.
- If no instance is running, start one: run
```
diffity tree --no-open
```
  using the Bash tool with
```
run_in_background: true
```
  , wait 2 seconds, then run
```
diffity list --json
```
  to get the port.

检查
```
diffity
```
是否可用：运行
```
which diffity
```
。如果找不到，通过
```
npm install -g diffity
```
安装。
确保有实例正在运行：运行
```
diffity list --json
```
。
- 如果没有运行的实例，启动一个：使用 Bash 工具运行
```
diffity tree --no-open
```
  ，设置
```
run_in_background: true
```
  ，等待2秒，再运行
```
diffity list --json
```
  获取端口。

Instructions

使用说明

Phase 1: Find examples in the codebase

第一阶段：在代码库中查找示例

This is the most important phase. You must find real, concrete examples of the concept in this codebase.

Identify what to search for. Based on the concept, determine what code patterns to look for:
- For "closures": functions returned from other functions, callbacks capturing outer variables, factory patterns
- For "async/await": async functions, Promise chains, error handling with try/catch in async contexts
- For "generics": generic type parameters, generic functions/classes, constrained generics
- For "React hooks": useState, useEffect, useCallback, useMemo, custom hooks
- Think broadly about what forms the concept takes in practice
Search the codebase. Use grep, glob, and file reads to find instances. Search for:
- Language keywords associated with the concept
- Common patterns and idioms
- Both simple and complex usage
Select and rank examples. Pick 3-8 examples that:
- Are real and meaningful — not trivial boilerplate
- Cover different facets of the concept — not 5 examples of the same thing
- Progress from simple to complex — the first example should be the easiest to understand
- Are self-contained enough to explain without extensive context
Understand each example deeply. Read the surrounding code. Know why the concept is used here, what alternatives existed, and what would break without it.

这是最重要的阶段，你必须找到代码库中该概念真实、具体的示例。

确定搜索方向：基于要学习的概念，明确需要查找的代码模式：
- 对于「closures」：其他函数返回的函数、捕获外部变量的回调、工厂模式
- 对于「async/await」：async 函数、Promise 链、异步上下文下的 try/catch 错误处理
- 对于「generics」：泛型类型参数、泛型函数/类、受限泛型
- 对于「React hooks」：useState、useEffect、useCallback、useMemo、自定义 hooks
- 广泛思考该概念在实际应用中可能存在的各种形式
搜索代码库：使用 grep、glob 和文件读取功能查找实例，搜索对象包括：
- 与该概念相关的语言关键字
- 常见模式和惯用法
- 简单和复杂的两种用法
选择并排序示例：挑选3-8个符合以下要求的示例：
- 真实且有意义——不是无意义的样板代码
- 覆盖概念的不同维度——不要5个都是同一种用法的示例
- 按照从简单到复杂排序——第一个示例应该最容易理解
- 足够独立，不需要太多上下文就能解释清楚
深入理解每个示例：阅读周边代码，明确这里为什么要用这个概念，有什么替代方案，没有这个概念会出现什么问题。

Phase 2: Create the teaching tour

第二阶段：创建教学导览

The tour should feel like a patient teacher walking a beginner through real code, building their understanding step by step.

Start the tour with a concept introduction:
```
diffity agent tour-start --topic "<Concept Name>" --body "<concept overview>" --json
```
The
```
--topic
```
should be the concept name — keep it to 2-5 words (e.g. "JavaScript Closures", "Async/Await Patterns", "TypeScript Generics").
Writing the intro body (step 0): This is a standalone explanation of the concept that the reader sees before any code. Write it for someone who has basic programming knowledge but hasn't encountered this concept (or has only a vague understanding). Include:
- What the concept is — a clear, jargon-free definition
- Why it exists — what problem does it solve? What would code look like without it?
- Mental model — an analogy or way of thinking about it that makes it click
- What to look for — the syntactic or structural clues that tell you "this is an example of X"
- A preview of what the reader will see: "In this codebase, we'll look at N examples ranging from simple to complex"
Use rich markdown formatting. Do NOT list the files you'll visit — this is a concept explanation, not a table of contents.

Extract the tour ID from the JSON output.
Add steps in order of increasing complexity. For each step:
```
diffity agent tour-step --tour <id> --file <path> --line <start> --end-line <end> --body "<narrative>" --annotation "<short label>" --json
```
Writing teaching steps:

Each step should teach one facet of the concept through a concrete example. The narrative has two jobs: explain the concept AND explain why it's used in this specific code.

Structure each step's body as:
- What you're looking at — orient the reader in the code. What does this file/function do? (1-2 sentences)
- The concept in action — point out where and how the concept appears. Be specific: "On line 15,
```
config
```
  is captured by the inner function — this is a closure because..."
- Why it's used here — what problem does this solve in this specific context? What would the code look like without this pattern?
- Key takeaway — one sentence summarizing what this example teaches about the concept
Progression guidelines:
- First example: The simplest, most isolated instance. Minimal surrounding complexity. The reader should think "oh, that's all it is?"
- Middle examples: Introduce variations, edge cases, or more sophisticated usage. Each example should add one new dimension.
- Last example: The most complex or elegant usage. By now the reader has enough context to appreciate it.
IMPORTANT — Goto links for code references: Every time you mention a function, class, variable, or type that exists in a known file, you MUST make it a goto link. Do NOT use plain backtick code for symbols you can locate. The reader should be able to click any code reference to jump to its definition.
Syntax:
```
[`symbolName`](goto:path/to/file.ts:startLine-endLine)
```
or
```
[`symbolName`](goto:path/to/file.ts:line)
```
for a single line. Example:
```
[`handleDragEnd`](goto:src/KanbanContent.jsx:42-58)
```
These render as clickable inline code that navigates to the file and highlights the target lines. Use plain backtick code ONLY for generic terms, CLI commands, language keywords, or symbols you haven't located in the codebase.

Do:
- Use bold for concept terms being introduced or reinforced
- Use sub-highlights when a step covers 30+ lines to guide the reader's eye
- Draw connections between examples: "Unlike the previous example where X, here we see Y"
- Include "what if" scenarios: "If we removed the
```
async
```
  keyword here, this would return a raw Promise instead of..."
- Use mermaid diagrams sparingly — only when visualizing flow or state helps (e.g., a Promise chain, a closure's scope chain)
Don't:
- Assume knowledge of the concept — you're teaching it
- Just describe the syntax — explain the why
- Use jargon without defining it first
- Skip explaining why this specific code uses the pattern
- Show the same facet of the concept repeatedly

Finish the tour:

diffity agent tour-done --tour <id> --json

导览的体验应该像一个有耐心的老师带着初学者通读真实代码，逐步建立认知。

启动导览，先给出概念介绍：
```
diffity agent tour-start --topic "<Concept Name>" --body "<concept overview>" --json
```
```
--topic
```
应该是概念名称，控制在2-5个词（例如 "JavaScript Closures"、"Async/Await Patterns"、"TypeScript Generics"）。
编写介绍正文（第0步）： 这是读者看到代码之前的独立概念说明，面向有基础编程知识但没接触过该概念（或只有模糊认知）的用户，内容需要包含：
- 概念是什么——清晰、无晦涩术语的定义
- 它为什么存在——解决了什么问题？没有它的话代码会是什么样？
- 思维模型——能帮助理解的类比或者思考方式
- 识别要点——能判断「这是X概念的示例」的语法或结构线索
- 内容预告：「在这个代码库中，我们会看N个从简单到复杂的示例」
支持富Markdown格式，不要列出你要访问的文件——这是概念说明，不是目录。

从JSON返回结果中提取导览ID。
按复杂度从低到高添加步骤，每个步骤使用如下命令：
```
diffity agent tour-step --tour <id> --file <path> --line <start> --end-line <end> --body "<narrative>" --annotation "<short label>" --json
```
编写教学步骤：

每个步骤需要通过具体示例教授概念的一个维度，讲解内容有两个作用：解释概念本身，同时解释为什么这段特定代码要使用这个概念。

每个步骤的正文结构如下：
- 当前场景说明——帮助读者定位代码位置，说明这个文件/函数的作用（1-2句话）
- 概念实际应用——指出概念出现的位置和方式，要具体：「在第15行，
```
config
```
  被内部函数捕获——这就是一个closure，因为……」
- 此处使用的原因——在这个特定场景下它解决了什么问题？不用这个模式的话代码会是什么样？
- 核心收获——一句话总结这个示例关于该概念的教学点
难度递进规则：
- 第一个示例：最简单、最独立的实例，周边复杂度最低，读者看完应该会觉得「哦，原来就这么简单？」
- 中间示例：引入变体、边界场景，或者更复杂的用法，每个示例都要增加一个新的维度
- 最后一个示例：最复杂或者最巧妙的用法，此时读者已经有足够的上下文能够理解其价值
重要说明——代码引用的跳转链接： 每次你提到存在于已知文件中的函数、类、变量或者类型时，必须做成跳转链接。对于能定位到的符号，不要只用反引号包裹代码，读者应该能点击任意代码引用跳转到其定义位置。
语法：
```
[`symbolName`](goto:path/to/file.ts:startLine-endLine)
```
，单行的话用
```
[`symbolName`](goto:path/to/file.ts:line)
```
示例：
```
[`handleDragEnd`](goto:src/KanbanContent.jsx:42-58)
```
这些会渲染为可点击的行内代码，点击后会跳转到对应文件并高亮目标行。只有通用术语、CLI命令、语言关键字，或者你在代码库中找不到的符号才可以只用反引号包裹。

推荐做法：
- 对新引入或需要强化的概念术语使用加粗格式
- 当步骤覆盖30行以上代码时，使用 sub-highlights 引导读者视线
- 建立示例之间的关联：「和上一个X的示例不同，这里我们看到的是Y」
- 加入「假设」场景：「如果我们删掉这里的
```
async
```
  关键字，这里会返回一个原生Promise而不是……」
- 少量使用mermaid图表——仅当可视化流程或状态有助于理解时（比如Promise链、closure的作用域链）
禁止做法：
- 假设读者已经了解该概念——你的角色是教授者
- 只描述语法——要解释「为什么」
- 使用未提前定义的专业术语
- 跳过解释为什么这段特定代码要使用该模式
- 反复讲解概念的同一个维度

完成导览：

diffity agent tour-done --tour <id> --json

Phase 3: Open in browser

第三阶段：在浏览器中打开

Get the running instance port from
```
diffity list --json
```
.
Open the tour:
```
open "http://localhost:<port>/tour/<tour-id>"
```
(or the appropriate command for the user's OS).
Tell the user the tour is ready:

Your learning tour is ready — check your browser.

从
```
diffity list --json
```
的结果中获取运行实例的端口
打开导览：
```
open "http://localhost:<port>/tour/<tour-id>"
```
（或用户操作系统对应的命令）
告知用户导览已准备好：

你的学习导览已准备就绪，请查看浏览器。