Momentry Studio
a096bb645c
Studio Team 已完成修复： 1. ✅ 权重配置修正（rule1_ingestion: 0.05, face_tracing: 0.05, identity_agent: 0.10） 2. ✅ 移除 identity_agent 过滤 3. ✅ API 端点已验证正确（无需修改） 4. ✅ syncFileStatus() 加载进度数据 5. ✅ LibraryView 启动轮询（处理边缘情况） Core Team 后端问题： - 🟡 Pipeline 进度计算逻辑 - 🟡 Pipeline stages 初始化 - 🟡 文件处理异常处理
280 lines
6.6 KiB
Markdown
280 lines
6.6 KiB
Markdown
# Core Team Action Items - Pipeline Progress Issue
|
||
|
||
## ✅ Studio Team 已完成修复
|
||
|
||
**修复内容**：
|
||
1. ✅ 权重配置已修正（基于 Core team 规格）
|
||
2. ✅ 移除 identity_agent 过滤
|
||
3. ✅ API 端点已验证正确
|
||
|
||
**Commit**: `待推送`
|
||
|
||
---
|
||
|
||
## 🚨 问题摘要（已部分解决）
|
||
|
||
**现象**：Library 卡片在 deep scan 时卡在 "Scanning..." 状态，没有进度百分比
|
||
|
||
**前端已修复**：
|
||
- ✅ 权重配置已修正（基于 Core team 规格）
|
||
- ✅ 移除 identity_agent 过滤
|
||
- ✅ API 端点已验证正确（无需修改）
|
||
- ✅ `syncFileStatus()` 现在会加载进度数据
|
||
- ✅ LibraryView 会启动轮询即使 pipeline 数据缺失
|
||
|
||
**后端需要诊断**：3 项核心问题
|
||
|
||
---
|
||
|
||
## 📋 Core Team 需要检查的项目
|
||
|
||
### 1. 🟡 Pipeline 进度计算逻辑（中优先级）
|
||
|
||
**位置**: Core API pipeline 执行引擎
|
||
|
||
**需要检查**：
|
||
- 各处理阶段的进度追踪是否准确？
|
||
- `overall_progress` 权重计算是否正确？
|
||
- 阶段状态转换是否及时？
|
||
|
||
**权重设置**（前端期望）：
|
||
```typescript
|
||
const WEIGHT_MAP = {
|
||
processors: 0.30,
|
||
rule1_ingestion: 0.10,
|
||
face_tracing: 0.10,
|
||
tkg_nodes: 0.20,
|
||
tkg_edges: 0.15,
|
||
rule2_ingestion: 0.15
|
||
}
|
||
```
|
||
|
||
**需要验证**：
|
||
- ✅ 后端权重是否与前端一致？
|
||
- ✅ 各阶段进度是否正确追踪？
|
||
- ✅ 阶段完成时是否立即更新状态？
|
||
|
||
---
|
||
|
||
### 4. 🟡 Pipeline stages 初始化（中优先级）
|
||
|
||
**需要检查**：
|
||
- 文件开始处理时，是否立即创建 stages 数据？
|
||
- 所有必要的阶段是否都被追踪？
|
||
- 阶段顺序是否正确？
|
||
|
||
**可能的问题**：
|
||
- 文件开始处理时，`stages` 数组为空
|
||
- 导致前端无法判断是否有正在运行的阶段
|
||
- `pollPipelineProgress()` 不会被启动
|
||
|
||
**需要验证**：
|
||
- ✅ 文件注册后，立即创建初始 stages？
|
||
- ✅ 所有阶段都被包含在返回数据中？
|
||
- ✅ 阶段顺序是否符合 pipeline 流程？
|
||
|
||
---
|
||
|
||
### 5. 🟡 文件处理异常处理（中优先级）
|
||
|
||
**需要检查**：
|
||
- 处理过程出错时，文件状态是否正确更新？
|
||
- 是否有文件卡在 `processing` 状态无法完成？
|
||
- 错误日志是否完整？
|
||
|
||
**可能的问题**：
|
||
- 文件处理出错，但状态未更新为 `failed`
|
||
- 文件永远卡在 `processing` 状态
|
||
- 前端无法判断文件是否完成
|
||
|
||
**需要验证**：
|
||
- ✅ 错误处理机制是否完善？
|
||
- ✅ 失败文件是否有明确的 `failed` 状态？
|
||
- ✅ 错误日志是否包含足够信息？
|
||
|
||
---
|
||
|
||
## 🧪 诊断步骤
|
||
|
||
### Step 1: 检查 processing 文件的 pipeline stats
|
||
|
||
```bash
|
||
# 1. 获取 processing 文件列表
|
||
curl -X GET "http://localhost:3002/api/v1/files?status=processing&per_page=10" \
|
||
-H "Authorization: Bearer {API_KEY}"
|
||
|
||
# 2. 对每个 processing 文件，检查 pipeline stats
|
||
for uuid in $(processing_files); do
|
||
echo "=== File: $uuid ==="
|
||
curl -X GET "http://localhost:3002/api/v1/pipeline-stats?file_uuid=$uuid" \
|
||
-H "Authorization: Bearer {API_KEY}"
|
||
echo ""
|
||
done
|
||
```
|
||
|
||
**观察重点**：
|
||
- `overall_progress` 是否为 0 或 null？
|
||
- `stages` 数组是否为空？
|
||
- 是否有 stage 的 `status === 'running'`？
|
||
|
||
---
|
||
|
||
### Step 2: 检查文件状态同步
|
||
|
||
```bash
|
||
# 对卡住的文件，手动调用 sync_file_status
|
||
curl -X POST "http://localhost:3002/api/v1/sync-file-status" \
|
||
-H "Authorization: Bearer {API_KEY}" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"file_uuid": "{STUCK_FILE_UUID}"}'
|
||
```
|
||
|
||
**观察重点**：
|
||
- API 是否返回正确的状态？
|
||
- 状态是否从 `processing` 变为 `completed`？
|
||
|
||
---
|
||
|
||
### Step 3: 检查后端日志
|
||
|
||
```bash
|
||
# 查看最近的错误日志
|
||
tail -f /path/to/core-api/logs/error.log | grep -E "pipeline|processing|file_uuid"
|
||
```
|
||
|
||
**观察重点**：
|
||
- 是否有 pipeline 执行错误？
|
||
- 是否有文件处理超时？
|
||
- 是否有数据库连接错误？
|
||
|
||
---
|
||
|
||
## 📊 API 端点验证结果
|
||
|
||
### ✅ 已验证正确（无需修改）
|
||
|
||
**API 端点已是正确的**：
|
||
- ✅ `get_pipeline_stats`: `/api/v1/stats/pipeline/:file_uuid` (src/api/index.ts:510)
|
||
- ✅ `sync_file_status`: `/api/v1/file/:file_uuid/sync-status` (src/api/index.ts:582)
|
||
|
||
**权重配置已修正**：
|
||
```typescript
|
||
const WEIGHT_MAP = {
|
||
processors: 0.30,
|
||
rule1_ingestion: 0.05, // ✅ 已修正（was 0.10）
|
||
face_tracing: 0.05, // ✅ 已修正（was 0.10）
|
||
identity_agent: 0.10, // ✅ 已添加（was filtered out）
|
||
tkg_nodes: 0.20,
|
||
tkg_edges: 0.15,
|
||
rule2_ingestion: 0.15
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 前端已修复的内容
|
||
|
||
### 修复 1: `syncFileStatus()` 添加进度加载
|
||
|
||
**文件**: `src/store.ts:888-891`
|
||
|
||
**改动**：
|
||
```typescript
|
||
// 在 syncFileStatus() 中，当状态为 processing 时，加载进度数据
|
||
if (newStatus === 'processing') {
|
||
await loadPipelineStats(fileUuid, true)
|
||
}
|
||
```
|
||
|
||
**效果**：每 10 秒轮询时，会更新进度数据
|
||
|
||
---
|
||
|
||
### 修复 2: LibraryView 启动轮询（处理边缘情况）
|
||
|
||
**文件**: `src/views/LibraryView.vue:789-790`
|
||
|
||
**改动**：
|
||
```typescript
|
||
// 即使没有 pipeline 数据，如果状态是 processing，也启动轮询
|
||
else if (!pipeline && f.status === 'processing') {
|
||
pollPipelineProgress(f.file_uuid)
|
||
}
|
||
```
|
||
|
||
**效果**：不会因为 pipeline 数据缺失而无法启动轮询
|
||
|
||
---
|
||
|
||
### 修复 3: 权重配置修正
|
||
|
||
**文件**: `src/store.ts:923-931`
|
||
|
||
**改动**：
|
||
```typescript
|
||
const WEIGHT_MAP: Record<string, number> = {
|
||
processors: 0.30,
|
||
rule1_ingestion: 0.05, // ✅ 修正（was 0.10）
|
||
face_tracing: 0.05, // ✅ 修正（was 0.10）
|
||
identity_agent: 0.10, // ✅ 添加（was filtered out）
|
||
tkg_nodes: 0.20,
|
||
tkg_edges: 0.15,
|
||
rule2_ingestion: 0.15
|
||
}
|
||
```
|
||
|
||
**效果**：进度百分比计算准确
|
||
|
||
---
|
||
|
||
### 修复 4: 移除 identity_agent 过滤
|
||
|
||
**文件**: `src/store.ts:919`
|
||
|
||
**改动**：
|
||
```typescript
|
||
// 移除过滤，包含所有阶段
|
||
const stages = data.stages || []
|
||
```
|
||
|
||
**效果**：identity_agent 阶段被正确追踪
|
||
|
||
---
|
||
|
||
## ✅ 修复验证清单
|
||
|
||
修复后，前端期望看到：
|
||
|
||
1. **进度条显示百分比**
|
||
- 不再只显示 "Scanning..."
|
||
- 显示具体进度（如 "45%"）
|
||
|
||
2. **进度数据定期更新**
|
||
- 每 10 秒更新一次
|
||
- 进度条实时变化
|
||
|
||
3. **文件状态正确转换**
|
||
- `processing` → `completed`
|
||
- 处理失败的文件显示 `failed`
|
||
|
||
4. **无卡住现象**
|
||
- 文件不会永远卡在 `processing`
|
||
- 有明确的完成时间
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
如有疑问，请联系 Studio team：
|
||
|
||
- **前端修复 Commit**: `{COMMIT_HASH}`
|
||
- **修复文件**:
|
||
- `src/store.ts:888-891`
|
||
- `src/views/LibraryView.vue:789-790`
|
||
- **测试环境**: `http://localhost:5173`
|
||
- **API 文档**: `AGENTS.md`
|
||
|
||
---
|
||
|
||
**生成时间**: 2026-07-25
|
||
**优先级**: 🔴 高 - 影响用户体验 |