momentry_studio/CORE_TEAM_ACTION_ITEMS.md

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 权重计算是否正确？
• 阶段状态转换是否及时？

权重设置（前端期望）：

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

# 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: 检查文件状态同步

# 对卡住的文件，手动调用 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: 检查后端日志

# 查看最近的错误日志
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)

权重配置已修正：

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

改动：

// 在 syncFileStatus() 中，当状态为 processing 时，加载进度数据
if (newStatus === 'processing') {
  await loadPipelineStats(fileUuid, true)
}

效果：每 10 秒轮询时，会更新进度数据

---

修复 2: LibraryView 启动轮询（处理边缘情况）

文件: src/views/LibraryView.vue:789-790

改动：

// 即使没有 pipeline 数据，如果状态是 processing，也启动轮询
else if (!pipeline && f.status === 'processing') {
  pollPipelineProgress(f.file_uuid)
}

效果：不会因为 pipeline 数据缺失而无法启动轮询

---

修复 3: 权重配置修正

文件: src/store.ts:923-931

改动：

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

改动：

// 移除过滤，包含所有阶段
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 优先级: 🔴 高 - 影响用户体验