feat: skill v3.2.0 — 硬约束Checklist五项压缩到三项，移除MCP session依赖，cases/成为唯一经验库

- SKILL.md 瘦身重写（核心层+按需加载references/） - Checklist: CHECK-3/4(session)删除，五项→三项 - 新增6个references子文档（path-a/path-b/phase-details/experience-rules-full/mcp-tool-reference/common-pitfalls） - 删除 references/domain-session-guide.md - 工具引用对齐实际MCP（32工具），verify_signer_offline替代verify_against_session - cases/_template.md 新增可验证事实清单段 - 经验法则session相关条目改写 - 红线四条、第一原则0-5、三分法、四板斧、六步法完整保留
2026-04-18 13:36:14 +08:00
parent a5228600f4
commit 38b982fb1e
13 changed files with 2905 additions and 2067 deletions
@@ -0,0 +1,287 @@
+# MCP 工具分类索引 + v0.9.0 迁移指南
+
+> **说明**：SKILL.md 核心层有工具分类索引，这里是详细版 + MCP v0.9.0 的迁移映射
+>
+> **版本**：v3.1.0（MCP v0.9.0 工具名迁移）
+>
+> **当前 MCP 版本**：camoufox-reverse MCP v0.9.0（~50 个工具，从 v0.8.x 的 ~80 个合并而来）
+
+---
+
+## 一、工具分类表
+
+### Browser — 浏览器与页面控制
+
+| 工具名 | 一行描述 |
+|--------|---------|
+| `launch_browser` | 启动 Camoufox 反检测浏览器（C++ 引擎级指纹伪装） |
+| `close_browser` | 关闭浏览器释放资源 |
+| `navigate` | 导航到 URL，支持 pre_inject_hooks / wait_until / collect_response_chain |
+| `reload` | 刷新当前页面 |
+| `go_back` | 浏览器后退 |
+
+### Page — 页面交互与信息
+
+| 工具名 | 一行描述 |
+|--------|---------|
+| `click` | 点击页面元素 |
+| `type_text` | 输入文本（带真实按键延迟） |
+| `wait_for` | 等待元素出现或网络请求匹配 |
+| `get_page_info` | 获取当前页面 URL、标题、视口尺寸 |
+| `take_screenshot` | 截取页面截图 |
+| `take_snapshot` | 获取页面无障碍树（token 高效） |
+| `evaluate_js` | 在页面上下文执行任意 JS（最核心工具） |
+| `evaluate_js_handle` | 执行 JS 并检查复杂对象属性 |
+| `get_page_html` | 获取页面 HTML 或指定元素的 outerHTML |
+
+### Network — 网络分析
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `network_capture(action='start'\|'stop')` <!-- v3.1.0: migrated from start_network_capture/stop_network_capture --> | 启停网络流量捕获，支持 capture_body=True |
+| `list_network_requests` | 列出捕获的请求（支持 URL/method/type/status 过滤） |
+| `get_network_request` | 获取请求完整详情（含响应体） |
+| `get_request_initiator` | 获取发起请求的 JS 调用栈（黄金路径） |
+| `intercept_request` | 拦截请求（log/block/modify/mock） |
+| `stop_intercept` | 停止拦截 |
+| `search_response_body` | 在所有已捕获响应体中全文搜索 |
+| `get_response_body_page` | 分页读取大响应体 |
+| `search_json_path` | 按 JSON 路径提取响应数据 |
+
+### Scripts — 源码分析
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `scripts(action='list')` <!-- v3.1.0: migrated from list_scripts --> | 列出页面加载的所有 JS 脚本 |
+| `scripts(action='get', url=...)` <!-- v3.1.0: migrated from get_script_source --> | 获取完整 JS 源码 |
+| `scripts(action='save', url=..., save_path=...)` <!-- v3.1.0: migrated from save_script --> | 保存 JS 文件到本地 |
+| `search_code` | 在所有已加载 JS 中搜索关键词（全局） |
+| `search_code(keyword, script_url=url)` <!-- v3.1.0: migrated from search_code_in_script --> | 在指定脚本中搜索（大文件精确定位） |
+
+### Hook — 调试与 Hook
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `add_init_script` | 注入页面加载前执行的脚本（支持 persistent） |
+| `set_breakpoint_via_hook` | 通过 JS Hook 设置伪断点 |
+| `get_breakpoint_data` | 获取伪断点捕获的数据 |
+| `get_console_logs` | 获取页面控制台输出 |
+| `hook_function(path, mode='trace', ...)` <!-- v3.1.0: migrated from trace_function --> | 追踪函数调用（不暂停执行） |
+| `get_trace_data` | 获取追踪数据 |
+| `hook_function(path, hook_code=..., position=...)` | 注入自定义 Hook（before/after/replace） |
+| `hook_function(path, mode='intercept', non_overridable=True)` <!-- v3.1.0: migrated from freeze_prototype --> | 冻结原型方法防覆盖 |
+| `inject_hook_preset` | 一键预设 Hook（xhr/fetch/crypto/websocket/debugger_bypass/cookie/runtime_probe） |
+| `get_runtime_probe_log` | 拉取 runtime_probe 日志 |
+| `remove_hooks` | 移除所有 Hook |
+| `bypass_debugger_trap` | 一键绕过反调试陷阱 |
+
+### JSVMP — 虚拟机专项分析
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `hook_jsvmp_interpreter` | 多路径通用探针（proxy/transparent 模式） |
+| `hook_jsvmp_interpreter(mode='proxy', trackProps=True)` <!-- v3.1.0: migrated from trace_property_access --> | Proxy 级别属性访问追踪 |
+| `get_jsvmp_log` | 获取 JSVMP 探针日志 |
+| `dump_jsvmp_strings` | 提取 JSVMP 脚本中的字符串 |
+| `compare_env` | 采集浏览器环境指纹基准 |
+| `instrumentation(action='install', url_pattern=..., mode=..., tag=...)` <!-- v3.1.0: migrated from instrument_jsvmp_source --> | 源码级插桩（HTTP 层改写 VMP） |
+| `instrumentation(action='log', tag=..., type_filter=...)` <!-- v3.1.0: migrated from get_instrumentation_log --> | 获取源码插桩日志（hot_keys/hot_methods/hot_functions） |
+| `instrumentation(action='status')` | 查看当前激活的源码插桩状态 |
+| `instrumentation(action='stop', url_pattern=...)` <!-- v3.1.0: migrated from stop_instrumentation --> | 停止源码级插桩 |
+| `instrumentation(action='reload')` <!-- v3.1.0: migrated from reload_with_hooks --> | 重载页面让 hooks 先于 VMP 生效 |
+| `analyze_cookie_sources` | Cookie 归因分析（HTTP vs JS 来源） |
+
+### Session — 域级 Session 档案
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `start_reverse_session` | 启动新的分析 run |
+| `stop_reverse_session` | 结束当前 run |
+| `get_session_snapshot` | 获取活跃 session 快照 |
+| `list_sessions` | 列出所有域 session 档案 |
+| `attach_domain_readonly` | 只读附加已有域档案 |
+| `export_session` | 导出域档案为 zip |
+| `import_session` | 导入域档案 zip |
+
+### Assertion — 断言系统
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `add_assertion` | 注册域级断言 |
+| `verify_assertion(assertion_id=...)` | 验证单条断言 |
+| `verify_assertion(assertion_id='*')` <!-- v3.1.0: migrated from reverify_all_assertions_on_domain --> | 批量验证所有断言 |
+| `list_assertions` | 列出域上的所有断言 |
+| `remove_assertion` | 软删除断言 |
+
+### Environment — 存储与指纹
+
+| 工具名（v0.9.0） | 一行描述 |
+|-------------------|---------|
+| `cookies(action='get', ...)` <!-- v3.1.0: migrated from get_cookies --> | 获取 Cookie |
+| `cookies(action='set', ...)` <!-- v3.1.0: migrated from set_cookies --> | 设置 Cookie |
+| `delete_cookies` | 删除 Cookie |
+| `get_storage` | 获取 localStorage/sessionStorage |
+| `set_storage` | 设置 storage |
+| `export_state` | 导出浏览器状态（Cookie + Storage） |
+| `import_state` | 导入浏览器状态 |
+| `get_fingerprint_info` | 检查当前浏览器指纹 |
+| `check_detection` | 在反检测站点测试是否被识别 |
+| `get_session_info` | 查看当前会话状态全貌 |
+
+---
+
+## 二、v0.8.x → v0.9.0 完整迁移表
+
+> MCP v0.9.0 将 ~80 个工具合并为 ~50 个，核心变化是将同类操作合并为带 `action` 参数的统一接口。
+
+### 19 个工具合并为 7 个统一接口
+
+| v0.8.x 旧名 | v0.9.0 新名 | 说明 |
+|-------------|-------------|------|
+| `start_network_capture(capture_body=X)` | `network_capture(action='start', capture_body=X)` | 网络捕获启停合并 |
+| `stop_network_capture()` | `network_capture(action='stop')` | |
+| `search_code_in_script(url, keyword)` | `search_code(keyword, script_url=url)` | 合并到 search_code，script_url 可选参数 |
+| `trace_function(path, ...)` | `hook_function(path, mode='trace', ...)` | 追踪合并到 hook_function |
+| `instrument_jsvmp_source(url_pattern, ...)` | `instrumentation(action='install', url_pattern=url_pattern, ...)` | 源码插桩统一接口 |
+| `get_instrumentation_log(tag=X)` | `instrumentation(action='log', tag=X)` | |
+| `get_instrumentation_status()` | `instrumentation(action='status')` | |
+| `stop_instrumentation()` | `instrumentation(action='stop')` | |
+| `reload_with_hooks()` | `instrumentation(action='reload')` | |
+| `get_cookies(...)` | `cookies(action='get', ...)` | Cookie 管理统一接口 |
+| `set_cookies(...)` | `cookies(action='set', ...)` | |
+| `list_scripts(...)` | `scripts(action='list', ...)` | 脚本管理统一接口 |
+| `get_script_source(url)` | `scripts(action='get', url=url)` | |
+| `save_script(url, path)` | `scripts(action='save', url=url, save_path=path)` | |
+| `reverify_all_assertions_on_domain()` | `verify_assertion(assertion_id='*')` | 批量验证合并到 verify_assertion |
+| `find_dispatch_loops(url)` | `search_code(keyword='switch', script_url=url, context_chars=500)` | 合并到 search_code 的高级用法 |
+| `trace_property_access(...)` | `hook_jsvmp_interpreter(mode='proxy', trackProps=True)` | 合并到 hook_jsvmp_interpreter |
+| `freeze_prototype(class, method)` | `hook_function('class.prototype.method', mode='intercept', ...)` | 合并到 hook_function |
+| `get_page_content()` | `evaluate_js("document.documentElement.outerHTML")` | 用 evaluate_js 替代 |
+
+### 已删除工具及替代方案（12 个）
+
+| 已删除工具 | 替代方案 |
+|-----------|---------|
+| `get_property_access_log` | `get_jsvmp_log(type_filter='prop_read')` |
+| `get_page_content` | `evaluate_js("document.documentElement.outerHTML")` <!-- v3.1.0: migrated from get_page_content --> |
+| `find_dispatch_loops` | `search_code(keyword='switch', script_url='<url>', context_chars=500)` |
+| `trace_property_access` | `hook_jsvmp_interpreter(mode='proxy', trackProps=True)` |
+| `freeze_prototype` | `hook_function('X.prototype.Y', mode='intercept', non_overridable=True)` |
+| `check_csp_policy` | `evaluate_js("document.querySelector('meta[http-equiv=Content-Security-Policy]')?.content")` |
+| `get_response_chain` | `navigate()` 返回值中的 `redirect_chain` 字段 |
+| `get_dual_sign_data` | 组合 `list_network_requests` + `get_network_request` 手动提取 |
+| `diff_hot_keys` | 本地 JSON diff 或 `evaluate_js` 实现 |
+| `create_session` | `start_reverse_session` |
+| `load_session` | `attach_domain_readonly` + `verify_assertion(assertion_id='*')` |
+| `update_session` | `stop_reverse_session` + `add_assertion` |
+
+---
+
+## 三、6 个月 Shim 兼容期
+
+> MCP v0.9.0 提供 6 个月的 shim 兼容期（至 2027-01-01）。
+
+### Shim 行为
+
+- 旧工具名仍可调用，MCP 内部自动映射到新接口
+- 每次调用旧名会在 console 输出 deprecation warning
+- Shim 期结束后旧名将返回 `ToolNotFound` 错误
+
+### 建议迁移时间线
+
+| 阶段 | 时间 | 行动 |
+|------|------|------|
+| 立即 | 现在 | 新代码/新文档全部使用 v0.9.0 名称 |
+| 1 个月内 | 2026-08 | 更新所有 cases/*.md 中的工具名 |
+| 3 个月内 | 2026-10 | 更新所有 references/*.md 中的工具名 |
+| 6 个月内 | 2027-01 | 确认无旧名残留，shim 期结束 |
+
+---
+
+## 四、MCP v0.9.0 关键变化总结
+
+### 工具数量
+
+- v0.8.x：~80 个独立工具
+- v0.9.0：~50 个工具（19 个合并为 7 个统一接口 + 12 个删除）
+
+### 设计原则
+
+1. **同类操作合并**：start/stop/get/list 合并为带 `action` 参数的统一接口
+2. **功能重叠消除**：`trace_function` 和 `hook_function` 合并（trace 是 hook 的一种 mode）
+3. **语义一致性**：`freeze_prototype` 本质是 hook 的 intercept 模式
+4. **减少记忆负担**：7 个统一接口覆盖原来 19 个工具的功能
+
+### 不变的核心工具
+
+以下工具在 v0.9.0 中保持不变：
+
+```
+launch_browser / close_browser / navigate / reload / go_back
+click / type_text / wait_for / get_page_info
+take_screenshot / take_snapshot
+evaluate_js / evaluate_js_handle
+get_page_html / add_init_script
+set_breakpoint_via_hook / get_breakpoint_data
+get_console_logs / get_trace_data
+hook_function (扩展了 mode 参数)
+inject_hook_preset / remove_hooks / bypass_debugger_trap
+hook_jsvmp_interpreter / get_jsvmp_log / dump_jsvmp_strings
+compare_env / analyze_cookie_sources
+get_runtime_probe_log
+list_network_requests / get_network_request / get_request_initiator
+intercept_request / stop_intercept
+search_response_body / get_response_body_page / search_json_path
+delete_cookies / get_storage / set_storage
+export_state / import_state
+get_fingerprint_info / check_detection / get_session_info
+start_reverse_session / stop_reverse_session / get_session_snapshot
+list_sessions / attach_domain_readonly
+export_session / import_session
+add_assertion / verify_assertion / list_assertions / remove_assertion
+```
+
+---
+
+## 五、Session/Assertion 工具移除（v3.2.0 新增）
+
+以下工具在当前 MCP 版本中**不存在**，skill v3.2.0 已移除所有引用：
+
+| 移除的工具 | 替代 |
+|---|---|
+| `start_reverse_session` / `stop_reverse_session` | 无替代。经验沉淀到 cases/ 文件 |
+| `get_session_snapshot` | 无替代。手动查看 list_network_requests / instrumentation(action='log') |
+| `list_sessions` / `attach_domain_readonly` | 无替代。读 cases/README.md 查已有案例 |
+| `export_session` / `import_session` | 无替代。case 文件本身是可 commit 的经验 |
+| `add_assertion` / `verify_assertion` / `list_assertions` / `remove_assertion` | 在 case 文件的"可验证事实清单"段列事实，AI 手动核对 |
+| `verify_against_session(signer_code, sample_filter=...)` | `verify_signer_offline(signer_code, samples=[...])` — 样本由用户提供 |
+
+`verify_signer_offline` 迁移示例：
+
+```python
+# 步骤 1 — 手动提取样本
+reqs = await list_network_requests(url_filter="api/search")
+samples = []
+for req in reqs["requests"][:10]:
+    full = await get_network_request(req["id"])
+    url = full["url"]
+    xbogus = _parse_url_param(url, "X-Bogus")
+    if xbogus:
+        samples.append({
+            "id": f"req_{req['id']}",
+            "input": {"url": _strip_param(url, "X-Bogus")},
+            "expected": {"X-Bogus": xbogus},
+        })
+
+# 步骤 2 — 验证
+r = await verify_signer_offline(
+    signer_code="(s) => ({'X-Bogus': mySign(s.input.url)})",
+    samples=samples,
+    compare_params=["X-Bogus"],
+)
+```
+
+---
+
+> **SKILL.md 核心层**有工具分类索引的精简版
+> **各工具的详细用法**：查看工具自身的 docstring