From f13676c52085470908e857ec577ef2aedf7b52e9 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Wed, 17 Dec 2025 01:53:11 +0800 Subject: [PATCH] =?UTF-8?q?[aide]=20impl:=20=E5=AE=8C=E6=88=90=20docs/comm?= =?UTF-8?q?ands/docs.md=20=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3=E6=9B=B4?= =?UTF-8?q?=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .aide/flow-status.json | 12 ++- .aide/flow-status.lock | 2 +- .../aide-plugin/docs/commands/docs.md | 95 ++++++++++++++----- 3 files changed, 80 insertions(+), 29 deletions(-) diff --git a/.aide/flow-status.json b/.aide/flow-status.json index 3900c27..965c200 100644 --- a/.aide/flow-status.json +++ b/.aide/flow-status.json @@ -1,7 +1,7 @@ { "task_id": "2025-12-17T01-45-46", "current_phase": "impl", - "current_step": 8, + "current_step": 9, "started_at": "2025-12-17T01:45:46+08:00", "history": [ { @@ -65,7 +65,15 @@ "action": "next-step", "phase": "impl", "step": 8, - "summary": "完成 docs.md 命令文件修改" + "summary": "完成 docs.md 命令文件修改", + "git_commit": "dfe26eff4370dfcae7513b748d2559737278e71d" + }, + { + "timestamp": "2025-12-17T01:53:11+08:00", + "action": "next-step", + "phase": "impl", + "step": 9, + "summary": "完成 docs/commands/docs.md 设计文档更新" } ] } diff --git a/.aide/flow-status.lock b/.aide/flow-status.lock index fb69fbe..1bf30eb 100755 --- a/.aide/flow-status.lock +++ b/.aide/flow-status.lock @@ -1 +1 @@ -11787 \ No newline at end of file +11881 \ No newline at end of file diff --git a/aide-marketplace/aide-plugin/docs/commands/docs.md b/aide-marketplace/aide-plugin/docs/commands/docs.md index 673badb..b516000 100644 --- a/aide-marketplace/aide-plugin/docs/commands/docs.md +++ b/aide-marketplace/aide-plugin/docs/commands/docs.md @@ -2,18 +2,23 @@ ## 一、概述 -`/aide:docs` 是项目文档管理命令，用于创建和维护面向 LLM 的项目文档。 +`/aide:docs` 是项目文档管理命令，用于创建和维护面向 LLM 的**完整深度**项目文档。 ### 1.1 设计目标 | 目标 | 说明 | |------|------| +| 完全深度探索 | 对每个文件、每个目录（包括空目录）完全覆盖，不考虑效率 | | 独立运行 | 通常在需要时单独执行 | | 区块化 | 文档按区块组织，支持增量更新 | | 面向 LLM | 文档格式针对 LLM 理解优化 | | 多对话续接 | 大项目支持多次对话完成 | -### 1.2 新增命令 +### 1.2 核心原则 + +> **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。 + +### 1.3 新增命令 本命令是 v2.0.0 新增的独立命令。 @@ -31,32 +36,40 @@ │ ▼ ┌─────────────────────────────────────────┐ -│ 目录探索 │ -│ (遍历结构、统计文件、识别忽略项) │ +│ 完整目录扫描 │ +│ (递归遍历所有目录和文件) │ +│ - 读取 .gitignore 规则 │ +│ - 记录每个文件/目录（含空目录） │ +│ - 生成类似 tree 的目录结构 │ +│ - 标注 [ignored] 和 [空目录] │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 初步区块划分 │ │ (按目录结构和功能模块划分) │ +│ - 包含空目录归入相应区块 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 区块验证 │ -│ (浅层探索验证划分合理性) │ +│ (确认没有遗漏任何文件或目录) │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ -│ 逐区块深度了解 │ -│ (完整阅读、提取信息、生成文档) │ +│ 逐区块完全深度探索 │ +│ - 每个文件从头到尾完整阅读 │ +│ - 二进制文件根据上下文推断概括 │ +│ - 生成区块内完整 tree 结构 │ +│ - 生成文件清单及概括 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 生成总导览 │ -│ (整合所有区块信息) │ +│ (简化版目录结构 + 区块索引) │ └─────────────────────────────────────────┘ ``` @@ -71,19 +84,27 @@ ▼ ┌─────────────────────────────────────────┐ │ 读取区块计划 │ -│ (了解当前文档结构) │ +│ (了解当前文档结构和完整目录树) │ +└─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 重新扫描目录 │ +│ (对比当前结构与文档记录的结构) │ +│ - 识别新增、删除、移动的文件/目录 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 分区块验证 │ -│ (对比文档与代码，识别差异) │ +│ (完全重读有变化的文件) │ +│ - 更新区块内目录树 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 增量更新 │ -│ (只更新有变化的区块) │ +│ (更新区块文档 + 总导览) │ └─────────────────────────────────────────┘ ``` @@ -95,9 +116,9 @@ ``` .aide/project-docs/ -├── README.md # 总导览 +├── README.md # 总导览（含简化版目录结构） ├── block-plan.md # 区块计划（进度追踪） -└── blocks/ # 子区块文档 +└── blocks/ # 子区块文档（含完整目录树） ├── core.md ├── api.md └── ... @@ -112,9 +133,11 @@ ## 项目简介 ## 技术栈 +## 项目结构（简化版） # 前两层目录，含空目录和忽略项标注 ## 架构概述 -## 区块索引 +## 区块索引 # 含文件数列 ## 快速导航 +## 统计信息 # 目录数、文件数、空目录数、被忽略项 ``` ### 3.3 子区块格式 @@ -125,7 +148,8 @@ > 路径：xxx/ ## 概述 -## 文件清单 +## 目录结构 # 区块内完整 tree 结构 +## 文件清单 # 每个文件一行概括，含类型列 ## 核心组件 ## 接口说明 ## 依赖关系 @@ -134,16 +158,31 @@ --- -## 四、职责边界 +## 四、文件处理规则 -### 4.1 本命令负责 +| 文件类型 | 处理方式 | +|----------|----------| +| **源码文件** | 完整阅读，分析逻辑和结构，提取核心信息 | +| **配置文件** | 完整阅读，记录关键配置项 | +| **文档文件** | 完整阅读，提取主要内容 | +| **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断概括 | +| **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]`，不分析内容 | +| **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 | -- 探索项目目录结构 +--- + +## 五、职责边界 + +### 5.1 本命令负责 + +- 递归遍历项目所有目录和文件 +- 生成完整目录树结构 +- 完全深度阅读每个文件 - 划分文档区块 - 创建和更新项目文档 - 维护区块计划（进度追踪） -### 4.2 本命令不负责 +### 5.2 本命令不负责 - 环境配置（由 `/aide:setup` 负责） - 项目文档载入（由 `/aide:load` 负责） @@ -151,27 +190,30 @@ --- -## 五、区块划分规则 +## 六、区块划分规则 1. **按目录结构**：每个主要目录可作为一个区块 2. **按功能模块**：相关功能的文件归为一个区块 -3. **大小控制**：单个区块不超过 5000 行代码 +3. **包含空目录**：空目录也要归入相应区块 4. **低耦合**：区块间依赖关系尽量简单 +> 注：v2.0.1 移除了"单个区块不超过 5000 行代码"的限制 + --- -## 六、多对话续接 +## 七、多对话续接 大项目可能需要多次对话完成： 1. 每次开始时读取区块计划 2. 找到未完成的区块 -3. 继续处理 -4. 更新区块计划的进度 +3. **完全深度探索**该区块（每个文件从头到尾） +4. 生成区块内完整目录树 +5. 更新区块计划的进度 --- -## 七、相关文档 +## 八、相关文档 - [执行文件](../../commands/docs.md) - [/aide:load 命令](load.md) @@ -179,7 +221,8 @@ --- -## 八、版本信息 +## 九、版本信息 - 创建日期：2025-12-15 - v2.0.0 新增命令 +- v2.0.1 强化完全深度探索要求，添加目录树结构展示