svharness 0.8.0 → 0.13.2

package/dist/core/state.js

@@ -10,49 +10,69 @@ const node_path_1 = __importDefault(require("node:path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const logger_1 = require("../utils/logger");
 /**
- * Build the initial state object. P-1 is DONE (skeleton just created);
- * everything else starts PENDING. `P1_wiki` is conditional on
+ * Build the initial state object. S00 is DONE (skeleton just created);
+ * everything else starts PENDING. `S10_wiki` is conditional on
  * `wikiPhase` (only present when project has baseline).
  *
- * Phase order: P-1_skeleton → [P1_wiki] → P2_raw → P3_requirements → P4_specs
- *   → P5_rules → P6_skills_tasks → P7_memory → P-Final_seal
+ * Phase order: S00_bootstrap → [S10_wiki] → S20_collect_inputs → S30_convert_docs → S40_extract_requirements
+ *   → S50_generate_specs → S60_process_references → S61_confirm_baseline_extraction
+ *   → S65_customize_agent_env → S70_runtime_assets → S80_seed_memory → S90_finalize
  *
- * Design: P1_wiki comes before P2_raw because baseline wiki is the project
+ * Design: S10_wiki comes before S20_collect_inputs because baseline wiki is the project
  * experience foundation — it provides architectural knowledge that helps the
- * user write better requirement documents. When no baseline, P1_wiki is
- * absent and the flow starts from P2_raw.
+ * user write better requirement documents. When no baseline, S10_wiki is
+ * absent and the flow starts from S20_collect_inputs.
  */
 function buildInitialState(input) {
     const phases = {
-        'P-1_skeleton': { status: 'DONE' },
+        S00_bootstrap: { status: 'DONE' },
     };
     const wp = input.wikiPhase ?? 'none';
-    // P1_wiki: baseline wiki (project experience foundation) — only when baseline exists
+    // S10_wiki: baseline wiki (project experience foundation) — only when baseline exists
     if (wp === 'done') {
-        phases.P1_wiki = { status: 'DONE', requires_agent: false, mode: 'full', source: 'cli-full' };
+        phases.S10_wiki = { status: 'DONE', requires_agent: false, mode: 'full', source: 'cli-full' };
     }
     else if (wp === 'pending') {
-        phases.P1_wiki = {
+        phases.S10_wiki = {
             status: 'PENDING',
             requires_agent: true,
             mode: 'outline-only',
             source: input.wikiSource ?? 'cli-tasks',
-            tasks_file: 'assets/baseline/wiki/TASKS.md',
+            tasks_file: 'baseline/wiki/TASKS.md',
         };
     }
-    // P2_raw: user adds requirement documents (can reference wiki for context)
-    phases.P2_raw = { status: 'PENDING', manual_required: true };
-    phases.P3_requirements = { status: 'PENDING', requires_agent: true };
-    phases.P4_specs = { status: 'PENDING', requires_agent: true };
-    phases.P5_rules = { status: 'PENDING', manual_required: true };
-    phases.P6_skills_tasks = { status: 'PENDING', requires_agent: true };
-    phases.P7_memory = { status: 'PENDING', requires_agent: true };
-    phases['P-Final_seal'] = { status: 'PENDING' };
-    // current_phase starts at P1_wiki (if present) or P2_raw (if no baseline)
-    const startPhase = wp !== 'none' ? 'P1_wiki' : 'P2_raw';
+    // S20_collect_inputs: collect related inputs (requirements/references/optional extra skills & rules)
+    phases.S20_collect_inputs = { status: 'PENDING', manual_required: true };
+    // S30_convert_docs: convert non-md raw docs to markdown for downstream entry-ization
+    phases.S30_convert_docs = { status: 'PENDING', requires_agent: true };
+    phases.S40_extract_requirements = { status: 'PENDING', requires_agent: true };
+    phases.S50_generate_specs = { status: 'PENDING', requires_agent: true };
+    // S60: references convert + structured indexing
+    phases.S60_process_references = { status: 'PENDING', requires_agent: true };
+    // S61: explicitly confirm whether baseline auto-extraction (skills/rules) is enabled
+    phases.S61_confirm_baseline_extraction = {
+        status: 'PENDING',
+        manual_required: true,
+        baseline_auto_extract: 'UNSET',
+    };
+    // S65: merge extra-skills / extra-rules with user-confirmed conflict handling
+    phases.S65_customize_agent_env = {
+        status: 'PENDING',
+        manual_required: true,
+        incoming_total: 0,
+        skills_count: 0,
+        rules_count: 0,
+        unknown_count: 0,
+        conflicts_resolved: 0,
+    };
+    phases.S70_runtime_assets = { status: 'PENDING', requires_agent: true };
+    phases.S80_seed_memory = { status: 'PENDING', requires_agent: true };
+    phases.S90_finalize = { status: 'PENDING' };
+    // current_phase starts at S10_wiki (if present) or S20_collect_inputs (if no baseline)
+    const startPhase = wp !== 'none' ? 'S10_wiki' : 'S20_collect_inputs';
     const startAction = wp !== 'none'
-        ? '请先构建 baseline wiki（项目经验底座），完成后继续下一步。'
-        : '请将原始需求文档放入 assets/raw/ 目录后，告诉 Agent 继续构建。';
+        ? '请先构建 baseline wiki（项目经验底座），完成后进入 S20 输入文件收集。'
+        : '请先完成 S20 输入文件收集：requirements/raw、references/raw，并确认是否有额外 skills/rules。';
     const state = {
         project: input.name,
         arch: input.arch,

package/dist/index.js

@@ -4,70 +4,124 @@ const commander_1 = require("commander");
 const logger_1 = require("./utils/logger");
 const version_1 = require("./utils/version");
 const validate_args_1 = require("./utils/validate-args");
+const harness_name_1 = require("./utils/harness-name");
 const init_1 = require("./commands/init");
 const apply_1 = require("./commands/apply");
+const convert_1 = require("./commands/convert");
+const wizard_1 = require("./commands/wizard");
+const config_1 = require("./config");
 /**
  * Default values surfaced to users (also reflected in README "全部参数" tables).
- *
- * Keep this list in one place so README, banner help text and command options
- * stay in sync. Updating a default here is a *single* source of truth change.
  */
 const DEFAULT_ARCH = 'android-compose';
 const DEFAULT_AGENT = 'codechat';
-/**
- * Resolve `--harness-name` / `--name` (alias) into a single value and emit a
- * deprecation warning when only the legacy `--name` form is used.
- */
 function resolveHarnessName(opts) {
     if (opts.harnessName && opts.name && opts.harnessName !== opts.name) {
         throw new Error('同时收到 --harness-name 与 --name 但取值不同，请只保留一个（推荐 --harness-name）');
     }
-    if (opts.harnessName)
-        return opts.harnessName;
-    if (opts.name) {
+    const raw = opts.harnessName ?? opts.name;
+    if (!raw) {
+        throw new Error('--harness-name <name> 是必填参数（可在配置文件的 build.harnessName 中提供）');
+    }
+    if (opts.name && !opts.harnessName) {
         logger_1.logger.warn('⚠️  --name 已重命名为 --harness-name，旧名将在下个 minor 版本移除。');
-        return opts.name;
     }
-    throw new Error('--harness-name <name> 是必填参数');
+    const check = (0, harness_name_1.validateHarnessNameInput)(raw);
+    if (!check.ok) {
+        throw new Error(check.message);
+    }
+    if (check.normalized !== raw.trim()) {
+        logger_1.logger.info(`harness 名称已规范为 ${check.normalized}（目录：${check.normalized}-harness）`);
+    }
+    return check.normalized;
 }
-async function runBuildAction(opts) {
+function buildSectionFromOpts(opts, harnessName) {
+    return {
+        harnessName,
+        arch: opts.arch,
+        agent: opts.agent,
+        baseline: opts.baseline,
+        requirements: opts.requirements,
+        references: opts.references,
+        extraSkills: opts.extraSkills,
+        baselineBranch: opts.baselineBranch,
+        baselineMaxFileKb: opts.baselineMaxFileKb,
+        convertEndpoint: opts.convertEndpoint,
+        convertConcurrency: opts.convertConcurrency,
+        convertMaxFileMb: opts.convertMaxFileMb,
+        convertTimeoutSec: opts.convertTimeoutSec,
+        convertForce: opts.convertForce,
+        force: opts.force,
+        yes: opts.yes,
+        verbose: opts.verbose,
+        generateWiki: opts.generateWiki,
+        wikiTasksOnly: opts.wikiTasksOnly,
+        wikiLang: opts.wikiLang === 'en' ? 'en' : opts.wikiLang === 'zh' ? 'zh' : undefined,
+        wikiModel: opts.wikiModel,
+        wikiBaseUrl: opts.wikiBaseUrl,
+        wikiApiKey: opts.wikiApiKey,
+        wikiSource: opts.wikiSource,
+    };
+}
+async function runBuildAction(opts, cmd) {
     try {
-        const harnessName = resolveHarnessName(opts);
+        const loaded = (0, config_1.loadConfig)({ configPath: opts.config });
+        const merged = (0, config_1.mergeBuildOptions)(opts, loaded?.config.build, loaded?.config.defaults, cmd);
+        const harnessName = resolveHarnessName(merged);
         await (0, init_1.runInit)({
             name: harnessName,
-            arch: opts.arch,
-            agent: opts.agent,
-            baseline: opts.baseline,
-            baselineBranch: opts.baselineBranch,
-            baselineMaxFileKB: opts.baselineMaxFileKb,
-            force: !!opts.force,
-            yes: !!opts.yes,
-            verbose: !!opts.verbose,
-            generateWiki: !!opts.generateWiki,
-            wikiTasksOnly: !!opts.wikiTasksOnly,
-            wikiLang: opts.wikiLang === 'en' ? 'en' : opts.wikiLang === 'zh' ? 'zh' : undefined,
-            wikiModel: opts.wikiModel,
-            wikiBaseUrl: opts.wikiBaseUrl,
-            wikiApiKey: opts.wikiApiKey,
-            wikiSource: opts.wikiSource,
+            arch: (merged.arch ?? DEFAULT_ARCH),
+            agent: (merged.agent ?? DEFAULT_AGENT),
+            baseline: merged.baseline,
+            requirements: merged.requirements,
+            references: merged.references,
+            extraSkills: merged.extraSkills,
+            baselineBranch: merged.baselineBranch,
+            baselineMaxFileKB: merged.baselineMaxFileKb,
+            convertEndpoint: merged.convertEndpoint,
+            convertConcurrency: merged.convertConcurrency,
+            convertMaxFileMB: merged.convertMaxFileMb,
+            convertTimeoutSec: merged.convertTimeoutSec,
+            convertForce: merged.convertForce,
+            force: !!merged.force,
+            yes: !!merged.yes,
+            verbose: !!merged.verbose,
+            generateWiki: !!merged.generateWiki,
+            wikiTasksOnly: !!merged.wikiTasksOnly,
+            wikiLang: merged.wikiLang === 'en' ? 'en' : merged.wikiLang === 'zh' ? 'zh' : undefined,
+            wikiModel: merged.wikiModel,
+            wikiBaseUrl: merged.wikiBaseUrl,
+            wikiApiKey: merged.wikiApiKey,
+            wikiSource: merged.wikiSource,
         });
+        if (opts.saveConfig !== undefined && opts.saveConfig !== false) {
+            const outPath = typeof opts.saveConfig === 'string' && opts.saveConfig.trim()
+                ? opts.saveConfig
+                : undefined;
+            const saved = await (0, config_1.saveConfigSection)({
+                outPath,
+                build: buildSectionFromOpts(merged, harnessName),
+            });
+            logger_1.logger.success(`当前参数已写入配置：${saved}`);
+        }
     }
     catch (err) {
         logger_1.logger.error(err.message);
         process.exitCode = 1;
     }
 }
-/**
- * Attach all options shared between `build` and the legacy `init` alias.
- * Centralised so the two stay byte-for-byte identical.
- */
 function attachBuildOptions(cmd) {
     return cmd
-        .option('--harness-name <name>', '【必填】harness 名称（小写字母、数字、中连线），生成 <name>-harness/ 目录')
+        .option('--config <path>', `从 YAML/JSON 读取参数（默认可选 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
+        .option('--save-config [path]', `执行成功后把参数写入配置文件（默认 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
+        .option('--harness-name <name>', '【必填】harness 名称（如 my-app → .my-app-harness/ 目录）')
         .option('--name <name>', '【已废弃】--harness-name 的旧别名，下个 minor 版本移除')
         .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('--requirements <path>', '【可选】需求文档输入路径（文件或目录）')
+        .option('--references <path>', '【可选】参考资料输入路径（文件或目录）')
+        .option('--extra-skills <path...>', '【可选】额外运行期资源（skills/rules 混放，先入 _incoming）')
         .option('--baseline-branch <name>', '【Git 模式】指定分支名（默认：main）')
         .option('--baseline-max-file-kb <kb>', '【过滤】单文件大小上限 KB（默认：1024）', (v) => {
         const n = Number(v);
@@ -76,16 +130,21 @@ function attachBuildOptions(cmd) {
         }
         return n;
     })
+        .option('--convert-endpoint <url>', '【build 自动 convert】markitdown_serve 基址（默认 http://markitdown.desaysz.site）')
+        .option('--convert-concurrency <n>', '【build 自动 convert】并发上传数（默认沿用 convert）', (v) => Number(v))
+        .option('--convert-max-file-mb <n>', '【build 自动 convert】单文件大小上限 MB（默认沿用 convert）', (v) => Number(v))
+        .option('--convert-timeout-sec <n>', '【build 自动 convert】超时秒数（默认沿用 convert）', (v) => Number(v))
+        .option('--convert-force', '【build 自动 convert】覆盖已存在同名 .md')
         .option('--force', '强制覆盖已存在的目标目录')
         .option('-y, --yes', '跳过交互确认，使用默认值')
         .option('--verbose', '显示详细日志')
         .option('--generate-wiki', '【Wiki】自动生成完整 Wiki 文档（需 --baseline）')
-        .option('--wiki-tasks-only', '【Wiki】仅生成 Wiki 大纲和任务列表，由 Agent 后续撰写（有 --baseline 时为隐式默认）')
+        .option('--wiki-tasks-only', '【Wiki】仅生成 Wiki 大纲和任务列表（有 --baseline 时为隐式默认）')
         .option('--wiki-lang <lang>', '【Wiki】输出语言：zh（默认）| en')
-        .option('--wiki-model <model>', '【Wiki】AI 模型名称（覆写默认配置）')
+        .option('--wiki-model <model>', '【Wiki】AI 模型名称')
         .option('--wiki-base-url <url>', '【Wiki】OpenAI 兼容 API 地址')
         .option('--wiki-api-key <key>', '【Wiki】API 密钥')
-        .option('--wiki-source <path>', '【Wiki】扫描的源码根路径（默认：--baseline 或当前目录）');
+        .option('--wiki-source <path>', '【Wiki】扫描的源码根路径');
 }
 function main() {
     const program = new commander_1.Command();
@@ -97,132 +156,145 @@ function main() {
         .helpOption('-h, --help', '显示帮助信息');
     const banner = [
         '',
-        '╔══════════════════════════════════════════════════════════════════════════╗',
-        '║                    svharness v' + version.padEnd(33) + '║',
-        '╠══════════════════════════════════════════════════════════════════════════╣',
-        '║  规格驱动开发（SDD）AI 协作框架脚手架                                      ║',
-        '║  为任意 Agent IDE 生成项目本地知识层骨架（harness）                          ║',
-        '╠══════════════════════════════════════════════════════════════════════════╣',
-        '║  支持架构：android-compose | android-xml | cpp | web-react | python          ║',
-        '║  支持 Agent：codechat | qoder | cursor | claude-code | generic           ║',
-        '║  运行要求：Node.js ≥ 18                                                   ║',
-        '╚══════════════════════════════════════════════════════════════════════════╝',
+        '╔══════════════════════════════════════════════════════════════════════════',
+        '║                    svharness v' + version.padEnd(33) + '',
+        '╠══════════════════════════════════════════════════════════════════════════',
+        '║  规格驱动开发（SDD）AI 协作框架脚手架                                      ',
+        '║  为任意 Agent IDE 生成项目本地知识层骨架（harness）                          ',
+        '╠══════════════════════════════════════════════════════════════════════════',
+        '║  支持架构：android-compose | android-xml | cpp | web-react | python          ',
+        '║  支持 Agent：codechat | qoder | cursor | claude-code | opencode | generic ',
+        '║  运行要求：Node.js ≥ 18                                                   ',
+        '╚══════════════════════════════════════════════════════════════════════════',
         '',
     ].join('\n');
     program.addHelpText('beforeAll', banner);
     program.addHelpText('afterAll', [
         '',
-        '┌──────────────────────────────────────────────────────────────────────────┐',
-        '│  📖 快速上手                                                             │',
-        '├──────────────────────────────────────────────────────────────────────────┤',
-        '│                                                                          │',
-        '│  # 方式一：交互式创建（仅 --harness-name 必填，其余取默认值）              │',
-        '│  svharness build --harness-name my-app                                   │',
-        '│                                                                          │',
-        '│  # 方式二：本地基线 + 自动生成 wiki                                       │',
-        '│  svharness build \\                                                       │',
-        '│    --harness-name my-app \\                                               │',
-        '│    --baseline your_project_dir \\                                         │',
-        '│    --generate-wiki \\                                                     │',
-        '│    --yes                                                                 │',
-        '│                                                                          │',
-        '│  # 方式三：Git 基线（指定分支与单文件上限）                                │',
-        '│  svharness build \\                                                       │',
-        '│    --harness-name my-app \\                                               │',
-        '│    --baseline git@github.com:your/repo.git \\                             │',
-        '│    --baseline-branch main \\                                              │',
-        '│    --baseline-max-file-kb 1024 \\                                         │',
-        '│    --generate-wiki                                                       │',
-        '│                                                                          │',
-        '│  # 方式四：把已构建好的 harness 绑定到目标项目                             │',
-        '│  svharness apply \\                                                       │',
-        '│    --harness ./my-app-harness \\                                          │',
-        '│    --target . \\                                                          │',
-        '│    --yes                                                                 │',
-        '│                                                                          │',
-        '└──────────────────────────────────────────────────────────────────────────┘',
-        '',
-        '┌──────────────────────────────────────────────────────────────────────────┐',
-        '│  📋 build 参数说明（含默认值）                                             │',
-        '├──────────────────────────────────────────────────────────────────────────┤',
-        '│                                                                          │',
-        '│  必填参数：                                                               │',
-        '│    --harness-name <name>  harness 名称（小写字母、数字、中连线）           │',
-        '│                                                                          │',
-        '│  含默认值参数：                                                           │',
-        '│    --arch <架构>          默认：android-compose                           │',
-        '│    --agent <Agent>        默认：codechat                                  │',
-        '│    --wiki-lang <语言>     默认：zh                                        │',
-        '│    --baseline-branch      默认：main（仅 git 模式）                       │',
-        '│    --baseline-max-file-kb 默认：1024                                      │',
-        '│                                                                          │',
-        '│  可选开关：                                                               │',
-        '│    --baseline <路径|URL>  本地目录或 Git 仓库地址                          │',
-        '│    --generate-wiki        自动生成完整 Wiki                                │',
-        '│    --wiki-tasks-only      仅生成 Wiki 大纲（有 --baseline 时为隐式默认）   │',
-        '│    --force                覆盖已存在的目标目录                             │',
-        '│    -y, --yes              跳过交互确认                                    │',
-        '│    --verbose              显示详细日志                                    │',
-        '│                                                                          │',
-        '└──────────────────────────────────────────────────────────────────────────┘',
-        '',
-        '┌──────────────────────────────────────────────────────────────────────────┐',
-        '│  📋 apply 参数说明（含默认值）                                             │',
-        '├──────────────────────────────────────────────────────────────────────────┤',
-        '│                                                                          │',
-        '│  必填参数：                                                               │',
-        '│    --harness <path>       已构建好的 harness 目录路径                      │',
-        '│                                                                          │',
-        '│  含默认值参数：                                                           │',
-        '│    --target <path>        默认：当前工作目录（cwd）                        │',
-        '│    --agent <agent>        默认：从 <harness>/.harness-build-state.yaml 读取│',
-        '│                                                                          │',
-        '│  可选开关：                                                               │',
-        '│    --clone                完整拷贝 harness 到目标项目（默认 bind-only）    │',
-        '│    --force                覆盖已存在的 dispatcher skill 目录              │',
-        '│    -y, --yes              跳过交互确认                                    │',
-        '│    --verbose              显示详细日志                                    │',
-        '│                                                                          │',
-        '└──────────────────────────────────────────────────────────────────────────┘',
-        '',
-        '  📚 完整文档：https://yesv-desaysv.feishu.cn/docx/YEIHdD4NGooMdrxQO4McqwfNnjf?pre_pathname=%2Fdrive%2Fhome%2F',
+        '┌──────────────────────────────────────────────────────────────────────────',
+        '│  快速上手, 帮助：svharness <command> --help  或  svharness help <command>                                                             ',
+        '├──────────────────────────────────────────────────────────────────────────',
+        '│  # 方式零：交互式向导（推荐新手）                                          ',
+        '│  svharness wizard                                                        ',
+        '│                                                                          ',
+        '│  # 方式二：仅 --harness-name 必填                                        ',
+        '│  svharness build --harness-name my-app                                   ',
+        '│                                                                          ',
+        '│  # 方式三：本地基线 + wiki + requirements + references                     ',
+        '│  svharness build --harness-name my-app --baseline ./src \ ',
+        '│  --requirements ./requirements.xlsx --references ./references.pdf      ',
+        '│                                                                          ',
+        '│  # 方式四：绑定 harness 到目标项目                                        ',
+        '│  svharness apply --harness ./my-app-harness --target .              ',
+        '│                                                                          ',
+        '│  # 方式五：文档转 Markdown                                               ',
+        '│  svharness convert --input ./docs/*.pdf --output ./docs/md --type requirements',
+        '│                                                                          ',
+        '└──────────────────────────────────────────────────────────────────────────',
+        '  📚 使用说明文档：https://yesv-desaysv.feishu.cn/docx/OEBwdywTfoncPNxPZ0acClNincg',
         '',
     ].join('\n'));
-    // ── build：主命令（v0.8+） ───────────────────────────────────────────────
     attachBuildOptions(program
         .command('build')
-        .description('构建 harness：生成目录骨架、渲染元文件、向对应 Agent 注入构建辅助 skill。')).action(async (opts) => {
-        await runBuildAction(opts);
+        .description('构建 harness：生成目录骨架、渲染元文件、注入 harness-build skill 与构建规则。')).action(async (opts, cmd) => {
+        await runBuildAction(opts, cmd);
     });
-    // ── init：隐藏别名（兼容老脚本，下个 minor 版本移除） ─────────────────────
     attachBuildOptions(program
         .command('init', { hidden: true })
-        .description('【已废弃别名】等同于 `build`，下个 minor 版本移除，请改用 `svharness build`。')).action(async (opts) => {
+        .description('【已废弃别名】等同于 build')).action(async (opts, cmd) => {
         logger_1.logger.warn('⚠️  `svharness init` 已重命名为 `svharness build`，旧名将在下个 minor 版本移除。');
-        await runBuildAction(opts);
+        await runBuildAction(opts, cmd);
+    });
+    program
+        .command('wizard')
+        .description('交互式向导：分步填写路径与说明，可保存到 svharness.config.yaml 并/或立即执行 build/apply/convert。')
+        .action(async () => {
+        try {
+            await (0, wizard_1.runWizard)();
+        }
+        catch (err) {
+            logger_1.logger.error(err.message);
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('convert')
+        .description('把本地原始文档通过 markitdown_serve 转为 Markdown，产物落到 <harness>/<type>/md/。')
+        .option('--config <path>', `从配置文件读取 convert 节（默认 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
+        .option('--input <path...>', '【可选，默认 .】源文件、目录或 glob')
+        .option('--harness <path>', '【可选】目标 harness 目录')
+        .option('--output <path>', '【可选，默认 .】Markdown 输出目录；含 harness.yaml 时写入 <output>/<type>/md/')
+        .option('--endpoint <url>', 'markitdown_serve 基址')
+        .option('--concurrency <n>', '【默认 3】并发上传数', (v) => Number(v))
+        .option('--max-file-mb <n>', '【默认 50】单文件大小上限（MB）', (v) => Number(v))
+        .option('--timeout-sec <n>', '【默认 120】超时秒数', (v) => Number(v))
+        .option('--type <type>', 'requirements | references')
+        .option('--force', '覆盖已存在同名 .md')
+        .option('-y, --yes', '跳过交互确认')
+        .option('--verbose', '显示详细日志')
+        .action(async (opts, cmd) => {
+        try {
+            const loaded = (0, config_1.loadConfig)({ configPath: opts.config });
+            const merged = (0, config_1.mergeConvertOptions)({
+                input: opts.input,
+                harness: opts.harness,
+                output: opts.output,
+                endpoint: opts.endpoint,
+                concurrency: opts.concurrency,
+                maxFileMb: opts.maxFileMb,
+                timeoutSec: opts.timeoutSec,
+                type: opts.type,
+                force: opts.force,
+                yes: opts.yes,
+                verbose: opts.verbose,
+            }, loaded?.config.convert, loaded?.config.defaults, cmd);
+            await (0, convert_1.runConvert)({
+                input: merged.input ?? [],
+                harness: merged.harness,
+                output: merged.output,
+                endpoint: merged.endpoint,
+                concurrency: merged.concurrency,
+                maxFileMB: merged.maxFileMb,
+                timeoutSec: merged.timeoutSec,
+                type: merged.type,
+                force: !!merged.force,
+                yes: !!merged.yes,
+                verbose: !!merged.verbose,
+            });
+        }
+        catch (err) {
+            logger_1.logger.error(err.message);
+            process.exitCode = 1;
+        }
     });
     program
         .command('apply')
-        .description('把已构建好的 harness（<name>-harness/）绑定到目标项目：向目标项目的 agent skills 目录注入单一 dispatcher skill（harness-apply-skills-main），binding 元数据直接内联到 SKILL.md 的「## 绑定元数据」小节作为运行时权威来源；references/binding.yaml 同时写出作为冗余副本供工具链解析。')
-        .requiredOption('--harness <path>', '已构建好的 harness 目录路径（形如 ./my-app-harness）')
+        .description('把已构建好的 harness 绑定到目标项目（注入 harness-apply-skills-main，内联 apply_skill_registry）。')
+        .option('--config <path>', `从配置文件读取 apply 节（默认 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
+        .option('--harness <path>', '已构建好的 harness 目录路径（可在配置文件的 apply.harness 中提供）')
         .option('--target <path>', '目标项目根目录（默认：当前工作目录）')
         .option('--agent <agent>', '目标 Agent：' +
         (0, validate_args_1.listSupportedAgents)().join(' | ') +
-        '（省略时从 harness/.harness-build-state.yaml 读取）')
+        '（省略时从 harness 状态文件读取）')
         .option('--force', '覆盖已存在的 dispatcher skill 目录')
-        .option('--clone', '把整个 harness 目录拷贝到目标项目根下（默认仅绑定，不拷贝）')
+        .option('--clone', '拷贝整个 harness 到目标项目（默认 bind-only）')
         .option('-y, --yes', '跳过交互确认')
         .option('--verbose', '显示详细日志')
-        .action(async (opts) => {
+        .action(async (opts, cmd) => {
         try {
+            const loaded = (0, config_1.loadConfig)({ configPath: opts.config });
+            const merged = (0, config_1.mergeApplyOptions)(opts, loaded?.config.apply, loaded?.config.defaults, cmd);
+            if (!merged.harness) {
+                throw new Error('--harness <path> 是必填参数（可在配置文件的 apply.harness 中提供）');
+            }
             await (0, apply_1.runApply)({
-                harness: opts.harness,
-                target: opts.target,
-                agent: opts.agent,
-                force: !!opts.force,
-                clone: !!opts.clone,
-                yes: !!opts.yes,
-                verbose: !!opts.verbose,
+                harness: merged.harness,
+                target: merged.target,
+                agent: merged.agent,
+                force: !!merged.force,
+                clone: !!merged.clone,
+                yes: !!merged.yes,
+                verbose: !!merged.verbose,
             });
         }
         catch (err) {
@@ -230,7 +302,6 @@ function main() {
             process.exitCode = 1;
         }
     });
-    // Parse argv. Use process.argv directly so --help and --version work as-is.
     program.parseAsync(process.argv).catch((err) => {
         logger_1.logger.error(err.message);
         process.exitCode = 1;

package/dist/utils/harness-name.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeHarnessName = normalizeHarnessName;
+exports.harnessNameCore = harnessNameCore;
+exports.validateHarnessNameInput = validateHarnessNameInput;
+exports.harnessDirNameFromName = harnessDirNameFromName;
+/**
+ * Normalize and validate harness names for `svharness build`.
+ *
+ * User-facing input `my-app` becomes `.my-app`; directory is `.my-app-harness`.
+ */
+const HARNESS_NAME_CORE_RE = /^[a-z][a-z0-9-]{1,39}$/;
+/** Ensure harness name starts with `.` (e.g. `my-app` → `.my-app`). */
+function normalizeHarnessName(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return trimmed;
+    return trimmed.startsWith('.') ? trimmed : `.${trimmed}`;
+}
+/** Core segment without leading dot, for validation messages. */
+function harnessNameCore(raw) {
+    const trimmed = raw.trim();
+    return trimmed.startsWith('.') ? trimmed.slice(1) : trimmed;
+}
+function validateHarnessNameInput(raw) {
+    if (!raw?.trim()) {
+        return { ok: false, message: '--harness-name 为必填参数' };
+    }
+    const core = harnessNameCore(raw);
+    if (!HARNESS_NAME_CORE_RE.test(core)) {
+        return {
+            ok: false,
+            message: `harness 名称 "${raw.trim()}" 无效：允许小写字母、数字、中划线；` +
+                '须以字母开头；核心段长度 2–40（不含可选的前导 `.`）。',
+        };
+    }
+    return { ok: true, normalized: normalizeHarnessName(raw) };
+}
+function harnessDirNameFromName(harnessName) {
+    return `${normalizeHarnessName(harnessName)}-harness`;
+}