把任何可度量任务，接入一个会持续变好的系统。

核心抽象

把任意可度量任务统一抽象为：

target + metric + budget

• target：当前要优化的对象
• metric：怎样算更好
• budget：允许迭代多少轮

当前支持的目标类型

• text
• code
• html
• markdown
• config
• 实验性：顶层 Python callable（仅本地/CLI）

无 API key 的本地演示

python examples/demo_simple.py

这个 demo 不调用外部模型，主要用来验证优化循环本身。

启动 Web / API 服务

python -m autoloop.cli serve --host 127.0.0.1 --port 8000

默认 job 状态会持久化到 ~/.autoloop/jobs.sqlite3。

装饰器模式

from autoloop import loop

@loop(metric=len, budget=1)
def build_prompt(topic):
    return f"请写一个关于 {topic} 的标题"

装饰器会按输入缓存优化结果。相同输入复用结果，不同输入独立优化。

实验性 callable

result = loop(
    target=my_function,
    metric=my_metric,
    budget=2,
    experimental=True,
)

仅支持顶层 Python 函数；lambda、闭包、绑定实例方法和依赖自由变量的函数都会被拒绝。

常用命令

python -m autoloop.cli "请把这段说明写得更专业" --provider ollama --budget 5
python -m autoloop.cli ./notes.md --budget 6 --diff
python -m autoloop.cli "帮我润色这封邮件" --template work-email --provider ollama
python -m autoloop.cli history
python -m autoloop.cli continue <record_id>

CLI 能做什么

• 直接优化文本或文件
• 支持模板和自然语言 criteria
• 查看历史、删除记录、继续优化
• 支持 --diff、--output、--inplace
• 支持 serve 启动 Web / API 服务

Web 当前能力

• BYOK：API key 只保存在浏览器本地
• 模板选择与自定义 criteria
• 自动 target type 检测，默认 auto
• 任务事件流、取消、重试、复制结果
• 高级设置：direction、cost limit、target type

任务状态持久化

• job 状态和事件会落到 SQLite
• 服务重启后已完成任务仍可查询
• 中断或失败的任务可以显式 retry
• retry 会生成新的 job，并保留 retried_from 关系

通用目标

• 更清晰
• 更专业
• 更可执行
• 更有结构
• 更简洁

办公场景

• 邮件润色
• 汇报摘要
• 会议纪要整理
• 标题 / Headline 优化
• 提案表达优化
• Prompt 优化

History 记录什么

• 输入、目标类型、provider、criteria
• baseline、final score、improvement、cost、duration
• 每轮实验的 accept / reject 状态
• 策略、phase、reject reason、diff stats
• 继续优化所需的上下文信息

Job Runtime 记录什么

• job 状态：queued / running / cancelling / completed / cancelled / failed
• 事件流：proposal、accepted、rejected、completed、failed 等
• 原始请求参数和是否需要 API key 重试
• 历史关联和 retried_from 血缘关系

OptimizeRequest

任务状态与事件

• 状态：queued、running、cancelling、completed、cancelled、failed
• 事件：queued、baseline_scored、proposal_generated、candidate_rejected、candidate_accepted、cancel_requested、cancelled、completed、failed
• /jobs/{id} 返回持久化 job 数据、结果、错误、模板和重试来源。
• /jobs/{id}/events 通过 SSE 连续输出事件，适合 Web 界面实时展示。

读取任务详情

{
  "job_id": "a1b2c3d4",
  "status": "completed",
  "created_at": 1773501000.12,
  "updated_at": 1773501005.44,
  "input_text": "请把这段说明写得更专业",
  "provider": "deepseek",
  "target_type": "text",
  "history_id": "rec_20260315_001",
  "retried_from": null,
  "template_id": "general-professional",
  "request": {
    "target": "请把这段说明写得更专业",
    "provider": "deepseek",
    "criteria": null,
    "template_id": "general-professional",
    "budget": 8,
    "direction": "maximize",
    "target_type": "text",
    "cost_limit": 5.0,
    "temperature": 0.7,
    "judge_mode": null,
    "parent_id": "",
    "api_key_required": true
  },
  "retry_supported": true,
  "api_key_required_for_retry": true,
  "error": null,
  "result": {
    "best": "优化后的最佳结果",
    "score": 9.2,
    "baseline": 6.8,
    "improvement": 0.3529,
    "rounds": 6,
    "accepted": 2,
    "rejected": 4,
    "cost": 1.14,
    "duration": 4.83,
    "status": "completed",
    "accept_reason": "score_improved",
    "judge_mode": "score",
    "target_kind": "text",
    "best_diff_stats": {"added": 4, "removed": 2, "changed": 6},
    "history_id": "rec_20260315_001"
  }
}

取消与重试

{
  "job_id": "a1b2c3d4",
  "status": "cancelling"
}

{
  "provider": "deepseek",
  "api_key": "sk-...",
  "budget": 10
}

{
  "job_id": "e5f6g7h8",
  "status": "queued"
}

从历史继续优化

{
  "provider": "deepseek",
  "api_key": "sk-...",
  "budget": 6,
  "cost_limit": 3.0,
  "judge_mode": "score+pairwise"
}

{
  "job_id": "i9j0k1l2",
  "status": "queued"
}

SSE 事件流

event: baseline_scored
data: {"baseline": 6.8, "target_kind": "text", "target_type": "text"}

event: candidate_accepted
data: {"round": 2, "score": 8.7, "reason": "score_improved"}

event: completed
data: {"best": "优化后的最佳结果", "score": 9.2, "history_id": "rec_20260315_001"}

推荐部署形态

• 使用 python -m autoloop.cli serve 启动应用服务。
• 通过 --jobs-db 指定持久化 SQLite 路径，例如 /var/lib/autoloop/jobs.sqlite3。
• 用 Nginx、Caddy 或云负载均衡做 HTTPS 和域名转发。
• BYOK 模式下，API key 默认由浏览器本地保存，服务端按请求使用但不落盘。

启动示例

python -m pip install --upgrade pip
pip install '.[dev]' fastapi uvicorn

python -m autoloop.cli serve \
  --host 0.0.0.0 \
  --port 8000 \
  --jobs-db /var/lib/autoloop/jobs.sqlite3

为什么不是单次生成，而是多轮优化？

AutoLoop 的目标不是“先生成一个答案”，而是“在预算和约束内不断找更好的答案”。如果一个任务可以被评分，它就适合进入这个循环。

普通用户需要自己写 metric 吗？

不需要。Web 和 Service API 可以直接用模板或自然语言 criteria。Python API 更适合需要完全自定义评估逻辑的开发者。

任务取消后会丢结果吗？

不会。取消后会返回当前已经找到的最佳结果，并把状态写成 cancelled。如果任务还没产生更优结果，最佳结果可能仍然是 baseline。

服务重启后正在运行的任务会怎样？

当前版本不会自动恢复运行中的任务。它们会被标记为失败，并可以通过 /jobs/{id}/retry 或 Web 的重试入口重新发起。

为什么 retry 需要重新传 API key？

因为 Web 默认采用 BYOK，服务端不会持久化用户密钥。这样更适合 beta 和自托管场景，也能降低密钥托管风险。

callable 优化适合线上使用吗？

暂时不建议。它是本地 / CLI 的实验能力，虽然有子进程沙箱和危险调用限制，但不是强安全边界，不应该当成多租户执行环境。

当前限制

• score+pairwise 只在分数接近时触发 pairwise 裁决
• Web 当前只支持取消任务，不支持 pause / resume
• BYOK 模式下，provider 需要密钥时，retry 也需要重新提交 API key
• 重启后的运行中任务不会自动恢复，而是标记为失败后显式 retry

实验性 callable

• 仅面向本地 / CLI 路径，不进入首个 Web 多租户路径
• 走子进程沙箱，但这不是强安全边界
• 默认拒绝 lambda、闭包、绑定实例方法和危险调用
• 适合作为实验能力，不建议当成高强度代码沙箱