Human-controlled AI onboarding for Feishu/Lark — configurable workflows, document OCR and review, Bitable sync, and reminders in one inspectable FastAPI app.

HR Onboarding Agent coordinates the journey from pre-boarding documents to HR review, reminders, and Feishu/Lark updates. Models assist with extraction and review; deterministic rules and people remain in control of consequential decisions.

• Run a complete local demo with three fictional candidates and no credentials.
• Give HR and candidates separate task-focused workspaces.
• Configure due dates, owners, visibility, and workflow nodes in safe YAML.
• Plug in mock, OpenAI, Gemini, Ark/Doubao, Zhipu, or DeepSeek paths.
• Treat uploads and OCR text as untrusted evidence, with manual-review gates.

This is an early-stage reference implementation, not a payroll, identity-verification, legal, or autonomous hiring decision system. DEMO_MODE=true is intentionally open and must never process real HR data.

Requirements: Python 3.11+.

git clone https://github.com/z15114664687-dot/hr-onboarding-agent.git
cd hr-onboarding-agent
./scripts/demo.sh

Open the HR workspace, candidate workspace, or health check. The script creates a local virtual environment, installs pinned runtime dependencies, copies the safe demo configuration, and starts the app on localhost.

Docker users can run:

./scripts/demo.sh --docker

No Feishu/Lark account, model key, OCR key, or candidate record is required. External AI remains disabled.

The deterministic demo seeds three fictional candidate journeys only when the database is empty. You can:

1. review current, completed, and overdue workflow nodes;
2. update HR-owned fields and exercise the local Bitable synchronization path;
3. inspect material status and deterministic OCR/review output;
4. upload a synthetic PDF or image from the candidate workspace; and
5. see reminder-ready overdue state without sending a real notification.

The seed records live in examples/demo_candidates.json. Synthetic prompt-injection regression files live in examples/demo_documents/. Rebuild the screenshots with ./scripts/capture_demo.sh.

flowchart LR
    C["Candidate workspace"] --> U["Untrusted upload"]
    H["HR workspace"] --> W["YAML workflow engine"]
    U --> V["Size, MIME, signature, and path validation"]
    V --> O["OCR provider"]
    O --> B["Untrusted-content boundary"]
    B --> R["Deterministic rules"]
    B --> L["Optional LLM second pass"]
    R --> G["Human review gate"]
    L --> G
    W --> D["SQLite workflow state"]
    G --> D
    D --> F["Feishu/Lark and Bitable"]
    D --> S["APScheduler reminders"]

Uploaded documents and OCR-derived text are data, never instructions. Suspicious instruction overrides, secret requests, self-approval language, fake system prompts, active HTML, and unsafe URLs force manual review. This reduces risk; it does not eliminate prompt injection. Read the architecture and threat model.

Set WORKFLOW_CONFIG_PATH to a version 1 YAML file. The default is examples/workflows/default.yaml; a shorter alternative is in examples/workflows/engineering.yaml.

version: 1
name: Synthetic engineering onboarding
steps:
  - node_name: prepare_access
    display_name: Equipment and access
    offset: 0
    unit: calendar_day
    owner_role: it_admin
  - node_name: manager_check_in
    display_name: Manager check-in
    offset: 5
    unit: business_day
    owner_role: manager

Supported units are calendar_day, business_day, and month. Node names must be unique lowercase snake_case. Unknown keys, unsafe YAML tags, invalid roles, oversized files, and duplicate nodes fail closed at startup/use.

The active template is process-wide. Restart the application after changing WORKFLOW_CONFIG_PATH or its YAML file so UI labels, ordering, visibility, and new cases use one consistent catalog.

External processing requires both ALLOW_EXTERNAL_AI=true and the chosen provider credentials. OpenAI support uses the existing httpx dependency, structured output when a schema is supplied, input_image for images, and input_file for PDFs. Provider tests use mocked transport only. See provider setup.

• HR/admin endpoints require HTTP Basic auth outside demo/test mode.
• Candidate links use expiring HMAC tokens bound to one case and then a SameSite, HttpOnly cookie.
• Feishu/Lark HTTP callbacks require a verification token, reject stale events, and claim idempotency keys.
• Provider endpoints require public HTTPS unless private endpoints are explicitly allowed.
• Raw event payload and OCR persistence are off by default.
• GitHub workflows run Python 3.11 tests, Docker health smoke, CodeQL, dependency review, pip-audit, Bandit, secret scanning, license inventory, and CycloneDX SBOM generation.

Files are not encrypted at rest or malware-scanned, and this version has no organization SSO, token revocation, retention engine, or multi-tenant isolation. Review SECURITY.md, docs/THREAT_MODEL.md, and OSS_SECURITY_AUDIT.md before any real deployment.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
./scripts/verify_release.sh

The suite needs no live credential or network call. Use python scripts/audit_public_release.py --root . before sharing a snapshot. GitHub launch settings and first issues are in docs/GITHUB_LAUNCH.md.

• Organization SSO/OIDC and role-based access control
• Encrypted object storage, malware scanning, retention, deletion, and restore tests
• PostgreSQL/Alembic and distributed scheduler ownership
• Authenticated Feishu/Lark encrypted callback handling
• Multi-tenant isolation and per-tenant keys
• Permission-aware retrieval and exportable audit logs
• Optional Slack/Teams adapters after the Feishu/Lark reference path is stable

See the launch issue list for scoped contribution opportunities.

Read CONTRIBUTING.md before opening a pull request. Never put a vulnerability, credential, private document, or real candidate record in a public issue.

Licensed under the Apache License 2.0.