指标定义工作流
建立业务指标定义知识库
把获准的 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、不会提供字段血缘、不会监控数据质量、不会管理权限、不会自动批准定义，也不会自动协调冲突公式。具名领域负责人仍要做业务判断和最终审核。
让一个指标定义可检查
从获准规范开始，保留冲突和准确来源，只在具名负责人审核后替代旧定义。
常见问题