svharness 0.15.1 → 0.15.8

package/auto/auto-harness-detail-design.md

@@ -3,8 +3,8 @@
 > **文档定位**：`svharness auto` 模式的完整设计书，面向本系统的开发者与维护者。  
 > **上级文档**：`svharnessbuild/README.md`（CLI 总体规范）、`svharnessbuild/tmp/svharnessbuild-detail-design.md`（SDD）。  
 > **参照工程**：[snarktank/ralph](https://github.com/snarktank/ralph)（外循环思路）。  
-> **版本**：v2.3（2026-06-13，依据 `design-problem2.md` 审查修订）  
-> **最后更新**：2026-06-13
+> **版本**：v2.5（2026-06-16，新增 Web 仪表盘、默认标志优化、优化容错）  
+> **最后更新**：2026-06-16
 
 ---
 
@@ -428,6 +428,17 @@ class AutoOrchestrator {
       await this.runBuildSkeleton();           // svharness build --yes
     }
 
+    // == v2.5 新增 ==
+    // 启动本地 Web 仪表盘（端口 7879），通过 SSE 实时推送构建进展
+    startDashboard(7879);
+
+    // == v2.4 修改 ==
+    // PhaseRunner 必须延迟到 ctx.harnessRoot 就绪后创建，
+    // 避免构造函数中根据初始 ctx.harnessRoot=null 创建的 PhaseRunner
+    // 持有陈旧引用，导致后续 runBuildPhases() 报"缺少 harnessRoot"。
+    // 实际代码：this.phaseRunner = new PhaseRunner(this.ctx, ...);
+    this.ensurePhaseRunnerReady();
+
     // === AGENT-2: 构建 ===
     await this.runHarnessBuild();              // 驱动 S10→S80 全流程
 
@@ -492,6 +503,11 @@ export class AcpClient {
 
 #### 策略 A：Claude Code CLI `--print` 模式（与 Ralph 一致，零额外依赖）
 
+> **v2.4 修订**：`spawnSync` → 异步 `spawn` + Promise，实时转发子进程 stdout/stderr 到终端。  
+> 原版 `spawnSync` 完全缓冲子进程输出，用户只能看到阶段标题后静默等待数分钟。  
+> 新版通过 `child.stdout.on('data')` / `child.stderr.on('data')` 实时 tee 输出，
+> 同时收集完整结果供日志和完成标记解析。
+
 ```typescript
 function parseCompletionSignals(output: string): string | undefined {
   const patterns = [
@@ -506,25 +522,42 @@ function parseCompletionSignals(output: string): string | undefined {
   return undefined;
 }
 
-function callViaCliPrint(opts: AcpCallOptions): AcpResult {
-  const result = spawnSync(
-    'claude',
-    ['--dangerously-skip-permissions', '--print'],
-    {
-      input: opts.prompt,
+async function callViaCliPrint(opts: AcpCallOptions): Promise<AcpResult> {
+  const args = ['--dangerously-skip-permissions', '--print'];
+  return new Promise((resolve) => {
+    const child = spawn('claude', args, {
       cwd: opts.workDir,
-      encoding: 'utf-8',
       timeout: opts.timeoutMs ?? 600_000,
       shell: process.platform === 'win32',
-    },
-  );
-  const output = result.stdout ?? '';
-  return {
-    success: result.status === 0,
-    output,
-    completionSignal: parseCompletionSignals(output),
-    error: result.stderr || result.error?.message,
-  };
+    });
+    let stdout = '', stderr = '', settled = false;
+
+    child.stdout.on('data', (chunk) => {    // ← 实时输出到终端
+      process.stdout.write(chunk.toString());
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {    // ← 实时输出到终端
+      process.stderr.write(chunk.toString());
+      stderr += chunk;
+    });
+
+    child.stdin.end(opts.prompt);
+
+    child.on('close', (code) => {
+      if (settled) return; settled = true;
+      const success = code === 0;
+      resolve({
+        success,
+        output: stdout,
+        completionSignal: parseCompletionSignals(stdout),
+        error: success ? undefined : stderr || `claude exit ${code}`,
+      });
+    });
+    child.on('error', (err) => {
+      if (settled) return; settled = true;
+      resolve({ success: false, output: stdout, error: err.message });
+    });
+  });
 }
 ```
 
@@ -832,9 +865,18 @@ svharness auto --yes
 | `--harness-name <name>` | 从 `--goal` 提取关键词，或从 work-dir 目录名派生 | `--harness-name` |
 | `--arch <arch>` | 有 baseline/code 时从代码文件扩展名推断；无 baseline 时自动选 `documents` | `--arch` |
 | `--agent <agent>` | 固定为 `claude-code`（auto 模式专属，不支持其他 agent） | `--agent` |
-| `--force` | 检测目标 `<name>-harness/` 目录是否存在，存在则自动加 `--force` | `--no-force` 禁用 |
+| `--force` | **默认 true**（v2.5 起）。用户可用 `--no-force` 禁用 | `--no-force` |
+
+> **v2.4 修改：`--force` 模式下 `.bak` 备份机制**（`src/core/scaffold.ts` + `src/core/build-project-entry.ts`）：
+> - **Harness 目录**：`ensureTargetAvailable()` 不再直接 `fs.remove()`，改为 `fs.move(targetRoot, targetRoot + '.bak', { overwrite: true })`，先重命名备份再重建
+> - **项目根入口文件**（CLAUDE.md/AGENTS.md）：`writeBuildProjectEntry()` 中 `force=true` 时先 `fs.copyFile(dest, dest + '.bak')` 记录旧内容，再覆盖写入新内容
+> - 无 `--force` 时零行为变化，仍保持原有跳过/报错逻辑
+>
+> **v2.5 修改**：`--force`、`--yes`、`--auto-approve` 三个标志的默认值从 `undefined` 改为 `true`（仅 `mergeAutoOptions()`），用户无需再手动传参。底层 `pickBool()` 保持优先级：CLI 显式值 > 配置文件 > 默认 true，因此 `--no-force` 仍可覆盖。
+
+| `--yes` / `--auto-approve` | **默认 true**（v2.5 起），无人值守直接通过所有确认门禁 | `--no-yes` / `--no-auto-approve` |
 
-**参数推断算法**：
+**参数推断算法**（v2.5 增强：`deriveHarnessName` 三阶段安全兜底——goal→workDir→`'harness'`，确保中文场景不抛错）：
 
 ```typescript
 interface BuildParams {
@@ -1122,6 +1164,17 @@ const PHASE_DEFS: PhaseDef[] = [
   { key: 'S80_seed_memory', mode: 'acp', promptTemplate: 'S80-seed-memory.md' },
 ];
 
+// == v2.4 新增：阶段中文描述映射，供执行前显示给用户了解当前进展 ==
+const PHASE_DESC: Record<string, string> = {
+  S10_wiki:                '生成 baseline wiki 正文',
+  S40_extract_requirements: '需求条目化与覆盖率检查',
+  S50_generate_specs:      '生成四域规格（signals/ui/behavior/interfaces）',
+  S60_process_references:   '参考资料结构化索引与注册',
+  S65_customize_agent_env:  'Agent 运行环境定制合并',
+  S70_runtime_assets:       '运行期 Skills 与 Tasks 裁剪',
+  S80_seed_memory:          'Memory 初始化播种',
+};
+
 function extractPhaseNumber(phaseName: string): number {
   const match = phaseName.match(/^S(\d+)/);
   return match ? parseInt(match[1], 10) : Infinity;
@@ -1166,6 +1219,13 @@ async runHarnessBuild(opts?: { onlyPendingOrOutdated?: boolean }) {
       await this.waitForUserConfirm(`即将执行 ${phase}，请确认后继续`);
     }
 
+    // == v2.4 修改：每个阶段执行前显示中文描述（src/lib/phase-runner.ts）==
+    // PHASE_DESC 映射：S10_wiki→生成 baseline wiki 正文；S40→需求条目化...
+    logger.info(`${phase}：${PHASE_DESC[phase] ?? phase}`);
+    if (def.promptTemplate) {
+      logger.info(`调用 Claude 执行「${def.promptTemplate}」...`);
+    }
+
     await this.runMechanicalPre(phase, def.mechanicalSteps);
 
     if (def.mode === 'mechanical' || def.mode === 'skip') continue;
@@ -1178,9 +1238,11 @@ async runHarnessBuild(opts?: { onlyPendingOrOutdated?: boolean }) {
     if (stateAfter.phases[phase]?.status !== 'DONE') {
       await this.retryPhase(phase, result);
     }
+    // == v2.4 修改：阶段完成日志增加 emoji ==
+    const label = afterStatus === 'DONE' ? '✅ 完成' : '⏭️ 跳过';
+    logger.info(`${phase} ${label}`);
     await this.runGates(phase);
     await this.runSubAgentCheck(phase);
-    logger.info(`✓ ${phase} DONE`);
   }
 }
 
@@ -2102,9 +2164,13 @@ auto:
   # 控制流
   checkpoint: null           # 设为阶段名则在该阶段前暂停
   maxPhase: null             # 调试用：只跑到此阶段
-  autoApprove: false         # true = 自动通过所有表单门禁
+  autoApprove: true          # v2.5 起默认 true，无人值守自动通过所有表单门禁
   baselineAutoExtract: explicit  # explicit | conservative | disabled（见 §6.2 S61 策略表）
 
+  # 仪表盘
+  dashboard: true            # v2.5 新增：启动本地 Web 仪表盘（端口 7879）
+  dashboardPort: 7879        # 仪表盘 HTTP 端口
+
   # 成本控制
   maxTotalCalls: 30
   budgetUsd: null            # null = 不限制
@@ -2112,7 +2178,7 @@ auto:
 
   # ACP 配置
   acpMode: auto              # auto | sdk | cli-print
-  acpTimeoutMs: 600000       # 10 分钟
+  acpTimeoutMs: 1800000      # 30 分钟（v2.4 从 10 分钟提升）
   maxRetriesPerPhase: 2      # 每阶段最大重试次数
   
   # 构建参数（同 svharness.config.yaml build 节）
@@ -2211,19 +2277,32 @@ async function main(config) {
     if (score.composite_score >= config.targetScore && score.gate_pass) {
       runFinalize(harnessRoot); break;
     }
-    runOptimizePlan(harnessRoot, config, round);       // → 第<n>轮修改-plan.md
-    runOptimizeImplement(harnessRoot, config, round);  // 按计划实施
+    // == v2.5 修改：优化实施容错 ==
+    // ACP 超时不 throw——状态重置（阶段→PENDING）比 ACP 完成更重要。
+    // 不重置状态则下次重跑仍从原评审点开始，永远无法推进。
+    try {
+      runOptimizePlan(harnessRoot, config, round);       // → 第<n>轮修改-plan.md
+      runOptimizeImplement(harnessRoot, config, round);  // 按计划实施
+    } catch (err) {
+      logger.warn(`第 ${round} 轮优化失败，状态重置已执行，下一轮继续`);
+    }
   }
 }
 
-function callClaude(workDir, prompt, config) {
-  const result = spawnSync('claude', ['--dangerously-skip-permissions', '--print'], {
-    input: prompt, cwd: workDir, encoding: 'utf-8',
-    timeout: config.acpTimeoutMs ?? 600_000,
+function callClaude(workDir, prompt, config, onData) {
+  // == v2.4 修改：spawnSync → 异步 spawn ==
+  // spawnSync 完全缓冲子进程输出，用户只能看到阶段标题后静默等待数分钟。
+  // 异步 spawn 通过 child.stdout.on('data') 实时 tee 输出到终端，
+  // 同时收集完整结果供日志和完成标记解析。
+  // == v2.5 新增：onData 回调用于仪表盘 SSE 推送 ==
+  const result = spawnPromise('claude', ['--dangerously-skip-permissions', '--print'], {
+    input: prompt, cwd: workDir,
+    timeout: config.acpTimeoutMs ?? 1_800_000,
     shell: process.platform === 'win32',
+    onData,  // → dashboardEventBus.emitAcpOutput()
   });
-  if (result.error) throw new Error(`claude CLI 调用失败: ${result.error.message}`);
-  return result.stdout;
+  // 即使超时也返回部分输出（Claude 可能已写完状态文件），不 throw
+  return result;
 }
 ```
 
@@ -2474,3 +2553,77 @@ flowchart TD
 ---
 
 *设计结束（v2.3，已吸收 design-problem2.md 全部 14 项修订）。*
+
+---
+
+## 附录：v2.4 实现修订记录（2026-06-16）
+
+根据实现反馈对详细设计的修订：
+
+| # | 文件 | 修订内容 | 类型 | 对应 § |
+|---|------|---------|------|--------|
+| 1 | `src/lib/auto-orchestrator.ts` | **PhaseRunner 延迟创建**：构造函数不再创建 PhaseRunner，改为 `run()` 方法中 ctx.harnessRoot 就绪后才创建 `new PhaseRunner(this.ctx, ...)`。修复初始 `ctx.harnessRoot=null` 时 PhaseRunner 持有陈旧引用 → 阶段执行报"缺少 harnessRoot"的 Bug | Bug 修复 | §3.3 |
+| 2 | `src/core/scaffold.ts` | **Harness 目录 .bak 备份**：`ensureTargetAvailable()` 中 `force=true` 且目标目录存在时，不再 `fs.remove()`，改为 `fs.move(targetRoot, targetRoot + '.bak', { overwrite: true })` | 增强 | §5.3.2 |
+| 3 | `src/core/build-project-entry.ts` | **CLAUDE.md .bak 备份**：`writeBuildProjectEntry()` 中 `force=true` 且文件已存在时，先 `fs.copyFile(dest, dest + '.bak')` 再覆盖写入新内容 | 增强 | §5.3.2 |
+| 4 | `src/lib/acp-client.ts` | **ACP 实时输出**：`callViaCliPrint()` 从 `spawnSync` 改为异步 `spawn` + Promise，`child.stdout.on('data')` / `child.stderr.on('data')` 实时 tee 输出到终端，同时收集完整结果供日志和完成标记解析 | 增强 | §4.3 |
+| 5 | `src/lib/phase-runner.ts` | **可见性日志**：执行每个阶段前打印中文描述（PHASE_DESC 映射）+ 提示调用的 prompt 模板名；完成后打印 emoji 标记（`✅ 完成` / `⏭️ 跳过`）；重试日志改为"准备重试第 N 次" | 增强 | §6.3 |
+
+---
+
+## 附录：v2.5 实现修订记录（2026-06-16）
+
+根据实现反馈对详细设计的修订：
+
+| # | 文件 | 修订内容 | 类型 | 对应 § |
+|---|------|---------|------|--------|
+| 1 | `src/config/merge-options.ts` | **默认标志优化**：`mergeAutoOptions()` 中 `force`、`yes`、`autoApprove` 三个 boolean 标志的默认值从 `undefined` 改为 `true`。用户无需再手动传 `--force --yes --auto-approve`。底层 `pickBool()` 保持优先级不变（CLI 显式值 > 配置文件 > 默认），因此 `--no-force` 仍可显式覆盖。仅影响 `mergeAutoOptions()`，`mergeBuildOptions()`/`mergeApplyOptions()` 不受影响 | 优化 | §9 |
+| 2 | `src/dashboard/`（新建模块） | **Web 仪表盘**：创建与 `auto/` 平级的 `src/dashboard/` 模块，解耦自动构建设仪表盘逻辑 | 新增 | §15 |
+|   | `src/dashboard/event-bus.ts` | **DashboardEventBus**：EventEmitter 单例，15 个类型化事件方法（build_started/completed、phase_started/completed/failed、acp_output、cost_updated、score_updated、review/optimize 事件） | 新增 | §15.1 |
+|   | `src/dashboard/sse-handler.ts` | **SSE 广播管理器**：维护 BuildSnapshot（总阶段数、完成数、当前阶段、状态映射、花费、评分等），通过 `text/event-stream` 实时推送事件到浏览器客户端。包含 15 秒心跳保活、自动清理断开客户端 | 新增 | §15.2 |
+|   | `src/dashboard/server.ts` | **HTTP 服务器**：Node.js 内置 `http` 模块（零外部依赖），路由 `GET /` → index.html、`GET /events` → SSE 端点、`GET /api/state` → 构建状态快照、`GET /css/*` / `GET /js/*` → 静态资源 | 新增 | §15.3 |
+|   | `src/dashboard/index.ts` | **startDashboard/stopDashboard 入口**：订阅 EventBus 所有事件转发至 SSE，启动 HTTP 服务器（默认端口 7879），自动打开浏览器，端口被占用时仅日志警告不 crash | 新增 | §15.4 |
+|   | `src/dashboard/static/` | **前端三面板页面**：深色主题仪表盘 | 新增 | §15.5 |
+|   | `src/dashboard/static/index.html` | **页面结构**：顶部状态栏 + 进度条 → 中部 SVG 流程图 → 底部详细日志面板 | 新增 | §15.5 |
+|   | `src/dashboard/static/css/styles.css` | **样式**：深色主题 CSS，SVG 节点颜色编码（灰/蓝/绿/红/黄），脉冲动画 @keyframes | 新增 | §15.5 |
+|   | `src/dashboard/static/js/app.js` | **前端逻辑**：EventSource SSE 客户端、SVG 数据流图渲染（React Flow 风格节点+箭头+状态色码）、log 面板（系统/成功/错误/ACP 输出分类），100ms 批处理渲染节流 | 新增 | §15.5 |
+| 3 | `src/types/auto-types.ts` | **AcpCallOptions.onData**：增加 `onData?: (text: string) => void` 可选回调，用于 ACP 实时 stdout 逐块推送到仪表盘 | 增强 | §4.3 |
+| 4 | `src/lib/acp-client.ts` | **onData 转发**：在 `child.stdout.on('data')` 处理器中，收集 stdout 后调用 `opts.onData?.(text)`，将 Claude 实时输出逐块推送给 EventBus → SSE → 前端日志面板 | 增强 | §4.3 |
+| 5 | `src/lib/phase-runner.ts` | **事件埋点**：引入 `dashboardEventBus`；`runPhase()` 开始处 emit `phase_started`；ACP 调用传入 `onData: (text) => dashboardEventBus.emitAcpOutput()`；完成时 emit `phase_completed`（含耗时）；失败时 emit `phase_failed` | 增强 | §6.3 |
+| 6 | `src/lib/auto-orchestrator.ts` | **事件埋点 + 优化容错**：`run()` 开始 emit `build_started`；review 循环前后 emit `review_started/completed` + `score_updated`；optimize 块 try-catch 包裹（v2.5 关键修复——ACP 超时不 throw），成功后 emit `optimize_started/completed`；最终 emit `build_completed` + `cost_updated` | Bug 修复 | §3.3 / §12 |
+| 7 | `src/lib/cost-tracker.ts` | **花费事件**：每次 `recordCall()` 末尾 emit `cost_updated`，使仪表盘实时更新花费显示 | 增强 | §9.4 |
+| 8 | `src/lib/auto-optimize.ts` | **优化实施容错**（根因修复）：`runOptimizeImplement()` 中 ACP 调用失败不再 `throw new Error()`，改为 `logger.warn("继续状态重置")`。状态重置（对应阶段→PENDING）是优化流程正确推进的关键——不做状态重置则下次重跑仍从原评审点开始，永远不能推进到 S90 | Bug 修复 | §12 |
+| 9 | `src/commands/auto.ts` | **Dashboard 集成**：`runAuto()` 中 `startDashboard(7879)` → `orchestrator.run()` → `finally { stopDashboard() }` | 集成 | §14 |
+| 10 | `package.json` | **构建脚本**：`build` 增加 `cpSync('src/dashboard/static', 'dist/dashboard/static')` 确保前端静态资源随编译产物一同发布 | 增强 | — |
+
+### v2.5 架构变更示意图
+
+```
+svharnessbuild/src/
+├── dashboard/                          ← 新增模块（与 auto/ 平级）
+│   ├── index.ts            ← startDashboard/stopDashboard
+│   ├── event-bus.ts        ← DashboardEventBus 单例
+│   ├── server.ts           ← HTTP 服务器（端口 7879）
+│   ├── sse-handler.ts      ← SSE 广播管理器
+│   └── static/             ← 前端资源（纯 HTML/CSS/JS）
+├── lib/
+│   ├── auto-orchestrator.ts  ← +事件埋点 + try-catch 优化容错
+│   ├── phase-runner.ts       ← +事件埋点 + onData 传递
+│   ├── auto-optimize.ts      ← 优化实施不 throw
+│   ├── cost-tracker.ts       ← +cost_updated 事件
+│   └── acp-client.ts         ← +onData 回调
+├── commands/
+│   └── auto.ts               ← +startDashboard/stopDashboard
+└── config/
+    └── merge-options.ts      ← force/yes/autoApprove 默认 true
+```
+
+### v2.5 事件流
+
+```
+PhaseRunner/AutoOrchestrator/CostTracker
+  → dashboardEventBus.emit*(event)
+    → SseManager.handleDashboardEvent(event)
+      → update BuildSnapshot state
+      → broadcast SSE event → 浏览器三面板自动更新
+```
+

package/bin/launch-codechat-cli.js

@@ -4,10 +4,12 @@
 const { runStartAgent } = require('../dist/lib/agent-launcher');
 
 const positionalWorkdir = process.argv[2];
+const extraArgs = process.argv.slice(3);
 
 runStartAgent({
   agent: 'codechat',
   positionalWorkdir,
+  extraArgs: extraArgs.length > 0 ? extraArgs : undefined,
 })
   .then((code) => {
     process.exitCode = code;

package/dist/commands/auto.js

@@ -6,17 +6,59 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAuto = runAuto;
 exports.resolveAutoContext = resolveAutoContext;
 const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 const config_1 = require("../config");
 const logger_1 = require("../utils/logger");
 const harness_resolver_1 = require("../lib/harness-resolver");
 const auto_orchestrator_1 = require("../lib/auto-orchestrator");
+const dashboard_1 = require("../dashboard");
+/**
+ * Prevent system sleep on Windows during long-running auto execution.
+ * Registers process-level handlers so sleep is restored on any exit path.
+ * Non-Windows platforms are a no-op.
+ */
+function preventSleepWindows() {
+    if (process.platform !== 'win32')
+        return null;
+    const restore = () => {
+        try {
+            (0, node_child_process_1.execSync)('powercfg /change standby-timeout-ac 30', { timeout: 5000 });
+            (0, node_child_process_1.execSync)('powercfg /change hibernate-timeout-ac 30', { timeout: 5000 });
+        }
+        catch { /* best-effort */ }
+    };
+    // Disable sleep
+    try {
+        (0, node_child_process_1.execSync)('powercfg /change standby-timeout-ac 0', { timeout: 5000 });
+        (0, node_child_process_1.execSync)('powercfg /change hibernate-timeout-ac 0', { timeout: 5000 });
+        console.log('💤 已禁止系统休眠，执行完成后自动恢复');
+    }
+    catch { /* powercfg not available or no permission; skip */ }
+    // Register safety net: restore on any process exit
+    process.on('exit', restore);
+    process.on('SIGINT', () => process.exit(130));
+    process.on('SIGTERM', () => process.exit(143));
+    process.on('uncaughtExceptionMonitor', restore);
+    return restore;
+}
 async function runAuto(positionalWorkdir, opts, cmd) {
     const loaded = (0, config_1.loadConfig)({ configPath: opts.config });
     const merged = (0, config_1.mergeAutoOptions)(opts, loaded?.config.auto, loaded?.config.defaults, cmd);
     const ctx = await resolveAutoContext(positionalWorkdir, merged);
     (0, logger_1.setVerbose)(ctx.verbose);
+    // Start dashboard server (non-blocking, best-effort)
+    (0, dashboard_1.startDashboard)(7879).catch(() => { });
+    // Prevent system sleep during execution; restore on any exit path
+    const restoreSleep = preventSleepWindows();
     const orchestrator = new auto_orchestrator_1.AutoOrchestrator(ctx);
-    await orchestrator.run();
+    try {
+        await orchestrator.run();
+    }
+    finally {
+        // Graceful completion: restore sleep (exit handler also covers crashes)
+        restoreSleep?.();
+        (0, dashboard_1.stopDashboard)();
+    }
 }
 async function resolveAutoContext(positionalWorkdir, opts) {
     const workDir = node_path_1.default.resolve(positionalWorkdir ?? opts.workDir ?? process.cwd());
@@ -35,7 +77,7 @@ async function resolveAutoContext(positionalWorkdir, opts) {
         budgetUsd: opts.budgetUsd ?? null,
         costAlertThreshold: normalizeNumber(opts.costAlertThreshold, 5, '--cost-alert'),
         acpMode: opts.acpMode === 'sdk' || opts.acpMode === 'cli-print' ? opts.acpMode : 'auto',
-        acpTimeoutMs: normalizeInteger(opts.acpTimeoutMs, 600_000, '--acp-timeout-ms'),
+        acpTimeoutMs: normalizeInteger(opts.acpTimeoutMs, 1_800_000, '--acp-timeout-ms'),
         maxRetriesPerPhase: normalizeInteger(opts.maxRetriesPerPhase, 2, '--max-retries-per-phase'),
         baselineAutoExtract: normalizeBaselineExtract(opts.baselineAutoExtract),
         promptDir: opts.promptDir,

package/dist/commands/shell-integration.js

@@ -117,7 +117,7 @@ try { chcp 65001 | Out-Null } catch {}
 $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
 
 Set-Location -LiteralPath $WorkDir
-& node '${escapedNodeScript}' $WorkDir
+& node '${escapedNodeScript}' "$WorkDir"
 exit $LASTEXITCODE
 `;
 }
@@ -137,7 +137,8 @@ function buildMenuCommand(ps1Path, dirPlaceholder, wtPath) {
     return `powershell.exe ${psArgs}`;
 }
 function registerMenuKey(menuKey, command, iconValue) {
-    (0, win_registry_1.regSetDefault)(menuKey, win_registry_1.SHELL_MENU_LABEL);
+    // Use PowerShell-based write for the label (Unicode-safe for Chinese chars)
+    (0, win_registry_1.regSetDefaultUnicode)(menuKey, win_registry_1.SHELL_MENU_LABEL);
     (0, win_registry_1.regSetString)(menuKey, 'Icon', iconValue);
     (0, win_registry_1.regSetDefault)(`${menuKey}\\command`, command);
 }
@@ -176,8 +177,12 @@ async function runShellInstall(opts = {}) {
  */
 async function runShellUninstall(opts = {}) {
     assertWin32();
+    // Remove svharness-managed menu
     (0, win_registry_1.regDeleteKey)(win_registry_1.SHELL_MENU_KEY_BG);
     (0, win_registry_1.regDeleteKey)(win_registry_1.SHELL_MENU_KEY_DIR);
+    // Also remove standalone script menu (Start-CodeChat.ps1 independent install)
+    (0, win_registry_1.regDeleteKey)(STANDALONE_MENU_KEY_BG);
+    (0, win_registry_1.regDeleteKey)(STANDALONE_MENU_KEY_DIR);
     if (await fs_extra_1.default.pathExists(STUB_PATH)) {
         await fs_extra_1.default.remove(STUB_PATH);
     }
@@ -187,6 +192,11 @@ async function runShellUninstall(opts = {}) {
     if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
         await fs_extra_1.default.remove(LEGACY_STUB_PATH);
     }
+    // Clean up standalone script directory (Start-CodeChat.ps1 independent install)
+    const standaloneDir = path_1.default.join(process.env.LOCALAPPDATA ?? path_1.default.join(os_1.default.homedir(), 'AppData', 'Local'), 'codechat-standalone');
+    if (await fs_extra_1.default.pathExists(standaloneDir)) {
+        await fs_extra_1.default.remove(standaloneDir);
+    }
     await (0, ps_codechat_alias_1.uninstallCodechatAlias)({ silent: opts.silent });
     logSuccess('Windows 右键菜单与 PowerShell 别名已卸载', opts.silent);
 }

package/dist/commands/start-agent.js

@@ -30,6 +30,7 @@ async function runStartAgentCommand(opts) {
         positionalWorkdir,
         syncEnv: !opts.noSyncEnv,
         skipPermissions: !opts.noSkipPermissions,
+        extraArgs: opts.extraArgs,
     });
 }
 function handleStartAgentError(err) {

package/dist/config/merge-options.js

@@ -67,14 +67,14 @@ function mergeAutoOptions(cli, configSection, defaults, cmd) {
         requirements: pickString('requirements', cli.requirements, cfg.requirements, cmd),
         references: pickString('references', cli.references, cfg.references, cmd),
         extraSkills: pickStringArray('extraSkills', cli.extraSkills, cfg.extraSkills, cmd),
-        force: pickBool('force', cli.force, cfg.force, defaults?.force, cmd),
+        force: pickBool('force', cli.force, cfg.force, true, cmd),
         targetScore: pickNumber('targetScore', cli.targetScore, cfg.targetScore, cmd),
         maxOptimizeRounds: pickNumber('maxOptimizeRounds', cli.maxOptimizeRounds, cfg.maxOptimizeRounds, cmd),
         checkpoint: pickString('checkpoint', cli.checkpoint, cfg.checkpoint ?? undefined, cmd),
         maxPhase: pickString('maxPhase', cli.maxPhase, cfg.maxPhase ?? undefined, cmd),
         dryRun: pickBool('dryRun', cli.dryRun, cfg.dryRun, undefined, cmd),
-        autoApprove: pickBool('autoApprove', cli.autoApprove, cfg.autoApprove, undefined, cmd),
-        yes: pickBool('yes', cli.yes, cfg.yes, defaults?.yes, cmd),
+        autoApprove: pickBool('autoApprove', cli.autoApprove, cfg.autoApprove, true, cmd),
+        yes: pickBool('yes', cli.yes, cfg.yes, true, cmd),
         verbose: pickBool('verbose', cli.verbose, cfg.verbose, defaults?.verbose, cmd),
         maxTotalCalls: pickNumber('maxTotalCalls', cli.maxTotalCalls, cfg.maxTotalCalls, cmd),
         budgetUsd: pickNumber('budgetUsd', cli.budgetUsd, cfg.budgetUsd ?? undefined, cmd),

package/dist/core/build-project-entry.js

@@ -87,6 +87,10 @@ async function writeBuildProjectEntry(input) {
             logger_1.logger.warn(`项目根已存在 ${rel}，跳过写入（如需覆盖请对 harness 使用 --force 并确保允许覆盖根入口文件）`);
             return undefined;
         }
+        // --force 模式下先备份现有文件为 .bak 再覆盖
+        const backupPath = dest + '.bak';
+        await fs_extra_1.default.copyFile(dest, backupPath);
+        logger_1.logger.info(`已备份 ${rel} 为 ${rel}.bak`);
     }
     const body = renderBuildProjectEntryMarkdown({
         adapter: input.adapter,

package/dist/core/scaffold.js

@@ -111,13 +111,15 @@ async function rollbackTarget(targetRoot) {
 }
 /**
  * Target directory guard. When targetRoot exists and `force` is not set, throws.
+ * When `force` is set, backs up the existing directory as `.bak` before removal.
  */
 async function ensureTargetAvailable(targetRoot, force) {
     if (!(await fs_extra_1.default.pathExists(targetRoot)))
         return;
     if (!force) {
-        throw new Error(`target directory already exists: ${targetRoot}\n  Use --force to overwrite (will delete existing content).`);
+        throw new Error(`target directory already exists: ${targetRoot}\n  Use --force to overwrite (will backup existing content as .bak).`);
     }
-    logger_1.logger.warn(`--force specified, removing existing ${targetRoot}`);
-    await fs_extra_1.default.remove(targetRoot);
+    const backupPath = targetRoot + '.bak';
+    await fs_extra_1.default.move(targetRoot, backupPath, { overwrite: true });
+    logger_1.logger.warn(`已将现有 ${node_path_1.default.basename(targetRoot)} 备份为 ${node_path_1.default.basename(backupPath)}，重新生成...`);
 }

package/dist/dashboard/event-bus.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardEventBus = exports.DashboardEventBus = void 0;
+const node_events_1 = require("node:events");
+class DashboardEventBus extends node_events_1.EventEmitter {
+    emitBuildStarted(totalPhases) {
+        this.emitEvent('build_started', { totalPhases });
+    }
+    emitBuildCompleted(finalScore) {
+        this.emitEvent('build_completed', { finalScore });
+    }
+    emitPhaseStarted(key, short, description, attempt) {
+        this.emitEvent('phase_started', { key, short, description, attempt });
+    }
+    emitPhaseCompleted(key, status, elapsedMs) {
+        this.emitEvent('phase_completed', { key, status, elapsedMs });
+    }
+    emitPhaseFailed(key, error, attempt) {
+        this.emitEvent('phase_failed', { key, error, attempt });
+    }
+    emitAcpOutput(phase, text) {
+        this.emitEvent('acp_output', { phase, text });
+    }
+    emitCostUpdated(totalCost, callCount) {
+        this.emitEvent('cost_updated', { totalCost, callCount });
+    }
+    emitScoreUpdated(score, round) {
+        this.emitEvent('score_updated', { score, round });
+    }
+    emitReviewStarted(round) {
+        this.emitEvent('review_started', { round });
+    }
+    emitReviewCompleted(round, score, criticalCount) {
+        this.emitEvent('review_completed', { round, score, criticalCount });
+    }
+    emitOptimizeStarted(round) {
+        this.emitEvent('optimize_started', { round });
+    }
+    emitOptimizeCompleted(round) {
+        this.emitEvent('optimize_completed', { round });
+    }
+    emitEvent(type, data) {
+        const event = { type, data, timestamp: Date.now() };
+        this.emit(type, event);
+    }
+}
+exports.DashboardEventBus = DashboardEventBus;
+exports.dashboardEventBus = new DashboardEventBus();

package/dist/dashboard/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDashboard = startDashboard;
+exports.stopDashboard = stopDashboard;
+const event_bus_1 = require("./event-bus");
+const server_1 = require("./server");
+const sse_handler_1 = require("./sse-handler");
+const logger_1 = require("../utils/logger");
+let server = null;
+let sseManager = null;
+/**
+ * Start the dashboard HTTP server.
+ *
+ * @param port - HTTP port (default 7879)
+ * @returns Promise that resolves when server is listening
+ */
+function startDashboard(port = 7879) {
+    return new Promise((resolve) => {
+        if (server) {
+            resolve();
+            return;
+        }
+        sseManager = new sse_handler_1.SseManager();
+        server = (0, server_1.createServer)(event_bus_1.dashboardEventBus, sseManager);
+        // Subscribe to all events from the bus and forward to SSE clients
+        const eventTypes = [
+            'build_started', 'build_completed',
+            'phase_started', 'phase_completed', 'phase_failed',
+            'acp_output',
+            'cost_updated', 'score_updated',
+            'review_started', 'review_completed',
+            'optimize_started', 'optimize_completed',
+        ];
+        for (const type of eventTypes) {
+            event_bus_1.dashboardEventBus.on(type, (event) => {
+                sseManager?.handleDashboardEvent(event);
+            });
+        }
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                logger_1.logger.warn(`[dashboard] 端口 ${port} 已被占用，跳过仪表盘`);
+            }
+            else {
+                logger_1.logger.warn(`[dashboard] 启动失败: ${err.message}`);
+            }
+            // Don't crash the build, dashboard is optional
+            server = null;
+            resolve();
+        });
+        server.listen(port, () => {
+            const url = `http://localhost:${port}`;
+            logger_1.logger.info(`[dashboard] 仪表盘已启动，请手动访问: ${url}`);
+            resolve();
+        });
+    });
+}
+/**
+ * Stop the dashboard server and clean up.
+ */
+function stopDashboard() {
+    if (sseManager) {
+        sseManager.closeAll();
+        sseManager = null;
+    }
+    if (server) {
+        server.close();
+        server = null;
+    }
+}