dsh-session-recall 0.7.5 → 0.7.6

package/README.md

@@ -6,7 +6,7 @@ English | [中文](https://github.com/kittimzhe/dsh-session-recall/blob/main/REA
 
 Deterministic cross-session full-text retrieval for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): the model-facing `recall` tool lets the agent **search its own past session transcripts** — "that bug we fixed last week", "the font we chose for my resume" — through the trusted `ctx.sessionQuery` seam.
 
-## Quick Start
+## Install
 
 **Requirements**: Node.js 20 or 22 · a DeepSeek Harness profile that mounts the `tools` and `sessionQuery` services (the shipped `web` / `agent` profiles qualify).
 
@@ -14,42 +14,61 @@ Deterministic cross-session full-text retrieval for [DeepSeek Harness](https://g
 dsh plugin --profile web add dsh-session-recall
 ```
 
+## Try it once
+
 The first search builds a persistent FTS5 index automatically — no extra setup. In a session, just ask naturally:
 
 ```text
 recall: which font did we pick for the resume last week?
 ```
 
-Full details — GitHub install route, `cordis.patch.yml` snippet, configuration — in [Install](#install-out-of-tree-plugin) below.
+The tool surfaces the best-matching event per session — each hit carries the session id, a best-effort title, the date, and a match snippet, rendered as a native search card in the Web UI.
 
-## Positioning
+## The session toolchain
 
-`dsh-session-recall` is a **transcript retrieval layer** focused on correctness and control.
+| Plugin | Layer | Answers |
+|---|---|---|
+| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | Evidence | "What exactly happened in this session?" |
+| **`dsh-session-recall`** | **Memory** | **"What did I do before, and where is it?"** |
+| [`dsh-session-eval`](https://www.npmjs.com/package/dsh-session-eval) | Measurement | "Was that session good? Is the trend improving?" |
 
-- It returns evidence from original session logs, not synthesized summaries.
-- It enforces explicit retrieval scope (cwd by default, opt-in widening).
-- It favors deterministic behavior over "smart" but lossy memory extraction.
+All three read through the same trusted `ctx.sessionQuery` seam.
 
-If you need agent memory orchestration, use a memory framework; if you need bounded, auditable lookup over historical transcripts, use this plugin.
+## Contributing
 
-## Competitive context
+- **Local dev**: `npm install && npm run typecheck && npm test && npm run bundle` (Node 20 or 22).
+- **Start in the source**: [`src/tool.ts`](src/tool.ts) (tool contract), [`src/rank.ts`](src/rank.ts) (recency re-ranking, pinned cwds), [`src/redact.ts`](src/redact.ts) (redaction patterns), [`src/resilient.ts`](src/resilient.ts) (degraded raw-scan). The full source map is in [CONTRIBUTING.md](CONTRIBUTING.md).
+- **Open gaps**: [#6](https://github.com/kittimzhe/dsh-session-recall/issues/6) (redaction patterns), [#7](https://github.com/kittimzhe/dsh-session-recall/issues/7) (tie-break order) — or browse [issues labeled `good first issue`](https://github.com/kittimzhe/dsh-session-recall/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+- **Roadmap**: [P2: evidence handoff — expose `sessionId` + transcript path from recall hits (#8)](https://github.com/kittimzhe/dsh-session-recall/issues/8), acceptance criteria in the issue; post a comment before starting so effort is not duplicated.
+- **Rules**: behavior changes need tests; doc changes must update `README.md` and `README.zh.md` in sync; releases belong to the maintainer. Details: [CONTRIBUTING.md](CONTRIBUTING.md).
 
-| Capability focus | Memory frameworks | Generic transcript search | `dsh-session-recall` |
-|---|---|---|---|
-| Retrieval target | Derived memory objects | Varies by implementation | **Original session transcript events** |
-| Scope control | Framework-specific | Often coarse | **cwd-scoped default + explicit `all_projects`, `since_days`, `tools`, `errors_only` gate** |
-| CJK behavior | Framework-specific | Often tokenizer-limited | **FTS + CJK zero-hit substring fallback** |
-| Output contract | Usually framework-native | Varies | **Typed `recall` result with stable fields/hints** |
+## What the model gets
 
-Name & scope notes (2026-09):
+```
+recall({ query })                        → best-matching event per session, current project only
+recall({ query, all_projects: true })    → search every session on the machine
+recall({ query, session_id })            → search the events of one session
+recall({ query, limit, cursor })         → page through results
+```
 
-- This plugin is **unrelated to `dsh-recall-plugin`** — that plugin is message undo/rewind (restoring workspace and conversation to before a message was sent).
-- It **succeeds `dsh-recall`** — an earlier transcript-search plugin (last release 2026-08-21) with a similar goal; this plugin continues the line with persistent FTS5 indexing, CJK fallback, approval gates, and lineage-scoped authorization.
-- It **complements memory frameworks** such as `dsh-mnemon` (write-side memory orchestration): this plugin stays a read-only retrieval layer over original session logs and makes no writes to any memory store.
+Each hit carries the session id, title (best-effort), date, and a match snippet; the result renders as a native search card in the Web UI (`SearchMatchesResultView`). Because the FTS `unicode61` tokenizer indexes an uninterrupted CJK run as a single token, a short Chinese phrase inside a longer sentence would otherwise never match the index — so a zero-hit CJK query automatically falls back to a substring scan over session text (the `sessionQuery.filterEvents` literal text clause). Every whitespace-separated term must match, so `简历 模板` still recovers `简历模板`; the hint reports when that path matched.
 
-## Roadmap
+## Scoping (the authorization gap)
+
+`sessionQuery` is trusted infrastructure — it can read every session. This tool therefore constrains each call itself:
 
-- **P2: evidence handoff** — one-click bridge to session export for matched sessions.
+- by default, `sessionFilters: [{ kind: 'cwd', values: [<calling agent's cwd>] }]` — only sessions started in the same project directory;
+- `all_projects: true` widens the scope, and only if the deployment allows it (`allowAllProjects: false` disables the argument).
+
+## Positioning
+
+`dsh-session-recall` is a **transcript retrieval layer** focused on correctness and control.
+
+- It returns evidence from original session logs, not synthesized summaries.
+- It enforces explicit retrieval scope (cwd by default, opt-in widening).
+- It favors deterministic behavior over "smart" but lossy memory extraction.
+
+If you need agent memory orchestration, use a memory framework; if you need bounded, auditable lookup over historical transcripts, use this plugin.
 
 ## Why
 
@@ -69,23 +88,20 @@ And the shipped web profile mounts its SQLite FTS5 backend with `openAt: never`
 
 Memory plugins extract structured notes with an LLM (lossy, costs tokens); `recall` searches the **original transcripts** — zero extraction, zero loss, works retroactively on day one.
 
-## What the model gets
-
-```
-recall({ query })                        → best-matching event per session, current project only
-recall({ query, all_projects: true })    → search every session on the machine
-recall({ query, session_id })            → search the events of one session
-recall({ query, limit, cursor })         → page through results
-```
-
-Each hit carries the session id, title (best-effort), date, and a match snippet; the result renders as a native search card in the Web UI (`SearchMatchesResultView`). Because the FTS `unicode61` tokenizer indexes an uninterrupted CJK run as a single token, a short Chinese phrase inside a longer sentence would otherwise never match the index — so a zero-hit CJK query automatically falls back to a substring scan over session text (the `sessionQuery.filterEvents` literal text clause). Every whitespace-separated term must match, so `简历 模板` still recovers `简历模板`; the hint reports when that path matched.
+## Competitive context
 
-## Scoping (the authorization gap)
+| Capability focus | Memory frameworks | Generic transcript search | `dsh-session-recall` |
+|---|---|---|---|
+| Retrieval target | Derived memory objects | Varies by implementation | **Original session transcript events** |
+| Scope control | Framework-specific | Often coarse | **cwd-scoped default + explicit `all_projects`, `since_days`, `tools`, `errors_only` gate** |
+| CJK behavior | Framework-specific | Often tokenizer-limited | **FTS + CJK zero-hit substring fallback** |
+| Output contract | Usually framework-native | Varies | **Typed `recall` result with stable fields/hints** |
 
-`sessionQuery` is trusted infrastructure — it can read every session. This tool therefore constrains each call itself:
+Name & scope notes (2026-09):
 
-- by default, `sessionFilters: [{ kind: 'cwd', values: [<calling agent's cwd>] }]` — only sessions started in the same project directory;
-- `all_projects: true` widens the scope, and only if the deployment allows it (`allowAllProjects: false` disables the argument).
+- This plugin is **unrelated to `dsh-recall-plugin`** — that plugin is message undo/rewind (restoring workspace and conversation to before a message was sent).
+- It **succeeds `dsh-recall`** — an earlier transcript-search plugin (last release 2026-08-21) with a similar goal; this plugin continues the line with persistent FTS5 indexing, CJK fallback, approval gates, and lineage-scoped authorization.
+- It **complements memory frameworks** such as `dsh-mnemon` (write-side memory orchestration): this plugin stays a read-only retrieval layer over original session logs and makes no writes to any memory store.
 
 ## Install (out-of-tree plugin)
 
@@ -171,7 +187,7 @@ Every result also carries a `diagnostics` object (v0.5): which engine produced t
 
 ## Benchmark
 
-Measured on a real headless profile (Node 25, Apple Silicon, warm filesystem cache).
+Measured on a real headless profile on the machine at hand (Node 25, Apple Silicon, warm filesystem cache) — indicative numbers, not a CI gate. Supported and CI-tested Node versions remain 20 and 22.
 
 | Corpus | |
 |---|---|
@@ -198,16 +214,6 @@ npm test            # vitest run
 npm run bundle      # tsdown → lib/
 ```
 
-## Session toolchain
-
-This plugin is one of three layers over the same trusted `ctx.sessionQuery` seam:
-
-| Plugin | Layer | Answers |
-|---|---|---|
-| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | Evidence | "What exactly happened in this session?" |
-| `dsh-session-recall` | Memory | "What did I do before, and where is it?" |
-| [`dsh-session-eval`](https://www.npmjs.com/package/dsh-session-eval) | Measurement | "Was that session good? Is the trend improving?" |
-
 ## License
 
 [MIT](https://github.com/kittimzhe/dsh-session-recall/blob/main/LICENSE)

package/README.zh.md

@@ -6,7 +6,7 @@
 
 DeepSeek Harness 的**确定性跨会话全文检索**插件：注册模型可调用的 `recall` 工具，让 agent 能**检索自己过往的会话原文**——"上周修的那个 bug"、"简历选的什么字体"——全部通过可信的 `ctx.sessionQuery` 缝完成。
 
-## 快速开始
+## 安装
 
 **环境要求**：Node.js 20 或 22 · 挂载了 `tools` 与 `sessionQuery` 服务的 DeepSeek Harness profile（官方 `web` / `agent` profile 均满足）。
 
@@ -14,13 +14,33 @@ DeepSeek Harness 的**确定性跨会话全文检索**插件：注册模型可
 dsh plugin --profile web add dsh-session-recall
 ```
 
+## 试一次
+
 首次搜索会自动构建持久化 FTS5 索引——无需额外步骤。会话里直接问：
 
 ```text
 recall：上周给简历选的什么字体来着？
 ```
 
-完整细节（GitHub 安装方式、`cordis.patch.yml` 片段、配置项）见下文「安装」一节。
+工具会按会话返回最强命中——每条带会话 id、尽力补全的标题、日期与命中摘录，在 Web UI 里渲染成原生搜索卡片。
+
+## 会话工具链
+
+| 插件 | 层 | 回答的问题 |
+|---|---|---|
+| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | 证据层 | "这个会话到底发生了什么？" |
+| **`dsh-session-recall`** | **记忆层** | **"我以前做过什么，在哪？"** |
+| [`dsh-session-eval`](https://www.npmjs.com/package/dsh-session-eval) | 评测层 | "刚才的会话好不好？趋势在变好吗？" |
+
+三者都通过同一个受信的 `ctx.sessionQuery` 接缝读取。
+
+## 贡献
+
+- **本地开发**：`npm install && npm run typecheck && npm test && npm run bundle`（Node 20 或 22）。
+- **源码入口**：[`src/tool.ts`](src/tool.ts)（工具契约）、[`src/rank.ts`](src/rank.ts)（新近度重排、置顶项目）、[`src/redact.ts`](src/redact.ts)（脱敏规则）、[`src/resilient.ts`](src/resilient.ts)（降级直扫）。完整源码地图见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+- **当前缺口**：[#6](https://github.com/kittimzhe/dsh-session-recall/issues/6)（脱敏规则扩展）、[#7](https://github.com/kittimzhe/dsh-session-recall/issues/7)（同分排序钉死）——或浏览 [`good first issue` 标签](https://github.com/kittimzhe/dsh-session-recall/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
+- **路线图**：[P2：证据联动——recall 命中携带 sessionId + 转录路径（#8）](https://github.com/kittimzhe/dsh-session-recall/issues/8)，验收标准见 issue；认领前请先留言避免撞车。
+- **规矩**：行为变更必须带测试；文档必须 `README.md` 与 `README.zh.md` 同步改；版本发布由维护者执行。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ## 项目定位
 
@@ -46,10 +66,6 @@ recall：上周给简历选的什么字体来着？
 - 本插件与 **`dsh-recall-plugin` 无关**——那是"撤回消息"插件（把工作区与对话回退到某条消息发出之前）。
 - 本插件是 **`dsh-recall` 的后继者**——后者是更早的会话检索插件（最后更新 2026-08-21）；本插件在其方向上续写：持久 FTS5 索引、中文回退、审批闸门、谱系鉴权。
 - 本插件与 **`dsh-mnemon` 等记忆框架互补**：它们做写入侧的记忆编排；本插件保持只读检索层，只读原始会话日志，不写任何记忆存储。
-## 路线图
-
-- **P2：证据联动导出** —— 命中后可一键触发对应会话导出。
-
 ## 为什么做这个
 
 官方 `@deepseek-ai/dsh-session-query` 的 README 自己列出了缺口：
@@ -170,7 +186,7 @@ dsh plugin --profile web add github:kittimzhe/dsh-session-recall
 
 ## 基准
 
-真机 headless profile 实测（Node 25，Apple Silicon，暖文件缓存）。
+真机 headless profile 实测（手头机器为 Node 25、Apple Silicon、暖文件缓存）——数字仅供参考，不是 CI 门槛；受支持并经 CI 测试的版本仍是 Node 20 与 22。
 
 | 语料 | |
 |---|---|

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-session-recall",
   "description": "Deterministic cross-session transcript retrieval for DeepSeek Harness: the model-facing `recall` tool searches past session logs with explicit scope control",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "publishConfig": {
     "access": "public"
   },