# codetour

**Repository Path**: ccpdead/codetour

## Basic Information

- **Project Name**: codetour
- **Description**: 一个方便vscode阅读代码并做笔记的插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeTour 🗺️

CodeTour 是一个 Visual Studio Code 插件，允许你记录并回放代码库的引导式演练。它就像一个目录，让开发者在克隆仓库后能够立即**学习代码**，而无需阅读 `CONTRIBUTING.md` 或依赖他人帮助。代码导览是一系列交互式步骤，每个步骤关联到特定的目录、文件/行号，并包含对相应代码的描述。

本仓库在 [microsoft/codetour](https://github.com/microsoft/codetour) 原版基础上新增了以下功能：

- **数学公式渲染**：步骤描述中支持 LaTeX 数学公式，使用 `$...$`（行内公式）和 `$$...$$`（块级公式）语法，由 MathJax 渲染为 SVG 图像内嵌在注释中。
- **点击节点直接开始导览**：在资源管理器侧边栏的 `CodeTour` 树视图中，直接单击导览节点即可开始播放，无需右键菜单。

---

## 目录

- [功能介绍](#功能介绍)
  - [记录导览](#记录导览)
  - [开始导览](#开始导览)
  - [浏览导览](#浏览导览)
  - [导出导览](#导出导览)
  - [数学公式支持（新增）](#数学公式支持新增)
- [从源码安装到 VS Code](#从源码安装到-vs-code)
  - [环境准备](#环境准备)
  - [克隆并构建](#克隆并构建)
  - [打包为 .vsix 文件](#打包为-vsix-文件)
  - [在 VS Code 中安装](#在-vs-code-中安装)
- [参考](#参考)

---

## 功能介绍

### 记录导览

点击 `CodeTour` 树视图中的 `+` 按钮，或运行命令 `CodeTour: Record Tour`，即可开始录制。录制过程中：

1. 打开任意文件，点击行号左侧的注释图标（或高亮选中一段代码后点击），添加步骤说明（支持 Markdown）。
2. 录制完成后，点击停止按钮（红色方块）结束录制。

步骤说明支持以下扩展语法：

| 语法 | 说明 |
|---|---|
| `>> npm run build` | 点击后在终端中执行该命令 |
| `[步骤标题][#2]` | 跳转到当前导览的第 2 步 |
| `[导览名称]` | 跳转到另一个导览 |
| `$E=mc^2$` | 行内 LaTeX 数学公式（新增） |
| `$$\sum_{i=1}^n i$$` | 块级 LaTeX 数学公式（新增） |

导览文件以 JSON 格式保存在工作区的 `.tours/`、`.vscode/tours/` 或 `.github/tours/` 目录下。

#### 步骤类型

- **文件步骤**：关联到具体的文件与行号
- **目录步骤**：高亮资源管理器中的某个目录
- **内容步骤**：纯 Markdown 内容页，不关联任何文件（适合作为导览序言）
- **文本选区步骤**：关联到文件中的一段代码选区

#### 版本控制

录制时可为导览关联 Git ref（分支、标签或提交），使导览与代码库版本同步。支持选项：`None`（不锁定版本）、`Current Branch`、`Current Commit`、或具体 Tag。

### 开始导览

打开包含导览的工作区后，可通过以下方式开始：

- **单击导览节点**（新增）：在 `CodeTour` 树视图中直接单击导览名称，即可立即开始播放。
- **命令面板**：运行 `CodeTour: Start Tour`，从列表中选择导览。
- **树视图**：展开导览节点，点击某一具体步骤，从该步骤开始。
- **导览标记**：在文件编辑器的行号旁会显示导览图标（gutter marker），悬停后点击 `Start Tour` 链接。

### 浏览导览

导览播放时，注释 UI 中提供以下操作：

- `上一步` / `下一步`：在步骤之间导航
- `编辑导览`：进入编辑模式
- `结束导览`：退出当前导览

**键盘快捷键**（导览进行中有效）：

| Windows / Linux | macOS | 说明 |
|---|---|---|
| `Ctrl+Right` | `Cmd+Right` | 下一步 |
| `Ctrl+Left` | `Cmd+Left` | 上一步 |
| `Ctrl+Down Ctrl+Down` | `Cmd+Down Cmd+Down` | 结束导览 |
| `Ctrl+Up Ctrl+Up` | `Cmd+Up Cmd+Up` | 开始新导览 |

状态栏右下角会显示当前导览名称和步骤编号，点击可跳回当前步骤。

### 导出导览

可将导览导出为独立的 `.tour` 文件（内嵌所有相关代码内容），方便分享给未克隆仓库的同事：

- 右键点击 `CodeTour` 树视图中的导览节点，选择 `Export Tour...`

### 数学公式支持（新增）

在步骤描述中可以直接书写 LaTeX 公式，CodeTour 会通过 MathJax 将其渲染为 SVG 图像内嵌在注释中：

**行内公式**（使用单个 `$` 包裹）：

```
质能方程：$E = mc^2$
```

**块级公式**（使用 `$$` 包裹，独占一行）：

```
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
```

公式使用 MathJax Full 渲染，支持 TeX 全部扩展宏包，适配深色主题。

---

## 从源码安装到 VS Code

### 环境准备

确保已安装以下工具：

- [Node.js](https://nodejs.org/) >= 16（推荐 LTS 版本）
- npm（随 Node.js 一同安装）
- [Visual Studio Code](https://code.visualstudio.com/)

验证安装：

```bash
node --version
npm --version
```

### 克隆并构建

```bash
# 克隆仓库
git clone <your-repo-url>
cd codetour

# 安装依赖
npm install

# 生产构建（生成 dist/extension-node.js 和 dist/extension-web.js）
npm run build
```

> 如需开发模式（监听文件变化自动重新构建），可运行 `npm run watch`。

### 打包为 .vsix 文件

```bash
# 安装 vsce 打包工具（仅需执行一次）
npm install -g @vscode/vsce

# 打包（在项目根目录下执行）
npm run package
```

执行成功后，项目根目录会生成一个名为 `codetour-<version>.vsix` 的文件。

> 如果没有 `npm run package` 脚本，也可以直接运行：
> ```bash
> vsce package --no-dependencies
> ```

### 在 VS Code 中安装

**方式一：通过命令面板（推荐）**

1. 打开 VS Code
2. 按 `Ctrl+Shift+P`（macOS：`Cmd+Shift+P`）打开命令面板
3. 输入并运行：`Extensions: Install from VSIX...`
4. 选择刚才生成的 `.vsix` 文件
5. 安装完成后重新加载窗口

**方式二：通过终端**

```bash
code --install-extension codetour-<version>.vsix
```

**方式三：通过扩展视图**

1. 点击左侧活动栏的扩展图标（或按 `Ctrl+Shift+X`）
2. 点击视图右上角的 `···`（更多操作）按钮
3. 选择 `Install from VSIX...`
4. 选择生成的 `.vsix` 文件

安装完成后，打开任意含有 `.tours/` 目录的工作区，即可在资源管理器侧边栏看到 `CodeTour` 树视图。

---

## 参考

### 导览文件格式

导览文件为 JSON，存放于 `.tours/`、`.vscode/tours/` 或 `.github/tours/` 目录：

```jsonc
{
  "title": "导览名称",
  "description": "可选描述",
  "ref": "main",          // 可选：关联的 git ref
  "isPrimary": true,      // 可选：标记为主导览，打开工作区时自动提示
  "steps": [
    {
      "file": "src/foo.ts",
      "line": 42,
      "title": "可选步骤标题",
      "description": "支持 Markdown 的步骤说明，包括 $LaTeX$ 公式"
    }
  ]
}
```

### 配置项

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `codetour.promptForWorkspaceTours` | `true` | 打开含导览的工作区时是否弹出提示 |
| `codetour.recordMode` | `lineNumber` | 步骤关联模式：`lineNumber`（行号）或 `pattern`（正则） |
| `codetour.showMarkers` | `true` | 是否在编辑器行号区显示导览标记 |
| `codetour.customTourDirectory` | `null` | 自定义导览文件存放目录 |

### 主要命令

| 命令 | 说明 |
|---|---|
| `CodeTour: Record Tour` | 开始录制新导览 |
| `CodeTour: Start Tour` | 选择并开始一个导览 |
| `CodeTour: End Tour` | 结束当前导览 |
| `CodeTour: Edit Tour` | 编辑当前导览 |
| `CodeTour: Resume Tour` | 恢复当前导览到当前步骤 |
| `CodeTour: Open Tour File...` | 从本地文件打开导览 |
| `CodeTour: Open Tour URL...` | 从 URL 打开已导出的导览 |
| `CodeTour: Hide/Show Tour Markers` | 切换行号区导览标记的显示 |
| `CodeTour: Reset Progress` | 重置导览进度记录 |
| `CodeTour: Refresh Tours` | 刷新导览列表 |