Oriole · 黄雀 职位引擎

中文说明 · 架构 · 来源 · 验证

将开放网络转化为一张可追溯、经人工审核的职位来源地图——而非一堆不透明的抓取列表。

Oriole 是一个开放的中国全国职位来源情报 Agent。它发现公开的招聘发布者，验证其端点，在收集前要求人工批准，按实际工作地点对职位进行归一化，并通过 16 个 MCP 工具将结果暴露给任何 LLM。

它刻意被构建为一个引擎，而非单一网站。你可以从 CLI 运行它，在午夜调度它，将确定性核心嵌入另一个 Node.js 服务，或连接支持 MCP 的模型，而无需将该模型的凭据交给它。

已实现的功能

Related MCP server: OpenAI-Compatible MCP Gateway

来源模型

发现渠道和职位来源有不同的职责：

• 百度 是一个发现雷达。配置后，Oriole 调用百度官方千帆端点并存储请求级证据。它从不抓取百度结果页面。

• Common Crawl 是受控 site: 模式的无密钥存档/索引回退。它验证公共 URL 是否存在；它不被视为全文搜索引擎或最终职位来源。

• 公共目录 为权威的国家和地方发布者提供种子，包括国家公共就业、大学就业、公共机构、中央国有企业，以及政府部门目录。

• 雇主网站、官方 ATS 板和政府就业页面 是长期收集目标。来源必须通过安全探测和人工审核，其职位才能进入注册表。

• 用户提交 允许另一个 Agent 或操作员提出公共 URL，同时保持相同的探测和审核门。

收集九个预先批准的来源种子或从捆绑的官方目录中发现候选者不需要百度密钥。提供者能力对每个查询任务都是显式的：普通关键字发现仅限百度，因此当百度不可用时，这些任务在 status.discoveryBacklog 和发现运行统计中保持可见的 blocked。Common Crawl 仅适用于受控的 site: 任务；被阻止的工作永远不会被计为已完成。

公共仓库提供零职位记录。npm run init 导入九个经过明确审计的公共来源种子——八个雇主控制的板，包括 ByteDance，以及一个政府就业来源——因此干净的克隆具有功能性的收集目标，而不会发布过时或私有的职位快照。这不是对搜索结果的自动批准：种子清单本身是一个经过审核的信任决策，所有新发现的来源仍然需要探测和批准。

覆盖率是一个可衡量的差距报告，而非对全国职位捕获的完整声明。在 19 个雇主观测中，ByteDance 是唯一经过审核的引导目标；其他 18 个雇主根目录作为未批准的候选者开始，在它们被探测、验证和批准之前无法产生职位。

ByteDance/Feishu 收集被限制为每次来源调用 50 页、5,000 个上游行和 24 MB。当一次调用无法到达尾部时，已提交的运行会在 source.collection.resume 下存储一个带指纹、代际检查的游标；下一个段刷新一个头部页面，然后以有意重叠的一页继续尾部。职位写入和游标推进共享一个原子注册表事务。在任一变更之前，注册表对收集器读取的来源修订和保存的游标代际进行 compare-and-swap；任一冲突都不会写入职位或游标。预览、失败或冲突永远不会推进保存的位置。恢复的尾部段保持 pagination.complete: false，即使它关闭了一个轮换周期，因为变化的偏移量不是跨运行快照，不能证明缺失职位的关闭。分别检查收集运行和注册表证据：npm run coverage 测量来源/渠道/区域状态，不读取分页或恢复进度。

参见 docs/SOURCES.md 了解确切的提供者边界和种子目录。

快速开始

要求：Node.js 22.13+。Oriole 没有运行时依赖，初始化或收集其预先批准的来源、从官方目录发现或运行受控的 Common Crawl site: 任务，都不需要密钥。

git clone https://github.com/gaofeibilly-maker/oriole-job-engine.git
cd oriole-job-engine
npm test
npm run init
npm run status
npm run coverage
npm run regions -- --province-code 420000

init 后，status 应显示 9 个已批准的来源和 0 个捆绑职位。职位仅在真实提交的收集后出现。

对于仅预览、产生证据的 ByteDance 当前公共职位检查（无需百度密钥），运行 npm run live-source-check。它验证官方申请 URL 并打印紧凑摘要，而非原始响应或职位描述。预览读取适用的窗口，但从不提交职位或推进已保存的恢复游标。匹配的 GitHub 工作流可以手动运行，或通过标记拉取请求 live-source-audit 运行。

无需凭据即可发现捆绑的官方目录：

node scripts/huangque/cli.mjs discover \
  --providers official_catalog \
  --force

node scripts/huangque/cli.mjs sources
node scripts/huangque/cli.mjs graph

发现创建候选者；它不会静默地将它们变成收集目标。探测候选者，检查其证据和当前注册表修订，然后显式批准它：

node scripts/huangque/cli.mjs probe --source <source-id>

node scripts/huangque/cli.mjs review \
  --source <source-id> \
  --decision approve \
  --reviewer <operator-name> \
  --reason "Official public recruitment source verified" \
  --revision <current-revision> \
  --confirm

node scripts/huangque/cli.mjs collect --source <source-id> --commit
node scripts/huangque/cli.mjs jobs --province-code 420000 --city-code 420100

所有状态默认本地：

• .huangque/state.json — 原子可移植注册表；

• .huangque/artifacts/ — 内容寻址、压缩的证据；

• .huangque/latest-audit.json — 最新的机器可读自审计。

这些路径被 Git 忽略，可以通过环境变量重新定位。

通过 MCP 连接任何 LLM

启动 stdio 服务器：

npm run mcp

示例 MCP 客户端配置：

{
  "mcpServers": {
    "oriole": {
      "command": "node",
      "args": ["/absolute/path/oriole-job-engine/scripts/huangque/mcp-server.mjs"],
      "env": {
        "HUANGQUE_REGISTRY_PATH": "/absolute/path/oriole-data/state.json",
        "HUANGQUE_ARTIFACT_ROOT": "/absolute/path/oriole-data/artifacts"
      }
    }
  }
}

服务器暴露了用于管道运行、运行查找、状态、可衡量的来源覆盖差距、发现、公共来源提交、探测、来源列表、职位列表、区域列表、图读取、人工审核、收集、到期工作、审计和可移植投影导出的工具。

huangque.list_regions 在省级、仅省级和每个二级城市报告唯一职位聚合。一个职位在一个省的两个城市中明确提供，在省级总数中计一次，在每个适用的城市中计一次。

通过 MCP 的来源批准默认禁用。操作员必须有意设置 HUANGQUE_ALLOW_MCP_REVIEW=1；CLI 批准仍然可用，而不会削弱该服务器端边界。

可选的百度发现

复制示例配置，并在本地或作为 GitHub Actions 密钥设置你的密钥。切勿提交它。

cp .env.example .env
export HUANGQUE_BAIDU_API_KEY="<your-key>"
node scripts/huangque/cli.mjs discover --providers baidu --max-queries 5

密钥仅发送到 qianfan.baidubce.com。其他主机上的自定义端点被拒绝。默认每日预算为 40 个请求，可以通过 HUANGQUE_BAIDU_DAILY_BUDGET 降低。

不配置百度不会停止已批准来源的收集。它只会让普通的基于关键字的主动发现任务显式阻塞；无密钥的 Common Crawl 继续处理查询计划的受控 site: 任务。

官方参考：百度千帆 AI 搜索 API。

午夜全国每日更新

捆绑的工作流在 16:00 UTC 运行，即下一个本地日历日的 00:00 Asia/Shanghai：

npm run daily

运行器写入北京日期的完成标记，因此重试不会重复同一天的运行，除非提供 --force。GitHub 调度可能晚几分钟开始；本地标记控制业务日期，而不是队列时间。参见 docs/SCHEDULING.md。

来源图，而非仅列表

每个图边都携带证据和观察时间戳。核心关系是：

publisher ← published_by — source — covers_region → region
                            │
                            ├─ has_entry_point → public page
                            ├─ has_endpoint → collection endpoint
                            ├─ discovered_via → provider/query/run evidence
                            └─ lists_job → normalized job

发布者和区域边遵循最新的权威已批准来源证据：当审计的来源身份改变时，过时的 published_by 和 covers_region 关系被修剪，而不是作为误导性的历史事实保留。

“完整图”在这里意味着每个注册来源都以其证据支持的关系表示，并且每个关系都是可审计的。它不意味着有限目录已经包含中国每个雇主或每个开放职位；Oriole 旨在持续扩展和重新验证该图。

先验证再信任

npm run verify
npm run audit

测试套件涵盖归一化、全国区域、多地点处理、提供者、有界大流轮换、游标原子性/并发性、图证据、注册表保留、MCP 生命周期、SSRF 控制、robots 处理、来源所有权和职位身份。运行时审计单独报告外部提供者和已发布的 GitHub 调度是否在当前注册表中具有真实的成功运行证据。Fixtures 和手动每日运行永远不计为实时提供者或 GitHub Actions 成功。

遵循 docs/VERIFY.md 中的可复现清单。

边界

Oriole 处理公共、非登录的 Web 来源。它有意排除私有微信组、图像 OCR、电子邮件收件箱、CAPTCHA/仅登录页面，以及其他私有渠道。它不申请职位或做出就业决策。公共 Web 访问不豁免站点的条款、robots 政策、数据库权利、隐私义务或适用法律；部署者仍负责来源特定的合规性。

项目布局

data/huangque/              verified public seeds, national query plan, and public catalog
scripts/huangque/           CLI, daily runner, MCP server, deterministic core
tests/                      Node test suite
docs/                       architecture, sources, schedule, verification
.github/workflows/          CI and Beijing-midnight daily update

Beiträge sind unter Apache-2.0 willkommen. Bitte lesen Sie CONTRIBUTING.md und melden Sie Sicherheitsprobleme über SECURITY.md.