StudyIA-2026/fondamenta-archcode

# Fondamenta ArchCode **零依赖的代码库智能分析工具，专为 AI Agent 和人类设计。** 静态分析 → 结构化 Markdown → 任何 LLM 均可读取。无需图数据库，无需 MCP server，无需云服务。只需将 `.md` 文件提交到您的仓库即可。 ## 为什么选择它？ 每种 AI 编程工具（Claude Code, Cursor, Copilot）都需要理解您的代码库。现有的解决方案通常需要运行服务器或数据库。Fondamenta ArchCode 生成**结构化的 Markdown 文件**，任何 LLM 都可以直接原生读取 —— 无需特殊工具。 ``` npx fondamenta-archcode analyze ``` 就是这样。您的 `.planning/` 目录现在包含了完整的架构分析。 ## 生成内容 ``` .planning/ ├── DEPENDENCY-MAP.md # Architecture overview, impact areas └── dependencies/ ├── pages-atomic.md # Every page: imports, auth, data fetching ├── components-atomic.md # Every component: props, state, hooks, used-by ├── api-routes-atomic.md # Every API route: methods, auth, models ├── lib-atomic.md # Every utility: exports, imports, env vars ├── schema-crossref-atomic.md # DB models, fields, relations, enums └── component-graph.md # Visual dependency tree ``` 每个文件都： - **人类可读** — 在任何编辑器中打开，在任何 PR 中审查 - **AI 可读** — 任何 LLM 原生理解 Markdown - **Grep 友好** — 使用标准工具查找任何内容 - **Git 友好** — 代码更改时产生有意义的差异 ## 快速开始 ``` # 分析当前项目 npx fondamenta-archcode analyze # 分析特定目录 npx fondamenta-archcode analyze ./my-project # 自定义输出目录 npx fondamenta-archcode analyze --output .docs # 初始化配置文件 npx fondamenta-archcode init ``` ## 输出示例 ### pages-atomic.md ``` ### `/dashboard` - **File:** `app/(dashboard)/dashboard/page.tsx` - **Type:** Server Component - **Auth:** auth() - **Data Fetching:** - DB: findMany (courses) - DB: count (flashcards) - **Components:** `CourseCard`, `StatsWidget`, `RecentActivity` - **i18n:** `dashboard` ``` ### api-routes-atomic.md ``` ### `/api/courses` - **File:** `app/api/courses/route.ts` - **Methods:** `GET`, `POST` - **Auth:** auth() - **Models:** `course`, `enrollment` - **Side Effects:** DB: findMany, DB: create ``` ### schema-crossref-atomic.md ``` ### `User` | Field | Type | Constraints | | --- | --- | --- | | `id` | `String` | primary key, @default(cuid()) | | `email` | `String` | unique | | `name` | `String` | optional | | `courses` | `Course` | array | **Relations:** - `courses` → `Course` (one-to-many) - `flashcards` → `Flashcard` (one-to-many) ``` ## 配置 创建 `fondamenta.config.ts`（或运行 `npx fondamenta-archcode init`）： ``` import { defineConfig } from 'fondamenta'; export default defineConfig({ output: '.planning', framework: 'auto', // 'nextjs-app' | 'nextjs-pages' | 'nuxt' | 'sveltekit' | 'remix' language: 'en', generators: { pages: true, components: true, apiRoutes: true, lib: true, schemaXref: true, componentGraph: true, dependencyMap: true, }, exclude: ['**/node_modules/**', '**/*.test.*'], schema: { provider: 'auto', // 'prisma' | 'drizzle' | 'none' }, }); ``` ## 支持的框架 | 框架 | 状态 | |-----------|--------| | Next.js App Router | 支持 | | Next.js Pages Router | 支持（基础）| | Nuxt 3 | 计划中 | | SvelteKit | 计划中 | | Remix | 计划中 | ## 工作原理 1. **发现** 使用 `fast-glob` 发现文件（遵循 `.gitignore`） 2. **解析** 使用 TypeScript Compiler API 解析 TypeScript/TSX（非正则表达式） 3. **构建** 在内存中构建导入、导出、组件、hooks 的关系图 4. **分类** 对每个文件进行分类：page, component, API route, lib, hook 5. **分析** 分析 Prisma schema 中的模型、字段和关系 6. **生成** 生成格式一致的结构化 Markdown 分析后零运行时依赖 —— 输出为纯 Markdown。 ## 与替代方案对比 | | Fondamenta ArchCode | GitNexus | Repomix | |---|---|---|---| | **输出** | 结构化 .md 文件 | Graph DB (KuzuDB) | 单个拼接文件 | | **运行时依赖** | 无 | KuzuDB + MCP server | 无 | | **AI 集成** | 任何工具（读取文件）| 仅 Claude Code (MCP) | 任何工具 | | **框架感知** | 是（路由、页面、认证）| 仅 AST | 否 | | **Schema 感知** | 是 | 否 | 否 | | **人类可读性** | 优秀 | 需要查询 | 差（文本墙）| | **Git 友好度** | 是（有意义的差异）| 否（二进制 DB）| 差（单文件）| | **增量更新** | 是（watch + diff）| 重新索引 | 否 | ## 命令 | 命令 | 描述 | |---------|-------------| | `fondamenta analyze [path]` | 完整代码库分析 → Markdown 文件 | | `fondamenta analyze --incremental` | 仅分析 git 变更的文件 | | `fondamenta analyze --no-preserve-manual` | 跳过手动章节保留 | | `fondamenta agents [path]` | 在项目图上运行代码健康 agents | | `fondamenta agents --json` | 输出 JSON 格式的发现（用于 CI/工具）| | `fondamenta diff [path]` | 显示自上次分析以来的更改 | | `fondamenta watch [path]` | 监视模式 —— 文件更改时重新生成 | | `fondamenta ai-context [path]` | 生成 AI 上下文文件 | | `fondamenta init` | 创建配置文件 | ### `fondamenta agents` 运行 8 个代码健康 agents（3 个免费，5 个 PRO），分析您的项目图并产生可执行的发现。 ``` fondamenta agents # All available agents fondamenta agents --free # Free agents only fondamenta agents --agent dead-code # Single agent fondamenta agents --ci # Exit code 1 if errors found fondamenta agents --report # Generate AGENTS-REPORT.md fondamenta agents --list # List all agents with tier ``` **免费 agents：** | Agent | 检查内容 | |-------|---------------| | `dead-code` | 孤立组件、未使用的导出、未引用的 lib 文件 | | `circular-deps` | 循环导入链（DFS 环检测）| | `architecture-guard` | 过大文件、God 组件、未受保护的 mutation 路由 | **PRO agents**（需要许可证）： | Agent | 检查内容 | |-------|---------------| | `security-scanner` | 认证缺口、环境变量泄露、不安全模式 | | `schema-drift` | 代码↔schema 模型不匹配 | | `performance-sentinel` | 重型页面、不必要的客户端组件、API 瀑布流 | | `convention-enforcer` | 命名、Barrel exports、认证模式一致性 | | `impact-analyzer` | 扇入/扇出热点、枢纽组件、桥接文件 | ### `fondamenta diff` ``` fondamenta diff # Show what changed fondamenta diff --ci # Exit code 1 if outdated (for CI) ``` ### `fondamenta watch` ``` fondamenta watch # Watch and regenerate on changes fondamenta watch --debounce 1000 # Custom debounce (ms) ``` ### `fondamenta ai-context` ``` fondamenta ai-context --claude # Generate/update CLAUDE.md fondamenta ai-context --cursor # Generate .cursorrules fondamenta ai-context --copilot # Generate .github/copilot-instructions.md fondamenta ai-context --all # All of the above ``` ## 手动章节 Fondamenta 在重新生成期间保留人类编写的内容。使用标记添加手动章节： ``` Your custom notes here — they survive `fondamenta analyze` ``` 或使用分割点模式 —— `## Manual Notes` 之后的所有内容都会被保留： ``` ## /dashboard (auto-generated content above) ## 手动笔记 Your custom architecture notes here — preserved across regeneration. ``` 使用 `--no-preserve-manual` 禁用。 ## 增量模式 仅重新生成自上次提交以来更改的文件的文档： ``` fondamenta analyze --incremental ``` 使用 `git diff` 检测更改的 `.ts`/`.tsx`/`.vue` 文件，并跳过未更改的文件。结合 `writeIfChanged`（始终激活），只有实际内容发生变化的文件才会被写入磁盘 —— git diff 中零噪音。 ## 自动化 ### Cron（推荐用于服务器） ``` # 每 6 小时重新生成 30 */6 * * * cd /path/to/project && fondamenta analyze > /dev/null 2>&1 ``` ### Git pre-commit hook ``` # .git/hooks/pre-commit fondamenta analyze git add .planning/ ``` ### GitHub Action ``` - name: Update architecture docs run: npx fondamenta-archcode analyze - name: Commit changes run: | git add .planning/ git diff --staged --quiet || git commit -m "docs: update fondamenta analysis" ``` ## 路线图 - [x] CLI `analyze` 命令 - [x] Next.js App Router 支持 - [x] Prisma schema 分析 - [x] 7 个原子生成器 + 依赖图 - [x] `fondamenta watch`（增量重建） - [x] `fondamenta diff`（显示自上次分析以来的变化） - [x] AI 上下文生成（`.cursorrules`, `CLAUDE.md`, copilot 指令） - [x] 代码健康 agents（8 个 agents：死代码、循环依赖、安全、性能等） - [x] 开源核心许可（3 个免费 + 5 个 PRO） - [x] 手动章节保留（基于标记 + 分割点） - [x] 增量模式（通过 git diff 的 `--incremental`） - [x] writeIfChanged（零噪音 git diff） - [x] 测试套件（120+ 测试，使用 GitHub Actions 进行 CI） - [ ] GitHub Action（marketplace） - [ ] 多框架支持 - [ ] Ed25519 许可证验证（从 HMAC 升级） ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ## 许可证 MIT

标签：AI编码助手, Codebase Intelligence, LLM上下文, Markdown生成, MITM代理, RAG增强, 代码健康, 代码可视化, 代码库智能, 依赖图分析, 威胁情报, 安全专业人员, 开发者工具, 技术文档自动化, 架构文档生成, 自动化攻击, 软件架构, 错误基检测, 防御加固, 零依赖, 静态代码分析