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

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

设置页里的「本地记忆」面板：看 / 搜 / 编 / 新增，文件仍是权威。

把一份基于文件的记忆档案搬进 DSH 的设置页：看、搜、编、新增、新设备铺底、跨设备同步预览。 落点是设置页里的一页（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 必须原样等于路径，防手滑）。