ai-spec-dev 0.1.0

package/README.md

@@ -0,0 +1,387 @@
+# ai-spec
+
+> AI 驱动的功能开发编排工具 — 从一句话需求到可运行代码的完整流水线
+
+```
+需求描述 → 项目感知 → Spec 生成 → 交互式润色 → Git 隔离 → 代码生成 → AI 代码审查
+```
+
+---
+
+## 目录
+
+- [快速开始](#快速开始)
+- [支持的模型](#支持的模型)
+- [命令总览](#命令总览)
+- [工作流详解](#工作流详解)
+- [配置文件](#配置文件)
+- [全局安装](#全局安装)
+
+---
+
+## 快速开始
+
+```bash
+# 1. 安装依赖 & 构建
+npm install
+npm run build
+
+# 2. 设置 API Key（以 Gemini 为例）
+export GEMINI_API_KEY=your_key_here
+
+# 3. 运行
+node dist/cli/index.js create "给用户模块增加登录功能"
+```
+
+运行后会依次经历以下步骤（全部自动化）：
+
+```
+[1/6] Loading project context...        ← 读取 package.json / prisma / 路由文件
+[2/6] Generating spec with gemini...    ← AI 生成结构化 Markdown Spec
+[3/6] Interactive spec refinement...    ← 终端交互：编辑 / AI 润色 / 确认
+[4/6] Setting up git worktree...        ← 创建隔离的 feature 分支工作区
+[5/6] Spec saved: specs/feature-xxx.md
+[6/6] Code generation (mode: api)...    ← AI 生成代码文件 / 启动 Claude Code
+[7/7] Automated code review...          ← AI 对照 Spec 审查 git diff
+```
+
+---
+
+## 支持的模型
+
+| Provider | 关键词 | API Key 环境变量 | 默认模型 |
+|---|---|---|---|
+| Google Gemini | `gemini` | `GEMINI_API_KEY` | `gemini-2.5-flash` |
+| Anthropic Claude | `claude` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| OpenAI | `openai` | `OPENAI_API_KEY` | `gpt-4o` |
+| 通义千问 | `qwen` | `DASHSCOPE_API_KEY` | `qwen-max` |
+| MiniMax | `minimax` | `MINIMAX_API_KEY` | `MiniMax-Text-01` |
+| 智谱 GLM | `glm` | `ZHIPU_API_KEY` | `glm-4-plus` |
+
+> 国内模型（Qwen / MiniMax / GLM）均使用 OpenAI 兼容接口，无需额外依赖。
+
+查看所有 provider 的完整模型列表：
+
+```bash
+ai-spec model --list
+```
+
+---
+
+## 命令总览
+
+```
+ai-spec create [idea]     完整工作流：context → spec → refine → worktree → codegen → review
+ai-spec model             交互式切换 AI provider / model，写入 .ai-spec.json
+ai-spec review [file]     对当前 git diff 运行 AI 代码审查
+ai-spec config            查看 / 修改 / 重置项目级配置
+```
+
+---
+
+## 命令详解
+
+### `ai-spec create [idea]`
+
+启动完整的功能开发流水线。`idea` 参数省略时会交互式询问。
+
+```bash
+# 最简用法（使用 .ai-spec.json 或默认值）
+ai-spec create "增加商品搜索功能"
+
+# 指定 provider / model
+ai-spec create "用户登录" --provider claude --model claude-opus-4-6
+
+# Spec 用 Claude，代码生成用 Qwen
+ai-spec create "购物车结算" \
+  --provider claude \
+  --codegen api \
+  --codegen-provider qwen \
+  --codegen-model qwen-max
+
+# 只生成 Spec 和实施方案，不写代码不创建 worktree
+ai-spec create "重构支付模块" --codegen plan --skip-worktree --skip-review
+```
+
+**完整选项：**
+
+| 选项 | 说明 | 默认值 |
+|---|---|---|
+| `--provider <name>` | Spec 生成使用的 provider | `gemini` |
+| `--model <name>` | Spec 生成使用的模型 | provider 默认模型 |
+| `-k, --key <key>` | API Key（优先级高于环境变量） | — |
+| `--codegen <mode>` | 代码生成模式：`claude-code` / `api` / `plan` | `claude-code` |
+| `--codegen-provider <name>` | 代码生成使用的 provider（默认同 `--provider`） | — |
+| `--codegen-model <name>` | 代码生成使用的模型 | — |
+| `--codegen-key <key>` | 代码生成的 API Key（provider 不同时使用） | — |
+| `--skip-worktree` | 跳过 git worktree 创建 | — |
+| `--skip-review` | 跳过最终代码审查 | — |
+
+**`--codegen` 三种模式：**
+
+| 模式 | 说明 |
+|---|---|
+| `claude-code` | 在 worktree 目录中交互式启动 Claude Code CLI（默认） |
+| `api` | 调用 AI API 自动规划文件列表并逐文件生成代码写入磁盘 |
+| `plan` | 仅输出实施方案（文件清单 + 步骤），不写任何代码 |
+
+---
+
+### `ai-spec model`
+
+交互式 provider / model 切换器，结果写入当前目录的 `.ai-spec.json`。
+
+```bash
+# 启动交互式选择
+ai-spec model
+
+# 仅查看所有可用 provider 和模型，不做任何修改
+ai-spec model --list
+```
+
+**交互流程：**
+
+```
+? Configure model for:
+  ❯ Spec generation  (用于 spec 生成和润色)
+    Code generation  (--codegen api 时生效)
+    Both             (spec 和 codegen 使用同一模型)
+
+? Spec — select provider:
+  ❯ Google Gemini       Google AI Studio — Gemini 2.5 / 1.5 series
+    Anthropic Claude    Anthropic — Claude 4.x series
+    通义千问 (Qwen)     阿里云百炼 DashScope — qwen-max / plus / turbo
+    MiniMax             MiniMax AI — MiniMax-Text-01 / abab series
+    智谱 GLM (Zhipu AI) 智谱 AI — GLM-4 plus / flash / air series
+    ...
+
+? Spec — select model (通义千问):
+  ❯ qwen-max
+    qwen-max-latest
+    qwen-plus
+    qwen-turbo
+    ✎  Enter custom model name...
+
+  Preview:
+    spec    → qwen/qwen-max
+
+? Save to .ai-spec.json? Yes
+  ✔ Saved to .ai-spec.json
+```
+
+---
+
+### `ai-spec review [specFile]`
+
+抓取当前目录的 git diff，让 AI 以架构师视角对照 Spec 进行代码审查。
+
+```bash
+# 自动检测 specs/ 目录下最新的 Spec 文件
+ai-spec review
+
+# 指定 Spec 文件
+ai-spec review specs/feature-1234567890.md
+
+# 指定 provider
+ai-spec review --provider glm --model glm-4-plus
+```
+
+**输出结构：**
+
+```
+─── Review Result ───────────────────────────────
+## ✅ 优点 (What's Good)
+## ⚠️ 问题 (Issues Found)
+## 💡 改进建议 (Suggestions)
+## 📊 总体评价 (Overall Assessment)  Score: X/10
+─────────────────────────────────────────────────
+```
+
+> 提示：先执行 `git add .` 再运行 `ai-spec review`，可以让 AI 审查所有变更。
+
+---
+
+### `ai-spec config`
+
+管理当前项目的默认配置（`.ai-spec.json`），避免每次都传重复的参数。
+
+```bash
+# 查看当前配置
+ai-spec config --show
+
+# 设置默认 provider 和 codegen 模式
+ai-spec config --provider qwen --codegen api
+
+# 单独设置 codegen provider（spec 和 codegen 使用不同模型）
+ai-spec config --codegen-provider glm --codegen-model glm-4-plus
+
+# 重置为空（恢复内置默认值）
+ai-spec config --reset
+```
+
+**完整选项：**
+
+| 选项 | 说明 |
+|---|---|
+| `--provider <name>` | 默认 spec provider |
+| `--model <name>` | 默认 spec model |
+| `--codegen <mode>` | 默认代码生成模式 |
+| `--codegen-provider <name>` | 默认 codegen provider |
+| `--codegen-model <name>` | 默认 codegen model |
+| `--show` | 打印当前配置 |
+| `--reset` | 清空配置文件 |
+
+---
+
+## 工作流详解
+
+### Step 1 — Context Injection（项目感知）
+
+自动读取当前项目：
+
+- `package.json` → 依赖列表、技术栈识别（Express / Prisma / React 等）
+- `prisma/schema.prisma` → 数据库模型
+- `src/**/routes/**` / `src/**/controllers/**` → 路由文件（读取前 60 行作为上下文）
+
+这些信息作为 System Prompt 的一部分注入给 AI，确保生成的 Spec 和代码与现有项目结构一致。
+
+---
+
+### Step 2 — Spec Generation（Spec 生成）
+
+调用选定的 AI provider，生成结构化的中文 Markdown Spec，模板包含：
+
+```
+# Feature Spec: {功能名称}
+## 1. 功能概述
+## 2. 背景与动机
+## 3. 用户故事
+## 4. 功能需求（核心功能 + 边界条件）
+## 5. API 设计（接口列表 + 请求响应示例）
+## 6. 数据模型（Prisma Schema）
+## 7. 非功能性需求
+## 8. 实施要点
+```
+
+---
+
+### Step 3 — Spec Refiner（交互式润色）
+
+终端交互循环，每轮提供三个选项：
+
+```
+? What would you like to do?
+  ❯ ✅  Finalize — proceed to code generation
+    🤖  AI Polish — let AI improve clarity & completeness
+    ✏️   Edit again — continue editing
+```
+
+- **Finalize** — 确认 Spec，进入下一步
+- **AI Polish** — AI 自动润色后在编辑器中打开供确认，不强制覆盖
+- **Edit again** — 重新打开编辑器手动修改
+
+---
+
+### Step 4 — Git Worktree（隔离工作区）
+
+在项目同级目录自动创建 git worktree：
+
+```
+原项目: ~/code/my-app/
+worktree: ~/code/my-app-add-user-login/   ← 新目录，独立分支 feature/add-user-login
+```
+
+- 分支已存在时直接复用，不重复创建
+- 不是 git 仓库时跳过，在原目录继续
+- 可通过 `--skip-worktree` 强制跳过
+
+---
+
+### Step 5 — Code Generator（代码生成）
+
+根据 `--codegen` 参数选择模式：
+
+**`api` 模式（推荐用于自动化）**
+
+两阶段生成：
+1. AI 读取 Spec，输出 JSON 格式的文件操作计划（create / modify）
+2. 对每个文件逐一调用 AI 生成完整代码，写入 worktree
+
+```
+Plan: 3 file(s) to process
+  + src/controllers/userController.ts: Handle user login logic
+  + src/routes/client/user.ts: Register login routes
+  ~ src/routes/client/index.ts: Mount user router
+
+  Generating src/controllers/userController.ts... ✔
+  Generating src/routes/client/user.ts... ✔
+  Generating src/routes/client/index.ts... ✔
+```
+
+**`claude-code` 模式（默认）**
+
+在 worktree 目录中启动 Claude Code CLI 交互式会话，由用户手动引导实现。找不到 `claude` CLI 时自动降级到 `plan` 模式。
+
+**`plan` 模式**
+
+AI 输出详细的实施方案（文件清单 + 步骤顺序），不写入任何文件。适合人工开发参考。
+
+---
+
+### Step 6 — Code Review（代码审查）
+
+抓取 worktree 中的 git diff，与 Spec 一起发送给 AI，以架构师身份输出结构化审查报告。
+
+---
+
+## 配置文件
+
+`.ai-spec.json` 存放在项目根目录，所有 `create` / `review` 命令都会自动读取：
+
+```json
+{
+  "provider": "qwen",
+  "model": "qwen-max",
+  "codegen": "api",
+  "codegenProvider": "glm",
+  "codegenModel": "glm-4-plus"
+}
+```
+
+**优先级（从高到低）：** 命令行参数 > `.ai-spec.json` > 内置默认值
+
+---
+
+## 全局安装
+
+```bash
+npm run build
+npm link
+
+# 之后在任意项目目录使用
+ai-spec model                        # 切换模型
+ai-spec create "增加消息通知功能"     # 开始开发
+ai-spec review                       # 代码审查
+```
+
+---
+
+## 项目结构
+
+```
+ai-spec-dev-poc/
+├── cli/
+│   └── index.ts              # CLI 入口，定义所有命令
+├── core/
+│   ├── spec-generator.ts     # 所有 AI Provider + SpecGenerator
+│   ├── context-loader.ts     # 项目上下文读取
+│   ├── spec-refiner.ts       # 交互式 Spec 润色循环
+│   ├── code-generator.ts     # 三模式代码生成器
+│   └── reviewer.ts           # AI 代码审查
+├── git/
+│   └── worktree.ts           # Git Worktree 管理
+├── prompts/
+│   ├── spec.prompt.ts        # Spec 生成 System Prompt
+│   └── codegen.prompt.ts     # 代码生成 / 审查 System Prompt
+└── specs/                    # 生成的 Spec 文件输出目录
+```

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node