# Context Guardian for DeepSeek Harness

[English](README.md) · 简体中文

这个适配器在 DeepSeek Harness 提交原生上下文压缩前审计 Preview：

```text
Harness 原生 Preview → Context Guardian 审计 → 自动修正 / 最多 3 个主题问题
→ 精确状态修正或确定性 Reviewed Facts 区块 → Harness 原生 compaction 提交
```

它是 `dsh-compaction-basic` 的装饰器。DeepSeek Harness 继续负责压缩范围、
token 统计、会话事件、摘要格式、持久化和 `/compact` 命令。适配器只调用一次原生
`summarize()`，只对文本块应用来源明确且唯一的精确修正，并在需要时追加一个确定性的 Reviewed Facts 内容区块；其他摘要块和元数据保持不变。如果 Python、桥接、
模型审计、UI 或最终处理不可用，适配器会记录 warning 并接受已经成功的 Preview；如果
Preview 本身失败才回到 Harness 原生 fallback。这是实验性能力，不保证一定改善
摘要或 Agent 表现。

可用 `CONTEXT_GUARDIAN_MAX_REVIEW_QUESTIONS=0..3` 设置问题硬上限；设为 0 表示
不弹窗，对未决主题采用保守处理。

## 安装

DeepSeek Harness 目前仍是 developer preview，适配器锁定 `0.1.5-rc.x` API 系列。
适配器已经发布，安装 Python 核心并加入 Web profile：

```bash
python3 -m pip install context-guardian-core
dsh plugin --profile web add context-guardian-deepseek-harness
```

适配器与 Python 核心共用带版本的 bridge 合同，必须保持在同一条 `0.4.x` 发布线上。
复现已发布配置时请固定两边的版本；例如 `0.4.2` 配对安装如下：

```bash
python3 -m pip install "context-guardian-core==0.4.2"
dsh plugin --profile web add context-guardian-deepseek-harness@0.4.2
```

如果旧核心不认识适配器使用的操作，适配器的 fail-open warning 会包含底层 bridge
错误，不再静默隐藏兼容性问题。

从源码试用时，可以把包名替换为：

```bash
dsh plugin --profile web add /absolute/path/to/ContextGuardian/adapters/deepseek-harness
```

由于 DeepSeek Harness Web 会在选中的 agent preset 内组合 compaction，仅安装包
还不够。请复制 `standard` preset，保持其他内容不变，把其中的
`compaction-basic` 行替换为 `context-guardian-deepseek-harness`，然后选择该
preset 或将它设为默认。compaction 分组应包含：

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

这是必须步骤，因为 Harness 会在每个 session scope 内挂载 preset，profile 级别
的插件行不能覆盖 preset 自己的 `compaction-basic` 行。

Python 核心需要安装在 `dsh` 使用的环境中，也可以显式指定解释器：

```bash
python3 -m pip install -e /absolute/path/to/ContextGuardian
export CONTEXT_GUARDIAN_PYTHON=/absolute/path/to/python
```

适配器不会接收或转发 `DEEPSEEK_API_KEY`。结构化检查会通过 Harness 当前的
`ctx.llm` 路由执行，由 Harness 负责解析 Provider 凭证。

Provider 审计输出默认不可信。每个 finding 必须引用本次请求中的真实消息，证据片段还
必须逐字匹配对应原文，才能进入 Review 主题或 Reviewed Facts。模型生成的易读或翻译文案
只用于界面显示；界面会单独展示原文证据，并且只持久化经过校验的原文完整句子。宿主规划
元数据、system/plugin 消息、工具调用、路径、哈希、日志和已解决的机械错误不会进入人工
审查。这与 Pi 适配器使用同一套来源规则。

如果核心安装在虚拟环境中，启动 Harness 前设置
`CONTEXT_GUARDIAN_PYTHON=/absolute/path/to/venv/bin/python`。

在 Windows 上，bridge 会在保持最小子进程环境的同时传递 Python 网络栈所需的运行时变量。
如果 `python3` 解析到了 Microsoft Store 占位符，请在启动 Harness 的同一个 PowerShell
会话中显式指定解释器：

```powershell
$env:CONTEXT_GUARDIAN_PYTHON = (Get-Command python).Source
$env:CONTEXT_GUARDIAN_DEBUG = "1"
$env:CONTEXT_GUARDIAN_TIMEOUT_MS = "120000"
dsh --profile web
```

bridge 默认超时为 120 秒，也可以用 `CONTEXT_GUARDIAN_TIMEOUT_MS` 调低（上限为 120 秒）。
启用 debug 后，适配器会记录已加载，并只报告审计 finding 和主题问题数量，不输出
原始 prompt 内容。

## 交互式验证

启动 Web profile：

```bash
dsh --profile web
```

要验证完整流程而不进行很长的真实对话，在仓库根目录运行：

```bash
env PATH="/path/to/node-22.19/bin:$PATH" npm run dsh-fixture-smoke
```

fixture 会创建隔离的 Web profile，预置足够长的会话，并故意让 replay 的原生
Preview 缺少部分事实。打开 Harness UI 后，先选择名为
`Context Guardian 预置长对话（请先选择）` 的会话（或选择
`context-guardian-fixture-long` 工作区中的该会话），再输入 `/compact`。界面应
最多显示 3 个主题问题；请手动选择“采用修正 / 保持当前摘要”或 Keep/Drop，然后确认原生 Preview 及其
确定性 Reviewed Facts 区块。它使用 replay model，不需要 DeepSeek API Key。结束临时 Web 进程时
按 Ctrl-C。

如果要验证真实 Harness 宿主、真实模型和真实 Review UI，可以运行 live fixture：

```bash
CONTEXT_GUARDIAN_DSH_LIVE=1 \
CONTEXT_GUARDIAN_FIXTURE_PACKAGE=context-guardian-deepseek-harness@0.4.2 \
npm run dsh-fixture-smoke
```

live 模式使用现有 DSH home 和 Provider 路由，认证信息留在 Harness 内，不会传给 Python。
它会预置一个足够长的会话，并额外加入一个刻意未决、与未来安全设计有关的主题。打开 Web
后输入 `/compact`，确认出现不超过 3 个主题问题，手动选择 Keep 或 Drop，并确认原生压缩
完成。具体是否弹出问题取决于模型：如果原生 Preview 已经保留该主题，0 个问题也是正确
结果。replay 模式用于确定性 CI，live 模式用于真实宿主/UI 验证。

如果无头组合没有 answerer，适配器会明确报告 Review UI 不可用，并接受已经成功的
原生 Preview。只有在明确配置无 UI 运行时才设置 `CONTEXT_GUARDIAN_NO_UI=1`；此时
未决主题按保守建议处理。

## 禁用或卸载

临时禁用时，在 `Settings → Agent Presets` 中选择原生 `standard` preset，设为
默认并新建 session。自定义 preset 可以保留，之后还可重新启用。

要完全卸载，先切换离开自定义 preset，再移除 profile 插件；之后可以删除自定义
preset：

```bash
dsh plugin --profile web remove context-guardian-deepseek-harness
```

原生 `standard` preset 会恢复 Harness 原本的 compaction 流程。如果卸载命令
失败，先执行 `dsh plugin --profile web list` 检查当前 profile，不要直接修改整个
DSH 目录。

## 本地开发

```bash
npm install
npm --workspace adapters/deepseek-harness run typecheck
npm --workspace adapters/deepseek-harness run test
```

这个适配器与 Python distribution、Pi 适配器分别发布，因此每个宿主可以按自己
的生命周期和 UI 合同独立演进。