feat(extension): 可安装打包 zip + Edge 安装实测与文档

- scripts/package_extension.py: extension/ → dist/AutoOffer-Extension-<版本>.zip
  (manifest 引用资源齐全性校验)
- release 工作流把扩展 zip 挂上 Release 附件
- Edge(msedge 通道)实测 --load-extension 加载成功, SW 正常注册
- extension/README 重写至当前形态(M1 时代内容已过时); 主 README 快速上手补
  Edge/zip 两种安装方式

Author: simpleqt

.github/workflows/release.yml

@@ -55,6 +55,10 @@ jobs:
             exit 1
           }
 
+      - name: Package browser extension
+        shell: pwsh
+        run: python scripts/package_extension.py
+
       - name: Compute SHA256
         shell: pwsh
         run: |
@@ -70,3 +74,4 @@ jobs:
           files: |
             dist/AutoOffer-Setup.exe
             dist/AutoOffer-Setup.exe.sha256
+            dist/AutoOffer-Extension-*.zip

README.md

@@ -10,7 +10,7 @@ AutoOffer 是一款基于多智能体（Multi-Agent）架构的**桌面软件**
 
 | 特性 | 说明 |
 | --- | --- |
-| **浏览器插件直填（推荐）** | Chrome 加载 `extension/` 即用：站点适配器（智易/北森 Phoenix、Moka、牛客、智联 + Ant/Element 兜底）+ 本地标签评分直填（含学历下拉、自绘单选、日历/月份选择器、「至今」开关）+ 多条教育经历自动补块 + 附件注入 |
+| **浏览器插件直填（推荐）** | Edge/Chrome 加载 `extension/` 即用：站点适配器（智易/北森 Phoenix、Moka、牛客、智联 + Ant/Element 兜底）+ 本地标签评分直填（含学历下拉、自绘单选、日历/月份选择器、「至今」开关）+ 多条教育经历自动补块 + 附件注入 |
 | 规则优先、AI 兜底 | 两段式填写：第一段本地规则直填（零 LLM、零数据外发）；未命中字段送 AI 标签映射（LLM 只见标签不见值），固定选项字段由 AI 选选项（级联逐层下钻） |
 | 通用表单泛化 | DOM 结构化感知 + 截图视觉辅助（Set-of-Marks），适配任意招聘网站，无需为单站写脚本（传统模式） |
 | 多智能体协作 | Planner（任务拆分）/ Actor（执行）/ Validator（校验）三角色循环（传统模式） |
@@ -58,7 +58,9 @@ AutoOffer 是一款基于多智能体（Multi-Agent）架构的**桌面软件**
 ## 浏览器插件快速上手（推荐）
 
 1. 启动本地服务：`python -m app.launcher`（健康检查 http://127.0.0.1:8765/api/v1/system/health）。
-2. Chrome → `chrome://extensions` → 开发者模式 → 「加载已解压的扩展程序」→ 选择仓库 `extension/` 目录。
+2. 安装插件（Edge / Chrome 通用，二选一）：
+   - **加载仓库目录**（开发推荐）：Edge 打开 `edge://extensions`（Chrome 为 `chrome://extensions`）→ 开「开发人员模式」→「加载解压缩的扩展」→ 选择仓库 `extension/` 目录。
+   - **安装打包 zip**：`python scripts/package_extension.py` 生成（或从 GitHub Release 附件下载）`dist/AutoOffer-Extension-<版本>.zip`，解压到固定目录后按上法加载该目录。
 3. 打开目标招聘表单页 → 点插件图标 → 「授权连接」→ 选档案 → 「开始填写」。只填不提交，检查无误后手动提交。
 
 权限模型：`activeTab + scripting + storage`，站点源与本地服务源均在点击时按需申请；微信扫码/验证码类登录由用户人工完成。详见 [extension/README.md](extension/README.md)。

extension/README.md

@@ -1,49 +1,72 @@
-# AutoOffer 浏览器插件（MV3）—— 规则直填 M1
+# AutoOffer 浏览器插件（MV3）
 
-以浏览器插件为「手」、本地服务为「脑」的轻量实现：页面上能规则匹配的字段零 LLM
-直接写入，数据不出本机。
+以浏览器插件为「手」、本地服务为「脑」：页面上能规则匹配的字段零 LLM 直接写入，
+规则未命中的字段走本地服务的 AI 标签映射/选选项通道，档案值不出本机。
 
 ## 架构
 
 ```
-popup(选档案/授权) ──▶ background(SW)
-                        │  fetch http://127.0.0.1:8765
-                        │   GET /api/v1/profiles/{id}/flat[?sensitive=true]
-                        ▼
-              content.js（规则直填引擎）
-                站点适配器(智易/Moka/北森/牛客/智联 + 框架兜底)
-                标签扫描 → 本地评分(textMatchScore) + 硬否决
-                         （上传类 / 家庭域 / 值形冲突）
-                → setNativeValue 原生注入(React 兼容)
-                → 自定义下拉三段降级（点开 → portal 选项匹配 → 搜索框注入重试）
+popup(选档案/授权敏感字段) ──▶ background(SW) 两段式编排
+                               │  fetch http://127.0.0.1:8765
+                               │   GET /api/v1/profiles/{id}/flat[?sensitive=true]
+                               │   GET /api/v1/profiles/{id}/attachments/{idx}
+                               │   POST /api/v1/mapping        （只见标签不见值）
+                               │   POST /api/v1/option-match   （AI 选选项，≤3轮级联）
+                               ▼
+                     content.js（规则直填引擎）
+                       站点适配器(智易/北森 Phoenix/Moka/牛客/智联 + Ant/Element 兜底)
+                       标签扫描 → 本地评分(textMatchScore) + 硬否决
+                                 （上传类 / 家庭域 / 值形冲突）
+                       → setNativeValue 原生注入(React 兼容)
+                       → 自定义下拉（弹层叶子兜底 + 搜索框重试 + 选项收割）
+                       → Phoenix 自绘单选（内部节点指针序列 + 选中态核验）
+                       → 日历/月份选择器、「至今」开关（幂等）
+                       → 多条教育经历自动补块（occurrence/itemIndex 配对）
+                       → 附件 File+DataTransfer 注入
 ```
 
 - 评分与注入设计参考 OpenJobAutofill（MIT），源码归档于 `reference/OpenJobAutofill/`。
 - 敏感字段（身份证号、家庭情况等）默认不输出，弹窗勾选授权后才随 `sensitive=true` 下发。
 - 值形/标签语义冲突硬否决来自 Playwright 路线的实战修复（手机号形状的值禁止写入身高/日期类标签）。
+- AI 映射只送字段标签与档案键名，不送档案值；选选项通道送单个值到你自己配置的 LLM（与简历解析同一信任域）。
 
-## 安装（开发者模式）
+## 安装到 Edge / Chrome
 
-1. 启动本地服务：仓库根目录 `.venv/Scripts/python.exe -m app.launcher`
-   （健康检查 http://127.0.0.1:8765/api/health）。
-2. Chrome 打开 `chrome://extensions` → 开启「开发者模式」→「加载已解压的扩展程序」→ 选择本目录。
-3. 打开目标招聘表单页 → 点击插件图标 → 「授权连接」本地服务 → 选择档案 → 「开始填写」。
+前提：本地服务已启动（`.venv/Scripts/python.exe -m app.launcher`，
+健康检查 http://127.0.0.1:8765/api/health）。
+
+**方式一：加载解压缩目录（开发推荐，改动即生效）**
+
+1. Edge 打开 `edge://extensions`（Chrome 为 `chrome://extensions`）。
+2. 打开左侧「开发人员模式」/「开发者模式」开关。
+3. 点「加载解压缩的扩展」/「加载已解压的扩展程序」，选择本仓库的 `extension/` 目录。
+
+**方式二：安装打包 zip（`dist/AutoOffer-Extension-<版本>.zip`）**
+
+1. `python scripts/package_extension.py` 生成 zip（或从 GitHub Release 下载附件）。
+2. 解压 zip 到任意固定目录（加载后目录不能删/移动）。
+3. 同方式一，加载解压缩的扩展时选中**解压出的目录**。
+
+**使用**：打开目标招聘表单页 → 点插件图标 → 首次「授权连接」本地服务（一并申请站点源与
+API 源）→ 选择档案 → 按需勾选「包含敏感字段」→「开始填写」→ 查看填写报告（AI 映射/附件
+补填的字段带标注）。
 
 权限模型：`activeTab + scripting + storage`，站点源与本地服务源均在点击时按需申请
 （`optional_host_permissions`），不常驻任何站点访问权。
 
-## M1 已知边界
+## 已知边界
 
-- repeat 档案区块（教育/实习/工作/项目经历）只匹配**第一条**；多条目「添加再填写」属 M3。
-- 附件上传字段一律跳过并提示手动上传（M3 处理）。
-- 无 AI 字段映射通道：规则分低于阈值的字段计入「跳过」（M2 在本地服务上加 `/api/v1/mapping`）。
-- 不触碰验证码/登录；自动提交不在插件范围内（沿用本地服务 auto_submit 设置语义，M3 接入）。
+- 两 pane 虚拟级联的职业大类（如北森「期望从事职业」46 类目）在自动化下仅部分可见，
+  AI 会拒选而不是乱选，该类字段留人工。
+- 不触碰验证码/登录（微信扫码等由人工完成）；不自动提交（沿用本地服务 auto_submit 设置）。
+- 招聘站普遍拒收 .md 附件，档案简历附件请用 PDF/Word
+  （`python scripts/md_resume_to_pdf.py` 可把 .md 转 PDF 并更新档案）。
 
 ## 测试
 
 ```bash
-# 引擎集成测试（真实 Chromium + fixture 基准页注入 content.js）
 .venv/Scripts/python.exe -m pytest tests/integration/extension -q
-# 扁平档案接口
 .venv/Scripts/python.exe -m pytest tests/integration/server/test_profile_flat.py -q
 ```
+
+真实 Chromium 注入 `src/content.js` 跑本地基准页（Ant/Element/北森 Phoenix 单选/多块/附件上传）。

scripts/package_extension.py

@@ -0,0 +1,54 @@
+"""把 extension/ 打包为可直接安装的浏览器扩展 zip（Edge/Chrome 通用）。
+
+用法: python scripts/package_extension.py
+产物: dist/AutoOffer-Extension-<版本>.zip
+安装: edge://extensions 打开开发人员模式 → 解压 zip → 「加载解压缩的扩展」选中目录。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+EXT = ROOT / "extension"
+DIST = ROOT / "dist"
+
+
+def main() -> int:
+    for _stream in (sys.stdout, sys.stderr):
+        if _stream.encoding and _stream.encoding.lower() not in ("utf-8", "utf8"):
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+
+    manifest = json.loads((EXT / "manifest.json").read_text(encoding="utf-8"))
+    version = manifest["version"]
+
+    files = sorted(
+        p for p in EXT.rglob("*") if p.is_file() and "__pycache__" not in p.parts
+    )
+    # manifest 引用的资源必须齐全
+    referenced: list[str] = [
+        manifest["action"]["default_popup"],
+        manifest["background"]["service_worker"],
+    ]
+    referenced += list(manifest["action"]["default_icon"].values())
+    referenced += list(manifest["icons"].values())
+    names = {str(p.relative_to(EXT)).replace("\\", "/") for p in files}
+    missing = [r for r in referenced if r not in names]
+    if missing:
+        print(f"manifest 引用的文件缺失: {missing}")
+        return 1
+
+    DIST.mkdir(parents=True, exist_ok=True)
+    out = DIST / f"AutoOffer-Extension-{version}.zip"
+    with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as zf:
+        for p in files:
+            zf.write(p, p.relative_to(EXT))
+    print(f"已打包: {out} ({out.stat().st_size // 1024} KB, {len(files)} 个文件)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())