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

package/README.md

@@ -10,26 +10,55 @@
 
 **Observe. Measure. Know.** Make knowledge changes in your AI application evidence-backed.
 
-OMK helps authors of prompts, RAG systems, skills, and agents compare versions, inspect evidence, and find knowledge gaps in real tasks. A controlled comparison keeps the **same model and evaluation samples, changing only the knowledge artifact**.
+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.
+
+**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.
 
 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)
 
-## Start with your goal
+## Choose how to use OMK
 
-| Goal | Entry point |
+| Interface | Use it for |
 |---|---|
-| Compare two skills and inspect the verdict, interval, and failed cases | [CLI quickstart](docs/quickstart-skill-eval.md) |
-| Add scoring and version comparisons to a Node.js service | [Service integration guide](docs/guides/eval-runtime.md), including an example without model credentials |
-| Inspect one task or find problems in historical logs | [Observation and task trajectories](docs/guides/observe-production.md) |
+| **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
 
-You need Node.js >=22 and an authenticated model runtime; see [Requirements](#requirements). Install the Beta and preview your first comparison:
+Installation requires Node.js >=22. Model calls also require an authenticated runtime; see [Requirements](#requirements).
 
 ```bash
 npm i -g oh-my-knowledge@next
+```
+
+### Inspect an existing task
+
+```bash
+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).
+
+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).
+
+### Or compare two skills directly
+
+```bash
 omk init demo
 cd demo
 omk eval --control code-review-v1 --treatment code-review-v2 --dry-run
@@ -45,23 +74,51 @@ The scaffold contains two skills and three cases. This small default set checks
 
 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.
 
-## Use inside AI Coding Agents
+## Use inside agents and DSH
+
+### Agent Skill and MCP
 
 ```bash
 omk install omk-agent-skill
 ```
 
-Then ask your coding agent: “Use omk to compare these two skills.” See the [quickstart](docs/quickstart-skill-eval.md#use-inside-an-agent) for installation targets and usage. DeepSeek Harness users can use the [host plugin](docs/reference/executors.md#deepseek-harness-prefer-the-host-plugin) to reuse their current profile.
+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
 
-`doctor` checks the artifact, `eval` compares versions, and `studio` presents results and raw evidence. When evidence meets the gate, `promote` can accept a version; `evolve` can generate a candidate. Gaps found by `observe` can become draft cases for review before the next evaluation.
+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 evidence lives under `.omk/`; machine-level state lives under `~/.oh-my-knowledge/`. 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.
+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
 

package/README.zh.md

@@ -10,26 +10,55 @@
 
 **Observe. Measure. Know.** 让 AI 应用的知识改动有据可依。
 
-OMK 帮助 prompt、RAG、skill 和 agent 的作者比较版本、检查证据，并从真实任务中发现知识缺口。受控比较遵循：**相同模型，相同评测用例，只改变知识载体。**
+OMK 是面向 AI 应用作者与维护者的知识观测、评测与改进工具体系。查看真实任务如何执行，从工作日志提炼可复核的知识内容，再测量 prompt、RAG、skill、agent 或 workflow 的载体改动是否有效，为采纳、回退和继续改进提供证据。
+
+**Observe** 保留真实表现与来源，**Measure** 在相同模型、用例与运行条件下比较知识载体，**Know** 让决定可以回到证据核对。已有两版载体时，可以直接开始评测；不必先收集日志。
 
 当前 1.0 仍处于 **Beta 迭代期**，接口与存储契约可能继续变化。从旧版本升级前，请先阅读[迁移指南](docs/zh/guides/v1-preview-migration.md)。
 
 ![OMK：从受控评测到真实使用反馈](./docs/public/omk-knowledge-flow-animated.gif)
 
-## 从你的目标开始
+## 选择使用方式
 
-| 想做什么 | 入口 |
+| 入口 | 适合什么场景 |
 |---|---|
-| 比较两版 skill，获得判定、置信区间与失败用例 | [命令行快速上手](docs/zh/quickstart-skill-eval.md) |
-| 在 Node.js 服务中接入评分与版本对比 | [服务接入指南](docs/zh/guides/eval-runtime.md)，含无需模型凭证的示例 |
-| 看清一次任务，或从历史日志发现问题 | [观测与任务轨迹](docs/zh/guides/observe-production.md) |
+| **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，详见[系统要求](#系统要求)。安装 Beta 并预览第一次比较：
+安装需要 Node.js >=22。调用模型前还需配置已认证的 runtime，详见[系统要求](#系统要求)。
 
 ```bash
 npm i -g oh-my-knowledge@next
+```
+
+### 先看已有任务
+
+```bash
+omk studio
+```
+
+打开命令返回的本地地址，从本机 Codex 对话进入任务轨迹；无需先 ingest，也不调用模型。进行中的任务支持实时跟随。Claude Code、OpenClaw 与 markdown 日志通过 `omk observe` 进入观测报告，见[观测指南](docs/zh/guides/observe-production.md)。
+
+需要沉淀经验时，在知识页面选择“从工作日志提炼知识”，选定工作区与 Codex 日志片段，核对来源后再生成。生成会调用模型；保留候选表示愿意维护，不等于已证实，也不会自动写入 AGENTS.md 或 skill。步骤见[提炼指南](docs/zh/guides/extract-knowledge.md)。
+
+### 或者，直接比较两版 skill
+
+```bash
 omk init demo
 cd demo
 omk eval --control code-review-v1 --treatment code-review-v2 --dry-run
@@ -45,23 +74,51 @@ omk eval --control code-review-v1 --treatment code-review-v2
 
 [完整教程](docs/zh/quickstart-skill-eval.md)介绍模型选择、换成自己的 skill 和结果解读；[示例画廊](examples/README.zh.md)提供更多可运行场景。
 
-## 在 Agent 中使用
+## 在 Agent 与 DSH 中使用
+
+### Agent Skill 与 MCP
 
 ```bash
 omk install omk-agent-skill
 ```
 
-安装后，可以对 coding agent 说：“用 omk 比较这两版 skill。”安装目标与使用方法见[快速上手](docs/zh/quickstart-skill-eval.md#在-agent-中使用)。DeepSeek Harness 用户可直接使用[宿主插件](docs/zh/reference/executors.md#deepseek-harness优先使用宿主插件)，复用当前 profile。
+安装 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-优先使用宿主插件)。
+
 ## 如何使用证据
 
-`doctor` 检查知识载体，`eval` 做受控比较，`studio` 展示结果与原始证据。证据满足条件后可以 `promote` 接受版本，或用 `evolve` 生成候选；`observe` 暴露的缺口可转成待复核用例，再进入下一轮评测。
+知识内容是一条可复核的事实、经验或方法；知识载体是承载内容的 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)重新建立证据。
+项目评测与观测证据保存在 `.omk/`，机器级状态位于 `~/.oh-my-knowledge/`；提炼的知识内容保存在显式选择的知识工作区。当前版本不读取或迁移旧存储布局；升级前备份，按[迁移指南](docs/zh/guides/v1-preview-migration.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: "<doctor|eval|evolve|init|install|list|observe|promote|rollback|sample|studio> [options]"
+argument-hint: "<agents|doctor|eval|evolve|init|install|list|observe|promote|rollback|sample|studio> [options]"
 ---
 
 # OMK — Observe. Measure. Know.
@@ -33,7 +33,7 @@ omk CLI 顶层命令包括：`init` / `install` / `list` / `promote` / `rollback
 
 ### 在 Codex / 支持 MCP 的客户端中
 
-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 的一等 runtime。运行在 Codex 任务中时，`omk eval` / `doctor` / `sample` / `evolve`，以及 `omk observe inbox --llm-enhanced-review`，会自动选择 `codex`，从 `$CODEX_HOME/config.toml` 或 `~/.codex/config.toml` 解析模型（顶层 `profile` 指向某个 profile 时取该 profile 的 `model`，否则取顶层 `model`），默认评委沿用同一个 Codex 模型；不要额外回落到 Claude。
 
 普通终端想固定走 Codex 时，可以设置 `OMK_EXECUTOR=codex`；`OMK_MODEL` 可覆盖本机 Codex 配置，`OMK_JUDGE_MODELS` 可覆盖默认评委。逐次覆盖仍可使用 `--executor` / `--model` / `--judge-models`。Codex 不需要 Claude Code 风格的 `/omk` slash command，直接执行 CLI。
 

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

@@ -4,6 +4,45 @@
 <!-- 此段由 scripts/build/docs.ts 从 src/cli/commands/ 自动生成。
      改 CLI 后跑 `yarn build:docs` 同步,CI `yarn build:docs:check` 会拦截 drift。-->
 
+## omk agents
+
+识别本机已安装的 Agent，采集其日志并映射成统一格式，再提炼候选知识。
+
+**用法:**
+
+```bash
+omk agents <operation> [flags]
+```
+
+**参数:**
+
+- `operation`(必填):操作：list 识别安装情况，collect 采集日志并映射成统一 Trace IR，extract 从已采集日志提炼候选知识。
+
+**Flags:**
+
+- `--dir` `option`:清单与采集产物目录，默认全局 ~/.oh-my-knowledge/observe/agents。
+- `--executor` `option`:extract：生成执行器，沿用 OMK 运行配置。
+- `--json` `boolean`:输出完整 JSON；默认输出可读摘要。
+- `--knowledge` `option`:extract：知识工作区，默认全局知识目录。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
+- `--limit` `option`:collect 单轮处理的会话文件上限。
+- `--model` `option`:extract：生成模型，沿用已配置模型。
+- `--session` `option`:extract：采集报告里的 runId。
+
+**示例:**
+
+```bash
+omk agents list
+```
+
+```bash
+omk agents collect --limit 50
+```
+
+```bash
+omk agents extract --session <runId> --executor codex --model <model>
+```
+
 ## omk doctor
 
 体检 omk 工作目录：先跑静态规则，再对 skill 做多维度 LLM 健康度审计（默认 --repeat 2 采样 + 共识归并）。
@@ -28,7 +67,7 @@ omk doctor [target] [flags]
 - `--gate` `boolean`:静默模式，只在 fail 时输出 stderr 摘要，exit code 标识结果。
 - `--global` `boolean`:写全局 ~/.oh-my-knowledge/doctor，而非项目 .omk/doctor
 - `--json` `boolean`:JSON 输出到 stdout，适合 CI / 外部脚本消费。
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--model` `option`:LLM model 名。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。
 - `--output-dir` `option`:报告输出目录，默认项目级 .omk/doctor（--global 写全局）。
 - `--repeat` `option`:健康度体检重复采样次数（self-consistency）。默认 2：并行跑 2 遍、finding 取并集并用 LLM 聚类归并同根因、标注支持度 k/N，压低单次采样方差。设 1 = 单次快速体检（不采样、不归并，最省）。
@@ -91,7 +130,7 @@ omk eval [flags]
 - `--holdout-ratio` `option`:留出比例 0-1（如 0.3）；切出 holdout 子集，对比 train/holdout 综合分检测过拟合
 - `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 codex:<model>（≥ 2 个 = ensemble）。默认跟随所选执行器；Claude 使用 haiku，其他执行器沿用被测模型。
 - `--judge-repeat` `option`:每个维度由评委评价 N 次
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--layered-stats` `boolean`:输出分层统计
 - `--mcp-config` `option`:MCP 配置文件路径
 - `--model` `option`:被测模型
@@ -145,7 +184,7 @@ omk eval gold [flags]
 
 **Flags:**
 
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 
 ## omk eval gold compare
 
@@ -166,7 +205,7 @@ omk eval gold compare <runId> [flags]
 - `--bootstrap-samples` `option`:bootstrap 重采样次数，默认 1000
 - `--evaluator` `option`:显式选择 Core evaluator ID。
 - `--gold-dir` `option`:gold dataset 目录，必填
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--metric` `option`:显式选择 Core metric ID。
 - `--minimum-alpha` `option`:可选的一致性阈值；按 Krippendorff α 置信区间下界评估
 - `--reports-dir` `option`:只读取指定 Core 报告目录（默认当前项目 + 全局）
@@ -187,7 +226,7 @@ omk eval gold init [flags]
 **Flags:**
 
 - `--annotator` `option`:标注者名，写入 metadata.yaml
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--out` `option` (默认 `./gold-dataset`):输出目录，默认 ./gold-dataset
 
 ## omk eval gold validate
@@ -206,7 +245,7 @@ omk eval gold validate <dir> [flags]
 
 **Flags:**
 
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 
 ## omk evolve
 
@@ -231,7 +270,7 @@ omk evolve <skillPath> [flags]
 - `--improve-mode` `agent|rewrite` (默认 `agent`):改写策略（默认：agent）
 - `--improve-model` `option`:负责重写 skill 的 LLM，默认沿用被测模型
 - `--judge-models` `option`:评委 model（单评委约束），格式 executor:model。默认跟随所选执行器；Codex 沿用被测模型。
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--model` `option`:被评测的 LLM。Codex 自动读取本机配置；无用例时也用作自动生成用例的出题模型。
 - `--no-edit-budget` `boolean`:关掉 edit budget 约束（允许任意大小的单轮改动）
 - `--no-reject-memory` `boolean`:关掉 rejected-edit 记忆（不把被拒改法回灌下一轮 prompt）
@@ -273,7 +312,7 @@ omk init [targetDir] [flags]
 **Flags:**
 
 - `--force` `boolean`:允许覆盖目标目录中已有的 omk 脚手架文件
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--samples` `3|20` (默认 `3`):官方起步用例数量：3 条用于快速跑通，20 条用于达到默认启发式证据下限
 
 **示例:**
@@ -318,7 +357,7 @@ omk install <input> [flags]
 - `--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。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--to` `option` (默认 `auto`):安装目标：auto（默认，本机已检测目标） / codex / claude / all。
 
 **示例:**
@@ -373,7 +412,7 @@ omk list [flags]
 
 - `--global` `boolean`:看全局受管目录（~/.oh-my-knowledge/governance/managed）而非项目 .omk/governance/managed
 - `--json` `boolean`:输出 JSON（含完整可比性 marker），供脚本消费
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 
 **示例:**
 
@@ -415,7 +454,7 @@ omk observe [sessionsDir] [flags]
 - `--from` `option`:起始时间 ISO，优先级高于 --last
 - `--global` `boolean`:写全局 ~/.oh-my-knowledge/observe/health，而非项目 .omk/observe/health
 - `--kb` `option`:知识库 root，启用 KB-aware 分析
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--last` `option`:时间窗(7d / 24h / 30m）
 - `--output-dir` `option`:健康报告输出目录，默认项目级 .omk/observe/health（--global 写全局）
 - `--skills` `option`:只看指定 skill，逗号分隔
@@ -448,7 +487,7 @@ omk observe inbox [flags]
 - `--include-noise` `boolean`:explore 时也包含 noise 桶
 - `--input-dir` `option`:inbox 数据目录，默认 .omk/observe/inbox（项目级，相对于 cwd）；目录不存在时兜底读 ~/.oh-my-knowledge/observe/inbox。
 - `--json` `boolean`:JSON 格式输出（schemaVersion: 1，kind 标识查询、聚合或增强复盘）
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--limit` `option`:限制条数，默认 20
 - `--llm-enhanced-review` `boolean`:显式调用模型进行链路增强复盘，包含标准抽取、目标判断、类型判断、产物匹配和 owner 建议
 - `--model` `option`:LLM 增强复盘使用的模型。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。
@@ -473,7 +512,7 @@ omk observe ingest <traceDir> [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。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--output-dir` `option`:输出目录，默认 .omk/observe/inbox（项目级，相对于 cwd；--global 写全局）。
 
 ## omk observe knowledge
@@ -498,13 +537,13 @@ omk observe knowledge <operation> [flags]
 - `--id` `option`:知识身份；resume 时为运行身份。
 - `--input` `option`:revise：包含 title、content、entities、evidence 的 JSON 草稿。
 - `--json` `boolean`:输出完整 JSON；默认输出可读摘要。
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--model` `option`:生成模型，沿用已配置模型。
 - `--reason` `option`:保留、舍弃或修订的理由。
 - `--revision` `option`:查看或处理的明确修订身份。
 - `--run-id` `option`:generate：稳定 UUID，用于重试同一次运行。
 - `--snapshot` `option`:generate／source／delete-source：归档身份。
-- `--source` `option`:capture：一份 Codex JSONL 文件。
+- `--source` `option`:capture：一份已支持格式的 Agent 会话日志（Codex／Claude／Qoder 等）。
 - `--start-record` `option`:从零开始的非空记录序号，包含。
 - `--workspace` `option`:本地知识工作区，默认使用全局设置；CLI 与 Studio 共用。
 
@@ -540,7 +579,7 @@ omk observe show <inboxId> [flags]
 
 - `--global` `boolean`:直接读取全局 ~/.oh-my-knowledge/observe/inbox（跳过项目级与兜底）。
 - `--input-dir` `option`:inbox 数据目录
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 
 ## omk promote
 
@@ -564,7 +603,7 @@ omk promote <name> [flags]
 - `--global` `boolean`:操作全局受管目录而非项目 .omk/governance/managed
 - `--json` `boolean`:输出 JSON（版本化信封）供脚本消费
 - `--kind` `option` (默认 `skill`):artifact 类型（当前仅 skill）
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--reason` `option`:promote / 越门的理由（写入决定）
 
 **示例:**
@@ -607,7 +646,7 @@ omk rollback <name> [flags]
 - `--global` `boolean`:操作全局受管目录而非项目 .omk/governance/managed
 - `--json` `boolean`:输出 JSON（版本化信封）供脚本消费
 - `--kind` `option` (默认 `skill`):artifact 类型（当前仅 skill）
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--reason` `option`:回退的理由（写入决定）
 
 **示例:**
@@ -646,7 +685,7 @@ omk sample [skillPath] [flags]
 - `--executor` `option`:执行器名。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。
 - `--focus` `option`:生成焦点（自然语言提示）。控制 LLM 偏向哪类用例。
 - `--from-traces` `boolean`:from-traces 模式：从 observe inbox 的失败信号回流生成评测用例草稿（provenance: production-trace），落草稿待人工 review。
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--model` `option`:生成 LLM model 名。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。
 - `--no-mock` `boolean`:不生成 mocks。执行器不支持工具拦截时会自动启用，避免产生必然失败的 mock_hit。
 - `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observe/inbox。
@@ -685,12 +724,13 @@ omk studio [flags]
 
 **Flags:**
 
+- `--agents-dir` `option`:本机 Agent 识别／采集报告目录（可选，默认全局 ~/.oh-my-knowledge/observe/agents，即 `omk agents` 的落点）
 - `--analyses-dir` `option`:观测健康报告目录（可选，默认项目级 .omk/observe/health，空则全局兜底）
 - `--dev` `boolean`:dev 模式：子进程启动 + 热更新
 - `--doctors-dir` `option`:体检报告目录（可选，默认项目级 .omk/doctor，空则全局兜底）
 - `--global` `boolean`:只看全局 eval / observe/health / doctor / observe/inbox 目录（~/.oh-my-knowledge/），而非机器级聚合 / 项目优先；governance/managed 不受影响
 - `--host` `option`:监听 host，默认 localhost。改为 0.0.0.0 暴露给局域网
-- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > zh。
+- `--lang` `option`:输出语言 zh|en，优先级 CLI > OMK_LANG env > 全局设置 > 系统 locale > zh。
 - `--no-open` `boolean`:不自动打开浏览器
 - `--observations-dir` `option`:观测收件箱数据目录（可选，默认 .omk/observe/inbox）
 - `--port` `option` (默认 `7799`):监听端口，默认 7799。传 0 让 OS 分配

package/dist/cli/commands/agents.d.ts

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../oclif/base-command.js';
+export default class AgentsCommand extends BaseCommand {
+    static description: string;
+    static args: {
+        operation: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        session: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        knowledge: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        executor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}