ropimen/claude-skill-kpi-calculator

KPI 計算機

將一個或多個 CSV/TSV 檔案與簡短指令，轉換為一組經過驗證的 KPI，每個 KPI 都包含數值、單位、方程式、含義和基礎標籤。沒有固定的欄位清單：KPI 是根據資料和指令所描述的內容而設計的。附在資料旁邊的論文、報告或先前結果，會貢獻其 KPI，並應用於使用者的資料，同時標註其來源。

以下 <skill_dir> 表示包含此檔案的資料夾。從工作資料夾（請參閱「輸出位置」）執行指令，例如 python <skill_dir>/scripts/<name>.py，並使用絕對路徑傳遞資料檔案。

如果找不到 python（或開啟了 Microsoft Store），請在 Windows 上使用 py -3，在其他環境中使用 python3。請在開始時用 python --version 檢查一次。

嚴格規則

1. 每個數字都來自對檔案執行的程式碼。 絕不估計、憑目測四捨五入，或在散文敘述中陳述 results.json 中沒有的數值。
2. 排除的 KPI 永不計算，且除了一行「應您要求排除」的說明外，不會出現在任何地方。
3. 每個假設都需說明，記錄在「我的理解」中（模式、角色、單位、內插法、時區、日/月順序、使用的預設值）。
4. 每次執行最多問一個問題，且僅在錯誤猜測會改變結果時才問（請參閱 references/role-mapping.md 的「何時提問」）。否則，陳述所採用的解讀方式並繼續執行。
5. 每個 KPI 都是一個規格，在 kpi_specs.json 中由基本元件構成。每個都標記為 basis: established（該領域的標準）或 derived（從基本原理建構）。
6. 跨期間的比率是總和的比率，而不是比率的平均值，除非 KPI 另有定義。
7. 不規則時間是真實時間。 絕不將資料列視為時間步長；需對時間戳記進行積分和平均，並對每個欄位進行內插。
8. 驗證失敗會重新檢查一次（解析筆記 → 對應 → 規格），然後報告並附上警告，絕不隱藏。
9. 領域知識僅存在於 Markdown 中。 絕不將領域特定的邏輯加入指令碼。
10. 參考文獻中的數值僅為引用。 論文或先前結果中報告的數字只會放入規格的 reference.reported 中；它們永遠不會作為計算的輸入，也不會被呈現為使用者的結果。

輸出位置

在步驟 1 決定此項，並記錄在 request.json → output_dir 中。

情況	工作資料夾（所有 JSON 檔案、指令碼的當前工作目錄）	交付物
使用者指定了資料夾（「將結果儲存在 D:/reports/line3」）	該資料夾（建立它）	同一資料夾
Claude 應用程式（claude.ai / 桌面聊天，/mnt/user-data/outputs/ 存在）	當前目錄	複製到 /mnt/user-data/outputs/：這些會顯示為可下載的檔案
Claude Code，未指定資料夾	當前目錄下的 kpi_output/	同一資料夾

交付物包括 report.md、kpi_results.csv、kpi_run.py，以及當產生時還有 kpi_chart.png、kpi_adhoc.py 和一個提供的領域套件。工作檔案（request.json、profile.json、mapping.json、kpi_specs.json、results.json）保留在工作資料夾中以供稽核，僅在使用者要求時才分享。

將交付物交給使用者，以便他們可以儲存在任何地方：

• Claude 應用程式：除了可下載的檔案外，將完成的報告顯示為 Markdown 文件成品，以便可以獨立閱讀、複製或下載。
• Claude Code：將每個交付物列為其路徑的連結。當主機提供將檔案傳送給使用者的工具時（例如桌面應用程式中的檔案卡片），也透過該工具傳送交付物。
• 除非使用者要求，否則絕不在工作資料夾和交付物位置之外寫入。

若要稍後重新執行 kpi_run.py，請將其與輸入檔案放在同一個資料夾中。

優先使用指令碼，僅將臨時腳本作為備案

始終執行下列指令碼。僅在以下情況編寫您自己的 pandas 程式碼：

• 指令碼因您無法藉由修正 profile.json、mapping.json 或規格（例如 profile_csv.py 無法解析檔案）來修復的錯誤而退出，或
• KPI 需要一個沒有基本元件或表達式涵蓋的操作（check_spec.py 回報 unknown_op）。

接著：

1. 將程式碼放入工作目錄中的 kpi_adhoc.py，使用 profile.json（或 scripts/lib/io.py load）中的解析設定載入資料，並保持其可獨立執行。
2. 在 run_specs.py 寫入檔案後，將每個臨時 KPI 加入 results.json → kpis，並帶有 schemas/results.schema.json 的每個欄位和 "computed_by": "ad_hoc"。絕不更改引擎計算的值。
3. 報告中用 † 標記這些 KPI，並指向 kpi_adhoc.py。

絕不在使用者或資料衍生的字串上使用 eval/exec，即使是臨時腳本也不行。

工作流程

按順序執行八個步驟。僅在步驟需要時才讀取參考檔案。

步驟 1 [Claude] 解析請求 → request.json

讀取 references/request-parsing.md。提取 field、mode、focus、include、exclude、custom、params、max_kpis、output_dir。

• 提示中附加或提及的參考文獻（論文、報告、標準、先前結果）：讀取 references/reference-documents.md，將它們與資料檔案區分開來，完整讀取每一個，並將其 KPI 記錄在 request.json → references 中（id、名稱、定義、方程式、位置、報告數值）。只有資料檔案會進入步驟 2。
• Excel 輸入：先將每個工作表轉換為自己的 CSV（pandas.read_excel(sheet_name=None)），命名為 <book>__<sheet>.csv。
• 同時被包含和排除的 KPI → 這是本次執行的唯一問題。在得到答案之前，不為該 KPI 計算任何內容。

步驟 2 [指令碼] 載入並剖析 → profile.json

python <skill_dir>/scripts/profile_csv.py FILE [FILE ...] --out profile.json

檢查每個欄位的類型、單位提示和解析筆記。如果一個應該是數值的欄位變成了 text，請查看其樣本並修正解析後再繼續。

步驟 3 [指令碼] 偵測時間和收集模式 → profile.json（時間部分）

python <skill_dir>/scripts/detect_time.py --profile profile.json [--tz <IANA tz>] --out profile.json

讀取 references/collection-patterns.md。此指令碼會提出一個模式及其 evidence 和其他合理的 candidates，加上 entity_column（當時間戳記在分組欄位中重複時）、frequency（pandas 別名，如 D、B、h、MS）、gaps、duplicates 和 tz。使用使用者的描述確認或覆寫模式和實體。如果 ambiguous_dayfirst 為 true，請說明假設（或者提問，如果兩種解讀都會改變 KPI 值且沒有其他待處理的問題）。當使用者指定了本機時間戳記的時區時，傳遞 --tz。

步驟 4 [Claude] 對應欄位角色 → mapping.json

讀取 references/role-mapping.md。為每個欄位分配角色、物理量、單位和內插法；記錄實體、配對、聯結、重塑、重新取樣和參數。任何語言的標題都根據其意義讀取；保留原始名稱。

然後撰寫 mapping.json → sensitivity：針對每個本可以合理做出不同判斷的判斷點（內插法、不明確的狀態類別、日/月順序、計劃性停機時間、假設的單位或參數），建立一個變體。引擎會在每個變體下重新執行每個 KPI，並報告一個低-高範圍，以便使用者了解哪些數字依賴於哪些假設。規則和補丁格式在 references/role-mapping.md 的「敏感度變體」中。

步驟 5 [Claude] 設計並選擇 KPI → kpi_specs.json

讀取 references/kpi-discovery.md（方法）和 references/kpi-spec.md（格式、基本元件、語法）。如果 references/fields/ 有與該領域匹配的套件，也請讀取它；它提供資訊但絕不限制。

選擇順序：必要（include）和 custom 優先 → 來自 references 的 KPI（規格 source: reference 且帶有 reference 區塊，請參閱 references/reference-documents.md）→ 絕不使用 exclude → 根據與 focus 的相關性、已建立的優先於衍生的、無近似重複 → 將 Claude 自己挑選的 KPI 上限設為 max_kpis（預設 12）。必要、自訂和參考 KPI 絕不被刪除；資料無法支援的參考 KPI 不會產生規格，並列在「自動未計算項目」下。

然後檢查規格：

python <skill_dir>/scripts/check_spec.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json

退出代碼 0 = 正常。退出代碼 1 = 在 stdout 上輸出錯誤的 JSON：修正規格或對應並重新執行。未知單位會以警告形式返回：如果一個變更了結果，它可能是本次執行的問題。

步驟 6–7 [指令碼] 計算並驗證 → results.json、kpi_run.py

python <skill_dir>/scripts/run_specs.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json --out results.json --script-out kpi_run.py

每個規格按實體（群組）執行，並根據其 overall 規則加上一個總體值。失敗的規格或群組會變成 not_computed 並附上原因；執行會繼續。stdout 摘要會列出每個 validation: 警告。

同一執行也：

• 針對每個敏感度變體重新執行所有 KPI，並在每個 KPI 上儲存 sensitivity: {low, high, variants}；
• 將每個 KPI 與其參考文獻報告的值進行比較，並轉換為 KPI 的單位（comparison：差異、相對差異、根據方向的好/壞、報告值是否落在敏感度範圍內）；
• 寫入 data_health：每個已對應的數值欄位，包含缺失比例、最長常數序列、穩健離群值和不可能值（負數計數、超過 100 的百分比、低於絕對零度），以及正規時間序列的時間覆蓋率。

如果任何 KPI 帶有驗證警告：重新檢查一次解析筆記（步驟 2）、對應（步驟 4）和規格（步驟 5），從您更改的最早步驟開始重新執行，然後如果仍然失敗，則報告並附上警告。

執行後，您只能編輯 results.json 以對 not_computed 項目（始終針對來自參考文獻和 include 的 KPI）加入 enable 文字（哪些資料或參數會使該 KPI 可計算），以及根據上述備案，加入臨時 KPI 記錄。kpi_run.py 嵌入了輸入的雜湊值、設定檔、對應、規格和技能的程式碼；它可以無需技能而重新產生 results.json（作為 results_rerun.json）。

步驟 8 [指令碼 + Claude] 報告 → report.md、kpi_results.csv、可選圖表

python <skill_dir>/scripts/report.py --results results.json --request request.json \
       --mapping mapping.json --profile profile.json \
       --out-md report.md --out-csv kpi_results.csv [--chart kpi_chart.png]

僅當重點涉及隨時間的變化且存在時間欄位時才傳遞 --chart；它會繪製最多兩個具有 per_period 值的 KPI（為這些 KPI 提供 per_period 範圍）。如果 results.json 中存在被排除的 KPI，指令碼將拒絕執行。

讀取 references/report-format.md，然後取代指令碼在 stdout 上列出的佔位符，就地編輯 report.md：

• {{FINDINGS}}：2-5 個句子回答重點，引用 results.json 中的 KPI 數值及其單位。不引入新數字。命名那些敏感度範圍較廣的 KPI（以及影響它們的解讀方式）、與參考文獻的比較（使用計算出的差異和結論，以及可比性限制），以及關鍵 KPI 所使用的欄位上的任何資料健康標記。
• {{READING:<kpi_id>}}：每個 KPI 一個句子：根據其方向和已知的典型範圍，判斷是好是壞。

報告中的其他所有內容（名稱、方程式、含義、數字）都來自 results.json，不會被重寫。在聊天中顯示完成的 report.md，並按照「輸出位置」中的說明交付檔案。

輸出檢查清單

在回答之前，確認所有這些事項：

• 聊天報告包含八個章節，順序如下：我的理解 · KPI 概述 · KPI 詳細資訊 · 發現 · 未計算項目 · 應您要求排除的項目 · 資料問題 · 重現。
• 每個 KPI 都顯示數值、單位、方向、基礎標籤、來源、LaTeX 方程式 和 純文字方程式，符號對應到原始欄位名稱並附有 n、含義、解讀方式、警告。
• 每個必要的 KPI 要不是已被計算，就是列在「未計算項目」下，並附上哪些資料或參數可以啟用它。
• 排除的 KPI 除了那行「排除」資訊外，不會出現在任何地方（也檢查 CSV）。
• 收集模式和每個假設都已說明；每個判斷點要不是已提問，就是已說明並作為敏感度變體進行測試。
• 資料健康表格存在；發現中提及了關鍵 KPI 輸入的標記。
• 在參考文獻中找到的每個 KPI 要不是已被計算（並顯示引用、位置、定義和改編方式），就是列在「未計算項目」下，並附上哪些資料可以啟用它；報告的數值標記為引用。
• kpi_results.csv（UTF-8 with BOM）和 kpi_run.py 已寫入，且每個交付物都已按照「輸出位置」中的說明交給使用者（在 Claude 應用程式中：下載 + 報告成品；在 Claude Code 中：路徑和檔案卡片）。
• 僅當重點與隨時間的變化有關時才包含圖表。
• 在 references/fields/ 中沒有對應套件的領域：提供一個基於本次執行所用 KPI 建構的領域套件，作為遵循 references/fields/_template.md 的獨立 Markdown 檔案，供使用者審查和新增。不要將其寫入技能資料夾。

非目標

不進行預測或模型建構（該技能評估它所獲得的預測值）。不處理即時資料來源或資料庫。不提供投資、醫療或工程建議：報告指標及其所指示的內容。不進行貨幣轉換：混合貨幣會被標記並按貨幣計算。

預設值（無需詢問即可使用，使用時需說明）

設定	預設值
無風險利率	0
年化因子	僅交易日 252，日曆日 365，每週 52，每月 12，每季 4，每小時 8760
MASE 季節週期	每小時 24，每日 7，每週 52，每月 12，每季 4，否則為 1
不規則閾值	間隔 CV > 0.5
間隔閾值	3 × 中位數間隔
時間欄位解析率	≥ 95%
剖析抽樣	> 1,000,000 列 → 200,000 列樣本（時間欄位始終完整讀取）