Files

T

AskaEth 985860b2a2 docs: 将反检测作为核心设计原则，全面更新架构和文档

- architecture.md: 新增反检测为核心第一性原理，新增 §3 反检测设计（13 个指纹维度全覆盖）
- anti-detection.md: 新增反检测专项文档（14 节，详尽列举检测方式和应对策略）
- api.md: POST /pages 新增 profile 参数，新增 GET /profiles 端点
- cli.md: 新增 --profile 全局选项，新增 visionl profiles 命令
- contributing.md: 新增反检测开发规范、检测站点验证要求
- README.md: 更新项目定位和特性描述

2026-08-12 20:21:53 +08:00

3.9 KiB

Raw Blame History

VisionL 开发规范

环境要求

Node.js >= 18
npm >= 9
Git

克隆与安装

git clone ssh://git@git.yeij.top:2222/AskaEth/VisionL.git
cd VisionL
git checkout dev

# 安装所有 workspace 依赖
npm install

# 安装 Playwright 浏览器（Chromium）
npx playwright install chromium

项目结构

Monorepo 使用 npm workspaces 管理：

packages/
├── core/        # 共享类型（含 FingerprintProfile）、HTTP 客户端、JSON 转义
├── daemon/      # 后台守护进程 + stealth 反检测模块
└── cli/         # 命令行工具

开发命令

# 类型检查（全仓）
npm run typecheck

# 运行所有测试
npm test

# 运行单个包的测试
npm test --workspace=packages/core
npm test --workspace=packages/daemon
npm test --workspace=packages/cli

# 构建
npm run build

# 本地开发（cli 链接到全局）
cd packages/cli && npm link
# 然后可以在任何目录使用 visionl 命令

代码规范

命名

文件名：kebab-case（browser-manager.ts）
变量/函数：camelCase（pageRegistry、getPageInfo）
类型/接口：PascalCase（PageInfo、ApiResponse）
常量：UPPER_SNAKE_CASE（DEFAULT_PORT）

TypeScript

严格模式 (strict: true)
禁止 any（必须显式类型）
导出类型使用 interface 而非 type（可扩展性更好）

注释

文件头简述文件职责（中英双语一行）
公共 API 必须有 JSDoc
不写废话注释（不解释显而易见的代码）

日志

Daemon 和 CLI 使用统一的日志层级：

DEBUG：调试信息（带上下文）
INFO：关键状态变更（页面打开/关闭/崩溃）
WARN：可恢复的异常
ERROR：需要关注的错误

生产环境默认 INFO 级别，开发模式可设为 DEBUG。

测试规范

使用 vitest 作为测试框架
测试文件放在 src/__tests__/ 目录下
文件命名：*.test.ts
每个 PR 必须包含相关测试
集成测试放在 packages/daemon/src/__tests__/integration/

Git 工作流

main：稳定发布分支
dev：开发分支（日常开发在此）
功能分支：feature/xxx
修复分支：fix/xxx

Commit 规范

遵循 Conventional Commits：

feat: 添加页面截图功能
fix: 修复 daemon 端口冲突时的错误提示
docs: 更新 API 文档
test: 添加 CLI 自动拉起单元测试
refactor: 重构 page-registry 为 Map 实现

反检测开发规范

这是 VisionL 最核心的质量要求。任何新功能不能降低反检测评分。

原则

GUI 浏览器所有可被页面 JS 读取的属性，VisionL 都必须有真实值（或模拟值）
禁止暴露任何 navigator.webdriver、--headless、Playwright/Puppeteer 痕迹
每个 stealth 模块必须先写测试，验证目标属性值符合真实浏览器

检测站点验证

每次版本发布前，必须通过以下站点验证：

站点	指标
https://bot.sannysoft.com	全部绿条
https://abrahamjuliot.github.io/creepjs/	所有维度分数 ≤ 30% 异常
https://fingerprint.com/demo	访客置信度显示为正常浏览器（非 bot）

新增 Stealth 模块 Checklist

确认需要覆盖的 JS API / 属性
在真实 Chrome GUI 中抓取基准值
实现模块，写入 daemon/src/stealth/
写测试验证模拟值与基准值一致
在三个检测站点验证未被降级

发布流程

功能开发在 dev 分支
测试全过后合并到 main
打 tag：v1.0.0
发布到 npm

JSON 转义规范

所有返回给外部的 JSON 必须通过 JSON.stringify 序列化，禁止以下写法：

// ❌ 禁止
`{"ok":true,"text":"${pageText}"}`

// ✅ 正确
JSON.stringify({ ok: true, text: pageText })

页面内容（文本、HTML）中可能包含任意字符，手动拼接必然导致 JSON 非法。

3.9 KiB Raw Blame History Unescape Escape