agent-aide/aide-marketplace/aide-plugin/docs/commands/_deprecated_init.md

/aide:init 命令设计文档

一、背景

1.1 解决的问题

在开始项目工作前，需要解决以下问题：

问题	影响
环境不就绪	后续命令执行失败，打断业务流程
项目认知缺失	LLM 不了解项目结构，决策质量下降
配置未初始化	aide 程序无法正常工作

1.2 设计目标

将环境问题前置解决，在业务流程开始前确保一切就绪：

• 沉没成本小：发现严重问题可重开对话
• 环境问题不会打断后续业务逻辑

---

二、职责

2.1 做什么

1. 检测 aide 运行时环境（Python、uv 等）
2. 初始化 .aide/ 目录和配置文件
3. 触发 LLM 对项目内容的主动认知
4. 检测项目开发环境并自动修复问题
5. 介绍 aide 流程体系和可用能力

2.2 不做什么

• 不修改任何业务代码
• 不执行任务分析或优化
• 不启动流程追踪（flow）

---

三、执行流程

@startuml
skinparam defaultFontName "PingFang SC"

start

:aide env ensure --runtime;
note right: 检查 aide 自身运行环境\n不依赖配置文件

if (运行时环境就绪?) then (是)
else (否)
  :输出错误信息;
  :告知用户修复方法;
  stop
endif

:aide init;
note right: 创建 .aide/ 目录\n生成默认配置\n更新 .gitignore

:项目认知;
note right: 阅读 README.md\n阅读 CLAUDE.md\n浏览目录结构\n识别技术栈

:aide env ensure;
note right: 读取配置文件\n检查项目环境\n输出配置信息

if (项目环境就绪?) then (是)
else (否)
  if (可自动修复?) then (是)
    :自动修复;
  else (否)
    :告知用户;
    if (3次尝试失败?) then (是)
      stop
    endif
  endif
endif

:汇报就绪状态;
note right: 项目概况\n环境状态\n可用命令

stop
@enduml

3.1 步骤详解

步骤	操作	aide 命令	说明
1	运行时环境检测	aide env ensure --runtime	不依赖配置文件
2	初始化配置	aide init	创建 .aide/ 和配置
3	项目认知	无	LLM 自主阅读项目文件
4	项目环境检测	aide env ensure	读取配置，检查项目环境
5	汇报状态	无	LLM 向用户汇报

---

四、与 aide 程序的交互

4.1 aide env ensure --runtime

调用时机：步骤 1

输入：无

输出示例：

✓ 运行时环境就绪 (python:3.12, uv:0.4.0)

错误处理：

• ✗ Python 版本不足 → 告知用户安装要求
• ✗ 未检测到 uv → 告知用户安装 uv

4.2 aide init

调用时机：步骤 2

输入：无

输出示例：

✓ 已创建默认配置 .aide/config.toml
✓ 初始化完成，.aide/ 与默认配置已准备就绪

行为：

• 创建 .aide/ 目录
• 生成 config.toml 默认配置
• 检查并更新 .gitignore

4.3 aide env ensure

调用时机：步骤 4

输入：无（读取 .aide/config.toml）

输出示例：

→ 任务原文档: task-now.md
→ 任务细则文档: task-spec.md
✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv)

行为：

• 读取配置文件
• 检查/创建虚拟环境
• 安装依赖
• 输出任务文档路径配置

---

五、项目认知阶段

5.1 认知内容

内容	来源	目的
项目概述	README.md	理解项目目标和功能
开发约定	CLAUDE.md	了解项目特定规则
目录结构	文件系统	理解模块划分
技术栈	package.json/requirements.txt 等	了解使用的技术

5.2 认知输出

向用户汇报项目概况（3-5句话），包括：

• 项目是什么
• 主要功能/模块
• 使用的技术栈

---

六、汇报格式

项目概况：[来自项目认知的概要]

环境状态：✓ 环境就绪 (python:3.12, ...)

项目配置：
- 任务原文档：task-now.md
- 任务细则：task-spec.md

Aide 已就绪，可用命令：
- /aide:prep [文档路径] - 任务准备
- /aide:exec [文档路径] - 任务执行

---

七、依赖

依赖项	类型	说明
aide env	aide 子命令	环境检测
aide init	aide 子命令	配置初始化

---

八、被依赖

依赖方	说明
/aide:prep	依赖 init 完成环境准备
/aide:exec	依赖 init 完成环境准备

---

九、修改指南

9.1 修改执行流程

1. 更新本文档的流程图和步骤详解
2. 修改执行文件 ../../commands/init.md
3. 如涉及新的 aide 子命令，同步更新 aide skill 设计文档

9.2 修改项目认知内容

1. 更新本文档的"项目认知阶段"章节
2. 修改执行文件中的认知步骤

9.3 修改汇报格式

1. 更新本文档的"汇报格式"章节
2. 修改执行文件中的汇报模板

---

十、相关文档

• 执行文件
• aide env 设计
• aide init 设计
• plugin 导览