@easbot/codebase 0.3.36 → 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 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.36
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.36
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
- ## Installation
19
+ ## Database Backend
19
20
 
20
- ```bash
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
- ## Quick Start
23
+ ### Default backend: `better-sqlite3`
25
24
 
26
- ```typescript
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
- // Create graph instance
30
- const graph = await createCodebase({
31
- workspaceDir: '/path/to/your/project',
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
- // Index project
35
- const result = await graph.indexDirectory();
36
- console.log(`Indexed: ${result.filesProcessed} files, ${result.nodesCreated} nodes`);
31
+ ### Switching backends
37
32
 
38
- // Search code
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
- // Query nodes
45
- const classes = await graph.queryNodes({ astType: 'class_declaration' });
35
+ For the full backend abstraction and performance comparison see:
46
36
 
47
- // Query call graph
48
- const callGraph = await graph.queryCallGraph('ts:src/service.ts:function_declaration:UserService');
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
- // Close graph
51
- await graph.close();
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` is also exposed as a standalone CLI `easbot-codebase` (and via the main `easbot` CLI as `easbot codebase ...`). It provides 25+ subcommands covering the full lifecycle (init / index / sync / status / doctor / config / upgrade / embed / recreate / clear / watch / stop) and graph queries (query / node / context / impact / callers / callees / explore / dead-code / circular / path / config get|set).
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-codebase status --json
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-codebase init --json
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
- # "initialSync": { "filesAdded": 0, "filesUpdated": 0, ... }
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-codebase path <missing> --json
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 | Parent-child AST relationship |
334
- | CALLS | Function call relationship |
335
- | INHERITS_FROM | Class inheritance |
336
- | IMPLEMENTS | Interface implementation |
337
- | IMPORTS | Module import |
338
- | REFERENCES | Variable/identifier reference |
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.36
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.