docs: CR rev.2 decisions + ROADMAP.md

## CR-20260607-001 §十三 — 12 个开放问题决策记录

每问下面追加 `[2026-06-07 决策]` 区块, 含 答案 + Rationale + (部分含
Revisit 触发条件 / 副作用 / 实现细节)。原始问题保留作为 reasoning trail。

§13.1 产品与场景 (7 决策):
  Q1 产品名         → ResearchAgent Desktop (LambdAgent 保留为内核名)
  Q2 平台优先       → macOS 先 (Windows EV 证书需 ≥3 月排队)
  Q3 Ollama        → 只检测不内置 (减少安装包体积)
  Q4 默认 provider → Claude Code (学术圈渗透率 + 无 API key 体验)
  Q5 医学场景      → 延后到 M5 后 (合规阴影 → ResearchAgent Medical
                     单独立项, FR-012/013/014 freeze)
  Q6 Pack Registry → GitHub Releases (零基建, latest API 已够用)
  Q7 集成顺序      → Obsidian M2 内 / Zotero 推迟到 M4 后

§13.2 部署模式 (5 决策):
  Q8  Mode chip   → 可见 (信任 + 故障排查; Desktop/Lab/PaaS 三色)
  Q9  路由隐藏     → 404 (与 audit critical #1 oracle 防御一致)
  Q10 schema mig  → 不需要工具, 但 M1 写一次三档 mode-transition test
  Q11 tenant_id   → local-{uuid} 匿名, tenants.name 写 {hostname}/{user}
  Q12 Lab bind    → 默认 127.0.0.1, SetupWizard 给 nginx 反代路径

## ROADMAP.md (NEW)

把 CR §十一里程碑 M0-M5 拆成可跟踪面板。结构:

  North star    一段产品愿景
  Now           本周任务 (5 项, 4 待办 1 完成)
  Next (M1)     1.5 月内: Phase B Desktop runtime + Phase C webui 改造
  Then (M2)     3 月内: Phase D AgentPack + E PDF 引用 + F 三个内置 pack
  M3            4 月内: macOS Beta + 10-20 真实用户内测 + 6 项成功指标
  Later         M4 Windows / M5 License + Pro
  Beyond        v1.2+ Lab / Zotero / 医学场景重启
  不做清单       明确划界与 CR §4.3 §5.4 一致
  Open risks    7 个跟踪项 + 概率 + 影响 + 缓解
  audit map     现存 84 finding 中 Desktop 仍需修 10 / Lab+PaaS 自动复用 46

ROADMAP 与 CR 双向同步, 任一文档更新都引用另一份。

## 决策的工程后果

- M0 解锁: Apple Developer 账号 + Windows EV 证书申请 立刻可启动
- M1 范围明确: 加约 200 LOC 而非删/改 319 处 tenant_id 引用 (CR rev.2 核心)
- M3 验收指标可量化: 首次安装 <10 min / PDF >90% / 审稿 >80% / 引用 >80%
- v1.0.0-rc2 与 audit 28/84 关闭进度的工作 100% 保留, 作为 Lab/PaaS 升级
  时的 free win

## 不在本 commit 范围

- working tree 仍有 3 个无关 modified (Chat.tsx / claude_code_provider
  / mkdocs.yml), 留作下一轮 WIP
- audit 文档 (docs/AUDIT_2026-06-05.md) 仍按之前决定保留本地不进 git

下一步: M0 4 个待办的并行启动 + spike deployment_mode flag 验证 200 LOC
估算。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ROADMAP.md

@@ -0,0 +1,223 @@
+# Roadmap
+
+## North star
+
+**ResearchAgent Desktop** — 一个本地运行的专业 AI 工作台，让教授、博士、医学研究人员把私有论文 / 笔记 / 指南导入后，用专业智能体完成论文审稿、文献综述、基金写作、病例报告等可追溯任务。
+
+战略路径（[`docs/requirements-change-personal-desktop.md`](docs/requirements-change-personal-desktop.md)）：
+
+```
+desktop  → 单机科研助手 + agent pack 生态     (M0-M3, 4 个月)
+   ↓ 同一份代码，改一行 config
+lab      → 课题组/科室团队版 (1 tenant, N user) (M5+, 商业验证后)
+   ↓ 同一份代码，改一行 config
+paas     → 云端/私有化 (N tenant)             (v2+, 已有完整能力)
+```
+
+## 现状（截至 2026-06-07）
+
+- `v1.0.0-rc2` 已发布，CI 全绿，132 测试通过 Python 3.10/3.11/3.12
+- audit 84 finding 关闭 28 个（critical 7/7、high 22/33）
+- 仓库 private，PaaS 叙事完整
+- CR rev.2 + 12 个开放问题决策已 commit
+
+---
+
+## Now (本周 — 2026-06-07 至 2026-06-14)
+
+**主题**: M0 产品收敛 + 解锁 Apple Developer / Windows EV 长流程
+
+| 任务 | Owner | 验收 | 状态 |
+|---|---|---|---|
+| 答 CR §13.1 + §13.2 共 12 个开放问题，记录到 CR doc | Kenny | CR rev.2-decisions commit ✓ | ✅ 完成 |
+| 起草 `ROADMAP.md` | Kenny | 本文档 ✓ | ✅ 完成 |
+| 申请 Apple Developer 账号 ($99/年) | Kenny | 收到 Apple ID 启用确认邮件 | 🔲 待办 |
+| 启动 Windows EV 代码签名证书申请（需 ≥3 个月） | Kenny | DigiCert/Sectigo 申请单提交 | 🔲 待办 |
+| 决定第一批 alpha 用户名单（3-5 位教授/博士） | Kenny | 名单 + 试用承诺 | 🔲 待办 |
+| spike: `deployment_mode` flag 200 LOC 估算 | Kenny | 1 个 PR 跑通 desktop / lab / paas mode 切换，132 test 全绿 | 🔲 待办 |
+
+---
+
+## Next (1.5 个月内 — M1, 至 2026-07-21)
+
+**主题**: Desktop runtime + 单 mode 改造
+
+按 CR §十一 M1 + §10.2 的实现细节展开：
+
+### Phase B — Desktop runtime（≈1 周）
+
+- [ ] `agentpaas/src/agentpaas/config.py` 加 `deployment_mode: Literal["desktop", "lab", "paas"]`
+- [ ] `agentpaas/src/agentpaas/api/v1/setup.py` 加 `mode=desktop` 自动 bootstrap 路径
+  - 首次启动: 创建 `tenant_id="local-{uuid}"`, `tenants.name="{hostname}/{user}"` (Q11), admin API key 写入 `~/.agentpaas/config.json`
+  - 后续启动: 直接读 config，跳过 wizard
+- [ ] `agentpaas/src/agentpaas/api/app.py` mode-aware 路由 mount
+  - `mode=desktop`: `/tenants/*` `/billing/*` `/admin/*` 路由仍 mount 但 middleware 强制 404 (Q9)
+  - `mode=lab|paas`: 完整暴露
+- [ ] mode-transition smoke test（Q10）: 三档全跑通 + tenant scope assert
+- [ ] Network bind 默认值: desktop `127.0.0.1` / lab `127.0.0.1`（Q12 默认安全）/ paas `0.0.0.0`
+
+### Phase C — Webui Desktop 工作台改造（≈1-2 周）
+
+- [ ] 顶栏 mode chip（Q8）: `🖥️ Desktop` / `👥 Lab · {tenant}` / `☁️ PaaS · {tenant}`
+- [ ] 文案重命名（无逻辑改动）
+  - `Dashboard` → 今日工作 / 最近报告 / 知识库状态
+  - `Knowledge` → 本地资料库
+  - `Providers` → 模型与隐私
+  - `Chat` → 专业任务工作台
+- [ ] 首次启动向导：数据目录 `~/LambdAgentDesktop/`（FR-002）+ provider 选择（Q4: Claude Code 默认）
+- [ ] SR-002 隐私警告 dialog: 调用云端模型前列出 "将发送 / 不发送" 清单
+- [ ] mode=desktop 时隐藏 webui 侧栏的 admin / billing / tenants 入口
+
+### 关键依赖与风险
+
+- Apple Developer 账号必须本月内 active（M3 才能 notarize macOS 包）
+- Windows EV 证书排队期间，Phase B+C 完全可以并行
+- `319 处 tenant_id 引用` 完全不动，Q10 smoke test 是这条假设的最终验证
+
+---
+
+## Then (3 个月内 — M2 至 2026-09-07)
+
+**主题**: AgentPack format + 3 个内置 pack + PDF 引用追踪
+
+### Phase D — AgentPack format（≈2-3 周）
+
+- [ ] `docs/AGENTPACK_SPEC.md` 起草: manifest.yml schema + permission model
+  - 必填: `id` `name` `version` `domain` `audience` `entrypoint` `permissions` `model.recommended`
+  - permission 字段: `read_knowledge` / `write_workspace` / `network` / `shell` / `read_filesystem`（CR §SR-003）
+- [ ] 后端端点: `POST /agentpack/install` `GET /agentpack/list` `DELETE /agentpack/{id}`
+  - 安装源（Q6）: local zip / GitHub Releases URL（`gh release download` 模式）
+  - 解压目标: `~/LambdAgentDesktop/agentpacks/{id}/{version}/`
+  - 装前权限摘要弹窗（CR FR-007）
+- [ ] permission 运行时 enforcement: lambdagent 内核里读 manifest, 不允许的工具直接 reject
+
+### Phase E — PDF 引用追踪（≈2-3 周）
+
+- [ ] 升级 `lambdagent/builtin_tools/qa_tools.py` 的 PyPDF2 路径到 `pdfplumber`（page-number-aware）
+- [ ] 引入 page-number-preserving chunker: 每 chunk 携带 `{file, page, char_offset, len}`
+- [ ] `lambdagent.rag.RAGTool` 输出格式扩展: `[Source N | filename.pdf p.12]` 而非现在的 `[Source N]`
+- [ ] Obsidian vault 导入（Q7）: 把 vault 路径当 root_dir，markdown 文件遍历 + 双向链 `[[wiki]]` 解析
+
+### Phase F — 3 个内置 agent pack（≈4-6 周，并行 D/E）
+
+- [ ] `research.literature-mapper` — 输入 PDF 集 + 研究问题 → 文献地图 + 方法谱系 + BibTeX
+  - 基于 `agentexample/research67` 改造
+- [ ] `research.top-journal-reviewer` — 输入论文 → 顶刊审稿意见 + 接收概率 + 修改清单
+  - 基于 `agentexample/physics67/agents/reviewer.yml` 改造
+- [ ] `research.grant-planner` — 输入方向 + 已有材料 → 立项依据 + 创新点 + 技术路线 + 风险
+  - 基于 `agentexample/research67` 改造
+- [ ] agentexample 整体升级为 agentpack 来源（CR §10.4 映射表）
+
+### 同期任务
+
+- [ ] alpha 用户访谈（3-5 位），录三个真实 use case 视频
+- [ ] 内部 dogfood: 让 Kenny 自己用 ResearchAgent Desktop 完成一篇论文审稿，记录痛点
+
+---
+
+## M3 (4 个月内 — 至 2026-10-07)
+
+**主题**: macOS Beta 可下载 + 10-20 位真实用户内测
+
+### Phase G — macOS Installer（≈3-6 周）
+
+- [ ] PyInstaller spike: 嵌入 Python 3.12 + uvicorn + 全部依赖 + webui-dist 静态文件
+- [ ] 启动器: 双击 .app → 后台启 uvicorn → 自动 `open http://127.0.0.1:8000`
+- [ ] notarization 走通: Apple Developer ID + xcrun altool / notarytool
+- [ ] .dmg 安装包: 拖到 Applications 即装
+- [ ] 自动更新: 检测 GitHub Releases latest，提示用户
+
+### 用户验证（CR §十二 成功指标）
+
+| 指标 | M3 目标 |
+|---|---|
+| 首次安装到完成第一个任务 | < 10 分钟 |
+| PDF 导入成功率 | > 90% |
+| 审稿报告生成成功率 | > 80% |
+| 报告包含引用比例 | > 80% |
+| 真实试用用户 | 10-20 人 |
+| 一周后再次使用 | > 40% |
+
+### Release 动作
+
+- [ ] tag `v1.1.0-beta1`
+- [ ] GitHub Release（prerelease）含 .dmg / .zip
+- [ ] 写 `docs/USER_GUIDE.md` 面向非技术用户（教授友好语言）
+
+---
+
+## Later (5-7 个月 — M4 + M5)
+
+### M4 — Windows Beta（≈4-6 周）
+
+- [ ] Windows EV 证书到位 → PyInstaller + signtool
+- [ ] .msi / .exe 安装包，无 SmartScreen 警告
+- [ ] Microsoft Store 评估（独立工作流）
+- [ ] 与 macOS Beta 同步功能矩阵，跑同样的成功率指标
+
+### M5 — License + Pro 版（≈3-4 周）
+
+- [ ] License key 验证（推荐用 Paddle / Lemonsqueezy 第三方，不自建支付）
+- [ ] Free / Pro 功能门控
+  - Free: 1 个 agent pack, 知识库 100 文件, Markdown 报告
+  - Pro: 全部 agent pack, 无限制知识库, 批量审稿, PDF/DOCX 导出
+- [ ] 定价试验: 49 RMB / 月 vs 199 RMB / 月 vs $9 / $29 USD（CR §十二）
+- [ ] 首批 5-10 位 Pro 付费用户跟踪
+
+---
+
+## Beyond (v1.2+)
+
+不在 v1.x scope, 但已经在 CR 里 mark 为路径终点的：
+
+- **Lab 版正式商用** — `deployment_mode=lab` UI/营销已就绪，等 Pro 用户里出现 "我们课题组想团购" 信号触发
+- **Zotero 集成** — Q7 推迟到这里
+- **医学场景重启** — Q5 推迟到这里，配合医院法务一起立项 ResearchAgent Medical
+- **Agent Pack Registry 自建** — 等 GitHub Releases 路径覆盖不够时再做
+- **私有化部署 / paas mode 商业化** — 等 Lab 版有 ≥5 个课题组实际跑通后
+
+---
+
+## Roadmap 里没有的事情（不做清单）
+
+明确不做（与 CR §4.3 + §5.4 一致）：
+
+- 多租户云端 SaaS 公开发布（v2 之前不做）
+- 医疗诊断 / 处方 / 治疗决策（永远不做，CR FR-013）
+- App Store / Microsoft Store 首发（M5+ 看情况）
+- 团队协作 + 组织级权限（v1.x 不做）
+- Agent Pack marketplace 交易系统（v1.x 不做）
+- 面向普通大众的聊天助手（不做，定位偏离）
+- 通用 Agent 编排 SDK 作为主产品（lambdagent 仍开源但不再是产品门面）
+
+---
+
+## Open risks（持续跟踪）
+
+| 风险 | 概率 | 影响 | 缓解 |
+|---|---|---|---|
+| Apple Developer 账号审核 > 2 周 | 中 | M3 阻塞 | 立刻申请，准备备用账号 |
+| Windows EV 证书 > 3 个月到货 | 高 | M4 阻塞但不阻塞 M3 | 提前 M0 当天申请 |
+| PDF 引用追踪准确率 < 80% | 中 | M3 验收指标失守 | Phase E 期间用 5 篇 SOTA 论文跑 ground truth |
+| Alpha 用户找不齐 3-5 位 | 中 | M3 反馈不足 | M0 期间通过个人网络锁定 |
+| `deployment_mode` flag 改动 break 现有 132 test | 低 | M1 阻塞 | spike 阶段就跑全套 test 验证 |
+| 医学场景外部压力（用户主动要） | 中 | 偏离 roadmap | 坚持 Q5 决策，给出 "不做" rationale |
+| BUSL ≤10 user 与 Lab 多设备认定冲突 | 低 | 法律风险 | Lab 版上线前请律师 review 一次 BUSL 文本 |
+
+---
+
+## How this roadmap maps to existing audit work
+
+[`docs/AUDIT_2026-06-05.md`](docs/AUDIT_2026-06-05.md) 的 84 个 finding 中：
+
+- **28 已关闭**（截至 rc2）— 5 critical + 22 high + 1 medium + 1 low
+- **56 待办**，按 mode 影响分类：
+  - **Desktop 模式下仍需要修**（10 个）: #11 #13 并发 race, #22 #23 webui 稳定性, #17 pickle RCE, #16 qaagent67lambda 硬编码路径
+  - **只在 lab/paas 模式生效**（46 个）: tenant scoping 加固类、多用户 admin 类、RBAC 细化类、SPEC 漂移类。这些在 M1 完成后自动复用，**不需要重新修**。
+
+**Desktop 优先级 + 多租户保留** 这条战略选择，让 audit 修过的工作成为 lab/paas 升级时的 free win，不需要为 desktop 单独再修一遍。
+
+---
+
+最后更新: 2026-06-07
+本 roadmap 与 [`docs/requirements-change-personal-desktop.md`](docs/requirements-change-personal-desktop.md) 同步。需求决策记录见 CR §十三。

docs/requirements-change-personal-desktop.md

@@ -11,6 +11,7 @@
 |---|---|---|
 | 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 落到团队跟踪面板。 |
 
 ---
 
@@ -676,25 +677,104 @@ agentexample/pptagent67      → research.presentation-helper
 
 ---
 
-## 十三、开放问题
+## 十三、开放问题（含决策记录）
+
+每问下面紧跟 `[2026-06-07 决策]` 块。原始问题保留，便于未来需要 revisit 时回看 reasoning trail。
 
 ### 13.1 产品与场景
 
-1. 第一版产品名使用 `LambdAgent Desktop` 还是 `ResearchAgent Desktop`？
-2. 第一版优先 macOS 还是 Windows？
-3. 是否默认内置 Ollama，还是只检测本机 Ollama？
-4. 是否把 Claude Code 作为推荐默认 provider？
-5. 医学场景是否延后到科研版本验证之后？
-6. Agent Pack Registry 是否先用 GitHub Releases 实现？
-7. 是否需要与 Obsidian / Zotero 作为第一批集成？
-
-### 13.2 部署模式 (rev.2 新增)
-
-8. Webui 顶栏的 mode 标识是否可见？推荐**可见** (用户知道自己是 desktop / lab / paas, 安全感 + 信任), 还是**透明** (完全不暴露 mode 概念)？
-9. `desktop` 模式下被隐藏的路由 (`/tenants/*` `/billing/*` `/admin/*`) 返回 **404** (更隐蔽, 与 audit 已采用的 oracle 防御一致) 还是 **403** (语义更准)？
-10. `lab → paas` 升级路径是否需要 schema 迁移工具？(预期不需要 — schema 已是 paas-ready, 只是 mode 切换。需要单独验证一次。)
-11. 单台 desktop 用户的 `tenant_id` 命名: `local-{uuid}` (匿名) vs `{hostname}-{user}` (有 contextual 信息便于后续 Lab 合并)? 涉及隐私 + 升级体验权衡。
-12. Lab 模式的网络绑定: 默认 `0.0.0.0:8000` 让局域网可达, 还是默认 `127.0.0.1` + 文档教用户加 nginx 反代? 前者更易上手, 后者更安全。
+**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。
 
 ---