什麼时候需要 Reference
欄位映射表、狀态碼字典、join 說明、外部代碼对照——这類内容往往很长、很少整份改，但分析时要反覆查。
| 放錯地方 | 問題 |
|---|---|
| 整段塞进 Plan / Report | 污染交付流程；Execute 狀态機与審閱焦点被稀釋 |
| 整段塞进 Project Knowledge | 注入预算有限；Agent 每次都被動帶上全文 |
| 只放在资料夾、沒索引 | Agent 不知道存在、也不知道何时該读 |
Reference docs 是專案内的「映射手冊」：正文在 Reference 檔，Agent 透过 Project Knowledge 的短索引按需查閱。
在产品里长什麼樣
- 側邊欄 Projects 下，Plan / Report 与 Reference docs 分开子樹——永不混列
- Reference 檔为一般 Markdown（@@PROTECT0@@；旧版 @@PROTECT1@@ 仍相容）
- Update Intro 在 @@PROTECT2@@ 写入一條 @@PROTECT3@@
- Agent 在任务符合 When to read 时才載入全文；你也可在对話中指名「查 mapping 表」
- 若内容本来由这次项目对话或分析整理而成，可明确要求 Agent 存成 Project Reference；系统会一次建立正文、名称与必填 Intro，不会伪造成由本机文件导入。
逐步操作見 USER_GUIDE §11.3.1。
Update Intro 的两條路
| 方式 | 适合 |
|---|---|
| Create by agent | 已有 mapping 草稿，请 Agent 提案 Purpose / When to read → 審批卡 Apply |
| Enter manually | 你已清楚索引文案，直接填写、不经審批卡 |
首次儲存 Reference 后，工具列会引导建立 Intro（可选稍后再說）。沒有 Intro 的 Reference，Agent 不会主動知道何时該读。
与 Plan、Memory、SQL 的分工
| 内容 | 放哪 |
|---|---|
| 本次分析的时间窗、checkpoint | Plan |
| 穩定、可核准的业务规则 | Project / User Knowledge（見 Memory 分工） |
| 大型映射表、字典全文 | Reference 檔 + @@PROTECT4@@ 索引 |
| 可執行的 JOIN / WHERE | SQL 分页（見 SQL-first） |
原则： Reference 存查表本体；Knowledge 存何时查、查什麼的一句索引。
匯出、封存、Compare
- Project / Workspace 匯出 会帶 Reference 檔与 Knowledge 中的 @@PROTECT5@@ 條目
- 封存 Reference 后，Agent 预设不主動读取，除非你明確要求
- Compare view 可唯读开启 Reference（无批註面板）
跟做（約 10 分钟）
- 在测试專案 Reference docs 右鍵 → New Reference
- 貼一小段欄位映射（5–10 行即可）并儲存
- 点 Update Intro → Enter manually，填 Purpose 与 When to read（例如「写 funnel SQL 前」）
- 聚焦專案，对 Agent 提一个会用到該映射的問題，確认它会先查表再写 Plan