yongle-worker 0.1.0

Local worker SDK + control plane API MVP

yongle-worker MVP

yongle-worker 是一个本地采集 SDK + 控制面 API 的最小可运行实现。

• 数据面在本地执行：SDK 直接请求第三方 URL，出口 IP 为用户本机。
• 控制面只做编排：鉴权、任务下发、心跳、结果回传、计费统计、审计。
• 双层脱敏：客户端本地预处理 + 上报前二次校验；平台端再次强制校验。

目录

yongle_worker_mvp/
  pyproject.toml
  README.md
  .env.example
  examples/
    run_once.py
  scripts/
    start_control.py
  src/
    yongle_worker/
      __init__.py
      client.py
      config.py
      models.py
      executor.py
      sanitizer.py
      checkpoint.py
      rate_limiter.py
      logging_utils.py
    yongle_control/
      __init__.py
      __main__.py
      app.py
      auth.py
      config.py
      db.py

安装命令

直接安装（PyPI）

pip install yongle-worker

私有 PyPI 安装

pip install --index-url https://your-private-pypi/simple yongle-worker

5 分钟跑通

1. 创建虚拟环境并安装依赖

python -m venv .venv
# Windows
.venv\Scripts\activate
pip install -U pip
pip install -e .

2. 配置环境变量

copy .env.example .env

3. 启动控制面 API

python scripts/start_control.py

4. 另开终端执行一次任务

python examples/run_once.py

预期：

• SDK 自动注册 agent
• 拉取 demo 任务 task-demo-001
• 本地请求 https://httpbin.org/json
• 完成脱敏和回传

控制面 API

• POST /agent/register
• POST /tasks/pull
• POST /tasks/{id}/heartbeat
• POST /tasks/{id}/result
• POST /tasks/{id}/fail
• GET /policy/current

鉴权方式：x-api-key 请求头。

脱敏策略说明

支持 3 种策略模式：

• strict（默认）：姓名/手机号/身份证/邮箱等敏感字段禁止上报（drop 或 block）
• research：允许本地保留研究字段，但默认上报仍会 mask/drop/block
• custom：用户通过 custom_patterns 与 rules 自定义

动作：

• mask：掩码
• drop：删除字段
• block：拒绝上报并报错

每次上报必须包含 policy_version，平台端会校验任务绑定版本。

常见错误排查

1. 401 invalid api key

• 检查 .env 中 YONGLE_API_KEY 与 YONGLE_CONTROL_API_KEYS 是否一致。

2. policy_version mismatch

• 任务下发后策略版本变化，或客户端篡改了 policy_version。

3. blocked field_type=id_card

• 命中了 block 规则。可在策略中调整，但平台端仍会执行强制校验。

4. http execution failed

• 本地网络不通、目标站超时、或 TLS/代理配置问题。

发布流程（TestPyPI + 正式 PyPI）

python -m build
twine upload --repository testpypi dist/*
twine upload dist/*

验证清单

1. 安装后 import 成功

python -c "from yongle_worker import WorkerClient; print(WorkerClient.__name__)"

2. run_once 成功拉任务、执行、回传

python examples/run_once.py

3. 敏感字段被拦截/掩码（示例日志）

{"ts":"2026-04-16T12:00:00+00:00","level":"INFO","logger":"yongle_worker","message":"sanitization hit","task_id":"task-123","agent_id":"agent-abc","policy_version":"2026.04.16.1","field_type":"email","action":"drop"}
{"ts":"2026-04-16T12:00:01+00:00","level":"ERROR","logger":"yongle_worker","message":"task failed","task_id":"task-456","agent_id":"agent-abc","policy_version":"2026.04.16.1"}

打包输出

构建后产物位于 dist/，可用于 pip install 验证。