Oriole · 黄雀 Job Engine

中文说明 · Architecture · Sources · Verification

Превратите открытый веб в прослеживаемую карту источников вакансий с ручной проверкой — а не в непрозрачную кучу собранных объявлений.

Oriole — это открытый агент разведки источников вакансий по всему Китаю. Он обнаруживает публичных рекрутинговых издателей, проверяет их конечные точки, требует одобрения человека перед сбором, нормализует вакансии по фактическому месту работы и предоставляет результат любому LLM через 16 MCP-инструментов.

Он намеренно построен как движок, а не как единый веб-сайт. Запускайте его из CLI, планируйте на полночь, встраивайте детерминированное ядро в другой сервис на Node.js или подключайте модель с поддержкой MCP, не передавая этой модели свои учётные данные.

Что реализовано

Related MCP server: OpenAI-Compatible MCP Gateway

Модель источников

Каналы обнаружения и источники вакансий выполняют разные задачи:

• Baidu — это радар обнаружения. При настройке Oriole вызывает официальную конечную точку Qianfan от Baidu и хранит доказательства на уровне запроса. Он никогда не скрейпит страницу результатов Baidu.

• Common Crawl — это резервный архив/индекс без ключа для контролируемых шаблонов site:. Он проверяет, что публичные URL-адреса существовали; он не рассматривается как полнотекстовая поисковая система или как конечный источник вакансий.

• Публичные каталоги — это источники авторитетных национальных и местных издателей, включая национальные государственные службы занятости, университетские службы занятости, государственные учреждения, центральные государственные компании и каталоги правительственных департаментов.

• Сайты работодателей, официальные доски ATS и правительственные страницы занятости — это долгоживущие цели сбора. Источник должен пройти проверку безопасности и человеческое рецензирование, прежде чем его вакансии могут попасть в Реестр.

• Пользовательская отправка позволяет другому агенту или оператору предложить публичный URL-адрес, сохраняя при этом тот же шлюз проверки и рецензирования.

Для сбора девяти предварительно одобренных источников или обнаружения кандидатов из встроенного официального каталога ключ Baidu не требуется. Возможности провайдера явно указаны для каждой задачи запроса: обычное обнаружение по ключевым словам доступно только через Baidu, поэтому такие задачи остаются видимо blocked в status.discoveryBacklog и статистике запусков обнаружения, когда Baidu недоступен. Common Crawl доступен только для контролируемых задач site:; заблокированная работа никогда не считается выполненной.

Публичный репозиторий поставляется с нулевыми записями вакансий. npm run init импортирует девять явно проверенных публичных источников — восемь досок, контролируемых работодателями, включая ByteDance, и один правительственный источник занятости — так что чистая копия имеет функциональные цели сбора без публикации устаревшего или приватного снимка вакансий. Это не автоматическое одобрение результатов поиска: сам манифест источников является рецензируемым решением о доверии, и все вновь обнаруженные источники по-прежнему требуют проверки и одобрения.

Покрытие — это измеримый отчёт о пробелах, а не заявление о полном национальном охвате вакансий. В списке из 19 работодателей ByteDance — единственная проверенная цель начальной загрузки; остальные 18 корней работодателей начинаются как неодобренные кандидаты и не могут создавать вакансии, пока не будут проверены, подтверждены и одобрены.

Сбор ByteDance/Feishu ограничен 50 страницами, 5 000 строк вышестоящего уровня и 24 МБ на вызов источника. Когда один вызов не может достичь хвоста, зафиксированный запуск сохраняет отпечатанный курсор с проверкой поколения в source.collection.resume; следующий сегмент обновляет одну головную страницу, а затем продолжает хвост с одной страницей намеренного перекрытия. Запись вакансий и продвижение курсора используют одну атомарную транзакцию Реестра. Перед любой мутацией Реестр сравнивает и заменяет как ревизию источника, прочитанную коллектором, так и сохранённое поколение курсора; при любом конфликте не записываются ни вакансии, ни курсор. Предпросмотр, сбой или конфликт никогда не продвигают сохранённую позицию. Возобновлённый хвостовой сегмент остаётся 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 (ключ Baidu не требуется) запустите npm run live-source-check. Он проверяет официальные URL-адреса приложений и печатает компактную сводку, а не необработанные ответы или описания вакансий. Предпросмотр читает применимое окно, но никогда не фиксирует вакансии и не продвигает сохранённый курсор возобновления. Соответствующий GitHub workflow можно запустить вручную или пометив pull request 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 и могут быть перемещены с помощью переменных окружения.

Подключите любой LLM через MCP

Запустите сервер 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 остаётся доступным без ослабления этой серверной границы.

Необязательное обнаружение Baidu

Скопируйте пример конфигурации и установите свой ключ локально или как секрет 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.

Отсутствие настройки Baidu не останавливает сбор одобренных источников. Это только оставляет обычные задачи активного обнаружения по ключевым словам явно заблокированными; Common Crawl без ключа продолжает обрабатывать контролируемые задачи site: плана запроса.

Официальная ссылка: Baidu Qianfan AI Search API.

Ежедневное общенациональное обновление в полночь

Встроенный workflow запускается в 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 реальные успешные доказательства запусков в текущем Реестре. Фикстуры и ручной ежедневный запуск никогда не считаются живым провайдером или успехом GitHub Actions.

Следуйте воспроизводимому чек-листу в docs/VERIFY.md.

Границы

Oriole обрабатывает публичные, не требующие входа веб-источники. Он намеренно исключает частные группы WeChat, OCR изображений, почтовые ящики, страницы с CAPTCHA/только входом и другие частные каналы. Он не подаёт заявки на вакансии и не принимает решений о трудоустройстве. Публичный веб-доступ не отменяет условия сайта, политику 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.