convert

/asciinema-tools:convert

将 asciinema .cast 录制文件转换为整洁的 .txt 文件。支持单文件和批量目录模式。

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生变化，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

参数

单文件模式

参数	说明
file	.cast 文件的路径
-o, --output	输出路径（默认：同一目录）
--index	创建带时间戳索引的版本
--chunks	在 30 秒及以上的空闲间隔处分段
--dims	保留终端尺寸
--analyze	转换后自动运行 /analyze

批量模式

参数	说明
--batch	启用目录转换批量模式
--source	源目录（默认：~/asciinemalogs）
--output-dir	输出目录（默认：~/Downloads/cast-txt/）
--skip-existing	跳过已有 .txt 输出的文件（默认：true）

注意：--batch 和位置参数 file 不能同时使用。

执行

使用用户选择的选项调用 asciinema-converter 技能。

单文件模式跳过逻辑

• 如果提供了 file → 跳过阶段 1（文件选择）
• 如果提供了选项 → 跳过阶段 2（选项）
• 如果提供了 -o → 跳过阶段 3（输出位置）
• 如果提供了 --analyze → 跳过阶段 6 并自动运行分析

批量模式跳过逻辑

• 如果提供了 --batch → 跳过阶段 1–3，进入批量阶段（7–10）
• 如果提供了 --source → 跳过阶段 7（源目录选择）
• 如果提供了 --output-dir → 跳过阶段 8（输出组织）

单文件工作流

1. 预检查：检查 asciinema convert 命令
2. 发现：查找 .cast 文件
3. 选择：使用 AskUserQuestion 选择文件
4. 选项：使用 AskUserQuestion 选择转换选项
5. 位置：使用 AskUserQuestion 选择输出位置
6. 执行：运行 asciinema convert
7. 报告：显示压缩率
8. 后续操作：使用 AskUserQuestion 选择后续操作

批量工作流

1. 预检查：检查 asciinema convert 命令
2. 源目录：使用 AskUserQuestion 选择源目录
3. 输出目录：使用 AskUserQuestion 选择输出目录
4. 执行：批量转换并报告进度
5. 报告：显示汇总压缩统计信息
6. 后续操作：使用 AskUserQuestion 选择后续操作

示例

# Single file conversion
/asciinema-tools:convert ~/Downloads/session.cast

# Batch mode with defaults
/asciinema-tools:convert --batch

# Batch mode with custom paths
/asciinema-tools:convert --batch --source ~/Downloads --output-dir ~/cast-txt/

# Batch mode, force re-convert existing
/asciinema-tools:convert --batch --skip-existing=false

故障排除

问题	原因	解决方案
找不到 asciinema	未安装 asciinema	brew install asciinema
转换命令失败	.cast 文件已损坏	先尝试 asciinema cat file.cast
找不到 .cast 文件	目录错误	检查 --source 路径
未创建输出文件	权限被拒绝	检查输出位置的写入权限
文件过大	录制时长过长	使用 --chunks 在暂停处拆分

执行后复盘

此技能完成后，关闭前请检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要采用变通方法？ — 如果你不得不临时调整（使用不同标志、增加步骤），请更新此 SKILL.md，避免下次调用时重复采用相同的变通方法。

仅在问题真实且可复现时更新，不要基于猜测进行更新。