# ═══════════════════════════════════════════════════════════
# SpecCore 主配置完整示例（.speccore.yml）—— v8.3.303 对齐版
# ═══════════════════════════════════════════════════════════
# 位置：项目根 .speccore.yml（与 .speccore/PROJECT.yaml 分工：
#       PROJECT.yaml 管「端/源码/Git/部署」，本文件管「行为/门禁/AI」）
# 升级：speccore config --upgrade（不要手动编辑 schema_version）
# 参考：docs/config-reference.md（字段详解）
#
# ⚠️ 本示例与 DEFAULT_CONFIG（v8.3.303）逐字段对齐，注意三处归属变化：
#   1. project → 已迁至 .speccore/PROJECT.yaml；tech_stack/team → 已废弃（升级自动清理）
#   2. tests/stages/pipeline 测试环境段 → 归属 .speccore/environments/{env}.yaml（见 VERIFY-EXAMPLE.yaml）
#   3. 新增：logging / tools / settings.pipeline / with_code / gates
#
# 📖 本示例为「字典」——每个字段配定义式注释（含义/枚举/默认/影响），
#    直接复制需要的段到你的 .speccore.yml 再改值即可。
# ═══════════════════════════════════════════════════════════

# schema_version：配置结构版本号，config --upgrade 自动维护，勿手动修改
schema_version: 1

# ─────────────────────────────────────────────────────────────
# 本地文件日志（v8.3.253+）
# ─────────────────────────────────────────────────────────────
# 开关三级优先级：--log 参数 > SPECCORE_LOG=1 环境变量 > logging.enabled
# 开启后所有 logger 输出同步写盘 .speccore/local/logs/speccore-<日期>.log
# 排查问题时可直接把日志文件发给 AI 分析。默认关闭，零开销。
logging:
  # enabled: 是否启用本地文件日志（true/false，默认 false）
  enabled: false

# ─────────────────────────────────────────────────────────────
# 质量门禁（Quality Gates）
# ─────────────────────────────────────────────────────────────
# 三道闸的开关都在这里：测试闸、审查闸、PR 闸。
quality_gates:
  # enforce_testing: 是否强制要求每个任务包含测试用例
  #   true  → execute 前检查 TEST.md，缺失则阻断
  #   false → 仅警告，不阻断
  enforce_testing: true
  # enforce_review: 是否强制代码审查
  #   true  → 执行完自动进入 review 流程
  #   false → 审查可选
  enforce_review: true
  # require_pr: 是否强制通过 PR 合并代码
  #   true  → 禁止直接 push 到保护分支，必须通过 speccore pr 提交
  #   false → 允许直接 push（本地单人开发常用）
  require_pr: true
  # block_level: 质量门禁阻塞级别（v8.3.197+）
  #   standard → 编译+单测+契约阻塞（默认）
  #   compile  → 仅编译阻塞
  block_level: standard
  # case_gate: 用例核对闸（v8.3.399+）——execute 后按 TEST.md 的 TC-XXX 用例逐条核对实现
  #   block  → ❌ 未实现阻塞修复环（默认）
  #   report → 仅出矩阵报告，不阻塞
  #   off    → 关闭
  case_gate: block
  # ── UI 验证（v8.3.47+）──
  verify_ui:
    # enabled: 是否启用 UI 验证（冒烟测试 + 视觉检查）
    enabled: false
    # smoke_test: 是否执行冒烟测试
    smoke_test: true
    # visual_check: 是否执行视觉检查（截图 + 像素/模型比对）
    visual_check: true
    # headed: 是否使用有头浏览器（显示浏览器窗口，便于调试，默认 false 无头）
    headed: false
    # threshold: 视觉检查的检测严格度
    #   strict → 任何微小差异都视为问题
    #   normal → 明显差异视为问题（默认）
    #   loose  → 仅严重问题
    threshold: normal
    # devices: 测试设备列表
    devices:
      - desktop
    # browsers: 测试浏览器列表
    browsers:
      - chromium
    # timeout: 单场景超时（毫秒）
    timeout: 30000
    # visual_model: 视觉模型配置（v8.3.50+，看图判断走外部模型）
    visual_model:
      # provider: 视觉模型提供方 qwen-vl(默认) / openai / anthropic / local
      provider: qwen-vl
      # model: 模型名称（可选，留空用 provider 默认模型）
      model: qwen-vl-max
      # apiKey: API Key（可选，支持 ${ENV_VAR} 环境变量引用）
      # endpoint: 自定义端点（可选）
      # timeout: 请求超时（毫秒，可选）

# ─────────────────────────────────────────────────────────────
# 契约冲突裁决（Arbitration）
# ─────────────────────────────────────────────────────────────
arbitration:
  # enabled: 是否启用三级冲突裁决机制
  #   true → analyze/taskify/execute 各阶段自动检测并裁决契约冲突
  enabled: true
  # mode: 裁决模式
  #   full        → 完整三级裁决（Spec 层 → 代码层 → 运行时层）
  #   l1-only     → 仅 Spec 层冲突检测
  #   report-only → 只报告冲突不裁决
  mode: full

# ─────────────────────────────────────────────────────────────
# 通用设置（Settings）
# ─────────────────────────────────────────────────────────────
settings:
  # ── 指派策略（Assignee）──
  assignee:
    # enabled: 是否启用自动指派（taskify 时按 STAFFING.md 分配负责人）
    enabled: true
    # mode: 指派严格度
    #   strict → 每个子任务必须指定 owner，缺失则阻断
    #   loose  → 仅任务级指定 owner，子任务可共享（默认）
    #   off    → 关闭指派
    mode: loose
  # ── 追踪（Trace）──
  trace:
    # enabled: 是否启用全链路追踪（需求→规格→任务→代码 双向追溯）
    enabled: true
    # auto_annotate: 是否自动在代码中插入 @spec 追踪注解
    auto_annotate: true
  # ── 归档（Archive）──
  archive:
    # auto_cleanup: 迭代完成后是否自动清理临时文件
    auto_cleanup: false
  # ── 计划（Plan）──
  plan:
    # parallel_suggest: 是否建议并行执行无依赖任务（plan 输出里提示可并行项）
    parallel_suggest: true
  # ── 校验（Validation）──
  validation:
    # strict_mode: 是否启用严格校验模式
    #   true  → 任何格式错误都阻断执行
    #   false → 仅记录警告，尽量继续
    strict_mode: false
  # ── 同步（Sync）──
  sync:
    # auto_check: 执行前是否自动检查配置/规范库是否为最新（有新版提示升级）
    auto_check: true
  # ── 模式沉淀（Patterns）──
  patterns:
    # auto_save: 是否自动将分析中发现的模式保存到 .speccore/PATTERNS/
    #   smart  → 仅置信度高时自动保存（默认）
    #   aggressive → 全部自动保存
    #   off    → 不自动保存，仅手动
    auto_save: smart
  # ── 审查（Review）──
  review:
    # check_assignee: 审查时是否检查指派人与执行人一致（不一致则警告）
    check_assignee: false
  # ── 测试验证（Tests，v8.3.351+）──
  tests:
    # smoke: 配置式冒烟线（质量门禁自动启用的 UI 验证）
    smoke:
      enabled: true
    # ai_verify: AI 宿主验证线（verify --ai，自然语言剧本 + 视觉执行）
    ai_verify:
      enabled: true
    # layered: AI 剧本分层（common=公共能力层 | modules=模块层）
    layered:
      common: true
      modules: true
  # ── 视觉模型（Vision，v8.3.94+）──
  # specs 文档图片理解（PNG/JPG/GIF/WebP 位图自动转文本注入 AI prompt）。默认关闭。
  vision:
    # enabled: 是否启用视觉模型
    enabled: false
    # provider: 视觉模型提供方
    #   qwen-vl(默认) | openai | anthropic | local
    provider: qwen-vl
    # model: 模型名称（可选，留空用 provider 默认模型）
    model: qwen-vl-plus
    # maxImagesPerPrompt: 单次 prompt 最多注入图片数
    maxImagesPerPrompt: 10
    # imageMaxSizeKb: 单张图片大小上限（KB）
    imageMaxSizeKb: 2048
  # ── 流水线（Pipeline）──
  # pipeline: 是否默认启用 Pipeline 模式（true 时 run 默认走流水线）
  pipeline: false
  # ── 关联代码（with_code）──
  # with_code: 分析时是否默认关联源码（from-source 场景）
  with_code: false
  # ── 非必要流水线步骤开关（三态）──
  #   auto = 按内置逻辑智能判定（默认） | on = 强制执行 | off = 跳过
  optional_steps:
    # clarify: 需求澄清（auto=按文档专业度判定，专业就跳过）
    clarify: auto
    # verify: 验证（代码 review + 契约/性能 + UI）
    verify: auto
    # pipeline: 部署（合并→构建→测试→部署）
    pipeline: auto
    # pr: 合并请求（本地开发可不 PR）
    pr: auto
    # done: 归档复盘（可延后）
    done: auto
    # spec2doc: 导出文档（Word/PDF/HTML）
    spec2doc: auto
  # ── 命名流水线（Pipelines）──
  pipelines:
    # default: 默认流水线名（内置 full/import/spec/analyze/develop/deliver/deploy/docs 或自定义名）
    default: develop
    # custom: 自定义命名流水线（名称: 逗号分隔的阶段串）
    #   示例: { my-flow: analyze,validate,taskify,plan,execute }
    custom: {}
  # ── 流水线 review 闸口模式（Gates）──
  gates:
    # mode: 质量门禁闸口行为
    #   manual = 闸口 A/B/C 都软停人工确认（默认，最安全）
    #   auto   = 三闸口都跳过（含 C 部署，自动执行，谨慎使用）
    mode: manual
  # ── AI 内容生成来源（v8.3.193+）──
  ai:
    # provider: 内容生成提供方
    #   host = 宿主 AI（Qoder SDK / Headless，默认）
    #   llm  = 自配 LLM（走下方 providers 池）
    #   auto = 宿主优先，失败回退自配 LLM
    provider: host
    # providers: 自配 LLM 池（定义一次，各功能按 name 引用；演示条目，默认 providers: []）
    providers:
      - name: local
        type: ollama
        endpoint: "http://localhost:11434"
        model: qwen2.5:7b
        priority: 1
      - name: gpt4o
        type: openai
        model: gpt-4o
        apiKey: "${OPENAI_API_KEY}"
        priority: 2
    # defaults: 各功能的默认 provider name（示例: { analyze: gpt4o }）
    defaults: {}
    # fallback: 兜底 provider name（可选，主 provider 失败时启用）
    fallback: local
  # ── 子 Agent SDK 派单（v8.3.301+，第七层「窗口物理隔离」增强通道）──
  agent_dispatch:
    # mode: 子 Agent SDK 派单开关
    #   auto → Qoder 宿主 + token 可用（PAT 或 CLI 登录态）时启用（默认）
    #   on   → 强制尝试 SDK 派单（失败回退标记模式）
    #   off  → 禁用 SDK 派单，永远走标记模式
    mode: auto
  # ── 冒烟测试统一配置（三时机开关 + 范围 + 按环境差异化，v8.3.217+）──
  smoke:
    points:
      local: auto        # ①本地冒烟（开发完成后、提交前）
      pre-deploy: auto  # ②部署前冒烟（critical 阻断）
      post-deploy: auto # ③环境冒烟（只报告）
    scope: module    # full=全量 / module=当前功能模块（默认）
    # scope_by_env 示例: dev: module / production: full
    scope_by_env: {}

# ─────────────────────────────────────────────────────────────
# Ask 引擎路由配置（控制 speccore ask 的行为）
# ─────────────────────────────────────────────────────────────
ask:
  # ── 路由策略（Routing）──
  routing:
    # mode: 意图识别路由模式
    #   hybrid → 混合路由（本地规则 + LLM 兜底，默认）
    #   cli-only   → 仅本地规则匹配
    #   host-ai-only → 仅宿主 AI 识别
    mode: hybrid
    # high_threshold: 高置信度阈值（≥此值直接执行，不询问确认）
    high_threshold: 70
    # low_threshold: 低置信度阈值（<此值进入模糊拦截，询问用户）
    low_threshold: 45
    # auto_host_ai: 是否在无法识别时自动调用宿主 AI（Qoder/Cursor 等）
    auto_host_ai: true
    # cache_enabled: 是否缓存意图识别结果
    cache_enabled: true
    # cache_min_hits: 缓存生效最小命中次数（命中 ≥N 次后才走缓存）
    cache_min_hits: 3
  # ── 规则覆盖（Rules）──
  rules:
    # force_host_ai: 是否强制所有意图走宿主 AI（调试用，默认 false）
    force_host_ai: false
  # ── 自配 LLM 池（演示条目，默认 []）──
  # 结构与 settings.ai.providers 一致：name/type/endpoint/model/priority
  llm_providers:
    - name: ollama-local
      enabled: false
      type: ollama
      endpoint: http://localhost:11434
      model: qwen2.5:7b
      priority: 1
    - name: openai-compatible
      enabled: false
      type: openai
      endpoint: https://api.openai.com/v1/chat/completions
      model: gpt-4o-mini
      priority: 2

# ─────────────────────────────────────────────────────────────
# 工具路径（doc2spec 转换依赖，留空自动探测）
# ─────────────────────────────────────────────────────────────
tools:
  # pandoc: pandoc 可执行文件路径（Word/PDF 转换用，留空自动探测 PATH）
  pandoc: ''
  # libreoffice: LibreOffice 可执行文件路径（PDF 转换用，留空自动探测）
  libreoffice: ''

# ─────────────────────────────────────────────────────────────
# 配置变更历史（speccore config --upgrade 自动维护，勿手动编辑）
# ─────────────────────────────────────────────────────────────
config_history: []