dsh-session-eval 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
+## 0.2.4 — 2026-10-11
+
+Feature release: eval-history report files.
+
+- New: `/eval-history --out PATH[.md|.json]` writes the history report to a Markdown or JSON file instead of only echoing it (contributed by @varshith84 in #4, merged as 117f918 after a maintainer rebase).
+
 # Changelog
 
+
+## 0.2.3 — 2026-10-03
+
+Docs polish round (no runtime changes).
+
+- Install detail completed: requirements, GitHub install route, the `cordis.patch.yml` row.
+- Contributor block links the open-gap issues directly; sample outputs aligned with the shipped version.
+- Community section; bilingual issue templates (`.github/ISSUE_TEMPLATE/`).
+- English/Chinese README sections kept in sync.
+
 ## 0.2.2 — 2026-10-02
 
 Contributor-first docs release.
@@ -9,6 +25,8 @@ Contributor-first docs release.
 - Skeleton: one-liner → install → try-once → toolchain table → 6-line contributor block.
 - CONTRIBUTING.md (with source map), SECURITY.md, CODE_OF_CONDUCT.md added; GitHub topics set.
 - Docs no longer hardcode test counts.
+- Install details (GitHub route + `cordis.patch.yml`), Development/Community footers, and issue links #1–#3 added for parity with the sibling plugins.
+- GitHub issue templates (`bug_report`, `feature_request`) added.
 
 
 ## 0.2.1 — 2026-09-26

package/README.md

@@ -13,10 +13,26 @@ No benchmark suites to author. No LLM judges. No new runs. Every grade is a fixe
 
 ## Install
 
+**Requirements**: Node.js 20 or 22 · a DeepSeek Harness profile that mounts the `commands` and `sessionQuery` services (the shipped `web` / `agent` profiles qualify).
+
 ```bash
 dsh plugin --profile web add dsh-session-eval
 ```
 
+Or from GitHub:
+
+```bash
+dsh plugin --profile web add github:kittimzhe/dsh-session-eval
+```
+
+The bundle overlay mounts `/eval`, `/eval-diff`, and `/eval-history`. If you maintain your own `cordis.patch.yml`, keep this row:
+
+```yaml
+- insert:
+    - id: session-eval
+      name: 'dsh-session-eval'
+```
+
 ## Try it once
 
 In DeepSeek Harness:
@@ -26,7 +42,7 @@ In DeepSeek Harness:
 ```
 
 ```text
-Session eval — a1b2c3d4… (dsh-session-eval v0.2.1)
+Session eval — a1b2c3d4… (dsh-session-eval v0.2.2)
 Overall: A
   Reliability   A    2/87 tool results errored (2.3%)
   Re-ask        A    1 re-ask signal(s) over 23 turns (0.4/10 turns)
@@ -49,7 +65,7 @@ All three read through the same trusted `ctx.sessionQuery` seam, so any persiste
 
 - **Local dev**: `npm ci && npm run typecheck && npm test && npm run bundle` (Node 20 or 22).
 - **Start in the source**: [`src/grade.ts`](src/grade.ts) (thresholds, grade cards), [`src/metrics.ts`](src/metrics.ts) (metric extraction), [`src/trend.ts`](src/trend.ts) (`/eval-history` trend logic). See [CONTRIBUTING.md](CONTRIBUTING.md) for the source map and first-PR suggestions.
-- **Open gaps**: threshold configurability, wider `/eval-history` filters, trend export — tracked in [issues labeled `good first issue`](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+- **Open gaps**: [#1](https://github.com/kittimzhe/dsh-session-eval/issues/1) (configurable thresholds), [#2](https://github.com/kittimzhe/dsh-session-eval/issues/2) (`/eval-history --since`), [#3](https://github.com/kittimzhe/dsh-session-eval/issues/3) (`/eval-history --out`) — or browse [issues labeled `good first issue`](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 - **Rules**: behavior changes need tests; doc changes must update `README.md` and `README.zh.md` in sync; version releases belong to the maintainer. Details: [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## How it differs from benchmark-style evaluation
@@ -75,6 +91,8 @@ Both are useful; they don't compete. Benchmarks test what you *predicted*; retro
 | `/eval-history [N]` | Grade the last N sessions in this workspace and show the trend |
 | `/eval-history … --json` | Machine-readable history report |
 
+Use `/eval-history --out report.md` to save the terminal card as Markdown, or add `--json` to save the JSON payload. Relative paths resolve against the current session workspace (the process working directory when unavailable). Parent directories must already exist; file errors are reported without creating directories. Existing output files are overwritten.
+
 `/eval-history` finds the sessions for you via the same `sessionQuery` seam `/archive` uses (scoped to the current workspace's `cwd`), grades each, and diffs the first against the last. `/eval-diff` remains the tool when you already know the two ids that matter.
 
 Typical use: grade the ten sessions before and after a plugin or prompt change; a persistent `Reliability` regression is an early warning that the change hurt real work, not just benchmarks.
@@ -99,6 +117,19 @@ Diff verdicts include a noise band (±2pp error rate, ±0.5 re-ask, ±1 tool loa
 
 Same session logs in → same grade card out, every time, forever. There is no model in the loop, no sampling, no clock dependence in the metrics (wall time is reported, never graded). This is what makes `/eval-diff` trustworthy as a regression signal.
 
+## Development
+
+```bash
+npm ci
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+npm run bundle      # tsdown → lib/
+```
+
 ## License
 
 [MIT](LICENSE)
+
+## Community
+
+- [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md)

package/README.zh.md

@@ -3,6 +3,7 @@
 [English](README.md) | 中文
 
 [![npm](https://img.shields.io/npm/v/dsh-session-eval)](https://www.npmjs.com/package/dsh-session-eval)
+[![npm downloads](https://img.shields.io/npm/dw/dsh-session-eval)](https://www.npmjs.com/package/dsh-session-eval)
 [![tests](https://github.com/kittimzhe/dsh-session-eval/actions/workflows/test.yml/badge.svg)](https://github.com/kittimzhe/dsh-session-eval/actions/workflows/test.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
@@ -12,10 +13,26 @@
 
 ## 安装
 
+**环境要求**：Node.js 20 或 22 · 挂载了 `commands` 与 `sessionQuery` 服务的 DeepSeek Harness profile（官方 `web` / `agent` profile 均满足）。
+
 ```bash
 dsh plugin --profile web add dsh-session-eval
 ```
 
+或从 GitHub：
+
+```bash
+dsh plugin --profile web add github:kittimzhe/dsh-session-eval
+```
+
+bundle 覆盖层会挂上 `/eval`、`/eval-diff`、`/eval-history`。若你维护自己的 `cordis.patch.yml`，请保留这一行：
+
+```yaml
+- insert:
+    - id: session-eval
+      name: 'dsh-session-eval'
+```
+
 ## 试一次
 
 在 DeepSeek Harness 里：
@@ -25,7 +42,7 @@ dsh plugin --profile web add dsh-session-eval
 ```
 
 ```text
-Session eval — a1b2c3d4… (dsh-session-eval v0.2.1)
+Session eval — a1b2c3d4… (dsh-session-eval v0.2.2)
 Overall: A
   Reliability   A    2/87 tool results errored (2.3%)
   Re-ask        A    1 re-ask signal(s) over 23 turns (0.4/10 turns)
@@ -48,7 +65,7 @@ Notes:
 
 - **本地开发**：`npm ci && npm run typecheck && npm test && npm run bundle`（Node 20 或 22）。
 - **源码入口**：[`src/grade.ts`](src/grade.ts)（阈值与等级卡）、[`src/metrics.ts`](src/metrics.ts)（指标提取）、[`src/trend.ts`](src/trend.ts)（`/eval-history` 趋势逻辑）。源码地图与第一次 PR 建议见 [CONTRIBUTING.md](CONTRIBUTING.md)。
-- **当前缺口**：阈值可配置、`/eval-history` 过滤条件扩展、趋势导出——见 [`good first issue` 标签的 issue](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
+- **当前缺口**：[#1](https://github.com/kittimzhe/dsh-session-eval/issues/1)（阈值可配置）、[#2](https://github.com/kittimzhe/dsh-session-eval/issues/2)（`/eval-history --since`）、[#3](https://github.com/kittimzhe/dsh-session-eval/issues/3)（`/eval-history --out`）——或浏览 [`good first issue` 标签](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
 - **规矩**：行为变更必须带测试；文档必须 `README.md` 与 `README.zh.md` 同步改；版本发布由维护者执行。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ## 与基准式评测（dsh-eval）的区别
@@ -74,6 +91,8 @@ Notes:
 | `/eval-history [N]` | 本工作区最近 N 个会话成绩单 + 首末趋势 |
 | `/eval-history … --json` | 机器可读历史报告 |
 
+使用 `/eval-history --out report.md` 将终端卡片保存为 Markdown，添加 `--json` 则保存 JSON。相对路径基于当前会话工作目录（缺失时使用进程工作目录）。父目录必须已存在；写入失败会返回错误，不会创建目录。已存在的输出文件会被覆盖。
+
 `/eval-history` 通过与 `/archive` 相同的 `sessionQuery` 接缝自动找到会话（按当前工作区 `cwd` 过滤），逐个评级，并把首尾两个会话做趋势对比——不用再手动挑 id。已经知道两个关键 id 时用 `/eval-diff`。
 
 典型用法：换插件或 prompt 前后各评十个会话；`Reliability` 持续回归 = 改动伤害了真实工作的早期预警。
@@ -96,6 +115,19 @@ Diff 判定带噪声带（错误率 ±2pp、Re-ask ±0.5、工具负载 ±1）
 
 同样的日志进 → 同样的等级出。没有模型在环、没有采样、指标不含时钟依赖（wall time 只报告不评级）。这是 `/eval-diff` 能作为回归信号被信任的原因。
 
+## 开发
+
+```bash
+npm ci
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+npm run bundle      # tsdown → lib/
+```
+
 ## 许可
 
 [MIT](LICENSE)
+
+## 社区
+
+- [贡献指南](CONTRIBUTING.md) · [安全策略](SECURITY.md) · [行为准则](CODE_OF_CONDUCT.md)

package/lib/index.d.ts

@@ -133,11 +133,12 @@ declare function executeEval(ctx: Context, invocation: CommandInvocation, seam?:
 declare function executeEvalDiff(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam): Promise<CommandResult>;
 //#endregion
 //#region src/historyCommand.d.ts
-declare const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json]  (N = last N sessions, 1-20, default 5)";
+declare const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json] [--out PATH]  (N = last N sessions, 1-20, default 5)";
 /** Args for /eval-history. */
 interface EvalHistoryArgs {
   readonly count: number;
   readonly json: boolean;
+  readonly out?: string;
 }
 /** Parse /eval-history input; returns args or a usage-error string. */
 declare function parseEvalHistoryArgs(rawInput: string): EvalHistoryArgs | string;
@@ -177,7 +178,7 @@ declare function executeEvalHistory(ctx: Context, invocation: CommandInvocation,
  *
  * @module dsh-session-eval/version
  */
-declare const VERSION = "0.2.2";
+declare const VERSION = "0.2.4";
 //#endregion
 //#region src/index.d.ts
 declare const name = "session-eval";

package/lib/index.js

@@ -1,4 +1,6 @@
 import { SessionId } from "@deepseek-ai/dsh-session";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
 //#region src/metrics.ts
 /** Count a correction signal for every extra user message inside a consecutive-user run. */
 function countCorrections(events) {
@@ -227,7 +229,7 @@ function compareSessions(before, after) {
 *
 * @module dsh-session-eval/version
 */
-const VERSION = "0.2.2";
+const VERSION = "0.2.4";
 //#endregion
 //#region src/evalCommand.ts
 const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--json]";
@@ -327,14 +329,14 @@ async function executeEval(ctx, invocation, seam = ctx.sessionQuery) {
 	if (parsed.json === true) return {
 		kind: "success",
 		text: JSON.stringify({
-			generator: "dsh-session-eval v0.2.2",
+			generator: "dsh-session-eval v0.2.4",
 			metrics,
 			card
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderCard(card, "dsh-session-eval v0.2.2")
+		text: renderCard(card, "dsh-session-eval v0.2.4")
 	};
 }
 /** Execute /eval-diff against the session-query seam. */
@@ -358,25 +360,44 @@ async function executeEvalDiff(ctx, invocation, seam = ctx.sessionQuery) {
 	if (parsed.json === true) return {
 		kind: "success",
 		text: JSON.stringify({
-			generator: "dsh-session-eval v0.2.2",
+			generator: "dsh-session-eval v0.2.4",
 			report
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderTrend(report, "dsh-session-eval v0.2.2")
+		text: renderTrend(report, "dsh-session-eval v0.2.4")
 	};
 }
 //#endregion
 //#region src/historyCommand.ts
-const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json]  (N = last N sessions, 1-20, default 5)";
+/**
+* `/eval-history` — grade the last N sessions in this workspace and show the trend.
+*
+* Completes the regression-tracking story: `/eval-diff` compares two sessions
+* you already know about; this command finds them for you (via
+* `ctx.sessionQuery.listSessions()`, same seam as `/archive` in
+* dsh-session-export) and answers "is the trend improving?" out of the box.
+*
+* @module dsh-session-eval/historyCommand
+*/
+const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json] [--out PATH]  (N = last N sessions, 1-20, default 5)";
 /** Parse /eval-history input; returns args or a usage-error string. */
 function parseEvalHistoryArgs(rawInput) {
 	const tokens = rawInput.trim().split(/\s+/).filter((t) => t.length > 0);
 	let count = 5;
 	let json = false;
 	let sawCount = false;
-	for (const token of tokens) {
+	let out;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--out") {
+			if (out !== void 0) return `--out may be given only once.\n${EVAL_HISTORY_USAGE}`;
+			const path = tokens[++i];
+			if (!path || path.startsWith("--")) return `--out requires a path.\n${EVAL_HISTORY_USAGE}`;
+			out = path;
+			continue;
+		}
 		if (token === "--json") {
 			if (json) return `--json may be given only once.\n${EVAL_HISTORY_USAGE}`;
 			json = true;
@@ -392,7 +413,8 @@ function parseEvalHistoryArgs(rawInput) {
 	}
 	return {
 		count,
-		json
+		json,
+		...out !== void 0 ? { out } : {}
 	};
 }
 function toMillis(createdAt) {
@@ -441,10 +463,6 @@ async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
 		id: String(header.id),
 		createdAt: toMillis(header.createdAt)
 	})).sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0)).slice(-parsed.count);
-	if (recent.length === 0) return {
-		kind: "success",
-		text: "No sessions found in this workspace; nothing to grade."
-	};
 	const entries = [];
 	for (const header of recent) {
 		let events;
@@ -468,16 +486,25 @@ async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
 		entries,
 		trend: entries.length >= 2 ? compareSessions(entries[0].metrics, entries[entries.length - 1].metrics) : null
 	};
-	if (parsed.json === true) return {
-		kind: "success",
-		text: JSON.stringify({
-			generator: `dsh-session-eval v${VERSION}`,
-			report
-		}, null, 2)
-	};
+	const text = parsed.json ? JSON.stringify({
+		generator: `dsh-session-eval v${VERSION}`,
+		report
+	}, null, 2) : renderHistory(report);
+	if (parsed.out !== void 0) {
+		const path = resolve(typeof ownCwd === "string" ? ownCwd : process.cwd(), parsed.out);
+		try {
+			const output = parsed.json ? text : `\`\`\`text\n${text}\n\`\`\``;
+			await writeFile(path, `${output}\n`, "utf8");
+		} catch (error) {
+			return {
+				kind: "error",
+				text: `Could not write history report to ${path}: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+	}
 	return {
 		kind: "success",
-		text: renderHistory(report)
+		text
 	};
 }
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-session-eval",
   "description": "Retrospective agent-session evaluation for DeepSeek Harness: deterministic grade cards from persisted session logs, cross-session regression diffs, era comparison — no benchmark runs, no LLM judges.",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },