# Roadmap

## North star

**ResearchAgent Service** — 一家 AI-native research service company：用本地 Desktop 获取资料信任，用 AgentPack 自动化科研服务流程，用专家 QA 控制方差，向教授、博士、课题组交付可追溯的论文预审、文献地图、基金打磨等结果。

战略路径（[`docs/requirements-change-personal-desktop.md`](docs/requirements-change-personal-desktop.md)）：

```
service  → 论文预审 / 文献地图 / 基金打磨三类结果型 SKU  (M0-M3, pilot)
   ↑
desktop  → 本地资料入口 + 报告交付界面 + 隐私信任层        (M0-M3, 已在建)
   ↓ 同一份代码，改一行 config
retainer → 课题组月度服务 + Desktop Pro / Lab 承接自助需求  (M4-M5, 付费验证)
   ↓ 同一份代码，改一行 config
paas     → 私有化 / 多租户平台化                             (v2+, 服务跑通后)
```

核心商业假设：

- 客户不为 "一个 AI 工具" 付高价，客户为 **可交付科研结果** 付费。
- Desktop 是入口，不是收入上限；AgentPack 是生产线，不是 marketplace 起点。
- 专家 QA、SOP、COGS、返工率和低方差交付，是比下载量更重要的早期指标。

## 现状（截至 2026-06-07）

- `v1.1.0-rc1` 已发布，CI 全绿，**189 测试**通过 Python 3.10/3.11/3.12
- audit 84 finding 关闭 28 个（critical 7/7、high 22/33）
- 仓库 private，PaaS / Desktop / AgentPack 软件叙事完整；商业叙事已切换为 **AI-native research service**
- CR rev.2 + 12 个开放问题决策已 commit
- **M1 完成**：`deployment_mode` 三档落地（desktop 默认），webui mode-aware，
  FR-001 一键登录 + FR-002 数据目录，dogfood 三档 UI 验收通过
- **M2 完成**：AgentPack format（manifest + 安装 + 权限）+ 3 个内置科研 pack
  （reviewer / literature-mapper / grant-planner）+ citation-aware ingestion
  （PDF 页码 + Obsidian + `[Source N | file p.12]`）
- **下一步 = M0 的 3 个非软件项**（Apple Developer / Windows EV / 服务 pilot 客户）
  + **M2 收尾集成**（agentpack 接入 KB 管线带页码 + dogfood）
  + **服务生产线**（三类 SKU、QA checklist、COGS tracker、样例报告）
  + **M3**（macOS installer + 3-5 个结果型服务 pilot）

---

## 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 | 本文档 ✓ | ✅ 完成 |
| spike: `deployment_mode` flag 200 LOC 估算 | Claude | 88bdddb: 143 LOC + 11 test; 132 老 test 全绿 ✓ | ✅ 完成 |
| 申请 Apple Developer 账号 ($99/年) | Kenny | 收到 Apple ID 启用确认邮件 | 🔲 待办 (M0) |
| 启动 Windows EV 代码签名证书申请（需 ≥3 个月） | Kenny | DigiCert/Sectigo 申请单提交 | 🔲 待办 (M0) |
| 决定第一批服务 pilot 客户名单（3-5 位教授/博士/PI） | Kenny | 名单 + 真实论文/方向/基金材料 + 反馈承诺 | 🔲 待办 (M0) |
| 定义 3 个结果型 SKU 与报价 | Kenny | 论文预审 / 文献地图 / 基金打磨的交付物、SLA、价格假设 | 🔲 待办 (M0) |
| 建立服务 QA checklist + COGS tracker | Kenny | 预审报告 QA 表、人工分钟数/模型成本/返工原因表格 | 🔲 待办 (M0) |
| 准备 1 份样例服务报告 | Kenny | 可公开脱敏的 Top Journal Readiness Report 样例 | 🔲 待办 (M0) |

> **M0 备注**: 软件侧（spike）已完成并直接滚入 M1。当前阻塞不在代码，
> 而在账号/证书、人脉、服务 SKU、QA/SOP/COGS 这四类商业化准备。

---

## ✅ M1 完成 (2026-06-07, 至 2026-07-21 计划 → 提前完成)

**主题**: Desktop runtime + 单 mode 改造 — **全部交付，CI 全绿，dogfood 验收通过**

实测成本: CR rev.2 估算 ~200 LOC，实际生产代码约 480 LOC（含 FR-002 +
FR-001 + dogfood 修复），新增 24 个 test（132 → 156 root tests）。

### Phase B — Desktop runtime ✅ (88bdddb + 56eebc7)

- [x] `config.py` 加 `deployment_mode = desktop|lab|paas`（默认 desktop）+ 非法值 fail-fast
- [x] `setup.py` `auto_bootstrap_desktop()`：首启建 `tenant_id="tn_local_{hex}"`（Q11 匿名）+ `tenants.name="{hostname}/{user}"` alias + admin key 写 `~/.agentpaas/config.json`；幂等
- [x] `app.py` mode-aware 路由 gating：desktop 下 `/admin/*` `/billing/*` 强制 404（Q9 oracle 防御）
- [x] mode-transition smoke test（Q10）：desktop→lab→paas→desktop 四档全跑通 + tenant scope assert
- [x] Network bind 默认值：desktop/lab `127.0.0.1`、paas `0.0.0.0`（Q12），`AGENTPAAS_HOST` 可覆盖
- [x] data_dir mode 分流（FR-002）：desktop `~/LambdAgentDesktop`、lab/paas `~/.agentpaas/data`
- [x] `GET /setup/mode` 端点（Q8 webui 接口）

### Phase C — Webui Desktop 工作台改造 ✅ (ff61e59 + 9e933e4 + 891775f + 904c876)

- [x] 顶栏 mode chip（Q8）：🖥️ Desktop / 👥 Lab · {tenant} / ☁️ PaaS · {tenant}（teal/amber/indigo）
- [x] 文案重命名：Dashboard→今日工作、Knowledge→资料库、Providers→模型与隐私、Chat→研究任务工作台（desktop）
- [x] 首次启动向导 mode-aware brand（ResearchAgent Desktop）+ 数据目录展示（FR-002）+ Claude Code 推荐（Q4）
- [x] SR-002 隐私 modal：会发送/不会发送两列对照，desktop 首次强制弹窗（持久化 ack）
- [x] FR-001 一键登录：desktop + bootstrapped → `/setup/desktop-key` 自动取 key 跳 dashboard，教授双击即用

### dogfood 验收 (904c876) — 真实服务 + 浏览器走通三档

抓到并修复 2 个单元测试查不出的真 bug：
- **webui-dist 静态服务回归**（src-layout 迁移后 `../../webui-dist` 失效 → 整个 desktop app 不出 UI）→ `_resolve_webui_dist()` 多候选路径探测
- **FR-001 向导死路**（auto-bootstrap 写了 key 但向导让用户贴 key）→ `/setup/desktop-key` + 向导自动登录

### 已知小瑕疵（非阻塞，留 M2 打磨）

- 向导 step3 panel 内文案 "初始化平台" 未 mode-aware（pill 已是 "完成设置"；desktop 一键登录后看不到此步）
- Dashboard PageHeader "仪表盘" 未 mode-aware（sidebar 已是 "今日工作"）

### 验证的核心假设

✅ **CR rev.2 战略成立**：`319 处 tenant_id 引用` 完全没动，Q10 mode-transition smoke 全绿 — 多租户能力 100% 保留，desktop 只是默认隐藏。从 desktop 升 lab/paas = 改一行 `AGENTPAAS_DEPLOYMENT_MODE` + 重启。

---

## ✅ M2 完成 (2026-06-07, 至 2026-09-07 计划 → 大幅提前)

**主题**: AgentPack format + 3 个内置 pack + PDF 引用追踪 + Pack↔Agent 集成 + webui 管理页 + e2e dogfood — **软件全部交付，CI 全绿，189 test**

### Phase D — AgentPack format ✅ (c550f15)

- [x] `docs/AGENTPACK_SPEC.md`: manifest schema (id/name/version/domain/entrypoint/permissions/model) + 权限模型 + 安全 (zip-slip/yaml.safe_load)
- [x] kernel `lambdagent/agentpack.py`: AgentPackManifest + PackPermissions(SR-003 deny-by-default) + load_manifest（semver/id/entrypoint 校验 + escape 防御）
- [x] agentpaas 端点: `GET /agentpacks` `GET /{id}` `POST /install`(loopback) `DELETE /{id}`
- [x] `engine/agentpack_store.py`: 安全 unzip + 第三方 shell 拒绝(SR-003) + install/list/uninstall
- [x] config 加 `agentpacks_dir`；19 test
- 注：permission 运行时 tool-registry gating 是增量项（v0.1 校验+声明+install 拒绝；完整 gating 留后续）

### Phase F — 3 个内置 agent pack ✅ (0db8d9a)

- [x] `research.top-journal-reviewer` — 论文 → 审稿报告 + 中稿概率 + 修改清单
- [x] `research.literature-mapper` — 方向 + 本地论文 → 文献地图 + 方法谱系 + open problems
- [x] `research.grant-planner` — 方向 + 材料 → 立项依据 + 创新点 + 技术路线 + 风险
- [x] 设计决策：**独立 agent 而非 symlink 流水线 sub-agent**（physics67 reviewer 是读 {workspace}/02_sim/.. 的子节点，不能独立跑）。改造成 standalone 输入契约，local-first（无 shell/network），全部 from_config 编译通过
- [x] 4 test（bundled-pack regression guard）

### Phase E — citation-aware ingestion ✅ (0abbd47)

- [x] `lambdagent/ingest.py`: extract_pdf_pages（pdfplumber→PyPDF2 兜底）+ chunk_pages（页码保留，chunk 不跨页）+ CitedChunk
- [x] `import_obsidian_vault`（Q7）: walk .md + `[[wiki]]` alias 展开 + target 进 link graph
- [x] `rag.RAGTool` 引用格式: `[Source N | paper.pdf p.12]`（FR-005）
- [x] pdfplumber 加进 knowledge extra；9 test
- 集成边界：lambdagent 层 citation 原语已测；接进 agentpaas KB index 构建管线（pickle subprocess 子系统，audit #17）是后续集成步骤

### Phase G2 — Pack↔Agent 集成 ✅ (1299d22)

- [x] `POST /agentpacks/{id}/create-agent` — 从已安装 pack 一键创建 agent（agent_dir=pack.path, _config_dir=pack.path）
- [x] 2 test（E2E + 404 guard）

### Phase H — webui AgentPack 管理页 ✅ (e010efa)

- [x] `webui/src/api/agentpacks.ts` — API client（list/get/install/uninstall/create-agent）
- [x] `webui/src/pages/AgentPacks.tsx` — 安装/列表/卸载/创建智能体，安全提示 banner
- [x] App.tsx 路由 + Sidebar "智能体包"导航项（Package 图标）
- [x] tsc + vite build 全通过

### Phase I — AgentPack 端到端 dogfood ✅ (67beab7)

- [x] `tests/test_agentpack_e2e.py`：11 test（install→list→get→create-agent→GET agent→from_config 编译→uninstall pack 不级联删 agent）
- [x] `scripts/dogfood_agentpack.py`：手动 E2E 脚本（需运行 server + API key）
- [x] 全套 189 passed，1 skipped（LLM run，设计如此）

### 仍待做（M2 软件范围外的同期任务，需 Kenny / 真实用户）

- [ ] 服务 pilot 访谈（3-5 位），锁定真实论文 / 研究方向 / 基金材料
- [ ] 内部 dogfood: Kenny 用 ResearchAgent Service 完成一篇真实论文预审，交付 `Top Journal Readiness Report`
- [ ] 对 dogfood 记录 COGS: 模型成本、人工 QA 分钟数、总 cycle time、返工原因
- [ ] 形成 3 个服务 SKU 的 SOP:
  - `paper-readiness-review`
  - `literature-map`
  - `grant-polish`
- [ ] agentpack 接入 agentpaas KB index 管线（让 KBSearch 结果带页码）
- [ ] permission 运行时 tool-registry 完整 gating

---

## M3 (4 个月内 — 至 2026-10-07)

**主题**: macOS Beta 可下载 + 3-5 个结果型服务 pilot

### 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，提示用户

### 用户验证（Desktop 入口指标）

| 指标 | M3 目标 |
|---|---|
| 首次安装到完成第一个任务 | < 10 分钟 |
| PDF 导入成功率 | > 90% |
| 审稿报告生成成功率 | > 80% |
| 报告包含引用比例 | > 80% |
| 真实试用用户 | 10-20 人 |
| 一周后再次使用 | > 40% |

### 服务验证（AI-native service 指标）

| 指标 | M3 目标 |
|---|---|
| 结果型服务 pilot | 3-5 单 |
| 首批服务 SKU | 论文预审 / 文献地图 / 基金打磨 |
| 论文预审交付时长 | 24-48 小时 |
| 专家 QA 时间 | 30-60 分钟 / 单 |
| 每单 COGS 记录率 | 100% |
| 客户愿意付费/复购反馈 | 至少 2 个明确 yes |
| 返工原因记录 | 100% |

### Release 动作

- [ ] tag `v1.1.0-beta1`
- [ ] GitHub Release（prerelease）含 .dmg / .zip
- [ ] 写 `docs/USER_GUIDE.md` 面向非技术用户（教授友好语言）
- [ ] 写 `docs/SERVICE_SKU.md`：三类结果型服务、样例交付物、SLA、报价假设
- [ ] 写 `docs/SAMPLE_REPORTS/`：至少 1 份脱敏论文预审样例报告
- [ ] 官网/下载页增加 "提交服务 pilot" 入口，而不是只追求下载量

---

## Later (5-7 个月 — M4 + M5)

### M4 — Windows Beta（≈4-6 周）

- [ ] Windows EV 证书到位 → PyInstaller + signtool
- [ ] .msi / .exe 安装包，无 SmartScreen 警告
- [ ] Microsoft Store 评估（独立工作流）
- [ ] 与 macOS Beta 同步功能矩阵，跑同样的成功率指标

### M5 — Outcome Pricing + Retainer + Desktop Pro（≈3-4 周）

- [ ] 结果型服务报价验证
  - 论文预审: 499-1999 RMB / 篇
  - 文献地图: 1999-9999 RMB / 方向
  - 基金打磨: 3000-20000 RMB / 项
- [ ] 课题组 Retainer 报价验证
  - 每月 N 份论文预审 / 文献地图 / 基金打磨
  - 加急通道 + 专家 QA + Desktop 资料入口
  - 3000-20000 RMB / 月价格带访谈
- [ ] 每单 COGS dashboard
  - 模型成本
  - 专家 QA 分钟数
  - 交付/沟通分钟数
  - 返工率
  - gross margin
- [ ] Desktop Pro 作为辅助入口，而非收入上限
  - Free: 1 个 agent pack, 知识库 100 文件, Markdown 报告
  - Pro: 全部 agent pack, 无限制知识库, 批量审稿, PDF/DOCX 导出
- [ ] 首批 5-10 位付费客户跟踪（按服务单 / Retainer，而不是只按 Pro 订阅）

---

## Beyond (v1.2+)

不在 v1.x scope, 但已经在 CR 里 mark 为路径终点的：

- **Service Retainer → Lab** — `deployment_mode=lab` UI/营销已就绪；等 3-5 个课题组愿意持续购买结果型服务后，再把 Lab 版作为团队入口交付
- **Zotero 集成** — Q7 推迟到这里
- **医学场景重启** — Q5 推迟到这里，配合医院法务一起立项 ResearchAgent Medical
- **Agent Pack Registry 自建** — 等 AgentPack 在内部服务生产中稳定、且自助需求明确后再做
- **私有化部署 / paas mode 商业化** — 等 Lab/Retainer 有 ≥5 个课题组实际跑通后

---

## Roadmap 里没有的事情（不做清单）

明确不做（与 CR §4.3 + §5.4 一致）：

- 多租户云端 SaaS 公开发布（v2 之前不做）
- 医疗诊断 / 处方 / 治疗决策（永远不做，CR FR-013）
- App Store / Microsoft Store 首发（M5+ 看情况）
- 团队协作 + 组织级权限（v1.x 不做）
- Agent Pack marketplace 交易系统（v1.x 不做；AgentPack 先用于内部服务生产）
- 大规模下载量 / DAU 增长（v1.x 不追；服务 pilot 和付费意愿优先）
- 纯软件订阅作为主收入（Desktop Pro 是入口和辅助，不是商业化上限）
- 偏离三类 SKU 的定制外包（论文预审 / 文献地图 / 基金打磨之外的杂活不接）
- 面向普通大众的聊天助手（不做，定位偏离）
- 通用 Agent 编排 SDK 作为主产品（lambdagent 仍开源但不再是产品门面）

---

## Open risks（持续跟踪）

| 风险 | 概率 | 影响 | 缓解 |
|---|---|---|---|
| Apple Developer 账号审核 > 2 周 | 中 | M3 阻塞 | 立刻申请，准备备用账号 |
| Windows EV 证书 > 3 个月到货 | 高 | M4 阻塞但不阻塞 M3 | 提前 M0 当天申请 |
| PDF 引用追踪准确率 < 80% | 中 | M3 验收指标失守 | Phase E 期间用 5 篇 SOTA 论文跑 ground truth |
| 服务 pilot 客户找不齐 3-5 位 | 中 | M3 服务验证不足 | M0 期间通过个人网络锁定，并要求真实材料 + 反馈承诺 |
| 服务质量方差过高 | 中 | 客户不信任，无法复购 | 每单专家 QA + QA checklist + 返工原因记录，回灌 AgentPack |
| COGS 过高 / 毛利不成立 | 中 | AI-native service 经济模型失败 | 每单记录模型成本、专家分钟数、交付分钟数；优先优化高频 SKU |
| 专家 QA 供给不足 | 中 | throughput 上不去 | 从兼职领域顾问开始，目标让专家只复核关键判断而非从零写报告 |
| `deployment_mode` flag 改动 break 现有 189 test | 低 | M1/M2 回归 | mode-transition smoke + 全套测试持续跑 |
| 医学场景外部压力（用户主动要） | 中 | 偏离 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 完成后自动复用，**不需要重新修**。

**Service-first + Desktop 优先级 + 多租户保留** 这条战略选择，让 audit 修过的工作成为 lab/paas 升级时的 free win；同时把 v1.x 的商业验证从 "卖软件" 调整为 "卖可追溯科研结果"。

---

最后更新: 2026-06-07
本 roadmap 与 [`docs/requirements-change-personal-desktop.md`](docs/requirements-change-personal-desktop.md) 和 `01-Research/Agent/LambdAgent Desktop 商业计划书.md` 同步。需求决策记录见 CR §十三；商业叙事以 AI-native research service company 为准。