From dfe26eff4370dfcae7513b748d2559737278e71d Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Wed, 17 Dec 2025 01:51:43 +0800 Subject: [PATCH] =?UTF-8?q?[aide]=20impl:=20=E5=AE=8C=E6=88=90=20docs.md?= =?UTF-8?q?=20=E5=91=BD=E4=BB=A4=E6=96=87=E4=BB=B6=E4=BF=AE=E6=94=B9?= 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-marketplace/aide-plugin/commands/docs.md | 200 ++++++++++++++---- 3 files changed, 175 insertions(+), 39 deletions(-) diff --git a/.aide/flow-status.json b/.aide/flow-status.json index b040cac..3900c27 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": 7, + "current_step": 8, "started_at": "2025-12-17T01:45:46+08:00", "history": [ { @@ -57,7 +57,15 @@ "action": "next-part", "phase": "impl", "step": 7, - "summary": "流程设计完成，进入实现环节" + "summary": "流程设计完成，进入实现环节", + "git_commit": "65c02dc79796e35a1d3a438b1abaf082382fa832" + }, + { + "timestamp": "2025-12-17T01:51:43+08:00", + "action": "next-step", + "phase": "impl", + "step": 8, + "summary": "完成 docs.md 命令文件修改" } ] } diff --git a/.aide/flow-status.lock b/.aide/flow-status.lock index 59ee658..fb69fbe 100755 --- a/.aide/flow-status.lock +++ b/.aide/flow-status.lock @@ -1 +1 @@ -11413 \ No newline at end of file +11787 \ No newline at end of file diff --git a/aide-marketplace/aide-plugin/commands/docs.md b/aide-marketplace/aide-plugin/commands/docs.md index 4fbf337..250a028 100644 --- a/aide-marketplace/aide-plugin/commands/docs.md +++ b/aide-marketplace/aide-plugin/commands/docs.md @@ -1,6 +1,10 @@ # Aide 项目文档管理 -你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的项目文档。 +你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的**完整深度**项目文档。 + +## 核心原则 + +> **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。 ## 前置准备 @@ -31,12 +35,60 @@ aide config get docs.block_plan_path ## 创建流程 -### 阶段 1：目录探索 +### 阶段 1：完整目录扫描 -1. 遍历项目目录结构 -2. 统计文件数量和大小 -3. 识别 `.gitignore` 排除项 -4. 记录关键文件（README、配置文件、入口文件等） +**此阶段必须完整执行，不允许跳过任何目录或文件。** + +#### 1.1 读取忽略规则 + +读取项目根目录的 `.gitignore` 文件，解析忽略规则。 + +#### 1.2 递归遍历所有目录 + +使用 `find` 或类似命令遍历项目所有目录和文件： + +```bash +# 获取完整目录树（排除 .git） +find . -not -path './.git/*' -not -name '.git' | sort +``` + +**必须记录的信息**： +- 每个目录（包括空目录） +- 每个文件的路径 +- 文件大小 +- 文件类型（源码/配置/文档/二进制/其他） + +#### 1.3 生成目录树结构 + +生成类似 `tree` 命令输出的完整目录结构，对于 .gitignore 中的项目标注 `[ignored]`： + +``` +project/ +├── src/ +│ ├── main.py +│ ├── utils/ +│ │ ├── helper.py +│ │ └── config.py +│ └── __init__.py +├── tests/ +│ └── test_main.py +├── docs/ [空目录] +├── cache/ [ignored] +├── node_modules/ [ignored] +├── .gitignore +├── README.md +└── requirements.txt +``` + +#### 1.4 统计项目信息 + +``` +- 总目录数：xx（含 xx 个空目录） +- 总文件数：xx +- 源码文件：xx +- 被忽略项：xx +- 代码行数：约 xxx 行 +``` ### 阶段 2：初步区块划分 @@ -44,7 +96,7 @@ aide config get docs.block_plan_path 1. **按目录结构**：每个主要目录可作为一个区块 2. **按功能模块**：相关功能的文件归为一个区块 -3. **大小控制**：单个区块不超过 5000 行代码 +3. **包含空目录**：空目录也要归入相应区块 4. **低耦合**：区块间依赖关系尽量简单 生成初步区块计划： @@ -55,14 +107,19 @@ aide config get docs.block_plan_path ## 项目概况 - 项目名称：xxx - 主要语言：xxx -- 文件总数：xxx +- 文件总数：xxx（含 xx 被忽略） +- 空目录数：xxx - 代码行数：xxx +## 完整目录树（简化版） +[前两层目录结构] + ## 区块划分 ### 区块 1：[名称] - 路径：xxx/ - 文件数：xx +- 空目录：xx - 状态：待处理 ### 区块 2：[名称] @@ -77,45 +134,66 @@ aide config get docs.block_plan_path ### 阶段 3：区块验证 对每个区块进行浅层探索： -1. 阅读区块内的关键文件（入口、配置、README） +1. 确认区块包含的所有文件和目录 2. 验证区块划分是否合理 3. 调整区块边界（如需要） +4. 确保没有遗漏任何文件或目录 -### 阶段 4：逐区块深度了解 +### 阶段 4：逐区块完全深度探索 -对每个区块： +**对每个区块，必须完整阅读该区块内的每一个文件，从头到尾，不允许遗漏任何一行。** -1. **完整阅读**：阅读区块内所有文件 -2. **提取信息**： - - 模块职责 - - 核心组件/类/函数 - - 对外接口 - - 依赖关系 -3. **生成文档**：按子区块文档格式生成 +#### 4.1 文件处理规则 + +| 文件类型 | 处理方式 | +|----------|----------| +| **源码文件** | 完整阅读，分析逻辑和结构，提取核心信息 | +| **配置文件** | 完整阅读，记录关键配置项 | +| **文档文件** | 完整阅读，提取主要内容 | +| **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断概括 | +| **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]`，不分析内容 | +| **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 | + +#### 4.2 每个区块需要生成 + +1. **区块内完整目录树**：类似 tree 输出，包含该区块内所有文件和子目录 +2. **文件清单及概括**：每个文件一行概括说明 +3. **核心组件说明**：重要类/函数/模块的详细说明 +4. **依赖关系**：与其他区块的依赖 ### 阶段 5：生成总导览 整合所有区块信息，生成总导览文档。 +**总导览使用简化版目录结构**（前两层），详细结构在各区块文档中展示。 + --- ## 更新流程 ### 阶段 1：读取区块计划 -读取现有的区块计划文档，了解当前文档结构。 +读取现有的区块计划文档，了解当前文档结构和完整目录树。 -### 阶段 2：分区块验证 +### 阶段 2：重新扫描目录 + +1. 重新执行完整目录扫描 +2. 对比当前目录结构与文档中记录的结构 +3. 识别新增、删除、移动的文件和目录 + +### 阶段 3：分区块验证 对每个区块： -1. 对比文档与当前代码 +1. **完全重读**有变化的文件（从头到尾） 2. 识别差异（新增、删除、修改） +3. 更新区块内目录树 -### 阶段 3：增量更新 +### 阶段 4：增量更新 1. 更新有变化的区块文档 -2. 更新总导览（如需要） -3. 更新区块计划的时间戳 +2. 更新区块内完整目录树 +3. 更新总导览的简化目录树（如有结构变化） +4. 更新区块计划的时间戳 --- @@ -139,21 +217,44 @@ aide config get docs.block_plan_path - 框架：xxx - 主要依赖：xxx +## 项目结构（简化版） + +[展示前两层目录结构，包含空目录和忽略项标注] + +``` +project/ +├── src/ 源码目录 +├── tests/ 测试目录 +├── docs/ [空目录] +├── cache/ [ignored] +├── .gitignore +└── README.md +``` + +> 详细结构见各区块文档 + ## 架构概述 [简要描述项目架构，可包含简单的 ASCII 图] ## 区块索引 -| 区块 | 路径 | 说明 | -|------|------|------| -| [区块名](./blocks/xxx.md) | xxx/ | 简要说明 | -| ... | ... | ... | +| 区块 | 路径 | 文件数 | 说明 | +|------|------|--------|------| +| [区块名](./blocks/xxx.md) | xxx/ | xx | 简要说明 | +| ... | ... | ... | ... | ## 快速导航 - 想了解 xxx → 查看 [区块名](./blocks/xxx.md) - 想修改 xxx → 查看 [区块名](./blocks/xxx.md) + +## 统计信息 + +- 总目录数：xx（含 xx 个空目录） +- 总文件数：xx +- 被忽略项：xx +- 代码行数：约 xxx 行 ``` ### 子区块文档格式 @@ -168,12 +269,33 @@ aide config get docs.block_plan_path [区块的职责和作用] +## 目录结构 + +[区块内完整目录树，类似 tree 输出] + +``` +xxx/ +├── module1/ +│ ├── __init__.py +│ ├── core.py +│ └── utils.py +├── module2/ +│ ├── __init__.py +│ └── handler.py +├── empty_dir/ [空目录] +└── README.md +``` + ## 文件清单 -| 文件 | 说明 | -|------|------| -| xxx.py | 简要说明 | -| ... | ... | +| 文件 | 类型 | 说明 | +|------|------|------| +| module1/__init__.py | 源码 | 模块初始化 | +| module1/core.py | 源码 | 核心逻辑实现 | +| module1/utils.py | 源码 | 工具函数 | +| empty_dir/ | 目录 | [空目录] 用途推断 | +| data.bin | 二进制 | [根据上下文推断的说明] | +| ... | ... | ... | ## 核心组件 @@ -207,8 +329,9 @@ aide config get docs.block_plan_path 1. 每次开始时读取区块计划 2. 找到未完成的区块 -3. 继续处理 -4. 更新区块计划的进度 +3. **完全深度探索**该区块（每个文件从头到尾） +4. 生成区块内完整目录树 +5. 更新区块计划的进度 --- @@ -217,12 +340,17 @@ aide config get docs.block_plan_path 文档创建/更新完成后： 1. 确认所有区块已处理 -2. 确认总导览已更新 -3. 向用户汇报完成情况 +2. 确认每个区块都有完整目录树 +3. 确认总导览包含简化版目录结构 +4. 确认没有遗漏任何文件或目录（包括空目录） +5. 向用户汇报完成情况 ``` 项目文档已更新： - 总导览：.aide/project-docs/README.md - 区块数：N 个 +- 总目录数：xx（含 xx 个空目录） +- 总文件数：xx +- 被忽略项：xx - 本次更新：[新增/更新的区块列表] ```