svharness 0.8.0

package/dist/core/next-steps.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printNextSteps = printNextSteps;
+const picocolors_1 = __importDefault(require("picocolors"));
+const repomix_pack_1 = require("./repomix-pack");
+/**
+ * Print a human-friendly "what to do next" block after init succeeds.
+ */
+function printNextSteps(input) {
+    const lines = [];
+    const wikiMode = input.wikiMode ?? 'off';
+    lines.push('');
+    lines.push(picocolors_1.default.bold(picocolors_1.default.green('Harness 骨架已生成: ') + input.targetRoot));
+    lines.push('');
+    lines.push(picocolors_1.default.bold('下一步'));
+    lines.push(picocolors_1.default.gray('---------------------------------------------------------'));
+    lines.push('');
+    lines.push(`1. ${picocolors_1.default.cyan('cd ' + input.targetRoot)}`);
+    lines.push('');
+    lines.push('2. 确认构建辅助 skill 已加载到 Agent 的 skill 目录: ' +
+        picocolors_1.default.cyan(input.adapter.skillsDir + '/'));
+    lines.push('   - harness-build-skill-orchestrator       （构建总调度）');
+    lines.push('   - harness-build-skill-spec-builder       （raw → requirements → specs）');
+    lines.push('   - harness-build-skill-knowledge-builder  （baseline/code 样本 / rules / skills & tasks）');
+    lines.push('   - harness-build-skill-wiki-writer        （按 TASKS.md 逐页撰写 baseline wiki 正文）');
+    lines.push('');
+    if (input.adapter.rulesDir) {
+        lines.push('   同时确认 harness 构建规则已注入到: ' +
+            picocolors_1.default.cyan(input.adapter.rulesDir + '/'));
+        lines.push('');
+    }
+    if (input.hasSource) {
+        lines.push('3. 已识别到基线源码（反向提取模式）。将原始需求文档放入 ' +
+            picocolors_1.default.cyan('assets/raw/') +
+            '，然后打开 AI 会话并说：');
+    }
+    else {
+        lines.push('3. 全新项目模式。将需求文档编写或粘贴到 ' +
+            picocolors_1.default.cyan('assets/raw/') +
+            '，然后打开 AI 会话并说：');
+    }
+    lines.push('');
+    lines.push('   ' + picocolors_1.default.bold(picocolors_1.default.yellow('>> 开始构建 harness')));
+    lines.push('');
+    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，默认）'));
+        lines.push('   输出文件: ' + picocolors_1.default.cyan((0, repomix_pack_1.repomixPackRelFile)()));
+        lines.push('   （若 init 中 Repomix 步骤失败，请查看上方日志中的具体报错）');
+        lines.push('');
+    }
+    if (wikiMode === 'tasks') {
+        lines.push(picocolors_1.default.bold('Baseline wiki 任务清单已生成（默认 tasks-only 模式）'));
+        lines.push('   清单位置: ' + picocolors_1.default.cyan('assets/baseline/wiki/TASKS.md'));
+        lines.push('   Outline XML: ' + picocolors_1.default.cyan('assets/baseline/wiki/structure.xml'));
+        lines.push('   源码快照: ' + picocolors_1.default.cyan('assets/baseline/code/'));
+        lines.push('   打开 AI 会话并说: ' +
+            picocolors_1.default.bold(picocolors_1.default.yellow('>> 按 TASKS.md 逐页生成 baseline wiki')));
+        lines.push('   （由 harness-build-skill-wiki-writer skill 接管，源码引用统一指向 assets/baseline/code/）');
+        lines.push('   .harness-build-state.yaml 中 P1_wiki 初始为 PENDING，');
+        lines.push('   全部 [x] 后由 harness-build-skill-orchestrator 标记 DONE。');
+        lines.push('');
+    }
+    else if (wikiMode === 'full') {
+        lines.push(picocolors_1.default.bold('Baseline wiki 已完整生成（--generate-wiki 模式）'));
+        lines.push('   wiki 目录: ' + picocolors_1.default.cyan('assets/baseline/wiki/'));
+        lines.push('   .harness-build-state.yaml 中 P1_wiki 初始为 DONE。');
+        lines.push('');
+    }
+    // 更显眼的提示框
+    const tipBox = [
+        '┌──────────────────────────────────────────────────────────────────────────┐',
+        '│  💡 提示                                                                 │',
+        '│  svharness 已完成骨架初始化及辅助 skill 的注入到 Agent 的 skill目录    │',
+        '│  自此起所有构建步骤均由 Agent 驱动                                         │',
+        '└──────────────────────────────────────────────────────────────────────────┘',
+    ];
+    for (const line of tipBox) {
+        lines.push(picocolors_1.default.bold(picocolors_1.default.yellow(line)));
+    }
+    lines.push('');
+    for (const line of lines) {
+        // eslint-disable-next-line no-console
+        console.log(line);
+    }
+}

package/dist/core/render-meta.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMeta = renderMeta;
+exports.renderMetaLayered = renderMetaLayered;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const ejs_1 = __importDefault(require("ejs"));
+const logger_1 = require("../utils/logger");
+const META_FILES = [
+    { tplName: 'harness.yaml.ejs', outName: 'harness.yaml' },
+    { tplName: 'AGENTS.md.ejs', outName: 'AGENTS.md' },
+    { tplName: 'README.md.ejs', outName: 'README.md' },
+    { tplName: 'VERSION.ejs', outName: 'VERSION' },
+    { tplName: 'CHANGELOG.md.ejs', outName: 'CHANGELOG.md' },
+];
+/**
+ * Render meta-file EJS templates into the harness target root.
+ */
+async function renderMeta(metaDir, targetRoot, ctx) {
+    if (!(await fs_extra_1.default.pathExists(metaDir))) {
+        throw new Error(`meta template directory not found: ${metaDir}`);
+    }
+    const written = [];
+    for (const { tplName, outName } of META_FILES) {
+        const tplPath = node_path_1.default.join(metaDir, tplName);
+        if (!(await fs_extra_1.default.pathExists(tplPath))) {
+            logger_1.logger.warn(`meta template missing, skipped: ${tplName}`);
+            continue;
+        }
+        const tplContent = await fs_extra_1.default.readFile(tplPath, 'utf8');
+        const rendered = ejs_1.default.render(tplContent, ctx, { async: false });
+        const outPath = node_path_1.default.join(targetRoot, outName);
+        await fs_extra_1.default.outputFile(outPath, rendered, 'utf8');
+        written.push(outName);
+        logger_1.logger.debug(`rendered meta: ${outName}`);
+    }
+    return written;
+}
+/**
+ * Layered meta rendering: given multiple meta template directories (ordered
+ * low→high priority, e.g. `[_shared/meta, <arch>/meta]`), for each output
+ * file the LAST directory that contains the template wins.
+ *
+ * Missing directories are tolerated; at least one must contain each tpl.
+ */
+async function renderMetaLayered(metaDirs, targetRoot, ctx) {
+    const existing = [];
+    for (const d of metaDirs) {
+        if (await fs_extra_1.default.pathExists(d))
+            existing.push(d);
+    }
+    if (existing.length === 0) {
+        throw new Error(`no meta template directory found among: ${metaDirs.join(', ')}`);
+    }
+    const written = [];
+    for (const { tplName, outName } of META_FILES) {
+        // Walk directories in reverse so the highest-priority one wins.
+        let picked = null;
+        for (let i = existing.length - 1; i >= 0; i--) {
+            const cand = node_path_1.default.join(existing[i], tplName);
+            if (await fs_extra_1.default.pathExists(cand)) {
+                picked = cand;
+                break;
+            }
+        }
+        if (!picked) {
+            logger_1.logger.warn(`meta template missing in all layers, skipped: ${tplName}`);
+            continue;
+        }
+        const tplContent = await fs_extra_1.default.readFile(picked, 'utf8');
+        const rendered = ejs_1.default.render(tplContent, ctx, { async: false });
+        const outPath = node_path_1.default.join(targetRoot, outName);
+        await fs_extra_1.default.outputFile(outPath, rendered, 'utf8');
+        written.push(outName);
+        logger_1.logger.debug(`rendered meta: ${outName} (from ${picked})`);
+    }
+    return written;
+}

package/dist/core/repomix-pack.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPOMIX_PACK_FILENAME = exports.REPOMIX_BASELINE_REL_DIR = void 0;
+exports.repomixPackRelFile = repomixPackRelFile;
+exports.runRepomixPackBaseline = runRepomixPackBaseline;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const repomix_1 = require("repomix");
+/** Relative to harness root: `assets/baseline/repomix/repomix-pack.xml`. */
+exports.REPOMIX_BASELINE_REL_DIR = node_path_1.default.join('assets', 'baseline', 'repomix');
+exports.REPOMIX_PACK_FILENAME = 'repomix-pack.xml';
+function repomixPackRelFile() {
+    return node_path_1.default.join(exports.REPOMIX_BASELINE_REL_DIR, exports.REPOMIX_PACK_FILENAME).replace(/\\/g, '/');
+}
+/**
+ * Pack `packRootFs` with Repomix (library `runCli`) and write XML to
+ * `<harnessRootFs>/assets/baseline/repomix/repomix-pack.xml`.
+ */
+async function runRepomixPackBaseline(opts) {
+    const { packRootFs, harnessRootFs, onLog } = opts;
+    const outDir = node_path_1.default.join(harnessRootFs, exports.REPOMIX_BASELINE_REL_DIR);
+    await fs_extra_1.default.ensureDir(outDir);
+    const outAbs = node_path_1.default.join(outDir, exports.REPOMIX_PACK_FILENAME);
+    await fs_extra_1.default.remove(outAbs).catch(() => undefined);
+    const cliOptions = {
+        style: 'xml',
+        output: outAbs,
+        quiet: true,
+        compress: true,
+        parsableStyle: true,
+        outputShowLineNumbers: true,
+        truncateBase64: true,
+    };
+    onLog?.(`[repomix] cwd=${packRootFs}`);
+    onLog?.(`[repomix] output=${outAbs}`);
+    try {
+        const result = await (0, repomix_1.runCli)(['.'], packRootFs, cliOptions);
+        if (result && typeof result === 'object' && 'packResult' in result) {
+            const pr = result.packResult;
+            onLog?.(`[repomix] done: ${pr.totalFiles} files, ${pr.totalTokens} tokens, ${pr.totalCharacters} chars`);
+        }
+    }
+    catch (e) {
+        const err = e;
+        throw new Error(`repomix 失败：${err.message}`);
+    }
+    if (!(await fs_extra_1.default.pathExists(outAbs))) {
+        throw new Error(`repomix 未写出预期文件：${outAbs}`);
+    }
+    return outAbs;
+}

package/dist/core/scaffold.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffold = scaffold;
+exports.scaffoldLayered = scaffoldLayered;
+exports.rollbackTarget = rollbackTarget;
+exports.ensureTargetAvailable = ensureTargetAvailable;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../utils/logger");
+/**
+ * Recursively copy a skeleton directory tree to the target root.
+ * Preserves .gitkeep placeholders so empty directories survive.
+ */
+async function scaffold(skeletonSrc, targetRoot) {
+    if (!(await fs_extra_1.default.pathExists(skeletonSrc))) {
+        throw new Error(`skeleton template not found: ${skeletonSrc}`);
+    }
+    await fs_extra_1.default.ensureDir(targetRoot);
+    const copied = [];
+    await fs_extra_1.default.copy(skeletonSrc, targetRoot, {
+        overwrite: true,
+        errorOnExist: false,
+        filter: (src) => {
+            // Track every real file we're about to copy (skeleton dir itself has empty base).
+            const rel = node_path_1.default.relative(skeletonSrc, src);
+            if (rel && rel.length > 0) {
+                try {
+                    const stat = fs_extra_1.default.statSync(src);
+                    if (stat.isFile()) {
+                        copied.push(rel);
+                    }
+                }
+                catch {
+                    /* ignore transient fs errors */
+                }
+            }
+            return true;
+        },
+    });
+    logger_1.logger.debug(`scaffold copied ${copied.length} file(s) to ${targetRoot}`);
+    return copied;
+}
+/**
+ * Layered scaffold: copy multiple skeleton sources in order, later sources
+ * overwrite earlier ones on conflict. Use for `_shared` + `<arch>` merging.
+ *
+ * Missing sources are skipped with a warning (not an error), so an arch
+ * without arch-specific skeleton files still works.
+ */
+async function scaffoldLayered(skeletonSrcs, targetRoot) {
+    const all = [];
+    let anyFound = false;
+    for (const src of skeletonSrcs) {
+        if (!(await fs_extra_1.default.pathExists(src))) {
+            logger_1.logger.debug(`scaffold layer skipped (missing): ${src}`);
+            continue;
+        }
+        anyFound = true;
+        const copied = await scaffold(src, targetRoot);
+        all.push(...copied);
+    }
+    if (!anyFound) {
+        throw new Error(`no skeleton source found among: ${skeletonSrcs.join(', ')}`);
+    }
+    return all;
+}
+/**
+ * Rollback helper: remove a target directory (best-effort, ignores ENOENT).
+ */
+async function rollbackTarget(targetRoot) {
+    try {
+        await fs_extra_1.default.remove(targetRoot);
+        logger_1.logger.debug(`rolled back ${targetRoot}`);
+    }
+    catch (err) {
+        logger_1.logger.warn(`rollback failed for ${targetRoot}: ${err.message}`);
+    }
+}
+/**
+ * Target directory guard. When targetRoot exists and `force` is not set, throws.
+ */
+async function ensureTargetAvailable(targetRoot, force) {
+    if (!(await fs_extra_1.default.pathExists(targetRoot)))
+        return;
+    if (!force) {
+        throw new Error(`target directory already exists: ${targetRoot}\n  Use --force to overwrite (will delete existing content).`);
+    }
+    logger_1.logger.warn(`--force specified, removing existing ${targetRoot}`);
+    await fs_extra_1.default.remove(targetRoot);
+}

package/dist/core/state.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildInitialState = buildInitialState;
+exports.writeStateFile = writeStateFile;
+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 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
+ * `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
+ *
+ * Design: P1_wiki comes before P2_raw 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.
+ */
+function buildInitialState(input) {
+    const phases = {
+        'P-1_skeleton': { status: 'DONE' },
+    };
+    const wp = input.wikiPhase ?? 'none';
+    // P1_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' };
+    }
+    else if (wp === 'pending') {
+        phases.P1_wiki = {
+            status: 'PENDING',
+            requires_agent: true,
+            mode: 'outline-only',
+            source: input.wikiSource ?? 'cli-tasks',
+            tasks_file: 'assets/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';
+    const startAction = wp !== 'none'
+        ? '请先构建 baseline wiki（项目经验底座），完成后继续下一步。'
+        : '请将原始需求文档放入 assets/raw/ 目录后，告诉 Agent 继续构建。';
+    const state = {
+        project: input.name,
+        arch: input.arch,
+        agent: input.agent,
+        baseline: input.baseline,
+        created_at: input.createdAt,
+        svharnessbuild_version: input.cliVersion,
+        current_phase: startPhase,
+        phases,
+        next_action: startAction,
+    };
+    return state;
+}
+/**
+ * Write .harness-build-state.yaml under the target root.
+ */
+async function writeStateFile(targetRoot, state) {
+    const outPath = node_path_1.default.join(targetRoot, '.harness-build-state.yaml');
+    const body = js_yaml_1.default.dump(state, { lineWidth: 100, noRefs: true, sortKeys: false });
+    const header = '# svharness build-state tracker (auto-generated; AI Agent may update).\n' +
+        '# Phase legend: PENDING | IN_PROGRESS | DONE | FAILED | BLOCKED\n';
+    await fs_extra_1.default.outputFile(outPath, header + body, 'utf8');
+    logger_1.logger.debug(`wrote state file: ${outPath}`);
+    return outPath;
+}

package/dist/index.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 init_1 = require("./commands/init");
+const apply_1 = require("./commands/apply");
+/**
+ * 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) {
+        logger_1.logger.warn('⚠️  --name 已重命名为 --harness-name，旧名将在下个 minor 版本移除。');
+        return opts.name;
+    }
+    throw new Error('--harness-name <name> 是必填参数');
+}
+async function runBuildAction(opts) {
+    try {
+        const harnessName = resolveHarnessName(opts);
+        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,
+        });
+    }
+    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('--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('--baseline-branch <name>', '【Git 模式】指定分支名（默认：main）')
+        .option('--baseline-max-file-kb <kb>', '【过滤】单文件大小上限 KB（默认：1024）', (v) => {
+        const n = Number(v);
+        if (!Number.isFinite(n)) {
+            throw new Error(`--baseline-max-file-kb 必须是数字，收到: ${v}`);
+        }
+        return n;
+    })
+        .option('--force', '强制覆盖已存在的目标目录')
+        .option('-y, --yes', '跳过交互确认，使用默认值')
+        .option('--verbose', '显示详细日志')
+        .option('--generate-wiki', '【Wiki】自动生成完整 Wiki 文档（需 --baseline）')
+        .option('--wiki-tasks-only', '【Wiki】仅生成 Wiki 大纲和任务列表，由 Agent 后续撰写（有 --baseline 时为隐式默认）')
+        .option('--wiki-lang <lang>', '【Wiki】输出语言：zh（默认）| en')
+        .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 或当前目录）');
+}
+function main() {
+    const program = new commander_1.Command();
+    const version = (0, version_1.getCliVersion)();
+    program
+        .name('svharness')
+        .description(`规格驱动开发（SDD）AI 协作框架脚手架工具`)
+        .version(version, '-v, --version', '打印版本号')
+        .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                                                   ║',
+        '╚══════════════════════════════════════════════════════════════════════════╝',
+        '',
+    ].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',
+        '',
+    ].join('\n'));
+    // ── build：主命令（v0.8+） ───────────────────────────────────────────────
+    attachBuildOptions(program
+        .command('build')
+        .description('构建 harness：生成目录骨架、渲染元文件、向对应 Agent 注入构建辅助 skill。')).action(async (opts) => {
+        await runBuildAction(opts);
+    });
+    // ── init：隐藏别名（兼容老脚本，下个 minor 版本移除） ─────────────────────
+    attachBuildOptions(program
+        .command('init', { hidden: true })
+        .description('【已废弃别名】等同于 `build`，下个 minor 版本移除，请改用 `svharness build`。')).action(async (opts) => {
+        logger_1.logger.warn('⚠️  `svharness init` 已重命名为 `svharness build`，旧名将在下个 minor 版本移除。');
+        await runBuildAction(opts);
+    });
+    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）')
+        .option('--target <path>', '目标项目根目录（默认：当前工作目录）')
+        .option('--agent <agent>', '目标 Agent：' +
+        (0, validate_args_1.listSupportedAgents)().join(' | ') +
+        '（省略时从 harness/.harness-build-state.yaml 读取）')
+        .option('--force', '覆盖已存在的 dispatcher skill 目录')
+        .option('--clone', '把整个 harness 目录拷贝到目标项目根下（默认仅绑定，不拷贝）')
+        .option('-y, --yes', '跳过交互确认')
+        .option('--verbose', '显示详细日志')
+        .action(async (opts) => {
+        try {
+            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,
+            });
+        }
+        catch (err) {
+            logger_1.logger.error(err.message);
+            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;
+    });
+}
+main();

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Public types shared across the CLI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });