# 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 非法。