Paper Workflow Orchestrator

确认后，设置环境变量 PROJECT_ROOT 指向用户确认的根目录，所有脚本会自动使用该路径。

4. 研究课题名称: "您的研究课题简称是什么？（用于报告标题、图表标注、输出文件名）"
   • 默认值为空，必须由用户确认
   • 示例："ClimateAI"、"AI4S"、"Quantum"、"LLM" 等
   • 设置环境变量 RESEARCH_TOPIC=<课题简称>
   • 所有图表标题、数据源标注、报告文件名均使用该变量
   • Do not continue to final report export if RESEARCH_TOPIC is missing or ambiguous

Data Format Routing

根据用户提供的数据格式，自动决定从哪个阶段开始：

格式检测逻辑（agent 在 Pre-flight 阶段执行）：

import pandas as pd
df = pd.read_csv("user_file.csv", nrows=5)  # 或 pd.read_excel
cols = set(df.columns)
has_ut = "UT" in cols
has_base = {"TI", "AB", "PY"}.issubset(cols)
has_country = any(c in cols for c in ["country_c1", "Country", "C1"])
has_author = any(c in cols for c in ["author_id", "AU", "paper_authors"])
print(f"UT={has_ut}, base={has_base}, country={has_country}, author={has_author}")
# 根据结果决定入口阶段

Portable Directory Convention

Same as paper-data-processing. All paths are workspace-relative.

{workspace}/
├── data/raw/              # ← User input: WoS txt files
├── data/processed/        # Processing + analysis outputs
├── reports/               # Final deliverables
│   ├── figures/
│   ├── tables/
│   └── {RESEARCH_TOPIC}_bibliometric_report.md
├── models/
├── src/
└── .github/skills/

Delegation Rule

1. Use paper-data-processing for raw data → processed artifacts.
2. Use paper-processing-analysis-handoff as the mandatory stage gate between processing and analysis.
3. Use paper-analysis-report for analysis → report artifacts, only after handoff returns analysis-ready.

Portability Enforcement

Before running ANY script at ANY stage:

1. The agent reads the script and checks for hardcoded absolute paths.
2. If found, patches them to workspace-relative paths.
3. This is a non-negotiable step at every stage.

Stages

Stage 1: Data Processing

• Delegate to paper-data-processing skill.
• Input routing by format:
  • WoS .txt → src/wos_txt_to_csv.py → data/processed/wos_merged.csv
  • CSV/Excel → agent 检测字段完整度，复制到对应的 processed 位置，跳过已完成的子阶段
• Output: data/processed/wos_merged.csv, data/processed/wos_cleaned.csv, data/processed/paper_authors.csv, data/processed/authors_summary.csv

Stage 2: Handoff Gate

• Delegate to paper-processing-analysis-handoff skill.
• Validates UT contract, column schema, artifact existence.
• Returns: analysis-ready, ready-with-risks, or blocked-*.
• Do NOT proceed to Stage 3 unless status is analysis-ready or ready-with-risks.

Stage 3: Analysis and Reporting

• Delegate to paper-analysis-report skill.
• Sub-stages executed in order:
  1. Topic modeling → data/processed/paper_topics.csv, reports/topic_info_*.csv
  2. Mobility analysis → reports/flow_matrix.csv, reports/talent_flow_sankey.html
  3. Chapter figures/tables → reports/figures/, reports/tables/
  4. Final report assembly → reports/{RESEARCH_TOPIC}_bibliometric_report.md
  5. Export figure-integrated Word report → reports/{RESEARCH_TOPIC}_bibliometric_report.docx
  6. Report quality gate → run skills/paper-analysis-report/scripts/report_quality_gate.py --report reports/{RESEARCH_TOPIC}_bibliometric_report.md
  7. Manual report checklist → skills/paper-analysis-report/checklists/report-quality-checklist.md

The orchestrator must not export a final report to a generic bibliometric_report.* name when RESEARCH_TOPIC is known. Final report paths should bind to the current topic to avoid stale-report reuse in cold-start testing.

Stage 4: Verification

• All expected artifacts exist at workspace-relative paths.
• Final report references valid figure paths.
• Final Word report exists and is suitable as the formal illustrated deep-analysis deliverable.
• Report quality gate passes with no blocking issues.
• Final report is not accepted if it only provides descriptive ranking/chart narration without data-backed structural judgment.
• Summary of outputs and any residual risks emitted.

Stage Gate Contracts

Rerun Strategy

• Full rerun: execute all stages 1 → 4.
• Partial rerun: execute only impacted stage + downstream.
• No rerun of unaffected upstream stages unless schema changed.

Failure Handling

• Stop at failed stage.
• Emit: failing script, error summary, missing artifact list.
• Do not proceed downstream until gate checks pass.

New Machine Quick Start

1. Copy workspace folder to new machine.
2. python -m venv .venv
3. .venv\Scripts\activate        # Windows
   source .venv/bin/activate     # Linux/Mac
4. pip install -r requirements.txt
5. Place WoS .txt files in data/raw/
6. Ask: "从 WoS 数据开始走完整分析流程"

Done Criteria

• All requested stages complete.
• Artifacts generated at expected workspace-relative paths.
• Final summary lists outputs and residual risks.
• On a fresh machine with only WoS data, the full pipeline runs without path editing.