27.v4 Agent Native：Runtime + Skill + Hook + HITL 三栏 UI

👉 第二个实战项目：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）：

「最近七天活跃度怎么样？」
自动跑：understand-intent → select-metrics → compile-and-query
暂停：确认或修改 metric_ids 后重查
确认后 analyze-insight → 再问是否 生成报告
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）：

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。

🧠 八、快速启动

bash 复制代码

# 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）

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

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

🧠 十一、总结

💥 一句话

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

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