Главная Обзор Помощь
Регистрация Вход
CaoZheng
/
lambdagent
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: main
Ветки Метки
lambdagent
/
docs
/
DESKTOP_MANUAL_zh.md

DESKTOP_MANUAL_zh.md 30 KB
Постоянная ссылка История Исходник

LambdAgent Desktop 安装与使用手册

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

目录

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

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

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

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

./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）

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

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

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

验证安装

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

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

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

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

./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：

./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 个内置包）打成一个原生可执行文件，用户双击即用：

./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 启动服务

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，服务重启后自动加载。

在公司/校园网络下接入在线模型若报 SSL: CERTIFICATE_VERIFY_FAILED（多为代理注入自签 CA），见 §14 Q9。

5.2 通过命令行配置

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

5.3 零 API Key 方案

本地 Ollama（完全离线）：

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. 你可调用确认接口放行或拒绝：
# 放行
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）速查

# 服务
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）即可，无其他系统残留。

Q9：在线模型报 SSL: CERTIFICATE_VERIFY_FAILED ... self-signed certificate in certificate chain？ 通常是公司/校园网络的代理或防火墙做了 TLS 拦截，往证书链里注入了自签根 CA，而 Python 默认信任库不认它（「测试连接」可能显示可达，但智能体实际调用会失败）。注意 PYTHONHTTPSVERIFY=0 对底层 urllib 不可靠，不要依赖它。

推荐做法（安全，验证仍开启） —— 导出公司根 CA 为 PEM，让程序信任它：

# macOS：把系统钥匙串里的根证书导出为一个 PEM 包
security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem
# 写入环境变量（指向上一步的 PEM）
echo 'AGENTPAAS_CA_BUNDLE=/Users/<你的用户名>/corp-ca.pem' >> ~/.agentpaas/.env

临时做法（不安全，仅限本地开发或你完全信任所处网络） —— 关闭证书验证：

echo 'AGENTPAAS_INSECURE_SSL=1' >> ~/.agentpaas/.env   # 会在日志打印醒目警告

两者都写进 ~/.agentpaas/.env 后重启服务生效（launchctl kickstart -k gui/$(id -u)/com.agentpaas.serve，或重启桌面应用）。优先级：AGENTPAAS_CA_BUNDLE > AGENTPAAS_INSECURE_SSL；都不设则保持系统默认。该配置进程级生效，覆盖所有在线 Provider 与工具的 HTTPS 调用。

15. 进阶配置

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

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      # 工作目录保留策略
AGENTPAAS_CA_BUNDLE=/path/to/corp-ca.pem   # 信任公司根 CA（应对 TLS 拦截代理，安全；见 Q9）
AGENTPAAS_INSECURE_SSL=1                    # 关闭 HTTPS 证书验证（不安全，临时；见 Q9）

三种部署模式：

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

开发模式（改前端）：

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