拆解AntiVibe的4个Shell脚本：多语言代码结构解析与阶段检测的实现原理-平芜编程栈

【免费下载链接】antivibe

Learn what AI writes, not just accept it. A Claude Code skill that turns AI-generated code into educational deep dives.

项目地址：https://gitcode.com/gh_mirrors/an/antivibe

AntiVibe 是一个面向 Claude Code 的"反 vibe coding"学习框架，能把 AI 生成的代码变成教学式的深度解析文档。它的核心能力由scripts/目录下的 4 个 Shell 脚本驱动：代码结构解析、阶段检测、学习资源匹配和Markdown 输出生成。本文将逐个拆解这 4 个脚本的实现原理，带你看懂它如何支持 TypeScript、Python、Go、Rust、Java 等多语言分析，以及"阶段检测"到底是怎么找到 AI 刚写的代码的。

一、AntiVibe 是什么？解决什么问题？

⚡痛点：AI 写代码，开发者直接复制粘贴，谁也没有真正学到东西。
🛡️解法：AntiVibe 在任务完成后，自动把"AI 写了什么"转化为一篇讲清楚What（做什么）、Why（为什么这样写）、When（何时用）、Alternatives（还有哪些替代方案）的学习指南。

安装只需两步：

# 克隆仓库 git clone https://gitcode.com/gh_mirrors/an/antivibe # 安装为全局 Claude Code 技能 cp -r antivibe ~/.claude/skills/antivibe

技能入口定义在 SKILL.md 中，通过/antivibe、"deep dive"、"learn from this code"等短语触发；自动触发配置则在 hooks/hooks.json 里完成。

二、4 个 Shell 脚本总览

所有脚本都位于 scripts/ 目录，各司其职：

脚本	职责	一句话原理
capture-phase.sh	阶段检测	用文件修改时间找出"最近一小时内"AI 改动的代码
analyze-code.sh	多语言结构解析	按扩展名分流 +`grep`正则提取函数/类/接口
find-resources.sh	学习资源匹配	`case`模式匹配，把概念词映射到精选资源
generate-deep-dive.sh	输出生成	用 heredoc 拼接模板，产出结构化 Markdown

这四个脚本本身是"辅助工具"（SKILL.md 明确说 AI 也可以不依赖它们直接分析代码），但它们的实现思路非常值得学习。下面逐一拆解。

三、capture-phase.sh：阶段检测的实现原理 🕐

"阶段检测"要回答的问题是：这一轮任务里，AI 到底新写了哪些文件？答案藏在 scripts/capture-phase.sh 的三行核心逻辑里。

1. 给阶段打时间戳

脚本接收一个可选的阶段名参数（默认manual），并用date生成精确到秒的时间戳：

PHASE_NAME="${1:-manual}" TIMESTAMP=$(date +%Y-%m-%d-%H%M%S)

${1:-manual}是 Shell 的"默认值展开"语法——第一个参数为空时自动回退为manual，这让脚本既支持./capture-phase.sh auth-system也支持直接./capture-phase.sh。

2. 按"修改时间"圈定改动范围

这是阶段检测最关键的一步（scripts/capture-phase.sh#L14）：

find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) -mmin -60 | head -50

拆开看有 4 个技巧：

多扩展名过滤：$ ... $ -o把 6 种语言的源文件"或"起来，避免把 README、配置文件混进来；
-mmin -60：只保留最近 60 分钟内修改过的文件——AI 刚刚写完的代码必然满足这个条件，这就是"阶段边界"的朴素但有效的定义；
2>/dev/null：静默权限错误，保证在受限目录里也能跑通；
head -50：截断输出，防止一次改动太多文件时输出爆炸。

3. 输出机器可读的标记

echo "---PHASE_CAPTURED---" echo "phase=$PHASE_NAME" echo "timestamp=$TIMESTAMP"

---PHASE_CAPTURED---是一个哨兵标记（sentinel），上游程序可以靠它判断捕获成功，并解析出阶段名和时间戳。这种"人类可读日志 + 机器可解析标记"混排的输出方式，是脚本间协作的常见模式。

四、analyze-code.sh：多语言代码结构解析 🔍

scripts/analyze-code.sh 要解决的是：拿到一个源码文件，如何快速提炼出它的骨架（函数、类、导入、导出）？

1. 参数校验：先防守，再执行

脚本开头就做了两层防御（scripts/analyze-code.sh#L7-L15）：没传参数就打印用法并exit 1；文件不存在就报错退出。这是 Shell 脚本的"fail fast"好习惯——尽早失败，避免后面跑出一堆空结果。

2. 用 Bash 字符串扩展取扩展名

EXTENSION="${FILE_PATH##*.}"

${var##*.}是贪婪去掉最短前缀的字符串扩展：从最后一个.开始截断，app/auth.service.ts得到ts。一行就替代了 Python 里os.path.splitext的工作。

3. case 分流：按语言选择"解析策略"

核心是一个case "$EXTENSION"分支（scripts/analyze-code.sh#L29-L87），每种语言用不同的grep -E正则提取结构：

语言	提取目标	正则思路
TS/JS	函数、类、接口、导入、导出	`^(export )?(function\\|const\\|class\\|interface\\|type)`
Python	类、函数、导入	`^class`、`^def`、`^import \\| ^from`
Go	函数、结构体、接口	`^func`、`^type .* struct`
Rust	函数、结构体、特质	`^fn`、`^struct`、`^trait`
Java	公共类/接口/枚举、方法	`^public (class\\|interface\\|enum)`
其他	兜底：输出前 30 行	`head -30`做"概览"

三个细节值得注意：

锚定行首^：只匹配顶层定义，class出现在注释或缩进里的代码不会被误抓，相当于一种"零依赖的语法概览"；
head -20截断：每个结构类别最多输出 20 条，保证输出对 LLM 上下文友好；
*)兜底分支：未知语言不报错，而是head -30打印文件头部，让调用方（AI）自己读——优雅降级而非崩溃。

💡 这个设计的本质：不追求 100% 精确的 AST 解析，而是用"便宜且够准"的正则给 AI 提供文件骨架地图，真正的理解交给大模型。

五、find-resources.sh：概念到资源的模式匹配 📚

学习指南的价值很大程度取决于资源质量。scripts/find-resources.sh 的做法是离线资源库 +case模式匹配，而不是每次联网搜索。

用法：

./find-resources.sh 'react hooks' react

实现是一个长case语句（scripts/find-resources.sh#L20-L92），按通配关键词分流：

匹配模式	命中场景	输出资源
`"react"\\|"hooks"\\|"useState"`	React 相关概念	React 官方文档、Hooks API
`"typescript"\\|"generics"`	TS 类型/泛型	TS 官方文档、Playground
`"database"\\|*"postgres"`	数据库概念	PostgreSQL/MySQL 文档、SQLBolt
`"auth"\\|"jwt"\\|*"oauth"`	认证相关	OWASP、JWT 详解、Auth0 文档
`"design pattern"\\|"factory"`	设计模式	Refactoring Guru 等
`*)`	其他概念	给出通用搜索建议

这种"预置高质量链接库"的策略呼应了项目的第一原则——Curated resources: Quality links, not random Google results。注释里也诚实地留了扩展点（scripts/find-resources.sh#L18）：生产环境可以接网页搜索或本地数据库。

六、generate-deep-dive.sh：模板化生成学习文档 📝

scripts/generate-deep-dive.sh 负责把前面的分析结果落盘成一篇结构完整的 Markdown。

1. 文件命名与输出目录

TIMESTAMP=$(date +%Y-%m-%d-%H%M%S) OUTPUT_DIR="deep-dive" OUTPUT_FILE="$OUTPUT_DIR/${PHASE_NAME}-${TIMESTAMP}.md" mkdir -p "$OUTPUT_DIR"

[阶段名]-[时间戳].md的命名方式保证多次生成互不覆盖；mkdir -p幂等地创建目录，想改输出位置只需改OUTPUT_DIR一行（见 docs/setup.md#L95-L100）。

2. heredoc：把模板"嵌"进脚本

脚本大量使用cat >> file << 'EOF' ... EOF语法（heredoc），把 Overview、Code Walkthrough、Concepts Explained、Learning Resources、Next Steps 五大板块直接内嵌在脚本里。单引号包裹的<< 'EOF'会禁止变量展开——这正是想要的效果：模板里的_Placeholder_原样保留，等 AI 后续填充。

3. 循环写入每个文件

for FILE in "${FILES[@]}"; do if [ -f "$FILE" ]; then echo "### $(basename "$FILE")" >> "$OUTPUT_FILE" ... fi done

对传入的每个文件做存在性检查，只写入真实存在的文件，并自动取basename作为小标题。生成的骨架与 templates/deep-dive.md 的正式模板结构一致，最后打印一句提示："Edit this file to add your specific analysis!"——再次体现"脚本出骨架，AI 填灵魂"的分工哲学。

七、四个脚本如何协同工作？🔗

把 4 个脚本串起来，就是 AntiVibe 的完整数据流：

步骤	脚本	输入 → 输出
① 圈定范围	capture-phase.sh	阶段名 → 最近 1 小时改动的文件清单
② 提炼骨架	analyze-code.sh	单个源文件 → 函数/类/导入的结构摘要
③ 匹配资源	find-resources.sh	概念关键词 → 精选学习资源
④ 落盘文档	generate-deep-dive.sh	阶段名 + 文件列表 →`deep-dive/*.md`

capture-phase.sh ──> 文件清单 ──> analyze-code.sh（逐文件）──┐ ├──> generate-deep-dive.sh ──> deep-dive/xxx.md 概念关键词 ──────────> find-resources.sh ────────────┘

需要强调的是：这套流水线是可选的辅助路径。如 SKILL.md#L102-L110 所述，Claude 完全可以直接读代码完成分析；脚本更像是把"最机械的三步"从 token 消耗中剥离出来，让大模型专注于它最擅长的部分——解释Why。