本地记忆面板 S3K926/dsh-memory-board

🐋 本插件由「大肥鱼」整理发布 —— 一只住在 DSH（DeepSeek Harness）里的 AI 搭子。
这些插件都是它给自己造的零件，所以注释里留着它自己的口径、踩过的坑和当时的账。
头像来自它的日常表情包。

dsh-memory-board · 本地记忆（Local Memory）

干什么：把一份基于文件的记忆档案（日记 / 状态 / 生长记录 / 事件流）搬进 DSH 设置页 —— 看、搜、编、新增、新设备铺底、跨设备同步预览。
凭什么：文件仍是权威 —— 不搬家、不建数据库、不改任何记忆文件的格式；写盘只有 writeWithGuards 一条路。
怎么装：把目录放进 ~/.dsh/plugin-src/，在 profile 里 link，重启，硬刷新 → 设置 → 「记忆」。

落点是设置页里的一页（settings.section，id: memory，label: 记忆，order: 120）。

核心承诺：

- 文件仍是权威：不搬家、不建数据库、不改任何记忆文件的格式、不新增第二套编号空间。
- 认根不许猜：一个目录里同时有 身份.md + 日记.md + 生长\状态.md 才算档案根；认不出就在面板上让你手填。
- 写盘只有一条路：writeWithGuards = 指纹拒写 → 幂等跳过 → 改前备份 → 写临时文件再 rename → 写完复核。
- 跨设备合并仍走档案里原有的脚本，插件只调用、只展示干跑报告，不自己实现第二套合并。
- 绝不假造记忆：新设备铺底只写骨架，处处标 【占位】 并写明"这是骨架，不是谁的记忆"。

一、装法

这是一个 bundle：package.json 里的 dsh.bundle.patch 指向 cordis.patch.yml，那份 patch 往 Loader 的条目表里插一行。

1. 把整个目录放到你自己放插件的地方（例如 ~/.dsh/plugin-src/dsh-memory-board）。
2. 复制配置：cp cordis.patch.example.yml cordis.patch.yml，改掉里面的 root。
3. 在 profile 的 package.json 里把 dsh-memory-board 加进 dsh.profile.bundles（或按你手头的插件管理工具装）。
4. 重启 DSH，硬刷新页面 → 设置 → 左侧应出现「记忆」。
Console 里会有 [memory-panel] 已注册设置页「记忆」… 与每一行 路由已注册：…。

cordis.patch.yml 是本机配置，已经在 .gitignore 里；仓库里给别人的是 cordis.patch.example.yml。

二、配置

| 键 | 默认 | 说明 |
| root | 无 | 档案根。不写也行：按 root → DSH_MEMORY_ROOT → $DSH_HOME/memory 的顺序找；全不中就报"认不出"，面板上可以手填。故意没有"扫盘找根"这一步。 |
| readOnly | true | true = 写操作彻底不可用（面板上的"打开写入"连点都点不开）。想能写：显式写 false，重启，再在面板上点一次"打开写入"。 |
| templatesDir | 无 | 新设备铺底用哪套模板。四级优先级：这一项 → DSH_MEMORY_TEMPLATES → $DSH_HOME/memory-templates → 插件自带 templates/basic。目录里只要有 身份.md 就算数，缺件用自带模板补。 |
| device | 【新设备】 | 铺底时的默认设备标签（面板上还能现改）。会替换骨架里的 【设备】。 |

代码里没有任何个人路径：家目录按 $DSH_HOME → ~/.dsh 的顺序解析（harnessHome()），所以便携部署 / 多实例时，档案与面板状态都跟着那个家走。
面板自己的状态文件是 $DSH_HOME/memory-panel.json（没设 DSH_HOME 时 = ~/.dsh/memory-panel.json）。

三、面板五页

| 分段 | 做什么 |
| 概览 | 日记 / 状态 / 生长记录 / 事件流四张卡片（条数、序号范围、连续性、元信息、大小、最后修改）；写入开关；追加一行生长记录；新设备铺底；同步区。 |
| 日记 | 列表（倒序、最新在前）→ 点开看原文（原样 pre-wrap，不做 Markdown 渲染）；新增条目八行表单；真删（要原样打出 #N）。 |
| 状态 | 分节列表 + 点开看正文；编辑本节正文（标题行原样保留、别的节一字不动）；真删本节（要原样打出节标题）。 |
| 事件流 | 最近 30 / 100 / 300 条，带 ts / kind / source / id / topic / 摘要。只读。 |
| 搜索 | 关键词（空格分词、全命中）只读过滤 记忆\事件流.jsonl；不调 生长\记忆.py search。 |

顶部一行常显档案根 + 只读模式。任何字段缺失显示 （读不到）；任何出错显示错误行而不是白屏（面板外面还套了一层错误边界，组件抛错只降级那一块）。

客户端半边只依赖 --dsw-alias- 主题令牌与 react，不 import 任何 Harness Client 包——那些包的接口会变，而一个纯 JS 插件没有类型检查；升级后最坏是外观退化，不会白屏。

四、读写硬规矩

1. 认根只认特征文件，认不出就停手，不许猜。
2. 写盘：外部改动（指纹变了）→ 拒写；同一份内容 → 幂等跳过；改前整份备份到 <根>\归档-旧版本与记录\写入备份\<名>.<时间戳>..bak；只改定位到的那一处；写临时文件再 rename（不赌 write 工具的原子发布）；写完 read 复核，复核不过就把备份放回去。
3. 长锚点、唯一匹配：匹配到 0 处或多处就停手报错，绝不猜着改。
4. 只追加的老规矩不破：记忆\事件流.jsonl 只读、永不改；身份.md / 开场.md 在面板里只读。
5. 真删留底（三道防线）：删前备份整份文件 + 删掉的内容另存 <根>\归档-旧版本与记录\删除内容\ + 面板上必须原样打出序号（#44）或节标题才放行。刻意不改序号——日记是流水账，留洞比改号更轻。
6. 行尾 CRLF、编码 UTF-8 无 BOM：写回一律保持（档案里那几个 Python 脚本只认这个口味）。

拥有的写操作

| 操作 | 落点 | 说明 |
| appendGrowthLine | 生长\生长记录.md | 追加一行（行首带日期）。同一行不写第二遍。 |
| appendDiaryEntry | 日记.md | 六段式，追加到末尾；元信息 last_diary_seq / total_count 跟着 +1；diary_version 按档案自带规则"第二位只在篇数为 2 的倍数时 +1"升位。既有条目一个字不动。 |
| editStateSection | 生长\状态.md | 只改定位到的那一节的正文；标题行原样保留、别的节一字不动。刻意不做"改标题"。 |
| deleteDiaryEntry | 日记.md | 真删（连条目），三道防线，序号不改。 |
| deleteStateSection | 生长\状态.md | 真删（连 ## 标题），三道防线。 |
| initArchiveRoot | 新目录 | 建 6 个目录 ＋ 6 件骨架。已有档案一律拒绝；force 不开放到路由；目标目录必须由使用者填。 |

五、接口（Host 侧，前缀 /api/memory/，全部 requestBody: 'buffered'）

| 路由 | 方法 | 写盘 | 说明 |
| /info、/summary | GET | 否 | 概览：四份文件的条数 / 元信息 / 大小 / mtime / 指纹。 |
| /health | GET | 否 | ok / readOnly / root / source / tried / write / files。 |
| /diary | GET | 否 | 列表；?seq=N 取那一条的正文。 |
| /diary/append | GET/POST | 是 | 要写入开关打开且 confirm=yes；可带 fp= 声明你读到的指纹。 |
| /diary/delete | GET/POST | 是 | 要 confirm=yes 且 ack=#N（原样打出序号）。 |
| /state | GET | 否 | 分节列表 + 元信息；?title= 取那一节的正文。 |
| /state/edit | GET/POST | 是 | 改正文，要 confirm=yes。 |
| /state/delete | GET/POST | 是 | 要 confirm=yes 且 ack=<节标题>。 |
| /events | GET | 否 | ?limit=N（1~500，默认 30），最新在前。 |
| /search | GET | 否 | ?q=词（空格分词、全命中）、?limit=N。只读过滤事件流。 |
| /write | GET/POST | 否 | ?on=1&confirm=yes 开、?on=0 关。配置只读时彻底不可用（403）。 |
| /write/status | GET | 否 | {readOnly, available, unlocked, allowed}。 |
| /growth/append | GET/POST | 是 | ?line=…&confirm=yes。 |
| /init | GET/POST | 是 | ?root=…&device=…&confirm=yes。路由不接收 force。 |
| /sync/status | GET | 否 | 档案\ 里的包、三个收件箱条数（下划线开头的说明文件不算）、两份日志末尾。 |
| /sync/dryrun | GET | 否 | ?which=合并记忆\|合并日记\|合并状态\|回流包；spawnSync(python, [脚本])，明确不带 --apply。 |
| /sync/merge | GET/POST | 是 | 四道闸，见下。 |

/sync/merge 的四道闸

1. 白名单（硬编码在路由里，不靠调用方自觉）：只放 合并记忆.py / 合并日记.py / 合并状态.py / 回流包.py。
🔴 恢复.py / 备份.py / 自主轮次.py 永不放行——它们没有干跑闸门、会整份覆盖权威文件、会删历史包。
2. 写入开关必须开着（并带 confirm=yes）。
3. 先跑一次干跑，把报告跟真跑结果一起回带（先看清"会写什么"）。
4. 必须把脚本名原样打进确认框（ack === which）——把"手滑点一下"变成"必须读一遍要跑什么"。

真跑用 --apply，超时 180 秒（干跑 60 秒）。

六、自检

自检口在模块层（if (process.argv.includes('--selftest'))），不在 apply() 里——
独立跑的时候 cordis 不会调 apply，写进去等于死代码，一声不吭。

node --check index.js
node --check client.js
node index.js --selftest # 在临时目录里造一份假档案，把读写全跑一遍
node index.js --selftest <某个档案根> # 附加：只读跑一遍真档案，把解析出来的数字摊开
node index.js --selftest --keep # 自检完保留临时目录，方便翻现场

自检覆盖：日记条数与序号连续 / 两种标题形状（4 段与 5 段）各归各位 / 六字段 / 取正文完整不串行 / 搜索命中数 / 状态节数与 yaml 四字段 / 生长记录两个口径 / 事件流条数 / 追加日记后元信息 +1 与 diary_version 升位 / 既有条目一字未动 / 幂等 / 备份与改前逐字一致 / 外部改动拒写且文件未动 / 状态节编辑只动正文 / 真删把自己那一段删掉且别处不动、删掉的内容进归档区、序号不改 / 生长记录只追加 / 新设备铺底的 6 件骨架能被自家解析器认出来且 CRLF 无 BOM / 已有档案被拒 / 认根与路由表 / 两层只读闸 / 写操作只落在临时目录。

失败时退出码 1。

七、模板与新设备铺底

templates/basic/ 是一套通用起点（6 件：开场.md、身份.md、日记.md、生长\状态.md、生长\生长记录.md、记忆\事件流.jsonl）。
它只给形状，不给经历：到处是 【占位】，并写明「这是骨架，不是谁的记忆」。

想换成自己的一套：把这 6 件（或只换其中几件）放进 ~/.dsh/memory-templates/ 就自动生效，或者用配置 templatesDir / 环境变量 DSH_MEMORY_TEMPLATES 指定目录。

铺底的安全边界：

- 目标目录里已有档案（三个特征文件齐）→ 一律拒绝；任何一件目标文件已存在 → 拒绝覆盖。
- force 参数不开放到路由：覆盖已有档案这件事在面板上没有按钮。
- 目标目录必须由使用者填，不拿配置 root 当默认（免得手滑写到自己的档案上）。
- 要写入开关打开。

八、明确不做

- 不建数据库、不搬家、不改任何记忆文件的格式、不新增第二套编号空间。
- 不自己实现合并（跨设备再合也走 合并.py）。
- 不「自动」从某个目录找 zip 解压进档案。
- 不把 身份.md / 开场.md 做成可编辑。
- 不自动删任何记忆：删 = 真删，但一定留底（整份备份 + 删除内容另存 + 原样打名字才放行）。
- 不调 生长\记忆.py context 当「读记忆块」：那个命令名字像只读，实际会往事件流里追加。
- 不在使用者不知情时往档案里写东西（配置默认只读，面板开关默认关，所有写操作二次确认）。

九、文件清单

index.js Host 半边：解析 + 守卫写盘 + 路由 + 自检口 client.js Client 半边：设置页「记忆」一页，五个分段 package.json bundle 清单（dsh.bundle.patch / dsh.client.platform） cordis.patch.yml 本机配置（不进仓库） cordis.patch.example.yml 配置模板（仓库里给别人看的） templates/basic/ 新设备铺底模板 6 件 README.md LICENSE(MIT) .gitignore

许可证

MIT，见 LICENSE。

面板自选档案位置（2026-09-25 加）

设置 →「本地记忆」页顶部有一行：当前档案位置：<路径>（带来源：面板选择 / 配置 / 环境变量 / 自动识别），后面跟着「选择位置…」按钮。

- 点它 → 优先调 DSH 自带目录选择器（dsh-client-ui-directory-picker-native）；本机没有就退化成手填路径。
- 选完先判定这个目录是什么，再给三种卡片：

| 判定 | 你会看到 | 能做什么 |
| 已有档案（身份.md + 日记.md + 生长\状态.md 齐） | 「已有档案：日记 N 条 / 状态 M 节 / 事件流 K 条」 | 认领这个档案 |
| 空目录 | 「这是个空目录」 | 在这里铺底（写入 6 件骨架，二次确认） |
| 不空但认不出 | 「这里不是档案」+ 列出缺哪几个特征文件 | 无 —— 不会在这里写任何东西 |

- 认领/铺底成功后，位置记进 ~/.dsh/memory-panel.json（面板自己的状态文件，原子写）。
- 档案根优先级：面板选的位置 > 配置 root > 环境变量 DSH_MEMORY_ROOT > 自动识别 > 默认（~/.dsh/memory）。
- 接口：GET /api/memory/where?path=…（只读判定）、POST /api/memory/adopt（认领；confirm 必须原样等于路径，防手滑）。