docs: LambdAgent Desktop 安装与使用手册（中文版）

面向非技术科研用户的完整手册：三种安装方式、设置向导、8 类
Provider 配置（含 Ollama 离线/Claude Code 零 Key 方案）、核心概念、
Web 界面全流程（对话/继续运行/Guard/高危确认）、4 个内置科研包、
知识库、CLI 速查、数据隐私、12 条 FAQ、进阶部署模式。已入 mkdocs 导航。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/DESKTOP_MANUAL_zh.md

@@ -0,0 +1,399 @@
+# LambdAgent Desktop 安装与使用手册
+
+> 版本：v0.1.0 ・ 更新日期：2026-06-11
+> 适用读者：科研人员、研究生、高校教师等**非技术背景用户**，以及需要本地部署的技术用户。
+
+---
+
+## 目录
+
+1. [产品简介](#1-产品简介)
+2. [系统要求](#2-系统要求)
+3. [安装](#3-安装)
+4. [首次启动与设置向导](#4-首次启动与设置向导)
+5. [配置大模型（Provider）](#5-配置大模型provider)
+6. [核心概念速览](#6-核心概念速览)
+7. [Web 界面使用指南](#7-web-界面使用指南)
+8. [内置科研智能体包](#8-内置科研智能体包)
+9. [知识库：把你的文献变成可问答的资料库](#9-知识库把你的文献变成可问答的资料库)
+10. [命令行（CLI）速查](#10-命令行cli速查)
+11. [数据与隐私](#11-数据与隐私)
+12. [常见问题与故障排查](#12-常见问题与故障排查)
+13. [进阶配置](#13-进阶配置)
+
+---
+
+## 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       # 查看帮助
+```
+
+### 方式二：手动安装（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":"0.1.0"}
+```
+
+---
+
+## 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. 自动安装 4 个内置科研智能体包（见 §8）；
+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.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` — 只追问讨论，不动产物；
+- **工作目录浏览**：回复下方可直接浏览/下载本次运行产出的所有文件；
+- **记忆编辑**：查看与修改智能体的核心记忆和回忆日志。
+
+> 如果运行期间后端重启，界面会自动查询该次运行的最终状态并妥善收尾，不会永久转圈。
+
+### 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 与工具审计日志。
+
+---
+
+## 8. 内置科研智能体包
+
+桌面模式首次启动自动安装以下 4 个包（全部 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 |
+
+**使用方法**：「智能体包」页 → 选择包 → 「创建智能体」→ 对话中给出论文路径或研究方向即可。例如对审稿包说：
+
+```
+请评审这篇论文：/Users/你/Papers/manuscript.pdf，目标期刊 TSE
+```
+
+第三方包可通过「智能体包」页上传 zip 安装；声明 `shell: true` 的第三方包默认拒绝安装。
+
+---
+
+## 9. 知识库：把你的文献变成可问答的资料库
+
+1. 「知识库」页 → 「新建」→ 填名称和**根目录**（你的文献文件夹，支持 PDF/DOCX/TXT/MD/CSV/HTML）；
+2. 「添加文件」选入需要索引的文档；
+3. 点「**建立索引**」（BM25 检索索引，后台任务，可查看进度日志）；
+4. 可选：点「**编译 Wiki**」自动生成可浏览的知识 Wiki（可暂停/恢复）；
+5. 使用：
+   - 页内直接**搜索**或**流式问答**（边检索边回答）；
+   - 在智能体编辑页**关联知识库**，对话时自动注入相关段落。
+
+---
+
+## 10. 命令行（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
+```
+
+---
+
+## 11. 数据与隐私
+
+- **数据目录**（默认 `~/LambdAgentDesktop`）：知识库索引、智能体实例、运行工作目录全部在本机；
+- **配置目录** `~/.agentpaas/`：`config.json`（登录凭证与数据目录选择）、`providers.json`（API Key）、`.env`（环境变量覆盖）；
+- **出网内容**：仅发给所选大模型 Provider 的提示词文本（含你提供的论文内容）。使用 Ollama 本地模型时**完全不出网**；
+- **运行留痕**：每次运行的输入/输出/轨迹/产物清单永久保留，可随时回查（这是特性：科研过程可审计）；
+- **许可证**：BSL 1.1 — 10 用户以内免费生产使用，2031-04-05 后转 Apache 2.0。
+
+---
+
+## 12. 常见问题与故障排查
+
+**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`）即可，无其他系统残留。
+
+---
+
+## 13. 进阶配置
+
+环境变量写入 `~/.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*

mkdocs.yml

@@ -19,6 +19,7 @@ nav:
   - API Reference: api.md
   - AgentPaaS: agentpaas.md
   - Product:
+    - Desktop 安装与使用手册 (中文): DESKTOP_MANUAL_zh.md
     - Desktop Requirements Change: requirements-change-personal-desktop.md
   - Theory: theory.md
   - Research: