PRD: 通用能力增强 + 科研场景

[suntianc]

Problem Statement

CDF 已完成通用 Agent 工作站能力，但所有用户面对的是同一套界面和工具集。不同领域（科研、开发、设计等）的用户有截然不同的工作流和工具需求，通用界面无法提供领域深度。科研用户需要搜论文、管理文献、复现实验、撰写学术文档、处理 AI 检测问题和绘制科研图表，这些需求目前没有被 CDF 覆盖。

同时，CDF 缺少若干通用基础能力——无头浏览器爬取、本地知识管理、PDF 解析、本地向量化、文生图——这些能力不仅科研场景需要，未来其他垂直场景也会依赖。

Solution

分两层解决：

1. P0 通用能力增强：新增 6 项通用基础设施模块，所有场景可复用。
2. P1-P3 科研场景：引入 Scene（场景）概念，科研场景作为第一个垂直领域落地。用户创建 Project 时选择 Scene，科研 Scene 提供专属侧边栏面板（论文库、写作项目、实验记录）和 5+1 个预设 Agent。

Agent 对话仍为主交互方式，侧边栏替换为科研专用面板。通用 Agent 能力始终可用，科研能力叠加。主 Agent 通过 LLM 智能路由调度 5 个专业子 Agent，复用现有 delegated task 框架。

User Stories

Scene 机制

1. As a user, I want to choose a Scene (e.g. "Research") when creating a new Project, so that the workstation is pre-configured for my domain.
2. As a user, I want the sidebar layout to change based on the Project's Scene, so that I see domain-relevant panels instead of generic ones.
3. As a user, I want my general-purpose Agent capabilities (bash, file, search) to remain available in any Scene, so that I don't lose core functionality.
4. As a user, I want pre-configured domain Agents to appear automatically when I enter a Scene-enabled Project, so that I can start domain work immediately.

论文检索 Agent

5. As a researcher, I want to search for papers across Google Scholar, arXiv, and Semantic Scholar in one query, so that I get comprehensive results without switching tools.
6. As a researcher, I want the Agent to automatically download found papers' PDFs to my Paper Library, so that I can read them offline.
7. As a researcher, I want to use the Obscura headless browser to crawl academic sources that require JS rendering, so that I can access papers behind dynamic pages.
8. As a researcher, I want search results to be stored as OKF metadata files in my Paper Library, so that they are structured and agent-readable.

论文库面板

9. As a researcher, I want to browse all collected papers in the Paper Library panel, so that I can see my research corpus at a glance.
10. As a researcher, I want to tag and organize papers into groups, so that I can manage literature for different topics or projects.
11. As a researcher, I want to see a paper's title, authors, abstract, source, and tags in the panel, so that I can quickly assess relevance.
12. As a researcher, I want to open a paper's PDF from the panel, so that I can read the full text.
13. As a researcher, I want the Agent to be able to search and retrieve content from my Paper Library via vector search, so that it can reference specific papers when helping me write.

论文审查 Agent

14. As a researcher, I want a "quick summary" mode that extracts a paper's core contribution, methods, and limitations, so that I can screen papers fast.
15. As a researcher, I want a "deep review" mode that evaluates novelty, methodology rigor, experimental sufficiency, writing quality, and related work coverage, so that I get a peer-review-level assessment.
16. As a researcher, I want the review Agent to reference specific sections and quotes from the paper, so that its assessment is grounded and verifiable.

学术写作 Agent

17. As a researcher, I want the Agent to help me write a literature survey by synthesizing papers from my Paper Library, so that I can produce a structured review.
18. As a researcher, I want the Agent to help me draft sections of a research paper (intro, methods, results, discussion), so that I can accelerate the writing process.
19. As a researcher, I want the Agent to automatically generate a bibliography from papers I cite in the Paper Library, so that I don't have to manually format references.
20. As a researcher, I want citation management that inserts in-text citations and maintains a reference list, so that my academic document is properly cited.
21. As a researcher, I want to manage the outline of my writing project in the Writing Project panel, so that I can see and reorganize the document structure.

降 AI 味 Agent

22. As a researcher, I want to select a full document and have the Agent rewrite it to reduce AI-detectable patterns, so that the writing reads as human-authored.
23. As a researcher, I want to select individual paragraphs for rewriting, so that I have fine-grained control over which parts are modified.
24. As a researcher, I want the Agent to preserve the academic tone and factual accuracy during rewriting, so that the content remains scholarly.

实验助手 Agent

25. As a researcher, I want the Agent to help me clone a paper's source code repository and set up the environment, so that I can start reproducing results faster.
26. As a researcher, I want an integrated terminal within CDF for running experiments, so that I don't need to switch to an external terminal.
27. As a researcher, I want the Experiment Record panel to track my reproduction attempts with input parameters and output results, so that I can compare runs.
28. As a researcher, I want the Agent to generate data visualization charts (line, bar, scatter, heatmap), so that I can create publication-ready figures.
29. As a researcher, I want the Agent to generate architecture diagrams and flowcharts, so that I can illustrate my methods visually.
30. As a researcher, I want the Agent to generate specialized scientific diagrams (molecular structures, neural network topologies, etc.), so that I can include domain-specific figures.
31. As a researcher, I want the Agent to call text-to-image APIs (GPT-Image, Nano Banana, MiniMax) for generating conceptual illustrations, so that I can create visuals from text descriptions.

主 Agent 调度

32. As a researcher, I want to talk to a single main Agent that automatically routes my requests to the right specialist Agent, so that I don't have to manually pick which Agent to use.
33. As a researcher, I want to @ a specific Agent by name to bypass the main Agent's routing, so that I can directly invoke a specialist when I know what I need.

P0 通用能力

34. As a user, I want Obscura headless browser bundled with CDF, so that any Agent can crawl pages that require JS rendering without external setup.
35. As a user, I want a Crawler Skill that encodes crawling strategies for the Obscura tool, so that Agents know how to effectively crawl different types of sites.
36. As a user, I want an OKF-based local knowledge base, so that structured knowledge is stored as Markdown + YAML and is both human-browsable and agent-readable.
37. As a user, I want PDF parsing that produces a Structured Paper Parse from PDFs (including academic papers with dual columns, formulas, and tables), so that Agents can read, reference, retrieve, and chunk PDF content with source locations.
38. As a user, I want a local embedding pipeline that downloads models on demand and falls back to cloud APIs when configured, so that vector search works offline and improves online.
39. As a user, I want a text-to-image module with its own settings page for configuring API keys (GPT-Image, Nano Banana, MiniMax), so that image generation is managed separately from LLM providers.
40. As a user, I want a test interface in the text-to-image settings to verify my API configuration works, so that I can troubleshoot before using it in a workflow.

Implementation Decisions

Scene 机制

• Project 数据模型新增 scene 字段（如 "general" | "research"），创建时指定，不可更改。
• Scene 决定侧边栏面板集合和预设 Agent 列表。渲染进程根据 Project 的 scene 字段动态加载对应的侧边栏面板组件。
• 通用 Agent 能力（bash-tool、file-tools、fetch-tool、search-tools 等）在所有 Scene 中始终可用，Scene 专属能力叠加注入。

论文库 + OKF

• 每篇论文对应一个 OKF Markdown 文件（YAML frontmatter 存标题、作者、摘要、来源、标签），正文区存用户笔记和 Agent 摘要。
• PDF 原文存储在项目本地文件系统，OKF 文件中通过相对路径引用。
• 向量索引基于 SQLite 存储（保持离线优先），embedding 来源为本地模型（按需下载）或用户已配置的云端 embedding API，自动选择最优。

PDF 解析

• 方案待定：Marker（Python，输出 Markdown）vs LLM 多模态解析，需实验验证后选定。
• 纯文本提取方案（pdf.js / pdf-parse）已排除。
• 无论最终选择哪个方案，对外暴露统一接口：输入 PDF 文件路径，输出 StructuredPaperParse，包含 Markdown、block-level 内容，以及至少页码 + 章节/标题级别的 Paper Source Location。
• 若 Marker 与多模态 LLM 都达到可用质量，默认优先选择离线可用、成本可控的 Marker；多模态 LLM 默认作为失败兜底或用户触发的高成本增强路径，除非 Spike 证明它应成为默认生产方案。

写作编辑器

• 选型延后。开发时先调研科研写作的实际工作流（用户普遍先用 Word 再转 PDF），再决定内置编辑器类型或是否只做文件管理+Agent 生成。

文生图模块

• 独立于 LLM provider 配置，在设置页面单独新增「文生图模型」配置区。
• 统一接口：输入 prompt + 参数（尺寸、风格等），输出图片文件路径。首批对接 GPT-Image、Nano Banana、MiniMax。
• 提供基础测试界面供用户验证 API 配置。
• 作为模块能力暴露给所有 Agent，不限于科研场景。

Obscura + 爬虫 Skill

• Obscura 无头浏览器 bundle 进安装包（~30MB），作为底层 tool 暴露给所有 Agent。
• 爬虫能力实现为 Crawler Skill（prompt + 策略层），引用 Obscura tool 作为执行引擎。开发前先调研开源爬虫 Skill 方案作为经验参考。
• 简单 HTTP 请求仍走现有 fetch-tool，需要 JS 渲染/登录态/反爬绕过时走 Obscura。

Agent 架构

• 5 个专业 Agent + 1 个主 Agent，共 6 个。
  • 论文检索 Agent：搜论文 + 下载入库
  • 论文审查 Agent：快速总结 + 深度审稿
  • 学术写作 Agent：写综述 + 写论文 + 引用管理
  • 降 AI 味 Agent：全文/段落改写
  • 实验助手 Agent：实验复现 + 科研图绘制
• 主 Agent 通过 LLM 路由（system prompt 描述子 Agent 职责）调度，复用现有 delegated task + parallel-task-tool 框架，不需要新建调度基础设施。
• 用户可通过 @ 指定子 Agent 直接对话，跳过主 Agent 路由。

学术搜索数据源

• Google Scholar（通过 Obscura 爬取）、arXiv API（现有 arxiv-tool 扩展）、Semantic Scholar API。
• 知网 / 万方已排除（反爬和版权风险）。

引用管理

• 学术写作 Agent 从 Paper Library 中提取被引论文元数据，自动生成参考文献列表。
• 支持常见引用格式（APA、IEEE、GB/T 7714 等）。

Testing Decisions

什么是好的测试

• 测试外部行为而非内部实现细节。
• 对于 Agent tool：验证输入输出契约（给定输入，返回预期格式的输出），mock 外部依赖（网络、文件系统）。
• 对于 Renderer 组件：验证用户可见行为（面板渲染、交互响应），不绑定 DOM 内部结构。

测试接缝（4 个）

1. Agent Tool 层（现有接缝）：src/main/deepagent/*-tool.ts + *.test.ts。覆盖 Obscura tool、PDF 解析模块、embedding 管线、文生图模块。先例：arxiv-tool.test.ts、bash-tool.test.ts。
2. Skill Manager 层（现有接缝）：src/main/deepagent/skill-manager.ts + *.test.ts。覆盖 Crawler Skill 的注册和加载。
3. Agent 配置层（现有接缝）：src/main/deepagent/agent-tools.ts + *.test.ts。覆盖 5 个科研预设 Agent 的创建、system prompt 注入、tool 绑定。
4. Scene 选择机制（新接缝）：项目管理层，覆盖创建 Project 时选择 Scene → 触发预设 Agent 和面板初始化。放在现有项目 CRUD 逻辑旁边。

Out of Scope

• 知网 / 万方数据源集成
• 多人协作功能
• 论文投稿辅助（选刊推荐、格式适配）
• AI 文本检测能力（用户自行使用第三方检测工具）
• 写作编辑器的具体选型（延后到开发阶段调研）
• PDF 解析方案的最终选定（需实验验证）

Further Notes

• 交付顺序为 P0 → P1 → P2 → P3，P0 的 6 项通用能力是后续科研场景的前置依赖。
• 当前有代码重构任务在并行进行，科研场景实际开发在重构完成后启动。
• Scene 机制设计为可扩展——科研是第一个场景，后续可新增其他垂直领域场景，复用同一套 Scene 基础设施。
• 实验复现从中量级（集成终端 + 环境管理）起步，逐步迭代到更高自动化程度。