@neat.is/claude-skill 中文 description（草稿）

技能简介

NEAT Claude Skill（npm 包 @neat.is/claude-skill）是 NEAT 实时语义图与 Claude Code 的桥接技能。它将 NEAT 的 16 个 MCP 工具注入 Claude Code，使 Agent 在执行编码任务时能够优先查询项目的语义依赖图，而非直接做文本搜索，从而实现对系统结构、依赖关系、运行时行为和线上状态的精准感知。

核心能力

1. 语义图根因分析（get_root_cause）：将故障节点沿依赖图向上追溯，找到导致问题的根本原因，而非仅看到表面报错。
2. 爆炸半径计算（get_blast_radius）：列出指定节点的所有下游依赖，评估变更或故障的潜在影响范围。
3. 依赖全链路查询（get_dependencies）：BFS 遍历指定深度的传递依赖，返回每条边的类型（EXTRACTED vs OBSERVED）和来源证明。
4. 运行时依赖观测（get_observed_dependencies）：仅返回生产环境 OTel 采集的真实调用链，区分"代码声明的依赖"与"实际运行的依赖"。
5. 图谱差异对比（get_graph_diff）：将历史快照与当前运行图谱对比，发现新增、移除和变更的节点与边。
6. 行为分歧检测（get_divergences）：检测代码层（EXTRACTED）与生产层（OBSERVED）的不一致之处，按置信度 × 严重性排序，是 NEAT 最核心的查询能力。
7. 语义搜索（semantic_search）：通过自然语言描述查找图谱节点，有 embedding 向量时用向量检索，否则降级为子串匹配。
8. 最近陈旧边检测（get_recent_stale_edges）：列出所有 OBSERVED → STALE 状态转换，即一段时间无生产流量的集成点，是潜在故障预警信号。
9. 政策合规检查（check_policies）：检查项目的 policy.json 当前违规情况，或预测某操作会否引发违规。
10. 可观测性扩展工具（6个 /neat extend 工具）：自动查找待插桩库、预览插桩 diff、以幂等方式安装/回滚 OTel 插桩包，无需 Agent 手动编辑 OTel 配置。
11. 多平台连接器：支持 Supabase、Railway、Cloudflare、Firebase 平台 API 轮询，将平台级依赖数据汇入 OBSERVED 层。
12. 无 LLM 调用：NEAT 本身不调用任何 LLM，Agent 阅读工具输出自行推理，保证信息透明、无幻觉。
13. 凭证隔离：连接器凭证以 $VAR 环境变量引用存储，Agent 只能读取脱敏后的数据，无法接触密钥原文。
14. Agent 无关引导（GRAPH_FIRST.md）：为所有 Agent（Claude Code / Codex / Cursor / Gemini CLI）提供统一的"先问图再搜索"指导文本。

安装配置

前提条件

• 已安装 Node.js 环境
• 已在项目目录运行过 neat init（注册项目）
• neatd 守护进程正在运行（端口默认 http://localhost:8080），或接受每次通过 npx -y @neat.is/mcp 按需启动

方式一：NEAT CLI 一键安装（推荐）

neat skill --apply

该命令将 mcpServers.neat 自动合并到 ~/.claude.json，不改动其他 MCP 条目。

方式二：手动合并配置

# 打印 MCP 配置片段
cat node_modules/@neat.is/claude-skill/claude_code_config.json

# 或通过 CLI
neat skill --print-config

将输出的 mcpServers.neat 对象合并到 ~/.claude.json 中。

安装搜索引导钩子（可选，推荐开启）

neat hooks --apply

这会安装两个引导机制：

1. Claude Code PreToolUse 钩子：当 Agent 执行 Grep / Glob / Bash grep 时，自动注入提示，引导其优先使用图谱工具。
2. GRAPH_FIRST.md 指导文件：写入 ~/.neat/neat-graph-first.md，可粘贴到任意 Agent 的项目说明文件（CLAUDE.md / AGENTS.md / .cursorrules 等）。

使用步骤

第一步：初始化 NEAT 并启动守护进程

neat init 
neatd start

第二步：安装 Skill 并验证

neat skill --apply
claude mcp list   # 确认 neat MCP 服务器已注册

第三步：开启搜索引导（推荐）

neat hooks --apply

第四步：在编码任务中优先使用图谱查询

不再直接用 Grep 搜索代码，而是先问图谱：

# 通过 NEAT CLI
neat ask "为什么 checkout 失败了？"
neat ask "修改 orders 表会影响哪些服务？"

# 通过 MCP 工具（Claude Code 中）
# 使用 mcp__neat__semantic_search 查找相关节点
# 使用 mcp__neat__get_divergences 检查代码与生产的分歧
# 使用 mcp__neat__get_dependencies 查看传递依赖

第五步：扩展可观测性（按需）

# 列出项目中被 NEAT 自动插桩但尚未覆盖的库
neat_list_uninstrumented

# 查找某库的标准插桩包
neat_lookup_instrumentation 

# 预览插桩变更（不实际写入）
neat_dry_run_extension 

# 执行插桩
neat_apply_extension 

适用场景

1. 生产故障排查：当某服务异常时，用 get_root_cause 追溯真正根因，而非靠日志猜测。
2. 变更影响评估：上线前用 get_blast_radius 评估变更对下游的影响范围。
3. 代码与生产一致性审计：用 get_divergences 定期检查代码声明的依赖与实际运行调用是否一致。
4. 新成员 onboarding：新开发者用 semantic_search 自然语言查询系统结构，快速理解项目架构。
5. 集成点健康监控：用 get_recent_stale_edges 发现长期无生产流量的集成点，提前预警技术债务。
6. CI/CD 变更验证：PR 合入前用 get_graph_diff 对比变更前后图谱，确保没有意外影响。
7. 多 Agent 协作场景：在 Claude Code / Codex / Cursor / Gemini CLI 并存的环境中，通过统一的 GRAPH_FIRST.md 确保各 Agent 优先使用一致的架构感知方式。

适用人群

• 后端工程师：需要精确感知微服务依赖关系、排查生产故障的开发者。
• SRE / DevOps：关注系统可观测性、集成健康度和运行时行为的工程师。
• AI Agent 开发者：想让编码 Agent 具备更深度系统感知能力的技术人员。
• 技术负责人：需要团队统一使用图谱优先的架构感知规范。

工作原理

NEAT 的核心是一个语义依赖图（Semantic Graph）+ 可观测性数据融合层。

图谱层：NEAT 维护一张有向图，节点代表服务、函数、API、资源等图谱实体，边代表依赖关系。节点携带 EXTRACTED（从源码抽取）、OBSERVED（从 OTel 运行时观测）、INFERRED（trace 缝合推算）三种来源标签，以及 STALE 状态标记。

可观测性融合：OBSERVED 数据来自两个渠道：① OTel spans（应用运行时推送，需通过 /neat extend 插桩）；② 平台连接器（NEAT 轮询 Supabase / Railway / Cloudflare / Firebase 等平台 API）。两者融合进同一 OBSERVED 层，Agent 无需关心数据来源。

工具层：16 个 MCP 工具是图谱的查询入口。其中 10 个为只读查询（读实时图谱），6 个为 OTel 插桩管理工具（修改插桩配置但不调用 LLM）。所有工具返回结构化数据，Agent 自行推理下一步行动。

安装机制：@neat.is/claude-skill 包本身只包含 MCP 配置片段（claude_code_config.json）和一个 PreToolUse 钩子脚本（neat-search-nudge.mjs），无编译代码。真正的工作由 @neat.is/mcp 包（stdio MCP 服务器）完成。

官方链接

• npm：https://www.npmjs.com/package/@neat.is/claude-skill
• GitHub（NEAT 主仓库）：https://github.com/NEAT-Technologies/Neat
• 官网：https://neat.is
• SKILL.md：https://github.com/NEAT-Technologies/Neat/blob/main/packages/claude-skill/SKILL.md