# 安装与验证指南

把 billion-context-dsh 装进真实 DSH 部署并验证它工作。以下步骤在本机 profile（`~/.dsh/profiles/web`）上实测过解析机制（组合行包名从 profile 目录向上解析 node_modules）。

## 1. 安装包

### 方式 A：开发迭代（symlink，改代码即生效）

```bash
mkdir -p ~/.dsh/profiles/web/node_modules
ln -s /Users/yintianan/GitHub/billion-context-dsh ~/.dsh/profiles/web/node_modules/billion-context-dsh
```

依赖说明：`dist/index.js` 内联了 acp-kernel，运行时只外链 `@deepseek-ai/dsh-compaction` 与 `@deepseek-ai/cordis`，二者由项目 `devDependencies` 提供（`billion-context-dsh/node_modules` 已在解析链上）。

### 方式 B：打包安装（发布前验证）

```bash
cd /Users/yintianan/GitHub/billion-context-dsh
npm pack                        # 产出 billion-context-dsh-0.2.1.tgz
mkdir -p ~/.dsh/profiles/web/node_modules
npm install --prefix ~/.dsh/profiles/web ./billion-context-dsh-0.2.1.tgz
```

### 方式 C：bundle 安装（v0.2.0+，`dsh plugin` 一键装）

包已声明 `dsh.bundle` manifest（`package.json` 的 `dsh.bundle.patch` → 仓库根的
[../cordis.patch.yml](../cordis.patch.yml)），可用 DSH 的插件机制安装，patch 自动把
ACP 组合行插入当前 profile 的层栈：

```bash
dsh plugin --profile web add billion-context-dsh
```

装完重启 `dsh`（bundle 层在启动时组合）。该方式等效于下面 2a 的手写组合行
（id `compaction-acp`、name `billion-context-dsh`）；bundle 的默认 patch 不带
`config`（`modelContextLimit` 省略 = 自动探测、提示词用内置文案），需要自定义
`config` 时仍建议手写组合行。

## 2. 组合行

两种挂法，按你想要生效的范围选。

### 2a. 全局生效（host 平面，所有模式）——推荐

编辑 `~/.dsh/profiles/web/cordis.patch.yml`（你的 profile 的补丁文件），追加：

```yaml
# ACP 作为全局压缩后端：四个模型工具 + `/acp` 命令 + nudge + ACP 提示词段，
# 对每个模式（standard / code / minimal / cordis / 自定义预设）都生效。
# 通常应禁用 host 的 compaction-basic（同一 realm 内两个后端同时
# provide `ctx.compaction` 会冲突），但注意：dsh 0.1.0-rc.6+ 上 web-app
# bundle 已自带该行的 disabled: true，此处显式禁用是冗余的（无害，保留
# 仅作兼容提醒；若 bundle 默认值跟踪变化，可省略此段）。
- id: compaction-basic
  disabled: true

- insert:
    - id: compaction-acp
      name: 'billion-context-dsh'
      config:
        # 模型的真实上下文窗口！省略（推荐）时会自动从模型 API 探测
        # （agent.ctx.llm.resolveModelInfo），探测失败回退默认 128000；
        # 显式配置则优先且跳过探测。分母配小（如百万窗口模型配 128K）
        # 会让使用率虚高 8 倍、nudge 过频。growth 触发阈值（50000）不随此值变化。
        modelContextLimit: 128000
        # （可选）自定义提示词文案：按槽位覆盖 nudge / 范围表 / system prompt /
        # 工具描述，模板 + 命名占位符，构造期校验（拼写错误启动即抛）。未配置时
        # 用内置默认文案（逐字节不变）。槽位与占位符清单见
        # docs/configurable-prompts-design.md。
        # prompts:
        #   nudge:
        #     normal: '上下文使用率 {pct}%。这是建议而非命令——由你决定是否压缩。'
        #   tools:
        #     acpStatus: '报告 ACP 块账本：压缩块数、回收 token、当前上下文压力。'
```

作用：host 平面注册 `ctx.compaction` + 四个模型工具 + `/acp` 命令 + `agent/pre-step` nudge 监听，所有模式共享一份。

注意：shipped 预设（standard / code / cordis）各自内部仍带着 realm 级 `dsh-compaction-basic` 兜底（shipped 安装不可改），所以这些模式里"自动压力压缩"仍由 basic 兜底，但 ACP 的 `compress` 工具、nudge、提示词段照常可用；minimal 与不带 compaction realm 的预设直接使用 host 的 ACP 引擎。

### 2a-2. 可选：关闭 shipped 模式的系统自动压缩（纯模型驱动）

2a 方案下，shipped 预设（standard / code / cordis）的 realm 里仍挂着一份 `dsh-compaction-basic` 兜底，其 `auto` 默认开启——上下文压力超阈值时会**自动摘要**，与 ACP 的"模型驱动"理念并存但不一致。若你希望某个模式也完全由模型决定压缩时机，可以复制该预设并关闭自动压缩（shipped 安装不可直接编辑，复制是唯一正路；`auto: false` 是 `dsh-compaction-basic` 的原生配置）：

```bash
# 1) 复制 shipped 预设到用户目录（以 standard 为例）
mkdir -p ~/.dsh/.agent-presets/standard-np
cp <deepseek-harness>/apps/cli/config/agent-presets/standard/{agent.cordis.yml,preset.yml} \
   ~/.dsh/.agent-presets/standard-np/
```

```yaml
# 2) 编辑 ~/.dsh/.agent-presets/standard-np/agent.cordis.yml，
#    在 compaction realm 组的 compaction-basic 行下加：
    - id: compaction-basic
      name: '@deepseek-ai/dsh-compaction-basic'
      config:
        auto: false        # 关闭系统自动压力压缩，只保留手动 /compact
```

保存后重启（或新开会话），GUI 里选择新的 `standard-np` 模式即可。该模式不再自动摘要，ACP 的 `compress` / nudge / 提示词段照常工作。已验证：复制 + `auto: false` 后预设可正常挂载（`standingKeyFor` → `mounted OK`）。

- **standard / code**：可直接复制，无冲突。
- **cordis**：含 `tool-cordis` 行（进程全局 inspect provider），复制会与已挂载的 shipped cordis 冲突——除非同时删除该预设里的 `tool-cordis` 行（代价：失去 cordis 的插件开发工具）。要纯模型驱动的 cordis，建议保留 shipped 原版，接受其 realm 兜底，或从 standard 副本开始按需补行。

### 2b. 单模式生效（agent preset 的 `compaction` realm）

放进某个 preset 的 `compaction` isolate realm，并**用本引擎替换该 realm 的 `dsh-compaction-basic`**：先禁用（或删除）realm 内原有的 `dsh-compaction-basic` 行，再插入本引擎——同一 realm 内两个后端同时 provide `ctx.compaction` 会冲突：

```yaml
# 先禁用 realm 内默认后端（或直接删掉这一行）
- id: compaction-basic
  disabled: true

# 再插入本引擎
- id: compaction-acp
  name: 'billion-context-dsh'
  config:
    # 同上：省略时自动探测模型真实窗口，显式配置优先（默认 128000 按 128K 窗口）。
    modelContextLimit: 128000
```

只对该模式生效，不是全局。此时本引擎的 `compactIfNeeded` 成为该 agent 的自动压缩策略（返回 null = 只 nudge 不自动摘要）。

## 3. 重启

组合变更后，若你的 profile 开启了补丁热加载（如 `dsh --profile web` 对 `cordis.patch.yml` 的配置热更新）则立即生效，否则重启 dsh web 进程（你当前的启动方式，如 `pnpm run dev:web` 或 `dsh --profile web`）。重启后打开/新建一个会话。

## 4. 验证清单

| 步骤 | 命令/操作 | 预期 |
|---|---|---|
| 1. 工具注册 | 新会话里要求模型列出可用工具，或观察工具目录 | 出现 `compress`、`decompress`、`search_context`、`acp_status` |
| 2. 状态可用 | 让模型调用 `acp_status` | 返回块数、压缩 token、估计上下文占用 |
| 3. 压缩闭环 | 在一个较长会话（消息多、上下文超过窗口时），模型按 nudge 或自行调用 `compress({ content: [{ startSeq, endSeq, summary }] })` | 返回 `Compressed N block(s)`；会话上下文明显缩小；`acp_status` 的 blocks 增加 |
| 4. 可恢复 | 调用 `decompress({ blockId })` | 返回被压缩范围的原文 |
| 5. 可搜索 | 调用 `search_context({ query })` | 命中被压缩块内信息 |
| 6. nudge | 持续对话到出现可压缩堆积。增长路径：某层 pending ≥ 5 万 token 且较上次检测增长 ≥ 2.25 万 token（无百分比下限，中前期就可能触发）；保证线：使用率 ≥ 70%；紧急：≥ 85% | 注入消息提示压缩，带 `seq a..b` 范围表 |
| 7. 持久性 | 重启后同一会话 | `acp_status` 仍能从日志重建块账本（block ledger 来自 `compaction/summary` 事件） |

## 5. 快速自检（不依赖真实模型）

```bash
cd /Users/yintianan/GitHub/billion-context-dsh
npm run typecheck && npm test && npm run build
```

80 个测试覆盖：seam 挂载、窗口探测、CJK 感知 token 估算、消息投影、压缩事务（事件序列 + surface 遮蔽）、日志重建账本、四工具端到端、nudge 注入/去重/紧急绕过、可配置提示词模板与校验。

## 6. 回滚

```bash
rm ~/.dsh/profiles/web/node_modules/billion-context-dsh   # 或对应 tarball 安装
# 从 cordis.patch.yml 删除 compaction-acp 插入行；若按 2a 全局方案装的，
# 还要删除对 compaction-basic 的 disabled: true（恢复默认自动压缩）。
# 注意：dsh 0.1.0-rc.6+ 上 bundle 自带该 disabled: true，如未显式添加则无需删除。
# 视热加载/重启策略生效。
```