ai-spec-dev 0.1.0 → 0.17.0

package/core/spec-generator.ts

@@ -0,0 +1,428 @@
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import Anthropic from "@anthropic-ai/sdk";
+import OpenAI from "openai";
+import axios from "axios";
+import { ProxyAgent } from "undici";
+import { specPrompt } from "../prompts/spec.prompt";
+import { ProjectContext } from "./context-loader";
+
+// ─── Proxy Helper ─────────────────────────────────────────────────────────────
+// 仅用于 Gemini：其他 SDK（Anthropic / OpenAI）会自动读取 HTTPS_PROXY。
+// Gemini SDK 使用 Node.js 原生 fetch（undici），不会自动读代理环境变量，
+// 需要手动创建 ProxyAgent 并通过 fetchOptions 注入。
+// 这是 in-process 级别的配置，完全不影响 execSync 启动的子进程（如 claude CLI）。
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function geminiRequestOptions(): any {
+  const proxyUrl =
+    process.env.GEMINI_PROXY ||
+    process.env.HTTPS_PROXY ||
+    process.env.https_proxy ||
+    process.env.HTTP_PROXY ||
+    process.env.http_proxy;
+
+  if (!proxyUrl) return undefined;
+  // fetchOptions.dispatcher は型定義(v0.21)に未記載だが runtime では動作する
+  return { fetchOptions: { dispatcher: new ProxyAgent(proxyUrl) } };
+}
+
+// ─── Provider Interface ────────────────────────────────────────────────────────
+
+export interface AIProvider {
+  generate(prompt: string, systemInstruction?: string): Promise<string>;
+  readonly providerName: string;
+  readonly modelName: string;
+}
+
+// ─── Provider Catalog ─────────────────────────────────────────────────────────
+// Single source of truth for all supported providers and their models.
+
+export interface ProviderMeta {
+  /** Human-readable display name */
+  displayName: string;
+  /** Short description shown in model picker */
+  description: string;
+  /** Available models (first is the default) */
+  models: string[];
+  /** Environment variable name for the API key */
+  envKey: string;
+  /**
+   * Base URL for OpenAI-compatible providers.
+   * Undefined means the provider has its own SDK (Gemini / Claude).
+   */
+  baseURL?: string;
+  /**
+   * Role to use for system instructions.
+   * OpenAI o1/o3 use "developer" instead of "system".
+   * Default: "system"
+   */
+  systemRole?: "system" | "developer";
+  /**
+   * Extra body params injected into every chat completion request.
+   * e.g. Qwen3 needs { enable_thinking: false } to suppress CoT noise.
+   */
+  extraBody?: Record<string, unknown>;
+}
+
+export const PROVIDER_CATALOG: Record<string, ProviderMeta> = {
+  // ── International ──────────────────────────────────────────────────────────
+  mimo: {
+    displayName: "MiMo (Xiaomi)",
+    description: "小米 MiMo — mimo-v2-pro (Anthropic-compatible API)",
+    models: ["mimo-v2-pro"],
+    envKey: "MIMO_API_KEY",
+    // baseURL not used — MiMo has a dedicated provider class
+  },
+  gemini: {
+    displayName: "Google Gemini",
+    description: "Google AI Studio — Gemini 2.5 / 2.0 series",
+    models: [
+      "gemini-2.5-pro",
+      "gemini-2.5-flash",
+      "gemini-2.0-flash",
+      "gemini-2.0-flash-lite",
+      "gemini-1.5-pro",
+      "gemini-1.5-flash",
+    ],
+    envKey: "GEMINI_API_KEY",
+  },
+  claude: {
+    displayName: "Anthropic Claude",
+    description: "Anthropic — Claude 4.x / 3.7 series",
+    models: [
+      "claude-opus-4-6",
+      "claude-sonnet-4-6",
+      "claude-haiku-4-5",
+      "claude-3-7-sonnet-20250219",
+    ],
+    envKey: "ANTHROPIC_API_KEY",
+  },
+  openai: {
+    displayName: "OpenAI",
+    description: "OpenAI — o3 / GPT-4o series",
+    models: [
+      "o3",
+      "o3-mini",
+      "o1",
+      "o1-mini",
+      "gpt-4o",
+      "gpt-4o-mini",
+    ],
+    envKey: "OPENAI_API_KEY",
+    baseURL: "https://api.openai.com/v1",
+  },
+  deepseek: {
+    displayName: "DeepSeek",
+    description: "DeepSeek — V3 (chat) / R1 (reasoning)",
+    models: [
+      "deepseek-chat",       // DeepSeek-V3
+      "deepseek-reasoner",   // DeepSeek-R1
+    ],
+    envKey: "DEEPSEEK_API_KEY",
+    baseURL: "https://api.deepseek.com/v1",
+  },
+
+  // ── Chinese Models (OpenAI-compatible) ────────────────────────────────────
+  qwen: {
+    displayName: "通义千问 (Qwen)",
+    description: "阿里云百炼 — Qwen3 / Qwen2.5 series",
+    models: [
+      "qwen3-235b-a22b",     // Qwen3 MoE flagship (supports thinking mode)
+      "qwen3-72b",
+      "qwen3-32b",
+      "qwen3-8b",
+      "qwen-max",
+      "qwen-max-latest",
+      "qwen-plus",
+      "qwen-long",
+    ],
+    envKey: "DASHSCOPE_API_KEY",
+    baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    // Qwen3 models enable thinking (CoT) by default, which pollutes structured outputs.
+    // Disable it so JSON/Markdown responses stay clean.
+    extraBody: { enable_thinking: false },
+  },
+  glm: {
+    displayName: "智谱 GLM (Zhipu AI)",
+    description: "智谱 AI — GLM-5 / GLM-4 series + Z1 reasoning",
+    models: [
+      "glm-5",               // GLM-5 flagship (如不可用请确认最新 model ID)
+      "glm-5-flash",
+      "glm-z1",              // GLM-Z1 reasoning model
+      "glm-z1-flash",
+      "glm-4-plus",
+      "glm-4-flash",
+      "glm-4-long",
+    ],
+    envKey: "ZHIPU_API_KEY",
+    baseURL: "https://open.bigmodel.cn/api/paas/v4/",
+  },
+  minimax: {
+    displayName: "MiniMax",
+    description: "MiniMax AI — MiniMax-Text-2.7 / Text-01 series",
+    models: [
+      "MiniMax-Text-2.7",    // MiniMax 最新旗舰 (如不可用请确认最新 model ID)
+      "MiniMax-Text-01",
+      "abab6.5s-chat",
+    ],
+    envKey: "MINIMAX_API_KEY",
+    baseURL: "https://api.minimax.chat/v1",
+  },
+  doubao: {
+    displayName: "豆包 Doubao (ByteDance)",
+    description: "火山引擎 Ark — Doubao Pro/Lite series",
+    models: [
+      "doubao-pro-256k",
+      "doubao-pro-128k",
+      "doubao-pro-32k",
+      "doubao-lite-128k",
+      "doubao-lite-32k",
+    ],
+    envKey: "ARK_API_KEY",
+    baseURL: "https://ark.cn-beijing.volces.com/api/v3",
+  },
+};
+
+// Derived convenience maps (kept for backward compatibility)
+export const SUPPORTED_PROVIDERS = Object.keys(PROVIDER_CATALOG);
+
+export const DEFAULT_MODELS: Record<string, string> = Object.fromEntries(
+  Object.entries(PROVIDER_CATALOG).map(([k, v]) => [k, v.models[0]])
+);
+
+export const ENV_KEY_MAP: Record<string, string> = Object.fromEntries(
+  Object.entries(PROVIDER_CATALOG).map(([k, v]) => [k, v.envKey])
+);
+
+// ─── Gemini Provider ───────────────────────────────────────────────────────────
+
+export class GeminiProvider implements AIProvider {
+  private genAI: GoogleGenerativeAI;
+  readonly providerName = "gemini";
+  readonly modelName: string;
+
+  constructor(apiKey: string, modelName = PROVIDER_CATALOG.gemini.models[0]) {
+    this.genAI = new GoogleGenerativeAI(apiKey);
+    this.modelName = modelName;
+  }
+
+  async generate(prompt: string, systemInstruction?: string): Promise<string> {
+    const model = this.genAI.getGenerativeModel(
+      { model: this.modelName, ...(systemInstruction ? { systemInstruction } : {}) },
+      geminiRequestOptions()
+    );
+    const result = await model.generateContent(prompt);
+    return result.response.text();
+  }
+}
+
+// ─── Claude Provider ───────────────────────────────────────────────────────────
+
+export class ClaudeProvider implements AIProvider {
+  private client: Anthropic;
+  readonly providerName = "claude";
+  readonly modelName: string;
+
+  constructor(apiKey: string, modelName = PROVIDER_CATALOG.claude.models[0]) {
+    this.client = new Anthropic({ apiKey });
+    this.modelName = modelName;
+  }
+
+  async generate(prompt: string, systemInstruction?: string): Promise<string> {
+    const message = await this.client.messages.create({
+      model: this.modelName,
+      max_tokens: 8192,
+      ...(systemInstruction ? { system: systemInstruction } : {}),
+      messages: [{ role: "user", content: prompt }],
+    });
+    const block = message.content[0];
+    if (block.type === "text") return block.text;
+    throw new Error("Unexpected response type from Claude API");
+  }
+}
+
+// ─── OpenAI-Compatible Provider ───────────────────────────────────────────────
+// Handles OpenAI, DeepSeek, Qwen, MiniMax, GLM, Doubao — all expose the same API.
+
+export class OpenAICompatibleProvider implements AIProvider {
+  protected client: OpenAI;
+  readonly providerName: string;
+  readonly modelName: string;
+  private systemRole: "system" | "developer";
+  private extraBody?: Record<string, unknown>;
+
+  constructor(
+    providerName: string,
+    apiKey: string,
+    modelName: string,
+    baseURL?: string,
+    systemRole: "system" | "developer" = "system",
+    extraBody?: Record<string, unknown>
+  ) {
+    this.providerName = providerName;
+    this.modelName = modelName;
+    this.systemRole = systemRole;
+    this.extraBody = extraBody;
+    this.client = new OpenAI({
+      apiKey,
+      ...(baseURL ? { baseURL } : {}),
+    });
+  }
+
+  async generate(prompt: string, systemInstruction?: string): Promise<string> {
+    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [];
+
+    if (systemInstruction) {
+      // o1/o3 require "developer" role; gpt-4o/gpt-4-turbo use "system"
+      // Auto-detect: if model starts with "o1" or "o3", use developer role
+      const isOSeries = /^o[13]/.test(this.modelName);
+      const role = isOSeries ? "developer" : this.systemRole;
+      messages.push({ role, content: systemInstruction } as OpenAI.Chat.ChatCompletionMessageParam);
+    }
+    messages.push({ role: "user", content: prompt });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const completion = await (this.client.chat.completions.create as any)({
+      model: this.modelName,
+      messages,
+      ...(this.extraBody ? { extra_body: this.extraBody } : {}),
+    });
+
+    return (completion.choices[0].message.content as string) ?? "";
+  }
+}
+
+// ─── MiMo Provider ─────────────────────────────────────────────────────────────
+// MiMo uses the Anthropic messages format but with a different base URL
+// and a custom "api-key" auth header (not "x-api-key" / "Authorization: Bearer").
+// The Anthropic SDK does not support custom auth headers, so we call the API
+// directly via axios.
+
+export class MiMoProvider implements AIProvider {
+  readonly providerName = "mimo";
+  readonly modelName: string;
+  private apiKey: string;
+  private readonly baseUrl = "https://api.xiaomimimo.com/anthropic/v1/messages";
+
+  constructor(apiKey: string, modelName = PROVIDER_CATALOG.mimo.models[0]) {
+    this.apiKey = apiKey;
+    this.modelName = modelName;
+  }
+
+  async generate(prompt: string, systemInstruction?: string): Promise<string> {
+    const body: Record<string, unknown> = {
+      model: this.modelName,
+      max_tokens: 16384,
+      messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
+      top_p: 0.95,
+      stream: false,
+      temperature: 1.0,
+      stop_sequences: null,
+    };
+
+    if (systemInstruction) {
+      body.system = systemInstruction;
+    }
+
+    const response = await axios.post(this.baseUrl, body, {
+      headers: {
+        "api-key": this.apiKey,
+        "Content-Type": "application/json",
+      },
+    });
+
+    // Response follows Anthropic format: { content: [{ type: "text"|"thinking", ... }] }
+    // MiMo may return a "thinking" block before the actual "text" block — skip it.
+    const data = response.data as { stop_reason?: string; content?: Array<{ type: string; text?: string; thinking?: string }> };
+    const blocks = data?.content ?? [];
+
+    const textBlock = blocks.find((b) => b.type === "text");
+    if (textBlock?.text) return textBlock.text;
+
+    // If stop_reason is max_tokens, the model was cut off mid-generation (thinking block only)
+    if (data?.stop_reason === "max_tokens") {
+      throw new Error(`MiMo response truncated (max_tokens reached). The prompt may be too long. Try a shorter spec or switch to a model with larger context.`);
+    }
+
+    throw new Error(`Unexpected MiMo response: ${JSON.stringify(response.data).slice(0, 200)}`);
+  }
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createProvider(
+  providerName: string,
+  apiKey: string,
+  modelName?: string
+): AIProvider {
+  const meta = PROVIDER_CATALOG[providerName];
+  if (!meta) {
+    throw new Error(
+      `Unknown provider: "${providerName}". Valid options: ${SUPPORTED_PROVIDERS.join(", ")}`
+    );
+  }
+
+  const model = modelName || meta.models[0];
+
+  switch (providerName) {
+    case "gemini":
+      return new GeminiProvider(apiKey, model);
+    case "claude":
+      return new ClaudeProvider(apiKey, model);
+    case "mimo":
+      return new MiMoProvider(apiKey, model);
+    // All OpenAI-compatible providers: openai, deepseek, qwen, glm, minimax, doubao
+    default:
+      return new OpenAICompatibleProvider(
+        providerName,
+        apiKey,
+        model,
+        meta.baseURL,
+        meta.systemRole ?? "system",
+        meta.extraBody
+      );
+  }
+}
+
+// ─── Spec Generator ───────────────────────────────────────────────────────────
+
+export class SpecGenerator {
+  constructor(private provider: AIProvider) {}
+
+  async generateSpec(idea: string, context?: ProjectContext): Promise<string> {
+    const parts: string[] = [idea];
+
+    if (context) {
+      // Constitution is highest priority — put it first so the AI respects it
+      if (context.constitution) {
+        parts.push(
+          `\n\n=== 项目宪法 (Project Constitution — MUST follow these rules) ===\n${context.constitution}`
+        );
+      }
+
+      parts.push(`\n\n=== 项目上下文 (Project Context) ===`);
+      if (context.techStack.length > 0) {
+        parts.push(`技术栈: ${context.techStack.join(", ")}`);
+      }
+      if (context.dependencies.length > 0) {
+        parts.push(`主要依赖: ${context.dependencies.slice(0, 25).join(", ")}`);
+      }
+      if (context.apiStructure.length > 0) {
+        parts.push(
+          `\n现有 API 文件:\n${context.apiStructure
+            .slice(0, 10)
+            .map((f) => `  - ${f}`)
+            .join("\n")}`
+        );
+      }
+      if (context.routeSummary) {
+        parts.push(`\n路由结构（摘要）:\n${context.routeSummary}`);
+      }
+      if (context.schema) {
+        parts.push(`\n数据库 Schema (Prisma):\n${context.schema.slice(0, 3000)}`);
+      }
+    }
+
+    return this.provider.generate(parts.join("\n"), specPrompt);
+  }
+}

package/core/spec-refiner.ts

@@ -0,0 +1,89 @@
+import { editor, confirm, select } from "@inquirer/prompts";
+import chalk from "chalk";
+import { AIProvider } from "./spec-generator";
+import { computeDiff, printDiff, printDiffSummary } from "./spec-versioning";
+
+export class SpecRefiner {
+  constructor(private provider: AIProvider) {}
+
+  async refineLoop(initialSpec: string): Promise<string> {
+    let currentSpec = initialSpec;
+    let round = 1;
+
+    while (true) {
+      console.log(chalk.cyan(`\n─── Spec Review (Round ${round}) ─────────────────`));
+      console.log(chalk.gray("  Opening spec in editor. Save and close to continue."));
+
+      // Open spec in editor for user to review/edit
+      currentSpec = await editor({
+        message: "Review and edit the spec:",
+        default: currentSpec,
+        postfix: ".md",
+        waitForUserInput: false,
+      });
+
+      console.log(chalk.green("  ✔ Spec saved."));
+
+      // Ask what to do next
+      const action = await select({
+        message: "What would you like to do?",
+        choices: [
+          { name: "✅  Finalize — proceed to code generation", value: "finalize" },
+          { name: "🤖  AI Polish — let AI improve clarity & completeness", value: "ai" },
+          { name: "✏️   Edit again — continue editing", value: "edit" },
+        ],
+      });
+
+      if (action === "finalize") {
+        break;
+      }
+
+      if (action === "ai") {
+        console.log(chalk.blue(`  AI (${this.provider.providerName}/${this.provider.modelName}) is polishing the spec...`));
+        try {
+          const improved = await this.provider.generate(
+            `Review the following feature spec and improve it for clarity, completeness, and technical feasibility.
+Keep the same structure and language (Chinese). Fix any gaps in API design, missing error cases, or vague requirements.
+Output ONLY the improved markdown spec, nothing else.
+
+${currentSpec}`,
+            "You are a Senior Tech Lead doing a spec review. Output only the improved Markdown."
+          );
+
+          console.log(chalk.yellow("\n  AI has suggested improvements. Opening diff in editor..."));
+          const acceptImproved = await confirm({
+            message: "Accept AI improvements? (opens editor so you can review first)",
+            default: true,
+          });
+
+          if (acceptImproved) {
+            // Show diff before opening editor
+            const diff = computeDiff(currentSpec, improved);
+            console.log(chalk.cyan("\n  ── AI Changes ──────────────────────────────"));
+            printDiffSummary(diff, "AI edits");
+            printDiff(diff);
+            console.log(chalk.cyan("  ────────────────────────────────────────────\n"));
+
+            // Let user review AI's version before accepting
+            currentSpec = await editor({
+              message: "Review AI-improved spec (edit if needed, then save):",
+              default: improved,
+              postfix: ".md",
+              waitForUserInput: false,
+            });
+            console.log(chalk.green("  ✔ AI-improved spec accepted."));
+          } else {
+            console.log(chalk.gray("  AI improvements discarded. Keeping your version."));
+          }
+        } catch (err) {
+          console.error(chalk.red("  AI improvement failed:"), err);
+          console.log(chalk.gray("  Continuing with current spec."));
+        }
+      }
+
+      round++;
+    }
+
+    return currentSpec;
+  }
+}