svharness 0.14.8 → 0.14.11

package/README.md

@@ -40,6 +40,10 @@ svharness build --harness-name my-app --arch android-compose --agent qoder --yes
 
 # 把构建完成的 harness 应用到其它项目（绑定式，不拷贝）
 svharness apply --harness ./my-app-harness --target ../other-project --yes
+
+# build 完成后启动 CodeChat Agent 填充 harness（当前目录）
+svharness start-agent --work-dir .
+# 或全局快捷命令: launch_codechat_cli
 ```
 
 ### 配置文件与向导（v0.10+）
@@ -179,7 +183,7 @@ harness-build-{skill|rule}-<semantic-name>
 
 ### 构建阶段
 
-`build` 只生成骨架。各阶段的**实际内容**由 Agent 借助注入的 skill 逐步填充：
+`build` 生成目录骨架，并在 **S00** 预置默认 `tasks/templates/`；其余各阶段的**项目相关内容**由 Agent 借助注入的 skill 逐步填充：
 
 | 阶段 | 动作 | 产物 |
 |------|------|------|
@@ -191,17 +195,15 @@ harness-build-{skill|rule}-<semantic-name>
 | **S60_process_references** | references 处理（`svharness convert` + 结构化索引 + 用户确认落地） | `references/md/` |
 | **S61_confirm_baseline_extraction** | 确认是否自动从 baseline 提取 skills/rules（表单确认） | `.harness-build-state.yaml`（`phases.S61_confirm_baseline_extraction.baseline_auto_extract`） |
 | **S65_customize_agent_env** | agent-env 定制（extra-skills/extra-rules 冲突建议与重命名建议 → 用户确认 → 写入） | `agent-env/rules/` + `agent-env/skills/` |
-| **S70_runtime_assets** | 运行期 Skills & tasks 索引（skill 执行 task） | `agent-env/skills/` + `tasks/templates/` |
+| **S70_runtime_assets** | 运行期 Skills 定制 + tasks 模板按项目裁剪/增补（build 已预置默认模板） | `agent-env/skills/` + `tasks/templates/` |
 | **S80_seed_memory** | Memory 初始化 | `agent-env/memory/categories/` |
 | **S85_pre_seal_validation** | 封存前校验 | `svharness doctor` + 全面审查报告 |
 | **S90_finalize** | 封板 | 版本 bump + CHANGELOG + `bootstrap_mode: false` |
 
 > 反复调用 orchestrator 总是从"第一个非 DONE 的阶段"继续。
 > **S10_wiki 仅在有 baseline 时出现；无 baseline 则不构建 wiki，流程从 S20_collect_inputs 开始。**
-> **S20_collect_inputs 必须等待用户放入需求文档，且需显式征询 references 与额外运行期资源输入（`--extra-skills`，可混放 skills/rules）；Agent 不得自行生成占位文件。若 build 传入了 `--requirements/--references`，CLI 会在拷贝到 raw 后自动尝试 convert 到 md。**
-> **S60_process_references 专注 references：必须执行 `svharness convert`，并产出结构化索引（规制约束 / skills 候选 / signals / manuals），经表单确认后再进入后续阶段。**
-> **S61_confirm_baseline_extraction 必须显式确认是否启用 baseline 自动提取 skills/rules；未经确认不得在 S65 自动提取。**
-> **S65_customize_agent_env 专注 extra-skills/extra-rules：来源可来自 `--extra-skills` 导入后的 `_incoming/manifest.yaml`，先冲突识别与重命名建议，再表单确认写入；推荐命名：`harness-apply-skills-<topic>` 与 `harness-apply-rules-<topic>.md/.mdc`。**
+> **S20_collect_inputs**：`requirements/raw/` 须有真实文档。未传 `--references` / `--extra-skills` 时 CLI 预声明 `input_declarations` 并可能预 DONE S20（当 `--requirements` 已注入）；Agent 不得再对已为 `none` 的可选项弹表单。`--strict-input-confirm` 可恢复旧行为。
+> **S60/S61/S65/S80**：未提供对应可选输入时，build 可预标记 `source: cli-default`、`outcome: none` 并 DONE；增量添加时说「reopen S60」等。S61 默认 `baseline_auto_extract: DISABLED`；需提取时传 `--enable-baseline-extract`。
 > **S40/S50/S85 的 DONE 都带覆盖率门禁：未闭环 gap（或未备案 waiver）不得推进。**
 
 ---
@@ -276,13 +278,15 @@ svharness build \
 | `--baseline-branch <name>` | 可选 | git 基线的分支名（仅 git 模式有效） | `main` |
 | `--baseline-max-file-kb <kb>` | 可选 | 基线拷贝单文件大小上限（KB） | `1024` |
 | `--repomix` | 可选 flag | 将 `baseline/code` 打成**单文件** Repomix XML；**须同时提供 `--baseline`**。适用场景见下文 [Repomix](#repomix-repomix) | `false` |
-| `--convert-endpoint <url>` | 可选 | build 自动 convert 使用的 markitdown 服务基址；省略时读环境变量 `SVHARNESS_MARKITDOWN_ENDPOINT` | `http://markitdown.desaysz.site` |
+| `--convert-endpoint <url>` | 可选 | build 自动 convert 使用的 markitdown 服务基址（支持逗号分隔 failover）；省略时读 `SVHARNESS_MARKITDOWN_ENDPOINT` | `http://markitdown.desaysz.site` |
 | `--convert-concurrency <n>` | 可选 | build 自动 convert 并发上传数 | `3` |
 | `--convert-max-file-mb <n>` | 可选 | build 自动 convert 单文件大小上限（MB） | `50` |
 | `--convert-timeout-sec <n>` | 可选 | build 自动 convert 请求超时秒数 | `120` |
 | `--convert-force` | 可选 flag | build 自动 convert 覆盖同名 `.md`（否则按 `-1/-2` 追加） | `false` |
 | `--force` | 可选 flag | 覆写已存在的 harness 目录；同时允许覆盖已注入的 build skills/rules 与项目根 `AGENTS.md` / `CLAUDE.md`（默认遇到已存在文件会跳过） | `false` |
 | `-y, --yes` | 可选 flag | 跳过所有提示，采用默认值 | `false` |
+| `--enable-baseline-extract` | 可选 flag | 启用 baseline 自动提取 skills/rules（S61 ENABLED） | `false` |
+| `--strict-input-confirm` | 可选 flag | 禁用 CLI 预声明，恢复 S60/S61/S65 等 Agent 表单确认 | `false` |
 | `--verbose` | 可选 flag | 打印每个生成文件 | `false` |
 
 #### Wiki 参数
@@ -446,7 +450,7 @@ svharness doctor --harness ./my-app-harness --mode pre-seal --format json --repo
 | 选项 | 说明 |
 |------|------|
 | `--harness` | harness 根目录（必填；可写在 `svharness.config.yaml` 的 `doctor.harness`） |
-| `--mode` | `pre-seal`（默认）或 `health` |
+| `--mode` | `pre-seal`（默认）、`health` 或 **`requirements`**（S40 专用） |
 | `--format` | `text`（默认）或 `json` |
 | `--report` | JSON 报告路径（默认 `<harness>/doctor-report.json`） |
 | `--strict` | 将 warning 视为 error |
@@ -459,15 +463,34 @@ svharness doctor --harness ./my-app-harness --mode pre-seal --format json --repo
 - **Part B**：按 `specs.layers` 与 `agent-env/review-profiles/<arch>.yaml` 做深度评分
 - **门禁**：`overall_score >= 5.0`（C 级）、`critical_count == 0`、报告 frontmatter `gate_pass: true`、用户表单确认
 
-`doctor` 另含 `check-review-report`（warning）：S85 已 DONE 时校验报告 frontmatter 与 state 中 `review_gate_pass` 一致。数量覆盖率阻断仍由 S40/S50 表单门禁负责。
+`doctor` 另含 `check-review-report`（warning）：S85 已 DONE 时校验报告 frontmatter 与 state 中 `review_gate_pass` 一致。**S40 数量/结构覆盖率**由 `svharness requirements verify` + `doctor --mode requirements` 负责（非表单门禁）。
 同时新增：
 
 - `check-requirements-fidelity`：检查 `source_excerpt` 缺失、`description` 缩略与占位语义。
 - `check-specs-depth`：检查 index-only 信号、enum 缺失 `enum_values`、behavior 空 `guard/action`。
 
-### `convert` —— 文档 → Markdown 预处理（对接 S20_collect_inputs）
+- `check-structure-coverage` / `check-source-inventory`：结构块与 Locator 摘录校验（`requirements` 模式）。
+
+### `requirements` —— S40 条目化结构扫描与 verify 门禁
+
+`structure-scan` 在 **`svharness convert`（requirements）与 `svharness build` 注入需求后自动执行**；也可手动增量重扫。
 
-把本地原始需求文档（`.pdf / .docx / .pptx / .xlsx / .html / .epub / .txt / .csv / .json / ...`）通过**云端部署**的 `markitdown_serve`（FastAPI + Microsoft MarkItDown）批量转为 Markdown，产物统一落到 `<harness>/<type>/md/`（`type` 为 `requirements` 或 `references`），直接喂给下游 `S40_extract_requirements` 条目化流程，显著提升 specs 生成质量的稳定性。
+```bash
+# 增量重扫（docx→md 与 raw/*.md 双路径）
+svharness requirements structure-scan --harness ./my-app-harness
+
+# S40 机器门禁（生成 coverage-report + verify-gaps.json）
+svharness requirements verify --harness ./my-app-harness --strict
+
+# S40 专用 doctor
+svharness doctor --harness ./my-app-harness --mode requirements --strict
+```
+
+`svharness convert ... --no-structure-scan` 可跳过 convert 后的自动 structure-scan。
+
+### `convert` —— 文档 → Markdown 预处理（对接 S30_convert_docs）
+
+把本地原始需求文档（`.pdf / .docx / .pptx / .xlsx / .html / .epub / .txt / .csv / .json / ...`）通过**云端部署**的 `markitdown_serve`（FastAPI + Microsoft MarkItDown + **多引擎 fallback chain**）批量转为 Markdown，产物统一落到 `<harness>/<type>/md/`（`type` 为 `requirements` 或 `references`），直接喂给下游 `S40_extract_requirements` 条目化流程。
 
 > **表格清洗（xlsx/xls/csv）**：源文件为 `.xlsx`、`.xls` 或 `.csv` 时，转换完成后自动清理 Markdown 表格中的 `NaN`、全空行、以及数据全空且表头为 `Unnamed: N` 的列（CLI 与服务端双端生效）。对已存在的产物 md 可执行：`node scripts/cleanup-spreadsheet-md.js <dirOrFile>`。
 
@@ -475,6 +498,11 @@ svharness doctor --harness ./my-app-harness --mode pre-seal --format json --repo
 
 > **架构约束**：CLI 只是 HTTP 客户端，**不 spawn / 不装 Python / 不管进程**。服务端代码集中在 `svharnessbuild/markitdown_serve/` 便于仓内维护，但**不随 npm 包分发**，部署方式详见 [markitdown_serve/README.md](./markitdown_serve/README.md)。
 
+> **高可靠转换（2026-06）**：
+> - **服务端 fallback chain**：MarkItDown 失败或输出过短时，按扩展名尝试后备（PDF：pymupdf → pypdf → tesseract OCR；xlsx：openpyxl → pandas）。详见 [markitdown_serve/README.md §详细设计](./markitdown_serve/README.md#详细设计) 与 [详细设计 §4.10](../tmp/svharnessbuild-detail-design.md#410-文档转换convert-命令--markitdown_serve-远端服务)。
+> - **CLI endpoint failover**：`--endpoint` / `SVHARNESS_MARKITDOWN_ENDPOINT` 支持逗号分隔多 URL。
+> - **失败追溯**：有失败时写入 `<outputDir>/convert-failures.json`（含 `trace_id`）。
+
 ```bash
 # 最简 —— 所有参数均可省略，默认扫描当前目录
 svharness convert
@@ -485,8 +513,9 @@ svharness convert --input ./docs/*.pdf --output ./docs/md --yes
 # harness 模式：md 写入 ./my-app-harness/requirements/md/
 svharness convert --input ./my-app-harness/requirements/raw --output ./my-app-harness --yes
 
-# 显示处理日志
-svharness convert --verbose
+# 多节点 failover + 详细引擎日志
+export SVHARNESS_MARKITDOWN_ENDPOINT=https://md-a.example.com,https://md-b.example.com
+svharness convert --verbose --yes
 ```
 
 #### 全部参数
@@ -496,7 +525,7 @@ svharness convert --verbose
 | `--input <path...>` | 一个或多个源文件 / 目录 / glob，支持 `./a/*.pdf`、`./docs/**/*.docx`、`./{a,b}/*.md` | `.`（当前目录） |
 | `--harness <path>` | harness 根目录（需 `harness.yaml`）；单独使用时写入 `<harness>/<type>/md/`；与 `--output` 同用时 `--output` 为最终 md 目录 | — |
 | `--output <path>` | **独立模式**：最终 md 输出目录；**harness 模式**：`path` 含 `harness.yaml` 时写入 `<path>/<type>/md/` | `.`（当前目录） |
-| `--endpoint <url>` | 云端 `markitdown_serve` 基址，省略时读环境变量 `SVHARNESS_MARKITDOWN_ENDPOINT` | `http://markitdown.desaysz.site` |
+| `--endpoint <url>` | 云端 `markitdown_serve` 基址；**逗号分隔**可配置 failover；省略时读 `SVHARNESS_MARKITDOWN_ENDPOINT` | `http://markitdown.desaysz.site` |
 | `--concurrency <n>` | 并发上传数 | `3` |
 | `--max-file-mb <n>` | 单文件大小上限（MB），本地 + 服务端双重限流 | `50` |
 | `--timeout-sec <n>` | 单请求超时秒数 | `120`（2 分钟） |
@@ -505,12 +534,13 @@ svharness convert --verbose
 | `--split-sheets-suffix <suffix>` | xlsx/xls 按 sheet 拆分的子目录后缀 | `_split` |
 | `--no-split-sheets` | flag，不将 xlsx/xls 合并 md 按 `##` 拆分为多文件 | `false`（默认拆分） |
 | `-y, --yes` | flag，跳过交互确认 | `false` |
-| `--verbose` | flag，显示详细日志 | `false` |
+| `--verbose` | flag，显示详细日志（含每文件 `converter` / `fallback_used` / endpoint） | `false` |
 
 #### 行为要点
 
-- **健康探针前置**：上传前先 `GET /healthz`，不通直接退出并打印清晰定位指引（endpoint / 环境变量 / 服务端目录三条线索）。
-- **单文件失败不中断**：失败单文件计入汇总，其它文件照常完成。结束时打印 `ok / skipped / failed` 计数。
+- **健康探针前置**：上传前先 `GET /healthz`（多 endpoint 时过滤不健康节点），不通直接退出。
+- **单文件失败不中断**：失败计入汇总；有失败时写入 `convert-failures.json` 并 `exit 1`。
+- **Endpoint failover**：5xx / 网络错误在 comma-separated 列表中切换下一节点；415 等 4xx 不切换。
 - **本地白名单预过滤**：客户端与服务端的扩展名白名单保持一致，非白名单文件本地直接跳过，避免无意义往返。
 - **两种输出模式**：
   - **独立**：`--output` 即最终 md 目录（路径下无 `harness.yaml`），例如 `--output ./docs/md`。
@@ -530,16 +560,84 @@ svharness convert --verbose
     └── md/
         ├── 参考文档.md
         └── ...
+
+# 有失败时额外产出（与 md 同目录）：
+convert-failures.json
 ```
 
 #### 接口契约（CLI ⇄ markitdown_serve）
 
 | 端点 | 方法 | 约定 |
 |---|---|---|
-| `/healthz` | GET | 200 `{status, markitdown_version}` |
-| `/convert` | POST | multipart/form-data，字段 `file`；200 返回 `{markdown, source_name, mime}`；413/415/500 带结构化 `error` 字段 |
+| `/healthz` | GET | 200 `{status, markitdown_version, converters?}` |
+| `/convert` | POST | multipart/form-data，字段 `file`；200 返回 `{markdown, source_name, mime, converter?, fallback_used?}`；413/415/500 带 `error` + `trace_id` |
+
+完整契约、fallback chain、Docker 部署见 [markitdown_serve/README.md](./markitdown_serve/README.md)；模块设计见 [tmp/svharnessbuild-detail-design.md §4.10](../tmp/svharnessbuild-detail-design.md#410-文档转换convert-命令--markitdown_serve-远端服务)。
+
+### `start-agent` —— 启动 Agent 填充 harness（v0.16+）
+
+`build` 生成骨架后，用本命令在**项目根（workdir）**启动 CodeChat CLI，驱动 S10–S90 构建阶段；`apply` 之后亦可在目标项目根启动 Agent 做业务开发。
+
+详细设计见 [`docs/agent-launcher-design.md`](docs/agent-launcher-design.md)。
 
-完整契约与部署说明见 [markitdown_serve/README.md](./markitdown_serve/README.md)。
+#### 快速示例
+
+```bash
+# 当前目录
+svharness start-agent
+
+# 显式 workdir
+svharness start-agent --work-dir /path/to/project
+svharness start-agent codechat ./my-app
+svharness start-agent /path/to/project
+
+# 不同步项目 env、保留 CodeChat 权限确认
+svharness start-agent --work-dir . --no-sync-env --no-skip-permissions
+```
+
+#### 全部参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `[agentOrWorkdir]` | 已知 agent 名 **或** workdir 路径 | — |
+| `[workdir]` | 工作目录（前一参数为 agent 时使用） | — |
+| `--work-dir <path>` | Agent 工作目录（harness 项目根） | 当前目录 |
+| `--agent <agent>` | 目标 Agent（**当前仅 codechat 可实际启动**） | `codechat` |
+| `--no-sync-env` | 不同步 `<workdir>/.claude/.env` → `~/.claude/.env` | false |
+| `--no-skip-permissions` | 不传 `--dangerously-skip-permissions` | 默认传 |
+
+#### 平台说明
+
+| 平台 | CodeChat runner |
+|------|-----------------|
+| Windows | `~/.codechat/cli_app/run.bat` |
+| Linux | `~/.codechat/cli_app/run.sh` |
+
+### `launch_codechat_cli` —— 全局快捷命令（v0.16+）
+
+`npm install -g svharness` 后可用，等价于 `svharness start-agent codechat`（不支持额外 flag）。
+
+```bash
+launch_codechat_cli
+launch_codechat_cli D:\projects\my-app    # Windows
+launch_codechat_cli ~/projects/my-app     # Linux
+```
+
+### `shell` —— Windows 右键菜单（v0.16+，仅 win32）
+
+在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」。
+
+```bash
+svharness shell install      # 注册（幂等）
+svharness shell uninstall    # 移除
+svharness shell status       # 查看 stub / 注册表状态
+```
+
+`npm install -g svharness` 在 Windows 上 **默认自动** `shell install`。跳过：
+
+```bash
+SVHARNESS_SKIP_SHELL=1 npm install -g svharness
+```
 
 ---
 
@@ -666,10 +764,16 @@ svharness build \
 ```
 svharnessbuild/                   # 源码目录名沿用旧名（历史包名），CLI 名称已迁至 svharness
 ├── bin/cli.js                    # npm bin 入口 → dist/index.js
+├── bin/launch-codechat-cli.js    # 全局快捷命令 launch_codechat_cli
+├── docs/agent-launcher-design.md # Agent 启动器详细设计
 ├── src/
 │   ├── index.ts                  # CLI 入口（commander）
 │   ├── types.ts                  # SupportedArch 枚举
 │   ├── commands/init.ts          # 4 步主管线（双模板根：_shared + <arch>）
+│   ├── commands/start-agent.ts   # start-agent 子命令
+│   ├── commands/shell-integration.ts  # Windows 右键菜单
+│   ├── lib/agent-launcher.ts     # CodeChat 启动核心
+│   ├── lib/win-registry.ts       # HKCU 注册表封装
 │   ├── core/
 │   │   ├── scaffold.ts           # scaffoldLayered: 先 _shared 再 <arch>
 │   │   ├── render-meta.ts        # renderMetaLayered: 同名 .ejs 以 <arch> 为准

package/bin/launch-codechat-cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runStartAgent } = require('../dist/lib/agent-launcher');
+
+const positionalWorkdir = process.argv[2];
+
+runStartAgent({
+  agent: 'codechat',
+  positionalWorkdir,
+})
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    console.error('[err]  ' + err.message);
+    process.exitCode = 1;
+  });

package/dist/commands/convert.js

@@ -27,6 +27,7 @@ const logger_1 = require("../utils/logger");
 const validate_args_1 = require("../utils/validate-args");
 const markitdown_client_1 = require("../core/markitdown-client");
 const doc_intake_paths_1 = require("../core/doc-intake-paths");
+const structure_scan_1 = require("../lib/requirements/structure-scan");
 const markdown_table_cleanup_1 = require("../core/markdown-table-cleanup");
 const markdown_sheet_split_1 = require("../core/markdown-sheet-split");
 /**
@@ -87,7 +88,12 @@ async function runConvert(opts) {
         configRows.push({ label: 'harness    ', value: v.harnessRoot });
         configRows.push({ label: 'type       ', value: v.type });
     }
-    configRows.push({ label: 'output dir ', value: outDir }, { label: 'endpoint   ', value: v.endpoint }, { label: 'concurrency', value: String(v.concurrency) }, { label: 'max file   ', value: `${v.maxFileMB} MB` }, { label: 'timeout    ', value: `${v.timeoutSec}s` }, { label: 'force      ', value: opts.force ? 'yes' : 'no' }, {
+    configRows.push({ label: 'output dir ', value: outDir }, {
+        label: 'endpoint   ',
+        value: v.endpoints.length > 1
+            ? `${v.endpoint} (+${v.endpoints.length - 1} failover)`
+            : v.endpoint,
+    }, { label: 'concurrency', value: String(v.concurrency) }, { label: 'max file   ', value: `${v.maxFileMB} MB` }, { label: 'timeout    ', value: `${v.timeoutSec}s` }, { label: 'force      ', value: opts.force ? 'yes' : 'no' }, {
         label: 'split sheets',
         value: opts.splitSheets === false
             ? 'no'
@@ -130,20 +136,60 @@ async function runConvert(opts) {
             return;
         }
     }
-    // 4. Probe health endpoint before any upload.
-    try {
-        const h = await (0, markitdown_client_1.ping)(v.endpoint);
-        logger_1.logger.debug(`healthz ok: status=${h.status} markitdown=${h.markitdown_version ?? 'n/a'}`);
+    // 4. Probe health endpoint(s) before any upload.
+    let activeEndpoints = v.endpoints;
+    if (v.endpoints.length > 1) {
+        activeEndpoints = await (0, markitdown_client_1.filterHealthyEndpoints)(v.endpoints);
+        if (activeEndpoints.length === 0) {
+            logger_1.logger.error(`all ${v.endpoints.length} markitdown_serve endpoint(s) unreachable`);
+            for (const ep of v.endpoints) {
+                logger_1.logger.plain(`  - ${ep}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (activeEndpoints.length < v.endpoints.length) {
+            logger_1.logger.warn(`using ${activeEndpoints.length}/${v.endpoints.length} healthy endpoint(s)`);
+        }
+        if (opts.verbose) {
+            try {
+                const h = await (0, markitdown_client_1.ping)(activeEndpoints[0]);
+                if (h.converters) {
+                    const ready = Object.entries(h.converters)
+                        .filter(([, ok]) => ok)
+                        .map(([name]) => name)
+                        .join(', ');
+                    logger_1.logger.debug(`converters ready: ${ready}`);
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
     }
-    catch (err) {
-        const e = err;
-        logger_1.logger.error(`markitdown_serve unreachable at ${v.endpoint}: ${e.message}`);
-        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 set env SVHARNESS_MARKITDOWN_ENDPOINT');
-        logger_1.logger.plain('  - check the server code under svharnessbuild/markitdown_serve/');
-        process.exitCode = 1;
-        return;
+    else {
+        try {
+            const h = await (0, markitdown_client_1.ping)(v.endpoint);
+            logger_1.logger.debug(`healthz ok: status=${h.status} markitdown=${h.markitdown_version ?? 'n/a'}`);
+            if (opts.verbose && h.converters) {
+                const ready = Object.entries(h.converters)
+                    .filter(([, ok]) => ok)
+                    .map(([name]) => name)
+                    .join(', ');
+                logger_1.logger.debug(`converters ready: ${ready}`);
+            }
+        }
+        catch (err) {
+            const e = err;
+            logger_1.logger.error(`markitdown_serve unreachable at ${v.endpoint}: ${e.message}`);
+            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');
+            logger_1.logger.plain('  - set env SVHARNESS_MARKITDOWN_ENDPOINT (supports comma-separated list)');
+            logger_1.logger.plain('  - check the server code under svharnessbuild/markitdown_serve/');
+            process.exitCode = 1;
+            return;
+        }
     }
     // 5. Bounded-concurrency upload.
     const results = skipped.map(planToResult);
@@ -155,7 +201,7 @@ async function runConvert(opts) {
             const item = queue.shift();
             if (!item)
                 break;
-            results.push(await uploadOne(item.source, outDir, used, v, opts));
+            results.push(await uploadOne(item.source, outDir, used, v, opts, activeEndpoints));
         }
     };
     for (let i = 0; i < Math.min(v.concurrency, toUpload.length); i++) {
@@ -173,6 +219,18 @@ async function runConvert(opts) {
     const failed = results.filter((r) => r.status === 'failed');
     if (failed.length > 0) {
         process.exitCode = 1;
+        await writeFailuresReport(outDir, activeEndpoints, failed, opts.failuresReport);
+    }
+    if (v.harnessMode && v.harnessRoot && v.type === 'requirements') {
+        try {
+            await (0, structure_scan_1.maybeRunStructureScanForRequirements)(v.harnessRoot, 'convert', {
+                noStructureScan: opts.noStructureScan,
+                verbose: opts.verbose,
+            });
+        }
+        catch (err) {
+            logger_1.logger.warn(`structure-scan 失败（不中断 convert）：${err.message}`);
+        }
     }
 }
 /** Walk glob patterns / explicit paths / directories into an absolute file list. */
@@ -324,7 +382,7 @@ async function buildPlan(files, limitBytes) {
     }
     return out;
 }
-async function uploadOne(source, outDir, used, v, opts) {
+async function uploadOne(source, outDir, used, v, opts, activeEndpoints) {
     const basename = node_path_1.default.basename(source, node_path_1.default.extname(source));
     const outPath = await resolveOutputPath(outDir, basename, used, !!opts.force);
     used.add(outPath);
@@ -332,7 +390,11 @@ async function uploadOne(source, outDir, used, v, opts) {
     const splitSuffix = opts.splitSheetsSuffix ?? '_split';
     logger_1.logger.debug(`upload ${source} -> ${outPath}`);
     try {
-        const resp = await (0, markitdown_client_1.postConvertWithRetry)(v.endpoint, source, v.timeoutSec * 1000);
+        const resp = await (0, markitdown_client_1.postConvertWithEndpointFailover)(activeEndpoints, source, v.timeoutSec * 1000);
+        if (opts.verbose && (resp.converter || resp.fallback_used)) {
+            logger_1.logger.debug(`converter ${node_path_1.default.basename(source)}: ${resp.converter ?? 'markitdown'} ` +
+                `fallback=${resp.fallback_used ? 'yes' : 'no'} endpoint=${resp.endpointUsed}`);
+        }
         const ext = node_path_1.default.extname(source).toLowerCase();
         let markdown = resp.markdown;
         if (markdown_table_cleanup_1.XLSX_CONVERT_EXTS.has(ext)) {
@@ -358,17 +420,37 @@ async function uploadOne(source, outDir, used, v, opts) {
                 outputs.push(...splitWritten);
                 logger_1.logger.debug(`sheet split ${node_path_1.default.basename(source)}: ${split.sections.length} sections -> ${splitDir}`);
                 logger_1.logger.success(`${node_path_1.default.basename(source)} -> ${node_path_1.default.basename(outPath)} + ${split.sections.length} sheets in ${node_path_1.default.basename(splitDir)}/ (${bytes}B)`);
-                return { source, output: outPath, outputs, status: 'ok', bytes };
+                return {
+                    source,
+                    output: outPath,
+                    outputs,
+                    status: 'ok',
+                    bytes,
+                    converter: resp.converter,
+                    fallbackUsed: resp.fallback_used,
+                    endpoint: resp.endpointUsed,
+                };
             }
         }
-        logger_1.logger.success(`${node_path_1.default.basename(source)} -> ${node_path_1.default.basename(outPath)} (${bytes}B)`);
-        return { source, output: outPath, outputs, status: 'ok', bytes };
+        const convNote = resp.fallback_used && resp.converter ? ` [${resp.converter}]` : '';
+        logger_1.logger.success(`${node_path_1.default.basename(source)} -> ${node_path_1.default.basename(outPath)} (${bytes}B)${convNote}`);
+        return {
+            source,
+            output: outPath,
+            outputs,
+            status: 'ok',
+            bytes,
+            converter: resp.converter,
+            fallbackUsed: resp.fallback_used,
+            endpoint: resp.endpointUsed,
+        };
     }
     catch (err) {
         const e = err;
         const reason = e.message;
+        const traceId = e instanceof markitdown_client_1.MarkItDownClientError ? (0, markitdown_client_1.extractTraceId)(e.body) : undefined;
         logger_1.logger.error(`failed: ${node_path_1.default.basename(source)} — ${reason}`);
-        return { source, status: 'failed', reason };
+        return { source, status: 'failed', reason, traceId };
     }
 }
 /**
@@ -393,14 +475,39 @@ function printSummary(results) {
     const ok = results.filter((r) => r.status === 'ok').length;
     const failed = results.filter((r) => r.status === 'failed').length;
     const skipped = results.filter((r) => r.status === 'skipped').length;
+    const fallbackOk = results.filter((r) => r.status === 'ok' && r.fallbackUsed).length;
     logger_1.logger.section('convert summary');
     logger_1.logger.plain(`  ok      : ${ok}`);
     logger_1.logger.plain(`  skipped : ${skipped}`);
     logger_1.logger.plain(`  failed  : ${failed}`);
+    if (fallbackOk > 0) {
+        logger_1.logger.plain(`  fallback: ${fallbackOk} file(s) used backup converter`);
+    }
     if (failed > 0) {
         logger_1.logger.plain('');
         for (const r of results.filter((x) => x.status === 'failed')) {
-            logger_1.logger.plain(`  - ${node_path_1.default.basename(r.source)}: ${r.reason}`);
+            const trace = r.traceId ? ` (trace_id=${r.traceId})` : '';
+            logger_1.logger.plain(`  - ${node_path_1.default.basename(r.source)}: ${r.reason}${trace}`);
         }
     }
 }
+async function writeFailuresReport(outDir, endpoints, failed, customPath) {
+    if (customPath === '')
+        return;
+    const reportPath = customPath && customPath.trim().length > 0
+        ? node_path_1.default.isAbsolute(customPath)
+            ? customPath
+            : node_path_1.default.resolve(outDir, customPath)
+        : node_path_1.default.join(outDir, 'convert-failures.json');
+    const payload = {
+        generated_at: new Date().toISOString(),
+        endpoints,
+        failures: failed.map((r) => ({
+            source: r.source,
+            reason: r.reason,
+            trace_id: r.traceId,
+        })),
+    };
+    await fs_extra_1.default.writeFile(reportPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    logger_1.logger.warn(`wrote failure manifest: ${reportPath}`);
+}