# LambdAgent Desktop 安装与使用手册

> 版本：v1.3.0 ・ 更新日期：2026-06-13
> 适用读者：科研人员、研究生、高校教师等**非技术背景用户**，以及需要本地部署的技术用户。

---

## 目录

1. [产品简介](#1-产品简介)
2. [系统要求](#2-系统要求)
3. [安装](#3-安装)
4. [首次启动与设置向导](#4-首次启动与设置向导)
5. [配置大模型（Provider）](#5-配置大模型provider)
6. [核心概念速览](#6-核心概念速览)
7. [Web 界面使用指南（含工作台/对话/记忆面板/模型切换）](#7-web-界面使用指南)
8. [记忆系统：让智能体记住上下文](#8-记忆系统让智能体记住上下文)
9. [工具与连接：MCP 工具 + 能力插件](#9-工具与连接mcp-工具--能力插件)
10. [内置科研智能体包](#10-内置科研智能体包)
11. [知识库：把你的文献变成可问答的资料库](#11-知识库把你的文献变成可问答的资料库)
12. [命令行（CLI）速查](#12-命令行cli速查)
13. [数据与隐私](#13-数据与隐私)
14. [常见问题与故障排查](#14-常见问题与故障排查)
15. [进阶配置](#15-进阶配置)

---

## 1. 产品简介

**LambdAgent Desktop** 是一个运行在你自己电脑上的 AI 智能体（Agent）工作台。它把大语言模型变成可以**读文献、写评审、做计划、管理知识库**的科研助手，并且：

- **本地优先（local-first）**：你的论文、数据、知识库都存在本机，只有发给大模型的文本会出网（使用本地 Ollama 模型时完全不出网）。
- **开箱即用**：内置顶刊审稿、文献地图、基金写作等科研智能体包，安装后即可使用。
- **全程可审计**：每次运行都保留完整的工作目录、执行轨迹（trace）、产物修改清单和成本记录，永不删除。
- **安全可控**：高危操作（删文件、系统命令）默认拦截或需人工确认；每个智能体可配置验收规则（Guard）。

底层由 **lambdagent** 演算内核驱动——智能体是带类型、效应和成本标注的 λ 项，运行前可静态预估成本，运行中可验证产物。

---

## 2. 系统要求

| 项目 | 要求 |
|---|---|
| 操作系统 | macOS 12+ / Linux / Windows（WSL2） |
| Python | 3.9 及以上（推荐 3.10–3.12） |
| Node.js | 18+（仅当你需要自行编译前端时） |
| 内存 | 4 GB 起；使用本地 Ollama 模型建议 16 GB |
| 磁盘 | 1 GB（不含模型与知识库数据） |
| 网络 | 使用云端大模型时需要联网；纯本地模型可离线 |

可选组件：

- **Ollama**（https://ollama.com）— 想完全离线、零费用运行时安装，推荐模型 `qwen2.5:7b`。
- **pandoc + XeLaTeX** — 审稿包导出 PDF 报告时需要（macOS：`brew install pandoc` + MacTeX；Linux：`apt install pandoc texlive-xetex`）。
- **Claude Code CLI** — 已有 Claude 订阅的用户可零 API Key 使用（见 §5.3）。

---

## 3. 安装

### 方式一：一键脚本（推荐）

```bash
git clone https://github.com/kenny67nju/lambdagentpaas.git
cd lambdagentpaas
chmod +x setup.sh
./setup.sh              # 安装依赖并启动服务
```

脚本会自动创建虚拟环境、安装 `lambdagent` 和 `agentpaas` 两个包，并启动服务。其他用法：

```bash
./setup.sh --install    # 仅安装依赖，不启动
./setup.sh --launch     # 安装并直接进入 Agent 对话
./setup.sh --docker     # 使用 Docker Compose 启动
./setup.sh --help       # 查看帮助
```

> **两种安装模式自动识别**：`setup.sh` 会先看同目录下有没有 `dist/*.whl`。
> 拿到**发行包**（解压后含 `dist/` 里两个 `.whl`、无源码）→ 从预编译 wheel 安装；
> 在**源码树**里（有 `lambdagent/`、`agentpaas/` 目录）→ editable 安装源码。
> 终端用户走前者，开发者走后者，命令都是 `./setup.sh`，无需关心区别。

### 方式二：手动安装（pip）

```bash
git clone https://github.com/kenny67nju/lambdagentpaas.git
cd lambdagentpaas
python3 -m venv .venv && source .venv/bin/activate
pip install -e lambdagent/          # 演算内核
pip install -e "agentpaas/[dev]"    # 平台服务（含开发依赖）
```

### 方式三：Docker

```bash
docker compose up -d                # 生产编排（docker-compose.yml）
# 或开发编排：
docker compose -f docker-compose.dev.yml up
```

Docker 模式下数据目录挂载到容器的 `/data`（由 `AGENTPAAS_DATA_DIR` 指定）。

### 验证安装

```bash
agentpaas serve --port 8000 &
curl http://127.0.0.1:8000/health
# 期望输出: {"status":"ok","version":"1.3.0"}
```

### 打包发布给他人（开发者）

要把产品发给别人，**不要**直接拷贝整个源码目录或让对方 `git clone`——那等于把全部源码、
测试、内部文档一并送出。有两档发行方式，按对源码保护的需求选：

**A. 普通 wheel 发行包**（最快，仍含 `.py`）：

```bash
./setup.sh --build      # 构建普通 wheel → dist/*.whl
./setup.sh --package    # 组装 release/（wheel + 启动脚本 + 前端产物 + 文档）
zip -r lambdagent-paas-1.3.0.zip release/
```

**B. 编译版 wheel 发行包（推荐用于对外分发，防逆向）**：用 Nuitka 把两个包编成原生 `.so`，
解开 `.whl` 只有机器码、没有 `.py`：

```bash
./setup.sh --build-secure   # Nuitka 编译 → dist-secure/*.whl（首次约数分钟）
./setup.sh --package        # 自动优先用 dist-secure/ 里的编译版组装 release/
zip -r lambdagent-paas-1.3.0.zip release/
```

**C. 单文件二进制（最强：防逆向 + 用户免装 Python）**：用 Nuitka 把整个应用（含内嵌
Python、依赖、前端、10 个内置包）打成一个原生可执行文件，用户双击即用：

```bash
./setup.sh --build-binary    # 默认 onefile 单文件 → dist-binary/agentpaas
# 资源受限/CI 机器可用 standalone 目录模式（更省内存、更稳）：
ONEFILE=0 ./setup.sh --build-binary    # → dist-binary/agentpaas-darwin-arm64.app/
# 默认打包 anthropic/openai SDK；dashscope/ollama 走 HTTP 无需 SDK。自定义:
PROVIDERS="anthropic openai" ./setup.sh --build-binary
```

用户用法：`./agentpaas serve --port 8000`，机器上**完全不需要 Python**。已实测：
单二进制在无 Python 环境启动服务、加载内嵌 Web UI、首启自动安装全部 10 个内置智能体包。

前置（B、C 通用）：本机有 C 编译器（macOS：`xcode-select --install`），以及**原生架构、
3.10+、带头文件**的 Python（macOS 上推荐 Homebrew 的 `python3.11`，不要用 Rosetta 下的
x86_64 Python，否则编出错架构）。

A/B 方式对方都是：解压 → `cd release` → `./setup.sh`，脚本检测到 `dist/*.whl` 即按发行模式安装；
C 方式直接把二进制（或 `.app/` 目录）发给对方即可。
`release/` 里**不含** `lambdagent/src`、`agentpaas/src` 源码树，也不含 `.git`、测试、内部文档。

> **关于源码保护（重要，请如实理解）**
> Python 是解释型语言，代码要在用户机器上运行，因此**任何纯本地分发都无法做到绝对不可逆**——
> 这是语言层面的客观限制。防护强度由弱到强：
> `.py` 源码（裸奔）< 普通 wheel < **Nuitka 编译 `.so` / 单文件二进制（本产品已支持，`--build-secure` / `--build-binary`）** < 核心逻辑放服务端（唯一数学上成立）。
> - **普通 wheel** 仍是 `.py` 打包，`unzip` 即可读源码，不混淆——价值只在「不泄露仓库历史/测试/内部文档」。
> - **编译版 wheel（`--build-secure`）/ 单文件二进制（`--build-binary`）** 把代码编成 Mach-O 机器码：**控制流/算法无法反编译回可读 `.py`**，已用 `--python-flag=no_docstrings` 去除 docstring。这是当前本地分发能做到的最强保护；二进制还顺带免去用户装 Python。
>   - ⚠️ **边界**：开源版 Nuitka **不加密字符串常量**——日志文本、错误信息、**尤其是写在代码里的 prompt**，用 `strings` 命令仍能提取。若 prompt 是核心 IP，需上 Nuitka Commercial（常量加密）或把 prompt 改为加密/远程加载。
>   - ⚠️ **平台绑定**：编译产物绑定「Python 小版本（wheel）/ 操作系统 + CPU 架构（二进制）」（如 `cp311`、`macOS arm64`）。用户环境需匹配；多平台分发要在各对应机器/CI 上分别构建。
>   - ⚠️ **二进制未打包**：chromadb 向量库、PDF 外部工具（pandoc/xelatex）等未内嵌——用到这些功能仍需系统侧依赖。
> **本产品定位为面向高校老师的单机产品 + BSL 1.1 协议**——真正的威慑来自授权条款，技术保护是叠加。
> 选择建议：一般用户用普通 wheel 即可；对外分发/防逆向用 `--build-secure`；想让用户「免装 Python、双击即用」且最强保护用 `--build-binary`。详见 `RELEASE_NOTES.md` 与 BSL 协议。

---

## 4. 首次启动与设置向导

### 4.1 启动服务

```bash
agentpaas serve                  # 默认监听 0.0.0.0:8000
# 或指定端口：
agentpaas serve --port 8067
```

桌面（desktop）模式是默认模式。首次启动时系统会自动完成初始化（auto-bootstrap）：

1. 创建你的本地租户和管理员 API Key，写入 `~/.agentpaas/config.json`；
2. 自动安装 10 个内置智能体包（见 §10）；
3. 清理上次异常退出遗留的运行记录。

### 4.2 打开 Web 界面

浏览器访问 **http://127.0.0.1:8000**。首次进入会看到**设置向导（Setup Wizard）**，按提示完成三步：

1. **选择数据目录** — 你的研究数据（知识库、运行记录、智能体实例）的存放位置。
   桌面模式默认为 `~/LambdAgentDesktop`（在访达/文件管理器中可直接看到）。
2. **配置大模型** — 填入至少一个 Provider 的 API Key（详见 §5），或选择本地 Ollama。
3. **完成登录** — 向导自动保存 API Key，之后打开页面即处于登录状态。

> 提示：`/setup` 相关接口只接受本机（127.0.0.1）访问，远程无法调用，不必担心初始化接口暴露。

---

## 5. 配置大模型（Provider）

LambdAgent 支持 8 类 Provider，可同时配置多个，不同智能体可使用不同模型。

| Provider | 模型示例 | 费用 | 配置方式 |
|---|---|---|---|
| **DashScope（阿里通义）** | qwen-max / qwen-plus | 按量计费 | API Key |
| **Anthropic** | claude-sonnet | 按量计费 | API Key |
| **DeepSeek** | deepseek-chat | 按量计费 | API Key |
| **OpenAI** | gpt-4o | 按量计费 | API Key |
| **智谱（Zhipu）** | glm-4 | 按量计费 | API Key |
| **Moonshot** | moonshot-v1-128k | 按量计费 | API Key |
| **Ollama（本地）** | qwen2.5:7b | **免费** | 无需 Key |
| **Claude Code** | sonnet | 订阅额度 | 无需 Key |

### 5.1 通过 Web 界面配置（推荐）

进入左侧菜单「**环境配置**」（Providers）页面 → 选择 Provider → 粘贴 API Key → 点击「**测试连接**」确认可用。Key 保存在本机 `~/.agentpaas/providers.json`，服务重启后自动加载。

### 5.2 通过命令行配置

```bash
agentpaas provider add dashscope --api-key sk-xxxx
agentpaas provider test dashscope     # 测试连通性
agentpaas provider list               # 查看已配置项
agentpaas provider models dashscope   # 列出可用模型
```

### 5.3 零 API Key 方案

**本地 Ollama（完全离线）：**

```bash
ollama pull qwen2.5:7b      # 下载模型（约 4.7 GB）
ollama serve                # 通常安装后已自动运行
```

智能体配置中将模型写为 `ollama/qwen2.5:7b` 即可，所有推理在本机完成、计费为 $0。

**Claude Code 订阅：** 已安装 Claude Code CLI 且有订阅的用户，模型写 `claude-code/sonnet`，直接使用订阅额度，无需任何 Key。

---

## 6. 核心概念速览

| 概念 | 含义 |
|---|---|
| **Agent（智能体）** | 一份 YAML 配置定义的 AI 助手：模型、系统提示词、工具、子智能体、验收规则。相当于"函数定义"。 |
| **Instance（实例）** | 同一个智能体模板 + 不同领域数据（如不同学科的知识库）= 不同实例。相当于"函数调用"。 |
| **Run（运行）** | 一次执行。每个 Run 拥有独立工作目录 `workspace/run_时间戳/`，包含输入、输出、轨迹、配置快照、成本、产物修改清单，**永不删除**。 |
| **AgentPack（智能体包）** | 可安装/卸载的智能体分发单元（zip），带权限声明清单（是否联网、是否可执行 shell、可写哪里）。 |
| **知识库（KB）** | 指向本地文件夹的文献/资料库，建索引后支持 BM25 检索、Wiki 编译和流式问答。 |
| **记忆（Memory）** | 三层：核心记忆（人设与关键事实）、回忆日志（近 50 次运行摘要）、档案记忆（知识库）。跨运行持久。 |
| **Guard（验收与安全）** | 智能体的"质检门"：输出验收表达式 + 失败重试 + 高危命令拦截/确认 + 输出长度限制。 |

---

## 7. Web 界面使用指南

左侧导航：**今日工作 / 智能体 / 智能体包 / 资料库 / 模型与隐私 / 工具与连接**。

### 7.0 今日工作台（首页）

打开界面默认进入工作台，这是日常入口：

- **AI 助手输入框（主角）**：直接用自然语言描述任务（例如「帮我审这篇论文 ~/Papers/draft.pdf，目标期刊 TSE」），系统用一次轻量分类自动判断该交给哪个智能体，命中后直达对话并预填好你的话；拿不准时弹出手动选择框（永远不会卡住）。
- **继续上次的工作**：跨智能体的最近运行列表（运行中的排最前），一键回到对话。
- **常用场景卡片**：审一篇论文 / 出一份试卷 / 写推荐信 / 设计一门课 —— 点击直达，没有对应智能体时自动从内置包创建。
- 底部一行显示累计运行次数与 token 用量，点击进模型页看明细。

### 7.1 创建智能体

「智能体」页 →「**新建**」，三种方式：

1. **从模板创建** — 下拉选择内置模板，表单自动预填，改名即用；
2. **从 ZIP 导入** — 上传智能体包 zip 文件；
3. **从目录导入** — 填本地配置目录路径。

创建表单关键字段：

- **模型**：如 `dashscope/qwen-max`、`ollama/qwen2.5:7b`；
- **系统提示词**：智能体的角色与行为约定；
- **类型**：`simple`（单轮）、`react`（多步推理+工具调用）、`chain` / `router` / `parallel`（编排）；
- **知识库关联**：勾选后对话时自动检索相关段落注入上下文。

### 7.2 编辑智能体与版本管理

点击智能体卡片 → 「编辑」。每次保存自动生成新版本；「版本历史」中可一键**回滚**到任意旧版本。

**「验收 & 安全」标签页（Guard）**：

- `validator`：输出验收表达式，例如 `'review_report' in x`（输出必须包含该文件名）；
- `retry`：验收失败自动重试次数；
- `dangerousCommandBlock`：拦截危险命令（`rm -rf`、磁盘操作等），默认开启；
- `highRiskConfirmation`：高危操作改为**弹出确认**而非直接拦截——运行中会收到确认请求，5 分钟内不确认则按拒绝处理；
- `maxOutputLength`：工具输出截断长度。

### 7.3 对话（Chat）

点击智能体 → 「对话」。这是日常使用的主界面：

- **实时推理过程**：ReAct 智能体的每一步「思考 → 调用工具 → 观察结果」以卡片实时展示，带效应标签（ε: IO/KB/Exec/Write/Memory）和实时成本（USD）；
- **停止按钮**：运行 ID 出现后即可随时点击 Stop 终止（终止接口永不限流）；
- **继续运行**：每条回复下方的「继续」按钮可在**同一工作目录**上迭代，三种模式：
  - `iterate` — 在上次产物基础上继续完善；
  - `edit` — 指定某个子智能体定向修改；
  - `chat` — 只追问讨论，不动产物；
- **工作目录浏览**：回复下方可直接浏览/下载本次运行产出的所有文件；
- **会话记忆**（顶部按钮）：
  - **新会话** — 开始一段干净对话（不带前情记忆），换话题时用；
  - **历史** — 列出该智能体过往的对话线程，点击恢复历史气泡接着聊；
  - 连续对话时第二句会自动带上前情，无需重复背景（详见 §8 记忆系统）。
- **记忆面板**（右侧抽屉，点「智能体记忆」）：核心记忆 / **待确认** / 近期对话三个标签。「待确认」里是系统自动提炼的、可能值得长期记住的事实，点「记住」纳入核心记忆、「忽略」丢弃。

> 如果运行期间后端重启，界面会自动查询该次运行的最终状态并妥善收尾，不会永久转圈。

### 7.4 高危操作确认

当智能体开启 `highRiskConfirmation` 且触发高危工具调用（如删除文件、写系统目录）时：

1. 对话流中出现 `confirm_required` 提示，显示工具名与原因；
2. 你可调用确认接口放行或拒绝：

```bash
# 放行
curl -X POST http://127.0.0.1:8000/api/v1/traces/<run_id>/confirm \
  -H "Authorization: Bearer <你的API Key>" -d '{"approved": true}'
# 拒绝: {"approved": false}；5 分钟超时自动拒绝
```

### 7.5 仪表盘与运行历史

「仪表盘」显示智能体数量、运行次数、成功率、平均时延、累计 token。每个智能体详情页可查看最近运行列表、健康分，点开单次运行可看完整 trace 与工具审计日志。

### 7.6 模型显示与切换

「模型与隐私」页顶部「使用中的模型」区块：列出每个智能体当前用的 provider/model，下拉一键切换。切换会生成新版本（旧配置在版本历史可回滚）；Ollama 选项会实时探测你本机实际装好的模型。

---

## 8. 记忆系统：让智能体记住上下文

智能体的记忆分五层，全部存在本机、跨运行持久：

| 层 | 作用 | 你看到的效果 |
|---|---|---|
| **会话记忆** | 同一对话线程内自动带前情（最近几轮 + 滚动摘要） | 连续追问不用重复背景，第二句「简答题换两道」它知道指的是上一份试卷 |
| **核心记忆** | 长期事实/偏好（学科、惯用格式、常用路径） | 你确认后长期生效；在记忆面板「待确认」里逐条确认 |
| **情景记忆** | 跨会话按当前问题语义召回的相关历史 | 换个对话问相关话题，它能想起以前处理过的类似任务 |
| **档案记忆** | 知识库（见 §10） | 挂接的文献库 |
| **工作记忆** | 单次运行内的对话历史 | 一次 ReAct 多步推理内部 |

**自动提炼，但不自动记**：每次对话后系统会提炼「可能值得长期记住的事实」放进**待确认区**，需要你在记忆面板点「记住」才转正。敏感信息（身份证、手机号、成绩、健康状况）有双层拦截，绝不会被自动记录。

**隐私**：记忆压缩/提炼默认复用该智能体自己的模型 —— 用本地 Ollama 的智能体，对话内容不会被偷偷送到云端。

操作入口：对话页顶部「新会话 / 历史」管理对话线程；右侧记忆面板管理核心记忆与待确认项。

---

## 9. 工具与连接：MCP 工具 + 能力插件

侧栏「工具与连接」页，两个标签：

### 9.1 MCP 工具（接入外部工具服务）

把外部 MCP 服务（如 arXiv 检索、数据库查询）接进来供智能体调用：

1. 「添加 MCP」→ 选连接方式（http / sse 端点，或 stdio 本机命令）→ 填地址，凭证填**环境变量名**（值写在 `~/.agentpaas/.env`，不直接存密钥）；
2. 点「测试」拉取工具清单，每个工具自动标注风险等级；
3. 启停开关控制是否对智能体可用。

**安全**：stdio 命令限 npx/node/python 等已知运行器；MCP 的删除/发送类工具默认标为高危，运行时需人工确认（见 §7.4）。

### 9.2 能力插件（prompt skill）

能力插件 = 一段提示词 + 工具依赖，挂载到智能体即扩充其能力，不用每个智能体重写提示词。例如一个「PDF 导出」插件，任何智能体挂上它就会用规范的中文字体导出 PDF。

- 「新建能力插件」填名称/描述/提示词/依赖工具；
- 在智能体配置里 `skills:` 引用即挂载；
- **安全**：插件提示词始终在系统规则**之后**、优先级更低，含可疑指令（「忽略以上规则」等）的插件会被拒绝；高风险工具（Bash/写删类）不会被插件自动授予。

---

## 10. 内置科研智能体包

桌面模式首次启动自动安装以下 10 个包（全部 local-first：工具层不联网、不可执行 shell），覆盖科研、教学、学术服务三类场景：

**科研类：**

| 包 | 用途 | 推荐模型 |
|---|---|---|
| **research.top-journal-reviewer**（审稿67） | 顶刊水准论文评审：读 PDF → 逐维度评审 → 中英文报告 + 机读结论 + PDF 导出 | claude-code/sonnet 或 dashscope/qwen-max |
| **research.multi-reviewer**（多视角审稿） | 主编排器派发 4 位专科审稿人（创新性/方法/实验/写作）独立评审后综合，盲点更少、可溯源到维度 | dashscope/qwen-max |
| **research.literature-mapper**（文献地图） | 围绕研究问题梳理文献脉络与谱系 | dashscope/qwen-plus |
| **research.grant-planner**（基金助手） | 生成基金申请书核心部分：立项依据、科学问题、创新点、技术路线、风险预案 | dashscope/qwen-max |
| **research.paper-polisher**（润色投稿） | 论文润色（只改语言、改动附理由）+ 语言问题清单 + cover letter 草稿 | dashscope/qwen-max |
| **research.rebuttal-assistant**（审稿回复） | 逐条拆解审稿意见（接受/澄清/商榷/超范围）→ response letter + 修改任务清单 | dashscope/qwen-max |
| **research.thesis-advisor**（论文指导） | 研究生开题/中期/学位论文第一轮把关：问题定位到章节、三档分级、附改法 | dashscope/qwen-max |

**教学类：**

| 包 | 用途 | 推荐模型 |
|---|---|---|
| **teaching.course-designer**（课程设计） | 教学大纲（OBE）、逐周教学日历、考核方案 + rubric、第一课教案 | dashscope/qwen-max |
| **teaching.exam-builder**（试卷题库） | 基于课程材料出卷不超纲：双向细目表 + A/B 平行卷 + 答案评分标准 | dashscope/qwen-max |

**学术服务类：**

| 包 | 用途 | 推荐模型 |
|---|---|---|
| **service.academic-letters**（学术信函） | 推荐信（中英）、邀请函、提名材料、评语；事实全部来自你的材料，绝不编造 | dashscope/qwen-max |

**使用方法**：「智能体包」页 → 选择包 → 「创建智能体」→ 对话中给出论文路径或研究方向即可。例如对审稿包说：

```
请评审这篇论文：/Users/你/Papers/manuscript.pdf，目标期刊 TSE
```

第三方包可通过「智能体包」页上传 zip 安装；声明 `shell: true` 的第三方包默认拒绝安装。

**更新包**：拿到新版包 zip 后，在包卡片上点「**更新**」选择文件即可。系统会：

1. 校验 zip 内的包 id 与当前包一致（误传别的包会被拒绝）；
2. 安装新版本（同版本号则覆盖重装）；
3. **自动把所有由该包创建的智能体切换到最新配置** —— 每个智能体生成一个新版本，旧配置保留在版本历史中，随时可在「编辑 → 版本历史」回滚。

更新完成后的提示会告诉你有几个智能体被同步刷新。

---

## 11. 知识库：把你的文献变成可问答的资料库

1. 「知识库」页 → 「新建」→ 填名称和**根目录**（你的文献文件夹，支持 PDF/DOCX/TXT/MD/CSV/HTML）；
2. 「添加文件」选入需要索引的文档；
3. 点「**建立索引**」（BM25 检索索引，后台任务，可查看进度日志）；
4. 可选：点「**编译 Wiki**」自动生成可浏览的知识 Wiki（可暂停/恢复）；
5. 使用：
   - 页内直接**搜索**或**流式问答**（边检索边回答）；
   - 在智能体编辑页**关联知识库**，对话时自动注入相关段落。

---

## 12. 命令行（CLI）速查

```bash
# 服务
agentpaas serve [--port 8000] [--dev]      # 启动服务（--dev 开发模式）
agentpaas launch <config.yml>              # 一键：起服务+注册 agent+进入对话

# CLI 配置
agentpaas config set --server http://127.0.0.1:8000 --api-key ap_xxx
agentpaas config show

# 智能体
agentpaas agent list
agentpaas agent create --name 审稿助手 --config reviewer.yml
agentpaas agent versions <agent_id>
agentpaas agent rollback <agent_id> --version 3

# 执行与对话
agentpaas run <agent_id> --input "..."     # 单次执行
agentpaas chat <agent_id>                  # 交互式对话
agentpaas runs <agent_id>                  # 运行历史
agentpaas trace <run_id>                   # 查看运行轨迹

# Provider 与 Key
agentpaas provider add dashscope --api-key sk-xxx
agentpaas provider test dashscope
agentpaas key create --name laptop
agentpaas usage --group-by model           # 用量统计

# 消息桥接（可选）
agentpaas wechat start <agent_id>          # 微信 ↔ Agent
agentpaas xiaoyi start <agent_id>          # 华为小艺 ↔ Agent
```

---

## 13. 数据与隐私

- **数据目录**（默认 `~/LambdAgentDesktop`）：知识库索引、智能体实例、运行工作目录全部在本机；
- **配置目录** `~/.agentpaas/`：`config.json`（登录凭证与数据目录选择）、`providers.json`（API Key）、`.env`（环境变量覆盖）；
- **出网内容**：仅发给所选大模型 Provider 的提示词文本（含你提供的论文内容）。使用 Ollama 本地模型时**完全不出网**；
- **运行留痕**：每次运行的输入/输出/轨迹/产物清单永久保留，可随时回查（这是特性：科研过程可审计）；
- **许可证**：BSL 1.1 — 10 用户以内免费生产使用，2031-04-05 后转 Apache 2.0。

---

## 14. 常见问题与故障排查

**Q1：启动后浏览器打不开界面？**
确认服务在跑：`curl http://127.0.0.1:8000/health`。若改过端口，访问对应端口。前端白屏时检查仓库根目录是否存在 `webui-dist/`（源码安装需 `cd webui && npm install && npm run build` 编译一次）。

**Q2：对话报 `[QWEN_ERROR]` / `[DASHSCOPE_ERROR]`？**
Provider Key 无效、欠费或超时。到「环境配置」页点「测试连接」定位；长论文用 qwen-max 时偶发首调超时，重试即可。

**Q3：返回 429 Rate Limited？**
触发限流（默认认证用户 60 次/分钟）。等 1 分钟或在租户配额中调高。「停止运行」接口永不限流，不用担心停不下来。

**Q4：审稿包导不出 PDF？**
缺 pandoc 或 XeLaTeX。macOS：`brew install pandoc` 并安装 MacTeX；Linux：`apt install pandoc texlive-xetex`。中文字体已内置 PingFang SC 方案（macOS）。

**Q5：Ollama 模型不响应？**
确认 `ollama serve` 在运行、模型已 `ollama pull`；智能体模型名需带前缀：`ollama/qwen2.5:7b`。

**Q6：运行卡住/界面一直转圈？**
点 Stop；若后端曾重启，重启后会自动把遗留的「运行中」记录收尾为失败/已取消，界面也会自动拉取最终状态。键盘 `Esc` 可强制解锁输入框。

**Q7：忘记 API Key？**
桌面模式凭证存在 `~/.agentpaas/config.json`，打开即可找回；或 `agentpaas key create` 新建。

**Q8：如何彻底卸载？**
删除仓库目录、`~/.agentpaas/`、数据目录（默认 `~/LambdAgentDesktop`）即可，无其他系统残留。

---

## 15. 进阶配置

环境变量写入 `~/.agentpaas/.env`（重启服务生效）：

```bash
AGENTPAAS_PORT=8067                        # 服务端口
AGENTPAAS_DATA_DIR=/path/to/data           # 数据目录（优先级最高）
AGENTPAAS_DEPLOYMENT_MODE=desktop          # desktop / lab / paas
AGENTPAAS_LOG_LEVEL=INFO
AGENTPAAS_CORS_ORIGINS=http://my-host:5173 # 自定义前端来源
AGENTPAAS_WORKSPACE_RETENTION_DAYS=30      # 工作目录保留策略
```

**三种部署模式**：

| 模式 | 场景 | 差异 |
|---|---|---|
| `desktop` | 个人电脑（默认） | 自动初始化；管理/计费接口隐藏 |
| `lab` | 课题组服务器 | 完整租户/配额/RBAC |
| `paas` | 多租户云服务 | 同 lab + 严格审计、HTTPS 强制 |

**开发模式（改前端）**：

```bash
agentpaas serve --dev          # 终端 1：后端 8000
cd webui && npm run dev        # 终端 2：前端 5173（热更新）
```

**静态分析 API**（运行前检查智能体配置）：`POST /api/v1/analyze/lint | type-check | cost | full` —— 可在不花一分钱的情况下预估最坏情况成本、检查类型与结构缺陷。

---

*遇到本手册未覆盖的问题，请查阅 `docs/` 目录下的专题文档，或在 GitHub 仓库提 Issue：https://github.com/kenny67nju/lambdagentpaas/issues*
