---
name: long-audio-to-obsidian
description: 将语音转写项目输出的复杂文件结构整理合并为适合 Obsidian 归档的 Markdown 文档
license: Apache-2.0
author: github/cafe3310
depends_on_skill: []
depends_on_binary:
  - python3
---

# Long Audio to Obsidian Archiver

此技能将散乱的语音转写项目文件整理成结构清晰的 Markdown 文档，便于在 Obsidian 等知识库中归档。

它采用 **"Agent 规划 + 脚本执行"** 的模式：
1.  **Agent (你)**：负责理解目录结构、识别文件类型、对分段文件进行逻辑排序（例如按行号 1-200, 201-400），并生成合并计划。
2.  **Script**：负责根据你的计划，机械地读取文件并生成 Markdown。

## 使用场景

当用户要求将一个包含多个原始音频、数十个转写分段、以及各种说明文档的目录“整理归档”时使用。

## 工作流 (Workflow)

### 1. 调查与分析 (Survey & Analyze)

首先，使用 `list_directory` (必要时配合 `glob`) 扫描目标项目目录。
你需要回答以下问题：
-   哪些是**原始录音文本**？（通常在 `1-原始文件` 或类似目录）
-   哪些是**最终输出的分段脚本**？（通常在 `5-最终输出`，文件名包含行号如 `_1-200`）
    -   *关键任务*：你需要根据文件名中的数字对它们进行正确排序。
-   哪些是**项目元数据**？（日志、术语表、背景要求等）
-   哪些是**衍生知识/问答**？（`5-最终输出` 中非分段的 Markdown 文件）

### 2. 生成合并配置 (Generate Configuration)

基于你的分析，构建一个 JSON 配置文件。不要直接输出给用户，而是准备写入临时文件。

**JSON 结构定义**：

```json
{
  "output_dir": "目标项目路径/obsidian_archive",
  "tasks": [
    {
      "filename": "1-原始录音汇总.md",
      "title": "原始录音汇总",
      "sections": [
        {
          "title": "文件1.txt",
          "path": "绝对路径或相对路径/文件1.txt",
          "syntax": "text"
        }
      ]
    },
    {
      "filename": "2-最终输出脚本汇总.md",
      "title": "最终输出脚本汇总",
      "sections": [
        {
          "title": "Part 1 (1-200)",
          "path": "路径/output_1-200.txt",
          "syntax": "text"
        },
        {
          "title": "Part 2 (201-400)",
          "path": "路径/output_201-400.txt",
          "syntax": "text"
        }
        // Agent 必须确保这里的顺序是正确的！
      ]
    }
    // ... 继续为“整理要求汇总”和“知识整理汇总”创建任务
  ]
}
```

### 3. 执行合并 (Execute)

1.  使用 `write_file` 将 JSON 配置保存为临时文件，例如 `merge_plan.json`。
2.  调用脚本执行合并：
    ```bash
    python3 .gemini/skills/long-audio-to-obsidian/scripts/doc_merger.py merge_plan.json
    ```
    *(注意：请根据实际安装位置调整脚本路径)*

3.  检查脚本输出，确认生成成功。
4.  删除临时文件 `merge_plan.json`。

### 4. 优化命名与生成索引 (Rename & Index)

脚本生成的只是标准文件名的中间产物。为了方便 Obsidian 使用，你需要进行最后一步的人工智能优化：

1.  **确定项目标题**：根据原始目录名或核心文件名，提取一个清晰的项目标题（例如 `2024-01-01 会议转写 - 项目 A`）。
2.  **重命名文件**：使用 `run_shell_command` 的 `mv` 命令，将 `obsidian_archive` 中的标准文件重命名为带前缀的格式。
    -   `1-原始录音汇总.md` -> `{标题} 1 原始录音汇总.md`
    -   `2-最终输出脚本汇总.md` -> `{标题} 2 最终输出脚本汇总.md`
    -   ...以此类推。
3.  **生成索引页**：
    -   创建一个名为 `{标题}.md` 的新文件。
    -   内容应包含指向上述所有文件的 Obsidian WikiLinks (`[[文件名]]`)。
    -   如果有关联的外部产品文档（未合并进来的），也可以在此处添加链接。

**索引页内容示例**：
```markdown
相关文档:

[[2024-01-01 会议转写 - 项目 A 1 原始录音汇总]]

[[2024-01-01 会议转写 - 项目 A 2 最终输出脚本汇总]]

...
```

## 归档标准 (Archiving Standards)

请按照以下四个维度组织输出文件（对应 JSON 中的 4 个 task）：

1.  **原始录音汇总**：包含所有原始录音文本。
2.  **最终输出脚本汇总**：包含所有经过校对、合并后的分段文本。**顺序至关重要**。
3.  **整理要求与日志汇总**：
    -   工作日志 (`0-工作日志.md`)
    -   校对术语表 (`3-校对和术语表.md`)
    -   分段主题 (`4-分段主题.md`)
    -   所有背景要求文件 (`2-要求和信息/*`)
4.  **知识整理汇总**：
    -   包含所有衍生生成的知识文件（如 `问题和回答-xxx.md`）。

## 注意事项

-   **路径处理**：JSON 中的 `path` 推荐使用绝对路径，或者相对于执行 `doc_merger.py` 时的相对路径。
-   **容错**：如果某个预期的目录不存在（例如没有“知识整理”文件），则不要在 JSON 中包含对应的 task，或者创建一个空的 task。
-   **排序**：脚本不会自动排序。**必须**由 Agent 在生成 JSON 时完成所有文件的逻辑排序。