# CR-20260607-001: 从 Agent PaaS 扩展为三档部署模式 (Desktop / Lab / PaaS)

**状态:** Draft (rev.2)
**日期:** 2026-06-07
**变更负责人:** Kenny Liu
**影响范围:** 产品定位、Web UI、Agent 模板、知识库、分发方式、商业化路径

## 修订历史

| 版本 | 日期 | 主要调整 |
|---|---|---|
| rev.1 | 2026-06-07 | 初稿: "从 PaaS 转向单机版个人助手", 暗示删除/简化多租户 |
| **rev.2** | 2026-06-07 | **改为"保留多租户能力, 引入 `deployment_mode` 三档"**: desktop 默认, lab 团队共享, paas 云端完整。所有 audit 已修复的多租户 scoping (#14 #28 #30 等) + 已落地的 132 个 test 在 lab/paas 模式下自动复用, 不删任何东西。M3 时间从 3-4 个月缩短到 2-3 个月。 |
| **rev.2-decisions** | 2026-06-07 | §十三 12 个开放问题全部记录决策 + rationale; 解除 M0 阻塞。同步起草 `ROADMAP.md` 把 M0-M5 落到团队跟踪面板。 |

---

## 一、变更摘要

当前项目原始定位偏向 **LambdAgent PaaS**：通过 `lambdagent` 内核、`agentpaas` 服务层和 Web UI，为用户提供可配置、可部署、可管理的 Agent 平台。

本次需求变更将第一阶段产品重心调整为：

> **面向教授、科研人员、医生等高知识密度职业的单机版专业个人助手。**
> **但保留多租户代码与能力作为团队版 (Lab) 与云端版 (PaaS) 的天然升级路径。**

产品第一优先级是可以下载安装、默认本地运行、可加载专业智能体包的桌面/本地 Web 应用。多租户路由、tenant scoping、RBAC、audit log 等已实现能力**不删除**, 改为按 `deployment_mode` flag 默认隐藏或暴露:

| 部署模式 | 默认场景 | 多租户路由 | 网络绑定 | 首次启动 |
|---|---|---|---|---|
| `desktop` | macOS / Windows installer 默认 | 路由仍挂载, webui 不显示 | `127.0.0.1` only | 自动 bootstrap 单 tenant + API key |
| `lab` | 课题组/科室局域网共享 | webui 显示, 1 tenant + N user | 局域网 IP | SetupWizard, 团队 admin 邀请成员 |
| `paas` | 云端服务化/未来形态 | 完整暴露 | `0.0.0.0` 经过反代 | 现行 PaaS 流程 |

升级路径线性: **desktop → lab → paas, 只换一行 config, 不动 319 处 tenant_id 代码, 不动 132 个测试**。

---

## 二、变更动机

### 2.1 原路线问题

直接以 PaaS 形态进入市场会过早遇到以下问题：

| 问题 | 影响 |
|---|---|
| 多租户隔离复杂 | 需要完善 RBAC、租户隔离、沙箱、密钥管理 |
| 云端合规压力大 | 科研未发表数据、医学资料、企业文档不适合默认上传 |
| 用户价值表达抽象 | "Lambda Calculus Agent PaaS" 对非技术用户不直观 |
| 竞品正面压力大 | Dify、LangGraph、LangSmith、Langfuse 等已占据平台心智 |
| 冷启动部署门槛高 | 教授、医生等目标用户不愿配置 YAML、API、Docker |

### 2.2 新路线机会

教授、科研人员、医生存在大量本地知识工作流：

- 阅读和归纳大量 PDF、指南、论文、课题资料。
- 审阅论文、基金、项目申请书、病例报告或综述。
- 需要保留引用、页码、修改痕迹和可追溯产物。
- 对资料上传云端存在天然顾虑。
- 愿意为节省时间、提升写作质量、保护隐私的软件付费。

因此第一阶段更适合做：

```text
本地资料 + 专业智能体 + 可追溯 workspace + 可下载应用
```

---

## 三、产品定位变更

### 3.1 原定位

> LambdAgent PaaS 是一个基于 Lambda 演算的 Agent 平台，用于构建、部署、运行和管理 AI Agent。

### 3.2 新定位

> LambdAgent Desktop 是一个本地运行的专业 AI 工作台。用户可以导入自己的论文、笔记、指南和项目资料，并安装不同领域的智能体包来完成科研、写作、审稿、资料整理等任务。

### 3.3 对外表达

优先使用面向用户的语言：

- 本地科研助手
- 私有论文库 AI
- 教授个人 AI 研究助理
- 医生本地文献与指南助手
- 可下载安装的专业智能体工作台

暂不作为主叙事使用：

- Lambda 演算 Agent PaaS
- 多租户 Agent 服务平台
- 通用 Agent 编排框架

---

## 四、目标用户

### 4.1 第一优先级: 科研人员

| 用户 | 核心任务 |
|---|---|
| 教授 / PI | 审学生论文、写基金、整理研究方向、评估创新性 |
| 博士后 / 博士生 | 文献综述、实验计划、论文初稿、投稿修改 |
| 科研助理 | 批量整理 PDF、生成阅读笔记、维护课题知识库 |

### 4.2 第二优先级: 医生与医学研究人员

| 用户 | 核心任务 |
|---|---|
| 临床医生 | 整理指南、总结文献、撰写病例报告草稿 |
| 医学科研人员 | 综述写作、Meta-analysis 辅助、课题申请 |
| 科室教学用户 | 指南学习、病例讨论材料准备 |

### 4.3 暂不优先

- 面向普通大众的聊天助手。
- 直接替代医生诊断/处方/治疗决策的临床 AI。
- 面向大企业的云端多租户 Agent 平台。
- 面向开发者的通用 Agent 编排 SDK 作为主产品。

---

## 五、MVP 范围

### 5.1 MVP 名称

暂定名：

```text
LambdAgent Desktop
```

科研场景版本可使用：

```text
ResearchAgent Desktop
```

### 5.2 MVP 一句话

> 一个本地运行的科研 AI 工作台，能导入 PDF/Obsidian/Zotero 资料，安装专业智能体，对论文、基金、文献和研究计划生成可追溯报告。

### 5.3 MVP 必须包含

| 模块 | 需求 |
|---|---|
| 部署模式 | 引入 `deployment_mode = desktop \| lab \| paas`, 默认 `desktop`。配置位置: 安装包写入 `~/.agentpaas/config.json`, 环境变量 `AGENTPAAS_DEPLOYMENT_MODE` 覆盖。 |
| 本地安装 | macOS / Windows 至少支持一种稳定安装包；技术用户可用 Docker |
| 本地资料库 | 支持导入 PDF、Markdown、TXT；建立本地索引 |
| 工作区 | 每次任务生成独立 `workspace/run_*`，保存输入、输出、引用、产物 |
| 智能体包 | 内置不少于 3 个科研智能体 |
| 引用追踪 | 回答和报告中尽量保留来源文件、页码或段落 |
| 模型选择 | 支持 Claude Code / API provider / Ollama 本地模型 |
| 隐私模式 | 默认本地优先，明确显示哪些内容会发送给云端模型 |
| 报告导出 | Markdown 为必选；PDF/DOCX 可后续支持 |
| 多 tenant 兼容 | 单 tenant 默认, 但 `tenants` / `users` / `api_keys` schema 保留; `lab`/`paas` 模式下立即可用 (无需 schema 迁移) |

### 5.4 MVP 不包含

- 多租户云端 SaaS。
- 医疗诊断或治疗建议。
- App Store / Microsoft Store 首发。
- 团队协作和组织级权限。
- 智能体 marketplace 交易系统。

---

## 六、核心功能需求

### 6.1 本地启动与安装

#### FR-001: 单机模式启动

系统必须支持单机模式：

```text
用户双击应用 / 执行启动脚本
→ 自动启动本地 agentpaas 服务
→ 自动打开本地 UI
→ 默认数据目录位于用户本机
```

要求：

- 不要求用户理解 FastAPI、YAML、Docker。
- 首次启动必须进入简化向导。
- 服务异常时 UI 要能给出可理解的修复建议。

#### FR-002: 数据目录管理

系统必须提供本地数据目录设置：

```text
~/LambdAgentDesktop/
  agents/
  agentpacks/
  knowledge/
  workspace/
  models/
  config/
```

用户应能在设置中查看和修改数据目录。

---

### 6.2 本地资料库

#### FR-003: 导入资料

MVP 支持导入：

- PDF
- Markdown
- TXT
- 文件夹批量导入

后续支持：

- DOCX
- Zotero library
- Obsidian vault
- BibTeX
- RIS / EndNote

#### FR-004: 本地索引

导入资料后，系统应执行：

1. 文本抽取。
2. 元数据识别。
3. 分块。
4. 本地索引。
5. 索引状态展示。

索引失败的文件必须显示原因，不允许静默失败。

#### FR-005: 引用与证据

任何基于资料库生成的研究结论，必须尽量包含：

- 来源文件名。
- 页码或段落位置。
- 原文摘录的短引用。
- 置信度或证据强度。

---

### 6.3 专业智能体包

#### FR-006: Agent Pack 格式

新增 `agentpack` 概念。一个智能体包是可下载、可安装、可版本化的目录：

```text
agentpack/
  manifest.yml
  agents/
  prompts/
  knowledge/
  examples/
  README.md
```

`manifest.yml` 至少包含：

```yaml
id: research.top-journal-reviewer
name: Top Journal Reviewer
version: 0.1.0
domain: research
audience:
  - professor
  - phd_student
entrypoint: agents/reviewer.yml
permissions:
  network: false
  file_write: workspace
  shell: false
model:
  recommended:
    - claude-code/sonnet
    - anthropic/claude-sonnet
    - ollama/qwen
```

#### FR-007: Agent Pack 安装

用户应能通过 UI 安装智能体包：

- 从本地 zip 安装。
- 从 GitHub Release URL 安装。
- 后续支持从官方目录安装。

安装前必须显示权限摘要：

```text
此智能体包将读取本地知识库，写入 workspace，不执行 shell，不访问网络。
```

#### FR-008: 内置科研智能体包

MVP 内置至少 3 个智能体包：

| Agent Pack | 功能 |
|---|---|
| `research.literature-mapper` | 对一个方向的 PDF 生成文献地图、方法分类、关键争议 |
| `research.top-journal-reviewer` | 对论文生成顶刊审稿意见、接收概率、修改清单 |
| `research.grant-planner` | 辅助生成基金立项依据、创新点、研究内容和风险 |

后续医学智能体包：

| Agent Pack | 功能 |
|---|---|
| `medical.guideline-summarizer` | 总结指南、保留证据等级和章节引用 |
| `medical.case-report-assistant` | 辅助病例报告写作，不给诊疗建议 |
| `medical.literature-update` | 按疾病/技术方向生成近期文献更新 |

---

### 6.4 科研工作流

#### FR-009: 论文审稿工作流

输入：

- 论文 PDF 或 LaTeX 目录。
- 目标期刊/会议。
- 审稿强度：普通 / 严格 / 顶刊。

输出：

```text
workspace/run_xxx/
  input/
  review_report.md
  acceptance_estimate.json
  revision_tasks.json
  evidence_map.json
```

报告必须包含：

- 摘要评价。
- 主要贡献判断。
- 创新性评价。
- 技术正确性风险。
- 实验/仿真充分性。
- 写作和结构问题。
- 中稿概率区间。
- 可执行修改清单。

#### FR-010: 文献地图工作流

输入：

- 一组 PDF。
- 研究问题。

输出：

- 研究主题分类。
- 方法谱系。
- 代表论文表格。
- 尚未解决的问题。
- 可以切入的研究方向。
- BibTeX 或引用清单。

#### FR-011: 基金写作工作流

输入：

- 研究方向。
- 已有论文/初稿/项目材料。
- 申请类型。

输出：

- 立项依据草稿。
- 科学问题。
- 创新点。
- 研究内容与技术路线。
- 风险与替代方案。
- 评审人可能质疑点。

---

### 6.5 医学场景限制

#### FR-012: 医学安全边界

医学智能体必须默认显示安全边界：

```text
本工具仅用于文献、指南、教学和写作辅助，不提供诊断、处方或治疗决策。
所有临床判断必须由有资质医生完成。
```

#### FR-013: 禁止能力

MVP 阶段禁止：

- 自动诊断。
- 自动处方。
- 对具体患者给出治疗方案。
- 直接生成面向患者的医疗建议。
- 替代医生签署病历或医疗文书。

#### FR-014: 医疗资料隐私

若用户导入病例或患者相关材料，系统必须：

- 提醒用户进行去标识化。
- 提供本地去标识化工具作为后续需求。
- 明确显示云端模型调用风险。
- 默认禁止将医学敏感资料发送到外部模型，除非用户显式确认。

---

## 七、隐私与安全需求

### 7.1 本地优先

#### SR-001: Local-first 默认策略

默认情况下：

- 文件保存在本地。
- 索引保存在本地。
- workspace 保存在本地。
- agent pack 保存在本地。
- 不上传用户资料到平台服务器。

#### SR-002: 云端模型透明提示

如果用户选择 Claude Code、Anthropic API、OpenAI-compatible 等云端模型，系统必须在任务开始前提示：

```text
本次任务将把以下内容发送给云端模型:
- 用户问题
- 检索到的相关片段
- 当前智能体提示词

不会发送:
- 完整知识库
- 未检索到的文件
```

#### SR-003: 权限模型

Agent Pack 必须声明权限：

| 权限 | 说明 |
|---|---|
| `read_knowledge` | 读取用户知识库 |
| `write_workspace` | 写入当前运行目录 |
| `network` | 访问网络 |
| `shell` | 执行 shell 命令 |
| `read_filesystem` | 读取知识库之外的文件 |

MVP 阶段默认禁止第三方 agent pack 使用 `shell`。

---

## 八、分发需求

### 8.1 第一阶段分发

| 渠道 | 用途 |
|---|---|
| GitHub Releases | 发布 macOS/Windows 安装包、agent pack zip |
| 项目官网 | 面向非技术用户下载 |
| Docker Hub / GHCR | 技术用户和实验室服务器部署 |
| Hugging Face / ModelScope | Demo、模型说明、agent pack 展示 |

### 8.2 第二阶段分发

| 渠道 | 用途 |
|---|---|
| Microsoft Store | Windows 用户信任分发 |
| Homebrew | macOS 技术用户安装 |
| PyPI | CLI / SDK 分发 |
| 官方 Agent Pack Registry | 应用内安装和更新 |

### 8.3 安装包要求

- macOS 包应完成签名和 notarization。
- Windows 包应尽量支持代码签名。
- 安装包必须包含清晰卸载方式。
- 首次安装不得要求用户手动编辑 `.env`。

---

## 九、商业化需求

### 9.1 免费版

面向获客：

- 本地资料库基础能力。
- 1 个科研智能体包。
- 每个知识库文件数限制。
- 基础 Markdown 报告导出。

### 9.2 Pro 版

面向个人教授/博士/医生：

- 无限本地知识库。
- 完整科研 agent pack。
- 批量论文审稿。
- 基金写作工作流。
- 高级导出。
- 本地模型加速配置。

### 9.3 Lab 版

面向课题组。**技术上 = `deployment_mode=lab` + N 个 user 同属 1 个 tenant**, 无需 fork / 单独 SKU 维护:

- 多设备授权 (1 tenant, N user, N API key — schema 已存在)。
- 共享 agent pack (按 tenant scope, audit #30 修复后自动生效)。
- 共享模板，但不默认共享原始资料 (RBAC scope: `agents:*` vs `knowledge:read-own` — RBAC 字段已存在)。
- 课题组知识库导入工具。
- 优先支持。
- **BUSL 1.1 ≤10 user 阈值**自然对齐"1 课题组 ≤ 10 PI/学生"; 超出走 Custom。

### 9.4 定制版

面向实验室、医院科室、学院：

- 专属智能体包。
- 私有部署。
- 内部资料适配。
- 安全策略定制。

---

## 十、对现有项目的影响

### 10.1 `lambdagent`

保持作为核心运行内核：

- YAML 编译。
- Agent 执行。
- ReAct / chain / sub-agent。
- lint / compile / trace。

新增需求：

- agent pack manifest 校验。
- agent pack 权限声明解析。
- 本地资料引用结构标准化。

### 10.2 `agentpaas`

**不删, 不简化。** 引入 `deployment_mode` 三档, 现有 319 处 `tenant_id` 引用、29 文件、132 个 test 全部保留。`agentpaas/src/agentpaas/config.py` 加约 30 行:

```python
class Settings:
    deployment_mode: Literal["desktop", "lab", "paas"] = "desktop"
```

各模式下的差异化行为 (~200 LOC 跨 setup.py / app.py / webui 顶栏):

| 行为 | desktop | lab | paas |
|---|---|---|---|
| 首次启动 | 自动 bootstrap: 创建 `tenant_id="local-{uuid}"` + admin API key, 写入 `~/.agentpaas/config.json` | SetupWizard, admin 配置 | SetupWizard, 多 tenant |
| Network bind | `127.0.0.1` (强制) | 局域网 IP (可配) | `0.0.0.0` (经反代) |
| Webui 顶栏 | 隐藏 tenant chip, 显示模式标识 + 用户名 + 隐私状态 | 显示 tenant chip + 成员管理 | 完整 admin UI |
| `/tenants/*` `/billing/*` `/admin/*` 路由 | mount 但所有请求返回 404 (audit critical #1 的同种 loopback 守门思路) | mount + 403 (RBAC 不允许的话) | 完整暴露 |
| `/setup/bootstrap` | 自动调用一次, 后续返回 404 | 走 SetupWizard | 走 SetupWizard |
| 隐私警告 (SR-002) | 强制弹窗 | opt-in 配置 | opt-in 配置 |
| Agent Pack 安装 | webui 一键 | webui 一键 + admin scope | admin scope only |

升级路径: 用户从 desktop → lab 升级时, 只需 `AGENTPAAS_DEPLOYMENT_MODE=lab` 重启服务, 已有 tenant + agent + knowledge base 全部继承。

简化 auth 在 desktop 模式下表现为"自动管理"而非"功能弱化": 后端 schema 与代码路径不变。

### 10.3 `webui`

从管理后台调整为专业工作台：

| 原页面 | 新定位 |
|---|---|
| Dashboard | 今日工作、最近报告、知识库状态 |
| Agents | 智能体包 / 已安装助手 |
| Chat | 专业任务工作台 |
| Knowledge | 本地资料库 |
| Providers | 模型与隐私设置 |
| Agent Workspace | 报告与产物浏览器 |

### 10.4 `agentexample`

从示例目录升级为内置智能体包来源：

```text
agentexample/physics67       → research.physics-pipeline
agentexample/research67      → research.paper-workflow
agentexample/qaagent67       → research.local-qa
agentexample/pptagent67      → research.presentation-helper
```

---

## 十一、里程碑

### M0: 产品收敛

- 完成本需求变更评审。
- 确定产品名。
- 确定第一个目标用户群：教授/科研人员。
- 冻结 MVP 智能体包范围。

### M1: 单机壳与本地工作台

- 一键启动本地服务。
- 本地数据目录。
- 简化首次启动向导。
- 本地资料库导入 PDF/Markdown/TXT。

### M2: 科研智能体包

- `literature-mapper`
- `top-journal-reviewer`
- `grant-planner`
- Agent Pack manifest。
- 本地安装 agent pack。

### M3: 可下载 Beta

- GitHub Release 安装包。
- 官网下载页。
- 10 位真实科研用户试用。
- 收集任务成功率、留存和付费意愿。

### M4: Pro 版验证

- 激活码/授权机制。
- Pro agent pack。
- 批量审稿。
- Lab license 访谈。

---

## 十二、成功指标

### 产品指标

| 指标 | MVP 目标 |
|---|---|
| 首次安装到完成第一个任务 | < 10 分钟 |
| PDF 导入成功率 | > 90% |
| 审稿报告生成成功率 | > 80% |
| 报告包含引用比例 | > 80% |
| 单次任务产物可追溯率 | 100% |

### 用户指标

| 指标 | MVP 目标 |
|---|---|
| 真实试用用户 | 10-20 人 |
| 一周后再次使用 | > 40% |
| 愿意推荐给同组同事 | > 30% |
| 愿意为 Pro 付费 | > 20% |

### 商业指标

| 指标 | 早期目标 |
|---|---|
| 首批 Pro 付费 | 5-10 人 |
| 首批 Lab 试点 | 1-2 个课题组 |
| 单个用户月付费意愿 | 49-199 RMB 或 9-29 USD |

---

## 十三、开放问题（含决策记录）

每问下面紧跟 `[2026-06-07 决策]` 块。原始问题保留，便于未来需要 revisit 时回看 reasoning trail。

### 13.1 产品与场景

**Q1.** 第一版产品名使用 `LambdAgent Desktop` 还是 `ResearchAgent Desktop`？

> `[2026-06-07 决策]` **`ResearchAgent Desktop`**。
>
> Rationale: 教授 / 博士生 / 医生对 "Lambda 演算" 无认知亲和；"ResearchAgent" 直接命中场景。后续技术受众 (CLI / SDK / docs/) 仍可暴露 LambdAgent 品牌作为内核名。
>
> Revisit 触发: 出现 ≥3 个用户反馈 "想要这个工具但不知道做什么用的"。

**Q2.** 第一版优先 macOS 还是 Windows？

> `[2026-06-07 决策]` **macOS 先**。
>
> Rationale: 教授群体 Mac 占比 > 50% (与 Windows 不同, macOS 上 PDF/Zotero/Obsidian 用户密度高); Windows EV 证书购买流程 ≥ 3 个月 (个人开发者更长), 排队期间正好做 macOS。
>
> 并行准备: M0 当天就申请 Apple Developer 账号 ($99/年) + 开始 EV 证书申请。

**Q3.** 是否默认内置 Ollama，还是只检测本机 Ollama？

> `[2026-06-07 决策]` **只检测，不内置**。
>
> Rationale: Ollama 镜像 + 模型 200MB-7GB, 拖慢安装包；用户已安装的尊重之；未安装的提示 "[Open Ollama install page]"。Ollama 1-click 安装本身已经成熟。
>
> 例外: 如果 Phase D 测试发现 PDF chunking 必须用本地 embedding 模型, 可考虑内置 `all-MiniLM-L6-v2` (90MB) 作为唯一兜底。

**Q4.** 是否把 Claude Code 作为推荐默认 provider？

> `[2026-06-07 决策]` **是**。
>
> Rationale: 教授 / 科研用户 Claude 订阅渗透率高 (Anthropic Pro $20/月 vs OpenAI Plus $20/月, 学术圈 Anthropic 偏好明显)；Claude Code 不要 API key, 配合 "本地优先" 隐私叙事最匹配；Sonnet 在 reasoning / 长文档质量当前最强。
>
> SetupWizard 流程: 自动检测 Claude Code CLI → 检测到 → 默认。未检测到 → 列出 Anthropic API / OpenAI compatible / Ollama / DashScope 四个备选。

**Q5.** 医学场景是否延后到科研版本验证之后？

> `[2026-06-07 决策]` **是，延后到 M5 公开下载之后**。
>
> Rationale: FDA / CFDA / NMPA 对 "辅助诊疗" 边界模糊，即便有 FR-013 禁止能力声明，实操中医生写病例报告 → 投诉 → 监管介入的链条仍存在；科研版本可以单纯卖 "节省时间 / 提升写作质量"，没有医疗器械阴影。等科研验证产品力后再单独立项 ResearchAgent Medical, 配合医院法务一起推。
>
> 副作用: §6.5 的 4 个 FR (FR-012/013/014) 暂时 freeze, 标 "v2 scope"。

**Q6.** Agent Pack Registry 是否先用 GitHub Releases 实现？

> `[2026-06-07 决策]` **是**。
>
> Rationale: 零基建成本 (GitHub Releases 自带 CDN + 版本号 + 签名)；用户已熟悉 (科研人员普遍会从 GitHub 下载 .zip)；从 manifest.yml 里读 `download_url` 直接 GET zip → 解压到 `agentpacks/{id}/{version}/` 即完成安装；后续真正做 Registry 时可以无缝迁移 (Registry 只是 GitHub Releases 的 metadata 索引层)。
>
> 实现细节: GitHub Releases API `GET /repos/{owner}/{repo}/releases/latest` 返回 assets[] + tag_name, 客户端解析即可。无需自建 backend。

**Q7.** 是否需要与 Obsidian / Zotero 作为第一批集成？

> `[2026-06-07 决策]` **Obsidian: 是 (M2 内)；Zotero: 推迟到 M4 后**。
>
> Rationale:
> - Obsidian: vault 就是 markdown 文件夹, 直接遍历读 + 增量索引, 0 集成成本；目标用户重叠度高 (PARA / Zettelkasten 用户大量是教授/博士)。
> - Zotero: 数据走 SQLite + RDF/XML, library.bib 增量同步需要正确解析 fields；Zotero 用户群体也欢迎 .bib 导出, 第一版用 "拖一个 .bib 进来" 路径足够覆盖 80% 场景, 不需要直接读 ~/Zotero/。

---

### 13.2 部署模式

**Q8.** Webui 顶栏的 mode 标识是否可见？

> `[2026-06-07 决策]` **可见**。
>
> Rationale: 用户知道自己在 desktop / lab / paas 模式 → 信任感 + 故障排查时第一眼能确认状态。隐藏 mode 概念反而会让 lab 模式用户问 "为什么我看到了 admin 选项, 我同事看不到"。视觉设计: 顶栏右侧一个小 chip, `🖥️ Desktop` / `👥 Lab · {tenant_name}` / `☁️ PaaS · {tenant_name}`, 颜色分别用 teal / amber / indigo。

**Q9.** `desktop` 模式下被隐藏的路由 (`/tenants/*` `/billing/*` `/admin/*`) 返回 **404** 还是 **403**？

> `[2026-06-07 决策]` **404**。
>
> Rationale: 与 audit critical #1 已采用的 `/setup/bootstrap` oracle 防御一致 — 隐藏端点存在性 > 暴露权限语义。404 让远程扫描器看不出 desktop / lab / paas 之间的差异。代价: 内部 admin 误以为路由没 mount → 加 dev log 显示真实原因 (`Mode-blocked: deployment_mode=desktop, expected lab|paas`)。

**Q10.** `lab → paas` 升级路径是否需要 schema 迁移工具？

> `[2026-06-07 决策]` **不需要工具, 但 M1 期间写一次 mode-transition smoke test 验证。**
>
> Rationale: schema 已 paas-ready (audit 已确认 tenants / users / api_keys 三表完整, instance_dir 支持多实例)；mode 切换只影响"运行时行为", 不动数据。Smoke test: 起 desktop → 创建 1 tenant + 2 agent + 1 KB → 改 mode=lab 重启 → 同 tenant 下加一个 user → 改 mode=paas 重启 → 加一个新 tenant + 跑跨 tenant scope assert。三档全部跑通即结。

**Q11.** 单台 desktop 用户的 `tenant_id` 命名: `local-{uuid}` vs `{hostname}-{user}`？

> `[2026-06-07 决策]` **`local-{uuid}` (匿名)**，但 `tenants.name` 字段写 `{hostname}/{user}` (有 contextual 信息) 作为 alias。
>
> Rationale: tenant_id 是 PK + 出现在 logs / traces / 第三方 webhook payload, 用匿名 UUID 保护用户隐私 (避免 hostname 泄漏到 cloud LLM provider 的 logs)；name 字段只在 webui 顶栏 chip 显示, 帮用户在多设备 lab 升级时识别 "哦, 这个是 Alice 的 MacBook"。升级到 lab/paas 时 admin 可以改 tenant.name, 不用改 tenant_id (历史 trace 不断)。

**Q12.** Lab 模式的网络绑定: 默认 `0.0.0.0:8000` vs 默认 `127.0.0.1` + nginx 反代文档？

> `[2026-06-07 决策]` **默认 `127.0.0.1`, 文档 + SetupWizard 双路径教用户开 LAN**。
>
> Rationale: 与 audit critical #1 (loopback-only `/bootstrap`) 同款安全姿态 — 默认 secure, 用户显式 opt-in 开放。在 SetupWizard 里加 "团队共享" 一步, 选择 `允许局域网访问` 时:
> (a) 简单路径: 直接改 bind 到 `0.0.0.0`, 弹警告 "请确认你的局域网可信"；
> (b) 推荐路径: 指引装 nginx (一键 install script) + 加 self-signed cert + reverse proxy 到 `127.0.0.1:8000`。
> 默认指南给路径 (b), 路径 (a) 作为 "我知道我在做什么" 的 advanced toggle。

---

## 十四、结论

本次变更不废弃 `lambdagentpaas` 的平台能力，而是**通过 `deployment_mode` 三档将商业化和产品进入市场的顺序拆开**：

```text
desktop (今天默认)  → 单机专业助手 + agent pack 生态
                    ↓ 同一份代码, 改一行 config
lab                 → 课题组/科室团队版 (多 user 单 tenant)
                    ↓ 同一份代码, 改一行 config
paas                → 云端/私有化 (多 tenant 完整)
```

**关键工程价值**: rev.1 草案需要碰 29 个文件、删除 319 处 tenant 引用、回归 132 个 test。rev.2 实现只加约 200 LOC, 现有 audit 修复 (5 critical + 22 high) + 测试套件 + Phase 0-5 release 工作**零损失**。

这一路线既贴近当前代码资产, 又让教授 / 科研人员 / 医生第一眼看到 "下载即用", 同时为未来 Lab / PaaS 业务留下零成本通道。

