neat

NEAT 通过构建代码库的实时确定性模型——将静态代码与实时运行时行为融合为一张图——并通过 MCP 工具将其暴露给 AI 代理，从而解决 AI 编码上下文问题。它旨在减少 LLM 幻觉，提供沿图节点和边的时间旅行错误日志以用于调试，并通过策略强制执行架构规则。 ## 核心概念 中心是系统的一张实时图，由两个流融合而成： - **静态分析**——对源代码（JavaScript、TypeScript、Python）、`package.json` 以及 yaml/env 配置运行 tree-sitter。每个源文件成为一个节点；导入成为边；对数据库、队列和外部主机的调用从代码中提取。 - **运行时遥测**——OpenTelemetry span 被归属回发起调用的确切文件和行。NEAT 会自动接入插桩。 两个流落在相同的节点上，因此图中并排保存了代码*声明*的内容和系统*实际执行*的内容。文件是主要单元——关系从文件出发（例如 `src/services/billing.ts ──CALLS──▶ api.stripe.com`），使答案保持清晰且具体。 每条边都带有一个 `provenance` 标签： - `EXTRACTED` 来自源代码（无时钟衰减） - `OBSERVED` 来自 span（带有 `lastObserved` 和 `callCount`） - `INFERRED` 由 trace 拼接器在 OTel 覆盖存在缺口处推断（置信度设有上限） - `STALE` 因为运行时不再发声（保留原始 `lastObserved`） ## 快速开始 ```bash npx neat.is ``` 在项目内部运行（或 `npx neat.is <path>`）。它会发现服务、提取静态图、接入 OpenTelemetry、启动守护进程并打开仪表盘——无需配置。然后运行应用，观察实时边逐渐填充。 > **Windows 注意：** 使用 `neat` 命令，而不是 `npx neat.is`。npm 会生成一个字面名为 `neat.is` 的 shim，而 Windows 不会执行 `.is` 文件。全局安装一次（`npm i -g neat.is`）并运行 `neat`（或 `neat <path>`）。若未全局安装：`npx -p neat.is neat`。 ## CLI 动词 ``` neat <path> 编排器：提取、插桩、启动守护进程、打开仪表盘 neat init <path> 仅提取；默认补丁模式，--apply 写入 neat watch <path> 在文件变化时保持图实时更新 neat deploy 为托管目标生成部署产物 neat sync --to <url> 将本地 EXTRACTED 快照推送到远程守护进程 neat divergences 代码与生产流量不一致之处 neat root-cause <id> 沿入边回溯，找出最先出问题的环节 neat blast-radius <id> 出边 BFS；如果此节点失效会破坏什么 neat dependencies <id> 传递性出边依赖 neat incidents 最近的错误事件 neat policies 当前策略违规 neat search <query> 对节点名称和 id 进行语义匹配 ``` 每个查询动词都支持 `--json` 和 `--project <name>`。退出码：0 成功，1 服务器错误，2 误用，3 守护进程不可达。 ## 分歧 分歧是声明意图与观察到的行为分道扬镳之处——这是用其他方式最难回答的问题，因为它需要同时具备两个流。示例： ``` [missing-extracted] src/services/prices.ts ──CALLS──▶ folio-api.example.com confidence 0.87 生产环境观察到了此调用，但静态分析从未发现该边。 → 动态分派或覆盖缺口。 [missing-observed] src/db/client.ts ──CONNECTS_TO──▶ postgres:primary confidence 0.85 代码声明了此连接，但没有任何生产流量使用过它。 → 死路径、功能开关或未发布的代码分支。 ``` ## 策略 项目中的 `policy.json` 将架构规则声明为对图的断言——例如“只有 `service:billing` 和 `service:orders` 可以连接到 `postgres:primary`”，或“任何文件都不得调用 `legacy-api.internal`”。NEAT 会在图变化时持续评估每条策略。违规通过 `neat policies`（CLI）和 `check_policies`（面向代理的 MCP 工具）呈现。`block` 动作会阻止新出现的外部主机（`FrontierNode`）被提升，从而避免未经批准的依赖沉淀到模型中。 ## MCP 工具 二十四个 MCP 工具将图暴露给 AI 代理。十四个读取图：`ask`、`get_root_cause`、`get_blast_radius`、`get_dependencies`、`get_observed_dependencies`、`get_incident_history`、`get_incident_card`、`get_divergences`、`get_graph_diff`、`get_recent_stale_edges`、`check_policies`、`semantic_search`、`expand`、`relate`。六个（`neat extend`）为捆绑 OTel 集未覆盖的库填补插桩缺口，由版本化的插桩注册表驱动。四个将托管项目连接到提供商。 ## 服务器部署 容器镜像位于 `ghcr.io/neat-technologies/neat:latest`，启动 `neatd start` 并在 `:8080` 上暴露 REST、在 `:4318` 上暴露 OTLP、在 `:6328` 上暴露 Web UI。每个公共接口都要求 `NEAT_AUTH_TOKEN`；没有它，守护进程拒绝非回环绑定。`neat deploy` 会生成令牌、写入 `docker-compose.neat.yml`，并打印应用程序部署平台的环境变量块： ``` OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-host>:4318 OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <generated-token> ``` 当 TLS 终止和认证已在上游完成时，可通过 `NEAT_AUTH_PROXY=true` 支持反向代理。 ## 代理集成 NEAT 的 MCP 服务器已在官方 MCP Registry 中列为 `io.github.neat-technologies/neat`。Cursor 和 VS Code 提供一键安装按钮。对于 Claude Code： ```bash claude mcp add neat -- neat-mcp ``` 或编辑 `~/.claude/settings.json`： ```json { "mcpServers": { "neat": { "command": "neat-mcp", "env": { "NEAT_CORE_URL": "http://localhost:8080" } } } } ``` `neat hooks --apply` 会安装一个 Claude Code 搜索提示钩子（在原始 grep 之前注入一条提示，引导代理使用 `semantic_search`、`get_dependencies`、`get_divergences`），以及一个与代理无关的 `GRAPH_FIRST.md` 指导块。Claude Code 插件（`claude plugin marketplace add NEAT-Technologies/Neat` 然后 `claude plugin install neat@neat`）将 MCP 工具、钩子和技能打包为一次安装。 ## 仓库布局 ``` packages/ types/ 共享 Zod schema：节点、边、事件、结果类型 core/ 图引擎、tree-sitter 提取、OTel 摄取、REST API、neat CLI mcp/ stdio MCP 服务器，暴露二十四个工具 web/ Next.js 仪表盘 claude-skill/ Claude Code 技能元数据 neat.is/ 伞形包 plugin/ Claude Code 插件（仓库托管） ``` ## 文档 - `docs/guide/`：用户指南——快速开始、核心概念、查询、AI 代理、故障排除 - `PROVENANCE.md`：四种边状态以及置信度如何传递 - `CLAUDE.md`：面向代理和贡献者的指南 - `docs/architecture.md`：包边界和数据流 - `docs/api-reference.md`：REST 端点和 MCP 工具签名 - `docs/runbook.md`：日常命令和恢复方案 - `docs/contracts.md`：每个 PR 都必须遵守的约束规则 - `CONTRIBUTING.md`：分支约定、PR 形态、开发环境设置 - `SECURITY.md`：漏洞报告 ## 许可证 Apache 2.0。