Git 演化记忆 Kytolly/dsh-evolve-in-git

dsh-evolve-in-git

English · 中文

DeepSeek Harness 插件：用 Git 支撑长期记忆与进化。

目录

- 它能做什么
- 安装
- 用法
- 架构
- 数据布局
- 配置
- Harness 入口
- 浏览器端
- 开发
- 交付说明
- 协议

它能做什么

这个插件把用户选定或预先配置好的 Git 仓库当作记忆存储。
它能把会话笔记、分支专属记录、可复用技能草稿写进仓库，再作为普通 Git 历史提交。

安装

example: install into the web profile
dsh plugin --profile web add github:Kytolly/dsh-evolve-in-git

安装包会插入一行 dsh-evolve-in-git，使用插件默认值。
后续的配置档补丁可以覆盖 repoPath、repoUrl、auth 以及各个存储根目录。

用法

自然语言

你不用记工具名——把想要的结果说出来，模型会自己挑对应的 evolve_ / memory_ 工具：

| 你说的话（或类似说法） | 模型会用的工具 |
| 「记住：只要 X 发生，就做 Y」 | evolve_remember / memory_save |
| 「有关于部署流程的记忆吗？」 | evolve_recall / memory_search |
| 「读一下我最近的记忆历史」 | evolve_timeline |
| 「把这条警告变成可复用的技能」 | evolve_skill_draft → evolve_skill_promote |
| 「记忆仓库现在是什么状态？」 | evolve_status / evolve_branches |
| 「撤销上一次记忆提交」 | evolve_rollback |

命令（/evolve）

想要明确、可控的操作，就输入 /evolve <subcommand>：

/evolve remember warning "pitfall" :: <content>
/evolve search deploy
/evolve skill list
/evolve skill promote evolve-process
/evolve status
/evolve help

完整命令参考见 Harness 入口。

架构

这个包分成两部分：不依赖框架的核心和一层薄薄的 DSH 适配器：

- src/core.ts（GitMemoryCore）是可移植性边界。它只依赖 Node 内置模块和同级的核心模块——绝不依赖 @deepseek-ai/——并从磁盘上的配置文件解析配置，覆盖宿主提供的基础配置。
- src/index.ts（GitEvolutionService）是适配器：它注册 Cordis 工具、/evolve 命令、系统提示词片段、技能服务商和配置文件路由，再把每个接口映射到 GitMemoryCore。

| 模块 | 职责 |
| src/git.ts | 启动 git：clone/open、status、分支操作、push/fetch、commit、git mv、冲突、回滚。 |
| src/memory.ts + src/memory-index.ts | 扫描 Markdown + YAML frontmatter，维护元数据索引缓存（HEAD + mtime 签名），按预算召回，生成时间线。 |
| src/update.ts | 带版本的更新：新增一条 active 记录，并写入 supersedes/supersededBy；旧文件永不删除。 |
| src/forget.ts | 软删除（移到 archiveRoot）与恢复。 |
| src/privacy.ts | 敏感内容检测、敏感度分级、脱敏、导出过滤。 |
| src/skill.ts | 在 drafts/ ↔ enabled/ 中发现技能；用 git mv 提升/降级；同步内置技能。 |
| src/strategy.ts | Slug/sanitize、从记忆生成草稿、演进建议、预览。 |
| src/harness.ts | /evolve 命令的规范化/解析，以及帮助、用法、安全提示文案。 |
| src/config.ts + src/defaults.ts | 配置文件的读、写、合并，以及插件默认值。 |
| src/invariant.ts | 空操作的不变量伴随模块（唯一事实来源是配置的 Git 仓库）。 |
| src/loopback.ts + src/config-route.ts | 仅限回环的 /api/evolve-git/config 路由，供配置文件编辑器使用。 |
| src/client/ | 浏览器设置区块（evolve-git 插槽）与配置文件编辑器。 |

数据布局

- 记忆 — <repo>/<memoryRoot>/<kind>/<timestamp>-<slug>-<id>.md，每条记录一个 Markdown 文件，带 YAML frontmatter（kind、title、branch、source、tags、createdAt、id、updatedAt、status、supersedes、supersededBy、expiresAt、sensitivity），后面是正文。
- 技能 — <repo>/<skillsRoot>/drafts/<name>/SKILL.md（可提升）与 <repo>/<skillsRoot>/enabled/<name>/SKILL.md（可发现）。提升就是在两者之间执行 git mv，绝不复制，因此始终可逆，也留在历史里。
- 归档 — <repo>/<archiveRoot>/…（相对布局与记忆相同）；evolve_forget 把记录移到这里，于是它们退出召回和时间线，但仍可恢复。archiveRoot 必须保持在 memoryRoot 之外。

配置

Web 设置界面（v0.1.4+）。 插件带一个浏览器端部分，在 web 配置档的设置页上注册一级 Settings → 演进记忆 区块（通过 settings.section 插槽）。表单使用 SettingsScope 适配器，直接通过仅限回环的 /api/evolve-git/config 路由读写每用户配置文件，所以表单显示的就是实际生效的内容（默认值被文件覆盖），保存时立即写入文件。嵌套的 auth 作为一个合并对象写入，auth.token 字段只写（密钥，读回时脱敏）。安装后需要重启配置档，以便重新扫描客户端清单。

- repoPath - 本地 Git 检出目录，用来存放记忆和技能。默认是 ~/.dsh-evolve-in-git/remote-memory。
- repoUrl - 远程记忆仓库。插件不带个人默认值：内置默认值是占位符 https://github.com/<your-github-username>/<your-memory-repo>.git，所以请配置你自己的仓库（见下文「按用户配置文件」）。
- auth - 私有访问的 Git 认证设置。默认配置档优先用 SSH，也支持 token。
- memoryRoot - 记忆记录的写入位置，默认 .dsh-evolve/memory。
- skillsRoot - 技能草稿的写入位置，默认 .dsh-evolve/skills。
- defaultBranch - 创建新分支时从哪个分支演进，默认 main。
- remoteName - 拉取和推送的远程，默认 origin。
- autoCommit - 写入是否自动提交，默认 true。
- archiveRoot - evolve_forget 把记录移到哪里，默认 .dsh-evolve/archive。
- recallTopK - evolve_recall 返回的最大结果数，默认 10。
- recallMinScore - 保留结果的最低相关度分数，默认 0。
- recallMaxChars - 返回的召回内容累计字符预算，默认 8000。
- privacyMode - 敏感内容的写入路径隐私闸门，默认 ask。检测到敏感内容时，block 拒绝写入；redact 存储脱敏后的内容（绝不存明文）；ask 原样存储内容并标记其 sensitivity，以便审查确认。
- digestEnabled - 是否在会话开始时注入 persona+warning 摘要，默认 true。
- digestMaxRecords - 会话开始摘要中 persona/warning 记录的最大条数，默认 5。
- digestMaxChars - 会话开始摘要的最大字符数，默认 2000。

认证

- auth.mode: "ssh" - 使用 ssh 或自定义 sshCommand。
- auth.mode: "token" - 使用 token，或从 tokenEnv 取 token，并带上 GitHub 风格的 Authorization 头。

隐私写入闸门

每次写入记忆都要过隐私闸门（邮箱、电话、身份证、信用卡、AWS 密钥、GitHub token、私钥，以及 password: 这类机密）。privacyMode 控制响应方式：

- block - 检测到敏感内容时拒绝写入。
- redact - 把检测到的片段替换为 <REDACTED>，存储替换后的内容，而不是明文。
- ask（默认）- 原样存储内容，并记录其 sensitivity，以便审查确认。

evolve_show/evolve_export 会遵循记录的 sensitivity 级别，导出默认排除 secret 记录。没有记录 sensitivity 的记录（在闸门出现之前写入的）一律视为 secret，这样它们绝不会被误导出。

闸门只覆盖记忆写入（writeMemoryRecord/updateMemory，即 evolve_remember/memory_save/evolve_update/memory_update）。技能草稿写入（writeSkillDraft/saveSkillDraftFromRecord）在本版本中刻意不过隐私闸门；提升草稿之前，请先检查其中是否有机密。

召回打分。 evolve_recall/memory_search 会把查询与记录只读元数据（title、kind、tags、branch、source）；正文按需加载，只对排名靠前的匹配项加载，但不计入相关性评分。人类命令 /evolve search 用的是同一套元数据索引召回，所以返回的排名结果完全一致，而不是换一套匹配器。

归档约束。 archiveRoot 必须留在 memoryRoot 之外（默认的 .dsh-evolve/archive 就在外面）。如果你把 archiveRoot 指向 memoryRoot 里面，已遗忘的记录仍会被扫描，不会消失。

每用户配置文件

每个 DSH 用户在本地保留一份配置文件，路径为 $DSH_HOME/evolve-in-git.json（默认是 ~/.dsh/evolve-in-git.json）。它只属于本机用户，永远不进任何 Git 仓库——不要提交它。这个文件是唯一的用户配置层：Web 端「Settings → 演进记忆」表单读写的正是这个文件（显示时用你的文件值覆盖默认值，保存时立即写入文件），/evolve config show|open|refresh|set <key> <value> 命令改的也是它。内嵌的配置文件编辑器打开的是原始 JSON。

示例：

{
"repoPath": "/absolute/path/to/your/local-memory-checkout",
"repoUrl": "https://github.com/<your-github-username>/<your-memory-repo>.git"
}

千万不要把访问令牌写进这个文件——用 auth.tokenEnv 指定环境变量名，或者用 Web 设置里的 token 字段（只写）。

Web 端「Settings → 演进记忆」还内嵌了一个配置文件编辑器，直接打开这个文件，按原始 JSON 编辑，通过仅限回环地址的 /api/evolve-git/config 路由保存（保存立即生效）。

Harness 入口点

插件面向当前 Harness 0.1.1-rc.2 宿主契约，涵盖命令、工具、系统提示词和不变量（peerDependencies 为 ^0.1.1-rc.2）。把它装进某个配置档，然后重启该配置档，让 bundle 层完成组装。

工具：

- evolve_connect
- evolve_status
- evolve_remember
- evolve_update
- evolve_forget
- evolve_restore
- evolve_show
- evolve_export
- evolve_branches
- evolve_branch_switch
- evolve_branch_diff
- evolve_skill_draft
- evolve_skill_list
- evolve_skill_promote
- evolve_skill_demote
- evolve_rollback
- evolve_conflicts
- evolve_resolve
- evolve_timeline
- evolve_recall
- evolve_help
- memory_search（evolve_recall 的别名）
- memory_save（evolve_remember 的别名）
- memory_update（evolve_update 的别名）
- memory_delete（evolve_forget 的别名）

人类命令：

- /evolve connect
- /evolve status
- /evolve branches
- /evolve remember <kind> [--expires <iso>] :: <content>
- /evolve update <id> [--merge] :: <content>
- /evolve forget <id>
- /evolve restore <id>
- /evolve config show|open|refresh|set <key> <value>
- /evolve skill draft <kind> :: <content>
- /evolve skill list
- /evolve skill promote <name>
- /evolve skill demote <name>
- /evolve skill sync
- /evolve rollback <ref> [--dry]
- /evolve conflicts
- /evolve resolve <path> <ours|theirs|both>
- /evolve timeline
- /evolve search [--kind k] [--tag t]
- /evolve branch switch <name> \| /evolve branch diff [b] \| /evolve branch revert <ref>
- /evolve help

安装完成后，先验证组合是否正确，再启动长时间运行的配置档：

dsh --profile web --dump-config
dsh --profile web

第一条命令应当显示插件包里的 evolve-git 行。第二条命令启动配置档；加载完成后，模型就能看到 evolve_ 工具，UI 命令注册表也会暴露 /evolve。

内置技能

包里在 skills/ 下附带 evolve-process 技能。加载时，插件会把它实体化到仓库的 <skillsRoot>/drafts/evolve-process/（只在缺失时创建）；/evolve skill sync 会按需覆盖内置副本。用 /evolve skill promote evolve-process 提升它。适配器把仓库的 <skillsRoot>/enabled/ 目录注册为 DSH 技能服务商，所以提升后的技能无需复制到 ~/.dsh/skills 就能调用。

浏览器端

- src/client/ - 浏览器包（lib/client.js），由 tsc -p tsconfig.client.json && tsdown 编译（见 tsdown.config.ts）；注册为 settings.section 插槽，让 Web 设置页渲染配置表单。
- package.json - exports["./client"] + dsh.client（platform: "web"）是清单契约，dsh-client-modules 扫描它，把包纳入 window.__DSH_BOOT__。

开发

需要 Node.js 和 pnpm。工作区设置 nodeLinker: hoisted，并允许 esbuild 构建。

pnpm install
pnpm build # tsc (server) + tsc (client) + tsdown browser bundle
npx pnpm test # regenerates the @deepseek-ai/dsh-tools stub, then runs tests
npx pnpm typecheck # tsc --noEmit for both projects
npx pnpm check # build + test (CI uses this)

prepack 脚本会运行 pnpm build，所以发布的 lib/ 产物始终是最新的。测试放在 tests/.spec.ts 下，通过 tsx 用 node --test 运行。

交付说明

v0.6.3 敲定了 MVP：带预算的元数据索引召回、版本化更新（supersedes/supersededBy）、软删除/恢复加过期、可回滚的技能草稿（仓库 enabled/ 目录注册为 DSH 技能服务商）、block/redact/ask 隐私写入门禁，以及 memory_ 别名和会话启动时的 persona+warning 摘要。

验证：npx pnpm check（构建 + 测试；build 也会做类型检查）通过。

已知的非阻塞 TODO

- getMemoryIndex 在缓存命中时仍会重新遍历记忆根目录（正确性优先于速度）；基于 watcher 的廉价签名是后续工作。
- 隐私门禁覆盖记忆写入（writeMemoryRecord/updateMemory）；技能草稿写入（writeSkillDraft/saveSkillDraftFromRecord）有意放在门禁之外（已记录为仅限记忆的范围）。
- classifySensitivity 从不分配 internal；只有手工编写记录、把 frontmatter 写成该值时，才能触达 internal 导出级别。

许可证

MIT —— 见 LICENSE。