sillyspec 3.18.3 → 3.18.4

package/package.json

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

package/src/contract-matrix.js

@@ -0,0 +1,278 @@
+/**
+ * contract-matrix.js — API Contract Matrix 生成与注入
+ *
+ * plan 阶段：识别 task 之间的 provider/consumer 关系，生成契约矩阵
+ * execute 阶段：
+ *   - 后端 task 完成后自动提取 endpoint artifact
+ *   - 前端 task 开始时注入上游契约
+ * verify 阶段：读取 artifact 做 parity check
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs'
+import { join, resolve, basename, relative } from 'path'
+import {
+  scanBackendEndpoints,
+  scanFrontendApiCalls,
+  normalizePath,
+} from './endpoint-extractor.js'
+
+// ─── 关键词检测 ─────────────────────────────────────────────────────────
+
+const PROVIDER_KEYWORDS = /router|routes|endpoint|api|backend|controller|fastapi|flask|express|koa|spring/i
+const CONSUMER_KEYWORDS = /frontend|client|service|apiFetch|request|fetch|axios|http/i
+
+/**
+ * 判断一个 task 文档是 provider（产出 API）还是 consumer（消费 API）
+ * @param {string} taskContent - task markdown 内容
+ * @returns {{ isProvider: boolean, isConsumer: boolean, confidence: number }}
+ */
+export function classifyTask(taskContent) {
+  const isProvider = PROVIDER_KEYWORDS.test(taskContent)
+  const isConsumer = CONSUMER_KEYWORDS.test(taskContent)
+  // 避免所有 task 都被标记（因为几乎所有 task 都含 "api"）
+  // 加强判定：provider 要命中 router/endpoint/backend/controller + api
+  // consumer 要命中 frontend/client/apiFetch + api
+  const providerStrong = /router|endpoint|backend|controller|fastapi|flask/i.test(taskContent)
+  const consumerStrong = /frontend|apiFetch|axios|api.*client/i.test(taskContent)
+  const providerConfidence = providerStrong ? 0.8 : (isProvider ? 0.4 : 0)
+  const consumerConfidence = consumerStrong ? 0.8 : (isConsumer ? 0.4 : 0)
+  return {
+    isProvider: providerConfidence >= 0.4,
+    isConsumer: consumerConfidence >= 0.4,
+    confidence: Math.max(providerConfidence, consumerConfidence),
+  }
+}
+
+/**
+ * 从 plan.md 解析 task 依赖关系，识别 provider → consumer 对
+ * @param {string} planContent - plan.md 内容
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @returns {Array<{ provider: string, consumer: string, type: string }>}
+ */
+export function buildContractMatrix(planContent, changeDir) {
+  const contracts = []
+
+  // 解析 task 依赖关系
+  // 格式: - [ ] task-04: ... (depends_on: [task-01]) 或
+  //        | task-04 | ... | 01 |
+  const taskDeps = parseTaskDependencies(planContent)
+
+  // 读取各 task 文档，分类 provider/consumer
+  const taskClasses = {}
+  for (const taskName of Object.keys(taskDeps)) {
+    const taskFile = join(changeDir, 'tasks', `${taskName}.md`)
+    if (existsSync(taskFile)) {
+      taskClasses[taskName] = classifyTask(readFileSync(taskFile, 'utf8'))
+    }
+  }
+
+  // 识别契约对：A depends_on B，且 A 是 consumer，B 是 provider
+  for (const [consumer, deps] of Object.entries(taskDeps)) {
+    const consumerClass = taskClasses[consumer]
+    if (!consumerClass?.isConsumer) continue
+
+    for (const provider of deps) {
+      const providerClass = taskClasses[provider]
+      if (!providerClass?.isProvider) continue
+
+      // 避免自引用和重复
+      if (consumer === provider) continue
+      const alreadyExists = contracts.some(
+        c => c.provider === provider && c.consumer === consumer
+      )
+      if (alreadyExists) continue
+
+      contracts.push({
+        provider,
+        consumer,
+        type: 'api',
+      })
+    }
+  }
+
+  return contracts
+}
+
+/**
+ * 从 plan.md 解析 task 依赖关系
+ * @param {string} planContent
+ * @returns {Record<string, string[]>} task → depends_on list
+ */
+function parseTaskDependencies(planContent) {
+  const deps = {}
+
+  // 方式 1: 表格形式 | task-04 | ... | 01,02 |
+  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
+  for (const match of tableRows) {
+    const task = `task-${match[1]}`
+    const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
+    deps[task] = depList
+  }
+
+  // 方式 2: depends_on 关键字
+  const dependsPattern = planContent.matchAll(/task-(\d+).*?depends_on.*?(\d+(?:\s*[,，]\s*\d+)*)/gi)
+  for (const match of dependsPattern) {
+    const task = `task-${match[1]}`
+    const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
+    if (!deps[task]) deps[task] = []
+    for (const d of depList) {
+      if (!deps[task].includes(d)) deps[task].push(d)
+    }
+  }
+
+  return deps
+}
+
+// ─── Execute 阶段：后端 task 完成后提取 artifact ───────────────────────
+
+/**
+ * 后端 task 完成后，扫描变更文件提取 endpoint artifact
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @param {string} worktreePath - worktree 路径（扫描源码用）
+ * @param {string} specBase - .sillyspec 目录
+ * @param {string} taskName - task-04
+ * @returns {{ ok: boolean, endpoints: Array, artifactPath: string|null }}
+ */
+export function extractProviderArtifact(changeDir, worktreePath, specBase, taskName) {
+  const artifactDir = join(specBase, '.runtime', 'contract-artifacts', taskName)
+  const artifactPath = join(artifactDir, 'endpoints.json')
+
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return { ok: false, endpoints: [], artifactPath: null, error: 'worktree not found' }
+  }
+
+  try {
+    const endpoints = scanBackendEndpoints(worktreePath)
+
+    if (endpoints.length > 0) {
+      mkdirSync(artifactDir, { recursive: true })
+      const artifact = {
+        task: taskName,
+        type: 'backend_endpoints',
+        extractedAt: new Date().toISOString(),
+        endpoints: endpoints.map(e => ({
+          method: e.method,
+          path: normalizePath(e.path),
+          source: relative(worktreePath, e.source),
+          line: e.line,
+        })),
+      }
+      writeFileSync(artifactPath, JSON.stringify(artifact, null, 2) + '\n')
+      return { ok: true, endpoints: artifact.endpoints, artifactPath }
+    }
+
+    // 无端点提取到 — 不算错误（可能不是 router task）
+    return { ok: true, endpoints: [], artifactPath: null }
+  } catch (e) {
+    return { ok: false, endpoints: [], artifactPath: null, error: e.message }
+  }
+}
+
+// ─── Execute 阶段：前端 task 开始时注入契约 ─────────────────────────────
+
+/**
+ * 为 consumer task 构建上游契约注入文本
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @param {string} specBase - .sillyspec 目录
+ * @param {string} taskName - 当前 task（consumer）
+ * @param {Array<{ provider: string, consumer: string, type: string }>} contracts
+ * @returns {string|null} 注入到 prompt 的契约文本，无契约时返回 null
+ */
+export function buildConsumerInjection(changeDir, specBase, taskName, contracts) {
+  const myContracts = contracts.filter(c => c.consumer === taskName)
+  if (myContracts.length === 0) return null
+
+  const parts = []
+  for (const contract of myContracts) {
+    const artifactDir = join(specBase, '.runtime', 'contract-artifacts', contract.provider)
+    const artifactFile = join(artifactDir, 'endpoints.json')
+
+    let endpoints = []
+    if (existsSync(artifactFile)) {
+      try {
+        const artifact = JSON.parse(readFileSync(artifactFile, 'utf8'))
+        endpoints = artifact.endpoints || []
+      } catch {}
+    }
+
+    parts.push(`### Upstream Contract: ${contract.provider}`)
+    if (endpoints.length > 0) {
+      parts.push(`\nAvailable endpoints from **${contract.provider}**:`)
+      for (const ep of endpoints) {
+        parts.push(`- **${ep.method}** \`${ep.path}\``)
+      }
+    } else {
+      parts.push(`\n⚠️ No endpoint artifact found for ${contract.provider}. This may indicate a contract gap.`)
+    }
+  }
+
+  if (parts.length === 0) return null
+
+  parts.unshift('## Upstream API Contracts')
+  parts.push('')
+  parts.push('### Rules')
+  parts.push('1. Do not invent API paths. Use only endpoints listed above.')
+  parts.push('2. If a required endpoint is missing, **stop and report the contract gap** instead of coding around it.')
+  parts.push('3. If you need to add new endpoints, you must also update the backend provider task.')
+
+  return parts.join('\n')
+}
+
+// ─── Verify 阶段：parity check ──────────────────────────────────────────
+
+/**
+ * verify 阶段执行 API parity check
+ * @param {string} specBase - .sillyspec 目录
+ * @param {string} worktreePath - worktree 路径
+ * @returns {{ ok: boolean, missingBackend: Array, unusedBackend: Array, summary: string }}
+ */
+export function verifyApiParity(specBase, worktreePath) {
+  const { diffApiParity } = require('./endpoint-extractor.js')
+
+  // 读取所有 provider artifacts
+  const artifactBase = join(specBase, '.runtime', 'contract-artifacts')
+  const allProviderEndpoints = []
+
+  if (existsSync(artifactBase)) {
+    for (const entry of readdirSync(artifactBase, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const epFile = join(artifactBase, entry.name, 'endpoints.json')
+      if (existsSync(epFile)) {
+        try {
+          const artifact = JSON.parse(readFileSync(epFile, 'utf8'))
+          for (const ep of (artifact.endpoints || [])) {
+            allProviderEndpoints.push({
+              method: ep.method,
+              path: ep.path,
+              source: `${entry.name}/${ep.source}`,
+            })
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // 扫描前端调用
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return {
+      ok: true,
+      missingBackend: [],
+      unusedBackend: [],
+      summary: 'No worktree to scan for parity check',
+    }
+  }
+
+  const frontendCalls = scanFrontendApiCalls(worktreePath)
+  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, allProviderEndpoints)
+
+  const ok = missingBackend.length === 0
+  let summary = ok
+    ? `✅ API parity check passed: ${allProviderEndpoints.length} backend endpoints, ${frontendCalls.length} frontend calls`
+    : `❌ API parity check failed: ${missingBackend.length} frontend calls have no matching backend endpoint`
+
+  if (unusedBackend.length > 0) {
+    summary += ` | ${unusedBackend.length} backend endpoints unused by frontend`
+  }
+
+  return { ok, missingBackend, unusedBackend, summary }
+}

package/src/endpoint-extractor.js

@@ -0,0 +1,315 @@
+/**
+ * endpoint-extractor.js — 从代码中提取 HTTP 端点定义和调用
+ *
+ * provider 端：扫描 router 文件，提取注册的 API 路径
+ * consumer 端：扫描前端文件，提取 apiFetch/request 调用路径
+ *
+ * 契约对账时：provider 产出 ≠ consumer 消费 → gap
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, extname, basename, dirname, resolve } from 'path'
+import { execSync } from 'child_process'
+
+// ─── Provider: 扫描后端 router 注册的端点 ───────────────────────────────
+
+/**
+ * 从单个文件提取 FastAPI router 端点
+ * 支持 APIRouter(prefix=...) 和 @router.get/post/put/delete/patch("/path")
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractFastApiEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  // 1. 提取 router prefix
+  let routerPrefix = ''
+  for (const line of lines) {
+    const prefixMatch = line.match(/(?:APIRouter|router)\s*\(\s*(?:prefix\s*=\s*)?["'`]([^"'`]+)["'`]/)
+      || line.match(/\.include_router\s*\([^)]*prefix\s*=\s*["'`]([^"'`]+)["'`]/)
+    if (prefixMatch) {
+      routerPrefix = prefixMatch[1]
+    }
+  }
+
+  // 2. 提取 @router.method("/path") 或分散式定义
+  //    FastAPI 支持两种写法：
+  //    a) @router.get("/path", ...) 下一行 def func():
+  //    b) @router.get 下一行 ("/path", ...)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const decoratorMatch = line.match(
+      /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/
+    )
+    if (decoratorMatch) {
+      const method = decoratorMatch[1].toUpperCase()
+      const rawPath = decoratorMatch[2]
+      endpoints.push({
+        method,
+        path: routerPrefix + rawPath,
+        source: filePath,
+        line: i + 1,
+      })
+      continue
+    }
+    // 分散式: @router.get\n    ("/path",
+    const splitMatch = line.match(/@(?:router|api_router)\.(get|post|put|delete|patch)\s*$/)
+    if (splitMatch && i + 1 < lines.length) {
+      const nextLine = lines[i + 1]
+      const pathMatch = nextLine.match(/\(\s*["'`]([^"'`]+)["'`]/)
+      if (pathMatch) {
+        endpoints.push({
+          method: splitMatch[1].toUpperCase(),
+          path: routerPrefix + pathMatch[1],
+          source: filePath,
+          line: i + 1,
+        })
+      }
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从目录递归扫描所有 Python router 文件的端点
+ * @param {string} dir
+ * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function scanBackendEndpoints(dir, opts = {}) {
+  const filePattern = opts.filePattern || /(?:router|routes|api|endpoint|controller)\.py$/i
+  const excludePatterns = opts.excludePatterns || [/__pycache__/, /node_modules/, /\.venv/, /test/i]
+
+  const results = []
+  if (!existsSync(dir)) return results
+
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile() && filePattern.test(entry.name)) {
+        try {
+          results.push(...extractFastApiEndpoints(full))
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// ─── Consumer: 扫描前端 API 调用路径 ─────────────────────────────────────
+
+/**
+ * 从前端文件提取 API 调用路径
+ * 支持：
+ *   apiFetch("/api/xxx")
+ *   request("/api/xxx")
+ *   axios.get("/api/xxx")
+ *   axios.post("/api/xxx")
+ *   fetch("/api/xxx")
+ *
+ * @param {string} filePath
+ * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
+ */
+export function extractFrontendApiCalls(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const results = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Pattern 1: apiFetch<T>("/path", { method: "POST" }) — default GET
+    const apiFetchMatch = line.match(/apiFetch\s*(?:<[^>]*>)?\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (apiFetchMatch) {
+      // 检查是否有 method 字段（在后续行或同一行）
+      let method = 'GET'
+      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
+      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
+      if (methodMatch) method = methodMatch[1].toUpperCase()
+
+      results.push({
+        method,
+        path: normalizePath(apiFetchMatch[1]),
+        source: filePath,
+        line: i + 1,
+        raw: apiFetchMatch[1],
+      })
+      continue
+    }
+
+    // Pattern 2: axios.get/post/put/delete("/path")
+    const axiosMatch = line.match(/axios\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
+    if (axiosMatch) {
+      results.push({
+        method: axiosMatch[1].toUpperCase(),
+        path: normalizePath(axiosMatch[2]),
+        source: filePath,
+        line: i + 1,
+        raw: axiosMatch[2],
+      })
+      continue
+    }
+
+    // Pattern 3: fetch("/api/xxx", { method: "POST" })
+    const fetchMatch = line.match(/(?:api_?)?fetch\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (fetchMatch && !apiFetchMatch) {
+      let method = 'GET'
+      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
+      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
+      if (methodMatch) method = methodMatch[1].toUpperCase()
+
+      results.push({
+        method,
+        path: normalizePath(fetchMatch[1]),
+        source: filePath,
+        line: i + 1,
+        raw: fetchMatch[1],
+      })
+      continue
+    }
+  }
+
+  return results
+}
+
+/**
+ * 递归扫描前端目录的 API 调用
+ * @param {string} dir
+ * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
+ */
+export function scanFrontendApiCalls(dir, opts = {}) {
+  const filePattern = opts.filePattern || /\.(ts|tsx|js|jsx)$/
+  const excludePatterns = opts.excludePatterns || [/node_modules/, /\.next/, /dist/, /__tests__/, /\.d\.ts$/]
+
+  const results = []
+  if (!existsSync(dir)) return results
+
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile() && filePattern.test(entry.name)) {
+        try {
+          results.push(...extractFrontendApiCalls(full))
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// ─── 路径归一化 ─────────────────────────────────────────────────────────
+
+/**
+ * 将动态路径归一化为参数占位符
+ * /api/ppm/project-plan/${id}/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
+ * /api/ppm/project-plan/:planId/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
+ * @param {string} rawPath
+ * @returns {string}
+ */
+export function normalizePath(rawPath) {
+  return rawPath
+    .replace(/\$\{[^}]+\}/g, '{param}')
+    .replace(/:\w+/g, '{param}')
+    .replace(/\$\w+/g, '{param}')
+}
+
+// ─── 对账 ───────────────────────────────────────────────────────────────
+
+/**
+ * 比较前端调用的路径和后端注册的端点，返回差异
+ *
+ * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
+ * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
+ * @returns {{
+ *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
+ *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
+ * }}
+ */
+export function diffApiParity(frontendCalls, backendEndpoints) {
+  // 构建 backend 注册表：归一化 path + method → endpoint
+  const backendMap = new Map()
+  for (const ep of backendEndpoints) {
+    const key = `${ep.method}:${normalizePath(ep.path)}`
+    if (!backendMap.has(key)) backendMap.set(key, ep)
+  }
+
+  const missingBackend = []
+  for (const call of frontendCalls) {
+    const key = `${call.method}:${normalizePath(call.path)}`
+    if (!backendMap.has(key)) {
+      missingBackend.push({
+        path: normalizePath(call.path),
+        method: call.method,
+        consumerFile: call.source,
+        consumerLine: call.line,
+      })
+    }
+  }
+
+  // 构建 frontend 调用表
+  const frontendSet = new Set(
+    frontendCalls.map(c => `${c.method}:${normalizePath(c.path)}`)
+  )
+
+  const unusedBackend = []
+  for (const ep of backendEndpoints) {
+    const key = `${ep.method}:${normalizePath(ep.path)}`
+    if (!frontendSet.has(key)) {
+      unusedBackend.push({
+        path: normalizePath(ep.path),
+        method: ep.method,
+        providerFile: ep.source,
+      })
+    }
+  }
+
+  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
+}
+
+// ─── CLI 入口 ────────────────────────────────────────────────────────────
+
+/**
+ * CLI 子命令入口：sillyspec contract scan [--backend dir] [--frontend dir]
+ * 输出 JSON 格式的端点清单和对账结果
+ */
+export async function contractScan(args, cwd) {
+  const backendIdx = args.indexOf('--backend')
+  const frontendIdx = args.indexOf('--frontend')
+  const backendDir = backendIdx !== -1 && args[backendIdx + 1]
+    ? resolve(cwd, args[backendIdx + 1])
+    : resolve(cwd, 'backend')
+  const frontendDir = frontendIdx !== -1 && args[frontendIdx + 1]
+    ? resolve(cwd, args[frontendIdx + 1])
+    : resolve(cwd, 'frontend')
+
+  const backendEndpoints = scanBackendEndpoints(backendDir)
+  const frontendCalls = scanFrontendApiCalls(frontendDir)
+  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
+
+  return {
+    backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
+    frontend: frontendCalls.map(c => ({ method: c.method, path: normalizePath(c.path), file: c.source })),
+    missingBackend,
+    unusedBackend,
+    summary: {
+      backendEndpointCount: backendEndpoints.length,
+      frontendCallCount: frontendCalls.length,
+      missingBackendCount: missingBackend.length,
+      unusedBackendCount: unusedBackend.length,
+      ok: missingBackend.length === 0,
+    },
+  }
+}

package/src/index.js

@@ -329,7 +329,8 @@ SillySpec worktree — git worktree 隔离管理
   sillyspec worktree create <change-name> [--base <branch>]   创建隔离 worktree
   sillyspec worktree apply <change-name> [--check-only]        校验并应用变更到主工作区
   sillyspec worktree list                                      列出所有活跃 worktree
-  sillyspec worktree cleanup <change-name>                      强制清理 worktree
+  sillyspec worktree cleanup <change-name> [--force]           强制清理 worktree
+  sillyspec worktree doctor [--fix] [--stale-hours N]          健康检查 + 修复
 
 选项:
   --base <branch>       create: 指定基础分支（默认当前 HEAD）
@@ -429,11 +430,13 @@ SillySpec worktree — git worktree 隔离管理
           const forceFlag = args.includes('--force');
           try {
             const result = wm.cleanup(wtName, { force: forceFlag });
-            if (result.result === 'cleaned') {
+            if (result.result === 'cleaned' || result.result === 'force-cleaned') {
               console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
-            } else if (result.result === 'force-cleaned') {
-              console.log(`⚠️  worktree 已强制清理: ${wtName} (mode: ${result.mode})`);
-              console.log(`   原因: git worktree remove 失败，通过直接删除目录完成`);
+              if (result.details?.length > 0) {
+                for (const d of result.details) {
+                  if (d.startsWith('⚠️')) console.log(`   ${d}`);
+                }
+              }
             } else if (result.result === 'skipped') {
               console.log(`⏭️  worktree 跳过清理: ${wtName} (mode: ${result.mode})`);
               console.log(`   原因: in-place 模式没有隔离目录需要清理`);
@@ -446,6 +449,34 @@ SillySpec worktree — git worktree 隔离管理
           }
           break;
         }
+        case 'doctor': {
+          const fixFlag = args.includes('--fix');
+          const staleIdx = args.indexOf('--stale-hours');
+          const staleHours = staleIdx !== -1 && args[staleIdx + 1] ? parseInt(args[staleIdx + 1], 10) : 24;
+          const diag = wm.doctor({ fix: fixFlag, staleHours });
+          if (diag.issues.length === 0) {
+            console.log('✅ worktree 健康检查通过，无异常');
+          } else {
+            console.log(`🔍 发现 ${diag.issues.length} 个问题：\n`);
+            for (const issue of diag.issues) {
+              const icon = issue.fixable ? '⚠️' : '❌';
+              console.log(`  ${icon} [${issue.type}] ${issue.name}: ${issue.detail}`);
+            }
+            if (fixFlag) {
+              console.log(`\n🔧 修复完成：`);
+              for (const f of diag.fixed) console.log(`  ✅ ${f}`);
+              if (diag.unfixable.length > 0) {
+                for (const u of diag.unfixable) console.log(`  ❌ ${u}`);
+              }
+              if (diag.fixed.length === 0 && diag.unfixable.length === 0) {
+                console.log('  无需修复');
+              }
+            } else {
+              console.log(`\n💡 运行 sillyspec worktree doctor --fix 自动修复`);
+            }
+          }
+          break;
+        }
         default:
           console.error(`❌ 未知子命令: worktree ${wtSubCmd}`);
           console.log('   运行 sillyspec worktree --help 查看帮助');