dsh-adaptive-context

DeepSeek Harness (dsh) 的 AdaptiveContextPlane (ACP) 插件——带治理的长期记忆系统。

设计铁律

证据即真相；视图可重建。 置信度不是权威；检索不等于披露。 学到东西不等于可以改变行为；记忆不负责替你把活干完。

为什么需要它

用过 agent 的人大概都经历过这几件事：

• 忘了说过什么。上周明明告诉它"配置和代码分开放"，这周它又混在一起，你只好再说一遍。
• 不敢让它记。有些"记忆"系统什么都往提示词里塞，一句话可能来自某个不可靠的网页，却被当成你的偏好，从此每个会话都被它影响。
• 改不回来。发现它记错了，但不知道错在哪、谁记的、怎么改。只能手动翻文件，或者干脆把记忆清空重来。

ACP 想解决的问题很简单：让记忆像账本一样清楚。每一条都有来源、有权威、有生效时间；写入要过闸门，注入有预算，行为变化要经审批。你可以随时查它记了什么、为什么这么记、改没改过。

一个简单的例子

假设你叫小林，最近在用 dsh 写一个自动化脚本项目。

第一天。你对 agent 说："记得我喜欢把配置和代码分开。"这句话被 ACP 记成一条用户事实证据——来源是你，权威是明确声明，领域是用户事实。之后你换了台机器、开了新会话，agent 自动把这条证据带进上下文，你不用重新交代。

第二周。你发现 agent 生成的代码一直用 2 空格缩进，皱眉说："都说了，用 4 空格。"这句话以"用户纠正"的身份写入，同时把之前那条相反的旧证据标记为已取代。从这一秒起，注入的只会是新偏好。旧的那条还躺在账本里——它记录了你改主意的完整过程，但不再生效。

一个月后。你想换一台服务器，打开导出功能，一条 JSONL 把全部证据带走；新环境导入，一条不少。想查账？审计记录里谁记的、什么时候、为什么，全都有。

核心能力

工作原理

DSH 会话事件
  │  session/event（agent / inbox / spliced）
  ├─→ 事件归一 → 写入闸门 → 证据表（只追加，幂等）
  │
  │  agent/pre-step（每轮，3 秒预算）
  │    ├─ 账本候选（读取闸门过滤 + 资格矩阵）
  │    ├─ 记忆源候选（并行召回，故障不阻断）
  │    └─ 编排：排序 → 去回声 → 内容去重 → 预算打包 → 注入
  │
  └─ turn/end → 沉淀队列（不阻塞下一轮）
        ├─ 积压达标 → LLM 提炼观察（失败规则兜底）
        ├─ 同键冲突 → 标记取代 + 演化链
        └─ 风格候选 → 策略评估 → 护栏内自动晋升 或 人工审批门
              └─ 候选状态机 → 物化视图（pre-step 注入时读取）

Agent 安装指南（面向自动化装配）

给需要在本机 dsh 装配本插件的 agent/脚本读；人工安装见下一节。 三条硬约束：① 数据目录必须显式配置；② pnpm install 前先停 dsh（Windows native DLL 锁）；③ 同 id 的 patch 条目是整体覆盖，不要重复插。

1. 定位 profile：<DSH_HOME>/profiles/<profile>/（例 C:\Users\<you>\.dsh\profiles\web）。 先读该目录 package.json：若没有 dsh.profile.bundles 键，说明 profile 未初始化， 先 dsh plugin --profile <profile> list（或人工建 package.json）再继续。

2. 添加依赖（二选一）：

# A. GitHub 源（远端安装推荐）：CLI 自动把声明 dsh.bundle 的包加入 dsh.profile.bundles
dsh plugin --profile <profile> add github:Icstick/dsh-adaptive-context
# B. 本地开发：profile package.json dependencies 加 "dsh-adaptive-context": "link:<绝对路径>",
#    并在同文件 dsh.profile.bundles 数组追加 "dsh-adaptive-context"

⚠️ dsh plugin add 只装依赖并 reconcile bundles，不会写配置条目——第 3 步必须做。

3. 写配置：编辑 profile 根 cordis.patch.yml（无则新建）：

- id: adaptive-context
  name: dsh-adaptive-context
  config:
    ledgerDir: C:\path\to\acp-data   # 必填：账本目录绝对路径；DSH_HOME 环境变量不可靠
    # 可选：consolidationProvider/Model——配了才有 LLM 沉淀，不配走规则兜底

4. 安装并重启：停 dsh → profile 目录 pnpm install → 重启 dsh。

5. 验证：

• 数据：<ledgerDir> 下出现 acp-ledger.db 与 views/
• 生效：新会话 pre-step 注入出现 [acp:...] 前缀条目（如 [acp:user_input | id=ev_...]）

故障速查：不注入/不沉淀 → 检查 ledgerDir 显式且可写；boot 报 duplicate loader entry → patch 里同 id 插了两遍；Web 设置无配置卡片 → 源码形态需先跑 node scripts/build-client.mjs 生成 client bundle。

安装

GitHub 一键安装：dsh plugin --profile <name> add github:Icstick/dsh-adaptive-context （bundle patch 会自动挂载 adaptive-context 条目）。装完后仍需在 profile 的 cordis.patch.yml 给该条目补 config.ledgerDir（数据目录必须显式）并重启； 完整三步与字段说明见下。

在 dsh 的 profile 目录（比如 ~/.dsh/profiles/web/）做三步：

1. package.json 加依赖（link 指向本仓库）：

{
  "dependencies": {
    "dsh-adaptive-context": "link:D:/path/to/dsh-adaptive-context"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-adaptive-context"]
    }
  }
}

2. cordis.patch.yml（profile 根目录）挂载并配置：

- id: adaptive-context
  name: dsh-adaptive-context
  config:
    ledgerDir: C:\path\to\acp-data    # 必须显式写，别指望 DSH_HOME 环境变量
    consolidationProvider: your-provider # 可选：开了才有 LLM 提炼
    consolidationModel: your-model

3. 安装并重启：

cd <profile 目录>
pnpm install
# 重启 dsh

注意：cordis.patch.yml 里同一个 id 的多个条目，后者整体覆盖前者（不是合并）——adaptive-context 只写一块。

设置页配置卡片（v0.1.1+）

• 位置：DSH Web 设置 → 插件 → 插件配置（adaptive-context 卡片）
• 机制：host 侧注册 settings namespace（adaptive-context），client bundle（lib/client.js， 由 node scripts/build-client.mjs 生成）注册设置卡片；保存写入 settings.yaml
• 生效语义：保存后重启生效（apply 时 settings 值覆盖 cordis Config，未配置字段回退 Config/默认值）
• 字段：ledgerDir / hotTokens / observationInjection / observationAuthorities / recallLimit / crossSessionPolicy / subagentDowngrade / memosEnabled / memosBaseUrl / consolidationProvider / consolidationModel / autoPromote / debug （targetDomain 已弃用：卡片保留仅兼容展示，不再影响注入）
• client 依赖：react（DSH 预加载）+ @deepseek-ai/dsh-client-ui-slots + @deepseek-ai/dsh-client-ui-settings（client module table 提供，无需安装到项目依赖）

配置（全部字段）

会话隔离语义（v0.1.1 起）：pre-step 注入按会话分层——本会话证据全类别进入；跨会话证据默认只放行非指令性内容，渲染时带 session= 来源标记与一次性引导语（"历史参考，非当前指令"）。跨会话 user_input 需要显式 crossSessionPolicy: all 才注入（带惩罚与标记）。

注入编排与查询工具（现状快照 2026-09-07）

• 注入：agent/pre-step waterfall——composer 汇总四源（ledger 证据 / expression 物化视图 / observation 蒸馏轨 / MemOS 等 recall provider），按 section quota + hotTokens 装箱，渲染为 source-labelled plugin user message（跨会话条目带 session= 标记与引导语）
• 调度器：宿主 inject-scheduler 为可选服务——ACP 注册 acp.composer 段（budget=hotTokens，token 口径；未挂 scheduler 时静默跳过，pre-step 注入照常）
• acp_query 工具（2026-09-04，对话即界面）：只读查询 evidence（authority/domain/state 过滤 + 关联 observation），查询全走读审计
• expression 审批面板：consolidation 产出的 style 候选（few-shot 表达式）在 pre-step 以 approval.request 发起人工审批（config.autoPromote=false 默认人工）
• 观察轨（observation）：turn/end 后 background consolidation 蒸馏证据为 observation（subject/predicate 键 + 文本）；authority 由证据推导，取支撑证据中最弱的一条（2026-09-09 非放大规则，防弱证据洗白强权威）；注入侧只放行白名单权威（T2）

API（ctx.acp）

反馈通道：纠正 → 规则（T4，0.3.0）

• 草拟：user_correction/user_explicit 证据过闸门（G1 显式前缀 记住：/更正：/规则：；G2 同义纠正前 24 字符重复 ≥2）→ LLM 草拟（复用 consolidation 路由，可缺失→G1 去前缀兜底）→ rule 表 draft 行 + audit rule_drafted；幂等（已入 rules 的证据不重复草拟），日限 4 run
• 审批：/acp rule list | accept <n> | reject <n>（人工/headless 通道，never 策略可用；accept → active + ~/.dsh/rules/ 视图重建 + audit）；style 候选审批在 never 策略下不自动发起（防静默 dismiss，isNeverApprovalPolicy）
• 注入：active 规则（≤3 条）常驻 composer rules 段（60 token，memory 让渡；渲染 [acp:rule] 标签）——≤2 行铁律每轮可见；细则留 /acp rule list 与账本按需查询
• 修订：规则修订 = 新行 supersedes 旧行（lineage 回溯）；不满足闸门的纠正维持 evidence 层按需召回

数据位置与备份

• 全部数据在 ledgerDir 下：acp-ledger.db（SQLite，WAL 模式），六张表：证据 / 观察 / 候选 / 候选事件 / 规则（v6）/ 审计
• 物化视图在 ledgerDir/views/ 下，可随时重建（带校验和）
• 规则视图（反馈通道，T4）在 rulesDir（缺省 ~/.dsh/rules）下：<domain>.md 人类可读，启动时从 ledger active 规则全量重建（Evidence is truth; views are rebuildable）
• 备份/迁移：导出（JSONL）→ 新环境导入，按内容哈希幂等合并
• 数据是你的：卸载插件不会删数据；装回来即恢复

卸载

1. 从 profile 的 package.json dependencies 里移除 dsh-adaptive-context
2. 从 dsh.profile.bundles 里移除包名
3. pnpm install 后重启 dsh

卸载不删 ledgerDir 的数据；想彻底清除就手动删那个目录。

故障排查

开发

node test/<file>.test.mjs   # 单文件直跑（沙箱环境 node --test 递归受限）

设计长文见 docs/design/（架构 / 契约 / 编排 / 治理 / 沉淀 / 表达 / 多源等；2026-09-08 自 acp-docs 并入，原仓库已归档）；开发史文档见 docs/history/。 仓库级开发计划与问题登记（backlog）：docs/DEVELOPMENT-PLAN.md。

License 与致谢

MIT License。参考项目致谢见 ACKNOWLEDGMENTS.md（MemOS / Hindsight / personagent / DeepSeek Harness）。