svharness 0.15.10 → 0.15.13

package/auto/skills/svharness/SKILL.md

@@ -169,7 +169,7 @@ svharness auto [--work-dir <path>] [options]
 | `--arch <arch>` | 架构模板 | `android-compose` |
 | `--harness-name <name>` | harness 名称（资料包模式必填） | — |
 | `--target-score <score>` | 目标综合评分 | `9.5` |
-| `--max-optimize-rounds <n>` | 最大优化轮数 | `5` |
+| `--max-optimize-rounds <n>` | 最大优化轮数 | `10` |
 | `--auto-approve` | 自动通过表单门禁 | `false` |
 | `-y, --yes` | 跳过所有交互确认 | `false` |
 | `--max-total-calls <n>` | ACP 调用次数上限 | `30` |
@@ -193,6 +193,49 @@ svharness auto --config auto.config.yaml --auto-approve
 
 **首次运行自动注入**：首次执行 `svharness auto` 时，CLI 会自动将 `svharness` skill 注入到 `~/.claude/skills/svharness/`，使 Claude Code 能识别 `/svharness` 命令。之后可在任意项目中对 Agent 说"自动构建 harness"触发。
 
+### `svharness auto_pack_req` — 需求包全自动条目化（S40 专项）
+
+独立于 `auto` 命令，专门用于需求文档条目化 + 三维度质量闭环，不污染完整 harness 构建流程。
+
+```bash
+# 推荐：在 requirements 资料目录直接运行（目录名任意）
+cd ./requirements && svharness auto_pack_req --yes
+
+svharness auto_pack_req [workdir] [options]
+```
+
+**工作目录**：无参数时默认当前目录。若当前目录本身是 requirements 资料夹（含 doc/md/pdf 等），自动视为输入并在上级目录创建 harness。
+
+**内置默认**：`targetScore=9.5`（须**严格大于**）、`maxOptimizeRounds=10`、`sampleCount=7`、`autoApprove=true`、`yes=true`
+
+**评分模型**：
+```
+综合分 = 机械门禁 × 0.40 + 对抗验证 × 0.30 + 抽样验证 × 0.30
+```
+
+| 维度 | 说明 |
+|------|------|
+| 机械门禁 | `verify --strict` + `doctor --mode requirements --strict` 全通过 |
+| 对抗验证 | 独立 Reviewer Agent 逐 block 挑刺（不读 Builder 自评） |
+| 抽样验证 | 从 `requirements/md` 随机抽 N 片段反向追溯 yaml 产物 |
+
+**两种入口**：
+- **资料包新建**：目录下无 `harness.yaml` → 创建 harness → S30+S40
+- **已有 harness 重做**：检测到 `harness.yaml` → 重置 S40=PENDING → 只跑 S40
+
+**典型用法**：
+
+```bash
+cd ./requirements && svharness auto_pack_req --yes
+svharness auto_pack_req ./req-pack --yes
+svharness auto_pack_req ./existing-harness --requirements ./docs --yes
+svharness auto_pack_req --dry-run
+```
+
+配置模板：`auto/templates/auto-pack-req.config.example.yaml`（`auto_pack_req:` 节）
+
+**产物**：`requirements/yaml/`、`auto-review/pack-req-complete.json`（不执行 S90 封存）
+
 ### `svharness shell` — Windows 右键菜单和别名管理
 
 ```bash

package/auto/templates/auto-pack-req.config.example.yaml

@@ -0,0 +1,29 @@
+version: 1
+
+defaults:
+  yes: true
+  verbose: false
+
+auto_pack_req:
+  workDir: .
+  harnessName: my-req-pack
+  goal: "描述此需求包的条目化目的"
+  arch: documents
+  agent: claude-code
+
+  requirements: ./requirements
+
+  targetScore: 9.5
+  maxOptimizeRounds: 10
+  sampleCount: 7
+  autoApprove: true
+
+  acpMode: auto
+  acpTimeoutMs: 600000
+  maxRetriesPerPhase: 2
+  maxTotalCalls: 100
+  budgetUsd: null
+  costAlertThreshold: 5
+
+  convertEndpoint: "http://markitdown.desaysz.site"
+  dryRun: false

package/auto/templates/auto.config.example.yaml

@@ -23,7 +23,7 @@ auto:
 
   # 质量目标与流程控制。
   targetScore: 9.5
-  maxOptimizeRounds: 5
+  maxOptimizeRounds: 10
   maxPhase: null
   checkpoint: null
   autoApprove: true
@@ -33,7 +33,7 @@ auto:
   acpMode: auto
   acpTimeoutMs: 600000
   maxRetriesPerPhase: 2
-  maxTotalCalls: 30
+  maxTotalCalls: 100
   budgetUsd: null
   costAlertThreshold: 5
 

package/auto/templates/phase-prompts/S40-adversarial-review.md

@@ -0,0 +1,31 @@
+你是**独立**的需求审计 Agent（未参与 S40 条目化构建）。当前任务：对 {{HARNESS_ROOT}} 执行第 {{ROUND}} 轮对抗性验证。
+
+## 硬约束（违反则任务失败）
+- **禁止读取** `auto-review/第{{ROUND}}轮需求自评报告.md` 及任何 Builder 自评内容。
+- 仅基于源文档与产物独立审查。
+
+## 项目上下文
+- 构建目的：{{AUTO_GOAL}}
+- 机械门禁：doctor exit={{DOCTOR_EXIT}}，verify exit={{VERIFY_EXIT}}
+
+## 审查方法
+1. 读取 `requirements/_work/structure-index.json`，逐 block 对照 `requirements/yaml/*.yaml`。
+2. 挑刺重点：
+   - 遗漏条目（block 无对应 requirement 且无合理 waived）
+   - `source_excerpt` 缩略或占位语（「见上文」「同前」）
+   - `description` 信息缩减（条件/数值/枚举/时序丢失）
+   - waived 条目缺少 `aggregation_reason`
+3. 读取 `{{HARNESS_ROOT}}/auto/requirements-review-rubric.yaml` 中 adversarial 维度。
+
+## 产出要求
+1. 写入 `{{HARNESS_ROOT}}/auto-review/第{{ROUND}}轮对抗评审.md`。
+2. frontmatter 必须包含：
+   - `round: {{ROUND}}`
+   - `score.adversarial.coverage`（0-10）
+   - `score.adversarial.fidelity`（0-10）
+   - `score.adversarial.completeness`（0-10）
+   - `score.adversarial.average`（三项平均，0-10）
+   - `issues`（数组，每项含 severity/category/description/unit_id 或 block_id）
+   - `critical_count`（issues 中 severity=critical 的数量）
+3. 正文列出发现的问题清单。
+4. 输出末尾：`<AUTO_SIGNAL>ADV_REVIEW_DONE</AUTO_SIGNAL>`。

package/auto/templates/phase-prompts/S40-review.md

@@ -0,0 +1,22 @@
+你是 harness 构建 Agent。当前任务：对 {{HARNESS_ROOT}} 执行第 {{ROUND}} 轮 S40 需求自评。
+
+## 项目上下文
+- 构建目的：{{AUTO_GOAL}}
+- 机械门禁：doctor exit={{DOCTOR_EXIT}}，verify exit={{VERIFY_EXIT}}，文件齐全度={{FILE_COMPLETENESS_PCT}}%
+
+## 评审契约
+1. 读取 `{{HARNESS_ROOT}}/auto/requirements-review-rubric.yaml`。
+2. 仅评审 **requirements** 维度（不评 wiki/specs/references 等）。
+3. 检查 `requirements/yaml/*.yaml`、`requirements/coverage-report.yaml`、`requirements/_work/verify-gaps.json`。
+
+## 产出要求
+1. 写入 `{{HARNESS_ROOT}}/auto-review/第{{ROUND}}轮需求自评报告.md`。
+2. frontmatter 必须包含：
+   - `round: {{ROUND}}`
+   - `score.dimensions.requirements`（0-10）
+   - `gates.doctor_exit` / `gates.verify_exit` / `gates.file_completeness_pct`
+   - `gate_pass`（布尔）
+   - `critical_count`
+   - `modifications_required`
+3. 正文必须包含「修改建议汇总」表（优先级 | 阶段 | 问题 | 建议动作），供优化 Agent 读取。
+4. 输出末尾：`<AUTO_SIGNAL>REQ_REVIEW_DONE</AUTO_SIGNAL>`。

package/auto/templates/phase-prompts/S40-sample-trace.md

@@ -0,0 +1,26 @@
+你是需求抽样验证 Agent。当前任务：对 {{HARNESS_ROOT}} 执行第 {{ROUND}} 轮反向追溯抽样验证。
+
+## 项目上下文
+- 构建目的：{{AUTO_GOAL}}
+- 抽样片段文件：{{SAMPLE_FRAGMENTS_PATH}}
+
+## 验证方法（Sample-based Reverse Trace）
+1. 读取 `{{SAMPLE_FRAGMENTS_PATH}}` 中的 `fragments[]`。
+2. 对每个片段，在 `requirements/yaml/*.yaml` 中**反向查找**对应条目。
+3. 对每个片段评三个子维度（0-10）：
+   - **traceability**：能否找到对应 `unit_id`
+   - **fidelity**：`source_excerpt` 是否覆盖片段关键信息（条件/数值/枚举/时序）
+   - **usability**：`description` + `acceptance` 是否足以支撑开发者直接实现功能
+4. 读取 `{{HARNESS_ROOT}}/auto/requirements-review-rubric.yaml` 中 sample_trace 维度。
+
+## 产出要求
+1. 写入 `{{HARNESS_ROOT}}/auto-review/第{{ROUND}}轮抽样验证报告.md`。
+2. frontmatter 必须包含：
+   - `round: {{ROUND}}`
+   - `score.sample_trace.traceability`（所有片段平均，0-10）
+   - `score.sample_trace.fidelity`（0-10）
+   - `score.sample_trace.usability`（0-10）
+   - `score.sample_trace.average`（三项平均，0-10）
+   - `score.sample_trace.items`（数组，每项含 fragment_id、found_unit_id、traceability、fidelity、usability、note）
+3. 正文含逐片段验证明细表。
+4. 输出末尾：`<AUTO_SIGNAL>SAMPLE_TRACE_DONE</AUTO_SIGNAL>`。

package/auto/templates/requirements-review-rubric.yaml

@@ -0,0 +1,79 @@
+# requirements-review-rubric.yaml — auto_pack_req 三维度评审契约
+version: "1.0"
+
+scope: requirements
+
+dimensions:
+  - id: requirements
+    weight_composite: 0.0
+    title: Builder 自评（requirements 维度）
+    role: gap_generation
+    questions:
+      - 需求文档是否充分解析？覆盖率是否 100%？
+      - source_excerpt 是否保真？有无压缩导致细节丢失？
+      - unit_id / source_anchor 是否可索引？
+    evidence_hints:
+      - requirements/coverage-report.yaml
+      - requirements/yaml/*.yaml
+      - requirements/_work/verify-gaps.json
+
+  - id: adversarial
+    weight_composite: 0.30
+    title: 对抗性验证
+    role: scoring
+    questions:
+      - 逐 block 对照 structure-index，是否有遗漏条目？
+      - source_excerpt 是否缩略或使用占位语？
+      - description 是否缩减了条件/数值/枚举/时序？
+      - waived 条目是否有 aggregation_reason？
+    sub_scores:
+      - coverage
+      - fidelity
+      - completeness
+    evidence_hints:
+      - requirements/_work/structure-index.json
+      - requirements/yaml/*.yaml
+
+  - id: sample_trace
+    weight_composite: 0.30
+    title: 抽样反向追溯验证
+    role: scoring
+    questions:
+      - 随机源文档片段能否在 yaml 中找到 unit_id？
+      - source_excerpt 是否覆盖片段关键信息？
+      - description + acceptance 是否足以支撑功能开发？
+    sub_scores:
+      - traceability
+      - fidelity
+      - usability
+    evidence_hints:
+      - auto-review/sample-fragments.json
+      - requirements/md/*.md
+      - requirements/yaml/*.yaml
+
+mechanical_gate:
+  weight_composite: 0.40
+  checks:
+    - svharness requirements verify --strict exit 0
+    - svharness doctor --mode requirements --strict exit 0
+    - coverage_ratio == 1
+    - critical_count == 0
+
+pass_criteria:
+  composite_score_gt: 9.5
+  gate_pass: true
+  critical_count: 0
+
+modification_summary_columns:
+  - priority
+  - phase
+  - problem
+  - action
+  - status
+
+outputs:
+  self_review: "auto-review/第{n}轮需求自评报告.md"
+  adversarial: "auto-review/第{n}轮对抗评审.md"
+  sample_trace: "auto-review/第{n}轮抽样验证报告.md"
+  score_snapshot: auto-review/auto-score.json
+  complete_marker: auto-review/pack-req-complete.json

package/dist/commands/auto-pack-req.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAutoPackReq = runAutoPackReq;
+const node_path_1 = __importDefault(require("node:path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const config_1 = require("../config");
+const logger_1 = require("../utils/logger");
+const auto_state_1 = require("../lib/auto-state");
+const auto_pack_req_context_1 = require("../lib/auto-pack-req-context");
+const auto_1 = require("./auto");
+const PACK_REQ_DEFAULTS = {
+    scope: 'requirements',
+    targetScore: 9.5,
+    maxOptimizeRounds: 10,
+    autoApprove: true,
+    yes: true,
+    sampleCount: 7,
+};
+async function runAutoPackReq(positionalWorkdir, opts, cmd) {
+    const loaded = (0, config_1.loadConfig)({ configPath: opts.config });
+    const autoSection = loaded?.config.auto_pack_req ?? loaded?.config.auto;
+    const merged = {
+        ...(0, config_1.mergeAutoOptions)(opts, autoSection, loaded?.config.defaults, cmd),
+        ...PACK_REQ_DEFAULTS,
+        ...opts,
+        scope: 'requirements',
+        targetScore: opts.targetScore ?? autoSection?.targetScore ?? PACK_REQ_DEFAULTS.targetScore,
+        maxOptimizeRounds: opts.maxOptimizeRounds ?? autoSection?.maxOptimizeRounds ?? PACK_REQ_DEFAULTS.maxOptimizeRounds,
+        sampleCount: opts.sampleCount ?? autoSection?.sampleCount ?? 7,
+        autoApprove: opts.autoApprove ?? true,
+        yes: opts.yes ?? true,
+    };
+    const workCtx = await (0, auto_pack_req_context_1.resolveAutoPackReqWorkContext)(positionalWorkdir, merged.workDir, merged.requirements);
+    const runOpts = {
+        ...merged,
+        ...(workCtx.requirementsPath ? { requirements: workCtx.requirementsPath } : {}),
+    };
+    if (workCtx.harnessRoot) {
+        logger_1.logger.info(`[auto_pack_req] 检测到已有 harness：${workCtx.harnessRoot}，将重做 S40`);
+        await resetS40ForRerun(workCtx.harnessRoot);
+    }
+    else if (workCtx.mode === 'requirements-cwd') {
+        logger_1.logger.info(`[auto_pack_req] 当前目录识别为 requirements 输入：${workCtx.requirementsPath}`);
+        logger_1.logger.info(`[auto_pack_req] 将在上级目录创建 harness：${workCtx.workDir}`);
+    }
+    else {
+        logger_1.logger.info('[auto_pack_req] 资料包模式：将创建 harness 并执行 S30+S40');
+    }
+    await (0, auto_1.runAuto)(workCtx.workDir, runOpts, cmd);
+}
+async function resetS40ForRerun(harnessRoot) {
+    const statePath = node_path_1.default.join(harnessRoot, '.harness-build-state.yaml');
+    if (!(await fs_extra_1.default.pathExists(statePath)))
+        return;
+    const state = await (0, auto_state_1.readBuildState)(harnessRoot);
+    if (!state.phases.S40_extract_requirements)
+        return;
+    state.phases.S40_extract_requirements = {
+        ...state.phases.S40_extract_requirements,
+        status: 'PENDING',
+    };
+    delete state.phases.S40_extract_requirements.outdated_reason;
+    state.current_phase = 'S40_extract_requirements';
+    state.next_action = 'auto_pack_req 已重置 S40，等待重新条目化';
+    await (0, auto_state_1.writeBuildState)(harnessRoot, state);
+    logger_1.logger.success('已重置 S40_extract_requirements 为 PENDING');
+}

package/dist/commands/auto.js

@@ -12,6 +12,7 @@ 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");
+const acp_agent_cli_resolver_1 = require("../lib/acp-agent-cli-resolver");
 /**
  * Prevent system sleep on Windows during long-running auto execution.
  * Registers process-level handlers so sleep is restored on any exit path.
@@ -46,6 +47,13 @@ async function runAuto(positionalWorkdir, opts, cmd) {
     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);
+    if (!ctx.dryRun) {
+        logger_1.logger.section('[auto] 启动前检查：Agent CLI');
+        if (!ctx.acpAgentCli) {
+            throw new Error('内部错误：ACP Agent CLI 未解析');
+        }
+        logger_1.logger.success(`已找到 Agent CLI → ${(0, acp_agent_cli_resolver_1.formatAcpAgentCliLog)(ctx.acpAgentCli)}`);
+    }
     // Start dashboard server (non-blocking, best-effort)
     (0, dashboard_1.startDashboard)(7879).catch(() => { });
     // Prevent system sleep during execution; restore on any exit path
@@ -63,28 +71,33 @@ async function runAuto(positionalWorkdir, opts, cmd) {
 async function resolveAutoContext(positionalWorkdir, opts) {
     const workDir = node_path_1.default.resolve(positionalWorkdir ?? opts.workDir ?? process.cwd());
     const harnessRoot = await (0, harness_resolver_1.resolveHarnessRoot)(workDir);
+    const acpAgentCli = opts.dryRun ? null : (0, acp_agent_cli_resolver_1.ensureAcpAgentCliAvailable)();
     return {
         workDir,
         harnessRoot,
         harnessExists: !!harnessRoot,
+        acpAgentCli,
         targetScore: normalizeNumber(opts.targetScore, 9.5, '--target-score'),
-        maxOptimizeRounds: normalizeInteger(opts.maxOptimizeRounds, 5, '--max-optimize-rounds'),
+        maxOptimizeRounds: normalizeInteger(opts.maxOptimizeRounds, 10, '--max-optimize-rounds'),
         dryRun: !!opts.dryRun,
         autoApprove: !!opts.autoApprove,
         yes: !!opts.yes,
         verbose: !!opts.verbose,
-        maxTotalCalls: normalizeInteger(opts.maxTotalCalls, 30, '--max-total-calls'),
+        maxTotalCalls: normalizeInteger(opts.maxTotalCalls, 100, '--max-total-calls'),
         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, 1_800_000, '--acp-timeout-ms'),
         maxRetriesPerPhase: normalizeInteger(opts.maxRetriesPerPhase, 2, '--max-retries-per-phase'),
         baselineAutoExtract: normalizeBaselineExtract(opts.baselineAutoExtract),
+        scope: normalizeScope(opts.scope),
+        sampleCount: normalizeInteger(opts.sampleCount, 7, '--sample-count'),
         promptDir: opts.promptDir,
         checkpoint: opts.checkpoint,
         maxPhase: opts.maxPhase,
         goal: opts.goal,
         buildOverrides: opts,
+        autoRepair: opts.autoRepair ?? true,
     };
 }
 function normalizeNumber(value, fallback, name) {
@@ -106,3 +119,6 @@ function normalizeBaselineExtract(value) {
     }
     return 'conservative';
 }
+function normalizeScope(value) {
+    return value === 'requirements' ? 'requirements' : 'full';
+}

package/dist/commands/convert.js

@@ -182,6 +182,8 @@ async function runConvert(opts) {
         catch (err) {
             const e = err;
             logger_1.logger.error(`markitdown_serve unreachable at ${v.endpoint}: ${e.message}`);
+            logger_1.logger.plain('  - if another user is converting a large PDF, the service may still be busy; retry in a minute');
+            logger_1.logger.plain('  - production should run uvicorn with --workers 4+ and nginx proxy_read_timeout ≥ 900s');
             logger_1.logger.plain('');
             logger_1.logger.plain('  - confirm the service is deployed and reachable from this machine');
             logger_1.logger.plain('  - pass --endpoint <url> or comma-separated URLs for failover');

package/dist/commands/shell-integration.js

@@ -3,7 +3,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveLaunchScriptPath = void 0;
 exports.resolveShellMenuIconSourcePath = resolveShellMenuIconSourcePath;
 exports.installShellMenuIcon = installShellMenuIcon;
 exports.resolveWindowsTerminalPath = resolveWindowsTerminalPath;
@@ -19,11 +18,8 @@ const child_process_1 = require("child_process");
 const logger_1 = require("../utils/logger");
 const win_registry_1 = require("../lib/win-registry");
 const ps_codechat_alias_1 = require("../lib/ps-codechat-alias");
-const launch_script_path_1 = require("../lib/launch-script-path");
-Object.defineProperty(exports, "resolveLaunchScriptPath", { enumerable: true, get: function () { return launch_script_path_1.resolveLaunchScriptPath; } });
 const STUB_DIR = path_1.default.join(process.env.LOCALAPPDATA ?? path_1.default.join(os_1.default.homedir(), 'AppData', 'Local'), 'svharness', 'bin');
-const STUB_PATH = path_1.default.join(STUB_DIR, 'launch_codechat_cli.ps1');
-const LEGACY_STUB_PATH = path_1.default.join(STUB_DIR, 'launch_codechat_cli.cmd');
+const PS1_INSTALL_PATH = path_1.default.join(STUB_DIR, 'Start-CodeChat.ps1');
 const ICON_FILENAME = 'codechat-agent.ico';
 const ICON_STUB_PATH = path_1.default.join(STUB_DIR, ICON_FILENAME);
 const STANDALONE_MENU_KEY_BG = 'HKCU\\Software\\Classes\\Directory\\Background\\shell\\CodeChatStandaloneAgent';
@@ -102,31 +98,24 @@ function resolveWindowsTerminalPath() {
     }
     return null;
 }
-function buildStubContent(launchScriptPath) {
-    const escapedNodeScript = launchScriptPath.replace(/'/g, "''");
-    // ASCII-only + UTF-8 BOM. Legacy conhost fallback sets UTF-8 before CodeChat TUI.
-    return `param(
-  [string]$WorkDir = (Get-Location).Path
-)
-
-$ErrorActionPreference = 'Stop'
-
-try { chcp 65001 | Out-Null } catch {}
-[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
-[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
-$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
-
-Set-Location -LiteralPath $WorkDir
-& node '${escapedNodeScript}' "$WorkDir"
-exit $LASTEXITCODE
-`;
-}
-function writeStubFile(launchScriptPath) {
-    const content = buildStubContent(launchScriptPath);
-    return fs_extra_1.default.writeFile(STUB_PATH, `\uFEFF${content}`, 'utf8');
-}
 function buildPsInvokeArgs(ps1Path, dirPlaceholder) {
-    return `-NoExit -NoProfile -ExecutionPolicy Bypass -File "${ps1Path}" ${dirPlaceholder}`;
+    return `-NoExit -NoProfile -ExecutionPolicy Bypass -File "${ps1Path}" -Action Start -WorkDir ${dirPlaceholder}`;
+}
+async function installStartCodeChatPs1() {
+    const fromDist = path_1.default.resolve(__dirname, '..', '..', 'templates', 'codechat', 'Start-CodeChat.ps1');
+    const fromCwd = path_1.default.resolve(__dirname, '..', '..', '..', 'templates', 'codechat', 'Start-CodeChat.ps1');
+    let source = '';
+    if (fs_extra_1.default.existsSync(fromDist)) {
+        source = fromDist;
+    }
+    else if (fs_extra_1.default.existsSync(fromCwd)) {
+        source = fromCwd;
+    }
+    else {
+        throw new Error(`\u672A\u627E\u5230 Start-CodeChat.ps1\uFF08\u9884\u671F\uFF1A${fromDist}\uFF09`);
+    }
+    await fs_extra_1.default.copy(source, PS1_INSTALL_PATH, { overwrite: true });
+    return PS1_INSTALL_PATH;
 }
 function buildMenuCommand(ps1Path, dirPlaceholder, wtPath) {
     const psArgs = buildPsInvokeArgs(ps1Path, dirPlaceholder);
@@ -150,23 +139,18 @@ async function runShellInstall(opts = {}) {
     // Avoid duplicate menu entries: overwrite standalone menu if present.
     (0, win_registry_1.regDeleteKey)(STANDALONE_MENU_KEY_BG);
     (0, win_registry_1.regDeleteKey)(STANDALONE_MENU_KEY_DIR);
-    const launchScriptPath = (0, launch_script_path_1.resolveLaunchScriptPath)();
     await fs_extra_1.default.ensureDir(STUB_DIR);
-    await writeStubFile(launchScriptPath);
-    if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
-        await fs_extra_1.default.remove(LEGACY_STUB_PATH);
-    }
+    const ps1Path = await installStartCodeChatPs1();
     const iconValue = await installShellMenuIcon();
     const wtPath = resolveWindowsTerminalPath();
-    const bgCommand = buildMenuCommand(STUB_PATH, '"%V"', wtPath);
-    const dirCommand = buildMenuCommand(STUB_PATH, '"%1"', wtPath);
+    const bgCommand = buildMenuCommand(PS1_INSTALL_PATH, '"%V"', wtPath);
+    const dirCommand = buildMenuCommand(PS1_INSTALL_PATH, '"%1"', wtPath);
     registerMenuKey(win_registry_1.SHELL_MENU_KEY_BG, bgCommand, iconValue);
     registerMenuKey(win_registry_1.SHELL_MENU_KEY_DIR, dirCommand, iconValue);
     const via = wtPath ? 'Windows Terminal' : 'PowerShell（UTF-8）';
     logSuccess(`Windows 右键菜单已注册：「在此启动 CodeChat Agent」（${via}）`, opts.silent);
-    logInfo(`  stub: ${STUB_PATH}`, opts.silent);
+    logInfo(`  脚本: ${ps1Path}`, opts.silent);
     logInfo(`  icon: ${ICON_STUB_PATH}`, opts.silent);
-    logInfo(`  脚本: ${launchScriptPath}`, opts.silent);
     if (wtPath) {
         logInfo(`  wt:   ${wtPath}`, opts.silent);
     }
@@ -183,15 +167,12 @@ async function runShellUninstall(opts = {}) {
     // 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);
+    if (await fs_extra_1.default.pathExists(PS1_INSTALL_PATH)) {
+        await fs_extra_1.default.remove(PS1_INSTALL_PATH);
     }
     if (await fs_extra_1.default.pathExists(ICON_STUB_PATH)) {
         await fs_extra_1.default.remove(ICON_STUB_PATH);
     }
-    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)) {
@@ -205,24 +186,17 @@ async function runShellUninstall(opts = {}) {
  */
 function getShellStatus() {
     assertWin32();
-    let launchScriptPath = '';
-    try {
-        launchScriptPath = (0, launch_script_path_1.resolveLaunchScriptPath)();
-    }
-    catch {
-        launchScriptPath = '(未找到)';
-    }
+    const ps1Installed = fs_extra_1.default.existsSync(PS1_INSTALL_PATH);
     const backgroundMenu = (0, win_registry_1.regKeyExists)(win_registry_1.SHELL_MENU_KEY_BG);
     const directoryMenu = (0, win_registry_1.regKeyExists)(win_registry_1.SHELL_MENU_KEY_DIR);
-    const stubExists = fs_extra_1.default.existsSync(STUB_PATH);
     const wtPath = resolveWindowsTerminalPath();
     const aliasStatus = (0, ps_codechat_alias_1.getCodechatAliasStatus)();
     return {
-        installed: backgroundMenu && directoryMenu && stubExists,
-        stubPath: STUB_PATH,
+        installed: backgroundMenu && directoryMenu && ps1Installed,
+        stubPath: PS1_INSTALL_PATH,
         backgroundMenu,
         directoryMenu,
-        launchScriptPath,
+        launchScriptPath: PS1_INSTALL_PATH,
         viaWindowsTerminal: wtPath !== null,
         aliasInstalled: aliasStatus.installed,
         profilePath: aliasStatus.profilePath,
@@ -232,10 +206,9 @@ function printShellStatus() {
     const status = getShellStatus();
     logger_1.logger.section('Windows shell 集成状态');
     logger_1.logger.plain(`  右键菜单完整: ${status.installed ? '是' : '否'}`);
-    logger_1.logger.plain(`  stub 路径:     ${status.stubPath}`);
+    logger_1.logger.plain(`  Start-CodeChat.ps1: ${status.stubPath}`);
     logger_1.logger.plain(`  空白处菜单:    ${status.backgroundMenu ? '已注册' : '未注册'}`);
     logger_1.logger.plain(`  文件夹菜单:    ${status.directoryMenu ? '已注册' : '未注册'}`);
-    logger_1.logger.plain(`  启动脚本:      ${status.launchScriptPath}`);
     logger_1.logger.plain(`  经 WT 启动:    ${status.viaWindowsTerminal ? '是（install 时检测到 wt.exe）' : '否'}`);
     logger_1.logger.plain(`  codechat 别名: ${status.aliasInstalled ? '已安装' : '未安装'}`);
     logger_1.logger.plain(`  profile 路径:  ${status.profilePath}`);

package/dist/config/merge-options.js

@@ -85,6 +85,8 @@ function mergeAutoOptions(cli, configSection, defaults, cmd) {
         promptDir: pickString('promptDir', cli.promptDir, cfg.promptDir, cmd),
         baselineAutoExtract: pickString('baselineAutoExtract', cli.baselineAutoExtract, cfg.baselineAutoExtract, cmd),
         convertEndpoint: pickString('convertEndpoint', cli.convertEndpoint, cfg.convertEndpoint, cmd),
+        scope: pickString('scope', cli.scope, cfg.scope, cmd),
+        sampleCount: pickNumber('sampleCount', cli.sampleCount, cfg.sampleCount, cmd),
     };
 }
 function mergeBuildOptions(cli, configSection, defaults, cmd) {

package/dist/config/normalize.js

@@ -50,6 +50,7 @@ function pickAutoSection(raw) {
         'costAlertThreshold',
         'acpTimeoutMs',
         'maxRetriesPerPhase',
+        'sampleCount',
     ]) {
         if (raw[k] !== undefined && raw[k] !== null) {
             s[k] = Number(raw[k]);
@@ -235,5 +236,11 @@ function normalizeConfig(raw, configPath) {
         }
         cfg.auto = pickAutoSection(raw.auto);
     }
+    if (raw.auto_pack_req !== undefined) {
+        if (!isPlainObject(raw.auto_pack_req)) {
+            throw new Error(`配置 auto_pack_req 必须是对象：${configPath}`);
+        }
+        cfg.auto_pack_req = pickAutoSection(raw.auto_pack_req);
+    }
     return cfg;
 }

package/dist/constants/convert.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONVERT_TIMEOUT_SEC = void 0;
+/** Default per-file convert HTTP timeout: 15 minutes. */
+exports.DEFAULT_CONVERT_TIMEOUT_SEC = 900;

package/dist/core/markitdown-client.js

@@ -57,7 +57,7 @@ function parseEndpointList(raw) {
     }
     return out;
 }
-async function ping(endpoint, timeoutMs = 10_000) {
+async function ping(endpoint, timeoutMs = 30_000) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -80,7 +80,7 @@ async function ping(endpoint, timeoutMs = 10_000) {
     }
 }
 /** Probe endpoints in order; return those that respond to /healthz. */
-async function filterHealthyEndpoints(endpoints, timeoutMs = 10_000) {
+async function filterHealthyEndpoints(endpoints, timeoutMs = 30_000) {
     const healthy = [];
     for (const endpoint of endpoints) {
         try {
@@ -186,6 +186,11 @@ function extractTraceId(body) {
 }
 function describeHttpError(status, body, endpoint) {
     const prefix = endpoint ? `[${endpoint}] ` : '';
+    if (status === 504) {
+        return (`${prefix}gateway timeout (HTTP 504): reverse proxy gave up waiting for markitdown_serve ` +
+            `(worker may still be running VLM/OCR). Increase nginx proxy_read_timeout to match ` +
+            `--timeout-sec, or reduce MARKITDOWN_OCR_MAX_RENDER_PX / use a shorter PDF export.`);
+    }
     if (body && typeof body === 'object') {
         const b = body;
         if (status === 415 && b.error === 'unsupported_format') {

package/dist/dashboard/event-bus.js

@@ -9,6 +9,9 @@ class DashboardEventBus extends node_events_1.EventEmitter {
     emitBuildCompleted(finalScore) {
         this.emitEvent('build_completed', { finalScore });
     }
+    emitBuildFailed(finalScore) {
+        this.emitEvent('build_failed', { finalScore });
+    }
     emitPhaseStarted(key, short, description, attempt) {
         this.emitEvent('phase_started', { key, short, description, attempt });
     }

package/dist/dashboard/index.js

@@ -24,7 +24,7 @@ function startDashboard(port = 7879) {
         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',
+            'build_started', 'build_completed', 'build_failed',
             'phase_started', 'phase_completed', 'phase_failed',
             'acp_output',
             'cost_updated', 'score_updated',