# 结构化AI编程工具分阶段迭代计划及第一阶段作业题

## 一、分阶段迭代计划（总览）  
本计划旨在通过"小步快跑"的方式，逐步验证"AI结构化编程"核心逻辑的可行性，最终实现从"单文件修改"到"项目级结构化重构"的能力闭环。共分为四个递进阶段，每个阶段聚焦1-2个核心能力，以可演示的场景验证成果。  

**技术栈选择**：使用 bun + TypeScript 作为开发环境，利用 bun 的快速启动和内置 TypeScript 支持，专注于核心逻辑验证。

### 阶段一：单文件AST基础操作闭环（2-3周）  
**核心目标**：实现"手动指定修改节点→提取约束信息→AI生成代码片段→结构化替换"的全流程，验证基础逻辑可行性。  
**关键成果**：  
- 能解析单个TypeScript文件生成AST，并手动定位目标节点（如if条件表达式、变量赋值语句）；  
- 自动提取节点的约束信息（可用变量及类型、节点类型要求）；  
- 用AST工具链完成节点替换，生成无语法错误的新代码。  
**演示场景**：修改函数内的条件判断逻辑（如将"a>10"改为"a>10且b为偶数"），替换后代码通过TypeScript类型检查。  
**详细作业题**：参见 [docs/tasks/Stage1.md](docs/tasks/Stage1.md)  

### 阶段二：文件内符号自动索引与定位（2-3周）  
**核心目标**：摆脱"手动指定节点"，实现文件内符号的自动识别与精准定位。  
**关键成果**：  
- 自动索引文件内所有符号（函数、变量、接口等），生成包含名称、类型、作用域的符号表；  
- 支持通过"符号名+上下文"定位目标节点（如"找到函数formatUser中处理user.age的赋值语句"）；  
- 当AI生成无效符号（如未定义变量）时，工具能返回明确错误提示。  
**演示场景**：用户输入"修改calculate函数中total变量的计算逻辑"，工具自动定位目标节点并完成修改。  

### 阶段三：项目级跨文件符号支持与自动导入（3-4周）  
**核心目标**：支持跨文件符号引用，实现导入语句的自动管理。  
**关键成果**：  
- 构建项目级符号表，索引所有文件的导出符号（如utils.ts的formatDate函数）；  
- 当AI需要引用其他文件符号时，工具自动生成或补充import语句（如import { formatDate } from './utils'）；  
- 替换后通过项目级TypeScript编译检查，确保跨文件引用无错误。  
**演示场景**：在main.ts中新增日期格式化逻辑，工具自动定位并导入utils.ts的formatDate函数，修改后项目编译通过。  

### 阶段四：第三方库符号基础支持（3-4周）  
**核心目标**：支持单一版本第三方库的符号引用，暂不处理版本冲突。  
**关键成果**：  
- 解析项目依赖的第三方库类型定义（如lodash、react），提取常用符号及类型；  
- 当AI生成第三方库相关代码时，工具返回符号的类型信息及导入路径；  
- 自动处理第三方库的导入语句（如import map from 'lodash/map'）。  
**演示场景**：使用lodash的map函数处理数组，工具自动导入并确保类型匹配。  

## 二、各阶段详细作业题

各阶段的详细作业题将分别放在 `docs/tasks/` 目录下：
- [Stage1.md](docs/tasks/Stage1.md) - 第一阶段：单文件AST基础操作闭环
- Stage2.md - 第二阶段：文件内符号自动索引与定位（待创建）
- Stage3.md - 第三阶段：项目级跨文件符号支持与自动导入（待创建）
- Stage4.md - 第四阶段：第三方库符号基础支持（待创建）

## 三、通用验收标准
每个阶段完成后，需要满足以下通用标准：
1. 代码能通过 `bun run` 正常运行
2. 无TypeScript编译错误
3. 功能逻辑符合预期
4. 代码风格符合TypeScript最佳实践
5. 包含完整的测试用例和文档说明