@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Orchestrator/StepNode.js

@@ -0,0 +1,312 @@
+/**
+ * StepNode —— 编排器中的步骤节点模型
+ *
+ * 封装单个 FlexRunner 步骤的元信息与运行时状态，
+ * 供 Orchestrator 进行拓扑分析、依赖调度、进度追踪。
+ *
+ * 高内聚：所有与单个步骤相关的状态和查询方法集中在此类。
+ * 低耦合：不直接依赖 FlexRunner 实例，只持有配置和运行时结果。
+ */
+
+import { nowCST } from '../library/cstTime.js';
+
+// ─── 步骤状态常量 ────────────────────────────────────────────────────────────
+
+/** 编排器层面步骤状态（与 FlexRunner.StepStatus 对齐，额外增加编排层语义） */
+export const NodeStatus = Object.freeze({
+    PENDING: 'pending',       // 等待执行（未满足依赖条件）
+    READY: 'ready',           // 依赖已满足，可执行
+    RUNNING: 'running',       // 正在执行
+    COMPLETED: 'completed',   // 执行成功
+    FAILED: 'failed',         // 执行失败（已用完重试）
+    SKIPPED: 'skipped',       // 被跳过（如前置失败导致无法执行）
+    BLOCKED: 'blocked'        // 被阻塞（循环检测或死锁）
+});
+
+/**
+ * @typedef {object} StepConfig
+ * @property {number|string} stepId        - 步骤 ID（唯一标识）
+ * @property {string}        taskDescription - 任务描述
+ * @property {number|string|Array<number|string>} [dependId=0] - 依赖步骤 ID，支持单值或数组（fan-in 聚合）
+ * @property {number|string} [nextStepId=0]- 成功后下一步骤 ID（0 = 无后续，结束）
+ * @property {number|string} [failStepId=0]- 失败后指向步骤 ID（0 = 失败即终止）
+ * @property {number}        [maxRetries=3]- 最大重试次数
+ * @property {string}        [skillDirectory] - SKILL 目录路径
+ * @property {string}        [specifiedSkill] - 指定 SKILL（name 或目录名）；非空时跳过自动匹配
+ * @property {string}        [taskDir]     - 工作目录
+ * @property {string}        [inputReport] - 输入报告路径
+ * @property {string}        [taskDescription] - 任务描述
+ */
+
+/**
+ * 归一化 dependId 为字符串前置 ID 数组。
+ * - 单值（number/string）→ 非 0 时包装为 [id]，0/null/-1 → []
+ * - 数组 → 过滤掉 0/空/-1，逐项转字符串
+ * 其中 -1 是"修复步骤哨兵"：表示该步骤仅由 failStepId 触发，不是真实依赖 ID，
+ * 因此不进入 _dependIds（避免 fan-in 聚合误判），同时真实依赖为 0 时仍保留 -1 原值（见构造/updateConfig）。
+ * @param {number|string|Array<number|string>|null|undefined} value
+ * @returns {string[]}
+ */
+function normalizeDependIds(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map(v => String(v))
+            .filter(v => v !== '0' && v !== '' && v !== '-1');
+    }
+    if (value == null) return [];
+    const s = String(value);
+    return s === '0' || s === '' || s === '-1' ? [] : [s];
+}
+
+/** 原始 dependId 中是否含 -1 哨兵（单值或数组任一项） */
+function hasSentinel(value) {
+    if (Array.isArray(value)) {
+        return value.some(v => String(v) === '-1');
+    }
+    return String(value ?? '') === '-1';
+}
+
+/**
+ * @typedef {object} ExecutionRecord
+ * @property {number}        attempt       - 第几次执行（从 1 开始）
+ * @property {string}        startTime     - 开始时间
+ * @property {string}        [endTime]     - 结束时间
+ * @property {boolean}       success       - 是否成功
+ * @property {string}        resultPath    - 结果文件路径
+ * @property {string}        [sessionId]   - 会话 ID
+ * @property {string}        [error]       - 错误信息
+ */
+
+class StepNode {
+    /**
+     * @param {StepConfig} config
+     */
+    constructor(config) {
+        if (!config || config.stepId == null) {
+            throw new Error('StepNode: stepId 为必填项');
+        }
+
+        // ── 元信息（可修改，仅 PENDING 状态时允许） ──
+        this.stepId = String(config.stepId);
+        this.taskDescription = config.taskDescription || '';
+        // dependId 支持 number | number[]：内部统一归一化为字符串前置 ID 数组（_dependIds）。
+        // 对外暴露 dependId 便于兼容——单依赖时为其第一个元素，多依赖时为数组。
+        // 修复步骤哨兵 -1 不算真实依赖：_dependIds 为空，但 dependId 保留 -1 原值作为图数据自解释标记。
+        this._dependIds = normalizeDependIds(config.dependId);
+        this.dependId = hasSentinel(config.dependId)
+            ? '-1'
+            : (this._dependIds.length === 1 ? this._dependIds[0] : this._dependIds);
+        this.nextStepId = config.nextStepId != null ? String(config.nextStepId) : '0';
+        this.failStepId = config.failStepId != null ? String(config.failStepId) : '0';
+        this.maxRetries = typeof config.maxRetries === 'number' ? config.maxRetries : 3;
+        this.skillDirectory = config.skillDirectory || '';
+        this.specifiedSkill = String(config.specifiedSkill || '').trim();
+        this.taskDir = config.taskDir || '';
+        this.inputReport = config.inputReport || '';
+
+        // ── 运行时状态 ──
+        /** @type {string} */
+        this.status = NodeStatus.PENDING;
+        /** @type {number} 当前重试次数（0 = 尚未执行） */
+        this.retryCount = 0;
+        /** @type {string|null} 当前开始时间 */
+        this.startTime = null;
+        /** @type {string|null} 当前结束时间 */
+        this.endTime = null;
+        /** @type {string} 最新结果报告路径 */
+        this.resultPath = '';
+        /** @type {string} 最新会话 ID */
+        this.sessionId = '';
+        /** @type {ExecutionRecord[]} 历史执行记录 */
+        this.history = [];
+        /** @type {object|null} 结构化指标（SKILL 约定的键值对，如 mergeLevel / score；无则 null） */
+        this.metrics = null;
+        /** @type {string|null} 失败原因 */
+        this.error = null;
+        /** @type {FlexRunner|null} 关联的 FlexRunner 实例（运行时注入） */
+        this._runner = null;
+    }
+
+    // ─── 状态查询 ──────────────────────────────────────────────────────
+
+    /**
+     * 归一化后的前置依赖步骤 ID 数组。
+     * 调度层统一使用此数组判断 fan-in 聚合条件（所有依赖完成才激活）。
+     * @returns {string[]}
+     */
+    get dependencies() {
+        return this._dependIds;
+    }
+
+    /** 是否有前置依赖（非入口步骤） */
+    get hasDependencies() {
+        return this._dependIds.length > 0;
+    }
+
+    /** 是否尚未执行 */
+    get isPending() {
+        return this.status === NodeStatus.PENDING || this.status === NodeStatus.READY;
+    }
+
+    /** 是否正在执行 */
+    get isRunning() {
+        return this.status === NodeStatus.RUNNING;
+    }
+
+    /** 是否已结束（成功 / 失败 / 跳过 / 阻塞） */
+    get isFinished() {
+        return (
+            this.status === NodeStatus.COMPLETED ||
+            this.status === NodeStatus.FAILED ||
+            this.status === NodeStatus.SKIPPED ||
+            this.status === NodeStatus.BLOCKED
+        );
+    }
+
+    /** 是否成功 */
+    get isCompleted() {
+        return this.status === NodeStatus.COMPLETED;
+    }
+
+    /** 是否还能重试 */
+    get canRetry() {
+        return this.retryCount < this.maxRetries && !this.isFinished;
+    }
+
+    // ─── 状态变更 ──────────────────────────────────────────────────────
+
+    /** 标记为就绪（依赖已满足）。
+     *  允许从 PENDING（初始）/ COMPLETED（成功）/ FAILED（失败）重新进入 READY，
+     *  以支持 failStepId 修复步骤被重复执行（不清空历史结果，由 markRunning/markFinished 自然更新）。 */
+    markReady() {
+        if (this.status === NodeStatus.PENDING ||
+            this.status === NodeStatus.COMPLETED ||
+            this.status === NodeStatus.FAILED) {
+            this.status = NodeStatus.READY;
+        }
+    }
+
+    /** 标记为执行中 */
+    markRunning() {
+        this.status = NodeStatus.RUNNING;
+        this.retryCount++;
+        this.startTime = nowCST();
+        this.endTime = null;
+        this.error = null;
+    }
+
+    /**
+     * 标记执行完成
+     * @param {{success: boolean, resultPath: string, sessionId?: string, error?: string, metrics?: object|null}} result
+     */
+    markFinished(result) {
+        this.endTime = nowCST();
+        this.resultPath = result.resultPath || '';
+        this.sessionId = result.sessionId || '';
+        this.error = result.error || null;
+        // 结构化指标（SKILL 约定的键值对，如 mergeLevel / score；无则 null）
+        this.metrics = result.metrics || null;
+
+        this.history.push({
+            attempt: this.retryCount,
+            startTime: this.startTime,
+            endTime: this.endTime,
+            success: result.success,
+            resultPath: this.resultPath,
+            sessionId: this.sessionId,
+            error: this.error,
+            metrics: this.metrics
+        });
+
+        this.status = result.success ? NodeStatus.COMPLETED : NodeStatus.FAILED;
+    }
+
+    /** 标记为跳过 */
+    markSkipped(reason) {
+        this.status = NodeStatus.SKIPPED;
+        this.error = reason;
+    }
+
+    /** 标记为阻塞 */
+    markBlocked(reason) {
+        this.status = NodeStatus.BLOCKED;
+        this.error = reason;
+    }
+
+    /**
+     * 释放关联的 FlexRunner 实例及其重型引用（CLIController / SkillSelector / LLMClient / Storage）。
+     *
+     * 编排结束后调用，使 FlexRunner 及其内嵌依赖可被 GC 回收。
+     * 仅置空 `_runner`，保留 `sessionId` / `resultPath` / `history` 等序列化元信息，
+     * 前端仍可通过 `toJSON()` 与本地归档查看历史。
+     */
+    releaseRunner() {
+        this._runner = null;
+    }
+
+    // ─── 配置修改 ──────────────────────────────────────────────────────
+
+    /**
+     * 修改步骤配置（仅 PENDING 状态允许）。
+     *
+     * @param {Partial<StepConfig>} patch - 要修改的字段
+     * @returns {boolean} 是否修改成功
+     */
+    updateConfig(patch) {
+        if (!this.isPending) {
+            return false;
+        }
+        if (!patch || typeof patch !== 'object') return false;
+
+        if (patch.taskDescription !== undefined) this.taskDescription = patch.taskDescription;
+        if (patch.dependId !== undefined) {
+            this._dependIds = normalizeDependIds(patch.dependId);
+            this.dependId = hasSentinel(patch.dependId)
+                ? '-1'
+                : (this._dependIds.length === 1 ? this._dependIds[0] : this._dependIds);
+        }
+        if (patch.nextStepId !== undefined) this.nextStepId = String(patch.nextStepId);
+        if (patch.failStepId !== undefined) this.failStepId = String(patch.failStepId);
+        if (patch.maxRetries !== undefined) this.maxRetries = Number(patch.maxRetries);
+        if (patch.skillDirectory !== undefined) this.skillDirectory = patch.skillDirectory;
+        if (patch.specifiedSkill !== undefined) this.specifiedSkill = String(patch.specifiedSkill || '').trim();
+        if (patch.taskDir !== undefined) this.taskDir = patch.taskDir;
+        if (patch.inputReport !== undefined) this.inputReport = patch.inputReport;
+
+        return true;
+    }
+
+    // ─── 序列化 ────────────────────────────────────────────────────────
+
+    /**
+     * 序列化为 JSON（供前端展示和持久化）。
+     * @returns {object}
+     */
+    toJSON() {
+        return {
+            stepId: this.stepId,
+            taskDescription: this.taskDescription,
+            dependId: this.dependId,
+            nextStepId: this.nextStepId,
+            failStepId: this.failStepId,
+            maxRetries: this.maxRetries,
+            skillDirectory: this.skillDirectory,
+            specifiedSkill: this.specifiedSkill,
+            taskDir: this.taskDir,
+            inputReport: this.inputReport,
+            status: this.status,
+            retryCount: this.retryCount,
+            startTime: this.startTime,
+            endTime: this.endTime,
+            resultPath: this.resultPath,
+            sessionId: this.sessionId,
+            error: this.error,
+            metrics: this.metrics,
+            canRetry: this.canRetry,
+            history: this.history
+        };
+    }
+}
+
+export { StepNode };
+export default StepNode;

package/vendor/Server/Orchestrator/index.js

@@ -0,0 +1,13 @@
+/**
+ * Orchestrator 模块统一导出
+ *
+ * 外部使用：
+ *   import { Orchestrator } from './Orchestrator/index.js';
+ *   const orch = new Orchestrator({ sseHub, storage });
+ *   await orch.loadTask(taskDef);
+ *   await orch.start();
+ */
+
+export { Orchestrator, OrchestratorStatus } from './Orchestrator.js';
+export { StepNode, NodeStatus } from './StepNode.js';
+export { default } from './Orchestrator.js';

package/vendor/Server/Routes/controllers/BrainController.js

@@ -0,0 +1,241 @@
+/**
+ * BrainController —— Brain 任务拆解 HTTP 接口控制器
+ *
+ * 职责：封装 Brain 的 HTTP 接口，供前端提交自然语言任务并查看拆解结果。
+ * 不感知 HTTP 层细节，只接收 RequestContext / ResponseContext。
+ *
+ * 管理多个 Brain 实例（按 planId 区分），支持：
+ *   - 提交自然语言任务，获取拆解后的任务 JSON
+ *   - 拆解并直接提交 Orchestrator 执行
+ *   - 查询拆解历史
+ *   - 查看拆解详情
+ */
+
+import { Brain, BrainStatus } from '../../Brain/index.js';
+
+/**
+ * BrainController
+ */
+class BrainController {
+    /**
+     * @param {object} [deps] - 共享依赖
+     * @param {object} [deps.sseHub]               - SseHub 实例
+     * @param {object} [deps.storage]              - 存储门面
+     * @param {object} [deps.orchestratorController] - OrchestratorController（用于 planAndExecute）
+     * @param {string} [deps.skillDirectory]       - SKILL 目录路径
+     */
+    constructor(deps = {}) {
+        this.sseHub = deps.sseHub || null;
+        this.storage = deps.storage || null;
+        this.orchestratorController = deps.orchestratorController || null;
+        this.skillDirectory = deps.skillDirectory || null;
+
+        // Brain 实例（单例，复用 LLM 连接）
+        this._brain = null;
+    }
+
+    /**
+     * 懒初始化 Brain 实例
+     * @returns {Brain}
+     */
+    _getBrain() {
+        if (!this._brain) {
+            this._brain = new Brain({
+                sseHub: this.sseHub,
+                storage: this.storage,
+                skillDirectory: this.skillDirectory
+            });
+        }
+        return this._brain;
+    }
+
+    // ─── HTTP Handlers ─────────────────────────────────────────────────
+
+    /**
+     * POST /api/brain/plan
+     * 提交自然语言任务，返回拆解后的任务 JSON
+     *
+     * Body: {
+     *   taskDescription: string,      // 必填
+     *   taskId?: string,              // 可选，指定 taskId
+     *   taskDir?: string,             // 可选，指定工作目录
+     *   skillDirectory?: string,      // 可选，覆盖 SKILL 目录
+     *   planId?: string,              // 可选，指定 planId
+     *   acceptanceCriteria?: string   // 可选，验收标准（自然语言）
+     * }
+     */
+    async plan(req, res) {
+        const body = req.body || {};
+        const { taskDescription } = body;
+
+        if (!taskDescription) {
+            return res.error(400, 'taskDescription 为必填项');
+        }
+
+        try {
+            const brain = this._getBrain();
+            const plan = await brain.planTask(taskDescription, {
+                taskId: body.taskId,
+                taskDir: body.taskDir,
+                skillDirectory: body.skillDirectory,
+                planId: body.planId,
+                acceptanceCriteria: body.acceptanceCriteria
+            });
+
+            res.json({
+                status: 'ok',
+                message: `任务已拆解: planId=${plan.planId}, 步骤数=${plan.taskDef.steps.length}`,
+                plan
+            });
+        } catch (err) {
+            res.error(500, `任务拆解失败: ${err.message}`);
+        }
+    }
+
+    /**
+     * POST /api/brain/plan-and-execute
+     * 拆解任务并直接提交 Orchestrator 执行
+     *
+     * Body: {
+     *   taskDescription: string,      // 必填
+     *   taskId?: string,
+     *   taskDir?: string,
+     *   skillDirectory?: string,
+     *   acceptanceCriteria?: string   // 可选，验收标准（自然语言）
+     * }
+     */
+    async planAndExecute(req, res) {
+        const body = req.body || {};
+        const { taskDescription } = body;
+
+        if (!taskDescription) {
+            return res.error(400, 'taskDescription 为必填项');
+        }
+
+        if (!this.orchestratorController) {
+            return res.error(503, 'OrchestratorController 未注入，无法执行');
+        }
+
+        try {
+            const brain = this._getBrain();
+            const result = await brain.planAndExecute(
+                taskDescription,
+                this.orchestratorController,
+                {
+                    taskId: body.taskId,
+                    taskDir: body.taskDir,
+                    skillDirectory: body.skillDirectory,
+                    acceptanceCriteria: body.acceptanceCriteria
+                }
+            );
+
+            res.json({
+                status: 'ok',
+                message: `任务已拆解并提交执行: taskId=${result.plan.taskDef.taskId}`,
+                plan: result.plan,
+                loadResult: result.loadResult
+            });
+        } catch (err) {
+            res.error(500, `拆解并执行失败: ${err.message}`);
+        }
+    }
+
+    /**
+     * GET /api/brain/plans
+     * 列出所有拆解计划
+     */
+    async plans(req, res) {
+        try {
+            const brain = this._getBrain();
+            const plans = await brain.listPlans();
+            res.json({
+                status: 'ok',
+                count: plans.length,
+                plans: plans.map(p => ({
+                    planId: p.planId,
+                    taskId: p.taskId,
+                    taskDescription: p.taskDescription,
+                    status: p.status,
+                    createdAt: p.createdAt,
+                    stepCount: p.taskDef?.steps?.length || 0,
+                    valid: p.validation?.valid || false
+                }))
+            });
+        } catch (err) {
+            res.error(500, err.message);
+        }
+    }
+
+    /**
+     * GET /api/brain/plan?planId=xxx 或 GET /api/brain/plan?taskId=xxx
+     * 获取指定拆解计划的详情
+     *
+     * 支持两种查询方式：
+     *   - planId: 按计划 ID 查找（遍历 db/task/ 子目录）
+     *   - taskId: 按任务 ID 查找（直接读取 db/task/{taskId}/brain.json，更快）
+     *   - taskId + loop: 按任务 ID + 轮次查找（读取 brain_loop{N}.json）
+     */
+    async planDetail(req, res) {
+        const { planId, taskId } = req.query;
+        const loopParam = req.query.loop;
+
+        if (!planId && !taskId) {
+            return res.error(400, 'planId 或 taskId 为必填项');
+        }
+
+        try {
+            const brain = this._getBrain();
+
+            // 指定轮次：按 taskId + loopCount 加载
+            if (taskId && loopParam != null && loopParam !== '') {
+                const loopNum = Number(loopParam);
+                const plan = await brain.loadPlan('', { taskId, loopCount: loopNum });
+                if (plan) {
+                    return res.json({ status: 'ok', plan });
+                }
+                return res.error(404, `未找到第 ${loopNum} 轮 Brain 计划: taskId=${taskId}`);
+            }
+
+            // 优先按 taskId 快速加载最新计划
+            if (taskId) {
+                const plans = await brain.listPlans();
+                const plan = plans.find(p => p.taskId === taskId);
+                if (plan) {
+                    return res.json({ status: 'ok', plan });
+                }
+            }
+
+            // 回退到按 planId 加载
+            const plan = await brain.loadPlan(planId || '', taskId ? { taskId } : {});
+
+            if (!plan) {
+                return res.error(404, `未找到计划: ${planId ? 'planId=' + planId : 'taskId=' + taskId}`);
+            }
+
+            res.json({
+                status: 'ok',
+                plan
+            });
+        } catch (err) {
+            res.error(500, err.message);
+        }
+    }
+
+    /**
+     * GET /api/brain/status
+     * 获取 Brain 当前状态
+     */
+    async status(req, res) {
+        const brain = this._getBrain();
+        res.json({
+            status: 'ok',
+            brain: {
+                status: brain.status,
+                skillDirectory: brain.skillDirectory,
+                plansCount: brain.getPlans().length
+            }
+        });
+    }
+}
+
+export default BrainController;