opencroc 1.8.3 → 1.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.ja.md +383 -386
  2. package/README.md +383 -417
  3. package/README.zh-CN.md +383 -414
  4. package/dist/cli/index.js +24 -8
  5. package/dist/cli/index.js.map +1 -1
  6. package/package.json +1 -1
package/README.zh-CN.md CHANGED
@@ -1,414 +1,383 @@
1
- <p align="center">
2
- <img src="assets/banner.png" alt="OpenCroc 横幅" width="820" />
3
- </p>
4
-
5
- <h1 align="center">OpenCroc</h1>
6
-
7
- <p align="center">
8
- <strong>AI 原生 E2E 测试框架：读取你的源码、自动生成测试、并可自愈失败。</strong>
9
- </p>
10
-
11
- <p align="center">
12
- <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
13
- <a href="https://github.com/opencroc/opencroc/actions/workflows/ci.yml"><img src="https://github.com/opencroc/opencroc/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
14
- <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
15
- <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
16
- </p>
17
-
18
- <p align="center">
19
- <a href="README.en.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
20
- </p>
21
-
22
- ---
23
-
24
- ## OpenCroc 是什么？
25
-
26
- OpenCroc 是一个构建在 [Playwright](https://playwright.dev) 之上的 **AI 原生端到端测试框架**。你不需要手写大量脚本，OpenCroc 会**读取后端源码**（模型、控制器、DTO），并自动生成完整 E2E 测试套件，包括 API 调用链、种子数据、请求体与断言。
27
-
28
- 当测试失败时，OpenCroc 不只是报错，而是会沿完整请求链路**定位根因**、**生成修复补丁**，并**自动回归验证**修复结果。
29
-
30
- ### 核心能力
31
-
32
- | 能力 | 说明 |
33
- |---|---|
34
- | **源码感知测试生成** | 通过 [ts-morph](https://ts-morph.com) 解析 Sequelize/TypeORM 模型、Express/NestJS 控制器、DTO 装饰器，识别 API 面 |
35
- | **AI 配置生成** | 使用 LLM 生成请求模板、种子数据、参数映射，并通过三层校验（schema -> semantic -> dry-run） |
36
- | **智能调用链规划** | 构建 API 依赖 DAG，做拓扑排序并以贪心策略提升覆盖率 |
37
- | **日志驱动完成判定** | 超越 `networkidle`，通过后端日志（`api_exec end`）确认请求真正完成 |
38
- | **失败链路归因** | 从网络异常 -> 慢接口 -> 后端日志逐层追踪，定位根因 |
39
- | **可控自愈机制** | `backup -> AI patch -> dry-run -> apply -> re-run -> verify -> rollback`，每步有安全闸门 |
40
- | **影响面分析** | 基于外键关系做 BFS 传播分析，自动输出 Mermaid 图 |
41
-
42
- ## 快速开始
43
-
44
- ### 前置要求
45
-
46
- - Node.js >= 18
47
- - 使用 Express/NestJS + Sequelize/TypeORM 的后端项目
48
-
49
- ### 安装
50
-
51
- ```bash
52
- npm install opencroc --save-dev
53
- ```
54
-
55
- ### 初始化
56
-
57
- ```bash
58
- npx opencroc init
59
- ```
60
-
61
- 该命令会：
62
- 1. 扫描项目结构
63
- 2. 识别 ORM 与后端框架
64
- 3. 生成默认 `opencroc.config.ts`
65
- 4. 生成一套示例测试
66
-
67
- ### 生成测试
68
-
69
- ```bash
70
- # 为单个模块生成测试
71
- npx opencroc generate --module=knowledge-base
72
-
73
- # 为所有模块生成测试
74
- npx opencroc generate --all
75
-
76
- # 仅预览，不落盘
77
- npx opencroc generate --all --dry-run
78
- ```
79
-
80
- ### 运行测试
81
-
82
- ```bash
83
- # 运行全部生成的测试
84
- npx opencroc test
85
-
86
- # 运行指定模块
87
- npx opencroc test --module=knowledge-base
88
-
89
- # 启用自愈运行
90
- npx opencroc test --self-heal
91
- ```
92
-
93
- ### 校验 AI 配置
94
-
95
- ```bash
96
- # 校验所有生成配置
97
- npx opencroc validate --all
98
-
99
- # 比较两份报告差异
100
- npx opencroc compare --baseline=report-a.json --current=report-b.json
101
- ```
102
-
103
- ### 启动 OpenCroc Studio
104
-
105
- OpenCroc Studio 是一个**像素风鳄鱼办公室** + 实时**知识图谱** UI。它在本地启动一个 Web 服务器，可视化展示项目结构、Agent 状态和测试结果。
106
-
107
- ```bash
108
- # 启动 Studio（自动打开浏览器 http://localhost:8765）
109
- npx opencroc serve
110
-
111
- # 自定义端口
112
- npx opencroc serve --port 3000
113
-
114
- # 不自动打开浏览器
115
- npx opencroc serve --no-open
116
-
117
- # 指定 host（如远程访问）
118
- npx opencroc serve --host 0.0.0.0 --port 8765
119
- ```
120
-
121
- Studio 功能：
122
- - **知识图谱画布** — 项目模型、控制器、API 关系的可交互图谱（拖拽、缩放、悬停提示）
123
- - **像素鳄鱼办公室** — 6 只 AI 鳄鱼 Agent（解析鳄 🐊、分析鳄 🐊、测试鳄 🐊、修复鳄 🐊、规划鳄 🐊、汇报鳄 🐊），带实时状态动画
124
- - **实时 WebSocket** — Agent 状态和图谱变化即时推送到浏览器
125
- - **模块侧边栏** — 一目了然浏览已发现的模块和 Agent 状态
126
- - **REST API** — `GET /api/project`（图谱数据）、`GET /api/agents`（Agent 状态）、`POST /api/project/refresh`（重新扫描）
127
-
128
- ### 完整流水线（一条命令）
129
-
130
- ```bash
131
- # 一键运行：generate → execute → analyze → heal → report
132
- npx opencroc run
133
-
134
- # 带选项
135
- npx opencroc run --module=users --self-heal --report html,json
136
- ```
137
-
138
- ### CI/CD 集成
139
-
140
- ```bash
141
- # 生成 GitHub Actions 工作流
142
- npx opencroc ci --platform github
143
-
144
- # 生成 GitLab CI 管道
145
- npx opencroc ci --platform gitlab --self-heal
146
- ```
147
-
148
- ### Dashboard 与报告
149
-
150
- ```bash
151
- # 生成可视化 Dashboard
152
- npx opencroc dashboard
153
-
154
- # 生成多格式报告
155
- npx opencroc report --format html,json,markdown
156
- ```
157
-
158
- ## 架构
159
-
160
- ```
161
- ┌─────────────────────────────────────────────────────────────┐
162
- │ OpenCroc Studio (localhost:8765) │
163
- │ 像素鳄鱼办公室 + 知识图谱 + WebSocket │
164
- ├─────────────────────────────────────────────────────────────┤
165
- │ CLI / Orchestrator │
166
- ├──────────┬──────────┬──────────┬──────────┬─────────────────┤
167
- │ Source │ Chain │ Test │ Execution│ Self-Healing │
168
- │ Parser │ Planner │Generator │ Engine │ Engine │
169
- │ │ │ │ │ │
170
- │ ts-morph │ DAG + │ Template │Playwright│ AI Attribution │
171
- │ Model │ Topo │ + AI │ + Log │ + Controlled │
172
- │ Controller│ Sort + │ Config │ Driven │ Fix + Verify │
173
- │ DTO │ Greedy │ Merge │ Assert │ + Rollback │
174
- ├──────────┴──────────┴──────────┴──────────┴─────────────────┤
175
- │ Observation Bus (Network + Backend Logs) │
176
- ├──────────────────────────────────────────────────────────────┤
177
- │ Report Engine (HTML / JSON / Markdown) │
178
- └──────────────────────────────────────────────────────────────┘
179
- ```
180
-
181
- ### 6 阶段流水线
182
-
183
- ```
184
- Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
185
- │ │ │ │ │ │
186
- ts-morph Mermaid Dependency Topological Playwright + Root Cause +
187
- parsing erDiagram DAG builder + greedy AI body/seed Impact map
188
- ```
189
-
190
- ## 工作原理
191
-
192
- ### 1. 源码解析
193
-
194
- OpenCroc 基于 [ts-morph](https://ts-morph.com) 做静态分析：
195
-
196
- - **Models**：从 Sequelize `Model.init()` / TypeORM `@Entity()` 提取表名、字段类型、索引、外键
197
- - **Controllers**：从 Express `router.get/post/put/delete` 提取路由、HTTP 方法、路径参数
198
- - **DTOs**：从 `@IsString()`、`@IsNumber()`、`@IsOptional()` 装饰器提取校验规则
199
-
200
- ### 2. AI 配置生成
201
-
202
- 每个模块都会调用 LLM（OpenAI / 智谱 / 任意 OpenAI 兼容 API）生成：
203
-
204
- - **请求体模板**：字段级精确的 POST/PUT payload
205
- - **种子数据**：`beforeAll` 的初始化步骤与正确调用顺序
206
- - **参数映射**：路径参数别名（`/:id` -> `categoryId`）
207
- - **ID 别名**：避免多资源链路中的 ID 冲突
208
-
209
- 每份配置都要通过 **3 层校验**：
210
- 1. **Schema 校验**：JSON 结构完整性
211
- 2. **语义校验**：字段值是否与源码元数据一致
212
- 3. **Dry-run 校验**：TypeScript 编译检查
213
-
214
- 若校验失败，会在落盘前自动修复（最多 3 轮）。
215
-
216
- ### 3. 日志驱动完成判定
217
-
218
- 不依赖脆弱的 `networkidle`：
219
-
220
- ```
221
- Frontend Request -> Backend api_exec start log -> Backend processing -> api_exec end log
222
- ↓
223
- OpenCroc polls end logs to confirm completion
224
- ```
225
-
226
- 这能覆盖“前端看起来空闲、后端仍在处理”的场景。
227
-
228
- ### 4. 自愈闭环
229
-
230
- ```
231
- Test Failure
232
- -> AI Attribution (LLM + heuristic fallback)
233
- -> Generate Fix Patch
234
- -> Dry-Run Validation
235
- -> Apply Patch (with backup)
236
- -> Re-run Failed Tests
237
- -> Verify Fix
238
- -> Commit or Rollback
239
- ```
240
-
241
- ## 真实项目验证
242
-
243
- OpenCroc 已在一套**生产级 RBAC 系统**（多租户企业权限管理）上完成验证，涵盖 100+ Sequelize 模型、75+ Express 控制器、以及模型文件内嵌的关联声明：
244
-
245
- ```
246
- $ npx tsx examples/rbac-system/smoke-test.ts
247
-
248
- Modules : 5 (default, aigc, data-platform, integration, workflow)
249
- ER Diagrams : 5
250
- [default] 102 tables, 65 relations
251
- [aigc] 6 tables, 0 relations
252
- [data-platform] 4 tables, 0 relations
253
- [integration] 14 tables, 0 relations
254
- [workflow] 2 tables, 0 relations
255
- Chain Plans : 5
256
- [aigc] 78 chains, 150 steps
257
- Generated Files: 78
258
- Duration : 1153ms
259
- ```
260
-
261
- 关键发现：
262
- - 从扁平模型布局中正确提取了 **102 张表** 和 **65 条外键关系**
263
- - 无需独立 association 文件，直接检测模型文件中的**嵌入式关联**（`.belongsTo()` / `.hasMany()`）
264
- - 5 个模块共生成 **78 个测试文件**，耗时仅 1 秒出头
265
- - 同时兼容扁平（`models/*.ts`）和嵌套（`models/module/*.ts`）目录结构
266
-
267
- ## 配置示例
268
-
269
- ```typescript
270
- // opencroc.config.ts
271
- import { defineConfig } from 'opencroc';
272
-
273
- export default defineConfig({
274
- // 后端源码路径
275
- backend: {
276
- modelsDir: 'src/models',
277
- controllersDir: 'src/controllers',
278
- servicesDir: 'src/services',
279
- },
280
-
281
- // 目标应用
282
- baseUrl: 'http://localhost:3000',
283
- apiBaseUrl: 'http://localhost:3000/api',
284
-
285
- // AI 配置
286
- ai: {
287
- provider: 'openai', // 'openai' | 'zhipu' | 'custom'
288
- apiKey: process.env.AI_API_KEY,
289
- model: 'gpt-4o-mini',
290
- },
291
-
292
- // 测试执行
293
- execution: {
294
- workers: 4,
295
- timeout: 30_000,
296
- retries: 1,
297
- },
298
-
299
- // 日志驱动完成判定（需后端埋点）
300
- logCompletion: {
301
- enabled: true,
302
- endpoint: '/internal/test-logs',
303
- pollIntervalMs: 500,
304
- timeoutMs: 10_000,
305
- },
306
-
307
- // 自愈
308
- selfHealing: {
309
- enabled: false,
310
- fixScope: 'config-only', // 'config-only' | 'config-and-source'
311
- maxFixRounds: 3,
312
- dryRunFirst: true,
313
- },
314
- });
315
- ```
316
-
317
- ## 支持的技术栈
318
-
319
- | 层级 | 已支持 | 规划中 |
320
- |---|---|---|
321
- | **ORM** | Sequelize, TypeORM, Prisma, Drizzle | — |
322
- | **Framework** | Express | NestJS, Fastify, Koa |
323
- | **Test Runner** | Playwright | — |
324
- | **LLM** | OpenAI, ZhiPu (GLM), Ollama (local) | Anthropic |
325
- | **Database** | MySQL, PostgreSQL | SQLite, MongoDB |
326
-
327
- ## 对比
328
-
329
- | 功能 | OpenCroc | Playwright | Metersphere | auto-playwright |
330
- |---|---|---|---|---|
331
- | 源码感知生成 | ✅ | ❌ | ❌ | ❌ |
332
- | AI 配置生成 + 校验 | ✅ | ❌ | ❌ | ❌ |
333
- | 日志驱动完成判定 | ✅ | ❌ | ❌ | ❌ |
334
- | 失败链路归因 | ✅ | ❌ | 部分 | ❌ |
335
- | 自愈 + 回滚 | ✅ | ❌ | ❌ | ❌ |
336
- | API 依赖 DAG | ✅ | ❌ | ❌ | ❌ |
337
- | 零配置测试生成 | ✅ | 仅 codegen | 手工 | NL->action |
338
- | 影响面分析 | ✅ | ❌ | ❌ | ❌ |
339
-
340
- ## Roadmap
341
-
342
- - [x] 6-stage source-to-test pipeline
343
- - [x] AI configuration generation with 3-layer validation
344
- - [x] Controlled self-healing loop
345
- - [x] Log-driven completion detection
346
- - [x] Failure chain attribution + impact analysis
347
- - [x] TypeORM / Prisma adapter
348
- - [x] Ollama local LLM support
349
- - [x] Real-world validation (102 tables, 65 relations, 78 generated tests)
350
- - [x] GitHub Actions / GitLab CI integration
351
- - [x] VS Code extension scaffold
352
- - [x] Plugin system
353
- - [x] HTML / JSON / Markdown report generation
354
- - [x] NestJS controller parser
355
- - [x] Visual dashboard (opencroc.com)
356
- - [x] Drizzle ORM adapter
357
- - [x] AI Config Suggester + Enhanced DTO-aware Suggester
358
- - [x] Auto-Fixer（4 策略：接口路径匹配、DTO 字段填充、种子依赖排序、参数映射修复）
359
- - [x] 三层配置验证（schema → semantic → dry-run）
360
- - [x] DTO Parser（ts-morph 接口解析 + express-validator 规则提取）
361
- - [x] Baseline Comparator（Playwright 报告 diff + 回归检测）
362
- - [x] 模块配置预设加载器
363
- - [x] LLM 增强链路规划器
364
- - [x] Runtime 基础设施（Playwright 配置生成、认证 Setup、Teardown、网络监控）
365
- - [x] 全流程编排管道
366
- - [x] 高级报告系统（检查清单、工单生成、Token 追踪）
367
- - [x] OpenCroc Studio — 像素鳄鱼办公室 + 知识图谱 UI（`opencroc serve`）
368
-
369
- ## 发布快照
370
-
371
- - 当前稳定版本：`1.3.0`
372
- - npm `latest` 标签：`1.3.0`
373
- - Roadmap 状态：M1 Studio 已交付
374
- - 全量质量门禁：34 个测试文件 / 373 个测试通过（Node.js 20.x & 22.x）
375
-
376
- ### 版本节奏
377
-
378
- - `0.3.x`：插件系统、CI 模板、报告系统、VS Code 脚手架、CI 稳定化
379
- - `0.4.x`：NestJS 控制器解析
380
- - `0.5.x`：Drizzle ORM 适配器
381
- - `0.6.x`：可视化 dashboard 与 Windows 下 Vitest 稳定性收口
382
- - `0.7.x – 0.9.x`：Runtime 基础设施（Playwright 生成器、认证、日志驱动检测、规则引擎）
383
- - `1.0.0`：全流程编排管道
384
- - `1.1.0`：高级自愈（对话循环、可控修复器、自动修复 PR 生成）
385
- - `1.2.0`：高级报告系统 + Sprint 0-3 迁移完成
386
- - `1.3.0`：OpenCroc Studio M1 — Fastify 服务器、知识图谱 API、像素鳄鱼办公室前端
387
-
388
- ### 发布验证
389
-
390
- ```bash
391
- npm run lint
392
- npm run typecheck
393
- npm test
394
- npm view opencroc version dist-tags --json
395
- ```
396
-
397
- ## 文档
398
-
399
- 访问 **[opencroc.com](https://opencroc.com)** 查看完整文档，或阅读：
400
-
401
- - [Architecture Guide](docs/architecture.md)
402
- - [Configuration Reference](docs/configuration.md)
403
- - [Backend Instrumentation Guide](docs/backend-instrumentation.md)
404
- - [AI Provider Setup](docs/ai-providers.md)
405
- - [Self-Healing Guide](docs/self-healing.md)
406
- - [Troubleshooting](docs/troubleshooting.md)
407
-
408
- ## 贡献
409
-
410
- 欢迎贡献代码与文档。请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。
411
-
412
- ## License
413
-
414
- [MIT](LICENSE) © 2026 OpenCroc Contributors
1
+ <p align="center">
2
+ <img src="assets/banner.png" alt="OpenCroc 横幅" width="820" />
3
+ </p>
4
+
5
+ <h1 align="center">OpenCroc</h1>
6
+
7
+ <p align="center">
8
+ <strong>AI 原生 E2E 测试框架：读取源码、生成测试，并对失败进行自愈。</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
13
+ <a href="https://github.com/opencroc/opencroc/actions/workflows/ci.yml"><img src="https://github.com/opencroc/opencroc/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
14
+ <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
15
+ <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
20
+ </p>
21
+
22
+ ---
23
+
24
+ ## OpenCroc 是什么？
25
+
26
+ OpenCroc 是一个构建在 [Playwright](https://playwright.dev) 之上的 AI 原生端到端测试框架。它不要求你手写大量测试脚本，而是直接读取后端源码，理解模型、控制器、DTO 与关系后，自动生成完整的 E2E 测试套件，包括种子数据、请求体、API 调用链和断言。
27
+
28
+ 当测试失败时，OpenCroc 不只是输出报错。它会沿着请求链路追踪问题，归因可能的根因，生成修复建议，并在受控流程中重新执行验证。
29
+
30
+ ## 核心能力
31
+
32
+ | 能力 | 说明 |
33
+ | --- | --- |
34
+ | 源码感知生成 | 解析 Sequelize、TypeORM、Prisma、Drizzle 结构，识别模块、模型、路由与 DTO |
35
+ | AI 配置生成 | 生成请求模板、种子数据计划、参数映射与测试脚手架，并经过校验 |
36
+ | 调用链规划 | 构建依赖 DAG，规划更高覆盖率的 API 执行顺序 |
37
+ | 日志驱动完成判定 | 不只依赖 `networkidle`，还能结合后端执行信号判断是否真正完成 |
38
+ | 失败归因 | 关联前端请求、后端日志与依赖链路，定位问题来源 |
39
+ | 受控自愈 | 支持 backup、patch、dry-run、re-run、verify、rollback 等闭环 |
40
+ | 可视化 Studio | 提供本地 Web UI，用于图谱探索、Agent 状态观察和像素办公室展示 |
41
+
42
+ ## 快速开始
43
+
44
+ ### 前置要求
45
+
46
+ - Node.js 18 或更高版本
47
+ - 使用 Express 或 NestJS 的后端项目
48
+ - 使用受支持的 ORM 或模式结构
49
+
50
+ ### 安装
51
+
52
+ ```bash
53
+ npm install opencroc --save-dev
54
+ ```
55
+
56
+ ### 初始化
57
+
58
+ ```bash
59
+ npx opencroc init
60
+ ```
61
+
62
+ 这条命令会：
63
+
64
+ 1. 扫描项目结构
65
+ 2. 识别框架与 ORM 特征
66
+ 3. 创建 `opencroc.config.ts`
67
+ 4. 生成起步用的输出结构
68
+
69
+ ### 生成测试
70
+
71
+ ```bash
72
+ # 为单个模块生成测试
73
+ npx opencroc generate --module=knowledge-base
74
+
75
+ # 为所有检测到的模块生成测试
76
+ npx opencroc generate --all
77
+
78
+ # 仅预览，不落盘
79
+ npx opencroc generate --all --dry-run
80
+ ```
81
+
82
+ ### 运行测试
83
+
84
+ ```bash
85
+ # 运行全部生成的测试
86
+ npx opencroc test
87
+
88
+ # 运行单个模块
89
+ npx opencroc test --module=knowledge-base
90
+
91
+ # 以 headed 模式运行
92
+ npx opencroc test --headed
93
+
94
+ # 通过 CLI 覆盖生命周期钩子
95
+ npx opencroc test --setup-hook="npm run e2e:setup" --auth-hook="node scripts/auth.js" --teardown-hook="npm run e2e:cleanup"
96
+ ```
97
+
98
+ ### 校验 AI 配置
99
+
100
+ ```bash
101
+ npx opencroc validate --all
102
+ npx opencroc compare --baseline=report-a.json --current=report-b.json
103
+ ```
104
+
105
+ ## OpenCroc Studio
106
+
107
+ OpenCroc Studio 是 OpenCroc 的本地可视化工作台。它把知识图谱视图、像素办公室运营视图和 3D 办公室运行时整合在一个由 CLI 启动的 Web 体验中。
108
+
109
+ ### 启动 Studio
110
+
111
+ ```bash
112
+ # 启动 Studio 并打开浏览器
113
+ npx opencroc serve
114
+
115
+ # 自定义端口
116
+ npx opencroc serve --port 3000
117
+
118
+ # 禁止自动打开浏览器
119
+ npx opencroc serve --no-open
120
+
121
+ # 绑定公开 host
122
+ npx opencroc serve --host 0.0.0.0 --port 8765
123
+ ```
124
+
125
+ ### 当前 Web 架构
126
+
127
+ - Fastify 提供本地 Studio 应用与 API 服务
128
+ - 前端是单入口 Vite SPA
129
+ - 主路由为 `/`、`/studio`、`/pixel`
130
+ - Web 源码位于 `src/web`，按 `app`、`pages`、`features`、`shared`、`styles`、`public` 分层
131
+ - 历史入口如 `/index-studio.html`、`/index-v2-pixel.html` 会被重定向到 SPA 路由
132
+
133
+ ### Studio 能力
134
+
135
+ - 模块、API 与关系的知识图谱画布
136
+ - 展示 Agent 活动的像素办公室仪表盘
137
+ - 用于沉浸式监控的 3D 办公室运行时视图
138
+ - 基于 WebSocket 的实时状态更新
139
+ - 支持路由切换的侧边导航
140
+ - REST 接口，例如 `GET /api/project`、`GET /api/agents`、`POST /api/project/refresh`
141
+
142
+ ## 完整流水线
143
+
144
+ ```bash
145
+ # 执行完整流水线
146
+ npx opencroc run
147
+
148
+ # 对单个模块启用自愈并输出报告
149
+ npx opencroc run --module=users --self-heal --report html,json
150
+ ```
151
+
152
+ ## CI/CD 集成
153
+
154
+ ```bash
155
+ npx opencroc ci --platform github
156
+ npx opencroc ci --platform gitlab --self-heal
157
+ ```
158
+
159
+ ## Dashboard 与报告
160
+
161
+ ```bash
162
+ npx opencroc dashboard
163
+ npx opencroc report --format html,json,markdown
164
+ ```
165
+
166
+ ## 架构
167
+
168
+ ```text
169
+ +-------------------------------------------------------------------+
170
+ | OpenCroc Studio |
171
+ | Fastify 服务 + 单入口 Vite SPA + WebSocket 更新 |
172
+ | 路由：/, /studio, /pixel |
173
+ +-------------------------------------------------------------------+
174
+ | CLI / Orchestrator |
175
+ +--------------+--------------+---------------+----------------------+
176
+ | 源码解析 | 链路规划 | 测试生成 | 执行 / 观察 |
177
+ +--------------+--------------+---------------+----------------------+
178
+ | 自愈 | 影响分析 | 报告输出 | Dashboard / Studio |
179
+ +--------------+--------------+---------------+----------------------+
180
+ ```
181
+
182
+ ### 6 阶段流水线
183
+
184
+ ```text
185
+ Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
186
+ ```
187
+
188
+ ## 工作原理
189
+
190
+ ### 1. 源码解析
191
+
192
+ OpenCroc 使用 [ts-morph](https://ts-morph.com) 以及框架感知解析器来分析：
193
+
194
+ - 模型与关系
195
+ - 控制器与路由
196
+ - DTO 字段与校验规则
197
+ - 模块边界与依赖面
198
+
199
+ ### 2. AI 配置生成
200
+
201
+ 针对每个模块，OpenCroc 可以生成：
202
+
203
+ - 请求体模板
204
+ - 种子数据计划
205
+ - 参数映射
206
+ - ID 别名规则
207
+
208
+ 每份配置都要经过以下校验：
209
+
210
+ 1. Schema 校验
211
+ 2. 语义校验
212
+ 3. Dry-run 校验
213
+
214
+ ### 3. 日志驱动完成判定
215
+
216
+ OpenCroc 不只依赖浏览器空闲信号，还能结合后端完成信号来判断请求是否真正结束。
217
+
218
+ ### 4. 自愈闭环
219
+
220
+ ```text
221
+ Test Failure
222
+ -> Attribution
223
+ -> Proposed Fix
224
+ -> Dry-Run Validation
225
+ -> Apply Patch
226
+ -> Re-run
227
+ -> Verify
228
+ -> Rollback if needed
229
+ ```
230
+
231
+ ## 真实项目验证
232
+
233
+ OpenCroc 已在一个生产风格的 RBAC 系统上完成验证，项目包含 100+ Sequelize 模型、数十个控制器以及嵌入式关联定义。
234
+
235
+ ```bash
236
+ $ npx tsx examples/rbac-system/smoke-test.ts
237
+
238
+ Modules : 5
239
+ ER Diagrams : 5
240
+ Chain Plans : 5
241
+ Generated Files: 78
242
+ Duration : 1153ms
243
+ ```
244
+
245
+ 关键结果：
246
+
247
+ - 从扁平模型布局中提取出 102 张表与 65 条外键关系
248
+ - 无需单独 association 文件即可识别嵌入式关联
249
+ - 在 5 个模块上生成了 78 个测试文件
250
+ - 同时兼容扁平与嵌套目录结构
251
+
252
+ ## 配置示例
253
+
254
+ ```typescript
255
+ import { defineConfig } from 'opencroc';
256
+
257
+ export default defineConfig({
258
+ backend: {
259
+ modelsDir: 'src/models',
260
+ controllersDir: 'src/controllers',
261
+ servicesDir: 'src/services',
262
+ },
263
+
264
+ baseUrl: 'http://localhost:3000',
265
+ apiBaseUrl: 'http://localhost:3000/api',
266
+
267
+ ai: {
268
+ provider: 'openai',
269
+ apiKey: process.env.AI_API_KEY,
270
+ model: 'gpt-4o-mini',
271
+ },
272
+
273
+ execution: {
274
+ workers: 4,
275
+ timeout: 30_000,
276
+ retries: 1,
277
+ },
278
+
279
+ logCompletion: {
280
+ enabled: true,
281
+ endpoint: '/internal/test-logs',
282
+ pollIntervalMs: 500,
283
+ timeoutMs: 10_000,
284
+ },
285
+
286
+ selfHealing: {
287
+ enabled: false,
288
+ fixScope: 'config-only',
289
+ maxFixRounds: 3,
290
+ dryRunFirst: true,
291
+ },
292
+ });
293
+ ```
294
+
295
+ ## 支持的技术栈
296
+
297
+ | 层 | 已支持 | 计划中 |
298
+ | --- | --- | --- |
299
+ | ORM | Sequelize, TypeORM, Prisma, Drizzle | 视需求继续扩展 |
300
+ | Framework | Express | NestJS, Fastify, Koa |
301
+ | Test Runner | Playwright | 更多运行器 |
302
+ | LLM | OpenAI, ZhiPu, Ollama | Anthropic |
303
+ | Database | MySQL, PostgreSQL | SQLite, MongoDB |
304
+
305
+ ## 对比
306
+
307
+ | 功能 | OpenCroc | Playwright | Metersphere | auto-playwright |
308
+ | --- | --- | --- | --- | --- |
309
+ | 源码感知生成 | Yes | No | No | No |
310
+ | AI 配置生成与校验 | Yes | No | No | No |
311
+ | 日志驱动完成判定 | Yes | No | No | No |
312
+ | 失败归因 | Yes | No | Partial | No |
313
+ | 自愈与回滚 | Yes | No | No | No |
314
+ | API 依赖 DAG | Yes | No | No | No |
315
+ | 零配置测试生成 | Yes | Limited | Manual | Prompt-driven |
316
+ | 影响分析 | Yes | No | No | No |
317
+
318
+ ## 路线图
319
+
320
+ - [x] 6 阶段源码到测试流水线
321
+ - [x] AI 配置生成与校验
322
+ - [x] 受控自愈闭环
323
+ - [x] 日志驱动完成判定
324
+ - [x] 失败归因与影响分析
325
+ - [x] Prisma 与 Drizzle 适配
326
+ - [x] Ollama 本地模型支持
327
+ - [x] CI 集成
328
+ - [x] VS Code 插件脚手架
329
+ - [x] 插件系统
330
+ - [x] HTML、JSON、Markdown 报告
331
+ - [x] 可视化 Studio 仪表盘
332
+ - [x] Runtime 基础设施
333
+ - [x] 全流程编排
334
+ - [x] 高级报告系统
335
+ - [x] OpenCroc Studio 路由化 Web 应用
336
+
337
+ ## 版本快照
338
+
339
+ - 本文档对应的产品快照：`1.8.3`
340
+ - Studio 架构快照：Fastify + 单入口 Vite SPA + 路由视图
341
+ - 主 Studio 路由：`/`、`/studio`、`/pixel`
342
+ - 全量质量门禁：41 个测试文件、414 个测试通过
343
+
344
+ ### 版本节奏
345
+
346
+ - `0.3.x`：插件系统、CI 模板、报告系统、VS Code 脚手架
347
+ - `0.4.x`：NestJS 控制器解析器
348
+ - `0.5.x`：Drizzle ORM 适配
349
+ - `0.6.x`：可视化 dashboard 与 Windows Vitest 稳定性工作
350
+ - `0.7.x - 0.9.x`：runtime 基础设施、认证、日志驱动检测、规则引擎
351
+ - `1.0.0`：全流程编排管道
352
+ - `1.1.0`：高级自愈
353
+ - `1.2.0`：高级报告与迁移工作
354
+ - `1.3.0`：OpenCroc Studio M1
355
+ - `1.8.3`：Vite SPA 路由化、web 架构整理、发包瘦身
356
+
357
+ ### 发布验证
358
+
359
+ ```bash
360
+ npm run lint
361
+ npm run typecheck
362
+ npm test
363
+ npm view opencroc version dist-tags --json
364
+ ```
365
+
366
+ ## 文档
367
+
368
+ 访问 **[opencroc.com](https://opencroc.com)** 获取更多文档，也可以查看：
369
+
370
+ - [Architecture Guide](docs/architecture.md)
371
+ - [Configuration Reference](docs/configuration.md)
372
+ - [Backend Instrumentation Guide](docs/backend-instrumentation.md)
373
+ - [AI Provider Setup](docs/ai-providers.md)
374
+ - [Self-Healing Guide](docs/self-healing.md)
375
+ - [Troubleshooting](docs/troubleshooting.md)
376
+
377
+ ## 贡献
378
+
379
+ 欢迎贡献代码与文档。请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。
380
+
381
+ ## 许可证
382
+
383
+ [MIT](LICENSE) Copyright 2026 OpenCroc Contributors