跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

cg

Trace code and assess change impact via the pre-built symbol, call-graph and co-edit index.

Surething-io · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Surething-io/cockpit --skill cg

技能说明


name: cg description: "Trace code and assess change impact via the pre-built symbol, call-graph and co-edit index."

Enter project graph exploration mode (CodeGraph).

CodeGraph = pre-built symbol + call-graph index + git co-edit view. Six endpoints, each answers one class of question:

QuestionEndpoint
Where is X defined / which files share the name?search?q=X
Who calls X?callers?qname=X
What does X call?callees?qname=X
Changing X affects which symbols?impact?qname=X&depth=2
What symbols does file F contain?file?path=F
Which files are commonly edited alongside F? (conventional coupling / parallel registries)coedit?filePath=F

All responses are coordinates / file paths — never source bodies. (One exception: search&includeLiterals=true echoes each matched literal's own text in value.) More precise than grep's textual match, cheaper in tokens than Reading whole files.

The 6 graph endpoints ({{BASE_URL}})

# search: find symbols by name → hits carry the same node shape as every other
#   endpoint, so a hit's startLine/endLine feed Read directly.
# q is normalized for naming style: user_profile / userProfile / user-profile / USER_PROFILE are equivalent
# Pass includeLiterals=true to also search identifier-shaped string literals (tool names, event names,
# config keys, route paths — the "looks like a name but isn't an identifier" strings). The response
# then carries an extra literals[] array with value / filePath / line / enclosingSymbol per hit.
curl -fsS "{{BASE_URL}}/api/projectGraph/search?cwd=$PWD&q=<NAME>"
curl -fsS "{{BASE_URL}}/api/projectGraph/search?cwd=$PWD&q=<NAME>&includeLiterals=true"

# callers / callees: 1-hop call relations
curl -fsS "{{BASE_URL}}/api/projectGraph/callers?cwd=$PWD&qname=<QNAME>"
curl -fsS "{{BASE_URL}}/api/projectGraph/callees?cwd=$PWD&qname=<QNAME>"

# impact: transitive callers BFS (depth 1-5, default 2; out-of-range is clamped
#   silently, not rejected). `truncated: true` = node ceiling hit, list is partial.
curl -fsS "{{BASE_URL}}/api/projectGraph/impact?cwd=$PWD&qname=<QNAME>&depth=2"

# file: file symbol tree (no source). Hierarchical: nested symbols live in
#   children[] — always an array, empty for leaves (never null / never absent).
curl -fsS "{{BASE_URL}}/api/projectGraph/file?cwd=$PWD&path=<REL_PATH>"

# coedit: files commonly edited alongside the target = git log history + current working-tree co-edits
#   catches "conventional coupling" the call-graph can't see (parallel registries / double-writes / sibling .md configs)
#   history[] entries may name PRE-RENAME paths (git --follow), so a path here need not exist today.
#   `cooccurrence` is a RAW COUNT; the ratio ships alongside as `probability`.
curl -fsS "{{BASE_URL}}/api/projectGraph/coedit?cwd=$PWD&filePath=<REL_PATH>"

Response shapes

Every endpoint speaks ONE node shape (call it NODE):

{ filePath, qualifiedName, name, kind, startLine, endLine, params?[] }

params is OPTIONAL: absent for non-callables (class / interface / type / enum / const) and for languages without a tree-sitter grammar. params: [] is different — it means "0 parameters", not "unknown".

search    { files[], symbols[], literals?[] }      # literals only with includeLiterals=true
            files[]    = { type:'file',    label, hint?, target: { filePath } }
            symbols[]  = { type:'symbol',  label, hint?, target: NODE }
            literals[] = { type:'literal', value, filePath, line, enclosingSymbol? }
            # narrow on the outer `type`
file      { filePath, language, symbols[] }
            symbols[] = NODE plus { contentHash, children[] }
            # children[] is always an array, empty for leaves (never null / absent)
callers   { qname, target: NODE|null, callers[]: { caller: NODE, callLines[] }, ambiguousIn? }
callees   { qname, target: NODE|null, callees[]: { callee: NODE, callLines[] }, ambiguousIn? }
impact    { qname, target: NODE|null, nodes[]: { symbol: NODE, depth }, truncated, ambiguousIn? }
coedit    { target: string, totalCommits, uncommitted[],
            history[]: { filePath, cooccurrence, probability, lastCoEdit } }
            # probability = cooccurrence / totalCommits, precomputed. `cooccurrence`
            # alone is a RAW COUNT — never compare it against a ratio threshold.
context   { results[]: NODE + { score, signals[] }, seeds[]: { node, weight, from }, degraded }
related   { target, results[]: NODE + { score, relations[] }, coedit[], degraded, ambiguousIn? }
risk      { target, totalImpactedNodes, highRisk[]: NODE + { depth, risk{}, tags[] },
            suggestedTests[], coedit[], degraded, degradedReason? }   # NOTE: no ambiguousIn
affected  { testFiles[], byInput[]: { filePath, reachable, reachableTests[] },
            unresolved[], stats: { visited, bfsMs, truncated }, degraded }

The coedit[] embedded in related / risk is a strict SUPERSET of a /coedit history row (same fields plus a per-row totalCommits) — you never need a second request to get recency.

Errors are { error, tag }. Tags seen from these routes: ValidationError (400), NotFoundError (404), AppError (500 — every endpoint wraps its lookup in one, so an index/git failure surfaces here), InternalError (500, uncaught defect).

Silent-failure traps

  • An unknown qname returns HTTP 200, not 404. callers / callees / impact / related / risk answer a typo'd or non-indexed name with target: null (every endpoint spells this slot target, callees included) and empty arrays — byte-identical to a real symbol that genuinely has no callers. Always check target !== null before concluding "nothing calls this" / "this change is safe". Same for coedit on an unknown path (200, empty). Only file 404s.
  • A non-null target with callers: [] does NOT mean "nothing calls this". obj.method() resolves only when the receiver's imported name directly names the conta
阅读完整来源 ↗