sanguo_vnpy_v2/.claude/workflows/helpers/comment-markers.js

/**
 * Comment 标记生成器
 *
 * 根据 v0.5 设计文档中的 Comment 标记约定，生成标准的完成标记
 */

/**
 * 生成 Execute Sub Agent 完成标记
 *
 * @param {Object} data - 完成数据
 * @param {Array<string>} data.deliverables - 交付物列表
 * @param {Object} data.testStatus - 测试状态
 * @param {string} data.executor - 执行者名称
 * @returns {string} 完成标记内容
 */
export function generateExecuteMarker(data) {
  const {
    deliverables = [],
    testStatus = { local: 'PASS', coverage: '0%' },
    executor = 'Execute Sub Agent',
    notes = ''
  } = data

  const timestamp = new Date().toISOString()

  return `@main-agent ✅ **EXECUTE_DONE**

## 完成总结

### 交付物
${deliverables.map((item, i) => `${i + 1}. \`${item}\``).join('\n')}

### 测试状态
- 本地运行: ${testStatus.local ? '✅ ' + testStatus.local : '❌ FAIL'}
${testStatus.coverage ? `- 覆盖率: ${testStatus.coverage}` : ''}

${notes ? `### 备注\n${notes}\n` : ''}

---
**执行者**: ${executor}
**完成时间**: ${timestamp}`
}

/**
 * 生成 Review Sub Agent 完成标记
 *
 * @param {Object} data - 审查数据
 * @param {string} data.verdict - 审查结论 (approved/rejected)
 * @param {Array<string>} data.findings - 发现的问题
 * @param {Array<string>} data.suggestions - 改进建议
 * @param {string} data.reviewer - 审查者名称
 * @returns {string} 完成标记内容
 */
export function generateReviewMarker(data) {
  const {
    verdict = 'approved',
    findings = [],
    suggestions = [],
    reviewer = 'Review Sub Agent',
    notes = ''
  } = data

  const timestamp = new Date().toISOString()
  const verdictIcon = verdict === 'approved' ? '✅' : '❌'
  const verdictText = verdict.toUpperCase()

  return `@main-agent ${verdictIcon} **REVIEW_DONE verdict=${verdictText}**

## 审查结果

### 检查项
- 代码质量: ${verdict === 'approved' ? '✅' : '❌'}
- 安全性: ${verdict === 'approved' ? '✅' : '❌'}
- 性能: ${verdict === 'approved' ? '✅' : '❌'}
- 测试覆盖: ${verdict === 'approved' ? '✅' : '❌'}

${findings.length > 0 ? `### 发现的问题
${findings.map((f, i) => `${i + 1}. ${f}`).join('\n')}

` : ''}${suggestions.length > 0 ? `### 改进建议
${suggestions.map((s, i) => `${i + 1}. ${s}`).join('\n')}

` : ''}${notes ? `### 备注\n${notes}\n` : ''}---
**审查者**: ${reviewer}
**结论**: ${verdictIcon} ${verdictText}
**完成时间**: ${timestamp}`
}

/**
 * 生成 Test Sub Agent 完成标记
 *
 * @param {Object} data - 测试数据
 * @param {string} data.result - 测试结果 (passed/failed)
 * @param {string} data.coverage - 测试覆盖率
 * @param {Array<string>} data.failures - 失败的测试
 * @param {string} data.summary - 测试摘要
 * @param {string} data.tester - 测试者名称
 * @returns {string} 完成标记内容
 */
export function generateTestMarker(data) {
  const {
    result = 'passed',
    coverage = '0%',
    failures = [],
    summary = '',
    tester = 'Test Sub Agent',
    notes = ''
  } = data

  const timestamp = new Date().toISOString()
  const resultIcon = result === 'passed' ? '✅' : '❌'
  const resultText = result.toUpperCase()

  return `@main-agent ${resultIcon} **TEST_DONE result=${resultText} coverage=${coverage}**

## 测试结果

### 测试摘要
${summary || '无'}

${failures.length > 0 ? `### 失败的测试
${failures.map((f, i) => `${i + 1}. ${f}`).join('\n')}

` : ''}${notes ? `### 备注\n${notes}\n` : ''}---
**测试者**: ${tester}
**覆盖率**: ${coverage}
**完成时间**: ${timestamp}`
}

/**
 * 生成 Main Agent 验收完成标记
 *
 * @param {Object} data - 验收数据
 * @param {Object} data.requirementDesign - 需求→设计检查结果
 * @param {Object} data.designCode - 设计→编码检查结果
 * @param {Object} data.requirementCode - 需求→编码检查结果
 * @param {string} data.verdict - 最终结论 (approved/rejected)
 * @returns {string} 完成标记内容
 */
export function generateVerificationMarker(data) {
  const {
    requirementDesign = { passed: true, items: [] },
    designCode = { passed: true, items: [] },
    requirementCode = { passed: true, items: [] },
    verdict = 'approved'
  } = data

  const timestamp = new Date().toISOString()
  const verdictIcon = verdict === 'approved' ? '✅' : '❌'
  const verdictText = verdict.toUpperCase()

  // 检查是否全部通过
  const allPassed = requirementDesign.passed && designCode.passed && requirementCode.passed
  const finalVerdict = allPassed ? 'approved' : 'rejected'

  return `@main-agent ✅ **VERIFICATION_${finalVerdict.toUpperCase()}**

## 三向一致性检查

### 1️⃣ 需求 → 设计
${renderCheckTable(requirementDesign.items)}
${requirementDesign.passed ? '✅ **需求→设计: 通过**' : '❌ **需求→设计: 未通过**'}

### 2️⃣ 设计 → 编码
${renderCheckTable(designCode.items)}
${designCode.passed ? '✅ **设计→编码: 通过**' : '❌ **设计→编码: 未通过**'}

### 3️⃣ 需求 → 编码
${renderCheckTable(requirementCode.items)}
${requirementCode.passed ? '✅ **需求→编码: 通过**' : '❌ **需求→编码: 未通过**'}

## 最终结论
${allPassed ? '✅ **三向一致性检查全部通过**' : '❌ **三向一致性检查未通过，存在偏差**'}
**VERDICT**: ${verdictIcon} ${finalVerdict === 'approved' ? 'APPROVED FOR MERGE' : 'NEEDS FIX'}

---
**执行者**: Main Agent
**完成时间**: ${timestamp}`
}

/**
 * 辅助函数：渲染检查表格
 */
function renderCheckTable(items) {
  if (!items || items.length === 0) {
    return '无检查项'
  }

  const header = '| 检查项 | 实际情况 | 状态 |\n|--------|----------|------|'
  const rows = items.map(item => {
    const status = item.passed ? '✅' : '❌'
    return `| ${item.check} | ${item.actual || '-'} | ${status} |`
  }).join('\n')

  return `${header}\n${rows}`
}

/**
 * 生成进度更新标记
 *
 * @param {Object} data - 进度数据
 * @param {string} data.stage - 当前阶段
 * @param {Array<string>} data.completed - 已完成的任务
 * @param {Array<string>} data.inProgress - 进行中的任务
 * @returns {string} 进度更新内容
 */
export function generateProgressUpdate(data) {
  const {
    stage = 'Execute',
    completed = [],
    inProgress = []
  } = data

  const total = completed.length + inProgress.length
  const progress = total > 0 ? Math.round((completed.length / total) * 100) : 0

  return `@main-agent 📝 **进度更新: ${stage} 阶段**

## 已完成
${completed.map((item, i) => `- ✅ ${item}`).join('\n') || '- 无'}

## 进行中
${inProgress.map((item, i) => `- 🔄 ${item}`).join('\n') || '- 无'}

---
**进度**: ${progress}% (${completed.length}/${total} 完成)`
}

/**
 * 生成偏差报告标记
 *
 * @param {Object} data - 偏差数据
 * @param {string} data.type - 偏差类型 (requirement-design/design-code/requirement-code)
 * @param {string} data.issue - 偏差描述
 * @param {string} data.expected - 预期情况
 * @param {string} data.actual - 实际情况
 * @returns {string} 偏差报告内容
 */
export function generateDeviationMarker(data) {
  const {
    type = 'unknown',
    issue = '',
    expected = '',
    actual = '',
    actionRequired = []
  } = data

  const typeLabels = {
    'requirement-design': '需求 → 设计 偏差',
    'design-code': '设计 → 编码 偏差',
    'requirement-code': '需求 → 编码 偏差'
  }

  const timestamp = new Date().toISOString()

  return `@main-agent ❌ **CONSISTENCY_ISSUE**

## 发现偏差

### 问题: ${typeLabels[type] || type}
**问题描述**: ${issue}

${expected ? `**预期**: ${expected}\n` : ''}${actual ? `**实际**: ${actual}\n` : ''}${actionRequired.length > 0 ? `### 处理要求
${actionRequired.map((a, i) => `${i + 1}. ${a}`).join('\n')}

` : ''}---
**标签**: needs-consistency-fix 🔴
**报告时间**: ${timestamp}`
}

/**
 * 导出所有标记生成函数
 */
export default {
  generateExecuteMarker,
  generateReviewMarker,
  generateTestMarker,
  generateVerificationMarker,
  generateProgressUpdate,
  generateDeviationMarker
}