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 中，由原语构建。每个 KPI 都标记为 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 KPI → 来自 references 的 KPI（规范 source: reference 并带有 reference 块，见 references/reference-documents.md） → 永远不会 exclude → 根据与 focus 的相关性，先建立的标准再派生的，无近似重复项 → 限制 Claude 自己的选择在 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 = 标准输出上的 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 并附有原因；运行继续。标准输出摘要列出每个 validation: 警告。

相同的运行还会：

• 对每个敏感性变体重新运行所有 KPI，并在每个 KPI 上存储 sensitivity: {low, high, variants}；
• 将每个 KPI 与其参考文献报告的值进行比较，转换为 KPI 的单位（comparison：差值、相对差值、根据方向判断更好/更差、报告的值是否落在敏感性范围内）；
• 写入 data_health：每个映射的数值列，包含缺失占比、最长连续运行、稳健异常值和不可能值（负计数、超过 100 的百分比、低于绝对零度），以及规则序列的时间覆盖率。

如果任何 KPI 带有验证警告：一次重新检查解析笔记（步骤 2）、映射（步骤 4）和规范（步骤 5），从更改的最早步骤重新运行，如果仍然失败，则带警告报告。

运行后，您只能编辑 results.json 以向 not_computed 条目添加 enable 文本（始终适用于来自参考文献和 include 的 KPI）（说明什么数据或参数会使 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，然后替换脚本在标准输出上列出的占位符，原地编辑 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 构建的领域包，作为单独的 Markdown 文件，遵循 references/fields/_template.md 格式，供用户审阅和添加。不要将其写入技能文件夹。

非目标

不进行预测或模型构建（该技能评估给出的预测）。不提供实时数据源或数据库。不提供投资、医疗或工程建议：报告指标及其指示内容。不进行货币转换：混合货币会标记出来并按每种货币计算。

默认值（无需询问即可使用，使用时要说明）

设置	默认值
无风险利率	0
年化因子	仅工作日日度 252，日历日度 365，周度 52，月度 12，季度 4，小时度 8760
MASE 季节性周期	小时度 24，日度 7，周度 52，月度 12，季度 4，否则 1
不规则阈值	区间 CV > 0.5
间隙阈值	3 × 中位数区间
时间列解析率	≥ 95%
采样概要	> 1,000,000 行 → 200,000 行样本（时间列始终完整读取）
max_kpis	12（仅 Claude 自己的选择）
百分比处理	通过启发式方法（非百分比的 0–1 值、0–100 区间、关于合计或基数的提示）检测的列中 0–100 的值。保留原样，除非 0–100 的列是比率：然后除以 100。