Back to Details

import-track

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Your Task

你的任务

Input: $ARGUMENTS
Import a track markdown file (.md) to the correct album location based on config.
输入：$ARGUMENTS
根据配置将曲目Markdown文件（.md）导入到正确的专辑目录中。

Import Track Skill

导入曲目Skill

You move track markdown files to the correct location in the user's content directory.
你需要将曲目Markdown文件移动到用户内容目录中的正确位置。

Step 1: Parse Arguments

步骤1：解析参数

Expected format: 
<file-path> <album-name> [track-number]
Examples:
  • ~/Downloads/track.md sample-album 03
  • ~/Downloads/t-day-beach.md sample-album 03
  • ~/Downloads/03-t-day-beach.md sample-album
    (number already in filename)
If arguments are missing, ask:
Usage: /import-track <file-path> <album-name> [track-number]

Example: /import-track ~/Downloads/track.md sample-album 03
预期格式：
<file-path> <album-name> [track-number]
示例：
  • ~/Downloads/track.md sample-album 03
  • ~/Downloads/t-day-beach.md sample-album 03
  • ~/Downloads/03-t-day-beach.md sample-album
    （文件名中已包含编号）
如果参数缺失，请提示：
Usage: /import-track <file-path> <album-name> [track-number]

Example: /import-track ~/Downloads/track.md sample-album 03

Step 2: Find Album and Resolve Path via MCP

步骤2：通过MCP查找专辑并解析路径

  1. Call 
    find_album(album_name)
    — fuzzy match by name, slug, or partial. Returns album metadata including genre.
  2. Call 
    resolve_path("tracks", album_slug)
    — returns the full tracks directory path
If album not found, MCP returns available albums:
Error: Album "{album-name}" not found.

Available albums:
[list from MCP response]

Create album first with: /new-album {album-name} <genre>
  1. 调用
    find_album(album_name)
    ——按名称、slug或部分内容进行模糊匹配。返回包含流派的专辑元数据。
  2. 调用
    resolve_path("tracks", album_slug)
    ——返回完整的曲目目录路径
如果未找到专辑，MCP会返回可用专辑列表：
Error: Album "{album-name}" not found.

Available albums:
[list from MCP response]

Create album first with: /new-album {album-name} <genre>

Step 4: Construct Target Path

步骤4：构建目标路径

The target path is ALWAYS:
{content_root}/artists/{artist}/albums/{genre}/{album}/tracks/{XX}-{track-name}.md
Example with:
  • content_root: ~/bitwize-music
  • artist: bitwize
  • genre: electronic
    (found from album location)
  • album: sample-album
  • track-number: 03
  • track-name: t-day-beach
Result:
~/bitwize-music/artists/bitwize/albums/electronic/sample-album/tracks/03-t-day-beach.md
Track numbering:
  • If track number provided, use it (zero-padded: 
    03
    )
  • If filename already has number prefix (e.g., 
    03-name.md
    ), preserve it
  • If neither, ask user for track number
目标路径必须为：
{content_root}/artists/{artist}/albums/{genre}/{album}/tracks/{XX}-{track-name}.md
示例：
  • content_root: ~/bitwize-music
  • artist: bitwize
  • genre: electronic
    （从专辑目录中获取）
  • album: sample-album
  • track-number: 03
  • track-name: t-day-beach
结果：
~/bitwize-music/artists/bitwize/albums/electronic/sample-album/tracks/03-t-day-beach.md
曲目编号规则：
  • 如果提供了曲目编号，则使用该编号（需补零：
    03
    ）
  • 如果文件名已包含编号前缀（例如
    03-name.md
    ），则保留该编号
  • 如果两者都没有，请询问用户获取曲目编号

Step 5: Move File

步骤5：移动文件

bash
mv "{source_file}" "{target_path}"
bash
mv "{source_file}" "{target_path}"

Step 6: Confirm

步骤6：确认

Report:
Moved: {source_file}
   To: {target_path}
反馈：
Moved: {source_file}
   To: {target_path}

Error Handling

错误处理

Source file doesn't exist:
Error: File not found: {source_file}
Config file missing:
Error: Config not found at ~/.bitwize-music/config.yaml
Run /configure to set up.
Album not found:
Error: Album "{album-name}" not found.
Create it first with: /new-album {album-name} <genre>
Track already exists:
Warning: Track already exists at destination.
Overwrite? (The original was not moved)
源文件不存在：
Error: File not found: {source_file}
配置文件缺失：
Error: Config not found at ~/.bitwize-music/config.yaml
Run /configure to set up.
专辑未找到：
Error: Album "{album-name}" not found.
Create it first with: /new-album {album-name} <genre>
曲目已存在：
Warning: Track already exists at destination.
Overwrite? (The original was not moved)

Examples

示例

/import-track ~/Downloads/t-day-beach.md sample-album 03
Config has:
yaml
paths:
  content_root: ~/bitwize-music
artist:
  name: bitwize
Album found at: 
~/bitwize-music/artists/bitwize/albums/electronic/sample-album/
Result:
Moved: ~/Downloads/t-day-beach.md
   To: ~/bitwize-music/artists/bitwize/albums/electronic/sample-album/tracks/03-t-day-beach.md
/import-track ~/Downloads/t-day-beach.md sample-album 03
配置内容：
yaml
paths:
  content_root: ~/bitwize-music
artist:
  name: bitwize
找到的专辑路径：
~/bitwize-music/artists/bitwize/albums/electronic/sample-album/
结果：
Moved: ~/Downloads/t-day-beach.md
   To: ~/bitwize-music/artists/bitwize/albums/electronic/sample-album/tracks/03-t-day-beach.md

Common Mistakes

常见错误

❌ Don't: Manually read config and search for albums

❌ 不要：手动读取配置并搜索专辑

Wrong:
bash
cat ~/.bitwize-music/config.yaml
find . -name "README.md" -path "*albums/$album_name*"
Right:
undefined
错误做法：
bash
cat ~/.bitwize-music/config.yaml
find . -name "README.md" -path "*albums/$album_name*"
正确做法：
undefined

Use MCP to find album and resolve path

使用MCP查找专辑并解析路径

find_album(album_name) → returns album metadata with genre resolve_path("tracks", album_slug) → returns full tracks directory path

**Why it matters:** MCP handles config reading, fuzzy matching, and path resolution in single calls.
find_album(album_name) → 返回包含流派的专辑元数据 resolve_path("tracks", album_slug) → 返回完整的曲目目录路径

**原因**：MCP可通过单次调用处理配置读取、模糊匹配和路径解析。

❌ Don't: Forget the tracks/ subdirectory

❌ 不要：忘记tracks/子目录

Wrong destination:
{album_path}/01-track.md
错误的目标路径：
{album_path}/01-track.md

Example: ~/bitwize-music/artists/bitwize/albums/electronic/sample-album/01-track.md

示例：~/bitwize-music/artists/bitwize/albums/electronic/sample-album/01-track.md


**Correct destination:**
{album_path}/tracks/01-track.md

**正确的目标路径**：
{album_path}/tracks/01-track.md

Example: ~/bitwize-music/artists/bitwize/albums/electronic/sample-album/tracks/01-track.md

示例：~/bitwize-music/artists/bitwize/albums/electronic/sample-album/tracks/01-track.md


**Why it matters:** Tracks always go in the `tracks/` subdirectory within the album folder.

**原因**：曲目必须存放在专辑文件夹内的`tracks/`子目录中。

❌ Don't: Skip track number validation

❌ 不要：跳过曲目编号验证

Wrong:
bash
undefined
错误做法：
bash
undefined

Not validating track number format

未验证曲目编号格式

mv track.md {album_path}/tracks/$track_num-track.md
mv track.md {album_path}/tracks/$track_num-track.md

Could result in: 3-track.md instead of 03-track.md

可能导致：3-track.md 而非 03-track.md


**Right:**
```bash

**正确做法**：
```bash

Ensure zero-padding

确保补零

track_num=$(printf "%02d" $track_num) mv track.md {album_path}/tracks/$track_num-track.md
track_num=$(printf "%02d" $track_num) mv track.md {album_path}/tracks/$track_num-track.md

Results in: 03-track.md

结果：03-track.md


**Why it matters:** Track numbers must be zero-padded (01, 02, 03...) for proper sorting.

**原因**：曲目编号必须补零（01、02、03...）以保证排序正确。

❌ Don't: Assume album location without searching

❌ 不要：未搜索就假设专辑位置

Wrong:
bash
undefined
错误做法：
bash
undefined

Guessing album is in electronic genre

猜测专辑属于electronic流派

mv track.md ~/music-projects/artists/bitwize/albums/electronic/sample-album/tracks/

**Right:**
mv track.md ~/music-projects/artists/bitwize/albums/electronic/sample-album/tracks/

**正确做法**：

Use MCP to find the album (handles genre resolution)

使用MCP查找专辑（自动处理流派解析）

find_album(album_name) → returns album metadata including genre and path

**Why it matters:** Albums are organized by genre. `find_album` resolves the genre automatically.
find_album(album_name) → 返回包含流派和路径的专辑元数据

**原因**：专辑按流派分类。`find_album`会自动解析流派。