@ohos-cpf/3rdloop 0.0.1

package/lib/workflow.js

@@ -0,0 +1,291 @@
+/**
+ * workflow.js —— 工作流执行器
+ *
+ * 职责：
+ *   - 解析工作流 params schema（cli/workflows/*.js 声明）对应的 CLI flags
+ *   - 必填校验 / 未知 flag 校验 / --help 参数说明
+ *   - 调用工作流 buildTaskDef(params) 构造具参 taskDef
+ *   - 复用 runner.js 的 orchLoad / orchStart 链路执行编排，沿用 orch.js 的
+ *     信号处理、进度渲染与退出码约定（passed=0 / failed=2 / TIMEOUT=3 / SIGINT=130 / SIGTERM=143）
+ *   - --print-taskdef dry-run：只构造并打印/落盘 taskDef，不触碰引擎
+ *
+ * 产品形态与责任边界：
+ *   - 本期只提供机制（注册/分发/taskDef 构造/编排执行），不预置业务工作流
+ *   - 具体工作流（如 pr push）由后续其他项目开发者按 cli/workflows/*.js 约定注册
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { EXIT } from './exit-codes.js';
+
+/**
+ * 3rdloop run <workflow> 命令实现（由 cli.js 在工作流命中时转发）。
+ * @param {object} ctx
+ * @param {object} ctx.wf            - 工作流声明对象（含 name/params/buildTaskDef）
+ * @param {string[]} ctx.wfWords     - 位置参数（已消费掉工作流名的剩余部分）
+ * @param {object} ctx.flags         - parseGlobalFlags 返回
+ * @param {object} ctx.env           - { projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u }
+ * @returns {Promise<number>} 退出码
+ */
+export async function cmdWorkflow({ wf, wfWords, flags, env }) {
+    const { rest } = flags;
+    const { jsonMode, quiet, verbose, out, u, dataDir } = env;
+
+    // ── 工作流自有参数解析（从 flags.rest 中提取）─────────────────────
+    const paramSpecs = Array.isArray(wf.params) ? wf.params : [];
+    const flagNames = new Set(paramSpecs.map(p => p.flag));
+
+    // --help：打印该工作流参数说明（退出码 0）
+    if (rest.includes('--help') || rest.includes('-h')) {
+        _printWorkflowHelp(wf, paramSpecs);
+        return EXIT.OK;
+    }
+
+    // 收集值型 flag：--flag <value>
+    const params = {};
+    const usedFlags = new Set();
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (!arg.startsWith('--')) continue;
+        const name = arg.slice(2);
+        if (!flagNames.has(name)) continue;
+        const value = rest[i + 1];
+        if (value === undefined) {
+            process.stderr.write(`缺少参数值: --${name}\n`);
+            return EXIT.ERROR;
+        }
+        params[name] = value;
+        usedFlags.add(name);
+        i++; // 跳过值
+    }
+
+    // ── 必填校验 ──────────────────────────────────────────────────────
+    const missing = paramSpecs.filter(p => p.required && (params[p.flag] == null || params[p.flag] === ''));
+    if (missing.length > 0) {
+        process.stderr.write(`工作流 "${wf.name}" 缺少必填参数:\n`);
+        for (const p of missing) {
+            process.stderr.write(`  --${p.flag}` + (p.describe ? `  ${p.describe}` : '') + '\n');
+        }
+        process.stderr.write('\n用法: 3rdloop run ' + wf.name + ' ' + paramSpecs.map(p => '--' + p.flag).join(' ') + '\n');
+        return EXIT.ERROR;
+    }
+
+    // ── 未知 flag 校验（只报告工作流 schema 之外的 --flag，非 flag 的裸词忽略）──
+    const unknownFlags = [];
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (!arg.startsWith('--')) continue;
+        const name = arg.slice(2);
+        if (flagNames.has(name)) continue;
+        if (['print-taskdef'].includes(name)) continue; // 框架级 flag
+        unknownFlags.push(name);
+    }
+    if (unknownFlags.length > 0) {
+        process.stderr.write(`工作流 "${wf.name}" 不认识的参数: ${unknownFlags.map(f => '--' + f).join(', ')}\n`);
+        return EXIT.ERROR;
+    }
+
+    // ── 构造 taskDef ────────────────────────────────────────────────
+    let taskDef;
+    try {
+        taskDef = await wf.buildTaskDef(params, { dataDir });
+    } catch (err) {
+        process.stderr.write(`工作流 "${wf.name}" 构造 taskDef 失败: ${err.message}\n`);
+        return EXIT.ERROR;
+    }
+    if (!taskDef || typeof taskDef !== 'object') {
+        process.stderr.write(`工作流 "${wf.name}" 的 buildTaskDef 未返回有效 taskDef 对象\n`);
+        return EXIT.ERROR;
+    }
+    if (!Array.isArray(taskDef.steps) || taskDef.steps.length === 0) {
+        process.stderr.write(`工作流 "${wf.name}" 的 taskDef 缺少非空 steps 数组\n`);
+        return EXIT.ERROR;
+    }
+
+    // ── taskId 缺省补全 ─────────────────────────────────────────────
+    // runner.orchLoad / Orchestrator.loadTask 均要求 taskId 必填；
+    // 工作流若未显式指定则由 CLI 生成稳定唯一 taskId（generateTaskId），
+    // taskDir 缺省由 Orchestrator.loadTask 落到 <data-dir>/task/<taskId>。
+    if (!taskDef.taskId) {
+        const cfg = await _config();
+        taskDef.taskId = cfg.generateTaskId() + '_wf';
+        if (jsonMode) { /* 生成值在最终 JSON 中体现 */ }
+    }
+
+    // ── dry-run：仅打印/落盘 taskDef，不触碰引擎 ────────────────────
+    if (rest.includes('--print-taskdef')) {
+        const taskId = taskDef.taskId || 'task_wf_dry';
+        const printTarget = path.join(dataDir, 'task', taskId);
+        fs.mkdirSync(printTarget, { recursive: true });
+        const dryPath = path.join(printTarget, 'task-def.dry.json');
+        fs.writeFileSync(dryPath, JSON.stringify(taskDef, null, 2), 'utf8');
+        if (jsonMode) {
+            out({ ok: true, dryRun: true, taskId, taskDef, dryPath });
+        } else {
+            process.stdout.write(`--print-taskdef [dry-run] 工作流: ${wf.name}\n`);
+            process.stdout.write(`  taskId: ${taskId}\n`);
+            process.stdout.write(`  步骤数: ${taskDef.steps.length}\n`);
+            process.stdout.write(`  taskDef 预览:\n`);
+            process.stdout.write(JSON.stringify(taskDef, null, 2) + '\n');
+            process.stdout.write(`  已落盘: ${dryPath}\n`);
+        }
+        return EXIT.OK;
+    }
+
+    // ── 正式执行：复用 orch 链路 ────────────────────────────────────
+    // taskId 缺省由 runner 生成（generateTaskId），workflow 可覆盖
+    const r = await _runner();
+    const ctx = r.createRunContext({
+        projectRoot: env.projectRoot,
+        dataDir,
+        skillDir: env.skillDir,
+        cliType: 'opencode',
+        verbose,
+    });
+
+    // 挂载 opencode 生命周期
+    const oc = await _ensureOpcodene(ctx, jsonMode, out);
+    if (!oc) return EXIT.ERROR;
+
+    // 信号处理：优雅中止（orchControl abort → kill 子进程）
+    let interrupted = false;
+    const exitHandler = async (sig) => {
+        if (interrupted) return;
+        interrupted = true;
+        try {
+            const taskId = taskDef.taskId;
+            if (taskId) await r.orchControl(ctx, taskId, 'abort');
+        } 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'));
+
+    const started = Date.now();
+    try {
+        if (!quiet && !jsonMode) {
+            u.logProgress(`${u.C.cyan}工作流已提交: ${u.C.reset}${u.C.bold}${wf.name}${u.C.reset}`);
+            u.logProgress(`  任务定义步骤数: ${taskDef.steps.length}`);
+        }
+
+        // load + start（阻塞执行到终态）
+        await r.orchLoad(ctx, taskDef);
+        const result = await _startAndRender(ctx, r, taskDef.taskId, { jsonMode, quiet, verbose, out, u, started });
+
+        if (jsonMode) {
+            out({
+                ok: result.passed,
+                workflow: wf.name,
+                taskId: taskDef.taskId,
+                status: result.status,
+                passed: result.passed,
+                resultPaths: result.resultPaths || [],
+                error: result.error || null,
+                elapsedSec: result.progress ? Math.round(((Date.now() - started) / 1000)) : null,
+            });
+        }
+        return result.passed ? EXIT.OK : EXIT.TASK_FAILED;
+    } catch (err) {
+        await oc.stop();
+        if (jsonMode) out({ ok: false, error: err.message, taskId: taskDef.taskId });
+        else process.stderr.write(`\n工作流执行失败: ${err.message}\n`);
+        return EXIT.ERROR;
+    }
+}
+
+/**
+ * 编排启动 + 进度渲染（run / start 共用，语义与 orch.js 的 _startAndRender 一致）。
+ */
+async function _startAndRender(ctx, r, taskId, { jsonMode, quiet, verbose, out, u, started }) {
+    const q = await _queries();
+    let prev = null;
+    let finished = false;
+
+    const poll = (async () => {
+        if (jsonMode) return;
+        while (!finished) {
+            const state = q.readOrchestrationState(ctx.dataDir, taskId);
+            if (state && prev) {
+                const lines = u.diffOrchestration(prev, state, { verbose });
+                for (const line of lines) u.logProgress(line);
+            }
+            if (state) prev = state;
+            await new Promise(res => setTimeout(res, 3000));
+        }
+    })();
+
+    try {
+        const result = await r.orchStart(ctx, taskId);
+        finished = true;
+        await poll;
+
+        if (!jsonMode) {
+            const lines = u.diffOrchestration(prev, result.progress, { verbose });
+            for (const line of lines) u.logProgress(line);
+
+            const elapsedSec = ((Date.now() - started) / 1000).toFixed(0);
+            u.logProgress(`\n${result.passed ? u.C.green : u.C.red}工作流完成: ${u.C.reset}${result.status}`);
+            u.logProgress(`  耗时: ${elapsedSec}s`);
+            const stats = result.progress.stats || {};
+            u.logProgress(`  步骤: 完成 ${stats.completed || 0} / 失败 ${stats.failed || 0}`);
+            if (result.error) u.logProgress(`  错误: ${result.error}`);
+            for (const item of result.resultPaths || []) {
+                u.logProgress(`  产物 ${item.stepId}: ${item.resultPath}`);
+            }
+        }
+        return result;
+    } catch (err) {
+        finished = true;
+        throw err;
+    }
+}
+
+/**
+ * 打印工作流参数说明。
+ */
+function _printWorkflowHelp(wf, paramSpecs) {
+    process.stdout.write(`工作流: ${wf.name}\n`);
+    if (wf.description) process.stdout.write(`  描述: ${wf.description}\n`);
+    process.stdout.write(`用法: 3rdloop run ${wf.name}`);
+    if (paramSpecs.length) process.stdout.write(' ' + paramSpecs.map(p => `--${p.flag} <值>` + (p.required ? '(必填)' : '')).join(' '));
+    process.stdout.write('\n');
+    if (paramSpecs.length) {
+        process.stdout.write('\n参数:\n');
+        for (const p of paramSpecs) {
+            process.stdout.write(`  --${p.flag}` + (p.required ? '  [必填]' : '') + (p.describe ? `  ${p.describe}` : '') + '\n');
+        }
+    }
+}
+
+/** 惰性加载 runner（与 cli.js 同步策略）。 */
+function _runner() {
+    return import('./runner.js');
+}
+
+/** 惰性加载 config（taskId 生成等）。 */
+function _config() {
+    return import('./config.js');
+}
+
+/** 惰性加载 queries。 */
+function _queries() {
+    return import('./queries.js');
+}
+
+/** 确保 opencode serve 运行（正式执行需要；dry-run 不需要）。 */
+async function _ensureOpcodene(ctx, jsonMode, out) {
+    const { OpencodeManager } = await import('./opencode.js');
+    const oc = new OpencodeManager({ projectRoot: ctx.projectRoot });
+    const ocHealth = await oc.ensureRunning();
+    if (!ocHealth.ok) {
+        if (jsonMode) out({ ok: false, error: ocHealth.message });
+        process.stderr.write(`\n错误: ${ocHealth.message}\n`);
+        process.stderr.write('请先启动 opencode serve（项目上一级目录: opencode serve）后重试。\n');
+        await oc.stop();
+        return null;
+    }
+    if (ocHealth.spawned) process.stderr.write(`${ocHealth.message}\n`);
+    return oc;
+}

package/lib/workflows.js

@@ -0,0 +1,132 @@
+/**
+ * workflows.js —— 工作流注册表与加载器
+ *
+ * 机制：目录自动加载（可插拔）。
+ *   - 扫描 cli/workflows/ 下所有 .mjs/.js 模块，每个模块默认导出一个工作流声明
+ *   - 工作流新增 = 目录下新增一个文件，零改动核心分发代码（cli.js）
+ *
+ * 工作流声明对象约定：
+ *   {
+ *     name: 'pr push',                 // 工作流名（支持多词，空格分隔）
+ *     description: '简述该固定编排的目的',
+ *     params: [                        // CLI flags schema
+ *       { flag: 'workspace-dir', required: true,  describe: '本地工作区 git 仓库根目录' },
+ *       { flag: 'upstream-url', required: false, describe: '上游仓库 URL' },
+ *     ],
+ *     buildTaskDef(params) {           // params: { 'workspace-dir': <值>, ... }
+ *       return { ... };                // 与 Orchestrator.loadTask 对齐的 taskDef（含 steps）
+ *     },
+ *   }
+ *
+ * 加载容错：
+ *   - 模块 import 失败 / 导出非法：跳过该文件并记录警告（不阻断其余工作流）
+ *   - name 缺失或与已注册工作流重名：跳过并记录警告
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// cli/ 目录绝对路径（本文件在 cli/lib/ 下）
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const WORKFLOWS_DIR = path.join(CLI_ROOT, 'workflows');
+
+/**
+ * 扫描并加载 cli/workflows/ 下所有工作流。
+ * @param {object} [opts]
+ * @param {string} [opts.workflowsDir] - 覆盖工作流目录（便于测试）
+ * @returns {Promise<{ workflows: Map<string, object>, warnings: string[] }>}
+ */
+export async function loadWorkflows(opts = {}) {
+    const dir = opts.workflowsDir || WORKFLOWS_DIR;
+    const workflows = new Map();
+    const warnings = [];
+
+    if (!fs.existsSync(dir)) {
+        return { workflows, warnings: [`工作流目录不存在: ${dir}（已跳过自动加载）`] };
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files = entries
+        .filter(ent => ent.isFile() && /\.(mjs|js)$/.test(ent.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const ent of files) {
+        const filePath = path.join(dir, ent.name);
+        try {
+            const modUrl = new URL(`file://${filePath.replace(/\\/g, '/')}`);
+            const mod = await import(modUrl.href);
+            const wf = mod.default;
+            if (!wf || typeof wf !== 'object' || typeof wf.buildTaskDef !== 'function') {
+                warnings.push(`[workflows] 跳过 ${ent.name}: 默认导出缺少 buildTaskDef()（参考声明约定）`);
+                continue;
+            }
+            const name = String(wf.name || '').trim();
+            if (!name) {
+                warnings.push(`[workflows] 跳过 ${ent.name}: 缺少 name 字段`);
+                continue;
+            }
+            if (workflows.has(name)) {
+                warnings.push(`[workflows] 跳过 ${ent.name}: 工作流名 "${name}" 已注册（来自其他文件）`);
+                continue;
+            }
+            workflows.set(name, wf);
+        } catch (err) {
+            warnings.push(`[workflows] 加载失败 ${ent.name}: ${err.message}`);
+        }
+    }
+
+    return { workflows, warnings };
+}
+
+/**
+ * 按位置参数列表做工作流最长匹配。
+ *
+ * 规则：
+ *   - 依次尝试 words.join(' ') 的降序组合，命中即返回
+ *   - 例：['pr', 'push', '--x', 'v'] → 先试 'pr push'，未中退 'pr' → 再未中返回 namedFlow
+ *
+ * @param {Map<string, object>} workflows - loadWorkflows 返回的注册表
+ * @param {string[]} words - 位置参数数组（不含 flag）
+ * @returns {{ wf: object|null, matchWords: number, name: string|null }}
+ */
+export function resolveWorkflow(workflows, words) {
+    if (!workflows || !Array.isArray(words) || words.length === 0) {
+        return { wf: null, matchWords: 0, name: null };
+    }
+
+    // 只取连续位置参数前缀做匹配（遇 flag 即截断）
+    const positional = [];
+    for (const w of words) {
+        if (typeof w === 'string' && w.startsWith('--')) break;
+        positional.push(w);
+    }
+    if (positional.length === 0) return { wf: null, matchWords: 0, name: null };
+
+    for (let len = positional.length; len >= 1; len--) {
+        const candidate = positional.slice(0, len).join(' ');
+        if (workflows.has(candidate)) {
+            return { wf: workflows.get(candidate), matchWords: len, name: candidate };
+        }
+    }
+    return { wf: null, matchWords: 0, name: null };
+}
+
+/**
+ * 列出已注册工作流（供 help / list 使用）。
+ * @param {Map<string, object>} workflows
+ * @returns {Array<{ name: string, description: string, params: object[] }>}
+ */
+export function listWorkflows(workflows) {
+    if (!workflows) return [];
+    const out = [];
+    for (const [name, wf] of workflows) {
+        out.push({
+            name,
+            description: wf.description || '',
+            params: Array.isArray(wf.params) ? wf.params : [],
+        });
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return out;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@ohos-cpf/3rdloop",
+    "version": "0.0.1",
+    "description": "3rdLibraryLoop 三方库自动化检视 CLI：嵌入式复用核心引擎，任务生命周期管理（submit/run/wait/progress/abort/list/result/doctor）",
+    "type": "module",
+    "license": "MIT",
+    "author": "junxiaoliu927 <1605029776@qq.com>",
+    "homepage": "https://gitcode.com/Sincerelyurs/3rdLibraryLoop",
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitcode.com/Sincerelyurs/3rdLibraryLoop.git"
+    },
+    "bugs": {
+        "url": "https://gitcode.com/Sincerelyurs/3rdLibraryLoop/issues"
+    },
+    "keywords": [
+        "3rdlibrary",
+        "harmonyos",
+        "opencode",
+        "cli",
+        "code-review",
+        "automation"
+    ],
+    "bin": {
+        "3rdloop": "bin/3rdloop.mjs"
+    },
+    "main": "lib/cli.js",
+    "engines": {
+        "node": ">=22"
+    },
+    "files": [
+        "bin",
+        "lib",
+        "vendor",
+        "workflows",
+        "README.md"
+    ],
+    "scripts": {
+        "prepack": "node scripts/prepack.mjs",
+        "postpack": "node scripts/clean-vendor.mjs",
+        "verify-deps": "node scripts/verify-deps.mjs",
+        "test": "node --test test/*.mjs"
+    },
+    "dependencies": {
+        "@opencode-ai/sdk": "^1.18.6",
+        "better-sqlite3": "^13.0.1",
+        "dotenv": "^17.0.0",
+        "openai": "^4.0.0"
+    }
+}