plelevier/gcyphrq

技能指南

gcyphrq技能让AI编码代理能够通过自然语言提示对JSON图文件执行Cypher查询。安装一次后，就可以问类似“API网关依赖哪些服务？”这样的问题，并获得结构化的JSON结果。

该技能的功能

安装后，该技能教会AI代理：

• 自动将自然语言 翻译成Cypher查询
• 使用gcyphrq CLI运行查询 针对您的JSON图文件
• 解释结果 并以可读格式呈现
• 链式执行多个查询 用于复杂分析（爆炸半径、路径追踪、度数分析）

该技能包含一个精选的查询模式库，涵盖常见的基础设施问题——服务依赖、副本拓扑、监控覆盖率等。

安装

使用CLI（推荐）

最简单的方式是使用内置的安装命令。它会检测您已安装的代理（pi、Claude Code、OpenCode）并自动安装该技能：

# 全局安装（在代理配置目录中创建符号链接）
gcyphrq --install-skill global

# 本地安装（复制到当前目录）
gcyphrq --install-skill local

--install-skill命令能够：

• 检测系统上已安装哪些代理
• 创建符号链接（全局）或复制（本地）技能内容
• 为Claude Code和OpenCode生成CLAUDE.md / AGENTS.md参考文件
• 幂等操作——可安全多次运行

安装后：

• Pi 会自动识别该技能。通过/skill:gcyphrq或自然语言描述您的需求来调用。
• Claude Code 在您提出与图相关的问题时会自动识别该技能。
• OpenCode 在您的提示与其描述（图查询、基础架构拓扑、服务依赖等）匹配时加载该技能。

手动安装

如果安装命令不适合您的环境，您可以手动放置技能目录：

# pi
mkdir -p ~/.pi/agent/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
  -o ~/.pi/agent/skills/gcyphrq/SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
  -o ~/.claude/skills/gcyphrq/SKILL.md

# OpenCode
mkdir -p ~/.opencode/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
  -o ~/.opencode/skills/gcyphrq/SKILL.md

您也可以将references/目录（包含queries.md和example-graph.json）下载到SKILL.md旁边的references/子目录中，以获得额外的查询模式和一个独立的测试图。

其他代理

对于任何支持自定义指令或系统提示的AI编码代理：

1. 安装CLI：npm install -g gcyphrq
2. 复制SKILL.md 从 https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md 到您的代理自定义指令中
3. 复制参考文件 从 https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/（包含queries.md和example-graph.json）到 SKILL.md 旁边的 references/ 子目录中
4. 指向您的图文件 — 将技能示例中的 <graph.json> 替换为您的实际图文件路径

前置条件

• gcyphrq CLI 已安装并在PATH中 — 安装指令请参阅入门指南
• 一个JSON图文件 用于查询（可以使用附带的 references/example-graph.json 开始）

示例提示

安装技能后，您可以使用自然语言提示。以下是技能应能解析的示例：

服务依赖

提示： “API网关依赖哪些服务？”

该技能将其翻译为追踪API网关节点出站连接的Cypher查询。

提示： “显示所有连接到PostgreSQL的服务。”

返回所有与PostgreSQL主数据库有TCP连接的服务。

爆炸半径分析

提示： “如果Kafka宕机，什么会受影响？”

追踪从Kafka集群在2跳内可达的所有节点，以显示影响范围。

提示： “如果API网关故障，爆炸半径是多少？”

映射受API网关不可用影响的所有下游服务和基础设施。

路径追踪

提示： “显示从CDN到数据库的路径。”

查找CDN和数据库节点之间的连接路径，显示中间服务。

提示： “请求如何从API网关流向用户数据库？”

追踪通过认证、RPC服务和数据库连接的请求路径。

基础架构拓扑

提示： “消息队列是如何连接的？”

列出所有消息队列基础设施及其生产者/消费者关系。

提示： “数据库的副本设置是什么样的？”

显示主-副本关系和副本边类型。

度数分析

提示： “哪个服务拥有最多的出站连接？”

计算所有服务的出度数，并返回连接最多的服务。

提示： “找出拥有超过2个出站连接的服务。”

使用聚合和WHERE按出度阈值过滤服务。

监控覆盖率

提示： “哪些服务正在被监控？”

查找所有连接到监控基础设施（Prometheus、Grafana等）的服务。

提示： “哪些服务没有监控？”

使用OPTIONAL MATCH查找没有监控连接的服务。

外部依赖

提示： “哪些服务调用外部API？”

追踪1-3跳内的RPC服务，以查找外部API依赖。

提示： “列出所有外部集成。”

返回所有带External标签的节点及其上游调用者。

高级过滤

提示： “显示所有RPC或Worker服务。”

使用WHERE加OR匹配多种类型。

提示： “查找不是批量作业的服务。”

使用WHERE加NOT排除某类型。

提示： “列出us-east-1中名称包含'Service'的服务。”

使用WHERE加AND组合条件。

分页

提示： “显示第2页的服务，每页10条，按字母排序。”

使用ORDER BY、SKIP和LIMIT对服务结果进行分页。

图变更

提示： “添加一个名为'Datadog'的新监控服务。”

使用CREATE向图中添加新节点。

提示： “将API网关的状态设置为'deprecated'。”

使用SET更新节点属性。

提示： “从Alice身上移除'Person'标签。”

使用REMOVE从节点上剥离标签或移除属性，同时保留节点及其关系不变。

技能参考

技能文件（SKILL.md）包含：

• CLI用法 — 命令语法、选项、标准输入管道、链式查询
• 图文件格式 — 节点和边结构
• 支持的Cypher特性 — 完整特性矩阵及状态
• 查询模式 — 使用附带的references/example-graph.json的预构建查询
• 输出格式 — 图格式（默认）和行格式及链式示例
• 局限性 — 已知限制（无子查询、无APOC等）

故障排除

问题	解决方案
gcyphrq: command not found	运行 npm install -g gcyphrq
代理无法检测到技能	确认 SKILL.md 位于您平台正确的技能目录中
查询返回空结果	检查节点标签和属性名称是否与您的图文件完全匹配

下一步

• [入门指南]({{ '/getting-started/' | relative_url }}) — 安装gcyphrq并运行您的第一个查询
• [查询指南]({{ '/query-guide/' | relative_url }}) — 完整的Cypher语法参考
• [示例]({{ '/examples/' | relative_url }}) — 30个可直接运行的查询及样例输出
• [库API]({{ '/library-api/' | relative_url }}) — 在Node.js / TypeScript中以编程方式使用gcyphrq