用Claude五分钟造出Vidman：视频man手册的命令行工具实战

一个被忽视的痛点：视频版的man手册

资深Linux内容创作者DistroTube（DT）过去一年一直在做一个有意思的项目——视频man手册（Video Man Pages）。这类视频通常只有五到十分钟，专门讲解GNU core utils等Linux标准shell工具的常用标志、选项和典型用法，比如最近做的nl（行号编号）、yes、basename等命令。

目前他已经积累了36个视频man手册，并计划把数量推到50个，最终目标是100个。但随着视频数据库越做越大，一个新问题浮现出来：用户如何在Linux系统上快速检索和调出这些视频？手动翻YouTube播放列表显然不够高效。于是他决定做一个命令行工具——vidman，让用户在终端里直接输入vidman cat，就能看到关于cat命令的视频或配套文档。

已有的基础设施：GitLab仓库与org文档

这个工具并非凭空而起。DT早已在GitLab上维护了一个vidman仓库，仓库主页的README.org渲染出一张表格，列出所有已覆盖的命令、对应的YouTube视频链接，以及一份org格式的文档链接。

在docs目录下，每个命令都有一份独立的org文件，比如awk.org里就记录了他在awk视频中演示过的所有命令。这意味着视频和可读文档是一一对应的——你可以边看视频边对照文档里的实际命令。这套结构清晰的仓库，正是vidman工具能够快速落地的数据基础。

Org格式（.org）是Emacs生态中广泛使用的纯文本标记语言，语法上类似Markdown，但功能更丰富，原生支持大纲折叠、表格、代码块、任务管理等结构化内容。GitLab和GitHub均能将.org文件渲染为带格式的网页视图。在终端环境下，org文件本质上是纯文本，可以直接用less、cat等标准工具阅读，无需任何特殊解析器——这正是它适合作为跨环境文档格式的原因。DT选择org而非Markdown，很可能与他长期使用Emacs/Doom Emacs的习惯有关，也与GNU工具链的文化氛围相符。

不写代码，直接问Claude

这里是整段分享最具话题性的部分。DT坦言，他完全可以自己花几个小时写一个bash脚本、再配一个Makefile和Arch的PKGBUILD来完成安装。但他的选择是：直接把需求丢给Claude。

他只用一段话描述了需求，Claude随即反问了四五个关键问题，这个交互过程本身很有参考价值：

• 用什么语言？ 考虑到大多数Linux机器都自带bash，Python也是备选。DT选了bash。
• 怎么看视频？ 直接在浏览器打开链接，还是用MPV这类媒体播放器？DT的回答是——两种都提供。
• 怎么读org文档？ 在终端或TTY环境下用什么打开？答案是用标准的less命令。
• 数据/文档放在哪？ 是每次从GitLab在线拉取，还是在安装时就把org文档下载到本地？显然本地安装更合理。

大约五分钟后，Claude输出了完整的脚本、一个包含脚本的tar包，以及对每个文件的详细说明。整个过程DT几乎没有额外工作量。

Claude在这个交互中展示的「反向提问」行为，体现了大语言模型处理需求模糊性的一种典型策略：在生成代码之前，先通过少量高价值问题消除关键不确定性，而不是直接根据假设生成一个可能完全跑偏的初版。语言选择（bash vs Python）、视频播放路径（浏览器 vs MPV）、文档阅读方式（终端 vs 其他）、数据存储策略（在线拉取 vs 本地安装）这四个问题，恰好对应了工具的核心依赖项与分发逻辑——任何一个判断错误都会导致代码框架性重写，而非小修小补。这种提问策略实质上是在用最低成本完成需求的「范围锁定」。

代码可审计：LLM不等于黑箱

面对"你根本不知道Claude在干什么"的常见质疑，DT的回应很直接：他本就懂bash，完全有能力自己写，只是不想把时间花在他并不享受的脚本和编程上。更重要的是，生成的代码是完全可审计的。

他现场打开vidman脚本逐行讲解：开头是#!/usr/bin/bash的shebang，接着是set -euo pipefail做错误检查，然后是程序名变量、注释里的帮助信息。往下是几个函数——resolve_share_directory用于定位存放commands.tsv的数据目录，resolve_docs_directory用于查找各命令的org文档，逻辑都用for循环遍历候选目录，"一点都不复杂"。

一个让DT本人都感到惊喜的细节是：Claude主动加入了一个配置文件机制（.config/vidman/config，采用key=value格式），支持自定义视频播放器等选项。而这是他在提示词里完全没有要求的功能。他评价说，这正是LLM的价值所在——会想到你原本不会想到的、但确实合理的设计。数据部分则包含一个commands.tsv（制表符分隔值）文件，由仓库里的生成脚本从README.org自动提取并排序。

真实的坑：安装过程中的两个小问题

这段分享难得地保留了完整的"翻车"与排错过程，比纯粹的成功演示更有说服力。

第一个坑出现在Makefile安装时报"permission denied"。排查发现是tools目录下的gen_commands.tsv生成脚本缺少执行权限（被设成了nobody可执行）。给它加上owner执行权限后，sudo make install顺利通过——这是本地环境问题，与Claude生成的代码无关。

第二个坑与Arch的PKGBUILD有关。Claude默认假设GitLab的主分支还叫master，但GitLab早已把默认分支从master改名为main，这个历史变动连Claude也没能完全跟上，需要手动修正。此外，makepkg -si首次报"validity check"失败，原因是PKGBUILD里的SHA-256校验和未更新。DT安装了pacman-contrib包，用其中的updpkgsums命令更新校验和后，Arch包安装成功。

PKGBUILD是Arch Linux及其衍生发行版（如Manjaro、EndeavourOS）用于描述软件包构建流程的脚本文件，makepkg工具会读取它并自动完成下载源码、验证完整性、编译、打包等步骤，最终生成可由pacman管理的.pkg.tar.zst包。SHA-256校验和（checksums字段）是PKGBUILD的安全机制，用于验证下载的源文件未被篡改或损坏；每次源文件内容变动（即使只是分支名修改导致拉取的tar包不同），校验和就必须同步更新。pacman-contrib是pacman的配套工具集，其中的updpkgsums命令可以自动重新计算并写入正确的校验和，省去手动运行sha256sum再粘贴的繁琐步骤。

工具实测：watch、browser与read

安装完成后，直接运行vidman（无参数）或vidman -h会打印帮助信息，列出六个标志：-W（watch，默认用MPV播放）、-R（read，读org文档）、-B（browser，须与-W配合）、-M、-L（列出所有已覆盖命令）、-H（帮助）。

实际使用时，vidman -W ls会从网络拉取并用MPV打开ls命令的视频；加上-B则改为在浏览器中打开。而直接输入vidman cat（不带标志）会弹出交互菜单，让你选择用MPV看、用浏览器看、还是用less阅读org文档。DT现场选了阅读文档，less随即打开了与视频内容一致的cat命令说明。

Makefile和PKGBUILD两种安装方式最终都验证通过，vidman现在既是可在Arch上安装的软件包，也能通过Makefile在任意发行版上安装。想知道已经覆盖了哪些命令，一个vidman -L就能列出全部清单。

一点观察：LLM作为"工程效率杠杆"

抛开工具本身，这个案例折射出LLM在实际开发中的一种务实用法：不是替代开发者的判断，而是放大其执行效率。 DT全程清楚代码在做什么、能够逐行审计、也能定位并修复Claude遗漏的分支改名、权限、校验和等真实问题。LLM负责的是把一段清晰需求快速翻译成可运行的脚手架，并在交互中补充合理的设计建议。

对于不以编程为乐、只想"把事做成"的技术用户而言，这种"一段提示词+四个澄清问题+五分钟产出+人工审计"的协作模式，可能才是当下大模型编程最接地气的落地姿势。