AskaEth
0c437a96f1
- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略） - api.md: REST + WebSocket 接口文档 - cli.md: CLI 命令参考 - contributing.md: 开发规范与 JSON 转义要求 - quickstart.md: 快速开始指南 - llm-integration.md: 智能体集成指南 - examples.md: 8 个典型使用场景
137 lines
2.8 KiB
Markdown
137 lines
2.8 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/ # 共享类型、HTTP 客户端、工具函数
|
||
├── daemon/ # 后台守护进程
|
||
└── 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 实现
|
||
```
|
||
|
||
## 发布流程
|
||
|
||
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 非法。
|