Skip to content

ves-cli.md

Latest commit

 

History

History
103 lines (81 loc) · 5.21 KB

ves-cli.md

File metadata and controls

103 lines (81 loc) · 5.21 KB
Raw

VES v0.1 快速上手

VES（Verifier-first Executable Search）v0.1 的公共 facade 与 CLI。

安装/入口

  • 公共 API facade：ves/__init__.py（__all__ 四层 33 个导出名： Verification / Judgment / Records / Search；ves.compat 为内部兼容层，不属公共 facade）
  • CLI 入口：[project.scripts] ves = "ves.cli:main"（pip install -e . 后获得 ves 命令；未安装时可用 python -m ves.cli）

核心概念（30 秒）

  1. 不可信候选产出 RawArtifact；宿主用 ArtifactContract（文件名/格式/大小/必需字段/数值规则）独立校验。
  2. EvidenceVerifier.verify(raw_artifact, context) 在宿主 VerificationContext 内产出 Evidence（仅事实，无 gate/judgment）。
  3. Judge 依据 JudgeSpec（gates + 偏好方向）产出 Verdict / Comparison。
  4. VerificationRecord 记录 verifier_version / context_id / fingerprint / evidence，不泄漏 hidden truth。
  5. 与 legacy 判分的兼容链（ves.compat）仅作仓库内部迁移用，不属 v0.1 公共 API。

对抗 Demo（无 LLM、无网络）

python examples/demo_adversarial.py        # 或 python -m examples.demo_adversarial

输出六段判定：自报 objective=999999 → IGNORE；非法 JSON → REJECT； 恶意 artifact（NaN/Infinity/非数值/重复索引/超大 size）→ REJECT； symlink artifact → BLOCKED（O_NOFOLLOW）；hidden-truth 访问 → BLOCKED BY SANDBOX； 合法 selected → VERIFIED（宿主复算 weight/value + 容量 gate）。

ves verify（内置三例）

ves verify <artifact-file> --example knapsack
ves verify <artifact-file> --example regression_hidden --out record.json
ves verify <artifact-file> --example mechanism_fitting
ves verify <artifact-file> --problem examples.knapsack:problem   # 自定义 VerifiedProblem
  • 内置三例（--example）与自定义问题（--problem module:attr，如 examples.knapsack:problem）都通过 VerifiedProblem （contract / context_factory / verifier / judge_spec 四要素）与 VerificationPipeline 接入；--example 与 --problem 互斥。
  • 输出区分验证与判定（VES-R1）：verification: verified / invalid_artifact / verification_failed + feasibility: feasible / infeasible + verdict: VERIFIED / REJECT + Evidence 观察；reject reason 直接来自 VerificationResult.issues（CLI 绝不重复调用 verifier）。
  • 退出码：VERIFIED 且 feasible=0；其余（infeasible / 参数错误 / 缺文件）= 2。
  • --out <path> 写入 VerificationRecord JSON（verified 即写，含 verified-but-infeasible 的 repair 用 record）。

示例：

echo '{"selected": [0, 1]}' > solution.json
ves verify solution.json --example knapsack --out record.json
# verdict: VERIFIED
#   observation weight: value=5.0 provenance=deterministic:host-recompute
#   ...

ves replay

ves replay record.json
ves replay record.json --artifact solution.json   # 指定重验 artifact

replay 是真实闭环（Phase 6）：resolve 宿主 Context（context_factory） → 用 record 的 context_fingerprint 比对（不一致 → MISMATCH exit 2） → 重新加载 artifact（设计决策：artifact 重读，record 不保存候选内容， 默认路径为 <record 目录>/<artifact_source>，可用 --artifact 覆盖） → 重跑 verifier → 新 Evidence 与 record 内 Evidence 比较 → REPRODUCIBLE（一致，exit 0）或 MISMATCH（不一致，exit 2，打印差异）。

replay schema v1（VES-R4）：按 problem_ref resolve VerifiedProblem， 逐项比对 contract_fingerprint / context_fingerprint / verifier_version / judge_spec_fingerprint（任一不符 → MISMATCH 并指明 字段），artifact 重读后校验 artifact_sha256，再 verify → judge → Evidence 比对 → REPRODUCIBLE / MISMATCH。旧 record（无 schema_version/problem_ref）仅打印 inspect 提示并 exit 2。

VerificationRecord schema v1 新增字段（全部带默认值，向后兼容）： schema_version、problem_ref、candidate_id、candidate_sha256、 artifact_sha256、contract_fingerprint、judge_spec_fingerprint； 既有 verifier_module/verifier_attr/context_factory 四件套并行保留 （problem_ref 优先用于 replay，四件套作 fallback 审计元数据）。

Judge 语义（VES-P7，提炼自 legacy judging）

  • Comparison.outcome 四态枚举：BETTER / WORSE / TIE / INCOMPARABLE （winner 字符串保留兼容）。
  • JudgeSpec：per-observation 方向（directions，缺省 prefer_lower）、 容差（tolerances）、feasibility-first（不可行永远劣于可行；两个不可行按 gate 超量排序）、rule 支持 lexicographic（默认，按 priority）与 Pareto。
  • 与 aide_solver/judging 对应：feasibility-first ≈ _compare_gates； scalar 比较 ≈ _compare_scalar；lexicographic/Pareto ≈ compare_point_estimates。

安全读取

ves verify / ves replay 通过 SafeArtifactLoader（ves/artifact.py）读取： O_NOFOLLOW 防符号链接、打开后 fstat 确认 regular file（拒绝目录冒充）、 只允许 basename（拒绝路径逃逸）、默认 5MB 大小上限、fd 打开后读取（竞态安全）。