s867968286/dsh-preset-md

dsh-preset-md

给 DSH 助手赋予人格、灵魂与长期记忆——用 Markdown 定义伙伴的身份、性格、准则与记忆，
自动写日记、自动更新记忆，并在官方设置页里可视化管理。

Give your DSH assistant a soul, personality, and long-term memory — define a companion's
identity, character, and memory in Markdown, with automatic journals and memory updates.

本项目由 AI 生成：代码与文档均由 AI 编码代理产出并迭代，人类负责需求、设计与实机验证。

DSH 的 agent preset 是一份插件行列表（/.agent-presets//agent.cordis.yml）。
本插件让一个 preset 从自己的目录读取几个约定好的 Markdown 文件，拼成该会话唯一的系统提示词；
同时在后台按天写日志、按条目更新记忆文件。

提示词按会话冻结：改文件后新开一个对话即可生效，运行中的会话不受影响。

预览

| 伙伴列表 | 参数设置 | 提示词编辑 |
| :---: | :---: | :---: |
| 伙伴列表 | 参数设置 | 提示词编辑 |

文件约定

/.agent-presets//
├── agent.cordis.yml     ← 加一行 preset-md
├── preset.yml           ← 昵称与个性签名
├── SYSTEM.md            ┐
├── SOUL.md              │
├── IDENTITY.md          ├─ 按此顺序拼成唯一系统提示词
├── USER.md              │
├── AGENTS.md            │
├── MEMORY.md            ┘
├── memory/              ← 按天日志（YYYY-MM-DD.md）
└── changelog/           ← 记忆文件的改动留痕

| 文件 | 用途 | 后台回顾可改 |
|---|---|---|
| SYSTEM.md | 系统级指令 | ❌ |
| SOUL.md | 人格 | ✅ |
| IDENTITY.md | 自我认知 | ✅ |
| USER.md | 用户上下文 | ✅ |
| AGENTS.md | 工作方式 | ❌ |
| MEMORY.md | 持久记忆 | ✅ |

文件不存在或内容为空 → 该段跳过，不会留下空标题。
标题由文件自己写，插件不额外加：最终提示词就是各文件正文按顺序用空行连接。

占位符

正文里可以写下面四个占位符，在会话冻结时替换一次（同一会话内恒定）：

| 占位符 | 替换为 |
|---|---|
| {{cwd}} | 当前会话的工作目录 |
| {{preset}} | 当前 preset id（如 agent-1bd5） |
| {{presetDir}} | 预设目录的绝对路径（六个 MD 与 memory/ 所在目录） |
| {{session}} | 当前会话 id |

其余 {{…}} 原样保留，便于看出没生效。取不到值（例如会话没有 cwd）时同样原样保留。

安装

尚未发布到 npm，请从 GitHub 安装：

装进某个 profile（推荐：可用完整的「伙伴设置」页面）
dsh plugin --profile  add github:s867968286/dsh-preset-md

装完重启 dsh：bundle 不热重载，已挂载的组合不会热替换模块。

本地开发时改用 link：

dsh plugin --profile  add link:/绝对路径/dsh-preset-md

也可以不安装，直接在 preset 里用绝对路径引用 preset 行入口，此时只有提示词注入与自动记忆，没有设置页。

在目标 preset 的 agent.cordis.yml 里加一行：

- id: preset-md
name: dsh-preset-md/preset

目录取 ctx.baseUrl——preset 加载器会把它指向 agent.cordis.yml 所在目录，
所以插件行与那几个 Markdown 必须放在同一个 preset 目录里。取不到时提示词为空并打一条 warn。

人格类预设只需基础工具。 内置模板（templates/agent.cordis.yml.tpl）给的是
一套精简清单：shell / 文件系统 / 技能 / ask-user / todo / web / present，
不含官方 standard 里那套编码 agent 的重型机械（plan mode、compaction、
委派与工作流、goal、jobs）。理由：陪伴场景不需要工程流程，这些行会把工具目录撑大、
并诱导模型走「先规划再实现」的套路；另外模板不挂官方 persona 行——
它的 You are a coding agent ... 会盖掉你的人设。
想拿它当编码 agent 用时，从官方 standard preset 拷回所需的行即可。

本插件不带构建步骤（无 prepare 脚本），从 GitHub 装不需要 allowBuilds 放行。
若日后加了构建脚本，pnpm 会拦截它并打印所需 key，按提示加进 profile 目录的 pnpm-workspace.yaml 的 allowBuilds 再重跑即可。

收窄工具

agent 能看到的工具 = 全局层（profile 里装的插件）＋ preset 层（agent.cordis.yml 挂的行）＋ agent 层。
「preset 没挂某个插件」并不会让它的工具消失，要收窄得显式声明：

- id: preset-md
name: dsh-preset-md/preset
config:
tools:
deny:
- 'mnemon'        # 前缀
- '_recall'       # 后缀
- 'mcp'          # 包含
- 'read_page'      # 精确
allow: ['read_page', 'x_search']   # 白名单：只保留这些全局工具

只支持上面四种写法，中间通配（如 ab）一律不命中。
deny 是黑名单，allow 是白名单（两者同时给时都生效）。

插件会先把写法展开成精确的工具名再下发，因此没命中任何工具的条目只会打一条 warn，
不会让插件加载失败——升级第三方插件后名单失效时你能从日志里看到。

自动记忆

后台异步执行，不阻塞对话，也不需要子代理。

触发时机

| 时机 | 条件 |
|---|---|
| 会话结束 | 必触发（绕过防抖；若正好有回顾在跑，排队等它结束后补跑） |
| 上下文压缩 | 压缩开始（compaction/start）时必触发——压缩会把老对话摘要掉，没归档的段落压缩后就再没机会总结 |
| 回合结束 | 满足其一即触发：未总结轮数 ≥ reviewTurns 或 新增字符数 ≥ reviewChars |
| 防抖 | 5 秒内不重复触发（只作用于「回合结束」这一路） |
| 超时 | 单次回顾最长 2 分钟，超时中止并复位状态 |

失败会重试：水位（已总结到哪）只在成功后才推进。调用失败或输出解析失败时，
那一段内容的水位不推进，下一轮自然带上重试——否则失败那轮的内容滚出转写窗口后就静默丢了。
连续失败到 MAX_REVIEW_ATTEMPTS（3 次）则放弃这一段强制推进，避免一段坏内容把水位永久卡死。

只统计真人发言：user/message 这个事件类型不区分来源（真人发言、官方运行时快照、
其他插件的注入消息都落成它），所以触发阈值只计 source.kind === 'user' 的发言与助手回复。
不过滤的话注入文本会撑大「新增字符数」，让回顾在真人几乎没说话时就被触发。

默认阈值 reviewTurns = 3、reviewChars = 2000：一次有实质内容的往来通常 2~3 轮就够，
2000 字符约等于一次中等长度的往返。阈值设得太大（旧默认是 10 轮 / 8000 字符）会让短会话
几乎不可能在回合中触发，只能靠「会话结束」兜底，体感就是「根本不触发」。

阈值设置（reviewTurns / reviewChars）会在读写时做校验：非正数、空值或类型不符一律回落到默认值。
这一点很重要——阈值退化成 0 会让「未达阈值才跳过」的判断恒不成立，变成每个回合都跑一次 LLM 回顾。

转写窗口跟随 reviewChars：阈值调大后回顾间隔变长，窗口同比例放大，
两次回顾之间的内容不会被尾部截断丢掉；阈值调小时窗口有下限，不会缩到把正常对话截成「太短」。
真的超窗时保留尾部（本轮结论比开头更值得总结），并在开头加一行 …（前文略） 标记 —— 不静默截断。

只统计本会话自己的事件：子代理会话由 fork 派生，磁盘上带着父会话的完整历史。
用官方 ownEvents()（"after its fork-inherited prefix"）而非 snapshotEvents()（全量），
否则继承前缀会在第一轮就把触发阈值灌满 —— 实测子会话转写有 90%～99% 是父会话内容。

用哪个模型：直接用当前会话正在跑的模型（取自会话日志最后一条 request/header 的
provider/model），而不是全局默认模型——否则会话换过模型后，回顾会跑到另一个模型上去。
只有在会话还没有任何请求头的极端情况下才回退到全局默认。

一次回顾做两件事（单次调用）：

1. 当天日志：追加到 memory/YYYY-MM-DD.md。正文可写一行「> 摘要：…」（本段最核心的结论，
不超过 50 字，会被检索索引直接展示），其余按需分「讨论与解决 / 关键信息 / 感悟」三段；
2. 记忆更新：只允许改 SOUL.md / IDENTITY.md / USER.md / MEMORY.md，
操作 add / replace / remove。replace / remove 的目标文本必须逐字来自原文且唯一，
否则该条被跳过——永远不整文件覆盖。单条失败不影响后续条目。

记什么、不记什么：摘要与那三段都允许为空——判据是「本轮有没有值得以后回看的新内容」，
不是「把格式填满」。没有对应内容的段落整段省略，不要凑字数写套话。

| 要记 | 不记 |
|---|---|
| 新出现的偏好、决定、约定、事实 | 无意义寒暄（打招呼、道谢、应答） |
| 达成的结论、方案、取舍理由 | 一问一答即结束、没有结论的简单问题 |
| 排查出的根因、踩过的坑、验证方式 | 测试性对话（「测试」「试试」「1」） |
| 关系或情绪的转折 | 纯操作确认（「重启了」「改了」） |
| 项目与环境的稳定事实 | 今天日志或长期记忆里已经记过的内容 |

拿不准时用一条判断：这条信息在往后某天回看时，还能帮我理解他、或理解当时的决定吗？
能就写，不能就跳过。当天已经有日志，不代表这一轮就不用写——只是别把旧内容重复抄一遍。

失败要看得见：回顾在后台跑，日志只进 dsh 进程的 stdout，默认看不到。所以
「触发条件已满足、但没能写入」时（拿不到模型、调用异常、输出解析失败、模型没产出日志段落），
除了打 warn，还会往对话里注入一条 [preset-md] 提示，说明是「已触发但失败」并带上原因。
同一条会话的这类提示有 60 秒节流，不会刷屏；「对话太短」这类正常跳过只记日志、不打扰用户。

写回来的换行风格：MD 文件若是 CRLF（Windows 编辑器保存过），改动后仍保持 CRLF，
不会因为一次自动记忆就把整个文件的换行符换掉。

留痕：每次改动前先写 changelog/.changelog.md，一条记录一块，按块滚动裁剪，不切断单条记录。

上下文预算

六个 MD 拼起来就是系统提示词，所以插件按整体管体积：

| 项 | 默认 | 说明 |
|---|---|---|
| 预算 | 20000 字符 ≈ 9400 token | 可在「伙伴设置 → 参数」改；折算按 DeepSeek 口径（1 汉字 ≈ 0.6 token） |
| 分配 | 按固定比例瓜分 | MEMORY 25% / AGENTS 22% / SOUL 20% / IDENTITY 13% / SYSTEM 12% / USER 8% |
| 超限提醒 | 开 | 超预算时追加一段「请收敛」提醒；不硬截断——截断会把记忆切碎，比超一点更糟 |
| 关掉提醒 | — | 只度量并打日志，不往提示词里加任何东西；预算仍然生效（日志照打） |

单个文件偏大但总量没超 → 不提示。只有整体越过预算线才提醒，并在提醒里点名偏重的文件，
让模型自己在下次更新记忆时合并、精简、清理过期条目。

启动时会打一条 info 日志，形如：

[preset-md] 注入体积 6031 字符 ≈ 2866 token，预算 20000（占 30%）| SYSTEM 533(9%) SOUL 1583(26%) ...

预算只管六个 MD。三个 preset_md_ 工具 schema 另占约 700 token，不含在内。

记忆工具：注册三个 preset_md_ 前缀工具，覆盖「读日志 / 写日志 / 更新记忆」。

| 工具 | 用途 |
|---|---|
| preset_md_search | 只读：检索历史日志 |
| preset_md_journal | 写入：把一段正文追加进当天日志（自动补日期头与时间标题） |
| preset_md_memory | 写入：条目级更新 IDENTITY.md / SOUL.md / USER.md / MEMORY.md |

preset_md_search 参数：

| 参数 | 行为 |
|---|---|
| days | 最多回溯几个有内容的日志文件（不是自然日），默认 7 |
| query | 全文逐行匹配，返回 日期:行号 与上下文；不填则返回日志索引（每段时间标题 + 摘要行，超长截断补 …） |

preset_md_memory 参数：file（白名单枚举）、op（add / replace / remove）、content、old_text。
replace / remove 的 old_text 必须逐字来自原文且全文唯一，否则被拒绝并提示先读文件。

为什么不直接用 write / edit 直写文件：后台自动记忆走 memory-store 的按路径写队列
（enqueue），直写不经过队列会与后台形成「读-改-写」竞态；而且直写绕过 changelog 留痕
与 old_text 校验。这两个写入工具内部走 appendJournal / applyUpdate，三条保护都在。

伙伴设置

装进 profile 后，官方设置页里会多一项「伙伴设置」（复用官方 settings.section，不自建侧栏入口）。

设置 → 伙伴设置
├── 伙伴   卡片列表：昵称 + 个性签名 + 查看 / 复制 / 删除
│   └── 查看   昵称与签名可编辑，另有 7 个页签
│              提示词 / 个性 / 身份 / 用户 / 准则 / 记忆 / 日记
└── 参数   自动记忆开关与阈值、注入预算与超限提醒

| 行为 | 说明 |
|---|---|
| 编辑 Markdown | 每个文件一个页签，纯文本编辑（不引 Markdown 渲染库）。无改动时保存按钮禁用；切换页签前若有未保存改动会先确认 |
| 新建伙伴 | 用内置模板生成 6 个 Markdown + agent.cordis.yml + preset.yml + memory/ |
| 复制伙伴 | 克隆内容与组合，不带历史日志 |
| 删除 | 只移动到备份目录，不真删；新会话选不到，旧对话仍可查看 |
| 参数 | 存 /preset-md/settings.json；改完点「保存」提交。自动记忆与阈值实时生效（下一个回合就按新值走，不必重启或重开会话） |

参数表单是攒草稿、点保存才提交（与 dsh-memory-md 一致）：改到一半不会生效，
有未保存改动时按钮上方会显示提示。数字项留空即用默认值（提交 null，由服务端
归一化回落）；0、负数、非数字同样回落默认，不会被夹成一个更小的值。

生效时机分两类：

| 设置 | 何时生效 | 为什么 |
|---|---|---|
| autoMemory、reviewTurns、reviewChars | 实时（下一个回合） | 后台回顾每次触发时直接读设置文件 |
| contextBudget、budgetNotice | 新开会话 | 它们影响注入文本，而注入文本按会话冻结（见下方「固定行为」） |

目录结构

├── src/index.js          主入口（Host 半）：/preset-md/api/* 与文件读写
├── src/preset.js         preset 行（子路径 ./preset）：提示词注入 + 自动记忆
├── src/core.js           纯逻辑：目录解析、变量与 section 注册、会话冻结、工具收窄
├── src/memory-store.mjs  日志追加 / 条目级更新 / changelog
├── src/review.mjs        回顾提示词 + 模型调用 + 结果解析
├── src/search.mjs        preset_md_search 工具
├── src/tools.mjs         preset_md_journal / preset_md_memory 工具
├── src/settings.mjs      设置读写
├── src/templates.mjs     模板装载
├── templates/.tpl       新建伙伴时写入的内置模板
├── client/client.js      Client 半：注册「伙伴设置」页面
├── cordis.patch.yml      bundle 补丁
└── test/.test.mjs

开发

npm install
npm test          # node --test
npm run check     # 语法检查

运行时依赖只有官方的 @deepseek-ai/dsh-llm（用于构造回顾消息与解析模型输出流），
版本需与 dsh 运行时一致——预发布版本不受 ^ 范围匹配，请写精确版本。

固定行为（不可配）
这几项没有开关——只有一种模式是对的，留着开关只会让人以为另一种也可用：

| 行为 | 说明 |
|---|---|
| 独占系统提示词 | 系统提示词只保留本插件的 MD。官方那句身份声明与其他插件注册的提示词段都不再进入请求。同一 scope 里若另有 complete 段，组装会直接失败（官方限制：只能有一个） |
| 会话内冻结 | 同一会话只读一次文件，改 Markdown 要新开对话才生效。代价是改动不即时，收益是系统提示词逐字节稳定、KV 缓存前缀持续命中 |
| 按会话隔离缓存 | 缓存键取会话 id；取不到时用 cwd 兜底，避免不同工作区的 {{cwd}} 串味 |

注意事项

| 事项 | 说明 |
|---|---|
| 改插件代码要重启 dsh | 已挂载的组合不会热替换模块 |
| 官方 context 不受影响 | 独占只替换 section；沙箱策略、审批策略等运行期快照照常注入 |
| preset.yml 只动三个键 | 昵称/签名写入时只替换 name / description / order 三行，注释与其余字段原样保留（官方 dsh-agent-presets 也读这个文件）。昵称不写进 agent.cordis.yml——那里只是插件行清单 |
| 设置页写入带冲突检测 | 保存 Markdown 时回传载入时的版本指纹；若后台自动记忆期间改过同一文件，服务端回 409 并提示重新载入，不会静默覆盖那条记忆 |
| 本机 HTTP 接口有来源校验 | /preset-md/api/* 的写请求（POST/PUT/DELETE）校验 Sec-Fetch-Site 与 Origin，跨站一律 403；非浏览器客户端（curl 等）不受影响 |
| 昵称 / 签名有长度上限 | 昵称 ≤ 60 字符、签名 ≤ 200 字符，超限报 400 |

关键词

dsh · deepseek-harness · persona · soul · memory · companion · ai-assistant ·
agent-preset · markdown · system-prompt

人格 · 灵魂 · 记忆 · 助手 · 伙伴 · 预设 · 提示词

致谢与借鉴

本项目参考了以下两个开源项目，仅借鉴设计思路与文件约定，代码为独立实现：

| 项目 | 地址 | 借鉴点 |
|---|---|---|
| dsh-claw-suite | https://github.com/xingyingyuzhui/dsh-claw-suite | 用约定的 Markdown（SOUL / IDENTITY / AGENTS）承载人设并注入系统提示词，USER / MEMORY ＋ memory/YYYY-MM-DD.md 日记另行注入与回合后回顾；在设置页里按页签读写这些文件的交互思路 |
| DeepSeek-Harness-Hanako-Memory | https://github.com/moononnn/DeepSeek-Harness-Hanako-Memory | 卡片式伙伴管理界面与预设增删改的交互思路（本项目按官方 UI 规范重写，未照搬其界面代码） |

也感谢官方 @deepseek-ai/dsh 提供的 agent-presets / settings / home-paths 机制。

关于 AI 生成：本项目的代码、文档与界面实现均由 AI 编码代理生成并多轮迭代，
人类负责需求定义、架构决策与实机验证。使用前请自行审阅，生产环境请谨慎评估。

许可

MIT