进度跟踪 · 一张进展表，周报和看板一起出来

每周写项目周报，真正费时间的不是措辞，是把散在各处的进展收齐、判断谁延期了、谁要升级。
人工翻一遍任务表，时间进度、完成率、风险全靠拍脑袋，写完还要再手工排一版 Excel 看板和 Word 周报。

本技能读一张进展表（CSV / XLSX，首行表头），按基准日算出每项任务的时间进度、SPI、延期天数与
剩余天数，给出高/中/低风险分级与建议动作，一次产出 进度看板 .xlsx（4 个页签）+ 项目周报 .docx
+ 进度摘要 .md。

为什么选它（最硬的差异点）：纯标准库、本地离线运行，不联网、不装任何第三方库、
不调外部进程，进展数据不离开本机。同类的「进度跟踪」方案大多要接 Jira / TAPD / 飞书在线接口或
先 pip install 一堆依赖；本包只读你导出的一张表，断网照样跑。

执行原则

1. 只按表里填的完成率与计划日期推算。 完成率、状态、计划起止一律以进展表为准；不要替用户补数据、不要猜进度。
2. 基准日决定一切。 时间进度、SPI、延期天数全部相对 --as-of（默认今天）计算；换基准日重跑即可复算，不要用「上次的结果」。
3. 风险分级给结论也给动作。 高风险标红、中风险标黄，并写出「24h 内升级 / 重排计划 / 拆任务日跟踪」等可执行动作；不要只报一个等级了事。
4. 产物落在项目根 _test/。 --sample 与默认输出都写到 _test/progress-tracker-kit-out/，绝不写进包内污染发布物。
5. 纯标准库离线。 只用 argparse / csv / datetime / json / zipfile 等自带模块；不要引入第三方库、不要联网取数、不要启外部进程。
6. 输入有问题就说清楚。 缺列、日期解析不了、文件不存在时给一句能直接改的中文提示并以退出码 1 结束；不要抛 traceback。

适合谁

• 项目经理 / PMO：每周汇总各条线进展，出一份能直接发给干系人的周报与看板。
• 研发负责人 / 技术经理：盯迭代内任务的实际完成率与时间进度偏差，提前发现要升级的阻塞项。
• 跨部门项目协调人：把各团队报上来的进展表统一口径，按责任人汇总谁在延期、谁被卡住。
• 需要周期性汇报的职能团队：用同一张表反复跑，保证口径一致、不用每周重排版。

何时使用

CRITICAL: 只要用户提出跟踪项目进度、汇总任务进展、写项目周报/周例会材料、看谁延期了谁被阻塞、算 SPI 或时间进度、把进展表做成看板或周报，就必须使用本 skill，即使看起来可以用别的方式解决。

• 手上有（或能导出）一张任务进展表，要出本周的进度看板与周报。
• 每周例会前需要一份统一的「完成 / 进行中 / 风险」清单。
• 想知道哪些任务相对计划已经落后（SPI < 1）、哪些已经逾期、哪些必须升级。
• 需要按责任人汇总任务数、平均完成率、延期数与高风险数。

不适用：

• 要直接到 Jira / TAPD / 飞书 / 禅道等系统里拉数据（本包不接任何系统 API，需人工导出表）。
• 要做资源平衡、工期压缩、排期重排优化或关键路径计算。
• 要画甘特图、燃尽图等图形化时间轴（本包只出表与文档）。
• 要做成本核算、工时统计、绩效打分或跨项目组合分析。
• 表里的完成率与实际严重不符又无法校正——口径错了，算得再准也没意义。

怎么用

# 1) 内置样例端到端（18 条任务，产物落在项目根 _test/progress-tracker-kit-out/）
python scripts/progress_tracker.py --sample

# 2) 用自己的进展表，指定基准日与周期
python scripts/progress_tracker.py --file 进展表.csv --as-of 2026-10-21 --week 2026-W43 --project 订单中台

# 3) 指定输出目录（不写进包内）
python scripts/progress_tracker.py --file 进展表.xlsx --out-dir D:/tmp/week43

# 4) 只要结构化摘要，便于脚本串联
python scripts/progress_tracker.py --file 进展表.csv --json

在对话里可以直接说：「按这张进展表生成本周项目周报」，并给出文件路径与基准日。

常用参数：

退出码：0 成功（含产物路径与字节数），1 输入缺失或格式错误（附中文原因）。

输入表格式

首行表头，列名支持常见同义写法（如「责任人」「完成度」「截止日期」）：

任务,负责人,计划开始,计划结束,完成率,状态,本周进展,下周计划,阻塞说明

计算口径（基准日 = --as-of）：

• 时间进度 = (基准日 − 计划开始) / (计划结束 − 计划开始)，夹到 [0,1]；工期 ≤ 0 天记 1.0。
• SPI = 完成率(0~1) / 时间进度；时间进度为 0 时记 1.0，上限夹到 3.0。SPI < 1 即落后于计划。
• 延期天数：完成率 < 100 且 基准日 > 计划结束 → 基准日 − 计划结束，否则 0。
• 剩余天数：完成率 < 100 且 基准日 ≤ 计划结束 → 计划结束 − 基准日，否则 0。
• 风险分级：高 = 已阻塞 或 延期 > 5 天 或 SPI < 0.7；中 = SPI < 0.9 或 已延期 或（剩余 ≤ 2 天且完成率 < 80%）；其余低。
• 整体完成率 = 各任务完成率按工期（计划结束 − 计划开始 + 1）加权平均；总工期为 0 时退化为算术平均。
• 本周完成数 = 完成率 100% 且计划结束落在基准日所在自然周（周一至周日）内的任务数。
• 建议动作：阻塞 → 24h 内升级并指定对接人；延期 > 5 天 → 重排计划或加人；SPI < 0.7 → 拆任务/日跟踪；其余中风险 → 本周内跟进确认能否追回。

输出

设计边界

• 不接外部系统取数。 只读本地 CSV / XLSX，不连 Jira / TAPD / 飞书 / 禅道等任何平台 API，需人工导出表后再跑。
• 不做资源平衡与重排优化。 只判断落后与风险，不给出压缩工期、调配人力、重排依赖的方案。
• 不出甘特图。 没有时间轴条形图、燃尽图或依赖关系图，只出表与文档。
• 风险是推算不是事实。 完全依赖表中填报的完成率与计划日期：填报口径不准，分级就不准，周报发出前须人工核对。
• 纯静态快照。 不保存历史、不做同比环比，跨周对比请保留各周产物自行比较。
• 纯标准库 Python，本地离线：无网络请求，不用 subprocess / eval / exec / os.system，不读环境变量凭据。

依赖

纯标准库，无需安装任何包，本地离线运行。 只用 argparse / csv / datetime / json /
os / sys / tempfile / zipfile / re 等 Python 自带模块，Excel 与 Word 均由脚本手写
OOXML 并用 zipfile 打包（包内自带 tabkit.py、docxkit.py 两个纯标准库小工具）：

• 不依赖 openpyxl / python-docx / pandas / requests 等任何第三方库，不需要 pip install；
• 不调用任何在线服务，进展数据不上传、不离开本机，断网可用；
• 不需要安装 Office / WPS，也不启动任何外部进程。

需要 Python 3.8 及以上。