Skill Publish Verify

发布前黑盒验证

任意有 SKILL.md 的 skill 发布前,用一条命令跑完新用户视角的隔离验证,产出 可用性报告。是否 esflow 化不限——envelope 契约是 esflow skill 的加成,缺失时 verify_facts.envelope=null,agent_report 照常写。

依赖

pip install esflow

用例格式

{
  "skill_path": "<待验 skill 根目录>",
  "demand": "生成北京南→天津西 2026 抢票日历 HTML"
}

只写"验什么 skill + 要完成什么需求"。不含 command、不含 expect——命令由 agent 读 SKILL.md 自行构造,产物是否符合预期由 agent_report 综合判断 + 用户复核。 这是真黑盒,才能测出"新用户能否看懂 SKILL.md"。

Flow 结构

isolate_env → copy_skill → install_deps → preflight_target → agent_run → verify_artifact → agent_report
                                                    (TO_AGENT)                  (TO_AGENT)

Agent 介入(两次 --resume)

# 1. 首跑到 agent_run 退出(exit 2)
python3 scripts/run.py case.json

# 2. Agent 读 _agent_run_brief.json + skill_dir/SKILL.md,自行跑 skill,
#    把 artifacts(必填)+ steps/envelope(可选)写入 run_record.json

# 3. 续跑到 agent_report 退出(exit 2)
python3 scripts/run.py --resume <job_dir>

# 4. Agent 读 _agent_report_brief.json + verify_facts.json + run_record,
#    写 skill_verify_report.md(含:可用性评分/卡壳点/文档问题/产物结论/改进建议)

# 5. 续跑收尾,输出 envelope,极简清理 work_dir
python3 scripts/run.py --resume <job_dir>

agent_run brief 字段

work_dir/_agent_run_brief.json:

run_record.json 必填:artifacts(绝对路径列表,全部落在 artifacts_must_under 下, 框架核实路径合法性 + 存在性)。可选:steps(数组,每步含 command/exit_code/ stdout/stderr,agent 自报过程,框架不核实)、envelope(skill 最终 envelope)。 单步 skill 可只填 artifacts;多步 skill(如自带 TO_AGENT 的 esflow skill)用 steps 逐步记录。agent 应主动用 --out work_dir/out 之类参数把产物输出到 work_dir 内。

agent_report brief 字段

work_dir/_agent_report_brief.json:skill_md_path / run_record_path / verify_facts_path / verify_summary / report_file / report_required_sections / resume_cmd。

skill_verify_report.md 必含章节:可用性评分、卡壳点、文档问题、产物结论、 改进建议。deliver 逐项检查章节标题,缺失判失败。

verify_facts.json

全量事实外置,字段:run_record(steps/envelope,steps 为 agent 自报过程)、 envelope_ok、artifacts([{path, exists, size, text_head}])、work_dir_tree。 节点 artifact 与最终 envelope 只带摘要(exit_code/envelope_ok/artifact_count, exit_code 取 steps 末步,无 steps 则 null),避免多 job 时终端被单次 stdout/stderr 撑爆。

参数

退出码:0 ok / 1 runtime / 2 to_agent / 3 validation

输出契约

成功时 stdout 一行 JSON envelope(清理后构造,只带仍存在的路径):

{
  "ok": true,
  "data": {
    "work_dir": "<job 目录>",
    "report_path": "<work_dir>/skill_verify_report.md",
    "artifacts": ["<work_dir>/out/xxx.html"],
    "verify": {"exit_code": 0, "envelope_ok": true, "artifact_count": 1}
  },
  "error": null,
  "meta": {"schema_version": "1.1.0", "tool": "skill-publish-verify", "elapsed_ms": 0}
}

artifacts 是清理后仍存在的产物绝对路径。verify 是摘要(全量事实已随 verify_facts.json 删除,如需保留用 --keep)。失败时 ok=false, error 含 {code, message, retryable},data 为 null。

隔离与生命周期

工作目录 /tmp/skill-publish-verify/<job_id>,venv 不复用(每次全新装依赖, 才能暴露 SKILL.md 依赖说明是否完整)。

清理后无法再 --resume 该 job,end/error 后验证已结束,复跑用新 job_id。

多场景约定

一 case 一 job,编排层循环,禁止一个 work_dir 跑多轮 demand:

for f in verify.cases/*.json; do
  python3 scripts/run.py "$f"   # 每次新 job_id、新 work_dir、新 venv
  # Agent 对该 job 完成两次 resume 后再跑下一个 f
done

仓库约定

待验 skill 在自己仓库下放 verify.cases/,每个 JSON 一个 case。Agent SOP 固定 四步:首跑 → 手跑 skill 写 run_record → resume 写报告 → resume 收尾;禁止 resume 别的 job 目录。

通用性边界

验任何有 SKILL.md 的 skill。有 scripts/run.py + --schema(esflow skill) 则 preflight 把 schema 摘要喂给 brief、verify 解析 envelope;否则 envelope=null 是合法事实,agent 按 SKILL.md 手工执行。不引入分支判断——null 本身就是事实。

被验 skill 若自带 TO_AGENT 节点(如 esflow skill 的 agent_review),agent 须在 agent_run 阶段内完整跑通其全部 resume 步骤(首跑到该 skill 的 TO_AGENT 退出 → 写该 skill 要求的产物 → resume 续跑),把最终结果记入 run_record。即两层 TO_AGENT 嵌套时,内层由 agent 自行消化,对 publish-verify 只暴露一次外层 resume。

Agent 使用指引

用户提到「发布前验证」「skill 黑盒验证」「发布前自检」时使用:确认待验 skill 路径 + demand → 写 case.json → 按"Agent 介入"章节两次 --resume 节奏介入 → 把 skill_verify_report.md 呈现给用户。