@yolk_vat-y/dsh-project-memory 0.5.8 → 0.5.9

package/README.zh-CN.md

@@ -9,15 +9,12 @@
 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）agent 提供持久化的 **项目开发记忆**。专门针对项目开发，原生融合 dsh 任务系统，会话内任务清单与读过的文件自动沉淀为跨会话任务记录，任务↔文件自动关联——开发工作流可切换、可续接，无需重复梳理整个项目，解决上下文失效；文档（PDF/Markdown/txt）与代码符号写入工作区独立存储，文档自动交叉链接至所提及的代码符号；经验笔记（问题 → 方案）自动去重，避免重复踩坑。所有数据按项目落盘，跨会话压缩与交接保留，召回附带 `路径:行号` 可回源核实。单依赖，无向量数据库，无原生构建。
 
 
-> 插件在磁盘上维护一份精简的项目**记忆**，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查**记忆**，无需重读整个项目。任务与经验跨会话压缩与交接保持。
-![alt text](docs/images/image.png)
+> 插件在磁盘上维护一份精简的项目**记忆**，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查**记忆**，无需重读整个项目。
+![任务面板：任务清单、步骤进度与涉及文件](docs/images/image.png)
 
-工作流卡片可收起，自动适应dsh及主题插件风格，提供四种卡片风格切换。
-
-![alt text](docs/images/image-4.png)
 ## 特性
 
-- **TaskBridge：跨会话开发任务** — 会话内的任务清单与触碰过的文件持久化为跨会话的项目任务实体，工作流可以随时切走再续接，不必重新界定项目范围。关联文件按最近活跃排序（读取永远不越过写过的文件），续接时一眼看到该先看哪些。新会话通过 `list_tasks` → `select_task` 续接。委派给子代理的工作不会建档（见「设计取舍」）。自动同步需要含会话事件的 dsh 构建；旧宿主下降级为纯记录。
+- **TaskBridge：跨会话开发任务** — 会话内的任务清单与触碰过的文件持久化为跨会话的项目任务实体，工作流可以随时切走再续接，不必重新界定项目范围。关联文件按最近活跃排序（读取永远不越过写过的文件），续接时一眼看到该先看哪些。新会话通过 `list_tasks` → `select_task` 续接。委派给子代理的工作不会建档（见「已知限制与边界」）。自动同步需要含会话事件的 dsh 构建；旧宿主下降级为纯记录。
 - **dsh web 浮动任务面板（v0.4.2+）** — 卡片可拖拽，展示任务步骤与涉及文件，可折叠为迷你条或彻底隐藏。面板默认隐藏，仅在显式唤起后出现；会话切换只后台同步，刷新页面不会自行打开。渲染错误有边界兜底，面板崩溃不会拖垮宿主。
 - **面板编辑与外观（v0.4.2+）** — 绑定卡片支持标题与步骤的行内编辑、步骤状态循环切换；非绑定卡片只读。四档外观风格只改材质、几何、字型与密度，颜色跟随宿主。
 - **任务清单双向同步（v0.4.2+）** — 绑定任务时把步骤推给宿主任务清单，面板编辑与模型更新写回同一套逻辑。配置 `tasklist.syncHostOnAdopt` 可关闭。
@@ -30,71 +27,11 @@
 - **经验笔记** — 记录问题 → 方案；相似问题覆盖而不重复，数量随项目规模有界，仅在检索命中时返回。
 - **分层 insight 记忆（教训 / 决策 / 流程，v0.5）** — 同一实体贯穿任务、项目、全局三级。近重复合并或强化；提升是更换归属而非复制。被使用会记账，因此衰减与容量按活跃度排序，而不是只按时间。LLM 反思默认关闭，只写任务级草稿。面板提供分级的记忆视图用于审核与编辑。
 - **触发式注入** — insight 可携带 authored trigger：只有 `when` 能触发，`guard` 只能收窄，`prevents` 记下没有它会坏在哪。语料正文永远不能触发注入；统计通道另有独立门槛。
-- **流式 TF + IDF 缓存** — 查询路径按存储版本缓存词权重，20k 条目 p50 2.6 ms / p95 5.4 ms，4k 条目 p50 0.6 ms / p95 1.6 ms。只有真实写入才清空缓存，watch 轮询不会把查询刚建好的缓存清掉。
+- **流式 TF + IDF 缓存** — 查询路径按存储版本缓存词权重（实测数字见「性能」）。只有真实写入才清空缓存，watch 轮询不会把查询刚建好的缓存清掉。
 - **无锁同步事务** — 所有写入走同步事务，`remember` / `forget` 不会排在重索引之后。锁在进程内：不要让两个 dsh 实例写同一个 store。
 - **依赖极简** — 纯 JavaScript；运行时只有一个用于 PDF 文本提取的依赖，无需原生构建。
 - **开销可忽略** — 记忆操作在进程内完成；瓶颈是文档提取与磁盘 I/O，而不是打分。
 
-## 性能
-
-### 合成基准测试（Node 24.19，WSL2 / 20 vCPU，Linux 文件系统）
-
-| 场景 | 规模 | 实测 |
-|------|------|------|
-| 批量冷记忆构建 | 5,000 文件 / 20k 条目 | 269 ms 均值（p50 267）|
-| 冷加载 | 5,000 文件 | 40 ms |
-| 热路径懒记忆 | 单文件重记忆+落盘 | p50 2.4 ms / 最大 5.5 ms (5k) |
-| query_memory (缓存命中) | 5k 文件 / 20k 条目 | p50 2.6 ms / p95 5.4 ms |
-| query_memory (缓存命中) | 1k 文件 / 4k 条目 | p50 0.6 ms / p95 1.6 ms |
-| 批量冷记忆构建 | 10,000 文件 / 40k 条目 | 551 ms 均值（p50 528）|
-| 冷加载 | 10,000 文件 | 90 ms |
-| 热路径懒记忆 | 单文件重记忆+落盘 | p50 5.4 ms / 最大 9.2 ms (10k) |
-
-> 合成基准：生成代码（~4–5 符号/文件），Node 24.19 / WSL2 / 20 vCPU / Linux 文件系统，实测于 2026-09-14。复现命令 `npm run bench:synthetic -- 5000`（脚本 `scripts/bench-synthetic.mjs`）。测量纯索引开销，不含 LLM 调用。query_memory 使用 IDF 缓存 + 预计算 searchText；写入后的首次查询会重建 IDF（**40k 条目 106 ms**，20k 条目 57 ms，4k 条目 12 ms），后续查询命中缓存。
-
-### 真实项目存储体积
-
-| 项目 | 文件数 | 条目数 | 存储体积 | 单条目 |
-|------|--------|--------|----------|--------|
-| Java Spring Boot 后端 | 1,254 | 7,335 | 6.7 MB | ~0.9 KB |
-| Vue 3 + Vite 前端 | 289 | 2,141 | 1.0 MB | ~0.5 KB |
-
-> 真实项目（Java + Vue），测试于 Linux 文件系统（Node 24）。真实项目单条目体积小于合成基准，因符号密度更低、声明行更短。
-
-### 自己复现这些数字
-
-与其让你相信上面的表格，不如把测量本身一起发布——它随仓库发布，**也随 npm 包一起发布**（`scripts/` 已包含在 tarball 中）。脚本**不需要 dsh 实例、不需要网络、不调用任何模型**，也**不碰被测项目自己的 store**——结果写进临时目录，跑完删除：
-
-```bash
-npm run bench -- /你的/项目路径
-# 或带参数：
-node scripts/bench.mjs /你的/项目路径 [--json] [--samples 100] [--no-pdf] [--keep]
-```
-
-输出包含：冷索引（拆成 read+hash / extract / commit 三段）、冷加载、IDF 重建、冷查询与热查询延迟（走线上同一套 scorer，100 条采样报 p50/p95/max）、单文件热重索引、存储体积与每条字节数。示例——我们内部的 Vue 项目（289 文件 / 2,141 条目，Node 24，20 CPU，Linux）：
-
-```
-冷索引     253 ms   （read+hash 9 ms · extract 229 ms · commit 13 ms）← 第二次、页缓存已热
-存储       1.10 MB · 538 bytes/条目 · 冷加载 4.6 ms
-热查询     p50 0.80 ms · p95 1.35 ms          （2,141 条目）
-单文件重索引  p50 0.33 ms
-```
-
-两个我们宁可自己说清楚的坑：`read+hash` 受操作系统页缓存影响——同一个语料第一遍花了 787 ms、第二遍 253 ms，报数时请说明是第几遍；**真实项目比上面的合成基准慢**——在一个大型 TypeScript 仓库的 3,000 文件切片上（15,594 条目）热查询 p50 为 7.5 ms，因为真实声明文本比生成出来的桩代码长得多。带 `--queries 你的查询集.json` 可以在你自己的项目上跑同一套标注集方法（hit@5 / hit@10 / MRR）。
-
-## 工作原理
-
-设计遵循四个原则：
-
-- **易失性** — 上下文是临时的，会话压缩即丢失。
-- **持久性** — **记忆**存于磁盘，跨压缩与会话保留。
-- **紧凑性** — 代码层每个符号只存一行声明，所以代码为主的项目仍约 **0.5% 源码体积**（示例项目中 8.8 MB 源码 → 49 KB 索引），**召回**替代了通读整个文件。文档层按设计更重：每个 chunk 保留 ≤300 字符的注入 `summary`、覆盖整 chunk 的 `terms`，以及预计算的 `searchText`。纯文档语料实测（179 chunk / 225 KB Markdown）：`terms` ≈ 源码 **27.5%**，整库落盘 ≈ 源码 **166%**——文档占比高的项目请按「约等于文档本身大小」估，而不是 0.5%。
-- **可核验性** — **召回**在适用时携带 `路径:行号` 引用，agent 可对照源文件核实。
-
-构建**记忆**无需预先全量扫描：文件在模型读取时被记忆，**记忆**恰好覆盖实际处理过的内容。未变更的文件重读是空操作（内容哈希），因此**记忆**的持续维护开销很低。
-
-存储按项目独立存放，并跟随代码库变化：文件变更按内容哈希重新抽取，文件删除则同步移除。经验层仅检索，累积不影响上下文。
-
 ## 安装
 
 插件仅依赖通过 peerDependencies 声明的稳定公共 API（`defineTool`、`llm.stream`、`Schema`），保证与后续 rc/alpha 版本无需改动即兼容。
@@ -126,8 +63,8 @@ dsh plugin --profile web add /path/to/dsh-project-memory.tgz
 | 工具 | 用途 |
 |---|---|
 | `index_doc file_path` | 索引单个文档（PDF/MD/txt）：分块 → 确定性 `summary` + 整 chunk `terms` → 带 `路径:行号` 入库。未变更文件自动跳过。 |
-| `index_repo root` | 索引整个项目：文档生成确定性摘要 + 整 chunk 词项，代码文件生成零 token 符号表。增量更新、清理已删除文件、文档与符号交叉链接。根目录不存在（含在 Linux/macOS 上被解析成相对路径的 Windows 风格路径）时，会在写入任何内容前直接拒绝。 |
-| `watch_repo root` | 启用自动刷新：后台轮询检测新增/变更文件（mtime + 内容哈希），仅重抽这些文件。监听的项目在插件重启后自动恢复；不存在的根目录、文件系统根与共享临时目录都会被拒绝，已消失的根目录会被丢弃而不是被重新创建。 |
+| `index_repo root` | 索引整个项目：文档生成确定性摘要 + 整 chunk 词项，代码文件生成零 token 符号表。增量更新、清理已删除文件、文档与符号交叉链接。根目录不存在（含在 Linux/macOS 上被解析成相对路径的 Windows 风格路径）时会在写入任何内容前直接拒绝；**危险根**（家目录、文件系统根、系统/包管理器前缀）同样拒绝——扫它们等于走几十万个文件。 |
+| `watch_repo root` | 启用自动刷新：后台轮询检测新增/变更文件（mtime + 内容哈希），仅重抽这些文件。监听的项目在插件重启后自动恢复；不存在的根目录与危险根（文件系统根、家目录、共享临时目录、系统/包管理器前缀）都会被拒绝，已消失的根目录会被丢弃而不是被重新创建，旧版本遗留的污染 watchlist 会在启动时自愈。 |
 | `memory_stats root` | 查看记忆库内容：总量（文件 / 条目 / 经验笔记）、最近索引时间，以及按时间排序的逐文件清单。 |
 | `query_memory query` | 对文档、符号、经验与 insight（教训/决策/流程）执行 BM25 检索，可选 LLM 查询扩展。`type` 选择层（`all` / `doc` / `symbol` / `experience` / `insight` / `task`）。返回带相对分数（0-100）、引用或 insight id、以及文档→符号链接的排序结果。 |
 | `list_tasks` | 列出本项目任务记录（含归档，带标记）。新会话/续接前先调用。 |
@@ -145,6 +82,19 @@ dsh plugin --profile web add /path/to/dsh-project-memory.tgz
 所以插件的宿主命令**只保留 `/tasks` 一条**，其余动作全部作为它的子动词由卡片按钮驱动：菜单里的重复因此只有一行。
 手敲 `/tasks` 回车即执行（与合并前一致）；手敲 `/tasks switch x` 这类带参数的行不再被识别为命令，请用卡片按钮。
 
+## 工作原理
+
+设计遵循四个原则：
+
+- **易失性** — 上下文是临时的，会话压缩即丢失。
+- **持久性** — **记忆**存于磁盘，跨压缩与会话保留。
+- **紧凑性** — 代码层每个符号只存一行声明，所以代码为主的项目仍约 **0.5% 源码体积**（示例项目中 8.8 MB 源码 → 49 KB 索引），**召回**替代了通读整个文件。文档层按设计更重：每个 chunk 保留 ≤300 字符的注入 `summary`、覆盖整 chunk 的 `terms`，以及预计算的 `searchText`。纯文档语料实测（179 chunk / 225 KB Markdown）：`terms` ≈ 源码 **27.5%**，整库落盘 ≈ 源码 **166%**——文档占比高的项目请按「约等于文档本身大小」估，而不是 0.5%。
+- **可核验性** — **召回**在适用时携带 `路径:行号` 引用，agent 可对照源文件核实。
+
+构建**记忆**无需预先全量扫描：文件在模型读取时被记忆，**记忆**恰好覆盖实际处理过的内容。未变更的文件重读是空操作（内容哈希），因此**记忆**的持续维护开销很低。
+
+存储按项目独立存放，并跟随代码库变化：文件变更按内容哈希重新抽取，文件删除则同步移除。经验层仅检索，累积不影响上下文。
+
 ## 设计
 
 ```
@@ -178,97 +128,9 @@ TaskPanel (Container)
 └── TaskComponents   (MiniBar, TaskCard — 纯展示组件)
 ```
 
-## 设计取舍
-
-### 1. 同步无锁事务，而非异步锁
-
-**我们做：** 所有写入走 `store.commit(fn)` 同步事务。回调 `fn` 内完成校验与变更，成功后才原子落盘。JS 事件循环天然串行，CAS (`applyFileUpdate`) 让并发写入幂等。
-
-**不做：** 异步互斥锁、文件锁、多进程协调。
-
-**为什么：** DSH 基于 Cordis，单进程是架构基石。为极少见的多进程场景加锁，会让热路径（每次 `remember`/`forget`/`index_doc`）增重。同步事务让热路径中位数 ~2 ms，零争用开销。
-
-### 2. Watch：事务外计算，事务内提交
-
-**我们做：** 重活（mtime/哈希/扫描/解析/PDF 抽取）在事务外跑，单次 `commit` 原子应用全部变更。失败回滚 snapshot，下轮自动重试。
-
-**不做：** 持锁做解析，或用 `fs.watch` 事件。
-
-**为什么：** PDF 抽取与大文件解析耗时明显，持锁会阻塞 `remember`/`forget`/`query_memory`。轮询 + mtime+内容哈希跨平台一致（网络盘、Docker 卷、WSL 皆可），避免 `fs.watch` 的「重复触发/漏事件」噩梦。
-
-### 3. 损坏文件隔离，不自动修复
-
-**我们做：** JSON 解析失败时，坏文件改名 `*.corrupt`、记错误、该文件存储重头开始，其余分片不受影响。
-
-**不做：** 预写日志 (WAL)、嵌入式数据库、自动部分恢复。
-
-**为什么：** 一个损坏分片 = 一个源文件索引丢失，隔离成本近零。WAL 或嵌入式 DB 增加 500 KB+ 原生依赖、锁竞争、新故障模式（WAL 自身损坏）。权衡：丢一个文件索引 vs. 引入重型原生栈。
-
-### 4. 查询零向量、零语义搜索
-
-**我们做：** BM25 + CJK 短语加分（3+ 字 ×1.5）、同义词表双向展开、字段加权（标题 ×5）、经验层短语加分。查询侧零 LLM 调用。
+工作流卡片可收起，自动适应 dsh 及主题插件风格，提供四种卡片风格切换。
 
-**不做：** 向量嵌入、稠密检索、重排序、混合搜索。
-
-**为什么：** 向量需要嵌入模型（本地重、远程慢+贵+隐私）、向量索引（HNSW/IVF 占内存+建索引慢）、重排序（再调一次 LLM）。对本插件所针对的查询，词法 BM25 已经够用且可核实：基准（真实 Vue 项目 29 条查询）文件级 hit@5 为 **96.6%**，其中 28 条是精确符号名查询、词法检索基本必中；整 chunk `terms` 把文档词项覆盖从 **27.3% 提到 100%**，而原本可答的查询排序不变（MRR **0.958** vs **0.955**）。这些数字来自内部一个 Vue 项目 + 手工标注的 29 条查询集，出了那个语料无法复现——但**方法**已随代码发布：`scripts/bench.mjs --queries 你的查询集.json`，可以在你自己的项目上跑完全相同的测量。边际收益不抵 10x 复杂度/成本。
-
-### 5. 索引确定且不调用模型
-
-**我们做：** keywords 由规则推导（标题加权词项），并构建覆盖整 chunk 的 `terms`——两者都确定、可复现。doc↔symbol 链接从中文命中带出英文符号名，CJK 分词保证跨语种命中。`llmQueryExpansion: false` 时查询完全不碰 LLM。
-
-**不做：** 索引时调用模型去翻译或改写文档，也不在查询时翻译。
-
-**为什么：** 索引期调用模型会让索引变慢、不确定、不可复现——同一份文档两次索引可能得到不同结果。查询时翻译增延迟，且有一个硬失败模式（译错 = 零召回）。规则 + 符号链接覆盖常见情况，离线可用，并让索引期保持零模型调用。
-
-### 6. 面向模型的记忆：agent 自己写，不把人放进回路
-
-**我们做：** 把 agent 当作一等写入者。`remember` / `save_lesson` **随时可写任意作用域**（`task` / `project` / `global`），不需要人参与；提升是确定性的，就发生在普通写入路径里：跨任务的 token 重叠去重会累积 `sourceTaskIds`，随后 `promoteAllTasksToProject` / `promoteProjectToGlobal` 在佐证数达标时把条目上移（升 project 需 ≥2 个任务命中，升 global 需 ≥ `globalPromoteTasks`，默认 3）。整条链路不等任务面板：用户从不打开 UI，记忆照样会积累、去重、逐级提升。
-
-**我们做（标注）：** 让「推断出来的」和「记录下来的」可区分。v0.5 `reflection`（可选、**默认关闭**）是唯一做推断而非记录的写入者：它写的是 task 级草稿，带 `draft: true` / `source: 'reflect'`；只要还是草稿，`recall` 与静默注入就会跳过它。
-
-**不做：** 不要求「人工批准」记忆才能生效，也不把 UI 变成写入路径上的一步。`draft` 是**来源标记 + 佐证门槛**，不是审批队列。
-
-**为什么：** 记忆的消费方是 agent，而 agent 通常是无头的——只在有人点卡片时才升级的记忆，等于永远不会升级。保留标注就保住了这份谨慎里有用的那一半（推断 ≠ 记录，且未经佐证的单任务推断不进提示词），同时又不用给正常路径加税。草稿靠佐证毕业：第二个任务通过模型自己的写入命中了它，或者模型把同一知识直接写到 project 级（此时会挂到既有条目上，而不是复制一份）。
-
-### 7. 直接返回完整条目
-
-**我们做：** `query_memory` 直接返回含 `path:line` 引用的完整条目，每条可回源核实。
-
-**不做：** 先返回极简索引（如 700 字符），再二次调工具取详情。
-
-**为什么：** 完整返回保持 **可核验性**——Agent 能看到每条声明的出处行号。也避免了每次有效命中多一轮工具调用+上下文切换。条目本已紧凑（~300 字摘要+引用，外加一个从不进上下文的检索用 `terms`），完整返回的 token 成本低于二次调用。
-
-### 8. 符号提取聚焦开发者实际搜索的内容
-
-**我们做：** 正则符号提取（函数/类/方法/接口/类型别名），含字符串/注释掩码、多行签名、跨文件按名链接。对 TypeScript/JavaScript 项目，可选的 L2 增强层利用 TS Compiler API 推导返回类型、实例化泛型、提取接口 —— 全部按内容哈希缓存，毫秒级复用。
-
-**不做：** tree-sitter AST、导入图、调用图、跨文件全程序类型推导。
-
-**为什么：** 正则扫描器零依赖、8 语言、<1 ms/文件，覆盖开发者最常搜索的声明（名字、签名、泛型）。可选 TS 增强层为 TS/JS 提供语义深度，且无原生依赖。按名跨文件链接已覆盖最常见的「找相关代码」场景。全程序分析会引入原生二进制、安装体积增 10x、语言版本即破——边际收益仅在剩余 5% 的边缘情况。
-
-### 9. `forget` 按关键词激进；精确请用 ID
-
-**我们做：** `forget query` 删除所有 token 重叠 ≥0.5 的经验笔记。
-
-**不做：** 交互确认、软删除/回收站、仅精确匹配。
-
-**为什么：** 经验笔记低风险、高量、仅检索。激进删除防止陈旧噪音污染搜索。精确删用 ID（`query_memory` 输出里有）。
-
-### 10. TS 增强可选、异步、缓存
-
-**我们做：** L2 TS Compiler API 在优先级队列异步跑（P0 `fs/observed`、P1 `watch`、P2 `index_repo`），结果按内容哈希缓存 `type-cache/`。零配置——`npm i -D typescript@5` 或 `npm i -D typescript@6` 即用。无 TS 或禁用时优雅回退 L1 正则。
-
-**不做：** 强制 TS、阻塞式增强、全程序类型检查。
-
-**为什么：** 强制 TS 会让非 TS 项目装不上。阻塞增强会卡死大项目 `index_repo`。全程序检查慢 10x、内存重。设计：读到即增强、缓存复用、热路径永不阻塞。
-
-### 11. 子代理会话暂不纳入（以后可能做）
-
-**我们做：** 把以子代理身份启动的会话（`origin: 'subagent'` / `delegationDepth > 0`）排除在自动建档与绑定之外：它们的 `todo_write` 不建任务，也不继承任何任务绑定。
-
-**不做：** 把委派出去的运行的 steps 与文件并回派发它的那条任务。这块**尚未设计**：目前没有委派工作的父子关联模型，而粗暴实现只会让每个子代理各铸一条项目任务。
-
-**为什么：** 子代理只要写一次 todo 就会各自建档，一次 fan-out 就会往任务列表里灌进一批没人会续接的临时条目。排除掉它们，任务列表才等于「用户真正拥有的工作」。代价是委派进度在任务记录里不可见；正确的合并方式（子步骤折进父任务，或单列一个委派视图）属于后续工作。
+![四种卡片风格](docs/images/image-4.png)
 
 ## 配置
 
@@ -288,11 +150,19 @@ TaskPanel (Container)
 | `autoIndexOnFirstUse` | false | 插件加载时对当前工作目录做全量扫描（可选） |
 | `watch` | true | 启用后台刷新 |
 | `watchInterval` | 15 | 轮询间隔（秒） |
+| `maxScanFiles` | 20000 | 单次扫描的文件数硬上限；被截断时会在报告里说明，且**绝不**删除没扫到的旧条目。设 `0` 取消上限（自担风险） |
+| `maxScanDepth` | 12 | 单次扫描的目录深度硬上限。设 `0` 取消 |
+| `allowUnsafeRoots` | false | 允许**显式**工具调用（带 `root` 的 `index_repo`/`watch_repo`/`remember`）指向危险根。自动路径（懒索引、会话审计、TaskBridge、`autoIndexOnFirstUse`）无论此项如何都不会越权 |
 | `tsPath` | (自动) | 可选：强制指定特定 `typescript` 安装路径；省略时按项目 cwd → 插件 node_modules 向上解析 |
 | `enableTypeScript` | true | 设为 `false` 彻底禁用 L2 TS 增强（仅保留 L1 正则） |
+
+### 记忆与注入旋钮
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
 | `insight.*` | dedupOverlap `0.7` · reinforceBand `0.65` · maxProject `100` · maxGlobalProcedures `200` · promoteConfidence `0.7` · globalPromoteTasks `3` · decayDays `90` · `globalFile`（自动） | v0.5 insight 去重/强化/提升/容量/归档设置 |
 | `reflection.enabled` | false | v0.5 LLM 反思，**只写任务级草稿**（触发于任务切走/归档）。`cooldownMs` `1800000`、`maxLessonsPerReflect` `3`、`maxDecisionsPerReflect` `2` |
-| `autoContext.enabled` | true | v0.5 静默注入包装（entry 常驻块 + relevance）。宿主无法解析会话 cwd 时完全透传（零副作用）；`maxTokens` `400`、`editedMax` `3`（resident 任务卡显示最近"编辑中"文件数）、`signalMinRatio` `0.5`（提示至少要达到该层最高分的一半）、`skipEchoSelfTodo` `true`（模型自己写/维护任务清单后、无新人类消息时不回声任务卡，省 token；相关 insights 仍注入）、`budgetLog` `off`（预算丢弃审计写到 stderr：`off` 静默 / `once` 每会话最多一行 / `all` 丢弃组合每变化一次一行。注入按优先级排程，预算不够时丢掉低优先级条目属于**正常降级而非故障**，所以默认不占用用户终端）、`reinjectItemsAfter` `0`（同一条 insight 重复注入的冷却步数；`0` = 正文没变就不在本会话内再注入——注入消息留在会话历史里，重发只是重复占位） |
+| `autoContext.enabled` | true | v0.5 静默注入包装（entry 常驻块 + relevance）。宿主无法解析会话 cwd 时完全透传（零副作用）；`maxTokens` `400`、`editedMax` `3`（resident 任务卡显示最近"编辑中"文件数）、`signalMinRatio` `0.5`（提示至少要达到该层最高分的一半）、`skipEchoSelfTodo` `true`（模型自己写/维护任务清单后、无新人类消息时不回声任务卡，省 token；相关 insights 仍注入）、`budgetLog` `off`（预算丢弃审计写到 stderr：`off` 静默 / `once` 每会话最多一行 / `all` 丢弃组合每变化一次一行。注入按优先级排程，预算不够时丢掉低优先级条目属于**正常降级而非故障**，所以默认不占用用户终端）、`reinjectItemsAfter` `0`（同一条 insight 重复注入的冷却步数；`0` = 正文没变就不在本会话内再注入——注入消息留在会话历史里，重发只是重复占位）、`rootNotice` `true`（记忆根是从无标记的工作目录**推定**出来时，向模型通告一次根在哪、怎么改） |
 | `autoContext.gateCooldownSteps` | 2 | **准入旋钮**：两次*条目*注入之间至少隔几步（常驻任务卡不受限——它是状态快照，内容变了就该更新）。这是"别频繁注入"的主旋钮 |
 | `autoContext.maxItemsPerSession` | 12 | 每会话条目注入条数硬上限；预算是上限不是目标，用尽后条目通道持续沉默 |
 | `autoContext.maxItemCharsPerSession` | 4000 | 同上，按字符计 |
@@ -319,6 +189,16 @@ TaskPanel (Container)
 
 两个最常用的开关是 `lazyIndexing`（模型读取文件的瞬间即索引；默认开启）和 `autoIndexOnFirstUse`（插件加载时对当前工作目录做全量扫描；默认关闭）。懒加载建立的索引根会自动注册到 watcher，文件变更无需手动 `watch_repo` 也能保持新鲜。
 
+**项目根是怎么定的。** 全插件同一套策略——懒索引、会话审计、TaskBridge、所有工具都走它：显式 `root` 参数优先；其次是显式登记的根（`watch_repo`）；其次是最近的、含 VCS 标记（`.git`/`.hg`/`.svn`）或构建/清单标记（`package.json`、`go.mod`、`Cargo.toml`、`pyproject.toml` 等）的祖先目录；最后是**会话工作目录本身（只要它是安全目录）**。所以你在一个没有标记的临时目录里启动 dsh，项目记忆照样能用——插件只会说明一次：
+
+```
+memory root: /Users/me/scratch (inferred from the session working directory; no project marker found).
+If project memory should live elsewhere, pass `root: <dir>` to index_repo / watch_repo / remember / query_memory,
+or restart dsh inside the project directory.
+```
+
+这条通告每个会话只发一次，可用 `autoContext.rootNotice: false` 关掉。插件**不会**做的是把任意目录升格成项目：在工作目录之外读到一个散文件不会记任何东西；危险根（文件系统根、家目录、共享临时目录、系统/包管理器前缀——POSIX 上如 `/opt/homebrew`，Windows 上是 `%SystemRoot%`/`%ProgramFiles%`/`%ProgramData%`）直接拒绝——旧版正是从这些目录一路扫下去把内存打满的。工作目录属于这些目录的会话，记忆功能整体停用（stderr 会有一行说明）。
+
 配置存放在插件的 config 对象中。修改方式：在 profile 的 `cordis.patch.yml` 里加一条覆盖项——web profile 对应 `~/.dsh/profiles/web/cordis.patch.yml`：
 
 ```yaml
@@ -329,7 +209,10 @@ TaskPanel (Container)
     llmQueryExpansion: false    # 关闭：不用 LLM 扩展查询，节省 token（默认）
     watch: true                 # 开启：被监听根目录后台保持新鲜（默认）
     watchInterval: 15           # 轮询间隔（秒）
+    maxScanFiles: 20000         # 单次扫描文件上限（截断会报告，且不会误删旧条目）
+    maxScanDepth: 12            # 单次扫描目录深度上限
     enableTypeScript: true      # 开启：装了 TS 时启用 L2 语义增强（默认）
+    # allowUnsafeRoots: false   # 保持 false，除非你确实要显式索引家目录/系统目录
     # budgetLog: once           # 调试用：注入被预算挤掉时在 stderr 留痕（默认 off 静默）
     # reinjectItemsAfter: 20    # 调试用：同一条 insight 隔 N 步才允许重发（默认 0 = 本会话只发一次）
     # tsPath: /custom/path/to/typescript  # 可选：强制指定 TS 安装路径
@@ -345,6 +228,66 @@ dsh web --patch ./config.yml
 
 其中 `config.yml` 内容就是上面的覆盖块。
 
+## 性能
+
+### 合成基准测试（Node 24.19，WSL2 / 20 vCPU，Linux 文件系统）
+
+| 场景 | 规模 | 实测 |
+|------|------|------|
+| 批量冷记忆构建 | 5,000 文件 / 20k 条目 | 269 ms 均值（p50 267）|
+| 冷加载 | 5,000 文件 | 40 ms |
+| 热路径懒记忆 | 单文件重记忆+落盘 | p50 2.4 ms / 最大 5.5 ms (5k) |
+| query_memory (缓存命中) | 5k 文件 / 20k 条目 | p50 2.6 ms / p95 5.4 ms |
+| query_memory (缓存命中) | 1k 文件 / 4k 条目 | p50 0.6 ms / p95 1.6 ms |
+| 批量冷记忆构建 | 10,000 文件 / 40k 条目 | 551 ms 均值（p50 528）|
+| 冷加载 | 10,000 文件 | 90 ms |
+| 热路径懒记忆 | 单文件重记忆+落盘 | p50 5.4 ms / 最大 9.2 ms (10k) |
+
+> 合成基准：生成代码（~4–5 符号/文件），Node 24.19 / WSL2 / 20 vCPU / Linux 文件系统，实测于 2026-09-14。复现命令 `npm run bench:synthetic -- 5000`（脚本 `scripts/bench-synthetic.mjs`）。测量纯索引开销，不含 LLM 调用。query_memory 使用 IDF 缓存 + 预计算 searchText；写入后的首次查询会重建 IDF（**40k 条目 106 ms**，20k 条目 57 ms，4k 条目 12 ms），后续查询命中缓存。
+
+### 真实项目存储体积
+
+| 项目 | 文件数 | 条目数 | 存储体积 | 单条目 |
+|------|--------|--------|----------|--------|
+| Java Spring Boot 后端 | 1,254 | 7,335 | 6.7 MB | ~0.9 KB |
+| Vue 3 + Vite 前端 | 289 | 2,141 | 1.0 MB | ~0.5 KB |
+
+> 真实项目（Java + Vue），测试于 Linux 文件系统（Node 24）。真实项目单条目体积小于合成基准，因符号密度更低、声明行更短。
+
+### 自己复现这些数字
+
+与其让你相信上面的表格，不如把测量本身一起发布——它随仓库发布，**也随 npm 包一起发布**（`scripts/` 已包含在 tarball 中）。脚本**不需要 dsh 实例、不需要网络、不调用任何模型**，也**不碰被测项目自己的 store**——结果写进临时目录，跑完删除：
+
+```bash
+npm run bench -- /你的/项目路径
+# 或带参数：
+node scripts/bench.mjs /你的/项目路径 [--json] [--samples 100] [--no-pdf] [--keep]
+```
+
+输出包含：冷索引（拆成 read+hash / extract / commit 三段）、冷加载、IDF 重建、冷查询与热查询延迟（走线上同一套 scorer，100 条采样报 p50/p95/max）、单文件热重索引、存储体积与每条字节数。示例——我们内部的 Vue 项目（289 文件 / 2,141 条目，Node 24，20 CPU，Linux）：
+
+```
+冷索引     253 ms   （read+hash 9 ms · extract 229 ms · commit 13 ms）← 第二次、页缓存已热
+存储       1.10 MB · 538 bytes/条目 · 冷加载 4.6 ms
+热查询     p50 0.80 ms · p95 1.35 ms          （2,141 条目）
+单文件重索引  p50 0.33 ms
+```
+
+两个我们宁可自己说清楚的坑：`read+hash` 受操作系统页缓存影响——同一个语料第一遍花了 787 ms、第二遍 253 ms，报数时请说明是第几遍；**真实项目比上面的合成基准慢**——在一个大型 TypeScript 仓库的 3,000 文件切片上（15,594 条目）热查询 p50 为 7.5 ms，因为真实声明文本比生成出来的桩代码长得多。带 `--queries 你的查询集.json` 可以在你自己的项目上跑同一套标注集方法（hit@5 / hit@10 / MRR）。
+
+## 设计取舍
+
+- **同步无锁事务，而非异步锁** — 不加异步锁、文件锁或多进程协调：DSH 基于 Cordis，单进程是架构基石，为极少见的多进程场景加锁只会让热路径（每次 `remember`/`forget`/`index_doc`）增重；同步事务下热路径中位数 ~2 ms，零争用。
+- **Watch：事务外计算，事务内提交** — 不持锁解析、也不用 `fs.watch`：解析与 PDF 抽取很慢，持锁会阻塞查询；轮询 + mtime/内容哈希在网络盘、Docker 卷、WSL 上行为一致，没有 `fs.watch` 的重复触发/漏事件问题。
+- **损坏分片隔离，不自动修复** — 解析失败的 JSON 改名 `*.corrupt`、该文件重头开始，其余分片不受影响；不引入 WAL 或嵌入式数据库：那要多 500 KB+ 原生依赖、锁竞争，以及一个新故障模式（WAL 自身损坏），而代价只是丢一个文件的索引。
+- **查询零向量、零语义搜索** — 不引入嵌入模型、向量索引（HNSW/IVF）或重排序：在本插件针对的查询上词法检索已经够用——真实 Vue 项目 29 条标注查询的文件级 hit@5 为 **96.6%**，整 chunk `terms` 把文档词项覆盖从 **27.3% 提到 100%** 且 MRR 不变（**0.958** vs **0.955**）。边际收益不抵 10x 复杂度/成本；方法随代码发布，`scripts/bench.mjs --queries 你的查询集.json` 可在你自己的项目上复现。
+- **索引确定且不调用模型** — 索引期不调模型、查询期也不翻译：前者会让同一份文档两次索引结果不同，后者有一个硬失败模式（译错 = 零召回）；规则 + 符号链接已经覆盖常见情况，且离线可用。
+- **面向模型的记忆：agent 自己写，不把人放进回路** — 不要求人工批准：记忆的消费方是 agent，而 agent 通常是无头的，只在有人点卡片时才升级的记忆等于永远不会升级。`draft` 是「来源标记 + 佐证门槛」而不是审批队列——唯一的推断型写入者 `reflection`（默认关闭）只写任务级草稿，草稿不进召回与注入。
+- **直接返回完整条目** — 条目本就紧凑，完整返回更可核验，也少一轮往返。
+- **`forget` 按关键词激进；精确请用 ID** — 不做确认弹窗、回收站或仅精确匹配：经验笔记低风险、高量、仅用于检索，陈旧噪音比误删更伤。精确删用 `query_memory` 输出里的 ID。
+- **TS 增强可选、异步、缓存** — L2 TS Compiler API 在优先级队列异步跑（P0 `fs/observed`、P1 `watch`、P2 `index_repo`），结果按内容哈希缓存；不强制 TS、也不阻塞索引：强制会让非 TS 项目装不上，阻塞会卡死大项目的 `index_repo`；`npm i -D typescript@5|6` 即自动启用，没有 TS 时回退 L1 正则。
+- **子代理会话暂不纳入（以后可能做）** 
+
 ## 开发（面向贡献者）
 
 以下命令用于**维护插件源码**，普通用户无需执行。安装插件只需使用[安装](#安装)一节中的命令。

package/client/client.js

@@ -668,92 +668,92 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var TaskPanel_module_css_default = {
-			"emptyTitle": "vZSZnG_emptyTitle",
-			"stepRow": "vZSZnG_stepRow",
-			"dragGhostClose": "vZSZnG_dragGhostClose",
-			"counts": "vZSZnG_counts",
-			"dragGhostContent": "vZSZnG_dragGhostContent",
-			"dropTargetBefore": "vZSZnG_dropTargetBefore",
-			"stepContent": "vZSZnG_stepContent",
-			"memRowArchived": "vZSZnG_memRowArchived",
-			"memCount": "vZSZnG_memCount",
-			"stepDone": "vZSZnG_stepDone",
+			"memNew": "vZSZnG_memNew",
+			"dragHandle": "vZSZnG_dragHandle",
 			"headerIconBtn": "vZSZnG_headerIconBtn",
-			"cardHead": "vZSZnG_cardHead",
+			"memCount": "vZSZnG_memCount",
 			"memTitle": "vZSZnG_memTitle",
-			"syncHint": "vZSZnG_syncHint",
-			"stepInput": "vZSZnG_stepInput",
-			"dragHandle": "vZSZnG_dragHandle",
-			"section": "vZSZnG_section",
-			"fileRow": "vZSZnG_fileRow",
-			"memoryPane": "vZSZnG_memoryPane",
-			"dragGhost": "vZSZnG_dragGhost",
-			"memBody": "vZSZnG_memBody",
-			"badge": "vZSZnG_badge",
-			"boundaryFallback": "vZSZnG_boundaryFallback",
+			"headerTitle": "vZSZnG_headerTitle",
+			"memToolbarActs": "vZSZnG_memToolbarActs",
+			"stepContentRun": "vZSZnG_stepContentRun",
+			"miniChevron": "vZSZnG_miniChevron",
+			"panel": "vZSZnG_panel",
+			"memRowArchived": "vZSZnG_memRowArchived",
+			"filePath": "vZSZnG_filePath",
+			"notice": "vZSZnG_notice",
+			"fileDot": "vZSZnG_fileDot",
+			"cardTitle": "vZSZnG_cardTitle",
+			"cardTitleRow": "vZSZnG_cardTitleRow",
+			"miniText": "vZSZnG_miniText",
+			"stepContent": "vZSZnG_stepContent",
+			"fileLine": "vZSZnG_fileLine",
+			"boundBadge": "vZSZnG_boundBadge",
 			"card": "vZSZnG_card",
-			"sectionCount": "vZSZnG_sectionCount",
-			"stepsList": "vZSZnG_stepsList",
-			"stepRun": "vZSZnG_stepRun",
-			"dragGhostCard": "vZSZnG_dragGhostCard",
-			"hintsOff": "vZSZnG_hintsOff",
-			"stepToggle": "vZSZnG_stepToggle",
-			"taskList": "vZSZnG_taskList",
+			"updated": "vZSZnG_updated",
+			"muted": "vZSZnG_muted",
 			"memActs": "vZSZnG_memActs",
-			"chevron": "vZSZnG_chevron",
-			"cardFooter": "vZSZnG_cardFooter",
+			"memLabel": "vZSZnG_memLabel",
 			"memToolbar": "vZSZnG_memToolbar",
-			"memList": "vZSZnG_memList",
-			"memNew": "vZSZnG_memNew",
+			"syncHint": "vZSZnG_syncHint",
+			"miniIcon": "vZSZnG_miniIcon",
+			"dropTargetAfter": "vZSZnG_dropTargetAfter",
+			"stepPending": "vZSZnG_stepPending",
+			"dragGhostCard": "vZSZnG_dragGhostCard",
+			"stepEditable": "vZSZnG_stepEditable",
+			"sectionCount": "vZSZnG_sectionCount",
+			"stepToggle": "vZSZnG_stepToggle",
+			"hintsOff": "vZSZnG_hintsOff",
+			"boundaryFallback": "vZSZnG_boundaryFallback",
+			"emptyTitle": "vZSZnG_emptyTitle",
+			"memRowMain": "vZSZnG_memRowMain",
+			"cardHead": "vZSZnG_cardHead",
 			"header": "vZSZnG_header",
-			"filePath": "vZSZnG_filePath",
-			"cardTitleRow": "vZSZnG_cardTitleRow",
-			"cardTitleEditable": "vZSZnG_cardTitleEditable",
-			"boundBadge": "vZSZnG_boundBadge",
-			"cardMeta": "vZSZnG_cardMeta",
-			"progressText": "vZSZnG_progressText",
-			"stepContentRun": "vZSZnG_stepContentRun",
-			"headerTitle": "vZSZnG_headerTitle",
 			"editorArea": "vZSZnG_editorArea",
-			"muted": "vZSZnG_muted",
-			"cardTitle": "vZSZnG_cardTitle",
-			"emptyDesc": "vZSZnG_emptyDesc",
+			"badgeArchived": "vZSZnG_badgeArchived",
+			"stepRun": "vZSZnG_stepRun",
+			"miniBar": "vZSZnG_miniBar",
+			"stepDragging": "vZSZnG_stepDragging",
+			"memoryPane": "vZSZnG_memoryPane",
+			"dragGhostClose": "vZSZnG_dragGhostClose",
+			"cardMeta": "vZSZnG_cardMeta",
+			"stepRow": "vZSZnG_stepRow",
+			"filesList": "vZSZnG_filesList",
+			"memNewRow": "vZSZnG_memNewRow",
 			"cardBody": "vZSZnG_cardBody",
-			"sectionLabel": "vZSZnG_sectionLabel",
-			"fileLine": "vZSZnG_fileLine",
-			"track": "vZSZnG_track",
+			"stepContentDone": "vZSZnG_stepContentDone",
+			"cardTitleEditable": "vZSZnG_cardTitleEditable",
 			"dropPulse": "vZSZnG_dropPulse",
 			"kindBadge": "vZSZnG_kindBadge",
-			"filesList": "vZSZnG_filesList",
+			"headerRight": "vZSZnG_headerRight",
 			"trackFill": "vZSZnG_trackFill",
-			"memNewRow": "vZSZnG_memNewRow",
-			"headerIcon": "vZSZnG_headerIcon",
-			"headerLeft": "vZSZnG_headerLeft",
-			"notice": "vZSZnG_notice",
-			"stepDragging": "vZSZnG_stepDragging",
-			"miniText": "vZSZnG_miniText",
-			"stepPending": "vZSZnG_stepPending",
-			"miniIcon": "vZSZnG_miniIcon",
-			"fileDot": "vZSZnG_fileDot",
-			"stepEditable": "vZSZnG_stepEditable",
-			"miniBar": "vZSZnG_miniBar",
-			"memLabel": "vZSZnG_memLabel",
-			"memMeta": "vZSZnG_memMeta",
+			"progressText": "vZSZnG_progressText",
 			"panelIn": "vZSZnG_panelIn",
+			"dragGhostContent": "vZSZnG_dragGhostContent",
+			"emptyDesc": "vZSZnG_emptyDesc",
+			"chevron": "vZSZnG_chevron",
+			"track": "vZSZnG_track",
+			"sectionLabel": "vZSZnG_sectionLabel",
+			"cardFooter": "vZSZnG_cardFooter",
+			"stepDone": "vZSZnG_stepDone",
+			"section": "vZSZnG_section",
+			"dropTargetBefore": "vZSZnG_dropTargetBefore",
+			"memList": "vZSZnG_memList",
+			"cardBound": "vZSZnG_cardBound",
+			"fileRow": "vZSZnG_fileRow",
+			"handleGrip": "vZSZnG_handleGrip",
+			"counts": "vZSZnG_counts",
+			"stepsList": "vZSZnG_stepsList",
+			"dragGhost": "vZSZnG_dragGhost",
 			"emptyState": "vZSZnG_emptyState",
-			"memRowMain": "vZSZnG_memRowMain",
-			"badgeArchived": "vZSZnG_badgeArchived",
-			"panel": "vZSZnG_panel",
-			"stepContentDone": "vZSZnG_stepContentDone",
+			"memBody": "vZSZnG_memBody",
+			"headerLeft": "vZSZnG_headerLeft",
 			"memRow": "vZSZnG_memRow",
-			"cardBound": "vZSZnG_cardBound",
 			"badgeDraft": "vZSZnG_badgeDraft",
-			"handleGrip": "vZSZnG_handleGrip",
-			"headerRight": "vZSZnG_headerRight",
-			"updated": "vZSZnG_updated",
-			"miniChevron": "vZSZnG_miniChevron",
-			"dropTargetAfter": "vZSZnG_dropTargetAfter",
-			"memToolbarActs": "vZSZnG_memToolbarActs"
+			"badge": "vZSZnG_badge",
+			"headerIcon": "vZSZnG_headerIcon",
+			"taskList": "vZSZnG_taskList",
+			"memMeta": "vZSZnG_memMeta",
+			"stepInput": "vZSZnG_stepInput"
 		};
 		//#endregion
 		//#region src/client/TaskComponents.tsx
@@ -2201,8 +2201,8 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var TaskCommandNode_module_css_default = {
-			"row": "TPe-xa_row",
-			"icon": "TPe-xa_icon"
+			"icon": "TPe-xa_icon",
+			"row": "TPe-xa_row"
 		};
 		//#endregion
 		//#region src/client/TaskCommandNode.tsx

package/cordis.patch.yml

@@ -10,4 +10,10 @@
         lazyIndexing: true
         autoIndexOnFirstUse: false
         watch: true
-        watchInterval: 15
+        watchInterval: 15
+        # 危险根护栏（家目录 / 文件系统根 / 系统与包管理器前缀整体扫描会吃满内存）。
+        # 自动路径永远不越权；true 只放开**显式**带 root 的工具调用。
+        allowUnsafeRoots: false
+        # 单次扫描上限；截断会报告，且不会删除未扫到的条目。
+        maxScanFiles: 20000
+        maxScanDepth: 12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk_vat-y/dsh-project-memory",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "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",
@@ -18,8 +18,9 @@
     "url": "https://github.com/00080000/dsh-project-memory.git"
   },
   "scripts": {
-    "test": "node test/run-test.mjs && node test/taskbridge.test.mjs && node test/insight-store.test.mjs && node test/reflection-pipeline.test.mjs && node test/auto-inject.test.mjs && node test/insight-actions.test.mjs && node test/host-contract.test.mjs && node test/llm-route.test.mjs && node test/doc-index.test.mjs && node test/client-hints.test.mjs && node test/recall.test.mjs && node test/readiness.test.mjs && node test/insight-derive.test.mjs && node test/readiness-eval.test.mjs && node test/ops.test.mjs && node test/injection-audit.test.mjs && node test/injection-budget.test.mjs && node test/injection-scenarios.test.mjs && node test/bugfix-0.5.7.test.mjs && node test/client-icons.test.mjs && node test/client-slash.test.mjs && node test/workflow-command.test.mjs && node test/client-session-id.test.mjs",
+    "test": "node test/run-test.mjs && node test/taskbridge.test.mjs && node test/insight-store.test.mjs && node test/reflection-pipeline.test.mjs && node test/auto-inject.test.mjs && node test/insight-actions.test.mjs && node test/host-contract.test.mjs && node test/llm-route.test.mjs && node test/doc-index.test.mjs && node test/client-hints.test.mjs && node test/recall.test.mjs && node test/readiness.test.mjs && node test/insight-derive.test.mjs && node test/readiness-eval.test.mjs && node test/ops.test.mjs && node test/injection-audit.test.mjs && node test/injection-budget.test.mjs && node test/injection-scenarios.test.mjs && node test/bugfix-0.5.7.test.mjs && node test/client-icons.test.mjs && node test/client-slash.test.mjs && node test/workflow-command.test.mjs && node test/client-session-id.test.mjs && node test/task-view.test.mjs && node test/root-guards.test.mjs",
     "eval:injection": "node test/injection-scenarios.test.mjs",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.client.json",
     "selfcheck:triggers": "node test/injection-scenarios.test.mjs --selfcheck",
     "bench": "node scripts/bench.mjs",
     "bench:synthetic": "node scripts/bench-synthetic.mjs",

package/scripts/bench-synthetic.mjs

@@ -90,7 +90,7 @@ async function coldIndex(root, config) {
   const store = new ProjectMemoryStore(storeDir)
   // 首次 load 会读盘（若已存在），这里传入一个全新实例以贴近真实冷启动
   store.load()
-  const files = walkDir(root)
+  const { files } = walkDir(root)
   const seen = new Set()
   let updated = 0
   const fileUpdates = []
@@ -234,7 +234,7 @@ async function main() {
   {
     const root = tmpd('pm-sym-')
     generateCorpus(root, FILES)
-    const files = walkDir(root).filter((f) => f.endsWith('.js'))
+    const files = walkDir(root).files.filter((f) => f.endsWith(".js"))
     const times = []
     const n = Math.min(files.length, 500)
     for (let i = 0; i < n; i++) {
@@ -256,7 +256,7 @@ async function main() {
     generateCorpus(root, FILES)
     const { store, report } = await coldIndex(root, config)
     void report
-    const files = walkDir(root).filter((f) => f.endsWith('.js'))
+    const files = walkDir(root).files.filter((f) => f.endsWith(".js"))
     const times = []
     const n = Math.min(files.length, 50)
     for (let i = 0; i < n; i++) {

package/scripts/bench.mjs

@@ -123,7 +123,7 @@ const kb = (n) => `${(n / 1024).toFixed(1)} KB`
 const mb = (n) => `${(n / 1024 / 1024).toFixed(2)} MB`
 
 // ---------- 1. 扫描 ----------
-const all = walkDir(root)
+const { files: all } = walkDir(root)
 const targets = []
 let skippedPdf = 0
 for (const abs of all) {