spectra-cli 4.1.1

package/plugins/spec-driver/templates/product-spec-template.md

@@ -0,0 +1,250 @@
+# {PRODUCT_NAME} — 产品级活规范
+
+**最后更新**: {LAST_UPDATED}
+**聚合来源**: {SPEC_COUNT} 个增量功能规范
+**当前版本**: 基于 specs/{LATEST_SPEC_ID} 为止的全部已实现功能
+
+> 本文档由 Spec Driver 的 sync 子代理自动生成，反映产品的当前完整状态。
+> 增量功能规范保留在 `specs/NNN-xxx/` 目录中作为决策历史记录。
+
+---
+
+## 产品概述
+
+{PRODUCT_OVERVIEW}
+
+**定位**: {PRODUCT_POSITIONING}
+**目标用户**: {TARGET_USERS}
+**核心价值**: {CORE_VALUE}
+
+---
+
+## 目标与成功指标
+
+### 产品愿景
+
+{PRODUCT_VISION}
+
+### 成功指标
+
+| 指标 | 基线值 | 当前值 | 目标值 | 来源 spec |
+|------|--------|--------|--------|----------|
+| {指标名} | {基线} | {当前} | {目标} | {NNN-xxx} |
+
+<!-- 聚合指导: 从各 spec 的 Success Criteria 和 Measurable Outcomes 中提取产品级 KPI -->
+
+---
+
+## 用户画像与场景
+
+### 目标用户
+
+| 用户角色 | 描述 | 核心痛点 | 使用频率 |
+|---------|------|---------|---------|
+| {角色名} | {描述} | {痛点} | {频率} |
+
+### 核心使用场景
+
+1. **{场景名}**: {场景描述}
+   - **触发条件**: {触发}
+   - **期望结果**: {结果}
+   - **来源**: specs/{NNN-xxx}
+
+<!-- 聚合指导: 从 User Stories 中提取用户角色和场景，合并同类用户 -->
+
+---
+
+## 范围与边界
+
+### 范围内
+
+- {功能/能力描述}（来源: {NNN-xxx}）
+
+### 范围外
+
+- {明确排除的功能/能力}（来源: {NNN-xxx}）
+
+<!-- 聚合指导: 从各 spec 的 Constraints & Boundaries 章节提取，合并去重 -->
+
+---
+
+## 当前功能全集
+
+### 功能总览
+
+| 编号 | 功能 | 来源 spec | 状态 | 说明 |
+|------|------|----------|------|------|
+| F-001 | {功能名} | {NNN-xxx} | ✅ 活跃 / 🔄 已更新 / ❌ 已废弃 | {一句话说明} |
+
+### 详细功能描述
+
+#### F-001: {功能名}
+
+**来源**: specs/{NNN-xxx}/spec.md
+**状态**: ✅ 活跃
+
+{功能的当前描述——合并所有相关 spec 后的最终版本}
+
+**当前行为**:
+- {行为描述 1}
+- {行为描述 2}
+
+**验收标准**:
+- {从最新相关 spec 提取的验收标准}
+
+---
+
+## 非功能需求
+
+### 性能
+
+| 指标 | 要求 | 来源 spec |
+|------|------|----------|
+| {指标} | {要求描述} | {NNN-xxx} |
+
+### 安全
+
+- {安全要求}（来源: {NNN-xxx}）
+
+### 可扩展性
+
+- {可扩展性要求}（来源: {NNN-xxx}）
+
+### 可用性
+
+- {可用性要求}（来源: {NNN-xxx}）
+
+### 兼容性
+
+- {兼容性要求}（来源: {NNN-xxx}）
+
+<!-- 聚合指导: 从各 spec 的非功能需求、Constraints、Edge Cases 中提取，按类别归组 -->
+<!-- 容错: 若某类别无信息，标注 [待补充: 增量 spec 中未明确此维度] -->
+
+---
+
+## 当前技术架构
+
+> 从最新的 plan.md 提取，重构类 spec 的架构描述优先。
+
+**技术栈**: {TECH_STACK}
+**项目结构**:
+
+```text
+{PROJECT_STRUCTURE}
+```
+
+> 关键设计决策已迁移至【设计原则与决策记录】章节，详见下方。
+
+---
+
+## 设计原则与决策记录
+
+### 设计原则
+
+1. **{原则名}**: {原则描述}（来源: {NNN-xxx}）
+
+### 关键决策记录
+
+| 决策 | 上下文 | 理由 | 替代方案 | 来源 spec |
+|------|--------|------|---------|----------|
+| {决策描述} | {决策背景} | {选择理由} | {被拒绝的方案} | {NNN-xxx} |
+
+<!-- 聚合指导: 从各 plan.md 的架构决策和 Complexity Tracking 中提取 -->
+
+---
+
+## 已知限制与技术债
+
+| 来源 spec | 类别 | 描述 | 状态 |
+|----------|------|------|------|
+| {NNN-xxx} | 限制 / 技术债 | {描述} | 未解决 / 已在 {NNN-xxx} 中解决 |
+
+---
+
+## 假设与风险
+
+### 关键假设
+
+| 假设 | 依据 | 影响（若假设不成立） | 来源 spec |
+|------|------|-------------------|----------|
+| {假设描述} | {依据} | {影响} | {NNN-xxx} |
+
+### 风险矩阵
+
+| 风险 | 概率 | 影响 | 缓解措施 | 来源 spec |
+|------|------|------|---------|----------|
+| {风险描述} | 高/中/低 | 高/中/低 | {措施} | {NNN-xxx} |
+
+<!-- 聚合指导: 从各 spec 的 Dependencies & Impacts、Edge Cases、Constraints 推断 -->
+
+---
+
+## 被废弃的功能
+
+> 以下功能已被后续迭代取代或移除。
+
+| 原功能 | 原始 spec | 废弃原因 | 取代者 |
+|--------|----------|---------|--------|
+| {功能名} | {NNN-xxx} | {原因} | {NNN-xxx} 中的 {新功能} |
+
+---
+
+## 变更历史
+
+| 编号 | 功能 spec | 类型 | 日期 | 摘要 |
+|------|----------|------|------|------|
+| 001 | {NNN-xxx} | INITIAL / FEATURE / FIX / REFACTOR / ENHANCEMENT | {日期} | {一句话摘要} |
+
+---
+
+## 术语表
+
+| 术语 | 定义 | 来源 spec |
+|------|------|----------|
+| {术语} | {定义} | {NNN-xxx} |
+
+<!-- 聚合指导: 从各 spec 中提取反复出现的领域术语，统一定义 -->
+<!-- 真实性优先: 仅收录增量 spec 中实际出现的术语，信息不足时允许少于 5 个 -->
+
+---
+
+## 对外文档摘要（供 spec-driver-doc 使用）
+
+> 此区块是产品活文档到仓库 README / 使用文档的 handoff 层。
+> 目标是为 `spec-driver-doc` 提供稳定、可追溯、面向外部读者的摘要素材，而不是把整份内部活规范直接改写成 README。
+
+### README 电梯陈述
+
+{一句话说明产品是什么、给谁用、解决什么问题}
+
+### 核心价值主张
+
+- {核心价值 1}
+- {核心价值 2}
+- {核心价值 3}
+
+### 主要用户与工作流
+
+| 用户角色 | 典型任务 | 推荐入口 | 来源 spec |
+|---------|---------|---------|----------|
+| {角色名} | {任务} | {入口/流程} | {NNN-xxx} |
+
+### 对外边界
+
+- **应该对外强调**: {适合进入 README / 使用文档的能力或约束}
+- **不应直接对外承诺**: {仅内部有效、仍在演进或证据不足的内容}
+
+<!-- 聚合指导:
+1. 此区块必须只基于已有 spec / plan / tasks / current-spec 事实生成
+2. 信息不足时使用 [待补充]，有推断时使用 [推断]
+3. 内容风格应简洁、可扫描、面向外部读者，避免复制内部实现细节
+4. spec-driver-doc 优先消费此区块，再消费正文其他章节 -->
+
+---
+
+## 附录：增量 spec 索引
+
+| spec | 标题 | 类型 | 关键变更 |
+|------|------|------|---------|
+| [001-xxx](../001-xxx/spec.md) | {标题} | {类型} | {关键变更摘要} |

package/plugins/spec-driver/templates/research-synthesis-template.md

@@ -0,0 +1,102 @@
+# 产研汇总: {FEATURE_NAME}
+
+**特性分支**: `{BRANCH_NAME}`
+**汇总日期**: {DATE}
+**输入**: [product-research.md](product-research.md) + [tech-research.md](tech-research.md)
+**执行者**: 主编排器（非子代理）
+
+## 1. 产品×技术交叉分析矩阵
+
+| MVP 功能 | 产品优先级 | 技术可行性 | 实现复杂度 | 综合评分 | 建议 |
+|---------|-----------|-----------|-----------|---------|------|
+| {功能 1} | P1 | 高/中/低 | 高/中/低 | ⭐⭐⭐ | 纳入 MVP |
+| {功能 2} | P1 | 高/中/低 | 高/中/低 | ⭐⭐⭐ | 纳入 MVP |
+| {功能 3} | P2 | 高/中/低 | 高/中/低 | ⭐⭐ | 二期 |
+
+**评分说明**:
+- ⭐⭐⭐: 高优先 + 高可行 + 低复杂度 → 纳入 MVP
+- ⭐⭐: 中等匹配 → 视资源纳入 MVP 或推迟
+- ⭐: 低匹配 → 推迟
+
+## 2. 可行性评估
+
+### 技术可行性
+
+{总体技术可行性评估}
+
+### 资源评估
+
+- **预估工作量**: {概述}
+- **关键技能需求**: {技术栈需求}
+- **外部依赖**: {外部服务或库}
+
+### 约束与限制
+
+- {约束 1}
+- {约束 2}
+
+## 3. 风险评估
+
+### 综合风险矩阵
+
+| # | 风险 | 来源 | 概率 | 影响 | 缓解策略 | 状态 |
+|---|------|------|------|------|---------|------|
+| 1 | {风险 1} | 产品/技术 | 高/中/低 | 高/中/低 | {策略} | 待监控 |
+
+### 风险分布
+
+- **产品风险**: {N} 项（高:{n1} 中:{n2} 低:{n3}）
+- **技术风险**: {M} 项（高:{m1} 中:{m2} 低:{m3}）
+
+## 4. 最终推荐方案
+
+### 推荐架构
+
+{综合产品需求和技术评估后的推荐架构方案}
+
+### 推荐技术栈
+
+| 类别 | 选择 | 理由 |
+|------|------|------|
+| {类别 1} | {技术/库} | {产品+技术综合理由} |
+
+### 推荐实施路径
+
+1. **Phase 1 (MVP)**: {核心功能集}
+2. **Phase 2**: {扩展功能}
+3. **Phase 3**: {优化和高级功能}
+
+## 5. MVP 范围界定
+
+### 最终 MVP 范围
+
+**纳入**:
+- {功能 1}: {理由——产品价值 + 技术可行}
+- {功能 2}: {理由}
+
+**排除（明确不在 MVP）**:
+- {功能 X}: {理由——技术复杂度高 / 产品价值低}
+
+### MVP 成功标准
+
+- {可测量标准 1}
+- {可测量标准 2}
+
+## 6. 结论
+
+### 综合判断
+
+{一段话概述产品方向+技术方案的最终推荐}
+
+### 置信度
+
+| 维度 | 置信度 | 说明 |
+|------|--------|------|
+| 产品方向 | 高/中/低 | {理由} |
+| 技术方案 | 高/中/低 | {理由} |
+| MVP 范围 | 高/中/低 | {理由} |
+
+### 后续行动建议
+
+- 确认推荐方案后，进入需求规范阶段（specify）
+- {其他建议}

package/plugins/spec-driver/templates/spec-driver.config-template.yaml

@@ -0,0 +1,244 @@
+# Spec Driver - 驱动配置文件
+# 文件位置: 项目根目录/spec-driver.config.yaml 或 .specify/spec-driver.config.yaml
+# 首次使用时由 init-project.sh 交互式引导创建
+#
+# 快速填写指南（建议按顺序）:
+# 1) 新手只改 `preset`，其余保持默认即可运行
+# 2) 需要精细调参时再打开 `agents.<agent>.model` 覆盖
+# 3) Codex 运行时推荐固定模型为 `gpt-5.4`，通过 `codex_thinking` 调整思考等级
+
+# ═══════════════════════════════════════
+# 模型预设（第一优先）
+# ═══════════════════════════════════════
+# 可选值: balanced | quality-first | cost-efficient
+#
+# balanced（默认）:
+#   - 重分析任务（调研、规范、规划、分析）使用 Opus 语义
+#   - 执行任务（澄清、检查表、任务分解、实现、验证）使用 Sonnet 语义
+#
+# quality-first:
+#   - 所有阶段都按 Opus 语义执行（质量优先，成本较高）
+#
+# cost-efficient:
+#   - 所有阶段都按 Sonnet 语义执行（成本优先，适合探索）
+#
+preset: balanced
+
+# ═══════════════════════════════════════
+# 子代理模型覆盖（第二优先）
+# ═══════════════════════════════════════
+# 使用方式:
+# - 不配置: 全部跟随 preset
+# - 按需取消注释某个 agent: 仅覆盖该阶段
+#
+# 可选值:
+# - Claude 逻辑名（推荐，跨端可移植）: opus | sonnet | haiku
+# - 运行时原生模型名（高级）: 例如 gpt-5.4
+#
+# 常见示例:
+# - plan/verify 想更稳: 改为 opus
+# - tasks/implement 想省成本: 改为 sonnet
+#
+agents:
+  # --- 重分析任务（balanced 预设下默认 opus）---
+  # product-research:
+  #   model: opus
+  # tech-research:
+  #   model: opus
+  # specify:
+  #   model: opus
+  # plan:
+  #   model: opus
+  # analyze:
+  #   model: opus
+
+  # --- 执行任务（balanced 预设下默认 sonnet）---
+  # clarify:
+  #   model: sonnet
+  # checklist:
+  #   model: sonnet
+  # tasks:
+  #   model: sonnet
+  # implement:
+  #   model: sonnet
+  # verify:
+  #   model: sonnet
+
+# ═══════════════════════════════════════
+# 模型运行时兼容（Claude / Codex）
+# ═══════════════════════════════════════
+# 目的:
+# - 保留 preset/agents 的语义（opus/sonnet/haiku）
+# - 在不同运行时自动映射成可用模型名
+#
+# runtime:
+#   auto   - 自动识别运行时（推荐）
+#   claude - 强制按 Claude 映射
+#   codex  - 强制按 Codex 映射
+#
+# aliases:
+#   codex  - Claude 逻辑名 -> Codex 模型名
+#   claude - Codex 模型名 -> Claude 逻辑名（用于反向兼容）
+#
+# defaults:
+#   当映射后的模型不可用时，回退到该运行时默认模型
+#
+# 说明:
+# - Codex 默认统一映射到 `gpt-5.4`
+# - 思考深度不靠“切模型”，而是由下方 `codex_thinking` 和 `service_tier` 控制
+#
+model_compat:
+  runtime: auto
+  aliases:
+    codex:
+      opus: gpt-5.4
+      sonnet: gpt-5.4
+      haiku: gpt-5.4
+    claude:
+      gpt-5.4: sonnet
+      gpt-5.3-codex: sonnet
+      gpt-5: opus
+      gpt-5-mini: sonnet
+      o3: opus
+      o4-mini: sonnet
+  defaults:
+    codex: gpt-5.4
+    claude: sonnet
+
+codex:
+  service_tier: fast
+
+# ═══════════════════════════════════════
+# Codex Thinking 等级（Codex 专用）
+# ═══════════════════════════════════════
+# 适用场景:
+# - runtime=codex 或 auto 且识别为 Codex
+#
+# level 可选值: low | medium | high | xhigh
+#
+# 建议:
+# - 默认使用 xhigh（质量优先）
+# - 复杂设计/关键验证推荐 xhigh
+# - 常规实现可用 high
+# - 简单改动或高并发批处理可用 medium/low
+#
+# level_map 的作用:
+# - 当上游语义模型是 opus/sonnet/haiku 时，映射到对应 thinking level
+# - 未命中时使用 default_level
+#
+codex_thinking:
+  default_level: xhigh
+  level_map:
+    opus: xhigh
+    sonnet: high
+    haiku: medium
+
+# ═══════════════════════════════════════
+# 调研阶段配置（Feature 模式）
+# ═══════════════════════════════════════
+# 控制 Feature 模式中调研阶段的行为
+# Story 模式和 Fix 模式不受此配置影响
+#
+# default_mode 可选值:
+#   auto          — 由编排器根据需求特征智能推荐（默认）
+#   full          — 完整调研（产品+技术+汇总），与当前版本行为一致
+#   tech-only     — 仅技术调研（跳过产品调研和汇总）
+#   product-only  — 仅产品调研（跳过技术调研和汇总）
+#   codebase-scan — 代码库上下文扫描（与 Story 模式相同）
+#   skip          — 跳过调研（不执行任何调研步骤）
+#   custom        — 自定义步骤组合（需配置 custom_steps）
+#
+research:
+  default_mode: auto
+
+  # 自定义步骤（仅当 default_mode: custom 时生效）
+  # 可选步骤: product-research, tech-research, codebase-scan, synthesis
+  # 注意: synthesis 依赖 product-research 和 tech-research 的输出
+  custom_steps: []
+
+# ═══════════════════════════════════════
+# 验证阶段配置
+# ═══════════════════════════════════════
+verification:
+  # 自定义构建/Lint/测试命令
+  # 键名为语言标识（小写），覆盖自动检测的默认命令
+  # 取消注释并修改以使用自定义命令
+  commands: {}
+    # typescript:
+    #   build: "npm run build"
+    #   lint: "npm run lint"
+    #   test: "npm test"
+    # python:
+    #   lint: "ruff check ."
+    #   test: "pytest -v"
+    # rust:
+    #   lint: "cargo clippy -- -D warnings"
+    #   test: "cargo test --all-features"
+
+  # Monorepo 子项目检测
+  monorepo:
+    enabled: true  # 是否启用 Monorepo 子项目自动检测
+
+  # 验证命令超时（秒）
+  # 超时后命令将被自动终止
+  # 默认值: 300（5 分钟）
+  #
+  # timeout: 300
+
+# ═══════════════════════════════════════
+# 质量门配置
+# ═══════════════════════════════════════
+quality_gates:
+  # WARNING 级别发现时自动继续（不暂停）
+  auto_continue_on_warning: true
+  # CRITICAL 级别发现时暂停（此设置不可关闭，仅供参考）
+  pause_on_critical: true
+
+# ═══════════════════════════════════════
+# 门禁策略
+# ═══════════════════════════════════════
+# 控制质量门（Quality Gate）在流程中的暂停行为
+#
+# strict:     所有门禁暂停等待确认（最高人工控制权）
+# balanced:   关键门禁暂停，非关键自动继续（默认，推荐）
+# autonomous: 仅失败或 CRITICAL 问题时暂停（最低中断）
+#
+# 注：GATE_DESIGN 在 feature 模式下始终暂停（硬门禁），不受此配置影响
+gate_policy: balanced
+
+# ═══════════════════════════════════════
+# 门禁级配置（高级，可选）
+# ═══════════════════════════════════════
+# 对每个门禁独立配置，优先于 gate_policy
+# 可选值: always（始终暂停）| auto（始终自动继续）| on_failure（仅失败时暂停）
+#
+# gates:
+#   GATE_RESEARCH:
+#     pause: auto
+#   GATE_DESIGN:
+#     pause: always
+#   GATE_ANALYSIS:
+#     pause: auto
+#   GATE_TASKS:
+#     pause: always
+#   GATE_IMPLEMENT_MID:
+#     pause: on_failure    # 实施中期门禁（>5 tasks 时在 50% 处触发）
+#   GATE_VERIFY:
+#     pause: always
+
+# ═══════════════════════════════════════
+# 子代理重试策略
+# ═══════════════════════════════════════
+retry:
+  # 子代理失败后自动重试的最大次数
+  # 超过此次数后暂停，等待用户决策（重试/跳过/中止）
+  max_attempts: 2
+
+# ═══════════════════════════════════════
+# 进度输出配置
+# ═══════════════════════════════════════
+progress:
+  # 阶段开始/完成时输出进度信息（如 "[3/10] 正在执行技术规划..."）
+  show_stage_progress: true
+  # 阶段完成时输出关键产出摘要
+  show_stage_summary: true

package/plugins/spec-driver/templates/specify-base/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

package/plugins/spec-driver/templates/specify-base/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the checklist phase of the spec-driver orchestrator based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The checklist phase of the orchestrator MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference