name: ohspec description: Use when 需要 RFC 技术规范、需求分析或 API 契约设计。Triggers on "RFC", "OHSpec", "/ohspec". allowed-tools: Task, AskUserQuestion, request_user_input, Read, Write, Glob, Grep, Bash, spawn_agent, wait, send_input, close_agent

OHSpec - 需求分析与设计规范

AI辅助需求分析与设计规范生成，强调多代理编排、结构化产物和质量门禁。

Architecture

架构概览与职责划分。

+-------------------------------------------------------------------+
| Orchestrator (你)                                                  |
| - 协调流程 / 复杂度路由 / 质量门禁 / 维护三文件                     |
+-------------------------------+-----------------------------------+
| Subagents                     | Artifacts                         |
| dispatcher-agent /            | rfc.md / findings.json /           |
| analyze-agent /               | progress.json                      |
| design-agent /                |                                    |
| audit-agent /                 |                                    |
+-------------------------------+-----------------------------------+
| Optional export: /ohspec:export -> rfc.digest.json + tasks.json    |
+-------------------------------------------------------------------+

核心职责：

1. 协调工作流：启动子代理，管理阶段转换，确保质量门禁
2. 委托执行：优先委托（Claude Code/Task 子代理环境）；Task 不可用时启用 Codex 兼容回退
3. 管理上下文：将繁重工作委托给子代理，保持主上下文清洁
4. 确保质量：执行强制检查，验证输出，维护 RFC 标准

关键产物：rfc.md、findings.json、progress.json（三文件是 scan-of-record 与质量审计入口）。

Hard Constraints

• 三文件必须先落盘：rfc.md、findings.json、progress.json 必须在扫描前初始化
• 默认委托 dispatcher-agent 执行基线扫描（scan-of-record）；Task 不可用时使用 Codex 兼容回退
• Codex 并行优先：当 Task 不可用且 spawn_agent 可用时，MEDIUM/COMPLEX 在 dispatcher 阶段必须优先使用 spawn_agent 并行分区扫描；失败才降级串行，并在 progress.json.tooling + audit_log 记录原因
• 工具选择以 ASSESS 为准（跨 CLI）：搜索/语义检索/并行策略必须由 ASSESS 决策并落盘到 progress.json.tooling；后续阶段只“读取并执行”（详见 phases/assess.md）
• 所有详细扫描结果写入 findings.json
• 子代理返回 JSON 摘要（≤500 tokens）
• 每阶段结束更新 progress.json
• DFX 必须量化，禁止模糊描述
• 禁止开放式问题，必须选项式
• 机读件不写进 RFC：通过 /ohspec:export 手动生成 rfc.digest.json（可选 tasks.json）
• 澄清/门禁提问工具优先级：优先用 AskUserQuestion（若可用）；否则 Codex CLI 用 request_user_input；若工具不可用/被禁用，输出"选项式问题 + 影响 + 建议"的文本并暂停，不得进入 plan/design/audit
• 禁止假设：找不到证据就补扫或阻断，不得编造设置键/接口/默认值

Codex 兼容回退（Task 不可用）

当无法使用 Task 子代理时（例如 Codex 环境），按以下优先级执行：

1. 优先：Codex 子代理并行（spawn_agent）分区扫描（MEDIUM/COMPLEX 默认启用）

   • 分区建议（4 个）：entrypoints（入口/路由/CLI）、config（配置/环境变量/feature flags）、deps（依赖/构建/部署/IaC）、tests_obs（测试/日志/指标/追踪/告警）
   • 子代理硬约束：只返回 JSON 摘要；不得直接写 rfc.md/findings.json/progress.json
   • 汇总规则：编排器 wait 后合并到 findings.json.confirmed.key_files/facts；冲突以“证据锚点更强/更靠近入口”优先，并写入 audit_log
   • 失败降级：spawn_agent 不可用/异常/超时 → 退回“最小化 scan-of-record（串行）”，并记录 progress.json.tooling.execution_mode=serial + 原因

2. 降级：最小化 scan-of-record（串行）

• 优先使用 rg（其次 ag/grep）做关键词预过滤，快速定位候选关键文件
• 必须排除生成物目录：避免把历史 RFC/缓存当作"证据"并拉爆上下文（示例：rg --glob '!**/.ohspec/**' --glob '!**/.claude/ohspec/**' --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**' ...）
• 先落盘三文件（rfc.md/findings.json/progress.json），再开始任何扫描
• ASSESS 必须先落盘：在进入任何内容级扫描前，先用 ASSESS 选定工具与 scan_scope，并写入 progress.json.tooling + phases.assess + audit_log
• 产出必须写入 findings.confirmed.key_files（≥3 且覆盖入口/配置/依赖或测试/可观测）
• 同时写入 findings.confirmed.facts（SIMPLE ≥ 1；MEDIUM/COMPLEX ≥ 3，项目事实：配置/存储/权限/错误码/线程模型/可观测等，每条附证据锚点）
• 禁止假设：找不到证据就补扫/阻断，不得编造设置键/接口/默认值
• 第一分钟基线：开始深度 Read/设计推演前，必须先把 key_files+facts 落盘（否则中断会导致三文件"空壳"）
• 记录到 progress.json.tooling 与 audit_log

Routing Signals

基于复杂度和信号动态路由，不强制执行所有阶段。

| 信号 | 触发条件 | Agent | 说明 | |------|----------|-------|------| | SKIP_ANALYZE | 需求明确、单文件 | 跳过 analyze | 快速通道 | | LOAD_DIPLOMAT | 跨子系统依赖 | diplomat-agent | 处理跨模块依赖 | | TRIGGER_SPIKE | 技术不确定 | prototyper-agent | 触发 Spike 验证 | | SIMPLIFY_CLARIFY | 详细需求 | 简化澄清 | 减少澄清轮次 |

复杂度路由

| 级别 | 特征 | 模式 | |------|------|------| | SIMPLE | 单文件，<50行 | 快速通道 | | MEDIUM | 多文件，单子系统 | 标准流程 | | COMPLEX | 跨子系统，架构级 | 完整流程 + spike |

Execution Flow

用户需求
  -> 初始化三文件（rfc.md/findings.json/progress.json）
  -> PRECHECK：快速需求预检（30秒过滤不可行需求）
  -> ASSESS：确定工具与 scan scope，写入 progress.json + audit_log
  -> 快速意图澄清（≤2问题，确保扫描准确性）
  -> dispatcher-agent 基线扫描（scan-of-record）
  -> 深度技术澄清（基于扫描结果）
  -> 复杂度路由 + 路由信号
  -> analyze -> design -> precheck -> audit
  -> RFC 输出
  -> 可选 /ohspec:export 生成机读件

语言要求

强制：所有交付物必须使用简体中文（RFC、findings.json、progress.json、审查报告）。

例外：代码标识符遵循项目约定。

快速开始

/ohspec "为音频服务增加 3D 音效开关"

Usage Examples

基础 RFC 生成

# 简单功能需求
/ohspec "为音频服务增加 3D 音效开关"

# 跨模块需求
/ohspec "实现用户认证模块与权限系统集成"

# 性能优化需求
/ohpec "优化数据库查询响应时间至 100ms 以内"

API 契约设计

# 设计新的 API 契约
/ohspec "设计用户注册 API 契约，包含邮箱验证和密码强度检查"

# 修改现有 API
/ohspec "重构支付接口，支持多种支付方式"

导出机读件

# 生成 RFC 后导出 digest 和 tasks
/ohspec "支付系统重构"

# 然后执行导出（手动触发）
/ohspec:export

# 输出：
# - rfc.digest.json (面向编码 Agent 的摘要)
# - tasks.json (可执行任务清单，支持 depends_on)

Resume 模式（中断恢复）

# 中断后恢复 RFC 生成
/ohspec:resume

# 列出所有 RFC
/ohspec:list

# 预检现有 RFC
/ohspec:precheck .ohspec/rfcs/RFC-20260126-example

Execution

核心执行流程

// OHSpec 核心执行流程（伪代码）
async function executeOHSpec(userRequirement, repoRoot) {
  // ============ 阶段 -1: 初始化三文件 ============
  const rfcId = generateRFCId();
  const rfcDir = `.ohspec/rfcs/${rfcId}`;

  await initializeThreeFiles(rfcDir, rfcId, userRequirement);
  // 产出：rfc.md（骨架）、findings.json（空结构）、progress.json（INIT 状态）

  // ============ 阶段 0: PRECHECK 需求预检 ============
  const precheckResult = await runRequirementPrecheck(userRequirement);
  await updateProgressJSON('requirement_precheck', precheckResult);

  if (!precheckResult.proceed) {
    return { error: '需求预检未通过', recommendations: precheckResult.recommendations };
  }

  // ============ 阶段 1: ASSESS 代码库评估（优化版） ============
  const assessResult = await runAssessOptimized(repoRoot, userRequirement);
  await updateProgressJSON('assess', assessResult);
  // 产出：tooling（搜索工具）、scan_scope、metrics（文件数/匹配数）

  // ============ 并行阶段：意图澄清 + 项目上下文加载 ============
  const [intentResult, contextData] = await Promise.all([
    runIntentClarify(userRequirement, assessResult),
    loadProjectContext(repoRoot)  // 可选，首次运行时执行
  ]);

  await updateProgressJSON('intent_clarify', intentResult);

  // ============ 阶段 3: dispatcher-agent 基线扫描（并行优化） ============
  const dispatcherResult = await runDispatcherParallel(
    userRequirement,
    intentResult,
    assessResult.tooling
  );

  // 合并结果到 findings.json
  await mergeFindings(dispatcherResult, contextData);
  // 产出：key_files（≥3，含角色标注）、facts（≥3，含证据锚点）

  // ============ 阶段 4: Gate-1 深度技术澄清 ============
  const gate1Result = await runTechnicalClarification(
    dispatcherResult,
    userRequirement
  );

  if (gate1Result.action === 'adjust_scope') {
    // 回到 dispatcher-agent 补扫
    await supplementScan(gate1Result.adjustments);
  }

  // ============ 阶段 5: 复杂度路由 ============
  const complexity = determineComplexity(dispatcherResult, intentResult);
  const signals = detectRoutingSignals(dispatcherResult, intentResult);

  // ============ 阶段 6: 执行对应流程 ============
  if (complexity === 'SIMPLE' || signals.includes('SKIP_ANALYZE')) {
    // 快速通道：分析 + 设计合并
    await runFastTrack(rfcId, dispatcherResult, userRequirement);
  } else if (complexity === 'MEDIUM') {
    // 标准流程
    await runStandardFlow(rfcId, dispatcherResult, userRequirement);
  } else {
    // COMPLEX：完整流程 + spike（如需）
    await runFullFlow(rfcId, dispatcherResult, userRequirement, signals);
  }

  // ============ 阶段 7: 质量门禁 ============
  const precheckResult = await runPrecheck(rfcDir);
  await updateProgressJSON('precheck', precheckResult);

  // ============ 阶段 8: 质量审查 ============
  const auditResult = await runAudit(rfcDir, precheckResult);
  await updateProgressJSON('audit', auditResult);

  return {
    rfcId,
    rfcPath: `${rfcDir}/rfc.md`,
    findingsPath: `${rfcDir}/findings.json`,
    progressPath: `${rfcDir}/progress.json`,
    complexity,
    signals,
    auditScore: auditResult.score
  };
}

关键优化函数

1. ASSESS 并行评估（优化版）

/**
 * ASSESS 阶段：并行评估代码库规模 + 缓存复用
 * 目标：30秒内完成，避免盲目扫描
 */
async function runAssessOptimized(repoRoot, userRequirement) {
  const startTime = Date.now();

  // 步骤 1: 检测搜索工具（并行检测多个）
  const searchTool = await detectSearchTool(['rg', 'ag', 'grep']);

  // 步骤 2: 并行统计文件数量 + 关键词预览
  const excludePatterns = [
    '**/.git/**', '**/.claude/**', '**/.ohspec/**',
    '**/node_modules/**', '**/dist/**', '**/build/**'
  ];

  const [fileCount, keywordMatches] = await Promise.all([
    countFiles(repoRoot, searchTool, excludePatterns),
    previewKeywords(repoRoot, extractKeywords(userRequirement), searchTool, excludePatterns)
  ]);

  // 步骤 3: 决策扫描策略
  const strategy = decideScanStrategy({
    totalFiles: fileCount,
    matchRatio: keywordMatches / fileCount,
    timeBudget: 30000 - (Date.now() - startTime)  // 保留时间给 dispatcher-agent
  });

  return {
    tooling: {
      search_tool: searchTool,
      fallback_used: searchTool === 'grep' ? 'true' : 'false',
      scan_scope: strategy.scope,
      strategy: strategy.mode
    },
    metrics: {
      total_files: fileCount,
      matched_files: keywordMatches,
      assessment_time_ms: Date.now() - startTime
    },
    strategy
  };
}

// 辅助：检测搜索工具（带回退）
async function detectSearchTool(preferences) {
  for (const tool of preferences) {
    const available = await checkToolAvailable(tool);
    if (available) return tool;
  }
  return 'grep';  // 最后回退
}

2. dispatcher-agent 并行扫描

/**
 * dispatcher-agent 基线扫描：并行子任务优化
 * 目标：快速收集 key_files + facts，避免串行等待
 */
async function runDispatcherParallel(requirement, intentContext, tooling) {
  // 子任务 1: 扫描入口文件
  const taskEntries = scanEntries(requirement, tooling);

  // 子任务 2: 扫描配置文件
  const taskConfig = scanConfig(requirement, tooling);

  // 子任务 3: 扫描依赖声明
  const taskDeps = scanDependencies(requirement, tooling);

  // 子任务 4: 扫描测试/可观测（可选）
  const taskTests = scanTests(requirement, tooling);

  // 并行执行所有子任务
  const [entries, config, deps, tests] = await Promise.all([
    taskEntries,
    taskConfig,
    taskDeps,
    taskTests.catch(() => ({ files: [], facts: [] }))  // 失败不阻断
  ]);

  // 合并结果
  const keyFiles = [
    ...entries.files,
    ...config.files,
    ...deps.files,
    ...tests.files
  ].filter(distinct);

  const facts = [
    ...entries.facts,
    ...config.facts,
    ...deps.facts,
    ...tests.facts
  ].filter(distinct);

  return {
    complexity: estimateComplexity(keyFiles, facts),
    intent: intentContext.primary_intent,
    scope: {
      key_files: keyFiles.slice(0, 10),  // 限制数量
      dependencies: deps.files,
      config_files: config.files
    },
    findings: {
      confirmed: {
        key_files: keyFiles,
        facts: facts
      }
    },
    signals: detectRoutingSignals(keyFiles, facts)
  };
}

3. 复杂度路由

/**
 * 复杂度路由：基于扫描结果动态选择执行路径
 */
function determineComplexity(dispatcherResult, intentContext) {
  const { key_files, facts } = dispatcherResult.findings.confirmed;
  const fileCount = key_files.length;
  const factCount = facts.length;

  // SIMPLE: 单文件，<50行
  if (fileCount <= 2 && factCount >= 1 && !intentContext.cross_module) {
    return 'SIMPLE';
  }

  // COMPLEX: 跨子系统，>200行或架构级
  if (fileCount >= 10 || intentContext.cross_module || intentContext.architecture_level) {
    return 'COMPLEX';
  }

  // MEDIUM: 默认
  return 'MEDIUM';
}

/**
 * 路由信号检测：动态调整执行路径
 */
function detectRoutingSignals(keyFiles, facts, intentContext) {
  const signals = [];

  // SKIP_ANALYZE: 需求明确、单文件影响
  if (keyFiles.length <= 2 && intentContext.user_provided_detail) {
    signals.push('SKIP_ANALYZE');
  }

  // LOAD_DIPLOMAT: 跨子系统依赖
  if (facts.some(f => f.category === 'cross_subsystem')) {
    signals.push('LOAD_DIPLOMAT');
  }

  // TRIGGER_SPIKE: 技术不确定
  if (facts.some(f => f.uncertainty === 'high')) {
    signals.push('TRIGGER_SPIKE');
  }

  // SIMPLIFY_CLARIFY: 详细需求
  if (intentContext.information_score >= 85) {
    signals.push('SIMPLIFY_CLARIFY');
  }

  return signals;
}

执行模式对比

┌─ 串行模式（默认） ─────────────────────────────────────┐
│ PRECHECK → ASSESS → 意图澄清 → dispatcher → Gate-1 →  │
│ analyze → Gate-2 → design → precheck → audit          │
│ 预计耗时：~5-8 分钟                                     │
└────────────────────────────────────────────────────────┘

┌─ 并行模式（优化） ─────────────────────────────────────┐
│ PRECHECK → ASSESS（并行统计）                          │
│   ↓                                                      │
│ [意图澄清 || 项目上下文加载]  (并行，~30s 节省)         │
│   ↓                                                      │
│ dispatcher（并行子任务：入口+配置+依赖+测试）            │
│   ↓                                                      │
│ Gate-1 → [快速通道 || 标准流程 || 完整流程]              │
│   ↓                                                      │
│ precheck + audit（自动流转）                             │
│ 预计耗时：~3-5 分钟（提升 40-60%）                       │
└────────────────────────────────────────────────────────┘

关键优化收益

| 优化项 | 收益 | 适用场景 | |--------|------|----------| | ASSESS 并行统计 | 节省 10-15s | 所有任务 | | 意图澄清 + 上下文并行 | 节省 20-30s | 首次运行 | | dispatcher 并行扫描 | 节省 30-60s | MEDIUM/COMPLEX | | 快速通道（SIMPLE） | 节省 2-3 分钟 | 单文件任务 | | SKIP_ANALYZE 信号 | 节省 1-2 分钟 | 需求明确 | | 自动流转 | 减少用户等待 | 无需决策阶段 |

Agent 选择

| Agent | 用途 | |-------|------| | dispatcher-agent | 基线扫描（scan-of-record） | | analyze-agent | 深度技术澄清，输出 RFC §1-§2 | | design-agent | 设计方案，定义接口，输出 RFC §3-§5 | | api-design-agent | API 契约设计与验证 | | diplomat-agent | 跨子系统依赖处理 | | prototyper-agent | Spike 验证（技术不确定） | | audit-agent | 质量审查，评分决策 |

质量门禁

必须满足：

• 5 个 RFC 章节完整
• 8 个 DFX 维度量化
• 4 种场景类型覆盖（Gherkin格式）
• 无模糊描述

RFC 格式

ID格式：RFC-{YYYYMMDD}-{slug}-{hash4}

目录（推荐）：.ohspec/rfcs/{RFC-ID}/ 兼容（历史）：.claude/ohspec/rfcs/{RFC-ID}/

Reference Documents

必读文档（P0）

• 工作流: phases/main.md - 主工作流程
• 规范: docs/phases.md, docs/quality-gates.md, docs/rfc-format.md
• 模板: templates/rfc.md, templates/findings.json, templates/progress.json

参考文档（按需）

• 其他工作流: phases/ - precheck, export, resume, spike 等
• 其他文档: docs/ - routing-signals, implementation-guide, best-practices, error-handling
• 扩展模板: templates/ - rfc-minimal, project-context, checkpoint 等

Scripts 目录

• precheck_rfc.py - RFC 预检
• export_digest.py - 导出 digest/tasks
• bootstrap_project.py - 项目初始化
• 优化脚本: decision_engine.py, dynamic_threshold.py, token_monitor.py, user_feedback.py