dsh-compaction-weave 0.0.0-stage → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/LICENSE +21 -0
  3. package/README.en.md +145 -0
  4. package/README.md +148 -2
  5. package/cordis.patch.yml +19 -0
  6. package/docs/architecture.md +84 -0
  7. package/docs/benchmarks/published-0.3.2-rc.1-tests.json +576 -0
  8. package/docs/benchmarks/rc2-documentation.json +41 -0
  9. package/docs/benchmarks/rc2-linux-tests.json +590 -0
  10. package/docs/benchmarks/rc2-live-and-cost.json +746 -0
  11. package/docs/benchmarks/rc3-host-compatibility.json +2314 -0
  12. package/docs/benchmarks/rc4-tests.json +617 -0
  13. package/docs/benchmarks/review35-compression.json +117 -0
  14. package/docs/benchmarks/v0.3.2-live-four-way.json +3495 -0
  15. package/docs/benchmarks/v0.3.2-tests.json +590 -0
  16. package/docs/configuration.md +131 -0
  17. package/docs/development.md +95 -0
  18. package/docs/en/architecture.md +75 -0
  19. package/docs/en/configuration.md +131 -0
  20. package/docs/en/development.md +92 -0
  21. package/docs/en/feedback.md +47 -0
  22. package/docs/en/principles.md +235 -0
  23. package/docs/en/testing.md +368 -0
  24. package/docs/en/troubleshooting.md +60 -0
  25. package/docs/feedback.md +47 -0
  26. package/docs/images/principles-context.en.svg +77 -0
  27. package/docs/images/principles-context.zh.svg +77 -0
  28. package/docs/images/principles-pipeline.en.svg +93 -0
  29. package/docs/images/principles-pipeline.zh.svg +93 -0
  30. package/docs/images/principles-recovery.en.svg +46 -0
  31. package/docs/images/principles-recovery.zh.svg +46 -0
  32. package/docs/principles.md +235 -0
  33. package/docs/test-results.json +634 -0
  34. package/docs/testing.md +358 -0
  35. package/docs/troubleshooting.md +60 -0
  36. package/lib/abort.js +13 -0
  37. package/lib/action-state.js +60 -0
  38. package/lib/atomic-replace.js +18 -0
  39. package/lib/attachments.js +76 -0
  40. package/lib/audit-reject.js +161 -0
  41. package/lib/audit.js +939 -0
  42. package/lib/cache-policy.js +71 -0
  43. package/lib/client.js +696 -0
  44. package/lib/command-compact.js +38 -0
  45. package/lib/command-heartbeat.js +61 -0
  46. package/lib/config.js +596 -0
  47. package/lib/constraint-scope.js +37 -0
  48. package/lib/continuation-budget.js +69 -0
  49. package/lib/continuation-pending.js +57 -0
  50. package/lib/continuation-progress.js +46 -0
  51. package/lib/continuation.js +287 -0
  52. package/lib/engine-entry.js +103 -0
  53. package/lib/engine.js +2485 -0
  54. package/lib/failure-diagnostics.js +220 -0
  55. package/lib/history-source.js +74 -0
  56. package/lib/history.js +712 -0
  57. package/lib/idle-compaction.js +64 -0
  58. package/lib/index.js +611 -0
  59. package/lib/instruction-source.js +163 -0
  60. package/lib/journal.js +164 -0
  61. package/lib/manual-error.js +179 -0
  62. package/lib/memory-policy.js +383 -0
  63. package/lib/meter.js +387 -0
  64. package/lib/observation-mask.js +390 -0
  65. package/lib/proactive.js +108 -0
  66. package/lib/progress-facts.js +347 -0
  67. package/lib/progress-state.js +30 -0
  68. package/lib/prompt.js +194 -0
  69. package/lib/reconstruct.js +72 -0
  70. package/lib/reference-input.js +107 -0
  71. package/lib/region.js +972 -0
  72. package/lib/source-provenance.js +58 -0
  73. package/lib/source-recovery.js +22 -0
  74. package/lib/source-refs.js +137 -0
  75. package/lib/state.js +46 -0
  76. package/lib/storage-path.js +42 -0
  77. package/lib/summary-budget.js +187 -0
  78. package/lib/summary-config.js +308 -0
  79. package/lib/summary-progress.js +56 -0
  80. package/lib/summary-retry.js +27 -0
  81. package/lib/summary-timeout.js +68 -0
  82. package/lib/summary.js +476 -0
  83. package/lib/tools.js +341 -0
  84. package/lib/transaction-host.js +252 -0
  85. package/lib/transaction.js +285 -0
  86. package/lib/validate.js +503 -0
  87. package/lib/version.js +3 -0
  88. package/lib/window.js +120 -0
  89. package/lib/work-report.js +55 -0
  90. package/locale/en.json +6 -0
  91. package/locale/zh.json +6 -0
  92. package/package.json +71 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,103 @@
1
+ # 更新记录
2
+
3
+ ## 0.3.4 — 2026-11-21
4
+
5
+ - **npm `latest` 分发渠道与双语文档更新**:在 `README.md` 与 `README.en.md` 顶部加入绑定 `latest` 标签的 npm 徽章,将推荐安装与升级方式调整为直接安装 npm 包 `dsh-compaction-weave`(`dsh plugin --profile web add dsh-compaction-weave`,自动接收更新提示并免 `allowBuilds`),保留离线 `.tgz` 方案并同步更新 `docs/troubleshooting.md`、`docs/en/troubleshooting.md` 升级命令示例。
6
+ - **自动发版工作流(`.github/workflows/release.yml`)**:推送与 `package.json` 匹配的 `v<version>` 标签后自动运行 Windows / Linux 校验与 DSH 宿主兼容矩阵,并通过 npm OIDC Trusted Publishing(自动生成 Provenance 溯源证明,免长期 `NPM_TOKEN`)发布到 `latest`(或预发布 `next`),同时创建或更新 GitHub Release(`--latest` + 全部 5 个产物含无版本号 `dsh-compaction-weave.tgz`);支持 `workflow_dispatch` 的 `dry_run` 预演。
7
+ - **发布文档路径修正**:更新 `docs/development.md` 与 `docs/en/development.md` 中的手动发布命令示例为 `./dist/...` 相对路径前缀(适配 npm 11+),并补充 Trusted Publishing 配置说明。
8
+
9
+ ## 0.3.3 — 2026-11-21
10
+
11
+ - **修复技术术语被误判为数值约束([#1](https://github.com/NightFrost42/dsh-compaction-weave/issues/1))**:在 `lib/audit.js` 中为 `numericFacts` 与 `scalarRequirement` 增加 `isNonQuantityTechTerm` 校验:紧贴数字的大写单字母时长符号(如 `3D`、`2D`、`3M`、`6S`、`2H`)不再被当作时长单位(小写 `3d`/`30s`/`5m`/`2h` 与 `3 days`/`3天` 保持不变);缺少存储/内存/配额类上下文的独立 `5G` 不再被当作 `5gb`(`备份上限 5G`、`5GB` 及 `25G`/`8GB` 等真实容量约束不受影响)。
12
+ - **回归测试**:在 `test/constraint-scope.mjs` 新增 14 项针对 `3D`/`2D`/`5G` 等术语与真实容量/时长边界的回归用例,离线全量测试 **955 项 0 失败**。
13
+
14
+ ## 0.3.2 — 2026-11-19
15
+
16
+ - **正式稳定版发布与渠道调整**:将包版本升级为 `0.3.2` 正式版,将 `publishConfig.tag` 调整为 `latest`;同时更新发布脚本 `scripts/release.mjs`,每次打包同步输出无版本号副本 `dsh-compaction-weave.tgz` 与带版本号 `dsh-compaction-weave-0.3.2.tgz`,支持 `releases/latest/download/dsh-compaction-weave.tgz` 固定升级入口。
17
+ - **宿主兼容放宽与公开接口平滑降级(`strictHostFingerprints: false`)**:将 `engines.dsh` 从 `>=0.2.2-rc.1 <0.3.0-0` 放宽至 `>=0.2.2-rc.1 <1.0.0-0`(覆盖 `0.2.x–0.x`);新增 `strictHostFingerprints` 配置(默认 `false`):在无条件阻断未恢复 `.rollback`/`.tail` 原子日志与保留前置归档的前提下,当 DSH 小版本更新调整私有持久化方法时发出一次兼容提示并自动降级为公开 `Session.append(..., { surfaceOp: { op: 'replace' } })` + `sessions.flush()`,避免无关宿主小更新造成插件停机(设为 `true` 时保留严格方法指纹白名单拦截)。
18
+ - **第一级零模型调用工具输出折叠(`observationMaskingEnabled`)**:在压力触发下先把尾部外超过 `4000` 字的非报错工具结果归档并折叠为首尾预览与 `history_read` 指针,重新实测达标则直接结束、免去一次摘要模型调用(实测重工具输入压力压缩由 `1 → 0` 次调用、`7329 ms → 19.36 ms`);不足达标时不污染可见前缀以保 KV 缓存,同时严格限制溯源链深度上限(`< 63`)、单批引用配额(`<= 3840`)及写盘错误 `surfaceMutated` 传播。
19
+ - **同模型路由原样前缀复用(`preservePrefixCache`)**:当摘要路由与主会话持久路由一致且预算允许时,保持前缀消息逐字节不变(配对实测从 `60%` / `654 B` 提升至 `100%` / `12,215 B`);遇到溢出时按原文上限折半并平滑退回外部坐标投影;标准检查点自动附带 `History archive: <compactionId>` 指针与涉及文件列表,超出体积限制时依次精简文件列表或指针行。
20
+ - **结构化通道隔离与通用审计(正则大减法)**:用宿主原生事件通道与显式 XML 标签(`<untrusted_reference>`、`<quoted_text>` 等,支持同类嵌套与闭合防逃逸、内部边界转义及 `<channel-provenance>` 清单)替代猜测性自然语言引用正则;要求审计支持按用户原始消息时序重放逐条授权与撤回出处、双侧条件比对、正反同义极性识别、词集查表 + 双字切片与通用争议句修复;进度事实收敛为与业务名词无关的显式 `key: value` 结构化校验(45 轮校验由 `1.08 ms` 降至 `0.01 ms`)。
21
+ - **闲置后先压缩与热生效设置**:保留 `0.3.2-rc.4` 引入的“闲置后先压缩”(`idleCompactionMinutes` / `idleCompactionMinTokens` / `idleRetainTokens`,1–43200 分钟自定义、供应商缓存参考说明及设置保存/恢复免重启 DSH)。
22
+ - **摘要结构解包与标量审计加固**:`unwrapJsonSectionMap` 新增对单键 JSON 包装(如 `{"handoff": "## 1. ..."}`)与围栏感知四节续传标题的安全解包,并修正 `lib/audit.js` 中“判别”复合词否定边界、行内反引号/加粗剥离(保留 `8080**2` 幂运算)及 ``基线:`listenPort 9443` `` 等空格分隔标量识别,消除切换测试中首轮结构或标量误拒重试。
23
+ - **事务备份、检索优化与全套验证**:`.rollback` 改为单趟流式复制兼 SHA-256(`2.1 MB` 提交提速 `14.2%`),归档检索支持多词并查与附件 stat 快检;新增 `test/release-billing-safety.mjs`(9 项资金/额度熔断与入口校验)、`test/astra-review-fixes.mjs`(20 项专项回归)及宿主兼容降级集成校验,全量实测 **51 套活动套件、1059 项断言 0 失败**(44 套离线 941 项 + 7 套 DSH `0.2.2-rc.3` 宿主 118 项)。完成无失真三组真实 Magpie 网关评测(**Gemini 4 Argon / GLM-5.3-Flash / DeepSeek-V4.1-Flash / GPT-6.1 Sol**,其中 `auto/gpt-6-astra` 在官方 Codex CLI 下深度参与代码与基准审计,因网关仅限 Codex 客户端直接访问 `auto/gpt-6-astra`,DSH HTTP 对标槽位依不伪造请求头原则分别采用 `2-2/gpt-6.1-sol` 与 `auto/gpt-6.1-sol`):32 分支单模型独立对标(Weave `8/8`、**175/176 = 99.43%**,`w2` 零调用均耗时 `35.8 ms`)、5 轮连续压缩 `C1–C5` × `R1–R6` 缓存恢复与速度对标(`R2–R6` 稳态命中 `97%–99%`,GLM 压缩总耗时比 `dsh-basic` 快 `4.01×`),以及 19 次跨模型连续切换(Weave **4/4** 一次过审、`226/226 = 100%`),详见 [测试记录](docs/testing.md)、[docs/benchmarks/v0.3.2-tests.json](docs/benchmarks/v0.3.2-tests.json) 与 [docs/benchmarks/v0.3.2-live-four-way.json](docs/benchmarks/v0.3.2-live-four-way.json)。
24
+
25
+ ## 0.3.2-rc.4 — 2026-11-17
26
+
27
+ - 作为候选基线提交(`a41b41a`),引入“闲置后先压缩”(`idleCompactionMinutes`)预设与 1–43200 分钟自定义设置、设置损坏保护与运行期并发配置快照隔离、历史锚点/约束/状态修正,归档前通过 67 套 / 2064 项基线测试(留存于 `docs/benchmarks/rc4-tests.json`)。
28
+
29
+ ## 0.3.2-rc.3 — 2026-11-14
30
+
31
+ ### 宿主兼容与接口适配
32
+
33
+ - 将 `engines.dsh` 兼容范围扩宽为 `>=0.2.2-rc.1 <0.3.0-0`(覆盖 `0.2.2-rc.1` 起的 `0.2` 系列含预发布版,不含 `0.3.0` 预发布版)。
34
+ - 核验并纳入 DSH `0.2.2-rc.2` / `0.2.2-rc.3` 新增批量输入与单事件快照校验辅助函数后的 `Session.append` 实现指纹(保留 `0.2.2-rc.1` 指纹);`Session.commit`、`Session.publicationEntry`、`SurfaceManager.validateNext`、`SurfaceManager._processDelta`、JSONL 后端与句柄受检方法、官方 `/compact` 命令及 `token-meter` 实现保持不变。
35
+ - 诊断元数据中的 `supportedDshVersion` 现记录兼容范围字符串 `>=0.2.2-rc.1 <0.3.0-0`,`actualDshVersion` 保持 `null`(可在反馈时手动补充实际宿主版本)。
36
+ - 未知宿主写入实现仍会在发起摘要请求或执行事务性历史替换前拒绝压缩,并保留已有恢复材料;本次不改动压缩、冷读、预热或重生成策略。
37
+
38
+ ### 测试与 CI
39
+
40
+ - 新增真实宿主事务与版本范围测试套件(8 项检查):覆盖 `rc.1` / `rc.2` / `rc.3` 及后续 `0.2` 范围准入、旧版与 `0.3` 预发布版拒绝、原生持久化提交与本地归档回读及重开、提交前失败回滚、提交后发布异常保留持久化结果并在冷启动时清理决策、物理尾部中断从已校验备份恢复并关闭生命周期后重开、未知 `append` 在摘要请求前拒绝,以及批量/单条 `append` 后的完整压缩与回读(不调用付费模型)。
41
+ - 实测通过全部离线(50 套、1597 项)与真实宿主集成(6 套、101 项)共 **56 套、1698 项**测试(0 失败):Windows(Node.js 24.21.0)分别完成 DSH `0.2.2-rc.1` 与 `0.2.2-rc.3` 实测,Linux(Node.js 24.9.0)分别完成 DSH `0.2.2-rc.2` 与 `0.2.2-rc.3` 实测;明细记录于 `docs/benchmarks/rc3-host-compatibility.json`。
42
+ - GitHub Actions 保留原有离线矩阵,并新增 Windows / Linux × DSH `0.2.2-rc.1` / `0.2.2-rc.3` 隔离宿主测试矩阵。
43
+
44
+ ## 0.3.2-rc.2 — 2026-11-14
45
+
46
+ ### 修复
47
+
48
+ - 修正已复现的要求与进度审计误拒:明确关联来源序号和被最新进度取代的旧快照,区分历史转述、当前状态、缺少证据与未来动作,减少合格摘要的重复生成。
49
+ - 保留参数修订、独立禁止事项及协调动作列表中的否定范围;转折后的新相反动作、错误当前值和错误下一步仍会被拦截。
50
+ - 将产物完成谓语与第一步动作绑定到所属工作项,避免报告、图表和扫描状态串扰;已有原始来源 ID、哈希与存储格式保持兼容。
51
+ - 摘要服务未返回 `usage` 或失败时适配器合成全零用量时,传入 `null` 并将尝试记录标记为 `usageKnown: false`(不写入虚构零用量字段);成功响应返回的真实零用量、正数与缓存用量仍正常保留。
52
+ - 补齐真实失败摘要重放与否定范围、旧快照边界回归;“并非……”“不是……而是已被取代”等复杂中文间接否定仍为已知识别边界。
53
+ - 移除旧版独立的 `/context-continue` 手动接续命令注册及提示;常规 `/compact` 与后台分页接续机制继续保留,支持已完成页面恢复及有限重试预算。
54
+ - 失败诊断采用白名单字段补充运行环境、会话与摘要配置路由、有效设置、输入估算、重试等待与失败分类(`failureKind`);确定性重建成功后保留关联的 `auditReports` 审计记录索引。
55
+
56
+ ### 策略与验证
57
+
58
+ - 保持既有增量压缩与必要时完整合并策略,压缩后首答保持正常冷读、不额外预热;后半段检查点局部合并实验未获得跨模型一致收益,未设为默认。
59
+ - 配对费用实验计入内容、格式、语义及审计误拒导致的重生成(含未完成的内容失败分支)与压缩后 6 次接续回答,排除网络、供应商、限流、超时与断流请求失败。DeepSeek、GPT、Gemini 按返回 `usage` 与记录的网关单价估算;GLM 测试使用免费额度,未核查适用结算单价和实际账单,仅将真实返回的 `usage` 套入 DeepSeek 网关单价做情景估算。
60
+ - 最终代码在 Windows(Node.js 24.21.0、DSH 0.2.2-rc.1)通过 55 套、1690 项回归(含宿主集成),在 Linux(Node.js 24.9.0)通过 50 套、1597 项离线回归,均 0 失败。在移除独立 `/context-continue` 命令及调整诊断元数据前,基于内部 `rc.1` 打包构建完成的 **Gemini 4 Argon → GLM → DeepSeek → GPT** 联网验收共执行 4 次压缩(各 1 次摘要请求,无重生成)、24 次模型切换与 60 次 HTTP 请求,728 / 728 个状态字段和 77 / 77 项流程结构检查通过。
61
+
62
+ ### 文档与发布
63
+
64
+ - 修订中英文 README 与原理、测试、排障、反馈文档,集中说明适用边界、诊断字段含义与隐私注意事项。
65
+ - 增补双语工作原理讲解与三组静态 SVG 示意图,核对窗口预算公式、第六节近期原话预算、单目标路由、双重严格缩小检查与四类故障恢复边界。
66
+ - 整理测试记录中的条件总览表、四模型配对费用主表(逐次 token 明细收归 JSON 产物)、GLM 代理单价情景估算说明及 `0.3.1-review.35` 历史测试记录。
67
+ - 优化中英文 Issue 模板与脱敏指南:明确日志附件完全可选、保留云端 AI 分享与人工复查隐私提醒,内置跨文件一致的“信息类型+编号”脱敏提示词。
68
+ - 提供安装包、源码包、逐文件清单和 SHA-256 校验值。
69
+
70
+ ## 0.3.2-rc.1
71
+
72
+ ### 修复
73
+
74
+ - 修正“进度报告:扫描已完成”被误认为报告产物完成的情况。
75
+ - 区分缺少完成证据、禁止声称完成与真正的完成声明。
76
+ - 区分是否要求生成产物与产物当前是否完成。
77
+ - 识别“生成后再更新字段”的未来动作,以及最新来源之后的假设性变化。
78
+ - 将字段未知判断限制在对应字段,避免跨批次问题覆盖已知文件数量。
79
+ - 正确识别“不允许修改”“不实际修改”等否定要求。
80
+ - 保持转折后的当前状态、错误数量和相反要求检查;原始事实身份与来源记录保持兼容。
81
+
82
+ ### 发布整理
83
+
84
+ - 新增完整中英文 README、五组双语文档、项目徽章及下载入口。
85
+ - 配置 Windows / Linux GitHub Actions,执行测试、项目检查与打包验证;文件占用回归分别检查平台的重试与原错误保留行为。
86
+ - 整理并在文档中引用 `0.3.1-review.35` 历史实测的平均输入缩减 68.50% 口径、逐次 token 数据和复算公式。
87
+ - 增加中英文 Issue 模板,收集报错、回答质量下降和压缩后遗忘反馈。
88
+ - 建立源码、测试、脚本与文档的标准目录。
89
+ - 重写 README,补充配置、架构、故障排查和开发文档。
90
+ - 提供统一离线测试与可选 DSH 宿主集成测试入口。
91
+ - 添加发布内容检查、运行包、源码包与 SHA-256 清单。
92
+ - 诊断版本从包元数据读取,减少手动版本同步。
93
+
94
+ ## 0.3.1-review.35
95
+
96
+ - 增量保留已有检查点和稳定前缀,在需要时合并摘要。
97
+ - 支持用户要求的修订、取消、去重与近期原话预算。
98
+ - 保存工作报告与进度来源,支持完整历史和附件回查。
99
+ - 支持大段历史的分页接续、持久化进度及恢复。
100
+ - 增加摘要失败重试、等待上限、错误提示和诊断。
101
+ - 提供摘要模型、触发比例、最小压缩幅度及重试参数设置页。
102
+
103
+ 官方接口实测记录及后续修复见 [测试记录](docs/testing.md)。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-compaction-weave contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,145 @@
1
+ <div align="center">
2
+
3
+ # DSH Compaction Weave
4
+
5
+ **Compact context. Keep requirements. Carry work forward.**
6
+
7
+ A context-compaction plugin for DeepSeek Harness that keeps long conversations focused on the current goal, active constraints, and the next step.
8
+
9
+ [简体中文](README.md) · [English](README.en.md)
10
+
11
+ [![Release](https://img.shields.io/github/v/release/NightFrost42/dsh-compaction-weave?style=flat-square&color=5865F2)](https://github.com/NightFrost42/dsh-compaction-weave/releases/latest)
12
+ [![npm](https://img.shields.io/npm/v/dsh-compaction-weave/latest?style=flat-square&color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/dsh-compaction-weave)
13
+ [![CI](https://img.shields.io/github/actions/workflow/status/NightFrost42/dsh-compaction-weave/ci.yml?style=flat-square)](https://github.com/NightFrost42/dsh-compaction-weave/actions/workflows/ci.yml)
14
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.2.2--rc.1%20%3C1.0.0--0-4D6BFE?style=flat-square)](docs/en/configuration.md)
15
+ [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A524.9-339933?style=flat-square&logo=node.js&logoColor=white)](docs/en/development.md)
16
+ [![License: MIT](https://img.shields.io/badge/License-MIT-22A06B?style=flat-square)](LICENSE)
17
+ [![Languages](https://img.shields.io/badge/docs-English%20%7C%20%E4%B8%AD%E6%96%87-0F766E?style=flat-square)](README.md)
18
+
19
+ Incremental compaction · Requirement retention · History lookup · Audit checks · Diagnostics
20
+
21
+ [Install & upgrade](#installation-and-upgrade) · [Quick start](#quick-start) · [Principles](docs/en/principles.md) · [Basic settings](#basic-settings) · [Tests & verification](#tests-and-verification) · [Diagnostics & feedback](#diagnostics-and-feedback) · [Changelog](CHANGELOG.md)
22
+
23
+ </div>
24
+
25
+ ## Why Weave?
26
+
27
+ Long sessions accumulate tool outputs, logs, superseded plans, and repeated discussion. Under the default configuration, DSH Compaction Weave uses a **two-stage approach — fold oversized tool outputs cheaply first, summarize only when needed** — to preserve **the current task, active user requirements, completed progress, and the next step**, while archiving original messages and attachments locally for on-demand lookup.
28
+
29
+ - **Two-stage compaction & same-route prefix reuse**: Non-error tool outputs longer than `4000` characters outside the recent tail are archived and folded into compact head/tail previews with `history_read` pointers first, skipping LLM calls whenever folding alone meets the target. When summarization is required, stable prefixes and prior checkpoints stay intact, and same-model requests keep the live prefix unchanged within budget to stay KV-cache friendly.
30
+ - **Channel isolation & requirement/progress checks**: Uses host event roles and explicit tags (`<untrusted_reference>`, `<quoted_text>`) to tell genuine user instructions apart from logs, fetched pages, and tool outputs, while independently checking numbers, conditions, prohibitions, approval provenance, target scopes, and explicit `key: value` progress fields.
31
+ - **Resumable paging and direct archive lookup**: Splits oversized histories into resumable pages persisted on disk; standard checkpoints carry `History archive` pointers and touched file paths for targeted queries via `history_list`, multi-term `history_search`, and `history_read`.
32
+
33
+ ## How compaction works
34
+
35
+ When context reaches the trigger threshold, resumes after idle time, or receives a compaction request under default archiving, Weave first checks whether folding bulky older tool outputs is enough on its own. Otherwise it selects a tool-balanced span of earlier history, requests a structured candidate summary, and deterministically fills bounded recent verbatim user quotes into the checkpoint. Once structure, dual size reduction, active requirements, approval provenance, and `key: value` progress checks pass, Weave writes original events to the local archive, verifies host method fingerprints, creates a single-pass hashed backup, and transactionally replaces the visible span. See [Compaction principles and diagrams](docs/en/principles.md) for the full pipeline, budget formulas, archive boundaries, and recovery rules.
36
+
37
+ ## Installation and upgrade
38
+
39
+ Supports **DeepSeek Harness `>=0.2.2-rc.1 <1.0.0-0`** (`0.2.x–0.x` from `0.2.2-rc.1`), with native atomic transactions verified against **DSH `0.2.2-rc.1`, `0.2.2-rc.2`, and `0.2.2-rc.3`** on **Node.js 24.9+**, plus graceful fallback (`strictHostFingerprints: false` default) to public `Session.append(replace)` + `sessions.flush()` across minor DSH updates while still blocking unrecovered `.rollback`/`.tail` atomic journals. Stable releases are published to **[npm (`latest`)](https://www.npmjs.com/package/dsh-compaction-weave)** and [GitHub Releases](https://github.com/NightFrost42/dsh-compaction-weave/releases/latest): installing `dsh-compaction-weave` from npm is recommended so DSH can track `latest` updates automatically without `allowBuilds` prompts; manual installs using `dsh-compaction-weave.tgz` (versionless latest asset), `dsh-compaction-weave-0.3.4.tgz`, or a locally built `.tgz` remain supported as well.
40
+
41
+ ### Desktop
42
+
43
+ - **Install from npm / plugin market (recommended for automatic updates)**: install `dsh-compaction-weave` via `dsh-market` (or enter package name `dsh-compaction-weave` under **Plugins → Add plugin**) to track the npm `latest` release channel.
44
+ - **Manual `.tgz` install / upgrade**:
45
+ 1. Download `dsh-compaction-weave.tgz` or `dsh-compaction-weave-0.3.4.tgz` from [Releases](https://github.com/NightFrost42/dsh-compaction-weave/releases/latest).
46
+ 2. When upgrading, uninstall the existing Weave package on the **Plugins** page first while keeping archives and settings in the independent storage directory. Skip this step for a fresh installation.
47
+ 3. Open **Plugins → Add plugin**, enter the absolute path to the package (for example `C:/Downloads/dsh-compaction-weave-0.3.4.tgz`), then install and enable it.
48
+ 4. **Restart DSH** and verify the version on the plugin details page.
49
+
50
+ ### Command line
51
+
52
+ Stop the target profile, then install or upgrade from npm (recommended — tracks `latest` and skips `allowBuilds`):
53
+
54
+ ```bash
55
+ dsh plugin --profile web add dsh-compaction-weave
56
+ ```
57
+
58
+ For offline or manual tarball installation, pass a local `.tgz` path instead:
59
+
60
+ ```bash
61
+ dsh plugin --profile web add /absolute/path/dsh-compaction-weave-0.3.4.tgz
62
+ ```
63
+
64
+ Replace `web` with your command-line profile name and restart that profile afterwards. Desktop users should follow the plugin manager steps above.
65
+
66
+ ## Quick start
67
+
68
+ Once enabled, chat normally. By default, Weave uses the active conversation model for summarization and automatically plans compaction as context approaches the trigger threshold (targeting at least a **20%** input reduction on automatic runs).
69
+
70
+ - **Manual compaction**: Type `/compact` in chat to compact immediately or resume a paused multi-page continuation.
71
+ - **Phase wrap-up request**: Ask the model to call `context_compact` after finishing a task phase. The tool returns `queued` to record the request; at the next safe step after the current tool batch finishes, Weave checks context growth and eligible span conditions, then either runs compaction (`compacted`, `partial`, or `failed`) or returns a non-compacting receipt such as `skipped` or `blocked`. Check the follow-up receipt for the outcome.
72
+ - **Look up original history**: When you need earlier errors, file paths, or code details verified, ask or prompt the model—it can call these tools on demand to query the local archive:
73
+
74
+ | Tool | Purpose |
75
+ | --- | --- |
76
+ | `context_compact` | Queue a compaction request at a task boundary |
77
+ | `history_list` | List archived message ranges |
78
+ | `history_search` | Search archived history by keyword |
79
+ | `history_read` | Read original messages and attachments in pages |
80
+
81
+ ## Basic settings
82
+
83
+ Adjust common options under **Settings → Summary model** (or on the plugin details page). **Saving applies to subsequent operations without restarting DSH; an in-flight compaction keeps its original settings.**
84
+
85
+ | Setting | Default | Description |
86
+ | --- | --- | --- |
87
+ | Summary provider and model | Follow conversation | Leave blank to reuse the active chat model, or configure a dedicated summary model |
88
+ | Summary output limit | 8192 tokens | Maximum output length allowed for a single summary response |
89
+ | Automatic trigger ratio | 80% | Combined with next-reply output reservation and headroom to set the trigger threshold |
90
+ | Minimum reduction | 20% | Target input space reduction for automatic compaction planning |
91
+ | Retry count | 2 | Up to 2 additional attempts after an initial failure |
92
+ | Base retry delay | 1 second | Exponentially backed-off wait between retries (capped at 30 seconds) |
93
+ | Per-request timeout | 180 seconds | Timeout limit for each summary request |
94
+ | Compact after inactivity | Off | Presets or custom 1–43200 minutes (30 days); compact existing history before resuming after the interval |
95
+
96
+ Retry settings take effect independently of summary model selection. See [Configuration](docs/en/configuration.md) and [Compaction principles and diagrams](docs/en/principles.md) for prefix preservation, verbatim quote budgets, summary language (`auto` / `zh` / `en`), continuation paging options, and the restrictions when local archiving is disabled (`archiveEnabled: false`).
97
+
98
+ ## Tests and verification
99
+
100
+ - **Stable release `0.3.2` (after the 2026-11-19 host-compatibility relaxation, two-stage compaction, channel-isolation refactor, JSON-wrapper unwrapping, and billing-safety stress tests)**: **51 active suites / 1,059 checks passed with 0 failures** against DSH `0.2.2-rc.3` on Windows (**44 offline suites / 941 checks** including 20 checks in `astra-review-fixes.mjs` and 9 billing/entry checks in `release-billing-safety.mjs`, plus **7 real-host integration suites / 118 checks** covering `strictHostFingerprints: false` graceful fallback and atomic journal refusal); in paired benchmarks against `v0.3.2-rc.4` (`a41b41a`), heavy tool-output compaction cut summary LLM calls from `1` to `0` (`7,329.35 ms → 19.36 ms`), same-route verbatim KV prefix preservation rose from `60%` (`654 B`) to `100%` (`12,215 B`), structured `key: value` validation sped up ~`108×` (`1.08 ms → 0.01 ms`), native `2.1 MB` host transaction commit sped up `14.2%`, and runtime `lib/` bytes dropped `2.66%` (`748,804 → 728,876 B`) — see [Per-suite results and improvement benchmark](docs/benchmarks/v0.3.2-tests.json). 21 legacy synthetic-vocabulary and natural-language regex suites remain archived under [`test/archived-regex/`](test/archived-regex/README.md) outside default runs, and the pre-archive baseline (67 suites / 2,064 checks) stays recorded in [Per-suite baseline results](docs/benchmarks/rc4-tests.json).
101
+
102
+ - **Four-model × four-system distortion-free live gateway benchmark (2026-11-19 single-run observations, [`docs/benchmarks/v0.3.2-live-four-way.json`](docs/benchmarks/v0.3.2-live-four-way.json))**: Restored stock `dsh-basic` `headroomTokens: 65,536` (`CHAT_MAX_TOKENS=16384`), persistent `x-acp-session` + `ccr` + `<acp-nudge>` for `billion-context@0.1.216`, non-repetitive per-phase Node.js/SQL modules, and explicit `null` allowance for unverified fields. Because `auto/gpt-6-astra` only permits official Codex CLI clients directly (`HTTP 403` on plain DSH HTTP requests; used natively inside Codex MCP for code and benchmark audits, with no client spoofing), the DSH GPT slot ran `2-2/gpt-6.1-sol` in Suite A and `auto/gpt-6.1-sol` in Suite C alongside `auto/gemini-4-argon`, `auto/glm-5.3-flash`, and `deepseek/deepseek-flash`:
103
+ - **Suite A · Standalone 32 branches** (4 models × 4 systems × `w1` evolving specs + `w2` tool-heavy debugging): **`weave-0.3.2` completed 8/8 with highest accuracy `175/176 (99.43%)`** — `144/144` on `w1` (`26.88 s` mean compaction vs `56.81 s` for `dsh-basic`, **`2.11×` faster**) and `31/32` on `w2` in **`35.8 ms`** (**`0` summary LLM calls**, `72.20%` mean effective/wire reduction, `$1.0821` Magpie / `$0.8539` norm); `rc.4` completed `5/8` (`3/4` `w1` branches failed `PROGRESS_FACT_CONFLICT`; `62/68 = 91.18%` conditional on completed, `62/176 = 35.23%` overall); `dsh-basic` finished `8/8` (`164/176 = 93.18%`) but fell to **`20/32 (62.50%)`** on `w2` (`ToolResultPruner` drops middle-of-file constants with no archive lookup); `billion-context` finished `8/8` at **`155/176 (88.07%)`** (`w2` **`11/32 = 34.38%`**, `0/8` on GPT & DeepSeek) with **`-13.95%` local wire bloat** at `$1.6899` / `$1.3999`.
104
+ - **Suite B · 5 continuous cycles (`C1–C5`) × 6 replies (`R1–R6`) cache recovery & speed**: Separates first post-compaction prefix write (`R1`: `0%` consolidation / `~33%` incremental) from steady-state recovery: **`weave-0.3.2` recovered KV cache hits to `97%–99%` across `R2–R6` through all 5 cycles on DeepSeek and GLM**, while hitting cache on compaction calls themselves (`85.94%–95.52%` DeepSeek, `37.68%–65.37%` GLM vs `0%` on `dsh-basic`). On DeepSeek: `100/100`, `45.99 s` compaction (`2.77×` faster than `rc.4`, `3.78×` vs `billion-context`), `$0.0419` (`billion-context` dropped to `88/100` with `-27.75%..-189.07%` bloat). On GLM: `100/100`, **`107.65 s` compaction (`4.01×` faster than `dsh-basic` `431.44 s`; `3.27×` vs `billion-context` `351.90 s`; `2.83×` faster e2e; `rc.4` failed)**.
105
+ - **Suite C · Continuous 19-switch rotation** (`Gemini → GLM → DeepSeek → auto/gpt-6.1-sol`, 226 checks): **`weave-0.3.2` passed 4/4 compactions on the first attempt (`4` calls, `0` retries), scored `226/226 (100%)` in `114.86 s` compaction (`400.74 s` e2e), `60.00%` mean wire reduction (`$0.6077` / `$0.4915`)**; `rc.4` failed Gen 4 GPT (`3/4`, `7` calls, `224.45 s` comp, `226/226` only because Gen 4 stayed uncompressed `-0.64%`); text-only `dsh-basic` scored `4/4` (`226/226`, `118.40 s` comp / `327.88 s` e2e, `$0.5935` / `$0.4811`, without verbatim Section 6 or tool archive); `billion-context` ran `15` compaction calls and `48` HTTP calls (`875.97 s` e2e = `2.19×` slower), expanded `-36.31%` in Gen 1, and cost `$0.8260` / `$0.6873`.
106
+
107
+ - **Offline and host regression**: `0.3.2-rc.3` passed **56 suites with 1,698 checks** (**50 offline suites with 1,597 checks** plus **6 real-host integration suites with 101 checks**, including 8 new checks for native transactional commit/rollback, range admission, and unknown-method refusal) on Windows (Node.js 24.21.0 with DSH `0.2.2-rc.1` and `0.2.2-rc.3`) and on Linux (Node.js 24.9.0 with DSH `0.2.2-rc.2` and `0.2.2-rc.3`), all with 0 failures; see [`docs/benchmarks/rc3-host-compatibility.json`](docs/benchmarks/rc3-host-compatibility.json).
108
+ - **Four-model live cross-switch acceptance**: Live testing on the internal `0.3.2-rc.1` build prior to removing the legacy manual continuation command and adding diagnostic metadata covered **Gemini 4 Argon → GLM → DeepSeek → GPT**, completing 4 compactions (1 summary call each), 24 model switches, and 60 HTTP requests with **728 / 728** state fields and **77 / 77** workflow and structure checks passing.
109
+ - **Strategy and cost evaluation**: Paired experiments compared the existing incremental and full-consolidation policy against an experimental partial-consolidation candidate across compaction and 6 follow-up replies, counting content and false-rejection regenerations while excluding network and provider request failures. The existing policy proved more consistent across models and remains the default, without post-compaction prewarming.
110
+
111
+ Compaction produces a lossy summary backed by on-demand archive lookup, and input token reduction differs from actual billing changes depending on cache hits, regenerations, and provider pricing. See [Testing](docs/en/testing.md) for full experimental conditions, the GLM proxy-rate cost scenario, and historical records.
112
+
113
+ ## Diagnostics and feedback
114
+
115
+ If you encounter an error, an unexpected summary rejection, or missing context after compaction:
116
+
117
+ 1. Open [GitHub Issues](https://github.com/NightFrost42/dsh-compaction-weave/issues/new/choose), choose the English or Chinese template, and describe the symptom, reproduction steps, and expected behavior.
118
+ 2. **Log attachments are optional.** Attaching the diagnostic file for the failed operation usually speeds up troubleshooting; diagnostics already record the plugin version, declared DSH version range `supportedDshVersion` (`actualDshVersion` remains `null`, so you can still note your actually installed DSH version in the issue), configured model routes, effective settings, attempts, error categories, and returned usage automatically.
119
+ 3. **Privacy notice:** Diagnostic logs and linked audit records may contain local paths, conversation text, or business data. Sending original files to a cloud AI is itself an external disclosure, and AI redaction can miss sensitive details or alter evidence. Always review redacted copies yourself before submitting, and omit attachments if unsure. See [Reporting issues and redacting logs](docs/en/feedback.md) for details and the redaction prompt.
120
+
121
+ ## Documentation and development
122
+
123
+ | English | 简体中文 |
124
+ | --- | --- |
125
+ | [Configuration](docs/en/configuration.md) | [配置指南](docs/configuration.md) |
126
+ | [Compaction principles & diagrams](docs/en/principles.md) | [压缩原理与示意图](docs/principles.md) |
127
+ | [Architecture](docs/en/architecture.md) | [代码导航](docs/architecture.md) |
128
+ | [Reporting & redaction](docs/en/feedback.md) | [提交问题与日志脱敏](docs/feedback.md) |
129
+ | [Troubleshooting](docs/en/troubleshooting.md) | [故障排查](docs/troubleshooting.md) |
130
+ | [Testing](docs/en/testing.md) | [测试记录](docs/testing.md) |
131
+ | [Development & releases](docs/en/development.md) | [开发与发布](docs/development.md) |
132
+
133
+ The project uses native JavaScript ES modules with no build step:
134
+
135
+ ```bash
136
+ git clone https://github.com/NightFrost42/dsh-compaction-weave.git
137
+ cd dsh-compaction-weave
138
+ npm test
139
+ npm run check
140
+ npm run pack:release
141
+ ```
142
+
143
+ ## License
144
+
145
+ [MIT](LICENSE)
package/README.md CHANGED
@@ -1,3 +1,149 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # DSH Compaction Weave
4
+
5
+ **压缩上下文,保留要求,延续工作。**
6
+
7
+ 面向 DeepSeek Harness 的上下文压缩插件,让长对话带着明确的目标、有效约束和下一步继续推进。
8
+
9
+ [简体中文](README.md) · [English](README.en.md)
10
+
11
+ [![Release](https://img.shields.io/github/v/release/NightFrost42/dsh-compaction-weave?style=flat-square&color=5865F2)](https://github.com/NightFrost42/dsh-compaction-weave/releases/latest)
12
+ [![npm](https://img.shields.io/npm/v/dsh-compaction-weave/latest?style=flat-square&color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/dsh-compaction-weave)
13
+ [![CI](https://img.shields.io/github/actions/workflow/status/NightFrost42/dsh-compaction-weave/ci.yml?style=flat-square)](https://github.com/NightFrost42/dsh-compaction-weave/actions/workflows/ci.yml)
14
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.2.2--rc.1%20%3C1.0.0--0-4D6BFE?style=flat-square)](docs/configuration.md)
15
+ [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A524.9-339933?style=flat-square&logo=node.js&logoColor=white)](docs/development.md)
16
+ [![License: MIT](https://img.shields.io/badge/License-MIT-22A06B?style=flat-square)](LICENSE)
17
+ [![Languages](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87%20%7C%20English-0F766E?style=flat-square)](README.en.md)
18
+
19
+ 增量压缩 · 要求保留 · 历史回查 · 审计校验 · 故障诊断
20
+
21
+ [安装与升级](#安装与升级) · [快速上手](#快速上手) · [压缩原理](docs/principles.md) · [基本设置](#基本设置) · [测试与验证](#测试与验证) · [诊断与反馈](#诊断与反馈) · [更新日志](CHANGELOG.md)
22
+
23
+ </div>
24
+
25
+ ## 用途与能力
26
+
27
+ 长对话会逐步积累工具输出、日志、旧方案和重复讨论。默认配置下,DSH Compaction Weave 采用**“先轻折超大工具输出、不够再总结对话”**的两级整理策略,在检查点中保留**当前任务、仍有效的用户要求、已完成进度和下一步动作**,同时把被替换的原始消息与附件写入本地归档,供后续按需检索与分段读取。
28
+
29
+ - **两级整理与同路由缓存复用**:近期尾部之外超过 `4000` 字的非报错工具结果会先归档并折叠为“开头 + 结尾预览 + `history_read` 指引”,若空间已够直接结束、无需调用总结模型;确实需要总结时,优先保留稳定前缀与已有检查点,同模型路由在预算内原样保持请求前缀,尽量命中服务商缓存。
30
+ - **通道隔离与要求进度校验**:基于宿主事件角色与 `<untrusted_reference>` / `<quoted_text>` 等显式标签区分真实用户指令与外部引用,避免把网页正文、日志或工具返回误当成用户命令;独立核对数值、条件、禁止事项、授权出处、作用对象与显式 `key: value` 结构化任务进度。
31
+ - **分页接续与归档回查**:遇到超长历史或单次容量受限时,可按页保存已完成进度并接续处理;标准检查点自动携带 `History archive` 指针与涉及文件列表,配合 `history_list`、多词 `history_search` 与 `history_read` 按需精准回查。
32
+
33
+ ## 压缩是怎样工作的
34
+
35
+ 当上下文接近触发线、闲置超时或收到压缩指令时,在开启归档的默认配置下,插件会先评估能否只靠折叠旧的超大工具输出达标;不够或需要总结时,再选出工具调用完整配对的历史区间,生成结构化候选摘要,并把预算内的近期用户原话确定性填入检查点。候选检查点通过结构、体积缩小、有效要求、授权出处与 `key: value` 进度核对后,插件先把原始事件写入本地归档,核验宿主存储方法指纹并完成单趟哈希备份后,以事务方式替换当前可见历史。完整流程、数学预算、归档开关边界和恢复机制见 [压缩原理与示意图](docs/principles.md)。
36
+
37
+ ## 安装与升级
38
+
39
+ 支持 **DeepSeek Harness `>=0.2.2-rc.1 <1.0.0-0`**(`0.2.2-rc.1` 起的 `0.2.x–0.x` 系列),原生原子事务已实测 **DSH `0.2.2-rc.1`、`0.2.2-rc.2`、`0.2.2-rc.3`**,并在默认 `strictHostFingerprints: false` 下支持宿主后续小版本调整私有持久化方法时平顺降级至公开 `Session.append(replace)` + `sessions.flush()`(同时继续拦截未恢复 `.rollback`/`.tail` 日志),运行环境需 **Node.js 24.9+**。正式版已同步发布到 **[npm(`latest`)](https://www.npmjs.com/package/dsh-compaction-weave)** 与 [GitHub Releases](https://github.com/NightFrost42/dsh-compaction-weave/releases/latest):优先推荐通过 npm 安装 `dsh-compaction-weave`(自动跟踪 `latest` 更新提示并免除 `allowBuilds` 构建授权),也可使用 Releases 页面提供的 `dsh-compaction-weave.tgz`(无版本号最新包)、`dsh-compaction-weave-0.3.4.tgz` 或本地打包生成的 `.tgz` 文件。
40
+
41
+ ### 桌面端
42
+
43
+ - **通过 npm / 插件市场安装(推荐,可自动获取更新)**:在 `dsh-market` 搜索或点击安装 `dsh-compaction-weave`(或使用 **插件 → 添加插件** 安装 npm 包名 `dsh-compaction-weave`),后续将自动跟踪 npm `latest` 标签提示升级。
44
+ - **通过离线 `.tgz` 手动安装 / 升级**:
45
+ 1. 从 [Releases 页面](https://github.com/NightFrost42/dsh-compaction-weave/releases/latest) 下载 `dsh-compaction-weave.tgz` 或 `dsh-compaction-weave-0.3.4.tgz`。
46
+ 2. 升级安装时,先在 **插件** 页面卸载旧版 Weave,保留独立存储目录中的历史归档与设置;首次安装可跳过此步。
47
+ 3. 打开 **插件 → 添加插件**,填入安装包绝对路径(如 `C:/Downloads/dsh-compaction-weave-0.3.4.tgz`),完成安装并启用。
48
+ 4. **重启 DSH**,在插件详情页确认版本号已更新。
49
+
50
+ ### 命令行
51
+
52
+ 停止目标 profile 后执行安装或覆盖升级。推荐直接从 npm 安装(自动绑定 `latest` 并免 `allowBuilds`):
53
+
54
+ ```bash
55
+ dsh plugin --profile web add dsh-compaction-weave
56
+ ```
57
+
58
+ 如需离线安装或手动指定版本 `.tgz` 包,也可改用本地文件路径:
59
+
60
+ ```bash
61
+ dsh plugin --profile web add /absolute/path/dsh-compaction-weave-0.3.4.tgz
62
+ ```
63
+
64
+ 请将 `web` 替换为实际使用的命令行 profile 名称,完成后重新启动该 profile。桌面端用户请参考上方的插件管理页流程。
65
+
66
+ ## 快速上手
67
+
68
+ 插件启用后即可正常对话。默认情况下,Weave 跟随当前会话模型生成摘要,并在上下文接近阈值时自动规划压缩(自动模式以释放至少 **20%** 输入空间为规划目标)。
69
+
70
+ - **手动触发**:在对话框输入 `/compact` 立即尝试压缩,或在后台分页暂停后继续剩余页面。
71
+ - **阶段收尾申请**:可让模型在完成阶段任务后调用 `context_compact` 提交申请。工具返回 `queued` 表示已进入队列,插件会在当前工具批次结束后的安全步骤检查上下文增长与可压缩区间,满足条件时执行压缩并返回 `compacted`、`partial` 或 `failed`,不满足条件或插件已停止时返回 `skipped`、`blocked` 等最终回执;查看后续回执即可确认结果。
72
+ - **回查原文**:需要核对早期报错、路径或代码细节时,可提醒或直接向模型提问,模型可按需调用以下工具检索本地归档:
73
+
74
+ | 工具 | 作用 |
75
+ | --- | --- |
76
+ | `context_compact` | 在阶段任务边界排队申请上下文压缩 |
77
+ | `history_list` | 查看已归档的历史消息区间 |
78
+ | `history_search` | 按关键词检索已归档历史 |
79
+ | `history_read` | 分段读取原始消息与附件内容 |
80
+
81
+ ## 基本设置
82
+
83
+ 在 **设置 → 摘要模型**(或插件详情页)中修改常用项,**保存后无需重启 DSH,后续操作使用新设置;进行中的压缩保留原设置**。
84
+
85
+ | 设置项 | 默认值 | 说明 |
86
+ | --- | --- | --- |
87
+ | 摘要供应商和模型 | 跟随会话 | 留空时复用当前对话模型,也可单独指定摘要模型 |
88
+ | 摘要输出上限 | 8192 tokens | 单次摘要响应允许的最大输出长度 |
89
+ | 自动压缩触发比例 | 80% | 与主回答输出预留和提前量共同决定实际触发线 |
90
+ | 最小压缩幅度 | 20% | 自动压缩规划期望释放的输入空间比例 |
91
+ | 失败重试次数 | 2 次 | 首次请求失败后最多追加尝试 2 次 |
92
+ | 重试基础间隔 | 1 秒 | 连续重试时按指数退避延长等待(上限 30 秒) |
93
+ | 每次摘要等待上限 | 180 秒 | 单次摘要请求的超时时间 |
94
+ | 闲置后先压缩 | 关闭 | 预设或自定义 1–43200 分钟(30 天);超过间隔后先压缩已有历史再继续 |
95
+
96
+ 重试设置可独立于摘要模型生效。前缀保留、近期原话预算、摘要语言(自动 / 中文 / 英文)、后台分页参数,以及关闭本地归档(`archiveEnabled: false`)时的功能限制见 [配置指南](docs/configuration.md) 与 [压缩原理与示意图](docs/principles.md)。
97
+
98
+ ## 测试与验证
99
+
100
+ - **正式版 `0.3.2`(2026-11-19 宿主兼容放宽、两级整理、通道隔离、JSON 解包与计费保护后)**:Windows / Node.js / DSH `0.2.2-rc.3` 实测全部 **51 套活动套件、1,059 项断言全部通过,0 失败**(包含 **44 套离线单元测试 / 941 项** 与 **7 套真实 DSH `0.2.2-rc.3` 宿主集成测试 / 118 项**,含 `strictHostFingerprints: false` 降级与阻断测试、20 项修复回归 `astra-review-fixes.mjs` 及 9 项资金/额度熔断压测 `release-billing-safety.mjs`);与 `v0.3.2-rc.4`(`a41b41a`)配对基准实测重工具输入省下 100% 摘要调用(`1 → 0` 次、`7329.35 ms → 19.36 ms`)、同路由原样前缀从 `60%`(`654 B`)提升至 `100%`(`12,215 B`)、结构化进度校验提速约 `108×`、`2.1 MB` 原生事务提交提速 `14.2%`,运行库体积净减 `2.66%`(`748,804 → 728,876 B`),详见 [逐套结果与提升对比](docs/benchmarks/v0.3.2-tests.json)。此前强绑定特定业务词表与旧自然语言猜测正则的 21 套历史测试已归档至 [`test/archived-regex/`](test/archived-regex/README.md),退出日常测试入口;重构前基线快照(67 套、2064 项)留存于 [逐套结果基线](docs/benchmarks/rc4-tests.json)。
101
+
102
+ - **四模型 × 四系统无失真真实网关对比基准(2026-11-19 单轮实盘观测,详见 [`docs/benchmarks/v0.3.2-live-four-way.json`](docs/benchmarks/v0.3.2-live-four-way.json))**:恢复 `dsh-basic` 原生满额 `headroomTokens: 65536` 与 `CHAT_MAX_TOKENS=16384`、为 `billion-context@0.1.216` 全程注入持久 `x-acp-session` + `ccr` 与 `<acp-nudge>` 并采用独立非重复代码/SQL 用例(未核实字段显式允许 `null`)。GPT 槽位因网关限制 `auto/gpt-6-astra` 仅官方 Codex 客户端可用(`Codex` 内已完成代码与基准对抗复核;DSH 普通 HTTP 请求不伪造客户端头),因此 Suite A 使用 `2-2/gpt-6.1-sol`、Suite C 使用 `auto/gpt-6.1-sol`(连同 `auto/gemini-4-argon`、`auto/glm-5.3-flash`、`deepseek/deepseek-flash`):
103
+ - **Suite A · 单模型独立 32 分支**(4 模型 × 4 系统 × `w1` 工程规格演进 + `w2` 重工具排障):**`weave-0.3.2` 8/8 全部完成且总分最高 `175/176 (99.43%)`**——`w1` 4/4 模型 `144/144`(压缩均耗时 `26.88 s`,比 `dsh-basic` `56.81 s` 快 `2.11×`)、`w2` `31/32` 仅耗 **`35.8 ms`**(**0 次摘要调用**,均有效/本地压缩 `72.20%`,总花 `$1.0821` / 标准化 `$0.8539`);`rc.4` 仅完成 `5/8`(3 组 `w1` 被旧 `PROGRESS_FACT_CONFLICT` 拦截,已完成 `62/68 = 91.18%`,占总测题 `62/176 = 35.23%`);`dsh-basic` 完成 `8/8` 但 `w2` 跌至 **`20/32 (62.50%)`**(`ToolResultPruner` 头尾截断永久丢弃文件中间常量且无归档工具);`billion-context` 完成 `8/8` 总分仅 **`155/176 (88.07%)`**(`w2` 跌至 **`11/32 (34.38%)`**,`gpt`/`deepseek` 均 `0/8`),本地请求反膨胀 **`-13.95%`**,耗资 `$1.6899` / `$1.3999`。
104
+ - **Suite B · 连续 5 次压缩(`C1–C5`)× 6 轮恢复(`R1–R6`)缓存与速度**:揭示压缩后首次缓存读与稳态恢复的真实规律——`R1` 为更换前缀后首次写入(合并归零、增量约 `33%`),自 `R2–R6` 起 **`weave-0.3.2` 在 DeepSeek 与 GLM 全部 5 轮均稳定恢复至 `97%–99%`**,且摘要调用自身持续命中前缀缓存(DeepSeek `compactionSelfPct` 达 **`85.94%–95.52%`**,GLM 增/合复用 **`37.68%–65.37%`**;`dsh-basic` 摘要自身始终 `0%`)。DeepSeek 上 `weave-0.3.2` `100/100`、压缩 `45.99 s`(快 `rc.4` `2.77×`、快 `billion-context` `3.78×`)、仅 `$0.0419`(`billion-context` 跌至 `88/100` 且全线倒挂 `-27.75%..-189.07%`);GLM 上 `weave-0.3.2` `100/100`、压缩仅 **`107.65 s`**(比 `dsh-basic` `431.44 s` 快 **`4.01×`**,比 `billion-context` `351.90 s` 快 **`3.27×`**,端到端快 **`2.83×`**,`rc.4` 则因预算溢出失败)。
105
+ - **Suite C · 四模型 19 次连续切换**(`Gemini → GLM → DeepSeek → auto/gpt-6.1-sol`,共 226 项检查):**`weave-0.3.2` 4/4 压缩全部一次过审(4 次摘要调用、0 重试)、`226/226 (100%)`、压缩 `114.86 s`(400.74 s 端到端)、四代平均压缩 `60.00%`(`$0.6077` / `$0.4915`)**;`rc.4` 第 4 代 GPT 失败(`3/4`、`7` 次摘要、`224.45 s`、`226/226` 系第 4 代未压缩直接回放);纯文本基线 `dsh-basic` `4/4`(`226/226`、压缩 `118.40 s`、`$0.5935` / `$0.4811`,不保第 6 节逐字原话与工具归档);`billion-context` 发起 `15` 次压缩与 `48` 次请求(端到端 `875.97 s` 慢 `2.19×`),第 1 代膨胀 `-36.31%`,总花 `$0.8260` / `$0.6873`。
106
+
107
+ - **离线与宿主回归**:`0.3.2-rc.3` 在 Windows(Node.js 24.21.0,分别搭配 DSH `0.2.2-rc.1` 与 `0.2.2-rc.3`)及 Linux(Node.js 24.9.0,分别搭配 DSH `0.2.2-rc.2` 与 `0.2.2-rc.3`)均通过 **56 套、1698 项**测试(其中离线 **50 套、1597 项**,真实宿主集成 **6 套、101 项**,含新增 8 项宿主事务、范围准入与未知实现拒绝检查),全部 0 失败;明细见 [`docs/benchmarks/rc3-host-compatibility.json`](docs/benchmarks/rc3-host-compatibility.json)。
108
+ - **四模型连续切换实测**:在移除旧手动接续命令并补充诊断元数据前的内部版本(`0.3.2-rc.1`)上,联网验收覆盖 **Gemini 4 Argon → GLM → DeepSeek → GPT**,连续完成 4 次压缩(每次 1 次摘要请求)、24 次模型切换与 60 次 HTTP 请求,**728 / 728** 个状态字段和 **77 / 77** 项流程结构检查全部通过。
109
+ - **策略与费用评估**:配对实验对比了既有增量与完整合并策略同实验性局部合并方案,计入内容不合格与误拒重生成及压缩后 6 次接续回答,排除网络和供应商请求失败。实测显示既有策略跨模型表现更稳健,因此保持既有策略且不在压缩后额外预热。
110
+
111
+ 上下文压缩属于有损摘要加按需归档回查,输入 tokens 缩减比例与实际账单变化受缓存命中、重生成和模型计费规则影响;完整实验条件、GLM 代理单价情景估算及历史测试结果见 [测试记录](docs/testing.md)。
112
+
113
+ ## 诊断与反馈
114
+
115
+ 遇到报错、摘要被拒或压缩后遗漏信息时,可按以下步骤排查与反馈:
116
+
117
+ 1. 在 [GitHub Issues](https://github.com/NightFrost42/dsh-compaction-weave/issues/new/choose) 选择中文或英文模板,描述问题现象、复现步骤与预期表现。
118
+ 2. **日志附件完全可选**。附上对应操作的诊断日志通常有助于更快定位问题;诊断文件已自动记录插件版本、支持的 DSH 版本范围 `supportedDshVersion`(`actualDshVersion` 仍为 `null`,可在 Issue 中补充实际安装的 DSH 版本)、配置的模型路由、有效设置、尝试记录、错误分类和返回用量,无需手动抄写。
119
+ 3. **隐私提示**:诊断日志与关联审计文件可能包含本地路径、对话原文或业务信息。将原始文件发给云端 AI 本身属于信息分享,AI 脱敏也可能遗漏敏感内容或改动关键证据。提交前请人工复查脱敏副本,拿不准时可不附日志。详细说明与脱敏提示词见 [提交问题与日志脱敏](docs/feedback.md)。
120
+
121
+ ## 文档与开发
122
+
123
+ | 简体中文 | English |
124
+ | --- | --- |
125
+ | [配置指南](docs/configuration.md) | [Configuration](docs/en/configuration.md) |
126
+ | [压缩原理与示意图](docs/principles.md) | [Compaction principles](docs/en/principles.md) |
127
+ | [代码导航](docs/architecture.md) | [Architecture](docs/en/architecture.md) |
128
+ | [提交问题与日志脱敏](docs/feedback.md) | [Reporting & redaction](docs/en/feedback.md) |
129
+ | [故障排查](docs/troubleshooting.md) | [Troubleshooting](docs/en/troubleshooting.md) |
130
+ | [测试记录](docs/testing.md) | [Testing](docs/en/testing.md) |
131
+ | [开发与发布](docs/development.md) | [Development & releases](docs/en/development.md) |
132
+
133
+ 项目采用原生 JavaScript ES modules,无需构建步骤,可在本地直接运行测试与打包:
134
+
135
+ ```bash
136
+ git clone https://github.com/NightFrost42/dsh-compaction-weave.git
137
+ cd dsh-compaction-weave
138
+ npm test
139
+ npm run check
140
+ npm run pack:release
141
+ ```
142
+
143
+ ## License
144
+
145
+ [MIT](LICENSE)
146
+
147
+ ---
148
+
149
+ 感谢 [LINUX DO](https://linux.do/) 提供技术交流与开源分享的社区空间。
@@ -0,0 +1,19 @@
1
+ # Register the configuration gate before loading agent presets.
2
+ - insert:
3
+ - id: compaction-weave-gate
4
+ name: dsh-compaction-weave
5
+ config:
6
+ mode: replace
7
+ engine: {}
8
+
9
+ - id: preset-standard
10
+ inject: [compactionWeaveGate]
11
+
12
+ - id: preset-ptc
13
+ inject: [compactionWeaveGate]
14
+
15
+ - id: preset-minimal
16
+ inject: [compactionWeaveGate]
17
+
18
+ - id: preset-cordis
19
+ inject: [compactionWeaveGate]
@@ -0,0 +1,84 @@
1
+ # 工作原理
2
+
3
+ [简体中文](architecture.md) · [English](en/architecture.md)
4
+
5
+ 面向使用者的完整讲解、数值例子、静态示意图和保证边界见 [压缩原理详解](principles.md)。本页用于代码导航。
6
+
7
+ ## 从历史到下一步
8
+
9
+ Weave 在 DSH 的会话维护阶段整理上下文。一次压缩按以下顺序执行:
10
+
11
+ 1. 读取当前消息表,测量输入规模;在开启归档、历史检索工具可用且开启 `observationMaskingEnabled` 时,优先把近期热尾之外超过 4000 字的非报错工具输出存入归档并折叠为首尾预览(`observation-mask.js`),若重新实测空间已降到触发线和目标内则直接结束、免调摘要模型,并附带 `history_read` 回查指针。
12
+ 2. 仍超水位时选出工具调用配对完整的历史区间;在保留热尾与压缩目标的前提下,当摘要路由与主对话一致且预算允许时启用 `preservePrefixCache` 原样前缀复用,避免破坏服务商 KV Cache。
13
+ 3. 从原始消息提取有效要求、近期原话、XML 通道隔离元数据(`source-provenance.js` / `instruction-source.js` / `reference-input.js`:`user` 与 `<untrusted_reference>` / `<channel-provenance>`)和最新工作报告,建立来源引用。
14
+ 4. 调用摘要模型生成候选;大段历史可分块,适用容量问题可进入后台分页接续。
15
+ 5. 检查完整候选的结构、要求、进度与大小,失败时有限重试;合格后归档选区原文与附件,并在标准检查点末尾写入 `History archive: <compactionId>` 指针与涉及文件列表。
16
+ 6. 核验事务条件,单趟拷贝兼哈希备份并持久化替换,写入成功决定后发布检查点;后续对话从更新后的上下文继续。
17
+
18
+ 常规多块流程逐块提交,后块失败时前块可能已经完成。分页接续保存已接受页面用于恢复,完整候选通过后才替换主历史。
19
+
20
+ ## 缓存策略
21
+
22
+ `cache-policy.js` 优先选择最后一个检查点之后的历史区间。已有检查点和保留前缀维持原有内容,只在后面追加新摘要。
23
+
24
+ 选择区间时同时考虑近期对话、摘要输出预算、原话预算、最新工作报告和最小释放空间。以下情况会切换到合并路径:
25
+
26
+ - 闲置恢复压缩主动关闭增量前缀保留;
27
+ - 已达到 `cacheMaxCheckpoints`;
28
+ - 新要求修订了旧检查点携带的要求;
29
+ - 增量区间无法释放所需空间。
30
+
31
+ 这样把前缀复用与上下文容量放在同一个决策里。服务端实际缓存量从模型返回的 usage 读取,测试记录单独展示压缩后的恢复过程。
32
+
33
+ ## 要求与来源
34
+
35
+ `memory-policy.js` 处理要求的生效、修订、取消与去重。近期原话遵循条数和 token 预算,仍有效的要求独立保留。
36
+
37
+ `audit.js` 检查要求的覆盖、数值、否定、条件和适用对象。测试环境与生产环境、不同文件及不同批次分别判断。
38
+
39
+ 原始事件号、文本片段和哈希共同标识来源。历史检查点中的生成文字不会成为新的原始要求;下一代压缩仍从经过核验的原始事件恢复依据。
40
+
41
+ 独立的“继续”等低信息原话可以移出检查点。取消上一条时仍按原始用户消息顺序定位,避免因为裁剪改变指代对象。
42
+
43
+ ## 进度与工作报告
44
+
45
+ `work-report.js` 保存最新工作报告的来源。短报告可随检查点携带原话,长报告保存来源标识,供后续摘要与回查使用。
46
+
47
+ `progress-facts.js` 基于显式 `key: value` 结构化进度声明与 SHA-256 来源校验跟踪计数、状态、产物路径和 `nextAction`,避免领域词表对普通自然语言的误判。
48
+
49
+ ## 分页接续与重试
50
+
51
+ 完整摘要请求包含源消息、规则、近期原话索引、`<channel-provenance>` 通道隔离声明和工作报告。`summary-budget.js` 按完整请求规划容量,`continuation.js` 在需要时分页生成工作笔记。
52
+
53
+ 每个已接受页面保存来源身份和进度。重试或恢复时复用匹配的已完成页面,未完成页面继续请求。调用额度、实际发送与未知用量分别记录。
54
+
55
+ `summary-retry.js` 对超时、断流、空摘要、结构不合格和检查失败进行有限重试。常规和接续请求均使用 `singleTarget: true`,只请求选定的首个摘要目标。用户取消会结束当前操作。`summary-timeout.js` 在发送和读取阶段检查截止时间。
56
+
57
+ ## 归档与提交
58
+
59
+ 归档以消息区间组织,保存原始事件、消息块和工具关系。附件按 SHA-256 保存和按需校验(`history_search` 文本检索仅核验存在性与字节大小,显式 `readSpan`/`readAttachment` 执行逐字节校验),历史工具提供多词联合检索与分段读取。
60
+
61
+ 事务适配器对经审查的 DSH `0.2.2-rc.1`、`0.2.2-rc.2` 与 `0.2.2-rc.3` 宿主方法(含单条与批量 `Session.append` 实现及去除注释/空白后的归一化方法签名)做指纹核验,按“单趟拷贝兼哈希备份、持久化替换、持久化成功决定、发布”的顺序提交;若遇到未知宿主方法体则在摘要请求与历史修改前直接拒绝并保留已有恢复材料。成功决定前失败可恢复已核验的备份;决定后发布异常会隔离写入并要求冷重开会话,保留已持久成功的历史。
62
+
63
+ ## 插件入口
64
+
65
+ `cordis.patch.yml` 注册配置入口,并让四种 preset 在入口就绪后加载。入口将 preset 中的基础压缩引擎替换为 Weave,合并原有配置与插件设置。
66
+
67
+ `client.js` 注册“摘要模型”设置页;`summary-config.js` 负责读取、校验和保存设置;`command-compact.js` 接入手动命令。
68
+
69
+ ## 代码导航
70
+
71
+ | 目录或模块 | 职责 |
72
+ | --- | --- |
73
+ | `lib/index.js`、`engine-entry.js` | DSH 加载与配置入口 |
74
+ | `lib/engine.js`、`idle-compaction.js` | 选区、分级压缩、闲置判定、生成、检查和提交流程 |
75
+ | `lib/observation-mask.js` | 第一级工具输出归档折叠与 `history_read` 预览 |
76
+ | `lib/cache-policy.js`、`region.js` | 前缀复用、工具配对、区间选择与归档指针 |
77
+ | `lib/source-provenance.js`、`instruction-source.js`、`reference-input.js` | 宿主通道分类、`<untrusted_reference>` / `<channel-provenance>` XML 隔离 |
78
+ | `lib/memory-policy.js`、`audit.js` | 要求生命周期与通用确定性审计 |
79
+ | `lib/progress-facts.js`、`work-report.js` | 结构化 `key: value` 进度与报告来源 |
80
+ | `lib/summary-*.js`、`continuation*.js` | 摘要请求、分页、重试与恢复 |
81
+ | `lib/history.js`、`attachments.js`、`tools.js` | 归档与历史回查 |
82
+ | `lib/transaction*.js`、`journal.js`、`state.js` | 事务与持久化状态 |
83
+ | `lib/failure-diagnostics.js`、`audit-reject.js` | 失败诊断与拒绝样本 |
84
+ | `test/` | 离线回归与宿主集成测试 |