@ohos-cpf/3rdloop 0.0.1

package/lib/step.js

@@ -0,0 +1,326 @@
+/**
+ * step.js —— 单步执行（FlexRunner 直连）命令实现
+ *
+ * 命令：
+ *   step run "<任务描述>"   阻塞执行单个步骤（initContext → executeStart 循环）
+ *   step status <taskId>   查询单步状态/产物/会话（磁盘直读）
+ *   step result <taskId>   读取该步 result.md 内容（磁盘直读）
+ *
+ * 与 run（大循环 LoopEngine）的区别：
+ *   - 不经 Brain 拆解 / Orchestrator 编排 / TestCheck 审核
+ *   - 自定 taskId / stepId / maxRetries，产物落 taskDir
+ *   - 写精简 loop.json（isSingleExecution:true），使 3rdloop list/progress/result 可见
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { EXIT } from './exit-codes.js';
+
+/** 单步任务产物前缀（与 FlexRunner.executeStart 命名一致） */
+const RESULT_FILE_PREFIX = (stepId, loop) => `stepId${stepId}_loop${loop}_result_`;
+/** 步骤执行记录文件名（与 TaskExecutionStore._key 命名一致） */
+const STEP_STATE_FILE = (stepId, loop) => `stepid_${stepId}_loop${loop}.json`;
+
+/**
+ * 3rdloop step 命令二段分发。
+ * @returns {Promise<number>}
+ */
+export async function cmdStep({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u }) {
+    // 基于 flags.rest 分发：全局 flags（如 --data-dir）已被 parseGlobalFlags 消费，
+    // flags.rest 是"未知 flag + 值 + 位置参数"混合，取第一个位置参数作为子命令。
+    const fRest = flags.rest || [];
+    const sub = fRest[0];
+    const subRest = fRest.slice(1);
+    switch (sub) {
+        case 'run':
+            return cmdStepRun({ flags, rest: subRest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u });
+        case 'status':
+        case 'result':
+            return cmdStepQuery(sub, { flags, rest: subRest, dataDir, jsonMode, quiet, out, u, verbose });
+        default:
+            process.stderr.write(`缺少或未知的 step 子命令: ${sub || '(空)'}\n`);
+            process.stderr.write('用法: 3rdloop step run|status|result ...\n');
+            return EXIT.ERROR;
+    }
+}
+
+/**
+ * 阻塞执行单个步骤。
+ *
+ * 参数：
+ *   3rdloop step run "<任务描述>" [--task-id <id>] [--step-id N] [--input-report <path>]
+ *                      [--max-retries N] [--loop N] [--task-dir <path>]
+ *                      [--specified-skill <SKILL name|目录名>]   <!-- 固定执行指定 SKILL，跳过 SkillSelector 匹配 -->
+ */
+async function cmdStepRun({ flags, rest, dataDir, skillDir, jsonMode, quiet, verbose, out, u, projectRoot }) {
+    const positional = _positionalArgs(rest);
+    const description = positional[0];
+    if (!description) {
+        process.stderr.write('缺少任务描述。用法: 3rdloop step run "生成 xxx 的 demo 场景"\n');
+        return EXIT.ERROR;
+    }
+
+    const taskId = _stringFlag(flags, 'task-id') || '';
+    const stepId = _parseIntFlag(flags, 'step-id', 1);
+    if (!taskId) {
+        process.stderr.write('缺少 --task-id。用法: 3rdloop step run "<描述>" --task-id <id>\n');
+        return EXIT.ERROR;
+    }
+    if (!Number.isInteger(stepId) || stepId <= 0) {
+        process.stderr.write(`--step-id 必须为正整数: ${stepId}\n`);
+        return EXIT.ERROR;
+    }
+
+    const inputReport = _stringFlag(flags, 'input-report');
+    if (inputReport && !fs.existsSync(inputReport)) {
+        process.stderr.write(`--input-report 文件不存在: ${inputReport}\n`);
+        return EXIT.ERROR;
+    }
+
+    const maxRetries = _parseIntFlag(flags, 'max-retries', 3);
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+        process.stderr.write(`--max-retries 必须为非负整数: ${maxRetries}\n`);
+        return EXIT.ERROR;
+    }
+    const loop = _parseIntFlag(flags, 'loop', 0);
+    if (!Number.isInteger(loop) || loop < 0) {
+        process.stderr.write(`--loop 必须为非负整数: ${loop}\n`);
+        return EXIT.ERROR;
+    }
+
+    let taskDir = _stringFlag(flags, 'task-dir');
+    if (taskDir) taskDir = path.resolve(dataDir, taskDir); // 相对路径基于 dataDir
+    else taskDir = path.join(dataDir, 'task', taskId);      // 默认与 run 一致
+
+    const specifiedSkill = _stringFlag(flags, 'specified-skill');
+
+    // 挂载 opencode 生命周期（复用 runner 语义）
+    const r = await _runner();
+    const ctx = r.createRunContext({ projectRoot, dataDir, skillDir, cliType: 'opencode', verbose });
+    const { OpencodeManager } = await import('./opencode.js');
+    const oc = new OpencodeManager({ projectRoot });
+    const ocHealth = await oc.ensureRunning();
+    if (!ocHealth.ok) {
+        if (jsonMode) out({ ok: false, error: ocHealth.message, taskId });
+        else process.stderr.write(`\n错误: ${ocHealth.message}\n`);
+        await oc.stop();
+        return EXIT.ERROR;
+    }
+    if (ocHealth.spawned) process.stderr.write(`${ocHealth.message}\n`);
+
+    // 信号处理：Ctrl+C → abortStandaloneStep（而非 engine.abortLoop）
+    let interrupted = false;
+    const exitHandler = async (sig) => {
+        if (interrupted) return;
+        interrupted = true;
+        try { await r.abortStandaloneStep(ctx, taskId, stepId); } catch { /* 忽略 */ }
+        await oc.stop();
+        process.stderr.write(`\n已中止（${sig}）\n`);
+        process.exit(sig === 'SIGINT' ? EXIT.SIGINT : EXIT.SIGTERM);
+    };
+    process.once('SIGINT', () => exitHandler('SIGINT'));
+    process.once('SIGTERM', () => exitHandler('SIGTERM'));
+
+    if (!quiet && !jsonMode) {
+        u.logProgress(`${u.C.cyan}单步任务已提交: ${u.C.reset}${u.C.bold}${taskId}${u.C.reset}`);
+        u.logProgress(`  描述: ${description.slice(0, 120)}`);
+        u.logProgress(`  stepId: ${stepId}  loop: ${loop}  maxRetries: ${maxRetries}`);
+    }
+
+    try {
+        const result = await r.runStandaloneStep(ctx, {
+            taskId,
+            stepId,
+            taskDescription: description,
+            skillDirectory: skillDir,
+            specifiedSkill,
+            taskDir,
+            inputReport: inputReport || '',
+            maxRetries,
+            bigLoopIndex: loop,
+        });
+
+        if (jsonMode) {
+            out({
+                ok: result.success,
+                taskId,
+                stepId: result.stepId,
+                status: result.success ? 'passed' : 'failed',
+                success: result.success,
+                resultPath: result.resultPath,
+                nextStepId: result.nextStepId,
+                error: result.error,
+                executeStep: result.executeStep,
+            });
+        } else {
+            if (result.success) {
+                u.logProgress(`\n${u.C.green}步骤执行成功${u.C.reset}`);
+            } else {
+                u.logProgress(`\n${u.C.red}步骤执行失败${u.C.reset}`);
+            }
+            if (result.resultPath) u.logProgress(`  产物: ${result.resultPath}`);
+            if (result.nextStepId) u.logProgress(`  下一步: stepId=${result.nextStepId}`);
+            if (result.error) u.logProgress(`  错误: ${result.error}`);
+        }
+        return result.success ? EXIT.OK : EXIT.TASK_FAILED;
+    } catch (err) {
+        await oc.stop();
+        if (jsonMode) out({ ok: false, error: err.message, taskId });
+        else process.stderr.write(`\n单步执行失败: ${err.message}\n`);
+        return EXIT.ERROR;
+    }
+}
+
+/**
+ * status / result 查询（共用磁盘直读）。
+ */
+async function cmdStepQuery(sub, { flags, rest: subRest, dataDir, jsonMode, quiet, out, u, verbose }) {
+    const positional = _positionalArgs(subRest);
+    const taskId = positional[0];
+    if (!taskId) {
+        process.stderr.write(`缺少 taskId。用法: 3rdloop step ${sub} <taskId> [--step-id N]\n`);
+        return EXIT.ERROR;
+    }
+
+    const stepId = _parseIntFlag(flags, 'step-id', 1);
+    const loop = _parseIntFlag(flags, 'loop', 0);
+    const taskPath = path.join(dataDir, 'task', taskId);
+    if (!fs.existsSync(taskPath)) {
+        if (jsonMode) out({ ok: false, error: '任务不存在', taskId });
+        else process.stderr.write(`任务不存在: ${taskId}\n`);
+        return EXIT.ERROR;
+    }
+
+    const stepState = _readJson(path.join(taskPath, STEP_STATE_FILE(stepId, loop)));
+
+    if (sub === 'result') {
+        // 读取最终 result.md（按 executeStep 优先，兜底扫描自小到大最大的 retry 文件）
+        const resultFile = _findResultFile(taskPath, stepId, loop);
+        if (!resultFile) {
+            if (jsonMode) out({ ok: false, error: '该步骤尚无产物文件', taskId, stepId, loop });
+            else process.stderr.write(`该步骤尚无产物文件: ${taskId} (stepId=${stepId} loop=${loop})\n`);
+            return EXIT.ERROR;
+        }
+        const content = fs.readFileSync(resultFile, 'utf8');
+        if (jsonMode) {
+            out({
+                ok: true,
+                taskId,
+                stepId,
+                loop,
+                resultPath: resultFile,
+                content,
+                stepState,
+            });
+        } else if (quiet) {
+            process.stdout.write(content + '\n');
+        } else {
+            u.logProgress(`任务 ${taskId} step${stepId} 结果:`);
+            process.stdout.write(content + '\n');
+        }
+        return EXIT.OK;
+    }
+
+    // status：状态 + 产物文件清单 + 步骤记录
+    const files = fs.readdirSync(taskPath).filter(f => f.startsWith(RESULT_FILE_PREFIX(stepId, loop)));
+    const info = {
+        taskId,
+        stepId,
+        loop,
+        resultFiles: files.map(f => ({ name: f, path: path.join(taskPath, f) })),
+        stepState,
+    };
+    if (jsonMode) {
+        out({ ok: true, ...info });
+    } else {
+        process.stdout.write(`任务: ${taskId}\n`);
+        process.stdout.write(`步骤: stepId=${stepId} loop=${loop}\n`);
+        if (stepState) {
+            if (stepState.status) process.stdout.write(`状态: ${stepState.status}\n`);
+            if (stepState.matchedSkillDir) process.stdout.write(`匹配技能: ${stepState.matchedSkillDir}\n`);
+            if (stepState.sessionId) process.stdout.write(`会话: ${stepState.sessionId}\n`);
+            if (stepState.executeStep != null) process.stdout.write(`执行次数: ${stepState.executeStep}\n`);
+            if (stepState.endTime) process.stdout.write(`结束时间: ${stepState.endTime}\n`);
+        } else {
+            process.stdout.write('步骤记录: 无\n');
+        }
+        if (files.length) {
+            process.stdout.write(`产物文件 (${files.length}):\n`);
+            for (const f of files) process.stdout.write(`  ${f}\n`);
+        } else {
+            process.stdout.write('产物文件: 无\n');
+        }
+    }
+    return EXIT.OK;
+}
+
+// ─── 磁盘直读工具 ─────────────────────────────────────────────────────────
+
+/** 读取 JSON 文件（不存在/损坏返回 null）。 */
+function _readJson(file) {
+    try {
+        if (fs.existsSync(file)) return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch { /* 损坏 */ }
+    return null;
+}
+
+/** 查找该步骤最新产物 result.md（优先 stepState.executeStep，兜底 max retry）。 */
+function _findResultFile(taskPath, stepId, loop) {
+    const prefix = RESULT_FILE_PREFIX(stepId, loop);
+    const files = fs.readdirSync(taskPath).filter(f => f.startsWith(prefix) && f.endsWith('.md'));
+    if (!files.length) return null;
+
+    // 提取 retry 号排序（避免字典序），取最大
+    const parseRetry = (f) => {
+        const m = f.slice(prefix.length).match(/^(\d+)\.md$/);
+        return m ? parseInt(m[1], 10) : -1;
+    };
+    files.sort((a, b) => parseRetry(a) - parseRetry(b));
+    return path.join(taskPath, files[files.length - 1]);
+}
+
+// ─── 小工具 ───────────────────────────────────────────────────────────────
+
+/** 惰性加载 runner（与 cli.js 同步策略）。 */
+function _runner() {
+    return import('./runner.js');
+}
+
+function _parseIntFlag(flags, name, def) {
+    const idx = flags.rest.indexOf(`--${name}`);
+    const raw = idx !== -1 ? flags.rest[idx + 1] : undefined;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) ? n : def;
+}
+
+function _stringFlag(flags, name) {
+    const idx = flags.rest.indexOf(`--${name}`);
+    return idx !== -1 ? flags.rest[idx + 1] : undefined;
+}
+
+/** step 子命令专用 flags（带值）。用于从参数列表剔除 flag 与值，提取位置参数。 */
+const STEP_FLAG_NAMES = ['task-id', 'step-id', 'input-report', 'max-retries', 'loop', 'task-dir', 'specified-skill'];
+
+/**
+ * 从参数数组提取位置参数（描述 / taskId）。
+ *
+ * 说明：parseGlobalFlags 会把未知 flag 与其值原样保留在 flags.rest，
+ * 因此 rest 是"flag + 值 + 位置参数"混合，不能直接取 rest[0]。
+ * 这里跳过已知 step flags 及其值，只返回真正的位置参数。
+ *
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+function _positionalArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const name = arg.slice(2);
+            if (STEP_FLAG_NAMES.includes(name)) i++; // 跳过该 flag 的值
+            continue;
+        }
+        out.push(arg);
+    }
+    return out;
+}

package/lib/ui.js

@@ -0,0 +1,223 @@
+/**
+ * ui.js —— 进度渲染与输出契约
+ *
+ * 设计（进度与输出打印，已确认决策）：
+ *   - stdout 只放 `--json` 或最终结果（脚本可解析）
+ *   - stderr 放进度日志 / 诊断信息（不影响 stdout 管道）
+ *   - TTY 感知：非 TTY（CI）= 纯行式时间戳追加；TTY = 行式阶段日志 + 静止期单行刷新
+ *   - verbosity 三级：--quiet / 默认 / -v
+ *
+ * 增量 diff 渲染：
+ *   从 loop.json 快照计算"相对上次快照的变化"，仅打印变化项，避免刷屏。
+ */
+
+const isTTY = process.stdout.isTTY;
+
+// ANSI 颜色（仅 TTY 启用，非 TTY 输出纯文本）
+export const C = isTTY ? {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+} : {
+    reset: '', bold: '', dim: '', red: '', green: '',
+    yellow: '', blue: '', magenta: '', cyan: '', gray: '',
+};
+
+/**
+ * 输出到 stderr（进度/日志通道）。
+ * @param {string} message
+ */
+export function logProgress(message) {
+    process.stderr.write(message + '\n');
+}
+
+/**
+ * 带时间戳的进度行（非 TTY 模式）。
+ * @param {string} message
+ * @param {boolean} [verbose]
+ */
+export function logLine(message, verbose = false) {
+    if (verbose && !process.env.LOOP_SHOW_TIMESTAMP) return;
+    const ts = new Date().toISOString().slice(11, 19);
+    process.stderr.write(`${C.gray}[${ts}]${C.reset} ${message}\n`);
+}
+
+/**
+ * 状态图标 / 文案映射。
+ */
+const STATUS_LABEL = {
+    idle: '待启动',
+    planning: '拆解中',
+    executing: '执行中',
+    checking: '审核中',
+    passed: '通过 ✓',
+    failed: '失败 ✗',
+    aborted: '已中止 ⏹',
+    error: '出错 ✗',
+};
+
+/**
+ * 渲染循环级进度一行（非 TTY 行式）。
+ * @param {object} p - loop.json 快照
+ */
+export function renderLoopLine(p) {
+    const roundInfo = p.rounds && p.rounds.length
+        ? `${p.rounds.length}/${p.maxLoops}` : `0/${p.maxLoops}`;
+    const label = STATUS_LABEL[p.status] || p.status;
+    const color = p.status === 'passed' ? C.green
+        : (p.status === 'failed' || p.status === 'error' || p.status === 'aborted') ? C.red
+        : C.cyan;
+    logLine(`${color}循环 ${roundInfo} 状态=${label}${C.reset}`, true);
+}
+
+/**
+ * 计算两个循环快照的增量（返回需要打印的变化行描述）。
+ *
+ * @param {object|null} prev - 上次快照（无则 null）
+ * @param {object} cur        - 当前快照
+ * @param {object} [opts]
+ * @param {boolean} [opts.verbose]
+ * @returns {string[]} 变化行列表
+ */
+export function diffLoop(prev, cur, opts = {}) {
+    const lines = [];
+
+    if (!prev) {
+        // 首次快照：纯描述状态
+        const label = STATUS_LABEL[cur.status] || cur.status;
+        lines.push(`任务状态: ${label}`);
+        return lines;
+    }
+
+    // 状态变化
+    if (prev.status !== cur.status) {
+        const from = STATUS_LABEL[prev.status] || prev.status;
+        const to = STATUS_LABEL[cur.status] || cur.status;
+        lines.push(`阶段变化: ${from} → ${to}`);
+    }
+
+    // 轮次推进
+    const prevRounds = prev.rounds?.length || 0;
+    const curRounds = cur.rounds?.length || 0;
+    if (curRounds > prevRounds) {
+        lines.push(`轮次推进: ${curRounds}/${cur.maxLoops}`);
+    }
+
+    // 轮内状态细化（当前轮）
+    if (cur.status === 'passed' || cur.status === 'failed') {
+        const lastRound = cur.rounds?.[cur.rounds.length - 1];
+        if (lastRound) {
+            const check = lastRound.checkPassed != null
+                ? (lastRound.checkPassed ? '准出通过' : '准出未通过')
+                : '';
+            const orchStatus = lastRound.orchestratorStatus || '';
+            lines.push(`终态判定: ${lastRound.error ? '出错: ' + lastRound.error : check || orchStatus || STATUS_LABEL[cur.status]}`);
+        }
+    }
+
+    return lines;
+}
+
+/**
+ * 计算两个编排快照的增量（返回需要打印的变化行描述）。
+ *
+ * 面向 orchestration.json（Orchestrator.getProgress() 产物）：
+ *   - 首快照：输出整体概览
+ *   - 步骤状态变化：输出发生变化的步骤行
+ *
+ * @param {object|null} prev - 上次快照（无则 null）
+ * @param {object} cur        - 当前快照
+ * @param {object} [opts]
+ * @param {boolean} [opts.verbose]
+ * @returns {string[]} 变化行列表
+ */
+export function diffOrchestration(prev, cur, opts = {}) {
+    const lines = [];
+
+    if (!prev) {
+        // 首次快照：整体概览
+        const stats = cur.stats || {};
+        lines.push(`编排任务: ${cur.taskId}  状态: ${_orchStatusLabel(cur.status)}`);
+        if (Array.isArray(cur.steps) && cur.steps.length) {
+            lines.push(`步骤: ${cur.steps.length} 个（完成 ${stats.completed || 0} / 失败 ${stats.failed || 0} / 进行 ${stats.running || 0}）`);
+        }
+        return lines;
+    }
+
+    // 编排状态变化
+    if (prev.status !== cur.status) {
+        lines.push(`编排状态: ${_orchStatusLabel(prev.status)} → ${_orchStatusLabel(cur.status)}`);
+    }
+
+    // 步骤状态变化
+    const prevSteps = new Map((prev.steps || []).map(s => [String(s.stepId), s.status]));
+    for (const step of cur.steps || []) {
+        const sid = String(step.stepId);
+        const prevStatus = prevSteps.get(sid);
+        if (prevStatus !== step.status) {
+            const icon = step.status === 'completed' ? '✓' : (step.status === 'failed' ? '✗' : '▶');
+            const statusText = _orchNodeStatusLabel(step.status);
+            let line = `步骤 ${sid} ${icon} ${statusText}`;
+            if (opts.verbose && step.taskDescription) {
+                line += `  ${step.taskDescription.slice(0, 60)}`;
+            }
+            if (step.status === 'failed' && step.error) line += `  (${step.error.slice(0, 80)})`;
+            if (step.resultPath && (step.status === 'completed')) line += `  产物: ${step.resultPath}`;
+            lines.push(line);
+        }
+    }
+
+    return lines;
+}
+
+/** OrchestratorStatus 的中文标签。 */
+function _orchStatusLabel(status) {
+    const map = {
+        idle: '待加载', loaded: '已加载', running: '运行中',
+        completed: '完成', failed: '失败', aborted: '已中止', deadlocked: '死锁',
+    };
+    return map[status] || status;
+}
+
+/** NodeStatus 的中文标签。 */
+function _orchNodeStatusLabel(status) {
+    const map = {
+        pending: '等待中', ready: '就绪', running: '执行中',
+        completed: '完成', failed: '失败', skipped: '跳过', blocked: '阻塞',
+    };
+    return map[status] || status;
+}
+
+/**
+ * 从结果文件 / 内存任务快照提取最终可读摘要。
+ * @param {object} progress - loop.json 快照
+ * @returns {string}
+ */
+export function finalSummary(progress) {
+    const parts = [];
+    parts.push(`任务: ${progress.taskId}`);
+    parts.push(`状态: ${STATUS_LABEL[progress.status] || progress.status}`);
+    if (progress.currentLoop != null && progress.maxLoops != null) {
+        parts.push(`轮次: ${progress.currentLoop}/${progress.maxLoops}`);
+    }
+    if (progress.error) parts.push(`错误: ${progress.error}`);
+
+    const rounds = progress.rounds || [];
+    const lastPassed = rounds.find(r => r.checkPassed);
+    const last = rounds[rounds.length - 1];
+    if (lastPassed) {
+        parts.push(`准出通过: 第 ${lastPassed.loop + 1} 轮`);
+        if (lastPassed.checkSummary) parts.push(`审核摘要: ${lastPassed.checkSummary}`);
+    } else if (last && last.checkSummary) {
+        parts.push(`最后审核: ${last.checkSummary}`);
+    }
+    if (progress.taskDir) parts.push(`产物目录: ${progress.taskDir}`);
+    return parts.join('\n');
+}