Skill_Seekers Man 页面转 Skill 管线中的 Other 回退分类机制解析【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers导读本篇技术指南以 Skill_Seekers 仓库中的 golden 输出文件 other_02.md 为切入点深入讲解man命令解析器Man Page Scraper将 Unix/Linux 手册页转换为 Claude AI Skill 时的分类categorization机制。你将理解为什么 curl 这类不匹配任何关键字类别的手册页会落入名为 Other 的兜底分类、编号引用文件名如other_02.md如何产生、参考文件与 SKILL.md 之间的内容组织关系以及该机制如何通过 golden 测试保证输出字节级一致。一、other_02.md 在 Skill 产物树中的位置other_02.md不是一篇独立文档而是 Skill_Seekers 的 man 页面 → Skill 转换管线在关键字分类模式下生成的一类分类参考文件reference file。它以 golden 测试快照的形式存储在仓库中对应的完整产物树如下tests/golden/phase2/man_kw/ ├── SKILL.md # 生成的技能主文件含统计信息与导航 └── references/ ├── index.md # 分类索引与全部手册页清单 ├── version_control_01.md # 关键字分类版本控制类 └── other_02.md # 关键字未命中时的兜底分类Other这份 golden 树由 test_phase2_golden_man.py 在Phase 2 移植时捕获用于证明重构后的ManPageToSkillConverter输出与重构前逐字节一致。换句话说other_02.md同时承担两个角色运行期角色它是生成 Skill 中references/目录下其他类手册页的参考文档测试期角色它是断言转换器输出稳定性的基准快照。该 golden 用例的构建配置见测试第 120128 行man_names[git-log, git-diff, curl]显式分类为{version_control: [commit, diff]}。三个手册页中git-log与git-diff的标题/描述命中关键字commit/diff归入 Version Control而curl不命中任何关键字于是落入 Other 兜底桶——这正是 other_02.md 存在的根因。二、other_02.md 的文件结构逐段解析原文件全文仅 23 行但每一行都对应 man_scraper.py 中_generate_reference_file()的固定生成逻辑。逐段拆解如下2.1 一级标题分类名# Other对应源码第 964 行f.write(f# {cat_data[title]}\n\n)。这里title是分类创建时写死的Other见第 889 行而非从分类键推导其他类别如version_control会经cat_key.replace(_, ).title()变成 Version Control。2.2 手册页二级标题名字 小节号## curl对应第 971 行f.write(f---\n\n## {man_name}{section_label}\n\n)。由于测试数据中 curl 的section为None见测试第 72 行注释no section label anywheresection_label为空字符串因此标题不带(1)之类的后缀对比同目录version_control_01.md中的## git-log(1)其 section 为 1。2.3 标题行被跳过的条件文件里没有出现**curl - ...**加粗标题行。对应第 974976 行title page.get(title, ) if title and title ! man_name: f.write(f**{title}**\n\n)测试数据第 73 行title: curl与name完全相等因此该分支被跳过——这是一个刻意设计的边界用例用于覆盖标题等于名字的生成分支。2.4 Description描述### Description Transfer a URL using one of the supported protocols.对应第 986992 行。curl 的描述很短未触发 3000 字符截断git-diff则故意构造了超过 3000 字符的描述测试第 23 行LONG_DESCRIPTION生成时会输出前 3000 字符并追加*... (truncated)*标记。2.5 Options选项### Options - -s, --silent -- Silent mode.对应第 9961006 行。选项以- \flag -- 描述的格式输出若描述超过 200 字符如--max-count的长描述会截断到 200 字符并追加...第 1004 行。这解释了 [version_control_01.md](https://link.gitcode.com/i/85b22610c3c8cd97291a9ae88f4ae919) 中--max-count描述以... 结尾的现象。2.6 Examples示例### Examples **Example 1:** Fetch a page bash curl https://example.com对应第 10101019 行。示例按序号编号若示例只有描述、没有命令command 为空则只输出描述而不输出代码块——这正是 version_control_01.md 中 Prose-only example with no command 用例覆盖的分支。 ### 2.7 缺失部分同样有意义 - **无 Synopsis**测试数据中 curl 的 synopsis 为空第 75 行对应第 980 行 if synopsis: 分支跳过 - **无 See Also**curl 的 see_also 为空列表第 80 行对应第 1022 行 if see_also: 分支跳过 - **无额外章节**curl 的 sections 为空字典第 77 行因此不输出 ENVIRONMENT、NOTES 等附加小节而 git-log 的 GIT_PAGER 环境变量章节就出现在 version_control_01.md 中。 --- ## 三、分类机制源码剖析关键字匹配与 Other 兜底 other_02.md 的产生核心在 categorize_content() 方法[man_scraper.py](https://link.gitcode.com/i/f35476d411b6ee6e6c43cd8bb633317b#L836-L929)。该方法支持三种分类路径理解它们就能解释 golden 目录中三种命名形态的差异 ### 3.1 路径一预分组数据不做匹配 当 self.categories 的值为 list 且首元素为 dict 时第 856861 行说明调用方已经完成分组直接按组输出。这一分支面向从外部 JSON 恢复数据的场景。 ### 3.2 路径二关键字打分匹配other_02.md 走的就是这条 当 self.categories 是 {类别: [关键字, ...]} 结构时第 863890 行算法为每个手册页计算与每个类别的关键字命中分数 python text page.get(description, ).lower() title page.get(title, ).lower() for cat_key, keywords in self.categories.items(): score sum(1 for kw in keywords if isinstance(kw, str) and (kw.lower() in text or kw.lower() in title))分数基于描述与标题中出现的关键字个数不区分大小写取分数最高的类别作为该页归属max(scores, keyscores.get)没有任何类别得分时即触发 Other 兜底if other not in categorized: categorized[other] {title: Other, pages: []} categorized[other][pages].append(page)curl 的描述 Transfer a URL using one of the supported protocols. 与标题 curl 中均不含commit/diff得分全为 0因此进入此分支。分类键other经_sanitize_filename()清洗后成为文件名前缀。3.3 路径三前缀自动分组无显式分类时未提供categories时第 897924 行按名字的-前缀分组如git-log→git但仅在分组确实减少类别数量时生效否则归入单个commands类单页场景则以页名作为类别。这就是man目录下git_01.md/curl_02.md命名的来源——注意此时curl的类别名是curl而非other可见 Other 是关键字分类模式独有的回退设计。3.4 编号文件名规则other_02.md中的_02由_generate_reference_file()决定第 958961 行当总类别数 1 时文件名为{cat_key}_{cat_num:02d}.mdcat_num是类别在字典中的 1 起始序号。在 index.md 的 Categories 一节中Other (1 man page(s)) 是第二个被写出的条目因此得到02。单类别场景则不编号如man_single目录下的curl.md。四、从分类到 Skill 的完整生成链路other_02.md只是产物树的一部分理解整条链路才能把握它的上下文。ManPageToSkillConverter继承自DocumentSkillBuilder其build_skill()编排流程为提取extract通过三种策略之一获取手册页数据——调用系统man name命令抓取 stdout、扫描目录中的.1~.8/.man文件、或从先前保存的中间 JSON 加载见 man_scraper.py 模块 docstring 与STANDARD_SECTIONS列表分类categorize调用上文categorize_content()产出{类别键: {title: ..., pages: [...]}}生成参考文件对每个类别调用_generate_reference_file()产出references/{键}_{序号}.md即other_02.md的诞生地生成索引_generate_index()产出references/index.md其中 Categories 一节引用各参考文件other_02.md被写作[Other](https://link.gitcode.com/i/a6ea401763ad2071a13696d7ed5aa41c) (1 man page(s))All Man Pages 一节按名字排序列出全部手册页生成 SKILL.md_generate_skill_md()产出技能主文件 SKILL.md包含使用时机、常用选项摘要、示例与 SEE ALSO 导航并在 Documentation Statistics 中汇总 3 个手册页、3 个选项、3 个示例与 3 个交叉引用。由此AI Agent 在加载该 Skill 时可通过 SKILL.md 快速定位到references/version_control_01.md与references/other_02.md获取细节——Other 类保证了任何未分类手册页都不会丢失只是被降级归入通用桶。五、golden 测试如何保障输出稳定test_phase2_golden_man.py 提供了验证other_02.md及整棵产物树的测试。其机制为固定 fixturePAGES列表手工构造了三个手册页第 3183 行刻意覆盖所有生成分支——带/无 section 标签、标题等于名字、缺失 synopsis、超长描述3000、超长选项描述200、纯文字示例、SEE ALSO 引用、空白额外章节被跳过等三组断言test_man_prefix_grouping_matches_golden前缀分组、test_man_keyword_categorization_matches_golden关键字分类 Other 兜底、test_man_single_page_matches_golden单页不编号分别对应man、man_kw、man_single三棵 golden 树比对方式assert_matches_golden(build_snapshot(converter), man_kw)将转换器实时输出快照与仓库中的 golden 树逐字节比对任何格式漂移都会导致测试失败。这套测试的价值在于分类逻辑、截断阈值3000/200/1500 字符、文件名编号等细节一旦被无意改动立刻会被捕获。你可以直接运行该测试验证当前实现python -m pytest tests/test_phase2_golden_man.py -v六、实战如何复现 other_02.md 的生成要亲手得到与 golden 树一致的输出只需构造等效配置并调用转换器。测试中的_converter辅助函数给出了最小配置模板测试第 100110 行from skill_seekers.cli.man_scraper import ManPageToSkillConverter config { name: golden_man_kw, description: Use when testing the man golden build, man_names: [git-log, git-diff, curl], categories: {version_control: [commit, diff]}, output_dir: skill, } converter ManPageToSkillConverter(config)命令行等价用法见 man_scraper.py 的 Usage 示例skill-seekers man --man-names git,curl --name unix-tools skill-seekers man --man-path /usr/share/man/man1 --name coreutils skill-seekers man --from-json unix-tools_extracted.json当--man-names列表中存在无法匹配--categories关键字的手册页时产物references/中就会出现other_*.md。这一兜底设计使转换管线对任意手册页集合都保持完整性与可导航性是 SKILL.md 中 Total Man Pages: 3 / Other: 1 man page(s) 统计成立的底层保证。结语other_02.md看似只是一份 23 行的简单参考文件实则是 Skill_Seekers man 页面转换管线中关键字分类 兜底回退 编号命名 截断保护四大设计交汇的产物。它同时作为 golden 快照锁定了整个分类与生成逻辑的行为契约。理解它的生成路径也就理解了 man_scraper.py 中categorize_content()、_generate_reference_file()、_generate_index()与_generate_skill_md()之间的协作关系以及 golden 测试对输出稳定性的守护方式。相关实现与验证代码可继续在 man_scraper.py 与 test_phase2_golden_man.py 中深入研读。【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Skill_Seekers Man 页面转 Skill 管线中的 “Other“ 回退分类机制解析
Skill_Seekers Man 页面转 Skill 管线中的 Other 回退分类机制解析【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers导读本篇技术指南以 Skill_Seekers 仓库中的 golden 输出文件 other_02.md 为切入点深入讲解man命令解析器Man Page Scraper将 Unix/Linux 手册页转换为 Claude AI Skill 时的分类categorization机制。你将理解为什么 curl 这类不匹配任何关键字类别的手册页会落入名为 Other 的兜底分类、编号引用文件名如other_02.md如何产生、参考文件与 SKILL.md 之间的内容组织关系以及该机制如何通过 golden 测试保证输出字节级一致。一、other_02.md 在 Skill 产物树中的位置other_02.md不是一篇独立文档而是 Skill_Seekers 的 man 页面 → Skill 转换管线在关键字分类模式下生成的一类分类参考文件reference file。它以 golden 测试快照的形式存储在仓库中对应的完整产物树如下tests/golden/phase2/man_kw/ ├── SKILL.md # 生成的技能主文件含统计信息与导航 └── references/ ├── index.md # 分类索引与全部手册页清单 ├── version_control_01.md # 关键字分类版本控制类 └── other_02.md # 关键字未命中时的兜底分类Other这份 golden 树由 test_phase2_golden_man.py 在Phase 2 移植时捕获用于证明重构后的ManPageToSkillConverter输出与重构前逐字节一致。换句话说other_02.md同时承担两个角色运行期角色它是生成 Skill 中references/目录下其他类手册页的参考文档测试期角色它是断言转换器输出稳定性的基准快照。该 golden 用例的构建配置见测试第 120128 行man_names[git-log, git-diff, curl]显式分类为{version_control: [commit, diff]}。三个手册页中git-log与git-diff的标题/描述命中关键字commit/diff归入 Version Control而curl不命中任何关键字于是落入 Other 兜底桶——这正是 other_02.md 存在的根因。二、other_02.md 的文件结构逐段解析原文件全文仅 23 行但每一行都对应 man_scraper.py 中_generate_reference_file()的固定生成逻辑。逐段拆解如下2.1 一级标题分类名# Other对应源码第 964 行f.write(f# {cat_data[title]}\n\n)。这里title是分类创建时写死的Other见第 889 行而非从分类键推导其他类别如version_control会经cat_key.replace(_, ).title()变成 Version Control。2.2 手册页二级标题名字 小节号## curl对应第 971 行f.write(f---\n\n## {man_name}{section_label}\n\n)。由于测试数据中 curl 的section为None见测试第 72 行注释no section label anywheresection_label为空字符串因此标题不带(1)之类的后缀对比同目录version_control_01.md中的## git-log(1)其 section 为 1。2.3 标题行被跳过的条件文件里没有出现**curl - ...**加粗标题行。对应第 974976 行title page.get(title, ) if title and title ! man_name: f.write(f**{title}**\n\n)测试数据第 73 行title: curl与name完全相等因此该分支被跳过——这是一个刻意设计的边界用例用于覆盖标题等于名字的生成分支。2.4 Description描述### Description Transfer a URL using one of the supported protocols.对应第 986992 行。curl 的描述很短未触发 3000 字符截断git-diff则故意构造了超过 3000 字符的描述测试第 23 行LONG_DESCRIPTION生成时会输出前 3000 字符并追加*... (truncated)*标记。2.5 Options选项### Options - -s, --silent -- Silent mode.对应第 9961006 行。选项以- \flag -- 描述的格式输出若描述超过 200 字符如--max-count的长描述会截断到 200 字符并追加...第 1004 行。这解释了 [version_control_01.md](https://link.gitcode.com/i/85b22610c3c8cd97291a9ae88f4ae919) 中--max-count描述以... 结尾的现象。2.6 Examples示例### Examples **Example 1:** Fetch a page bash curl https://example.com对应第 10101019 行。示例按序号编号若示例只有描述、没有命令command 为空则只输出描述而不输出代码块——这正是 version_control_01.md 中 Prose-only example with no command 用例覆盖的分支。 ### 2.7 缺失部分同样有意义 - **无 Synopsis**测试数据中 curl 的 synopsis 为空第 75 行对应第 980 行 if synopsis: 分支跳过 - **无 See Also**curl 的 see_also 为空列表第 80 行对应第 1022 行 if see_also: 分支跳过 - **无额外章节**curl 的 sections 为空字典第 77 行因此不输出 ENVIRONMENT、NOTES 等附加小节而 git-log 的 GIT_PAGER 环境变量章节就出现在 version_control_01.md 中。 --- ## 三、分类机制源码剖析关键字匹配与 Other 兜底 other_02.md 的产生核心在 categorize_content() 方法[man_scraper.py](https://link.gitcode.com/i/f35476d411b6ee6e6c43cd8bb633317b#L836-L929)。该方法支持三种分类路径理解它们就能解释 golden 目录中三种命名形态的差异 ### 3.1 路径一预分组数据不做匹配 当 self.categories 的值为 list 且首元素为 dict 时第 856861 行说明调用方已经完成分组直接按组输出。这一分支面向从外部 JSON 恢复数据的场景。 ### 3.2 路径二关键字打分匹配other_02.md 走的就是这条 当 self.categories 是 {类别: [关键字, ...]} 结构时第 863890 行算法为每个手册页计算与每个类别的关键字命中分数 python text page.get(description, ).lower() title page.get(title, ).lower() for cat_key, keywords in self.categories.items(): score sum(1 for kw in keywords if isinstance(kw, str) and (kw.lower() in text or kw.lower() in title))分数基于描述与标题中出现的关键字个数不区分大小写取分数最高的类别作为该页归属max(scores, keyscores.get)没有任何类别得分时即触发 Other 兜底if other not in categorized: categorized[other] {title: Other, pages: []} categorized[other][pages].append(page)curl 的描述 Transfer a URL using one of the supported protocols. 与标题 curl 中均不含commit/diff得分全为 0因此进入此分支。分类键other经_sanitize_filename()清洗后成为文件名前缀。3.3 路径三前缀自动分组无显式分类时未提供categories时第 897924 行按名字的-前缀分组如git-log→git但仅在分组确实减少类别数量时生效否则归入单个commands类单页场景则以页名作为类别。这就是man目录下git_01.md/curl_02.md命名的来源——注意此时curl的类别名是curl而非other可见 Other 是关键字分类模式独有的回退设计。3.4 编号文件名规则other_02.md中的_02由_generate_reference_file()决定第 958961 行当总类别数 1 时文件名为{cat_key}_{cat_num:02d}.mdcat_num是类别在字典中的 1 起始序号。在 index.md 的 Categories 一节中Other (1 man page(s)) 是第二个被写出的条目因此得到02。单类别场景则不编号如man_single目录下的curl.md。四、从分类到 Skill 的完整生成链路other_02.md只是产物树的一部分理解整条链路才能把握它的上下文。ManPageToSkillConverter继承自DocumentSkillBuilder其build_skill()编排流程为提取extract通过三种策略之一获取手册页数据——调用系统man name命令抓取 stdout、扫描目录中的.1~.8/.man文件、或从先前保存的中间 JSON 加载见 man_scraper.py 模块 docstring 与STANDARD_SECTIONS列表分类categorize调用上文categorize_content()产出{类别键: {title: ..., pages: [...]}}生成参考文件对每个类别调用_generate_reference_file()产出references/{键}_{序号}.md即other_02.md的诞生地生成索引_generate_index()产出references/index.md其中 Categories 一节引用各参考文件other_02.md被写作[Other](https://link.gitcode.com/i/a6ea401763ad2071a13696d7ed5aa41c) (1 man page(s))All Man Pages 一节按名字排序列出全部手册页生成 SKILL.md_generate_skill_md()产出技能主文件 SKILL.md包含使用时机、常用选项摘要、示例与 SEE ALSO 导航并在 Documentation Statistics 中汇总 3 个手册页、3 个选项、3 个示例与 3 个交叉引用。由此AI Agent 在加载该 Skill 时可通过 SKILL.md 快速定位到references/version_control_01.md与references/other_02.md获取细节——Other 类保证了任何未分类手册页都不会丢失只是被降级归入通用桶。五、golden 测试如何保障输出稳定test_phase2_golden_man.py 提供了验证other_02.md及整棵产物树的测试。其机制为固定 fixturePAGES列表手工构造了三个手册页第 3183 行刻意覆盖所有生成分支——带/无 section 标签、标题等于名字、缺失 synopsis、超长描述3000、超长选项描述200、纯文字示例、SEE ALSO 引用、空白额外章节被跳过等三组断言test_man_prefix_grouping_matches_golden前缀分组、test_man_keyword_categorization_matches_golden关键字分类 Other 兜底、test_man_single_page_matches_golden单页不编号分别对应man、man_kw、man_single三棵 golden 树比对方式assert_matches_golden(build_snapshot(converter), man_kw)将转换器实时输出快照与仓库中的 golden 树逐字节比对任何格式漂移都会导致测试失败。这套测试的价值在于分类逻辑、截断阈值3000/200/1500 字符、文件名编号等细节一旦被无意改动立刻会被捕获。你可以直接运行该测试验证当前实现python -m pytest tests/test_phase2_golden_man.py -v六、实战如何复现 other_02.md 的生成要亲手得到与 golden 树一致的输出只需构造等效配置并调用转换器。测试中的_converter辅助函数给出了最小配置模板测试第 100110 行from skill_seekers.cli.man_scraper import ManPageToSkillConverter config { name: golden_man_kw, description: Use when testing the man golden build, man_names: [git-log, git-diff, curl], categories: {version_control: [commit, diff]}, output_dir: skill, } converter ManPageToSkillConverter(config)命令行等价用法见 man_scraper.py 的 Usage 示例skill-seekers man --man-names git,curl --name unix-tools skill-seekers man --man-path /usr/share/man/man1 --name coreutils skill-seekers man --from-json unix-tools_extracted.json当--man-names列表中存在无法匹配--categories关键字的手册页时产物references/中就会出现other_*.md。这一兜底设计使转换管线对任意手册页集合都保持完整性与可导航性是 SKILL.md 中 Total Man Pages: 3 / Other: 1 man page(s) 统计成立的底层保证。结语other_02.md看似只是一份 23 行的简单参考文件实则是 Skill_Seekers man 页面转换管线中关键字分类 兜底回退 编号命名 截断保护四大设计交汇的产物。它同时作为 golden 快照锁定了整个分类与生成逻辑的行为契约。理解它的生成路径也就理解了 man_scraper.py 中categorize_content()、_generate_reference_file()、_generate_index()与_generate_skill_md()之间的协作关系以及 golden 测试对输出稳定性的守护方式。相关实现与验证代码可继续在 man_scraper.py 与 test_phase2_golden_man.py 中深入研读。【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考