后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载本篇技术指南围绕 explainshell 项目中的/eval-llm技能定义于 .claude/skills/eval-llm/SKILL.md展开系统讲解如何对explainshell/extraction/llm/的提示词、分块、后处理与 Provider 改动做端到端回归评测先跑出干净基线baseline再跑候选改动candidate对比后给出merge / regression / defer三态结论。读完本文你将掌握/eval-llm的全部命令参数、五步执行流程、逐页分类方法与评分准则并能结合仓库源码理解tests/evals/llm/llm_eval.py底层如何产出指标与可疑结构变化告警。eval-llm 是什么提交前的 LLM 抽取回归评测explainshell 的核心能力是把命令行参数匹配到它们的帮助文本其中一条抽取路径由 LLM 完成explainshell/extraction/llm/。当开发者改动这条管线的任何环节——提示词、文本分块、响应解析、后处理、Provider 配置——都需要回答一个问题这次改动是让抽取变好还是变坏/eval-llm技能就是为回答这个问题而生的它对当前工作树working tree做端到端评测深入对比 diff并给出是否安全提交的三态结论。该流程与项目内另一评测技能/eval-render同构后者对应 tests/evals/render/render_eval.py评测 mandoc 渲染链路先捕获干净基线 → 跑候选 → 对比 → 分类 → 出结论。两个评测共享一套纯函数工具内核语料读取、run 目录加载、指标查找、delta 格式化见 tests/evals/_common.py。命令格式与参数/eval-llm [--label tag] [--model model] [--description text]参数必选默认值说明--label否根据用户陈述的改动自动推断如prompt-tweak-v2、chunking-fix候选 run 目录的短标签基线 run 自动命名为baseline-clean--model否openai/gpt-5-miniLLM 模型。应选择用户迭代时使用的同一模型——评测容忍跨模型 token 差异但跨模型的 option 数量差异会干扰结论--description否用户改动的一句话摘要候选 run 的长描述其中默认模型openai/gpt-5-mini与tests/evals/llm/llm_eval.py中的DEFAULT_MODEL常量一致llm_eval.py。/eval-llm本质是对llm_eval.py这个 CLI 的编排封装后者提供三个子命令run跑一次评测并写 summary、compare对比两个 run、list枚举已保存的 run。Step 1产出基线 run 与候选 run评测需要两个 run一个针对未改动的代码一个针对用户的改动。如何切换两种代码状态git stash、commit 后回退、切换分支等由用户自己决定技能不预设方式。两个 run 都必须后台运行run_in_background: true因为单次 run 的典型耗时是 8–15 分钟不要轮询等待等任务完成通知后再启动下一个 run。source .venv/bin/activate \ python tests/evals/llm/llm_eval.py run --label tag --model model --jobs 10 -d one-line summary关键执行决策默认使用--jobs 10且不带--batch。batch API 对当前小语料有很高的排队延迟且当 batch_size 超过 chunk 数时会退化为串行--jobs N则是并行化 realtime API。以约 12 个语料页 × 每页约 20 个 chunk 估算jobs10大约 10 分钟跑完。只有用户明确要求用成本换墙钟时间时才使用--batch。batch 模式会额外生成batch-manifest.json记录批次的提交/完成/失败状态见 explainshell/extraction/manifest.py。候选tag要反映改动内容如prompt-tweak-v2、chunking-fix基线用baseline-clean或类似命名。输出末尾的Run directory:行给出两个 run 的目录路径必须记下compare 阶段要用。复用已有基线如果用户手里已有想复用的基线例如 tests/evals/llm/runs/ 下最近的 run可跳过基线 run直接用该路径。python tests/evals/llm/llm_eval.py list可列出所有已保存的 run含时间戳、git commit、模型、options 总数与描述源码见 llm_eval.py。语料来源run默认读取 tests/evals/llm/corpus.txt当前仓库中该文件列出 13 个 man pageavrdude、curl、dig、docker、echo、find、grep、ps、sed、ssh、tar、xargs、xz均来自 ubuntu/26.04路径经manpages/子模块解析#注释与空行被忽略。也可以用位置参数直接传.gz文件或目录覆盖语料或用--output指定 run 输出目录。run 到底做了什么从源码看llm_eval.pyrun_bench先收集.gz文件用ExtractorConfig(model, run_dir, repo_root, debugTrue)构建 LLM extractor然后经 explainshell/extraction/runner.py 的run分发器sequential / parallel / batch 三种模式逐个抽取每个文件的结果n_chunks、plain_text_len、n_options、dashless_opts、n_aliases、has_synopsis、token 用量等汇总为summary.json并写入run_dir/下的markdown/、prompts/、responses/三类调试工件。Step 2对比两个 runsource .venv/bin/activate \ python tests/evals/llm/llm_eval.py compare baseline-run candidate-run必须通读完整输出。三块内容值得关注Aggregate 表一眼看总量评分脚手架verdict scaffold就在这里。Per-page metric deltas哪些页面在哪些轴上发生了移动——extraction.n_options、extraction.n_chunks、extraction.plain_text_len、tokens.*。Suspicious structural changes评测标记了方向性问题的页面option 数量下降零容忍、success 翻转、malformed-options 增加。Token 的定位token 会打印在 deltas 区块但被刻意排除在可疑检查之外——仅模型抖动就能让它们波动 ±5%。评分时不要给 token 加权。源码层面可以印证这套告警策略llm_eval.py页面布尔检查_PAGE_BOOL_CHECKSextraction.success、extraction.has_synopsis、extraction.dashless_opts—— 任何翻转都视为需要浮出的回归页面数值检查_PAGE_NUMERIC_CHECKSextraction.n_options容差 0.0只标记下降、extraction.n_aliases容差 0.0只标记下降、extraction.n_chunks容差 0.0任何变化都标记聚合检查_AGGREGATE_CHECKSfailed_files、malformed_options、zero_option_pages上升即标记extracted_files、total_options下降即标记。compare还支持--fail-on-suspicious检测到可疑结构变化时以非零退出码返回便于接入 CIllm_eval.py。Step 3逐页分类每个被标记页面对Suspicious structural changes区块中的每个页面判定三类之一improvement改进、regression回归、ambiguous模糊。标记告诉你什么变了检查告诉你为什么。检查来源按廉价程度排序Per-page metric deltas 下的指标块option 数量下降是否跟随 chunk 数或纯文本长度下降大概率良性分块变了、真正能提取的 option 变少了还是纯下降而其他指标稳定大概率是抽取质量的真回归候选响应文件candidate-run/responses/safe-name.chunk-N.response.txt与基线的responses/same-name直接diff这些是纯文本看模型实际返回了哪些 option。候选提示词candidate-run/prompts/safe-name.chunk-N.prompt.json若改动涉及提示词构造与基线对比。mandoc 渲染后的 markdowncandidate-run/markdown/safe-name.md若改动涉及分块或文本准备与基线对比。自问这个页面上的移动是否指向同一方向该方向是否与用户 diff 的预期一致 当 delta 混杂、改动描述无法解释时判为ambiguous而不是猜测。信号与噪声LLM 抖动是真实存在的。单个页面单独摆动 ±2 个 option 通常是噪声两个或更多页面同方向一起移动、或单页移动超过其 option 数的 10%才是信号。工件命名细节safe-name是 repo 相对路径经过编码的 stem/替换为__、去掉.gz后缀见 tests/evals/_common.py这些工件由 extractor 的 debug 模式写入explainshell/extraction/llm/extractor.py。Step 4套用评分准则三态结论的判定规则merge⇢ 没有被标记的页面或所有被标记页面都归类为 improvement且聚合total_options未下降超过约 1%且failed_files/malformed_options持平或下降。此时建议用户提交并在改动触及渲染/分块文本路径时追加一次/eval-render。regression⇢ 存在任何被判为 regression 的页面或聚合total_options下降超过约 1%或failed_files/malformed_options上升。要告诉用户是哪些页面给出 before→after 数字和你检查过的响应文件路径。defer⇢ 存在任何 ambiguous 页面或检查未能消解的抖动-信号模糊性。询问用户是否重跑LLM 确定性是部分的第二组基线候选往往能澄清或是否想覆盖结论。注意 merge 分支里的~1%是技能文档给出的经验阈值与源码中页面级 0.0 容差并不冲突页面级对任何option 下降都零容忍地浮出聚合级则允许最多约 1% 的总量波动总量本来就是页面数的累计。Step 5汇报最终面向用户的报告直接输出在聊天中不落盘包含一行结论merge/regression/defer及置信度说明聚合快照total_options基线 → 候选failed_files/malformed_options的 deltatoken delta 用括号标注仅作参考两个 run 的目录路径每个被标记页面一行page: classification — one-line reason若merge根据用户改动描述推断的一行 commit message 草稿若regression列出希望修复迭代 agent 优先阅读的响应文件回归最严重的 1–2 个页面若defer触发放置的具体页面/指标以及能消除它们的证据通常是重跑一次或手动 diff 某个具体响应文件。源码级补充评测指标与抽取管线的衔接理解指标含义有助于正确解读对比输出。summary.json的aggregate字段llm_eval.py包括指标含义total_files/extracted_files/failed_files文件总数 / 成功数 / 失败数total_options所有成功页面的 option 总数核心质量指标malformed_options解析校验失败被跳过的 option 数extractor.py 中stats.malformed_options累计normalized_options/dropped_empty/deduped_options字段规范化数、空 option 丢弃数、去重数后处理阶段统计zero_option_pages/multi_chunk_pages/total_chunks零 option 页面数 / 多 chunk 页面数 / chunk 总数input_tokens/output_tokens/reasoning_tokenstoken 用量realtime 调用按页记录batch API 只返回聚合用量batch run 中页级 token 保持 0这些计数与抽取管线一一对应。LLM 抽取管线分三个阶段explainshell/extraction/llm/extractor.pyprepare()读取 man page、清理 mandoc 痕迹、过滤低价值小节、行号化、分块extract()每个 chunk 一次 LLM 请求累计 token 与耗时finalize()解析 JSON 响应、把行号引用还原成 option 文本、跨 chunk 去重、通用后处理、构建ParsedManpage/RawManpage。两个设计点直接影响评测解读其一LLM不直接返回 option 描述而是返回对编号源文本的行号区间最终文本由response.py本地重建——这让模型输出更小、存储文本确定其二分块在过滤后的纯文本上进行但行号相对原始过滤文档编号多 chunk 响应无需重编号即可合并。另外prepare()会跳过黑名单来源如被 Provider 内容过滤器误判为 jailbreak 的 man page见 extractor.py并对超大 man page 直接SkippedExtraction——这类页面会以failed_files或 skip 形态出现在评测汇总中解读时要与候选改动导致的失败区分开。--jobs N的并行执行由 runner.py 的滚动线程池实现最多同时提交jobs个任务late fatal error 不会让剩余语料全部预排队批处理模式则按文件整体分组单个文件的所有 chunk 进同一批见group_work_items文件在其批次完成后立即 finalizeon_result回调始终在主线程执行runner.py。实践技巧与注意事项模型一致性跨模型 token 差异评测可容忍但跨模型 option 数量差异会污染结论——候选 run 务必沿用用户迭代用的模型除非有明确理由换模型。后台运行纪律单 run 8–15 分钟是常态前后两个 run 顺序执行期间不要轮询收到完成通知再启动下一个。优先复用基线改动前先list看tests/evals/llm/runs/里有没有可复用的干净基线能省一次 10 分钟的 run。先看指标、再开文件分类被标记页面时按指标块 → 响应文件 diff → 提示词对比 → markdown 对比的廉价优先顺序推进多数情况下指标块就能给出答案。抖动处理单页 ±2 option 视为噪声两页同向移动或单页 10% 变化才算信号悬而未决就判 defer 并建议重跑一对 run而不是强行下结论。合并前的联动检查merge 通过不代表万事大吉——若改动触及渲染或分块文本路径技能明确建议补跑一次/eval-render对应 tests/evals/render/ 的 render 评测两条链路各自把关再提交。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐LLM 应用评估实战指南基于 llm-evaluation 技能构建可度量、可回归、可上线的评测体系LLM 应用评估实战指南基于 llm evaluation 技能构建可度量、可回归、可上线的评测体系 本篇文章以 agents24/agents 仓库中 llAI 插件AI 技能开发工具WeChatFerry 完整指南如何三步把微信机器人接上 DeepSeek 等大模型WeChatFerry 完整指南如何三步把微信机器人接上 DeepSeek 等大模型 回复重复消息占掉你半天时间或者你想把日常用的 AI 助手接入微信却找不Activepieces Chat Prompt Eval 实战指南用回归 Fixture 与 LLM 裁判为 AI Copilot 系统提示词建立评测门禁Activepieces Chat Prompt Eval 实战指南用回归 Fixture 与 LLM 裁判为 AI Copilot 系统提示词建立评测门禁工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考