Agent Demo

OpenAI 兼容的 Agent 服务，支持工具调用、Skills 技能系统、MCP 协议，并内置 Web UI。

目录结构

agent-py/                      # 仓库根目录 (REPO_ROOT)
├── .env                       # 运行时配置（从 .env.example 复制）
├── .env.example               # 配置模板
├── .venv/                     # Python 虚拟环境
├── logs/                      # 服务日志
├── scripts/                   # 安装与服务脚本
│   ├── install.sh / install.ps1
│   ├── server.sh / server.ps1
│   └── install.bat / server.bat
├── skills/                    # Agent 技能（SKILL.md）
│   ├── page-scrape-builder/
│   └── ...
└── agent-server-py/           # Python 应用 (PYTHON_ROOT)
    ├── pyproject.toml
    ├── requirements.txt
    ├── mcp_servers.json
    ├── examples/
    └── src/agent_demo/

路径约定（与代码一致）：

路径	说明
REPO_ROOT/.env	环境变量，由 config.py 加载
REPO_ROOT/skills/	Skills 目录，SKILLS_DIR=skills
REPO_ROOT/.venv	虚拟环境
REPO_ROOT/logs/	scripts/server.sh / scripts/server.ps1 写入日志
agent-server-py/mcp_servers.json	MCP 客户端配置

环境要求

• Python 3.11+
• macOS / Linux / Windows
• 可选：Node.js（部分 MCP 服务需要 npx）

一键安装

macOS / Linux

chmod +x scripts/install.sh scripts/server.sh
./scripts/install.sh

Windows（PowerShell 或 CMD）

.\scripts\install.ps1
# 或
scripts\install.bat

安装脚本会：

1. 在仓库根目录创建 .venv
2. 安装 requirements.txt 依赖并以可编辑模式安装本项目
3. 安装 Playwright Chromium（浏览器工具，可用 --no-browser / -NoBrowser 跳过）
4. 从 .env.example 生成 .env（若不存在）
5. 创建 logs/ 目录

安装完成后启动：

# macOS / Linux
./scripts/install.sh --start
./scripts/server.sh start

# Windows
.\scripts\install.ps1 -Start
.\scripts\server.ps1 start
# 或
scripts\server.bat start

手动安装

# 1. 创建虚拟环境（在仓库根目录）
cd agent-py
python3 -m venv .venv
source .venv/bin/activate

# 2. 安装依赖
pip install -r agent-server-py/requirements.txt
pip install -e agent-server-py

# 3. 安装浏览器（可选）
playwright install chromium

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env，至少设置 OPENAI_API_KEY、OPENAI_BASE_URL

# 5. 启动
./scripts/server.sh start

配置说明

编辑仓库根目录的 .env：

# 必填：大模型 API
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
DEFAULT_MODEL=gpt-4o-mini

# 服务端口
HOST=0.0.0.0
PORT=8888

# 可选：API 鉴权（Web UI 需填写相同 Bearer Token）
API_KEY=

# 文件工具允许访问的目录（相对 REPO_ROOT，也可用绝对路径）
FILE_TOOL_ALLOWED_DIRS=.,agent-server-py,skills

# Shell / grep / git 等工具（详见 .env.example）

内置工具概览

类别	工具
文件	read_file、write_file、edit_file、apply_patch、create_file、delete_path、move_path、glob_files、list_directory
搜索	grep（支持 .gitignore 忽略）
执行	run_shell、run_python
Git	git_status、git_diff、git_log（只读）
其他	http_request、浏览器工具、Skills、calculator

Web UI（/ui）支持为每个会话指定工作目录，服务端会自动授权该目录的文件访问，并注入项目类型与常用命令提示。

常用命令

macOS / Linux

./scripts/server.sh start     # 启动
./scripts/server.sh stop      # 停止
./scripts/server.sh restart   # 重启
./scripts/server.sh status    # 状态

Windows

.\scripts\server.ps1 start
.\scripts\server.ps1 stop
.\scripts\server.ps1 restart
.\scripts\server.ps1 status
# 或使用 scripts\server.bat start / stop / restart / status

访问地址

地址	说明
http://localhost:8888/ui	Web 聊天界面
http://localhost:8888/v1	OpenAI 兼容 API
http://localhost:8888/health	健康检查
http://localhost:8888/v1/skills	技能列表
http://localhost:8888/v1/tools	工具列表
http://localhost:8888/ui/config	Web UI 配置（含运行时 OS 信息）

添加 Skill

在 skills/ 下创建子目录并添加 SKILL.md：

skills/my-skill/
└── SKILL.md

SKILL.md 头部示例：

---
name: my-skill
description: 技能描述
---

# 技能正文
...

热重载：POST /v1/skills/reload 或 Web UI 中的重载按钮。

MCP 配置

编辑 agent-server-py/mcp_servers.json，参考 mcp_servers.json.example。

重载 MCP：POST /v1/mcp/reload

故障排查

Windows 安装报 Failed to build uvloop

uvloop 仅支持 Linux/macOS，Windows 上不能安装。请拉取最新代码后重新安装；或手动从 agent-server-py/requirements.txt 中删除 uvloop 那一行再执行 pip install -r requirements.txt。

Windows 手动能启动，脚本启动失败

请使用最新版 scripts/server.ps1（已改为直接调用 .venv\Scripts\python.exe，不再经 cmd.exe 重定向）。拉取代码后执行：

.\scripts\server.ps1 restart

若仍失败，查看 logs\server.log 与 logs\server.err.log（uvicorn 日志通常在后者）。

服务无法启动

# macOS / Linux
tail -f logs/server.log

# Windows
Get-Content logs\server.log -Wait -Tail 50

Skills 未加载

确认 skills/ 在仓库根目录（与 .env 同级），且 SKILLS_DIR=skills。

文件工具报路径不允许

检查 .env 中 FILE_TOOL_ALLOWED_DIRS，路径相对于 agent-py/ 仓库根目录。

浏览器工具不可用

# macOS / Linux
source .venv/bin/activate
playwright install chromium

# Windows
.\.venv\Scripts\Activate.ps1
playwright install chromium