{"_id":"@buckeyestudio/toh-command-compact","name":"@buckeyestudio/toh-command-compact","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-command-compact","description":"Human-facing slash command for explicit session compaction","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/compaction/command-compact"},"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","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-commands":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1","@buckeyestudio/toh-compaction":"^0.1.1-rc.2"},"devDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/cordis-plugin-loader":"^1.0.2","@buckeyestudio/toh-compaction":"^0.1.1-rc.2","@buckeyestudio/toh-commands":"^0.1.1-rc.2","@buckeyestudio/cordis-plugin-include":"^1.0.6","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-command-compact@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-13QfQZuriwRsEm8lHGzZW7Xv2He4RFsMXRHZnYF63Rzfe93oMQ8/0q1HLoML/D3wduC5n0+VwwI73ah2yoX/5A==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-command-compact-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-command-compact-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-13QfQZuriwRsEm8lHGzZW7Xv2He4RFsMXRHZnYF63Rzfe93oMQ8/0q1HLoML/D3wduC5n0+VwwI73ah2yoX/5A==","shasum":"7fd71eb747a91ac90530c308e0006916742a141a","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-command-compact/-/toh-command-compact-0.1.1-rc.2.tgz","fileCount":9,"unpackedSize":18458,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDPFZO8UtLSBL8NfwDi6Uad+nkA1x9KHu8B436TVic2GQIgVooIrJqb8LUxi8o63byAihKhMxpWQPqJLM8L/cG6enk="}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-command-compact_0.1.1-rc.2_1787489176886_0.7695360241673257"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:46:16.725Z","0.1.1-rc.2":"2026-08-23T12:46:17.033Z","modified":"2026-08-23T12:46:17.238Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Human-facing slash command for explicit session compaction","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/compaction/command-compact"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-command-compact\n\n[English](README.md) | 中文\n\n通过 [`ctx.compaction`](../compaction/README.zh.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../interaction/commands/README.zh.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md)拥有接纳、锁与持久性决策。\n\n## 命令约定\n\n| 输入 | 结果 |\n|---|---|\n| `/compact` | 即使未达到自动压力，也摘要一段有效、平衡的较早范围；独立标记对 flush 后，报告被替换的历史项数量与估算 token 数。 |\n| `/compact`，但没有可压缩历史 | `No compactable history yet.`：不会写入标记，也不会变更 surface。 |\n| `/compact <anything>` | `Usage: /compact (no arguments)`：该命令不接受参数，也不会调用压缩后端。 |\n\n该命令与后端无关，只依赖 `compactNow(agent, signal)`。调用该命令的 agent（智能体）就是操作的确切目标，发起分发的 UI 会通过 seam 转发取消信号。每次完成的调用都会记录执行器所属的纯日志事件对 `command/run` / `command/done`；两者都不进入模型历史。成功时，`command/done.sourceEventSeq` 会指明该事务的 `compaction/summary` 事件，让呈现层无须解析结果文本或假定两行相邻，即可将命令生命周期归并到对应检查点中。\n\n预期的 `ManualCompactionError` 代码会成为稳定的直接错误：\n\n| 代码 | 直接结果 |\n|---|---|\n| `busy` | `Compaction is unavailable because this process has an active compaction, or the agent is not idle.` |\n| `changed` | `The history selected for compaction changed before it could be replaced. The conversation is unchanged; the attempt is recorded in the session log.` |\n| `summary` | `Compaction could not produce a useful summary. The conversation is unchanged; the attempt is recorded in the session log.` |\n| `commit` | `Compaction did not finish cleanly; some session history may have changed. Inspect the current session state before retrying.` |\n| `persistence` | `Compaction finished, but the session could not be saved.` |\n\nbusy 结果有意限定在进程范围内：活动的未匹配标记会阻塞，而早于最新 `session/end-seed` 的标记已陈旧，不会阻塞。意外实现故障会拒绝分发。取消仍具有最终决定权；后端会完成必需的闭合／flush 清理，命令内部以 `Compaction cancelled.` 结算，而命令执行器会因取消错误停止等待。插件处置会先注销 `/compact`，再等待所有已开始的处理器结算，因此根级 teardown 不会越过已中止命令的闭合或 flush 边界。\n\n压缩运行期间提交的提示词仍会按 agent 的普通 FIFO 获得接纳，保留相同的身份与唤醒信息。它们仅在压缩的显式持久性检查点和接纳预留释放后启动。空闲注入的上下文不受阻塞：它可以记录在 `compaction/start` 与 `compaction/end` 之间，位置替换会使其在检查点之后保持可见。\n\n## 组合\n\n生产方注入 `commands` 和 `compact`。挂载命令注册表、一个后端与本插件：\n\n```yaml\n- id: commands\n  name: '@buckeyestudio/toh-commands'\n- id: compaction-basic\n  name: '@buckeyestudio/toh-compaction-basic'\n- id: command-compact\n  name: '@buckeyestudio/toh-command-compact'\n```\n\n随附 `toh` 基础配置将它挂载在 `compaction-basic` 旁，Web 客户端提供命令适配器。未组合命令适配器的自动化接口只保留自动压缩。\n\n## 模型体验\n\n### 用户 `/compact` 控制\n\n#### 模型看到什么\n\n斜杠输入与直接结果绝不会进入模型请求。已获接纳的压缩会另外在独立的 `compaction/* { turn: null }` 标记对内，用后端的 user 角色检查点替换一段较早范围。\n\n#### Token 影响\n\n命令生命周期不会增加模型 token。成功压缩会用一份带框架的摘要替换所选范围，从而减少后续请求；摘要生成本身需要一次辅助请求。\n\n#### KV Cache 影响\n\n命令发现与簿记不会影响缓存。已获接纳的 surface 替换会从第一个被遮蔽的历史 token 起使复用失效。\n\n## 已知限制与暂缓事项\n\n- **仅限空闲状态**：当一个轮次或已获接纳的唤醒提示词拥有优先权时，`/compact` 会报告 `busy`；命令本身不会排队。\n- **不接受范围或策略参数**：无参数形式使各命令适配器的行为保持稳定。显式范围仍由编程接口 `compactRegion()` 处理。\n- **仅限命令适配器**：没有 `ctx.commands` 的接口无法调用该命令，只能依赖自动压力压缩。\n","readmeFilename":"README.zh.md","_rev":"1-0ebc674a43f5b1c184b7ae28dcf6acb2"}