后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载导读explainshell 是一个 Web 工具解析 man 手册man pages通过 bashlex 分析用户输入的命令行把每个参数逐一匹配到对应的帮助文本从而解释任意 shell 命令。本文以仓库根目录的 CLAUDE.md 项目指令文档为骨架完整展开其技术栈、开发工作流、核心架构、LLM 提取评估方法与部署实践并结合 Makefile、explainshell/manager.py、explainshell/models.py、explainshell/matcher.py、explainshell/store.py 等源码给出可验证的实现细节。读完本文你将掌握 explainshell 从环境搭建、代码修改、测试分层、LLM 提取评测到生产部署的完整工程闭环。项目定位与技术栈CLAUDE.md 开篇即给出项目定义一个解析 man 手册、通过参数 → 帮助文本匹配来解释命令行参数的工具。核心链路是原始.gz手册 → 解析 → 提取选项 → 存入 SQLite → Web 端对用户输入做 AST 级匹配并渲染解释。技术栈如下原文逐项继承并补充落地文件Python 3.12 FlaskWeb 服务框架入口为 runserver.py路由实现在 explainshell/web/views.pySQLite唯一存储后端建表与读写逻辑在 explainshell/store.pybashlex命令匹配阶段对用户输入做 Bash AST 解析Matcher直接继承bashlex.ast.nodevisitor见 explainshell/matcher.pyOpenAI SDK / Google Gemini SDK / LiteLLMfallbackLLM 选项提取管线explainshell/extraction/llm/中的三类 ProviderLintingPython 用 ruffJS 用 biome测试pytest单元 doctest、JS Playwright Teste2e配置见 playwright.config.js。依赖按用途拆分三份 requirements 与一份 package.json原文要点附源码佐证依赖文件用途requirements.txtWeb 服务所需requirements-extraction.txtLLM SDK仅离线工具使用requirements-dev.txt全部依赖 测试/静态检查package.jsonPlaywright e2e 依赖环境准备与开发循环虚拟环境.venv与激活前缀仓库规定 Python 虚拟环境位于仓库内.venv且有一个容易踩坑的硬性约定CLAUDE.md 特别强调每个 Bash 工具调用都在全新 shell 中执行、默认不激活 venv因此所有 Python/pip/pytest/ruff/make 命令都必须以source .venv/bin/activate 作为前缀严禁直接裸跑python、pytest、ruff、pip或make。示例source .venv/bin/activate make tests收尾三步每项任务必做CLAUDE.md 规定任何任务结束前必须依次执行运行make format格式化代码按改动范围选择测试套件详见下文测试分层若改动涉及 CLI 命令、环境变量或用户可见功能更新 README.md若改动影响结构、约定或工作流同步更新 CLAUDE.md。测试分层如何选择测试套件这是 CLAUDE.md 的核心工作流规则选择依据是改动是否会触及 Web 服务路径make tests-quicklint 单元测试改动明确不影响 Web 服务时使用例如提取管线、CLI 工具、测试本身make tests-alllint 单元 e2e botshed 集成改动可能影响 Web 服务路径时使用包括渲染、匹配、存储、模板、静态资源、配置拿不准就运行make tests-all。从 Makefile 可看到二者的真实构成tests-all: lint tests botshed-test e2e prod-integration tests-quick: lint tests botshed-test即tests-all额外叠加了 Playwright e2e含数据库完整性构建e2e-db与生产镜像集成测试prod-integration。若 e2e 因快照差异失败需要先判断差异是否符合预期征得用户确认后才允许执行make e2e-update更新快照——这是对快照回归的保护机制。常用命令速查CLAUDE.md 完整列出以下命令此处逐条继承并补充出处与用途命令作用对应实现make tests单元测试 doctest不含 e2eMakefilepytest tests/test_matcher.py -v跑单个测试文件tests/test_matcher.pypytest tests/test_matcher.py::test_matcher::test_no_options -v跑单个测试方法同上make lintruff biome 静态检查Makefilemake formatruff format biome fixMakefilemake e2ePlaywright e2e需先npm install npx playwright install chromium且已构建tests/e2e/e2e.dbMakefilemake e2e-update更新 e2e 快照Makefilemake test-llmLLM 集成测试需在.env中配置 API keyMakefile实际执行tests/extraction/llm/test_extractor.py::test_real_llm_echo_manpagemake tests-quick/make tests-all快速 / 全量测试见上文分层make db-check数据库完整性检查默认explainshell.dbMakefile底层是python -m explainshell.manager db-checkmake serve本地启动 Web 服务器Makefile等价于DB_PATHexplainshell.db python runserver.pymake ubuntu-archive UBUNTU_RELEASEresolute生成 Ubuntu 手册归档需 GoMakefilemake arch-archive生成 Arch Linux 手册归档需 manned.org 转储Makefilepython -m explainshell.manager extract --mode llm:codex/gpt-5.6-sol/medium /path/to/manpage.1.gz将单个手册处理入库explainshell/manager.py关键细节补充make serve默认DB_PATH为explainshell.db可用DB_PATHxxx make serve覆盖端口来自环境变量PORT默认 5000见 runserver.pymake ubuntu-archive内部执行 Go 构建的 ingest 工具manpages/ubuntu-manpages-operator子模块产出归档再经tools/postprocess_ubuntu_archive.py后处理到manpages/ubuntu/releaseArch 侧则依赖python tools/fetch_manned.py download --data-dir ignore/manned先行下载转储make test-llm通过环境变量RUN_LLM_TESTS1激活真实 LLM 调用避免默认测试套件产生费用。项目结构导览CLAUDE.md 给出了完整目录语义此处按模块整理并标注关键测试对应关系主包explainshell/manager.pyCLI 入口python -m explainshell.manager commanddb_check.py数据库完整性检查供manager.py db-check调用测试见 tests/test_db_check.pymatcher.py核心匹配逻辑遍历 Bash AST 并将 token 匹配到帮助文本测试见 tests/test_matcher.pymodels.py核心领域类型Option、ParsedManpage、RawManpagePydantic / dataclassstore.pySQLite 存储层测试见 tests/test_store.pycaching_store.py只读、大小感知的缓存 Store用于生产 Web 服务DEBUGfalse时 Flask 应用按 worker 进程各持一份于app.extensions测试见 tests/test_caching_store.pyerrors.py异常体系ProgramDoesNotExist、DuplicateManpage、InvalidSourcePath、ExtractionError、SkippedExtraction、FatalExtractionErrordiff.py手册比对与 diff 格式化roff_parser.py 与 roff_utils.pyroff 宏解析与源码检测dashless opts、嵌套命令manpage.py手册读取与 HTML 转换help_constants.pyshell 常量定义如NO_SYNOPSISutil.py共享工具group_continuous、Peekable、name_sectionconfig.py配置DB_PATH、HOST_IP、DEBUG、MANDOC_PATH、MANPAGE_URLSextraction/手册选项提取管线公共 API 为make_extractor(mode)工厂见 explainshell/extraction/init.py细分types.pyExtractionResult、ExtractionStats、BatchResult、ExtractorConfig与Extractor协议runner.py执行编排顺序 / 并行 / batchcommon.py各提取器共享的元数据组装prefilter.py提取前分类大小、符号链接、--filter-db、已入库、内容去重postprocess.py与提取器无关的选项后处理llm/LLM 提取子包含 extractor.py编排、prompt.py提示词构建、response.py响应解析、text.py文本准备与分块、providers/OpenAI、Gemini、LiteLLM 三类 Providerweb/views.pyFlask 路由基于 URL 的发行版/版本路由。tools/独立脚本含 fetch_manned.py拉取 manned.org 周更转储与mandoc-md带 markdown 输出的定制 mandoc 二进制路径由 config.py 的MANDOC_PATH指向。tests/单元测试与 fixturestests/e2e/为 Playwright e2e专用e2e.db与快照tests/evals/为人工评审型评测不纳入make tests-all分llm/LLM 提取评测与render/mandoc markdown 渲染评测。manpages/Git 子模块存放各发行版手册归档及 Ubuntu 归档 Go 管线ubuntu-manpages-operator抓取.deb包、提取手册并转 markdown。核心架构详解Man Page 处理管线CLAUDE.md 给出的管线总览manager.py编排raw .gz → parse → extract options → store in SQLite。CLI 使用子命令多数命令需要数据库路径DB_PATH环境变量或--db path指定不需要数据库的命令如extract --dry-run、diff extractors可脱离数据库运行。主要命令原文完整继承extract --mode mode [options] files...— 提取选项并入库diff db --mode mode files...— 将新提取结果与数据库存量做 diffdiff extractors A..B files...— 两个提取器同场对比show {manpage,distros,sections,manpages,mappings,stats}— 查询数据库db-check— 运行数据库完整性检查。提取模式--modellm:provider/model把手册文本发送给 LLM例如llm:openai/gpt-5-mini、llm:azure/my-deployment支持 Gemini、OpenAI、Azure OpenAI 与 LiteLLMfallback四种 Provider。azure/...的 model 后缀是 Azure 部署名需要AZURE_OPENAI_API_KEY以及AZURE_OPENAI_BASE_URL或AZURE_OPENAI_ENDPOINT之一。从 manager.py 的 docstring 可进一步确认一个进阶细节——推理强度可追加在模型串尾部openai/model/effort如llm:openai/o3/mediumlow / 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。提取参数原文完整继承并补充默认值--overwrite、--filter-db spec条件覆盖需与--overwrite同用语法同--mode可重复——只要命中任一 spec 即重提取、--dry-run、--debug、--drop、-j/--jobs int并行提取默认 1、--batch intProvider 批量 API。所有运行输出日志、调试产物、manifest统一落盘到logs/{timestamp}/。与 prefilter.py 结合可知--dry-run会输出每个输入文件的分类决策六种决策类型为Work将处理、SizeSkip大小过滤、AlreadyStored已入库、FilterSkip与--filter-db不符、Symlink符号链接归一、ContentDup内容去重。其中大小过滤阈值在 manager.py 定义为_SIZE_FILTER_THRESHOLD 2048字节该阈值以下视为廉价模型安全以上需要更强模型——此结论源自tools/experiments/eval_size_routing.py的实验阈值内页面与强模型在约 98% 文件上结果一致分歧从 4–8 KB 桶开始出现。数据模型与存储 SchemaSQLite 三张核心表store.py 的建表 DDLmanpagessource唯一基名、data压缩原始数据、generated_at、generator、generator_version、source_gz_sha256parsed_manpagessource主键形如ubuntu/26.04/1/tar.1.gz、name、synopsis、optionsJSON 列表、aliasesJSON、dashless_opts、subcommandsJSON、updated、nested_cmd、extractor、extraction_metaJSONmappings命令名 → 手册 ID 的查找表多对一score决定优先级也承载多命令父级映射如srcgit commit → dstgit-commit 手册 id并建有idx_mappings_dst与idx_mappings_src(src, dst, score)两个索引db_events追加式事件日志提取、上传等生命周期事件。此外 store.py 用正则^[a-zA-Z][a-zA-Z0-9_-]*/[^/]/[^/]/[^/]\.\d\w*\.gz$强制校验 source 的distro/release/section/name.section.gz格式不匹配抛InvalidSourcePathconfig.py 的source_from_path负责从本地路径提取该四段标识。领域类型models.pyPydantic 模型Optiontext、short/long标志列表、has_argument可布尔或字符串列表、positional、prefix位置参数必须以此字面 sigil 开头才能认领如 dig 的[server]中限定在OPTION_PREFIX_SIGILS白名单//:定义于 models.py、nested_cmd选项参数可否开启嵌套命令ParsedManpagesource、name、synopsis、options、aliases、dashless_opts、subcommands、updated、nested_cmd、extractor、extraction_meta提供positionals排除带前缀项与prefixed_positionals名称 → (prefix, 合并帮助文本)两个派生属性以及find_option(flag)查找to_store/from_store完成 JSON 序列化往返。CLAUDE.md 特别说明OPTION_PREFIX_SIGILS刻意保持窄集digserver、gccFILE参数文件、dateFORMAT、vi 风格line、:X display 编号均来自语料库全部 SYNOPSIS 的扫描误判前缀会把位置参数从有序匹配中整体移除例如 ssh 的[user]hostname绝不能成为前缀这是设计上宁缺毋滥的取舍。命令匹配matcher.py匹配器采用bashlex AST 访问者模式原文要点 源码佐证Matcher继承bashlex.ast.nodevisitormatcher.pyvisitcommand()查找手册、处理多命令如git commitvisitword()将 token 匹配到选项——先精确匹配再对组合短标志如-abc做模糊拆分位置参数双池机制CLAUDE.md 原文 matcher.py 的positional_index字段佐证带前缀的位置参数仅被以 sigil 开头的 token 认领8.8.8.8→ dig 的server其余 token 按顺序消耗非前缀位置参数最后一个可复用变参语义。token 携带了任何位置参数都未声明的 sigil 时回退到有序消耗若全部位置参数都带前缀且无一命中则该 token 判定为未知。产出MatchResult(start, end, text, match)其中start/end是原字符串中的字符位置text为None时表示未知参数unknown属性并携带debug_info供 explain 页调试面板使用。从tests/e2e/snapshots/中的explain-dig-prefixed-positional.png等快照可推断该机制是 dig 这类工具解释质量的关键不过图片仅为界面佐证不改变上述源码语义。Web Store 生命周期CLAUDE.md 原文要点附 caching_store.py 佐证Web 应用仅当DEBUGfalse生产与 e2e时使用CachingStore缓存 store 按 worker 进程懒创建并存放于app.extensions本地开发DEBUGtrue即make serve默认使用每请求新建的普通Store这样重建数据库无需重启服务器即可生效工具链explainshell.manager、tests/evals/llm/llm_eval.py应继续使用普通Store不要改用CachingStore。DEBUG的解析规则见 config.pyDEBUG os.getenv(DEBUG, true).lower() not in (0, false, no)即默认开启显式设为0/false/no才关闭。E2E 测试架构CLAUDE.md 原文e2e 采用**封闭hermetic**环境——专用tests/e2e/e2e.db 随机端口服务器每次运行全新启动reuseExistingServer: false。make e2e-db会用llm:codex/gpt-5.4/medium模型以-j 9并行构建 9 本测试手册tar、echo、grep、git-rebase、dig 的 Ubuntu 24.04/26.04 与 Arch 版本见 Makefile。LLM 提取评估llm_eval.py 实战CLAUDE.md 用相当篇幅规定 LLM 提取器的评测工作流这是修改 LLM 提取器API、提示词、分块、后处理时必须执行的对比流程。运行机制与产物评测入口 tests/evals/llm/llm_eval.py在 tests/evals/llm/corpus.txt 列出的语料上运行提取路径指向manpages/子模块并把summary.json与逐页产物markdown/、prompts/、responses/写入tests/evals/llm/runs/下的时间戳目录。摘要包含git 元数据、模型、label、描述、聚合指标提取成功/失败文件数、总选项数、零选项页、多分块页、token 用量以及按仓库相对路径键控的逐页指标。其默认模型为openai/gpt-5-minillm_eval.py。必备参数label 与描述run强制要求--label tag会并入运行目录名并接受-d ...长描述。CLAUDE.md 强调务必传入有意义的 label 与描述——例如当前任务的简称或改动前的 baseline——以保证list与compare输出自解释。例如-d baseline before short summary of change。代码改动标准流程baseline/change 对比原文给出的五步工作流完整继承# 1. Stash 改动以得到干净基线 git stash push -- explainshell/extraction/llm/ # 2. 在旧代码上运行 python tests/evals/llm/llm_eval.py run --label baseline --model codex/gpt-5.6-sol/medium --jobs 10 -d baseline before short summary of change # 3. 恢复改动 git stash pop # 4. 在新代码上运行 python tests/evals/llm/llm_eval.py run --label change --model codex/gpt-5.6-sol/medium --jobs 10 -d short summary of change # 5. 对比两个运行目录旧在前 python tests/evals/llm/llm_eval.py compare tests/evals/llm/runs/baseline-run tests/evals/llm/runs/change-run其它常用用法# 默认语料上运行并行化实时调用 python tests/evals/llm/llm_eval.py run --label smoke --model codex/gpt-5.6-sol/medium --jobs 10 # 指定文件覆盖 --corpus python tests/evals/llm/llm_eval.py run --label probe --model codex/gpt-5.6-sol/medium --jobs 10 path/to/file.1.gz # 用 --batch size 替代 --jobs走 Provider 批量 API # 更便宜但有数分钟到数小时的排队延迟仅在更大语料上划算 # 对比两个运行目录 python tests/evals/llm/llm_eval.py compare tests/evals/llm/runs/baseline-run tests/evals/llm/runs/current-run # 列出全部已保存运行 python tests/evals/llm/llm_eval.py list相关单元测试LLM 提取子包自带针对性单元测试tests/extraction/llm/test_extractor.py含真实 LLM 集成测试test_real_llm_echo_manpage由make test-llm触发、test_response.py响应解析、test_text.py文本准备/分块、test_openai_provider.py与test_codex_provider.pyProvider 层。代码风格约定CLAUDE.md 唯一一条硬性风格规则所有新代码必须带 Python 类型注解函数签名、返回类型、不显而易见的变量不追溯性注解既有代码除非正在修改它。该约定与 ruff.toml 的静态检查配套生效。部署与数据库更新生产基础设施CLAUDE.md 原文要点应用部署于DigitalOcean App PlatformSQLite 数据库在Docker 构建期内嵌进镜像从 GitHub Release 下载.zst构建时解压。生产链路为域名explainshell.com→ Cloudflare橙色云代理→ DigitalOcean App PlatformCloudflareDNS 代理SSL 模式Full (Strict)App specprod/digitalocean/app.yaml含 region、实例大小/数量、环境变量、自定义域名。重要约定doctl apps update --spec是全量替换任何带外配置会在下次部署时被清掉因此必须检入此文件容器产物prod/docker/Dockerfile、Caddyfile、start.sh。代码变更部署CI 驱动合并到master触发 CI 部署工作流解析最新db-latest资产名 → 用envsubst以DB_NAME与GIT_SHA渲染 spec →doctl apps update --spec应用 →doctl apps create-deployment --force-rebuild --wait强制全新构建。--force-rebuild是承重步骤deploy_on_push关闭时若无强制重建DO 会从缓存的过期分支头部署而非当前 commit。本地等价操作是make deploy-localMakefile解析最新资产名、envsubst渲染、应用 spec、强制重建带两道交互确认从本地部署与工作区脏是否继续并要求设置DO_APP_ID。更新数据库CLAUDE.md 原文两步make upload-live-db— 上传explainshell-{date}.db.zst资产到db-latestRelease若 digest 与最新一致则跳过推送master— 部署管线解析最新资产名作为 DockerDB_NAME构建参数传入下载层缓存被破坏以拉取新库。配套命令还有make download-latest-db下载线上库到本地explainshell.db与make prod-image本地构建生产镜像同样先经gh api解析db-latest资产名再docker build --build-arg DB_NAME...。完整镜像级验证链为make prod-integration构建镜像后执行 prod/integration-test.sh已被纳入tests-all。小结explainshell 的工程实践可概括为一条清晰的闭环make format与分层测试守护改动质量 →llm_eval.py的 baseline/change 对比守护 LLM 提取精度 → 封闭 e2e 守护 Web 匹配与渲染 → CI 强制重建守护生产部署与数据库一致性。若你要参与本仓库开发请牢记三条黄金规则所有命令前缀source .venv/bin/activate 、拿不准测试范围就跑make tests-all、任何带外部署配置一律检入 prod/digitalocean/app.yaml。深入阅读可直接从 CLAUDE.md 与 Makefile 起步再按需进入 manager.py、matcher.py、store.py 与 tests/evals/llm/llm_eval.py 的源码细节。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐告别命令行困惑explainshell如何智能解析man手册页告别命令行困惑explainshell如何智能解析man手册页 explainshell是一款能够智能匹配命令行参数与帮助文本的工具让开发者和系统管理员告后端开发工具AutoGPT Platform 后端开发指南Poetry 工作流、测试约定、Block 开发与 LLM 模型目录实战AutoGPT Platform 后端开发指南Poetry 工作流、测试约定、Block 开发与 LLM 模型目录实战 本文基于 AutoGPT 仓库中后端模人工智能AI Agent自主智能体Agent 工作流工作流自动化后端前端HyperDX 项目 Playwright 端到端测试编写指南Agent 驱动的 E2E 测试工作流与工程约定HyperDX 项目 Playwright 端到端测试编写指南Agent 驱动的 E2E 测试工作流与工程约定 本篇指南围绕 HyperDX 开源仓库中面向可观测性云原生运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考