arkevo_task_scaling：把真实专业软件资料变成 RL task

先建立全局心智模型

这里的“任务”不是一句 prompt。一个可交付任务至少同时包含：像真实委托的题面、合理阶段的 workspace、声明交付物、可靠 verifier、来源与版本证据，以及可复现的运行条件。原工程只是资料，不会自动变成任务；能打开文件也不等于任务可解、可评分或可分发。

flowchart TD
  T["01 Taxonomy
职业场景 · 工作流 · 输入输出"] --> A
  R["02 Raw data
工程 · 资产 · 视频 · 配套文件"] --> S["准入与脱敏派生
原生检查 · 依赖 · 干净输入"]
  S --> A["03 初版任务
题面 + workspace + verifier"]
  A --> C{"派发 workspace
是否含工程文件？"}
  C -->|"有"| B["输入基线
同版 verifier + RewardKit"]
  C -->|"无"| P["正常试解
基线字段为 null"]
  B --> P["04 多模型试解
3–5 配置 · 每题各 1 次"]
  P --> Q["05 聚合审题
逐项分析 · 校准 · 修订"]
  Q -->|"修订或重跑"| A
  Q -->|"验收并冻结"| F["Final
冻结题面 · 输入 · verifier · 参考"]
  F --> E["06 正式评测
每配置每题独立 3 次"]
  E --> D["07 数据产品
Harbor 包 · 证据 · HTML"]
  F --> V["固定软件 probes + RewardKit
Rule 80% · VL 20% · Agent 0%"]
  V -.-> E
  H["Harbor 环境接口"] --> BK["Bunker adapter
通用版待实现"]
  H --> DK["Docker backend
本仓待验证"]
  H --> VM["专用 VM backend
后续"]
  P -.-> H
  E -.-> H
    

01–07：每一步吃什么、做什么、产出什么

CLI：arkevo 命令全表

src/arkevo_task_scaling/cli.py 是薄入口。所有命令输出 JSON；基础检查不会启动 Blender、不会调用模型，也不会产生付费请求。

.venv/bin/arkevo check --root .
.venv/bin/arkevo plan --root . --software blender
.venv/bin/arkevo taxonomy --root . --software blender
.venv/bin/arkevo sources --root . --software blender --asset-root ../blender
.venv/bin/arkevo task-check examples/blender/building-generator/task.json \
  --policy configs/privacy.json
.venv/bin/arkevo pipelines --root .
.venv/bin/arkevo pipeline-resolve --root . --tag complex-assets
.venv/bin/arkevo pipeline-snapshot --root . \
  --pipeline-id blender-complex-assets --pipeline-version 0.4.4
.venv/bin/arkevo privacy-check PAYLOAD --root .
.venv/bin/arkevo metrics --plan evaluation-plan.json --trials trials.jsonl

数据合同：task.schema.json

task.json 是制题侧合同，不应整体暴露给 solver。当前 Schema 明确是 draft only，且 status 只能为 draft；KUKA 的冻结状态由个案证据维护，通用合同校验器不会“晋级”。

{
  "task_id": "blender-building-generator-candidate",
  "task_version": "0.1-draft",
  "pipeline_ref": null,
  "workflow_primary": "MOD-12",
  "profession_primary": "G",
  "source_ids": ["procedural-buildings"],
  "deliverables": [
    {
      "path": "output/final.blend",
      "purpose": "可继续调整并运行的建筑生成工程"
    }
  ],
  "requirements": [],
  "criteria": []
}

contracts.py 额外做了什么

数据合同：taxonomy.schema.json

Taxonomy 编码的不是“工具菜单”，而是 职业场景 · 工作流 · 输入 · 输出 · 验收重点。Geometry Nodes 或 MCP 是实现手段，不会自动形成新职业。

{
  "id": "MOD-04",
  "group": "MOD",
  "title": "建筑模块与套件制作",
  "professions": ["G", "A", "F"],
  "commission": "制作墙、门窗、转角和屋顶模块",
  "input": "模块清单、网格步长、立面／平面、拼接尺寸和允许变化",
  "output": "可复用模块库及组合验证场景",
  "verification_focus": "接口、尺度、枢轴和多种拼接；单栋楼不能替代模块能力"
}

Pipeline versioning：配方身份不是一个版本字符串

当前可用路线是 blender-complex-assets@0.4.4。完整身份是 pipeline_id + pipeline_version + pipeline_digest；tag 只用于选择和分组，progress.json 只记录进度，两者都不进入 digest。

versions.py 怎样计算 fingerprint

1. 读取 configs/pipelines.json 中 profile。
2. 对每个 component 文件保存相对路径、字节数与 SHA256。
3. 递归枚举 code_roots，拒绝 symlink，跳过 cache / .pyc。
4. 按 role 和路径排序，构造不含 tags 的 payload。
5. 用紧凑、排序键、禁止 NaN 的 JSON 序列化，再计算 SHA256。
6. snapshot 自己仍标记 execution_started:false、native_runtime_validated:false。

def content_digest(value):
    body = json.dumps(
        value,
        sort_keys=True,
        separators=(",", ":"),
        ensure_ascii=False,
        allow_nan=False,
    )
    return hashlib.sha256(body.encode()).hexdigest()

Privacy 与 sanitization：三道边界都要检查

configs/privacy.json 定义 rl-task-basic-sanitization@0.1.0。目标是让真实账号、宿主绝对路径、邮箱、凭据和认证链接不进入模型可见材料或产品，同时在私有控制侧保留原始物、哈希和替换映射。

privacy.py 的规则与保护

status = (
    "failed" if findings
    else "coverage_pending" if uninspected
    else "text_checks_passed"
)

Native intake：怎样让 .blend 真正“可进入制题”

来源哈希只回答“是否是登记的那份字节”。原生准入还要回答：能否用固定软件安全打开、依赖是否齐全、目标功能是否工作、保存重开是否保持、渲染是否有效、脱敏是否破坏工程，以及授权是否允许计划用途。

flowchart LR
  A["登记 URL / SHA / 版本 / 权利线索"] --> B["固定 Blender
factory-startup + disable-autoexec"]
  B --> C["结构与依赖 inventory"]
  C --> D["功能 probes
播放 / 控制 / 渲染"]
  D --> E["对副本脱敏
路径 / 名称 / metadata / 像素"]
  E --> F["保存并重开"]
  F --> G["重复结构与功能检查"]
  G --> H["媒体 OCR / metadata / 人工复核"]
  H --> I["serialized string 补查"]
  I --> J["干净 authoring_input
按 SHA 绑定回执"]
    

准入层级

1. 来源已登记，URL、家族、哈希和许可线索存在。
2. 本地字节与登记 SHA256 一致。
3. 依赖已准备，外部文件与插件可定位。
4. 在固定版本原生软件中安全打开。
5. 相关控制、播放、模拟或参数功能实际运行。
6. 保存重开、渲染和媒体复核通过。
7. 授权用途经审核；“可下载”不等于“可转售”。

Sources：来源登记不等于许可或可运行

software/blender/sources.json 当前登记 4 个历史 Blender demo：BMW27、radial tiling、procedural buildings、pizza delivery。保存版本横跨 2.73、2.93、4.2、5.0，全部仍标记 runtime_validated:false 与 rights_status:pending_review。

Verification：Rule 80 / VL 20 / Agent 0

这是 reward 贡献比例，不是 criterion 数量、调用次数或耗时比例。规则通道可以包含真正的功能测试；VL 只判断难以可靠程序化的有限视觉质量；自主探索 Agent 被移到制题、probe 开发、审题和离线复查。

base_reward = 0.8 * rule_score + 0.2 * vl_score
# 通道内部 criteria 按各自显式权重汇总。
# 核心失败可应用校准后的 cap；success 另行计算。

固定软件 probes 与 RewardKit 的分工

Input baseline：输入已有多少，不等于模型新增多少

reward_delta = final_reward - input_reward
# 有效范围 [-1, 1]；负值保留，用于发现退化。
# 它只用于审题诊断，不替代正式 reward 或 success。

通用约定计划保存为 input-baseline.json 与 baseline-comparison.json，但当前没有 Schema 或 CLI；KUKA 已由个案脚本完成。

Evaluation：avg@3、pass@3 与错误语义

正式评测在任务、输入、环境、verifier、参考、阈值、judge 和预算冻结后进行。每个配置对每题独立运行三次；“同一作品打三遍分”不算三次。

avg@3  = (1 / N) * sum(
    (r_i1 + r_i2 + r_i3) / 3
    for each planned task i
)

pass@3 = (1 / N) * sum(
    max(s_i1, s_i2, s_i3)
    for each planned task i
)

evaluation.py 的实际聚合核心

valid = (
    len(attempts) == 3
    and all(t["status"] != "verification_error"
            for t in attempts.values())
)
per_task.append({
    "task_id": task_id,
    "complete": valid,
    "avg@3": mean(t["reward"] for t in attempts.values())
             if valid else None,
    "pass@3": int(any(t["success"] for t in attempts.values()))
              if valid else None,
})

聚合器还拒绝：exploration 混入 evaluation、计划外 task、重复 run ID / attempt、pipeline identity 不一致、task/verifier/configuration 版本不一致。仓库 synthetic fixture 的结果是 avg@3=0.35、pass@3=0.5，不是真实模型基线。

Model config 与 preflight

configs/models.json 保存候选字符串，不把“名字写进配置”当作 endpoint 已可用。执行前还必须固定 runner、完整模型 ID、effort 映射、endpoint、工具、预算、客户端版本和配置哈希。

Infrastructure：统一接口，后端逐个验收

flowchart LR
  A["Arkevo
task · workspace · verifier · manifest"] --> H["Harbor
trial 调度 · Agent · 产物交接"]
  H --> E{"Environment backend"}
  E --> B["Bunker
专用个案已跑
通用 adapter 待实现"]
  E --> D["Linux + Docker
Harbor 已有 backend
本仓待验证"]
  E --> V["Windows / desktop VM
后续"]
  H --> R["独立 verifier"]
  R --> P["软件 probes"]
  P --> K["RewardKit"]
    

Harbor 环境接口至少要记录

• OS / CPU 架构、软件/插件版本、solver/verifier image digest、CPU/GPU/内存/磁盘/显示需求。
• 就绪检查、命令与总超时、网络策略、环境变量、执行用户。
• trial 独立 ID、创建/取消/销毁、失败时证据先导出再清理。
• workspace 上传、声明产物下载、路径边界与内容哈希。
• task/workspace/verifier/config/backend 版本、资源、日志、耗时与费用依据。

templates/harbor 为什么会主动失败

模板只声明 Harbor 1.3 形状、/app/output artifact、独立 verifier 和 RewardKit 的 0.8/0.2 权重。它缺少固定软件镜像、真实 probes、VL judge、私有参考和校准阈值，所以 tests/test.sh 故意退出，不制造常量 reward 或存在性假通过。

配置文件：谁管什么

Python library：模块之间怎样协作

包内代码刻意保持“普通 domain function + 薄 CLI”。这样 Harbor、脚本或未来调度器都能复用同一逻辑，也能在不调用模型和 Blender 的单元测试中验证边界。

# 这些值会被拒绝：
{"reward": 0, "reward": 1}  # duplicate key
{"reward": NaN}             # non-finite
"../private/reference"      # parent traversal
"/host/path/file.blend"     # absolute path
"a\\b"                      # non-portable separator

# 合格包内路径：
"workspace/start.blend"
"output/final.blend"

目录地图

arkevo_task_scaling/
├── configs/                  阶段、版本、模型、隐私、评分与进度
├── pipelines/                不可覆盖的配方 fingerprint snapshots
├── docs/                     设计与运行协议
├── software/blender/         Taxonomy、sources、实施入口与历史证据
├── src/arkevo_task_scaling/  CLI、contracts、versions、privacy、metrics
│   └── schemas/              task/taxonomy/source/evaluation/trial JSON Schema
├── examples/blender/         明确标记 draft 的合同示例
├── templates/harbor/         故意不可运行的集成边界样板
├── scripts/                  导入、原生准入、脱敏、个案执行脚本
├── tests/                    合同、版本、隐私、来源、CLI、指标测试
├── data/                     本地大文件与私有参考约定
├── runs/                     运行产物，Git 忽略
├── products/                 冻结包与 HTML，Git 忽略
└── web/kuka-task/            KUKA 展示个案

零基础推荐阅读顺序

1. README.md：先看 01–07 全图和当前状态。
2. 本页：建立通用合同、CLI、版本、隐私与评测心智模型。
3. docs/DESIGN.md：理解为什么这样分层。
4. docs/MODULES.md：把阶段映射到文件与实现状态。
5. software/blender/WALKTHROUGH.md：看首题真实进度。
6. software/blender/LESSONS.md：看评分、相机、内存、接口与脱敏踩坑。
7. 按问题查 VERIFICATION / EVALUATION / PIPELINE_VERSIONS / SANITIZATION / INFRASTRUCTURE。
8. 最后读 src/ 与 tests，用测试确认协议不是口号。

与 arkevo_blender_rl 的耦合与边界

arkevo_task_scaling 是上游方法论与首例实验场；arkevo_blender_rl 是 Blender 专用的批量自动化流水线（authoring → solver → scoring → packaging）。两者不是同一个执行器，也没有共享运行时 import。

测试告诉我们的真实边界

常见误解与重要 caveats

术语表

研究者可以从哪里开始动手