asciinema-analyzer

asciinema-analyzer

对转换后的 .txt 录制内容进行语义分析，以供 Claude Code 使用。采用分层分析：ripgrep（主要，50-200ms）-> YAKE（次要，1-5s）-> TF-IDF（可选）。

平台：macOS、Linux（需要 ripgrep，可选安装 YAKE）

自我迭代技能：此技能会随着使用不断改进。如果说明有误、参数发生偏差，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实、可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 在转换后的录制内容中搜索关键词或模式
• 从会话转录中提取主题或话题
• 在会话历史记录中查找特定命令或错误
• 自动发现录制内容中未预料到的术语
• 分析会话内容，用于文档编写或审查

---

分析层级

层级	工具	速度（4MB）	使用时机
1	ripgrep	50-200ms	始终从此处开始（精选关键词）
2	YAKE	1-5s	自动发现未预料到的术语
3	TF-IDF	5-30s	主题建模（可选）

决策：从第 1 层（ripgrep + 精选关键词）开始。只有在明确要求自动发现时，才使用第 2 层（YAKE）。

---

要求

组件	必需	安装方式	说明
ripgrep	是	brew install ripgrep	主要搜索工具
YAKE	可选	uv run --with yake	用于自动发现层

---

工作流阶段（全部必需）

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

阶段 0：预检

目的：确认输入文件存在，并检查是否为 .txt（已转换）格式。

/usr/bin/env bash << 'PREFLIGHT_EOF'
INPUT_FILE="${1:-}"

if [[ -z "$INPUT_FILE" ]]; then
  echo "NO_FILE_PROVIDED"
elif [[ ! -f "$INPUT_FILE" ]]; then
  echo "FILE_NOT_FOUND: $INPUT_FILE"
elif [[ "$INPUT_FILE" == *.cast ]]; then
  echo "WRONG_FORMAT: Convert to .txt first with /asciinema-tools:convert"
elif [[ "$INPUT_FILE" == *.txt ]]; then
  SIZE=$(ls -lh "$INPUT_FILE" | awk '{print $5}')
  LINES=$(wc -l < "$INPUT_FILE" | tr -d ' ')
  echo "READY: $INPUT_FILE ($SIZE, $LINES lines)"
else
  echo "UNKNOWN_FORMAT: Expected .txt file"
fi
PREFLIGHT_EOF

如果未找到 .txt 文件，请建议先运行 /asciinema-tools:convert。

---

阶段 1：文件选择（必需）

目的：发现 .txt 文件，并让用户选择要分析的文件。

步骤 1.1：发现 .txt 文件

/usr/bin/env bash << 'DISCOVER_TXT_EOF'
# Find .txt files that look like converted recordings
for file in $(fd -e txt . --max-depth 3 2>/dev/null | head -10); do
  SIZE=$(ls -lh "$file" 2>/dev/null | awk '{print $5}')
  LINES=$(wc -l < "$file" 2>/dev/null | tr -d ' ')
  BASENAME=$(basename "$file")
  echo "FILE:$file|SIZE:$SIZE|LINES:$LINES|NAME:$BASENAME"
done
DISCOVER_TXT_EOF

步骤 1.2：展示文件选择项（必须使用 AskUserQuestion）

Question: "Which file would you like to analyze?"
Header: "File"
Options:
  - Label: "{filename}.txt ({size})"
    Description: "{line_count} lines"
  - Label: "{filename2}.txt ({size2})"
    Description: "{line_count2} lines"
  - Label: "Enter path"
    Description: "Provide a custom path to a .txt file"
  - Label: "Convert first"
    Description: "Run /asciinema-tools:convert before analysis"

---

阶段 2：分析类型（必需）

目的：让用户选择分析深度。

Question: "What type of analysis do you need?"
Header: "Type"
Options:
  - Label: "Curated keywords (Recommended)"
    Description: "Fast search (50-200ms) with domain-specific keyword sets"
  - Label: "Auto-discover keywords"
    Description: "YAKE unsupervised extraction (1-5s) - finds unexpected patterns"
  - Label: "Full analysis"
    Description: "Both curated + auto-discovery for comprehensive results"
  - Label: "Density analysis"
    Description: "Find high-concentration sections (peak activity windows)"

---

阶段 3：领域选择（必需）

目的：让用户选择要搜索的关键词领域。

Question: "Which domain keywords to search?"
Header: "Domain"
multiSelect: true
Options:
  - Label: "Trading/Quantitative"
    Description: "sharpe, sortino, calmar, backtest, drawdown, pnl, cagr, alpha, beta"
  - Label: "ML/AI"
    Description: "epoch, loss, accuracy, sota, training, model, validation, inference"
  - Label: "Development"
    Description: "iteration, refactor, fix, test, deploy, build, commit, merge"
  - Label: "Claude Code"
    Description: "Skill, TodoWrite, Read, Edit, Bash, Grep, iteration complete"

完整的关键词列表请参见领域关键词参考。

---

阶段 4：执行精选分析

目的：针对所选领域的关键词运行 Grep 搜索。

步骤 4.1：交易领域

/usr/bin/env bash << 'TRADING_EOF'
INPUT_FILE="${1:?}"
echo "=== Trading/Quantitative Keywords ==="

KEYWORDS="sharpe sortino calmar backtest drawdown pnl cagr alpha beta roi volatility"
for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done
TRADING_EOF

步骤 4.2：ML/AI 领域

/usr/bin/env bash << 'ML_EOF'
INPUT_FILE="${1:?}"
echo "=== ML/AI Keywords ==="

KEYWORDS="epoch loss accuracy sota training model validation inference tensor gradient"
for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done
ML_EOF

步骤 4.3：开发领域

/usr/bin/env bash << 'DEV_EOF'
INPUT_FILE="${1:?}"
echo "=== Development Keywords ==="

KEYWORDS="iteration refactor fix test deploy build commit merge debug error"
for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done
DEV_EOF

步骤 4.4：Claude Code 领域

/usr/bin/env bash << 'CLAUDE_EOF'
INPUT_FILE="${1:?}"
echo "=== Claude Code Keywords ==="

KEYWORDS="Skill TodoWrite Read Edit Bash Grep Write"
for kw in $KEYWORDS; do
  COUNT=$(rg -c "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done

# Special patterns
ITERATION=$(rg -c "iteration complete" "$INPUT_FILE" 2>/dev/null || echo "0")
echo "  'iteration complete': $ITERATION"
CLAUDE_EOF

---

阶段 5：YAKE 自动发现（如已选择）

目的：运行无监督关键词提取。

/usr/bin/env bash << 'YAKE_EOF'
INPUT_FILE="${1:?}"
echo "=== Auto-discovered Keywords (YAKE) ==="

uv run --with yake python3 -c "
import yake

kw = yake.KeywordExtractor(
    lan='en',
    n=2,           # bi-grams
    dedupLim=0.9,  # dedup threshold
    top=20         # top keywords
)

with open('$INPUT_FILE') as f:
    text = f.read()

keywords = kw.extract_keywords(text)
for score, keyword in keywords:
    print(f'{score:.4f}  {keyword}')
"
YAKE_EOF

---

阶段 6：密度分析（如已选择）

目的：查找关键词最集中的部分。

/usr/bin/env bash << 'DENSITY_EOF'
INPUT_FILE="${1:?}"
KEYWORD="${2:-sharpe}"
WINDOW_SIZE=100  # lines

echo "=== Density Analysis: '$KEYWORD' ==="
echo "Window size: $WINDOW_SIZE lines"
echo ""

TOTAL_LINES=$(wc -l < "$INPUT_FILE" | tr -d ' ')
TOTAL_MATCHES=$(rg -c -i "$KEYWORD" "$INPUT_FILE" 2>/dev/null || echo "0")

echo "Total matches: $TOTAL_MATCHES in $TOTAL_LINES lines"
echo "Overall density: $(echo "scale=4; $TOTAL_MATCHES / $TOTAL_LINES * 1000" | bc) per 1000 lines"
echo ""

# Find peak windows
echo "Top 5 densest windows:"
awk -v ws="$WINDOW_SIZE" -v kw="$KEYWORD" '
BEGIN { IGNORECASE=1 }
{
  lines[NR] = $0
  if (tolower($0) ~ tolower(kw)) matches[NR] = 1
}
END {
  for (start = 1; start <= NR - ws; start += ws/2) {
    count = 0
    for (i = start; i < start + ws && i <= NR; i++) {
      if (matches[i]) count++
    }
    if (count > 0) {
      printf "Lines %d-%d: %d matches (%.1f per 100)\n", start, start+ws-1, count, count*100/ws
    }
  }
}
' "$INPUT_FILE" | sort -t: -k2 -rn | head -5
DENSITY_EOF

---

阶段 7：报告格式（必需）

目的：让用户选择输出格式。

Question: "How should results be presented?"
Header: "Output"
Options:
  - Label: "Summary table (Recommended)"
    Description: "Keyword counts + top 5 peak sections"
  - Label: "Detailed report"
    Description: "Full analysis with timestamps and surrounding context"
  - Label: "JSON export"
    Description: "Machine-readable output for further processing"
  - Label: "Markdown report"
    Description: "Save formatted report to file"

---

阶段 8：后续操作（必需）

目的：引导用户执行下一步操作。

Question: "Analysis complete. What's next?"
Header: "Next"
Options:
  - Label: "Jump to peak section"
    Description: "Read the highest-density section in the file"
  - Label: "Search for specific keyword"
    Description: "Grep for a custom term with context"
  - Label: "Cross-reference with .cast"
    Description: "Map findings back to original timestamps"
  - Label: "Done"
    Description: "Exit - no further action needed"

---

TodoWrite 任务模板

1. [Preflight] Check input file exists and is .txt format
2. [Preflight] Suggest /convert if .cast file provided
3. [Discovery] Find .txt files with line counts
4. [Selection] AskUserQuestion: file to analyze
5. [Type] AskUserQuestion: analysis type (curated/auto/full/density)
6. [Domain] AskUserQuestion: keyword domains (multi-select)
7. [Curated] Run Grep searches for selected domains
8. [Auto] Run YAKE if auto-discovery selected
9. [Density] Calculate density windows if requested
10. [Format] AskUserQuestion: report format
11. [Next] AskUserQuestion: follow-up actions

---

修改后检查清单

修改此技能后：

1. 所有 bash 代码块都使用 heredoc 包装器
2. 精选关键词与 references/domain-keywords.md 一致
3. 分析层级与 references/analysis-tiers.md 一致
4. YAKE 调用使用 uv run --with yake
5. 包含所有 AskUserQuestion 阶段
6. TodoWrite 模板与实际工作流一致

---

参考文档

• 领域关键词参考
• 分析层级参考
• ripgrep 手册
• YAKE 文档

---

故障排查

问题	原因	解决方案
出现 "WRONG_FORMAT" 错误	提供了 .cast 文件	先运行 /asciinema-tools:convert，创建 .txt 文件
找不到 ripgrep	尚未安装	brew install ripgrep
YAKE 导入错误	未安装软件包	uv run --with yake 会自动处理
未找到关键词	选择了错误的领域	尝试其他领域或自动发现模式
密度分析结果为空	文件中没有该关键词	先使用精选搜索查找有效关键词
文件对 YAKE 来说过大	内存限制	对大文件仅使用第 1 层（ripgrep）
所有领域均无匹配项	文件是二进制文件或已损坏	使用 file 命令确认文件是纯文本
找不到 fd 命令	尚未安装	brew install fd，或使用 find 替代

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。 — 在编辑前找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修复导致问题的指令。
2. 哪些做法比预期更有效？ — 将其提升为推荐实践。
3. 哪些内容已偏离实际情况？ — 修复不再符合实际情况的脚本、参考资料或依赖项。
4. 记录下来。 — 添加一条演进日志，记录触发原因、修复内容和证据。

不要推迟。下次调用会继承你留下的一切。