Reference docs：大型參照怎麼放

讀時間： 約 7 分鐘 · 系列： 分析師進階 · 上一步： 統計分析工具 · 下一步： Memory 分工

什麼時候需要 Reference

欄位映射表、狀態碼字典、join 說明、外部代碼對照——這類內容往往很長、很少整份改，但分析時要反覆查。

Reference docs 是專案內的「映射手冊」：正文在 Reference 檔，Agent 透過 Project Knowledge 的短索引按需查閱。

側邊欄 Projects 下，Plan / Report 與 Reference docs 分開子樹——永不混列
Reference 檔為一般 Markdown（ref_N.md；舊版 NN_reference.md 仍相容）
Update Intro 在 project_knowledge.md 寫入一條 [Ref: file_name] Purpose: … When to read: …
Agent 在任務符合 When to read 時才載入全文；你也可在對話中指名「查 mapping 表」
本機 PDF／DOCX／PPTX 等可經 Create reference from… 匯入成 Reference（含圖片資產）；細節見 USER_GUIDE §11.3.1
若內容本來就由這次對話或分析整理而成，可在聚焦專案中明確要求 Agent 存成 Project Reference；系統會一次建立正文、名稱與必填 Intro，不會偽造成外部檔案匯入

方式	適合
Create by agent	已有 mapping 草稿，請 Agent 提案 Purpose / When to read → 審批卡 Apply
Enter manually	你已清楚索引文案，直接填寫、不經審批卡

首次儲存 Reference 後，工具列會引導建立 Intro（可選稍後再說）。沒有 Intro 的 Reference，Agent 不會主動知道何時該讀。

內容	放哪
本次分析的時間窗、checkpoint	Plan
穩定、可核准的業務規則	Project / User Knowledge（見 Memory 分工）
大型映射表、字典全文	Reference 檔 + `[Ref: …]` 索引
本機 PDF／DOCX／簡報裡的參照說明	Create reference from… 匯入成 Reference（不是塞進 Plan）
可執行的 JOIN / WHERE	SQL 分頁（見 SQL-first）
明顯可 SQL 查詢的 CSV／表格資料	優先 Workspace 資料源，不要一律當 Reference

原則： Reference 存查表本體；Knowledge 存何時查、查什麼的一句索引。

Agent 讀 Reference 時只拿到 Markdown 與圖片連結，看不到圖。需要它看某一張圖時：Visual 右鍵圖片 → Copy image → 貼到對話（見 USER_GUIDE §12.3.1）。

Project / Workspace 匯出 會帶 Reference 檔、Knowledge 中的 [Ref: …] 條目，以及圖片資產與來源備份（若有）
封存 Reference 後，Agent 預設不主動讀取，除非你明確要求
Compare view 可唯讀開啟 Reference（無批註面板）

路徑 A — 空白殼

在測試專案 Reference docs 右鍵 → New Reference
貼一小段欄位映射（5–10 行即可）並儲存
點 Update Intro → Enter manually，填 Purpose 與 When to read（例如「寫 funnel SQL 前」）
聚焦專案，對 Agent 提一個會用到該映射的問題，確認它會先查表再寫 Plan

路徑 B — 本機文件匯入（可選）

路徑 C — 對話整理成原生 Reference（可選）