Files

T

AskaEth 0c437a96f1 docs: 项目架构设计文档（中文）及使用指南

- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略）
- api.md: REST + WebSocket 接口文档
- cli.md: CLI 命令参考
- contributing.md: 开发规范与 JSON 转义要求
- quickstart.md: 快速开始指南
- llm-integration.md: 智能体集成指南
- examples.md: 8 个典型使用场景

2026-08-12 20:14:54 +08:00

2.8 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/        # 共享类型、HTTP 客户端、工具函数
├── daemon/      # 后台守护进程
└── 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 实现

发布流程

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

JSON 转义规范

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

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

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

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

2.8 KiB Raw Blame History Unescape Escape