# LambdAgent PaaS 快速上手指南

本指南面向**非技术人员**，帮助你在几分钟内启动 LambdAgent 智能助手服务。

---

## 使用 Claude Code Max Plan（无需 API Key）

如果你已有 Claude Code Max Plan 订阅，可以**零配置**启动 Agent，无需任何 API Key。

### 第 1 步：修改配置

在 `agent-config.yml` 中设置 provider 为 `claude-code`：

```yaml
model:
  provider: claude-code
  name: sonnet
```

### 第 2 步：启动对话

```bash
# 交互式 Agent 对话
python3 -m agentpaas chat lambda

# 或直接运行示例 Agent
python3 agentexample/agent67/run.py --claude
```

无需设置环境变量、无需 `.env` 文件、无需 API Key -- 直接使用你的 Claude Code 订阅额度。

> **提示：** `ConversationLam` 会保持完整会话上下文，避免因历史截断导致的幻觉问题。

---

## 使用 Web 管理界面（推荐非技术用户）

LambdAgent PaaS 内置了一个可视化管理界面，无需命令行即可完成安装向导、创建智能体和进行对话。

### 开发模式（前后端分离）

```bash
# 终端 1 — 启动后端服务
source .venv/bin/activate
agentpaas serve --dev          # 监听 http://localhost:8000

# 终端 2 — 启动前端开发服务器
cd webui
npm install                    # 首次需要安装依赖
npm run dev                    # 监听 http://localhost:5173
```

打开浏览器访问 **http://localhost:5173**，按向导完成配置。

### 生产模式（UI 嵌入后端）

```bash
# 编译前端（只需执行一次）
cd webui && npm run build      # 输出到 webui-dist/

# 启动服务（同时提供 API 和 Web UI）
agentpaas serve --dev          # UI 地址：http://localhost:8000
```

### 首次配置向导

1. **环境检测** — 自动检查后端服务状态
2. **选择模型** — 选择 AI 提供商（Claude Code / Ollama 无需 Key）
3. **初始化平台** — 一键创建本地租户，自动生成 API Key

---

## 使用 API Key 方式（通用）

以下是需要 API Key 的传统启动方式。

## 前提条件

你只需要以下**其中一种**环境：

| 方式 | 需要安装 | 适合人群 |
|------|----------|----------|
| **方式 A: Python** | Python 3.10+ | 大多数用户 |
| **方式 B: Docker** | Docker Desktop | 不想装 Python 的用户 |

你还需要一个 **LLM 大模型的 API Key**（至少一个）：

| 提供商 | 获取地址 | 说明 |
|--------|----------|------|
| 阿里云 DashScope | https://dashscope.console.aliyun.com/ | 通义千问，推荐国内用户 |
| OpenAI | https://platform.openai.com/api-keys | GPT 系列 |
| Anthropic | https://console.anthropic.com/ | Claude 系列 |
| DeepSeek | https://platform.deepseek.com/ | 性价比高 |
| 智谱 AI | https://open.bigmodel.cn/ | GLM 系列 |
| Moonshot | https://platform.moonshot.cn/ | Kimi |
| Ollama（本地） | https://ollama.ai/ | 免费，无需 API Key |

---

## 方式 A: 一键脚本启动（推荐）

### 第 1 步：下载项目

```bash
git clone https://github.com/kenny67nju/lambdagent.git
cd lambdagent
```

### 第 2 步：运行安装脚本

```bash
chmod +x setup.sh
./setup.sh
```

脚本会自动：
1. 检查 Python 版本
2. 创建 `.env` 配置文件（首次运行会提示你填入 API Key）
3. 创建虚拟环境并安装所有依赖
4. 启动服务

### 第 3 步：访问服务

启动成功后，打开浏览器访问：
- 服务地址：http://localhost:8000
- API 文档：http://localhost:8000/docs

### 其他启动选项

```bash
# 仅安装依赖，不启动服务
./setup.sh --install

# 一键启动 Agent 对话（安装 + 启动 + 自动进入对话）
./setup.sh --launch

# 使用 Docker 启动
./setup.sh --docker

# 构建 wheel 发行包（开发者：打包发布用，产出 dist/*.whl，仍含 .py）
./setup.sh --build

# 防逆向：Nuitka 编译成 .so wheel（产出 dist-secure/，解开只有机器码，仍需 Python）
./setup.sh --build-secure

# 最强：Nuitka 打成单文件二进制（产出 dist-binary/，用户免装 Python，双击即用）
./setup.sh --build-binary
# 资源受限可用目录模式: ONEFILE=0 ./setup.sh --build-binary

# 组装「不含源码」的发行包 release/（有编译版则优先用，再 zip 后发给用户）
./setup.sh --package

# 查看帮助
./setup.sh --help
```

---

## 方式 B: Docker 一键启动

### 第 1 步：准备配置

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env，填入你的 API Key
nano .env    # 或用其他编辑器
```

### 第 2 步：启动

```bash
# 开发模式（SQLite，适合体验和测试）
docker compose up

# 生产模式（含 PostgreSQL + Redis）
docker compose --profile prod up
```

### 第 3 步：访问

- 服务地址：http://localhost:8000
- API 文档：http://localhost:8000/docs

停止服务：按 `Ctrl+C`，或运行 `docker compose down`

---

## 配置 Agent

项目根目录的 `agent-config.yml` 是默认的 Agent 配置文件。你可以修改它来定制你的智能助手：

```yaml
# agent-config.yml 关键配置项

# Agent 名称
name: SeeCoderManus
description: 智能编程助手

# 模型配置 — 修改 provider 和 name 来切换模型
model:
  provider: dashscope          # 改为你使用的提供商
  name: qwen3-max-2026-01-23  # 改为对应的模型名
  temperature: 0.7

# 系统提示词 — 定义 Agent 的角色和行为
systemPrompt: |
  你是一个智能助手。
  你能够帮助用户解决各种问题。
```

**支持的 provider 值：**
- `dashscope` — 通义千问（qwen 系列）
- `openai` — GPT 系列
- `anthropic` — Claude 系列
- `deepseek` — DeepSeek 系列
- `zhipu` — GLM 系列
- `moonshot` — Kimi
- `ollama` — 本地模型（免费）

---

## 常用命令速查

安装后，激活虚拟环境即可使用以下命令：

```bash
# 激活虚拟环境（每次打开新终端时需要）
source .venv/bin/activate

# ── AgentPaaS 服务命令 ──
agentpaas serve --dev              # 启动服务（开发模式）
agentpaas create-tenant --name "我的组织"  # 创建租户，获取 API Key
agentpaas launch agent-config.yml  # 一键启动：服务 + Agent + 对话

# ── LambdAgent 核心命令 ──
lambdagent run agent-config.yml "你好"     # 直接运行 Agent
lambdagent repl agent-config.yml           # 交互式对话
lambdagent lint agent-config.yml           # 检查配置文件
lambdagent compile agent-config.yml        # 编译查看 Lambda 表达式

# ── Provider 管理 ──
agentpaas provider list                    # 查看已配置的提供商
agentpaas provider add dashscope --api-key sk-xxx  # 添加提供商
agentpaas provider test dashscope          # 测试提供商连通性
```

---

## 常见问题

### Q: 启动报错 "Python 版本过低"
安装 Python 3.10 或更高版本：
```bash
# macOS
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12 python3.12-venv
```

### Q: 启动报错 "AGENTPAAS_MASTER_KEY required"
这说明你在生产模式运行但没设置密钥。解决方法：
```bash
# 生成密钥
python -c 'import secrets; print(secrets.token_hex(32))'

# 将生成的密钥填入 .env 文件的 AGENTPAAS_MASTER_KEY=
```

### Q: 提示 "No LLM provider configured"
至少在 `.env` 文件中配置一个大模型的 API Key。

### Q: Docker 启动失败
1. 确保 Docker Desktop 已启动
2. 确保已创建 `.env` 文件：`cp .env.example .env`
3. 查看日志：`docker compose logs`

### Q: 如何使用本地模型（不需要 API Key）
1. 安装 Ollama：https://ollama.ai/
2. 下载模型：`ollama pull qwen2.5:7b`
3. 在 `agent-config.yml` 中设置 `provider: ollama`

---

## 进阶: 选择执行引擎

lambdagent 支持双执行引擎。默认使用 `recursive`（Python 调用栈），对于复杂任务可切换到 `cek`（CEK Machine）以获得成本监控和循环检测：

```yaml
runtime:
  engine: cek
```

或通过 CLI：

```bash
lambdagent run agent-config.yml "你的任务" --engine cek
```

---

## 项目结构简介

```
lambdagentpaas/
├── setup.sh              # 一键安装启动脚本
├── .env.example          # 环境变量模板
├── .env                  # 你的实际配置（需自行创建）
├── agent-config.yml      # Agent 配置文件
├── docker-compose.yml    # Docker 编排文件
├── Dockerfile            # Docker 镜像定义
├── lambdagent/           # 核心引擎（Lambda 演算 Agent DSL）
├── agentpaas/            # 服务层（REST API + 多租户）
├── webui/                # 前端管理界面（React + Vite）
├── webui-dist/           # 前端编译产物（npm run build 生成）
├── agentexample/         # 示例 Agent 应用
└── experiments/          # 实验性脚本（非生产代码）
```