dsh-session-eval 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
+## 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.
+
 # Changelog
 
+## 0.2.2 — 2026-10-02
+
+Contributor-first docs release.
+
+- Install command fixed to `dsh plugin --profile web add dsh-session-eval` (a global npm install does not mount the slash commands).
+- README.zh.md language switch fixed (English link restored, toggle on top); sample outputs bumped to the shipped version.
+- 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
 
 - **Fix: ship the bundle overlay.** v0.2.0 declared `dsh.bundle.patch: ./cordis.patch.yml`

package/README.md

@@ -11,41 +11,38 @@ English | [中文](README.zh.md)
 
 No benchmark suites to author. No LLM judges. No new runs. Every grade is a fixed, documented threshold over persisted session logs — fully reproducible.
 
-## The measurement layer of the session toolchain
-
-| Plugin | Layer | Answers |
-|---|---|---|
-| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | Evidence | "What exactly happened in this session?" |
-| [`dsh-session-recall`](https://www.npmjs.com/package/dsh-session-recall) | Memory | "What did I do before, and where is it?" |
-| **`dsh-session-eval`** | **Measurement** | **"Was that session good? Is the trend improving?"** |
+## Install
 
-All three read through the same trusted `ctx.sessionQuery` seam, so any persistence backend (JSONL or SQLite) works without touching raw artifacts.
+**Requirements**: Node.js 20 or 22 · a DeepSeek Harness profile that mounts the `commands` and `sessionQuery` services (the shipped `web` / `agent` profiles qualify).
 
-## How it differs from benchmark-style evaluation
+```bash
+dsh plugin --profile web add dsh-session-eval
+```
 
-| | `dsh-eval` (benchmark) | `dsh-session-eval` (this) |
-|---|---|---|
-| Evaluates | Runs you launch ahead of time | Sessions that already happened |
-| Setup | Author benchmark YAML + cases | None — read existing logs |
-| Judge | Metric folding over trials | Fixed thresholds, deterministic |
-| Best at | Pre-deploy benchmarks | Regression tracking over real work |
+Or from GitHub:
 
-Both are useful; they don't compete. Benchmarks test what you *predicted*; retrospective evaluation watches what *actually happened*.
+```bash
+dsh plugin --profile web add github:kittimzhe/dsh-session-eval
+```
 
-## Quick Start
+The bundle overlay mounts `/eval`, `/eval-diff`, and `/eval-history`. If you maintain your own `cordis.patch.yml`, keep this row:
 
-```bash
-npm install -g dsh-session-eval
+```yaml
+- insert:
+    - id: session-eval
+      name: 'dsh-session-eval'
 ```
 
-Then in DeepSeek Harness:
+## Try it once
+
+In DeepSeek Harness:
 
 ```text
 /eval
 ```
 
 ```text
-Session eval — a1b2c3d4… (dsh-session-eval v0.2.0)
+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)
@@ -54,45 +51,50 @@ Notes:
   • Wall time 41.2 min over 23 turns.
 ```
 
-Grade another session, or emit machine-readable JSON:
+## The measurement layer of the session toolchain
 
-```text
-/eval --id <sessionId> --json
-```
+| Plugin | Layer | Answers |
+|---|---|---|
+| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | Evidence | "What exactly happened in this session?" |
+| [`dsh-session-recall`](https://www.npmjs.com/package/dsh-session-recall) | Memory | "What did I do before, and where is it?" |
+| **`dsh-session-eval`** | **Measurement** | **"Was that session good? Is the trend improving?"** |
 
-Compare two sessions — the regression workflow:
+All three read through the same trusted `ctx.sessionQuery` seam, so any persistence backend (JSONL or SQLite) works without touching raw artifacts.
 
-```text
-/eval-diff <beforeSessionId> <afterSessionId>
-```
+## Contributing
 
-```text
-Session diff — a1b2c3d4… → e5f6a7b8… (dsh-session-eval v0.2.0)
-Overall: regressed — 0 improved, 2 regressed, 1 flat.
-  Reliability   2.1% → 11.8%   regressed
-  Re-ask        0.5 → 3.2      regressed
-  Tool load     3.8 → 4.1      flat
-```
+- **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**: [#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).
 
-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.
+## How it differs from benchmark-style evaluation
 
-See the whole trend — no ids to hunt for:
+| | `dsh-eval` (benchmark) | `dsh-session-eval` (this) |
+|---|---|---|
+| Evaluates | Runs you launch ahead of time | Sessions that already happened |
+| Setup | Author benchmark YAML + cases | None — read existing logs |
+| Judge | Metric folding over trials | Fixed thresholds, deterministic |
+| Best at | Pre-deploy benchmarks | Regression tracking over real work |
 
-```text
-/eval-history        # last 5 sessions in this workspace
-/eval-history 12     # last 12
-```
+Both are useful; they don't compete. Benchmarks test what you *predicted*; retrospective evaluation watches what *actually happened*.
 
-```text
-Session history — last 5 in this workspace
-  2026-09-20 14:02  a1b2c3d4…  B   4 turns, 9 tools
-  2026-09-21 09:15  c3d4e5f6…  A   5 turns, 11 tools
-  2026-09-22 17:44  e5f6a7b8…  A   3 turns, 7 tools
-Trend (first → last): improved — 2 improved, 0 regressed, 1 flat.
-```
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/eval` | Grade card for the current session |
+| `/eval --id <sessionId>` | Grade a specific session |
+| `/eval --json` | Machine-readable metrics + card |
+| `/eval-diff <beforeId> <afterId>` | Regression comparison, noise-tolerant |
+| `/eval-diff … --json` | Machine-readable trend report |
+| `/eval-history [N]` | Grade the last N sessions in this workspace and show the trend |
+| `/eval-history … --json` | Machine-readable history report |
 
 `/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.
+
 ## Dimensions & thresholds
 
 All grades derive from three deterministic metrics. `n/a` when the session lacks the relevant activity.
@@ -105,7 +107,7 @@ All grades derive from three deterministic metrics. `n/a` when the session lacks
 
 ¹ A *correction signal* is each extra user message inside a consecutive-user run — the human re-asking before any assistant reply, a behavioral proxy for "the agent didn't get it right the first time."
 
-`Overall` is the **worst** graded dimension — conservative by design. Thresholds are constants in [`src/grade.ts`](src/grade.ts); they will be configurable in a future release.
+`Overall` is the **worst** graded dimension — conservative by design. Thresholds are constants in [`src/grade.ts`](src/grade.ts); making them configurable is on the roadmap (see issues).
 
 Diff verdicts include a noise band (±2pp error rate, ±0.5 re-ask, ±1 tool load) so trivial jitter doesn't cry regression.
 
@@ -113,27 +115,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.
 
-## Commands
-
-| Command | Effect |
-|---|---|
-| `/eval` | Grade card for the current session |
-| `/eval --id <sessionId>` | Grade a specific session |
-| `/eval --json` | Machine-readable metrics + card |
-| `/eval-diff <beforeId> <afterId>` | Regression comparison, noise-tolerant |
-| `/eval-diff … --json` | Machine-readable trend report |
-| `/eval-history [N]` | Grade the last N sessions in this workspace and show the trend |
-| `/eval-history … --json` | Machine-readable history report |
-
 ## Development
 
 ```bash
-npm install
+npm ci
 npm run typecheck   # tsc --noEmit
-npm test            # vitest run — 24 tests
+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

@@ -1,6 +1,9 @@
 # dsh-session-eval
 
+[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)
 
@@ -8,40 +11,89 @@
 
 不需要编写基准测试集，没有 LLM 裁判，不需要跑新任务。所有等级 = 持久化会话日志上的固定公开阈值——完全可复现。
 
-English | [中文](README.zh.md)
+## 安装
+
+**环境要求**：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 里：
+
+```text
+/eval
+```
+
+```text
+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)
+  Tool load     B    3.8 tool calls per turn
+Notes:
+  • Wall time 41.2 min over 23 turns.
+```
 
 ## 会话工具链的评测层
 
 | 插件 | 层 | 回答的问题 |
 |---|---|---|
-| `dsh-session-export` | 证据层 | "这个会话到底发生了什么？" |
-| `dsh-session-recall` | 记忆层 | "我以前做过什么，在哪？" |
+| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | 证据层 | "这个会话到底发生了什么？" |
+| [`dsh-session-recall`](https://www.npmjs.com/package/dsh-session-recall) | 记忆层 | "我以前做过什么，在哪？" |
 | **`dsh-session-eval`** | **评测层** | **"刚才的会话好不好？趋势在变好吗？"** |
 
 三者都通过同一个可信的 `ctx.sessionQuery` 缝读取，JSONL / SQLite 等任何持久化后端均可使用。
 
+## 贡献
+
+- **本地开发**：`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)。
+- **当前缺口**：[#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）的区别
 
-- `dsh-eval`：**前瞻**——预先写好基准 YAML，跑无头评测，评的是"你预测到的场景"
-- 本插件：**回溯**——直接读存量日志，评的是"真实发生的工作"，零准备、零额外 token
+| | `dsh-eval`（基准） | `dsh-session-eval`（本插件） |
+|---|---|---|
+| 评什么 | 预先发起的运行 | 已经发生的会话 |
+| 准备 | 编写基准 YAML + 用例 | 零——直接读存量日志 |
+| 裁判 | 跨 trial 的指标折叠 | 固定阈值，确定性 |
+| 擅长 | 上线前基准 | 真实工作的回归追踪 |
 
-两者互补而非竞争。
+两者互补而非竞争：基准测你*预测到*的场景，回溯评测看*实际发生*的工作。
 
-## 快速开始
+## 命令
 
-```bash
-npm install -g dsh-session-eval
-```
+| 命令 | 效果 |
+|---|---|
+| `/eval` | 当前会话等级卡 |
+| `/eval --id <会话ID>` | 指定会话 |
+| `/eval --json` | 机器可读指标 + 等级卡 |
+| `/eval-diff <前ID> <后ID>` | 回归对比（带噪声带） |
+| `/eval-diff … --json` | 机器可读趋势报告 |
+| `/eval-history [N]` | 本工作区最近 N 个会话成绩单 + 首末趋势 |
+| `/eval-history … --json` | 机器可读历史报告 |
 
-```text
-/eval                 # 当前会话等级卡
-/eval --id <会话ID>    # 指定会话
-/eval-diff <前> <后>   # 回归对比（换插件/prompt 前后各评一次）
-/eval-history         # 本工作区最近 5 个会话的成绩单 + 首末趋势
-/eval-history 12      # 最近 12 个
-```
+`/eval-history` 通过与 `/archive` 相同的 `sessionQuery` 接缝自动找到会话（按当前工作区 `cwd` 过滤），逐个评级，并把首尾两个会话做趋势对比——不用再手动挑 id。已经知道两个关键 id 时用 `/eval-diff`。
 
-`/eval-history` 通过与 `/archive` 相同的 `sessionQuery` 接缝自动找到会话（按当前工作区 `cwd` 过滤），逐个评级，并把首尾两个会话做趋势对比——不用再手动挑 id。
+典型用法：换插件或 prompt 前后各评十个会话；`Reliability` 持续回归 = 改动伤害了真实工作的早期预警。
 
 ## 维度与阈值（确定性，无裁判）
 
@@ -53,7 +105,9 @@ npm install -g dsh-session-eval
 
 ¹ 纠正信号 = 连续用户消息中多出的那条（agent 还没回复用户就重问）——"第一次没做对"的行为学代理指标。
 
-总评 = 最差维度（保守设计）。Diff 判定带噪声带（错误率 ±2pp 等），微小抖动不会误报回归。
+总评 = 最差维度（保守设计）。阈值是 [`src/grade.ts`](src/grade.ts) 中的常量；可配置化在路线图上（见 issue）。
+
+Diff 判定带噪声带（错误率 ±2pp、Re-ask ±0.5、工具负载 ±1），微小抖动不会误报回归。
 
 ## 确定性保证
 
@@ -62,10 +116,16 @@ npm install -g dsh-session-eval
 ## 开发
 
 ```bash
-npm install && npm run typecheck && npm test   # 24 个测试
-npm run bundle
+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

@@ -177,7 +177,7 @@ declare function executeEvalHistory(ctx: Context, invocation: CommandInvocation,
  *
  * @module dsh-session-eval/version
  */
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.2.3";
 //#endregion
 //#region src/index.d.ts
 declare const name = "session-eval";

package/lib/index.js

@@ -227,7 +227,7 @@ function compareSessions(before, after) {
 *
 * @module dsh-session-eval/version
 */
-const VERSION = "0.2.1";
+const VERSION = "0.2.3";
 //#endregion
 //#region src/evalCommand.ts
 const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--json]";
@@ -327,14 +327,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.1",
+			generator: "dsh-session-eval v0.2.3",
 			metrics,
 			card
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderCard(card, "dsh-session-eval v0.2.1")
+		text: renderCard(card, "dsh-session-eval v0.2.3")
 	};
 }
 /** Execute /eval-diff against the session-query seam. */
@@ -358,13 +358,13 @@ async function executeEvalDiff(ctx, invocation, seam = ctx.sessionQuery) {
 	if (parsed.json === true) return {
 		kind: "success",
 		text: JSON.stringify({
-			generator: "dsh-session-eval v0.2.1",
+			generator: "dsh-session-eval v0.2.3",
 			report
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderTrend(report, "dsh-session-eval v0.2.1")
+		text: renderTrend(report, "dsh-session-eval v0.2.3")
 	};
 }
 //#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.1",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public"
   },