speccore 8.3.333 → 8.3.341

package/templates/deploy-examples.yaml

@@ -12,6 +12,25 @@
 #   speccore deploy --env production --platform h5 --dry-run   # 预览模式
 #
 # ═══════════════════════════════════════════════════════════
+# 公共字段字典（所有部署类型通用，按需选用）
+# ═══════════════════════════════════════════════════════════
+#   type         → 部署类型：ssh / sftp / static / script / docker / pm2 / k8s / helm / vercel / serverless
+#   build_cmd    → 构建命令（部署前执行，如 npm run build:staging）
+#   output_dir   → 构建产物目录（上传/部署的对象，如 dist）
+#   host         → 远程主机（格式 user@host[:port]，配置后走远程部署）
+#   key          → SSH 私钥路径（密钥认证，推荐；与 password 二选一）
+#   password     → SSH 密码（v8.3.91+，需安装 sshpass；与 key 二选一）
+#   remote_dir   → 远程目录（上传目标，须有写权限）
+#   script       → 部署后执行的命令/脚本路径（远程重启服务等）
+#   pre_deploy   → 部署前钩子（命令列表，逐条执行）
+#   post_deploy  → 部署后钩子（命令列表，逐条执行）
+#   target       → 目标位置（static=本地目录/S3/rsync 地址，k8s/helm=namespace，serverless=函数名）
+#   dockerfile   → Dockerfile 路径（docker 类型，默认 ./Dockerfile）
+#   registry     → 镜像仓库地址（docker 类型，远程部署必须配置）
+#   image        → 镜像名（docker 类型）
+#   tag          → 镜像标签（docker 类型）
+#   pm2_config   → PM2 配置文件（pm2 类型，默认 ecosystem.config.js）
+# ═══════════════════════════════════════════════════════════
 
 # ─────────────────────────────────────────
 # 1. SSH 部署（推荐：有独立服务器的场景）
@@ -32,15 +51,24 @@
 #     2) 配置 password 字段
 #
 ssh_key_example:
+  # type: 部署类型
   type: ssh
+  # build_cmd: 部署前构建命令
   build_cmd: npm run build:staging
+  # output_dir: 构建产物目录
   output_dir: dist
+  # host: 远程主机（user@host:port）
   host: deployer@192.168.1.100:22
+  # key: SSH 私钥路径（密钥认证）
   key: ~/.ssh/id_rsa
+  # remote_dir: 远程上传目录
   remote_dir: /var/www/html/h5
+  # script: 部署后命令（重载 Nginx）
   script: sudo nginx -s reload
+  # pre_deploy: 部署前钩子
   pre_deploy:
     - echo "开始部署到 staging..."
+  # post_deploy: 部署后钩子
   post_deploy:
     - echo "部署完成"
 
@@ -50,7 +78,7 @@ ssh_password_example:
   build_cmd: npm run build:staging
   output_dir: dist
   host: deployer@192.168.1.100:22
-  password: your-password-here          # SSH 密码（v8.3.91+，需安装 sshpass）
+  password: your-password-here          # SSH 密码（v8.3.91+，需安装 sshpass；与 key 二选一）
   remote_dir: /var/www/html/h5
   script: sudo nginx -s reload
 
@@ -138,10 +166,10 @@ script_ftp_example:
 # 基础 Docker：仅本地构建并推送到仓库（适合 CI/CD 场景）
 docker_push_only:
   type: docker
-  dockerfile: ./Dockerfile
-  registry: registry.example.com
-  image: my-project/h5
-  tag: staging
+  dockerfile: ./Dockerfile                       # Dockerfile 路径
+  registry: registry.example.com                 # 镜像仓库地址（远程部署必须配置）
+  image: my-project/h5                           # 镜像名
+  tag: staging                                   # 镜像标签
 
 # 前端 Docker + 远程部署（Nginx 托管）
 docker_frontend_remote:

package/templates/html/speccore-ask-explain.html

@@ -7,4 +7,4 @@
 .match-result{padding:10px 0}.match-summary{font-weight:600;font-size:14px;margin-bottom:12px}.match-detail{color:var(--muted);font-size:12px;line-height:1.6}
 /* Pipeline */
 .pipeline-title{font-weight:600;margin-bottom:16px}.pipeline-steps{display:flex;flex-direction:column;gap:10px}.pipe-step{display:flex;gap:14px;padding:12px 14px;background:rgba(99,102,241,.04);border-left:2px solid var(--purple);border-radius:0 8px 8px 0}.pipe-step .pipe-num{font-family:Orbitron;font-size:20px;font-weight:900;color:var(--purple);min-width:36px}.pipe-step .pipe-cmd{font-weight:600;color:var(--green)}.pipe-step .pipe-args{color:var(--muted);font-size:11px}.pipe-step .pipe-desc{color:var(--muted);font-size:10px;margin-top:4px}.pipe-step .pipe-dep{font-size:9px;color:var(--orange);margin-top:4px}.confirm-bar{text-align:center;padding:14px;margin-top:16px;background:rgba(99,102,241,.08);border:1px dashed rgba(99,102,241,.2);border-radius:8px;color:var(--purple);font-size:12px}
-.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}h1{text-shadow:0 0 20px rgba(14,165,233,.35),0 0 60px rgba(14,165,233,.12)!important}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"dashboard怎么用"</div><div class="badge">📖 命令解释</div><div class="explain-box"><div class="explain-desc">项目仪表盘：期次状态/进度/健康度，--scope global 全量视图</div><div class="explain-usage"><span class="label">用法</span><code>speccore dashboard [--scope global|iteration] [--export html] [--health] [--lifecycle]</code></div><div class="explain-related"><span class="label">关联</span><span class="tag">analyze</span> <span class="tag">health</span></div></div><div style="text-align:center;margin-top:16px"><a href="speccore-welcome.html" style="color:var(--cyan);font-size:11px;text-decoration:none">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · 2026-08-31</div></div></body></html>
+.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}h1{text-shadow:0 0 20px rgba(14,165,233,.35),0 0 60px rgba(14,165,233,.12)!important}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"dashboard怎么用"</div><div class="badge">📖 命令解释</div><div class="explain-box"><div class="explain-desc">项目仪表盘：期次状态/进度/健康度，--scope global 全量视图</div><div class="explain-usage"><span class="label">用法</span><code>speccore dashboard [--scope global|iteration] [--export html] [--health] [--lifecycle]</code></div><div class="explain-related"><span class="label">关联</span><span class="tag">analyze</span> <span class="tag">health</span></div></div><div style="text-align:center;margin-top:16px"><a href="speccore-ask-onboarding.html" style="color:var(--cyan);font-size:11px;text-decoration:none">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · 2026-08-31</div></div></body></html>

package/templates/html/speccore-ask-guide.html

@@ -7,4 +7,4 @@
 .match-result{padding:10px 0}.match-summary{font-weight:600;font-size:14px;margin-bottom:12px}.match-detail{color:var(--muted);font-size:12px;line-height:1.6}
 /* Pipeline */
 .pipeline-title{font-weight:600;margin-bottom:16px}.pipeline-steps{display:flex;flex-direction:column;gap:10px}.pipe-step{display:flex;gap:14px;padding:12px 14px;background:rgba(99,102,241,.04);border-left:2px solid var(--purple);border-radius:0 8px 8px 0}.pipe-step .pipe-num{font-family:Orbitron;font-size:20px;font-weight:900;color:var(--purple);min-width:36px}.pipe-step .pipe-cmd{font-weight:600;color:var(--green)}.pipe-step .pipe-args{color:var(--muted);font-size:11px}.pipe-step .pipe-desc{color:var(--muted);font-size:10px;margin-top:4px}.pipe-step .pipe-dep{font-size:9px;color:var(--orange);margin-top:4px}.confirm-bar{text-align:center;padding:14px;margin-top:16px;background:rgba(99,102,241,.08);border:1px dashed rgba(99,102,241,.2);border-radius:8px;color:var(--purple);font-size:12px}
-.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}h1{text-shadow:0 0 20px rgba(14,165,233,.35),0 0 60px rgba(14,165,233,.12)!important}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"我想做一个登录功能"</div><div class="badge">🗺️ 任务指引</div><div class="guide-title">已为你规划「新功能开发全流程」（9 步）</div><div class="guide-steps"><div class="guide-step"><div class="step-num">1</div><div class="step-body"><div class="step-cmd">speccore init</div><div class="step-desc">初始化项目（如果还没有）</div></div></div><div class="guide-step"><div class="step-num">2</div><div class="step-body"><div class="step-cmd">speccore doc2spec -f PRD.docx --iter {iteration}</div><div class="step-desc">导入 PRD 文档，AI 分析生成需求规格</div></div></div><div class="guide-step"><div class="step-num">3</div><div class="step-body"><div class="step-cmd">speccore analyze --iteration {iteration} --audit</div><div class="step-desc">AI 分析需求，生成审计报告</div></div></div><div class="guide-step"><div class="step-num">4</div><div class="step-body"><div class="step-cmd">speccore iteration taskify -f REQUIREMENT.md</div><div class="step-desc">将需求拆分为独立开发任务</div></div></div><div class="guide-step"><div class="step-num">5</div><div class="step-body"><div class="step-cmd">speccore plan --all</div><div class="step-desc">生成任务执行计划，确定优先级和依赖</div></div></div><div class="guide-step"><div class="step-num">6</div><div class="step-body"><div class="step-cmd">speccore execute --auto</div><div class="step-desc">按计划依次执行开发任务</div></div></div><div class="guide-step"><div class="step-num">7</div><div class="step-body"><div class="step-cmd">speccore verify --ui</div><div class="step-desc">本地冒烟测试（自动登录 + 页面冒烟，默认 module 范围）</div></div></div><div class="guide-step"><div class="step-num">8</div><div class="step-body"><div class="step-cmd">speccore pr --auto</div><div class="step-desc">代码提交后创建 Pull Request</div></div></div><div class="guide-step"><div class="step-num">9</div><div class="step-body"><div class="step-cmd">speccore done --all</div><div class="step-desc">全部完成后归档收尾</div></div></div></div><div style="text-align:center;margin-top:16px"><a href="speccore-welcome.html" style="color:var(--cyan);font-size:11px;text-decoration:none">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · v8.3.333 · 2026-08-31</div></div></body></html>
+.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}h1{text-shadow:0 0 20px rgba(14,165,233,.35),0 0 60px rgba(14,165,233,.12)!important}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"我想做一个登录功能"</div><div class="badge">🗺️ 任务指引</div><div class="guide-title">已为你规划「新功能开发全流程」（9 步）</div><div class="guide-steps"><div class="guide-step"><div class="step-num">1</div><div class="step-body"><div class="step-cmd">speccore init</div><div class="step-desc">初始化项目（如果还没有）</div></div></div><div class="guide-step"><div class="step-num">2</div><div class="step-body"><div class="step-cmd">speccore doc2spec -f PRD.docx --iter {iteration}</div><div class="step-desc">导入 PRD 文档，AI 分析生成需求规格</div></div></div><div class="guide-step"><div class="step-num">3</div><div class="step-body"><div class="step-cmd">speccore analyze --iteration {iteration} --audit</div><div class="step-desc">AI 分析需求，生成审计报告</div></div></div><div class="guide-step"><div class="step-num">4</div><div class="step-body"><div class="step-cmd">speccore iteration taskify -f REQUIREMENT.md</div><div class="step-desc">将需求拆分为独立开发任务</div></div></div><div class="guide-step"><div class="step-num">5</div><div class="step-body"><div class="step-cmd">speccore plan --all</div><div class="step-desc">生成任务执行计划，确定优先级和依赖</div></div></div><div class="guide-step"><div class="step-num">6</div><div class="step-body"><div class="step-cmd">speccore execute --auto</div><div class="step-desc">按计划依次执行开发任务</div></div></div><div class="guide-step"><div class="step-num">7</div><div class="step-body"><div class="step-cmd">speccore verify --ui</div><div class="step-desc">本地冒烟测试（自动登录 + 页面冒烟，默认 module 范围）</div></div></div><div class="guide-step"><div class="step-num">8</div><div class="step-body"><div class="step-cmd">speccore pr --auto</div><div class="step-desc">代码提交后创建 Pull Request</div></div></div><div class="guide-step"><div class="step-num">9</div><div class="step-body"><div class="step-cmd">speccore done --all</div><div class="step-desc">全部完成后归档收尾</div></div></div></div><div style="text-align:center;margin-top:16px"><a href="speccore-ask-onboarding.html" style="color:var(--cyan);font-size:11px;text-decoration:none">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · v8.3.341 · 2026-08-31</div></div></body></html>

package/templates/html/speccore-ask-match.html

@@ -7,4 +7,4 @@
 .match-result{padding:10px 0}.match-summary{font-weight:600;font-size:14px;margin-bottom:12px}.match-detail{color:var(--muted);font-size:12px;line-height:1.6}
 /* Pipeline */
 .pipeline-title{font-weight:600;margin-bottom:16px}.pipeline-steps{display:flex;flex-direction:column;gap:10px}.pipe-step{display:flex;gap:14px;padding:12px 14px;background:rgba(99,102,241,.04);border-left:2px solid var(--purple);border-radius:0 8px 8px 0}.pipe-step .pipe-num{font-family:Orbitron;font-size:20px;font-weight:900;color:var(--purple);min-width:36px}.pipe-step .pipe-cmd{font-weight:600;color:var(--green)}.pipe-step .pipe-args{color:var(--muted);font-size:11px}.pipe-step .pipe-desc{color:var(--muted);font-size:10px;margin-top:4px}.pipe-step .pipe-dep{font-size:9px;color:var(--orange);margin-top:4px}.confirm-bar{text-align:center;padding:14px;margin-top:16px;background:rgba(99,102,241,.08);border:1px dashed rgba(99,102,241,.2);border-radius:8px;color:var(--purple);font-size:12px}
-.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}h1{text-shadow:0 0 20px rgba(14,165,233,.35),0 0 60px rgba(14,165,233,.12)!important}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"查看进度"</div><div class="badge">🎯 意图匹配</div><div class="match-result"><div class="match-summary">✅ 推荐: dashboard</div><div class="match-detail">🎯 推荐命令: <code>speccore dashboard<br>项目仪表盘：期次状态/进度/健康度，--scope</code> global 全量视图<br><br>用法: <code>speccore dashboard</code> [--scope global|iteration] [--export html] [--health] [--lifecycle]<br><br>示例:<br>  $ <code>speccore dashboard<br></code>  $ <code>speccore dashboard</code> --scope global --export html</div></div><div style="text-align:center;margin-top:16px"><a href="speccore-welcome.html" style="color:var(--cyan);font-size:11px;text-decoration:none">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · 2026-08-31</div></div></body></html>
+.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}h1{text-shadow:0 0 20px rgba(14,165,233,.35),0 0 60px rgba(14,165,233,.12)!important}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"查看进度"</div><div class="badge">🎯 意图匹配</div><div class="match-result"><div class="match-summary">✅ 推荐: dashboard</div><div class="match-detail">🎯 推荐命令: <code>speccore dashboard<br>项目仪表盘：期次状态/进度/健康度，--scope</code> global 全量视图<br><br>用法: <code>speccore dashboard</code> [--scope global|iteration] [--export html] [--health] [--lifecycle]<br><br>示例:<br>  $ <code>speccore dashboard<br></code>  $ <code>speccore dashboard</code> --scope global --export html</div></div><div style="text-align:center;margin-top:16px"><a href="speccore-ask-onboarding.html" style="color:var(--cyan);font-size:11px;text-decoration:none">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · 2026-08-31</div></div></body></html>

package/templates/html/speccore-ask-pipeline.html

@@ -1 +1 @@
-<!DOCTYPE html><html lang="zh-CN" data-theme="ocean"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>SpecCore · ask --pipeline</title><style>@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@500;700;900&family=JetBrains+Mono:wght@400;600;700&display=swap');[data-theme="ocean"]{--cyan:#0ea5e9;--bg:#0b1929;--card:rgba(13,31,56,.95);--border:rgba(14,165,233,.15);--text:#bae6fd;--muted:#5b7fa5;--green:#14b8a6;--orange:#f97316;--purple:#6366f1}*{margin:0;padding:0;box-sizing:border-box}body{font-family:'JetBrains Mono',monospace;background:var(--bg);color:var(--text);min-height:100vh;display:flex;align-items:center;justify-content:center;padding:20px}.scanlines{position:fixed;inset:0;pointer-events:none;z-index:99;background:repeating-linear-gradient(0deg,transparent,transparent 2px,rgba(0,240,255,.01) 2px,rgba(0,240,255,.01) 4px)}.card{max-width:900px;width:100%;margin:0 auto;background:var(--card);border:1px solid var(--border);border-radius:16px;padding:32px;position:relative;overflow:hidden;z-index:1}.card::before{content:'';position:absolute;top:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX 3s linear infinite}.card::after{content:'';position:absolute;bottom:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX-rev 3s linear infinite}@keyframes scanX{0%{transform:translateX(-100%)}100%{transform:translateX(100%)}}@keyframes scanX-rev{0%{transform:translateX(100%)}100%{transform:translateX(-100%)}}@keyframes scanY{0%{transform:translateY(-100%)}100%{transform:translateY(100%)}}@keyframes scanY-rev{0%{transform:translateY(100%)}100%{transform:translateY(-100%)}}.vline{position:absolute;top:0;width:1px;bottom:0;pointer-events:none}.vline.l{left:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY-rev 3s linear infinite}.vline.r{right:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY 3s linear infinite}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.page-title{font-family:'Orbitron',sans-serif;font-size:22px;font-weight:700;text-align:center;color:var(--cyan);margin-bottom:32px;letter-spacing:1px;text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}.page-title span{color:var(--text);font-weight:500}.flow-chart{display:flex;align-items:stretch;gap:0;margin-bottom:28px}.flow-node{flex:1;background:rgba(13,31,56,.7);border:1px solid;border-radius:10px;padding:14px 8px;text-align:center;position:relative}.flow-node .icon{font-size:18px;margin-bottom:6px}.flow-node .name{font-size:12px;font-weight:600;margin-bottom:4px}.flow-node .desc{font-size:10px;color:var(--muted)}.flow-node.n1{border-color:rgba(14,165,233,.4);color:var(--cyan)}.flow-node.n2{border-color:rgba(99,102,241,.4);color:var(--purple)}.flow-node.n3{border-color:rgba(14,165,233,.4);color:var(--cyan)}.flow-node.n4{border-color:rgba(20,184,166,.4);color:var(--green)}.flow-connector{width:24px;display:flex;align-items:center;justify-content:center}.flow-connector::after{content:'';width:100%;height:1px;background:linear-gradient(90deg,var(--border),var(--cyan),var(--border))}.example-box{border:1px dashed rgba(14,165,233,.3);border-radius:12px;padding:16px 20px;margin-bottom:24px;background:rgba(14,165,233,.03)}.example-label{font-size:13px;font-weight:600;color:var(--cyan);margin-bottom:8px}.example-query{font-family:'JetBrains Mono',monospace;font-size:14px;color:var(--text)}.example-query code{color:var(--green);font-weight:600}.steps{display:flex;flex-direction:column;gap:12px;margin-bottom:24px}.step{background:rgba(13,31,56,.8);border:1px solid rgba(14,165,233,.12);border-radius:10px;padding:14px 18px}.step-num{font-family:'Orbitron',sans-serif;font-size:14px;font-weight:700;color:var(--green);margin-bottom:6px}.step-cmd{font-family:'JetBrains Mono',monospace;font-size:14px;color:var(--text);margin-bottom:6px}.step-cmd .cmd-name{color:var(--green)}.step-cmd .cmd-args{color:var(--muted)}.step-parse{font-size:12px;color:var(--muted);line-height:1.5}.step-parse::before{content:'→ 解析：';color:var(--cyan)}.confirm-btn{display:block;width:100%;max-width:420px;margin:0 auto 16px;text-align:center;padding:16px;background:linear-gradient(135deg,var(--cyan),#0284c7);border:none;border-radius:40px;color:#fff;font-size:15px;font-weight:600;cursor:pointer;box-shadow:0 0 30px rgba(14,165,233,.3)}.legend{display:flex;justify-content:center;gap:20px;font-size:11px;color:var(--muted);margin-bottom:16px;flex-wrap:wrap}.legend-item{display:flex;align-items:center;gap:4px}.legend-dot{width:8px;height:8px;border-radius:50%;display:inline-block}.legend-dot.required{background:var(--cyan)}.legend-dot.generated{background:var(--green)}.legend-dot.pending{background:rgba(255,255,255,.3)}.back-link{text-align:center;margin-top:12px}.back-link a{color:var(--cyan);font-size:11px;text-decoration:none}.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:20px}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><div class="page-title">ask --pipeline <span>多步骤编排引擎</span></div><div class="flow-chart"><div class="flow-node n1"><div class="icon">🧠</div><div class="name">AI 意图分解</div><div class="desc">LLM 分解多步骤</div></div><div class="flow-connector"></div><div class="flow-node n2"><div class="icon">📐</div><div class="name">命令匹配</div><div class="desc">意图→命令图</div></div><div class="flow-connector"></div><div class="flow-node n3"><div class="icon">🔗</div><div class="name">依赖解析</div><div class="desc">顺序/并行/参数</div></div><div class="flow-connector"></div><div class="flow-node n4"><div class="icon">✅</div><div class="name">预览</div><div class="desc">展示给用户</div></div></div><div class="example-box"><div class="example-label">📋 示例：<span class="example-query"><code>/spec-ask "本期迭代：从 PRD 导入到代码提交，跑完整开发流程"</code></span></div></div><div class="steps"><div class="step"><div class="step-num">1.</div><div class="step-cmd"><span class="cmd-name">speccore doc2spec</span> <span class="cmd-args">-f PRD.docx --iter {iteration}</span></div><div class="step-parse">导入 PRD 文档，AI 分析生成需求规格说明书</div></div><div class="step"><div class="step-num">2.</div><div class="step-cmd"><span class="cmd-name">speccore analyze</span> <span class="cmd-args">--iteration {iteration} --audit</span></div><div class="step-parse">AI 深度分析需求，生成审计报告和可行性评估</div></div><div class="step"><div class="step-num">3.</div><div class="step-cmd"><span class="cmd-name">speccore iteration taskify</span> <span class="cmd-args">-f REQUIREMENT.md</span></div><div class="step-parse">将需求拆分为独立开发任务，确定优先级和依赖关系</div></div><div class="step"><div class="step-num">4.</div><div class="step-cmd"><span class="cmd-name">speccore execute</span> <span class="cmd-args">--auto</span></div><div class="step-parse">按任务计划依次自动执行开发、测试和代码生成</div></div><div class="step"><div class="step-num">5.</div><div class="step-cmd"><span class="cmd-name">speccore verify</span> <span class="cmd-args">--ui</span></div><div class="step-parse">本地冒烟测试：自动登录 + 页面冒烟（默认 module 范围）</div></div><div class="step"><div class="step-num">6.</div><div class="step-cmd"><span class="cmd-name">speccore pr</span> <span class="cmd-args">--auto</span></div><div class="step-parse">代码提交后自动创建 Pull Request，完成交付</div></div></div><div class="confirm-btn">确认执行? (y/N) 或修改参数</div><div class="legend"><div class="legend-item"><span class="legend-dot required"></span> = 必选步骤</div><div class="legend-item"><span class="legend-dot generated"></span> = 已生成</div><div class="legend-item"><span class="legend-dot pending"></span> = 待执行</div><div class="legend-item">→ = 依赖传递</div></div><div class="back-link"><a href="speccore-welcome.html">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · v8.3.333 · 2026-08-31</div></div></body></html>
+<!DOCTYPE html><html lang="zh-CN" data-theme="ocean"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>SpecCore · ask --pipeline</title><style>@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@500;700;900&family=JetBrains+Mono:wght@400;600;700&display=swap');[data-theme="ocean"]{--cyan:#0ea5e9;--bg:#0b1929;--card:rgba(13,31,56,.95);--border:rgba(14,165,233,.15);--text:#bae6fd;--muted:#5b7fa5;--green:#14b8a6;--orange:#f97316;--purple:#6366f1}*{margin:0;padding:0;box-sizing:border-box}body{font-family:'JetBrains Mono',monospace;background:var(--bg);color:var(--text);min-height:100vh;display:flex;align-items:center;justify-content:center;padding:20px}.scanlines{position:fixed;inset:0;pointer-events:none;z-index:99;background:repeating-linear-gradient(0deg,transparent,transparent 2px,rgba(0,240,255,.01) 2px,rgba(0,240,255,.01) 4px)}.card{max-width:900px;width:100%;margin:0 auto;background:var(--card);border:1px solid var(--border);border-radius:16px;padding:32px;position:relative;overflow:hidden;z-index:1}.card::before{content:'';position:absolute;top:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX 3s linear infinite}.card::after{content:'';position:absolute;bottom:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX-rev 3s linear infinite}@keyframes scanX{0%{transform:translateX(-100%)}100%{transform:translateX(100%)}}@keyframes scanX-rev{0%{transform:translateX(100%)}100%{transform:translateX(-100%)}}@keyframes scanY{0%{transform:translateY(-100%)}100%{transform:translateY(100%)}}@keyframes scanY-rev{0%{transform:translateY(100%)}100%{transform:translateY(-100%)}}.vline{position:absolute;top:0;width:1px;bottom:0;pointer-events:none}.vline.l{left:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY-rev 3s linear infinite}.vline.r{right:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY 3s linear infinite}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.page-title{font-family:'Orbitron',sans-serif;font-size:22px;font-weight:700;text-align:center;color:var(--cyan);margin-bottom:32px;letter-spacing:1px;text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}.page-title span{color:var(--text);font-weight:500}.flow-chart{display:flex;align-items:stretch;gap:0;margin-bottom:28px}.flow-node{flex:1;background:rgba(13,31,56,.7);border:1px solid;border-radius:10px;padding:14px 8px;text-align:center;position:relative}.flow-node .icon{font-size:18px;margin-bottom:6px}.flow-node .name{font-size:12px;font-weight:600;margin-bottom:4px}.flow-node .desc{font-size:10px;color:var(--muted)}.flow-node.n1{border-color:rgba(14,165,233,.4);color:var(--cyan)}.flow-node.n2{border-color:rgba(99,102,241,.4);color:var(--purple)}.flow-node.n3{border-color:rgba(14,165,233,.4);color:var(--cyan)}.flow-node.n4{border-color:rgba(20,184,166,.4);color:var(--green)}.flow-connector{width:24px;display:flex;align-items:center;justify-content:center}.flow-connector::after{content:'';width:100%;height:1px;background:linear-gradient(90deg,var(--border),var(--cyan),var(--border))}.example-box{border:1px dashed rgba(14,165,233,.3);border-radius:12px;padding:16px 20px;margin-bottom:24px;background:rgba(14,165,233,.03)}.example-label{font-size:13px;font-weight:600;color:var(--cyan);margin-bottom:8px}.example-query{font-family:'JetBrains Mono',monospace;font-size:14px;color:var(--text)}.example-query code{color:var(--green);font-weight:600}.steps{display:flex;flex-direction:column;gap:12px;margin-bottom:24px}.step{background:rgba(13,31,56,.8);border:1px solid rgba(14,165,233,.12);border-radius:10px;padding:14px 18px}.step-num{font-family:'Orbitron',sans-serif;font-size:14px;font-weight:700;color:var(--green);margin-bottom:6px}.step-cmd{font-family:'JetBrains Mono',monospace;font-size:14px;color:var(--text);margin-bottom:6px}.step-cmd .cmd-name{color:var(--green)}.step-cmd .cmd-args{color:var(--muted)}.step-parse{font-size:12px;color:var(--muted);line-height:1.5}.step-parse::before{content:'→ 解析：';color:var(--cyan)}.confirm-btn{display:block;width:100%;max-width:420px;margin:0 auto 16px;text-align:center;padding:16px;background:linear-gradient(135deg,var(--cyan),#0284c7);border:none;border-radius:40px;color:#fff;font-size:15px;font-weight:600;cursor:pointer;box-shadow:0 0 30px rgba(14,165,233,.3)}.legend{display:flex;justify-content:center;gap:20px;font-size:11px;color:var(--muted);margin-bottom:16px;flex-wrap:wrap}.legend-item{display:flex;align-items:center;gap:4px}.legend-dot{width:8px;height:8px;border-radius:50%;display:inline-block}.legend-dot.required{background:var(--cyan)}.legend-dot.generated{background:var(--green)}.legend-dot.pending{background:rgba(255,255,255,.3)}.back-link{text-align:center;margin-top:12px}.back-link a{color:var(--cyan);font-size:11px;text-decoration:none}.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:20px}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><div class="page-title">ask --pipeline <span>多步骤编排引擎</span></div><div class="flow-chart"><div class="flow-node n1"><div class="icon">🧠</div><div class="name">AI 意图分解</div><div class="desc">LLM 分解多步骤</div></div><div class="flow-connector"></div><div class="flow-node n2"><div class="icon">📐</div><div class="name">命令匹配</div><div class="desc">意图→命令图</div></div><div class="flow-connector"></div><div class="flow-node n3"><div class="icon">🔗</div><div class="name">依赖解析</div><div class="desc">顺序/并行/参数</div></div><div class="flow-connector"></div><div class="flow-node n4"><div class="icon">✅</div><div class="name">预览</div><div class="desc">展示给用户</div></div></div><div class="example-box"><div class="example-label">📋 示例：<span class="example-query"><code>/spec-ask "本期迭代：从 PRD 导入到代码提交，跑完整开发流程"</code></span></div></div><div class="steps"><div class="step"><div class="step-num">1.</div><div class="step-cmd"><span class="cmd-name">speccore doc2spec</span> <span class="cmd-args">-f PRD.docx --iter {iteration}</span></div><div class="step-parse">导入 PRD 文档，AI 分析生成需求规格说明书</div></div><div class="step"><div class="step-num">2.</div><div class="step-cmd"><span class="cmd-name">speccore analyze</span> <span class="cmd-args">--iteration {iteration} --audit</span></div><div class="step-parse">AI 深度分析需求，生成审计报告和可行性评估</div></div><div class="step"><div class="step-num">3.</div><div class="step-cmd"><span class="cmd-name">speccore iteration taskify</span> <span class="cmd-args">-f REQUIREMENT.md</span></div><div class="step-parse">将需求拆分为独立开发任务，确定优先级和依赖关系</div></div><div class="step"><div class="step-num">4.</div><div class="step-cmd"><span class="cmd-name">speccore execute</span> <span class="cmd-args">--auto</span></div><div class="step-parse">按任务计划依次自动执行开发、测试和代码生成</div></div><div class="step"><div class="step-num">5.</div><div class="step-cmd"><span class="cmd-name">speccore verify</span> <span class="cmd-args">--ui</span></div><div class="step-parse">本地冒烟测试：自动登录 + 页面冒烟（默认 module 范围）</div></div><div class="step"><div class="step-num">6.</div><div class="step-cmd"><span class="cmd-name">speccore pr</span> <span class="cmd-args">--auto</span></div><div class="step-parse">代码提交后自动创建 Pull Request，完成交付</div></div></div><div class="confirm-btn">确认执行? (y/N) 或修改参数</div><div class="legend"><div class="legend-item"><span class="legend-dot required"></span> = 必选步骤</div><div class="legend-item"><span class="legend-dot generated"></span> = 已生成</div><div class="legend-item"><span class="legend-dot pending"></span> = 待执行</div><div class="legend-item">→ = 依赖传递</div></div><div class="back-link"><a href="speccore-ask-onboarding.html">← 返回 ask 引导页</a></div><div class="footer">由 SpecCore 驱动 · v8.3.341 · 2026-08-31</div></div></body></html>

package/templates/html/speccore-ask-result.html

@@ -7,4 +7,4 @@
 .match-result{padding:10px 0}.match-summary{font-weight:600;font-size:14px;margin-bottom:12px}.match-detail{color:var(--muted);font-size:12px;line-height:1.6}
 /* Pipeline */
 .pipeline-title{font-weight:600;margin-bottom:16px}.pipeline-steps{display:flex;flex-direction:column;gap:10px}.pipe-step{display:flex;gap:14px;padding:12px 14px;background:rgba(99,102,241,.04);border-left:2px solid var(--purple);border-radius:0 8px 8px 0}.pipe-step .pipe-num{font-family:Orbitron;font-size:20px;font-weight:900;color:var(--purple);min-width:36px}.pipe-step .pipe-cmd{font-weight:600;color:var(--green)}.pipe-step .pipe-args{color:var(--muted);font-size:11px}.pipe-step .pipe-desc{color:var(--muted);font-size:10px;margin-top:4px}.pipe-step .pipe-dep{font-size:9px;color:var(--orange);margin-top:4px}.confirm-bar{text-align:center;padding:14px;margin-top:16px;background:rgba(99,102,241,.08);border:1px dashed rgba(99,102,241,.2);border-radius:8px;color:var(--purple);font-size:12px}
-.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"dashboard"</div><div class="badge">🎯 意图匹配</div><div class="match-result"><div class="match-summary">✅ 推荐: dashboard</div><div class="match-detail">🎯 推荐命令: <code>speccore dashboard<br>项目仪表盘：期次状态/进度/健康度，--scope</code> global 全量视图<br><br>用法: <code>speccore dashboard</code> [--scope global|iteration] [--export html] [--health] [--lifecycle]<br><br>示例:<br>  $ <code>speccore dashboard<br></code>  $ <code>speccore dashboard</code> --scope global --export html</div></div><div class="footer">由 SpecCore 驱动 v8.3.333 · 2026-08-31</div></div></body></html>
+.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 25% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes titleGlow{0%,100%{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15)}50%{text-shadow:0 0 30px rgba(14,165,233,.7),0 0 80px rgba(14,165,233,.3)}}h1,h2{text-shadow:0 0 20px rgba(14,165,233,.4),0 0 60px rgba(14,165,233,.15);animation:titleGlow 3s ease-in-out infinite}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE ASK</h1><div class="query">"dashboard"</div><div class="badge">🎯 意图匹配</div><div class="match-result"><div class="match-summary">✅ 推荐: dashboard</div><div class="match-detail">🎯 推荐命令: <code>speccore dashboard<br>项目仪表盘：期次状态/进度/健康度，--scope</code> global 全量视图<br><br>用法: <code>speccore dashboard</code> [--scope global|iteration] [--export html] [--health] [--lifecycle]<br><br>示例:<br>  $ <code>speccore dashboard<br></code>  $ <code>speccore dashboard</code> --scope global --export html</div></div><div class="footer">由 SpecCore 驱动 v8.3.341 · 2026-08-31</div></div></body></html>

package/templates/html/speccore-help.html

@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="zh-CN" data-theme="ocean"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>SpecCore Help</title><style>@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@500;700;900&family=JetBrains+Mono:wght@400;600;700&display=swap');[data-theme="ocean"]{--cyan:#0ea5e9;--bg:#0b1929;--card:rgba(13,31,56,.95);--border:rgba(14,165,233,.15);--text:#bae6fd;--muted:#5b7fa5;--green:#14b8a6;--orange:#f97316;--purple:#6366f1}*{margin:0;padding:0;box-sizing:border-box}body{font-family:'JetBrains Mono',monospace;background:var(--bg);color:var(--text);min-height:100vh;padding:40px 20px}.scanlines{position:fixed;inset:0;pointer-events:none;z-index:99;background:repeating-linear-gradient(0deg,transparent,transparent 2px,rgba(0,240,255,.01) 2px,rgba(0,240,255,.01) 4px)}.card{max-width:960px;margin:0 auto;background:var(--card);border:1px solid var(--border);border-radius:16px;padding:36px;position:relative;overflow:hidden}.card::before{content:'';position:absolute;top:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX 3s linear infinite}.card::after{content:'';position:absolute;bottom:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX-rev 3s linear infinite}@keyframes scanX{0%{transform:translateX(-100%)}100%{transform:translateX(100%)}}@keyframes scanX-rev{0%{transform:translateX(100%)}100%{transform:translateX(-100%)}}@keyframes scanY{0%{transform:translateY(-100%)}100%{transform:translateY(100%)}}@keyframes scanY-rev{0%{transform:translateY(100%)}100%{transform:translateY(-100%)}}.vline{position:absolute;top:0;width:1px;bottom:0;pointer-events:none}.vline.l{left:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY-rev 3s linear infinite}.vline.r{right:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY 3s linear infinite}h1{font-family:'Orbitron',sans-serif;font-size:24px;font-weight:900;background:linear-gradient(135deg,var(--cyan),var(--purple));-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;letter-spacing:2px;margin-bottom:4px;animation:titleGlow 3s ease-in-out infinite}.sub{color:var(--muted);font-size:11px;margin-bottom:24px}.intro-card{padding:20px;margin-bottom:20px;background:linear-gradient(135deg,rgba(14,165,233,.08),rgba(99,102,241,.08));border:1px solid rgba(14,165,233,.2);border-radius:12px}.intro-title{font-size:16px;font-weight:700;color:var(--cyan);margin-bottom:12px}.intro-text{font-size:13px;line-height:1.6;color:var(--text);margin-bottom:16px}.highlight-box{display:flex;gap:16px;padding:16px;background:rgba(20,184,166,.08);border:1px solid rgba(20,184,166,.2);border-radius:10px}.highlight-icon{font-size:32px}.highlight-content{flex:1}.highlight-title{font-size:12px;font-weight:700;color:var(--green);margin-bottom:8px;text-transform:uppercase;letter-spacing:1px}.highlight-list{list-style:none;padding:0;margin:0}.highlight-list li{font-size:12px;color:var(--text);padding:4px 0;line-height:1.5}.highlight-list strong{color:var(--cyan)}.quick-start{padding:20px;margin:20px 0;background:rgba(249,115,22,.05);border:1px solid rgba(249,115,22,.15);border-radius:12px}.section-header{display:flex;align-items:center;gap:8px;margin-bottom:16px}.header-icon{font-size:20px}.header-title{font-size:14px;font-weight:700;color:var(--orange);text-transform:uppercase;letter-spacing:1px}.step-row{display:flex;align-items:center;gap:12px;flex-wrap:wrap;justify-content:center}.step-item{display:flex;gap:12px;padding:12px 16px;background:rgba(255,255,255,.03);border:1px solid rgba(255,255,255,.08);border-radius:10px;min-width:180px}.step-num{width:32px;height:32px;border-radius:50%;background:linear-gradient(135deg,var(--orange),#ea580c);display:flex;align-items:center;justify-content:center;font-weight:700;font-size:14px;color:#fff;flex-shrink:0}.step-text{font-size:12px;line-height:1.5}.step-text code{display:inline-block;margin-top:4px;padding:2px 8px;background:rgba(249,115,22,.1);border-radius:4px;color:var(--orange);font-size:11px}.step-arrow{color:var(--muted);font-size:20px;font-weight:700}.cat{margin:16px 0;padding:16px;background:rgba(255,255,255,.02);border:1px solid rgba(255,255,255,.04);border-radius:12px;transition:all .3s}.cat:hover{border-color:rgba(14,165,233,.3);background:rgba(14,165,233,.03)}.cat-header{display:flex;align-items:center;gap:12px;margin-bottom:12px}.cat-icon{font-size:24px}.cat-info{flex:1}.cat-title{font-size:13px;font-weight:700;color:var(--cyan);margin-bottom:2px}.cat-desc{font-size:11px;color:var(--muted)}.cat-cmds{display:flex;flex-wrap:wrap;gap:8px}.cmd-pill{padding:4px 12px;border-radius:6px;font-size:11px;background:rgba(14,165,233,.08);color:var(--cyan);border:1px solid rgba(14,165,233,.15);transition:all .2s;cursor:pointer}.core-commands{padding:16px;border:1px solid var(--border);border-radius:12px;background:rgba(14,165,233,.04)}.core-commands .cmd-pill{font-size:12px;padding:6px 14px;background:rgba(20,184,166,.12);color:var(--green);border-color:rgba(20,184,166,.3)}.core-hint{margin-top:12px;font-size:12px;color:var(--muted)}.cmd-pill:hover{background:rgba(14,165,233,.15);border-color:rgba(14,165,233,.3);transform:translateY(-1px)}.cmd-detail{padding:8px 0}.cmd-desc{font-size:14px;margin-bottom:16px;color:var(--text);line-height:1.6}.param-list{margin:16px 0}.param{display:flex;gap:16px;padding:8px 0;border-bottom:1px solid rgba(255,255,255,.03)}.param-flag{color:var(--green);font-size:12px;min-width:180px;font-weight:600}.param-meaning{color:var(--muted);font-size:12px;line-height:1.5}.example-list{margin:16px 0}.section-label{font-size:10px;font-weight:700;color:var(--muted);text-transform:uppercase;letter-spacing:1px;margin-bottom:8px}.tips-section{padding:20px;margin:20px 0;background:rgba(99,102,241,.05);border:1px solid rgba(99,102,241,.15);border-radius:12px}.tip-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:12px;margin-top:16px}.tip-card{padding:14px;background:rgba(255,255,255,.03);border:1px solid rgba(255,255,255,.06);border-radius:10px;display:flex;gap:12px;transition:all .3s}.tip-card:hover{border-color:rgba(99,102,241,.3);background:rgba(99,102,241,.05);transform:translateY(-2px)}.tip-icon{font-size:24px;flex-shrink:0}.tip-content{flex:1}.tip-title{font-size:12px;font-weight:700;color:var(--purple);margin-bottom:4px}.tip-text{font-size:11px;color:var(--muted);line-height:1.5}.tip-text code{display:inline-block;margin-top:4px;padding:2px 6px;background:rgba(99,102,241,.1);border-radius:4px;color:var(--purple);font-size:10px}code{display:block;background:rgba(14,165,233,.08);padding:6px 12px;border-radius:6px;color:var(--cyan);font-size:12px;margin:6px 0;transition:all .2s}code:hover{background:rgba(14,165,233,.12)}.params-section{padding:20px;margin:20px 0;background:rgba(14,165,233,.05);border:1px solid rgba(14,165,233,.15);border-radius:12px}.param-table{margin-top:16px}.param-row{display:flex;gap:12px;padding:10px 0;border-bottom:1px solid rgba(255,255,255,.03);align-items:center}.header-row{border-bottom:2px solid rgba(14,165,233,.3);font-weight:700}.param-col{flex:1;font-size:12px;line-height:1.5}.param-col.flag{min-width:120px;color:var(--green);font-weight:600}.param-col.meaning{flex:2;color:var(--text)}.param-col.example{flex:1.5;color:var(--muted)}.param-col code{display:inline-block;padding:2px 8px;background:rgba(14,165,233,.08);border-radius:4px;font-size:11px;margin:0}.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 30% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}@keyframes titleGlow{0%,100%{filter:drop-shadow(0 0 20px rgba(14,165,233,.4)) drop-shadow(0 0 60px rgba(14,165,233,.15))}50%{filter:drop-shadow(0 0 30px rgba(14,165,233,.7)) drop-shadow(0 0 80px rgba(14,165,233,.3))}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE HELP</h1><div class="sub">SpecCore 命令参考 · v8.3.333</div>
+<!DOCTYPE html><html lang="zh-CN" data-theme="ocean"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>SpecCore Help</title><style>@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@500;700;900&family=JetBrains+Mono:wght@400;600;700&display=swap');[data-theme="ocean"]{--cyan:#0ea5e9;--bg:#0b1929;--card:rgba(13,31,56,.95);--border:rgba(14,165,233,.15);--text:#bae6fd;--muted:#5b7fa5;--green:#14b8a6;--orange:#f97316;--purple:#6366f1}*{margin:0;padding:0;box-sizing:border-box}body{font-family:'JetBrains Mono',monospace;background:var(--bg);color:var(--text);min-height:100vh;padding:40px 20px}.scanlines{position:fixed;inset:0;pointer-events:none;z-index:99;background:repeating-linear-gradient(0deg,transparent,transparent 2px,rgba(0,240,255,.01) 2px,rgba(0,240,255,.01) 4px)}.card{max-width:960px;margin:0 auto;background:var(--card);border:1px solid var(--border);border-radius:16px;padding:36px;position:relative;overflow:hidden}.card::before{content:'';position:absolute;top:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX 3s linear infinite}.card::after{content:'';position:absolute;bottom:0;left:0;right:0;height:1px;background:linear-gradient(90deg,transparent,var(--cyan),transparent);animation:scanX-rev 3s linear infinite}@keyframes scanX{0%{transform:translateX(-100%)}100%{transform:translateX(100%)}}@keyframes scanX-rev{0%{transform:translateX(100%)}100%{transform:translateX(-100%)}}@keyframes scanY{0%{transform:translateY(-100%)}100%{transform:translateY(100%)}}@keyframes scanY-rev{0%{transform:translateY(100%)}100%{transform:translateY(-100%)}}.vline{position:absolute;top:0;width:1px;bottom:0;pointer-events:none}.vline.l{left:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY-rev 3s linear infinite}.vline.r{right:0;background:linear-gradient(180deg,transparent,var(--cyan),transparent);animation:scanY 3s linear infinite}h1{font-family:'Orbitron',sans-serif;font-size:24px;font-weight:900;background:linear-gradient(135deg,var(--cyan),var(--purple));-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;letter-spacing:2px;margin-bottom:4px;animation:titleGlow 3s ease-in-out infinite}.sub{color:var(--muted);font-size:11px;margin-bottom:24px}.intro-card{padding:20px;margin-bottom:20px;background:linear-gradient(135deg,rgba(14,165,233,.08),rgba(99,102,241,.08));border:1px solid rgba(14,165,233,.2);border-radius:12px}.intro-title{font-size:16px;font-weight:700;color:var(--cyan);margin-bottom:12px}.intro-text{font-size:13px;line-height:1.6;color:var(--text);margin-bottom:16px}.highlight-box{display:flex;gap:16px;padding:16px;background:rgba(20,184,166,.08);border:1px solid rgba(20,184,166,.2);border-radius:10px}.highlight-icon{font-size:32px}.highlight-content{flex:1}.highlight-title{font-size:12px;font-weight:700;color:var(--green);margin-bottom:8px;text-transform:uppercase;letter-spacing:1px}.highlight-list{list-style:none;padding:0;margin:0}.highlight-list li{font-size:12px;color:var(--text);padding:4px 0;line-height:1.5}.highlight-list strong{color:var(--cyan)}.quick-start{padding:20px;margin:20px 0;background:rgba(249,115,22,.05);border:1px solid rgba(249,115,22,.15);border-radius:12px}.section-header{display:flex;align-items:center;gap:8px;margin-bottom:16px}.header-icon{font-size:20px}.header-title{font-size:14px;font-weight:700;color:var(--orange);text-transform:uppercase;letter-spacing:1px}.step-row{display:flex;align-items:center;gap:12px;flex-wrap:wrap;justify-content:center}.step-item{display:flex;gap:12px;padding:12px 16px;background:rgba(255,255,255,.03);border:1px solid rgba(255,255,255,.08);border-radius:10px;min-width:180px}.step-num{width:32px;height:32px;border-radius:50%;background:linear-gradient(135deg,var(--orange),#ea580c);display:flex;align-items:center;justify-content:center;font-weight:700;font-size:14px;color:#fff;flex-shrink:0}.step-text{font-size:12px;line-height:1.5}.step-text code{display:inline-block;margin-top:4px;padding:2px 8px;background:rgba(249,115,22,.1);border-radius:4px;color:var(--orange);font-size:11px}.step-arrow{color:var(--muted);font-size:20px;font-weight:700}.cat{margin:16px 0;padding:16px;background:rgba(255,255,255,.02);border:1px solid rgba(255,255,255,.04);border-radius:12px;transition:all .3s}.cat:hover{border-color:rgba(14,165,233,.3);background:rgba(14,165,233,.03)}.cat-header{display:flex;align-items:center;gap:12px;margin-bottom:12px}.cat-icon{font-size:24px}.cat-info{flex:1}.cat-title{font-size:13px;font-weight:700;color:var(--cyan);margin-bottom:2px}.cat-desc{font-size:11px;color:var(--muted)}.cat-cmds{display:flex;flex-wrap:wrap;gap:8px}.cmd-pill{padding:4px 12px;border-radius:6px;font-size:11px;background:rgba(14,165,233,.08);color:var(--cyan);border:1px solid rgba(14,165,233,.15);transition:all .2s;cursor:pointer}.core-commands{padding:16px;border:1px solid var(--border);border-radius:12px;background:rgba(14,165,233,.04)}.core-commands .cmd-pill{font-size:12px;padding:6px 14px;background:rgba(20,184,166,.12);color:var(--green);border-color:rgba(20,184,166,.3)}.core-hint{margin-top:12px;font-size:12px;color:var(--muted)}.cmd-pill:hover{background:rgba(14,165,233,.15);border-color:rgba(14,165,233,.3);transform:translateY(-1px)}.cmd-detail{padding:8px 0}.cmd-desc{font-size:14px;margin-bottom:16px;color:var(--text);line-height:1.6}.param-list{margin:16px 0}.param{display:flex;gap:16px;padding:8px 0;border-bottom:1px solid rgba(255,255,255,.03)}.param-flag{color:var(--green);font-size:12px;min-width:180px;font-weight:600}.param-meaning{color:var(--muted);font-size:12px;line-height:1.5}.example-list{margin:16px 0}.section-label{font-size:10px;font-weight:700;color:var(--muted);text-transform:uppercase;letter-spacing:1px;margin-bottom:8px}.tips-section{padding:20px;margin:20px 0;background:rgba(99,102,241,.05);border:1px solid rgba(99,102,241,.15);border-radius:12px}.tip-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:12px;margin-top:16px}.tip-card{padding:14px;background:rgba(255,255,255,.03);border:1px solid rgba(255,255,255,.06);border-radius:10px;display:flex;gap:12px;transition:all .3s}.tip-card:hover{border-color:rgba(99,102,241,.3);background:rgba(99,102,241,.05);transform:translateY(-2px)}.tip-icon{font-size:24px;flex-shrink:0}.tip-content{flex:1}.tip-title{font-size:12px;font-weight:700;color:var(--purple);margin-bottom:4px}.tip-text{font-size:11px;color:var(--muted);line-height:1.5}.tip-text code{display:inline-block;margin-top:4px;padding:2px 6px;background:rgba(99,102,241,.1);border-radius:4px;color:var(--purple);font-size:10px}code{display:block;background:rgba(14,165,233,.08);padding:6px 12px;border-radius:6px;color:var(--cyan);font-size:12px;margin:6px 0;transition:all .2s}code:hover{background:rgba(14,165,233,.12)}.params-section{padding:20px;margin:20px 0;background:rgba(14,165,233,.05);border:1px solid rgba(14,165,233,.15);border-radius:12px}.param-table{margin-top:16px}.param-row{display:flex;gap:12px;padding:10px 0;border-bottom:1px solid rgba(255,255,255,.03);align-items:center}.header-row{border-bottom:2px solid rgba(14,165,233,.3);font-weight:700}.param-col{flex:1;font-size:12px;line-height:1.5}.param-col.flag{min-width:120px;color:var(--green);font-weight:600}.param-col.meaning{flex:2;color:var(--text)}.param-col.example{flex:1.5;color:var(--muted)}.param-col code{display:inline-block;padding:2px 8px;background:rgba(14,165,233,.08);border-radius:4px;font-size:11px;margin:0}.footer{text-align:center;color:var(--muted);font-size:10px;margin-top:24px;padding-top:16px;border-top:1px solid rgba(255,255,255,.04)}.card-bg{position:absolute;inset:0;pointer-events:none;z-index:0;background:radial-gradient(ellipse at 30% 10%,rgba(14,165,233,.25) 0%,transparent 70%);animation:cardGlow 3s ease-in-out infinite;transform-origin:top center}@keyframes cardGlow{0%,100%{opacity:.5;transform:scale(1)}50%{opacity:1;transform:scale(1.6)}}@keyframes titleGlow{0%,100%{filter:drop-shadow(0 0 20px rgba(14,165,233,.4)) drop-shadow(0 0 60px rgba(14,165,233,.15))}50%{filter:drop-shadow(0 0 30px rgba(14,165,233,.7)) drop-shadow(0 0 80px rgba(14,165,233,.3))}</style></head><body><div class="scanlines"></div><div class="card"><div class="card-bg"></div><div class="vline l"></div><div class="vline r"></div><h1>SPECCORE HELP</h1><div class="sub">SpecCore 命令参考 · v8.3.341</div>
       <div class="intro-card">
         <div class="intro-title">🎯 SpecCore — SDD 开发方法论 CLI 工具</div>
         <div class="intro-text">SpecCore 采用 <strong>Specification-Driven Development（规格驱动开发）</strong>方法论，通过标准化流程和 AI 辅助，实现从需求到交付的自动化流水线。</div>
@@ -238,4 +238,4 @@
           </div>
         </div>
       </div>
-    <div class="footer">由 SpecCore 驱动 v8.3.333 · 2026-09-29</div></div></body></html>
+    <div class="footer">由 SpecCore 驱动 v8.3.341 · 2026-09-29</div></div></body></html>

package/templates/speccore-yml-example.yml

@@ -10,100 +10,195 @@
 #   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
 
-# ── 日志（文件日志开关，输出到 .speccore/local/logs/）──
+# ─────────────────────────────────────────────────────────────
+# 本地文件日志（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       # true → execute 前检查 TEST.md，缺失则阻断
-  enforce_review: true        # true → 执行完自动进入 review 流程
-  require_pr: true            # true → 禁止直接 push 保护分支，走 speccore pr
-  # 阻塞级别：standard（编译+单测+契约都阻断，默认）/ compile（仅编译阻断）
+  # 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
-  # v8.3.95+: UI 验证默认行为（speccore verify --ui）
+  # ── UI 验证（v8.3.47+）──
   verify_ui:
-    enabled: false            # 演示默认关闭，按需 true
-    smoke_test: true          # 冒烟测试
-    visual_check: true        # 视觉检查
-    headed: false             # 有头浏览器（调试用）
-    # threshold: strict 任何微小差异 / normal 明显差异（默认）/ loose 仅严重问题
+    # 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: [desktop]        # desktop / mobile / iPhone13 / Pixel5 ...
-    browsers: [chromium]
-    timeout: 30000            # 单场景超时（毫秒）
-    # v8.3.50+: 视觉模型（看图判断走外部模型）
+    # devices: 测试设备列表
+    devices:
+      - desktop
+    # browsers: 测试浏览器列表
+    browsers:
+      - chromium
+    # timeout: 单场景超时（毫秒）
+    timeout: 30000
+    # visual_model: 视觉模型配置（v8.3.50+，看图判断走外部模型）
     visual_model:
-      provider: qwen-vl       # qwen-vl / openai / anthropic / local
+      # provider: 视觉模型提供方 qwen-vl(默认) / openai / anthropic / local
+      provider: qwen-vl
+      # model: 模型名称（可选，留空用 provider 默认模型）
       model: qwen-vl-max
+      # apiKey: API Key（可选，支持 ${ENV_VAR} 环境变量引用）
+      # endpoint: 自定义端点（可选）
+      # timeout: 请求超时（毫秒，可选）
 
-# ── 契约裁决：full 全流程 / l1-only / report-only ──
+# ─────────────────────────────────────────────────────────────
+# 契约冲突裁决（Arbitration）
+# ─────────────────────────────────────────────────────────────
 arbitration:
+  # enabled: 是否启用三级冲突裁决机制
+  #   true → analyze/taskify/execute 各阶段自动检测并裁决契约冲突
   enabled: true
+  # mode: 裁决模式
+  #   full        → 完整三级裁决（Spec 层 → 代码层 → 运行时层）
+  #   l1-only     → 仅 Spec 层冲突检测
+  #   report-only → 只报告冲突不裁决
   mode: full
 
-# ── 运行时行为 ──
+# ─────────────────────────────────────────────────────────────
+# 通用设置（Settings）
+# ─────────────────────────────────────────────────────────────
 settings:
-  # 指派策略：strict 阻断不一致 / loose 自动填+警告 / off 关闭
+  # ── 指派策略（Assignee）──
   assignee:
+    # enabled: 是否启用自动指派（taskify 时按 STAFFING.md 分配负责人）
     enabled: true
+    # mode: 指派严格度
+    #   strict → 每个子任务必须指定 owner，缺失则阻断
+    #   loose  → 仅任务级指定 owner，子任务可共享（默认）
+    #   off    → 关闭指派
     mode: loose
-  # 双向追溯 + @spec 注释
+  # ── 追踪（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
-  # 模式沉淀：off / smart / aggressive
+  # ── 模式沉淀（Patterns）──
   patterns:
+    # auto_save: 是否自动将分析中发现的模式保存到 .speccore/PATTERNS/
+    #   smart  → 仅置信度高时自动保存（默认）
+    #   aggressive → 全部自动保存
+    #   off    → 不自动保存，仅手动
     auto_save: smart
-  # 审查时检查执行人签名
+  # ── 审查（Review）──
   review:
+    # check_assignee: 审查时是否检查指派人与执行人一致（不一致则警告）
     check_assignee: false
-  # v8.3.94+: 视觉模型（specs 文档图片理解，默认关闭）
+  # ── 视觉模型（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
-  # 分析时附带源码（from-source 场景）
+  # ── 关联代码（with_code）──
+  # with_code: 分析时是否默认关联源码（from-source 场景）
   with_code: false
-  # 非必要流水线步骤三态开关：auto（智能，默认）/ on 强制 / off 跳过
+  # ── 非必要流水线步骤开关（三态）──
+  #   auto = 按内置逻辑智能判定（默认） | on = 强制执行 | off = 跳过
   optional_steps:
-    clarify: auto             # 文档专业就跳过澄清
+    # 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
-  # 命名流水线（run --preset <name>）
+  # ── 命名流水线（Pipelines）──
   pipelines:
-    default: develop          # full/import/spec/analyze/develop/deliver/deploy/docs
-    custom: {}                # 自定义: { my-flow: analyze,validate,taskify,plan,execute }
-  # 质量门禁模式
+    # 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
-  # v8.3.193+: 统一 LLM provider 池（host=宿主AI / llm=自配 / auto=宿主优先）
-  # 演示条目，默认 providers: []——自配时按此结构填写
+  # ── 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
@@ -115,35 +210,54 @@ settings:
         model: gpt-4o
         apiKey: "${OPENAI_API_KEY}"
         priority: 2
-    defaults: {}              # 按阶段指定 provider: { analyze: gpt4o }
+    # defaults: 各功能的默认 provider name（示例: { analyze: gpt4o }）
+    defaults: {}
+    # fallback: 兜底 provider name（可选，主 provider 失败时启用）
     fallback: local
-  # v8.3.301+: 子 Agent SDK 派单开关
-  #   auto = Qoder 宿主 + token 可用（PAT 或 CLI 登录态）时启用（默认）
-  #   on   = 强制尝试 SDK 派单（失败回退标记模式）
-  #   off  = 禁用 SDK 派单，永远走标记模式
+  # ── 子 Agent SDK 派单（v8.3.301+，第七层「窗口物理隔离」增强通道）──
   agent_dispatch:
+    # mode: 子 Agent SDK 派单开关
+    #   auto → Qoder 宿主 + token 可用（PAT 或 CLI 登录态）时启用（默认）
+    #   on   → 强制尝试 SDK 派单（失败回退标记模式）
+    #   off  → 禁用 SDK 派单，永远走标记模式
     mode: auto
-  # v8.3.217+: 冒烟三时机开关 + 范围（run --smoke / --skip-smoke / --scope 单次覆盖）
+  # ── 冒烟测试统一配置（三时机开关 + 范围 + 按环境差异化，v8.3.217+）──
   smoke:
     points:
-      local: auto             # 开发完本地冒烟
-      pre-deploy: auto        # 部署前门禁
-      post-deploy: auto       # 部署后确认环境活着
-    scope: module             # full 全量 / module 当前功能模块
-    scope_by_env: {}          # 按环境覆盖: { production: full }
+      local: auto        # ①本地冒烟（开发完成后、提交前）
+      pre-deploy: auto  # ②部署前冒烟（critical 阻断）
+      post-deploy: auto # ③环境冒烟（只报告）
+    scope: module    # full=全量 / module=当前功能模块（默认）
+    # scope_by_env 示例: dev: module / production: full
+    scope_by_env: {}
 
-# ── Ask 引擎 ──
+# ─────────────────────────────────────────────────────────────
+# Ask 引擎路由配置（控制 speccore ask 的行为）
+# ─────────────────────────────────────────────────────────────
 ask:
+  # ── 路由策略（Routing）──
   routing:
-    mode: hybrid              # hybrid / cli-only / host-ai-only
+    # 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 池（演示条目，默认 []）
+  # ── 自配 LLM 池（演示条目，默认 []）──
+  # 结构与 settings.ai.providers 一致：name/type/endpoint/model/priority
   llm_providers:
     - name: ollama-local
       enabled: false
@@ -158,10 +272,16 @@ ask:
       model: gpt-4o-mini
       priority: 2
 
-# ── 工具路径（doc2spec 转换依赖，留空自动探测）──
+# ─────────────────────────────────────────────────────────────
+# 工具路径（doc2spec 转换依赖，留空自动探测）
+# ─────────────────────────────────────────────────────────────
 tools:
+  # pandoc: pandoc 可执行文件路径（Word/PDF 转换用，留空自动探测 PATH）
   pandoc: ''
+  # libreoffice: LibreOffice 可执行文件路径（PDF 转换用，留空自动探测）
   libreoffice: ''
 
-# ── 配置变更历史（speccore config --upgrade 自动维护，勿手动编辑）──
+# ─────────────────────────────────────────────────────────────
+# 配置变更历史（speccore config --upgrade 自动维护，勿手动编辑）
+# ─────────────────────────────────────────────────────────────
 config_history: []