dsh-semble 2.0.0 → 2.1.0

package/README.md

@@ -24,6 +24,9 @@ agent decides when the index is worth a call.
 | `mcp__semble__search` | a sentence describing the code or where it lives | ranked `file:line` hits with snippets |
 | `mcp__semble__find_related` | one location you already know | its neighbours: other implementations, callers, tests |
 
+The bundle also registers one slash command, `/semble`, for the two reporting subcommands that MCP
+does not expose: `/semble savings` and `/semble file-types`. See [Commands](#commands).
+
 A typical exchange:
 
 > **You:** Where does DSH decide that a plugin is "loaded"?
@@ -54,7 +57,7 @@ than "the best answer".
 dsh-semble
 ```
 
-Pin a version with `dsh-semble@2.0.0`. The settings page is the only supported route for the
+Pin a version with `dsh-semble@2.1.0`. The settings page is the only supported route for the
 `desktop` profile — the CLI refuses it because the Electron app owns that profile's `node_modules`
 and lockfile.
 
@@ -113,11 +116,83 @@ Edit the `semble-mcp` row in **Settings → Plugins**:
 | `args` | `--from 'semble[mcp]' semble` | append `--content all` to index docs and config too |
 | `args` (version) | floating | `semble[mcp]==X.Y.Z` pins a release |
 | `env` | empty | `HF_ENDPOINT` on restricted networks, `SEMBLE_CACHE_LOCATION` to move the index |
+| `toolCallTimeoutMs` | `300000` | the first call builds the index and downloads the model; lower it to fail faster |
 | `cwd` | inherited | keep unset; per-call `repo` values should be absolute paths |
 | `command` | `uvx` | point it at `uvx.exe` if only a `.cmd` shim is installed |
 
 Changing settings restarts the MCP connection; disk index caches survive.
 
+## Tuning
+
+Semble reads its configuration from the environment of the process that runs it. For the MCP server,
+put these in the `env` field of the `semble-mcp` row. `/semble` spawns a separate process and inherits
+the host environment instead, so export a value in both places when a report must agree with search —
+`SEMBLE_CACHE_LOCATION` is the one that matters.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `SEMBLE_INDEX_WORKERS` | `4` | worker processes that chunk a repository during the first index; `0` chunks in-process. Raise it on a many-core machine, lower it to stop a background search from saturating the CPU |
+| `SEMBLE_MCP_IDLE_TIMEOUT` | `0` (never) | seconds an idle repository index stays in the in-memory cache; with the 10-index cap, `1800` releases repositories you have moved on from |
+| `SEMBLE_MODEL_NAME` | `minishlab/potion-code-16M-v2` | alternative Model2Vec embedding model, as a local path or a Hugging Face repository |
+| `SEMBLE_MAX_FILE_BYTES` | `1000000` | files above this size are skipped; raise it for generated code worth indexing |
+| `SEMBLE_CLONE_TIMEOUT` | `60` | seconds allowed for cloning an `https://` repository |
+| `HF_ENDPOINT` | `https://huggingface.co` | mirror used for the one-time model download |
+
+### Excluding files
+
+The indexer honours `.gitignore`, plus a `.sembleignore` at the repository root for files git keeps but
+search should skip: generated clients, fixtures, vendored trees. The syntax is gitignore's, negation
+included:
+
+```gitignore
+# .sembleignore
+packages/client/generated/
+test/fixtures/
+*.min.js
+!*.proto          # force-include a file .gitignore excludes
+```
+
+A pattern that only ever needs one repository should stay in that repository's `.sembleignore`; keep
+the plugin settings free of per-repository rules.
+
+### Several repositories
+
+`repo` accepts a list, so one call can compare a service with the shared library it depends on:
+
+```json
+{ "query": "where is the retry policy applied", "repo": ["D:\\work\\service", "D:\\work\\shared"] }
+```
+
+Git URLs work the same way and are cloned once into the cache. Each repository gets its own index; a
+list costs one first-time index build per repository.
+
+## Commands
+
+MCP exposes `search` and `find_related`; Semble's two reporting subcommands only exist in its CLI. The
+bundle registers `/semble` for them:
+
+| Command | Prints |
+| --- | --- |
+| `/semble savings` | tokens saved by returning snippets instead of whole files, per period and per call type |
+| `/semble file-types` | the extensions Semble indexes, as JSON grouped by content type |
+
+Both run in the host process: nothing is sent to the model, no approval prompt appears, and the output
+is the CLI's own (colour disabled). The same `uvx --from "semble[mcp]" semble` installation is used, so
+`/semble` works exactly where the MCP server works.
+
+`savings` reads the cache that the MCP server wrote, so it only counts searches made against the same
+`SEMBLE_CACHE_LOCATION`. To see a summary of everything, and for maintenance, stay in a terminal:
+
+```sh
+uvx --from "semble[mcp]" semble savings        # same report, from a shell
+uvx --from "semble[mcp]" semble clear          # drop caches
+uvx --from "semble[mcp]" semble clear index    # force a rebuild
+```
+
+`/semble` is deliberately not a search shortcut — that is what the MCP tools are for — and it has no
+destructive subcommands, because a slash command cannot ask for confirmation. Type `/semble` alone for
+the usage line.
+
 ## Platform notes
 
 The bundle ships no OS-specific path and no region-specific endpoint, so one installation serves all
@@ -144,8 +219,13 @@ DSH loads skills lazily:
 | Model calls `skill` | the full `skills/semble/SKILL.md` body | ~2 KB, only when used |
 | You type `/semble-code-search` | same body, injected into that step | manual |
 
+`/semble-code-search` loads *instructions*: the search itself still runs through the MCP tools. The
+real executable command is `/semble` (see [Commands](#commands)), which runs a CLI report in the host
+and costs no model tokens.
+
 The body never enters the system prompt. To keep the tools and drop the skill, delete the
-`ctx.skills.register(...)` call in `lib/index.js`.
+`ctx.skills.register(...)` block in `lib/index.js`; `/semble` keeps working because it is registered
+separately.
 
 ## How it works
 
@@ -167,11 +247,11 @@ the CLI surface would need an edit here.
 Re-run the install with a newer version, or press 更新 in settings:
 
 ```sh
-dsh plugin --profile web add dsh-semble@2.0.0
+dsh plugin --profile web add dsh-semble@2.1.0
 ```
 
 Source installs re-run with the new ref, e.g.
-`dsh plugin --profile web add github:CodeIntegrity/dsh-semble#v2.0.0`.
+`dsh plugin --profile web add github:CodeIntegrity/dsh-semble#v2.1.0`.
 
 ## Uninstall
 
@@ -195,6 +275,10 @@ The cached index and the HuggingFace model stay on disk and are reused after a r
 | Tools work, row reads 未加载 | `cordis.patch.yml` lost the anchor row | reinstall this version or newer |
 | `mcp__semble__*` never appears | `uvx` missing, or the first download failed | run `uvx --from "semble[mcp]" semble --version` and read the error |
 | First search takes minutes | one-time model download | wait, or set `HF_ENDPOINT` |
+| First search fails on `toolCallTimeoutMs` | index build + model download outran the limit | raise `toolCallTimeoutMs`, or warm the cache once with a CLI search |
+| Search looks stale after a large refactor | the disk index reuses files it believes unchanged | `uvx --from "semble[mcp]" semble clear index`, then search again |
+| `/semble` answers "Could not start the Semble CLI" | `uvx` is not on the host's PATH | install uv, restart DSH |
+| `savings` counts fewer calls than you made | the report reads the cache of the MCP row's `env`, which `/semble` does not inherit | set `SEMBLE_CACHE_LOCATION` in the host environment as well |
 | `ERR_PNPM_GIT_RESOLVE_FAILED` | no network route to github.com | use a tarball URL or a mirror |
 
 ## Development
@@ -204,9 +288,33 @@ git clone https://github.com/CodeIntegrity/dsh-semble
 dsh plugin --profile web add link:$(pwd)   # then edit and restart DSH
 ```
 
-No build step: `lib/index.js` is plain ESM and `cordis.patch.yml` is read directly. The only runtime
+No build step: `lib/` is plain ESM and `cordis.patch.yml` is read directly. The only runtime
 dependency is `uv`.
 
+`npm test` runs the suite with Node's built-in runner. The spawn tests replace `uvx` with the Node
+binary, so they neither download Semble nor touch your cache.
+
+## Publishing
+
+Releases are tag-driven by `.github/workflows/publish.yml`:
+
+```sh
+npm version minor          # bumps package.json and creates the vX.Y.Z tag
+git push origin main --follow-tags
+```
+
+The workflow runs the tests, refuses to continue when the tag and `package.json` disagree, skips a
+version that is already on the registry, and publishes with npm provenance. It needs one repository
+secret:
+
+| Secret | What it is |
+| --- | --- |
+| `NPM_TOKEN` | an npm granular access token with read/write access to `dsh-semble` and 2FA bypass enabled for automation |
+
+Provenance requires a public repository; on a private one, drop `--provenance` from the publish step.
+A manual run of the workflow (`workflow_dispatch`) defaults to publishing the current `package.json`
+version; tick *dry_run* to only run `npm pack --dry-run`.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -21,6 +21,9 @@
 | `mcp__semble__search` | 一句话描述代码做什么、或者它在哪儿 | 按相关度排序的 `file:line` 命中 + 片段 |
 | `mcp__semble__find_related` | 一个你已经知道的位置 | 它的邻居：其他实现、调用方、测试 |
 
+另外还注册了一个 slash command：`/semble savings` 和 `/semble file-types`，用来跑 MCP 没有暴露的
+两个 CLI 报表，见[命令](#命令)。
+
 一次典型对话：
 
 > **你：** DSH 判断「插件已加载」是在哪儿决定的？
@@ -48,7 +51,7 @@
 dsh-semble
 ```
 
-钉住版本写 `dsh-semble@2.0.0`。`desktop` profile 只支持从设置页安装——CLI 会拒绝，
+钉住版本写 `dsh-semble@2.1.0`。`desktop` profile 只支持从设置页安装——CLI 会拒绝，
 因为这个 profile 的 `node_modules` 与 lockfile 由 Electron 应用独占。
 
 ### 命令行
@@ -105,11 +108,77 @@ curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS / Linux
 | `args` | `--from 'semble[mcp]' semble` | 追加 `--content all` 让文档和配置也进索引 |
 | `args`（版本） | 浮动 | 改成 `semble[mcp]==X.Y.Z` 钉版本 |
 | `env` | 空 | 受限网络加 `HF_ENDPOINT`；搬索引加 `SEMBLE_CACHE_LOCATION` |
+| `toolCallTimeoutMs` | `300000` | 首次调用要建索引并下载模型；想更快失败就调小 |
 | `cwd` | 继承 | 保持不设；每次调用的 `repo` 用绝对路径 |
 | `command` | `uvx` | 如果只装了 `.cmd` 包装，改指向 `uvx.exe` |
 
 改设置会重启 MCP 连接；磁盘上的索引缓存不受影响。
 
+## 调优
+
+Semble 从**运行它的进程**的环境变量读配置。MCP server 的变量写在 `semble-mcp` 行的 `env` 里。
+`/semble` 是另起进程、继承宿主环境，所以要让报表和检索看到同一份配置时，两处都要设——真正会出问题的
+只有 `SEMBLE_CACHE_LOCATION`。
+
+| 变量 | 默认值 | 作用 |
+| --- | --- | --- |
+| `SEMBLE_INDEX_WORKERS` | `4` | 首次建索引时切块用的工作进程数；`0` 表示在主进程里做。多核机器可调大，不想让后台检索吃满 CPU 就调小 |
+| `SEMBLE_MCP_IDLE_TIMEOUT` | `0`（永不过期） | 空闲索引在内存缓存里保留多少秒；配合 10 个索引的上限，设 `1800` 可以释放已经不看的仓库 |
+| `SEMBLE_MODEL_NAME` | `minishlab/potion-code-16M-v2` | 换一个 Model2Vec 嵌入模型：本地路径或 Hugging Face 仓库 |
+| `SEMBLE_MAX_FILE_BYTES` | `1000000` | 超过这个大小的文件跳过；生成代码也想进索引就调大 |
+| `SEMBLE_CLONE_TIMEOUT` | `60` | clone `https://` 仓库的超时秒数 |
+| `HF_ENDPOINT` | `https://huggingface.co` | 一次性模型下载走的镜像 |
+
+### 排除文件
+
+索引器认 `.gitignore`，另外认仓库根目录的 `.sembleignore`，用来排除「git 要留、但检索不该看」的文件：
+生成的客户端、fixtures、vendored 目录。语法同 gitignore，支持取反：
+
+```gitignore
+# .sembleignore
+packages/client/generated/
+test/fixtures/
+*.min.js
+!*.proto          # 把被 .gitignore 排除的文件强行拉回索引
+```
+
+只对某一个仓库成立的规则就留在那个仓库的 `.sembleignore` 里，别塞进插件设置。
+
+### 检索多个仓库
+
+`repo` 接受数组，所以一次调用就能把服务端和它依赖的公共库放在一起比：
+
+```json
+{ "query": "重试策略在哪儿生效", "repo": ["D:\\work\\service", "D:\\work\\shared"] }
+```
+
+git 地址同理，首次会 clone 进缓存。每个仓库各有一份索引；传数组时，每个仓库各付一次首次建索引的成本。
+
+## 命令
+
+MCP 只暴露 `search` 与 `find_related`；Semble 的两个报表子命令只存在于 CLI。bundle 为它们注册了
+`/semble`：
+
+| 命令 | 输出 |
+| --- | --- |
+| `/semble savings` | 用片段代替整文件省下的 token，按时间区间和调用类型分列 |
+| `/semble file-types` | Semble 会索引的扩展名，按内容类型分组的 JSON |
+
+两者都在宿主进程里跑：不进模型、不弹审批，输出就是 CLI 原文（已关闭颜色）。用的是同一份
+`uvx --from "semble[mcp]" semble` 安装，所以 MCP server 能用的地方它就能用。
+
+`savings` 读的是 MCP server 写的缓存，因此只统计同一个 `SEMBLE_CACHE_LOCATION` 下的检索。要看全量汇总
+或做维护，回终端：
+
+```sh
+uvx --from "semble[mcp]" semble savings        # 同一份报表，在 shell 里看
+uvx --from "semble[mcp]" semble clear          # 清缓存
+uvx --from "semble[mcp]" semble clear index    # 强制重建索引
+```
+
+`/semble` 故意不做检索捷径——那是 MCP 工具的事；也故意不带破坏性子命令，因为 slash command 没法弹确认。
+只敲 `/semble` 会显示用法。
+
 ## 平台差异
 
 bundle 不含任何 OS 专属路径、也不含区域专属 endpoint，一份安装三平台通用。真正不同的只有你敲进去的东西：
@@ -134,8 +203,11 @@ DSH 的 skill 惰性加载：
 | 模型调 `skill` | 完整 `skills/semble/SKILL.md` 正文 | 约 2 KB，只在实际用到时 |
 | 你输入 `/semble-code-search` | 同一份正文，注入当步 | 手动 |
 
+`/semble-code-search` 注入的是**说明**：真正的检索仍然走 MCP 工具。可执行的命令是 `/semble`
+（见[命令](#命令)），它在宿主里跑 CLI 报表，不花模型 token。
+
 正文不进系统提示词。只想保留工具、不要 skill，删掉 `lib/index.js` 里的 `ctx.skills.register(...)`
-调用即可。
+代码块即可；`/semble` 是单独注册的，不受影响。
 
 ## 工作原理
 
@@ -155,11 +227,11 @@ Semble 本体**不做 vendored 内嵌**。插件只声明如何从 PyPI 拉起
 用更新的版本重跑安装，或在设置页点「更新」：
 
 ```sh
-dsh plugin --profile web add dsh-semble@2.0.0
+dsh plugin --profile web add dsh-semble@2.1.0
 ```
 
 源码安装则换 ref 重跑，例如
-`dsh plugin --profile web add github:CodeIntegrity/dsh-semble#v2.0.0`。
+`dsh plugin --profile web add github:CodeIntegrity/dsh-semble#v2.1.0`。
 
 ## 卸载
 
@@ -182,6 +254,10 @@ dsh plugin --profile web remove dsh-semble
 | 工具能用但显示「未加载」 | `cordis.patch.yml` 缺了锚点行 | 重装本版本或更新版本 |
 | `mcp__semble__*` 一直不出现 | 缺 `uvx`，或首次下载失败 | 手动跑 `uvx --from "semble[mcp]" semble --version` 看报错 |
 | 首次检索卡几分钟 | 模型一次性下载 | 等待，或设 `HF_ENDPOINT` |
+| 首次检索报 `toolCallTimeoutMs` 超时 | 建索引 + 下载模型超过了上限 | 调大 `toolCallTimeoutMs`，或先用 CLI 检索热身 |
+| 大改之后检索结果偏旧 | 磁盘索引复用了「自认为没变」的文件 | `uvx --from "semble[mcp]" semble clear index` 后再检索 |
+| `/semble` 答「Could not start the Semble CLI」 | 宿主 PATH 上没有 `uvx` | 装 uv，重启 DSH |
+| `savings` 统计的调用次数偏少 | 报表读的是 MCP 行 `env` 里的缓存位置，`/semble` 不会继承 | 在宿主环境里也设一次 `SEMBLE_CACHE_LOCATION` |
 | 安装时报 `ERR_PNPM_GIT_RESOLVE_FAILED` | 到 github.com 没有网络通路 | 改用 tarball 链接或镜像 |
 
 ## 开发
@@ -191,7 +267,29 @@ git clone https://github.com/CodeIntegrity/dsh-semble
 dsh plugin --profile web add link:$(pwd)   # 之后改代码、重启 DSH
 ```
 
-没有构建步骤：`lib/index.js` 是纯 ESM，`cordis.patch.yml` 直接读取。唯一运行时依赖是 `uv`。
+没有构建步骤：`lib/` 是纯 ESM，`cordis.patch.yml` 直接读取。唯一运行时依赖是 `uv`。
+
+`npm test` 用 Node 自带的 test runner 跑测试。涉及子进程的用例用 Node 可执行文件代替 `uvx`，
+所以不会下载 Semble，也不会碰你的缓存。
+
+## 发布
+
+发版由 tag 驱动，见 `.github/workflows/publish.yml`：
+
+```sh
+npm version minor          # 改 package.json 并打 vX.Y.Z tag
+git push origin main --follow-tags
+```
+
+工作流会先跑测试，tag 与 `package.json` 不一致时直接失败，版本已在 registry 上则跳过发布，最后带 npm
+provenance 发布。需要配一个仓库 secret：
+
+| Secret | 内容 |
+| --- | --- |
+| `NPM_TOKEN` | npm 细粒度访问令牌，对 `dsh-semble` 有读写权限，并为自动化开启 2FA bypass |
+
+provenance 要求仓库公开；私有仓库请在发布步骤去掉 `--provenance`。手动触发（`workflow_dispatch`）
+默认发布当前 `package.json` 版本；勾上 *dry_run* 只跑 `npm pack --dry-run`。
 
 ## 许可
 

package/cordis.patch.yml

@@ -36,6 +36,13 @@
           - 'semble[mcp]'
           - semble
         failOnStartupError: true
+        # The first search in a repository also builds that repository's index:
+        # chunking runs locally and the embedding model is downloaded once from
+        # HuggingFace. That routinely exceeds the MCP client's 60 s default, which
+        # would fail the first call even though the server is healthy. Five
+        # minutes covers a cold start on a slow link; once an index exists, calls
+        # answer in seconds and the higher ceiling costs nothing.
+        toolCallTimeoutMs: 300000
         # No `env` defaults on purpose: the embedding model
         # (minishlab/potion-code-16M-v2) is fetched from huggingface.co unless the
         # operator asks otherwise. On networks where huggingface.co is unreachable,

package/lib/cli.js

@@ -0,0 +1,221 @@
+/**
+ * Runner for the Semble command line, used by the `/semble` command.
+ *
+ * The bundle talks to Semble through MCP for search, but a few reports only
+ * exist in the CLI: token savings (`semble savings`) and the indexed file
+ * types (`semble file-types`). Those are read-only and cheap, so the command
+ * shells out to the same uvx installation the MCP server uses.
+ *
+ * Output is captured through temporary files rather than pipes: pipes make a
+ * sandboxed host refuse the spawn (EPERM on the named pipe), while file
+ * descriptors keep `/semble` working wherever the plugin loads, and a file also
+ * bounds the capture without stalling the child on a full pipe buffer.
+ *
+ * Only an allow-list is reachable from the command. Destructive subcommands
+ * such as `clear` stay out on purpose: a slash command has no confirmation
+ * step, and the cache it would delete is what makes the next search fast.
+ */
+
+import { spawn } from 'node:child_process'
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+/** How the MCP row launches Semble; kept identical so both share one install. */
+export const SEMBLE_UVX_PREFIX = ['--from', 'semble[mcp]', 'semble']
+
+/** Bumped from the MCP client's 60 s default: savings only reads a jsonl file. */
+export const DEFAULT_TIMEOUT_MS = 60_000
+
+/** Trace reports are tiny; a cap keeps a runaway child from filling the transcript. */
+export const CAPTURE_LIMIT_BYTES = 256 * 1024
+
+const TRUNCATED = '\n… output truncated by dsh-semble …\n'
+
+/** Subcommands exposed by `/semble`, mapped to the argv handed to Semble. */
+const SUBCOMMANDS = new Map([
+  ['savings', ['savings']],
+  ['file-types', ['file-types']],
+])
+
+/**
+ * Parse the raw text typed after `/semble`.
+ *
+ * Strict on purpose: an unknown token is reported instead of being forwarded,
+ * so the command can never reach a subcommand the allow-list excludes.
+ *
+ * @param {string | undefined} rawInput
+ * @returns {{ kind: 'usage' } | { kind: 'unknown', name: string } | { kind: 'run', argv: string[] }}
+ */
+export function parseSembleArgs(rawInput) {
+  const input = typeof rawInput === 'string' ? rawInput.trim() : ''
+  if (input === '') {
+    return { kind: 'usage' }
+  }
+
+  const [name, ...extra] = input.split(/\s+/)
+  const argv = SUBCOMMANDS.get(name)
+  if (argv === undefined || extra.length > 0) {
+    return { kind: 'unknown', name: input }
+  }
+
+  return { kind: 'run', argv: [...argv] }
+}
+
+/**
+ * Run one Semble CLI invocation and capture its output.
+ *
+ * Never rejects: every failure mode (missing uvx, timeout, abort, non-zero
+ * exit) is reported in the resolved value so the command can render it.
+ *
+ * @param {string[]} argv
+ * @param {{ timeoutMs?: number, signal?: AbortSignal, command?: string, prefix?: string[], env?: Record<string, string> }} [options]
+ * @returns {Promise<{ code: number | null, stdout: string, stderr: string, timedOut?: boolean, aborted?: boolean, error?: string }>}
+ */
+export function runSemble(argv, options = {}) {
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    signal,
+    command = 'uvx',
+    prefix = SEMBLE_UVX_PREFIX,
+    env,
+  } = options
+
+  if (signal?.aborted) {
+    return Promise.resolve({ code: null, stdout: '', stderr: '', aborted: true })
+  }
+
+  let capture
+  try {
+    capture = openCapture()
+  } catch (error) {
+    return Promise.resolve({ code: null, stdout: '', stderr: '', error: messageOf(error) })
+  }
+
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(command, [...prefix, ...argv], {
+        // NO_COLOR/FORCE_COLOR keep ANSI escapes out of the transcript; the rest
+        // of the environment is inherited so SEMBLE_* tuning applies.
+        env: { ...process.env, ...env, NO_COLOR: '1', FORCE_COLOR: '0' },
+        stdio: ['ignore', capture.stdoutFd, capture.stderrFd],
+        windowsHide: true,
+      })
+    } catch (error) {
+      capture.dispose()
+      resolve({ code: null, stdout: '', stderr: '', error: messageOf(error) })
+      return
+    }
+
+    let timedOut = false
+    let aborted = false
+    let settled = false
+
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener?.('abort', onAbort)
+      const { stdout, stderr } = capture.collect()
+      capture.dispose()
+      resolve({ ...result, stdout, stderr })
+    }
+
+    const kill = () => {
+      child.kill('SIGTERM')
+      // A child that ignores SIGTERM must not outlive the command; the
+      // unref'd escalation is dropped once the event loop is done with it.
+      setTimeout(() => child.kill('SIGKILL'), 2_000).unref?.()
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      kill()
+    }, timeoutMs)
+
+    function onAbort() {
+      aborted = true
+      kill()
+    }
+    signal?.addEventListener?.('abort', onAbort, { once: true })
+
+    child.on('error', (error) => finish({ code: null, error: messageOf(error) }))
+    child.on('close', (code, closeSignal) =>
+      finish({
+        code: typeof code === 'number' ? code : null,
+        timedOut,
+        aborted,
+        ...(closeSignal ? { signal: closeSignal } : {}),
+      }),
+    )
+  })
+}
+
+/**
+ * A private directory holding the child's two output streams.
+ *
+ * The descriptors stay open for the child's lifetime and are closed before the
+ * files are read, so a child that writes until its last moment (or is killed)
+ * still leaves a complete prefix behind.
+ */
+function openCapture() {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-semble-'))
+  const stdoutPath = join(dir, 'stdout.log')
+  const stderrPath = join(dir, 'stderr.log')
+
+  const stdoutFd = openSync(stdoutPath, 'w')
+  let stderrFd
+  try {
+    stderrFd = openSync(stderrPath, 'w')
+  } catch (error) {
+    closeSync(stdoutFd)
+    rmSync(dir, { recursive: true, force: true })
+    throw error
+  }
+
+  return {
+    stdoutFd,
+    stderrFd,
+    collect() {
+      closeSync(stdoutFd)
+      closeSync(stderrFd)
+      return { stdout: readCapped(stdoutPath), stderr: readCapped(stderrPath) }
+    },
+    dispose() {
+      try {
+        closeSync(stdoutFd)
+      } catch {}
+      try {
+        closeSync(stderrFd)
+      } catch {}
+      rmSync(dir, { recursive: true, force: true })
+    },
+  }
+}
+
+/** Read at most CAPTURE_LIMIT_BYTES and mark the cut, so output stays bounded. */
+function readCapped(path) {
+  try {
+    if (statSync(path).size === 0) return ''
+    const text = readFileSync(path, 'utf8')
+    return text.length > CAPTURE_LIMIT_BYTES ? text.slice(0, CAPTURE_LIMIT_BYTES) + TRUNCATED : text
+  } catch {
+    return ''
+  }
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** Text shown for `/semble` with no argument, and after an unknown one. */
+export const SEMBLE_USAGE = [
+  'Semble CLI reports',
+  '',
+  '  /semble savings      tokens saved by snippets instead of whole files',
+  '  /semble file-types   file extensions Semble indexes, per content type',
+  '',
+  'Runs the same uvx installation the MCP server uses. Cache maintenance stays in a',
+  'terminal: uvx --from "semble[mcp]" semble clear --help',
+].join('\n')

package/lib/index.js

@@ -17,6 +17,11 @@
  *    semble/SKILL.md) and is registered as a runtime skill, which keeps plugin
  *    installation a single step: no copying files into ~/.dsh/skills.
  *
+ * 3. Register the `/semble` command, which shells out to the Semble CLI for the
+ *    two read-only reports MCP does not expose (`savings`, `file-types`). The
+ *    command runs in the host, so it works wherever the plugin works, and its
+ *    output never costs a model turn.
+ *
  * The skill is loaded lazily by DSH: the session catalog carries only the name
  * and description, and the body text reaches the model only when it calls the
  * `skill` tool. Reading the file here costs one small synchronous read at host
@@ -24,6 +29,8 @@
  */
 import { readFileSync } from 'node:fs'
 
+import { parseSembleArgs, runSemble, SEMBLE_USAGE } from './cli.js'
+
 export const name = 'semble-mcp'
 
 export const inject = ['skills']
@@ -48,23 +55,92 @@ function readSkillBody() {
   }
 }
 
-/** Apply: provide the loader anchor and register the bundled routing skill. */
+/**
+ * Handler for `/semble`.
+ *
+ * Returns a CommandResult instead of throwing: the command surface renders
+ * `{ kind: 'error' }` inline, and a failed uvx run is an ordinary answer here,
+ * not a plugin fault.
+ */
+export async function handleSembleCommand(invocation) {
+  const parsed = parseSembleArgs(invocation.rawInput)
+
+  if (parsed.kind === 'usage') {
+    return { kind: 'success', text: SEMBLE_USAGE }
+  }
+  if (parsed.kind === 'unknown') {
+    return { kind: 'error', text: `Unknown subcommand "${parsed.name}".\n\n${SEMBLE_USAGE}` }
+  }
+
+  const result = await runSemble(parsed.argv, { signal: invocation.signal })
+  const output = [result.stdout?.trim(), result.stderr?.trim()].filter(Boolean).join('\n')
+
+  if (result.error !== undefined) {
+    return {
+      kind: 'error',
+      text: `Could not start the Semble CLI (${result.error}). Install uv first: https://docs.astral.sh/uv/`,
+    }
+  }
+  if (result.aborted === true) {
+    return { kind: 'error', text: 'Semble CLI command cancelled.' }
+  }
+  if (result.timedOut === true) {
+    return {
+      kind: 'error',
+      text: `Semble CLI did not finish within its time limit; the first uvx run may still be downloading.\n\n${output}`.trim(),
+    }
+  }
+  if (result.code !== 0) {
+    return {
+      kind: 'error',
+      text: `semble ${parsed.argv.join(' ')} exited with code ${result.code ?? 'unknown'}.\n\n${output}`.trim(),
+    }
+  }
+
+  return { kind: 'success', text: output === '' ? 'Semble CLI returned no output.' : output }
+}
+
+/**
+ * Register `/semble` once the optional `commands` service is available.
+ *
+ * A UI-less composition (for example an ACP automation profile) provides no
+ * command surface; the MCP tools and the skill must keep working there, so the
+ * command is a child plugin rather than a hard dependency.
+ */
+function registerSembleReports(ctx) {
+  ctx.commands.register({
+    name: 'semble',
+    description: 'Show Semble CLI reports (token savings, indexed file types)',
+    input: { hint: 'savings | file-types' },
+    handler: handleSembleCommand,
+  })
+}
+
+/** Apply: provide the loader anchor, the routing skill, and the CLI reports. */
 export default function sembleMcpBundle(ctx) {
   const content = readSkillBody()
-  if (content === undefined) return
-  // Registered into this plugin's layer, so teardown follows the fiber and the
-  // returned disposer needs no bookkeeping here.
-  ctx.skills.register({
-    name: 'semble-code-search',
-    description:
-      'Find code by what it does, not by exact text. Use when locating an implementation, a caller, or a related pattern before editing, or when a plain text search returns too much noise.',
-    whenToUse:
-      'before a broad code search in a repository, and when a grep result is too noisy to be useful; gives the query shape, the semantic search workflow, and the cost limits of the Semble MCP tools.',
-    content,
-    source: 'bundle:dsh-semble',
-    resourceBase: { kind: 'opaque', description: 'Exposed as the mcp__semble__search and mcp__semble__find_related MCP tools.' },
-    invocation: { modelInvocable: true, userInvocable: true },
-  })
+  if (content !== undefined) {
+    // Registered into this plugin's layer, so teardown follows the fiber and the
+    // returned disposer needs no bookkeeping here.
+    ctx.skills.register({
+      name: 'semble-code-search',
+      description:
+        'Find code by what it does, not by exact text. Use when locating an implementation, a caller, or a related pattern before editing, or when a plain text search returns too much noise.',
+      whenToUse:
+        'before a broad code search in a repository, and when a grep result is too noisy to be useful; gives the query shape, the semantic search workflow, and the cost limits of the Semble MCP tools.',
+      content,
+      source: 'bundle:dsh-semble',
+      resourceBase: { kind: 'opaque', description: 'Exposed as the mcp__semble__search and mcp__semble__find_related MCP tools.' },
+      invocation: { modelInvocable: true, userInvocable: true },
+    })
+  }
+
+  // `ctx.inject` starts a child plugin that loads only when the commands service
+  // exists, which keeps UI-less compositions usable while adding `/semble`
+  // wherever a command surface is present.
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['commands'], registerSembleReports)
+  }
 }
 
 /**

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Semble Code Search (MCP)",
-    "description": "Exposes the Semble agent code-search engine as native MCP tools (search / find_related). Starts the official Semble MCP server from PyPI via uvx; follows the latest upstream release automatically."
+    "description": "Exposes the Semble agent code-search engine as native MCP tools (search / find_related) and adds a /semble command for the CLI's token-savings and file-type reports. Starts the official Semble MCP server from PyPI via uvx; follows the latest upstream release automatically."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Semble 代码搜索（MCP）",
-    "description": "把 Semble 的 Agent 代码检索引擎接入为原生 MCP 工具（search / find_related）。通过 uvx 从 PyPI 启动官方 Semble MCP 服务器，自动跟随上游最新版本。"
+    "description": "把 Semble 的 Agent 代码检索引擎接入为原生 MCP 工具（search / find_related），并新增 /semble 命令输出 CLI 的 token 节约与文件类型报表。通过 uvx 从 PyPI 启动官方 Semble MCP 服务器，自动跟随上游最新版本。"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-semble",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "main": "lib/index.js",
   "description": "Semble 语义代码搜索（semantic code search）MCP bundle：安装即用，无需客户端配置。Semble semantic code search for DeepSeek Harness via MCP (search / find_related).",
@@ -44,6 +44,9 @@
     "README.md",
     "README.zh-CN.md"
   ],
+  "scripts": {
+    "test": "node --test"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"

package/skills/semble/SKILL.md

@@ -62,4 +62,6 @@ Controls, all on both tools unless noted:
 
 `mcp__semble__search` and `mcp__semble__find_related` only exist when this bundle's MCP connection
 mounted in the current session. If they are absent from your toolset, say so and fall back to
-`grep`/`glob`; do not narrate a call you cannot make.
+`grep`/`glob`; do not narrate a call you cannot make. The user can still run `/semble savings` and
+`/semble file-types` from the composer — those are host commands and do not depend on the MCP
+connection.