crwsr124/dsh-memflow

dsh-memflow

MEMFLOW 记忆流模式 —— DeepSeek Harness 的目录级上下文框架插件。

会话会结束，记忆不会：感知先行、边做边记、无缝续接。
目录即身份：.dsh/context.yaml 声明这个目录里「谁在工作」以及「开工前必须感知什么」。
记忆不是预设，是每个 agent loop 的基线要求。

English · 协议全文 · License

0.3.0 的前提变化

0.2.x 把记忆做成一个用户主动挑选的 preset：选了「记忆流模式」才有记忆。0.3.0 放弃了这个前提。

记忆与身份不是一种模式，而是每个 agent loop 的基线要求。

因此身份与感知的来源从「预设」下移到「目录」：每个工作目录用 .dsh/context.yaml 声明自己的 systemPrompt 与 preload，任何在该目录打开的会话都机械地获得这套上下文——web、headless、被调度的子 agent 一视同仁，不经过 preset 服务。

/.dsh/context.yaml
systemPrompt:            # 身份 / 协议 —— 作为 prompt section 注入
- AGENT.md
- ../shared/PROTOCOL.md
preload:                 # 感知 —— 作为会话首条 user message 注入
- memory/status.md
- memory/history.md
inherit: false           # 缺省；置 true 才向上合并祖先目录的声明（外层在前）

systemPrompt 文件在每次 prompt 组装时重新读取，改文件下一轮即生效；preload 文件拼成一条固定的首条 user message，每个会话只注入一次——感知先于第一个任务，且永不重投。

未声明的目录仍按 0.2.x 行为加载 memory/ 目录（legacy fallback），存量项目无需改动。声明存在时以声明为准。

声明路径变量（0.4.0）

声明被 git 托管、跨设备共享时，设备各自的记忆文件没法用一条静态路径写死。0.4.0 起声明路径支持两个内置变量：

/.dsh/context.yaml
preload:
- memory/${device}/status.md    # 每台设备各自的分区记忆

| 变量 | 解析值 |
|------|--------|
| ${device} | 从声明所在目录（.dsh 的上级）起向上逐级查找 .device 文件（上限 64 级），取首个命中文件的第一个非空行、trim 后的值；找不到或内容为空则回退到主机名去掉尾部 .local |
| ${hostname} | 主机名去掉尾部 .local |

解析顺序与规则：

- 替换发生在 resolveFrom 这个唯一咽喉点，对 systemPrompt 与 preload、声明来源与 DSH_CONTEXT_/config 来源的 extra 路径统一生效（extra 路径以会话工作目录为基准向上找 .device）。
- 每次组装都重新求值，不做缓存——与「声明文件每回合重读」的既有哲学一致；.device 是一行小文件，读取代价可忽略。
- 未知的 ${...} 保持字面量：不删除、不报错，下游读取时自然产生「无法读取」注记，响亮暴露拼写错误。
- 不支持 env 变量替换、glob、转义，也不引入通用 var 键——声明格式保持极小面。变量在路径上替换；文件内容不做任何替换。

一个协议、两个载具

| 载具 | 作用 |
|------|------|
| .dsh/context.yaml 声明 | 目录级身份与感知；显式写 inherit: true 才沿父目录向上合并（外层先注入） |
| DSH_CONTEXT_ 环境变量 | 调度方的按次通道：为某一次调度追加上下文、替换声明、或整体忽略声明 |

这里没有 {{memflow_protocol}} 变量，也是有意为之。 0.3.0 移除了「插件自带一份协议全文并注入每个 prompt」这条通道：协议属于工作目录，不属于插件。要什么身份，就在该目录的 .dsh/context.yaml 的 systemPrompt 里声明（WORKFLOW.md / AGENT.md / 你自己的协议文件）。包内 MEMFLOW.md 仅作参考实现与文档，不再进入任何 prompt——需要它就把它列进声明。

这里没有 delegate 工具，是有意为之。 被调度的子 agent 就是「在另一个目录里打开的一个会话」——调度方设定它的 cwd，它便从那个目录的声明里自己组装身份与感知，走的是与其它任何会话完全相同的代码路径。若再提供一条「把准备好的 dossier 递给子 agent」的通道，就等于用两套发散的机制说同一件事。

按次调度参数

目录声明的是默认身份，调度方还需要能收窄某一次运行。进程外（ACP）provider 无法下推 persona / outputSchema / toolFilter（subagent 服务在 start 之前就会拒绝），唯一能穿过进程边界的通道是子进程环境变量：

| 变量 | 作用 |
|------|------|
| DSH_CONTEXT_IGNORE=1 | 忽略所有声明（纯 headless，连 legacy memory/ 也不注入） |
| DSH_CONTEXT_FILE= | 用指定声明文件替代目录发现 |
| DSH_CONTEXT_SYSTEM_PROMPT= | 追加身份文件（换行或路径分隔符分隔） |
| DSH_CONTEXT_PRELOAD= | 追加感知文件 |
| DSH_CONTEXT_PARAMS= | 本次调度参数，原文注入，排序在所有身份 section 之后（因此可收窄它们） |
使用 DSH_ 前缀是有意为之：harness 的 scrubbedParentEnv() 会从环境继承中剥掉所有 DSH_ 名称，而显式 env 层在剥离之后合并——所以交给某个子 agent 的参数不会泄漏到它自己的孙 agent。按次调度真的只作用一次。

快速开始

安装（bundle 自动注册，首次需重启 dsh 进程加载）
dsh plugin --profile web add github:crwsr124/dsh-memflow
dsh plugin --profile headless add github:crwsr124/dsh-memflow

在项目里声明身份与感知
mkdir -p .dsh && cat > .dsh/context.yaml  0 的进程内子 agent 注入感知；默认注入，因为子 agent 与其它会话一样只是「某个目录里的一个会话」（旧名 includeDelegated: false 等价） |
| suppressRoots | [] | 抑制目录：这些项目根（按 .git 向上发现）完全不注入 |

0.3.0 移除了 protocolFile 与 rosterlessProtocol（协议全文通道已废，见上文）；配置里残留这两个键无害，会被忽略。

memoryPerFileBytes / memoryTotalBytes 作为 perFileBytes / totalBytes 的旧名仍被接受。

目录结构

/
├── .dsh/
│   └── context.yaml     # 身份与感知声明（0.3.0 起的入口）
├── AGENT.md             # 该目录的 agent 身份 / 协议（由声明引用）
└── memory/              # 持久记忆
├── tasks.md         # 任务清单与状态
├── status.md        # 项目现状快照
├── history.md       # 工作记录
├── notes.md         # 实操笔记与陷阱
├── brick_index.md   # 可复用技能索引
└── bricks/          # 可复用技能文档

实现说明

- 零 @deepseek-ai 依赖（有意为之）：profile 插件若携带与组合 row 重名的依赖（dsh-tools/dsh-subagent 等），会遮蔽 host row 的模块解析导致 Symbol 分裂、首次工具调用即崩。本插件全部走注入服务（ctx.tools / ctx.subagents / ctx.get('jobs') / ctx.systemPrompt），工具定义与 YAML 子集解析器均手写。
- stdout 属于协议：ACP 部署下 stdout 是 JSON-RPC 帧通道，插件从不写 stdout，诊断只走 ctx.logger。
- 感知是框架保证，不是模型自觉：感知消息由 agent/pre-step 瀑布机械注入（与 agent-instructions 同通道），去重依据是会话持久事件日志而非单轮 step。
- 声明解析出错不杀 loop：YAML 子集解析器带行号报错，loadDeclaration 捕获后告警并退化为「无声明」，不影响会话启动。
- 社区项目，与 DeepSeek 官方无隶属关系。

English

MEMFLOW — per-directory context composition for DeepSeek Harness (dsh).
0.3.0 改变了前提。 记忆与身份不再是用户选择的预设；它们成为每个 agent 循环的基线要求。一个目录声明谁在那里工作，以及在工作开始前必须感知到什么，而在该目录中打开的任何会话都会机械地获得该组合——无论是 web、headless，还是派发的 subagent，都不涉及名册。
yaml
/.dsh/context.yaml
systemPrompt: [AGENT.md]          # 身份 → 有序的提示词片段，每次组装时重新读取
preload: [memory/status.md]       # 感知 → 一条固定的首条用户消息，每个会话一次
inherit: false                    # 默认：不合并祖先；设为 true 以选择加入

0.4.0 为 git 共享、多设备声明添加了声明路径变量：
yaml
preload:
- memory/${device}/status.md

${device} 从声明目录向上查找第一个 .device 文件（≤64 层），并取其第一行非空内容，去除首尾空白；若缺失或为空，则回退到去掉 .local 后缀的主机名。${hostname} 始终是该短主机名。未知的 ${...} 保持字面量，并在下游作为不可读路径提示浮现。替换发生在 resolveFrom 中——这是声明路径与环境/配置提供路径共同的唯一咽喉点——并在每次组装时重新求值（无缓存）。无环境变量展开，无 glob，无转义。

调度器通过子进程的环境来细化单次运行——这是唯一能跨越进程边界的通道，因为进程外 provider 可能不会推送 persona：

DSH_CONTEXT_IGNORE=1              忽略声明（纯 headless）
DSH_CONTEXT_FILE=            使用此声明而非发现机制
DSH_CONTEXT_SYSTEM_PROMPT= 额外的身份文件
DSH_CONTEXT_PRELOAD=       额外的感知文件
DSH_CONTEXT_PARAMS=    本次运行的参数，原样注入

DSH_ 是有意选择的正确命名空间：harness 会从环境继承中剥离所有 DSH_* 名称，并在清理之后合并显式环境层，因此传给某个子进程的参数不会泄漏到该子进程自己的孙进程中。

没有声明的目录仍会机械地加载 memory/（0.2.x 行为），因此现有项目无需改动即可继续工作。

安装：
sh
dsh plugin --profile  add github:crwsr124/dsh-memflow

一个社区项目，与 DeepSeek 无关联。