概述

ai-orchestrator 是一个基于 Ollama 的 AI 代理编排框架，旨在为 AI 模型执行提供可观测、可干预、可量化的生产级工作流环境。该项目采用"平台而非集线器"的设计原则，强调与本地工具链的深度集成而非简单的 API 聚合。

资料来源：README.md

核心设计理念

平台而非集线器

传统 AI 代理框架往往将所有功能集中于单一服务，形成功能耦合的"集线器"。ai-orchestrator 反其道而行，采用模块化架构，每个组件专注于特定职责，通过标准化接口通信。这种设计使得系统各部分可以独立演进、测试和部署。

资料来源：VISION.md

关键设计目标

资料来源：README.md

系统架构

整体架构图

graph TD
    subgraph 前端层
        UI[Console UI]
        WS[WebSocket 客户端]
    end
    
    subgraph API 层
        API[FastAPI REST API]
        MCP[MCP Server]
    end
    
    subgraph 核心编排层
        P[Planner]
        G[Generator]
        J[Judge]
        O[Optimizer]
    end
    
    subgraph 记忆层
        MEM[Memory]
        HIN[Hindsight]
        VAULT[Vault Writer]
    end
    
    subgraph 执行层
        REG[Tool Registry]
        GATES[Gates Layer]
        SSH[SSH Sandboxes]
    end
    
    UI --> API
    UI --> WS
    WS --> API
    MCP --> API
    
    API --> P
    API --> G
    API --> J
    API --> O
    
    P --> REG
    G --> REG
    REG --> GATES
    GATES --> SSH
    
    P --> MEM
    J --> MEM
    MEM --> HIN
    HIN --> VAULT

核心组件职责

资料来源：ARCHITECTURE.md

核心功能模块

1. Campaign 抽象层

Campaign 是项目的核心抽象概念，用于组织和管理多个相关的 AI 执行任务。每个 Campaign 包含：

• 运行批次：一组逻辑关联的 Run 实例
• 配置复用：共享的模型选择、目标配置、评估标准
• 生命周期管理：创建、执行、暂停、恢复、终止的完整状态机

stateDiagram-v2
    [*] --> Created: 创建 Campaign
    Created --> Running: 启动执行
    Running --> Paused: HITL 干预 / SmartPause
    Paused --> Running: 批准 / 编辑通过
    Running --> Complete: 所有 Run 完成
    Running --> Failed: 关键错误
    Complete --> [*]
    Failed --> [*]

资料来源：README.md, ui/console/src/lib/types.ts:1-30

2. HITL 干预模式

Phase 3.1 引入了完整的人类在环干预机制，支持五种干预模式：

资料来源：ui/console/src/lib/types.ts:10-18

3. SmartPause 机制

Phase 3.2 实现了基于置信度的智能暂停功能。当 Planner 的输出置信度低于预设阈值（默认 0.50）时，系统自动触发 SmartPause，等待人工审查：

• 置信度可视化：UI 实时显示 Planner 置信度条
• 阈值方案：>=0.7 绿色 / 0.4-0.7 黄色 / <0.4 红色
• 干预选项：批准当前计划、编辑后通过、跳过当前步骤、终止运行

资料来源：ui/console/src/components/ConfidenceBar.tsx:1-20, ui/console/src/pages/Hitl.tsx:1-50

4. 双重 Ollama 路由

系统支持同时连接多个 Ollama 实例，具备以下特性：

• 模型感知 URL 缓存：根据模型名称自动选择最优端点
• Judge 模型熔断器：防止 Judge 模型故障级联影响主流程
• 单次刷新机制：避免并发请求导致的重复刷新

资料来源：README.md

5. 沙箱执行环境

通过 SSH 连接到远程服务器实现代码隔离执行：

graph LR
    A[Generator] -->|验证代码| B[Verify]
    B -->|通过| C[Deploy]
    B -->|失败| D[Reject]
    C -->|SSH| E[Remote Server]
    E -->|结果| F[Results]

支持的语言环境：Python、Bash、JavaScript

资料来源：README.md

6. 工具注册与调度

资料来源：api/routes/admin.py:1-50, README.md

7. MCP 服务器

项目在 /mcp 端点提供 Model Context Protocol 服务，支持外部 LLM 客户端（如 Claude Desktop）直接调用编排能力。

资料来源：README.md

8. Vault Writer

自动发布各类笔记到 NoteDiscovery 主机和 NAS 镜像：

• 按运行、项目、模型、目标、错误类型分类
• 每日汇总笔记
• 跨维度索引与检索

资料来源：README.md, api/routes/memory.py:1-50

9. Hindsight 知识图谱

Phase 3.3 引入的基于 NoteDiscovery 的规划器增强功能：

• 自动反思：/hindsight/reflect/auto 接口合成模型性能洞察
• 失败模式分析：识别常见错误模式与规避策略
• 部署模式学习：提炼最可靠的执行模式

资料来源：api/routes/memory.py:50-80, README.md

运行阶段（Phase）

每个 Run 实例经历以下执行阶段：

资料来源：ui/console/src/lib/types.ts:1-10

技术栈

后端技术

前端技术

监控与可观测性

资料来源：ui/console/README.md, README.md

快速开始

# 克隆仓库
git clone https://github.com/ernesto01louis/ai-orchestrator.git
cd ai-orchestrator

# 创建虚拟环境
python3.11 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置
cp config.example.json config.json   # 编辑 Ollama URL 和 SSH 目标
cp .env.example .env                 # 填写 GOTIFY_TOKEN 等

# 启动服务
uvicorn app:app --host 0.0.0.0 --port 8000

# 健康检查
curl http://127.0.0.1:8000/health

资料来源：README.md

文档体系

资料来源：README.md

版本历史亮点

资料来源：社区发布记录

适用场景

ai-orchestrator 特别适用于以下场景：

1. 需要人类监督的 AI 执行：通过 HITL 机制确保关键决策经过人工确认
2. 多模型对比研究：Campaign 支持批量运行与对比分析
3. 代码质量要求严格的工程：引用等级评估与事实性验证
4. 资源受限的私有化部署：支持本地 Ollama 与 SSH 沙箱
5. 持续优化的生产工作流：Optimizer 与参数调优机制

系统概述

ai-orchestrator 是一个 AI 驱动的任务编排平台，核心功能包括：

• 多阶段执行管道：planner → post_planner → generator → judge → optimizer
• Campaign 抽象：批量运行管理，支持参数网格搜索和预算控制
• HITL（Human-in-the-Loop）干预模式：checkpoint、gate_only、step_by_step、co_pilot、full_auto
• SmartPause 智能暂停：基于 planner 置信度的动态干预机制
• 双 Ollama 路由：模型感知 URL 缓存 + judge 模型断路器
• 沙箱执行：通过 SSH 在可配置目标上执行 Python/Bash/JavaScript 代码
• MCP 服务：支持外部 LLM 客户端（如 Claude Desktop）
• Vault 写入器：将运行结果发布到 NoteDiscovery 和 NAS 镜像
• 实时 WebSocket 流：推送日志行和状态变更
• Prometheus 指标：高基数管控（不含 run_id 标签）

前置要求

环境准备

克隆代码仓库

git clone https://github.com/ernesto01louis/ai-orchestrator.git
cd ai-orchestrator

创建 Python 虚拟环境

python3.11 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或: venv\Scripts\activate  # Windows

安装依赖

pip install -r requirements.txt

资料来源：README.md:Quickstart

配置

项目需要两类配置文件才能正常运行。

服务配置（config.json）

复制配置模板并编辑 Ollama URL 和 SSH 目标：

cp config.example.json config.json

关键配置项说明：

环境变量（.env）

复制环境变量模板并填写必要值：

cp .env.example .env

资料来源：README.md:Quickstart

启动服务

后端 API 服务

使用 uvicorn 启动 FastAPI 应用：

uvicorn app:app --host 0.0.0.0 --port 8000

服务将监听在 http://0.0.0.0:8000。

健康检查

验证服务是否正常运行：

curl http://127.0.0.1:8000/health

正常响应示例：

{
  "status": "healthy",
  "version": "0.3.6-phase3.6",
  "ollama_connected": true,
  "timestamp": "2024-01-15T10:30:00Z"
}

资料来源：README.md:Quickstart

前端 UI 控制台（可选）

如需使用 Web UI，进入控制台目录并启动开发服务器：

cd ui/console
pnpm install
pnpm dev

UI 主题通过 localStorage.theme 和 data-theme 属性控制，支持 default 和 personal 两套皮肤。

服务控制

详细的运维任务参考 RUNBOOK.md。

常用命令

项目结构

ai-orchestrator/
├── app.py                    # FastAPI 应用入口
├── api/
│   └── routes/               # API 路由模块
│       ├── health.py         # 健康检查端点
│       ├── runs.py           # 运行管理
│       ├── campaigns.py      # Campaign 管理
│       ├── memory.py         # 内存与知识图谱
│       └── activity.py       # 活动时间线
├── core/
│   ├── orchestrator.py       # 核心编排引擎
│   ├── planner.py            # Planner 代理
│   ├── generator.py          # Generator 代理
│   ├── judge.py              # Judge 代理
│   ├── hitl.py               # HITL 干预逻辑
│   └── gates.py              # 安全门控层
├── memory_pkg/               # 内存与持久化
├── ui/
│   └── console/              # React 前端控制台
├── cli/
│   └── main.py               # CLI 工具
├── campaigns/                 # Campaign 存储
├── projects/                 # 项目存储
└── memory/                   # 运行内存数据

核心概念

执行阶段（Phase）

graph TD
    A[planner] --> B[post_planner]
    B --> C{HITL Checkpoint?}
    C -->|是| D[等待人工批准]
    D --> C
    C -->|否| E[generator]
    E --> F[judge]
    F --> G{通过?}
    G -->|否| H[optimizer]
    H --> E
    G -->|是| I[complete]

HITL 干预模式

SmartPause

SmartPause 是 Phase 3.2 引入的智能暂停机制，基于 planner 置信度动态触发干预：

• 置信度 ≥ 0.70：状态显示为 ok，继续自动执行
• 置信度 0.40-0.70：状态显示为 warn，建议关注
• 置信度 < 0.40：自动触发 SmartPause，等待人工批准

资料来源：ui/console/src/components/ConfidenceBar.tsx:8-9

后续步骤

概述

ai-orchestrator 采用阶段式版本发布策略，版本号格式为 vX.Y.Z-phaseN.M，其中：

• X.Y.Z 为语义化版本号
• N.M 表示当前开发的阶段编号

该项目目前处于 Phase 3 阶段，核心功能围绕 AI 编排引擎、Campaign 管理、人机协作（HITL）和智能暂停（SmartPause）机制展开。

资料来源：README.md:1-10

版本号命名规范

阶段编号与功能模块的对应关系：

资料来源：ROADMAP.md

发布时间线

Phase 2 系列 (v0.2.x)

Phase 2 核心贡献：

• feat(campaign): Phase 1.1 — Campaign 抽象层 资料来源：PR #1
• chore(ci): 用正确修复替代临时方案，ruff 成为阻塞性检查 资料来源：PR #2
• feat: Phase 1.2 — 引用级证据包

Phase 3 系列 (v0.3.x)

#### v0.3.1-phase3.1 — HITL 干预模式

HITL 模式定义 (types.ts):

export type HitlMode =
  | "full_auto"      // 全自动执行
  | "gate_only"      // 仅在关卡点暂停
  | "checkpoint"     // 检查点暂停
  | "step_by_step"   // 单步执行
  | "co_pilot";      // 副驾驶协作模式

资料来源：ui/console/src/lib/types.ts:6-17

#### v0.3.2-phase3.2 — SmartPause 智能暂停

SmartPause 是 Phase 3.2 的核心特性，当规划器置信度低于阈值时自动触发暂停：

置信度可视化组件 (ConfidenceBar.tsx):

const tone: Tone = value >= 0.7 ? "ok" : value >= 0.4 ? "warn" : "err";

资料来源：ui/console/src/components/ConfidenceBar.tsx:8-14

#### v0.3.3-phase3.3 — NoteDiscovery 规划器

资料来源：PR #19

#### v0.3.4-phase3.4 至 v0.3.6-phase3.6

最新版本保持 Phase 3.3 的核心功能集，聚焦于：

• Campaign 抽象层稳定化
• CI/CD 流程规范化
• 证据包功能完善

功能阶段演进图

graph LR
    A[v0.2.1] --> B[Phase 2.2-2.5]
    B --> C[v0.3.1]
    C --> D[Phase 3.1<br/>HITL干预模式]
    D --> E[v0.3.2]
    E --> F[Phase 3.2<br/>SmartPause]
    F --> G[v0.3.3]
    G --> H[Phase 3.3<br/>NoteDiscovery规划器]
    H --> I[v0.3.4-3.6]
    
    style D fill:#e1f5fe
    style F fill:#fff3e0
    style H fill:#e8f5e9

HITL 控制台页面

HITL（Human-In-The-Loop）控制台是 Phase 3 的核心 UI 组件，位于 /hitl 路由：

graph TD
    A[Run 暂停等待] --> B{暂停类型?}
    B -->|SmartPause| C[显示置信度条]
    B -->|HITL Checkpoint| D[显示干预选项]
    C --> E[操作员决策]
    D --> E
    E --> F[approve<br/>reject<br/>edit]
    F --> G[POST /runs/:id/intervene]

干预操作 API (ui/console/src/pages/Hitl.tsx):

资料来源：ui/console/src/pages/Hitl.tsx:30-40

版本间迁移

升级到 v0.3.x 的注意事项

1. HITL 模式变化

• 后端 paused 字段现在存储 hitl:{phase} 格式
• UI 需要从 Run.hitl_mode 读取实际模式

1. SmartPause 阈值

• 默认置信度阈值：0.50
• 可在 core/hitl.py 中自定义

1. API 端点变更

• /runs/:id/intervene 端点已更新
• 响应格式新增 confidence 字段

常见问题

Q: 为什么版本号跳过了 v0.3.0？

A: v0.3.0 为内部开发版本，未发布到社区。从 v0.3.1 开始正式发布。

Q: Phase 4 什么时候开始？

A: 根据 ROADMAP，当前项目聚焦于 Phase 3.x 的稳定化，Phase 4 的具体内容尚未公布。

Q: 如何回退到旧版本？

A: 使用 Git 标签切换：

git checkout v0.2.5-phase2.5

相关资源

概述

ai-orchestrator 是一个基于 FastAPI 构建的 AI 编排平台，旨在实现模型无关的 AI 工作流自动化与可观测性。该系统遵循"平台而非枢纽"（platform-not-hub）的设计原则，支持多模型路由、沙箱执行、HITL（Human-in-the-Loop）干预、证据级别溯源等核心能力。

资料来源：README.md:1-20

整体架构图

graph TB
    subgraph 前端层["前端层 (React + Vite)"]
        UI[UI Console]
        WS[WebSocket 客户端]
        API[REST API 客户端]
    end

    subgraph 后端层["后端层 (FastAPI)"]
        APP[app.py<br/>FastAPI Application]
        subgraph 路由层["API 路由"]
            ROUTES[routes/*]
        end
        subgraph 核心层["Core 模块"]
            HITL[core/hitl.py<br/>HITL 控制]
            AGENTS[core/agents/*<br/>Agent 逻辑]
            EXEC[core/exec.py<br/>执行引擎]
        end
    end

    subgraph 记忆层["Memory & Storage"]
        MEM[memory_pkg]
        VAULT[Vault Writer]
        HINDSIGHT[Hindsight]
    end

    subgraph 外部集成["外部集成"]
        OLLAMA[Ollama<br/>多模型路由]
        SSH[SSH Targets<br/>沙箱执行]
        MCPS[MCP Server]
    end

    UI --> API
    UI --> WS
    API --> APP
    WS --> APP
    APP --> ROUTES
    ROUTES --> HITL
    ROUTES --> AGENTS
    ROUTES --> EXEC
    APP --> MEM
    APP --> VAULT
    APP --> HINDSIGHT
    EXEC --> OLLAMA
    EXEC --> SSH
    MCPS --> APP

核心模块布局

API 路由结构

系统后端采用 FastAPI Router 进行模块化路由管理，所有路由文件位于 api/routes/ 目录下：

资料来源：api/routes/memory.py:1-30

Agent 执行阶段

系统定义了完整的 AI Agent 执行管道，包含以下阶段：

stateDiagram-v2
    [*] --> Planner: 任务输入
    Planner --> PostPlanner: 生成计划
    PostPlanner --> HITL_Check: HITL Gate
    HITL_Check --> Generator: 批准通过
    HITL_Check --> [*]: 中止
    Generator --> Judge: 生成内容
    Judge --> Optimizer: 评估通过
    Judge --> Generator: 需重试
    Optimizer --> [*]: 完成

#### 阶段类型定义

资料来源：ui/console/src/lib/types.ts:1-15

HITL（Human-in-the-Loop）系统

干预模式

Phase 3.1 实现了五种 HITL 干预模式，用于在不同粒度上控制 AI 执行流程：

资料来源：ui/console/src/lib/types.ts:16-25

SmartPause 机制

Phase 3.2 引入了 SmartPause 智能暂停功能，当 Planner 置信度低于阈值时自动触发暂停：

# 置信度阈值方案
阈值 >= 0.7:  ok (绿色)  - 正常执行
阈值 0.4-0.7: warn (黄色) - 警告状态
阈值 < 0.4:   err (红色)  - 高风险暂停

SmartPause 与传统 HITL 检查点的区别：

资料来源：ui/console/src/pages/Hitl.tsx:1-50

干预操作 API

HITL 控制台支持三种干预操作：

POST /runs/{runId}/intervene
{
  "action": "approve" | "reject" | "edit",
  "payload": "<edited_json>"  # 仅 edit 模式需要
}

干预后的行为：

• approve: 继续执行，Generator 正常运行
• reject: 中止运行，不再消耗 Token
• edit: 修改 Planner 输出后继续执行

资料来源：ui/console/src/pages/Hitl.tsx:51-80

记忆与数据层

记忆源架构

系统采用多源记忆聚合架构：

graph LR
    subgraph 记忆源
        RI[run_index.json<br/>运行索引]
        CAMP[campaigns.json<br/>战役数据]
        NEG[negative_memory.json<br/>负面模式]
        PROMPT[prompt_index.json<br/>提示词索引]
    end

    subgraph 外部存储
        HINDSIGHT[Hindsight<br/>知识图谱]
        VAULT[NoteDiscovery Vault<br/>笔记聚合]
        NAS[NAS Mirror<br/>NAS 镜像]
    end

    RI --> AGG[Activity API]
    CAMP --> AGG
    NEG --> AGG
    PROMPT --> AGG
    AGG --> GraphData[/graph-data<br/>图数据端点]
    HINDSIGHT --> memory_routes
    VAULT --> memory_routes

活动时间线聚合

/api/activity 端点聚合三类事件源：

资料来源：api/routes/activity.py:1-80

参考文档管理

参考文档支持 PDF → Markdown 自动转换，并可选择性地摄入 Hindsight 知识图谱：

# 上传流程
1. 接收文件 → 检查大小 (MAX_REFERENCE_UPLOAD_BYTES)
2. 保存原始文件 → local_path
3. convert_file_to_markdown() → md_text
4. 保存 Markdown 版本 → REFERENCE_DIR/{stem}.md
5. hindsight_retain() → 摄入知识图谱 (可选)

资料来源：api/routes/memory.py:30-60

前端架构

UI Console 技术栈

资料来源：ui/console/README.md:1-20

页面路由

资料来源：ui/console/README.md:21-30

主题系统

系统支持双主题切换：

运行时切换方式：

window.__setTheme("personal")  // 切换主题
window.__setTheme("default")   // 恢复默认

资料来源：ui/console/README.md:31-45

数据流与执行管道

运行数据模型

interface Run {
  id: string;              // 运行唯一标识
  project: string;         // 项目名称
  campaign_id: string;     // 所属战役 ID
  phase: Phase;            // 当前阶段
  score: number | null;   // 评分 (0-1)
  model: string;           // 模型标识
  target: string;          // 执行目标
  started_at: string;      // ISO 时间戳
  paused: PausedState;    // 暂停状态
  hitl_mode: HitlMode;    // HITL 模式
  confidence?: number;     // Planner 置信度
}

后端 API 合约

资料来源：ui/console/README.md:46-55

外部集成

Ollama 多模型路由

系统支持双 Ollama 实例路由，具备以下特性：

• 模型感知 URL 缓存: 根据模型名称缓存对应实例地址
• 判断模型断路器: Judge 模型失败时自动切换
• 单例刷新机制: 防止并发刷新冲突

沙箱执行

通过 SSH Targets 实现跨机器代码执行：

• verify-then-deploy: 验证后部署模式
• 持久化项目布局: 保持项目目录结构
• 多语言支持: Python / Bash / JavaScript

MCP Server

/mcp 端点提供 MCP (Model Context Protocol) 服务，供外部 LLM 客户端（如 Claude Desktop）接入。

Vault Writer

发布以下笔记到 NoteDiscovery Host 和 NAS 镜像：

• per-run: 单次运行记录
• per-project: 项目级汇总
• per-model: 模型性能对比
• per-target: 目标环境分析
• per-error: 错误模式分析
• daily: 每日总结

资料来源：README.md:20-40

Campaign 战役抽象

Phase 1.1 引入的 Campaign 概念用于批量管理多个 Run：

interface Campaign {
  id: string;              // 战役唯一标识
  name: string;           // 战役名称
  hitl_mode: HitlMode;    // 继承的 HITL 模式
  status: 'running' | 'complete' | 'aborted';
  children: number;       // 子 Run 总数
  completed: number;      // 已完成数
  failed: number;         // 失败数
  started_at: string;     // 开始时间
  budget: BudgetInfo;     // 预算信息
  grid?: GridConfig;      // 参数网格配置
}

Campaign 支持参数网格扫描，可批量执行多组模型/参数组合。

CLI 工具

命令行工具 cli/main.py 提供运维功能：

资料来源：cli/main.py:1-80

版本演进

资料来源：社区发布记录

概述

五层记忆系统是 ai-orchestrator 的核心知识管理基础设施，为 AI Agent 提供持久化、可检索、上下文感知的记忆能力。该系统通过分层架构存储和管理项目身份、目标、参考资料、运行历史和反思洞察，使 Agent 在多轮任务执行中保持连贯性和上下文连续性。

记忆系统与 Phase 1.2 — citation-grade evidence bundles 和 Phase 3.3 — NoteDiscovery-grounded planner 功能紧密集成，通过 REST 接口为规划器提供基于笔记的推理能力。

系统架构

graph TB
    subgraph "第五层：反思记忆 (Hindsight)"
        H[反思引擎]
        H --> HI[Hindsight 记忆]
    end
    
    subgraph "第四层：运行记忆 (Run Index)"
        RI[run_index.json]
        RI --> RH[运行历史]
    end
    
    subgraph "第三层：参考资料 (References)"
        RF[Reference 上传]
        RF --> RM[Markdown 转换]
        RM --> R[参考资料库]
    end
    
    subgraph "第二层：目标与计划 (Goals)"
        G[goals.md]
        G --> GP[目标追踪]
    end
    
    subgraph "第一层：身份认同 (Identity)"
        I[identity.md]
        I --> IP[项目身份]
    end
    
    ND[NoteDiscovery] -->|上下文注入| P[Planner]
    HI -->|洞察检索| ND
    R -->|证据支撑| ND
    RI -->|历史模式| ND
    GP -->|目标约束| P
    IP -->|角色定义| P

层次详解

第一层：身份认同 (Identity Layer)

文件位置: memory/identity.md

身份层存储项目的核心定义，包括 Agent 角色定位、能力边界和行为准则。这是 Agent 理解"我是谁"的基础。

核心内容：

• 项目名称和描述
• Agent 角色定义
• 核心能力列表
• 行为约束和边界
• 默认工作模式

身份信息在系统启动时加载，并作为系统提示词模板的基础输入，确保 Agent 行为的一致性。

第二层：目标追踪 (Goals Layer)

文件位置: memory/goals.md

目标层维护项目的短期和长期目标，为规划器提供任务方向指引。

功能特性：

第三层：参考资料 (References Layer)

文件位置: api/routes/content.py:195-230, api/routes/memory.py:30-75

参考资料层管理用户上传的文档，支持 PDF、Markdown 和纯文本格式，并自动转换为可检索的 Markdown 格式。

#### API 端点

#### 文件处理流程

flowchart LR
    A[原始文件] --> B{文件类型}
    B -->|PDF| C[Markdownify 转换]
    B -->|MD| D[直接存储]
    B -->|TXT| D
    C --> E[Markdown 存储]
    D --> E
    E --> F[Hindsight 索引]
    F --> G[可检索记忆]

文件大小限制: 10MB（可配置 MAX_REFERENCE_UPLOAD_BYTES）

存储结构：

REFERENCE_DIR/
├── document.pdf
├── document.md
└── document_images/    # PDF 提取的图像

第四层：运行历史 (Run Index Layer)

文件位置: api/routes/activity.py:55-75

运行层记录所有执行过的任务，包括输入、输出、评分和时间戳，为模式识别和性能分析提供数据基础。

索引数据结构 (memory/run_index.json)：

{
  "runs": [
    {
      "id": "run_01HZ...",
      "project": "citation-grade-eval",
      "campaign_id": "cmp_2qab",
      "phase": "complete",
      "score": 0.83,
      "model": "llama3.1:70b-instruct-q4_0",
      "started_at": "2024-01-15T10:30:00Z",
      "paused": null,
      "confidence": 0.91
    }
  ]
}

用途：

• 历史性能趋势分析
• 模型选择优化
• 失败模式识别
• 资源使用统计

第五层：反思记忆 (Hindsight Layer)

文件位置: api/routes/memory.py:30-75, core/note_discovery.py

反思层是最高级的记忆能力，支持自动反思、洞察提取和知识合成。

#### Hindsight 自动反思

API 端点: POST /hindsight/reflect/auto

触发时机：关键事件发生后自动调用，合成关于以下主题的洞察：

• 模型性能表现
• 常见失败模式
• 语言/任务类型趋势
• 优化建议

#### Hindsight 摄入

函数: hindsight_retain(content: str, source: str)

当新内容进入系统时（参考资料上传、运行完成等），自动摄入到 Hindsight 索引中：

hindsight_result = hindsight_retain(
    f"Reference document '{filename}' uploaded.\n\n{md_text[:3000]}",
    "api-upload"
)

#### NoteDiscovery 检索

文件位置: core/note_discovery.py

NoteDiscovery 是基于 Hindsight 记忆的规划增强组件，为 Planner 提供上下文感知的知识检索。

flowchart TD
    P[Planner 请求] --> ND[NoteDiscovery]
    ND --> QI[查询构造]
    QI --> HR[Hindsight 检索]
    HR --> IR[洞察结果]
    IR --> GF[目标过滤]
    GF --> CI[上下文注入]
    CI --> PR[规划输出]

活动时间线集成

文件位置: api/routes/activity.py:85-110

记忆系统通过活动时间线端点暴露聚合的事件流：

@router.get("/activity")
def get_activity(limit: int = 200, hours: int = 168) -> dict[str, Any]:

时间线事件来源：

查询参数：

配置与状态

内存路径配置

Hindsight 状态

HINDSIGHT_ENABLED = os.getenv("HINDSIGHT_ENABLED", "false").lower() == "true"

当 Hindsight 未启用时，相关 API 返回 503 状态码：

if not HINDSIGHT_ENABLED:
    raise HTTPException(status_code=503, detail="Hindsight is not enabled")

API 集成示例

上传参考资料

curl -X POST "http://localhost:8000/references" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@research_paper.pdf"

响应：

{
  "filename": "research_paper.pdf",
  "markdown_filename": "research_paper.md",
  "path": "/opt/ai-orchestrator/references/research_paper.pdf",
  "size": 2048576,
  "markdown_size": 45678,
  "conversion": {"pages": 12, "images": 3},
  "hindsight_ingested": true
}

获取活动时间线

curl "http://localhost:8000/activity?limit=50&hours=24"

相关发布版本

待办功能

根据 UI Console 的占位符设计，以下记忆相关功能正在规划中：

• Memory & Gates 页面 (/memory)
• 记忆可视化界面
• 手动记忆编辑
• 记忆导入/导出

安全考量

• 参考资料文件名通过 SAFE_FILENAME 正则验证，防止路径遍历攻击
• 上传文件大小限制为 10MB
• Markdown 内容通过 errors="replace" 处理编码问题
• 所有记忆路径使用绝对路径配置，避免相对路径注入风险

概述

数据流与清单验证是ai-orchestrator的核心机制，用于确保AI运行流程的可追溯性、完整性和可验证性。该系统通过清单（Manifest）结构记录每次运行的完整状态转换，并通过Merkle树提供加密级的数据完整性证明。

主要职责包括：

• 记录每个Agent的执行阶段和输出结果
• 提供清单内容的加密哈希验证
• 支持Campaign级别的批量运行管理
• 实现证据等级（citation-grade）的结果溯源

概述

Campaign（活动/实验）系统是 ai-orchestrator 的核心抽象层，用于组织、管理和追踪一组相关的自动化运行（Run）。从 v0.2.1-phase2.1 版本开始引入，并在 v0.3.6-phase3.6 中持续迭代完善。

核心职责：

• 将多个相关 Run 组织为逻辑单元（实验/基准测试）
• 支持参数网格搜索（Grid Search）实验设计
• 提供 HITL（Human-in-the-Loop）干预模式控制
• 追踪预算消耗与执行状态
• 生成可验证的 Merkle 根用于数据完整性保障

核心数据结构

Campaign 接口定义

// ui/console/src/lib/types.ts
interface Campaign {
  id: string;
  name: string;
  hitl_mode: HitlMode;
  status: "running" | "complete" | "aborted" | "paused";
  children: number;      // 子 Run 总数
  completed: number;    // 已完成 Run 数
  failed: number;       // 失败 Run 数
  started_at: string;
  budget: Budget;
  grid: Record<string, unknown[]>;
}

Budget 追踪结构

interface Budget {
  used: number;         // 已消耗预算（美元）
  total: number;        // 总预算上限
  percentage: number;    // 消耗百分比
  state: "healthy" | "warn" | "err";  // 健康状态
}

HITL 模式枚举

Campaign 支持五种 HITL 干预模式，用于控制自动化代理的人机协作程度：

资料来源：ui/console/src/lib/types.ts:24-34

Campaign 生命周期

状态流转图

graph TD
    A[创建 Campaign] --> B{初始化成功?}
    B -->|是| C[running]
    B -->|否| D[aborted]
    C --> E{所有子 Run 完成?}
    E -->|是| F[complete]
    E -->|否| G{用户暂停?}
    G -->|是| H[paused]
    G -->|否| I[继续执行]
    I --> E
    H --> J{用户恢复?}
    J -->|是| C
    J -->|否| H
    F --> K[生成报告]
    D --> L[记录失败原因]
    C --> M{Run 失败?}
    M -->|是| N[failed +1]
    M -->|否| O[completed +1]
    N --> E
    O --> E

状态说明

资料来源：ui/console/src/lib/mocks.ts:80-100

参数网格与实验设计

Campaign 的 grid 字段支持声明式参数扫描，允许多维度超参数实验：

// 示例网格配置
{
  "temperature": [0.3, 0.6, 0.9],
  "judge_model": ["llama3.1:70b", "qwen2.5:72b"]
}

上述配置会生成 3 × 2 = 6 个组合的 Run，Campaign 自动管理这些变体的执行与结果汇总。

已知的网格维度示例：

资料来源：ui/console/src/lib/mocks.ts:100-115

API 路由

创建 Campaign

POST /api/campaigns

请求体包含实验配置、网格定义和初始参数。API 验证后将创建 Campaign 记录并启动子 Run 的调度。

Campaign 干预端点

POST /api/campaigns/{campaign_id}/intervene

支持暂停、恢复或中止 Campaign 的执行。

时间线集成

Campaign 生命周期事件会聚合到活动时间线（Activity Timeline），包括：

• Campaign 创建事件
• Campaign 完成事件
• Campaign 中止事件

# api/routes/activity.py
def _campaign_events(cutoff: datetime) -> list[dict[str, Any]]:
    """从 memory/campaigns.json 提取 Campaign 生命周期事件"""
    # 生成 campaign-created / campaign-completed 类型事件

资料来源：api/routes/activity.py:55-80

后端存储结构

Campaign 数据使用 JSON-first 双重写入策略，同时写入 Postgres 持久化存储以确保数据安全。

前端 UI 集成

已实现页面

资料来源：ui/console/README.md:1-30

组件结构

ui/console/src/pages/
├── Dashboard.tsx
├── Runs.tsx          ← Run 列表（按 Campaign 分组）
├── RunDetail.tsx
├── Hitl.tsx         ← HITL 干预控制台
└── Stub.tsx         ← Campaigns / Logs / Memory / Config 占位

与 HITL 系统的集成

Campaign 的 hitl_mode 字段决定了整个实验的自动化程度：

graph LR
    A[Campaign hitl_mode] --> B{模式判断}
    B --> C[full_auto: 无干预]
    B --> D[checkpoint: 检查点暂停]
    B --> E[step_by_step: 每步暂停]
    B --> F[smartpause: 置信度触发]
    
    F --> G[planner.confidence < 0.50]
    G --> H[SmartPause 触发]
    H --> I[Operator 审批]
    I --> J[继续或编辑计划]

SmartPause 机制

当 hitl_mode 包含 SmartPause 逻辑时，系统会监控 planner 的置信度评分：

• 触发条件：confidence < 0.50
• UI 显示：Badge 显示 smartpause，ConfidenceBar 可视化当前置信度
• 干预方式：Operator 可以批准当前计划或编辑后重新提交

资料来源：ui/console/src/pages/Hitl.tsx:1-60

模板系统

Campaign 模板存储在 campaign_templates/ 目录，支持 YAML 格式声明：

# campaign_templates/example.yaml
name: citation-grade-eval
hitl_mode: full_auto
grid:
  temperature: [0.3, 0.6, 0.9]
  judge_model:
    - llama3.1:70b-instruct-q4_0
    - qwen2.5:72b-instruct-q4_K_M
budget:
  total: 6.0  # 美元

模板可复用于类似的实验场景，减少重复配置。

数据完整性验证

Campaign 与其子 Run 共享 Merkle 根验证机制：

orchestrator verify-campaign CAMPAIGN_ID

该命令递归验证 Campaign 下所有 Run 的 SHA256 清单，确保实验数据未被篡改。

资料来源：cli/main.py:50-80

常见工作流

1. 创建并执行基准测试

sequenceDiagram
    participant User
    participant API
    participant CampaignMgr
    participant RunScheduler
    
    User->>API: POST /campaigns (含 grid 配置)
    API->>CampaignMgr: 创建 Campaign 记录
    CampaignMgr->>CampaignMgr: 计算网格组合数 N
    CampaignMgr->>RunScheduler: 批量调度 N 个 Run
    RunScheduler-->>User: 返回 campaign_id
    loop 定期轮询
        User->>API: GET /campaigns/{id}
        API-->>User: 进度百分比、消耗预算
    end

2. HITL 干预流程

sequenceDiagram
    participant Run
    participant HITLService
    participant Operator
    participant UI
    
    Run->>HITLService: checkpoint 触发暂停
    HITLService->>UI: POST /ws 推送暂停事件
    UI-->>Operator: 显示 HITL Console
    Operator->>UI: 选择 approve/edit/reject
    UI->>HITLService: POST /runs/{id}/intervene
    HITLService->>Run: 恢复执行

版本演进

资料来源：README.md 和 Release Notes

待办功能

以下功能在 UI 中标记为 Stub 状态，预计后续迭代实现：

• 完整的 Campaign 管理页面
• 实时日志查看器
• Memory 可视化
• 高级配置面板

功能概述

引用级证据包的核心目标是将 AI 编排系统中的每一个关键决策、每一次模型调用、每一份引用来源封装为独立、可签名、可验证的证据单元。通过这种方式，用户可以在事后对任意一次运行的完整过程进行回溯验证。

该功能与以下模块深度集成：

架构设计

证据包结构

每个证据包包含以下核心组成部分：

graph TD
    A[证据包 Evidence Bundle] --> B[元数据 Metadata]
    A --> C[执行轨迹 Execution Trace]
    A --> D[引用来源 Citations]
    A --> E[评分数据 Scores]
    A --> F[签名与校验 Signatures]
    
    B --> B1[run_id 时间戳 项目信息]
    C --> C1[Planner 输出]
    C --> C2[Generator 输出]
    C --> C3[Judge 裁决]
    D --> D1[Reference 文档]
    D --> D2[Markdown 转换内容]
    E --> E1[citation_grade 评分]
    E --> E2[factuality 评分]
    F --> F1[HMAC 签名]
    F --> F2[时间戳验证]

模块职责

证据生成流程

构建阶段（Build Phase）

证据包的生成在每次运行的生命周期中按需触发：

graph LR
    A[Run 启动] --> B{Phase 1: Planner}
    B --> C[生成执行计划]
    C --> D[记录到轨迹]
    D --> E{Phase 2: Generator}
    E --> F[生成内容]
    F --> G[提取引用来源]
    G --> H{Phase 3: Judge}
    H --> I[评分裁决]
    I --> J[证据包构建触发]
    J --> K[签名与验证]
    K --> L[存储到 Vault]

引用级评分机制

证据包内置引用质量评分系统，与 Judge 模块联动：

# 评分阈值（来自 ConfidenceBar 组件）
# 资料来源：ui/console/src/components/ConfidenceBar.tsx:7-9

THRESHOLDS = {
    "ok":   0.7,   # >= 0.7 引用质量合格
    "warn": 0.4,   # 0.4 - 0.7 需人工复核
    "err":  0.0    # < 0.4 引用质量不合格
}

评分数据作为证据包的核心组成部分被持久化存储，供后续审计使用。

RO-Crate 格式支持

证据包支持导出为 RO-Crate 格式，这是一种用于打包研究数据的标准化容器格式。RO-Crate 确保证据包可以在不同系统之间互操作。

RO-Crate 结构

签名与验证机制

签名流程

证据包在存储前必须经过签名，确保内容未被篡改：

graph TD
    A[构建证据包] --> B[计算内容哈希]
    B --> C[生成 HMAC 签名]
    C --> D[附加时间戳]
    D --> E[存储证据包]
    E --> F[Vault 持久化]

验证流程

任何时候都可以对已存储的证据包进行验证：

1. 重新计算内容哈希
2. 对比签名中的哈希值
3. 验证时间戳的合理性
4. 检查检查清单完整性

验证失败时，系统将拒绝使用该证据包进行后续裁决。

检查清单（Checklists）

证据包附带完整性检查清单，确保每个必需组件都已包含：

API 端点

证据包通过以下后端 API 暴露：

与 Campaign 的关联

证据包与 Campaign（战役）抽象深度集成。在 Campaign 级别，系统可以：

• 聚合多个 Run 的证据包
• 生成 Campaign 级别的汇总报告
• 跨 Run 追踪引用来源趋势
• 验证 Campaign 的 Merkle 根

# 使用 CLI 验证 Campaign 的 Merkle 根
python -m cli.main verify-campaign <CAMPAIGN_ID>

存储与持久化

证据包存储采用多层策略：

使用场景

学术写作辅助

在学术场景中，引用级证据包可以证明 AI 生成内容的每个论断都有可追溯的来源，便于论文审核。

合规审计

对于需要 AI 决策可解释性的行业（如金融、医疗），证据包提供了完整的审计轨迹。

模型评估

通过对比不同模型的证据包评分，可以系统性地评估模型在引用质量方面的表现差异。

版本历史

注意事项

• 证据包生成会增加运行延迟，建议在批量评估时异步处理
• RO-Crate 导出不支持大于 100MB 的引用文档
• 签名密钥轮换需配合 rotate-secrets CLI 命令
• SmartPause 暂停的 Run 不会生成中间证据包，只在恢复或终止时生成

概述

HITL（Human-in-the-Loop，人机回环）干预系统是 ai-orchestrator 的 Phase 3.1 和 Phase 3.2 阶段引入的核心功能，旨在为 AI 自动化流程提供可控的人工介入机制。该系统包含两种暂停触发方式：HITL 阶段检查点（HITL Checkpoint） 和 SmartPause（智能暂停）。

SmartPause 于 v0.3.2-phase3.2 发布，是 HITL 干预模式的补充功能，通过置信度阈值自动检测低质量规划并触发人工审查。HITL 干预模式于 v0.3.1-phase3.1 发布，定义了五种不同的介入级别。

资料来源：v0.3.1-phase3.1，v0.3.2-phase3.2

架构设计

系统组件

graph TD
    subgraph 后端层
        HITL[core/hitl.py<br/>HITL 控制模块]
        RUNS[api/routes/runs.py<br/>运行路由]
        RUN_INDEX[memory/run_index.json<br/>运行索引]
    end
    
    subgraph 前端层
        HITL_PAGE[ui/console/src/pages/Hitl.tsx<br/>HITL 控制台页面]
        CONFIDENCE[ui/console/src/components/ConfidenceBar.tsx<br/>置信度条形图]
        TYPES[ui/console/src/lib/types.ts<br/>类型定义]
    end
    
    subgraph 干预操作
        APPROVE[approve<br/>批准]
        EDIT[edit<br/>编辑]
        SKIP[skip<br/>跳过]
        ABORT[abort<br/>中止]
    end
    
    RUNS -->|paused 状态| HITL
    HITL -->|confidence 阈值| SmartPause
    HITL_PAGE -->|干预请求| RUNS
    CONFIDENCE -->|confidence 可视化| HITL_PAGE
    TYPES -->|类型约束| HITL_PAGE

暂停状态流转

stateDiagram-v2
    [*] --> Running : 正常运行
    Running --> SmartPause : confidence < 0.50
    Running --> HitlCheckpoint : post_planner 阶段
    HitlCheckpoint --> HitlCheckpoint : hitl_mode=checkpoint
    SmartPause --> Running : 人工批准/编辑
    HitlCheckpoint --> Running : 人工批准/编辑
    HitlCheckpoint --> Aborted : abort 操作
    SmartPause --> Aborted : abort 操作
    Running --> Complete : 所有阶段完成
    Running --> Failed : 执行失败

HITL 干预模式

五种介入级别

资料来源：ui/console/src/lib/types.ts:41-47

干预操作类型

资料来源：ui/console/src/lib/types.ts:63-67

SmartPause 机制

触发条件

SmartPause 在 planner 阶段输出后触发，当 置信度（confidence）低于 0.50 阈值时，系统自动暂停并等待人工审查。

# SmartPause 触发逻辑
if planner_confidence < 0.50:
    trigger_smartpause()

资料来源：ui/console/src/pages/Hitl.tsx:14-15

置信度可视化

ConfidenceBar 组件采用三级颜色编码方案：

资料来源：ui/console/src/components/ConfidenceBar.tsx:6-8

export function ConfidenceBar({ value, w = 80 }: { value: number; w?: number }) {
  const tone: Tone = value >= 0.7 ? "ok" : value >= 0.4 ? "warn" : "err";
  // ...
}

SmartPause vs HITL Checkpoint 对比

资料来源：ui/console/src/lib/types.ts:49-58

运行阶段定义

资料来源：ui/console/src/lib/types.ts:31-38

后端 API 接口

干预端点

POST /runs/{run_id}/intervene

请求体格式：

{
  "action": "approve" | "edit" | "skip" | "abort",
  "payload": "<edited json>"  // 仅 action === "edit" 时需要
}

响应示例：

{
  "run_id": "run_01HZK4ABNR6P7VCT2K",
  "action": "approve",
  "queued": true
}

资料来源：api/routes/runs.py:198-214

干预后的状态更新

当干预操作成功后，后端会执行以下操作：

1. 清除 paused 标志 - 移除 paused 字段（设置为 None）
2. 通知 SmartPause 轮询循环 - 确保暂停状态的 run 也能解除阻塞
3. 队列通知 - 干预请求入队等待处理

# 清除暂停标志以解锁 SmartPause 轮询循环
_update_run_status(run_id, paused=None)

资料来源：api/routes/runs.py:209-212

日志尾部接口

GET /logs/{run_id}/tail?lines=80

返回指定 run 的最后 N 行日志内容。

资料来源：api/routes/runs.py:217-232

前端 HITL 控制台

页面路由

HITL 控制台页面位于 /hitl 路由，是操作员进行人工干预的主要界面。

资料来源：ui/console/README.md

界面布局

graph LR
    subgraph HITL 控制台
        Header[Run 元信息栏<br/>ID · Badge · Phase · ConfidenceBar]
        Meta[元数据网格<br/>project · campaign · model · waiting]
        Planner[Planner 输出区<br/>JSON/Edit 编辑器]
        Alert[告警信息区<br/>SmartPause / Checkpoint 说明]
        Action[操作按钮区<br/>approve · edit · skip · abort]
    end

条件渲染逻辑

// SmartPause 识别条件
const isSmart = run.paused === "smartpause";

// 显示内容差异
{isSmart
  ? "SmartPause triggered — planner confidence below threshold."
  : `Checkpoint reached — campaign hitl_mode=${run.hitl_mode} requires explicit go-ahead.`}

资料来源：ui/console/src/pages/Hitl.tsx:12-23

编辑模式

当选择 edit 操作时，页面显示可编辑的 textarea：

<textarea
  value={editText}
  onChange={(e) => setEditText(e.target.value)}
  spellCheck={false}
  className="w-full min-h-[220px] p-3 mono text-xs..."
/>

编辑内容作为 JSON payload 提交到干预接口。

运行数据结构

Run 接口定义

interface Run {
  id: string;
  project: string;
  campaign_id: string;
  phase: Phase;
  score: number | null;
  model: string;
  target: string;
  started_at: string;
  paused: PausedState;
  hitl_mode: HitlMode;
  confidence?: number;  // SmartPause 置信度
}

PausedState 类型

type PausedState = null | "smartpause" | `hitl:${string}`;

状态含义：

• null - 正常运行
• "smartpause" - SmartPause 触发的暂停
• "hitl:${phase}" - 指定阶段的人工检查点暂停

注意：后端存储的是检查点阶段名称（如 hitl:post_planner），而非 HITL 模式本身。UI 从 Run.hitl_mode 字段读取实际模式。

资料来源：ui/console/src/lib/types.ts:49-58

干预操作流程

完整交互序列

sequenceDiagram
    participant Ops as 操作员
    participant UI as HITL 控制台
    participant API as /runs/{id}/intervene
    participant Core as core/hitl.py
    participant Run as 运行引擎

    Note over Run: planner 阶段完成<br/>confidence = 0.31 < 0.50
    Run->>UI: paused: "smartpause"
    Ops->>UI: 查看 planner 输出
    Ops->>UI: 选择 "edit" 操作
    UI->>API: POST {action: "edit", payload: "<edited json>"}
    API->>Core: 验证并入队干预
    Core->>Run: 清除 paused 状态
    Core->>Run: 应用编辑后的规划
    Run->>UI: phase 更新为 generator

Mock 数据示例

{
  id: "run_01HZK3W5J1DMFXY8VL",
  project: "rag-router-bench",
  campaign_id: "cmp_91xs",
  phase: "post_planner",
  score: null,
  model: "qwen2.5:7b-instruct-q5_K_M",
  target: "homelab-3090",
  started_at: ago(1180),
  paused: "smartpause",
  hitl_mode: "smartpause",  // UI 别名
  confidence: 0.31,          // 触发 SmartPause
}

资料来源：ui/console/src/lib/mocks.ts

活动时间线集成

HITL 干预事件会记录到活动时间线（Activity Timeline），供操作员追踪操作历史。

时间线事件类型：

资料来源：api/routes/activity.py

配置与阈值

SmartPause 置信度阈值

Campaign 级别的 HITL 配置

每个 Campaign 在创建时可指定 hitl_mode，决定该 Campaign 下所有 Run 的默认干预策略：

interface Campaign {
  id: string;
  name: string;
  hitl_mode: HitlMode;  // 继承给子 Run
  status: "running" | "complete" | "aborted" | "paused";
  // ...
}

最佳实践

何时使用 SmartPause

• 推荐场景： 新模型、新任务类型、高不确定性任务
• 不推荐场景： 已验证的标准流程、高吞吐量批量任务

干预操作建议

性能考量

• post_planner 检查点是硬性门控，不会产生任何 token 消耗
• Generator 阶段仅在干预批准后才会启动
• 干预队列支持容量限制，超出时返回 409 状态码

资料来源：api/routes/runs.py:198-205

相关文档

• ARCHITECTURE.md - 系统架构总览
• RUNBOOK.md - 运维操作手册
• CLAUDE.md - AI 助手编辑指南

概述

Dual Ollama 路由是 ai-orchestrator 的核心能力之一，用于在多个 Ollama 服务器实例之间智能分配 LLM 请求。该机制支持模型感知 URL 缓存、judge-model 断路器以及单例刷新模式，确保在多目标沙箱执行和复杂推理工作流中的高可用性和资源优化。

Dual Ollama 路由的主要职责包括：

• 多实例管理：支持配置多个 Ollama 服务器 URL，按需路由请求
• 模型缓存：维护模型到服务器 URL 的映射缓存，避免重复查找
• 断路器保护：对 judge-model 实现熔断机制，防止故障扩散
• 健康监控：实时检测各 Ollama 实例的可用性和状态

资料来源：README.md

架构设计

系统上下文

graph TD
    subgraph "Orchestrator Core"
        A[请求入口] --> B[模型路由层]
        B --> C{断路器检查}
        C -->|正常| D[Ollama 实例 1]
        C -->|正常| E[Ollama 实例 2]
        C -->|触发| F[Judge 断路器]
        D --> G[响应处理]
        E --> G
        F --> H[降级策略]
    end
    
    subgraph "健康监控"
        I[Health Check] --> J[Ollama 状态]
        J --> K[Topbar UI]
    end

核心组件

健康检查集成

健康端点实现

Ollama 路由与系统健康检查紧密集成，通过 /health 端点暴露各实例状态：

# api/routes/health.py
requests.get(f"{url}/api/tags", timeout=5)
ollama_status[name] = {
    "url": url,
    "status": "online" if r.status_code == 200 else f"error ({r.status_code})",
    "model_count": len(r.json().get("models", [])) if r.status_code == 200 else 0,
}

资料来源：api/routes/health.py:1-50

健康数据结构

// ui/console/src/lib/types.ts
export interface Health {
  orchestrator: "ok" | "degraded" | "down";
  ollama: "ok" | "degraded" | "down";
  hindsight: "ok" | "degraded" | "down";
  postgres: "ok" | "degraded" | "down";
  redis: "ok" | "degraded" | "down";
  tempo: "ok" | "degraded" | "down";
  prometheus: "ok" | "degraded" | "down";
  dvc: "ok" | "degraded" | "down";
  uptime_s: number;
  version: string;
}

资料来源：ui/console/src/lib/types.ts

前端状态展示

Topbar 健康指示器

操作控制台顶部导航栏实时显示 Ollama 连接状态：

// ui/console/src/shell/Topbar.tsx
<LiveDot tone={health?.ollama === "ok" ? "ok" : "err"} animated={false} />
<span className="mono text-fg-1">ollama</span>

资料来源：ui/console/src/shell/Topbar.tsx

状态指示灯含义

配置管理

配置文件结构

项目根目录的 config.json 包含 Ollama 服务器配置：

{
  "ollama_servers": {
    "default": "http://localhost:11434",
    "gpu-1": "http://gpu-server:11434",
    "gpu-2": "http://gpu-server-2:11434"
  }
}

环境变量

工作流程

请求路由流程

sequenceDiagram
    participant C as Client
    participant R as Router
    participant CB as CircuitBreaker
    participant O1 as Ollama-1
    participant O2 as Ollama-2

    C->>R: LLM 请求 (model: xxx)
    R->>R: 查询模型缓存
    alt 缓存命中
        R->>CB: 检查断路器状态
        alt 断路器关闭
            R->>O1: 转发请求
            O1-->>R: 响应
        else 断路器开启
            R->>O2: 降级到备用实例
        end
    else 缓存未命中
        R->>R: 单例刷新缓存
        R->>CB: 初始化断路器
    end
    R-->>C: 返回响应

模型感知的 URL 缓存

路由层维护模型名称到服务器 URL 的映射缓存：

1. 首次请求：查询目标模型对应的 Ollama 实例 URL
2. 缓存命中：直接使用缓存的 URL 路由请求
3. 单例刷新：缓存更新采用单一刷新模式，避免并发竞争

Judge-Model 断路器

对于评分/判断类请求（judge-model），系统实现熔断保护：

与其他模块的交互

调用链

graph LR
    subgraph "LLM 层"
        A[llm/ollama.py] --> B[Ollama 路由]
    end
    
    subgraph "核心层"
        B --> C[core/budget.py]
        B --> D[core/llm_call_log.py]
    end
    
    subgraph "API 层"
        D --> E[api/routes/health.py]
    end
    
    subgraph "UI 层"
        E --> F[Topbar 健康显示]
    end

故障排查

常见问题

健康检查命令

# 检查 Ollama 服务状态
curl http://localhost:11434/api/tags

# 通过 orchestrator 健康端点检查
curl http://localhost:8000/health

# 查看详细服务状态
curl http://localhost:8000/health | jq '.services.ollama'

版本历史

参考链接

• 项目主 README
• 架构文档 ARCHITECTURE.md
• 运行手册 RUNBOOK.md
• 快速开始指南

Pitfall Log / 踩坑日志

项目：ernesto01louis/ai-orchestrator

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1225805640 | https://github.com/ernesto01louis/ai-orchestrator | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1225805640 | https://github.com/ernesto01louis/ai-orchestrator | last_activity_observed missing

3. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1225805640 | https://github.com/ernesto01louis/ai-orchestrator | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1225805640 | https://github.com/ernesto01louis/ai-orchestrator | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1225805640 | https://github.com/ernesto01louis/ai-orchestrator | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1225805640 | https://github.com/ernesto01louis/ai-orchestrator | release_recency=unknown