Xiuyiw/CFD-SCIPaper-Agent · 上手攻略
- 仓库：Xiuyiw/CFD-SCIPaper-Agent
- 链接：https://github.com/Xiuyiw/CFD-SCIPaper-Agent
- 分类：academic-writing · research-workflow · CFD
- 作者：Tom
- 更新：2026-08-31
是什么
CFD-SCIPaper-Agent 是一个作者参与式 CLI 工具，帮助流体力学（CFD）研究者把已有的结构化计算结果转化为有证据支撑的研究选题方向。它 v0.2.0（2026-08-31 刚发布）支持从成熟结构化记录中自动生成 2–4 个有证据边界的候选研究方向，并提供可追溯的证明链。
⚠️ 重要澄清：它不是一个 CFD 求解器，也不运行任何仿真。它是一个选题规划与证据管理的外层工作流工具——研究者必须先有成熟的 case/boundary/convergence/conservation/QoI 记录，通过 Python 合同注入，它才能在证据边界内生成候选。
核心哲学：缺失证据是一个合法结果，而不是被隐藏的成功。工具永远在证据边界内工作，不会凭空发明数据，也不会替作者批准选题。
解决什么问题
CFD 研究者常见痛点：
- 仿真结果散落：大量 CSV/日志/导出文件没有被系统化管理，
inspect可以建立本地索引并追踪文件新鲜度。 - 选题缺乏证据链：论文审稿人经常质疑"你怎么知道这个方向值得做"——
plan命令输出的 ranking 报告自带证据出处和缺失数据清单。 - 人工整理候选工作量大：从几十个案例中归纳有潜力方向费时费力，工具可从结构化记录中自动发现 matched-comparison、ordered-response、coupled-association 三类研究机会。
- 离线工作需求：没有 API Key、没有网络时，
--provider offline仍是确定性工作流，所有数据留在本地 SQLite。
快速安装
环境要求：Python 3.10–3.12，Windows / Linux 均有 CI 验证。
# 方式一：从源码安装（推荐）
git clone https://github.com/Xiuyiw/CFD-SCIPaper-Agent.git
cd CFD-SCIPaper-Agent
python -m pip install -e .
# 验证安装
cfdpaper --help
⚠️ 不需要 API Key，离线模式开箱即用。可选 provider 集成（如 LLM 润色措辞）在无可用 provider 时自动 fallback 到离线模式。
核心用法
完整 quickstart（五步）
# 1. 复制示例目录到可写位置
cp -r examples/quickstart /tmp/my-cfd-project
cd /tmp/my-cfd-project
# 2. 初始化项目（创建本地 SQLite 数据库和 .cfdpaper/ 目录）
cfdpaper init project --project-id synthetic-duct-study
# 3. 索引项目文件（建立本地源索引，追踪新鲜度）
cfdpaper inspect project
# 4. 规划研究方向（使用作者提供的候选 JSON)
cfdpaper plan project --candidates candidates.json
# 5. 查看项目状态（含 checkpoint 信息）
cfdpaper status project
预期输出示例：
Plan complete: outcome=missing-evidence; leading=pressure-loss-screening; gaps=4; approval=none
⚠️ 这个 missing-evidence 结果是有意设计的成功演示，不代表工具失败——它正确识别了证据缺口。真实场景下有完整结构化记录时，outcome 会不同。
自动生成候选（需结构化记录已就绪）
# 在有完整 case/boundary/QoI/convergence/conservation/provenance 记录时
cfdpaper plan PROJECT_ROOT
# 强制重新生成（跳过 reuse）
cfdpaper plan PROJECT_ROOT --regenerate
# 指定离线模式（确定性，无需网络）
cfdpaper plan PROJECT_ROOT --provider offline
审批选题（v0.2.0 仅为记录，不触发后续分析）
# ⚠️ --approve-topic 记录作者选择方向及证据范围
# 但不执行 analyze/figure/write/review/revise/export
cfdpaper plan PROJECT_ROOT --author "Dr. Smith" --approve-topic
典型适用场景
| 场景 | 适用性 |
|---|---|
| CFD 硕博士论文开题：梳理现有算例找研究空白 | ✅ 强——工具帮你结构化呈现证据缺口 |
| 工业 CFD 项目结题：整理大量仿真报告形成技术论文 | ✅ 可用——index + status 管理项目状态 |
| 基金申请书：证明"研究问题有证据支撑" | ✅ 规划报告自带可追溯证据链 |
| 想用 LLM 辅助写 CFD 论文 | ⚠️ analyze/figure/write 仍为 roadmap placeholder（v0.2.0 不支持） |
| 直接生成论文全文 | ❌ 不支持——在 roadmap 上，开发已暂停到 v0.3.0 |
坑与注意
1. inspect 不生成证据记录
inspect 只建立文件索引和新鲜度追踪，不会自动把 CSV/日志文件变成证据记录。v0.2.0 没有通用 CLI 把任意文件提升为科学证据——必须通过 Python 合同或 adapter 手动注入结构化记录。这是有意设计的边界。
2. 缺失证据 ≠ 失败
outcome=missing-evidence 是工具的合法输出，不是 bug。如果研究者强行在没有完整证据的情况下推进选题，--approve-topic 也不会绕过科学门控。工具的诚实设计意味着它会如实报告 gap 数量。
3. v0.2.0 开发已暂停
文档明确写明"Development pauses after v0.2.0. No v0.3.0 work is active without explicit author authorization."——不要再等新功能，如果需要 analyze/figure/write 等功能，当前无法满足，请评估其他工具。
4. JSON artifact 不是稳定交换格式
.cfdpaper/outputs/plan/topic-ranking.json 是项目本地持久化格式，不保证跨版本兼容性。v0.1.0 项目数据库可以原地迁移到 v0.2.0，但未来 v0.3.0 不一定兼容这些 artifact。
5. 不支持 Fluent / STAR-CCM+ 原生导出
可选 adapter 是 extension point，v0.2.0 仅提供"small synthetic or neutral exported files"的演示，不支持真实求解器导出。工业用户需要自行实现 adapter。
6. 不要提交敏感文件
README 明确警告：不要 commit 机密求解案例、未发表稿件、公司数据、凭证或授权文件。文件存在 ≠ 等于验证，研究者仍需对 comparability、convergence、conservation、单位、QoI 定义和 claim 范围负责。
与同类对比
| 工具 | 定位 | 离线 | 证据边界 | CFD 特化 | 分析/写作 |
|---|---|---|---|---|---|
| CFD-SCIPaper-Agent | 作者参与式选题规划 | ✅ | ✅ 结构化 | ✅ 强 | ❌ Roadmap |
| Foam-Agent (arXiv:2505.04997) | CFD 工作流自动化（基于 MCP） | 部分 | ❌ | ✅ 强 | 部分 |
| Gatsbi | 综合学术研究平台 | ❌ | ❌ | ❌ | ✅ 完整 |
| AutoGen + 学术 Agent | 通用多 Agent 写稿 | ❌ | ❌ | ❌ | ✅ |
| Zotero MCP / paper-memory-builder | 文献管理与证据追踪 | ✅ | 部分 | ❌ | 有限 |
核心差异：CFD-SCIPaper-Agent 是唯一一个把证据边界检查做进核心工作流的 CFD + 学术选题工具。Foam-Agent 侧重 CFD 求解自动化，CFD-SCIPaper-Agent 侧重研究选题的证据链管理。通用学术写作 Agent（如 Gatsbi）功能全但缺乏领域特异性。
一句话推荐结论
如果你是一个有成熟 CFD 仿真数据的科研工作者，想把散落的算例系统化地转化为有证据支撑的研究选题，CFD-SCIPaper-Agent v0.2.0 是目前最专门的离线选题规划工具——但请在有完整结构化记录之后再用，不要期待它帮你写论文（那些功能在 roadmap 上且开发已暂停）。