# Yszen AI

**Repository Path**: xcodinglifex/yszen-ai

## Basic Information

- **Project Name**: Yszen AI
- **Description**: Yszen AI是一个面向开发者的 Harness 架构基础项目，旨在为 AI 应用开发提供一个生产可用、易扩展、上下文友好的脚手架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: http://122.51.108.251/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

<img src="frontend/public/logo.svg" alt="Yszen AI" width="120" />

# Yszen AI

**一个开箱即用的 Harness 架构智能 Agent 基础项目**

基于 FastAPI + LangChain + LangGraph 构建，支持 Skill 渐进式披露、工具调用、上下文压缩、RAG 检索、企微接入等能力。

[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=white)](https://react.dev/)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.2-1C3C3C)](https://github.com/langchain-ai/langgraph)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[功能特性](#-功能特性) · [快速开始](#-快速开始) · [Harness 架构](#-harness-架构) · [Skill 框架](#-skill-框架) · [界面预览](#-界面预览)

</div>

---

## 📖 简介

**Yszen AI** 是一个面向开发者的 Harness 架构基础项目，旨在为 AI 应用开发提供一个**生产可用、易扩展、上下文友好**的脚手架。

> **什么是 Harness 架构？**
> Harness（驾驭/挽具）是 Anthropic 提出的智能 Agent 设计哲学，核心是**让 LLM 在受控、可观测的环境中调用工具**。它强调：
> - 🎯 **渐进式披露**：按需加载技能正文，避免一次性塞满上下文窗口
> - 🛠️ **工具优先**：Agent 只通过工具与世界交互，能力清晰可枚举
> - 🔁 **可观测**：每一次思考、调用、结果都通过事件总线流式输出

本项目把这些理念落地为一个开箱即用的全栈应用，**适合作为你 AI 项目的起点**。

```mermaid
graph TB
    subgraph Frontend["🎨 Frontend (React + TypeScript)"]
        UI[Chat UI]
        Settings[Settings]
        RAG_UI[RAG Manager]
    end

    subgraph Backend["⚙️ Backend (FastAPI)"]
        API[API Routes]
        Agent[Agent Service<br/>LangGraph 状态机]
        Skills[Skill Manager<br/>三阶段生命周期]
        Tools[Tool Registry]
        EventBus[Event Bus<br/>SSE 事件流]
        Compress[Context Compression]
    end

    subgraph Storage["💾 Storage"]
        DB[(SQLite<br/>用户/会话/消息)]
        Vector[(Milvus<br/>向量库)]
    end

    subgraph External["🌐 External Services"]
        LLM[LLM API<br/>OpenAI 兼容]
        Embed[Embedding<br/>阿里云百炼]
        WeCom[企业微信<br/>WebSocket Bot]
    end

    UI --> API
    Settings --> API
    RAG_UI --> API
    API --> Agent
    API --> Skills
    Agent --> Tools
    Agent --> Compress
    Agent --> EventBus
    Agent --> LLM
    EventBus -.SSE.-> UI
    Tools --> Skills
    Compress --> DB
    Agent --> DB
    RAG_UI -.检索.-> Vector
    Vector -.向量化.-> Embed
    WeCom --> Agent

    style Agent fill:#6366F1,color:#fff
    style Skills fill:#8B5CF6,color:#fff
    style EventBus fill:#10B981,color:#fff
```

---

## ✨ 功能特性

- 🧠 **智能 Agent 内核** —— 基于 LangGraph 的状态机，支持多轮工具调用与流式输出
- 🧩 **标准 Skill 框架** —— 三阶段生命周期（Discovery / Activation / Execution），自然语言 + 显式命令双触发
- 📚 **上下文管理** —— 自动摘要压缩、消息级缓存、Token 预算控制
- 🔧 **可扩展工具系统** —— 内置 Python 执行器、API 调用器、文件读取器、Skill 加载器,支持自定义注册
- 🔍 **RAG 检索增强** —— 集成 Milvus 向量库 + 阿里云百炼 Embedding/Rerank,支持文档管理
- 💼 **企微 WebSocket Bot** —— 通过企业微信智能机器人 SDK 接入，支持多用户多会话
- 🔐 **多用户认证** —— JWT 鉴权 + 用户级配置覆盖（每个用户独立的 API Key、模型选择）
- 🎨 **现代化前端** —— React 18 + TypeScript + shadcn/ui + TailwindCSS,深色模式、国际化、响应式
- 🐳 **一键 Docker 部署** —— 提供完整的 Dockerfile 与 docker-compose 配置
- 📋 **OpenSpec 变更管理** —— 内置规格驱动的变更工作流,适合规范化的迭代开发

---

## 🏗️ Harness 架构

Yszen AI 的核心是一个 **Agent Loop**，每一轮都遵循"思考 → 调用 → 观察 → 再思考"的范式：

```mermaid
sequenceDiagram
    autonumber
    participant U as 👤 用户
    participant F as 🎨 前端
    participant A as 🤖 Agent
    participant L as 🧠 LLM
    participant T as 🛠️ Tool
    participant E as 📡 EventBus

    U->>F: 输入消息
    F->>A: POST /api/chat (SSE)
    A-->>F: 建立事件流

    loop 多轮工具调用 (≤ max_rounds)
        A->>L: 上下文 + 工具列表
        L-->>E: think_chunk (流式)
        E-->>F: SSE 推送
        F-->>U: 实时显示思考

        alt LLM 决定调用工具
            L->>A: tool_calls
            A->>E: tool_start
            A->>T: 执行工具
            T-->>A: 工具结果
            A->>E: tool_end
            E-->>F: 渲染调用卡片
        else LLM 决定回复
            L->>A: final answer
            A->>E: message
            E-->>F: 显示最终回复
        end
    end

    A-->>F: done 信号
    F->>U: 渲染完整回复
```

### 关键组件

| 组件 | 文件 | 职责 |
|------|------|------|
| Agent Service | [backend/app/services/agent.py](backend/app/services/agent.py) | LangGraph 状态机，编排工具调用 |
| Tool Registry | [backend/app/tools/registry.py](backend/app/tools/registry.py) | 工具注册与分发 |
| Skill Manager | [backend/app/skills/manager.py](backend/app/skills/manager.py) | 三阶段技能生命周期 |
| Context Compression | [backend/app/services/context_compression.py](backend/app/services/context_compression.py) | 历史会话摘要压缩 |
| Event Bus | [backend/app/services/event_bus.py](backend/app/services/event_bus.py) | 事件流式分发 |

---

## 🚀 快速开始

### 前置要求

- **Python** 3.11+
- **Node.js** 20+
- **Docker** 20.10+（可选，用于容器化部署）
- 一个 OpenAI 兼容的 LLM API Key（项目默认使用 [MiniMax](https://www.minimaxi.com/)）

### 方式一：一键启动（推荐本地开发）

```bash
# 克隆项目
git clone https://github.com/<your-org>/yszen-ai.git
cd yszen-ai

# 复制环境变量模板
cp .env.example .env
# 编辑 .env 填入你的 API Key

# 一键检查、安装依赖并启动前后端
make run
```

启动完成后访问：
- 前端：http://localhost:5173
- 后端 API 文档：http://localhost:8000/docs

### 方式二：分别启动

```bash
# 后端
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 前端（另开终端）
cd frontend
npm install
npm run dev
```

### 方式三：Docker 部署

```bash
# 准备 .env 文件
cp .env.example .env

# 一键启动
docker-compose up -d
```

容器启动后访问：
- 前端：http://localhost
- 后端：http://localhost:8001

---

## 📁 项目结构

```
yszen-ai/
├── backend/                    # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/            # REST API 路由（auth/chat/sessions/rag/...）
│   │   ├── core/              # 核心配置、鉴权、异常处理
│   │   ├── db/                # SQLite 数据库（用户/会话/消息/设置）
│   │   ├── models/            # Pydantic 数据模型
│   │   ├── services/          # 业务服务（Agent/RAG/企微/上下文压缩...）
│   │   ├── skills/            # Skill 框架核心（三阶段生命周期）
│   │   ├── tools/             # 工具实现与注册中心
│   │   └── main.py            # FastAPI 入口
│   ├── skills/                # 内置 Skill 资源（SKILL.md + scripts/references/assets）
│   ├── data/                  # SQLite 数据文件（运行时生成）
│   ├── AGENT.md               # Agent 系统提示词
│   └── requirements.txt
├── frontend/                   # React + TypeScript 前端
│   ├── src/
│   │   ├── components/        # UI 组件（ChatInput/Sidebar/ToolCallCard...）
│   │   ├── pages/             # 页面（Chat/Login/RagManager/Settings...）
│   │   ├── stores/            # Zustand 状态管理
│   │   ├── hooks/             # 自定义 Hooks
│   │   └── App.tsx
│   └── package.json
├── openspec/                   # OpenSpec 变更管理（规格 + 变更提案）
├── scripts/                    # 启动脚本
├── docker-compose.yml          # 容器编排
├── Dockerfile.backend          # 后端镜像
├── Dockerfile.frontend         # 前端镜像（Nginx 静态托管）
├── nginx.conf                  # Nginx 反向代理配置
├── Makefile                    # 常用命令封装
└── .env.example                # 环境变量模板
```

---

## 🔧 配置说明

项目采用**两级配置策略**：

| 层级 | 文件/位置 | 用途 | 示例 |
|------|----------|------|------|
| 系统级 | `.env` | 服务端口、数据库路径等部署相关配置 | `BACKEND_PORT=8000` |
| 用户级 | 数据库（前端设置页面） | API Key、模型选择等用户个性化配置 | `MiniMax API Key` |

> 用户级配置会在运行时**覆盖**系统级，便于多租户场景下每个用户使用自己的 API Key。

### 关键环境变量

```bash
# 后端服务
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000

# 数据库
DATABASE_URL=sqlite:///./data/harness.db

# LLM（也可在前端设置页面配置）
MINIMAX_API_KEY=your_api_key
MINIMAX_MODEL=MiniMax-M2.5

# RAG（可选）
MILVUS_HOST=localhost
MILVUS_PORT=19530
BAILIAN_API_KEY=your_bailian_key
```

完整变量见 [.env.example](.env.example)。

---

## 🧩 Skill 框架

Skill 是 Yszen AI 中**最重要的扩展机制**，灵感来自 Anthropic 的 Skill/Agent 生态。

### 设计目标

1. **元数据常驻、正文按需** —— 启动时只加载所有 Skill 的 `name + description`，匹配命中后再加载完整正文
2. **自然语言 + 显式命令** —— 用户既可以说"帮我审查这段代码"，也可以输入 `/code-review`
3. **资源动态加载** —— `scripts/`、`references/`、`assets/` 在 Skill 执行阶段才加载

### 三阶段生命周期

```mermaid
graph LR
    Start([🚀 启动时])
    Discovery[Discovery<br/>扫描 SKILL.md]
    MetaCache[元数据常驻<br/>name + description]

    Query([💬 用户输入])
    Match{匹配方式}
    Explicit["显式命令<br/>/skill-name"]
    Semantic[自然语言<br/>语义匹配]

    Activation[Activation<br/>加载完整正文]
    Execution[Execution<br/>按需加载<br/>scripts / references / assets]
    Result([✅ 返回结果])

    Start --> Discovery --> MetaCache
    Query --> Match
    Match --> Explicit
    Match --> Semantic
    Explicit --> Activation
    Semantic --> Activation
    MetaCache -.提供候选.-> Match
    Activation --> Execution --> Result

    style MetaCache fill:#fef3c7,stroke:#f59e0b,color:#000
    style Activation fill:#dbeafe,stroke:#3b82f6,color:#000
    style Execution fill:#dcfce7,stroke:#22c55e,color:#000
```

### 目录结构

```
backend/skills/
└── my-skill/
    ├── SKILL.md          # 必需：元数据 + 正文
    ├── scripts/          # 可选：可执行脚本
    ├── references/       # 可选：参考资料（手册、模板）
    └── assets/           # 可选：静态资源（图片、模板文件）
```

### 创建一个 Skill

```markdown
---
name: my-skill
description: 当用户需要 XX 时使用。支持 YY，能输出 ZZ。
---

# 技能名称：我的技能

## When to Use
描述触发场景。

## How It Works
1. 步骤一
2. 步骤二

## Examples
### 输入
...
### 输出
...

## Anti-Patterns
- 不做什么
```

把这个目录放进 `backend/skills/`，重启后端即可生效。

### 内置 Skills

| Skill | 说明 |
|-------|------|
| `code-review` | 代码审查（Python/JS/Java） |
| `data-analysis` | 数据分析 |
| `summarize-text` | 文本摘要 |
| `hv-profile-creator-coach` | 高价值用户画像教练 |

---

## 📸 界面预览

<!-- TODO: 在此处贴 4-6 张界面截图,建议尺寸 1200x800 -->

### Skill 触发
![Skill+tools字体语言触发](frontend/public/chat.png)

### RAG 知识库管理
![RAG管理](frontend/public/rag.png)


### 设置中心
![配置](frontend/public/settings.png)

---

## 🛠️ 技术栈

### 后端
- **Web 框架**：[FastAPI](https://fastapi.tiangolo.com/) 0.115
- **Agent 框架**：[LangChain](https://www.langchain.com/) 0.3 + [LangGraph](https://github.com/langchain-ai/langgraph) 0.2
- **数据库**：SQLite（默认）/ 可替换为 PostgreSQL
- **向量库**：[Milvus](https://milvus.io/) 2.5
- **认证**：JWT (python-jose) + bcrypt
- **企微 SDK**：wecom-aibot-python-sdk

### 前端
- **框架**：React 18 + TypeScript 5.6
- **构建**：[Vite](https://vitejs.dev/) 5
- **UI 组件**：[shadcn/ui](https://ui.shadcn.com/) + [Radix UI](https://www.radix-ui.com/) + [TailwindCSS](https://tailwindcss.com/) 4
- **状态管理**：[Zustand](https://github.com/pmndrs/zustand)
- **数据获取**：[TanStack Query](https://tanstack.com/query)
- **Markdown**：react-markdown + remark-gfm

### 基础设施
- **容器**：Docker + Docker Compose
- **反向代理**：Nginx
- **CI/CD**：GitHub Actions（待补充）

---

## 🤝 贡献

欢迎贡献代码、报告 Bug 或提出新功能建议！

1. Fork 本项目
2. 创建特性分支：`git checkout -b feat/amazing-feature`
3. 提交变更：`git commit -m 'feat: add amazing feature'`
4. 推送分支：`git push origin feat/amazing-feature`
5. 提交 Pull Request

### 开发规范

- 代码风格：后端遵循 PEP 8，前端使用 ESLint
- 提交信息：遵循 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)
- 大型变更：建议先在 [openspec/](openspec/) 中提交变更提案

---

## 🗺️ 路线图

- [ ] 多 LLM 提供商支持（OpenAI / Anthropic / 通义千问 / DeepSeek）
- [ ] Skill 市场（在线浏览、一键安装）
- [ ] 工具沙箱（隔离 Python 执行环境）
- [ ] 多模态支持（图片、音频输入）
- [ ] 插件系统（动态加载第三方扩展）
- [ ] 完整的可观测性（OpenTelemetry 接入）

---

## 📄 License

本项目采用 [MIT License](LICENSE)。

---

## 🙏 致谢

本项目站在以下优秀开源项目的肩膀上：

- [Anthropic](https://www.anthropic.com/) —— Harness 与 Skill 设计哲学
- [LangChain](https://www.langchain.com/) —— Agent 编排基础
- [shadcn/ui](https://ui.shadcn.com/) —— 现代化 UI 组件
- [FastAPI](https://fastapi.tiangolo.com/) —— 现代 Python Web 框架

---

<div align="center">

**如果这个项目对你有帮助，欢迎点一个 ⭐ Star 支持一下！**

</div>