speccore 8.3.59 → 8.3.61

package/.agents/skills/spec-deploy/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: spec-deploy
+description: >
+  部署专属 Skill。覆盖 build / deploy / pipeline 命令的意图识别与参数提取。
+  支持自然语言（"部署到测试环境"）和显式参数（--env test --all）。
+  参数缺失时交互式提示，前置校验环境配置与平台有效性。
+  支持 Pipeline 内置测试节点（--test-enabled）和分层测试策略。
+  不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
+disable-model-invocation: false
+---
+
+# spec-deploy — 构建与部署（专属逻辑）
+
+> **定位**：`/deploy` 快捷入口的专属预处理层
+> **覆盖命令**：`speccore build`、`speccore deploy`、`speccore pipeline`
+> **原则**：不影响 `speccore ask` 的意图识别能力
+
+---
+
+## 调用方式
+
+```
+/deploy [自然语言或参数]
+/deploy 部署到测试环境
+/deploy --env test --platforms h5,api
+/deploy --env staging --all --dry-run
+/build --platform h5 --env local
+
+# 测试外部项目（非当前 SpecCore 项目）
+/deploy --project-dir ~/projects/other-app --env staging --all
+/verify --project-dir ~/projects/third-party-api --config ./tests/api.yaml --env-file test
+```
+
+---
+
+## 外部项目支持（v8.3.60+）
+
+`--project-dir` 是**全局选项**，所有命令自动继承。SpecCore 的能力可以"走出去"，用于任意外部项目，不仅限于当前 SpecCore 管理的项目。
+
+### 原理
+
+```
+speccore <任意命令> --project-dir <外部目录>
+         │
+         ▼
+    全局 preAction hook
+         │
+         ▼
+    process.chdir(外部目录)
+         │
+         ▼
+    所有配置从外部目录读取
+    所有操作在外部目录执行
+```
+
+### 外部项目目录结构
+
+```
+~/my-test-projects/
+├── company-app/
+│   ├── PROJECT.yaml                    # 定义 platforms（可选）
+│   ├── .speccore/
+│   │   └── environments/
+│   │       ├── staging.yaml            # 环境配置 + tests.base_urls
+│   │       └── production.yaml
+│   ├── tests/
+│   │   ├── smoke.yaml                  # 测试场景
+│   │   └── api.yaml
+│   └── API_CONTRACT.yaml               # API 契约（可选）
+│
+└── third-party-api/
+    ├── .speccore/
+    │   └── environments/
+    │       └── test.yaml
+    └── tests/
+        └── quick.yaml
+```
+
+### 各命令外部项目示例
+
+```bash
+# ===== 测试相关 =====
+# Pipeline 测试外部项目
+speccore pipeline --project-dir ~/my-test-projects/company-app --env staging --all
+
+# Verify 测试外部项目
+speccore verify --project-dir ~/my-test-projects/company-app --config ./tests/smoke.yaml
+
+# 仅做构建检查（无需 PROJECT.yaml）
+speccore verify --project-dir ~/my-test-projects/company-app --ui --url https://staging.example.com
+
+# ===== 文档转换（像 doc2spec 一样外用）=====
+# 将外部项目的 PRD 转换为 Spec
+speccore doc2spec --project-dir ~/my-test-projects/company-app --input ./docs/requirement.docx
+
+# 将外部项目的 Spec 导出为 Word
+speccore spec2doc --project-dir ~/my-test-projects/company-app --output ./reports/
+
+# ===== 项目诊断 =====
+# 诊断外部项目的健康度
+speccore doctor --project-dir ~/my-test-projects/company-app --fix
+
+# ===== 搜索 =====
+# 在外部项目中搜索文档
+speccore search --project-dir ~/my-test-projects/company-app "登录相关的需求"
+
+# ===== 构建部署 =====
+# 构建/部署外部项目
+speccore build --project-dir ~/my-test-projects/company-app --env staging --platform h5
+speccore deploy --project-dir ~/my-test-projects/company-app --env staging --all
+```
+
+### 最小外部项目配置
+
+外部项目可以只有环境配置，无需完整的 SpecCore 项目结构：
+
+```yaml
+# ~/my-test-projects/minimal/.speccore/environments/test.yaml
+env: test
+tests:
+  base_urls:
+    h5: https://example.com
+```
+
+```bash
+speccore verify --project-dir ~/my-test-projects/minimal --ui --env-file test
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /deploy [输入]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 意图识别                        │
+│ 判断是 build / deploy / pipeline        │
+│ 从自然语言或显式参数提取参数              │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验                        │
+│ - 环境配置是否存在？                    │
+│ - 指定平台是否在 PROJECT.yaml 中？      │
+│ - 当前分支是否能获取？（pipeline 需要）  │
+└───────────────┬───────────────────────┘
+                │
+        校验失败？
+                │
+        是 ──► 输出问题 + 修复建议
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 执行                            │
+│ 直接 execute_command 执行 CLI 命令      │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 意图识别与参数提取
+
+### 双模式支持
+
+**模式 A — 自然语言（默认）**：
+```
+/deploy 把当前功能部署到测试环境
+/deploy 构建一下 H5
+/deploy 预览生产环境部署
+```
+AI 从自然语言中提取参数。
+
+**模式 B — 显式参数**：
+```
+/deploy --env test --platforms h5,api --dry-run
+/build --env local --platform h5
+```
+直接解析参数，不经过自然语言理解。
+
+### 参数定义
+
+| 参数 | 短名 | 长名 | 必填 | 默认值 | 说明 |
+|:---|:---|:---|:---|:---|:---|
+| env | -e | --env | 否 | `staging` | 目标环境名（对应 .speccore/environments/{env}.yaml） |
+| platforms | -p | --platforms | 否 | - | 逗号分隔端列表（与 --all 互斥） |
+| all | -a | --all | 否 | false | 所有端 |
+| dry-run | -d | --dry-run | 否 | false | 预览模式，不实际执行 |
+| skip-build | -s | --skip-build | 否 | false | 跳过构建（仅 pipeline） |
+| env-file | -f | --env-file | 否 | - | 指定环境配置文件路径 |
+| project-dir | - | --project-dir | 否 | - | 外部项目目录路径（全局选项） |
+
+### 意图映射表
+
+| 用户说法 | 推断命令 | 推断参数 |
+|:---|:---|:---|
+| "部署到测试环境" | pipeline | --env test --all |
+| "构建 H5" | build | --platform h5 |
+| "部署 H5 到测试环境" | pipeline | --env test --platforms h5 |
+| "预览生产部署" | pipeline | --env production --all --dry-run |
+| "把当前分支合并到 develop 并部署" | pipeline | --env dev --all |
+| "只部署不构建" | pipeline | --env staging --all --skip-build |
+| "用自定义配置部署" | pipeline | --env-file ./my-env.yaml --all |
+| "本地构建验证" | build | --env local --platform h5 |
+| "本地部署看看效果" | deploy | --env local --platform h5 |
+| "跑冒烟测试" | verify | --stage deploy |
+| "PR 前跑测试" | verify | --stage pr |
+| "发布前全量回归" | verify | --stage release |
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+### 环境名缺失
+
+```
+🚀 speccore deploy — 请选择目标环境
+
+可用环境（从 .speccore/environments/ 读取）：
+  [1] local    — 本地开发
+  [2] dev      — 开发联调
+  [3] test     — 测试环境
+  [4] staging  — 预发布
+  [5] production — 生产环境
+
+请回复环境名或序号（如：test 或 3）
+```
+
+### 平台缺失（且未指定 --all）
+
+```
+📦 speccore deploy — 请选择目标平台
+
+可用平台（从 PROJECT.yaml 读取）：
+  [1] h5         — H5 移动端
+  [2] admin-web  — 管理后台
+  [3] order-api  — 订单服务
+
+选项：
+  - 回复平台名或序号（如：h5 或 1）
+  - 回复 "all" 或 "全部" 部署所有平台
+  - 回复逗号分隔多选（如：h5,order-api）
+```
+
+---
+
+## Step 3: 前置校验
+
+### 校验项
+
+1. **环境配置存在性**
+   - 检查 `.speccore/environments/{env}.yaml` 是否存在
+   - 不存在 → 提示："环境 {env} 未配置，运行 `speccore update` 初始化默认环境配置"
+
+2. **平台有效性**
+   - 检查指定平台是否在 PROJECT.yaml 的 platforms 列表中
+   - 不存在 → 提示可用平台列表
+
+3. **pipeline 分支检查**
+   - 检查环境配置中是否配置了 `branch`
+   - 未配置 → 提示："环境 {env} 未配置 branch，pipeline 无法执行 merge"
+
+4. **Git 仓库检查（pipeline 需要）**
+   - 检查当前目录是否为 Git 仓库
+   - 检查当前分支是否能获取
+
+---
+
+## 命令组装规则
+
+### pipeline（默认）
+```bash
+speccore pipeline --env {env} {--platforms p1,p2 | --all} [--dry-run] [--skip-build] [--env-file path] [--project-dir dir]
+```
+
+### build
+```bash
+speccore build --env {env} {--platform p | --all} [--env-file path] [--project-dir dir]
+```
+
+### deploy
+```bash
+speccore deploy --env {env} {--platform p | --all} [--dry-run] [--skip-build] [--env-file path] [--project-dir dir]
+```
+
+**意图 → 命令映射**：
+- 用户说"构建"或"build" → `build`
+- 用户说"部署"且不带 merge/checkout → `deploy`
+- 用户说"流水线"、"合并部署"、"pipeline"或只说"部署"（含 merge 语义）→ `pipeline`
+
+---
+
+## 错误处理
+
+| 场景 | 提示 |
+|:---|:---|
+| 环境配置不存在 | "环境 {env} 未配置，运行 `speccore update` 初始化默认环境配置" |
+| 平台不存在 | "平台 {platform} 不在 PROJECT.yaml 中，可用平台：..." |
+| 分支未配置 | "环境 {env} 未配置 branch，pipeline 无法执行 merge" |
+| Git 检查失败 | "当前目录不是 Git 仓库，或无法获取当前分支" |

package/.agents/skills/spec-verify/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: spec-verify
+description: >
+  测试验证专属 Skill。覆盖 verify 命令的测试意图识别与参数提取。
+  支持自然语言（"跑一下冒烟测试"）和显式参数（--config ./tests/smoke.yaml --stage deploy）。
+  参数缺失时交互式提示，自动发现测试配置文件。支持 --project-dir 测试外部项目。
+  不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
+disable-model-invocation: false
+---
+
+# spec-verify — 测试验证（专属逻辑）
+
+> **定位**：`/verify` 快捷入口的专属预处理层
+> **覆盖命令**：`speccore verify`
+> **原则**：不影响 `speccore ask` 的意图识别能力
+
+---
+
+## 调用方式
+
+```
+/verify [自然语言或参数]
+/verify 跑一下冒烟测试
+/verify --stage pr
+/verify --config ./tests/smoke.yaml --env-file test
+/verify --project-dir ~/projects/other-app --stage deploy
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /verify [输入]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 意图识别                        │
+│ 判断测试类型、阶段、目标项目              │
+│ 从自然语言或显式参数提取参数              │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验                        │
+│ - 测试配置文件是否存在？                  │
+│ - 环境配置是否存在？                     │
+│ - 外部项目目录是否有效？                 │
+└───────────────┬───────────────────────┘
+                │
+        校验失败？
+                │
+        是 ──► 输出问题 + 修复建议
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 执行                            │
+│ 直接 execute_command 执行 CLI 命令      │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 意图识别与参数提取
+
+### 双模式支持
+
+**模式 A — 自然语言（默认）**：
+```
+/verify 跑冒烟测试
+/verify PR 前检查一下
+/verify 发布前全量回归
+/verify 测试一下 H5
+```
+AI 从自然语言中提取参数。
+
+**模式 B — 显式参数**：
+```
+/verify --stage deploy --project-dir ~/my-app
+/verify --config ./tests/smoke.yaml --env-file staging
+/verify --ui --url https://example.com
+```
+直接解析参数，不经过自然语言理解。
+
+### 参数定义
+
+| 参数 | 短名 | 长名 | 必填 | 默认值 | 说明 |
+|:---|:---|:---|:---|:---|:---|
+| stage | -s | --stage | 否 | - | 测试阶段：dev/pr/deploy/release |
+| config | -c | --config | 否 | - | 测试场景配置文件路径 |
+| env-file | -e | --env-file | 否 | - | 环境配置文件路径或环境名 |
+| ui | -u | --ui | 否 | false | 启用 UI 验证 |
+| smoke-only | - | --smoke-only | 否 | false | 仅冒烟测试 |
+| visual-only | - | --visual-only | 否 | false | 仅视觉检查 |
+| api-contract | - | --api-contract | 否 | false | API 契约测试 |
+| perf | - | --perf | 否 | false | 性能基线测试 |
+| type | -t | --type | 否 | - | 验证类型：compile/lint/test/all |
+| url | - | --url | 否 | - | 目标 URL（独立模式） |
+| spec | - | --spec | 否 | - | VERIFY_SPEC.yaml 路径 |
+| router-file | - | --router-file | 否 | - | 前端路由配置文件路径 |
+| project-dir | - | --project-dir | 否 | - | 外部项目目录路径 |
+
+### 意图映射表
+
+| 用户说法 | 推断命令 | 推断参数 |
+|:---|:---|:---|
+| "跑冒烟测试" | verify | --stage deploy |
+| "PR 前检查一下" | verify | --stage pr |
+| "发布前全量回归" | verify | --stage release |
+| "开发时跑测试" | verify | --stage dev |
+| "测试一下 H5" | verify | --ui --config ./tests/smoke.yaml |
+| "验证 API 契约" | verify | --api-contract |
+| "跑视觉检查" | verify | --ui --visual-only |
+| "测试外部项目" | verify | --project-dir {路径} --stage deploy |
+
+### 阶段映射详情
+
+| stage | 自动参数 | 覆盖范围 |
+|:---|:---|:---|
+| dev | --type all | 编译 + Lint + 单元测试 |
+| pr | --type all --ui --smoke-only --api-contract | 代码质量 + 关键页面冒烟 + API 契约 |
+| deploy | --ui --smoke-only | 仅 UI 冒烟测试 |
+| release | --ui --api-contract --perf | 全量 UI + API + 性能回归 |
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+### 测试阶段缺失
+
+```
+🧪 speccore verify — 请选择测试阶段
+
+可用阶段：
+  [1] dev      — 开发阶段（编译 + Lint + 单元测试）
+  [2] pr       — PR 阶段（代码质量 + 冒烟 + API 契约）
+  [3] deploy   — 部署阶段（仅冒烟测试）
+  [4] release  — 发布阶段（全量回归）
+
+请回复阶段名或序号（如：deploy 或 3）
+```
+
+### 测试配置缺失（--stage 指定但无对应配置）
+
+```
+⚠️ 未找到阶段对应的测试配置文件
+
+建议操作：
+  1. 运行 speccore update 初始化默认测试配置模板
+  2. 手动创建 .speccore/tests/smoke.yaml
+  3. 使用 --config 显式指定配置路径
+```
+
+---
+
+## Step 3: 前置校验
+
+### 校验项
+
+1. **外部项目目录有效性**（指定 --project-dir 时）
+   - 检查目录是否存在
+   - 检查是否为 Git 仓库（可选）
+
+2. **测试配置文件存在性**（指定 --config 时）
+   - 检查文件是否存在
+   - 不存在 → 提示可用配置列表
+
+3. **环境配置存在性**（指定 --env-file 时）
+   - 检查 `.speccore/environments/{env}.yaml` 是否存在
+   - 不存在 → 提示可用环境列表
+
+---
+
+## 命令组装规则
+
+### verify（默认）
+```bash
+speccore verify [--stage {stage}] [--config {path}] [--env-file {env}] [--ui] [--smoke-only] [--visual-only] [--api-contract] [--perf] [--type {type}] [--url {url}] [--spec {spec}] [--router-file {path}] [--project-dir {dir}]
+```
+
+**意图 → 命令映射**：
+- 用户说"冒烟"、"smoke" → `--stage deploy` 或 `--ui --smoke-only`
+- 用户说"PR"、"提交前" → `--stage pr`
+- 用户说"发布"、"上线前"、"回归" → `--stage release`
+- 用户说"编译"、"lint"、"单元测试" → `--stage dev`
+- 用户说"视觉"、"截图" → `--ui --visual-only`
+- 用户说"API"、"契约" → `--api-contract`
+- 用户说"性能" → `--perf`
+
+---
+
+## 外部项目测试
+
+```bash
+/verify --project-dir ~/projects/other-app --stage deploy
+/verify --project-dir ~/projects/other-app --config ./tests/smoke.yaml
+```
+
+最小外部项目配置：
+```yaml
+# ~/my-test-projects/minimal/.speccore/environments/test.yaml
+env: test
+tests:
+  base_urls:
+    h5: https://example.com
+```
+
+---
+
+## 错误处理
+
+| 场景 | 提示 |
+|:---|:---|
+| 测试配置不存在 | "未找到测试配置文件，运行 `speccore update` 初始化默认配置" |
+| 环境配置不存在 | "环境 {env} 未配置，运行 `speccore update` 初始化默认环境" |
+| 外部项目目录无效 | "目录 {path} 不存在，请检查路径" |
+| 视觉模型调用失败 | "视觉模型调用失败，检查 DASHSCOPE_API_KEY / OPENAI_API_KEY 环境变量" |

package/README.md

@@ -1,6 +1,6 @@
 # SpecCore — Code by Spec, Not by Vibe
 
-🖥️ 规范驱动开发 CLI · 20 命令 · 人机协同闭环 · 多层 AI 架构
+🖥️ 规范驱动开发 CLI · 26+ 命令 · 环境驱动部署 · 全命令 Skill 覆盖 · 多层 AI 架构
 
 ```bash
 @spec-ask "分析会议预订系统的需求文档，拆分为独立开发任务，按依赖顺序执行"
@@ -69,7 +69,7 @@ init → doc2spec → analyze → split → plan → execute → pr → done →
 | 🔒 AI 流水线 | `doc2spec` `analyze` `split` `plan` `execute` `pr` `done` `spec2doc` |
 | 🔒 AI 智能 | `dev` |
 | 🔒 AI 变更 | `change` `retro` |
-| ✅ 质量验证 | `verify` `verify --ui` `verify --api-contract` `verify --perf` |
+| ✅ 质量验证 | `verify` `verify --ui` `verify --stage` `verify --api-contract` `verify --perf` `verify --project-dir` |
 
 ## 目录结构（全英文）
 
@@ -101,6 +101,45 @@ Iteration-001-meeting/
 └── STAFFING.md                 ← 人员排期
 ```
 
+## 环境驱动部署（v8.3.60+）
+
+```bash
+# 一键流水线：merge → build → deploy
+speccore pipeline --env staging --all              # 部署到预发布环境
+speccore pipeline --env test --platforms h5,api    # 只部署 H5 和 API
+speccore pipeline --env dev --all --dry-run        # 预览模式
+
+# Pipeline 内置测试节点（v8.3.60+）
+speccore pipeline --env staging --all --test-enabled --test-type smoke
+
+# 独立构建/部署
+speccore build --env staging --platform h5         # 构建 H5 端
+speccore deploy --env production --all             # 部署到生产环境
+```
+
+**五层环境模型**：`local` → `dev` → `test` → `staging` → `production`
+
+**环境配置**（`.speccore/environments/staging.yaml`）：
+```yaml
+env: staging
+branch: staging
+defaults:
+  build_cmd: npm run build:staging
+platforms:
+  h5:
+    build_cmd: npm run build:h5:staging
+    deploy:
+      type: static
+      output_dir: dist
+      target: s3://mybucket-staging/h5/
+```
+
+**特性**：
+- `--env` 读取环境配置中的 `branch`，自动 merge 当前分支
+- 配置覆盖：环境文件 > PROJECT.yaml > 默认值
+- 失败不阻断：某端失败继续处理其他端
+- 支持任意数量自定义环境
+
 ## 质量验证（v8.3.47+）
 
 ```bash
@@ -108,12 +147,24 @@ Iteration-001-meeting/
 speccore verify -t Task-001 --ui                          # 任务绑定模式
 speccore verify --ui --url=https://example.com --spec=./test.yaml  # 独立模式
 
+# 配置驱动测试（v8.3.60+）
+speccore verify --config ./tests/smoke.yaml --env-file test  # 加载测试场景 + 合并环境配置
+
 # API 契约测试（v8.3.49+）
 speccore verify -t Task-001 --api-contract
 
 # 性能基线测试（v8.3.49+）
 speccore verify -t Task-001 --perf
 
+# 分层测试策略（v8.3.60+）
+speccore verify --stage dev                  # 开发阶段：编译 + Lint + 单元测试
+speccore verify --stage pr                   # PR 阶段：代码质量 + 冒烟 + API 契约
+speccore verify --stage deploy               # 部署阶段：仅冒烟测试
+speccore verify --stage release              # 发布阶段：全量 UI + API + 性能回归
+
+# 测试外部项目（v8.3.60+）
+speccore verify --project-dir ~/projects/other-app --stage deploy
+
 # 视觉模型切换（v8.3.50+）
 speccore verify --ui --visual-model=qwen-vl               # 阿里云 DashScope（默认）
 speccore verify --ui --visual-model=local                 # 本地模型
@@ -308,6 +359,12 @@ speccore --version   # v8.3.10
 | `retro` | `rt` | 📝 🔒 任务回顾复盘 + 评分 |
 | `rename` | `rn` | ✏️ 🔒 重命名 |
 | `history` | `hi` | 📜 历史记录（操作日志 / 需求变更） |
+| `pipeline` | `pln` | 🚀 环境驱动流水线（merge → build → deploy） |
+| `build` | `bd` | 🔨 按端构建 |
+| `deploy` | `dp` | 🚀 按端部署 |
+| `verify` | `vf` | 🧪 代码验证 + UI 测试 |
+
+> 💡 **全命令 Skill**：所有命令均支持 `/命令 + 自然语言` 快捷入口，如 `/deploy 部署到测试环境`、`/verify 跑冒烟测试`。详见 [DESIGN.md](docs/DESIGN.md#58-全命令-skill-覆盖v8360)。
 
 ## TTY 智能适配
 
@@ -331,7 +388,7 @@ speccore --version   # v8.3.10
 | 中文 | English | 说明 |
 |------|---------|------|
 | [快速开始](docs/quick-start.md) | [Quick Start](docs/quick-start.en.md) | 5 分钟上手，安装 → 完整流程 |
-| [命令参考](docs/command-reference.md) | [Commands](docs/commands.en.md) | 全部 20 命令 + 子命令 + 示例 |
+| [命令参考](docs/command-reference.md) | [Commands](docs/commands.en.md) | 全部 26+ 命令 + 子命令 + 示例 |
 | [总览](docs/overview.md) | — | 核心概念 + 工作流 + 三种使用方式 |
 | [场景实战](docs/scenarios.md) | [Scenarios](docs/scenarios.en.md) | 35 个真实开发场景 |
 | [SDD 方法论](docs/sdd-methodology.md) | [SDD](docs/sdd-methodology.en.md) | 规范驱动开发理念 |