AST API

透過 REST API 查詢程式碼結構。專為 Claude Code、Gemini CLI 等 AI 程式編碼助手設計。

快速開始

步驟 1：取得工作區 ID

所有 API 呼叫都需要：

curl -s 'http://localhost:3033/api/workspaces' | jq '.data.workspaces[0].id'

步驟 2：搜尋符號

curl 'http://localhost:3033/api/search?q=UserService&workspace=<wsId>&limit=10'

步驟 3：使用符號 ID

使用回傳的 symbolId 來查詢呼叫者、被呼叫者和影響分析。

何時使用 AST API

使用 AST API 當：

  • • 使用者問「X 在哪裡？」、「誰呼叫了 X？」
  • • 編輯前需要找到檔案路徑
  • • 變更可能影響多個檔案
  • • 在沒有明確目標時進行廣泛搜尋

跳過 AST API 當：

  • • 使用者提供了確切的檔案路徑
  • • 任務只涉及文檔或設定檔
  • • 只需要字面字串搜尋

API 參考

1. 搜尋符號

GET /api/search?q=<name>&workspace=<wsId>&limit=10

回應欄位：

  • • symbolId - 用於呼叫者/被呼叫者查詢
  • • file - 絕對路徑
  • • line - 0-indexed（顯示時加 1）
  • • type - 5=類別, 6=方法, 11=介面, 12=函式

2. 檔案依賴關係

GET /api/graph/deps?file=src/path/to/file.ts&workspace=<wsId>

回傳：imports（此檔案使用的）和 exports（此檔案提供的）

3. 誰呼叫了這個？（呼叫者）

GET /api/graph/callers?to=<symbolId>&workspace=<wsId>

找出所有呼叫或引用此符號的位置。

4. 這個呼叫了什麼？（被呼叫者）

GET /api/graph/calls?from=<symbolId>&workspace=<wsId>

找出此函式/方法呼叫的所有符號。

5. 影響分析

GET /api/impact?symbolId=<id>&depth=2&workspace=<wsId>

回傳所有會受此符號變更影響的符號和檔案。重構前必備。

6. 重建索引

POST /api/index/update
Content-Type: application/json
{"workspace":"<wsId>"}

程式碼變更後重建索引。當搜尋結果看起來過時時使用。

常見模式

模式 A：找到並理解一個類別

# 1. 找到它
curl 'http://localhost:3033/api/search?q=TerminalService&workspace=ws_xxx&limit=1'
# 記下 symbolId 和檔案路徑

# 2. 查看它的 imports/exports
curl 'http://localhost:3033/api/graph/deps?file=src/main/services/TerminalService.ts&workspace=ws_xxx'

# 3. 現在帶著上下文讀取檔案

模式 B：追蹤使用情況

# 1. 找到函式
curl 'http://localhost:3033/api/search?q=createSession&workspace=ws_xxx&limit=5'
# 選擇正確的 symbolId

# 2. 找出所有呼叫者
curl 'http://localhost:3033/api/graph/callers?to=<symbolId>&workspace=ws_xxx'

模式 C：安全重構

# 變更函式前，檢查影響
curl 'http://localhost:3033/api/impact?symbolId=<id>&depth=2&workspace=ws_xxx'
# 在進行變更前審查 impactedFiles

決策流程圖

使用者詢問程式碼相關問題
        |
        v
是「X 在哪裡？」的問題嗎？
    |是               |否
    v                 v
/api/search      是關於依賴關係的嗎？
    |                 |是          |否
    v                 v            v
取得 symbolId?   /api/graph/deps  是關於呼叫鏈的嗎？
    |是                               |是          |否
    v                                 v            v
需要呼叫者？ -----> /api/graph/callers   使用其他工具
需要被呼叫者？ ---> /api/graph/calls
需要影響分析？ ---> /api/impact

錯誤處理

錯誤原因處理方式
找不到工作區API 未執行啟動 Termdock 應用程式
搜尋結果為空符號未被索引嘗試部分名稱或重建索引
symbolId 404程式碼變更後 ID 過時重新搜尋以取得新 ID

重要提示

  • • 行號是 0-indexed - 顯示給使用者時加 1
  • • 使用相對路徑於 /api/graph/deps（例如 src/main/...）
  • • 符號 ID 是穩定的直到程式碼變更
  • • API 基礎網址：http://localhost:3033（正式版）或 :3032（開發版）

為 Claude Code 安裝 AST 技能

  1. 在 Termdock 開啟 設定 → 技能 分頁
  2. 選擇 Claude Code 作為目標
  3. 在 "termdock-ast" 技能上點擊 安裝
  4. Claude Code 會在相關情境自動使用 AST API