Flutter Project Structure

Flutter 项目结构

理解代码库所需的上下文减少 90%。 只需一条命令，就能让每个 AI Agent——Claude Code、Cursor、Copilot——全面了解项目结构：每个文件提供什么、文件之间如何关联，以及修改某个文件会造成什么影响。以下数据来自真实应用，而非估算。

这是一个让 Flutter/Dart 代码库适配 AI 的 Dart 包。它可以分析、记录并可视化项目结构，还能生成上下文文件，取代耗时的“让我先读读你的代码库”阶段。

为什么？（上下文问题）

在 Agent 能为你的代码库编写任何有用内容之前，它必须回答三个问题：

1. 这是个什么项目？——技术栈、架构、约定、入口点
2. 哪些文件与这项任务有关？——还有哪些文件依赖它们
3. 这些文件提供什么？——它需要调用的类和方法

通过阅读源码来回答这些问题成本很高，而且每次会话都得从头开始。breeze_buy_app 是一个真实的 Flutter 应用，包含 170 个文件，Dart 代码有 670 KB——从头到尾阅读约需 171,000 个 token。没有哪个 Agent 会通读全部代码，因此它只能在上下文不足的情况下逐个打开文件，直到信息够用，第二天又要重新付出同样的代价。

你能得到什么

运行一次：dart run flutter_project_structure ai-context

产物	解答的问题	在 breeze_buy_app 上测得的数据
CLAUDE.md	这是个什么项目？	2.6 KB（约 670 个 token），由 Claude Code 自动加载
.ai-context/graph.json	哪些文件有关，修改某个文件会造成什么影响	170 个文件之间有 777 条边
.ai-context/skeletons.json	每个文件提供什么	63 KB，而源码有 670 KB——小了 90.6%

该应用的完整结构信息约为 17,000 个 token，而通读源码则需要约 171,000 个 token。90% 的缩减率由此而来；你可以在自己的项目上运行此工具，复现这一结果——压缩率会记录在 skeletons.json 中。

骨架示例

lib/core/utils/http_base_interceptor.dart
  class BaseInterceptor extends Interceptor  // base [Interceptor] for [Dio]...
    @override void onRequest(RequestOptions options, RequestInterceptorHandler handler)
    @override void onResponse(Response response, ResponseInterceptorHandler handler)
    @override Future onError(DioException err, ErrorInterceptorHandler handler)
  class RefreshToken
    final String access;
    RefreshToken({required this.access})

这些信息足以让你正确调用该文件，而无需打开它。只有在需要修改时，才阅读文件本身。

图表还能告诉你修改会带来什么影响

get_file_graph(path: "lib/config/colors.dart")
  importedBy   : 108 files
  blastRadius  : 134 of 170 files

此工具的功能与局限

这一区别很重要，下面直说。

**它能做的是：**让 Agent 全面了解整个项目的结构和接口，包括每个文件、每个公共 API、每条依赖关系，所需成本约为阅读源代码的十分之一。它能让 Agent 不必猜测该打开哪些文件，也不必在每次会话中重新推导项目架构。

**它不能做的是：**告诉 Agent 代码具体做什么。行为体现在方法体中，而骨架定义上会移除方法体。对于服务、模型、Bloc 和仓库，这种方式效果最好，因为接口确实承载了大部分含义。对于 Flutter 组件，效果最弱，因为其含义体现在 build() 方法体中，骨架更像目录，而非摘要。

它也不会缩短整个会话。编写代码、运行测试和反复迭代都不受影响，而在真实任务中，这些通常比上下文更耗时。这个包消除的是你反复付费、却没有任何新收获的那部分成本。

功能

核心分析

• 以 Markdown 可视化目录树
• 在每个 Dart 文件顶部添加路径注释（// Path: lib/src/...）——这对基于 RAG 的工具最有用，因为这类工具会将文件分块建立索引，导致路径丢失；Claude Code 这类 Agent 工具已会在每条结果中附带路径
• 文件统计信息（文件总数、代码行数、最大／最小文件）
• 扫描 TODO/FIXME 注释并标出行号
• 包依赖分析（基于 AST 的导入跟踪）
• 每个文件的代码指标（类、方法、注释比例）

骨架（v3.0.0）

• API 骨架——保留每个声明并移除其方法体；在一个包含 170 个文件的真实应用中，比源代码小 90.6%
• 文档摘要——保留作者对每个声明所写的一行描述，并与签名一同呈现
• 让 Agent 能在上下文中掌握整个项目的结构，只为实际需要编辑的文件读取完整方法体
• 对服务、模型、Bloc 和仓库的效果最好；对于 Flutter 组件，其含义体现在 build() 方法体中，因此骨架更像目录，而非摘要

导入关系图（v3.0.0）

• 文件依赖图——节点为文件，边为在项目内部解析的 import、export 和 part 指令（包括 package:<own_name>/... 形式的自导入）
• 影响范围——修改任一文件可能影响的传递性文件集合，让你在编辑前知道要检查哪些内容
• 正向闭包——某个文件正常运行所需的一切
• 死代码候选项——无法从任何入口点到达的文件
• 枢纽文件——被依赖最多的文件，也就是修改风险最高的文件

智能检测（v3.0.0）

• 项目类型——monorepo、plugin、flutter_app 或 dart_package
• 10 种框架——GetX、Riverpod、Bloc/Cubit、Provider、Dio、GoRouter、AutoRoute、Freezed、Hive、Drift（通过 pubspec、导入和 AST 超类匹配进行检测）
• 架构分层——将目录映射到各层（models、services、controllers、widgets、blocs 等），并生成依赖关系图
• 入口点——检测 main.dart、app.dart 以及 main_development.dart、main_staging.dart、main_production.dart 等环境变体
• 命名约定——文件后缀模式（_model、_service、_bloc）和类后缀模式（Model、Service、Bloc）
• 文件用途分类——为每个文件标注角色：组件、模型、服务、Bloc、测试、生成文件、工具类等
• 聚合指标——平均值、总数、最大的 5 个文件、没有注释的文件

AI 输出生成器

• CLAUDE.md——面向 AI 优化的项目摘要（<20KB），包含概览、架构、约定、依赖和代码健康状况
• .ai-context/——8 个 JSON 文件：architecture.json、files.json、patterns.json、conventions.json、metrics.json、todos.json、graph.json、skeletons.json
• MCP 服务——通过 stdio JSON-RPC 提供 8 个实时查询工具，并支持可选的 --watch 模式

单次扫描架构

• FileAnalyzer 接口 — 每个文件只读取和解析一次，然后分发给所有分析器
• AnalysisPipeline — 协调单次扫描处理（比逐个分析器扫描快 3 倍）
• ProjectContext — 将所有分析结果存放在一个数据类中，供生成器和 MCP 工具使用

安装

添加到你的 pubspec.yaml：

dev_dependencies:
  flutter_project_structure: ^3.0.0

然后运行：

dart pub get

CLI 用法

快速开始

# Analyze your project — generates project_structure.md with path comments
dart run flutter_project_structure

# Full AI setup — project_structure.md + CLAUDE.md + .ai-context/ JSON files
dart run flutter_project_structure ai-context

# Start MCP server for live AI agent queries
dart run flutter_project_structure mcp-server --watch

命令

每个命令都会生成路径注释和作为基准的 project_structure.md，然后添加各自特有的输出。

analyze（默认）

核心命令。生成包含目录树和所有分析部分的 project_structure.md。为每个 Dart 文件添加 // Path: 注释。

dart run flutter_project_structure
dart run flutter_project_structure analyze --root-dir=lib --output=structure.md

为保持向后兼容，不带子命令运行时默认执行 analyze。

claude-md

生成 CLAUDE.md — 精简、针对 AI 优化的项目上下文文件（<20KB）。Claude Code 等 AI Agent 会在每次会话开始时自动读取此文件。

dart run flutter_project_structure claude-md
dart run flutter_project_structure claude-md --output=AI_CONTEXT.md

还会生成：路径注释 + project_structure.md。

ai-context

内容最全面的命令。生成所有内容：project_structure.md、CLAUDE.md，以及 .ai-context/ 中的 8 个结构化 JSON 文件。

dart run flutter_project_structure ai-context
dart run flutter_project_structure ai-context --output-dir=.ai-context

生成的 JSON 文件：

• architecture.json — 项目类型、分层、依赖图、入口点
• files.json — 每个文件的用途、LOC、类、方法、注释比例
• patterns.json — 检测到的框架及其文件依据
• conventions.json — 命名后缀计数和文件用途分布
• metrics.json — 汇总的代码健康度指标
• todos.json — 结构化的 TODO/FIXME 索引

还会生成：路径注释 + project_structure.md + CLAUDE.md。

mcp-server

启动 MCP 服务，以便 AI Agent 实时查询。服务会在启动时分析你的项目，并可选择监视文件更改。

dart run flutter_project_structure mcp-server
dart run flutter_project_structure mcp-server --watch

使用 --watch 时，.dart 文件发生更改后，服务会重新分析（防抖间隔为 2 秒）。启动时还会生成路径注释 + project_structure.md。

提供 8 个 MCP 工具：

工具	描述
get_architecture	项目类型、分层、依赖图、入口点
get_file_purpose(path)	特定文件的用途和指标
get_dependencies(package?)	软件包依赖，可选择按条件筛选
get_conventions	命名模式和后缀采用率
get_todos(severity?)	TODO/FIXME 项，可选择按条件筛选
get_file_skeleton(path?, paths?)	文件声明（不含主体）——大小约为读取完整文件的 10%。用于了解如何调用文件；如需修改文件，请读取文件
get_file_graph(path?, depth?)	文件依赖图。不带参数：显示大小、被依赖最多的文件、不可达文件。带 path：显示其导入的内容、导入它的内容，以及其影响范围
get_project_structure(section?)	完整的项目结构 Markdown — 默认返回摘要，也可返回特定部分（目录树、框架、架构等）

在 Claude Code 中配置：

{
  "mcpServers": {
    "flutter-project-structure": {
      "command": "dart",
      "args": ["run", "flutter_project_structure", "mcp-server", "--watch"]
    }
  }
}

选项

Analyze 命令标志（默认全部启用）：

标志	简写	描述
--root-dir	-r	要分析的根目录（默认：lib）
--output	-o	输出文件路径（默认：项目根目录中的 project_structure.md）
--file-stats	-f	文件/行数统计
--todo-comments	-t	扫描 TODO/FIXME
--dependency-analysis	-d	跟踪软件包导入
--code-metrics	-m	类、方法、注释比例
--project-type		项目类型检测
--framework-detection		框架/库检测
--architecture		分层和依赖分析
--conventions		命名约定分析
--file-purpose		文件角色分类
--metrics-aggregation		汇总健康度指标

使用 --no-<flag> 禁用任意功能（例如，--no-framework-detection）。

编程方式使用

带路径注释的完整分析

import 'package:flutter_project_structure/flutter_project_structure.dart';

void main() {
  // Omit outputFile to write project_structure.md to the project root
  // (next to pubspec.yaml). Pass one to choose your own path.
  final structure = FlutterProjectStructure(rootDir: 'lib');

  // generate() injects path comments, writes project_structure.md,
  // and returns a ProjectContext for further use
  final context = structure.generate();
  if (context == null) return;

  print('Written to: ${structure.outputFilePath}');
  print('Project type: ${context.projectTypeDetector?.projectType}');
  print('Total files: ${context.fileStatistics.totalFiles}');
  print('Frameworks: ${context.frameworkDetector?.detectedFrameworks.keys}');

  // Generators default to the project root too, and return the path written
  print(ClaudeMdGenerator(context).generate());
  print(AiContextGenerator(context).generate());
}

输出位置遵循一条规则：省略标志时，输出会写入项目根目录（与 pubspec.yaml 放在一起），因此输出会留在你分析的项目中，而不是你恰好运行命令的目录。传入明确的路径后，程序会按原样使用该路径，并像其他 CLI 工具一样相对于当前目录解析。

只读分析（不修改文件）

final structure = FlutterProjectStructure(rootDir: 'lib');
final context = structure.runAnalysis();
// Or get the markdown string without writing to disk:
final markdown = structure.generateMarkdown();

架构

AnalysisPipeline (reads & parses each file once)
  |-- FileStatistics        -- file/line counts, largest/smallest files
  |-- TodoComments          -- TODO/FIXME scanning
  |-- DependencyAnalysis    -- package import mapping (AST-based)
  |-- CodeMetrics           -- classes, methods, comment ratio (AST-based)
  |-- FrameworkDetector     -- framework detection (pubspec + imports + AST)
  |-- ArchitectureAnalyzer  -- layers, entry points, dependency graph
  |-- ConventionAnalyzer    -- file/class naming patterns
  |-- FilePurposeAnalyzer   -- file role classification

Every command produces (baseline):
  |-- Path comments         -- // Path: lib/src/... in every Dart file
  |-- project_structure.md  -- comprehensive directory tree + all analysis

Output Generators (added on top):
  |-- ClaudeMdGenerator     -- CLAUDE.md for AI agents (<20KB)
  |-- AiContextGenerator    -- .ai-context/ (8 JSON files)
  |-- McpProjectServer      -- MCP server with 8 live-query tools

所有分析器都实现了 FileAnalyzer 接口。你可以构建自定义分析器：

import 'dart:io';
import 'package:analyzer/dart/ast/ast.dart';
import 'package:flutter_project_structure/flutter_project_structure.dart';

class MyCustomAnalyzer implements FileAnalyzer {
  @override
  void analyzeFile(File file, String content, CompilationUnit? compilationUnit) {
    // Your analysis logic here — receives pre-parsed AST
  }
}

示例

查看 example 文件夹，了解完整的用法示例：

dart run example/main.dart

参与贡献

欢迎参与贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

支持本项目

如果你觉得这个软件包很有用，可以考虑在 pub.dev 上为它点赞。

联系我

• LinkedIn：LinkedIn 个人主页
• GitHub：GitHub 个人主页

聘用我或联系我的组织

自由职业或大型项目合作：

• Upwork 个人主页：个人主页
• Upwork 机构主页：机构主页

如需开展大型开发项目或洽谈潜在合作，请发送电子邮件至：[email protected]

成功案例

我很荣幸能为多个项目的成功做出贡献。以下是其中一个亮点：

Abwaab.com

Abwaab 是 MENA 地区顶尖的 EdTech 平台之一。我在开发稳健且可扩展的解决方案方面发挥了重要作用，助力 Abwaab 实现其使命，让数百万学生能够获得优质教育。

访问 Abwaab

我的组织

Increments Inc.

我们的软件为餐厅实现自动化、优化能源、革新金融、改善医疗保健、创新教育、简化服装行业流程，并推动无纸化解决方案。 Increments Inc. 是孟加拉国排名第 1 的移动应用开发机构。

访问 Increments Inc.

---

感谢你查看 Flutter Project Structure！希望它能为你的开发工作流带来帮助。祝编码愉快！