指標包
您的任務
您被要求將新創公司的營收數據轉換為基金分析師最先閱讀的數字：
MRR、同群分析、NRR – 全部放在一張簡報上。這些數字來自 metrics.py，絕非來自您的推測。
您選擇輸入、執行輔助程式、讀取其 CSV 檔案，並在這些數字周圍撰寫文字說明。
輸入 輔助程式 (metrics.py) 您
───── ─────────────────── ───
updates/ (a) ──┐
客戶匯出 (b) ──┼──► mrr.csv cohorts.csv ──► metrics.md (純文字說明)
合約登記簿 (c) ┘ nrr.csv excluded.csv metrics-slide.png (一張簡報)
產出檔案位於目前工作目錄的 <company-slug>/metrics-pack/ 資料夾中：
metrics.md– 說明文件。開頭為「用白話文來說明。」mrr.csv,cohorts.csv,nrr.csv（以及合約登記簿輸入的excluded.csv）– 由輔助程式產生，您不需修改。metrics-slide.png– 一張 16:9 的簡報。
本檔案中使用的縮寫：MRR = 每月經常性收入；NRR = 淨收入留存率；
CSV = 逗號分隔值檔案；PNG = 圖片檔案；ISO = 國際日期格式
（YYYY-MM-DD，或月份用 YYYY-MM）；EUR = 歐元；USD = 美元；--as-of = 輔助程式中用以指定最後一個已開帳月份的選項。
輸入
來自 $ARGUMENTS 或對話：一家公司，以及一個選擇性檔案。三種輸入類型，依偏好順序如下：
| 輸入 | 說明 | 如何傳入輔助程式 |
|---|---|---|
| (b) 客戶匯出 | CSV 檔案 customer_id,month,revenue，月份格式為 YYYY-MM | --revenue <csv> |
| (c) 合約登記簿 | 帶有標題列 Client, Contract value, Start month, Term (months) 的 CSV 檔案；標題列以上的行會被略過；月份格式如 May-26；數值格式如 "1,550,000" | --contracts <csv> |
(a) <company-slug>/updates/ | 包含營收行的每月更新檔案，無客戶詳細資訊 | 如同 revenue-chart 讀取（該處的第 2 步），寫入 customer_id,month,revenue，客戶為 total，然後使用 --revenue |
對於輸入 (a)，沒有客戶區分。輔助程式將會寫入只有標題列的 cohorts.csv 和 nrr.csv，並將 mrr.csv 中的 new、expansion、contraction 和 churned 欄位留空，因為對於單一客戶而言，這些欄位只會重述總增長。忽略這些欄位，不顯示熱力圖，並印出「12 個月 NRR：無法計算」（原因：無客戶詳細資訊）。這同樣適用於任何只有單一客戶 ID 的 --revenue 檔案。
如果公司名稱有歧義（兩家公司同名），請先詢問是哪一家，再開始讀取任何資料。
第 1 步 – 公司資訊卡與輸入
公司資訊卡
<company-slug>/company-profile.md – 首先讀取。如果檔案不存在，則建立它。如果某個欄位為空白，且您得知其資訊，請填入該值，並更新 updated / updated_by。絕不要覆蓋已填入的欄位：如果您發現不同的值，請在 ## Conflicts 區段新增一行，同時提供兩個值及其來源。資訊卡結尾為 ## Conflicts 區段（如果不存在則建立），其表格標題必須為 | Field | Card value | Card source | New value | New source | Found by | Date |。
| 欄位 | 允許的值 |
|---|---|
| 為客戶完成的工作 | 一句話，用公司自己的話來說，附上引號和 URL |
| 誰付錢 | 自由文字 |
| 商業模式 | B2B · B2C · B2G |
| 營收模式 | subscription · transaction · ads · one-off · n.a. |
| 市場 | 僅限一個：Fintech & insurance · Health & bio · Commerce & retail · Logistics & supply chain · AI & data infrastructure · Enterprise software · Cybersecurity · Legal, compliance & governance · Sales & marketing · HR & talent · Education · Media, gaming & entertainment · Real estate & construction · Energy, climate & agriculture · Industrial & robotics · Consumer lifestyle & services · Other |
| 垂直領域 | 自由文字 |
| 階段 | pre-seed · seed · Series A · Series B+ · n.a. |
| 地理位置 | 總部所在國家；銷售國家 |
| 正在進行的募資輪 | 金額 + 貨幣 + 工具，或「未說明」 |
| 可用指標 | 位置（updates/、匯出檔案），或「無」 |
前置中繼資料：company、slug、website、updated（ISO 日期）、updated_by（技能名稱）。
資訊卡的表格有第三欄 Source，每個欄位都必須填入。
從資訊卡獲取公司名稱、商業模式、營收模式和地理位置；地理位置有助於推測預期的貨幣。將「可用指標」填入您使用的檔案。如果營收模式不是 subscription，請在說明文件中說明 MRR 是基於經常性收入的假設。
找到輸入（上表所述）並將其複製到 <company-slug>/metrics-pack/input/ 中，以便執行過程可供審計。除非擁有者同意公開，否則絕不提交或發布客戶層級的檔案。**貨幣：**從檔案中獲取；合約登記簿通常不註明貨幣。如果沒有註明，請在所有地方寫「未註明貨幣」，且絕不要自行選擇一種貨幣。
今天日期與 --as-of。 --as-of 是最後一個實際已開帳的月份 – 通常是從今天日期（ISO）算起的當月。此後的月份為 已簽約：已簽署，但尚未開帳。
第 2 步 – 執行輔助程式
使用 /usr/bin/python3 或任何 Python 3.9+ 版本；metrics.py 只需標準函式庫，且不進行任何網路呼叫。它位於此檔案的旁邊（skills/metrics-pack/metrics.py；在已安裝的外掛中，路徑為 ${CLAUDE_PLUGIN_ROOT}/skills/metrics-pack/metrics.py）。
python3 <path>/metrics.py --contracts <register.csv> --out-dir <company-slug>/metrics-pack \
--as-of 2026-11 --min-term 3
python3 <path>/metrics.py --revenue <export.csv> --out-dir <company-slug>/metrics-pack \
--as-of 2026-11
其寫入的檔案：
| 檔案 | 欄位 | 意義 |
|---|---|---|
mrr.csv | month, mrr, new, expansion, contraction, churned, status | 每個日曆月一行；status 在 --as-of 之前（含）為 billed，之後為 contracted |
cohorts.csv | cohort, month_offset, revenue | cohort = 客戶首次產生營收的月份；offset = 自該月起的經過月數 |
nrr.csv | start_month, months, nrr | 每個起始月份，若可根據已開帳月份計算（--as-of 之後的月份一律不計），則提供其 12 個月 NRR；若無法計算，則僅有標題列。對於單一客戶的匯出檔案，以及沒有記錄續約的合約登記簿，也僅有標題列；對於登記簿，僅列出某些客戶有記錄續約的起始月份（規則見第 2 步） |
excluded.csv | client, value, start, term | 期限短於 --min-term 個月（預設為 3）的合約 |
如果輔助程式停止並顯示 error:，它會指出錯誤的欄位或值。請在來源處修正輸入（或詢問擁有者） – 絕不要繞過它進行編輯。
輔助程式的假設（請在說明文件中逐條說明）：
- 合約價值是整個期限的總額，平均分攤：每個月價值 ÷ 期限，從起始月份開始。如果擁有者說是每月或每年，請停止詢問 – 答案會改變所有數字。
- 只有當期限至少為
--min-term個月時，合約才算經常性。期限較短的為 非經常性：回報於excluded.csv，不計入 MRR。 - 除非有新的一行記錄，否則不會有續約。當合約期限結束時，輔助程式會將離開的營收顯示為
churned。對於合約登記簿，這是 合約結束，而非已證明的流失 – 對於每個此類月份都必須如此說明。 - 合約登記簿記錄的是合約，而非續約。 合約結束被解讀為營收損失，因此輔助程式僅針對某些客戶有記錄續約的起始月份，從登記簿計算
nrr.csv。規則：續約是同一客戶的後續經常性合約（期限至少為--min-term），其起始月份至少比先前經常性合約的結束月份晚一個月（結束月份 = 起始月份 + 期限 - 1；因此，在結束後的下個月開始的無縫接軌合約視為續約，也允許有間隔）。與前一合約重疊的第二份合約（追加銷售或附加服務）不算續約。如果沒有任何客戶有續約，則nrr.csv僅有標題列，答案為「無法計算」。如果有些客戶有續約，則該數字僅反映 登記簿所記錄的續約，說明文件和簡報都必須如此說明。 - 停止服務後又重新回來的客戶，將再次被視為
new。
第 3 步 – 讀取輸出
使用 csv 模組讀取 CSV 檔案。您撰寫的每個數字都來自這些檔案。不要在文字中進行計算；如果您需要 CSV 檔案中沒有的數字（例如某個佔比），請使用命令列計算，並引用命令的輸出。
- MRR。 最後一個已開帳月份的
mrr；峰值月份及其status；已開帳與已簽約的拆分。指出數據中的第一個和最後一個月份。 - 合約期滿流失。 在最後一個合約起始月份之後的月份，營收只會流失，因為數據中沒有續約。將這些月份標記為無續約合約的合約期滿流失，絕不要標記為流失。
- 同群分析。 統計至少有兩個月已開帳營收的同群組。簡報上的熱力圖至少需要兩個這樣的同群組；否則跳過並說明原因。
- NRR。 首先檢查輸入。對於輸入 (a) 或單一客戶的匯出，請忽略
nrr.csv、cohorts.csv和異動欄位：答案為「無法計算」。否則，如果nrr.csv有數據行，請引用它們；如果是合約登記簿，請加上「僅統計登記簿中記錄的續約」。如果它只有標題列，答案為 「12 個月 NRR 無法計算」：沒有任何客戶的營收月份距離其起始月份有十二個月。永遠不要估算它，也不要從更短的時間窗口填入。用一句話說明原因（例如「登記簿中的每份合約都開始於 2026 年，因此沒有任何一份已營運十二個月並完成續約」）。 - 被排除的合約。 被排除的合約數量、其總價值以及排除它們的規則。
第 4 步 – metrics-slide.png
需要 matplotlib 和 numpy（python3 -c "import matplotlib, numpy"）。如果缺少，請先詢問再安裝任何套件；最乾淨的方法是使用一次性虛擬環境。圖表範本基於 revenue-chart（深色主題、標籤碰撞檢查）。
一張 16:9 的簡報，佈局如下：
┌─────────────────────────────────────────────────────────────┐
│ <公司名稱> – 營收指標 截至 <ISO 日期> │
├──────────────────────────────┬──────────────────────────────┤
│ MRR 線圖：實線 = 已開帳， │ 同群熱力圖（僅已開帳月份 │
│ 虛線 + 陰影區 = 已簽約 │ 的月份 0 百分比）– 或 │
│ │ 若無熱力圖則顯示 NRR 面板 │
├──────────────────────────────┴──────────────────────────────┤
│ NRR：<數值> 或