svharness 0.14.2 → 0.14.7

package/README.md

@@ -109,13 +109,14 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 ├── requirements/                   # 正式需求（参与条目化）
 │   ├── raw/                        #   S20_collect_inputs 用户入口
 │   ├── md/                         #   convert 产物
-│   └── yaml/                       #   S40 条目化产出
+│   └── yaml/                       #   S40 条目化产出（含 schema.json）
 ├── references/                     # 参考资料（不参与条目化）
 │   ├── raw/
 │   ├── md/
 │   └── yaml/
 └── baseline/
     ├── code/                       #   参考代码快照
+    ├── repomix/                    #   可选：`--repomix` 时生成的单文件 XML 快照
     └── wiki/                       #   架构 wiki
 │
 ├── agent-env/                    # Agent 运行期环境
@@ -185,8 +186,8 @@ harness-build-{skill|rule}-<semantic-name>
 | **S10_wiki** | 构建 baseline wiki（仅当有 baseline 时出现，项目经验底座） | `baseline/wiki/` |
 | **S20_collect_inputs** | 添加相关文件：需求/参考文档 + 额外运行期资源征询（`--extra-skills` 单入口，可混放 skills/rules） | `requirements/raw/` + `references/raw/` + `agent-env/_incoming/skills/` + `task_list.md` |
 | **S30_convert_docs** | 非 Markdown 原始文档转 Markdown | `requirements/md/` + `references/md/` |
-| **S40_extract_requirements** | 条目化需求 + 覆盖率门禁 | `requirements/yaml/*.yaml` + `requirements/coverage-report.yaml` |
-| **S50_generate_specs** | 生成规格 + REQ→spec 覆盖 | `specs/<layer>/<module>.<layer>.yaml` + schema 校验 + 覆盖率结果 |
+| **S40_extract_requirements** | 条目化需求 + 覆盖率门禁 + 保真门禁（`title/source_excerpt/description`） | `requirements/yaml/*.yaml` + `requirements/yaml/schema.json` + `requirements/coverage-report.yaml` |
+| **S50_generate_specs** | 生成规格 + REQ→spec 覆盖 + 深度门禁（非 index-only） | `specs/<layer>/<module>.<layer>.yaml` + schema 校验 + 覆盖率结果 |
 | **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/` |
@@ -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 应：
@@ -426,11 +460,19 @@ svharness doctor --harness ./my-app-harness --mode pre-seal --format json --repo
 - **门禁**：`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 表单门禁负责。
+同时新增：
+
+- `check-requirements-fidelity`：检查 `source_excerpt` 缺失、`description` 缩略与占位语义。
+- `check-specs-depth`：检查 index-only 信号、enum 缺失 `enum_values`、behavior 空 `guard/action`。
 
 ### `convert` —— 文档 → Markdown 预处理（对接 S20_collect_inputs）
 
 把本地原始需求文档（`.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
@@ -460,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` |
 
@@ -699,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/doctor/check-requirements-fidelity.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRequirementsFidelity = checkRequirementsFidelity;
+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 utils_1 = require("./utils");
+const TRUNCATION_HINT_RE = /(详见原文|见上文|同前|tbd|placeholder|…|\.{3,})/i;
+const MIN_EXCERPT_LEN = 20;
+const WARN_RATIO = 0.5;
+const ERROR_RATIO = 0.25;
+function normalizeLength(v) {
+    if (typeof v !== 'string')
+        return 0;
+    return v.replace(/\s+/g, '').length;
+}
+async function checkRequirementsFidelity(ctx) {
+    const id = 'requirements-fidelity';
+    const findings = [];
+    const yamlDir = node_path_1.default.join(ctx.harnessRoot, 'requirements', 'yaml');
+    const reqYamlFiles = (await (0, utils_1.listRealFilesRecursive)(yamlDir, { extensions: ['.yaml', '.yml'] })).filter((f) => !f.endsWith('schema.json'));
+    for (const yamlFile of reqYamlFiles) {
+        let parsed;
+        try {
+            parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(yamlFile, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const items = parsed?.items;
+        if (!Array.isArray(items))
+            continue;
+        for (const [idx, item] of items.entries()) {
+            const obj = (item ?? {});
+            const itemId = typeof obj.id === 'string' ? obj.id : `#${idx + 1}`;
+            const excerpt = typeof obj.source_excerpt === 'string' ? obj.source_excerpt : '';
+            const desc = typeof obj.description === 'string' ? obj.description : '';
+            const excerptLen = normalizeLength(excerpt);
+            const descLen = normalizeLength(desc);
+            const ratio = excerptLen > 0 ? descLen / excerptLen : 1;
+            const itemPath = `${(0, utils_1.rel)(ctx.harnessRoot, yamlFile)}:${itemId}`;
+            if (excerptLen === 0) {
+                findings.push({
+                    checkId: id,
+                    severity: 'error',
+                    message: 'source_excerpt 为空，无法证明需求保留了源文档信息',
+                    path: itemPath,
+                });
+            }
+            else if (excerptLen < MIN_EXCERPT_LEN) {
+                findings.push({
+                    checkId: id,
+                    severity: 'warning',
+                    message: `source_excerpt 过短（${excerptLen}），建议补充完整原文摘录`,
+                    path: itemPath,
+                });
+            }
+            if (!desc.trim()) {
+                findings.push({
+                    checkId: id,
+                    severity: 'error',
+                    message: 'description 为空，缺少完整需求陈述',
+                    path: itemPath,
+                });
+            }
+            else if (ratio < ERROR_RATIO) {
+                findings.push({
+                    checkId: id,
+                    severity: ctx.mode === 'pre-seal' ? 'error' : 'warning',
+                    message: `description 相对 source_excerpt 明显缩略（ratio=${ratio.toFixed(2)}）`,
+                    path: itemPath,
+                });
+            }
+            else if (ratio < WARN_RATIO) {
+                findings.push({
+                    checkId: id,
+                    severity: 'warning',
+                    message: `description 可能缩略 source_excerpt（ratio=${ratio.toFixed(2)}）`,
+                    path: itemPath,
+                });
+            }
+            if (TRUNCATION_HINT_RE.test(excerpt) || TRUNCATION_HINT_RE.test(desc)) {
+                findings.push({
+                    checkId: id,
+                    severity: 'warning',
+                    message: '检测到截断/占位语义（如 详见原文、TBD、placeholder）',
+                    path: itemPath,
+                });
+            }
+        }
+    }
+    return { id, title: '需求保真度', findings };
+}

package/dist/commands/doctor/check-requirements.js

@@ -7,6 +7,8 @@ exports.checkRequirements = checkRequirements;
 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 ajv_1 = __importDefault(require("ajv"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
 const utils_1 = require("./utils");
 async function checkRequirements(ctx) {
     const id = 'requirements';
@@ -35,6 +37,24 @@ async function checkRequirements(ctx) {
         }
     }
     else {
+        const schemaPath = node_path_1.default.join(yamlDir, 'schema.json');
+        let validate;
+        if (await fs_extra_1.default.pathExists(schemaPath)) {
+            try {
+                const schema = JSON.parse(await fs_extra_1.default.readFile(schemaPath, 'utf8'));
+                const ajv = new ajv_1.default({ allErrors: true, strict: false });
+                (0, ajv_formats_1.default)(ajv);
+                validate = ajv.compile(schema);
+            }
+            catch (err) {
+                findings.push({
+                    checkId: id,
+                    severity: 'error',
+                    message: `requirements/yaml/schema.json 无效：${err.message}`,
+                    path: 'requirements/yaml/schema.json',
+                });
+            }
+        }
         for (const file of yamlFiles) {
             try {
                 const raw = await fs_extra_1.default.readFile(file, 'utf8');
@@ -47,7 +67,19 @@ async function checkRequirements(ctx) {
                     });
                     continue;
                 }
-                js_yaml_1.default.load(raw);
+                const parsed = js_yaml_1.default.load(raw);
+                if (validate && !validate(parsed)) {
+                    const detail = (validate.errors ?? [])
+                        .slice(0, 3)
+                        .map((e) => `${e.instancePath || '/'} ${e.message}`)
+                        .join('; ');
+                    findings.push({
+                        checkId: id,
+                        severity: 'error',
+                        message: `requirements schema 校验失败：${detail}`,
+                        path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                    });
+                }
             }
             catch (err) {
                 findings.push({

package/dist/commands/doctor/check-specs-depth.js

@@ -0,0 +1,165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSpecsDepth = checkSpecsDepth;
+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 utils_1 = require("./utils");
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+async function getEnabledLayers(harnessRoot) {
+    const { doc } = await (0, utils_1.readHarnessYaml)(harnessRoot);
+    const layers = asArray(doc?.specs?.layers);
+    const enabled = new Set();
+    for (const l of layers) {
+        const name = l?.name;
+        if (name === 'signals' || name === 'behavior' || name === 'interfaces' || name === 'ui') {
+            enabled.add(name);
+        }
+    }
+    if (enabled.size === 0) {
+        enabled.add('signals');
+        enabled.add('behavior');
+        enabled.add('interfaces');
+        enabled.add('ui');
+    }
+    return enabled;
+}
+async function getDepthThresholds(harnessRoot) {
+    const defaults = {
+        warnThreshold: 0.5,
+        failThreshold: 0.8,
+    };
+    const { doc } = await (0, utils_1.readHarnessYaml)(harnessRoot);
+    const arch = doc?.arch?.trim();
+    const candidates = [
+        arch ? node_path_1.default.join(harnessRoot, 'agent-env', 'review-profiles', `${arch}.yaml`) : '',
+        node_path_1.default.join(harnessRoot, 'agent-env', 'review-profiles', '_default.yaml'),
+    ].filter(Boolean);
+    for (const file of candidates) {
+        if (!(await fs_extra_1.default.pathExists(file)))
+            continue;
+        try {
+            const parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(file, 'utf8'));
+            const heuristics = (parsed?.heuristics ?? {});
+            const fail = Number(heuristics.index_signal_id_ratio_threshold);
+            if (!Number.isNaN(fail) && fail > 0 && fail <= 1) {
+                return {
+                    warnThreshold: Math.max(0.1, Math.min(0.95, fail * 0.7)),
+                    failThreshold: fail,
+                };
+            }
+        }
+        catch {
+            // ignore invalid profile and fall back
+        }
+    }
+    return defaults;
+}
+async function scanSignalsDepth(ctx, findings, warnThreshold, failThreshold) {
+    const signalsDir = node_path_1.default.join(ctx.harnessRoot, 'specs', 'signals');
+    const files = (await (0, utils_1.listRealFilesRecursive)(signalsDir, { extensions: ['.yaml', '.yml'] })).filter((f) => !f.endsWith('schema.json'));
+    let totalSignals = 0;
+    let indexOnlySignals = 0;
+    for (const file of files) {
+        let parsed;
+        try {
+            parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const signals = asArray(parsed?.signals);
+        for (const sig of signals) {
+            totalSignals++;
+            const id = typeof sig.id === 'string' ? sig.id : '';
+            const hasDescription = typeof sig.description === 'string' && sig.description.trim().length >= 8;
+            const hasEnumValues = Array.isArray(sig.enum_values) && sig.enum_values.length > 0;
+            const hasLength = typeof sig.length_bytes === 'number';
+            const isEnum = sig.type === 'enum';
+            const maybeIndexOnly = /^CMDID_[A-Z0-9_]+$/.test(id) && !hasDescription && !hasLength && (!isEnum || !hasEnumValues);
+            if (maybeIndexOnly) {
+                indexOnlySignals++;
+            }
+            if (isEnum && !hasEnumValues) {
+                findings.push({
+                    checkId: 'specs-depth',
+                    severity: 'warning',
+                    message: `enum 信号缺少 enum_values（${id || 'unknown-id'}）`,
+                    path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                });
+            }
+        }
+    }
+    if (totalSignals === 0)
+        return;
+    const ratio = indexOnlySignals / totalSignals;
+    if (ratio >= failThreshold) {
+        findings.push({
+            checkId: 'specs-depth',
+            severity: 'error',
+            message: `signals 索引式占比过高（${indexOnlySignals}/${totalSignals}=${ratio.toFixed(2)}）`,
+            path: 'specs/signals',
+        });
+    }
+    else if (ratio >= warnThreshold) {
+        findings.push({
+            checkId: 'specs-depth',
+            severity: 'warning',
+            message: `signals 索引式占比偏高（${indexOnlySignals}/${totalSignals}=${ratio.toFixed(2)}）`,
+            path: 'specs/signals',
+        });
+    }
+}
+async function scanBehaviorDepth(ctx, findings) {
+    const behaviorDir = node_path_1.default.join(ctx.harnessRoot, 'specs', 'behavior');
+    const files = (await (0, utils_1.listRealFilesRecursive)(behaviorDir, { extensions: ['.yaml', '.yml'] })).filter((f) => !f.endsWith('schema.json'));
+    for (const file of files) {
+        let parsed;
+        try {
+            parsed = js_yaml_1.default.load(await fs_extra_1.default.readFile(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const transitions = asArray(parsed?.transitions);
+        for (const t of transitions) {
+            const trigger = typeof t.trigger === 'string' ? t.trigger : 'unknown-trigger';
+            const guard = typeof t.guard === 'string' ? t.guard.trim() : '';
+            const action = typeof t.action === 'string' ? t.action.trim() : '';
+            if (!guard || /^见需求|^tbd|placeholder/i.test(guard)) {
+                findings.push({
+                    checkId: 'specs-depth',
+                    severity: 'warning',
+                    message: `transition.guard 为空或占位（${trigger}）`,
+                    path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                });
+            }
+            if (!action || /^见需求|^tbd|placeholder/i.test(action)) {
+                findings.push({
+                    checkId: 'specs-depth',
+                    severity: 'warning',
+                    message: `transition.action 为空或占位（${trigger}）`,
+                    path: (0, utils_1.rel)(ctx.harnessRoot, file),
+                });
+            }
+        }
+    }
+}
+async function checkSpecsDepth(ctx) {
+    const id = 'specs-depth';
+    const findings = [];
+    const enabledLayers = await getEnabledLayers(ctx.harnessRoot);
+    const { warnThreshold, failThreshold } = await getDepthThresholds(ctx.harnessRoot);
+    if (enabledLayers.has('signals')) {
+        await scanSignalsDepth(ctx, findings, warnThreshold, failThreshold);
+    }
+    if (enabledLayers.has('behavior')) {
+        await scanBehaviorDepth(ctx, findings);
+    }
+    return { id, title: 'Specs 深度启发式', findings };
+}

package/dist/commands/doctor/index.js

@@ -45,7 +45,9 @@ const check_empty_dirs_1 = require("./check-empty-dirs");
 const check_convert_pairing_1 = require("./check-convert-pairing");
 const check_requirements_1 = require("./check-requirements");
 const check_requirements_coverage_1 = require("./check-requirements-coverage");
+const check_requirements_fidelity_1 = require("./check-requirements-fidelity");
 const check_specs_1 = require("./check-specs");
+const check_specs_depth_1 = require("./check-specs-depth");
 const check_references_1 = require("./check-references");
 const check_skills_tasks_1 = require("./check-skills-tasks");
 const check_memory_1 = require("./check-memory");
@@ -74,7 +76,9 @@ async function runDoctorChecks(input) {
         check_convert_pairing_1.checkConvertPairing,
         check_requirements_1.checkRequirements,
         check_requirements_coverage_1.checkRequirementsCoverage,
+        check_requirements_fidelity_1.checkRequirementsFidelity,
         check_specs_1.checkSpecs,
+        check_specs_depth_1.checkSpecsDepth,
         check_references_1.checkReferences,
         check_skills_tasks_1.checkSkillsTasks,
         check_memory_1.checkMemory,

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),
     };