后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载explainshell 是一款将 manpage 解析、选项提取与命令行参数匹配串联成一条自动化管线的开源工具带 Web 界面它读取 gzip 压缩的 man 手册页提取其中的命令选项与帮助文本再把用户输入的任意命令行逐 token 匹配到对应的帮助文本上。本文以仓库 README.md 为主线结合 matcher.py、store.py、manager.py 等源码与测试完整讲解其架构组成、本地运行方式、SQLite 存储模型、LLM 提取管线、数据库查询命令与评测体系读完后你可以独立部署一个能解释tar -xzf、git commit这类命令的本地服务并了解如何用 LLM 批量生成高质量的 manpage 解析数据。项目概览与核心定位explainshell 的核心能力可以概括为一句话match command-line arguments to their help text把命令行参数匹配到它们的帮助文本。它不是一个通用的 shell 语法高亮器而是一个面向 man 手册的参数翻译器针对一个具体程序如tar、grep、git把用户输入的命令行逐段拆分将每个选项、位置参数、管道符号甚至重定向符与对应 manpage 中提取出的帮助文本一一对应起来。从架构上看explainshell 由四个相对独立的组件构成见 README.md 的 How 一节manpage readermanpage 读取器从给定的 manpage 中提取元数据名称 name、简介 synopsis、别名 aliases实现位于 explainshell/manpage.py。options extractor选项提取器解析 roff 宏或使用 LLM 从 manpage 中提取选项实现位于 explainshell/extraction/。storage backend存储后端把处理后的 manpage 保存进 SQLite 数据库实现位于 explainshell/store.py。matcher匹配器基于 bashlex 解析命令行为 AST并将每个节点上下文相关地匹配到对应帮助文本实现位于 explainshell/matcher.py。这四者构成了一条manpage 入库 → 查询解释的完整流水线查询时 explainshell 先将用户输入解析成 AST然后遍历其中值得关注的节点——command 节点表示一条简单命令和 shell 相关节点表示|、这类 shell 语义——对每个 command 节点判断是否知道该程序的解释方式再遍历剩余 token 尝试匹配到已知选项列表最终返回一组匹配结果由 Flask 渲染成页面。本地运行 explainshell环境准备与依赖安装README 给出了完整的本地启动流程。首先克隆仓库并创建 Python 虚拟环境# Clone repository $ git clone https://github.com/idank/explainshell.git $ cd explainshell # Set up Python virtualenv $ python3 -m venv .venv $ source .venv/bin/activate $ pip install -r requirements-dev.txt依赖文件分为三类requirements.txt核心运行依赖、requirements-dev.txt开发与测试依赖其中应包含 requirements.txt 的内容并追加 pytest、playwright 等、requirements-extraction.txtLLM 提取路径的额外依赖如 OpenAI/Gemini SDK。按 README 的指示安装 requirements-dev.txt 即可覆盖本地开发与 Web 服务运行。获取数据下载线上数据库或解析 manpageexplainshell 本地运行有两种数据来源。最省事的方式是下载线上服务正在使用的数据库# Download the live db $ make download-latest-db该命令调用 tools/download-latest-db.sh 从 GitHub Release 中拉取线上数据库快照产出默认的explainshell.db线上服务的数据库保存在 GitHub Release 中。第二种方式是自己解析 manpage。仓库在 manpages/ 下存放了按distro/release/section/组织的 gzip 手册页例如manpages/ubuntu/26.04/1/tar.1.gz你可以对单个文件执行 LLM 提取# Or parse a manpage $ python -m explainshell.manager extract --mode llm:codex/gpt-5.6-sol/medium manpages/ubuntu/26.04/1/tar.1.gz关于--mode的详细语义llm:provider/model语法、codex/model/effort中的 reasoning effort 后缀等见下文LLM 提取管线一节。启动 Web 服务数据就绪后一行命令即可启动 Web 服务器# Run the web server $ make serve # open http://localhost:5000make serve实际执行的是DB_PATH$(or $(DB_PATH),explainshell.db) python runserver.py见 Makefile 的 serve 目标即优先读取DB_PATH环境变量缺省时使用explainshell.db。启动后浏览器访问 http://localhost:5000 即可输入命令获取解释。Web 层由 Flask 实现视图函数位于 explainshell/web/views.py页面模板位于 explainshell/web/templates/。查询流程bashlex AST 与逐节点匹配README 描述了查询时的处理步骤解析 AST → 访问 command/shell 节点 → 逐命令匹配选项 → 返回结果并渲染。这一流程在 explainshell/matcher.py 中有完整的源码级实现。AST 解析与节点访问Matcher类继承自bashlex.ast.nodevisitor其match()方法matcher.py首先用 bashlex 将输入解析为 ASTself.ast bashlex.parser.parsesingle( self.s, expansionlimit1, strictmodeFalse )expansionlimit1限制递归展开深度为 1防止命令替换等结构无限展开。解析成功后visit()会遍历整个 AST 树针对不同节点类型执行不同的匹配策略。命令节点的处理与 manpage 查找对每个command节点matcher 会先找出第一个 WordNode命令名再调用find_man_pages()到 store 中查找对应的 manpagematcher.py。查找逻辑支持两种模式严格模式当查询已锚定到某个发行版distro/release或没有偏好列表可回退时直接按distro/release过滤查找偏好回退模式按_distro_preference列表依次尝试各发行版第一个命中即锚定后续所有查询都固定在该发行版上。如果命令名是仓库中已定义的 shell 函数visitfunction会把函数名记录进self.functionsmatcher 会把它当作函数调用而非 manpage 查找并为其参数附加_functionarg帮助文本避免把函数参数误判为未知程序。子命令的前瞻匹配对于git commit、systemctl start这类父命令 子命令形式manpage 中提取出的subcommands列表起着关键作用。在 matcher.py 中如果当前 manpage 声明了子命令且下一个 token 是可匹配的词节点matcher 会尝试拼接git commit这样的复合名字再次查找 manpagestore 中mappings表的src列就保存着git commit这样的键指向git-commit手册页。命中后父命令与子命令会合并为一个 MatchGroup其帮助文本使用子命令 manpage 的 synopsis。选项、位置参数与 shell 结构的匹配visitword()matcher.py是匹配的核心按优先级依次处理长选项--longvalue形式会先按拆分只匹配选项名部分短选项簇-abc这类会被attemptfuzzy()逐字符拆分尝试匹配若某选项声明has_argument剩余字符会被整体当作其参数覆盖xargs -r0n1这种紧凑写法带引号的词如-7 days不会被当作选项簇因为 bashlex 保留的位置跨度大于词长上一条选项的参数若前一个选项声明需要参数当前词会被当作它的参数吸收支持has_argument为枚举列表时的白名单校验以及nested_cmd触发嵌套命令的场景位置参数manpage 声明positionals时按序消费positional_index游标先精确匹配关键词式位置参数如start/stop消费完所有位置参数后复用最后一个变参声明prefixed_positionals时token 必须以声明的字面前缀如、、:开头才能认领该位置参数兜底以上都失败则标记为 unknown。shell 语义同样有专门处理visitpipe为|附加管道帮助文本visitredirect处理重定向、、、heredocvisitreservedword/visitoperator处理保留字与运算符如if、并会结合compound_stack区分done在for/while中的不同含义visitassignment处理VARvalue赋值命令替换、进程替换、波浪号展开与参数展开则被记录为 expansions 而非当作参数匹配。匹配完成后_merge_adjacent()会把相邻且帮助文本相同的匹配结果合并成一段_mark_unparsed_unknown()则把解析器未覆盖的残余字符包括#注释标记为 unknown 或 comment。每个匹配结果是一个MatchResultmatcher.py包含start/end位置、帮助文本text、被匹配的原文match以及调试元数据debug_infounknown属性标识该 token 无法解释。同一条命令行的匹配结果按MatchGroup分组一个 shell 组加每命令一个组每个组的manpage字段存放对应手册页suggestions存放同名但未命中的候选手册页。存储层SQLite 三表模型README 的 Storage 一节明确了数据模型所有处理过的 manpage 存放在单个 SQLite 数据库默认explainshell.db中共三张核心表。其建表语句在 explainshell/store.py 的_CREATE_SCHEMA中manpages保存 zlib 压缩后的 manpage 源文本通常是由mandoc -T markdown生成的 markdown。主键source是distro/release/section/name.section.gz格式的路径如ubuntu/26.04/1/tar.1.gz另有generated_at、generator、generator_version、source_gz_sha256等溯源字段。parsed_manpages保存每个 manpage 提取出的name、synopsis、optionsJSON 列表、aliases[别名, 分数]对、dashless_opts是否允许不带前导-的选项、subcommands子命令名 JSON 列表如[build,run,push]、nested_cmd位置参数是否启动嵌套命令如sudo、xargs、updated是否手工编辑过、extractor与extraction_meta。外键source级联删除。mappings把命令名含别名与子命令形式映射到parsed_manpages行多对一带score权重。一条 manpage 可以有多个映射每个别名一个每个子命令形式一个如git commit→git-commit手册页。另有追加写的db_events事件日志表记录 extraction、upload 等数据库生命周期事件。source路径在manpages和parsed_manpages中都是主键同时充当命名空间查询可以按路径前缀过滤把搜索范围限定到某个 distro/release。store.py 中的validate_source_path()用正则严格校验distro/release/section/name.section.gz格式。Store类explainshell/store.py是读写入口create()打开或创建可写数据库并执行建表脚本find_man_page()store.py是查询核心——先查mappings精确命中未命中时把name.section末尾的点号后缀当作手册节section重新查找再按 score 排序、按 distro/release 过滤返回最高分手册页及 suggestions 列表。子命令映射的自动对账由update_subcommand_mappings()store.py完成它扫描所有声明了subcommands的父手册页在同 distro/release 下寻找git-commit这类连字符子手册页先删除全部旧的多词映射再全量重建避免历史运行留下过期映射。Manpage 归档来源与本地生成explainshell.com 的 manpage 来源于已知归档目前是 Ubuntu 归档与 manned.org所有 gzip 源文件gz 文件都提交在 explainshell-manpages本仓库的 git submodule中。README 特别说明本地运行 explainshell 并不需要克隆这个 submodule——如果你只想跑服务用下载线上数据库的方式即可。需要本地生成归档时$ git submodule update --init --recursive $ make ubuntu-archive UBUNTU_RELEASEresolute $ make arch-archive # Arch only has a latest archivemake ubuntu-archive见 Makefile 的 ubuntu-archive 目标先构建并运行manpages/ubuntu-manpages-operator下的 Go 摄取器ingest再调用 tools/postprocess_ubuntu_archive.py 做后处理make arch-archive则要求先用python tools/fetch_manned.py download --data-dir ignore/manned下载 manned.org 数据再执行fetch_manned.py extract提取。两种方式最终都在manpages/distro/release/下输出 gzip 后的 manpage。LLM 提取管线与 manager CLI提取模式的完整语法manager CLI 是提取与查询数据库的统一入口入口为 explainshell/manager.py大多数命令需要数据库路径可通过DB_PATH环境变量设置或命令行传入--db path。不需要数据库的命令如extract --dry-run、diff extractors可省略。--mode标志选择提取策略目前唯一的生产模式是llm:provider/model把 manpage 文本经mandoc -T markdown转换发送给 LLM 提取选项。模型串还可以追加推理档位后缀openai/model/effort如llm:openai/o3/mediumeffort 取值 low、medium、highazure/model/effort如llm:azure/o3/highgemini/model/budget如llm:gemini/gemini-2.5-flash/8192thinking token 预算codex/model/effort如llm:codex/o3/high。典型用法README 原样保留# Calls out to codex exec to extract the manpage and writes the result to test.db. $ python -m explainshell.manager --db test.db extract --mode llm:codex/gpt-5.6-sol/medium manpages/ubuntu/26.04/1/tar.1.gz # Or set DB_PATH: $ export DB_PATH$(pwd)/test.db # Can also use an API key (see .env.example). $ python -m explainshell.manager extract --mode llm:openai/gpt-5-mini manpages/ubuntu/26.04/1/find.1.gz $ python -m explainshell.manager extract --mode llm:openai/gpt-5-mini --batch 50 manpages/ubuntu/26.04/API key 通过.env.example中列出的环境变量配置dotenv会在启动时加载.env与.env.example见 extractor.py。反幻觉设计LLM 只返回行号区间README 强调了一个关键设计LLM 返回的是源文本中的行号区间而不是生成的描述文本因此幻觉在结构上不可能发生——实际帮助文本始终从原始 manpage 中切片得到。源码印证了这一设计explainshell/extraction/llm/extractor.py 的设计注释与finalize()实现prepare()读取 manpage、剥离 mandoc 产物、过滤低价值章节、给剩余行编号并分块LLM 对每个 chunk 返回 JSONfinalize()解析后把行号引用映射回original_lines中的原文拼装成最终帮助文本。这样既缩小了模型输出又让入库文本保持确定性。分块chunking发生在过滤后的纯文本上但行号相对原始过滤文档因此多个 chunk 的响应可以合并而无需重新编号去重是两层的先dedup_ref_options()移除 chunk 交叠产生的原始 dict 级重复再由postprocess()在已验证的Option对象上做高层清理。提取管线还内置了内容过滤黑名单_BLACKLISTED_SOURCESextractor.py用于跳过被 provider 内容过滤器误判的少数 manpage。extract 的其余标志README 列出了extract的全部可选标志及其语义--overwrite重新处理库中已存在的条目--filter-db spec与--overwrite配合只重新提取库中extractor与spec匹配的行语法与--mode相同可重复传多次以匹配多个提取器/模型--dry-run只打印每个文件的预过滤决策不提取、不写库-j N并行 worker 数默认 1--batch N走 provider 批量 API仅gemini/、openai/、azure/模型支持批量更便宜但需要几分钟到几小时的排队延迟--small-only/--large-only按约 2 KB gz 大小把语料分成两半让便宜模型处理小页面、能力强的模型处理其余部分。README 给出的两阶段路由示例# pass 1 - cheap model on small pages $ python -m explainshell.manager extract --mode llm:codex/gpt-5.6-luna/medium --small-only manpages/... # pass 2 - capable model on the rest (already-stored small pages are skipped) $ python -m explainshell.manager extract --mode llm:codex/gpt-5.6-sol/medium --large-only manpages/...大小阈值_SIZE_FILTER_THRESHOLD 2048定义在 manager.py源自tools/experiments/eval_size_routing.py的实验该阈值以下的页面用廉价模型在约 98% 的文件上与能力模型结果一致分歧从 4-8 KB 桶开始出现。从源码看manager 还在提取前对每个输入文件做预过滤分类explainshell/extraction/prefilter.py每个文件会归入 Work、SizeSkip、AlreadyStored、FilterSkip、Symlink、ContentDup 六类之一——symlink 与内容完全相同的文件如交叉编译器变体会被去重并映射到 canonical manpage而不是重复提取。批量超过 100 个 manpage 时还要求提供--reason写入db_events供后续追溯。比较提取结果diff 子命令diff有两个子命令用于对比提取质量# Diff against the database $ python -m explainshell.manager diff db --mode llm:openai/gpt-5-mini manpages/ubuntu/26.04/1/tar.1.gz # Compare two extractors head-to-head $ python -m explainshell.manager diff extractors llm:openai/gpt-5-mini..llm:openai/gpt-5 manpages/ubuntu/26.04/1/tar.1.gzdiff db把一次全新提取与数据库中已存的结果做 diffdiff extractors用A..B语法对两个提取器做头对头比较输出逐选项差异与 token 消耗统计见 manager.py 的_run_diff_extractors它同时运行两个提取器并逐文件format_diff。查询数据库show 子命令# Show aggregate stats $ python -m explainshell.manager show stats # Look up a command $ python -m explainshell.manager show manpage tar # List available distros $ python -m explainshell.manager show distros # Run integrity checks $ python -m explainshell.manager db-checkshow stats展示库中parsed_manpages与mappings的行数Store.counts()show manpage tar按命令名查找并打印手册页的解析结果show distros从source路径中提取去重后的 (distro, release) 对store.pydb-check则执行完整性检查对应 explainshell/db_check.py。测试与评测体系一键运行全部测试$ make tests-all # lint unit tests e2emake tests-allMakefile依次执行ruff checkruff format --checkbiome checklint见lint目标、pytest --doctest-modules tests/ explainshell/单元测试含 doctest、cd prod/botshed go vet ./... go test ./...Go 模块测试、e2ePlaywright 端到端以及 prod-integration构建 Docker 镜像并跑集成脚本。仓库的单元测试覆盖了存储tests/test_store.py、匹配器tests/test_matcher.py、manpage 元数据tests/test_manpage.py、Web 视图tests/test_web_views.py以及 LLM 提取的各子模块tests/extraction/llm/。注意 e2e 与 prod-integration 有前置条件e2e 需要先make e2e-db用真实 LLM 生成 tests/e2e/e2e.db默认 9 个测试 manpage、-j 9并行prod-integration 需要 gh 认证解析 Release 资产。LLM 评测tests/evals/llmLLM evaltests/evals/llm/llm_eval.py在 tests/evals/llm/corpus.txt 列出的语料上运行 LLM 提取器产出summary.json及每页的工件markdown/、prompts/、responses/。每次运行自动以时间戳保存到tests/evals/llm/runs/timestamp-label/并附带 git 元数据。官方建议的用法是在修改 LLM 提取管线之前先跑一次建立 baseline修改后再跑一次对比由于 LLM 的不确定性两次运行间存在一定方差属正常现象。# Run on the default corpus, parallelizing realtime calls $ python tests/evals/llm/llm_eval.py run --label baseline --model openai/gpt-5-mini --jobs 10 # Compare two run directories (oldest first) $ python tests/evals/llm/llm_eval.py compare tests/evals/llm/runs/baseline-run tests/evals/llm/runs/current-run # List all saved runs $ python tests/evals/llm/llm_eval.py list与extract --batch同理评测也支持--batch size走批量 API——更便宜但排队延迟以分钟到小时计对默认 12 页的小语料并不划算只有大规模语料才值得。Markdown 渲染评测tests/evals/render针对mandoc -T markdown变更的评审型评测框架位于 tests/evals/render/。它用两个 mandoc 二进制渲染同一份 vendored manpage 语料对比结构指标并生成带可拖拽预期/实际滑块的截图 diff 报告。它刻意不纳入make tests-all——只有在改动 markdown 渲染路径时才手动运行用法见 tests/evals/render/README.md。数据模型与选项结构的细节从 explainshell/models.py 可以确认入库选项的完整结构。Option模型的字段包括text帮助文本、short-a形式的短选项列表、long--a形式的长选项列表、has_argument布尔或枚举参数列表表示某选项是否期待额外参数、positional是否视为位置参数、prefix位置参数必须带有的字面前缀仅当positional设置时有意义允许的字面 sigil 限于、、:定义在OPTION_PREFIX_SIGILS其依据是对语料中所有 SYNOPSIS 节的扫描如dig server、date FORMAT、X display numbers以及nested_cmd该选项的参数能否启动嵌套命令。ParsedManpage则在 manpage 层面聚合这些信息dashless_opts允许匹配不带前导-的选项subcommands非空时匹配器会前瞻解析git commit并解析到git-commit手册页nested_cmd表示该程序的位置参数可启动嵌套命令典型如sudo、xargs此时 matcher 会在位置参数处开启一个新的命令组。positionals与prefixed_positionals两个属性分别把位置参数按有无前缀组织成有序映射正是前面提到的 matcher 位置参数消费逻辑的数据来源。许可证与数据库分发须知explainshell 的代码采用 GPLv3 许可见 LICENSE。但发布的数据库是另一回事它包含从 Ubuntu 与 Arch Linux 软件包提取的数以万计的 manpage 的近乎逐字的原文每页保留各自上游许可证GPL、BSD、MIT 及其他GPLv3 并不覆盖它们项目方也无权重新授权。数据库或其衍生品若需再分发必须从各 manpage 自身许可证获得许可自行做合规审查并按各自许可证要求保留上游作者的版权声明。source列可用于追溯每页来自哪个 distro/release。实战小结一条完整的本地链路把 README 的内容串起来一套典型的本地工作流是git clone→ 创建 venv 并pip install -r requirements-dev.txt→make download-latest-db或对 manpages/ 下手册页执行python -m explainshell.manager extract --mode llm:... file→make serve→ 打开 http://localhost:5000 输入命令查看逐 token 解释。进阶用户可以进一步用--small-only/--large-only做大小路由、用--batch走批量 API 降本、用diff对比提取器、用db-check校验库完整性并用make tests-all与tests/evals/llm/评测管线改动。这套读取 manpage → 提取选项 → 入库 → AST 匹配的管线正是 explainshell 把命令行参数匹配到它们的帮助文本这一核心目标落到实处的完整答案。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐Encore CLI 命令全参考从本地开发到云端部署的完整命令行指南Encore CLI 命令全参考从本地开发到云端部署的完整命令行指南 本指南以 Encore 官方 CLI Reference https://link.gi后端开发工具云原生微服务WeasyPrint 命令行工具完全指南weasyprint 命令的 manpage、参数全解析与源码实现WeasyPrint 命令行工具完全指南weasyprint 命令的 manpage、参数全解析与源码实现 导读 weasyprint 命令是 WeasyPr文档后端btop 命令行使用手册从 manpage 到源码级的全部启动参数解析btop 命令行使用手册从 manpage 到源码级的全部启动参数解析 本篇技术指南围绕 btop 项目的官方手册 manpage.md https://liCLI指标监控运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考