dsh-workspace-intelligence

Readme

<div align="right">
中文 | <a href="./README.en.md">English</a>
</div>

# dsh-workspace-intelligence

独立的 DeepSeek Harness（DSH）/ Cordis 插件。它提供 `workspace_symbol` 工具，让 agent 在不知道文件和光标位置时，通过标准 LSP `workspace/symbol` 按名称查找代码符号。

插件只依赖公开的 `ctx.fs`、`ctx.subprocess` 和 `ctx.tools`，不修改 DeepSeek Harness，也不调用 `ctx.lsp`。现有 `goToDefinition`、`findReferences`、`goToImplementation` 和 `hover` 的行为不受影响。

## 安装

要求 Node.js `^22.19.0` 或 `>=24`、兼容 `^0.1.0-rc.6` 的 DSH 公开包，以及至少一个支持 stdio LSP 的 language server。

```sh
dsh plugin --profile <name> add dsh-workspace-intelligence
pnpm add -g pyright typescript typescript-language-server
```

插件默认禁用，因为 language server 命令必须由部署方指定。

### Windows

运行 `pnpm root -g`，把 [Windows 配置模板](./examples/windows/cordis.patch.yml) 合并到 profile 的 `cordis.patch.yml`，再将两处 `C:/pnpm-global-root` 替换为实际输出（路径分隔符改为 `/`）。保留 `node + JS 绝对路径`，不要使用 `.cmd` shim；`ctx.subprocess` 不经过 shell。

### macOS/Linux

把 [macOS/Linux 配置模板](./examples/macos-linux/cordis.patch.yml) 合并到 profile 的 `cordis.patch.yml`。模板直接从 PATH 启动 `pyright-langserver` 和 `typescript-language-server`。

DSH patch 会整体替换一行的 `config`；覆盖时请写全所有非默认项。启动前检查合成结果：

```sh
dsh --profile <name> --dump-config
```

## 使用

模型只传一个必填参数：

```json
{ "query": "SessionManager" }
```

workspace root 固定取调用 session 的 `header.cwd`。空白 query 会被拒绝，不允许模型选择 provider、命令、workspace 或 timeout。

结果包含符号名、可读的 `kind`、canonical URI、可选 range 和 `containerName`。插件兼容 `SymbolInformation[]`、`WorkspaceSymbol[]`、URI-only location、`null` 和空数组；不会伪造位置，也不会向模型暴露 raw JSON-RPC。

## 配置

`servers` 必填且至少有一项。server id 会按字典序排序，因此对象插入顺序不影响行为。

| 配置 | 默认值 | 说明 |
| --- | ---: | --- |
| `command` | 必填 | executable 绝对路径或由 `ctx.subprocess` 解析的命令名 |
| `args` | `[]` | 直接传入的 argv，不经过 shell |
| `env` | `{}` | 子进程环境变量增量 |
| `initializationOptions` | `null` | LSP initialize 参数 |
| `configuration` | `null` | `workspace/configuration` 返回值 |
| `maxMessageBytes` | `16000000` | 单条 LSP 消息上限 |
| `maxStderrBytes` | `1000000` | stderr 诊断尾部上限 |
| `shutdownTimeoutMs` | `5000` | graceful shutdown 等待时间 |
| `killGraceMs` | `2000` | process-tree 终止等待时间 |
| `maxResults` | `100` | merge 和去重后保留的符号数 |
| `maxResultChars` | `16000` | 完整模型输出字符预算，最小 `256` |
| `timeoutMs` | `60000` | 交给 DSH timeout policy 的工具超时元数据 |

## 行为边界

- 查询会 fan-out 到全部已配置 server；server 间并发，同一 server 内串行。
- 结果按 exact match、prefix match、其他结果、server id 和 server 原始顺序稳定排序。
- 去重 key 为 `name + kind + URI + optional range`；排序后的第一项保留。
- 任一 provider 成功（包括空结果）即返回成功；失败和不支持的 provider 只计数。全部不支持时报 `WORKSPACE_SYMBOL_UNSUPPORTED`，存在失败且无成功结果时报 `WORKSPACE_SYMBOL_PROVIDER_FAILED`。
- caller cancellation 会发送 best-effort `$/cancelRequest`，并原样拒绝；不会变成 partial success。
- 每个 canonical workspace/server 惰性复用一个进程；卸载时先移除工具，再执行 `shutdown`、`exit` 和必要的 process-tree 终止。
- 不提供 grep fallback、document symbols、call hierarchy、embedding、raw JSON-RPC 或 cursor-based LSP 操作。

## 开发

```sh
pnpm test
pnpm test:coverage
pnpm typecheck
pnpm lint
pnpm build
pnpm pack:check
```