OfferClaw

一个长期运行、带状态的个人求职 AI Agent
A stateful, long-running personal AI agent for job hunting.

画像 → 匹配 → 规划 → 执行 → 复盘 → 回到画像
_{Profile · Match · Plan · Execute · Reflect · Loop}

把"找工作"当成持续运行的工程项目。
_{个人作品集 · 不自动投递 · 不伪造经历 · 不预测录用概率}

项目数据

Why OfferClaw

求职过程通常被拆成"刷岗位 → 改简历 → 投 → 等"这种一次性动作。

这种方式的问题是：

• 简历和 JD 之间的真实差距没人告诉你，匹配靠感觉
• 学习计划和投递节奏互相脱节，今天该做什么靠记忆
• 每次投递、每次面试反馈没有沉淀，画像不更新
• 生成式工具能写漂亮文案，但没有状态、没有约束、没有可解释性

OfferClaw 的思路：用一个带状态的 Agent 把链路连起来——所有判断走 Prompt 契约 + 规则代码双通路，所有状态写入可读的 Markdown 文件，所有变更经同一个 Orchestrator 反向修正画像与计划。

核心能力

⚙️ 工程亮点 · Engineering Highlights

不只是「功能能跑」，而是把 RAG 检索与 LLM/Agent 调用都做到了生产级工程化——每项改进都有量化指标、故障注入测试、逐轮可追溯日志。完整记录见 docs/RAG_OPTIMIZATION_LOG.md 与 docs/AGENT_OPTIMIZATION_LOG.md。

RAG 检索系统 · 评测驱动迭代

生产 /api/query 使用显式检索管线，而不是由 rag_graph.py 统一编排：路由与作用域 → 原问题 + HyDE 双通道 → Dense/BM25/RRF → bge-reranker → answerability v5 判据重排 → 三票共识证据门。rag_graph.py 保留为 LangGraph RAG 实验/演示实现；生产链路集中在 rag_api.py 与 rag_gate.py，便于逐阶段回退和审计。

三套评测口径诚实并列：

Final v4 上 Quality 的 R@1 没有提高（A/C 均为 59/80）；主要收益是 Candidate、Top-K、有效作答和门控动作。代价是须拒答子集出现 1/28 真误纳，以及完整 Quality 检索在历史同分布 100 题冷缓存下 p50 13.9s、p95 29.8s。当前拒答守卫为简单负例 12/12、近似负例 11/12。

• 跨语言显式论文检索：xling50 grounded 正确 30/50（60%）、错误放行 0、p50/p95 309/589ms；仅在显式 paper_kb 路由生效，不能外推到普通查询。
• HyDE 取舍：替换式 HyDE 会污染按原问题标定的距离分布，因此被否决；当前采用附加式双通道，并把候选距离统一重算回原问题。
• 答案质量（当前 HEAD）：冻结的历史开发回归集 n=48（40 正例 + 8 负例，非盲集/非 organic），两个独立裁判配置对同一不可变答案完成 96/96 裁判。正例 claim 忠实度 96.9%–97.1%，答案要求完整度 65.0%–81.3%，有效完整度 63.8%–81.3%；39/40 进入 KB grounded，28/40 命中冻结 exact-gold chunk。8 个负例的 pipeline 路由动作本身 8/8，但端到端动作合同仅 6/8；其中 4 个 correct_premise 最终答案只有 2/4 真正纠错，说明门控动作尚未完全传给生成合同。原始裁判输出属于本地私有评估包，不进入 Git。
• 当前答案链延迟：同一 n=48、独立空判据缓存、模型常驻单进程下，检索 p50/p95 31.0s/80.4s，生成 4.35s/77.4s，端到端 37.6s/97.1s。这是当前最明确的工程短板，不与历史 Final v4 的纯检索延迟混写。
• 小型产品验收：画像治理、JD 匹配、今日计划、投递生命周期、复盘记忆、简历/CareerFlow 六域共 36/36 通过（各域 6 例，含跨模块不变量：审批治理、非法状态拒绝、损坏恢复、并发写、节点降级、重放幂等）；全部复用 tmp_path 隔离合同，不调用外部 LLM、不写真实用户状态。
• 回归防线：eval_rag_bench.py --fail-under 已落地为 .githooks/pre-push；改检索代码会触发离线回归，不把外部 LLM 可用性当成 push 的硬依赖。

LLM/Agent 工程化 · 12 项容错加固 + CI

把检索侧的弹性容错系统复刻到生成/编排/记忆/工具/数据全栈，用故障注入测试量化：

47 个专项故障注入测试 + 1,659 全量测试通过 + CI 门禁（.github/workflows/ci.yml）。

多 Agent 架构 · Supervisor 编排(2026-07)

• 内环专家 Agent:学习规划 / 简历定制 / 独立校验各司其职,按匹配三档结论条件路由;JD Parser 与语义证据对齐器是受约束服务，匹配裁决坚持规则引擎（LLM 只关联已有证据，不碰硬门槛和最终三档）
• 生成-校验分离:简历由生成 Agent 产出、独立校验 Agent 对照画像与 metrics 真值核对,守"不编造"硬边界(编造硬拦=代码,LLM 仅语义标注)
• 外环督导(确定性代码):跨天记忆沉淀、停滞检测、多 JD 并行编排
• Agentic-RAG：可选 CRAG 条件恢复循环（证据弱时改写重检；RAG_CRAG=0 默认关），只在口语化回归集测正后才考虑晋级；生产默认门为 answerability v5 + 三票共识
• 泛化与诚实数据:职业域泛化 31 项兼容测试 + 跨域泛化矩阵 128 对(合成画像,明标)
• 设计权衡、reframe/新增台账与"测正才采纳"纪律 → docs/MULTI_AGENT_UPGRADE.md

How It Works

                       用户输入一段 JD
                              │
                              ▼
                  ┌──────────────────────┐
                  │   profile_loader     │  读 user_profile.md
                  │   13 字段画像 + 缓存   │  按 JSON Schema 校验
                  └──────────┬───────────┘
                             │
                             ▼
              ┌────────────────────────────┐
              │  CareerFlow (LangGraph)    │  routed: 条件路由 4 分支
              │  profile → job_input →     │
              │  match → gap → plan →      │
              │  today → resume →          │
              │  application_suggest       │
              └──────────┬─────────────────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
         适合投递    中长期可转向    暂不建议
              │          │          │
              ▼          ▼          ▼
        full path  plan+today  gap-only  → END
              │          │          │
              └──────────┴──────────┘
                         │
                         ▼
              ┌────────────────────────────┐
              │  Observability             │  JSONL trace
              │  logs/traces/<id>.jsonl    │  /api/trace 重放
              └────────────────────────────┘

旁路：
  ReAct Agent (POST /api/agent)  ─→  Tool Registry (6 tools)
  MCP Server (POST /mcp · Streamable HTTP) ─→ Tool Registry (同一 REGISTRY)
  RAG (混合检索+rerank+路由+双证据门控)         ─→  ChromaDB (3327 chunks)
  Memory Layers (V4)             ─→  Episodic / Semantic / Procedural

详见 docs/architecture.md。

Quick Start

# 1. 克隆 + 创建本地虚拟环境
git clone https://github.com/zhangrldndx/offerclaw.git
cd offerclaw
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

# 2. 配置本机 API 环境（已被 .gitignore 忽略）
cp .env.example .env.local
# 然后把 .env.local 里的 API Key 占位符替换为你自己的 Key。
# 百炼推荐配置见 .env.example：chat 走 OPENAI_*，embedding 走 EMBEDDING_PROVIDER=bailian。
# 想用 DeepSeek / 智谱 GLM 等其他国内模型：只改 OPENAI_BASE_URL / OPENAI_API_KEY /
# LLM_MODEL 三个变量（OpenAI 兼容协议，现成示例见 .env.example 注释）；
# 手头没有 embedding 类 key 时选 EMBEDDING_PROVIDER=local（本地模型，免费无额度）。

# 2.5 如果切换了 embedding provider/model，重建对应 Chroma collection
python rag_ingest.py --rebuild

# 3. 启动 FastAPI 服务
python -m uvicorn rag_api:app --host 127.0.0.1 --port 8000

# 4. 浏览器打开任一控制台
#    /ui            — 8 卡片求职工作台（顶部 RAG 问答条 + 今日建议横条 + CareerFlow 流程条）
#    /ui/console    — V3 CareerFlow 8 步 Stepper（一页跑完整流程）
#    /docs          — Swagger（91 路由）

本机 Chrome 兜底

JD 半自动抽取会先用轻量请求抓正文；遇到 SPA 招聘页时，job_discovery.py 会优先调用本机 Google Chrome 的无头模式渲染页面，若本机没有 Chrome 或启动失败，再回退到 Playwright 自带 Chromium。

工程自检

python doctor.py                  # 12 项环境与文件健康检查
python verify_pipeline.py         # 6 步主链路端到端冒烟
python eval_match.py              # match_job 评估（status acc / direction acc）
python -m pytest tests/ -q        # 1,659 tests passed / 54 skipped
python verify_docs.py             # 4 份关键文档指标口径一致性巡检
python normalize_applications.py  # applications.md 投递表 schema 校验

OPENAI_* 用于 chat completion / Agent 推理；EMBEDDING_PROVIDER、EMBEDDING_MODEL、RAG_COLLECTION_NAME 用于 RAG 向量库切换。百炼可用 DASHSCOPE_API_KEY，旧智谱路径可用 ZHIPU_API_KEY。KEY 仅本地、绝不入 git。

渠道接入和本地部署见 docs/WECHAT_INTEGRATION.md。

微信联动(一键接入)

工作日早间建议、晚间留痕提醒和周日复盘可自动推送到微信。微信端还支持顶部问答、JD 匹配、附件解析、计划与简历草稿生成，以及投递状态、每日留痕和知识材料的待审核写入；计划、画像、投递、日志、知识库和正式简历等本地状态只有在用户明确确认后才修改。

bash setup_wechat.sh            # 幂等一键部署;--dry-run 可先预览
# 首次需扫码配对:openclaw channels login openclaw-weixin

脚本部署 OpenClaw gateway 作为渠道层（调度 + 微信桥），OfferClaw 保持领域后端。上传的 md/txt/pdf/docx 会先解析为来源或候选；图片暂不做 OCR，外部向量数据库也不直接合并。知识材料须先确认候选，再在知识库审核后入库并重建 OfferClaw 自己的索引。完整能力、审批边界和运维方式见 docs/WECHAT_INTEGRATION.md。

V4 · 5 个 Agent 工程优化点

V4 把项目从「流程画板」推进到「真正可以被工程师 review 的 Agent 系统」。5 个独立模块、66 个新增测试全部绿、不破坏 V3 任何回归。（V4 之后又做了 RAG 检索 8 轮优化 + LLM/Agent 工程化 A1–A8/B1–B4，再 +47 故障注入测试，详见两份手册）

python eval_match.py           # 跑 baseline
python eval_match.py --judge   # 叠加 LLM 二次审视

curl -X POST localhost:8000/api/agent \
  -d '{"message":"今天该做什么？"}'

curl localhost:8000/api/trace?limit=20
curl localhost:8000/api/trace/{trace_id}

Tech Stack

Evaluation · 工程自检证据

评估基于自建小规模评估集，仅用于个人项目自检与回归对比，不代表通用基准。

完整现场输出固化在 docs/verification_report.md。

Project Structure

offerclaw/
│
├─ Prompt 契约层（不变契约 · 全部入 Git）
│   SOUL.md · target_rules.md · source_policy.md
│   onboarding_prompt.md · job_match_prompt.md
│   plan_prompt.md · summary_prompt.md
│
├─ 核心代码（V1 → V4 演进）
│   agent_demo.py        # V1 Agent 核心 (tools.py)
│   match_job.py         # 规则版 JD 匹配（三档结论）
│   plan_gen.py          # 4 周路线生成
│   resume_builder.py    # JD 定制简历段
│   job_discovery.py     # JD 抓取（含 Playwright 兜底）
│   rag_*.py             # RAG + LangGraph 4 节点 + 工具循环
│   career_agent.py      # V2 Orchestrator（"今天最该做什么"）
│   career_flow.py       # CareerFlow 10 业务节点 + routed 变体(+4 router)
│   profile_loader.py    # V3 状态真实化 + V4 Schema 校验
│
├─ V4 新增模块
│   eval_match.py        # match_job 评估 + LLM-as-judge
│   tools_registry.py    # OpenAI 兼容 Tool 抽象 + 默认注册表
│   react_agent.py       # ReAct Agent（deterministic + LLM）
│   observability.py     # JSONL Trace + 重放
│   memory_layers.py     # Episodic / Semantic / Procedural
│   profile_schema.json  # 13 字段 JSON Schema
│
├─ FastAPI 层
│   rag_api.py           # 91 路由 · SSE 流 · Swagger
│   mcp_server.py        # 手写 MCP Streamable HTTP 服务端（POST /mcp，工具来自同一 REGISTRY）
│
├─ 工程自检
│   doctor.py            # 10 项体检
│   verify_pipeline.py   # 6 步冒烟
│   verify_docs.py       # 文档口径漂移巡检
│   normalize_applications.py  # 投递表 schema 校验
│
├─ 运行时数据（部分入 Git，部分 .gitignore）
│   user_profile.md · daily_log.md · applications.md
│   interview_story_bank.md · application_jds/
├─ 离线回归样例
│   jd_candidates.md（不进入产品 RAG）
│   profiles/p1_demo_ai.json / p2 / p3
│   chroma_db/ · logs/ · memory.json   ← .gitignore
│
├─ tests/                # 1,659 tests passed（含 RAG/Agent 工程化故障注入测试）
│
└─ docs/
    architecture.md · v3_changelog.md · RESUME_PROJECT.md
    verification_report.md · archive/(V1–V2 历史快照)
    interview_qa.md · persona_compare_report.md
    project_one_pager.md · postmortem.md · ethical_use.md
    MEMORY_SYSTEM.md · WECHAT_INTEGRATION.md

Design Decisions

• 不依赖 Agent 框架：核心 Agent 调用、工具循环、跨会话 memory 全部手写，便于在面试中拆解每一层逻辑
• Prompt + 代码双通路：关键判断（JD 匹配）必须两边都过，规则版作为 Prompt 版的回归基线
• 契约式 Prompt：每份 Prompt 文件明确输入 / 步骤 / 输出 / 禁止条款，可像 API 一样回归测试
• 状态用文件而非数据库：Markdown / JSON 直接 diff，故障与变更全部可读
• 声明式 RAG 工作流：LangGraph 把"检索 → 提示拼装 → LLM → 工具调用"显式化为 4 节点，避免黑盒链路
• 抓取双通道 + 自动回退：常规站点走 requests，SPA 自动回退 Playwright，控制成本同时覆盖主流招聘页
• V4：Tool 与编排解耦：所有能力暴露为 OpenAI 兼容 Tool；ReAct Agent / MCP / 第三方脚本从同一 REGISTRY 取，不重写 schema（V5 已兑现：mcp_server.py Streamable HTTP）
• V4：Trace 文件化：每次 CareerFlow 落 JSONL，重放与审计零基础设施依赖

Local Application Reflow SOP · 本地投递回流

目标：在本地完成 JD → CareerFlow → 简历 → 状态回填 → 复盘闭环。真实投递数据始终留在 Git 忽略的运行时文件中。

1. 临时抽取 JD                 POST /api/discover         → 仅返回结构化结果
2. CareerFlow 评估             POST /api/flow/run         → match_report + gaps + today
3. 决策分叉
   ├─ 适合投递                  → §4 生成简历
   └─ 其他三档                   → plan/4_weeks 中长期补能，本轮不投
4. 生成简历草稿                POST /api/resume/markdown  默认无 LLM 拿骨架
                              + POST /api/resume/build    SSE 流式 LLM 写定制段
5. 确认登记投递               applications.md 加一行，并绑定不可变 JD 版本
6. 真实投出                   状态改 已投递               POST /api/daily 追加日志
7. 回流证据                   只保存在本地私密目录，不进入 Git
8. 复盘入 RAG                 daily_log.md 写 1-2 句     python rag_ingest.py 入库

最小可交付证据集

• 合成 JD 回归：完整 CareerFlow 节点链路由自动化测试覆盖
• 真实投递回流：仅保存在本地运行时数据中，不作为公开仓库证据

Roadmap

• V1 — 画像 / 匹配 / 规划 / 执行 / 复盘五段 + Agent Demo
• V1.5 — RAG（LangGraph + ChromaDB）+ FastAPI 接口层
• V2 — 6 卡片控制台 + Orchestrator + JD 自动抓取 + JD 定制简历 + 多 Persona 回归
• V3 阶段 1-7（产品级 Agent 化） — 状态真实化 · CareerFlow 8 节点 · Stepper UI · JD 排序 · 简历骨架 · RAG verification · 端到端验证 — docs/v3_changelog.md
• V3 收口审计 — DEMO_PROFILE 0 生产耦合 · /api/info 与 24 路由 0 漂移 · pytest 64/64
• 合成投递闭环 — 8 节点流程、简历骨架、日志与投递状态由自动化测试覆盖
• V4 · 5 个 Agent 工程优化点 — Eval-driven · Agentic Graph · Tool Ecology · Observability · Schema/Memory（pytest 64 → 130，新增 4 路由）
• 真实投递回流 — 仅作为本地用户行为，不在公开仓库记录公司、岗位或反馈
• 简历最终可投递版本（Word / PDF）
• 1 分钟 Demo 视频（可选）
• RAG 评估集扩到 100 题（可选）
• match_eval_set 扩到 30 样本 + LLM-as-judge 集成 CI（可选）

完整推进记录见 PROJECT_STATUS.md。

Limitations · 硬边界

• 不自动投递 — 不会代为提交简历到任何平台；投递动作必须人工完成
• JD 抓取仅半自动 · 不批量 · 不登录 — 一次只处理用户给定的单个 URL；不做门户扫描 / 翻页 / 列表遍历；不登录任何招聘平台、不绕验证码。详见 docs/ethical_use.md §1.6
• 不伪造经历 — 简历草稿仅基于 user_profile.md 与 interview_story_bank.md 中的真实素材重组、强调和适配 JD，不会编造未发生的项目
• 不承诺录用概率 — 所有匹配结论是"差距分析 + 建议"，不输出录用率、面试通过率之类的数字预测
• 写入需人工确认 — 写入 applications.md / user_profile.md 等用户层文件的关键动作必须 UI 二次确认（详见 DATA_CONTRACT.md §4.0 写入策略表）
• 个人作品集，非生产系统 — 单用户运行、本地存储、无完整多租户（仅预留租户接缝,见 docs/MULTI_USER_ROADMAP.md）、无登录鉴权 / 限流 / 审计
• 指标规模小 — 自建评估集只覆盖本仓库内容，结论不推广到通用领域
• LLM 输出不可强保证 — 尽管走 Prompt 契约，仍可能产生不符合规则的回答，需人工二次确认

API Reference

当前代码含 91 个路由装饰器、86 个唯一项目路径（同一路径的不同 HTTP 方法分别注册）；完整运行时 Swagger 在 /docs。

Citing & Contact

个人作品集项目，未配置开源许可。引用或参考请在 issue 中联系。

_{Built around the discipline of stateful agent engineering.
github.com/zhangrldndx/offerclaw}