@a9i5k4/dsh-auto-memory 2.2.2 → 2.2.4

package/docs/implementation-handoff-context.zh-CN.md

@@ -0,0 +1,429 @@
+# dsh-auto-memory 主动联想记忆实施交接上下文
+
+> 用途：将本文完整注入一个新的 DSH 编码会话，作为正式实现的起点。
+>
+> 工作区：D:\dsh-auto-memory
+>
+> DSH 原生实现只读参考：C:\Users\JH Z\AppData\Roaming\npm\node_modules\@deepseek-ai\dsh
+>
+> **2026-08-22 权威说明**：目标架构和实施进度以 `docs/proactive-associative-memory-system-map.html` 为准。本文第 8-13 节与第 14 节早期执行指令保留为历史记录；当前执行范围见 `docs/M4-CONTRACT.md`、第 14 节更新指令与 `docs/PREVIEW-NEXT-STEPS.md`。
+
+## 1. 你的任务
+
+在现有 dsh-auto-memory 插件上，分阶段实现“Host 侧主动联想记忆中间件”。
+
+目标不是让模型主动调用 memory_search，而是：
+
+~~~text
+Host 观察用户消息、工具调用/结果、可见输出和生命周期事件
+→ 按 session 隔离形成滑动上下文
+→ 主动检索可能相关的记忆
+→ 经过排序、去重、预算、风险和版本校验
+→ 生成 MemoryPacket
+→ 在下一次 agent/pre-step 请求边界注入
+→ 根据工具结果和用户纠正更新证据
+→ 必要时把重复成功 Episode 固化为 Procedure candidate
+~~~
+
+不要一次实现全部架构。M0-R/T0/M1/M2/P-A/M3a/M3b/M4/M5/M6 已完成并 live；M7 完整契约与研究报告已冻结，当前交给外部 Agent 实施，具体以 M7-AGENT-HANDOFF-PROMPT.md 为准。
+
+## 2. 开始前必须阅读
+
+按顺序阅读：
+
+1. docs/M7-PYTHON-IMPLEMENTATION-REPORT.md
+   - M7 算法选型、开源来源、许可证、benchmark 与阶段计划。
+2. docs/PYTHON-SIDECAR-CONTRACT.md
+   - M7 wire、index_sync、生命周期、安全和验收门。
+3. docs/M7-AGENT-HANDOFF-PROMPT.md
+   - 外部 Agent 执行入口。
+4. docs/proactive-associative-memory-system-map.html
+   - 当前权威系统架构图。浏览器直接打开；点击模块可查看概览、实现、依据、Meta 代码和验收条件。
+5. M5/M6 live modules：context-bridge/evidence/context-host/activation-inbox/state/host。
+   - 读取真实 wire 与 delivery/seen 语义。
+6. lib/index.js 与 M0-M6 smoke tests。
+   - 当前 Web UI。
+5. smoke-test.mjs、smoke-test-reflect.mjs、smoke-test-external.mjs
+   - 现有测试和历史契约，注意部分断言可能已经陈旧，修改前先验证。
+6. package.json、cordis.patch.yml
+   - 插件入口和包结构。
+
+阅读后再检查 git status。工作区可能已有用户改动和研究文件；不得回退或覆盖无关改动。
+
+## 3. 当前已经完成的内容
+
+M0-M6 已 live verified；M7 Python 尚未实现，以下交接文档和研究报告是外部 Agent 的实施依据。
+
+- 正式研究报告：docs/proactive-associative-memory-research-report.zh-CN.md
+- 交互式整体系统地图：docs/proactive-associative-memory-system-map.html
+- 早期长版架构页面：docs/proactive-associative-memory-architecture.html
+- 关键引用已审计：
+  - FLARE 正确编号为 arXiv:2305.06983。
+  - CoALA=2309.02427
+  - Generative Agents=2304.03442
+  - MemoryBank=2305.10250
+  - MemGPT=2310.08560
+  - A-MEM=2502.12110
+  - MemOS=2507.03724
+  - HippoRAG=2405.14831
+  - IRCoT=2212.10509
+  - DRAGIN=2403.10081
+  - Self-RAG=2310.11511
+  - Reflexion=2303.11366
+  - Voyager=2305.16291
+  - LongMemEval=2410.10813
+  - LoCoMo=2402.17753
+  - Proteus=2608.16844，仅作为“渐进式记忆激活”的概念启发，不得声称复现其具体算法。
+
+系统地图已经加入：
+
+- 稳定 memoryId/anchorId
+- MemoryFileIndex
+- read 返回内容 coverage
+- Access Evidence Graph：seen/read/cite/reuse/success/correction
+- Procedure：sourceMemoryIds/sourceEpisodes + 跨 session 成功晋升门
+- hesitation 滞回状态
+- Python activation_request
+- 渐进激活：index → hint → excerpt → checklist → resource → full
+- JS Host 权威 Safety Gate
+
+## 4. 原生 DSH 已确认事实
+
+这些是从本机 DSH 0.1.0-rc.7 构建产物核对出的实现事实：
+
+### 4.1 请求链
+
+~~~text
+claim
+→ systemPrompt.assemble
+→ runtime-context projection
+→ agent/pre-step waterfall
+→ step/start
+→ user/message append
+→ buildRequest
+→ LLM dispatch
+~~~
+
+已发出的模型请求不能被后续事件原地改写。主动记忆只能影响下一 step 或下一 turn。
+
+### 4.2 Session 与 Inbox
+
+- Session 是 append-only、连续 seq、lossless JSON 的可重放事实源。
+- Agent Inbox 是 durable projection，维护 next-turn 和 next-step。
+- inject：写入 next-step，但不唤醒 Agent。
+- steer：写入 next-step，并唤醒 Agent。
+- Inbox 的 splice、claim、replace、remove 都有持久事件语义，不是临时内存。
+
+### 4.3 dsh-agent-instructions 可借鉴骨架
+
+~~~text
+structured tools/result
+→ per-agent serial projection
+→ version/digest reconcile
+→ pending inbox
+→ pre-step await + compose
+→ next request
+~~~
+
+可借鉴：
+
+- WeakMap<agent, Promise> 串行 projection。
+- desired 已在 claimed 或 visible surface 时删除 pending。
+- 相同 pending 复用，旧 pending replace，多余 pending remove。
+- version + digest + visible/pending 状态共同去重。
+- UTF-8 byte budget 与模型 token budget 分开。
+
+### 4.4 systemPrompt 与 Minimal
+
+- systemPrompt section/context provider 是同步求值，不能在 section.text 内 await 异步检索。
+- Minimal preset：complete: true、includeRuntimeContext: false，默认只含持久 bash 和 str_replace_editor，也不挂载 dsh-agent-instructions。
+- complete persona 只限制 system-prompt sections，不等于禁止独立 user/message。
+- 若未来覆盖 Minimal，需要 dsh-auto-memory 自己提供 pre-step user/message 路径；不能假设 Minimal 已有该能力。
+
+### 4.5 tools/result
+
+- tools/result 是 frozen、emit-only、可重放的最终观察点。
+- Host 应抽取最小标量快照，不能保留或序列化整个 DSH 内部对象。
+- read 工具参数/返回结构需要 adapter，不要硬编码所有工具都拥有同一字段。
+
+## 5. 最终架构不变量
+
+所有实现必须持续满足：
+
+1. 跨 session 泄漏为零。
+2. 已发出的请求不原地改写，主动记忆只在下一请求边界生效。
+3. memoryId/anchorId 是稳定身份；行号仅是当前版本 UI/debug locator。
+4. sourceVersion + recordDigest 用于确认内容身份和新鲜度。
+5. open/read 不等于 citation；coverage=0 不形成记忆访问证据。
+6. Procedure 必须来自跨 session 的 reuse/success Episode，而不是 read 次数。
+7. activation_request 只是 Python 建议；最终由 JS Host 校验版本、scope、风险、冷却和 Procedure 状态。
+8. 过期或 contextVersion/indexVersion 不匹配的结果必须丢弃，不标记 delivered。
+9. 记忆是参考资料，不覆盖 system、developer 或当前用户指令。
+10. 未验证 Procedure 不自动执行；SSH、发布、部署、删除、支付等副作用默认需要用户确认。
+11. 检索中间态不写主 Session；只有实际注入的 packet 才进入可解释历史或审计。
+12. Python、embedding、图检索不可用时，基础插件与 JS 关键词回退仍可工作。
+
+## 6. 目标数据契约
+
+这些契约目前主要存在于系统地图的 Meta 代码中。里程碑 0 可以先在 JS 中建立最小版本，但不要过度设计。
+
+~~~ts
+interface EventEnvelope {
+  schemaVersion: 1
+  sessionId: string
+  agentId: string
+  eventSeq: number
+  turn?: number
+  step?: number
+  sourceKind: 'user' | 'tool' | 'agent' | 'lifecycle'
+  callId?: string
+  rootCallId?: string
+  payloadDigest: string
+}
+
+interface SessionRuntime {
+  sessionId: string
+  contextVersion: number
+  eventCursor: number
+  pendingPacket?: MemoryPacket
+  cooldownUntilStep?: number
+  lastInjectionAt?: number
+}
+
+interface MemoryLocator {
+  memoryId: string
+  anchorId: string
+  sourceFile: string
+  sourceVersion: number
+  lineStart: number
+  lineEnd: number
+  byteStart: number
+  byteEnd: number
+  recordDigest: string
+}
+
+type AccessKind = 'seen' | 'read' | 'cite' | 'reuse' | 'success' | 'correction'
+
+interface AccessEvidence {
+  kind: AccessKind
+  memoryId: string
+  anchorId?: string
+  sessionId: string
+  callId?: string
+  sourceFile?: string
+  coverage?: number
+  contextVersion: number
+  sourceVersion: number
+  recordDigest: string
+  timestamp: number
+}
+
+type ActivationLevel = 'index' | 'hint' | 'excerpt' | 'checklist' | 'resource' | 'full'
+~~~
+
+当前阶段不需要一次把所有接口正式导出，也不要引入 TypeScript 构建链；可以继续使用现有 ESM JavaScript，并用清晰的 JSDoc typedef 或内聚的小类表达。
+
+## 7. 最终完整路线，但本轮不要全部实施
+
+~~~text
+M0 基线开关与数据契约
+M1 SessionRuntime / per-agent isolation
+M2 ContextObserver / 结构化事件
+M3 Markdown Anchor + MemoryFileIndex
+M4 Shadow Retrieval
+M5 Access Evidence Graph
+M6 InjectionBroker + pre-step Soft Injection
+M7 Python sidecar / embedding / graph
+M8 Semantic/Profile candidates
+M9 Procedure promotion
+M10 Provider reasoning adapter
+M11 Streaming abort/resume experiment
+~~~
+
+## 8. 本次新会话只实施的范围
+
+### 里程碑 0：基线、配置与内部契约
+
+目标：为后续功能建立可关闭、可测试、不会改变现有行为的骨架。
+
+必须完成：
+
+1. 扩展 DEFAULT_CONFIG，新增默认关闭的实验配置：
+
+~~~json
+{
+  "associativeMemoryEnabled": false,
+  "shadowRetrievalEnabled": false,
+  "softInjectionEnabled": false,
+  "pythonBackendEnabled": false,
+  "reasoningObserverEnabled": false,
+  "procedurePromotionEnabled": false,
+  "streamingInterruptionEnabled": false,
+  "maxPacketItems": 2,
+  "maxPacketChars": 800,
+  "packetTtlSteps": 2,
+  "injectionCooldownSteps": 3
+}
+~~~
+
+注意：配置全部关闭时，现有插件行为必须逐字节兼容当前逻辑。
+
+2. 在 lib/index.js 内新增最小、内聚的运行时结构：
+
+~~~text
+SessionRuntimeStore
+  Map 或 WeakMap 管理 per-agent/session 状态
+  get(agent)
+  dispose(agent)
+  disposeAll()
+~~~
+
+3. 定义内部的 EventEnvelope、SessionRuntime、ContextSegment、MemoryPacket 最小契约。
+4. 加入只记录、不检索、不注入的调试状态字段，供后续 smoke test 检查。
+5. 将所有新状态初始化和清理挂入 Cordis 生命周期；插件 dispose 时清空。
+6. 不添加 Python、不添加 embedding、不修改 Markdown 格式、不注入新消息。
+
+### 里程碑 1：会话隔离
+
+目标：消除当前进程级状态在并发会话下串线的风险。
+
+重点检查并逐步替换这些进程级状态：
+
+- engine.state 中与当前 workspace/agent 强耦合的动态状态
+- engine._lastAgent
+- engine._consolidating
+- engine._pendingConsolidations
+- engine._lastTurnByAgent
+- 自动沉淀和刷新路径中的 agent fallback
+
+本阶段不要求一次重写整个 MemoryEngine。优先做最小安全改造：
+
+1. SessionRuntimeStore 以 Agent 或 sessionId 为键。
+2. agent/session-start 时建立 runtime。
+3. agent/pre-step 和工具执行时通过当前 agent 精确取 runtime。
+4. agent/turn-stopping payload 不保证有 agent，不能继续依赖全局 _lastAgent 推断当前会话。
+   - 需要核对 DSH 可用的 agent/session 生命周期和当前插件监听上下文。
+   - 若该 hook 无法可靠获得 agent，设计显式的 per-agent turn tracking 或换用拥有 agent 的邻近事件。
+   - 不允许在并发会话下猜测最近 Agent。
+5. 自动沉淀队列按 session 隔离。
+6. agent dispose / session dispose / plugin dispose 时清理 runtime 和异步任务。
+7. 添加至少两个并发顶层 agent/session 的隔离测试。
+
+## 9. 本次明确禁止实现的内容
+
+在里程碑 0/1 验收前，不要实现：
+
+- Python worker 或虚拟环境初始化
+- embedding / vector database
+- MemoryFileIndex 和 Markdown anchor 写入
+- read coverage 解析
+- Access Evidence Graph
+- Procedure 自动抽取或 skill 文件生成
+- reasoning trace 观察器
+- 自动 pre-step MemoryPacket 注入
+- 流式中断、steer 或 abort/resume
+- UI 大改
+- npm 发布、GitHub 推送、tag 或版本发布
+
+这些属于后续阶段，先保证会话隔离和关闭时零行为变化。
+
+## 10. 测试和验收
+
+至少需要：
+
+1. 当前功能回归：
+   - 现有 memory 工具仍可注册和执行。
+   - renderMemory 行为不变。
+   - 自动沉淀在单会话下保持当前结果。
+   - 路由和 GUI state/config 返回仍兼容。
+2. 新配置：
+   - 缺省全部实验开关为 false。
+   - 配置保存/加载只接受 DEFAULT_CONFIG 白名单。
+   - 关闭时不产生新的 model-visible 文本。
+3. SessionRuntime：
+   - A/B 两个 session 使用不同 runtime。
+   - A 的 cwd、contextVersion、pending 状态不出现在 B。
+   - 清理 A 不影响 B。
+4. 自动沉淀：
+   - A/B turn 去重独立。
+   - A 的沉淀任务不会读取 B 的 Agent 或 workspace。
+5. 编码：
+   - 所有改动保持 UTF-8 无 BOM。
+   - 完成后检查修改文件头不是 EF BB BF。
+
+建议先运行：
+
+~~~powershell
+node --check lib/index.js
+node --check lib/client.js
+node smoke-test.mjs
+node smoke-test-reflect.mjs
+node smoke-test-external.mjs
+~~~
+
+如果旧 smoke test 因历史数量断言过时，先说明并只修正与当前真实注册契约一致的断言，不要为了让测试绿而倒退当前功能。
+
+## 11. 实施方式要求
+
+1. 先检查 git status 和现有改动，不回退任何用户文件。
+2. 先读代码，再决定最小修改面；不要重写整个 2,000+ 行文件。
+3. 优先抽出小型内部 helper/class，但不要过度抽象。
+4. 每完成一个子步骤立即运行相关测试。
+5. 新功能默认关闭，先验证关闭路径。
+6. 修改后检查无 BOM。
+7. 不启动替代 dsh web 服务。
+8. 如需要在现有 Web GUI 验证：修改 apps/web shell 以外的插件代码后，按当前 DSH 运行规则重建/重载并刷新 http://127.0.0.1:3080；不要承诺 HMR，除非确认同一 checkout 的 pnpm run dev:web watcher 正在运行。
+9. 未经用户明确要求，不发布 npm、不推 GitHub、不创建 tag。
+
+## 12. 子代理纪律
+
+可以使用子代理，但必须受控：
+
+- 研究/审查默认最多并行 2 个一级子代理。
+- 每个子代理提示必须明确：禁止创建 subagent、subagent_fork、workflow 或 Ralph。
+- 必须等待同一批返回并提炼后，才决定是否继续下一批。
+- 不允许递归套娃。
+
+本次 M0/M1 实现范围较集中，优先由主 Agent 直接完成；若委派，只委派“原生生命周期核对”或“并发隔离测试审查”中的一个独立任务。
+
+## 13. 完成后汇报格式
+
+最终回复必须说明：
+
+- 改了哪些文件
+- M0/M1 分别实现了什么
+- 哪些风险仍未解决
+- 跑了哪些测试及结果
+- 是否验证无 BOM
+- 是否更改了 model-visible 行为
+- 下一里程碑建议
+
+## 14. 当前新会话的第一条执行指令（2026-08-23 更新）
+
+请按以下顺序开始：
+
+1. 首先读取 `docs/proactive-associative-memory-system-map.html`、`docs/M7-PYTHON-IMPLEMENTATION-REPORT.md`、`docs/PYTHON-SIDECAR-CONTRACT.md` 和 `docs/M7-AGENT-HANDOFF-PROMPT.md`；目标架构和进度以 system-map 为准。
+2. 再读取 `docs/M5-CONTRACT.md`、`docs/M6-CONTRACT.md`、M5/M6 live JS modules 和 smoke tests，运行 `git status --short --branch`；保留全部无关或未跟踪文件。
+3. 只读核对 `lib/index.js`、context-bridge/evidence/context-host、activation-inbox/state/host 及 M3/M4 provenance；M7 不重写 M5/M6 wire 或 delivery semantics。
+4. M0-R/T0/M1/M2/P-A/M3a/M3b/M4/M5/M6 已完成并 live；M7-0 完整契约已冻结，当前交给外部 Agent 按 M7-0→M7-8 实施，默认关闭。
+5. 预览版所有对外注册与持久化标识必须使用 `_pre`/`-pre`，禁止 `_dev` 或无后缀标识与稳定版碰撞。
+6. M2/M5/M6 的 event、scope、provenance、contextVersion、ActivationRequest 与 delivery/seen 是兼容基线；M7 不修改现有 JS validator 或 M6 投递路径。
+7. M7 必须通过 index_sync 获取完整授权语料；Python 不读 DSH 文件、不创建 evidence、不写 prompt/Packet；失败回退 lexical_pre_v2。
+8. 测试和编码检查通过后，必须回写系统地图 progressLedger 和相关模块证据；不发布、不 push、不 tag。
+
+## 15. M0/M1 后维护状态
+
+- 已完成缓存稳定性维护：稳定记忆纪律保留在 `systemPrompt.section()`，动态工作区记忆使用原生 `systemPrompt.context()` runtime-context projection。
+- 动态快照由 DSH 原生 projection 按完整文本比较；相同快照不重复创建 user-context，变化快照替换之前的 projection。
+- f00ad23 已落地 M1：SessionRuntimeStore、AsyncLocalStorage、per-runtime 自动沉淀状态与并发隔离测试。
+- v0.1.29 合并后 M0 的 7 个实验开关与 4 个 packet 预算参数曾从 DEFAULT_CONFIG 丢失；该问题已由 M0-R 在 M2 前恢复并通过回归。
+- 当前预览身份使用 `dsh:auto-memory-pre`、`dsh:auto-memory-pre-rules` 和 Agent 可见 `memory_*_pre` 工具；所有对外注册、API/config/cache/log/localStorage 等持久化命名空间必须保持 `_pre`/`-pre`，不得重新引入 `_dev` 或稳定版无后缀冲突标识。
+- 当前维护改动没有启用主动检索、Python、embedding、MemoryPacket、流式中断或自动阈值注入；这些仍属于后续里程碑。
+
+## 16. 架构权威与进度纪律
+
+- `proactive-associative-memory-system-map.html` 是目标架构、模块契约、架构不变量和实施进度的唯一权威。
+- 研究报告负责理论依据、相关工作、风险与总路线；architecture/meta-code HTML 是辅助视图，不得覆盖系统地图的后增契约。
+- 当前实现事实由 `lib/index.js`、本机 DSH 类型和测试证据确认。工程审查补充必须明确标注，不能冒充论文原文。
+- Python sidecar 的完整 M7 架构、JSONL 协议、JS Host 权威边界和压缩恢复顺序固定在 `docs/PYTHON-SIDECAR-CONTRACT.md`；M7 必须等待 M3b/M4/M5/M6，当前不得启动 Python worker。
+- 每个里程碑完成后必须在同一轮更新系统地图的 progressLedger、相关模块实现证据、验收结果和日期；聊天或记忆中的完成声明不能替代 HTML 进度。