# Sortspec Generator

> 为 Obsidian 文件夹生成 sortspec.md 排序配置文件。 触发场景： - 用户说"生成 sortspec"、"创建排序配置"、"为某文件夹生成 sortspec" - 用户想要自定义 Obsidian 文件列表排序 - 用户提到 Custom Sort 插件配置 - 用户整理 Obsidian 笔记文件夹时需要排序 即使没有明确说"sortspec"，只要涉及文件夹排序配置，也应使用此 skill。

- Skill: `treasoni/sortspec-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add treasoni/sortspec-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/treasoni/sortspec-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: treasoni (https://skillmd.com/u/treasoni)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/treasoni/sortspec-generator

---


# Sortspec Generator

为 Obsidian 文件夹生成 sortspec.md 排序配置文件。

## 输入规格

接受以下两种输入形式：

1. **完整路径**：`/Users/xxx/Notes/linux`
2. **文件夹名称**：`linux`、`Git 文件夹`（需在当前工作目录下查找）

**解析优先级**：
1. 用户直接给出的绝对路径
2. 用户给出的相对路径（相对于当前工作目录）
3. 用户提到的文件夹名称（在当前目录下模糊匹配）

## 边界条件处理

### 错误场景与输出模板

| 场景 | 输出模板 |
|------|---------|
| 文件夹路径不存在 | `❌ 未找到目标文件夹：{路径}。请确认路径是否正确。` |
| 文件夹中没有 .md 文件 | `⚠️ 文件夹 "{文件夹名}" 中没有可排序的 .md 文件。` |
| 只有 1 个 .md 文件 | `ℹ️ 文件夹中仅有一个笔记文件，无需生成排序配置。` |
| 已存在 sortspec.md | `📋 检测到已有 sortspec.md，以下是建议的新排序配置：【预览内容】\n\n是否覆盖？请确认后我将写入文件。` |

### 执行约束

```
IF 文件夹不存在 → 输出错误模板 → 停止
IF 文件夹内 .md 文件数 = 0 → 输出警告模板 → 停止
IF 文件夹内 .md 文件数 = 1 → 输出信息模板 → 停止
IF 已存在 sortspec.md → 输出预览 → 等待用户确认 → 确认后写入
ELSE → 输出预览 → 等待用户确认 → 确认后写入
```

**默认行为**：无论是否已存在 sortspec.md，都先生成预览内容展示给用户，等待确认后再写入文件。

## 工作流程

### 步骤 1：定位并扫描文件夹

使用 Glob 扫描目标文件夹下的所有 `.md` 文件：
- 排除 `sortspec.md` 本身
- 排除 `assets/` 文件夹
- 排除以 `.` 开头的隐藏文件

### 步骤 2：分析文件内容

对每个文件，按以下**硬性规则**识别类型：

#### 文件类型判定规则（按优先级从高到低匹配）

| 优先级 | 类型 | 判定条件（任一匹配即生效） |
|--------|------|---------------------------|
| 1 | MOC/索引 | 文件名含 `MOC` / `索引` / `目录` / `Index` / `index`（不区分大小写） |
| 2 | MOC/索引（备选） | 正文前 80 行中 wikilink 数量 ≥ 5 |
| 3 | 入门/安装 | 标题/文件名含 `安装` / `入门` / `教程` / `配置指南` / `快速开始` / `Getting Started` |
| 4 | 基础概念 | 标题/文件名含 `基础` / `概念` / `原理` / `是什么` / `简介` / `Introduction` |
| 5 | 进阶/高级 | 标题/文件名含 `进阶` / `高级` / `深入` / `优化` / `最佳实践` / `Advanced` |
| 6 | 故障排查 | 标题/文件名含 `问题` / `排查` / `错误` / `解决` / `FAQ` / `Troubleshooting` |
| 7 | 其他 | 未匹配以上任何规则 |

#### 冲突解决

- 同时命中"入门"和"MOC" → **优先判为 MOC**
- 同时命中"基础"和"进阶" → 按文件名关键词出现顺序，先出现者优先
- 同时命中多个同优先级规则 → 按字母顺序排序

### 步骤 3：确定排序顺序

按以下优先级排列：

```
1. MOC/索引文件（置顶）
2. 入门/安装/教程类
3. 基础概念类
4. 进阶/高级类
5. 故障排查/问题解决类
6. 其他文件（按字母排序）
```

同类文件排序规则：
- 有明确依赖关系的：被依赖的在前（如"安装"在"配置"前）
- 无依赖关系的：按文件名字母顺序

### 步骤 4：生成 sortspec.md

**标准模板**（参考 `/Users/zhqznc/Documents/项目/Git/sortspec.md`）：

```yaml
---
sorting-spec: |
  文件名1
  文件名2
  文件名3
---
```

**格式要求**：
- 文件名不带 .md 后缀
- 每个文件名单独一行，缩进 2 个空格
- 禁止使用 Custom Sort 的规则占位语法（如 default、a-z 等）
- 只允许显式列出文件名，每行一个
- 末尾的三个短横线必须保留

### 步骤 5：输出与写入

1. **先输出预览**：展示生成的 sortspec.md 内容
2. **检查是否已存在 sortspec.md**
   - 已存在：询问用户是否覆盖
   - 不存在：直接写入

## 完整示例

### 场景 1：正常生成

**用户输入**：
```
为 /Users/xxx/Notes/linux 文件夹生成 sortspec
```

**输出**：
```
📋 已扫描 /Users/xxx/Notes/linux，发现 9 个笔记文件。

生成的 sortspec.md：

---
sorting-spec: |
  linux MOC
  Ubuntu Server 安装教程
  Ubuntu Server SSH 配置指南
  Linux换源
  linux磁盘相关的知识
  linux的LVM管理
  linux的文件权限
  linux如何修改网络信息
  Ubuntu curl SSL连接问题排查
---

✅ 已写入 /Users/xxx/Notes/linux/sortspec.md
```

### 场景 2：已有 sortspec.md

**用户输入**：
```
给 linux 文件夹重新生成 sortspec
```

**输出**：
```
📋 检测到 /Users/xxx/Notes/linux/sortspec.md 已存在。

建议的新排序配置：

---
sorting-spec: |
  linux MOC
  Ubuntu Server 安装教程
  ...
---

是否覆盖现有文件？请回复"是"或"确认"继续。
```

### 场景 3：文件夹不存在

**用户输入**：
```
为 /Users/xxx/Notes/nonexistent 生成 sortspec
```

**输出**：
```
❌ 未找到目标文件夹：/Users/xxx/Notes/nonexistent

请确认路径是否正确，或提供有效的文件夹名称。
```

### 场景 4：没有 md 文件

**用户输入**：
```
为 assets 文件夹生成 sortspec
```

**输出**：
```
⚠️ 文件夹 "assets" 中没有可排序的 .md 文件。
```

## 判定规则速查表

| 类型 | 关键词（标题/文件名，不区分大小写） |
|------|-------------------------------------|
| MOC/索引 | MOC、索引、目录、Index |
| 入门/安装 | 安装、入门、教程、配置指南、快速开始、Getting Started |
| 基础概念 | 基础、概念、原理、是什么、简介、Introduction |
| 进阶/高级 | 进阶、高级、深入、优化、最佳实践、Advanced |
| 故障排查 | 问题、排查、错误、解决、FAQ、Troubleshooting |

## 注意事项

1. 保持配置简洁，不添加注释或额外说明
2. MOC 判定优先级最高，确保索引文件始终置顶
3. 无法识别类型的文件放入"其他"类别，按字母排序