Material Organizer

---
name: material-organizer
version: 1.0.0
description: |
  批量资料整理助手 — 把一堆素材提炼成结构化文档，或对本地目录进行扫描归档。
  UseWhen:
  1. 需要批量整理多个链接、PDF、文档或图片
  2. 需要提取要点、去重归类、按主题归档
  3. 需要生成带目录和来源溯源的研究笔记
  4. 用户提到"整理资料"、"资料归档"、"提炼要点"、"收藏夹整理"、"批量读取链接"、"生成研究笔记"、"帮我整理这些链接"、"把这些资料整理成文档"、"提取关键信息"
  5. 用户提到"整理下载目录"、"整理文件夹"、"帮我归档文件"、"扫描目录"、"清理文件"、"文件分类"
display_name: 资料整理
display_name_en: Material Organizer
description_zh: 批量资料整理工具，支持最多 30 项素材（URL/PDF/Word/图片/纯文本），自动提取要点、去重归类，输出带目录和来源溯源的结构化研究笔记，含关键词索引，支持保存为文件。
description_en: Batch material organizer that ingests up to 30 items (URLs, PDFs, Word docs, images, plain text), extracts key points, deduplicates, and outputs a structured research-note Markdown document with table of contents, source attribution, keyword index, and file export.
author: TPD
---

# 资料整理与结构化助手

两大模式：
- **内容整理模式**：批量导入链接 / PDF / 笔记 / 截图 → 提炼要点 + 分类归档 + 生成结构化研究笔记
- **目录整理模式**：扫描本地文件目录 → 分析分类 + 生成整理报告 + 可选执行归档

> 收藏夹塞满了却从没看？把资料链接发给我，帮你提炼出有用的东西。

---

## 何时触发

**触发（内容整理模式）**：用户提供 **2 项及以上**素材（URL / PDF / 文本片段 / 图片）并要求：
- 整理 / 归档 / 提炼 / 分类 / 生成笔记
- 批量读取链接 / 收藏夹整理
- 输出结构化文档 / 研究笔记 / Markdown 报告

**触发（目录整理模式）**：用户提到本地文件目录整理，如：
- 「帮我整理下载目录」「整理 ~/Downloads」「扫描这个文件夹」
- 「帮我归档文件」「清理文件夹」「文件分类」
- 用户提供一个本地路径并要求整理

**不触发**（转交其他 Skill）：
- 单篇文章/论文精读 → `paper-quick-reader`
- 纯翻译需求（无整理意图）→ `academic-translation`
- 用户只提供 1 项素材且无分类需求 → 直接回答，无需启动本 Skill
- 用户要求生成知识框架/思维导图 → `knowledge-framework-builder`

---

## 输入规范

### 内容整理模式

| 字段 | 说明 |
|------|------|
| 素材列表 | 最多 30 项/次；每项可为 URL / PDF / Word / 图片 / 纯文本片段 |
| 主题提示（可选） | 用户指定分类维度，如| 输出偏好（可选） | 详细 / 简洁 / 仅摘要；默认详细 |
| 保存文件（可选） | 是否将报告保存为 Markdown 文件；默认询问用户 |

---

## 核心工作流

---

### 🗂️ 目录整理模式工作流（4 步）

#### Step D0：扫描目录

收到目录路径后，**立即用 `list_dir` / `terminal ls` 扫描目录**，统计：
- 文件/目录总数、总大小
- 各文件类型分布
- 识别重复文件（带 ` 2`、` 3`、`(1)`、`(2)` 等编号）
- 识别空文件、`.part` 未完成下载
- 识别超大文件（>500MB）

扫描完成后，输出**目录概览**并向用户确认整理方案：

```
📊 已扫描 [路径]，共 N 个文件/目录，总大小 X GB

发现以下主要类别：
1️⃣ [类别名]（约 N 项）— 示例：skill-assistant、paper-reader...
2️⃣ [类别名]（约 N 项）— 示例：合同、简历、大纲...
...

🤔 你希望我如何整理？请告诉我：

1. 整理方式：
   📄 仅生成整理报告（推荐）— 不移动文件，生成分类报告 + 清理建议
   📁 生成整理脚本 — 生成 shell 脚本，你审核后执行
   🗂️ 直接整理 — 我帮你直接移动文件到分类目录

2. 分类维度：
   🏷️ 按主题（技能、工作、个人、工具等）
   📂 按文件类型（文档、代码、图片、视频、压缩包等）
   📅 按时间（按年份/月份归档）

3. 是否提供清理建议：
   ✅ 是（标记重复文件、空文件、超大文件，默认）
   ❌ 否

4. 报告格式：
   📝 Markdown 文档（默认）
   🌐 HTML 报告（含目录导航 + 分类高亮，浏览器直接查看）
   📦 两者都要（MD + HTML）
   📊 Excel 表格
```

#### Step D1：制定整理方案

根据用户选择，制定分类方案：
- **按主题**：根据文件名/内容语义自动聚类，识别项目、工具、个人文档等
- **按文件类型**：文档/代码/图片/视频/压缩包/安装包等
- **按时间**：按文件修改时间归入年份/月份目录

若目录已有分类文件夹（如 `01-文档`、`02-图片`），优先沿用已有结构，新增补充分类。

#### Step D2：生成整理报告

输出标准「目录整理报告」，格式见 [references/output-schema.md](references/output-schema.md) 的目录整理模板。

报告必须包含：
- 📊 统计总览（文件数、大小、类别分布）
- 🗂️ 主题分类详情（每类含代表性文件示例）
- 🧹 清理建议（按优先级分级：🔴 高 / 🟡 中 / 🟢 低）
- ⚠️ 需确认的重要文件（证书、合同、毕业证等）
- 📋 建议的目录结构
- 🎯 下一步行动计划（分阶段）

**按 Step D0 中用户选择的报告格式生成文件**：
- 选「仅 Markdown」→ 生成 `organize-report-{YYYYMMDD}.md`
- 选「仅 HTML」→ 生成 `organize-report-{YYYYMMDD}.html`（含目录导航 + 分类高亮）
- 选「两者都要」（默认）→ 同时生成 `.md` 和 `.html` 两份
- 选「Excel 表格」→ 生成 `organize-report-{YYYYMMDD}.xlsx`

#### Step D3：执行整理（按用户选择）

- **仅报告**：保存报告文件，附上后续操作菜单
- **生成脚本**：生成 `organize.sh`，包含 `mkdir` + `mv` 命令，用户审核后执行
- **直接整理**：逐步执行 `mv` 命令，每步播报进度，完成后输出结果汇总

**执行完成后**，附上交互菜单：
```
✅ 整理完成！
   📄 报告已保存至：[文件路径]

您可以继续：
  [A] 对某个子目录深入整理
  [B] 生成自动化清理脚本（删除重复/空文件）
  [C] 按新维度重新分类
  [D] 导出为 Excel 表格
```

---

### 📚 内容整理模式工作流（6 步）

#### Step 0：需求确认（首次交互必做）

收到素材后，**先向用户确认以下信息**（若用户已在消息中明确说明则跳过对应项）：

```
📋 已收到 N 项素材，开始整理前请确认：

1. 分类方式：希望按什么维度分类？
   - 🏷️ 自动聚类（默认，AI 根据内容自动分组）
   - 📅 按时间线
   - 🔧 按技术栈 / 主题
   - 📌 按重要程度
   - 其他（请说明）

2. 输出详细程度：
   - 📄 详细（含核心观点 + 摘录 + 标签，默认）
   - 📝 简洁（仅标题 + 核心观点）
   - 📋 仅摘要（每条一句话）

3. 报告格式：
   - 📝 仅 Markdown（.md，默认）
   - 🌐 仅 HTML（含目录导航 + 标签高亮，浏览器直接查看）
   - 📦 两者都要（MD + HTML）

4. 是否保存为文件？（默认：是，保存到当前目录）

如无特殊要求，直接回复「开始」即可按默认设置处理。
```

- **≤5 项素材**：可跳过确认，直接按默认设置处理，处理前简短说明
- **6-30 项素材**：必须等待用户确认（或用户已明确授权则直接开始）
- **用户回复「开始」或「默认」**：按默认设置立即处理

#### Step 1：素材清单确认与分批规划

确认需求后，输出清单预览并制定处理计划：

```
📋 已接收 N 项素材，处理计划如下：
  - [1] URL: https://...
  - [2] PDF: xxx.pdf
  - [3] 文本片段: "..."
  ...
分类方式：[用户选择 / 自动聚类]
输出详细度：[详细 / 简洁 / 仅摘要]
处理计划：分 K 批（每批 8-10 项）→ 预计输出 X 个主题分类。
```

- 每批 **8-10 项**处理，防止 context 溢出，批次间汇总后继续
- 素材超过 30 项：提示用户分批提交，建议按主题拆分

**批次进度播报**：每完成一批后输出进度行：
```
✅ 第 K/N 批处理完成（已处理 M 项，剩余 R 项）→ 继续处理下一批...
```

#### Step 2：逐项内容读取与提炼

对每项素材执行（**必做项**优先，**可选项**视内容质量决定是否执行）：

**必做（每项都要执行）**：
1. **读取内容**：URL 用 `web_fetch` 抓取正文；PDF/Word 用 `read_file` 提取文本；图片 OCR 识别文字；纯文本直接处理
2. **提炼要点**：提取核心观点（≤5条）、关键数据/引用、作者/来源信息
3. **记录溯源**：保留原始来源链接/文件名

**可选（内容足够丰富时执行）**：
4. **证据分级**：每条核心观点标注可信度 `🟢 High` / `🟡 Medium` / `🔴 Low`
5. **注解分类**：识别内容中的 `❓Question` / `✅ TODO` / `💡 Idea` / `⚡ Disagreement`
6. **打标签**：自动生成 2-4 个主题标签（如 `#AI` `#效率工具` `#研究方法`）
7. **场景化适配**：根据资料类型调整提炼结构：
   - **学术类**：摘要 → 方法 → 结论 → 局限性
   - **技术类**：功能 → 使用场景 → 优缺点 → 替代方案
   - **新闻/资讯类**：事件 → 影响 → 各方观点 → 后续关注点
   - **工具/产品类**：核心功能 → 目标用户 → 定价 → 竞品对比

> ⚠️ **防幻觉约束**（强制执行）：
> - 所有核心观点必须来自原文，**不得补充、推断或编造**原文未提及的内容
> - 关键摘录必须是**原文逐字引用**，不得改写或意译，用 `>` 引用块标注
> - 若原文信息不足，宁可标注 `⚠️ 信息不足` 留空，不得用猜测填充
> - 数字、百分比、日期等数据必须与原文完全一致，不得估算
> - 所有数据必须来自 `web_fetch` / `read_file` 的真实内容，**严禁编造数据**

详细提炼规则见 [references/extraction-rules.md](references/extraction-rules.md)。

#### Step 3：去重、合并与矛盾检测

满足以下**任一条件**即触发去重合并：
- 内容相似度 > 70%（核心观点高度重叠）
- 来源完全相同（同一 URL 被提交多次）
- 标题相同/近似（编辑距离 < 3，同一文章不同版本）

合并规则：
- **跨源合并**：合并为一条，保留所有来源，在条目末尾添加 `🔀 已与条目 #N 合并（相似度 XX%）`（独立成行）
- **矛盾检测**：同一主题下观点相反的条目，标注 `⚡ 观点对立` 并列保留，不强制合并
- **不合并情况**：来源观点相反 / 时间跨度 > 2 年 / 用户明确要求保留所有条目

去重策略见 [references/dedup-strategy.md](references/dedup-strategy.md)。

#### Step 4：主题分类归档

- 若用户指定分类维度，按指定维度分组
- 若未指定，自动聚类（按内容相似性 + 标签）
- 每个主题生成小标题 + 条目数量统计
- 无法归类的条目放入「📥 收件筐」并说明原因

分类规则见 [references/classification-rules.md](references/classification-rules.md)。

#### Step 5：生成结构化文档

输出标准「研究笔记」Markdown，格式见 [references/output-schema.md](references/output-schema.md)。

文档末尾附加**关键词索引**（来自 qclaw doc-organizer 最佳实践）：

```markdown
---

## 🔑 关键词索引

| 关键词 | 出现条目 | 频次 |
|--------|---------|------|
| #AI | #1, #3, #4 | 3 |
| #效率工具 | #1, #2 | 2 |
| ...  | ... | ... |
```

#### Step 6：保存文件并交付

**文件保存**（强制执行，除非用户明确拒绝）：
- 默认文件名前缀：`research-notes-{主题}-{YYYYMMDD}`
- 默认保存路径：当前工作目录
- 同时生成关键词索引文件：`keyword-index-{主题}-{YYYYMMDD}.md`

**按 Step 0 中用户选择的报告格式生成文件**：
- 选「仅 MD」→ 生成 `research-notes-{主题}-{YYYYMMDD}.md`
- 选「仅 HTML」→ 生成 `research-notes-{主题}-{YYYYMMDD}.html`（含目录导航 + 标签高亮 + 关键词索引）
- 选「两者都要」（默认）→ 同时生成 `.md` 和 `.html` 两份文件

**输出完成后**，附上交互菜单：
```
📎 研究笔记已生成！
   📄 已保存至：research-notes-{主题}-{YYYYMMDD}.md
   🌐 HTML 版本：research-notes-{主题}-{YYYYMMDD}.html
   🔑 关键词索引：keyword-index-{主题}-{YYYYMMDD}.md

您可以继续：
  [A] 重新保存到指定路径
  [B] 按新维度重新分类（请告诉我分类方式）
  [C] 深入精读某条目（请告诉我条目编号）
  [D] 补充更多素材（继续追加）
  [E] 生成知识框架图（调用 knowledge-framework-builder）
```

---

## 输出结构

完整格式规范见 [references/output-schema.md](references/output-schema.md)。

节点顺序（固定）：
1. `📊 提炼总览`（统计表 + 分类目录）
2. `✅ 可操作项汇总`（Action Items，无则省略）
3. 各主题分类节（含条目详情 + 证据分级）
4. `📥 收件筐`（无法归类的条目，无则省略）
5. `📌 跨主题关键洞察`
6. `⚡ 观点矛盾记录`（无则省略）
7. `⚠️ 处理异常记录`（无则省略）
8. `🔑 关键词索引`

---

## 场景化适配

根据资料主题自动调整整理结构：

| 资料类型 | 提炼重点 | 分类维度建议 |
|---------|---------|------------|
| 学术论文 / 研究报告 | 摘要→方法→结论→局限性 | 按研究方向 / 方法论 |
| 技术文档 / 教程 | 功能→使用场景→优缺点 | 按技术栈 / 难度 |
| 新闻 / 资讯 | 事件→影响→各方观点 | 按时间线 / 话题 |
| 工具 / 产品评测 | 核心功能→定价→竞品 | 按使用场景 / 类别 |
| 混合类型 | 按内容实质路由 | 自动聚类（默认） |

---

## 异常处理

| 情况 | 处理策略 |
|------|---------|
| URL 无法访问 | 标注 `⚠️ 无法读取`，跳过，继续处理其他条目 |
| 网络超时（>15s）| 重试 1 次；仍失败则标注 `⚠️ 超时`，记录 URL，继续处理其余条目 |
| PDF 加密/损坏 | 标注 `⚠️ 文件异常`，提示用户重新上传 |
| 图片文字不清晰 | 尽力 OCR，标注置信度低的内容 |
| 内容为空/极短（<50字）| 标注 `⚠️ 内容不足`，仅保留来源信息，放入收件筐 |
| 需要登录/付费墙 | 标注 `⚠️ 需登录/访问受限`，跳过，记录 URL |
| 超过 30 项 | 提示分批：「您提交了 N 项素材，超过单次上限（30项）。建议按主题拆分：第一批发送前 30 项，处理完成后再发送剩余 N-30 项；或按主题分组，每组不超过 30 项分批提交。」 |

---

## 不在范围

- 单篇论文深度精读 → 用 `paper-quick-reader`
- 学术翻译 → 用 `academic-translation`
- 知识框架/思维导图 → 用 `knowledge-framework-builder`
- 简历整理 → 用 `resume-assistant`
- 实时网络搜索（本 Skill 只处理用户提供的素材，不主动搜索）