PaperOrchestra 通过 CLI 的 --raw_materials_dir 参数读取研究材料,默认依赖该目录下的 idea_sparse.md 和 experimental_log.md 两个 Markdown 文件。准备材料的正确方式是创建指定目录并填入符合框架解析规范的假设与日志内容,随后通过显式传递文件名参数或保持默认命名来启动生成流程。
创建研究材料存储目录
paperorchestra 要求把原始研究数据存放在独立目录里,方便后续管理和校验,推荐直接创建一个名为 my_materials 的文件夹作为原材料根目录。在当前工作终端执行以下命令,就能完成目录初始化:
mkdir -p my_materials
这一步只会创建空文件夹,还没填充任何内容,之后所有研究假设和实验记录都要存在这个路径下。要保证当前终端用户对该目录拥有读写权限,否则后续调用 CLI 时很容易因为权限不足弹出 Permission denied 报错。
编写研究假设文件 (idea_sparse.md)
研究假设文件是整个框架的核心驱动,默认情况下 CLI 会自动查找名为 idea_sparse.md 的文件。这个文件直接用 Markdown 格式编写就行,清晰写清楚问题陈述、核心假设、方法论概要及预期贡献。下面是基于 TSAM 案例构建的模板结构,你根据自己的实际研究内容替换掉占位符即可:
cat > my_materials/idea_sparse.md << 'EOF' ## Problem Statement [在此处详细描述研究背景及现有技术的局限性] ## Core Hypothesis [在此处阐述你的核心科学假设或技术猜想] ## Proposed Methodology (High-Level Technical Approach) 1. [方法组件一] 2. [方法组件二] ## Expected Contribution - [预期贡献点一] - [预期贡献点二] EOF
写入完成后,执行 cat my_materials/idea_sparse.md 检查文件内容是否完整。如果文件为空,CLI 运行时提取不到关键语义信息,要么生成流程直接失败,要么输出一堆无意义的占位文本。注意官方示例里的具体技术细节比如 SAM 模型架构仅作参考,不要直接复制,一定要填入你自己的研究逻辑。
编写实验日志文件 (experimental_log.md)
实验日志文件用来支撑论文里的数据分析和消融实验部分,默认文件名为 experimental_log.md。内容要包含实验设置、原始数值数据表以及定性观察结果,哪怕实验还没完全结束,也可以先把结构搭好,填入待补字段:
cat > my_materials/experimental_log.md << 'EOF' ## 1. Experimental Setup * **Datasets:** [数据集名称及规模] * **Metrics:** [评估指标定义] * **Baselines:** [对比基线模型列表] * **Implementation Details:** [硬件环境、优化器、超参数等] ## 2. Raw Numeric Data **Table 1: Performance Comparison** | Method | Metric A | Metric B | | :--- | :--- | :--- | | Baseline_1 | [待填] | [待填] | | Ours | [待填] | [待填] | ## 3. Qualitative Observations [在此处记录初步的观察结论、异常值分析或可视化效果描述] EOF
材料目录不存在时,CLI 会先报目录错误。单个 Markdown 文件缺失则在加载材料时报告找不到文件,两类错误分别检查目录与文件名。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

验证材料完整性与 CLI 参数配置
正式运行生成管线之前,必须确认材料目录非空,两个文件的格式也没问题,执行下面这条命令就能快速检查:
ls -l my_materials/
输出结果里要明确显示 idea_sparse.md 和 experimental_log.md 两个文件都存在,且大小大于0。如果你修改了默认文件名,调用 CLI 时必须显式传入参数覆盖默认值。
使用自定义文件名
如果你想给不同版本的研究草稿起不同的文件名方便区分,可以用 --idea_filename 和 --experimental_log_filename 参数实现。比如你把假设文件重命名为 v2_hypothesis.md 之后,调用方式如下:
python paper_writing_cli.py \ --raw_materials_dir ./my_materials \ --latex_template_dir ./templates/cvpr2025 \ --output_dir ./output_v2 \ --idea_filename v2_hypothesis.md \ --experimental_log_filename experimental_log.md
这里的 ./templates/cvpr2025 只是示例模板路径,实际使用时要替换成你所投会议对应的 LaTeX 模板目录。如果没提供 --latex_template_dir,程序会直接报错退出。这套逻辑不用修改全局默认文件名,靠传参就能灵活切换不同的输入源。

排查常见材料加载错误
准备材料阶段最常见的故障就是路径错误或者文件缺失。运行 CLI 时如果碰到 Error: Raw materials directory ... does not exist,先检查 --raw_materials_dir 是绝对路径还是相对于当前终端工作区的相对路径。建议先用 pwd 确认当前终端的工作位置,再用 realpath my_materials 获取目录的绝对路径,就能避免路径歧义。
另一种常见情况是文件存在但内容为空,框架解析阶段检测到空文件可能不会立刻报错,但生成大纲的时候会因为缺少上下文输出低质量内容。建议正式提交前用 wc -l my_materials/*.md 统计两个文件的行数,确保每行都是有效文本内容。另外不要往 Markdown 文件里混入复杂的 HTML 标签或者非标准字符,不然很容易导致解析器抛出语法错误,影响后续的 LaTeX 转换。

















