# Mantis Excel Update

> Update a Mantis issue-tracking Excel workbook from an exported CSV while preserving the template, issue history, summary comparisons, and cell-comment rules. Conditionally update a release-staging sheet from read-only GitHub Release and PR evidence. Use for recurring Mantis CSV-to-Excel updates, not for creating a generic spreadsheet.

- Skill: `f00215a5/mantis-excel-update` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add f00215a5/mantis-excel-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/f00215a5/mantis-excel-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: f00215a5 (https://skillmd.com/u/f00215a5)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/f00215a5/mantis-excel-update

---


# Mantis Excel Update

將最新的 Mantis CSV 套用到既有問題單 Excel。預設是「更新既有問題單」：相同問題單更新最新欄位，CSV 新出現的問題單新增列，不把每次 CSV 重新製成無歷史的新清單。

依當下 runtime 可用的工具改寫「作用中工作簿副本」；Spreadsheets skill 可用時可依其 workbook authoring / verification 流程處理，但不是唯一 writer。無論實際使用何種工具，處理開始前都要讀取 CSV、現有工作簿、相關欄位與格式；不要以 CSV 欄位名稱或工作表名稱猜測對應關係。writer 的 API 回傳成功、記憶體 workbook model 或單純畫面預覽都不是交付證據；輸出後一律以本 skill 的獨立 raw OOXML validator 回讀 artifact，並依結果修正或回報限制。

## 範本與工作簿選擇

1. 使用者提供 Excel 範本時，該檔案及其儲存格備註是本次唯一的格式、工作表與規則基準；不要混用預設範本的格式或備註規則。
2. 使用者沒有提供範本時，使用此 skill 目錄內的 assets/template.xlsx。以 skill 根目錄解析此相對資產；不得參照桌面或其他外部固定路徑。
3. assets/template.xlsx 是唯讀的種子檔。先將它複製到本次使用者指定的工作／輸出位置，再於副本上更新；絕不可寫入、覆寫或把這個資產本身當成交付檔。
4. 正常工作以使用者提供的「既有問題單 Excel」為更新基礎；也應先建立工作副本。只有沒有既有更新檔時，才從選定範本的副本建立第一版。
5. 除非使用者明確要求覆寫，將更新結果另存成可追溯的新檔；不修改來源檔。實際交付只可回傳本次建立的輸出副本，不可回傳或取代內建範本。

預設範本有三張工作表：

| 工作表 | 預設處理 |
| --- | --- |
| 概要 | 更新統計區 E3:H17，以及已確認的規則儲存格。 |
| 問題單清單 | 以 A:K 欄位對應 Mantis CSV，最小化地更新問題單資料列或新增列。 |
| 過版調整 | 僅在 CSV 偵測到待過版問題單、且使用者確認要更新後，更新已確認的問題單與版號欄位；否則維持當前狀態。 |

## 初始化：首次回覆必問

對每個新的 CSV 更新任務，尚未取得確認前，不開始寫入、產出或覆寫 Excel。第一輪固定輸出以下表單；已知資料填入，未知資料要求使用者確認。只有使用者明確說「略過範圍確認並接受既有預設」時，才可略過。

> **Mantis CSV→Excel 更新範圍確認**
>
> 1. **範本**：是否提供本次 Excel 範本？若未提供，使用預設 Mantis 範本；若提供，會完全依該範本的格式與工作表配置更新。
> 2. **更新目標與問題單欄位**：請提供最新 CSV、要更新的 Excel，並確認問題單工作表及其「問題單號」欄位。CSV／Excel 欄位名稱不明確時，請確認對應；至少需要問題單號與狀態。
> 3. **替位符號規則**：偵測到新的 ${...} 替位符號時，會先轉成儲存格備註規則並請你確認，之後才計算；既有備註規則會沿用。是否有新的規則或要停用的規則？
> 4. **其他轉換規則**：CSV 找不到既有問題單時，預設狀態改為「不明」；請確認或指定替代狀態。也請確認「處理中／待過版／已解決」各自包含哪些原始狀態值。
>
> 請回覆「接受預設」或逐項補充／修改。

如果必要檔案、問題單號欄位、狀態欄位或輸出位置仍未確認，停止在確認階段，不猜測或修改資料。

## 更新規則

### 識別與欄位對應

- 將問題單號當文字處理，保留 Excel 顯示的前導零。比對時可用去除空白與前導零的正規化鍵（例如 0037745 與 37745），但不得因此改寫既有顯示值。
- 問題單號若重複、空白，或 CSV 內同一問題單有多筆且無法以更新時間安全判定最新一筆，先列出衝突並請使用者決定。
- 預設範本的問題單清單欄位是：編號、分配給、優先權、嚴重性、出現頻率、類別、回報日期、已更新、摘要、狀態、備註。僅更新已確認對應的欄位；沒有明確對應的 Excel 欄位、人工備註、色彩、資料驗證與公式一律保留。
- CSV 中不存在於 Excel 的問題單，新增到確認的問題單清單末端，並沿用相鄰資料列的格式、公式、驗證和條件格式。
- Excel 有、CSV 沒有的問題單，預設把已確認的狀態欄改為「不明」。這是獨立的「缺單轉不明」統計；不得把它混入一般 CSV 狀態更新。

### 工作表保留範圍

- 完整檢視工作簿的工作表、格式、公式、註解、篩選與隱藏狀態，再進行最小必要變更。寫入前建立本次 preflight：記錄工作表順序、作用中工作表／儲存格、確認的欄位 mapping、完整 issue ID 集合、每一個摘要公式及其預期快取值、保留工作表與其應維持的內容；以此建立 validator 所需 contract 與 preflight snapshot。若使用者未授權「過版調整」更新，snapshot 的 `preservation` 必須以更新前作用中工作簿副本做為 `source_workbook`，將「過版調整」列為 `protected_sheets`，並啟用版本化規則備註保留。使用預設範本時，還要確認來源與輸出各有 20 筆去重後的 `MANTIS_RULE_V1` 規則。無法完整建立這些確認資料時，不得修改工作簿。
- 「概要」可更新統計區與已確認的規則儲存格。
- 「問題單清單」只可更新已確認資料列的對應欄位或新增列；不可重建、清空或全表重設樣式。保留既有篩選與檢視狀態；既有 hidden 狀態只保留在非 populated issue rows。進入 post-save validator 前，所有 populated issue rows 必須有效可見：含 issue cells 的 explicit `<row>` 不得有 `hidden=true`，且有效列高必須大於零；有 row-level `ht` 時以它為準，否則才使用已宣告的 `sheetFormatPr.defaultRowHeight`。`sheetFormatPr.zeroHeight` 只預設隱藏未寫出／unused rows，不會使含 issue cells 的 explicit `<row>` 自動不可見。這是固定驗證契約，不可設定 contract 例外；任一 populated issue row 未達有效可見時，validator 必須回報 `visibility: FAIL`，而不是修補 artifact。
- 寫入後以當下工作表順序計算問題單工作表的 zero-based active tab；若 workbook view 或 sheet view 缺失則建立必要節點，將目標工作表設為 visible，並將其 `activeCell`、`sqref` 都設為 `A1`。目標外不可留下衝突的 `tabSelected`。如果既有 filter criteria 會遮住任何本次寫入問題單，只清除該 criteria、保留 filter range，並在交付回報記錄。這些是已確認目標可見性的 allowlist，不得藉此全表 unhide 或改動非目標工作表。
- 每個已確認概要公式都要同時保留 `<f>` 與依本次獨立計數計算的 numeric cached value，包括前次／本次異動比例；只設定開檔重算旗標或把公式替換為靜態值均不可接受。若 workbook runtime 無法產生並回讀該快取，停止交付並回報公式快取驗證失敗。
- 待過版／過版調整工作表預設維持既有結構、版面、公式、格式、註解、篩選與檢視狀態；只有依「待過版工作表與 GitHub 版號」流程取得使用者確認後，才可最小化地更新問題單列及其已確認的版號欄位。
- 使用者提供不同範本時，先確認對應的總表、問題單工作表及其餘保留工作表，再套用相同的最小變更原則。

## 待過版工作表與 GitHub 版號

完成 CSV 解析、問題單號比對與狀態正規化後，先計算本次分類為「待過版」的問題單。若為 0 筆，不詢問、不修改待過版工作表，繼續其餘更新。若至少有 1 筆，在任何待過版工作表寫入前，先詢問：

> 偵測到 N 筆待過版問題單。是否要更新本次 Excel 的待過版／過版調整工作表，並依 GitHub Release 的 PR 內容填入對應版號？

使用者選擇更新時，再請其提供本次要採用的 GitHub Release URL 或可明確定位 Release 的 repository、tag 與版本範圍；同時確認待過版工作表、問題單號欄，以及後端／前端版號欄位。預設範本的「過版調整」只是候選工作表，必須先檢視其現有欄位後才能寫入。使用者選擇不更新時，保留該工作表且完成 CSV、問題單清單與概要的其餘工作。

### Release 與 PR 證據

依 [GitHub Release／PR 唯讀流程](references/github-release-read-only.md) 讀取使用者指定的 Release 及其 PR。以 Release tag、PR title／內容、merge commit 與必要時的變更檔案作為對照證據；將可直接對應的後端或前端版號填入該問題單的已確認欄位。版本顯示格式必須沿用目標工作表，例如只有在既有欄位格式已確認時才移除 tag 後綴。

- 有直接 PR 證據才填版號；一張問題單若對應前後端 PR，分別填入相應欄位。
- 多個候選 PR、沒有相符 PR，或 Release 範圍不明時，不猜測版號。保留版號空白（或既有值），在可用備註欄記錄「待確認」及來源，並在完成回報列出。
- 新增或更新待過版列時，以正規化問題單號比對，保留顯示前導零、既有人工內容與列格式。不要重建整張工作表。
- GitHub 資料未能取得時，若使用者已確認更新待過版工作表，仍可依 CSV 更新／新增已確認問題單列，但不得填造版號；明確標示未填原因，並繼續完成其他可執行的工作表更新。

## 概要統計

在套用 CSV 前，以既有問題單清單建立「前次」快照；更新後再產生「本次」統計。預設範本的概要區 E3:H17 是一組可由備註規則重跑的摘要：

| 分類 | 預設定義 |
| --- | --- |
| 處理中 | 已確認不是待過版、已解決、已結束或不明的進行中狀態 |
| 待過版 | 使用者確認的待過版狀態值 |
| 已解決 | 已解決與已結束，兩者合併為結案狀態 |
| 不明 | CSV 找不到既有問題單後所設定的預設狀態 |

狀態比較表位於 E3:H7：E 欄是分類、F 欄是更新前快照、G 欄是問題單清單的目前公式計數、H 欄是異動比例。前次與本次用整數問題單數表示；異動比例以 (本次－前次)／前次 計算，前次為零時要避免除以零。

更新摘要位於 E9:F17，依序為：本次 CSV 筆數、問題單總數、新增問題單數、更新既有問題單數、缺單轉不明數、未變更、更新時間、來源 CSV。問題單總數是工作表公式；其餘結果由本次更新的已確認差異寫入。

版本化備註規則與 placeholder 的實際資料只存在於本次「作用中工作簿副本」的儲存格備註；skill 檔案不保存任何工作簿的規則 payload、公式、欄位名稱或統計設定。每次更新先從作用中工作簿探索有效備註：formula 規則重建公式，snapshot 規則在指定時點寫入值。使用預設範本時，沿用其副本中的備註；使用者提供範本時，只沿用或新增該範本副本中已存在或經本次確認的新規則。不可只依賴目前顯示值，或只將規則硬編碼在更新程式中。

狀態值的實際對應以初始化確認為準；如果使用者變更狀態對應，先在作用中工作簿副本更新相關備註規則與公式，再進行更新。無法分類的值要列為待確認，而不是靜默併入「處理中」。

可選的實用統計（僅在範本已有位置或使用者同意後加入）是：分配人員分布、優先級分布、待過版清單、未完成天數與最近更新趨勢。不要為此新增未經同意的工作表。

## 替位符號與備註規則

替位符號與備註是工作簿內容，不是 skill 設定。只從本次作用中工作簿副本讀取；不得在 SKILL.md、references/ 或其他 skill 檔案快取、複製或預先設定任何實際規則資料。

當作用中工作簿的儲存格完整文字是 ${...} 時，視為待設定規則，不把它當 Excel 公式或任意程式碼執行。

1. 初次偵測時，擷取其自然語言要求，依 [替位符號規則](references/placeholder-rules.md) 轉成受限、可重複執行的規格，並在初始化確認中請使用者核准。
2. 核准後，僅在作用中工作簿副本的該儲存格備註寫入版本化規則規格。保留原有人工備註；必要時新增回覆或以清楚的區段附加，而非覆寫。
3. 將儲存格顯示值更新為規則的計算結果。規則的來源工作表、問題單號欄與狀態分類必須明確記錄。
4. 後續更新以作用中工作簿備註中的版本化規則為準，即使 ${...} 已被計算值取代也要重新套用。
5. 不支援、歧義或高風險的規則保留原替位符號，列出原因並要求使用者確認；不推測。

## 驗證與完成回報

輸出工作簿完成 export/save 後，先確認 workbook writer 的 handle 已釋放；只有 writer 位於獨立 process 時，才需等待該 process 結束。接著必須對已儲存的輸出路徑執行獨立 artifact 驗證；不得以 writer 記憶體中的 workbook 物件代替磁碟回讀：

```bash
python3 scripts/validate_artifact.py "<artifact.xlsx>" --contract "<contract.json>" --renderer auto --visual-verdict not-run
```

只有在要建立或檢視 contract，或要解讀 validator 的 report、outcome 與 exit code 時，才讀 [artifact 驗證契約與報告](references/artifact-validation.md)。

資料正確性、可見性、公式快取三層一律由 raw OOXML validator 獨立驗證；這三層不依賴視覺化能力。若環境有 Spreadsheets 的工作簿檢視能力或其他可實際檢視輸出的 renderer，完成逐工作表視覺檢查後才可將同一份 artifact 以 `--visual-verdict pass` 重跑 validator。不得因為成功產出 PDF，或僅因為環境宣稱有 renderer，就填入 `pass`。無視覺化能力時保留 `not-run`，讓 validator 回傳 `PARTIAL`；這不是資料驗證失敗，也不是完整成功。

完成前，依可用能力檢查並確認：

- 每一筆 CSV 問題單都正確更新或新增，且既有不在 CSV 的問題單依確認規則轉為不明。
- 問題單號沒有因數字格式而失去前導零；沒有未處理的重複鍵。
- 問題單清單的非目標內容、公式、格式、註解、篩選與檢視狀態，以及未經確認的過版調整工作表內容均未被非必要改動。
- 概要的前次／本次／異動比例能與更新前後清單的獨立計數相互核對；公式沒有錯誤。
- 當使用預設範本或使用者確認相同概要版面時，匯出後先檢查「概要」的浮動繪圖物件與其錨點。空白、白底黑框、覆蓋 A1:J6、且實際尺寸與錨點明顯不符的文字方塊是已知異常特徵；名稱為 Text Box 21 時尤其須排查。
- 僅在確認該浮動物件不是使用者有意保留的內容、且符合上述異常特徵時，才以最小 OOXML 變更移除該圖形及其 drawing 關聯。不可藉此刪除其他圖形、圖表、圖片或註解物件。
- 移除前後都要核對摘要 sheetData、公式與所有既有儲存格註解未變；預設範本輸出還要確認 20 筆版本化規則註解仍在。E3:H3 與 E9 的 12 pt 字級可作交叉檢核，但 styleId 重編本身不代表字型異常，也不得因此重設字型。
- 若已確認 Text Box 21 是異常物件，將其名稱列入 preflight `preservation.forbidden_drawing_names`；唯讀 validator 必須在輸出所有 drawing parts 中確認它已不存在。不可只憑名稱推定未確認的使用者圖形可刪除。
- 替位符號的可執行規則都已寫入備註，且其值與問題單清單一致。
- 若使用者選擇更新待過版工作表，每個新填版號都有本次指定 Release／PR 的唯讀證據；無法對應者未被猜測填入，且已列入回報。

完整驗證的完成條件是上述檢查均完成，且 validator `outcome` 為 `PASS`。`PARTIAL` 表示資料正確性、可見性與公式快取均已通過獨立回讀，但 renderer 或視覺檢查未完成；必須明示此限制，不得稱為完整成功。`FAIL` 時依 report 修正輸出流程，重新儲存、關閉 writer 後再驗證；validator 本身不修復工作簿。

交付時分開回報：新增問題單數、更新既有問題單數、缺單轉不明數，以及目前不明總數；不能把「缺單轉不明」併進一般更新數。若偵測到待過版問題單，也回報其數量、使用者是否選擇更新待過版工作表、寫入／新增的列數、成功填入的後端／前端版號數、待確認數，以及採用的 GitHub 資料來源或無法取得原因。若使用者沒有指定缺單規則，明確說明採用預設「不明」，並列出或附上受影響問題單的數量。