# /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 设计文档](../skill/aide.md)

### 9.2 修改项目认知内容

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

### 9.3 修改汇报格式

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

---

## 十、相关文档

- [执行文件](../../commands/init.md)
- [aide env 设计](../../../../aide-program/docs/commands/env.md)
- [aide init 设计](../../../../aide-program/docs/commands/init.md)
- [plugin 导览](../README.md)