{"id":47922769,"url":"https://github.com/jeffkit/argusai","last_synced_at":"2026-04-04T06:18:52.322Z","repository":{"id":340740636,"uuid":"1156312089","full_name":"jeffkit/argusai","owner":"jeffkit","description":"Generic Docker E2E Testing Toolkit - Config-driven Docker build, run, and test workflows","archived":false,"fork":false,"pushed_at":"2026-04-02T11:42:54.000Z","size":1226,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T01:36:48.538Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeffkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T14:05:23.000Z","updated_at":"2026-04-02T11:41:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeffkit/argusai","commit_stats":null,"previous_names":["jeffkit/argusai"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/jeffkit/argusai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffkit%2Fargusai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffkit%2Fargusai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffkit%2Fargusai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffkit%2Fargusai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeffkit","download_url":"https://codeload.github.com/jeffkit/argusai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffkit%2Fargusai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31389691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T06:18:51.031Z","updated_at":"2026-04-04T06:18:52.099Z","avatar_url":"https://github.com/jeffkit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ArgusAI\n\n\u003e 配置驱动的 Docker 容器端到端测试平台 — 代码的百眼守护者\n\nArgusAI 是一个声明式的 E2E 测试框架，通过 YAML 配置文件描述测试环境、Mock 服务和测试用例，自动完成 Docker 镜像构建、容器管理、Mock 服务启动和测试执行。同时提供 MCP Server，让 AI 编程助手可以直接执行 E2E 测试。\n\n## 特性\n\n- **YAML 驱动** — 声明式定义测试环境和用例，零脚本编写\n- **Docker 原生** — 自动构建镜像、管理容器、配置网络和健康检查\n- **Mock 服务** — 内置 Mock 服务器，通过配置快速模拟外部依赖\n- **OpenAPI 智能 Mock** — 从 OpenAPI 3.0/3.1 spec 自动生成 Mock 路由，支持请求验证、录制/回放\n- **多运行器** — 支持 YAML / Vitest / pytest / Shell / Exec / Playwright 等多种测试运行器\n- **断言 DSL** — 丰富的断言语法，支持精确匹配、正则、类型检查、存在性验证等\n- **变量系统** — 支持 `{{config.*}}`、`{{env.*}}`、`{{runtime.*}}` 模板变量\n- **韧性自愈** — 结构化错误码、预检健康检查、容器自动重启、端口冲突规避、孤儿资源清理、熔断器保护\n- **测试持久化与趋势分析** — SQLite 持久化测试结果，Flaky Test 识别，通过率/时长趋势分析\n- **智能诊断建议** — 失败自动分类、错误签名匹配、修复知识库、置信度评分、修复反馈闭环\n- **可视化 Dashboard** — 实时查看测试执行状态、容器日志、Mock 请求录制、趋势分析\n- **多项目隔离** — 进程级端口注册中心（`PortAllocator`）+ 项目命名空间网络（`argusai-\u003cproject\u003e-network`），多项目并发运行互不干扰\n- **纯测试模式** — 无需定义任何 `service`，直接对外部容器（如 docker-compose 编排的服务）跑 YAML 测试套件\n- **完整 CLI** — 25 个命令覆盖测试全生命周期（构建、运行、诊断、趋势分析），适合终端和 AI Agent\n- **MCP Server** — AI 原生集成，让 Cursor/Claude 等编程助手直接运行 E2E 测试（23 个工具）\n- **CI/CD 模板** — 提供 GitLab CI 和 GitHub Actions 开箱即用模板\n\n## 环境要求\n\n| 依赖 | 最低版本 | 说明 |\n|------|---------|------|\n| Node.js | \u003e= 20.0 | 运行时环境 |\n| pnpm | \u003e= 10.0 | 包管理器 |\n| Docker | \u003e= 24.0 | 容器引擎（需启动 Docker Daemon） |\n\n## 快速开始\n\n### 1. 安装\n\n```bash\n# 全局安装 CLI\nnpm install -g argusai\n\n# 或作为开发依赖\npnpm add -D argusai argusai-core\n```\n\n### 2. 初始化项目\n\n```bash\nargusai init\n```\n\n自动生成：\n- `e2e.yaml` — 主配置文件\n- `tests/health.yaml` — 示例健康检查测试\n- `.env.example` — 环境变量模板\n\n### 3. 编辑配置\n\n编辑 `e2e.yaml`，配置你的服务：\n\n```yaml\nversion: \"1\"\n\nproject:\n  name: my-app\n  description: \"我的应用 E2E 测试\"\n\nservice:\n  build:\n    dockerfile: Dockerfile\n    context: .\n    image: my-app:e2e\n\n  container:\n    name: my-app-e2e\n    ports:\n      - \"8080:3000\"\n    environment:\n      NODE_ENV: test\n    healthcheck:\n      path: /health\n      interval: 5s\n      timeout: 3s\n      retries: 10\n      startPeriod: 15s\n\n  vars:\n    base_url: http://localhost:8080\n\ntests:\n  suites:\n    - name: 健康检查\n      id: health\n      file: tests/health.yaml\n```\n\n### 4. 编写测试\n\n创建 `tests/health.yaml`：\n\n```yaml\nname: 健康检查\ndescription: 验证服务健康状态\n\ncases:\n  - name: \"GET /health 返回 200\"\n    request:\n      method: GET\n      path: /health\n    expect:\n      status: 200\n      body:\n        status: ok\n```\n\n### 5. 运行测试\n\n```bash\nargusai build          # 构建 Docker 镜像\nargusai setup          # 启动测试环境（网络 + Mock + 容器）\nargusai run            # 执行测试\nargusai clean          # 清理资源\n```\n\n## CLI 命令参考\n\n```\nargusai [command] [options]\n\n全局选项:\n  -c, --config \u003cpath\u003e    e2e.yaml 配置文件路径\n  --verbose              详细输出模式\n  -V, --version          显示版本号\n  -h, --help             显示帮助信息\n```\n\n| 命令 | 说明 | 关键选项 |\n|------|------|----------|\n| `init` | 初始化项目模板 | `--dir \u003cpath\u003e` 目标目录 |\n| `build` | 构建 Docker 镜像 | `--no-cache` 禁用缓存 |\n| `setup` | 启动测试环境 | `--skip-build` 跳过构建 |\n| `run` | 运行测试套件 | `-s \u003cid\u003e` 指定套件, `--reporter json` 报告格式, `--timeout \u003cms\u003e` 超时 |\n| `status` | 查看容器/网络状态 | — |\n| `logs` | 查看容器日志 | `-f` 实时跟踪, `-n \u003clines\u003e` 行数, `--container \u003cname\u003e` 指定容器 |\n| `dashboard` | 启动可视化面板 | `-p \u003cport\u003e` 端口 |\n| `clean` | 清理测试资源 | `--all` 同时删除镜像和 volumes |\n| `dev` | 一键启动开发环境 | `--skip-build` 跳过构建, `--no-cache` 禁用缓存 |\n| `rebuild` | 一键重建（clean+build+setup） | `--no-cache` 禁用缓存 |\n| `history` | 查看历史测试运行记录 | `-n \u003ccount\u003e` 记录数, `--status` 过滤, `--days \u003cn\u003e` 天数 |\n| `flaky` | 检测不稳定测试 | `-n \u003ccount\u003e` Top N, `--min-score` 阈值, `-s \u003cid\u003e` 套件 |\n| `trends` | 查看测试趋势 | `-m \u003cmetric\u003e` 指标, `-d \u003cdays\u003e` 天数, `-s \u003cid\u003e` 套件 |\n| `compare` | 对比两次运行差异 | `--base \u003cid\u003e` 基准, `--target \u003cid\u003e` 对比 |\n| `diagnose` | 诊断失败的测试用例 | `--run \u003cid\u003e` 运行 ID, `--case \u003cname\u003e` 用例名 |\n| `report-fix` | 报告修复结果 | `--run \u003cid\u003e`, `--case \u003cname\u003e`, `--fix \u003cdesc\u003e` |\n| `patterns` | 浏览失败模式知识库 | `--category`, `--source`, `--sort` |\n| `preflight` | 环境预检健康检查 | `--auto-fix` 自动修复, `--skip-disk`, `--skip-orphans` |\n| `resources` | 查看所有 ArgusAI Docker 资源 | — |\n| `mock-requests` | 查看 Mock 请求录制 | `--mock \u003cname\u003e`, `--clear` |\n| `mock-generate` | 从 OpenAPI spec 生成 Mock | `--spec \u003cpath\u003e`, `--name`, `--port` |\n| `mock-validate` | 验证 Mock 覆盖度 | `--mock \u003cname\u003e`, `--spec \u003cpath\u003e` |\n| `reset-circuit` | 重置 Docker 熔断器 | — |\n\n### 典型工作流\n\n```bash\n# 完整的一键测试流程\nargusai build \u0026\u0026 argusai setup \u0026\u0026 argusai run \u0026\u0026 argusai clean\n\n# 一键启动开发环境\nargusai dev\n\n# 一键重建测试环境\nargusai rebuild\n\n# 只运行指定套件\nargusai run -s health\n\n# 运行多个套件\nargusai run -s health,api\n\n# JSON 报告输出（适合 CI）\nargusai run --reporter json \u003e test-results.json\n\n# 启动 Dashboard 后手动测试\nargusai setup \u0026\u0026 argusai dashboard\n\n# 查看历史记录和趋势\nargusai history -n 10\nargusai trends -m pass-rate -d 7\nargusai flaky -n 5\n\n# 诊断失败的测试\nargusai diagnose --run \u003crun-id\u003e --case \"用例名称\"\n\n# 环境预检\nargusai preflight --auto-fix\n```\n\n## e2e.yaml 配置参考\n\n```yaml\nversion: \"1\"\n\nproject:\n  name: my-project                # 项目名称（必填）\n  description: \"项目描述\"          # 项目描述（可选）\n\n# ============ 单服务模式 ============\nservice:\n  build:\n    dockerfile: Dockerfile         # Dockerfile 路径（必填）\n    context: \".\"                   # 构建上下文（默认 \".\"）\n    image: my-app:e2e             # 镜像名称（必填）\n    args:                          # 构建参数（可选）\n      NODE_ENV: production\n\n  container:\n    name: my-app-e2e              # 容器名称（必填）\n    ports:                         # 端口映射（host:container）\n      - \"8080:3000\"\n    environment:                   # 环境变量（可选，支持变量引用）\n      NODE_ENV: production\n      API_KEY: \"{{env.API_KEY}}\"\n    volumes:                       # Volume 挂载（可选）\n      - \"data-vol:/app/data\"\n    healthcheck:                   # 健康检查（可选）\n      path: /health\n      interval: 10s\n      timeout: 5s\n      retries: 10\n      startPeriod: 30s\n\n  vars:                            # 自定义变量（通过 {{config.xxx}} 引用）\n    base_url: http://localhost:8080\n\n# ============ 多服务模式 ============\nservices:\n  - name: api-server\n    build: { ... }\n    container: { ... }\n  - name: worker\n    build: { ... }\n    container: { ... }\n\n# ============ Mock 服务 ============\nmocks:\n  gateway:\n    port: 9081                    # 宿主机端口\n    containerPort: 8081           # 容器内端口（可选）\n    routes:\n      - method: GET\n        path: /api/status\n        response:\n          status: 200\n          body: { status: \"ok\" }\n\n  # OpenAPI 智能 Mock（从 spec 自动生成路由）\n  payment-api:\n    port: 9082\n    openapi: ./specs/payment.yaml # OpenAPI 3.0/3.1 spec 文件\n    mode: auto                    # auto | record | replay | smart\n    validate: true                # 请求验证（不符合 schema 返回 422）\n    target: http://real-api:8080  # record 模式的目标地址\n    overrides:                    # 手动覆盖自动生成的路由\n      - method: POST\n        path: /api/charge\n        response:\n          status: 200\n          body: { charged: true }\n\n# ============ 测试套件 ============\ntests:\n  suites:\n    - name: 健康检查\n      id: health\n      file: tests/health.yaml\n      runner: yaml                # 可选：yaml | vitest | pytest | shell | exec | playwright\n\n# ============ Dashboard ============\ndashboard:\n  port: 9095                      # API 端口（默认 9095）\n  uiPort: 9091                   # UI 端口（默认 9091）\n\n# ============ Docker 网络（可选） ============\n# 默认网络名：argusai-\u003cproject-slug\u003e-network（项目隔离）\n# 手动指定时覆盖默认值：\nnetwork:\n  name: my-custom-network\n\n# ============ 多项目隔离（可选） ============\nisolation:\n  namespace: my-project        # 自定义 Docker 资源前缀（默认从 project.name 推导）\n  portRange: [9000, 9999]      # 端口自动分配范围（默认 [9000, 9999]）\n\n# ============ 纯测试模式（可选） ============\n# 不定义 service/services 时，ArgusAI 仅执行测试，跳过 Docker 构建/启动。\n# 适用于对外部编排容器（如 docker-compose up）执行 YAML 测试的场景。\n# 须同时禁用 preflight：\nresilience:\n  preflight:\n    enabled: false\n\n# ============ 测试持久化（可选） ============\nhistory:\n  enabled: true\n  storage: local              # local | memory\n  retention: 90d              # 保留天数\n  flakyWindow: 10             # Flaky 检测滑动窗口大小\n\n# ============ 韧性与自愈（可选） ============\nresilience:\n  preflight:                         # 预检健康检查\n    enabled: true                    # 启用预检（默认 true）\n    diskSpaceThreshold: \"2GB\"        # 最低磁盘空间阈值\n    cleanOrphans: true               # 自动清理孤儿资源\n  container:                         # 容器自动重启\n    restartOnFailure: true           # 容器崩溃时自动重启\n    maxRestarts: 3                   # 最大重启次数\n    restartDelay: \"2s\"               # 重启基础延迟\n    restartBackoff: exponential      # 退避策略: exponential | linear\n  network:                           # 网络韧性\n    portConflictStrategy: auto       # 端口冲突策略: auto | fail\n    verifyConnectivity: true         # 启动后验证 Mock 可达性\n  circuitBreaker:                    # 熔断器\n    enabled: true                    # 启用熔断保护\n    failureThreshold: 5              # 连续失败阈值\n    resetTimeoutMs: 30000            # 重置超时（毫秒）\n```\n\n## YAML 测试语法\n\n### 测试文件结构\n\n```yaml\nname: 测试套件名称                    # 必填\ndescription: 套件描述                 # 可选\nsequential: true                     # 顺序执行（默认 true）\n\nvariables:                           # 套件级变量\n  game_id: \"test-{{timestamp}}\"\n\nsetup:                               # 前置步骤\n  - waitHealthy: { timeout: 60s }    # 等待服务健康\n  - delay: 3s                        # 等待指定时间\n  - name: \"前置请求\"                  # 执行 HTTP 请求\n    request:\n      method: POST\n      path: /api/init\n\nteardown:                            # 后置清理\n  - name: \"清理数据\"\n    request:\n      method: DELETE\n      path: /api/cleanup\n    ignoreError: true\n\ncases:                               # 测试用例\n  - name: \"用例名称\"\n    delay: 2s                        # 执行前等待\n    request:\n      method: GET\n      path: /api/resource\n      headers:\n        Authorization: \"Bearer {{config.token}}\"\n      body:\n        key: value\n      timeout: 30s\n    expect:\n      status: 200\n      headers:\n        content-type: application/json\n      body:\n        data: expected_value\n    save:                            # 保存响应值供后续用例使用\n      my_id: \"data.id\"\n```\n\n### 变量系统\n\n| 模板 | 来源 | 示例 |\n|------|------|------|\n| `{{config.xxx}}` | `service.vars` + `variables` | `{{config.base_url}}` |\n| `{{env.xxx}}` | 环境变量 / `.env` 文件 | `{{env.API_KEY}}` |\n| `{{runtime.xxx}}` | `save` 保存的值 | `{{runtime.my_id}}` |\n| `{{timestamp}}` | 当前 ISO-8601 时间戳 | — |\n\n### 断言 DSL\n\n```yaml\nexpect:\n  status: 200                        # 精确匹配\n  status: [200, 201]                 # 多值匹配\n\n  body:\n    name: \"hello\"                    # 字符串精确匹配\n    count: 42                        # 数字精确匹配\n    active: true                     # 布尔精确匹配\n\n    token: { exists: true }          # 存在性检查\n    name: { type: string }           # 类型检查\n    status: { in: [active, pending] }  # 枚举值\n\n    count: { gt: 0, lte: 100 }      # 数值比较\n    message: { contains: \"success\" } # 包含子串\n    code: { matches: \"^\\\\d+$\" }      # 正则匹配\n    items: { length: 5 }             # 长度检查\n\n    token: $exists                   # 简写 DSL\n    status: $regex:^ok$              # 简写正则\n\n    user:                            # 嵌套对象断言\n      profile:\n        age: { gt: 18 }\n\n  headers:\n    content-type: application/json   # 大小写不敏感\n    x-request-id: { exists: true }\n```\n\n### 时间格式\n\n支持 `100ms`、`5s`、`2m`、`1h` 或纯数字（毫秒）。\n\n## Mock 服务\n\n### 基本用法\n\n```yaml\nmocks:\n  api-gateway:\n    port: 9081\n    routes:\n      - method: GET\n        path: /api/users/:id\n        response:\n          status: 200\n          body:\n            id: \"{{request.params.id}}\"\n            name: \"User {{request.params.id}}\"\n```\n\n### 响应模板变量\n\n| 变量 | 说明 |\n|------|------|\n| `{{request.body.xxx}}` | 请求 body 中的字段 |\n| `{{request.params.xxx}}` | 路由参数 |\n| `{{request.query.xxx}}` | Query 参数 |\n| `{{timestamp}}` | ISO-8601 时间戳 |\n| `{{uuid}}` | 随机 UUID v4 |\n\n### 高级功能\n\n```yaml\nroutes:\n  # 延迟响应（模拟慢接口）\n  - method: POST\n    path: /api/slow\n    response:\n      status: 200\n      delay: \"2s\"\n      body: { result: ok }\n\n  # 条件匹配（根据请求内容返回不同响应）\n  - method: POST\n    path: /api/action\n    when:\n      body:\n        type: \"create\"\n    response:\n      status: 201\n      body: { created: true }\n\n  - method: POST\n    path: /api/action\n    response:\n      status: 200\n      body: { default: true }\n```\n\n### 诊断端点\n\n每个 Mock 服务自动提供：\n\n| 端点 | 说明 |\n|------|------|\n| `GET /_mock/health` | Mock 服务健康检查 |\n| `GET /_mock/requests` | 查看所有已录制的请求 |\n| `POST /_mock/requests/clear` | 清空录制的请求 |\n\n## 测试运行器\n\n| 运行器 | runner ID | 用途 | 目标格式 |\n|--------|-----------|------|----------|\n| YAML Runner | `yaml` | 声明式 HTTP 测试（默认） | `.yaml` 测试文件 |\n| Vitest Runner | `vitest` | JS/TS 单元/集成测试 | 测试目录/文件 |\n| Pytest Runner | `pytest` | Python 测试 | 测试目录/文件 |\n| Shell Runner | `shell` | Shell 脚本测试 | `.sh` 脚本 |\n| Exec Runner | `exec` | 任意命令 | 命令字符串 |\n| Playwright Runner | `playwright` | 浏览器 E2E 测试 | Playwright 测试文件 |\n\n```yaml\ntests:\n  suites:\n    - name: API 测试\n      id: api\n      file: tests/api.yaml              # YAML 运行器（默认）\n\n    - name: 集成测试\n      id: integration\n      runner: vitest\n      file: tests/integration/\n      config: vitest.config.ts\n\n    - name: Python 测试\n      id: pytest-suite\n      runner: pytest\n      file: tests/\n\n    - name: 冒烟测试\n      id: smoke\n      runner: shell\n      file: scripts/smoke-test.sh\n\n    - name: 自定义命令\n      id: custom\n      runner: exec\n      command: \"curl -sf http://localhost:8080/health\"\n\n    - name: 浏览器测试\n      id: browser\n      runner: playwright\n      file: tests/e2e/\n```\n\n## MCP Server（AI 集成）\n\nArgusAI 提供 MCP Server，让 AI 编程助手（如 Cursor、Claude Desktop）可以直接执行 E2E 测试。\n\n### 配置 Cursor\n\n在项目根目录的 `.cursor/mcp.json`（或 Cursor 全局 MCP 配置）中添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"argusai\": {\n      \"command\": \"npx\",\n      \"args\": [\"argusai-mcp\"]\n    }\n  }\n}\n```\n\n### MCP 工具列表\n\n| 工具 | 说明 |\n|------|------|\n| `argus_init` | 初始化项目（加载 e2e.yaml） |\n| `argus_build` | 构建 Docker 镜像（含熔断器保护） |\n| `argus_setup` | 启动测试环境（含预检、端口解析、孤儿清理、网络验证） |\n| `argus_run` | 运行所有/指定测试套件 |\n| `argus_run_suite` | 运行单个测试套件 |\n| `argus_status` | 查看环境状态 |\n| `argus_logs` | 查看容器日志 |\n| `argus_clean` | 清理资源 |\n| `argus_mock_requests` | 查看 Mock 请求录制 |\n| `argus_preflight_check` | 主动检查环境健康（Docker 守护进程、磁盘空间、孤儿资源） |\n| `argus_reset_circuit` | 重置熔断器状态（open → half-open） |\n| `argus_history` | 查询历史运行记录（支持过滤、分页） |\n| `argus_trends` | 获取趋势数据（通过率、时长、flaky 排行） |\n| `argus_flaky` | 获取 Flaky Test 列表（按不稳定程度排序） |\n| `argus_compare` | 对比两次运行的差异 |\n| `argus_diagnose` | 智能失败诊断（分类 + 知识库匹配 + 修复建议） |\n| `argus_report_fix` | 回报修复结果（更新知识库置信度） |\n| `argus_patterns` | 查看/搜索失败模式知识库 |\n| `argus_mock_generate` | 从 OpenAPI spec 生成 Mock YAML 配置 |\n| `argus_mock_validate` | 验证 Mock 配置对 OpenAPI spec 的覆盖度 |\n| `argus_dev` | 一键启动项目供手动测试（init + build + setup，返回访问地址） |\n| `argus_rebuild` | 一键重建测试环境（clean + init + build + setup） |\n| `argus_resources` | 查看所有 ArgusAI 管理的 Docker 资源（跨项目） |\n\n### AI 工作流示例\n\n通过 MCP，AI 助手可以执行完整的测试循环：\n\n```\n1. argus_preflight_check(projectPath)    → 检查环境健康（可选）\n2. argus_init(projectPath)               → 加载项目配置\n3. argus_build(projectPath)              → 构建镜像（熔断器保护）\n4. argus_setup(projectPath)              → 启动环境（预检 + 端口解析 + 孤儿清理 + 网络验证）\n5. argus_run(projectPath)                → 执行测试\n6. argus_logs(projectPath, container)    → 查看失败日志\n7. argus_clean(projectPath)              → 清理\n```\n\n当测试失败时，AI 可以智能诊断：\n```\nargus_diagnose(projectPath, runId, caseName)  → 分类失败 + 匹配知识库 + 获取修复建议\nargus_flaky(projectPath)                       → 检查是否为 Flaky Test\nargus_report_fix(projectPath, runId, ...)      → 修复成功后反馈，提升知识库置信度\n```\n\n开发者想手动测试时，一键启动：\n```\nargus_dev(projectPath)       → 构建 + 启动环境，返回访问 URL（如有健康会话则直接复用）\nargus_clean(projectPath)     → 测试完毕后清理\n```\n\n当 Docker 环境异常时，AI 可以：\n```\nargus_preflight_check(projectPath, autoFix: true)  → 诊断并自动修复\nargus_reset_circuit(projectPath)                     → 重置熔断器\n```\n\n查询历史趋势：\n```\nargus_history(projectPath, limit: 20)          → 最近 20 次运行记录\nargus_trends(projectPath, metric: \"pass-rate\") → 通过率趋势\nargus_compare(projectPath, runId1, runId2)     → 对比两次运行差异\n```\n\n## Dashboard\n\nArgusAI 提供可视化 Dashboard 用于实时监控测试。\n\n```bash\nargusai dashboard\n```\n\n功能包括：\n- 实时测试执行状态展示\n- 容器状态和日志查看\n- 测试结果历史\n- Mock 服务请求录制查看\n- API Explorer（支持自定义预设端点）\n- 配置编辑器\n- **趋势分析页面** — 通过率折线图、执行时间趋势、Flaky Test 排行、运行时间轴\n\n## 报告格式\n\n| 格式 | 用途 |\n|------|------|\n| Console | 终端彩色实时输出（默认） |\n| JSON | 机器可读的结构化报告，适合 CI |\n| HTML | 自包含的 HTML 报告文件，可离线查看 |\n\n```bash\n# JSON 报告\nargusai run --reporter json \u003e report.json\n```\n\n## CI/CD 集成\n\n项目提供开箱即用的 CI 模板，位于 `ci-templates/` 目录。\n\n### GitLab CI\n\n```yaml\ninclude:\n  - local: 'ci-templates/gitlab-ci.yml'\n\nvariables:\n  PROJECT_PATH: .\n  TEST_FILTER: ''\n```\n\n### GitHub Actions\n\n```yaml\njobs:\n  e2e:\n    uses: ./.github/workflows/argusai-e2e.yml\n    with:\n      project_path: .\n      test_filter: ''\n```\n\n详见 `ci-templates/` 目录中的完整模板。\n\n## 架构概览\n\n```\nargusai/\n├── packages/\n│   ├── core/             # 核心引擎（argusai-core）\n│   │   └── src/\n│   │       ├── config-loader.ts      # YAML 配置加载 + Zod 验证\n│   │       ├── docker-engine.ts      # Docker CLI 封装\n│   │       ├── yaml-engine.ts        # YAML 测试执行引擎\n│   │       ├── mock-generator.ts     # Mock 服务生成器（Fastify）\n│   │       ├── assertion-engine.ts   # 断言 DSL 引擎\n│   │       ├── variable-resolver.ts  # 变量模板解析\n│   │       ├── test-runner.ts        # RunnerRegistry\n│   │       ├── reporters.ts          # Console/JSON/HTML 报告\n│   │       ├── runners/              # 测试运行器实现\n│   │       ├── resilience/           # 韧性与自愈子系统\n│   │       │   ├── error-codes.ts    #   结构化错误码（13 种）\n│   │       │   ├── preflight.ts      #   预检健康检查\n│   │       │   ├── container-guardian.ts  # 容器自动重启\n│   │       │   ├── port-resolver.ts  #   端口冲突规避\n│   │       │   ├── orphan-cleaner.ts #   孤儿资源清理\n│   │       │   ├── circuit-breaker.ts #  熔断器\n│   │       │   └── network-verifier.ts # 网络韧性验证\n│   │       ├── history/              # 测试持久化与趋势分析\n│   │       │   ├── history-store.ts  #   SQLite 持久化存储\n│   │       │   ├── memory-history-store.ts # 内存存储（测试/CI 用）\n│   │       │   ├── history-recorder.ts #  测试运行记录器\n│   │       │   ├── flaky-detector.ts #   Flaky Test 识别引擎\n│   │       │   └── migrations.ts     #   数据库迁移\n│   │       ├── knowledge/            # 智能诊断与知识库\n│   │       │   ├── classifier.ts     #   失败分类器（10 类）\n│   │       │   ├── normalizer.ts     #   错误消息规范化\n│   │       │   ├── diagnostics-engine.ts # 诊断引擎\n│   │       │   ├── knowledge-store.ts #  修复知识库存储\n│   │       │   └── built-in-patterns.ts # 内置失败模式\n│   │       └── openapi/              # OpenAPI 智能 Mock\n│   │           ├── spec-loader.ts    #   OpenAPI 3.0/3.1 解析器\n│   │           ├── route-builder.ts  #   Mock 路由生成\n│   │           ├── response-generator.ts # 响应体生成\n│   │           ├── request-validator.ts # 请求 schema 验证\n│   │           └── recorder.ts       #   录制/回放引擎\n│   │       ├── port-allocator.ts     # 进程级端口注册中心（多项目隔离）\n│   │       └── resource-limiter.ts   # 并发资源控制\n│   │\n│   ├── cli/              # CLI 工具（argusai）\n│   ├── dashboard/        # 可视化面板（argusai-dashboard）\n│   └── mcp/              # MCP Server（argusai-mcp）\n│\n├── examples/             # 示例项目\n├── ci-templates/         # CI/CD 模板\n├── mcp-templates/        # MCP 配置模板\n└── schemas/              # JSON Schema（IDE 自动补全）\n```\n\n### 技术栈\n\n| 模块 | 技术 |\n|------|------|\n| 配置验证 | Zod |\n| YAML 解析 | js-yaml |\n| Mock 服务器 | Fastify |\n| OpenAPI 解析 | @readme/openapi-parser |\n| 请求验证 | Ajv |\n| Docker 操作 | Docker CLI (child_process) |\n| CLI 框架 | Commander.js |\n| 持久化存储 | better-sqlite3 (WAL mode) |\n| Dashboard | React + Vite + Tailwind CSS |\n| 图表 | Recharts |\n| 实时通信 | SSE (Server-Sent Events) |\n| 运行时 | Node.js \u003e= 20 |\n\n## 韧性与自愈\n\nArgusAI 内置了完整的错误恢复与自愈系统，将错误处理从「报错停止」升级为「恢复继续」。\n\n| 能力 | 说明 | 关键配置 |\n|------|------|---------|\n| **结构化错误码** | 13 种 AI 可解析的错误码（如 `DOCKER_UNAVAILABLE`、`PORT_CONFLICT`），附带类别、严重等级和修复建议 | — |\n| **预检健康检查** | 操作前自动检查 Docker 守护进程、磁盘空间、孤儿资源 | `resilience.preflight` |\n| **容器自动重启** | 崩溃容器自动诊断（exit code/OOM/日志）并退避重启 | `resilience.container` |\n| **端口冲突规避** | 自动检测被占用端口并分配替代端口，或快速失败 | `resilience.network.portConflictStrategy` |\n| **孤儿资源清理** | 通过 Docker Label 识别并清理上次运行残留的容器和网络 | `resilience.preflight.cleanOrphans` |\n| **熔断器** | Docker CLI 连续失败后自动熔断，所有后续操作 \u003c 100ms 快速失败 | `resilience.circuitBreaker` |\n| **网络韧性** | 启动后验证 Mock 服务 DNS 可达性和 TCP 连通性 | `resilience.network.verifyConnectivity` |\n\n所有韧性事件通过 SSE 实时推送，Dashboard 可实时展示。\n\n## 测试持久化与趋势分析\n\nArgusAI 自动持久化每次测试运行的结果，支持 Flaky Test 识别和趋势分析。\n\n```yaml\nhistory:\n  enabled: true\n  storage: local       # local (SQLite) | memory (CI/测试)\n  retention: 90d       # 保留天数\n  flakyWindow: 10      # Flaky 检测滑动窗口大小\n```\n\n| 能力 | 说明 |\n|------|------|\n| **自动持久化** | 每次 `argus_run` 的结果自动写入 SQLite |\n| **Flaky 识别** | 滑动窗口算法，5 级稳定性分类（STABLE → BROKEN） |\n| **趋势分析** | 通过率、执行时长、Flaky 排行、运行对比 |\n| **Dashboard** | 通过率折线图、时长趋势、Flaky 排行表、运行时间轴 |\n\nAI Agent 使用场景：测试失败 → 查询 flaky score → 判断是否为已知不稳定测试 → 决定忽略或修复。\n\n## 智能诊断建议\n\n内置失败模式知识库，自动分类诊断失败原因并给出修复建议。\n\n| 能力 | 说明 |\n|------|------|\n| **失败分类** | 10 类自动分类（ASSERTION_MISMATCH、HTTP_ERROR、TIMEOUT 等） |\n| **错误签名** | 规范化错误消息 + SHA-256 签名，精确匹配历史模式 |\n| **修复知识库** | 内置 6 个常见模式 + 自学习模式，Laplace 平滑置信度评分 |\n| **反馈闭环** | Agent 修复成功后通过 `argus_report_fix` 反馈，持续提升知识库质量 |\n\nAI Agent 使用场景：测试失败 → `argus_diagnose` 自动分类 → 匹配知识库 → 获取修复建议和置信度 → 修复后反馈。\n\n## 多项目隔离\n\n支持多个项目在同一台机器、同一 MCP Server 实例下并发运行，互不干扰。\n\n| 能力 | 说明 |\n|------|------|\n| **项目命名空间网络** | 默认 Docker 网络名为 `argusai-\u003cproject-slug\u003e-network`，不同项目使用各自独立的网络 |\n| **端口注册中心** | `PortAllocator` 进程级单例，并发 setup 时跨项目协调端口分配，消除端口抢占竞争 |\n| **自定义命名空间** | 通过 `isolation.namespace` 自定义资源前缀；`isolation.portRange` 指定可分配的端口范围 |\n| **资源全局视图** | `argus_resources` 工具查询所有 `argusai.managed=true` 的 Docker 容器和网络，按项目分组展示 |\n\n```yaml\nisolation:\n  namespace: my-project     # 可选，默认从 project.name 推导\n  portRange: [10000, 10999] # 可选，默认 [9000, 9999]\n```\n\nAI Agent 使用场景：`argus_resources` → 一眼看到哪些项目的哪些容器/网络还在跑 → 精准清理目标项目。\n\n## OpenAPI 智能 Mock\n\n从 OpenAPI 3.0/3.1 spec 一键生成 Mock 路由，支持请求验证和录制/回放。\n\n```yaml\nmocks:\n  payment-api:\n    port: 9082\n    openapi: ./specs/payment.yaml   # OpenAPI spec 文件\n    mode: auto                       # auto | record | replay | smart\n    validate: true                   # 请求 schema 验证（不符合返回 422）\n    target: http://real-api:8080     # record 模式的代理目标\n    overrides:                       # 手动覆盖路由（优先级最高）\n      - method: POST\n        path: /api/charge\n        response:\n          status: 200\n          body: { charged: true }\n```\n\n| 模式 | 行为 |\n|------|------|\n| `auto` | 基于 OpenAPI schema 自动生成响应（优先使用 example 字段） |\n| `record` | 代理请求到真实 API 并录制响应 |\n| `replay` | 从录制文件回放响应 |\n| `smart` | 有录制就回放，没有就自动生成 |\n\n通过 `X-Mock-Status` request header 可切换返回的 HTTP 状态码。\n\n## 开发\n\n```bash\ngit clone \u003crepo-url\u003e\ncd argusai\npnpm install\npnpm build\npnpm test:run\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffkit%2Fargusai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffkit%2Fargusai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffkit%2Fargusai/lists"}