{"_id":"@buddhilive/dsh-compaction-tool-result-pruner","name":"@buddhilive/dsh-compaction-tool-result-pruner","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-compaction-tool-result-pruner","description":"Replay-safe model-free head/middle/tail pruning for tool-result surface nodes","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/compaction/compaction-tool-result-pruner"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-compaction":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-token-meter":"^0.1.2-alpha.3"},"dependencies":{"@buddhilive/dsh-util-values":"^0.1.2-alpha.3","@deepseek-ai/schemastery":"^3.18.2"},"devDependencies":{"@deepseek-ai/cordis":"^4.0.2","@deepseek-ai/cordis-plugin-include":"^1.0.7","@deepseek-ai/cordis-plugin-loader":"^1.0.3","@buddhilive/dsh-compaction":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-token-meter":"^0.1.2-alpha.3"},"_id":"@buddhilive/dsh-compaction-tool-result-pruner@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-Cx54Cgi/5c4HCgtWR6zHpIi7PVReDFrEoIUhUpLZdUAJkH/hkzko7okYb9zRkgZTVDcFbbj4pW64grGeNGvwnQ==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-compaction-tool-result-pruner-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-compaction-tool-result-pruner-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Cx54Cgi/5c4HCgtWR6zHpIi7PVReDFrEoIUhUpLZdUAJkH/hkzko7okYb9zRkgZTVDcFbbj4pW64grGeNGvwnQ==","shasum":"be1d42e35ae2e9f54dc8aeb07705bac86836a1da","tarball":"https://registry.npmjs.org/@buddhilive/dsh-compaction-tool-result-pruner/-/dsh-compaction-tool-result-pruner-0.1.2-alpha.3.tgz","fileCount":11,"unpackedSize":34994,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDexWLwW0EMRkAqKeJo0ODWY+P5lahjV0RC1QFCnFk3WgIgPFfZGtmqkbXDOjbrq0LuToqu384zB5p6ZBhHC6zTPOQ="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-compaction-tool-result-pruner_0.1.2-alpha.3_1788165577771_0.9472262521121959"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:39:37.562Z","0.1.2-alpha.3":"2026-08-31T08:39:37.910Z","modified":"2026-08-31T08:39:38.086Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Replay-safe model-free head/middle/tail pruning for tool-result surface nodes","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/compaction/compaction-tool-result-pruner"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向组合压缩的部署方的工具输出修剪：选择大小限制或排查超大工具结果为何被缩短。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-compaction-tool-result-pruner\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-compaction-tool-result-pruner` 防止上下文窗口被超大工具输出填满。压缩即将运行时，它会把每个超出预算的工具结果修剪为长度受限的头部、简短的「middle pruned」标记与长度受限的尾部，同时完整原始结果仍保留在会话日志中，可供精确回放与检查。修剪不发起模型调用，并可能自行清除 token 压力，因此压缩可能完全跳过摘要。它只在压缩触发条件满足后运行——低于压力的对话绝不会被触碰。字符预算只是启发式；token meter 负责判定压力是否真的得到缓解。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当工具输出经常主导对话窗口时，在 `dsh-compaction-basic` 旁挂载本包。修剪会改变模型看到的内容——更短的结果——并让压缩有更少的历史需要压缩。\n\n### 最小可用组合\n\n按此顺序挂载 token 测量、本包与后端：\n\n```yaml\n- name: '@buddhilive/dsh-token-meter'\n- name: '@buddhilive/dsh-compaction-tool-result-pruner'\n- name: '@buddhilive/dsh-compaction-basic'\n```\n\n有了这些配置行，超大工具结果会在压缩过程中自动被修剪。你可以通过检查后续请求是否显示修剪后的结果来确认成功；完整原始内容仍保留在会话日志中。\n\n### 什么会被修剪\n\n每个文本超过阈值的工具结果都会被替换为修剪版本：配置的头部、简短的「middle pruned」标记与配置的尾部。图片与结构化块等富内容保持原有顺序。替换保留工具调用、步骤、错误与元数据——只有文本内容发生变化。如果替换无法被记录，运行会失败，已应用的修剪仍会保留。\n\n### 设置大小限制\n\n所有设置都可选；默认会把文本超过 8,192 个字符的结果修剪为其前 4,096 加后 1,024 个字符，并用标记连接。生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-compaction-tool-result-pruner)是穷尽式真源。\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `thresholdChars` | `8192` | 合并文本超过此 Unicode 码点数时修剪。 |\n| `headChars` | `4096` | 保留的开头 Unicode 码点数。 |\n| `tailChars` | `1024` | 保留的末尾 Unicode 码点数。 |\n\n字符数以 Unicode 码点计，因此切片绝不会拆分 emoji 对，但多字符字素仍可能被切断。头部加标记加尾部之和必须不超过阈值，因此有效配置可以修剪每个超出预算的结果，不会增长或重复改写。未知设置会在构造时拒绝插件。\n\n### 修剪何时运行\n\n修剪只在压缩触发条件满足后运行：`dsh-compaction-basic` 在压力或溢出确认后、选择要压缩的内容之前调用它。低于压力时不会修剪任何内容，修剪本身也不发起模型调用。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释修剪器背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。\n\n### 设计理念\n\n该修剪器建立在三项承诺之上：\n\n- **确定性的单次收敛。** 按 Unicode 码点以固定预算切片，因此每个发出的结果在文本码点上都精确包含已配置的头部、标记与尾部，不大于 `thresholdChars`，且严格小于触发输入。\n- **可安全回放的替换。** 原始事件保留在仅追加日志中；替换通过 `sourceEventSeqs` 引用它，因此回放可以恢复产生已剪枝结果的精确输入。\n- **影子价格协议。** `compaction/prune` 紧跟其替换，通过注入的 token meter 为被替换的精确范围定价，使纯消费方无需每节点状态即可减去它——即 `compaction/prune` 事件上记录的共享协议。\n\n### 剪枝机制\n\n剪枝按 Unicode 码点测量 `text` 块（非文本块计为零），生成长度受限的替换——内容已在预算内时则不替换——并把每个超出预算的工具结果换为一条新追加的 `tool/result`，该事件替换原始事件并通过 `sourceEventSeqs` 引用它，前面紧跟一条 `compaction/prune` 影子价格事件。会话拒绝替换时，运行会同步失败；本次扫描中先前已提交的替换仍会保留。非文本块保持原始相对位置，切片绝不会拆分 UTF-16 代理项对。精确签名见 [`src/index.ts`](src/index.ts)。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 插件入口：`ToolResultPruner` 服务、`pruneSession` / `pruneContent` / `measureContent` |\n| [`src/config.ts`](src/config.ts) | `PRUNE_MARKER`、默认值、码点计数、预算验证 |\n| [`src/types.ts`](src/types.ts) | `ToolResultPruneConfig`、`ResolvedConfig`、`PrunedEntry`、`PruneResult` |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；替换可在会话日志中观察） |\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面；它们从消费后端逐步进入共享 seam 与定价服务。\n\n- [压缩基础后端](../compaction-basic/README.zh.md)——在压缩前修剪超大工具输出的后端。\n- [压缩 seam](../compaction/README.zh.md)——本包接入的压缩约定。\n- [压缩子系统参考](../../../docs/subsystems/compaction.zh.md)——压缩词汇、结果与服务行为。\n- [Token meter](../../llm/token-meter/README.zh.md)——判定修剪是否缓解压力的测量服务。\n- [生成配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-compaction-tool-result-pruner)——每个受支持配置字段及其源声明。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 已剪枝的工具结果\n\n#### 模型看到的内容\n\n一旦满足压缩触发条件，后续请求看到的将是保留的头部、`\\n\\n[... tool result middle pruned ...]\\n\\n` 和保留的尾部，而非被移除的文本。非文本块保持原有顺序。模型不会看到原文的第二份副本。\n\n#### Token 影响\n\n每个已改写工具结果最多包含 `thresholdChars` 个文本码点。剪枝本身不会发起模型调用；重新测量的请求低于压力阈值时，compaction-basic 会跳过摘要，否则摘要器会读取已剪枝的表层。\n\n#### KV Cache 影响\n\n替换较早的结果会使从第一个改变的 token 起的复用失效。当其路由、envelope 与之前的历史保持一致时，已剪枝前缀可以复用。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明修剪何时不合适，或何时需要特别注意；它们是当前包约束。\n\n- **字符预算不是 token 预算**——不同提供方的 token 密度各异，因此 `ctx.tokenMeter` 仍负责判定修剪是否缓解了请求压力。\n- **剪枝只基于语法**——它保留开头与结尾，不解释中间哪些行在语义上重要。\n- **字素簇可能被拆分**——按码点切片可保护代理项对，但不会执行感知区域设置的字素簇分割。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n本开发备注是维护者的工作上下文，明确不具权威性；已交付行为以上文、包代码与所链接的 Agent Note 为准。\n\n- **语义化中间选择，尚未决定**——剪枝盲目保留头部与尾部；判断中间哪些行重要需要模型或结构化启发式，两者都未随附。\n- **基于 token 的预算，暂缓**——预算以 Unicode 码点计；改为基于 token 的预算需要 token meter 未暴露的估算器约定。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-eb372da07c38b5b28b565f5931dd43ec"}