codegraph-ast-grep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeGraph + ast-grep

Goal

目标

Make a repository's coding agents ready to use CodeGraph for semantic scope and ast-grep CLI for structural evidence. Public workflows manage that capability; repository exploration and refactoring are ordinary internal coding behaviors after setup.

让仓库的编程 Agent 做好使用 CodeGraph 获取语义范围、使用 ast-grep CLI 获取结构证据的准备。公开工作流负责管理这项能力；完成设置后，仓库探索和重构属于普通的内部编码行为。

When to use

何时使用

Install or reconcile CodeGraph, ast-grep CLI, MCP exposure, indexing, and agent guidance.
Update the installed analysis stack and run required configuration, index, or schema migrations.
Diagnose a missing, stale, disconnected, or apparently broken setup without repairing it.

安装或对齐 CodeGraph、ast-grep CLI、MCP 暴露、索引和 Agent 指引。
更新已安装的分析栈，并运行所需的配置、索引或 schema 迁移。
诊断缺失、过期、断开连接或看似损坏的设置，但不执行修复。

When not to use

何时不使用

Do not activate this skill merely because a coding task can benefit from an already-ready analysis stack. Follow the persisted repository guidance instead. Do not use it for general dependency audits, compiler/runtime proof, or an unreviewed broad rewrite.

不要仅仅因为某项编码任务可以从已准备好的分析栈中受益就激活此 skill。应遵循已持久化的仓库指引。也不要在常规依赖审计、编译器或运行时证明，以及未经审查的大范围重写中使用它。

Workflow selection

工作流选择

Always expose these finite workflows in plain, benefit-first language when the skill is invoked directly:

```
setup
```
: supercharge the repository with Semantic Code Intelligence and structural code search, helping coding agents answer faster with fewer tool calls. Install missing pieces, connect the coding client, build the code index, add repository guidance, and safely reuse or repair any existing setup.
```
update
```
: bring an existing setup to current stable versions without changing how it was installed. Migrate configuration or index data when needed, reconnect the coding client, and verify that everything still works.
```
doctor
```
: diagnose setup health and report analytics without repairing anything.

There is no

auto

workflow. Select by intent:

An explicit setup or installation request selects
```
setup
```
.
An explicit stable-tool update, migration, or refresh request selects
```
update
```
.
“Something is broken,” a health check, or a request for setup analytics selects
```
doctor
```
.
A bare invocation or ambiguous intent requires showing all three workflows and asking the user to choose.

For clear direct intent, state the selected workflow, rationale, root, expected writes/artifacts, and protected state, then proceed. Agent-initiated activation may select and announce only

doctor

; it must not infer setup or update authority. Selecting

setup

update

is allowed only when the user already requested that outcome for the stated root. Privileged/global installation, paid or external services, publication/deployment, destructive replacement, telemetry changes, and scope expansion retain separate approval.

直接调用 skill 时，始终以通俗、以收益为先的语言展示以下三种有限工作流：

```
setup
```
：全面增强仓库的 Semantic Code Intelligence 和结构化代码搜索能力，让编程 Agent 用更少的工具调用更快给出答案。安装缺失组件、连接编程客户端、构建代码索引、添加仓库指引，并安全复用或修复任何现有设置。
```
update
```
：将现有设置升级至当前稳定版本，同时不改变其安装方式。必要时迁移配置或索引数据，重连编程客户端，并验证一切仍然正常。
```
doctor
```
：诊断设置健康状况并报告分析结果，但不执行修复。

不存在

auto

工作流。请根据意图选择：

明确要求设置或安装时，选择
```
setup
```
。
明确要求更新稳定版工具、执行迁移或刷新时，选择
```
update
```
。
“Something is broken”、健康检查或设置分析请求，选择
```
doctor
```
。
仅调用 skill 或意图不明确时，必须展示全部三种工作流，并要求用户选择。

对于意图明确的直接请求，应先说明所选工作流、选择理由、根目录、预期写入项或产物以及受保护状态，然后继续执行。Agent 主动激活时只能选择并声明

doctor

，不得自行推断

setup

或

update

权限。只有当用户已经针对指定根目录请求相应结果时，才能选择

setup

或

update

。特权或全局安装、付费或外部服务、发布或部署、破坏性替换、遥测变更以及范围扩展仍需单独批准。

Inputs to inspect

需要检查的输入

Exact repository root, nested repositories or monorepo packages, package/declarative policy, and protected Git state.
Effective
```
CODEGRAPH_DIR
```
(default
```
.codegraph/
```
), root
```
codegraph.json
```
when supported,
```
sgconfig.yml
```
/
```
sgconfig.yaml
```
, and repository instruction files.
Executable paths, installer channel and scope, version pins, installed help, configured client, and exposed MCP tools.
Approved scope for package/config/index writes and any exact-root project opening that may migrate generated metadata.

精确的仓库根目录、嵌套仓库或 monorepo 包、包管理与声明式策略，以及受保护的 Git 状态。
生效的
```
CODEGRAPH_DIR
```
（默认值为
```
.codegraph/
```
）、受支持时根目录下的
```
codegraph.json
```
、
```
sgconfig.yml
```
/
```
sgconfig.yaml
```
，以及仓库指令文件。
可执行文件路径、安装器渠道和作用域、版本锁定、已安装工具的帮助信息、已配置客户端，以及已暴露的 MCP 工具。
对软件包、配置和索引写入的已批准范围，以及任何以精确仓库根目录打开项目的操作；此类操作可能会迁移生成的元数据。

Workflow

工作流

setup

setup

Capture the exact root, protected state, runtime client, package/declarative policy, existing installer provenance, and offline/telemetry constraints.
Inspect existing binaries, configuration, MCP exposure, state paths, and repository guidance before changing anything. Installed help and exposed tools are authoritative.
Reconcile the stable CodeGraph release and stable ast-grep CLI through the repository's approved installer channel and scope. Do not install the experimental ast-grep MCP server during normal setup.
Configure the selected runtime client and CodeGraph project root, then perform the help-confirmed initialization and any required configuration/index/schema migration within the approved root.
Persist concise repository-native guidance for coding agents. It must say, in equivalent terms: use CodeGraph for semantic symbols, callers, call paths, and impact; use ast-grep CLI for structural syntax evidence; reconcile both before broad edits.
Reconnect or restart the client when required, then verify one semantic query, one bounded structural query, state freshness, and guidance discovery.
Report installed versions/provenance, writes, migration/reconnection evidence, readiness, and remaining limitations.

Setup is idempotent and agent-complete: rerunning it reconciles drift instead of duplicating config, instructions, indexes, or dependencies.

收集精确根目录、受保护状态、运行时客户端、包管理与声明式策略、现有安装器来源，以及离线或遥测限制。
在进行任何更改前，检查现有二进制文件、配置、MCP 暴露、状态路径和仓库指引。已安装工具的帮助信息和已暴露的工具是权威依据。
通过仓库批准的安装器渠道和作用域，对齐稳定版 CodeGraph 发布版本与稳定版 ast-grep CLI。正常设置期间不要安装实验性的 ast-grep MCP server。
配置所选运行时客户端和 CodeGraph 项目根目录，然后在已批准根目录内执行经帮助信息确认的初始化操作，以及所需的配置、索引或 schema 迁移。
为编程 Agent 持久化简洁且符合仓库原生的指引。指引必须用等价表述说明：使用 CodeGraph 获取语义符号、调用方、调用路径和影响范围；使用 ast-grep CLI 获取结构化语法证据；进行广泛编辑前先对齐两者结果。
根据需要重连或重启客户端，然后验证一次语义查询、一次有边界的结构查询、状态新鲜度以及指引发现情况。
报告已安装版本及其来源、写入内容、迁移或重连证据、就绪状态和剩余限制。

设置必须具备幂等性并可由 Agent 完整执行：重复运行时应校准偏差，而不是重复生成配置、指令、索引或依赖项。

update

update

Capture the same root, policy, protected-state, telemetry, and provenance evidence as setup.
Compare installed core tools with their authoritative stable channels once. Respect offline intent,
```
DO_NOT_TRACK
```
,
```
CODEGRAPH_NO_UPDATE_CHECK
```
, registry restrictions, and repository pins.
Preserve the existing installer channel and global/project/declarative scope. Update only the stable CodeGraph and ast-grep CLI components selected by repository policy; never run a blanket update-all operation.
Run every version-required configuration, index, or schema migration in the approved root. Keep binary replacement, runtime-config changes, prompt hooks, telemetry, and graph operations visible in the execution receipt.
Reconnect/restart the client, refresh the graph only as required, and verify versions/PATH, MCP exposure, graph readiness, a semantic query, a structural query, and persisted guidance.
If an update fails, stop further mutation, preserve config/index state, report what still works, and use only a pre-disclosed safe rollback.

The user's explicit update request authorizes ordinary in-root update and required migration work. Ask separately for privilege escalation, installer-channel or scope changes, unrelated dependency changes, destructive rebuilds, or external-service actions.

收集与设置相同的根目录、策略、受保护状态、遥测和来源证据。
仅一次将已安装的核心工具与其权威稳定渠道进行比较。遵守离线意图、
```
DO_NOT_TRACK
```
、
```
CODEGRAPH_NO_UPDATE_CHECK
```
、registry 限制和仓库版本锁定。
保留现有安装器渠道以及全局、项目或声明式作用域。仅更新仓库策略选定的稳定版 CodeGraph 和 ast-grep CLI 组件；绝不执行一刀切的
```
update-all
```
操作。
在已批准根目录中运行所有由版本要求触发的配置、索引或 schema 迁移。在执行回执中明确记录二进制替换、运行时配置变更、提示词钩子、遥测和图操作。
重连或重启客户端，仅在确有需要时刷新图谱，并验证版本与 PATH、MCP 暴露、图谱就绪状态、语义查询、结构查询和持久化指引。
如果更新失败，停止进一步变更，保留配置和索引状态，报告仍然可用的功能，并且只使用事先披露的安全回滚方案。

用户明确提出更新请求，即授权在根目录内执行常规更新和所需迁移。权限提升、安装器渠道或作用域变更、无关依赖变更、破坏性重建及外部服务操作仍需单独询问。

doctor

doctor

Inspect executable/provenance, versions/help, config presence, MCP registration, state paths, ignore policy, repository guidance, and non-opening connectivity evidence.
Do not install, update, reconnect by writing config, initialize/rebuild/sync, repair, or rewrite source.
Before
```
codegraph status
```
, an MCP graph query, or another diagnostic that opens a project and may migrate generated metadata, name the exact root and obtain affirmative approval, or use an approved disposable copy. Without that approval, report the skipped deep check.
When approved, gather bounded graph health and useful analytics such as freshness, indexed languages, symbol/file coverage, and query readiness. Do not describe this as strictly read-only if metadata migration was possible.
Return diagnosis, evidence, confidence, recommended
```
setup
```
or
```
update
```
follow-up, and any unverified boundary. Do not repair as part of
```
doctor
```
.

检查可执行文件及其来源、版本与帮助信息、配置是否存在、MCP 注册状态、状态路径、忽略策略、仓库指引，以及无需打开项目的连通性证据。
不得安装、更新、通过写入配置进行重连、初始化、重建、同步、修复或重写源代码。
在执行
```
codegraph status
```
、MCP 图谱查询或其他可能打开项目并迁移生成元数据的诊断前，必须指明精确根目录并获得明确批准，或者使用已批准的临时副本。未经批准时，应报告已跳过的深度检查。
获得批准后，收集有边界的图谱健康信息和有用分析，例如新鲜度、已索引语言、符号或文件覆盖率以及查询就绪状态。如果可能发生元数据迁移，不得将其描述为严格只读。
返回诊断结果、证据、置信度、建议的后续
```
setup
```
或
```
update
```
操作，以及任何未验证的边界。
```
doctor
```
不得执行修复。

Internal coding behaviors

内部编码行为

Once the setup is ready, coding agents use these behaviors without treating them as public skill modes:

Routine semantic exploration, structural search, impact analysis, rule authoring, and reviewed rewrites are internal coding behaviors.

Semantic exploration: prefer exposed
```
codegraph_explore
```
, then installed-help-confirmed
```
codegraph explore
```
, then narrower verified CodeGraph capabilities.
Structural search: use ast-grep CLI after the syntax shape is known; specify language when ambiguous and bound paths/output.
Impact analysis: reconcile semantic ownership/call paths with structural match inventory and targeted source reads.
Rule authoring: use tested YAML rules for reusable or relational patterns, including positive and negative fixtures.
Reviewed rewrites: inventory, test, preview, approve exact bounded scope, apply, inspect the diff, and run repository-native validation.

When semantic and structural evidence disagree, check graph freshness/root, parser/language, generated or dynamic code, ignore rules, and targeted source before claiming coverage. Runtime-native LSP and bounded text/file inspection are fallbacks; neither core tool is compiler, type, taint, or runtime proof.

设置就绪后，编程 Agent 应直接使用以下行为，而不将其视为公开的 skill 模式：

常规语义探索、结构搜索、影响分析、规则编写和经审查的重写均属于内部编码行为。

**语义探索：**优先使用已暴露的
```
codegraph_explore
```
，然后使用经已安装帮助信息确认
```
codegraph explore
```
，最后使用范围更窄且经验证的 CodeGraph 能力。
**结构搜索：**在已知语法结构后使用 ast-grep CLI；语法结构存在歧义时应指定语言，并限制路径和输出范围。
**影响分析：**将语义归属关系和调用路径与结构匹配清单及针对性源码读取结果进行交叉核对。
**规则编写：**使用经过测试的 YAML 规则表达可复用或关系型模式，其中包括正向和反向测试样例。
**经审查的重写：**先盘点、测试和预览，批准精确且有边界的范围，再应用更改、检查 diff，并运行仓库原生验证。

当语义证据与结构证据不一致时，在声称覆盖范围前，应检查图谱新鲜度与根目录、解析器或语言、生成代码或动态代码、忽略规则以及针对性源码。运行时原生 LSP 和有边界的文本或文件检查可作为回退手段；两个核心工具都不能提供编译器、类型、taint 分析或运行时层面的证明。

Safety rules

安全规则

Keep ast-grep CLI as the supported default; the experimental ast-grep MCP server is excluded from normal setup.
Suppress CodeGraph telemetry for skill-driven checks and approved setup/update commands with
```
CODEGRAPH_TELEMETRY=0
```
unless the user separately consented to telemetry. Default-on telemetry is not consent.
Prefer exact packages or checksummed release assets. Do not default to pipe-to-shell or pipe-to-PowerShell installation.
Preserve installer channel and scope; do not bypass package-manager freshness, trust, lifecycle-script, checksum, or declarative policy.
Do not invent
```
.codegraph/config.json
```
. Treat effective
```
CODEGRAPH_DIR
```
as generated state and root
```
codegraph.json
```
as version/capability dependent.
Do not assume auto-sync without an active supported watcher or require manual sync when status proves freshness.
Do not apply an untested ast-grep rewrite or indiscriminately accept snapshots/update-all behavior.
Redact secrets, static headers, customer data, private service names, and internal hostnames from persisted or public artifacts.

将 ast-grep CLI 保持为受支持的默认方案；正常设置中排除实验性的 ast-grep MCP server。
对于 skill 驱动的检查以及已批准的设置或更新命令，使用
```
CODEGRAPH_TELEMETRY=0
```
抑制 CodeGraph 遥测，除非用户另行同意启用遥测。默认启用遥测不构成用户同意。
优先使用精确的软件包或带校验和的发布资产。不要默认采用 pipe-to-shell 或 pipe-to-PowerShell 安装方式。
保留安装器渠道和作用域；不要绕过软件包管理器的版本时效性、信任机制、生命周期脚本、校验和或声明式策略检查。
不要臆造
```
.codegraph/config.json
```
。将生效的
```
CODEGRAPH_DIR
```
视为生成状态，并将根目录下的
```
codegraph.json
```
视为取决于版本或能力的文件。
没有受支持的活动 watcher 时，不要假定
```
auto-sync
```
可用；status 已证明状态新鲜时，也不要要求手动 sync。
不要应用未经测试的 ast-grep 重写，也不要不加区分地接受快照或
```
update-all
```
行为。
从持久化或公开产物中隐去密钥、静态标头、客户数据、私有服务名称和内部主机名。

References

参考资料

Read only what the selected workflow or later coding task needs:

```
references/setup-and-mcp-config.md
```
for installation scopes, runtime configuration, state paths, and initialization.
```
references/update-and-provenance.md
```
for stable channels, provenance-preserving updates, migrations, verification, and rollback.
```
references/troubleshooting.md
```
for the read-only doctor ladder and follow-up routing.
```
references/codegraph-capability-guide.md
```
for current/legacy capability discovery, graph freshness, and exact-root project opening.
```
references/usage-playbook.md
```
for the persisted agent guidance and internal semantic/structural/impact behaviors.
```
references/ast-grep-rule-recipes.md
```
for bounded CLI patterns, rules/tests, and reviewed rewrites.
```
references/extensions-and-escalation.md
```
only when the core stack cannot safely express the task.

仅阅读所选工作流或后续编码任务所需的内容：

```
references/setup-and-mcp-config.md
```
：安装作用域、运行时配置、状态路径和初始化。
```
references/update-and-provenance.md
```
：稳定渠道、保留来源的更新、迁移、验证和回滚。
```
references/troubleshooting.md
```
：只读 doctor 检查阶梯和后续操作路由。
```
references/codegraph-capability-guide.md
```
：当前或旧版能力发现、图谱新鲜度，以及以精确根目录打开项目。
```
references/usage-playbook.md
```
：持久化 Agent 指引，以及内部语义、结构与影响分析行为。
```
references/ast-grep-rule-recipes.md
```
：有边界的 CLI 模式、规则与测试，以及经审查的重写。
仅当核心工具栈无法安全表达任务时，才阅读
```
references/extensions-and-escalation.md
```
。

Scripts

脚本

No runtime scripts. Use installed tools and repository-native validation commands; the catalog's deterministic contract validator is maintainer-only and is not installed with the skill.

没有运行时脚本。使用已安装的工具和仓库原生验证命令；该 catalog 的确定性契约验证器仅供维护者使用，不随 skill 安装。

Output format

输出格式

Report the selected workflow and rationale, exact root, protected state, installer provenance, versions/capabilities, writes or skipped writes, migrations/reconnect state, verification evidence, and remaining limitations. For

doctor

, separate non-opening evidence from exact-root deep analytics and provide diagnosis plus a recommended follow-up without repair.

报告所选工作流及选择理由、精确根目录、受保护状态、安装器来源、版本与能力、实际写入或跳过的写入、迁移与重连状态、验证证据，以及剩余限制。对于

doctor

，应将无需打开项目的证据与精确根目录深度分析分开，并提供诊断结果和建议的后续操作，但不得修复。

Completion criteria

完成标准

The selected
```
setup
```
,
```
update
```
, or
```
doctor
```
workflow and intent rationale are explicit.
Setup/update preserve provenance and protected state, and required migrations/reconnection are verified.
Target-repository guidance makes semantic plus structural evidence the default for broad coding work.
Doctor performs no repair and labels exact-root graph-opening approval and possible metadata mutation accurately.
Readiness is proven with verified capabilities and representative semantic/structural checks, or limitations are explicit.

明确说明所选的
```
setup
```
、
```
update
```
或
```
doctor
```
工作流及选择理由。
设置或更新操作保留来源信息和受保护状态，并验证所需迁移及重连。
目标仓库的指引使语义证据和结构证据成为广泛编码工作的默认依据。
Doctor 不执行修复，并准确标明精确根目录图谱打开操作的批准情况及可能发生的元数据变更。
使用已验证的能力以及有代表性的语义和结构检查来证明就绪状态；如果无法证明，则明确说明限制。

Failure modes

失败模式

If intent or root is ambiguous, expose all three workflows and ask before inspection or mutation.
If stable metadata is blocked, report
```
not checked
```
; do not bypass offline, opt-out, registry, or pinning policy.
If setup/update needs an unauthorized privilege, channel, scope, destructive rebuild, or external action, preserve current state and request that specific authority.
If a tool or client remains unavailable, retain verified intermediates/configuration, report incomplete readiness, and give the narrowest next action.
If evidence conflicts, report the disagreement and confidence rather than claiming complete semantic or structural coverage.

如果意图或根目录不明确，应展示全部三种工作流，并在检查或变更前询问用户。
如果稳定渠道元数据检查受阻，应报告
```
not checked
```
；不要绕过离线、选择退出、registry 或版本锁定策略。
如果设置或更新需要未获授权的提权、渠道变更、作用域变更、破坏性重建或外部操作，应保留当前状态并请求对应权限。
如果工具或客户端仍不可用，应保留已验证的中间产物和配置，报告尚未完全就绪，并给出范围最窄的下一步操作。
如果证据相互冲突，应报告分歧和置信度，而不是声称已获得完整的语义或结构覆盖。

codegraph-ast-grep

Original

Translation

CodeGraph + ast-grep

CodeGraph + ast-grep

Goal

目标

When to use

何时使用

When not to use

何时不使用

Workflow selection

工作流选择

Inputs to inspect

需要检查的输入

Workflow

工作流

`setup`

`setup`

`update`

`update`

`doctor`

`doctor`

Internal coding behaviors

内部编码行为

Safety rules

安全规则

References

参考资料

Scripts

脚本

Output format

输出格式

Completion criteria

完成标准

Failure modes

失败模式