oh-my-knowledge 0.48.0 → 0.49.0

package/dist/assets/agent-skills/omk/SKILL.md

@@ -21,6 +21,12 @@ npm i oh-my-knowledge -g
 
 omk CLI 顶层命令包括：`init` / `install` / `list` / `promote` / `rollback` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
 
+### 在 Codex / ChatGPT desktop 中
+
+Codex 是 omk 的一等 runtime。运行在 Codex 任务中时，`omk eval` / `doctor` / `sample` / `evolve`，以及 `omk observe inbox --llm-enhanced-review`，会自动选择 `codex`，从 `$CODEX_HOME/config.toml` 或 `~/.codex/config.toml` 读取顶层 `model`，默认评委沿用同一个 Codex 模型；不要额外回落到 Claude。
+
+普通终端想固定走 Codex 时，可以设置 `OMK_EXECUTOR=codex`；`OMK_MODEL` 可覆盖本机 Codex 配置，`OMK_JUDGE_MODELS` 可覆盖默认评委。逐次覆盖仍可使用 `--executor` / `--model` / `--judge-models`。Codex 不需要 Claude Code 风格的 `/omk` slash command，直接执行 CLI。
+
 ## 第二步：理解用户意图
 
 根据用户的描述，匹配对应的操作：
@@ -79,9 +85,10 @@ omk eval --config eval.yaml
 
 常用选项：
 
-- `--model <name>` 任务执行模型（默认 opus；省钱用 sonnet / haiku）
+- `--executor <name>` 显式覆盖执行器；Codex 任务中通常不用传
+- `--model <name>` 显式覆盖任务执行模型；Codex 默认读取本机配置
 - `--effort <low|medium|high|xhigh|max>` 执行模型扩展思考预算（默认 low；跨 effort 报告不严格可比）
-- `--judge-models <executor:model[,...]>` 评委配置（默认 claude:haiku，≥ 2 条 = ensemble）
+- `--judge-models <executor:model[,...]>` 显式覆盖评委配置（Codex 默认沿用被测模型，≥ 2 条 = ensemble）
 - `--concurrency <n>` 并发数
 - `--skip-doctor` 跳过 doctor preflight 门禁（默认 doctor 会先跑一次卡掉 skill 写法大问题）
 - `--no-diagnostic` 关掉 diagnostic 诊断 LLM 调用（默认开启，给 failed sample 出「哪错了 + 怎么改」建议）
@@ -118,6 +125,19 @@ omk sample --batch
 
 输出位置：目录 skill（`<skill>/SKILL.md`）→ `<skill>/.omk/samples.json`（标准）；扁平 `.md` 单次生成 → 当前目录 `eval-samples.json`（项目级兜底）；扁平 `.md` 的 `--batch` 兼容生成 `<skill-dir>/<name>.eval-samples.json`。
 
+### 观测真实使用
+
+```bash
+# ChatGPT desktop / Codex CLI rollout
+omk observe ~/.codex/sessions --last 7d
+omk observe ingest ~/.codex/sessions
+
+# Claude Code session
+omk observe ~/.claude/projects/<project> --last 7d
+```
+
+Codex rollout 会保留 `sourceKind=codex`、模型、父子任务、tool call 和 token 证据，并从实际读取的 `skills/<name>/SKILL.md` 归因 skill。`observe ingest` 生成待复核 observation；确认真实知识缺口后，再用 `omk sample --from-traces` 草拟评测用例。
+
 ### 体检 skill 写法
 
 ```bash
@@ -154,9 +174,9 @@ Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级
 
 1. **结论**：verdict 是 PROGRESS / NOISE / REGRESSION / CAUTIOUS，哪个 variant 更好
 2. **质量分数**：各 variant 的平均综合分（0-5 分）+ Δ + 95% CI
-3. **成本对比**：token 消耗、execCostUSD、判官花费、diagnostic 花费
+3. **成本对比**：token 消耗、execCostUSD、评委花费、diagnostic 花费
 4. **低分样本**：哪些样本两个版本差异最大，rubric 期望 vs 实际差在哪
-5. **建议**：基于数据给出的下一步行动建议
+5. **下一步动作**：基于 verdict 给出动作；`PROGRESS` 时明确说明可以进入发布流程、留存报告作为发布证据，受管 skill 继续 `omk promote`；其它 verdict 给出扩样 / 修复 / 重跑建议
 
 示例输出：
 
@@ -165,7 +185,7 @@ v2 比 v1 更好（verdict: PROGRESS，Δ=+0.7，95% CI [+0.3, +1.1]）：
 - 质量：v2 平均 4.5 分 vs v1 平均 3.8 分（+18%）
 - 成本：v2 略高（$0.15 vs $0.12），因为输出更详细
 - 亮点：v2 在 s002（错误处理）上显著提升（2.5 → 4.5），因为新增了"列出所有缺失的错误处理场景"指令
-- 建议：v2 可以上线，但 s003（XSS 检测）仍然有提升空间
+- 建议：v2 可以进入发布流程；留存本次报告作为发布证据。如果这是受管 skill，继续运行 `omk promote` 记录接受决定。s003（XSS 检测）仍然可以作为下一轮优化点。
 ```
 
 ### evolve 模式
@@ -189,11 +209,11 @@ v2 比 v1 更好（verdict: PROGRESS，Δ=+0.7，95% CI [+0.3, +1.1]）：
       values: ["auth.ts", "login.tsx"]
 ```
 
-`cwd` 会作为 executor 的工作目录，`claude -p` 将在该目录下运行，能自动读取仓库代码。适用于「给一个任务 query，断言应该修改哪些文件」的 A/B 评测场景。
+`cwd` 会作为 executor 的工作目录，Codex / Claude 等 agent runtime 会在该目录下运行并读取仓库代码。适用于「给一个任务 query，断言应该修改哪些文件」的 A/B 评测场景。
 
 ## 注意事项
 
-- 评测需要调用 LLM，会产生费用。运行前告知用户预估成本（样本数 × 变体数 × 约 $0.01-0.05 美元 / 次）
+- 评测需要调用 LLM，会产生费用。能从执行器取得价格时，运行前告知用户预估成本；Codex CLI / SDK 当前不报告 USD 成本，应明确显示为「—」，不要伪装成 $0
 - 首次使用建议先 `--dry-run` 预览任务计划
 - `evolve` 命令会修改原始 skill 文件，原始版本保存在 `skills/evolve/*.r0.md`
 - 详细命令参考见 [commands.md](references/commands.md)

package/dist/assets/agent-skills/omk/references/commands.md

@@ -23,13 +23,13 @@ omk doctor [target] [flags]
 - `--concurrency` `option`:多次采样的并发数。默认 = --repeat（全并行，各遍相互独立，压墙钟时间）。设 1 = 串行。成本不变，只抬高瞬时并发（rate-limit 敏感时调小）。
 - `--dimensions` `option`:自定义维度配置文件（YAML），追加到内置 7 维度之后。每条维度二选一：promptSection（走 LLM 体检）或 endpoint（POST skill 快照给接口判定）。注意：endpoint 会把 SKILL.md 全文 + 子文件发到该地址，仅对可信配置/可信地址启用。
 - `--effort` `option`:LLM 推理 effort：low / medium / high / xhigh / max。
-- `--executor` `option`:执行器名，默认 claude。指定为测试 fixture 路径可在测试里跑（同 omk doctor）。
+- `--executor` `option`:执行器名。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。指定为测试 fixture 路径可在测试里跑。
 - `--fix` `boolean`:交互式修复：根据 doctor 报告问题，用 LLM agent 修复 skill。
 - `--gate` `boolean`:静默模式，只在 fail 时输出 stderr 摘要，exit code 标识结果。
 - `--global` `boolean`:写全局 ~/.oh-my-knowledge/doctors，而非项目 .omk/doctors
 - `--json` `boolean`:JSON 输出到 stdout，适合 CI / 外部脚本消费。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
-- `--model` `option`:LLM model 名，默认 sonnet。
+- `--model` `option`:LLM model 名。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。
 - `--output-dir` `option`:报告输出目录，默认项目级 .omk/doctors（--global 写全局）。
 - `--repeat` `option`:健康度体检重复采样次数（self-consistency）。默认 2：并行跑 2 遍、finding 取并集并用 LLM 聚类归并同根因、标注支持度 k/N，压低单次采样方差。设 1 = 单次快速体检（不采样、不归并，最省）。
 - `--static-only` `boolean`:只跑静态检测（不调 LLM、不读 samples.json）：skill 可读性 / frontmatter 合法性 / 正文引用的脚本·CLI·文件·env 是否存在。CI 无 LLM 凭证或断网时用。
@@ -85,11 +85,11 @@ omk eval [flags]
 - `--control-cwd` `option`:control 的 runtime context 目录
 - `--dry-run` `boolean`:只 plan 不实跑
 - `--effort` `option`:被测 LLM 扩展思考预算 low/medium/high/xhigh/max（默认 low；跨 effort 报告不严格可比）。
-- `--executor` `option`:执行器:claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令（默认 claude）。
+- `--executor` `option`:执行器：claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。
 - `--global` `boolean`:报告写全局 ~/.oh-my-knowledge/reports，而非项目 .omk/
 - `--gold-dir` `option`:gold dataset 目录
 - `--holdout-ratio` `option`:留出比例 0-1（如 0.3）；切出 holdout 子集，对比 train/holdout 综合分检测过拟合
-- `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai-api:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。
+- `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 codex:<model>（≥ 2 个 = ensemble）。默认跟随所选执行器；Codex 沿用被测模型。
 - `--judge-repeat` `option`:每个 dim 评 N 次
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--layered-stats` `boolean`:输出分层统计
@@ -106,7 +106,7 @@ omk eval [flags]
 - `--output-dir` `option`:报告输出目录（默认项目级 .omk/reports）
 - `--repeat` `option`:每个 sample 重复跑 N 次
 - `--report-only` `boolean`:生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
-- `--resume` `option`:从某次失败 run 续跑
+- `--resume` `option`:从契约兼容的报告恢复成功项；不兼容则从头运行
 - `--retry` `option`:失败 sample 重试次数
 - `--samples` `option`:用例文件路径。默认项目级 eval-samples.json，也接受 .yaml/.yml；单 treatment 时可自动发现 <skill>/.omk/。
 - `--skill-dir` `option`:skill 目录，默认 skills
@@ -225,13 +225,13 @@ omk evolve <skillPath> [flags]
 - `--concurrency` `option` (默认 `1`):评测并发数，默认 1
 - `--edit-budget` `option` (默认 `0.2`):单轮最多改动的 skill 行占比（默认 0.2）。超预算的候选评测前直接判拒，省 eval 成本
 - `--effort` `option`:reasoning effort: low/medium/high/xhigh/max
-- `--executor` `option` (默认 `claude`):执行器名，默认 claude
+- `--executor` `option`:执行器名。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。
 - `--holdout-ratio` `option` (默认 `0`):留出验收集比例（0..1，默认 0=关）。> 0 时按 holdout 分接受候选、weak-sample 只取训练集，防 train-on-test
 - `--improve-mode` `agent|rewrite` (默认 `agent`):改写策略（默认：agent）
-- `--improve-model` `option` (默认 `sonnet`):负责重写 skill 的 LLM，默认 sonnet
-- `--judge-models` `option` (默认 `claude:haiku`):评委 model（单评委约束），格式 executor:model。默认 claude:haiku
+- `--improve-model` `option`:负责重写 skill 的 LLM，默认沿用被测模型
+- `--judge-models` `option`:评委 model（单评委约束），格式 executor:model。默认跟随所选执行器；Codex 沿用被测模型。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
-- `--model` `option` (默认 `sonnet`):被评测的 LLM，默认 sonnet。无用例时也用作自动生成用例的出题模型。
+- `--model` `option`:被评测的 LLM。Codex 自动读取本机配置；无用例时也用作自动生成用例的出题模型。
 - `--no-diagnostic` `boolean`:关 LLM diagnostic 调用
 - `--no-edit-budget` `boolean`:关掉 edit budget 约束（允许任意大小的单轮改动）
 - `--no-reject-memory` `boolean`:关掉 rejected-edit 记忆（不把被拒改法回灌下一轮 prompt）
@@ -396,7 +396,7 @@ omk list --json
 
 ## omk observe
 
-分析 sessions 目录的 skill 调用健康度（默认行为）。子命令:ingest / inbox / show。
+把 Codex、Claude Code、OpenClaw 或 markdown trace 统一为 Trace IR，分析 skill 调用健康度（默认行为）。子命令：ingest / inbox / show。
 
 **用法:**
 
@@ -406,7 +406,7 @@ omk observe [sessionsDir] [flags]
 
 **参数:**
 
-- `sessionsDir`(可选):sessions 目录路径（如 ~/.claude/sessions）
+- `sessionsDir`(可选):sessions 目录路径（如 ~/.codex/sessions 或 ~/.claude/projects/<project>）
 
 **Flags:**
 
@@ -422,10 +422,10 @@ omk observe [sessionsDir] [flags]
 
 **示例:**
 
-> 分析最近 7 天
+> 分析最近 7 天的 Codex rollout
 
 ```bash
-omk observe ~/.claude/sessions --last 7d
+omk observe ~/.codex/sessions --last 7d
 ```
 
 ## omk observe inbox
@@ -441,7 +441,7 @@ omk observe inbox [flags]
 **Flags:**
 
 - `--by-skill` `boolean`:按 skill 聚合输出
-- `--executor` `option`:LLM 增强复盘使用的执行器
+- `--executor` `option`:LLM 增强复盘使用的执行器。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。
 - `--explore` `option`:抽样 N 条 medium/low 长尾（replaces limit）
 - `--global` `boolean`:直接读取全局 ~/.oh-my-knowledge/observe-inbox（跳过项目级与兜底）。
 - `--include-noise` `boolean`:explore 时也包含 noise 桶
@@ -450,7 +450,7 @@ omk observe inbox [flags]
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--limit` `option`:限制条数，默认 20
 - `--llm-enhanced-review` `boolean`:显式调用模型进行链路增强复盘，包含标准抽取、目标判断、类型判断、产物匹配和 owner 建议
-- `--model` `option`:LLM 增强复盘使用的模型，默认 sonnet
+- `--model` `option`:LLM 增强复盘使用的模型。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。
 - `--refresh` `boolean`:重新生成 LLM 增强复盘，不复用已有结果
 - `--skill` `option`:只看指定 skill
 
@@ -471,6 +471,7 @@ omk observe ingest <traceDir> [flags]
 **Flags:**
 
 - `--global` `boolean`:写入全局 ~/.oh-my-knowledge/observe-inbox，而非项目 .omk/observe-inbox。
+- `--json` `boolean`:把完整 observation inbox 报告输出到 stdout；默认只输出摘要。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--output-dir` `option`:输出目录，默认 .omk/observe-inbox（项目级，相对于 cwd；--global 写全局）。
 
@@ -595,12 +596,12 @@ omk sample [skillPath] [flags]
 - `--append` `boolean`:在已有用例文件上追加新生成的用例（撞 sample_id 自动加后缀去重，保留原 json/yaml 格式）。仅单 skill 模式，不支持 --batch / --from-traces / --fix。不传则已有文件时报错保护。常配 --focus 补特定场景。
 - `--batch` `boolean`:批量模式：扫 --skill-dir 下所有缺 samples 的 skill，逐个生成。
 - `--count` `option`:生成用例条数。不传由 LLM 按 skill 类型自动决定。
-- `--executor` `option`:执行器名，默认 claude（同 omk eval / doctor / evolve）。指定 codex 等其它执行器时，记得连带传一个该执行器能识别的 --model。
+- `--executor` `option`:执行器名。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。
 - `--fix` `boolean`:fix 模式：基于最近评测报告自动修复 sample_design 类型失败。
 - `--focus` `option`:生成焦点（自然语言提示）。控制 LLM 偏向哪类用例。
 - `--from-traces` `boolean`:from-traces 模式：从 observe inbox 的失败信号回流生成回归用例草稿（provenance: production-trace），落草稿待人工 review。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
-- `--model` `option` (默认 `sonnet`):生成 LLM model 名，默认 sonnet。
+- `--model` `option`:生成 LLM model 名。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。
 - `--no-mock` `boolean`:不生成 mocks，eval 时所有工具调用真实执行。
 - `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observe-inbox。
 - `--reports-dir` `option`:报告目录（fix 模式用），默认 ~/.oh-my-knowledge/reports。

package/dist/authoring/evolver.d.ts

@@ -15,6 +15,7 @@ interface WeakSample {
         none?: string;
     };
 }
+export declare function singleVariantReport(report: Report, variantKey: string): Report;
 export declare function extractWeakSamples(report: Report, variantKey: string, count?: number, sampleIdFilter?: Set<string>): WeakSample[];
 /** A train / val / test partition. `val` drives the accept decision; `test` is
  *  locked — never seen during the loop, read once at the end for an unbiased
@@ -78,6 +79,7 @@ export declare function decideAccept(bestScores: number[], candScores: number[],
  */
 export declare function restrictReportToSamples(report: Report, sampleIds: Set<string>): Report;
 export declare function allNonTripwireAssertionsPass(report: Report, variantKey: string): boolean;
+export declare function agentSampleEditWithinScope(previous: Sample, next: Sample): boolean;
 interface EditDelta {
     /** Symmetric line difference (added + removed unique lines) over original line count. */
     ratio: number;
@@ -114,7 +116,7 @@ export interface EvolveRoundProgressInfo {
      *  explain an otherwise-confusing `(+0.0x) ✗ REJECT`. Undefined = gate didn't run. */
     significant?: boolean;
 }
-interface EvolveOptions {
+export interface EvolveOptions {
     skillPath: string;
     samplesPath: string;
     rounds?: number;
@@ -123,15 +125,17 @@ interface EvolveOptions {
     autoFixSamples?: boolean;
     sampleFixMaxAttempts?: number;
     reuseLatestEval?: boolean;
-    model?: string;
+    /** Explicit measured runtime. Provider defaults belong to the CLI boundary. */
+    model: string;
     /** Single-judge config. evolve 不支持 ensemble — CLI 在 length>=2 时 exit 2,
-     *  programmatic API 在 evolveSkill 入口同样 throw,二者一致。Default
-     *  `[{ executor: <executorName>, model: 'haiku' }]`. */
+     *  programmatic API 在 evolveSkill 入口同样 throw,二者一致。缺省时复用
+     *  被测 executor/model；CLI 会在调用前解析 provider-specific 默认值。 */
     judgeModels?: JudgeConfig[];
     improveModel?: string;
     /** 改写策略。'agent' 用 agent 工具增量 Edit；'rewrite' 用单次 LLM 输出全文。默认 'agent'。 */
     improveMode?: 'agent' | 'rewrite';
-    executorName?: string;
+    /** Explicit measured executor. Provider defaults belong to the CLI boundary. */
+    executorName: string;
     concurrency?: number;
     timeoutMs?: number;
     skipConnectivity?: boolean;
@@ -254,6 +258,6 @@ export interface RoundReport {
     accepted: boolean;
     report: Report;
 }
-export declare function mergeEvolveReports(roundReports: RoundReport[], skillName: string, totalCostUSD: number, samples?: Sample[], skillPath?: string): Report;
+export declare function mergeEvolveReports(roundReports: RoundReport[], skillName: string, processCostUSD: number, samples?: Sample[], skillPath?: string, processCostReported?: boolean): Report;
 export declare function evolveSkill({ skillPath, samplesPath, rounds, target, stopOnAssertionsPass, autoFixSamples, sampleFixMaxAttempts, reuseLatestEval, model, judgeModels, improveModel, improveMode, executorName, concurrency, timeoutMs, skipConnectivity, effort, noDiagnostic, skipDoctor, holdoutRatio, significanceGate, significanceAlpha, testRatio, editBudget, rejectMemory, writeBackToSource, onProgress, onRoundProgress, }: EvolveOptions): Promise<EvolveResult>;
 export {};