gongfen-calc

从格式不固定的 Excel/CSV 任务清单中自动识别字段、归一单位、按多维度打分并汇总工分，产出打好评级的 Excel 结果表（工分明细/批次汇总/质检自检/字段识别）+ 可复核的 Markdown 报告。当用户提供任务清单（.xlsx/.xls/.csv）要求"算工分""算任务分""按工时/难度/金额/优先级给任务打分""评估任务价值分布""导出打分表"，或贴出一张任务表问"能不能自动算分"时使用。识别不出必要字段时明确报"分析失败"并回显已识别列名清单，不静默编造结果。

工分计算（gongfen-calc）

用途

把一张格式不固定的任务清单，变成一份可复核的工分事实清单：

text

Excel/CSV → 字段识别 → 单位归一 → 质检 → 批次评级 → 打分 → Excel 结果表 + Markdown 报告 + 中间 JSON

输出的是任务分，不是个人绩效等级。设计上宁可报"分析失败"，也不静默编造一个看起来合理的分数。

门槛：只要识别到任务名称或描述列就执行分析，缺列不阻断——缺失的维度不参与计算，只在报告提示。 唯一阻断条件是「连任务名/描述都认不出来」。难度维度固定启用，从任务名（优先）或备注描述推断。

不适用：给人定绩效等级（A/B/C）、淘汰或扣罚名单。这类需求直接拒绝。

快速开始

bash

# 1. 装依赖（Windows 必须走阿里云镜像，直连 pypi 会超时）
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# 2. 跑（一条命令出结果，全程不询问、不中断）
python scripts/run.py 任务清单.xlsx
python scripts/run.py 任务清单.xlsx --out-dir out --baseline out/baseline.json

# 3. 只有在「明知第 N 列是什么、脚本却认错了」时才人工覆写（唯一的人工介入点）
python scripts/run.py 任务清单.xlsx --override 3=hours --override 5=money

# 4. 明知覆盖度不足（C/D 分支）仍要出工分 —— 默认不出，必须显式加 --force-points
python scripts/run.py 任务清单.xlsx --force-points

--override 列号=字段名：列号从 1 开始（对应报告「字段识别明细」的列号），字段名取值 task_name/hours/money/difficulty/risk/priority/quality/urgency/start_date/end_date/collab/reuse/parent/role/…。 覆写会写进仲裁记录留痕，被取代的同名字段列自动转入「未映射列」。低置信列默认按规则自动裁定，不会停下来问。

产出（默认与输入同目录，可用 --out-dir / --xlsx / --json / --md 指定）：

• 任务清单.gongfen.xlsx —— 打分结果表（主交付物），4 个 sheet：
  • 工分明细：逐任务 原表行号 / 任务名 / 各维度档位（带权重）/ 原始值 / 完整度 / 分层 / 层内排名 / 小计 S / K系数 / 工分 P / 判定依据（容器父任务也列出，标"不计分"）
  • 批次汇总：分支结论、总分 T、总工分、分层分布、维度权重与覆盖度、口径冻结、提升建议
  • 质检与自检：质检提示、自检结果、被打折任务、被剔除行（含行号与原因）、冻结任务、红线声明
  • 字段识别：列映射明细（列号/置信度/方式/样例）+ 未映射列 + 仲裁日志
• 任务清单.gongfen.md —— 给人看的报告（九节）
• 任务清单.gongfen.json —— 复核与下游用的中间结构（解析层与打分层的唯一契约）
• out/baseline.json —— 首次运行自动存档，第二次起启用环比检测

C/D 分支下 Excel 的「工分 P」列留空，另给一列**「参考工分（仅供排序对照·不可用于分配）」**（= S×20×K）， 表头与汇总页都写明不可用于分配；确需工分时加 --force-points 重跑，脚本会在保单里追加一条强制输出警示。

退出码：0 正常或降级 / 1 分析失败（已出可读报告）/ 2 参数错误 / 3 内部异常。

执行流程

脚本端到端出结果，模型不做二次判断。 不要自己打开 Excel 猜字段，不要覆写脚本给出的分数，不要在识别环节打断用户。

1. 跑脚本（合并单元格展开、合计行剔除、单位归一、Excel 排版这些手工很难做对的事都在脚本里）。
2. 读"批次结论"：A_正常 / B_可排名 / D_体系退化 / C_仅描述 / E_失败。这决定结果能不能用于分配。
3. 交付 *.gongfen.xlsx（主交付物，直接给用户打开）；Markdown 是同一份数据的文字版，用于贴聊天/贴文档。
4. 把三件事讲给用户：分支结论与免责句、剔除了哪些行（Excel「质检与自检」第五节有行号与原文）、哪些任务标了异常（工时与日期矛盾、被偏离度打折、难度为估算值）。
5. 用户追问某个数怎么来的，查 任务清单.gongfen.json 或 references/field_dictionary.md（别名表、正则、换算系数、质检规则都在里面）。
6. 口径：改 scripts/params.py 后重跑；列认错了用 --override 列号=字段名 重跑；不要手工改分数，也不要手工改 JSON。

Excel 结果表（scripts/excel_out.py）

只在非 E_失败分支产出（失败时只有 MD/JSON）。excel_out.py 只读 payload、不碰任何分数， 所以 Excel 与 MD/JSON 永远同源同值；重跑即覆盖同名文件。

sheet	内容	用途
工分明细	原表行号 / 任务ID / 任务名 / 各维度档位（表头带归一化权重）+ 原始值 / 有效维度数 / 完整度×2 / 分层 / 层内排名 / 小计 S / K偏离·K合计 / 工分 P / 判定依据	逐任务核对、按原表行号回溯
批次汇总	分支结论、总分 T、总工分、分层分布、维度权重与覆盖度表、口径冻结、补齐字段建议	一眼看结论
质检与自检	质检提示、批次评级提示、自检结果、被打折任务、被剔除行（行号+原因+原文）、冻结任务、红线声明	复核"哪些数据没被采信"
字段识别	列号 / 原始列名 / 识别为 / 置信度 / 识别方式 / 样例值 + 未映射列 + 仲裁日志	认错列时查列号，配 --override 重跑

实现约束（改这个文件时必须守住）：

• 列对齐：明细行逐列拼装，len(line) != len(headers) 直接抛错。容器父任务分支只补 「分层/排名/小计/K偏离/K合计」5 列（有效维度数与完整度在分支前已追加），多补就会越界。
• 容器父任务必须出现在明细里（标"不计分（防父子重复计分）"），否则用户会以为漏了任务。
• P.COVERAGE_RANK/COVERAGE_NORMAL 是百分制数值（45.0/60.0），格式化用 :.0f% 而不是 :.0%。
• 未映射列要跳过空白列名（真实表常有几十个空列）。
• 写入前清 Excel 非法控制字符并截断超长文本（备注列经常带换行与超长文本）。

五个输出分支（都是正常路径，不是异常）

分支	触发	结果能用于什么
A_正常	启用维度权重 ≥60%，n_eff ≥3	可排名，作分配参考
B_可排名	权重 45–60%，或单维归一权重 >35%（预警线），或无日期锚点	可排名，不建议直接分配
D_体系退化	n_eff <3，或难度排名与工时排名一致性 >0.85，或有效维度 ≤2（40% 硬上限数学不可满足）	仅排序参考，禁作分配依据
C_仅描述	权重 <45%，或任务数 <3，或 >50% 任务无任何有效维度	仅描述统计，不出总分
E_失败	无任务名或描述列 / 表头定位失败 / 文件不可读或加密	不出分，回显失败三件套

门槛口径（已按用户要求放宽）：只要识别到任务名称或描述列就执行分析， 缺列不再阻断——缺失的维度不参与计算（走降权重重分配），只在报告里提示。 唯一阻断条件是「连任务名/描述都认不出来」。「无任何可量化维度」由阻断改为降级提示 （W_NO_QUANT_DIM），落到 C_仅描述 分支，仍出逐任务难度与排序，但不输出工分。

优先级 E → C → D → B → A，命中即停。分支 B/C/D 不停流程、不弹询问，只在报告首屏加固定提示句； 在 C/D 分支下不得给出任何分配建议，也不输出工分单价（MD 里工分列渲染为「—」， Excel 里「工分 P」列留空，另给一列明标「参考工分（仅供排序对照·不可用于分配）」）。 确需工分时由人工显式加 --force-points，脚本会在保单与 Excel 汇总页追加"强制输出"警示 —— 默认不给，脚本不替人做这个决定。

红线

1. 不产出"某人应得 X 分 / 应评为 X 级"。要按人汇总，只能说"该人负责任务的工分合计"，并注明"不等同于个人绩效结论，用于分配前须经团队共识与人工复核"。
2. 不产出淘汰/扣罚名单，也不设计这类规则。
3. 不得静默改分。工时偏离度打折、疑似拆分、分布偏斜——全部只提示 + 列清单，判断权归人工。
4. F 技能门槛永不进小计（即使有花名册）。职级→门槛的映射会让同级员工的所有任务获得加成，且同一任务换人做就变分，属于对特定人群的系统性偏差。
5. 数据不足不得伪装成可用。权重合计 <45% 或 n_eff <3 时，必须显式写「仅排序参考」。
6. 报告必须带红线声明；失败时必须回显三件套（①已识别列名 ②缺失字段 ③建议补充列）。
7. 估算值不得冒充实测值。关键词推断出的难度必须标 estimated，且标注要出现在总分旁边，不能只写在方法说明里。

关键口径

项	口径
单任务小计	S = Σ(level_i × W_i) / Σ(W_i有效)，缺失维度从分子分母同时剔除，不填 0、不填中位 3
单任务工分	P = S × 20 × K_偏离 × K_体量 × K_角色 × K_子任务。所有 K 只乘在工分上，不进小计 S；K_体量 默认关闭（K_VOLUME_ENABLED=False），K_角色 默认 1.0
工时偏离度	K_偏离 = h_eff / h，h_eff = min(h,P90) + 0.3×max(0,h−P90)；n≥10 启用；物理可行豁免：有起止日期且 h ≤ 自然日×8×0.7×1.5 → K_偏离 = 1。被打折任务逐条单列进报告第五节，证据含原始 h、P90、h_eff、K 值
⚠️ 分档输入	分位数与绝对档一律用原始工时 h，不得用 h_eff（绝对档下用它等于二次惩罚，与 K_偏离 重复打折）
⚠️ 不存在	hours_deviation_weight_compression 开关、「削 B 权重 + 回补」写法——只有上面一种打折实现
分档	P10/30/70/90 右闭；n<5 或 P10==P90 → 绝对档 4/16/40/80h
完整度	分母 = 本批启用维度权重和（不是固定 100），另输出 completeness_vs_100 对照。分层两刀：L1 ≥90%／L2 60%–90%／L3 <60%
总分	只对 L1+L2 求和（INCLUDE_L3_IN_TOTAL=False）；L3 不参与分配，另出一行含 L3 的参考总分
冻结	无任何有效维度的任务不填 0、不进任何层、不排名，单列第六节
覆盖度（批次级）	min(启用维度基础权重和, 100) / 100；≥60% 分支 A／45–60% 分支 B／<45% 分支 C
40% 封顶	单维归一权重 >40% 触发回流；有效维度 ≤2 时数学不可满足 → 强制 D 分支且不输出工分
相关性	Spearman，n≥10 才执行（n<10 不执行，不猜）
C 经济效益	覆盖率按「非空且非 0」计，<50% 整批关闭，走通用归一化
A 困难程度	关键词规则表（params.A_KEYWORD_TABLE，剥离排除词 → 最长匹配去重 → 取最低档）。只要有任务名/描述就启用：命中率 <20% 只提示「建议校准词表」、不再关闭维度。匹配分两级源：① 任务名（+交付物列）优先；② 任务名无命中才用备注/描述列，依据前缀 描述: 区分。无模型参与
J 复用价值	三档枚举 5/3/1；表里必须有交付物列且命中率 ≥20% 才启用
子任务折价	父任务被判独立任务时，子任务 ×0.60 防重复计分；父被判容器时父子不重复计

完整锚点、权重算例、自检项与参数表见 references/scoring_anchors.md。

脏数据处理

现象	处理
表头不在第一行	前 15 行打分定位，阈值 0.45，失败回显前 15 行
多 Sheet	评分选表，分差 <1.5 报歧义让用户选，默认不合并
纵向合并任务名	按锚点聚合成 1 条，工时/金额求和（防成倍放大）
合计/小计行	关键词 + 可加性自检（没有"合计"二字也能抓）双重判定
2人天 / 8h / 约3天 / 待定 混排	单位三来源：列名 > 日期锚点反算 > 数量级推断
¥12,000 / 1.2万 / 12k	统一转元；列名已含"万"不重复乘
- 待定 N/A	统一空值集，转 NaN 并计入缺失率
「状态」列	内容仲裁：枚举含 通过/驳回/返工/验收 → 归质量；含 已完成/进行中 → 归进度，不参与打分
「优先级 P0-P3」	只喂紧迫性，不喂风险（急 ≠ 错了多严重）
多区块考核表（区块标题 + 独立表头 + 数据，重复多次）	detect_blocks 切分区块、每块独立识别表头与列后合并。闸门：第 2 个及以后的表头行正上方必须是区块标题行，否则不切（防单表被切碎）
月评/计划/意见栏被当任务	is_non_task_row 剔除：整行同值（合并标题）、单格文本、或命中 自我月评/下月计划/意见/签字 等
序号列被当成工时	公差为 1 的连续整数列判为 seq，不映射工时（否则 1–13 变成 8–104 小时，排名由行号决定且不报错）

完整清单见 references/field_dictionary.md（24 项质检 + 别名表 + 解析正则）。

参数校准

所有经验值集中在 scripts/params.py，禁止散落硬编码。标注 [需校准] 的必须按团队实际校准后方可用于分配，重点四项：

• HOURS_PER_MANDAY = 8.0 —— 研发岗常见 6.5–7（单位统一时不影响分位数分档，影响较小）
• WORKDAY_FACTOR = 0.7 + 无节假日日历 → 工期高估 10–12%，影响面大
• HOURS_DEVIATION_FACTOR = 0.3（超 P90 部分保留比例）
• ABSOLUTE_BANDS / COLLAB_LEVEL_CUTS / LOOSE_* / ENTROPY_MIN

换算系数会冻结进 baseline.json，跨批次系数不一致时自动禁用环比比较。

已验证 / 已知限制

已跑通并回归验证（10 份 fixture，tests/）：

fixture	验证点
fixture_dirty.xlsx	表头在第 3 行、纵向合并聚合成 1 条、无「合计」字样但等值于上方之和的伪合计行（靠可加性自检抓到）、工时混排 2人天/8h/约3天/待定、金额混排 ¥12,000/1.2万、480h 与 2 天工期的矛盾行只标记不改分、真实 160h 长任务豁免打折
fixture_status_progress.xlsx	「状态」列枚举为 已完成/进行中 → 判为进度列、不映射质量维（否则所有已完成任务同分、E 维退化成常数）
fixture_container.xlsx	容器父任务可加性自检（父 40h = 子 15+15+10 → 父不计分）；父工时 >> 子之和 → 父判独立任务、子任务 ×0.6 折价
fixture_serial_date.xlsx	Excel 序列号日期（46027 = 2026-01-05）反算可用工时，不被当成工时/金额
fixture_double_header.xlsx	双层表头（父行纵向/横向合并 + 子行细分 → 拼成 工时投入|投入工时）＋第三行「单位:人天」单位行 → 工时 ×8
fixture_minimal.xlsx	3 维、n_eff<3 → D 分支，工分列降级为「—」
fixture_only_hours.xlsx	仅工时 → C 分支，只出描述统计；同时作为 --force-points 回归用例（强制出工分不报错）
fixture_gbk.csv	GBK 编码 CSV，全角 ￥ 金额
fixture_no_dim.xlsx	无可量化维度（只有任务名+负责人）→ 按放宽后的门槛不再阻断，落 C 分支只出描述统计 + 提示可补充的列（旧口径为退出码 1）
fixture_noheader.xlsx	表头定位失败 → 退出码 1 + 前 15 行回显

已实现但未做回归验证（遇到时以实际输出为准，不要向用户承诺）：

• .xls 旧格式与加密文件（需 xlrd / msoffcrypto，默认环境未装）
• 多 Sheet 歧义分支（分差 <1.5 需人工指定）、分页重复表头剔除、列级横向合并
• 「单位行」只解出工时的单位；金额的 万元 单位行暂未回填到金额换算（同列同尺度，不影响相对档位）
• Excel 输出不回写原文件（不改动用户原表），只另存 *.gongfen.xlsx；如需"原表+打分列"的合表形式， 用明细表的「原表行号」列自行 VLOOKUP 关联，不要在脚本里改写用户文件

依赖

Python ≥3.9（实测 3.13）｜pandas / openpyxl / numpy / python-dateutil，版本见 requirements.txt。

文件结构

text

scripts/
  params.py            全部经验参数（唯一来源）
  excel_io.py          读取、编码嗅探、选表、表头定位、合并展开
  field_recognize.py   别名词典、字段识别、仲裁、单位归一、层级
  quality_stats.py     24 项质检、分档、覆盖度、自检、baseline
  score.py             小计、分层、层内排名、总分（只读 JSON）
  report.py            Markdown 报告、固定句、失败回显
  excel_out.py         打分结果 Excel（工分明细/批次汇总/质检与自检/字段识别）
  run.py               编排入口
references/
  scoring_anchors.md   评分锚点、动态权重、参数表、红线（口径来源）
  field_dictionary.md  别名词典/单位表/解析规则/质检清单（模型与脚本共用）
tests/
  make_fixture.py       生成「故意做脏」的测试表（6 份）
  make_fixture_extra.py 生成 4 份高危场景测试表（状态列/容器父任务/序列号日期/双层表头）
  run_regression.py     回归入口：跑全部 fixture + --force-points 用例，可接真实表路径

bash

python tests/run_regression.py                      # 只跑 fixture
python tests/run_regression.py 你的真实表.xlsx       # 额外跑一份真实表

预期：fixture_noheader.xlsx 退出码 1（故意失败），其余全部 0；末尾打印"全部符合预期"。