毕业条件、支持策略与数据兼容承诺
这份文档回答三个「用户会问、而仓库以前只在散文里顺带提过」的问题：
- 什么时候算正式版（毕业条件）
- 什么环境被支持（支持策略）
- 我的数据会不会因为升级打不开（数据兼容承诺）
相关决策留档：decisions/ship-once-per-release.md（单一发布节点与月粒度 CalVer 版本）、decisions/read-missing-columns-as-empty.md（兼容条款的技术实现）、decisions/keep-writes-human-confirmed.md（写入边界）。
一、毕业条件（首个正式发布即 1.0-equivalent）
毕业不是「功能攒够了」，而是可判据的稳定。四条全部满足才算毕业：
| # | 判据 | 怎么核 |
|---|---|---|
| 1 | 连续 14 天自用无阻断缺陷 | 期间每天至少走一遍真实流程（看板 → 投递 → 邮件/面试记录 → 简历或题库），出现「必须绕过或改数据才能继续」的问题即重新计时 |
| 2 | 主流程冒烟全过 | 八页 + 命令行主流程（init / track / jd / apply / resume / export）在同一版本上跑通；CI 全部 job 绿（后端 / MCP / 前端 / UI 冒烟 / 安装冒烟 / exe 冒烟 / PR 标题） |
| 3 | 无未决阻断问题 | 没有挂着未修的 P0 / MAJOR 级审查发现；已知边界写进文档而不是留在 issue 里 |
| 4 | 兼容条款生效 | 下面第三节的四条在最近一次升级里被真实验证过（旧工作区直接打开、无需迁移） |
毕业判定（2026-10-09）：四条全部满足——① 连续 14 天自用无阻断（dev 栈，2026-09-26 起）；
② 主流程冒烟全绿（八页 + 命令行 + CI 全 job，同一版本 26.10.0）；③ 无未决 P0/MAJOR；
④ 兼容条款经 26.10.0 升级真机复装（真下载 → 安装 → 打开旧工作区）验证。判定证据归档在
releases/26.10.0-verification.md。
未满足时的诚实说法：版本仍是「自用可用」，不是「正式版」——本仓库不靠把版本号写成 1.0 来暗示稳定。
二、支持策略（按版本与日期表述）
| 维度 | 支持范围 |
|---|---|
| 发布版本 | 只支持最近一次发布（与 ../SECURITY.md 同口径：修复只落在最新版；更早的版本请先升级再报问题） |
| 运行环境（命令行 / 后端） | Python 3.12（验证基线，<3.12 会被自检拦下）；标准库为主；pypdf（PDF 校验）与 certifi（出网证书兜底）随后端依赖声明安装，缺失时对应能力降级并给出可读错误；PDF 生成需本机 Chrome 或 Edge |
| 桌面端 | Windows 安装包（主目标平台；真机冒烟后才发布，正式包复装见 release-checklist.md 的「发布后完整验证链」）；其他平台未验证，不承诺 |
| AI 宿主 | CodeBuddy、Claude Code（.codebuddy/、.claude/ 落点）；跨运行时 ~/.agents/skills/；MCP 宿主（Gemini CLI、Codex、VS Code 等）按 mcp-integration.md 配置；DSH（DeepSeek Harness）走插件包 dsh-job-workbench——宿主版本用 peer 声明参与准入（越界即组合包跳过；官方 compatibility.json 可豁免），兼容区间与放宽路径见 ../integrations/dsh/README.md §七 |
| 数据位置 | 全部本地：工作区在你的目录里（新装默认 <系统用户数据目录>/job-workbench/data，详见下文「升级路径 · 数据位置」）；凭证在系统安全存储（Windows 凭据管理器，工作区 config/ 只留引用）；无项目方云端、无遥测。联网只发生在你启用的功能：AI（BYOK）/ IMAP（你的邮箱）/ JD 抓取 / 启动后一次更新检查——明细以 data-flow-matrix.md 为准（隐私承诺的权威底稿） |
| 不支持的用法 | 自动投递、代登录、把工具当服务端多用户使用（见 ADR keep-writes-human-confirmed.md） |
安全相关的取舍（如自动更新链未签名）单列在 ../SECURITY.md，不在本文里重复。
三、数据兼容承诺（工作区格式）
一句话：升级永远不需要你转换数据。
- 读时缺列按空值：新版本加了列，你手上的旧 CSV 直接读，缺的列当空处理。
- 写时统一表头：写回时按当前表头落盘，缺的列补空——你不需要手工对齐列。注意：手工新增的列不会被保留（写出时按工具的表头重排，多余列连值一起消失）；需要承载额外信息请用既有的备注 / 标签字段，不要手加列。
- 不要求迁移：没有「升级前请先跑迁移脚本」这一步——加列、加表都不会让你动数据。
- 破坏性变更走过过渡：真要删除或改名列，先登记为废弃（读时兼容），至少一个发布节点后才移除，并在
CHANGELOG.md的「破坏性变更」里显式列出影响与迁移办法（Keep a Changelog 的 Deprecated → Removed 纪律）。
自检：python tools/jobws.py track check 会点名必填列缺失与枚举外的取值——它是这套承诺的可执行面。
排练（2026-10-02，#208）：上面四条不是散文承诺——tests/fixtures/workspaces/ 下有三组
版本化夹具（v0.3 老表头 / 缺列 / 坏输入），tests/test_workspace_compat.py 每次 CI 都跑一遍
「打开 → 读 → 改 → 重读 → 校验」（含「读路径绝不改文件」与坏输入响亮报错的断言）。
备份一侧另有 tests/test_snapshot_restore.py（30 条）守着那条原则：能生成 zip ≠ 有备份，
restore 验证过才算。
已知边界（写清楚比含糊兜住更有用）：
- 手工改坏表头（例如把「当前阶段」改成别的名字）不在兼容范围内，自检会报必填列缺失。
- 编码被改成非 UTF-8、两列同名这类「用户侧的结构破坏」同样不支持，但错误信息会指向具体列。
- 删除类操作不可逆：删前会写一份整表快照到工作区之外（可整份拷回），但工具不提供「一键撤销」。
四、升级路径
- 桌面端：内置自动更新（下载与重启各问一次）；也可直接下载新安装包覆盖安装。
- 命令行 / 源码：
git pull后重跑python tools/jobws.py skills install（技能 / 命令 / 子代理三类资产一次同步）；--link可选，指向真源、免同步。 - 升级前：建议整份拷走工作区目录（它就是你的数据，没有隐藏状态）。
数据位置（2026-10-05 起，数据根契约 B3）
- 新装默认：
<系统用户数据目录>/job-workbench/data（Windows 即%APPDATA%\job-workbench\data）——四端（命令行 / AI 宿主 / 插件 / 桌面端）共同计算，不依赖安装或仓库位置。 - 老用户不受影响：旧默认位置（仓库 checkout、
%APPDATA%\job-workbench顶层）已有真实工作区的，原样继续使用，不会被搬迁或改名；诊断（jobws doctor/ 设置页「数据位置」卡）会如实标注来源与候选。 - 想搬家：
jobws data-root migrate <新位置>（默认只出计划，--apply才执行；中断可续跑、事后可回滚），或在设置页「数据位置」卡里预览 → 确认。旧目录在迁移后不会被删除，观察期清理由你裁决。 - 便携模式：改为显式选择——数据旁放
portable.txt标记才生效（源码与打包形态同一判据）；「目录可写就便携」的旧规则已退役。
五、这份文档怎么维护
- 判据变了（例如毕业条件的时间门槛）→ 改本文并在
CHANGELOG.md的Changed里记一条。 - 新增一条「已知边界」时，优先问：能不能改成自检能报出来的错误——能报的就不该只写在文档里。