基础变量与 Reporter

环境变量

这些变量在脚本启动时自动注入，可直接使用：

变量	类型	说明
TASK_ID	str	当前任务实例 UUID
PROJECT_ID	str	所属项目 UUID
TASK_JWT	str	短期 JWT，用于调用 TaskFlow API
TASKFLOW_API_URL	str	TaskFlow API 地址，例如 http://localhost:8000/api
BG_SERVICE_ID	str	若脚本由后台服务触发，此字段非空

params

params 是一个普通 Python 字典，包含创建任务时传入的参数，对应元任务的 param_schema。

def run(params: dict, reporter) -> None:
    url = params["url"]           # 必填参数
    depth = params.get("depth", 3)  # 可选参数，提供默认值

reporter

reporter 用于更新任务的当前阶段和进度，在 TaskFlow UI 的任务看板中实时显示。

def run(params: dict, reporter) -> None:
    reporter.set_phase("抓取数据")    # 更新当前阶段文字
    reporter.set_progress(10)         # 进度 0-100

    # ... 执行逻辑 ...

    reporter.set_phase("生成报告")
    reporter.set_progress(80)

    reporter.set_progress(100)

reporter.set_phase(phase: str) -> None

参数	类型	说明
phase	str	当前阶段描述，展示在 UI 中

reporter.set_progress(pct: int) -> None

参数	类型	说明
pct	int	进度百分比，取值范围 0–100

project_tokens

project_tokens 是一个字典，包含在项目设置中配置的 Token（只读密钥），适合存储 API Key 等敏感信息。

def run(params: dict, reporter) -> None:
    github_token = project_tokens.get("github_pat", "")
    openai_key = project_tokens["openai_api_key"]

提示：Token 在项目的「设置 → Tokens」页面配置，值加密存储，脚本内只能读取，无法修改。

返回值

run() 函数的返回值会作为任务的 result 保存，可通过 wait_task() 或 API 查询获取。

def run(params: dict, reporter) -> dict:
    # ... 执行逻辑 ...
    return {"summary": "...", "count": 42}

返回值必须是 JSON 可序列化的类型（dict、list、str、int、float、bool、None）。