Oriole · 黄雀 职位引擎

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

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

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

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

已实现的功能

Related MCP server: OpenAI-Compatible MCP Gateway

来源模型

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

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

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

• 公共目录 为权威的国家和地方发布者提供种子数据，包括国家公共就业、高校就业、事业单位、中央国企和政府部门的目录。

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

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

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

公共仓库不附带任何职位记录。npm run init 导入九个经过明确审计的公共来源种子——八个雇主控制的招聘板（包括字节跳动）和一个政府就业来源——因此一个干净的克隆拥有可用的采集目标，而不会发布过时或私有的职位快照。这不是对搜索结果的自动批准：种子清单本身就是一个经过审核的信任决策，所有新发现的来源仍然需要探测和批准。

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

字节跳动/飞书采集被限制为每次来源调用最多 50 页、5,000 行上游数据和 24 MB。当一次调用无法到达尾部时，已提交的运行会在 source.collection.resume 下存储一个带指纹、经过代次检查的游标；下一个分段刷新一个头部页面，然后以一个有意的重叠页面继续尾部。职位写入和游标推进共享一个原子 Registry 事务。在任一变更之前，Registry 对采集器读取的来源修订版和保存的游标代次执行比较并交换（compare-and-swap）；任一冲突都不会写入职位或游标。预览、失败或冲突永远不会推进保存的位置。恢复的尾部段即使在关闭一个轮换周期时仍保持 pagination.complete: false，因为变化的偏移量源不是跨运行快照，不能证明缺失职位的闭合。请分别检查采集运行和 Registry 证据：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 个捆绑职位。职位只会在真实的已提交采集后出现。

如需对字节跳动当前公开职位进行仅预览、产生证据的检查（无需百度密钥），运行 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

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

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 — 原子可移植 Registry；

• .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

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

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

边界

Oriole 处理公开的、无需登录的 Web 来源。它有意排除私有微信群、图像 OCR、电子邮件收件箱、验证码/仅登录页面和其他私有渠道。它不申请职位或做出就业决策。公共 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

欢迎通过 Apache-2.0 许可贡献内容。请阅读 CONTRIBUTING.md，并通过 SECURITY.md 报告安全问题。