Skip to main content
D

oh-my-clm

devzjqx/oh-my-clm

Pi extension + DSH plugin: manual live-context cleanup and automatic, replay-safe tool-result clearing.

Install

dsh plugin --profile web add github:devzjqx/oh-my-clm

README

oh-my-clm

Pi extension + DSH/Cordis plugin。DSH 侧默认关闭一条自动清理通道:turn/end 把已被同一目标取代的 read/grep/glob 结果换成一行重取指针,记录是 log-only 的 ignorable plugin record,消息投影只改模型可见副本;会话日志、surface 和人类 transcript 都不动。手动路径仍保留 mirror + cleanup。

自动清理(DSH,默认关闭)

autoClear.enabled: true 时每个 turn/end 结算一次:清被同一目标后续调用取代的块,以及正文全部可重取、且已过期 staleTurns 个 turn 或 staleSteps 个 tool result 的块;闸门为 1200 token、2 块或死内容占当前 prompt 的 5%,占用 ≥60% 停手交给宿主 compaction;同一个目标被重读 2 次即拒收该 key,全局重读率过高才熔断。计时器按 step 计(老化另有 staleSteps 时钟),结算点留在 turn 边界,让一次断点摊到整批块上;autoClear.midTurnSuffixTokens 可单独放开尾部很短的 turn 内清理。autoClear.canary: true 只记账不执行;npm run canary:replay 可离线跑已存会话。详见 自动清理。

手动通道:mirror 与 cleanup

Pi projection ──► /tmp/clm-${sessionId}/LIVE_CTX_MAIN.md ◄── 模型 edit / cleanup
                              │
                              ▼
                 snapshot / 结构 / 配对 / shrink-only 校验
                              │
                              ▼
          Pi: context_edit          DSH: Session.append() replacement
  • Pi:turn_end 把 mirror 差异提交为 branch-local context_edit;/tree、fork、resume 仍由 Pi 处理。
  • DSH:通过 Session.append() 的 surfaceOp: { op: "replace" } 改写当前 active surface;append-only session log 保留原始事件。
  • cleanup:在 host 侧按 1-based editable block ID 直接删除或软卸载,不读取 block body,不受 preview 截断影响。
  • block index:DSH 把可操作的 ID 区间放进 runtime context;默认 digest,每个已完成 turn 一行。
  • 自动清理(DSH,默认关):turn 边界把被后续调用取代的 tool result 换成 [cleared … re-read if needed] 指针,通过宿主消息投影实现——会话日志与人类 transcript 都保留原文。需要宿主提供 appendPluginRecord seam(dsh-session ≥ 0.2.2-rc.1),否则该通道保持关闭。

安装

npm 主包同时包含 Pi extension 与 DSH bundle。

# Pi:写入 ~/.pi/agent/settings.json;加 --local 写入项目 .pi/settings.json
pi install npm:oh-my-clm
pi install git:github.com/DevZjQx/oh-my-clm

# DSH:安装到指定 profile
dsh plugin --profile <profile> add oh-my-clm
dsh plugin --profile <profile> add github:DevZjQx/oh-my-clm

# 卸载
pi remove npm:oh-my-clm
dsh plugin --profile <profile> remove oh-my-clm

固定版本:npm 用 oh-my-clm@<version>,GitHub 用 #<ref>。DSH 不读取 Pi 设置;安装后重启对应宿主。

从源码试运行:

pi --extension ./extensions/clm.ts
pi -e .

使用

整理历史优先用 cleanup,一次调用批量给出所有目标:

cleanup({ blockIds: [2, 3, 4] })
cleanup({ ranges: ["3-16"], skipRoles: ["user"] })
cleanup({ offload: [{ blockId: 2, note: "旧测试在 X 上失败,已修" }] })
cleanup({ list: "3-16" })

只有需要完整、未截断的正文做 rewrite 时才读 mirror。命令:

/clm
/clm status
/clm mode [blocks|digest|auto]   # 仅 DSH

/clm mode 是当前进程级覆盖,从下一步生效,重启后回到配置文件的 index.mode。没有 /clm refresh、/clm export 或专用 /clm-compact;手动压缩使用宿主原生的 /compact。

行为约束

mirror 只是编辑面:原始 session JSONL / DSH session log 是事实来源,只有当前 projection / surface 被替换。编辑只改 body,保留 header、snapshot、marker 与顺序;所有编辑必须严格缩短上下文,非法编辑整体拒绝。block ID 是 1-based 编辑序号,block 1、user-authored 正文、截断 preview 都不能被改写;tool call 与 result 配对级联。细节见 Live context mirror。

配置

不再读取任何 CLM_* 环境变量。配置是一个 JSON 文件,按会话工作目录解析:

  1. 用户级 $XDG_CONFIG_HOME/oh-my-clm/config.json(未设或非绝对路径时为 ~/.config/oh-my-clm/config.json);
  2. 项目级 <cwd>/.oh-my-clm.json,逐 key 覆盖用户级。

XDG_CONFIG_HOME 只决定用户级文件的位置(标准 XDG 语义),不是插件开关:没有任何配置值来自环境变量。

只写需要改的 key;其余取默认值。非法值回退到默认值并写一条 warning,不会因为一个拼写错误让插件整体失效。每次请求都会重新读文件,所以改完不需要重启宿主。

{
  "context": { "budgetTokens": 32000 },
  "index": { "mode": "digest" },
  "cleanup": {
    "cacheDiscountPercent": 2,
    "paybackTurns": 10,
    "trigger": { "usagePercent": 70, "stepsSinceCleanup": 40 }
  },
  "autoClear": { "enabled": false, "canary": false }
}
配置项默认作用
context.budgetTokens0Pi 侧近似目标 token;0 表示不设显式预算。用量达到约 0.75 × max(1, budget − 2048) 时追加同请求 budget nudge。
context.windowTokens0宿主不提供窗口时的兜底;未知时用量行写 window unknown。
context.fixedTokens0DSH 额外计入 shrink-only gate 的固定 token。
context.maxBlockChars12000单个 block 的 preview 上限。
context.maxMirrorChars96000全部可编辑 preview 的总上限。
index.modedigest索引形状:digest 或 blocks。
index.previewChars64blocks 模式每行 preview 字符数。
index.headBlocks12列表开头保留的 block 数。
index.tailBlocks40列表尾部窗口宽度。
index.maxLines40digest 模式最多列出的 turn 数。
index.refreshSteps4同一 turn 内最多每几步重渲染一次;1 为每步刷新。
cleanup.resultModecompactDSH 结果模式:compact / full / none。
cleanup.cacheDiscountPercent2缓存命中价占全价的百分比(2 = 1/50),即候选成本公式中的 r。
cleanup.paybackTurns10断点成本摊到多少次后续请求(一次请求 = 一步),即公式中的 N。按轮理解会高估成本。
cleanup.paybackSteps0显式请求数(horizon),覆盖 paybackTurns;0 = 不设。
cleanup.trigger.usagePercent0用量达到窗口百分比时触发候选;0 关闭。
cleanup.trigger.completedTurns0已完成 turn 数达到该值时触发。turn 比 step 粗,优先用 completedSteps。
cleanup.trigger.completedSteps0已完成 step(请求)数达到该值时触发。
cleanup.trigger.toolResultSharePercent0toolResult 占可编辑 token 的百分比达到该值时触发。
cleanup.trigger.turnsSinceCleanup0距上次成功清理的 turn 数达到该值时触发。
cleanup.trigger.stepsSinceCleanup0距上次成功清理的 step 数达到该值时触发。
cleanup.trigger.maxCandidates3一次触发最多给出的候选区间数。
cleanup.trigger.minSavingsTokens0小于该估算 token 的 turn 不作为候选。
autoClear.enabledfalse真正清理:把被取代或已老化的可重取 tool result 换成重取指针。
autoClear.canaryfalse只记录自动清理决策到 CANARY.jsonl,不改模型输入。
autoClear.staleTurns3一个正文全可重取的块过期多少 turn 后按 rot 清理,不再要求被取代;0 关闭 turn 时钟。
autoClear.staleSteps0同一个块过期多少个 tool result(约等于 step)后按 rot 清理。一个 turn 有 11–39 个 step,所以 turn 时钟管不到单个长 turn 内部;0 关闭该时钟。
autoClear.minTokens1200一批至少释放的 token;低于它不值得断一次前缀。
autoClear.minBlocks2或者至少这么多个候选块。
autoClear.minSharePercent5或者候选块占当前 prompt 的百分比达到该值;0 = 只按量。这是抗 rot 判据,不是省钱判据。
autoClear.stopPercent60占用达到窗口百分比即停手,交给宿主 compaction。
autoClear.midTurnSuffixTokens0允许在 turn 内清理:死块之后待重算的尾部 ≤ 该 token 数即可,不再要求回本。0 关闭。
host.pluginRecordModule@deepseek-ai/dsh-session提供 appendPluginRecord seam 的宿主模块;高级/测试用。

自动清理的记录必须是宿主可忽略的 plugin record,所以它需要宿主提供 appendPluginRecord(@deepseek-ai/dsh-session ≥ 0.2.2-rc.1)。插件目录解析不到宿主包,所以解析器会再从宿主入口(process.argv[1],即 dsh/lib/bin.js)和全局模块根兜底;解析出的模块必须是会话所用的同一份 dsh-session(否则私有字段写入会失败),导出 Session 时会在写入前比对原型。仍然解析不到时插件不会退回 session.append()(那会让含记录的会话在重启后被宿主拒绝恢复),而是保持关闭:会话创建时 warn 一次,/clm 显示 stopped (unrecordable)。autoClear.canary 只写 /tmp/clm-<session>/CANARY.jsonl,不需要该 seam。

所有触发阈值默认关闭(0)。命中后只在该 turn 边界装配一次用量行和候选;候选只取已完成的 turn,按断点后的净收益排序,并固定带 skipRoles: ["user"]。Pi 侧另认 cleanup.trigger.stepsSinceCleanup(回退 turnsSinceCleanup)与 cleanup.trigger.toolResultSharePercent,预算 nudge 与 DSH 共用同一套用量行/候选格式。

计数单位:陈旧度信号(completedSteps / stepsSinceCleanup / 候选的 stepsOld / 摊销 N)按 step 计;批次结算、闸门和候选区间仍按 turn,因为一次断点必须摊到多个块上。度量依据见 src/features/live-context/auto-clear.ts 与 changelog。

DSH 适配

  • 发现入口:dsh-plugin.json;host entry:dist/dsh/index.js;官方安装元数据:package.json 的 dsh.bundle.patch 与 cordis.patch.yml。
  • 使用 Cordis 生命周期注册工具与 system prompt;不启动独立 agent loop,不扫描 JSONL。
  • replacement 只在打开的 turn/step 内执行;assistant/message 不能作为 replacement。
  • 生命周期、replacement 语义与未验证边界见 DSH surface bridge。

打包:

npm run build:dsh:plugin
# 默认输出 artifacts/oh-my-clm-<version>.tgz
node scripts/build-dsh-plugin.mjs --output ./out/oh-my-clm.tgz

专用包只含 DSH host、dist、manifest、bundle patch、locale、icon;普通 npm pack 仍生成 Pi + DSH 完整包。

开发

npm test
npm run check
npm run typecheck
npm pack --dry-run

依赖方向固定为 shared (src/lib) → features (src/features/live-context) → host adapters (extensions, dsh);npm run check 验证边界。目录与测试布局见 项目结构。

文档

边界

不实现独立 agent runtime、rollback/retry harness、trajectory export、receipt store 或 dsh-ops 的工具矩阵。自动清理默认关闭,且不承诺省算力:在缓存命中价 0.02× 的端点上去掉断点之后的 token,省下的钱通常抵不过断点重算;它解决的是上下文腐烂,不是账单。token 估算不是 provider 精确 tokenizer,只用于编辑前后比较;宿主窗口仍是硬约束,超限交给宿主原生 auto-compaction / /compact。mirror 可能含 reasoning 与 tool output,由宿主负责临时文件生命周期与内容审计。

Related plugins