Skip to content
BranchesTags

Repository files navigation

企业级 AI Agent 平台

面向二次开发与企业落地的 AI Agent 平台底座

English | 中文

Vue 3 Workspace Testcase Agent Live Skills MCP Knowledge Ready Harness LangGraph Runtime Core Latest Release README EN/ZH

系统总览 · 前端入口 · 快速开始 · 部署文档 · 最新 Release · 更新日志 · 致谢参考 · AI代理部署

Testcase Agent 展示视频

Testcase Agent 展示视频

▶ 观看当前平台 Testcase Agent 演示视频

GitHub README 中采用预览图展示，点击后跳转到 YouTube 播放。

基于 LangGraph / LangChain 的企业级 AI 平台架构，可在此基础上进行二次开发。
它把平台治理层和Agent Runtime 执行层拆开，既支持平台侧的认证、项目管理、审计、catalog 管理，也支持 Agent 侧的图编排、模型装配、Tools / MCP / Skills 接入与快速调试，适合作为企业内部 AI 平台和智能体应用的基础骨架。

当前仓库默认提供一套正式五服务演示链路，适合：

  • 想基于主流 Agent 技术栈做二次开发的团队
  • 想同时建设平台能力和 Agent 执行能力的项目
  • 想快速验证 LangGraph Runtime、Agent 行为和前端交互的开发者
  • 希望把 AI 协同开发真正纳入工程流程的团队

想先理解开发流程和任务分级，可看 AGENTS.md。

当前建议优先把下面几份文档当成正式事实源：

  • docs/local-deployment-contract.yaml
  • AGENTS.md
  • docs/quickstart/local-dev.md
  • docs/quickstart/env-matrix.md
  • deploy/README.md
  • docs/runbooks/container-update-runbook.md

如果你要从零开始使用 Docker / Docker Compose 部署当前项目，优先看：

  • deploy/README.md
  • docs/quickstart/zero-to-one-container-deploy.md
  • docs/runbooks/container-update-runbook.md

AI 执行入口

如果你希望后续的人类开发者或 AI 代理都按同一套开发规范进入任务，建议先按下面顺序阅读：

  1. AGENTS.md —— 开发流程、改动分级标准（单项目/链路/治理改动）
  2. Docs 总入口

当前规划：Dear Agent 总纲与能力迁移（第二版：独立前端、前后端基础框架与逐章实施接续；治理方案待评审，尚未实施）。

一句话理解：

  • AGENTS.md：开发规范入口，定义分级标准和验证要求
  • docs/projects/：链路/治理改动的项目文档（方案、任务、验证记录）
  • 各 app/service 自己的 docs/：服务内部标准

改动分级由 AI 自动判断（不需要手动调用命令），依据见 AGENTS.md。

规划链路/治理改动项目、记录实现细节、执行验证分别使用 $plan-project、$implement-feature、$verify-change。

当前前端与推荐入口

apps/platform-web 是当前正式平台前端宿主，也是仓库默认联调和后续平台前端开发的统一入口。

前端架构与 Agent Chat 重构原方案已获用户批准，保留 Vue/官方 SDK、允许 SDK 升级并沿用现有视觉，尚未实施；多端消息队列与 Runtime Middleware 按用户要求最后完成，不阻塞前端主体验收，见 重构方案与验收计划。

当前正式平台入口已经覆盖首批核心页面：

  • overview
  • projects
  • users
  • assistants
  • me
  • security
  • audit

当前正式前端相关事实源：

  • apps/platform-web/src/router/routes.ts
  • apps/platform-web/docs/control-plane-page-standard.md
  • apps/platform-api/docs/README.md
  • apps/platform-api/docs/handbook/project-handbook.md
  • Platform API开发规范

补充说明：上面列出的页面是当前正式前端范围中的核心入口，以 apps/platform-web/src/router/routes.ts 为代码事实源。

如果你是第一次跑这个仓库，建议直接按根目录脚本启动并打开 apps/platform-web。

AI 持续编程 Harness

这个仓库不只是“放了一堆代码”，而是已经形成了一套可以指导 AI 代理持续开发、持续联调、持续验收的工程 Harness。

这里说的 Harness，不是单个工具，而是一整套受控的工程外壳：

  • 边界：平台治理、运行时执行、调试前端、结果域服务已经拆层，AI 不需要在一个大泥球里瞎改
  • 契约：本地部署 contract、环境变量矩阵、接口命名、默认启动顺序和账号口径都已固定
  • 范式：runtime-service、platform-web、控制面页面标准与现成样例页面已经沉淀出可复用范式
  • 闭环：根级脚本、健康检查、烟测清单、验收文档、CHANGELOG 和 release runbook 已形成可执行交付链路

平台控制面后端这部分，当前专用的落地蓝图与正式标准已经统一写入：

  • apps/platform-api/docs/README.md
  • apps/platform-api/docs/handbook/project-handbook.md

一句话说，这个仓库已经不是“让 AI 随便写代码”，而是“让 AI 在明确边界、稳定契约和现成范式中持续完成开发”。

这个项目解决什么问题

很多 Agent 项目能跑 demo，但一到真实工程场景就容易混乱：平台治理、运行时执行、调试入口、环境配置全耦在一起，后面越改越难受。

这个仓库的目标很明确：

  • 用 LangGraph / LangChain 主流生态构建企业级 AI 平台架构，不重新发明一套封闭框架
  • 把平台层和运行时层解耦，便于分工、演进和交付
  • 提供可复用的 Runtime 执行骨架，而不是一次性 demo
  • 给后续业务二开和测试场景接入预留空间

前端效果展示

如果你想先看当前平台前端已经做到了什么程度、页面大致长什么样，以及前端这部分是怎么组织和展示的，可以直接看这篇记录：

这篇内容更偏平台前端视角，适合快速了解当前 Agent Platform Console 的页面效果、工作区结构和一些实际展示结果。

平台前端效果展示

系统总览

当前根目录默认联调脚本会启动 4 个正式应用：

  • apps/interaction-data-service：结果域数据服务 / 工作流结果落库与查询
  • apps/platform-api：正式平台后端 / 控制面 API
  • apps/platform-web：正式平台前端宿主 / 管理台入口
  • apps/runtime-service：LangGraph 执行层 / Agent Runtime

主要链路

  • 平台链路：platform-web -> platform-api -> runtime-service
  • 结果链路：runtime-service -> interaction-data-service

前端入口

  • platform-web：当前正式平台工作台入口，承接 Agent Platform Console、Agent 页面和平台治理相关前端能力

架构图

系统架构图

快速开始

默认启动顺序

  1. runtime-service
  2. interaction-data-service
  3. platform-api
  4. platform-web

本地栈启动（推荐）

如果本机已经运行 PostgreSQL 和 Redis，使用本地栈脚本：

bash scripts/local-stack.sh doctor   # 验证环境和依赖
bash scripts/local-stack.sh start    # 启动完整栈
bash scripts/local-stack.sh status   # 检查服务状态
bash scripts/local-stack.sh stop     # 停止服务

该脚本直接启动 GraphHarbor API、GraphHarbor Worker、Platform API、Platform Worker 和 Platform Web； 数据库迁移使用 migrate 子命令执行，日志和 PID 文件放在系统临时目录。它不会停止或删除本机 PostgreSQL、Redis，也不会按端口杀掉不属于自己的进程。启动前会检查 DATABASE_URI 对应的 PostgreSQL 和 REDIS_URI，发现失效 PostgreSQL 锁文件时不会自动删除。Runtime 使用 apps/runtime-service/.env，Platform API 使用 apps/platform-api/.env。 首次使用时，分别从对应的 .env.example 创建本地 .env，填入真实模型凭据和本机 PostgreSQL 账号；不要覆盖已有 .env，也不要提交真实值。

Docker / Docker Compose

如果你希望直接用容器方式启动，当前有 3 种常见用法：

  1. 只启动 runtime-service
docker compose -f apps/runtime-service/deploy/docker-compose.runtime-service.yml --env-file apps/runtime-service/deploy/.env.runtime-service up -d
  1. 启动整仓 stack（无 Nginx，前后端分端口）
docker compose -f deploy/docker-compose.stack.yml --env-file deploy/.env.stack up -d
  1. 启动整仓 stack（带 Nginx，单入口）
docker compose -f deploy/docker-compose.stack.nginx.yml --env-file deploy/.env.stack up -d

建议阅读顺序：

  • deploy/README.md
  • docs/quickstart/zero-to-one-container-deploy.md
  • docs/runbooks/container-update-runbook.md

如果你想单独启动 platform-web

根目录默认脚本已经会启动 apps/platform-web。

如果你要单独调试平台前端，也可以这样启动：

VITE_DEV_PORT=3002 pnpm --dir "apps/platform-web" dev

然后打开：

  • platform-web：http://127.0.0.1:3002

这样不会和默认的 platform-web:3000 端口冲突。

默认本地端口

  • interaction-data-service：8081
  • runtime-service：8123
  • platform-api：2142
  • platform-web：3000

成功启动后访问地址

  • platform-web：http://127.0.0.1:3000

最小健康检查

curl http://127.0.0.1:8081/_service/health
curl http://127.0.0.1:8123/info
curl http://127.0.0.1:2142/_system/health
curl http://127.0.0.1:2142/api/langgraph/info

如果 platform-api 的 /api/langgraph/info 和 interaction-data-service 的 /_service/health 都返回成功，说明平台链路和结果落库主链已经基本打通。

本地联调启动流程图

仓库结构

AITestLab/
├── apps/
│   ├── interaction-data-service/
│   ├── platform-api/
│   ├── platform-web/
│   ├── runtime-service/
│   └── ...
├── .codex/skills/
├── docs/
├── scripts/
└── deploy/
  • apps/：业务应用目录，包含当前默认联调服务与其他按需维护的应用目录
  • .codex/skills/：可跨设备复用的项目级 Codex Skills
  • docs/：部署、开发、约束和背景文档
  • scripts/：统一启动、停止、健康检查脚本
  • archive/：历史归档说明

按目标阅读文档

文档导航图

我想先把环境跑起来

唯一支持的启动方式是使用 local-stack.sh：

bash "scripts/local-stack.sh" start

详细说明见：

  • docs/local-deployment-contract.yaml
  • docs/quickstart/local-dev.md
  • docs/quickstart/env-matrix.md

我想了解完整部署细节

再看：

  • docs/quickstart/deployment-guide.md

我想继续开发或二开

重点看：

  • AGENTS.md
  • docs/guides/development-guidelines.md
  • docs/project-story.md

我想做正式发版

先看：

  • docs/releases/release-policy.md
  • docs/releases/v0.3.1-agent-workspace-demo-draft.md
  • docs/releases/v0.3.1-release-runbook.md
  • docs/releases/：完整历史发布记录

我想让 AI 代理帮我部署

入口文档：

  • docs/guides/ai-deployment-assistant-instruction.md

如果你只是想触发标准本地部署，这句话就够了：

阅读 `docs/guides/ai-deployment-assistant-instruction.md` 帮我部署环境。

如果你已经知道本地要用哪套模型，建议把模型配置也一次性发给代理。这样代理更容易一次把环境配好，而不是启动到一半再回头追问 runtime 模型配置。

更推荐直接发这段（把占位符替换成你自己的真实配置，且只让代理写入本地 settings.local.yaml，不要把真实 key 提交回仓库）：

阅读 `docs/guides/ai-deployment-assistant-instruction.md` 帮我部署环境。

默认推理模型使用 `<YOUR_REASONING_MODEL_ID>`。
当前多模态链路需要的模型一并配置为 `<YOUR_MULTIMODAL_MODEL_ID>`。
如果本地缺少 runtime 模型配置，请把下面内容写入 `apps/runtime-service/runtime_service/conf/settings.local.yaml`，并继续完成部署、启动与验证；不要把真实 API Key 提交回仓库。

default:
  default_model_id: <YOUR_REASONING_MODEL_ID>
  models:
    <YOUR_MULTIMODAL_MODEL_ID>:
      alias: <OPTIONAL_MULTIMODAL_ALIAS>
      model_provider: openai
      model: <YOUR_MULTIMODAL_MODEL_NAME>
      base_url: <YOUR_PROVIDER_BASE_URL>
      api_key: <YOUR_API_KEY>
    <YOUR_REASONING_MODEL_ID>:
      alias: <OPTIONAL_REASONING_ALIAS>
      model_provider: openai
      model: <YOUR_REASONING_MODEL_NAME>
      base_url: <YOUR_PROVIDER_BASE_URL>
      api_key: <YOUR_API_KEY>

实操参考

如果你希望参考一套更贴近真实开发过程的本地实操记录，详细见：

这组记录不是重复贴源码，而是专门补“具体怎么做、怎么验证、怎么复盘”的落地路径，可作为本仓库进行智能体功能开发和平台相关能力开发的参考。

建议这样理解这组内容：

  • 根仓库 README 更偏项目地图、系统分层和文档导航
  • ai-learning-portfolio 里的本地实操记录更偏真实开发过程、验证路径和复盘方法

如果你想按主线看，建议优先关注这些内容：

你可以这样理解这 3 篇记录的作用：

  • 20260323_deployment_environment.md：看本地环境怎么准备、怎么启动、怎么验证链路是否打通
  • 20260312_texttosql_rd.md：看一个相对简单的 Text-to-SQL 能力案例是怎么围绕具体场景做设计与实现的
  • 20260314_requirement_agent_rd.md：看多智能体复杂业务场景从需求理解、角色拆分到研发落地是怎么推进的

如果你是第一次接触这个仓库，比较推荐的阅读顺序是：

  1. 先看当前仓库的 README、docs/local-deployment-contract.yaml 和 docs/quickstart/local-dev.md
  2. 再看 ai-learning-portfolio 中的本地实操记录索引
  3. 如果想先从简单案例入手，就看 Text-to-SQL；如果想看复杂业务协作场景，就看多智能体需求研发案例

当前状态

当前仓库已经完成：

  • 正式默认本地演示链路已收口到 apps/*
  • apps/platform-web 是当前正式平台前端宿主
  • runtime-service 可启动
  • interaction-data-service 可启动
  • platform-api 可启动
  • platform-api -> runtime-service 联调已通过
  • runtime-service -> interaction-data-service 已接入本地联调脚本
  • platform-web 是当前正式平台前端入口
  • 开发流程已收口到 AGENTS.md：改动分级（单项目/链路/治理）由 AI 自动判断并按需自动调用 plan-project/implement-feature/verify-change Skills
  • 当前正式版本为 v0.3.1

当前仍保持的约定：

  • 每个应用独立维护自己的环境与依赖
  • 根目录不统一维护 .env
  • 根目录暂不统一 Python / Node 依赖

项目方向

这个仓库的长期方向，是把它打磨成一套可复用、可扩展、可继续二开的 AI Agent 平台基础框架。
当前会优先吸收测试工程相关场景能力，例如：

  • AI 智能评审
  • AI 驱动的 UI 自动化
  • 自动化脚本生成与测试辅助
  • AI 性能测试
  • Text-to-SQL

更完整的项目背景、演进过程和设计取舍，见：

  • docs/project-story.md

支持与交流

如果这个项目对你有帮助，欢迎 star。
如果你希望交流测试平台、AI 协同开发、LangGraph / MCP 相关实践，也欢迎联系。

个人微信号：

个人微信号

历史代码

旧版 AITestLab 代码已不再保留在当前工作分支。

如需回看旧版代码，请访问：

致谢与参考

本项目在持续演进过程中，参考并受益于一些优秀的开源项目与技术生态，尤其包括：

  • Wei-Shaw/sub2api：在前端视觉组织、后台工作台布局、列表页与系统区交互节奏上给了当前平台工作台设计不少启发
  • FastAPI：平台后端与服务接口层的重要基础
  • LangGraph：Agent Runtime、状态编排与执行流建模的重要基础
  • FastMCP：MCP 工具接入与服务化能力的重要参考生态
  • HKUDS/LightRAG：项目级知识检索与可选仓库内 LightRAG MCP 接入方案的重要参考

这里的“参考”不是简单照搬源码，而是基于这些开源项目和技术生态，结合当前仓库的业务目标、工程边界和平台化需求，做了再组织、再封装和再落地。

开源与引用说明

本项目以公开源码方式持续维护，欢迎学习、参考和基于当前仓库继续二次开发。

如果你在公开项目、技术文章、演示材料、培训内容或二次发布中使用了本项目的代码、设计、文档或衍生实现，请明确注明来源仓库与作者信息。

建议至少保留类似说明：

This project is based on or references AITestLab:
https://github.com/ljxpython/AITestLab

About

AI agent平台开发 --以测试 方向为例，搭建了一套 harness 可落地方案，不需要手写一段代码，企业级通用 AI 智能体平台框架（平台控制面 + LangGraph 运行时），可以在这个基础轻松二次开发

Topics

agentagentic-aiharness-engineeringlanggraphtestngvibe-coding

Resources

Readme
Activity

Stars

130 stars

Watchers

5 watching

Forks

19 forks
Report repository

Releases

Packages

Contributors

Languages