投入核算

你要解决的事

用户的原话通常是这样：

"我要填报公司系统，协助分析 9 月 1 号开始在这个项目的投入。" "这个月我在 XX 项目投了多少人天？" "工时填报要逐日的，每天大概几个小时。"

他的处境：工时填报没有客观依据，只能靠回忆 —— 结果要么少报（白干），要么多报（被追问答不上），要么几个项目混在一张工时表里分不清（同一小时双计）。

你要把他从「感觉这阵子挺忙」带到「一张能提交、被追问能当场演示证据的逐日工时表」。

这个技能为什么存在

• 解决什么问题：工时填报缺乏客观依据。销售/售前/FDE 这类跨项目角色尤其严重——工时全挂在一个项目名下，实际分摊到多个项目，项目成本统计失真（实测案例：某角色工时全挂在 A 项目，其中约 1/5 实际属于 B、C 项目）。

• 不解决什么（边界）：

  不做	原因
  不替你决定报多少	口径选择权在用户手里，技能只把三个口径摆出来并给推荐
  不算「未经 AI 工具产出」的工作	大前提：本核算面向 AI Native 工作方式——产出必须经过某个 AI 工具（当前支持 Claude Code）。线下会议、出差、纯手工写文档这类没有 AI 会话痕迹的工作，无法核算也无法证伪，不计入，需另行说明
  不做跨工作空间全盘扫描	只认当前工作空间（含其子目录）对应的会话；跨空间的工作会漏，需人工补
  不适用团队/多人工时	会话记录是单人视角

💡 大前提说明了什么：这套方法能成立，靠的是「工作痕迹天然带时间戳」。 一旦某个动作没走 AI 工具，它就脱离了可核算范围——不是它不算工作，而是它不可证伪。 所以核算结论的措辞永远是「至少这么多」，不是「正好这么多」。

• 决策依据：

  选了	否决了	为什么否决
  会话时间戳做时间基准	让用户自己回忆填表	无证据链，被追问第一句就崩
  同上	按 git commit 数折算工时	提交数 ≠ 工时；夜间批量提交、格式化提交会严重失真
  同上	按 AI token 消耗折算	token 与人的投入非线性，同一个人不同天的 token/小时 差异可达数倍
  会话 span 与有效工时并列给出	只给一个区间	单值经不起质疑；并列才能让人自己判断并说明取舍

💡 为什么"否决理由"要写：只写"选了什么"，后人会问"为什么不按 commit 数算"； 写清了，后人不必重新纠结一遍。

三条铁律

1. 三口径并列，不藏中间值。 下限（可证伪）/ 中性（建议填报）/ 上限。填报值必须落在区间内，且说得清为什么取它 —— 别只给一个数就完事。
2. 必须读会话正文，不能只看时间戳。 只看时间戳会把挂机、以及在同一目录里干的别的事算进来（实测：某天 0.7h 的会话内容其实是查另一个项目的接口，与本次核算无关）。
3. 产出必须落盘 Markdown，且附可复算命令。 未落盘 = 未完成。被追问时要能当场演示"这个数是怎么来的"。

第 0 步：确认工作空间与区间（能推断就别问）

只在两种情况下需要问用户：① 用户说的项目名与当前目录明显不是同一个；② 他要填报的系统有最小粒度限制（如必须 0.5 天起）。

第 1 步：跑时间戳核算

python3 scripts/scan-sessions.py --dir "<工作空间>" --since YYYY-MM-DD --until YYYY-MM-DD

判据：输出逐日「有效工时」表。若提示"没找到会话目录" → 见排错表第 1 行。

先跑一次自检确认脚本没坏（合成数据，秒出）：

python3 scripts/scan-sessions.py --selftest    # 应输出 selftest OK

第 2 步：读会话正文，剔除非本工作空间的事项

python3 scripts/scan-sessions.py --dir "<工作空间>" --since ... --until ... --topics

输出每天的头几条用户消息。逐条过一遍，把不属于本工作空间的事剔出来：

• 同一会话里顺手查了另一个项目的接口/数据 → 剔除该时段
• 纯工具安装、环境调试（不属于本次核算范围） → 视情况剔除
• 剔除后必须在文档里写明剔了什么、剔了多少小时 —— 这是可证伪的一部分

第 3 步：验产出（有产出的日子才值得算工时）

# 文件创建时间（birth time 才是"新产出"，mtime 会被后续编辑刷新）
find <工作空间> -type f -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.git/*" \
  -exec stat -f "%SB|%N" -t "%Y-%m-%d" {} \; | grep -E "^2026-09"

# 各仓提交数
for r in <工作空间>/git/*/; do echo "$(git -C "$r" log --since=YYYY-MM-DD --oneline 2>/dev/null | wc -l)  $r"; done

判据：某天有效工时 > 0 但零产出 → 大概率是挂机或调试，考虑折减。

第 4 步：CHANGELOG 对账（没有就先建一个）

grep -n "^## 2026-09" <工作空间>/CHANGELOG.md

先查有没有 <工作空间>/CHANGELOG.md：

为什么 CHANGELOG 是必需的一环（不是可选优化）：

三源里，会话给时长、文件给存在性、CHANGELOG 给语义 —— 缺了语义， 算出来的就只是一堆小时数，经不起「你这些时间具体做了什么」这一问。

⚠️ CHANGELOG 的日期可能写错（实测：一条标 09-19 的条目，当天零会话记录，内容却与 09-20 的提交一致）。 对不上时以会话时间戳为准，并在文档里标注疑点，不要径自改 CHANGELOG（历史记录只登记不动手）。

第 4 步附：补漏三法（三条交叉校验，专抓"有痕迹但没记"的日子）

前三步（时间戳 / 正文 / 文件）看到的都是「AI 在电脑前」的痕迹。下面三法各用一条独立证据链交叉验证，互相覆盖盲区。

边界（别过度补）：

• 微信只能补「有沟通无痕迹」的日子，不能给每条消息估工时（一条通知 ≠ 1 小时）
• 差集需人工按内容剔除他项目 / 私事的日期
• 会议下界只算可核查的部分（有起止的会），不推算

为什么有效：单一证据源总有盲区（会话被清理、Copilot 无时间戳、线下会议无痕迹）。三条独立证据链交叉，盲区互补，且每条都能对外指认来源。

第 5 步：出三口径 + 逐日填报明细

三口径表（必给）：

逐日明细表（用户填系统直接抄）：

逐日合计必须等于中性口径的人数 —— 不一致就是算错了，回去对。

第 6 步：落盘

写到 <工作空间> 下习惯存放估算的位置（如 资源相关/），文件名带日期戳。

文档必含 6 节：一句话结论 / 估算口径（四源 + 折算规则）/ 逐日明细 / 三口径对照 / 工作包分解 / 边界与未计入项 / 附可复算命令。

边界节必须写（这是"能对外扛"的关键）：

• 哪些时段不算（别的项目、挂机）
• 哪些占用未计入（线下会议、读材料、通勤思考）→ 实际投入可能更高
• 折算里的主观系数及其误差范围
• 如果是分摊而非新增：明写"应从原项目转出，勿双计"

排错

红线

• ❌ 不替用户拍板口径 —— 三个口径都摆出来 + 给推荐，理由写清楚
• ❌ 不把挂机算成工时 —— span 与有效工时的差，必须在文档里说清
• ❌ 不凭文件名猜事项 —— 每天的"主线"必须来自会话正文或 CHANGELOG，猜不出来就写"待确认"
• ❌ 不擅改 CHANGELOG 等历史记录 —— 发现日期疑点只标注，等确认
• ❌ 技能仓里不放客户名 / 项目代号 / 真实业务数据 —— 本技能仓是通用资产，样板留在用户自己的工作空间
• ✅ 落盘 + 附可复算命令
• ✅ 声明"分摊非新增"，防止同一小时在多张工时表里双计