svharness 0.14.13 → 0.14.17

package/dist/commands/wiki.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * `svharness wiki` — standalone wiki generation for any code project.
+ *
+ * Unlike the wiki embedded in `svharness build`, this command:
+ * - Scans source code in-place (no baseline copy).
+ * - Defaults output to `./wiki/` (relative to cwd).
+ * - Does NOT require a harness; optionally syncs S10_wiki via --update-state.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWiki = runWiki;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const version_1 = require("../utils/version");
+const logger_1 = require("../utils/logger");
+const run_wiki_generation_1 = require("../lib/wiki/run-wiki-generation");
+const state_1 = require("../core/state");
+async function runWiki(opts) {
+    (0, logger_1.setVerbose)(!!opts.verbose);
+    const cwd = opts.cwd ?? process.cwd();
+    // 1. Mutual exclusion check
+    if (opts.generateWiki && opts.wikiTasksOnly) {
+        logger_1.logger.error('--generate-wiki 与 --wiki-tasks-only 不可同时启用');
+        return 1;
+    }
+    // 2. --update-state requires --harness
+    if (opts.updateState && !opts.harness) {
+        logger_1.logger.error('--update-state 须同时提供 --harness <path>');
+        return 1;
+    }
+    // 3. Resolve paths
+    const repoRootFs = node_path_1.default.resolve(cwd, opts.wikiSource ?? '.');
+    const outputRoot = node_path_1.default.resolve(cwd, opts.output ?? './wiki');
+    const wikiRelPath = node_path_1.default.relative(outputRoot, outputRoot); // always '.'
+    const projectName = opts.projectName ?? node_path_1.default.basename(repoRootFs);
+    const mode = opts.generateWiki ? 'full' : 'tasks';
+    // 4. Source guard
+    if (!(await fs_extra_1.default.pathExists(repoRootFs))) {
+        logger_1.logger.error(`源码目录不存在：${repoRootFs}`);
+        return 1;
+    }
+    // 5. Display config
+    logger_1.logger.info(`源码根：${repoRootFs}`);
+    logger_1.logger.info(`输出到：${outputRoot}`);
+    logger_1.logger.info(`模式：${mode === 'full' ? '完整生成（generate-wiki）' : '仅任务清单（tasks-only）'}`);
+    logger_1.logger.info(`语言：${opts.wikiLang ?? 'zh'}`);
+    // 6. Run wiki generation
+    const result = await (0, run_wiki_generation_1.runWikiGeneration)({
+        repoRootFs,
+        wikiOutputRootFs: outputRoot,
+        wikiRelPath: '.', // wiki output is directly in outputRoot
+        wikiLang: opts.wikiLang,
+        wikiModel: opts.wikiModel,
+        wikiBaseUrl: opts.wikiBaseUrl,
+        wikiApiKey: opts.wikiApiKey,
+        projectName,
+        cliVersion: (0, version_1.getCliVersion)(),
+        mode,
+        cwd,
+        forceFull: opts.forceFull,
+        wikiAudience: opts.harness ? 'agent' : 'human',
+        sourceRootRel: '.',
+        onLog: (m) => logger_1.logger.info(m),
+    });
+    // 7. Handle result
+    if (result.ok) {
+        if (mode === 'full') {
+            logger_1.logger.success(`wiki 已完整生成到：${outputRoot}`);
+        }
+        else {
+            logger_1.logger.success(`wiki 任务清单已生成：${result.tasksPath} （共 ${result.pageCount} 页任务）`);
+        }
+    }
+    else {
+        if (mode === 'full') {
+            logger_1.logger.error('wiki 完整生成失败（已产出部分文件可从 checkpoint 恢复）');
+        }
+        else {
+            logger_1.logger.error('wiki 任务清单生成失败');
+        }
+    }
+    // 8. Optional: sync S10_wiki to harness state
+    if (opts.updateState && opts.harness) {
+        const harnessRoot = node_path_1.default.resolve(cwd, opts.harness);
+        if (!(await fs_extra_1.default.pathExists(node_path_1.default.join(harnessRoot, 'harness.yaml')))) {
+            logger_1.logger.warn(`未找到 harness.yaml：${harnessRoot}，跳过 state 更新`);
+        }
+        else {
+            // Warn if output doesn't match harness/baseline/wiki
+            const expectedOutput = node_path_1.default.resolve(harnessRoot, 'baseline', 'wiki');
+            if (node_path_1.default.resolve(outputRoot) !== expectedOutput) {
+                logger_1.logger.warn(`--output (${outputRoot}) 不等于 <harness>/baseline/wiki。` +
+                    'state 中 S10_wiki 的 tasks_file 路径可能不匹配实际产出位置。');
+            }
+            await (0, state_1.patchS10WikiPhase)(harnessRoot, {
+                wikiPhase: result.wikiPhase,
+                wikiSource: result.wikiSource,
+            });
+        }
+    }
+    // 9. Next-steps hint
+    if (result.ok) {
+        logger_1.logger.plain('');
+        if (opts.updateState && opts.harness) {
+            logger_1.logger.plain(picocolors_1.default.bold('下一步（harness 联动）：'));
+            logger_1.logger.plain('  - 可执行 svharness doctor --harness <path> 校验 wiki 状态');
+            if (mode === 'tasks') {
+                logger_1.logger.plain('  - 可用 harness-build-skill-wiki-writer 按 TASKS.md 逐页补写');
+            }
+        }
+        else {
+            logger_1.logger.plain(picocolors_1.default.bold('下一步：'));
+            if (mode === 'tasks') {
+                logger_1.logger.plain(`  - 编辑 ${node_path_1.default.join(outputRoot, 'TASKS.md')} 中的 wiki 页面任务`);
+                logger_1.logger.plain('  - 或使用 --generate-wiki 直接完整生成');
+            }
+            else {
+                logger_1.logger.plain(`  - wiki 文件位于 ${outputRoot}`);
+            }
+        }
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.saveConfigSection = exports.mergeDoctorOptions = exports.mergeConvertOptions = exports.mergeApplyOptions = exports.mergeBuildOptions = exports.resolveConfigHarnessName = exports.normalizeConfig = exports.resolveConfigPath = exports.loadConfig = exports.CONFIG_SCHEMA_VERSION = exports.DEFAULT_CONFIG_FILENAME = void 0;
+exports.saveConfigSection = exports.mergeWikiOptions = exports.mergeDoctorOptions = exports.mergeConvertOptions = exports.mergeApplyOptions = exports.mergeBuildOptions = exports.resolveConfigHarnessName = exports.normalizeConfig = exports.resolveConfigPath = exports.loadConfig = exports.CONFIG_SCHEMA_VERSION = exports.DEFAULT_CONFIG_FILENAME = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "DEFAULT_CONFIG_FILENAME", { enumerable: true, get: function () { return constants_1.DEFAULT_CONFIG_FILENAME; } });
 Object.defineProperty(exports, "CONFIG_SCHEMA_VERSION", { enumerable: true, get: function () { return constants_1.CONFIG_SCHEMA_VERSION; } });
@@ -15,5 +15,6 @@ Object.defineProperty(exports, "mergeBuildOptions", { enumerable: true, get: fun
 Object.defineProperty(exports, "mergeApplyOptions", { enumerable: true, get: function () { return merge_options_1.mergeApplyOptions; } });
 Object.defineProperty(exports, "mergeConvertOptions", { enumerable: true, get: function () { return merge_options_1.mergeConvertOptions; } });
 Object.defineProperty(exports, "mergeDoctorOptions", { enumerable: true, get: function () { return merge_options_1.mergeDoctorOptions; } });
+Object.defineProperty(exports, "mergeWikiOptions", { enumerable: true, get: function () { return merge_options_1.mergeWikiOptions; } });
 var save_config_1 = require("./save-config");
 Object.defineProperty(exports, "saveConfigSection", { enumerable: true, get: function () { return save_config_1.saveConfigSection; } });

package/dist/config/merge-options.js

@@ -4,6 +4,7 @@ exports.mergeBuildOptions = mergeBuildOptions;
 exports.mergeApplyOptions = mergeApplyOptions;
 exports.mergeConvertOptions = mergeConvertOptions;
 exports.mergeDoctorOptions = mergeDoctorOptions;
+exports.mergeWikiOptions = mergeWikiOptions;
 const normalize_1 = require("./normalize");
 function getSource(cmd, key) {
     if (!cmd)
@@ -137,3 +138,21 @@ function mergeDoctorOptions(cli, configSection, defaults, cmd) {
         verbose: pickBool('verbose', cli.verbose, cfg.verbose, defaults?.verbose, cmd),
     };
 }
+function mergeWikiOptions(cli, configSection, defaults, cmd) {
+    const cfg = mergeSection(configSection, defaults);
+    return {
+        wikiSource: pickString('wikiSource', cli.wikiSource, cfg.wikiSource, cmd),
+        output: pickString('output', cli.output, cfg.output, 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),
+        wikiModel: pickString('wikiModel', cli.wikiModel, cfg.wikiModel, cmd),
+        wikiBaseUrl: pickString('wikiBaseUrl', cli.wikiBaseUrl, cfg.wikiBaseUrl, cmd),
+        wikiApiKey: pickString('wikiApiKey', cli.wikiApiKey, cfg.wikiApiKey, cmd),
+        projectName: pickString('projectName', cli.projectName, cfg.projectName, cmd),
+        forceFull: pickBool('forceFull', cli.forceFull, cfg.forceFull, undefined, cmd),
+        harness: pickString('harness', cli.harness, cfg.harness, cmd),
+        updateState: pickBool('updateState', cli.updateState, cfg.updateState, undefined, cmd),
+        verbose: pickBool('verbose', cli.verbose, cfg.verbose, defaults?.verbose, cmd),
+    };
+}

package/dist/config/normalize.js

@@ -129,6 +129,18 @@ function pickDefaults(raw) {
     }
     return s;
 }
+function pickWikiSection(raw) {
+    const s = {};
+    for (const k of ['wikiSource', 'output', 'wikiLang', 'wikiModel', 'wikiBaseUrl', 'wikiApiKey', 'projectName', 'harness']) {
+        if (raw[k] !== undefined && raw[k] !== null)
+            s[k] = String(raw[k]).trim();
+    }
+    for (const k of ['generateWiki', 'wikiTasksOnly', 'forceFull', 'updateState', 'verbose']) {
+        if (raw[k] !== undefined)
+            s[k] = Boolean(raw[k]);
+    }
+    return s;
+}
 /**
  * Parse and normalize raw YAML/JSON object into SvharnessConfig.
  */
@@ -165,5 +177,11 @@ function normalizeConfig(raw, configPath) {
         }
         cfg.convert = pickConvertSection(raw.convert);
     }
+    if (raw.wiki !== undefined) {
+        if (!isPlainObject(raw.wiki)) {
+            throw new Error(`配置 wiki 必须是对象：${configPath}`);
+        }
+        cfg.wiki = pickWikiSection(raw.wiki);
+    }
     return cfg;
 }

package/dist/core/state.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildInitialState = buildInitialState;
 exports.writeStateFile = writeStateFile;
+exports.patchS10WikiPhase = patchS10WikiPhase;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
@@ -130,3 +131,41 @@ async function writeStateFile(targetRoot, state) {
     logger_1.logger.debug(`wrote state file: ${outPath}`);
     return outPath;
 }
+/**
+ * Patch `phases.S10_wiki` in an existing `.harness-build-state.yaml`.
+ *
+ * - Inserts or updates `S10_wiki` with the appropriate status/mode fields.
+ * - Does NOT modify `current_phase` or `next_action` to avoid disrupting
+ *   a build that has already progressed past S10.
+ * - If the state file does not exist, logs a warning and returns without error.
+ */
+async function patchS10WikiPhase(harnessRoot, input) {
+    const statePath = node_path_1.default.join(harnessRoot, '.harness-build-state.yaml');
+    if (!(await fs_extra_1.default.pathExists(statePath))) {
+        logger_1.logger.warn('--update-state 已跳过：未找到 .harness-build-state.yaml');
+        return;
+    }
+    const raw = await fs_extra_1.default.readFile(statePath, 'utf8');
+    // Strip comment-only header lines before parsing.
+    const body = raw.replace(/^#.*\n/gm, '');
+    const state = js_yaml_1.default.load(body);
+    const phases = (state.phases ?? {});
+    if (input.wikiPhase === 'done') {
+        phases.S10_wiki = { status: 'DONE', requires_agent: false, mode: 'full', source: 'cli-full' };
+    }
+    else {
+        phases.S10_wiki = {
+            status: 'PENDING',
+            requires_agent: true,
+            mode: 'outline-only',
+            source: input.wikiSource ?? 'cli-tasks',
+            tasks_file: 'baseline/wiki/TASKS.md',
+        };
+    }
+    state.phases = phases;
+    // Preserve the original header comment block.
+    const headerLines = raw.split('\n').filter((l) => l.startsWith('#')).join('\n') + '\n';
+    const newBody = js_yaml_1.default.dump(state, { lineWidth: 100, noRefs: true, sortKeys: false });
+    await fs_extra_1.default.outputFile(statePath, headerLines + newBody, 'utf8');
+    logger_1.logger.info(`已更新 S10_wiki → ${input.wikiPhase.toUpperCase()}（未修改 current_phase）`);
+}

package/dist/index.js

@@ -10,6 +10,7 @@ const apply_1 = require("./commands/apply");
 const convert_1 = require("./commands/convert");
 const wizard_1 = require("./commands/wizard");
 const doctor_1 = require("./commands/doctor");
+const wiki_1 = require("./commands/wiki");
 const requirements_1 = require("./commands/requirements");
 const start_agent_1 = require("./commands/start-agent");
 const shell_integration_1 = require("./commands/shell-integration");
@@ -120,6 +121,20 @@ async function runBuildAction(opts, cmd) {
         process.exitCode = 1;
     }
 }
+/**
+ * Attach wiki-specific LLM and source options to a command.
+ * Shared by both `build` (for --baseline wiki generation) and standalone `wiki`.
+ */
+function attachWikiOptions(cmd) {
+    return cmd
+        .option('--generate-wiki', '【Wiki】自动生成完整 Wiki 文档')
+        .option('--wiki-tasks-only', '【Wiki】仅生成 Wiki 大纲和任务列表（默认模式）')
+        .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】扫描的源码根路径');
+}
 function attachBuildOptions(cmd) {
     return cmd
         .option('--config <path>', `从 YAML/JSON 读取参数（默认可选 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
@@ -149,13 +164,6 @@ function attachBuildOptions(cmd) {
         .option('--force', '强制覆盖已存在的目标目录')
         .option('-y, --yes', '跳过交互确认，使用默认值')
         .option('--verbose', '显示详细日志')
-        .option('--generate-wiki', '【Wiki】自动生成完整 Wiki 文档（需 --baseline）')
-        .option('--wiki-tasks-only', '【Wiki】仅生成 Wiki 大纲和任务列表（有 --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】扫描的源码根路径')
         .option('--enable-baseline-extract', '【可选】启用 baseline 自动提取 skills/rules（S61 ENABLED；默认 DISABLED）')
         .option('--strict-input-confirm', '【可选】禁用 CLI 预声明，恢复 S60/S61/S65 等阶段的 Agent 表单确认');
 }
@@ -176,7 +184,7 @@ function main() {
         '║  为任意 Agent IDE 生成项目本地知识层骨架（harness）                          ',
         '╠══════════════════════════════════════════════════════════════════════════',
         '║  支持架构：android-compose | android-xml | cpp | web-react | python          ',
-        '║  支持 Agent：codechat | qoder | cursor | claude-code | opencode | generic ',
+        '║  支持 Agent：codechat | qoder | cursor | claude-code | opencode | codex | generic',
         '║  运行要求：Node.js ≥ 18                                                   ',
         '╚══════════════════════════════════════════════════════════════════════════',
         '',
@@ -203,13 +211,16 @@ function main() {
         '│  # 方式五：文档转 Markdown                                               ',
         '│  svharness convert --input ./docs/*.pdf --output ./docs/md --type requirements',
         '│                                                                          ',
+        '│  # 方式六：对当前工程生成 wiki 骨架                                       ',
+        '│  svharness wiki                                                          ',
+        '│                                                                          ',
         '└──────────────────────────────────────────────────────────────────────────',
         '  📚 使用说明文档：https://yesv-desaysv.feishu.cn/docx/OEBwdywTfoncPNxPZ0acClNincg',
         '',
     ].join('\n'));
-    attachBuildOptions(program
+    attachWikiOptions(attachBuildOptions(program
         .command('build')
-        .description('构建 harness：生成目录骨架、渲染元文件、注入 harness-build skill 与构建规则。')).action(async (opts, cmd) => {
+        .description('构建 harness：生成目录骨架、渲染元文件、注入 harness-build skill 与构建规则。'))).action(async (opts, cmd) => {
         await runBuildAction(opts, cmd);
     });
     attachBuildOptions(program
@@ -336,6 +347,43 @@ function main() {
             process.exitCode = 1;
         }
     });
+    // Standalone wiki generation for any code project
+    attachWikiOptions(program
+        .command('wiki')
+        .description('对任意代码工程目录生成 baseline wiki（不依赖 harness）'))
+        .option('--output <path>', 'wiki 产物输出目录（默认 ./wiki）')
+        .option('--project-name <name>', '项目名（用于 TASKS.md 标题；默认取 wiki-source 的目录名）')
+        .option('--force-full', 'full 模式：忽略 checkpoint 强制重新生成')
+        .option('--harness <path>', '【可选】已有 harness 根目录（仅配合 --update-state 使用）')
+        .option('--update-state', '同步 S10_wiki 到 harness 的 .harness-build-state.yaml（须同时提供 --harness）')
+        .option('--config <path>', `从配置文件读取 wiki 节（默认 ${config_1.DEFAULT_CONFIG_FILENAME}）`)
+        .option('--verbose', '显示详细日志')
+        .action(async (opts, cmd) => {
+        try {
+            const loaded = (0, config_1.loadConfig)({ configPath: opts.config });
+            const merged = (0, config_1.mergeWikiOptions)(opts, loaded?.config.wiki, loaded?.config.defaults, cmd);
+            const exitCode = await (0, wiki_1.runWiki)({
+                wikiSource: merged.wikiSource,
+                output: merged.output,
+                generateWiki: merged.generateWiki,
+                wikiTasksOnly: merged.wikiTasksOnly,
+                wikiLang: merged.wikiLang,
+                wikiModel: merged.wikiModel,
+                wikiBaseUrl: merged.wikiBaseUrl,
+                wikiApiKey: merged.wikiApiKey,
+                projectName: merged.projectName,
+                forceFull: merged.forceFull,
+                harness: merged.harness,
+                updateState: merged.updateState,
+                verbose: merged.verbose,
+            });
+            process.exitCode = exitCode;
+        }
+        catch (err) {
+            logger_1.logger.error(err.message);
+            process.exitCode = 1;
+        }
+    });
     const requirements = program
         .command('requirements')
         .description('S40 需求条目化：结构扫描与 verify 门禁');

package/dist/lib/agent-launcher.js

@@ -13,6 +13,7 @@ const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
 const logger_1 = require("../utils/logger");
 const validate_args_1 = require("../utils/validate-args");
+const codechat_runner_resolver_1 = require("./codechat-runner-resolver");
 const SUPPORTED_START_AGENTS = ['codechat'];
 const DEFAULT_ENV_TEMPLATE = 'default-claude.env';
 function homePath(...segments) {
@@ -54,23 +55,21 @@ async function verifyUserEnvWritten(userEnvPath) {
     throw new Error(`env 写入后校验失败（文件不存在或为空）：${userEnvPath}\n` +
         `请重试 svharness start-agent，或手动创建该文件。`);
 }
-function getCodechatRunnerConfig() {
+function getCodechatEnvConfig() {
     const platform = process.platform;
-    if (platform === 'win32') {
+    if (platform === 'win32' || platform === 'linux' || platform === 'darwin') {
         return {
-            runner: homePath('.codechat', 'cli_app', 'run.bat'),
             envFile: homePath('.claude', '.env'),
             envSyncFromRel: path_1.default.join('.claude', '.env'),
         };
     }
-    if (platform === 'linux' || platform === 'darwin') {
-        return {
-            runner: homePath('.codechat', 'cli_app', 'run.sh'),
-            envFile: homePath('.claude', '.env'),
-            envSyncFromRel: path_1.default.join('.claude', '.env'),
-        };
+    throw new Error(`当前平台 "${platform}" 暂不支持 start-agent codechat。支持：win32、linux、darwin。`);
+}
+function formatRunnerSourceLog(source, label) {
+    if (label) {
+        return `${source}: ${label}`;
     }
-    throw new Error(`当前平台 "${platform}" 暂不支持 start-agent codechat。支持：win32、linux。`);
+    return source;
 }
 function normalizeComparable(p) {
     return path_1.default.resolve(p).replace(/\\/g, '/').toLowerCase();
@@ -206,14 +205,12 @@ async function runStartAgent(opts) {
         workDir: opts.workDir,
         positionalWorkdir: opts.positionalWorkdir,
     });
-    const config = getCodechatRunnerConfig();
+    const config = getCodechatEnvConfig();
     const syncEnv = opts.syncEnv !== false;
     const skipPermissions = opts.skipPermissions !== false;
     await ensureUserEnv(workdir, config, syncEnv);
     const userEnvFile = resolveUserEnvPath(config);
-    if (!(await fs_extra_1.default.pathExists(config.runner))) {
-        throw new Error(`未找到 CodeChat CLI：${config.runner}\n请先安装 CodeChat CLI 到用户目录。`);
-    }
+    const { runner, source, label } = (0, codechat_runner_resolver_1.resolveCodechatRunner)();
     if (!(await fs_extra_1.default.pathExists(userEnvFile))) {
         throw new Error(`未找到 env 文件：${userEnvFile}\n` +
             `请提供 ${path_1.default.join(workdir, config.envSyncFromRel)}，或确保内置模板 templates/default-claude.env 可访问。`);
@@ -221,14 +218,15 @@ async function runStartAgent(opts) {
     await verifyUserEnvWritten(userEnvFile);
     warnIfNotHarnessProject(workdir);
     const args = buildRunnerArgs(config, workdir, skipPermissions);
+    logger_1.logger.info(`CodeChat CLI: ${runner} (${formatRunnerSourceLog(source, label)})`);
     logger_1.logger.info(`启动 CodeChat Agent（workdir: ${workdir}）`);
     const result = process.platform === 'win32'
-        ? (0, child_process_1.spawnSync)(config.runner, args, {
+        ? (0, child_process_1.spawnSync)(runner, args, {
             cwd: workdir,
             stdio: 'inherit',
             shell: true,
         })
-        : (0, child_process_1.spawnSync)(config.runner, args, {
+        : (0, child_process_1.spawnSync)(runner, args, {
             cwd: workdir,
             stdio: 'inherit',
             shell: false,

package/dist/lib/codechat-runner-resolver.js

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODECHAT_CLI_RUNNER_ENV = void 0;
+exports.getRunnerFileName = getRunnerFileName;
+exports.getStandaloneRunnerPath = getStandaloneRunnerPath;
+exports.parseIdeVersion = parseIdeVersion;
+exports.compareVersionDesc = compareVersionDesc;
+exports.compareIdePluginCandidates = compareIdePluginCandidates;
+exports.getDefaultIdeScanRoots = getDefaultIdeScanRoots;
+exports.scanIdePluginRunners = scanIdePluginRunners;
+exports.resolveCodechatRunner = resolveCodechatRunner;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+exports.CODECHAT_CLI_RUNNER_ENV = 'CODECHAT_CLI_RUNNER';
+function canAccessExecutable(filePath) {
+    try {
+        fs_extra_1.default.accessSync(filePath, fs_extra_1.default.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function homePath(homedir, ...segments) {
+    return path_1.default.join(homedir, ...segments);
+}
+/** Runner script file name for the current platform. */
+function getRunnerFileName(platform = process.platform) {
+    return platform === 'win32' ? 'run.bat' : 'run.sh';
+}
+/** Standalone CodeChat CLI install path (~/.codechat/cli_app/run.*). */
+function getStandaloneRunnerPath(homedir = os_1.default.homedir(), platform = process.platform) {
+    return homePath(homedir, '.codechat', 'cli_app', getRunnerFileName(platform));
+}
+/**
+ * Parse version segments from IDE install dir name (e.g. AndroidStudio2024.2 → [2024, 2]).
+ */
+function parseIdeVersion(installDirName, dirPrefix) {
+    if (!installDirName.startsWith(dirPrefix)) {
+        return [0];
+    }
+    const rest = installDirName.slice(dirPrefix.length);
+    const match = rest.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!match) {
+        return [0];
+    }
+    return [match[1], match[2], match[3]]
+        .filter((part) => part !== undefined && part !== '')
+        .map(Number);
+}
+function formatIdeLabel(labelPrefix, installDirName, dirPrefix) {
+    const versionPart = installDirName.slice(dirPrefix.length);
+    return versionPart ? `${labelPrefix} ${versionPart}` : labelPrefix;
+}
+/** Compare version arrays lexicographically (descending — higher version first). */
+function compareVersionDesc(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av !== bv) {
+            return bv - av;
+        }
+    }
+    return 0;
+}
+/**
+ * Compare two IDE plugin candidates — higher version first, then newer mtime.
+ */
+function compareIdePluginCandidates(a, b) {
+    const versionCmp = compareVersionDesc(a.version, b.version);
+    if (versionCmp !== 0) {
+        return versionCmp;
+    }
+    return b.mtimeMs - a.mtimeMs;
+}
+/** Default IDE plugin scan roots for the current platform. */
+function getDefaultIdeScanRoots(platform = process.platform, homedir = os_1.default.homedir(), appData = process.env.APPDATA) {
+    if (platform === 'win32') {
+        const roaming = appData ?? homePath(homedir, 'AppData', 'Roaming');
+        return [
+            { root: path_1.default.join(roaming, 'Google'), dirPrefix: 'AndroidStudio', labelPrefix: 'Android Studio' },
+            { root: path_1.default.join(roaming, 'JetBrains'), dirPrefix: 'IntelliJIdea', labelPrefix: 'IntelliJ IDEA' },
+            { root: path_1.default.join(roaming, 'JetBrains'), dirPrefix: 'IdeaIC', labelPrefix: 'IntelliJ IDEA Community' },
+        ];
+    }
+    if (platform === 'darwin') {
+        const appSupport = homePath(homedir, 'Library', 'Application Support');
+        return [
+            { root: path_1.default.join(appSupport, 'Google'), dirPrefix: 'AndroidStudio', labelPrefix: 'Android Studio' },
+            { root: path_1.default.join(appSupport, 'JetBrains'), dirPrefix: 'IntelliJIdea', labelPrefix: 'IntelliJ IDEA' },
+            { root: path_1.default.join(appSupport, 'JetBrains'), dirPrefix: 'IdeaIC', labelPrefix: 'IntelliJ IDEA Community' },
+        ];
+    }
+    // linux and others
+    const localShare = homePath(homedir, '.local', 'share');
+    return [
+        { root: path_1.default.join(localShare, 'JetBrains'), dirPrefix: 'IntelliJIdea', labelPrefix: 'IntelliJ IDEA' },
+        { root: path_1.default.join(localShare, 'JetBrains'), dirPrefix: 'IdeaIC', labelPrefix: 'IntelliJ IDEA Community' },
+    ];
+}
+/**
+ * Scan IDE plugin directories for CodeChat CLI runner scripts.
+ */
+function scanIdePluginRunners(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const runnerFileName = getRunnerFileName(platform);
+    const scanRoots = options.ideScanRoots ??
+        getDefaultIdeScanRoots(platform, options.homedir ?? os_1.default.homedir(), options.appData);
+    const candidates = [];
+    for (const { root, dirPrefix, labelPrefix } of scanRoots) {
+        if (!fs_extra_1.default.existsSync(root)) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = fs_extra_1.default.readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.startsWith(dirPrefix)) {
+                continue;
+            }
+            const runner = path_1.default.join(root, entry, 'plugins', 'CodeChat', 'cli', runnerFileName);
+            if (!canAccessExecutable(runner)) {
+                continue;
+            }
+            let mtimeMs = 0;
+            try {
+                mtimeMs = fs_extra_1.default.statSync(runner).mtimeMs;
+            }
+            catch {
+                // keep 0
+            }
+            candidates.push({
+                runner: path_1.default.resolve(runner),
+                installDirName: entry,
+                label: formatIdeLabel(labelPrefix, entry, dirPrefix),
+                version: parseIdeVersion(entry, dirPrefix),
+                mtimeMs,
+            });
+        }
+    }
+    return candidates.sort(compareIdePluginCandidates);
+}
+function pickBestIdeCandidate(candidates) {
+    if (candidates.length === 0) {
+        return null;
+    }
+    return candidates[0];
+}
+function buildRunnerNotFoundError(standalonePath, envOverride, scanRoots, platform) {
+    const runnerFile = getRunnerFileName(platform);
+    const lines = [
+        `未找到 CodeChat CLI（${runnerFile}）。已尝试：`,
+        `  1. 环境变量 ${exports.CODECHAT_CLI_RUNNER_ENV}${envOverride ? ` → ${envOverride}` : '（未设置）'}`,
+        `  2. 独立安装 → ${standalonePath}`,
+        '  3. IDE 插件目录扫描：',
+    ];
+    for (const { root, dirPrefix } of scanRoots) {
+        lines.push(`     ${path_1.default.join(root, `${dirPrefix}*`, 'plugins', 'CodeChat', 'cli', runnerFile)}`);
+    }
+    lines.push('', '请安装 CodeChat CLI 到 ~/.codechat/cli_app/，或在 Android Studio / IntelliJ IDEA 中安装 CodeChat 插件，', `或设置 ${exports.CODECHAT_CLI_RUNNER_ENV} 指向 run.bat / run.sh 的绝对路径。`);
+    return lines.join('\n');
+}
+/**
+ * Resolve CodeChat CLI runner with fallback: env → standalone → IDE plugin scan.
+ */
+function resolveCodechatRunner(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const homedir = options.homedir ?? os_1.default.homedir();
+    const envRunner = (options.envRunner ?? process.env[exports.CODECHAT_CLI_RUNNER_ENV])?.trim();
+    const standalonePath = getStandaloneRunnerPath(homedir, platform);
+    const scanRoots = options.ideScanRoots ??
+        getDefaultIdeScanRoots(platform, homedir, options.appData);
+    if (envRunner) {
+        if (!canAccessExecutable(envRunner)) {
+            throw new Error(`${exports.CODECHAT_CLI_RUNNER_ENV} 指向的路径不可访问：${envRunner}`);
+        }
+        return {
+            runner: path_1.default.resolve(envRunner),
+            source: 'env',
+            label: exports.CODECHAT_CLI_RUNNER_ENV,
+        };
+    }
+    if (canAccessExecutable(standalonePath)) {
+        return {
+            runner: path_1.default.resolve(standalonePath),
+            source: 'standalone',
+        };
+    }
+    const ideCandidates = scanIdePluginRunners(options);
+    const best = pickBestIdeCandidate(ideCandidates);
+    if (best) {
+        return {
+            runner: best.runner,
+            source: 'ide-plugin',
+            label: best.label,
+        };
+    }
+    throw new Error(buildRunnerNotFoundError(standalonePath, envRunner, scanRoots, platform));
+}