Imported from anklecrusher/medical-product-research-agent (
AGENTS.md). Install upstream withnpx skills add anklecrusher/medical-product-research-agent. Copyright stays with the author.
AGENTS.md
1. 文件定位
本文件是本仓库的全局开发指导文件，供所有后续开发线程、协作者和自动化 agent 阅读。
它的作用不是记录某一个阶段的任务清单，而是统一整个项目从原型、MVP、产品化到后续维护过程中的架构原则、协作规则、参考项目使用边界、隐私要求和质量标准。
所有新线程开始工作前，都应先阅读：
AGENTS.md医疗产品调研Agent开发周期计划表.mdLOG.md最新记录- 与当前任务相关的代码、模板和文档
2. 项目使命
本项目要构建一个面向医疗产品经理的本地优先调研系统。
系统应支持用户输入一句调研需求，自动完成以下工作：
- 拆解调研问题。
- 检索论文、厂商资料、监管资料和市场资料。
- 解析网页、PDF、手册和用户上传文档。
- 抽取结构化证据和产品参数。
- 识别来源冲突和缺失证据。
- 生成结构清晰、来源可追溯的 Markdown 调研报告。
- 导出适合分享和归档的 PDF。
目标不是做医疗诊断系统，也不是替代专业医学判断，而是为医疗产品调研、竞品分析、参数梳理和选题研究提供高质量草稿。
3. 目标用户与报告风格
目标用户：
- 医疗产品经理
- 医疗器械研发相关人员
- 调研、战略、市场或注册相关人员
报告风格参考仓库中的现有草稿：
DBS脑电采集电极要求调研_加强版.mdSCS刺激参数调研.md
报告应偏向产品调研和工程理解，而不是泛泛的科普综述。
优先输出：
- 关键结论
- 参数表
- 竞品/厂商对照表
- 论文证据表
- 监管/产品资料补充
- 工程或产品解释
- 风险、边界和未确认项
- 参考文献与直达链接
4. 总体架构原则
本项目采用 workflow 优先架构，不采用完全自由发挥的自治聊天 agent。
核心原则：
- 流程可控：每一步都应有明确输入、输出和状态。
- 证据可追溯：关键结论必须能回到来源。
- 中间结果可保存：来源、证据、报告草稿和核查结果都应可落盘。
- 失败可恢复：长任务失败时，应尽量支持从中间步骤继续。
- 私有资料本地优先：用户上传资料默认不发送外部 API。
- 报告模板可演进：模板应尽量外置，避免每次调整报告风格都改核心流程。
主流程：
用户需求
-> 意图解析
-> 调研规划
-> 多源检索
-> 来源抓取与解析
-> 证据抽取
-> 证据去重与冲突检查
-> 报告大纲
-> 章节写作
-> 引用与结论核查
-> Markdown 报告
-> PDF 渲染
-> 任务归档与版本记录5. 推荐技术方向
全流程推荐技术方向如下。具体实现可以随阶段调整，但变更应记录在 LOG.md 或相关设计文档中。
| 层级 | 推荐技术 | 作用 |
|---|---|---|
| 主语言 | Python | 核心 workflow、检索、解析、报告生成 |
| 编排 | LangGraph | 状态机式 agent/workflow 编排 |
| 数据约束 | Pydantic | 定义任务、来源、证据、参数、报告结构 |
| LLM 调用 | OpenAI SDK 或兼容 API | 意图解析、证据抽取、报告写作、核查 |
| 检索与抓取 | httpx、公开 API、网页解析工具 | 获取论文、厂商、监管和市场资料 |
| 文档解析 | PyMuPDF、pypdf、trafilatura、BeautifulSoup | 解析 PDF、网页和正文 |
| 存储 | SQLite 起步，后续可换 PostgreSQL | 保存任务、来源、证据、报告和日志 |
| 本地检索 | LlamaIndex / Chroma / Qdrant 可选 | 检索用户上传资料和本地知识库 |
| 报告模板 | Markdown + Jinja2 | 生成结构稳定的报告 |
| PDF 渲染 | Playwright Chromium 或 WeasyPrint | 将报告渲染为 PDF |
| 后端 | FastAPI | 提供任务、上传、状态、下载接口 |
| 前端 | 简单 HTML 起步，后续 React/Vite | 从本地工具升级到产品化工作台 |
6. 模块边界
开发时应尽量保持模块职责清晰。
| 模块 | 职责 | 不应承担 |
|---|---|---|
| Workflow 编排 | 决定节点顺序、状态流转、重试和人工介入 | 不直接写业务 prompt 或解析网页 |
| Connector | 连接外部数据源，返回统一来源结构 | 不写报告，不做复杂结论判断 |
| Parser | 抽取网页/PDF/文档正文和元数据 | 不生成最终观点 |
| Evidence Extractor | 从解析文本中抽取结构化证据 | 不拼装最终报告 |
| Evidence Store | 保存任务、来源、证据、报告版本 | 不承载业务逻辑 |
| Report Planner | 根据需求和证据规划报告结构 | 不虚构证据 |
| Section Writer | 基于证据写章节 | 不引入无来源强结论 |
| Claim Verifier | 检查结论和参数是否有证据支撑 | 不负责美化语言 |
| Renderer | 生成 Markdown、HTML、PDF | 不改变事实内容 |
| Web/API | 提供交互、上传、状态和下载 | 不绕过 workflow 直接生成报告 |
7. 数据与中间产物规范
系统应优先通过结构化数据传递信息，而不是在模块之间传递大段自由文本。
建议长期保留的中间产物：
sources.json：本次任务检索到的来源。documents.json：已抓取和解析的文档元数据。evidence.json：抽取出的结构化证据。claims.json：报告中的关键结论及其核查状态。report.md：最终 Markdown 报告。report.pdf：最终 PDF 报告。run.log：任务执行日志。
典型结构对象应包括：
ResearchTaskSourceRecordParsedDocumentEvidenceItemProductSpecClinicalFindingRegulatoryFindingClaimReportSectionReportArtifact
8. 必须参考的 GitHub 项目
以下项目是本项目的重要设计参考。新线程在开发相关模块时，应主动查看这些项目的思路，但不得无评估地整体照搬。
| 参考项目 | 何时参考 | 重点学习内容 |
|---|---|---|
Future-House/paper-qa |
做论文问答、文献证据、引用溯源、论文 chunk、citation 逻辑时 | 科学文献如何检索、切分、引用，并基于证据回答问题 |
assafelovic/gpt-researcher |
做调研规划、多源搜索、网页资料汇总和调研草稿生成时 | 如何把一句调研问题拆成搜索任务，收集来源并汇总研究输出 |
stanford-oval/storm |
做长报告大纲、章节规划和长文组织时 | 如何先规划报告结构，再分章节生成长报告 |
参考边界：
paper-qa主要影响文献证据和引用机制。gpt-researcher主要影响深度调研流程和搜索规划。STORM主要影响长报告组织与章节规划。- 这些项目默认只是设计参考，不是硬依赖。
- 如需引入其中任何项目或其核心库作为依赖，必须先记录评估理由、收益、风险和替代方案。
9. 隐私与数据安全规则
本项目应按本地优先思路设计。
来源类型必须明确标记：
public_literature：公开论文public_web：公开网页public_regulatory：公开监管资料vendor_public_doc：厂商公开文档user_uploaded_private：用户上传的私有资料internal_private：内部私有资料
默认策略：
- 公开来源可以发送给外部 LLM API。
- 用户上传的私有资料默认只在本地处理。
- 内部私有资料默认不得发送外部 API。
- 如果未来允许外部处理私有内容，必须显式配置、记录日志，并能被用户关闭。
以下内容不得提交到 git：
.env- API key
data/outputs/cache/uploads/- 本地数据库文件
- 用户上传的私有文档
10. 报告质量标准
报告生成必须优先保证可核查，而不是追求语言华丽。
质量要求：
- 关键结论必须有来源。
- 参数表中的数值必须能回溯来源。
- 不同来源冲突时，应标记冲突，而不是强行合并。
- 缺少证据时，应标记
needs_review或“未确认”。 - 公开论文、厂商资料、监管资料和本地资料应区分展示。
- 不能把厂商宣传材料当作临床结论。
- 不能把单篇论文结论写成行业共识。
- 中文表达要清晰，单位要规范。
常用单位应统一处理：
- Hz
- us 或 μs
- mA
- V
- ohm 或 Ω
- uC/cm2 或 μC/cm²
- mm
- cm
11. 多线程协作规则
本项目可能由多个开发线程并行推进。为了避免上下文污染和重复决策，所有线程必须遵守以下规则。
开始前：
- 先读
AGENTS.md。 - 再读开发周期计划表。
- 再读
LOG.md最新记录。 - 再查看当前相关文件。
开发中：
- 只修改当前任务必要文件。
- 不顺手重构无关模块。
- 不删除其他线程可能正在使用的约定或文档。
- 如果发现计划与现实冲突，应更新文档，而不是只改代码。
完成后：
- 在
LOG.md追加记录。 - 写清楚修改文件、改动摘要、关键决定和后续事项。
- 如果变更影响架构、schema、workflow、存储、报告格式、隐私策略或依赖管理，必须额外说明。
12. 变更记录要求
LOG.md 是跨线程共享记忆，不是详细 commit history。
以下情况必须更新 LOG.md：
- 新增或重构核心模块。
- 修改 workflow 节点或状态。
- 修改 schema。
- 修改报告模板或引用格式。
- 新增外部数据源 connector。
- 修改隐私策略。
- 修改安装、启动或更新方式。
- 做出重要技术取舍。
记录应简洁，但必须足够让新线程理解“发生了什么”和“为什么这样做”。
13. 依赖与交付原则
依赖原则：
- 优先选择稳定、维护活跃、Python 生态成熟的库。
- 不为小功能引入重依赖。
- 能用标准库或轻量依赖解决的问题，不引入复杂框架。
- 新增依赖要说明用途。
交付原则：
- 本地运行应尽量简单。
- 用户数据和输出文件应与代码分离。
- 配置应通过
.env或配置文件管理。 - 更新流程应考虑
git pull后的依赖同步和数据库迁移。 - 生成文件、缓存和私有数据必须被
.gitignore排除。
Git 使用约定：
- 本机普通
gitwrapper 可能出现error launching git。 - 历史可用路径为
D:\Users\gongjx\AppData\Local\Programs\Git\mingw64\bin\git.exe；在当前机器上该路径不可用。 - 当前机器涉及 git 操作时，直接使用已验证可工作的完整路径：
C:\Users\ankle crusher\scoop\apps\git\current\cmd\git.exe。 - 不要先尝试普通
git命令再在报错后切换；应一开始就使用上述完整路径，避免重复排查。 - GitHub CLI 已安装在：
C:\Users\gongjx\tools\gh\bin\gh.exe。
14. 维护与演进原则
项目后续会持续演进，因此设计时应考虑：
- 数据源接口可能变化。
- LLM API 和模型名称可能变化。
- 报告模板可能多版本并存。
- 本地数据库可能需要迁移。
- 用户可能需要清理缓存、备份报告、迁移数据。
- 前端可能从简单页面升级到完整工作台。
任何实现都应避免把这些变化写死在单一脚本中。
推荐长期保留：
- 版本号
- 变更日志
- 数据库迁移脚本
- 模板版本
- connector 测试样例
- 示例任务
- 一键启动脚本
- 一键更新脚本
15. 总体判断
本项目的核心竞争力不在于“有很多 agent 角色”，而在于：
- 调研流程稳定。
- 证据结构清楚。
- 参数抽取可靠。
- 报告风格贴近医疗产品经理需求。
- 引用和结论可追溯。
- 本地资料隐私边界清晰。
所有后续开发都应围绕这些目标取舍。