dsh-context-structurer

Readme

# dsh-context-structurer

**结构化 dsh 上下文**:把会话上下文拆成类型化小上下文(思考 / 工具调用 / 正式回复),以「结构化上下文目录」为索引。两种模式:

- **auto**(默认):注入 目录 + 分型小节(思考/工具/回复摘要),内容变化才重发。
- **release(按需放行,省 token)**:目录升级为**带序号的全量条目索引**,**三层自动筛选**按用户需要放行相关条目,未放行的条目不占 token。

## release 模式:三层筛选

```
用户发消息 → step 1 内部:
  ① 确定性基线(零成本):自动放行 最近回复 + 最近工具调用(可配置)
  ② 内置筛查器:一次小模型调用(输入=目录+用户请求 → 输出=相关序号)
     —— 主模型无感,不用调任何工具
  ③ context_release 工具(兜底):主模型可随时补放行
→ step 1 直接载入:目录 + 放行条目,主模型一次请求就绪
```

- **确定性基线**(`baselineEnabled`,默认开):最近 1 条回复 + 最近 2 次工具调用自动放行——模型什么都不做也有最近上下文;
- **内置筛查器**(`screenerEnabled`,默认开):纯文本小调用(无工具、无副作用),超时 15s、abort 联动、输出严格校验(仅目录内整数序号、上限 20 个),**任何失败静默降级为基线**,绝不阻塞会话;默认复用会话当前 provider/model,可用 `screenerProvider/screenerModel` 指定;
- **工具兜底**:`context_release({ids:[...]})` 或 `all`,主模型补放行;放行工具的调用不占序号、不列目录。

## 安全设计

筛查器调用:纯文本补全(不给工具)、超时上限、abort 联动、输出白名单校验、失败降级;每个用户输入最多一次调用;`screenerEnabled: false` 可整体关闭(退化为纯基线 + 工具)。

## 序号稳定性

序号按**条目身份**分配(用户输入 / 思考块 / 工具调用+结果 / 回复块),追加式日志下跨 step、跨进程稳定,不会因新消息入日志而漂移。

## 配置(profile cordis.patch.yml 里 context-structurer 行的 config)

```yaml
- id: context-structurer
  name: dsh-context-structurer
  config:
    mode: release            # auto | release(默认 auto)
    language: zh             # zh | en
    baselineEnabled: true    # 确定性基线开关
    baselineReplies: 1       # 基线自动放行的最近回复数
    baselineTools: 2         # 基线自动放行的最近工具调用数
    screenerEnabled: true    # 内置筛查器开关
    screenerMaxIds: 20       # 筛查器最多接受的序号
    screenerTimeoutMs: 15000 # 筛查调用超时
    screenerProvider: ''     # 空=复用会话模型
    screenerModel: ''
    maxSectionBytes: 4096    # 目录/放行正文的截断上限
```

auto 模式独有:`includeThinking / includeTools / includeReplies`(默认 true)、`maxThinkingItems(5) / maxToolItems(8) / maxReplyItems(5) / tocMaxInputChars(120)`。

## 联动(两种模式一致)

不 suppress、不禁用任何东西:扁平运行时快照(`@deepseek-ai/dsh-system-prompt`)与工作区指令(`dsh-agent-instructions`)的消息原样保留,与平台 compaction 不冲突。

## 安装

```sh
dsh plugin --profile <name> add C:/Users/Administrator/dsh-context-structurer
```

## 验收

```sh
node verify.mjs                # 契约 + 引擎 + 集成(93 断言;集成层需依赖可解析)
pwsh -File verify-plugin.ps1   # 完整验收:93 断言 + pmv2 双启动(release 模式)+ SHA-256 一致性
```