專案管理與 Markdown 批註

11. 專案管理與 Markdown 批註

本章說明 Plan / Report 的介面操作與批註功能。分析流程概覽見 §1.3、§2。

11.1 專案與檔案管理

在側邊欄的「Projects」區塊，你可以建立與管理分析專案。

建立專案：

1. 在「Projects」區塊點擊 ＋ 按鈕。
2. 輸入專案名稱，點擊確認。
3. 新專案會出現在側邊欄，可在其下新增 Markdown 檔案。

管理檔案：

• 在專案名稱上按右鍵，選擇「New File」新增 Plan 或 Report 檔案。
• 點擊檔案名稱即可在主區域開啟 Markdown 分頁。
• 右鍵選單提供開啟、刪除，以及設定／編輯別名（見 §11.2）。
• 右鍵選單亦提供 Export project…，可將該專案（可再勾選其他專案）打包為 .lantide 檔（見下方 §11.1.0）。

11.1.0 何時用哪種匯出

四種 .lantide 匯出的操作步驟見 §11.1.1–§11.1.3。先依你的目標選類型：

一句話： Project 帶這次分析的契約與交付；Workspace 帶整個工作環境（預設不含本機 CSV／Parquet，可選打包）；Application 帶你是誰；四者都不含資料庫密碼與授權快取。

常見場景對照：

常見誤解：

• Project 不含實體資料檔——收件方須在本機有相同資料、或自行 Rebind／連線後才能重跑 SQL。
• Workspace 預設不含 CSV／Parquet——接續查詢通常要 Rebind 指向本機資料夾（含 Additional folder），或匯出時勾選 Include physical data files（涵蓋初始資料夾與 Additional folder 中符合範圍的已註冊檔）。
• 匯入後不能立刻查——須 Reconnect databases、Reconfigure MCP；含 Additional folder 時可能出現 Additional folders destination（還原至你選的基底目錄下各 alias 子目錄）；SQL Server 等連線不含可復原密碼，須重新輸入 credential。無 physical data 時常需 Source Run 重建快取。

11.1.1 匯出與匯入專案（.lantide）

可將一個或多個專案的 Plan、Report、project_knowledge.md、Reference 檔（ref_*.md；舊版 NN_reference.md 仍相容）、Reference 圖片資產與來源備份（若有）及相關 sidecar（進度、批註 *.annotations.json、HTML、viz）打包成單一 .lantide 檔。適合共享分析脈絡與結果（見 §11.1.0）。不包含工作區資料檔、SQL 分頁、連線設定或對話紀錄。

匯出：

1. 點擊頂部列 UsersRound 圖示 → Export… → Project；或在專案上右鍵 → Export project…（會預先勾選該專案）。
2. 在對話框中勾選要匯出的專案（至少一項），點擊 Export…。
3. 選擇儲存位置；預設檔名為 proj_export_<日期>.lantide。

匯入：

1. 點擊頂部列 UsersRound 圖示 → Import… → Project。
2. 選擇 .lantide 檔（僅副檔名須為 .lantide，主檔名任意）。
3. 確認預覽資訊後，選擇目標工作區；若專案名稱已存在，可勾選 Rename on conflict 自動加上 (imported) 或 (2) 等後綴。
4. 點擊 Import。成功後側邊欄專案列表會更新；不會自動切換專案焦點。請重新連接資料來源後再執行查詢。

注意： HTML 報告若內含本機 localhost URL，匯入後預覽可能需在目前執行個體下重新產生或調整。

11.1.2 匯出與匯入工作區（Workspace .lantide）

可將整個工作區的設定（data.json、tabs.json、schema.json、連線與 MCP 設定、knowledge_queue、所有專案等）打包為 .lantide 檔。適合協作接續工作或換機（見 §11.1.0）。預設不包含實體資料檔；可選勾選 Include physical data files 將已註冊的 CSV／Excel／Parquet 一併打包（含初始資料夾與 Additional folder）。不包含 user_knowledge.md 或全域 global_config.json。

匯出：

1. 點擊頂部列 UsersRound 圖示 → Export… → Workspace。
2. 可選是否包含 agent query ledger、chat sessions、MCP cache。
3. 實體資料（可選）： 勾選 Include physical data files 後可選 Referenced in SQL tabs 或 All registered files；大於 50 MB 須二次確認，大於 10 MB 顯示進度。
4. 選擇儲存位置；預設檔名為 ws_export_<日期>.lantide。

匯入：

• 未含實體資料： 五步精靈 — Rebind 匹配本機已註冊檔；Additional folder 綁定需指向新機路徑。
• 含實體資料： 六步精靈 — 另含 Review files to extract（衝突：Replace／Rename imported／Keep existing）；若套件含額外文件夾，會請你選擇 Additional folders destination，檔案解壓至該基底下各 alias 子目錄並自動 rebind。

完成後 Reconnect databases、Reconfigure MCP sources；SQL Server 等須重新輸入密碼（套件不含可復原密碼）。必要時對相關分頁執行 Source Run。可選擇是否切換至新工作區。

注意： 連線密碼不會寫入套件；實體資料 bundle 可能含敏感檔案，請謹慎分享。

11.1.3 匯出與匯入應用設定檔與完整備份（Application / Full backup）

Application profile 可打包跨工作區的 user_knowledge.md（User Memory）、global_config.json 子集（knowledge／memory 設定），以及可選的 AI 偏好（ai_settings_config）。不包含 license_cache.json、實體資料檔或工作區內容。

Full backup 將一個或多個工作區（嵌套 .lantide 子套件）加上 Application profile 合併為單一 .lantide 檔，適合換機完整遷移。

匯出 Application profile：

1. UsersRound → Export… → Application profile。
2. 可選是否包含 AI preferences；預設不含 API keys（勾選含 keys 時須二次確認）。
3. 儲存為 app_export_<日期>.lantide。

匯入 Application profile（三步精靈）：

1. 選擇 .lantide 並預覽（含 user memory 大小、是否含 API keys）。
2. 選擇 User Memory：Merge（去重合併）或 Replace（覆蓋前備份至 .pre_import.bak）。
3. 選擇 Knowledge settings（global_config.knowledge）：Merge 或 Replace；Memory 僅 merge；可選套用 AI preferences。

匯出 Full backup：

1. Export… → Full backup。
2. 多選工作區；可選 ledger／chat／MCP cache、各工作區實體資料（與 Workspace 匯出相同 scope），以及 Application 可選項。
3. 多工作區時實體資料大小在匯出前顯示為 Size unknown until export（各 nested bundle 獨立估算）。
4. 儲存為 full_backup_<日期>.lantide。

匯入 Full backup：

1. 選擇 bundle 後，依序為每個內嵌工作區指定新名稱與資料夾；含 physical_data 的工作區須逐步處理檔案衝突（同 Workspace Extract Wizard）。
2. 最後設定 Application profile（User Memory／Knowledge settings／AI preferences）。
3. 完成後依檢查清單重新連接資料庫、MCP；必要時對相關分頁執行 Source Run，並檢查 AI Settings（含 localhost 提示）。

11.1.4 可選加密（passphrase）

四種 .lantide 匯出（Project、Workspace、Application profile、Full backup）均可選擇以 passphrase 加密外層套件。未勾選時產生的檔案與舊版相同（明文 ZIP，檔頭 PK），可與舊版應用互相匯入。

匯出：

1. 在 Export 對話框勾選 Encrypt bundle（或類似選項）。
2. 輸入 passphrase（至少 8 個字元）並在確認欄位再輸入一次。
3. 介面會提示：遺失 passphrase 將無法還原內容，請自行安全保存。

匯入：

1. 選擇 .lantide 後，系統先 inspect 套件類型；若為加密檔，會顯示 header 中的低敏感摘要（例如專案數、內嵌工作區名稱），並標註需解鎖後才能看到完整預覽。
2. 輸入 passphrase 並點擊 Unlock；解鎖過程可能需數秒（Argon2 金鑰衍生）。
3. 解鎖成功後顯示完整預覽（bindings、warnings 等），再執行匯入或 Rebind。

注意：

• Full backup 僅外層加密；內層各工作區子套件仍為明文 ZIP。
• 加密套件需要較多暫存磁碟空間（解密時會寫入暫存 zip）；完成後自動清理。
• Preview 與 Import 會各自解密一次（無跨步驟快取）。

11.2 檔案顯示別名（Display alias）

每份 Plan / Report 可設定一個顯示別名（最多 30 字），方便在側邊欄與分頁標籤上用語意化名稱辨識檔案，而不必記住 01_plan.md 這類檔名。磁碟上的實際檔名不變。

如何設定：

1. 在側邊欄專案檔案列上按右鍵，選擇 Set alias（尚未設定）或 Edit alias（已有別名）。
2. 在對話框中輸入別名；留空並儲存可清除別名。
3. 亦可對已開啟的 Markdown 分頁雙擊標籤或於標籤上右鍵 → Edit alias 進行編輯（SQL 分頁的雙擊／右鍵仍為重新命名分頁，行為不同）。

顯示規則：

• 側邊欄：有別名時顯示 別名 (01_plan)；無別名時僅顯示 stem（如 01_plan）。滑鼠暫留可看到完整提示。
• 分頁標籤：顯示 專案名稱/別名 或 專案名稱/01_plan（無別名時）；滑鼠暫留可看到完整標題。雙擊編輯時仍只編輯別名本體。
• 專案名稱不可包含 / 字元（建立與重新命名時皆會驗證）。
• 同專案內別名不可重複；若與其他檔案衝突，儲存時會顯示錯誤。

與 AI 的關係：

• AI 可透過 list_project_files 與聚焦專案摘要看見 file_name 與 display_alias 的對照。
• 你可在對話中用別名指稱檔案（例如「打開 Q1 計畫」）；Agent 工具會解析到正確的 canonical 檔名後再讀寫內容。

11.3 文件封存（Archived docs）

當你的專案中累積許多 Plan / Report 檔案時，可以將暫時不需要的文件封存，讓側邊欄主要列表保持簡潔。封存不會刪除檔案，也不會搬動磁碟上的路徑——文件仍然存在於同一專案中。

介面位置：

1. 在側邊欄展開某個專案後，列表最上方會固定顯示 Archived docs 群組（可點擊標題列展開／收合）。
2. 未封存的 Plan / Report 顯示在 Archived docs 下方，順序與檔案編號一致。
3. 封存區是否展開會依目前工作區 + 專案分別記住（存在本機瀏覽器中）。

如何封存與還原：

• 在一般列表中，將滑鼠移入某個檔案列時，列右側會顯示封存圖示；點擊後該檔會移入 Archived docs。
• 在 Archived docs 區內，移入檔案列時同樣會顯示**還原（解除封存）**圖示，點擊後檔案會回到下方的一般列表。
• 備援操作：在觸控裝置或不便 hover 時，可右鍵檔案列，選擇 Archive 或 Unarchive 完成封存／還原。
• 點擊圖示或選單項時不會開啟文件；點擊檔名列（列本身）仍可照常開啟 Markdown 分頁。
• Plan 若處於 Executing / Executed 等鎖定編輯狀態，仍可封存或還原（僅變更側邊欄歸類，不解鎖內容）。

與 AI 的關係：

• 封存後的文件仍可由 AI 讀取與開啟；若你需要繼續某份舊計畫或報告，直接開啟即可。
• 在已聚焦專案的前提下，傳給 AI 的「專案檔案摘要」會略過已封存檔，並以未封存檔案為主來理解目前工作脈絡（例如 Agent 工具中的「最新 Plan／Report」也以未封存者為準）。

11.3.1 Reference docs（參照文件）

Reference 是專案內可編輯的大型參照本體（欄位映射、狀態碼字典、join 說明等），與 Plan / Report 分開列在側邊欄 Reference docs 子樹下。

建立 Reference 的三條路

原生建立不需要先做一個 preview tool call；服務端會驗證內容，並把正文、alias 與 Purpose／When to read Intro 視為同一次操作。若是 Agent 主動建議，會先展示用途、大綱與 Intro，等你確認後才建立；確認後若內容改變，需重新確認。此路徑不會建立來源 manifest，也不支援圖片；真實本機來源或含圖片內容請使用 governed import。正式 Plan 執行中，內建 Agent 不會新增可能改變專案權威上下文的 Reference。

從本機文件匯入（跟做）：

1. 在側邊欄 Reference docs 右鍵 → Create reference from…，於檔案對話框選一個本機檔案。
2. Lantide 建立一次性匯入請求（請求本身不含主機絕對路徑）：
   • 無 active external writer：內建 Agent 自動接手解析並寫入 Reference。
   • 有 active Execute／Admin writer：匯入請求複製到剪貼簿；請貼到外部 Agent 對話，由外部 Agent 完成同一流程。
3. 成功後側邊欄出現新的 ref_N.md；圖片會顯示在 Visual；缺 Intro 時仍走下方 Update Intro 引導。

支援與限制（使用者語言）：

• 支援選檔： 常見文字／標記（.md、.txt、.html、.json 等）、PDF、DOCX、PPTX、XLSX／CSV／TSV、EPUB 等（以對話框 All supported files 為準）。
• 不內建 OCR： 掃描或純圖 PDF 可能要求提供可搜尋匯出；系統不會假裝產出空白「完整」Reference。
• 可查詢資料優先進資料源： 明顯是可 SQL 查詢的 CSV／表格式內容時，Agent 應先說明差異並詢問是否改放 Workspace 資料，而非一律當 Reference。
• 匯入產物： Markdown 正文＋受管圖片資產（Visual 可顯示）；來源可追溯。若你之後人工大幅改過正文，整檔覆寫會有衝突保護，不會靜默蓋掉你的修改。

外部 Agent 提供本機路徑（信任邊界）：

詳見 §13。需要 Agent 看圖時，在 Visual 右鍵圖片 → Copy image，再貼到對話（見 §12.3.1）。

Update Intro（工具列）：

• Create by agent：送 artifact 給 Agent → propose_knowledge → 審批卡 → Apply 寫入 Rules。
• Enter manually：直接填寫 Purpose / When to read，不經審批卡。
• 尚無 Intro 時，Update Intro 以黃字提示；首次儲存成功後會引導建立 Intro（可選 Not now，需二次確認）。匯入成功但尚未寫 Intro 時同樣適用。

匯出／匯入： Project bundle（.lantide）與 Workspace 內嵌專案皆包含 Reference 檔（ref_*.md）、project_knowledge.md 中的 [Ref: …] 條目，以及圖片資產與來源備份（若有）。

Compare view： 可在 Reference 檔案列右鍵開啟唯讀對照視窗（無批註 sidecar）。Tab bar 與 Compare view 中 Reference 分頁以琥珀色 md 標記，與 Plan（藍）、Report（綠）區分。

封存： 已封存的 Reference 預設不列入 Agent 主動讀取範圍；除非你在對話中明確要求，否則 Agent 不會依 [Ref: …] 索引載入已封存檔案。

11.4 專案焦點模式（Project Focus）

聚焦 / 取消聚焦：

1. 在側邊欄的專案列表中，每個專案右側有眼睛圖示（👁）。已聚焦的專案其綠色眼睛圖示會常駐顯示；未聚焦時，眼睛圖示與排序箭頭預設隱藏，需將滑鼠暫留在該專案列上（或鍵盤使列內獲得焦點）才會顯示，避免列上擠滿圖示。
2. 點擊眼睛圖示即可聚焦該專案——圖示變為綠色，該專案列會以高亮背景標示。
3. 再次點擊同一專案的眼睛圖示可取消聚焦。
4. 點擊其他專案的眼睛圖示會自動切換焦點（同時間只能聚焦一個專案）。

手動排序專案：

每個專案列右側的 ↑ / ↓ 與（未聚焦時的）眼睛圖示相同，預設在暫留該列或列內 focus-within 時才顯示；列表最上／最下的專案對應無效的箭頭會隱藏。點擊箭頭可調整專案在列表中的顯示順序。排序結果會持久保存，重新整理頁面後順序不變。

自動切換焦點：

當你開啟一個 Plan 或 Report 分頁時，如果該文件所屬的專案與當前聚焦的專案不同，系統會自動切換焦點到該專案：

• AI 未在生成時： 焦點自動切換，畫面右下角會顯示 Toast 通知（例如「Focused project switched to "銷售分析"」），附帶 Undo 按鈕可一鍵還原。
• AI 正在生成時： 系統會先彈出確認對話框，讓你決定是否切換（切換不會中斷 AI 生成，僅變更焦點）。
• 尚未聚焦任何專案時： 直接靜默切換，不顯示通知。

注意： 自動切換焦點僅在同一工作區內生效。開啟其他工作區的分頁不會觸發自動切換。

自動清理：

• 當被聚焦的專案被刪除時，焦點會自動清除。
• 重新命名工作區時，焦點與排序設定會自動遷移至新名稱，不會遺失。

提示： 焦點狀態按工作區獨立儲存——不同工作區可以各自聚焦不同的專案，互不影響。

11.5 Markdown 雙模式編輯

Markdown 分頁支援兩種編輯模式，可從分頁工具列隨時切換：

分頁標籤顏色區分： Plan 分頁的標籤以藍色顯示，Report 分頁以綠色顯示，Reference 分頁以琥珀色顯示，與側邊欄的顏色一致，讓你一眼就能區分不同類型的 Markdown 文件。

工具列版面（Plan / Report）： 左側為 Visual / Markdown 模式切換；中間為 Save 圖示按鈕（Tooltip 顯示 Cmd/Ctrl+S；有未儲存變更時圖示右上角顯示圓點）與 View options（含 Wide layout，僅 Visual 模式）；右側為 Progress、Resolve (N)（Astroid 圖示 + 文字，見 §11.9）、Approve & Execute / HTML Report 等工作流按鈕。Plan 處於 Executing 或 Executed 時隱藏 Save。

Plan / Report 手動關聯（View options）： 在 Visual 模式下，已 Executed 的 Plan 與 Report 的 View options 會依關聯狀態顯示 Linked report: … / Linked plan: …（點擊開啟已配對檔案；名稱優先顯示別名）或 Link generated report / Link source plan（從尚未配對的候選中手動綁定）。Planning／Executing 的 Plan 不顯示此選項。手動 Link 只寫入 plan sidecar 的關聯 metadata，不會把 Plan 標成 Executed、也不會凍結 steps 或完成 Todo——正式執行完成仍須走 Execute 流程。

提示： 兩種模式的內容會即時同步。在 Visual 模式下新增的批註，在 Markdown 模式中會顯示為 <mark> HTML 標籤。

11.5.1 Plan / Report 程式碼顯示

本節功能僅適用於 Plan 與 Report 類型的 Markdown 文件，且需在 Visual 模式下使用。Raw Markdown 模式與 Chat 對話中的程式碼顯示不在此節範圍內。

單行 code（反引號）：

• 不會顯示裝飾性反引號字元。
• 以淺色底色 pill 呈現，搭配等寬字體，與正文區隔。

多行 fenced code（`````）：

• 以統一卡片外框呈現（工具列 + 程式碼區共用外觀），具淺色底色與邊框。
• 本版不提供語法高亮，僅單色文字與底色。

Code block 工具列（由左至右）：

收合狀態持久化： 在同一工作階段內，若你收合某個 code block 後切換至其他分頁再切回，收合狀態會保留（儲存於記憶體中的 tab-ui-state，不寫入專案檔）。

Agent 修改內容後： 若區塊內文變更，系統會視為新的 code block，預設重新展開。

唯讀狀態： Plan 處於 Executing、或文件已鎖定時，你仍可使用收合、Copy 與 Open in new SQL tab，不會因此解鎖正文編輯。

11.5.2 Report 表格與圖表工具

本節功能僅適用於 Report 類型的 Markdown 文件，且需在 Visual 模式下使用（Raw Markdown 模式不提供表格工具列）。Plan 文件中的表格不會出現下列工具。

懸停工具列： 將滑鼠移到 Report 內的表格上時，表格右上角會出現一組圖示按鈕（與表格一起浮動，長文捲動時仍對齊表格）。按鈕上沒有文字標籤；將滑鼠停在圖示上可看到說明。圖示順序（由左至右）：Bar chart → Line chart → Copy for Excel；若該表已綁定圖表，最右側為 Remove chart。

圖表區工具列： 已建立圖表後，圖表區塊右上角會出現另一組工具列。圖示順序（由左至右）：Show values → Bar chart → Line chart → Copy for Excel → Remove chart。其中 Show values / Hide values 可切換是否在圖上顯示數值標籤（預設關閉）；標籤文字與表格儲存格所見一致（含 %、千分位等），繪圖仍使用解析後的數值。

圖表持久化： 每張表的圖表綁定、hide_source_table 與 show_data_labels 設定存於專案 sidecar 檔（01_report.viz.json，與 Report 同名前綴），關閉並重新開啟 Report 仍會保留。應用程式不再提供全域「一次隱藏所有已建圖表的源表」開關。

貼到 Excel 的步驟：

1. 在 Report 分頁切換至 Visual。
2. 將滑鼠移到目標表格上，點擊 Copy for Excel 圖示。
3. 在 Excel 中選取要貼上的儲存格，按 Cmd/Ctrl + V 貼上。

源表已隱藏時： 隱藏源表後，懸停表格區域不會再出現浮動工具列；請改在圖表區塊右上角的同一組圖示中使用 Copy for Excel（資料仍來自該圖表對應的表格）。

限制與注意：

• 含合併儲存格（colspan / rowspan）的表格仍可複製，但系統會提示可能無法在 Excel 中完整還原版面；貼上後請自行檢查。
• 此功能與 SQL 查詢結果面板的 Export 不同：Export 會將查詢結果存成檔案；Copy for Excel 僅複製 Report 編輯器內的 Markdown 表格到剪貼簿。
• 若剪貼簿寫入失敗（權限或環境限制），會顯示錯誤提示。
• 切換 Dark / Light 主題後，已渲染圖表的軸線與標籤配色可能短暫與目前主題不符；重新開啟 Report 分頁或再次切換 Show values 可恢復正確配色。

提示： Report 在 Plan 執行中的唯讀狀態下仍可使用 Copy for Excel 與 Show values，不會修改 Markdown 正文。

11.6 Plan 狀態機

Plan 文件擁有四個狀態，透過工具列右側按鈕管理（Executed 與 Stopped 顯示為唯讀狀態標籤，非可點按鈕）：

一鍵核准並啟動 AI 執行： 當你在 Planning 狀態完成 Plan 的審閱後，點擊工具列的 Approve & Execute 按鈕，系統會自動將 Plan 狀態切換為 Executing，同時自動向 AI Agent 發送「開始執行」系統指令（對話中顯示為 Execute plan），驅動 Agent 根據 Plan 內容開始逐步執行分析——你不需要手動切到 AI 面板輸入指令。即使 AI 面板處於收起狀態，系統也會自動展開面板並開始執行。

中斷恢復（Continue）： 如果 AI Agent 在 Executing 過程中被中斷（例如會話超時、網路中斷、關閉 AI 面板後再開啟、或重新載入頁面），Plan 不會卡在 Executing 狀態無法繼續。此時：

• 工具列的按鈕會從「Executing...」旋轉動畫切換為 Continue 按鈕（左側）與下拉選單按鈕（右側），組成 split button。
• AI 狀態指示器會顯示「Paused — click Continue on plan」。
• 點擊 Continue 按鈕，系統會向 AI 發送與 Execute 不同的「續跑」系統指令（對話中顯示為 Continue plan），明確要求 Agent 根據對話歷史與已有快取結果從中斷處繼續，而不是從頭重新執行。

提示： 你不需要回到 Planning 狀態重新開始。Continue 機制確保 Plan 的 Executing 狀態可以安全地恢復，AI 會基於已完成的快取結果繼續後續步驟。

停止並重新規劃（Stop & Replan）： 若資料不可用、口徑或方向已改變，或不應繼續這次正式執行，請從 Executing Plan 的動作選單選 Stop & Replan…；Planning Plan 則可選 Stop Plan…。在確認視窗中必須填寫停止原因與目前部分成果，並選擇是否立即草擬替代 Plan。

• 停止後舊 Plan 會標為 Stopped，不會冒充已完成；其 SQL Steps、Todo 與已取得的正式 evidence 都會保留供審閱。
• 選擇建立替代 Plan 時，新的 Plan 會回到 Planning，並帶有與舊 Plan 的明確關係；請重新審閱後再 Approve & Execute。
• Stopped Plan 的 New Plan 可讓你稍後再開始替代分析。它不會偷偷恢復舊的 execution grant 或繼續跑已停止的工作。

注意： 在 Executing、Executed 與 Stopped 狀態下，Plan 正文無法手動修改。若需修改計畫，請以 Stop & Replan 開新 Plan，或對已完成交付物以批註提出小幅修訂。

正式收尾（Report）： Plan 處於 Executing 時，Agent 不能改寫既有 Report；正式 closeout 會以 add_report 新增 Report，並將該 Plan 標為 Executed。Executed 之後若需小幅修訂已產出的 Report，再以批註或明確要求處理。

執行進度（Progress）： 當 Plan 處於 Executing 或 Executed 時，工具列右側會出現 Progress 圖示按鈕。點擊後在工作區頂部顯示 Execution Progress 內嵌面板，包含兩個分頁：

• Todo：Agent 維護的執行待辦清單（唯讀），以 Circle / CircleCheck 圖示標示未完成與已完成項目。
• Steps：Query Step Ledger 鏡像的查詢步驟列表（唯讀）。一般 SQL 步驟可點 View SQL；正式分析中的 Source Run 步驟則顯示 View DAG，開啟該次執行的血緣／DAG 快照（非單一 SQL 文字）。

面板底部可拖拽調整高度（預設約 280px，範圍約 140–560px）；縮小視窗時顯示高度會自動適應，放大後恢復你調整過的高度。

當 Agent 更新 Todo 或新增查詢步驟時，Progress 按鈕會顯示紅點提示；開啟面板後紅點消失。進度資料儲存於 Plan 同名的 sidecar 檔（*.progress.json），不寫入 Plan 正文。

Analysis Lineage： 在 Plan 或 Report 工具列選 Analysis Lineage，可開啟由 Plan → Markdown Report → HTML Report 組成的脈絡圖。點選節點可查看狀態、正式 evidence 角色，以及已停止 Plan 的原因與部分成果，並直接開啟對應 artifact。若目前文件有未儲存修改，請先儲存：Lineage 只反映已保存的版本。手動建立、且沒有連結 Plan 的 Report 會明確顯示沒有 Plan evidence；歷史鏈過長時可選 Load more，不會把缺失或歧義的關係假裝成完整。

11.7 沉浸式批註功能

批註功能讓你在 Markdown 文件中對特定段落標記意見，這些意見會隨文件一同保存。

新增批註：

1. 在 Visual 模式下，用滑鼠選取（反白）你想批註的文字。
2. 選取完成後，文字末端會出現一個批註圖示按鈕，點擊它開啟批註浮窗。
3. 在浮窗的輸入框中撰寫你的批註內容。
4. 點擊 Enter 按鈕或按下 Cmd/Ctrl + Enter 送出批註。

送出後，被批註的文字會以半透明黃色高亮標示，右側會出現對應的批註卡片。批註內容會立即寫入同名的 sidecar 檔（*.annotations.json），並在 Markdown 正文中寫入 id-only <mark data-annotation-id="…"> 標籤；Cmd/Ctrl + S 會一併保存含 mark 的 Markdown 與 sidecar。

批註卡片面板：

當文件中存在批註時，畫面會自動分為左側編輯區與右側批註卡片面板。你可以拖曳中間的分隔線調整兩側寬度。

每張卡片的垂直位置會與左側對應原文對齊，包含表格儲存格內的批註（已修正舊版可能錯至面板頂部的問題）。當文件版面變更時——例如收合或展開 code block、圖表區塊高度變化——右側卡片位置會自動重新對齊。

每張卡片顯示批註的文字內容，並提供以下操作：

雙向 Hover 高亮：

• 當滑鼠移到被批註的文字上時，右側對應的卡片會高亮。
• 當滑鼠移到右側卡片上時，左側對應的文字高亮會加深。
• 多張卡片（尤其多筆 Resolved）垂直位置可能重疊；hover 左側原文或右側某張卡片時，該卡片會置頂並以不透明背景顯示，方便閱讀堆疊區塊。

這讓你能快速對照批註與原文的對應關係。

狀態用語： 主視窗批註卡片上的 Anchor outdated 與 Compare view 內的 orphaned 指同一狀態——正文 mark 遺失或無法對應時，批註 metadata 仍保留，需 Re-anchor（僅主視窗）或 Archive。

提示： 批註高亮由 Markdown 內 data-annotation-id mark 與編輯器 runtime map 共同驅動；sidecar 儲存 comment、status、history 等 metadata（不再寫入 UTF-16 anchor.span）。舊專案若仍含 data-comment inline mark，首次開啟時會自動將批註 metadata 遷移至 sidecar；正文 id-only mark 的完整保留仍在逐步收斂，遷移過程可能先寫入不含舊 inline tag 的乾淨 Markdown。

注意： 不支援對已有批註的文字範圍再疊加批註（巢狀批註）。如需修改批註範圍，請先刪除現有批註，再重新選取並新增。

11.8 AI 批註上下文（read_plan / read_report）

當你在 Plan / Report 中使用批註並呼叫 AI 時，Agent 透過 read_plan / read_report 取得：

• 磁碟正文 content（含 id-only <mark data-annotation-id> 標籤）
• 批註 sidecar annotations（含 open / resolved 狀態、quote、history；忽略過期的 anchor.span）
• open_annotation_count 與 annotation_summary（Action Required 任務清單）
• patch_guidance（resolve 模式 A/B 與 mark 邊界規則）

Resolve Comments 流程使用專用工具 resolve_annotations，會原子更新 sidecar 與 Markdown 正文（保留 mark），並透過 sync_tab_content 刷新編輯器。

11.9 一鍵批註處理（Resolve Comments）

當文件中有多條批註需要 AI 統一處理時，你不需要手動逐條與 AI 溝通——當文件中存在批註時，工具列右側會出現 Resolve (N) 按鈕（Astroid 圖示 + 文字，N 為待處理批註數；與右側 AI 面板圖示相同），一鍵驅動 AI 讀取所有批註並修改文件。

操作方式：

1. 在 Plan 或 Report 的 Markdown 分頁中，確認你已新增至少一條批註（此時工具列會顯示 Resolve (1) 等按鈕）。
2. 點擊 Resolve (N) 按鈕（hover 可見完整說明，例如「Resolve N comments with AI」）。
3. 系統會自動：

• 儲存當前文件（確保 AI 讀取的是最新版本）。
• 開啟 AI 面板（若已收起）。
• 向 AI 發送批註處理請求，AI 會根據文件中所有批註的修改意見一次性更新文件內容。

按鈕顯示與停用：

提示： Resolve Comments 與手動在 AI 對話中說「幫我處理批註」效果相同。AI 會透過 read_plan / read_report 讀取 sidecar 批註清單，再以 resolve_annotations 寫回。處理完成後文件與 sidecar 會自動更新；Resolve (N) 計數來自 sidecar 的 open 批註數。

設計說明： Plan / Report、批註、Execute 邊界見 Agent 時代的數據分析工作流 §三–§八。

11.10 Compare view（對照視窗）

Compare view 是獨立的桌面子視窗，用於唯讀並列檢視 Plan、Report 或持久 SQL 分頁，方便雙螢幕或寬螢幕工作流：在主視窗編輯與執行，在 Compare view 對照閱讀。Compare view 內不提供 Markdown 工具列、不可執行 SQL、不可新增或修改批註。

11.10.1 適用內容與入口

不支援： 臨時（Temp）SQL 分頁、快取表、MCP 資料表右鍵開啟。

子選單結構：

Open in compare view  ▸
  New compare view
  ─────────────────────
  Compare view 1
  Compare view 2

• New compare view：建立新的對照視窗（最多 2 個實例：Compare view 1、Compare view 2）。
• 若兩個實例皆已開啟且未關閉，New compare view 會停用；需先關閉其中一個 OS 視窗後才能再新建。
• 每個 Compare view 內最多 5 個 compare tab；已滿時對應項目停用，並提示 This compare view is full (5 tabs max).

若目標文件已在該 Compare view 中，系統會激活該 compare tab 並將 OS 視窗帶到前景。

11.10.2 視窗與分頁列

• 新開的 Compare view 1 預設出現在主顯示器右半；Compare view 2 在右半區域略為錯位，避免與 view 1 完全重疊。你可將視窗拖到第二塊螢幕。
• 視窗標題格式：Compare view 1 — {目前 active tab 標題}。
• 分頁列佈局（由左至右）：☰ 漢堡選單 → Refresh → 可橫向捲動的 compare tabs。
• 樣式與主視窗分頁列一致（高度、字體）。

☰ 漢堡選單：

• 第一項 Refresh all：重整該 Compare view 內所有 compare tab。
• 其後為 tab 列表：點選可切換 active tab；每列右側 × 可從 Compare view 移除（不關閉主視窗分頁）。

Refresh（左側圖示按鈕）：

• 僅重整目前 active 的 compare tab（tooltip：Refresh active tab）。
• 進行中圖示會旋轉；全部重整成功時可能顯示 Compare view refreshed.。

11.10.3 唯讀內容與批註

編輯、Execute、Save、新增批註、Resolve Comments 請回到主視窗對應分頁操作。

11.10.4 與主視窗的同步

• 若 compare tab 對應主視窗中仍開啟的同一分頁（mirror），主視窗的內容變更（含未儲存修改）會即時反映到 Compare view。
• 若你從側邊欄直接開啟、主視窗尚未開該檔，Compare view 以當下磁碟內容為準（standalone）；之後在主視窗開啟同一檔案後會自動升級為 mirror。
• 關閉主視窗上的某個分頁不會關閉 Compare view；該 compare tab 會保留關閉當下的內容快照，仍可繼續唯讀檢視。

來源狀態提示（Info icon）：

在 compare tab 標題旁，下列情況會顯示 Info 圖示（非主 TabBar 的 dirty 圓點）：

點 Refresh 或 Refresh all 可從磁碟重新載入。若主分頁有未儲存修改，Refresh 仍會更新 Compare view，但不會覆寫主視窗記憶體中的內容，並可能提示 Main tab has unsaved changes. Compare view refreshed from disk.。

11.10.5 Refresh 行為摘要

11.10.6 生命週期與限制

提示： Compare view 是「讀來對照、在主視窗改」——適合 Execute 時對照 Plan、驗收 Report 時對照口徑、或比較兩份持久 SQL 結果。分析師工作流範例見 Plan → Execute → Report。