@easbot/codebase 0.3.37 → 0.3.39
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/README.en.md +139 -40
- package/README.md +69 -1
- package/dist/assets/txt/src/plugin/tool/codebase.txt +214 -0
- package/dist/chunks/{chunk-OUJNWRIY.mjs → chunk-KUX25CUR.mjs} +2 -2
- package/dist/chunks/{chunk-FZNMPXUO.mjs → chunk-OXF2UU4K.mjs} +10 -10
- package/dist/chunks/{chunk-6NYX22KV.cjs → chunk-P3IAXGOT.cjs} +6 -6
- package/dist/chunks/{chunk-VXLUR7M5.cjs → chunk-XGZDPIEP.cjs} +11 -11
- package/dist/chunks/{cli-handler-7HKSS3UW.mjs → cli-handler-FGFM3HBJ.mjs} +1 -1
- package/dist/chunks/cli-handler-WCP6T427.cjs +1 -0
- package/dist/chunks/{stdio-server-37QG6AO2.cjs → stdio-server-BLGU4RQ5.cjs} +2 -2
- package/dist/chunks/{stdio-server-QAEXVFSI.mjs → stdio-server-OD7CDSWQ.mjs} +1 -1
- package/dist/cli.cjs +1 -1
- package/dist/cli.mjs +1 -1
- package/dist/index.cjs +7 -1
- package/dist/index.d.cts +162 -1
- package/dist/index.d.ts +162 -1
- package/dist/index.mjs +7 -1
- package/package.json +12 -9
- package/dist/chunks/cli-handler-OU2TC2SB.cjs +0 -1
package/README.en.md
CHANGED
|
@@ -6,7 +6,7 @@ Code Knowledge Graph SDK - A code indexing and querying system based on the Prop
|
|
|
6
6
|
|
|
7
7
|
## Version
|
|
8
8
|
|
|
9
|
-
v0.3.
|
|
9
|
+
v0.3.39
|
|
10
10
|
## Features
|
|
11
11
|
|
|
12
12
|
- **Property Graph Model**: Store code entities and their relationships using nodes and edges
|
|
@@ -14,46 +14,36 @@ v0.3.37
|
|
|
14
14
|
- **Hybrid Search**: FTS full-text search + structured queries
|
|
15
15
|
- **Incremental Updates**: Smart incremental indexing based on file content hashes
|
|
16
16
|
- **Tree-sitter Parsing**: High-performance AST parsing
|
|
17
|
+
- **Unified DB abstraction**: Accessed via `@easbot/database`'s `SyncSqliteConnection`, defaulting to the `better-sqlite3` backend; switchable to `node:sqlite` / `@tursodatabase/database`
|
|
17
18
|
|
|
18
|
-
##
|
|
19
|
+
## Database Backend
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
pnpm add @easbot/codebase
|
|
22
|
-
```
|
|
21
|
+
`packages/codebase` accesses SQLite through `@easbot/database` and no longer depends on the raw `better-sqlite3` binding. `DatabaseManager` holds a `SyncSqliteConnection` (a synchronous facade equivalent to codegraph's `SqliteDatabase`); all 60+ synchronous DB call sites remain **unchanged**.
|
|
23
22
|
|
|
24
|
-
|
|
23
|
+
### Default backend: `better-sqlite3`
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
import { createCodebase } from '@easbot/codebase';
|
|
25
|
+
`DatabaseManager` explicitly passes `backend: 'better-sqlite3'` at construction and does **not** use the `'auto'` fallback. Rationale:
|
|
28
26
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
});
|
|
27
|
+
- Codebase performance baselines (index / search / sync metrics) are measured against the `better-sqlite3` synchronous binding.
|
|
28
|
+
- Auto-detection may fall back to unexpected backends in containers / Linux / Windows, making runtime behavior unpredictable.
|
|
29
|
+
- `better-sqlite3@^12.9.0` remains a physical dependency of `packages/codebase` (**not** moved to `optionalDependencies`), guaranteeing the matching native binding is fetched at install time.
|
|
33
30
|
|
|
34
|
-
|
|
35
|
-
const result = await graph.indexDirectory();
|
|
36
|
-
console.log(`Indexed: ${result.filesProcessed} files, ${result.nodesCreated} nodes`);
|
|
31
|
+
### Switching backends
|
|
37
32
|
|
|
38
|
-
|
|
39
|
-
const results = await graph.search('UserService');
|
|
40
|
-
for (const r of results) {
|
|
41
|
-
console.log(`${r.name} (${r.astType}) - ${r.filePath}:${r.startLine}`);
|
|
42
|
-
}
|
|
33
|
+
Applications can switch via `createSyncSqliteConnection({ backend: 'node-sqlite' | '@tursodatabase/database', ... })`. Codebase's `DatabaseManager` currently hardcodes `'better-sqlite3'`; to switch, modify its constructor in `packages/codebase/src/database/database-manager.ts` (around L98).
|
|
43
34
|
|
|
44
|
-
|
|
45
|
-
const classes = await graph.queryNodes({ astType: 'class_declaration' });
|
|
35
|
+
For the full backend abstraction and performance comparison see:
|
|
46
36
|
|
|
47
|
-
|
|
48
|
-
|
|
37
|
+
- [`@easbot/database` README](file:///e:/work/apps/eas/easbot/packages/database/README.md)
|
|
38
|
+
- Decision [`0036-storage-backend.md`](file:///e:/work/apps/eas/easbot/docs/decisions/0036-storage-backend.md)
|
|
49
39
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
40
|
+
### `:memory:` literal support
|
|
41
|
+
|
|
42
|
+
`SyncSqliteConnection.initialize` accepts the `:memory:` literal (the SQLite ecosystem default) as an in-memory database signal; codebase's `DatabaseManager` skips `Filesystem.normalize` so the literal passes through.
|
|
53
43
|
|
|
54
44
|
## CLI / MCP / Installer
|
|
55
45
|
|
|
56
|
-
`packages/codebase`
|
|
46
|
+
`packages/codebase` **does not currently expose a standalone CLI**; callers integrate through the `createCodebase()` API, or invoke it as a subcommand `easbot codebase ...` via the main `easbot` CLI (after the [H-M1 phase lands](file:///e:/work/apps/eas/easbot/.easbot/knowledge/tasks/codebase-refactor-plan/findings.md)).
|
|
57
47
|
|
|
58
48
|
### `--json` Protocol (decision 0051 / spec v1.3)
|
|
59
49
|
|
|
@@ -61,7 +51,7 @@ All CLI commands support `--json` for machine-readable output. Unified through [
|
|
|
61
51
|
|
|
62
52
|
```bash
|
|
63
53
|
# Success response schema
|
|
64
|
-
easbot
|
|
54
|
+
easbot codebase status --json
|
|
65
55
|
# {
|
|
66
56
|
# "ok": true,
|
|
67
57
|
# "data": { "rootDir": "...", "configExists": true, "dbExists": true, ... },
|
|
@@ -69,22 +59,30 @@ easbot-codebase status --json
|
|
|
69
59
|
# }
|
|
70
60
|
|
|
71
61
|
# init path (added in decision 0051)
|
|
72
|
-
easbot
|
|
62
|
+
easbot codebase init --json
|
|
73
63
|
# {
|
|
74
64
|
# "ok": true,
|
|
75
65
|
# "data": {
|
|
76
66
|
# "configPath": "<worktree>/.easbot/codebase.json",
|
|
67
|
+
# "dbPath": "<worktree>/.easbot/db/codebase.db",
|
|
77
68
|
# "backend": "better-sqlite3",
|
|
78
69
|
# "schemaVersion": 1,
|
|
79
70
|
# "created": true,
|
|
80
71
|
# "skipped": false,
|
|
81
|
-
# "
|
|
72
|
+
# "metaInitialized": true
|
|
82
73
|
# },
|
|
83
74
|
# "meta": { "action": "created" }
|
|
84
75
|
# }
|
|
76
|
+
#
|
|
77
|
+
# Decision 0076: init now establishes a three-artifact contract (aligned with memory/note):
|
|
78
|
+
# 1. <worktree>/.easbot/codebase.json — JSON config
|
|
79
|
+
# 2. <worktree>/.easbot/db/codebase.db — SQLite db (schema + meta table with 5 KVs)
|
|
80
|
+
# 3. db meta table: version / createdAt / index_state=uninitialized / indexed_with_version=unknown / schema_version
|
|
81
|
+
# A second init without --force is idempotent (skipped); with --force the old db is deleted and the three artifacts rebuilt.
|
|
82
|
+
# No sync is triggered automatically; the user runs `easbot codebase sync` explicitly for the first sync.
|
|
85
83
|
|
|
86
84
|
# Error response schema
|
|
87
|
-
easbot
|
|
85
|
+
easbot codebase path <missing> --json
|
|
88
86
|
# {
|
|
89
87
|
# "ok": false,
|
|
90
88
|
# "error": { "code": "E_NOT_FOUND", "message": "..." }
|
|
@@ -193,6 +191,42 @@ $ easbot codebase status --json
|
|
|
193
191
|
|
|
194
192
|
Compatible with [CLI Output Spec v1.4](file:///e:/work/apps/eas/easbot/docs/spec/cli-output-spec.md) / [Decision 0040](file:///e:/work/apps/eas/easbot/docs/decisions/0040-cli-output-unified-json.md).
|
|
195
193
|
|
|
194
|
+
## Installation
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
pnpm add @easbot/codebase
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Quick Start
|
|
201
|
+
|
|
202
|
+
```typescript
|
|
203
|
+
import { createCodebase } from '@easbot/codebase';
|
|
204
|
+
|
|
205
|
+
// Create graph instance
|
|
206
|
+
const graph = await createCodebase({
|
|
207
|
+
workspaceDir: '/path/to/your/project',
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
// Index project
|
|
211
|
+
const result = await graph.indexDirectory();
|
|
212
|
+
console.log(`Indexed: ${result.filesProcessed} files, ${result.nodesCreated} nodes`);
|
|
213
|
+
|
|
214
|
+
// Search code
|
|
215
|
+
const results = await graph.search('UserService');
|
|
216
|
+
for (const r of results) {
|
|
217
|
+
console.log(`${r.name} (${r.astType}) - ${r.filePath}:${r.startLine}`);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// Query nodes
|
|
221
|
+
const classes = await graph.queryNodes({ astType: 'class_declaration' });
|
|
222
|
+
|
|
223
|
+
// Query call graph
|
|
224
|
+
const callGraph = await graph.queryCallGraph('ts:src/service.ts:function_declaration:UserService');
|
|
225
|
+
|
|
226
|
+
// Close graph
|
|
227
|
+
await graph.close();
|
|
228
|
+
```
|
|
229
|
+
|
|
196
230
|
## API Documentation
|
|
197
231
|
|
|
198
232
|
### CodeKnowledgeGraph
|
|
@@ -328,14 +362,14 @@ await service.callers(ctx, { name: 'AuthService' });
|
|
|
328
362
|
|
|
329
363
|
### Relation Types
|
|
330
364
|
|
|
331
|
-
| Relation | Description
|
|
332
|
-
| ------------- |
|
|
333
|
-
| CONTAINS |
|
|
334
|
-
| CALLS | Function call relationship
|
|
335
|
-
| INHERITS_FROM | Class inheritance
|
|
336
|
-
| IMPLEMENTS | Interface implementation
|
|
337
|
-
| IMPORTS | Module import
|
|
338
|
-
| REFERENCES |
|
|
365
|
+
| Relation | Description |
|
|
366
|
+
| ------------- | -------------------------------------- |
|
|
367
|
+
| CONTAINS | Containment (a class contains methods) |
|
|
368
|
+
| CALLS | Function call relationship |
|
|
369
|
+
| INHERITS_FROM | Class inheritance |
|
|
370
|
+
| IMPLEMENTS | Interface implementation |
|
|
371
|
+
| IMPORTS | Module import |
|
|
372
|
+
| REFERENCES | Reference relationship |
|
|
339
373
|
|
|
340
374
|
## Evaluation (Generic Evaluation Model)
|
|
341
375
|
|
|
@@ -412,6 +446,71 @@ src/
|
|
|
412
446
|
└── query-interface.ts # Query interface
|
|
413
447
|
```
|
|
414
448
|
|
|
449
|
+
## Plugin (plugin / tool)
|
|
450
|
+
|
|
451
|
+
`@easbot/codebase` provides an installable plugin under the `@easbot/plugin` contract: one `codebase` tool (**no hooks** — codebase has no context-collection semantics; only note / memory sources register `context.collect`). The implementation lives in `src/plugin/`, and all symbols are imported **from the package root only** (no subpath exports).
|
|
452
|
+
|
|
453
|
+
> **Distribution form (2026-11-18, decision by Hou Jian)**: the codebase plugin does **not** go into the host's `INTERNAL_PLUGINS`;
|
|
454
|
+
> it is installed via marketplace, with tools fully effective and distributed on demand.
|
|
455
|
+
> The tool exposes 8 read-only ops (search / node / context / impact / callers / callees / explore / status);
|
|
456
|
+
> `doctor` is available only via CLI / MCP and is not in the tool schema (same convention as the host built-in tool).
|
|
457
|
+
|
|
458
|
+
```typescript
|
|
459
|
+
import {
|
|
460
|
+
CodebasePlugin,
|
|
461
|
+
CODEBASE_PLUGIN_MANIFEST,
|
|
462
|
+
CODEBASE_PLUGIN_ID,
|
|
463
|
+
CodebaseTool,
|
|
464
|
+
CODEBASE_TOOL_ARGS,
|
|
465
|
+
CODEBASE_TOOL_OPS,
|
|
466
|
+
} from '@easbot/codebase';
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
| Export | Description |
|
|
470
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
471
|
+
| `CodebasePlugin` / `Plugin` / `default` | Plugin factory (three export names share one reference; host loader recognizes the entry by whitelist) |
|
|
472
|
+
| `CODEBASE_PLUGIN_MANIFEST` | Manifest (source of truth for generating the distribution `plugin.json`) |
|
|
473
|
+
| `CodebaseTool` / `CODEBASE_TOOL_ARGS` | Tool definition and parameter schema (discriminated union, isomorphic with the host built-in tool) |
|
|
474
|
+
| `CODEBASE_TOOL_OPS` | Ops exposed by the tool (8 ops) |
|
|
475
|
+
|
|
476
|
+
### Generating distribution artifacts
|
|
477
|
+
|
|
478
|
+
```bash
|
|
479
|
+
# Generate plugin distribution artifacts (plugins/codebase + marketplace manifest)
|
|
480
|
+
pnpm --filter @easbot/codebase plugin:generate
|
|
481
|
+
|
|
482
|
+
# Only verify artifacts are up to date (for CI; exits 1 if stale)
|
|
483
|
+
pnpm --filter @easbot/codebase plugin:check
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
The script `scripts/generate-plugin-distribution.ts` uses these inputs and produces:
|
|
487
|
+
|
|
488
|
+
| Input | Artifact |
|
|
489
|
+
| ------------------------------------------------------ | -------------------------------------------------------------- |
|
|
490
|
+
| `version` in `package.json` | Version in `plugin.json` / `package.json` |
|
|
491
|
+
| `CODEBASE_PLUGIN_MANIFEST` in `src/plugin/manifest.ts` | `plugin.json` name / description / entry / capabilities |
|
|
492
|
+
| Whitelist exports in `src/plugin/index.ts` | Re-export identifiers in `index.mjs` |
|
|
493
|
+
| `tool/` directory under `src/plugin/` | Capability validation (errors out if a declaration is missing) |
|
|
494
|
+
|
|
495
|
+
The source of truth for the version is `package.json`; if `CODEBASE_PLUGIN_VERSION` in `src/plugin/manifest.ts` diverges, the script syncs it automatically (`--check` mode only reports without writing).
|
|
496
|
+
The script is idempotent: it does not write when artifact content already matches disk.
|
|
497
|
+
|
|
498
|
+
### Installation and runtime loading
|
|
499
|
+
|
|
500
|
+
The distribution directory is the repository-wide unified area `plugins/codebase/` (`{plugin.json,package.json,index.mjs}`),
|
|
501
|
+
and the marketplace manifest is the single in-repo copy at `plugins/.easbot-plugin/marketplace.json`.
|
|
502
|
+
`index.mjs` only re-exports the package root, so `@easbot/codebase` MUST be built before use.
|
|
503
|
+
|
|
504
|
+
```bash
|
|
505
|
+
pnpm --filter @easbot/codebase build
|
|
506
|
+
|
|
507
|
+
# Register the local marketplace (path to the repository-wide distribution area)
|
|
508
|
+
easbot plugins marketplace add ./plugins
|
|
509
|
+
|
|
510
|
+
# Install the codebase plugin
|
|
511
|
+
easbot plugins install codebase
|
|
512
|
+
```
|
|
513
|
+
|
|
415
514
|
## Development
|
|
416
515
|
|
|
417
516
|
```bash
|
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
## 版本
|
|
8
8
|
|
|
9
|
-
v0.3.
|
|
9
|
+
v0.3.39
|
|
10
10
|
## 特性
|
|
11
11
|
|
|
12
12
|
- **Property Graph 模型**: 使用节点和边存储代码实体及其关系
|
|
@@ -446,6 +446,74 @@ src/
|
|
|
446
446
|
└── query-interface.ts # 查询接口
|
|
447
447
|
```
|
|
448
448
|
|
|
449
|
+
## 插件(plugin / tool)
|
|
450
|
+
|
|
451
|
+
`@easbot/codebase` 按 `@easbot/plugin` 契约提供可安装插件:1 个 `codebase` 工具(**无 hooks** ——
|
|
452
|
+
codebase 没有上下文收集语义,笔记 / 记忆类来源才注册 `context.collect`)。
|
|
453
|
+
实现位于 `src/plugin/`,所有符号**统一从包根入口导入**(不提供 subpath 导出)。
|
|
454
|
+
|
|
455
|
+
> **分发形态(2026-11-18 侯剑决策)**:codebase 插件**不进宿主 `INTERNAL_PLUGINS`**,
|
|
456
|
+
> 走 marketplace 安装,tool 全量生效、按需分发。
|
|
457
|
+
> 工具提供 8 个只读 op(search / node / context / impact / callers / callees / explore / status);
|
|
458
|
+
> `doctor` 仅 CLI / MCP 提供,不在 tool schema(与宿主内置工具同口径)。
|
|
459
|
+
|
|
460
|
+
```typescript
|
|
461
|
+
import {
|
|
462
|
+
CodebasePlugin,
|
|
463
|
+
CODEBASE_PLUGIN_MANIFEST,
|
|
464
|
+
CODEBASE_PLUGIN_ID,
|
|
465
|
+
CodebaseTool,
|
|
466
|
+
CODEBASE_TOOL_ARGS,
|
|
467
|
+
CODEBASE_TOOL_OPS,
|
|
468
|
+
} from '@easbot/codebase';
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
| 导出 | 说明 |
|
|
472
|
+
| --------------------------------------- | -------------------------------------------------------- |
|
|
473
|
+
| `CodebasePlugin` / `Plugin` / `default` | 插件工厂(三个导出名同引用,宿主加载器按白名单识别入口) |
|
|
474
|
+
| `CODEBASE_PLUGIN_MANIFEST` | 清单(分发目录 `plugin.json` 的生成真值源) |
|
|
475
|
+
| `CodebaseTool` / `CODEBASE_TOOL_ARGS` | 工具定义与参数 schema(判别联合,与宿主内置工具同构) |
|
|
476
|
+
| `CODEBASE_TOOL_OPS` | 工具暴露的 op 清单(8 op) |
|
|
477
|
+
|
|
478
|
+
#### 生成分发产物
|
|
479
|
+
|
|
480
|
+
```bash
|
|
481
|
+
# 生成插件分发产物(plugins/codebase + marketplace 清单)
|
|
482
|
+
pnpm --filter @easbot/codebase plugin:generate
|
|
483
|
+
|
|
484
|
+
# 只校验产物是否最新(CI 用,过期则 exit 1)
|
|
485
|
+
pnpm --filter @easbot/codebase plugin:check
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
脚本 `scripts/generate-plugin-distribution.ts` 的数据来源与产物:
|
|
489
|
+
|
|
490
|
+
| 输入 | 产物 |
|
|
491
|
+
| ------------------------------------------------------ | ---------------------------------------------------------- |
|
|
492
|
+
| `package.json` 的 `version` | `plugin.json` / `package.json` 的版本 |
|
|
493
|
+
| `src/plugin/manifest.ts` 的 `CODEBASE_PLUGIN_MANIFEST` | `plugin.json` 的 name / description / entry / capabilities |
|
|
494
|
+
| `src/plugin/index.ts` 的白名单导出 | `index.mjs` 的 re-export 标识符 |
|
|
495
|
+
| `src/plugin/` 下的 `tool/` 目录 | capabilities 能力校验(缺声明即报错退出) |
|
|
496
|
+
|
|
497
|
+
版本真值源是 `package.json`;`src/plugin/manifest.ts` 的 `CODEBASE_PLUGIN_VERSION`
|
|
498
|
+
与之不一致时脚本会自动同步(`--check` 模式只报错不改文件)。
|
|
499
|
+
脚本幂等:产物内容与磁盘一致时不写盘。
|
|
500
|
+
|
|
501
|
+
#### 安装与运行时加载
|
|
502
|
+
|
|
503
|
+
分发目录位于仓根统一分发区 `plugins/codebase/`(`{plugin.json,package.json,index.mjs}`),
|
|
504
|
+
marketplace 清单为仓内唯一一份 `plugins/.easbot-plugin/marketplace.json`。
|
|
505
|
+
`index.mjs` 只做包根 re-export,因此使用前 MUST 先构建 `@easbot/codebase`。
|
|
506
|
+
|
|
507
|
+
```bash
|
|
508
|
+
pnpm --filter @easbot/codebase build
|
|
509
|
+
|
|
510
|
+
# 注册本地 marketplace(路径为仓根统一分发区)
|
|
511
|
+
easbot plugins marketplace add ./plugins
|
|
512
|
+
|
|
513
|
+
# 安装 codebase 插件
|
|
514
|
+
easbot plugins install codebase
|
|
515
|
+
```
|
|
516
|
+
|
|
449
517
|
## 开发
|
|
450
518
|
|
|
451
519
|
```bash
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
Access and analyze the codebase knowledge graph (CodeBase). Provides **8 operations** for searching symbols, exploring regions, traversing relations, and checking graph status.
|
|
2
|
+
|
|
3
|
+
## Markdown rendering
|
|
4
|
+
|
|
5
|
+
Code is rendered in full (source body + caller/callee trail) since code interpretation requires
|
|
6
|
+
the actual lines. Two-stage trim (2026-09-21 老侯反馈) keeps output bounded:
|
|
7
|
+
|
|
8
|
+
1. **service-layer SQL LIMIT** — `callers` / `callees` / `impact` / `context` / `search` /
|
|
9
|
+
`explore` enforce `maxEdgesPerNode` on the SQL query (default 10 / max 100).
|
|
10
|
+
2. **tool-layer edges trim** (`trimEdgesForLLM`) — namespace guard + relation priority
|
|
11
|
+
ordering + unresolved filtering + default `maxEdgesPerList=15` for the markdown rendered
|
|
12
|
+
to the LLM. Full untrimmed data is persisted to `Truncate.DIR/knowledge_codebase_<id>.json`
|
|
13
|
+
and can be re-fetched with Grep / Read if needed.
|
|
14
|
+
|
|
15
|
+
## Recommended workflow (决策 0087)
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
search → (pick nodeId/name) → callers | callees | impact | context | node
|
|
19
|
+
↑ ↓
|
|
20
|
+
└─────────────── explore (PRIMARY, source code + 1-level) ←──────┘
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**Step 1**: `search(query="ClassName")` — find candidate nodeIds/names.
|
|
24
|
+
**Step 2**: If you know the symbol precisely (e.g., `AuthService.login@20`), go straight to `callers` / `callees` / `impact` / `context` / `node`.
|
|
25
|
+
**Step 3**: For "show me how this code works end-to-end", call `explore(query="ClassName")` which returns source + caller/callee 1-level trail in one call.
|
|
26
|
+
|
|
27
|
+
## Edges / limits parameter naming
|
|
28
|
+
|
|
29
|
+
All edge-count limits use a single field name `maxEdgesPerNode` (default 10, range [1, 100]).
|
|
30
|
+
All node-result limits use a single field name `maxResults` (default 10, range [1, 100]).
|
|
31
|
+
|
|
32
|
+
| parameter | ops | scope |
|
|
33
|
+
|------------|-----|-------|
|
|
34
|
+
| `maxEdgesPerNode` | `callers`, `callees`, `impact`, `context`, `node`, `search`, `explore` | SQL-fetched edges for one direction / one depth / one node / per-hit / per-symbol |
|
|
35
|
+
| `maxResults` | `search`, `callers`, `callees`, `impact` | max node entries returned (independent of `maxEdgesPerNode`) |
|
|
36
|
+
| `maxNodes` | `context` | max nodes returned (independent of `maxEdgesPerNode`) |
|
|
37
|
+
| `maxFiles` / `maxSymbols` | `explore` | entry-point count / symbols-per-entry-point |
|
|
38
|
+
|
|
39
|
+
## When to use which operation (决策 0087 分层)
|
|
40
|
+
|
|
41
|
+
| Operation | Tier | Purpose | When to use |
|
|
42
|
+
|-----------|------|---------|-------------|
|
|
43
|
+
| `explore` | **PRIMARY** | Get code + caller/callee trail in one call | **Call FIRST** for any question or before an edit |
|
|
44
|
+
| `search` | **PRIMARY** | Fast symbol lookup (no code) | "Find class X" / "list methods named Y" |
|
|
45
|
+
| `callers` | **PRIMARY** | Flat list of who calls `<symbol>` | Quick "who depends on this?" |
|
|
46
|
+
| `callees` | **PRIMARY** | Flat list of what `<symbol>` calls | Quick "what does this function do?" |
|
|
47
|
+
| `impact` | **PRIMARY** | Incoming BFS, bucketed by depth | Pre-refactor blast-radius analysis |
|
|
48
|
+
| `context` | ADVANCED | BFS sub-graph (incoming + outgoing) | Use when callers+callees+impact together isn't enough |
|
|
49
|
+
| `node` | ADVANCED | Single node details by name/ID | Inspect one specific symbol's edges / source |
|
|
50
|
+
| `status` | ADVANCED | Graph state (db path / node count / edge count / index state / meta) | Quick snapshot to confirm the index is healthy before query |
|
|
51
|
+
|
|
52
|
+
## Operations
|
|
53
|
+
|
|
54
|
+
### search [PRIMARY]
|
|
55
|
+
- `query` (string, required): Symbol name or partial name (e.g., "auth", "UserService").
|
|
56
|
+
- `maxResults` (number, default 10, range [1, 100]): Max search hits.
|
|
57
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max edges kept per hit. Module-level nodes can carry 500+ edges; raise when you need richer neighborhood context for each hit.
|
|
58
|
+
- `kind` (string, optional): Filter by node kind. One of: class, function, method, interface, type, variable, route, component, const.
|
|
59
|
+
- `astType` (string, optional): Filter by AST type.
|
|
60
|
+
- `language` (string, optional): Filter by language.
|
|
61
|
+
- `file` (string, optional): Substring match on file path.
|
|
62
|
+
- `intent` (string, optional): LLM context for ranking.
|
|
63
|
+
- `includeContent` (boolean, default false): Include source code snippets.
|
|
64
|
+
|
|
65
|
+
For full code with relations, use `explore` instead.
|
|
66
|
+
|
|
67
|
+
### explore [PRIMARY]
|
|
68
|
+
- `query` (string, required): Symbol name or natural language (e.g., "MemorySystem", "auth flow").
|
|
69
|
+
- `file` (string, optional): Disambiguate when same name in multiple files.
|
|
70
|
+
- `kind` (string, optional): Filter by node kind.
|
|
71
|
+
- `maxFiles` (number, default 5): Entry point count.
|
|
72
|
+
- `maxSymbols` (number, default 3): Symbols per entry point.
|
|
73
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max caller/callee edges per symbol.
|
|
74
|
+
- `depth` (number, 1-2, default 1): Neighbor depth for callers/callees trail.
|
|
75
|
+
- `includeContent` (boolean, default true): Include source code body.
|
|
76
|
+
- `intent` (string, optional): LLM context for ranking.
|
|
77
|
+
|
|
78
|
+
**Workflow**: First try `search` to disambiguate, then `explore` to see source code + callers/callees trail. Use this when you need to understand a region of code, not just one symbol.
|
|
79
|
+
|
|
80
|
+
### callers [PRIMARY]
|
|
81
|
+
- `name` (string, required): Name to find callers for.
|
|
82
|
+
- `nodeId` (string, optional): Direct lookup (zero ambiguity).
|
|
83
|
+
- `file` (string, optional): **Strongly recommended** — disambiguates short names like `validate` / `login` across multiple classes.
|
|
84
|
+
- `kind` (string, optional): Filter by node kind.
|
|
85
|
+
- `relationTypes` (string[], optional): Filter edges by relation type (exact SQL IN match), e.g. `["CALLS","IMPORTS"]`. Valid values: `CALLS` / `IMPORTS` / `TYPE_REFERENCES` / `ANNOTATES` / `EXTENDS` / `IMPLEMENTS` / `HAS_METHOD` / `HAS_PROPERTY` / `METHOD_OVERRIDES` / `CONTAINS`.
|
|
86
|
+
- `maxResults` (number, default 10): Max callers returned (range [1, 100]).
|
|
87
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max incoming edges fetched.
|
|
88
|
+
|
|
89
|
+
**Workflow**: If you only know the class name, call `search` first to get `name + file`. Then `callers({name, file})`.
|
|
90
|
+
**Anti-pattern**: Don't pass short class names like `name="Indexer"` without `file` — it returns 10+ candidates and you waste a tool roundtrip.
|
|
91
|
+
|
|
92
|
+
### callees [PRIMARY]
|
|
93
|
+
- `name` (string, required): Name to find callees for.
|
|
94
|
+
- `nodeId` (string, optional): Direct lookup.
|
|
95
|
+
- `file` (string, optional): **Strongly recommended** for disambiguation.
|
|
96
|
+
- `kind` (string, optional): Filter by node kind.
|
|
97
|
+
- `relationTypes` (string[], optional): Filter edges by relation type (exact SQL IN match), e.g. `["CALLS","IMPORTS"]`. Valid values: `CALLS` / `IMPORTS` / `TYPE_REFERENCES` / `ANNOTATES` / `EXTENDS` / `IMPLEMENTS` / `HAS_METHOD` / `HAS_PROPERTY` / `METHOD_OVERRIDES` / `CONTAINS`.
|
|
98
|
+
- `maxResults` (number, default 10): Max callees returned (range [1, 100]).
|
|
99
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max outgoing edges fetched.
|
|
100
|
+
|
|
101
|
+
**Workflow**: Same as `callers`. Use `search` first if uncertain about the symbol.
|
|
102
|
+
|
|
103
|
+
### impact [PRIMARY]
|
|
104
|
+
- `name` (string, required): Symbol to analyze.
|
|
105
|
+
- `nodeId` (string, optional): Direct lookup.
|
|
106
|
+
- `file` (string, optional): **Strongly recommended** for disambiguation.
|
|
107
|
+
- `kind` (string, optional): Filter by node kind.
|
|
108
|
+
- `depth` (number, 1-3, default 2): BFS depth (service-side clamp; typically 1-3).
|
|
109
|
+
- `relationTypes` (string[], optional): Filter edges by relation type (exact SQL IN match), e.g. `["CALLS","IMPORTS"]`. Valid values: `CALLS` / `IMPORTS` / `TYPE_REFERENCES` / `ANNOTATES` / `EXTENDS` / `IMPLEMENTS` / `HAS_METHOD` / `HAS_PROPERTY` / `METHOD_OVERRIDES` / `CONTAINS`.
|
|
110
|
+
- `maxResults` (number, default 10, range [1, 200]): Max affected symbols.
|
|
111
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max incoming edges per BFS level. Independent of `maxResults` — raise when the wildcard-target union query is dropping important callers.
|
|
112
|
+
|
|
113
|
+
**Workflow**: Use before refactoring a widely-used symbol. Pre-fix pass to know blast radius.
|
|
114
|
+
|
|
115
|
+
### context [ADVANCED]
|
|
116
|
+
- `name` (string, required): Symbol name.
|
|
117
|
+
- `nodeId` (string, optional): Direct lookup.
|
|
118
|
+
- `file` (string, optional): **Strongly recommended** for disambiguation.
|
|
119
|
+
- `kind` (string, optional): Filter by node kind in BFS result.
|
|
120
|
+
- `depth` (number, default 2): BFS depth (service-side clamp; typically 1-3).
|
|
121
|
+
- `relationTypes` (string[], optional): Filter edges by relation type (exact SQL IN match), e.g. `["CALLS","IMPORTS"]`. Valid values: `CALLS` / `IMPORTS` / `TYPE_REFERENCES` / `ANNOTATES` / `EXTENDS` / `IMPLEMENTS` / `HAS_METHOD` / `HAS_PROPERTY` / `METHOD_OVERRIDES` / `CONTAINS`.
|
|
122
|
+
- `maxNodes` (number, default 100): Max nodes.
|
|
123
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max edges per direction per BFS level.
|
|
124
|
+
- `direction` (incoming|outgoing|both, default both).
|
|
125
|
+
|
|
126
|
+
**Workflow**: Use this when you need **both** callers and callees at once, with depth > 1. For depth=1, `callers` + `callees` is more focused. For depth > 1 or both directions at once, prefer `context`.
|
|
127
|
+
|
|
128
|
+
### node [ADVANCED]
|
|
129
|
+
- `name` (string, optional): Symbol name (recommended).
|
|
130
|
+
- `nodeId` (string, optional): Direct lookup.
|
|
131
|
+
- `file` (string, optional): **Strongly recommended** for disambiguation.
|
|
132
|
+
- `kind` (string, optional): Filter by node kind.
|
|
133
|
+
- `includeContent` (boolean, default false): Include source code body.
|
|
134
|
+
- `includeEdges` (boolean, default false): Include edge listing.
|
|
135
|
+
- `maxEdgesPerNode` (number, default 10, range [1, 100]): Max edges (incoming + outgoing) when `includeEdges=true`.
|
|
136
|
+
|
|
137
|
+
**Workflow**: Use after `search` to get full details of one specific node, including edges and source. For most use cases `explore` already gives you source code; use `node` only when you need the full edge list (e.g., dependency analysis).
|
|
138
|
+
|
|
139
|
+
### status [ADVANCED]
|
|
140
|
+
- No parameters. Returns `GraphStatus` (db path, node count, edge count, index state, meta).
|
|
141
|
+
|
|
142
|
+
**Workflow**: Call this only when something feels wrong (search returns empty, callers/callees fail). Healthy graph → skip status.
|
|
143
|
+
|
|
144
|
+
## Name lookup behavior (决策 0087)
|
|
145
|
+
|
|
146
|
+
The `name` field uses a 4-tier SQL match (priority order):
|
|
147
|
+
1. **exact**: `name === query` (e.g., `name="Indexer"` matches class `Indexer`)
|
|
148
|
+
2. **idTail**: `nodeId` ends with `:query` (e.g., `name="Indexer.indexFile@175"` matches method node)
|
|
149
|
+
3. **qualified**: `name LIKE %query%` (e.g., `name="extractEdges"` matches `EdgeExtractor.extractEdges@80`)
|
|
150
|
+
4. **substring** (only when tiers 1-3 return nothing): name LIKE with file/kind filter
|
|
151
|
+
|
|
152
|
+
**When multiple candidates exist**, the tool throws `AmbiguousError` with a top-10 candidate list (each with `name + file_path + start_line`). **To disambiguate**, retry with `file=<file_path>` (strongest signal) or `nodeId=<id>` (zero-ambiguity direct lookup).
|
|
153
|
+
|
|
154
|
+
**Anti-patterns**:
|
|
155
|
+
- ❌ `name="Indexer"` (short class name without `file`) → 10+ candidates
|
|
156
|
+
- ✅ `name="Indexer" file="indexer.ts"` → 1 candidate (file disambiguates)
|
|
157
|
+
- ✅ `name="Indexer.indexFile@175"` → 1 candidate (qualified name with @<line>)
|
|
158
|
+
- ✅ `nodeId="ts:src/indexer.ts:method_definition:Indexer.indexFile@175"` → 1 candidate (zero ambiguity)
|
|
159
|
+
|
|
160
|
+
**Edge target resolution (决策 0088)**: for `callers` / `callees` / `impact`, the query layer unions
|
|
161
|
+
two SQL paths: (a) **exact** match on the resolved target node id, plus (b) **wildcard** match on
|
|
162
|
+
`ts:*:*:<symbol-name>` patterns emitted by the IMPORTS edge extractor when a call site references
|
|
163
|
+
a symbol that the indexer hasn't materialized into a real node yet. The wildcard hit is rendered
|
|
164
|
+
with an `(unresolved)` placeholder so you can see the call site without losing the edge.
|
|
165
|
+
|
|
166
|
+
## Filter Values
|
|
167
|
+
|
|
168
|
+
### kind
|
|
169
|
+
`class`, `function`, `method`, `interface`, `type`, `variable`, `route`, `component`, `const`.
|
|
170
|
+
|
|
171
|
+
### language
|
|
172
|
+
`ts`, `tsx`, `js`, `py`, `rs`, `go`, `c`, `cpp`, `csharp`, `java`, `scala`, `ruby`, `php`, `zig`.
|
|
173
|
+
|
|
174
|
+
## Examples
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
# PRIMARY — explore a symbol with code + relations
|
|
178
|
+
codebase(operation="explore" query="MemorySystem")
|
|
179
|
+
|
|
180
|
+
# Quick lookup
|
|
181
|
+
codebase(operation="search" query="auth")
|
|
182
|
+
|
|
183
|
+
# Pre-refactor blast radius (with file disambiguation)
|
|
184
|
+
codebase(operation="impact" name="DatabaseManager" file="database-manager.ts" depth=2)
|
|
185
|
+
|
|
186
|
+
# Find Python handler functions
|
|
187
|
+
codebase(operation="search" query="handler" language="py")
|
|
188
|
+
|
|
189
|
+
# Who calls connect()? (use file when ambiguous)
|
|
190
|
+
codebase(operation="callers" name="connect" file="auth-service.ts")
|
|
191
|
+
|
|
192
|
+
# What does remember() call?
|
|
193
|
+
codebase(operation="callees" name="remember")
|
|
194
|
+
|
|
195
|
+
# Get sub-graph around a symbol (ADVANCED — depth > 1 or both directions)
|
|
196
|
+
codebase(operation="context" name="AuthService" file="auth-service.ts" depth=2)
|
|
197
|
+
|
|
198
|
+
# Inspect one node's edges (ADVANCED — after search)
|
|
199
|
+
codebase(operation="node" name="AuthService.login@20" includeEdges=true)
|
|
200
|
+
|
|
201
|
+
# Graph status snapshot (ADVANCED — only when investigating issues)
|
|
202
|
+
codebase(operation="status")
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## Notes
|
|
206
|
+
- **workspaceDir is auto-injected from session context** — do NOT pass a `dir` parameter (it's not in the schema and would be silently dropped to enforce the Trust Boundary). To query a different workspace, change the session's worktree.
|
|
207
|
+
- **`search` is FTS-only.** No `enableEmbedding` (or any vector-search) parameter is exposed on this tool.
|
|
208
|
+
- If `search` returns 0 hits, retry with a shorter, more token-like keyword (e.g., `Scheduler.createHeartbeat` → `createHeartbeat`), or fall back to `explore(query=...)` for neighborhood-walk retrieval.
|
|
209
|
+
- Use `file` parameter when same-named symbols exist (monorepos) — **this is the single biggest source of "Ambiguous name" errors**
|
|
210
|
+
- Results are truncated at ~24KB; use `maxFiles` / `maxSymbols` to control output size
|
|
211
|
+
- `name` is preferred over `nodeId` for LLM workflow (search → use returned `name + file`)
|
|
212
|
+
- **`explore` is the most cost-effective tool** — usually the ONLY call you need for understanding an area
|
|
213
|
+
- **First-time setup**: if you get `Codebase knowledge graph is not initialized`, ask the user to run `easbot codebase index <workspaceDir>` once, then retry. Do **not** silently retry the tool.
|
|
214
|
+
- **Ambiguous name recovery**: if you see "AmbiguousError — N candidates", retry with `file=<path>` or `nodeId=<id>` from the candidate list. Do NOT retry the same call without changes.
|