Agent 時代的數據分析工作流：可審閱的交付、協作與執行授權

方法論答卷 A：AI 不取代分析流程，而是把流程變成可審閱的 artifact 與明確的執行授權。知識治理見 可治理的 Agent Memory。操作見 使用者指南 §10–12。

系列位置

完整導讀見 系列導讀與產品定位。

一、核心判斷：AI 不會取代分析流程，只會重塑分析流程

數據分析的本質沒變：提出問題、理解資料、驗證假設、形成結論、對利害關係人負責。變的是介面——從「在聊天視窗裡問一句答一句」，變成「在 IDE 裡留下可查的 SQL、可改的 Plan、可簽核的 Report」。

Lantide Data 的產品假設是：

• 分析不是單次回答，而是一組可討論、可版本化、可執行的交付物。
• 人類保留節奏與授權；Agent 負責探索、起草與執行，但不能自行按下「開始跑正式分析」的開關。
• 協作發生在文件上（批註、Plan 狀態），而不只是對話氣泡裡。

二、Quick Analysis 與 Project Analysis

簡單 SQL 問答（如語法怎麼寫）不強制選模式。有分析意圖時，Quick 模式下 Agent 會先問要快速分析還是建立專案。詳見 §12.5。

何時用哪種模式（決策要點）：

一次性查詢 / 欄位探索 / 無需簽核交付物     → Quick Analysis
需審閱假設、版本化 Plan、正式 Report/HTML  → Project Analysis（建議先 focus 專案）
已 focus 專案                              → 直接走專案迴圈，不再詢問模式

管線階段映射（見 系列導讀 §一「分析師的一天」）：

三、為何 SQL-first：分析、維護與協作

Lantide Data 把 SQL 作為分析工作的主交付語言——不是因為引擎碰巧支援 DuckDB，而是因為在現代分析實踐裡，最值得被留下、被維護、被協作的部分，是口徑與取數。

下面從三個角度說明：分析時口徑即契約、維護時 SQL 可 diff 可重跑、協作時討論發生在可查的 artifact 上。

分析：口徑即契約

分析品質取決於「這個數是什麼意思」，而不取決於程式寫得是否簡潔。活躍用戶怎麼定義？兩個來源的 user_id 怎麼對齊？這個 JOIN 會不會 fan-out？這類問題用關係代數最直接：FROM、JOIN、WHERE、GROUP BY 就是在寫口徑契約。

Plan 天然是 SQL 規格書——寫的是查什麼、用哪些表、如何驗證——而不是一串 notebook cell 的執行順序。分析不是單次回答，而是一組可討論的假設與證據；SQL 讓假設可被引用、可被反駁。

分析品質：先把數算對，再談管線形狀

SQL-first 不等於「把所有東西都拆成 DAG」。真正的優先順序是：

1. 先講清楚問題、分母、時間窗與業務口徑。
2. 確認資料粒度、欄位、JOIN key 與可能的 fan-out。
3. 用最小可驗證 SQL 證明指標邏輯是對的。
4. 檢查輸出欄位與步驟名稱是否一致，例如「商品類別分析」就應該產出類別欄位。
5. 最後才判斷是否需要 persist tab、快取或 Source Run。

因此，cache / DAG 是可重用與可審閱的優化能力，不是分析可信度的最低條件。若一個多表 JOIN 是一次性且口徑清楚，直接 SQL 也可以是正確選擇；若中間結果會被重用、需要同事審閱，或上游改動後需要重跑，才值得升級成 persist-tab DAG。

維護：可 diff、可重跑

維護分析，維護的是六個月後還能不能說清楚這個數怎麼來的。

• 宣告式邏輯易審閱：改一條 WHERE 或 JOIN 條件，diff 直指口徑變更，而非沿 imperative 程式重建心智模型。
• 依賴顯式：FROM "clean_orders" JOIN "dim_user" 把中間假設寫在紙上；notebook 裡的 df2、df3 是隱式狀態。
• 重跑語意乾淨：同一段 SQL、同一套表 → 結果可預期；較少 cell 執行順序造成的「為什麼我先跑第 7 格就不一樣」。
• 接近團隊口徑語言：可復用的定義往往最終以 warehouse SQL / 語義層存在；在 SQL 裡打磨的口徑，比藏在一次性 Python 裡的更容易升格為團隊資產。

協作：發生在 SQL 分頁與 Plan 上

協作型分析常敗在：結論在簡報裡，邏輯在某人筆電裡；圖表能分享，口徑不能討論。下表說明 SQL-first 如何回應常見協作需求：

圖表可以分享；口徑必須可討論。這與 系列導讀 §一 中 Julius 類 Harness（隱藏程式換速度）形成對照：我們選擇暴露 SQL 以換可治理。

與 Python 的分工

不是不用 Python，而是不讓 Python 成為預設的、不可審閱的分析載體：

統計與 ML 在已審閱的乾淨表上執行，取數仍走 SQL——見 §十二。拒絕的是「模型在對話裡隨手寫 pandas、跑完即丟」的預設路徑。

邊界（我們不宣稱取代一切）

• 高度程式化、自訂演算法、重度探索性 notebook → Jupyter / Cursor 等仍合理；Lantide 補的是需治理與簽核的分析。
• 非表格、NLP、深度學習 → 非主場景。
• 我們不做企業級 Silver ETL 調度；工作區內中間結果的定位見 統一查詢層 §七。

工程落點（一筆帶過）

上述原則由 IDE 內 SQL 分頁、Plan 契約與 統一查詢層（邏輯表名、物化、Source Run 血緣）承載；不在此展開 DuckDB / sqlglot 細節。

四、Plan / Report：Markdown 契約

專案內文件分 Plan（執行前契約）與 Report（執行後交付），通常以編號配對，例如 01_plan.md / 01_report.md。

Plan 寫的是查什麼、用哪些表、如何驗證——與 §三 SQL-first 一致：執行前的口徑契約，而非 notebook 執行順序。

設計目的：

1. Plan 是執行前的契約 — 查什麼、用哪些表、如何驗證，須先寫清楚再執行。
2. Report 是執行後的交付物 — 結論與證據進文件，而非只留在聊天記錄。
3. 一對一配對 — 新分析應新 Plan，避免覆寫舊 Report。
4. Executed Plan 鎖定 — 追溯歷史；後續迭代開新 Plan。
5. HTML 為第二種可交付物 — 見 §五；與 report.md 並存。

Plan Grilling（草案後對齊）： add_plan 成功後，若口徑、分母、資料邊界或假設仍未裁定，Agent 經 ask_user 進入 一次一問 + 推薦答案 的短問答；每確認一項即以 patch_plan 寫回 Plan，再進入審閱 handoff。分析方向發生結構性轉折時同樣先 grilling、再大改。可透過 schema／探數查到的事實不拿來問使用者。行為由 plan-authoring skill 定義（內建與外部 Agent 共用）。操作見 USER_GUIDE §2.5／§12.7。

專案檔案、封存（Archived docs）、焦點模式見 §11。

Plan 三態（系統內部代碼如 PlanPlanning 等，此處用產品語言）：

前端指示器與後端狀態同步，決定可用工具集（見 AI Agent 架構）。Continue / Mark Executed 處理執行中斷，見 §11.5。

flowchart LR
  planning[Planning_可批註]
  execute[使用者_Execute]
  executing[Executing_跑SQL]
  report[add_report]
  executed[Executed_鎖定Plan]
  stopped[Stopped_保留部分成果]
  planning --> execute --> executing --> report --> executed
  planning --> stopped
  executing --> stopped
  stopped --> planning

Reference docs（與 Plan / Report 分流）

除 Plan / Report 外，專案可含 Reference 檔——存放欄位映射、狀態碼字典、join 說明等大型、少整份改寫的參照本體。設計取捨：

建立路徑： 空白殼（New Reference）、Agent 原生建立，或本機文件匯入（governed import）。原生建立只在 ProjectFocused／PlanPlanning 開放，明確要求可一次提交；Agent 主動建議則先取得綁定內容 digest 的確認。Update Intro 可經 Agent propose_knowledge 審批或使用者手動寫入。封存 Reference 預設不觸發 read_reference。Project / Workspace 匯出含 Reference、索引、native origin，以及圖片資產／來源備份（若有）；Compare view 可唯讀開啟 Reference（無批註 sidecar）。操作見 §11.3.1；onboarding 見 Learn：Reference docs。

停止不是完成： 當正式執行的資料條件或決策前提改變，使用者可以 Stop & Replan，而不是把未完成的 Plan 標為 Executed。舊 Plan 保留停止原因、部分成果與正式 evidence；替代 Plan 必須重新滿足 Plan 的品質與執行契約，再由使用者重新 Execute。Plan／Report／HTML 的 Analysis Lineage 讓審閱者由交付物回看這條脈絡，並明示缺失、歧義或截斷的關係，不用聊天記憶補猜。

五、HTML 報告：第二種可交付物

除 Markdown Report 外，可從 Report 產出獨立 .html，在瀏覽器閱讀、分享或匯出。

產品定位：

• Generate / Re-generate：依版面（Standard / Presentation）、樣式預設、CDN／Chart.js 等配置，由 Agent 產出完整 HTML。Standard + CDN 時 Chart.js 預設開啟（需網路）；離線請關閉 CDN。
• Open Report / Export HTML Report：本機瀏覽或另存快照（Electron 匯出）。
• 事後修改（scoped edit）：在 Report 分頁或透過 activate_html_editing 請 Agent 做區塊編輯——patch_html_chunk_by_id（全量或 mode=replace 字串微調）、insert_html_chunk／delete_html_chunk（加／刪段落且不動其他區塊）、patch_html_styles。Chart.js 報告可含常駐數值標籤與命名標註（options.plugins.datalabels／annotation）。
• 何時 Re-generate：整體換版面、換 profile、或契約失效的舊檔；不要為「加一段分析」整份重產。
• Quick Edit HTML：使用者手動改單一區塊，帶 content hash 防併發覆寫；可開 Live Preview 熱重載（patch／insert／delete 皆觸發 reload）。
• Other Requirements：配置對話框可附自由文字與 / User skill 片段，注入 Generate 任務。
• Content quality hints：契約通過後仍可能附非阻斷 content_hints（legacy 別名 content_warnings：段落過少、缺 executive summary／limitations）；Agent 應擴寫後再視為定稿。契約失敗時走 html_report_design skill recovery（load_skill → read_report → 重建），見 AI Agent 架構 §7.4。

契約要求（如 data-report-contract="1"、單一 #report-styles、data-text-id 區塊）與工具行為在 AI Agent 架構 §七 說明。操作步驟見 使用者指南 §10。

External Agent 邊界： Execute 雙開須在 GUI Approve & Execute；Admin 單開可在外部對話確認後 claim_plan_approved。Plan 草稿在外部 chat 不取代 Lantide GUI 上的 Plan 狀態（見 USER_GUIDE §13.6–13.8）。

六、Plan / Report 批註：把共識寫進文件

批註讓審閱意見綁在原文上，並成為 Agent 下一輪修改的輸入。

儲存模型： Preview 選取文字 → 批註寫入 *.annotations.json sidecar，並在 Markdown 正文寫入 id-only <mark data-annotation-id>；編輯器以正文 mark 與右側卡片雙向對應。舊 data-comment inline mark 開檔自動遷移至 sidecar（metadata 不含 anchor.span；正文 id-only 保留仍規劃中）。不支援巢狀批註。

Resolve Comments： 工具列一鍵請 Agent 依全部 open 批註更新文件（等同手動說「處理批註」）。Executing / Executed 等鎖定狀態下正文唯讀，批註 margin 仍可操作。

狀態與生命週期： Open → Agent Resolve → Resolved → 可 Archive（history 留於 sidecar dismissed[]）；Reopen 可恢復 Resolved。正文 mark 遺失時為 orphaned（主視窗 UI 標 Anchor outdated）——需 Re-anchor 重新反白；View changes 提供 Before/After 對照。

Compare view： 唯讀顯示 sidecar 批註與高亮、View changes Popover；不可編輯、刪除或 Re-anchor——協作編輯留在主視窗。見 §11.10.3。

Agent 透過 read_plan / read_report 取得含 id-only mark 的磁碟正文與 sidecar annotations；批量處理走 resolve_annotations（原子寫回 sidecar + 正文 mark）——實作見 Prompt 與 Context 工程 §十一。操作見 §11.6–11.9。

Report 表格另支援 Copy for Excel（TSV + BOM），與 SQL 結果 Export 不同，見 §11.4.1。

七、最重要的邊界：Agent 不能自己按 Execute

Execute 是使用者明確授權：將 Plan 切到 Executing，並觸發 Agent 依 Plan 執行。Agent 不得透過工具或對話自行等同於「使用者已按下 Execute」。

這條邊界區分：

• 探索與起草（讀表、驗證 SQL、改 Plan）
• 正式執行分析（需 Executing 狀態與使用者已選的執行模式）

若 Agent 能自行開跑，利害關係人簽核就失去意義：Plan 上的假設可能尚未審完，批註可能還掛在原文上，正式統計卻已在背景產出 Report——分析師無法向團隊交代「這個數是誰、在什麼前提下核准的」。因此 Execute 必須是可觀測的人類動作，而非模型自行推斷的意圖。

Planning 階段不得跑正式統計或 activate_analysis；方法論護欄寫在 Prompt 層（Prompt 與 Context 工程）。

八、add_report：用交付物完成狀態轉換

執行完成後，Agent 以 add_report 一次性產出 Report，並將對應 Plan 標記 Executed。這是狀態機上的交付事件，不是隨手改一篇 Markdown。

• 新 Plan 執行 → 新 Report；不更新舊 Report。
• PlanExecuting 期間矩陣不含 update_report／patch_report：正式 closeout 只能 add_report；Executed 之後若使用者批註或明確要求，才修訂已有 Report 段落（增量編輯優先）。

九、Foreground / Background / Hybrid

Plan 進入 Executing 後，Agent 透過 ask_user 詢問一次執行偏好：

同一對話內不重複詢問已表達的偏好。後台 run_query 的物化策略與 persist / agent 快取語意見 Prompt 與 Context 工程 §七（語意契約）與 統一查詢層 §8.1（策略表）；Data → Cached 右鍵 查看 SQL 可審閱任一快取來源。

十、ask_user：把人類決策變成協議

需要選模式、確認執行方式、探索配額用盡是否繼續、以及 Plan Grilling（口徑／邊界裁定）等，Agent 呼叫 ask_user，前端顯示選項或自由文字；後端暫停 ReAct 直至回覆或逾時（約 5 分鐘）。探索配額續跑亦經此協議，見 AI Agent 架構 §4.2；grilling 節奏見 §四。

這把「產品流程」從 prompt 裡的建議，變成可觀測的互動事件。操作見 §12.7。

十一、分析品質護欄

分析品質護欄分三層協作：識別場景（A/B、漏斗、異常等，在 Plan 中加入檢查點、在 Report 中寫限制）→ ask_user 確認（統計參數、執行模式等人類必須拍板的決策）→ activate_analysis 執行（在已審閱的乾淨表上跑內建統計／ML 工具）。Planning 階段不應跳過前兩步直接跑統計；工具可用性由狀態矩陣過濾（見 AI Agent 架構 §三）。

對一般商業分析，最低品質線不是「有沒有 DAG」，而是報告是否可信。新建 Plan 與 Report 會以可機器檢查的讀者契約驗證必要結構，並把 semantic section mapping 與內容 digest 綁定的 verification receipt 一起留下；這不取代人的審閱，卻能避免缺少決策、證據、範圍或限制說明的交付物直接定稿。add_report 前 skill／playbook 會自檢邏輯與閱讀體驗（Do-not-ship 反模式）；Release smoke 目前用下列訊號當 hard gate：

• 是否先建立 Plan、再依 Plan 建 todo、最後產出 Report。
• SQL / tool 是否沒有明顯錯誤迴圈。
• 報告是否講清楚場景必要內容，例如漏斗的 stage definition、denominator、最大流失環節。
• 報告是否有具體數字與 limitations，而不是只留下聊天摘要。
• 速率、漏斗、留存、財務等指標是否同時保留 numerator / denominator 與粒度說明。

DAG、Source Run、Execution Strategy 區塊現在是 soft signal：用上很好，沒用上不應阻擋一份可信分析。

文件修訂優先段落級增量編輯，減少整份覆寫與批註錯位。操作見 §12.9–12.10。

十二、反模式

十三、能力總覽

十四、結語

Lantide Data 的分析工作流核心，是把「問 AI 一個問題」變成「留下一組可審閱、可授權、可重跑的交付物」。Execute 邊界與 SQL-first 口徑契約 是這套方法論的兩根支柱——前者保證人類節奏，後者保證協作載體。

跨對話的口徑沉澱屬於另一維度：見 可治理的 Agent Memory。若要理解模型如何看見 Plan、批註與知識，接著讀 Prompt 與 Context 工程。