# agent-distillery

**Repository Path**: rr84/agent-distillery

## Basic Information

- **Project Name**: agent-distillery
- **Description**: 蒸馏，把专业知识结构化地提取出来，注入到 AI Agent 里，让它能以这个专家的方式思考和工作。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Distillery

将人类专业知识蒸馏为可移植的 AI Agent 技能 —— 像专家一样思考、决策和协作的数字分身。

面向企业生产环境，支持双路径蒸馏、LLM-as-Judge 评估、A/B 对比实验和多运行时部署。

## 功能亮点

- **双路径蒸馏** — 路径 A（结构化管线）：SKILL.md → Loader → UAS；路径 B（LLM 直接蒸馏）：原始素材 → Tool Calling 三阶段提取 → UAS
- **LLM-as-Judge 评估** — 规则引擎（12 条规则）+ LLM 语义评估并行评分，场景化测试 + 漂移检测
- **A/B 对比实验** — `agent-distillery benchmark` 量化对比三阶段 vs 单次蒸馏的结构质量（Schema 通过率、字段覆盖率）
- **审批门控** — 从 UAS tools_proficiency 和 escalation_policy 自动生成审批队列，支持 approve/reject
- **Dashboard 全栈面板** — React + FastAPI，8 个功能页面：制品管理、上传蒸馏、聊天验证、流水线、质量评估、智能体观察、审批队列
- **双运行时支持** — SemaClaw 和 LangGraph Emitter，灵活选择部署目标
- **隐私脱敏** — 内置 PII 检测与脱敏，存储前自动处理敏感数据

## 快速开始

### 安装

```bash
git clone https://gitee.com/rr84/agent-distillery.git
cd agent-distillery
pip install -e ".[dev]"
```

需要 Python 3.11+。

### 环境配置

LLM 蒸馏和评估功能需要 Anthropic 兼容 API。在项目根目录创建 `.env`：

```env
LLM_API_KEY=your-api-key
LLM_API_BASE=https://api.anthropic.com
LLM_MODEL=claude-sonnet-4-6
LLM_MAX_TOKENS=8192
```

### 启动 Dashboard

```bash
# 终端 1：后端
python -m uvicorn dashboard.backend.app:app --host 0.0.0.0 --port 8000

# 终端 2：前端（需要 Node.js 20+）
cd dashboard/frontend
npm install
npm run dev
```

前端访问 `http://localhost:5173`，通过 Vite proxy 将 `/api/*` 转发到后端 `:8000`。

Swagger API 文档：`http://localhost:8000/docs`。

### 最简 CLI 示例

```bash
# 校验已有 artifact
agent-distillery validate tests/fixtures/minimal.uas.yaml

# 运行蒸馏管线（路径 A：结构化 Loader）
agent-distillery distill --expert-id my-expert --data-dir ./data/raw --store-dir ./data/artifacts

# 发射到 SemaClaw 格式
agent-distillery emit my-expert --store-dir ./data/artifacts

# 发射到 LangGraph 格式
agent-distillery emit my-expert --store-dir ./data/artifacts --format langgraph

# LLM 语义评估（路径 B 产物）
agent-distillery evaluate my-expert --store-dir ./data/artifacts

# A/B 对比实验
agent-distillery benchmark --samples-dir benchmarks/source_samples

# 脱敏 PII
agent-distillery redact data/artifacts/my-expert/v1.0.0.uas.yaml

# 管理定时重新蒸馏
agent-distillery schedule add my-expert --interval 24 --threshold 0.3
```

## 架构

Agent Distillery 使用 **统一制品架构（UAS）** 作为核心数据模型。所有蒸馏工具输出到 UAS，所有运行时从 UAS 消费。支持两条独立路径：

### 路径 A：结构化管线

```
[OpenPersona SKILL.md]    ──→ OpenPersonaLoader    ──→ partial_UAS ──┐
                                                                       ├──→ Merger ──→ UAS ──→ Validator ──→ Store
[teammate-skill SKILL.md] ──→ TeammateSkillLoader  ──→ partial_UAS ──┘
```

### 路径 B：LLM 直接蒸馏

```
原始素材 (.jsonl) ──→ PII 脱敏 ──→ Tool Calling 三阶段蒸馏 ──→ Schema 校验 ──→ Store
                                     ├─ extract_identity
                                     ├─ extract_capabilities
                                     └─ extract_behaviors
```

两条路径的产物通过 `Validator` 校验后统一存入 `ArtifactStore`，再由 `Emitter` 发射到目标运行时：

```
Store ──→ SemaClawEmitter  ──→ persona.md + permissions.json
       ──→ LangGraphEmitter ──→ AgentState + graph config
```

### Dashboard 页面

| 页面 | 路由 | 功能 |
|------|------|------|
| 首页 | `/` | 系统总览、统计卡片 |
| 制品管理 | `/artifacts` | 浏览 UAS 制品四层结构（identity / capabilities / behaviors / evolution） |
| 上传蒸馏 | `/upload` | 路径 B 入口：上传素材 → 4 步向导 → 6 阶段进度（chunk → identity → capabilities → behaviors → validate → store） |
| 聊天 | `/chat` | UAS → System Prompt 对话验证，选择专家后以专家人格对话 |
| 流水线 | `/pipeline` | 路径 A 入口：触发结构化管线、查看进度 |
| 质量评估 | `/evaluation` | 三大区域：规则评分 + 漂移检测 / LLM 语义评估 / 场景化测试 |
| 智能体观察 | `/observer` | 已蒸馏专家列表 + 质量评分 + WebSocket 实时事件流 |
| 审批队列 | `/approvals` | 从 UAS 自动生成审批项（non-autonomous 工具 + escalation level ≥ 2），支持 approve/reject |

详见 [docs/architecture.md](docs/architecture.md)。

## 企业特性

- **审批流程** — 从 tools_proficiency 和 escalation_policy 自动生成审批队列，支持通过/拒绝操作
- **审计追踪** — 完整版本历史与 diff 跟踪
- **漂移监控** — 定时质量检查，自动触发重新蒸馏
- **隐私脱敏** — 可配置规则的 PII 自动检测与脱敏

## 支持的框架

| 框架 | Loader | Emitter | 状态 |
|------|--------|---------|------|
| OpenPersona | Yes | — | 稳定 |
| teammate-skill | Yes | — | 稳定 |
| SemaClaw | — | Yes | 稳定 |
| LangGraph | — | Yes | 稳定 |

## 示例

参见 [examples/distillations/](examples/distillations/)，包含可直接使用的专家蒸馏示例：
- **企业架构师** (Morgan Chen) — ADR 编写、设计评审、技术选型
- **SRE 工程师** (Jordan Park) — 事件响应、容量规划、Runbook

评估 benchmark 参见 [benchmarks/](benchmarks/)：8 组评估场景 + ground truth + A/B 对比结果。

## 开发

参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发环境搭建和贡献指南。

```bash
# 运行测试
pytest

# 代码检查
ruff check .

# 类型检查
mypy src/
```

## 许可证

[MIT](LICENSE)