qKnow v2.1.1：智能体平台精细化迭代，把"能用"推向"好用"

# 查询某个文档在 qKnow 中的完整处理链路
# 前提：已配置 qKnow 的日志输出到 Elasticsearch 或类似系统

# 1. 获取文档的 trace_id（入库接口返回，或从文档元数据表查）
TRACE_ID=$(curl -s "http://localhost:8080/api/v1/documents/meta?doc_name=产品规格书v3.pdf" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['doc_trace_id'])")

echo "文档 trace_id: $TRACE_ID"

# 2. 拉取该 trace_id 下所有处理步骤的日志
curl -s "http://localhost:9200/qknow-traces/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": { "term": { "doc_trace_id": "'"$TRACE_ID"'" } },
    "sort": [ { "timestamp": "asc" } ],
    "_source": ["step", "status", "duration_ms", "error_msg"]
  }' | python3 -c "
import sys, json
hits = json.load(sys.stdin)['hits']['hits']
for h in hits:
    s = h['_source']
    print(f'{s[\"step\"]:20s} | status={s[\"status\"]} | {s[\"duration_ms\"]}ms | err={s.get(\"error_msg\",\"-\")}')
"

# 3. 如果某步 status=failed，直接看切片版本状态
curl -s "http://localhost:8080/api/v1/chunks?doc_trace_id=$TRACE_ID&version_status=superseded" \
  | python3 -c "
import sys, json
chunks = json.load(sys.stdin)
print(f'已过期切片数: {len(chunks)}')
for c in chunks[:3]:
    print(f'  chunk_id={c[\"chunk_id\"]}, content_preview={c[\"content\"][:60]}...')
"

# 最小化步骤进度推送示例（FastAPI + WebSocket）
# 适用于任何智能体编排场景，不依赖 qKnow 特定 API

from fastapi import FastAPI, WebSocket
import asyncio

app = FastAPI()

# 模拟智能体处理步骤
AGENT_STEPS = [
    {"step": "document_parse",   "label": "正在解析文档",   "avg_ms": 3000},
    {"step": "chunk_split",      "label": "正在知识切片",   "avg_ms": 1500},
    {"step": "vectorize",        "label": "正在向量化索引", "avg_ms": 5000},
    {"step": "index_write",      "label": "正在写入索引",   "avg_ms": 2000},
]

@app.websocket("/ws/task-progress/{task_id}")
async def task_progress(ws: WebSocket, task_id: str):
    await ws.accept()
    try:
        for i, step in enumerate(AGENT_STEPS):
            # 推送当前步骤开始
            await ws.send_json({
                "task_id": task_id,
                "step": step["step"],
                "label": step["label"],
                "progress": i / len(AGENT_STEPS),
                "status": "running"
            })
            # 模拟处理耗时
            await asyncio.sleep(step["avg_ms"] / 1000)
            # 推送当前步骤完成
            await ws.send_json({
                "task_id": task_id,
                "step": step["step"],
                "label": step["label"],
                "progress": (i + 1) / len(AGENT_STEPS),
                "status": "done"
            })
        await ws.send_json({
            "task_id": task_id,
            "step": None,
            "label": "处理完成",
            "progress": 1.0,
            "status": "completed"
        })
    except Exception as e:
        await ws.send_json({
            "task_id": task_id,
            "step": None,
            "label": f"处理异常: {str(e)}",
            "status": "error",
            "suggestion": "请检查输入数据格式，或联系管理员查看服务日志"
        })
    finally:
        await ws.close()

# 启动: uvicorn progress_demo:app --host 0.0.0.0 --port 8080