👉 第二个实战项目：AI 运营助手；项目 git 地址：ai-ops-assistant-lab

---

🧠 一、v3 之后，还缺什么？

v3 把 数据口径 管住了，但运营同学会问：

• 查完数能不能 先改指标再出报告？
• 推理过程能不能 看得见，而不是黑盒一句 Markdown？
• 新加一个分析步骤，能不能 别改巨型 workflow 类？

v4 的定位：

👉 Agent Native 产品雏形——在 v3 数据引擎之上，加会话、Skill 插件、Hook 审计、HITL、Web UI。

💥 二、四层架构（一张图）

                Agent Runtime
                       │
       ┌───────────────┼───────────────┐
       │                               │
    Skill Engine                  Hook Engine
  SKILL.md / workflow.yaml      SSE + audit.jsonl
  scripts/run.py
       │                               │
       └───────────────┬───────────────┘
                       │
                 Model Adapter
         OpenAI / Anthropic / DeepSeek / Gemini / Mock

层	职责
Agent Runtime	会话、YAML 工作流、Skill 调度、HITL 闸门
Skill Engine	声明式能力包（文档 + 步骤脚本）
Hook Engine	生命周期事件、右侧时间线、审计日志
Model Adapter	多模型统一 chat_json

数据面继承 v3：backend/metrics/、semantic_layer/sql_compiler.py 由 Skill 脚本调用。

🧩 三、三栏 UI 在解决什么？

栏位	能力
左	对话 + HITL 按钮（继续 / 修改指标 / 生成报告 / 取消）
中	Markdown 报告 + 图表
右	Hook 推理时间线（SSE）

典型路径（见 README.md）：

1. 「最近七天活跃度怎么样？」
2. 自动跑：understand-intent → select-metrics → compile-and-query
3. 暂停：确认或修改 metric_ids 后重查
4. 确认后 analyze-insight → 再问是否 生成报告
5. generate-report → 中栏展示

👉 这是 v3 一键 CLI 与 v4 可运营产品 的最大差异。

🟢 四、Agent Runtime：会话与 HITL

backend/runtime/agent_runtime.py 核心 API：

• create_session()
• handle_message(session_id, text) — 按 ops-analysis.yaml 跑 skill_sequence
• handle_action(session_id, action, payload) — 处理 confirm_metrics、edit_metrics 等

工作流片段（runtime/workflows/ops-analysis.yaml）：

skill_sequence:
  - understand-intent
  - select-metrics
  - compile-and-query
hitl_gates:
  - after_skill: compile-and-query
    phase: awaiting_metric_review
    actions: [confirm_metrics, edit_metrics, cancel]
  - before_skill: generate-report
    phase: awaiting_report_confirm
    actions: [confirm_report, cancel]
post_hitl_skills:
  - analyze-insight
  - generate-report

注意：analyze-insight / generate-report 不在 首次 skill_sequence 里，而是用户确认后才触发——人在回路写进配置，而不是写死在运营流程培训里。

🟡 五、Skill：可插拔的能力包

每个 Skill 目录：

understand-intent/
  SKILL.md           # 说明 + YAML front matter
  workflow.yaml      # steps: id, script, fn
  scripts/run.py     # run(ctx, inp) -> dict

SkillExecutor 动态加载脚本，逐步合并 ctx.data，并发射 skill_step Hook。

当前 Skill 链：

Skill	作用
understand-intent	意图与时间范围
select-metrics	registry 白名单选指标
compile-and-query	v3 编译 + Doris
analyze-insight	洞察
generate-report	Markdown

扩展新能力 ≈ 新建目录 + 改 YAML，不必 fork 整个 Runtime 类。

🔵 六、Hook Engine：可观测与审计

HookDispatcher 事件类型包括：

• session_start / session_message

• pre_skill_execute / post_skill_execute / skill_step

• hitl_pause / report_ready

• SSE：GET /api/sessions/{id}/stream

• 持久化：backend/logs/audit.jsonl

这和 v3 的 trace 字典是同一条演进线：从批处理日志 → 会话时间线。

🟣 七、FastAPI 与前端

后端路由（api/routes.py）：

• POST /api/sessions
• POST /api/sessions/{id}/messages
• POST /api/sessions/{id}/actions
• GET /api/metrics — HITL 改指标用

前端：Vite + React + Tailwind，开发态 http://localhost:5173。

🧠 八、快速启动

# Backend
cd ai-ops-assistant-v4/backend
pip install -r requirements.txt
python3 -m uvicorn main:app --reload --port 8000

# Frontend
cd ai-ops-assistant-v4/frontend
npm install && npm run dev

.env 中 MODEL_PROVIDER=mock 可完全离线演示。

🧠 九、v4 与 v3 怎么协作？（不是替代）

	v3	v4
定位	可信 分析引擎	Agent 操作系统 + UI
SQL	Compiler	同一套 Compiler（Skill 内调用）
编排	Python Workflow 类	YAML + Runtime
人	一次性 CLI	HITL + 改指标重查

原则：v4 改编排与交互，不削弱 v3 的指标—计划—编译红线。

❗ 十、v4 已知局限（后续 Runtime 2.0）

1. 工作流仍以 预定义 YAML 顺序 为主，尚未接 OWL Workforce 动态分解。
2. handle_action 对部分分支仍有 Skill 名硬编码（如重跑 compile-and-query）。
3. Skill 动态 importlib 加载，尚缺 Schema 校验与版本治理。

这些在总结篇《Agent Runtime 展望》展开。

🧠 十一、总结

💥 一句话

👉 v4 = 把 v3 的「指标编译引擎」装进「可会话、可审计、可插拔」的 Agent 产品壳。

关键路径：backend/runtime/agent_runtime.py、skill_engine/、hook_engine/、frontend/src/App.tsx。