dsh-btw

Readme

# dsh-btw

dsh（DeepSeek Harness）全局命令插件：`/btw` 进行**一次不计入会话记忆的问答**，等价于 Claude Code 的 `/btw` 指令。

A global-command plugin for DeepSeek Harness (dsh): `/btw` performs a **one-off Q&A that is not recorded into session memory** — the Claude Code `/btw` equivalent.

## 兼容性 / Compatibility

> **本插件只保证适用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 官方仓库的 v0.1.1 基线版本**（tag `dsh-v0.1.1`；本地开发与验证基线为 `dsh-v0.1.1-rc.2`）。不保证在官方仓库更高版本（v0.1.2 及以后）上正常工作，升级 harness 前请先在本机验证。
>
> **This plugin is only guaranteed to work on the v0.1.1 baseline of the official [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) repository** (tag `dsh-v0.1.1`; the local development and validation baseline is `dsh-v0.1.1-rc.2`). It is not guaranteed to work on later official versions (v0.1.2 and beyond) — verify on your own machine before upgrading the harness.

插件只依赖宿主注入的 `ctx.commands` 与 `ctx.llm` 服务；对 `@deepseek-ai/*` 包全部为类型导入，构建时擦除、零运行时依赖，因此不会随 harness 产生依赖版本漂移，但仍以 v0.1.1 基线的服务语义为准。

The plugin depends only on the host-injected `ctx.commands` and `ctx.llm` services; every `@deepseek-ai/*` import is type-only and erased at build time, so there is zero runtime dependency and no drift with the harness — the v0.1.1 baseline service semantics are authoritative.

## 特性 / Features

- **全局生效**：在普通 `ctx` 上通过 `ctx.commands.register()` 注册（plain-context registration is global），profile 下任何 agent preset / 模式 / 会话都可用，无需在每个 preset 中配置。
  **Global**: registered on the plain `ctx` via `ctx.commands.register()` (plain-context registration is global), so every agent preset / mode / session under the profile sees the command with no per-preset configuration.
- **detached 即时清空**：触发即清空 composer、立即释放输入能力；主代理繁忙时也可随时触发，不需要排队（`/` 行走命令管线，不进入消息队列）。
  **Detached, immediate clearing**: triggering clears the composer and frees input instantly; it can fire even while the main agent is busy and does not queue (it walks the command pipeline, not the message queue).
- **沿用当前模型**：优先复用当前会话最近一次请求的 provider/model 路由，其次才是 agent 自身的 `options.provider` / `options.model`；两者都没有时返回明确错误。
  **Reuses the current model**: prefers the provider/model route of the session's latest request, then falls back to the agent's own `options.provider` / `options.model`; errors out clearly when neither exists.
- **只读上下文拼接**：自动携带最近最多 40 条用户/助手消息（合计上限 32000 字符）作为只读背景，使提问可以引用会话内容；背景只是字符串快照，不写回会话、不进入 session log，也不影响后续模型的缓存键。
  **Read-only context stitching**: automatically carries up to the most recent 40 user/assistant messages (32,000 characters total) as read-only background, so the question can reference session content; the background is a plain string snapshot — not written back to the session, not entered into the session log, and not affecting later cache keys.
- **零运行时依赖**：`lib/index.js` 为 tsc 类型擦除后的纯 ESM，不 import 任何运行时包。
  **Zero runtime dependencies**: `lib/index.js` is pure ESM after type erasure; no runtime package is imported.
- **可取消**：把 UI 请求的 `AbortSignal` 转发给底层 stream。
  **Cancellable**: forwards the UI request's `AbortSignal` to the underlying stream.

## 用法 / Usage

```text
/btw 这个函数是做什么的？             # What does this function do?
/btw 帮我算一下 0x2F & 0x0F 等于几      # What is 0x2F & 0x0F?
```

命令在输入框触发后**立即清空输入并转入后台执行**：命令声明为 `detached`，composer 在触发的同一瞬间结算本次提交（不再等待模型答完才清空输入框），随后宿主调用 `ctx.llm.stream()` 发起一次独立的一次性模型请求，答案以持久化的命令节点渲染在会话流中。整个过程**不写入任何会话消息**（不产生 user 消息、assistant 消息或可被后续模型请求读取的会话事件），所以这次问答不会进入会话历史、不影响后续轮次的记忆。

Once triggered, the command **immediately clears the input and runs in the background**: it declares `detached`, so the composer settles the submission at the instant of the trigger (it does not wait for the model answer to clear the input box); the host then makes one independent one-shot model request through `ctx.llm.stream()`, and the answer renders as a durable command node in the conversation stream. The whole run **writes no session messages** (no user message, no assistant message, and no session event a later model request could read), so the Q&A never enters session history and does not affect the memory of later turns.

## 设计说明 / Design notes

- `detached` 由命令定义声明（`CommandDefinition.detached`），描述符经 `command.list` 线传给 composer：claim 的 submit 立即返回成功并在后台执行，主机仍照常记录 `command/run` / `command/done` 生命周期，结果节点照常渲染。
  `detached` is declared by the command definition (`CommandDefinition.detached`); the descriptor reaches the composer over the `command.list` line: the claim's submit returns success immediately and runs in the background, while the host still records the `command/run` / `command/done` lifecycle and renders the result node as usual.
- `command/run` / `command/done` 为仅日志记录（log-only），永远不会进入模型请求，因此命令输入与结果对模型不可见，也即"不计入后续记忆"。
  `command/run` / `command/done` are log-only records that never reach a model request, so the command's input and result stay invisible to the model — i.e. "not recorded into later memory".
- 一次性调用使用独立的精简 system prompt，不携带会话 persona 与工具；与 DSH 压缩后端直接调用 `ctx.llm.stream()` 的模式一致。
  The one-off call uses an independent, minimal system prompt without the session persona or tools — the same pattern DSH's compaction backend uses to call `ctx.llm.stream()` directly.
- 只读上下文复制会按请求放大一次性调用的 token 用量（上限约 32000 字符）；因为零会话写入，会话自身的派生上下文与 provider 缓存前缀保持不变。
  The read-only context copy scales the one-off call's token usage with the request (capped at ~32,000 characters); because there is zero session writes, the session's own derived context and the provider cache prefix stay unchanged.
- `max-tokens` 截断与失败终态（error / aborted）会转换为命令错误返回。
  `max-tokens` truncation and failing terminal states (error / aborted) are returned as command errors.

## 安装 / Install

前置：已安装 dsh（`dsh` CLI）并存在目标 profile（默认 GUI profile 名为 `web`）。

Prerequisites: a dsh installation (the `dsh` CLI) and a target profile (the default GUI profile is named `web`).

### 从 GitHub / From GitHub

```sh
dsh plugin --profile web add github:clclyzybzjsq/dsh-btw
```

Git 安装取的是源码而非构建产物，因此 pnpm 会运行包的 `prepare` 脚本以生成 `lib/`。pnpm ≥ 10 默认拒绝运行 git 依赖的 `prepare`，首次 `add` 会失败并打印确切的包 key；把该 key 复制进 profile 的 `pnpm-workspace.yaml`：

A git install fetches sources, not built artifacts, so pnpm runs the package's `prepare` script to build `lib/`. pnpm ≥ 10 refuses to run a git dependency's `prepare` until explicitly allowed — the first `add` fails and dsh prints the exact package key; copy it into the profile's `pnpm-workspace.yaml`:

```yaml
allowBuilds:
  dsh-btw: true
```

然后重新执行 `add`。该放行意味着允许在安装时执行此包代码——只放行你信任的包，并建议固定 commit（`github:clclyzybzjsq/dsh-btw#<sha>`）。完成后再（重）启动一次 `dsh web`，组合生效。

Then re-run the `add`. That allowance is permission to execute the package's code at install time — only allow packages whose source you trust, and pin a commit (`github:clclyzybzjsq/dsh-btw#<sha>`). (Re)start your `dsh web` once so the composition picks up the new row.

### 从 tarball（无需构建放行）/ From a tarball (no build allowance needed)

```sh
pnpm pack                      # 生成 dsh-btw-0.1.0.tgz / produces dsh-btw-0.1.0.tgz
dsh plugin --profile web add ./dsh-btw-0.1.0.tgz
```

### 本地目录 / From a local directory

```sh
dsh plugin --profile web add /path/to/dsh-btw
```

### 卸载 / Uninstall

```sh
dsh plugin --profile web remove dsh-btw
```

## 构建 / Build

```sh
pnpm install    # 安装 tsdown 并运行 prepare，生成 lib/ / installs tsdown and runs prepare, emitting lib/
```

`prepare` 脚本是自包含构建（`src/` + 专属 tsdown 配置）：无 monorepo 上下文、无 project references、无类型检查，产物为 `lib/index.js`（ESM node half）。

The `prepare` script is self-contained (builds from `src/` with a dedicated tsdown config): no monorepo context, no project references, no type checking. Output: `lib/index.js` (ESM node half).

## 分发 / Distribution

这是标准的 dsh bundle：`package.json` 声明 `dsh.bundle`（patch `cordis.patch.yml` 向 profile 组合插入 `command-btw` 行）。本仓库地址 `github:clclyzybzjsq/dsh-btw`，用户按上面的 GitHub 命令安装；也可以 `pnpm pack` 分发 tarball。

This is a standard dsh bundle: `package.json` declares `dsh.bundle` (patch `cordis.patch.yml` inserts the `command-btw` row into the profile composition). Repository: `github:clclyzybzjsq/dsh-btw` — users install with the GitHub command above, or you distribute tarballs with `pnpm pack`.

## License

MIT © 2026 [iseri_tomori](./LICENSE)