工作体检（work-checkup）
把散落在几百个 jsonl 里的"怎么干活"变成一份能照着改的报告。
核心分工：统计交给脚本，判断交给模型。模型不允许自己估算数字，也不允许读原始 jsonl。
1. 边界
做：读本地会话记录 → 算指标 → 找规则命中 → 解释 → 聚合 → 给可执行建议 → 留快照。
适用任何岗位：销售、设计、HR、财务、运营、科研都会留下 AI 协作记录，六轴指标与画像框架通用。
差别在解释与建议：岗位要由模型依据会话标题、目录名、高频词判断，再按岗位选候选方案；
默认对方是程序员是最常见的错误（详见 judgment.md「按岗位选候选池」）。
不做（越界即失败）：
- 不做绩效、工时、产出排名。审计工作方式，不评价工作价值。
- 不做实时监控、看板、告警。
- 不改用户任何既有文件，只新增报告与快照。
- 不替代代码审查、测试、CI。
- 不做会话内容检索问答——那是搜索，不是聚合。
2. 五步流程
扫描 → 统计 → 分析 → 聚合 → 出报告
（脚本） （脚本） （模型） （模型） （模型+自检）
第 1–2 步：扫描与统计（脚本，阶段 A）
默认全量：本机所有工具目录 × 所有工作区 × 全部时间。
OUT=~/.workbuddy/insights/$(date +%Y-%m-%d)
python3 scripts/stage_a.py --out "$OUT" --depth standard --label "$(date +%Y-%m-%d) 周期回顾"
上面的命令不带任何范围参数，这就是默认口径。不要自作主张缩小范围：少扫一个工作区，
可能正好漏掉问题最集中的那个，而读者不知道你漏了。缩小范围只有一个合法理由——用户在调用前
明确说了范围（"只看某个项目""最近一个月""别算 claude"）。
| 用户怎么说 | 怎么传参 |
|---|---|
| 没说范围（最常见） | 不传：全量 |
| 「最近/近期/这两个月/上季度」 | 只传 --since（必要时 --until），工作区仍然全量 |
| 「只看 X 工作区/这个项目」 | 才传 --workspace X（可加时间） |
| 「别算某个工具」 | 从 --sources 里去掉那个 |
其他档位开关（不影响范围，随时可用）：
| 需求 | 参数 |
|---|---|
| 专项深挖 | --depth deep（每规则 20 条证据） |
| 日常快速自查 | --depth quick（无证据，只能出指标与异常项） |
| 只补增量 | --incremental（复用上次 sessions.json，结果与全量一致） |
一旦裁剪了范围，必须在报告第 1 节写清"本次只覆盖 X / 只到 Y"，并说明是你指定的；
不写就等于让读者误以为是全貌。
脚本产出 sessions.json / metrics.json / findings.json / excerpts/*.md / stats.md / profile.json。
其中 profile.json 是画像事实（工作面、任务摩擦、协作风格、节奏、资产、重复动作），「关于你」一节和
画像图表都用它，不要自己另算。
实测规模：数百个会话、GB 级原始数据、四源全开，约半分钟（M 系列 / Python 3.14）。
第 3 步：读产物，不读原始数据
先读 BRIEF.md（脚本生成，约 2k tokens：样本、12 项关键指标、命中规则各带 2 条证据、画像要点）。
一份全量样本的 findings.json 有 160KB、约 98k tokens，sessions.json 有 1.8MB——
整份读进去，思考和写报告的空间就没了。先看简报，再按需展开：
BRIEF.md—— 默认入口，足够写出一份完整报告的骨架excerpts/<rule_id>.md—— 只有要引用更多证据时才打开metrics.json—— 需要某个指标的完整extra（分布、按工具明细）时再查stats.md—— 第 1 节的样本披露从这里取
原始 sessions.json 只给脚本用，阶段 B 永远不读。
规则命中不等于问题。 回到证据读一遍：这条真的成立吗？阈值被越过但证据不像，就不要写进报告，
并在报告里标注该规则待校准。
第 4 步：聚合与归因
先判置信度，再决定输出形态：
| 置信度 | 允许 |
|---|---|
| 高 | 结论 + 建议 |
| 中 | 结论 + 建议（标注更长观察窗口） |
| 低 | 只出描述性统计与待验证线索，拒绝下结论 |
然后把多个表象归到共同上游因子，形成「1 个根因 → 多个表象 → 1 个整体方案」。
写建议前先跑一次 python3 scripts/check_docs.py：确认本机 CLI 与文档同版本、引用的文档还在。
不一致时先更新引用再写，别把过期入口写进报告。
每个问题定下来之后，先查官方能力：用户主要用的那个工具（看 sessions.json 的 source）自带什么开关，
能不能解决一半。官方文档在本地，几分钟能查完。跳过这一步直接推第三方工具，是最常见的浪费——
让人装了本来就有的东西。
找不到共性就写「暂未归因」，禁止为聚合编造共性。
归因三选一，且决定谁能改：用户习惯 / 工具配置缺陷 / 任务本身性质。
工具问题写成"你要注意"，是本技能最严重的错误。
第 5 步：出报告 + 自检
报告文件名固定，便于历次排序对比：YYYY年M月D日-工作体检报告（不补零）。
名字由脚本给，不要自己拼：
NAME=$(python3 scripts/render_report.py --print-name) # 例：2026年11月4日-工作体检报告
按 references/report-template.md 的九节骨架写到 "$OUT/$NAME.md"，再渲染：
python3 scripts/assess.py "$OUT/$NAME.md" --metrics "$OUT/metrics.json" --findings "$OUT/findings.json"
# violations 非空就改到为空
python3 scripts/render_report.py --report "$OUT/$NAME.md" --metrics "$OUT/metrics.json" \
--profile "$OUT/profile.json" --out-dir "$OUT"
# 输出 $OUT/$NAME.html，文件名与 md 一致
python3 scripts/snapshot.py --metrics "$OUT/metrics.json" --out ~/.workbuddy/insights/snapshots/$(date +%Y-%m-%d).json
# 有上轮快照时追加对比
python3 scripts/snapshot.py --metrics "$OUT/metrics.json" --out ... --compare <上轮快照>
交付物是 $OUT/$NAME.html：单文件、内联 CSS 与 SVG、可离线打开、可直接发人。
同名的 .md 保留作源文件；两个文件同名不同后缀，方便对照。
图表由渲染器从 metrics.json 生成，不许手画数字。
写的时候记住三条（细则在 references/judgment.md 的「可说人话」一节）：
术语首次出现用括号解释成人话；每个数字出现前先说它证明了什么，一段最多三个数字；
建议给两个候选 + 优缺点对比表，别让读者自己脑补取舍。
「关于你」里允许一句带温度的话（最多两句、100 字以内，一段说完），写清处境与代价再还回选择权；
写成安慰长文就跑偏了。
若某个问题行业里已有成熟解法（工具、方法、规范），在建议里追加一小节列出，写清为什么贴合你这次的
具体现象、优缺点、以及可访问链接。链接必须先用 WebFetch 打开确认，凭印象写网址会给出死链。
每问题最多 3 个；需要上传代码或数据的方案要标「需审批」，客户内网环境下不推荐。
只推现在还在用的：先用 GitHub API 或官方 release 页核实最近提交时间，12 个月无更新或已归档的一律不列；
表里带「近况」列（星数 + 最近提交日期），表格上方写核实日期。这个领域半年就换一批，推荐两年前的东西
比不推荐更糟。
3. 四条硬规则
- 每个数字都要能回到指标 ID。
metrics.json里没有的数字不许出现在报告里。
分母为 0 写「不适用」，不写 0%。 - 每条结论挂 ≥1 条证据
[sessionId:序号]，序号是该会话的用户消息序号。
无证据的只能写进「假设」并标待验证。 - 禁止因果断言。「X 导致 Y」改成「X 出现时 Y 占比 a%，不出现时 b%」。
写不出对照数据，降级为假设。 - 反迎合负面清单（
references/judgment.md）：整体表现良好、虽然但是已经很不错、
可能是网络原因、可以考虑/建议关注、值得一提的是——出现即重写。
4. 关键判据速查
| 判据 | 门槛 | 出处 |
|---|---|---|
| 系统性：工作区覆盖率 | ≥ 50%，或跨 ≥3 工作区 | judgment §系统性问题 |
| 系统性：时间持续性 | 跨 ≥3 周 | 同上 |
| 系统性：任务无关性 | ≥3 类任务 | 同上 |
| 系统性 | 以上至少两项（覆盖率/持续性/任务无关性由脚本算，第 4 项共同上游因子人工判） | 同上 |
| 置信度低 | 单工作区、单次、样本不足 | 禁止下结论 |
| 追问上限 | 5 条，每条带 ≥2 个候选解释 | report-template §6 |
| 核心结论上限 | 5 条 | report-template §2 |
| 推荐候选 | ≥2 个，含零成本方案与重方案 | judgment §四段式 |
5. 什么时候读哪个参考
| 场景 | 读 |
|---|---|
| 不清楚字段含义、路径、去重与脱敏口径 | references/data-contract.md |
| 写指标解释、复算数字、判断分母 | references/metrics.md |
| 某条规则命中，要判断是否成立 | references/detectors.md |
| 归因、聚合、反迎合、写建议 | references/judgment.md |
| 开始写报告 | references/report-template.md（九节骨架、写作规则、图表挂载点） |
| 写「关于你」一节 | references/profile.md + profile.json |
| 要判断某个指标偏离多严重 | references/baselines.md（只给自身分布，无外部基准） |
| 给某个问题提建议前 | references/official-capabilities.md（先查工具自带能力的开关） |
不要一次全读。先看 findings.json 决定要打开哪几条规则，再按需读对应章节。
6. 失败与降级
| 情况 | 处理 |
|---|---|
| 目录不存在或无权限 | 脚本会在 run_meta.json 的 skipped 里列出探测过的路径；如实转述给用户，不静默 |
| 单行损坏 | 跳过并计数，写进报告样本披露「丢弃 N 行」 |
| 样本不足 | 只出描述性统计与待验证线索，明确说明为什么不下结论 |
| 耗时超限 | 降级为 --depth quick 并声明，不产出半成品报告 |
| 字段字典与新数据不符 | 以实测为准更新 data-contract.md 与适配器，并记差异，不中断运行 |
7. 交付前检查
- [ ] 未指定范围时用的是全量（无
--workspace）；若裁剪过，第 1 节写明了范围与指定来源 - [ ] 报告九节齐全，顺序未变，没有附录与复算说明
- [ ] 「关于你」七块齐全（一句话/工作面/协作方式/费劲的活/工作习惯/节奏/已建成），每条断言都有数字
- [ ] 工作习惯四条都落到具体动作，或明确写「不用改」；没有把习惯说成性格
- [ ] 所有「偏高/偏低」都写了参照物（上轮快照 / 你自己各工作区的分布），没有编造标准值或行业均值
- [ ] 岗位判断有具体依据（标题/目录/高频词），建议池与岗位匹配，没给非技术岗推编程工具
- [ ] 每个数字都有指标 ID；
assess.py无 violations - [ ] 每条核心结论有
[sessionId:序号]，抽查 3 条能在excerpts/里找到 - [ ] 自造词/内部词首次出现都有括号解释；没有整段只有数据没有判断的段落
- [ ] ≥1 个系统性问题覆盖 ≥2 个表象，并写清被排除的替代解释
- [ ] 每条建议含症状、根因、两个方案、优缺点对比表、推荐理由
- [ ] 行业方案（若有）逐个给了贴合依据、优缺点与链接，链接已实测可访问
- [ ] 若补了实践经验，写明机制与失效条件，且没有包装成研究结论
- [ ] 每个问题都先查过官方内置能力，能在工具内解决的没有推外部工具
- [ ] 引用了官方文档时，check_docs.py 通过（版本一致、文档未变）
- [ ] 行业方案均 12 个月内有更新，表内带「近况」列，表上方有核实日期
- [ ] 样本披露含：工作区数、会话数、跨度、去重数、自动化会话占比
- [ ] 已生成
YYYY年M月D日-工作体检报告.html，md 与 html 同名，图表由脚本从metrics.json生成 - [ ] 无未脱敏的客户域名、内网主机、凭证片段
- [ ] 已写快照；有上轮快照时已生成对比（无基线则明示）
