Metadata-Version: 2.4
Name: yongle-worker
Version: 0.1.0
Summary: Local worker SDK + control plane API MVP
Author: Yongle Platform Team
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: python-dotenv>=1.0.1
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"

﻿# yongle-worker MVP

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

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

## 目录

```text
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）

```bash
pip install yongle-worker
```

### 私有 PyPI 安装

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

## 5 分钟跑通

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

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

2. 配置环境变量

```bash
copy .env.example .env
```

3. 启动控制面 API

```bash
python scripts/start_control.py
```

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

```bash
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）

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

## 验证清单

1. 安装后 import 成功

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

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

```bash
python examples/run_once.py
```

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

```json
{"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` 验证。
