napi - Better Software Architecture for the AI Age

napi - AI 时代的更优软件架构

napi 是一款完全离线的 CLI，可分析代码库的架构——包括依赖关系、复杂度和结构——然后让你可视化并重构代码，全程不会将代码发送到任何地方。

它会根据源代码生成依赖清单，将其保存在本地，并直接通过 CLI 提供交互式图形可视化工具。

功能

• 🔍 依赖分析：自动绘制代码库中每个文件、符号和依赖关系的映射。
• 🚨 审计：检测复杂度、大小或耦合度超出阈值的文件和符号。
• 📊 交互式可视化工具：通过在浏览器中本地提供的 Cytoscape.js 图形探索架构。
• 📝 符号提取：将指定的函数、类或符号提取到独立文件中，以便重构。
• 🏷️ AI 标注（可选）：使用 OpenAI、Google 或 Anthropic 模型自动标注依赖项。
• ⚙️ 支持 CI/CD：可集成到任何流水线中——每次推送时生成清单并跟踪架构变化。
• 🔒 完全离线：无需账户或服务，不会有任何数据离开你的设备。

支持的语言

语言	状态
Python	✅ 支持
C#	✅ 支持
C	✅ 支持
Java	✅ 支持
C++	🚧 开发中
PHP	🚧 开发中
JS/TS	🚧 开发中

安装

Unix（macOS、Linux）

curl -fsSL https://raw.githubusercontent.com/nanoapi-io/napi/refs/heads/main/install_scripts/install.sh | bash

也可以直接从 GitHub Releases 下载二进制文件。

Windows

使用 WSL 运行 napi。 原生 Windows 支持正在开发中。

快速开始

# 1. Initialize your project (creates .napirc)
napi init

# 2. Generate a dependency manifest
napi generate

# 3. Open the visualizer in your browser
napi view

就这样。清单已保存在本地的 .napi/manifests/ 中，可视化工具会在 http://localhost:3000 打开。

CLI 命令

napi init

交互式设置，会在项目根目录中创建 .napirc 配置文件。

它会提示你输入：

• 语言 —— Python、C#、C 或 Java
• 包含/排除模式 —— 要分析哪些文件
• 输出目录 —— 提取的符号写入的位置
• AI 标注（可选）——提供方和并发设置

napi init

napi generate

分析代码库并生成依赖清单。清单会记录每个文件、符号、依赖项和指标（行数、复杂度、耦合度）。

清单以 JSON 文件形式保存在 .napi/manifests/ 中，命名格式为 {timestamp}-{commitSha}.json。

# Interactive (prompts for branch/commit if not in git)
napi generate

# Non-interactive (for CI)
napi generate --branch main --commit-sha abc1234 --commit-sha-date 2026-01-01T00:00:00Z

选项：

• --branch —— Git 分支名称（省略时自动检测）
• --commit-sha —— Git 提交哈希（省略时自动检测）
• --commit-sha-date —— ISO 8601 格式的提交日期（省略时自动检测）
• --labelingApiKey —— 用于 AI 标注的 API 密钥（覆盖全局配置）

napi view

启动本地 Web 服务，并在浏览器中打开交互式依赖可视化工具。

napi view
napi view --port 8080

查看器提供：

• 清单列表 —— 按分支、提交和日期浏览所有本地存储的清单
• 项目图形 —— 使用 Cytoscape.js 展示文件级依赖关系图
• 文件图形 —— 查看文件内的符号级视图（函数、类、变量）
• 符号图形 —— 查看特定符号的传递依赖链
• 文件浏览器侧边栏 —— 浏览代码库结构
• 审计警报 —— 以可视化标记提示超出阈值的文件/符号

napi extract

使用本地清单，将代码库中的指定符号提取到单独的文件中。

# Extract a function from a specific file
napi extract --symbol "src/auth/login.py|authenticate"

# Extract multiple symbols
napi extract --symbol "src/models.py|User" --symbol "src/models.py|Session"

# Use a specific manifest (defaults to latest)
napi extract --symbol "src/main.py|run" --manifestId 1712500000000-a1b2c3d

输出写入 {outDir}/extracted-{timestamp}/。

napi set apiKey

配置用于 AI 驱动依赖标注的 API 密钥。密钥存储在全局配置中（而非项目中）。

napi set apiKey

它会提示你输入：

• 提供方 —— Google、OpenAI 或 Anthropic
• API 密钥 —— 你的提供方 API 密钥

本地清单存储

所有清单都存储在相对于项目根目录的 .napi/manifests/ 中。 每个清单都是一个独立的 JSON 文件：

{
  "id": "1712500000000-a1b2c3d",
  "branch": "main",
  "commitSha": "a1b2c3d4e5f6...",
  "commitShaDate": "2026-04-07T10:00:00Z",
  "createdAt": "2026-04-07T10:01:00Z",
  "manifest": {}
}

你可以将 .napi/ 添加到 .gitignore，也可以将其提交到版本控制中以追踪架构历史——由你决定。

CI/CD 集成

在每次推送时自动生成清单：

# .github/workflows/napi.yml
name: Generate Manifest
on: [push]
jobs:
  manifest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install napi
        run: curl -fsSL https://raw.githubusercontent.com/nanoapi-io/napi/refs/heads/main/install_scripts/install.sh | bash

      - name: Generate manifest
        run: napi generate --branch ${{ github.ref_name }} --commit-sha ${{ github.sha }} --commit-sha-date "$(git log -1 --format=%cI)"

配置参考

.napirc

由 napi init 创建的项目级配置：

{
  "language": "python",
  "python": { "version": "3.10" },
  "project": {
    "include": ["src/**/*.py"],
    "exclude": [".git/**", "**/__pycache__/**", "napi_out/**"]
  },
  "outDir": "napi_out",
  "labeling": {
    "modelProvider": "openai",
    "maxConcurrency": 5
  }
}

全局配置

存储在操作系统的配置目录中（Linux 上为 ~/.config/napi/config.json，macOS 上为 ~/Library/Application Support/napi/config.json）。通过 napi set apiKey 管理。

{
  "labeling": {
    "apiKeys": {
      "openai": "sk-...",
      "google": "AIza...",
      "anthropic": "sk-ant-..."
    }
  }
}

开发

需要 Deno v2.4+。

# Install dependencies
deno install --allow-scripts

# Run CLI in dev mode
deno task dev

# Run viewer dev server (hot-reload)
deno task dev:viewer

# Build viewer for production
deno task build:viewer

# Compile binary (includes viewer)
deno task compile

# Run tests
deno task test

# Lint
deno lint

# Format
deno fmt

贡献

我们欢迎社区贡献。请阅读我们的 贡献指南 ，了解如何参与。

许可证

napi 根据 Sustainable Use License 授权。

延伸阅读

• 使用微型单体开发自动化绞杀者模式
• “微型单体”的兴起：为现代开发者重新思考微服务

捐赠

NanoAPI 是一个公平源码项目。因此，我们认为将任何捐赠据为己有是不道德的。我们将按以下方式处理捐赠：

• 捐赠将汇入资金池
• 资金池中的款项将分配给贡献者
• 年末，任何剩余款项都将捐赠给社区选定的慈善机构

我们会定期发布更新，说明资金池中的金额以及款项的分配情况。