AI Agent 轨迹分析和管理系统，支持轨迹存储、失效分析、可视化和JSON导入。
- ✅ 轨迹CRUD操作（创建、查询、更新、删除）
- ✅ JSON文件导入
- ✅ 失效分析引擎（6种失效模式检测）
- ✅ 向量搜索（相似轨迹检索）
- ✅ 标签和收藏管理
- ✅ 统计分析和可视化数据
- ✅ RESTful API
- ✅ 108个测试用例
- 基础信息：各类轨迹完成的类别（env_done、截断、timeout、finish的占比），意外终止的轨迹查看
- 工具信息：工具返回的类别（正常返回、空、超时、连接报错等的占比），意外工具的工具上下文查看
- 奖励信息：轨迹奖励的类别（完美分数，完全失败，部分成功等的占比），特殊奖励对应轨迹的查看
- 过程信息：过程奖励和轨迹奖励的相关性，例如肯德尔相关性系数的指标（过程reward平均值作为x，结果reward作为y，在整个轨迹层面计算相关性），相关性高的->beam_search，相关性低的->2.0
trajectory_store/
├── backend/ # 后端代码
│ ├── models/ # 数据模型
│ ├── repositories/ # 数据访问层
│ ├── services/ # 业务服务层
│ ├── analyzers/ # 分析引擎
│ ├── routes/ # API路由
│ ├── config.py # 配置
│ └── main.py # FastAPI应用
├── tests/ # 测试用例
│ ├── scripts/ # 测试脚本和工具
│ └── *.py # 测试文件
├── scripts/ # 实用脚本
│ ├── run_server.py # 启动脚本
│ └── *.py # 其他脚本
├── docs/ # 项目文档
├── samples/ # 示例数据
├── frontend/ # 前端代码
├── venv/ # 虚拟环境
├── requirements.txt # 依赖列表
└── README.md # 本文件
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或 venv\Scripts\activate # Windows
# 安装核心依赖（推荐）
pip install -r requirements-core.txt
# 或安装完整依赖（包含测试和代码质量工具）
pip install -r requirements.txt依赖说明：
requirements-core.txt- 只包含运行所需的核心依赖（约50MB）requirements.txt- 包含测试和开发工具（约200MB）
如果下载速度慢，可以使用国内镜像：
pip install -r requirements-core.txt -i https://pypi.tuna.tsinghua.edu.cn/simplepython tests/scripts/demo.py# 方式1：使用启动脚本
python scripts/run_server.py
# 方式2：直接使用uvicorn
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload访问 API 文档：http://localhost:8000/docs
# 运行所有测试
pytest tests/ -v
# 运行基础测试
pytest tests/test_basic.py -v
# 运行特定测试
pytest tests/test_trajectory_service.py -v
# 生成覆盖率报告
pytest tests/ --cov=backend --cov-report=htmlGET /api/trajectories- 获取轨迹列表POST /api/trajectories- 创建轨迹GET /api/trajectories/{id}- 获取轨迹详情PUT /api/trajectories/{id}- 更新轨迹DELETE /api/trajectories/{id}- 删除轨迹GET /api/trajectories/search- 搜索轨迹PUT /api/trajectories/{id}/tags- 添加标签PUT /api/trajectories/{id}/bookmark- 收藏轨迹
POST /api/import/json- 导入JSON文件POST /api/import/dict- 从字典导入GET /api/import/status/{task_id}- 查询导入状态GET /api/import/history- 导入历史
POST /api/analysis/analyze- 分析轨迹GET /api/analysis/{id}- 获取分析结果GET /api/analysis/stats- 获取统计数据GET /api/analysis/failures/distribution- 失败原因分布
GET /api/viz/timeline/{id}- 时序图数据GET /api/viz/flow/{id}- 流程图数据GET /api/viz/stats- 统计图表GET /api/viz/network- 关系网络图
GET /api/export/csv- 导出CSVGET /api/export/json- 导出JSONPOST /api/export/pdf/{id}- 导出PDF报告
curl -X POST http://localhost:8000/api/trajectories \
-H "Content-Type: application/json" \
-d '{
"trajectory_id": "traj_001",
"data_id": "q_001",
"task": {
"question": "如何使用Python读取CSV文件？",
"ground_truth": "使用pandas.read_csv()"
},
"steps": [],
"chat_completions": [],
"reward": 1.0,
"exec_time": 5.0,
"agent_name": "Agent",
"termination_reason": "success",
"epoch_id": 1,
"iteration_id": 1,
"sample_id": 1,
"toolcall_reward": 0.8,
"res_reward": 0.9,
"training_id": "train_001"
}'curl -X POST http://localhost:8000/api/import/json \
-F "file=@trajectories.json"支持的JSON格式：
{
"trajectories": [
{
"trajectory_id": "traj_001",
"data_id": "q_001",
"task": {"question": "...", "ground_truth": "..."},
"steps": [],
"chat_completions": [],
"reward": 1.0,
"exec_time": 5.0,
"agent_name": "Agent",
"termination_reason": "success",
"epoch_id": 1,
"iteration_id": 1,
"sample_id": 1
}
]
}curl -X POST http://localhost:8000/api/analysis/analyze \
-H "Content-Type: application/json" \
-d '{"trajectory_id": "traj_001"}'系统支持以下失效模式检测：
- 格式错误 - 工具调用标签不匹配
- 重复工具错误 - 连续多次工具调用失败
- 重复输出 - 相同内容重复输出
- 挂起 - 助手没有action就停止
- 过度自信 - 未验证就声称成功
- 上下文超限 - 超过最大轮次限制
项目采用测试驱动开发（TDD），所有测试用例已提前编写完成。
- 查看测试状态
pytest tests/ -v-
修复失败的测试
-
运行测试验证
- 在
tests/中添加测试用例 - 在
backend/中实现功能 - 运行测试验证
- 更新API文档
配置文件：backend/config.py
class Settings(BaseSettings):
db_path: str = "data/lancedb" # 数据库路径
vector_dimension: int = 384 # 向量维度
api_host: str = "0.0.0.0" # API主机
api_port: int = 8000 # API端口
max_import_size: int = 100 * 1024 * 1024 # 最大导入大小- 后端: FastAPI, Pydantic, Python 3.10+
- 数据库: LanceDB (向量数据库)
- 向量处理: sentence-transformers
- 测试: pytest, pytest-asyncio, pytest-cov
- 开发工具: uvicorn, black, flake8
MIT License
欢迎提交Issue和Pull Request！