infrawise

用途

Infrawise 为 AI 编程助手提供确定性的基础设施感知能力。AI 助手能读取源码，但无法确定性地了解基础设施：不知道存在哪些 GSI、表如何分区、哪些函数已触发扫描、哪里缺少索引，因此只能猜测。Infrawise 通过静态分析代码库、云基础设施和数据库模式，将上下文通过 MCP 暴露给 Claude Code 等工具，用基础设施感知的上下文替代猜测。

它本身不是 AI 智能体框架、基础设施配置工具、可观测性平台或云管理仪表盘，而是面向 AI 辅助开发的确定性基础设施智能层。

主要能力

Infrawise 包含两层分析：

基础设施分析（所有语言）：基于 AWS API、数据库模式内省和 IaC 文件，不依赖应用代码。

代码关联分析（TypeScript / JavaScript / Python）：使用 ts-morph AST 分析检测哪些函数调用哪些表以及如何调用。Python 仓库使用内置的 stdlib-ast 扫描器（需要 PATH 中有 python3，否则跳过并警告），支持 boto3 客户端和 dynamodb.Table() 资源、cursor.execute SQL、pymongo 集合、kafka-python/confluent-kafka 生产者和消费者。语言检测自动进行，TypeScript 和 Python 扫描仅在存在匹配文件时运行。

扫描器支持：DynamoDB 的 AWS SDK v3/v2、PostgreSQL 的 pg/Prisma/Knex、MySQL 的 mysql2/Knex、MongoDB 的 driver/Mongoose、SQS/SNS/SSM/Secrets/Lambda 的 AWS SDK v3、Kafka 主题的 kafkajs（生产者/消费者）。

工作流程：扫描仓库和基础设施元数据 → 图引擎映射服务、模式、索引和查询模式 → 基于规则的分析器检测基础设施和查询反模式 → 通过 MCP 暴露上下文 → AI 编程助手在生成代码时查询该上下文。

使用方式

需要 Node.js 22 或更高版本。

首次运行 infrawise start 会：探测环境并生成 infrawise.yaml（仅首次，若有多个 AWS 配置文件会询问使用哪个）；扫描 AWS 服务、数据库和代码库；写入 .mcp.json 使编辑器在后续启动时自动连接；打开 Claude Code 并准备好全部 22 个 MCP 工具。

之后每次分析缓存 24 小时。缓存过期时，编辑器自动启动的 infrawise serve --stdio 会在会话开始时刷新。会话内检测文件变更并自动更新代码图。

与 AI 编程助手配合：

• Claude Code（推荐）：写入项目根目录的 .mcp.json（与已有 MCP 服务器合并）并打开 Claude Code。也可作为 Claude Code 插件安装，注册相同的 MCP 服务器，仍需项目中的 infrawise.yaml。
• Cursor：写入 .cursor/mcp.json 并打开 Cursor，22 个工具在 MCP 面板中可用。
• VS Code：写入 .vscode/mcp.json 并打开 VS Code，工具通过 MCP 服务器面板对 Copilot 智能体模式可用。
• 任意编辑器（无标志）：写入 .mcp.json 后退出，将编辑器指向 infrawise serve --stdio --config /path/to/infrawise.yaml 作为 MCP 服务器命令。
• HTTP 传输（替代方案）：若编辑器或工作流需要 HTTP MCP 端点而非 stdio，可添加到编辑器的 MCP 配置中。

每个工具都标注为只读（readOnlyHint: true, openWorldHint: false），遵循注解的 MCP 客户端可无需确认提示直接调用。

每个响应都带有固定结构的 dataHealth 块：基础设施读取时间及距今多久、该答案背后每个源的状态、cdk.out 此后是否已 synth、以及刷新命令。每个键始终存在，无需从字段缺失推断。

Infrawise 只报告，不裁决。当问题具有时间点性质时，可传入 maxAgeSeconds，答案会告知数据是否满足该要求（建议性——数据仍会返回并标记）。运行中的服务器在每次工具调用时重新检查缓存，打开的会话可在下次提问时获取新的 infrawise analyze 结果，无需重启。

命令选项：

• infrawise analyze：分析选项。
• infrawise check（CI/CD）：运行全新分析，存在阻塞性发现时设置非零退出码，可在没有 AI 编辑器的情况下门控流水线。
• infrawise serve：服务选项。

infrawise.yaml 由 infrawise start（或 infrawise start --interactive 引导向导）生成，位于仓库根目录。每个服务必须显式 enabled: true——infrawise 从不连接配置中未列出的任何内容。连接字符串支持 ${ENV_VAR} 替换，密码无需提交。

Infrawise 是只读的。DynamoDB 的最小 IAM 策略见文档。SSO 配置文件需先登录再运行 infrawise。PostgreSQL 设置（可选）：创建只读用户；Amazon RDS 需在安全组中允许来自本机 IP 的 5432 端口入站。

适用场景

• 让 AI 编程助手在生成代码时了解真实的表结构、分区键、排序键和 GSI，避免建议已存在的索引或对 5000 万行表使用 .scan()。
• 检测 IaC 漂移、缺失索引、安全缺口和性能反模式。
• 在 CI/CD 中通过 infrawise check 门控流水线。
• 两个演示可在 Docker 中本地模拟真实 AWS API，零成本且无需真实 AWS 账户：demo/floci/ 使用 Floci（MIT 许可，覆盖 infrawise 支持的所有服务，包括 CloudFront、API Gateway v2、RDS、Cognito、Kinesis、ElastiCache 和 MSK，无需认证令牌或注册）；demo/localstack/ 使用 LocalStack 社区版，覆盖核心服务。两者都监听 4566 端口，需一次运行一个。

限制

• 代码级关联支持 TypeScript、JavaScript 和 Python（Python 需要 PATH 中有 python3）。
• 动态构造的查询可能无法总是被静态解析。
• 尚未实现运行时追踪。
• 大型 monorepo 可能需要未来的增量分析优化。
• 其他语言的项目仍可从基础设施级分析器获得完整价值，但代码关联（函数到表映射、N+1 模式）目前仅支持 TypeScript、JavaScript 和 Python。

安全与设计

• 确定性分析：不使用 LLM 分析基础设施，所有提取和分析都是确定性的（AST 解析、模式内省、基于规则的分析器、图关联）。LLM 仅通过 MCP 消费生成的上下文。
• 只读：从不写入 AWS 或数据库，从不执行 DDL。
• 本地优先：一切在本机运行，不发送到外部服务器。
• 无遥测：零数据收集。
• 凭据：使用现有 AWS 凭据链，infrawise 从不存储。

注意：某些供应链安全扫描器可能因 "infra" 前缀将此包标记为 "欺骗性命名"，这是自动化工具触发的误报。该项目完全安全、独立，与任何商业商标无关。