Oriole · 黄雀 Job Engine

중국어 문서 · 아키텍처 · 소스 · 검증

방대한 웹을 단순히 스크래핑한 채용 목록의 불투명한 더미가 아니라, 추적 가능하고 검토 승인을 거치는 채용 출처 지도로 만드십시오.

Oriole는 오픈소스이며 중국 전역을 대상으로 하는 유형발 지능 에이전트입니다. 공개 채용 게시자를 발견하고, 게시자의 방화벽 확인, 수집 전 인간의 승인을 요구하며, 실제 근무지 기준으로 채용 정보를 정규화하고, 그 결과를 16개의 MCP 도구를 통해 어떤 LLM에든 노출합니다.

이는 의도적으로 단일 웹사이트가 아니라 엔진(engine)으로 설계되었습니다. 명령줄(CLI)에서 실행할 수도 있고, 자정으로 스케줄을 잡을 수도 있으며, 결정적 핵심(core)을 다른 Node.js 서비스에 임베드할 수도 있고, 자격 증명을 그 모델에 넘기지 않은 채 MCP 지원 모델을 연결할 수도 있습니다.

구현된 분류

Related MCP server: OpenAI-Compatible MCP Gateway

소스 모델

발견 채널과 직업에 대한 소스가 서로 다른 역할을 합니다.

• Baidu은 감지 radar입니다. 구성 시, Oriole이 Baidu 공식 Qianfan 엔드포인트를 호출하고 요청 시 moot 객체에 대한 proof를 저장합니다. Baidu 결과 페이지를 스크래핑하지 않습니다.

• Common Crawl은 특정 site: 패턴을 위해 키 없이 사용 가능한 아카이브/인덱스 폴백입니다. 공개 URL이 존재했는지 검증하는 용도지 불 컬러텍스트 검색 엔진이나 최종 채용 정보 소스는 아닙니다.

• 공공 디렉토리은 국가·지방 고용, 대학교 취업, 공공기관, 중앙 국유 기업 및 정부 부처 채용 정보 디렉토리 등 공식 게시자를 시드합니다.

• 회원사 사이트, 공식 ATS 채널, 정부 고용 페이지는 장기 채용 정보 수집 대상입니다. 소스는 안전 검사와 사람승인 검토를 통과해야만 그 작업이 Registry에 들어올 수 있습니다.

• 사용자 지금은 다른 Agent나 운영자가 공개 URL을 제출할 수 있도록 하되, 동일한 검사와 승인 절차를 유지합니다.

공식적으로 검증된 소스 시드를 사전 초기화하거나 공식 카테고리에서 후보 결과를 발견하는 데 Baidu API 키가 필요 없습니다. 쿼 가능 플랜별로 각 공급자의 역할이 명확합니다. 즉 일반적인 키워드 발견은 Baidu 전용입니다. Baidu를 사용할 수 없다면 그 작업들은 status.discoveryBacklog와 발견 실행 통계에서 뚜렷이 blocked 상태로 남습니다. Common Crawl은 통제된 site: 작업 대상에서만 허용됩니다. 차단 된 job은 완료 보고로 처리되지 않습니다.

공개 저장소에는 채용 레코드가 0개 포함되어 있습니다. npm run init는 명시적으로 감색된 9개의 공개 소초를 가져옵니다(Bytedance를 포함한 8개의 고용주 통제 채널 + 정부 고용 채널 1개). 따라서 전신 복제(clone)한 경우에도 낡은/비공개 스냅샷을 게시하지 않고도 기능성 수집 대상을 갖게 됩니다. 이것은 검색 결과 자동 승인을 의미하지는 않습니다. 시드 itself는 인가판을 거친 신뢰 판정이고, 모든 새로 발견된 소스는 여전히 검사 후 승인 과정이 필요합니다.

Coverage는 완전한 국가 전체 채용 정보 잡아내기를 나타내는 주장이 아니라, 측정 가능하고 부족한 부분을 보여주는 리포트입니다. 19개 이머전 워치리스트마다 ByteDance만 승인된 초기 운영 대상이며, 나머지 18개 직원 측 루트는 비승인 후보로 시작됩니다. 따라서 프로브, 검증, 승인 전까지는 채용 작업을 생성하지 않습니다.

ByteDance/Feishu 수집은 한 번 호출로의 50 pages, 5,000source rows, 24MB로 상한이 있습니다. 한 번 호출이 파일 끝까지 도달하지 못하면, 커밋된 실행이 source.collection.resume 아래에 지문 및 generation 검증된 커서를 저장합니다. 다음 실행은 head page 하나를 새로고침하면서, 일부러 한 page의 오버랩을 사용하여 tail부터 이어서 쓸어내려갑니다. 채용 정보 쓰기와 커서 옮김은 하나의 결정적(atomic) Registry 트랜잭션으로 갈이 수행됩니다. 커서 이동 전/후에 Registry가 컬렉터가 읽은 source의 revision과 저장된 커서의 generation을 각 각 CSA(compare-and-swap)하며, 어느 한쪽이라도 충돌하면 채용 정보도 커서도 쓰지 않습니다. 프리뷰, 장애/취소는 저장된 위치를 절대 옮겨놓지 않습니다.

재개된 tail 조각는 실제로 회전 완료가 되어도 pagination.complete: false 상태로 남습니다. 이는 offset feed의 내용이 실행마다 바뀔 수 있어, 두 실행 사이의 단일 snapshot처럼 취급하는 채용 누락을 확인할 수 없기 때문입니다. 기존 채용된 작업 결과와 Registry 상태를 별도로 점검하십시오: npm run coverage는 source/channel/region 상태를 체크하며 페이지네이션이나 resume 진행 상태는 읽지 않습니다. 일정하고 정확한 provider 가이드라인과 seed 카탈로그은 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을 검증하고 요약 요약만 출력합니다(원시 응답을 노출하지 않음). 즉시 수용 가능한 시간 창을 읽지만 커밋은 만들지 않으며 저장된 resume 커서도 진전하지 않습니다. 동일한 GitHub Actions workflow는 수동 실행 또는 풀 리퀘스트에 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 revision을 검토하고 승인 절차를 명시하세요:

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 — Atomic/Portable Registry;

• .huangque/artifacts/ — 내용 주소가 있는(compensated) 압축 artifact;

• .huangque/latest-audit.json — 최신의 machine readable 셀프 오딧;

위의 경로는 Git이 무시하며, 환경 변수로 다른 위치로 옮길 수 있습니다.

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"
      }
    }
  }
}

서버에서는 다음을 위한 도구를 사용할 수 있습니다: pipeline 실행, run 조회, 상태 확인, 측정 가능한 소스 커버리지 갭, 발견, 공개 소스 등록, 검사(probe), 소스 목록, 채용 목록, 지역 목록, graph 읽기, 사람 검토, 수집, 예약 대기 항목, 감사, 그리고 portable export.

huangque.list_regions는 고유 채용(unique-job) 합계를 Hongo 단위, Hongo 전용 단위, 그리고 각 제2차 도시 단위로 보고합니다. 어느 한 성(province) 안에서 두 도시에 채용이 명시된 채용 정보는 성 합계에 한 번, 각 해당 도시는 별도로 한 번으로 계산됩니다.

MCP를 통한 소스 승인은 기본 off입니다. 운영자가 의도적으로 HUANGQUE_ALLOW_MCP_REVIEW=1을 설정해야 하며, CLI에서의 승인은 그 서버 경계를 느슨하게 하지 않고 활성화되어 있습니다.

선택사항 Baidu 탐지

예제 환경 설정을 복사한 다음 키를 로컬 또는 GitHub Actions의 secret으로 설정하세요. 프로젝트 비밀번호를 커밋하지 마세요.

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를 구성하지 않아도 승인된 소스 수집이 중단되지는 않습니다. 일반적인 키워드 기반 active discovery 작업만 명확히 차단되고, 키가 없는 Common Crawl은 예약된 계획의 통제된 site: 작업을 계속 처리합니다.

관련 공식 문서: Baidu Qianfan AI Search API.

자정 국내 업데이트

번들된 workflow는 매일 16:00 UTC에서 실행되고 이는 한국 시간의 다음 자정에 해당합니다:

npm run daily

러너는 베이징 날짜 기준 완료 마커를 쓰므로, --force 플래그로 지정하지 않는 한 재시도해도 해당 일의 중복 실행이 되지 않습니다. GitHub Actions 스케줄이 몇 분 늦게 시작될 수 있습니다. 마커 기준 작업 날짜는로컬 runner가 정하며 큐 시각은 아닙니다. 상세한 것은 docs/SCHEDULING.md을 참조하세요.

그래프를 목록처럼 제공하지 않기

각 그래프 edge에는 증거와 관측 시각이 저장됩니다. edge 구성은:

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

Publisher와지역 관계는 최신 research에서 만들어집니다. 검증된 소스의 identity가 바뀌면 기존의 published_by 관계와 covers_region 관계는 잘못된 히스토리 업증으로 남기 않고 제거됩니다.

“완성된 그래프”의 의미는 레지스트리 모든 소스에대해 진단에서 증명된 relationship이 있고, 그 관계가 모든 사람이 감사할 수 있음을 뜻합니다. 등록된 카탈로그만으로 모든 중국 고용주 및 모든 진행 중인 채용이 나타난다는 의미는 아닙니다. Oriole는 이 그래프를 계속 확장하고 다시 무결성하게 확인되도록 설계되어 있습니다.

각성 후 신뢰

npm run verify
npm run audit

test suite 코드들은 인반 structural normalization, 지역 등록 분류, 채용 local multiple location, provider별, bounded 단계 large rotation, cursor atomicity/concurrency, 신뢰 그래프 evidence, Registry retention, MCP lifecycle, SSRF 통제, rust/hook 처리, source ownership 과 job의 불변성. 런타임 오딧는 별도로 “현재 Registry에서 외부 provider 및 GitHub 배포 스케줄이 실제 성공적인 run evidence 기록을 보이는지” 대해 보고합니다. 테스트 고정 값/flask와 형식적으로 수동 실행한 일일 구현은 live provider 또는 GitHub Actions의 성공으로 집계되지 않습니다.

재현 가능한 검증 순서는 docs/VERIFY.md 시 따라 따르도록 하세요.

범위

Oriole는 상태 접속 불필요 공개 정보 채널만 처리합니다. 사적인 WeChat 그룹, 이미지 OCR, 이메일의 받은 편지함 GXP CAPTCHA/로그인 전용 웹 페이지 등은 제외합니다. 사용자를 대신해 입구 신청을 하거나 고용 판단을 내리지 않습니다. 공용 웹에 개방해야 하는 대가로 운영𝔰이트는 사이트 이용약관, robots 정책, 데이터베이스권, 개인정보 보호책 규정를 위반하는 것은 아닙니다. 배포자는 각 채널에 따라 법률/규정을 충족할 책임이 있습니다.

프로젝트 layout

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를 통해 신고해 주시기 바랍니다.