AgentSkillsCN

docs-to-zh-manual

从官方文档入口 URL 自动梳理文档结构、提取关键内容并生成可发布的中文 Markdown 使用手册文档集（README + 分章文件 + 相对链接导航 + 目录树预览）。当用户提供“官方文档入口 URL”并要求“中文使用手册/中文文档集/内部发布版 Markdown 文档/把分散网页整理成手册”时使用。

中文原作
SKILL.md
--- frontmatter
name: docs-to-zh-manual
description: 从官方文档入口 URL 自动梳理文档结构、提取关键内容并生成可发布的中文 Markdown 使用手册文档集（README + 分章文件 + 相对链接导航 + 目录树预览）。当用户提供“官方文档入口 URL”并要求“中文使用手册/中文文档集/内部发布版 Markdown 文档/把分散网页整理成手册”时使用。

Docs To Zh Manual（从官方文档生成中文手册）

目标

给定一个“官方文档入口 URL”，自动抓取与理解文档结构与页面内容，整理为结构化的中文 Markdown 文档集（多文件、相对链接、可直接发布/学习）。

输入格式（优先按此提供）

code
官方文档入口 URL：
<用户填入 URL>

Markdown 文档集存放路径：
<用户填入输出目录路径；可选，默认：./软件使用手册-软件名称/>

如果可选信息可获得，一并确认（缺失则在流程中自动推断，或在必要时再追问 1-2 个关键问题）：

  • •软件名称/产品名（用于输出目录命名）
  • •文档版本（如 v1/v2、latest、LTS）
  • •目标读者（新手/运维/开发/安全/管理员）
  • •输出范围（仅入门 + 核心模块 / 全量 / 指定模块列表）
  • •文档语言（英文/中文/混合；默认“中文总结 + 保留原始代码/命令”）

工作流（按顺序执行）

1) 获取并解析文档结构

  1. •访问入口页，识别可用的结构线索（按优先级）：
    • •sitemap.xml / robots.txt / 站内搜索结果页（如有）
    • •全局导航栏/侧边栏目录（nav/aside）、页面内 TOC（table of contents）
    • •“Next/Previous” 翻页链路、面包屑、版本切换器
  2. •建立“章节树/模块树”：
    • •识别父/子章节关系与模块划分（按 URL 前缀、导航层级、面包屑、标题层级综合判断）
    • •记录每个节点：标题、URL、父节点、推荐归属手册章节
  3. •如果文档规模很大（例如数百页以上），先做“范围确认”：
    • •默认优先产出：简介、安装配置、核心概念、快速开始、最常用模块、FAQ、附录
    • •其余模块可按“模块清单”分批生成

2) 提取核心信息（逐章节/逐模块）

对每个重要章节或 API/功能模块，提取并归纳（缺什么补什么）：

  • •关键概念/术语定义（必要时给中英文对照）
  • •用法与步骤（从“最小可跑”开始）
  • •配置项/参数说明（含默认值、取值范围、是否必填、约束）
  • •示例代码/命令/配置片段（保持格式与可复制性）
  • •注意事项、限制条件、兼容性、最佳实践
  • •表格信息（转为 Markdown 表格或结构化列表）
  • •常见错误与排查（如有）

当信息分散在多个页面时：

  • •合并到同一手册文件内，用二级/三级标题区分来源与小节
  • •在章节末尾增加“延伸阅读/原文链接”

3) 生成结构化 Markdown 中文文档集（独立目录）

输出到独立目录，目录结构反映内容逻辑，默认命名：

  • •软件使用手册-软件名称/（软件名称无法可靠推断时先追问）

推荐文件结构（可按文档实际模块增减）：

code
/软件使用手册-软件名称/
├─ README.md
├─ 01-简介.md
├─ 02-安装与配置.md
├─ 03-核心概念.md
├─ 04-快速开始.md
├─ 05-功能模块-XXX.md
├─ 06-功能模块-YYY.md
├─ 98-常见问题.md
└─ 99-附录.md

每个 Markdown 文件要求：

  • •以清晰的一级标题开头（# 标题），标题与文件名一致或高度一致
  • •代码示例使用 fenced code block（```），并标注语言（如 bash/yaml/json/python）
  • •表格尽量转为 Markdown 表格；过宽表格转为“字段清单”格式
  • •文内引用使用相对链接，例如：参见：[核心概念](03-核心概念.md)

README.md 需要包含：

  • •项目概览（软件是什么、适用人群、版本/入口链接）
  • •文档导航（按序号列出章节链接）
  • •生成说明（数据来源：官方文档 URL；生成时间；覆盖范围）

生成完成后输出目录树预览（文本树即可）。

4) 质量要求与自检

在交付前，至少做一次自检：

  • •不遗漏“入口 URL 导航树”中的核心章节（或明确说明“未覆盖范围”）
  • •关键示例、注意事项、FAQ 被纳入；命令/配置片段可复制
  • •相对链接可用、编号顺序合理、章节命名一致
  • •中文表达流畅、术语一致；对不确定处使用“待确认”并附原文链接，避免编造

可选脚本：抓取页面并生成提取结果

当需要快速批量抓取网页并得到“可总结的正文（markdown-ish）”时，运行：

bash
python scripts/crawl_docs.py "<入口URL>" --out "<Markdown 文档集存放路径>/_docs_crawl" --max-pages 80

脚本输出：

  • •<out>/manifest.json：页面列表（URL、标题、状态、正文文件名、出链数）
  • •<out>/pages/*.md：每页提取后的正文（用于后续总结与合并）

优先用脚本结果来建立章节结构与内容归纳；如果脚本抓取受限（强 JS 渲染/登录墙），再切换为逐页访问与手动结构抽取。