指標定義工作流
建立商業指標定義知識庫
把核准的 KPI 規格整理成有來源的資料字典，保留公式文字、粒度、維度、排除條件、負責人、來源修訂與複核狀態。
關於這篇指南
工作流程
需要為人員與 AI agent 解決 KPI 定義衝突的資料、分析、產品、財務與營運團隊
8 分鐘閱讀
01
從核准的指標規格開始，不從儀表板或推測公式開始。
02
把公式文字、粒度、維度、排除條件、負責人與來源修訂放在同一筆紀錄。
03
明確取代過期定義，不讓 AI agent 把衝突版本混成一個答案。
完整示範
建立業務指標定義知識庫
這是三個檔案的虛構指標練習：判斷 C-104 是否計入，檢查儀表板草稿，保留退款規則的未知狀態。
試做這個任務
只根據三個來源檔，定義每週活躍客戶數，判斷 C-104，並審查儀表板草稿。保留所有未知資訊，每個結論都用 [[filename]] 引用。
預期推理
依第 1 版定義，C-104 在週二行動時已付費且尚未取消，因此應計入；週四取消不會移除該週活動。草稿在週末篩選取消日期而錯誤排除，退款處理仍未知。
為什麼要保持這些內容連結
單一指標契約可以用普通檔案檢查。當定義、排除條件、查詢草稿與後續修訂需要一起保持可檢視，又不能假裝公式已核准時，來源連結的指標 wiki 才有幫助。
審查邊界
分別核對行動時的付費與未取消規則、C-104 與週末篩選；保留退款處理未知，讓指標負責人確認草稿。
在 Wenlan 裡查看這個範例
Wenlan v0.18.3 介面，呈現隔離測試後讀回的資料。來源是虛構教學資料，參考答案為這次練習人工編寫；畫面沒有展示 AI 自動生成或審批完成。
引用的來源變更後，Wenlan 將頁面標記為過期，正文仍保留原文。這裡的「updating…」表示等待重建，不代表已完成修正。請先檢查變更的來源，再重建並審查新答案。
來源檔案
打開檔案即可閱讀完整的人工編寫 Markdown。
三種語言檢視使用相同的人工編寫英文來源資料集。
01weekly-active-customer-contract.mdWeekly active customer — revision 1
# Weekly active customer — revision 1 Owner: Growth Analytics Window: Monday 00:00 through Sunday 23:59 UTC. Count distinct customer_id values with at least one qualifying action during the window. At the action timestamp, the subscription must be paid and not canceled. Exclude a customer when cancellation is effective before the action timestamp; a cancellation after the action does not remove that week's activity. Exclude test accounts. The contract does not specify how refund state changes this metric. Leave refund handling unknown.
02qualifying-actions.mdQualifying customer actions
# Qualifying customer actions Count an event only when it has a customer_id and an event_at timestamp in UTC. The qualifying actions are: publish a reviewed knowledge page, complete a source review, or approve a revision for reuse. Do not count a login, a page view, a failed import, or an event without customer_id. The action list does not define revenue, retention, or customer health.
03dashboard-query-draft.mdExisting dashboard query — draft
# Existing dashboard query — draft Status: owner approval pending Window example: 2026-04-06 through 2026-04-12 UTC. The draft counts distinct customer_id values with a qualifying action and a paid subscription, then filters out any customer whose cancellation_date is before the end of the week. Example row: customer C-104 was paid and completed a qualifying action on Tuesday, then canceled on Thursday. The draft excludes C-104 because cancellation_date is inside the week. This query is a draft and is not an approved metric definition.
參考答案
Reference answer: count the action-time state, then flag the draft query
Under revision 1, C-104 counts because the customer was paid and not canceled at the Tuesday action; a Thursday cancellation does not remove that week's activity. The draft query incorrectly excludes any cancellation before week end and still needs owner approval. Refund handling is unspecified.
Weekly active customer — reference
Definition
Count distinct customer_id values with at least one qualifying action in the Monday-through-Sunday UTC window. A qualifying action is publishing a reviewed knowledge page, completing a source review, or approving a revision for reuse. Login, page view, failed import, and events without customer_id do not count. weekly-active-customer-contract.md qualifying-actions.md
At the action timestamp, the subscription must be paid and not canceled. A customer whose cancellation becomes effective after the action still counts for this revision of the metric. weekly-active-customer-contract.md
C-104 and the draft query
C-104 counts in the example: the customer was paid and not canceled at the Tuesday qualifying action, while the Thursday cancellation happened afterward. The dashboard draft incorrectly removes C-104 by filtering cancellation_date at the end of the week. It is not an approved definition and needs the metric owner to reconcile its filter with the contract. weekly-active-customer-contract.md dashboard-query-draft.md
Refund handling is not specified by these sources. Keep it unknown rather than deciding whether a refund changes activity. weekly-active-customer-contract.md
變更後的來源: weekly-active-customer-contract.md
這項變更後的預期更新
The revision changes the cancelled-but-paid case: C-104 no longer counts because the cancellation became effective on Thursday inside the measurement window, even though the qualifying action was on Tuesday. The reference must replace its action-time-only conclusion and the draft query's end-of-week exclusion is now consistent with this revised contract, subject to owner approval. Qualifying actions and unknown refund handling are unchanged.
# Weekly active customer — revision 2 Owner: Growth Analytics Window: Monday 00:00 through Sunday 23:59 UTC. Count distinct customer_id values with at least one qualifying action during the window. At the action timestamp, the subscription must be paid and not canceled. Exclude a customer when a cancellation becomes effective at any time during the window, even when the qualifying action happened before the cancellation. Exclude test accounts. The contract does not specify how refund state changes this metric. Leave refund handling unknown.
01
先說結論：一個指標配一筆有來源、可取代的定義紀錄
每個商業指標維護一筆可複核紀錄：商業定義、不可執行的公式文字、粒度、維度、納入與排除條件、負責人、確切來源與來源修訂、複核狀態，以及它取代的舊定義。兩份核准來源互相衝突時，先保留衝突並交給具名負責人判斷，不讓 AI 自動調和。
Wenlan 可以讀取核准的 Markdown、文字與可擷取文字 PDF，建立有來源 Pages、保留引用與來源修訂、執行 provenance lint 並留下可審查版本。它不會導入 CSV 或 YAML、不會執行 SQL、不會連接資料倉儲或 BI、不會計算指標、不會提供血緣、不會監控資料品質、不會管理權限、不會自動核准，也不會自動調和衝突。
02
為什麼同名 KPI 仍可能不是同一件事
活躍客戶、淨收入或轉換率可能同時出現在財務備忘錄、分析規格、產品儀表板說明與營運手冊，但公式、粒度、時間窗、排除條件或負責人各不相同。把它們整理成一段流暢摘要，反而會隱藏真正需要決策的差異。
可維護的資料字典應該讓每個版本回到確切來源，清楚標記目前有效、過期、矛盾或未解，並在新版核准後保留舊版本與取代關係。即使不用 Wenlan，這也是可獨立採用的指標治理基本紀錄。
03
建立核准規格到指標紀錄的閉環
先選一組指標與少量核准檔案。這個工作流只負責定義查找與衝突處理，不建立所有資料表、儀表板或即時運算的目錄。
- 先記錄指標名稱、商業問題、核准來源、排除系統、具名負責人與複核人。
- 只加入核准的 Markdown、文字或可擷取文字 PDF；CSV、YAML、SQL、資料倉儲 metadata 與 API 不在這個流程。
- 把公式寫成可複核文字，並記錄粒度、維度、時間窗、納入、排除與例外。
- 每個重要欄位連回 source ID、確切標題或頁碼、來源修訂與生效日期。
- 來源衝突時保留兩個版本，標成矛盾或未解，不自行平均或合併。
- 負責人選定目前版本後，記錄取代的舊定義、保留歷史版本並設定下次複核條件。
完成 Wenlan 與 AI 用戶端設定後
wenlan status
wenlan sources add ~/Metrics/approved-specifications
# 在 Wenlan plugin client 中：
/distill <指標定義>
/pages <指標名稱>
/lint
/curate
metric: activated customer
business_definition: <核准來源真正定義的意義>
formula_text: <不可執行的公式文字>
grain: <帳戶 | workspace | 使用者 | 事件>
dimensions: <允許的拆分維度>
inclusions: <納入狀態或事件>
exclusions: <排除狀態、事件或時間窗>
owner: <負責團隊或複核人>
sources: <source ID 與確切位置>
source_revision: <版本或生效日期>
review_state: <目前有效 | 過期 | 矛盾 | 未解>
supersedes: <舊定義或無>
next_review: <來源變更條件或日期>04
指標紀錄應該保留什麼
一筆可用紀錄不只是一句定義。它要讓讀者知道公式文字在什麼粒度成立、哪些狀態被排除、誰有權決定目前版本，以及這個版本依據哪份來源。
05
知道這不是資料目錄、BI 或計算引擎
Wenlan 不會導入 CSV、不會執行 SQL、不會連接資料倉儲、不會同步 BI 或 semantic layer、不會計算 KPI、不會提供欄位血緣、不會監控資料品質、不會管理權限、不會自動核准定義，也不會自動調和衝突公式。具名領域負責人仍要做商業判斷與最終複核。
讓一個指標定義可檢查
從核准規格開始，保留衝突與確切來源，只在具名負責人複核後取代舊定義。
常見問題