# 根據你的資料寫作

讓分析的輸入、腳本、表格與稿件結果保持連結。

當結果段落背後的計算就在附近時，這段文字更讓人信得過。請用研究專案，把分析程序與它的輸出放在稿件旁邊。

## 設定專案

選擇 **「可重現分析」** 起始範本。[連結資料所在的資料夾](/docs/linked-folders/)，讓研究工具可以讀取原始量測資料，而不必把它們搬進論文裡。

在要求分析之前，先記錄各欄的意義、單位與任何排除的資料。

## 給助理一個範圍明確的工作

使用 `/oleafly-data-analysis` 或 **「分析」** [研究任務](/docs/research-tasks/)：

> 讀取已連結 Data 資料夾中的量測資料。使用 analysis-plan.md 中的方法比較兩個條件。儲存腳本、一份附單位的表格，以及一份說明排除項目的註記。不要更動輸入資料。

分析腳本需要相關的本機執行環境與程式庫。請助理檢查這些需求，並把重新執行這項工作的方式存起來。

## 檢查輸出

閱讀腳本，確認所選的資料與方法符合問題。接受結果之前，先檢查單位、樣本數、缺失值與不確定性。

把表格與圖片和產生它們的腳本放在一起。[圖片準備技能](/docs/skills/)可以幫忙把檢查過的結果變成稿件用的圖片。

使用 [CLI 代理程式](/docs/cli-agents/#research-starting-points)時，**「可重現性查核」** 起點會詢問每個結果還需要什麼才能被重現：程式碼、資料、軟體版本、隨機種子與建置說明。**「圖片查核」** 會檢查圖說、標籤、座標軸單位與可讀性。兩者都會請代理程式在 `research/` 中寫一份報告，並且不動稿件。

## 在文件中執行程式碼

想讓 PDF 中的數字直接來自程式碼，請用 [Quarto 或 Calepin](/docs/engines/#quarto) 撰寫報告。Quarto 在 `.qmd` 或 `.Rmd` 檔案中執行 R、Python 或 Julia 程式碼區塊，而 Calepin 在 Typst 文件中執行程式碼區塊。

- 每個專案的程式碼預設都是關閉的，直到你選擇 **「在此專案中允許程式碼」**。程式碼關閉時，Quarto 會顯示每個程式碼區塊的程式碼但不顯示輸出，而 Calepin 會顯示上次執行程式碼時儲存的結果。篩選器、短代碼、`_extensions` 資料夾、算繪指令碼和行內 R 程式碼即使在這時也會執行程式碼，所以使用其中任何一項的專案在你允許程式碼之前無法編譯。
- 程式碼關閉且電腦上沒有 R 時，有 front matter 的 `.qmd` 檔案仍然可以預覽，除非它的 front matter 有 `knitr:` 鍵。任何其他含有 R 程式碼的文件，包括 `.Rmd` 檔案，即使程式碼關閉也需要 R。請從 [cloud.r-project.org](https://cloud.r-project.org/) 安裝 R，然後再編譯一次。
- Oleafly 需要 Quarto 1.5 或更新版本。如果你的版本較舊，Oleafly 會使用自己的副本，或請你從 **「設定 → 引擎 → Quarto」** 下載一份。沒有下載副本時，`_quarto.yml` 專案中的文件會改用你較舊的 Quarto 建置。
- 專案有 `.venv`、`venv` 或 `env` 資料夾且裝有 Jupyter 時，Python 程式碼會在專案自己的環境中執行；專案有 `.venv` 資料夾時，Calepin 會使用它。否則程式碼會在 **「設定 → 引擎 → Quarto」** 的 **「語言」** 下列出的 Python 中執行。
- `pdf` 或 `beamer` 文件需要 LaTeX。沒有安裝 TeX 時，請在 Oleafly 提供時安裝 TinyTeX、把文件切換為 `format: typst`，或在允許程式碼之後，於 front matter 加入 `pdf-engine: tectonic` 來使用內建引擎。
- Quarto 會在文件旁邊寫出一個與文件同名的工作檔案：PDF 是 `report.tex`，Typst 是 `report.typ`。如果你已有檔案用了那個名稱，編譯會停止並指出它，而不是取代它。請重新命名或移動你的檔案，然後再編譯一次。
- 如果 PDF 中缺少韓文、中文或日文字元，警告會指出一個字型，並給出兩行要加入 front matter 的內容：`CJKmainfont:` 加上該字型，以及 `pdf-engine: tectonic`。兩者都要加，因為字型隨內建引擎提供。`pdf-engine: tectonic` 只有在專案允許程式碼之後才有效。
- 筆記本最多可以執行一小時。超過後 Oleafly 會停止它，記錄檔會顯示它跑到的儲存格。請縮短或快取那個儲存格，然後再編譯一次。

## 寫出結果

請助理只使用審閱過的輸出，草擬結果段落。把每個數字與表格對照檢查，並讓方法與詮釋分開。

編譯文件，並在 PDF 中檢查完整的表格或圖片，包括標籤與圖說。
