dsh-session-recall 0.7.5 → 0.7.7

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 ci && 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 | |
 |---|---|
@@ -192,22 +208,12 @@ Warm searches run sub-millisecond to ~1.5 ms against the on-disk index. Cold sta
 ## Development
 
 ```sh
-npm install
+npm ci
 npm run typecheck   # tsc --noEmit
 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,51 @@ 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 ci && 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)。
+
+## 模型看到什么
+
+```
+recall({ query })                        → 每个会话返回最强命中事件，默认只搜当前项目
+recall({ query, all_projects: true })    → 搜索本机全部会话
+recall({ query, session_id })            → 只搜指定会话内的事件
+recall({ query, limit, cursor })         → 翻页
+```
+
+每条命中带会话 id、标题（尽力补全）、日期、命中摘录；结果在 Web UI 里渲染成原生搜索卡片（`SearchMatchesResultView`）。因为 FTS 的 `unicode61` 分词器会把连续中文当成一个 token，短中文短语一旦嵌在长句里就匹配不到索引——所以 CJK 查询零命中时会自动回退到对会话文本的子串扫描（走 `sessionQuery.filterEvents` 的字面文本子句），空格拆出的每个词都必须命中，因此 `简历 模板` 也能找回 `简历模板`；hint 会说明这条回退路径是否命中。
+
+## 授权边界（官方明确留给工具层的责任）
+
+`sessionQuery` 是可信基础设施——它能读所有会话。所以本工具自己约束每一次调用：
+
+- 默认注入 `sessionFilters: [{ kind: 'cwd', values: [<调用方 agent 的 cwd>] }]`——只搜同一项目目录下开始的会话；
+- `all_projects: true` 才放宽到全机，且部署方可以用 `allowAllProjects: false` 直接禁用该参数。
 
 ## 项目定位
 
@@ -32,24 +70,6 @@ recall：上周给简历选的什么字体来着？
 
 如果你要做长期记忆编排，请用记忆框架；如果你要做可审计、有权限边界的历史检索，请用本插件。
 
-## 竞品视角
-
-| 能力重心 | 记忆框架类插件 | 通用检索类插件 | `dsh-session-recall` |
-|---|---|---|---|
-| 检索对象 | 推导后的记忆结构 | 视实现而定 | **原始会话事件文本** |
-| 范围控制 | 框架内约束 | 常较粗粒度 | **默认 cwd + 显式 `all_projects` 闸门** |
-| CJK 体验 | 视实现而定 | 常受分词限制 | **FTS + CJK 零命中子串回退** |
-| 输出契约 | 框架内部格式 | 不统一 | **类型化 `recall` 结果 + 稳定 hint** |
-
-命名与边界说明（2026-09）：
-
-- 本插件与 **`dsh-recall-plugin` 无关**——那是"撤回消息"插件（把工作区与对话回退到某条消息发出之前）。
-- 本插件是 **`dsh-recall` 的后继者**——后者是更早的会话检索插件（最后更新 2026-08-21）；本插件在其方向上续写：持久 FTS5 索引、中文回退、审批闸门、谱系鉴权。
-- 本插件与 **`dsh-mnemon` 等记忆框架互补**：它们做写入侧的记忆编排；本插件保持只读检索层，只读原始会话日志，不写任何记忆存储。
-## 路线图
-
-- **P2：证据联动导出** —— 命中后可一键触发对应会话导出。
-
 ## 为什么做这个
 
 官方 `@deepseek-ai/dsh-session-query` 的 README 自己列出了缺口：
@@ -68,23 +88,20 @@ recall：上周给简历选的什么字体来着？
 
 记忆类插件用 LLM 提取结构化笔记（有损、费 token）；`recall` 检索的是**原始对话记录**——零提取、零损失、装完当天就能搜全部历史。
 
-## 模型看到什么
-
-```
-recall({ query })                        → 每个会话返回最强命中事件，默认只搜当前项目
-recall({ query, all_projects: true })    → 搜索本机全部会话
-recall({ query, session_id })            → 只搜指定会话内的事件
-recall({ query, limit, cursor })         → 翻页
-```
-
-每条命中带会话 id、标题（尽力补全）、日期、命中摘录；结果在 Web UI 里渲染成原生搜索卡片（`SearchMatchesResultView`）。因为 FTS 的 `unicode61` 分词器会把连续中文当成一个 token，短中文短语一旦嵌在长句里就匹配不到索引——所以 CJK 查询零命中时会自动回退到对会话文本的子串扫描（走 `sessionQuery.filterEvents` 的字面文本子句），空格拆出的每个词都必须命中，因此 `简历 模板` 也能找回 `简历模板`；hint 会说明这条回退路径是否命中。
+## 竞品视角
 
-## 授权边界（官方明确留给工具层的责任）
+| 能力重心 | 记忆框架类插件 | 通用检索类插件 | `dsh-session-recall` |
+|---|---|---|---|
+| 检索对象 | 推导后的记忆结构 | 视实现而定 | **原始会话事件文本** |
+| 范围控制 | 框架内约束 | 常较粗粒度 | **默认 cwd + 显式 `all_projects` 闸门** |
+| CJK 体验 | 视实现而定 | 常受分词限制 | **FTS + CJK 零命中子串回退** |
+| 输出契约 | 框架内部格式 | 不统一 | **类型化 `recall` 结果 + 稳定 hint** |
 
-`sessionQuery` 是可信基础设施——它能读所有会话。所以本工具自己约束每一次调用：
+命名与边界说明（2026-09）：
 
-- 默认注入 `sessionFilters: [{ kind: 'cwd', values: [<调用方 agent 的 cwd>] }]`——只搜同一项目目录下开始的会话；
-- `all_projects: true` 才放宽到全机，且部署方可以用 `allowAllProjects: false` 直接禁用该参数。
+- 本插件与 **`dsh-recall-plugin` 无关**——那是"撤回消息"插件（把工作区与对话回退到某条消息发出之前）。
+- 本插件是 **`dsh-recall` 的后继者**——后者是更早的会话检索插件（最后更新 2026-08-21）；本插件在其方向上续写：持久 FTS5 索引、中文回退、审批闸门、谱系鉴权。
+- 本插件与 **`dsh-mnemon` 等记忆框架互补**：它们做写入侧的记忆编排；本插件保持只读检索层，只读原始会话日志，不写任何记忆存储。
 
 ## 安装（out-of-tree 插件）
 
@@ -170,7 +187,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。
 
 | 语料 | |
 |---|---|
@@ -191,7 +208,7 @@ dsh plugin --profile web add github:kittimzhe/dsh-session-recall
 ## 开发
 
 ```sh
-npm install
+npm ci
 npm run typecheck   # tsc --noEmit
 npm test            # vitest run
 npm run bundle      # tsdown → lib/

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.7",
   "publishConfig": {
     "access": "public"
   },