oh-my-knowledge 0.51.2 → 0.52.0

package/README.md

@@ -1,4 +1,4 @@
-# oh-my-knowledge
+# 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)
@@ -8,14 +8,19 @@
 
 **English** | [简体中文](./README.zh.md)
 
-**Stop editing LLM knowledge inputs by gut feel.**
-`oh-my-knowledge` (omk) is a measurement workflow for prompts, RAG context, skills, agents, and workflows. It fixes the executor model and the evaluation samples, changes only the knowledge artifact, then answers the release question that matters: **can v2 ship, and where is it better?**
+**Observe. Measure. Know.**
+
+**OMK makes every knowledge change in your AI application evidence-backed.**
+
+Observe real-world performance, measure version differences, and determine whether the change is effective and the version is ready to ship.
+
+**Same model. Same evaluation samples. Only the knowledge artifact changes.**
 
 ![omk knowledge artifact evaluation flow: doctor / eval / observe / sample / evolve loop](./docs/public/omk-knowledge-flow-en-animated.gif)
 
 📖 **Full documentation: [oh-my-knowledge.pages.dev](https://oh-my-knowledge.pages.dev)** (searchable, English / 简体中文)
 
-## What omk makes measurable
+## What OMK helps you know
 
 | Decision | Command | Evidence you get |
 |---|---|---|
@@ -23,6 +28,7 @@
 | Is v2 actually better than v1? | `omk eval` | one-line verdict, confidence interval, failed samples, cost |
 | Why did it pass or fail? | `omk studio` | report view with scores, diagnostics, and examples |
 | Should this version become the accepted one? | `omk promote` / `omk evolve` | evidence-gated accept or generate a better candidate |
+| What happened during one real AI task? | `omk observe` / Studio Task Trajectory | a trace-backed view of the request, visible Knowledge, tool calls, results, response, and user correction |
 | What did real usage expose? | `omk observe` / `omk sample --from-traces` | production gaps drafted for review; reviewed drafts can become eval samples |
 
 ![omk report — verdict pill "v2 is clearly better than v1 — ready to ship"](./assets/screenshots/report-overview.png)
@@ -57,9 +63,23 @@ Walkthrough: [5-minute quickstart guide](docs/quickstart-skill-eval.md) (recomme
 
 Deeper: [who omk is for](docs/explanation/who-omk-is-for.md) · [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors](docs/reference/executors.md) · [artifact layout](docs/reference/artifact-layout.md)
 
-## The omk loop
+## Inspect one Codex task
+
+If you only want to see what happened behind one Codex conversation, you do not need to run `observe ingest` first:
+
+```bash
+omk studio
+```
+
+Studio opens the local Codex conversation overview at `http://127.0.0.1:7799` by default. Select a conversation, then a task, to open **Task Trajectory**. Its four lanes — **Conversation, Actions, Results, and Knowledge** — show the request, AI responses, tool calls, tool returns, and observable context, with drill-downs into normalized events and raw logs.
+
+Running tasks are prioritized and update live. While **Following**, the trajectory advances smoothly as events arrive; after you inspect an earlier point, Studio keeps your position and offers **View updates**. Old logs without a terminal event are marked **End status not recorded** instead of remaining live forever.
+
+Task Trajectory only reconstructs facts observable in the log. It does not reveal or infer hidden reasoning. See [Observe production traces](docs/guides/observe-production.md#inspect-one-task) for the full model.
+
+## The OMK loop
 
-omk is for authors and maintainers of LLM knowledge artifacts who need a release decision, not for passive end-users of a skill. The main loop is deliberately controlled:
+OMK is for authors and maintainers of LLM knowledge artifacts who need a release decision, not for passive end-users of a skill. The main loop is deliberately controlled:
 
 ```text
 change a prompt / RAG / skill / agent artifact
@@ -166,6 +186,7 @@ The full docs are published at **[oh-my-knowledge.pages.dev](https://oh-my-knowl
 - **[CLI reference](docs/reference/cli.md)** — all top-level commands with bash examples and flag tables
 - **[Executors](docs/reference/executors.md)** & **[artifact layout](docs/reference/artifact-layout.md)** — built-in / custom executors; how `variant` resolves to an artifact + runtime context
 - **[How-to guides](docs/guides/agent-eval.md)** — [evaluate an agent](docs/guides/agent-eval.md) (project runtime context) and [use non-Claude models](docs/guides/non-claude-models.md) (GLM / Qwen / DeepSeek / Moonshot / Ollama)
+- **[Observe & inspect task trajectories](docs/guides/observe-production.md)** — browse local Codex conversations, drill into one task, and follow its observable execution live
 - **[Quickstart](docs/quickstart-skill-eval.md)** — first-time five-minute walkthrough
 - **[Example gallery](https://github.com/lizhiyao/oh-my-knowledge/tree/main/examples)** — a set of runnable examples in the repo, arranged simplest-to-richest
 - **[Sample design spec](docs/specs/sample-design-spec.md)** — capability / construct / provenance metadata; industry-gap mapping

package/README.zh.md

@@ -1,4 +1,4 @@
-# oh-my-knowledge
+# 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)
@@ -8,14 +8,19 @@
 
 [English](./README.md) | **简体中文**
 
-**别再凭感觉改 LLM 知识输入。**
-`oh-my-knowledge`（omk）是一套面向 prompt、RAG、skill、agent、workflow 的测量工作流。它固定执行模型和评测用例，只改变知识载体，然后回答发布时真正要追问的问题：**v2 能不能发，好在哪里？**
+**Observe. Measure. Know.**
+
+**OMK，让 AI 应用的知识改动有据可依。**
+
+观测真实表现，量出版本差异，判断改动是否有效、版本能否发布。
+
+**相同模型，相同评测用例，只改变知识载体。**
 
 ![omk 知识载体评测流程：doctor / eval / observe / sample / evolve 闭环](./docs/public/omk-knowledge-flow-animated.gif)
 
 📖 **完整文档：[oh-my-knowledge.pages.dev/zh](https://oh-my-knowledge.pages.dev/zh/)**（可搜索，可切换英文）
 
-## omk 让什么变得可测量
+## OMK 让你知道什么
 
 | 决策问题 | 命令 | 你会得到的证据 |
 |------|------|------|
@@ -23,6 +28,7 @@
 | v2 是否真的优于 v1？ | `omk eval` | 一行 verdict、置信区间、失败样本、成本 |
 | 它为什么通过或失败？ | `omk studio` | 分数、诊断、样本证据的报告视图 |
 | 这个版本是否应成为接受版本？ | `omk promote` / `omk evolve` | 基于证据接受，或生成更好的候选版 |
+| 一次真实 AI 任务中发生了什么？ | `omk observe` / Studio 任务轨迹 | 请求、可见知识、工具调用与结果、回答和用户纠正的可核验轨迹 |
 | 真实使用暴露了哪些知识缺口？ | `omk observe` / `omk sample --from-traces` | 将线上缺口生成待复核草稿，复核后再沉淀为评测样本 |
 
 ![omk 报告 — verdict pill「v2 明显优于 v1，可以发布」](./assets/screenshots/report-overview-zh.png)
@@ -57,9 +63,23 @@ export OMK_EXECUTOR=codex
 
 深入：[为谁、解决什么](docs/zh/explanation/who-omk-is-for.md) · [CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [知识载体布局](docs/zh/reference/artifact-layout.md)
 
-## omk 的闭环
+## 先看清一次 Codex 任务
+
+只想知道一次 Codex 对话背后发生了什么，不需要先运行 `observe ingest`：
+
+```bash
+omk studio
+```
+
+Studio 默认在 `http://127.0.0.1:7799` 打开本机 Codex 对话总览。先选择一段对话，再选择其中一次任务，即可进入「任务轨迹」：按**对话、执行、结果、知识**四条泳道查看请求、AI 回答、工具调用、工具返回和可见上下文，并可下钻到规范化事件与原始日志。
+
+进行中的任务会优先显示并实时更新。保持「跟随中」时，轨迹会随新事件平滑前进；手动查看历史位置后，页面保留当前位置并提示「查看更新」。旧日志如果没有记录结束事件，会标记为「未记录结束状态」，不会一直冒充进行中。
+
+任务轨迹只还原日志中可观测的事实，不展示或推断隐藏思维。完整说明见[观测与任务轨迹](docs/zh/guides/observe-production.md#查看一次任务)。
+
+## OMK 的闭环
 
-omk 主要给 LLM 知识载体的作者 / 维护者用，帮他们做发布判断；它不是给被动安装 skill 的普通使用者用的。主流程刻意保持受控：
+OMK 主要给 LLM 知识载体的作者 / 维护者用，帮他们做发布判断；它不是给被动安装 skill 的普通使用者用的。主流程刻意保持受控：
 
 ```text
 改了一份 prompt / RAG / skill / agent 知识载体
@@ -166,6 +186,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 - **[CLI 参考](docs/zh/reference/cli.md)** —— 顶层命令的 bash 示例和 flag 表
 - **[执行器](docs/zh/reference/executors.md)** & **[知识载体布局](docs/zh/reference/artifact-layout.md)** —— 内置 / 自定义执行器；variant 如何解析为 artifact + runtime context
 - **[操作指南](docs/zh/guides/agent-eval.md)** —— [评测 agent](docs/zh/guides/agent-eval.md)（项目 runtime context）与[使用非 Claude 模型](docs/zh/guides/non-claude-models.md)（GLM / 通义 / DeepSeek / Moonshot / Ollama）
+- **[观测与任务轨迹](docs/zh/guides/observe-production.md)** —— 浏览本机 Codex 对话，下钻一次任务，并实时跟随可观测执行过程
 - **[快速上手](docs/zh/quickstart-skill-eval.md)** —— 第一次跑评测的 5 分钟教程
 - **[示例画廊](https://github.com/lizhiyao/oh-my-knowledge/tree/main/examples)** —— 仓库里一组可直接跑的示例，按由简到全排成上手路径
 - **[用例设计规范](docs/zh/specs/sample-design-spec.md)** —— capability / construct / provenance 元数据；行业 gap 映射

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

@@ -1,15 +1,15 @@
 ---
 name: omk
 description: |
-  oh-my-knowledge 知识载体评测工具的智能代理。评测 skill（系统提示词）质量，对比不同版本效果，自动迭代改进。
+  OMK（Observe. Measure. Know.）让 AI 应用的知识改动有据可依。观测真实表现，受控测量 prompt / RAG / skill / agent / workflow 的版本差异，判断改动是否有效、版本能否发布，并支持自动迭代改进。
   Use when: 用户提到"评测"、"测评"、"eval"、"benchmark"、"对比 skill"、"改进 skill"、"evolve"、"生成测试用例"、"gen-samples"、"omk"。
 user-invocable: true
 argument-hint: "<doctor|eval|evolve|init|install|list|observe|promote|rollback|sample|studio> [options]"
 ---
 
-# OMK — 知识载体评测
+# OMK — Observe. Measure. Know.
 
-你是 oh-my-knowledge（omk）的智能代理。帮助用户评测、对比、改进 AI skill（系统提示词），用数据说话。
+你是 OMK 的智能代理。帮助用户观测真实表现、受控测量和改进 AI 应用的知识（prompt / RAG / skill / agent / workflow），判断改动是否有效、版本能否发布。
 
 ## 第一步：检查环境
 
@@ -37,7 +37,7 @@ Codex 是 omk 的一等 runtime。运行在 Codex 任务中时，`omk eval` / `d
 | 改进 / 优化 skill | → `omk evolve`（自动多轮迭代） |
 | 生成测试用例 | → `omk sample` |
 | 体检 skill 写法 | → `omk doctor` |
-| 查看 / 浏览报告 | → `omk studio`（启动本地报告浏览器） |
+| 浏览对话、任务轨迹与报告 | → `omk studio`（启动本地知识工作台） |
 | 看真实使用 trace | → `omk observe` |
 | 查看受管 skill 状态 | → `omk list` |
 | 按证据接受 / 回退某版本 | → `omk promote` / `omk rollback` |
@@ -138,7 +138,7 @@ omk observe ingest ~/.codex/sessions
 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` 草拟评测用例。
+Codex rollout 会保留 `sourceKind=codex`、模型、父子任务、tool call 和 token 证据，并从实际读取的 `skills/<name>/SKILL.md` 归因 skill。`omk studio` 无需先 ingest，即可从本机 Codex 对话总览进入某次任务的实时轨迹；`observe ingest` 只在需要生成待复核 observation 时运行。任务轨迹按对话、执行、结果和知识呈现结构化事实，并联动检查配对后的工具调用与结果、AI 回答和用户纠正。该页面只呈现 trace 中可观测的执行过程，不推断隐藏思维或失败根因。确认真实知识缺口后，再用 `omk sample --from-traces` 草拟评测用例。
 
 ### 体检 skill 写法
 
@@ -155,16 +155,16 @@ omk doctor skills/my-skill.md
 
 `omk eval` 默认会先跑一次 doctor 当 preflight 门禁，所以一般不用单独跑；想在 eval 之前先把结构问题先扫一遍再跑评测，就单独跑 `omk doctor`。
 
-### 查看 / 浏览报告
+### 浏览对话、任务轨迹与报告
 
 ```bash
-omk studio                                # 启动本地 web 报告浏览器
+omk studio                                # 启动本地知识工作台（默认端口 7799）
 omk studio --port 8080                    # 改端口
 omk studio --host 0.0.0.0                 # 局域网访问（默认 127.0.0.1）
 omk studio --no-open                      # 不自动开浏览器
 ```
 
-Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势；详情页（`/skills/<name>`）左栏列关键问题清单，右栏画健康趋势 + 三档阶段卡（doctor / eval / observe）。访问 `/observe-inbox` 查看 observe inbox 看板。
+Studio 首页直接索引本机 Codex 对话。先选择对话，再选择任务查看四泳道任务轨迹；进行中的任务支持实时跟随。顶部「知识载体」入口用于浏览 doctor / eval / observe 报告，`/observe-inbox` 用于复核 observation。无需为了浏览本机 Codex 对话而先运行 `omk observe ingest`。
 
 ## 第五步：解读结果
 

package/dist/observability/codex-conversation-index.d.ts

@@ -0,0 +1,88 @@
+import type { ExperienceTurnStatus } from '../types/index.js';
+import type { TraceToolStatus } from './trace-ir.js';
+export interface CodexIndexedTask {
+    turnId: string;
+    title: string;
+    startTimestamp?: string;
+    endTimestamp?: string;
+    status: ExperienceTurnStatus;
+    sourceRecordCount: number;
+    toolCallCount: number;
+    toolFailureCount: number;
+    startOffset: number;
+    endOffset: number;
+    startLine: number;
+    endLine: number;
+}
+export interface CodexRolloutIndex {
+    schemaVersion: 11;
+    sourcePath: string;
+    /** File size observed when the index was produced. */
+    sourceSize: number;
+    sourceMtimeMs: number;
+    /** Byte boundary after the last complete JSONL record. */
+    indexedSize: number;
+    /** Physical line number at indexedSize, including blank lines. */
+    indexedLineCount: number;
+    /** Whether indexedSize is immediately after a newline delimiter. */
+    indexedEndsWithNewline: boolean;
+    sourceThreadId: string;
+    sessionMeta?: unknown;
+    sessionMetaLine?: number;
+    tasks: CodexIndexedTask[];
+    /** Incremental matcher state for the final unclosed task only. */
+    activeToolOutcomeState?: CodexActiveToolOutcomeState;
+    sourceRecordCount: number;
+    malformedRecordCount: number;
+}
+export interface CodexActiveToolOutcomeState {
+    callOccurrences: Array<[string, number]>;
+    resultOccurrences: Array<[string, number]>;
+    runtimeOccurrences: Array<[string, number]>;
+    outcomes: Array<[string, IndexedToolOutcome]>;
+}
+interface IndexedToolOutcome {
+    outputStatus?: TraceToolStatus;
+    runtimeStatus?: TraceToolStatus;
+}
+export interface CodexJsonlLine {
+    text: string;
+    line: number;
+    startOffset: number;
+    endOffset: number;
+}
+/**
+ * Build a compact byte-range index without retaining the rollout. Only records
+ * needed for turn boundaries and list metrics are parsed.
+ */
+export declare function buildCodexRolloutIndex(sourcePath: string, sourceThreadId: string): CodexRolloutIndex;
+/**
+ * Extend an append-only rollout index from its last byte boundary. If the
+ * source was replaced or truncated, rebuild so callers never observe a mixed
+ * index from two different files.
+ */
+export declare function extendCodexRolloutIndex(sourcePath: string, sourceThreadId: string, previous: CodexRolloutIndex): CodexRolloutIndex;
+/**
+ * Catch an append-only rollout up to a snapshot that is still current after
+ * indexing. Returning a stale prefix here would violate current-read callers.
+ */
+export declare function synchronizeCurrentCodexRolloutIndex(sourcePath: string, sourceThreadId: string, initial?: CodexRolloutIndex): CodexRolloutIndex;
+/**
+ * A single Codex rollout is sequential: once a newer task starts, an older
+ * task without a terminal record can no longer be live. Normalize historical
+ * caches in memory so an omitted task_complete never becomes a permanent
+ * "running" conversation.
+ */
+export declare function normalizeCodexRolloutIndex(index: CodexRolloutIndex): CodexRolloutIndex;
+export declare function isCurrentCodexRolloutIndex(value: unknown, sourcePath: string): value is CodexRolloutIndex;
+/**
+ * Codex rollouts are append-only while a conversation is active. A prefix
+ * index remains internally consistent even after newer records are appended.
+ */
+export declare function isReusableCodexRolloutIndex(value: unknown, sourcePath: string): value is CodexRolloutIndex;
+export declare function readCodexTaskRecords(index: CodexRolloutIndex, task: CodexIndexedTask): {
+    records: Array<unknown | undefined>;
+    lines: CodexJsonlLine[];
+    malformedRecordCount: number;
+};
+export {};