Usage

预览文档列表（含重复检测）

python scripts/doc_converter.py ~/Documents/reports --preview

执行转换

python scripts/doc_converter.py ~/Documents/reports --convert --confirm

转换指定文件

python scripts/doc_converter.py file1.pdf file2.pptx --convert --confirm

生成摘要（需先转换）

python scripts/doc_converter.py ~/Documents/reports --summarize
python scripts/doc_converter.py ~/Documents/reports --summarize --model qwen3:8b

三维度分类 + 软链接（需先摘要）

python scripts/doc_converter.py ~/Documents/reports --organize

分类 + 使用 AI 建议的文件名

python scripts/doc_converter.py ~/Documents/reports --organize --rename

全流程一步完成

python scripts/doc_converter.py ~/Documents/reports --convert --confirm --summarize --organize
# 含优化文件名
python scripts/doc_converter.py ~/Documents/reports --convert --confirm --summarize --organize --rename

JSON 格式输出

python scripts/doc_converter.py ~/Documents --preview --json

Arguments

Output Structure

转换输出在源文件夹的 .summaries/ 隐藏目录下：

{source}/
└── .summaries/
    ├── converted/              # markitdown 转换的 .md 文件
    │   ├── report.pdf.md
    │   ├── slides.pptx.md
    │   └── data.xlsx.md
    ├── briefs/                 # Ollama 生成的摘要
    │   ├── report.pdf.brief.md
    │   ├── slides.pptx.brief.md
    │   └── data.xlsx.brief.md
    ├── schemes/                # 软链接分类目录
    │   ├── by-topic/           # 按主题分类
    │   │   ├── AI技术/
    │   │   │   └── AI驱动产品管理指南.pptx -> ../../../../slides.pptx  # --rename
    │   │   └── 数据治理/
    │   │       └── C端数据治理规划.pdf -> ../../../../report.pdf       # --rename
    │   ├── by-usage/           # 按用途分类
    │   │   ├── 培训材料/
    │   │   └── 客户交付方案/
    │   └── by-client/          # 按客户分类
    │       ├── 沃尔沃/
    │       └── 通用方案/
    ├── mindmap.md              # Claude 生成的思维导图分类
    └── index.csv               # 转换索引（含 MD5、重复标记）

Dependencies

• Python 3.10+
• markitdown: pip install 'markitdown[all]'
• Ollama（摘要 + 分类）: brew install ollama + ollama pull qwen2.5:3b
• requests: pip install requests

Claude Workflow

Claude 使用此技能时，按以下步骤执行：

第 1 步：预览文档

运行预览命令，向用户展示文档列表和重复检测结果：

python doc-mindmap/scripts/doc_converter.py <路径> --preview

告知用户找到的文档数量、类型分布、总大小和重复文件情况，等待确认。

第 2 步：执行转换

用户确认后执行转换（重复文件自动跳过）：

python doc-mindmap/scripts/doc_converter.py <路径> --convert --confirm

第 3 步：生成摘要（Ollama 本地模型）

使用 Ollama 本地模型为每个文档生成摘要，不消耗 Claude 上下文窗口：

python doc-mindmap/scripts/doc_converter.py <路径> --summarize

也可以和 convert 一起执行：

python doc-mindmap/scripts/doc_converter.py <路径> --convert --confirm --summarize

第 4 步：三维度分类 + 软链接

使用 Ollama 对每个文档进行三维度分类（主题/用途/客户），同时为每个文档建议更清晰的文件名：

# 先不带 --rename 运行，展示分类结果和建议文件名
python doc-mindmap/scripts/doc_converter.py <路径> --organize

向用户展示分类结果和 AI 建议的文件名，询问是否使用优化文件名。如果用户同意：

python doc-mindmap/scripts/doc_converter.py <路径> --organize --rename

三套分类方案通过软链接同时存在于 .summaries/schemes/ 下，零额外磁盘占用。--rename 仅影响软链接名称，不修改原始文件。

第 5 步：预览分类结果

询问用户是否要在 Finder 中预览分类目录。如果用户同意：

1. 将 schemes 目录复制到桌面（保留软链接）：

cp -a <.summaries/schemes> ~/Desktop/文档分类-$(date +%Y%m%d)

1. 用 Finder 打开：

open ~/Desktop/文档分类-$(date +%Y%m%d)

用户可以在 Finder 中直观浏览三种分类方案，双击软链接即可打开原始文件。

第 6 步：生成思维导图

读取 .summaries/briefs/ 下的摘要文件，生成 .summaries/mindmap.md 思维导图分类文件。

第 7 步：展示结果

向用户展示：

1. 转换统计（成功/失败/跳过重复）
2. 重复文件列表及删除建议
3. 三维度分类概览
4. 思维导图分类预览

Credits

• markitdown - Microsoft 出品的文档转 Markdown 工具
• Ollama - 本地 LLM 运行框架
• 与 file-organizer 配合使用，先分类再整理

Weekly Installs

43

Repository

crazynomad/skills

GitHub Stars

9

First Seen

Jan 30, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykPass

Installed on

gemini-cli40

opencode38

cursor37

codex36

github-copilot34

amp32