AI 驱动的发现 - Archyl Docs

了解 Archyl 如何使用 AI 从您的代码库中自动发现和记录架构

AI 驱动的发现

Archyl 的 AI 发现功能分析您的代码库，自动发现和记录您的软件架构。这节省了大量手动文档工作，并确保架构文档与实际代码保持同步。

工作原理

1. 连接您的仓库

首先，将您的 Git 仓库连接到 Archyl：

  1. 前往项目设置
  2. 点击"连接仓库"
  3. 选择您的 Git 提供商（GitHub、GitLab、Bitbucket 等）
  4. 授权 Archyl 访问您的仓库

2. 开始发现

连接后，启动 AI 发现：

  1. 在项目中点击"开始发现"
  2. 选择要分析的分支或路径
  3. 配置发现设置（可选）
  4. 点击"运行发现"

3. AI 分析

AI 分析您的代码库以识别：

  • 项目结构：框架、语言、构建系统
  • 服务：微服务、API、后台工作进程
  • 数据存储：数据库、缓存、文件存储
  • 外部集成：第三方 API、SaaS 服务
  • 组件：模块、包、关键类
  • 关系：组件之间如何通信

4. 审查与批准

发现的内容会以"待处理"状态等待审查：

  1. 审查每个发现的元素
  2. 编辑名称、描述或关系
  3. 批准准确的发现
  4. 拒绝或修改不正确的发现

支持的技术

AI 发现最适合以下技术：

编程语言

  • JavaScript/TypeScript
  • Python
  • Go
  • Java
  • C#
  • Ruby
  • PHP
  • Rust

框架

  • React、Next.js、Vue、Angular
  • Express、Fastify、NestJS
  • Django、Flask、FastAPI
  • Spring Boot
  • ASP.NET Core
  • Ruby on Rails

基础设施

  • Docker/Kubernetes
  • Terraform
  • AWS CDK
  • 云配置文件

增量发现

增量发现通过仅分析变更的文件来保持 C4 模型的最新状态——而不是整个仓库。这更快、成本更低，并且可以在每次推送时自动运行。

工作原理

  1. 代码被推送到默认分支
  2. Archyl 接收推送事件（通过 Webhook 或 GitHub Action）
  3. 从提交中提取变更的文件
  4. 仅分析源文件（删除的文件被跳过）
  5. AI 在较小的文件集上运行
  6. 新元素作为待处理的发现被创建
  7. 现有元素自动去重

启用增量发现

有两种方式启用增量发现：

  • GitHub Webhook — 在项目的 Webhook 设置中启用 Discovery on Push
  • GitHub Action (CI/CD) — 将 Archyl Incremental Discovery Action 添加到您的工作流中。完整说明请参阅 GitHub Actions 集成。
name: Architecture Sync
on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

完整发现 vs 增量发现

完整发现 增量发现
范围 整个仓库 仅变更的文件
触发方式 手动（UI/API） 自动（Webhook 或 GitHub Action）
速度 分钟级（取决于仓库大小） 秒到分钟
AI 成本 较高（分析所有文件） 较低（仅分析差异）
使用场景 初始设置、重大重构 日常代码变更

最佳实践

从小处开始

对于大型代码库：

  1. 从单个服务或模块开始
  2. 审查并完善结果
  3. 逐步扩展到其他区域

定期更新

保持文档的时效性：

  1. 在重大变更后运行发现
  2. 在待处理中审查新的发现
  3. 根据需要更新现有元素

结合手动操作

AI 发现是一个起点：

  1. 使用 AI 完成繁重的工作
  2. 手动添加业务上下文
  3. 完善关系和描述

故障排除

发现耗时过长

  • 降低并发设置
  • 排除大型目录（node_modules、vendor）
  • 聚焦特定路径

结果不准确

  • 边使用边审查和纠正
  • AI 会从您的纠正中学习
  • 代码注释中的更多上下文有帮助