codegraph-ast-grep

CodeGraph + ast-grep

目标

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

适用情况

• 安装或协调 CodeGraph、ast-grep CLI、MCP 暴露、索引和 Agent 指引。
• 更新已安装的分析栈，并运行所需的配置、索引或架构迁移。
• 诊断缺失、过时、断开连接或看似故障的设置，但不进行修复。

不适用情况

不要仅仅因为编码任务可以受益于已就绪的分析栈，就激活此技能。请遵循持久化的仓库指引。不要将其用于常规依赖项审计、编译器／运行时验证，或未经审核的大范围改写。

工作流选择

完整且有限的工作流清单如下，采用直白、以收益为先的表述：

• setup：通过语义代码智能和结构化代码搜索增强仓库，帮助编码 Agent 更快作答并减少工具调用。安装缺失组件、连接编码客户端、构建代码索引、添加仓库指引，并安全地复用或修复现有设置。
• update：将现有设置更新到当前稳定版本，同时不改变安装方式。根据需要迁移配置或索引数据、重新连接编码客户端，并验证一切仍能正常工作。
• doctor：诊断设置健康状况并报告分析数据，不进行任何修复。

对于不明确的调用或有实质歧义的调用，或用户明确要求查看选项时，按文档顺序展示完整且有限的工作流清单。仅请求查看选项并不代表授权执行或检查仓库／工具；请依据文档清单作答。对于明确且已授权的意图，只说明所选工作流及其理由，并列出重要的范围和证据字段，然后继续执行。

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

• 明确请求设置或安装时，选择 setup。
• 明确请求稳定工具更新、迁移或刷新时，选择 update。
• 用户表示“有东西坏了”、要求健康检查或要求提供设置分析数据时，选择 doctor。
• 对于未指定内容的调用或意图不明确的情况，展示全部三个工作流并请用户选择。

对于明确的直接意图，只说明所选工作流、理由、根目录、预期写入／生成的产物以及受保护状态，然后继续执行。由 Agent 发起激活时，只能选择并说明 doctor；不得推断其获得了执行设置或更新的权限。只有当用户已针对所述根目录请求相应结果时，才允许选择 setup 或 update。特权／全局安装、付费或外部服务、发布／部署、破坏性替换、遥测变更以及范围扩展，仍需单独审批。

需要检查的输入

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

工作流

setup

1. 记录确切的根目录、受保护状态、运行时客户端、软件包／声明式策略、现有安装来源，以及离线／遥测限制。
2. 在更改任何内容前，检查现有二进制文件、配置、MCP 暴露情况、状态路径和仓库指南。已安装工具的帮助信息和已暴露的工具具有权威性。
3. 通过仓库批准的安装渠道和范围，协调稳定版 CodeGraph 与稳定版 ast-grep CLI。正常设置期间不要安装实验性的 ast-grep MCP 服务。
4. 配置所选运行时客户端和 CodeGraph 项目根目录，然后在批准的根目录内执行经帮助信息确认的初始化，以及任何所需的配置／索引／架构迁移。
5. 持久化简洁、符合仓库惯例的编码 Agent 指南。指南必须表达以下等效含义：语义符号、调用方、调用路径和影响分析使用 CodeGraph；结构语法证据使用 ast-grep CLI；进行大范围编辑前协调两者的结果。
6. 根据需要重新连接或重启客户端，然后验证一项语义查询、一项范围受限的结构查询、状态新鲜度和指南发现情况。
7. 报告已安装版本／来源、写入内容、迁移／重新连接证据、就绪情况和剩余限制。

设置具有幂等性，且可由 Agent 完整执行：重新运行时会协调偏差，而不会重复添加配置、说明、索引或依赖项。

update

1. 收集与 setup 相同的根目录、策略、受保护状态、遥测和来源证据。
2. 将已安装的核心工具与其权威稳定渠道各比较一次。遵守离线意图、DO_NOT_TRACK、CODEGRAPH_NO_UPDATE_CHECK、注册表限制和仓库固定版本。
3. 保留现有安装渠道以及全局／项目／声明式范围。仅更新仓库策略选定的稳定版 CodeGraph 和 ast-grep CLI 组件；绝不执行一揽子更新全部操作。
4. 在批准的根目录内执行版本要求的所有配置、索引或架构迁移。清晰记录二进制文件替换、运行时配置更改、提示词钩子、遥测和图操作，并纳入执行回执。
5. 重新连接／重启客户端，仅在需要时刷新图，并验证版本／PATH、MCP 暴露情况、图就绪情况、一项语义查询、一项结构查询和持久化指南。
6. 如果更新失败，停止进一步变更，保留配置／索引状态，报告仍可正常工作的部分，并且只使用事先披露的安全回滚方案。

用户明确提出的更新请求授权执行普通的根目录内更新和必要的迁移。若需提升权限、更改安装渠道或范围、变更无关依赖项、进行破坏性重建或执行外部服务操作，请另行征求许可。

doctor

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

内部编码行为

设置就绪后，编码 Agent 会使用以下行为，但不会将其视为公开的技能模式：

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

• **语义探索：**优先使用已公开的 codegraph_explore，然后使用经已安装帮助信息确认的 codegraph explore，再考虑范围更窄且已验证的 CodeGraph 功能。
• **结构化搜索：**确定语法形态后使用 ast-grep CLI；存在歧义时指定语言，并限制路径和输出范围。
• **影响分析：**结合语义归属关系／调用路径、结构化匹配清单和针对性的源代码读取进行核验。
• **规则编写：**对于可复用或涉及关系的模式，使用经过测试的 YAML 规则，其中包括正向和负向测试样例。
• **经审查的重写：**先盘点，再测试和预览；批准明确且有界的范围后再应用，检查差异，并运行仓库原生验证。

当语义证据与结构证据不一致时，应检查图的新鲜度／根目录、解析器／语言、生成或动态代码、忽略规则以及针对性的源代码，再声称覆盖充分。原生运行时 LSP 和有界文本／文件检查是备用方案；核心工具都不能证明编译器、类型、污点或运行时方面的问题。

安全规则

• 将 ast-grep CLI 作为受支持的默认工具；实验性的 ast-grep MCP 服务不纳入常规设置。
• 对技能驱动的检查和经批准的设置／更新命令，使用 CODEGRAPH_TELEMETRY=0 禁用 CodeGraph 遥测，除非用户另行同意启用遥测。默认启用遥测不代表用户已同意。
• 优先使用精确的软件包或带校验和的发布资产。不要默认采用通过管道传给 shell 或 PowerShell 的安装方式。
• 保留安装渠道和范围；不要绕过软件包管理器的新鲜度、信任、生命周期脚本、校验和或声明式策略。
• 不要臆造 .codegraph/config.json。将生效的 CODEGRAPH_DIR 视为生成状态；根目录下的 codegraph.json 则取决于版本／功能。
• 不要在没有启用且受支持的监视程序时假定会自动同步；如果状态已证明内容是最新的，也不要要求手动同步。
• 不要应用未经测试的 ast-grep 重写，也不要不加区分地接受快照／update-all 行为。
• 对持久化或公开的制品，隐去机密、静态标头、客户数据、私有服务名称和内部主机名。

参考资料

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

• 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：仅在核心技术栈无法安全表达任务时阅读。

脚本

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

输出格式

报告所选工作流及其理由、精确根目录、受保护状态、安装来源信息、版本／功能、已执行或跳过的写入、迁移／重连状态、验证证据以及剩余限制。对于 doctor，应区分非打开式证据与精确根目录的深度分析，并提供诊断和建议的后续步骤，不进行修复。

完成标准

• 明确指出所选的 setup、update 或 doctor 工作流，并说明意图依据。
• setup/update 保留来源信息和受保护状态，并验证所需的迁移/重新连接。
• 面向目标仓库的指导将语义和结构证据作为广泛编码工作的默认要求。
• Doctor 不执行修复，并准确说明打开图谱需获得的精确根目录授权，以及可能发生的元数据更改。
• 通过已验证的能力以及有代表性的语义/结构检查证明就绪状态，或明确说明限制。

失败模式

• 如果意图或根目录不明确，列出全部三个工作流，并在检查或更改前询问。
• 如果无法访问稳定元数据，则报告 not checked；不要绕过离线、退出、注册表或固定版本策略。
• 如果 setup/update 需要未经授权的权限、渠道、范围、破坏性重建或外部操作，则保留当前状态，并请求相应的具体授权。
• 如果工具或客户端仍不可用，则保留已验证的中间结果/配置，报告就绪状态未完成，并给出范围最小的后续操作。
• 如果证据相互矛盾，则报告分歧及置信度，而不要声称语义或结构覆盖完整。