@startuml docs-command-logic
title /aide:docs 命令执行逻辑（改进版）

start

:触发 aide skill;
:获取文档配置;
note right: docs.path, docs.block_plan_path

if (文档目录存在?) then (是)
  :进入【更新流程】;
else (否)
  :进入【创建流程】;
endif

partition "创建流程" {
  :=== 阶段 1: 完整目录扫描 ===;

  :读取 .gitignore 规则;
  :递归遍历项目所有目录;
  note right
    包括空目录
    记录每个文件/目录
    标记 [ignored] 项
  end note

  :生成完整目录树结构;
  note right: 类似 tree 命令输出

  :统计文件信息;
  note right
    文件数量、类型
    代码行数、大小
  end note

  :=== 阶段 2: 初步区块划分 ===;

  :按目录结构划分区块;
  :按功能模块聚合;
  :生成区块计划文档;

  :=== 阶段 3: 区块验证 ===;

  :浅层探索验证区块划分;
  :调整区块边界（如需要）;

  :=== 阶段 4: 完全深度探索 ===;

  while (还有未处理区块?) is (是)
    :选择下一个区块;

    partition "处理单个区块" {
      :【完全阅读】区块内所有文件;
      note right
        每个文件从头到尾
        不遗漏任何一行
      end note

      if (是二进制文件?) then (是)
        :根据上下文推断概括;
        note right
          文件名、大小
          关联文件信息
        end note
      else (否)
        :分析文件内容;
        :提取关键信息;
      endif

      :生成文件概括;
      :生成区块内完整 tree 结构;
      :生成子区块文档;
    }

    :更新区块计划进度;
  endwhile (否)

  :=== 阶段 5: 生成总导览 ===;

  :整合所有区块信息;
  :生成简化版目录结构;
  note right: 总导览用前两层结构
  :生成总导览文档;
}

partition "更新流程" {
  :读取区块计划;

  while (还有区块?) is (是)
    :对比文档与代码;

    if (有变化?) then (是)
      :【完全重读】区块内文件;
      :更新区块文档;
      :更新区块内 tree 结构;
    endif
  endwhile (否)

  :更新总导览（如需要）;
  :更新区块计划时间戳;
}

:汇报完成情况;

stop
@enduml