跳转至

求职工作台 · 使用手册

English（主版）：usage-guide.md ｜ 本文件是简体中文同步版，内容与主版一致。

从零开始把工作台跑起来，以及日常使用的完整说明。

遇到问题先看最后的「常见问题」，覆盖了黑屏、端口占用等已踩过的坑。

一、一次性环境准备

只需做一次。已配好可跳过。

必装

软件 用途 检查命令
Python 3.12+ 后端与 CLI 脚本（3.12 是支持与 CI 验证的基线；3.9+ 或可运行但未验证） python --version
Node.js 18+ 前端构建 node --version
Chrome 或 Edge PDF 生成（headless 渲染） 一般自带

安装依赖（各一次）

# 后端依赖（上限已随 3.12 基线逐步放宽、每条跑全量回归后才合；当前值见 web/backend/requirements.txt）
cd <仓库目录>\web\backend
pip install -r requirements.txt
# 后端启动时导入领域包（jobws_core），缺了 uvicorn 会直接退出：
pip install ../../packages/jobws-core

# 前端依赖
cd <仓库目录>\web\frontend
npm install

初始化你的工作区（已有 personal/ 的跳过）

python tools/jobws.py init --target personal --domain hvac-cooling

插件换成你专业的：--domain 可选值见 docs/README.md 的「领域插件」表（含适用人群）。

把 AI 工作流分发到你的 AI CLI（用桌面安装包的用户也要跑一次）——评分 / 投递 / 追踪这些 AI 技能靠这一步分发，不跑的话 Web 界面正常但 AI 侧没有工作流：

python tools/jobws.py skills install --target user

只想先看看界面长什么样、不想先填任何真实信息的话，用 --demo：

python tools/jobws.py init --target demo --demo

它会额外铺一份占位数据（8 条投递 / 3 场面试 / 2 位联系人 / 1 个 Offer / 3 场宣讲会 / 6 道题 / 6 封邮件 / 7 张解析卡 / 1 份简历），公司与人名全是假的，可以直接上手体验或截图； 同时会默认装入 software-backend 插件（demo 数据的方向字段依赖它）。 启动后在右上角工作区下拉里选 demo 即可。

填档案：AGENTS.md（评分的前置条件）

init 之后，工作区根目录会生成 AGENTS.md（模板与逐项说明见 template/AGENTS.example.md）。第三节「硬门槛事实」必须填——学历 / 专业 / 届数 / 英语 / 城市，是岗位评分工作流硬门槛判定的唯一事实源：

  • 不填的后果：字段停留在 [待填] 的岗位会被判成「待补档案」——不打分、不终止，但也没有结论；
  • 填好之后：硬门槛按事实判定，只有明确不满足才终止；
  • 城市要求分两级：硬性不可行（要求本地户籍、必须长期驻外）才判不通过；"本地优先"这类偏好只在「培养与稳定性」里轻度扣分（-3 / -5，合计不超过 5），不再一票否决。

第五节是自定义红线（默认两条：简历动词经得起追问、不编造经历），按需追加。

二、日常启动：Web 界面

方式一：一键启动（推荐）

cd <仓库目录>\web
.\start.ps1

脚本会自动：清掉被占用的端口 → 启动后端（8765）→ 启动前端（5173）→ 等待就绪 → 自动打开浏览器。

关闭方式：关掉脚本所在的控制台窗口，两个服务一起停。

方式二：手动启动（需要看后端日志时用）

开两个终端：

# 终端一：后端
cd <仓库目录>\web\backend
python -m uvicorn main:app --port 8765

# 终端二：前端（Windows 必须用 npm.cmd，直接跑 npm 会静默失败）
cd <仓库目录>\web\frontend
npm.cmd run dev

访问地址

地址 是什么
http://localhost:5173 工作台界面（日常用这个）
http://localhost:8765/docs 后端 API 交互文档（FastAPI 自动生成）

前端把 /api 请求代理到 8765，所以浏览器只跟 5173 打交道。

方式三：双击 exe（免环境，适合给别人用 / 快速查看）

构建产物在 web/backend/dist/job-workbench-backend/，双击其中的 job-workbench-backend.exe：

  • 没服务在跑 → 启动后端 + 自动打开浏览器（黑色控制台窗口是服务日志，关掉=停服务）
  • 服务已在跑 → 直接打开浏览器，不会重复起服务
  • 端口被其他程序占用 → 人话提示，窗口保持打开（不会闪退）

⚠️ exe 是"干净分发物"，不读你的个人数据。便携版的工作区在 exe 旁边（personal/，默认为空）——这是刻意设计，避免你的求职数据随安装包散播。自己日常用方式一/二（数据在仓库根）；exe 用来验证产品或发给别人。硬要 exe 读自己的数据，设环境变量 JOBWS_DATA_DIR 指向仓库根（不推荐，容易数据分叉）。

重新构建 exe：

powershell -ExecutionPolicy Bypass -File scripts\build_backend_exe.ps1

桌面安装包（Electron 壳，v0.1.1 起）

不想配环境可以用 Release 里的 job-workbench-setup-*.exe（Electron 窗口 + 打包好的后端，双击装完即用）。数据目录：安装版在 %APPDATA%\job-workbench\personal\，绿色版（backend exe 旁有 portable.txt）在 exe 旁 personal\——卸载安装版不影响 %APPDATA% 里的数据。

安装包现在是向导式：可以自选安装位置，并选择「为所有用户 / 仅为我」。升级旧版时请沿默认选项（「仅为我」+ 原目录）——选「所有用户」会装到 Program Files 并与旧安装分叉。静默安装仍可用：/S（/D=<目录> 可指定位置）。

桌面版可以调界面缩放：设置页的「界面大小」滑块（拖动即预览，整个界面含文字一起缩放），或 Ctrl + = 放大、Ctrl + - 缩小（0.5 级步进，约 0.58x–1.73x）、Ctrl + 0 复位；级别会记住，重启沿用，滑块与快捷键互相同步。

一键重建安装包（前端 dist → PyInstaller 后端 exe → NSIS）：

powershell -ExecutionPolicy Bypass -File scripts\build_desktop.ps1

产物在 web/electron/release/job-workbench-setup-<版本>-win64.exe（产品名英文化为 Job Workbench：安装包与开始菜单项是英文；窗口标题跟随界面语言）。冒烟：<安装包> /S 静默安装到默认的「仅为我」位置（/D=<目录> 可指定位置），启动后验证 http://127.0.0.1:8765。

三、Web 界面八个页面

看板（首页）

打开就是它。回答三个问题：投了几家、几家还在流程中、接下来七天该干什么。

  • 顶部四张统计卡：投递总数 / 流程中 / 近七天待办 / 已过截止（点击可下钻到追踪表）
  • 投递漏斗：每个阶段多少人（待投→已投→笔试→…→签约），点柱子按阶段下钻
  • 待推进：健康度异常（紧急/逾期/停滞）的活跃岗位清单，每条带具体理由，点击下钻
  • 近七天待办：下次动作日期或截止日期落在未来 7 天的记录（可一键顺延 7 天）
  • 近 7 天宣讲会：宣讲会 / 招聘会里时间落在未来 7 天的活动（点条目直达「准备」页的宣讲会页签）
  • 已过截止提醒：还停在「待投」但截止日期已过的记录（红色）
  • 静默提醒：长期无进展的活跃岗位（默认超 14 天）
  • 周期复盘：阶段转化率（从时间线重建）、停留中位天数、失败归因与失败原因聚类

追踪表

所有投递记录的表格。六件事：

  • 筛选与搜索：按阶段 / 方向 / 批次过滤，关键字搜公司、岗位或备注
  • 排序：下次动作日期 / 评分 / 停留天数 / 健康度（紧急 > 逾期 > 停滞 > 正常，徽章悬停显示理由）
  • 改状态：点某行的「当前阶段」下拉框直接改（待投→已投→笔试…），改完自动保存
  • 新增与批量导入：右上「新增投递」逐条录入；「批量导入」粘贴或上传 CSV，先出差异预览（新增/重复/错误分色，带行号与原因），有错误行时禁提交
  • 状态原因：每行就地编辑；进入「已挂 / 已放弃」必须填原因，且这两态一旦进入就不可再改阶段（想重新投要新建一条）
  • 行展开：查看该记录的变更时间线与当前阶段停留天数

两条约束（CLI 与网页同源，自动拦）： 1. 终态不回退：已挂 / 已放弃后「当前阶段」锁定，只可补状态原因与备注 2. 同公司+岗位去重：重复录入会被拦截并提示既有记录 id（挂了之后再投一次则放行）

方向下拉框的选项来自工作区装入的领域插件（config/directions/），不是写死的。

岗位池

管理你看过的岗位。每张卡片显示公司_岗位、评分、档位。

  • 新建岗位：粘贴完整 JD 原文（职责+任职要求）系统原样存档；或粘贴网页链接自动抓取正文（需登录 / 反爬 / 纯 JS 渲染的页面会明确提示手动粘贴，不假装成功）
  • 点开详情：左边 JD 原文，右边解析卡
  • 资格硬门槛（置顶优先）：解析卡顶部的「资格硬门槛」卡片先于分数展示——通过（绿）/ 不通过（红）/ 待补档案（琥珀：档案缺事实，不打分、不终止，卡片点名缺哪些字段并指向 AGENTS.md）/ 待确认（中性描边）四态。不通过时明确标红置顶，这时分数是次要信息（说明资格不够，别投）
  • 评分下钻：四维（技术/经历/方向/培养）每条可点开，展开逐条命中明细——每条带能力分层（Primary/Secondary/Weak）+ 证据标签（精确/模糊/语义徽章）+ 命中说明。想知道"为什么得这个分"点开看
  • 简历差距面板：该 JD 与你简历的差距清单，区分「可召回」（母版里有）与「真实缺口」（只能补经历）
  • 解析卡：评分由 AI 在 CodeBuddy 里完成后写入 解析卡.md，这里自动显示四维度进度条 + 总分 + 档位
  • 还没评分的岗位显示"尚未生成解析卡"及操作指引——网页不做评分，评分是 AI 的工作

简历工坊

双模式：

  • 标准版式（数据驱动）：左结构化表单、右 A4 实时预览；页面直接新建版本；生成 PDF 后回显 ATS 校验与纸型检查；含防超页护栏
  • 版式与强调色：版式下拉内置经典 / 紧凑 / 强调三套（全部单栏、过 ATS 校验；紧凑适合内容多、要压一页）；强调色四档（石墨灰 / 商务蓝 / 深墨绿 / 酒红）与版式自由组合，切换即刷新预览，生成的 PDF 与预览同源。命令行等价物：resume render --template std_compact --resume-accent 酒红
  • 一键导入：上传 PDF / Word(.docx) / Markdown / 纯文本 → 抽取成结构化字段。抽取而非生成：模型未抽到的字段标黄、疑似补全的标红，核对页逐段确认后才落盘
  • AI 改写建议：BYOK 模型只改写既有事实的表述，反编造护栏不过不能采用
  • 导出 Word：零依赖 .doc，方便往网申系统粘贴文本（排版以 PDF 为准）
  • 高级模板（手写 HTML 精排版）：只读浏览与一键生成

底部还有版本谱系：哪版简历投了哪些岗位、各走到哪一步。

准备

投递之前的事归一处——宣讲会、题库与笔记都在这里（2026-09-18 从「进展」页迁来：那页的定位是"投递之后"，这两件恰恰在投递之前）：

  • 宣讲会 / 招聘会：活动时间、形式、地点与收获，可导出 .ics（提前 1 小时提醒）；不推进任何阶段。看板「近 7 天宣讲会」点一下直达这里
  • 题库（两个视图）：「我的题库」= 自建可编辑的 questions.csv（领域 / 科目 / 状态 未看·看过·会了 / 答案要点），可从 03_面试准备/**/*.md 只读解析 → 预览 → 确认导入（两段式）；点任意一行打开详情，在弹窗里改答案要点、标记三态、调难度、改标签与备注——同样先看差异表再确认（确认前不落盘，取消不留痕）；「被问过的」= 面过的问题按公司 + 岗位归集、关键词检索——面试前先过一遍这家公司问过你什么；命令行可 jobws bank export --csv <文件> 导出整个题库、jobws bank import-csv <文件> 从 CSV 导入（预览后凭令牌落盘；导出再导入是幂等的）、jobws bank due 看今日待复习（未看恒在；看过 3 天 / 会了 14 天；空/脏数据保守计待复习）、jobws bank wrong 看错题本（--add/--remove <题目id> 标记——标记就是给「标签」加/去「错题」，界面里在题目详情改标签同效）；jobws bank delete 删题——单题 --id Q012，误导入想整批撤回用 --origin 导入 --today（也可按 --domain / --subject / --keyword / --company 组合）——同样先给「将删哪几行」的预览，确认后凭令牌落盘，落盘前把整表快照写到工作区之外（默认 <快照根>/<工作区名>/question-deletes/questions-before-delete-<时间戳>.csv，jobws apply 会打印确切路径；恢复 = 回到删除前一刻的整表状态，把那份 CSV 复制回 05_投递追踪/questions.csv——删除之后的其它改动会一并被冲掉）。落盘前还核对行指纹（id + 题目 + 领域 + 科目 + 创建日期）：id 会被复用，预览之后那一行被改过或被新题顶替就整体拒绝、要求重新预览。界面里在题目详情弹窗底部点「删除这道题」同效（批量删只在命令行）
  • 新增题目（2026-09-21）：面板顶部的「新增题目」自拟一道题入库——填领域 / 科目 / 难度 / 答案要点，先预览将写入的字段、确认后落盘（与 CLI jobws bank add、MCP preview_add_question 同一份校验）；列表每行还会带「待复习」与「错题」徽章——到期按复习间隔算（未看 恒在、看过 3 天、会了 14 天），鼠标悬停徽章能看到"为什么算到期"；错题按标签判定（与训练面板同一套标签口径）
  • 训练（题库的「练」入口）：抽题 → 盲答（答案默认折叠）→ 展开对答案 → 自评三态 / 标错题 → 下一题。三种模式：重练队列（错题 ∪ 今日待复习）、只错题、随机；可按领域 / 科目 / 状态 / 关键词收窄。写操作零新增（自评改「状态」、标错题改「标签」，都先看差异再确认）；命令行同效：jobws bank drill --mode due|wrong|random --n 5。三处口径要留意：本轮存在会话里——每写一题工作区指纹会触发整页刷新，抽到的题与进度（含折叠状态）会原样回来，不会被刷新清空；「未看」在状态本来就是未看时不发写请求（没有可写的差异），直接进下一题；「看过」按复习规则不写「最近复习」，该题因此仍在重练队列里（未看 / 看过但没记录 → 保守计待复习），要让它 14 天后才再出现就点「会了」。一轮走完的结束卡会给出本轮真正落盘的写入数（取消 / 预览失败 / 冲突不计）与题库三态现状——"会了"在涨才是进度。可以全程用键盘：空格 / Enter 看答案、1 / 2 / 3 三态自评、W 标错题、← / → 上一题 / 下一题、Esc 关掉确认卡（请求在飞时 Esc 不响应）；焦点在输入框或下拉里时不抢键——打开「一轮题数」下拉后空格不会变成"看答案"，盲答纪律不被自己破坏
  • 笔记：03_面试准备 与 04_知识库 的 Markdown 直接读——左侧目录树（README 显示为「目录说明」、_模板_/_示例_ 淡显、空文件与读不了的文件带标记、可按文件名过滤），右侧渲染成正文（标题 / 列表 / 勾选框 / 表格 / 代码块 / 引用），长文右侧有「本页大纲」，超 256 KB 截断并显式告知。改内容用自己的编辑器，切回来 10 秒内自动刷新（并回到原页签与原文件）；勾选框可点——点一下弹出「原行 → 新行」差异，确认后只改这一行的一个字符，文件其余内容一个字节都不动（走全站唯一的两段式写通道；预览之后这一行若被改过则拒绝并要求重新预览）；全文搜索可按关键词搜文件名与正文，点结果直接打开并滚到命中行（命中过多只列前 50 条并说明；读不动或超过 256 KB 的文件会列出"没搜全"，不静默少给）

进展

投递之后的主战场，四个子 Tab：

  • 面试：三段式记录（问题 → 回答要点 → 复盘），48 小时内待定的琥珀高亮，一键导出 .ics 日历
  • 邮件：往来邮件台账（面试邀约 / 笔试通知 / 拒信…）——可关联投递记录、标签行内改；有 Message-ID 的邮件给「打开原邮件」（Gmail 搜索深链），无可用深链的邮箱（Outlook / QQ / 163 等）给「复制主题去邮箱搜索」的降级提示；会议链接列承接解析出的入会地址（腾讯会议 / Zoom / Teams / Meet…）；邮件不会自动改阶段
  • 联系人：招聘方联系人跟进节奏，超期琥珀提醒，一键「已联系」
  • Offer 对比：多个 offer 的已知事实并排，只并排、不推荐

素材库

事实库（00_事实库/）的只读浏览（由 CLI / AI 生成维护）：事实卡以正文排版显示（表格 / 勾选框 / 引用 / 代码块），超 256 KB 截断并显式告知；外部改完切回来 10 秒内自动刷新。简历相关文件已迁往「简历工坊」（2026-09-03），此处不再重复展示。

设置（Provider）

导航栏「设置」页配置 AI Provider（BYOK，自带 key）：

  • 服务商预设：从下拉选一家（DeepSeek / 智谱 GLM / 通义千问 / Kimi / 硅基流动 / OpenAI），地址模板自动填入；也可选「自定义（兼容 OpenAI）」手填任意兼容端点。地址写法有问题时只给非阻断提示（例如通义千问必须用 …/compatible-mode/v1、不要把 /chat/completions 当 base_url 填），不拦你保存——很多网关的路径本就是自定义的。
  • Base URL：OpenAI 兼容端点（含 /v1，如 https://api.orcarouter.ai/v1）
  • API Key：只存本地，界面只显示脱敏后的末尾 4 位
  • 默认模型：在这里设一次，简历导入 / 简历改写 / 邮件 AI 三处共用；三处仍可就地临时改，但那是本地覆盖，不会改掉这里的默认值。留空则三处都要求手填。
  • 测试连接：调 {base_url}/models 验证 key 有效并列出模型（同时给出总数与"只显示前 N 个"的说明）；返回的模型名是可点的小胶囊，点一下即填入默认模型。拉不到列表不代表不能用——有些服务没实现 /models，直接手填模型名即可。出网 HTTPS 默认校验证书（抓取 JD、简历改写同一策略）：本机证书库加载失败时会拒绝连接并提示修证书库（certmgr.msc），不会静默跳过校验——key 不会在未校验的连接上发出。显式降级用 JOBWS_HTTP_TLS=insecure（不推荐）
  • 数据与隐私：整包导出 zip、快照备份到系统用户目录、快照一键还原（先演练后落盘）、诊断包导出（版本 / 平台 / 自检摘要 / 日志尾部——不含工作区数据与凭证）、打开数据目录、无遥测声明
  • 到点提醒：开关 + 「提前几天」（3 / 5 / 7 天）；通知按事项每天一次，点通知直达追踪表对应记录（详见「进展」章的完整口径）
  • 设置页可搜索（含 @modified 只看改过的项）与单项还原；改动项带标记
  • 导成 Obsidian 笔记（命令行）：python tools/jobws.py export --obsidian <目录>——八张 CSV 各成一个目录、每行一笔记，frontmatter 带上原表全部字段（供 Obsidian Bases / Dataview 过滤排序），题库笔记带 spaced-repetition 卡片语法；输出目录带时间戳、不覆盖旧导出、不改工作区（是快照，不是同步）。加 --notes 另把 03_面试准备 / 04_知识库 / 00_事实库 的 Markdown 投影成笔记（保留目录层级、全量不截断、正文按原意搬运），这样手机上除了刷题也读得到材料全文；训练卡目录不重复投影（它已在题库里）；隐藏文件（草稿、原子写临时名等）按设计跳过、不入清单，读失败与超 2 MiB 的单篇跳过并列进导出目录的 README；导出目录必须在工作区之外（落在里面会直接报错）。更新手机端：加 --sync-to <固定的库目录>，把新快照镜像进一个固定名字的 Obsidian 库——白名单条目（八张表目录 / README.md / jobws.base / 材料目录）按托管语义镜像（会被覆盖；源里删了的题库里也删，有删除时必须加 --yes 确认，否则拒绝执行、库目录零改动）；白名单之外的文件与库里的 .obsidian/ 一个字节不动；只差复习注释（<!--SR:…-->）或空白（空行 / 行尾空格）的笔记不覆盖——前者是手机刷出的进度，被覆盖就归零；正文真改了才更新（那篇笔记里的卡进度归零）。没有强制覆盖开关：确要对齐就删掉库目录里对应文件后重跑（会被当「新增」复制过去）。每次先打印「新增 / 更新 / 删除」计划再执行，--dry-run 只看计划不改库；升级版本后第一次同步先 --dry-run（渲染模板若变会整库更新、所有卡进度归零）。更新的完整顺序（手工拷贝时）：① 手机库拷回电脑、覆盖电脑上的库目录（把进度带回来）→ ② 跑同步 → ③ 把库目录拷回手机；用网盘双向同步则该往返自动完成
  • 还没有 API Key？：未存 key 时，页面会给出一个推荐 Provider 的注册入口，以及一个「一键填入该 Provider 端点」的按钮（预设值只在源码里定义一处）。这个入口在界面上明确标注为推广链接——通过它注册会给本项目作者返佣，你的价格与权益不受影响；点击只是打开网页，不会有任何数据从本应用发出。该入口当前指向 OrcaRouter。

本工作台的 AI 判断默认由 AI CLI（CodeBuddy 等）完成，Provider 是可选的 BYOK 增强入口（简历导入 / AI 改写用）。

只读邮箱拉取（可选）

如果你的邮箱支持 IMAP，工作台可以把最近的招聘邮件拉回来，省掉逐封复制粘贴。在设置页 → 「邮箱只读拉取」里配置（填 IMAP 授权码，不是网页登录密码；多数邮箱要先在网页版设置里开启 IMAP 服务）。

支持哪些邮箱：配置区顶部是服务商下拉——QQ 邮箱 / Foxmail、网易 163、网易 126、yeah.net、Gmail、Outlook / Hotmail、阿里云邮箱、新浪邮箱、搜狐邮箱，另加「其它（手工填写）」。选中即带出服务器与端口，你自己改过之后就不会再被覆盖；也可以只填邮箱地址、服务器留空按域名推断。每个服务商自带就地引导（去网页版哪里开、授权码 / 应用专用密码怎么拿）；163 / 126 / yeah.net 另有一条硬要求——客户端必须在打开文件夹之前声明身份（IMAP ID），本工作台会自动完成，你不用管。Outlook / Hotmail 个人账号暂不支持：微软自 2024-09-16 起停用基本认证，第三方客户端必须走 OAuth2，而本工作台目前只有「用户名 + 授权码」，所以界面上直接标注并说明原因，而不是留一个填了就错的输入框（可行性调研见 OAuth2 连 IMAP 的可行性）。测试连接成功后可以点「读取可用文件夹」拿候选（只读 LIST，点一次连一次），点一下填入、仍可手填。

它怎么工作、以及它不会做什么：

  • 只读：连接使用 SELECT (readonly) 与 BODY.PEEK——不发信、不标已读、不移动、不删除任何邮件。
  • 只在点击时连接：只有你点「从邮箱拉取」时才会连一次邮箱——没有后台定时器、轮询或连接保活。
  • 凭证默认存进系统凭据管理器：桌面版把授权码写进 Windows 凭据管理器，工作区里的 config/imap.json 只保留一条引用；界面与错误消息里脱敏，也不会进入导出 / 备份 zip。源码 / CLI 形态（或显式 JOBWS_CREDENTIAL_STORE=plaintext）是明文回退：那时授权码就写在 <工作区>/config/imap.json 里，能读到你用户目录的进程都能读到它——请把工作区当敏感目录看待，不要放在同步盘或公共共享里。桌面版读到旧明文会自动迁移进凭据管理器；迁移写失败时明文原样保留（绝不丢钥匙）。换电脑、换 Windows 账户，或把工作区目录拷到别的机器之后，系统里取不到这条引用——应用会明确提示「重新保存」，而不是假装成「还没配置」。需要「忘掉」这把钥匙时，设置页可以直接清除已保存的凭据——系统存储里的条目与配置文件里的引用会一并删除（之后再用需重新输入）。
  • 默认校验服务器证书：连接会对邮件服务器证书做系统证书库校验。如果本机 Windows 证书库有损坏条目，create_default_context() 会失败、连接被拒绝（授权码不能在未校验的连接上传输）。确认了解风险——连接可能被中间人截获——后，可显式设置环境变量 JOBWS_IMAP_TLS=insecure 跳过校验。
  • 默认 dry-run：拉取只列出邮件，在你逐条确认建议之前不会往追踪表写任何东西。

常见流程：投递追踪 → 「从邮箱拉取」 → 选时间范围（最近 7 / 30 / 90 天）→ 本地关键词筛选 → 点一封邮件 → 核对解析出的建议 → 确认写回。正文的三种口径界面上都会标注：拉取列表是原文（保留引用与签名、超 140 字截断）；点开后预填的是完整原文（后端上限 4000 字，顶到上限标「已截断」）；✨建议卡里的「出处」是摘录（已去掉引用与签名、仅用于解析）——三处不同是刻意的，不是数据丢了。如果这封邮件对应的投递还没记录，空态里会直接给一个「创建记录」表单（当前阶段默认按邮件内容推断）。

拉取列表里的邮件有三条去向：点邮件正文 = 走「解析 → 建议 → 确认」更新投递状态；点 ✨ = 就地展开解析建议（时间 / 截止事项 / 链接有效期 / 会议链接 / 建议阶段 / 对应岗位，共六类，每条都带原文出处与把握程度，逐条确认才写入——邀请类邮件优先按日历附件解析，比正文正则可靠）；点右侧的「＋」小图标 = 把这封邮件的元数据记入邮件台账（主题 / 发件人 / 日期 / Message-ID）——之后到「进展 → 邮件」里补标签与关联，不用再手打一遍。

解析建议里，把握程度为「需核对」的取值（原文没写年份、相对日期如「明天」「本周五」）必须勾选「我已核对取值」才允许写入；会议链接卡片可以直接复制或打开，写进台账后也能在「进展 → 邮件」里再次打开或复制。解析建议只在拉取流程里出现——手工粘贴的正文没有日历附件，仍走「粘贴邮件」的原有解析对话框。配置了 BYOK Provider（设置 → Provider）之后，底部还会出现可选 AI 增强：填模型名后手动跑一次，同一条建议链路、一律标「AI」且同样需要你核对——AI 只产建议，绝不直接写入。

正文里「请在 X 前完成在线测评 / 笔试」这类句子会被识别为截止事项（第五类候选）：卡片上带任务名（如"完成在线测评"）与日期，确认后同时写入投递记录的「下次动作日期」与「下次动作」。这两个字段正是到点提醒（看板「近七天待办」与系统通知）读的，所以倒计时会自动出现，不需要额外设置；相对日期支持「今天 / 明天 / 后天 / 大后天 / 本周X / 下周X」（后两者按周一为起点），算出的日期若已过去，那就是"已过期"信号，按「需核对」提示你确认。「N 天内 / N 个工作日内 / 链接 N 小时内有效」这类时长表达以邮件发出的那天为基准（三天前收到的邮件今天再看应当已经过期），工作日跳过周末、不跳法定节假日；「链接…有效」与「要交的东西」是两类候选（前者是链接会失效，要你复制保存）。

到点提醒的完整口径（桌面端）：设置页可调「提前几天提醒」（3 / 5 / 7 天，默认 3）。满足任一条就发一条系统通知：已过期（含「截止日期已过仍待投」与「下次动作日期已过」两类，按过期天数排在前）、提前 N 天内的待办（今天到期的与还剩几天的在正文里分开写）、近 7 天宣讲会。去重是按事项、每天一次——同一条今天报过就不再报，但今天新出现的照样会报（旧口径"一天只报一次"会把新出现的截止项漏掉）。点通知会跳到追踪表并自动展开那一条，不用自己找。应用内容区顶部还有一条常驻提醒条（读同一个端点、受同一个开关约束）：打开应用就能看到「N 条已过期 / 近 N 天 N 条待办 / N 场宣讲会」，点一下跳到对应页面；没有到点事项时它不出现、也不占位。关掉开关，通知与提醒条一起停；关窗即停，没有后台服务、不建托盘。

四、让 AI 干活：jwb-jd / jwb-apply 工作流

网页负责看和记，判断类的工作交给 AI。在 CodeBuddy 里用自然语言：

接进别的 AI 宿主（MCP，可选）

工作台还能作为一个 MCP 服务接进支持 MCP 的其它 AI 宿主（Claude Code / Codex / Gemini CLI 等）：AI 能读投递记录、岗位池与看板，并在你确认之后写入 （先给差异表，你点头才落盘）。

  • 安装与三种宿主的配置形态：docs/mcp-integration.md（配置键名按宿主不同，别照抄）
  • 四个入口（命令行 / AI 宿主 / 编辑器插件 / 桌面界面）各能做什么：docs/four-ends.md

解析一个岗位（jwb-jd 工作流）

把 JD 原文贴给我，或者说"解析这份 JD"。AI 会：

  1. 在 personal/01_岗位池/<公司>_<岗位>/ 存 JD 原文
  2. 跑硬门槛过滤（学历→专业→届数→英语→城市，对照 personal/AGENTS.md）
  3. 通过后四维度评分（技术30/经历25/方向30/培养15），回查事实卡核验
  4. 校验加总并输出档位（75–100 强烈投 / 60–74 投 / 45–59 斟酌 / 30–44 大概率跳过 / 0–29 不投）

硬门槛不过会直接拦下，不打分不写材料。比如对外语有硬性要求的岗位会被你的外语红线拦住。

生成投递包（jwb-apply 工作流）

说"给 XX 岗位生成投递包"。AI 会：选对应方向的简历版本 → 按需微调四处（项目事实不动）→ 生成 PDF → ATS 校验（页数/文本层/关键事实）→ 归档到 05_投递追踪/applications/ → 写入追踪表 → 列出改动清单交你确认后 git 提交。

更新进展（jwb-track）

面试完说"把 XX 更新到一面"，或直接在网页追踪表里点下拉框。

改简历后重新出 PDF（jwb-resume 工作流）

说"重建简历 PDF"，或命令行：

python tools/jobws.py resume --workspace personal --version hvac

五、CLI 命令速查（不用网页时）

所有命令在仓库根目录执行。--workspace personal 可省略（默认就是它）。

# 追踪表
python tools/jobws.py track list                        # 全部记录
python tools/jobws.py track list --due-within 7         # 未来 7 天到期
python tools/jobws.py track list --stage 笔试           # 按阶段筛
python tools/jobws.py track add --company "某公司" --role "岗位" --direction hvac --batch 正式批 ...
python tools/jobws.py track update --id A001 --stage 一面 --next "准备口述" --next-date 2026-09-10
python tools/jobws.py track history --id A001           # 变更时间线
python tools/jobws.py track import --file 待导入.csv --dry-run   # CSV 批量导入（只预览差异）
python tools/jobws.py track import --file 待导入.csv             # 预览通过后写入
python tools/jobws.py track interview add --app A001 --round 一面 --questions "..."   # 面试记录
python tools/jobws.py track contact add --name "张工" --app A001   # 招聘方联系人
python tools/jobws.py track offer add --company "某公司" --monthly "..."  # Offer 事实
python tools/jobws.py track mail add --subject "面试邀请（一面）" --app A001 --tag 邀约  # 邮件台账
python tools/jobws.py track mail list --app A001        # 某条投递的往来邮件
python tools/jobws.py track check                       # schema 自检（坏文件隔离）

# 投递漏斗看板（Markdown，含周期复盘与失败原因聚类）
python tools/jobws.py report --stdout

# 简历 PDF + ATS 校验
python tools/jobws.py resume --workspace personal            # 全部版本
python tools/jobws.py resume --version hvac                  # 指定版本
python tools/jobws.py resume render --workspace personal     # 数据驱动标准版式
python tools/jobws.py resume render --template std_compact --resume-accent 酒红   # 换版式 + 强调色

# JD 解析卡评分校验
python tools/jobws.py jd "personal/01_岗位池/<目录>/解析卡.md" --domain hvac-cooling --direction hvac
python tools/jobws.py jd --gap --resume hvac "personal/01_岗位池/<目录>/解析卡.md"   # JD↔简历差距

上文的阶段名（笔试、一面……）会原样写进你的数据文件，所以界面与文档里保留中文；它们按固定词表校验（STAGES，定义在 jobws_core.tracker），不能简单改成英文。

六、数据在哪、怎么备份

所有数据都是纯文本文件，在 personal/ 下：

目录 内容
00_事实库/ 项目/实习事实卡——唯一事实源
01_岗位池/ 每个岗位一个目录：JD 原文 + 解析卡
02_简历工坊/ 简历 md + HTML 模板 + 生成的 PDF + 照片
03_面试准备/ 自我介绍、项目表达、行为面、复盘（题库已迁至下方 05_投递追踪/questions.csv）
04_知识库/ 知识词典目录——按需自建（骨架里只有一份 README）
05_投递追踪/ 八张表：tracker.csv（投递）+ history.csv（变更时间线）+ interviews / contacts / offers / talks / mails / questions.csv
AGENTS.md 你的档案：硬门槛事实、诚实红线

备份（重要）：personal/ 已整体 gitignore——git 不追踪你的数据，仓库镜像克隆不会带走它们。主备份方式：

  1. 设置页「立即备份」：快照到系统用户目录（工作区之外，推荐，一键完成）
  2. 设置页「整包导出 zip」：随时可带走的完整工作区

⚠️ 分享仓库给任何人之前无需担心数据——personal/ 不在仓库里；但不要把 personal/ 目录本身发给别人（含姓名、照片、联系方式）。

七、常见问题

打开 localhost:5173 黑屏 / 连不上

按顺序排查：

  1. 服务活着吗：cd web && .\start.ps1 重启（会自动清端口）。Vite 是前台进程，启动它的终端关了服务就没了——这是最常见原因
  2. 浏览器缓存了旧版 JS：Ctrl + F5 强制刷新
  3. 还是黑屏：页面现在有 ErrorBoundary，崩溃会显示错误文字而不是黑屏；按 F12 看 Console，把报错发我

启动脚本报错

start.ps1 用了三层回退定位仓库根（参数 → 脚本位置 → 向上找 AGENTS.md）。如果报"无法定位仓库根"，在仓库目录内运行，或显式指定：

.\start.ps1 -RepoRoot <仓库目录>

npm 命令没反应

Windows 下手动启动前端必须用 npm.cmd run dev。直接 npm run dev 在某些调用方式下会静默失败（无报错、端口不监听）。

端口被占用

start.ps1 会自动释放 8765/5173。手动释放：

Get-NetTCPConnection -LocalPort 8765 -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

网页里岗位卡片没有评分

评分必须满足两点：解析卡.md 存在 且 四项加总与总分自洽（会被 jd_score 规则校验）。如果手改过解析卡导致格式不对，网页会当作"未评分"。用 python tools/jobws.py jd <解析卡路径> 看具体哪里不自洽。

CSV 用 Excel 打开乱码

不会乱码——写入用了 UTF-8 BOM（utf-8-sig）。如果乱码，说明文件被其他工具重写过编码，联系我修复。

双击 exe 没反应

console=True 黑窗一闪而过通常意味着启动即失败。原因与处置：

  1. 端口被占 → exe 现在会给出明确提示并保持窗口（除非被杀软拦截）。先 Get-NetTCPConnection -LocalPort 8765 -State Listen 看占用者
  2. 刚构建的 exe 数据为空是正常的——见上文"方式三"（exe 是干净分发物，不读仓库根数据）

网页标题显示 "Vite + React + TS"

旧版构建残留的缓存或未刷新产物。Ctrl+F5 强刷；仍不行则重新构建前端（cd web/frontend && npm.cmd run build）并重启后端。新的正确标题是 "Job Workbench"（窗口标题跟随界面语言，中文界面为「求职工作台」）。

.ps1 脚本报 ParserError / 中文乱码

含中文的 .ps1 必须存成 UTF-8 带 BOM。若文件被无 BOM 地重存，Windows PowerShell 5.1 会按 GBK 误解码导致语法错误。两个脚本（start.ps1、build_backend_exe.ps1）都已带 BOM；手动改它们时不要去掉 BOM。

八、技术文档导航

想了解 看哪份
整体架构（三层分离、领域插件） docs/specs/2026-08-30-general-workbench-design.md
Web 层设计（API 契约、并发与安全） docs/specs/2026-08-30-web-prototype-design.md
AI 工作流定义 根 skills/ 下九个 SKILL.md（五个求职向 + 一个扩展向 + 三个开发向；主文件精简、细节在各自的 references/。tools/jobws.py skills install 一并分发技能 / 命令 / 子代理三类资产到各 AI CLI）
毕业条件 / 支持策略 / 数据兼容承诺 docs/support-and-compatibility.md（什么时候算正式版、支持哪些环境、升级为什么不要求转换数据）
关键决策（为什么这样定） docs/decisions/ 下的短档（写入人工确认、单一发布节点、数据兼容、hooks 默认关闭）
文档总索引 docs/README.md

外观：主题与字体

设置页「外观」卡（设备级偏好，只影响这台机器、不随工作区导出）：

  • 主题：默认暗之外内置浅色与 8 套开源皮肤（Catppuccin Mocha·Latte / Nord / Tokyo Night / Rosé Pine + Dawn / Gruvbox / Everforest），支持「跟随系统」；「自定义主题…」改关键色并实时显示对比度，保存后进入主题列表；可导入 tweakcn / shadcn 的 CSS 或导出的 JSON。
  • 字体：界面字体 12 款可选（Inter 默认，另有 Geist、IBM Plex Sans、Manrope、Plus Jakarta Sans、DM Sans、Figtree、Outfit、Public Sans、Source Sans 3、Work Sans、Atkinson Hyperlegible Next，以及系统字体与衬线）；等宽字体独立可选 6 款（Maple Mono 默认，另有 JetBrains Mono、Fira Code、Geist Mono、IBM Plex Mono、Source Code Pro），管代码 / 编号 / 日期；数字字体另设一槽（Geist Mono 默认，可选 JetBrains Mono、IBM Plex Mono 或「跟随界面字体」），管 KPI / 计数 / 天数 / 百分比等数值。全部随应用本地打包（OFL-1.1、离线可用），只含拉丁子集——中文始终走系统栈。界面字号为连续滑块（80%–150%，步进 5%）。终端字体请在你的终端软件里设置——jobws prefs doctor 会给出推荐清单（Maple Mono / JetBrains Mono / 更纱黑体）。
  • 偏好分层：主题 / 字体是设备级（存本机）；jobws prefs（theme / font / resume_style）是工作区级物料偏好，供 CLI、技能与导出使用。

主题改动会过门禁 jobws lint themes（完整性 / 对比度 / 明度阶梯）——10 套内置主题全部满足正文 4.5:1、大字与图形 3:1。