dsh-tracepoint 0.0.0-stage → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# 版本历史 · dsh-tracepoint（痕迹）
+
+本文件记录每个版本的实际改动。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.6.1] - 2026-11-14
+
+### 修复
+- **"写之前自动拍点"在 DSH 0.2.2 真宿主上不触发**：0.6.0 只从 `exec.agent.cwd` 取工作区根，而 DSH 0.2.2 的 Agent 没有 `cwd` 字段（根在 `agent.session.header.cwd`），导致自动拍点每次都在"根拿不到"处静默跳过，第一笔改动照样退不回去。现在两个字段都认，旧宿主兼容保留。
+- 自动拍点测试补"真宿主形状"用例（`agent` 只有 `session.header.cwd`），并改为有通过/失败计数、失败时退出码非 0。
+
+### 验证
+- 实机复验通过：改一个没手动拍过的文件 → 自动拍点生效、写完不再提醒、`restore` 成功退回。
+- 全套 8 个测试文件 147 项通过（autosave 由 9 项增至 17 项）。
+
+### 发布
+- **对外包名由 `dsh-trace` 改为 `dsh-tracepoint`**：npm 防混淆策略拒绝注册 `dsh-trace`（与 Datadog 的 `dd-trace` 过于相近）；候选名 `dsh-tracer` 又已被他人占用。最终选用空闲的无作用域名 `dsh-tracepoint`，安装时可直接 `npm install dsh-tracepoint`，无需账号前缀。
+- 内部标识保持不变：数据目录仍为 `~/.dsh/dsh-trace/`、工具名仍为 `trace_anchor` / `trace_attempt`、提示词段名仍为 `dsh-trace:remind`——既有快照与配置不受改名影响。
+- 补全 npm 元数据（repository / homepage / bugs / keywords），新增本版本历史文档。
+
+## [0.6.0] - 2026-11-14
+
+### 新增
+- **第零层兜底：写之前自动拍点**。`write` / `edit` / `str_replace` 等写文件工具真正执行前，若目标文件还没进过任何快照，自动拍一张（paths 模式，毫秒级），第一笔改动也退得回去。通过宿主 `tools/pre-execute` 钩子实现。
+- 只拍"还没拍过的、真实存在的、≤50MB 的普通文件"；新文件、工作区外、超大、根拿不到都静默跳过，交给写后提醒兜底。不拦调用、不改结果、失败不抛。
+- 配置 `{"autoSave": false}` 可单独关闭第零层（与 `remind` 独立）。
+
+### 变更
+- 第一层提示词从"改文件前先拍个点"改为"写文件会自动拍点，想留明确检查点再手动 save"。
+
+## [0.5.4] - 2026-11-14
+
+### 修复（第二轮外部工程评审，3 处 P1）
+- `restore` 以前只查词法路径，目录联接能把文件写到工作区外。现在取真实路径核对（`realPathOf` / `realInside`），写临时文件前再查一次。
+- `save({paths})` 以前用 `stat` 会顺着符号链接；改用 `lstat` 拒绝链接，并核对真实路径仍在工作区内。
+- 锁 5 分钟 TTL 小于 GC 实测耗时（约 7 分钟），且 GC 是同步长循环、心跳插不进去。现在锁加随机 token（只删自己的锁）＋心跳，GC 每个前缀目录／每 1024 个块手动刷锁。
+
+### 变更
+- dry-run 的"零写入"不再把"拒绝"误报成"本来就一致"，单列 `refused` / `failed` 并给出原因。
+
+### 新增
+- `test-boundary.mjs` 13 项（目录联接写不出去／链接不拍／活锁不许抢／死锁能接管）。
+
+## [0.5.3] - 2026-11-14
+
+### 修复（外部评审后）
+- paths 模式不再全盘 `sweepTmp`（与"只 stat 点名文件"的承诺一致）。
+- `gc` / `forget` 与 `save` 共用一把锁，避免回收和进行中的快照抢块。
+
+## [0.5.2] - 2026-11-14
+
+### 新增
+- `restore({id, paths:[...]})` 只退点名的文件（以前整份快照一起退）。没拍到的文件直说退不了，不假装成功；保护快照也只拍这几个；确认了但没东西可退时不拍空快照。
+
+### 背景
+- 真实使用场景：只想退项目卡、保留改好的 README，结果整份快照一起退，README 被迫重改。
+
+### 新增测试
+- `test-restore-paths.mjs` 23 项。
+
+## [0.5.1] - 2026-11-13
+
+### 修复（真机撞出来的）
+- 保护快照以前拍**整个工作区**；工作区里只要有超过 50MB 的文件被跳过（如视频），快照就永远算"不完整"，**一次还原都退不了**。现在保护快照只拍"这次要退的那几个文件"。
+
+### 新增测试
+- `test-restore-cover.mjs` 9 项回归。
+
+## [0.5.0] - 2026-11-13
+
+### 新增
+- **第一层兜底：系统提示词里一句**。用 `ctx.systemPrompt.section()` 注册，位置在 `write` 工具说明前一条（order 1199）。没有提示词口的环境自动跳过。
+
+## [0.4.0] - 2026-11-13
+
+### 新增
+- **第二层兜底：写完之后补一句**。写文件类工具跑完，若文件不在拍过的点里，在结果末尾追加「［痕迹］…」提醒。只追加文字，不拦调用、不改结果。每场最多 3 次、两次间隔至少 2 次写；`{"remind": false}` 可关。
+
+## [0.3.0] - 2026-11-13
+
+### 新增
+- `save({paths:[...]})` 只拍点名的那几个文件（毫秒级）；`restore` 也只退这几个。
+- 局部快照的 `diff` 不再把"没记录的文件"误报成新增。
+
+### 性能
+- 真实工作区 6981 文件下，局部快照 24ms（全量约 19.2 秒）。
+
+## [0.2.0] - 2026-11-13
+
+### 新增
+- `diff` 给内容差异（`+n/-n` ＋改动那几行的前后文），不只是文件名。
+- `forget` / `gc`：按名字删一个点、回收没人引用的块（都不自动）。
+- 并发锁：两个 save / restore 同时跑会被挡住。
+- Windows 长路径（>260 字符）自动走 `\\?\` 前缀。
+- 增量索引（size + mtime 命中就不重读）：364MB 工作区第二次拍照从 20 秒降到约 1 秒。
+
+### 修复
+- `forget` 的 O(n²) 引用查询改为一次性收集引用集合。
+- `gc` 逐个删块改为整前缀目录批量删。
+
+## [0.1.0] - 2026-11-13
+
+### 新增
+- 首个版本。`trace_anchor`（save / list / diff / restore）与 `trace_attempt`（log / recall）。
+- 内容寻址存块＋每份快照一张清单＋写入走"临时文件→校验→rename"。
+- 三条底线：不自动删快照、不整目录覆盖、原子写入。
+
+[0.6.1]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.6.0]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.5.4]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.5.3]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.5.2]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.5.1]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.5.0]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.4.0]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.3.0]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.2.0]: https://github.com/RainSnowYY/dsh-tracepoint
+[0.1.0]: https://github.com/RainSnowYY/dsh-tracepoint

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RainSnowYY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,228 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/icon.png" width="96" alt="dsh-tracepoint 图标" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">dsh-tracepoint · 痕迹</h1>
+
+<p align="center">
+  <b>动手前拍一个点，改坏了能退回去。退回本身也能退回。</b>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-tracepoint"><img src="https://img.shields.io/npm/v/dsh-tracepoint.svg" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" /></a>
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="zero dependencies" />
+  <img src="https://img.shields.io/badge/DSH-0.2.2--rc.1-orange.svg" alt="DSH compatibility" />
+</p>
+
+> **这是什么**：一个给 [DeepSeek Harness（DSH）](https://github.com/RainSnowYY/dsh-second-review) 用的本地插件。AI 助手改你的文件之前，先给文件拍一张"快照"；改坏了，一条命令退回去——连"退回"这个动作本身也能再退回来。它不给你新本事，它把"不敢动手"这件事摁住。
+
+---
+
+## 为什么需要它
+
+让 AI 助手改代码、改文档，最担心的不是它改得慢，是它**改坏了还退不回去**：
+
+- 模型想不起来"先备份"，第一笔改动就没了旧样子；
+- 就算备份了，整目录覆盖式的回滚会把你后来新写的东西一起冲掉；
+- 回滚到一半进程被杀，留下半个文件，比不回滚还糟。
+
+痕迹把这三件事一次性解决：**写之前自动拍点、退回只碰记录过的文件、写入全程原子化**。装上就生效，不需要你记得用它。
+
+## 三层兜底：装了就一定生效
+
+模型"想不起来拍点"是这类工具最大的失效方式。所以痕迹不靠自觉，靠三层兜底，**都不拦调用、不改结果**：
+
+**第零层 · 写之前自动拍点（v0.6 起，真正的兜底）**
+`write` / `edit` / `str_replace` 等写文件工具**真正执行前**，如果这个文件还没进过任何快照，就自动拍一张（只拍这一个文件，毫秒级）。哪怕模型一次都没想起来，**第一笔改动也退得回去**。
+只自动拍"还没拍过的、真实存在的、≤50MB 的普通文件"；新文件（没有旧样子可存）、工作区外的文件、超大文件不拍。拍不成就静默跳过，交给第二层提醒。
+
+**第一层 · 系统提示词里一句（v0.5 起）**
+写在 `write` 工具说明的前一条，模型动手之前就读得到：
+
+> 写文件前会自动拍点，改坏了能 restore；想留个明确的检查点就手动 trace_anchor save({root, paths:["要改的文件"]})。
+
+**第二层 · 写完之后补一句（v0.4 起）**
+万一自动拍点没拍成，写文件工具跑完后，结果末尾会补一句「［痕迹］…」提醒这次改动退不回去。每场会话最多提醒 **3 次**，两次之间至少隔 2 次写——宁可漏，不要吵。
+
+**怎么关**（`~/.dsh/dsh-trace/config.json`）：
+
+| 配置 | 关什么 |
+|-|-|
+| `{"autoSave": false}` | 关掉"写之前自动拍点"（第零层）。写完那层提醒还在 |
+| `{"remind": false}` | 关掉第一、二层提醒（提示词 + 写完补一句） |
+| 两个都 `false` | 三层全关，回到纯手动 |
+
+`autoSave` 下次调用即生效；`remind` 的第二层下次调用即生效、**第一层要重开 DSH 才消失**（提示词是启动时注册的）。
+
+---
+
+## 两个工具
+
+### `trace_anchor` —— 快照与退回
+
+| 动作 | 干什么 |
+|-|-|
+| `save` | 拍一个点。写文件之前调一次 |
+| `save({paths:[...]})` | **只拍点名的那几个文件**：改两个文件就只存两个，毫秒级；`restore` 也只退这几个 |
+| `list` | 看拍过哪些点 |
+| `diff` | 看某个点到现在改了什么——**给的是内容差异**（`+n/-n` 和改动那几行的前后文），不只是文件名 |
+| `restore` | 退回去。**第一次不带 `confirm` 只给清单，第二次带 `confirm:true` 才真写** |
+| `restore({id, paths:[...]})` | 只退点名的文件（必须是那个点里拍过的）；没拍到的直说退不了，不假装成功 |
+| `forget` | 删掉某一个点（要 `confirm`）。只动插件自己的存档，不动你工作区 |
+| `gc` | 回收没有任何点引用的存储块。先带 `compact:true` 可以只算不删 |
+
+### `trace_attempt` —— 尝试簿
+
+| 动作 | 干什么 |
+|-|-|
+| `log` | 记一条失败：做了什么、报错原文、判断的原因、什么条件下值得再试 |
+| `recall` | 按文件路径捞历史失败记录。**只回记录，不拦你** |
+
+第一版故意没有"自动判定是不是同一个坑"——判错一次，人就再也不信它了。
+
+---
+
+## 三条底线（写死在代码里，不是设置项）
+
+1. **不自动删任何快照。** 存储到 500MB 上限就拒绝新快照，让你自己 `forget`。
+2. **不整目录覆盖。** `restore` 只碰那份快照记过的文件，**不删你新增的**，也不碰快照之外的东西。
+3. **写文件一律"临时文件 → 校验 → rename"。** 中途被杀也不会留半个文件。
+
+还有四道闸：
+
+- `restore` 前自动拍一张"回滚前的现场"，**这张拍不成，整个 restore 拒绝执行**；
+- 目标文件正在被改（写临时文件前后 stat 不一致）→ 这个文件**拒写**并告诉你；
+- 存储超上限 → 拒绝执行；
+- 同一时刻只允许一个 save / 一个 restore（锁文件 + 心跳，长时间回收也不会被误判死锁）。
+
+---
+
+## 有多快（实测，不是估算）
+
+测试环境：Windows 11，工作区 **6984 个文件 / 364 MB**。
+
+| 场景 | 耗时 |
+|-|-|
+| 第一次拍（要读全量并落盘，约 205MB） | **20~30 秒** |
+| 之后每次拍（靠增量索引，只 stat 不重读） | **约 1 秒** |
+| **`save({paths:[1 个文件]})`** | **24 毫秒**（同一台机器、6981 文件的工作区） |
+| restore 一个 12MB 的文件 | 50 ms |
+| 真 SIGKILL 打断 restore（300 文件 / 60MB） | **0 个半写文件**，300/300 能用保护快照复活 |
+
+**为什么 paths 快**：它不遍历目录、不看索引——只 stat 你点名的那几个文件，读它们的字节落块。改 2 个文件就只付 2 个文件的钱。
+
+**代价（写明白）**：
+- `paths` 拍出来的点**只含那几个文件**，`restore` 也只退那几个——没点名的文件一个都不碰。这是有意的：最坏情况也不扩大作用面。
+- 增量索引只靠 `size + mtime` 判断"没变过"。如果某个文件被改过、但大小和修改时间都没变（极少见），那次改动不会被发现。换来的是 20 秒 → 1 秒。
+- **gc 会慢**：Windows 上删文件要过杀软，实测 3000 个块约 60 秒、200MB 约 7 分钟。所以它不自动跑，且支持 `compact:true` 先预演。
+
+---
+
+## 什么算"退得准"
+
+**承诺恢复**：文件内容（字节级）、空目录、权限位（尽力）、mtime（尽力）。
+
+**不承诺**：ACL、所有者、扩展属性、硬链接、符号链接（遇到直接报错，不静默跳过）。
+
+`node_modules`、`.git`、`.obsidian`、`备份`、超过 50MB 的单文件默认不进快照。遇到这些，快照会标成 `incomplete` 并当场告诉你——**不包装成完整快照**。
+
+Windows 长路径（>248 字符）自动加 `\\?\` 前缀，实测 282 字符的路径能拍能退。
+
+---
+
+## 安装
+
+> 兼容性：在 **DSH 0.2.2-rc.1** 上验证通过，其余版本未测。
+> 三种方式任选其一，装完都要**托盘退出 DSH 再开一次**（`Ctrl+R` 不管用）。
+
+### 方式一 · npm（发布后推荐）
+
+在 DSH 的 profile 目录（`~/.dsh/profiles/desktop`）里：
+
+```bash
+npm install dsh-tracepoint
+```
+
+然后在 profile 的 `package.json` 的 `dsh.profile.bundles` 数组里加一行 `"dsh-tracepoint"`，重开 DSH。
+
+### 方式二 · tgz 离线包
+
+适合不想配 npm、直接拿发布包的人：
+
+```
+DSH → 插件页 → 添加插件 → 粘 tgz 的绝对路径，例如：
+C:\path\to\dsh-tracepoint-0.6.1.tgz
+→ 安装 → 启用 → 托盘退出再开
+```
+
+### 方式三 · 源码目录
+
+适合 clone 了仓库、想改代码的人：
+
+```
+DSH → 插件页 → 添加插件 → 粘这一行（换成你机器上的实际路径）：
+file:C:\path\to\dsh-tracepoint
+→ 安装 → 启用 → 托盘退出再开
+```
+
+`file:` 后面必须是**绝对路径**，指向含 `package.json` 的那个目录。
+
+### 装完看什么
+
+不会多出标签页、不会多出按钮——它只给模型两个工具，外加自动拍点和提醒。想验证：让模型改一个小文件，然后 `trace_anchor list`，应该能看到一张自动快照。
+
+### 数据在哪
+
+全部在本地 `~/.dsh/dsh-trace/`，**不联网、不调任何模型 API**：
+
+```
+blobs/           按内容哈希存的块，同一份内容只存一次
+manifests/       每份快照一个 json
+index.json       增量索引（约 1.8MB / 7000 文件），删了只是下一次变慢
+attempts.jsonl   尝试簿，留 90 天
+config.json      你的开关（可选，没有就用默认）
+```
+
+想清空就整个目录删掉，插件不会因此坏（下次自己重建）。
+
+---
+
+## 已知限制
+
+- 符号链接不支持（Windows 建链接要管理员权限）；目录联接/符号链接指向工作区外时，写入会被拒绝。
+- 并发写只是"尽力检测"，不是强一致快照。
+- 单文件超 50MB 跳过。
+- 存的是磁盘真实占用，"不计配额"的保护快照也占盘。
+- `gc` 慢（见上），别在等它的时候重复调。
+- 自动拍点依赖宿主给的工作区根（`agent.cwd`，DSH 0.2.2 上在 `agent.session.header.cwd`）：拿不到就静默跳过，交给写完那层提醒。
+- 自动拍点会让快照变多（每写一个没拍过的文件就多一张），但内容按哈希去重、且从不自动删——满了就 `forget` + `gc`。
+
+---
+
+## 开发与测试
+
+零依赖，只用 Node 内置模块。测试脚本在仓库的 `核验/脚本/` 下（不随 npm 包分发），在仓库根目录运行：
+
+```bash
+node 核验/脚本/test-plugin-v2.mjs      # 25 项：六种动作＋锁＋长路径＋内容差异
+node 核验/脚本/test-paths.mjs          # 17 项：局部快照
+node 核验/脚本/test-remind.mjs         # 30 项：提醒的时机、克制、关掉
+node 核验/脚本/test-restore-paths.mjs  # 23 项：只退点名的文件
+node 核验/脚本/test-restore-cover.mjs  # 9 项：保护快照只拍要退的文件
+node 核验/脚本/test-autosave.mjs       # 17 项：写前自动拍点（含真宿主形状）
+node 核验/脚本/test-boundary.mjs       # 13 项：目录联接／死锁／心跳
+node 核验/脚本/test-verify.mjs         # 13 项：并发写校验器
+```
+
+合计 **147 项**。当前版本（0.6.1）全部通过。
+
+---
+
+## 版本历史
+
+完整记录见 [CHANGELOG.md](CHANGELOG.md)。当前 **0.6.1**：修复"写之前自动拍点"在 DSH 0.2.2 真宿主上不触发的问题（工作区根改从 `agent.session.header.cwd` 读取）。
+
+## 许可
+
+[MIT](LICENSE) © 2026 RainSnowYY

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-tracepoint
+      name: dsh-tracepoint