@gulibs/safe-coder 0.0.24 → 0.0.26

package/README.md

@@ -18,18 +18,29 @@
 - 智能缓存，基于版本键和 TTL
 - 热门包的背景刷新
 
-### 文档爬取和技能生成
+### 文档爬取和技能生成 🚀
 
+#### 核心功能
 - 递归爬取文档网站，自动跟踪文档链接
 - 智能边界检测，只在文档路径内爬取
 - 生成结构化的 Agent Skill 输出（Markdown 格式）
 - 支持深度限制、页面限制和速率控制
 - 自动组织内容，生成目录和章节
+
+#### 基础特性
 - **SPA 检测**：自动检测单页应用并提供建议
 - **智能重试**：对临时错误自动重试，提高成功率
 - **错误分类**：详细的错误类型统计和分析
 - **进度监控**：实时显示爬取进度和性能指标
 
+#### 🌟 增强特性（新增）
+- **双重爬取策略**：支持 BFS（广度优先）和 DFS（深度优先）两种策略
+- **并行爬取**：1-10个worker并发，速度提升 **4-6倍** ⚡
+- **断点续传**：中断后可恢复，支持大规模文档爬取
+- **llms.txt支持**：自动检测和使用llms.txt文件，效率提升 **2-3倍** ⚡
+- **Markdown支持**：完整支持.md文件爬取和结构化提取
+- **智能质量检测**：6项指标多维度评估内容质量
+
 ### 网页文档浏览
 
 - 浏览和搜索网页文档内容
@@ -435,11 +446,11 @@ pwd
 在 https://expressjs.com/en/guide 中查找关于路由的内容
 ```
 
-#### `crawl_documentation` - 爬取文档并生成技能
+#### `crawl_documentation` - 爬取文档并生成Agent Skill 🚀
 
 递归爬取文档网站，提取内容并生成结构化的 Agent Skill。
 
-**参数：**
+**基础参数：**
 - `url`（必需）：文档根 URL
 - `maxDepth`（可选）：最大爬取深度（默认：3）
 - `maxPages`（可选）：最大页面数（默认：50）
@@ -451,35 +462,181 @@ pwd
 - `outputDir`（可选）：保存技能文件的目录（如果不提供，只返回内容）
 - `filename`（可选）：自定义文件名（不含扩展名）
 
-**新功能：**
+**🌟 增强参数（新增）：**
+- `crawlStrategy`（可选）：爬取策略 `'bfs'` | `'dfs'`（默认：bfs）
+  - **BFS**（广度优先）：逐层爬取，适合全面覆盖
+  - **DFS**（深度优先）：深入一条路径，适合深度理解
+- `workers`（可选）：并发worker数量 1-10（默认：1）
+  - 建议：小型站点2-3个，大型站点5-8个
+  - 性能提升：3 workers ≈ 3倍，5 workers ≈ 4-5倍
+- `skipLlmsTxt`（可选）：是否跳过llms.txt检测（默认：false）
+  - 启用时自动检测和使用llms.txt，效率提升2-3倍
+- `checkpoint`（可选）：断点续传配置
+  - `enabled`：是否启用断点功能
+  - `interval`：每N页保存一次（默认：10）
+  - `file`：checkpoint文件路径（可选）
+- `resume`（可选）：是否从上次断点恢复（默认：false）
+
+**基础功能：**
 - ✅ **SPA 检测**：自动检测单页应用（SPA）并提供建议
 - ✅ **智能重试**：对临时错误（超时、网络错误等）自动重试
 - ✅ **错误分类**：详细的错误类型分类和统计
 - ✅ **进度日志**：实时显示爬取进度和统计信息
 
-**使用示例：**
+**🎯 使用示例：**
 
+##### 1. 快速基础爬取
 ```
 爬取 https://react.dev/docs 的文档并生成技能
 ```
 
+##### 2. 并行加速爬取（推荐）
+```
+从 https://react.dev 生成 agent skill，使用 5 个并发worker，最多爬取 200 页
+```
+
+对应参数：
+```json
+{
+  "url": "https://react.dev",
+  "workers": 5,
+  "maxPages": 200,
+  "rateLimit": 200
+}
+```
+
+##### 3. 深度优先策略
 ```
-从 https://nextjs.org/docs 生成 agent skill，深度限制为 2，最多 10 页，保存到 ./output
+使用 DFS 策略爬取 https://docs.example.com，深度限制为 6
 ```
 
-**输出：**
+对应参数：
+```json
+{
+  "url": "https://docs.example.com",
+  "crawlStrategy": "dfs",
+  "maxDepth": 6,
+  "workers": 3
+}
+```
+
+##### 4. 大规模爬取（带断点）
+```
+爬取 https://large-docs.com，最多 1000 页，启用断点每 50 页保存一次
+```
+
+对应参数：
+```json
+{
+  "url": "https://large-docs.com",
+  "maxPages": 1000,
+  "workers": 8,
+  "checkpoint": {
+    "enabled": true,
+    "interval": 50
+  }
+}
+```
+
+##### 5. 恢复中断的爬取
+```
+从断点恢复 https://large-docs.com 的爬取
+```
+
+对应参数：
+```json
+{
+  "url": "https://large-docs.com",
+  "resume": true,
+  "checkpoint": { "enabled": true }
+}
+```
+
+**📊 性能对比：**
+
+| 爬取规模 | 串行模式 | 并行模式(workers=5) | 提升 |
+|---------|---------|-------------------|------|
+| 50页 | ~90秒 | ~22秒 | **4倍** ⚡ |
+| 100页 | ~180秒 | ~45秒 | **4倍** ⚡ |
+| 200页 | ~360秒 | ~80秒 | **4.5倍** ⚡ |
+
+**输出内容：**
 - `skillContent`: Markdown 格式的技能内容
 - `metadata`: 技能元数据（标题、描述、源 URL 等）
-- `crawlStats`: 爬取统计（总页数、最大深度、错误列表）
+- `crawlStats`: 爬取统计（总页数、最大深度、错误列表、质量指标）
 - `files`（可选）：保存的文件路径
-  - `skillFile`: 技能 Markdown 文件路径（如果提供了 outputDir）
-  - `manifestFile`: 元数据 JSON 文件路径（如果提供了 outputDir）
+  - `skillFile`: SKILL.md 文件路径
+  - `manifestFile`: metadata.json 文件路径
+
+**💡 最佳实践：**
+1. **先小规模测试**：maxPages设为10-20验证效果
+2. **逐步增加并发**：从workers=2开始，观察效果
+3. **大规模使用断点**：超过200页建议启用checkpoint
+4. **关注质量指标**：diversity和coverage应 > 0.5
+
+**🌐 SPA网站支持（新增）：**
+
+系统智能检测并处理单页应用（React、Vue、Angular等），自动切换HTTP和浏览器渲染模式。
+
+##### 自动处理SPA（推荐）
+```
+爬取 https://react.dev 的文档  # 自动检测并处理SPA
+```
+
+##### SPA策略配置
+```typescript
+{
+  "spaStrategy": "smart",  // smart（智能）| auto（自动）| manual（手动）
+  "spaFallback": "warn",   // warn（警告）| skip（跳过）| error（错误）
+  "browserPath": "/path/to/chrome",  // 可选：自定义浏览器路径
+  "waitForTimeout": 3000,            // 可选：等待内容加载时间
+  "networkIdleTimeout": 500          // 可选：网络空闲等待时间
+}
+```
+
+**三种SPA策略**：
+- **smart（默认）**: HTTP优先，内容不足时自动切换浏览器（推荐）
+- **auto**: 检测到SPA立即使用浏览器
+- **manual**: 仅在useBrowserAutomation=true时使用浏览器
 
-**文件保存：**
-- 如果提供了 `outputDir`，会保存两个文件：
-  - `{filename}.md`: 技能内容文件
-  - `{filename}.metadata.json`: 元数据文件
-- 文件名自动从 URL 生成，或使用自定义 `filename` 参数
+**浏览器要求**：
+- ✅ 系统已安装Chrome/Chromium/Edge（推荐，自动检测）
+- ✅ 或安装完整版puppeteer（自动下载Chromium）
+- ✅ 或设置CHROME_PATH环境变量
+- 📖 详见：[SPA浏览器设置指南](docs/SPA_BROWSER_SETUP.md)
+
+**性能对比**：
+- HTTP模式：0.5-1秒/页
+- 浏览器模式：2-3秒/页
+- smart策略：平均<1.5秒/页（自动优化）
+
+**使用示例**：
+
+快速SPA爬取：
+```
+爬取 https://vuejs.org，自动处理SPA，最多100页
+```
+
+已知SPA站点：
+```
+从 https://angular.io 生成技能，使用浏览器渲染，5个并发worker
+```
+
+对应参数：
+```json
+{
+  "url": "https://angular.io",
+  "spaStrategy": "auto",
+  "workers": 5,
+  "maxPages": 200
+}
+```
+
+**📚 详细文档：**
+- SPA浏览器设置：`docs/SPA_BROWSER_SETUP.md`
+- 完整使用指南：`docs/ENHANCED_CRAWLING.md`
+- 快速上手：查看项目中的 `QUICKSTART_*.md` 文档
+- 实施细节：`IMPLEMENTATION_SUMMARY.md`
 
 #### `detect_errors` - 检测错误
 
@@ -678,8 +835,45 @@ npm run lint
 - 使用 `maxPages` 参数限制页面数量（默认 50）
 - 使用 `maxDepth` 参数限制爬取深度（默认 3）
 - 调整 `rateLimit` 避免对服务器造成压力（默认 500ms）
+- 使用 `workers` 参数启用并行爬取（推荐5-8个）
+- 启用 `checkpoint` 断点续传（超过200页建议启用）
 - 大型站点建议分多次爬取不同部分
 
+### Q: 如何爬取SPA网站（React、Vue等）？
+
+**A:**
+- 系统自动检测SPA并智能切换到浏览器渲染
+- 确保系统已安装Chrome/Chromium/Edge浏览器
+- 使用 `spaStrategy: "smart"` 获得最佳性能（默认）
+- 或使用 `spaStrategy: "auto"` 强制使用浏览器
+- 详见：`docs/SPA_BROWSER_SETUP.md`
+
+**示例**：
+```
+爬取 https://react.dev，自动处理SPA
+```
+
+### Q: 系统没有Chrome怎么办？
+
+**A:**
+有三种解决方案：
+1. **安装Chrome**（推荐）：
+   - macOS: `brew install --cask google-chrome`
+   - Windows: `winget install Google.Chrome`
+   - Linux: `sudo apt install google-chrome-stable`
+
+2. **安装完整版puppeteer**（自动下载Chromium）：
+   ```bash
+   npm install puppeteer
+   ```
+
+3. **设置浏览器路径**：
+   ```bash
+   export CHROME_PATH=/path/to/chrome
+   ```
+
+详细指南：`docs/SPA_BROWSER_SETUP.md`
+
 ### Q: 网页文档浏览和文档爬取有什么区别？
 
 **A:**
@@ -800,6 +994,244 @@ chmod +x dist/index.js
 
 MIT
 
+## 🎓 在大模型中使用MCP Server生成Agent Skill
+
+### 快速上手
+
+#### 步骤1：在Claude/Cursor中触发爬取
+
+**中文触发词：**
+```
+帮我爬取 https://react.dev 的文档并生成Agent Skill
+```
+
+```
+使用并行爬取从 https://docs.example.com 生成技能，要快一点
+```
+
+```
+递归抓取 https://nextjs.org/docs 的文档，深度优先策略
+```
+
+**英文触发词：**
+```
+Crawl https://react.dev and generate an agent skill
+```
+
+```
+Use parallel crawling to create a skill from https://docs.example.com
+```
+
+```
+Recursive crawl https://nextjs.org/docs with DFS strategy
+```
+
+#### 步骤2：配置爬取参数
+
+Claude/Cursor会自动调用`crawl_documentation`工具，你可以在对话中指定参数：
+
+**基础爬取：**
+```
+爬取 https://react.dev/docs，最多50页
+```
+
+**快速爬取（推荐）：**
+```
+爬取 https://react.dev，使用5个并发worker，最多200页
+```
+
+**深度研究：**
+```
+使用DFS策略深入爬取 https://docs.example.com，深度限制为6层
+```
+
+**大规模爬取：**
+```
+爬取 https://large-docs.com，最多1000页，启用断点续传每50页保存
+```
+
+### 使用场景
+
+#### 场景1：快速探索新技术栈
+```
+帮我爬取 Svelte 的官方文档，快速生成一个技能
+```
+
+**自动参数：**
+- workers: 3（快速）
+- maxPages: 50（快速探索）
+- crawlStrategy: bfs（全面覆盖）
+
+#### 场景2：深入学习框架
+```
+深入爬取 Vue 3 的文档，我要完整理解它的 API
+```
+
+**自动参数：**
+- crawlStrategy: dfs（深入学习）
+- maxDepth: 5（深入层级）
+- workers: 5（加速）
+- maxPages: 200（完整覆盖）
+
+#### 场景3：大型文档站点
+```
+爬取 MDN Web Docs 的 JavaScript 部分，分多次进行，支持断点恢复
+```
+
+**自动参数：**
+- workers: 8（大规模）
+- maxPages: 1000
+- checkpoint: { enabled: true, interval: 50 }
+
+#### 场景4：恢复中断的爬取
+```
+上次爬取中断了，从断点继续爬取 https://large-docs.com
+```
+
+**自动参数：**
+- resume: true
+- checkpoint: { enabled: true }
+
+### 生成的Agent Skill格式
+
+爬取完成后，会生成标准的Claude Agent Skill格式：
+
+```
+SKILL.md                    # 主技能文件
+├── 技能元数据（YAML frontmatter）
+├── When to Use This Skill  # 使用场景
+├── Core Concepts          # 核心概念
+├── API Reference         # API参考
+├── Examples              # 示例代码
+└── Reference Files       # 引用文件列表
+
+references/               # 引用文件目录
+├── page-1.md
+├── page-2.md
+└── ...
+```
+
+### 技能质量指标
+
+系统会自动评估生成的Skill质量：
+
+| 指标 | 说明 | 优秀标准 |
+|-----|-----|---------|
+| **内容充足性** | 每页内容长度 | > 100字符/页 |
+| **结构完整性** | 标题、章节组织 | 至少1个标题/页 |
+| **内容多样性** | URL路径和主题分布 | diversity > 0.7 |
+| **API覆盖度** | 代码示例比例 | coverage > 0.5 |
+
+### 使用生成的Skill
+
+#### 方法1：直接在对话中使用
+
+生成的Skill会自动出现在Claude的技能列表中，你可以直接引用：
+
+```
+根据我刚生成的React技能，帮我写一个自定义Hook
+```
+
+#### 方法2：保存为文件
+
+如果指定了`outputDir`，Skill会保存为文件：
+
+```
+爬取并保存到 ./skills 目录，文件名为 react-docs
+```
+
+生成文件：
+- `./skills/react-docs.md` - Skill内容
+- `./skills/react-docs.metadata.json` - 元数据
+
+#### 方法3：分享给团队
+
+将生成的SKILL.md文件放入项目的`.claude/skills/`目录，团队成员都可使用：
+
+```bash
+# 复制到项目技能目录
+cp output/react-docs.md .claude/skills/
+
+# 提交到版本控制
+git add .claude/skills/react-docs.md
+git commit -m "Add React documentation skill"
+```
+
+### 常见问题
+
+#### Q: 如何选择爬取策略？
+**A:**
+- **BFS（广度优先）**：适合扁平结构、需要全面覆盖的文档
+- **DFS（深度优先）**：适合层级结构、需要深入理解的文档
+
+#### Q: workers设置多少合适？
+**A:**
+- 小型站点（<50页）：workers: 2-3
+- 中型站点（50-200页）：workers: 3-5
+- 大型站点（>200页）：workers: 5-8
+
+#### Q: 什么时候需要启用断点？
+**A:**
+- 爬取页面超过200页
+- 网络不稳定
+- 需要分批次爬取
+
+#### Q: 如何提高爬取速度？
+**A:**
+1. 增加workers数量（推荐5-8个）
+2. 降低rateLimit（200-300ms）
+3. 确保站点有llms.txt（自动检测）
+
+#### Q: 生成的Skill质量不够怎么办？
+**A:**
+1. 增加maxPages（建议200+）
+2. 调整maxDepth（建议3-5）
+3. 使用includePaths精确指定路径
+4. 查看日志中的质量指标建议
+
+### 性能提示
+
+**🚀 极速模式（适合快速探索）：**
+```json
+{
+  "workers": 5,
+  "maxPages": 50,
+  "rateLimit": 200,
+  "crawlStrategy": "bfs"
+}
+```
+
+**🎯 深度模式（适合完整学习）：**
+```json
+{
+  "workers": 5,
+  "maxPages": 300,
+  "maxDepth": 5,
+  "crawlStrategy": "dfs",
+  "checkpoint": { "enabled": true }
+}
+```
+
+**⚡ 超快模式（适合有llms.txt的站点）：**
+```json
+{
+  "workers": 8,
+  "skipLlmsTxt": false,
+  "rateLimit": 200
+}
+```
+
+### 完整文档
+
+- **快速上手指南**：项目中的快速开始文档
+- **详细使用说明**：`docs/ENHANCED_CRAWLING.md`
+- **实施技术细节**：`IMPLEMENTATION_SUMMARY.md`
+- **原始文档爬取指南**：`docs/DOC_CRAWLER_USAGE.md`
+
+---
+
 ## 贡献
 
 欢迎提交 Issue 和 Pull Request！
+
+基于 [Skill_Seekers](examples/Skill_Seekers/) 项目的优秀实践，我们实现了完整对标并超越的TypeScript版本。

package/dist/documentation/browser-manager.d.ts

@@ -0,0 +1,51 @@
+import { type Browser } from 'puppeteer-core';
+export interface BrowserConfig {
+    executablePath?: string;
+    headless?: boolean;
+    timeout?: number;
+    waitForTimeout?: number;
+    networkIdleTimeout?: number;
+}
+export interface BrowserRenderResult {
+    html: string;
+    title: string;
+    url: string;
+    links: Array<{
+        text: string;
+        url: string;
+    }>;
+    screenshots?: string[];
+}
+/**
+ * Browser manager for SPA rendering using puppeteer-core
+ * Detects and uses system Chrome/Chromium/Edge
+ */
+export declare class BrowserManager {
+    private browser?;
+    private config;
+    private readonly BROWSER_PATHS;
+    constructor();
+    /**
+     * Detect system browser
+     * Returns path to Chrome/Chromium/Edge or null
+     */
+    detectBrowser(): Promise<string | null>;
+    /**
+     * Launch browser instance
+     */
+    launch(config?: Partial<BrowserConfig>): Promise<Browser>;
+    /**
+     * Render a page and extract content
+     * Uses balanced performance mode
+     */
+    renderPage(url: string): Promise<BrowserRenderResult>;
+    /**
+     * Close browser instance and cleanup resources
+     */
+    close(): Promise<void>;
+    /**
+     * Check if browser is currently launched
+     */
+    isLaunched(): boolean;
+}
+//# sourceMappingURL=browser-manager.d.ts.map

package/dist/documentation/browser-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-manager.d.ts","sourceRoot":"","sources":["../../src/documentation/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,OAAO,EAAa,MAAM,gBAAgB,CAAC;AAOjE,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAUD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAwB;IAGtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAoB5B;;IAYF;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA6D7C;;OAEG;IACG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAyD/D;;;OAGG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgF3D;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;OAEG;IACH,UAAU,IAAI,OAAO;CAGtB"}