dsh-ledger-memory 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 陈黛华
+
+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,136 @@
-# Temporary Holding Version
+# dsh-ledger-memory（台账记忆）
 
-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.
+> 一个 **DSH（DeepSeek Harness）宿主侧插件**：让 AI 用可复现的方式，把项目里的工作**记住**。
+
+它管的不是聊天记录，而是一个**项目自己的记忆载体 —— 台账**：
+可回溯、可追查、只追加、按周归档。围绕它还有活动日志、上下文压缩与跨会话交接。
+
+**不预设任何模板** —— 台账的文件名、分几个文件、有哪些字段，全部由 AI 在初始化时
+按项目类型自己决定；插件只做**检测 / 注入 / 回写 / 归档 / Git 配合**这些流程性工作。
+
+---
+
+## 它解决什么问题
+
+| 问题 | 它怎么做 |
+|---|---|
+| 换个会话就"忘了这个项目干到哪" | 会话开始把**活跃台账全文**注入上下文；内容没变则不重复注入（防打烂 prompt 缓存） |
+| AI 走完一轮，成果没落地 | 回合末把「完成了什么 / 卡在哪 / 下一步」写回活跃台账 |
+| 台账越来越长，读不完 | 超阈值时把**最旧的已完成条目**移进 `归档目录/YYYY-MM/weekN`，**只追加不删除** |
+| 细节被上下文压缩抹掉 | 压缩**之前**把用户原话、报错原文、改过哪些文件落盘成一份**逐字胶囊**；压缩后与台账一起注回 |
+| 新会话接不上旧会话 | 写一份**交接单**，并把指针推进新会话的**第一轮注入**（不是等你来问） |
+| 想查"谁什么时候改过这份台账" | 台账末尾自动维护一张变更登记；完整历史在只追加的活动日志里 |
+| 只是一次性排查，不是项目 | `ledger_note` 写一份**问题记录**（现象 → 根因 → 结论 → 做了什么），不建台账 |
+
+## 三层上下文压缩
+
+| 层 | 触发 | 做什么 |
+|---|---|---|
+| ① 常态 · 增量 | 水位比上次压缩涨约 **20 点** | 只压**最旧一段**，保留最近约 10 点不动 |
+| ② 兜底 · 全量 | 水位到 **70%**（内核默认是 80%） | 全量压缩，但保留**指向所需内容的指针**：用户原话 / 报错原文 / 改过哪些文件 / 去哪重读 |
+| ③ 终局 · 交接 | 你要换会话时 | 交接单让新对话无缝接上 |
+
+围绕这三层有一条铁律：**先记台账，再压缩**。水位提醒发出的那一刻，插件会记住
+「**已经要求它写台账了**」，在它写完之前**不压缩** —— 否则压掉的正是这一轮唯一的那份进展。
+
+## 安装
+
+需要 **Node.js ≥ 22.19**。
+
+```bash
+# 走 npm
+npm install dsh-ledger-memory
+
+# 或走 DSH 自己的插件命令
+dsh plugin add dsh-ledger-memory
+```
+
+装完**重启客户端**才生效 —— 内核对已加载的插件不会因文件改动自动重载。
+
+## 用法
+
+不用配置什么。打开一个项目目录开始工作，插件会：
+
+1. 发现这里**还没有台账** ⇒ 注入一句提示，让 AI **来问你**要不要初始化（它不会自己动手）；
+2. 你同意后，AI 按这个项目的类型**设计一套台账结构**并登记；
+3. 之后每个会话自动加载、每轮结束自动回写、超长自动归档。
+
+### 手动命令
+
+在对话里敲 `/ledger`（不带参数会弹一张可点的卡片），或用子命令：
+
+```
+/ledger status     看状态（有没有台账、用的哪个文件、几行、Git、日志开关）
+/ledger show       把当前活跃台账全文打出来
+/ledger init       初始化台账（由 AI 为这个项目设计一套结构）
+/ledger update     让 AI 把本次会话的进展写回台账
+/ledger archive    把最旧的已完成条目移进归档目录
+/ledger compact    立刻做一次全量压缩（保留指针）
+/ledger light      轻量压缩
+/ledger log        查活动日志
+/ledger handoff    写一份交接单
+```
+
+### 设置面板
+
+**设置 → 项目台账（台账 / 压缩 / 日志）**，可调十二项：回合末卡片开关、高保真压缩水位、
+增量压缩的涨幅与保留量、活动日志五档开关、活跃台账行数上限、变更登记条数、水位提醒档位等。
+
+> 一条要知道的语义：`maxActiveLines` / `changeRegisterMax` / `logLevels` **以每个项目
+> 自己清单里的值为准**（日志是只追加的证据，全局设置改不动它）。
+> 面板里这三项是**新项目初始化时写进去的默认值**。
+
+## 十二个工具
+
+AI 在对话里调用，你也可以让它调用：
+
+| 工具 | 作用 |
+|---|---|
+| `ledger_status` | 报告这个项目的台账状态（只读） |
+| `ledger_read` | 读台账 / 决策记录 / 归档 |
+| `ledger_write` | 写活跃台账或决策记录 |
+| `ledger_init` | 登记台账结构（四条硬约束：一个活跃台账 / 一份独立决策记录 / 一个只追加归档目录 / 行数上限） |
+| `ledger_archive` | 把旧条目移进只追加的归档 |
+| `ledger_conform` | 检查一个既有项目的台账是否符合预期，能修的**只做加法** |
+| `ledger_note` | 写一份**问题记录**（非项目场景，有终点的那种） |
+| `ledger_log` | 查活动日志（五档，**从不注入上下文**） |
+| `ledger_log_write` | 追加一条回合小结 |
+| `ledger_handoff` | 写交接单，供下一个会话接手 |
+| `ledger_compact` | 请求一次高保真压缩 |
+| `ledger_checkpoint` | 把这一刻的选择交给用户（记台账 / 记+压缩 / 记+交接 / 跳过） |
+
+## 活动日志（五档）
+
+挂在你为项目登记的日志目录下，**只追加、永不改写**，且**从不注入上下文**（按需查）：
+
+| 档 | 内容 |
+|---|---|
+| L0 | 台账变更的里程碑 |
+| L1 | 回合小结（带会话编号） |
+| L2 | 文件流向 |
+| L3 | 工具调用流水（默认关） |
+| L4 | **逐字存档你说过的每一句话**（带会话编号与时间） |
+
+> 采集类档位只认**会话的工作目录**，不会去猜子项目。
+> 在一个装着多个项目的目录里开会话时，采集类档位写不出东西 —— 这是刻意的。
+
+## 依赖与许可
+
+- **零运行时依赖**（`dependencies` 为空）
+- 唯一 peer 依赖：`@deepseek-ai/cordis`
+- 许可：**MIT**
+
+## 自检
+
+仓库里带一套离线自检，不需要网络、不需要装 DSH：
+
+```bash
+npm test
+```
+
+## 已知边界
+
+- 注入走 `agent/pre-step`（可替换本轮消息），不是 `systemPrompt.context`。
+- 改代码后**必须重启客户端**，内核对已加载插件不会热重载。
+- 采集类日志档位在"容器工作区"（装着多个项目的目录）里写不出东西。
+- 压缩服务只能经 `agentPresets.serviceFor(agent, "compaction")` 取到，`ctx.get("compaction")` 恒为 `undefined`。

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-ledger-memory —— 项目台账自动管理
+#
+# 这个文件是「profile bundle patch」：内核组合 profile 时会把它插进插件树。
+# ★ 两条实测教训（改动前必读）：
+#   1. package.json 里必须同时有 dsh.bundle.patch 和（如果带浏览器半边）dsh.client，
+#      只写 dsh.client 会让内核直接失败：
+#        profile bundle "..." declares no dsh.bundle in its package.json
+#   2. id 一律用包名，别自创短名。
+
+- insert:
+    - id: dsh-ledger-memory
+      name: dsh-ledger-memory