oh-my-knowledge 0.33.0 → 0.35.0

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

@@ -0,0 +1,556 @@
+# omk 命令参考
+
+<!-- omk:cli:start -->
+<!-- 此段由 scripts/build-docs.ts 从 src/cli/commands/ 自动生成。
+     改 CLI 后跑 `yarn build:docs` 同步,CI `yarn build:docs:check` 会拦截 drift。-->
+
+## omk doctor
+
+体检 omk 工作目录，检查 skill 配置 / 依赖 / executor 连通性。
+
+**用法:**
+
+```bash
+omk doctor [target] [flags]
+```
+
+**参数:**
+
+- `target`(可选):要体检的 skill 路径或目录。可选，默认扫当前 cwd 下的 skills/。
+
+**Flags:**
+
+- `--dimensions` `option`:自定义维度配置文件（YAML），追加到内置 7 维度之后。
+- `--effort` `option`:LLM 推理 effort：low / medium / high / xhigh / max。
+- `--executor` `option`:执行器名，默认 claude。指定为测试 fixture 路径可在测试里跑（同 omk doctor）。
+- `--fix` `boolean`:交互式修复：根据 doctor 报告问题，用 LLM agent 修复 skill。
+- `--gate` `boolean`:静默模式，只在 fail 时输出 stderr 摘要，exit code 标识结果。
+- `--json` `boolean`:JSON 输出到 stdout，适合 CI / 外部脚本消费。
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--model` `option`:LLM model 名，默认 sonnet。
+- `--output-dir` `option`:报告输出目录，默认 ~/.oh-my-knowledge/doctors。
+- `--samples` `option`:用例文件路径（.json/.yaml）。不传则按 target / cwd 顺序自动发现。
+- `--static-only` `boolean`:离线静态模式，只跑 4 条静态 rule(skill_readable / skill_metadata / dependencies_present / samples_contract_aligned），不调 LLM。
+- `--timeout` `option`:单次 LLM 会话超时秒数，默认 600(10 分钟）。
+
+**示例:**
+
+> 默认模式跑 LLM 健康度审计(7 内置维度）。
+
+```bash
+omk doctor
+```
+
+> 离线静态模式，只跑 4 条静态 rule，不调 LLM,CI 无 LLM 凭证时用。
+
+```bash
+omk doctor --static-only
+```
+
+> JSON 输出 + 写 HTML 报告，给 CI 抓 exit code 同时人看。
+
+```bash
+omk doctor --json --gate
+```
+
+## omk eval
+
+跑评测：对一个 control vs 多个 treatment skill 做对照试验，产 verdict 报告。
+
+**用法:**
+
+```bash
+omk eval [flags]
+```
+
+**Flags:**
+
+- `--batch` `boolean`:batch 模式:baseline vs 每个 skill
+- `--blind` `boolean`:judge blind 模式
+- `--bootstrap` `boolean`:加 bootstrap CI
+- `--bootstrap-samples` `option`:bootstrap 重采样次数，默认 1000
+- `--budget-per-sample-ms` `option`:单 sample 时长上限 ms（必须 > 0，不传则无上限）
+- `--budget-per-sample-usd` `option`:单 sample 预算上限 USD（必须 > 0，不传则无上限）
+- `--budget-usd` `option`:总预算上限 USD（必须 > 0，不传则无上限）
+- `--concurrency` `option`:并发数，默认 1
+- `--config` `option`:eval.yaml 路径
+- `--control` `option`:control variant 表达式（仅 artifact 身份）
+- `--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）。
+- `--gold-dir` `option`:gold dataset 目录
+- `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。
+- `--judge-repeat` `option`:每个 dim 评 N 次
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--layered-stats` `boolean`:输出分层统计
+- `--mcp-config` `option`:MCP 配置文件路径
+- `--model` `option`:被测模型
+- `--no-cache` `boolean`:跳过 executor cache
+- `--no-debias-length` `boolean`:关 length-debias（默认开）
+- `--no-diagnostic` `boolean`:关闭 diagnostic 诊断 LLM 调用（默认开，给 failed sample 出「哪错了 + 怎么改」建议）。
+- `--no-evidence` `boolean`:不把本次评测写成证据追加进受管记录(默认会为已 install 的 skill 自动写)。
+- `--no-gate` `boolean`:关 verdict gate
+- `--no-judge` `boolean`:跳过 LLM judge
+- `--no-serve` `boolean`:不启 report server
+- `--no-strict-baseline` `boolean`:关闭 baseline 隔离
+- `--output-dir` `option`:报告输出目录
+- `--repeat` `option`:每个 sample 重复跑 N 次
+- `--report-only` `boolean`:生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
+- `--resume` `option`:从某次失败 run 续跑
+- `--retry` `option`:失败 sample 重试次数
+- `--samples` `option`:用例文件路径。默认 eval-samples.json，也接受 .yaml/.yml；自动发现 --skill-dir 下的 <skill>/.omk/samples.json。
+- `--skill-dir` `option`:skill 目录，默认 skills
+- `--skip-connectivity` `boolean`:跳 LLM 连通性预检
+- `--skip-doctor` `boolean`:escape hatch:跳 doctor 健康检查门禁（默认强制启用）。沙箱 mock 提供依赖时绕开 doctor 物理路径误报；garbage-in 风险自负。
+- `--strict-baseline` `boolean`:强制 baseline 隔离（default true）
+- `--threshold` `option`:verdict 阈值，默认 3.5
+- `--timeout` `option`:单用例超时秒，默认 600
+- `--treatment` `option`:treatment variant 列表，逗号分隔（仅 artifact 身份）
+- `--treatment-cwd` `option`:treatment 的 runtime context 目录列表，逗号分隔、与 --treatment 按序对齐（空位 = 无 cwd）
+- `--trivial-diff` `option`:可忽略 diff 容差，0 表示不启用容差
+- `--verbose` `boolean`:详细日志
+
+**示例:**
+
+> 最简对照:baseline vs my-skill
+
+```bash
+omk eval --control baseline --treatment my-skill
+```
+
+> eval.yaml 驱动 + bootstrap CI
+
+```bash
+omk eval --config eval.yaml --bootstrap
+```
+
+## omk eval gold
+
+管理 human-gold 标注集（init / validate / compare 三个子命令）。
+
+**用法:**
+
+```bash
+omk eval gold [flags]
+```
+
+**Flags:**
+
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+
+## omk eval gold compare
+
+把一份 evaluation report 跟 gold dataset 对比，计算 bootstrap CI 后的 agreement。
+
+**用法:**
+
+```bash
+omk eval gold compare <reportId> [flags]
+```
+
+**参数:**
+
+- `reportId`(必填):report ID。
+
+**Flags:**
+
+- `--bootstrap-samples` `option`:bootstrap 重采样次数，默认 1000
+- `--gold-dir` `option`:gold dataset 目录，必填
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--reports-dir` `option`:报告目录，默认 ~/.oh-my-knowledge/reports
+- `--seed` `option`:bootstrap seed，可复现
+- `--variant` `option`:只比对指定 variant，默认全比
+
+## omk eval gold init
+
+初始化 gold dataset 目录（human-gold 标注集脚手架）。
+
+**用法:**
+
+```bash
+omk eval gold init [flags]
+```
+
+**Flags:**
+
+- `--annotator` `option`:标注者名，写入 metadata.yaml
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--out` `option` (默认 `./gold-dataset`):输出目录，默认 ./gold-dataset
+
+## omk eval gold validate
+
+校验 gold dataset 目录格式（annotations.yaml schema）。
+
+**用法:**
+
+```bash
+omk eval gold validate <dir> [flags]
+```
+
+**参数:**
+
+- `dir`(必填):gold dataset 目录。
+
+**Flags:**
+
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+
+## omk evolve
+
+自动迭代改进 skill:多轮 eval + skill 重写，直到达到 --target 或耗尽 --rounds。
+
+**用法:**
+
+```bash
+omk evolve <skillPath> [flags]
+```
+
+**参数:**
+
+- `skillPath`(必填):skill 文件或 SKILL.md 路径。
+
+**Flags:**
+
+- `--auto-fix-samples` `boolean`:每轮先修 skill，再修 sample，随后一起评估候选结果
+- `--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
+- `--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
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--model` `option` (默认 `sonnet`):被评测的 LLM，默认 sonnet
+- `--no-diagnostic` `boolean`:关 LLM diagnostic 调用
+- `--no-edit-budget` `boolean`:关掉 edit budget 约束（允许任意大小的单轮改动）
+- `--no-reject-memory` `boolean`:关掉 rejected-edit 记忆（不把被拒改法回灌下一轮 prompt）
+- `--no-significance-gate` `boolean`:关掉显著性接受门，退回「候选分高一点点就收」的点估计判定（默认门开：只收统计显著的提升）
+- `--reuse-latest-eval` `boolean`:复用可比的最新 eval 报告作为 round-0
+- `--rounds` `option` (默认 `5`):最大迭代轮数，默认 5
+- `--sample-fix-max-attempts` `option` (默认 `2`):每条 sample 自动修复最多尝试次数（默认：2）
+- `--samples` `option` (默认 `eval-samples.json`):用例文件路径，默认 eval-samples.json
+- `--significance-alpha` `option` (默认 `0.05`):显著性门的 diff CI 显著性水平（默认 0.05 = 95% CI）
+- `--skip-connectivity` `boolean`:跳过 LLM 连通性预检
+- `--skip-doctor` `boolean`:跳过 doctor 门禁（escape hatch，自负 garbage-in 风险）
+- `--stop-on-assertions-pass` `boolean`:普通用例断言全过时提前停止
+- `--target` `option`:目标 composite 分数，达到即停。不传则跑满 rounds
+- `--test-ratio` `option` (默认 `0`):锁定 test 集比例（0..1，默认 0=关），需配 --holdout-ratio。全程不参与选择，收尾读一次给无偏泛化分
+- `--timeout` `option` (默认 `600`):单用例超时秒，默认 600
+
+**示例:**
+
+> 默认 5 轮迭代
+
+```bash
+omk evolve skills/my-skill/SKILL.md
+```
+
+> 指定目标分 + 自定义模型
+
+```bash
+omk evolve skills/my-skill/SKILL.md --target 4.5 --model opus --improve-model opus
+```
+
+## omk init
+
+初始化 omk 项目脚手架（skills/ + eval-samples.json 模板）。
+
+**用法:**
+
+```bash
+omk init [targetDir] [flags]
+```
+
+**参数:**
+
+- `targetDir`(可选):初始化目标目录，默认当前目录（.）
+
+**Flags:**
+
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+
+**示例:**
+
+> 在当前目录初始化
+
+```bash
+omk init
+```
+
+> 在指定目录初始化
+
+```bash
+omk init my-project
+```
+
+## omk install
+
+安装 omk 官方 Agent Skill，或登记并分发用户自己的 skill（内置 id omk-agent-skill，本地路径，或 git:<ref>:<name> 取当前仓库某个 ref 的 skill）。默认写入本机已检测 agent 目标；安装用户 skill 时同时登记一条受管记录。
+
+**用法:**
+
+```bash
+omk install <input> [flags]
+```
+
+**参数:**
+
+- `input`(必填):要安装的知识输入：内置 id omk-agent-skill，本地 skill 路径（目录或 .md），或 git:<ref>:<name>（当前仓库某 ref 的 skill）。
+
+**Flags:**
+
+- `--dest` `option`:自定义 skill 根目录；skill 安装到 <dir>/<name>（内置 omk-agent-skill 为 <dir>/omk）。
+- `--dry-run` `boolean`:只打印安装目标，不写文件。
+- `--force` `boolean`:覆盖目标位置已存在的 skill。
+- `--git-ref` `option`:远端 git 的 ref（分支 / tag / SHA），默认 HEAD。仅配合 --git-url 使用。
+- `--git-url` `option`:远端 git 仓库 URL（https / ssh / git@host:path）。给了它时，位置参数当作仓库内 skill 路径（spec）。
+- `--kind` `skill|prompt|agent|workflow`:用户 artifact 的 kind（对齐 Artifact.kind）。可省：命中 SKILL.md 自动推导，当前仅支持 skill。
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--to` `option` (默认 `auto`):安装目标：auto（默认，本机已检测目标） / codex / claude / all。
+
+**示例:**
+
+> 安装 omk 官方 Agent Skill 到默认本机目标
+
+```bash
+omk install omk-agent-skill
+```
+
+> 强制安装到当前 omk 已知的所有目标
+
+```bash
+omk install omk-agent-skill --to all
+```
+
+> 安装到自定义 skill 根目录
+
+```bash
+omk install omk-agent-skill --dest ~/.my-agent/skills
+```
+
+> 登记并分发用户自己的 skill（--kind 可省，命中 SKILL.md 自动推导）
+
+```bash
+omk install ./skills/review
+```
+
+> 从当前仓库某个 ref 安装 skill（可复现；SHA 不可变、分支会随 ref 漂移）
+
+```bash
+omk install git:main:skills/review
+```
+
+> 从远端 git 仓库安装 skill（位置参数是仓库内路径；认证用本机 git 凭证；记录钉实际 SHA）
+
+```bash
+omk install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/review
+```
+
+## omk observe
+
+分析 sessions 目录的 skill 调用健康度（默认行为）。子命令:ingest / inbox / show。
+
+**用法:**
+
+```bash
+omk observe [sessionsDir] [flags]
+```
+
+**参数:**
+
+- `sessionsDir`(可选):sessions 目录路径（如 ~/.claude/sessions）
+
+**Flags:**
+
+- `--from` `option`:起始时间 ISO，优先级高于 --last
+- `--kb` `option`:知识库 root，启用 KB-aware 分析
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--last` `option`:时间窗(7d / 24h / 30m）
+- `--output-dir` `option`:分析结果输出目录
+- `--skills` `option`:只看指定 skill，逗号分隔
+- `--to` `option`:结束时间 ISO
+
+**示例:**
+
+> 分析最近 7 天
+
+```bash
+omk observe ~/.claude/sessions --last 7d
+```
+
+## omk observe inbox
+
+查询 observation inbox(skill 调用洞察）。
+
+**用法:**
+
+```bash
+omk observe inbox [flags]
+```
+
+**Flags:**
+
+- `--by-skill` `boolean`:按 skill 聚合输出
+- `--executor` `option`:LLM 增强复盘使用的执行器
+- `--explore` `option`:抽样 N 条 medium/low 长尾（replaces limit）
+- `--include-noise` `boolean`:explore 时也包含 noise 桶
+- `--input-dir` `option`:inbox 数据目录，默认 .omk/observations（项目级，相对于 cwd）；目录不存在时兜底读 ~/.oh-my-knowledge/observations。
+- `--json` `boolean`:JSON 格式输出
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--limit` `option`:限制条数，默认 20
+- `--llm-enhanced-review` `boolean`:显式调用模型进行链路增强复盘，包含标准抽取、目标判断、类型判断、产物匹配和 owner 建议
+- `--model` `option`:LLM 增强复盘使用的模型，默认 sonnet
+- `--refresh` `boolean`:重新生成 LLM 增强复盘，不复用已有结果
+- `--skill` `option`:只看指定 skill
+
+## omk observe ingest
+
+把 trace 目录 ingest 成 observation inbox 报告。
+
+**用法:**
+
+```bash
+omk observe ingest <traceDir> [flags]
+```
+
+**参数:**
+
+- `traceDir`(必填):trace 目录路径。
+
+**Flags:**
+
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--output-dir` `option`:输出目录，默认 .omk/observations（项目级，相对于 cwd）。
+
+## omk observe show
+
+展开 observation inbox 中某条 item 的详情。
+
+**用法:**
+
+```bash
+omk observe show <inboxId> [flags]
+```
+
+**参数:**
+
+- `inboxId`(必填):inbox item ID。
+
+**Flags:**
+
+- `--input-dir` `option`:inbox 数据目录
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+
+## omk sample
+
+为指定 skill 生成评测用例（eval-samples），支持 batch / single / fix / from-traces 四种模式。
+
+**用法:**
+
+```bash
+omk sample [skillPath] [flags]
+```
+
+**参数:**
+
+- `skillPath`(可选):skill 文件路径或 SKILL.md 路径。batch 模式不需要；single / fix 模式必填。
+
+**Flags:**
+
+- `--batch` `boolean`:批量模式：扫 --skill-dir 下所有缺 samples 的 skill，逐个生成。
+- `--count` `option`:生成用例条数。不传由 LLM 按 skill 类型自动决定。
+- `--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。
+- `--no-mock` `boolean`:不生成 mocks，eval 时所有工具调用真实执行。
+- `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observations。
+- `--reports-dir` `option`:报告目录（fix 模式用），默认 ~/.oh-my-knowledge/reports。
+- `--skill-dir` `option` (默认 `skills`):skill 根目录，默认 skills。batch 模式扫此目录。
+- `--treatment` `option`:指定 treatment 名（fix 模式用），默认推断自 skill 路径。
+
+**示例:**
+
+> 为单个 skill 生成默认数量的用例
+
+```bash
+omk sample skills/my-skill/SKILL.md
+```
+
+> 批量为 skill 目录下所有缺 samples 的 skill 生成
+
+```bash
+omk sample --batch --skill-dir skills
+```
+
+> 根据最近评测报告自动修复 sample_design 类型失败
+
+```bash
+omk sample skills/my-skill/SKILL.md --fix
+```
+
+> 从 observe inbox 的失败信号回流生成回归用例草稿
+
+```bash
+omk sample --from-traces
+```
+
+## omk studio
+
+启动 omk Studio 报告服务（skill-centric 仪表盘 + 浏览器自动打开）。
+
+**用法:**
+
+```bash
+omk studio [flags]
+```
+
+**Flags:**
+
+- `--analyses-dir` `option`:分析数据目录（可选）
+- `--dev` `boolean`:dev 模式：子进程启动 + 热更新
+- `--host` `option`:监听 host，默认 localhost。改为 0.0.0.0 暴露给局域网
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--no-open` `boolean`:不自动打开浏览器
+- `--observations-dir` `option`:观测数据目录（可选）
+- `--port` `option` (默认 `7799`):监听端口，默认 7799。传 0 让 OS 分配
+- `--reports-dir` `option`:报告目录，默认 ~/.oh-my-knowledge/reports
+
+**示例:**
+
+> 默认端口 7799
+
+```bash
+omk studio
+```
+
+> 指定端口，不打开浏览器
+
+```bash
+omk studio --port 8080 --no-open
+```
+<!-- omk:cli:end -->
+
+## eval-samples 字段参考
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `sample_id` | 是 | 唯一标识 |
+| `prompt` | 是 | 用户提示词 |
+| `context` | 否 | 附加上下文（代码片段等） |
+| `cwd` | 否 | executor 工作目录，用于指定目标仓库路径 |
+| `rubric` | 否 | LLM 评分标准 |
+| `assertions` | 否 | 断言数组（含 `mock_hit` 等新 v0.30 类型） |
+| `dimensions` | 否 | 多维度评分 `{ 维度名: 评分标准 }` |
+| `capability` | 否 | 能力标签（HF Dataset Cards 风） |
+| `difficulty` | 否 | 难度等级 |
+| `construct` | 否 | 测的是什么构念 |
+| `provenance` | 否 | 用例来源（`omk sample` 自动打） |
+| `mocks` | 否 | 工具调用 mock 返回（sandbox 评测） |
+| `environment` | 否 | 评测环境前置「已就绪」声明 |
+| `tripwire` | 否 | 标记为「故意诱错」样本，failed 时 diagnostic 不建议改 skill |
+
+完整 schema 见 [docs/specs/sample-design-spec.md](https://github.com/lizhiyao/oh-my-knowledge/blob/main/docs/specs/sample-design-spec.md)。