@gong-ym/ai-spec-auto 0.2.3

package/scripts/test-integration.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# 在测试项目中验证 visual 集成
+
+set -e
+
+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"
+VISUAL_SERVER="http://localhost:18780"
+
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║           测试项目 Visual 集成验证                           ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+
+# ========== 步骤 1：验证 visual 服务 ==========
+echo "🔍 步骤 1: 验证 visual 服务"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+HEALTH=$(curl -s http://localhost:18780/api/health 2>/dev/null || echo "failed")
+if [[ "$HEALTH" == *"ok"* ]]; then
+  echo "✅ visual 服务正常运行: http://localhost:18780"
+else
+  echo "❌ visual 服务未启动或异常"
+  echo "   请先在另一个终端执行："
+  echo "   cd $VISUAL_PATH"
+  echo "   ./start-with-db.sh"
+  exit 1
+fi
+echo ""
+
+# ========== 步骤 2：更新测试项目 ==========
+echo "🔄 步骤 2: 更新测试项目的 ai-spec-auto"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+cd "$TEST_PROJECT"
+
+echo "   更新 ai-spec-auto..."
+npm install "$AUTO_PATH" > /dev/null 2>&1
+echo "✅ ai-spec-auto 已更新"
+
+# 验证版本
+VERSION=$(npx ai-spec-auto --version 2>/dev/null || echo "unknown")
+echo "✅ 当前版本: $VERSION"
+
+# 验证 visual-hooks
+if [ -d "node_modules/ai-spec-auto/internal/visual-hooks" ]; then
+  echo "✅ visual-hooks 已安装"
+  HOOK_FILES=$(ls node_modules/ai-spec-auto/internal/visual-hooks/*.js 2>/dev/null | wc -l)
+  echo "   包含 $HOOK_FILES 个文件"
+else
+  echo "❌ visual-hooks 未找到"
+  exit 1
+fi
+echo ""
+
+# ========== 步骤 3：配置 visual 集成 ==========
+echo "⚙️  步骤 3: 配置 visual 集成"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+mkdir -p .ai-spec
+
+if [ -f ".ai-spec/visual-config.json" ]; then
+  echo "   ℹ️  visual-config.json 已存在"
+  CURRENT_URL=$(cat .ai-spec/visual-config.json | grep visual_url | cut -d'"' -f4 2>/dev/null || echo "")
+  if [ "$CURRENT_URL" != "$VISUAL_SERVER" ]; then
+    echo "   ⚠️  URL 不匹配，更新为: $VISUAL_SERVER"
+    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 "✅ 配置已更新"
+  else
+    echo "✅ 配置正确，无需修改"
+  fi
+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 "✅ 配置已创建"
+fi
+
+echo "   当前配置："
+cat .ai-spec/visual-config.json
+echo ""
+
+# ========== 步骤 4：执行 Collector 采集 ==========
+echo "📦 步骤 4: 执行 Collector 批量采集"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+cd "$VISUAL_PATH"
+
+echo "   采集测试项目的历史数据..."
+COLLECTOR_OUTPUT=$(npm run collector -- \
+  --workspace-id test-project-local \
+  --project "$TEST_PROJECT" \
+  --server "$VISUAL_SERVER" \
+  2>&1 | grep -A 20 "Collector CLI" || echo "")
+
+if [[ "$COLLECTOR_OUTPUT" == *"inserted"* ]] || [[ "$COLLECTOR_OUTPUT" == *"skipped"* ]]; then
+  echo "✅ Collector 采集完成"
+  echo "$COLLECTOR_OUTPUT" | grep -E "(inserted|skipped|total)" | head -5
+else
+  echo "⚠️  Collector 输出："
+  echo "$COLLECTOR_OUTPUT" | head -10
+fi
+echo ""
+
+# ========== 步骤 5：测试实时推送 ==========
+echo "🧪 步骤 5: 测试实时推送"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+cd "$TEST_PROJECT"
+
+echo "   执行 protocol-status 验证..."
+if npx ai-spec-auto protocol-status > /dev/null 2>&1; then
+  echo "✅ protocol-status 命令正常"
+else
+  echo "⚠️  protocol-status 命令异常（可能项目未初始化）"
+fi
+echo ""
+
+echo "   现在可以测试实时推送："
+echo ""
+echo "   cd $TEST_PROJECT"
+echo "   npx ai-spec-auto protocol-step --user-input '测试 visual 实时推送'"
+echo ""
+echo "   执行后，在 visual 控制台应该能看到新的 run 记录"
+echo ""
+
+# ========== 完成 ==========
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║                     ✅ 集成验证准备完成                      ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+echo "📋 当前状态："
+echo ""
+echo "  ✅ visual 服务运行: http://localhost:18780"
+echo "  ✅ MariaDB 运行: localhost:13306"
+echo "  ✅ ai-spec-auto 版本: $VERSION"
+echo "  ✅ visual-hooks 已安装"
+echo "  ✅ visual-config.json 已配置"
+echo "  ✅ Collector 采集已执行"
+echo ""
+echo "🎯 验证清单："
+echo ""
+echo "  1. 查看 visual 控制台："
+echo "     open http://localhost:18780/workspaces"
+echo ""
+echo "  2. 应该看到工作区 'test-project-local'"
+echo ""
+echo "  3. 测试实时推送："
+echo "     cd $TEST_PROJECT"
+echo "     npx ai-spec-auto protocol-step --user-input '测试实时推送'"
+echo ""
+echo "  4. 刷新控制台，验证新 run 是否出现"
+echo ""
+echo "  5. 测试降级机制（可选）："
+echo "     # 在 visual 终端按 Ctrl+C 停止服务"
+echo "     # 再次执行 protocol-step，协议应正常推进"
+echo ""

package/scripts/update-test-project.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# 快速更新测试项目的 ai-spec-auto 和配置 visual
+
+set -e
+
+AUTO_PATH="/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec"
+TEST_PROJECT="/Users/lizhenwei/workspace/test/test-ai-spec/prd-to-delivery-local-first-060/test_副本10"
+VISUAL_SERVER="http://localhost:3000"
+
+echo "=== 更新测试项目 ai-spec-auto ==="
+echo ""
+
+# 1. 更新 ai-spec-auto
+echo "1️⃣  更新 ai-spec-auto..."
+cd "$TEST_PROJECT"
+npm install "$AUTO_PATH"
+echo "   ✅ ai-spec-auto 更新完成"
+echo ""
+
+# 2. 验证更新
+echo "2️⃣  验证更新..."
+VERSION=$(npx ai-spec-auto --version 2>/dev/null || echo "unknown")
+echo "   当前版本: $VERSION"
+
+if [ -d "node_modules/ai-spec-auto/internal/visual-hooks" ]; then
+  echo "   ✅ visual-hooks 已安装"
+else
+  echo "   ❌ visual-hooks 未找到，请检查"
+  exit 1
+fi
+
+if [ -f "node_modules/ai-spec-auto/.ai-spec/visual-config.example.json" ]; then
+  echo "   ✅ visual-config.example.json 存在"
+else
+  echo "   ⚠️  visual-config.example.json 未找到"
+fi
+echo ""
+
+# 3. 创建或更新 visual 配置
+echo "3️⃣  配置 visual 集成..."
+mkdir -p .ai-spec
+
+if [ -f ".ai-spec/visual-config.json" ]; then
+  echo "   ℹ️  visual-config.json 已存在，跳过"
+  cat .ai-spec/visual-config.json
+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 ""
+
+# 4. 测试协议命令
+echo "4️⃣  测试协议命令..."
+if npx ai-spec-auto protocol-status > /dev/null 2>&1; then
+  echo "   ✅ protocol-status 命令正常"
+else
+  echo "   ⚠️  protocol-status 命令异常（可能项目未初始化 run）"
+fi
+echo ""
+
+# 5. 显示下一步操作
+echo "=== 更新完成 ==="
+echo ""
+echo "📋 下一步操作："
+echo ""
+echo "  1. 启动 visual 服务（如果尚未启动）："
+echo "     cd /Users/lizhenwei/workspace/vueworkspace/bairong/engineered-spec-visual"
+echo "     docker-compose up -d"
+echo ""
+echo "  2. 执行 Collector 批量采集："
+echo "     cd /Users/lizhenwei/workspace/vueworkspace/bairong/engineered-spec-visual"
+echo "     npm run collector -- \\"
+echo "       --workspace-id test-project-local \\"
+echo "       --project $TEST_PROJECT \\"
+echo "       --server http://localhost:3000"
+echo ""
+echo "  3. 启动新 run 测试实时推送："
+echo "     cd $TEST_PROJECT"
+echo "     npx ai-spec-auto protocol-step --user-input '测试 visual 集成'"
+echo ""
+echo "  4. 在浏览器查看控制台："
+echo "     open http://localhost:3000/workspaces"
+echo ""

package/scripts/upload-four-web.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+#
+# 将本站「four」静态内容同步到远端目录（默认 docs/four -> root@主机:/root/web/four/）
+#
+# 用法：
+#   export SSHPASS='你的密码'   # 仅在必须用密码登录时使用；更推荐 ssh-copy-id 配密钥
+#   ./scripts/upload-four-web.sh
+#
+# 环境变量（均可选）：
+#   UPLOAD_HOST          默认 82.156.14.216
+#   UPLOAD_USER          默认 root
+#   UPLOAD_REMOTE_PATH   默认 /root/web/four（会把本地目录「内容」同步到该路径下）
+#   UPLOAD_LOCAL_DIR       默认 docs/four（相对仓库根目录）
+#   UPLOAD_SSH_PORT        默认 2280
+#   SSHPASS                sshpass 读取的密码（勿写入仓库）
+#   UPLOAD_RSYNC_DELETE    设为 1 则在远端删除本地已删文件（慎用）
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+UPLOAD_HOST="${UPLOAD_HOST:-82.156.14.216}"
+UPLOAD_USER="${UPLOAD_USER:-root}"
+UPLOAD_REMOTE_PATH="${UPLOAD_REMOTE_PATH:-/root/web/four}"
+UPLOAD_LOCAL_DIR="${UPLOAD_LOCAL_DIR:-docs/four}"
+UPLOAD_SSH_PORT="${UPLOAD_SSH_PORT:-2280}"
+
+LOCAL_ABS="${REPO_ROOT}/${UPLOAD_LOCAL_DIR}"
+RSYNC_EXTRA=()
+if [[ "${UPLOAD_RSYNC_DELETE:-0}" == "1" ]]; then
+  RSYNC_EXTRA+=(--delete)
+fi
+
+if [[ ! -d "${LOCAL_ABS}" ]]; then
+  echo "错误：本地目录不存在：${LOCAL_ABS}" >&2
+  echo "可设置 UPLOAD_LOCAL_DIR 指向你的 four 目录。" >&2
+  exit 1
+fi
+
+RSYNC_TARGET="${UPLOAD_USER}@${UPLOAD_HOST}:${UPLOAD_REMOTE_PATH}/"
+
+if command -v sshpass >/dev/null 2>&1 && [[ -n "${SSHPASS:-}" ]]; then
+  export SSHPASS
+  RSYNC_RSH_CMD="sshpass -e ssh -p ${UPLOAD_SSH_PORT} -o StrictHostKeyChecking=accept-new"
+elif [[ -n "${SSHPASS:-}" ]] && ! command -v sshpass >/dev/null 2>&1; then
+  echo "已设置 SSHPASS 但未安装 sshpass。macOS: brew install sshpass" >&2
+  exit 1
+else
+  RSYNC_RSH_CMD="ssh -p ${UPLOAD_SSH_PORT} -o StrictHostKeyChecking=accept-new"
+  echo "提示：未使用 sshpass；将尝试交互式 SSH 密码或已配置的密钥。"
+fi
+
+echo "同步: ${LOCAL_ABS}/ -> ${RSYNC_TARGET}"
+rsync -avz "${RSYNC_EXTRA[@]}" -e "${RSYNC_RSH_CMD}" "${LOCAL_ABS}/" "${RSYNC_TARGET}"
+
+echo "完成。"

package/scripts/verify-install-ps1-bom.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const target = path.resolve(__dirname, "..", "install.ps1");
+
+if (!fs.existsSync(target)) {
+  console.error("[verify-install-ps1-bom] 未找到 install.ps1");
+  process.exit(1);
+}
+
+const buf = fs.readFileSync(target);
+const hasBom = buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf;
+
+if (!hasBom) {
+  console.error("[verify-install-ps1-bom] install.ps1 必须为 UTF-8 with BOM（EF BB BF）。");
+  console.error("[verify-install-ps1-bom] 请修复编码后再执行打包/发布。");
+  process.exit(1);
+}
+
+console.log("[verify-install-ps1-bom] OK: install.ps1 带 UTF-8 BOM");

package/src/agent/agent-context.js

@@ -0,0 +1,259 @@
+/**
+ * Agent Context — Agent 上下文边界管理
+ *
+ * 为每个 Agent 定义独立的上下文窗口、token 预算和可见文件范围。
+ * 支持敏感信息红脱和上下文裁剪。
+ */
+
+const { createChecksum } = require('../project/json-utils');
+
+// ============================================================
+// 默认配置
+// ============================================================
+
+const DEFAULT_CONTEXT_CONFIG = Object.freeze({
+  /** 最大 token 预算 */
+  maxTokens: 100000,
+  /** 预留给系统提示的 token 比例 */
+  systemPromptRatio: 0.2,
+  /** 预留给历史对话的 token 比例 */
+  historyRatio: 0.3,
+  /** 预留给当前任务的 token 比比 */
+  taskRatio: 0.5,
+  /** 是否启用红脱 */
+  redactSensitive: true,
+  /** 最大可见文件数 */
+  maxVisibleFiles: 50,
+});
+
+// ============================================================
+// 红脱规则
+// ============================================================
+
+/** 敏感信息正则模式列表 */
+const SENSITIVE_PATTERNS = [
+  { pattern: /(?:password|passwd|pwd)\s*[:=]\s*['"]?([^\s'"]+)/gi, replacement: 'password=***' },
+  { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"]?([^\s'"]+)/gi, replacement: 'api_key=***' },
+  { pattern: /(?:secret|token)\s*[:=]\s*['"]?([^\s'"]+)/gi, replacement: 'secret=***' },
+  { pattern: /(?:access[_-]?key|private[_-]?key)\s*[:=]\s*['"]?([^\s'"]+)/gi, replacement: 'access_key=***' },
+  { pattern: /-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----/g, replacement: '-----BEGIN REDACTED KEY-----' },
+];
+
+/**
+ * 对文本进行敏感信息红脱
+ * @param {string} text
+ * @returns {string}
+ */
+function redactSensitiveInfo(text) {
+  if (!text || typeof text !== 'string') return text;
+
+  let result = text;
+  for (const { pattern, replacement } of SENSITIVE_PATTERNS) {
+    // 重置 lastIndex（因为使用了 g 标志）
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+// ============================================================
+// AgentContext 类
+// ============================================================
+
+class AgentContext {
+  /**
+   * @param {Object} profile - AgentProfile
+   * @param {Object} [config] - 上下文配置覆盖
+   */
+  constructor(profile, config = {}) {
+    this.profile = profile;
+    this.config = { ...DEFAULT_CONTEXT_CONFIG, ...config };
+
+    /** 已消耗的 token 数量 */
+    this.consumedTokens = 0;
+    /** 可见文件列表 */
+    this.visibleFiles = [];
+    /** 上下文片段 */
+    this.fragments = [];
+  }
+
+  // ============================================================
+  // Token 预算
+  // ============================================================
+
+  /**
+   * 获取系统提示的 token 预算
+   * @returns {number}
+   */
+  getSystemPromptBudget() {
+    return Math.floor(this.config.maxTokens * this.config.systemPromptRatio);
+  }
+
+  /**
+   * 获取历史对话的 token 预算
+   * @returns {number}
+   */
+  getHistoryBudget() {
+    return Math.floor(this.config.maxTokens * this.config.historyRatio);
+  }
+
+  /**
+   * 获取当前任务的 token 预算
+   * @returns {number}
+   */
+  getTaskBudget() {
+    return Math.floor(this.config.maxTokens * this.config.taskRatio);
+  }
+
+  /**
+   * 获取剩余可用 token 数
+   * @returns {number}
+   */
+  getRemainingTokens() {
+    return Math.max(0, this.config.maxTokens - this.consumedTokens);
+  }
+
+  /**
+   * 检查是否有足够 token
+   * @param {number} estimatedTokens
+   * @returns {boolean}
+   */
+  hasEnoughTokens(estimatedTokens) {
+    return this.getRemainingTokens() >= estimatedTokens;
+  }
+
+  /**
+   * 消耗 token
+   * @param {number} count
+   * @returns {boolean} 是否成功
+   */
+  consumeTokens(count) {
+    if (!this.hasEnoughTokens(count)) return false;
+    this.consumedTokens += count;
+    return true;
+  }
+
+  // ============================================================
+  // 文件可见性
+  // ============================================================
+
+  /**
+   * 设置可见文件列表（受 maxVisibleFiles 限制）
+   * @param {string[]} files
+   */
+  setVisibleFiles(files) {
+    const maxFiles = this.config.maxVisibleFiles;
+    this.visibleFiles = files.slice(0, maxFiles);
+  }
+
+  /**
+   * 添加可见文件
+   * @param {string} filePath
+   * @returns {boolean} 是否成功（未超过限制）
+   */
+  addVisibleFile(filePath) {
+    if (this.visibleFiles.length >= this.config.maxVisibleFiles) return false;
+    if (!this.visibleFiles.includes(filePath)) {
+      this.visibleFiles.push(filePath);
+    }
+    return true;
+  }
+
+  /**
+   * 检查文件是否在可见范围内
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  isFileVisible(filePath) {
+    return this.visibleFiles.includes(filePath);
+  }
+
+  // ============================================================
+  // 上下文片段
+  // ============================================================
+
+  /**
+   * 添加上下文片段
+   * @param {Object} params
+   * @param {string} params.type - 片段类型 (system/task/file/message)
+   * @param {string} params.content - 片段内容
+   * @param {number} [params.estimatedTokens] - 预估 token 数
+   */
+  addFragment({ type, content, estimatedTokens = 0 }) {
+    const processedContent = this.config.redactSensitive ? redactSensitiveInfo(content) : content;
+
+    if (estimatedTokens > 0 && !this.hasEnoughTokens(estimatedTokens)) {
+      return false;
+    }
+
+    this.fragments.push({
+      type,
+      content: processedContent,
+      estimatedTokens,
+      addedAt: new Date().toISOString(),
+    });
+
+    if (estimatedTokens > 0) {
+      this.consumeTokens(estimatedTokens);
+    }
+
+    return true;
+  }
+
+  /**
+   * 获取指定类型的片段
+   * @param {string} type
+   * @returns {Array}
+   */
+  getFragmentsByType(type) {
+    return this.fragments.filter((f) => f.type === type);
+  }
+
+  /**
+   * 获取所有片段内容（按添加顺序）
+   * @returns {string[]}
+   */
+  getAllContent() {
+    return this.fragments.map((f) => f.content);
+  }
+
+  /**
+   * 清空上下文
+   */
+  reset() {
+    this.consumedTokens = 0;
+    this.visibleFiles = [];
+    this.fragments = [];
+  }
+
+  // ============================================================
+  // 序列化
+  // ============================================================
+
+  /**
+   * 导出上下文摘要
+   * @returns {Object}
+   */
+  toSummary() {
+    return {
+      agentId: this.profile.agentId,
+      maxTokens: this.config.maxTokens,
+      consumedTokens: this.consumedTokens,
+      remainingTokens: this.getRemainingTokens(),
+      visibleFileCount: this.visibleFiles.length,
+      fragmentCount: this.fragments.length,
+      budgets: {
+        systemPrompt: this.getSystemPromptBudget(),
+        history: this.getHistoryBudget(),
+        task: this.getTaskBudget(),
+      },
+    };
+  }
+}
+
+module.exports = {
+  AgentContext,
+  redactSensitiveInfo,
+  SENSITIVE_PATTERNS,
+  DEFAULT_CONTEXT_CONFIG,
+};