@gong-ym/ai-spec-auto 0.2.3

package/scripts/post-publish-verify.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+TARGET_DIR="${1:-/Users/lizhenwei/workspace/test/test-ai-spec/ai-spec-cursor-test}"
+PACKAGE_NAME="${AI_SPEC_PACKAGE_NAME:-$(node -e "process.stdout.write(require(process.argv[1]).name)" "${PACKAGE_ROOT}/package.json")}"
+PACKAGE_VERSION="${AI_SPEC_MANIFEST_VERSION:-$(node -e "process.stdout.write(require(process.argv[1]).version)" "${PACKAGE_ROOT}/package.json")}"
+PACKAGE_SPEC="${AI_SPEC_PACKAGE_SPEC:-${PACKAGE_NAME}@${PACKAGE_VERSION}}"
+TIMESTAMP="$(date '+%Y%m%d-%H%M%S')"
+SNAPSHOT_DIR="${PACKAGE_ROOT}/docs/paser_three/test-snapshots"
+SNAPSHOT_PREFIX="${SNAPSHOT_DIR}/${TIMESTAMP}-${PACKAGE_VERSION}-post-publish"
+SETUP_LOG="${SNAPSHOT_PREFIX}.setup.log"
+SMOKE_JSON="${SNAPSHOT_PREFIX}.smoke.json"
+AUTOFIX_JSON="${SNAPSHOT_PREFIX}.auto-fix.json"
+SNAPSHOT_MD="${SNAPSHOT_PREFIX}.md"
+
+STATUS_SETUP="pending"
+STATUS_SMOKE="pending"
+STATUS_AUTOFIX="pending"
+STATUS_OVERALL="running"
+ERROR_STEP=""
+ERROR_MESSAGE=""
+INSTALLED_VERSION="(not-installed)"
+SMOKE_RUN_STATUS="(not-run)"
+SMOKE_ARCHIVE_DIR="(not-run)"
+AUTOFIX_FAILURE_ROLE="(not-run)"
+AUTOFIX_GUARDIAN_ROLE="(not-run)"
+AUTOFIX_VERIFICATION="(not-run)"
+AUTOFIX_CHECKPOINTS="(not-run)"
+
+mkdir -p "${SNAPSHOT_DIR}"
+TARGET_DIR="$(cd "${TARGET_DIR}" && pwd 2>/dev/null || echo "${TARGET_DIR}")"
+
+write_snapshot() {
+  cat > "${SNAPSHOT_MD}" <<EOF
+# 发版后验证快照
+
+## 基本信息
+
+- 时间：${TIMESTAMP}
+- 包：\`${PACKAGE_SPEC}\`
+- 目标项目：\`${TARGET_DIR}\`
+- 已安装版本：\`${INSTALLED_VERSION}\`
+- 总体状态：\`${STATUS_OVERALL}\`
+
+## 验证结果
+
+| 项目 | 状态 | 说明 |
+| --- | --- | --- |
+| 安装/同步 | ${STATUS_SETUP} | setup 脚本输出见 \`${SETUP_LOG}\` |
+| smoke 闭环 | ${STATUS_SMOKE} | run_status=\`${SMOKE_RUN_STATUS}\`，archive=\`${SMOKE_ARCHIVE_DIR}\` |
+| auto-fix 回环 | ${STATUS_AUTOFIX} | 首次失败角色=\`${AUTOFIX_FAILURE_ROLE}\`，修复后角色=\`${AUTOFIX_GUARDIAN_ROLE}\`，verification=\`${AUTOFIX_VERIFICATION}\`，checkpoint_count=\`${AUTOFIX_CHECKPOINTS}\` |
+
+## 文件快照
+
+- setup 日志：\`${SETUP_LOG}\`
+- smoke JSON：\`${SMOKE_JSON}\`
+- auto-fix JSON：\`${AUTOFIX_JSON}\`
+- 当前快照：\`${SNAPSHOT_MD}\`
+
+## 查看建议
+
+1. 先看 \`${SNAPSHOT_MD}\`，确认总体状态与三项结果。
+2. 再看 \`${SMOKE_JSON}\`，确认 demo-runtime-smoke 是否仍能走到归档成功。
+3. 再看 \`${AUTOFIX_JSON}\`，确认失败后只回 implementer 一次，并进入 guardian。
+4. 如果要看临时验证目录，可打开：
+   - \`${TARGET_DIR}/.tmp/runtime-smoke-demo\`
+   - \`${TARGET_DIR}/.tmp/auto-fix-cli-demo\`
+
+## 清理方式
+
+如果你看完要删除本轮快照，可执行：
+
+\`\`\`bash
+rm -f "${SETUP_LOG}" "${SMOKE_JSON}" "${AUTOFIX_JSON}" "${SNAPSHOT_MD}"
+\`\`\`
+
+如果你连测试临时目录也一起清掉，可再执行：
+
+\`\`\`bash
+rm -rf "${TARGET_DIR}/.tmp/runtime-smoke-demo" "${TARGET_DIR}/.tmp/auto-fix-cli-demo"
+\`\`\`
+EOF
+
+  if [[ -n "${ERROR_STEP}" || -n "${ERROR_MESSAGE}" ]]; then
+    {
+      echo
+      echo "## 异常信息"
+      echo
+      echo "- 失败步骤：\`${ERROR_STEP:-unknown}\`"
+      echo "- 失败原因：\`${ERROR_MESSAGE:-unknown}\`"
+    } >> "${SNAPSHOT_MD}"
+  fi
+}
+
+trap write_snapshot EXIT
+
+run_step() {
+  local step_name="$1"
+  shift
+  echo "==> ${step_name}"
+  "$@"
+}
+
+capture_installed_version() {
+  INSTALLED_VERSION="$(node -e "const path=require('path');const name=process.argv[1];const target=process.argv[2];const file=path.join(target,'node_modules',...name.split('/'),'package.json');process.stdout.write(require(file).version);" "${PACKAGE_NAME}" "${TARGET_DIR}" 2>/dev/null || true)"
+  if [[ -z "${INSTALLED_VERSION}" ]]; then
+    INSTALLED_VERSION="(not-installed)"
+  fi
+}
+
+capture_smoke_summary() {
+  SMOKE_RUN_STATUS="$(node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(String((j.current_run && j.current_run.status) || (j.summary && j.summary.run_status) || j.run_status || '(unknown)'));" "${SMOKE_JSON}" 2>/dev/null || echo '(unknown)')"
+  SMOKE_ARCHIVE_DIR="$(node -e "const fs=require('fs');const path=require('path');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));const proposal=j.current_run&&j.current_run.artifacts&&j.current_run.artifacts.proposal;process.stdout.write(String(proposal ? path.dirname(proposal) : ((j.summary && j.summary.archive_dir) || j.archive_dir || '(none)')));" "${SMOKE_JSON}" 2>/dev/null || echo '(unknown)')"
+}
+
+capture_autofix_summary() {
+  AUTOFIX_FAILURE_ROLE="$(node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(String((j.first_failure && j.first_failure.current_role) || '(unknown)'));" "${AUTOFIX_JSON}" 2>/dev/null || echo '(unknown)')"
+  AUTOFIX_GUARDIAN_ROLE="$(node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(String((j.after_fix && j.after_fix.current_role) || '(unknown)'));" "${AUTOFIX_JSON}" 2>/dev/null || echo '(unknown)')"
+  AUTOFIX_VERIFICATION="$(node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(String((j.after_fix && j.after_fix.verification) || '(unknown)'));" "${AUTOFIX_JSON}" 2>/dev/null || echo '(unknown)')"
+  AUTOFIX_CHECKPOINTS="$(node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(String((j.after_fix && j.after_fix.checkpoint_count) || '(unknown)'));" "${AUTOFIX_JSON}" 2>/dev/null || echo '(unknown)')"
+}
+
+main() {
+  echo "==> package: ${PACKAGE_SPEC}"
+  echo "==> target: ${TARGET_DIR}"
+  echo "==> snapshot: ${SNAPSHOT_MD}"
+
+  ERROR_STEP="setup"
+  if bash "${PACKAGE_ROOT}/scripts/setup-cursor-spec-archive-test.sh" "${TARGET_DIR}" > "${SETUP_LOG}" 2>&1; then
+    STATUS_SETUP="passed"
+  else
+    STATUS_SETUP="failed"
+    STATUS_OVERALL="failed"
+    ERROR_MESSAGE="setup-cursor-spec-archive-test.sh 执行失败，详情见 ${SETUP_LOG}"
+    return 1
+  fi
+  capture_installed_version
+
+  ERROR_STEP="smoke"
+  rm -rf "${TARGET_DIR}/.tmp/runtime-smoke-demo"
+  if (
+    cd "${TARGET_DIR}"
+    ./node_modules/.bin/ai-spec demo-runtime-smoke --target ./.tmp/runtime-smoke-demo --json > "${SMOKE_JSON}"
+  ); then
+    STATUS_SMOKE="passed"
+    capture_smoke_summary
+  else
+    STATUS_SMOKE="failed"
+    STATUS_OVERALL="failed"
+    ERROR_MESSAGE="demo-runtime-smoke 执行失败，详情见 ${SMOKE_JSON}"
+    return 1
+  fi
+
+  ERROR_STEP="auto-fix"
+  if node "${PACKAGE_ROOT}/scripts/post-publish-auto-fix-check.js" --target-root "${TARGET_DIR}" --package-name "${PACKAGE_NAME}" --output "${AUTOFIX_JSON}" > /dev/null; then
+    STATUS_AUTOFIX="passed"
+    capture_autofix_summary
+  else
+    STATUS_AUTOFIX="failed"
+    STATUS_OVERALL="failed"
+    ERROR_MESSAGE="auto-fix CLI 验证失败，详情见 ${AUTOFIX_JSON}"
+    return 1
+  fi
+
+  STATUS_OVERALL="passed"
+  ERROR_STEP=""
+  ERROR_MESSAGE=""
+  echo "==> done"
+  echo "snapshot: ${SNAPSHOT_MD}"
+}
+
+main "$@"

package/scripts/setup-cursor-manual-test.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+TARGET_DIR="${1:-.}"
+PROFILE="${AI_SPEC_TEST_PROFILE:-vue}"
+IDE="${AI_SPEC_TEST_IDE:-cursor}"
+PACKAGE_NAME="${AI_SPEC_PACKAGE_NAME:-$(node -e "process.stdout.write(require(process.argv[1]).name)" "${PACKAGE_ROOT}/package.json")}"
+PACKAGE_VERSION="${AI_SPEC_MANIFEST_VERSION:-$(node -e "process.stdout.write(require(process.argv[1]).version)" "${PACKAGE_ROOT}/package.json")}"
+PACKAGE_SPEC="${AI_SPEC_PACKAGE_SPEC:-${PACKAGE_NAME}@${PACKAGE_VERSION}}"
+INIT_EXTRA_ARGS="${AI_SPEC_INIT_EXTRA_ARGS:---no-uipro --no-lint --no-husky -y}"
+
+TARGET_DIR="$(cd "${TARGET_DIR}" && pwd)"
+MANIFEST_PATH="${TARGET_DIR}/manifest.json"
+
+if command -v pnpm >/dev/null 2>&1; then
+  RUNNER=(pnpm dlx "${PACKAGE_SPEC}")
+else
+  RUNNER=(npx "${PACKAGE_SPEC}")
+fi
+
+echo "==> target: ${TARGET_DIR}"
+echo "==> package: ${PACKAGE_SPEC}"
+echo "==> profile: ${PROFILE}"
+echo "==> ide: ${IDE}"
+echo "==> init args: ${INIT_EXTRA_ARGS}"
+echo "==> runner: ${RUNNER[*]}"
+
+echo "==> clean old ai-spec artifacts"
+rm -rf \
+  "${TARGET_DIR}/.agents" \
+  "${TARGET_DIR}/.cursor" \
+  "${TARGET_DIR}/.claude" \
+  "${TARGET_DIR}/.ai-spec" \
+  "${TARGET_DIR}/openspec"
+rm -f \
+  "${TARGET_DIR}/node_modules/.bin/ai-spec" \
+  "${TARGET_DIR}/node_modules/.bin/ai-spec-auto" \
+  "${TARGET_DIR}/node_modules/.bin/ai-spec-auto"
+
+echo "==> write manifest.json"
+cat > "${MANIFEST_PATH}" <<EOF
+{
+  "schema_version": 1,
+  "manifest_type": "hub-install",
+  "name": "cursor-manual-test",
+  "description": "Manual test manifest for ${PACKAGE_NAME}@latest",
+  "version": "${PACKAGE_VERSION}",
+  "profile": "${PROFILE}",
+  "ides": ["${IDE}"],
+  "scenario_packages": ["frontend-basic"],
+  "roles": [
+    "task-orchestrator",
+    "requirement-analyst",
+    "frontend-implementer",
+    "code-guardian",
+    "archive-change"
+  ],
+  "skills": [
+    "create-proposal",
+    "design-analysis",
+    "execute-task",
+    "archive-change"
+  ],
+  "rules": [
+    "coding-standard",
+    "api-standard",
+    "route-standard",
+    "style-standard",
+    "generic-constraints",
+    "test-standard"
+  ],
+  "entry_role": "task-orchestrator",
+  "notes": [
+    "Manual Cursor installation and sync validation"
+  ]
+}
+EOF
+
+echo "==> init"
+(
+  cd "${TARGET_DIR}"
+  # Current-stage manual testing focuses on /spec-start summary UX.
+  # Skip optional installers and force non-interactive init to avoid waiting in silent OpenSpec setup.
+  # shellcheck disable=SC2086
+  "${RUNNER[@]}" init . --profile "${PROFILE}" --ide "${IDE}" ${INIT_EXTRA_ARGS}
+)
+
+echo "==> sync"
+(
+  cd "${TARGET_DIR}"
+  "${RUNNER[@]}" sync . --manifest ./manifest.json
+)
+
+echo "==> check"
+(
+  cd "${TARGET_DIR}"
+  "${RUNNER[@]}" check .
+)
+
+echo "==> done"
+echo "manifest: ${MANIFEST_PATH}"
+echo "next:"
+echo "  1. reopen Cursor"
+echo "  2. run /spec-start 创建一个好看的登录页面，没有UI，mock数据即可"

package/scripts/setup-cursor-spec-archive-test.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+TARGET_DIR="${1:-/Users/lizhenwei/workspace/test/test-ai-spec/ai-spec-cursor-test}"
+PROFILE="${AI_SPEC_TEST_PROFILE:-vue}"
+IDE="${AI_SPEC_TEST_IDE:-cursor}"
+PACKAGE_NAME="${AI_SPEC_PACKAGE_NAME:-$(node -e "process.stdout.write(require(process.argv[1]).name)" "${PACKAGE_ROOT}/package.json")}"
+PACKAGE_VERSION="${AI_SPEC_MANIFEST_VERSION:-$(node -e "process.stdout.write(require(process.argv[1]).version)" "${PACKAGE_ROOT}/package.json")}"
+PACKAGE_SPEC="${AI_SPEC_PACKAGE_SPEC:-${PACKAGE_NAME}@${PACKAGE_VERSION}}"
+INIT_EXTRA_ARGS="${AI_SPEC_INIT_EXTRA_ARGS:---no-uipro --no-lint --no-husky -y}"
+
+mkdir -p "${TARGET_DIR}"
+TARGET_DIR="$(cd "${TARGET_DIR}" && pwd)"
+MANIFEST_PATH="${TARGET_DIR}/manifest.json"
+
+if command -v pnpm >/dev/null 2>&1; then
+  RUNNER=(pnpm dlx "${PACKAGE_SPEC}")
+else
+  RUNNER=(npx "${PACKAGE_SPEC}")
+fi
+
+echo "==> target: ${TARGET_DIR}"
+echo "==> package: ${PACKAGE_SPEC}"
+echo "==> profile: ${PROFILE}"
+echo "==> ide: ${IDE}"
+echo "==> init args: ${INIT_EXTRA_ARGS}"
+echo "==> runner: ${RUNNER[*]}"
+
+echo "==> clean old ai-spec artifacts"
+rm -rf \
+  "${TARGET_DIR}/.agents" \
+  "${TARGET_DIR}/.cursor" \
+  "${TARGET_DIR}/.claude" \
+  "${TARGET_DIR}/.ai-spec" \
+  "${TARGET_DIR}/openspec"
+rm -f \
+  "${TARGET_DIR}/node_modules/.bin/ai-spec" \
+  "${TARGET_DIR}/node_modules/.bin/ai-spec-auto" \
+  "${TARGET_DIR}/node_modules/.bin/ai-spec-auto"
+
+echo "==> write manifest.json"
+cat > "${MANIFEST_PATH}" <<EOF
+{
+  "schema_version": 1,
+  "manifest_type": "hub-install",
+  "name": "cursor-spec-archive-test",
+  "description": "Manual Cursor test manifest for specs + archive confirmation",
+  "version": "${PACKAGE_VERSION}",
+  "profile": "${PROFILE}",
+  "ides": ["${IDE}"],
+  "scenario_packages": ["frontend-basic"],
+  "roles": [
+    "task-orchestrator",
+    "requirement-analyst",
+    "frontend-implementer",
+    "code-guardian",
+    "archive-change"
+  ],
+  "skills": [
+    "create-proposal",
+    "design-analysis",
+    "execute-task",
+    "archive-change"
+  ],
+  "rules": [
+    "coding-standard",
+    "api-standard",
+    "route-standard",
+    "style-standard",
+    "generic-constraints",
+    "test-standard"
+  ],
+  "entry_role": "task-orchestrator",
+  "notes": [
+    "Manual Cursor installation for specs generation and archive confirmation validation"
+  ]
+}
+EOF
+
+echo "==> init"
+(
+  cd "${TARGET_DIR}"
+  # shellcheck disable=SC2086
+  "${RUNNER[@]}" init . --profile "${PROFILE}" --ide "${IDE}" ${INIT_EXTRA_ARGS}
+)
+
+echo "==> sync"
+(
+  cd "${TARGET_DIR}"
+  "${RUNNER[@]}" sync . --manifest ./manifest.json
+)
+
+echo "==> validate registry"
+(
+  cd "${TARGET_DIR}"
+  "${RUNNER[@]}" validate-registry
+)
+
+echo "==> done"
+echo "manifest: ${MANIFEST_PATH}"
+echo "manual test steps:"
+echo "  1. reopen Cursor in ${TARGET_DIR}"
+echo "  2. run: /spec-start 创建一个商品 mock 页面，只做演示版，数据本地 mock"
+echo "  3. requirement 阶段后检查: openspec/changes/<change-id>/specs/ui/spec.md"
+echo "  4. code-guardian 完成后，确认是否出现“是否归档”的摘要询问"
+echo "  5. 输入: 同意归档"
+echo "  6. 检查: openspec/specs/ui/spec.md 与 openspec/changes/archive/"
+echo "  7. 若要测跳过归档，再跑一轮并输入: 先不归档"

package/scripts/setup-visual-integration.sh

@@ -0,0 +1,225 @@
+#!/bin/bash
+# 完整的 visual 集成配置和验证脚本
+
+set -e
+
+VISUAL_SERVER="${VISUAL_SERVER:-http://localhost:3000}"
+AUTO_PATH="/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec"
+VISUAL_PATH="/Users/lizhenwei/workspace/vueworkspace/bairong/engineered-spec-visual"
+TEST_PROJECT="/Users/lizhenwei/workspace/test/test-ai-spec/prd-to-delivery-local-first-060/test_副本10"
+
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║     engineered-spec-visual 集成配置与验证                         ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+
+# ========== 阶段 1：检查环境 ==========
+echo "📋 阶段 1: 检查环境"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# 检查 auto 项目
+if [ ! -d "$AUTO_PATH" ]; then
+  echo "❌ auto 项目不存在: $AUTO_PATH"
+  exit 1
+fi
+echo "✅ auto 项目: $AUTO_PATH"
+
+# 检查 visual 项目
+if [ ! -d "$VISUAL_PATH" ]; then
+  echo "❌ visual 项目不存在: $VISUAL_PATH"
+  exit 1
+fi
+echo "✅ visual 项目: $VISUAL_PATH"
+
+# 检查测试项目
+if [ ! -d "$TEST_PROJECT" ]; then
+  echo "❌ 测试项目不存在: $TEST_PROJECT"
+  exit 1
+fi
+echo "✅ 测试项目: $TEST_PROJECT"
+
+# 检查 Docker
+if ! command -v docker &> /dev/null; then
+  echo "❌ Docker 未安装"
+  exit 1
+fi
+echo "✅ Docker 已安装"
+
+# 检查 docker-compose
+if ! command -v docker-compose &> /dev/null; then
+  echo "❌ docker-compose 未安装"
+  exit 1
+fi
+echo "✅ docker-compose 已安装"
+
+echo ""
+
+# ========== 阶段 2：启动 visual 服务 ==========
+echo "🚀 阶段 2: 启动 visual 服务"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+cd "$VISUAL_PATH"
+
+# 检查 .env 文件
+if [ ! -f ".env" ]; then
+  echo "⚠️  .env 文件不存在，从模板创建..."
+  cp .env.example .env
+  echo "   请编辑 .env 文件设置 DB_PASSWORD 和 NEXTAUTH_SECRET"
+  echo "   然后重新运行此脚本"
+  exit 1
+fi
+echo "✅ .env 文件存在"
+
+# 启动服务
+echo "   启动 docker-compose..."
+docker-compose up -d
+
+# 等待服务启动
+echo "   等待服务启动（最多 60 秒）..."
+for i in {1..60}; do
+  if curl -s http://localhost:3000/api/health > /dev/null 2>&1; then
+    echo "✅ visual 服务启动成功"
+    break
+  fi
+  sleep 1
+done
+
+# 验证健康检查
+HEALTH=$(curl -s http://localhost:3000/api/health || echo "failed")
+if [[ "$HEALTH" == *"ok"* ]]; then
+  echo "✅ 健康检查通过"
+else
+  echo "❌ 健康检查失败: $HEALTH"
+  exit 1
+fi
+
+echo ""
+
+# ========== 阶段 3：更新测试项目 ==========
+echo "🔄 阶段 3: 更新测试项目"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+cd "$TEST_PROJECT"
+
+# 更新 ai-spec-auto
+echo "   更新 ai-spec-auto..."
+npm install "$AUTO_PATH"
+
+# 验证版本
+VERSION=$(npx ai-spec-auto --version 2>/dev/null || echo "unknown")
+echo "✅ ai-spec-auto 版本: $VERSION"
+
+# 验证 visual-hooks
+if [ -d "node_modules/ai-spec-auto/internal/visual-hooks" ]; then
+  echo "✅ visual-hooks 已安装"
+else
+  echo "❌ visual-hooks 未找到"
+  exit 1
+fi
+
+echo ""
+
+# ========== 阶段 4：配置 visual ==========
+echo "⚙️  阶段 4: 配置 visual"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+mkdir -p .ai-spec
+
+if [ -f ".ai-spec/visual-config.json" ]; then
+  echo "   ℹ️  visual-config.json 已存在"
+  cat .ai-spec/visual-config.json | head -5
+else
+  cat > .ai-spec/visual-config.json <<EOF
+{
+  "enabled": true,
+  "visual_url": "$VISUAL_SERVER",
+  "workspace_id": "test-project-local",
+  "workspace_name": "测试项目本地实例",
+  "push_mode": "hook",
+  "push_timeout_ms": 3000,
+  "retry_times": 1
+}
+EOF
+  echo "✅ visual-config.json 已创建"
+fi
+
+echo ""
+
+# ========== 阶段 5：执行 Collector 采集 ==========
+echo "📦 阶段 5: 执行 Collector 采集"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+cd "$VISUAL_PATH"
+
+# 安装 visual 项目依赖（如果需要）
+if [ ! -d "node_modules" ]; then
+  echo "   安装 visual 项目依赖..."
+  npm install
+fi
+
+# 执行 Collector
+echo "   执行 Collector 采集..."
+COLLECTOR_RESULT=$(npm run collector -- \
+  --workspace-id test-project-local \
+  --project "$TEST_PROJECT" \
+  --server "$VISUAL_SERVER" \
+  --json 2>/dev/null || echo '{"ingest":{"ok":false}}')
+
+# 解析结果
+INSERTED=$(echo "$COLLECTOR_RESULT" | jq -r '.ingest.inserted // 0' 2>/dev/null || echo "0")
+SKIPPED=$(echo "$COLLECTOR_RESULT" | jq -r '.ingest.skipped // 0' 2>/dev/null || echo "0")
+TOTAL=$(echo "$COLLECTOR_RESULT" | jq -r '.ingest.total // 0' 2>/dev/null || echo "0")
+
+if [ "$INSERTED" -gt 0 ] || [ "$SKIPPED" -gt 0 ]; then
+  echo "✅ Collector 采集成功"
+  echo "   插入: $INSERTED, 跳过: $SKIPPED, 总计: $TOTAL"
+else
+  echo "⚠️  Collector 采集失败或无数据"
+  echo "   结果: $COLLECTOR_RESULT"
+fi
+
+echo ""
+
+# ========== 阶段 6：验证集成 ==========
+echo "🧪 阶段 6: 验证集成"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# 验证控制台
+echo "   验证 visual 控制台..."
+WORKSPACES=$(curl -s http://localhost:3000/api/workspaces 2>/dev/null || echo "failed")
+if [[ "$WORKSPACES" != "failed" ]]; then
+  echo "✅ 控制台 API 正常"
+else
+  echo "❌ 控制台 API 异常"
+fi
+
+echo ""
+
+# ========== 完成 ==========
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║                     🎉 集成配置完成                          ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+echo "📋 验证清单："
+echo ""
+echo "  ✅ visual 服务运行: http://localhost:3000"
+echo "  ✅ ai-spec-auto 已更新: $VERSION"
+echo "  ✅ visual-hooks 已安装"
+echo "  ✅ visual-config.json 已配置"
+echo "  ✅ Collector 采集完成: 插入 $INSERTED 条"
+echo ""
+echo "🚀 下一步操作："
+echo ""
+echo "  1. 查看 visual 控制台："
+echo "     open http://localhost:3000/workspaces"
+echo ""
+echo "  2. 测试实时推送："
+echo "     cd $TEST_PROJECT"
+echo "     npx ai-spec-auto protocol-step --user-input '测试实时推送'"
+echo ""
+echo "  3. 测试降级机制："
+echo "     docker-compose -f $VISUAL_PATH/docker-compose.yml stop visual"
+echo "     cd $TEST_PROJECT"
+echo "     npx ai-spec-auto protocol-step --user-input '测试降级'"
+echo "     # 协议应该正常推进，不受影响"
+echo ""