@gong-ym/ai-spec-auto 0.2.3

package/internal/visual-hooks/push-client.js

@@ -0,0 +1,189 @@
+/**
+ * Visual Push Client
+ * 
+ * 功能：通过 HTTP/WebSocket 推送事件到 visual 服务
+ * 特性：
+ * - 超时控制
+ * - 自动重试
+ * - 优雅降级
+ */
+
+const https = require('https');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { URL } = require('url');
+
+/**
+ * 创建推送客户端
+ * @param {VisualConfig} config
+ * @returns {PushClient}
+ */
+function createPushClient(config) {
+  const {
+    visual_url,
+    workspace_id,
+    target_dir,
+    push_timeout_ms = 3000,
+    retry_times = 1
+  } = config;
+
+  // 在 hook 上下文里 process.cwd() 通常就是项目根目录；带上以便 visual 自动落 Workspace.rootPath，
+  // 让控制下行的文件兜底通道（.ai-spec/inbox/）能正确解析到本地路径。
+  const rootPath = (() => {
+    try {
+      return fs.realpathSync(path.resolve(target_dir || process.cwd()));
+    } catch (_err) {
+      return null;
+    }
+  })();
+
+  return {
+    /**
+     * 推送事件到 visual 服务
+     * @param {PushEvent} event
+     * @returns {Promise<void>}
+     */
+    async push(event) {
+      let url;
+      try {
+        url = new URL('/api/internal/ingest/raw', visual_url);
+      } catch (err) {
+        throw new Error(`invalid visual_url: ${visual_url}`);
+      }
+
+      const protocol = url.protocol === 'https:' ? https : http;
+
+      const payload = {
+        sourceKind: 'hook-push',
+        workspaceId: workspace_id,
+        root_path: rootPath,
+        rawEvents: [{
+          sourceKind: 'hook-event',
+          sourcePath: 'internal/visual-hooks',
+          eventType: event.eventType,
+          eventKey: `${event.runId}:${event.eventType}:${Date.now()}`,
+          dedupeKey: generateDedupeKey(event),
+          checksum: generateChecksum(event.payload),
+          occurredAt: new Date().toISOString(),
+          entityType: 'run',
+          entityId: event.runId,
+          payload: event.payload
+        }]
+      };
+
+      let lastError = null;
+
+      for (let attempt = 0; attempt <= retry_times; attempt++) {
+        try {
+          await sendRequest(protocol, url, payload, push_timeout_ms);
+          return; // 成功，直接返回
+        } catch (err) {
+          lastError = err;
+          if (attempt < retry_times) {
+            console.warn(`[visual-hooks] push failed (attempt ${attempt + 1}/${retry_times + 1}), retrying...`);
+            await sleep(500 * (attempt + 1)); // 指数退避
+          }
+        }
+      }
+
+      // 所有重试都失败
+      throw lastError;
+    }
+  };
+}
+
+/**
+ * 发送 HTTP 请求
+ * @param {typeof http | typeof https} protocol
+ * @param {URL} url
+ * @param {object} payload
+ * @param {number} timeoutMs
+ * @returns {Promise<void>}
+ */
+function sendRequest(protocol, url, payload, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      req.destroy();
+      reject(new Error(`push timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    // 勿把 workspaceId 放进 X-Workspace-ID：Node 的 HTTP 头值必须是单字节字符，
+    // 中文等非 ASCII 会抛 Invalid character in header content。ingest 已从 JSON body 读取 workspaceId。
+    const req = protocol.request(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'ai-spec-auto-visual-hooks/1.0'
+      }
+    }, (res) => {
+      clearTimeout(timeout);
+
+      let body = '';
+      res.on('data', chunk => body += chunk);
+
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve();
+        } else {
+          reject(new Error(`push failed: ${res.statusCode} ${body}`));
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    req.write(JSON.stringify(payload));
+    req.end();
+  });
+}
+
+/**
+ * 生成去重键
+ * @param {PushEvent} event
+ * @returns {string}
+ */
+function generateDedupeKey(event) {
+  const content = `${event.eventType}|${event.runId}|${JSON.stringify(event.payload)}`;
+  return simpleHash(content);
+}
+
+/**
+ * 生成校验和
+ * @param {object} payload
+ * @returns {string}
+ */
+function generateChecksum(payload) {
+  return simpleHash(JSON.stringify(payload));
+}
+
+/**
+ * 简单哈希函数（用于去重和校验）
+ * @param {string} str
+ * @returns {string}
+ */
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * 延迟函数
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  createPushClient
+};

package/internal/visual-hooks/receipt-pusher.js

@@ -0,0 +1,176 @@
+/**
+ * Visual Receipt Pusher
+ *
+ * 把 inbox-consumer 的处理结果（applied / rejected / conflict）作为
+ * `control.receipt` ingest 事件回灌给 visual。
+ *
+ * 设计约束：
+ * - 仅使用 Node 内置（http/https/fs/path/crypto），零依赖
+ * - 严格短超时，任何错误必须静默
+ * - 不读取或修改本地协议状态，仅做出站
+ */
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+const crypto = require('crypto');
+const { URL } = require('url');
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function loadBridgeConfig(targetDir) {
+  const candidates = [
+    path.join(targetDir, '.ai-spec/visual-bridge.json'),
+    path.join(targetDir, '.ai-spec/visual-config.json'),
+  ];
+  for (const file of candidates) {
+    const data = safeReadJson(file);
+    if (data && typeof data === 'object') {
+      return data;
+    }
+  }
+  return null;
+}
+
+function getServerUrl(bridge) {
+  return bridge?.server_url || bridge?.serverUrl || bridge?.visual_url || null;
+}
+
+function getWorkspaceId(bridge) {
+  return bridge?.workspace_id || bridge?.workspaceId || null;
+}
+
+function shortHash(value) {
+  return crypto
+    .createHash('sha256')
+    .update(typeof value === 'string' ? value : JSON.stringify(value))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function sendRequest({ url, payload, headers, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const protocol = parsed.protocol === 'https:' ? https : http;
+    const req = protocol.request(parsed, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'ai-spec-auto-receipt-pusher/1.0',
+        ...headers,
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf-8');
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+          resolve({ statusCode: res.statusCode, body: text });
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${text.slice(0, 200)}`));
+        }
+      });
+    });
+    const timer = setTimeout(() => {
+      req.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    req.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    req.on('close', () => clearTimeout(timer));
+    req.write(JSON.stringify(payload));
+    req.end();
+  });
+}
+
+/**
+ * 推送一组 receipts 给 visual
+ * @param {{ targetDir?: string, receipts: Array<object>, timeoutMs?: number }} opts
+ * @returns {Promise<{ pushed: number, error?: string }>}
+ */
+async function pushReceipts(opts = {}) {
+  const targetDir = opts.targetDir || process.cwd();
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 1500;
+  const receipts = Array.isArray(opts.receipts) ? opts.receipts : [];
+  if (receipts.length === 0) {
+    return { pushed: 0 };
+  }
+
+  const bridge = loadBridgeConfig(targetDir);
+  if (!bridge || bridge.enabled === false) {
+    return { pushed: 0, error: 'bridge disabled' };
+  }
+  const serverUrl = getServerUrl(bridge);
+  const workspaceId = getWorkspaceId(bridge);
+  if (!serverUrl || !workspaceId) {
+    return { pushed: 0, error: 'missing server_url/workspace_id' };
+  }
+
+  let endpoint;
+  try {
+    endpoint = new URL('/api/internal/ingest/raw', serverUrl).toString();
+  } catch (err) {
+    return { pushed: 0, error: `invalid url: ${err.message}` };
+  }
+
+  const now = new Date().toISOString();
+  const payload = {
+    sourceKind: 'control-receipt',
+    workspaceId,
+    rawEvents: receipts.map((receipt, index) => {
+      const dedupeBase = `${receipt.outbox_id || ''}|${receipt.result || ''}|${receipt.received_at || ''}`;
+      return {
+        sourceKind: 'control-receipt',
+        sourcePath: 'internal/visual-hooks/receipt-pusher',
+        eventType: 'control.receipt',
+        eventKey: `${receipt.outbox_id || `r_${index}`}:control.receipt:${Date.now()}`,
+        dedupeKey: shortHash(dedupeBase),
+        checksum: shortHash(receipt),
+        occurredAt: receipt.received_at || now,
+        entityType: 'control_outbox',
+        entityId: String(receipt.outbox_id || ''),
+        payload: {
+          outbox_id: receipt.outbox_id || null,
+          command: receipt.command || null,
+          result: receipt.result || 'unknown',
+          reason: receipt.reason || null,
+          applied_state_snapshot: receipt.applied_state_snapshot || null,
+          received_at: receipt.received_at || now,
+        },
+      };
+    }),
+  };
+
+  try {
+    // workspaceId 只在 JSON body 中传递；不要写入 X-Workspace-ID（非 ASCII 目录名会导致 Node 抛错）。
+    await sendRequest({
+      url: endpoint,
+      payload,
+      headers: {
+        ...(bridge.connect_token ? { 'X-Connect-Token': bridge.connect_token } : {}),
+      },
+      timeoutMs,
+    });
+    return { pushed: receipts.length };
+  } catch (err) {
+    return { pushed: 0, error: err.message };
+  }
+}
+
+module.exports = {
+  pushReceipts,
+};

package/internal/visual-hooks/runtime-state-pusher.js

@@ -0,0 +1,128 @@
+const fs = require('fs');
+const path = require('path');
+
+const { initVisualHooks } = require('./index');
+
+const pendingVisualRuntimeStatePushes = new Set();
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function appendVisualPushTrace(targetDir, payload) {
+  try {
+    const tracePath = path.join(targetDir, '.ai-spec', 'internal', 'visual-push.jsonl');
+    fs.mkdirSync(path.dirname(tracePath), { recursive: true });
+    fs.appendFileSync(tracePath, `${JSON.stringify({
+      at: new Date().toISOString(),
+      ...payload,
+    })}\n`, 'utf8');
+  } catch {
+    // ignore: visual push trace must never block the protocol flow
+  }
+}
+
+async function pushVisualRuntimeStateSnapshotNow(targetDir) {
+  const resolvedTargetDir = path.resolve(targetDir || '.');
+  const currentRunPath = path.join(resolvedTargetDir, '.ai-spec', 'current-run.json');
+  const currentRun = readJsonIfExists(currentRunPath);
+  if (!currentRun?.run_id) {
+    const result = { pushed: false, reason: 'missing-current-run' };
+    appendVisualPushTrace(resolvedTargetDir, {
+      result: result.reason,
+      run_id: null,
+      workspace_id: null,
+      targetDir: resolvedTargetDir,
+      config_source: null,
+    });
+    return result;
+  }
+
+  let hooks = null;
+  try {
+    hooks = initVisualHooks({ targetDir: resolvedTargetDir });
+  } catch (error) {
+    const result = {
+      pushed: false,
+      reason: 'hook-init-failed',
+      error: error?.message || String(error),
+    };
+    appendVisualPushTrace(resolvedTargetDir, {
+      result: result.reason,
+      run_id: currentRun.run_id,
+      workspace_id: currentRun.workspace_id || null,
+      targetDir: resolvedTargetDir,
+      config_source: null,
+      error: result.error,
+    });
+    return result;
+  }
+
+  if (!hooks?.onRunStateChange) {
+    const result = { pushed: false, reason: 'hooks-disabled' };
+    appendVisualPushTrace(resolvedTargetDir, {
+      result: result.reason,
+      run_id: currentRun.run_id,
+      workspace_id: currentRun.workspace_id || hooks?.config?.workspace_id || null,
+      targetDir: resolvedTargetDir,
+      config_source: hooks?.config?.config_source || null,
+    });
+    return result;
+  }
+
+  const response = await hooks.onRunStateChange({
+    ...currentRun,
+    workspace_id: currentRun.workspace_id || hooks.config?.workspace_id || path.basename(resolvedTargetDir),
+  });
+
+  const normalizedWorkspaceId =
+    currentRun.workspace_id || hooks.config?.workspace_id || path.basename(resolvedTargetDir);
+  const result = response?.ok === false
+    ? {
+        pushed: false,
+        reason: 'request-failed',
+        error: response.error || 'unknown push failure',
+      }
+    : {
+        pushed: true,
+        run_id: currentRun.run_id,
+        workspace_id: normalizedWorkspaceId,
+      };
+
+  appendVisualPushTrace(resolvedTargetDir, {
+    result: result.pushed ? 'pushed' : result.reason,
+    run_id: currentRun.run_id,
+    workspace_id: normalizedWorkspaceId,
+    targetDir: resolvedTargetDir,
+    config_source: hooks.config?.config_source || null,
+    error: result.pushed ? null : result.error || null,
+  });
+
+  return result;
+}
+
+function pushVisualRuntimeStateSnapshot(targetDir) {
+  const pushPromise = pushVisualRuntimeStateSnapshotNow(targetDir)
+    .catch(() => undefined)
+    .finally(() => {
+      pendingVisualRuntimeStatePushes.delete(pushPromise);
+    });
+  pendingVisualRuntimeStatePushes.add(pushPromise);
+  return pushPromise;
+}
+
+async function drainVisualRuntimeStatePushes() {
+  if (pendingVisualRuntimeStatePushes.size === 0) {
+    return;
+  }
+  await Promise.allSettled([...pendingVisualRuntimeStatePushes]);
+}
+
+module.exports = {
+  pushVisualRuntimeStateSnapshot,
+  pushVisualRuntimeStateSnapshotNow,
+  drainVisualRuntimeStatePushes,
+};

package/openspec/config.yaml.template

@@ -0,0 +1,52 @@
+# OpenSpec 项目配置（由 ai-spec-auto 提供的增强版模板）
+# install.sh / install.ps1 在 L3 安装时会将此模板写入 openspec/config.yaml，
+# 并同步 openspec/schemas/expert-delivery 到目标项目。
+# 详见 https://github.com/Fission-AI/OpenSpec
+
+schema: expert-delivery
+
+context: |
+  本项目接入 ai-spec-auto 专家协同平台：
+  - rules: .agents/rules/
+  - skills: .agents/skills/
+  - roles: .agents/roles/
+  - flows: .agents/flows/
+  - runtime: .ai-spec/
+
+  项目执行时优先遵循：
+  1. 仓库现有代码中的目录、路由、接口、样式、测试约定
+  2. context/PROJECT.md 中的项目背景与仓库事实
+  3. .agents/rules/ 中的团队规范
+  4. .agents/skills/ 中的执行技能
+
+rules:
+  proposal:
+    - "先收敛目标、范围、非目标项、默认假设和风险，再进入实现。"
+    - "能从项目规则和代码推断的内容，优先写入 assumptions，不重复标记为缺失输入。"
+    - "涉及页面、路由、接口、状态、样式时，必须对齐项目既有落点。"
+    - "proposal.md 需要写清业务目标、工程目标、组件复用策略、设计链接和变更入口。"
+  specs:
+    - "需求必须落为可测试的增量规范和场景。"
+    - "涉及 UI 时，验收场景应覆盖关键布局、状态和交互。"
+    - "涉及安装脚本、路径、运行态文件、归档或 IDE 适配时，必须明确 macOS / Linux / Windows 的行为差异与兼容边界。"
+    - "涉及产物生成、同步或删除时，必须明确目标定位依据，优先使用显式清单、注册表或固定映射，不依赖模糊模式匹配。"
+  tasks:
+    - "任务必须可执行、可验证、可交接。"
+    - "实现阶段不得静默扩 scope。"
+    - "涉及 UI 时必须明确验收方式；涉及接口时必须明确封装方式。"
+    - "保持改动最小化，聚焦于请求的变更。"
+    - "涉及安装、路径、runtime、归档或 IDE 适配时，必须包含跨平台验证任务。"
+    - "tasks.md 中每个子任务都必须写明目标、输入、输出、验证点和依赖或前置条件。"
+  design:
+    - "技术方案必须对齐项目目录、路由、API、状态、样式和测试约定。"
+    - "新增能力优先复用现有结构，不因单次变更引入无关重构。"
+    - "涉及路径处理时，必须使用跨平台路径能力，不硬编码路径分隔符。"
+    - "优先复用现有 registry、常量和显式映射，不引入启发式检测、模糊匹配或正则猜测。"
+    - "design.md 需要补齐信息结构、状态管理、组件复用策略和验收路径。"
+  checklist:
+    - "必须明确通过项、未通过项、阻断项和是否建议放行。"
+    - "检查结论必须基于 proposal/tasks、项目规则和实现证据。"
+    - "checklist.md 需要沉淀本地验证、浏览器验证、范围一致性和组件复用检查摘要。"
+  iterations:
+    - "必须记录问题、修正动作、残留风险和下轮提醒。"
+    - "iterations.md 需要记录问题来源、修正动作、残留风险和下轮提醒。"

package/openspec/schemas/expert-delivery/schema.yaml

@@ -0,0 +1,68 @@
+name: expert-delivery
+version: 1
+description: 基于 spec-driven 扩展的专家协同交付流程，显式包含交付检查与迭代记录产物。
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: 变更提案与执行边界
+    template: proposal.md
+    instruction: |
+      创建变更提案，说明为什么要做这项变更、当前范围包含什么、不包含什么，
+      以及在进入实现前必须明确的默认假设、约束和风险。
+    requires: []
+
+  - id: specs
+    generates: specs/**/*.md
+    description: 增量需求规范与验收场景
+    template: spec.md
+    instruction: |
+      在 specs/<domain>/spec.md 下创建一个或多个增量规范文件。
+      每份规范都必须定义清晰的需求和可验证场景，并与 proposal 保持一致。
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: 技术设计与实现方案
+    template: design.md
+    instruction: |
+      创建技术设计文档，说明当前仓库中应如何落地这项变更。
+      优先复用现有结构，避免与本次变更无关的重构。
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: 可执行任务清单
+    template: tasks.md
+    instruction: |
+      创建可交给实现专家执行的任务清单。
+      任务必须具体、可验证，并严格限定在已批准的变更范围内。
+    requires:
+      - specs
+      - design
+
+  - id: checklist
+    generates: checklist.md
+    description: 交付检查清单
+    template: checklist.md
+    instruction: |
+      创建交付检查清单，基于实现结果、tasks、specs 和项目规则记录通过项、
+      未通过项、阻断项以及是否建议继续推进或放行。
+    requires:
+      - tasks
+
+  - id: iterations
+    generates: iterations.md
+    description: 迭代记录与残留风险
+    template: iterations.md
+    instruction: |
+      记录本轮发现的问题、已采取的修正动作、残留风险，以及下一轮或后续跟进建议。
+    requires:
+      - checklist
+
+apply:
+  requires:
+    - tasks
+  tracks: tasks.md

package/openspec/schemas/expert-delivery/templates/checklist.md

@@ -0,0 +1,39 @@
+## 通过项
+
+- [ ] proposal、specs、design 与实现结果保持一致
+- [ ] 已完成任务已真实反映在代码和配套文件中
+- [ ] 项目的目录、路由、接口、样式、测试等规则已满足
+
+### 本地验证摘要
+
+- [ ] lint(静态检查)：
+- [ ] typecheck(类型检查)：
+- [ ] test(测试)：
+- [ ] build(构建)：
+
+### 浏览器验证摘要
+
+- [ ] 页面可访问：
+- [ ] 关键路径可执行：
+- [ ] console(控制台) 检查：
+
+### 范围一致性
+
+- [ ] 当前实现未超出 proposal、design、tasks 已批准范围
+
+### 组件复用检查
+
+- [ ] 已记录复用组件、组件缺口和重复实现风险
+
+## 未通过项
+
+- [ ] 记录未满足需求或项目规则的项
+
+## 阻断项
+
+- [ ] 记录在继续交付、放行或归档前必须解决的项
+
+## 是否建议继续推进
+
+<!-- 说明当前变更是可以继续推进、带风险推进，还是必须阻断。 -->
+<!-- 建议同步给出完成内容、验证摘要和是否适合继续交接或归档。 -->