mcpField
A
asciinema-converter

asciinema-converter

github.com/terrylica开发2126 次安装1 天前更新
代码仓库

关于 asciinema-converter

asciinema-converter 是面向 Claude Code 用户的 Skill，可将 asciinema .cast 终端录制转换为便于搜索的纯文本，并支持单文件与批量处理。它会清除终端控制码和 JSON 结构，便于使用 Read 和 Grep 分析录制内容。

主要功能

  1. 01转换 .cast 为 .txt
  2. 02批量转换目录中的录制
  3. 03移除 ANSI 控制码与 JSON 结构
  4. 04可选添加时间戳索引
  5. 05检查 asciinema 版本与输入文件

适用场景

  1. 01为 Claude Code 的 Read 和 Grep 准备录制内容
  2. 02批量整理终端会话录制
  3. 03从含 ANSI 控制码的输出中提取文本

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/terrylica/cc-skills --skill asciinema-converter

安装后在 Claude Code 中输入/asciinema-converter确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
anti-patterns.md
batch-processing.md
batch-workflow.md
evolution-log.md
integration-guide.md
post-change-checklist.md
task-templates.md
workflow-phases.md
tests/
converter-integration.bats
converter.test.ts
tests/fixtures/
simple.cast
with spaces.cast

详细介绍

asciinema-converter

将 asciinema .cast 录制文件转换为干净的 .txt 文件，以供 Claude Code 分析。通过剥离 ANSI 代码和 JSON 结构，实现 950:1 的压缩率（3.8GB -> 4MB）。

平台：macOS、Linux（需要 asciinema CLI v2.4+）

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

何时使用此技能

在以下情况使用此技能：

  • 将 .cast 录制文件转换为可搜索的 .txt 格式
  • 为 Claude Code Read/Grep 工具准备录制文件
  • 批量转换多个录制文件
  • 减少会话归档的存储空间
  • 从使用 ANSI 编码的终端输出中提取干净文本

为什么要转换？

格式大小（22 小时会话）与 Claude Code 兼容可搜索
.cast3.8GB否（NDJSON + ANSI）可通过 jq 搜索
.txt~4MB是（干净文本）Grep/Read

主要优势：Claude Code 的 Read 和 Grep 工具可以直接处理 .txt 输出。

要求

组件必需安装方式备注
asciinema是brew install asciinemaconvert 命令需要 v2.4+

工作流概览

重要提示：所有阶段均为必需。不要跳过任何阶段。每个决策点都必须使用 AskUserQuestion。

单文件模式（阶段 0-6）
阶段目的关键操作
0预检验证 asciinema CLI v2.4+
1文件发现与选择AskUserQuestion：选择要转换的文件
2输出选项AskUserQuestion：选择转换选项
3输出位置AskUserQuestion：选择保存位置
4执行转换asciinema convert -f txt
5时间戳索引可选的 [HH:MM:SS] 索引
6后续步骤AskUserQuestion：接下来要做什么

完整实现细节：工作流阶段

批量模式（阶段 7-10）

通过 --batch 标志启用。转换目录中的所有 .cast 文件，并整理输出。

阶段目的关键操作
7选择源目录AskUserQuestion（如果指定了 --source，则跳过）
8整理输出AskUserQuestion（如果指定了 --output-dir，则跳过）
9执行批量转换转换所有文件并报告进度
10批量转换后的下一步AskUserQuestion：接下来要做什么

完整实现细节：批量工作流

iTerm2 文件名格式

iTerm2 自动记录的文件遵循以下格式：

{creationTimeString}.{profileName}.{termid}.{iterm2.pid}.{autoLogId}.cast

示例：20260118_232025.Claude Code.w0t1p1.70C05103-2F29-4B42-8067-BE475DB6126A.68721.4013739999.cast

组成部分描述示例
creationTimeStringYYYYMMDD_HHMMSS20260118_232025
profileNameiTerm2 配置文件名称（可能包含点号）Claude Code
termid窗口/标签页/面板标识符w0t1p1
iterm2.pidiTerm2 进程 UUID70C05103-2F29-4B42-8067-BE475DB6126A
autoLogId会话自动记录标识符68721.4013739999

CLI 快速参考

# Basic conversion
asciinema convert -f txt recording.cast recording.txt

# Check asciinema version
asciinema --version

# Verify convert command exists
asciinema convert --help

参考文档

内部参考
外部参考

故障排除

问题原因解决方案
找不到 convert 命令asciinema 版本过旧升级：brew upgrade asciinema（需要 v2.4+）
未安装 asciinema缺少 CLIbrew install asciinema
输出文件为空.cast 输入已损坏验证 .cast 文件是否具有有效的 NDJSON 结构
转换失败cast 格式无效使用 jq 检查标头行是否为有效 JSON
找不到 numfmtmacOS 缺少 coreutils使用原始字节数，或运行 brew install coreutils
stat 语法错误Linux 与 macOS 的差异脚本可处理两者；检查 stat 版本
批处理跳过所有文件所有 .txt 文件均已存在使用 --skip-existing=false 重新转换
输出时权限被拒绝目录不可写检查输出目录权限

执行后反思

此技能完成后，结束前请检查：

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

只有在问题真实且可复现时才更新，不要基于猜测进行修改。

评论

支持 Markdown