From d2161690a17ad7d50d4855456feacd0093461473 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Fri, 19 Dec 2025 05:17:07 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E6=88=90=EF=BC=9Aaide/023=20-=20?= =?UTF-8?q?=E5=BC=80=E5=A7=8B=E4=BB=BB=E5=8A=A1=E5=87=86=E5=A4=87:=20?= =?UTF-8?q?=E4=B8=BA=20user-docs=20=E6=B7=BB=E5=8A=A0=E5=88=86=E6=AD=A5?= =?UTF-8?q?=E6=89=A7=E8=A1=8C=E5=92=8C=E6=8E=A5=E7=BB=AD=E6=89=A7=E8=A1=8C?= =?UTF-8?q?=E8=83=BD=E5=8A=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .aide/branches.json | 14 +- .aide/branches.md | 11 + .aide/config.toml | 3 + .aide/logs/2025-12-19T05-00-29-status.json | 115 ++++++++ CHANGELOG.md | 9 + .../aide-plugin/commands/user-docs.md | 253 +++++++++++++----- task-now.md | 5 - 7 files changed, 343 insertions(+), 67 deletions(-) create mode 100644 .aide/logs/2025-12-19T05-00-29-status.json diff --git a/.aide/branches.json b/.aide/branches.json index 22fc4ad..cae1a9b 100644 --- a/.aide/branches.json +++ b/.aide/branches.json @@ -1,5 +1,5 @@ { - "next_number": 23, + "next_number": 24, "branches": [ { "number": 1, @@ -258,6 +258,18 @@ "status": "finished", "end_commit": "76026e4b62996b667b2f788a2cf6e34cc79cebfb", "finished_at": "2025-12-19T04:50:04+08:00" + }, + { + "number": 23, + "branch_name": "aide/023", + "source_branch": "master", + "start_commit": "d2842d46dbef9b7fe9f85749a9d2c8feae4ee528", + "task_id": "2025-12-19T05-00-29", + "task_summary": "开始任务准备: 为 user-docs 添加分步执行和接续执行能力", + "started_at": "2025-12-19T05:00:29+08:00", + "status": "finished", + "end_commit": "91c9bca5d5356e7c06d018fab0138152ab96c56a", + "finished_at": "2025-12-19T05:17:07+08:00" } ] } diff --git a/.aide/branches.md b/.aide/branches.md index 93d78fe..9c5dd72 100644 --- a/.aide/branches.md +++ b/.aide/branches.md @@ -1,5 +1,16 @@ # Git 分支概况 +## aide/023 + +- **任务**: 开始任务准备: 为 user-docs 添加分步执行和接续执行能力 +- **任务ID**: 2025-12-19T05-00-29 +- **源分支**: master +- **起始提交**: d2842d4 +- **结束提交**: 91c9bca +- **状态**: finished +- **起始时间**: 2025-12-19 05:00 +- **结束时间**: 2025-12-19 05:17 + ## aide/022 - **任务**: 开始任务准备: 调整 aide 体系的 finish 清理、提交信息和 decide 界面 diff --git a/.aide/config.toml b/.aide/config.toml index 13cb53d..ace43b0 100644 --- a/.aide/config.toml +++ b/.aide/config.toml @@ -193,6 +193,9 @@ diagram_path = ".aide/diagrams" # 支持绝对路径或相对于 aide-program 目录的相对路径 # 默认使用 aide-program/lib/plantuml.jar jar_path = "lib/plantuml.jar" +font_name = "PingFang SC" +dpi = 300 +scale = 0.5 # Java 命令路径（可选） # 默认使用系统 PATH 中的 java diff --git a/.aide/logs/2025-12-19T05-00-29-status.json b/.aide/logs/2025-12-19T05-00-29-status.json new file mode 100644 index 0000000..6f5e8fc --- /dev/null +++ b/.aide/logs/2025-12-19T05-00-29-status.json @@ -0,0 +1,115 @@ +{ + "task_id": "2025-12-19T05-00-29", + "current_phase": "finish", + "current_step": 13, + "started_at": "2025-12-19T05:00:29+08:00", + "history": [ + { + "timestamp": "2025-12-19T05:00:29+08:00", + "action": "start", + "phase": "task-optimize", + "step": 1, + "summary": "开始任务准备: 为 user-docs 添加分步执行和接续执行能力", + "git_commit": "6bae19a71c609d86f2da23c28cf2385402c49f5d" + }, + { + "timestamp": "2025-12-19T05:04:30+08:00", + "action": "next-step", + "phase": "task-optimize", + "step": 2, + "summary": "任务细则已确认", + "git_commit": "8cd54588b37ef771b1e2ac61a328b1565c7c93b1" + }, + { + "timestamp": "2025-12-19T05:09:48+08:00", + "action": "next-part", + "phase": "flow-design", + "step": 3, + "summary": "进入流程设计环节", + "git_commit": "009e1733196dcba594b5916ad3887846d616c795" + }, + { + "timestamp": "2025-12-19T05:10:49+08:00", + "action": "next-step", + "phase": "flow-design", + "step": 4, + "summary": "流程图设计完成", + "git_commit": "a466de3d80e5e25fdda9b7f16063d464101480fe" + }, + { + "timestamp": "2025-12-19T05:11:10+08:00", + "action": "next-part", + "phase": "impl", + "step": 5, + "summary": "流程设计完成，进入实现环节", + "git_commit": "2f8de410688c7de42c4799779e377fafe3b86a52" + }, + { + "timestamp": "2025-12-19T05:12:49+08:00", + "action": "next-step", + "phase": "impl", + "step": 6, + "summary": "完成 user-docs.md 重构", + "git_commit": "ee4c1f2e6a675d3021c84e2a9523a2dddcc0afe5" + }, + { + "timestamp": "2025-12-19T05:13:24+08:00", + "action": "next-part", + "phase": "verify", + "step": 7, + "summary": "实现完成，进入验证环节", + "git_commit": "5692f32827531de7059df393b0270eb169f35557" + }, + { + "timestamp": "2025-12-19T05:14:04+08:00", + "action": "next-step", + "phase": "verify", + "step": 8, + "summary": "验证完成: 所有标准通过", + "git_commit": "167eb17787dcc5ca775a20d2efd2049df6b81c75" + }, + { + "timestamp": "2025-12-19T05:14:38+08:00", + "action": "next-part", + "phase": "docs", + "step": 9, + "summary": "验证通过，进入文档环节", + "git_commit": "30ae787d5009708fccd8eb30bfddbc9f9c7f4be7" + }, + { + "timestamp": "2025-12-19T05:15:24+08:00", + "action": "next-step", + "phase": "docs", + "step": 10, + "summary": "文档更新完成", + "git_commit": "bf829bc5cae3a264118d34bd1194799b94b6c579" + }, + { + "timestamp": "2025-12-19T05:15:38+08:00", + "action": "next-part", + "phase": "confirm", + "step": 11, + "summary": "文档更新完成，进入用户确认环节", + "git_commit": "b2588d1b761956d0584ff292ff854ff7fa535f1c" + }, + { + "timestamp": "2025-12-19T05:16:50+08:00", + "action": "next-step", + "phase": "confirm", + "step": 12, + "summary": "用户确认通过", + "git_commit": "d58f754bf01b9e8396b084fcacc1557b6cb33a89" + }, + { + "timestamp": "2025-12-19T05:17:07+08:00", + "action": "next-part", + "phase": "finish", + "step": 13, + "summary": "用户确认通过，进入收尾", + "git_commit": "91c9bca5d5356e7c06d018fab0138152ab96c56a" + } + ], + "source_branch": "master", + "start_commit": "d2842d46dbef9b7fe9f85749a9d2c8feae4ee528", + "task_branch": "aide/023" +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 826bff5..dfe8a6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ ### 优化 +**user-docs 分步执行和接续执行能力** + +- 重构 `commands/user-docs.md`，添加与 `user-graph.md` 相同的分步执行机制 +- 新增"分析和计划阶段"：首次运行时分析项目、规划结构、生成计划文档 +- 新增"接续执行阶段"：后续运行时读取计划、显示进度、支持接续 +- 新增"步骤执行流程"：每步完成后更新计划、支持暂停保存进度 +- 新增配置项 `user_docs.docs_plan_path`（默认 `docs/user-docs-plan.md`） +- 适用于大型项目的文档生成，支持分多次对话完成 + **finish 清理代码移除** - 移除 `run.md` 和 `auto-run.md` 中的"清理临时文件"指令和 `aide flow next-step "任务完成"` 命令 diff --git a/aide-marketplace/aide-plugin/commands/user-docs.md b/aide-marketplace/aide-plugin/commands/user-docs.md index a330aaa..5837dfc 100644 --- a/aide-marketplace/aide-plugin/commands/user-docs.md +++ b/aide-marketplace/aide-plugin/commands/user-docs.md @@ -2,6 +2,10 @@ 你正在执行 Aide 用户文档生成流程。这个命令帮助用户在 docs 目录下创建面向用户的详细文档。 +此命令支持**分步执行**和**接续执行**，适用于大型项目。 + +这可能是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。 + --- ## 前置准备 @@ -12,6 +16,25 @@ ## 开始 +### 检查计划文件 + +```bash +aide config get user_docs.docs_plan_path +``` + +读取配置的计划文件路径，检查文件是否存在。 + +**根据计划文件状态决定流程**： + +- **计划文件不存在** → 进入**分析和计划阶段** +- **计划文件存在** → 进入**接续执行阶段** + +--- + +## 分析和计划阶段 + +当计划文件不存在时执行此流程。 + ### 1. 检查前置条件 #### 1.1 检查 README 规范文件 @@ -48,11 +71,9 @@ aide config get docs.path - **先执行 /aide:docs**（推荐） - **继续生成文档**（基于代码分析） ---- +### 2. 分析项目 -## 2. 分析项目 - -### 2.1 读取项目信息 +#### 2.1 读取项目信息 **优先级**： @@ -68,7 +89,7 @@ aide config get docs.path - 分析目录结构 - 识别主要功能模块 -### 2.2 确定项目类型 +#### 2.2 确定项目类型 | 类型 | 特征 | |------|------| @@ -76,11 +97,11 @@ aide config get docs.path | 单体程序 | 单一主项目，可能有子模块 | | 多项目仓库 | 包含多个独立子项目 | ---- +### 3. 规划文档结构 -## 3. 规划文档结构 +根据项目类型选择文档结构模板： -### 3.1 纯文档/材料类项目 +#### 3.1 纯文档/材料类项目 ``` docs/ @@ -91,7 +112,7 @@ docs/ └── topic-2.md ``` -### 3.2 单体程序项目 +#### 3.2 单体程序项目 ``` docs/ @@ -106,7 +127,7 @@ docs/ └── ... ``` -### 3.3 多项目仓库 +#### 3.3 多项目仓库 ``` docs/ @@ -122,11 +143,57 @@ docs/ └── ... ``` ---- +### 4. 生成计划文档 -## 4. 向用户确认结构 +在配置的路径创建计划文件： -向用户展示规划的文档结构，使用 AskUserQuestion 确认： +```bash +aide config get user_docs.docs_plan_path +``` + +计划文档格式： + +```markdown +# 用户文档生成计划 + +## 项目概述 + +{{基于项目文档/分析的简要描述}} + +## 项目类型 + +{{纯文档/单体程序/多项目仓库}} + +## 文档结构 + +``` +{{PLANNED_STRUCTURE}} +``` + +## 执行步骤 + +| # | 步骤描述 | 状态 | +|---|----------|------| +| 1 | 创建目录结构 | - | +| 2 | 生成 {{doc-1}}.md | - | +| 3 | 生成 {{doc-2}}.md | - | +| ... | ... | - | +| N | 更新 README 链接 | - | + +## 当前进度 + +- 当前步骤：0（未开始） +- 已完成：0 / {{TOTAL_STEPS}} +- 最后更新：{{TIMESTAMP}} + +## 备注 + +（执行过程中的记录） +``` + +### 5. 用户确认 + +向用户展示规划的文档结构： > 根据项目分析，建议创建以下文档结构： > @@ -134,41 +201,110 @@ docs/ > {{PLANNED_STRUCTURE}} > ``` > +> **预估步骤**：共 {{TOTAL_STEPS}} 步 +> > 是否按此结构生成文档？ **选项**： -- **确认生成**（推荐） +- **开始执行**（推荐） - **调整结构**（自定义） +- **稍后执行** -如用户选择调整，通过对话确认最终结构。 +如用户选择调整，通过对话确认最终结构后更新计划文档。 + +如选择开始执行，进入步骤执行流程。 --- -## 5. 生成文档 +## 接续执行阶段 -### 5.1 检查现有文档 +当计划文件存在时执行此流程。 -```bash -aide config get user_docs.docs_path -``` +### 1. 读取计划文档 -检查 docs 目录是否存在以及包含的内容。 +解析计划文件获取： +- 项目概述和类型 +- 文档结构 +- 执行步骤列表和状态 +- 当前进度 +- 历史备注 -### 5.2 处理现有内容 +### 2. 显示进度 -**首次生成**：直接创建所有文档 +> **用户文档生成进度** +> +> 项目类型：{{PROJECT_TYPE}} +> 当前步骤：{{CURRENT_STEP}} +> 已完成步骤：{{COMPLETED_STEPS}}/{{TOTAL_STEPS}} +> 上次更新：{{LAST_UPDATE}} -**增量更新**（docs 目录已存在）： +### 3. 确认继续 -对于每个文档文件： +使用 AskUserQuestion： -1. **新文件**：直接创建 -2. **已存在的文件**： - - 检查是否有 `` 标记 - - 保留标记以上的用户编辑内容 - - 更新标记以下的自动生成内容 +> 是否从当前进度继续执行？ -### 5.3 文档内容规范 +**选项**： +- **继续执行**（推荐） +- **查看计划详情** +- **重新开始**（清空进度） + +如选择重新开始，删除计划文件后进入分析和计划阶段。 + +--- + +## 步骤执行流程 + +### 执行单个步骤 + +对于每个步骤： + +1. **显示当前任务**： + > 正在执行：{{STEP_DESCRIPTION}} + +2. **执行步骤**： + + **步骤类型 A：创建目录结构** + - 检查 docs 目录是否存在 + - 创建必要的子目录 + + **步骤类型 B：生成文档文件** + - 分析相关代码/文档 + - 根据模板生成内容 + - 写入文件 + + **步骤类型 C：更新 README 链接** + - 检查 README 中的文档链接部分 + - 更新链接指向新生成的文档 + +3. **更新计划文档**： + - 标记步骤完成（`✓`） + - 更新当前进度 + - 记录时间戳 + +4. **保存产出**： + - 写入生成的文档文件 + +### 步骤间询问 + +每完成一个步骤后询问： + +> 步骤 {{STEP_ID}} 已完成：{{STEP_DESCRIPTION}} +> +> 是否继续下一步？ + +**选项**： +- **继续**（推荐） +- **查看产出** +- **暂停（保存进度）** + +如选择暂停，保存进度后结束本次执行。 + +--- + +## 文档内容规范 + +### 文档文件结构 每个文档文件应包含： @@ -185,7 +321,7 @@ aide config get user_docs.docs_path {{用户自定义内容区域}} ``` -### 5.4 生成各文档 +### 各类文档内容要求 #### getting-started.md（快速开始） @@ -221,35 +357,27 @@ aide config get user_docs.docs_path --- -## 6. 更新 README +## 完成流程 -如果 README 中有文档链接部分，更新链接指向新生成的文档： +当所有步骤完成时： -```markdown -## 文档 +1. **更新计划文档**： + - 标记所有步骤完成 + - 记录完成时间 -- [快速开始](docs/getting-started.md) -- [安装指南](docs/installation.md) -- [使用说明](docs/usage.md) -- [配置说明](docs/configuration.md) -- [API 文档](docs/api/index.md) -``` +2. **显示完成提示**： ---- - -## 7. 完成提示 - -> 用户文档已生成：`{{DOCS_PATH}}/` -> -> 生成的文档： -> {{GENERATED_FILES_LIST}} -> -> 建议： -> - 检查生成的内容是否准确 -> - 在 `` 标记下方添加自定义内容 -> - 自定义内容不会被后续更新覆盖 -> -> 如需重新生成，可再次运行 `/aide:user-docs`。 + > 用户文档已生成：`{{DOCS_PATH}}/` + > + > 生成的文档： + > {{GENERATED_FILES_LIST}} + > + > 建议： + > - 检查生成的内容是否准确 + > - 在 `` 标记下方添加自定义内容 + > - 自定义内容不会被后续更新覆盖 + > + > 如需重新生成，可删除计划文件后再次运行 `/aide:user-docs`。 --- @@ -258,13 +386,16 @@ aide config get user_docs.docs_path | 配置项 | 默认值 | 说明 | |--------|--------|------| | `user_docs.docs_path` | `docs` | 用户文档目录路径 | +| `user_docs.docs_plan_path` | `docs/user-docs-plan.md` | 计划文件路径 | | `user_docs.rules_path` | `make-readme-rules.md` | README 规范文件路径 | --- ## 注意事项 -1. **保留用户编辑**：使用标记区分自动生成和用户编辑的内容 -2. **风格一致**：文档风格与 README 保持一致 -3. **增量更新**：多次运行不会覆盖用户自定义内容 -4. **链接同步**：README 中的文档链接自动更新 +1. **分步执行**：大型项目建议分多次对话完成 +2. **进度持久化**：进度保存在计划文件，可随时接续 +3. **保留用户编辑**：使用标记区分自动生成和用户编辑的内容 +4. **风格一致**：文档风格与 README 保持一致 +5. **增量更新**：多次运行不会覆盖用户自定义内容 +6. **链接同步**：README 中的文档链接自动更新 diff --git a/task-now.md b/task-now.md index ee8d144..e69de29 100644 --- a/task-now.md +++ b/task-now.md @@ -1,5 +0,0 @@ -我之前有一次任务的内容，我把它的节选保存在了 @cache/old-task.md 文件中， - -现在那部分内容已经被实现为了commands下的readme.md、user-docs.md和user-graph.md， - -我现在想要做的是，让user-docs具有和user-graph一样的**分步执行**和**接续执行**能力，