sillyspec 3.7.27 → 3.7.28

package/.claude/skills/sillyspec-doctor/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sillyspec:doctor
+description: 项目自检 — 检查 CLI、配置、构建环境和外部依赖
+---
+
+## 前置检查
+
+**在执行任何检查之前，先确认 SillySpec CLI 是否可用：**
+
+1. 运行 `sillyspec --version`
+2. 如果失败，运行 `npx sillyspec --version`
+3. 如果都失败：
+   - 输出：❌ SillySpec CLI 未安装，后续检查无法执行
+   - 给出安装命令：`npm install -g sillyspec`（生产环境）或 `npx sillyspec`（临时使用）
+   - 停止，不要继续后续步骤
+
+## 执行
+
+CLI 可用后，运行 `sillyspec run doctor`，按提示逐步执行。
+每步完成后运行 `sillyspec run doctor --done --output "摘要"`。
+
+## 用户指令
+$ARGUMENTS

package/.sillyspec/config.yaml

@@ -0,0 +1,7 @@
+# SillySpec 工作区配置
+# 修改此文件后运行 /sillyspec:workspace 更新
+
+projects:
+  # 运行 /sillyspec:workspace add 添加子项目
+
+shared: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.7.27",
+  "version": "3.7.28",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/packages/dashboard/server/parser.js

@@ -311,7 +311,7 @@ export function parseDocsTree(projectPath) {
 
       if (files.length > 0) {
         groups.push({
-          key: group.key,
+          key: `${projName}::${group.key}`,
           label: group.label,
           project: projName,
           files

package/packages/dashboard/src/components/DetailPanel.vue

@@ -81,7 +81,7 @@
         <!-- Output -->
         <div v-if="activeStep.output || activeStep.files" class="px-4 py-3" style="border-bottom: 1px solid #F0F0F3;">
           <h4 class="text-[9px] font-semibold uppercase tracking-[0.2em] mb-1.5 font-[JetBrains_Mono,monospace]" style="color: #6B7280;">输出</h4>
-          <n-code v-if="activeStep.output" :code="activeStep.output" language="text" word-wrap style="max-height: 160px; overflow-y: auto;" />
+          <n-code v-if="activeStep.output" :code="activeStep.output" language="text" word-wrap style="max-height: 300px; overflow-y: auto; padding: 8px; border-radius: 4px; background: #F5F5F7;" />
           <div v-if="activeStep.files" class="mt-2 space-y-1">
             <div v-for="(file, i) in activeStep.files" :key="i" class="flex items-center gap-2 text-[10px]" style="color: #6B7280;">
               <svg class="w-3 h-3 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">

package/packages/dashboard/src/components/DocTree.vue

@@ -39,7 +39,7 @@ const groupIcons = {
 const treeData = computed(() => {
   return props.groups.map(group => ({
     key: `group-${group.key}`,
-    label: group.label,
+    label: group.project ? `${group.label} (${group.project})` : group.label,
     prefix: () => groupIcons[group.label] || '📄',
     children: group.files.map(file => ({
       key: file.path,

package/packages/dashboard/src/components/StepCard.vue

@@ -1,6 +1,6 @@
 <template>
   <div
-    :class="['group relative rounded-md cursor-pointer overflow-hidden transition-all duration-200']"
+    :class="['group relative rounded-md cursor-pointer transition-all duration-200']"
     :style="cardStyle"
     @mouseenter="hovered = true"
     @mouseleave="hovered = false"
@@ -9,7 +9,7 @@
     <!-- Left accent bar -->
     <div class="absolute left-0 top-0 bottom-0 w-[2px]" :style="{ background: barColor }" />
 
-    <div class="pl-3.5 pr-3 py-2.5">
+    <div class="pl-4 pr-4 py-3">
       <div class="flex items-center gap-2">
         <h3 class="text-[12px] font-medium transition-colors duration-150" :style="{ color: isActive ? '#D97706' : '#1C1C1E', fontFamily: '\'JetBrains Mono\', monospace' }">
           {{ step.title || step.name }}
@@ -20,8 +20,8 @@
       <!-- Hover summary -->
       <div
         v-if="step.summary || step.description"
-        class="overflow-hidden transition-all duration-200"
-        :style="{ maxHeight: hovered ? '60px' : '0', opacity: hovered ? 1 : 0 }"
+        class="transition-all duration-200"
+        :style="{ maxHeight: hovered ? '80px' : '0', opacity: hovered ? 1 : 0, overflow: 'hidden' }"
       >
         <p class="mt-1.5 text-[11px] line-clamp-2" style="color: #636366;">
           {{ step.summary || step.description }}

package/src/index.js

@@ -20,7 +20,6 @@ SillySpec CLI — 规范驱动开发工具包
 用法:
   sillyspec init               初始化（零交互，自动检测工具）
     [--tool <name>]            只安装指定工具
-    [--workspace]              工作区模式
     [--interactive]            交互式引导
     [--dir <path>]             指定目录
   sillyspec setup [--list]     安装推荐 MCP 工具
@@ -47,7 +46,7 @@ SillySpec CLI — 规范驱动开发工具包
 示例:
   sillyspec init
   sillyspec init --tool claude
-  sillyspec init --workspace
+
   sillyspec setup
   sillyspec setup --list
   sillyspec dashboard
@@ -72,7 +71,6 @@ async function main() {
   let json = false;
   let targetDir = process.cwd();
   let tool = null;
-  let workspace = false;
   let interactive = false;
   const filteredArgs = [];
 
@@ -85,8 +83,6 @@ async function main() {
     } else if (args[i] === '--tool' && args[i + 1]) {
       tool = args[i + 1];
       i++;
-    } else if (args[i] === '--workspace' || args[i] === '-w') {
-      workspace = true;
     } else if (args[i] === '--interactive' || args[i] === '-i') {
       interactive = true;
     } else if (args[i] === '--list' || args[i] === '-l') {
@@ -111,7 +107,7 @@ async function main() {
 
   switch (command) {
     case 'init':
-      await cmdInit(dir, { tool, workspace, interactive });
+      await cmdInit(dir, { tool, interactive });
       break;
     case 'setup':
       const setupList = filteredArgs.includes('--list') || filteredArgs.includes('-l');

package/src/init.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSy
 import { join, resolve, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
-import { checkbox, select, confirm, input } from '@inquirer/prompts';
+import { checkbox, confirm, input } from '@inquirer/prompts';
 import { ProgressManager } from './progress.js';
 import chalk from 'chalk';
 
@@ -106,7 +106,7 @@ function isTTY() {
 
 // ── 核心安装逻辑 ──
 
-async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
+async function doInstall(projectDir, tools, subprojects = []) {
   // 创建基础目录
   // .sillyspec/projects/    → 项目注册表
   // .sillyspec/docs/<name>/ → 统一文档中心
@@ -128,13 +128,11 @@ async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
   const gitkeepPath = join(scanDir, '.gitkeep');
   if (!existsSync(gitkeepPath)) writeFileSync(gitkeepPath, '');
 
-  // 兼容：保留旧的 codebase/ changes/ quicklog/ 目录（如果已存在不删除）
-  if (isWorkspace) {
-    mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
-    mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });
-  }
+  // 创建 shared/workspace 目录
+  mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
+  mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });
 
-  // 创建知识库骨架（所有模式）
+  // 创建知识库骨架
   const knowledgeDir = join(projectDir, '.sillyspec', 'knowledge');
   mkdirSync(knowledgeDir, { recursive: true });
   const indexPath = join(knowledgeDir, 'INDEX.md');
@@ -207,19 +205,17 @@ async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
     console.log(chalk.yellow('    ⚠ 未找到 skills 目录，跳过 Claude Code skills 同步'));
   }
 
-
   // 工作区配置
-  if (isWorkspace) {
-    const configPath = join(projectDir, '.sillyspec', 'config.yaml');
-    if (!existsSync(configPath)) {
-      let projectsYaml = '';
-      if (subprojects.length > 0) {
-        projectsYaml = subprojects.map(p =>
-          `  ${p.name}:\n    path: ${p.path}\n    role: ${p.role || p.name}${p.repo ? `\n    repo: ${p.repo}` : ''}`
-        ).join('\n');
-      }
+  const configPath = join(projectDir, '.sillyspec', 'config.yaml');
+  if (!existsSync(configPath)) {
+    let projectsYaml = '';
+    if (subprojects.length > 0) {
+      projectsYaml = subprojects.map(p =>
+        `  ${p.name}:\n    path: ${p.path}\n    role: ${p.role || p.name}${p.repo ? `\n    repo: ${p.repo}` : ''}`
+      ).join('\n');
+    }
 
-      writeFileSync(configPath,
+    writeFileSync(configPath,
 `# SillySpec 工作区配置
 # 修改此文件后运行 /sillyspec:workspace 更新
 
@@ -228,16 +224,14 @@ ${projectsYaml || '  # 运行 /sillyspec:workspace add 添加子项目'}
 
 shared: []
 `
-      );
-    }
+    );
   }
 }
 
 // ── 安装完成总结 ──
 
-function showSummary(version, tools, isWorkspace) {
+function showSummary(version, tools) {
   const toolLabels = tools.map(t => TOOL_LABELS[t] || t);
-  const mode = isWorkspace ? '多项目工作区' : '单项目';
 
   console.log('');
   console.log(chalk.green('  ═══════════════════════════════════════'));
@@ -245,7 +239,6 @@ function showSummary(version, tools, isWorkspace) {
   console.log(chalk.green('  ═══════════════════════════════════════'));
   console.log('');
   console.log(`  已安装工具: ${chalk.cyan(toolLabels.join(', '))}`);
-  console.log(`  模式: ${chalk.yellow(mode)}`);
   console.log('  📁 .sillyspec/ — 项目规范目录');
   console.log('');
   console.log('  下一步：使用 AI 技能开始工作');
@@ -270,7 +263,7 @@ export function getVersion() {
 // ── 主命令 ──
 
 export async function cmdInit(projectDir, options = {}) {
-  const { tool, workspace, interactive } = options;
+  const { tool, interactive } = options;
   const version = getVersion();
 
   // ── 交互式模式（--interactive 或 -i）──
@@ -302,20 +295,11 @@ export async function cmdInit(projectDir, options = {}) {
       validate: (answer) => answer.length > 0 || '至少选择一个工具',
     });
 
-    // 工作区模式
-    const isWorkspace = await select({
-      message: '选择项目模式',
-      choices: [
-        { name: '单项目模式', value: 'false' },
-        { name: '多项目工作区', value: 'true' },
-      ],
-    }) === 'true';
-
-    // 工作区子项目引导
+    // 子项目引导（始终执行）
     let subprojects = [];
-    if (isWorkspace) {
+    {
       console.log('');
-      console.log(chalk.yellow('📋 工作区模式 — 添加子项目'));
+      console.log(chalk.yellow('📋 添加子项目'));
       console.log(chalk.dim('   子项目是工作区中的独立项目目录（如 frontend/、backend/）'));
       console.log('');
 
@@ -378,8 +362,8 @@ export async function cmdInit(projectDir, options = {}) {
     }
 
     console.log('');
-    const count = await doInstall(projectDir, selectedTools, isWorkspace, subprojects);
-    showSummary(version, selectedTools, isWorkspace);
+    await doInstall(projectDir, selectedTools, subprojects);
+    showSummary(version, selectedTools);
     return;
   }
 
@@ -397,7 +381,7 @@ export async function cmdInit(projectDir, options = {}) {
     tools = detectTools(projectDir);
   }
 
-  await doInstall(projectDir, tools, !!workspace);
+  await doInstall(projectDir, tools);
 
   console.log('');
   console.log(chalk.green(`  ✅ SillySpec v${version} 安装完成！`));

package/src/progress.js

@@ -17,7 +17,7 @@ const PROGRESS_FILE = 'progress.json';
 const BACKUP_FILE = 'progress.json.bak';
 
 const CURRENT_VERSION = 2;
-const VALID_STAGES = ['brainstorm', 'propose', 'plan', 'execute', 'verify', 'scan', 'quick', 'archive', 'status'];
+const VALID_STAGES = ['brainstorm', 'propose', 'plan', 'execute', 'verify', 'scan', 'quick', 'archive', 'status', 'doctor'];
 const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked'];
 
 const STAGE_LABELS = {
@@ -30,6 +30,7 @@ const STAGE_LABELS = {
   quick: '⚡ 快速任务',
   archive: '📦 归档变更',
   status: '📊 状态查看',
+  doctor: '🩺 项目自检',
 };
 
 function emptyStage() {
@@ -312,6 +313,10 @@ export class ProgressManager {
     console.log(`⚠️  发现问题，尝试修复...`);
     let fixed = { ...data, stages: { ...data.stages } };
     let changed = false;
+    if (!fixed.project) {
+      fixed.project = basename(cwd);
+      changed = true;
+    }
     if (!fixed._version || !Number.isInteger(fixed._version) || fixed._version < 1) {
       fixed._version = CURRENT_VERSION;
       changed = true;

package/src/stages/archive.js

@@ -39,7 +39,7 @@ export const definition = {
 
 ### 操作
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
-2. \`git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"\`
+2. \`git add .sillyspec/\` — **不要 commit**，由用户通过统一提交工具处理
 3. 更新 progress.json：
    - 清除当前变更信息（归档后不再活跃）
    - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除

package/src/stages/brainstorm.js

@@ -27,17 +27,16 @@ export const definition = {
       prompt: `加载项目现有上下文，理解代码结构和约定。
 
 ### 操作
-1. 检查是否工作区模式：\`ls .sillyspec/projects/*.yaml\`
-2. 工作区模式：加载 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文
-3. 单项目模式：加载 PROJECT.md、REQUIREMENTS.md、ROADMAP.md
-4. 棕地项目：读取 docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
-5. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
+1. 读取 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文
+2. 询问本次需求属于哪个子项目
+3. 棕地项目：读取 docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
+4. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
 
 ### 输出
 项目现状理解摘要（3-5 句话，关键约定和架构决策）
 
 ### 注意
-- 工作区模式下需要询问本次需求属于哪个子项目
+- 始终询问本次需求属于哪个子项目
 - 棕地项目必须读取数据模型章节`,
       outputHint: '上下文摘要',
       optional: false

package/src/stages/doctor.js

@@ -0,0 +1,303 @@
+// SillySpec Doctor — 项目自检阶段
+// 检查项通过 prompt 中的 bash 命令执行，此文件仅定义步骤结构
+
+
+export const definition = {
+  name: 'doctor',
+  title: '项目自检',
+  description: '检查 SillySpec 配置、构建环境和外部依赖',
+  auxiliary: true,
+  steps: [
+    {
+      name: 'SillySpec 内部检查',
+      prompt: `运行 SillySpec 内部检查。逐项执行以下命令并汇总结果：
+
+### 1. 目录结构完整性
+\`\`\`bash
+# 检查 .sillyspec/ 及子目录
+for d in .sillyspec .sillyspec/projects .sillyspec/docs .sillyspec/changes .sillyspec/.runtime; do
+  [ -d "$d" ] && echo "✅ $d" || echo "❌ $d"
+done
+# 检查 progress.json
+[ -f .sillyspec/.runtime/progress.json ] && echo "✅ progress.json 存在" || echo "❌ progress.json 不存在"
+node -e "JSON.parse(require('fs').readFileSync('.sillyspec/.runtime/progress.json','utf8')); console.log('✅ progress.json 可解析')" 2>/dev/null || echo "⚠️ progress.json 不可解析"
+\`\`\`
+
+### 2. 项目配置检查
+\`\`\`bash
+ls .sillyspec/projects/*.yaml 2>/dev/null
+# 对每个 yaml 文件，检查 name 和 path 字段，验证 path 存在
+for f in .sillyspec/projects/*.yaml; do
+  [ -f "$f" ] || continue
+  name=$(grep '^name:' "$f" | head -1 | sed 's/^name:[[:space:]]*//')
+  p=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+  [ -z "$name" ] && echo "⚠️ $(basename $f) — 缺少 name"
+  [ -z "$p" ] && echo "⚠️ $(basename $f) — 缺少 path"
+  [ -n "$p" ] && [ ! -d "$p" ] && echo "❌ $(basename $f) — path 不存在: $p"
+  [ -n "$name" ] && [ -n "$p" ] && [ -d "$p" ] && echo "✅ $(basename $f) — $name ($p)"
+done
+\`\`\`
+
+### 3. 进度数据一致性
+\`\`\`bash
+# 读取 currentChange 并检查目录存在性
+node -e "
+const p = JSON.parse(require('fs').readFileSync('.sillyspec/.runtime/progress.json','utf8'));
+const cc = p.currentChange;
+if (!cc) { console.log('ℹ️ 无当前变更'); process.exit(0); }
+const dir = '.sillyspec/changes/' + cc;
+const exists = require('fs').existsSync(dir);
+console.log(exists ? '✅ currentChange 目录存在: ' + cc : '❌ currentChange 目录不存在: ' + cc);
+// 检查各阶段产出
+const stages = p.stages || {};
+for (const [name, sd] of Object.entries(stages)) {
+  if (sd.status === 'completed' && sd.steps.length > 0) {
+    const hasOutput = sd.steps.some(s => s.output && s.output.trim());
+    console.log('  ' + name + ': ' + (hasOutput ? '✅ 有产出' : '⚠️ 已完成但无产出记录'));
+  }
+}
+" 2>/dev/null || echo "⚠️ 无法读取 progress.json"
+\`\`\`
+
+### 4. 孤儿文件检查
+\`\`\`bash
+node -e "
+const fs = require('fs');
+const dir = '.sillyspec/changes';
+if (!fs.existsSync(dir)) { console.log('ℹ️ changes/ 目录不存在'); process.exit(0); }
+const subs = fs.readdirSync(dir).filter(f => fs.statSync(dir+'/'+f).isDirectory());
+if (subs.length === 0) { console.log('ℹ️ 无变更目录'); process.exit(0); }
+let progress;
+try { progress = JSON.parse(fs.readFileSync('.sillyspec/.runtime/progress.json','utf8')); } catch { console.log('⚠️ 无法读取 progress.json'); subs.forEach(s => console.log('❓ ' + s)); process.exit(0); }
+const known = new Set();
+if (progress.currentChange) known.add(progress.currentChange);
+for (const sd of Object.values(progress.stages || {})) {
+  (sd.steps || []).forEach(s => { if (s.output) known.add(s.output); });
+}
+subs.forEach(s => {
+  console.log(known.has(s) ? '✅ ' + s + ' — 已关联' : '⚠️ ' + s + ' — 孤儿目录（可清理）');
+});
+"
+\`\`\`
+
+### 5. 配置文件检查
+\`\`\`bash
+# 检查 local.yaml 和 STACK.md
+for f in .sillyspec/projects/*.yaml; do
+  [ -f "$f" ] || continue
+  name=$(grep '^name:' "$f" | head -1 | sed 's/^name:[[:space:]]*//')
+  p=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+  [ -z "$p" ] && continue
+  local_yaml="$p/.sillyspec/local.yaml"
+  stack_md="$p/.sillyspec/STACK.md"
+  [ -f "$local_yaml" ] && echo "✅ local.yaml ($name)" || echo "⚠️ local.yaml ($name) — 不存在"
+  if [ -f "$local_yaml" ]; then
+    grep -q 'build:' "$local_yaml" && echo "  ✅ build 命令已配置" || echo "  ⚠️ 缺少 build 命令"
+    grep -q 'test:' "$local_yaml" && echo "  ✅ test 命令已配置" || echo "  ⚠️ 缺少 test 命令"
+  fi
+  [ -f "$stack_md" ] && echo "✅ STACK.md ($name)" || echo "⚠️ STACK.md ($name) — 不存在"
+done
+\`\`\`
+
+### 输出
+汇总所有检查结果，按以下格式：
+\`\`\`
+## SillySpec 内部
+✅/⚠️/❌ 各项状态
+\`\`\`
+
+### 注意
+- 不要编造路径或结果，严格基于命令输出
+- 如果 .sillyspec/ 不存在，直接输出 ❌ 并跳过后续检查`,
+      outputHint: 'SillySpec 内部检查结果',
+      optional: false
+    },
+    {
+      name: '构建环境检查',
+      prompt: `检查项目构建环境。先探测项目使用的构建工具，再逐项检查可用性。
+
+### 1. 探测构建工具
+\`\`\`bash
+# 确定项目路径（使用 progress.json 中的项目或当前目录）
+PROJECT_DIR=$(node -e "
+const fs=require('fs');
+try{const p=JSON.parse(fs.readFileSync('.sillyspec/.runtime/progress.json','utf8'));if(p.project){console.log(p.project);process.exit(0)}}catch{}
+const files=fs.readdirSync('.sillyspec/projects').filter(f=>f.endsWith('.yaml'));
+if(files.length>0){const c=fs.readFileSync('.sillyspec/projects/'+files[0],'utf8');const m=c.match(/^path:\\s*(.+)/m);console.log(m?m[1].trim():'.')}else console.log('.')
+" 2>/dev/null)
+echo "项目目录: $PROJECT_DIR"
+
+# 探测构建工具
+for f in pom.xml build.gradle package.json requirements.txt pyproject.toml go.mod Cargo.toml; do
+  [ -f "$PROJECT_DIR/$f" ] && echo "检测到: $f"
+done
+[ -f "$PROJECT_DIR/.sillyspec/STACK.md" ] && cat "$PROJECT_DIR/.sillyspec/STACK.md" | head -30
+\`\`\`
+
+### 2. 构建工具可用性
+根据上面检测到的工具，运行对应检查（未检测到的跳过）：
+
+**Maven 项目：**
+\`\`\`bash
+timeout 10 mvn -v 2>/dev/null | head -1 && echo "✅ Maven 可用" || echo "❌ Maven 不可用"
+[ -f ~/.m2/settings.xml ] && echo "✅ Maven settings.xml 存在" || echo "⚠️ Maven settings.xml 不存在"
+timeout 10 java -version 2>&1 | head -1
+\`\`\`
+
+**Gradle 项目：**
+\`\`\`bash
+timeout 10 gradle -v 2>/dev/null | head -1 && echo "✅ Gradle 可用" || echo "❌ Gradle 不可用"
+\`\`\`
+
+**Node.js 项目：**
+\`\`\`bash
+timeout 5 node -v 2>/dev/null && echo "✅ Node.js 可用" || echo "❌ Node.js 不可用"
+timeout 5 npm -v 2>/dev/null && echo "✅ npm 可用" || echo "❌ npm 不可用"
+timeout 5 pnpm -v 2>/dev/null && echo "✅ pnpm 可用" || echo "ℹ️ pnpm 未安装"
+# 检查 registry
+npm config get registry 2>/dev/null
+\`\`\`
+
+**Python 项目：**
+\`\`\`bash
+timeout 5 python3 --version 2>/dev/null && echo "✅ Python3 可用" || echo "❌ Python3 不可用"
+timeout 5 pip3 --version 2>/dev/null && echo "✅ pip3 可用" || echo "❌ pip3 不可用"
+\`\`\`
+
+### 3. Maven 私服检查（仅 Maven 项目）
+\`\`\`bash
+# 从 settings.xml 提取仓库地址
+if [ -f ~/.m2/settings.xml ]; then
+  grep -oP 'https?://[^<"]+:[0-9]+' ~/.m2/settings.xml 2>/dev/null | sort -u | while read url; do
+    timeout 5 curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null
+    echo " — $url"
+  done
+fi
+# 从 pom.xml 提取
+if [ -f "$PROJECT_DIR/pom.xml" ]; then
+  grep -oP 'https?://[^<"]+:[0-9]+' "$PROJECT_DIR/pom.xml" 2>/dev/null | sort -u | while read url; do
+    code=$(timeout 5 curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null)
+    [ "$code" = "000" ] && echo "❌ 私服不可达: $url（超时）" || echo "✅ 私服可达 ($code): $url"
+  done
+fi
+\`\`\`
+
+### 4. 运行时环境
+\`\`\`bash
+timeout 5 node -v 2>/dev/null && echo "Node.js: $(node -v)" || echo "❌ Node.js 未安装"
+timeout 5 git --version 2>/dev/null && echo "Git: $(git --version)" || echo "❌ Git 未安装"
+timeout 10 git remote -v 2>/dev/null | head -2
+timeout 5 git ls-remote --heads origin 2>/dev/null >/dev/null && echo "✅ Git remote 可达" || echo "⚠️ Git remote 不可达"
+timeout 5 java -version 2>&1 | head -1
+timeout 5 python3 --version 2>/dev/null
+\`\`\`
+
+### 输出
+汇总所有检查结果：
+\`\`\`
+## 构建环境
+✅/⚠️/❌ 各项状态
+\`\`\`
+
+### 注意
+- 未检测到的构建工具直接跳过，不要报错
+- timeout 超时的命令视为不可用
+- 不编造结果`,
+      outputHint: '构建环境检查结果',
+      optional: false
+    },
+    {
+      name: '外部依赖检查',
+      prompt: `检查外部依赖工具是否可用。
+
+### 1. Context7 MCP
+\`\`\`bash
+# 检查 MCP 配置
+for f in ~/.config/claude/claude_desktop_config.json ~/.cursor/mcp.json ~/.openclaw/mcp.json; do
+  [ -f "$f" ] && echo "MCP 配置文件: $f" && grep -i context7 "$f" 2>/dev/null && echo "✅ Context7 已配置" || true
+done
+# 也检查 sillyspec 自身的 setup
+node -e "
+try{const m=require(require('path').join(require('os').homedir(),'.sillyspec','config.json'));console.log('✅ sillyspec config 存在')}catch{console.log('ℹ️ 无 sillyspec 全局配置')}
+" 2>/dev/null
+\`\`\`
+
+### 2. grep.app
+\`\`\`bash
+timeout 5 curl -s -o /dev/null -w "%{http_code}" https://grep.app 2>/dev/null | grep -q "200" && echo "✅ grep.app 可达" || echo "⚠️ grep.app 不可达"
+\`\`\`
+
+### 3. 其他 AI 工具（可选）
+\`\`\`bash
+# 检查常用 AI/开发工具
+timeout 5 which gh 2>/dev/null && echo "✅ GitHub CLI 可用" || echo "ℹ️ GitHub CLI 未安装"
+timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ Docker 未安装"
+\`\`\`
+
+### 输出
+\`\`\`
+## 外部依赖
+✅/⚠️/❌ 各项状态
+\`\`\`
+
+### 注意
+- 不编造结果
+- 工具未安装用 ℹ️ 标记（非错误），不可达用 ⚠️`,
+      outputHint: '外部依赖检查结果',
+      optional: false
+    },
+    {
+      name: '汇总报告',
+      prompt: `汇总前三步的所有检查结果，生成最终的自检报告。
+
+### 输出格式
+\`\`\`
+🔍 SillySpec Doctor — 项目自检报告
+
+## SillySpec 内部
+✅ .sillyspec/ 目录结构 — 正常
+✅ projects/*.yaml — N 个项目已注册
+⚠️  local.yaml (xxx) — 缺少 test 命令
+❌ progress.json — brainstorm 标记完成但 design.md 不存在
+
+## 构建环境
+✅ Node.js v23.4.0 — 可用
+✅ npm 10.x — 可用
+✅ Java 17.0.2 — 可用
+❌ Maven 私服 (10.0.0.1:8081) — 不可达（超时）
+
+## 外部依赖
+✅ Context7 MCP — 已配置
+⚠️  grep.app — 不可达
+\`\`\`
+
+### 要求
+- 基于前 3 步的实际输出汇总，不要编造
+- 每类问题归入对应分区
+- 全部通过给出 🎉
+- 如果有 ❌ 或 ⚠️，在末尾逐项给出修复建议
+
+### 修复建议模板
+根据问题类型给出具体可操作的修复命令：
+
+**常见问题及修复：**
+- CLI 未安装 → \`npm install -g sillyspec\` 或 \`npx sillyspec\`
+- 缺少 local.yaml → \`sillyspec init\` 重新生成，或手动创建
+- local.yaml 缺少 build/test → 补充对应命令
+- 缺少 STACK.md → \`sillyspec run scan\` 重新扫描
+- progress.json 不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
+- 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`
+- Maven 私服不可达 → 检查 VPN、settings.xml 配置、私服状态
+- Git remote 不可达 → 检查网络、SSH key 或凭证
+- 工具未安装 → 给出安装命令（如 \`brew install maven\`）
+
+每条建议格式：
+\`\`\`
+💡 修复：<问题描述>
+   <具体命令或操作>
+\`\`\``,
+      outputHint: '完整自检报告',
+      optional: false
+    }
+  ]
+}

package/src/stages/execute.js

@@ -33,7 +33,7 @@ const fixedPrefix = [
 2. 读取 design.md（技术方案）
 3. 读取 CONVENTIONS.md、ARCHITECTURE.md
 4. 读取 local.yaml（构建命令）
-5. 工作区模式：额外加载 CODEBASE-OVERVIEW.md
+5. 加载 CODEBASE-OVERVIEW.md
 
 ### 输出
 已加载的上下文摘要`,

package/src/stages/index.js

@@ -7,6 +7,7 @@ import { definition as scan } from './scan.js'
 import { definition as quick } from './quick.js'
 import { definition as archive } from './archive.js'
 import { definition as status } from './status.js'
+import { definition as doctor } from './doctor.js'
 
 export const stageRegistry = {
   brainstorm,
@@ -17,7 +18,8 @@ export const stageRegistry = {
   scan,
   quick,
   archive,
-  status
+  status,
+  doctor
 }
 
 // 流程阶段顺序，用于 getNextStage
@@ -30,4 +32,4 @@ export function getNextStage(currentStage) {
 }
 
 // 辅助命令（不影响流程阶段推进）
-export const auxiliaryStages = ['scan', 'quick', 'archive', 'status']
+export const auxiliaryStages = ['scan', 'quick', 'archive', 'status', 'doctor']

package/src/stages/plan.js

@@ -21,10 +21,9 @@ export const definition = {
       prompt: `加载所有规范文件和代码库上下文。
 
 ### 操作
-1. 检测工作区模式
+1. 读取 CODEBASE-OVERVIEW.md + 各子项目上下文
 2. 读取 proposal.md、design.md、tasks.md、requirements.md
 3. 读取 CONVENTIONS.md、ARCHITECTURE.md、STACK.md
-4. 工作区模式：额外加载 CODEBASE-OVERVIEW.md + 各子项目上下文
 
 ### 输出
 已加载的文件清单`,

package/src/stages/propose.js

@@ -22,7 +22,7 @@ export const definition = {
       prompt: `加载所有相关规范和代码库上下文。
 
 ### 操作
-1. 检测工作区模式
+1. 加载 CODEBASE-OVERVIEW.md 和子项目上下文
 2. 读取最新设计文档、需求文档、代码库约定
 3. 如果是子阶段变更，读取 MASTER.md 和前序阶段设计
 

package/src/stages/scan.js

@@ -5,18 +5,18 @@ export const definition = {
   auxiliary: true,
   steps: [
     {
-      name: '检查工作区和已有文档',
-      prompt: `检查工作区模式和已有扫描文档。
+      name: '检查已有扫描文档和子项目列表',
+      prompt: `检查已有扫描文档和子项目列表。
 
 ### 操作
-1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\` — 判断是否工作区模式
-2. \`ls docs/*/scan/ 2>/dev/null\` — 检查已有文档
-3. \`wc -l docs/*/scan/*.md 2>/dev/null\` — 文档行数
-4. 已有 3 份 → 建议升级深度扫描；已有 7 份 → 建议刷新或跳过
-5. 工作区模式 → 询问扫描范围（逐个/选子项目/退出）
+1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\` — 检查已有文档
+1. \`ls docs/*/scan/ 2>/dev/null\` — 检查已有文档
+2. \`wc -l docs/*/scan/*.md 2>/dev/null\` — 文档行数
+3. 已有 3 份 → 建议升级深度扫描；已有 7 份 → 建议刷新或跳过
+5. 显示子项目列表供选择扫描范围
 
 ### 输出
-工作区模式判断 + 已有文档状态 + 扫描建议`,
+已有文档状态 + 扫描建议`,
       outputHint: '工作区和文档状态',
       optional: false
     },
@@ -127,7 +127,7 @@ TESTING.md、CONCERNS.md、PROJECT.md 路径`,
 1. 检查 7 份文档是否全部生成
 2. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
 3. 清理：\`rm -f docs/<project>/scan/_env-detect.md\`
-4. \`git add . && git commit -m "chore: sillyspec scan - codebase mapped"\`
+4. \`git add .\` — **不要 commit**，由用户通过统一提交工具处理
 
 ### 输出
 扫描完整性报告 + commit hash

package/src/stages/status.js

@@ -4,33 +4,6 @@ export const definition = {
   description: '查看项目进度和状态',
   auxiliary: true,
   steps: [
-    {
-      name: '检查工作区模式',
-      prompt: `判断是否为工作区模式。
-
-### 操作
-1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\`
-2. 是 → 工作区模式，对每个子项目执行状态检查
-3. 否 → 单项目模式，继续后续步骤
-
-### 工作区模式输出格式：
-\`\`\`
-🏢 工作区状态
-📦 子项目：
-  ✅ frontend  ./frontend
-     📋 项目：已初始化
-     📂 代码库：已扫描（7 份文档）
-     🔄 进行中：1 个变更
-  ⚠️ backend   ./backend
-     📂 代码库：未扫描
-📄 共享规范：2 份
-\`\`\`
-
-### 输出
-工作区/单项目判断`,
-      outputHint: '模式判断',
-      optional: false
-    },
     {
       name: '项目基础信息',
       prompt: `收集项目基础信息。