@aiwayds/dsh-dcp 0.8.0 → 0.9.1

package/README.en.md

@@ -176,6 +176,15 @@ All optional, defaults work out of the box:
 
 > **Upgrade note (0.5.0)**: the `roundInterval` counter switched from completed turns to assistant messages — the same value now triggers more often (a single turn usually contains several assistant messages).
 
+## Bundled skill
+
+The package registers a `dsh-dcp-config` skill (`skills/dsh-dcp-config/SKILL.md`, served via
+`ctx.skills.registerProvider`): ask the agent to tune compaction, configure dcp,
+or debug compaction behavior and the guide loads automatically — it carries an
+interactive `ask_user_question` tuning wizard (collect the expectation first,
+then map it to keys) and the persistent recipe for the `config:` section of the
+cordis.patch.yml mount block.
+
 ## Design reference
 
 - [Opencode-DCP/opencode-dynamic-context-pruning](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning)

package/README.md

@@ -148,6 +148,10 @@ npx dsh-dcp-setup --remove /path/to/cordis.patch.yml
 
 > **升级提示（0.5.0）**：`roundInterval` 的计数单位由 completed turn 改为 assistant message——同值下触发会更频繁（一个 turn 内往往有多条 assistant message）。
 
+## 内置技能 / Bundled skill
+
+插件随包注册了 `dsh-dcp-config` skill（`skills/dsh-dcp-config/SKILL.md`，经 `ctx.skills.registerProvider`）：在会话里让 agent 调压缩、配置 dcp 或排查压缩行为时，指南自动加载——内含 ask_user_question 交互式调参向导（先问期望再映射到具体键）与 cordis.patch.yml 挂载块 `config:` 段的持久化写法，无需翻文档。
+
 ## 设计参考
 
 - [Opencode-DCP/opencode-dynamic-context-pruning](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning)

package/lib/index.js

@@ -35,6 +35,7 @@ import { ManualCompactionError } from '@deepseek-ai/dsh-compaction'
 import { splitConfig, resolveDcpConfig } from './config.js'
 import { summarizeDeterministically, noticeText } from './summarizer.js'
 import { registerDcpCommand } from './command.js'
+import { skillProvider } from './skill.js'
 
 const require = createRequire(import.meta.url)
 const { version: VERSION } = require('../package.json')
@@ -68,7 +69,8 @@ const kAppendNotice = Symbol('dsh-dcp.appendNotice')
 
 /**
  * Deterministic compaction engine: `summarize()` overridden, everything else
- * inherited. Registers the `/dcp` command beside the inherited `/compact`.
+ * inherited. Registers the `/dcp` command beside the inherited `/compact`,
+ * and serves the bundled usage/config guide through the host skill registry.
  */
 /** Element schema mirroring compaction-basic's model-policy override shape. */
 const modelPolicy = z.object({
@@ -85,7 +87,7 @@ const modelPolicy = z.object({
 })
 
 export class DcpEngine extends BasicCompactionEngine {
-  static inject = ['llm', 'tokenMeter', 'sessions', 'commands']
+  static inject = ['llm', 'tokenMeter', 'sessions', 'commands', 'skills']
 
   static Config = z.object({
     // compaction-basic policy keys (forwarded verbatim)
@@ -140,6 +142,15 @@ export class DcpEngine extends BasicCompactionEngine {
     this.dcpStats = { compactions: 0, shadowedTokens: 0, lastAt: null }
     this.pluginPath = fileURLToPath(import.meta.url)
     const engine = this
+    // Bundled usage/config guide. Soft-guarded: engines constructed in exotic
+    // hosts without the skill registry must still boot; losing the bundled
+    // guide is non-fatal. On the real host, `skills` in `static inject`
+    // guarantees the service is present (verified by scripts/smoke-boot.mjs).
+    try {
+      ctx?.skills?.registerProvider?.(() => skillProvider)
+    } catch {
+      // non-fatal — see comment above
+    }
     ctx.effect(function* () {
       yield registerDcpCommand(ctx, engine, VERSION)
     }, 'dsh-dcp /dcp command lifecycle')

package/lib/skill.js

@@ -0,0 +1,98 @@
+/**
+ * Bundled usage/configuration skill for dsh-dcp.
+ *
+ * Ships `skills/dsh-dcp-config/SKILL.md` through `ctx.skills.registerProvider`
+ * (same mechanism as dsh-llm-proxy and dsh-vault): an agent asked to tune
+ * compaction, run `/dcp`, or persist a config change loads the guide
+ * automatically instead of guessing at key names and mount shapes.
+ *
+ * @module dsh-dcp/skill
+ */
+
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+// The runtime import of '@deepseek-ai/dsh-skill' is deliberately avoided:
+// the registry-published dsh-skill lib imports host-closure siblings
+// (@deepseek-ai/dsh-scope, dsh-llm — peers of it, but absent from a plugin
+// repo's own dependency graph), which dies under pnpm's isolated layout.
+// The host injects the real service at runtime; this module only hands it a
+// plain provider object.
+
+/** Mirrors dsh-skill's bundled-skill rank (a non-load-bearing ordering hint;
+ *  the constant is hardcoded there too). Local copy — see the note above
+ *  for why dsh-skill is not loaded at runtime here. */
+const BUNDLED_SKILL_RANK = 600
+
+/** Provider name under `ctx.skills`; doubles as the skill name. */
+export const SKILL_PROVIDER_NAME = 'dsh-dcp-config'
+
+/** Packaged skill body; `../skills/` resolves to the package root from lib/. */
+const SKILL_BODY_URL = new URL('../skills/dsh-dcp-config/SKILL.md', import.meta.url)
+
+/** Resource base served with the skill so its relative links resolve. */
+const SKILL_RESOURCE_BASE = {
+  kind: 'directory',
+  path: fileURLToPath(new URL('../skills/dsh-dcp-config/', import.meta.url)),
+}
+
+const SKILL_INVOCATION = { modelInvocable: true, userInvocable: true }
+
+/** Routing description; must stay identical to the SKILL.md frontmatter (asserted in tests). */
+export const SKILL_DESCRIPTION = 'dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南。凡涉及上下文压缩、/dcp 命令、压缩调参（阈值/密度/语言/轮数触发），或要配置 dcp 时先读本指南：/dcp 状态与 /dcp set 十个可调键、持久化到 cordis.patch.yml 挂载块 config: 段（dsh-dcp-setup 管理）、ask_user_question 调参向导、四类触发（压力/溢出/轮数/手动）、subagent 会话独立计数生效。触发词：dcp、压缩、compaction、上下文超限、摘要、thresholdRatio、roundInterval。'
+
+const SKILL_CANDIDATE = {
+  name: SKILL_PROVIDER_NAME,
+  description: SKILL_DESCRIPTION,
+  invocation: SKILL_INVOCATION,
+  provider: SKILL_PROVIDER_NAME,
+  source: 'bundled',
+  resourceBase: SKILL_RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: SKILL_BODY_URL,
+}
+
+/** The bundled-skill catalog entry, served through the host skill registry. */
+export const skillProvider = {
+  name: SKILL_PROVIDER_NAME,
+  list(_options) {
+    return Promise.resolve([SKILL_CANDIDATE])
+  },
+  async get(_candidate, _options) {
+    return {
+      name: SKILL_CANDIDATE.name,
+      description: SKILL_CANDIDATE.description,
+      invocation: SKILL_CANDIDATE.invocation,
+      provider: SKILL_CANDIDATE.provider,
+      source: SKILL_CANDIDATE.source,
+      resourceBase: SKILL_RESOURCE_BASE,
+      content: stripFrontmatter(await readFile(SKILL_BODY_URL, 'utf8')),
+    }
+  },
+}
+
+/**
+ * Strip a leading YAML frontmatter block (`---` / body / `---`) from a skill
+ * markdown file. `SkillDefinition.content` must be the instruction body after
+ * metadata removal — the same shape the filesystem provider serves — so the
+ * bundled SKILL.md, which keeps its frontmatter for the GitHub/manual install
+ * paths, has the block removed when served through `skillProvider.get`.
+ * Tolerant by design: input that does not open with a `---` line, or whose
+ * frontmatter block is never closed, is returned unchanged. Mirrors the
+ * delimiter semantics of the upstream skill-filesystem provider.
+ */
+export function stripFrontmatter(raw) {
+  const firstLineEnd = raw.indexOf('\n')
+  if (firstLineEnd < 0 || raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return raw
+  let lineStart = firstLineEnd + 1
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf('\n', lineStart)
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline
+    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return raw.slice(nextNewline < 0 ? raw.length : nextNewline + 1).trim()
+    }
+    if (nextNewline < 0) return raw
+    lineStart = nextNewline + 1
+  }
+  return raw
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-dcp",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Deterministic context-pruning compaction backend for dsh (DeepSeek Harness) — zero-LLM summaries, /dcp command, works out of the box. Design references Opencode-DCP/opencode-dynamic-context-pruning.",
   "type": "module",
   "main": "lib/index.js",
@@ -17,6 +17,7 @@
   "files": [
     "lib",
     "scripts",
+    "skills",
     "README.md",
     "README.en.md",
     "LICENSE",
@@ -61,6 +62,7 @@
     "@deepseek-ai/dsh-invariants": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-session": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1",
     "@deepseek-ai/dsh-token-meter": ">=0.1.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
@@ -95,6 +97,9 @@
     "@deepseek-ai/dsh-session": {
       "optional": true
     },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-token-meter": {
       "optional": true
     },

package/skills/dsh-dcp-config/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: dsh-dcp-config
+description: "dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南。凡涉及上下文压缩、/dcp 命令、压缩调参（阈值/密度/语言/轮数触发），或要配置 dcp 时先读本指南：/dcp 状态与 /dcp set 十个可调键、持久化到 cordis.patch.yml 挂载块 config: 段（dsh-dcp-setup 管理）、ask_user_question 调参向导、四类触发（压力/溢出/轮数/手动）、subagent 会话独立计数生效。触发词：dcp、压缩、compaction、上下文超限、摘要、thresholdRatio、roundInterval。"
+---
+
+# dsh-dcp 使用指南（确定性上下文压缩）
+
+> dsh 插件：替换官方 `compaction-basic` 的确定性压缩引擎——**零 LLM 调用**
+> （去重 / 折错 / 密度控制），中文场景优先（CJK 计价、中文报错与"待办："识别），
+> 附轮数触发。压力触发、保留尾巴、溢出恢复、tool-pairing 安全机制全部继承官方，只替换"摘要"这一环。
+
+## 配置入口（两条路）
+
+1. **会话内临时调参**：`/dcp set <键> <值>`，只影响当前会话，重启失效。十个可调键：
+   `dedup` `purgeErrors` `maxItems` `maxItemChars` `maxSummaryTokens` `language`
+   `tokenEstimate` `thresholdRatio` `roundInterval` `notice`。
+2. **持久化**：cordis.patch.yml 里 dsh-dcp 挂载块的 `config:` 段。用
+   `npx dsh-dcp-setup` 写入并维护（带 marker 注释、改动前日期备份、幂等）；
+   `--remove` 只删 setup 写的块，手工写的块不受影响。bundle 方式
+   （`dsh plugin add @aiwayds/dsh-dcp` 或列在 profile `bundles`）自动挂载，无需手写 patch。
+
+挂载块形状（`~/.dsh/cordis.patch.yml` 或某个 profile 的 cordis.patch.yml）：
+
+```yaml
+- id: compaction-basic
+  name: '@deepseek-ai/dsh-compaction-basic'
+  disabled: true
+- insert:
+    - id: dsh-dcp
+      name: '@aiwayds/dsh-dcp'
+      config:
+        thresholdRatio: 0.7   # 每个键都可选
+        language: zh
+```
+
+## 配置键
+
+dsh-dcp 自有键（除 `thresholdRatio` 外全部可用 `/dcp set` 调）：
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `dedup` | `true` | 重复工具调用折叠成一条标注 |
+| `purgeErrors` | `true` | 旧报错折叠成一条提示 |
+| `maxItems` / `maxItemChars` | 10 / 200 | 摘要密度（条数 / 单条字符上限） |
+| `maxSummaryTokens` | 2048 | 摘要 token 预算 |
+| `language` | `en`（代码默认；bundle 挂载默认 `zh`） | 摘要语言；`zh` 额外识别中文报错和"待办：" |
+| `tokenEstimate` | `cjk` | CJK（中/日/韩/全角）按 ~2 字符/token 计价；`ascii` 与宿主一致 |
+| `protectedTools` | `['write', 'edit', 'apply_patch']` | 写侧工具（子串匹配）的重复调用不折叠进 dedup 标注 |
+| `roundInterval` | 50 | 每 N 条 assistant message（一次 LLM 往返）触发一次压缩；`0` 关闭 |
+| `notice` | `true` | 压缩后在会话追加一行通知 |
+
+转发上游 compaction-basic 的策略键：`thresholdRatio`（上游默认 0.8；**本插件 bundle 挂载默认 0.7**，中文场景建议 0.7）、`retainRatio`、`retainTokens`、`maxTokens`、`summarizationProvider`、`summarizationModel`、`compactionRetries`、`maxOverflowRetries`、`modelPolicies`、`auto`。
+
+## 交互式调参向导（ask_user_question）
+
+用户抱怨压缩行为时，不要甩配置表让对方自己读——先用 `ask_user_question`
+问清期望，再映射到键：
+
+1. **触发时机**：更晚触发 → `thresholdRatio` 调高，或 `roundInterval` 调大
+   （完全不想要轮数触发 → `roundInterval: 0`）；更早/更频繁 → 反向。
+2. **摘要密度**：更细 → `maxItems` / `maxItemChars` 调大（预算不够再加
+   `maxSummaryTokens`）；更省 → 调小。
+3. **摘要语言** → `language: en|zh`。
+4. **token 计价** → `tokenEstimate: cjk|ascii`。
+5. **通知行** → `notice: on|off`。
+
+流程：先用 `/dcp set <键> <值>` 在会话内试效果，满意后再代写持久 config——
+直接改 cordis.patch.yml 里 dsh-dcp 挂载块的 `config:` 段（setup 写的块可原位改，marker 保留）。
+
+## 触发条件（四类）
+
+| 触发 | 时机 | 说明 |
+|---|---|---|
+| 压力 | 每步请求前 | token ≥ `thresholdRatio` × 上下文窗口 |
+| 溢出 | 模型报 context 超限 | 继承官方恢复流程 |
+| 轮数 | 每累计 `roundInterval` 条 assistant message | 任何一次压缩（含压力/手动）都重置时钟；`0` 关闭；需保持 `auto: true`（默认开） |
+| 手动 | `/dcp compact`、`/compact` | 随时可用 |
+
+- **subagent 同样生效**：进程内子代理（含 continuable 与 one-shot）走同一套事件分发，
+  压力/溢出/轮数对每个会话独立计数、独立触发。
+- `notice` 通知行本身也是上下文（每次压缩约 15–25 tokens）；`notice: false` 可关。
+
+## 排障
+
+1. `/dcp`（无参数）看状态：当前配置、压缩次数、省下的 LLM 调用，以及
+   per-session 概览（含子代理；已销毁的会话自动消失，列表最多前 10 个，超出显示 `+N more`）。
+2. 会话压不动 → 先确认 `auto` 是否为 `true`（自动触发总开关，默认开），再看
+   `thresholdRatio` 是否设得过高、`roundInterval` 是否为 `0`。
+3. `npx dsh-dcp-setup --remove` 后出现 `WARN: a compaction-basic entry remains...` →
+   patch 文件里还留着 disable 行，官方 LLM 压缩后端会保持关闭；不是给 dsh-dcp 用的
+   就手动删掉那一行。