机器学习运行溯源

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install ml-run-provenance
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 ml-run-provenance。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

机器学习运行溯源是一套协议和本地 JSON 验证器，用于记录机器学习实验背后的上下文。它记录运行身份、活动意图、数据集与配置身份、仓库状态、执行尝试、恢复谱系，以及检查点和指标旁可用证据的限制。
该技能面向需要可信实验元数据的 Openclaw Skills 工作流，但不会假装自动提供可复现性。它不替代训练器、跟踪器适配器、回填服务或提供商集成，而是定义项目集成应实现和测试的契约及验证实践。

应用场景

为新的机器学习训练项目建立一致的命名和元数据契约。
在首次记录训练步骤前附加已批准的运行上下文。
审计现有活动中缺失的意图、代码、数据、配置或种子信息。
区分原始运行创建事实与后续回填重建的元数据。
在保留原始溯源的同时，使用当前代码、配置和检查点身份跟踪恢复尝试。
调查运行为何存在、由哪个提案授权，以及哪些证据支持其元数据。
在昂贵的训练活动或跟踪器上传前本地验证 JSON 元数据。
设计将存活状态、输出增长、失败和完成情况分开的进度及可观测性记录。

工作原理

定义元数据契约，包括稳定身份字段、活动意图、代码和数据身份、执行输入、证据限制及隐私边界。
实现项目本地的 run_context.py，作为已批准运行名称模式和精选元数据的事实来源。
运行纯 classify(run_name) 函数返回结构化上下文；未知名称产生明确的未知值和诊断，而不是猜测分类。
使用幂等的 attach_run_context(logger, context, resolved_config) 适配器，仅合并自有字段和标签，并保留无关用户备注。
在日志记录器初始化期间、首个训练步骤之前完成分类和元数据附加，并为每次执行尝试捕获一次代码和配置身份。
对恢复运行读取跟踪器状态，保留原始创建事实，并追加包含当前代码、配置和检查点身份的新尝试。
获得回填授权后，预览精确差异，标记重建字段及其来源，并仅对准确的运行 ID 应用已批准更改。
验证本地记录，然后核实实际制品、跟踪器回读、时间戳、哈希、权限和附加行为，因为模式验证本身不能证明可复现性。
在交接时报告已实现组件、执行的检查、已验证字段、未解决缺口及准确制品路径。

配置指南

阅读 references/metadata-contract.md 中的元数据契约，并决定哪些字段可安全地跨项目和跟踪器边界公开。
统一运行命名、元数据所有权、隐私规则，以及人类可读名称与唯一执行 ID 的区别。
仅在请求集成的地方实现项目本地分类器和日志适配器；保持分类纯粹且附加幂等。
创建元数据 JSON 记录，并使用已安装的技能路径在本地验证其结构：
python3 /scripts/validate_metadata.py
当核心溯源字段必须为非 null 时使用严格验证：
python3 /scripts/validate_metadata.py --strict
添加表驱动分类器测试，预览获授权的运行名称，测试未知名称诊断，并在更大活动前运行获授权的短训练任务。
在初始化和恢复时回读本地及远程字段，以确认提供商特定行为；不要假设初始化元数据会在恢复时自动重新应用。
调用此 Openclaw Skills 工作流不意味着安装软件包、付费运行、提供商上传、跟踪器写入、删除或全局迁移。

数据架构

记录围绕五组元数据组织：
组 代表字段 用途
身份 run_id、created_at、phase、variant、modality、seed 标识执行及其活动上下文。
意图 dataset、reason、notes 说明运行目的，并关联提案、配置、先前结果和父活动。
代码 repo_url、branch、commit、dirty、commit_url、code_snapshot 记录源代码身份及是否存在未提交工作。
执行输入 config、data、预处理和分词器详情 捕获已解析配置、数据身份和转换输入。
证据 metadata_origin、recorded_at、missing、tags 区分创建元数据与回填，并记录不确定性及分类标签。
其他组织规则：
使用稳定且唯一的 run_id；仅凭阶段、变体和种子命名无法区分重试。
未知事实表示为 null 并列入 missing；绝不编造历史值。
哈希应标识不可变制品并说明算法，而不只是记录文件名。
恢复谱系保留原始创建事实，并添加尝试级别的代码、配置和检查点身份。
回填字段必须说明其为重建字段，并引用证据来源。
将私有仓库 URL、内部路径、数据集样本、机密和已解析的机密配置置于适当披露边界之后；必要时使用本地标识符或 null。
生成或维护的项目制品可包括 run_context.py、分类器测试、元数据 JSON 记录、验证输出、回填差异预览以及进度或交接报告。
本地验证仅确认结构和一致性；不能证明跟踪器附加、制品可访问性、时间戳准确性、权限，或记录的提交确实生成了结果。

高级特性

纯粹、表驱动的运行名称分类，并为未知模式提供明确诊断。
幂等元数据附加：合并自有字段和标签而不覆盖无关备注。
可感知恢复的谱系，将原始运行创建元数据与后续执行尝试分开。
以预览为先的回填工作流，包含准确运行 ID、获授权字段、重建标签和来源跟踪。
对必需溯源字段进行严格本地验证，并对结构和一致性进行普通验证。
使用本地标识符、null 值、编辑和制品哈希，在披露边界内实现隐私感知溯源。
进度可观测性分别记录阶段、当前及总工作量、速率、ETA、耗时、最近成功操作、输出、检查点、失败和完成状态。
证据感知的交接报告，清楚区分协议、分类器、适配器、回填工具、已执行检查和未解决缺口。
兼容 Openclaw Skills 的规范机器学习元数据工作流，无需私有仓库、训练器集成或可观测性技术栈。

name: ml-run-provenance description: Design or audit self-describing ML run metadata attached at initialization, including intent, code and data identity, resume lineage, and evidence limits. Use when wiring a tracker, introducing a run naming pattern, or investigating why a run exists.

ML run provenance

Treat provenance as a trainer output alongside checkpoints and metrics. A cryptic run directory or dashboard title does not preserve campaign intent. Capture context at run birth and distinguish recorded facts from reconstructed metadata.

This package provides a protocol and a local JSON validator, not a trainer integration, tracker adapter, classifier, backfill service, or guarantee of reproducibility. Those project-specific pieces must be implemented and tested where needed. No other private repository or skill is required.