Cadre / Employee Competency Assessment Kit

Build a scientifically-grounded, distortion-resistant competency assessment
system and generate its full document + tool kit. The bundled scripts are
proven, debugged generators that only need content (dimensions, weights,
questions) swapped to retarget a new role or organization.

When to use

• User asks to evaluate community/village party secretaries, grassroots cadres,
  or ordinary employees and wants a real, defensible system (not a vague
  framework).
• User wants any of: evaluation scheme document (Word), interactive radar chart
  tool (HTML), 360 questionnaire, knowledge-test bank, calibration log,
  AHP weight template, reliability report, or per-person radar gallery.
• User wants to extend an existing competency model, validate its
  scientific rigor, or adapt it to a different role family.

Quick start（非技术人员，5 分钟跑通）

你不需要懂 Python、也不需要改任何代码或路径。照下面三步就能拿到全套材料：

1. 准备环境（一次性）：安装 Python 依赖与 Node 的 docx 库（见下方
   “Environment & run commands”）。
2. 生成模板文档：在脚本所在目录依次运行生成脚本，例如：
   - python gen_question_bank.py → 知识测试题库
   - python gen_log.py → 日常问题台账
   - python assess_sample.py → 单人样例报告 + 《数据采集填报表.xlsx》
   - node gen_scheme.js → 评估方案文档
   产物默认出现在当前目录；想统一存放，先执行 set OUTPUT_DIR=D:\我的评估
   （Linux/Mac 用 export OUTPUT_DIR=...）再运行即可。
3. 填入真实数据并出图：
   - 打开《书记能力评估数据采集填报表.xlsx》的“多人录入与分池归一化”页；
   - 按列填写：B 姓名、C 社区(村)、D 人员类别（填“社区”或“村”）、
   F~M 八个维度分（各 0–100）；
   - 运行 python batch_assess.py → 自动生成每人一张雷达图 + 雷达图画廊
   • 排名汇总表。
   • 要评估多少人就填多少行（默认支持到 200 行，见“能力边界与常见问题”）。

脚本读不到文件、或你填错分数/漏填维度，都会弹出中文提示告诉你缺什么、先跑哪条
脚本，不会闪退也不会生成空文件。

> 一份完全白话、带“评估 100 人”逐步截图式示例的教程见
> references/docs/业务人员快速上手指南.md，非技术人员优先读它。
> 遇到问题（报错怎么看、权重怎么改、能评多少人、城乡怎么比）先查
> references/docs/常见问题FAQ.md —— 问答式速查 + 反模式清单 + 参数调优表，基本不用再翻 methodology。

如何把你的数据喂给脚本（业务视角）

绝大多数脚本是“模板生成器”——零输入，直接产出可改内容的文档/表格。
只有 batch_assess.py 需要你先喂真实数据（从你已经填好的 Excel 读取）。

一句话：11 个脚本里有 10 个零输入；唯一要喂数据的是 batch_assess，且数据来源就是
assess_sample.py 生成的同一份 Excel —— 你只需要在 Excel 里填行。

能力边界与常见问题（业务人员最关心的实际问题）

• 能评估 100 人以上吗？——能。 《数据采集填报表》的“多人录入与分池归一化”页
  默认支持 200 行；batch_assess.py 读取任意行数，一条命令即可生成 100+ 张雷达图
  与排名汇总。要超过 200 人：把 assess_sample.py 里的 FIRST, LAST = 4, 203 调大，并在
  Excel 里把 N/O/P 列公式下拖到新行即可（脚本读取本身不限行数）。
• 知识测试达标线？ 4 个模块均值 ≥ 60 才能评“优秀”；未达标者综合等级封顶“良好”。
• 社区和村怎么比才公平？ 不要直接比“原始综合得分”（城乡资源量级不同会失真），
  正式排名请以 O 列“分池归一化综合得分” 与 P 列“池内排名” 为准。
• 信度/效度现在可靠吗？ 目前是“设计 + 合成数据演示”（报告里的 α≈0.95 是演示值）。
  真实落地需：用真实试测分替换 信度试测样本数据.xlsx 重算 α；预测效度需 1–2 年
  纵向跟踪，尚未补齐。请把它当“决策辅助工具”，而非自动裁判。
• 单人报告页 vs 批量页口径一致吗？ 一致（同类别权重、四渠道加权、知识融合 k 值相同），
  可互相对照。

常见问题与反模式 FAQ（遇到问题先查这里）

绝大多数“跑不起来 / 看不懂结果 / 想改权重”的疑问，已在
references/docs/常见问题FAQ.md 用问答式集中回答，按主题分组，直接搜关键词即可，
不用通读 methodology。该文档包含四块，正好补齐“新用户门槛”：

1. 高频问题：能评估 100 人以上吗、脚本要不要填参数、报错看不懂怎么办；
2. 分主题问答：规模适用 / 怎么跑怎么喂数据 / 指标权重等级 / 分池归一化与排名 /
   雷达图 / 报错排查；
3. 反模式清单（10 条）：归一化方向写反、权重量级写错、城乡不分池混排、知识未达标
   却评优秀、缺失当 0、改 Excel 没改代码、路径用 unix 风格、重跑不清旧图等——“做了结果
   离谱”的坑都在这里；
4. 参数速查与调优表：想改什么 → 哪个文件 → 哪个变量/行 → 默认值 → 改完注意，
   一处查表即可动手，免去翻阅 methodology 的成本。

> 想“手把手跑通”看 业务人员快速上手指南.md；想“公式与推导的完整版”看 methodology.md。

Core methodology (read references/methodology.md for full detail)

The system is a "decision-support operating system", not a black-box scorer.
Five design pillars:

1. Multi-dimension competency model — default 4 classes × 8 dimensions
   (政治建设 / 履职本领 / 治理能力 / 素养品行), class weights 25/30/25/20.
2. Four-channel weighting — 360°(40%) + 实绩(30%) + 民主测评(20%) +
   量化指标(10%). Knowledge test folds in via dimension score =
   channelScore×(1−k) + moduleScore×k (k per dimension; 0 for 组织建设力/群众工作力).
3. Anti-distortion four defenses — reverse items, forced differentiation,
   true anonymity, cross-validation data cleaning. Never rely on a single
   self-report for traits.
4. Pool normalization — normalize within comparable pools (社区/村, or
   department/level) via min-max so heterogeneous groups are comparable.
5. Deep-trait iceberg — 6 traits (成就动机/公共服务动机/内控点/抗压韧性/
   廉洁定力/变革开放性) mined via BEI + SJT + behavior-anchored peer rating.
   Traits must NOT enter the scoring formula — they are interpretive /
   selection-layer signals only.

Workflow

1. Confirm scope & weights. Clarify the target role family and whether to
   use default weights or run an AHP exercise. For ordinary employees, rebuild
   the dimension model per role family (see methodology "延伸至普通员工").
2. Generate the scheme document with references/scripts/gen_scheme.js
   (Node docx). This is the master deliverable; all chapters (framework,
   防失真, 知识融合, 台账, 科学性与信效度, 要素完整框架与边界) live here.
3. Generate supporting tools as needed:
   - 360 questionnaire → gen_questionnaire logic (or extend gen_scheme).
   - Knowledge-test bank → gen_question_bank.py (python-docx).
   - Data-collection / normalization Excel → assess_sample.py
   (openpyxl; includes 分池归一化, 知识达标线, 多人录入 sheets).
   - AHP weight template → gen_ahp.py.
   - Calibration log → gen_log.py (问题记录 + 年终汇总, uses TEXTJOIN —
   requires Excel 365).
   - Deep-trait toolkit → gen_deep_trait.py (BEI 提纲, SJT, 他人评定,
   组合策略, 访谈员资质, 效度验证).
   - Operations manual → gen_ops_manual.py (python-docx; 角色分工 / 7 个
   实施环节逐项 / 计分归一化 / 结果应用 / 脚本重跑 / FAQ / 检查清单，
   零基础可直接上手，配套 references/docs/社区村书记胜任力评估实操手册.docx).
   - Ordinary-employee lightweight framework → gen_employee_model.py
   (python-docx; 岗位族群分层 + 维度池 + 员工版权重/数据源，替换血肉即可
   复用骨架，配套 references/docs/普通员工胜任力模型轻量框架模板.docx).
4. Validate scientifically. Run reliability_check.py (Cronbach α,
   split-half Spearman-Brown, item-total) and simulate_20.py (batch mock of
   20 people, injects calibration issues). Replace synthetic data with real
   pilot data when available.
5. Render radars. For a single person, assess_sample.py draw_radar()
   produces a PNG + 雷达图画廊.html. For a whole batch (e.g. 100 人), fill
   the 填报表's “多人录入与分池归一化” sheet, then run batch_assess.py — it reads
   the sheet and emits one radar PNG per person, a 批量雷达图画廊.html, and a
   批量评估排名汇总.xlsx (raw composite + pool-normalized + pool rank). The
   standalone interactive tool references/assets/社区村书记能力雷达图工具.html
   lets users input scores by hand.
6. Extend / iterate. Adjust dimensions, weights, or knowledge modules and
   re-run the affected script. Keep the scheme document as the single source
   of truth and cross-reference add-on toolkits from it.

Environment & run commands

• Python (venv with python-docx, openpyxl, matplotlib, numpy,
  Pillow): run *.py scripts with the managed interpreter.
• Node (with docx installed in the managed workspace node_modules):
  run *.js with NODE_PATH pointed at that node_modules.
• _common.py / _common.js are REQUIRED and must sit in the SAME
  directory as the generation scripts — they provide the shared robustness
  layer (path self-check, atomic write, friendly Chinese error prompts).
  Never delete or move them away from the scripts.
• Output directory: scripts write to the current working directory by
  default. Override with the OUTPUT_DIR environment variable
  (e.g. set OUTPUT_DIR=D:\my_output) to send all artifacts to one place.
• Windows NODE_PATH gotcha: when running from a shell that uses unix-style
  paths, NODE_PATH MUST be a Windows-style forward-slash path
  (C:/Users/.../node_modules), NOT /c/Users/.../node_modules (the unix
  form makes require('docx') fail with MODULE_NOT_FOUND). Same rule applies to
  OUTPUT_DIR if you set it manually.
• Always keep generation scripts in the working project directory so they can
  be re-run after edits. The skill's references/scripts/ copies are templates;
  copy them into the active project before editing.

Robustness & exception handling

All generation scripts import _common and are wrapped in a friendly error
layer so a bad path / missing file / wrong parameter shows a clear Chinese
prompt instead of a crash or an empty output file.

What is guarded
- Output dir check — get_output_dir() verifies the directory exists and
is writable; if not, prints 无法创建或访问输出目录 + the reason + how to fix.
- Input prerequisite check — require_readable() blocks scripts that need a
file another script produces (e.g. simulate_20 needs the 日常指导问题记录表
生成 by gen_log.py first) and tells you which script to run.
- Atomic write — save_docx / save_xlsx write to a .tmp temp file then
os.replace() into place, then verify a minimum byte size. An interrupted run
can never leave a 0-byte / half-written deliverable behind.
- Data sanity check — assess_sample.py validates the BATCH dimensions
count (=8) and score range (0–100) before generating.
- Global catch — a sys.excepthook (Python) / .catch(friendly) (Node)
intercepts any unhandled exception and prints a 4-step 排查清单 instead of a
raw traceback.

How to read a friendly prompt: it always starts with ❌ 运行中断 —— 友好提示：
followed by the specific cause and a numbered 常见排查 list (依赖 / 输出目录 /
数据参数 / 运行顺序). Fix the indicated item and re-run; no need to read a
stack trace.

Run order that matters: gen_log.py → simulate_20.py (simulate reads the
log). All other scripts are independent.

Gotchas (learned the hard way — do not repeat)

• Spearman-Brown formula is 2r/(1+r), NOT 2r/(1−r). The wrong sign
  explodes split-half reliability to absurd values.
• docx bullet() must be pushed: in gen_scheme.js every bullet('...')
  must be wrapped children.push(bullet('...')); forgetting the push silently
  drops the content from the document.
• HTML gallery % collision: do not use %d/%s printf-style in inline
  CSS that already uses width:100%. Use placeholder tokens + .replace().
• AHP tuples: pass (label, weight) as separate args, not a single tuple,
  to functions expecting two parameters.
• Synthetic reliability data: to get a sane α (not negative), generate
  correlated data with a latent ability factor, not independent noise.
• Long docx strings: keep paragraphs under ~2000 chars; split logical
  blocks into separate add_paragraph calls.
• Path-style pitfall (Windows shell): NODE_PATH and OUTPUT_DIR must use
  Windows-style paths (C:/Users/..., D:/out). A unix-style /c/Users/...
  breaks require('docx') and makes Python write into a phantom D:\c\...
  folder. From a native cmd/PowerShell these are already correct.

Output deliverables (typical kit)

• 社区村书记综合能力评估方案.docx (master scheme)
• 社区村书记360度评估问卷.docx
• 社区村书记知识测试题库框架.docx
• 书记能力评估数据采集填报表.xlsx (录入 + 分池归一化 + 知识达标)
• 社区村书记日常指导问题记录表.xlsx (台账 + 年终汇总)
• 社区村书记评估权重AHP计算模板.xlsx
• 社区村书记深层特质挖掘工具包.docx
• 社区村书记能力雷达图工具.html + assets/radars/雷达图画廊.html + per-person PNGs
• 批量评估排名汇总.xlsx + assets/batch_radars/批量雷达图画廊.html + 每人雷达图 PNG
  （batch_assess.py 整批产出，支持 100 人以上；读《数据采集填报表》的“多人录入”页）
• 信度检验报告.txt / 信度试测样本数据.xlsx
• 社区村书记胜任力评估实操手册.docx (零基础实操手册，references/docs/)
• 普通员工胜任力模型轻量框架模板.docx (员工版轻量框架，references/docs/)
• 参考文档（references/docs/，非生成物，供学习与排查）：业务人员快速上手指南.md、
  常见问题FAQ.md（问答 + 反模式 + 参数调优表）、methodology.md（公式与推导完整版）

Honest maturity note (surface to the user)

The methodology is design-sound; empirical validation (real pilot α/κ, AHP
pairwise data, and especially predictive validity via 1–2 year longitudinal
tracking) is the remaining gap. Present the system as a decision-support aid,
not an autonomous judge. See methodology.md "成熟度自评估".