拓冰网站定制 
后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载导读explainshell 依靠一个本地 vendor 的 mandoc 1.14.6 源码树把 gzip 压缩的 roff 手册页转换为 Markdown再经 CommonMark 渲染为网页、并作为 LLM 抽取选项说明的文本源MANDOC_PATH默认指向 tools/mandoc-md见 explainshell/config.py。当mandoc -T markdown输出出现某类渲染缺陷如粗体/斜体强调符泄漏为****、roff 转义泄漏、空em标签时项目采用一条编排者 → 子代理 → 三层验证 → 决定晋升的修复流水线。本文以 subagent-brief 模板 为骨架完整拆解该模板的 13 个占位符、修复过程中的不可违反不变量invariants、make regress与 render_eval.py 交叉验证的实操命令并深入源码说明zwnj;、pending_close_marker等关键机制为何是承重墙。读完你就能独立驱动一次 mandoc 渲染缺陷从定位、修复、验证到晋升的完整闭环。一、背景为什么 explainshell 需要一条专门的 mandoc 修复流水线explainshell 的手册页文本链路是manpage .gz ──mandoc -T markdown──▶ Markdown ──CommonMark (cmark-gfm)──▶ HTML / LLM 文本文本抽取侧explainshell/extraction/llm/text.py的get_manpage_text()直接以[config.MANDOC_PATH, -T, markdown, gz_path]调用 mandoctext.py失败时抛出FailureReason.MANDOC_FAILEDexplainshell/errors.py网页渲染侧explainshell/web/markdown.py用 CommonMark 把这份 Markdown 再渲染成 HTML。这意味着 mandoc 输出的每一个字符级细节都会被 CommonMark 的 delimter-run、flanking 规则放大。比如**--config-file*****file*这类粗体/斜体接壤处的泄漏会被 CommonMark 折叠成乱码强调\fX字体转义或\[name]命名转义一旦泄漏就会原样出现在网页上。因此项目把 mandoc 二进制的版本也纳入追踪——explainshell/extraction/common.py通过resolve_mandoc_version()区分仓库追踪的tools/mandoc-md干净/脏工作区与自定义二进制common.py。由于官方 mandoc 并不总能满足 explainshell 对-T markdown输出的苛刻要求项目 vendor 了一份 mandoc 1.14.6 源码树并堆叠了一批本地修复。修复工作不能直接在主仓库进行主仓库只读而是派发一个全新的通用子代理到独立的 mandoc 工作树去改 C 源码——这正是 subagent-brief 模板 的用途。二、模板解剖13 个占位符与每一节的职责模板头部注释!-- ... --明确要求编排者在ANGLE_BRACKETS处填入实际值后把渲染后的文本整体派发给全新子代理每一节都必须承担重量如果某节为空就整节丢弃而不是输出空占位符。2.1 必须替换的占位符清单占位符含义示例 / 取值要点{{WORKTREE}}mandoc 工作树的绝对路径/home/idank/dev/vibe/mandoc-1.14.6模板作者机器上的惯例路径实际以编排者配置为准{{HEAD_COMMIT}}工作树中git log --oneline -1的输出让子代理知道当前 HEAD 在哪{{LOCAL_HISTORY}}近期本地提交的子弹列表每项含主题行 一句意图子代理必须不能破坏这些提交{{BUG_NAME}}缺陷类的短标签如quad_star_run对应的缺陷{{BUG_DESCRIPTION}}用通俗英语说明缺陷为何重要写成无需上下文、子代理也能懂{{REPRO_CLI}}演示缺陷与期望输出的printf \| mandoc调用可复现的最小命令{{REPRO_PAGE}}至少一个含该模式的真实 manpage 路径位于manpages/下如manpages/arch/latest/1/sox.1.gz{{ACCEPTANCE_TESTS}}候选实现必须产出的编号验收清单可验证、可判定{{INVARIANTS}}绝对不能改变的行为清单如斜体仍输出*...*、zwnj;插入保持原样、词内斜体仍可用{{AUDIT_RULE}}计数必须下降的审计规则 ID如quad_star_run合法 ID 全集见下文 5.3 节{{AUDIT_PAGE_SET}}标准语料库或path下的 N 页清单决定绝对基线渲染的对象集合{{BASELINE_COUNT}}派发前实测的基线计数P pages, N occurrences子代理必须严格低于它{{REPORTING_FIELDS}}编排者需要的回传字段提交哈希、冒烟测试输出、审计计数、回归清点、判断说明2.2 模板正文的结构语义模板正文依次包含 8 个功能段工作环境声明明确子代理身处{{WORKTREE}}、用make构建、产物是./mandocContextHEAD 位置 必须保留的近期本地提交列表缺陷定义The bug —{{BUG_NAME}}通俗描述 Repro 小节——CLI 可复现命令{{REPRO_CLI}}与真实 manpage 示例{{REPRO_PAGE}}位于manpages/下即模板原文的../explainshell/manpages/相对路径在本仓库的对应物期望产出What I want编号验收测试不变量Invariants必须持续工作的行为过程Process7 步操作指南详见下文第四节禁止事项What NOT to do4 条红线回传Reporting back按{{REPORTING_FIELDS}}给出简短总结若有阻塞则停下报告、绝不交付半成品。三、Repro 与验收把缺陷类变成可判定的句子模板强制要求两样东西让缺陷可判定CLI 级最小复现和真实语料佐证。# {{REPRO_CLI}}printf 构造 roff 输入管道交给工作树的 mandoc printf ...roff 片段... | {{WORKTREE}}/mandoc -T markdown # 期望输出修复后的正确 Markdown模板中一并给出{{REPRO_PAGE}}则保证这不是一个玩具案例——缺陷类必须至少在manpages/下的一页真实手册页例如 corpus.txt 中专门保留的 sox、hwloc-bind、play、hledger 等已知quad_star_run生产者中真实存在。验收测试{{ACCEPTANCE_TESTS}}由编排者按缺陷类编号列出例如输出中不再出现 4 连星号运行em不再为空等。值得强调的是不变量清单的优先级高于修复本身{{INVARIANTS}}记录了修复时绝不能踩的既有行为。模板给出了三个典型例子斜体仍输出*...*若近期本地提交已把斜体从*切换为_则反之zwnj;插入机制保持完整——它是粗体↔斜体接壤的承重墙词内斜体intraword italic仍工作。3.1zwnj;为什么是承重墙源码证据clean_mandoc_artifacts()的文档字符串explainshell/extraction/llm/text.py给出了精确解释mandoc 在粗体/斜体强调区间接壤处插入零宽连接符实体使**foo**zwnj;*bar*中;成为 ASCII 标点从而让 CommonMark 的 delimiter-run flanking 规则把两段强调解析为独立区间。若剥离zwnj;就会产生**--config-file*****file*这类被 CommonMark 折叠成乱码的模式。clean_mandoc_artifacts只把nbsp;替换为普通空格、刻意保留zwnj;。此外文档还对比了 Pandoc不输出分隔符会误解析**flag**arg-name与 Pod::Markdown用_表示斜体会破坏 ffmpeg.1、git.1、tar.1 中泛滥的词内斜体如_N_th两种业界替代路线结论是 mandoc 的zwnj;恰好同时躲开这两个坑——这解释了模板为什么把zwnj;机制列为红线。四、Process子代理的 7 步修复指南逐条实操模板的 Process 节给出子代理必须遵循的操作序列这是整份 brief 最可执行的部分Step 1 — 先读历史再动代码git log -p range修补mdoc_markdown.c之前必须通读近期本地提交的 diff——它们与将要修改的代码共享数据结构。这是模板反复强调先看{{LOCAL_HISTORY}}的原因。Step 2 — 实现修复优先扩展现有机器的既有机制模板明确建议复用pending_close_marker、marker_stack、outer_marker、字体模式辅助函数font-mode helpers而不是发明新的全局状态。这是 mandoc 渲染器 C 代码里维护强调符配对与嵌套的核心数据结构改动面最小、回归风险最低。Step 3 — 构建makeStep 4 — 跑 CLI 复现并确认期望输出直接执行第二节的printf | mandoc -T markdown命令核对输出与{{REPRO_CLI}}中给出的期望结果一致。Step 5 — 全量回归与夹具make regress # 必须 100% 通过仅当改动确实合法地改变既有夹具期望输出时才更新 fixture新用例夹具放在regress/man/B/或regress/mdoc/下风格参照近期新增的regress/man/B/emphasis_transitions。注regress/目录属于 mandoc 工作树而非本仓库模板以此指示子代理在何处落夹具。Step 6 — 在审计页集上交叉验证从 explainshell 仓库侧执行模板原文给出的是编排者机器的路径约定实际路径以环境为准source .venv/bin/activate python tests/evals/render/render_eval.py render \ --label candidate-{{BUG_NAME}} --mandoc {{WORKTREE}}/mandoc CORPUS_OR_LIST python tests/evals/render/render_eval.py audit run-dir --rules {{AUDIT_RULE}}验收目标{{AUDIT_RULE}}计数严格低于基线{{BASELINE_COUNT}}P pages, N occurrences。可接受的残余必须是内容驱动的例如源 roff 中本身就有字面*并要在报告中显式标注让编排者去核实而不是猜。Step 7 — 提交提交信息采用 Conventional Commits 形状Fix -T markdown: one-line正文Body需说明机制、引用规范动机页{{REPRO_PAGE}}、并注明任何被接受的残余。五、验证侧render eval 评测器与审计规则体系子代理的 Step 6 与编排者的验证都依赖 tests/evals/render/render_eval.py——一个有意的评审工具而非黄金快照测试README 明确它不接入make tests-all仅在改动tools/mandoc-md、explainshell/web/markdown.py或clean_mandoc_artifacts/filter_sections时手工运行。5.1 四个子命令子命令作用关键参数render用指定 mandoc 二进制渲染语料为每页产出markdown/*.md、html/*.html、metrics/*.json三类工件与summary.json--label必填、--mandoc、--corpus、--output、--fail-on-failurecompare对比两次渲染报告可疑结构变化与指标差baseline current、--fail-on-suspiciousdiff生成 Playwright 风格截图对比报告diff-report/index.html带可拖拽对比滑条--all、--limit N、--output、--timeoutaudit对一次渲染做无基线的绝对缺陷审计--rules逗号分隔默认全部、--fail-on-violation典型调用序列来自 READMEsource .venv/bin/activate # 基线当前 vendor 的二进制 python tests/evals/render/render_eval.py render --label repo-mandoc --mandoc tools/mandoc-md # 候选打了补丁的 mandoc 树 python tests/evals/render/render_eval.py render --label patched-mandoc --mandoc ~/dev/vibe/mandoc-1.14.6/mandoc # 对比两次 run 目录由 render 命令末尾的 run directory: 打印 python tests/evals/render/render_eval.py compare tests/evals/render/runs/baseline-run tests/evals/render/runs/candidate-run # 截图报告若浏览器缺失先 npx playwright install chromium python tests/evals/render/render_eval.py diff tests/evals/render/runs/baseline-run tests/evals/render/runs/candidate-run5.2 指标设计为什么任何非零 delta 都算可疑compare的_suspicious_changes()render_eval.py对所有阈值设为 0.0——结构性指标极少偶然变动所以任何非零 delta 都会浮出页面这恰好让小而有意的结构改进也能被标记审查。它同时统计三类指标markdown 行级指标行数、字符数、max_line_length、giant_lines_500/1000、option_like_tokens、unescaped_star_runs、unescaped_under_runs正则(?!\\)\*与(?!\\)_直接度量转义泄漏filtered 指标经clean_mandoc_artifactsfilter_sections清洗后的行数/字符数/移除节数removed_sections变化也算可疑HTML 结构指标用标准库HTMLParser统计 26 个标签计数、data_chars、max_depth及\ [ ] * _ \ 等敏感字符直方图。5.3 审计规则全集--rules可选 IDAUDIT_RULESrender_eval.py内置 11 条无基线绝对审计规则规则 ID扫描对象匹配模式正则quad_star_runmarkdown(?!\\)\*{4,}4 连星号如**foo****bar**empty_emphasis_taghtmlem\|strong ...\s*/\1空强调标签roff_named_escapehtml 去标签文本\\\[([A-Za-z0-9_-])\]且名称须在KNOWN_MANDOC_ESCAPE_NAMES白名单内roff_two_letter_escapehtml 去标签文本\\\(([A-Za-z0-9]{2})同样校验白名单roff_font_escapehtml 去标签文本\\f[BIRP]\b字体转义泄漏visible_zwnj_entityhtml 去标签文本zwnj;字面实体visible_nbsp_entityhtml 去标签文本nbsp;字面实体visible_double_amphtml 去标签文本amp;amp;双重编码与号visible_open_double_backtickmarkdown\\\不对称排版开引号泄漏giant_markdown_linemarkdown行长度 2000 字符synopsis_no_spaces_runmarkdownSYNOPSIS 节内 200 字符且无空白两个值得注意的实现细节roff_named_escape/roff_two_letter_escape会先用KNOWN_MANDOC_ESCAPE_NAMES白名单覆盖 mandoc_char(7) 的两字母与方括号命名转义全集过滤——像 lsof.8 中作者有意书写的\[bfrnt]这类 C 语言简写不会被误报synopsis_no_spaces_run则以# SYNOPSIS标题进入、遇到下一个标题退出只在 SYNOPSIS 区间内计数。5.4 语料库构成默认语料 tests/evals/render/corpus.txt 按四种意图挑选页面本就渲染良好的主食页grep、sed、ssh、tar…、选项密集的大页curl、find、ps、xz…、已知 markdown 压缩了选项清单的 ImageMagick 页、.IP/.TP连续重载的 git 系列以及专门为quad_star_run规则保留信号的 sox、hwloc-bind、play、hledger。语料路径经manpages/子模块解析git submodule update --init初始化一次可用render后追加路径的方式临时渲染子集而不改动语料。audit报告按页面 × 出现次数输出每页最多列 10 条并给首个示例片段——这正是模板中基线计数P pages, N occurrences的来源。六、编排者侧三层验证与晋升决策子代理回报提交 重建后的二进制后mandoc-fix SKILL 的编排者按三层验证收口绝对检查承重用候选二进制重渲染同一页集并audit对比基线——目标规则的pages × occurrences严格下降残余须由子代理报告区分回归网调用/eval-render candidate-binary跑标准 compareeval-render SKILL与目标规则无关的可疑 delta 即为回归每个被标记页面须判定 improvement / regression / ambiguous抽查对受影响最深的 2–3 页做视觉 diff确认修复与子代理的 repro 一致且无新视觉伪影。最终按三条出路裁决merge⇢ 绝对计数严格下降、compare 无回归、抽查干净。晋升命令为cp candidate tools/mandoc-md git add tools/mandoc-md git commit -m feat(tools): promote mandoc-md with one-line summary Picks up mandoc upstream-commit (\upstream-subject\). impact line. rule drops from baseline to candidate across the page-set.regression⇢ 任一验证层失败带着点名具体回归 具体验收测试的 delta brief 重新派发defer⇢ 证据模糊如绝对计数下降但 compare 标记结构变化把证据呈现给用户并请示。晋升后可提议须用户明确同意才执行/eval-llm抽查、用python -m explainshell.manager extract --mode llm:model --overwrite -j 10 --reason one-line重抽取受影响页面以及make upload-live-db上传线上数据库——这些都是有成本或生产影响的下游动作模板与 SKILL 均禁止未经确认擅自执行。七、红线清单What NOT to do与失败哲学模板最后给出了四条不可逾越的红线也是修复质量的最低保障不要为斜体重引*若近期本地提交已把斜体切换为_或反之先查{{LOCAL_HISTORY}}再动手不要移除zwnj;插入机制它是粗体↔斜体接壤的承重墙第 3.1 节的源码证据已说明缘由不要触碰{{WORKTREE}}之外的任何文件mandoc 工作树与 explainshell 主仓库隔离候选二进制也不得自行提升到tools/晋升是编排者的职责不要 push子代理在自己的工作树提交是否推送上游由用户决定。最后的失败哲学同样值得借鉴如果任何东西阻塞了修复例如它会回归某个不变量停下并报告——不要交付部分修复。配合{{REPORTING_FIELDS}}回传提交哈希、冒烟测试输出、审计计数、回归清点与判断说明编排者可以做到全程可核实而非靠猜。八、结语把模板落地到自己的仓库subagent-brief.md的价值在于它把修复一个 C 渲染器缺陷这种高不确定性任务压缩成参数化、可判定、可回传的子代理任务以printf | mandoc -T markdown做最小复现、以真实 manpage 佐证、以验收测试 不变量双重约束、以make regress与render_eval.py audit做定量门禁、以 Conventional Commits 与结构化回传收尾。若你的项目也 vendor 了 mandoc 并依赖-T markdown输出这套模板可以直接复用把{{WORKTREE}}换成你的源码树路径、{{REPRO_CLI}}换成你的缺陷复现、{{AUDIT_RULE}}换成 render_eval.py 中与你缺陷对应的规则 ID或自行扩展AUDIT_RULES表即可获得同样的诊断 → 修复 → 验证 → 晋升闭环。整个流程的每一环都能在本仓库找到可执行依据编排逻辑在 mandoc-fix SKILL验证工具在 render_eval.py 与 README下游文本处理在 explainshell/extraction/llm/text.py。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐Explainshell 渲染评估指南用 eval-render 系统化评测 mandoc Markdown 渲染输出Explainshell 渲染评估指南用 eval render 系统化评测 mandoc Markdown 渲染输出 本指南完整讲解 Explainshel后端开发工具Voyager Markdown 渲染修复机制详解自动修复 Gemini 断裂的加粗标记Voyager Markdown 渲染修复机制详解自动修复 Gemini 断裂的加粗标记 Gemini™ 网页界面在渲染对话内容时常会在文本中插入引用来源、AI 应用前端插件系统提示工程Salt napalm_network 模块修复实战内联模板渲染崩溃与 commit_at 定时提交调度Salt napalm_network 模块修复实战内联模板渲染崩溃与 commit_at 定时提交调度 本篇文章围绕 Salt 仓库 changelog/6运维配置管理后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 explainshell 的 mandoc 渲染修复流水线：subagent-brief 模板与 `-T markdown` 输出修复实战指南
后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载导读explainshell 依靠一个本地 vendor 的 mandoc 1.14.6 源码树把 gzip 压缩的 roff 手册页转换为 Markdown再经 CommonMark 渲染为网页、并作为 LLM 抽取选项说明的文本源MANDOC_PATH默认指向 tools/mandoc-md见 explainshell/config.py。当mandoc -T markdown输出出现某类渲染缺陷如粗体/斜体强调符泄漏为****、roff 转义泄漏、空em标签时项目采用一条编排者 → 子代理 → 三层验证 → 决定晋升的修复流水线。本文以 subagent-brief 模板 为骨架完整拆解该模板的 13 个占位符、修复过程中的不可违反不变量invariants、make regress与 render_eval.py 交叉验证的实操命令并深入源码说明zwnj;、pending_close_marker等关键机制为何是承重墙。读完你就能独立驱动一次 mandoc 渲染缺陷从定位、修复、验证到晋升的完整闭环。一、背景为什么 explainshell 需要一条专门的 mandoc 修复流水线explainshell 的手册页文本链路是manpage .gz ──mandoc -T markdown──▶ Markdown ──CommonMark (cmark-gfm)──▶ HTML / LLM 文本文本抽取侧explainshell/extraction/llm/text.py的get_manpage_text()直接以[config.MANDOC_PATH, -T, markdown, gz_path]调用 mandoctext.py失败时抛出FailureReason.MANDOC_FAILEDexplainshell/errors.py网页渲染侧explainshell/web/markdown.py用 CommonMark 把这份 Markdown 再渲染成 HTML。这意味着 mandoc 输出的每一个字符级细节都会被 CommonMark 的 delimter-run、flanking 规则放大。比如**--config-file*****file*这类粗体/斜体接壤处的泄漏会被 CommonMark 折叠成乱码强调\fX字体转义或\[name]命名转义一旦泄漏就会原样出现在网页上。因此项目把 mandoc 二进制的版本也纳入追踪——explainshell/extraction/common.py通过resolve_mandoc_version()区分仓库追踪的tools/mandoc-md干净/脏工作区与自定义二进制common.py。由于官方 mandoc 并不总能满足 explainshell 对-T markdown输出的苛刻要求项目 vendor 了一份 mandoc 1.14.6 源码树并堆叠了一批本地修复。修复工作不能直接在主仓库进行主仓库只读而是派发一个全新的通用子代理到独立的 mandoc 工作树去改 C 源码——这正是 subagent-brief 模板 的用途。二、模板解剖13 个占位符与每一节的职责模板头部注释!-- ... --明确要求编排者在ANGLE_BRACKETS处填入实际值后把渲染后的文本整体派发给全新子代理每一节都必须承担重量如果某节为空就整节丢弃而不是输出空占位符。2.1 必须替换的占位符清单占位符含义示例 / 取值要点{{WORKTREE}}mandoc 工作树的绝对路径/home/idank/dev/vibe/mandoc-1.14.6模板作者机器上的惯例路径实际以编排者配置为准{{HEAD_COMMIT}}工作树中git log --oneline -1的输出让子代理知道当前 HEAD 在哪{{LOCAL_HISTORY}}近期本地提交的子弹列表每项含主题行 一句意图子代理必须不能破坏这些提交{{BUG_NAME}}缺陷类的短标签如quad_star_run对应的缺陷{{BUG_DESCRIPTION}}用通俗英语说明缺陷为何重要写成无需上下文、子代理也能懂{{REPRO_CLI}}演示缺陷与期望输出的printf \| mandoc调用可复现的最小命令{{REPRO_PAGE}}至少一个含该模式的真实 manpage 路径位于manpages/下如manpages/arch/latest/1/sox.1.gz{{ACCEPTANCE_TESTS}}候选实现必须产出的编号验收清单可验证、可判定{{INVARIANTS}}绝对不能改变的行为清单如斜体仍输出*...*、zwnj;插入保持原样、词内斜体仍可用{{AUDIT_RULE}}计数必须下降的审计规则 ID如quad_star_run合法 ID 全集见下文 5.3 节{{AUDIT_PAGE_SET}}标准语料库或path下的 N 页清单决定绝对基线渲染的对象集合{{BASELINE_COUNT}}派发前实测的基线计数P pages, N occurrences子代理必须严格低于它{{REPORTING_FIELDS}}编排者需要的回传字段提交哈希、冒烟测试输出、审计计数、回归清点、判断说明2.2 模板正文的结构语义模板正文依次包含 8 个功能段工作环境声明明确子代理身处{{WORKTREE}}、用make构建、产物是./mandocContextHEAD 位置 必须保留的近期本地提交列表缺陷定义The bug —{{BUG_NAME}}通俗描述 Repro 小节——CLI 可复现命令{{REPRO_CLI}}与真实 manpage 示例{{REPRO_PAGE}}位于manpages/下即模板原文的../explainshell/manpages/相对路径在本仓库的对应物期望产出What I want编号验收测试不变量Invariants必须持续工作的行为过程Process7 步操作指南详见下文第四节禁止事项What NOT to do4 条红线回传Reporting back按{{REPORTING_FIELDS}}给出简短总结若有阻塞则停下报告、绝不交付半成品。三、Repro 与验收把缺陷类变成可判定的句子模板强制要求两样东西让缺陷可判定CLI 级最小复现和真实语料佐证。# {{REPRO_CLI}}printf 构造 roff 输入管道交给工作树的 mandoc printf ...roff 片段... | {{WORKTREE}}/mandoc -T markdown # 期望输出修复后的正确 Markdown模板中一并给出{{REPRO_PAGE}}则保证这不是一个玩具案例——缺陷类必须至少在manpages/下的一页真实手册页例如 corpus.txt 中专门保留的 sox、hwloc-bind、play、hledger 等已知quad_star_run生产者中真实存在。验收测试{{ACCEPTANCE_TESTS}}由编排者按缺陷类编号列出例如输出中不再出现 4 连星号运行em不再为空等。值得强调的是不变量清单的优先级高于修复本身{{INVARIANTS}}记录了修复时绝不能踩的既有行为。模板给出了三个典型例子斜体仍输出*...*若近期本地提交已把斜体从*切换为_则反之zwnj;插入机制保持完整——它是粗体↔斜体接壤的承重墙词内斜体intraword italic仍工作。3.1zwnj;为什么是承重墙源码证据clean_mandoc_artifacts()的文档字符串explainshell/extraction/llm/text.py给出了精确解释mandoc 在粗体/斜体强调区间接壤处插入零宽连接符实体使**foo**zwnj;*bar*中;成为 ASCII 标点从而让 CommonMark 的 delimiter-run flanking 规则把两段强调解析为独立区间。若剥离zwnj;就会产生**--config-file*****file*这类被 CommonMark 折叠成乱码的模式。clean_mandoc_artifacts只把nbsp;替换为普通空格、刻意保留zwnj;。此外文档还对比了 Pandoc不输出分隔符会误解析**flag**arg-name与 Pod::Markdown用_表示斜体会破坏 ffmpeg.1、git.1、tar.1 中泛滥的词内斜体如_N_th两种业界替代路线结论是 mandoc 的zwnj;恰好同时躲开这两个坑——这解释了模板为什么把zwnj;机制列为红线。四、Process子代理的 7 步修复指南逐条实操模板的 Process 节给出子代理必须遵循的操作序列这是整份 brief 最可执行的部分Step 1 — 先读历史再动代码git log -p range修补mdoc_markdown.c之前必须通读近期本地提交的 diff——它们与将要修改的代码共享数据结构。这是模板反复强调先看{{LOCAL_HISTORY}}的原因。Step 2 — 实现修复优先扩展现有机器的既有机制模板明确建议复用pending_close_marker、marker_stack、outer_marker、字体模式辅助函数font-mode helpers而不是发明新的全局状态。这是 mandoc 渲染器 C 代码里维护强调符配对与嵌套的核心数据结构改动面最小、回归风险最低。Step 3 — 构建makeStep 4 — 跑 CLI 复现并确认期望输出直接执行第二节的printf | mandoc -T markdown命令核对输出与{{REPRO_CLI}}中给出的期望结果一致。Step 5 — 全量回归与夹具make regress # 必须 100% 通过仅当改动确实合法地改变既有夹具期望输出时才更新 fixture新用例夹具放在regress/man/B/或regress/mdoc/下风格参照近期新增的regress/man/B/emphasis_transitions。注regress/目录属于 mandoc 工作树而非本仓库模板以此指示子代理在何处落夹具。Step 6 — 在审计页集上交叉验证从 explainshell 仓库侧执行模板原文给出的是编排者机器的路径约定实际路径以环境为准source .venv/bin/activate python tests/evals/render/render_eval.py render \ --label candidate-{{BUG_NAME}} --mandoc {{WORKTREE}}/mandoc CORPUS_OR_LIST python tests/evals/render/render_eval.py audit run-dir --rules {{AUDIT_RULE}}验收目标{{AUDIT_RULE}}计数严格低于基线{{BASELINE_COUNT}}P pages, N occurrences。可接受的残余必须是内容驱动的例如源 roff 中本身就有字面*并要在报告中显式标注让编排者去核实而不是猜。Step 7 — 提交提交信息采用 Conventional Commits 形状Fix -T markdown: one-line正文Body需说明机制、引用规范动机页{{REPRO_PAGE}}、并注明任何被接受的残余。五、验证侧render eval 评测器与审计规则体系子代理的 Step 6 与编排者的验证都依赖 tests/evals/render/render_eval.py——一个有意的评审工具而非黄金快照测试README 明确它不接入make tests-all仅在改动tools/mandoc-md、explainshell/web/markdown.py或clean_mandoc_artifacts/filter_sections时手工运行。5.1 四个子命令子命令作用关键参数render用指定 mandoc 二进制渲染语料为每页产出markdown/*.md、html/*.html、metrics/*.json三类工件与summary.json--label必填、--mandoc、--corpus、--output、--fail-on-failurecompare对比两次渲染报告可疑结构变化与指标差baseline current、--fail-on-suspiciousdiff生成 Playwright 风格截图对比报告diff-report/index.html带可拖拽对比滑条--all、--limit N、--output、--timeoutaudit对一次渲染做无基线的绝对缺陷审计--rules逗号分隔默认全部、--fail-on-violation典型调用序列来自 READMEsource .venv/bin/activate # 基线当前 vendor 的二进制 python tests/evals/render/render_eval.py render --label repo-mandoc --mandoc tools/mandoc-md # 候选打了补丁的 mandoc 树 python tests/evals/render/render_eval.py render --label patched-mandoc --mandoc ~/dev/vibe/mandoc-1.14.6/mandoc # 对比两次 run 目录由 render 命令末尾的 run directory: 打印 python tests/evals/render/render_eval.py compare tests/evals/render/runs/baseline-run tests/evals/render/runs/candidate-run # 截图报告若浏览器缺失先 npx playwright install chromium python tests/evals/render/render_eval.py diff tests/evals/render/runs/baseline-run tests/evals/render/runs/candidate-run5.2 指标设计为什么任何非零 delta 都算可疑compare的_suspicious_changes()render_eval.py对所有阈值设为 0.0——结构性指标极少偶然变动所以任何非零 delta 都会浮出页面这恰好让小而有意的结构改进也能被标记审查。它同时统计三类指标markdown 行级指标行数、字符数、max_line_length、giant_lines_500/1000、option_like_tokens、unescaped_star_runs、unescaped_under_runs正则(?!\\)\*与(?!\\)_直接度量转义泄漏filtered 指标经clean_mandoc_artifactsfilter_sections清洗后的行数/字符数/移除节数removed_sections变化也算可疑HTML 结构指标用标准库HTMLParser统计 26 个标签计数、data_chars、max_depth及\ [ ] * _ \ 等敏感字符直方图。5.3 审计规则全集--rules可选 IDAUDIT_RULESrender_eval.py内置 11 条无基线绝对审计规则规则 ID扫描对象匹配模式正则quad_star_runmarkdown(?!\\)\*{4,}4 连星号如**foo****bar**empty_emphasis_taghtmlem\|strong ...\s*/\1空强调标签roff_named_escapehtml 去标签文本\\\[([A-Za-z0-9_-])\]且名称须在KNOWN_MANDOC_ESCAPE_NAMES白名单内roff_two_letter_escapehtml 去标签文本\\\(([A-Za-z0-9]{2})同样校验白名单roff_font_escapehtml 去标签文本\\f[BIRP]\b字体转义泄漏visible_zwnj_entityhtml 去标签文本zwnj;字面实体visible_nbsp_entityhtml 去标签文本nbsp;字面实体visible_double_amphtml 去标签文本amp;amp;双重编码与号visible_open_double_backtickmarkdown\\\不对称排版开引号泄漏giant_markdown_linemarkdown行长度 2000 字符synopsis_no_spaces_runmarkdownSYNOPSIS 节内 200 字符且无空白两个值得注意的实现细节roff_named_escape/roff_two_letter_escape会先用KNOWN_MANDOC_ESCAPE_NAMES白名单覆盖 mandoc_char(7) 的两字母与方括号命名转义全集过滤——像 lsof.8 中作者有意书写的\[bfrnt]这类 C 语言简写不会被误报synopsis_no_spaces_run则以# SYNOPSIS标题进入、遇到下一个标题退出只在 SYNOPSIS 区间内计数。5.4 语料库构成默认语料 tests/evals/render/corpus.txt 按四种意图挑选页面本就渲染良好的主食页grep、sed、ssh、tar…、选项密集的大页curl、find、ps、xz…、已知 markdown 压缩了选项清单的 ImageMagick 页、.IP/.TP连续重载的 git 系列以及专门为quad_star_run规则保留信号的 sox、hwloc-bind、play、hledger。语料路径经manpages/子模块解析git submodule update --init初始化一次可用render后追加路径的方式临时渲染子集而不改动语料。audit报告按页面 × 出现次数输出每页最多列 10 条并给首个示例片段——这正是模板中基线计数P pages, N occurrences的来源。六、编排者侧三层验证与晋升决策子代理回报提交 重建后的二进制后mandoc-fix SKILL 的编排者按三层验证收口绝对检查承重用候选二进制重渲染同一页集并audit对比基线——目标规则的pages × occurrences严格下降残余须由子代理报告区分回归网调用/eval-render candidate-binary跑标准 compareeval-render SKILL与目标规则无关的可疑 delta 即为回归每个被标记页面须判定 improvement / regression / ambiguous抽查对受影响最深的 2–3 页做视觉 diff确认修复与子代理的 repro 一致且无新视觉伪影。最终按三条出路裁决merge⇢ 绝对计数严格下降、compare 无回归、抽查干净。晋升命令为cp candidate tools/mandoc-md git add tools/mandoc-md git commit -m feat(tools): promote mandoc-md with one-line summary Picks up mandoc upstream-commit (\upstream-subject\). impact line. rule drops from baseline to candidate across the page-set.regression⇢ 任一验证层失败带着点名具体回归 具体验收测试的 delta brief 重新派发defer⇢ 证据模糊如绝对计数下降但 compare 标记结构变化把证据呈现给用户并请示。晋升后可提议须用户明确同意才执行/eval-llm抽查、用python -m explainshell.manager extract --mode llm:model --overwrite -j 10 --reason one-line重抽取受影响页面以及make upload-live-db上传线上数据库——这些都是有成本或生产影响的下游动作模板与 SKILL 均禁止未经确认擅自执行。七、红线清单What NOT to do与失败哲学模板最后给出了四条不可逾越的红线也是修复质量的最低保障不要为斜体重引*若近期本地提交已把斜体切换为_或反之先查{{LOCAL_HISTORY}}再动手不要移除zwnj;插入机制它是粗体↔斜体接壤的承重墙第 3.1 节的源码证据已说明缘由不要触碰{{WORKTREE}}之外的任何文件mandoc 工作树与 explainshell 主仓库隔离候选二进制也不得自行提升到tools/晋升是编排者的职责不要 push子代理在自己的工作树提交是否推送上游由用户决定。最后的失败哲学同样值得借鉴如果任何东西阻塞了修复例如它会回归某个不变量停下并报告——不要交付部分修复。配合{{REPORTING_FIELDS}}回传提交哈希、冒烟测试输出、审计计数、回归清点与判断说明编排者可以做到全程可核实而非靠猜。八、结语把模板落地到自己的仓库subagent-brief.md的价值在于它把修复一个 C 渲染器缺陷这种高不确定性任务压缩成参数化、可判定、可回传的子代理任务以printf | mandoc -T markdown做最小复现、以真实 manpage 佐证、以验收测试 不变量双重约束、以make regress与render_eval.py audit做定量门禁、以 Conventional Commits 与结构化回传收尾。若你的项目也 vendor 了 mandoc 并依赖-T markdown输出这套模板可以直接复用把{{WORKTREE}}换成你的源码树路径、{{REPRO_CLI}}换成你的缺陷复现、{{AUDIT_RULE}}换成 render_eval.py 中与你缺陷对应的规则 ID或自行扩展AUDIT_RULES表即可获得同样的诊断 → 修复 → 验证 → 晋升闭环。整个流程的每一环都能在本仓库找到可执行依据编排逻辑在 mandoc-fix SKILL验证工具在 render_eval.py 与 README下游文本处理在 explainshell/extraction/llm/text.py。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐Explainshell 渲染评估指南用 eval-render 系统化评测 mandoc Markdown 渲染输出Explainshell 渲染评估指南用 eval render 系统化评测 mandoc Markdown 渲染输出 本指南完整讲解 Explainshel后端开发工具Voyager Markdown 渲染修复机制详解自动修复 Gemini 断裂的加粗标记Voyager Markdown 渲染修复机制详解自动修复 Gemini 断裂的加粗标记 Gemini™ 网页界面在渲染对话内容时常会在文本中插入引用来源、AI 应用前端插件系统提示工程Salt napalm_network 模块修复实战内联模板渲染崩溃与 commit_at 定时提交调度Salt napalm_network 模块修复实战内联模板渲染崩溃与 commit_at 定时提交调度 本篇文章围绕 Salt 仓库 changelog/6运维配置管理后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考