oh-my-knowledge 1.0.0-beta.12 → 1.0.0-beta.14

package/README.md

@@ -1,163 +1,54 @@
 # OMK
 
-[![npm version](https://img.shields.io/npm/v/oh-my-knowledge.svg)](https://www.npmjs.com/package/oh-my-knowledge)
-[![npm weekly downloads](https://img.shields.io/npm/dw/oh-my-knowledge.svg)](https://www.npmjs.com/package/oh-my-knowledge)
+[![Beta @next](https://img.shields.io/npm/v/oh-my-knowledge/next.svg?label=Beta)](https://www.npmjs.com/package/oh-my-knowledge?activeTab=versions)
 [![CI](https://github.com/lizhiyao/oh-my-knowledge/actions/workflows/ci.yml/badge.svg)](https://github.com/lizhiyao/oh-my-knowledge/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Node.js Version](https://img.shields.io/node/v/oh-my-knowledge.svg)](https://nodejs.org)
 
 **English** | [简体中文](./README.zh.md)
 
-**Observe. Measure. Know.** Make knowledge changes in your AI application evidence-backed.
+**Observe. Measure. Know.** Turn working experience into knowledge you can keep maintaining.
 
-OMK is a toolkit for observing, evaluating, and improving knowledge in AI applications. Inspect how real tasks ran, extract reviewable knowledge items from work logs, and measure changes to prompts, RAG, skills, agents, or workflows to inform adoption, rollback, and further improvement.
+OMK is for agent users and AI application developers. Extract candidates from real work, review sources and conditions, accumulate and revise knowledge around objects, then update the skills or prompts that reference it. When you need evidence about a change, compare artifact versions under controlled conditions independently.
 
-**Observe** preserves real behavior and its sources. **Measure** compares knowledge artifacts with the same model, cases, and execution conditions. **Know** connects decisions back to evidence. If you already have two artifact versions, start directly with evaluation; logs are not a prerequisite.
+## Start with local work records
 
-Version 1.0 is still **in Beta iteration**; APIs and storage contracts may change. Read the [migration guide](docs/guides/v1-preview-migration.md) before upgrading an older installation.
-
-![OMK: from controlled evaluation to real-world feedback](./docs/public/omk-knowledge-flow-en-animated.gif)
-
-## Choose how to use OMK
-
-| Interface | Use it for |
-|---|---|
-| **CLI** | Run checks, evaluations, observation, and improvement workflows from a terminal, coding agent, or CI |
-| **Studio** | Browse task trajectories, review knowledge items, and inspect reports and source evidence in a local workbench |
-| **eval-runtime** | Embed execution, scoring, and version comparison in your Node.js service or platform, without going through the CLI or starting Studio |
-| **DSH plugin** | Use `/omk eval` and `/omk observe` inside DeepSeek Harness with the current profile’s model, credentials, tools, and sandbox; see [host plugin setup](docs/reference/executors.md#deepseek-harness-prefer-the-host-plugin) |
-
-## Start with your goal
-
-| Goal | Entry point | What you get |
-|---|---|---|
-| Understand a real task | [Studio and task trajectories](docs/guides/observe-production.md) | Conversation, execution, results, and knowledge lanes with inspectable source records |
-| Preserve knowledge from work | [Extract knowledge from logs](docs/guides/extract-knowledge.md) | Candidate knowledge with sources and conditions; revise, retain, or discard it |
-| Record a confirmed knowledge problem | [MCP feedback](docs/guides/mcp-integration.md) | An observation for review; draft a case after confirming a real issue |
-| Decide whether to adopt a change | [Evaluation quickstart](docs/quickstart-skill-eval.md) | A version decision, uncertainty, failed cases, and scoring evidence |
-| Try improving a skill automatically | [Iterative improvement](docs/guides/auto-improve-skills.md) | Candidate versions screened through controlled comparisons |
-| Embed evaluation in a service or platform | [Node.js service](docs/guides/eval-runtime.md) · [Platform host](docs/guides/platform-host-integration.md) | Composable execution, scoring, and comparison interfaces |
-
-## Quick start
-
-Installation requires Node.js >=22. Model calls also require an authenticated runtime; see [Requirements](#requirements).
+Requires **Node.js ≥22**. The library, artifact authoring, and change review described here require **1.0.0-beta.14 or later**, from the **`@next` channel**; npm `latest` is a separate stable channel. Beta.13 does not include this maintenance UI. Read the [migration guide](docs/guides/maintenance/v1-preview-migration.md) before upgrading an older installation.
 
 ```bash
 npm i -g oh-my-knowledge@next
-```
-
-### Inspect an existing task
-
-```bash
+omk --version
 omk studio
 ```
 
-Open the local URL returned by the command and select a local Codex conversation to inspect its task trajectory. No prior ingest or model call is needed; active tasks support live following. Claude Code, OpenClaw, and markdown logs enter observation reports through `omk observe`; see the [observation guide](docs/guides/observe-production.md).
+Open the local URL returned by the command and inspect an existing Codex task and its source records. This step makes no model call; Studio offers source and collection guidance when no conversations exist. Follow the [observation guide](docs/guides/observe/observe-production.md) for other log sources.
 
-To preserve reusable knowledge, choose “Extract knowledge from work logs” on the knowledge page. Select a workspace and a Codex log excerpt, inspect the source, then generate candidates. Generation calls a model. Retaining a candidate means you intend to maintain it, not that it is verified; it does not automatically update AGENTS.md or skills. See the [extraction guide](docs/guides/extract-knowledge.md).
+Next, choose a conversation and turns under “Knowledge → Candidate review”, inspect the material to send, and extract candidates. **Extraction calls a model**, so prepare an [authenticated runtime](docs/reference/integration/executors.md#prerequisites) first. Link sources in the library, revise outdated content, then explicitly generate and save an artifact. Its detail view lets you review knowledge changes and old and new references. Follow the [knowledge maintenance workflow](docs/guides/knowledge/extract-knowledge.md).
 
-### Or compare two skills directly
+## When knowledge changes, review its artifacts
 
-```bash
-omk init demo
-cd demo
-omk eval --control code-review-v1 --treatment code-review-v2 --dry-run
-```
+![SDK historical artifact changes in the Studio reader, captured from the Chinese case](./docs/public/sdk-maintenance-review.png)
 
-After checking the plan and estimated calls, run the evaluation (this calls the model):
+In the existing SDK maintenance case, old statements were limited to their historical context, one item was discarded, and another gained a clearer boundary for its static observations. v4 retains three historical references and shows two changes; v5 explicitly selects two currently retained items, while old content and references remain available. [Read the case, sources, and review steps](docs/guides/knowledge/sdk-maintenance-case.md).
 
-```bash
-omk eval --control code-review-v1 --treatment code-review-v2
-```
+This verifies maintenance and reference behavior. It does not verify dynamic SDK effects, time saved, or cross-agent reuse benefits. Retaining knowledge, saving artifacts, using them, and verifying effects are separate records. Complete automatic management and reuse across agents remain in development.
 
-The scaffold contains two skills and three cases. This small default set checks the workflow; `UNDERPOWERED` is expected. Starter cases are marked `llm-generated`. Even the full pack created with `omk init demo-full --samples 20` only meets the default heuristic evidence floor, not an a priori power plan or a release-evidence requirement. Review and replace starter cases with real domain cases before relying on the results.
+## Continue with your task
 
-The [full walkthrough](docs/quickstart-skill-eval.md) covers runtime selection, your own skills, and interpreting results. The [example gallery](examples/README.md) offers more runnable scenarios.
+- **Compare two artifacts directly**: preview the plan in the [evaluation quickstart](docs/quickstart-skill-eval.md), configure a runtime, then call the model. Fix models and cases, record execution conditions, and inspect decisions, uncertainty, and failed-case evidence.
+- **Embed evaluation in a service**: begin with the [offline Node example](docs/guides/integration/eval-runtime.md), complete a traceable comparison, then choose models and configuration as needed.
+- **Use OMK inside agents or DSH**: [install the official Skill](docs/quickstart-skill-eval.md#use-inside-an-agent), [submit MCP feedback](docs/guides/integration/mcp-integration.md), or use the [DSH host plugin](docs/reference/integration/executors.md#deepseek-harness-prefer-the-host-plugin).
+- **Verify an agent’s file changes**: use independent checks in [local task acceptance](docs/guides/evaluation/local-tasks.md), or screen candidate versions with [iterative improvement](docs/guides/evaluation/auto-improve-skills.md).
 
-## Use inside agents and DSH
+Starter cases check the workflow; `UNDERPOWERED` is expected. Release decisions need your own domain cases and independent evidence. Observation signals do not establish causality; passing an evaluation does not mean an artifact took effect or a version was published.
 
-### Agent Skill and MCP
+## Look up details and upgrade
 
-```bash
-omk install omk-agent-skill
-```
+[Documentation start](docs/README.md) · [Website](https://oh-my-knowledge.pages.dev/) · [CLI](docs/reference/cli.md) · [Runtimes and executors](docs/reference/integration/executors.md) · [Settings and environment variables](docs/reference/shared/settings.md) · [Examples](examples/README.md)
 
-Install the Skill, then ask your coding agent: “Use omk to compare these two skills; preview the plan first.” See the [quickstart](docs/quickstart-skill-eval.md#use-inside-an-agent) for installation targets and usage.
-
-The [MCP integration](docs/guides/mcp-integration.md) accepts user-authorized knowledge feedback. It records partial evidence submitted at its tool boundary; it does not automatically monitor complete conversations.
-
-### DeepSeek Harness plugin
-
-If you already use DSH, add OMK to an existing profile. For example, use the command-enabled `web` profile:
-
-```bash
-dsh plugin --profile web add oh-my-knowledge
-dsh --profile web
-```
-
-Inside DSH, run:
-
-```text
-/omk eval eval.yaml
-/omk observe
-/omk observe <session-id>
-```
-
-Evaluation reuses the host’s model, credentials, tools, and sandbox, creating an isolated session for each case. Observation reads snapshots of completed sessions and returns a Studio task-trajectory URL; it does not currently live-follow running DSH sessions. See [DSH integration](docs/reference/executors.md#deepseek-harness-prefer-the-host-plugin) for configuration requirements and current plugin limitations.
-
-## Use the evidence
-
-A knowledge item is a reviewable fact, experience, or method. An artifact is a prompt, document, skill, or other carrier of that content. Candidate knowledge describes content awaiting review; a candidate version describes a proposed artifact version.
-
-1. **Observe and review**: inspect tasks and sources in Studio; extract knowledge or confirm observations, preserving conditions and review reasons.
-2. **Prepare a measurable change**: manually apply selected content to an artifact and turn reproducible problems into evaluation cases. Candidates do not take effect automatically.
-3. **Compare under control**: `doctor` performs preflight checks; `eval` compares control and treatment with a Decision, coverage, failed cases, and costs.
-4. **Adopt or improve further**: use evidence to `promote` or `rollback` managed skills. `evolve` screens candidate versions through A/B gates and compares again before writing back.
-
-These paths compose; they are not a mandatory linear state machine. Passing an evaluation does not mean knowledge has been written or a version published.
-
-Conclusions depend on the cases, scoring criteria, and execution environment. Observation signals are not causal conclusions, and generated cases are not an independent release-validation set. See [statistical rigor](docs/explanation/statistical-rigor.md) and the [three-stage workflow](docs/explanation/three-stage-workflow.md) for the method and limits.
-
-Project evaluation and observation evidence lives under `.omk/`; machine-level state lives under `~/.oh-my-knowledge/`. Extracted knowledge items live in the explicitly selected knowledge workspace. The current version neither reads nor migrates the old storage layout. Back up before upgrading and follow the [migration guide](docs/guides/v1-preview-migration.md) to establish new evidence.
-
-## Documentation
-
-[Documentation index](docs/README.md) · [Online docs](https://oh-my-knowledge.pages.dev) · [CLI reference](docs/reference/cli.md) · [Sample format](docs/reference/eval-sample-format.md) · [Executors](docs/reference/executors.md) · [How OMK understands knowledge](docs/explanation/knowledge.md)
-
-## Environment variables
-
-| Variable | Description |
-|---|---|
-| `OMK_EXECUTOR` | default executor preference, e.g. `codex` / `codex-sdk` / `claude` |
-| `OMK_MODEL` | default evaluated model; Codex reads local `config.toml` when unset |
-| `OMK_JUDGE_MODELS` | default judge list in `executor:model[,...]` format |
-| `CCV_PROXY_URL` | proxy requests through cc-viewer for live eval-traffic visualization |
-| `OMK_REPORT_PORT` | report server port (default: 7799) |
-
-## Requirements
-
-- Node.js >= 22
-- At least one authenticated model runtime:
-  - Codex: install and authenticate the Codex CLI (`npm i -g @openai/codex`); Codex tasks in the ChatGPT desktop app select it automatically
-  - Claude: install and authenticate [Claude Code](https://claude.ai/code)
-  - API / other executors: configure them as described in [Executors](docs/reference/executors.md)
-- Advanced `claude-sdk` / `codex-sdk` executors are optional and are not downloaded by the base OMK install. Install the matching SDK in the same local project or global npm prefix only when you select one; see [Executor prerequisites](docs/reference/executors.md#prerequisites).
+Beta APIs and storage contracts may change. Knowledge stays in the explicitly selected workspace; execution evidence and machine preferences have their own storage scopes. Back up before upgrading, then establish new evidence through the migration guide.
 
 ## Security notice
 
-This tool is designed for **local trusted environments** (dev machines, CI pipelines). The following features execute local code — make sure inputs come from a trusted source:
-
-| Feature | Risk | Scope |
-|---|---|---|
-| **Custom assertions** (`custom`) | dynamically loads and executes user-specified `.mjs` files | only use assertion files you authored or reviewed |
-| **eval-samples.json** | assertion configs can reference external file paths | don't use sample files from untrusted sources |
-
-**Recommendations:**
-
-- Do not expose the local report server on the public internet (no auth)
-- Don't use third-party eval-samples you haven't vetted
-- Custom assertions have a 30-second timeout but no sandbox isolation
-
----
+Use a trusted local environment. Tasks, verifiers, and custom assertions execute local code and should be reviewed first; workspace copies are not security sandboxes. Inspect the material before a model call: source records and artifacts may contain sensitive information. The local report server has no authentication and should not be exposed publicly.
 
-See [GitHub Releases](https://github.com/lizhiyao/oh-my-knowledge/releases) for release notes. Contributions welcome — see [CONTRIBUTING](./CONTRIBUTING.md).
+See [GitHub Releases](https://github.com/lizhiyao/oh-my-knowledge/releases) for release notes and [CONTRIBUTING](./CONTRIBUTING.md) for the contribution workflow.

package/README.zh.md

@@ -1,163 +1,54 @@
 # OMK
 
-[![npm version](https://img.shields.io/npm/v/oh-my-knowledge.svg)](https://www.npmjs.com/package/oh-my-knowledge)
-[![npm weekly downloads](https://img.shields.io/npm/dw/oh-my-knowledge.svg)](https://www.npmjs.com/package/oh-my-knowledge)
+[![Beta @next](https://img.shields.io/npm/v/oh-my-knowledge/next.svg?label=Beta)](https://www.npmjs.com/package/oh-my-knowledge?activeTab=versions)
 [![CI](https://github.com/lizhiyao/oh-my-knowledge/actions/workflows/ci.yml/badge.svg)](https://github.com/lizhiyao/oh-my-knowledge/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Node.js Version](https://img.shields.io/node/v/oh-my-knowledge.svg)](https://nodejs.org)
 
 [English](./README.md) | **简体中文**
 
-**Observe. Measure. Know.** 让 AI 应用的知识改动有据可依。
+**Observe. Measure. Know.** 把工作中的经验，沉淀为可持续维护的知识。
 
-OMK 是面向 AI 应用作者与维护者的知识观测、评测与改进工具体系。查看真实任务如何执行，从工作日志提炼可复核的知识内容，再测量 prompt、RAG、skill、agent 或 workflow 的载体改动是否有效，为采纳、回退和继续改进提供证据。
+OMK 面向 Agent 使用者和 AI 应用开发者。从真实工作记录中提炼候选，核对来源与适用条件，围绕对象持续积累和修订，再更新引用它们的 skill 或 prompt。需要判断改动效果时，可以独立开展受控版本比较。
 
-**Observe** 保留真实表现与来源，**Measure** 在相同模型、用例与运行条件下比较知识载体，**Know** 让决定可以回到证据核对。已有两版载体时，可以直接开始评测；不必先收集日志。
+## 从本地工作记录开始
 
-当前 1.0 仍处于 **Beta 迭代期**，接口与存储契约可能继续变化。从旧版本升级前，请先阅读[迁移指南](docs/zh/guides/v1-preview-migration.md)。
-
-![OMK：从受控评测到真实使用反馈](./docs/public/omk-knowledge-flow-animated.gif)
-
-## 选择使用方式
-
-| 入口 | 适合什么场景 |
-|---|---|
-| **CLI** | 在终端、coding agent 或 CI 中执行检查、评测、观测与迭代工作流 |
-| **Studio** | 在本地工作台浏览任务轨迹、复核知识内容，查看报告与原始证据 |
-| **eval-runtime** | 通过 Node.js API 将执行、评分与版本比较嵌入自己的服务或平台；无需通过 CLI 或启动 Studio |
-| **DSH 插件** | 在 DeepSeek Harness 内用 `/omk eval` 和 `/omk observe`，复用当前 profile 的模型、凭证、工具与 sandbox；见[宿主插件接入](docs/zh/reference/executors.md#deepseek-harness-优先使用宿主插件) |
-
-## 从你的目标开始
-
-| 想做什么 | 入口 | 得到什么 |
-|---|---|---|
-| 看清一次真实任务 | [Studio 与任务轨迹](docs/zh/guides/observe-production.md) | 对话、执行、结果、知识四条泳道，以及可核对的原始记录 |
-| 把工作经验沉淀为知识 | [从日志提炼知识](docs/zh/guides/extract-knowledge.md) | 带来源和适用条件的候选知识，支持修订、保留和舍弃 |
-| 记录已确认的知识问题 | [MCP 主动反馈](docs/zh/guides/mcp-integration.md) | 待复核 observation；确认真实问题后再草拟用例 |
-| 判断一版改动是否值得采用 | [评测快速上手](docs/zh/quickstart-skill-eval.md) | 版本判定、不确定性、失败用例和评分依据 |
-| 自动尝试改进 skill | [迭代改进](docs/zh/guides/auto-improve-skills.md) | 经受控比较筛选的候选版本 |
-| 将评测接入服务或平台 | [Node.js 服务](docs/zh/guides/eval-runtime.md) · [平台宿主](docs/zh/guides/platform-host-integration.md) | 可组合的执行、评分与比较接口 |
-
-## 快速开始
-
-安装需要 Node.js >=22。调用模型前还需配置已认证的 runtime，详见[系统要求](#系统要求)。
+需要 **Node.js ≥22**。本页的知识库、载体生成与变化核对需要 **1.0.0-beta.14 或更新版本**，使用 **`@next` 通道**；npm 的 `latest` 是另一条稳定通道。Beta.13 不包含这里的维护界面。旧版用户先阅读[迁移指南](docs/zh/guides/maintenance/v1-preview-migration.md)。
 
 ```bash
 npm i -g oh-my-knowledge@next
-```
-
-### 先看已有任务
-
-```bash
+omk --version
 omk studio
 ```
 
-打开命令返回的本地地址，从本机 Codex 对话进入任务轨迹；无需先 ingest，也不调用模型。进行中的任务支持实时跟随。Claude Code、OpenClaw 与 markdown 日志通过 `omk observe` 进入观测报告，见[观测指南](docs/zh/guides/observe-production.md)。
+打开命令返回的本地地址，从已有 Codex 对话核对任务与原始记录。这一步不调用模型；没有对话时，Studio 提供来源与采集入口。其他日志来源按[观测指南](docs/zh/guides/observe/observe-production.md)接入。
 
-需要沉淀经验时，在知识页面选择“从工作日志提炼知识”，选定工作区与 Codex 日志片段，核对来源后再生成。生成会调用模型；保留候选表示愿意维护，不等于已证实，也不会自动写入 AGENTS.md 或 skill。步骤见[提炼指南](docs/zh/guides/extract-knowledge.md)。
+接下来，在“知识 → 候选核对”选择会话和轮次，核对发送范围后提炼候选。**提炼会调用模型**，需先准备[已认证的运行时](docs/zh/reference/integration/executors.md#前置要求)。在知识库关联来源、修订过时内容，再明确生成和保存载体；载体详情可核对知识变化和新旧引用。完整步骤见[知识维护动线](docs/zh/guides/knowledge/extract-knowledge.md)。
 
-### 或者，直接比较两版 skill
+## 知识变化，载体也需要核对
 
-```bash
-omk init demo
-cd demo
-omk eval --control code-review-v1 --treatment code-review-v2 --dry-run
-```
+![Studio 中 SDK 历史载体的知识变化核对阅读区](./docs/public/sdk-maintenance-review.png)
 
-检查计划和预估调用次数后，执行评测（会调用模型）：
+在已有 SDK 维护案例中，旧说法限定为历史场景，一条不再适用的知识被舍弃，另一条补充了静态观察的范围。v4 保留三条旧引用并提示两项变化；v5 明确选择两条当前保留知识，旧版本正文与引用继续保留。[查看案例、来源和核对步骤](docs/zh/guides/knowledge/sdk-maintenance-case.md)。
 
-```bash
-omk eval --control code-review-v1 --treatment code-review-v2
-```
+这证明维护与引用链路可核对，没有验证 SDK 动态效果、节省时间或跨 Agent 复用收益。保留知识、保存载体、实际使用和验证效果分别记录；完整跨 Agent 自动管理与复用仍在建设中。
 
-脚手架包含两版 skill 和三条用例。默认小样本用于检查流程，出现 `UNDERPOWERED` 符合预期。官方起步用例标记为 `llm-generated`；即使用 `omk init demo-full --samples 20` 创建完整起步集，也只是达到默认启发式证据下限，不等于完成功效规划或具备发布证据。实际使用前应人工复核并替换为真实领域用例。
+## 按当前任务继续
 
-[完整教程](docs/zh/quickstart-skill-eval.md)介绍模型选择、换成自己的 skill 和结果解读；[示例画廊](examples/README.zh.md)提供更多可运行场景。
+- **直接比较两版载体**：从[评测快速上手](docs/zh/quickstart-skill-eval.md)预览计划，配置运行时后再调用模型。固定模型与用例，记录运行条件，核对判定、不确定性和失败证据。
+- **嵌入自己的服务**：从[离线 Node 示例](docs/zh/guides/integration/eval-runtime.md)开始，完成第一轮可回查的比较，再按需选择模型与配置。
+- **在 Agent 或 DSH 中使用**：[安装官方 Skill](docs/zh/quickstart-skill-eval.md#在-agent-中使用)、[MCP 主动反馈](docs/zh/guides/integration/mcp-integration.md)和[DSH 宿主插件](docs/zh/reference/integration/executors.md#deepseek-harness-优先使用宿主插件)各有独立入口。
+- **验收 Agent 修改的文件**：使用[本地任务验收](docs/zh/guides/evaluation/local-tasks.md)的独立检查；用[迭代改进](docs/zh/guides/evaluation/auto-improve-skills.md)筛选候选版本。
 
-## 在 Agent 与 DSH 中使用
+入门用例只检查流程，`UNDERPOWERED` 符合预期。真实发布判断需要自己的领域用例和独立证据；观测信号不能证明因果，一次评测通过也不等于载体已经生效或版本已发布。
 
-### Agent Skill 与 MCP
+## 查阅与升级
 
-```bash
-omk install omk-agent-skill
-```
+[文档入口](docs/zh/README.md) · [官网](https://oh-my-knowledge.pages.dev/zh/) · [CLI](docs/zh/reference/cli.md) · [运行时与执行器](docs/zh/reference/integration/executors.md) · [配置与环境变量](docs/zh/reference/shared/settings.md) · [示例](examples/README.zh.md)
 
-安装 Skill 后，可以对 coding agent 说：“用 omk 比较这两版 skill，先预览计划。”安装目标与使用方法见[快速上手](docs/zh/quickstart-skill-eval.md#在-agent-中使用)。
-
-[MCP 集成](docs/zh/guides/mcp-integration.md)提供用户授权的主动知识反馈入口。它仅记录提交到工具边界的部分证据，不自动监听完整对话。
-
-### DeepSeek Harness 插件
-
-已有 DSH 环境时，把 OMK 加入现有 profile。以支持命令适配的 `web` profile 为例：
-
-```bash
-dsh plugin --profile web add oh-my-knowledge
-dsh --profile web
-```
-
-在 DSH 内执行：
-
-```text
-/omk eval eval.yaml
-/omk observe
-/omk observe <session-id>
-```
-
-评测复用当前宿主的模型、凭证、工具和 sandbox，并为每条用例创建隔离 session。观测读取已结束 session 的快照并返回 Studio 任务轨迹地址；目前不实时跟随正在运行的 DSH session。配置要求与插件当前限制见[DSH 接入](docs/zh/reference/executors.md#deepseek-harness-优先使用宿主插件)。
-
-## 如何使用证据
-
-知识内容是一条可复核的事实、经验或方法；知识载体是承载内容的 prompt、文档、skill 等。候选知识是内容的待复核状态，候选版本是拟采用的载体版本，两者不能混为一谈。
-
-1. **观测与复核**：在 Studio 核对任务与来源；提炼知识或确认 observation，留下适用条件和处理理由。
-2. **形成可测改动**：人工把需要采纳的内容落实到载体，把可复现的问题整理为正式用例；候选不会自动生效。
-3. **受控比较**：`doctor` 做前置检查，`eval` 比较 control 与 treatment，检查 Decision、覆盖、失败样本与成本。
-4. **采纳或继续改进**：受管 skill 可按证据 `promote`／`rollback`；`evolve` 通过 A/B 门禁筛选候选版本，写回前再次比较。
-
-这是可组合的工作路径，不是强制的单向状态机。一次评测通过也不等于知识已写入或版本已发布。
-
-结论受用例、评分准则和执行环境约束。观测信号不等于因果结论，生成的样本也不能直接充当独立发布验证集。原理与限制见[统计严谨性](docs/zh/explanation/statistical-rigor.md)和[三阶段工作流](docs/zh/explanation/three-stage-workflow.md)。
-
-项目评测与观测证据保存在 `.omk/`，机器级状态位于 `~/.oh-my-knowledge/`；提炼的知识内容保存在显式选择的知识工作区。当前版本不读取或迁移旧存储布局；升级前备份，按[迁移指南](docs/zh/guides/v1-preview-migration.md)重新建立证据。
-
-## 文档
-
-[完整文档与导航](docs/zh/README.md) · [在线文档](https://oh-my-knowledge.pages.dev/zh/) · [CLI 参考](docs/zh/reference/cli.md) · [用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [OMK 如何理解知识](docs/zh/explanation/knowledge.md)
-
-## 环境变量
-
-| 变量 | 说明 |
-|------|------|
-| `OMK_EXECUTOR` | 默认执行器偏好，例如 `codex` / `codex-sdk` / `claude` |
-| `OMK_MODEL` | 默认被测模型；Codex 未设置时读取本机 `config.toml` |
-| `OMK_JUDGE_MODELS` | 默认评委列表，格式 `executor:model[,...]` |
-| `CCV_PROXY_URL` | 通过 cc-viewer 代理请求，实时可视化评测流量 |
-| `OMK_REPORT_PORT` | 报告服务端口（默认 7799） |
-
-## 系统要求
-
-- Node.js >= 22
-- 至少一个已认证的模型 runtime：
-  - Codex：安装并登录 Codex CLI（`npm i -g @openai/codex`）；ChatGPT desktop 的 Codex 任务会自动选择它
-  - Claude：安装并登录 [Claude Code](https://claude.ai/code)
-  - API / 其它执行器：按[执行器文档](docs/zh/reference/executors.md)配置
-- 高级 `claude-sdk`／`codex-sdk` 执行器是可选能力，OMK 基础安装不再下载它们。仅在明确选择对应 SDK 时，才在 OMK 所在的本地项目或全局 npm prefix 安装；详见[执行器前置要求](docs/zh/reference/executors.md#前置要求)。
+Beta 接口和存储契约仍可能变化。知识在显式选定的工作区维护；运行证据与机器偏好各有自己的存储范围。升级前备份，再按迁移指南建立新证据。
 
 ## 安全说明
 
-本工具设计用于**本地可信环境**（开发机、CI 流水线）。以下功能会执行本地代码，请确保输入来源可信：
-
-| 功能 | 风险 | 适用场景 |
-|------|------|----------|
-| **自定义断言**（`custom`） | 动态加载并执行用户指定的 `.mjs` 文件 | 仅使用自己编写或审查过的断言文件 |
-| **eval-samples.json** | 断言配置可引用外部文件路径 | 不要使用来源不明的用例文件 |
-
-**建议：**
-
-- 不要将本地报告服务暴露到公网（无身份认证）
-- 不使用未经审查的第三方 eval-samples
-- 自定义断言有 30 秒超时，但无沙箱隔离
-
----
+用于本地可信环境。任务、验收程序和自定义断言会执行本地代码，应先审查；工作区副本不是安全沙箱。调用模型前核对发送范围，原始记录与产物可能含敏感内容。本地报告服务没有身份认证，不应暴露到公网。
 
-发布日志见 [GitHub Releases](https://github.com/lizhiyao/oh-my-knowledge/releases)。欢迎贡献 —— 见 [CONTRIBUTING](./CONTRIBUTING.md)。
+发布说明见 [GitHub Releases](https://github.com/lizhiyao/oh-my-knowledge/releases)。贡献流程见 [CONTRIBUTING](./CONTRIBUTING.md)。

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

@@ -4,7 +4,7 @@ description: |
   OMK（Observe. Measure. Know.）让 AI 应用的知识改动有据可依。观测真实表现，受控测量 prompt / RAG / skill / agent / workflow 的版本差异，判断改动是否有效、版本能否发布，并支持自动迭代改进。
   Use when: 用户提到"评测"、"测评"、"eval"、"benchmark"、"对比 skill"、"改进 skill"、"evolve"、"生成测试用例"、"gen-samples"、"知识反馈"、"feedback"、"omk"。
 user-invocable: true
-argument-hint: "<agents|doctor|eval|evolve|init|install|list|observe|promote|rollback|sample|studio> [options]"
+argument-hint: "<agents|doctor|eval|evolve|init|install|observe|sample|studio> [options]"
 ---
 
 # OMK — Observe. Measure. Know.
@@ -19,7 +19,7 @@ argument-hint: "<agents|doctor|eval|evolve|init|install|list|observe|promote|rol
 2. 该显式调用本身视为用户确认。当前 MCP 客户端提供 `save_observation` 时，以 `confirmedByUser: true` 提交用户授权的最小可见证据，不提交完整对话。
 3. 如果没有明确候选，或同时存在多个无法唯一判断的候选，只追问要记录哪一项；确认目标前不调用工具。
 4. 如果当前客户端没有 `save_observation`，明确说明 OMK MCP 尚未连接；不要回退为 CLI 写文件，也不要声称已经保存。
-5. 快捷入口只保存 observation，不自动复核、生成 sample、写入 gold set 或 promote。
+5. 快捷入口只保存 observation，不自动复核、生成 sample 或写入 gold set。
 
 ## 第一步：检查环境
 
@@ -29,7 +29,7 @@ argument-hint: "<agents|doctor|eval|evolve|init|install|list|observe|promote|rol
 npm i -g oh-my-knowledge@next
 ```
 
-omk CLI 顶层命令包括：`init` / `install` / `list` / `promote` / `rollback` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
+omk CLI 顶层命令包括：`init` / `install` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
 
 ### 在 Codex / 支持 MCP 的客户端中
 
@@ -44,7 +44,7 @@ Codex 是 omk 的一等 runtime。运行在 Codex 任务中时，`omk eval` / `d
 - 用户明确说「记录这个问题」「把刚才的失败存下来」时，才以 `confirmedByUser: true` 调用 `save_observation`；只提交用户授权的最小可见证据。
 - 用户只是纠正答案、指出知识不足或遇到重复工具失败时，可以建议记录并请求确认；确认前不要调用 `save_observation`。这条启发式路径是 best-effort，不能声称覆盖全部对话。
 - 普通追问、假设性例子、泛泛的不满意或没有明确知识缺口的反馈，不要记录 observation。
-- 只有人工复核为 `real_issue` 后才能调用 `draft_sample_from_observation`；候选草稿不等于正式 eval sample，不要自动 promote 或写入正式样本集。
+- 只有人工复核为 `real_issue` 后才能调用 `draft_sample_from_observation`；候选草稿不等于正式 eval sample，不要自动写入正式样本集。
 - 需要对话内复核时，先 `get_observation`，再 `review_observation`。所有结果都按 `coverageStatus: partial` 解读，不推断未提交的上下文、其它工具调用或隐藏推理。
 
 ### 在 DeepSeek Harness 中
@@ -66,8 +66,6 @@ Codex 是 omk 的一等 runtime。运行在 Codex 任务中时，`omk eval` / `d
 | 体检 skill 写法 | → `omk doctor` |
 | 浏览对话、任务轨迹与报告 | → `omk studio`（启动本地知识工作台） |
 | 看真实使用 trace | → `omk observe` |
-| 查看受管 skill 状态 | → `omk list` |
-| 按证据接受 / 回退某版本 | → `omk promote` / `omk rollback` |
 
 如果用户意图不明确，先扫描当前项目结构（skills/ 目录、项目级 eval-samples 文件、目录 skill 私有 `.omk/eval-samples.*`），然后推荐最合适的操作。
 
@@ -205,7 +203,7 @@ Studio 首页直接索引本机 Codex 对话。先选择对话，再选择任务
 2. **质量分数**：各 variant 的平均综合分（0-5 分）+ Δ + 95% CI
 3. **成本对比**：token 消耗、execCostUSD、评委花费、diagnostic 花费
 4. **低分样本**：哪些样本两个版本差异最大，rubric 期望 vs 实际差在哪
-5. **下一步动作**：基于 verdict 给出动作；`PROGRESS` 时明确说明可以进入发布流程、留存报告作为发布证据，受管 skill 继续 `omk promote`；其它 verdict 给出扩样 / 修复 / 重跑建议
+5. **下一步动作**：基于 verdict 给出动作；`PROGRESS` 时明确说明可以进入发布流程、留存报告作为发布证据；其它 verdict 给出扩样 / 修复 / 重跑建议
 
 示例输出：
 
@@ -214,7 +212,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 可以进入发布流程；留存本次报告作为发布证据。如果这是受管 skill，继续运行 `omk promote` 记录接受决定。s003（XSS 检测）仍然可以作为下一轮优化点。
+- 建议：v2 可以进入发布流程；留存本次报告作为发布证据。s003（XSS 检测）仍然可以作为下一轮优化点。
 ```
 
 ### evolve 模式