@yolk_vat-y/dsh-project-memory 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.3.2 (2026-08-31)
+
+### TS Compiler API 增强器 (Phase 2 L2/L3)
+- **L2 语义增强层**：用户项目安装 `typescript`（`npm i -D typescript`）后，插件自动激活，利用 TS Compiler API 推导返回类型、实例化泛型、提取接口与类型别名、丰富箭头函数签名
+- **L3 磁盘缓存层**：增强结果按文件内容 SHA256 哈希缓存至 `.dsh-project-memory/type-cache/<hash>.json`，冷启动毫秒级复用，跨会话持久化
+- **三级优先级队列**：P0 ACTIVE（`fs/observed` 读文件瞬间）> P1 RECENT（`watch` 变更后）> P2 BATCH（`index_repo` 批量）> P3 BACKLOG（启动补全历史），`setImmediate` 每任务后让出事件循环
+- **零配置、零感知**：装 TS 重启 dsh 即可；无 TS 或 `enableTypeScript: false` 时优雅回退 L1 正则；TS 6.x/7.x 检测到警告并回退 L1
+- **解析策略**：单文件 `createProgram`（快 10x），`createRequire(import.meta.url)` 兼容 ESM，解析优先级：配置 `tsPath` → 项目 cwd 向上 `node_modules/typescript` → 插件自身 `node_modules`
+- **新增配置**：`tsPath`（可选指定 TS 路径）、`enableTypeScript`（默认 true，设 false 彻底禁用）
+- **扩展名支持**：新增 `.mts` `.cts`
+- **文档同步**：README.md / README.zh-CN.md 新增功能介绍与配置表
+- **依赖升级**：cordis 4.0.2、schemastery 3.18.2、dsh-tools/llm 0.1.2-alpha.2
+
+## Unreleased
+
+### 符号层：只存身份牌，不存行为
+- `src/symbols.js` `buildSymbol`：删除 `summary` 废话字段；`text` 不再截断，保存完整声明行（含签名）；返回一行身份牌 `fn(a: A, b: B): R — file.ts:42`；删除冗余 `sig` 字段
+
+### 文档层：答案级摘要 + 自报盲区
+- `src/llm.js` `extractDocEntry`：新增 `blindSpots` 字段（自报盲区，如 `// 未覆盖：部署细节、性能基准、v0.2 前 API`）；Prompt 要求 LLM 返回 `blindSpots`；摘要通过 `summarizeText()` 截断至 300 字符；`blindSpots` 追加在摘要末尾 `// 未覆盖：...`
+- `src/doc-pipeline.js` `buildDocEntries`：新增 `hash` 字段（SHA256 内容哈希，用于更新检测）；新增 `blindSpots` 字段存入分片
+
+## 0.3.1 (2026-08-30)
+
+### 存储：相对路径存储
+- Entry 存相对路径（如 `src/main.js`），查询时按项目根解析绝对路径；项目搬家仅在根目录变更时需重新索引，兼容旧绝对路径 entry
+- 所有写入路径（`index_doc` / `index_repo` / `watch` / `lazy`）统一传相对路径给构建函数
+- `scanSymbols` / `buildDocEntries` 兼容旧签名（绝对路径 entry 仍可读）
+
+### 设计取舍同步
+- 移除「绝对路径引用」项，该限制已由相对路径存储方案解决
+
 ## 0.3.0 (2026-08-29)
 
 ### 存储：无锁同步事务重构

package/README.md

@@ -4,19 +4,21 @@
 
 [![ci](https://github.com/00080000/dsh-project-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/00080000/dsh-project-memory/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![npm](https://img.shields.io/npm/v/@yolk_vat-y/dsh-project-memory)](https://www.npmjs.com/package/@yolk_vat-y/dsh-project-memory) [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/00080000/dsh-project-memory) [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-Persistent project memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(dsh) agents. Indexes documents (PDF / Markdown / txt) and code symbols into a per-workspace store, refreshes them automatically, and recalls them with source citations — documents are cross-linked to the code symbols they reference.
+Persistent project memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(dsh) agents. **Memorizes** documents (PDF / Markdown / txt) and code symbols into a per-workspace store, refreshes them automatically, and **recalls** them with source citations — documents are cross-linked to the code symbols they reference.
 
-> The plugin keeps a compact project index on disk, with every entry pointing to a concrete file and line — the agent can reorient quickly instead of re-reading the whole project.
+> The plugin keeps a compact project **memory** on disk, with every entry pointing to a concrete file and line — the agent can reorient quickly instead of re-reading the whole project.
 
 ## Features
 
-- **Document indexing** — PDF, Markdown, and plain text files are chunked and summarized by the LLM; each entry carries a `path:line` citation back to the source.
-- **Code symbol table** — function, class, and method names are extracted by a dependency-free source scanner (string/comment masking, multi-line signature joining, indentation-aware Python, class-method context), without LLM token usage.
-- **Automatic refresh** — a background poll (`watch_repo`) detects new or changed files by content hash and re-indexes only those.
-- **Read-time indexing** — files are indexed the moment the model actually reads them (`fs/observed`), so the index is a byproduct of normal work, not a separate upfront scan. Files that are never read are never indexed. The project root is detected by markers (`.git`, `package.json`, …), a README plus source directories, or the file's own directory as a last resort.
+- **Document memorization** — PDF, Markdown, and plain text files are chunked and summarized by the LLM; each entry carries a `path:line` citation back to the source.
+- **Code symbol memory** — function, class, and method names with full type signatures (generics, parameters, return types, overloads) are extracted by a dependency-free source scanner (string/comment masking, multi-line signature joining, indentation-aware Python, class-method context), without LLM token usage.
+- **Optional TypeScript semantic enhancement** — when `typescript` is installed in the user project (`npm i -D typescript`), the plugin automatically activates a second layer (L2) that uses the TS Compiler API to infer return types, resolve generics, extract interfaces and type aliases, and enrich arrow functions — all asynchronously in a priority queue (P0 on `fs/observed`, P1 on `watch`, P2 on `index_repo`). Results are cached on disk keyed by file content hash for instant cold-start reuse. Zero config: just install TS and restart dsh. Fully optional; if TS is absent or disabled via `enableTypeScript: false`, the plugin falls back to L1 regex-only extraction.
+- **Automatic refresh** — a background poll (`watch_repo`) detects new or changed files by content hash and re-memorizes only those.
+- **Read-time memorization** — files are memorized the moment the model actually reads them (`fs/observed`), so the memory is a byproduct of normal work, not a separate upfront scan. Files that are never read are never indexed. The project root is detected by markers (`.git`, `package.json`, …), a README plus source directories, or the file's own directory as a last resort.
 - **Doc ↔ code cross-linking** — when a document mentions a symbol, the match is recorded as a `reference`; querying a symbol also surfaces the documents that describe it.
-- **BM25 retrieval** — ranked search over documents, symbols, and experience notes, with optional LLM query expansion to handle vocabulary mismatch. **CJK-optimized**: precise phrase boost (3+ char phrases ×1.5 score on title/keywords match), synonym table (e.g. 数据库连接池 ↔ 连接池 ↔ DB pool), and CJK-aware word boundaries for doc↔symbol linking.
+- **BM25 memory recall** — ranked search over documents, symbols, and experience notes, with optional LLM query expansion to handle vocabulary mismatch. **CJK-optimized**: precise phrase boost (3+ char phrases ×1.5 score on title/keywords match), synonym table (e.g. 数据库连接池 ↔ 连接池 ↔ DB pool), and CJK-aware word boundaries for doc↔symbol linking.
 - **Experience notes** — problems → solutions; similar problems supersede instead of duplicating, and notes are returned only when a search matches. The note store is bounded: capacity scales with project size (clamped to 100–2000), and the oldest notes are pruned when the limit is exceeded. **Supersede tightened to bidirectional 0.7 overlap** (was 0.6); **experience `problem` field now participates in CJK phrase boost** for long-tail query recall.
+- **Lock-free sync transactions** — all writes (index / watch / remember / forget / watch_repo) go through synchronous transactions `store.commit(fn)`; fn succeeds then atomic write; JS single-threaded event loop guarantees no interleaving; `remember`/`forget` never blocked by watch re-indexing.
 - **Minimal dependencies** — pure JavaScript; the only runtime dependency is `pdfjs-dist` (PDF text extraction), no native builds required.
 - **Negligible overhead** — pure in-process operation; cold start <100 ms (5k files), typical project query median 2–3 ms (p99 < 7 ms); bottleneck is LLM summarization and PDF parsing, not the plugin.
 
@@ -25,11 +27,11 @@ Persistent project memory for [DeepSeek Harness](https://github.com/deepseek-ai/
 The design follows four principles:
 
 - **Volatility** — context is ephemeral; it is lost when a session is compacted.
-- **Persistence** — the index is stored on disk and survives compaction and new sessions.
-- **Compactness** — only summaries are stored; the index runs around 0.5% the size of the source it covers (8.8 MB of source → 49 KB of index in the example project), so retrieval replaces re-reading the full file.
-- **Verifiability** — hits carry a `path:line` citation where applicable, so the agent can confirm details against the source.
+- **Persistence** — the **memory** is stored on disk and survives compaction and new sessions.
+- **Compactness** — only summaries are stored; the **memory** runs around 0.5% the size of the source it covers (8.8 MB of source → 49 KB of index in the example project), so **recall** replaces re-reading the full file.
+- **Verifiability** — **recalls** carry a `path:line` citation where applicable, so the agent can confirm details against the source.
 
-Building the index does not require an upfront scan: files are indexed as the model reads them, so the index grows to cover exactly what has been worked with. Re-reading a file that has not changed is a no-op (content hash), so the index stays fresh with minimal ongoing overhead.
+Building the **memory** does not require an upfront scan: files are memorized as the model reads them, so the **memory** grows to cover exactly what has been worked with. Re-reading a file that has not changed is a no-op (content hash), so the **memory** stays fresh with minimal ongoing overhead.
 
 The store is per-project and follows the codebase: changed files are re-extracted by content hash, deleted files are removed. Experience notes are retrieval-only, so accumulation does not affect context.
 
@@ -52,7 +54,7 @@ dsh plugin --profile web add @yolk_vat-y/dsh-project-memory -w
 A prebuilt tarball is published with each release, installable without a build step:
 
 ```bash
-dsh plugin --profile web add /path/to/dsh-project-memory-0.3.0.tgz
+dsh plugin --profile web add /path/to/dsh-project-memory.tgz
 ```
 
 Each indexed project has its own store at `<root>/.dsh-project-memory/`. Add it to `.gitignore` if it should not be committed.
@@ -93,8 +95,8 @@ Stores created before v0.2.0 (single `entries.json` / `index.json`) migrate auto
 
 These are deliberate scope choices.
 
-- **In-process locking** — store writes are serialized per memory directory within one dsh process; two dsh instances sharing a project store is last-writer-wins. A cross-process lock would need a resident daemon, which conflicts with the pure-JS, no-background-service positioning, so multi-instance writes are explicitly unsupported.
-- **Watch poll holds the lock** — while the watcher re-indexes changed docs (LLM summarization), `remember`/`forget` queue behind it. Polling (mtime + content hash) instead of `fs.watch` events keeps behavior consistent across platforms; overlapping polls serialize on the same lock: safe, but they can pile up on very large diffs. Tune via `watchInterval`.
+- **Lock-free sync transactions** — all writes (index / watch / remember / forget / watch_repo) go through synchronous transactions `store.commit(fn)`; fn succeeds then atomic write; JS single-threaded event loop guarantees no interleaving; `remember`/`forget` never blocked by watch re-indexing. Multi-instance concurrent writes to the same project store are naturally idempotent via CAS + atomic commits. We don't fear multi-process DSH because DSH is built on Cordis, and Cordis's single-process architecture is foundational — changing it would be a breaking change for the entire ecosystem.
+- **Watch compute and commit separated** — watcher does heavy work (mtime/hash/symbol scan/LLM summary) outside transaction, then single `commit` applies atomically; `applyFileUpdate` uses CAS verification (unified null handling, delete skips hash compare) to prevent concurrent modification; failures rollback snapshot for next retry; indexing failures delete snapshot for auto-retry. Polling (mtime + content hash) instead of `fs.watch` events keeps behavior consistent across platforms.
 - **Corrupt files are quarantined** — a store JSON that fails to parse falls back to empty for that file and is rebuilt on the next write; the broken file is renamed to `*.corrupt` with an error logged, but its data cannot be recovered. Auto-repairing partial writes would need a write-ahead journal or an embedded database — out of proportion when quarantining one bad file costs nothing.
 - **`forget` by query is eager** — keyword deletion matches at ≥0.5 token overlap and may remove several notes at once; prefer deleting by id for precision.
 - **Cross-language recall depends on index time** — with `llmQueryExpansion` off, a Chinese-only query reaches English content through bilingual keywords captured when docs are indexed, plus doc↔symbol links; queries stay LLM-free. Stores indexed before v0.1.1 gain bilingual keywords as files change, or immediately via `index_repo` with `reindex: true`.
@@ -116,6 +118,8 @@ These are deliberate scope choices.
 | `autoIndexOnFirstUse` | false | full scan of the current working directory on plugin load (opt-in) |
 | `watch` | true | enable the background refresh |
 | `watchInterval` | 15 | poll interval (seconds) |
+| `tsPath` | (auto) | optional absolute path to a specific `typescript` install; if omitted, resolves from project cwd → plugin node_modules |
+| `enableTypeScript` | true | set `false` to disable L2 TS enhancement entirely (L1 regex only) |
 
 ### Toggling features
 
@@ -131,6 +135,8 @@ Settings live in the plugin's config object. To change them, add an override ent
     llmQueryExpansion: false    # off: do not spend tokens on LLM query expansion (default)
     watch: true                 # on: background refresh for watched roots (default)
     watchInterval: 15           # poll interval in seconds
+    enableTypeScript: true      # on: L2 TS enhancement when TS is installed (default)
+    # tsPath: /custom/path/to/typescript  # optional: force specific TS install
 ```
 
 Only list the keys you want to change; the rest fall back to the plugin defaults. Verify the result with `dsh --profile web --dump-config`.

package/README.zh-CN.md

@@ -4,19 +4,21 @@
 
 [![ci](https://github.com/00080000/dsh-project-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/00080000/dsh-project-memory/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![npm](https://img.shields.io/npm/v/@yolk_vat-y/dsh-project-memory)](https://www.npmjs.com/package/@yolk_vat-y/dsh-project-memory) [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/00080000/dsh-project-memory) [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）agent 提供持久化的项目记忆。将文档（PDF / Markdown / txt）与代码符号索引进每个工作区独立的存储库，自动维护更新，召回时附源文件引用——文档自动交叉链接到其提及的代码符号。
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）agent 提供持久化的项目记忆。**记住**文档（PDF / Markdown / txt）与代码符号，写入每个工作区独立的存储库，自动维护更新，**回忆**时附源文件引用——文档自动交叉链接到其提及的代码符号。
 
-> 插件在磁盘上维护一份精简的项目索引，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查索引，无需重读整个项目。
+> 插件在磁盘上维护一份精简的项目**记忆**，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查**记忆**，无需重读整个项目。
 
 ## 特性
 
-- **文档索引** — PDF、Markdown、纯文本按块切分并由 LLM 生成摘要，每条索引携带 `路径:行号` 引用回源文件。
-- **代码符号表** — 通过零依赖的源码扫描器提取函数、类与方法名（字符串/注释掩码、多行签名续行、Python 缩进感知、类方法上下文），不使用 LLM token。
-- **自动刷新** — `watch_repo` 后台轮询，按内容哈希识别新增或变更文件，仅重抽这些文件。
-- **读到即索引** — 文件在模型**实际读取的瞬间**被索引（监听 `fs/observed`），索引是正常工作的副产品，而非额外的一次全量扫描。从未读过的文件不会被索引。项目根通过标记（`.git`、`package.json` 等）、README 加源码目录、或兜底到文件所在目录逐级识别。
+- **文档记忆** — PDF、Markdown、纯文本按块切分并由 LLM 生成摘要，每条记忆携带 `路径:行号` 引用回源文件。
+- **代码符号记忆** — 通过零依赖的源码扫描器提取函数、类与方法名及完整类型签名（泛型、参数类型、返回类型、重载签名），包含字符串/注释掩码、多行签名续行、Python 缩进感知、类方法上下文，不使用 LLM token。
+- **可选 TypeScript 语义增强** — 当用户项目安装了 `typescript`（`npm i -D typescript`），插件自动激活第二层（L2），利用 TS Compiler API 推导返回类型、实例化泛型、提取接口与类型别名、丰富箭头函数签名 —— 全部在优先级队列中异步后台处理（P0：`fs/observed` 读文件瞬间、P1：`watch` 变更后、P2：`index_repo` 批量索引）。结果按文件内容哈希缓存到磁盘，冷启动毫秒级复用。零配置：装 TS 再重启 dsh 即可。完全可选；若无 TS 或设置 `enableTypeScript: false`，回退至 L1 正则提取。
+- **自动刷新** — `watch_repo` 后台轮询，按内容哈希识别新增或变更文件，仅重记这些文件。
+- **读到即记忆** — 文件在模型**实际读取的瞬间**被记忆（监听 `fs/observed`），记忆是正常工作的副产品，而非额外的一次全量扫描。从未读过的文件不会被记忆。项目根通过标记（`.git`、`package.json` 等）、README 加源码目录、或兜底到文件所在目录逐级识别。
 - **文档 ↔ 代码交叉链接** — 文档提及某符号时记录为 `reference`；查询符号时同时带出描述该符号的文档。
-- **BM25 检索** — 对文档、符号与经验笔记进行排序召回，可选 LLM 查询扩展以应对表述不一致。**CJK 增强**：精确短语乘法加分（3+ 字短语在标题/关键词命中 ×1.5）、同义词表（如 数据库连接池 ↔ 连接池 ↔ DB pool）、CJK 感知的文档↔符号链接边界。
+- **BM25 记忆召回** — 对文档、符号与经验笔记进行排序召回，可选 LLM 查询扩展以应对表述不一致。**CJK 增强**：精确短语乘法加分（3+ 字短语在标题/关键词命中 ×1.5）、同义词表（如 数据库连接池 ↔ 连接池 ↔ DB pool）、CJK 感知的文档↔符号链接边界。
 - **经验笔记** — 记录问题 → 方案；相似问题覆盖而非重复；笔记仅在检索命中时返回。笔记数量有界：容量随项目规模伸缩（钳制在 100–2000），超限时淘汰最旧的笔记。**覆盖阈值收紧为双向 0.7 重叠**（原 0.6）；**经验 `problem` 字段现参与 CJK 短语加分**，提升长尾问句召回。
+- **无锁同步事务** — 不采用锁：所有写入（index / watch / remember / forget / watch_repo）统一走同步事务 `store.commit(fn)`，fn 成功后才一次落盘；JS 单线程事件循环保证事务间不交错，`remember`/`forget` 不会被 watch 重索引阻塞排队。多实例并发写入同一项目存储时，得益于 CAS 幂等更新与原子提交，自然具备幂等性，无数据损坏风险。
 - **依赖极简** — 纯 JavaScript；唯一运行时依赖是 `pdfjs-dist`（PDF 文本提取），无需原生构建。
 - **开销可忽略** — 纯进程内操作；冷启动 <100 ms（5k 文件），典型项目查询中位数 2–3 ms（p99 < 7 ms）；瓶颈在 LLM 摘要与 PDF 解析，插件本身不阻塞。
 
@@ -25,11 +27,11 @@
 设计遵循四个原则：
 
 - **易失性** — 上下文是临时的，会话压缩即丢失。
-- **持久性** — 索引存于磁盘，跨压缩与会话保留。
-- **紧凑性** — 仅存摘要；索引规模约为其覆盖源码的 0.5%（示例项目中 8.8 MB 源码 → 49 KB 索引），检索替代了通读整个文件。
-- **可核验性** — 命中在适用时携带 `路径:行号` 引用，agent 可对照源文件核实。
+- **持久性** — **记忆**存于磁盘，跨压缩与会话保留。
+- **紧凑性** — 仅存摘要；**记忆**规模约为其覆盖源码的 0.5%（示例项目中 8.8 MB 源码 → 49 KB 索引），**召回**替代了通读整个文件。
+- **可核验性** — **召回**在适用时携带 `路径:行号` 引用，agent 可对照源文件核实。
 
-构建索引无需预先全量扫描：文件在模型读取时被索引，索引恰好覆盖实际处理过的内容。未变更的文件重读是空操作（内容哈希），因此索引的持续维护开销很低。
+构建**记忆**无需预先全量扫描：文件在模型读取时被记忆，**记忆**恰好覆盖实际处理过的内容。未变更的文件重读是空操作（内容哈希），因此**记忆**的持续维护开销很低。
 
 存储按项目独立存放，并跟随代码库变化：文件变更按内容哈希重新抽取，文件删除则同步移除。经验层仅检索，累积不影响上下文。
 
@@ -52,7 +54,7 @@ dsh plugin --profile web add @yolk_vat-y/dsh-project-memory -w
 每个版本会附带预构建 tarball，无需构建步骤即可安装：
 
 ```bash
-dsh plugin --profile web add /path/to/dsh-project-memory-0.3.0.tgz
+dsh plugin --profile web add /path/to/dsh-project-memory.tgz
 ```
 
 每个被索引的项目在 `<root>/.dsh-project-memory/` 下有独立存储。如无需入库，可加入 `.gitignore`。
@@ -93,7 +95,7 @@ v0.2.0 之前创建的库（单文件 `entries.json` / `index.json`）在首次
 
 以下是刻意的范围选择。
 
-- **无锁同步事务** — 不采用锁：所有写入（index / watch / remember / forget / watch_repo）统一走同步事务 `store.commit(fn)`，fn 成功后才一次落盘；JS 单线程事件循环保证事务间不交错，`remember`/`forget` 不会被 watch 重索引阻塞排队。两个 dsh 实例共享同一项目存储时后写覆盖先写；跨进程协调需要常驻守护进程，违背纯 JS 插件、无后台服务的定位，故明确不支持多实例共写。
+- **无锁同步事务** — 不采用锁：所有写入（index / watch / remember / forget / watch_repo）统一走同步事务 `store.commit(fn)`，fn 成功后才一次落盘；JS 单线程事件循环保证事务间不交错，`remember`/`forget` 不会被 watch 重索引阻塞排队。多实例并发写入同一项目存储时，得益于 CAS 幂等更新与原子提交，自然具备幂等性，无数据损坏风险。我们不担心 dsh 变多进程，因为 dsh 基于 Cordis，而 Cordis 的单进程架构是基础——改变它将是整个生态的破坏性变更。
 - **watch 计算与提交分离** — watcher 在事务外完成 mtime/哈希/符号扫描/LLM 摘要等重活，再以单次 `commit` 原子应用全部变更；`applyFileUpdate` 用 CAS 校验（统一 null 处理、删除跳过对比）防并发修改，失败回滚 snapshot 下轮重试，索引失败删除 snapshot 自动重试。轮询（mtime + 内容哈希）而非 `fs.watch` 事件驱动，是为了跨平台行为一致。间隔可用 `watchInterval` 调整。
 - **损坏隔离重建** — 存储 JSON 损坏时该文件回落为空并在下次写入时重建；坏文件会改名备份为 `*.corrupt` 并输出错误日志，但该文件内的数据无法恢复。自动修复半写文件需要预写日志或嵌入式数据库，代价与收益不成比例——而隔离一个坏文件的成本几乎为零。
 - **`forget` 按关键词删除偏激进** — 关键词删除按 ≥0.5 token 重叠匹配，可能一次删掉多条；追求精确请用 id 删除。
@@ -116,6 +118,8 @@ v0.2.0 之前创建的库（单文件 `entries.json` / `index.json`）在首次
 | `autoIndexOnFirstUse` | false | 插件加载时对当前工作目录做全量扫描（可选） |
 | `watch` | true | 启用后台刷新 |
 | `watchInterval` | 15 | 轮询间隔（秒） |
+| `tsPath` | (自动) | 可选：强制指定特定 `typescript` 安装路径；省略时按项目 cwd → 插件 node_modules 向上解析 |
+| `enableTypeScript` | true | 设为 `false` 彻底禁用 L2 TS 增强（仅保留 L1 正则） |
 
 ### 功能开关
 
@@ -131,6 +135,8 @@ v0.2.0 之前创建的库（单文件 `entries.json` / `index.json`）在首次
     llmQueryExpansion: false    # 关闭：不用 LLM 扩展查询，节省 token（默认）
     watch: true                 # 开启：被监听根目录后台保持新鲜（默认）
     watchInterval: 15           # 轮询间隔（秒）
+    enableTypeScript: true      # 开启：装了 TS 时启用 L2 语义增强（默认）
+    # tsPath: /custom/path/to/typescript  # 可选：强制指定 TS 安装路径
 ```
 
 只需列出要改的键，其余键回落到插件默认值。用 `dsh --profile web --dump-config` 验证生效。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk_vat-y/dsh-project-memory",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Persistent project memory for dsh agents: index docs (PDF/Markdown/text) and code symbols into a searchable per-workspace store, recall them with cited sources, and keep experience entries (problems -> solutions) searchable on demand.",
   "type": "module",
   "main": "src/index.js",
@@ -39,16 +39,18 @@
     "pdfjs-dist": "^4.10.38"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
-    "@deepseek-ai/schemastery": "3.18.1",
-    "@deepseek-ai/dsh-llm": "0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "typescript": "^5.6.3"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-llm": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.1.1-rc.1 <0.2.0-0",
     "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.1.1-rc.1 <0.2.0-0",
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-ai/dsh-llm": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.1.1-rc.1 <0.2.0-0"
+    "typescript": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -62,6 +64,9 @@
     },
     "@deepseek-ai/dsh-llm": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "dsh": {

package/src/doc-pipeline.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import path from 'node:path'
 import { stat } from 'node:fs/promises'
 import { looksLikeDump, readTextFile } from './util/fs.js'
@@ -27,6 +28,10 @@ export async function buildDocEntries(llm, a, b, c) {
   const [relPath, filePath, opts] = c === undefined ? [a, a, b] : [a, b, c]
   const text = await extractTextFromFile(filePath, opts)
   if (looksLikeDump(text)) return null
+  
+  // Compute content hash for update detection
+  const hash = createHash('sha256').update(text).digest('hex').slice(0, 16)
+  
   const chunks = chunkText(text, opts.chunkChars, opts.maxChunks)
   const metas = new Array(chunks.length)
   let cursor = 0
@@ -47,7 +52,9 @@ export async function buildDocEntries(llm, a, b, c) {
     type: 'doc',
     title: meta.title,
     summary: meta.summary,
+    blindSpots: meta.blindSpots || '',
     keywords: meta.keywords,
+    hash,
   }))
 }
 

package/src/enhancer.js

@@ -0,0 +1,444 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { linkEntries } from './link.js'
+
+const require = createRequire(import.meta.url)
+
+let ts = null
+let tsPath = null
+let tsVersion = null
+
+function acceptTsVersion(mod) {
+  if (mod && mod.version && (mod.version.startsWith('6.') || mod.version.startsWith('7.'))) {
+    console.warn(`[dsh-project-memory] TypeScript ${mod.version} 不受支持，回退到 L1 正则。请使用 TS 5.x 获得增强类型。`)
+    return null
+  }
+  return mod
+}
+
+export function initTypeScript(config) {
+  if (config?.enableTypeScript === false) return null
+  if (ts) return ts
+
+  // 1. 配置指定路径
+  if (config?.tsPath) {
+    try {
+      const req = createRequire(config.tsPath)
+      const mod = acceptTsVersion(req(config.tsPath))
+      if (mod) {
+        ts = mod
+        tsPath = config.tsPath
+        tsVersion = mod.version
+        return ts
+      }
+    } catch (e) {
+      console.warn(`[dsh-project-memory] tsPath 无效: ${config.tsPath}`)
+    }
+  }
+
+  // 2. 从用户项目 cwd 向上查找 node_modules/typescript
+  try {
+    const req = createRequire(process.cwd() + '/')
+    const mod = acceptTsVersion(req('typescript'))
+    if (mod) {
+      ts = mod
+      tsPath = req.resolve('typescript')
+      tsVersion = mod.version
+      return ts
+    }
+  } catch {}
+
+  // 3. 全局（从插件自身位置解析）
+  try {
+    const mod = acceptTsVersion(require('typescript'))
+    if (mod) {
+      ts = mod
+      tsPath = require.resolve('typescript')
+      tsVersion = mod.version
+      return ts
+    }
+  } catch {}
+
+  ts = null
+  return null
+}
+
+export function getTypeScript() {
+  return ts
+}
+
+export function hasTypeScript() {
+  return ts !== null
+}
+
+export function getTsPath() {
+  return tsPath
+}
+
+export function getTsVersion() {
+  return tsVersion
+}
+
+const PRIORITY = {
+  ACTIVE: 0,
+  RECENT: 1,
+  BATCH: 2,
+  BACKLOG: 3
+}
+
+const enhanceQueue = []
+let processing = false
+
+function getCacheDirForRoot(root, config) {
+  return join(root, config.memoryDir || '.dsh-project-memory', 'type-cache')
+}
+
+function getCacheKey(content) {
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16)
+  return hash
+}
+
+async function loadTypeCache(cacheDir, key) {
+  const file = join(cacheDir, `${key}.json`)
+  if (!existsSync(file)) return null
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'))
+    return data
+  } catch {
+    return null
+  }
+}
+
+async function saveTypeCache(cacheDir, key, data) {
+  try {
+    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true })
+    const file = join(cacheDir, `${key}.json`)
+    writeFileSync(file, JSON.stringify(data))
+  } catch {}
+}
+
+export function isTypeScriptFile(filePath) {
+  const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase()
+  return ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' ||
+         ext === '.mjs' || ext === '.cjs' || ext === '.mts' || ext === '.cts'
+}
+
+export function deepParseWithTS(filePath, content) {
+  if (!ts) return null
+
+  // Create a compiler host that provides the source file from memory
+  const host = {
+    getSourceFile: (fileName, languageVersion, onError) => {
+      if (fileName === filePath) {
+        return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true)
+      }
+      return undefined
+    },
+    getDefaultLibFileName: (options) => ts.getDefaultLibFileName(options),
+    getDefaultLibLocation: () => ts.getDefaultLibFilePath({}),
+    getCanonicalFileName: (fileName) => fileName,
+    getCurrentDirectory: () => process.cwd(),
+    getNewLine: () => '\n',
+    useCaseSensitiveFileNames: () => true,
+    fileExists: (fileName) => fileName === filePath,
+    readFile: (fileName) => fileName === filePath ? content : undefined,
+    directoryExists: () => true,
+    getDirectories: () => [],
+  }
+
+  const program = ts.createProgram([filePath], {}, host)
+  const sourceFile = program.getSourceFile(filePath)
+  if (!sourceFile) return []
+  const checker = program.getTypeChecker()
+
+  const symbols = []
+
+  function getSignature(node) {
+    try {
+      return checker.getSignatureFromDeclaration(node)
+    } catch {
+      return undefined
+    }
+  }
+
+  function getReturnType(signature) {
+    if (!signature) return null
+    try {
+      return checker.getReturnTypeOfSignature(signature)
+    } catch {
+      return null
+    }
+  }
+
+  function getTypeStr(type) {
+    if (!type) return 'void'
+    try {
+      return checker.typeToString(type)
+    } catch {
+      return 'any'
+    }
+  }
+
+  function getLine(node) {
+    const pos = node.getStart()
+    if (pos < 0) return 1
+    return sourceFile.getLineAndCharacterOfPosition(pos).line + 1
+  }
+
+  function visit(node) {
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      const signature = getSignature(node)
+      const returnType = getReturnType(signature)
+      const typeParams = node.typeParameters?.map(tp => tp.getText()) || []
+      const params = node.parameters.map(p => {
+        const type = p.type ? getTypeStr(checker.getTypeAtLocation(p.type)) : 'any'
+        return `${p.name.getText()}: ${type}`
+      })
+      const returnTypeStr = getTypeStr(returnType)
+      const generics = typeParams.length ? `<${typeParams.join(', ')}>` : ''
+      symbols.push({
+        name: node.name.getText(),
+        kind: 'function',
+        typeSig: `${generics}(${params.join(', ')}): ${returnTypeStr}`,
+        line: getLine(node)
+      })
+    } else if (ts.isMethodDeclaration(node) && node.name) {
+      const signature = getSignature(node)
+      const returnType = getReturnType(signature)
+      const typeParams = node.typeParameters?.map(tp => tp.getText()) || []
+      const params = node.parameters.map(p => {
+        const type = p.type ? getTypeStr(checker.getTypeAtLocation(p.type)) : 'any'
+        return `${p.name.getText()}: ${type}`
+      })
+      const returnTypeStr = getTypeStr(returnType)
+      const generics = typeParams.length ? `<${typeParams.join(', ')}>` : ''
+      symbols.push({
+        name: node.name.getText(),
+        kind: 'method',
+        typeSig: `${generics}(${params.join(', ')}): ${returnTypeStr}`,
+        line: getLine(node)
+      })
+    } else if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+      const parent = node.parent
+      if (parent && (ts.isVariableDeclaration(parent) || ts.isPropertyAssignment(parent) || ts.isPropertyDeclaration(parent))) {
+        const signature = getSignature(node)
+        const returnType = getReturnType(signature)
+        const typeParams = node.typeParameters?.map(tp => tp.getText()) || []
+        const params = node.parameters.map(p => {
+          const type = p.type ? getTypeStr(checker.getTypeAtLocation(p.type)) : 'any'
+          return `${p.name.getText()}: ${type}`
+        })
+        const returnTypeStr = getTypeStr(returnType)
+        const generics = typeParams.length ? `<${typeParams.join(', ')}>` : ''
+        const name = parent.name?.getText() || '(anonymous)'
+        const kind = ts.isArrowFunction(node) ? 'arrow' : 'function'
+        symbols.push({
+          name,
+          kind,
+          typeSig: `${generics}(${params.join(', ')}): ${returnTypeStr}`,
+          line: getLine(node)
+        })
+      }
+    } else if (ts.isClassDeclaration(node) && node.name) {
+      const typeParams = node.typeParameters?.map(tp => tp.getText()) || []
+      const generics = typeParams.length ? `<${typeParams.join(', ')}>` : ''
+      symbols.push({
+        name: node.name.getText(),
+        kind: 'class',
+        typeSig: generics,
+        line: getLine(node)
+      })
+      ts.forEachChild(node, visit)
+    } else if (ts.isInterfaceDeclaration(node)) {
+      const members = node.members.map(m => {
+        // Skip index signatures (m.name is undefined for index signatures like [key: string]: T)
+        if (!m.name) return null
+        const type = m.type ? getTypeStr(checker.getTypeAtLocation(m.type)) : 'any'
+        return `${m.name.getText()}: ${type}`
+      }).filter(Boolean).join('; ')
+      symbols.push({
+        name: node.name.getText(),
+        kind: 'interface',
+        typeSig: `{ ${members} }`,
+        line: getLine(node)
+      })
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      const typeStr = node.type ? getTypeStr(checker.getTypeAtLocation(node.type)) : 'any'
+      symbols.push({
+        name: node.name.getText(),
+        kind: 'type',
+        typeSig: `= ${typeStr}`,
+        line: getLine(node)
+      })
+    } else {
+      ts.forEachChild(node, visit)
+    }
+  }
+
+  const sf = program.getSourceFile(filePath)
+  if (sf) {
+    visit(sf)
+  }
+  return symbols
+}
+
+export function enqueueEnhance(store, relPath, filePath, priority = PRIORITY.BATCH, config, root) {
+  if (!ts) return Promise.resolve()
+
+  let content
+  try {
+    content = readFileSync(filePath, 'utf8')
+  } catch {
+    // File disappeared between detection and enqueue - skip silently
+    return Promise.resolve()
+  }
+  const cacheKey = getCacheKey(content)
+
+  // Dedupe by (relPath, contentHash) - if same content, skip; if different, replace
+  const existingIdx = enhanceQueue.findIndex(q => q.relPath === relPath)
+  if (existingIdx >= 0) {
+    const existing = enhanceQueue[existingIdx]
+    if (existing.cacheKey === cacheKey) {
+      // Same content, just update priority if higher
+      if (priority < existing.priority) {
+        enhanceQueue[existingIdx].priority = priority
+        enhanceQueue.sort((a, b) => a.priority - b.priority)
+      }
+      return existing.promise
+    } else {
+      // Content changed - replace the task
+      enhanceQueue[existingIdx] = { relPath, filePath, priority, cacheKey, promise: null }
+      // Will create new promise below
+    }
+  }
+
+  const p = (async () => {
+    try {
+      const content = readFileSync(filePath, 'utf8')
+      const cacheKey = getCacheKey(content)
+      const cacheDir = getCacheDirForRoot(root || process.cwd(), config)
+      const cached = await loadTypeCache(cacheDir, cacheKey)
+      if (cached) {
+        // Cache hit: persist via store.commit
+        await store.commit(fn => applyEnhancedSymbols(fn, relPath, cached.symbols))
+        return
+      }
+
+      const enhanced = deepParseWithTS(filePath, content)
+      if (enhanced?.length) {
+        await saveTypeCache(cacheDir, cacheKey, { symbols: enhanced })
+        await store.commit(fn => applyEnhancedSymbols(fn, relPath, enhanced))
+      }
+    } catch (err) {
+      console.warn(`[dsh-project-memory] enhance failed for ${relPath}: ${err.message}`)
+    } finally {
+      // Remove only this task's own queue entry (not a newer one for the same relPath)
+      const idx = enhanceQueue.findIndex(q => q.promise === p)
+      if (idx >= 0) enhanceQueue.splice(idx, 1)
+    }
+  })()
+
+  // Update or add to queue
+  const existingIdx2 = enhanceQueue.findIndex(q => q.relPath === relPath)
+  if (existingIdx2 >= 0) {
+    enhanceQueue[existingIdx2] = { relPath, filePath, priority, cacheKey, promise: p }
+  } else {
+    enhanceQueue.push({ relPath, filePath, priority, cacheKey, promise: p })
+  }
+  enhanceQueue.sort((a, b) => a.priority - b.priority)
+
+  scheduleProcess()
+  return p
+}
+
+function scheduleProcess() {
+  if (processing) return
+  processing = true
+
+  const processNext = async () => {
+    while (enhanceQueue.length > 0) {
+      const task = enhanceQueue.shift()
+      try {
+        await task.promise
+      } catch (err) {
+        console.warn(`[dsh-project-memory] enhance task failed: ${err.message}`)
+      }
+      await new Promise(r => setImmediate(r))
+    }
+    processing = false
+  }
+
+  processNext()
+}
+
+function applyEnhancedSymbols(fn, relPath, enhanced) {
+  // Store entries in fn.entries[relPath], not fn.files[relPath].entries
+  const existingEntries = fn.entries[relPath] || []
+  // L1 entries carry title "name (kind)" + sourceLine but no name/line fields
+  const nameOf = e => (e.title || '').replace(/\s*\([^)]*\)\s*$/, '')
+  const enhancedByLine = new Map(enhanced.map(s => [s.line, s]))
+  const existingKeys = new Set(existingEntries.map(e => `${nameOf(e)}#${e.sourceLine}`))
+
+  // Upgrade L1 entries in place only when TS found the same symbol on the same line
+  const mergedEntries = existingEntries.map(e => {
+    const enh = enhancedByLine.get(e.sourceLine)
+    if (!enh || nameOf(e) !== enh.name) return e
+    return {
+      ...e,
+      text: `${enh.name}${enh.typeSig} -- ${relPath}:${enh.line}`,
+      typeSig: enh.typeSig,
+      enhanced: true
+    }
+  })
+
+  // Add enhanced symbols that L1 missed; keep ids unique even when several
+  // symbols share one line (e.g. one-line class + method)
+  const usedIds = new Set(existingEntries.map(e => e.id))
+  const newEntries = []
+  for (const s of enhanced) {
+    if (existingKeys.has(`${s.name}#${s.line}`)) continue
+    const base = `${relPath.replace(/[\/:\s]/g, '_')}#${s.line}`
+    let id = base
+    if (usedIds.has(id)) id = `${base}-${s.kind}`
+    for (let n = 2; usedIds.has(id); n++) id = `${base}-${s.kind}-${n}`
+    usedIds.add(id)
+    newEntries.push({
+      id,
+      sourcePath: relPath,
+      sourceLine: s.line,
+      type: 'symbol',
+      title: `${s.name} (${s.kind})`,
+      keywords: [s.name, s.kind],
+      text: `${s.name}${s.typeSig} -- ${relPath}:${s.line}`,
+      enhanced: true
+    })
+  }
+
+  // Write to store.entries via setEntries so the shard is marked dirty and persisted
+  fn.setEntries(relPath, [...mergedEntries, ...newEntries])
+
+  // Refresh doc<->symbol links for newly added symbols
+  if (newEntries.length) linkEntries(fn)
+
+  // Also update fn.files metadata
+  if (fn.files[relPath]) {
+    fn.files[relPath].enhanced = true
+  }
+}
+
+export function onFileObserved(store, relPath, filePath, config, root) {
+  if (!isTypeScriptFile(filePath)) return
+  enqueueEnhance(store, relPath, filePath, PRIORITY.ACTIVE, config, root)
+}
+
+export function onFileChanged(store, relPath, filePath, config, root) {
+  if (!isTypeScriptFile(filePath)) return
+  enqueueEnhance(store, relPath, filePath, PRIORITY.RECENT, config, root)
+}
+
+export function onFileIndexed(store, relPath, filePath, config, root) {
+  if (!isTypeScriptFile(filePath)) return
+  enqueueEnhance(store, relPath, filePath, PRIORITY.BATCH, config, root)
+}

package/src/index.js

@@ -8,6 +8,7 @@ import { watchRepoTool } from './tools/watch-repo.js'
 import { statsTool } from './tools/stats.js'
 import { WatchManager } from './watch.js'
 import { setupLazyIndexing } from './lazy.js'
+import { initTypeScript } from './enhancer.js'
 
 export const name = 'dsh-project-memory'
 export const inject = ['llm', 'tools']
@@ -25,9 +26,16 @@ export const Config = Schema.object({
   autoIndexOnFirstUse: Schema.boolean().default(false),
   watch: Schema.boolean().default(true),
   watchInterval: Schema.number().default(15),
+  tsPath: Schema.string(),
+  enableTypeScript: Schema.boolean().default(true),
 })
 
 export function apply(ctx, config) {
+  // Initialize TypeScript enhancer if enabled
+  if (config.enableTypeScript !== false) {
+    initTypeScript(config)
+  }
+
   const watchManager = new WatchManager(ctx, config)
   if (config.watch) {
     watchManager.restorePersisted()

package/src/lazy.js

@@ -6,6 +6,7 @@ import { buildDocEntries } from './doc-pipeline.js'
 import { scanSymbols } from './symbols.js'
 import { linkEntries } from './link.js'
 import { ProjectMemoryStore } from './store.js'
+import { onFileObserved } from './enhancer.js'
 
 const STRONG_MARKERS = ['.git', '.hg', '.svn']
 
@@ -87,6 +88,7 @@ export async function indexFile(ctx, config, filePath, watchManager = null) {
   const existing = store.fileRecord(rel)
   let hash
   let size
+  let entries
   try {
     if (isSupportedCode(ext) && config.maxFileSizeMb && statSync(filePath).size > config.maxFileSizeMb * 1024 * 1024) {
       return false
@@ -102,9 +104,9 @@ export async function indexFile(ctx, config, filePath, watchManager = null) {
     store.addWatch(root)
   }
 
-  let entries
   if (isSupportedCode(ext)) {
     entries = scanSymbols(rel, filePath, readFileSync(filePath, 'utf8'))
+    onFileObserved(store, rel, filePath, config, root)
     return store.commit((s) => {
       s.markFile(rel, { sha256: hash, size, type: 'code', indexedAt: new Date().toISOString() })
       s.setEntries(rel, entries)

package/src/llm.js

@@ -96,10 +96,15 @@ export async function expandQuery(llm, query, count = 6) {
 export async function extractDocEntry(llm, chunk, sourcePath) {
   const system =
     'You are a project-documentation indexer. Given a chunk of a project document, ' +
-    'return a STRICT JSON object with exactly three fields: ' +
-    '"title" (short section title, string), "summary" (2-4 sentence dense summary of what this section covers, ' +
-    'mentioning concrete names, decisions and constraints), "keywords" (array of 5-10 searchable strings: ' +
-    'cover the document\'s own language AND English equivalents, so a query in either language can match). ' +
+    'return a STRICT JSON object with exactly four fields: ' +
+    '"title" (short section title, string), ' +
+    '"summary" (3-5 sentence dense summary of what this section covers, ' +
+    'mentioning concrete names, decisions, constraints, and key technical details), ' +
+    '"blindSpots" (string describing what this summary does NOT cover, ' +
+    'e.g. "未覆盖：部署细节、性能基准、v0.2 前 API", empty string if none), ' +
+    '"keywords" (array of 5-10 searchable strings: ' +
+    'cover the document\'s own language AND English equivalents, ' +
+    'so a query in either language can match). ' +
     'Do not include markdown fences, do not add commentary, output only the JSON object.'
 
   const user =
@@ -109,6 +114,7 @@ export async function extractDocEntry(llm, chunk, sourcePath) {
   const fallback = () => ({
     title: chunk.title || sourcePath,
     summary: summarizeText(chunk.text),
+    blindSpots: '',
     keywords: tokenize(chunk.title).slice(0, 5),
   })
 
@@ -121,7 +127,8 @@ export async function extractDocEntry(llm, chunk, sourcePath) {
     const kw = Array.isArray(parsed.keywords) ? parsed.keywords.map(String).filter((k) => k).slice(0, 8) : []
     return {
       title: typeof parsed.title === 'string' && parsed.title.trim() ? parsed.title.trim() : chunk.title || sourcePath,
-      summary: summarizeText(parsed.summary),
+      summary: summarizeText(parsed.summary.trim()),
+      blindSpots: typeof parsed.blindSpots === 'string' ? parsed.blindSpots.trim() : '',
       keywords: kw.length ? kw : tokenize(chunk.title).slice(0, 5),
     }
   } catch {

package/src/symbols.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 
-const JS_LIKE = new Set(['.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx'])
+const JS_LIKE = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx'])
 const PYTHON = new Set(['.py'])
 const GO = new Set(['.go'])
 const RUST = new Set(['.rs'])
@@ -96,19 +96,121 @@ function balanceDelta(text) {
   return delta
 }
 
+function extractTypeSignature(line) {
+  let sig = ''
+  
+  // 1. Generics: <T, U extends Base> - but NOT the return type generics like Promise<T>
+  // Match generics that appear BEFORE the first ( (function params) or => (arrow)
+  // For: function foo<T>(a: T): R
+  // For: const foo = <T>(a: T): R =>
+  // For: class Foo<T> { method() }
+  const beforeParams = line.split(/\(|=>/)[0]
+  const genericMatch = beforeParams.match(/<[^<>]*(?:<[^<>]*>[^<>]*)*>/)
+  if (genericMatch) sig += genericMatch[0]
+  
+  // 2. Parameters: (a: string, b: number) - handle nested parentheses
+  let paramMatch = null
+  const parenIdx = line.indexOf('(')
+  if (parenIdx >= 0) {
+    let depth = 0
+    for (let i = parenIdx; i < line.length; i++) {
+      if (line[i] === '(') depth++
+      else if (line[i] === ')') {
+        depth--
+        if (depth === 0) {
+          paramMatch = line.slice(parenIdx, i + 1)
+          // 3. Return type: ONLY after the closing ) of params
+          const afterParams = line.slice(i + 1)
+          // Match return type including nested generics, stop at { ; => 
+          const retMatch = afterParams.match(/^\s*:\s*([^{;=]+)/)
+          if (retMatch) sig += paramMatch + `: ${retMatch[1].trim()}`
+          else sig += paramMatch
+          break
+        }
+      }
+    }
+  }
+  
+  // 3b. Arrow function without parens: foo = (x): R => or foo = x: R =>
+  if (!paramMatch) {
+    const arrowMatch = line.match(/=>/)
+    if (arrowMatch) {
+      const afterArrow = line.slice(arrowMatch.index + 2)
+      const retMatch = afterArrow.match(/^\s*([^{;=]+)/)
+      if (retMatch) sig += `: ${retMatch[1].trim()}`
+    }
+  }
+  
+  return sig
+}
+
+function extractInterfaceOrType(line) {
+  // interface User { name: string; age: number }
+  const ifaceMatch = line.match(/^interface\s+(\w+)\s*(?:extends\s+[^{]+)?\s*\{([^}]*)\}/)
+  if (ifaceMatch) {
+    return `{ ${ifaceMatch[2].trim()} }`
+  }
+  // type UserMap = Map<string, User>
+  const typeMatch = line.match(/^type\s+(\w+)\s*=\s*([^;{]+)/)
+  if (typeMatch) {
+    return `= ${typeMatch[2].trim()}`
+  }
+  return ''
+}
+
+function extractOverloads(masked, startIdx) {
+  const overloads = []
+  for (let i = startIdx; i < masked.length; i++) {
+    const text = masked[i].trim()
+    if (!text) continue
+    
+    // Skip comments
+    if (text.startsWith('//') || text.startsWith('/*')) continue
+    
+    // Check for function declaration (with or without export/async/default)
+    const fnMatch = text.match(/^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+\w+\s*/)
+    if (!fnMatch) break
+    
+    // Extract ONLY the signature part (generics + params + return), NOT the function name
+    const sig = extractTypeSignature(text)
+    if (sig) overloads.push(sig)
+    
+    // If it has a body {, it's the implementation - stop
+    if (text.includes('{')) break
+  }
+  return overloads
+}
+
 function matchJsLike(line) {
+  // export default async function foo<T>(a: T): Promise<T> { ... }
   let m = line.match(/^export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Za-z_$][\w$]*)|class\s+([A-Za-z_$][\w$]*))/)
   if (m) return { name: m[1] || m[2], kind: m[1] ? 'function' : 'class' }
-  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/)
+  
+  // export async function foo<T>(a: T): Promise<T> { ... }
+  // Handle optional generics: function name<T>(...
+  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*(?:<[^<>]*>)?\s*\(/)
   if (m) return { name: m[1], kind: 'function' }
+  
+  // export class Foo { ... }
   m = line.match(/^(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/)
   if (m) return { name: m[1], kind: 'class' }
+  
+  // export const foo = (a: T): Promise<T> => { ... }
   m = line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\(/)
   if (m) return { name: m[1], kind: 'function' }
+  
+  // export const foo = async (a: T): Promise<T> => { ... }
   m = line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/)
   if (m) return { name: m[1], kind: 'function' }
-  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s*\(/) // anonymous
+  
+  // export function (multi-line, name on next line)
+  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s*$/)
+  if (m) return { name: '(pending)', kind: 'function' }
+  
+  // anonymous function
+  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s*\(/)
   if (m) return { name: '(anonymous)', kind: 'function' }
+  
   return null
 }
 
@@ -124,31 +226,77 @@ function scanJsLike(masked, relPath, rawLines) {
   const symbols = []
   let prevOpensBlock = false
   for (let i = 0; i < masked.length; i++) {
-    const text = masked[i].trim()
-    if (!text) continue
+    const rawText = rawLines[i].trim()
+    const maskedText = masked[i].trim()
+    if (!rawText) continue
+    
     let matched = null
-    if (prevOpensBlock) {
-      const method = text.match(/^([A-Za-z_$][\w$]*)\s*(?:<[^<>]*>)?\s*\(([^()]*)\)\s*(?::\s*[^={]{1,80})?\{/)
-      if (method && !JS_NON_METHOD.has(method[1])) matched = { name: method[1], kind: 'method' }
+    let joinedText = null
+    
+    // Check for interface / type alias first (on raw line, not masked)
+    const ifaceSig = extractInterfaceOrType(rawText)
+    if (ifaceSig) {
+      const nameMatch = rawText.match(/^(?:export\s+)?(?:interface|type)\s+(\w+)/)
+      if (nameMatch) {
+        matched = { name: nameMatch[1], kind: 'interface', typeSig: ifaceSig }
+      }
     }
-    if (!matched) matched = matchJsLike(text)
-    if (!matched && JS_DECL_START.test(text)) {
-      let joined = text
+    
+    if (!matched) {
+      // Check for method inside class (prev line ends with {)
+      if (prevOpensBlock) {
+        const method = maskedText.match(/^([A-Za-z_$][\w$]*)\s*(?:<[^<>]*>)?\s*\(([^()]*)\)\s*(?::\s*[^={]{1,80})?\{/)
+        if (method && !JS_NON_METHOD.has(method[1])) matched = { name: method[1], kind: 'method' }
+      }
+      
+      // Regular declarations - try initial match
+      if (!matched) matched = matchJsLike(maskedText)
+    }
+    
+    // Multi-line declaration joining (only when no initial match, or when match is pending)
+    if ((!matched || (matched && matched.name === '(pending)')) && JS_DECL_START.test(maskedText)) {
+      // No initial match, or pending match - do joining to find/resolve one
+      let joined = maskedText
       let extra = 0
-      for (let j = i + 1; j < masked.length && extra < 3; j++) {
+      let declMatched = null
+      for (let j = i + 1; j < masked.length && extra < 5; j++) {
         const tail = masked[j].trim()
         if (!tail) continue
         joined += ' ' + tail
         extra++
-        matched = matchJsLike(joined)
-        if (matched) {
-          i = j
+        if (!declMatched) declMatched = matchJsLike(joined)
+        if (/[{};]/.test(tail)) {
+          if (declMatched && declMatched.name !== '(pending)') {
+            matched = declMatched
+            i = j
+            joinedText = joined
+          }
           break
         }
-        if (/[{};]/.test(tail)) break
+      }
+      if (!matched && declMatched && declMatched.name !== '(pending)') {
+        matched = declMatched
+        joinedText = joined
       }
     }
-    if (matched) symbols.push(buildSymbol(matched, relPath, rawLines[i], i + 1))
+    
+    if (matched) {
+      // Extract type signature: use joined text if multi-line, else raw line
+      if (matched.kind !== 'interface') {
+        const sourceForType = joinedText || rawText
+        const typeSig = extractTypeSignature(sourceForType)
+        if (typeSig) matched.typeSig = typeSig
+      }
+      
+      // Extract overloads for function declarations
+      if (matched.kind === 'function' && (joinedText || rawText).startsWith('function')) {
+        const overloads = extractOverloads(masked, i)
+        if (overloads.length > 1) matched.overloads = overloads
+      }
+      
+      symbols.push(buildSymbol(matched, relPath, rawLines[i], i + 1))
+    }
+    
     prevOpensBlock = masked[i].trim().endsWith('{')
   }
   return symbols
@@ -208,16 +356,77 @@ function matchShell(line) {
   return m ? { name: m[1], kind: 'function' } : null
 }
 
+function extractParamsAndReturn(line) {
+  const trimmed = line.trim()
+  
+  // Try to extract params and return type from function declaration
+  // Matches: function name(params): returnType { or => returnType {
+  const funcMatch = line.match(/function\s+([A-Za-z_$][\w$]*)\s*(\([^)]*\))\s*(?::\s*([^{]+))?\s*\{/)
+  if (funcMatch) {
+    const params = funcMatch[2] || '()'
+    const returnType = funcMatch[3] ? `: ${funcMatch[3].trim()}` : ''
+    return `${funcMatch[1]}${params}${returnType}`
+  }
+  
+  // Arrow function: const name = (params): returnType => {
+  const arrowMatch = line.match(/const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*:\s*([^=]+)\s*=>/)
+  if (arrowMatch) {
+    return `${arrowMatch[1]}(${arrowMatch[2]}): ${arrowMatch[3].trim()}`
+  }
+  
+  // Arrow function without explicit return type: const name = (params) => {
+  const arrowSimple = line.match(/const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/)
+  if (arrowMatch) {
+    return `${arrowMatch[1]}(${arrowMatch[2]})`
+  }
+  
+  // Class method: methodName(params): returnType {
+  const methodMatch = line.match(/^\s*([A-Za-z_$][\w$]*)\s*(?:<[^<>]*>)?\s*\(([^()]*)\)\s*(?::\s*([^{]+))?\s*\{/)
+  if (methodMatch) {
+    const returnType = methodMatch[3] ? `: ${methodMatch[3].trim()}` : ''
+    return `${methodMatch[1]}(${methodMatch[2] || ''})${returnType}`
+  }
+  
+  // Constructor
+  const constructorMatch = line.match(/constructor\s*\(([^)]*)\)/)
+  if (constructorMatch) {
+    return `constructor(${constructorMatch[1]})`
+  }
+  
+  // Fallback: try to extract from the raw line
+  const declMatch = line.match(/(function|const|let|var)\s+([A-Za-z_$][\w$]*)/)
+  if (declMatch) {
+    return declMatch[0]
+  }
+  
+  // Fallback: return the raw line trimmed
+  return ''
+}
+
 function buildSymbol(matched, relPath, rawLine, lineNo) {
+  // Use pre-extracted type signature if available, otherwise fall back to extractParamsAndReturn
+  let typeSig = matched.typeSig || extractParamsAndReturn(rawLine)
+  
+  // Add overloads if present
+  const overloadPart = matched.overloads?.length
+    ? ` | overloads: ${matched.overloads.join('; ')}`
+    : ''
+  
+  // For interface/type, typeSig already includes the full signature without name
+  // For others, typeSig is just the generics+params+return
+  const prefix = matched.kind === 'interface' ? '' : matched.name
+  
+  // Build one-line identity: name<Generics>(params): ReturnType — file.ts:lineNo
+  const identity = `${prefix}${typeSig}${overloadPart} — ${relPath}:${lineNo}`
+
   return {
     id: `${String(relPath).replace(/[\\/:\s]/g, '_')}#${lineNo}`,
     sourcePath: relPath,
     sourceLine: lineNo,
     type: 'symbol',
     title: `${matched.name} (${matched.kind})`,
-    summary: `${matched.kind} "${matched.name}" declared at ${relPath}:${lineNo}`,
     keywords: [matched.name, matched.kind],
-    text: String(rawLine).trim().slice(0, 200),
+    text: identity,
   }
 }
 

package/src/tools/index-repo.js

@@ -6,6 +6,7 @@ import { buildDocEntries } from '../doc-pipeline.js'
 import { scanSymbols } from '../symbols.js'
 import { linkEntries } from '../link.js'
 import { ProjectMemoryStore } from '../store.js'
+import { onFileIndexed, isTypeScriptFile } from '../enhancer.js'
 
 export async function indexRepository(ctx, config, root, { reindex = false } = {}) {
   const memoryDir = memoryRootFor(root, config.memoryDir)
@@ -77,7 +78,7 @@ export async function indexRepository(ctx, config, root, { reindex = false } = {
   }
 
   // Second pass: single commit with all updates
-  return store.commit((s) => {
+  const report = store.commit((s) => {
     for (const update of fileUpdates) {
       const result = s.applyFileUpdate(update.rel, update)
       if (result.skipped) {
@@ -105,6 +106,18 @@ export async function indexRepository(ctx, config, root, { reindex = false } = {
     }
     return report
   })
+
+  // Trigger TS enhancement for code files (TS/JS only)
+  for (const update of fileUpdates) {
+    if (update.type === 'code') {
+      const filePath = path.join(root, update.rel)
+      if (isTypeScriptFile(filePath)) {
+        onFileIndexed(store, update.rel, filePath, config, root)
+      }
+    }
+  }
+
+  return report
 }
 
 export function indexRepoTool(ctx, config) {

package/src/util/fs.js

@@ -85,7 +85,7 @@ export function looksLikeDump(text, maxBytes = 4096) {
 
 export function isSupportedCode(ext) {
   return [
-    '.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx', '.py', '.java', '.go',
+    '.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py', '.java', '.go',
     '.rs', '.c', '.cpp', '.cc', '.h', '.hpp', '.cs', '.php', '.rb',
     '.swift', '.kt', '.kts', '.sh', '.zsh',
   ].includes(ext)

package/src/watch.js

@@ -5,6 +5,7 @@ import { buildDocEntries } from './doc-pipeline.js'
 import { scanSymbols } from './symbols.js'
 import { linkEntries } from './link.js'
 import { ProjectMemoryStore } from './store.js'
+import { onFileChanged, isTypeScriptFile } from './enhancer.js'
 
 export class WatchManager {
   constructor(ctx, config) {
@@ -144,12 +145,15 @@ export class WatchManager {
       }
     })
 
-    // Update snapshot for successfully processed files only, using the
-    // first-pass signature: if the file changed during the compute window
-    // (hash / scanSymbols / LLM summary), the next poll's signature differs
-    // and the file is re-indexed — restoring the pre-refactor self-healing.
+    // Trigger TS enhancement for code files (TS/JS only)
     for (const update of fileUpdates) {
       if (update._skipSnapshot) continue
+      if (update.type === 'code') {
+        const filePath = path.join(root, update.rel)
+        if (isTypeScriptFile(filePath)) {
+          onFileChanged(state.store, update.rel, filePath, this.config, root)
+        }
+      }
       state.snapshot[update.rel] = update._sig
     }
   }