hello_js_reverse_skill/references/domain-session-guide.md

域级 Session 档案指南

v2.9.0 新增。每个目标域维护一份持久化 Session 档案，跨任务复用反爬类型判定、指纹基准、Cookie 归因结论，避免重复侦察。

1. 档案结构

每个域的 Session 档案存放在 cases/_session_archives/<domain-hash>/ 下，包含以下文件：

cases/_session_archives/
└── <domain-hash>/
    ├── session.json          # 核心档案（结构化元数据）
    ├── fingerprint.json      # 浏览器指纹基准快照
    ├── cookie-attribution.json  # Cookie 归因结论缓存
    ├── assertions.json       # 断言集（通过/失败/跳过）
    └── notes.md              # 人工备注（可选）

session.json 字段说明

{
  "domain_hash": "sha256(domain)[0:12]",
  "created_at": "ISO8601",
  "updated_at": "ISO8601",
  "skill_version": "2.9.0",
  "anti_crawl_type": "signature | behavioral | obfuscation | unknown",
  "anti_crawl_evidence": {
    "initial_status": 412,
    "final_status": 200,
    "redirect_chain_pattern": "412→412→200",
    "vmp_script_url": "**/sdenv-*.js",
    "vmp_case_count": 87,
    "sdk_fingerprint": ["sdenv", "FuckCookie"]
  },
  "tool_chain": {
    "primary": "instrument_jsvmp_source",
    "mode": "ast",
    "fallback": "hook_jsvmp_interpreter(mode=transparent)"
  },
  "hot_keys_snapshot": {
    "top_10": ["userAgent", "plugins", "webdriver", "cookie", "platform", "language", "screen.width", "screen.height", "hardwareConcurrency", "deviceMemory"],
    "total_count": 42,
    "captured_at": "ISO8601"
  },
  "cookie_attribution_summary": {
    "signature_cookies": ["acw_tc"],
    "js_cookies": ["x-bogus-js"],
    "mixed_cookies": ["NfBCSins"]
  },
  "assertions_passed": 12,
  "assertions_failed": 0,
  "assertions_total": 12
}

2. 生命周期

2.1 创建时机

Session 档案在以下时机自动创建：

1. Phase 0 启动时：launch_browser + navigate 成功后，检查 cases/_session_archives/ 下是否已有该域的档案

   • 已有 → 加载并验证（跑断言集，见第 4 节）
   • 没有 → 创建空档案，后续步骤逐步填充

2. 反爬类型识别完成后：将 anti_crawl_type 和 anti_crawl_evidence 写入档案

3. Phase 0.5 指纹采集后：将 hot_keys_snapshot 和 cookie_attribution_summary 写入档案

2.2 更新时机

• 每次成功完成 Phase 5 交付后，更新 updated_at 和断言结果
• Cookie 归因结论变化时（如新增 cookie 字段），更新 cookie-attribution.json
• 用户手动触发 session refresh 时，重新采集指纹基准

2.3 过期策略

• 档案默认 7 天有效（updated_at 距今超过 7 天视为过期）
• 过期档案不删除，但加载时会标记 stale: true，提示用户是否重新验证
• 断言集失败 ≥ 3 条时，自动标记为 needs_refresh

3. 与工作流的集成

Phase 0 集成

Phase 0 步骤 4（新增）：启动域级 Session 档案
  ① 计算目标域的 hash：sha256(domain)[0:12]
  ② 检查 cases/_session_archives/<hash>/session.json 是否存在
  ③ 存在且未过期 → 加载档案，输出摘要：
     "已加载域级 Session 档案：反爬类型=签名型，上次分析于 2 天前，12/12 断言通过"
  ④ 存在但过期 → 加载档案 + 标记 stale，提示用户：
     "域级 Session 档案已过期（7 天前），建议重新验证断言集"
  ⑤ 不存在 → 创建空档案，后续步骤自动填充

Phase 0.5 集成

Phase 0.5.-1（新增前置步骤）：本域断言 Reverify
  如果 Session 档案存在且包含断言集：
  ① 逐条执行断言（见第 4 节）
  ② 全部通过 → 跳过 Phase 0.5 的指纹采集，直接进入 Phase 1
     输出："断言集 12/12 通过，目标站点技术栈未变，跳过重复侦察"
  ③ 有失败 → 标记失败断言，进入 Phase 0.5 正常流程重新采集
     输出："断言 #3（VMP case_count）失败：期望 87，实际 102。目标可能已更新，重新侦察"

Phase 5 集成

Phase 5 交付时自动更新 Session 档案：
  ① 将本次分析的断言集写入 assertions.json
  ② 更新 session.json 的 updated_at 和 assertions_passed/failed/total
  ③ 如果是新域，提示用户："已创建域级 Session 档案，下次分析同域时将自动复用"

4. 断言系统

断言是 Session 档案的核心验证机制。每条断言描述一个可自动检测的技术事实，用于快速判断目标站点是否发生了技术变更。

4.1 断言类型

类型	示例	检测方法
script_exists	VMP 脚本 URL 模式仍然存在	list_scripts → 匹配 URL pattern
script_size_range	VMP 脚本大小在 ±20% 范围内	list_scripts → 检查文件大小
dispatch_loop_count	VMP 分发循环 case 数在 ±10 范围内	find_dispatch_loops → 比较 case_count
anti_crawl_type	反爬类型未变（仍为签名型）	navigate → 检查 redirect_chain 模式
cookie_names	关键 cookie 名称仍然存在	get_cookies → 检查 name 列表
sdk_fingerprint	SDK 特征关键词仍可搜索到	search_code → 匹配关键词
hot_keys_stable	hot_keys top 10 与快照重合度 ≥ 70%	get_instrumentation_log → 比较 hot_keys
response_structure	API 响应结构未变	get_network_request → 检查 JSON 字段

4.2 断言格式

{
  "assertions": [
    {
      "id": 1,
      "type": "script_exists",
      "description": "VMP 脚本 URL 匹配 **/sdenv-*.js",
      "params": { "url_pattern": "**/sdenv-*.js" },
      "last_result": "passed",
      "last_checked": "ISO8601"
    },
    {
      "id": 2,
      "type": "dispatch_loop_count",
      "description": "VMP 分发循环 case 数在 77-97 范围内",
      "params": { "expected": 87, "tolerance": 10 },
      "last_result": "passed",
      "last_checked": "ISO8601"
    }
  ]
}

4.3 断言执行流程

对每条断言：
  ① 根据 type 选择检测方法（MCP 工具调用）
  ② 执行检测，获取实际值
  ③ 与 params 中的期望值比较
  ④ 记录结果：passed / failed / skipped（工具不可用时）
  ⑤ 更新 assertions.json 的 last_result 和 last_checked

5. 隐私与安全

• 域名哈希化：目录名使用 sha256(domain)[0:12]，不直接暴露域名
• 已加入 .gitignore：cases/_session_archives/ 不纳入版本控制
• 敏感数据脱敏：session.json 中不存储具体 Cookie 值、密钥、Token 等
• fingerprint.json 仅存结构：存储属性名和类型，不存储具体指纹值（如 canvas hash）

6. 手动操作

查看当前域的 Session 档案

# 计算域名 hash
echo -n "target-domain.com" | sha256sum | cut -c1-12

# 查看档案
cat cases/_session_archives/<hash>/session.json | jq .

强制刷新档案

在对话中告诉 Agent："刷新当前域的 Session 档案"，Agent 将：

1. 清空 assertions.json
2. 重新执行 Phase 0 + Phase 0.5 的完整流程
3. 重建断言集

删除档案

rm -rf cases/_session_archives/<hash>/

7. 与经验库（cases/）的关系

维度	Session 档案	经验库案例
粒度	单个域	一类技术方案
内容	运行时状态（指纹、cookie、断言）	方法论（定位路径、还原模板）
生命周期	7 天有效，自动过期	永久，手动更新
隐私	哈希化，不入 git	脱敏后入 git
用途	跳过重复侦察	跳过重复分析

两者互补：Session 档案回答"这个域现在是什么状态"，经验库回答"这类技术方案怎么破"。