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

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

docs/development/contributing.md

@@ -0,0 +1,136 @@
+# 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 非法。