dsh-code-index 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +20 -20
- package/README.md +142 -129
- package/README.zh.md +138 -125
- package/cordis.patch.yml +4 -4
- package/dist/index.js +62 -19
- package/dist/index.js.map +1 -1
- package/package.json +13 -5
- package/scripts/fix-wsl-links.mjs +154 -0
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 dsh-code-index contributors
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-code-index contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
21
|
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,129 +1,142 @@
|
|
|
1
|
-
# dsh-code-index
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/dsh-code-index)
|
|
4
|
-
[](https://github.com/lemonxiny55/dsh-code-index/actions)
|
|
5
|
-
|
|
6
|
-
English | [中文](README.zh.md)
|
|
7
|
-
|
|
8
|
-
Semantic repo index — a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) plugin that gives the agent a **codebase map**: a tree-sitter symbol index, ranked symbol search, and a bounded auto-updating repo map in the system prompt.
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
## What the model gets
|
|
13
|
-
|
|
14
|
-
| Tool | Purpose |
|
|
15
|
-
|---|---|
|
|
16
|
-
| `code_index` | Status / (re)build the index for the current workspace |
|
|
17
|
-
| `code_symbols` | List symbols (functions, classes, interfaces, types, methods…) with file:line — filtered by name, path, kind, exported |
|
|
18
|
-
| `code_search` | Ranked lookup: exact > prefix > substring > subsequence-fuzzy, exports first, relevance score + file:line |
|
|
19
|
-
| `code_map` | Bounded ranked repo map (top files by symbol density + import
|
|
20
|
-
|
|
21
|
-
Plus an optional **auto-injected system prompt section** (`code-index:repo-map`, order 60): a compact ranked map of the default workspace, refreshed on a TTL (`mapTtlMs`, default 60s). Set `autoInject: false` to disable and rely on the `code_map` tool only.
|
|
22
|
-
|
|
23
|
-
## Install
|
|
24
|
-
|
|
25
|
-
Requires `dsh` (any install path — npx, npm, or source) and Node ≥ 22.
|
|
26
|
-
|
|
27
|
-
```sh
|
|
28
|
-
# from npm (prebuilt)
|
|
29
|
-
npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
|
|
30
|
-
|
|
31
|
-
# or from a directory containing this checkout
|
|
32
|
-
npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Restart the Web UI (`npx @deepseek-ai/dsh web`) — startup logs confirm each tool:
|
|
36
|
-
|
|
37
|
-
```
|
|
38
|
-
[dsh-code-index] plugin loaded
|
|
39
|
-
[dsh-code-index] registered tool: code_index
|
|
40
|
-
...
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Verify the composed config without booting: `dsh --profile web --dump-config`.
|
|
44
|
-
|
|
45
|
-
## Using it
|
|
46
|
-
|
|
47
|
-
In a workspace session, ask the agent:
|
|
48
|
-
|
|
49
|
-
- "Which repo are we in — run code_map first."
|
|
50
|
-
- "Find every function whose name contains `parse` and where it lives."
|
|
51
|
-
- "List the exported symbols in src/core."
|
|
52
|
-
- "Rebuild the code index."
|
|
53
|
-
|
|
54
|
-
No API key is needed to *index*; the model must of course be configured to call the tools.
|
|
55
|
-
|
|
56
|
-
## Example (input → output)
|
|
57
|
-
|
|
58
|
-
User prompt:
|
|
59
|
-
|
|
60
|
-
> Which repo are we in? Run `code_map` first, then find where `extractSymbols` is defined.
|
|
61
|
-
|
|
62
|
-
The agent calls the tools in turn:
|
|
63
|
-
|
|
64
|
-
```
|
|
65
|
-
code_map
|
|
66
|
-
# repo map
|
|
67
|
-
## src/extract.ts (14)
|
|
68
|
-
function extractSymbols(code, id) :121
|
|
69
|
-
function languageForFile(filePath) :37
|
|
70
|
-
...
|
|
71
|
-
|
|
72
|
-
code_search { query: "extractSymbols" }
|
|
73
|
-
export function extractSymbols(code, id) — src/extract.ts:121
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
The index builds lazily on first use; later calls are served from the on-disk cache with mtime-incremental refresh.
|
|
77
|
-
|
|
78
|
-
## Configuration
|
|
79
|
-
|
|
80
|
-
Options are passed as the plugin row's `config` in the profile patch (or defaults are used if absent):
|
|
81
|
-
|
|
82
|
-
```yaml
|
|
83
|
-
# $DSH_HOME/profiles/<name>/cordis.patch.yml — a bare row overrides by id.
|
|
84
|
-
- id: code-index
|
|
85
|
-
config:
|
|
86
|
-
excludeDirs: [generated, playground]
|
|
87
|
-
mapTopFiles: 30
|
|
88
|
-
mapMaxChars: 4000
|
|
89
|
-
autoInject: true
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
| Key | Default | Meaning |
|
|
93
|
-
|---|---|---|
|
|
94
|
-
| `excludeDirs` | `[]` | Extra dirs appended to the built-in excludes (`node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `.next`, `.nuxt`, `.cache`, `target`, `vendor`, …) |
|
|
95
|
-
| `mapTopFiles` | `24` | Max files in a ranked map |
|
|
96
|
-
| `mapMaxChars` | `3200` | Hard cap on rendered map characters |
|
|
97
|
-
| `mapTtlMs` | `60000` | Refresh interval for the auto-injected map (ms, min 1000) |
|
|
98
|
-
| `autoInject` | `true` | Register the system prompt section |
|
|
99
|
-
|
|
100
|
-
## Supported languages
|
|
101
|
-
|
|
102
|
-
TypeScript, JavaScript, Python, Go, Rust and Java (`.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java`) via tree-sitter WASM — pure parsing, no native build. The symbol provider seam (`src/extract.ts` + grammars) is where other languages/embeddings plug in later.
|
|
103
|
-
|
|
104
|
-
## How it works
|
|
105
|
-
|
|
106
|
-
- **Index build** (`src/buildIndex.ts`): recursive scan (excludes applied), per-file tree-sitter extraction (`src/extract.ts`), JSON cache under `<repo>/.dsh-code-index/`, incremental refresh by mtime (only touched files re-parse).
|
|
107
|
-
- **Search** (`src/search.ts`): pure scoring — exact `1` / prefix `0.8` / substring `0.5`, export boost, name order tiebreak.
|
|
108
|
-
- **Repo map** (`src/repomap.ts`): density-aware file score (class/interface/function weighted,
|
|
109
|
-
- **Workspace resolution**: each tool resolves the session cwd (`agent.session.header.cwd`) and walks up to the nearest `.git` (bounded — a directory without a repo marker is never indexed).
|
|
110
|
-
|
|
111
|
-
## Known limitations
|
|
112
|
-
|
|
113
|
-
- **web-tree-sitter pinned to `^0.
|
|
114
|
-
- Auto-injected section targets the **default workspace** (launch directory, matching headless/CLI mode). Multi-workspace Web UI sessions should use `code_map`/`code_symbols` (they resolve per-session cwd).
|
|
115
|
-
- Local variables are indexed too — recall over precision; `code_search` ranking keeps them low.
|
|
116
|
-
- Developer-preview harness: expect breaking harness/plugin API changes upstream.
|
|
117
|
-
|
|
118
|
-
## Development
|
|
119
|
-
|
|
120
|
-
```sh
|
|
121
|
-
pnpm install
|
|
122
|
-
pnpm test # vitest — extractor, scan, cache, search, repo map
|
|
123
|
-
pnpm typecheck
|
|
124
|
-
pnpm build # tsup → dist/index.js (ESM, external deps)
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
1
|
+
# dsh-code-index
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-code-index)
|
|
4
|
+
[](https://github.com/lemonxiny55/dsh-code-index/actions)
|
|
5
|
+
|
|
6
|
+
English | [中文](README.zh.md)
|
|
7
|
+
|
|
8
|
+
Semantic repo index — a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) plugin that gives the agent a **codebase map**: a tree-sitter symbol index, ranked symbol search, and a bounded auto-updating repo map in the system prompt.
|
|
9
|
+
|
|
10
|
+
Fits a niche the ecosystem took a while to fill: alongside git/voice/browser/memory plugins, several code-intelligence plugins have appeared (graph-based, embedding-based), while this one stays deliberately **dependency-free** — pure in-process tree-sitter over WASM, the aider repo-map / Cursor `@Codebase` style for dsh agents.
|
|
11
|
+
|
|
12
|
+
## What the model gets
|
|
13
|
+
|
|
14
|
+
| Tool | Purpose |
|
|
15
|
+
|---|---|
|
|
16
|
+
| `code_index` | Status / (re)build the index for the current workspace |
|
|
17
|
+
| `code_symbols` | List symbols (functions, classes, interfaces, types, methods…) with file:line — filtered by name, path, kind, exported |
|
|
18
|
+
| `code_search` | Ranked lookup: exact > prefix > substring > subsequence-fuzzy, exports first, relevance score + file:line |
|
|
19
|
+
| `code_map` | Bounded ranked repo map (top files by symbol density + import-graph PageRank, key symbols + lines) |
|
|
20
|
+
|
|
21
|
+
Plus an optional **auto-injected system prompt section** (`code-index:repo-map`, order 60): a compact ranked map of the default workspace, refreshed on a TTL (`mapTtlMs`, default 60s). Set `autoInject: false` to disable and rely on the `code_map` tool only.
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
Requires `dsh` (any install path — npx, npm, or source) and Node ≥ 22.
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
# from npm (prebuilt)
|
|
29
|
+
npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
|
|
30
|
+
|
|
31
|
+
# or from a directory containing this checkout
|
|
32
|
+
npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Restart the Web UI (`npx @deepseek-ai/dsh web`) — startup logs confirm each tool:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
[dsh-code-index] plugin loaded
|
|
39
|
+
[dsh-code-index] registered tool: code_index
|
|
40
|
+
...
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Verify the composed config without booting: `dsh --profile web --dump-config`.
|
|
44
|
+
|
|
45
|
+
## Using it
|
|
46
|
+
|
|
47
|
+
In a workspace session, ask the agent:
|
|
48
|
+
|
|
49
|
+
- "Which repo are we in — run code_map first."
|
|
50
|
+
- "Find every function whose name contains `parse` and where it lives."
|
|
51
|
+
- "List the exported symbols in src/core."
|
|
52
|
+
- "Rebuild the code index."
|
|
53
|
+
|
|
54
|
+
No API key is needed to *index*; the model must of course be configured to call the tools.
|
|
55
|
+
|
|
56
|
+
## Example (input → output)
|
|
57
|
+
|
|
58
|
+
User prompt:
|
|
59
|
+
|
|
60
|
+
> Which repo are we in? Run `code_map` first, then find where `extractSymbols` is defined.
|
|
61
|
+
|
|
62
|
+
The agent calls the tools in turn:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
code_map
|
|
66
|
+
# repo map
|
|
67
|
+
## src/extract.ts (14)
|
|
68
|
+
function extractSymbols(code, id) :121
|
|
69
|
+
function languageForFile(filePath) :37
|
|
70
|
+
...
|
|
71
|
+
|
|
72
|
+
code_search { query: "extractSymbols" }
|
|
73
|
+
export function extractSymbols(code, id) — src/extract.ts:121
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The index builds lazily on first use; later calls are served from the on-disk cache with mtime-incremental refresh.
|
|
77
|
+
|
|
78
|
+
## Configuration
|
|
79
|
+
|
|
80
|
+
Options are passed as the plugin row's `config` in the profile patch (or defaults are used if absent):
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
# $DSH_HOME/profiles/<name>/cordis.patch.yml — a bare row overrides by id.
|
|
84
|
+
- id: code-index
|
|
85
|
+
config:
|
|
86
|
+
excludeDirs: [generated, playground]
|
|
87
|
+
mapTopFiles: 30
|
|
88
|
+
mapMaxChars: 4000
|
|
89
|
+
autoInject: true
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
| Key | Default | Meaning |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| `excludeDirs` | `[]` | Extra dirs appended to the built-in excludes (`node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `.next`, `.nuxt`, `.cache`, `target`, `vendor`, …) |
|
|
95
|
+
| `mapTopFiles` | `24` | Max files in a ranked map |
|
|
96
|
+
| `mapMaxChars` | `3200` | Hard cap on rendered map characters |
|
|
97
|
+
| `mapTtlMs` | `60000` | Refresh interval for the auto-injected map (ms, min 1000) |
|
|
98
|
+
| `autoInject` | `true` | Register the system prompt section |
|
|
99
|
+
|
|
100
|
+
## Supported languages
|
|
101
|
+
|
|
102
|
+
TypeScript, JavaScript, Python, Go, Rust and Java (`.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java`) via tree-sitter WASM — pure parsing, no native build. The symbol provider seam (`src/extract.ts` + grammars) is where other languages/embeddings plug in later.
|
|
103
|
+
|
|
104
|
+
## How it works
|
|
105
|
+
|
|
106
|
+
- **Index build** (`src/buildIndex.ts`): recursive scan (excludes applied), per-file tree-sitter extraction (`src/extract.ts`), JSON cache under `<repo>/.dsh-code-index/`, incremental refresh by mtime (only touched files re-parse).
|
|
107
|
+
- **Search** (`src/search.ts`): pure scoring — exact `1` / prefix `0.8` / substring `0.5`, export boost, name order tiebreak.
|
|
108
|
+
- **Repo map** (`src/repomap.ts`): personalized PageRank over the import graph (teleport = per-file density share, so hub files that are themselves imported by other hubs rise above flat in-degree counting), seeded by the density-aware file score (class/interface/function weighted, test paths damped), top-N files, per-file symbol cap, hard char truncation.
|
|
109
|
+
- **Workspace resolution**: each tool resolves the session cwd (`agent.session.header.cwd`) and walks up to the nearest `.git` (bounded — a directory without a repo marker is never indexed).
|
|
110
|
+
|
|
111
|
+
## Known limitations
|
|
112
|
+
|
|
113
|
+
- **web-tree-sitter pinned to `^0.25` (ESM)** — the 0.25 line uses ESM named exports (`Language`/`Query`); this pairing with `tree-sitter-wasms` static builds is verified working under Node ≥ 22/24.
|
|
114
|
+
- Auto-injected section targets the **default workspace** (launch directory, matching headless/CLI mode). Multi-workspace Web UI sessions should use `code_map`/`code_symbols` (they resolve per-session cwd).
|
|
115
|
+
- Local variables are indexed too — recall over precision; `code_search` ranking keeps them low.
|
|
116
|
+
- Developer-preview harness: expect breaking harness/plugin API changes upstream.
|
|
117
|
+
|
|
118
|
+
## Development
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
pnpm install
|
|
122
|
+
pnpm test # vitest — extractor, scan, cache, search, repo map
|
|
123
|
+
pnpm typecheck
|
|
124
|
+
pnpm build # tsup → dist/index.js (ESM, external deps)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**WSL → Windows checkouts:** running `pnpm install` from WSL against a checkout on `/mnt/c` leaves Linux-style symlinks that Windows Node cannot traverse (`Cannot find package 'web-tree-sitter'`, `EACCES`). Repair without a reinstall from the Windows side:
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
node.exe scripts\fix-wsl-links.mjs # this repo's node_modules
|
|
131
|
+
node.exe scripts\fix-wsl-links.mjs C:\Users\you\.dsh\profiles\web # a dsh profile install
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
It re-points every dead link at its real `.pnpm` store entry as a junction; safe to re-run (idempotent, reports `fixed: 0` when clean).
|
|
135
|
+
|
|
136
|
+
## Feedback
|
|
137
|
+
|
|
138
|
+
Found a bug, or the map ranks something badly? Please [open an issue](https://github.com/lemonxiny55/dsh-code-index/issues) — real-world usage reports (repos where the ranking misbehaves, languages you want next) directly drive the roadmap.
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
MIT. Not affiliated with DeepSeek; built on the public `dsh` plugin surface.
|
package/README.zh.md
CHANGED
|
@@ -1,126 +1,139 @@
|
|
|
1
|
-
# dsh-code-index
|
|
2
|
-
|
|
3
|
-
[English](README.md) | 中文
|
|
4
|
-
|
|
5
|
-
语义仓库索引 —— 一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)插件,为 agent 提供**代码库地图**:基于 tree-sitter 的符号索引、带排名的符号搜索,以及注入到系统提示词里的限量自动更新仓库地图。
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## 模型能得到什么
|
|
10
|
-
|
|
11
|
-
| 工具 | 用途 |
|
|
12
|
-
|---|---|
|
|
13
|
-
| `code_index` | 查看 / (重)建当前工作区的索引 |
|
|
14
|
-
| `code_symbols` | 列出符号(函数、类、接口、类型、方法……),带 file:line——支持按名称、路径、类型、是否导出过滤 |
|
|
15
|
-
| `code_search` | 排名检索:精确 > 前缀 > 子串 > 子序列模糊,导出优先,带相关度分数与 file:line |
|
|
16
|
-
| `code_map` | 限量排名仓库地图(按符号密度 +
|
|
17
|
-
|
|
18
|
-
外加一个可选的**自动注入系统提示词段**(`code-index:repo-map`,序 60):默认工作区的精简排名地图,按 TTL 自动刷新(`mapTtlMs`,默认 60 秒)。将 `autoInject: false` 可关闭,只依赖 `code_map` 工具。
|
|
19
|
-
|
|
20
|
-
## 安装
|
|
21
|
-
|
|
22
|
-
需要 `dsh`(任意安装方式——npx、npm 或源码)与 Node ≥ 22。
|
|
23
|
-
|
|
24
|
-
```sh
|
|
25
|
-
# 从 npm(预编译)
|
|
26
|
-
npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
|
|
27
|
-
|
|
28
|
-
# 或从包含本仓库检查副本的目录
|
|
29
|
-
npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
重启 Web UI(`npx @deepseek-ai/dsh web`)——启动日志会确认每个工具:
|
|
33
|
-
|
|
34
|
-
```
|
|
35
|
-
[dsh-code-index] plugin loaded
|
|
36
|
-
[dsh-code-index] registered tool: code_index
|
|
37
|
-
...
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
不启动即可核对组合配置:`dsh --profile web --dump-config`。
|
|
41
|
-
|
|
42
|
-
## 使用
|
|
43
|
-
|
|
44
|
-
在工作区会话中,向 agent 提这类请求:
|
|
45
|
-
|
|
46
|
-
- "我们现在在哪个仓库?先跑 code_map。"
|
|
47
|
-
- "找出所有名字含 `parse` 的函数及其位置。"
|
|
48
|
-
- "列出 src/core 里的导出符号。"
|
|
49
|
-
- "重建代码索引。"
|
|
50
|
-
|
|
51
|
-
*索引*本身不需要 API key;模型当然要配置好才能调用这些工具。
|
|
52
|
-
|
|
53
|
-
## 示例(输入 → 输出)
|
|
54
|
-
|
|
55
|
-
用户提示:
|
|
56
|
-
|
|
57
|
-
> 我们现在在哪个仓库?先跑 `code_map`,然后找出 `extractSymbols` 定义在哪。
|
|
58
|
-
|
|
59
|
-
agent 依次调用工具:
|
|
60
|
-
|
|
61
|
-
```
|
|
62
|
-
code_map
|
|
63
|
-
# repo map
|
|
64
|
-
## src/extract.ts (14)
|
|
65
|
-
function extractSymbols(code, id) :121
|
|
66
|
-
function languageForFile(filePath) :37
|
|
67
|
-
...
|
|
68
|
-
|
|
69
|
-
code_search { query: "extractSymbols" }
|
|
70
|
-
export function extractSymbols(code, id) — src/extract.ts:121
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
索引在首次使用时惰性构建;后续调用由磁盘缓存提供,并按 mtime 增量刷新。
|
|
74
|
-
|
|
75
|
-
## 配置
|
|
76
|
-
|
|
77
|
-
选项通过插件行的 `config` 在 profile 补丁中传入(缺省时使用默认值):
|
|
78
|
-
|
|
79
|
-
```yaml
|
|
80
|
-
# $DSH_HOME/profiles/<name>/cordis.patch.yml —— 裸行按 id 覆盖。
|
|
81
|
-
- id: code-index
|
|
82
|
-
config:
|
|
83
|
-
excludeDirs: [generated, playground]
|
|
84
|
-
mapTopFiles: 30
|
|
85
|
-
mapMaxChars: 4000
|
|
86
|
-
autoInject: true
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
| 键 | 默认 | 含义 |
|
|
90
|
-
|---|---|---|
|
|
91
|
-
| `excludeDirs` | `[]` | 追加到内置排除列表(`node_modules`、`.git`、`dist`、`build`、`out`、`coverage`、`.next`、`.nuxt`、`.cache`、`target`、`vendor`……)之外的额外目录 |
|
|
92
|
-
| `mapTopFiles` | `24` | 排名地图中的最大文件数 |
|
|
93
|
-
| `mapMaxChars` | `3200` | 渲染地图的硬性字符上限 |
|
|
94
|
-
| `mapTtlMs` | `60000` | 自动注入地图的刷新间隔(毫秒,最小 1000) |
|
|
95
|
-
| `autoInject` | `true` | 是否注册系统提示词段 |
|
|
96
|
-
|
|
97
|
-
## 支持的语言
|
|
98
|
-
|
|
99
|
-
TypeScript、JavaScript、Python、Go、Rust、Java(`.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java`),通过 tree-sitter WASM 解析——纯解析,无需原生编译。符号提供方的接缝(`src/extract.ts` + 语法文件)预留了后续接入其他语言/嵌入检索的位置。
|
|
100
|
-
|
|
101
|
-
## 工作原理
|
|
102
|
-
|
|
103
|
-
- **索引构建**(`src/buildIndex.ts`):递归扫描(应用排除规则),逐文件 tree-sitter 提取(`src/extract.ts`),JSON 缓存置于 `<repo>/.dsh-code-index/`,按 mtime 增量刷新(只有被改动的文件才重新解析)。
|
|
104
|
-
- **搜索**(`src/search.ts`):纯打分——精确 `1` / 前缀 `0.8` / 子串 `0.5`,导出加权,名称序平局裁决。
|
|
105
|
-
- **仓库地图**(`src/repomap.ts`)
|
|
106
|
-
- **工作区解析**:每个工具解析会话 cwd(`agent.session.header.cwd`)并向上查找最近的 `.git`(有界——没有仓库标记的目录绝不会被索引)。
|
|
107
|
-
|
|
108
|
-
## 已知限制
|
|
109
|
-
|
|
110
|
-
- **web-tree-sitter 固定为 `^0.
|
|
111
|
-
- 自动注入段针对**默认工作区**(启动目录,与 headless/CLI 模式一致)。多工作区 Web UI 会话应使用 `code_map`/`code_symbols`(它们按会话 cwd 解析)。
|
|
112
|
-
- 局部变量也会被索引——召回优先于精确;`code_search` 的排名会压低它们。
|
|
113
|
-
- 开发者预览版 harness:上游 harness/插件 API 大概率有破坏性变更。
|
|
114
|
-
|
|
115
|
-
## 开发
|
|
116
|
-
|
|
117
|
-
```sh
|
|
118
|
-
pnpm install
|
|
119
|
-
pnpm test # vitest —— 提取器、扫描、缓存、搜索、仓库地图
|
|
120
|
-
pnpm typecheck
|
|
121
|
-
pnpm build # tsup → dist/index.js(ESM,外部依赖)
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
1
|
+
# dsh-code-index
|
|
2
|
+
|
|
3
|
+
[English](README.md) | 中文
|
|
4
|
+
|
|
5
|
+
语义仓库索引 —— 一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)插件,为 agent 提供**代码库地图**:基于 tree-sitter 的符号索引、带排名的符号搜索,以及注入到系统提示词里的限量自动更新仓库地图。
|
|
6
|
+
|
|
7
|
+
在一个生态姗姗来迟的细分领域占位:git/语音/浏览器/记忆类插件之外,代码智能方向的插件已陆续出现(图谱路线、向量嵌入路线),而本插件刻意保持**零外部依赖**——纯进程内 tree-sitter WASM,把 aider repo-map / Cursor `@Codebase` 的同类能力带给 dsh agent。
|
|
8
|
+
|
|
9
|
+
## 模型能得到什么
|
|
10
|
+
|
|
11
|
+
| 工具 | 用途 |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `code_index` | 查看 / (重)建当前工作区的索引 |
|
|
14
|
+
| `code_symbols` | 列出符号(函数、类、接口、类型、方法……),带 file:line——支持按名称、路径、类型、是否导出过滤 |
|
|
15
|
+
| `code_search` | 排名检索:精确 > 前缀 > 子串 > 子序列模糊,导出优先,带相关度分数与 file:line |
|
|
16
|
+
| `code_map` | 限量排名仓库地图(按符号密度 + import 图 PageRank 取核心文件 + 关键符号与行号) |
|
|
17
|
+
|
|
18
|
+
外加一个可选的**自动注入系统提示词段**(`code-index:repo-map`,序 60):默认工作区的精简排名地图,按 TTL 自动刷新(`mapTtlMs`,默认 60 秒)。将 `autoInject: false` 可关闭,只依赖 `code_map` 工具。
|
|
19
|
+
|
|
20
|
+
## 安装
|
|
21
|
+
|
|
22
|
+
需要 `dsh`(任意安装方式——npx、npm 或源码)与 Node ≥ 22。
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
# 从 npm(预编译)
|
|
26
|
+
npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
|
|
27
|
+
|
|
28
|
+
# 或从包含本仓库检查副本的目录
|
|
29
|
+
npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
重启 Web UI(`npx @deepseek-ai/dsh web`)——启动日志会确认每个工具:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
[dsh-code-index] plugin loaded
|
|
36
|
+
[dsh-code-index] registered tool: code_index
|
|
37
|
+
...
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
不启动即可核对组合配置:`dsh --profile web --dump-config`。
|
|
41
|
+
|
|
42
|
+
## 使用
|
|
43
|
+
|
|
44
|
+
在工作区会话中,向 agent 提这类请求:
|
|
45
|
+
|
|
46
|
+
- "我们现在在哪个仓库?先跑 code_map。"
|
|
47
|
+
- "找出所有名字含 `parse` 的函数及其位置。"
|
|
48
|
+
- "列出 src/core 里的导出符号。"
|
|
49
|
+
- "重建代码索引。"
|
|
50
|
+
|
|
51
|
+
*索引*本身不需要 API key;模型当然要配置好才能调用这些工具。
|
|
52
|
+
|
|
53
|
+
## 示例(输入 → 输出)
|
|
54
|
+
|
|
55
|
+
用户提示:
|
|
56
|
+
|
|
57
|
+
> 我们现在在哪个仓库?先跑 `code_map`,然后找出 `extractSymbols` 定义在哪。
|
|
58
|
+
|
|
59
|
+
agent 依次调用工具:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
code_map
|
|
63
|
+
# repo map
|
|
64
|
+
## src/extract.ts (14)
|
|
65
|
+
function extractSymbols(code, id) :121
|
|
66
|
+
function languageForFile(filePath) :37
|
|
67
|
+
...
|
|
68
|
+
|
|
69
|
+
code_search { query: "extractSymbols" }
|
|
70
|
+
export function extractSymbols(code, id) — src/extract.ts:121
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
索引在首次使用时惰性构建;后续调用由磁盘缓存提供,并按 mtime 增量刷新。
|
|
74
|
+
|
|
75
|
+
## 配置
|
|
76
|
+
|
|
77
|
+
选项通过插件行的 `config` 在 profile 补丁中传入(缺省时使用默认值):
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
# $DSH_HOME/profiles/<name>/cordis.patch.yml —— 裸行按 id 覆盖。
|
|
81
|
+
- id: code-index
|
|
82
|
+
config:
|
|
83
|
+
excludeDirs: [generated, playground]
|
|
84
|
+
mapTopFiles: 30
|
|
85
|
+
mapMaxChars: 4000
|
|
86
|
+
autoInject: true
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
| 键 | 默认 | 含义 |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `excludeDirs` | `[]` | 追加到内置排除列表(`node_modules`、`.git`、`dist`、`build`、`out`、`coverage`、`.next`、`.nuxt`、`.cache`、`target`、`vendor`……)之外的额外目录 |
|
|
92
|
+
| `mapTopFiles` | `24` | 排名地图中的最大文件数 |
|
|
93
|
+
| `mapMaxChars` | `3200` | 渲染地图的硬性字符上限 |
|
|
94
|
+
| `mapTtlMs` | `60000` | 自动注入地图的刷新间隔(毫秒,最小 1000) |
|
|
95
|
+
| `autoInject` | `true` | 是否注册系统提示词段 |
|
|
96
|
+
|
|
97
|
+
## 支持的语言
|
|
98
|
+
|
|
99
|
+
TypeScript、JavaScript、Python、Go、Rust、Java(`.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java`),通过 tree-sitter WASM 解析——纯解析,无需原生编译。符号提供方的接缝(`src/extract.ts` + 语法文件)预留了后续接入其他语言/嵌入检索的位置。
|
|
100
|
+
|
|
101
|
+
## 工作原理
|
|
102
|
+
|
|
103
|
+
- **索引构建**(`src/buildIndex.ts`):递归扫描(应用排除规则),逐文件 tree-sitter 提取(`src/extract.ts`),JSON 缓存置于 `<repo>/.dsh-code-index/`,按 mtime 增量刷新(只有被改动的文件才重新解析)。
|
|
104
|
+
- **搜索**(`src/search.ts`):纯打分——精确 `1` / 前缀 `0.8` / 子串 `0.5`,导出加权,名称序平局裁决。
|
|
105
|
+
- **仓库地图**(`src/repomap.ts`):import 图上的个性化 PageRank(传送向量 = 各文件密度份额,被其他枢纽文件引用的枢纽会比平铺入度统计排得更靠前),以密度感知的文件打分为底(class/interface/function 加权,测试路径衰减),取 Top-N 文件,每文件符号上限,硬截断。
|
|
106
|
+
- **工作区解析**:每个工具解析会话 cwd(`agent.session.header.cwd`)并向上查找最近的 `.git`(有界——没有仓库标记的目录绝不会被索引)。
|
|
107
|
+
|
|
108
|
+
## 已知限制
|
|
109
|
+
|
|
110
|
+
- **web-tree-sitter 固定为 `^0.25`(ESM)** —— 0.25 采用 ESM 具名导出(`Language`/`Query`);与 `tree-sitter-wasms` 静态构建的组合在 Node ≥ 22/24 下验证可用。
|
|
111
|
+
- 自动注入段针对**默认工作区**(启动目录,与 headless/CLI 模式一致)。多工作区 Web UI 会话应使用 `code_map`/`code_symbols`(它们按会话 cwd 解析)。
|
|
112
|
+
- 局部变量也会被索引——召回优先于精确;`code_search` 的排名会压低它们。
|
|
113
|
+
- 开发者预览版 harness:上游 harness/插件 API 大概率有破坏性变更。
|
|
114
|
+
|
|
115
|
+
## 开发
|
|
116
|
+
|
|
117
|
+
```sh
|
|
118
|
+
pnpm install
|
|
119
|
+
pnpm test # vitest —— 提取器、扫描、缓存、搜索、仓库地图
|
|
120
|
+
pnpm typecheck
|
|
121
|
+
pnpm build # tsup → dist/index.js(ESM,外部依赖)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**WSL → Windows 检出**:从 WSL 对 `/mnt/c` 下的检出跑 `pnpm install`,会留下 Windows 侧 Node 无法穿透的 Linux 风格符号链接(`Cannot find package 'web-tree-sitter'`、`EACCES`)。无需重装,在 Windows 侧跑一次修复:
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
node.exe scripts\fix-wsl-links.mjs # 本仓库的 node_modules
|
|
128
|
+
node.exe scripts\fix-wsl-links.mjs C:\Users\you\.dsh\profiles\web # dsh profile 里的插件安装
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
它会把每个失效链接以 junction 形式重新指向 `.pnpm` store 里的真实位置;可重复执行(幂等,干净时报 `fixed: 0`)。
|
|
132
|
+
|
|
133
|
+
## 反馈
|
|
134
|
+
|
|
135
|
+
发现 bug,或者地图排名不合理?请[提 issue](https://github.com/lemonxiny55/dsh-code-index/issues)——真实使用报告(排名失准的仓库、想支持的语言)直接决定路线图。
|
|
136
|
+
|
|
137
|
+
## 许可证
|
|
138
|
+
|
|
126
139
|
MIT。与 DeepSeek 无关;基于公开的 `dsh` 插件接口构建。
|
package/cordis.patch.yml
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
# dsh-code-index bundle: inserts the plugin row into the composition.
|
|
2
|
-
# Later layers (profile cordis.patch.yml, --patch) may override this row by id.
|
|
3
|
-
- insert:
|
|
4
|
-
- id: code-index
|
|
1
|
+
# dsh-code-index bundle: inserts the plugin row into the composition.
|
|
2
|
+
# Later layers (profile cordis.patch.yml, --patch) may override this row by id.
|
|
3
|
+
- insert:
|
|
4
|
+
- id: code-index
|
|
5
5
|
name: dsh-code-index
|