尧图网站建设 
后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载导读本文围绕 explainshell 仓库中的设计文档 plans/positional-prefix-matching.md 展开深入剖析 explainshell 为解决位置参数positional operand错误归属问题而设计并落地的sigil 前缀匹配方案。你将了解到为什么dig ns foo.bar 8.8.8.8中的8.8.8.8会被错误解释为type而不是server、prefix字段如何从 LLM 抽取管线一路贯通到匹配器、sigil 白名单为何只包含//:以及该方案如何在不改动存量数据行为的前提下做到降级安全。读完后你将掌握这一方案的完整链路数据模型 → 抽取 prompt → 字段净化 → 匹配算法 → 测试与数据迁移。一、问题背景位置参数的纯顺序匹配缺陷1.1 现状Matcher.visitword的顺序指派explainshell 的匹配器matcher.py对命令中的每个单词进行匹配。当单词不是 flag 时visitwordmatcher.py:670-706会遍历ParsedManpage.positionals——这是一个OrderedDict键为位置参数名、值为合并后的帮助文本models.py——并借助单一计数器matched_group.positional_indexmatcher.py:28按顺序消费第一个未被 flag 认领的单词 → 第一个位置参数第二个单词 → 第二个位置参数依此类推。唯一的例外是精确名称匹配word in dmatcher.py:686用于start/stop这类关键字风格的位置参数。1.2 缺陷复现dig 的三参数错位对于 dig抽取出的位置参数顺序是server, name, type因此dig ns foo.bar 8.8.8.8会产生灾难性的错误指派单词被指派的位置参数后果nsserver命中 693 字符的最长文本——最糟糕的落点foo.barname侥幸正确8.8.8.8type语义完全错误而正确的映射是毫无歧义的dig 的 synopsis 是dig [server] [name] [type] ...这个 sigil符号前缀明确附着在server这一个操作数上。问题根源在于匹配器对 token 的形状一无所知无法利用前缀这一信息。二、核心设计取舍sigil 知识放在哪一层设计文档给出了三个候选方案LLM 产出的 schema 字段最终采纳。抽取 prompt 已经要求模型识别位置参数而 sigil 就明晃晃地写在 synopsis如[server]里。只需在 option 的 JSON schema 与Option模型中新增一个可选prefix字段。这是通用方案——任何 synopsis 中把字面 sigil 附着在操作数上的手册页都能承载该信息没有前缀的页面行为与今天完全一致。匹配器侧启发式已否决。在 matcher.py 中硬编码 名为 server 的位置参数只能修好 dig 一个案例把命令专属知识放进了错误的抽象层且会无限膨胀。UI 截断正交方案。折叠长帮助文本是独立的产品问题不能修复错误指派。次要设计决策带前缀的位置参数完全退出有序消费池——它只能被携带对应前缀的 token 认领。这正是修复整条命令的关键当server退出有序池后ns和foo.bar将消费name, type而非server, name。副作用是dig 8.8.8.8无会把8.8.8.8映射到name——这恰好符合 dig 的真实语义裸地址是查询名而非服务器。三、模型层改造Option.prefix与双位置参数池3.1Option新增prefix字段models.py 中的OptionPydantic 模型新增prefix: str | None None其语义是token 必须以此字面字符串开头该位置参数才能认领它且仅在positional被设置时才有意义与positional对 flags 的规则对称。两个关键实现细节不进Option.metameta是抽取侧附带数据如{lines: [start, end]}见 response.pyprefix是匹配行为应当作为一等字段存在。序列化零成本to_store()使用model_dump()models.py旧数据库行缺少该键时会反序列化为None默认值——老数据天然兼容。3.2 白名单常量OPTION_PREFIX_SIGILSmodels.py 顶部定义了 sigil 白名单models.py#L39-L44OPTION_PREFIX_SIGILS frozenset({, , :})3.3 双位置参数池ParsedManpage.positionals保持现有形状name → text但排除带前缀的选项新增属性prefixed_positionalsmodels.py返回有序的 name →(prefix, text)映射。由于positionals只被 matcher.py 的两处调用消费形状变化的影响被严格限制。四、匹配器改造双池指派算法matcher.py 中的位置参数分支现在按以下顺序处理第 1 步加宽分支门槛。整个分支原本以if self.man_page.positionals:matcher.py:672为门槛由于带前缀条目已离开该 dict门槛必须变成存在任何位置参数positionals or prefixed——否则一个只有前缀位置参数的页面如cmd [server]永远进不了前缀池cmd 8.8.8.8会被判为 unknown。第 2 步前缀池优先。若单词以任何已声明的前缀开头则认领该位置参数并返回。多个带前缀的 token 可以认领同一个位置参数复用镜像既有的变长参数行为若多个位置参数声明了相同前缀文档顺序靠前者获胜matcher.py:686-706。第 3 步有序池 一个新增守卫。先精确名称匹配再按索引顺序消费并复用最后一个键——即今日逻辑matcher.py:715-728在无前缀 dict 上的运行。positional_index计数器继续存活由于前缀池从不与索引交互无需 consumed-set。新守卫当有序池为空所有位置参数都带前缀时无前缀 token 必须落入 unknown——因为既有的变长回退keys[-1]在空列表上会抛IndexError而该路径位于 web 服务链路上。携带无位置参数声明前缀的 token如对withmultipos输入x会像今天一样落入有序池——对无前缀页面零行为变化。与 sigil 风格 flag 的优先级option/flag 匹配先于位置参数分支执行因此把风格 flag 存为long选项的页面dig 的trace家族不受进入白名单影响——已验证dig trace foo.bar今天就把trace匹配为 flag前缀池只会看到 flag 认领失败的 token。有意为之的行为差异今天dig server这类字面量会通过word in dmatcher.py:715精确名称匹配到server新方案下该条目退出有序 dict字面量落入有序消费name。这 arguably 更正确——dig 将裸词视为查询名——但确实是对既有数据形状的刻意变更。五、抽取管线改造从 prompt 到字段净化5.1 Prompt新增prefix字段指令prompt.py 的系统提示现在要求prefix: null, // literal sigil character the SYNOPSIS attaches to this // positional operand (e.g. in digs [server]). // Only valid together with positional. Do NOT use for // optional sub-components like [user]hostname or for // placeholder styling like FILE. Omit if none.承载约束load-bearing由于带前缀的位置参数完全退出有序消费流行页面上一个误报的prefix会破坏其最常见操作数的裸形式。两个具体陷阱ssh/scp 陷阱synopsis 使用[user]hostname——这是可选的子组件不是操作数 sigil。若模型在此处产出prefix: 普通的ssh example.com将不再匹配hostname。占位符陷阱FILE这类占位符风格的名称不得被规范化成前缀。因此prefix被限制为来自语料库实证白名单的单个标点字符在两个净化站点强制执行任何其他值被丢弃并打 debug 日志。5.2 白名单的实证来源全语料 SYNOPSIS 扫描白名单并非凭空猜测而是扫描了数据库中全部61,322个原始页面的 SYNOPSIS 章节匹配独立的方括号 sigil 操作数[前有空白因此粘在另一 token 上的后缀语法不计入。结果sigil页面数典型用法197dig/delv/adig 的serverGNU as/gcc 的FILEargfilesjavadoc/jar 的filesbdep 的cfg-namecargo-install 的version117date FORMATvi 风格编辑器mg、mcedit、vile、geany的linepr pagexset dpms:19X display 编号Xorg :display、tightvncserver :display、broadwayd :DISPLAY有证据地否决和%几乎只以粘附后缀形式出现--flag[VALUE]、samba 的user[%password]——正是该约束要拦截的误报形态TeX 的format与#是 shell 元字符永远不会以裸词形式到达匹配器、[、{、(、引号是占位符/或选项语法而非 sigil。种子列表一次性就位是因为页面会在未来每次重新抽取时机会性地获得前缀。5.3 响应净化三层防护response.py 的净化链路llm_option_to_store_optionresponse.py:206读取prefix并传给Option。sanitize_option_fieldsresponse.py:170-203当positional为空时清空prefix与既有 positional-vs-flags 规则并行并丢弃白名单之外的取值。normalize_option_fieldsresponse.py:131-167若模型把 sigil 直接嵌入位置参数名positional: server且无 prefix 字段则将其剥离为prefix——这是模型最可能犯的错误。该规则仅作用于白名单 sigil 字符因此FILE风格占位符不受影响。5.4 后处理对齐postprocess.py 的sanitize_option采用相同的prefix 需 positional 白名单规则所有重建Option的站点postprocess.py:60、76、182 对应位置都必须携带prefix——实现上可切换为opt.model_copy(update{...})postprocess.py:77使未来新增字段零成本。六、diff 工具与 Web 层的配套改动6.1 diff 工具diff.py 将prefix加入_OPT_FIELDS与_FALSY_EQUIVALENT后者使None与缺失在对比旧行时等价。这样diff db就能在数据刷新期间暴露 prefix 变更。6.2 Web 层正常渲染无需改动——匹配发生在服务端 matcherviews.py 只转发positional与prefix用于展示。唯一例外DEBUG 面板镜像 option 字段views.py:495-507 与 matcher.py 的_option_debugmatcher.py:52-62需在调试 dict 中加入prefix——否则在调试某 token 为何匹配时新的匹配提示恰好不可见。七、必须坚守的不变量设计文档明确了五条不可破坏的契约引用手册页契约帮助文本永远是手册页定义块的逐字引用本方案只改指派绝不改文本内容。降级安全数据无prefix的页面即当前全部语料必须与今天逐字节一致——前缀池必须是严格的超集特性。净化对称性response.py 与 postprocess.py 执行相同的字段规则既有 positional-vs-flags 约定prefix 遵循之。存储生命周期工具用普通Store生产 Web 用CachingStore本方案不触碰存储生命周期。旧行兼容options JSON 经 Pydantic 读回缺失prefix键不得使校验失败默认None处理——需确认无extraforbid类配置干扰。八、测试与验证矩阵8.1 单元测试helpers.py 新增两个 fixturewithprefixposdig 风格server前缀 name/type有序与onlyprefixpos唯一位置参数即带前缀。测试覆盖test_matcher.py测试输入断言要点乱序前缀认领withprefixpos ns foo.bar 8.8.8.88.8.8.8→ server 文本ns→ namefoo.bar→ type首位置前缀withprefixpos 8.8.8.8 foo.bar前缀 token 不消耗有序池前缀复用withprefixpos a b相邻相同文本合并为一个 MatchResult未声明前缀回落withmultipos xx落入有序消费SOURCE字面名行为变更withprefixpos serverserver字面量映射到 name刻意变更纯前缀页面onlyprefixpos :1/onlyprefixpos foo前缀 token 匹配非前缀 token 判 unknown 而非空池抛错既有的位置参数测试test_matcher.py:77-109必须原样通过。8.2 端到端测试e2e.spec.js 固化了 issue-361 命令访问/explain?cmddignsfoo.bar%408.8.8.8deterministic后断言8.8.8.8的helpref指向包含 server 的帮助文本且ns不共享该帮助框并生成截图快照explain-dig-prefixed-positional.png。8.3 评估与文档LLM 评估prompt 变更触及抽取器落地前需跑/eval-llm按 CLAUDE.md 的 stash 工作流做基线对比。关注无 sigil 页面的扰动新 schema 字段对它们应是 no-op零 option 差异、无 positional 变动并专门检查 ssh/scp 形态页面[user]hostname的 prefix 误报。文档同步AGENTS.md 的 Data Model 章节枚举了Option字段与匹配器描述需为prefix同步更新。手工验证python -m explainshell.manager diff db --mode llm:model manpages/arch/latest/1/dig.1.gz应显示server获得prefix: 随后本地匹配dig ns foo.bar 8.8.8.8应映射8.8.8.8→ server、ns→ name、foo.bar→ type。九、数据迁移与部署节奏两张 dig 行需要新字段ubuntu/26.04/1/dig.1.gz与arch/latest/1/dig.1.gz。在 prompt 变更后以--overwrite重新抽取两者优于手工编辑 JSON——能锻炼真实管线。其余语料保持不变页面在后续重新抽取中机会性获得前缀本方案不包含批量重新抽取。生产部署数据库烘焙进 Docker 镜像修复到达 explainshell.com 只能通过make upload-live-db 推送master部署管线。代码变更必须与数据变更同时或更早部署——旧代码读到prefix键只在 Pydantic 拒绝未知字段时才成问题而默认并不会拒绝故顺序灵活但仍以先发代码为宜。十、明确不在范围内的事项nsvsfoo.bar的语义指派两者仍按顺序映射name,type——语义上ns才是 type。修复它需要值集知识schema 的has_argument允许值列表扩展至位置参数并按成员关系匹配。这是刻意的后续项不属本方案。UI 级长帮助文本的截断/展开文本过长抱怨——正交的产品决策。十一、已决开放问题双人评审codex claude2026-06-12与用户确认已解决全部问题无遗留字段名prefix——两位评审均无异议它紧邻positional后者提供上下文。Prompt 范围仅限 synopsis——评审的误报分析[user]hostname也在 synopsis 中真正的守卫是 sigil 白名单强化了synopsis-only 使指令简单保守的结论。e2e 覆盖是——向tests/e2e/e2e.db添加 dig 页并快照 issue-361 命令。回填广度仅 dig其他页面在后续重新抽取时机会性获得前缀。白名单内容预先播种更广的 sigil 词汇表但以语料而非猜测为依据。全部 61,322 个 SYNOPSIS 章节扫描得出、、:为真实独立 sigil并淘汰了最初提议的%与粘附后缀伪影证据并入抽取章节。结语一条从数据到匹配的完整闭环sigil 前缀匹配方案的价值在于它是一条端到端的修复链路LLM 从 synopsis 中读出[server]并产出prefix字段 → response.py 与 postprocess.py 双重净化拦截误报 →Option.prefix把匹配行为下沉为一等数据 →prefixed_positionals将带前缀操作数移出有序池 → 匹配器双池指派让8.8.8.8准确落到 server。配合语料实证的//:白名单与逐层测试单元 → e2e → LLM 评估它既修复了 issue-361 的具体缺陷又为未来任何synopsis 带字面 sigil 的操作数提供了通用、可增量采纳的机制——而这一切都以存量页面行为逐字节不变为底线。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐StatsD指标前缀与后缀设置组织复杂监控数据StatsD指标前缀与后缀设置组织复杂监控数据 你是否曾面对监控系统中杂乱无章的指标数据感到无从下手当服务规模扩大到数十个实例、上百个接口时原始的 api可观测性指标监控countUp.js数字格式化全攻略千分位、小数与前缀后缀countUp.js数字格式化全攻略千分位、小数与前缀后缀 你是否曾为网页中枯燥的静态数字感到困扰想让数据展示更具吸引力却苦于复杂的JavaScript动画前端UI组件Elasticsearch部分匹配技术前缀查询、通配符、短语前缀的完整教程Elasticsearch部分匹配技术前缀查询、通配符、短语前缀的完整教程 想要实现智能搜索和输入即搜索功能吗Elasticsearch的部分匹配技术正是你教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 explainshell 位置参数前缀匹配（sigil 前缀操作数）设计解析
后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载导读本文围绕 explainshell 仓库中的设计文档 plans/positional-prefix-matching.md 展开深入剖析 explainshell 为解决位置参数positional operand错误归属问题而设计并落地的sigil 前缀匹配方案。你将了解到为什么dig ns foo.bar 8.8.8.8中的8.8.8.8会被错误解释为type而不是server、prefix字段如何从 LLM 抽取管线一路贯通到匹配器、sigil 白名单为何只包含//:以及该方案如何在不改动存量数据行为的前提下做到降级安全。读完后你将掌握这一方案的完整链路数据模型 → 抽取 prompt → 字段净化 → 匹配算法 → 测试与数据迁移。一、问题背景位置参数的纯顺序匹配缺陷1.1 现状Matcher.visitword的顺序指派explainshell 的匹配器matcher.py对命令中的每个单词进行匹配。当单词不是 flag 时visitwordmatcher.py:670-706会遍历ParsedManpage.positionals——这是一个OrderedDict键为位置参数名、值为合并后的帮助文本models.py——并借助单一计数器matched_group.positional_indexmatcher.py:28按顺序消费第一个未被 flag 认领的单词 → 第一个位置参数第二个单词 → 第二个位置参数依此类推。唯一的例外是精确名称匹配word in dmatcher.py:686用于start/stop这类关键字风格的位置参数。1.2 缺陷复现dig 的三参数错位对于 dig抽取出的位置参数顺序是server, name, type因此dig ns foo.bar 8.8.8.8会产生灾难性的错误指派单词被指派的位置参数后果nsserver命中 693 字符的最长文本——最糟糕的落点foo.barname侥幸正确8.8.8.8type语义完全错误而正确的映射是毫无歧义的dig 的 synopsis 是dig [server] [name] [type] ...这个 sigil符号前缀明确附着在server这一个操作数上。问题根源在于匹配器对 token 的形状一无所知无法利用前缀这一信息。二、核心设计取舍sigil 知识放在哪一层设计文档给出了三个候选方案LLM 产出的 schema 字段最终采纳。抽取 prompt 已经要求模型识别位置参数而 sigil 就明晃晃地写在 synopsis如[server]里。只需在 option 的 JSON schema 与Option模型中新增一个可选prefix字段。这是通用方案——任何 synopsis 中把字面 sigil 附着在操作数上的手册页都能承载该信息没有前缀的页面行为与今天完全一致。匹配器侧启发式已否决。在 matcher.py 中硬编码 名为 server 的位置参数只能修好 dig 一个案例把命令专属知识放进了错误的抽象层且会无限膨胀。UI 截断正交方案。折叠长帮助文本是独立的产品问题不能修复错误指派。次要设计决策带前缀的位置参数完全退出有序消费池——它只能被携带对应前缀的 token 认领。这正是修复整条命令的关键当server退出有序池后ns和foo.bar将消费name, type而非server, name。副作用是dig 8.8.8.8无会把8.8.8.8映射到name——这恰好符合 dig 的真实语义裸地址是查询名而非服务器。三、模型层改造Option.prefix与双位置参数池3.1Option新增prefix字段models.py 中的OptionPydantic 模型新增prefix: str | None None其语义是token 必须以此字面字符串开头该位置参数才能认领它且仅在positional被设置时才有意义与positional对 flags 的规则对称。两个关键实现细节不进Option.metameta是抽取侧附带数据如{lines: [start, end]}见 response.pyprefix是匹配行为应当作为一等字段存在。序列化零成本to_store()使用model_dump()models.py旧数据库行缺少该键时会反序列化为None默认值——老数据天然兼容。3.2 白名单常量OPTION_PREFIX_SIGILSmodels.py 顶部定义了 sigil 白名单models.py#L39-L44OPTION_PREFIX_SIGILS frozenset({, , :})3.3 双位置参数池ParsedManpage.positionals保持现有形状name → text但排除带前缀的选项新增属性prefixed_positionalsmodels.py返回有序的 name →(prefix, text)映射。由于positionals只被 matcher.py 的两处调用消费形状变化的影响被严格限制。四、匹配器改造双池指派算法matcher.py 中的位置参数分支现在按以下顺序处理第 1 步加宽分支门槛。整个分支原本以if self.man_page.positionals:matcher.py:672为门槛由于带前缀条目已离开该 dict门槛必须变成存在任何位置参数positionals or prefixed——否则一个只有前缀位置参数的页面如cmd [server]永远进不了前缀池cmd 8.8.8.8会被判为 unknown。第 2 步前缀池优先。若单词以任何已声明的前缀开头则认领该位置参数并返回。多个带前缀的 token 可以认领同一个位置参数复用镜像既有的变长参数行为若多个位置参数声明了相同前缀文档顺序靠前者获胜matcher.py:686-706。第 3 步有序池 一个新增守卫。先精确名称匹配再按索引顺序消费并复用最后一个键——即今日逻辑matcher.py:715-728在无前缀 dict 上的运行。positional_index计数器继续存活由于前缀池从不与索引交互无需 consumed-set。新守卫当有序池为空所有位置参数都带前缀时无前缀 token 必须落入 unknown——因为既有的变长回退keys[-1]在空列表上会抛IndexError而该路径位于 web 服务链路上。携带无位置参数声明前缀的 token如对withmultipos输入x会像今天一样落入有序池——对无前缀页面零行为变化。与 sigil 风格 flag 的优先级option/flag 匹配先于位置参数分支执行因此把风格 flag 存为long选项的页面dig 的trace家族不受进入白名单影响——已验证dig trace foo.bar今天就把trace匹配为 flag前缀池只会看到 flag 认领失败的 token。有意为之的行为差异今天dig server这类字面量会通过word in dmatcher.py:715精确名称匹配到server新方案下该条目退出有序 dict字面量落入有序消费name。这 arguably 更正确——dig 将裸词视为查询名——但确实是对既有数据形状的刻意变更。五、抽取管线改造从 prompt 到字段净化5.1 Prompt新增prefix字段指令prompt.py 的系统提示现在要求prefix: null, // literal sigil character the SYNOPSIS attaches to this // positional operand (e.g. in digs [server]). // Only valid together with positional. Do NOT use for // optional sub-components like [user]hostname or for // placeholder styling like FILE. Omit if none.承载约束load-bearing由于带前缀的位置参数完全退出有序消费流行页面上一个误报的prefix会破坏其最常见操作数的裸形式。两个具体陷阱ssh/scp 陷阱synopsis 使用[user]hostname——这是可选的子组件不是操作数 sigil。若模型在此处产出prefix: 普通的ssh example.com将不再匹配hostname。占位符陷阱FILE这类占位符风格的名称不得被规范化成前缀。因此prefix被限制为来自语料库实证白名单的单个标点字符在两个净化站点强制执行任何其他值被丢弃并打 debug 日志。5.2 白名单的实证来源全语料 SYNOPSIS 扫描白名单并非凭空猜测而是扫描了数据库中全部61,322个原始页面的 SYNOPSIS 章节匹配独立的方括号 sigil 操作数[前有空白因此粘在另一 token 上的后缀语法不计入。结果sigil页面数典型用法197dig/delv/adig 的serverGNU as/gcc 的FILEargfilesjavadoc/jar 的filesbdep 的cfg-namecargo-install 的version117date FORMATvi 风格编辑器mg、mcedit、vile、geany的linepr pagexset dpms:19X display 编号Xorg :display、tightvncserver :display、broadwayd :DISPLAY有证据地否决和%几乎只以粘附后缀形式出现--flag[VALUE]、samba 的user[%password]——正是该约束要拦截的误报形态TeX 的format与#是 shell 元字符永远不会以裸词形式到达匹配器、[、{、(、引号是占位符/或选项语法而非 sigil。种子列表一次性就位是因为页面会在未来每次重新抽取时机会性地获得前缀。5.3 响应净化三层防护response.py 的净化链路llm_option_to_store_optionresponse.py:206读取prefix并传给Option。sanitize_option_fieldsresponse.py:170-203当positional为空时清空prefix与既有 positional-vs-flags 规则并行并丢弃白名单之外的取值。normalize_option_fieldsresponse.py:131-167若模型把 sigil 直接嵌入位置参数名positional: server且无 prefix 字段则将其剥离为prefix——这是模型最可能犯的错误。该规则仅作用于白名单 sigil 字符因此FILE风格占位符不受影响。5.4 后处理对齐postprocess.py 的sanitize_option采用相同的prefix 需 positional 白名单规则所有重建Option的站点postprocess.py:60、76、182 对应位置都必须携带prefix——实现上可切换为opt.model_copy(update{...})postprocess.py:77使未来新增字段零成本。六、diff 工具与 Web 层的配套改动6.1 diff 工具diff.py 将prefix加入_OPT_FIELDS与_FALSY_EQUIVALENT后者使None与缺失在对比旧行时等价。这样diff db就能在数据刷新期间暴露 prefix 变更。6.2 Web 层正常渲染无需改动——匹配发生在服务端 matcherviews.py 只转发positional与prefix用于展示。唯一例外DEBUG 面板镜像 option 字段views.py:495-507 与 matcher.py 的_option_debugmatcher.py:52-62需在调试 dict 中加入prefix——否则在调试某 token 为何匹配时新的匹配提示恰好不可见。七、必须坚守的不变量设计文档明确了五条不可破坏的契约引用手册页契约帮助文本永远是手册页定义块的逐字引用本方案只改指派绝不改文本内容。降级安全数据无prefix的页面即当前全部语料必须与今天逐字节一致——前缀池必须是严格的超集特性。净化对称性response.py 与 postprocess.py 执行相同的字段规则既有 positional-vs-flags 约定prefix 遵循之。存储生命周期工具用普通Store生产 Web 用CachingStore本方案不触碰存储生命周期。旧行兼容options JSON 经 Pydantic 读回缺失prefix键不得使校验失败默认None处理——需确认无extraforbid类配置干扰。八、测试与验证矩阵8.1 单元测试helpers.py 新增两个 fixturewithprefixposdig 风格server前缀 name/type有序与onlyprefixpos唯一位置参数即带前缀。测试覆盖test_matcher.py测试输入断言要点乱序前缀认领withprefixpos ns foo.bar 8.8.8.88.8.8.8→ server 文本ns→ namefoo.bar→ type首位置前缀withprefixpos 8.8.8.8 foo.bar前缀 token 不消耗有序池前缀复用withprefixpos a b相邻相同文本合并为一个 MatchResult未声明前缀回落withmultipos xx落入有序消费SOURCE字面名行为变更withprefixpos serverserver字面量映射到 name刻意变更纯前缀页面onlyprefixpos :1/onlyprefixpos foo前缀 token 匹配非前缀 token 判 unknown 而非空池抛错既有的位置参数测试test_matcher.py:77-109必须原样通过。8.2 端到端测试e2e.spec.js 固化了 issue-361 命令访问/explain?cmddignsfoo.bar%408.8.8.8deterministic后断言8.8.8.8的helpref指向包含 server 的帮助文本且ns不共享该帮助框并生成截图快照explain-dig-prefixed-positional.png。8.3 评估与文档LLM 评估prompt 变更触及抽取器落地前需跑/eval-llm按 CLAUDE.md 的 stash 工作流做基线对比。关注无 sigil 页面的扰动新 schema 字段对它们应是 no-op零 option 差异、无 positional 变动并专门检查 ssh/scp 形态页面[user]hostname的 prefix 误报。文档同步AGENTS.md 的 Data Model 章节枚举了Option字段与匹配器描述需为prefix同步更新。手工验证python -m explainshell.manager diff db --mode llm:model manpages/arch/latest/1/dig.1.gz应显示server获得prefix: 随后本地匹配dig ns foo.bar 8.8.8.8应映射8.8.8.8→ server、ns→ name、foo.bar→ type。九、数据迁移与部署节奏两张 dig 行需要新字段ubuntu/26.04/1/dig.1.gz与arch/latest/1/dig.1.gz。在 prompt 变更后以--overwrite重新抽取两者优于手工编辑 JSON——能锻炼真实管线。其余语料保持不变页面在后续重新抽取中机会性获得前缀本方案不包含批量重新抽取。生产部署数据库烘焙进 Docker 镜像修复到达 explainshell.com 只能通过make upload-live-db 推送master部署管线。代码变更必须与数据变更同时或更早部署——旧代码读到prefix键只在 Pydantic 拒绝未知字段时才成问题而默认并不会拒绝故顺序灵活但仍以先发代码为宜。十、明确不在范围内的事项nsvsfoo.bar的语义指派两者仍按顺序映射name,type——语义上ns才是 type。修复它需要值集知识schema 的has_argument允许值列表扩展至位置参数并按成员关系匹配。这是刻意的后续项不属本方案。UI 级长帮助文本的截断/展开文本过长抱怨——正交的产品决策。十一、已决开放问题双人评审codex claude2026-06-12与用户确认已解决全部问题无遗留字段名prefix——两位评审均无异议它紧邻positional后者提供上下文。Prompt 范围仅限 synopsis——评审的误报分析[user]hostname也在 synopsis 中真正的守卫是 sigil 白名单强化了synopsis-only 使指令简单保守的结论。e2e 覆盖是——向tests/e2e/e2e.db添加 dig 页并快照 issue-361 命令。回填广度仅 dig其他页面在后续重新抽取时机会性获得前缀。白名单内容预先播种更广的 sigil 词汇表但以语料而非猜测为依据。全部 61,322 个 SYNOPSIS 章节扫描得出、、:为真实独立 sigil并淘汰了最初提议的%与粘附后缀伪影证据并入抽取章节。结语一条从数据到匹配的完整闭环sigil 前缀匹配方案的价值在于它是一条端到端的修复链路LLM 从 synopsis 中读出[server]并产出prefix字段 → response.py 与 postprocess.py 双重净化拦截误报 →Option.prefix把匹配行为下沉为一等数据 →prefixed_positionals将带前缀操作数移出有序池 → 匹配器双池指派让8.8.8.8准确落到 server。配合语料实证的//:白名单与逐层测试单元 → e2e → LLM 评估它既修复了 issue-361 的具体缺陷又为未来任何synopsis 带字面 sigil 的操作数提供了通用、可增量采纳的机制——而这一切都以存量页面行为逐字节不变为底线。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐StatsD指标前缀与后缀设置组织复杂监控数据StatsD指标前缀与后缀设置组织复杂监控数据 你是否曾面对监控系统中杂乱无章的指标数据感到无从下手当服务规模扩大到数十个实例、上百个接口时原始的 api可观测性指标监控countUp.js数字格式化全攻略千分位、小数与前缀后缀countUp.js数字格式化全攻略千分位、小数与前缀后缀 你是否曾为网页中枯燥的静态数字感到困扰想让数据展示更具吸引力却苦于复杂的JavaScript动画前端UI组件Elasticsearch部分匹配技术前缀查询、通配符、短语前缀的完整教程Elasticsearch部分匹配技术前缀查询、通配符、短语前缀的完整教程 想要实现智能搜索和输入即搜索功能吗Elasticsearch的部分匹配技术正是你教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考