# https://github.com/ernesto01louis/ai-orchestrator 项目说明书
生成时间：2026-05-31 22:52:45 UTC
## 目录
- [项目介绍](#page-project-intro)
- [快速开始](#page-quickstart)
- [版本发布历史](#page-release-history)
- [系统架构](#page-system-architecture)
- [五层记忆系统](#page-5-layer-memory)
- [数据流与清单验证](#page-data-flow)
- [Campaign 系统](#page-campaign-system)
- [引用级证据包](#page-evidence-bundles)
- [HITL 干预与 SmartPause](#page-hitl-smartpause)
- [Dual Ollama 路由](#page-ollama-routing)
## 项目介绍
### 相关页面
相关主题：[快速开始](#page-quickstart), [系统架构](#page-system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/README.md)
- [VISION.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/VISION.md)
- [ARCHITECTURE.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ARCHITECTURE.md)
- [ui/console/src/lib/types.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts)
- [api/routes/memory.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/memory.py)
# 项目介绍
## 概述
ai-orchestrator 是一个基于 Ollama 的 AI 代理编排框架，旨在为 AI 模型执行提供可观测、可干预、可量化的生产级工作流环境。该项目采用"平台而非集线器"的设计原则，强调与本地工具链的深度集成而非简单的 API 聚合。
资料来源：[README.md]()
## 核心设计理念
### 平台而非集线器
传统 AI 代理框架往往将所有功能集中于单一服务，形成功能耦合的"集线器"。ai-orchestrator 反其道而行，采用模块化架构，每个组件专注于特定职责，通过标准化接口通信。这种设计使得系统各部分可以独立演进、测试和部署。
资料来源：[VISION.md]()
### 关键设计目标
| 目标 | 描述 |
|------|------|
| 可观测性 | 完整的运行追踪、证据收集和状态可视化 |
| 人类干预 | 多层次的 HITL（Human-in-the-Loop）机制 |
| 知识积累 | Hindsight 知识图谱与 Obsidian 笔记系统集成 |
| 资源隔离 | SSH 沙箱执行环境，支持多目标部署 |
| 质量保证 | 评分员（Judge）模型与引用等级评估 |
资料来源：[README.md]()
## 系统架构
### 整体架构图
```mermaid
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
```
### 核心组件职责
| 组件 | 职责 | 源码位置 |
|------|------|----------|
| Planner | 任务分解、工具选择、计划生成 | `core/planner.py` |
| Generator | 代码生成、文档撰写、执行脚本 | `core/generator.py` |
| Judge | 评分评估、引用等级验证、事实性检查 | `core/judge.py` |
| Optimizer | 参数调优、策略迭代、温度/采样优化 | `core/optimizer.py` |
| Memory | 运行索引、负向记忆、提示模板索引 | `memory_pkg/` |
| Hindsight | 知识图谱、自动反思、模型性能分析 | `hindsight/` |
资料来源：[ARCHITECTURE.md]()
## 核心功能模块
### 1. Campaign 抽象层
Campaign 是项目的核心抽象概念，用于组织和管理多个相关的 AI 执行任务。每个 Campaign 包含：
- **运行批次**：一组逻辑关联的 Run 实例
- **配置复用**：共享的模型选择、目标配置、评估标准
- **生命周期管理**：创建、执行、暂停、恢复、终止的完整状态机
```mermaid
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 引入了完整的人类在环干预机制，支持五种干预模式：
| 模式 | 描述 | 干预时机 |
|------|------|----------|
| `full_auto` | 全自动执行，无人工干预 | 无 |
| `gate_only` | 仅在关键节点介入 | 策略门 |
| `checkpoint` | 检查点暂停等待确认 | 后置规划器 |
| `step_by_step` | 每步确认后执行 | 每个阶段 |
| `co_pilot` | AI 与人类协作模式 | 实时协作 |
资料来源：[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 连接到远程服务器实现代码隔离执行：
```mermaid
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. 工具注册与调度
| 组件 | 功能 |
|------|------|
| Tool Registry | 工具注册表管理，支持动态增删改查 |
| Gates Layer | 基于学习的安全策略层，控制工具调用权限 |
资料来源：[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 实例经历以下执行阶段：
| Phase | 说明 | 可干预 |
|-------|------|--------|
| `planner` | 任务规划与分解 | 是 |
| `post_planner` | 规划输出验证 | 是 |
| `generator` | 代码/内容生成 | 是 |
| `judge` | 质量评估 | 是 |
| `optimizer` | 参数调优 | 是 |
| `complete` | 执行完成 | 否 |
| `failed` | 执行失败 | 否 |
资料来源：[ui/console/src/lib/types.ts:1-10]()
## 技术栈
### 后端技术
| 技术 | 用途 |
|------|------|
| FastAPI | REST API 框架 |
| Uvicorn | ASGI 服务器 |
| WebSocket | 实时日志与状态推送 |
| Pydantic | 数据验证与序列化 |
### 前端技术
| 技术 | 用途 |
|------|------|
| React 18 | UI 框架 |
| Vite | 构建工具 |
| TypeScript | 类型安全 |
| Tailwind CSS | 样式系统 |
### 监控与可观测性
| 技术 | 用途 |
|------|------|
| Prometheus | 指标采集（`/metrics`） |
| WebSocket | 实时日志流 |
| run_index.json | 运行历史索引 |
资料来源：[ui/console/README.md](), [README.md]()
## 快速开始
```bash
# 克隆仓库
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]()
## 文档体系
| 文档 | 受众 | 用途 |
|------|------|------|
| VISION.md | 所有读者 | 项目愿景与设计原则 |
| ARCHITECTURE.md | 开发者 | 模块布局与数据流 |
| ROADMAP.md | 贡献者 | 阶段性任务列表 |
| CLAUDE.md | AI 助手 | 内部开发指南 |
| CONTRIBUTING.md | 贡献者 | 本地开发与约定 |
| RUNBOOK.md | 运维 | 服务控制与恢复操作 |
| SECURITY.md | 安全团队 | 威胁模型与漏洞报告 |
资料来源：[README.md]()
## 版本历史亮点
| 版本 | 阶段 | 重要特性 |
|------|------|----------|
| v0.3.6 | Phase 3.6 | Campaign 抽象完善、证据等级包 |
| v0.3.3 | Phase 3.3 | SmartPause、NoteDiscovery 规划器 |
| v0.3.1 | Phase 3.1 | HITL 干预模式系统 |
| v0.2.x | Phase 2.x | 基础运行框架与评分系统 |
| v0.1.x | Phase 1.x | 项目初始化与核心抽象 |
资料来源：[社区发布记录](https://github.com/ernesto01louis/ai-orchestrator/releases)
## 适用场景
ai-orchestrator 特别适用于以下场景：
1. **需要人类监督的 AI 执行**：通过 HITL 机制确保关键决策经过人工确认
2. **多模型对比研究**：Campaign 支持批量运行与对比分析
3. **代码质量要求严格的工程**：引用等级评估与事实性验证
4. **资源受限的私有化部署**：支持本地 Ollama 与 SSH 沙箱
5. **持续优化的生产工作流**：Optimizer 与参数调优机制
---
## 快速开始
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/README.md)
- [config.example.json](https://github.com/ernesto01louis/ai-orchestrator/blob/main/config.example.json)
- [.env.example](https://github.com/ernesto01louis/ai-orchestrator/blob/main/.env.example)
- [RUNBOOK.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/RUNBOOK.md)
- [CONTRIBUTING.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/CONTRIBUTING.md)
- [api/routes/health.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/health.py)
# 快速开始
本文档面向希望快速部署和运行 ai-orchestrator 的开发者和运维人员。快速开始指南涵盖从环境准备到服务验证的完整流程，帮助用户在最短时间内启动本地开发环境或小型生产实例。
## 系统概述
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 标签）
## 前置要求
| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Python | 3.11+ | 推荐使用 pyenv 或 conda 管理 |
| Node.js | 18+ | 仅当需要构建前端 UI 时 |
| pnpm | 8+ | UI 控制台包管理器 |
| Ollama | 最新版 | 本地 LLM 推理引擎 |
| SSH | OpenSSH 8+ | 沙箱执行目标连接 |
| 系统内存 | 16GB+ | 取决于运行的模型大小 |
## 环境准备
### 克隆代码仓库
```bash
git clone https://github.com/ernesto01louis/ai-orchestrator.git
cd ai-orchestrator
```
### 创建 Python 虚拟环境
```bash
python3.11 -m venv venv
source venv/bin/activate # Linux/macOS
# 或: venv\Scripts\activate # Windows
```
### 安装依赖
```bash
pip install -r requirements.txt
```
资料来源：[README.md:Quickstart]()
## 配置
项目需要两类配置文件才能正常运行。
### 服务配置（config.json）
复制配置模板并编辑 Ollama URL 和 SSH 目标：
```bash
cp config.example.json config.json
```
关键配置项说明：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `ollama.base_url` | string | `http://localhost:11434` | Ollama 服务地址 |
| `ollama.models[]` | array | - | 可用模型列表 |
| `targets[].host` | string | - | SSH 目标主机 |
| `targets[].user` | string | - | SSH 用户名 |
| `targets[].python_path` | string | `python3` | Python 解释器路径 |
| `campaigns_dir` | string | `./campaigns` | Campaign 存储目录 |
| `projects_dir` | string | `./projects` | 项目存储目录 |
| `memory_dir` | string | `./memory` | 内存数据目录 |
### 环境变量（.env）
复制环境变量模板并填写必要值：
```bash
cp .env.example .env
```
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `GOTIFY_TOKEN` | 是 | Gotify 通知服务的访问令牌 |
| `GOTIFY_ENDPOINT` | 否 | Gotify 服务器地址 |
| `HINDSIGHT_ENABLED` | 否 | 是否启用 Hindsight 知识图谱（默认 true） |
| `NOTE_DISCOVERY_URL` | 否 | NoteDiscovery 服务地址 |
| `VITE_API_BASE` | 否 | 前端 API 基础 URL |
| `VITE_WS_URL` | 否 | 前端 WebSocket 地址 |
资料来源：[README.md:Quickstart]()
## 启动服务
### 后端 API 服务
使用 uvicorn 启动 FastAPI 应用：
```bash
uvicorn app:app --host 0.0.0.0 --port 8000
```
服务将监听在 `http://0.0.0.0:8000`。
### 健康检查
验证服务是否正常运行：
```bash
curl http://127.0.0.1:8000/health
```
正常响应示例：
```json
{
"status": "healthy",
"version": "0.3.6-phase3.6",
"ollama_connected": true,
"timestamp": "2024-01-15T10:30:00Z"
}
```
资料来源：[README.md:Quickstart]()
### 前端 UI 控制台（可选）
如需使用 Web UI，进入控制台目录并启动开发服务器：
```bash
cd ui/console
pnpm install
pnpm dev
```
| 页面 | 路由 | 功能 |
|------|------|------|
| Dashboard | `/dashboard` | 系统概览和统计 |
| Runs list | `/runs` | 运行列表 |
| Run detail | `/runs/:runId` | 单次运行详情 |
| HITL Console | `/hitl` | 人工干预控制台 |
| Campaigns | `/campaigns` | Campaign 管理（开发中） |
UI 主题通过 `localStorage.theme` 和 `data-theme` 属性控制，支持 `default` 和 `personal` 两套皮肤。
## 服务控制
详细的运维任务参考 [RUNBOOK.md](RUNBOOK.md)。
### 常用命令
| 操作 | 命令 | 说明 |
|------|------|------|
| 启动服务 | `uvicorn app:app --host 0.0.0.0 --port 8000` | 后端服务 |
| 健康检查 | `curl http://127.0.0.1:8000/health` | 验证服务状态 |
| 查看日志 | `tail -f logs/orchestrator.log` | 实时日志 |
| 日志轮转 | `python -m cli.main rotate-logs` | gzip 1天+日志，删除 90天+日志 |
## 项目结构
```
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]
```
| 阶段 | 说明 | 可干预点 |
|------|------|----------|
| `planner` | 任务分解与工具选择 | 是 |
| `post_planner` | Planner 输出审查 | 是（SmartPause） |
| `generator` | 代码/内容生成 | 否 |
| `judge` | 质量评分与事实性检查 | 否 |
| `optimizer` | 根据评分调整参数 | 是 |
| `complete` | 运行完成 | - |
| `failed` | 运行失败 | - |
### HITL 干预模式
| 模式 | 行为 | 适用场景 |
|------|------|----------|
| `full_auto` | 完全自动，无人工干预 | 批量生产 |
| `gate_only` | 仅在关键门控点暂停 | 质量门禁 |
| `checkpoint` | post_planner 硬检查点 | 高风险任务 |
| `step_by_step` | 每个阶段都需要批准 | 调试模式 |
| `co_pilot` | AI 与人工协同 | 复杂任务 |
### 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]()
## 后续步骤
| 文档 | 内容 |
|------|------|
| [VISION.md](VISION.md) | 项目愿景与设计原则 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 模块布局与数据流 |
| [RUNBOOK.md](RUNBOOK.md) | 运维任务与服务控制 |
| [ROADMAP.md](ROADMAP.md) | 阶段性开发计划 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 开发规范与本地调试 |
| [docs/PLUGINS.md](docs/PLUGINS.md) | 可选集成（Blender、SkyPilot 等） |
---
## 版本发布历史
### 相关页面
相关主题：[Campaign 系统](#page-campaign-system), [引用级证据包](#page-evidence-bundles), [HITL 干预与 SmartPause](#page-hitl-smartpause)
相关源码文件
以下源码文件用于生成本页说明：
- [CHANGELOG.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/CHANGELOG.md)
- [ROADMAP.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ROADMAP.md)
- [README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/README.md)
- [ui/console/src/lib/types.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts)
- [ui/console/src/components/ConfidenceBar.tsx](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/components/ConfidenceBar.tsx)
- [ui/console/src/pages/Hitl.tsx](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/pages/Hitl.tsx)
# 版本发布历史
## 概述
ai-orchestrator 采用**阶段式版本发布策略**，版本号格式为 `vX.Y.Z-phaseN.M`，其中：
- `X.Y.Z` 为语义化版本号
- `N.M` 表示当前开发的阶段编号
该项目目前处于 **Phase 3** 阶段，核心功能围绕 AI 编排引擎、Campaign 管理、人机协作（HITL）和智能暂停（SmartPause）机制展开。
资料来源：[README.md:1-10]()
## 版本号命名规范
| 格式 | 含义 | 示例 |
|------|------|------|
| `v{语义化版本}-phase{阶段号}.{子阶段号}` | 主版本号 + 阶段编号 | v0.3.6-phase3.6 |
| phase 前缀 | 表示当前处于哪个开发阶段 | phase1.1, phase3.1 |
阶段编号与功能模块的对应关系：
| 阶段 | 功能域 | 说明 |
|------|--------|------|
| Phase 1.x | Campaign 抽象层 | 任务编排基础架构 |
| Phase 2.x | 证据与评估系统 | 引用级证据包、评分机制 |
| Phase 3.x | HITL 与智能控制 | 人机协作干预模式 |
资料来源：[ROADMAP.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ROADMAP.md)
## 发布时间线
### Phase 2 系列 (v0.2.x)
| 版本 | 标签 | 主要变更 |
|------|------|----------|
| v0.2.1-phase2.1 | :label: | Campaign 抽象层初始实现 |
| v0.2.2-phase2.2 | :label: | CI 流程优化，ruff 静态检查集成 |
| v0.2.3-phase2.3 | :label: | 证据包功能增强 |
| v0.2.4-phase2.4 | :label: | 缺陷修复与稳定性改进 |
| v0.2.5-phase2.5 | :label: | Phase 2 功能冻结 |
**Phase 2 核心贡献：**
- `feat(campaign)`: Phase 1.1 — Campaign 抽象层 资料来源：[PR #1](https://github.com/ernesto01louis/ai-orchestrator/pull/1)
- `chore(ci)`: 用正确修复替代临时方案，ruff 成为阻塞性检查 资料来源：[PR #2](https://github.com/ernesto01louis/ai-orchestrator/pull/2)
- `feat`: Phase 1.2 — 引用级证据包
### Phase 3 系列 (v0.3.x)
#### v0.3.1-phase3.1 — HITL 干预模式
| 功能 | 说明 |
|------|------|
| HITL 干预模式 | 支持 5 种人机协作干预级别 |
| 暂停状态类型 | `null` / `"smartpause"` / `"hitl:{phase}"` |
**HITL 模式定义** (`types.ts`):
```typescript
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 的核心特性，当规划器置信度低于阈值时自动触发暂停：
| 置信度范围 | UI 状态 | 颜色标识 |
|-----------|---------|----------|
| ≥ 0.70 | ok (绿色) | 正常执行 |
| 0.40–0.70 | warn (黄色) | 警告提示 |
| < 0.40 | err (红色) | 高风险暂停 |
**置信度可视化组件** (`ConfidenceBar.tsx`):
```typescript
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 规划器
| 功能 | 说明 |
|------|------|
| REST pivot | 基于 REST 的规划器调用 |
| NoteDiscovery | 利用笔记数据进行上下文增强 |
| 心理模型集成 | 从 vault 和 memory 加载元数据 |
资料来源：[PR #19](https://github.com/ernesto01louis/ai-orchestrator/pull/19)
#### v0.3.4-phase3.4 至 v0.3.6-phase3.6
最新版本保持 Phase 3.3 的核心功能集，聚焦于：
- Campaign 抽象层稳定化
- CI/CD 流程规范化
- 证据包功能完善
## 功能阶段演进图
```mermaid
graph LR
A[v0.2.1] --> B[Phase 2.2-2.5]
B --> C[v0.3.1]
C --> D[Phase 3.1
HITL干预模式]
D --> E[v0.3.2]
E --> F[Phase 3.2
SmartPause]
F --> G[v0.3.3]
G --> H[Phase 3.3
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` 路由：
```mermaid
graph TD
A[Run 暂停等待] --> B{暂停类型?}
B -->|SmartPause| C[显示置信度条]
B -->|HITL Checkpoint| D[显示干预选项]
C --> E[操作员决策]
D --> E
E --> F[approve
reject
edit]
F --> G[POST /runs/:id/intervene]
```
**干预操作 API** (`ui/console/src/pages/Hitl.tsx`):
| 操作 | 请求体 | 说明 |
|------|--------|------|
| approve | `{action: "approve"}` | 批准当前计划 |
| reject | `{action: "reject"}` | 拒绝并重新规划 |
| edit | `{action: "edit", payload: }` | 编辑后继续 |
资料来源：[ui/console/src/pages/Hitl.tsx:30-40]()
## 版本间迁移
### 升级到 v0.3.x 的注意事项
1. **HITL 模式变化**
- 后端 `paused` 字段现在存储 `hitl:{phase}` 格式
- UI 需要从 `Run.hitl_mode` 读取实际模式
2. **SmartPause 阈值**
- 默认置信度阈值：0.50
- 可在 `core/hitl.py` 中自定义
3. **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 标签切换：
```bash
git checkout v0.2.5-phase2.5
```
## 相关资源
| 资源 | 链接 |
|------|------|
| 完整变更日志 | [CHANGELOG.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/CHANGELOG.md) |
| 开发路线图 | [ROADMAP.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ROADMAP.md) |
| 最新版本发布页 | [v0.3.6-phase3.6](https://github.com/ernesto01louis/ai-orchestrator/releases/tag/v0.3.6-phase3.6) |
---
## 系统架构
### 相关页面
相关主题：[五层记忆系统](#page-5-layer-memory), [数据流与清单验证](#page-data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/README.md)
- [ui/console/README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/README.md)
- [api/routes/memory.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/memory.py)
- [api/routes/content.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/content.py)
- [api/routes/activity.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/activity.py)
- [api/routes/admin.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/admin.py)
- [ui/console/src/lib/types.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts)
- [cli/main.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/cli/main.py)
# 系统架构
## 概述
ai-orchestrator 是一个基于 FastAPI 构建的 AI 编排平台，旨在实现模型无关的 AI 工作流自动化与可观测性。该系统遵循"平台而非枢纽"（platform-not-hub）的设计原则，支持多模型路由、沙箱执行、HITL（Human-in-the-Loop）干预、证据级别溯源等核心能力。
资料来源：[README.md:1-20]()
## 整体架构图
```mermaid
graph TB
subgraph 前端层["前端层 (React + Vite)"]
UI[UI Console]
WS[WebSocket 客户端]
API[REST API 客户端]
end
subgraph 后端层["后端层 (FastAPI)"]
APP[app.py
FastAPI Application]
subgraph 路由层["API 路由"]
ROUTES[routes/*]
end
subgraph 核心层["Core 模块"]
HITL[core/hitl.py
HITL 控制]
AGENTS[core/agents/*
Agent 逻辑]
EXEC[core/exec.py
执行引擎]
end
end
subgraph 记忆层["Memory & Storage"]
MEM[memory_pkg]
VAULT[Vault Writer]
HINDSIGHT[Hindsight]
end
subgraph 外部集成["外部集成"]
OLLAMA[Ollama
多模型路由]
SSH[SSH Targets
沙箱执行]
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/` 目录下：
| 路由模块 | 文件路径 | 功能说明 |
|---------|---------|---------|
| memory | `api/routes/memory.py` | 参考文档管理、Hindsight 记忆同步、自动反思 |
| content | `api/routes/content.py` | 参考文档上传/下载、图数据聚合 |
| activity | `api/routes/activity.py` | 活动时间线聚合（运行、战役、Git 提交） |
| admin | `api/routes/admin.py` | Agent 配置管理、工具注册表管理 |
| runs | `api/routes/runs.py` | 运行生命周期管理 |
| campaigns | `api/routes/campaigns.py` | 战役抽象管理 |
资料来源：[api/routes/memory.py:1-30]()
### Agent 执行阶段
系统定义了完整的 AI Agent 执行管道，包含以下阶段：
```mermaid
stateDiagram-v2
[*] --> Planner: 任务输入
Planner --> PostPlanner: 生成计划
PostPlanner --> HITL_Check: HITL Gate
HITL_Check --> Generator: 批准通过
HITL_Check --> [*]: 中止
Generator --> Judge: 生成内容
Judge --> Optimizer: 评估通过
Judge --> Generator: 需重试
Optimizer --> [*]: 完成
```
#### 阶段类型定义
| 阶段 | 枚举值 | 说明 |
|-----|-------|------|
| planner | `planner` | 任务分解与工具选择 |
| post_planner | `post_planner` | Planner 输出后置检查点 |
| generator | `generator` | 内容生成阶段 |
| judge | `judge` | 评估与质量判断 |
| optimizer | `optimizer` | 参数调优与优化 |
| complete | `complete` | 运行完成 |
| failed | `failed` | 运行失败 |
资料来源：[ui/console/src/lib/types.ts:1-15]()
## HITL（Human-in-the-Loop）系统
### 干预模式
Phase 3.1 实现了五种 HITL 干预模式，用于在不同粒度上控制 AI 执行流程：
| 模式 | 枚举值 | 说明 |
|-----|-------|------|
| 全自动 | `full_auto` | 无人工干预，完全自动执行 |
| 仅门控 | `gate_only` | 仅在关键门控点暂停 |
| 检查点 | `checkpoint` | 每个阶段结束后暂停等待批准 |
| 逐步执行 | `step_by_step` | 每个子步骤后暂停 |
| 协作模式 | `co_pilot` | AI 与人工并行协作 |
资料来源：[ui/console/src/lib/types.ts:16-25]()
### SmartPause 机制
Phase 3.2 引入了 SmartPause 智能暂停功能，当 Planner 置信度低于阈值时自动触发暂停：
```python
# 置信度阈值方案
阈值 >= 0.7: ok (绿色) - 正常执行
阈值 0.4-0.7: warn (黄色) - 警告状态
阈值 < 0.4: err (红色) - 高风险暂停
```
SmartPause 与传统 HITL 检查点的区别：
| 特性 | SmartPause | 传统 HITL 检查点 |
|-----|-----------|-----------------|
| 触发条件 | 置信度 < 0.50 | hitl_mode = checkpoint |
| UI 标识 | `smartpause` | `hitl:` |
| 停止阶段 | post_planner | 任意阶段 |
资料来源：[ui/console/src/pages/Hitl.tsx:1-50]()
### 干预操作 API
HITL 控制台支持三种干预操作：
```bash
POST /runs/{runId}/intervene
{
"action": "approve" | "reject" | "edit",
"payload": "" # 仅 edit 模式需要
}
```
干预后的行为：
- **approve**: 继续执行，Generator 正常运行
- **reject**: 中止运行，不再消耗 Token
- **edit**: 修改 Planner 输出后继续执行
资料来源：[ui/console/src/pages/Hitl.tsx:51-80]()
## 记忆与数据层
### 记忆源架构
系统采用多源记忆聚合架构：
```mermaid
graph LR
subgraph 记忆源
RI[run_index.json
运行索引]
CAMP[campaigns.json
战役数据]
NEG[negative_memory.json
负面模式]
PROMPT[prompt_index.json
提示词索引]
end
subgraph 外部存储
HINDSIGHT[Hindsight
知识图谱]
VAULT[NoteDiscovery Vault
笔记聚合]
NAS[NAS Mirror
NAS 镜像]
end
RI --> AGG[Activity API]
CAMP --> AGG
NEG --> AGG
PROMPT --> AGG
AGG --> GraphData[/graph-data
图数据端点]
HINDSIGHT --> memory_routes
VAULT --> memory_routes
```
### 活动时间线聚合
`/api/activity` 端点聚合三类事件源：
| 事件类型 | 数据来源 | 时间范围 |
|---------|---------|---------|
| `run` | `memory/run_index.json` | 最近 N 小时 |
| `campaign` | `memory/campaigns.json` | 最近 N 小时 |
| `git` | `git log` 本地仓库 | 最近 N 小时 |
资料来源：[api/routes/activity.py:1-80]()
### 参考文档管理
参考文档支持 PDF → Markdown 自动转换，并可选择性地摄入 Hindsight 知识图谱：
```python
# 上传流程
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 技术栈
| 技术 | 用途 |
|-----|------|
| React 18 | UI 框架 |
| Vite | 构建工具 |
| Tailwind CSS | 样式系统 (oklch 色彩) |
| React Query | 数据获取与缓存 |
| TypeScript | 类型安全 |
资料来源：[ui/console/README.md:1-20]()
### 页面路由
| 页面 | 路由 | 状态 |
|-----|------|-----|
| Dashboard | `/dashboard` | ✅ 已实现 |
| Runs List | `/runs` | ✅ 已实现 |
| Run Detail | `/runs/:runId` | ✅ 已实现 |
| HITL Console | `/hitl` | ✅ 已实现 |
| Campaigns | `/campaigns` | 🔧 占位 |
| Live Logs | `/logs` | 🔧 占位 |
| Memory & Gates | `/memory` | 🔧 占位 |
| Config | `/config` | 🔧 占位 |
资料来源：[ui/console/README.md:21-30]()
### 主题系统
系统支持双主题切换：
| 主题 | 配置文件 | 说明 |
|-----|---------|------|
| `default` | `src/theme/default.ts` | 操作员控制台风格 |
| `personal` | `src/theme/personal.ts` | 动漫风格覆盖层 |
运行时切换方式：
```javascript
window.__setTheme("personal") // 切换主题
window.__setTheme("default") // 恢复默认
```
资料来源：[ui/console/README.md:31-45]()
## 数据流与执行管道
### 运行数据模型
```typescript
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 合约
| 表面 | 接口文件 | 说明 |
|-----|---------|------|
| REST | `src/lib/api.ts` | `/api` → `VITE_API_BASE` |
| WebSocket | `src/lib/ws.ts` | `VITE_WS_URL` |
| React Query Keys | `src/lib/queries.ts` | `qk.health()`, `qk.runs()` |
| Types | `src/lib/types.ts` | 前后端类型对齐 |
资料来源：[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：
```typescript
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` 提供运维功能：
| 命令 | 功能 |
|-----|------|
| `verify-run ` | 验证运行 Merkle 根 |
| `verify-campaign ` | 验证战役 Merkle 根 |
| `rotate-logs` | 日志轮转（gzip >1d，删除 >90d） |
| `build-bundle` | 构建证据包 |
资料来源：[cli/main.py:1-80]()
## 版本演进
| 版本 | 阶段 | 核心功能 |
|-----|------|---------|
| v0.3.6 | Phase 3.6 | Campaign 抽象完善、证据链升级 |
| v0.3.3 | Phase 3.3 | NoteDiscovery-grounded planner |
| v0.3.2 | Phase 3.2 | SmartPause 机制 |
| v0.3.1 | Phase 3.1 | HITL 干预模式 |
| v0.2.x | Phase 2.x | 核心编排、Ollama 路由、工具注册 |
| v0.1.x | Phase 1.x | 基础框架搭建 |
资料来源：社区发布记录
---
## 五层记忆系统
### 相关页面
相关主题：[系统架构](#page-system-architecture), [引用级证据包](#page-evidence-bundles)
相关源码文件
以下源码文件用于生成本页说明：
- [memory_pkg/__init__.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/memory_pkg/__init__.py)
- [memory/identity.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/memory/identity.md)
- [memory/goals.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/memory/goals.md)
- [core/note_discovery.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/core/note_discovery.py)
- [api/routes/memory.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/memory.py)
- [api/routes/activity.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/activity.py)
- [api/routes/content.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/content.py)
# 五层记忆系统
## 概述
五层记忆系统是 ai-orchestrator 的核心知识管理基础设施，为 AI Agent 提供持久化、可检索、上下文感知的记忆能力。该系统通过分层架构存储和管理项目身份、目标、参考资料、运行历史和反思洞察，使 Agent 在多轮任务执行中保持连贯性和上下文连续性。
记忆系统与 **Phase 1.2 — citation-grade evidence bundles** 和 **Phase 3.3 — NoteDiscovery-grounded planner** 功能紧密集成，通过 REST 接口为规划器提供基于笔记的推理能力。
## 系统架构
```mermaid
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`
目标层维护项目的短期和长期目标，为规划器提供任务方向指引。
**功能特性**：
| 特性 | 说明 |
|------|------|
| 目标状态 | pending / in_progress / completed / blocked |
| 优先级 | P0 / P1 / P2 / P3 |
| 依赖关系 | 目标间的依赖图谱 |
| 截止日期 | 时间约束追踪 |
| 进度指标 | 完成百分比和里程碑 |
### 第三层：参考资料 (References Layer)
**文件位置**: `api/routes/content.py:195-230`, `api/routes/memory.py:30-75`
参考资料层管理用户上传的文档，支持 PDF、Markdown 和纯文本格式，并自动转换为可检索的 Markdown 格式。
#### API 端点
| 端点 | 方法 | 功能 |
|------|------|------|
| `/references` | POST | 上传参考文档 |
| `/references` | GET | 列出所有参考资料 |
| `/references/{filename}/content` | GET | 获取文档内容 |
| `/references/{filename}` | DELETE | 删除参考资料 |
#### 文件处理流程
```mermaid
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`)：
```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 索引中：
```python
hindsight_result = hindsight_retain(
f"Reference document '{filename}' uploaded.\n\n{md_text[:3000]}",
"api-upload"
)
```
#### NoteDiscovery 检索
**文件位置**: `core/note_discovery.py`
NoteDiscovery 是基于 Hindsight 记忆的规划增强组件，为 Planner 提供上下文感知的知识检索。
```mermaid
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`
记忆系统通过活动时间线端点暴露聚合的事件流：
```python
@router.get("/activity")
def get_activity(limit: int = 200, hours: int = 168) -> dict[str, Any]:
```
**时间线事件来源**：
| 来源 | 类型 | 说明 |
|------|------|------|
| `memory/run_index.json` | run | 运行完成事件 |
| `memory/campaigns.json` | campaign | 活动生命周期事件 |
| `git log` | git | 代码提交事件 |
**查询参数**：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `limit` | 200 | 最大返回事件数 |
| `hours` | 168 | 回溯窗口（7天） |
## 配置与状态
### 内存路径配置
| 常量 | 路径 | 用途 |
|------|------|------|
| `MEMORY_DIR` | `core/paths.py` | 记忆存储根目录 |
| `REFERENCE_DIR` | `api/routes/memory.py` | 参考资料存储 |
| `REPO_ROOT` | `core/paths.py` | Git 仓库根目录 |
### Hindsight 状态
```python
HINDSIGHT_ENABLED = os.getenv("HINDSIGHT_ENABLED", "false").lower() == "true"
```
当 Hindsight 未启用时，相关 API 返回 503 状态码：
```python
if not HINDSIGHT_ENABLED:
raise HTTPException(status_code=503, detail="Hindsight is not enabled")
```
## API 集成示例
### 上传参考资料
```bash
curl -X POST "http://localhost:8000/references" \
-H "Content-Type: multipart/form-data" \
-F "file=@research_paper.pdf"
```
**响应**：
```json
{
"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
}
```
### 获取活动时间线
```bash
curl "http://localhost:8000/activity?limit=50&hours=24"
```
## 相关发布版本
| 版本 | 关联功能 |
|------|----------|
| v0.3.3-phase3.3 | Phase 3.3 — NoteDiscovery-grounded planner |
| v0.2.1-phase2.1+ | Phase 1.2 — citation-grade evidence bundles |
## 待办功能
根据 UI Console 的占位符设计，以下记忆相关功能正在规划中：
- **Memory & Gates** 页面 (`/memory`)
- 记忆可视化界面
- 手动记忆编辑
- 记忆导入/导出
## 安全考量
- 参考资料文件名通过 `SAFE_FILENAME` 正则验证，防止路径遍历攻击
- 上传文件大小限制为 10MB
- Markdown 内容通过 `errors="replace"` 处理编码问题
- 所有记忆路径使用绝对路径配置，避免相对路径注入风险
---
## 数据流与清单验证
### 相关页面
相关主题：[引用级证据包](#page-evidence-bundles)
相关源码文件
以下源码文件用于生成本页说明：
- [manifest/__init__.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/manifest/__init__.py)
- [manifest/merkle.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/manifest/merkle.py)
- [manifest/run_manifest.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/manifest/run_manifest.py)
- [cli/main.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/cli/main.py)
- [api/routes/campaigns.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/campaigns.py)
# 数据流与清单验证
## 概述
**数据流与清单验证**是ai-orchestrator的核心机制，用于确保AI运行流程的可追溯性、完整性和可验证性。该系统通过清单（Manifest）结构记录每次运行的完整状态转换，并通过Merkle树提供加密级的数据完整性证明。
主要职责包括：
- 记录每个Agent的执行阶段和输出结果
- 提供清单内容的加密哈希验证
- 支持Campaign级别的批量运行管理
- 实现证据等级（citation-grade）的结果溯源
---
## 清单数据结构
### RunManifest 核心模型
```mermaid
classDiagram
class RunManifest {
+str run_id
+str project
+str campaign_id
+str phase
+List~PhaseRecord~ phases
+MerkleProof proof
+datetime started_at
+datetime? completed_at
+float? confidence
}
class PhaseRecord {
+str name
+dict output
+str model
+datetime timestamp
+str? error
}
class MerkleProof {
+str root_hash
+List~str~ proof_path
+List~str~ leaf_hashes
}
RunManifest "1" --> "*" PhaseRecord
RunManifest "1" --> "1" MerkleProof
```
清单结构包含以下关键字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `run_id` | string | 唯一运行标识符 |
| `project` | string | 所属项目名称 |
| `campaign_id` | string | 关联的Campaign ID |
| `phase` | string | 当前执行阶段 |
| `phases` | PhaseRecord[] | 各阶段的执行记录 |
| `confidence` | float | Planner置信度（Phase 3.2 SmartPause相关） |
| `paused` | string | 暂停状态（smartpause/hitl:xxx） |
---
## 阶段流转与数据流
### Agent Pipeline 阶段
```mermaid
graph LR
A[User Request] --> B[Planner]
B --> C{Phase Check}
C -->|post_planner| D[HITL Gate]
C -->|generator| E[Generator]
D -->|approved| E
E --> F[Judge]
F --> G{Score >= threshold?}
G -->|yes| H[Optimizer]
G -->|no| I[Loop back to Planner]
H --> J[Complete]
I --> B
```
每个阶段都会在清单中追加一条`PhaseRecord`，记录该阶段的输入、输出、使用的模型以及执行时间戳。
### Campaign 数据流
Campaign作为批量运行的抽象层，管理多个相关Run的执行：
```mermaid
graph TD
A[Campaign Create] --> B[Queue Runs]
B --> C[Run 1]
B --> D[Run 2]
B --> E[Run N]
C --> F[Complete/Update Manifest]
D --> F
E --> F
F --> G[Campaign Summary]
```
---
## Merkle 树验证机制
### 哈希计算逻辑
Merkle树对清单内容进行分层哈希，确保任何修改都能被检测到：
```python
# 伪代码展示验证逻辑
leaf_hash = hash(phase_name + model + timestamp + output_json)
merkle_root = build_merkle_tree(all_leaf_hashes)
```
阈值方案（与`core/hitl.py`同步）：
| 置信度范围 | 状态指示 |
|-----------|----------|
| >= 0.70 | ok（绿色） |
| 0.40 - 0.70 | warn（黄色） |
| < 0.40 | err（红色） |
### 验证端点
清单验证通过API暴露：
```
GET /api/runs/{run_id}/manifest
GET /api/runs/{run_id}/verify
```
返回包含`MerkleProof`的完整清单，客户端可自行验证哈希一致性。
---
## 证据等级（Citation-Grade）清单
Phase 1.2引入的证据捆绑机制要求清单包含：
1. **来源追踪**：每个生成结果必须关联到原始参考文档
2. **引用标记**：在markdown输出中嵌入可验证的引用锚点
3. **模糊匹配**：Quote对齐度需>= 0.85方可计入证据链
```mermaid
graph LR
A[Reference Upload] --> B[PDF → Markdown]
B --> C[Hindsight Ingest]
C --> D[Evidence Bundle]
D --> E[Generator Output]
E --> F[Citation Verification]
F --> G[Verified Manifest]
```
证据清单还通过`hindsight/reflect/auto`端点触发自动反思，同步模型表现、失败模式和任务类型趋势。
---
## Campaign 清单管理
### Campaign 生命周期
| 阶段 | 操作 | API端点 |
|------|------|---------|
| 创建 | 初始化Campaign | `POST /api/campaigns` |
| 排队 | 添加Run到队列 | `POST /api/campaigns/{id}/runs` |
| 监控 | 获取状态 | `GET /api/campaigns/{id}` |
| 干预 | HITL操作 | `POST /runs/{run_id}/intervene` |
### Campaign 清单结构
```json
{
"campaign_id": "cmp_xxx",
"project": "citation-grade-eval",
"runs": ["run_01HZK...", "run_01HZK..."],
"status": "running",
"created_at": "2025-01-01T00:00:00Z"
}
```
---
## HITL 干预与清单状态
### 干预模式
Phase 3.1实现的五种干预模式：
| 模式 | 说明 | 清单暂停状态 |
|------|------|-------------|
| `full_auto` | 完全自动执行 | null |
| `gate_only` | 仅在Gate处暂停 | `hitl:gate` |
| `checkpoint` | 每个阶段后暂停 | `hitl:checkpoint` |
| `step_by_step` | 逐Agent执行 | `hitl:step` |
| `co_pilot` | AI辅助，人类最终决策 | `hitl:copilot` |
### SmartPause 机制（Phase 3.2）
当Planner置信度低于阈值时触发SmartPause，清单记录`paused: "smartpause"`：
```typescript
// 来自 ui/console/src/components/ConfidenceBar.tsx:3
// Threshold: >=0.7 ok | 0.4-0.7 warn | <0.4 err
```
---
## CLI 与清单交互
命令行工具支持清单操作：
```bash
# 查看运行清单
ai-orch run manifest
# 验证清单完整性
ai-orch run verify
# 查看Campaign清单
ai-orch campaign list --project
```
---
## 类型定义参考
```typescript
// 来自 ui/console/src/lib/types.ts:1
export type Phase =
| "planner"
| "post_planner"
| "generator"
| "judge"
| "optimizer"
| "complete"
| "failed";
export type HitlMode =
| "full_auto"
| "gate_only"
| "checkpoint"
| "step_by_step"
| "co_pilot"
| "smartpause";
export type PausedState = null | "smartpause" | `hitl:${string}`;
```
---
## 相关页面
- [Campaign抽象层](./campaigns.md)
- [HITL干预模式](./hitl-modes.md)
- [SmartPause机制](./smartpause.md)
- [证据捆绑系统](./evidence-bundles.md)
---
## Campaign 系统
### 相关页面
相关主题：[引用级证据包](#page-evidence-bundles), [HITL 干预与 SmartPause](#page-hitl-smartpause)
相关源码文件
以下源码文件用于生成本页说明：
- [ui/console/src/lib/types.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts)
- [ui/console/src/lib/mocks.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/mocks.ts)
- [api/routes/campaigns.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/campaigns.py)（API 路由定义）
- [api/routes/activity.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/activity.py)（活动时间线集成）
- [README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/README.md)（系统概览）
# Campaign 系统
## 概述
Campaign（活动/实验）系统是 ai-orchestrator 的核心抽象层，用于组织、管理和追踪一组相关的自动化运行（Run）。从 v0.2.1-phase2.1 版本开始引入，并在 v0.3.6-phase3.6 中持续迭代完善。
**核心职责：**
- 将多个相关 Run 组织为逻辑单元（实验/基准测试）
- 支持参数网格搜索（Grid Search）实验设计
- 提供 HITL（Human-in-the-Loop）干预模式控制
- 追踪预算消耗与执行状态
- 生成可验证的 Merkle 根用于数据完整性保障
## 核心数据结构
### Campaign 接口定义
```typescript
// 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;
}
```
### Budget 追踪结构
```typescript
interface Budget {
used: number; // 已消耗预算（美元）
total: number; // 总预算上限
percentage: number; // 消耗百分比
state: "healthy" | "warn" | "err"; // 健康状态
}
```
### HITL 模式枚举
Campaign 支持五种 HITL 干预模式，用于控制自动化代理的人机协作程度：
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `full_auto` | 完全自动执行，无需人工介入 | 大批量基准测试 |
| `gate_only` | 仅在关键节点暂停等待确认 | 高风险操作审查 |
| `checkpoint` | 到达检查点时暂停 | 分阶段验证 |
| `step_by_step` | 每个步骤后等待确认 | 精细化控制 |
| `co_pilot` | AI 建议 + 人工决策 | 协作式开发 |
| `smartpause` | 置信度低于阈值时自动暂停 | 质量保障 |
> 资料来源：[ui/console/src/lib/types.ts:24-34]()
## Campaign 生命周期
### 状态流转图
```mermaid
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
```
### 状态说明
| 状态 | 含义 | 触发条件 |
|------|------|----------|
| `running` | 执行中 | Campaign 创建且至少有一个活跃 Run |
| `complete` | 全部完成 | 所有子 Run 都已结束（成功或失败） |
| `aborted` | 中止 | 创建失败或被用户强制终止 |
| `paused` | 暂停 | 用户主动暂停或 HITL 干预触发 |
> 资料来源：[ui/console/src/lib/mocks.ts:80-100]()
## 参数网格与实验设计
Campaign 的 `grid` 字段支持声明式参数扫描，允许多维度超参数实验：
```typescript
// 示例网格配置
{
"temperature": [0.3, 0.6, 0.9],
"judge_model": ["llama3.1:70b", "qwen2.5:72b"]
}
```
上述配置会生成 `3 × 2 = 6` 个组合的 Run，Campaign 自动管理这些变体的执行与结果汇总。
**已知的网格维度示例：**
| 维度 | 变体值示例 | 说明 |
|------|------------|------|
| `router` | `["bm25", "hybrid", "dense"]` | RAG 路由算法 |
| `k` | `[4, 8]` | Top-K 检索数量 |
| `temperature` | `[0.3, 0.6, 0.9]` | LLM 采样温度 |
| `judge_model` | `["llama3.1:70b", "qwen2.5:72b"]` | 评判模型选择 |
> 资料来源：[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 中止事件
```python
# 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]()
## 后端存储结构
| 存储位置 | 用途 |
|----------|------|
| `memory/campaigns.json` | Campaign 元数据持久化 |
| `memory/run_index.json` | Run 索引与状态追踪 |
| `campaigns/` 目录 | Campaign 模板与配置 |
Campaign 数据使用 JSON-first 双重写入策略，同时写入 Postgres 持久化存储以确保数据安全。
## 前端 UI 集成
### 已实现页面
| 页面 | 路由 | 功能 |
|------|------|------|
| Campaign 列表 | `/campaigns` | 展示所有 Campaign 及其状态 |
| Campaign 详情 | `/campaigns/:id` | 单一 Campaign 的完整视图 |
> 资料来源：[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` 字段决定了整个实验的自动化程度：
```mermaid
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 格式声明：
```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 根验证机制：
```bash
orchestrator verify-campaign CAMPAIGN_ID
```
该命令递归验证 Campaign 下所有 Run 的 SHA256 清单，确保实验数据未被篡改。
> 资料来源：[cli/main.py:50-80]()
## 常见工作流
### 1. 创建并执行基准测试
```mermaid
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 干预流程
```mermaid
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: 恢复执行
```
## 版本演进
| 版本 | 变更内容 |
|------|----------|
| v0.2.1-phase2.1 | Phase 1.1 — Campaign 抽象首次引入 |
| v0.3.1-phase3.1 | Phase 3.1 — HITL 干预模式支持 |
| v0.3.2-phase3.2 | Phase 3.2 — SmartPause 智能暂停 |
| v0.3.6-phase3.6 | 持续迭代完善 |
> 资料来源：[README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/README.md) 和 Release Notes
## 待办功能
以下功能在 UI 中标记为 Stub 状态，预计后续迭代实现：
- 完整的 Campaign 管理页面
- 实时日志查看器
- Memory 可视化
- 高级配置面板
---
## 引用级证据包
### 相关页面
相关主题：[Campaign 系统](#page-campaign-system), [数据流与清单验证](#page-data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [evidence/__init__.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/evidence/__init__.py)
- [evidence/builder.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/evidence/builder.py)
- [evidence/rocrate.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/evidence/rocrate.py)
- [evidence/signing.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/evidence/signing.py)
- [evidence/verify.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/evidence/verify.py)
- [evidence/checklists.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/evidence/checklists.py)
# 引用级证据包
引用级证据包（Citations-Grade Evidence Bundle）是 ai-orchestrator 项目 Phase 1.2 阶段的核心功能，旨在为每次运行（Run）生成可验证、可追溯的完整证据链。该功能确保 AI 生成内容的引用来源具备学术级别的可信度与可审计性。
## 功能概述
引用级证据包的核心目标是将 AI 编排系统中的每一个关键决策、每一次模型调用、每一份引用来源封装为独立、可签名、可验证的证据单元。通过这种方式，用户可以在事后对任意一次运行的完整过程进行回溯验证。
该功能与以下模块深度集成：
| 集成模块 | 交互方式 |
|---------|---------|
| 评判器（Judge） | 记录引用评分与裁决结果 |
| 记忆系统（Memory） | 关联历史知识图谱与负向记忆 |
| 证据库（References） | 追踪上传文档的来源与转换元数据 |
| Vault 写入器 | 发布证据包到 NoteDiscovery 和 NAS |
## 架构设计
### 证据包结构
每个证据包包含以下核心组成部分：
```mermaid
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[时间戳验证]
```
### 模块职责
| 模块 | 文件 | 核心职责 |
|------|------|---------|
| builder | `evidence/builder.py` | 构建证据包，聚合运行时数据 |
| rocrate | `evidence/rocrate.py` | 生成 RO-Crate 格式的可交换证据容器 |
| signing | `evidence/signing.py` | 对证据包进行加密签名 |
| verify | `evidence/verify.py` | 验证证据包的完整性与签名 |
| checklists | `evidence/checklists.py` | 维护证据检查清单，确保完整性 |
| \_init\_ | `evidence/__init__.py` | 模块导出与公共接口定义 |
## 证据生成流程
### 构建阶段（Build Phase）
证据包的生成在每次运行的生命周期中按需触发：
```mermaid
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 模块联动：
```python
# 评分阈值（来自 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](https://www.researchobject.org/ro-crate/) 格式，这是一种用于打包研究数据的标准化容器格式。RO-Crate 确保证据包可以在不同系统之间互操作。
### RO-Crate 结构
| 文件/目录 | 说明 |
|----------|------|
| `ro-crate-metadata.json` | 根元数据文件，描述包内实体关系 |
| `manifest.json` | SHA256 校验和清单 |
| `trace/` | 执行轨迹数据 |
| `citations/` | 引用来源文档（含 Markdown 转换版本） |
| `scores/` | Judge 评分数据 |
| `signatures/` | 签名文件 |
## 签名与验证机制
### 签名流程
证据包在存储前必须经过签名，确保内容未被篡改：
```mermaid
graph TD
A[构建证据包] --> B[计算内容哈希]
B --> C[生成 HMAC 签名]
C --> D[附加时间戳]
D --> E[存储证据包]
E --> F[Vault 持久化]
```
### 验证流程
任何时候都可以对已存储的证据包进行验证：
1. 重新计算内容哈希
2. 对比签名中的哈希值
3. 验证时间戳的合理性
4. 检查检查清单完整性
验证失败时，系统将拒绝使用该证据包进行后续裁决。
## 检查清单（Checklists）
证据包附带完整性检查清单，确保每个必需组件都已包含：
| 检查项 | 说明 |
|-------|------|
| `has_metadata` | 包含完整元数据 |
| `has_trace` | 包含执行轨迹 |
| `has_citations` | 包含引用来源 |
| `has_scores` | 包含评分数据 |
| `has_signature` | 已签名 |
| `signature_valid` | 签名有效 |
| `timestamp_valid` | 时间戳合理 |
## API 端点
证据包通过以下后端 API 暴露：
| 端点 | 方法 | 功能 |
|------|------|------|
| `/evidence/{run_id}` | GET | 获取指定运行的证据包 |
| `/evidence/{run_id}/verify` | POST | 验证证据包完整性 |
| `/evidence/bundle` | POST | 手动触发构建证据包 |
| `/evidence/export` | GET | 导出为 RO-Crate 格式 |
## 与 Campaign 的关联
证据包与 Campaign（战役）抽象深度集成。在 Campaign 级别，系统可以：
- 聚合多个 Run 的证据包
- 生成 Campaign 级别的汇总报告
- 跨 Run 追踪引用来源趋势
- 验证 Campaign 的 Merkle 根
```bash
# 使用 CLI 验证 Campaign 的 Merkle 根
python -m cli.main verify-campaign
```
## 存储与持久化
证据包存储采用多层策略：
| 存储层 | 位置 | 用途 |
|-------|------|------|
| 本地磁盘 | `memory/evidence/` | 快速访问缓存 |
| NAS 镜像 | Vault 配置路径 | 冗余备份 |
| NoteDiscovery | REST API | 知识图谱集成 |
## 使用场景
### 学术写作辅助
在学术场景中，引用级证据包可以证明 AI 生成内容的每个论断都有可追溯的来源，便于论文审核。
### 合规审计
对于需要 AI 决策可解释性的行业（如金融、医疗），证据包提供了完整的审计轨迹。
### 模型评估
通过对比不同模型的证据包评分，可以系统性地评估模型在引用质量方面的表现差异。
## 版本历史
| 版本 | 里程碑 |
|------|--------|
| v0.2.1-phase2.1 | 初始引入证据包概念 |
| v0.3.6-phase3.6 | Phase 1.2 完成，引用级证据包正式发布 |
## 注意事项
- 证据包生成会增加运行延迟，建议在批量评估时异步处理
- RO-Crate 导出不支持大于 100MB 的引用文档
- 签名密钥轮换需配合 `rotate-secrets` CLI 命令
- SmartPause 暂停的 Run 不会生成中间证据包，只在恢复或终止时生成
---
*本页最后更新于版本 v0.3.6-phase3.6*
---
## HITL 干预与 SmartPause
### 相关页面
相关主题：[Campaign 系统](#page-campaign-system)
相关源码文件
以下源码文件用于生成本页说明：
- [ui/console/src/pages/Hitl.tsx](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/pages/Hitl.tsx)
- [ui/console/src/lib/types.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts)
- [ui/console/src/components/ConfidenceBar.tsx](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/components/ConfidenceBar.tsx)
- [ui/console/src/lib/mocks.ts](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/mocks.ts)
- [api/routes/runs.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/runs.py)
- [api/routes/activity.py](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/activity.py)
# HITL 干预与 SmartPause
## 概述
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](https://github.com/ernesto01louis/ai-orchestrator/releases/tag/v0.3.1-phase3.1)，[v0.3.2-phase3.2](https://github.com/ernesto01louis/ai-orchestrator/releases/tag/v0.3.2-phase3.2)
## 架构设计
### 系统组件
```mermaid
graph TD
subgraph 后端层
HITL[core/hitl.py
HITL 控制模块]
RUNS[api/routes/runs.py
运行路由]
RUN_INDEX[memory/run_index.json
运行索引]
end
subgraph 前端层
HITL_PAGE[ui/console/src/pages/Hitl.tsx
HITL 控制台页面]
CONFIDENCE[ui/console/src/components/ConfidenceBar.tsx
置信度条形图]
TYPES[ui/console/src/lib/types.ts
类型定义]
end
subgraph 干预操作
APPROVE[approve
批准]
EDIT[edit
编辑]
SKIP[skip
跳过]
ABORT[abort
中止]
end
RUNS -->|paused 状态| HITL
HITL -->|confidence 阈值| SmartPause
HITL_PAGE -->|干预请求| RUNS
CONFIDENCE -->|confidence 可视化| HITL_PAGE
TYPES -->|类型约束| HITL_PAGE
```
### 暂停状态流转
```mermaid
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 干预模式
### 五种介入级别
| 模式 | 描述 | 使用场景 |
|------|------|----------|
| `full_auto` | 完全自动化，无人工介入 | 高置信度、可信赖的标准化任务 |
| `gate_only` | 仅在关键门控点介入 | 关键决策点的人工确认 |
| `checkpoint` | 固定阶段检查点介入 | 需要阶段性验收的工作流 |
| `step_by_step` | 每一步都需要批准 | 高风险或高精度要求的任务 |
| `co_pilot` | 协同模式，AI 和人工并行 | 辅助人类专家工作 |
资料来源：[ui/console/src/lib/types.ts:41-47](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts#L41-L47)
### 干预操作类型
| 操作 | 含义 | 适用条件 |
|------|------|----------|
| `approve` | 批准当前规划，继续执行 | 规划质量可接受 |
| `edit` | 编辑后批准，需附带 JSON payload | 需要修改规划内容 |
| `skip` | 跳过当前运行 | 临时跳过，不终止 Campaign |
| `abort` | 终止当前运行 | 任务不再需要执行 |
资料来源：[ui/console/src/lib/types.ts:63-67](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts#L63-L67)
## SmartPause 机制
### 触发条件
SmartPause 在 planner 阶段输出后触发，当 **置信度（confidence）低于 0.50 阈值**时，系统自动暂停并等待人工审查。
```python
# SmartPause 触发逻辑
if planner_confidence < 0.50:
trigger_smartpause()
```
资料来源：[ui/console/src/pages/Hitl.tsx:14-15](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/pages/Hitl.tsx#L14-L15)
### 置信度可视化
ConfidenceBar 组件采用三级颜色编码方案：
| 置信度范围 | 色调 | 含义 |
|------------|------|------|
| ≥ 0.70 | `ok` (绿色) | 规划质量良好，可自动执行 |
| 0.40 - 0.70 | `warn` (黄色) | 中等质量，建议审查 |
| < 0.40 | `err` (红色) | 质量较低，必须人工审查 |
资料来源：[ui/console/src/components/ConfidenceBar.tsx:6-8](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/components/ConfidenceBar.tsx#L6-L8)
```tsx
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 对比
| 特性 | SmartPause | HITL Checkpoint |
|------|------------|-----------------|
| 触发来源 | 置信度阈值自动触发 | 固定阶段强制检查点 |
| 暂停原因存储 | `paused: "smartpause"` | `paused: "hitl:${phase}"` |
| UI 显示 | `smartpause` badge | `hitl:${hitl_mode}` badge |
| 阶段关联 | planner 输出后 | post_planner 等固定阶段 |
资料来源：[ui/console/src/lib/types.ts:49-58](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts#L49-L58)
## 运行阶段定义
| 阶段 | 描述 | 可触发暂停 |
|------|------|-----------|
| `planner` | 任务规划分解 | SmartPause (后) |
| `post_planner` | 规划后检查点 | HITL Checkpoint |
| `generator` | 内容生成 | 可配置 |
| `judge` | 结果评判 | 可配置 |
| `optimizer` | 优化调整 | 可配置 |
| `complete` | 运行完成 | - |
| `failed` | 运行失败 | - |
资料来源：[ui/console/src/lib/types.ts:31-38](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/lib/types.ts#L31-L38)
## 后端 API 接口
### 干预端点
```
POST /runs/{run_id}/intervene
```
**请求体格式：**
```json
{
"action": "approve" | "edit" | "skip" | "abort",
"payload": "" // 仅 action === "edit" 时需要
}
```
**响应示例：**
```json
{
"run_id": "run_01HZK4ABNR6P7VCT2K",
"action": "approve",
"queued": true
}
```
资料来源：[api/routes/runs.py:198-214](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/runs.py#L198-L214)
### 干预后的状态更新
当干预操作成功后，后端会执行以下操作：
1. **清除 paused 标志** - 移除 `paused` 字段（设置为 `None`）
2. **通知 SmartPause 轮询循环** - 确保暂停状态的 run 也能解除阻塞
3. **队列通知** - 干预请求入队等待处理
```python
# 清除暂停标志以解锁 SmartPause 轮询循环
_update_run_status(run_id, paused=None)
```
资料来源：[api/routes/runs.py:209-212](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/runs.py#L209-L212)
### 日志尾部接口
```
GET /logs/{run_id}/tail?lines=80
```
返回指定 run 的最后 N 行日志内容。
资料来源：[api/routes/runs.py:217-232](https://github.com/ernesto01louis/ai-orchestrator/blob/main/api/routes/runs.py#L217-L232)
## 前端 HITL 控制台
### 页面路由
HITL 控制台页面位于 `/hitl` 路由，是操作员进行人工干预的主要界面。
资料来源：[ui/console/README.md](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/README.md)
### 界面布局
```mermaid
graph LR
subgraph HITL 控制台
Header[Run 元信息栏
ID · Badge · Phase · ConfidenceBar]
Meta[元数据网格
project · campaign · model · waiting]
Planner[Planner 输出区
JSON/Edit 编辑器]
Alert[告警信息区
SmartPause / Checkpoint 说明]
Action[操作按钮区
approve · edit · skip · abort]
end
```
### 条件渲染逻辑
```tsx
// 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](https://github.com/ernesto01louis/ai-orchestrator/blob/main/ui/console/src/pages/Hitl.tsx#L12-L23)
### 编辑模式
当选择 `edit` 操作时，页面显示可编辑的 textarea：
```tsx