@nicekit/agent

v0.2.0

Published

7 days ago

Nice Agent - AI Agent 管理平台服务包（FastAPI 后端 + React 前端 + 部署配置）

Downloads

297

0High
0Medium
0Low

healer007

agent ai fastapi mcp nicekit nice-agent

Nice Agent

Nice Today App 的 AI Agent 管理平台，基于 FastAPI + PydanticAI + React 构建。

🚀 快速开始

前置条件

Python 3.11+
Node.js 18+
(可选) Docker & Docker Compose
OpenAI API Key

1. 配置环境变量

cd nice-today-2.0/nice-agent
cp api/.env.example api/.env
# 编辑 api/.env，填入 OPENAI_API_KEY

2. 启动后端 API

cd api

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 启动服务
python -m app.main
# 或
uvicorn app.main:app --reload --port 8000

3. 启动前端

cd web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

4. 启动 CLI（可选）

cd api
python -m app.cli.main

5. 使用 Docker Compose（推荐）

docker compose up -d

启动后访问：

Web UI: http://localhost:3000
API 文档: http://localhost:8000/docs
Langfuse: http://localhost:3001

📁 项目结构

nice-agent/
├── api/                          # Python 后端 (FastAPI + PydanticAI)
│   ├── app/
│   │   ├── agents/              # Agent 定义 (BaseAgent + HealthAgent + AgentRouter)
│   │   ├── services/            # 业务服务
│   │   │   ├── agent_manager.py    # Agent CRUD + 持久化
│   │   │   ├── agent_cache.py      # PydanticAI Agent 实例缓存 (FEAT-035)
│   │   │   ├── agent_store.py      # SQLite 持久化层 (FEAT-035)
│   │   │   ├── chat_service.py     # 流式对话编排
│   │   │   └── multimodal.py       # 上传 + 文本提取
│   │   ├── tools/               # Agent 工具（健康/节气/五行/八字/易经）
│   │   ├── acp/                 # A2A 协议实现
│   │   ├── mcp/                 # MCP Client/Server
│   │   ├── middleware/          # 中间件（鉴权等，FEAT-035）
│   │   ├── observability/       # 可观测（Langfuse，FEAT-035）
│   │   ├── models/schemas.py    # Pydantic schema
│   │   ├── prompts/             # Prompt 模板 (citation_rules + culture_templates)
│   │   ├── data/                # 端侧知识库
│   │   └── cli/                 # Rich CLI
│   ├── tests/                   # 单元测试
│   ├── Dockerfile
│   └── requirements.txt
├── web/                          # React 19 + Vite 6 前端
│   └── src/{App.tsx, hooks/, pages/, services/, stores/, types/}
├── docs/                         # 文档（架构、PRD、需求、Code Review）
│   ├── ARCH-001-nice-agent-architecture.md
│   ├── PRD-001-nice-agent-mvp.md
│   ├── PRD-002-capabilities-enhancement.md
│   ├── REQ-001-nice-agent-core.md
│   └── REVIEW-001-nice-agent-code-review.md  # 代码审查报告
├── docker-compose.yml
└── README.md

🏗️ 技术架构

前端技术栈

| 组件 | 技术 | 版本 | |------|------|------| | 框架 | React | 19.x | | 构建 | Vite | 6.x | | AI SDK | Vercel AI SDK | 5.x | | 状态 | Zustand | 5.x | | 样式 | Tailwind CSS | 4.x | | 动画 | Framer Motion | 12.x |

后端技术栈

| 组件 | 技术 | 版本 | |------|------|------| | Web 框架 | FastAPI | 0.115+ | | Agent SDK | PydanticAI | 0.4+ | | 数据库 | SQLite (via aiosqlite) | 3.45+ | | 缓存 | Redis | 7.x（可选） | | 可观测 | Langfuse / Logfire | - |

基础设施

| 组件 | 技术 | 端口 | |------|------|------| | 反向代理 | Nginx | 80 | | 可观测 | Langfuse | 3001 | | 缓存 | Redis | 6379 | | 数据库 | PostgreSQL | 5432 |

🔐 鉴权（FEAT-035 TASK-010）

API Token 鉴权通过 API_TOKEN 环境变量启用：

# .env
API_TOKEN=your-secret-token-here

启用后所有写接口需要 Authorization: Bearer <token> 头。localhost 请求自动豁免，便于本地开发。

前端调用示例：

fetch("/api/agents", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(agentData),
});

📊 可观测（FEAT-035 TASK-010）

通过环境变量启用 Langfuse：

# .env
LANGFUSE_ENABLED=true
LANGFUSE_SECRET=...
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_HOST=http://localhost:3001

# 或者用 Logfire（pydantic-ai 也支持）
LOGFIRE_TOKEN=...

启用后所有 PydanticAI Agent 对话可追踪：token 用量、延迟、工具调用。

💾 持久化（FEAT-035 TASK-006）

Agent 配置默认用 SQLite 持久化（通过 aiosqlite），数据目录：

# 默认
/tmp/nice-agent-data/agents.db

# 自定义
AGENT_DATA_DIR=/data   # Docker 部署建议挂载到 volume

首次启动自动迁移：如果存在旧版 agents.json，会自动导入 SQLite 并备份为 agents.json.bak。

并发安全：写操作通过 SQLite WAL + 应用层锁支持多进程。

📚 API 文档

核心端点

# Agent 管理
GET  /api/agents              # 获取 Agent 列表
GET  /api/agents/{id}         # 获取单个 Agent
POST /api/agents              # 创建 Agent [需鉴权]
PUT  /api/agents/{id}         # 更新 Agent [需鉴权]
DELETE /api/agents/{id}       # 删除 Agent [需鉴权]
POST /api/agents/{id}/toggle  # 启用/禁用 Agent [需鉴权]

# 对话
POST /api/chat/stream         # SSE 流式对话
POST /api/chat                # 普通对话

# 文件
POST /api/upload              # 上传文件 + 自动文本提取
GET  /api/files/{file_id}     # 下载/预览已上传文件

# 健康数据
POST /api/health/data         # 查询健康数据
GET  /api/health/summary/{id} # 健康摘要

# 节气养生
GET  /api/solar-terms         # 节气列表
POST /api/solar-terms/info    # 节气详情

# MCP
GET  /api/mcp/servers         # MCP Server 列表
POST /api/mcp/servers         # 添加 MCP Server
DELETE /api/mcp/servers/{id}  # 断开 MCP Server
GET  /api/mcp/tools           # MCP 工具列表
POST /api/mcp/tools/call      # 调用 MCP 工具

# ACP（A2A 协议）
GET  /.well-known/agent.json  # Agent Card
POST /api/acp/tasks/send       # 任务委托
GET  /api/acp/agents           # 发现 ACP Agent

# 健康检查
GET /health                   # 服务健康状态（含存储后端）

SSE 流式响应格式

event: start
data: {"conversation_id": "conv_123", "agent_id": "..."}

event: intent
data: {"intent": "health_advice", "agent": "..."}

event: tool_call
data: {"tool": "get_health_data", "content": "..."}

event: message
data: {"content": "..."}

event: done
data: {"agent": "...", "intent": "..."}

event: error
data: {"error": "..."}

文件上传响应格式

{
  "file_id": "uuid",
  "file_name": "report.pdf",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "group": "document",
  "file_size": 12345,
  "size": 12345,
  "file_url": "/api/files/uuid",
  "extracted_text": "...",
  "md5": "...",
  "uploaded_at": "2026-07-06T14:30:00"
}

🔧 开发指南

添加新 Agent（系统预置）

在 api/app/prompts/culture_templates.py 添加模板函数（可选）
在 api/app/services/agent_manager.py:_build_system_agents() 注册
重启服务自动写入 SQLite

添加新 Agent（用户自建）

通过 Web UI（http://localhost:3000/agents）：

名称、图标、描述、system_prompt
MBTI 人格 + 温度 + 沟通风格
工具绑定（MCP 自动发现）
关键词

添加新工具

在 api/app/tools/ 创建新工具文件
在 api/app/tools/tool_registry.py:_get_xxx_tools() 注册
在 agent_manager.py 系统 Agent 的 tools 字段引用

工具签名要求：

async def my_tool(ctx: RunContext[ToolDeps], param: str) -> str:
    user_id = ctx.deps.user_id
    ...

运行测试

cd api
pytest                              # 全部测试
pytest tests/test_router.py -v      # 单个文件
pytest --cov=app                    # 覆盖率

当前测试数：220+ （含 70+ FEAT-035 新增）

🐛 故障排查

上传文件后 Agent 不分析内容

检查 extracted_text 字段是否返回非空
后端日志查找 Text extracted: ... 行
确认文件大小未超限（image: 10MB / document: 20MB / data: 5MB）

MCP Server 列表显示 "0 个工具"

确认 connected 为 true（看状态指示器）
检查后端 mcp_client_manager.list_servers() 输出
重连 MCP Server

Custom Agent 工具调用拿不到 user_id

确认 PydanticAI 版本 >= 0.4
工具签名第一个参数必须是 ctx: RunContext[SomeDeps]
调用 pydantic_agent.run() 时传 deps=SomeDeps(user_id=...)

鉴权 401

检查 Authorization: Bearer <token> 头格式
确认 .env 中 API_TOKEN 与请求头一致
localhost 请求应自动豁免

持久化数据丢失

旧版用 /tmp 路径，Docker 重启会丢
升级后用 SQLite 默认在 AGENT_DATA_DIR
Docker 部署务必挂载 /data 到 volume

🧪 测试

# 后端
cd api
pytest                                    # 全部
pytest tests/test_router.py tests/test_culture_templates.py -v  # 关键路径

# 前端
cd web
npm test                                  # vitest
npm run type-check                        # tsc --noEmit

📦 部署

Docker

docker compose up -d
docker compose logs -f api
docker compose ps

环境变量（生产）

# 必填
OPENAI_API_KEY=sk-...

# 强烈建议
API_TOKEN=<strong-secret>
AGENT_DATA_DIR=/data   # mount 到 volume
LANGFUSE_ENABLED=true
LANGFUSE_HOST=https://cloud.langfuse.com

🤝 贡献

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

Vercel AI SDK - 前端 AI 交互层
PydanticAI - Python Agent 框架
FastAPI - Web 框架
Langfuse - 可观测平台

维护者: Nice Today Team 最后更新: 2026-07-06 当前版本: 0.2.0 (FEAT-035 hardening)