vxi-ops-report-spec

概述

报表类需求分析（核算类需求逆向提炼）

把「一堆原始 Excel 加一份草稿需求」逆向提炼成一份与标准答案零差异、可验收的需求规格说明书。

⚠️ 绝对禁止（最高优先级）

• 绝对禁止修改业务方的原始需求目录中的任何文件（源数据、规则表、金标准、草稿文档）。所有产出只写入工作区。
• 绝对禁止文档对文档地「看着改」：任何规则结论都必须用金标准数据端到端复算验证，0 差异才算数。
• 禁止凭草稿需求文档下结论：草稿（HR 或 AI 写的）常有遗漏、错误、实现絮语，只能当线索。
• 绝对禁止把自己推断出来的口径写成已确认事实：没有金标准背书的结论一律按下面「三标法」标成假设或待确认，替代做法见那一节。
• 绝对禁止在复算差异未清零时宣称吻合，也绝对禁止为了对上金标准而反推一条没有依据的规则（凑出来的规则换个月必然崩）。算不出 0 差异有专门的收场路径：读 references/zero-diff-fallback.md（应含「## 四步收场」一节，读回空就重读一次）照它走，不许改写验收标准。

📍 每次都照办 / 做到才照办两层：每次都照办的是上面「绝对禁止」、下面「三标法」「权威优先级」「验收标准」四节，「数据处理与流向」里的两条硬约束（委托 vxi-xlsx 灌库后清掉它的快照缓存；规格说明书里用样本代号、不留真实姓名），以及「快速启动」第 1 步那条「写中文的临时脚本禁止用 python -c 内联」。其余各节——「为什么」「快速启动」「工作流」细节、「出错与中断怎么办」、「数据处理与流向」的其余部分——只在做到对应步骤时才有约束力；references/ 各篇的加载时机见文末「references 索引」。

为什么先要一份需求规格说明书

要解决的不是「AI 会不会算」，而是「算错时人能不能低成本指出错在哪」——规则没覆盖到的情形按这条原则推：白话规则是给人纠错的界面，三标法让人一眼看出哪些结论还没有底气。完整推导与三种正当用法见 references/credits.md。

何时用它、何时不用它（触发速查）

触发词去哪找：本节就是唯一权威清单，frontmatter 的 description 那份是它的摘要，两处不一致时以本节为准。拿不准要不要触发时的兜底：只看使用者要的成品是一份文档还是一张结果表——要文档才触发；两样都要时先做本技能出规格、并说明结果表不由它产出；仍判不出就直接问他要文档还是要数据，别默认开工。

强制触发：需求提炼、整理需求文档、把 Excel 需求转成规格说明书、报表需求分析、核算需求分析、逆向需求、规格化需求、核对需求与源数据或标准答案是否吻合（口语说法：这份需求跟数据对不对得上）。

不应触发：纯编码实现任务；直接产出业务结果表（「算出这个月每个人的结果并出 Excel」那是执行核算，不是提炼需求）；解读这份报表数据说明了什么（数据解读）；与「从源数据按规则核算出结果表」无关的需求。

使用者原话举例（可直接照抄比对）：「这是绩效核算的原始数据和 HR 手工算好的结果，帮我把需求整理成一份能验收的文档」「这个薪酬核算的规则表和数据源，逆向整理出核心逻辑、输入、输出三段式说明」「上个月的规则表改了，这份核算需求文档要跟着更新，差异帮我列出来」「帮我看看这份月度报表需求文档有没有遗漏，和原始表逐格核对」→都触发；「这是绩效原始数据，帮我算出这个月每个人的分数」→不触发（要的是结果表，不是需求文档）。

英文原话同样命中，照抄这两句：turn these Excel files and the draft doc into a verifiable requirements spec、check whether this draft requirement matches the source data and the gold answers；反例 calculate this month's performance scores from these files 不触发（要的仍是结果表）。

两条边界：只接受自然语言触发，不提供 API 或结构化调用接口（取舍理由见 references/credits.md）；规则表每次变更都要重新触发一次本流程出新版规格，旧版随之过期（版本与差异的记法见工作流第 9 步）。

产出物

1. 一份三段式《需求规格说明书》（核心逻辑 / 输入适配 / 输出适配），落到工作区，套 references/requirement-spec-template.md 的骨架（应含「## 4. 核算指标与计算规则」一节，读回空就重读一次，未确认非空不得往下写）。
2. （可选）一份审计报告，列出原始草稿文档的遗漏与错误。

快速启动（新手照这五步走，中间不会漏步）

1. 环境自检：python --version 需 3.8 及以上；输入是 .xlsx 时另需 openpyxl（pip install openpyxl），或改用零依赖的 CSV / JSON 输入。⚠️ 写中文的临时脚本一律落成 .py 文件再执行，禁止用 python -c 内联（Windows 终端默认 GBK，源码与输出两处都会坏）。另两条（不抛 UnicodeEncodeError 还要加哪一行、临时文件落点）见 references/env-notes.md（应含「## 开工前的环境自检」一节，读回空就重读一次）。
2. 兄弟技能依赖只有一个：源表是大表或复杂格式时把读取那一步委托给 vxi-xlsx，判据与它不可用时的三级降级见 references/xlsx-reading-guide.md。小表随手 dump 即可，不装它也能全程走完。
3. 过一遍下面的「资料齐套检查」，缺必需材料的别开工。
4. 第一次用、或对走法没把握：先读 references/worked-example.md（应含「## 案例二」一节，读回空就重读一次），两条案例各走一遍——一条差异一次清零，一条差异清不掉时收场。
5. 从工作流第 1 步起顺序执行，认表头、定口径、写规则、复核差异时各对照一遍 references/pitfalls.md（应含「## 12 条陷阱与对策」一节，读回空就重读一次）；撞上具体报错或选参数拿不准时查 references/faq.md。

资料齐套检查（动笔前先过一遍）

三样必需材料缺任一样就不要开工：原始数据源、金标准（业务方手工算好的结果表）、规则表与草稿需求至少有一样。缺了先把缺口如实告诉业务方（缺什么、为什么必须要、拿不到时降级成什么），不要默默猜着往下做。逐项判据与两类加分项见 references/intake-checklist.md（应含「## 三样必需材料」一节，读回空就重读一次，未确认非空不得开工）。

权威优先级（冲突时这样判）

口诀：规则看规则表，列名看数据源，对错看金标准，草稿只参考。

1. 金标准（手工结果）——验证一切的最终真值。
2. 规则表与标准表——规则定义权威；但其手写的列名与列字母常不准。
3. 数据源真实表头——字段名以数据源实际列名为准，覆盖规则表手写。
4. 草稿需求——仅作线索，所有结论须经金标准复算确认。

⚠️ 金标准本身也可能算错，它是「最高权威」不是「一定对」：复算差异要先定位在哪一侧（按文档算法逐步代入，看是自己的公式错、还是金标准那一格的人工算错，判法见 references/zero-diff-fallback.md）。判定为金标准有错时，把那一格连同推导过程一并列进待确认项交业务方复核，别自行改动金标准文件。

三标法：每条结论都标定性、出处、验证状态

需求规格里的每条规则、每个字段口径都要带三样：定性（事实 / 假设 / 待确认）、出处（规则表哪一行、金标准哪一格、数据源哪个字段）、验证状态（已复算 / 未复算 / 无法复算）。缺任一样即视为未完成——复核的人无从判断这条能不能信，换月复用时也无从核对它还成不成立。三个取值各自的判据与书写格式见 references/requirement-spec-template.md 的第 4 节。

⚠️ 标成「假设」的必须附一句「换月会不会翻车」：某月相关项恰好为 0 时，错误规则也能通过零差异复算；只有写明「哪种数据形态一出现它就不成立」，下个月的人才有机会发现（对应 references/pitfalls.md 的「被数据巧合掩盖的错误」那条）。

工作流（严格按序）

1. 盘点理解：先过「资料齐套检查」确认缺项已处置；列目录把每个 Sheet 归成 5 类材料（分类表在 references/intake-checklist.md）；读草稿需求与规则表建立业务全貌；dump 各 Excel 的 sheet 名、表头、行数，认表头时对照一遍 references/pitfalls.md 的表头与列名那几条。小表随手 dump 即可；大表与复杂格式的读法及降级路径见 references/xlsx-reading-guide.md（应含「## vxi-xlsx 不可用时的降级路径」一节，读回空就重读一次）。
2. 三段式建模：核心逻辑、输入适配、输出适配三段各要写什么字段照 references/requirement-spec-template.md 的骨架填。唯一护栏：核心逻辑层用业务字段名，绝不出现单元格位置（A 列 / K 列）——写了单元格位置，源表插一列规格就全错。
3. 规则书写：每条规则先一句白话（给非技术人员），再附公式或伪代码；每个核算指标配一个来自金标准的真实算例（数字要对得上）；每条按上面「三标法」标齐三样。
4. ⚠️ 金标准验证（决定成败）：按文档算法复算后将结果落盘，跑 python scripts/verify_gold_standard.py 做逐格比对（用法与各退出码的处置见文末「脚本与退出码」）。0 差异才算吻合，差异按 references/zero-diff-fallback.md 处置。大表比对会跑几十秒到几分钟、脚本自带进度打点，别当卡住去打断。规则表字段多时覆盖性核对可分组下派子代理并行做，但不下放改写权、由主执行者汇总后统一改一次（做法见 references/worked-example.md 的「覆盖性核对怎么并行下派」一节）。
5. 模糊词强制量化：核算规则里出现「按实际」「视情况」「原则上」「酌情」「参照上月」「从优」这类词，一律不许原样抄进规格——它们在实现时会被开发各自猜一种。要么用金标准反推出确定口径并标成事实，要么记成待确认项交业务方定。
6. 精简重写：砍掉与产出物算法无关的发散内容（下游业务定位、脚本路径、依赖版本、语言与 API 实现细节、过度性能指标）。重写而非叠加补丁。长文档加目录。
7. 数据规模预警：实测源数据行数与大小，大表（万行级、多 MB）写明「后续开发必须真流式读取、只读必要 Sheet、即读即聚合，避免内存溢出」。
8. 指标规则快照：要求产出物附带结构化「指标规则快照」（一指标一行、字段原子化、来源用 数据集.字段 记法，并带上三标法的三列），供人工盘点。
9. 本月口径版本与漂移：规格里写明这一版是按哪个月的规则表提炼的，并列出与上一版的差异（哪条规则变了、变成什么、依据是哪份规则表）。⚠️ 这个领域的规则按月变是常态而非例外，不记版本与差异，下个月的人只能从头再提炼一遍。
10. 列出修正与待确认：附录一张表列出草稿文档的遗漏与错误及修正依据；待确认项单独一张表、按「是否改变核算结果」排序，只留会真正改变结果或范围的那几条（一长串没人答的清单等于没提问）。

验收标准（交付前逐项核对）

• [ ] 按文档算法端到端复算，与金标准逐行逐列 0 差异；达不到的按 references/zero-diff-fallback.md 处置，且首页已如实标注。
• [ ] 规则表每条字段在文档都有对应（双向无遗漏）。
• [ ] 输出表每一列都能追到产出它的那条规则，反向每条规则也都有落到某一列或某项校验（双向无孤儿）。
• [ ] 每条规则与字段口径都带齐三标法的定性、出处、验证状态；标为假设的都写了换月风险。
• [ ] 核心逻辑层无单元格位置耦合。
• [ ] 每个核算指标有真实算例。
• [ ] 模糊词已全部量化或记成待确认，一个都没原样抄进规格（对应工作流第 5 步）。
• [ ] 指标规则快照已随产出物附带，一指标一行、带齐三标三列（对应工作流第 8 步）。
• [ ] 草稿文档的遗漏与错误已在「关键修正」表列出；待确认项已按是否改变结果排序。
• [ ] 大表数据规模与流式要求已写入。
• [ ] 本月口径版本、以及与上一版的差异已写明。

出错与中断怎么办

• 脚本非零退出：对照 references/script-exit-codes.md 的退出码表逐行处置（那张表装什么见文末「脚本与退出码」）。
• 会话中断：草稿即检查点，从第一条「未复算」的规则接着做，不必从第 1 步重来。
• 判不出来：如实标待确认或假设（三标法），不猜一个口径继续写。

数据处理与流向

本技能处理的原始材料通常含个人数据（员工姓名或工号、考勤打卡、绩效得分、薪酬明细）：只读提炼所必需的字段与行范围，探查与复算的中间产物落工作区内被版本控制忽略的临时目录、用完即删。本技能自身不外发任何数据，脚本只读本机文件做逐格比对，不联网、不遥测。硬约束两条：⚠️ 委托 vxi-xlsx 灌库后必须清掉它的快照缓存（它的缓存不会自动删，跨多次会话做同一份需求时每次收尾都清）；⚠️ 产出的规格说明书里用样本代号，不留真实姓名。为什么必须读真实数据、读到什么程度、规格与审计报告落在哪、以及外传边界见 references/data-handling.md。

references 索引（按需查阅，不必预读）

动手前必读三篇：references/intake-checklist.md（开工前）、references/requirement-spec-template.md（动笔写之前）、references/script-exit-codes.md（跑比对脚本之前）。其余各篇撞上对应情形才读，逐篇时机见下表。

🛠️ 脚本与退出码

scripts/verify_gold_standard.py 逐格比对计算结果与金标准，接受 CSV、JSON（对象数组）与 .xlsx。最短用法四个参数：

python scripts/verify_gold_standard.py --computed 复算结果.csv --gold 金标准.csv --key-column 工号 --columns 出勤天数,扣薪金额

scripts/ 下除上列入口外的 .py 只被它 import，别直接运行。可选参数（--sheet 与 --header-row 只对 .xlsx 生效、--json 落盘含工号与金额）、四类退出码（OK / DIFF_FOUND / BAD_INPUT / ENV_MISSING）与各自处置、脚本替你定了哪些默认行为、以及向非技术使用者转述时该怎么说，见 references/script-exit-codes.md（应含「退出码即本脚本的错误码体系」一句，读回空就重读一次）——跑这个脚本前必读。

⚠️ 「0 差异」是有判据的结论，不是逐位全等：数值列按 ±0.01 容差判定、文本列按去空白后全等判定，脚本每次都把这两条写进回执。键列取值不唯一、或两侧都没有数据行时，它报输入错误而不是 0 差异——比不成时结论是「无法判定」。

许可

本 skill 以 MIT 许可开源，Copyright © 上海维音信息技术股份有限公司 (VXI)，完整条款见同目录的 [LICENSE.md](LICENSE.md)。