openfeel 1.0.8 → 1.1.0

package/dist/core/flow-manager.js

@@ -9,13 +9,34 @@
  * - advancePhase() 增加 to 参数的 PipelinePhaseSchema 校验
  * - 新增 repair() 方法，自动检测并修复 flow.json 常见问题
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, renameSync, readdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { execSync } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import { PipelineConfigSchema, PipelinePhaseSchema, PIPELINE_PHASES, MetaPhaseSchema, META_PHASES, transitionKeyMatches, } from './pipeline-schema.js';
 import { PublicLogger, formatDate } from './public-logger.js';
 import { t, getCliLang } from './i18n.js';
+import { findStageStatusPath } from './plan/path.js';
+import { atomicWriteFileSync } from './fs/atomic-write.js';
+import { withFileLock, projectLockPath } from './fs/file-lock.js';
+/** flow.json 乐观并发冲突：磁盘 revision 与本次加载时不一致（存在并发写入） */
+export class FlowConcurrentModificationError extends Error {
+    /** 本次实例加载时的 revision */
+    expectedRevision;
+    /** 锁内读到的磁盘当前 revision */
+    actualRevision;
+    constructor(expected, actual) {
+        super(`flow.json 并发冲突：期望 revision=${expected}，磁盘为 ${actual}（已被其它进程修改）`);
+        this.name = 'FlowConcurrentModificationError';
+        this.expectedRevision = expected;
+        this.actualRevision = actual;
+    }
+}
+/** 判断错误是否为 flow.json 并发冲突（供命令层统一识别） */
+export function isFlowConcurrentError(err) {
+    return err instanceof FlowConcurrentModificationError
+        || (typeof err === 'object' && err !== null && err.name === 'FlowConcurrentModificationError');
+}
 // ── 默认值 ──
 /** 创建默认的 Checkpoints */
 function defaultCheckpoints() {
@@ -34,6 +55,7 @@ function defaultFlowData() {
             version: '1.0',
             project: 'OpenFeel',
             updated: new Date().toISOString(),
+            revision: 0,
         },
         pipeline: {
             phase: 'active',
@@ -45,10 +67,17 @@ function defaultFlowData() {
         log: [],
     };
 }
+/** 从 FlowData 提取 revision（缺失/非整数 → 0，兼容存量文件） */
+function extractRevision(data) {
+    const rev = data?.meta?.revision;
+    return typeof rev === 'number' && Number.isInteger(rev) ? rev : 0;
+}
 // ── 核心类 ──
 export class FlowManager {
     projectPath;
     data;
+    /** 本次实例加载（或最近一次成功 save）时的 flow.json revision，用于乐观并发校验 */
+    loadedRevision = 0;
     filePath;
     /** 从 pipeline.yaml 加载的流水线配置（含后备默认值） */
     pipelineConfig = null;
@@ -67,11 +96,14 @@ export class FlowManager {
     load() {
         if (!existsSync(this.filePath)) {
             this.data = null;
+            this.loadedRevision = 0;
             return;
         }
         try {
             const raw = readFileSync(this.filePath, 'utf-8');
             this.data = JSON.parse(raw);
+            // 记录加载基线 revision（缺失/非法视为 0，兼容存量文件）
+            this.loadedRevision = extractRevision(this.data);
             // 从 stages 的键名恢复 op 的 id 字段（运行时便利字段，磁盘不存储）
             if (this.data && this.data.stages) {
                 for (const [, stage] of Object.entries(this.data.stages)) {
@@ -86,9 +118,10 @@ export class FlowManager {
         }
         catch {
             this.data = null;
+            this.loadedRevision = 0;
         }
     }
-    /** 保存 flow.json（自动更新 meta.updated，序列化时去除 op 中的 id 字段以与键名保持一致） */
+    /** 保存 flow.json（自动更新 meta.updated；锁内做乐观并发校验、备份旧版本并原子写） */
     save() {
         if (!this.data) {
             return;
@@ -101,46 +134,42 @@ export class FlowManager {
                 delete op.id;
             }
         }
-        const content = JSON.stringify(serializable, null, 2) + '\n';
-        const tmpPath = this.filePath + '.tmp';
-        const bakPath = this.filePath + '.bak';
-        // 备份旧文件（写入前）
-        if (existsSync(this.filePath)) {
-            try {
-                copyFileSync(this.filePath, bakPath);
-            }
-            catch {
-                // 备份失败不阻塞写入
-            }
-        }
+        const lockPath = projectLockPath(this.projectPath, 'flow');
         try {
-            // 写入临时文件
-            writeFileSync(tmpPath, content, 'utf-8');
-            // 校验临时文件 JSON 合法性
-            try {
-                const tmpContent = readFileSync(tmpPath, 'utf-8');
-                JSON.parse(tmpContent);
-            }
-            catch (parseErr) {
-                // 清理失败的临时文件
-                try {
-                    writeFileSync(tmpPath, '', 'utf-8');
+            withFileLock(lockPath, () => {
+                // 乐观并发校验：锁内读磁盘 revision，与加载时比对；不一致说明有并发写，拒绝覆盖
+                const diskRevision = this.readDiskRevision();
+                if (diskRevision !== this.loadedRevision) {
+                    throw new FlowConcurrentModificationError(this.loadedRevision, diskRevision);
                 }
-                catch {
-                    // 清理失败也不阻塞
-                }
-                throw new Error(`flow.json 写入校验失败: ${parseErr.message}。备份已保留在 ${bakPath}`);
-            }
-            // 校验通过，rename 临时文件到正式文件
-            renameSync(tmpPath, this.filePath);
-            // 同步备份
-            writeFileSync(this.filePath + '.bak', content, 'utf-8');
+                const nextRevision = this.loadedRevision + 1;
+                serializable.meta.revision = nextRevision;
+                // S5：写前复制旧文件为 .bak；写成功后不覆盖 .bak，使其始终保留上一版本
+                const content = JSON.stringify(serializable, null, 2) + '\n';
+                atomicWriteFileSync(this.filePath, content, { backup: true });
+                // 同步内存与加载基线，避免同实例连续 save 误判冲突
+                this.data.meta.revision = nextRevision;
+                this.loadedRevision = nextRevision;
+            });
         }
         catch (err) {
             console.error(`[ERROR] flow.json 保存失败: ${err instanceof Error ? err.message : err}`);
             throw err;
         }
     }
+    /** 读取磁盘当前 revision（不存在/损坏/缺失 → 0，兼容存量文件） */
+    readDiskRevision() {
+        try {
+            const raw = readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const rev = parsed?.meta?.revision;
+            return typeof rev === 'number' && Number.isInteger(rev) ? rev : 0;
+        }
+        catch {
+            // 文件不存在或损坏：视为 0（首次写入 / 由 repair 兜底）
+            return 0;
+        }
+    }
     /** 数据是否已加载 */
     isLoaded() {
         return this.data !== null;
@@ -175,7 +204,8 @@ export class FlowManager {
             const timestamp = this.formatCheckpointTimestamp(new Date());
             const filename = `${stageId}-${timestamp}-${phase}.json`;
             const filePath = resolve(dir, filename);
-            writeFileSync(filePath, JSON.stringify(serializable, null, 2) + '\n', 'utf-8');
+            // REV-003：快照唯一文件名 + best-effort，原子写防半写；不接全局锁（避免长序列化纳入临界区）
+            atomicWriteFileSync(filePath, JSON.stringify(serializable, null, 2) + '\n');
             // 清理超限的最旧快照
             this.cleanupCheckpoints(stageId);
         }
@@ -222,16 +252,26 @@ export class FlowManager {
             const content = readFileSync(filePath, 'utf-8');
             // 校验快照 JSON 合法性，非法内容拒绝恢复
             JSON.parse(content);
-            // 备份当前 flow.json（失败不阻塞恢复）
-            if (existsSync(this.filePath)) {
-                try {
-                    copyFileSync(this.filePath, this.filePath + '.bak');
-                }
-                catch {
-                    // 备份失败忽略
+            const lockPath = projectLockPath(this.projectPath, 'flow');
+            let conflict = false;
+            withFileLock(lockPath, () => {
+                // 乐观并发校验：磁盘被并发修改时拒绝恢复，防止覆盖他人写入
+                const diskRevision = this.readDiskRevision();
+                if (diskRevision !== this.loadedRevision) {
+                    conflict = true;
+                    return;
                 }
+                // 快照 revision 重定基为 diskRevision+1，保证单调递增
+                const restored = JSON.parse(content);
+                restored.meta.revision = diskRevision + 1;
+                const restoredContent = JSON.stringify(restored, null, 2) + '\n';
+                // REV-002：与 save() 同锁、同 S5 语义（写前复制旧文件为 .bak，写后不覆盖）
+                atomicWriteFileSync(this.filePath, restoredContent, { backup: true });
+            });
+            if (conflict) {
+                console.warn('[WARN] flow.json 已被其它进程修改，拒绝从快照恢复（请重新加载后重试）');
+                return false;
             }
-            writeFileSync(this.filePath, content, 'utf-8');
             this.load();
             return true;
         }
@@ -1104,17 +1144,9 @@ export class FlowManager {
         }
         return { configDefaults, statusOverrides, effective };
     }
-    /** 查找 status.md 的路径（先查 stages 目录，再回退 plan 目录） */
+    /** 查找 status.md 的路径（三级回退：plan/{series}/ 精确 → plan 递归 → stages 兜底） */
     findStatusPath(stageId) {
-        const stagesDir = resolve(this.projectPath, '.openfeel', 'stages', stageId, 'status.md');
-        if (existsSync(stagesDir)) {
-            return stagesDir;
-        }
-        const planDir = resolve(this.projectPath, '.openfeel', 'plan', stageId, 'status.md');
-        if (existsSync(planDir)) {
-            return planDir;
-        }
-        return null;
+        return findStageStatusPath(this.projectPath, stageId);
     }
     /** 从 status.md 的状态记录表提取最近 N 条变更 */
     extractRecentChanges(maxChanges) {
@@ -1183,22 +1215,22 @@ export class FlowManager {
         }
         return result;
     }
-    /** 将 PipelinePhase 映射为负责 Agent 标识 */
+    /** 将 PipelinePhase 映射为负责 Agent 标识（返回新名，供新写入使用） */
     mapPhaseToAgent(phase) {
         const prefix = phase.split('_')[0];
         switch (prefix) {
             case 'plan':
-                return 'planner';
+                return 'openfeel-planner';
             case 'scheme':
-                return 'schemer';
+                return 'openfeel-schemer';
             case 'exec':
-                return 'executor';
+                return 'openfeel-executor';
             case 'review':
-                return 'reviewer';
+                return 'openfeel-reviewer';
             case 'test':
-                return 'feel-tester';
+                return 'openfeel-feel-tester';
             case 'archiving':
-                return 'archiver';
+                return 'openfeel-archiver';
             case 'done':
                 return 'none';
             default:
@@ -1228,7 +1260,7 @@ export class FlowManager {
             this.data.pipeline.retry = 0;
             this.appendLog({
                 time: '',
-                agent: 'executor',
+                agent: 'openfeel-executor',
                 action: 'attempt_pass',
                 detail: { opId, attempts: op.attempts },
             });
@@ -1246,7 +1278,7 @@ export class FlowManager {
             this.data.pipeline.retry += 1;
             this.appendLog({
                 time: '',
-                agent: 'executor',
+                agent: 'openfeel-executor',
                 action: 'attempt_fail_retry',
                 detail: { opId, attempts: op.attempts, maxAttempts: op.max_attempts },
             });
@@ -1263,7 +1295,7 @@ export class FlowManager {
         this.data.pipeline.retry += 1;
         this.appendLog({
             time: '',
-            agent: 'executor',
+            agent: 'openfeel-executor',
             action: 'attempt_fail_exhausted',
             detail: { opId, attempts: op.attempts, maxAttempts: op.max_attempts },
         });
@@ -1308,7 +1340,7 @@ export class FlowManager {
     }
     /**
      * 添加自动修复审查条目
-     * 当 Reviewer 认为问题可直接修复时调用，REV 条目状态直接设为 resolved，
+     * 当 openfeel-reviewer 认为问题可直接修复时调用，REV 条目状态直接设为 resolved，
      * pipeline.phase 跳过 review_failed→scheme_pending，直接推进到 exec_running。
      * @param item 审查条目（canAutoFix 自动设为 true）
      * @param opId 关联的操作 ID
@@ -1667,6 +1699,12 @@ export class FlowManager {
                 changes.push('已补全缺失的 meta.updated');
                 modified = true;
             }
+            // （乐观并发修订）补全缺失的 meta.revision（存量兼容，视为 0）
+            if (typeof flowData.meta.revision !== 'number') {
+                flowData.meta.revision = 0;
+                changes.push('已补全缺失的 meta.revision（存量兼容，视为 0）');
+                modified = true;
+            }
         }
         // 修复缺失的 pipeline 字段
         if (!flowData.pipeline) {
@@ -1761,17 +1799,11 @@ export class FlowManager {
         }
         // 写入修复后的数据（recovered 场景下磁盘文件仍损坏，即使无字段修改也必须写回恢复内容）
         if ((modified || recovered) && !dryRun) {
-            // 备份当前文件（recovered 场景下 .bak 已是有效恢复来源，避免被损坏文件覆盖）
-            if (!recovered) {
-                try {
-                    copyFileSync(this.filePath, this.filePath + '.bak');
-                }
-                catch {
-                    // 备份失败不阻塞
-                }
-            }
-            // 使用安全写入
-            const tmpPath = this.filePath + '.tmp';
+            // （乐观并发修订）恢复/修复亦视为一次写入：先在源对象上递增 revision，
+            // 再序列化深拷贝，确保 revision 随内容一起落盘（避免陈旧实例后续 save 误判冲突）
+            const meta = flowData.meta ?? defaults.meta;
+            flowData.meta = meta;
+            meta.revision = (typeof meta.revision === 'number' ? meta.revision : 0) + 1;
             const serializable = JSON.parse(JSON.stringify(flowData));
             // 去除 op 中的 id 字段
             if (serializable.stages && typeof serializable.stages === 'object') {
@@ -1786,23 +1818,19 @@ export class FlowManager {
                 }
             }
             const content = JSON.stringify(serializable, null, 2) + '\n';
-            writeFileSync(tmpPath, content, 'utf-8');
-            // 校验临时文件
+            const lockPath = projectLockPath(this.projectPath, 'flow');
             try {
-                const tmpContent = readFileSync(tmpPath, 'utf-8');
-                JSON.parse(tmpContent);
+                withFileLock(lockPath, () => {
+                    // recovered 场景 .bak 已是有效恢复来源，避免被损坏文件覆盖（保持既有语义）
+                    atomicWriteFileSync(this.filePath, content, { backup: !recovered });
+                });
             }
-            catch (parseErr) {
-                try {
-                    writeFileSync(tmpPath, '', 'utf-8');
-                }
-                catch {
-                    // 清理失败不阻塞
-                }
-                changes.push(`修复后写入校验失败: ${parseErr.message}`);
+            catch (err) {
+                changes.push(`修复后写入失败: ${err.message}`);
                 return { fixed: false, changes, recovered };
             }
-            renameSync(tmpPath, this.filePath);
+            // 写盘成功后重新加载，同步 this.data 与 this.loadedRevision 基线
+            this.load();
         }
         // changes 在无问题时保持空数组，CLI 层通过 changes.length === 0 判断"没问题"
         return { fixed: modified || recovered, changes, recovered };
@@ -2046,25 +2074,18 @@ export class FlowManager {
             }
         }
     }
-    /** 2. 检查 flow.json 与 plan/{stage}/status.md 跨文件一致性 */
+    /** 2. 检查 flow.json 与 plan/{series}/stage-NN/status.md 跨文件一致性 */
     checkCrossFileConsistency(items) {
         if (!this.data) {
             return;
         }
-        const planDir = resolve(this.projectPath, '.openfeel', 'plan');
-        // 同时检查 .openfeel/stages/ 目录（代码实际使用路径）
-        const stagesDir = resolve(this.projectPath, '.openfeel', 'stages');
         let total = 0;
         let consistent = 0;
         for (const [stageId, stage] of Object.entries(this.data.stages)) {
-            // 尝试 .openfeel/stages/{stageId}/status.md（代码实际路径）
-            let statusPath = resolve(stagesDir, stageId, 'status.md');
-            if (!existsSync(statusPath)) {
-                // 回退到 .openfeel/plan/{stageId}/status.md（文档声明路径）
-                statusPath = resolve(planDir, stageId, 'status.md');
-                if (!existsSync(statusPath)) {
-                    continue;
-                }
+            // 三级回退查找 status.md（plan/{series}/ 精确 → plan 递归 → stages 兜底）
+            const statusPath = findStageStatusPath(this.projectPath, stageId);
+            if (!statusPath) {
+                continue;
             }
             total++;
             try {
@@ -2100,8 +2121,6 @@ export class FlowManager {
             return;
         }
         // 僵尸阶段检测：各 stage 在 status.md 中声明的状态与 stage.status 不一致
-        const planDir = resolve(this.projectPath, '.openfeel', 'plan');
-        const stagesDir = resolve(this.projectPath, '.openfeel', 'stages');
         for (const [stageId, stage] of Object.entries(this.data.stages)) {
             // 所有 REV 已 closed 但 stage 仍为 review_failed
             if (stage.status === 'review_failed') {
@@ -2284,7 +2303,8 @@ export class FlowManager {
             return; // 已存在则不覆盖
         }
         const data = defaultFlowData();
-        writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+        // 首次创建（existsSync 守卫）、无并发读者，故不加锁，仅原子写；默认 revision:0
+        atomicWriteFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
     }
     /**
      * 内嵌数据（仅供测试使用）
@@ -2292,6 +2312,8 @@ export class FlowManager {
      */
     setData(data) {
         this.data = data;
+        // 测试专用：注入数据视为「当前磁盘状态」，同步并发校验基线，避免后续 save 误判冲突
+        this.loadedRevision = this.readDiskRevision();
     }
     // ═══ 流水线配置加载 ═══
     /**
@@ -2364,6 +2386,33 @@ export class FlowManager {
     }
 }
 // ── 辅助函数 ──
+/** 旧 agent 名 → 新名映射（读取兼容用；skill 名不在此列） */
+const LEGACY_AGENT_NAME_MAP = {
+    planner: 'openfeel-planner',
+    schemer: 'openfeel-schemer',
+    executor: 'openfeel-executor',
+    reviewer: 'openfeel-reviewer',
+    'feel-tester': 'openfeel-feel-tester',
+    utility: 'openfeel-utility',
+    vision: 'openfeel-vision',
+    archiver: 'openfeel-archiver',
+};
+/**
+ * 归一化 agent 名：旧名 → 新名（读取兼容 P5）。
+ * 内部 toLowerCase() 归一大小写不一致（REV-304）。
+ * 幂等：已是 openfeel-* 原样返回；feel / none / unknown / 非 agent 值（如 flow-manager）原样保留。
+ */
+export function normalizeAgentName(name) {
+    if (!name) {
+        return name;
+    }
+    const key = name.trim().toLowerCase();
+    // 已是新名（openfeel- 前缀）→ 原样返回，避免二次前缀化
+    if (key.startsWith('openfeel-')) {
+        return key;
+    }
+    return LEGACY_AGENT_NAME_MAP[key] ?? key;
+}
 /**
  * 将 PipelinePhase 映射为 stage 状态
  * @param phase 流水线阶段