omk 术语规范

范围: 这是 omk 维护者的内部设计决策归档(为什么 artifact 不叫 evaluand、为什么 v0.16 起废 --variants、qualityScore → judgeScore 迁移路径等)。不是新用户入门文档——日常用法看 README 即可。中英双版并存(docs/specs/ 英文 / docs/zh/specs/ 中文),术语本身全是英文，源码为命名的事实来源。

一、目标

这份规范用于统一 omk 后续迭代中的对外文案、命令示例、数据结构与代码命名。

目标有三条：

对齐行业与开源社区常见说法，尽量减少 omk 私有术语
把"被评测对象"、"运行环境"、"实验分组"与"实验角色"四层拆开，避免混用
为未来扩展到 skill、agent、workflow、agent team 等载体保留统一抽象

二、标准术语

1. Artifact

artifact 是 omk 对"被评测对象"的统一标准术语。

它表示在实验中被拿来比较、注入、运行或观测的对象，可以是：

baseline
skill
prompt
agent
workflow
未来的 team 或其他新型知识载体

规则：

对外文档优先使用 artifact
对内核心类型、请求结构、任务结构优先使用 artifact

2. Artifact Kind

artifact kind 是 artifact 的具体类别。

当前支持：

baseline
skill
prompt
agent
workflow

规则：

baseline 表示空 artifact，也就是不注入任何显式 artifact；对大多数使用者来说，可以直接理解为"什么都没有"
skill、agent、workflow 是 artifact 的子类，不是顶层总称
新增载体时，优先扩展 artifact kind，不要另起一套平行抽象

3. Variant

variant 是一次实验中的一条对比臂的表达式，不是领域对象本身。

例如：

baseline
prd
/path/to/SKILL.md（runtime context 的 cwd 单独声明，不编码进表达式）

规则：

variant 表达式解析后得到 artifact 与 runtime context
每个 variant 都必须绑定一个 experiment role（control 或 treatment），见第 4 节
CLI 层按 experiment role 声明 variant（--control / --treatment），不再使用扁平的 --variants 参数

4. Experiment Role

experiment role 是 variant 在当次实验中扮演的角色，采用统计学标准术语。

枚举：

control — 对照组，提供基线测量
treatment — 干预组（实验组），对比 control 看变化

规则：

role 是 variant 的 run-time 属性，不是 artifact 的固有属性；同一个 artifact 在不同 run 可以扮演不同 role
CLI 层通过 --control <expr> 和 --treatment <v1,v2,...> 两个独立参数声明
报告中以 control/treatment 标签展示，不再从 artifactKind === 'baseline' 反推角色
baseline 是 artifact kind 术语，不是 experiment role 术语；参见第三节边界

5. Runtime Context

runtime context 是运行时上下文，当前最核心的是 cwd。

它表示模型或 agent 在什么环境里运行，而不是"被评测对象"本身。

在项目型 agent 场景下，runtime context 就直接包含这些会影响行为的环境因素：

项目目录
CLAUDE.md
本地 skills
仓库文件
工具可见范围

规则：

cwd 归属于 runtime context，单独声明（CLI 的 --control-cwd / --treatment-cwd，或 eval.yaml 的结构化 cwd: 字段），不编码进 variant 表达式
如果要表达"空 artifact + 指定 runtime context"，用自描述标签作 artifact、cwd 单独给，例如 --treatment project-env --treatment-cwd /path/to/project
不要把项目目录、项目级 runtime context、显式 artifact 注入混成一个概念
不要把 runtime context 与 Core 的两个用例级投影混淆：executionContext 是单条用例中仅供 Executor 使用的输入，evaluationContext 是仅供 Evaluator 使用的输入；二者都不描述宿主运行环境

6. Sample / 用例

sample 是评测的一条用例(test case)记录。

规则:

代码 / API / 文件名 / CLI flag 继续用 sample:Sample 类型、sample_id 字段、eval-samples.json 文件名、--samples flag——这些是开源 API + 英文圈 LLM eval 通用术语，不动
user-facing 中文文案默认用「用例」，不用「样本」:CLI 输出、报告 UI、错误信息、文档正文、commit message 中文部分。包括"用例数"/"用例难度"/"用例不足"/"跨用例散度"等组合
理由:omk 的 eval-samples 是开发者手挑的测试用例，不是从某分布随机抽样的统计样本。「样本」会暗示"再多跑就能扩大样本量",误导用户——实际是要补设计、补用例。「用例」是工程语境(test case),与用户写测评时的心智一致("我设计了 5 个用例")
例外：统计学术语场景保留「样本」——Cohen's d / Hedges' g 的"小样本修正"、"样本均值"、"样本方差"、"样本量"、bootstrap "重采样" 等，这些是 stats 领域的固定提法(对应英文 small-sample correction / sample mean / sample variance / sample size / resampling),硬翻成「用例」反而让懂统计的读者多一拍。判定准则:这个词指的是"对总体的一次随机抽样"统计概念(那就是样本),还是**"开发者手挑的一条测试用例"**(那就是用例)。两者不混用、上下文清晰

6.1 Sample 元数据字段

Sample schema 含一组可选元数据字段，纯文档 / 诊断用，不参与 grading / judge / verdict。详见 docs/zh/specs/sample-design-spec.md。

capability?: string[] — 该 sample 测试的能力维度(可多个)。归一时大小写 / 短横线 / 驼峰 / 下划线不敏感。
difficulty?: 'easy' | 'medium' | 'hard' — 难度分层(强枚举)。
construct?: string — 该 sample 测的 construct 类型。Suggested:'necessity'(测必要性,baseline-vs-skill)/ 'quality'(测 skill 写得好不好)/ 'capability'(测某具体能力)。Free-form string 允许自定义。
provenance?: 'human' | 'llm-generated' | 'production-trace' — 数据来源。
covers?: { targetKind: string; ref: string }[] — 这条 sample 可选声明的 skill 结构锚点，Skill Map 用它展示已声明 / 未声明的定义节点。

construct 跟 capability 区别(用户最常混淆的两个字段):

construct = 这个 sample 测哪类事(necessity / quality / capability)。是实验设计的层面 — 你跑 baseline-vs-skill 是测必要性，跑 skill-v1-vs-skill-v2 是测质量。
capability = 这个 sample 测哪些具体能力(api-selection / error-diagnosis / fallback)。是被测对象的能力维度。

7. Task

task 是一次具体执行单元：

一个 sample × 一个 artifact × 一个 runtime context

规则：

任务层不直接代表实验结论
任务是执行与评分的最小单位

8. Trace

trace 是一次执行过程中产生的过程数据，包括：

turns
tool calls
timing
token / cost / cache 等执行指标

规则：

trace 属于运行结果
trace 用于解释 agent 行为差异，不用于命名被评测对象

10. Knowledge（知识）

知识是能被未来任务复用的事实、案例或方法；每条知识应保留适用范围、来源证据和当前验证状态。

这是 OMK 面向知识挖掘的产品工作定义，不代表行业存在统一定义。它指导后续设计，不引入新的存储 Schema，也不表示现有 observation 已具备这些字段。

形式	表达什么	例子
事实	对世界、环境或要求的有范围的主张	某工具在特定版本下的能力限制
案例	包含上下文、行动与观测结果的经历	一次失败尝试，以及在该环境中成功的恢复过程
方法	带适用条件与例外的可复用步骤或判断规则	并行开发需要保留当前工作现场时，创建独立 worktree

案例可以有复用价值，而不必足以支持一般规则。一次成功不能证明方法普遍有效。明确的偏好和要求应保留提出者与适用范围，不应被推断为普遍事实。

每条候选知识应保留：

适用范围：限制复用的任务、环境、版本或其他条件，以及已知例外。
来源证据：支持主张的可追溯记录，保留足够上下文以区分观测事实与解释，并保留反证。
验证状态：区分证据复核与效果评测，明确尚未验证的部分。来源已复核，不等于把知识提供给 Agent 已被证明能改善表现。

工作日志记录发生过什么。知识挖掘从证据中筛选可复用事实、保留有价值的案例并提出方法，同时覆盖成功经验、失败和对已有知识的修正。提炼出的解释在复核前属于候选；重复出现不自动构成独立佐证。

知识内容与知识载体是两个层次。一份 skill、prompt 或项目规则文件可以包含多条知识，同一条知识也可以出现在多个载体中。这些知识形式不扩展 ArtifactKind，也不替代现有 artifact 身份。

观测提供证据与候选。受控评测固定模型，检验载体改动在声明的任务范围内是否有帮助，不证明某条主张普遍为真。用于形成改动的案例不能再被表述为独立的泛化验证证据。知识接纳与版本发布仍遵循现有评测及治理契约。

设计参考：KCS 的知识条目结构与复用实践用于借鉴带上下文的捕获与持续复核；LangChain 的记忆分类区分事实、经历与指令。上述定义和边界是 OMK 对这些实践的综合取舍。

三、术语边界

1. baseline 就是"什么都没有"

baseline 的标准含义是：

不做显式 artifact 注入
不额外附带项目级 runtime context

对大多数使用者来说，baseline 就可以直接理解为"什么都没有"。

如果要单独观察项目级 runtime context，推荐显式写成：

artifact 用自描述标签 project-env，cwd 用 --treatment-cwd /path/to/project（或 eval.yaml 的 cwd: 字段）

这里的 project-env 只是实验分组标签，真正的语义是"空 artifact + 指定 runtime context"。

2. skill 不是总称

skill 只在对象确实是 skill 文件、skill 目录或 skill 风格 system prompt 时使用。

以下场景不要用 skill 做总称：

比较多个不同类型对象
描述 CLI 通用变体语法
描述未来 agent team、workflow 等对象

3. agent 不是总称

agent 用于描述具有 agent 运行特征的 artifact 或运行形态，例如：

有工具调用
有多轮轨迹
依赖运行时环境

但 agent 不应替代 artifact 成为通用术语。

4. baseline kind 和 control role 不是一回事

baseline 是 ArtifactKind 枚举中的一员，表示"空 artifact"（不注入任何显式 artifact）。 control 是 experimentRole 的取值，表示"这个 variant 在本次实验里扮演对照角色"。

两者正交：

一个 baseline kind 的 artifact 通常扮演 control role，但这不是定义
两个都是 skill kind 的 artifact（v1 vs v2）比较时，其中一个被显式声明为 control——此时 control role 和 baseline kind 没有任何关系
报告与代码都应以 experimentRole 作为判定对照组的唯一来源，不从 artifactKind === 'baseline' 反推

5. CI 在 omk 里只指 Confidence Interval

omk 里 CI 永远只指置信区间(Confidence Interval),不指 Continuous Integration。这条避免与统计学外的 "CI" 含义混淆。

规则:

持续集成场景的内部 helper 一律用 "gate"：omk eval 的 gate 路径 / evaluateLayerGates / gateThreshold / LayerGateResult
置信区间场景一律用「CI」：Bootstrap CI / comparison CI / interval Analysis result / 95% CI
文档 / 注释 / commit message 提到 "CI" 时不必加澄清 — 单一含义，读者不需上下文判断

6. 稳定性 = 跨独立 Run，而不是跨用例散度

稳定性属于 test-retest 概念：同一份 sealed measurement design 作为 Evaluation Series 中的独立 Run 重复执行。当前 Series Analysis 报告 run-mean composite 的无偏样本方差。单次 Run 不包含跨 run 稳定性证据，Run Decision 也绝不能自行推断。

跨用例 score range 与 success rate 都不是稳定性。用例本就会有意覆盖不同难度，而 success rate 属于运行健康事实；两者都应与 Series variance 分开表达。

7. Composite 三层：fact / behavior / judge

Core Composite Analysis 最多绑定 fact、behavior 与 judge 三个具名 layer。

层	来源	本质
事实	显式分类的 Boolean criterion observation	规则可验证
行为	显式分类的执行合规 criterion observation	规则可验证
LLM 评价	ensemble consensus 或 dimension aggregate	模型评测

这些术语表示 Analysis 职责，不是可变的 report field。新代码使用限定 table entry 与 source binding；不得重新引入已删除的 LayeredScores、factScore、behaviorScore、judgeScore 或 avg*Score 结果行字段。中文在指 evaluator 来源时使用「LLM 评委」，指 Composite Analysis 时使用「judge layer」。

四、对外表达规范

1. 文档

对外文档采用以下优先级：

顶层总称：artifact
实验分组：variant
实验角色：control / treatment
运行环境：runtime context
具体对象类型：skill / agent / workflow

2. 命令示例

命令示例中：

使用 --control <expr> + --treatment <v1,v2,...> 按 experiment role 声明 variant
variant 表达式解析为 artifact 与 runtime context
示例对象尽量写具体路径或具体名称，不用泛化占位代替所有场景
复杂实验配置推荐用 --config eval.yaml，CLI 参数只承担简单场景

3. 报告与验收

报告、验收文档应优先回答：

这次比较的 artifact 是什么
它们运行在什么 runtime context 中
谁是 control、谁是 treatment
差异来自 artifact 本身，还是来自 runtime context

五、对内实现规范

1. 类型与字段

新代码优先使用：

Artifact
ArtifactKind
artifacts
task.artifact
artifactHashes
VariantConfig.experimentRole（新增字段，枚举 'control' | 'treatment'）

2. 去兼容策略

omk 当前仍处于 0-1 阶段，用户规模很小，因此不主动保留历史兼容层。

规则：

新实现直接收敛到 artifact 术语
旧命名如果会造成长期歧义，应直接删除，而不是继续挂兼容别名
破坏性调整优先在现在完成，不向后滚雪球
v0.16 起 --variants 直接移除（不打 deprecation warning），用户迁移到 --control / --treatment

3. 命名原则

通用抽象用 artifact
具体子类用 skill / agent / workflow
实验编排用 variant
实验角色用 control / treatment（不用 baseline / experiment）
运行环境用 runtime context / cwd

4. 裸 `kind` 留给 `ArtifactKind`

在 omk 的产品语义里，裸 kind 默认指 Artifact.kind（ArtifactKind：baseline / skill / prompt / agent / workflow）。baseline 表示 eval 里的空 artifact；实验角色仍然看 control / treatment。命令行设计同理：omk install 上的 --kind flag 表示 artifact kind（对齐 Artifact.kind），而不是安装目标、report 类型或 observe event 类型。

其它判别字段如果是新字段，或能安全改名，就用限定名。已经发布、已落盘或已有外部消费方依赖的 kind 字段保持原样，除非单独做 migration：

report.kind 保持为 report public schema 的 canonical 字段
doctor.kind 保持为 doctor report 的 canonical 字段
observe-*.kind 保持为 observe report 的 canonical 字段
event.kind → eventKind
executorRuntime.kind → runtimeKind
standard.kind → standardKind

两条注意：

持久化判别字段 —— report / observe / doctor / diagnosis 的顶层判别字段是 kind，由它早先的限定名字段经一次有意的 BREAKING-SCHEMA 硬切换而来。 硬切换不做双读、不留迁移垫片：旧版本写的文件（顶层是旧的限定名判别字段、无 kind）直接不读、跳过。这是序列化向后兼容，不是统计可比性 —— 改字段名不改任何测量数字。（report.kind 另外还在 Report schema 不变量清单里，后续改动按常规 schema 谨慎处理。）
内部非持久字段的改名是渐进式的 —— 改到那块代码时顺手做，不搞一次性大扫除。一个 CI 护栏冻结当前裸 kind 声明点的集合，防止新的不加限定的 kind 混进来。

六、术语映射

旧术语	新标准术语	说明
evaluand	artifact	被评测对象的统一总称
EvaluandSpec	Artifact	核心对象类型
EvaluandKind	ArtifactKind	对象类别
evaluands	artifacts	请求中的对象列表
task.evaluand	task.artifact	单个任务绑定的对象
evaluandHashes	Target artifact descriptor	Target config 与 managed evidence 中封存的完整 SHA-256 内容身份
skillHashes	Target artifact descriptor	Core lineage 中统一的 artifact identity
skill 作为总称	artifact	skill 退回为具体子类
agent 作为总称	artifact / agent runtime	视语义选择
`--variants` CLI 参数	`--control` / `--treatment`	按 experiment role 声明 variant，废除扁平列表
从 `artifactKind === 'baseline'` 推断对照组	显式读 `experimentRole === 'control'`	对照组由用户声明，不从 artifact kind 反推
`LayeredScores.qualityScore`	Composite `judge` layer entry	已删除的结果行字段由显式绑定的 Analysis source 替代
`VariantSummary.avgQualityScore`	来自 Composite Analysis 的 Studio projection	展示数据从经过认证的 Core 产物重建
`VarianceLayerKey: 'quality'`	Evaluation Series run-mean composite variance	Series 不复用旧 layer key

七、Skill Isolation(v0.22 新增)

1. 问题背景

omk 通过原生 coding-agent runtime 跑 baseline-vs-skill 评测时，baseline 可能发现从未被声明为测量输入的本地知识，导致它不再是「裸模型」，形成 construct invalidity。

Claude runtime 有三条相关通道：SDK / CLI 的 skill 发现、子代理 Skill 工具，以及普通 cwd 文件访问。Codex 会从 workspace 与本地 profile 发现 AGENTS.md、.agents/skills/、项目规则等上下文。两类 runtime 也都可能通过普通工具读取 cwd 下的 skills/<name>/。

因此严格 baseline 必须同时使用干净的逐次运行 cwd 与执行器特定的隔离控制。任一发现通道仍然开放，verdict / Δ 反映的都会是污染基线 vs treatment，而非预期的「无知识 vs 有知识」。

2. 术语

allowedSkills(per-variant 字段，新加在 Artifact / VariantConfig / EvalConfigVariant 上):
- undefined → 使用执行器默认 runtime context，不请求隔离
- [] → 请求严格隔离：omk 提供空的逐次运行 cwd，并应用当前执行器支持的全部隔离控制
- [name1, ...]（非空）→ 在统一 execution-plan 边界拒绝：原生 agent、API 与自定义执行器之间不存在可移植且可证明的白名单机制；严格隔离请用 []，不隔离则省略
--strict-baseline flag(default true):对所有 kind === 'baseline' 的 artifact 自动设 allowedSkills = [];--no-strict-baseline 关掉(显式 opt-out)
meta.skillIsolation(report meta 新字段):variantName → allowedSkills 快照，跨报告对比 verdict / Δ 时校验

3. 默认值与优先级

eval.yaml variant.allowedSkills (显式)
  > CLI --strict-baseline / --no-strict-baseline (批量)
  > default (strictBaseline = true)

baseline-kind 默认 []（strict），其他 kind 默认 undefined（执行器默认上下文）。

4. 隔离覆盖范围

Runtime / 通道	覆盖？	机制
通用 cwd 文件访问	是，针对隐式 baseline cwd	`~/.oh-my-knowledge/state/isolated-cwd/` 下的全新逐次运行空目录
Codex CLI profile、session 与规则	是	`--ephemeral --ignore-user-config --ignore-rules` + 隔离 `-C`
Codex SDK profile 与 session	是	临时 `CODEX_HOME`（只复制凭证）+ 隔离 working directory
Codex SDK 项目 execpolicy	SDK 限制	SDK 不暴露 `--ignore-rules`；要求这一层隔离时使用 `codex` 执行器
Claude SDK skill 发现 / 子代理 Skill 工具	是	`skills: []` + `disallowedTools: ['Skill']`
Claude CLI skill 命令	是	`--disable-slash-commands --disallowedTools Skill`
自定义 script 执行器	无法强制	一次性告警；omk 无法证明用户命令加载了什么

为什么 cwd 单独列出：provider 特定的 flag 无法阻止 agent 用普通文件工具读取评测 workspace 下的 skills/<name>/。因此严格 baseline 在没有显式 cwd 时，每次执行都使用一个全新的空目录。用户显式指定 baseline cwd 时，omk 不会替换它，因为该目录属于用户有意纳入测量的 runtime context。

注:isolated-cwd 不是 sandbox,baseline 仍可 Read 任意 absolute path。但模型不会主动猜用户私有路径(没 system prompt 暗示)。如果评测场景里 baseline 会被 prompt 引导去读绝对路径，需要再加层 sandbox 保护(out-of-scope)。

5. cache key 版本

cache key 当前使用 v9: prefix，绑定模型、prompt、cwd、隔离声明、执行器、runtime 指纹、mocks、strict-mock 模式、effort、artifact 内容指纹，以及 return_file 引用的外部 mock fixture 内容。缓存结果保留完整 turns / toolCalls，并与冷执行一样经过 source-neutral 返回值校验和工具身份归一化；任一 construct-validity 输入变化都不会静默复用不兼容结果。

报告和 resume 可比性使用的样本 hash 还会纳入每个自定义 assertion 模块及其可静态解析的 ESM import 图。非字面量 dynamic import 会记录为未解析标记，无法读取或解析的模块也会写入显式标记，不会被当作“依赖未变化”。依赖展示路径会尽量相对评测用例 bundle 保存，因此相同 checkout 仅移动目录不会改变测量身份。

6. executor 兼容

Executor	undefined	`[]`	`[name]`
`codex`	执行器默认 cwd	隔离 cwd + 忽略用户配置 / rules	统一 planner 抛错
`codex-sdk`	项目 cwd；隔离 `CODEX_HOME`	隔离 cwd + 隔离 `CODEX_HOME`	统一 planner 抛错
`claude-sdk`	默认全发现	skills:[] + disallowedTools:[Skill]	throw
`claude-cli`	默认	`--disable-slash-commands --disallowedTools Skill`	throw
API 执行器	不隐式发现本地 skill	无额外效果	统一 planner 抛错
自定义 script	由命令决定	stderr 告警，无法保证隔离	统一 planner 抛错

非空 skill 白名单 [name] 会在执行器分发前被拒绝，programmatic caller 即使绕过 eval.yaml 校验也一样。严格隔离使用 []，执行器默认上下文则省略。自定义 script 即使收到 [] 也无法证明严格隔离，因此 omk 会告警并记录隔离声明用于审计，不会静默声称已经兑现。

八、落地判断标准

后续新增功能、文档或接口时，如果遇到命名选择，按下面顺序判断：

它是在描述被评测对象吗？如果是，用 artifact
它是在描述实验分组吗？如果是，用 variant
它是在描述实验角色吗？如果是，用 control / treatment
它是在描述运行目录或环境吗？如果是，用 runtime context
它是在描述具体对象类型吗？如果是，用 skill / agent / workflow
如果一个词同时混合了对象、环境或角色语义，就要拆开重写

omk 术语规范 ​

一、目标 ​

二、标准术语 ​

1. Artifact ​

2. Artifact Kind ​

3. Variant ​

4. Experiment Role ​

5. Runtime Context ​

6. Sample / 用例 ​

6.1 Sample 元数据字段 ​

7. Task ​

8. Trace ​

10. Knowledge（知识） ​

三、术语边界 ​

1. baseline 就是"什么都没有" ​

2. skill 不是总称 ​

3. agent 不是总称 ​

4. baseline kind 和 control role 不是一回事 ​

5. CI 在 omk 里只指 Confidence Interval ​

6. 稳定性 = 跨独立 Run，而不是跨用例散度 ​

7. Composite 三层：fact / behavior / judge ​

四、对外表达规范 ​

1. 文档 ​

2. 命令示例 ​

3. 报告与验收 ​

五、对内实现规范 ​

1. 类型与字段 ​

2. 去兼容策略 ​

3. 命名原则 ​

4. 裸 kind 留给 ArtifactKind ​

六、术语映射 ​

七、Skill Isolation(v0.22 新增) ​

1. 问题背景 ​

2. 术语 ​

3. 默认值与优先级 ​

4. 隔离覆盖范围 ​

5. cache key 版本 ​

6. executor 兼容 ​

八、落地判断标准 ​