用于科学数字资产交付前的自查。资产包提交前,使用本 skill 完成一次完整核验,确认资产可用、清单合规、结果与期望值一致,并在交付环节之前修正不符合项。
资产提交后,接收方将依据对外发版口径逐项核验。清单字段不完整、用例覆盖不足、结果与期望值不一致,均会导致交付被退回,并额外产生一轮沟通与整改。
本 skill 将上述核验要求前置到提供方一侧:采用与接收方一致的内置标准与判定规则,执行完整核验流程,产出可直接随包提交的资产清单与验证报告,减少交付环节的返工。
本 skill 是一个目录,装到 agent 能读到的 skills 位置即可。推荐用 git 安装(这样才能用上"开跑自动对齐最新版")。
# DSH:装到用户级 skills 目录(也可放项目的 .dsh/skills/ 下,仅该项目生效)
mkdir -p ~/.dsh/skills
git clone --depth 1 https://github.com/KnowledgeXLab/sci-asset-verify-skill.git \
~/.dsh/skills/sci-asset-verify-skill
# 想钉在某个版本上:加 --branch
git clone --depth 1 --branch 1.2-beta.5 https://github.com/KnowledgeXLab/sci-asset-verify-skill.git \
~/.dsh/skills/sci-asset-verify-skill其他 agent(Claude Code / Codex / Cursor 等):把同一仓库 clone 到它的 skills 目录即可,技能说明在 SKILL.md。
cd ~/.dsh/skills/sci-asset-verify-skill
cat VERSION # 当前版本,如 1.2-beta.5
python3 tests/selftest.py # 自测:应显示「自测结果:N/N 通过」
python3 scripts/update_skill.py --check # 与远端最新 tag 比对
python3 scripts/validate_envelope.py --help # 任一脚本能跑即说明依赖就绪装好之后不必再人工 pull:每次核验开始时 scripts/update_skill.py 会检查远端最新 tag,
有新版就切过去(工作区有未提交改动时拒绝更新,不覆盖本地修改);也可以手动:
python3 scripts/update_skill.py --apply # 切到远端最新 tag,并自动跑一次自测
python3 scripts/update_skill.py --apply --no-update # 本次不更新直接拷贝整个目录到 skills 位置也能用(依赖已随 vendor/ 打包,无网络也能跑),
但自动更新不可用——update_skill.py 会提示"非 git 安装,请重新下发最新版"。
自动更新要写 skill 目录(工作区 + .git),所以装在哪里取决于 agent 的写权限:
| 安装位置 | 自动更新 | 说明 |
|---|---|---|
项目级 <项目>/.dsh/skills/sci-asset-verify-skill |
✅ 可用 | 在会话工作区内,workspace-write 沙箱即可写 |
用户级 ~/.dsh/skills/sci-asset-verify-skill |
会话若只允许写工作区(workspace-write),git checkout 会被拒;此时脚本报 无写权限,跳过自动更新(不中断核验),需放宽权限或手动 pull |
脚本的行为:更新前先探测目录可写性,不可写就降级为提示(退出码 0,核验继续),并给出三条路——
放宽会话写权限、手动 git pull、或重新下发最新版。要强制关闭自动更新:--no-update 或 ASSET_VERIFY_NO_UPDATE=1。
| 项 | 要求 |
|---|---|
| Python | ≥ 3.10(仅标准库 + 随包 vendor/) |
| git | 仅"安装/自动更新"需要;离线拷贝安装可不要 |
| 网络 | 自动更新、--check 需要能访问 GitHub;核验本身不需要联网 |
| 第三方依赖 | 无(vendor/openpyxl、vendor/jsonschema 已内嵌) |
装好之后(见上节「安装」)无需额外配置,直接让 agent 使用本 skill 即可;也可把 SKILL.md 路径提供给 agent,由其按其中步骤执行。
执行前需明确核验对象与核验范围,例如:
用 sci-asset-verify-skill 自查 /data/delivery/some-package-2.1.0/ 这个包,
全量跑一遍,清单按对外发版口径填,交付前我想知道还有哪些项没过。
可根据进度调整范围:
- 材料尚未齐备,仅需确认缺口:「只做盘点和填表,先别跑用例」
- 服务已部署,仅需补跑用例:「跳过部署,直接用 http://xxx 那个服务」
- 上次执行中断:「接着
asset-runs/run-20261114-105545那次继续」
资产涉及大模型调用且需进行 Sage A1.5 兼容性验证时,应提供 SAGE_BASE_URL、SAGE_MODEL、SAGE_API_KEY。未提供时,agent 将暂停并向用户索取,不会跳过该环节。
核验完成后,资产目录下生成 asset-runs/run-[YYYYMMDD]-[hhmmss]/(批次目录名固定为「日期-时分秒」,便于按时间追溯)。其中以下三项为主要交付物:
validation-report.md:核验结论,含通过项、未通过项及原因registration/科学数字资产清单.xlsx:可直接随包提交的资产清单comparison.json:逐条用例的期望值与实际值
其余文件为过程记录,供接收方复核时查阅。
核验按六个阶段执行,每个阶段对应一类不符合项。
阶段一为资产盘点与使用说明。核查版本、入口、依赖、输入输出是否完整可追溯,常见问题包括目录名与版本号不一致、入口脚本缺失、依赖未声明。
阶段二为资产登记。按对外清单 23 列填写,表头、枚举、必填项、版本格式、一资产一行、用例引用可解析性均由脚本校验。使用内部字段口径、枚举值不在词表内、两行名称与版本重复等情况将直接报错。
阶段三为部署核验。存在 MCP 时完成注册并执行一次最小业务调用;存在模型时完成加载并执行一次推理。仅提供配置文件而服务不可用的情况不予通过。
阶段四为用例执行。使用资产包给定的用例逐条执行,记录输入、实际输出、退出码与耗时。用例缺失、期望值缺失、预期失败用例未按约定报错,均予以记录。
阶段五为比对与报告。逐项比对期望值,并按各类资产的用例数量下限核对覆盖度。通过率未注明分母、覆盖度不足却宣称完成的,将在报告中明确指出。
阶段六为 Sage A1.5 附加测试,仅针对涉及大模型调用的资产。切换后端执行后单独成节,不影响交付结论。
核验结束后自动清理中间产物,仅保留报告类证据,随包提交的目录不会因执行核验而增大。
用例状态分为四种:通过、失败、未判定、不适用。
未判定指缺少期望值或判定阈值,仅给出差值而不给出结论。不适用分两种情形:资产包内本不存在该类资产,属合规跳过;或本 skill 无对应验收步骤,属能力缺口,报告中标注「未覆盖」,交付前应与接收方确认处理方式。
判定遵循以下规则:
- 每个资产在清单中仅占一行,用例不额外占用资产行
- 通过率注明分母,例如「27/27」;未执行项单独列出,不计入分母
- 某类资产用例数低于下限时,报告标注「覆盖不足」
- 资产包内缺失的描述文件不由本 skill 补写
- Sage 附加测试结果仅说明后端切换后的可用性,不计入交付结论
资产清单生成依赖 openpyxl,已随本 skill 置于 vendor/ 目录,纯 Python 实现,MIT 许可,无需另行安装。运行时按以下顺序解析:当前环境已安装的版本、vendor/ 内置版本、自动安装;三者均不可用时终止并输出修复命令。可在离线环境与干净容器中直接执行。如需固定依赖行为,可设置 ACI_ASSET_VERIFY_AUTO_INSTALL=0。
%%{init: {"theme": "base", "themeVariables": {"fontSize": "14px", "primaryColor": "#e8f1ff", "primaryBorderColor": "#3569a8", "lineColor": "#52606d", "secondaryColor": "#eef8f1", "tertiaryColor": "#fff5df"}}}%%
flowchart LR
A[资产包]
B[盘点]
C{版本与入口<br/>可追溯?}
D[登记<br/>对外清单与自检]
E[部署<br/>MCP / 服务 / 模型探针]
F[用例执行<br/>副本内完成]
G[比对与报告<br/>覆盖度门禁]
H[Sage A1.5 附加测试]
I[清理中间产物]
X[中止并说明<br/>阻塞位置与缺失项]
A --> B --> C
C -- 是 --> D --> E --> F --> G --> H --> I
C -- 否 --> X
X -. 补齐后继续 .-> B
classDef gate fill:#fff5df,stroke:#c58a18,stroke-width:2px,color:#513b00;
classDef step fill:#eef8f1,stroke:#3f8f5b,stroke-width:1.5px;
class C gate;
class B,D,E,F,G,H,I step;
各阶段均产出机器可读回执。执行中断时保留现场并记录原因,不清理既有结果。
本 skill 已在下列环境完成完整流程测试,各项检查全部通过。
| 项目 | 环境 |
|---|---|
| 操作系统 | Linux x86_64,24 核 CPU,无 GPU |
| 运行时 | Python 3.12 |
| agent | DeepSeek Harness(DSH),Web 会话 |
| 驱动模型 | DeepSeek-V4.1-Flash-1017(DS-4.1) |
测试内容如下。
一、脚本自测。tests/selftest.py 覆盖全部二十个脚本,共 156 项断言,含正例与负例,全部通过。该套件不依赖真实资产包、不需要网络,执行时间约 3 秒。断言校验至具体报错字段与提示文案,不以退出码作为唯一依据。
python tests/selftest.py
二、完整流程验证。在数据、工具、工作流三类交付包上执行完整六阶段流程,159 条用例与判据全部完成判定,无遗留项;覆盖度门禁各类型均达标;数据侧逐文件核验 327 个实体、534,694 行记录,与声明不符 0 处。
三、附加测试路径验证。涉及大模型调用的资产已完成 Sage A1.5 附加测试,15 组用例通过 8 组。失败集中在问答与报告正文生成环节,原因在于被核验资产所依赖的后端服务,按既定规则不计入交付结论。
SKILL.md 六阶段流程的完整作业手册,agent 按此执行
references/ 登记字段口径与示例、比较规则与报告格式、资产发现方法
scripts/ 二十个自检脚本(另有 4 个内部模块)
assets/ 内置标准:23 列清单 schema、包络 JSON Schema、用例数量下限
tests/selftest.py 脚本自测套件
vendor/ 随包分发的 openpyxl
Harbor 任务包支持(合并 PR #1):识别 task / 显式 dataset / 隐式 dataset 三种形态;静态检查入固定清单 (
P0-HARB-STRUCT必需文件、P0-HARB-RUNoracle/nop 双 trial、P1-HARB-DATASET/P1-HARB-ENVELOPE/P1-HARB-LINT); 执行走官方 CLI 全量 oracle+nop(scripts/harbor_run.py),跑不了记 blocked(不算 na 不算 fail);task@harbor 不触发 Sage。
Sage 配置未就绪不再「只记未测」,改为阻断
-
新增检查项
P0-SAGE(清单现为 P0×6 + P1×5 = 11 条):需要 Sage 附加测试的资产 (包内含 skill/agent 类资产即需要)若因环境变量/连通性等配置原因没跑通,且用户给不出可用配置 → 判 P0, 须先完成配置(API URL 与 API KEY 可在端砚平台(书生·Intern-Discovery)获取)才能交付,不得以「未测」结案 -
probe_package.py新增--run-dir:读sage-need.json/sage-config.json/sage-a1.5-report.json, 区分config_missing(没配)/config_invalid(配了但连不上、401/403)/not_run(根本没用 Sage 跑) -
索取配置的文案写清:只要在环境变量里设置
SAGE_BASE_URL/SAGE_MODEL/SAGE_API_KEY, 不要把明文密钥贴进对话、写进文件或带进交付包 -
SKILL.md第 5 步固定带--run-dir跑判定;check_report.py加守卫——需要 Sage 却没带--run-dir(缺sage_profile)或未跑通却没有P0-SAGE,报告结构检查直接告警 -
自测 128 → 132 项断言
安全修复:核验过程不再把凭据落盘
隔离 DSH_HOME 原先会把 ~/.dsh/.credentials.yaml 复制进 run 目录,asset-runs/ 随包外发即等于交付物含明文密钥。
-
隔离
DSH_HOME只复制 profiles 与 node_modules 软链;凭据在内存中解析*_API_KEY(AGENT_CENTER_API_KEY/DEEPSEEK_API_KEY/INKSTONE_API_KEY…)后经环境变量注入子进程 -
新增
scrub_secrets():每次运行结束(含异常分支)清理.credentials.yaml、.dsh-home-*、codex-home/claude-home及其auth.json -
新增检查项
P0-SECRET(10 条清单里的第 5 条 P0):包内出现凭据文件(.credentials.yaml、auth.json、 带密钥的.env)或明文密钥(sk-…、Bearer …、*_API_KEY=<值>)即阻断交付; 扫描跳过asset-runs/、.asset-work/、node_modules/、vendor/、.tmp/,避免插件示例文档误报 -
自测 125 → 128 项断言
四类误判修正(都来自真实包复核)
-
容器内绝对路径不再判越界:资产自身声明容器(
environment_type=docker、image、base_image、自带Dockerfile/compose.yaml)或同包存在声明了容器的environment资产时,/opt/…、/data/…记为 note;/home/…、/Users/…、/root/…等宿主机路径仍判越界。结果里带container_context说明豁免依据 -
文档路径 token 不再被截断:
image/x.tar.sha256曾被截成…tar.sh、a.shp曾被截成a.sh而误报缺失; 扩展名改为必须落在文件名边界上。仅大小写不同的同名文件单独记case_only_mismatch,不算缺失 -
sage_probe.py detect支持catalog.json的路径数组:assets: ["x/asset.json", …]时不再AttributeError,逐条解析出资产类型 -
覆盖表 na 规则字段名修正:
P1-VERIFY-DOC曾因读旧字段名而永远判 na(理由与事实相反), 现在按实际cases_json判定;validate/cases.json缺失时兜底取资产内任一cases.json -
自测 120 → 125 项断言
开跑自动对齐版本
- 新增
scripts/update_skill.py:核验第一步检查远端最新 tag,有新版就git checkout过去, 更新后自动跑一次自测;版本比较按语义序(,alpha/beta/rc/正式,-dev后缀按同号处理) - 不阻断核验:非 git 安装、离线无 origin、工作区有未提交改动、目录不可写(如用户级安装但会话只能写工作区)
→ 一律打印状态并继续,
skill-update.json记录原因;--no-update/ASSET_VERIFY_NO_UPDATE=1可关闭 - 报告 front matter 的
skill_version/skill_commit自然反映更新后的版本;同一批核验内不中途切换
README 新增「安装」章节(在「使用方法」之前):git 安装(可 --branch 钉版本)、验证安装、
更新方式、离线拷贝安装的限制,以及「装在哪里:权限与自动更新的取舍」(项目级可自动更新 / 用户级视会话权限)
- 自测 114 → 120 项断言
判定口径固定,结论可复现
- P0×6 / P1×5 写死:P0 = 包结构、包络合规、资产完整性(含引用包外/绝对路径)、可执行验证入口与结论、不得含凭据/密钥(
P0-SECRET)、Sage 附加测试未跑通(P0-SAGE); P1 = 文档引用不存在、版本口径不一致、声明与实体/实现不符、文档事实或算术错误、验证说明与用例不一致 scripts/probe_package.py出确定性事实(同包多次运行指纹相同)+--evaluate按清单判级; 报告须附pass/fail/na覆盖表,na必须写理由- 问题清单每行必须写明归属(资产目录名或「包级」),P0/P1 只能引用检查项 id,P2 为自由建议
不校验(明确排除):governance 发布口径取值、包根一级文件(其问题一律丢弃,不降 P2)、spec.asset_protocol
字段内容、lifecycle 取值(draft 属正常交付状态)、挂载副本、asset-runs/
其它:包根出现 asset.json 判 P0-STRUCT(资产必须作为子目录存在);文档引用检查只看脚本/文档类 token
并豁免产物目录;check_report.py 新增归属、包根文件、lifecycle、检查项引用四项守卫
- 外部资产挂载重做:先在同包内按
asset_id解析,包外才按优先级查找并复制进副本,最后按target_path建软链(父目录自动创建);挂载进来的副本不计入本包校验,挂载缺失只报告不中断 - skill 验收改造:
validate/readme.md写清 Agent(harness + model)、怎么测(任务/输入/输出)、通过门槛;验收用run_skill_agent.py起独立 CLI 进程跑,内置 dsh/codex/claude/cursor/gemini/opencode/aider 预设,声明之外的 harness 就地固化;Sage 测试沿用同一 harness 只换后端(SAGE_*),门槛判 agent 产物 - 降噪与口径:
asset_protocol不校验内容;target_path本地缺失不告警;文档里的产物文件名不误判为路径;清单词表缺口(如「敏感级别」无「公开」档)不算缺陷;不参考包内已有核验结果、不做跨批次对比 - 自测 80 → 104 项断言
external_assets.json从包根改为每个资产目录一份;「资产关联」列只填本资产声明的asset_id(去前缀、逗号分隔、无则留空)- 批次目录统一
asset-runs/run-[YYYYMMDD]-[hhmmss]/(new_run.py生成,work_copy.py校验) - 报告的版本与生成时间改为文件头 YAML front matter,正文不再出现
- 自测 69 → 80 项断言
校验口径收紧、报告可追溯、依赖自包含。核心变化是把"资产能不能独立入库"变成可校验项。
新增校验能力
- 资产自包含校验:新增
scripts/check_selfcontained.py——任何资产只能引用自己目录内的文件;唯一允许的外部引用方式是本资产目录下的external_assets.json按资产编号声明。越界区分「指向包内另一个资产」「指向包内共享位置」「指向包外本机路径」并给整改方向;文档里的路径只算提示。包络校验同步收紧:spec.artifacts[].uri与spec.asset_protocol的本地路径越出资产目录即 error - 实体核对:
validate_envelope.py逐条核对spec.artifacts的实体是否存在、size_bytes(兼容bytes/size别名)与sha256(≤64MB 实测,大文件只提示)是否一致 - 修复
task_classes漏检:字段整体缺失时不再被跳过(skill/task/trajectory/benchmark 至少一个任务概念) - schema 交叉校验不再可能静默跳过:环境无
jsonschema时回退内置轻量实现,并如实标注所用引擎 sage_probe.py detect改为递归读取子目录asset.json,资产类型只作提示、是否需 Sage 测试只由大模型 API 证据决定;新增--assume-llm人工强制
报告
- 问题清单固定三级:P0 阻断 / P1 重要 / P2 建议,每条带编号与证据;某级为空写「无」,三级全空写「未发现问题」;新增
scripts/check_report.py自查 - 校验 skill 版本可追溯:
VERSION文件为版本唯一来源,所有证据 JSON 带skill: {name, version, commit},报告末尾由scripts/stamp_report.py写入「校验工具版本」小节 asset_id类问题的整改要求必须照抄完整格式规范(sciasset://{project-id}/{namespace}/{asset-type}/{slug},及 project-id/namespace/asset-type/slug 各自的含义)- 写 md 时表格单元格内的竖线须转义成
\|(反引号内同样)
依赖与产物约定
jsonschema4.26.0 连同依赖一并 vendor,包络交叉校验不再依赖环境- 按专项约定:不核验、也不生成包根
SHA256SUMS;完整性以文件数/字节数 +asset.json声明的实体摘要为准 - 修复
prune_evidence.py在actual_output为列表时的崩溃(此前会删了中间产物却没有清理记录) SKILL.md增加「历史批次只增不改」:每批新建asset-runs/<run_id>/,任何已有批次不得删除或覆盖
验证
- 自测 40 → 69 项断言,覆盖四个真实包的核验(地球科学数据/工具/工作流、生物育种 sample_skills)
清单精简与外部资产引用支持。
- 对外清单由 25 列精简为 23 列,移除「联系人」「项目负责人」两列,对接人与责任归属改由项目台账维护;「资产关联」仍为末列
- 新增可选文件
external_assets.json(当时定义在包根目录;1.2-beta.3起改为每个资产目录各一份),用于声明包内未随附、需平台按资产编号解析的外部资产 - 新增
scripts/external_refs.py:校验该文件的 schema_version、asset_id 四段格式、asset_version、target_path(相对 POSIX 路径、不得越出包根)、重复引用;通过后自动把引用明细写入清单「资产关联」列;文件不存在时合规跳过 - 新增内置标准
assets/external-assets.schema.json(schema_version + assets[],不含 task_id) check_list增加「资产关联」列内资产编号的格式校验- 自测套件扩到 40 项断言(新增外部引用正例与四类负例)
跟进规范 v1.1:明确资产编号规范,清单增加「资产ID」列。
- 包络
asset_id校验改为四段格式sciasset://{project-id}/{namespace}/{asset-type}/{slug},三段旧格式直接报错并提示补 project-id - 新增
scripts/asset_ids.py:从包络生成清单「资产ID」(asset_id去掉sciasset://前缀,不含版本号),支持--inject写回 rows.json、--check校验 - 清单 schema 由 24 列扩为 25 列,资产ID 列为首列且必填;
check_list校验其格式、不得含版本号、类型段与「资产类型」列一致 - 行标识改为「资产ID + 版本」
- 修复
check_coverage只认三段 asset_id、导致四段格式无法归类的问题 - 自测套件扩到 34 项断言(新增四段格式、带版本号、清单资产ID 拼接与写回等)
首个可用版本,由纯文档作业手册升级为可执行的核验工具链。
- 内置三份标准:对外清单 23 列 schema、资产包络 JSON Schema、各类资产用例数量下限
- 七个脚本:包络校验、清单生成与复检、覆盖度门禁、副本管理与完整性自检、证据清理、Sage 探测
- 自测套件 27 项断言,不依赖真实资产包
- 新增第六阶段 Sage A1.5 附加测试,结果不计入交付结论;配置缺失时中止并索取,不作跳过
- openpyxl 随包分发,缺失时自动安装作为兜底
- 判定口径:一资产一行、通过率注明分母、覆盖不足明确标注、不适用情形分类记录
- 完成三类交付包的完整流程验证
版本号说明:1.0-beta.1 合并了开发期的两轮改动(可执行化、依赖自包含),对外仅发布此版本。
初版,仅含文档:五阶段流程(盘点、登记、部署、用例执行、报告),references/ 四篇(28 字段登记规则、逐列示例、比较规则、资产发现),无脚本与内置标准,判定依赖人工执行。
Knowledge Frontier Team,上海人工智能实验室。仓库:KnowledgeXLab/sci-asset-verify-skill。
脚本变更后应先执行 python tests/selftest.py,80 项断言全部通过方可提交。版本号遵循:口径发生破坏性变更时递增次版本号,仅文档或脚本修补时递增修订号;发布时同步更新 tag 与本文档的版本记录。