ai-spec-dev 0.41.0 → 0.42.0

package/.ai-spec-workspace.json

@@ -0,0 +1,17 @@
+{
+  "name": "bookmark-demo",
+  "repos": [
+    {
+      "name": "demo-backend",
+      "path": "demo-backend",
+      "type": "node-express",
+      "role": "backend"
+    },
+    {
+      "name": "demo-frontend",
+      "path": "demo-frontend",
+      "type": "react",
+      "role": "frontend"
+    }
+  ]
+}

package/.ai-spec.json

@@ -0,0 +1,7 @@
+{
+  "provider": "glm",
+  "model": "glm-4.5-air",
+  "codegenMode": "api",
+  "codegenProvider": "glm",
+  "codegenModel": "glm-4.5-air"
+}

package/cli/pipeline/single-repo.ts

@@ -51,6 +51,7 @@ import {
   loadVcrRecording,
 } from "../../core/vcr";
 import { printBanner } from "./helpers";
+import { startSpinner, startStage } from "../../core/cli-ui";
 
 // ─── Pipeline Options ────────────────────────────────────────────────────────
 
@@ -168,7 +169,7 @@ export async function runSingleRepoPipeline(
       console.log(chalk.yellow(`  ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
     }
   } else {
-    console.log(chalk.yellow("  Constitution : not found — auto-generating..."));
+    const constitutionSpinner = startSpinner("Constitution not found — auto-generating...");
     try {
       const constitutionGen = new ConstitutionGenerator(
         createProvider(specProviderName, specApiKey, specModelName)
@@ -176,9 +177,9 @@ export async function runSingleRepoPipeline(
       const constitutionContent = await constitutionGen.generate(currentDir);
       await constitutionGen.saveConstitution(currentDir, constitutionContent);
       context.constitution = constitutionContent;
-      console.log(chalk.green(`  Constitution : ✔ generated and saved (.ai-spec-constitution.md)`));
+      constitutionSpinner.succeed("Constitution generated and saved (.ai-spec-constitution.md)");
     } catch (err) {
-      console.log(chalk.yellow(`  Constitution : ⚠ auto-generation failed (${(err as Error).message}), continuing without it.`));
+      constitutionSpinner.fail(`Constitution auto-generation failed (${(err as Error).message}), continuing without it.`);
     }
   }
 
@@ -214,17 +215,18 @@ export async function runSingleRepoPipeline(
   let initialTasks: import("../../core/task-generator").SpecTask[] = [];
 
   runLogger.stageStart("spec_gen", { provider: specProviderName, model: specModelName });
+  const specSpinner = startStage("spec_gen", `Generating spec with ${specProviderName}/${specModelName}...`);
   try {
     if (opts.skipTasks) {
       const { SpecGenerator } = await import("../../core/spec-generator");
       const generator = new SpecGenerator(specProvider);
       initialSpec = await generator.generateSpec(idea, context, architectureDecision);
-      console.log(chalk.green("  ✔ Spec generated."));
+      specSpinner.succeed("Spec generated.");
     } else {
       const result = await generateSpecWithTasks(specProvider, idea, context, architectureDecision);
       initialSpec = result.spec;
       initialTasks = result.tasks;
-      console.log(chalk.green(`  ✔ Spec generated.`));
+      specSpinner.succeed("Spec generated.");
       if (initialTasks.length > 0) {
         console.log(chalk.green(`  ✔ ${initialTasks.length} tasks generated (combined call).`));
       } else {
@@ -233,8 +235,8 @@ export async function runSingleRepoPipeline(
     }
     runLogger.stageEnd("spec_gen", { taskCount: initialTasks.length });
   } catch (err) {
+    specSpinner.fail(`Spec generation failed: ${(err as Error).message}`);
     runLogger.stageFail("spec_gen", (err as Error).message);
-    console.error(chalk.red("  ✘ Spec generation failed:"), err);
     process.exit(1);
   }
 
@@ -262,7 +264,9 @@ export async function runSingleRepoPipeline(
       console.log(chalk.blue("\n[3.4/6] Spec quality assessment..."));
     }
     runLogger.stageStart("spec_assess");
+    const assessSpinner = startStage("spec_assess", "Evaluating spec quality...");
     const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? undefined);
+    assessSpinner.stop();
     if (assessment) {
       runLogger.stageEnd("spec_assess", { overallScore: assessment.overallScore });
       if (!opts.auto) printSpecAssessment(assessment);
@@ -366,21 +370,24 @@ export async function runSingleRepoPipeline(
     console.log(chalk.blue("\n[DSL] Extracting structured DSL from spec..."));
     console.log(chalk.gray(`  Provider: ${specProviderName}/${specModelName}`));
     runLogger.stageStart("dsl_extract");
+    const dslSpinner = startStage("dsl_extract", "Extracting DSL from spec...");
     try {
       const isFrontend = isFrontendDeps(context.dependencies);
-      if (isFrontend) console.log(chalk.gray("  Frontend project detected — using ComponentSpec extractor"));
+      if (isFrontend) {
+        dslSpinner.update("🔗  Extracting DSL (frontend ComponentSpec mode)...");
+      }
       const dslExtractor = new DslExtractor(specProvider);
       extractedDsl = await dslExtractor.extract(finalSpec, { auto: opts.auto, isFrontend });
       if (extractedDsl) {
         runLogger.stageEnd("dsl_extract", { endpoints: extractedDsl.endpoints?.length ?? 0, models: extractedDsl.models?.length ?? 0 });
-        console.log(chalk.green("  ✔ DSL extracted and validated."));
+        dslSpinner.succeed("DSL extracted and validated.");
       } else {
         runLogger.stageEnd("dsl_extract", { skipped: true });
-        console.log(chalk.yellow("  ⚠ DSL skipped — codegen will use Spec + Tasks only."));
+        dslSpinner.fail("DSL skipped — codegen will use Spec + Tasks only.");
       }
     } catch (err) {
       runLogger.stageFail("dsl_extract", (err as Error).message);
-      console.log(chalk.yellow(`  ⚠ DSL extraction error: ${(err as Error).message} — continuing without DSL.`));
+      dslSpinner.fail(`DSL extraction error: ${(err as Error).message} — continuing without DSL.`);
     }
   }
 
@@ -590,6 +597,7 @@ export async function runSingleRepoPipeline(
   if (!opts.skipReview) {
     console.log(chalk.blue("\n[9/9] Automated code review (3-pass: architecture + implementation + impact/complexity)..."));
     runLogger.stageStart("review");
+    const reviewSpinner = startStage("review", "Running 3-pass code review...");
     const reviewer = new CodeReviewer(specProvider, workingDir);
     const savedSpec = await fs.readFile(specFile, "utf-8");
 
@@ -598,6 +606,7 @@ export async function runSingleRepoPipeline(
     } else {
       reviewResult = await reviewer.reviewCode(savedSpec, specFile);
     }
+    reviewSpinner.succeed("Code review complete.");
     runLogger.stageEnd("review");
 
     // Surface Pass 0 compliance score

package/core/cli-ui.ts

@@ -0,0 +1,136 @@
+import chalk from "chalk";
+
+// ─── Spinner ──────────────────────────────────────────────────────────────────
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface Spinner {
+  /** Update the text shown after the spinner. */
+  update(text: string): void;
+  /** Stop the spinner and show a final message. */
+  stop(finalText?: string): void;
+  /** Stop with a success (✔) mark. */
+  succeed(text: string): void;
+  /** Stop with a failure (✘) mark. */
+  fail(text: string): void;
+}
+
+/**
+ * Start a CLI spinner that renders on a single line.
+ * Works in any TTY; silently degrades to static text in non-TTY (CI).
+ */
+export function startSpinner(text: string): Spinner {
+  const isTTY = process.stderr.isTTY;
+  let frame = 0;
+  let currentText = text;
+  let stopped = false;
+
+  function render() {
+    if (stopped) return;
+    const symbol = chalk.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length]);
+    if (isTTY) {
+      process.stderr.write(`\r  ${symbol} ${currentText}${" ".repeat(10)}`);
+    }
+    frame++;
+  }
+
+  // Print initial line for non-TTY
+  if (!isTTY) {
+    process.stderr.write(`  … ${currentText}\n`);
+  }
+
+  const timer = setInterval(render, 80);
+  render();
+
+  return {
+    update(newText: string) {
+      currentText = newText;
+    },
+    stop(finalText?: string) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (isTTY) {
+        process.stderr.write(`\r${" ".repeat(currentText.length + 20)}\r`);
+      }
+      if (finalText) {
+        process.stderr.write(`  ${finalText}\n`);
+      }
+    },
+    succeed(successText: string) {
+      this.stop(chalk.green(`✔ ${successText}`));
+    },
+    fail(failText: string) {
+      this.stop(chalk.red(`✘ ${failText}`));
+    },
+  };
+}
+
+// ─── Retry Countdown ──────────────────────────────────────────────────────────
+
+/**
+ * Show an animated countdown during retry wait.
+ * Displays error details + a live seconds countdown.
+ */
+export async function retryCountdown(opts: {
+  attempt: number;
+  maxAttempts: number;
+  waitMs: number;
+  errorMessage: string;
+  label: string;
+}): Promise<void> {
+  const { attempt, maxAttempts, waitMs, errorMessage, label } = opts;
+  const isTTY = process.stderr.isTTY;
+
+  // Error box
+  const shortErr = errorMessage.length > 120
+    ? errorMessage.slice(0, 117) + "..."
+    : errorMessage;
+
+  process.stderr.write("\n");
+  process.stderr.write(chalk.yellow(`  ┌─ Retry ${attempt}/${maxAttempts} `) + chalk.gray(`[${label}]`) + chalk.yellow(` ${"─".repeat(Math.max(1, 40 - label.length))}\n`));
+  process.stderr.write(chalk.yellow(`  │ `) + chalk.white(shortErr) + "\n");
+  process.stderr.write(chalk.yellow(`  │ `) + chalk.gray(`Waiting before retry...`) + "\n");
+
+  // Animated countdown
+  const totalSeconds = Math.ceil(waitMs / 1000);
+  for (let s = totalSeconds; s > 0; s--) {
+    const bar = chalk.green("█".repeat(totalSeconds - s)) + chalk.gray("░".repeat(s));
+    const line = chalk.yellow(`  │ `) + `${bar} ${chalk.bold.white(`${s}s`)}`;
+    if (isTTY) {
+      process.stderr.write(`\r${line}${" ".repeat(10)}`);
+    }
+    await new Promise<void>((r) => setTimeout(r, 1000));
+  }
+
+  if (isTTY) {
+    process.stderr.write(`\r${" ".repeat(70)}\r`);
+  }
+  process.stderr.write(chalk.yellow(`  └─ `) + chalk.cyan(`Retrying now...`) + "\n\n");
+}
+
+// ─── Stage Progress ───────────────────────────────────────────────────────────
+
+const STAGE_ICONS: Record<string, string> = {
+  context_load: "📂",
+  design_dialogue: "💬",
+  spec_gen: "📝",
+  spec_refine: "✏️ ",
+  spec_assess: "📊",
+  dsl_extract: "🔗",
+  dsl_gap_feedback: "🔍",
+  codegen: "⚙️ ",
+  test_gen: "🧪",
+  error_feedback: "🔧",
+  review: "🔎",
+  self_eval: "📈",
+};
+
+/**
+ * Start a pipeline stage with a spinner.
+ * Returns a handle to succeed/fail/update the stage display.
+ */
+export function startStage(stageKey: string, label: string): Spinner {
+  const icon = STAGE_ICONS[stageKey] ?? "▸";
+  return startSpinner(`${icon}  ${label}`);
+}

package/core/code-generator.ts

@@ -22,6 +22,7 @@ import {
 } from "./codegen/helpers";
 import { topoSortLayerTasks, printTaskProgress, LAYER_ICONS } from "./codegen/topo-sort";
 import { estimateTokens, getDefaultBudget } from "./token-budget";
+import { startSpinner } from "./cli-ui";
 
 // Re-export public symbols for backward compatibility
 export { extractBehavioralContract } from "./codegen/helpers";
@@ -654,6 +655,7 @@ ${constitutionSection}
 === ${existingContent ? "Existing content (modify and return the complete file)" : "Create this file from scratch"} ===
 ${existingContent || "Output only the complete file content."}`;
 
+      const fileSpinner = startSpinner(`${prefix}Generating ${chalk.bold(item.file)}...`);
       try {
         const raw = await this.provider.generate(codePrompt, systemPrompt);
         const fileContent = stripCodeFences(raw);
@@ -661,11 +663,11 @@ ${existingContent || "Output only the complete file content."}`;
         await fs.ensureDir(path.dirname(fullPath));
         await fs.writeFile(fullPath, fileContent, "utf-8");
         getActiveLogger()?.fileWritten(item.file);
-        console.log(`${prefix}${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)} ${chalk.green("✔")}`);
+        fileSpinner.succeed(`${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)}`);
         successCount++;
         writtenFiles.push(item.file);
       } catch (err) {
-        console.log(`${prefix}${chalk.red("✘")} ${chalk.bold(item.file)} — ${chalk.red((err as Error).message)}`);
+        fileSpinner.fail(`${chalk.bold(item.file)} — ${(err as Error).message}`);
       }
     }
 

package/core/error-feedback.ts

@@ -7,6 +7,7 @@ import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
 import { SpecDSL } from "./dsl-types";
 import { buildDslContextSection } from "./dsl-extractor";
 import { getActiveSnapshot } from "./run-snapshot";
+import { startSpinner } from "./cli-ui";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -369,16 +370,17 @@ ${fileContent}
 
 Output ONLY the complete fixed file content. No markdown fences, no explanations.`;
 
+    const fixSpinner = startSpinner(`Fixing ${chalk.bold(file)} (${fileErrors.length} error(s))...`);
     try {
       const raw = await provider.generate(prompt, getCodeGenSystemPrompt());
       const fixed = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
       await getActiveSnapshot()?.snapshotFile(fullPath);
       await fs.writeFile(fullPath, fixed, "utf-8");
       results.push({ fixed: true, file, explanation: `Fixed ${fileErrors.length} error(s)` });
-      console.log(chalk.green(`  ✔ Auto-fixed: ${file}`));
+      fixSpinner.succeed(`Auto-fixed: ${file}`);
     } catch (err) {
       results.push({ fixed: false, file, explanation: `AI fix failed: ${(err as Error).message}` });
-      console.log(chalk.yellow(`  ⚠ Could not auto-fix: ${file}`));
+      fixSpinner.fail(`Could not auto-fix: ${file}`);
     }
   }
 

package/core/provider-utils.ts

@@ -1,6 +1,5 @@
 import chalk from "chalk";
-
-const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+import { retryCountdown } from "./cli-ui";
 
 // ─── Error Classification ──────────────────────────────────────────────────────
 
@@ -112,12 +111,14 @@ export async function withReliability<T>(
         throw classifyError(err, label);
       }
       const waitMs = attempt === 0 ? 2_000 : 6_000;
-      console.warn(
-        chalk.yellow(`  ⚠ ${label} failed (attempt ${attempt + 1}/${retries + 1}), retrying in ${waitMs / 1000}s`) +
-          chalk.gray(` — ${(err as Error).message}`)
-      );
       onRetry?.(attempt + 1, err);
-      await sleep(waitMs);
+      await retryCountdown({
+        attempt: attempt + 1,
+        maxAttempts: retries + 1,
+        waitMs,
+        errorMessage: (err as Error).message ?? String(err),
+        label,
+      });
     }
   }
   /* istanbul ignore next */

package/demo-backend/.ai-spec-constitution.md

@@ -0,0 +1,65 @@
+# Project Constitution
+
+## 1. 架构规则 (Architecture Rules)
+- **分层架构**：项目采用三层架构 `routes → controllers → services → database`。
+- **禁止跨层调用**：
+  - `routes` 层仅负责定义路由和中间件，不能包含业务逻辑。
+  - `controllers` 层负责接收请求、调用 `services` 和返回响应，不能直接操作数据库。
+  - `services` 层封装核心业务逻辑，是唯一允许直接调用数据访问层（如 Prisma）的层级。
+- **模块组织**：功能模块按领域划分，每个模块包含独立的 `routes.ts`, `controller.ts`, `service.ts` 文件。
+
+## 2. 命名规范 (Naming Conventions)
+- **文件命名**：使用 `kebab-case`（如 `user-profile.controller.ts`）。
+- **变量/函数**：使用 `camelCase`（如 `getUserById`）。
+- **类/接口**：使用 `PascalCase`（如 `UserService`）。
+- **路由路径**：使用 `kebab-case`，资源名词复数（如 `/api/v1/user-profiles`）。
+
+## 3. API 规范 (API Patterns)
+- **路由前缀**：
+  - 客户端 API：`/api/v1/...`
+  - 管理端 API：`/api/v1/admin/...`
+- **统一响应结构**：
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {}
+  }
+  ```
+- **错误码规范**：
+  - `400`：客户端请求错误（参数错误、验证失败）
+  - `401`：未认证
+  - `403`：无权限
+  - `404`：资源不存在
+  - `500`：服务器内部错误
+- **认证/鉴权**：使用 `auth.middleware.ts` 保护需要认证的路由，位于 `middleware/` 目录。
+
+## 4. 数据层规范 (Data Layer Rules)
+- **数据库访问**：仅允许在 `service` 层使用 Prisma Client 进行数据库操作。
+- **模型命名**：Prisma model 使用 `PascalCase`（如 `UserProfile`），表名使用 `snake_case`（如 `user_profiles`）。
+- **事务处理**：复杂业务逻辑使用 Prisma 的 `$transaction` API 保证数据一致性。
+
+## 5. 错误处理规范 (Error Handling Patterns)
+- **统一错误中间件**：使用 `error.middleware.ts` 捕获所有错误，位于 `middleware/` 目录。
+- **错误抛出**：在 `service` 或 `controller` 中抛出 `AppError`（自定义错误类，包含 `code` 和 `message`）。
+- **已知错误码**：
+  - `VALIDATION_ERROR` (400)
+  - `UNAUTHORIZED` (401)
+  - `FORBIDDEN` (403)
+  - `NOT_FOUND` (404)
+  - `INTERNAL_ERROR` (500)
+
+## 6. 禁区 (Red Lines — Never Violate)
+- [ ] **禁止**在 `controller` 或 `route` 层直接操作数据库（必须通过 `service`）。
+- [ ] **禁止**创建重复的配置文件（如错误码、路由定义），必须追加到现有文件。
+- [ ] **禁止**使用 `any` 类型，必须定义明确的接口或类型。
+- [ ] **禁止**提交未通过 `vitest` 测试的代码。
+
+## 7. 测试规范 (Testing Rules)
+- **测试文件位置**：与源文件同目录，命名规则为 `*.test.ts` 或 `*.spec.ts`。
+- **测试覆盖**：必须为所有 `service` 和 `controller` 方法编写单元测试，关键业务流程需包含集成测试。
+- **测试框架**：使用 `vitest` 进行单元测试和集成测试，使用 `supertest` 进行 HTTP 接口测试。
+
+## 8. 共享配置文件清单 (Shared Config Files — Append-Only)
+
+(No shared config files detected — will be populated on first run)

package/demo-backend/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "demo-backend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "cors": "^2.8.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "ts-node": "^10.9.2",
+    "vitest": "^2.1.0"
+  }
+}

package/demo-backend/prisma/schema.prisma

@@ -0,0 +1,22 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Bookmark {
+  id        String   @id @default(uuid())
+  title     String
+  url       String
+  tags      String[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("bookmarks")
+}

package/demo-backend/specs/feature-1-bookmark-id-uuid-title-string-required-url-str-v1.dsl.json

@@ -0,0 +1,186 @@
+{
+  "version": "1.0",
+  "feature": {
+    "id": "bookmark-management-system",
+    "title": "Bookmark 管理系统",
+    "description": "实现个人书签管理系统，支持创建、查看、编辑、删除网页书签，通过标签分类和分页浏览。"
+  },
+  "models": [
+    {
+      "name": "Bookmark",
+      "description": "书签数据模型，包含标题、URL和标签等信息",
+      "fields": [
+        {
+          "name": "id",
+          "type": "String",
+          "required": true,
+          "unique": true,
+          "description": ""
+        },
+        {
+          "name": "title",
+          "type": "String",
+          "required": true,
+          "unique": false,
+          "description": "书签标题"
+        },
+        {
+          "name": "url",
+          "type": "String",
+          "required": true,
+          "unique": false,
+          "description": "书签URL，需为有效URL格式"
+        },
+        {
+          "name": "tags",
+          "type": "String[]",
+          "required": false,
+          "unique": false,
+          "description": "标签数组"
+        },
+        {
+          "name": "createdAt",
+          "type": "DateTime",
+          "required": true,
+          "unique": false,
+          "description": "创建时间"
+        },
+        {
+          "name": "updatedAt",
+          "type": "DateTime",
+          "required": true,
+          "unique": false,
+          "description": "更新时间"
+        }
+      ],
+      "relations": []
+    }
+  ],
+  "endpoints": [
+    {
+      "id": "EP-001",
+      "method": "GET",
+      "path": "/api/v1/bookmarks",
+      "description": "获取书签分页列表",
+      "auth": false,
+      "request": {
+        "body": {},
+        "query": {
+          "limit": "integer (positive, default 20)",
+          "offset": "integer (non-negative, default 0)"
+        },
+        "params": {}
+      },
+      "successStatus": 200,
+      "successDescription": "返回书签数组及总数",
+      "errors": [
+        {
+          "status": 400,
+          "code": "VALIDATION_ERROR",
+          "description": "查询参数验证失败，如 limit 或 offset 无效"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    },
+    {
+      "id": "EP-002",
+      "method": "POST",
+      "path": "/api/v1/bookmarks",
+      "description": "创建新书签",
+      "auth": false,
+      "request": {
+        "body": {
+          "title": "string (required, non-empty)",
+          "url": "string (required, valid URL format)",
+          "tags": "string array (optional)"
+        },
+        "query": {},
+        "params": {}
+      },
+      "successStatus": 201,
+      "successDescription": "返回新创建的书签信息",
+      "errors": [
+        {
+          "status": 400,
+          "code": "VALIDATION_ERROR",
+          "description": "请求体验证失败，如 title 为空或 url 格式无效"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    },
+    {
+      "id": "EP-003",
+      "method": "PUT",
+      "path": "/api/v1/bookmarks/:id",
+      "description": "全量更新指定书签",
+      "auth": false,
+      "request": {
+        "body": {
+          "title": "string (required)",
+          "url": "string (required, valid URL format)",
+          "tags": "string array (required)"
+        },
+        "query": {},
+        "params": {
+          "id": "string (UUID format)"
+        }
+      },
+      "successStatus": 200,
+      "successDescription": "返回更新后的书签信息",
+      "errors": [
+        {
+          "status": 400,
+          "code": "VALIDATION_ERROR",
+          "description": "请求体验证失败"
+        },
+        {
+          "status": 404,
+          "code": "NOT_FOUND",
+          "description": "书签未找到"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    },
+    {
+      "id": "EP-004",
+      "method": "DELETE",
+      "path": "/api/v1/bookmarks/:id",
+      "description": "删除指定书签",
+      "auth": false,
+      "request": {
+        "body": {},
+        "query": {},
+        "params": {
+          "id": "string (UUID format)"
+        }
+      },
+      "successStatus": 204,
+      "successDescription": "无响应体",
+      "errors": [
+        {
+          "status": 404,
+          "code": "NOT_FOUND",
+          "description": "书签未找到"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    }
+  ],
+  "behaviors": []
+}