# todo-tree-lens

**Repository Path**: github-9819409/todo-tree-lens

## Basic Information

- **Project Name**: todo-tree-lens
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Todo Tree Navigator

![插件主界面](media/readme/index.png)

[English](#english) | [简体中文](#zh-cn)

<h2 id="english">English</h2>

`Todo Tree Navigator` is a VS Code extension for scanning structured todo markers, browsing them in a dedicated sidebar, and inserting them quickly while you type.

![Todo Tree Navigator screenshot](./media/readme/PixPin_2026-09-16_15-39-21.png)

## Features

- Scan structured markers such as `// @TODO:`, `// @FIXME`, and `<!-- @BUG: -->`
- Show results in a dedicated Activity Bar view, grouped by file
- Search by file name or marker content, and filter by tag
- Jump to the exact file and line when you click an item
- Type `todo` or `/todo` to open a quick tag picker and insert a marker snippet
- Manage tag name, color, and note in the built-in Tag Manager
- Support both English and Simplified Chinese UI

## Installation

Install the extension in one of these ways:

1. Search for `Todo Tree Navigator` in the VS Code Extensions view when it is available in a marketplace.
2. Or install a packaged `.vsix` file from `Extensions > ... > Install from VSIX...`.

After installation, open any workspace or folder and the extension will start scanning automatically.

## Recognized Marker Formats

The extension scans only structured markers that start with `@tag`.

Line comments:

```text
// @TODO: Refactor this logic
// @FIXME waiting for backend API
// @BUG: Wrong calculation here
```

HTML comments:

```html
<!-- @TODO: Update this section -->
<!-- @BUG: Layout breaks on mobile -->
```

Notes:

- Plain comments such as `// TODO` or `<!-- TODO -->` are not scanned.
- In `.vue` files, markers inside `<template>` use HTML comment style, while `script` and `style` areas use line comment style.

## Sidebar Usage

Open the `Todo Tree Navigator` icon in the Activity Bar to use the sidebar.

From there you can:

- browse todos grouped by file
- expand or collapse file groups
- search by file name, tag note, or marker text
- filter the list by tag
- click any todo item to jump to its source location
- use the title bar buttons for refresh, settings, tag management, expand all, and collapse all

## Quick Insert

When you type `todo` or `/todo` in the editor, the extension opens the saved tag picker automatically.

After you choose a tag, the trigger text is replaced with a snippet and the cursor is placed at the content position.

Examples:

```text
// @TODO: 
```

```html
<!-- @TODO: -->
```

You can customize the text after the tag with `todoTreeNavigator.quickInsertSuffix`.

## Tag Manager

Open Tag Manager from the sidebar title bar or the Command Palette.

With Tag Manager you can:

- add a new tag
- edit an existing tag
- set a color for each tag
- write a note shown in quick pick and the sidebar
- delete tags you no longer use

Tag rules:

- a tag must start with a letter
- it may contain letters, numbers, underscores, and hyphens

## Settings

Search for `todoTreeNavigator` in VS Code Settings.

| Setting | Description |
| --- | --- |
| `todoTreeNavigator.tagDefinitions` | Main tag configuration, including tag name, color, and note. |
| `todoTreeNavigator.includeGlobs` | File patterns to include in scanning. |
| `todoTreeNavigator.excludeGlobs` | File patterns to exclude from scanning. |
| `todoTreeNavigator.caseSensitive` | Whether marker matching is case-sensitive. |
| `todoTreeNavigator.defaultExpanded` | Default sidebar file group state: `expanded` or `collapsed`. |
| `todoTreeNavigator.language` | Extension UI language: `auto`, `zh-CN`, or `en`. |
| `todoTreeNavigator.quickInsertSuffix` | Text appended after an inserted tag, such as `: `. |
| `todoTreeNavigator.maxFiles` | Maximum number of files scanned per refresh. |
| `todoTreeNavigator.maxFileSizeKB` | Maximum file size scanned for markers. |

Legacy setting:

- `todoTreeNavigator.tags` is kept for compatibility, but `todoTreeNavigator.tagDefinitions` is the recommended option.

## Commands

Available commands in the Command Palette:

- `Todo Tree Navigator: Refresh`
- `Todo Tree Navigator: Settings`
- `Todo Tree Navigator: Manage Tags`
- `Todo Tree Navigator: Add Tag`
- `Todo Tree Navigator: Edit Tag`
- `Todo Tree Navigator: Remove Tag`
- `Todo Tree Navigator: Insert Tag`

## Troubleshooting

If the sidebar shows no results, check these points first:

1. A workspace or folder is open in VS Code.
2. Your comments use the supported `@TAG` format.
3. The tag exists in Tag Manager or in `todoTreeNavigator.tagDefinitions`.
4. The file is not excluded by `excludeGlobs`.
5. The file count or file size is not blocked by `maxFiles` or `maxFileSizeKB`.

## License

[MIT](./LICENSE.md)

---

<h2 id="zh-cn">简体中文</h2>

`Todo Tree Navigator` 是一个面向 VS Code 的待办标识管理插件，用来扫描结构化注释标识、在侧边栏集中浏览，并提供更顺手的快速插入体验。

![Todo Tree Navigator 截图](./media/readme/PixPin_2026-09-16_15-39-21.png)

## 功能简介

- 扫描结构化标识，例如 `// @TODO:`、`// @FIXME`、`<!-- @BUG: -->`
- 在 Activity Bar 中提供独立的 `Todo Tree Navigator` 侧边栏视图
- 按文件分组展示结果，并支持展开、收起、搜索和按标识筛选
- 点击任意条目可直接跳转到对应文件和行号
- 在编辑器中输入 `todo` 或 `/todo`，自动弹出标识选择器并插入注释片段
- 内置“标识管理”，可维护标识名称、颜色和备注
- 支持简体中文与英文界面

## 安装方式

你可以通过以下方式安装：

1. 当扩展发布到市场后，在 VS Code 扩展商店中搜索 `Todo Tree Navigator` 安装。
2. 或者通过 `扩展 > ... > Install from VSIX...` 安装打包好的 `.vsix` 文件。

安装完成后，打开任意工作区或文件夹，插件就会自动开始扫描。

## 支持的标识格式

插件只会扫描以 `@标识` 开头的结构化注释。

行注释格式：

```text
// @TODO: 这里后续要重构
// @FIXME 等后端接口好了再处理
// @BUG: 这里有计算错误
```

HTML 注释格式：

```html
<!-- @TODO: 这里需要补内容 -->
<!-- @BUG: 移动端布局异常 -->
```

补充说明：

- 普通注释例如 `// TODO`、`<!-- TODO -->` 不会被扫描。
- 在 `.vue` 文件中，`<template>` 区域会自动使用 HTML 注释格式，`script` 和 `style` 区域会使用行注释格式。

## 侧边栏怎么用

安装后，在 VS Code 左侧 Activity Bar 打开 `Todo Tree Navigator` 图标即可看到侧边栏。

你可以在这里：

- 按文件浏览所有待办标识
- 展开或收起文件分组
- 搜索文件名、注释内容或备注
- 按标识类型筛选列表
- 点击条目直接跳转到源码位置
- 使用标题栏按钮执行刷新、设置、标识管理、全部展开、全部收起

## 快速插入

在编辑器里输入 `todo` 或 `/todo` 时，插件会自动弹出已保存的标识选择框。

选择一个标识后，触发词会被替换成注释片段，并把光标放到正文输入位置。

示例：

```text
// @TODO:
```

```html
<!-- @TODO: -->
```

你也可以通过 `todoTreeNavigator.quickInsertSuffix` 自定义标识后面自动追加的文本，例如 `: `。

## 标识管理

可以通过侧边栏标题栏按钮，或者命令面板中的 `Todo Tree Navigator: Manage Tags` 打开“标识管理”。

在这里你可以：

- 新增标识
- 编辑已有标识
- 为每个标识设置颜色
- 添加备注，备注会显示在选择器和侧边栏提示中
- 删除不再需要的标识

标识命名规则：

- 必须以字母开头
- 只能包含字母、数字、下划线和连字符

## 配置项

在 VS Code 设置中搜索 `todoTreeNavigator`，可以看到这些主要配置：

| 配置项 | 说明 |
| --- | --- |
| `todoTreeNavigator.tagDefinitions` | 主要标识配置，包含标识名、颜色和备注。 |
| `todoTreeNavigator.includeGlobs` | 扫描时包含的文件规则。 |
| `todoTreeNavigator.excludeGlobs` | 扫描时排除的文件规则。 |
| `todoTreeNavigator.caseSensitive` | 是否区分大小写匹配标识。 |
| `todoTreeNavigator.defaultExpanded` | 侧边栏文件分组默认展开还是收起，可选 `expanded` / `collapsed`。 |
| `todoTreeNavigator.language` | 插件界面语言，可选 `auto`、`zh-CN`、`en`。 |
| `todoTreeNavigator.quickInsertSuffix` | 快速插入时标识后自动追加的文本，例如 `: `。 |
| `todoTreeNavigator.maxFiles` | 每次刷新最多扫描多少个文件。 |
| `todoTreeNavigator.maxFileSizeKB` | 单个文件允许扫描的最大大小（KB）。 |

兼容旧版本的配置项：

- `todoTreeNavigator.tags` 仍然保留，但更推荐使用 `todoTreeNavigator.tagDefinitions`。

## 命令列表

命令面板中可用的命令包括：

- `Todo Tree Navigator: Refresh`
- `Todo Tree Navigator: Settings`
- `Todo Tree Navigator: Manage Tags`
- `Todo Tree Navigator: Add Tag`
- `Todo Tree Navigator: Edit Tag`
- `Todo Tree Navigator: Remove Tag`
- `Todo Tree Navigator: Insert Tag`

## 常见排查

如果侧边栏没有显示结果，可以优先检查下面几点：

1. 当前是否已经打开工作区或文件夹。
2. 注释是否使用了受支持的 `@TAG` 格式。
3. 对应标识是否存在于“标识管理”或 `todoTreeNavigator.tagDefinitions` 中。
4. 文件是否被 `excludeGlobs` 排除了。
5. 文件数量或文件大小是否超过了 `maxFiles`、`maxFileSizeKB` 限制。

## License

[MIT](./LICENSE.md)