progmune-runtime 3.3.8 → 3.4.0

package/dist/agent-perception.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Phase 12: Agent 感知层 (P2)
+ *
+ * 为 agent loop 提供"看清世界"的能力（设计文档 P2）：
+ *   - GitContext     — 仓库扫描 + git 上下文（分支/最近提交/变更文件/源文件清单）
+ *   - extractIRWithDelta — IR 提取 + 前后函数名差集（IR 增量重提的观测面）
+ *   - RepoWatcher    — 文件变更监听（fs.watch + 防抖）→ 触发 IR 重提回调
+ *
+ * 原则：感知失败不阻塞主循环（best-effort，明确记录 unavailable）。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepoWatcher = void 0;
+exports.collectGitContext = collectGitContext;
+exports.extractIRWithDelta = extractIRWithDelta;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const extract_ir_1 = require("./extract-ir");
+// ── Git Context ──
+function git(projectPath, args) {
+    return (0, child_process_1.execSync)(`git -C "${projectPath}" ${args}`, {
+        encoding: "utf-8",
+        timeout: 10000,
+        stdio: "pipe",
+    });
+}
+/** 收集仓库上下文（分支、最近提交、变更文件）与源文件清单。best-effort。 */
+function collectGitContext(projectPath) {
+    try {
+        const branch = git(projectPath, "rev-parse --abbrev-ref HEAD").trim();
+        const recentCommits = git(projectPath, "log --oneline -5")
+            .split("\n").filter(Boolean);
+        // porcelain 输出首字符可能是空格（未暂存），必须整串不 trim 才能保住 3 字符状态列
+        const changedFiles = git(projectPath, "status --porcelain")
+            .split("\n").filter(Boolean).map((l) => l.slice(3).trim());
+        const sourceFiles = listSourceFiles(projectPath);
+        return { available: true, branch, recentCommits, changedFiles, sourceFiles };
+    }
+    catch (e) {
+        // 非 git 仓库等 → 只给源文件清单
+        try {
+            return {
+                available: false,
+                branch: "",
+                recentCommits: [],
+                changedFiles: [],
+                sourceFiles: listSourceFiles(projectPath),
+                error: e?.message || String(e),
+            };
+        }
+        catch {
+            return { available: false, branch: "", recentCommits: [], changedFiles: [], sourceFiles: [], error: e?.message || String(e) };
+        }
+    }
+}
+/** 浅层扫描项目源文件（不递归进依赖目录）。 */
+function listSourceFiles(projectPath) {
+    const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git", ".progmune_corpus", "__pycache__", "venv", ".venv"]);
+    const EXTS = new Set([".ts", ".js", ".py", ".tsx", ".jsx"]);
+    const out = [];
+    const stack = [projectPath];
+    const seen = new Set();
+    while (stack.length > 0 && out.length < 500) {
+        const dir = stack.pop();
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name) && !e.name.startsWith("."))
+                    stack.push(full);
+            }
+            else if (EXTS.has(path.extname(e.name))) {
+                out.push(path.relative(projectPath, full));
+            }
+        }
+    }
+    return out.sort();
+}
+// ── IR 增量 ──
+/**
+ * 提取 IR 并计算与上次函数名集合的差集。
+ * prevNames 缺省时只返回全量 IR（delta 为空）。
+ */
+function extractIRWithDelta(projectPath, prevNames) {
+    const ir = (0, extract_ir_1.extractIR)(projectPath);
+    const names = ir.map((f) => String(f.name || "")).filter(Boolean);
+    if (!prevNames) {
+        return { ir, delta: { added: [], removed: [], functionCount: names.length } };
+    }
+    const cur = new Set(names);
+    const added = names.filter((n) => !prevNames.has(n));
+    const removed = [...prevNames].filter((n) => !cur.has(n));
+    return { ir, delta: { added, removed, functionCount: names.length } };
+}
+// ── Repo Watcher ──
+const WATCH_EXTS = new Set([".ts", ".js", ".py", ".tsx", ".jsx"]);
+/**
+ * 文件变更监听器：fs.watch 递归监听项目目录，按文件防抖后回调。
+ * 用途：agent 或用户修改文件后触发 IR 增量重提（IR_STALE 消费方）。
+ */
+class RepoWatcher {
+    constructor(projectPath, onChange, debounceMs = 500) {
+        this.projectPath = projectPath;
+        this.onChange = onChange;
+        this.debounceMs = debounceMs;
+        this.watcher = null;
+        this.timers = new Map();
+    }
+    start() {
+        if (this.watcher)
+            return;
+        try {
+            this.watcher = fs.watch(this.projectPath, { recursive: true }, (event, filename) => {
+                if (!filename)
+                    return;
+                const ext = path.extname(String(filename));
+                if (!WATCH_EXTS.has(ext))
+                    return;
+                const rel = path.relative(this.projectPath, path.join(this.projectPath, String(filename)));
+                // 防抖：同一文件的连续事件合并
+                const prev = this.timers.get(rel);
+                if (prev)
+                    clearTimeout(prev);
+                this.timers.set(rel, setTimeout(() => {
+                    this.timers.delete(rel);
+                    try {
+                        this.onChange(rel);
+                    }
+                    catch { /* 回调异常不杀死 watcher */ }
+                }, this.debounceMs));
+            });
+            this.watcher.on("error", () => { });
+        }
+        catch {
+            this.watcher = null; // recursive 不支持时降级为不可用
+        }
+    }
+    stop() {
+        for (const t of this.timers.values())
+            clearTimeout(t);
+        this.timers.clear();
+        if (this.watcher) {
+            try {
+                this.watcher.close();
+            }
+            catch { /* ignore */ }
+            this.watcher = null;
+        }
+    }
+    get active() {
+        return this.watcher !== null;
+    }
+}
+exports.RepoWatcher = RepoWatcher;

package/dist/agent-perception.test.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Phase 12: 感知层测试 (P2)
+ *
+ * collectGitContext / extractIRWithDelta：mock git 与 IR，不触真实仓库。
+ * RepoWatcher：真实临时目录（fs.watch 需要真实文件系统）。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const child_process_1 = require("child_process");
+const extract_ir_1 = require("./extract-ir");
+const agent_perception_1 = require("./agent-perception");
+vitest_1.vi.mock("child_process", () => ({
+    execSync: vitest_1.vi.fn(),
+}));
+vitest_1.vi.mock("./extract-ir", () => ({
+    extractIR: vitest_1.vi.fn(),
+}));
+const mockExecSync = vitest_1.vi.mocked(child_process_1.execSync);
+const mockExtractIR = vitest_1.vi.mocked(extract_ir_1.extractIR);
+(0, vitest_1.beforeEach)(() => {
+    vitest_1.vi.clearAllMocks();
+});
+(0, vitest_1.describe)("agent-perception", () => {
+    (0, vitest_1.it)("collectGitContext 解析分支/提交/变更文件/源文件清单", () => {
+        mockExecSync.mockImplementation((cmd) => {
+            const c = String(cmd);
+            if (c.includes("rev-parse"))
+                return "main";
+            if (c.includes("log --oneline"))
+                return "abc123 feat: login\nbcd456 fix: session";
+            if (c.includes("status --porcelain"))
+                return " M src/auth.ts\n?? src/new.ts";
+            throw new Error("unexpected cmd: " + c);
+        });
+        const ctx = (0, agent_perception_1.collectGitContext)("/tmp/fake-project");
+        (0, vitest_1.expect)(ctx.available).toBe(true);
+        (0, vitest_1.expect)(ctx.branch).toBe("main");
+        (0, vitest_1.expect)(ctx.recentCommits).toHaveLength(2);
+        (0, vitest_1.expect)(ctx.changedFiles).toEqual(["src/auth.ts", "src/new.ts"]);
+        (0, vitest_1.expect)(ctx.sourceFiles.length).toBeGreaterThanOrEqual(0);
+    });
+    (0, vitest_1.it)("collectGitContext 非 git 仓库时降级为 available=false 且不抛", () => {
+        mockExecSync.mockImplementation(() => {
+            throw new Error("fatal: not a git repository");
+        });
+        const ctx = (0, agent_perception_1.collectGitContext)("/tmp/fake-project");
+        (0, vitest_1.expect)(ctx.available).toBe(false);
+        (0, vitest_1.expect)(ctx.error).toContain("not a git repository");
+    });
+    (0, vitest_1.it)("extractIRWithDelta 计算新增/消失函数差集", () => {
+        mockExtractIR.mockReturnValue([
+            { name: "verify_password" },
+            { name: "main" },
+        ]);
+        const prev = new Set(["verify_password", "logout"]);
+        const { delta } = (0, agent_perception_1.extractIRWithDelta)("/tmp/fake-project", prev);
+        (0, vitest_1.expect)(delta.added).toEqual(["main"]);
+        (0, vitest_1.expect)(delta.removed).toEqual(["logout"]);
+        (0, vitest_1.expect)(delta.functionCount).toBe(2);
+    });
+    (0, vitest_1.it)("RepoWatcher 文件变更防抖回调", async () => {
+        const fs = await Promise.resolve().then(() => __importStar(require("fs")));
+        const os = await Promise.resolve().then(() => __importStar(require("os")));
+        const path = await Promise.resolve().then(() => __importStar(require("path")));
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pm-watch-"));
+        const changed = [];
+        const w = new agent_perception_1.RepoWatcher(dir, (f) => changed.push(f), 50);
+        w.start();
+        // 等待 watcher 就绪后写文件
+        await new Promise((r) => setTimeout(r, 100));
+        fs.writeFileSync(path.join(dir, "new.ts"), "export function f() {}");
+        await new Promise((r) => setTimeout(r, 300));
+        w.stop();
+        (0, vitest_1.expect)(changed).toContain("new.ts");
+        (0, vitest_1.expect)(w.active).toBe(false);
+    });
+    (0, vitest_1.it)("RepoWatcher 忽略非源文件扩展名", async () => {
+        const fs = await Promise.resolve().then(() => __importStar(require("fs")));
+        const os = await Promise.resolve().then(() => __importStar(require("os")));
+        const path = await Promise.resolve().then(() => __importStar(require("path")));
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pm-watch2-"));
+        const changed = [];
+        const w = new agent_perception_1.RepoWatcher(dir, (f) => changed.push(f), 50);
+        w.start();
+        await new Promise((r) => setTimeout(r, 100));
+        fs.writeFileSync(path.join(dir, "notes.txt"), "hello");
+        await new Promise((r) => setTimeout(r, 300));
+        w.stop();
+        (0, vitest_1.expect)(changed).toHaveLength(0);
+    });
+});

package/dist/agent-supervision.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Phase 12: Agent 自监督层 (P3)
+ *
+ * 运行项目测试并提取失败信息 —— 失败注入下一次尝试的 prompt（失败→prompt 回路）。
+ * 设计文档 P3：编译/测试失败反馈注入重试。
+ *
+ * 自动探测顺序：
+ *   1. package.json 有 "test" script → npm test --silent
+ *   2. 存在 .py 文件 → python3 -m pytest -q
+ *   3. 都没有 → { ran: false }（调用方跳过该门）
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProjectTests = runProjectTests;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+// ── Helpers ──
+const FAILURE_PATTERN = /(FAIL|✕|×|failed|Error:|error TS|AssertionError|FAILED)/i;
+function extractFailures(output) {
+    return output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && FAILURE_PATTERN.test(l))
+        .slice(0, 10);
+}
+function runCommand(cwd, command, timeoutMs) {
+    try {
+        const output = (0, child_process_1.execSync)(command, {
+            cwd,
+            timeout: timeoutMs,
+            encoding: "utf-8",
+            stdio: "pipe",
+        });
+        return { pass: true, output };
+    }
+    catch (e) {
+        // 非零退出或超时 → 捕获输出
+        const output = `${e.stdout || ""}\n${e.stderr || ""}`;
+        return { pass: false, output, error: e?.message || String(e) };
+    }
+}
+// ── Main ──
+/**
+ * 自动探测并运行项目测试。
+ *
+ * @requires PROJECT_PATH @produces TEST_RESULT
+ */
+function runProjectTests(projectPath, timeoutMs = 60000) {
+    // 1) npm test
+    const pkgPath = path.join(projectPath, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (pkg.scripts?.test) {
+                const command = "npm test --silent";
+                const r = runCommand(projectPath, command, timeoutMs);
+                return {
+                    ran: true,
+                    pass: r.pass,
+                    failures: extractFailures(r.output),
+                    command,
+                    error: r.error,
+                };
+            }
+        }
+        catch { /* package.json 解析失败 → 继续探测 */ }
+    }
+    // 2) pytest
+    const hasPy = listQuickly(projectPath, (e) => e.endsWith(".py"));
+    if (hasPy) {
+        const command = "python3 -m pytest -q";
+        const r = runCommand(projectPath, command, timeoutMs);
+        if (r.error && /no module named pytest/i.test(r.error + r.output)) {
+            return { ran: false, pass: true, failures: [], command, error: "pytest 未安装" };
+        }
+        return {
+            ran: true,
+            pass: r.pass,
+            failures: extractFailures(r.output),
+            command,
+            error: r.error,
+        };
+    }
+    return { ran: false, pass: true, failures: [], command: "(无测试脚本)" };
+}
+/** 浅层探测是否存在匹配文件（不递归依赖目录）。 */
+function listQuickly(projectPath, match) {
+    const SKIP = new Set(["node_modules", "dist", "build", ".git", "__pycache__", "venv", ".venv"]);
+    const stack = [projectPath];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isFile() && match(e.name))
+                return true;
+            if (e.isDirectory() && !SKIP.has(e.name) && !e.name.startsWith("."))
+                stack.push(path.join(dir, e.name));
+        }
+    }
+    return false;
+}

package/dist/agent-supervision.test.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Phase 12: 自监督层测试 (P3)
+ *
+ * runProjectTests 的探测逻辑与失败提取。全部 mock，不跑真实测试。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const child_process_1 = require("child_process");
+const agent_supervision_1 = require("./agent-supervision");
+vitest_1.vi.mock("child_process", () => ({
+    execSync: vitest_1.vi.fn(),
+}));
+const mockExecSync = vitest_1.vi.mocked(child_process_1.execSync);
+(0, vitest_1.beforeEach)(() => {
+    vitest_1.vi.clearAllMocks();
+});
+(0, vitest_1.describe)("agent-supervision", () => {
+    (0, vitest_1.it)("package.json 有 test script → npm test，失败时提取失败行", () => {
+        mockExecSync.mockImplementation(() => {
+            const err = new Error("Command failed");
+            err.stdout = "FAIL src/auth.test.ts\nAssertionError: token 无效\n  12 passing\n  1 failing\n";
+            err.stderr = "";
+            throw err;
+        });
+        // 真实 npm 项目路径下才能探测到 package.json —— 用临时脚本验证探测逻辑
+        const fs = require("fs");
+        const os = require("os");
+        const path = require("path");
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pm-test-"));
+        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ scripts: { test: "vitest run" } }));
+        const r = (0, agent_supervision_1.runProjectTests)(dir, 5000);
+        (0, vitest_1.expect)(r.ran).toBe(true);
+        (0, vitest_1.expect)(r.pass).toBe(false);
+        (0, vitest_1.expect)(r.failures.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(r.failures.join(" ")).toContain("token 无效");
+        (0, vitest_1.expect)(r.command).toBe("npm test --silent");
+    });
+    (0, vitest_1.it)("测试通过时 pass=true 且 failures 为空", () => {
+        mockExecSync.mockReturnValue(" 12 passing (3s)");
+        const fs = require("fs");
+        const os = require("os");
+        const path = require("path");
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pm-test2-"));
+        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ scripts: { test: "vitest run" } }));
+        const r = (0, agent_supervision_1.runProjectTests)(dir, 5000);
+        (0, vitest_1.expect)(r.ran).toBe(true);
+        (0, vitest_1.expect)(r.pass).toBe(true);
+        (0, vitest_1.expect)(r.failures).toHaveLength(0);
+    });
+    (0, vitest_1.it)("无测试脚本且无 python 文件 → ran=false（调用方跳过该门）", () => {
+        const fs = require("fs");
+        const os = require("os");
+        const path = require("path");
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pm-test3-"));
+        const r = (0, agent_supervision_1.runProjectTests)(dir, 5000);
+        (0, vitest_1.expect)(r.ran).toBe(false);
+        (0, vitest_1.expect)(mockExecSync).not.toHaveBeenCalled();
+    });
+});

package/dist/execute.js

@@ -225,6 +225,10 @@ async function execute(intent, projectPath, filePath) {
 /** @requires FILE_PATH @produces COMPILE_RESULT */
 /** @requires FILE_PATH @produces COMPILE_RESULT */
 function verifyCompiles(filePath) {
+    // tsc 报错行以「相对 tsconfig 的文件路径」开头（如 `login_flow.ts(7,13):`），
+    // 而调用方可能传绝对路径——两种形态都要匹配，否则编译门会静默漏报。
+    const base = path.basename(filePath);
+    const isMatch = (l) => l.includes(filePath) || l.startsWith(base + "(") || l.startsWith(base + ":");
     try {
         const { execSync } = require("child_process");
         const result = execSync(`npx tsc --noEmit --project tsconfig.json --pretty false 2>&1`, {
@@ -233,13 +237,13 @@ function verifyCompiles(filePath) {
             stdio: "pipe",
         });
         // tsc exits 0, check if our file is mentioned in output anyway (unlikely but safe)
-        const lines = result.split("\n").filter((l) => l.includes(filePath));
+        const lines = result.split("\n").filter(isMatch);
         return { pass: lines.length === 0, errors: lines };
     }
     catch (e) {
         // tsc exits non-zero — parse stderr/stdout for our file's errors
         const output = (e.stdout || "") + (e.stderr || "");
-        const lines = output.split("\n").filter((l) => l.includes(filePath));
+        const lines = output.split("\n").filter(isMatch);
         return { pass: lines.length === 0, errors: lines };
     }
 }

package/dist/extract-ir.js

@@ -121,8 +121,10 @@ function parseProtocolFromJSDoc(node) {
                 const preMatch = text.match(/pre_states\s*=\s*\[([^\]]*)\]/);
                 const postMatch = text.match(/post_states\s*=\s*\[([^\]]*)\]/);
                 const invMatch = text.match(/invalidate\s*=\s*\[([^\]]*)\]/);
+                // 非规则注解（如文件头文档正文中的 "@protocol" 字样被 ts-morph 解析为 tag）
+                // → 跳过继续找下一个 @protocol tag，而不是直接放弃
                 if (!preMatch || !postMatch)
-                    return undefined;
+                    continue;
                 const namespace = nsMatch ? nsMatch[1] : undefined;
                 const pre_states = preMatch[1].split(',').map((s) => s.trim().replace(/["']/g, '')).filter(Boolean);
                 const post_states = postMatch[1].split(',').map((s) => s.trim().replace(/["']/g, '')).filter(Boolean);