AskaEth
985860b2a2
- architecture.md: 新增反检测为核心第一性原理，新增 §3 反检测设计（13 个指纹维度全覆盖） - anti-detection.md: 新增反检测专项文档（14 节，详尽列举检测方式和应对策略） - api.md: POST /pages 新增 profile 参数，新增 GET /profiles 端点 - cli.md: 新增 --profile 全局选项，新增 visionl profiles 命令 - contributing.md: 新增反检测开发规范、检测站点验证要求 - README.md: 更新项目定位和特性描述
165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
# VisionL 开发规范
|
||
|
||
## 环境要求
|
||
|
||
- Node.js >= 18
|
||
- npm >= 9
|
||
- Git
|
||
|
||
## 克隆与安装
|
||
|
||
```bash
|
||
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/ # 命令行工具
|
||
```
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
# 类型检查（全仓）
|
||
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
|
||
|
||
1. 确认需要覆盖的 JS API / 属性
|
||
2. 在真实 Chrome GUI 中抓取基准值
|
||
3. 实现模块，写入 `daemon/src/stealth/`
|
||
4. 写测试验证模拟值与基准值一致
|
||
5. 在三个检测站点验证未被降级
|
||
|
||
## 发布流程
|
||
|
||
1. 功能开发在 `dev` 分支
|
||
2. 测试全过后合并到 `main`
|
||
3. 打 tag：`v1.0.0`
|
||
4. 发布到 npm
|
||
|
||
---
|
||
|
||
## JSON 转义规范
|
||
|
||
所有返回给外部的 JSON 必须通过 `JSON.stringify` 序列化，禁止以下写法：
|
||
|
||
```typescript
|
||
// ❌ 禁止
|
||
`{"ok":true,"text":"${pageText}"}`
|
||
|
||
// ✅ 正确
|
||
JSON.stringify({ ok: true, text: pageText })
|
||
```
|
||
|
||
页面内容（文本、HTML）中可能包含任意字符，手动拼接必然导致 JSON 非法。
|