deepspider 0.3.1 → 0.3.2

package/src/agent/middleware/validationWorkflow.js

@@ -0,0 +1,171 @@
+/**
+ * DeepSpider - 验证流程强制中间件
+ * 使用 state machine 模式确保两层验证都通过才允许保存报告
+ */
+
+import { createMiddleware } from 'langchain';
+import { z } from 'zod';
+
+// 验证状态 schema
+const validationStateSchema = z.object({
+  validationStage: z.enum(['none', 'algorithm', 'end_to_end', 'passed']).default('none'),
+  algorithmVerified: z.boolean().default(false),
+  endToEndVerified: z.boolean().default(false),
+  savedPythonCode: z.boolean().default(false),
+});
+
+/**
+ * 检测是否调用了 js2python 子代理（算法验证）
+ */
+function isAlgorithmVerification(state) {
+  // 检查最近的 tool_calls 是否包含 task 且 subagent_type 为 js2python
+  const messages = state.messages || [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.type === 'ai' && msg.tool_calls) {
+      for (const call of msg.tool_calls) {
+        if (call.name === 'task' && call.args?.subagent_type === 'js2python') {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 检测是否通过了端到端验证（sandbox_execute 成功返回目标数据）
+ */
+function isEndToEndVerification(state) {
+  const messages = state.messages || [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.type === 'tool' && msg.name === 'sandbox_execute') {
+      try {
+        const result = JSON.parse(msg.content);
+        // 检查是否成功且包含目标数据
+        if (result.success && !result.error) {
+          return true;
+        }
+      } catch {
+        // 解析失败，忽略
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 检测是否已保存 Python 代码（artifact_save 且路径包含 .py）
+ */
+function isPythonCodeSaved(state) {
+  const messages = state.messages || [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.type === 'tool' && msg.name === 'artifact_save') {
+      try {
+        const result = JSON.parse(msg.content);
+        if (result.success && result.path?.endsWith('.py')) {
+          return true;
+        }
+      } catch {
+        // 解析失败，忽略
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 创建验证流程中间件
+ * 强制要求：算法验证 → 端到端验证 → 保存代码 → 保存报告
+ */
+export function createValidationWorkflowMiddleware() {
+  return createMiddleware({
+    name: 'validationWorkflow',
+    stateSchema: validationStateSchema,
+
+    // 每次模型调用后检查验证状态
+    afterModel: (state) => {
+      const updates = {};
+
+      // 检查当前验证阶段
+      if (!state.algorithmVerified && isAlgorithmVerification(state)) {
+        updates.algorithmVerified = true;
+        updates.validationStage = 'algorithm';
+      }
+
+      if (!state.endToEndVerified && isEndToEndVerification(state)) {
+        updates.endToEndVerified = true;
+        updates.validationStage = 'end_to_end';
+      }
+
+      if (!state.savedPythonCode && isPythonCodeSaved(state)) {
+        updates.savedPythonCode = true;
+      }
+
+      // 所有验证通过
+      if (updates.algorithmVerified && updates.endToEndVerified && updates.savedPythonCode) {
+        updates.validationStage = 'passed';
+      }
+
+      return Object.keys(updates).length > 0 ? updates : undefined;
+    },
+
+    // 工具调用前检查是否允许
+    wrapToolCall: async (request, handler) => {
+      const toolName = request.tool?.name ?? request.toolCall?.name;
+      const args = request.toolCall?.args || {};
+      const state = request.state || {};
+
+      // 保存 Python 代码前检查算法验证
+      if (toolName === 'artifact_save') {
+        const filePath = args.file_path || '';
+        if (filePath.endsWith('.py')) {
+          if (!state.algorithmVerified) {
+            return {
+              type: 'tool',
+              name: 'artifact_save',
+              content: JSON.stringify({
+                success: false,
+                error: '保存 Python 代码前必须先完成算法验证。请委托 js2python 子代理验证加密/解密逻辑。',
+                requiredStep: '算法验证',
+                hint: '使用 task 工具，指定 subagent_type: "js2python"',
+              }),
+              tool_call_id: request.toolCall?.id || 'blocked',
+            };
+          }
+        }
+      }
+
+      // 保存报告前强制检查验证状态
+      if (toolName === 'save_analysis_report') {
+        const stage = state.validationStage || 'none';
+
+        if (stage !== 'passed') {
+          // 构造阻止消息
+          const missing = [];
+          if (!state.algorithmVerified) missing.push('算法验证（委托 js2python）');
+          if (!state.endToEndVerified) missing.push('端到端验证（sandbox_execute）');
+          if (!state.savedPythonCode) missing.push('保存 Python 代码');
+
+          return {
+            type: 'tool',
+            name: 'save_analysis_report',
+            content: JSON.stringify({
+              success: false,
+              error: `验证未完成，无法保存报告。缺少步骤：${missing.join('、')}`,
+              requiredSteps: missing,
+              currentStage: stage,
+            }),
+            tool_call_id: request.toolCall?.id || 'blocked',
+          };
+        }
+      }
+
+      return handler(request);
+    },
+  });
+}
+
+export default createValidationWorkflowMiddleware;

package/src/agent/prompts/system.js

@@ -15,21 +15,56 @@ export const systemPrompt = `你是 DeepSpider，一个智能爬虫 Agent。你
 - **Hook 已经注入**，数据已在自动记录中
 - 直接使用工具获取已捕获的数据
 
+## 你的职责
+
+你是调度者，不是执行者。负责分析、决策和委托子代理执行具体任务。
+
 ## 委托子代理
 
-**原则：简单任务自己做，复杂任务委托子代理。**
+**原则：你负责分析和调度，子代理负责执行。**
 
 | 场景特征 | 委托给 |
 |----------|--------|
-| 重度混淆 + 环境检测多 | env-agent |
-| 混淆代码需要深度反混淆 | static-agent |
-| Python转换多次失败 | js2python |
-| 需要复杂断点调试 | dynamic-agent |
-| 沙箱执行反复报错 | sandbox-agent |
+| 加密分析（反混淆、AST、断点、Hook、沙箱验证） | reverse-agent |
+| 已还原的 JS 转 Python | js2python |
+| 生成完整爬虫脚本 | crawler |
+| 验证码处理 | captcha |
+| 反检测/指纹/代理 | anti-detect |
 
 使用 \`task\` 工具委托，指定 \`subagent_type\` 和详细任务描述。
 
-**传递浏览器状态**：如果浏览器已打开，任务描述中必须包含"[浏览器已就绪]"和当前页面 URL。`;
+**传递浏览器状态**：如果浏览器已打开，任务描述中必须包含"[浏览器已就绪]"和当前页面 URL。
+
+### 委托最佳实践
+
+- 委托前先用最小代价验证关键假设（如一次 run_node_code 快速测试）
+- **description 包含用户原始需求**（子代理看不到用户消息）
+- **委托 reverse-agent 时通过 context 传递**：site, requestId, targetParam, url
+- **description 包含分析结论**：调用栈摘要、可疑参数、加密特征
+- 示例："调用栈：send@match/1:652 → oo0O0@match/1:960，可疑参数：m=<32位hex>"
+
+## 禁止行为（必须遵守）
+
+**你禁止自己编写代码**。当用户需要代码时，你必须：
+
+1. **不要在回复中输出代码片段** — 即使是"示例代码"也不允许
+2. **必须委托子代理**：
+   - Python 加密/解密代码 → \`task\` 委托 js2python
+   - 完整爬虫脚本 → \`generate_crawler_code\` 让用户选择框架，然后委托 crawler
+3. **分析结果用文字描述** — 说明接口、参数、数据结构，不要写代码
+
+**为什么？**
+- 你是调度者，代码质量由专业子代理保证
+- 用户需要的是可运行的文件，不是聊天框里的代码片段
+- 子代理会验证代码、保存文件、生成完整报告
+
+**正确示例**：
+- ✅ "我发现了 API 接口结构：GET /api/list?page=1，返回 JSON 数据。需要我生成爬虫代码吗？"
+- ✅ 调用 \`generate_crawler_code\` → 用户选择框架 → 委托 crawler 生成完整代码文件
+
+**错误示例**：
+- ❌ 在回复中直接写 "\`\`\`python\\nimport requests\\n..." 代码块
+- ❌ 说"这是一个简单的示例代码"然后输出代码`;
 
 /**
  * 完整分析专用提示 - 仅在用户请求完整分析时使用
@@ -41,83 +76,170 @@ export const fullAnalysisPrompt = `
 
 ### 分析思路
 
-1. **识别加密类型** - 先判断是哪种场景：
+1. **定位目标请求** - 找到数据来源的 API 接口：
+   - 用 search_in_responses 搜索用户选中的文本，定位数据来源请求
+   - 或用 get_request_list 浏览所有 XHR/Fetch 请求
+   - 记录请求的 site 和 id，委托 reverse-agent 时通过 context 参数传递
+
+2. **识别加密类型** - 查看请求详情，判断场景：
    - Headers 动态签名（如 X-Sign, X-Token）
    - Cookie 动态生成（如反爬 Cookie）
    - 请求参数加密（POST body 加密）
    - 响应数据解密（接口返回加密数据）
 
-2. **判断复杂度** - 决定自己做还是委托：
-   - **简单场景**（自己做）：标准加密算法、代码清晰可读
-   - **复杂场景**（委托子代理）：重度混淆、多层嵌套、环境检测多
+3. **根据加密情况分流**：
+
+   **🟢 无加密（快速路径）** — 如果请求参数全部为明文、无动态签名、无加密响应：
+   - 跳过 reverse-agent 和 js2python 委托
+   - 用 \`run_node_code\` 发送一次完整请求，确认接口可用且返回目标数据
+   - 调用 \`save_analysis_report\` 保存分析报告（无加密代码时 pythonCodeFile 可省略）
+   - 调用 \`generate_crawler_code\` → 用户选择框架 → 委托 crawler 生成爬虫代码
+   - 对 crawler 生成的代码做端到端验证（运行代码确认能拿到目标数据）
 
-3. **验证与输出** - **必须验证代码能正确运行**，才能生成报告
+   **🔴 有加密（完整路径）** — 存在任何加密特征时：
+   - 委托 reverse-agent 分析加密逻辑
+   - 委托 js2python 生成 Python 加密代码并验证算法正确
+   - 端到端验证：运行生成的代码，确认能正确复现请求并拿到目标数据
+   - 验证通过后保存报告并生成爬虫
 
-### 强制验证流程（必须遵守）
+4. **验证与输出** - **所有生成的代码都必须经过端到端验证**
 
-**验证分为两个层次，必须全部通过：**
+### 端到端验证（所有路径都必须执行）
 
-#### 第一层：算法验证（必须）
-验证加密/解密函数本身是否正确：
-1. 使用 \`run_python_code\` 执行加密/解密代码
-2. 检查：encrypt(plaintext) → ciphertext → decrypt() → plaintext
+**端到端验证 = 运行生成的代码，确认能正确复现请求并拿到与浏览器一致的目标数据。**
 
-#### 第二层：端到端验证（必须）
-验证完整请求能否获取到目标数据：
-1. 使用生成的代码构造完整请求（包含正确的 Headers、Cookies、加密参数）
-2. 发送请求到目标接口
-3. **检查响应是否包含用户要求的目标数据**
+不管是 Python 代码还是 JS 代码，不管有没有加密，都必须验证：
+1. 运行生成的代码发送请求
+2. 检查响应包含目标数据（与浏览器中看到的一致）
+3. 如果有加密，验证加密参数与浏览器请求中的格式一致
 
-**端到端验证的成功标准**：
-- ✅ 响应状态码正常（200）
-- ✅ 响应内容包含目标数据
-- ❌ 响应返回错误信息（如"参数错误"、"签名无效"）→ 验证失败
+**有加密时额外验证：**
+- 算法验证：委托 js2python 验证加密/解密逻辑能正确还原
 
-**端到端验证失败时的处理**：
-1. 分析错误响应，判断缺少什么
-2. 使用 \`get_request_detail\` 查看原始请求的完整信息
-3. 使用 \`get_cookies\` 获取浏览器当前 Cookie
-4. 补全缺失的参数后重新验证
-5. 如果多次失败，明确告知用户当前进度和遇到的问题
+**验证失败处理**：分析错误 → 用 get_request_detail 比对 → 补全参数重试
 
 ### 输出与保存
 
-**推荐流程**（分步保存）：
-1. 先用 \`artifact_save\` 保存 Python 代码到文件（如 \`{domain}/decrypt.py\`）
-2. 再调用 \`save_analysis_report\`，传入 \`pythonCodeFile\` 文件路径
-3. **必须在最终输出中告知用户文件保存路径**
+**有加密时**（分步保存）：
+1. 先用 \`artifact_save\` 保存加密代码到文件（如 \`{domain}/decrypt.py\`）
+2. 端到端验证通过后，调用 \`save_analysis_report\`，传入 \`pythonCodeFile\` 文件路径
+3. 再调用 \`generate_crawler_code\` → 委托 crawler 生成完整爬虫
 
-**调用 save_analysis_report 的前提条件**（必须全部满足）：
-1. 已使用 \`run_python_code\` 或 \`verify_with_python\` 验证代码能正确运行
-2. 验证结果与预期一致
-3. 已用 \`artifact_save\` 保存代码文件
+**无加密时**：
+1. 用 \`run_node_code\` 验证接口可用后，直接调用 \`save_analysis_report\`（无需 pythonCodeFile）
+2. 再调用 \`generate_crawler_code\` → 委托 crawler 生成爬虫代码
+3. 对 crawler 生成的代码做端到端验证
 
-**完成后必须输出文件路径**：
-\`\`\`
-📁 生成的文件：
-- Python 代码: ~/.deepspider/output/{domain}/decrypt.py
-- 分析报告: ~/.deepspider/output/{domain}/report.html
-\`\`\`
+**调用 save_analysis_report 的前提条件**：
+- 有加密：加密代码已通过端到端验证，且已用 \`artifact_save\` 保存
+- 无加密：已用 \`run_node_code\` 确认接口可用且返回目标数据
+
+**必须在最终输出中告知用户文件保存路径。**
 
 ### 任务完成标准
 
-**任务只有在满足以下条件时才算完成：**
-1. ✅ 定位数据来源接口
-2. ✅ 分析加密/解密算法
-3. ✅ 生成可运行的代码
-4. ✅ **端到端验证：发送请求能获取到目标数据**
-5. ✅ **保存报告：调用 save_analysis_report 保存分析结果**
+**无加密快速路径：**
+1. 定位数据来源接口
+2. 用 run_node_code 验证接口可用
+3. 调用 save_analysis_report 保存报告
+4. 调用 generate_crawler_code → 用户选择框架 → 委托 crawler 生成代码
+5. 端到端验证通过（运行 crawler 生成的代码能拿到目标数据）
+
+**有加密完整路径：**
+1. 定位数据来源接口
+2. 委托 reverse-agent 分析加密逻辑
+3. 委托 js2python 生成可运行的加密代码
+4. 端到端验证通过（运行生成的代码能正确复现请求）
+5. 调用 save_analysis_report 保存报告
+6. 调用 generate_crawler_code → 用户选择框架 → 委托 crawler 生成爬虫
+
+### 生成完整爬虫脚本
+
+**分析报告保存后，必须调用 \`generate_crawler_code\` 工具：**
+
+\`\`\`
+步骤1: 调用 save_analysis_report 保存分析报告
+步骤2: 调用 generate_crawler_code 工具，传入分析摘要
+       - 工具会暂停执行，向面板发送可点击的框架选项
+       - 用户点击后，工具自动恢复并返回用户选择的框架名称
+步骤3: 根据返回值委托 crawler 子代理生成代码（"不需要"则结束）
+\`\`\`
 
-**以下情况不算完成**：
-- ❌ 只验证了加密算法正确，但请求返回错误
-- ❌ 请求返回"参数错误"、"签名无效"等
-- ❌ 没有实际获取到用户要求的目标数据
-- ❌ 验证成功但没有调用 save_analysis_report
+**crawler 子代理任务要求：**
+- 基于分析结果和已有的代码模块（如有加密代码则整合）
+- 生成完整可运行的爬虫脚本（不是片段）
+- 使用 artifact_save 保存到 ~/.deepspider/output/{domain}/crawler.{py/json}
 
 ### 禁止行为
 - 禁止只验证算法正确就认为任务完成
 - 禁止在端到端验证失败时保存报告
 - 禁止忽略错误响应
-- 禁止假装任务完成`;
+- 禁止假装任务完成
+- **禁止跳过人工确认步骤直接生成爬虫脚本**`;
+
+export const tracePrompt = `
+## 追踪数据来源
+
+找到用户选中数据的来源接口，快速返回结果。
+
+### 步骤
+
+1. 用 search_in_responses 搜索选中文本的关键词，定位数据来源请求
+2. 如果搜索无结果，用 get_request_list 浏览 XHR/Fetch 请求列表，根据 URL 和时间判断
+3. 找到后用 get_request_detail 查看接口详情
+
+### 输出格式
+
+简洁总结：
+- 接口地址和方法（GET/POST）
+- 关键请求参数
+- 是否有加密迹象（Headers 签名、加密参数、加密响应）
+- 如需深入分析，建议用户选择"分析加密参数"`;
+
+export const decryptPrompt = `
+## 分析加密参数
+
+定位数据接口，分析加密机制，委托 reverse-agent 破解。
+
+### 步骤
+
+1. **定位接口** — search_in_responses 搜索选中文本，找到数据来源请求
+2. **识别加密** — get_request_detail 查看请求详情，判断加密类型：
+   - Headers 动态签名（如 X-Sign, X-Token）
+   - Cookie 动态生成
+   - 请求参数加密（POST body）
+   - 响应数据解密
+3. **委托分析** — 定位到目标请求后，立即委托 reverse-agent：
+   - 通过 context 传递 site、requestId、targetParam、url
+   - description 包含 get_request_initiator 返回的调用栈摘要
+   - description 包含可疑加密参数
+
+### 输出
+
+总结分析结果，包括：
+- 加密算法类型和实现方式
+- 关键参数的生成逻辑
+- 如已还原算法，告知用户可选择"完整分析并生成爬虫"生成代码`;
+
+export const extractPrompt = `
+## 提取页面结构
+
+分析用户选中元素的 DOM 结构，生成爬虫所需的选择器和字段配置。
+
+### 步骤
+
+1. **分析选中元素** — 根据 XPath 判断元素在页面中的位置和层级关系
+2. **识别列表结构** — 判断选中元素是否属于列表项（表格行、卡片列表等）
+3. **生成选择器** — 为每个字段生成 XPath 和 CSS 选择器
+4. **检测分页** — 查找分页组件（下一页按钮、页码、滚动加载）
+5. **检测数据来源** — 用 search_in_responses 快速检查数据是否来自 API（如果是，建议用"追踪数据来源"）
+
+### 输出
+
+结构化的字段配置：
+- 每个字段的名称、选择器、数据类型
+- 列表容器选择器
+- 分页方式和选择器（如有）
+- 数据来源判断（SSR 渲染 vs API 接口）`;
 
 export default systemPrompt;

package/src/agent/run.js

@@ -10,12 +10,14 @@ import readline from 'readline';
 import { readFileSync } from 'fs';
 import { marked } from 'marked';
 import { createDeepSpiderAgent } from './index.js';
-import { fullAnalysisPrompt } from './prompts/system.js';
+import { fullAnalysisPrompt, tracePrompt, decryptPrompt, extractPrompt } from './prompts/system.js';
 import { getBrowser } from '../browser/index.js';
 import { markHookInjected } from './tools/runtime.js';
 import { createLogger } from './logger.js';
 import { browserTools } from './tools/browser.js';
 import { ensureConfig } from './setup.js';
+import { getConfigValues } from '../config/settings.js';
+import { PATHS, ensureDir } from '../config/paths.js';
 import { StreamHandler, PanelBridge } from './core/index.js';
 
 let rl = null;
@@ -56,6 +58,16 @@ async function showReportFromFile(mdFilePath) {
   }
 }
 
+function getActionPrompt(action) {
+  switch (action) {
+    case 'trace': return tracePrompt;
+    case 'decrypt': return decryptPrompt;
+    case 'extract': return extractPrompt;
+    case 'full':
+    default: return fullAnalysisPrompt;
+  }
+}
+
 /**
  * 处理浏览器消息（通过 CDP binding 接收）
  */
@@ -72,12 +84,13 @@ async function handleBrowserMessage(data, page) {
     ).join('\n');
 
     const supplementText = data.text ? `\n\n用户补充说明: ${data.text}` : '';
+    const action = data.action || 'full';
 
-    userPrompt = `${browserReadyPrefix}用户选中了以下数据要求完整分析：
+    userPrompt = `${browserReadyPrefix}用户选中了以下数据：
 
 ${elementsDesc}${supplementText}
 
-${fullAnalysisPrompt}`;
+${getActionPrompt(action)}`;
   } else if (data.type === 'generate-config') {
     const config = data.config;
     userPrompt = `${browserReadyPrefix}请使用 crawler 子代理生成爬虫。
@@ -117,6 +130,20 @@ ${elementsDesc}`;
       });
     }
     return;
+  } else if (data.type === 'choice') {
+    // interrupt 恢复：用户点击了选项
+    console.log('\n[浏览器] 用户选择: ' + data.value);
+    await streamHandler.resumeInterrupt(data.value);
+    console.log('\n');
+    process.stdout.write('> ');
+    return;
+  } else if (data.type === 'confirm-result') {
+    // interrupt 恢复：用户点击了确认/取消
+    console.log('\n[浏览器] 用户' + (data.confirmed ? '确认' : '取消'));
+    await streamHandler.resumeInterrupt(data.confirmed);
+    console.log('\n');
+    process.stdout.write('> ');
+    return;
   } else {
     return;
   }
@@ -151,6 +178,7 @@ async function init() {
   const args = process.argv.slice(2);
   targetUrl = args.find(arg => arg.startsWith('http://') || arg.startsWith('https://'));
   DEBUG = process.env.DEBUG === 'true' || args.includes('--debug');
+  const PERSIST = args.includes('--persist');
   debugFn = (...a) => { if (DEBUG) console.log('[DEBUG]', ...a); };
 
   debugFn('init: 启动');
@@ -169,7 +197,7 @@ async function init() {
     output: process.stdout,
   });
 
-  const logger = createLogger({ enabled: DEBUG, verbose: false });
+  const loggerCallbacks = createLogger();
 
   async function onReportReady(mdFilePath) {
     console.log('[report] 中间件触发报告显示:', mdFilePath);
@@ -181,7 +209,7 @@ async function init() {
   agentConfig = {
     configurable: { thread_id: `deepspider-${Date.now()}` },
     recursionLimit: 5000,
-    callbacks: logger ? [logger] : [],
+    callbacks: loggerCallbacks,
   };
 
   // 初始化流处理器
@@ -201,7 +229,14 @@ async function init() {
     console.log(`正在打开: ${targetUrl}\n`);
     try {
       debugFn('init: 获取浏览器实例');
-      browser = await getBrowser();
+      const browserOptions = {};
+      const config = getConfigValues();
+      if (PERSIST || config.persistBrowserData) {
+        ensureDir(PATHS.BROWSER_DATA_DIR);
+        browserOptions.userDataDir = PATHS.BROWSER_DATA_DIR;
+        console.log(`[持久化模式] 浏览器数据保存在 ${PATHS.BROWSER_DATA_DIR}`);
+      }
+      browser = await getBrowser(browserOptions);
       browser.onMessage = handleBrowserMessage;
       debugFn('init: 导航到目标URL');
       await browser.navigate(targetUrl);

package/src/agent/skills/crawler/SKILL.md

@@ -1,9 +1,70 @@
 ---
 name: crawler
 description: |
-  crawler 相关经验。
+  爬虫编排经验。采集流程设计、数据提取策略、脚本生成。
+  触发：爬虫编排、数据采集、脚本生成、请求重放。
 ---
 
-# crawler
+# 爬虫编排经验
 
-自动创建的 skill 目录。
+## 采集流程设计
+
+### 请求重放型（优先）
+适用于：API 接口明确、参数已破解的场景。
+```
+1. 分析目标接口（URL、Method、Headers、参数）
+2. 确认加密参数已还原（由 reverse-agent 完成）
+3. 构造请求：固定 Headers + 动态参数生成
+4. 翻页/遍历逻辑
+5. 数据解析 + 存储
+```
+
+### 浏览器渲染型
+适用于：SPA 页面、数据由 JS 动态渲染、无法直接请求 API。
+```
+1. 页面加载 + 等待渲染完成
+2. 元素定位 + 数据提取
+3. 翻页操作（点击/滚动）
+4. 循环采集
+```
+
+## 数据提取策略
+
+| 数据位置 | 提取方式 |
+|----------|----------|
+| API JSON 响应 | JSONPath / 字段映射 |
+| HTML 结构化 | CSS Selector / XPath |
+| JS 渲染内容 | element.innerText（渲染后） |
+| 表格数据 | 按行列索引提取 |
+
+## 脚本生成规范
+
+### Python 脚本结构
+```python
+import requests
+
+class Crawler:
+    def __init__(self):
+        self.session = requests.Session()
+        self.session.headers.update({...})
+
+    def get_sign(self, params):
+        """加密参数生成（由逆向分析提供）"""
+        pass
+
+    def fetch_page(self, page):
+        """单页采集"""
+        pass
+
+    def run(self, max_pages):
+        """主流程"""
+        for page in range(1, max_pages + 1):
+            data = self.fetch_page(page)
+            self.save(data)
+```
+
+### 关键注意事项
+- Headers 要完整（User-Agent、Referer、Cookie）
+- 请求间隔随机化（1-3s）
+- 异常重试（网络超时、频控返回）
+- 数据去重（基于唯一标识）

package/src/agent/skills/crawler/evolved.md

@@ -1,5 +1,5 @@
 ---
-total: 1
+total: 3
 last_merged: null
 ---
 
@@ -11,6 +11,14 @@ last_merged: null
 **场景**: 招标采购网站使用 AES-CFB 加密请求参数，Key和IV为 "jinrun2024secret"，需要实现 Python 加密模块并集成到爬虫中
 **经验**: AES-CFB 加密网站爬虫开发时，使用 pycryptodome 的 AES.MODE_CFB 模式，segment_size=128，密钥和IV需要截取16字节。加密后Base64编码，请求体直接发送密文字符串。
 
+### [2026-02-13] 猿人学题目m参数生成规范
+**场景**: 猿人学第1题，需要生成m参数：timestamp = Date.now() + 100000000，md5 = MD5(timestamp)，m = md5 + '丨' + timestamp
+**经验**: 注意使用中文竖线'丨'而非英文竖线'|'，需要对m参数进行URL编码，第1页不传page参数，第2-5页需要page参数
+
+### [2026-02-14] 政府公示网站爬虫最佳实践
+**场景**: 金昌市信用公示网站行政处罚数据爬取，采用列表+详情两步爬取策略
+**经验**: 政府公示网站通常采用列表接口+详情接口的分离设计，应先获取所有ID再批量请求详情，并添加0.5-1秒随机延迟以示友好
+
 ## 近期发现
 
 <!-- 最近发现，FIFO 滚动，最多保留 10 条 -->