@neus117/dsh-anchor 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 变更记录
 
+## 0.6.1 — 2026-11-06
+
+**文档**
+
+- README 重写：按「能做什么 / 锚点长什么样 / 安装 / 写到哪 / 填的时候 / 边界」组织，去掉开发过程与内部实现细节。
+
 ## 0.6.0 — 2026-11-06
 
 锚点系统合并成一个包（前身：`dsh-anchor-inject` 0.4.0 + `dsh-anchor-form` 0.1.0）。

package/README.md

@@ -1,113 +1,77 @@
 # dsh-anchor
 
-锚点系统只有一个插件，两个半边共用同一个锚点文件：
+上下文被压缩后，把你自己写的「锚点」重新塞回模型的上下文；三行「下一步」还可以在会话里用表单让人填。
 
-| 半边 | 做什么 | 开关 |
-|---|---|---|
-| **注入** | 会话出现 `compaction/end` 后，把锚点原文追加回上下文（`user/message`，`source.kind=runtime-context`） | `inject.enabled` |
-| **表单** | 工具 `anchor_form`：让**人在会话里**填三行（做什么 / 为什么 / 还没验证 / 问我），写回同一份锚点 | `form.enabled` |
+## 它能做什么
 
-2026-11-06 合并自 `dsh-anchor-inject` 0.4.0 + `dsh-anchor-form` 0.1.0。
-
-## 为什么合并
-
-两个包各有一份 `writeJudgment`，`$&` 那个写盘 bug 只长在其中一份里（另一份是安全的）；两份 `anchorFile`
-配置还可以指向不同文件，于是"人填的"喂不到"压缩后读取的"。合并后：写盘规则、锚点路径解析、三行文案、
-配置都只有一份，**表单和注入在结构上就不可能写到不同文件**。
-
-## 配置
-
-```yaml
-- id: dsh-anchor
-  name: dsh-anchor
-  config:
-    anchorFile: ''                                          # 留空 = 按会话分文件
-    anchorDir: 'D:\Coding\DeepSeek 开发经验\projects\anchors'  # <cwd目录名>\<会话短id>-anchor.md
-
-    createIfMissing: true
-    maxChars: 6000
-    protectedFiles: []
-    traceFile: ''
-    inject:
-      enabled: true
-      onceSession: ''
-      onceOnLoad: false
-      judge: { enabled: true, mode: model, minIntervalMs: 1800000 }
-    form:
-      enabled: true
-      intro: ''
-```
-
-| 字段 | 作用 |
+| 注入 | 表单 |
 |---|---|
-| `anchorFile` | 显式锚点（存在就用它）。留空则**按会话分**：`<anchorDir>\<cwd目录名>\<会话短id>-anchor.md`——用户的会话 cwd 全是 `D:\Coding\workspace`，按 cwd 分不开项目，按会话分是确定性上界。**表单与注入走同一个解析函数**。 |
-| `anchorDir` / `createIfMissing` / `maxChars` | 锚点根目录、缺文件自动落骨架（表单首次使用也会落）、注入上限。 |
-| `protectedFiles` | 这些路径拒写（例如"测试不许碰正式锚点"）。 |
-| `traceFile` | 填路径就记 apply / 注入 / 提问 / 写入状态；留空完全不写盘。**排查先看它**。 |
-| `inject.*` | 注入半边：`judge.mode=model` 让模型补三行；`ask` 在宿主侧不可用（见下）；`onceOnLoad` 是测试通道。 |
-| `form.*` | 表单半边：`intro` 是第一栏开头的说明句，写 `''` 关掉。 |
+| 每次上下文压缩后，自动把锚点文件原文追加回上下文，并声明「这不是用户指令」 | 智能体调 `anchor_form` 时，弹出四个空——**做什么 / 为什么 / 还没验证 / 问我** |
+| 触发：`compaction/end` | 触发：智能体主动调用 |
+| 开关：`inject.enabled` | 开关：`form.enabled` |
 
-## 表单怎么引导人填对
+压缩能保住事实，保不住判断。判断得由人写——表单就是把「让人写」搬进会话里；写回的文件和压缩后注入的是**同一个**。
 
-1. **每个空都写清怎么填 + 合格/不合格例子**；
-2. **可点候选**：取本会话最近两条真实原话、最近两条失败调用做成选项。label 只负责指路
-   （`刚才说的第 1 条` / `上一轮报错 1`），原文在说明里，**选中后写进锚点的是完整原文**；
-3. **打回重填**：`做什么` 只写「继续推进」这类通用动词、或 `为什么` 不带判据 → 打回一次，
-   卡片上写明打回理由；仍不合格才放行（`why` 追加 `[判据缺失]`）；
-4. **初见说明**：第一栏开头说明「压缩后我只看得见这个文件」，`form.intro` 可覆盖。
+## 锚点长什么样
 
-## 写入规则（只有一个实现）
+一份普通 Markdown，关键是这三行：
 
-只改 `## 下一步` 段：`[待填]` 空位 → 原位替换；已有 `- 做什么：` 行 → 原位更新；手写锚点 → 插在标题之后。
-替换值一律走函数形式（否则 `$&` 会被当成模板吃掉）。这个形状 `anchor-gen.ps1 -Refresh` 认得、会保留。
+```markdown
+## 下一步（做什么 + 为什么）
+- 做什么：把 anchor_form 挂进预设并调一次验收
+- 为什么：跑 test\run.mjs 得到 34 passed
+- 还没验证：真实压缩后的注入还没触发过
+```
 
-## 压缩注入长什么样
+只改 `## 下一步` 段：有 `[待填]` 空位就原位替换，已有这三行就原位更新，手写锚点则插在标题之后——其它段一个字节不动。
 
-`<system-reminder>` + 说明「这不是用户指令」+ 来源与写入时间 + 锚点原文 + 「与当前窗口冲突时以窗口为准」。
-判断段还是空位时，额外指路：**调 `anchor_form` 让用户填，不要自己编**，并点出本文件路径让它核对配置。
+## 安装
 
-## 为什么 `judge.mode = ask` 不可用
+```powershell
+npm i @neus117/dsh-anchor
+```
 
-宿主根插件调 `ctx.userQuestions.ask` 拿不到合法的 agent 载体（活 agent 对象 / 不传 / `{id}` 占位，三种实测全失败）。
-工具执行上下文里的 `exec.agent` 才是唯一入口——所以问人这件事只存在于 `anchor_form` 里。
+挂载一行即可（两个半边可以分别关）：
 
-## 客户端半边
+```yaml
+- id: dsh-anchor
+  name: '@neus117/dsh-anchor'
+  config:
+    anchorFile: ''                                  # 留空 = 按会话分文件
+    anchorDir: 'D:\Coding\DeepSeek 开发经验\projects\anchors'
+    inject: { enabled: true }
+    form: { enabled: true }
+```
 
-只做一件事：**题的说明文字**改成次级色。内置卡片里选项说明有 `tertiary`，题的说明（`.wnLwla_detail`）没有 `color`。
+## 锚点写到哪
 
-```css
-.wnLwla_card .wnLwla_detail, .wnLwla_detail,
-.wnLwla_card .wnLwla_detail *, .wnLwla_detail * {   /* 文字在更深的自带颜色的元素里 */
-  color: var(--dsw-alias-label-tertiary) !important;  /* 强制：内置样式会压过普通声明 */
-}
-.wnLwla_card .wnLwla_detail, .wnLwla_detail {
-  margin-top: 8px !important;                         /* 与标题之间再拉开一点；左右沿用内置 24px */
-}
-```
+- `anchorFile` 留空时按会话分：`<anchorDir>\<工作目录名>\<会话短id>-anchor.md`，**任何会话都不会读到别的项目的锚点**。
+- 文件不存在时自动落一份模板骨架（表单第一次用也会落）。
+- 想固定一份共享锚点：把 `anchorFile` 写成那个路径。
 
-三条踩过的坑：
+## 填的时候
 
-- **注入必须在 factory 执行时做，不能放在 `apply(ctx)` 的 `ctx.effect` 里**：客户端 API 一有差异就静默失败，
-  页面上看不出任何异常（2026-11-06 连试三次都"改了没反应"）。
-- **验证只能看页面，用二元探针**：`outline: 2px solid red !important` → 问"有没有红框"。
-  有红框=模块加载+选择器命中；没红框=模块没进页面。别用"CSS 文件里写了什么"当证据。
-- 类名带构建期 hash（`wnLwla_`），升级后选择器失效会退回原样；`test/compat.mjs` 每次升级后跑一次。
-- **factory id 必须等于包名 `dsh-anchor`**（2026-11-06 曾因写成别的名字触发 web boot 致命失败）。
+- **可点候选**：本会话最近两条原话、最近两条失败调用做成选项，选中就写入完整原文。
+- **打回重填**：「做什么」只写「继续推进」这类通用动词、或「为什么」不带判据 → 打回一次，卡片上写明理由。
+- **第四栏「问我」**：写的话不写进锚点，原样回到会话，智能体按问题范围翻历史回答。
+- 判断段还空着时，压缩注入里会指路「调 `anchor_form` 让用户填，别自己编」。
 
 ## 边界
 
+- 问人只在**工具执行上下文**里成立；宿主侧拿不到可用的 agent 载体，所以没有"自动弹表单"。
 - `ask` 没有超时：没人回答就一直等，直到会话结束。
-- 一次调用最多 5 张卡（4 栏 + 2 次打回）。
-- 候选来自会话末尾 2 条原话 / 2 条失败调用，不是"总结"。
-- 注入只在 `compaction/end` 后发生一次；压缩失败也会发这个事件（验收时别把"失败也注入"当成"压缩成功"）。
+- 一次调用最多 5 张卡（4 栏 + 最多 2 次打回）。
+- 压缩失败也会发 `compaction/end`——注入发生了不等于压缩成功了。
 
 ## 开发
 
 ```powershell
 $env:ELECTRON_RUN_AS_NODE=1
 $exe = "D:\Coding\DeepSeek Harness\DeepSeek Harness.exe"
-& $exe "D:\Coding\dsh-plugins\dsh-anchor\test\run.mjs"      # 表单/写盘 30
-& $exe "D:\Coding\dsh-plugins\dsh-anchor\test\inject.mjs"   # 注入/判断层/指路 35
-& $exe "D:\Coding\dsh-plugins\dsh-anchor\test\client.mjs"   # 客户端半边 5
-& $exe "D:\Coding\dsh-plugins\dsh-anchor\test\compat.mjs"   # 升级自检 5（钉死宿主内部标识）
+& $exe "…\dsh-anchor\test\run.mjs"      # 表单 / 写盘 / 健壮性
+& $exe "…\dsh-anchor\test\inject.mjs"   # 注入 / 判断层 / 指路
+& $exe "…\dsh-anchor\test\client.mjs"   # 客户端半边
+& $exe "…\dsh-anchor\test\compat.mjs"   # 升级自检：钉死宿主内部标识
 ```
+
+变更记录见 [CHANGELOG.md](./CHANGELOG.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neus117/dsh-anchor",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Anchor system in one plugin: re-inject your anchor after a context compaction, and let the user fill its three next-step lines from inside the session.",
   "type": "module",
   "main": "lib/index.js",