@yolk_vat-y/dsh-project-memory 0.3.4 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.4.1 (2026-09-03)
+
+### TS 6.x 兼容
+
+- **L2/L3 增强器**：验证 TS Compiler API 在 TypeScript 6.0.3 下完全兼容，放开版本限制；`peerDependencies` 与运行时检查同步支持 `^5.0.0 || ^6.0.0`
+- 仅拦截 TS 7.x+（major 版本通常有 breaking changes），警告提示更新为「请使用 TS 5.x/6.x 获得增强类型」
+
+## 0.4.0 (2026-09-02)
+
+### TaskBridge：跨会话开发任务（取代 v1.2 workflow 方案，v2.5 契约落地）
+
+- **定位**：模型会话内用宿主 `todo_write` 维护的清单 + 实际读过的文件，自动沉淀为跨会话可续接的任务实体——新会话 `list_tasks` → `select_task` 即接回进度与文件
+- **事件订阅（`session/event`，签名 (session, event)）**：`todo/write` → 绑定任务 steps 快照整体覆盖，未绑定会话自动新建任务并绑定；`tool/call`（read/write/edit/read_image，`arguments` 为 JSON 串）→ 绑定任务 files 并集（归一化相对路径、项目外拒绝、上限 100）
+- **标题由模型定**：`select_task(title=任务名)` 先命名再写 todo；自动回退取用户消息最后「：」后的任务段（截断 48 字）；续接可 `select_task(taskId, title)` 改名
+- **工具**：`list_tasks` / `select_task`（taskId 精确、自动解归档；title 完全匹配、多候选返回列表、无则新建）/ `archive_task`
+- **用户命令 `/tasks`**（`ctx.commands` 存在时注册，handler 不经模型）：任务数、标题、步骤进度、涉及文件、当前会话绑定；快捷键无宿主 API 不做
+- **`query_memory`**：新增 `type:'task'` 检索（title/steps/files）；`type:'all'` 结果尾部附一行任务计数提示
+- **存储**：`.dsh-project-memory/tasks.json` + `binding.json`（load 兜底空值、独立于 format v2 布局）；容量随项目体积自适应 `fileCount/20` clamp [5,100]，超限按 lastActiveAt 归档最旧
+- **边界**：不做步骤↔文件映射（todo 无 id、全量替换，语义上不可靠）；不去重（宿主语义）；子代理会话无法可靠判定，接受其自动建档（低频）
+- **环境要求**：自动同步需含 `session/event` 事件与 `todo_write` 的 dsh（0.1.2-alpha.x 实测）；旧宿主 `ctx.on('session/event')` 不触发时降级——任务工具仍可作纯记录使用
+- **测试**：新增 `test/taskbridge.test.mjs`（5 项：持久化往返/容量裁剪/路径归一化/自动建任务+快照覆盖/tool 文件跟踪边界）；既有 166 项测试全绿
+- **文档同步**：README.md / README.zh-CN.md
+
 ## 0.3.4 (2026-09-02)
 
 ### query_memory 性能优化：流式 TF + IDF 缓存
@@ -35,7 +58,7 @@
 - **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
+- **零配置、零感知**：装 TS 重启 dsh 即可；无 TS 或 `enableTypeScript: false` 时优雅回退 L1 正则；TS 7.x 检测到警告并回退 L1
 - **解析策略**：单文件 `createProgram`（快 10x），`createRequire(import.meta.url)` 兼容 ESM，解析优先级：配置 `tsPath` → 项目 cwd 向上 `node_modules/typescript` → 插件自身 `node_modules`
 - **新增配置**：`tsPath`（可选指定 TS 路径）、`enableTypeScript`（默认 true，设 false 彻底禁用）
 - **扩展名支持**：新增 `.mts` `.cts`

package/README.md

@@ -4,16 +4,16 @@
 
 [![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. **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.
+A persistent **project memory** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) agents. Built for software development: the agent's task list (todo_write) and file reads are continuously consolidated into durable cross-session task records, solving context loss. Documents (PDF/Markdown/txt) and code symbols are indexed into a per-workspace store with doc↔symbol cross-links. Experience notes (problem → solution) are deduplicated automatically. All data stored per-project on disk, survives session compaction, recalls with `path:line` citations for verification. Zero external dependencies (only `pdfjs-dist` for PDF text), no vector DB, no native builds.
 
-> 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.
+> 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. Tasks and experience persist across session compactions and handovers.
 
 ## Features
 
 - **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.
 - **L1 Enhanced Regex** — zero-dep regex scanner now extracts generics, parameter/return types, overloads, interfaces, and type aliases for all supported languages, producing one-line identity signatures `fn(a: A, b: B): R — file.ts:42`.
-- **Optional TypeScript semantic enhancement (L2/L3)** — 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 (L3) 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.
+- **Optional TypeScript semantic enhancement (L2/L3)** — 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 (L3) for instant cold-start reuse. Zero config: just install TS (5.x or 6.x) 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.
@@ -22,6 +22,7 @@ Persistent project memory for [DeepSeek Harness](https://github.com/deepseek-ai/
 - **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.
 - **Streaming TF + IDF caching** — query path caches IDF (term inverse frequency) per store version; on cache hit, single-pass streaming scores 20k entries in ~8 ms (5k files) / ~1 ms (1k files) with zero intermediate objects; write path is O(1) version bump.
 - **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.
+- **TaskBridge: cross-session development tasks** — the plugin watches each session's live todo list (`todo_write` events) and file reads (`tool/call`): progress snapshots (`steps`) and touched files sync into durable per-project task entities. An unbound session that writes a todo auto-creates a task. New sessions continue by `list_tasks` → `select_task` (bind / rename / unarchive); `query_memory` gains `type: 'task'` and appends a task-count hint to `type: 'all'` results. The user-side `/tasks` command shows the task stack, step progress, involved files, and the current session binding. Titles are chosen by the model via `select_task(title=…)` (fallback: the part of your message after the last colon). Capacity is project-size adaptive (`fileCount/20`, clamped 5–100). Storage: `.dsh-project-memory/tasks.json` + `binding.json`. Auto-sync requires a dsh build with session events + `todo_write` (verified on 0.1.2-alpha.x); on older hosts the task tools still work as a plain record list.
 - **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.
 
@@ -66,7 +67,7 @@ The store is per-project and follows the codebase: changed files are re-extracte
 
 ## Installation
 
-Tested against dsh **0.1.0-rc.7 through 0.1.2-alpha.3**. The plugin relies exclusively on stable public APIs (`defineTool`, `llm.stream`, `Schema`) declared via peerDependencies, ensuring compatibility with future rc/alpha releases without changes.
+The plugin relies exclusively on stable public APIs (`defineTool`, `llm.stream`, `Schema`) declared via peerDependencies, ensuring compatibility with future rc/alpha releases without changes.
 
 ```bash
 cd dsh-project-memory && dsh plugin --profile web add . -w
@@ -99,6 +100,10 @@ The tools below are **invoked by the agent**, not typed by the user. In the chat
 | `watch_repo root` | Enable automatic refresh: a background poll detects new/changed files (mtime + content hash) and re-indexes only those. Watched roots persist across plugin restarts. |
 | `memory_stats root` | Show what the store contains: totals (files / entries / experience notes), last index time, and the per-file list sorted by recency. |
 | `query_memory query` | BM25 search over docs + symbols + experience, optionally query-expanded by the LLM. Returns ranked hits with relative scores, sources, and doc→symbol references. |
+| `list_tasks` | List task records for the project (archived marked). Call first in a new session before continuing work. |
+| `select_task` | Bind the session to a task so its todo list and file reads sync into it. Exact `taskId`, or exact `title` (multiple matches return candidates; no match creates a new task). Pass `title` with `taskId` to rename. Auto-unarchives. |
+| `archive_task` | Archive a task (hide from default views, exclude from capacity, stop syncing). `select_task` restores it. |
+| `/tasks` (typed by the user, not the model) | Shows the task stack: title, step progress, involved files, and which task the current session is bound to. |
 | `remember problem solution` | Save an experience note. Similar problems supersede instead of duplicating. |
 | `forget id_or_query` | Delete stale experience notes. |
 
@@ -198,7 +203,7 @@ These are deliberate scope choices.
 
 ### 11. TypeScript enhancement is optional, lazy, and cached
 
-**We do:** L2 TS Compiler API enhancement runs async in a priority queue (P0 on `fs/observed`, P1 on `watch`, P2 on `index_repo`), results cached by content hash in `type-cache/`. Zero config — just `npm i -D typescript`. Falls back to L1 regex if TS absent or disabled.
+**We do:** L2 TS Compiler API enhancement runs async in a priority queue (P0 on `fs/observed`, P1 on `watch`, P2 on `index_repo`), results cached by content hash in `type-cache/`. Zero config — just `npm i -D typescript@5` or `typescript@6`. Falls back to L1 regex if TS absent or disabled.
 
 **We don't:** Mandatory TS, blocking enhancement, or full-program type checking.
 
@@ -213,6 +218,7 @@ These are deliberate scope choices.
 | `maxChunksPerFile` | 40 | max chunks per document |
 | `maxFileSizeMb` | 50 | skip documents (incl. PDF) and code files larger than this (MB) |
 | `maxOutputChars` | 8000 | cap for `query_memory` result text (chars) |
+| `tasklist.enabled` | true | enable TaskBridge auto-sync (task entities from the session todo list and file reads) |
 | `maxPdfPages` | 1000 | PDF page cap when pages are not otherwise limited |
 | `llmQueryExpansion` | false | expand queries via `ctx.llm` before BM25 (off by default to save tokens) |
 | `expansionCount` | 6 | max expansion variants |
@@ -257,7 +263,7 @@ These commands are for **maintaining the plugin code** — regular users do not
 
 ```bash
 npm install
-npm test          # 157 tests (v0.3.3): chunker / symbols / store / tools / BM25 / links / watch / lazy / config / dump / concurrency / restore / size limit
+npm test          # 166 tests (v0.4.0) + TaskBridge suite (node test/taskbridge.test.mjs, 5)
 ```
 
 ## License

package/README.zh-CN.md

@@ -4,16 +4,16 @@
 
 [![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）与代码符号写入工作区独立存储，文档自动交叉链接至所提及的代码符号；经验笔记（问题 → 方案）自动去重，避免重复踩坑。所有数据按项目落盘，跨会话压缩与交接保留，召回附带 `路径:行号` 可回源核实。零外部依赖（仅 `pdfjs-dist` 提取 PDF 文本），无向量数据库，无原生构建。
 
-> 插件在磁盘上维护一份精简的项目**记忆**，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查**记忆**，无需重读整个项目。
+> 插件在磁盘上维护一份精简的项目**记忆**，每条记录指向具体的文件与行号；agent 需要快速了解项目时先查**记忆**，无需重读整个项目。任务与经验跨会话压缩与交接保持。
 
 ## 特性
 
 - **文档记忆** — PDF、Markdown、纯文本按块切分并由 LLM 生成摘要，每条记忆携带 `路径:行号` 引用回源文件。
 - **代码符号记忆** — 通过零依赖的源码扫描器提取函数、类与方法名及完整类型签名（泛型、参数类型、返回类型、重载签名），包含字符串/注释掩码、多行签名续行、Python 缩进感知、类方法上下文，不使用 LLM token。
 - **L1 增强正则** — 零依赖正则扫描器现可提取泛型、参数/返回类型、重载、接口、类型别名，产出单行身份签名 `fn(a: A, b: B): R — file.ts:42`。
-- **可选 TypeScript 语义增强 (L2/L3)** — 当用户项目安装了 `typescript`（`npm i -D typescript`），插件自动激活第二层（L2），利用 TS Compiler API 推导返回类型、实例化泛型、提取接口与类型别名、丰富箭头函数签名 —— 全部在优先级队列中异步后台处理（P0：`fs/observed` 读文件瞬间、P1：`watch` 变更后、P2：`index_repo` 批量索引）。结果按文件内容哈希缓存到磁盘（L3），冷启动毫秒级复用。零配置：装 TS 再重启 dsh 即可。完全可选；若无 TS 或设置 `enableTypeScript: false`，回退至 L1 正则提取。
+- **可选 TypeScript 语义增强 (L2/L3)** — 当用户项目安装了 `typescript`（`npm i -D typescript@5` 或 `npm i -D typescript@6`），插件自动激活第二层（L2），利用 TS Compiler API 推导返回类型、实例化泛型、提取接口与类型别名、丰富箭头函数签名 —— 全部在优先级队列中异步后台处理（P0：`fs/observed` 读文件瞬间、P1：`watch` 变更后、P2：`index_repo` 批量索引）。结果按文件内容哈希缓存到磁盘（L3），冷启动毫秒级复用。零配置：装 TS 再重启 dsh 即可。完全可选；若无 TS 或设置 `enableTypeScript: false`，回退至 L1 正则提取。
 - **自动刷新** — `watch_repo` 后台轮询，按内容哈希识别新增或变更文件，仅重记这些文件。
 - **读到即记忆** — 文件在模型**实际读取的瞬间**被记忆（监听 `fs/observed`），记忆是正常工作的副产品，而非额外的一次全量扫描。从未读过的文件不会被记忆。项目根通过标记（`.git`、`package.json` 等）、README 加源码目录、或兜底到文件所在目录逐级识别。
 - **文档 ↔ 代码交叉链接** — 文档提及某符号时记录为 `reference`；查询符号时同时带出描述该符号的文档。
@@ -22,6 +22,7 @@
 - **经验笔记** — 记录问题 → 方案；相似问题覆盖而非重复；笔记仅在检索命中时返回。笔记数量有界：容量随项目规模伸缩（钳制在 100–2000），超限时淘汰最旧的笔记。**覆盖阈值收紧为双向 0.7 重叠**（原 0.6）；**经验 `problem` 字段现参与 CJK 短语加分**，提升长尾问句召回。
 - **流式 TF + IDF 缓存** — 查询路径按存储版本缓存 IDF（词逆频率）；命中时单次流式遍历 20k 条目仅需 ~8 ms（5k 文件） / ~1 ms（1k 文件），零中间对象；写入路径仅 O(1) 版本号递增。
 - **无锁同步事务** — 不采用锁：所有写入（index / watch / remember / forget / watch_repo）统一走同步事务 `store.commit(fn)`，fn 成功后才一次落盘；JS 单线程事件循环保证事务间不交错，`remember`/`forget` 不会被 watch 重索引阻塞排队。多实例并发写入同一项目存储时，得益于 CAS 幂等更新与原子提交，自然具备幂等性，无数据损坏风险。
+- **TaskBridge：跨会话开发任务** — 监听会话内宿主 `todo_write` 维护的任务清单与 `tool/call` 读文件：进度快照（steps）与触碰文件自动同步进跨会话的任务实体。未绑定会话写 todo 时自动建档。新会话通过 `list_tasks` → `select_task`（绑定/改名/解归档）续接；`query_memory` 新增 `type:'task'`，`type:'all'` 结果尾部附任务计数提示。用户侧 `/tasks` 命令展示任务栈、步骤进度、涉及文件与当前会话绑定。标题由模型经 `select_task(title=…)` 命名（回退：取消息最后一个「：」后的任务段）。容量随项目体积自适应（fileCount/20，clamp 5–100）。存储：`.dsh-project-memory/tasks.json` + `binding.json`。自动同步需含会话事件与 `todo_write` 的 dsh（0.1.2-alpha.x 实测）；旧宿主下降级为纯记录。
 - **依赖极简** — 纯 JavaScript；唯一运行时依赖是 `pdfjs-dist`（PDF 文本提取），无需原生构建。
 - **开销可忽略** — 纯进程内操作；冷启动 <100 ms（5k 文件），典型项目查询中位数 2–3 ms（p99 < 7 ms）；瓶颈在 LLM 摘要与 PDF 解析，插件本身不阻塞。
 
@@ -66,7 +67,7 @@
 
 ## 安装
 
-实测覆盖 dsh **0.1.0-rc.7 至 0.1.2-alpha.3**。插件仅依赖通过 peerDependencies 声明的稳定公共 API（`defineTool`、`llm.stream`、`Schema`），保证与后续 rc/alpha 版本无需改动即兼容。
+插件仅依赖通过 peerDependencies 声明的稳定公共 API（`defineTool`、`llm.stream`、`Schema`），保证与后续 rc/alpha 版本无需改动即兼容。
 
 ```bash
 cd dsh-project-memory && dsh plugin --profile web add . -w
@@ -99,6 +100,10 @@ dsh plugin --profile web add /path/to/dsh-project-memory.tgz
 | `watch_repo root` | 启用自动刷新：后台轮询检测新增/变更文件（mtime + 内容哈希），仅重抽这些文件。监听的项目在插件重启后自动恢复。 |
 | `memory_stats root` | 查看记忆库内容：总量（文件 / 条目 / 经验笔记）、最近索引时间，以及按时间排序的逐文件清单。 |
 | `query_memory query` | 对文档、符号、经验执行 BM25 检索，可选 LLM 查询扩展。返回带相对分数（0-100）、引用与文档→符号链接的排序结果。 |
+| `list_tasks` | 列出本项目任务记录（含归档，带标记）。新会话/续接前先调用。 |
+| `select_task` | 将会话绑定到某任务（此后 todo 清单与读文件同步进该任务）。按 `taskId` 精确绑定，或按 `title` 完全匹配（多个同名返回候选；无则新建）。带 title 可改名；自动解归档。 |
+| `archive_task` | 归档任务（隐藏默认视图、不占容量、停止同步）。`select_task` 可恢复。 |
+| `/tasks`（用户输入，不经模型） | 展示任务栈：标题、步骤进度、涉及文件、当前会话绑定哪套任务。 |
 | `remember problem solution` | 保存经验笔记。相似问题覆盖而非重复。 |
 | `forget id_or_query` | 删除过期经验笔记。 |
 
@@ -198,7 +203,7 @@ v0.2.0 之前创建的库（单文件 `entries.json` / `index.json`）在首次
 
 ### 11. TS 增强可选、异步、缓存
 
-**我们做：** L2 TS Compiler API 在优先级队列异步跑（P0 `fs/observed`、P1 `watch`、P2 `index_repo`），结果按内容哈希缓存 `type-cache/`。零配置——`npm i -D typescript` 即用。无 TS 或禁用时优雅回退 L1 正则。
+**我们做：** 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、阻塞式增强、全程序类型检查。
 
@@ -213,6 +218,7 @@ v0.2.0 之前创建的库（单文件 `entries.json` / `index.json`）在首次
 | `maxChunksPerFile` | 40 | 每文档最大块数 |
 | `maxFileSizeMb` | 50 | 大于该值（MB）的文档（含 PDF）/代码文件跳过 |
 | `maxOutputChars` | 8000 | `query_memory` 返回文本上限（字符） |
+| `tasklist.enabled` | true | 启用 TaskBridge 自动同步（由会话 todo 清单与文件读取沉淀任务实体） |
 | `maxPdfPages` | 1000 | 未另行限制时 PDF 的页数上限 |
 | `llmQueryExpansion` | false | BM25 检索前通过 `ctx.llm` 扩展查询（默认关闭，节省 token） |
 | `expansionCount` | 6 | 扩展变体上限 |
@@ -257,7 +263,7 @@ dsh web --patch ./config.yml
 
 ```bash
 npm install
-npm test          # 157 tests (v0.3.3)：chunker / symbols / store / tools / BM25 / links / watch / lazy / config / dump / concurrency / restore / size limit
+npm test          # 166 tests (v0.4.0) + TaskBridge 套件（node test/taskbridge.test.mjs，5 项）
 ```
 
 ## 许可证

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk_vat-y/dsh-project-memory",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "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",
@@ -30,7 +30,8 @@
   ],
   "license": "MIT",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "engines": {
     "node": ">=18"
@@ -50,7 +51,7 @@
     "@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",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {

package/src/commands/tasks.js

@@ -0,0 +1,54 @@
+// /tasks 用户命令：不经模型，直接展示本项目任务总览（非归档 + 归档计数 + 当前会话绑定）。
+import { memoryRootFor } from '../util/fs.js'
+import { ProjectMemoryStore } from '../store.js'
+import { projectRootFor } from '../setup/taskbridge.js'
+
+function timeAgo(iso) {
+  const diff = Date.now() - new Date(iso).getTime()
+  const m = Math.floor(diff / 60000)
+  if (m < 1) return '刚刚'
+  if (m < 60) return `${m}分钟前`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}小时前`
+  return `${Math.floor(h / 24)}天前`
+}
+
+export function tasksCommandDefinition(config) {
+  return {
+    name: 'tasks',
+    description: '查看本项目的任务清单（几套任务、进度、涉及文件、当前绑定）',
+    handler: (invocation) => {
+      try {
+        const cwd = invocation?.agent?.session?.header?.cwd
+        const root = projectRootFor(cwd)
+        const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+        const tasks = store.getTasks()
+        const active = tasks.filter((t) => !t.archived)
+        const archived = tasks.length - active.length
+        const sid = invocation?.agent?.session?.id
+        const boundId = sid ? store.getBoundTaskId(sid) : null
+        const bound = boundId ? tasks.find((t) => t.id === boundId) : null
+
+        if (!active.length) {
+          return { kind: 'success', text: `项目 ${root}\n任务记录: 0 套${archived ? `（归档 ${archived}）` : ''}。让模型开始干活并维护 todo 清单后会自动建档。` }
+        }
+        const lines = [`项目 ${root}`, `任务: ${active.length} 套${archived ? `（归档 ${archived}）` : ''}`, '']
+        for (const t of active) {
+          const done = (t.steps || []).filter((s) => s.status === 'completed').length
+          const total = (t.steps || []).length
+          const progress = total ? `${done}/${total}` : '无步骤'
+          const inProgress = (t.steps || []).find((s) => s.status === 'in_progress')
+          const step = inProgress ? ` · 当前: ${inProgress.content}` : ''
+          const marker = bound && bound.id === t.id ? '（本会话绑定）' : ''
+          const files = (t.files || []).slice(0, 8)
+          const fileLine = files.length ? `\n  文件: ${files.join(', ')}${t.files.length > 8 ? ' …' : ''}` : ''
+          lines.push(`● ${t.title}${marker}  步骤 ${progress}${step} · ${timeAgo(t.lastActiveAt || t.updatedAt)}${fileLine}`)
+        }
+        lines.push('', '续接/改名/归档：直接告诉模型（list_tasks / select_task / archive_task）。')
+        return { kind: 'success', text: lines.join('\n') }
+      } catch (err) {
+        return { kind: 'error', text: `[tasks] ${err?.message || err}` }
+      }
+    },
+  }
+}

package/src/enhancer.js

@@ -11,8 +11,8 @@ 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 获得增强类型。`)
+  if (mod && mod.version && mod.version.startsWith('7.')) {
+    console.warn(`[dsh-project-memory] TypeScript ${mod.version} 不受支持，回退到 L1 正则。请使用 TS 5.x/6.x 获得增强类型。`)
     return null
   }
   return mod

package/src/index.js

@@ -9,6 +9,9 @@ import { statsTool } from './tools/stats.js'
 import { WatchManager } from './watch.js'
 import { setupLazyIndexing } from './lazy.js'
 import { initTypeScript } from './enhancer.js'
+import { setupTaskbridge } from './setup/taskbridge.js'
+import { listTasksTool, selectTaskTool, archiveTaskTool } from './tools/task-tools.js'
+import { tasksCommandDefinition } from './commands/tasks.js'
 
 export const name = 'dsh-project-memory'
 export const inject = ['llm', 'tools']
@@ -28,6 +31,9 @@ export const Config = Schema.object({
   watchInterval: Schema.number().default(15),
   tsPath: Schema.string(),
   enableTypeScript: Schema.boolean().default(true),
+  tasklist: Schema.object({
+    enabled: Schema.boolean().default(true),
+  }).default({}),
 })
 
 export function apply(ctx, config) {
@@ -49,6 +55,21 @@ export function apply(ctx, config) {
     setupLazyIndexing(ctx, config, watchManager)
   }
 
+  // TaskBridge：任务实体 + 宿主 todo 同步
+  setupTaskbridge(ctx, config)
+  ctx.tools.register(listTasksTool(config))
+  ctx.tools.register(selectTaskTool(config))
+  ctx.tools.register(archiveTaskTool(config))
+
+  // /tasks 用户命令（宿主 commands 服务存在时注册，feature-detect 降级）
+  try {
+    ctx.inject(['commands'], (commandsCtx) => {
+      commandsCtx.commands.register(tasksCommandDefinition(config))
+    })
+  } catch (err) {
+    console.error(`[dsh-project-memory] /tasks registration skipped: ${err.message}`)
+  }
+
   ctx.tools.register(indexDocTool(ctx, config))
   ctx.tools.register(indexRepoTool(ctx, config))
   ctx.tools.register(queryMemoryTool(ctx, config))

package/src/setup/taskbridge.js

@@ -0,0 +1,169 @@
+// TaskBridge 运行时：监听会话事件，把宿主 todo/工具调用同步进任务实体。
+// 事实依据：dsh session/event 签名 (session, event)；todo/write data.todos；
+// tool/call data.arguments 为 JSON 字符串；fs 工具名 read/write/edit/read_image，参数 file_path。
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { memoryRootFor } from '../util/fs.js'
+import { findProjectRoot } from '../lazy.js'
+import { ProjectMemoryStore } from '../store.js'
+
+const FS_FILE_TOOLS = new Set(['read', 'write', 'edit', 'read_image'])
+const MAX_FILES_PER_TASK = 100
+const TITLE_MAX = 24
+
+export function hash8(text) {
+  return createHash('sha256').update(String(text)).digest('hex').slice(0, 8)
+}
+
+export function slugifyTitle(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^\w\u4e00-\u9fff]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, TITLE_MAX)
+}
+
+export function genTaskId(projectRoot, title) {
+  const slug = slugifyTitle(title) || 'task'
+  return `tsk_${hash8(projectRoot)}_${slug}_${Date.now()}`
+}
+
+/** 项目根推导：findProjectRoot 期望文件路径，传目录会从父级起跳，故用目录内探针路径。 */
+export function projectRootFor(cwd) {
+  const base = cwd || process.cwd()
+  return findProjectRoot(path.join(base, '__taskbridge__.probe'))
+}
+
+export function taskStoreFor(cwd, config) {
+  const root = projectRootFor(cwd)
+  return { root, store: new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load() }
+}
+
+/** 把工具参数里的文件路径归一化为项目相对路径；项目外返回 null。 */
+export function normalizeRelFile(root, file) {
+  if (typeof file !== 'string' || !file) return null
+  const abs = path.isAbsolute(file) ? file : path.resolve(root, file)
+  const rel = path.relative(root, abs)
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null
+  return rel.split(path.sep).join('/')
+}
+
+/** content 可能是字符串或 ContentBlock[]，统一取首段文本。 */
+export function firstTextOf(content) {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    for (const b of content) {
+      if (b && typeof b.text === 'string' && b.text.trim()) return b.text
+    }
+  }
+  return ''
+}
+
+function pickTitle(meta, todos) {
+  const firstHuman = meta?.firstHuman?.trim()
+  if (firstHuman) {
+    // 用户消息常带指令前缀（"用 todo_write 规划：…"），优先取最后一个"："后的任务段
+    const idx = Math.max(firstHuman.lastIndexOf('：'), firstHuman.lastIndexOf(':'))
+    const seg = idx >= 0 ? firstHuman.slice(idx + 1).trim() : ''
+    if (seg.length >= 2 && seg.length <= 48) return seg
+    return firstHuman.slice(0, 48)
+  }
+  const firstTodo = todos?.[0]?.content
+  if (firstTodo && firstTodo.trim()) return firstTodo.trim().slice(0, 48)
+  return 'Untitled Task'
+}
+
+/**
+ * 单条会话事件处理（导出便于测试）：user/message 记首条真人文本；
+ * todo/write → 已绑定则覆盖 steps，未绑定则自动新建任务并绑定；
+ * tool/call（fs 工具）→ 绑定任务 files 并集。
+ */
+export function onSessionEvent(config, session, event, meta) {
+  const sessionId = session?.id
+  const type = event?.type
+  if (!sessionId || !type) return
+
+  if (type === 'user/message') {
+    if (!meta.has(sessionId) && event.data?.source?.kind === 'user') {
+      const text = firstTextOf(event.data?.content)
+      if (text) meta.set(sessionId, { firstHuman: text })
+    }
+    return
+  }
+
+  const { root, store } = taskStoreFor(session?.header?.cwd, config)
+  const now = new Date().toISOString()
+
+  if (type === 'todo/write') {
+    const todos = event.data?.todos
+    if (!Array.isArray(todos)) return
+    store.commit((s) => {
+      let task = s.getBoundTaskId(sessionId) ? s.getTask(s.getBoundTaskId(sessionId)) : null
+      if (!task || task.archived) {
+        const title = pickTitle(meta.get(sessionId), todos)
+        task = {
+          id: genTaskId(root, title),
+          projectHash: hash8(root),
+          projectRoot: root,
+          title,
+          steps: null,
+          files: [],
+          archived: false,
+          lastSessionId: sessionId,
+          createdAt: now,
+          updatedAt: now,
+          lastActiveAt: now,
+        }
+        s.addTask(task)
+        s.setBinding(sessionId, task.id)
+      }
+      task.steps = todos
+      task.updatedAt = now
+      task.lastActiveAt = now
+      task.lastSessionId = sessionId
+      s._dirtyTasks = true
+    })
+    return
+  }
+
+  if (type === 'tool/call') {
+    const taskId = store.getBoundTaskId(sessionId)
+    if (!taskId) return
+    const data = event.data
+    if (!data?.name || !FS_FILE_TOOLS.has(data.name)) return
+    let args
+    try {
+      args = typeof data.arguments === 'string' ? JSON.parse(data.arguments) : data.arguments
+    } catch {
+      return
+    }
+    const raw = typeof args?.file_path === 'string' ? args.file_path : null
+    if (!raw) return
+    const rel = normalizeRelFile(root, raw)
+    if (!rel) return
+    store.commit((s) => {
+      const task = s.getTask(taskId)
+      if (!task || task.archived) return
+      if (!task.files.includes(rel)) {
+        task.files.push(rel)
+        if (task.files.length > MAX_FILES_PER_TASK) task.files.shift()
+      }
+      task.lastActiveAt = now
+      s._dirtyTasks = true
+    })
+  }
+}
+
+/** 插件接线：订阅 session/event；卸载时清会话元数据。 */
+export function setupTaskbridge(ctx, config) {
+  if (config.tasklist?.enabled === false) return
+  const meta = new Map()
+  ctx.on('session/event', (session, event) => {
+    try {
+      onSessionEvent(config, session, event, meta)
+    } catch (err) {
+      console.error('[dsh-project-memory] taskbridge:', err?.message)
+    }
+  })
+  ctx.effect(() => () => meta.clear())
+}

package/src/store.js

@@ -7,6 +7,8 @@ const FORMAT_FILE = 'format.json'
 const INDEX_FILE = 'index.json'
 const ENTRIES_FILE = 'entries.json'
 const EXPERIENCE_FILE = 'experience.json'
+const TASKS_FILE = 'tasks.json'
+const BINDING_FILE = 'binding.json'
 const WATCH_FILE = 'watch.json'
 const SHARDS_DIR = 'shards'
 
@@ -58,10 +60,14 @@ export class ProjectMemoryStore {
     this.files = {}
     this.entries = {}
     this.experience = []
+    this.tasks = []
+    this.binding = {}
     this.watchlist = []
     this._dirtyShards = new Set()
     this._removedShards = new Set()
     this._dirtyExperience = false
+    this._dirtyTasks = false
+    this._dirtyBinding = false
     this._dirtyWatch = false
     this._formatWritten = false
     this._version = 0
@@ -134,6 +140,8 @@ export class ProjectMemoryStore {
       this.entries[shard.relPath] = shard.entries || []
     }
     this.experience = loadJson(path.join(this.dir, EXPERIENCE_FILE), [])
+    this.tasks = loadJson(path.join(this.dir, TASKS_FILE), [])
+    this.binding = loadJson(path.join(this.dir, BINDING_FILE), {})
     this.watchlist = loadJson(path.join(this.dir, WATCH_FILE), [])
     this._formatWritten = existsSafe(path.join(this.dir, FORMAT_FILE))
   }
@@ -187,6 +195,14 @@ export class ProjectMemoryStore {
       writeJsonAtomic(path.join(this.dir, EXPERIENCE_FILE), this.experience)
       this._dirtyExperience = false
     }
+    if (this._dirtyTasks) {
+      writeJsonAtomic(path.join(this.dir, TASKS_FILE), this.tasks)
+      this._dirtyTasks = false
+    }
+    if (this._dirtyBinding) {
+      writeJsonAtomic(path.join(this.dir, BINDING_FILE), this.binding)
+      this._dirtyBinding = false
+    }
     if (this._dirtyWatch) {
       writeJsonAtomic(path.join(this.dir, WATCH_FILE), this.watchlist)
       this._dirtyWatch = false
@@ -355,11 +371,83 @@ export class ProjectMemoryStore {
       files: Object.keys(this.files).length,
       entries: this.allEntries().length,
       experience: this.experience.length,
+      tasks: this.tasks.length,
+      tasksActive: this.tasks.filter((t) => !t.archived).length,
+      tasksArchived: this.tasks.filter((t) => t.archived).length,
+    }
+  }
+
+  // ---- TaskBridge: task entities + per-session binding ----
+
+  getTasks() {
+    return this.tasks
+  }
+
+  getTask(id) {
+    return this.tasks.find((t) => t.id === id)
+  }
+
+  addTask(task) {
+    this.tasks.push(task)
+    this._dirtyTasks = true
+  }
+
+  updateTask(id, updates) {
+    const task = this.tasks.find((t) => t.id === id)
+    if (!task) return false
+    Object.assign(task, updates, { updatedAt: new Date().toISOString() })
+    this._dirtyTasks = true
+    return true
+  }
+
+  removeTask(id) {
+    const idx = this.tasks.findIndex((t) => t.id === id)
+    if (idx === -1) return false
+    this.tasks.splice(idx, 1)
+    for (const sid of Object.keys(this.binding)) {
+      if (this.binding[sid] === id) delete this.binding[sid]
+    }
+    this._dirtyTasks = true
+    this._dirtyBinding = true
+    return true
+  }
+
+  setBinding(sessionId, taskId) {
+    if (!sessionId) return
+    this.binding[sessionId] = taskId
+    this._dirtyBinding = true
+  }
+
+  getBoundTaskId(sessionId) {
+    return sessionId ? this.binding[sessionId] : undefined
+  }
+
+  removeBinding(sessionId) {
+    if (sessionId && sessionId in this.binding) {
+      delete this.binding[sessionId]
+      this._dirtyBinding = true
+    }
+  }
+
+  /** 每项目任务数上限随项目体积自适应；超限按 lastActiveAt 归档最旧（只统计非归档）。 */
+  pruneTasks() {
+    const fileCount = Object.keys(this.files).length
+    const maxTasks = Math.min(100, Math.max(5, Math.floor(fileCount / 20)))
+    const nonArchived = this.tasks.filter((t) => !t.archived)
+    if (nonArchived.length <= maxTasks) return 0
+    const ts = (t) => new Date(t.lastActiveAt || t.updatedAt || t.createdAt || 0).getTime()
+    const sorted = [...nonArchived].sort((a, b) => ts(a) - ts(b))
+    const toArchive = sorted.slice(0, nonArchived.length - maxTasks)
+    for (const task of toArchive) {
+      task.archived = true
+      this._dirtyTasks = true
     }
+    return toArchive.length
   }
 
   commit(fn) {
     const result = fn(this)
+    this.pruneTasks()
     this.save()
     return result
   }

package/src/tools/query-memory.js

@@ -30,8 +30,8 @@ export function queryMemoryTool(ctx, config) {
       },
       type: {
         type: 'string',
-        enum: ['all', 'doc', 'symbol', 'experience'],
-        description: 'Which memory layer to search. Default "all".',
+        enum: ['all', 'doc', 'symbol', 'experience', 'task'],
+        description: 'Which memory layer to search. Default "all". "task" searches task records (title/steps/files).',
       },
       limit: {
         type: 'number',
@@ -102,6 +102,31 @@ export function queryMemoryTool(ctx, config) {
         }
       }
 
+      // TaskBridge: type:'task' 专门查任务记录；type:'all' 尾部附一行任务计数提示
+      const tasks = store.tasks || []
+      if (type === 'task') {
+        const q = (queries[0] || '').toLowerCase()
+        const matched = tasks
+          .filter((t) => !t.archived && (t.title.toLowerCase().includes(q) || (t.steps || []).some((s) => s.text?.toLowerCase().includes(q)) || (t.files || []).some((f) => f.toLowerCase().includes(q))))
+          .slice(0, limit)
+        if (!matched.length) {
+          return `任务记录: 0 套匹配 "${args.query}"（list_tasks 查看全部，select_task 续做）`
+        }
+        for (const t of matched) {
+          const done = (t.steps || []).filter((s) => s.status === 'completed').length
+          const total = (t.steps || []).length
+          const stepsText = (t.steps || []).length
+            ? (t.steps || []).map((s) => `- [${s.status === 'completed' ? 'x' : s.status === 'in_progress' ? '*' : ' '}] ${s.text}`).join('\n')
+            : '（无步骤）'
+          const files = (t.files || []).slice(0, 8).join(', ')
+          lines.push(`### ${t.title} (${done}/${total} 完成)\n${stepsText}\n- 文件: ${files || '无'}`)
+        }
+        return truncate(lines.join('\n\n'), config.maxOutputChars)
+      }
+      if (type === 'all' && tasks.length) {
+        lines.push(`任务记录: ${tasks.length} 套（list_tasks 查看，select_task 续做）`)
+      }
+
       if (!lines.length) {
         const overview = storeOverview(store)
         const hint =

package/src/tools/task-tools.js

@@ -0,0 +1,164 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { ProjectMemoryStore } from '../store.js'
+import { truncate } from '../util/text.js'
+import { genTaskId, hash8 } from '../setup/taskbridge.js'
+import { createHash } from 'node:crypto'
+
+function sessionIdOf(exec) {
+  return exec?.agent?.session?.id || exec?.ctx?.session?.id
+}
+
+function timeAgo(iso) {
+  const diff = Date.now() - new Date(iso).getTime()
+  const m = Math.floor(diff / 60000)
+  if (m < 1) return '刚刚'
+  if (m < 60) return `${m}分钟前`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}小时前`
+  return `${Math.floor(h / 24)}天前`
+}
+
+function summaryOf(task) {
+  const done = (task.steps || []).filter((s) => s.status === 'completed').length
+  const total = (task.steps || []).length
+  const files = (task.files || []).length
+  const mark = task.archived ? ' [归档]' : ''
+  return `### ${task.title}${mark}\n- 进度: ${done}/${total} 完成\n- 文件: ${files} 个\n- 最后活动: ${timeAgo(task.lastActiveAt || task.updatedAt)}`
+}
+
+export function listTasksTool(config) {
+  return defineTool({
+    name: 'list_tasks',
+    description:
+      'List all task records in this project (archived included, marked). Call this first in a new session or before continuing work, to see what tasks exist and pick one with select_task.',
+    parameters: {
+      root: { type: 'string', description: 'Project root. Defaults to current working directory.' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+      const tasks = store.getTasks()
+      if (!tasks.length) {
+        return '任务记录: 0 套（先做一步再建清单，或用 select_task 新建）'
+      }
+      const lines = ['## 任务记录']
+      for (const task of tasks) lines.push(summaryOf(task))
+      lines.push(`\n任务记录: ${tasks.length} 套（list_tasks 查看，select_task 续做/切换）`)
+      return truncate(lines.join('\n\n'), config.maxOutputChars)
+    },
+  })
+}
+
+export function selectTaskTool(config) {
+  return defineTool({
+    name: 'select_task',
+    description:
+      'Bind the current session to a task record so its todo list and read files sync into it. When starting NEW work, call select_task(title="任务名") FIRST, then maintain your plan with todo_write — you choose the task title (short, no need to restate the user message). taskId: exact id from list_tasks (auto-unarchives; pass title too to rename). title: exact match only; multiple matches return candidates; no match creates a new task. Returns a task card (title, steps, files) to rebuild the session todo from. Call list_tasks first in a new session.',
+    parameters: {
+      taskId: { type: 'string', description: 'Exact task id, e.g. tsk_ab12cd34_...' },
+      title: { type: 'string', description: 'Exact task title; creates a new task when absent' },
+      root: { type: 'string', description: 'Project root. Defaults to current working directory.' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+      const sid = sessionIdOf(exec)
+      const now = new Date().toISOString()
+      const error = (msg) => truncate(JSON.stringify({ success: false, error: msg }), config.maxOutputChars)
+
+      if (!args.taskId && !args.title) {
+        return error('需要 taskId 或 title（先 list_tasks；未绑定会话出现 todo 时会自动新建任务）')
+      }
+
+      let task = null
+      let hint = ''
+      if (args.taskId) {
+        task = store.getTask(args.taskId)
+        if (!task) return error(`Task not found: ${args.taskId}`)
+        if (task.archived) {
+          task.archived = false
+          hint = '已解归档'
+        }
+        if (args.title && args.title !== task.title) {
+          task.title = args.title // 改名（自动标题可能带指令前缀，续接时可顺手改干净）
+          hint = (hint ? hint + '；' : '') + `已改名「${args.title}」`
+        }
+      } else {
+        const matches = store.getTasks().filter((t) => t.title === args.title)
+        if (matches.length > 1) {
+          const candidates = matches.map((t) => ({ taskId: t.id, title: t.title, updatedAt: t.updatedAt, archived: t.archived }))
+          return truncate(JSON.stringify({ success: false, error: '多个同名任务', candidates }), config.maxOutputChars)
+        }
+        if (matches.length === 1) {
+          task = matches[0]
+          if (task.archived) {
+            task.archived = false
+            hint = '已解归档'
+          }
+        } else {
+          task = {
+            id: genTaskId(root, args.title),
+            projectHash: hash8(root),
+            projectRoot: root,
+            title: args.title,
+            steps: null,
+            files: [],
+            archived: false,
+            lastSessionId: sid,
+            createdAt: now,
+            updatedAt: now,
+            lastActiveAt: now,
+          }
+          store.addTask(task)
+          hint = '已新建任务'
+        }
+      }
+
+      if (sid) {
+        store.setBinding(sid, task.id)
+        hint = (hint ? hint + '；' : '') + '已绑定本会话'
+      } else {
+        hint = (hint ? hint + '；' : '') + '（拿不到会话 id，未能持久绑定）'
+      }
+      task.updatedAt = now
+      task.lastActiveAt = now
+      if (sid) task.lastSessionId = sid
+      store.save()
+
+      const card = {
+        taskId: task.id,
+        title: task.title,
+        steps: task.steps,
+        files: task.files,
+        hint: hint + '；请据此用 todo_write 重建本会话清单',
+      }
+      return truncate(JSON.stringify(card), config.maxOutputChars)
+    },
+  })
+}
+
+export function archiveTaskTool(config) {
+  return defineTool({
+    name: 'archive_task',
+    description: 'Archive a task: hide from default views, exclude from capacity, stop syncing. Restore by selecting it again.',
+    parameters: {
+      taskId: { type: 'string', required: true, description: 'Task id to archive (from list_tasks / select_task)' },
+      root: { type: 'string', description: 'Project root. Defaults to current working directory.' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+      const task = store.getTask(args.taskId)
+      if (!task) return truncate(JSON.stringify({ success: false, error: 'Task not found' }), config.maxOutputChars)
+      if (task.archived) return truncate(JSON.stringify({ success: false, error: 'Already archived' }), config.maxOutputChars)
+      task.archived = true
+      task.updatedAt = new Date().toISOString()
+      store.save()
+      return truncate(JSON.stringify({ success: true, archived: true, hint: '已归档，select_task 可恢复' }), config.maxOutputChars)
+    },
+  })
+}