HologramAgent-DSH-Memory-Port/docs/shadow-context.md

# 影子上下文（Shadow Context）方案在 dsh 上的可行性核实

> 状态：**调查，不含实现**
> 目标：核实两条路 —— ①「劫持/外挂 dsh 原有信息流」；②「独立注册一种 agent 模式」
> 宿主：dsh（deepseek-harness）`0.2.1-rc.2`，cordis `4.0.5`
> 取证：只读 `lib/*.d.ts` 权威类型 **并** 核对 `lib/*.js` 真实实现。每条结论标注 `文件:行`。

---

## 结论（先给答案）

| 路线 | 可行？ | 一句话 |
|---|---|---|
| **② 注册一种 agent 模式** | ✅ **真正可行，且是官方支持的一等机制** | `agentPresets` 注册表 + `cordis:group` + `isolate`。现有 preset 已经在用 `isolate: {compaction: true}` 挂自己的 compaction（`dsh-web-app/presets/standard.patch.yml:66-82`）。这是 dsh 设计时就留好的口子。 |
| **① 劫持/外挂原有信息流** | ⚠️ **看着可行，实际是三条不同成熟度的路拼起来的** | `agent/pre-step` 能改本轮进模型的消息但**改不了持久面**（loop 随后 `session.append`，`dsh-agent-loop/lib/index.js:1067-1073`）；`llm/stream` 能做最终请求改写但它收到的 `GenerateOptions` 对 loop 请求**是深冻结的**（`dsh-llm/lib/types/index.d.ts:36-42`）；真正干净的「替换 compaction」只能走 ②（isolate realm），单独做会撞 `service "compaction" has been registered`（`cordis/lib/index.js:814`）。 |

**推荐**：走 ②。它是唯一能同时满足「不碰 dsh 内核」「不伪造持久面」「语义可解释」的路。

**硬阻塞**（两条，与路线无关）：

1. **`surface replace` 只能替换已存在的 surface 节点，且必须覆盖全部被遮蔽节点**（`dsh-session/lib/index.js:314-332` 的 `assertSourceEventReferences`）。所以「把某段历史整体换成影子版本」在 surface 上可行，但**换掉的那些节点必须逐一列进 `sourceEventSeqs`**，且被换掉的事件仍在 append-only 日志里。
2. **日志 seq 必须严格连续**（`dsh-session/lib/index.js:426`）。任何「删除/重排事件」的想法都会在 replay 时炸。影子副本**只能完全活在 dsh 之外**，不能写回日志。

---

## 1. 用户输入 → 模型调用的完整链路

### 1.1 六个环节（按执行顺序）

```
用户输入
  ↓ ① inbox 暂存
agent.inbox / ReactLoopInbox
  ↓ ② claim + 组装
preStep()                      ← systemPrompt.assemble() 在这里
  ↓ ③ waterfall: agent/pre-step  ← 插件可改 decision.messages
  ↓ ④ turn/start + step/start   ← 写日志（边界事件）
  ↓ ⑤ step(decision)
      ├─ prepareRequest()       ← waterfall: agent/request（只能换 provider/model）
      ├─ systemPrompt.project() ← 决定 system message 怎么进 surface
      ├─ session.append("user/message", ...)  ← ★ decision.messages 在这里落盘
      ├─ buildRequest()         ← session.deriveMessages() 派生 LLM 消息
      └─ llm.stream(request)    ← waterfall: llm/stream（最终请求）
```

### 1.2 逐环节的代码位置与读写边界

| # | 环节 | 位置 | 插件能做什么 | 能改持久面吗 |
|---|---|---|---|---|
| ① | inbox 暂存 | `dsh-agent-loop/lib/index.js:907` `this.inbox.claim(target, position.turn)` | 只能通过 `agent.followup/steer/inject` 间接写 | ❌ |
| ② | prompt 组装 | `dsh-agent-loop/lib/index.js:907` `await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal))` | `systemPrompt.section/context/tools/variable` 注册；`system-prompt/assemble` waterfall 可改整个 `PromptAssembly` | ❌（只影响本次组装） |
| ③ | **pre-step waterfall** | `dsh-agent-loop/lib/index.js:909-919` | **可整段替换 `decision.messages`**，或 `{kind:'reject'}` 拒绝本步 | ⚠️ 不能直接改日志，但**返回值会被 loop 落盘** |
| ④ | 边界事件 | `dsh-agent-loop/lib/index.js:987` `session.append("turn/start", {turn})` / `:997` `step/start` | 无钩子 | — |
| ⑤a | `agent/request` | `dsh-agent-loop/lib/index.js:1197-1201` | waterfall 返回 `LlmCallConfig`，但**只有 `provider/model/reasoningEffort/temperature/maxTokens/stop`**（`dsh-llm/lib/types/call-config.d.ts:22-26`），**没有 messages** | ❌（明确写了「this waterfall cannot mutate messages」） |
| ⑤b | **surface 落盘** | `dsh-agent-loop/lib/index.js:1067-1073` | 无钩子。`decision.messages` 逐个 `session.append("user/message", ..., {surfaceOp:"append"})` | ✅ **但这是 loop 干的，不是插件** |
| ⑤c | 派生 LLM 消息 | `dsh-agent-loop/lib/index.js:1274` `const boundaryMessages = session.deriveMessages()` | **只读 surface，不看 inbox，也不看你 plugin 的内部状态** | — |
| ⑤d | **llm/stream** | `dsh-llm/lib/index.js:2397` `this.ctx.waterfall(this, "llm/stream", options, () => this.adapterStream(...))` | **可 yield 自己的 chunk 短路，或包一层** | ❌（不改日志） |

### 1.3 ★ 关键发现：pre-step 的改动**会被持久化**

这一点决定了「影子上下文」能不能不落痕迹。看 `step()` 的落盘段（`dsh-agent-loop/lib/index.js:1066-1073`）：

```js
let contextAdmitted = false;
if (firstAttempt) for (const message of decision.messages) if (message.source.kind === "runtime-context") {
    if (context !== void 0 && !contextAdmitted) {
        this.session.append("user/message", context, { surfaceOp: "append" });
        contextAdmitted = true;
    }
} else this.session.append("user/message", message, { surfaceOp: "append" });
if (context !== void 0 && !contextAdmitted) this.session.append("user/message", context, { surfaceOp: "append" });
```

⇒ **你在 `agent/pre-step` 里返回的每一条 message，都会变成 `user/message` 事件永久写进会话日志**，
并进入下一次 `deriveMessages()`。

所以「影子上下文」如果靠 pre-step 注入，**注入的内容就成了真实历史**——它不是影子，是正文。
要做到「只在本次请求存在、不留痕」，pre-step 是错的钩子。

### 1.4 pre-step 能否「删掉」消息？

能，但有代价。`PreStepDecision.messages` 是**替换**语义（`dsh-agent/lib/types/runtime-types.d.ts:92-99`）：

```ts
export type PreStepDecision = { kind: 'reject' } | {
    kind: 'enter';
    messages: UserMessage[];
    startsRequestSeries?: true;
};
```

`messages` 是「进入本步的消息列表」的完整替换。**但注意**：它替换的是 **inbox 里刚 claim 出来的那几条**
（`claimed = this.inbox.claim(...)`，`index.js:907`），**不是整个 surface 历史**。
历史早已在之前的 step 里 append 完了，改不了。

⇒ pre-step 的能力边界：**能改「本轮新进的消息」，不能改「已经进过日志的历史」**。
想改历史只能走 surface replace（§3），而那就是 compaction 干的事。

### 1.5 全部可介入的 waterfall/hook 点（完整清单）

| 事件 | mode | 位置（类型定义） | 能否改消息 | 能否改请求 |
|---|---|---|---|---|
| `system-prompt/assemble` | waterfall | `dsh-system-prompt/lib/types/index.d.ts:27` | 间接（改 sections） | ❌ |
| `agent/pre-step` | waterfall | `dsh-agent/lib/types/runtime-types.d.ts:304` | ✅ 本轮新消息 | ❌ |
| `agent/request` | waterfall | 同上 :327 | ❌ | ✅ 但只有 config 标量 |
| `agent/request-error` | waterfall | 同上 :348 | ❌ | 只能 `{kind:'retry'}` |
| `agent/turn-stopping` | serial | 同上 :387 | 只能 `agent.steer()` 追加 | ❌ |
| `agent/created` / `disposed` / `status` | serial / emit / emit | 同上 :227 / :240 / :252 | ❌ | ❌ |
| `agent/inbox/inserted` / `claimed` / `discarded` | emit | 同上 :263 / :277 / :289 | ❌（只读通知） | ❌ |
| `agent/assistant-stream` | emit | 同上 :366 | ❌ | ❌ |
| `tools/pre-execute` / `execute` / `post-execute` / `result` | waterfall×3 / emit | `dsh-tools/lib/types/index.d.ts:47 / :58 / :70 / :92` | ❌ | ❌ |
| **`llm/stream`** | **waterfall** | `dsh-llm/lib/types/index.d.ts:45` | ❌ | ✅ **最深**，但见 §1.6 |
| `session/event` | emit | `dsh-session/lib/types/index.d.ts:61` | ❌ | ❌ |
| `session/flush` | parallel | 同上 :69 | ❌ | ❌ |

**没有**「上下文即将超限」事件，**没有**「请求消息即将发送」的可改写 waterfall（除了 `llm/stream`）。

### 1.6 `llm/stream` 的读写边界（最深的口子，但有硬约束）

签名（`dsh-llm/lib/types/index.d.ts:45`）：

```ts
'llm/stream'(this: LlmRuntime, options: GenerateOptions,
             next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
```

契约原文（同文件 `:36-42`）：

> `options` - the full request. A LOOP-built request carries the process-local
> `markAgentLoopRequest` identity and **arrives deep-frozen (mutation throws)**:
> its content is a pure function of the session log (the reconstructability
> Agent Note), **so listeners read it, never rewrite it.**

⇒ **对 loop 发起的请求，`options` 是深冻结的，改不了 `messages`**（改会抛）。
你能做的只有两件事：

1. **短路**：不调 `next()`，自己 yield chunk 流（伪造回复）—— 但那样 assistant message 会进日志，且内容与真实模型无关。
2. **包一层**：`yield* next()` 前后做观测/计时（`dsh-session-checkpoint-policy/lib/index.js:61-65` 就是这么用的）。

**要真正改请求**，必须自己**重新拼一个 `GenerateOptions`** 然后交给 `ctx.llm.stream(shadowOptions)`——
但那是**另一次模型调用**，它产生的 assistant message 会以新的 `assistant/message` 事件进日志。
即：**你没法让 dsh「用影子上下文调模型，然后把结果当成这次的真实回复」而不留痕**，
除非你自己接管 ⑤a~⑤d 全部（= 自己实现 runner，见 §5）。

---

## 2. `compactSurfaceRegion` / `CompactionTrigger` 的精确签名与替换可行性

### 2.1 精确签名

**服务抽象**（`dsh-compaction/lib/types/index.d.ts`）：

```ts
export type CompactionTrigger = 'pressure' | 'context-overflow';   // :25

export declare abstract class CompactionEngine extends Service {   // :~100
  abstract compactIfNeeded(agent: CompactionAgentContext,
      trigger: CompactionTrigger,
      signal: AbortSignal): Promise<CompactionResult | null>;
  abstract compactNow(agent, signal, sourceCommandId?): Promise<CompactionResult | null>;
  abstract compactRegion(start: SessionSeq, end: SessionSeq,
      agent: Agent, signal?: AbortSignal): Promise<CompactionResult>;
}
```

服务注册名由基类构造函数固定（`dsh-compaction/lib/index.js:169-173`）：

```js
var CompactionEngine = class extends Service {
	constructor(ctx) {
		super(ctx, "compaction");
	}
};
```

**实现函数**（`dsh-compaction-basic/lib/types/region.d.ts`）：

```ts
export declare function compactSurfaceRegion(
  dependencies: RegionDependencies,
  session: Session,
  start: SessionSeq,
  end: SessionSeq,
  agent: Agent,
  options: CompactionTransactionOptions,
  signal?: AbortSignal
): Promise<CompactionResult>;
```

**替换体的落盘**（`dsh-compaction-basic/lib/index.js:648-659`）：

```js
session.append("user/message", checkpointMessage, {
    surfaceOp: { op: "replace", startSeq: start, endSeq: end },
    sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs]
});
```

### 2.2 调用点：它其实只是两个事件监听器

这是最重要的发现。`compactSurfaceRegion` 不是被谁「调用」的——
它由 `BasicCompactionEngine` 的**自动监听器**触发（`dsh-compaction-basic/lib/index.js:834-879`）：

```js
_registerAutomaticCompaction() {
    const { ctx } = this;
    ctx.on("agent/pre-step", async ({ agent, signal }, next) => {      // :839
        if (!signal.aborted) try {
            const result = await this.compactIfNeeded(agent, "pressure", signal);
            ...
        } catch (error) { ... }
        return next();
    });
    ...
    ctx.on("agent/request-error", async ({ agent, failure, signal }, next) => {  // :861
        if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next();
        ...
        result = await this.compactIfNeeded(agent, "context-overflow", signal);
        ...
        return { kind: "retry" };
    });
}
```

而注册本身受一个开关控制（`index.js:827`）：

```js
if (this.config.auto) this._registerAutomaticCompaction();
```

`auto` 的 schema 与默认值（`index.js:817`、`:85`）：

```js
auto: z.boolean()          // :817
auto: config.auto ?? true  // :85
```

### 2.3 ★ 能让 compaction「完全不发生」吗？—— 能，三条路

**路 A：`config.auto = false`（最干净，零代码）**

```yaml
- id: compaction-basic
  name: '@deepseek-ai/dsh-compaction-basic'
  config:
    auto: false
```

`auto: false` ⇒ 不注册那两个监听器 ⇒ `compactIfNeeded` 永远不被自动调用。
`compactNow` 仍可被 `/compact` 命令手动触发（`dsh-command-compact/lib/index.js:55`），
但只要不装 `command-compact` 就完全静默。

⚠️ **注意**：`auto:false` 只关掉**自动**触发。`context-overflow` 那条也关了 ⇒
上游报 context_full 时会**直接失败**（`dsh-agent-loop/lib/index.js:1146-1155` 的
`agent/request-error` 若无人返回 `{kind:'retry'}` 就 `throw new LlmError`）。
所以 `auto:false` 必须配套一个**自己的溢出恢复**，否则长会话会硬失败。

**路 B：不装 `dsh-compaction-basic`，装自己的 `CompactionEngine` 子类**

服务名冲突会抛（`cordis/lib/index.js:800-823` 的 `provide`）：

```js
if (this.store[key]) throw new Error(`service "${name}" has been registered at <${this.store[key].fiber.name}>`);
```

所以在**同一个 realm** 里换实现是**不可能**的——必须先 `isolate`。
这正是 §5 的 preset 机制干的事。

**路 C：在 isolate realm 里挂自己的 compaction**

已实测存在先例（`dsh-web-app/presets/standard.patch.yml:66-82`）：

```yaml
- id: compaction
  name: cordis:group
  group: true
  isolate:
    compaction: true
    toolResultPruner: true
  config:
    - id: compaction-basic
      name: '@deepseek-ai/dsh-compaction-basic'
    - id: command-compact
      name: '@deepseek-ai/dsh-command-compact'
    - id: tool-result-pruner
      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
```

`isolate: {compaction: true}` ⇒ 这个 group 下的 `ctx.compaction` 解析到**realm 私有 symbol**
（`cordis/lib/index.js:1723-1727` 的 `isolate(name, label)`；`mount.d.ts:44-58` 的 `leakedServices` 注释解释了机制）。
把 `compaction-basic` 换成你自己的插件，就得到**完全可控的压缩策略**——
包括「永不压缩」「压缩前先把整段写成影子副本」这类行为。

### 2.4 结论：能否替换/旁路？

| 目标 | 可行 | 手段 |
|---|---|---|
| 让自动 compaction 完全不发生 | ✅ | `config.auto: false`（需自备溢出恢复） |
| 换成自己的压缩实现 | ✅ | isolate realm + 挂自己的 `CompactionEngine` 子类（路 C） |
| 在**现有** compaction 之外再旁路一份 | ✅ | `ctx.on('agent/pre-step', ..., {prepend:true})` 抢在前面做影子快照 |
| 阻止 `/compact` 手动命令 | ✅ | 不装 `dsh-command-compact` |
| **改 `compactSurfaceRegion` 内部行为** | ❌ | 它是模块内 `function`，未导出为可替换点；只能整体换 `CompactionEngine` |

---

## 3. surface 是否支持整段 replace / 重写？

### 3.1 支持，且是官方一等机制

`SessionSurface` 只有三个只读字段（`dsh-session/lib/types/surface.d.ts`）：

```ts
export interface SessionSurface {
    readonly nodes: readonly SessionSeq[];
    readonly replaceGeneration: number;
    readonly contentGeneration: number;
}
```

replace 的写法（`dsh-compaction-basic/lib/index.js:648-659` 已给出实证）：

```js
session.append("user/message", checkpointMessage, {
    surfaceOp: { op: "replace", startSeq: start, endSeq: end },
    sourceEventSeqs: [/* 必须覆盖全部被遮蔽节点 */]
});
```

落盘后的 fold 动作（`dsh-session/lib/index.js:461-476`）：

```js
else if (plan?.kind === "replace") {
    state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq);
    state.replaceGeneration += 1;
    state.contentGeneration += 1;
}
```

⇒ **一段连续 surface 节点被「一个」新节点替换**。这就是「整段 replace」。

### 3.2 ★ 四条硬约束（必须逐条满足，否则抛错）

| # | 约束 | 代码位置 | 后果 |
|---|---|---|---|
| 1 | `startSeq`/`endSeq` **必须指向更早的事件** | `dsh-session/lib/index.js:358` | `surface replace at seq N: startSeq and endSeq must reference earlier events` |
| 2 | 两端都**必须仍在当前 surface 上** | `:364-369` `replacementRange` | `start seq ... not found in surface` |
| 3 | `startSeq` 索引必须 ≤ `endSeq` 索引 | `:369` | `is after end seq` |
| 4 | `sourceEventSeqs` **必须包含每一个被遮蔽的节点** | `:331-332` | `sourceEventSeqs must include every shadowed surface node; missing ...` |

外加一条特殊保护（`:419-423`）：

```js
function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, baseSeq) {
	if (startIdx !== 0) return;
	if (events[state.nodes[0] - baseSeq]?.type !== "system/message") return;
	if (event.type !== "system/message" || shadowedSeqs.length !== 1)
	    throw new Error("surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node");
}
```

⇒ **node 0（system prompt）只能用 `system/message` 一对一替换**，不能被 compaction 那种整段 replace 吞掉。

### 3.3 重写后 turn 序号 / 消息 id 会不会断链？

**不会断。** 三条证据：

**① turn/step 是事件数据里的字段，不是 surface 位置**
`turn/start` / `step/start` / `turn/end` 不是 surface event
（`dsh-session/lib/index.js:157-160` 的 `SURFACE_EVENT_TYPES` 只含
`system/message` / `developer/message` / `user/message` / `assistant/message` / `tool/result`）。
它们留在日志里，`turn` / `step` 数字在 `event.data.turn` 中，replace 不动它们。

**② 消息 id 是消息自己的字段，replace 生成的是新消息、新 id**
被 replace 掉的原消息 id 随事件留在日志里；新 checkpoint message 是新 id。
两者的对应关系靠 `sourceEventSeqs` 记录（`:314-332`）。

**③ 依赖「序号连续」的地方只有 replay**
`planSurfaceEvent` 第一件事（`:426`）：

```js
if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
```

这是**日志事件的 seq 连续性**（每次 append +1），不是 surface 位置连续性。
replace 只改 `state.nodes`，不改日志 seq ⇒ 不影响。

**结论**：surface replace 安全，**前提是你只 append 新事件、从不动日志数组**。
任何「删日志」「重排日志」的黑魔法都会在 resume/replay 时炸。

### 3.4 但有一个代价：被替换的原文「模型看不到了」

replace 之后 `deriveMessages()` 从 `surface.nodes` 取消息（`dsh-session/lib/index.js:1672-1687`），
被遮蔽的节点的 seq 已不在 `nodes` 里 ⇒ **它们的消息不再进模型请求**。
原文仍在日志（`session.snapshotEvents()` 可读），但**模型视角永久失明**。

这正好是影子上下文要解决的问题：**原文搬到外面的影子副本，surface 留一个指针/摘要**。

---

## 4. `MessageBase` 无 timestamp，能否挂自定义字段并活到下一轮？

### 4.1 三条互补的机制，都能用

**机制 A：`MessageSourceMap` 是 declaration-merge 可扩展的**

`dsh-llm/lib/types/message.d.ts:101`：

```ts
export interface MessageSourceMap {
    user: { kind: 'user' };
    model: ModelMessageSource;
    tool: ToolMessageSource;
    'system-prompt': SystemPromptMessageSource;
}
```

注释（`:96-100`）明确写了这是 **merge-extensible sum type**，并给出扩展方式。
已有 11 个包这么干（`dsh-time-context`、`dsh-goal`、`dsh-compaction`、
`dsh-agent-instructions`、`experimental-agent-team`…）：

```ts
// dsh-time-context/lib/types/index.d.ts
declare module '@deepseek-ai/dsh-llm' {
    interface MessageSourceMap {
        'time-context': { kind: 'time-context' } & ContextFormed;
    }
}
```

⇒ **插件可以声明自己的 `kind`，并在 `source` 里带任意 JSON 字段。**

**机制 B：session 的校验对未知 `kind` 是放行的**

`dsh-session/lib/index.js:1193-1219` `assertMessageEventShape`：

```js
if (typeof source !== "object" || source === null
    || typeof source["kind"] !== "string" || source["kind"] === "")
    throw new Error(`${subject} message has invalid source`);
...
if (type === "system/message")  { /* 必须是 system-prompt */ }
if (type === "assistant/message") { /* 必须是 model */ }
if (type !== "tool/result") return;          // ★ user/message 到此就放行
if (sourceRecord["kind"] !== "tool" || ...) throw ...
```

⇒ **`user/message` 的 `source.kind` 可以是任意非空字符串**，附加字段不被校验也不被剥离。

**机制 C：`ContextForm` 已经预留 `'recall'`**

`dsh-llm/lib/types/message.d.ts:46-58`：

```ts
export type ContextForm =
    'instructions' | 'catalog' | 'snapshot' | 'notice' | 'relay' | 'recall';
```

`:92` 对应 `{ readonly form: 'recall' }`，注释是
「Material lifted out of another session's log, possibly reduced on the way in.」
—— **dsh 自己就为「从别处搬来的内容」预留了语义槽**。

### 4.2 这些字段会活到下一轮吗？—— 会，且不会被发给模型

**存活链路**（全部只读，不丢字段）：

1. `session.append("user/message", message, ...)` ⇒ 事件进日志，
   `data` 做 **lossless-JSON 快照**（`dsh-session/lib/types/index.d.ts` 的 `append` 注释：
   「returns the logged event — ... the SNAPSHOT of `data` that entered the log」）
2. resume/replay ⇒ `Session.fromRestore(...)` 读回同一份 `data`，
   `assertMessageEventShape` 对 user 消息只校验 `id/role/kind非空/content数组` ⇒ **自定义字段完整保留**
3. `deriveMessages()` ⇒ `deriveEventMessage(event)` 投影成 `Message`，
   `source` 原样带上
4. **发给模型前被丢掉**：adapter 只读 `role` + `content`
   （`dsh-llm-deepseek/lib/index.js:1676-1690` 的 user 分支只看 `message.content`；
   `:1630-1650` 的 developer 分支同理）。
   `source` **不进 wire**。

⇒ **自定义字段：本地永生，模型不可见。** 这正是挂「影子副本指针」需要的性质。

### 4.3 但「自定义 timestamp 字段」不等于「surface 有时序」

这是最容易误判的一点。你能挂 `source.ts: 1700000000000`，
但**surface 本身没有时间轴概念**：

- `SessionSurface.nodes` 是 `readonly SessionSeq[]`（`surface.d.ts`），**有序数组，不是时间轴**
- replace 只能替换**已存在的连续区间**（§3.2 约束 1/2：两端必须仍在 surface 上）
- **没有任何 API 能「按时间戳插到历史中间」**

⇒ 「在外面维护一份带时序的影子副本」**完全可行**，因为那是**你自己的数据结构**，
dsh 根本不参与。但「把影子副本按原时序塞回 dsh 的 surface」**不可行**——
最多做到「在末尾 append 一条 `source.kind='shadow-context', form='recall'` 的消息，
正文里写清每条的真实时间」。

### 4.4 结论

| 问题 | 答案 |
|---|---|
| 能否挂自定义字段到 message | ✅ `MessageSourceMap` declaration merging + 任意 JSON |
| 能否活到下一轮（含 resume） | ✅ lossless-JSON 快照 + 未知 kind 放行 |
| 会不会被发给模型 | ❌ `source` 不进 wire，adapter 只投影 `role`/`content` |
| 能否靠它实现「面内时序」 | ❌ surface 无时间轴，replace 不能插中间 |
| 能否在外面自己维护带时序影子副本 | ✅ 完全可行，与 dsh 解耦 |

---

## 5. dsh 有没有「注册一种 agent 模式/策略」的扩展点？

### 5.1 有，而且是**一等机制**：`agentPresets`

**服务**（`dsh-agent-preset-registry/lib/types/index.d.ts:26-29`）：

```ts
declare module '@deepseek-ai/cordis' {
    interface Context {
        agentPresets: AgentPresetRegistry;
    }
}
```

**注册接口**（同文件）：

```ts
register(definition: PresetDefinition): Promise<() => Promise<void>>;
mount(ctx: Context, id?: string): Promise<AgentPreset>;
recompose(ctx: Context, id: string): Promise<AgentPreset>;
serviceFor<K extends keyof Context>(agent: { ctx: Context }, name: K): Context[K] | undefined;
```

**定义形态**（`dsh-agent-preset-registry/lib/types/definition.d.ts`）：

```ts
export interface PresetDefinition {
    readonly id: string;
    readonly name?: string;
    readonly description?: string;
    readonly order?: number;
    readonly plugins: readonly (Omit<EntryOptions, 'id'|'disabled'> & { ... })[];
}
```

即：**一个 preset = 一个 id + 一棵子插件树（Cordis entry list）**。

**插件如何注册自己的 preset**（`dsh-agent-preset/lib/index.js:18-26`）：

```js
static inject = ["agentPresets"];
static Config = z.object({ id: z.string().required(), ..., plugins: z.array(z.any()).required() });
async *[Service.init]() {
    yield await this.ctx.agentPresets.register(this.config);
}
```

⇒ **任何插件都能 `ctx.agentPresets.register({id, plugins})` 注册一种 agent 模式。**

### 5.2 为什么这正好是「影子上下文」需要的口子

preset 的子树是**独立 scope + 可选 isolate realm**（`mount.d.ts:170-198`）：

```js
export async function mountPreset(ctx, id, plugins) {
    if (scopeOf(ctx) === undefined) throw new Error('agent-preset: mounting requires a scope');
    await ctx.fiber.await();
    const tree = new PresetTree(ctx);
    ctx.effect(() => () => { tree.root.stop(); }, 'agent-preset.tree');
    await tree.root.update(prepareProfileEntries(ctx, plugins, ctx.baseUrl));
    const audit = await auditRows(tree);
    const leaked = leakedServices(ctx, ctx.fiber);
    if (audit.failed.length > 0) throw new Error(audit.failed.join('\n'));
    if (leaked.length > 0) throw new Error(`Preset services require isolate realms: ${leaked.join(', ')}`);
    ...
}
```

绑定到 agent 的 scope（`index.js:271-279`）：

```js
join(ctx, key, generation) {
    const binding = { parent: bindScopeParent(key, generation.key), generation };
    ...
}
```

⇒ preset 是 agent 的**父 scope**。agent 内所有 `ctx.xxx` 解析时，
先在 preset realm 找，再回落到 root。

**已实测的先例**：`dsh-web-app/presets/standard.patch.yml:66-82` 的
`isolate: {compaction: true, toolResultPruner: true}` group——
preset 已经在替换 compaction 服务了。我们只要把那个 group 里的
`dsh-compaction-basic` 换成自己的插件即可。

### 5.3 那「注册 agent runner 本身」呢？—— 不行，是独占的

`AgentRegistry.setFactory`（`dsh-agent/lib/index.js:429-437`）：

```js
setFactory(factory) {
    return this.ctx.effect(() => {
        if (this.factory !== void 0) throw new Error("an agent factory is already registered");
        ...
    });
}
```

而 `dsh-agent-loop` 在构造时**无条件抢占**（`dsh-agent-loop/lib/index.js:1590`）：

```js
ctx.effect(() => ctx.agents.setFactory(this), "agentLoop.setFactory()");
```

⇒ **全局只有一个 agent factory，且被 `dsh-agent-loop` 占了。**
替换它 = 不用 `dsh-agent-loop`（整套 turn/step/tool/compaction 都得自己写）。**不建议。**

### 5.4 「自己包一个 runner」这条路（替代方案，代价高）

理论上可行：不装 `dsh-agent-loop`，自己实现 `AgentFactory` 并 `ctx.agents.setFactory(myFactory)`。
`Agent` 接口是公开的（`dsh-agent/lib/types/runtime-types.d.ts` 的 `declare module './types.ts'`
里有 `session` / `inbox` / `send` / `steer` / `runMaintenance` / `whenIdle` 等）。

代价：要自己实现
- turn/step 状态机（`turn/start`/`step/start`/`turn/end` 事件形状）
- tool call 调度（`executeToolCalls` 的并行/独占/abort 语义）
- system prompt 投影（`SystemPromptProjection`）
- runtime context 投影（`RuntimeContextProjection`）
- 请求组装 + `markAgentLoopRequest` + 深冻结
- 断线恢复 / resume / fork

`dsh-agent-loop/lib/index.js` 是 **2023 行**。这不是「包一层」，是「重写一个」。

### 5.5 最接近的替代：preset 里换掉 3 个服务 + 加 1 个监听器

比起重写 runner，preset 内可以：

| 想控制的东西 | preset 内怎么换 |
|---|---|
| 上下文压缩策略 | `isolate: {compaction: true}` + 挂自己的 `CompactionEngine` 子类 |
| 消息注入时机 | `ctx.on('agent/pre-step', ..., {prepend: true})`（preset 内注册，agent-scoped） |
| 系统提示词 | `ctx.systemPrompt.section({complete: true, ...})`（注意 `complete` 会压掉其他 section） |
| 工具集 | `ctx.tools.register` + `ctx.tools.restrict` |
| 自己的持久化 | `super(ctx, 'shadowContext')` 注册一个新服务（preset 的 isolate realm 里） |

**这四件事合起来，就是一个「影子上下文 agent 模式」的完整实现**，且全是官方扩展点。

---

## 6. 两条路的实现代价与风险

### 6.1 路线 ①：劫持/外挂原有信息流

**形态**：在 root（或 agent scope）注册一堆 `ctx.on(...)`，试图在不替换任何服务的前提下
「在 dsh 的信息流旁边插一份影子副本，并让模型看到影子版本」。

#### 可行的子集（60%）

| 能力 | 手段 | 代价 |
|---|---|---|
| 旁路观测每条消息 | `session/event` emit | 0（只读） |
| 在发送前注入影子片段 | `agent/pre-step` 返回追加的 message | 低，**但会落盘成真实历史** |
| 拦最终请求做观测/计时 | `llm/stream` 包 `next()` | 低 |
| 把历史写成影子副本 | 自己监听 `session/event` 维护 side store | 中（要处理 resume/replay 重建） |

#### 挂不上的部分（40%，且是核心）

| 需求 | 为什么挂不上 |
|---|---|
| 让模型看到「影子版本的历史」而不改日志 | loop 只从 `session.deriveMessages()` 取消息（`dsh-agent-loop/lib/index.js:1274`），它读的是 surface；你要改 surface 就得 replace（= compaction 的活，需要 `ctx.compaction` 之外的手段） |
| 改写 loop 请求的 messages | `llm/stream` 收到的 loop 请求**深冻结**（`dsh-llm/lib/types/index.d.ts:38-40`），改会抛 |
| 替换 compaction 而不 isolate | `provide` 撞名抛错（`cordis/lib/index.js:814`） |
| 控制「什么时候压缩」 | 只能通过 `config.auto` 开关，无法给现有实现喂策略（`CompactionTrigger` 只有两个值，无 query） |

⇒ 路线 ① **单独做只能到「旁路观测 + 追加注入」**，拿不到「模型看影子版本」。

#### 人天估算：**12–18 人天**（做到 60% 子集）
- side store + resume 重建：4–6
- `session/event` 增量维护 + 时序：3–4
- pre-step 注入 + 去重：2–3
- `llm/stream` 观测层：2–3
- 判据：1–2

#### 风险
- **高**：注入内容永久污染日志（§1.3），无法撤销
- **高**：`llm/stream` 深冻结会在上线后才暴露（类型上 `GenerateOptions` 看起来可变，运行时冻结）
- **中**：`agent/pre-step` 是 `prepend: true` 时与其他 listener（如 compaction）的顺序耦合，dsh 不保证顺序稳定

### 6.2 路线 ②：注册独立 agent 模式（preset）

**形态**：插件 `ctx.agentPresets.register({id:'shadow', plugins:[...]})`，
子树内 `isolate: {compaction: true}` 挂自己的压缩器 + 自己的 `shadowContext` 服务。

#### 能拿到的（90%）

| 能力 | 手段 |
|---|---|
| 完全控制压缩时机 | 自己的 `CompactionEngine` 子类：`compactIfNeeded` 里先写影子副本再决定是否 replace |
| 完全控制「不压缩」 | 子类 `compactIfNeeded` 直接 `return null` |
| 自己的持久化 | `super(ctx, 'shadowContext')` + `node:sqlite`/`ctx.storage.domain` |
| 在压缩前抓取原文 | `agent/pre-step`（prepend）或直接在自己的 `compactIfNeeded` 里读 `session.snapshotEvents()` |
| 影子指针挂在消息上 | `MessageSourceMap` 扩展 + `source.kind='shadow-*'`（§4） |
| 按模式隔离 | 只有选中该 preset 的 agent 生效，其他 agent 不受影响 |

#### 挂不上的（10%）

| 需求 | 为什么 |
|---|---|
| 让 surface「插回历史中间」 | §3.2 约束：replace 只能换已存在区间，不能插 |
| 改写 loop 的最终请求 | `llm/stream` 深冻结（除非自己在 preset 内短路重发） |
| 替换 agent factory | `setFactory` 独占（§5.3） |

#### 人天估算：**18–26 人天**
- preset 骨架 + 注册 + 验证 mount：2–3
- 自己的 `CompactionEngine` 子类（含 `compactRegion` 语义复刻）：5–7
- shadow store（sqlite + 时序 + 索引）：4–6
- `agent/pre-step` 注入表层 + `source` 扩展：2–3
- 消息↔影子副本双向映射 + resume 重建：3–4
- 判据（含「压缩后原文可取回」变异）：2–3

#### 风险
- **低**：全程官方扩展点，无 hack
- **中**：`CompactionEngine` 是 `abstract class`，要实现 3 个 abstract 方法；
  `compactRegion` 的语义（区间校验、`compaction/start`/`end` 括号、`sourceEventSeqs` 覆盖）
  必须自己复刻 —— 复刻不完整会在 resume 时炸
- **中**：preset 的 `auditRows` 要求所有行可用（`mount.js:192-195`），
  子插件加载失败会让整个 preset mount 失败

### 6.3 混合方案（推荐）

**preset 骨架（②）+ 只读旁路（① 的可行子集）**：

- preset 提供 isolate 的 `shadowContext` 服务与自己的 compaction
- shadowContext 内部监听 `session/event` 维护影子时序（不改 surface）
- 需要让模型看到影子内容时，通过**自己的 compaction 子类**在 replace 时插入影子指针消息
- 全程 `auto:false` 关掉 dsh 默认压缩，避免两套压缩打架

人天：**22–30**（② 的 18–26，加 ① 的 side-store 部分 4–6）

---

## 7. 硬阻塞清单（与路线无关）

| # | 阻塞 | 证据 | 影响 |
|---|---|---|---|
| 1 | **surface 不能插入中间位置** | `dsh-session/lib/index.js:364-369`（`replacementRange` 要求两端在当前 nodes 里） | 影子副本无法「按原时序」回到 dsh；只能末尾追加 + 正文写时间 |
| 2 | **日志 seq 必须严格连续** | `dsh-session/lib/index.js:426` | 任何日志层黑魔法（删/重排）在 replay 时炸 |
| 3 | **loop 请求深冻结** | `dsh-llm/lib/types/index.d.ts:36-42`；实现 `dsh-llm/lib/index.js:2397` | `llm/stream` 只能读/短路，不能改 messages |
| 4 | **agent factory 独占** | `dsh-agent/lib/index.js:431`；`dsh-agent-loop/lib/index.js:1590` | 想自己当 runner 必须弃用 agent-loop（2023 行） |
| 5 | **`compaction` 服务名独占（同 realm）** | `cordis/lib/index.js:814` | 换实现必须 isolate（= 必须走 preset） |
| 6 | **`CompactionTrigger` 无 query** | `dsh-compaction/lib/types/index.d.ts:25` | 「按相关性淘汰」必须自己实现整个 `CompactionEngine` |
| 7 | **pre-step 注入会落盘** | `dsh-agent-loop/lib/index.js:1067-1073` | 「不改日志的影子注入」不成立 |

---

## 8. 最终判断

### 哪条可行

**路线 ②（注册独立 agent 模式）可行。** 它是 dsh 设计时就留好的一等机制，
`agentPresets.register` + `cordis:group` + `isolate: {compaction: true}` 三件套
全部是公开扩展点，且 `dsh-web-app/presets/standard.patch.yml:66-82` 已有
「preset 替换 compaction」的实证。

### 哪条只是看着可行

**路线 ①（劫持/外挂原有信息流）看起来可行，实际是三条成熟度不同的路拼起来的**：

- `agent/pre-step` 看着像「注入钩子」，其实**注入即落盘**（§1.3）——它不是影子，是正文
- `llm/stream` 看着像「最终请求改写点」，其实**loop 请求深冻结**（§1.6）——只能读
- 「不装 compaction-basic 就没了」看着像「能旁路」，其实**auto:false 会连溢出恢复一起关掉**（§2.3）

它唯一干净的用法是**只读旁路观测**（`session/event` + `llm/stream` 计时），
以及**在 preset 内部**配合使用（那就已经是路线 ② 的一部分了）。

### 硬阻塞

一句话：**dsh 的 surface 是「只追加日志上的一个可替换视图」，不是「可编排的时序容器」。**
影子上下文需要的是「在面内按时间摆放内容」，而 dsh 只能做到
「换掉一段已有内容」或「在末尾追加」。这条差异无法用插件绕过——
它是 `replacementRange` 与 `assertSourceEventReferences` 的数据结构决定的。

**可行的形态因此被限定为**：

```
影子副本活在 dsh 之外（自己的 store，带完整时序）
  + dsh surface 上只留「当前有效视图」
  + 需要看原文时，用一条 source.kind='shadow-context' 的 message 在末尾追加指针
  + 压缩策略由 preset 内自己的 CompactionEngine 子类接管
```

---

## 附录：证据索引

### dsh 输入链路

| 主题 | 位置 |
|---|---|
| `preStep` 全文（assemble + waterfall + 默认 decision） | `dsh-agent-loop/lib/index.js:902-934` |
| `turn()` 循环（turn/start、step/start、turn-stopping） | `dsh-agent-loop/lib/index.js:938-1041` |
| `step()` 全文 | `dsh-agent-loop/lib/index.js:1043-1173` |
| **`decision.messages` 落盘** | `dsh-agent-loop/lib/index.js:1066-1073` |
| `buildRequest` + `deriveMessages()` | `dsh-agent-loop/lib/index.js:1227-1288`（derive 在 `:1274`） |
| `prepareRequest` + `agent/request` waterfall | `dsh-agent-loop/lib/index.js:1175-1219` |
| `setFactory` 独占 | `dsh-agent-loop/lib/index.js:1590` / `dsh-agent/lib/index.js:429-437` |
| `agent/pre-step` 类型 | `dsh-agent/lib/types/runtime-types.d.ts:293-311`（事件名在 :304） |
| `PreStepDecision` | `dsh-agent/lib/types/runtime-types.d.ts:92-99` |
| `agent/request` 类型（含「cannot mutate messages」） | `dsh-agent/lib/types/runtime-types.d.ts:311-328`（事件名在 :327） |
| `LlmCallConfig`（只有 6 个标量） | `dsh-llm/lib/types/call-config.d.ts:22-26` |
| **`llm/stream` 类型 + 深冻结契约** | `dsh-llm/lib/types/index.d.ts:32-46` |
| `llm/stream` 实现 | `dsh-llm/lib/index.js:2397` |
| `llm/stream` 生产用法（checkpoint） | `dsh-session-checkpoint-policy/lib/index.js:61-65` |
| `GenerateOptions` 全文 | `dsh-llm/lib/types/types.d.ts`（`GenerateOptions` 段） |
| `systemPrompt.section` / `context()` / `assemble()` | `dsh-system-prompt/lib/types/index.d.ts:250 / :269 / :314` |
| `AssembleContext`（基定义仅 scope/signal） | `dsh-system-prompt/lib/types/index.d.ts:37-44` |

### compaction

| 主题 | 位置 |
|---|---|
| `CompactionTrigger` | `dsh-compaction/lib/types/index.d.ts:25` |
| `CompactionEngine` 抽象类 | `dsh-compaction/lib/types/index.d.ts:102`（`compactIfNeeded` :116 / `compactNow` :137 / `compactRegion` :157） |
| **服务名硬编码** | `dsh-compaction/lib/index.js:169-173`（`super(ctx, "compaction")`） |
| `compactSurfaceRegion` 签名 | `dsh-compaction-basic/lib/types/region.d.ts` |
| **自动触发的两个监听器** | `dsh-compaction-basic/lib/index.js:839`（pre-step）/ `:861`（request-error） |
| `auto` 开关 | `dsh-compaction-basic/lib/index.js:827`、`:817`、`:85` |
| replace 落盘写法 | `dsh-compaction-basic/lib/index.js:648-659` |
| `provides` 撞名抛错 | `cordis/lib/index.js:800-823`（`:814`） |
| `isolate()` 实现 | `cordis/lib/index.js:1723-1727` |
| **preset 已 isolate compaction 的实证** | `dsh-web-app/presets/standard.patch.yml:66-82`、`dsh-web-app/presets/minimal.patch.yml:27-32` |

### surface

| 主题 | 位置 |
|---|---|
| `SessionSurface` 三个只读字段 | `dsh-session/lib/types/surface.d.ts`（interface 段） |
| `replacementRange`（两端必须在 surface 上） | `dsh-session/lib/index.js:363-375` |
| **`sourceEventSeqs` 必须覆盖全部被遮蔽节点** | `dsh-session/lib/index.js:314-332`（`:331-332`） |
| replace 的 seq 必须更早 | `dsh-session/lib/index.js:358` |
| node 0 系统提示词保护 | `dsh-session/lib/index.js:419-423` |
| **replay seq 连续性检查** | `dsh-session/lib/index.js:426` |
| fold 的 replace 动作 | `dsh-session/lib/index.js:461-476` |
| `SURFACE_EVENT_TYPES`（turn/step 不在其中） | `dsh-session/lib/index.js:157-164` |
| `deriveMessages()` | `dsh-session/lib/index.js:1672-1687` |

### message 扩展

| 主题 | 位置 |
|---|---|
| `MessageSourceMap`（merge-extensible） | `dsh-llm/lib/types/message.d.ts:96-105` |
| `ContextForm` 含 `'recall'` | `dsh-llm/lib/types/message.d.ts:46-58`、`:92` |
| `MessageBase`（无 timestamp） | `dsh-llm/lib/types/message.d.ts:124-136` |
| **user/message 的 source.kind 放行未知值** | `dsh-session/lib/index.js:1193-1219`（`:1216` 的 `if (type !== "tool/result") return;`） |
| adapter 只投影 role+content | `dsh-llm-deepseek/lib/index.js:1630-1690` |
| 自定义 kind 的 11 个先例 | `grep -rn "MessageSourceMap" --include=*.d.ts dsh-*/lib/types/*.d.ts` |

### agent 模式注册

| 主题 | 位置 |
|---|---|
| `agentPresets` 服务声明 | `dsh-agent-preset-registry/lib/types/index.d.ts:26-29` |
| `register` / `mount` / `recompose` / `serviceFor` | 同文件（`AgentPresetRegistry` 段） |
| `PresetDefinition` | `dsh-agent-preset-registry/lib/types/definition.d.ts` |
| `mountPreset`（audit + leaked services 检查） | `dsh-agent-preset-registry/lib/types/mount.d.ts:170-198` |
| `bindScopeParent`（preset 成为 agent 的父 scope） | `dsh-agent-preset-registry/lib/types/index.js:274-276` |
| 插件注册 preset 的写法 | `dsh-agent-preset/lib/index.js:18-26` |
| preset YAML 实样 | `dsh-web-app/presets/standard.patch.yml:1-130` |
| `cordis:group` + `isolate` 语法 | 同上 `:47-49`、`:66-82` |