dsh-semantic-eviction

⚠️ EXPERIMENTAL SCAFFOLD（2026-08-15）：tools/result / tools/post-execute 事件绑定与 evict_retrieve 已有实现，但插件整体仍为脚手架级——evict_tool_result execute 返回 stub 零值（originalSizeBytes=0）、client 半仍是 console.debug 脚手架、storage 访问为防御式探测。核心算法在 src/core.ts（独立可测）。请勿 在生产 profile 启用。见 DSH-PLUGIN-OPTIMIZATION-REVIEW-GROK.md 的 REBUILD wiring 结论。

Semantic eviction for DeepSeek Harness：大工具结果落盘后替换为带检索位置的 stub，释放上下文窗口（"evict, don't truncate"）。

移植自 los 的 packages/agent/src/semantic-eviction.ts——los 项目"语义逐出"思想的 DSH 插件化落地。

它解决什么

Agent 执行中，大工具结果（文件读取、搜索输出、shell 输出）会堆积在上下文窗口里。一旦结果已持久化（写入 storage），就可以用轻量 stub 替换：

• stub 引用持久化位置（storageKey）
• stub 含 1-2 行关键摘要
• 完整内容按需通过 evict_retrieve 检索

安装

dsh plugin --profile web add "github:<your-org>/dsh-semantic-eviction#main"
dsh --profile web    # 重启生效

⚠️ 安装提示（2026-08-26 核对）：仓库当前未提交构建产物 lib/ （package.json main 指向 ./lib/index.js）且无 prepare 脚本，而 DSH 对 github: 安装的 git 托管插件依赖其在安装时经 prepare 构建——因此当前版本 经 github: 安装无法加载 bundle。本机使用请先 pnpm build 再以 link: 方式安装；github: 路径待补齐 lib/ 产物与 prepare 脚本后可用。

或者本地开发时：

dsh plugin --profile web add "link:/path/to/dsh-semantic-eviction"

机制（对应 DSH capability seams）

能力	seam
观察不可变最终结果	tools/result 监听 → 大结果持久化到 ctx.storage
改写结果为 stub	tools/post-execute 监听 → 替换为 { evicted: true, ... }
模型主动掩码/检索	ctx.tools.register(defineTool(...)) → evict_tool_result / evict_retrieve
阈值配置	cordis.patch.yml → config → Config 类型
客户端卡片渲染	ctx.clientModules + ui-slots（client 半）

配置（cordis.patch.yml）

- insert:
    - id: dsh-semantic-eviction
      name: dsh-semantic-eviction
      config:
        maskThresholdBytes: 32768   # 超过 32 KiB 的工具结果被掩码
        stubMaxBytes: 512           # stub 摘要上限
        persistOriginal: true       # 完整结果写入 storage
        registerEvictTool: true     # 注册 evict_tool_result / evict_retrieve 工具

脚手架说明

本仓库是从 los → DSH 插件化提取的脚手架模板，展示了社区插件标准结构：

dsh-semantic-eviction/
├── package.json          # dsh.bundle.patch → cordis.patch.yml；dsh.client.inject
├── cordis.patch.yml      # profile 补丁层（insert 行）
├── src/
│   ├── index.ts          # host 半：name + inject + apply(ctx)，工具注册 + 事件监听
│   └── client/index.ts   # client 半：UI 槽位 + settings 绑定
└── tests/                # vitest 单测（核心纯函数）

参照的社区实现：dsh-context-doctor、dsh-subagent-tools、dsh-llm-fallbacks（bundle.patch 声明方式）、dsh-memory-evolve（client 注入 + 设置页模式）。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build          # tsup 输出 lib/

后续可扩展（对应 los 其他可移植件）

• 接入 ctx.compaction seam 做自动压力触发（los 的 context-monitor.ts）
• 掩码敏感信息（los 的 masking.ts）——与语义逐出同一事件流
• 记忆写入门禁（los 的 write-gate.ts）——给 evict_retrieve 加 ACL

License

MIT