sillyspec 3.11.7 → 3.11.9

package/src/stages/execute.js

@@ -47,6 +47,24 @@ const fixedPrefix = [
     outputHint: '上下文摘要',
     optional: false
   },
+  {
+    name: '创建 worktree',
+    prompt: `为本次执行创建隔离的 git worktree。
+
+### 操作
+1. 运行 \`sillyspec worktree create <change-name>\`
+2. 记录输出的 worktree 路径
+3. 后续所有子代理的 cwd 设为该 worktree 路径
+4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+
+### 输出
+worktree 路径 + 分支名
+
+### 完成后执行
+sillyspec run execute --done --output "worktree 路径 + 分支名"`,
+    outputHint: 'worktree 路径 + 分支名',
+    optional: false
+  },
   {
     name: '确认执行范围',
     prompt: `解析任务，确认执行范围和确认模式。
@@ -149,7 +167,7 @@ const fixedSuffix = [
     prompt: `检查本轮执行产生的新知识。
 
 ### 操作
-1. 检查 \`.sillyspec/knowledge/uncategorized.md\` 中待确认条目
+1. 检查 \.sillyspec/knowledge/uncategorized.md\` 中待确认条目
 2. 如有 → 提示用户审阅
 3. 用户确认后改为 [已确认]，可归类到专题文件
 
@@ -162,18 +180,29 @@ const fixedSuffix = [
     name: '完成确认',
     prompt: `所有任务完成后的收尾。
 
-### 操作
-1. 建议下一步：
-   - 运行 \`sillyspec run verify\` 进行验证（验证通过后才能归档）
-   - 如果发现问题需要修复，先修复再验证
-   - 用户也可以选择继续开发（不验证）
+### 操作（有 worktree）
+1. 运行 \`sillyspec worktree apply --check-only <change-name>\`
+2. 展示 diff 摘要（文件列表 + 变更统计）
+3. 检查结果说明（是否通过文件清单校验）
+4. 用户确认后运行 \`sillyspec worktree apply <change-name>\`
+5. apply 成功 → 自动 cleanup
+6. apply 失败 → 展示错误详情，用户选择重试或手动处理
+7. 如果用户不想 apply → 运行 \`sillyspec worktree cleanup <change-name>\` 丢弃
+8. 建议下一步：\`sillyspec run verify\`
+
+### 操作（无 worktree / --no-worktree 模式）
+1. 跳过 apply 和 cleanup 步骤（因为没有 worktree）
+2. 展示本次执行摘要
+3. 提示用户直接使用 \`git diff\` 查看变更
+4. 建议下一步：\`sillyspec run verify\`
 
 ### 输出
-用户选择 + 下一步命令
+apply 结果 + 下一步建议（或执行摘要）
 
 ### 注意
+- 如果用户不想 apply → 运行 cleanup 丢弃
 - 完成后运行 \`sillyspec run execute --done\` 即可自动推进阶段`,
-    outputHint: '用户选择',
+    outputHint: 'apply 结果',
     optional: false
   }
 ]
@@ -242,7 +271,7 @@ function parseWavesFromPlan(planContent) {
 /**
  * 为 Wave 生成 prompt（强制子代理执行）
  */
-function buildWavePrompt(wave, waveIndex, changeDir) {
+function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
   const taskSummary = wave.tasks.map((t, ti) => {
     const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
@@ -260,6 +289,17 @@ function buildWavePrompt(wave, waveIndex, changeDir) {
     return s
   }).join('\n')
 
+  const worktreeSection = (worktreePath)
+    ? `
+### 工作目录
+你必须在以下 worktree 中工作（子代理的 cwd 设为此路径）：
+\`${worktreePath}\`
+
+不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
+子代理的 cwd 参数设为 \`${worktreePath}\`。
+`
+    : ''
+
   return `## Wave ${waveIndex}: 执行以下任务
 
 ## 执行方式（必须严格遵守）
@@ -272,6 +312,7 @@ function buildWavePrompt(wave, waveIndex, changeDir) {
 3. 勾选 plan.md 中的 checkbox
 4. 记录改动文件和测试结果
 
+${worktreeSection}
 ### 任务摘要（按需读取完整蓝图）
 为每个任务启动子代理时，**只需告知任务目标和蓝图文件路径，让子代理按需读取**：
 
@@ -315,9 +356,11 @@ ${taskList}
 /**
  * 动态构建 execute 步骤列表
  * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave
+ * @param {{ worktreePath?: string, noWorktree?: boolean }} options
  * @returns {Array} 步骤列表
  */
-export function buildExecuteSteps(planFilePath = null) {
+export function buildExecuteSteps(planFilePath = null, options = {}) {
+  const noWorktree = !!options.noWorktree
   let waves
   let changeDir = null
 
@@ -336,10 +379,13 @@ export function buildExecuteSteps(planFilePath = null) {
     }
   }
 
+  // 尝试获取 worktree 路径（可能由前缀步骤创建）
+  const worktreePath = options.worktreePath || null
+
   const waveSteps = waves.map((wave, i) => ({
     name: `Wave ${i + 1} 执行`,
     mode: 'implementation',
-    prompt: buildWavePrompt(wave, i + 1, changeDir),
+    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath),
     outputHint: `Wave ${i + 1} 执行结果`,
     optional: false
   }))

package/src/stages/quick.js

@@ -20,7 +20,7 @@ export const definition = {
 ### 创建任务记录（必须执行）
 理解完任务后，立即创建记录文件：
 1. \`git config user.name\` 获取用户名
-2. 无 \`--change\`：创建 \.sillyspec/quicklog/QUICKLOG-<git用户名>.md\`（已存在则追加），写入：
+2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-<git用户名>.md\`（已存在则追加），写入：
    \`\`\`
    ## YYYY-MM-DD HH:mm:ss — <一句话任务描述>
    状态：进行中
@@ -28,19 +28,40 @@ export const definition = {
    \`\`\`
 3. 有 \`--change\`：在 \`.sillyspec/changes/<change-name>/tasks.md\` 追加未勾选的 task
 
-这样 Gate 检测到 \.sillyspec/\` 下有变更，就不会拦截后续的代码修改。
+这样 Gate 检测到 .sillyspec/\` 下有变更，就不会拦截后续的代码修改。
 
 ### 输出
 任务理解 + 上下文摘要 + quicklog 已创建`,
       outputHint: '任务理解',
       optional: false
     },
+    {
+      name: '创建 worktree',
+      prompt: `为本次 quick 任务创建隔离的 git worktree。
+
+### 操作
+1. 确定变更名（change name）：
+   - 如携带 \`--change <变更名>\`，使用该变更名
+   - 否则，生成临时变更名：\`quick-<当前时间戳 YYYYMMDD-HHmmss>\`
+2. 运行 \`sillyspec worktree create <变更名>\`
+3. 记录输出的 worktree 路径（后续步骤需要使用）
+4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+
+### 输出
+worktree 路径 + 变更名 + 分支名`,
+      outputHint: 'worktree 路径',
+      optional: false
+    },
     {
       name: '实现并验证',
       prompt: `实现任务。
 
+### 工作目录
+你必须在 worktree 中工作（将子代理的 cwd 设为上一步记录的 worktree 路径）。
+不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
+
 ### 操作
-1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在
+1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在（在 worktree 中读取）
 2. 写代码完成任务
 3. 如涉及逻辑变更，建议写单元测试验证（不强制，纯配置/文档/小改动可跳过）
 4. **不要编译！** 除非用户明确要求或改动量很大
@@ -55,6 +76,24 @@ export const definition = {
       outputHint: '实现摘要',
       optional: false
     },
+    {
+      name: 'apply 并 cleanup',
+      prompt: `将 worktree 中的变更应用到主工作区并清理。
+
+### 操作
+1. 运行 \`sillyspec worktree apply --check-only <变更名>\`
+2. 展示 diff 摘要（文件列表 + 变更统计）
+3. 展示检查结果（是否通过文件清单校验）
+4. 用户确认后运行 \`sillyspec worktree apply <变更名>\`
+5. apply 成功 → 自动 cleanup，进入下一步
+6. apply 失败 → 展示错误详情，用户选择重试或手动处理
+7. 如果用户不想 apply → 运行 \`sillyspec worktree cleanup <变更名>\` 丢弃变更
+
+### 输出
+apply 结果 + 下一步建议`,
+      outputHint: 'apply 结果',
+      optional: false
+    },
     {
       name: '暂存和更新记录',
       prompt: `Git 暂存并更新任务记录。

package/src/stages/scan.js

@@ -4,6 +4,38 @@ export const definition = {
   description: '分析项目结构、约定和架构',
   auxiliary: true,
   steps: [
+    {
+      name: '探测项目结构并建议子项目',
+      prompt: `扫描项目顶层目录结构，自动发现可能的子项目，**需用户确认后才创建 projects 配置**。
+
+### 操作
+1. 列出项目顶层目录：\`ls -d */ 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '.sillyspec'\`
+2. 对每个顶层目录，快速判断是否为独立项目（检查 package.json / pom.xml / build.gradle / pyproject.toml / go.mod 等构建文件）
+3. 对每个疑似独立项目，检测技术栈：\`cat <dir>/package.json 2>/dev/null | head -5\` 或类似
+4. 对比 \`.sillyspec/projects/\` 已有配置，找出未注册的子项目
+
+### 判断标准（满足任一即为子项目）
+- 有独立的构建文件（package.json, pom.xml, build.gradle, pyproject.toml 等）
+- 有独立的源码目录结构（src/, app/, lib/ 等）
+- 有独立的测试目录（test/, tests/, __tests__/ 等）
+- 不是 .git / node_modules / .sillyspec / dist / build 等工具目录
+
+### 输出格式
+列出发现的可能子项目列表，每个含：
+- 目录名
+- 技术栈（如 Next.js + TypeScript、FastAPI + Python）
+- 是否已注册到 projects/
+- 建议：注册 / 跳过
+
+### ⛔ 红线
+- **不要自动创建 projects 配置文件**，只列出建议供用户确认
+- **不要修改任何文件**，只做探测和报告
+
+### 输出
+子项目建议列表（含技术栈和注册状态）`,
+      outputHint: '子项目建议列表',
+      optional: false
+    },
     {
       name: '检查已有扫描文档和子项目列表',
       prompt: `检查已有扫描文档和子项目列表。

package/src/worktree-apply.js

@@ -0,0 +1,266 @@
+/**
+ * SillySpec applyWorktree — 将 worktree 中的变更应用到主工作区
+ *
+ * 流程：
+ * 1. 读取 meta.json 获取 baseHash
+ * 2. git diff --name-only baseHash 获取 worktree 中所有变更文件
+ * 3. 从 design.md 解析文件变更清单（无清单 = 允许所有）
+ * 4. 校验：变更文件 ⊆ 清单
+ * 5. 校验：主工作区文件 base hash 一致
+ * 6. --check-only 模式只输出检查结果
+ * 7. 非 checkOnly：生成 patch → apply --check → apply --3way
+ * 8. 成功后自动 cleanup
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+import { WorktreeManager } from './worktree.js';
+import { parseFileChangeList } from './change-list.js';
+
+const CHANGES_REL = '.sillyspec/changes';
+
+function git(cwd, args) {
+  return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function gitQuiet(cwd, args) {
+  try {
+    return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 获取文件在 git 中的 blob hash（基于某个 commit/tree）
+ * @param {string} cwd - git 工作区路径
+ * @param {string} treeish - commit hash、分支等
+ * @param {string} filePath - 相对路径
+ * @returns {string|null} blob hash，文件不存在返回 null
+ */
+function getFileBlobHash(cwd, treeish, filePath) {
+  return gitQuiet(cwd, `rev-parse ${treeish}:${filePath}`);
+}
+
+/**
+ * apply worktree 变更到主工作区
+ *
+ * @param {string} changeName - 变更名
+ * @param {{ cwd?: string, checkOnly?: boolean }} opts
+ * @returns {{
+ *   ok: boolean,
+ *   changedFiles: string[],
+ *   extraFiles: string[],
+ *   hashMismatchFiles: string[],
+ *   patchPath: string|null,
+ *   errors: string[]
+ * }}
+ */
+export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
+  const projectRoot = cwd || process.cwd();
+  const wm = new WorktreeManager({ cwd: projectRoot });
+  const meta = wm.getMeta(changeName);
+  const result = {
+    ok: false,
+    changedFiles: [],
+    extraFiles: [],
+    hashMismatchFiles: [],
+    patchPath: null,
+    errors: [],
+  };
+
+  // --- 1. 校验 worktree 存在 + meta.json 有效 ---
+  if (!meta) {
+    result.errors.push(`worktree not found: ${changeName}。meta.json 不存在或已损坏。`);
+    return result;
+  }
+
+  const { worktreePath, baseHash } = meta;
+
+  if (!existsSync(worktreePath)) {
+    result.errors.push(`worktree 目录不存在: ${worktreePath}`);
+    return result;
+  }
+
+  // --- 2. 获取变更文件列表 ---
+  // worktree 内修改可能没有 commit，用 git diff <baseHash>（比较 baseHash 到工作区内容）
+  // 同时检测 untracked 新文件（git diff 不包含 untracked）
+  let changedFiles;
+  try {
+    // tracked 文件的变更（modified/deleted）
+    const trackedRaw = git(worktreePath, `diff --name-only ${baseHash}`);
+    const trackedFiles = trackedRaw ? trackedRaw.split('\n').filter(Boolean) : [];
+
+    // untracked 新文件（baseHash 中不存在的文件）
+    const untrackedRaw = gitQuiet(worktreePath, `ls-files --others --exclude-standard`);
+    const untrackedFiles = untrackedRaw
+      ? untrackedRaw.split('\n').filter(Boolean).filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json')
+      : [];
+
+    changedFiles = [...new Set([...trackedFiles, ...untrackedFiles])];
+  } catch (e) {
+    result.errors.push(`获取变更文件列表失败: ${e.message}`);
+    return result;
+  }
+
+  result.changedFiles = changedFiles;
+
+  if (changedFiles.length === 0) {
+    // 没有变更
+    if (!checkOnly) {
+      wm.cleanup(changeName);
+    }
+    result.ok = true;
+    return result;
+  }
+
+  // --- 3. 解析 design.md 文件变更清单 ---
+  const designPath = join(projectRoot, CHANGES_REL, changeName, 'design.md');
+  const allowSet = parseFileChangeList(designPath);
+  const hasAllowList = allowSet.size > 0;
+
+  // --- 4. 校验：变更文件 ⊆ 清单（无清单则跳过）---
+  if (hasAllowList) {
+    for (const f of changedFiles) {
+      if (!allowSet.has(f)) {
+        result.extraFiles.push(f);
+      }
+    }
+    if (result.extraFiles.length > 0) {
+      result.errors.push(
+        `文件清单校验失败：以下变更文件不在 design.md 清单中：\n  ${result.extraFiles.join('\n  ')}`
+      );
+      return result;
+    }
+  }
+
+  // --- 5. 校验：主工作区文件 base hash 一致 ---
+  // 5a. 检查主工作区是否有未 commit 的脏文件（会影响 apply）
+  const mainDirtyRaw = gitQuiet(projectRoot, 'diff --name-only HEAD');
+  const mainDirtyFiles = mainDirtyRaw ? mainDirtyRaw.split('\n').filter(Boolean) : [];
+  if (mainDirtyFiles.length > 0) {
+    // 如果脏文件和本次 apply 的文件有交集 → 报错
+    const conflictDirty = mainDirtyFiles.filter(f => changedFiles.includes(f));
+    if (conflictDirty.length > 0) {
+      result.errors.push(
+        `主工作区有以下未 commit 的变更，会影响 apply：\n  ${conflictDirty.join('\n  ')}\n请先 commit 或 stash 这些变更。`
+      );
+      return result;
+    }
+  }
+
+  // 5b. 对比 worktree 的 baseHash 和主工作区 HEAD 中每个清单文件的 blob hash
+  const targetFiles = hasAllowList ? [...allowSet] : changedFiles;
+  for (const f of targetFiles) {
+    const wtBlob = getFileBlobHash(worktreePath, baseHash, f);
+    const mainBlob = getFileBlobHash(projectRoot, 'HEAD', f);
+
+    // 两者都为 null（文件在 base 时不存在）→ OK
+    if (wtBlob === null && mainBlob === null) continue;
+    // 两者一致 → OK
+    if (wtBlob === mainBlob) continue;
+    // 不一致 → 主工作区已被修改
+    result.hashMismatchFiles.push(f);
+  }
+
+  if (result.hashMismatchFiles.length > 0) {
+    result.errors.push(
+      `base hash 不一致：以下文件在主工作区已被修改：\n  ${result.hashMismatchFiles.join('\n  ')}`
+    );
+    return result;
+  }
+
+  // --- 6. checkOnly 模式：到此返回 ---
+  if (checkOnly) {
+    result.ok = true;
+    return result;
+  }
+
+  // --- 7. 生成 patch 并 apply ---
+  // 确定要包含在 patch 中的文件：有清单用清单交集，无清单用全部变更
+  const patchFiles = hasAllowList
+    ? [...allowSet].filter(f => changedFiles.includes(f))
+    : changedFiles;
+  const fileArgs = patchFiles.map(f => `-- ${f}`).join(' ');
+
+  // 创建临时文件
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-patch-'));
+  const patchPath = join(tmpDir, 'apply.patch');
+  result.patchPath = patchPath;
+
+  try {
+    let patchContent = '';
+
+    // 分 tracked 变更和 untracked 新文件生成 patch
+    const trackedFiles = patchFiles.filter(f => {
+      // untracked 文件在 baseHash 的 tree 中不存在
+      return gitQuiet(worktreePath, `cat-file -e ${baseHash}:${f}`) !== null;
+    });
+    const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
+
+    // tracked 文件：git diff baseHash
+    if (trackedFiles.length > 0) {
+      const trackedArgs = trackedFiles.map(f => `-- ${f}`).join(' ');
+      patchContent += execSync(
+        `git diff --binary ${baseHash} ${trackedArgs}`,
+        { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+    }
+
+    // untracked 新文件：git add 到 index，git diff --cached，然后 reset
+    if (untrackedPatchFiles.length > 0) {
+      const addArgs = untrackedPatchFiles.map(f => `-- ${f}`).join(' ');
+      git(worktreePath, `add ${addArgs}`);
+      try {
+        patchContent += execSync(
+          `git diff --binary --cached ${untrackedPatchFiles.map(f => `-- ${f}`).join(' ')}`,
+          { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+      } finally {
+        // 重置 index（不保留 staged 状态）
+        gitQuiet(worktreePath, `reset HEAD -- ${addArgs}`);
+      }
+    }
+
+    if (!patchContent.trim()) {
+      // patch 为空（清单中部分文件可能没实际变更）
+      result.ok = true;
+      rmSync(tmpDir, { recursive: true, force: true });
+      return result;
+    }
+
+    writeFileSync(patchPath, patchContent);
+
+    // apply --check 预检
+    try {
+      git(projectRoot, `apply --check ${patchPath}`);
+    } catch (e) {
+      result.errors.push(`patch 预检失败: ${e.message}`);
+      return result;
+    }
+
+    // apply --3way 正式应用
+    try {
+      git(projectRoot, `apply --3way ${patchPath}`);
+    } catch (e) {
+      result.errors.push(`patch apply 失败: ${e.message}`);
+      return result;
+    }
+
+    result.ok = true;
+
+    // --- 8. 成功后自动 cleanup ---
+    wm.cleanup(changeName);
+
+  } catch (e) {
+    result.errors.push(`patch 生成/应用异常: ${e.message}`);
+    return result;
+  } finally {
+    // 清理临时目录
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+  }
+
+  return result;
+}