svharness 0.14.5 → 0.14.7

package/README.md

@@ -116,6 +116,7 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 │   └── yaml/
 └── baseline/
     ├── code/                       #   参考代码快照
+    ├── repomix/                    #   可选：`--repomix` 时生成的单文件 XML 快照
     └── wiki/                       #   架构 wiki
 │
 ├── agent-env/                    # Agent 运行期环境
@@ -274,6 +275,7 @@ svharness build \
 | `--extra-skills <path...>` | 可选 | 额外运行期资源输入（文件/目录/glob，可混放 skills/rules）；build 阶段先拷贝到 `agent-env/_incoming/skills/` 并生成 `agent-env/_incoming/manifest.yaml`，S65 再分流写入 `skills/` 与 `rules/` | — |
 | `--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-concurrency <n>` | 可选 | build 自动 convert 并发上传数 | `3` |
 | `--convert-max-file-mb <n>` | 可选 | build 自动 convert 单文件大小上限（MB） | `50` |
@@ -307,6 +309,36 @@ svharness build \
 
 > Wiki 生成失败不会回滚 harness 骨架，仅输出警告。
 
+#### Repomix（`--repomix`）{#repomix-repomix}
+
+**产物**：`baseline/repomix/repomix-pack.xml` —— 用 [Repomix](https://github.com/yamadashy/repomix) 把 `baseline/code/` 目录树压缩成**一份带行号的 XML**，便于整包喂给上下文窗口有限的模型，或离线归档/比对。
+
+**默认关闭的原因**：harness 主流程已依赖 `baseline/code/`（逐文件引用、wiki-writer、knowledge-builder、S61 自动提取等）。Repomix 是**辅助快照**，不是 specs / requirements 的契约来源，且大仓库打包耗时长、产物体积大。
+
+**建议开启 `--repomix` 的场景**：
+
+| 场景 | 说明 |
+|------|------|
+| 基线体量较大，需要「整库一览」 | 希望 Agent **一次 attach 单文件** 做架构鸟瞰、模块边界梳理、依赖关系初扫，而不是在对话里反复 `@` 上百个路径 |
+| 外部工具只吃单文件上下文 | 使用只支持粘贴/上传**单个**上下文文件的分析器、审计脚本或二次 LLM 流水线 |
+| 离线交付或版本留档 | 需要把某次 `--baseline` 快照固化为**可 diff 的单文件**（例如随 harness 封存、发给评审方） |
+| 与 `baseline/wiki/` 互补 | wiki 偏「说明文档」；Repomix 偏「源码字面快照」。做反向提取前的**代码面**快速摸底时可同时保留两者 |
+
+**通常不必开启的场景**：
+
+- 基线很小，或 Agent 已能稳定按路径阅读 `baseline/code/`（**默认路径即可**）
+- 只关心 harness-build 标准阶段（S40/S50/S85）：规格与审查以 `requirements/`、`specs/`、`baseline/code` 为准，**不依赖** Repomix XML
+- 基线含大量二进制/生成物：Repomix 对图片等帮助有限，且会拉长 build 时间（失败仅告警，不回滚骨架）
+
+**用法**：
+
+```bash
+svharness build --harness-name my-app --baseline ./src --repomix
+# 或配置：build.repomix: true（须同时配置 build.baseline）
+```
+
+> Repomix 步骤在 baseline 拷贝**之后**执行；打包失败不会回滚 harness 骨架。已构建的 harness 可带 `--force` 重新 `build` 并补上 `--repomix`。
+
 ### Agent 适配器
 
 | Agent | skill 目录 | 扩展名 | 额外处理 |
@@ -341,6 +373,8 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 - `--inject-build-main-bridge` 开启时：在 `<target>/<adapter.skillsDir>/harness-build-skills-bridge/` 写入桥接 skill（仅用于构建流二次改造）
 - 目标 `.gitignore` 会在文件尾部 append 注入路径（幂等去重）
 
+**Repomix 与 apply**：若 build 时启用了 `--repomix` 且产物存在，CLI 会回写 `harness.yaml` → `baseline.repomix_pack`，并在 `apply` 时向 `harness-apply-skills-main` 与项目根 `AGENTS.md`/`CLAUDE.md` 注入 Repomix 路径与用法（权威参考实现仍为 `baseline/code/`）。详见上文 [Repomix（`--repomix`）](#repomix-repomix)。
+
 #### references 内容引用 → apply_skill_registry（S60，由 Agent 写入）
 
 S60（`harness-build-skill-references-intake`）属于 **build 阶段**。若某份 references 属于**内容引用**（apply 时要按 `references/md/` 原文指导开发），Agent 应：
@@ -435,6 +469,10 @@ svharness doctor --harness ./my-app-harness --mode pre-seal --format json --repo
 
 把本地原始需求文档（`.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 生成质量的稳定性。
 
+> **表格清洗（xlsx/xls/csv）**：源文件为 `.xlsx`、`.xls` 或 `.csv` 时，转换完成后自动清理 Markdown 表格中的 `NaN`、全空行、以及数据全空且表头为 `Unnamed: N` 的列（CLI 与服务端双端生效）。对已存在的产物 md 可执行：`node scripts/cleanup-spreadsheet-md.js <dirOrFile>`。
+
+> **Sheet 拆分（xlsx/xls）**：多 sheet 工作簿转换后，MarkItDown 以 `## SheetName` 分隔各 sheet。CLI 默认在保留合并 md 的同时，将各 sheet 写入 `<basename>_split/`（含 `README.md` 索引）；`--no-split-sheets` 可关闭。已有合并 md 可执行：`node scripts/split-spreadsheet-md.js <dirOrFile>`。
+
 > **架构约束**：CLI 只是 HTTP 客户端，**不 spawn / 不装 Python / 不管进程**。服务端代码集中在 `svharnessbuild/markitdown_serve/` 便于仓内维护，但**不随 npm 包分发**，部署方式详见 [markitdown_serve/README.md](./markitdown_serve/README.md)。
 
 ```bash
@@ -464,6 +502,8 @@ svharness convert --verbose
 | `--timeout-sec <n>` | 单请求超时秒数 | `120`（2 分钟） |
 | `--type <type>` | 目标子目录：`requirements`（正式需求）\| `references`（参考资料） | `requirements` |
 | `--force` | flag，覆盖已存在同名 `.md`（默认自动追加 `-1`、`-2` 后缀） | `false` |
+| `--split-sheets-suffix <suffix>` | xlsx/xls 按 sheet 拆分的子目录后缀 | `_split` |
+| `--no-split-sheets` | flag，不将 xlsx/xls 合并 md 按 `##` 拆分为多文件 | `false`（默认拆分） |
 | `-y, --yes` | flag，跳过交互确认 | `false` |
 | `--verbose` | flag，显示详细日志 | `false` |
 
@@ -703,6 +743,9 @@ node bin\cli.js build --harness-name demo --arch android-compose --agent codecha
 ### 发布
 
 ```bash
+npm version 0.14.6
+npm run build
+
 npm login
 npm publish --access public    # prepublishOnly 自动执行 build
 ```

package/dist/commands/apply.js

@@ -10,6 +10,7 @@ const js_yaml_1 = __importDefault(require("js-yaml"));
 const prompts_1 = __importDefault(require("prompts"));
 const adapters_1 = require("../adapters");
 const apply_project_entry_1 = require("../core/apply-project-entry");
+const repomix_apply_hint_1 = require("../core/repomix-apply-hint");
 const validate_args_1 = require("../utils/validate-args");
 const logger_1 = require("../utils/logger");
 const version_1 = require("../utils/version");
@@ -322,9 +323,14 @@ async function injectThinMainSkill(input) {
         await fs_extra_1.default.remove(dstDir);
     }
     const raw = await fs_extra_1.default.readFile(templatePath, 'utf8');
-    const rendered = raw
+    const repomixHint = await (0, repomix_apply_hint_1.buildRepomixApplyHintReplacement)({
+        harnessRoot: input.harnessRoot,
+        harnessDirName: input.harnessDirName,
+        blockquote: false,
+    });
+    const rendered = (0, repomix_apply_hint_1.applyRepomixHintPlaceholder)(raw
         .replace(/__HARNESS_ROOT_REL__/g, `./${input.harnessDirName}`)
-        .replace(/__HARNESS_DIR_NAME__/g, input.harnessDirName);
+        .replace(/__HARNESS_DIR_NAME__/g, input.harnessDirName), repomixHint, repomix_apply_hint_1.REPOMIX_APPLY_HINT_PLACEHOLDER);
     const content = input.adapter.transform
         ? input.adapter.transform(rendered, `${DISPATCHER_SKILL_NAME}.md`)
         : rendered;
@@ -707,6 +713,7 @@ async function runApply(opts) {
     const thinMainPath = await injectThinMainSkill({
         templatesRoot,
         targetRoot,
+        harnessRoot: effectiveHarnessRoot,
         adapter,
         harnessDirName,
         force: !!opts.force,

package/dist/commands/convert.js

@@ -27,6 +27,8 @@ 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 markdown_table_cleanup_1 = require("../core/markdown-table-cleanup");
+const markdown_sheet_split_1 = require("../core/markdown-sheet-split");
 /**
  * Extensions recognised by Microsoft MarkItDown (v0.x). Anything outside this
  * whitelist is skipped client-side to avoid a round-trip that is guaranteed to
@@ -85,7 +87,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.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'
+            : `yes (${opts.splitSheetsSuffix ?? '_split'})`,
+    });
     logger_1.logger.configBox('svharness convert', configRows);
     // 1. Collect candidate files.
     const candidates = await collectFiles(v.input, cwd);
@@ -321,13 +328,41 @@ async function uploadOne(source, outDir, used, v, opts) {
     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);
+    const splitSheets = opts.splitSheets !== false;
+    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);
-        await fs_extra_1.default.writeFile(outPath, resp.markdown, 'utf8');
-        const bytes = Buffer.byteLength(resp.markdown, 'utf8');
+        const ext = node_path_1.default.extname(source).toLowerCase();
+        let markdown = resp.markdown;
+        if (markdown_table_cleanup_1.XLSX_CONVERT_EXTS.has(ext)) {
+            const cleaned = (0, markdown_table_cleanup_1.cleanupSpreadsheetMarkdown)(markdown);
+            markdown = cleaned.markdown;
+            const { stats } = cleaned;
+            if (stats.nanCellsReplaced > 0 ||
+                stats.rowsRemoved > 0 ||
+                stats.columnsRemoved > 0) {
+                logger_1.logger.debug(`spreadsheet cleanup ${node_path_1.default.basename(source)}: ` +
+                    `NaN=${stats.nanCellsReplaced} rows-=${stats.rowsRemoved} cols-=${stats.columnsRemoved} ` +
+                    `bytes ${stats.charsBefore}->${stats.charsAfter}`);
+            }
+        }
+        await fs_extra_1.default.writeFile(outPath, markdown, 'utf8');
+        const bytes = Buffer.byteLength(markdown, 'utf8');
+        const outputs = [outPath];
+        if (splitSheets && markdown_sheet_split_1.XLSX_SPLIT_EXTS.has(ext)) {
+            const split = (0, markdown_sheet_split_1.splitSpreadsheetMarkdownBySheet)(markdown);
+            if (split.sections.length >= 2) {
+                const splitDir = node_path_1.default.join(outDir, `${basename}${splitSuffix}`);
+                const splitWritten = await (0, markdown_sheet_split_1.writeSheetSplitOutput)(split.sections, splitDir, node_path_1.default.basename(source), { writeIndex: true, force: !!opts.force });
+                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 };
+            }
+        }
         logger_1.logger.success(`${node_path_1.default.basename(source)} -> ${node_path_1.default.basename(outPath)} (${bytes}B)`);
-        return { source, output: outPath, status: 'ok', bytes };
+        return { source, output: outPath, outputs, status: 'ok', bytes };
     }
     catch (err) {
         const e = err;

package/dist/commands/init.js

@@ -20,6 +20,8 @@ const build_project_entry_1 = require("../core/build-project-entry");
 const project_ignore_1 = require("../core/project-ignore");
 const harness_name_1 = require("../utils/harness-name");
 const yaml_safe_path_1 = require("../utils/yaml-safe-path");
+const harness_yaml_baseline_1 = require("../core/harness-yaml-baseline");
+const repomix_apply_hint_1 = require("../core/repomix-apply-hint");
 const repomix_pack_1 = require("../core/repomix-pack");
 const extra_assets_intake_1 = require("../core/extra-assets-intake");
 const baseline_copy_1 = require("../utils/baseline-copy");
@@ -100,6 +102,10 @@ async function runInit(opts) {
     // modes. Wiki generation consumes this directory by default so it always
     // reflects the baseline the user asked for (not the caller's cwd).
     const hasBaseline = !!validated.baseline;
+    const enableRepomix = !!opts.repomix && hasBaseline;
+    if (opts.repomix && !hasBaseline) {
+        logger_1.logger.warn('--repomix 需要同时提供 --baseline，已忽略 Repomix 打包');
+    }
     const baselineCodeDir = node_path_1.default.join(targetRoot, 'baseline', 'code');
     const wikiSourceRoot = node_path_1.default.resolve(opts.wikiSource ?? (hasBaseline ? baselineCodeDir : cwd));
     // Derive the final wiki mode:
@@ -182,7 +188,9 @@ async function runInit(opts) {
     if (hasBaseline) {
         configItems.push({
             label: 'Repomix 基线包',
-            value: `默认生成（${(0, repomix_pack_1.repomixPackRelFile)()}）`,
+            value: enableRepomix
+                ? `启用（${(0, repomix_pack_1.repomixPackRelFile)()}）`
+                : '关闭（默认；大基线整库快照/单文件工具/留档时再 --repomix）',
         });
     }
     logger_1.logger.configBox('配置确认', configItems);
@@ -247,7 +255,7 @@ async function runInit(opts) {
     const hasExtraAssets = (opts.extraSkills?.length ?? 0) > 0;
     const stepExtraAssets = hasExtraAssets ? ++stepCursor : 0;
     const stepBaseline = hasBaseline ? ++stepCursor : 0;
-    const stepRepomix = hasBaseline ? ++stepCursor : 0;
+    const stepRepomix = enableRepomix ? ++stepCursor : 0;
     const stepWiki = wikiEnabled ? ++stepCursor : 0;
     const stepState = ++stepCursor;
     const totalSteps = stepCursor;
@@ -362,8 +370,9 @@ async function runInit(opts) {
             logger_1.logger.info('项目 ignore 文件已包含 build 注入路径，未追加新行');
         }
     }
-    // 6a. Repomix XML pack of baseline code (default when --baseline; non-fatal on failure).
-    if (hasBaseline) {
+    // 6a. Repomix XML pack of baseline code (opt-in via --repomix; non-fatal on failure).
+    let repomixGenerated = false;
+    if (enableRepomix) {
         logger_1.logger.section(`步骤 ${stepRepomix}/${totalSteps} - 生成 baseline Repomix 包`);
         try {
             const packRootFs = wikiSourceRoot;
@@ -381,6 +390,19 @@ async function runInit(opts) {
                 onLog: (m) => logger_1.logger.info(`  ${m}`),
             });
             logger_1.logger.success(`baseline Repomix 已生成：${node_path_1.default.relative(targetRoot, outAbs)}`);
+            repomixGenerated = true;
+            await (0, harness_yaml_baseline_1.setBaselineRepomixPack)(targetRoot, (0, repomix_pack_1.repomixPackRelFile)());
+            logger_1.logger.info(`已更新 harness.yaml：baseline.repomix_pack`);
+            const agentsApplyPath = node_path_1.default.join(targetRoot, 'AGENTS_APPLY.md');
+            if (await fs_extra_1.default.pathExists(agentsApplyPath)) {
+                const repomixHint = await (0, repomix_apply_hint_1.buildRepomixApplyHintReplacement)({
+                    harnessRoot: targetRoot,
+                    harnessDirName,
+                    blockquote: true,
+                });
+                const agentsApplyRaw = await fs_extra_1.default.readFile(agentsApplyPath, 'utf8');
+                await fs_extra_1.default.outputFile(agentsApplyPath, (0, repomix_apply_hint_1.applyRepomixHintPlaceholder)(agentsApplyRaw, repomixHint, repomix_apply_hint_1.REPOMIX_APPLY_HINT_PLACEHOLDER), 'utf8');
+            }
         }
         catch (err) {
             logger_1.logger.warn(`Repomix 生成失败（不回滚 harness 骨架）：${err.message}`);
@@ -563,6 +585,7 @@ async function runInit(opts) {
         adapter: adapterForNext,
         agent: validated.agent,
         hasSource: !!validated.baseline,
+        repomixGenerated,
         wikiMode,
     });
 }

package/dist/config/merge-options.js

@@ -77,6 +77,7 @@ function mergeBuildOptions(cli, configSection, defaults, cmd) {
         force: pickBool('force', cli.force, cfg.force, defaults?.force, cmd),
         yes: pickBool('yes', cli.yes, cfg.yes, defaults?.yes, cmd),
         verbose: pickBool('verbose', cli.verbose, cfg.verbose, defaults?.verbose, cmd),
+        repomix: pickBool('repomix', cli.repomix, cfg.repomix, undefined, cmd),
         generateWiki: pickBool('generateWiki', cli.generateWiki, cfg.generateWiki, undefined, cmd),
         wikiTasksOnly: pickBool('wikiTasksOnly', cli.wikiTasksOnly, cfg.wikiTasksOnly, undefined, cmd),
         wikiLang: pickString('wikiLang', cli.wikiLang, cfg.wikiLang, cmd),
@@ -113,6 +114,10 @@ function mergeConvertOptions(cli, configSection, defaults, cmd) {
         timeoutSec: pickNumber('timeoutSec', cli.timeoutSec, cfg.timeoutSec, cmd),
         type: pickString('type', cli.type, cfg.type, cmd),
         force: pickBool('force', cli.force, cfg.force, defaults?.force, cmd),
+        splitSheets: cli.noSplitSheets
+            ? false
+            : pickBool('splitSheets', cli.splitSheets, cfg.splitSheets, undefined, cmd),
+        splitSheetsSuffix: pickString('splitSheetsSuffix', cli.splitSheetsSuffix, cfg.splitSheetsSuffix, cmd),
         yes: pickBool('yes', cli.yes, cfg.yes, defaults?.yes, cmd),
         verbose: pickBool('verbose', cli.verbose, cfg.verbose, defaults?.verbose, cmd),
     };

package/dist/config/normalize.js

@@ -71,6 +71,7 @@ function pickBuildSection(raw) {
         'force',
         'yes',
         'verbose',
+        'repomix',
         'generateWiki',
         'wikiTasksOnly',
     ]) {
@@ -107,10 +108,13 @@ function pickConvertSection(raw) {
         if (raw[k] !== undefined)
             s[k] = Number(raw[k]);
     }
-    for (const k of ['force', 'yes', 'verbose']) {
+    for (const k of ['force', 'yes', 'verbose', 'splitSheets']) {
         if (raw[k] !== undefined)
             s[k] = Boolean(raw[k]);
     }
+    if (raw.splitSheetsSuffix !== undefined && raw.splitSheetsSuffix !== null) {
+        s.splitSheetsSuffix = String(raw.splitSheetsSuffix).trim();
+    }
     return s;
 }
 function pickDefaults(raw) {

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeApplyProjectEntry = writeApplyProjectEntry;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
+const repomix_apply_hint_1 = require("./repomix-apply-hint");
 const logger_1 = require("../utils/logger");
 function toPosix(p) {
     return p.replace(/\\/g, '/');
@@ -81,7 +82,13 @@ async function writeApplyProjectEntry(input) {
         : bridgeHint.length > 0
             ? `${raw.trimEnd()}\n\n${bridgeHint}`
             : raw;
-    const rewritten = rewriteEntryReferences(withBridgeHint, input.harnessDirName);
+    const repomixHint = await (0, repomix_apply_hint_1.buildRepomixApplyHintReplacement)({
+        harnessRoot: input.harnessRoot,
+        harnessDirName: input.harnessDirName,
+        blockquote: true,
+    });
+    const withRepomixHint = (0, repomix_apply_hint_1.applyRepomixHintPlaceholder)(withBridgeHint, repomixHint, repomix_apply_hint_1.REPOMIX_APPLY_HINT_PLACEHOLDER);
+    const rewritten = rewriteEntryReferences(withRepomixHint, input.harnessDirName);
     await fs_extra_1.default.outputFile(dest, rewritten, 'utf8');
     logger_1.logger.success(`已写入项目根 AI 入口：${rel}（由 AGENTS_APPLY.md 重命名）`);
     return rel;

package/dist/core/harness-yaml-baseline.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readHarnessYamlDoc = readHarnessYamlDoc;
+exports.getBaselineRepomixPackFromDoc = getBaselineRepomixPackFromDoc;
+exports.setBaselineRepomixPack = setBaselineRepomixPack;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const yaml_safe_path_1 = require("../utils/yaml-safe-path");
+const REPOMIX_PACK_KEY = 'repomix_pack';
+const REPOMIX_PACK_COMMENT = '  # repomix_pack: baseline/repomix/repomix-pack.xml  # 仅 --repomix 成功后由 CLI 写入';
+async function readHarnessYamlDoc(harnessRoot) {
+    const yamlPath = node_path_1.default.join(harnessRoot, 'harness.yaml');
+    if (!(await fs_extra_1.default.pathExists(yamlPath)))
+        return undefined;
+    try {
+        const raw = await fs_extra_1.default.readFile(yamlPath, 'utf8');
+        return js_yaml_1.default.load((0, yaml_safe_path_1.preprocessHarnessYamlText)(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+function getBaselineRepomixPackFromDoc(doc) {
+    if (!doc || typeof doc.baseline !== 'object' || doc.baseline === null)
+        return undefined;
+    const baseline = doc.baseline;
+    const v = baseline[REPOMIX_PACK_KEY];
+    if (typeof v !== 'string' || !v.trim())
+        return undefined;
+    return v.trim().replace(/\\/g, '/');
+}
+/**
+ * Set or clear `baseline.repomix_pack` in harness.yaml (line edit to preserve comments).
+ */
+async function setBaselineRepomixPack(harnessRoot, repomixPackRel) {
+    const yamlPath = node_path_1.default.join(harnessRoot, 'harness.yaml');
+    if (!(await fs_extra_1.default.pathExists(yamlPath))) {
+        throw new Error(`harness.yaml 不存在：${yamlPath}`);
+    }
+    let text = await fs_extra_1.default.readFile(yamlPath, 'utf8');
+    const rel = repomixPackRel?.trim().replace(/\\/g, '/') ?? null;
+    const activeLine = rel ? `  repomix_pack: ${rel}` : REPOMIX_PACK_COMMENT;
+    const activePattern = /^\s*repomix_pack:\s*.+$/m;
+    const commentPattern = /^\s*#\s*repomix_pack:.*$/m;
+    if (activePattern.test(text)) {
+        text = text.replace(activePattern, activeLine);
+    }
+    else if (commentPattern.test(text)) {
+        text = text.replace(commentPattern, activeLine);
+    }
+    else if (rel) {
+        const wikiLine = /(^\s*wiki:\s*baseline\/wiki\/.*$)/m;
+        if (wikiLine.test(text)) {
+            text = text.replace(wikiLine, `$1\n${activeLine}`);
+        }
+        else {
+            const baselineBlock = /(^baseline:\s*\n(?:^\s+.+\n)*)/m;
+            if (baselineBlock.test(text)) {
+                text = text.replace(baselineBlock, (block) => `${block}${activeLine}\n`);
+            }
+        }
+    }
+    await fs_extra_1.default.outputFile(yamlPath, text, 'utf8');
+}

package/dist/core/markdown-sheet-split.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XLSX_SPLIT_EXTS = void 0;
+exports.slugifySheetTitle = slugifySheetTitle;
+exports.splitSpreadsheetMarkdownBySheet = splitSpreadsheetMarkdownBySheet;
+exports.writeSheetSplitOutput = writeSheetSplitOutput;
+/**
+ * Split spreadsheet-derived Markdown by level-2 headings (`##`).
+ *
+ * MarkItDown emits one `## SheetName` block per Excel worksheet. This pass
+ * writes each block to its own `.md` file under `<basename><suffix>/`.
+ */
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Source extensions that trigger sheet split during `svharness convert`. */
+exports.XLSX_SPLIT_EXTS = new Set(['.xlsx', '.xls']);
+const INVALID_FILENAME_CHARS = /[<>:"/\\|?*\x00-\x1f]/g;
+/**
+ * Turn a sheet title into a safe filename: `{index}_{slug}.md`.
+ */
+function slugifySheetTitle(title, index) {
+    let name = title.trim();
+    name = name.replace(INVALID_FILENAME_CHARS, '_');
+    name = name.replace(/\s+/g, '_');
+    name = name.replace(/^[._]+|[._]+$/g, '');
+    if (!name) {
+        name = 'section';
+    }
+    return `${String(index).padStart(2, '0')}_${name}.md`;
+}
+/**
+ * Split markdown at `##` headings (one section per sheet).
+ */
+function splitSpreadsheetMarkdownBySheet(markdown) {
+    const charsBefore = Buffer.byteLength(markdown, 'utf8');
+    const lines = markdown.split(/\r?\n/);
+    const anchors = [];
+    for (let i = 0; i < lines.length; i++) {
+        const match = /^## (.+)$/.exec(lines[i]);
+        if (match) {
+            anchors.push({ title: match[1].trim(), startLine: i });
+        }
+    }
+    if (anchors.length === 0) {
+        return {
+            sections: [],
+            stats: { sectionsFound: 0, charsBefore, charsAfter: charsBefore },
+        };
+    }
+    const sections = [];
+    for (let i = 0; i < anchors.length; i++) {
+        const endLine = i + 1 < anchors.length ? anchors[i + 1].startLine : lines.length;
+        const body = lines.slice(anchors[i].startLine, endLine).join('\n').trimEnd() + '\n';
+        const filename = slugifySheetTitle(anchors[i].title, i + 1);
+        sections.push({
+            title: anchors[i].title,
+            body,
+            filename,
+        });
+    }
+    const charsAfter = sections.reduce((sum, s) => sum + Buffer.byteLength(s.body, 'utf8'), 0);
+    return {
+        sections,
+        stats: {
+            sectionsFound: sections.length,
+            charsBefore,
+            charsAfter,
+        },
+    };
+}
+function buildSplitIndex(sourceName, sections) {
+    const lines = [
+        `# Split index: ${sourceName}\n`,
+        `\nTotal sections: ${sections.length}\n\n`,
+    ];
+    for (const section of sections) {
+        lines.push(`- [${section.title}](${section.filename})\n`);
+    }
+    return lines.join('');
+}
+/**
+ * Persist split sections to `outputDir`. Returns absolute paths written.
+ */
+async function writeSheetSplitOutput(sections, outputDir, sourceName, opts) {
+    const writeIndex = opts?.writeIndex !== false;
+    const force = !!opts?.force;
+    await fs_extra_1.default.ensureDir(outputDir);
+    const written = [];
+    for (const section of sections) {
+        const filePath = node_path_1.default.join(outputDir, section.filename);
+        if (!force && (await fs_extra_1.default.pathExists(filePath))) {
+            throw new Error(`sheet split output exists (pass --force): ${filePath}`);
+        }
+        await fs_extra_1.default.writeFile(filePath, section.body, 'utf8');
+        written.push(filePath);
+    }
+    if (writeIndex) {
+        const indexPath = node_path_1.default.join(outputDir, 'README.md');
+        if (!force && (await fs_extra_1.default.pathExists(indexPath))) {
+            throw new Error(`sheet split index exists (pass --force): ${indexPath}`);
+        }
+        await fs_extra_1.default.writeFile(indexPath, buildSplitIndex(sourceName, sections), 'utf8');
+        written.push(indexPath);
+    }
+    return written;
+}

package/dist/core/markdown-table-cleanup.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Post-process Markdown emitted from spreadsheet conversions (`.xlsx` / `.xls` / `.csv`).
+ *
+ * MarkItDown / pandas represent empty Excel cells as the literal "NaN" in pipe
+ * tables. This pass:
+ *   1. Replaces NaN cells with empty cells
+ *   2. Drops data rows that are entirely empty or only contain a numeric index
+ *   3. Drops columns whose data rows are all empty and whose header is blank or
+ *      "Unnamed: N" (pandas default for empty header cells)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XLSX_CONVERT_EXTS = void 0;
+exports.cleanupSpreadsheetMarkdown = cleanupSpreadsheetMarkdown;
+/** Source extensions that trigger table cleanup during `svharness convert`. */
+exports.XLSX_CONVERT_EXTS = new Set([
+    '.xlsx',
+    '.xls',
+    '.csv',
+]);
+const UNNAMED_HEADER = /^Unnamed: \d+$/;
+function isTableRow(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith('|') && trimmed.endsWith('|');
+}
+function parseTableRow(line) {
+    const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+    return inner.split('|').map((cell) => cell.trim());
+}
+function formatTableRow(cells) {
+    return `| ${cells.join(' | ')} |`;
+}
+function normalizeCell(cell) {
+    if (cell === 'NaN' || cell === 'nan') {
+        return '';
+    }
+    return cell;
+}
+function isSparseTemplateRow(row) {
+    const nonEmpty = row.filter((cell) => cell !== '');
+    if (nonEmpty.length === 0) {
+        return true;
+    }
+    // Excel 预留行常在首列保留序号（2、3、…），其余单元格为空。
+    if (nonEmpty.length === 1 && /^\d+\.?\d*$/.test(nonEmpty[0])) {
+        return true;
+    }
+    return false;
+}
+function isSeparatorRow(cells) {
+    return (cells.length > 0 &&
+        cells.every((cell) => {
+            const c = cell.trim();
+            return c === '' || /^:?-{3,}:?$/.test(c);
+        }));
+}
+function padRow(row, width) {
+    const out = row.slice();
+    while (out.length < width) {
+        out.push('');
+    }
+    return out;
+}
+function cleanupTableBlock(lines) {
+    if (lines.length === 0) {
+        return { lines, nanCellsReplaced: 0, rowsRemoved: 0, columnsRemoved: 0 };
+    }
+    let nanCellsReplaced = 0;
+    const rawRows = lines.map(parseTableRow);
+    const colCount = Math.max(...rawRows.map((row) => row.length), 0);
+    if (colCount === 0) {
+        return { lines, nanCellsReplaced: 0, rowsRemoved: 0, columnsRemoved: 0 };
+    }
+    const rows = rawRows.map((row) => padRow(row, colCount).map((cell) => {
+        const normalized = normalizeCell(cell);
+        if (normalized !== cell) {
+            nanCellsReplaced += 1;
+        }
+        return normalized;
+    }));
+    const hasSeparator = rows.length > 1 && isSeparatorRow(rows[1]);
+    const header = rows[0];
+    const dataStart = hasSeparator ? 2 : 1;
+    const dataRowsBefore = rows.slice(dataStart);
+    const dataRows = dataRowsBefore.filter((row) => !isSparseTemplateRow(row));
+    const rowsRemoved = dataRowsBefore.length - dataRows.length;
+    const keepCols = [];
+    for (let col = 0; col < colCount; col += 1) {
+        const headerCell = header[col] ?? '';
+        const dataEmpty = dataRows.every((row) => (row[col] ?? '') === '');
+        if (dataEmpty && (headerCell === '' || UNNAMED_HEADER.test(headerCell))) {
+            continue;
+        }
+        keepCols.push(col);
+    }
+    if (keepCols.length === 0) {
+        keepCols.push(0);
+    }
+    const columnsRemoved = colCount - keepCols.length;
+    const pickCols = (row) => keepCols.map((col) => padRow(row, colCount)[col] ?? '');
+    const out = [];
+    out.push(formatTableRow(pickCols(header)));
+    if (hasSeparator || dataRows.length > 0) {
+        out.push(formatTableRow(keepCols.map(() => '---')));
+    }
+    for (const row of dataRows) {
+        out.push(formatTableRow(pickCols(row)));
+    }
+    return { lines: out, nanCellsReplaced, rowsRemoved, columnsRemoved };
+}
+/**
+ * Clean spreadsheet-derived Markdown document-wide (table blocks only).
+ */
+function cleanupSpreadsheetMarkdown(markdown) {
+    const charsBefore = Buffer.byteLength(markdown, 'utf8');
+    const inputLines = markdown.split(/\r?\n/);
+    const outputLines = [];
+    let nanCellsReplaced = 0;
+    let rowsRemoved = 0;
+    let columnsRemoved = 0;
+    let index = 0;
+    while (index < inputLines.length) {
+        const line = inputLines[index];
+        if (!isTableRow(line)) {
+            outputLines.push(line);
+            index += 1;
+            continue;
+        }
+        const block = [];
+        while (index < inputLines.length && isTableRow(inputLines[index])) {
+            block.push(inputLines[index]);
+            index += 1;
+        }
+        const cleaned = cleanupTableBlock(block);
+        nanCellsReplaced += cleaned.nanCellsReplaced;
+        rowsRemoved += cleaned.rowsRemoved;
+        columnsRemoved += cleaned.columnsRemoved;
+        outputLines.push(...cleaned.lines);
+    }
+    const result = outputLines.join('\n');
+    return {
+        markdown: result,
+        stats: {
+            nanCellsReplaced,
+            rowsRemoved,
+            columnsRemoved,
+            charsBefore,
+            charsAfter: Buffer.byteLength(result, 'utf8'),
+        },
+    };
+}

package/dist/core/next-steps.js

@@ -60,11 +60,24 @@ function printNextSteps(input) {
     lines.push('4. 随时用下面的命令查看进度: ' +
         picocolors_1.default.cyan('cat .harness-build-state.yaml'));
     lines.push('');
-    if (input.hasSource) {
-        lines.push(picocolors_1.default.bold('Baseline Repomix（XML，默认）'));
+    if (input.repomixGenerated) {
+        lines.push(picocolors_1.default.bold('Baseline Repomix（XML）'));
         lines.push('   输出文件: ' + picocolors_1.default.cyan((0, repomix_pack_1.repomixPackRelFile)()));
         lines.push('');
     }
+    else if (input.hasSource) {
+        lines.push(picocolors_1.default.bold('Baseline Repomix（可选，默认关闭）'));
+        lines.push('   适用：大基线整库鸟瞰、只接受单文件上下文的工具、封存留档；' +
+            '日常 S40/S50 以 ' +
+            picocolors_1.default.cyan('baseline/code/') +
+            ' 为准即可');
+        lines.push('   启用：重新 build 并加 ' +
+            picocolors_1.default.cyan('--repomix') +
+            '（须保留 --baseline）→ ' +
+            picocolors_1.default.cyan((0, repomix_pack_1.repomixPackRelFile)()));
+        lines.push('   说明：svharnessbuild README「Repomix」');
+        lines.push('');
+    }
     if (wikiMode === 'tasks') {
         lines.push(picocolors_1.default.bold('Baseline wiki 任务清单已生成（默认 tasks-only 模式）'));
         lines.push('   清单位置: ' + picocolors_1.default.cyan('baseline/wiki/TASKS.md'));

package/dist/core/repomix-apply-hint.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPOMIX_APPLY_HINT_PLACEHOLDER = void 0;
+exports.resolveRepomixPackRel = resolveRepomixPackRel;
+exports.renderRepomixApplyHintMarkdown = renderRepomixApplyHintMarkdown;
+exports.buildRepomixApplyHintReplacement = buildRepomixApplyHintReplacement;
+exports.applyRepomixHintPlaceholder = applyRepomixHintPlaceholder;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const harness_yaml_baseline_1 = require("./harness-yaml-baseline");
+const repomix_pack_1 = require("./repomix-pack");
+exports.REPOMIX_APPLY_HINT_PLACEHOLDER = '__REPOMIX_APPLY_HINT__';
+/**
+ * Resolve Repomix pack path relative to harness root: harness.yaml field first, then file existence.
+ */
+async function resolveRepomixPackRel(harnessRoot) {
+    const doc = await (0, harness_yaml_baseline_1.readHarnessYamlDoc)(harnessRoot);
+    const fromYaml = (0, harness_yaml_baseline_1.getBaselineRepomixPackFromDoc)(doc);
+    if (fromYaml) {
+        const abs = node_path_1.default.join(harnessRoot, fromYaml);
+        if (await fs_extra_1.default.pathExists(abs))
+            return fromYaml;
+    }
+    const defaultRel = (0, repomix_pack_1.repomixPackRelFile)();
+    const defaultAbs = node_path_1.default.join(harnessRoot, defaultRel);
+    if (await fs_extra_1.default.pathExists(defaultAbs))
+        return defaultRel;
+    return undefined;
+}
+function renderRepomixApplyHintMarkdown(input) {
+    const harnessScoped = `./${input.harnessDirName}/${input.packRel.replace(/\\/g, '/')}`;
+    const codeScoped = `./${input.harnessDirName}/baseline/code/`;
+    const body = [
+        '**Baseline Repomix（可选快照）**',
+        '',
+        `- **路径**：\`${input.packRel}\`（项目根视角：\`${harnessScoped}\`）`,
+        '- **用途**：将 `baseline/code/` 打成单文件 XML，便于整库鸟瞰、单文件 attach；与 `baseline/wiki/` 互补。',
+        '- **优先级**：**权威参考实现仍为** `baseline/code/`（行级引用、specs 追溯、守则不变）；Repomix **不得**替代对具体文件的精读，也不得作为 specs 契约来源。',
+        `- **读取**：优先 Read 上述 XML；上下文过大时只读相关片段，或退回 \`${codeScoped}<repo-relative>\`。`,
+        '- **典型场景**：架构摸底、模块边界初扫；实现细节与交付校验仍以 specs + `baseline/code/` 为准。',
+    ];
+    if (input.blockquote) {
+        return ['> Repomix 快照（build 已启用 `--repomix`）', ...body.map((l) => (l ? `> ${l}` : '>'))].join('\n');
+    }
+    return ['## Baseline Repomix（可选快照）', '', ...body].join('\n');
+}
+async function buildRepomixApplyHintReplacement(input) {
+    const packRel = await resolveRepomixPackRel(input.harnessRoot);
+    if (!packRel)
+        return '';
+    const block = renderRepomixApplyHintMarkdown({
+        harnessDirName: input.harnessDirName,
+        packRel,
+        blockquote: input.blockquote,
+    });
+    return `${block}\n\n`;
+}
+function applyRepomixHintPlaceholder(content, hint, placeholder = exports.REPOMIX_APPLY_HINT_PLACEHOLDER) {
+    if (content.includes(placeholder)) {
+        return content.replace(new RegExp(placeholder, 'g'), hint.trimEnd() ? hint : '');
+    }
+    if (!hint.trim())
+        return content;
+    return `${content.trimEnd()}\n\n${hint}`;
+}

package/dist/core/repomix-pack.js

@@ -6,6 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.REPOMIX_PACK_FILENAME = exports.REPOMIX_BASELINE_REL_DIR = void 0;
 exports.repomixPackRelFile = repomixPackRelFile;
 exports.runRepomixPackBaseline = runRepomixPackBaseline;
+/**
+ * Optional baseline snapshot via Repomix (single XML under `baseline/repomix/`).
+ * Enabled only when `svharness build --repomix` is passed with `--baseline`.
+ * Complements `baseline/code/` (per-file references); see svharnessbuild README § Repomix.
+ */
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
 const repomix_1 = require("repomix");

package/dist/index.js

@@ -55,6 +55,7 @@ function buildSectionFromOpts(opts, harnessName) {
         force: opts.force,
         yes: opts.yes,
         verbose: opts.verbose,
+        repomix: opts.repomix,
         generateWiki: opts.generateWiki,
         wikiTasksOnly: opts.wikiTasksOnly,
         wikiLang: opts.wikiLang === 'en' ? 'en' : opts.wikiLang === 'zh' ? 'zh' : undefined,
@@ -87,6 +88,7 @@ async function runBuildAction(opts, cmd) {
             force: !!merged.force,
             yes: !!merged.yes,
             verbose: !!merged.verbose,
+            repomix: !!merged.repomix,
             generateWiki: !!merged.generateWiki,
             wikiTasksOnly: !!merged.wikiTasksOnly,
             wikiLang: merged.wikiLang === 'en' ? 'en' : merged.wikiLang === 'zh' ? 'zh' : undefined,
@@ -120,6 +122,7 @@ function attachBuildOptions(cmd) {
         .option('--arch <arch>', '架构模板：' + (0, validate_args_1.listSupportedArches)().join(' | '), DEFAULT_ARCH)
         .option('--agent <agent>', '目标 Agent：' + (0, validate_args_1.listSupportedAgents)().join(' | '), DEFAULT_AGENT)
         .option('--baseline <path|url>', '【可选】基线源码路径或 Git 仓库地址')
+        .option('--repomix', '【可选，需 --baseline】生成 baseline/repomix/repomix-pack.xml：大基线整库鸟瞰、单文件上下文工具、封存留档；日常 build 默认关闭，详见 README「Repomix」')
         .option('--requirements <path>', '【可选】需求文档输入路径（文件或目录）')
         .option('--references <path>', '【可选】参考资料输入路径（文件或目录）')
         .option('--extra-skills <path...>', '【可选】额外运行期资源（skills/rules 混放，先入 _incoming）')
@@ -231,6 +234,8 @@ function main() {
         .option('--timeout-sec <n>', '【默认 120】超时秒数', (v) => Number(v))
         .option('--type <type>', 'requirements | references')
         .option('--force', '覆盖已存在同名 .md')
+        .option('--split-sheets-suffix <suffix>', 'xlsx/xls 按 sheet（##）拆分时的子目录后缀', '_split')
+        .option('--no-split-sheets', '不将 xlsx/xls 合并 md 按 ## 拆分为多文件')
         .option('-y, --yes', '跳过交互确认')
         .option('--verbose', '显示详细日志')
         .action(async (opts, cmd) => {
@@ -246,6 +251,8 @@ function main() {
                 timeoutSec: opts.timeoutSec,
                 type: opts.type,
                 force: opts.force,
+                splitSheetsSuffix: opts.splitSheetsSuffix,
+                noSplitSheets: opts.noSplitSheets,
                 yes: opts.yes,
                 verbose: opts.verbose,
             }, loaded?.config.convert, loaded?.config.defaults, cmd);
@@ -259,6 +266,8 @@ function main() {
                 timeoutSec: merged.timeoutSec,
                 type: merged.type,
                 force: !!merged.force,
+                splitSheets: merged.noSplitSheets ? false : merged.splitSheets,
+                splitSheetsSuffix: merged.splitSheetsSuffix,
                 yes: !!merged.yes,
                 verbose: !!merged.verbose,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.14.5",
+  "version": "0.14.7",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",

package/templates/_shared/apply-skills/harness-apply-skills-main.md

@@ -21,6 +21,8 @@ description: >
 4. 不修改 `__HARNESS_ROOT_REL__` 下的任何文件；harness 作为只读知识源。
 5. 入口链路以项目根 AI 入口文档为准：`AGENTS.md` 或 `CLAUDE.md`。
 
+__REPOMIX_APPLY_HINT__
+
 ## 典型触发
 
 - 应用 harness-apply-skills-main 完成 xxx 功能开发

package/templates/_shared/build-rules/harness-build-rule-requirements-extraction.md

@@ -28,6 +28,7 @@
    - `description` 必须覆盖 `source_excerpt` 里的条件、数值、枚举、时序，不得退化为标题短语。
    - 推荐使用长度启发式审查：`description` 明显短于 `source_excerpt`（如 < 50%）时标记风险并复核。
    - `title` 仅用于索引，禁止用 `title` 替代完整需求描述。
+   - `source_file` 必须指向 Agent 可读文本：优先 `requirements/md/<同名>.md`（convert 产物），或 `requirements/raw/` 下的 md/txt/代码文件；禁止引用 xlsx/pdf/docx 等难解析格式。
 
 5. **覆盖率报告是 S40 必备产物**
    - 必须生成 `requirements/coverage-report.yaml`。

package/templates/_shared/build-rules/harness-build-rule-specs-schema.md

@@ -28,7 +28,7 @@ specs/
 - `source_excerpt`: 源文档原文摘录（可多行）
 - `description`: 完整需求陈述（不得弱于 source_excerpt）
 - `source_anchor`: 可追踪源锚点（如 `SyRD-*`、章节+行号）
-- `source_file`: 源文件路径（通常在 `requirements/raw/`）
+- `source_file`: Agent 可读的文本源路径——`requirements/md/<同名>.md`（convert 产物）或 `requirements/raw/` 下的 md/txt/代码文件；禁止引用 xlsx/pdf/docx 等难解析格式
 - `source_section`: 源章节或表格区域
 - `aggregates`: 聚合锚点列表（仅在显式聚合时）
 - `aggregation_reason`: 聚合原因（聚合时必填）

package/templates/_shared/build-skills/harness-build-skill-spec-builder.md

@@ -53,7 +53,9 @@ items:
       允许整理语序，但信息集合不得缩小。
     acceptance: "如何验证该需求满足"
     source_anchor: "SyRD-..."
-    source_file: "requirements/raw/<file>"
+    # AI 可读文本源（二选一，禁止引用 xlsx/pdf/docx 等难解析格式）：
+    source_file: "requirements/md/<file>.md"          # 原始为 pdf/xlsx/docx 等 → 引用 convert 产物
+    # source_file: "requirements/raw/<file>.md"       # 或 raw 下本身可读的 md/txt/代码文件
     source_section: "01_Function Spec"
     aggregates: []
     waived: false
@@ -68,7 +70,11 @@ items:
 - `source_excerpt` 必须来自源文档原文；禁止写成「见上文」「同前」等替代语。
 - `description` 必须覆盖 `source_excerpt` 的关键约束；不得删减条件、数值、枚举、时序。
 - `traces_to` 初始可为空，阶段 B 生成 specs 后回填。
-- `source_doc` 与 `source_file` 必须引用真实源文件。
+- `source_doc` 记录原始入库路径（`requirements/raw/<原始文件名>`），用于资产追溯。
+- `source_file` 必须指向 **Agent 可直接读取的文本源**，路径二选一：
+  - `requirements/md/<同名>.md` —— 原始为 pdf/xlsx/docx 等时，引用 S30 convert 后的 Markdown；
+  - `requirements/raw/<file>` —— 原始本身即为 `.md`、`.txt` 或源代码文件（如 `.kt`、`.xml`、`.proto` 等）。
+  - **禁止**将 `requirements/raw/` 下的 xlsx、pdf、docx、图片等 AI 难处理格式写入 `source_file`。
 - 聚合仅在用户确认后允许，且必须带 `aggregates + aggregation_reason`。
 - 产出后必须校验 `requirements/yaml/schema.json`（若存在）；失败不得进入 S50。
 
@@ -93,7 +99,8 @@ items:
 extraction_strategy: md_primary
 generated_at: "..."
 sources:
-  - file: "requirements/raw/<file>"
+  - file: "requirements/md/<file>.md"   # 或 requirements/raw/<可读文本文件>
+    source_doc: "requirements/raw/<原始文件>"   # 可选，保留原始资产路径
     anchors_total: 100
     anchors_mapped: 96
     anchors_waived: 4

package/templates/_shared/meta/AGENTS_APPLY.md.ejs

@@ -100,6 +100,7 @@ __BUILD_MAIN_BRIDGE_HINT__
 |------|------|------|
 | `baseline/wiki/` | 项目知识摘要，优先建立上下文 | 只读 |
 | `baseline/code/` | 权威参考实现 | 只读 |
+| `baseline/repomix/repomix-pack.xml` | 可选：Repomix 整库 XML 快照（仅 build 启用 `--repomix` 时存在；见 `harness.yaml` → `baseline.repomix_pack`） | 只读 |
 | `specs/signals/` | 信号/协议规格 | 只读 |
 | `specs/ui/` | UI 规格 | 只读 |
 | `specs/behavior/` | 行为规格 | 只读 |
@@ -108,6 +109,10 @@ __BUILD_MAIN_BRIDGE_HINT__
 
 > `baseline/code/` 是“参考实现”的权威来源。  
 > 你仍需阅读并修改目标项目业务源码来完成交付，但不得把 `baseline/code/` 之外的路径当作规范样本来源。
+>
+> 若存在 `baseline/repomix/repomix-pack.xml`，清单字段为 `harness.yaml` → `baseline.repomix_pack`；`svharness apply` 会在项目根入口与本 skill 中注入详细用法。
+
+__REPOMIX_APPLY_HINT__
 
 ### 4.3 编码执行
 

package/templates/_shared/meta/harness.yaml.ejs

@@ -43,6 +43,7 @@ references:                              # 参考资料（不参与条目化）
 baseline:
   code: baseline/code/                   # 基线代码快照（参考样本）
   wiki: baseline/wiki/                   # 基线工程 wiki
+  # repomix_pack: baseline/repomix/repomix-pack.xml  # 仅 --repomix 成功后由 CLI 写入
 
 # Agent 运行时环境（规则、技能、工具、记忆）。
 # incoming_* 仅构建期：`svharness build --extra-skills` 将资源暂存于此并生成 manifest，S65 确认后分流写入 rules/skills。

package/templates/_shared/skeleton/requirements/yaml/schema.json

@@ -49,7 +49,11 @@
           "description": { "type": "string", "minLength": 1 },
           "acceptance": { "type": "string", "minLength": 1 },
           "source_anchor": { "type": "string", "minLength": 1 },
-          "source_file": { "type": "string", "minLength": 1 },
+          "source_file": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Agent 可读文本源：requirements/md/<同名>.md（convert 产物）或 requirements/raw/ 下的 md/txt/代码文件；禁止 xlsx/pdf/docx 等"
+          },
           "source_section": { "type": "string", "minLength": 1 },
           "aggregates": {
             "type": "array",

package/templates/svharness.config.example.yaml

@@ -20,6 +20,9 @@ build:
   referencesNote: 设计稿与接口文档
   extraSkills:
     - ./team-skills/custom-skill
+  # Repomix：将 baseline/code 打成单文件 baseline/repomix/repomix-pack.xml（默认 false）
+  # 适合：大基线整库鸟瞰、外部单文件上下文工具、封存留档；日常 harness-build 不必开
+  repomix: false
   generateWiki: false
   wikiLang: zh
   force: false